Skip to content

Allow pulls of multiplicity up to N, and a channel that uses them - #1

Merged
nicole-graus merged 42 commits into
pr-base-upstream-mainfrom
pr1-counted-pulls
Nov 19, 2026
Merged

nicole-graus merged 42 commits into
pr-base-upstream-mainfrom
pr1-counted-pulls

Conversation

@jotabulacios

@jotabulacios jotabulacios commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Why

A table that answers k identical lookups with one row pulls the facts it relies on with
multiplicity k. This is the ordinary shape of an arithmetic chip, not a corner case: one that
splits a result into two halves range-checks the limbs of both with the sum of the two
multiplicities, and with byte-sized limbs that sum reaches 2 * 255. Unrolling such a pull into
k pulls of multiplicity one is always possible, since k is fixed when the circuit is defined,
but costs k interactions on a row where one would do.

Today such a channel cannot be finished in a SoundEnsemble: consistency rests on
BalancedInteractions.exists_push_of_pull, which matches a pull only when its multiplicity is 1,
so a counted pull has no path to its guarantee.

This is not a gap in the proof. Under plain LogUp balance a counted channel really is unsound, and
Channel.counted_not_consistent builds the counterexample: a pull of multiplicity N and a pull of
multiplicity 1, both of a message nobody pushes. BalancedInteractions holds of that pair, since
exists_push_of_pull counts the pull of N as a push of the message — its multiplicity is neither
0 nor 1 — and so matches the pull of 1. The counted channel reads both as pulls and hands its
guarantee to the pull of 1, which is false. Matching counted pulls needs a stronger premise from
the balance check, so the check has to say how high a multiplicity it covers.

Raising that bound is not free, and exists_logUpBalanced_not_matchedUpTo says what it costs. Once
ringChar F ≤ 2 * N, two pulls of multiplicities N and ringChar F - N sum to the characteristic:
the field sums see a balanced list, its length stays below the characteristic, and nothing was
pushed anywhere. A bound on the interaction count alone, which is all Balance.logUp asks, is
therefore not enough once pulls may count, and this is why Balance.logUpUpTo N asks for
count * N < ringChar F as well. The theorem shows the weaker condition insufficient; it does not
claim the stronger one is the weakest that works.

What

Balance gains two fields:

  • pullBound : ℕ := 1 — the largest pull multiplicity the check matches with a push.
  • matchedUpTo_of_balanced, with a default proof for pullBound = 1
    (BalancedInteractions.matchedUpTo_one). Every existing check compiles unchanged, and a check
    that raises pullBound without discharging the field gets a type error, not a wrong default.

New in Clean/Air/Balance.lean:

  • Interaction.PullUpTo / PushUpTo, MatchedUpTo N, BalancedUpTo N, with of_perm, nil,
    mono.
  • CountUpTo N mult, with a docstring that states its scope: it says mult is named by a natural
    between 1 and N, and nothing about the field, so CountUpTo 2 (0 : ZMod 2) holds. The bound
    relating N to the characteristic is not carried here, because logUpUpTo already excludes the
    case.
  • LogUpBalanced.matchedUpTo: field-sum balance matches pulls of multiplicity up to N whenever
    interactions.length * N < ringChar F.
  • exists_logUpBalanced_not_matchedUpTo: a bound on the interaction count alone is not enough, by
    the counterexample above, which covers two interactions and so characteristics up to 2 * N.
  • Balance.logUpUpTo N: LogUp with pullBound := N, whose fits additionally asks
    count * N < char F.
  • RawChannel.ConsistentUpTo N, generalizing Consistent (which is ConsistentUpTo 1).
  • balancedUpTo_one_iff, Balance.logUpUpTo_one and RawChannel.consistentUpTo_one_iff: at bound
    1 each of the three new definitions is the one it generalizes, so an ensemble that does not
    count keeps exactly the premise its soundness proofs had before.
  • @[simp, circuit_norm] pullBound lemmas for logUp, logUpUpTo and multiset, so that
    simp and circuit_norm can reduce a ConsistentUpTo balance.pullBound goal.
  • Balance.logUpUpTo is @[reducible]. SoundEnsemble.markFinished takes
    [channel.ConsistentUpTo balance.pullBound] as an instance argument, and the counted channel's
    instance ties that bound to the channel's own N, so synthesis has to see
    (logUpUpTo N).pullBound as N. A simp lemma plays no part in synthesis, and an instance
    argument leaves no place to run one, so without this finishing a counted channel does not
    elaborate. A plain channel is unaffected: its instance comes from
    [Consistent] → ConsistentUpTo N with N free.

