This page documents every leancil command: its arguments, options, output files and failure
modes. For one complete verification, read the getting-started guide first.
| Command | Purpose | Reference |
|---|---|---|
leancil list assembly.dll |
Print the method signatures of an assembly | Discover and select methods |
leancil extract |
Validate a method and its reachable calls and translate them to Lean | Extract |
leancil blockers |
Report everything that stops extract for a list of methods |
Report extraction blockers |
leancil check |
Compare extraction artifacts with their assembly and settings | Check |
leancil new-proof |
Write a starting proof with marked holes | Start a proof |
leancil verify |
Check, kernel-replay and audit one theorem | Verify |
leancil verify-batch |
Verify many requests in one session | Batch verification |
leancil gates |
Build, extract and verify a catalog of methods, profiles, proofs and regression variants, or plan it over jobs | Run a proof catalog |
leancil bindings |
Write or check the proof sources a binding catalog generates | Binding catalogs |
leancil workspace |
Generate a method's extraction into a Lake package for editor goals | Editor workspace |
leancil watch |
Rebuild, re-extract and verify on change | Watch |
leancil export-contracts |
Publish verified contracts as a sidecar | Export contracts |
leancil resolve-imports |
Locate contract sidecars and implementations from SDK output | Resolving imports |
leancil audit-library |
Kernel-replay and axiom-audit the theorems of a Lean library | Library audits |
leancil templates |
Generate shared proof templates from extractions of several profiles, or check generated ones | Generated profile templates |
leancil lint-exceptions |
Compare modeled throw sites with XML documentation | Exception documentation lint experiment |
leancil --version |
Print the tool, framework and toolchain versions | Version |
leancil --help, leancil -h and leancil with no arguments print the usage of every command. A
failing command exits with 1 and prints on standard error a summary line starting Invalid: or
Error:, a Stage: line naming the failed step and a Next: line with the fix to try. check,
verify and audit-library start the summary with Invalid:, as does each failed request of
verify-batch and gates. Every other failure starts it with Error:. An unknown option is
an error, as is repeating an option that takes one value.
dotnet build Extractor -c Release produces Extractor/bin/leancil.exe on Windows (leancil on
other platforms). The managed assembly and package are named Nethermind.LeanCIL. To install the
tool globally, see getting started.
leancil --version prints the tool version (the installed package version, such as
0.1.0-dev.<stamp> for a development pack), the LeanCIL commit and Lean toolchain of its
framework, and the [[require]] block that pins the matching framework in a consumer
package. A tool built outside a git checkout reports the
revision as unknown.
leancil list assembly.dll prints the canonical signature of every method, including overloads
and non-public methods, for copying into extract. It reads metadata without executing the
assembly. A listed method is not necessarily supported: extract validates its signature, CIL and
reachable dependencies.
Method selectors accept C# type aliases, an optional return type, and an unqualified declaring type when the result is unique. The four selectors below select the same method:
System.UInt64 Examples.Arithmetic::Add(System.UInt64,System.UInt64)
ulong Examples.Arithmetic::Add(ulong,ulong)
Examples.Arithmetic::Add(ulong,ulong)
Arithmetic::Add(ulong,ulong)
- The parameter list is required. Matching is case-sensitive, and an explicit return type must match.
- Use
ulong&for a by-reference parameter. - An
inparameter of a virtual, abstract or interface member, including an explicit interface implementation, is spelledulong& modreq(System.Runtime.InteropServices.InAttribute), aslistprints it. The modifier is part of the selector and the recorded signature, so it never matches the unmodifiedulong&overload. - An ambiguous selector fails with the full candidate signatures, ready to copy into the command.
- Artifacts record the resolved canonical signature, so equivalent selectors check the same artifact. Selection never relaxes supported-type or instruction validation.
extract infers the assembly identity from the DLL's metadata. Add --assembly Examples to
require a short name, or a full identity to constrain version, culture and public key token as
well; a mismatch is rejected. Artifacts record the full identity and assembly hash with or
without --assembly.
leancil extract assembly.dll '[return-type ]Type::Method(parameter-types)' output-directory
[profile|@profile.json] [--assembly name-or-identity] [--type-argument Type]...
[--assume-initialized Namespace.Type]... [--reference Lib.dll]...
[--import Lib.leancil.contracts]... [--import-implementation Lib=path]...
[--import-sha256 Lib=hex]... [--import-interface-sha256 Lib=hex]...
| Option | Meaning |
|---|---|
profile or @profile.json |
Execution profile, the fourth positional argument. The default is scalar; see runtime profiles. |
--assembly |
Required assembly short name or full identity; see above. |
--type-argument |
A closed type argument of a generic entry, repeated in order; see referenced assemblies and typed imports. |
--assume-initialized |
A type the caller guarantees completed initialization successfully before invocation; see initialization assumptions. |
--reference |
A referenced assembly whose bodies are extracted too; see referenced assemblies. |
--import and --import-* |
Contract imports; see contract interfaces. |
Build the example assembly and extract a method from it:
dotnet build Examples/Assembly -c Release
leancil extract Examples/Assembly/bin/Examples.dll "Arithmetic::Add(ulong,ulong)" artifacts/AddFrom the repository root, extract prints:
Extracted 1 reachable method into artifacts/Add/Extracted.lean
The output directory holds:
| File | Content |
|---|---|
Extracted.lean |
The program: here arg 0, arg 1, add, ret, with the exact method signature, metadata, profile and kernel-checked fetch equations. The entry is method zero; reachable managed callees follow in dependency order. |
identity.json |
The manifest: assembly path, identity and SHA-256, entry, profile, assumptions, references, imports and extractor hash. |
Symbols.lean |
PDB names and source locations, written only when the assembly has a matching portable PDB. |
Extracted.lean also holds raw metadata and an Extracted.translation_valid certificate.
Verification requires this certificate to have the exact validator type for the complete emitted
program and kernel-replays it separately from the user proof.
Extraction evidence lists what
its validators recompute; raw metadata serialization and transformations outside those checks are
trusted. The per-site validators walk the raw code, reachability mask and emitted code in
lockstep, so a long branch excluded by the profile adds linear checking cost.
check and verify read the profile from the manifest. Capability prerequisites of a profile
are validated. Instructions unreachable under the fixed profile are emitted as explicit
unsupported placeholders, so artifacts of one profile are invalid for another.
Methods on types with static constructors are rejected by default; the diagnostic names the type and the flag to pass. If the caller guarantees successful initialization before invocation, record that precondition:
leancil extract assembly.dll 'Type::Method(ulong)' artifacts/Method --assume-initialized Namespace.TypeRepeat --assume-initialized for each required type, using its exact metadata name. An assumption
applies only to the named type in this assembly and does not propagate to helper types. It does
not execute or prove initialization, or admit calls to static constructors.
An assumption enables ldsfld of the type's static readonly struct fields whose value its static
constructor fixes (see static readonly values). Each such
field is recorded in staticValues and reported as a caller assumption that it keeps the value
its static constructor stored. A field whose value extraction cannot compute is also listed in
opaqueStaticValues and reported as Unknown static value; its loads read the caller's static
binding.
The generated Lean source and identity manifest retain the assumptions; check reuses them and
rejects conflicting explicit assumptions. Verification binds the manifest hash, prints the
initialization preconditions with the theorem and copies both lists into verified.json.
By default a call into another assembly needs a contract import.
To extract the callee's body instead, pin its DLL with --reference, repeated per assembly:
leancil extract App.dll 'App.Application::Direct(ulong)' artifacts/Direct --reference Lib.dllReferenced assemblies are trusted inputs like the selected one
(soundness). Each is recorded in
identity.json by relative path, full identity, MVID and SHA-256. Extracted.lean names it by
identity only, as an Extraction.AssemblyPin attributed to every body it supplies. check
replays the recorded references and rejects a changed hash or identity. Assemblies resolve only
against this pinned set and the runtime's platform assemblies, so an unpinned reference, a name
pinned under another version, a duplicate identity or a framework DLL passed as a reference fails.
One assembly cannot be both a typed import and a reference.
A referenced assembly's static methods are admitted as direct call and ldftn targets, and its
structs and interfaces as layouts and constrained dispatch,
including static flag getters that fold a branch. A struct of the selected assembly may implement
a referenced interface or rely on its interface-level bodies, and a closed generic struct of
either assembly may receive a static slot. Its generic methods, the static methods of its generic
classes and the methods of its closed generic structs are specialized from its own metadata, so
their bodies stay attributed to its pin. A closed generic struct such as Lib.Pair<ulong> is laid
out from the assembly that defines it, and its type arguments may be value types of the selected
assembly or of any pinned reference, in either direction. Reference-type arguments, reference
fields and layout cycles are rejected, as are static field loads, calli and types with static
constructors in a referenced assembly. A closed entry type argument may name one of its structs as
Namespace.Type, Assembly, by simple or full assembly name:
leancil extract App.dll 'App.Application::Size(ulong)' artifacts/Size --reference Lib.dll \
--type-argument 'Lib.Cell, Lib'A static method of a generic class can be the entry. --type-argument lists the method's own
type arguments first, then the declaring type's, outer type parameters before inner ones as
ECMA-335 numbers them; the selector names the open definition:
leancil extract App.dll 'App.Algo`1::Run(ulong)' artifacts/Run --type-argument App.GasInstance methods of generic classes are rejected as entries and as callees.
leancil blockers runs admission, the validation extract performs, over an explicit list of
method and profile pairs, and reports everything that blocks each one instead of stopping at the
first failure. It checks no proofs and keeps no extraction artifacts:
leancil blockers assembly.dll --manifest blockers-manifest.json [--output blockers.json] \
[--assembly name-or-identity] [--reference Lib.dll]... [--import Lib.leancil.contracts]... \
[--import-implementation Lib=path]... [--import-sha256 Lib=hex]... \
[--import-interface-sha256 Lib=hex]...The manifest lists the entries and the settings shared by all of them:
{
"initializedTypes": ["Namespace.Type"],
"references": ["Lib.dll"],
"imports": ["Other.leancil.contracts"],
"importSha256": { "Other": "implementation sha256" },
"importInterfaceSha256": { "Other": "interface digest" },
"entries": [
{ "signature": "Type::Method(ulong)", "profile": "scalar" },
{ "signature": "Type::Method(ulong)", "profile": "@profiles/x64-v3.json" },
{ "signature": "Type::Size()", "profile": "scalar", "typeArguments": ["Namespace.Pair"] }
]
}| Manifest key | Meaning |
|---|---|
entries[].signature |
A method selector, as for extract. |
entries[].profile |
A profile name or @file, resolved against the manifest's directory. |
entries[].typeArguments |
An optional key that applies --type-argument to that entry. |
initializedTypes |
Applies --assume-initialized to every entry. |
references |
Pins referenced assemblies for every entry, as --reference does; paths are relative to the manifest. |
imports, importImplementations, importSha256, importInterfaceSha256 |
Contract imports for every entry, as the --import, --import-implementation, --import-sha256 and --import-interface-sha256 options of extract; paths are relative to the manifest. |
A sidecar beside the assembly is discovered as extract discovers it. --assembly has its
extract meaning. Any other manifest key is rejected.
The report goes to --output, by default blockers.json next to the manifest, and a short
summary goes to standard output. The command exits with 0 whenever the report is written,
whatever the entries' status. Each entry has one status:
| Status | Meaning |
|---|---|
admitted |
extract succeeds: an entry with no blockers is extracted into a scratch directory to confirm it. |
blocked |
At least one blocker is listed. An entry the selector resolves but extract rejects by its shape, such as an init setter or a member of an open generic type, is blocked, and its definition is analysed as an entry. |
notChecked |
Nothing was analysed, for the reason given: a selector that matches no method or several, a malformed type argument, an unknown profile, or an assembly, import or assumption that fails before any method is checked. |
Each blocker is one unsupported construct (instruction, call, type, layout, method metadata or static constructor). It lists every site, with method, IL offset, instruction and the PDB source location when one is present, and every affected entry with the call chains from it to those sites.
- A condition found by two checks, such as an entry's modifier and the type that carries it, is reported once, by the more specific check.
- A rejected signature, receiver, static constructor or entry shape does not stop the analysis: the body and callees behind it are checked and their blockers reported. Only a method without IL to analyse, or a body whose control flow cannot be analysed, ends its branch, and that blocker's message names what was not analysed behind it.
- Only code reachable under the entry's profile is checked, so a branch excluded by a constant
IsSupportedis never reported. - An admitted entry is only extractable; verifying it needs a proof.
Check that the generated files still match the assembly and extraction settings:
leancil check artifacts/Addcheck prints:
Valid: extraction artifacts match the assembly and recorded settings.
Assembly: Examples, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
DLL: Examples/Assembly/bin/Examples.dll
Entry: System.UInt64 Examples.Arithmetic::Add(System.UInt64,System.UInt64)
Profile: scalar (scalar, 64-bit, little-endian)
Reachable methods: 1
CIL: artifacts/Add/Extracted.lean
Manifest: artifacts/Add/identity.json
Matched: assembly identity and SHA-256, extractor SHA-256, configuration, metadata and regenerated CIL.
Symbols: matched the PDB
Paths under the current directory are displayed relative to it; paths outside it remain absolute.
check reads the assembly path, method and profile from the manifest, regenerates the extraction
in memory, and compares it with the saved files without overwriting them. It runs no Lean.
| Option | Meaning |
|---|---|
--assembly-path path/to/Examples.dll |
Use a DLL that moved. Assembly paths are stored relative to the artifact directory; the DLL's identity and content must match the manifest. |
--assembly name-or-identity |
Require that assembly name or identity, as for extract. |
--import-implementation, --import-sha256, --import-interface-sha256 |
Override a recorded import's path or pin; see contract interfaces. |
check replays the recorded --reference assemblies and rejects that option. A changed assembly
or extractor, or a saved file that differs from the regenerated one, fails at the
extraction integrity stage; run leancil extract again. A manifest whose schema is not 3 is
rejected the same way.
Write a starting proof of an extraction's entry method:
leancil extract Examples/Assembly/bin/Examples.dll "Loops::Countdown(uint)" artifacts/Countdown
leancil new-proof artifacts/Countdown Proofs/Countdown.leannew-proof prints on standard output:
Wrote Proofs/Countdown.lean: a starting proof of System.UInt32 Examples.Loops::Countdown(System.UInt32)
Holes: 8 obligations, 0 paths not outlined (each `sorry`; verify rejects the file until none remain)
Next: leancil verify artifacts/Countdown --proof Proofs/Countdown.lean --goals prints the goal at each hole; fill them, then verify without --goals
new-proof reads only the extraction directory and first runs the comparison of leancil check,
so a stale or edited extraction is refused at the extraction integrity stage. It never replaces
a file: when the proof path exists, it exits with 1 and writes nothing. The same extraction
always gives the same file, byte for byte. The file imports the extraction's keyed module,
Extracted.KEY (see Editor workspace), so it opens in the editor once
leancil workspace selects the method, and verify accepts that import for this extraction only.
The file states ExampleProof.correctness as a CIL.Safety.Ensures theorem over the method's
parameters, named as in the PDB, and checks it with #print axioms correctness. A bool
parameter is a Bool, a narrow integer a BitVec of its width, and a bool result the Bool
its returned word encodes. Every place the author must decide something is a sorry, each with a
one-line comment saying which obligation it is. Wherever the outline splits a proof on a test,
each side that returns steps to its own return and leaves its own postcondition, commented with
the side or values it is for. In the Holds theorem of a callee that tests its arguments, each
returning side is stepped and leaves what post states of the result, and each throwing side is
closed from pre by cil_loop_obligation. The outline handles these shapes:
PreconditionandPostconditionare definitions to replace with the specification. The theorem assumes the precondition and promises the postcondition of the returned value. For a method that takes references, spans or arrays, or that calls a helper from a frame of integer locals, the postcondition also covers the caller's memory before and after. Each definition the author fills (Precondition,Postcondition,invariant,measure, afootprinthole and a helper's contract stub outside a loop) is underset_option linter.unusedVariables false in, since a specification rarely names every binder the theorem fixes. The header names each C# parameter bound under another name, such asvaluesasvalues1.- A method without a loop is stepped by
cil_checked_stepswhen its body is arithmetic on 32- and 64-bit arguments or a total bit count (Log2,PopCount,LeadingZeroCount,TrailingZeroCount), leaving only the postcondition. A signed or unsigned checked+,-or*is split withby_cases fitsNon whether its integer result fits. The fitting side steps withcheckedValues_add_unsigned_i32,checkedValues_add_signed_i32or their siblings; the overflowing side throws and is closed from the precondition bycil_loop_obligation. A conditional branch on words the body computes from its arguments, signed or unsigned, is split withby_cases branchNon its condition; a body splits into at most eight returns. A literal in a split's condition is in the form defaultsimpleaves it, such ascount = 0#32or, in a signed comparison,value.toInt < (-1), so the split's fact rewrites a simplified goal without restating it. A body that also takes up to threeboolarguments and tests nothing else is split withcaseson each. - An
int[],uint[],long[]orulong[]parameter, alone or beside a class instance, is anArrayViewwith a list of its elements. The theorem assumes the view validates, has its element type and holds those elements in its storage span,SpanContents initial values.storage. A method returningvalues[index]for anintargumentindex, read byldelemor through a static helper whose body only returnsref values[index], is split withby_cases valuesBoundon whether the index is below the number of elements; a null array has none, so the bound alone excludes it. The in-bound side steps throughSpanContents.array_load, and the helper's call through a contract proved from its body, leaving the postcondition. An index outside throws, a hole the precondition closes. Straight-line bodies over objects can also store the array in a field and read an element (see the word-array item below); unsupported combinations leave anot outlined:hole. - A loop over an array indexes it with an
intlocal tested againstvalues.Length, which throws on a null array.Preconditionis therefore generated asvalues.reference ≠ .null ∧ sorryunder a comment saying why, leaving thesorryfor what else callers guarantee. The proof destructures the array intovaluesBaseandvaluesLengthbefore the loop and closes the null case fromPrecondition; with the conjunct removed that case fails withPrecondition must exclude null. The cutpoint takesvaluesLength, which a valid array keeps below2 ^ 31(SpanView.length_boundedof its storage span). A read ofvalues[index]steps througharray_loadof the storage span's contents and loadsvaluesElements[index.toNat]. For an array the loop stores into, the theorem gives authority over its storage span,footprintis that span's, and a store ofvalues[index]steps througharrayElement_of_access. Each access leaves its index bound, and a store its write authority and footprint entry, tocil_loop_obligationfrom the author's definitions. A method storing into one of several arrays is refused. - A method with a loop gets its loop state, a cutpoint derived from its control flow, and
invariantandmeasuredefinitions to replace. A method that takes a reference also gets afootprintto replace: the caller memory the loop may write, which the loop state carries. The proof appliesinvoke_loop_satisfies, steps the entry to the first loop head, splits the iteration where the body branches, and leaves the obligations the loop tactics tag:invariantandmeasurewhere an iteration continues,postconditionwhere it returns, andpreconditionat a call. A comment at the iteration names what its holes follow from:holds, the invariant at the loop head,assumed, the precondition, and the fact of each test taken, such asguard. - An object local of a loop, such as a list walk's
node, is aManagedReferenceof the loop state, and the cutpoint's frame names its slot from the state. A null test of it splits the proof withcases node, leaving a hole for the liveness of the instance it holds. An identity test against another object splits the proof withby_cases branch1 : .... A load of a reference field into it is anot outlined:hole. - A loop's test of a 1- or 2-byte struct field splits on the word its load zero-extends, such as
(scanStopped.setWidth 8).setWidth 32 = 0. - A 4- or 8-byte store in a loop through
Unsafe.Addof a reference argument by anintindex, before any other store of the iteration, is stepped from three side conditions: write authority over that element at the iteration's memory, the index below2 ^ 31and the element withinfootprint.cil_loop_obligationproves each from the invariant, precondition and footprint the author writes, byomegaover their conjuncts or from aFilledorWritablefact covering the element. Each is a hole while any of those definitions issorry, and an error at the write once they are written and do not imply it. - A loop over a
Span<T>of 32- or 64-bit integers that storesspan[0]and continues withspan.Slice(1)keeps the span as aWritableSuffix. ItsWritableSpanholds the view's checks andSpanWritableauthority in the caller's memory and no fact about its contents, so the caller need not have initialized it. The loop splits on the remaining length withcases. The store, before any other store of the iteration, steps throughframe.write_span_head, which names the element's address, andSlice(1)throughWritableSpan.tail. The span's bytes are itsfootprint, and the theorem assumesSpanWritableover them. A read of the written span is anot outlined:hole. - Passing that span to a static
(Span<T> target, T value)callee whose body only storesvalueintotarget[0]gives the callee a proved contract over the span's bytes. The outline lends it the span throughWritableSpan.lendand namesWritableSpan.coveredandbelowfor the call's footprint side conditions; the invariant then extends the prefix withFilled.extend. Such a callee outlined on its own is stepped throughWritableSpan.write_head; an empty span throws there, a hole the precondition closes. Any other write to a span outside a loop is refused. - The span such a loop reads or fills may be a local,
ReadOnlySpan<T> rest = valuesorSpan<T> rest = values, assigned once before the loop from a span argument or from the whole of an array argument. The local's suffix is the loop state, and the cutpoint's frame names its slot from the state, since the entered frame holds the null span there. A copied span argument is checked as when the loop slices the argument itself. An array spanned this way is not destructured: the loop starts fromvalues.span falseorvalues.span true, the spanstep_arraySpan_wholepushes, checked byCheckedSpan.of_arrayfor a read and byWritableSpan.of_arrayfor a fill, whose authority andfootprintare the array's storage span. A null array converts to an empty span, so the precondition need not exclude it. A local assigned anything else, or an array also read other than through the local, is refused. - Loops in sequence are bound in pc order (
loop,loop2, ...), each with its own cutpoint,invariantandmeasure(header2,invariant2,measure2, ...). The path leaving one loop for the next loop's test enters that loop throughloop_terminates_then, leaving its invariant at its first head, and that loop's iteration follows. A loop nested in another is refused. - A call in the loop gets a
MethodContractfor the callee, withpreandpostto replace, and aHoldstheorem that steps the callee when it is arithmetic on its arguments. A callee of words that tests them and returns or throws on each side is split withby_caseson each test. A call whose callee returns a value is crossed withcil_loop_call keeping, so the next loop state names its resultoutputwhateverpoststates. A callee that only stores a word argument through a reference argument gets the contract its body meets, proved: it requires write authority over that word before the call and states the word's contents after it. When the loop passes itUnsafe.Addof a reference argument by anintindex, the element is named with the three side conditions of a store, its authority stated at the caller's memory, and they close the call's precondition. A callee over objects whose body a straight-line outline steps (see below) gets the contract read from its body instead, proved, leaving only its precondition at each call. - A struct instance method binds
this, a reference to the caller's struct, as aReferencenamed for the struct, such ascounter. A straight-line body over its scalar fields and word arguments is stepped. Each field it reads first gets a binder for its value on entry, such ascounterValue, withContentsof the field's address (counter, orcounter.element 1 8at offset 8) in the statement. Each written field getsWritableauthority, and the result promisesConfinedto those fields. Fields of 1, 2, 4 and 8 bytes use their stored width, including signed extension on loads and truncation on stores. Repeated stores, and reads between stores, are stepped. The postcondition receives the final field contents. Overlapping fields are not outlined. - A struct receiver loop over 64-bit fields with one conditional back edge and no local homes
gets a
Staterecording field values, contents, write authority and confinement. Its outline steps each path and leaves the invariant, natural-number measure and postcondition to the author. Scalar arguments and results must be 64-bit; void returns are also supported. Narrow fields and frame-owned locals in receiver loops are refused. - A struct value argument binds a fixed-size byte vector, including padding, and is passed as an aggregate scalar. Straight-line outlines step parameter homes and nested aggregate locals, including initialization, field addresses, loads and stores. Aggregate parameter homes and nested aggregate locals inside loops are not outlined.
- An instance of an admitted class is a
Reference. An instance method bindsthisunder its class's name in lower case, such asaccount, or asreceiverfor a compiler-generated class. A parameter named like a hypothesis or memory the proof introduces, such asheldorstored1, is bound asargumentand its position instead. The statement assumesLiveObject initial account,Readableof each field of each object that the body or a callee it steps reads, andOwnedof each they write, using the field views the extraction emits inExtracted.Classes(see Frame class instances). An object the body loads from a reference field is a further binder, such asnodeNextTarget, with the premise that the field holds it. A method that writes a field promisesConfined footprint initial final, withfootprintlisting the written fields. The body is stepped through its field loads, its stores, locals and null tests of objects, and leaves the postcondition withheld1,held2, ... the stored fields'Holdsfacts. A stepping call does not list that an argument object or array of references forms, where its fields lie or what an unsigned scalar field of it loads, which the tactic reads from the statement's hypotheses. A stepping call does list them for an object a field holds, such asnodeNextTarget, which the goal names only once the field's load has stepped. A test of words it names, such as a field value against an argument, splits the proof withby_cases branch1 : .... - A field holding a class outside the model, such as
string, loads as the reference it holds,Tagged.Tag.of initial item, never read through. The statement addsTagged.Tag.Forms initial item, that the reference forms, and the body may store it into such a field, compare it and test it for null, which splits the proof like a test of words. Any reference field may also be set to null, throughOwned.store_formed. Aboolresult leavescase resultfor theBoolthe returned word encodes andcase encodedfor the encoding. - An array argument of class references, such as
nodes : Node[], bindsnodesElement, the element class its allocation records, which covariance may make a class derived from the static one, andnodesLength. The statement assumesReferenceArray.Readableof each element the body loads andReferenceArray.Ownedof each it stores, numberednodesSlot1, ..., orReferenceArray.Livewhen it only reads the length. A loaded element is the referenceReferenceArray.of initial nodes index.toNat, with the premiseReferenceArray.Formsthat it forms, and a stored object adds the premise that it passes the covariance check,storableIn initial nodesElement (.address node) = .ok (), which the caller discharges from the object's class. The footprint listsReferenceArray.entryof each stored element. Each element fact is carried across the stores before it asReferenceArray.HoldsorReferenceArray.Readsof what the element holds, so a load after a store reads back the stored reference, and field facts cross element stores, since no array has fields. An access after a store into another array, or into the same array at an index that is not a different literal, is anot outlined:hole, since the two elements may be one element. A reference outside the model used after a call that writes is also anot outlined:hole. Anewarrof class references of a literal length, the body's first write, adds the premiseCIL.objectFieldSlot * 2 ≤ initial.heapBudgetfor its slots and afresh1Elementdef naming its element class; its elements start as owned nulls, the array isfresh1withfresh1Identitydating it after every caller allocation, and the footprint forgets its elements throughConfined.forget_fresh. An index into it that is not a literal below its length is anot outlined:hole, as is a method with a loop. - A word array keeps its
ArrayViewand element bindings beside a class instance argument or receiver, so indexed element reads and loops use the outline of a standalone word array. Storing the array into a class field also requires itsWholeArrayfact and its storage's origin to match the array reference. Field-slot writes preserve the array's element contents, so an element can be read after the field store. A straight-line element read after a scalar-field write or a supported helper call requires separation between the array storage and each written field; array validity alone does not establish unchanged contents. Allocation preserves existing contents without a separation premise for the fresh storage. Calls that change the array's elements need a contract describing those changes and are outside this outline pattern. An index expressed in the caller's initial bindings has an entry bound premise. An index depending on memory after a write leaves a bound obligation at the read, where the helper and field-store postconditions are available. - Straight-line class methods and supported helpers can use initialized 32- and 64-bit integer locals. The outline carries their private storage through scalar field writes and confined calls, preserves saved values and expires the homes on return. A helper that writes no caller fields preserves caller memory; allocating its local homes does not preserve the entire memory state by equality. A test of named words in such a frame splits the proof as it does without locals, each side going on from the homes and saved values of the path so far. Frames mixing these integers with other local kinds, narrow or native-sized local homes, uninitialized homes, escaped local addresses and reference-field or reference-array effects are unsupported. Helper summaries allow at most one field store and no nested calls.
- An array argument of structs or vectors binds
valuesLengthand is passed as.array ⟨.address values, valuesLength, element⟩, with the premiseWholeArray initial element values valuesLength. The element is theelementTypeof a field that holds such arrays, such asTiles.Pairs.elementType, or a literal such as.signed32; a struct or vector element no field names is a reduciblevaluesElementdef. A load of a field holding a value array, before any write, binds the array and its length, such assamplesValuesArrayandsamplesValuesLength, with premises that the field holds it and that it is whole. A store into such a field of an argument or loaded array steps throughOwned.store_whole, and eachldlen, local, call argument and return of an array is stepped with itsWholeArrayfact. A value-array result is anArrayView. A load of the field after a write, a store of a null array into it, and a call to a method that takes a value array or loads a value-array field arenot outlined:holes, and an unstepped body over a value array leaves itsfootprintto the author. A struct instance method or a method with a loop that takes a value array, or a loop that returns one, is refused. - A call in a body over objects to a method that loads its fields, stores at most one word field of
an object argument and returns a value it names gets a generated
MethodContractread from that body, with aHoldstheorem proved by the same stepping and closed at its return byMethodContract.Holds.returns framed post;cil_contract_stepscomposes the call through it, and the callee's store counts as one of the caller's. A callee that loads an object from a reference field and stores nothing gets apreasking that some object, such asnodeNextTarget, is held there with the facts it reads, and apoststating the result of whichever object the field holds; the caller names that object by its own fact that the field holds it, from a store just before the call or a target of its statement. A loop carries the object facts across its iterations, and acallvirtin it gets a contract like any other call. A loop's statement assumes the same per-object facts, read from its body and callees in order; when that reading stops, it assumes a fact of every named field of each object,Ownedwhere the method or a callee stores the field. - A call in a straight-line body to a static helper over words gets a contract stub, since what
the caller should learn of the result is the author's to state: in a body over objects, a helper
that tests its arguments or throws, and in a body over words alone, one that only computes as
well. The helper has 32- or 64-bit integer parameters and result and no locals, and its body
only computes, tests and throws. The stub is a
MethodContractwhosepreissorryand whosepostisfinal = initial ∧ sorry, the helper storing nothing, and aHoldstheorem against the helper's method index inExtracted.program, split withby_caseson each test. Whencil_loop_obligationfails on a throwing side, its error says that the path is reached unless one of the definitions it unfolds rules it out. At the call the caller statespermitted1, the helper'spreof the values passed, as a hole to prove fromassumed.cil_contract_stepscomposes the call through the contractwith called1 output1 call1, naming the memory after it, the result and the call'sCallResult. The proof reads whatpoststates of the result aspost1fromcall1.post, which the postcondition hole's comment cites. A wrongpreorpostfails in theHoldstheorem or at the caller; neither error is silent. - A helper that takes an object or keeps integer locals, tests words it names from its arguments,
fields and locals, and stores nothing gets the same kind of contract. Its
prestates the facts its body needs before thesorry: of an object, such asLiveObject memory gauge ∧ Gauge.Limit.Readable memory gauge, ormemory.WellFormedfor a frame of locals. Itspostisfinal = initial ∧ sorry, orsorryalone when the helper keeps locals, whose homes are allocated in the memory. ItsHoldstheorem closes each returning side withMethodContract.Holds.returns. At the call,permitted1gives those facts from the caller's own and leaves the rest ofpreas the hole. The helper'spostreads fields in the memory at the call, which a caller with locals names ininitialby its field equations, such asgaugeLimitEqual1. - A caller that keeps 32- or 64-bit integer locals composes these calls inside its frame: a
result stored into a local is read back as the word the helper returned, and a test after it
splits the proof. A body over words alone that keeps such locals beside a helper call, or calls
a helper that keeps its own, is stated of any well-formed
initialmemory rather than the empty one, since the homes are allocated in it; itsPreconditiontakesinitialand itsPostconditionboth memories. A helper over words that keeps its own locals and only computes gets the contract read from its body, which names its result, instead of a stub. - Any other callee leaves a
not outlined:hole, such as a helper that calls another method or stores a field beside a test: the hole names the callee's method index and theMethodContractto write and prove withHolds Extracted.programat that index.
Where the outline cannot step a path, it leaves a hole whose comment starts with not outlined:,
names what it met and what that step needs, and gives the source line to continue from. The
Holes line counts these apart from the obligations. The unedited file elaborates with only
warnings that a declaration uses sorry, and leancil verify rejects it at the theorem audit for
sorryAx until every hole is filled.
new-proof writes this outline for the countdown:
import Extracted.Loops_Countdown_1347de14
import CIL.Verification
import CIL.StructuralLabels
import CIL.Safety.LoopScaffold
/-! A starting proof of `Countdown`, generated by `leancil new-proof` from its extraction. Each
`sorry` is a hole: `leancil verify --goals` prints the goal at each, and `leancil verify`
rejects the file until none remains. A hole commented `not outlined:` marks a path the outline
could not step. The tactics leave obligations tagged `invariant`, `measure`, `postcondition` and
`precondition` (at a call), which the holes select with `case`. -/
open CIL.Safety
open CIL (W32 W64)
namespace ExampleProof
set_option linter.unusedVariables false in
/-- Replace with what callers must guarantee about the arguments, or `True`. -/
def Precondition (value : W32) : Prop := sorry
set_option linter.unusedVariables false in
/-- Replace with what `Countdown` guarantees about its result. -/
def Postcondition (value result : W32) : Prop := sorry
bind_entry entry (value : W32) := Extracted.method0
with [.scalar (.i32 value)] from Memory.empty
allocating Memory.empty_wellFormed
bind_loop loop := Extracted.method0
/-- The loop's locals at its head: `remaining`. -/
abbrev State (home0 : Reference) :=
FrameState [] Memory.empty [.word32] W32
(fun _ => [.bytes .word32 home0]) fun values => [some (.i32 values)]
-- The cutpoint is the loop's back-edge test at Loops.cs:38.
bind_cutpoint header (home0 : Reference) (state : State home0) :=
Extracted.method0 at loop.latch matching (· matches .brnonzero _)
with entry.frame home0, [.scalar (.i32 state.values)], state.memory
set_option linter.unusedVariables false in
/-- Replace with what holds at every loop head. -/
def invariant (value : W32) {home0 : Reference} (state : State home0) : Prop := sorry
set_option linter.unusedVariables false in
/-- Replace with a quantity each iteration decreases. -/
def measure (value : W32) {home0 : Reference} (state : State home0) : Nat := sorry
theorem correctness (value : W32) : Ensures Extracted.program 0
(fun args initial => args = [.scalar (.i32 value)] ∧ initial = Memory.empty ∧
Precondition value)
(fun _ _ _ results => ∃ result : W32, results = [.scalar (.i32 result)] ∧
Postcondition value result) := by
rintro args initial ⟨rfl, rfl, assumed⟩
obtain ⟨home0, entered, enter⟩ := entry.checked value
have setup := enter.setup
have entryFrame := enter.frame
refine invoke_loop_satisfies Extracted.lookup0 rfl setup (header home0) (invariant value)
(measure value) (fun start => ?_) ?_
· have entryFrame := entryFrame []
cil_loop_recurse start value
case invariant => sorry -- invariant at the first loop head
rintro ⟨remaining, current, frame⟩ holds recurse
-- `holds` is the invariant at this loop head and `assumed` the Precondition; each side below
-- names the test it took, such as `guard`.
by_cases guard : remaining = 0#32
· -- leaves the loop at Loops.cs:40
cil_loop_finish [guard]
case postcondition =>
refine ⟨_, rfl, ?_⟩
sorry -- Postcondition at the return at Loops.cs:40
· -- another iteration
cil_loop_recurse recurse (remaining - 1) [guard]
case invariant => sorry -- invariant again at the loop head
case measure => sorry -- measure decreases over this iteration
#print axioms correctness
end ExampleProofIt verifies once the precondition is True, the postcondition result = 0, the invariant True,
the measure state.values.toNat, and each tagged case is proved, the measure case by showing that
remaining - 1 is smaller than a nonzero remaining.
A shape the outline cannot state is refused at the proof outline stage, exiting with 1 and
writing nothing; the message names the parameter, local, loop or test and what it lacks.
leancil verify output-directory [--proof proof.lean] [--theorem name] [--proof-root package]
[--fresh] [--rebuild-library] [--goals] [--trace] [--format text|json]
[--force-full-verify] [--full-artifact Lib=directory]...
verify establishes one named theorem about an extraction. In order, it:
- checks the extraction artifacts as
checkdoes; - opens the certified framework library from its cache, or builds it on a cache miss (see stage progress);
- checks the selected proof with Lean and kernel-replays it;
- audits the theorem's transitive axioms, permitting only
propext,Quot.soundandClassical.choice; - checks artifact and source identity again and writes
verified.jsonin the output directory.
Its guarantee is exactly the theorem's statement, including its preconditions and quantifiers. Standard output carries only the report; standard error carries stage progress and diagnostics. Lean and Lake must be installed.
| Option | Meaning |
|---|---|
--proof |
The proof file. The default is the saved setting, else Proof.lean in the output directory. |
--theorem |
The theorem to check. The default is the saved setting, else ExampleProof.correctness. |
--proof-root |
The Lake package holding the proof's own modules; see consumer proof packages. |
--fresh |
Bypass proof and support reuse; the source-bound library cache is kept. |
--rebuild-library |
Rebuild the library as well. CI bypasses the local library cache automatically. |
--goals |
Print the goal at each hole; see goals of an unfinished proof. |
--trace |
Log each step the proof takes; see trace the proof's steps. |
--format json |
Print one JSON report; see machine-readable verify output. |
--force-full-verify, --full-artifact |
Re-check imported libraries; see verify with imported contracts. --full-artifact requires --force-full-verify. |
The tool ships the framework's CIL sources only. A proof imports Extracted (or a method's
Extracted.KEY, see Editor workspace) and CIL.*;
CIL.Safety.Memory.empty is the caller memory with no allocations. LeanCIL's own example and
test modules are not shipped, and a proof importing one is rejected as invalid-request.
Each Lean or Lake process verify and workspace start is a stage, and stderr reports it:
- On a terminal, a stage prints a
STARTline, aPROGRESSline every 10 seconds, and anENDline with the exit code and duration. - When stderr is a file or a pipe, a stage shorter than 20 seconds prints nothing, so a warm run
leaves stderr empty. A longer stage prints a
PROGRESSline every 20 seconds and then itsENDline. - The removal of unused cache directories after a run publishes a library entry is a stage of
its own: when it chooses any directory, fails or reaches its time limit it prints its
STARTandENDlines, even when stderr is a file, and neverPROGRESSlines, see Library cache.
A PROGRESS line of a Lake build carries Lake's job count:
PROGRESS Building fresh Lean verification library: 212 of 332 Lake jobs (240s)
END Building fresh Lean verification library (exit 0, 501.7s)
The certified library is the compiled framework. It holds every CIL module, and each module is
kernel-replayed. The library
certifies every proof and proof dependency for one framework version, and building it takes
several minutes. It is cached in the directory LEANCIL_CACHE_DIR names, by default
<local application data>/LeanCIL/libraries, under a key of the framework sources, toolchain
and platform. A cache miss first prints one line saying what is being built and kernel-replayed
and where later runs reuse it from.
An entry of a whole library holds about 1.2 GB; a closure entry holds only its modules. Every
verify, workspace and watch process that reads an entry in place records its use in the
entry directory's write time and holds a lock on a file beside the entry (<key>.use) until it
ends; the lock files are never deleted. A process that cannot create the lock file for want of
permission runs without it. LEANCIL_CACHE_DIR should name an absolute directory that only
LeanCIL uses.
A run that publishes an entry removes cache directories that it judges unused, once, before it
continues; there is no setting that turns this off. When the pass chooses any directory, fails or
reaches its time limit it prints a stage to stderr, even when stderr is a file: START Removing up to <n> unused certified library cache directories with the number chosen, or a START line
without a number when it chose none, and an END line with the number removed and the duration.
The number removed is smaller when a process holds an entry the pass chose, when an entry was
used or became a link after it was chosen, and when an entry could not be renamed or deleted.
The pass reads each package's lakefile for at most two seconds and stops choosing, reading and
removing after a minute, so a project on a mount that does not answer can delay it by up to a
minute; a deletion already under way can finish later. Whatever it could not read in that time it
keeps, whatever the age of its pin, past the limit it removes no entry and no pin, and the END
line says that it stopped at the limit or how many lakefiles it did not read in time. Nothing
the pass raises fails the run: a failure is reported on the END line, with exit 1. Nothing
else is printed. Removal goes by age and recency of use, not by whether anything needs the
library later:
- An entry not used for
LEANCIL_LIBRARY_RETENTION_DAYSdays (default 7) is removed. A value below one day counts as one day, so nothing used within the last day is removed. - When more than
LEANCIL_LIBRARY_MAX_ENTRIESentries exist (default 8), counting closure entries, the least recently used ones beyond that number are removed, except those used within the last day. - Staging directories, download archives and unfinished pin files left by killed runs that are over a day old are removed.
- The entry the run uses, an entry whose lock another process holds, and an entry that a
workspacepackage still requires by path are kept, whatever their age. The package records that in a<key>.pin-*file beside the entry, which everyworkspacerun renews. A pin renewed within a day always counts. Otherwise a package whose lakefile can be read keeps the entry for as long as the lakefile names a directory ending in the entry's key, whatever the age of the pin and however the cache directory is spelled; the pin stops protecting the entry when the lakefile names another key or none. When a read of the lakefile finishes and finds the package missing or unreadable, as when a drive is unmounted or the project was moved, the pin protects the entry until it has not been renewed for the retention period, and a pin that cannot be read is treated the same way. A lakefile that is not read in time keeps the entry for that pass, and a pin that a pass set aside and did not finish with is put back and judged again. - A directory is removed only if its name is exactly a library key and it holds the manifest and
receipt that a publisher writes, or its name is a library staging name. The
success-v1directory,.lockand.usefiles and every other name are left alone, and so are links. - The pins and closure records of a removed entry are removed with it.
Each setting is a positive number, a whole number for the entry limit; any other value keeps the default. Infinity and values too large to count mean for ever, or as many entries as can be counted.
An entry removed while its owner was away is rebuilt, or downloaded for a release, by the next
verify, which prints the stage lines of that build. A package that workspace wrote keeps its
entry while its lakefile can be read and names the entry. A package that is found missing or
unreadable for longer than the retention period without a workspace run, or whose lakefile
names another library or none, loses the entry, and leancil workspace sets it up again.
With no whole library cached, verify of one proof without --proof-root first builds a closure
entry: the framework modules that the proof, the extraction, its symbols and the statement display
import, transitively, together with those of the audit executable.
- Every module of the entry is kernel-replayed. Its cache key and receipt name exactly that
module list, and
verified.jsonrecords that key aslibraryKey,closureorclosure-cacheaslibraryBuildand the list aslibraryModules. - The entry holds no other framework source, so a module outside it can be neither imported from
it nor built into it.
verifyreads the import headers of the compiled proof and extraction and refuses a framework import the entry does not hold. - After a verified result is reported, the same command builds, replays and caches the whole
library, which stderr announces, reusing the entry's compiled modules where Lake's traces
allow, and removes the entry once no process reads it. If that build fails, the verified
result and its
verified.jsonstand, and the command reports the failure and exits nonzero. - A failed proof, or one with open goals under
--goals, leaves the entry for the next run. - One closure entry exists per library: a proof with other imports builds the whole library.
--proof-root, batch, contract-import and--force-full-verifyverification,workspace,watch, CI and--rebuild-libraryuse the whole library only, and a package never requires a closure entry by path.
Verification sessions read a cache entry in place, as do packages that require it by path after
workspace, and Lake rebuilds a required module it finds out of date inside the entry. Each run
therefore hashes every file of the entry against the manifest its receipt binds, about half a
second for the whole library.
- An entry that does not match is named on stderr and replaced by a rebuilt library. On Windows the replacement fails while another process, such as an editor, holds the entry's files open.
verifyalso compares the library's files, by name, length and write time, with those it had when it was opened, each time it snapshots the library's compiled modules after a build and once more before single-file and batch verification write their reports; a difference fails the run.- A command that finds another building or opening the library waits for it and says so on stderr.
To use a prepared library instead of the cache, set LEANCIL_CERTIFIED_LIBRARY to its directory
and LEANCIL_CERTIFIED_LIBRARY_SHA256 to the independently trusted SHA-256 of its
cache-manifest.json. The library must have the tool's library key and sources; a missing digest
or any mismatch fails the run. It is hashed against its manifest before a package requires it by
path, and --rebuild-library does not bypass it.
A release package can include a certified-library descriptor for the current runtime. On the first
cache miss, the tool downloads that exact release asset from the official LeanCIL GitHub
repository. The installed package pins its archive hash, producer manifest hash, runtime and
source/toolchain key. The download is validated and independently kernel-replayed before it
receives a local cache receipt. A missing descriptor, incompatible library or unavailable download
falls back to building the packaged sources. --rebuild-library bypasses this download and the
local library cache. Whoever packs a release produces the descriptor and its archive as
release assets describes.
The first invocation saves the proof and theorem selection in verification.json in the output
directory, apart from the success report:
{
"schema": 1,
"proof": "../../Examples/Proofs/Add.lean",
"theorem": "ExampleProof.correctness"
}Proof paths in settings are relative to the artifact directory; command-line paths are relative to
the current directory. With --proof-root, the settings also record the package root as
proofRoot. The settings are kept after a failed proof and after re-extraction, and can be
versioned separately from reports. Explicit --proof, --theorem and --proof-root arguments
override the saved values.
Run verification using the saved settings:
leancil verify artifacts/AddEvery invocation validates the request's identity and required proof evidence. Authenticated
caches can reuse unchanged certified builds and an unchanged proof's result (see
local support cache); source and hash checks, audits and
required kernel replay apply regardless. --fresh, --rebuild-library, --force-full-verify and
LEANCIL_DISABLE_SUCCESS_CACHE=true each bypass the reuse. A failed proof removes
the previous verified.json.
When the assembly or the extractor changed since extraction, verify first extracts again from
the settings identity.json records (assembly path, method, profile, assumptions, references and
imports) and prints Re-extracted artifacts/Add: the assembly changed since extraction. (on
stderr with --format json); a method that no longer exists then fails at extraction. An
artifact that changed while its assembly and extractor did not is rejected as tampered.
verify-batch does not extract again; it reports such an output as a stale input.
A successful run prints, among the assumptions and paths:
Verified: ExampleProof.addTwo_holds
Assembly: Examples, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
Subject: System.UInt32 Examples.Loops::AddTwo(System.UInt32) (method 1) via CIL.Safety.MethodContract.Holds
Extraction entry: System.UInt32 Examples.Loops::TallyTwice(System.UInt32)
...
Statement:
ExampleProof.addTwo_holds : ExampleProof.addTwoContract.Holds Extracted.program ExampleProof.addTwo
Lean messages (1):
TallyTwice.lean:38:0: info: 'ExampleProof.addTwo_holds' depends on axioms: [propext, Quot.sound]
Subject:names each method the statement's conclusion is about, andPremise:each method a hypothesis names. A method counts when a framework predicate withprogram : CIL.Programandmethod : Natparameters (CIL.Safety.invoke,MethodContract.Holds,LoopTerminates, ...) is applied toExtracted.programand an index that reduces to a literal. An index the statement quantifies over is reported as not fixed, and predicates the proof defines are not looked into, so a line never names more than the statement does.Extraction entry:is the method the extraction started from; it says nothing about which method the theorem concerns.Statement:is printed in Lean notation from the audited proof module. Only the notation of the modules the proof imports applies, including consumer modules under--proof-root; the proof's own declarations are loaded without their extensions, so notation a proof defines cannot change the text.verified.jsonkeeps the auditor's text intheoremAudit, which is printed instead, withSubject: not identified, if Lean cannot print the statement.Specification:follows the statement when it names definitions of the proof file, such as aPreconditionandPostcondition: each is printed asdef name binders : type := bodyfrom its elaborated value, in the statement's notation, before the definitions its own body names.verified.jsonrecords the same list asspecification, each entry with itsnameandtext, so changing a definition changes the report and the certificate. A definition that matches on its arguments or recurses is printed as Lean elaborates it, in terms of the auxiliary definitions it compiles to, and the field accessors of a structure the proof declares are not listed. Definitions of modules the proof imports are named in the statement and not printed.Lean messageslists the informational and warning messages of the proof file, such as#check,#evaland#print axiomsoutput, atfile:line:columnin the proof. The first 60 lines are shown;proof-messages.txtin the artifact directory holds the full text, and the report names it when lines are omitted. Messages are stored with the cached proof, so a run that reuses the proof shows them too. They are also printed on failure, after the diagnostic, so query commands work while a proof is unfinished, including under--proof-rootwhen proof checking itself fails.
leancil verify ... --goals prints the goal at each sorry written in the proof, the goal before
each tactic that raised an error and each goal a tactic block left unsolved, once each and in
source order. For the countdown outline of start a proof:
leancil verify artifacts/Countdown --proof Proofs/Countdown.lean --goalsIts diagnostic on standard error starts with:
Invalid: 8 goals remain in Proofs/Countdown.lean.
Stage: open goals
Next: Prove each goal listed below in place of its `sorry` or failing tactic, then rerun.
Goals (8):
Proofs/Countdown.lean:17:41: sorry
value : W32
⊢ Prop
Proofs/Countdown.lean:20:49: sorry
value result : W32
⊢ Prop
Each entry is the place in the proof, then sorry, failing tactic or unsolved, then the
goal as Lean prints it there: its case tag, hypotheses and target, in the names the proof file
opens. A sorry written as a term, such as the body of a definition, is listed with the type it
stands for.
When any goal is open, the run exits with 1 at the open goals stage, with kind unsolved-goal
in failed.json, unless Lean reported an error, which fails at
proof checking as without the option. A verification without --proof-root stops right after
the proof check, skipping kernel replay and the audit, which could only refuse such a proof. Under
--proof-root the package's replay and audit run before the goals are read. With no goal open,
verification continues as it does without --goals. A sorry anywhere in the proof file is an
open goal, whichever theorem is selected. The proof's other messages are not listed with the
goals: the report gives their count and proof-messages.txt, which holds them. A failed
verification without --goals names the option on a Goals: line after Next:.
--goals checks the proof with import CIL.Observe added as for --format json and the Lean
option cil.goals set (see PROOFS-STEPPING), and
its result is cached apart from one without it. With --format json the goals are the report's
goals. leancil watch --goals prints them after every save.
Method and call validation failures name the rejected item and the method containing it. A
rejected call reports its callee, caller, IL offset and declaring assembly scope. For example, a
reachable Environment.ProcessorCount call is outside the admitted runtime models. Exact closed
typeof comparisons are supported; a GetTypeFromHandle call outside those patterns is
unsupported. The diagnostic identifies metadata/CIL validation as the failing stage and links to
the supported subset.
When proof checking fails, the report leads with Lean errors (N):: each
error: diagnostic with its file:line:col, the module Lake was building and
its full message block, omitting axiom reports, traces and warnings. Each error
is printed once. A message longer than 40 lines or 400 columns, and every error
after the first 20, is shortened or left out of this summary and printed in full
under Details:; nothing else follows. When the output holds no Lean error,
such as a crashed tool, Details: holds the whole output instead. The
unmodified output is the message of failed.json and,
when LEANCIL_TRACE_DIRECTORY is set, its transcripts.
Lean prints an internal error when its runtime or a tactic reads a part of a term or an array
that is absent, and elaboration then continues on a default value. The messages are
PANIC at ..., INTERNAL PANIC: ..., Error: index out of bounds,
Stack overflow detected. Aborting. and LEAN ASSERTION VIOLATION. One counts where a line of
the output of Lean, Lake or the audit executable, or a line of a message Lean logged, starts with
that exact text, which is how Lean's runtime writes it. The same words inside a sentence, a goal or a term are ordinary output,
and a failed tactic, an expected rejection and the goals of --goals are Lean errors with their
own kinds. Every command that runs
Lean, Lake or the audit executable fails when their output holds one, including when the
process exits with 0, so verify, verify-batch, gates, check, audit-library,
workspace and the certified library build write no report or certificate from that run. The
report starts with Lean or a LeanCIL tactic reported an internal error. and leads with
Internal errors (N):. It lists each message once with the number of times it was printed, its
file:line:col when Lean logged it at a position, and the module Lake was building. The Lean
errors of the run follow. In a batch, an internal error printed while building one request's
proof module fails that request, whether or not the build as a whole succeeded, and one printed while building a module the requests share
fails each of them. The failure report has kind internal-error.
Verification checks a copy of the proof, Extracted.lean, the PDB names and, under
--proof-root, the package's sources and its proof module. A location in a copy cites the file it
was copied from, at the same line and column, and Lake's module names the proof's own module, so
editors and terminals open the file the developer edits. Only a copy byte-identical to its
original when it was made is mapped; a generated module keeps the path Lean printed. Direct
verification checks the proof with lean --json and renders each message in Lean's
file:line:col: severity: form. Informational messages, which plain Lean output prints without a
position, appear there as info: entries, and the proof's own messages follow under
Lean messages.
Lean on Windows builds the environment of each process it starts in a 32,767-byte buffer.
Lake starts Lean, including the editor's language server, with its own variables
(LEAN_PATH, LEAN_SRC_PATH, PATH and others) added to the environment it inherited,
and Lean drops every variable that no longer fits without an error, so LEAN_PATH can
be dropped and imports stop resolving. Each name=value entry counts its UTF-8 bytes plus a
terminator, and the block adds one more. Lean replaces an inherited variable only when the
name matches exactly, so Lake's PATH is added beside an inherited Path and the search
path counts twice.
Before running Lake, leancil computes what Lake will pass on: the environment it gives Lake, with
the changes elan's lake proxy makes, and the variables lake env prints (for lake build,
which passes Lean only LEAN_PATH, just that one). It fails when the result exceeds the limit,
naming the size, the limit and the largest variables. leancil workspace makes the same check for
lake serve, taking its own environment as the editor's, so the failure appears at setup. Lake
prints a variable it unsets as empty; counting it can overstate the size by a few bytes and
cannot understate it.
Lake adds a package's source directory to LEAN_SRC_PATH once for every [[lean_lib]] table in
the package's lakefile. After leancil workspace, a generated package and a package that pins
leancil resolve the framework to packages that declare only the framework and editor libraries,
which adds two directories. A LeanCIL checkout declares one library per test module, which adds
about ninety. A shorter checkout path and fewer PATH entries reduce the size. Setting
LEANCIL_LEAN_ENVIRONMENT_LIMIT to a byte count lowers the limit; on other systems, where Lean
has no such buffer, it enables the check, for example to measure headroom.
A failed verify writes failed.json next to where verified.json would go and
removes any verified.json; a later successful verification removes
failed.json. verify-batch writes the same report into each failing request's
output (for the last request of an output, as with verified.json) and as the
failure field of each --results entry (null when there is none).
{
"schema": 1,
"kind": "unsolved-goal",
"resource": null,
"stage": "proof checking",
"theorem": "ExampleProof.correctness",
"module": "Proofs.Mix",
"proof": "/work/package/Proofs/Mix.lean",
"output": "/work/artifacts/Mix",
"method": { "entry": "System.UInt64 Calls::Mix(System.UInt64,System.UInt64)", "assembly": "Contracts, Version=1.0.0.0, ...", "assemblySha256": "..." },
"file": "/work/package/Proofs/Mix.lean",
"line": 12,
"column": 3,
"diagnostics": [
{ "kind": "unsolved-goal", "resource": null, "module": "Proofs.Mix", "file": "/work/package/Proofs/Mix.lean", "line": 12, "column": 3, "message": "unsolved goals\n..." }
],
"message": "Command failed (1): lake build ...",
"rerun": ["leancil", "verify", "/work/artifacts/Mix", "--proof", "/work/package/Proofs/Mix.lean", "--theorem", "ExampleProof.correctness", "--proof-root", "/work/package"]
}kind is one of:
| Kind | Meaning |
|---|---|
unsupported-extraction |
check rejected the method in metadata and CIL validation, or Lean rejected the extraction certificate |
stale-input |
The assembly, extraction artifacts or proof inputs changed after extraction or during verification |
internal-error |
Lean, Lake or the audit executable printed an internal error, such as a panic in a tactic. The run is rejected whatever its exit code, and the report says nothing about whether the proof holds |
elaboration-error |
A Lean error other than an unsolved goal or a resource limit |
unsolved-goal |
A Lean unsolved goals error, or a verify --goals run that stopped at the goals it found open |
resource-limit |
Heartbeats ((deterministic) timeout, (kernel) deterministic timeout) or recursion depth; resource names which |
replay-or-audit-rejected |
Kernel replay or the theorem and axiom audit rejected the proof |
refutation |
The theorem verified and states Not (contract.Holds ...) for a MethodContract or OutcomeContract |
invalid-request |
The proof or theorem selection is invalid |
unclassified |
Anything else, such as a missing tool; read message |
The request's kind, file, line and column are those of the first diagnostic. diagnostics
lists each distinct internal error and then every Lean error of the request's own modules with its
message block, so an internal error gives the request its kind. Lines are 1-based and
columns 0-based, as Lean prints them. Locations in the session's copies cite their originals, as
in the text report. message is the original output, unmodified; rerun reruns just that
request. Classification uses only the stage, LeanCIL's own messages and Lean's error prefixes
above. Only a verified theorem whose elaborated statement is Not applied to a contract's Holds
is a refutation, as reported by the theorem audit; an unsolved goal is never a refutation. A
verified refutation keeps its verified.json, the certificate of the refutation, and also
writes failed.json with kind refutation, located at the theorem's name.
leancil verify ... --format json prints one JSON report on stdout instead of the text report,
and nothing on stderr except stage progress; the exit code is the same as
without it. --format text is the default. The report has schema 1, result (verified or
failed), the stage that failed, the theorem, method, proof and output, and on success
the axioms, the statement and its specification, the definitions
Specification: prints, each with its name and text. The proof's own
Lean messages are in messages, and rerun repeats the run. With --goals, goals lists each
open goal with its file, line, column, kind (sorry, failing tactic or unsolved) and
goal; without it goals is null and unknown.goals says why, as it does when the run stopped
before the proof was checked. failures holds one record per Lean error, or per goal a tactic
stopped on, located in the developer's file as in the text report:
{
"kind": "elaboration-error",
"source": { "file": "/work/Proofs/SpanDrain.lean", "line": 37, "column": 54 },
"message": "cil_loop_steps: target state not matched at pc 7: ...",
"tactic": "cil_loop_steps",
"stopped": false,
"method": {
"index": 0,
"signature": "System.Int32 Examples.Loops::Drain(System.ReadOnlySpan`1<System.Int32>)"
},
"cil": {
"pc": 7, "ilOffset": 19, "instruction": "brtrue.s IL_0002", "leanInstruction": null,
"source": { "file": "Loops.cs", "line": 30, "column": 9 }
},
"state": {
"reached": {
"stack": "[CIL.Safety.Value.scalar (CIL.Value.i32 (BitVec.ofNat 32 view.length))]"
},
"expected": {
"stack": "[CIL.Safety.Value.scalar (CIL.Value.i32 (BitVec.ofNat 32 (view.length + 1)))]"
}
},
"missing": { "shape": "targetState", "residual": [] },
"suggestions": ["state a fact in the reached form, or state the target in it"],
"obligations": [],
"unknown": {
"cil.leanInstruction": "the walk is at the target's pc, so it steps no instruction",
"obligations": "the goal the tactic was handed carries no obligation tag"
}
}kind, resource and module are as in failed.json. tactic, stopped,
method, cil, state and missing come from the failure record CIL.Observe
logged for the error; none is read from the error's prose. --format json checks the
proof with import CIL.Observe added at the start of its first import line,
which moves no other line or column, and with the Lean option cil.diagnostics
set; the observer then records each error a cil_ tactic raised, and each goal
one left that Lean reports as unsolved, with stopped true (see
PROOFS-STEPPING). An unsolved goals error with several such goals gives one failure per goal. ilOffset and
instruction are read from the manifest at that method and pc. cil.source is
the C# file, line and column of the last visible PDB sequence point at or before
the pc, read from the extraction's Symbols.lean whether or not the proof
imports ExtractedSymbols; an extraction without a matching PDB has no
Symbols.lean, and unknown says so. missing.shape names the kind of fact the step
lacks, such as unsafeAdd, spanValidity or targetState, calleeContract at a
call or callvirt, or on a class instance objectForm, objectSlot or
objectAllocation, and residual the terms it must prove: the step rewritten by
the proof's step equations and the _ = .ok _ and _ = .error _ facts in scope.
A side condition, such as an unfolded step a tactic could not close, has a shape when it names one
of these operations. A run stopped before its first instruction because the entry could not check
an object argument lacks objectForm, with the formObject of each object argument as its
residual. obligations lists the obligation tags of the goal that failed, or of the goals an
unsolved goals error lists, such as invariant.
suggestions is advice, kept apart from these facts. Every field left null
for lack of data, and an empty obligations, has its reason under unknown,
keyed by the field's name; an error without a failure record, such as Lean's
own, says so there. The message is Lean's error as printed; the tactic is the
one the error names, also when it ran inside another tactic's expansion, such
as the cil_loop_steps that cil_loop_continue runs.
leancil verify ... --trace checks the proof with import CIL.Observe added as
for --format json and trace.CIL.step set, so the observer logs each step the
proof takes, whichever tactic or term took it: its pc and instruction, the
source line when the proof imports ExtractedSymbols, the lemmas applied, the
hypotheses its proof used and what changed, then for each cil_ tactic the
number of steps it took and the obligation tags of the goals it left (see
PROOFS-STEPPING). The text report
prints them in full under Trace (N entries):, after and apart from the proof's
Lean messages; the JSON report lists them in trace, each with its location
and text. Without --trace, trace is null and unknown.trace says why, as
it does when the run stopped before the proof was checked. A traced result is
cached apart from an untraced one.
leancil verify-batch requests.json --format json prints one JSON document on
stdout instead of the per-request lines: schema 1, the passed and failed
counts, and requests, each with its expect, its status (verified,
rejected or failed) and the report that verify --format json prints for
it. --trace traces every request's proof, after its line in the text report
and in each report in JSON. The request manifest, the other options and what a batch shares are
in batch verification.
leancil export-contracts manifest.json [--output Lib.leancil.contracts] [--bundle directory]
checks a library's selected contracts and writes their bound sidecar. See
Publishing verified contracts for
the manifest, exact theorem guarantee, export restrictions and source bundle.
All exports must pass before the sidecar is published.
After import-aware extraction, leancil verify output --proof Caller.lean checks
the caller under the published contracts. --proof-root uses the same interface
audit for a consumer package. --fresh can use an empty LEANCIL_CACHE_DIR; no
library implementation proof source, artifact or full bundle is required.
Contract interfaces gives the extract options and required pins, the
sidecar schema and its checks, and the form the caller theorem must have.
A schema-4 verified.json contains imports[] with acceptedVia set to
published-certification, the implementation SHA-256, interface digest,
certification theorem/statement/digest, sidecarSha256, certificationAuthenticated
(always false: no pinned digest covers the certification text) and deployment
obligation. CLI output prints the certification as an unauthenticated sidecar
record with its sidecar SHA-256, and the obligation. The caller theorem is
conditional on those imported contracts.
--force-full-verify freshly checks the selected library implementations and discharges those
imports in a concrete linked CIL theorem; --full-artifact Lib=directory, repeatable, selects a
relocated copy of a published source bundle.
Independent imported-library verification states the checks, the supported
source format and the trust boundaries.
Reference-only extraction is an authoring input. Verification checks its caller
proof, then exits with status 1 and an authoring-only diagnostic. It does not
write verified.json or publish a successful proof receipt.
Run leancil lint-exceptions artifacts/Method --documentation Assembly.xml
after extraction. The command checks the extraction again, then writes
artifacts/Method/exception-lint.json. It does not verify a theorem or write
verified.json. Drift is diagnostic and does not change the command exit code.
Malformed documentation or stale extraction fails and removes an old lint report.
The report keeps potential modeled sites and XML declarations separate. It compares the selected entry's declarations with its profile-reachable method closure. It includes folded throws, integer divide/overflow, signed Abs, X86 DivRem and span indexing faults. Clamp invalid bounds remain a model fault; this experiment does not map them to a CLR exception. Memory faults, invalid states, unsupported operations and fuel exhaustion have no CLR name here. The lint is a conservative site analysis. It does not prove feasibility under a contract, exception conditions, or complete runtime behavior.
XML must contain the selected compiler member ID and matching assembly name. Unresolved cref, include and inheritdoc need expansion first. The supplied XML hash identifies bytes; it does not prove that they came from the DLL build. No documentation text becomes evidence or a contract premise.
leancil workspace assembly.dll method --profile profile --proof proof.lean [--theorem name]
[--proof-root package] [--assembly identity] [--assume-initialized Namespace.Type]...
leancil workspace --remove key-or-method [--profile profile] [--proof-root package]
leancil watch [package] [--project app.csproj]... [--configuration name] [--once] [--goals]
[--format text|json]
workspace generates the method's extraction into the proof's Lake package as the modules
Extracted.KEY and ExtractedSymbols.KEY, so the proof file shows live goals in the editor, and
prints the import to use. KEY names the method and digests its assembly name, signature, profile
and initialization assumptions, so each method has its own module. Run it again after rebuilding
the assembly, then restart the file in the editor.
| Option | Meaning |
|---|---|
--profile |
The execution profile, as for extract. This option is required. |
--proof |
The proof file to open in the editor. This option is required. |
--theorem |
The theorem watch verifies; without it watch only refreshes the editor modules. |
--proof-root |
The Lake package. The default is the nearest package above the proof; a proof outside any package gets one beside it. |
--assembly, --assume-initialized |
As for extract. |
--remove |
Drop one recorded selection, named by KEY or by a method selector that names one recorded profile (add --profile when it names several), from the package given by --proof-root, by default the one holding the current directory. Its record, both modules and their Lake outputs are deleted; nothing is rebuilt. |
watch rebuilds the C# on change, refreshes the extractions whose generated modules changed and
runs verify for each recorded proof whose extraction or sources changed.
| Option | Meaning |
|---|---|
package |
The Lake package workspace used. The default is the current directory. |
--project |
A C# project to build and watch; repeatable. |
--configuration |
The build configuration. The default is Release. |
--once |
Run one cycle; exit 1 unless every proof verified or names no theorem. |
--goals |
Print each proof's open goals every cycle. |
--format json |
Print each cycle as one JSON line. |
Run verify on the same files for a certificate; editor checking gives none. The package layout,
the editing loop, the watch statuses and the certification step are in proof-authoring
workspace.