hraness
Theme
Appearance

lean: proving the books balance before the tests run

a proof checker as a build step

drafted with ai assistance by ben guo

the rest of this lesson is free: add your email to keep reading.

Some invariants are simple enough to state in one line and simple enough to get wrong in a hundred ways: the books balance, the transcript cannot be forged, the quorum arithmetic adds up. Tests probe such invariants on examples. A proof checks them universally. The interesting engineering question is where a proof fits in a shipping product without becoming a research project that blocks releases.

the claim

A proof assistant such as Lean takes the statement "for every ledger of this shape, debits equal credits" and produces a derivation a mechanical checker accepts or rejects. Once the checker accepts, the claim is true for every input the theorem covers: not on the examples a test happened to pick, but on all of them.

That is a different kind of evidence than a test. A test is a sample; a proof is a census. The two are complementary, and treating either as a replacement for the other is how teams end up proving the wrong theorem or testing the same case a thousand times.

what a lean proof buys

The portfolio's pattern is narrow and deliberate: proofs over the laws that are expensive to get wrong and cheap to formalize.

Gobstopper keeps transcript invariants in Lean. Its vault holds copies of agent sessions; the claim that compaction preserved a transcript's structure is a property of the transformation, not of any particular session, so it belongs in a theorem. The Lean side states the structural law; the Rust side implements the transform; a correspondence check keeps the two honest.

vhalla's quorum reasoning is the same shape. A delivery that claims member acceptance has to satisfy arithmetic over how many members acknowledged what. Off-by-one in quorum counting is the classic distributed-systems hole, and it is exactly the kind of arithmetic a proof checker is good at: small statement, universal quantification, no environment.

The spike for algal-cloud's money laws follows the same logic: if a ledger of holds and captures is ever to hold real value, "debits equal credits" should be a theorem, not a wish. That work is a spike, not a launched product; the claim here is about the technique, not the product.

how it runs in ci

The working pattern treats the proof checker as a build step with a budget. The proofs live beside the code they constrain; CI runs the checker the way it runs tests; a failed proof blocks the same way a failed test does. The important operational property is that the checker is deterministic: the same proof either always checks or always fails, so there is no flaky-proof category to triage.

The equally important property is the correspondence boundary. A Lean proof about "the transcript transform preserves structure" says nothing unless the Rust code actually implements that transform. The projects keep an explicit correspondence layer: the Lean statement names the law, the implementation names the function that claims it, and the test suite pins the two together so one cannot drift from the other silently.

the honest limits

A proof is only as good as its statement, and that is where the honest accounting starts.

First, a proof does not cover code it does not model. The Lean checker verifies the theorem, not the binary. If the implementation diverges from the model (a different tie-break, a different bound), the proof still passes while the product is wrong. This is why the correspondence layer exists, and why it is itself a test, not a proof.

Second, a proof says nothing about the parts left outside the theorem. Gobstopper's transcript proofs say a preserved structure stays preserved; they do not say the compression chosen was useful, the vault unreadable to an attacker, or the session resumable after the provider changed its API. Those are different claims needing different evidence: tests, threat review, live qualification.

Third, proofs have a maintenance price. Every time the implementation's model changes, the theorem may need rewriting, and a proof that rots is worse than none because it still looks like evidence. The discipline that makes it workable is keeping theorems small and close to the code: one law, one place, checked every build, and retired with the feature it covers.

The last limit is scope. Lean is where Gobstopper and the vhalla quorum arithmetic keep their proofs; it is not a blanket claim across the portfolio. Soundfish and Ghostget get their correctness from other machinery in this series, and that is the point of the series: each technique earns its place on a specific class of claim.

keep reading: free for subscribers

the rest of this lesson is free. enter your email to subscribe, and every subscriber lesson unlocks in this browser.

already subscribed? enter the same email to unlock.