New file Clean/Air/CountedChannel.lean:

  • Channel.counted N channel — channel with pulls of multiplicity up to N: a pull of
    multiplicity 1 ≤ k ≤ N gets the guarantee, an active push owes it.
  • pulledUpTo / emittedUpTo interactions with their circuit_norm lemmas.
  • (channel.counted N).ConsistentUpTo N as an instance, counted_consistentUpTo_of_le for larger
    bounds, counted_one_guarantees_iff / counted_one_requirements_iff at bound 1, and
    counted_not_consistent for the counterexample above.

New file Clean/Examples/CountedSquares.lean: a squaring chip that constrains y = x * x and
pushes the pair, and a consumer that needs the same square once or twice and pulls it once with that
multiplicity. The consumer's constraint on its count is what discharges the pull's requirement
count = 0 ∨ CountUpTo 2 count. The two are assembled into a SoundEnsemble over
Balance.logUpUpTo 2, with the channel finished between them, and tableSoundness concludes for
every table of it.

New file Clean/Examples/CountedSquaresWitnessGenerationTest.lean: the example generates, and the
test pins what it generates. Four preallocated provider rows exist before there is any demand, and a
multiplicity cell starts at 0, so an emit of mult + 1 seeds the channel with one push from each;
two demand-generated consumer rows answer those four pushes at multiplicity 2. The test fixes the
heights at [2, 4] and that the witness satisfies the constraints, the balance check and its
interaction bound, in the manner of the other WitnessGenerationTest modules.

In Clean/Air/FlatEnsemble.lean, EnsembleWitness.BalancedChannel and BalancedChannels take the
bound and state BalancedUpTo instead of BalancedInteractions, so
balancedChannels_of_balanced concludes BalancedChannels balance.pullBound. That keeps the
per-channel derivation named in one place rather than inlined at each proof that needs the stronger
form.

Ensemble.SoundChannels and tableSoundness_of_soundChannels now take the pull bound; the in-tree
call sites in OrderedChannel.lean and Vm.lean are updated.

Compatibility

pullBound defaults to 1 and matchedUpTo_of_balanced has a default proof, so Balance.logUp,
Balance.multiset and any out-of-tree balance check keep working untouched.

Five definitions take the bound as a new argument: SoundChannels (both the one on a list of
tables and Ensemble.SoundChannels), PartialBalancedChannel, and
EnsembleWitness.BalancedChannel / BalancedChannels. The last two also strengthen their
conclusion from BalancedInteractions to BalancedUpTo N; N = 1 recovers the old content
through BalancedInteractions.matchedUpTo_one.

SoundEnsemble.markFinished changes its instance argument from [channel.Consistent] to
[channel.ConsistentUpTo balance.pullBound]. A plain channel still finds it, through
[Consistent] → ConsistentUpTo N.

Checks

  • lake build clean, zero warnings.
  • lake build CleanTests passes.
  • No sorry. No native_decide in the library: the single occurrence is the example of the
    generation test, as in the other WitnessGenerationTest modules. #print axioms on
    CountedSquares.tableSoundness and on the new theorems of Balance.lean and
    CountedChannel.lean reports only propext, Classical.choice and Quot.sound.
  • scripts/check-consecutive-empty-lines.py passes.

Extraction

Balance.logUpUpTo has no path through ensembleToRust, which is typed to .logUp. The lowering
itself never reads the balance — ensembleToRust calls lower ensemble.ensemble — so this is a
signature restriction rather than a missing translation. The stricter bound that logUpUpTo
carries, interactions.length * N < ringChar F, is not surfaced anywhere in the extraction, so
widening the signature alone would be wrong: backends/plonky3/src/generated_air.rs rejects an
ensemble whose interaction count reaches the field order, which is the count < p of
Balance.logUp, and has no counterpart for the factor of N. How much that bound costs depends on
the field and on N. The count it bounds is the number of interactions on one channel, not the
height of a trace: at N = 510, a 64-bit field still allows around 3.6 · 10^16 interactions on
a channel, while a 31-bit field allows around 4.2 · 10^6. The predicate is also uniform across
the ensemble: Ensemble.interactionsFit applies balance.fits to every channel, so a channel
whose pulls all have multiplicity 1 is asked for count * N < ringChar F too. Generalizing the
backend, and letting the bound vary with the channel, are left as follow-up.

