Repository navigation
Prove table soundness from a finishing order of channels and of message classes - #6
Draft
jotabulacios wants to merge 20 commits into
Draft
jotabulacios wants to merge 20 commits into
jotabulacios wants to merge 20 commits into
Conversation
jotabulacios
force-pushed
the
pr2-upstream-v2
branch
from
November 19, 2026 15:05
7840e1b to
c1ba262
Compare
…ge classes. A table's requirements on a channel may follow from its guarantees on channels finished before it, not only from its constraints. A counted pull needs this: its multiplicity bound comes from a lookup on another channel, which OrderedChannel can't express. Component.StagedRequirements states it for a finishing order, and Ensemble.tableSoundness_of_staged proves soundness by induction from the oldest channel. A stage is a channel together with a class of its messages. A table that pulls some messages of a channel and pushes others, like a division chip pulling LT and MUL results and pushing DIVREM results on the ALU bus, is not a cycle when the classes are finished in order. Ensemble.tableSoundness_of_stagedOn proves soundness from a finishing order of stages; balance is message by message, so each stage balances by itself (BalancedUpTo.filter_msg). Genuine cycles still have no valid order.
…ma too. Both staged soundness theorems inlined the same derivation over the ensemble's channels that `balancedChannels_of_balanced` names, which is the pattern just removed from `OrderedChannel.lean` and `Vm.lean`. All four call sites now go through the lemma, and `Balance.balancedUpTo_of_balanced` is applied in one place.
…eady does. `Component.StagedRequirements` has `@[circuit_norm]` nil and cons lemmas, so a caller discharging `∀ component ∈ ens.tables, component.StagedRequirements finished` with `simp [circuit_norm]` gets the list unfolded. `StagedRequirementsOn` had neither, so the identical proof over stages left a stuck goal.
The file held two inductions of the same shape, `channelGuarantees_of_staged` over a list of channels and `guaranteesOn_of_stagedOn` over a list of stages, forty-nine lines each, with a soundness corollary apiece. A whole channel is the stage whose class is every message, which the section already said in prose, so the channel pair is the stage pair read through that correspondence and does not need an induction of its own. `Stage.ofChannel` names the stage that is a whole channel, and `Component.stagedRequirementsOn_of_stagedRequirements` carries a finishing order of channels to the finishing order of those stages, one step at a time through `requirementsAfterOn_of_requirementsAfter`, which the file already had. On top of those, `channelGuarantees_of_staged` is ten lines and `tableSoundness_of_staged` is seven. Both statements are unchanged, so callers do not notice. What the stage theorem asks for and the channel one does not is `covered`, that every pull of every table lie in some finished stage; `subset_finished` discharges it, since the stage of a whole channel accepts every message. The stage theorems themselves are untouched.
…corollary. `REVIEWERS.md` asks that each underscore-separated part of a theorem name correspond to a declaration in its statement rather than to an invented description, and that nothing inside a namespace be qualified with that namespace. `staged` and `stagedOn` named no declaration. The hypotheses are `Component.StagedRequirements` and `Component.StagedRequirementsOn`, so the three theorems become `guaranteesOn_of_stagedRequirementsOn`, `tableSoundness_of_stagedRequirementsOn` and `tableSoundness_of_stagedRequirements`, which is the shape `Ensemble.tableSoundness_of_soundChannels` already has in `OrderedChannel.lean`. `Stage.ofChannel_channel` named the projection of a constructor inside out; Mathlib reads it outside in, so it is `Stage.channel_ofChannel`. Six references were qualified with the namespace of the declaration they appear in. The file was inconsistent about it: `stagedRequirementsOn_of_stagedRequirements` already called itself by its bare name on one line and qualified a sibling on the next. The `Table.` prefixes inside `Component.*` lemmas stay, since those are a different namespace. `channelGuarantees_of_staged` had no caller, in this repo or in any consumer: the staged soundness theorem is reached through `tableSoundness_of_stagedRequirements`, which does not go through it. It is removed rather than kept as an entry point nobody enters.
…annel orders. The module docstring named `LT`, `IS_HALF` and `ARE_BYTES`, and the stages section named `LT`, `MUL` and `DIVREM` on an ALU bus. No circuit in this repo carries those names, so they ask the reader to take the motivation on faith. The counted pull of `Clean/Examples/CountedSquares` is the same shape and is in the tree: its multiplicity owes `CountUpTo N`, and a bound too large to constrain arithmetically has to come from a range check on another channel. The bus is described by what it is rather than by one VM's opcodes. The first sentence also said only half of what `OrderedChannel` requires. Its defining property is an order between tables, as `Clean/Air/README.md` puts it: every table that pushes to a channel comes before every table that pulls from it. "A table may not both pull and owe requirements" is a consequence, not the condition.
Its `covered` hypothesis asked that every possible message of every guarantee channel lie in some finished stage. The proof passes it to `Table.guarantees_of_guaranteesOn`, which only ever needs it at the pulls a table actually makes, and reconstructed the weaker form from the stronger one at the call site. It now asks for exactly that weaker form, which is the shape `Component.requirementsAfterOn_of_covered` already uses a few lines above, and the call site hands it over unchanged. An ensemble whose finished stages cover every message still discharges it; one whose last stage is not a catch-all now also can.
…yway. `Component.RequirementsAfterOn` quantifies over the interactions of a whole table, which is not the form a component's own `circuit_norm` lemmas produce. Every chip proving a staged obligation therefore starts by turning it into rows times the component's row operations, through `Table.forall_interactionsWith_iff`, `Component.interactions_eq` and `AbstractInteraction.eval_requirements`. `requirementsAfterOn_of_rowOperations` is that step, stated once. `stagedRequirementsOn_of_no_guarantees` is the other end: a component that receives no guarantee owes nothing on any stage, so a provider discharges its whole staged obligation in one application. The channel form already had `stagedRequirements_of_forall` for this shape; the stage form had nothing. Both were written against this API outside the library and are stated here over an arbitrary `FiniteField`, which is what they always needed; neither mentions the characteristic or the size of the field.
The Organization section documents every file in `Clean/Air/` and says the library provides two arguments for ensemble soundness. `StagedChannels.lean` is a third, so it gets a paragraph in the same register: what it orders, what `StagedRequirements` and `Stage` say, and which theorem concludes. The paragraph also records the two limits that a reader comparing it with `OrderedChannel.lean` will want stated. The staged argument is made for a whole ensemble at once, so it does not compose with the incremental `SoundEnsemble` builder; and it applies only when the verifier is empty, since neither predicate says what a verifier owes on a staged channel. `OrderedChannel.lean` was described as "a staged channel construction", which now names the wrong file. The sentence after it already states the property that defines it, an order between tables, so the word is dropped rather than replaced.
The paragraph said only that neither staged predicate says what a verifier owes. The hypothesis is doing two separate jobs. It makes every interaction on a stage come from a table, so that the requirements the induction establishes cover the whole list that `RawChannel.ConsistentUpTo.consistent` is applied to; and it discharges the verifier's own spec, which is owed even once the first is settled. `OrderedChannel.lean` handles them with `PartialBalancedChannel`, which tolerates interactions from outside the list it is stated for, and with `verifierChannelGuarantees_of_tableRequirements`. Naming both says what lifting the hypothesis would actually take.
Nothing in the repo used the staged soundness theorems, so the API had no in-tree consumer: a reader could see what `StagedRequirements` says but not what discharging it looks like, and the `circuit_norm` lemmas and the two `requirementsAfter_of_*` helpers were reached by nothing. `StagedSquares` is the smallest case that needs a finishing order. It reuses the squaring chip and the counted channel of `Clean/Examples/CountedSquares` and changes one thing: where that consumer discharges its pull's requirement with a constraint of its own, `(count - 1) * (count - 2) = 0`, this one pulls its count from a second channel. A chip provides that channel, and its own constraint is what pays for the guarantee. The consumer therefore owes a requirement it cannot pay from its constraints. Its `requirementsChannelsLawful` declares the channel rather than proving the requirement, and `consumer_requirementsAfter` pays it with the guarantee the consumer was handed on `counts`. That is the shape `OrderedChannel` cannot express: it orders tables, and no order of these three says where the bound comes from. `counts` finished before `squares` does say it. The ensemble is assembled as a plain `Ensemble` rather than through `SoundEnsemble`, which the staged argument does not compose with, and generation is not exercised.
`StagedSquares` could not generate. Its range chip emitted `mult + 1`, copied from the squaring chip of `CountedSquares`, where the `+ 1` is what seeds a run: that chip is `preallocated`, its rows exist before any demand and their multiplicity cells start at `0`. The range chip is `demand`, so a row is created only by a pull it has to answer and is born with that pull counted. The `+ 1` pushed once more than anyone pulled, and `generate` stopped with `unhandled channel imbalance on: counts`. The chip now emits the multiplicity as it stands, and the component gets a padding row that answers nothing: multiplicity `0`, and `c := 1` so that the chip's own constraint holds, which `0` would not. `WitnessGenerationTest.lean` pins the run at heights `[1, 4, 2]` with the constraints, the balance check and the interaction bound all satisfied. The example said only that generation was not exercised, which was true and beside the point: nothing ran it, so nothing could say it was broken. Now something does.
…hes one bus. `StagedSquares` orders whole channels, so half of this file had no consumer: `Stage`, `GuaranteesOn` / `RequirementsOn`, `RequirementsAfterOn`, the `requirementsAfterOn_of_*` helpers and `tableSoundness_of_stagedRequirementsOn` could be read but not seen at work. That half is the argument; the channel form is read off it. `SameBus` is the smallest case that needs it. One bus carries `(tag, a, b)` and guarantees `b = a * a` at `tag = 0`, `b = a⁴` at `tag = 1`. A squaring chip provides the squares. A fourth-power chip pulls a square and pushes a fourth power, on the same bus: its push owes `b = a⁴`, and one constraint of its own is not enough, because `z = y * y` says nothing about `x` until the bus says `y = x * x`. Ordering whole channels cannot express that — `powers` would have to come before itself. The two classes can: the squares are finished before the fourth powers, and the chip's only pull lies in the earlier one, which is what `requirementsAfterOn_of_covered` asks for. `chip_shape` is the step that says so, that every interaction the chip makes on the bus is its pull at `tag = 0` or its push at `tag = 1` and nothing else. Interactions are plain pushes and pulls here. Multiplicity is what `CountedSquares` is about and it is orthogonal to the ordering question. The ensemble is not generated. Telling the two classes apart during generation needs demand guards, which nothing in the tree exercises yet; `StagedSquares` is the staged example that generates, and its test pins the run.
The stage half of this file now has an example, but the shape it was written for is larger than either: lambda_vm, a RISC-V zkVM built on Clean, whose lookup channels admit a finishing order with exactly one cycle, an arithmetic bus that one table both reads and writes. Breaking that cycle with message classes is why `Stage` exists. Saying so is the answer to "where is this needed?", which `Clean/Circuit/ExpressionPolynomial` gives in the same way for leanerVM.
A second pass over the same review landed in `pr2-review-fixes`. Five of its decisions are better than this branch's and are taken here: - `Stage` carried a `[FiniteField F]` instance argument that neither of its fields needs; `RawChannel` itself takes none. Dropping it means `Stage.channel_ofChannel` has to `omit` the instance the section still introduces. - The balance hypothesis of the two guarantee theorems spelled out `∀ channel ∈ ens.channels, BalancedUpTo N (witness.interactionsWith channel)`, which is what `EnsembleWitness.BalancedChannels N` abbreviates and what `balancedChannels_of_balanced` produces. This branch had already taken the opposite decision one PR earlier, in "Keep using BalancedChannel where this branch had spelled it out", so spelling it out here was inconsistent with its own convention. - The module docstring said nothing about what the file does not cover. A reader opening it was not told that both soundness theorems assume an empty verifier, or that there is no staged counterpart of `addVm_soundVmChannel_of_soundChannels`. The analysis stays in `Clean/Air/README.md`; the file now points at it. - `Component.RequirementsAfterOn` was the one definition here without a docstring. - `activeCount_filter_msg` was documented with the file's slogan, "balance is message by message", which is already the docstring of `BalancedUpTo.filter_msg` below it. It now says what the lemma itself says.
…amples. The same review round, for the parts that only exist on this branch. Three docstrings described `channelsWithRequirements` instead of naming it, and `stagedRequirements_of_forall` referred to "one of the two lemmas above" — a positional reference that breaks silently if anything is inserted between them. Of the three soundness arguments `Clean/Air/README.md` lists, this was the only one naming no example, having two. `CountedSquares` now points at `StagedSquares` for the case its last paragraph describes. `countUpTo_of_ne_zero_of_val_le` said no example in this repo range-checks a multiplicity; `StagedSquares` does, by pulling a channel that guarantees `CountUpTo`. What no example does is range-check one by its `.val`. `Stage.channel_ofChannel` was `@[simp]`, which `doc/conventions.md` reserves: simplification lemmas go to `circuit_norm`. Its two callers say so now. `countUpTo_of_sub_one_mul_sub_two_eq_zero` follows its rename in the parent commit.
The module docstring says the consumer's requirement on `squares` is one that `OrderedChannel.lean` cannot express, because the consumer both pulls from that channel and owes requirements on it. `OrderedChannelRefl` states exactly that condition, so the claim is one `example` away from being machine-checked rather than asserted in prose, and it is the motivation for the whole construction. Taken from the parallel review round's `RangeCheckedCount.lean`, which is otherwise this example with a byte lookup in place of the `CountUpTo` channel.
jotabulacios
force-pushed
the
pr2-upstream-v2
branch
from
November 19, 2026 18:45
c1ba262 to
b749711
Compare
A row needs a fact up to `255` times, pulls it once with that multiplicity, and range-checks the multiplicity by pulling it from a byte table. The requirement the counted pull owes, `count = 0 ∨ CountUpTo 255 count`, then follows from the row's guarantee on `bytes` rather than from its constraints, which is what the hierarchy of `OrderedChannel.lean` cannot express: the consumer both pulls from `doubles` and owes requirements on it. This is the first caller of `countUpTo_of_ne_zero_of_val_le` in the repo, and the case the counted docstrings describe: a bound too large to constrain with a polynomial.
`RangeCheckedCount` range-checks a multiplicity by its `.val` against a byte table, so the docstring's claim that no example in this repo does no longer holds.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #5: the base of this PR is
pr1-upstream-v2, so the diff below is this PR's own work —one new file in
Clean/Air/, five example files, 44 lines ofBalance.lean, five imports, a testentry and a README paragraph.
Why
OrderedChannelorders tables: on each channel, every table that pushes comes before everytable that pulls, and no table does both. Two shapes break that.
The first has no workaround. A table that both pulls from a channel and pushes to it, on different
messages, is not a cycle: what it reads and what it writes are disjoint. A bus shared by several
operations is where this happens — a table that answers one operation by using the answers to
others pulls those and pushes its own, all under one channel name. Ordering whole channels cannot
express that, and giving each operation a channel of its own costs a channel per operation.
The second is a table whose requirements on one channel follow from its guarantees on another.
Clean/Examples/CountedSquares, from #1, is the case in miniature: its consumer pulls a squarewith multiplicity
countand owescount = 0 ∨ CountUpTo 2 count, which it pays with a constraintof its own,
(count - 1) * (count - 2) = 0. That only scales while the bound is small enough towrite as a polynomial. A chip counting to
255range-checks its multiplicity on a second channelinstead, and then no order of its tables says where the bound came from.
This PR orders stages: a channel together with a class of its messages.
finishedlists themnewest first, and a component's requirements on one may use its guarantees on those finished before
it. By induction from the oldest, every one's requirements hold, so by consistency its guarantees
hold, and every table's spec follows. Balance is message by message (
BalancedUpTo.filter_msg), soa stage balances by itself.
What
The stage form is the argument; the channel form is read off it.
Stage, a channel together with a class of its messages, withTable.GuaranteesOn/RequirementsOnandComponent.RequirementsAfterOn/StagedRequirementsOn. The soundness isEnsemble.guaranteesOn_of_stagedRequirementsOnandEnsemble.tableSoundness_of_stagedRequirementsOn.through that correspondence rather than a second induction:
Stage.ofChannelandComponent.stagedRequirementsOn_of_stagedRequirementscarry it over, andEnsemble.tableSoundness_of_stagedRequirementsis seven lines on top. The statement is keptbecause an ensemble whose channels finish whole is the simpler thing to say, and to use.
requirementsAfter_of_not_mem/requirementsAfter_of_guarantees_subset/stagedRequirements_of_forall, and their stagecounterparts, plus
requirementsAfterOn_of_rowOperations, which reads a stage's obligation onerow and one interaction at a time — the form a component's own
circuit_normlemmas produce —and
stagedRequirementsOn_of_no_guaranteesfor a component that receives no guarantee at all.BalancedUpTo.filter_msginBalance.lean: balance holds message by message, so it restricts toany class of messages.
Clean/Examples/StagedSquares: the second shape above, built. It reuses the squaring chip andcounted channel of
CountedSquaresand changes one thing — the consumer pulls its count from asecond channel instead of constraining it, so its requirement on
squaresfollows from itsguarantee on
counts, andcountsfinished beforesquaresis what says so. It generates, andits
WitnessGenerationTestpins the run.Clean/Examples/SameBus: the first shape, built. One bus carries(tag, a, b)and guaranteesb = a * aattag = 0,b = a⁴attag = 1. A fourth-power chip pulls a square and pushes afourth power on that one bus; its push owes
b = a⁴and one constraint of its own is not enough,because
z = y * ysays nothing aboutxuntil the bus saysy = x * x. Ordering wholechannels cannot express it —
powerswould have to come before itself — and the two classes can.This is what exercises
Stage,tableSoundness_of_stagedRequirementsOnand therequirementsAfterOn_*helpers.Clean/Examples/RangeCheckedCount: the second shape again, at a bound no constraint reaches. Arow needs a fact up to
255times, pulls it once at that multiplicity, and range-checks themultiplicity by pulling it from a byte table, so the requirement
count = 0 ∨ CountUpTo 255 countfollows from its guarantee onbytesrather than from its ownconstraints.
OrderedChannelcannot order it either: the consumer both pulls fromdoublesandowes requirements on it, which
OrderedChannelReflrules out, while finishingbytesbeforedoublesworks. It is the only caller ofcountUpTo_of_ne_zero_of_val_le, which thecounted-pulls PR states and nothing there needs.
the verifier's, so the stage's consistency gives the verifier's pulls their guarantees, from which
its spec follows. Its requirements on a stage are a hypothesis,
VerifierStagedRequirementsOn,which may use its guarantees on earlier stages, as a component's does. Its pulls owe nothing by
construction; its pushes owe the channel's guarantee for a value of the public input. Helpers:
verifierStagedRequirementsOn_of_not_memfor a verifier that pushes nothing on the finishedchannels, and
verifierStagedRequirementsOn_of_verifier_empty.Clean/Examples/StagedSquares/Verifier.lean: the tables ofStagedSquareswith a verifier. Oneverifier pulls its public input from
counts, and its spec is that pull's guarantee. Another alsopushes the input to
seenCounts, which a table reads; the table's spec rests on that push, whoserequirement the verifier pays with its guarantee on the earlier
countsstage.Clean/Air/README.mdgains a paragraph for the file, since its Organization section says thelibrary provides two arguments for ensemble soundness and this is a third.
Both staged theorems take their per-channel balance from
EnsembleWitness.balancedChannels_of_balanced, the same named step thatOrderedChannel.leanandVm.leanuse, rather than inlining the derivation over the ensemble's channels.Scope
Two limits, both deliberate.
No staged counterpart of adding a VM. The verifier is covered, but
Ensemble.addVm_soundVmChannel_of_soundChannelsstill takes the table-orderedSoundChannels.A VM's state channel is pulled and pushed by the same tables with circular requirements, which no
order of stages breaks; it needs the VM argument of
Vm.lean, fed with staged guarantees for thelookup channels. That is a separate piece of work.
It does not compose with
SoundEnsemble. The argument is made for a whole ensemble at oncerather than built up table by table, so
StagedSquaresassembles itsEnsembledirectly. Relatingthe two is a separate piece of work.
Checks
lake build --wfailclean, standalone and on top of Allow pulls of multiplicity up to N, and a channel that uses them #1.lake build CleanTestspasses.#print axiomson every new theorem:propext,Classical.choice,Quot.soundonly.sorry. Nonative_decidein the library: the only occurrences are theexamples ofStagedSquares/WitnessGenerationTest.lean, as in the otherWitnessGenerationTestmodules.