Skip to content

Prove table soundness from a finishing order of channels and of message classes - #2

Merged
nicole-graus merged 18 commits into
pr1-counted-pullsfrom
pr2-staged-channels
Nov 19, 2026
Merged

nicole-graus merged 18 commits into
pr1-counted-pullsfrom
pr2-staged-channels

Conversation

@jotabulacios

@jotabulacios jotabulacios commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #1: the base of this PR is pr1-counted-pulls, so the diff below is this PR's own work —
one new file, plus 40 lines of Balance.lean and one import.

Why

OrderedChannel orders tables: a table may not both pull from a channel and owe requirements on
it. Two shapes a VM needs 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. The ALU bus is the
example — a division table pulls the LT and MUL results it needs and pushes its own DIVREM
results, all on one bus. 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:
LT pulls IS_HALF with multiplicity μ, and μ ≤ 255 is known only because the same table
pulls ARE_BYTES[μ, 0]. This one does have a workaround, unrolling the counted pull into N pulls
of multiplicity one, at N interactions per row instead of one.

This PR orders channels, and then stages: a channel together with a class of its messages.
finished lists them newest 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), so a stage balances by itself; a whole channel is the stage whose
class is every message.

What

  • Component.RequirementsAfter / StagedRequirements, with
    Ensemble.channelGuarantees_of_staged and Ensemble.tableSoundness_of_staged.
  • A refinement down to message classes: a Stage is a channel together with a class of messages, so
    one channel can be finished in several steps (byte lookups before the rows that use them).
    RequirementsAfterOn / StagedRequirementsOn, with guaranteesOn_of_stagedOn and
    tableSoundness_of_stagedOn.
  • BalancedUpTo.filter_msg in Balance.lean: balance holds message by message, so it restricts to
    any class of messages.

Both staged theorems take their per-channel balance from
EnsembleWitness.balancedChannels_of_balanced, the same named step that OrderedChannel.lean and
Vm.lean use, rather than inlining the derivation over the ensemble's channels.

Both forms are kept: the plain one is the simpler statement for an ensemble whose channels finish
whole, the staged-on one is what a VM ensemble needs.
requirementsAfterOn_of_requirementsAfter relates them.

Scope

Both theorems require ens.verifier = .empty F PublicIO. For an ensemble of tables this is free:
Ensemble.verifier defaults to the empty program, so the hypothesis is discharged by rfl. It is
not free for a VM. Ensemble.addVm propagates the VM's verifier, which pushes the initial state
and pulls the final one on the very channel being staged, and neither StagedRequirements nor
StagedRequirementsOn says anything about what a verifier owes — the hypothesis is what lets the
proofs use interactionsWith_of_verifier_empty. So the finishing order covers table ensembles,
while OrderedChannel, which carries OrderedChannelRefl channel ens.verifier, remains the path
that handles a verifier. Lifting the restriction means stating what a verifier owes on a staged
channel, which this PR does not do.

Checks

  • lake build clean, zero warnings.
  • lake build CleanTests passes.
  • No sorry, no native_decide in this PR's own files.

Open point

tableSoundness_of_staged concludes only ens.TableSoundness balance. The per-channel guarantees
it proves on the way are exported separately as channelGuarantees_of_staged /
guaranteesOn_of_stagedOn, which is what a caller that needs both uses.

…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.
…st are.

`BinaryFibonacci`, `FibonacciVm` and `OpcodeVm` each keep their ensemble and its generation test
side by side as `Ensemble.lean` and `WitnessGenerationTest.lean` in a directory of their own.
`CountedSquares` now does the same. Only the paths change: the imports in `Clean.lean` and
`Clean/Test.lean`, the test's own imports, and the path the example's module doc cites.
REVIEWERS.md asks a theorem's name to state its conclusion and then, after `_of_`, its hypotheses
in order, each part naming a declaration of the statement.

- `countUpTo_of_val` assumes `mult ≠ 0` and `mult.val ≤ N`, and is now
  `countUpTo_of_ne_zero_of_val_le`.
- `countUpTo_of_one_or_two` assumes `(c - 1) * (c - 2) = 0`, not a disjunction, and is now
  `countUpTo_of_sub_one_mul_sub_two_eq_zero`.
- `partialBalancedChannel_of_balancedInteractions` has assumed `BalancedUpTo N` since the bound was
  threaded through, and is now `partialBalancedChannel_of_balancedUpTo`.
