Skip to content

Review fixes for staged channels - #4

Open
MauroToscano wants to merge 17 commits into
pr2-staged-channelsfrom
pr2-review-fixes
Open

MauroToscano wants to merge 17 commits into
pr2-staged-channelsfrom
pr2-review-fixes

Conversation

@MauroToscano

Copy link
Copy Markdown

Review fixes for #2, into pr2-staged-channels. Merge #3 first.

The branch starts by merging #3 into pr2-staged-channels, which also brings #2 up to the
current head of #1 (ad6d07dc). The merge is clean. So the diff here also shows #1's last four
commits and #3. This PR's own changes are the commits after the first merge.

Names, following REVIEWERS.md: the theorems assume StagedRequirements(On), which staged
did not name.

  • 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 the file called them. Two smaller changes:

  • the guarantee theorems state their balance as witness.BalancedChannels N;
  • Stage drops an unused [FiniteField F].

Example: Clean/Examples/RangeCheckedCount.lean, the shape the module doc describes.

  • A consumer pulls from a counted doubles channel with a multiplicity it range-checks on a byte
    Lookup.
  • OrderedChannelRefl fails for it, and tableSoundness goes through
    tableSoundness_of_stagedRequirements.
  • Axioms: propext, Classical.choice, Quot.sound.
  • Witness generation is declared but not run.

Docs:

  • The module doc said OrderedChannel rules out requirements that follow from guarantees on other
    channels. What it rules out is owing requirements on a channel the table also pulls from.
  • The module doc now says what the staged theorems don't cover: they assume an empty verifier, and
    there is no staged addVm_soundVmChannel_of_soundChannels.
  • Docstrings are tightened throughout. Each commit message lists what was stale.

Verified on this branch merged with upstream main (71cd9a32):

  • lake build --wfail and lake build CleanTests pass.
  • The only warnings are the existing sorrys in TestCircuitProofStart.lean.
  • CI's blank-line check passes.

Not done: the message-class (…On) API still has no in-tree user.

Once this merges, #2's description is stale wherever it names the four renamed theorems.

jotabulacios and others added 17 commits November 16, 2026 12:22
Five docstrings, no change to any proof.

`exists_logUpBalanced_not_matchedUpTo` opened by calling the bound of `matchedUpTo`
necessary and described the general case of many interactions, while its hypothesis
`ringChar F ≤ 2 * N` confines it to fields no larger than `2 * N` and the list it builds
has length `2`. It now states what it proves, and a closing paragraph says what it leaves
out: `L` multiplicities in `[1, N]` reach every sum between `L` and `L * N`, so the same
counterexample exists on `L` interactions in a field with `L ≤ ringChar F ≤ L * N`, and
that version is not proved here.

`countUpTo_of_val` had no stated purpose. It is the step from what a chip knows about its
multiplicity, `mult ≠ 0` and `mult.val ≤ N`, to the requirement a counted pull owes, and
it is stated over `ZMod p` because that is where `mult.val` exists.

`Channel.counted` now documents the invariant behind the shared name: witness generation
tallies interactions by channel name and the generation modes take the plain `Channel`,
so a counted channel under a new name would stop generating rows, and an `Ensemble`
admits at most one channel of a given name.

`counted_consistentUpTo_of_le` says why it is a theorem rather than an instance, and what
to do instead: supply it with `haveI` before `SoundEnsemble.markFinished`, whose
consistency argument is an instance argument that leaves no place for a `simp` step.

`CountedSquares` pointed at `Ensemble.tableSoundness_of_stagedOn`, which this branch does
not define. The sentence now describes the finishing order it means without naming it.
`Balance.logUp` leaves `pullBound` at `1` and still wrote `matchedUpTo_of_balanced` out
through `LogUpBalanced.matchedUpTo`, where the field's default proof
`BalancedInteractions.matchedUpTo_one` already closes it. `Balance.multiset` beside it
takes that default, so the two checks disagreed for no reason, and the claim that an
existing check compiles untouched reads better when the main one is such a check.

Nothing observable changes: the field is a `Prop`, so no user of `Balance.logUp` can
depend on which proof stands there. `LogUpBalanced.matchedUpTo` keeps the caller it was
written for, the bound of `Balance.logUpUpTo`.
Two docstrings, no change to any proof.

`exists_logUpBalanced_not_matchedUpTo` said that `ringChar F ≤ 2 * N` confines the
statement to fields no larger than `2 * N`. It bounds the characteristic, and a field of
characteristic `p` may have `p ^ k` elements. The closing paragraph also gave the general
shape as `L ≤ ringChar F ≤ L * N`; at `L = ringChar F` the list has length `ringChar F`
and so no longer passes a bound on the length alone, which is what it has to pass to be a
counterexample to that bound. The inequality is now strict.

`Channel.counted` said that `channel.counted 2` and `channel.counted 3` are distinct
`RawChannel`s. Over `ZMod 2` the two bounds describe the same multiplicities and the two
values are equal, so they may denote different channels rather than must. The paragraph
also read as if at most one of them could belong to an ensemble, which does not hold when
they are equal; what `unique_channel_names` rules out is a second entry under a name that
is already taken.
The consumer of the example had no padding row, so a demand table that fell short of its
target height would have been padded with the generator's default of `0`. Away from
characteristic `2` that does not satisfy the consumer's one constraint,
`(count - 1) * (count - 2) = 0`. The component now carries a padding row that pulls, at
multiplicity `1`, the one message the provider ever pushes.

A padding row that interacts has to be answered, and the test now shows that it is. The
existing run never pads, because its consumer table has two rows, so the new scenario
builds the state directly: three consumer rows against four provider rows emitting six
pushes between them, which balances, and whose consumer `ComponentState.targetHeight`
asks for four. After `padAndBalance` the consumer holds four rows, the constraints, the
balance and the interaction bound all hold, and the multiplicity of the provider row that
`rowOf` maps the message to has risen from `2` to `3`, which is the push that covers the
padding row's pull.

Both scenarios go through the same `constraintsHold` and `channelsBalanced` as the
existing run, by way of the tail of `generateValid`, rather than a restatement of them.
The existing run is unchanged and still pins `[2, 4]`.
…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.
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.

2 participants