docs: report what Gumbo needs for durable execution frameworks

[contrasam]

Follow-up to #18. That PR recorded the v1 distribution design; this one writes up the log-layer work it depends on, as a standalone report Gumbo can be worked from directly.

Docs only — no source changes.

Why a separate document

The distribution design needed four things from Gumbo that it does not have. Rather than leave them as asides in a design doc, they are written up with the evidence for each, so the argument survives being read by someone who is not working on Catalyst. None of the findings are Catalyst-specific — they are the primitives any durable execution engine needs, which is why Boudin sits behind several of the same limitations.

Everything here was measured

The report opens with the probe table rather than burying it, because "we read the code and think this is wrong" and "we ran two JVMs and they both assigned seq 0" carry very different weight:

Probe	Result
Sequential restart (append, exit, continue)	3 4 5 — correct
Two JVMs, one directory, one execution	Both assigned 0 1 2; log reported 3 of 6
strings log.dat after the above	All six events physically present
Two executions in one log, tail-read the second	Returned the whole stream
Same, through Catalyst's snapshot warm path	Sole: 43 steps. Shared: 51 steps

The third row is the one that changes the diagnosis: nothing was lost, the view was. That makes D2 an index-clobber bug rather than a durability bug, and it is why the report says plainly up front that durability is correct and the foundation is not the problem.

The fifth row is a live bug in shipped Catalyst code (D4): GumboEventLog.readFrom passes a per-execution seq into readAfter, which is keyed on the global seqnum. The two number spaces coincide only when the log holds a single stream — true in every test, false in every real deployment. The reducer then re-applies events already folded into the snapshot and double-counts steps, tokens and cost. Not fixed here; this PR is the write-up.

Structure

Four defects (per-process localId, index clobber, no cross-process guard, no version-keyed read), six additions (conditional append, version-keyed reads, KV compare-and-set, declared capabilities, AppendResult/streamVersion, multi-tag), the cross-cutting concerns (unbounded in-memory index; trim silently destroying replayability), a suggested order, and five tests.

The ordering is by blocking-ness × cost, not conceptual elegance — so it starts with a directory lock, which fixes nothing but converts silent corruption into a loud error while the rest is designed.

The one genuinely open question, now resolved

localId was repurposed from Boki's per-engine meaning to a per-tag cursor without changing how it is assigned — that is the root cause of D1. The natural fix is to move the semantics back, and the report initially left that implicit. The second commit answers it.

The answer is that the two are different quantities Gumbo merged into one field: per-engine vs per-tag, internal write-path detail vs external client contract, superseded once seqnum is assigned vs permanent. So realigning with Boki is orthogonal, not an alternative — it would make localId correct and useless, since the version-keyed read and the conditional-append fence would each still need a number of their own.

Decision recorded: drop localId from the public API, expose a per-tag, storage-owned streamVersion, dense rather than the tag's latest global seqnum. Dense because (a) it avoids a log migration — a seeded counter continues existing sequences, whereas redefining the exposed version as seqnum would silently invalidate persisted cursors such as Catalyst's snapshot throughSeq, with no error at the seam — and (b) "diverged at step 7" is actionable where "diverged at seqnum 918,442" is not.

The supporting fact was verified against the tree rather than assumed: Catalyst performs no arithmetic on seq, only ordering comparisons. Density is asserted in one test and documented as an invariant, but nothing structurally requires contiguity — so the choice is free on the client side, which is why it is made on migration cost and readability instead.

Note on the branch

#18 was squash-merged, so this branch was restarted from main and the two unmerged commits replayed onto it. The tree is identical to what was reviewed before the restart.

---

Generated by Claude Code

[greptile-apps]

Greptile Summary

Adds a standalone report describing Gumbo capabilities required for durable execution frameworks.

• Documents measured concurrency, indexing, versioned-read, and multi-writer limitations.
• Defines proposed storage primitives, sequencing semantics, implementation order, and regression tests.
• Links the distribution design to the new requirements report.

Confidence Score: 5/5

The documentation-only PR appears safe to merge.

No blocking failure remains; the previously understated sequence-density dependency is now explicitly documented with its runtime and test implications.

Important Files Changed

Filename	Overview
docs/gumbo-requirements.md	Adds the Gumbo requirements report and now accurately records Catalyst's sequence-density dependency in snapshot scheduling and tests, resolving the prior review finding.
docs/distribution.md	Links the existing distribution design to the detailed Gumbo requirements report.

_{Reviews (2): Last reviewed commit: "docs: correct the sequence-density claim..." | Re-trigger Greptile}