lev docs

What lev check does

Terminal
lev check
lev check --kernel official --kernel nanoda --jobs 16
lev check --no-build --only Mathlib.Order.Basic
lev check --json > check.json
  1. Unless --no-build is given, it runs lake build through elan in the project.
  2. It builds lev-export, the per-module exporter in lev's repository under lean/export, once per toolchain. lev carries the exporter's sources, writes them to its cache with a lean-toolchain naming the project's toolchain, and runs lake build there through elan. The build is keyed by the toolchain and a hash of the sources.
  3. It exports the toolchain's own Init with lev-export, with LEAN_PATH set to the toolchain's lib/lean only, once per exporter build. This is the reference: the kernel's built-in constants and the standard axioms of the project must match it.
  4. It asks Lake for the modules of the root package's default targets (lake query --json :defaultModules, the modules lake check exports) and runs lake env lev-export --out DIR --jobs N MODULES in the project. lev-export imports them once and writes one LeanExport 3.1.0 file per module of the import closure, Init, Std and every dependency included. Each file holds only that module's own constants and, for files of Lean's module system, which of them importers see without a body.
  5. For every module and kernel it builds the module's slice, looks the verdict up under the kernel's identity and the slice's key, and runs the kernel on a slice file only when there is no verdict yet. Accept and reject verdicts are cached; errors and timeouts are not.
  6. It runs the composition check over all results and prints the verdict.

The project is registered for cache collection on every run. --only MODULE checks the named modules, their imports, and the owners of the constants their slices use, which is what the named modules' verdicts depend on.

Slices and views

A slice is one module's own constants in full, plus the closure of what they reference. In the slice, an imported theorem or opaque is an axiom with the same name, universe parameters and type. Every other imported constant appears in full, with what its type and value reference; inductive types come with their constructors and recursors, and the quotient package comes with Eq ahead of it. The kernel's built-ins (Nat and its arithmetic, String.ofList, Char.ofNat, Eq, Quot and the rest of Lake's primitiveTargets) are always copied in full and never become axioms. Neither does anything they or the standard axioms depend on in the toolchain's Init, such as Nat.bitwise, through which Nat.land is defined.

A slice is checked in up to three views, in this order, until a kernel accepts:

ViewAxioms in the slice
exportedImported theorems and opaques, and imported definitions that the module system hides from importers. This is what a module file saw when it was built.
theoremsImported theorems and opaques only.
closureNone: every import appears in full.

For a module file Lean itself stores imported theorems without their proofs, so lake build already elaborated the module's constants against axiomized imports, and the exported view is usually enough. Modules with import all and files outside the module system can need a larger view; those are listed as fallbacks.

The slice key is a SHA-256 hash over the export format, the Lean commit, the view and the sorted entries of the slice: each constant's name, role (own, full or axiom), kind and hash. Own and full entries carry a hash of the whole declaration, axiom entries a hash of the name, universe parameters and type only. The hashes ignore what kernels ignore and what exports vary on (binder names, binder info, metadata, file-local indices, record order) and keep everything else. So:

  • A new proof of the same statement changes the module's own slice, and the slices of importers that needed the closure view, because a closure slice copies imported theorem bodies. Importers checked in the exported or theorems view see the theorem as an axiom of the same type, and their slices keep their keys.
  • A new statement changes the slices of the importers that use the theorem.
  • A changed definition changes every slice that copies it in full.

The composition check

Each slice is checked on its own. A small linker then decides whether the accepted slices make up one well-typed environment. It accepts the development when all of these hold:

RuleRequirement
L1Every referenced constant has an owner. Only theorems with equal types may have several owners; Lean allows the same theorem in several modules.
L2Every axiom in a slice has an owner that declares a theorem or opaque (or, in the exported view, a hidden definition) with the same type, and the owner's slice was accepted by the same kernel.
L3Every full copy has the owner's kind and full hash.
L4No cycle in the graph "a slice copies a constant owned by another module".
L5Every slice is accepted by every selected kernel.
L6The real axioms in use are propext, Classical.choice and Quot.sound, each identical to the reference's. Every axiom declaration in use is checked, and names are compared component by component, so «Classical.choice» is not Classical.choice.
L7The kernel's built-ins, the standard axioms and everything their types and values depend on in the reference are identical to the reference's wherever the development declares them, and are never axiomized.
L8Every module comes from the same toolchain and exporter, every import is listed before its importer, and the reference belongs to the same toolchain.

The argument goes by induction over an order of the slices that L4 guarantees: when a slice is reached, every constant it took as an axiom is owned by an earlier slice whose check established its proof (L2, L5), and every constant it copied is the owner's (L3). Replacing an axiom by a theorem with a well-typed proof of the same type keeps every derivation valid. It assumes that each kernel is sound for what it accepts, that lev-export reports the .olean files faithfully (the trust lake check puts in leanexport), and that SHA-256 has no collisions.

Kernels

--kernelBinaryNotes
official (default)leanchecker --from-exportLean's C++ kernel through Lean.Replay, with LEAN_ABORT_ON_PANIC=1.
paranoidleanchecker-paranoid --from-exportThe same checker, linked statically.
nanodananoda_binAn independent kernel in Rust. Its configuration permits exactly the standard axioms, the slice's axiomized imports and the module's own axioms.

Repeat --kernel to require several kernels; every slice must then be accepted by each. A kernel's identity is the SHA-256 hash of its binary (for leanchecker also of the toolchain's shared libraries, .so, .dylib or .dll) and of how lev runs it, so a new toolchain gets new verdicts. lean4lean is not offered: the bundled version validates the kernel's primitive definitions against templates that need helper constants a slice does not contain, so it rejects most slices. The verified kernels con-leche and con-ron decline every slice, because they reject non-standard axioms and an axiomized import is one.