- `partialBalancedChannel_of_balancedChannel` and `verifierChannelGuarantees_of_tableRequirements`
  state their balance hypothesis as `witness.BalancedChannel N channel` again, the abbreviation
  they were written against, rather than its unfolding. The two are definitionally equal, so no
  caller changes.

`RawChannel.eq_false_of_name_ne` moves above `namespace Channel`, so it no longer needs `_root_`.
doc/conventions.md (§4) asks new simplification lemmas to go into `circuit_norm` only: "We do not
modify the default `[simp]` set." `Balance.logUp_pullBound`, `Balance.logUpUpTo_pullBound` and
`Balance.multiset_pullBound` were tagged `@[simp, circuit_norm]`; they are now `@[circuit_norm]`,
and their docstrings name `circuit_norm` alone. Every proof that reduces a `pullBound` already
passes `circuit_norm`, so nothing else changes.
…oes.

Docstrings only, no change to any proof.

- `Channel.counted`: a counted channel under a new name would not silently stop generating rows.
  No component would answer its interactions, so generation fails with `unhandledImbalance`. A
  second channel under a taken name fails the `fresh` argument of `SoundEnsemble.addChannel`,
  which is how in-tree ensembles add channels, or `unique_channel_names` for an `Ensemble` built
  directly.
- `counted_consistentUpTo_of_le`: `haveI` is one way to supply it. Passing it explicitly through
  `@` to `SoundEnsemble.markFinished` works too.
- The `Channel.counted` module doc says how to finish under a bound above `N`.
- `Balance.logUpUpTo`: the bound `count * N < ringChar F` applies to every channel of the ensemble,
  counted or not, because `Ensemble.interactionsFit` applies `fits` to each channel. The PR's
  Extraction section already said so; the docstring now does too.
- `exists_logUpBalanced_not_matchedUpTo`: the two-pull sentence now includes `2 ≤ N`. Without it,
  `N = 1` over `ZMod 2` meets the stated conditions, yet the list has length `2 = ringChar F` and
  fails the bound on the length, the boundary the next paragraph excludes.
- `countUpTo_of_ne_zero_of_val_le`: a range check gives `mult.val ≤ N`, and `mult ≠ 0` comes from
  splitting off the requirement's `mult = 0` case. The check does not give both.
- `CountedSquares`: `counted_not_consistent` does not show that a row free to claim any
  multiplicity breaks the channel. Both pulls of that counterexample meet their obligation, and
  what fails is the plain balance premise. The module doc now gives the row-level reason, a pull
  at `-1` counted as a push, and cites the theorem for the balance-check half.
- `CountedSquares`: generation does not split a row at `N`, so a chip that counts its demand in a
  multiplicity cell and pulls with it fails its constraint past `N`. The consumer here pulls a
  fixed count per row.
- Generation test: the three runs make `6`, `7` and `8` interactions, and the padding section's
  first scenario checks the unpadded state before the second one pads it.
The README's "Organization" section listed neither `CountedChannel.lean` nor the bound a `Balance`
now carries. The `Balance.lean` paragraph gains a sentence on `pullBound`, `Balance.logUpUpTo` and
`RawChannel.ConsistentUpTo`, and `CountedChannel.lean` gets a paragraph of its own pointing at
`Clean/Examples/CountedSquares`.
…nce by name.

REVIEWERS.md asks each part of a theorem's name to name a declaration of its statement. `staged`
and `stagedOn` name none: what the four theorems assume is `Component.StagedRequirements` or
`Component.StagedRequirementsOn`. Following `tableSoundness_of_soundChannels`, which drops the
namespace of `Ensemble.SoundChannels`, they become:

- `channelGuarantees_of_staged` → `channelGuarantees_of_stagedRequirements`
- `tableSoundness_of_staged` → `tableSoundness_of_stagedRequirements`
- `guaranteesOn_of_stagedOn` → `guaranteesOn_of_stagedRequirementsOn`
- `tableSoundness_of_stagedOn` → `tableSoundness_of_stagedRequirementsOn`

Nothing outside this file calls them yet, so this is the cheapest time to rename.

The two guarantee theorems took their balance as the unfolded
`∀ channel ∈ ens.channels, BalancedUpTo N (witness.interactionsWith channel)`. That is
`witness.BalancedChannels N`, which is what `balancedChannels_of_balanced` produces and what the
two soundness theorems pass, so they now say so. The proofs are unchanged.

