oficina / docs Public

Snapshots, so a document stops going read-only

maxRetainedUpdates was a cliff rather than a budget: at 4096 updates
Handle.Apply refused everything further and the document stopped
accepting edits, permanently, with no warning — about two hours of
continuous typing at the current debounce. Snapshots remove that, and
separately make a shorter debounce affordable, which is the next change
and the one anyone will actually feel.

A snapshot is one ordinary Yjs update encoding a whole document, which
is what keeps this cheap: Store.replay and the browser's applyServerLog
both already know how to apply concatenated updates. The Rust core gains
a state export and an in-core verifier (ABI v4); the store writes a
snapshot every 256 updates and replays snapshot-then-tail; the update
endpoint serves the same shape, with raw=1 as the escape hatch for a
snapshot that will not decode. Replaying 4000 rows: 3.55ms with a
snapshot against 71.10ms without.

The snapshot is taken from the replayed state BEFORE the incoming update
is applied, and that placement is the correctness argument rather than a
style choice. Taken after a successful apply it can record a state
missing a row a concurrent POST committed — the replay runs outside the
transaction, and the verification cannot catch it because it compares
the candidate against the same stale handle. It also never rescues a
document already at the cap, since Apply refuses before any update
succeeds, which is the case the whole feature exists for.

Reviewed per task and then as one branch by Fable. Five times a test
turned out to be incapable of failing against the mistake it guarded —
four of them in the plan's own code — and each fix was verified by
breaking the implementation and watching the test fail. The spec carries
the decisions, including D8's mid-replay re-seed, which keeps a long
document readable when its snapshot is invalidated by a future ABI bump.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>