Open points

  1. Channel.counted N keeps the underlying channel's name, so channel.toRaw,
    channel.counted 2 and channel.counted 3 may denote different RawChannels under one name,
    while Ensemble identifies channels by name. The sharing is load-bearing for witness
    generation, which tallies interactions by channel name and whose DemandMode and
    PreallocatedMode take the plain Channel; renaming the counted channel would silently stop it
    generating rows. The failure mode on the ensemble side is an opaque Nodup goal from
    unique_channel_names, rather than unsoundness. The invariant is documented in the docstring of
    Channel.counted; changing both sides is left as follow-up.

… interaction count.

A table that answers k identical lookups with one row pulls the facts it relies on with
multiplicity k. Field-sum balance alone does not match such pulls with a push: (p - 1) / 2 pulls
of multiplicity 2 and one pull of 1 sum to p with no push. With fewer than p / N interactions it
does: if no interaction pushes a message, its balance is -S with 1 <= S <= length * N < p.

Interaction.PullUpTo / PushUpTo, MatchedUpTo and BalancedUpTo state this, and
LogUpBalanced.matchedUpTo proves it. Balance gets pullBound (default 1) and
matchedUpTo_of_balanced, which takes the same fits premise as balancedInteractions_of_balanced;
Balance.logUpUpTo N puts length * N < p into fits. RawChannel.ConsistentUpTo N is consistency
under BalancedUpTo N, and every Consistent channel has it. Sound ensembles, partial balance and
the VM theorem use ConsistentUpTo balance.pullBound, so with N = 1 nothing changes.
Balance.multiset's proof moves to MultisetBalanced.balancedInteractions to reuse it.
A pull of multiplicity 1..N gets the channel's guarantee, an active push owes it, and a pull
requires its multiplicity to be 0 or 1..N. The channel is ConsistentUpTo N, so a sound ensemble
can finish it under a balance check with pullBound at least N, such as Balance.logUpUpTo N.
pullUpTo and emitUpTo are the circuit operations. The interactions they emit are opaque
definitions with circuit_norm lemmas, so that simp does not unfold the message first, and
RawChannel.eq_false_of_name_ne tells channels apart by name without unfolding them.
… balance.

Channel.counted_not_consistent gives the counterexample that justifies ConsistentUpTo: two pulls
of a message the channel does not guarantee, one of multiplicity N and one of multiplicity 1, and
nothing pushed. BalancedInteractions holds on that list, because exists_push_of_pull only has to
match pulls of multiplicity 1 and reads the pull of N as an Interaction.Push, while the count
condition is vacuous since N is neither 0 nor 1. The counted channel reads both as pulls and hands
the guarantee to the pull of 1, which is false.

Without this the library cannot answer why RawChannel.Consistent is not enough and why
MatchedUpTo, BalancedUpTo and Balance.pullBound exist. The statement is over a general field; all
the counterexample needs is 2 <= N < ringChar F, which makes N distinct from both 0 and 1.
Balance.logUp, Balance.logUpUpTo and Balance.multiset are plain defs, so instance search, which
runs at reducible transparency, cannot project pullBound out of them. A user of a SoundEnsemble
over Balance.logUpUpTo N therefore had to write show channel.ConsistentUpTo N by hand before the
ConsistentUpTo instance of a counted channel would be found.

Balance.logUp_pullBound, Balance.logUpUpTo_pullBound and Balance.multiset_pullBound are rfl
lemmas tagged simp and circuit_norm, so the goal normalises to the concrete bound first. The
example in CountedChannel.lean guards this: without the lemma, infer_instance on
ConsistentUpTo (Balance.logUpUpTo N).pullBound fails.
…iles again.

Adding matchedUpTo_of_balanced to Balance without a default broke every existing definition of a
Balance, although for the default pullBound = 1 the field is just
BalancedInteractions.matchedUpTo_one applied to balancedInteractions_of_balanced.

A default has to work around how Lean elaborates them. A term default is elaborated once with
pullBound still abstract, so matchedUpTo_one does not typecheck; a tactic default is elaborated
per instance, against the real pullBound, but without the earlier fields in scope, so it cannot
name balancedInteractions_of_balanced. Handing the conclusion of balancedInteractions_of_balanced
to matchedUpTo_of_balanced as an extra premise makes the tactic form work, and costs the two
checks that prove the field themselves nothing, since they ignore it.
Balance.balancedUpTo_of_balanced passes the weaker balance it already computes.