`Stage` drops its `[FiniteField F]` argument, which neither of its fields needs.
Nothing outside `StagedChannels.lean` used the new theorems. `Clean/Examples/RangeCheckedCount.lean`
is the shape the module doc describes, at the scale of an example. A consumer needs `y = x + x` up
to `255` times, pulls it once from a counted `doubles` channel with that multiplicity, and
range-checks the multiplicity by pulling it from a byte `Lookup`. The counted pull's requirement,
`count = 0 ∨ CountUpTo 255 count`, follows from the consumer's guarantee on `bytes` and from no
constraint of its own.

- An `example` shows that `OrderedChannelRefl` fails for the consumer on `doubles`, so
  `OrderedChannel` cannot order the ensemble.
- `consumer_requirementsAfter` is the one hand-written step: the requirement on `doubles` from the
  guarantee on `bytes`, read off the row operations.
- `tableSoundness` proves every table sound under `Balance.logUpUpTo 255` through
  `Ensemble.tableSoundness_of_stagedRequirements`, finishing `bytes` before `doubles`.

The step from a range-checked byte to the requirement goes through
`countUpTo_of_ne_zero_of_val_le`, which now has the in-tree caller its docstring describes.
Witness generation is declared but not exercised, as the module doc says.
Docs only, no change to any proof.

- The module doc said `OrderedChannel` rules out a table whose requirements on a channel follow
  from guarantees on other channels. It does not: `SoundEnsemble.addTable` takes requirements on
  an unfinished channel from guarantees on finished ones. What it rules out is a table that owes
  requirements on a channel it also pulls from, which is the case here.
- `LT`, `IS_HALF`, `ARE_BYTES`, `MUL` and `DIVREM` are not in this repository. They are now
  labelled as a zkVM's ALU, and the module doc points at `Clean/Examples/RangeCheckedCount.lean`
  for an in-tree instance.
- The module doc now states the scope. Both soundness theorems assume an empty verifier, so they
  do not cover an `Ensemble.addVm` ensemble, and there is no staged counterpart of
  `addVm_soundVmChannel_of_soundChannels` yet.
- `tableSoundness_of_stagedRequirementsOn` said "every pull" lies in a finished stage; its
  `covered` hypothesis asks this of every message of every channel a table has guarantees on.
- `Component.RequirementsAfterOn` gets a docstring.
- `activeCount_filter_msg` carried the docstring of `BalancedUpTo.filter_msg`; it now says what it
  proves.
- `Clean/Air/README.md` counts three soundness arguments, not two, and describes
  `StagedChannels.lean`.
Comments and docs only; with comments stripped, the code is unchanged.

Stale or wrong:
- `MatchedUpTo` cited `exists_push_of_pull` for `N = 1`; it is `matchedUpTo_one`.
- `pullBound` was "the largest" multiplicity matched, which nothing proves.
- `countUpTo_of_ne_zero_of_val_le` claimed to be how a circuit discharges a counted pull's
  requirement; it is stated as what it gives, with no claim about callers.
- The `example` after the counted instance spoke of any concrete balance check; it is
  `Balance.logUpUpTo`, which is reducible, unlike `Balance.logUp`.
- `ProviderInput.mult` said how many pulls a row answers; the row pushes `mult + 1` times.
- `consumerComponent` said one row per pushed square, then that two rows answer four pushes.
- The README called `Channel.counted N` a typed channel; it is a `RawChannel`. Its "every pull is
  matched" now says multiplicity `1`, next to the counted pulls of the same paragraph.

Shorter: history wording ("before counted pulls", "already had") is gone, the `_one` lemmas say
what they equate, and the module docs no longer repeat the docstrings beneath them.
`counted_not_consistent` and `exists_logUpBalanced_not_matchedUpTo` keep every hypothesis and the
range their counterexamples need, in about half the lines.
Comments and docs only.

Stale or wrong:
- `Component.StagedRequirements` cited `finished`, which is not a parameter.
- `stagedRequirements_of_forall` said "from one of the two lemmas above"; its hypothesis takes any
  `RequirementsAfter`.
- `Table.RequirementsAfterOn` left out the assumptions and constraints it also takes.
- `DoublerInput.mult` and `doublerComponent` counted pulls, not pulled multiplicity.

The module doc says when to reach for a finishing order and what it does not cover, in about half
the lines: the zkVM ALU aside moves to the stages section, which is the one it motivates. The
example's module doc says why its components declare a generation it never runs.
@nicole-graus
nicole-graus merged commit e30c5c4 into pr1-counted-pulls Nov 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants