diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 9527a79..29f03d7 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 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/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 cd51068..98de421 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"; @@ -29,13 +29,14 @@ 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 * 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) {} @@ -70,14 +71,37 @@ 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}",`); + +/** 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 malformed rows skipped (companion + * rows are not counted); 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; @@ -86,16 +110,28 @@ 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) => { - 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_STAMPS && COMPANION_KEY_PREFIXES.some((prefix) => key.startsWith(prefix))) return; + 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/src/doc.ts b/src/doc.ts index 80be3bb..7f64f9b 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) */ @@ -278,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/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 5e34128..bb8b900 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,66 @@ 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: 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: "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([...doc.getMap("__stamps").keys()].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",')); + 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"]); + 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)]); + 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|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 })) + .toEqual({ counter: undefined, skipped: 0 }); + 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 () => { const doc = mint({ nodes: [], links: [] }, catalog); const store = new DocDerivedLamportClockStore(doc); 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({ diff --git a/test/permutation/full-op-pool.permutation.test.ts b/test/permutation/full-op-pool.permutation.test.ts index 44e5440..e55d617 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 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) { if (outcome.outcome === "rejected") expect(appliedIds.has(outcome.opId)).toBe(false);