Setting pullBound := N for N > 1 and omitting the field is a type error, as intended, not a
silently wrong default. Balance.multiset now relies on the default.
SoundChannels took the bound N first and the tables second, while
Air.Flat.Ensemble.SoundChannels takes the ensemble first and N second, as dot notation forces it
to. The two now agree: subject, bound, finished channels. Only the definition and its six call
sites change; nothing else about the property moves.
…o guarantees.

Rebasing these commits onto current main crosses a2ff3c4, "Complete the vector
eval normal form", which changed where `eval` sits in a `ProvableType` goal. The
two lemmas about a counted pull's guarantee and a counted push's requirement were
written against the old shape and called
`ProvableType.fromElements_eval_toElements`, which no longer fires: the goal now
reads `fromElements (toElements (eval env msg))`, with the eval already inside, so
the plain `ProvableType.fromElements_toElements` is what closes it.

The linter said so before the error did, reporting the simp argument as unused.

No statement changes, only the two simp calls that prove them.
jotabulacios and others added 22 commits November 11, 2026 15:17
…it keeps its callers.

Allowing counted pulls made both proofs need `BalancedUpTo balance.pullBound` where they
used to need `BalancedInteractions`, and each inlined the derivation as the same lambda
over the ensemble's channels. That left `balancedChannels_of_balanced` and
`BalancedChannels` without users, and the step they name duplicated in two files.

`BalancedChannel` and `BalancedChannels` now take the bound, the lemma concludes
`BalancedChannels balance.pullBound`, and both proofs call it again.
… and fix two docstrings.

`Interaction.PullUpTo` and `PushUpTo` inlined the same existential that
`Channel.CountUpTo` defines, and the counted channel's `ConsistentUpTo` instance relied
on the two being definitionally equal to build a `PullUpTo` from a `CountUpTo`.
`CountUpTo` now lives next to the interaction predicates that use it, with
`countUpTo_one_iff` in place of `exists_le_one_iff`, so that bridge is stated rather
than coincidental.

`Balance.multiset` goes back to its inline `Balanced` field: extracting
`MultisetBalanced` was not needed for counted pulls, and the default
`matchedUpTo_of_balanced` does not depend on the field being named.

Both docstrings said "fewer than `p / N` interactions"; the hypothesis is
`interactions.length * N < ringChar F`, which is not the same bound.
…ject the new interactions.

Every other layer states its `N = 1` coincidence — `pullUpTo_one_iff`, `pushUpTo_one_iff`,
`matchedUpTo_one`, `logUp_pullBound` — but nothing said that `Channel.counted 1` is
`Channel.toRaw`. `counted_one_guarantees` and `counted_one_requirements` state it field
by field, which is the conservativity a reader checks first.

`pulledUpTo` and `emittedUpTo` had `circuit_norm` projections for `channel` and
`direction` but not for `mult` and `msg`, so simp could not reduce either, unlike the
`pulled`/`pushed` family they mirror.
Nothing in `Clean/Examples/` used `Channel.counted`, so the API had no in-tree consumer
and its ergonomics were untested. `CountedBytes` is the smallest honest use: a provider
that pushes a byte as often as it is pulled, and a consumer that needs the same fact once
or twice and pulls it once with that multiplicity.

The consumer's constraint on its count is the point. It is what discharges the pull's
requirement `count = 0 ∨ CountUpTo 2 count`, and `counted_not_consistent` is why a row
that could claim any multiplicity would make the channel unsound.
…ished.

`SoundEnsemble.markFinished` takes `[channel.ConsistentUpTo balance.pullBound]` as an
instance argument. The counted channel's instance ties that bound to the channel's own
`N`, so synthesis has to see `(Balance.logUpUpTo N).pullBound` as `N`. It cannot unfold a
plain `def`, and an instance argument leaves no place to `simp` first, so finishing a
counted channel failed to elaborate.

A plain channel was unaffected: its instance comes from `[Consistent] → ConsistentUpTo N`
with `N` free, which matches an unreduced projection.

