edytor 3.0.0 → 4.0.0

package/dist/crdt/vendor/yjs/UPSTREAM.md

@@ -33,7 +33,7 @@ is no longer a dependency of any kind: `tests/packed-consumer/smoke.js` and
 ## Layout
 
 ```text
-src/        upstream src/, plus patches YP1 (import specifiers), YP4, YP5, YP7, YP8 (pruning), YP9–YP15, YP16 (no delta layer), YP17 (one update encoding), YP18 (no undo manager) and YP19 (only what edytor calls)
+src/        upstream src/, plus patches YP1 (import specifiers), YP4, YP5, YP7, YP8 (pruning), YP9–YP15, YP16 (no delta layer), YP17 (one update encoding), YP18 (no undo manager), YP19 (only what edytor calls), YP20 (hold records), YP21 (claim items), YP22 (move records), YP23 (a block set's trim), YP24 (a string table per update), YP25 (paired marks written in parts), YP26 (a client table per update), YP27 (the parent kind in the info byte), YP28 (large integers in content values), YP29 (a collected mark or claim keeps its class) and YP30 (a transaction's `beforeCommit`)
 global.d.ts upstream global.d.ts, plus patches YP1, YP8 and YP19
 dts/        generated TypeScript declarations (not upstream source — see below)
 LICENSE     upstream MIT license, verbatim
@@ -55,11 +55,12 @@ applied to both) and `fork.diff` (newer → this tree, both carrying YP1) into
 the run's artifact, says in the summary whether the installed `lib0-v14`
 satisfies the newer engine's `lib0` range (a mismatch is a run warning: a
 red check may then be the older lib0, not the fork), then materializes the newer engine as `bench/vendor-baseline/yjs`
-so `bench/lib/interop.mjs` (the fork and the newer engine syncing over the
-wire) and the baseline leg of `src/tests/crdt/hardening/search-marker-format.test.ts`
-(byte-identical stores after every operation) run against it. A red run
+so the baseline leg of `src/tests/crdt/hardening/search-marker-format.test.ts`
+(identical stores after every operation, each read back from its own
+engine's encoding) runs against it. There is no wire interop to check since
+YP24: the fork's update encoding is its own. A red run
 means the re-sync needs care; the re-sync itself is the manual recipe under
-YP8. Locally: `node scripts/upstream-check.mjs`, then those two checks, then
+YP8. Locally: `node scripts/upstream-check.mjs`, then that check, then
 `bench/lib/mk-baseline.sh` to restore the pinned baseline.
 
 ## Local patches
@@ -553,8 +554,9 @@ each undo therefore brought it back twice (`abbc`), and the first undo brought
 it back although the other peer's delete still held it (arch-v2 contract
 program `history.concurrent-double-delete`). Edytor fixes this with per-writer
 text delete marks (`src/lib/crdt/text/deletes.ts`, execution ledger row
-"Text double-delete undo"); the engine needs two hooks for it, and nothing
-else changes.
+"Text double-delete undo"; since YP20 the engine's hold records, and that
+module is gone); the engine needs two hooks for it, and nothing else
+changes.
 
 Patch (hunks marked `// YP11` or delimited by `// YP11 begin` / `// YP11 end`):
 
@@ -832,10 +834,11 @@ Patch:
 - `edytor/crdt` exports `UpdateEncoder`, `UpdateDecoder` and `diffUpdate`
   in place of the V1/V2 pairs (see `src/tests/crdt/yp8-surface.test.ts`).
 
