hraness
Theme
Appearance

lean: proving the books balance before the tests run

a proof checker as a build step

by hraness · drafted with ai assistance

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

A Lean proof can sit in a shipping product as one more build step: CI checks a small theorem the way it runs a test, and a failed proof blocks the release. The laws worth proving this way are the ones you can state in a line and still get wrong in a hundred ways, such as “the books balance” or “the quorum arithmetic adds up.” Tests probe those laws on examples. A proof checks them for every input.

a proof covers every input

A proof assistant such as Lean takes the statement “for every ledger of this shape, debits equal credits” and produces a derivation that a mechanical checker accepts or rejects. Once the checker accepts it, the claim holds for every input the theorem covers, including the ones no test happened to pick.

A test is a sample and a proof is a census. Teams that treat either as a replacement for the other end up proving the wrong theorem or testing the same case a thousand times.

which laws get proved

The portfolio proves only laws that are expensive to get wrong and cheap to formalize.

Gobstopper keeps transcript invariants in Lean. Its vault holds copies of agent sessions, and the claim that compaction preserves a transcript’s structure is a property of the transformation rather than of any one session, so it belongs in a theorem. Lean states the structural law, Rust implements the transform, and a correspondence check ties the two together.

vhalla’s quorum reasoning has the same shape. A delivery that claims member acceptance must satisfy arithmetic over how many members acknowledged what. An off-by-one in quorum counting is a classic distributed-systems hole, and it suits a proof checker well: a small statement, quantified over all inputs, with no environment to model.

The algal-cloud money laws follow the same logic. If a ledger of holds and captures is ever to hold real value, “debits equal credits” should be a theorem. That work is a spike, and algal-cloud is not a launched product.

how it runs in ci

The proofs live beside the code they constrain, CI runs the checker with a time budget, and a failed proof blocks a merge like a failed test. The checker is deterministic: the same proof always checks or always fails, so there are no flaky proofs to triage.

A proof that “the transcript transform preserves structure” means nothing unless the Rust code implements that transform. The projects keep a correspondence layer for this: the Lean statement names the law, the implementation names the function that claims it, and a test pins the two together so neither drifts without a failure.

what a proof leaves out

A proof is only as good as its statement.

It does not cover code it does not model. The checker verifies the theorem, not the binary. If the implementation diverges from the model, say with a different tie-break or a different bound, the proof still passes while the product is wrong. The correspondence layer exists to catch that, and it is a test rather than a proof.

It says nothing about claims outside the theorem. Gobstopper’s transcript proofs show that a preserved structure stays preserved. They do not show that the chosen compression was useful, that the vault resists an attacker, or that a session still resumes after the provider changes its API. Those need tests, threat review, and checks against the live service.

It costs upkeep. When the implementation’s model changes, the theorem may need rewriting, and a stale proof is worse than none because it still looks like evidence. Keeping each theorem small and close to its code makes the upkeep manageable: one law in one place, checked on every build, and deleted with the feature it covers.

Lean holds the proofs for Gobstopper and the vhalla quorum arithmetic, and nowhere else in this series. Soundfish and GhostGet rely on other techniques covered in the lessons that follow.

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.