`Balance.logUpUpTo` is now reducible, which is what synthesis needs. The `simp` step in
the example above `counted_consistentUpTo_of_le` is no longer needed, and the lemma's
docstring no longer claims to solve a problem that a `simp` lemma cannot reach.
`REVIEWERS.md` asks each underscore-separated part of a theorem name to correspond to a
declaration or a standard logical word. The predicate is `Interaction.PullUpTo`, so the
plural `pullsUpTo` named nothing.
It states a `CountUpTo` fact and sat in `namespace Channel`, where `CountUpTo` no longer
lives, so it read as `Channel.countUpTo_of_val` about a root definition. Moving it leaves
the lemma itself unchanged.
Nothing in `Clean/Examples/` used `Channel.counted`, so the API had no in-tree consumer:
its ergonomics were untested, and the `pullBound` plumbing in `markFinished` and
`tableSoundness_of_soundChannels` was reached by no example. `CountedSquares` is the
smallest honest use. A squaring chip constrains `y = x * x` and pushes the pair as often
as it is pulled; a consumer that needs the same square once or twice pulls it once with
that multiplicity, and `tableSoundness` concludes for the assembled ensemble under
`Balance.logUpUpTo 2`.

The consumer's constraint on its count is the point: it discharges the pull's requirement
`count = 0 ∨ CountUpTo 2 count`, which is what `counted_not_consistent` shows a row must
not be free to skip.

Generation is not exercised, and the file says so. A `SoundEnsemble` that is not a VM has
no verifier in this version, so nothing creates the first interaction and the generator
returns an empty witness.
`BalancedUpTo`, `Balance.logUpUpTo` and `RawChannel.ConsistentUpTo` each carry a bound
that Clean's own definitions do not have, and nothing in the tree said what happens at
bound one. A reader had to unfold three definitions to be convinced that a channel which
does not count behaves exactly as it did before. `balancedUpTo_one_iff`,
`Balance.logUpUpTo_one` and `consistentUpTo_one_iff` state it instead, so the claim that
this generalizes Clean rather than replacing it is checked rather than asserted.

`Balance.logUpUpTo` carries `count * N < ringChar F` in its `fits` field, where
`Balance.logUp` only needs `count < ringChar F`. The factor reads like slack.
`exists_logUpBalanced_not_matchedUpTo` shows it is not: once `ringChar F ≤ 2 * N`, two
pulls whose multiplicities sum to the characteristic balance every message, the list is
shorter than the characteristic, and no push occurs anywhere. Without the factor,
`LogUpBalanced` would accept a balance that nothing ever pushed into.

`Channel.counted_one_guarantees` and `counted_one_requirements` both state an `iff`, and
`REVIEWERS.md` asks each part of a name to correspond to a declaration or a standard
logical word. They are now `..._iff`. Neither is used outside its own docstring.
The module docstring said that generation never runs, and gave a reason that was never
checked: that a `SoundEnsemble` which is not a VM has no verifier, so nothing creates the
first interaction. Neither part held. The consumer was `.preallocated` with no
`.multiplicity` cell, which `validateComponent` rejects outright, and an ensemble without a
VM can seed itself: a preallocated component's rows exist before there is any demand, and a
multiplicity cell starts at `0`, so an emit of `mult + 1` pushes once from every row.

The provider is now the preallocated component, with four rows and that emit, and the
consumer is demand-generated, one row per pushed square that nothing has pulled. The run
reaches `constraintsHold`, `channelsBalanced` and `interactionsFit`. The `+ 1` is the seed
and nothing more: it is field arithmetic rather than a count, so it says nothing about a row
whose `mult` is `-1`, and soundness is indifferent either way, since pushing is what owes
the guarantee.

`x` and `y` are witness cells on both sides now. They were fixed columns on the consumer,
and a fixed column is a value the verifier knows, so `y = x * x` held of the table whether
or not the pull carried it, which is the one thing this example exists to show.

`Clean/Examples/CountedSquaresWitnessGenerationTest.lean` pins the run, following the other
`WitnessGenerationTest` modules: heights `[2, 4]` and the three checks. `heights` lists the
tables in the ensemble's order, which `addTable` builds by prepending, so the consumer added
last comes first.
`CountUpTo N mult` says that `mult` is named by a natural between `1` and `N`, and carries
no hypothesis relating `N` to the field. In a small enough field two such naturals name the
same element, so `CountUpTo 2 (0 : ZMod 2)` holds, and a reader meeting that case has no way
to tell whether it was overlooked.

It was not, and the docstring now says why the bound is not stated here. Carrying
`N < ringChar F` in the definition would thread a condition on the field through every
requirement, guarantee and proof that mentions a count, to exclude a case the balance check
excludes already: `Balance.logUpUpTo N` fits an interaction count only when
`count * N < ringChar F`, which over `ZMod 2` with `N = 2` leaves `count = 0`.
…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.
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.

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.
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.
Prove table soundness from a finishing order of channels and of message classes
@nicole-graus
nicole-graus merged commit 8552c7a into pr-base-upstream-main 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