From b2233bf82cd9c3a7eae4e507ee5f309fd3ddf37a Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 15:29:06 -0700 Subject: [PATCH 1/9] fix(clock): skip autogrow request rows when taking the document floor observedDocCounter threw "malformed stamp tuple" on any document with an autogrow connect, because the applier keeps each grow's requested slot shape in __stamps under a ["grow_request", ...] key. Those rows carry no counter; skip them so producers can take a Lamport floor from real documents. Co-Authored-By: Claude Opus 5.5 (cherry picked from commit 26b6aeab6b2df2f11eb69e7bc9b02c2f873ac9b5) --- src/clock.ts | 6 ++++++ test/clock.test.ts | 23 ++++++++++++++++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/src/clock.ts b/src/clock.ts index ead003e..02ad7e9 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -70,9 +70,12 @@ export class DocDerivedLamportClockStore implements LamportClockStore { } } +const GROW_REQUEST_KEY_PREFIX = '["grow_request",'; + /** * Maximum counter across winning stamps and reservations in a current-schema * document. Missing ledgers are empty; missing/unsupported schema is refused. + * Autogrow request rows in `__stamps` carry no counter and are skipped. * Reads neither write structs nor create absent roots. */ export function observedDocCounter(doc: Y.Doc): number | undefined { @@ -86,6 +89,9 @@ export function observedDocCounter(doc: Y.Doc): number | undefined { if (root._start !== null) throw new TypeError(`${name} root contains non-map content`); const ledger = doc.getMap(name); // throws for a different concrete Y type ledger.forEach((value, key) => { + // An autogrow connect keeps its requested slot shape beside its stamp + // (applier growRequestKey); that row is not a stamp and has no counter. + if (name === ROOT_STAMPS && key.startsWith(GROW_REQUEST_KEY_PREFIX)) return; if (!Array.isArray(value) || value.length !== 3 || typeof value[1] !== "string" || typeof value[2] !== "string" || value[2].length === 0) { throw new TypeError(`${name} contains a malformed stamp tuple`); diff --git a/test/clock.test.ts b/test/clock.test.ts index 5e34128..7e92873 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -2,10 +2,12 @@ import * as Y from "yjs"; import { describe, expect, it, vi } from "vitest"; import { applyOps, DocDerivedLamportClockStore, freezeLamportEnvelope, MAX_LAMPORT_COUNTER, mint, migrate, observedDocCounter, observeLamport, persistLamportTick, project, readStamps, - SCHEMA_VERSION, tickLamport, validateLamportCounter, type LamportClockStore } from "../src/index.js"; + SCHEMA_VERSION, tickLamport, validateLamportCounter, type LamportClockStore, type WidgetCatalog, + type WorkflowJSON } from "../src/index.js"; import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); +const growCatalog: WidgetCatalog = { types: { Source: { widget_order: [] }, Destination: { widget_order: [] } } }; const identity = { workflow_id: "w", lineage_id: "l", producer_id: "agent:clock" }; const reservationKey = '["__lamport_clock","w","l","agent:clock"]'; @@ -117,6 +119,25 @@ describe("creator-owned Lamport counter", () => { )).rejects.toThrow(/Lamport counter/); }); + it("skips autogrow request rows when taking the floor of a real document", () => { + const io = (name: string, links: unknown) => ({ name, type: "IMAGE", ...(links === undefined ? {} : links as object) }); + const doc = mint({ + nodes: [ + { id: 1, type: "Source", pos: [0, 0], inputs: [], outputs: [io("out", { links: [] })], widgets_values: [] }, + { id: 2, type: "Destination", pos: [0, 0], inputs: [io("fixed", { link: null })], outputs: [], widgets_values: [] }, + ], + links: [], + } as unknown as WorkflowJSON, growCatalog); + applyOps(doc, [{ + op: "connect", op_id: "c".repeat(32), actor: "agent:t:1", base_version: 7, stamp: [7, "agent:t:1"], + link_id: 9, from_node: 1, from_slot: 0, to_node: 2, link_type: "IMAGE", + grow: { name: "images.image0", type: "IMAGE", widget: "upload" }, + }], growCatalog); + expect(Object.keys(readStamps(doc)).some((key) => key.startsWith('["grow_request",'))).toBe(true); + expect(observedDocCounter(doc)).toBe(7); + expect(observedDocCounter(replicaOf(doc))).toBe(7); + }); + it("keeps reservations out of public readStamps and preserves their identity tuple", async () => { const doc = mint({ nodes: [], links: [] }, catalog); const store = new DocDerivedLamportClockStore(doc); From a1c263294f0c10020d083375c67d65e25c9c78f6 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 15:39:08 -0700 Subject: [PATCH 2/9] fix(clock): also skip retained subgraph routes; pin what the skip leaves alone A deleted subgraph instance leaves its definition id in __stamps under an ["interior_route", ...] key, which made the floor read throw the same way. Skip both companion row kinds, and test that the grow's own stamp still counts and fails closed and that reservations are never skipped. Co-Authored-By: Claude Opus 5.5 (cherry picked from commit 733fbe3ca18660ca67017f001a9f1939c57067f8) --- src/clock.ts | 14 ++++++++------ test/clock.test.ts | 14 +++++++++++++- test/define-subgraph.test.ts | 23 +++++++++++++++++++++++ 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/src/clock.ts b/src/clock.ts index 02ad7e9..6039e4a 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -29,7 +29,8 @@ const documentTransactionTails = new WeakMap>(); * counter: the Y.Doc is the caller-owned lineage snapshot and this store's * transaction queue is the serialization boundary. * - * Both ledgers are validated rather than silently skipped. Malformed state + * Both ledgers are validated rather than silently skipped; only `__stamps` + * companion rows, which hold no counter, are passed over. Malformed state * must fail closed before a producer mints an unsafe counter. * Incarnation-qualified target keys all belong to this document lineage, so * old node lives remain part of the observed floor (DQ-11 / ADR-ORDERING-0021). A @@ -70,12 +71,15 @@ export class DocDerivedLamportClockStore implements LamportClockStore { } } -const GROW_REQUEST_KEY_PREFIX = '["grow_request",'; +// `__stamps` companion rows that ride beside a stamp but are not stamps: an +// autogrow connect's requested slot shape (applier growRequestKey) and a deleted +// subgraph instance's retained definition route (applier interiorRouteKey). +const COMPANION_KEY_PREFIXES = ['["grow_request",', '["interior_route",']; /** * Maximum counter across winning stamps and reservations in a current-schema * document. Missing ledgers are empty; missing/unsupported schema is refused. - * Autogrow request rows in `__stamps` carry no counter and are skipped. + * Companion rows in `__stamps` carry no counter and are skipped. * Reads neither write structs nor create absent roots. */ export function observedDocCounter(doc: Y.Doc): number | undefined { @@ -89,9 +93,7 @@ export function observedDocCounter(doc: Y.Doc): number | undefined { if (root._start !== null) throw new TypeError(`${name} root contains non-map content`); const ledger = doc.getMap(name); // throws for a different concrete Y type ledger.forEach((value, key) => { - // An autogrow connect keeps its requested slot shape beside its stamp - // (applier growRequestKey); that row is not a stamp and has no counter. - if (name === ROOT_STAMPS && key.startsWith(GROW_REQUEST_KEY_PREFIX)) return; + if (name === ROOT_STAMPS && COMPANION_KEY_PREFIXES.some((prefix) => key.startsWith(prefix))) return; if (!Array.isArray(value) || value.length !== 3 || typeof value[1] !== "string" || typeof value[2] !== "string" || value[2].length === 0) { throw new TypeError(`${name} contains a malformed stamp tuple`); diff --git a/test/clock.test.ts b/test/clock.test.ts index 7e92873..e389511 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -120,7 +120,7 @@ describe("creator-owned Lamport counter", () => { }); it("skips autogrow request rows when taking the floor of a real document", () => { - const io = (name: string, links: unknown) => ({ name, type: "IMAGE", ...(links === undefined ? {} : links as object) }); + const io = (name: string, links: object) => ({ name, type: "IMAGE", ...links }); const doc = mint({ nodes: [ { id: 1, type: "Source", pos: [0, 0], inputs: [], outputs: [io("out", { links: [] })], widgets_values: [] }, @@ -136,6 +136,18 @@ describe("creator-owned Lamport counter", () => { expect(Object.keys(readStamps(doc)).some((key) => key.startsWith('["grow_request",'))).toBe(true); expect(observedDocCounter(doc)).toBe(7); expect(observedDocCounter(replicaOf(doc))).toBe(7); + + // The skip covers only the request row: the grow's own stamp still counts and still fails closed. + const stamps = doc.getMap("__stamps"); + const growKey = [...stamps.keys()].find((key) => key.startsWith('["grow",'))!; + stamps.set(growKey, [9, "agent:t:1", "c".repeat(32)]); + expect(observedDocCounter(doc)).toBe(9); + stamps.set(growKey, ["images.image0", null, false]); + expect(() => observedDocCounter(doc)).toThrow(/malformed stamp tuple/); + // Reservations are never companion rows, whatever their key. + const reserved = mint({ nodes: [], links: [] }, catalog); + reserved.getMap("__clock_reservations").set('["grow_request","1","9","images"]', [3, "agent:clock", "x"]); + expect(() => observedDocCounter(reserved)).toThrow(TypeError); }); it("keeps reservations out of public readStamps and preserves their identity tuple", async () => { diff --git a/test/define-subgraph.test.ts b/test/define-subgraph.test.ts index 824b7b5..2f39d05 100644 --- a/test/define-subgraph.test.ts +++ b/test/define-subgraph.test.ts @@ -4,7 +4,10 @@ import { describe, expect, it } from "vitest" import { applyOps, + DocDerivedLamportClockStore, mint, + observedDocCounter, + persistLamportTick, project, type DefineSubgraphOp, type Op, @@ -384,6 +387,26 @@ describe("define_subgraph application", () => { expect(results.map(({ retainedRoute }) => retainedRoute)).toEqual([subgraphId, subgraphId]) }) + it("keeps the Lamport floor readable after a subgraph instance is deleted", async () => { + const instanceId = "dddddddd-dddd-4ddd-8ddd-dddddddddddd" + const doc = mint({ + nodes: [{ id: instanceId, type: subgraphId, inputs: [], outputs: [] }], + links: [], definitions: { subgraphs: [definition()] }, + } as unknown as WorkflowJSON, catalog) + const remove = { + op: "delete_node", node_id: instanceId, removed_links: [], + op_id: "f".repeat(32), actor: "human:delete", base_version: 5, stamp: [5, "human:delete"], + } as Op + expect(applyOps(doc, [remove], catalog).outcomes[0]?.outcome).toBe("applied") + expect(stampsMap(doc).get(JSON.stringify(["interior_route", instanceId, "0"]))).toBe(subgraphId) + + const replica = new Y.Doc() + Y.applyUpdate(replica, Y.encodeStateAsUpdate(doc)) + expect([observedDocCounter(doc), observedDocCounter(replica)]).toEqual([5, 5]) + const identity = { workflow_id: "w", lineage_id: "l", producer_id: "agent:clock" } + await expect(persistLamportTick(new DocDerivedLamportClockStore(doc), identity, [])).resolves.toBe(6) + }) + it("shares the canonical register between a retained instance route and a direct definition path", () => { const instanceId = "cccccccc-cccc-4ccc-8ccc-cccccccccccc" const doc = mint({ From 1f40da3396be7e7af179322d285326c280828c69 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 15:45:38 -0700 Subject: [PATCH 3/9] docs(clock): describe __stamps companion rows; guard the floor in the op-pool sweep Every generated op-pool document now asserts its Lamport floor is readable, so a new counterless __stamps row fails a test instead of producers. Co-Authored-By: Claude Opus 5.5 (cherry picked from commit e88fec42fdffc4fe50aafc5f02eede5e50ac6f5f) --- src/clock.ts | 2 +- src/doc.ts | 3 ++- src/read.ts | 3 ++- test/clock.test.ts | 2 +- test/permutation/full-op-pool.permutation.test.ts | 3 +++ 5 files changed, 9 insertions(+), 4 deletions(-) diff --git a/src/clock.ts b/src/clock.ts index 6039e4a..6ac0dba 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -36,7 +36,7 @@ const documentTransactionTails = new WeakMap>(); * old node lives remain part of the observed floor (DQ-11 / ADR-ORDERING-0021). A * successful transaction writes `__clock_reservations` so the next transaction * observes it even before the producer's semantic op is applied. `__stamps` - * remains exclusively the semantic write-target ledger exposed by readStamps. + * remains the semantic write-target ledger exposed by readStamps. */ export class DocDerivedLamportClockStore implements LamportClockStore { public constructor(private readonly doc: Y.Doc) {} diff --git a/src/doc.ts b/src/doc.ts index e4b93b4..c3cb1a2 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -17,7 +17,8 @@ * ├── Y.Map '__applied' — op_id → sha256 of the canonical op payload * │ (idempotency + op_id-reuse detection, §4 * │ amendment A8; a legacy `1` is a pre-A8 record) - * ├── Y.Map '__stamps' — write-target key → [base_version, actor, op_id] (§4) + * ├── Y.Map '__stamps' — write-target key → [base_version, actor, op_id] (§4), + * │ plus counterless grow_request / interior_route rows * ├── Y.Map '__link_state' — normalized link id → durable descriptor (§1.5) * └── Y.Map '__clock_reservations' — producer identity → reserved counter tuple (§1.6) */ diff --git a/src/read.ts b/src/read.ts index 07b33e1..34a7b29 100644 --- a/src/read.ts +++ b/src/read.ts @@ -472,7 +472,8 @@ export function readApplied(doc: Y.Doc): Readonly> { * The LWW ledger as plain frozen data: write-target key → * `[base_version, actor, op_id]` (schema §3/§4). This is where per-op actor * attribution is durably observable, and it is what a cross-language - * conformance harness compares — no projection contains it. + * conformance harness compares — no projection contains it. It also carries + * counterless `grow_request` / `interior_route` companion rows. */ export function readStamps(doc: Y.Doc): Readonly> { assertSnapshotReadable(doc, "readStamps"); diff --git a/test/clock.test.ts b/test/clock.test.ts index e389511..e4bae16 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -133,7 +133,7 @@ describe("creator-owned Lamport counter", () => { link_id: 9, from_node: 1, from_slot: 0, to_node: 2, link_type: "IMAGE", grow: { name: "images.image0", type: "IMAGE", widget: "upload" }, }], growCatalog); - expect(Object.keys(readStamps(doc)).some((key) => key.startsWith('["grow_request",'))).toBe(true); + expect([...doc.getMap("__stamps").keys()].some((key) => key.startsWith('["grow_request",'))).toBe(true); expect(observedDocCounter(doc)).toBe(7); expect(observedDocCounter(replicaOf(doc))).toBe(7); diff --git a/test/permutation/full-op-pool.permutation.test.ts b/test/permutation/full-op-pool.permutation.test.ts index 44e5440..2da027f 100644 --- a/test/permutation/full-op-pool.permutation.test.ts +++ b/test/permutation/full-op-pool.permutation.test.ts @@ -26,6 +26,7 @@ import { FROZEN_OPS, applyOps, mint, + observedDocCounter, project, type Op, type WireOp, @@ -287,6 +288,8 @@ function run( } } for (const group of groups) applyGroup(group); + // Every document the applier produces must keep a readable Lamport floor. + expect(() => observedDocCounter(doc)).not.toThrow(); const appliedIds = new Set(doc.getMap("__applied").keys()); for (const outcome of outcomes) { if (outcome.outcome === "rejected") expect(appliedIds.has(outcome.opId)).toBe(false); From 337288ffd58a13b6f1bf68dbcb1775e39c8c5595 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 16:11:02 -0700 Subject: [PATCH 4/9] feat(clock): opt-in skipMalformed floor read for producers that must keep minting observedDocCounter(doc) still fails closed on a malformed row (ADR-021). observedDocCounter(doc, { skipMalformed: true }) returns the maximum over the readable rows of both ledgers plus the count it passed over, so a producer can stamp above every valid counter instead of refusing or dropping to zero. Co-Authored-By: Claude Opus 5.5 (cherry picked from commit 14b33ac5ab2c7b4ccdbe7119b58986cfa8574c96) --- src/clock.ts | 42 +++++++++++++++++++++++++++++++++++------- test/clock.test.ts | 17 +++++++++++++++++ 2 files changed, 52 insertions(+), 7 deletions(-) diff --git a/src/clock.ts b/src/clock.ts index 6ac0dba..d019eb8 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -76,15 +76,32 @@ export class DocDerivedLamportClockStore implements LamportClockStore { // subgraph instance's retained definition route (applier interiorRouteKey). const COMPANION_KEY_PREFIXES = ['["grow_request",', '["interior_route",']; +/** Result of a lenient floor read: the maximum valid counter and how many rows were unreadable. */ +export interface LenientDocCounter { + counter: number | undefined; + skipped: number; +} + /** * Maximum counter across winning stamps and reservations in a current-schema * document. Missing ledgers are empty; missing/unsupported schema is refused. * Companion rows in `__stamps` carry no counter and are skipped. * Reads neither write structs nor create absent roots. + * + * By default a malformed row throws (fail closed, ADR-021). With + * `skipMalformed`, a producer that must keep minting gets the maximum over the + * readable rows instead, plus the count of rows it passed over; an unreadable + * schema or ledger root still throws. */ -export function observedDocCounter(doc: Y.Doc): number | undefined { +export function observedDocCounter(doc: Y.Doc): number | undefined; +export function observedDocCounter(doc: Y.Doc, options: { skipMalformed: true }): LenientDocCounter; +export function observedDocCounter( + doc: Y.Doc, + options?: { skipMalformed: true }, +): number | undefined | LenientDocCounter { assertReadableSchema(doc, "observedDocCounter"); let maximum: number | undefined; + let skipped = 0; for (const name of [ROOT_STAMPS, ROOT_CLOCK_RESERVATIONS]) { const root = doc.share.get(name); if (root === undefined) continue; @@ -94,16 +111,27 @@ export function observedDocCounter(doc: Y.Doc): number | undefined { const ledger = doc.getMap(name); // throws for a different concrete Y type ledger.forEach((value, key) => { if (name === ROOT_STAMPS && COMPANION_KEY_PREFIXES.some((prefix) => key.startsWith(prefix))) return; - if (!Array.isArray(value) || value.length !== 3 || typeof value[1] !== "string" || - typeof value[2] !== "string" || value[2].length === 0) { - throw new TypeError(`${name} contains a malformed stamp tuple`); + let counter: number; + try { + counter = ledgerRowCounter(name, key, value); + } catch (error) { + if (options?.skipMalformed !== true) throw error; + skipped++; + return; } - if (name === ROOT_CLOCK_RESERVATIONS) validateReservation(key, value[1], value[2]); - const counter = validateLamportCounter(value[0], name === ROOT_STAMPS); maximum = maximum === undefined ? counter : Math.max(maximum, counter); }); } - return maximum; + return options?.skipMalformed === true ? { counter: maximum, skipped } : maximum; +} + +function ledgerRowCounter(name: string, key: string, value: unknown): number { + if (!Array.isArray(value) || value.length !== 3 || typeof value[1] !== "string" || + typeof value[2] !== "string" || value[2].length === 0) { + throw new TypeError(`${name} contains a malformed stamp tuple`); + } + if (name === ROOT_CLOCK_RESERVATIONS) validateReservation(key, value[1], value[2]); + return validateLamportCounter(value[0], name === ROOT_STAMPS); } function validateReservation(key: string, producer: string, storedKey: string): void { diff --git a/test/clock.test.ts b/test/clock.test.ts index e4bae16..3a36cc1 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -150,6 +150,23 @@ describe("creator-owned Lamport counter", () => { expect(() => observedDocCounter(reserved)).toThrow(TypeError); }); + it("skips malformed rows only when asked, across both ledgers", async () => { + const doc = mint({ nodes: [], links: [] }, catalog); + await persistLamportTick(new DocDerivedLamportClockStore(doc), identity, [19]); + const stamps = doc.getMap("__stamps"); + stamps.set('["widget","1","0","seed"]', [12, "agent:t:1", "a".repeat(32)]); + stamps.set('["grow_request","1","9","images"]', ["images.image0", null, false]); + stamps.set("bad", [Number.NaN, "agent:bad", "c".repeat(32)]); + doc.getMap("__clock_reservations").set('["__lamport_clock","w","l","other"]', [99, "someone", "x"]); + + expect(() => observedDocCounter(doc)).toThrow(/Lamport counter/); + expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 20, skipped: 2 }); + expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 20, skipped: 2 }); + expect(observedDocCounter(mint({ nodes: [], links: [] }, catalog), { skipMalformed: true })) + .toEqual({ counter: undefined, skipped: 0 }); + expect(() => observedDocCounter(new Y.Doc(), { skipMalformed: true })).toThrow(); + }); + it("keeps reservations out of public readStamps and preserves their identity tuple", async () => { const doc = mint({ nodes: [], links: [] }, catalog); const store = new DocDerivedLamportClockStore(doc); From 45bbbfeff2dcf847c3d566aa543e1c7911019d2f Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 16:55:39 -0700 Subject: [PATCH 5/9] refactor(clock): share companion-row tags with the applier; amend the schema doc The floor read's companion prefixes are derived from GROW_REQUEST_TAG and INTERIOR_ROUTE_TAG in doc.ts, which the applier's key builders also use. Amendment A25 records the companion skip and the opt-in lenient read. The lenient tests now cover null rows, non-JSON reservation keys and a non-map ledger root, which still throws. Co-Authored-By: Claude Opus 5.5 (cherry picked from commit a226b3a7cff36ea6e723cb00b435acbe95586839) --- docs/multiplayer-schema.md | 12 ++++++++++++ src/applier.ts | 6 ++++-- src/clock.ts | 10 +++++----- src/doc.ts | 3 +++ test/clock.test.ts | 11 ++++++++--- test/permutation/full-op-pool.permutation.test.ts | 2 +- 6 files changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 8fe4e58..73eb930 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2602,3 +2602,15 @@ persists, so KA-11 does not require a layout bump or migration. An opt-in `dynamic_groups` catalog entry expands a saved row-count controller into indexed widget identities. These use the existing name-keyed registers; no op kind or on-document key changes. The new catalog hash requires coordinated reader adoption. Existing documents retain their original catalog and are re-minted to adopt the new layout. Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; supplied group metadata adds row-count bound validation (`min` to the allocation bound) and rejects a count change requiring a new declaration before mutation. This validation applies to the addressed occurrence in top-level, interior, and promoted writes. A count outside that range is rejected `dynamic_group_count_out_of_range`, whether it arrives as a `set_widget` value or as a saved count in an `add_node` or `insert_workflow` payload (including its definitions); a count change against a declared form is rejected `dynamic_group_form_mismatch`. Both are new rejection codes, so callers can count DynamicGroup refusals without parsing messages. A row-field name that no group row can address keeps `unknown_widget`, as any other unknown widget name does. Without group metadata, the package cannot identify count fields; compatible producer/catalog/reader admission remains the caller's responsibility. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance. + +## Amendment A27 — 2026-11-01 — Lamport floor reads past companion rows; opt-in lenient read (no schema change) + +§1.6 says `observedDocCounter()` validates every tuple and that a malformed entry fails the entire scan. The applier itself writes two `__stamps` rows that are not stamp tuples and carry no counter: +- `["grow_request", to_node, grow_id, family]`: an autogrow connect's requested slot shape, `[name, widget | null, isInputcount]`. +- `["interior_route", instance_id, incarnation]`: a deleted subgraph instance's retained definition id, a string. + +So one autogrow connect or one subgraph-instance delete made the floor unreadable for every later producer admission on that document. + +`observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). + +A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable rows of both ledgers, and the number of rows it passed over. An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. diff --git a/src/applier.ts b/src/applier.ts index 078d907..a061ce6 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -101,6 +101,8 @@ import { resolveDefinition, stampsMap, widgetStorageOf, + GROW_REQUEST_TAG, + INTERIOR_ROUTE_TAG, } from "./doc.js"; import { declaresWidgetForm, @@ -2173,7 +2175,7 @@ interface InteriorResolution { } function interiorRouteKey(instanceId: string, incarnation: string): string { - return JSON.stringify(["interior_route", instanceId, incarnation]); + return JSON.stringify([INTERIOR_ROUTE_TAG, instanceId, incarnation]); } function resolveInteriorNode( @@ -3083,7 +3085,7 @@ type GrowRequest = [string, string | null, boolean]; /** `__stamps` key holding a grow's own request, companion to its `["grow", ...]` stamp. */ function growRequestKey(toNode: unknown, growId: unknown, family: string): string { - return JSON.stringify(["grow_request", String(toNode), String(growId), family]); + return JSON.stringify([GROW_REQUEST_TAG, String(toNode), String(growId), family]); } /** diff --git a/src/clock.ts b/src/clock.ts index d019eb8..8117cdc 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -1,5 +1,5 @@ import * as Y from "yjs"; -import { ROOT_CLOCK_RESERVATIONS, ROOT_STAMPS } from "./doc.js"; +import { GROW_REQUEST_TAG, INTERIOR_ROUTE_TAG, ROOT_CLOCK_RESERVATIONS, ROOT_STAMPS } from "./doc.js"; import { assertReadableSchema } from "./schema-version.js"; import type { Actor } from "./types.js"; @@ -71,10 +71,10 @@ export class DocDerivedLamportClockStore implements LamportClockStore { } } -// `__stamps` companion rows that ride beside a stamp but are not stamps: an -// autogrow connect's requested slot shape (applier growRequestKey) and a deleted -// subgraph instance's retained definition route (applier interiorRouteKey). -const COMPANION_KEY_PREFIXES = ['["grow_request",', '["interior_route",']; +// Counterless `__stamps` rows (doc.ts companion tags), matched on the canonical +// JSON.stringify key prefix the applier writes. +const COMPANION_KEY_PREFIXES = [GROW_REQUEST_TAG, INTERIOR_ROUTE_TAG] + .map((tag) => `${JSON.stringify([tag]).slice(0, -1)},`); /** Result of a lenient floor read: the maximum valid counter and how many rows were unreadable. */ export interface LenientDocCounter { diff --git a/src/doc.ts b/src/doc.ts index c3cb1a2..2e5eb2d 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -279,6 +279,9 @@ export const ROOT_META = "meta"; export const ROOT_APPLIED = "__applied"; export const ROOT_STAMPS = "__stamps"; export const ROOT_LINK_STATE = "__link_state"; +/** `__stamps` companion-row key tags: counterless rows written beside a stamp. */ +export const GROW_REQUEST_TAG = "grow_request"; +export const INTERIOR_ROUTE_TAG = "interior_route"; /** Created lazily by a successful clock admission, never exported from the entrypoint. */ export const ROOT_CLOCK_RESERVATIONS = "__clock_reservations"; diff --git a/test/clock.test.ts b/test/clock.test.ts index 3a36cc1..264bac8 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -157,14 +157,19 @@ describe("creator-owned Lamport counter", () => { stamps.set('["widget","1","0","seed"]', [12, "agent:t:1", "a".repeat(32)]); stamps.set('["grow_request","1","9","images"]', ["images.image0", null, false]); stamps.set("bad", [Number.NaN, "agent:bad", "c".repeat(32)]); + stamps.set("null-row", null); doc.getMap("__clock_reservations").set('["__lamport_clock","w","l","other"]', [99, "someone", "x"]); + doc.getMap("__clock_reservations").set("not json", [98, "someone", "not json"]); expect(() => observedDocCounter(doc)).toThrow(/Lamport counter/); - expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 20, skipped: 2 }); - expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 20, skipped: 2 }); + expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 20, skipped: 4 }); + expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 20, skipped: 4 }); expect(observedDocCounter(mint({ nodes: [], links: [] }, catalog), { skipMalformed: true })) .toEqual({ counter: undefined, skipped: 0 }); - expect(() => observedDocCounter(new Y.Doc(), { skipMalformed: true })).toThrow(); + expect(() => observedDocCounter(new Y.Doc(), { skipMalformed: true })).toThrow(/schema/); + const brokenRoot = mint({ nodes: [], links: [] }, catalog); + brokenRoot.getArray("__clock_reservations").push([[5, "agent:clock", "x"]]); + expect(() => observedDocCounter(replicaOf(brokenRoot), { skipMalformed: true })).toThrow(/non-map content/); }); it("keeps reservations out of public readStamps and preserves their identity tuple", async () => { diff --git a/test/permutation/full-op-pool.permutation.test.ts b/test/permutation/full-op-pool.permutation.test.ts index 2da027f..e55d617 100644 --- a/test/permutation/full-op-pool.permutation.test.ts +++ b/test/permutation/full-op-pool.permutation.test.ts @@ -288,7 +288,7 @@ function run( } } for (const group of groups) applyGroup(group); - // Every document the applier produces must keep a readable Lamport floor. + // Every document this pool produces must keep a readable Lamport floor. expect(() => observedDocCounter(doc)).not.toThrow(); const appliedIds = new Set(doc.getMap("__applied").keys()); for (const outcome of outcomes) { From 682977b78acd3a90f142bdfbc9c7f4e62fbb52e6 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 17:05:45 -0700 Subject: [PATCH 6/9] refactor(clock): write the companion prefixes plainly; pin the prefix boundary skipped counts malformed rows only; the docs now say companion rows are not counted. Tests pin that a neighbouring or nested tag still fails closed. Co-Authored-By: Claude Opus 5.5 (cherry picked from commit be9f782951fd6327ebe48d2e96cb5feff44e54b5) --- docs/multiplayer-schema.md | 2 +- src/clock.ts | 6 +++--- test/clock.test.ts | 11 +++++++++-- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 73eb930..539b8c9 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2613,4 +2613,4 @@ So one autogrow connect or one subgraph-instance delete made the floor unreadabl `observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). -A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable rows of both ledgers, and the number of rows it passed over. An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. +A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable rows of both ledgers, and the number of malformed rows it skipped (companion rows are not counted). An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. diff --git a/src/clock.ts b/src/clock.ts index 8117cdc..127c4de 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -73,8 +73,7 @@ export class DocDerivedLamportClockStore implements LamportClockStore { // Counterless `__stamps` rows (doc.ts companion tags), matched on the canonical // JSON.stringify key prefix the applier writes. -const COMPANION_KEY_PREFIXES = [GROW_REQUEST_TAG, INTERIOR_ROUTE_TAG] - .map((tag) => `${JSON.stringify([tag]).slice(0, -1)},`); +const COMPANION_KEY_PREFIXES = [GROW_REQUEST_TAG, INTERIOR_ROUTE_TAG].map((tag) => `["${tag}",`); /** Result of a lenient floor read: the maximum valid counter and how many rows were unreadable. */ export interface LenientDocCounter { @@ -90,7 +89,8 @@ export interface LenientDocCounter { * * By default a malformed row throws (fail closed, ADR-021). With * `skipMalformed`, a producer that must keep minting gets the maximum over the - * readable rows instead, plus the count of rows it passed over; an unreadable + * readable rows instead, plus the count of malformed rows skipped (companion + * rows are not counted); an unreadable * schema or ledger root still throws. */ export function observedDocCounter(doc: Y.Doc): number | undefined; diff --git a/test/clock.test.ts b/test/clock.test.ts index 264bac8..bb8b900 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -139,11 +139,18 @@ describe("creator-owned Lamport counter", () => { // The skip covers only the request row: the grow's own stamp still counts and still fails closed. const stamps = doc.getMap("__stamps"); - const growKey = [...stamps.keys()].find((key) => key.startsWith('["grow",'))!; + const growKey = [...stamps.keys()].find((key) => key.startsWith('["grow",')); + if (growKey === undefined) throw new Error("the autogrow connect wrote no grow stamp"); stamps.set(growKey, [9, "agent:t:1", "c".repeat(32)]); expect(observedDocCounter(doc)).toBe(9); stamps.set(growKey, ["images.image0", null, false]); expect(() => observedDocCounter(doc)).toThrow(/malformed stamp tuple/); + // Only an exact leading companion tag is skipped: a neighbouring tag or a nested one still fails closed. + for (const key of ['["grow_request_x","1"]', '["widget",["grow_request","1"]]']) { + const neighbour = mint({ nodes: [], links: [] }, catalog); + neighbour.getMap("__stamps").set(key, ["not", "a", "stamp"]); + expect(() => observedDocCounter(neighbour), key).toThrow(/Lamport counter/); + } // Reservations are never companion rows, whatever their key. const reserved = mint({ nodes: [], links: [] }, catalog); reserved.getMap("__clock_reservations").set('["grow_request","1","9","images"]', [3, "agent:clock", "x"]); @@ -161,7 +168,7 @@ describe("creator-owned Lamport counter", () => { doc.getMap("__clock_reservations").set('["__lamport_clock","w","l","other"]', [99, "someone", "x"]); doc.getMap("__clock_reservations").set("not json", [98, "someone", "not json"]); - expect(() => observedDocCounter(doc)).toThrow(/Lamport counter/); + expect(() => observedDocCounter(doc)).toThrow(/Lamport counter|malformed stamp tuple/); expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 20, skipped: 4 }); expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 20, skipped: 4 }); expect(observedDocCounter(mint({ nodes: [], links: [] }, catalog), { skipMalformed: true })) From cbb5b4ef0cc276284081c04bbbad090720fc9bee Mon Sep 17 00:00:00 2001 From: bymyself Date: Sun, 1 Nov 2026 08:51:12 +0000 Subject: [PATCH 7/9] fix(clock): keep a malformed row's readable counter in the lenient floor; skip companion rows by value shape Lenient mode dropped a malformed row entirely, so a row like [900, 42, op] could leave the floor at a lower readable counter and the producer would mint under it. Count a valid first element even when the row is skipped. Companion rows are now skipped only when their value has the shape the applier stores (string for interior_route, [string, string|null, boolean] for grow_request), so a counter under a companion-looking key is still counted. --- docs/multiplayer-schema.md | 4 ++-- src/clock.ts | 40 ++++++++++++++++++++++++++++++-------- test/clock.test.ts | 33 +++++++++++++++++++++++++++++-- 3 files changed, 65 insertions(+), 12 deletions(-) diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 539b8c9..0f53be8 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2611,6 +2611,6 @@ Count writes change the projected layout, retaining hidden registers and applyin So one autogrow connect or one subgraph-instance delete made the floor unreadable for every later producer admission on that document. -`observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). +`observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag and whose value has the shape the applier stores there (a string for `interior_route`; `[string, string | null, boolean]` for `grow_request`). A companion-keyed row holding anything else is read as an ordinary row, so a counter can never hide behind a companion-looking key. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). -A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable rows of both ledgers, and the number of malformed rows it skipped (companion rows are not counted). An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. +A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable counters of both ledgers, and the number of malformed rows (companion rows are not counted). A malformed row whose first element is still a valid counter raises the floor: over-estimating the floor is safe, under-estimating it would let the producer mint under a counter already in the document. A caller that sees `skipped > 0` should log it. An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. diff --git a/src/clock.ts b/src/clock.ts index 127c4de..92d1e10 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -72,8 +72,30 @@ export class DocDerivedLamportClockStore implements LamportClockStore { } // Counterless `__stamps` rows (doc.ts companion tags), matched on the canonical -// JSON.stringify key prefix the applier writes. -const COMPANION_KEY_PREFIXES = [GROW_REQUEST_TAG, INTERIOR_ROUTE_TAG].map((tag) => `["${tag}",`); +// JSON.stringify key prefix the applier writes AND on the value shape the +// applier stores there, so a counter under a companion-looking key is never +// silently dropped from the floor. +const GROW_REQUEST_PREFIX = `["${GROW_REQUEST_TAG}",`; +const INTERIOR_ROUTE_PREFIX = `["${INTERIOR_ROUTE_TAG}",`; + +function isCompanionRow(key: string, value: unknown): boolean { + if (key.startsWith(INTERIOR_ROUTE_PREFIX)) return typeof value === "string"; + if (key.startsWith(GROW_REQUEST_PREFIX)) { + // applier GrowRequest: [name, widget | null, isInputcount] + return Array.isArray(value) && value.length === 3 && typeof value[0] === "string" && + (value[1] === null || typeof value[1] === "string") && typeof value[2] === "boolean"; + } + return false; +} + +// A malformed row still raises a lenient floor when its first element is a +// valid counter: over-estimating the floor is safe, under-estimating it lets a +// producer mint under a counter already in the document. +function salvageCounter(value: unknown): number | undefined { + if (!Array.isArray(value)) return undefined; + const counter: unknown = value[0]; + return typeof counter === "number" && Number.isSafeInteger(counter) && counter >= 0 ? counter : undefined; +} /** Result of a lenient floor read: the maximum valid counter and how many rows were unreadable. */ export interface LenientDocCounter { @@ -89,9 +111,10 @@ export interface LenientDocCounter { * * By default a malformed row throws (fail closed, ADR-021). With * `skipMalformed`, a producer that must keep minting gets the maximum over the - * readable rows instead, plus the count of malformed rows skipped (companion - * rows are not counted); an unreadable - * schema or ledger root still throws. + * readable counters instead (a malformed row whose first element is a valid + * counter still raises it), plus the count of malformed rows (companion rows + * are not counted). A caller that sees `skipped > 0` should log it. An + * unreadable schema or ledger root still throws. */ export function observedDocCounter(doc: Y.Doc): number | undefined; export function observedDocCounter(doc: Y.Doc, options: { skipMalformed: true }): LenientDocCounter; @@ -110,14 +133,15 @@ export function observedDocCounter( if (root._start !== null) throw new TypeError(`${name} root contains non-map content`); const ledger = doc.getMap(name); // throws for a different concrete Y type ledger.forEach((value, key) => { - if (name === ROOT_STAMPS && COMPANION_KEY_PREFIXES.some((prefix) => key.startsWith(prefix))) return; - let counter: number; + if (name === ROOT_STAMPS && isCompanionRow(key, value)) return; + let counter: number | undefined; try { counter = ledgerRowCounter(name, key, value); } catch (error) { if (options?.skipMalformed !== true) throw error; skipped++; - return; + counter = salvageCounter(value); + if (counter === undefined) return; } maximum = maximum === undefined ? counter : Math.max(maximum, counter); }); diff --git a/test/clock.test.ts b/test/clock.test.ts index bb8b900..f9e29de 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -169,8 +169,10 @@ describe("creator-owned Lamport counter", () => { doc.getMap("__clock_reservations").set("not json", [98, "someone", "not json"]); expect(() => observedDocCounter(doc)).toThrow(/Lamport counter|malformed stamp tuple/); - expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 20, skipped: 4 }); - expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 20, skipped: 4 }); + // The mis-keyed reservation (producer "someone" vs key "other") is malformed but its counter 99 is + // readable: a floor below it would let the producer mint under a counter already in the document. + expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 99, skipped: 4 }); + expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 99, skipped: 4 }); expect(observedDocCounter(mint({ nodes: [], links: [] }, catalog), { skipMalformed: true })) .toEqual({ counter: undefined, skipped: 0 }); expect(() => observedDocCounter(new Y.Doc(), { skipMalformed: true })).toThrow(/schema/); @@ -179,6 +181,33 @@ describe("creator-owned Lamport counter", () => { expect(() => observedDocCounter(replicaOf(brokenRoot), { skipMalformed: true })).toThrow(/non-map content/); }); + it("keeps a malformed row's readable counter in the lenient floor", () => { + const doc = mint({ nodes: [], links: [] }, catalog); + const stamps = doc.getMap("__stamps"); + stamps.set('["widget","1","0","seed"]', [50, "agent:t:1", "a".repeat(32)]); + stamps.set('["widget","1","0","cfg"]', [900, 42, "b".repeat(32)]); + expect(() => observedDocCounter(doc)).toThrow(/malformed stamp tuple/); + expect(observedDocCounter(doc, { skipMalformed: true })).toEqual({ counter: 900, skipped: 1 }); + expect(observedDocCounter(replicaOf(doc), { skipMalformed: true })).toEqual({ counter: 900, skipped: 1 }); + }); + + it("skips a companion-keyed row only when its value has the companion shape", () => { + const counted = mint({ nodes: [], links: [] }, catalog); + counted.getMap("__stamps").set('["grow_request","1","9","images"]', [50, "agent:t:1", "a".repeat(32)]); + counted.getMap("__stamps").set('["interior_route","3","inc"]', [60, "agent:t:1", "b".repeat(32)]); + expect(observedDocCounter(counted)).toBe(60); + for (const value of [{ x: 1 }, 5, ["images.image0", null], ["images.image0", 3, false]]) { + const odd = mint({ nodes: [], links: [] }, catalog); + odd.getMap("__stamps").set('["grow_request","1","9","images"]', value); + expect(() => observedDocCounter(odd), JSON.stringify(value)).toThrow(TypeError); + } + const route = mint({ nodes: [], links: [] }, catalog); + route.getMap("__stamps").set('["interior_route","3","inc"]', ["images.image0", null, false]); + expect(() => observedDocCounter(route)).toThrow(TypeError); + route.getMap("__stamps").set('["interior_route","3","inc"]', "definition-id"); + expect(observedDocCounter(route)).toBeUndefined(); + }); + it("keeps reservations out of public readStamps and preserves their identity tuple", async () => { const doc = mint({ nodes: [], links: [] }, catalog); const store = new DocDerivedLamportClockStore(doc); From c7a92ab72812d793fa27111abda1f450568dbd10 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sun, 1 Nov 2026 08:56:54 +0000 Subject: [PATCH 8/9] fix(clock): skip any grow_request row that cannot carry a counter The applier stores a grow's widget field as sent, so a grow with a non-string widget wrote a row the exact-shape check rejected, and the strict floor became unreadable again after one such connect. Skip a grow_request row whenever its first element is not a number; a counter-shaped row under that key is still counted. --- docs/multiplayer-schema.md | 2 +- src/clock.ts | 9 ++++----- test/clock.test.ts | 20 +++++++++++++++++++- 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 0f53be8..a1a37b8 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2611,6 +2611,6 @@ Count writes change the projected layout, retaining hidden registers and applyin So one autogrow connect or one subgraph-instance delete made the floor unreadable for every later producer admission on that document. -`observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag and whose value has the shape the applier stores there (a string for `interior_route`; `[string, string | null, boolean]` for `grow_request`). A companion-keyed row holding anything else is read as an ordinary row, so a counter can never hide behind a companion-looking key. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). +`observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag and whose value has the shape the applier stores there (a string for `interior_route`; an array whose first element is not a number for `grow_request`, whose rows are `[name, widget, isInputcount]` with the grow's widget stored as sent). A companion-keyed row holding anything else is read as an ordinary row, so a counter can never hide behind a companion-looking key. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable counters of both ledgers, and the number of malformed rows (companion rows are not counted). A malformed row whose first element is still a valid counter raises the floor: over-estimating the floor is safe, under-estimating it would let the producer mint under a counter already in the document. A caller that sees `skipped > 0` should log it. An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. diff --git a/src/clock.ts b/src/clock.ts index 92d1e10..ce82227 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -80,11 +80,10 @@ const INTERIOR_ROUTE_PREFIX = `["${INTERIOR_ROUTE_TAG}",`; function isCompanionRow(key: string, value: unknown): boolean { if (key.startsWith(INTERIOR_ROUTE_PREFIX)) return typeof value === "string"; - if (key.startsWith(GROW_REQUEST_PREFIX)) { - // applier GrowRequest: [name, widget | null, isInputcount] - return Array.isArray(value) && value.length === 3 && typeof value[0] === "string" && - (value[1] === null || typeof value[1] === "string") && typeof value[2] === "boolean"; - } + // applier GrowRequest: [name, widget, isInputcount]. The applier stores the + // grow's widget field as sent, so only the leading position is load-bearing: + // a row whose first element is not a number cannot carry a counter. + if (key.startsWith(GROW_REQUEST_PREFIX)) return Array.isArray(value) && typeof value[0] !== "number"; return false; } diff --git a/test/clock.test.ts b/test/clock.test.ts index f9e29de..e745ff1 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -196,7 +196,7 @@ describe("creator-owned Lamport counter", () => { counted.getMap("__stamps").set('["grow_request","1","9","images"]', [50, "agent:t:1", "a".repeat(32)]); counted.getMap("__stamps").set('["interior_route","3","inc"]', [60, "agent:t:1", "b".repeat(32)]); expect(observedDocCounter(counted)).toBe(60); - for (const value of [{ x: 1 }, 5, ["images.image0", null], ["images.image0", 3, false]]) { + for (const value of [{ x: 1 }, 5, [7, null, false]]) { const odd = mint({ nodes: [], links: [] }, catalog); odd.getMap("__stamps").set('["grow_request","1","9","images"]', value); expect(() => observedDocCounter(odd), JSON.stringify(value)).toThrow(TypeError); @@ -208,6 +208,24 @@ describe("creator-owned Lamport counter", () => { expect(observedDocCounter(route)).toBeUndefined(); }); + it("keeps the strict floor readable after a real grow whose widget is not a string", () => { + const io = (name: string, links: object) => ({ name, type: "IMAGE", ...links }); + const doc = mint({ + nodes: [ + { id: 1, type: "Source", pos: [0, 0], inputs: [], outputs: [io("out", { links: [] })], widgets_values: [] }, + { id: 2, type: "Destination", pos: [0, 0], inputs: [io("fixed", { link: null })], outputs: [], widgets_values: [] }, + ], + links: [], + } as unknown as WorkflowJSON, growCatalog); + applyOps(doc, [{ + op: "connect", op_id: "d".repeat(32), actor: "agent:t:1", base_version: 7, stamp: [7, "agent:t:1"], + link_id: 9, from_node: 1, from_slot: 0, to_node: 2, link_type: "IMAGE", + grow: { name: "images.image0", type: "IMAGE", widget: 5 }, + } as unknown as Parameters[1][number]], growCatalog); + expect(observedDocCounter(doc)).toBe(7); + expect(observedDocCounter(replicaOf(doc))).toBe(7); + }); + it("keeps reservations out of public readStamps and preserves their identity tuple", async () => { const doc = mint({ nodes: [], links: [] }, catalog); const store = new DocDerivedLamportClockStore(doc); From 1cea52834653330ed51a7ead6d38aac6559861c8 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sun, 1 Nov 2026 09:01:31 +0000 Subject: [PATCH 9/9] feat(clock): lenient floor read passes over an unreadable reservations root Applies the accepted Lamport decision D2: with skipMalformed, a __clock_reservations root that is not a readable map counts as one skipped entry instead of throwing. Winning counters live in __stamps, whose root still has to be readable in either mode; the strict read and the clock store refuse both. --- docs/multiplayer-schema.md | 2 +- src/clock.ts | 16 +++++++++++++--- test/clock.test.ts | 9 ++++++++- 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index a1a37b8..f60b490 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2613,4 +2613,4 @@ So one autogrow connect or one subgraph-instance delete made the floor unreadabl `observedDocCounter()` now passes over `__stamps` rows whose key begins with either tag and whose value has the shape the applier stores there (a string for `interior_route`; an array whose first element is not a number for `grow_request`, whose rows are `[name, widget, isInputcount]` with the grow's widget stored as sent). A companion-keyed row holding anything else is read as an ordinary row, so a counter can never hide behind a companion-looking key. The tags are `GROW_REQUEST_TAG` and `INTERIOR_ROUTE_TAG` in `doc.ts`, shared with the applier's key builders, and are matched on the canonical `JSON.stringify` key prefix. Every other row is validated exactly as §1.6 says, so the default read still fails closed. `__clock_reservations` rows are never skipped. The counters those operations carry are still counted through their own stamps (`["grow", …]`, `["node", …]`). -A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable counters of both ledgers, and the number of malformed rows (companion rows are not counted). A malformed row whose first element is still a valid counter raises the floor: over-estimating the floor is safe, under-estimating it would let the producer mint under a counter already in the document. A caller that sees `skipped > 0` should log it. An unreadable schema or ledger root still throws in this mode: a root that cannot be read is not a row that can be skipped. `DocDerivedLamportClockStore` keeps the strict read. +A producer that must keep minting rather than refuse may call `observedDocCounter(doc, { skipMalformed: true })`. It returns `{ counter, skipped }`: the maximum over the readable counters of both ledgers, and the number of malformed rows (companion rows are not counted). A malformed row whose first element is still a valid counter raises the floor: over-estimating the floor is safe, under-estimating it would let the producer mint under a counter already in the document. A caller that sees `skipped > 0` should log it. An unreadable `__clock_reservations` root counts as one skipped entry in this mode, since the winning counters live in `__stamps`; an unreadable schema or `__stamps` root still throws. The strict read and `DocDerivedLamportClockStore` refuse both. `DocDerivedLamportClockStore` keeps the strict read. diff --git a/src/clock.ts b/src/clock.ts index ce82227..447bf76 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -113,7 +113,8 @@ export interface LenientDocCounter { * readable counters instead (a malformed row whose first element is a valid * counter still raises it), plus the count of malformed rows (companion rows * are not counted). A caller that sees `skipped > 0` should log it. An - * unreadable schema or ledger root still throws. + * unreadable reservations root counts as one skipped entry; an unreadable + * schema or `__stamps` root still throws. */ export function observedDocCounter(doc: Y.Doc): number | undefined; export function observedDocCounter(doc: Y.Doc, options: { skipMalformed: true }): LenientDocCounter; @@ -129,8 +130,17 @@ export function observedDocCounter( if (root === undefined) continue; // Snapshot roots arrive as AbstractType, not Y.Map. Type only an existing // root; reject sequence content before getMap can hide it in a map view. - if (root._start !== null) throw new TypeError(`${name} root contains non-map content`); - const ledger = doc.getMap(name); // throws for a different concrete Y type + let ledger: Y.Map; + try { + if (root._start !== null) throw new TypeError(`${name} root contains non-map content`); + ledger = doc.getMap(name); // throws for a different concrete Y type + } catch (error) { + // Lenient mode passes over an unreadable reservations root as one skipped + // entry. Winning counters live in __stamps, whose root must stay readable. + if (options?.skipMalformed !== true || name !== ROOT_CLOCK_RESERVATIONS) throw error; + skipped++; + continue; + } ledger.forEach((value, key) => { if (name === ROOT_STAMPS && isCompanionRow(key, value)) return; let counter: number | undefined; diff --git a/test/clock.test.ts b/test/clock.test.ts index e745ff1..484d8df 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -176,9 +176,16 @@ describe("creator-owned Lamport counter", () => { expect(observedDocCounter(mint({ nodes: [], links: [] }, catalog), { skipMalformed: true })) .toEqual({ counter: undefined, skipped: 0 }); expect(() => observedDocCounter(new Y.Doc(), { skipMalformed: true })).toThrow(/schema/); + // An unreadable reservations root is one more skipped entry in lenient mode (the strict read and + // the clock store still refuse it); an unreadable __stamps root still throws in either mode. const brokenRoot = mint({ nodes: [], links: [] }, catalog); + brokenRoot.getMap("__stamps").set('["widget","1","0","seed"]', [12, "agent:t:1", "a".repeat(32)]); brokenRoot.getArray("__clock_reservations").push([[5, "agent:clock", "x"]]); - expect(() => observedDocCounter(replicaOf(brokenRoot), { skipMalformed: true })).toThrow(/non-map content/); + expect(() => observedDocCounter(replicaOf(brokenRoot))).toThrow(/non-map content/); + expect(observedDocCounter(replicaOf(brokenRoot), { skipMalformed: true })).toEqual({ counter: 12, skipped: 1 }); + const brokenStamps = replicaOf(mint({ nodes: [], links: [] }, catalog)); + brokenStamps.getArray("__stamps").push([[5, "agent:clock", "x"]]); + expect(() => observedDocCounter(replicaOf(brokenStamps), { skipMalformed: true })).toThrow(/non-map content/); }); it("keeps a malformed row's readable counter in the lenient floor", () => {