From 26b6aeab6b2df2f11eb69e7bc9b02c2f873ac9b5 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 15:29:06 -0700 Subject: [PATCH 1/6] 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 --- 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 cd51068..3b1e478 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 733fbe3ca18660ca67017f001a9f1939c57067f8 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 15:39:08 -0700 Subject: [PATCH 2/6] 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 --- 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 3b1e478..0069e4b 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-021). 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 e88fec42fdffc4fe50aafc5f02eede5e50ac6f5f Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 15:45:38 -0700 Subject: [PATCH 3/6] 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 --- 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 0069e4b..db9d643 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-021). 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 80be3bb..beb9936 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 1a58ef3..4d24235 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 14b33ac5ab2c7b4ccdbe7119b58986cfa8574c96 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 16:11:02 -0700 Subject: [PATCH 4/6] 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 --- 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 db9d643..6ac962a 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 a226b3a7cff36ea6e723cb00b435acbe95586839 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 16:55:39 -0700 Subject: [PATCH 5/6] 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 --- 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 9527a79..8361c97 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2494,3 +2494,15 @@ on that path and the retention on every other — rather than papered over. map directly, maintains neither passthrough register (A23's gap), and does not consult a declared order either. Pre-existing, one op over, and not addressed here. + +## Amendment A25 — 2026-10-10 — 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 dcc76b2..aeedf42 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, @@ -2077,7 +2079,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( @@ -2987,7 +2989,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 6ac962a..a1962d1 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 beb9936..7f64f9b 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 be9f782951fd6327ebe48d2e96cb5feff44e54b5 Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Sat, 10 Oct 2026 17:05:45 -0700 Subject: [PATCH 6/6] 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 --- 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 8361c97..29f03d7 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2505,4 +2505,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 a1962d1..98de421 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 }))