-Interop: an upstream engine reads the fork's bytes with its `…V2`
-functions (`bench/lib/interop.mjs`, the baseline legs of
-`search-marker-format.test.ts` and `yp16-writes.test.ts` compare against
-upstream's `encodeStateAsUpdateV2`). Vendored execution lines 5,123 →
+Interop: an upstream engine read the fork's bytes with its `…V2`
+functions until YP24 (a string table per update) made the encoding the
+fork's own; the baseline legs of `search-marker-format.test.ts` and
+`yp16-writes.test.ts` now compare the stores each engine reads back from
+its own encoding. Vendored execution lines 5,123 →
 4,872. Test side: `compatibility.tests.js` (v1 documents of Yjs 13) is
 removed; the upstream suite's helpers run every program in the one
 encoding (`testHelper.js`, `updates.tests.js`).
@@ -869,13 +872,17 @@ Vendored execution lines 4,872 → 4,630; an app bundle 546.4 → 545.0 KB min
 (minimal), 745.4 → 744.0 (every plugin): edytor's manager is 4.3 KB where
 the engine's (without `redoItem`) and the hooks' driver were 5.6.
 
-Test side: `src/tests/crdt/harness/undo.js` is the engine's `UndoManager`
-as it stood before YP18 (`undoManagerOf(Y)`, over the fork or a copy of its
-tree), for the upstream suite, the replica harness's `raw` adapter, the
-engine probes and the differentials. Removed with their subject:
-`yp11-undo-hooks.test.ts`, `yp12-undo-withdraw.test.ts` (the hooks' rows;
-the rules are the facade history's `hist.undo.*` rows) and the upstream row
-on `ignoreRemoteAttributeChanges`.
+Test side: the tests keep no undo manager of their own. Every undo a test
+runs is edytor's (`createUndoManager`, `document.history`, or over a raw
+document `src/tests/crdt/harness/history.ts`: the same class with the same
+rules, `historyRules`, its scope narrowed to the probed nodes). Removed with
+their subject: `yp11-undo-hooks.test.ts`, `yp12-undo-withdraw.test.ts` (the
+hooks' rows; the rules are the facade history's `hist.undo.*` rows), the
+upstream rows on `ignoreRemoteAttributeChanges`, and later (the review of
+PR #29) the test copy of the engine's `UndoManager` as it stood before YP18
+(`harness/undo.js`, 528 lines), upstream's `undo-redo.tests.js` (20 rows of
+that class) and its `testSubdocsUndo`; the undo/redo steps of the YP16
+writes differential (an engine write path no more).
 
 ### YP19 — the engine ships what edytor calls: no plain formats, no observers, no subdocuments, no relative-position objects (`src/ynode.js`, `src/structs/Item.js`, `src/utils/Doc.js`, `src/utils/Transaction.js`, `src/utils/transaction-helpers.js`, `src/utils/encoding.js`, `src/utils/ids.js`, `src/utils/StructStore.js`, `src/utils/positions.js` (new), `src/index.js`, `global.d.ts`)
 
@@ -954,8 +961,8 @@ prototype, from `src/tests/setup/engine-reads.ts` in every vitest lane (and
 on a stripped copy's node where a differential loads one). The harness's
 `applyDelta` writes a formatted op as paired mark operations (an insert takes
 exactly its formats, a retain sets the keys it names); the raw adapter marks
-with `mark`; the harness's pre-YP18 `UndoManager` derives
-`changedParentTypes` from `changed`. Removed with their subject: the
+with `mark`; the harness's pre-YP18 `UndoManager` derived
+`changedParentTypes` from `changed` (the copy is gone, YP18's test side). Removed with their subject: the
 upstream tests of observers and events, subdocuments, relative positions,
 plain formatting and its cleanup (`y-text`, `y-map`, `y-array`, `doc`,
 `delta`, `undo-redo`, `attribution`, `IdSet`, `y-xml`;
@@ -968,6 +975,546 @@ cleanup's delete-set walk). Ported: `v14-smoke` (marks, the `commit` event,
 probes (planting through `findMarker`), `testStructReferences`,
 `testKeyEncoding`. Upstream suite: 197 → 126 tests.
 
+### YP20 — hold records: an attributed, reversible delete (`src/structs/Item.js`, `src/structs/AbstractStruct.js`, `src/ynode.js`, `src/utils/encoding.js`, `src/utils/ids.js`, `src/utils/StructStore.js`, `src/utils/Transaction.js`, `src/utils/transaction-helpers.js`, `src/utils/redo.js`)
+
+Reason: the engine's delete is anonymous (a delete set names ids, not who
+deleted them) and irreversible (a deleted item is deleted forever; an undo
+re-creates COPIES). Edytor's product rules need a per-writer, reversible
+text delete — a character two writers deleted shows again only once both
+undid, an undo restores the same text in the same order, text another
+author added is kept — so edytor carried a layer over the engine
+(`crdt/text/deletes.ts`, `crdt/text/delete-index.ts`, 10.3 KB minified in
+every app): per-writer delete marks, restoration records, copy lineage
+(root, member, leaf), pending restorations, a hold rule for a peer's
+concurrent restoration, a leftmost-wins dedup of concurrent copies, a
+`gcFilter` keeping every deleted copy's content on every replica (the room
+too), and follow-up transactions after remote changes. The fork now has the
+delete, and the layer is gone. Design: `docs/archive/engine-delete/design.md`.
+Edytor's schema generation 7 is the cutover (no conversion).
+
+Patch (new code delimited by `// YP20 begin` / `// YP20 end`, edits marked `// YP20`):
+
+- **`ContentHold`** (`Item.js`, content ref 11, `readContentHold` in
+  `ynode.js`'s `contentRefs`): one unit per held id range
+  (`client, clock, len`, written as a left id and a length); `copy`,
+  `splice`, `mergeWith` (consecutive records of one writer merge, as a
+  typed run does), `write`. Integrating it holds what it names; deleting it
+  (an ordinary delete of the record item) releases. Records are immutable:
+  the state that decides visibility is the items, the delete set, the
+  records and the deleted records, so replicas converge in any order.
+- **`Item`**: `holds` (local, never encoded: how many live records name
+  the item), `removed` (bit 3, the delete set's fact; `AbstractStruct`
+  answers `deleted` for a GC struct or a Skip), and `deleted` = `removed ||
+  holds > 0`, so every reader of visibility (cursors, positions, the range
+  cursor, lengths, edytor's index) sees a held item as deleted. The paths
+  that mean the engine's delete read `removed`: `Item#delete`'s guard (a
+  held item is removed too, and logs a give-back: the delete set counts it
+  hidden again), `Item#gc`, `Item#split` (the right part copies `holds`),
+  `Item#mergeWith` (equal `removed` and `holds`), `Item#integrate`'s
+  deleted-parent rule (a held atom's attrs integrate), `ContentType#delete`
+  (a held child goes with its node), `createDeleteSetFromStructStore`,
+  `readAndApplyDeleteSet`, `tryGcDeleteSet`, `redoItem`'s parent rule.
+- **Holding** (`holdRange`): the items present take the hold now, split at
+  the range's edges; a range this replica lacks (past its clock, or a Skip)
+  waits in `store.pendingHolds` (`client → [clock, len, delta, …]`), applied
+  by `readUpdate` once an update of that client integrated
+  (`applyPendingHolds`): a record never waits for its items, so a delete of
+  text a room lost is stored and acknowledged at once. A GC struct takes
+  nothing. An item that starts or stops being held (and is not removed)
+  moves its parent's length, drops its search markers, joins
+  `transaction.changed` and is logged in `transaction.holds`
+  (`client, clock, ±len`, in order: the index's edits).
+- **`YNode#delete(index, length, into, fresh)`**: with `into` (the records
+  list) the live units are held by one record appended there instead of
+  removed, except those `fresh` names (the open undo step's inserts:
+  removed, so that step's undo changes nothing); the search markers move as
+  for a delete. **`YNode#hold(ids)`**: append a record holding `ids`.
+
+Plain deletes (every upstream test) are untouched: with no record, `holds`
+is 0 everywhere and every changed path reduces to upstream's.
+
+Edytor side: a text delete passes the records list (`crdt/text/model.ts`
+`deleteRange`); the history's undo deletes the undoer's record, a redo
+copies the record (never the text), an undo of typing holds the typed text,
+a dropped step removes what this writer's records of it hold
+(`hist.delete-marks.release`); the purge removes what a record older than
+the horizon holds; the index folds `transaction.holds`. Removed:
+`bindCrdt(Y).doc.keepCopies`, `PurgeReport.records`, the restoration
+records root, the engine object's `ContentAny`.
+
+Measured: vendored execution lines 3,392 → 3,548 (+156); edytor's
+`text/deletes.ts` + `text/delete-index.ts` (699) removed. App bundle
+(`scripts/bundle-size.mjs`): minimal 423.8 → 417.0 KB own (470.6 → 463.7
+total, 162.0 → 159.4 KB gzip), every plugin 653.2 → 646.4 (701.8 → 695.0),
+`edytor/export` unchanged. `bench:crdt` (one machine, two runs each): a
+keystroke, a load and an encode unchanged within noise, a backspace
+(`scale`) 0.15 → 0.08 ms at 1k blocks, an undo (`history5000`) 0.72 →
+0.42 ms. A room's state after 1,100 text deletes in separate steps over
+200 blocks: 94,584 → 88,431 bytes (83,826 once the writer's history
+releases them).
+
+Oracle: `src/tests/crdt/yp20-holds.test.ts` (a hold and its release show the
+same item; two writers in both orders; overlapping records; a peer's insert
+inside a held run; a record whose items arrive later; merged, diffed and
+reloaded updates; collection; `fresh`; three seeded differentials of held
+deletes, releases and inserts with search markers on and off, byte-identical
+after every step), the edytor rows `arch-v2/text-delete-marks.test.ts`,
+`delete-records-fold.test.ts`, `history-limit.test.ts` and the native
+contract programs (all 12 hold, `split.range-one-undo` included), the random
+corpus (every adapter), the upstream suite unchanged (`encoding.tests.js`
+pins ref 11).
+
+### YP21 — claim items sort after content and are never collected (`src/utils/marks.js`, `src/structs/Item.js`)
+
+Reason: a merge is a claim, "the display of this block continues with that
+block's". Edytor stored it in a `claims` list on the holder's node, so the
+claim had no place in the holder's text: a split its writer did not see could
+not tell which piece keeps it, and edytor carried a layer that anchored each
+claim to the end of its holder's stream as its writer saw it and moved it to
+the piece that ends that region after every fold (`crdt/text/index/anchored.ts`
+and the claim anchoring in `text/model.ts`, 2.4 KB minified, plus a `claims`
+node per block, 13 B stored). A claim is now one countable unit `{ m }` in the
+holder's backing text, at the end of the gap at the end of its stream (YP7's
+`insertAtGapEnd`), and YATA decides which piece of a concurrent split holds it.
+For that to give the serial outcome the engine only needs one sort rule:
+
+- `markClass` (YP13's integration class) answers `3` for a claim item: a
+  sequence item (`parentSub === null`) whose content's first value is an
+  object with a string `m`. Among the items of one origin, left-side mark
+  items, then content (boundaries included), then right-side mark items, then
+  claim items. So a boundary a concurrent split writes at the claim's origin
+  goes before it (the claim follows the split's last piece), and so does text
+  a concurrent writer types there (it stays in the holder, before the claimed
+  text); a writer who saw the claim writes before it anyway (its insert's
+  right origin is the claim).
+- `Item#gc` keeps the content of every item whose class is not `1` (paired
+  mark items, YP13, and claim items): the class orders concurrent inserts on
+  every replica, collected or not. The check was YP13's paired-mark test; it
+  is now `markClass(this) === 1`, the same answer for every format item.
+  (YP29: a collected mark or claim keeps only its class.)
+
+Plain items (every upstream test) are untouched: a sequence of strings,
+nodes or JSON values without an `m` key, and every map value, read class `1`.
+
+Edytor side: schema generation 8 (no conversion). A merge writes the claim
+item (`claimInto`; a streamless block gets its own text first); a block's
+claims are its implicit ones (`id.same.concurrent`), then the claim items of
+its stream, which the index's rows track as they track boundaries (a claim
+item is a row bound that never delimits, so no read shows it); a split writes
+the claims that follow its point again at the end of the new block's stream
+and deletes their items. Removed: the `claims` node, `MergeClaim.a`/`r`,
+`Claim.seqIndex`/`holder`, `TextBlockRec.claimsNode`/`listClaims`,
+`readClaims`, the index's anchored part.
+
+Oracle: `src/tests/crdt/text/merge-claim-anchor.test.ts` (48 client-id pairs,
+both delivery orders, duplicate delivery, a reload: the serial outcomes),
+`src/tests/crdt/yp21-claims.test.ts` (the sort rule against content,
+boundaries and marks on every pair of client ids, collection), the index
+self-checks (each record's claims equal a fresh scan's), the random corpus,
+the upstream suite unchanged.
+
+### YP22 — move records: an attributed, reversible, order-independent move (`src/structs/Item.js`, `src/ynode.js`, `src/utils/marks.js`, `src/utils/Doc.js` (`_clock`), `src/utils/Transaction.js`, `src/utils/StructStore.js`, `src/utils/encoding.js`, `src/index.js`, `global.d.ts`)
+
+Reason: the engine has no move. Edytor placed each block by a map of
+placement candidates (`at`: `{p: parent, r: rank}` under an ever-growing
+per-writer key) and ordered an array's items by a rank attr per item
+(`~id#`, `~id>`), so it carried a dense-key codec (`placement/rank.ts`,
+2.7 KB), source ranks, a candidate argmax with a runner-up fallback, a
+global cycle pass, and ranks that grew with every insert at one spot (39
+characters after 300 Enters) and a 37.7 B `at` node per block. The fork now
+has the move, built like YP20's hold record (Kleppmann's list move: a
+position is a YATA item, an element its original item), and the layer is
+gone. Design: `docs/archive/engine-move/design.md`. Edytor's schema
+generation 9 is the cutover (no conversion).
+
+Patch (new code delimited by `// YP22 begin` / `// YP22 end`, edits marked `// YP22`):
+
+- **`ContentMove`** (`Item.js`, content ref 12, `readContentMove` in
+  `ynode.js`'s `contentRefs`): one countable unit at its destination
+  holding a Lamport `priority`, a `side` (`0` after, `1` before), the
+  ordered id ranges (`client, clock, len`) of the units it moves and, for
+  the sort of two records at one origin, the chain it stands at (`at`: the
+  ids of the units from the root sequence down to the unit it stands at,
+  outermost first — for a block, the home slots of its ancestors, then its
+  own; `null`: the first unit it names alone) and its `part` there (0–7,
+  the writer's order among the records standing at one unit); `copy` keeps
+  them all (a redo copies the record, never the units); its one unit's
+  value (`getContent`) is the record itself; `write` puts
+  priority, whether a chain follows, part and side in one varint
+  (`priority · 32 + 16 · anchored + part · 2 + side`), then the chain (its
+  length, then its ids), then the ranges as a hold record's (one writer,
+  `writeIds`, and one reader, `readIds`, for both). `Item#delete` hands
+  the deleted item to its content's `delete`, so a record drops itself
+  from its units' movers without keeping its item.
+  A record never moves a record (such ids are skipped). Records are
+  immutable and deleted at most once: the state that decides a unit's place
+  is the items, the records and the deleted records, so replicas converge
+  in any order — no cleanup message, no replay (what sank upstream's
+  `ContentMove`, PR #357).
+- **`Item`**: `movers` (local, never encoded: the live records naming the
+  item, kept strongest first by `(priority, client, clock)`), `mover` (the
+  first of them), `deleted` =
+  `removed || holds > 0 || movers !== null` (hidden at home), `gone` =
+  `removed || holds > 0` (shown nowhere: a delete or a hold beats a move,
+  Collabs' and Liveblocks' rule, not Loro's resurrection). `Item#delete`
+  of a moved item logs it (`tr.moves`) and moves no length; `Item#split`
+  copies `movers`; `Item#mergeWith` requires both unmoved; `Item#gc` keeps
+  a record's content (its class orders concurrent inserts, as YP21's).
+- **Moving** (YP20's walk: `holdRange`/`holdIds`/`holdItem` take the record,
+  `null` for a hold): the items a record names take
+  it when it integrates, split at the range's edges. A record waits for
+  its units and its chain as an item waits for its origin (`getMissing` in
+  `encoding.js`: a named id past a client's clock, or one a Skip stands
+  for, is the missing dependency — a skip counts in the clock but holds no
+  item to sort by), so they are present whenever its place is decided and
+  whenever another record at its origin is sorted against it
+  (`sourceOrder`), in one update or in many; `applyPending` applies YP20's
+  pending holds only. A
+  unit that starts or stops being moved (and is not gone) moves
+  its home sequence's length and drops its search markers; one whose mover
+  changed is logged in `transaction.moves` (`client, clock, len`, in
+  order), and its home and its new mover's sequences are marked changed.
+- **`doc._clock`** (was YP13's `_markClock`): the greatest Lamport
+  timestamp of a mark or a move this document integrated; a local mark or
+  move takes `_clock + 1`, so a move made after seeing another wins over it
+  (Yjs ids are not Lamport timestamps). A move record raises `_clock` only
+  when it comes from a peer (`!transaction.local`): a writer's own records
+  keep one priority until it sees a peer's, so its gestures — one plan or
+  several between syncs — win or lose together against a concurrent peer's
+  (between two records of one writer at one priority the later clock wins),
+  and two peers splitting one list at once keep each block where one of them
+  put it, never half of a head's items with each.
+- **`YNode#move(index, ids, side, part, at)`**: one record at live index
+  `index` (in the gap there, `insertInGapHelper`).
+- **Sort classes** (`marks.js` `markClass`, `sortsBefore`): among the items
+  of one origin, a move record sorts after every slot (class `4 + side`:
+  a split's pieces first, then the after-records, then the before-records
+  — the order every serial run of the gestures gives, DR-crdt-6); two
+  records of one class sort by the chains they stand at (`sourceOrder`),
+  level by level from the root: two units of one sequence by
+  `sequenceOrder` (the walk from each item leftward until one
+  meets the other, the distance between them; one item: by clock), a unit
+  before the units inside its block (the shorter chain first); chains that
+  meet in no sequence (or reach a unit a GC struct replaced) order nothing,
+  and the part, then the stronger record decide — so two peers that outdent
+  or lift blocks out of one list, or of nested lists, into one gap at once
+  keep the list's order there whatever their client ids (CW-01). The
+  record names everything its sort reads, so the order needs no document
+  hook (the prototype's `_unitOrder` read the chains from the sequences at
+  integration time, and a replica that took a record before an ancestor's
+  slot, inside one update, compared it by client id); and among block slots (`{ b }` units)
+  the split key first (`s`: the id of the boundary item of the split that
+  made the block; two such slots sort by their boundaries' order in the
+  text, `sequenceOrder`, and before a slot no split made, so two peers'
+  splits of one block, with the lines a paste adds at its split, read in
+  the text's order whatever each typed meanwhile, `order.split.text`), then
+  the origin writer's own slots first (`extendsRun`): the lines one writer
+  types after its own line stay together around a peer's line inserted
+  there (`order.insert.run`). The two rules read a unit one way (`unitAt`:
+  an id's item and clock, `null` for a GC struct) and order two units one
+  way (`unitOrder`: by clock in one item, else `sequenceOrder`). Each is a
+  total order per origin
+  that every replica computes alike — `sourceOrder` because a record
+  integrates only once its units and its chain have (above), and a unit's
+  place in its sequence never changes.
+
+Plain items (every upstream test) are untouched: with no record, `movers`
+is `null` everywhere, `extendsRun` is false for every array or text item,
+and every changed path reduces to upstream's.
+
+Edytor side: each data owner keeps one order sequence, its node's list
+part (`placement/slots.ts`): a block's children are home slots `{ b }`
+there (the root's in the registry root's list part), an array's items slots
+`{ p, i }`, and a move one record naming the moved units in order. The
+index reads the sequences, keeps an in-memory order key per child
+(`placement/keys.ts`), re-places only the blocks whose slot, record or
+mover changed (`transaction.moves`, the slots and records a fold touched)
+and resolves a cycle locally: a block's candidate places are its live
+records, strongest first, then its home slot, and the block whose move is
+the oldest edge of a cycle is back where it stood (its next record, else
+home; the root's tail only when every place closes a cycle,
+`placement/resolve.ts`); writers name each record's chain (the home slots
+above the unit it stands at) and anchor and carry where the index shows a
+block; the purge drops the old records no block shows at and the slots of
+removed blocks.
+Removed: `placement/rank.ts`, `placement/source.ts`, the `at` nodes, the
+candidate argmax and runner-up, the global resolution pass, the ranks of
+data arrays.
+
+Measured: see `docs/archive/engine-move/design.md` ("Prototype: measured").
+
+Oracle: `src/tests/crdt/yp22-moves.test.ts` (two writers move one unit, in
+both orders; a group move overlapping a single move; undo, redo and a
+fallback; a record whose units arrive later; merged, diffed and reloaded
+updates; the sort classes; three seeded differentials with search markers
+on and off, byte-identical after every step; three replicas syncing in
+random orders), the placement rows (MV01–MV10, the order sweeps,
+`display-cycle`, `reachability`, `same-id-concurrent`), the index
+self-checks (each placement's parent and each parent's order equal the
+rebuild from the sequences), the random corpus (every adapter), the
+upstream suite unchanged (`encoding.tests.js` pins ref 12).
+
+### YP23 — an update's block set is trimmed to every known range (`src/utils/BlockSet.js`)
+
+Reason: before an update integrates, `readUpdate` removes from its block set
+what the store already has (`BlockSet.exclude`: the state below the client's
+clock, minus the store's skips). Upstream read a client's first and last
+struct once, before the loop over the known ranges; trimming the first range
+splits a struct in place (`findIndexCleanStart`), so for the next range the
+bounds were stale and the range was skipped. A struct spanning a skip, known
+ids and the end of the state — a GC of a whole removed subtree, after a
+dropped message left a gap — integrated whole over the known middle: its
+delete-set entry named ids the store never had, and the transaction's
+cleanup threw in `tryMerge` (`findIndexSS`: "Unexpected case", or reading
+`id` of `undefined`). The corpus's `seed-140` raw repro was this
+(`upstream-engine-crash`, tracked since the v14 cutover); the move records
+(YP22) made the raw adapter's runs reach it in a dozen more seeds.
+
+Patch (edits marked `// YP23`): `exclude` reads `firstStruct` and
+`lastStruct` per range, and a client without structs or ranges is skipped
+(`continue`), not the whole exclusion (`return`).
+
+Oracle: `src/tests/crdt/yp23-exclude.test.ts` (a block set holding one GC
+over 1..59 trimmed by the known ranges 0..5 and 9..34 keeps a skip per range
+and the structs only where the store has nothing; a replica that
+integrated around a gap takes the full state of the writer that removed the
+subtree without throwing, and ends at its state vector), the random corpus's
+raw adapter (seed 140 passes: its pin is gone).
+
+### YP24 — one string table per update (`src/utils/UpdateEncoder.js`, `src/utils/UpdateDecoder.js`, `src/structs/Item.js`, `src/utils/updates.js`, `src/utils/BlockSet.js`)
+
+Reason: the v2 encoding writes every map key, root name and string value
+in full, every time. Upstream's `writeKey` has a cache, commented out
+(`keyMap.set`) because decoders older than its own read format keys with
+`readString`, and map keys and root names do not go through it anyway
+(`writeString` in `Item#write`, `readString` in both struct readers). In an
+edytor document a block's id (12 characters) was written five times (its
+registry key, its `id` attr, its home slot `{ b }`, its record key, the
+boundary of the split that made it), and `"blocks"`, `"blockattr"`, `"id"`,
+`"type"`, `"paragraph"`, an actor's id, once per block each: about a fifth
+of a stored document. Design and measurements:
+`docs/archive/storage-diet/design.md`. Edytor's schema generation 10 is the
+cutover (no conversion).
+
+Patch (new code delimited by `// YP24 begin` / `// YP24 end`, edits marked `// YP24`):
+
+- **The string table.** `UpdateEncoder#writeKey` keeps its cache: a string
+  the update has written is its index. The key column (`keyClockEncoder`)
+  is a `UintOptRleEncoder` saying `0` for a new string (the next in the
+  string column) and the index plus one for a known one, so a key repeated
+  block after block is the same small number each time (gzip finds it; a
+  running difference, upstream's `IntDiffOptRle`, did not).
+  `UpdateDecoder#readKey` reads it back (an index past the table is
+  refused).
+- **Keys and root names through it.** `Item#write` writes a map entry's
+  key, a root parent's name and a string parent with `writeKey`; both
+  struct readers (`updates.js`, `BlockSet.js`) read them with `readKey`.
+  Node names and format keys already went through `writeKey`.
+- **Content values through it.** `writeAny`/`writeJSON` write lib0's
+  `writeAny` layout with every string and object key through the table
+  (`writeValue`); `readAny`/`readJSON` read it back (`readValue`). Numbers,
+  booleans, `null`, `undefined` and binary keep lib0's codec. Text
+  (`ContentString`) stays in the string column, never in the table.
+- **The encoding's name.** The update's first varuint, upstream's reserved
+  feature flag (`0`), says `1` (`UPDATE_ENCODING`); the decoder refuses an
+  update of another encoding before it reads anything (`an update of
+  another encoding`): an upstream update, or one of edytor's generations 6
+  to 9, is refused, never mis-read.
+
+The tables are built in write order, so an update is still a function of
+the store (byte-identical for identical stores, as the fork's differential
+rows check), and every path that re-encodes (`mergeUpdates`, `diffUpdate`,
+a block set's re-write, the room's stripped frames) writes through the
+encoder's own methods.
+
+Plain programs (every upstream test) are untouched in what they store; their
+bytes differ from upstream's.
+
+Measured: see `docs/archive/storage-diet/design.md` ("Prototype: measured").
+
+Oracle: the upstream suite (`updates.tests.js` merges, diffs and re-encodes
+every program), `src/tests/crdt/yp24-values.test.ts` (every value shape), `src/tests/crdt/yp16-writes.test.ts` and the baseline leg
+of `search-marker-format.test.ts` (the stores each engine reads back from
+its own encoding, `src/tests/crdt/harness/stored.js`, after every
+operation), `generation.test.ts` (an earlier encoding is refused before
+decode), `boundary-attacks/envelope.test.ts` (a v13 update inside a v14
+frame no longer integrates), the random corpus (every adapter).
+
+### YP25 — a paired mark's value is written in parts (`src/structs/Item.js`, `src/ynode.js`, `src/utils/updates.js`, `src/utils/BlockSet.js`)
+
+Reason: a paired mark (YP13) is a format item whose value is a JSON array —
+a start's `[v, l, c, k, side]` (its value, Lamport stamp, operation id and
+side), an end's `[c, k, side]` (its start's id) — written through
+`writeAny`, so a 53-bit client was a 9-byte float64 in every one, a start's
+operation id repeated the item's own id, and an end's repeated its start's,
+right before it: 33 bytes an item, 66 a mark. Design and measurements:
+`docs/archive/storage-diet/design.md`. Schema generation 10 (YP24's).
+
+Patch (new code delimited by `// YP25 begin` / `// YP25 end`, edits marked `// YP25`):
+
+- `ContentFormat#write` takes the item (`Item#write` passes itself to its
+  content's `write`) and writes, after its key, `writeFormatValue`: a flags
+  length — bit 0 the side; bit 1, for a start, its operation id is the
+  item's own (a redo's copy keeps the original's: then the id follows), for
+  an end, its start is the item's client's (the distance back to its clock
+  follows), else the start's id; bit 2 a start's value is `true`, bit 3
+  `null` — then a start's stamp (a length) and, unless implied, its id and
+  value. Any other value (a plain format, YP19's inert one; a value of
+  another shape) is flagged `16` and written whole.
+- `readContentFormat(decoder, id)` reads it back (`readFormatValue`, given
+  the item's id): both struct readers pass `readItemContent` the id they
+  create the item with.
+
+The value read back is the array written, so the mark rules (`foldPaired`,
+`markClass`) see what they saw. Plain programs keep their stores.
+
+Oracle: `src/tests/crdt/yp25-marks.test.ts` (every shape — own and copied
+ids, an end of another writer's start, `true`, `null`, string and object
+values, plain formats, values of another shape — read back through
+`applyUpdate`, `decodeUpdate`, `mergeUpdates` and `diffUpdate`, the same
+store giving the same bytes; a mark's cost), the mark rows (`mark.*`), the
+random corpus (every adapter).
+
+### YP26 — one client table per update (`src/utils/UpdateEncoder.js`, `src/utils/UpdateDecoder.js`, `src/utils/ids.js`)
+
+Reason: a client id (53 bits since v14: an 8-byte varint) was written in
+full wherever an update names it — each client's struct section, every
+origin, right origin and parent id, the delete set — and the client
+column's run-length code only helps while consecutive structs name one
+client. A document edited over many sessions (each page load is a client)
+names another session's text at most of its origins: 10 to 12 % of its
+bytes were client ids. Design and measurements:
+`docs/archive/storage-diet/design.md`. Schema generation 10 (YP24's).
+
+Patch (new code delimited by `// YP26 begin` / `// YP26 end`, edits marked `// YP26`):
+
+- `UpdateEncoder` keeps a client table: `clientIndex(client)` writes a
+  client's index in it, in first-use order, to the client column, and a new
+  client's index (the table's size) is followed there by its id, once;
+  `writeClient`, `writeLeftID` and `writeRightID` write through it.
+- `UpdateDecoder#readClient` (and `readLeftID`, `readRightID`) reads an
+  index: the table's size is a new client, whose id follows; one past the
+  table is refused (`an unknown client`).
+- The delete set's client goes through the same table: `writeIdSet` writes
+  it with `writeDsClient`, `readIdSet` and `readAndApplyDeleteSet` read it
+  with `readDsClient` (an `IdSetEncoder`/`IdSetDecoder` alone keeps the
+  plain varint).
+
+Every path that writes an update writes its clients through these methods
+(the struct sections, `writeStructs`, the lazy writer of `mergeUpdates` and
+`diffUpdate`, a block set's re-write, the room's stripped frames, the
+delete-only updates), in the order a reader reads them, so an update stays
+a function of the store. The state vector keeps its own encoding.
+
+Oracle: `src/tests/crdt/yp26-clients.test.ts` (twelve 53-bit sessions
+typing, deleting and syncing: their store reads back through `applyUpdate`,
+`decodeUpdate`, `mergeUpdates` and `diffUpdate`; two interleaved writers
+cost their ids once; an index past the table is refused), the upstream
+suite, the random corpus (every adapter).
+
+### YP27 — the parent kind in the info byte (`src/structs/Item.js`, `src/utils/UpdateEncoder.js`, `src/utils/UpdateDecoder.js`, `src/utils/updates.js`, `src/utils/BlockSet.js`, `src/ynode.js`)
+
+Reason: an item written with its parent (no origin, no right origin: a map
+entry's first value, a list's first item) said in a column of its own,
+`parentInfo` (a run-length code of a flag), whether the parent is a root
+(its name follows) or an item (its id follows). In an edytor document the
+flag alternates block after block (a registry entry under a root, then its
+attrs under the block's node), so the run-length code wrote two bytes a
+change: 8 bytes a block. Content refs fit four bits (0 to 12), so the
+info byte has room. Schema generation 10 (YP24's).
+
+Patch (edits marked `// YP27`): `Item#write` sets bit 5 (`BIT5`) of the
+info byte when the parent it writes is a root's name (or a string parent,
+the differential updates' edge case) and masks the content ref with
+`BITS4`; both struct readers read the bit instead of the column, and
+`readItemContent` masks with `BITS4`. `UpdateEncoder#writeParentInfo`,
+`UpdateDecoder#readParentInfo` and the `parentInfo` column are removed.
+
+Oracle: the upstream suite, every engine row reading stores back
+(`yp16-writes`, `yp25-marks`, `yp26-clients`), the random corpus (every
+adapter).
+
+### YP28 — large integers in content values (`src/utils/UpdateEncoder.js`, `src/utils/UpdateDecoder.js`)
+
+Reason: lib0's `writeAny` writes an integer past 31 bits as a float64 (9
+bytes). Edytor's values hold two kinds of them: a block's incarnation nonce
+(32 bits, written three times a block: the node's `n`, its record's `i`, the
+`n` of the boundary of the split that made it; past 2³¹ half the time) and
+a block slot's split key (`s: [client, clock]`, the id of that boundary: a
+53-bit client). Schema generation 10 (YP24's).
+
+Patch (edits marked `// YP28`, in YP24's value codec): an integer past 31
+bits a varint holds exactly is tag `115` and a varint; a two-element array
+of such an integer and a non-negative integer (an item id) is tag `114`,
+its first through the client table (YP26) and its second a varint. Both
+read back as the same number and the same array, whatever the value means.
+
+Oracle: `src/tests/crdt/yp24-values.test.ts` (every value shape — strings,
+nested objects and arrays, integers either side of 31 bits and of the safe
+range, floats, booleans, `null`, binary, pairs of every kind — reads back
+through `applyUpdate`, `mergeUpdates` and `diffUpdate`; a repeated string
+costs one table entry), the random corpus (every adapter).
+
+### YP29 — a collected mark or claim keeps only its class (`src/structs/Item.js`, `src/utils/marks.js`, `src/ynode.js`)
+
+Reason: YP13, YP21 and YP22 keep the content of every collected item whose
+sort class (`markClass`) is not content's: the class orders concurrent
+inserts at the item's origin on every replica, collected or not. A paired
+mark item's or a claim item's class is all a sort reads of it (two marks or
+two claims of one class at one origin sort by client id), yet each kept its
+key and value. Edytor's purge now deletes the marks of the streams it
+empties (`room.purge.what`), and an undone format operation's marks are
+collected too. A move record still keeps its content: the sort of two
+records at one origin reads their chains. Schema generation 10 (YP24's).
+
+Patch (new code delimited by `// YP29 begin` / `// YP29 end`, edits marked `// YP29`):
+
+- **A collected item's class** (`Item.js`): `ContentDeleted` takes an
+  optional `cls` (`0` a left-side mark, `2` a right-side one, `3` a claim)
+  for each of its units; with one it is content ref 13
+  (`readContentClass` in `ynode.js`'s `contentRefs`, its length and class
+  in one length word: `len · 4 + cls`), countable as the claim it was, not
+  as a mark; it splits and merges with its class, and integrates deleted as
+  any `ContentDeleted`.
+- `Item#gc` (an item of a live parent) gives a collected item of class 0 or
+  2, or a claim item every unit of which is a claim, a `ContentDeleted` of
+  its class; class 1 (content, a block slot's split key) and the move
+  records (4, 5) keep what they kept.
+- `markClass` reads a collected item's class first.
+
+Every reader of a mark or a claim reads live items only (`forward`,
+`findMarker`'s walk, `RangeCursor#_foldItem`, edytor's rows and scans), so
+a collected one's content was never read but by the sort.
+
+Oracle: `src/tests/crdt/yp21-claims.test.ts` (a collected claim item keeps
+its class, and a replica that receives it integrates it deleted, with its
+class), `purge-before-horizon.test.ts` (the marks of a stream the purge
+empties go; a live block keeps its own), the upstream suite
+(`encoding.tests.js` pins ref 13), the mark rows, the random corpus (every
+adapter).
+
+### YP30 — a transaction's `beforeCommit` (`src/utils/Transaction.js`, `src/utils/Doc.js`)
+
+Reason: edytor writes a replica's actor binding (`c/<clientID>`,
+`attr.binding.first-write`) with the replica's first write, inside that
+write's transaction, so a replica that only reads writes nothing and every
+struct a replica writes travels in the update that binds it. No event ran
+inside a transaction after its function: `beforeTransaction` comes before
+anything is written, `commit` after the transaction closed (a write there is
+a transaction of its own, a second update).
+
+Patch (new code delimited by `// YP30 begin` / `// YP30 end`): `transact`,
+for the outermost call, emits `beforeCommit` (transaction, doc) after the
+function returned or threw, while `doc._transaction` is still set, so a
+listener's writes join the transaction (its insert and delete sets, its one
+update, the `commit` fold); then the cleanup runs as before, also when a
+listener throws. Emitted only when the document has a listener. Not
+emitted for a nested call.
+
+Oracle: `src/tests/crdt/attribution/first-write-binding.test.ts` (the first
+local edit's one update carries the binding; a remote update writes none),
+the upstream suite.
+
 ## Generated declarations (`dts/`)
 
 `svelte-package` copies JS verbatim but emits no `.d.ts` for JS inputs, so
@@ -1019,7 +1566,7 @@ diff -r "$UP/tests" /tmp/yjs-tests-normalized
 Runner: `vendor-tests/yjs/upstream.test.js` registers every `testXxx(tc)`
 export as a vitest test with a real `lib0-v14/testing` `TestCase`.
 
-- `pnpm test:crdt` — **120 pass / 6 skipped / 0 failed** since YP19 (196/6
+- `pnpm test:crdt` — **120 pass / 6 skipped / 0 failed** since YP19, unchanged by YP20 (196/6
   since YP16, 216/6 since YP8, 325/6
   before; upstream standard tier; the 6 skips are upstream's own
   `t.skip(!t.production)` extensive-tier gates: 3× y-array, 3× y-map random