Explore what a Lean project proves, which uses those guarantees support, and where the correspondence still needs evidence. Review changes without treating every new question as a release obligation.
This first implementation extracts actual Lean declarations, separates statement dependencies from proof dependencies, and generates a standalone, interactive HTML map with JSON and Markdown reports. It includes explicit use cases, requirements, assumptions, hazards, mitigations, checks, concerns, alternatives, and an append-only decision log inside a Git-managed manifest.
Requires Lean 4.32.1 (via Elan/Lake), Git, and Node.js 22+. Lake fetches the pinned LeanTEA dependency on the first build. No npm packages, network service, database, or model API key is required.
lake build eproof eproof_tests Tests.Fixture
lake exe eproof_tests
lake exe eproof index . examples/fixture.json out/fixture.snapshot.json --allow-project-code
lake exe eproof map out/fixture.snapshot.json examples/fixture.json out/fixture-mapOpen out/fixture-map/report.html in a browser. It starts with the project overview,
not a selected theorem. Browse the module tree and select Fixture.Device to see
its configuration field, the inRange predicate and the reset guarantee.
Fixture.NamedDevice demonstrates inheritance. Add concerns,
record decisions, and use Download manifest with decisions to save changes.
Browser edits are in memory until downloaded; they never overwrite the source
manifest or change the displayed CI result. Regenerate the report after reviewing
and saving a manifest.
Every output path must be new. This prevents accidental overwrites of evidence.
Generated outputs under out/ are ignored by Git.
lake exe eproof index ../sparkle examples/sparkle-compilation.json out/compilation.snapshot.json --allow-project-code --no-build
lake exe eproof map out/compilation.snapshot.json examples/sparkle-compilation.json out/compilation-mapThis report starts with Guarantees and gaps, not the declaration graph:
- IR roundtrip: the actual conditional trace theorem, its hypotheses and axiom closure.
- General DSL-to-RTL preservation: existing
cnt8instance proofs alongside missing coverage, shipping-text semantics, trust reductions and hierarchical composition.
Expand a proof to inspect its exact statement and transitive axioms. Expand the
second guarantee's chain to see concrete follow-up work and source citations.
The declaration explorer is supporting evidence, not the definition of completeness.
--no-build needs existing artifacts and does not establish source/artifact agreement.
The optional manifest guarantees array records a title, desired statement,
scope, exclusions, and required steps. Each step has endpoints, detail and
a source, plus exactly one of root (registered theorem), gap (work needed),
or reported (not inspected here). Missing guarantees need no invented theorem.
The pure Lean assessment distinguishes available proof artifacts, missing/non-theorem
roots, sorryAx, incomplete inspection, reported evidence and open connections.
Custom/evaluator axioms remain visible; no automatic trust approval is inferred.
These results are included in HTML/JSON/Markdown. Changing a guarantee, its scope
or its gaps triggers review. CI policy pass is independent of guarantee completeness.
The Sparkle gap inventory is manually curated from the source and its guarantee documents. It is not an exhaustive automatic gap detector. Even a fully supported scoped argument does not prove that its scope matches the intended use.
lake exe eproof index ../sparkle examples/sparkle-signal.json out/signal.snapshot.json --allow-project-code
lake exe eproof map out/signal.snapshot.json examples/sparkle-signal.json out/signal-mapThis example starts with the clock-domain and signal structures, their fields, memory definitions, and the theorems connecting the memory model to a loop implementation. The selected modules are catalogued, including declarations not used by a registered proof. It is still a selected scope, not an inventory of every module in the Sparkle repository.
The overview connects model types, supporting definitions, and registered roots. Select a module to inspect all its indexed declarations. Focus a type or theorem to follow 1–6 levels, with separate colors for statement, definition and proof dependencies, record fields and inheritance. Switch to Users to see which declarations refer to a selected model. Selecting a graph node preserves the current map; Focus selected changes its starting point.
Library/generated declarations are filterable. A visible count and Show more nodes disclose limits; there is no silent eight-neighbor cutoff. Theorems mentioning a type are distinguished from proofs depending on a declaration. Neither relationship is presented as proof that the structure satisfies every intended use.
lake exe eproof index ../sparkle/proofs examples/sparkle-precision.json out/sparkle.snapshot.json --allow-project-code
lake exe eproof map out/sparkle.snapshot.json examples/sparkle-precision.json out/sparkle-mapThe example connects the modeled error budget and minimum fractional-bit count to their actual theorems. It also records a question about coefficient rounding, which the Precision module explicitly excludes. These use cases and mappings are proposals, not a record of deployment approval or a claim that Sparkle has a defect. Inspect other existing project results before concluding evidence is missing.
index builds only the selected modules, then loads their artifacts in the
target project's Lake environment. --no-build skips that build and reports
artifact_loaded; it does not claim the artifacts match the current sources.
Neither mode is an independent kernel check or a complete system recheck.
Project loading requires --allow-project-code because Lake and Lean can execute
project code. Only Lean 4.32.1 is currently supported; other versions fail
explicitly. Set EPROOF_WORKER to the absolute path to Worker.lean if invoking
the executable outside this repository.
Extract each version in its own existing checkout, with its own manifest and dependency lock. eproof never checks out revisions into a working tree.
lake exe eproof review out/base.snapshot.json out/head.snapshot.json base.manifest.json head.manifest.json out/reviewThe report distinguishes changes to statements and definitions, proof bodies, axioms, environment, requirements, and policy. The base manifest's obligations remain in force even if the head removes them. A changed use case triggers reassessment of connected mappings. Renames require an explicit manifest change; this version does not guess equivalence or silently transfer approval.
Exit codes: 0 means the specified policy passed; 2 means needs_review,
block, or incomplete; 1 means an input, environment, or execution error.
Passing a policy is not proof of suitability or complete hazard coverage.
The caller must supply trusted base inputs and a trusted eproof executable. Snapshots and manifests are ordinary files, not authenticated certificates. Do not let a PR choose its own trusted baseline or replace the checking binary.
AI integration uses an explicit file protocol, so you can use your existing agent without giving this application network credentials:
lake exe eproof suggest out/sparkle.snapshot.json examples/sparkle-precision.json req.budget out/packet.json
# Give packet.json to your chosen agent and save its JSON response as response.json.
lake exe eproof import-suggestions out/sparkle.snapshot.json examples/sparkle-precision.json response.json out/proposed.manifest.json
lake exe eproof map out/sparkle.snapshot.json out/proposed.manifest.json out/proposed-mapThe packet contains instructions, the manifest, root statements and extracted
semantic context. suggest does not invoke a model or send data anywhere.
Imported concerns must cite a source, describe a concrete scenario, and ask a
question that could change a decision. Alternatives retain gained/excluded use
cases and recheck work. Zero concerns is valid. Stale packets, duplicate IDs,
unknown targets and invalid fields are rejected. Importing suggestions cannot
modify obligations, accept a specification change, or authenticate approval.
See the fixture, the Sparkle example, and the data model.
items: stable IDs with akind,title,description,revision, and source citation.links: typed directed correspondence withproposed,recorded, orrejectedstatus. A recorded link needs rationale and evidence. It is a recorded assertion, not an authenticated approval. Bind endpoints usingsourceRevisionandtargetRevision; links to roots also need the report'ssnapshotDigest.concerns: source-grounded scenarios, questions and optional alternatives.decisions: append-only records ofaccepted,rejected, ordeferred, with reason, actor and date. Acceptance alone does not rewrite a specification.evidence: append-only reports targeting acheckitem, withid,outcome(passed,failed,not_run,unknown),sourceandsnapshotDigest. Their origin is alwaysexternal_reported; they are never promoted to a locally checked proof. The latest record for a check is used by policy.obligations: explicitroot_present,no_sorry,mapping_recorded, orreported_check_passedchecks. The last intentionally accepts a reported external result; CI must control the provenance of those inputs. Unsupported required checks are errors, not successful stubs.
A hazard can be linked from a mitigation with mitigates; a check can be
linked to that mitigation with verifies, then supplied with evidence from
an existing test or analysis. Merely registering a hazard or concern creates
no obligation. A missing connection is different from a failed check.
lake build eproof eproof_tests Tests.Fixture
lake exe eproof_tests
node tests/integration.mjs
node tests/graph.mjs
# Optional: requires local Chrome; set CHROME if its executable has another name.
node tests/browser.mjs out/fixture-map/report.htmlThe core tests cover graph cycles, transitive axioms, definition changes under unchanged statements, stale correspondence and evidence, policy removal, AI import boundaries, and HTML escaping. Integration tests exercise the real worker, CLI, reports and JSON protocol. The browser test checks navigation, concern entry, decision recording and dependency expansion.
LeanTEA supplies the typed HTML view, checked process arguments and SHA-256 for
the application. Its exact revision is pinned in lakefile.lean and
lake-manifest.json; it is compiled with the application's Lean 4.32.1 toolchain.
The standalone extractor and pure review core remain independent of LeanTEA.
Browser graph interaction is JavaScript;
the standalone worker uses one small Node native-crypto helper to avoid repeatedly forking
a large Mathlib environment. SHA-256 identifies exact extracted structures;
it is not a mathematical-equivalence test.
Implementation notes describe the current
limits and the relationship to the larger design in spec.md.