refactor: weigh the chapter's chunks against batch signing, and keep deriving

Batch signing landed on mantra while this branch was open, and it makes the
argument this change was built on obsolete as written. MantraChunk.chunksOf
said the chunks "cannot be events proposed on their own -- that would cost a
quorum per paragraph". They can now: proposeSigningBatch would carry the
chapter and a chunk per paragraph through one quorum, and every row would hold
a signature of its own.

Weighed and declined, and the KDoc now says so rather than leaning on a reason
that stopped being true. MAX_BATCH_SIZE is 64, which caps a batched chapter at
63 paragraphs and fails an ordinary one outright; the text would go on the wire
twice, whole on the chapter and again split across the chunks, and the proposal
is the term that cap is sized against; and all-or-nothing over k items would
make a long chapter less likely to be signed than a short one, for no reason a
member could see. The signature it would buy is redundant besides -- the
appendix rejects the manifest shape because an item then needs a lookup to be
checked, and here that lookup is a foreign key: a chunk is a pure function of
its chapter and cannot be stored without it.

docs/frost-batch-signing.md records this under the slot Phase 7 leaves open --
"deciding *what* to batch" -- because the next caller will reach for the same
shape. The rule it leaves behind: batch siblings, not derivations. Events that
could each have been authored separately are worth a batch; events that are a
function of another event in the same batch are worth deriving instead.

**The merge.** Only SignedChapterTest broke: the five per-item columns moved
off FrostSigningSession onto FrostSigningItem, so it builds an item and calls
signedEvent(item, sig), which is how SignedArtifactTest was ported in the same
commit. Nothing in the flow itself moved -- proposeSigning kept its signature
as the one-event form, and complete() applies each signed event through
ChatMessage.applyInnerEvent, so the chapter's chunk derivation works the same
whether the chapter arrives alone or as one item of somebody else's batch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso Ngako
2026-09-06 10:13:09 +02:00
parent 60abf243ed
commit e081d14f37
4 changed files with 62 additions and 32 deletions

View File

@@ -487,6 +487,32 @@ one rule that a batch is only as available as its worst item, so events that do
not belong together should not travel together, and the one prohibition that
`GroupKeyStateManager.propose` must never batch.
### The first caller to weigh it, and decline
Adding a chapter is the case batching looks made for: a chapter is proposed
with a chunk per paragraph, which before this work would have been one quorum
each. It signs the chapter alone anyway, and splits the chunks back out of the
signed text on every device
([`MantraChunk.chunksOf`](../composeApp/src/commonMain/kotlin/press/mantra/compose/database/model/MantraChunk.kt)).
Recorded here because the next caller will reach for the same shape:
- **The cap binds on ordinary content.** `MAX_BATCH_SIZE` is 64, so a batched
chapter is capped at 63 paragraphs. Prose runs past that, and the failure is
a chapter that cannot be proposed at all.
- **The text would travel twice** — whole in the chapter, again split across
the chunks — and the proposal is the term the cap is sized against.
- **Availability falls with length.** All-or-nothing over `k` items means a
long chapter is less likely to get signed than a short one, for no reason a
member could see.
- **The signature would be redundant.** The appendix rejects the manifest shape
because an item then needs a lookup to be checked. Here the lookup is a
foreign key: a chunk is a pure function of its chapter and cannot be stored
without it, so the chapter's signature already covers it.
The general rule this leaves behind: **batch siblings, not derivations.** Events
that could each have been authored separately are worth a batch; events that are
a function of another event in the same batch are worth deriving instead.
---
## Appendix — what was considered and rejected