Sandbox

Loading an .olean file is running untrusted input, so everything after the build runs in the same bwrap sandbox lake check uses for its kernels: lake query, lake env lev-export, the reference export and every kernel run. / is read-only, /home, /root, /run, /tmp and /var are covered, the toolchain, the project and its package directories are bound back read-only, only the export directory is writable, the environment is cleared, every namespace including the network is unshared, and core dumps are off. --no-sandbox runs them directly.

lake build is not sandboxed. It runs the project's Lakefile and build with your permissions, as running lake build yourself would. With --no-build, lev runs no project code outside the sandbox.

Measured on Mathlib

Mathlib at commit ae9dcc7a4b, Lean v4.36.0-rc2, on a 96-core Linux machine:

RunTime
What lake check runs: leanexport of Mathlib, then leanchecker on the full export7:04 plus 52:37, single-threaded
lev-export of all 11,136 modules, 16 jobs26 s
Cold lev check, official kernel, 32 jobs5:44

The cold run spends about three times the kernel time of the single full check, because every slice rechecks the imported definitions it copies. Warm runs over 20 consecutive Mathlib master commits:

CommitSlices recheckedChecking
Typical commits1 to 7about 19 to 21 s
The nnnorm to nnNorm rename (174 files)79176 s
A definition change22231 s
A Batteries bump11

The checking times do not include the export, which runs in full every time. With every verdict cached, lev check --no-build --jobs 4 on the same checkout took 2:26: 84 s for the sandboxed export of all 11,136 modules and 60 s to read, hash, look up and link, with no kernel run.

Limits

  • This is not a replacement for the trust model of lake check in one respect: whether the slices compose is decided by lev's own small linker, not by a proved theorem. con-leche PR #13 (Joachim Breitner, open) checks module by module with a proved composition theorem. The verified kernels con-leche and con-ron cannot check lev's slices, because they reject non-standard axioms.
  • lev-export is written against Lean's import internals and LeanExport format 3.1.0. It was built and tested with v4.36.0-rc2; with a toolchain whose API differs it does not build, and lev check exits 2.
  • The kernels still unfold theorem bodies. A slice whose check needs an imported proof, for example to reduce Acc.rec on it, is rejected in the smaller views and falls back to a larger one.
  • Lean.Replay in leanchecker orders declarations by constant references only, so a declaration with a string literal can reach the kernel before String.ofList. Such modules pass only in the closure view. On Mathlib this happened for 7 modules.
  • Only the checking is incremental. Every run exports the whole import closure again, and the export of Mathlib takes 6.9 GB of scratch space in lev's cache while the run lasts.
  • Verdicts are trusted cache entries. Anyone who can write to lev's cache directory can plant one.
  • The sandbox needs bwrap, so it works on Linux. Elsewhere pass --no-sandbox. Kernels run through /bin/sh, so Windows is not supported.

Output and exit status

lev check after a proof edit in a three-module library
accept: 4 of 4 modules checked with official
slices: 1 checked, 3 reused
axioms: Classical.choice, Quot.sound
time: build 0.2 s, export 0.4 s, check 1.8 s (kernels 0.1 s summed)

The fourth module is Init.Prelude, which the library's files import. The text summary says the verdict, how many slices were checked and reused, the fallbacks, the axioms in use and where the time went. A rejection lists the broken rules and the last line of each kernel's message. When a kernel run ends in an error, a timeout or a decline, the verdict is unknown and the summary lists the modules lev could not check. --json prints the envelope lev.cli.check/v2, whose data holds project, toolchain, built, sandboxed, roots, exporter, reference, seconds and check, the engine's full report (lev-check/1: verdict, kernels, slice counts, verdicts per view, fallbacks, rejections, the modules it could not check, axioms, violations, timings, and every attempt per module and kernel). Exit status 0 means accepted. 1 means rejected: a kernel rejected a slice in every view, or a linker rule failed. 2 means lev could not finish the check: no project, a failed build, a missing tool, an exporter that does not build, or a kernel run that ended in an error, a timeout or a decline. A rejection found alongside such a run still exits 1. Progress and errors go to stderr.