From 04a473cdca95a53b2d4518f7e70773d7a9c0bb4c Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Sun, 11 Oct 2026 11:56:04 +0900 Subject: [PATCH] feat: validate DynamicGroup row identity manifests --- docs/INVARIANTS.md | 2 + docs/decisions/EXCEPTIONS.md | 1 + docs/dynamic-groups.md | 12 +- docs/multiplayer-schema.md | 18 +- fixtures/golden-vectors/wire-layout.json | 4 +- src/applier.ts | 22 +- src/doc.ts | 15 +- src/dynamic-group-rows.ts | 53 +++++ src/mint.ts | 6 +- src/project.ts | 5 + src/read.ts | 10 +- src/types.ts | 2 +- test/clock.test.ts | 4 +- test/doc-mint-mutation-survivors.test.ts | 2 +- test/dynamic-group-row-identity.test.ts | 245 +++++++++++++++++++++++ test/link-state-foundation.test.ts | 4 +- test/readonly-surface.test.ts | 8 +- test/schema.test.ts | 6 +- 18 files changed, 390 insertions(+), 29 deletions(-) create mode 100644 src/dynamic-group-rows.ts create mode 100644 test/dynamic-group-row-identity.test.ts diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 0049de3..4ee9481 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -113,6 +113,8 @@ older reader emits the key as passthrough and mis-projects `widgets_values` — which is the SHA-pinned-consumer consequence A1 and A2 both document, and why the pins move in one coordinated step. +Schema v6 adds validated producer-owned DynamicGroup row IDs in node properties (schema A26). Earlier readers could resize a tagged group without updating those IDs, so v1–v5 documents are refused and re-minted from source. Reader/document-host adoption and FE sign-off remain release prerequisites. + ### KA-12 — Catalog pinned at mint **Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) resolves names and occurrences from that declaration without a catalog mapping. A25 makes one validation exception: supplied `dynamic_groups` metadata identifies count fields for allocation-bound checks and refuses a count change that would invalidate the declaration, using the addressed occurrence's current value. The declaration still owns ordering; the catalog does not replace it. Without that metadata, the package cannot identify a count field, so callers must enforce compatible producer, catalog, and reader adoption. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against. **Why:** Replay semantics must not drift with a moving vocabulary. diff --git a/docs/decisions/EXCEPTIONS.md b/docs/decisions/EXCEPTIONS.md index 1ae8919..30ad0a7 100644 --- a/docs/decisions/EXCEPTIONS.md +++ b/docs/decisions/EXCEPTIONS.md @@ -25,3 +25,4 @@ is retained as history, not authorization to accept unprojectable writes. | 2026-10-03 (PROPOSED) | KA-5 | **`insert_workflow` derives numeric group ids by the same pure 53-bit hash as KA-5's link ids, and accepts the same residual collision risk** (PR #264). ComfyUI_frontend's workflow schema declares `groups[].id` as `z.number()` (root and `definitions.subgraphs[].groups`) and refuses the whole workflow on a string, so the string `derivedId` groups used to carry made inserted workflows unloadable. `derivedGroupId` folds `insert:::group:` into `[1, Number.MAX_SAFE_INTEGER]` from the op's own content only (no document read, no retry), so replicas converge regardless of arrival order. Residual probability is the KA-5 row's: `≈ k²/2^54` for `k` groups in one document. **Unlike links, a realized group-id collision is NOT detected**: `applier.ts` merges groups by canonical JSON, not by id, so two distinct groups sharing an id both stay in the document and project with the same id; the frontend's behaviour on duplicate group ids is unverified. `project.ts` coerces a stored string group id to a number ONLY when it matches the derived form (`DERIVED_GROUP_ID`), so a workflow's own string group id round-trips `project(mint(wf))` unchanged and still fails the frontend schema exactly as it would without this package. | `src/remap.ts` `derivedGroupId`, `numericId`; `src/project.ts` `projectGroups`, `DERIVED_GROUP_ID`; `test/insert-workflow-numeric-group-ids.regression.test.ts` | Owner and approval: maintainer's to assign (proposed for Christian Byrne, who reviewed #264). Sunset: revisit if ComfyUI_frontend widens a group's `id` to `string \| number`, at which point the string `derivedId` suffices and this exception can be retired; add id-level collision detection to the groups merge before then if duplicate ids prove harmful on the canvas. | | 2026-10-04 (PROPOSED) | FC-10 | **`widgets_values_form` is a package-local, provisional workflow FIELD** (schema Amendment A24), because the pinned catalog is per-class while the two shapes that need describing are per-instance: a node with two same-named serializable widgets, and a node whose custom serializer emits an object whose non-widget keys must survive a widget write. Neither is derivable from the end state, so the producer declares its instance's ordered widget identity and this package decomposes, addresses and projects through that declaration with no catalog lookup. comfy-cli's frozen `op-vocabulary-v1.md` does not define the field, so the deviation is from FC-10's cite-the-pinned-vocabulary rule rather than from KA-12 (a declaration is the name-to-position mapping, supplied by the party that knows it, not a guess at one). Bounded deliberately: ONE declared key, closed to `{order}` and refused rather than ignored when malformed; every other part of the form is derived; an undeclared node keeps the catalog path and all of its existing refusals; `SCHEMA_VERSION` is unchanged on A2's precedent and under A2's exact condition. **Two residuals, both stated rather than discovered later:** `insert_workflow` strips every `__`-prefixed key at every depth (`prepareInsertedWorkflow` / `scrubPrivateKeys`, a pre-existing anti-forgery guard), so a serializer's own `__`-prefixed data key inside `widgets_values` does not survive THAT path — pinned by test rather than papered over; and the §8.3 autogrow `inputcount` bump still writes the `widgets` map directly and consults no declared order, which is A23's pre-existing gap one op over. | `src/widget-form.ts`; `src/doc.ts` `widgetStorageFor`/`widgetStorageOf`/`storeWidgetValues`; `src/project.ts` `projectWidgets`; `src/applier.ts` `validateWidgetName`/`rejectIfOpaqueWidgets`/`hostWriteStorage`/`createAddedNode`/`rejectUnprojectableWidgets`; `src/read.ts`; `fixtures/golden-vectors/wire-layout.json`; `test/node-local-widget-form.test.ts`; schema Amendment A24 | Owner and approval: maintainer's to assign (FE-3036's owner). Sunset: amend comfy-cli's frozen vocabulary to define the field and pin the adopted definition here, reconciling the name and shape if upstream differs; retire outright if the catalog acquisition ever becomes per-instance, at which point the declaration becomes redundant rather than merely unneeded. | | 2026-10-11 (PROPOSED) | KA-12 | A25 uses supplied DynamicGroup metadata to validate count writes even on an A24 self-described node. Name/occurrence resolution and projection still use the producer declaration; metadata only checks allocation bounds and refuses changing the addressed occurrence's count without an updated form. Metadata omission cannot identify a controller and remains a caller admission concern. | `src/applier.ts` `validateDynamicGroupValue`; `test/dynamic-group.test.ts`; schema Amendments A24/A25 | Owner and approval: maintainer's to assign. Reconcile when count safety becomes part of the producer declaration or atomic row-operation protocol. | +| 2026-10-11 (PROPOSED) | FC-10 / KA-12 | A26's `properties.dynamicGroupRows` is a package-local draft field, not part of the frozen vocabulary. It preserves producer-owned IDs and requires supplied catalog group metadata for membership/allocation validation, including on self-described nodes; widget mapping still follows the declaration. Schema v6 fences older writers, and tagged scalar resize is refused until an atomic row protocol exists. | `src/dynamic-group-rows.ts`; `src/doc.ts`; `src/read.ts`; `src/applier.ts`; schema Amendment A26 | Owner and approval: maintainer's to assign. Sunset: adopt and pin the reviewed row-operation/producer contract, reconciling the field and schema before enabling writers. | diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index 85dac89..9cfceb3 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -12,7 +12,7 @@ Like dynamic-combo selections, count changes only change projection. Fields in h An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is refused before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms. -No wire key or op kind changes. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10). +A25 does not change wire keys or op kinds; A26 below introduces the opt-in row identity manifest and schema v6. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10). ## Namespace safety @@ -20,7 +20,7 @@ Relative group fields must be distinct. A controller cannot also be a DynamicCom ## Reader and producer adoption -The released reader `0.3.10` and this draft both use schema v5. The schema gate and a catalog hash do **not** prove that an old reader understands `dynamic_groups`. An offline probe with the CLI composite fixture demonstrated that the old reader can mint a new positional workflow, acknowledge an `after` edit, and write that value into the first row's enabled position while leaving the real trailing value unchanged. Omitting group metadata produces the same unsupported mapping even with the current reader. +The released reader `0.3.10` uses schema v5. A25 originally used v5 as well; A26 in this draft requires v6. The schema gate and a catalog hash do **not** prove that an old reader understands `dynamic_groups`. An offline probe with the CLI composite fixture demonstrated that the old reader can mint a new positional workflow, acknowledge an `after` edit, and write that value into the first row's enabled position while leaving the real trailing value unchanged. Omitting group metadata produces the same unsupported mapping even with the current reader. | Producer declaration | Reader/catalog combination | Supported scope | | --- | --- | --- | @@ -53,3 +53,11 @@ JS ``` The released reader acknowledges the write at position 4, replacing the enabled value. This reader edits the final `tail` position. Both readers accept an existing-field edit with the fixture's explicit form; that is a separate supported path, not evidence of live row-resize support. + +## Draft row identity reader + +Schema A26 accepts an opt-in `properties.dynamicGroupRows` manifest, for example `{"loras": ["row-a", "row-c"]}` alongside a stored `loras=2`. IDs are opaque producer-owned strings scoped to the node lifetime and group. The reader validates distinct nonempty IDs, known catalog groups, stored counts and allocation bounds. It preserves saved rows above a changed advertised maximum and does not assign IDs to untagged workflows. + +`readGraph` exposes a deeply frozen `dynamicGroupRows` field for tagged nodes. Scalar count edits that would contradict a listed group's IDs are refused, even without a catalog at apply time. Existing field edits keep their current numeric addresses; stable-ID editing is not implemented by this reader. The next stage must implement atomic row insertion/deletion, stable field targets, links/promotions and admission together. + +This is a reader preparation draft, not a released row-operation capability. Schema v6 prevents v5 readers from accepting a tagged document; current readers refuse older documents, which the host must re-mint from source. Reader, document-host and producer pins must be coordinated and reviewed before adoption. No CLI, frontend or agent producer is enabled by this PR. diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 50d2526..bd4cb3e 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -1,6 +1,6 @@ -# Multiplayer workflow-document schema — v5 +# Multiplayer workflow-document schema — v6 -`SCHEMA_VERSION = 5` +`SCHEMA_VERSION = 6` > **State: DRAFT — awaiting FE sign-off (FE-1330).** > @@ -892,7 +892,7 @@ the epoch; cross-epoch struct updates never merge. ## 10. Versioning and `migrate()` -- `SCHEMA_VERSION = 5`, stored in `meta.schema_version` at mint. +- `SCHEMA_VERSION = 6`, stored in `meta.schema_version` at mint. - Private-alpha policy keeps one current format: old layouts are re-minted at their source and compatibility readers/migrations are not provided. - `migrate(doc, fromVersion)` contract: exact no-op when @@ -2503,3 +2503,15 @@ here. 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 allocation-bound validation and rejects a count change requiring a new declaration before mutation. This is A24's one catalog-validation exception, applied to the addressed occurrence in top-level, interior, and promoted writes. 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 A26 — 2026-10-11 — DynamicGroup row identity reader (schema v6) + +An opt-in node carries `properties.dynamicGroupRows`, mapping catalog group names to ordered arrays of distinct, nonempty row ID strings. IDs are scoped to the node lifetime and group; different groups or nodes may use the same string. The producer supplies the IDs, and this reader never invents or replaces them. Each listed group requires pinned catalog metadata and an explicitly stored count equal to its ID array length. Existing allocation bounds apply; a changed advertised min/max does not discard saved rows. + +Mint, definition import, `add_node` and `insert_workflow` validate before attaching node maps. Projection validates catalog membership and stored counts again. `readGraph` exposes only the validated, deeply frozen ID manifest as `NodeSnapshot.dynamicGroupRows`, without copying unrelated properties. Its catalog-free validation covers shape and count; catalog admission remains the caller's responsibility. Workflow insertion preserves this closed ID mapping while continuing to scrub unrelated private keys. + +Ordinary scalar count changes on tagged groups are refused before mutation on top-level, interior and promoted paths, including when the apply caller omits the catalog. Unchanged counts and existing-field edits retain the current registers and replay behavior. Untagged nodes keep A25 behavior. No new operation kind is implemented here: atomic insertion/deletion, stable-ID field addressing, row-aware links/promotions and writer admission remain required follow-ups. + +Schema v6 is an adoption boundary. A v5 reader would accept a tagged group's scalar resize and leave its row IDs attached to the wrong positions. Readers and document hosts must adopt v6 together before a producer emits the manifest. Per §10 and KA-11, v1–v5 documents are refused without relabelling; the host re-mints their source workflows. A package source change is not consumer sign-off or permission to release. Existing JSON conformance fixtures remain workflow/op inputs and are re-minted at the current schema; the wire-layout vector records v6. No corpus expectation is regenerated from this applier. + +`test/dynamic-group-row-identity.test.ts` covers imports, round trips, two groups with a sibling DynamicCombo and seed companion, malformed manifests, unchanged-count/field edits in both orders, byte-identical rejection/retry/abort, frozen snapshots and old-schema refusal. The existing schema, clock and wire-layout suites retain the shared read gate. diff --git a/fixtures/golden-vectors/wire-layout.json b/fixtures/golden-vectors/wire-layout.json index 69e936c..d101b75 100644 --- a/fixtures/golden-vectors/wire-layout.json +++ b/fixtures/golden-vectors/wire-layout.json @@ -1,7 +1,7 @@ { "format_version": 1, - "comment": "Canonical WIRE layout of the multiplayer Y.Doc (schema §1). `roots` maps each logical role to the Y.Doc ROOT TYPE NAME as it is spelled inside an encoded Yjs update; `reserved_node_keys` names the per-node keys the doc owns. These strings are a cross-implementation contract, not an internal detail: two replicas that disagree about them cannot exchange a document, because a follower forking from the bootstrap snapshot (KA-10) resolves roots by name. Renaming any of them is a layout break: schema §10 requires a SCHEMA_VERSION bump, an explicit old-layout disposition, updated fixtures or a fixture-format note, an amendment section in the schema document, and FE sign-off, plus a matching edit here and in docs/INVARIANTS.md KA-3. test/wire-layout-contract.test.ts holds the four-way name agreement and the SCHEMA_VERSION triple's consistency; it does NOT enforce the bump itself, so read §10 rather than treating a green suite as permission. A second implementation should read this file rather than transcribing the names. Schema v4 adds clock_reservations; schema v5 adds occurrence-addressed widget keys. Amendment A24 adds the reserved per-node key `widget_form` WITHOUT a schema bump, on Amendment A2's precedent: it is reachable only on a node whose payload declared `widgets_values_form`, so no earlier v5 document can contain it. Private-alpha old layouts are refused, not migrated. The reservation root is created on first successful admission and empty roots are absent from snapshots.", - "schema_version": 5, + "comment": "Canonical WIRE layout of the multiplayer Y.Doc (schema \u00a71). `roots` maps each logical role to the Y.Doc ROOT TYPE NAME as it is spelled inside an encoded Yjs update; `reserved_node_keys` names the per-node keys the doc owns. These strings are a cross-implementation contract, not an internal detail: two replicas that disagree about them cannot exchange a document, because a follower forking from the bootstrap snapshot (KA-10) resolves roots by name. Renaming any of them is a layout break: schema \u00a710 requires a SCHEMA_VERSION bump, an explicit old-layout disposition, updated fixtures or a fixture-format note, an amendment section in the schema document, and FE sign-off, plus a matching edit here and in docs/INVARIANTS.md KA-3. test/wire-layout-contract.test.ts holds the four-way name agreement and the SCHEMA_VERSION triple's consistency; it does NOT enforce the bump itself, so read \u00a710 rather than treating a green suite as permission. A second implementation should read this file rather than transcribing the names. Schema v4 adds clock_reservations; schema v5 adds occurrence-addressed widget keys. Amendment A24 adds the reserved per-node key `widget_form` WITHOUT a schema bump, on Amendment A2's precedent: it is reachable only on a node whose payload declared `widgets_values_form`, so no earlier v5 document can contain it. Private-alpha old layouts are refused, not migrated. The reservation root is created on first successful admission and empty roots are absent from snapshots. Amendment A26 uses schema v6 to fence older writers from resizing groups whose producer-owned row IDs are persisted in node properties; root names and reserved node keys are unchanged.", + "schema_version": 6, "roots": { "nodes": "nodes", "links": "links", diff --git a/src/applier.ts b/src/applier.ts index 1661baf..2683d2b 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -153,6 +153,7 @@ import { } from "./types.js"; import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js"; import { groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; +import { dynamicGroupRowsOf } from "./dynamic-group-rows.js"; import { optionOwnedWidgets, projectedLength, widgetLayoutForWidgets, widgetOrderForValues, widgetOrderForWidgets } from "./dynamic-combos.js"; import { NODE_INCARNATION_KEY, WRITABLE_NODE_FIELDS } from "./types.js"; @@ -952,12 +953,19 @@ function numericId(value: unknown): number | undefined { return undefined; } -function scrubPrivateKeys(value: unknown): unknown { - if (Array.isArray(value)) return value.map(scrubPrivateKeys); +function scrubPrivateKeys(value: unknown, parentKey?: string): unknown { + if (Array.isArray(value)) return value.map((child) => scrubPrivateKeys(child)); if (typeof value !== "object" || value === null) return value; const clean: Record = {}; for (const [key, child] of Object.entries(value)) { - if (!key.startsWith("__")) clean[key] = scrubPrivateKeys(child); + if (parentKey === "properties" && key === "dynamicGroupRows") { + try { + dynamicGroupRowsOf({ dynamicGroupRows: child }); + clean[key] = structuredClone(child); + } catch (err) { + throw new OpRejectedError("invalid_node_payload", `insert_workflow: ${err instanceof Error ? err.message : String(err)}`); + } + } else if (!key.startsWith("__")) clean[key] = scrubPrivateKeys(child, key); } return clean; } @@ -1138,7 +1146,7 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC } try { nodeWrites.push([String(node.id), node.id, createNodeMap(node, - declaresWidgetForm(node) ? undefined : widgetOrderForValues(entry, node.widgets_values))]); + declaresWidgetForm(node) ? undefined : widgetOrderForValues(entry, node.widgets_values), entry?.dynamic_groups)]); } catch (err) { throw new OpRejectedError("invalid_node_payload", `insert_workflow(${node.type}): ${err instanceof Error ? err.message : String(err)}`); } @@ -1315,7 +1323,7 @@ function createAddedNode(op: AddNodeOp, catalog?: WidgetCatalog): Y.Map rejectUnprojectableWidgets(op.node, op.node.type, wv, entry); } try { - return createNodeMap(op.node, order); + return createNodeMap(op.node, order, entry?.dynamic_groups); } catch (err) { throw new OpRejectedError( "invalid_node_payload", @@ -1958,6 +1966,10 @@ function validateWidgetOp(op: SetWidgetOp) { } function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog | undefined, widget: string, occurrence: number, value: unknown): void { + const rows = dynamicGroupRowsOf(node.get("properties")); + if (rows && Object.hasOwn(rows, widget) && (occurrence !== 0 || value !== rows[widget]!.length)) { + throw new OpRejectedError("malformed_op", "row count changes require an atomic DynamicGroup row operation"); + } const entry = catalogEntry(catalog, String(node.get("type") ?? "")); const refusal = groupCountRefusal(entry, widget, value); if (refusal) throw new OpRejectedError("malformed_op", refusal); diff --git a/src/doc.ts b/src/doc.ts index 80be3bb..01f1f13 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -30,9 +30,11 @@ import { NODE_INCARNATION_KEY, SCHEMA_VERSION, type WidgetCatalog, + type WidgetCatalogEntry, type WorkflowNode, } from "./types.js"; import { widgetIdentityFromStorageKey, widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; +import { assertDynamicGroupRowCatalog, assertDynamicGroupRowCounts, dynamicGroupRowsOf } from "./dynamic-group-rows.js"; import { WIDGET_FORM_FIELD, WIDGET_FORM_KEY, @@ -946,8 +948,9 @@ function storeWidgetValues( * `widgetOrder` (the pinned catalog's `widget_order` for the node's type) is * required to decompose a non-empty positional `widgets_values` array; a node * whose `widgets_values` is already a name-keyed record needs no catalog. + * A row-ID manifest additionally requires its pinned DynamicGroup metadata. */ -export function createNodeMap(node: WorkflowNode, widgetOrder?: readonly string[]): Y.Map { +export function createNodeMap(node: WorkflowNode, widgetOrder?: readonly string[], groups?: WidgetCatalogEntry["dynamic_groups"]): Y.Map { const m = new Y.Map(); // Read and validate the A24 declaration BEFORE the loop, for two reasons // that are both correctness and not tidiness: `Object.entries` order decides @@ -959,6 +962,16 @@ export function createNodeMap(node: WorkflowNode, widgetOrder?: readonly string[ if (declared && !Object.hasOwn(node, "widgets_values")) { throw new TypeError(`${WIDGET_FORM_FIELD}: declared on a node that carries no widgets_values`); } + const rows = dynamicGroupRowsOf(node["properties"]); + assertDynamicGroupRowCatalog(rows, groups); + const order = declared?.order ?? widgetOrder; + assertDynamicGroupRowCounts(rows, (name) => { + const index = order?.indexOf(name) ?? -1; + if (declared && (index < 0 || index !== order?.lastIndexOf(name))) return undefined; + const values = node.widgets_values; + if (!Array.isArray(values)) return values && Object.hasOwn(values, name) ? values[name] : undefined; + return index >= 0 && index === order?.lastIndexOf(name) ? values[index] : undefined; + }); for (const [k, v] of Object.entries(node)) { if (k === WIDGET_FORM_FIELD) { // Consumed by the `widgets_values` branch below and re-emitted by diff --git a/src/dynamic-group-rows.ts b/src/dynamic-group-rows.ts new file mode 100644 index 0000000..d27933e --- /dev/null +++ b/src/dynamic-group-rows.ts @@ -0,0 +1,53 @@ +import { MAX_OVERFLOW_WIDGETS } from "./limits.js"; +import type { WidgetCatalogEntry } from "./types.js"; + +type RowIds = Readonly>; + +function isPlainRecord(value: unknown): value is Record { + if (typeof value !== "object" || value === null) return false; + const proto = Object.getPrototypeOf(value) as unknown; + return proto === Object.prototype || proto === null; +} + +/** Producer-owned live row order, scoped to this node and group. */ +export function dynamicGroupRowsOf(properties: unknown): RowIds | null { + if (typeof properties !== "object" || properties === null || !Object.hasOwn(properties, "dynamicGroupRows")) return null; + if (!isPlainRecord(properties)) throw new TypeError("dynamicGroupRows: properties must be a plain object"); + const rows = properties["dynamicGroupRows"]; + if (!isPlainRecord(rows)) { + throw new TypeError("dynamicGroupRows: expected a group-to-row-ID object"); + } + for (const [group, ids] of Object.entries(rows)) { + if (group.length === 0 || !Array.isArray(ids) || ids.length > MAX_OVERFLOW_WIDGETS + || new Set(ids).size !== ids.length) { + throw new TypeError(`dynamicGroupRows.${group}: expected distinct nonempty row IDs within the allocation bound`); + } + for (const id of ids as unknown[]) { + if (typeof id !== "string" || id.length === 0) { + throw new TypeError(`dynamicGroupRows.${group}: expected distinct nonempty row IDs within the allocation bound`); + } + } + } + return rows as RowIds; +} + +export function assertDynamicGroupRowCounts(rows: RowIds | null, valueAt: (name: string) => unknown): void { + for (const [name, ids] of Object.entries(rows ?? {})) { + const count = valueAt(name); + if (typeof count !== "number" || !Number.isSafeInteger(count) || count !== ids.length) { + throw new TypeError(`dynamicGroupRows.${name}: row IDs must match the stored row count`); + } + } +} + +export function assertDynamicGroupRowCatalog(rows: RowIds | null, groups: WidgetCatalogEntry["dynamic_groups"]): void { + for (const [name, ids] of Object.entries(rows ?? {})) { + if (!groups || !Object.hasOwn(groups, name)) { + throw new TypeError(`dynamicGroupRows.${name}: group metadata is required in the pinned catalog`); + } + const fields = groups[name]!.widgets; + if (fields.length === 0 || ids.length > Math.floor(MAX_OVERFLOW_WIDGETS / fields.length)) { + throw new TypeError(`dynamicGroupRows.${name}: rows exceed the widget allocation bound`); + } + } +} diff --git a/src/mint.ts b/src/mint.ts index 5b6d9b7..54b8d05 100644 --- a/src/mint.ts +++ b/src/mint.ts @@ -107,7 +107,8 @@ export function mint(workflow: WorkflowJSON, catalog: WidgetCatalog, catalogVers const nodes = nodesMap(doc); for (const node of workflow.nodes ?? []) { nodes.set(String(node.id), createNodeMap(node, - declaresWidgetForm(node) ? undefined : widgetOrderFor(catalog, node.type, node.widgets_values))); + declaresWidgetForm(node) ? undefined : widgetOrderFor(catalog, node.type, node.widgets_values), + Object.hasOwn(catalog.types, node.type) ? catalog.types[node.type]?.dynamic_groups : undefined)); } const links = linksMap(doc); @@ -257,7 +258,8 @@ function mintDefinitionNodes(dm: Y.Map, nodes: WorkflowNode[], catalog: if (order.includes(key)) throw new TypeError(`mint: duplicate definition node id '${key}'`); order.push(key); nm.set(key, createNodeMap(node, - declaresWidgetForm(node) ? undefined : widgetOrderFor(catalog, node.type, node.widgets_values))); + declaresWidgetForm(node) ? undefined : widgetOrderFor(catalog, node.type, node.widgets_values), + Object.hasOwn(catalog.types, node.type) ? catalog.types[node.type]?.dynamic_groups : undefined)); } dm.set("nodes", nm); dm.set("node_order", order); diff --git a/src/project.ts b/src/project.ts index ac3e866..c2184a5 100644 --- a/src/project.ts +++ b/src/project.ts @@ -49,6 +49,7 @@ import { projectInteriorLinkOrder } from "./interior-link-order.js"; import { assertReadableSchema } from "./schema-version.js"; import { NODE_INCARNATION_KEY, type WidgetCatalog, type WorkflowJSON, type WorkflowNode } from "./types.js"; import { isDynamicGroupField } from "./dynamic-groups.js"; +import { assertDynamicGroupRowCatalog, assertDynamicGroupRowCounts, dynamicGroupRowsOf } from "./dynamic-group-rows.js"; import { hasDynamicWidgetLayout, optionOwnedWidgets, projectedLength, widgetLayoutForWidgets } from "./dynamic-combos.js"; import { widgetIdentityFromStorageKey, widgetOccurrenceAt, widgetStorageKey, widgetIndexOf } from "./widget-identity.js"; import { @@ -225,6 +226,10 @@ function projectWidgets( function projectNode(ym: Y.Map, catalog: WidgetCatalog): WorkflowNode { const out: Record = Object.create(null) as Record; const nodeType = String(ym.get("type") ?? ""); + const rows = dynamicGroupRowsOf(ym.get("properties")); + assertDynamicGroupRowCatalog(rows, Object.hasOwn(catalog.types, nodeType) ? catalog.types[nodeType]?.dynamic_groups : undefined); + const widgets = ym.get("widgets"); + assertDynamicGroupRowCounts(rows, (name) => widgets instanceof Y.Map ? widgets.get(widgetStorageKey(name, 0)) : undefined); ym.forEach((v, k) => { if (k === NODE_INCARNATION_KEY) { return; diff --git a/src/read.ts b/src/read.ts index 1a58ef3..007919b 100644 --- a/src/read.ts +++ b/src/read.ts @@ -57,6 +57,8 @@ */ import * as Y from "yjs"; +import { assertDynamicGroupRowCounts, dynamicGroupRowsOf } from "./dynamic-group-rows.js"; +import { widgetStorageKey } from "./widget-identity.js"; import { OPAQUE_WIDGETS_KEY, ROOT_APPLIED, @@ -325,12 +327,14 @@ function assertSnapshotReadable(doc: Y.Doc, context: string): void { const NODE_SNAPSHOT_KEYS: readonly string[] = ["type", "pos", "widgets", OPAQUE_WIDGETS_KEY, WIDGET_FORM_KEY]; /** - * One node, as plain frozen data. Every field is typed `unknown` because the + * One node, as plain frozen data. Unvalidated fields are typed `unknown` because the * document is untrusted input: a caller must validate exactly as it would when * reading the Y.Map directly. Absent keys are absent, not `undefined`, so key * presence round-trips. */ export interface NodeSnapshot { + /** Validated live row IDs in group order; absent on untagged nodes. */ + readonly dynamicGroupRows?: Readonly>; /** Node class name (`class_type`). */ readonly type?: unknown; /** Canvas position, verbatim (`[x, y]` for a well-formed node). */ @@ -373,6 +377,10 @@ export function readGraph(doc: Y.Doc): GraphSnapshot { for (const key of NODE_SNAPSHOT_KEYS) { if (node.has(key)) out[key] = snapshot(node.get(key), 1); } + const rows = dynamicGroupRowsOf(node.get("properties")); + const widgets = node.get("widgets"); + assertDynamicGroupRowCounts(rows, (name) => widgets instanceof Y.Map ? widgets.get(widgetStorageKey(name, 0)) : undefined); + if (rows) out["dynamicGroupRows"] = snapshot(rows, 1); nodes[id] = Object.freeze(out) as NodeSnapshot; }); diff --git a/src/types.ts b/src/types.ts index 4ffa061..de6563a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -20,7 +20,7 @@ * Version of the Y.Doc layout. Bump requires FE sign-off and an explicit old-layout disposition. * The authoritative layout + op-semantics reference is docs/multiplayer-schema.md. */ -export const SCHEMA_VERSION = 5; +export const SCHEMA_VERSION = 6; /** Version of an imported destination reconstruction descriptor in `__link_state`. */ export const LINK_STATE_DESCRIPTOR_VERSION = 1; diff --git a/test/clock.test.ts b/test/clock.test.ts index 5e34128..dfefc15 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -286,7 +286,7 @@ describe("creator-owned Lamport counter", () => { await expect(persistLamportTick(new DocDerivedLamportClockStore(doc), identity, [], { requireSeed: true })).resolves.toBe(1); }); - it.each([undefined, 1, 2, 3, 4, 6])("refuses unsupported schema %s without migration or reservation", async (version) => { + it.each([undefined, 1, 2, 3, 4, 5, 7])("refuses unsupported schema %s without migration or reservation", async (version) => { const doc = new Y.Doc(); if (version !== undefined) doc.getMap("meta").set("schema_version", version); const before = Y.encodeStateAsUpdate(doc); @@ -294,7 +294,7 @@ describe("creator-owned Lamport counter", () => { expect(() => observedDocCounter(doc)).toThrow(/schema/); await expect(persistLamportTick(new DocDerivedLamportClockStore(doc), identity, [])).rejects.toThrow(/schema/); expect(() => project(doc, catalog)).toThrow(/schema/); - expect(() => migrate(doc, version ?? 5)).toThrow(/schema/); + expect(() => migrate(doc, version ?? 6)).toThrow(/schema/); if (version !== undefined) expect(() => readStamps(doc)).toThrow(/schema/); expect(Y.encodeStateAsUpdate(doc)).toEqual(before); expect([...doc.share.keys()]).toEqual(roots); diff --git a/test/doc-mint-mutation-survivors.test.ts b/test/doc-mint-mutation-survivors.test.ts index a6fb93f..04a77c7 100644 --- a/test/doc-mint-mutation-survivors.test.ts +++ b/test/doc-mint-mutation-survivors.test.ts @@ -465,7 +465,7 @@ describe("schema §1 doc layout: root-map names and the reserved opaque key are expect(doc.getMap("nodes").has("1")).toBe(true); expect(doc.getMap("links").has("7")).toBe(true); expect(doc.getMap("definitions").has("d")).toBe(true); - expect(doc.getMap("meta").get("schema_version")).toBe(5); + expect(doc.getMap("meta").get("schema_version")).toBe(6); // The bookkeeping roots are named too — `__applied` is the idempotency // gate (§4) and `__stamps` the LWW register file (§3). const op = { op: "set_widget", ...env(), node_id: 1, widget: "text", value: "w" } as SetWidgetOp; diff --git a/test/dynamic-group-row-identity.test.ts b/test/dynamic-group-row-identity.test.ts new file mode 100644 index 0000000..42dd149 --- /dev/null +++ b/test/dynamic-group-row-identity.test.ts @@ -0,0 +1,245 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; +import * as Y from "yjs"; +import { applyOps, mint, project, readGraph, SCHEMA_VERSION, SchemaVersionError, type Op, type TopLevelSetWidgetOp, type WidgetCatalog, type WorkflowJSON } from "../src/index.js"; +import { canonicalize } from "./helpers.js"; +import { assertRejectedWithoutMutation } from "./rejection-test-helpers.js"; + +const fixture = JSON.parse(readFileSync(new URL("./fixtures/dynamic-group-composite.json", import.meta.url), "utf8")) as { + catalog: WidgetCatalog; + workflow: WorkflowJSON; + explicit_form_workflow: WorkflowJSON; + op: TopLevelSetWidgetOp; +}; +const { catalog } = fixture; +const ids = { loras: ["row-a", "row-c"], weights: ["row-a"] }; + +function workflow(shape: "array" | "object" | "declared" = "array"): WorkflowJSON { + const result = structuredClone(shape === "declared" ? fixture.explicit_form_workflow : fixture.workflow); + const node = result.nodes[0]!; + node["properties"] = { ...node["properties"] as object, dynamicGroupRows: structuredClone(ids) }; + if (shape === "object") node.widgets_values = structuredClone(node["widgets_values_named"]) as Record; + return result; +} + +function importOp(kind: "add_node" | "insert_workflow", value: WorkflowJSON): Op { + const envelope = { op_id: "a".repeat(32), actor: "agent:a", base_version: 1, stamp: [1, "agent:a"] as [number, string] }; + return kind === "add_node" + ? { ...envelope, op: kind, node_id: 1, class_type: value.nodes[0]!.type, pos: [0, 0], node: value.nodes[0]! } + : { ...envelope, op: kind, workflow: value }; +} + +describe("DynamicGroup row identity reader", () => { + it.each(["array", "object", "declared"] as const)("preserves %s row identities through projection, snapshots and re-mint", (shape) => { + const source = workflow(shape); + const doc = mint(source, catalog); + const projected = project(doc, catalog); + expect(projected.nodes[0]!["properties"]).toEqual(source.nodes[0]!["properties"]); + const snapshot = readGraph(doc); + expect(snapshot.nodes["1"]!.dynamicGroupRows).toEqual(ids); + expect(Object.isFrozen(snapshot.nodes["1"]!.dynamicGroupRows!["loras"])).toBe(true); + const reminted = mint(projected, catalog); + expect(canonicalize(project(reminted, catalog))).toEqual(canonicalize(projected)); + reminted.destroy(); + doc.destroy(); + }); + + it.each(["add_node", "insert_workflow"] as const)("preserves IDs on %s and duplicate replay", (kind) => { + const source = workflow(); + const doc = mint({ nodes: [], links: [] }, catalog); + const op = importOp(kind, source); + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, catalog).nodes[0]!["properties"]).toEqual(source.nodes[0]!["properties"]); + const before = Y.encodeStateAsUpdate(doc); + applyOps(doc, [op], catalog); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + doc.destroy(); + }); + + it("preserves interior IDs through definition import and field editing", () => { + const source: WorkflowJSON = { + nodes: [{ id: 9, type: "group-definition" }], links: [], + definitions: { subgraphs: [{ id: "group-definition", nodes: workflow().nodes, links: [] }] }, + }; + const doc = mint(source, catalog); + const op: Op = { ...fixture.op, path: ["9", "1"], inner_widget: "weights.0.weight", promoted: null }; + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, catalog)).toMatchObject({ definitions: { subgraphs: [{ nodes: [{ + properties: { dynamicGroupRows: ids }, widgets_values_named: { "weights.0.weight": 0.9 }, + }] }] } }); + doc.destroy(); + }); + + it.each([ + ["null", null], ["array", []], ["not an ID list", { loras: "row-a" }], + ["duplicate ID", { ...ids, loras: ["row-a", "row-a"] }], + ["empty ID", { ...ids, loras: ["row-a", ""] }], + ["nonstring ID", { ...ids, loras: ["row-a", 2] }], + ["count mismatch", { ...ids, loras: ["row-a"] }], + ["unknown group", { ...ids, other: [] }], + ])("refuses %s metadata at every node ingress", (_label, raw) => { + const source = workflow(); + (source.nodes[0]!["properties"] as Record)["dynamicGroupRows"] = raw; + expect(() => mint(source, catalog)).toThrow(/dynamicGroupRows/); + const interior: WorkflowJSON = { nodes: [], links: [], definitions: { subgraphs: [{ id: "def", nodes: source.nodes, links: [] }] } }; + expect(() => mint(interior, catalog)).toThrow(/dynamicGroupRows/); + for (const kind of ["add_node", "insert_workflow"] as const) { + assertRejectedWithoutMutation({ nodes: [], links: [] }, importOp(kind, source), "invalid_node_payload", catalog); + } + }); + + it("requires group metadata even when the producer declares the widget form", () => { + const missing = structuredClone(catalog); + delete missing.types["CompositeDynamicGroup"]!.dynamic_groups; + const source = workflow("declared"); + expect(() => mint(source, missing)).toThrow(/dynamicGroupRows.*catalog/); + assertRejectedWithoutMutation({ nodes: [], links: [] }, importOp("add_node", source), "invalid_node_payload", missing); + }); + + it("does not invent IDs or reject ordinary properties on untagged nodes", () => { + const source = structuredClone(fixture.workflow); + source.nodes[0]!["properties"] = { ...source.nodes[0]!["properties"] as object, unrelated: ["keep"] }; + const doc = mint(source, catalog); + expect(canonicalize(project(doc, catalog))).toEqual(canonicalize(source)); + doc.destroy(); + }); + + it("validates every inserted node before attaching any of them", () => { + const source = workflow(); + (source.nodes[0]!["properties"] as Record)["dynamicGroupRows"] = { loras: ["row-a"], weights: ids.weights }; + source.nodes.unshift({ id: 2, type: "LoadImage", widgets_values: [] }); + const before = structuredClone(source); + assertRejectedWithoutMutation({ nodes: [], links: [] }, importOp("insert_workflow", source), "invalid_node_payload", catalog); + expect(source).toEqual(before); + }); + + it.each(["define_subgraph", "insert_workflow"] as const)("validates interior IDs before %s attaches a definition", (kind) => { + const source = workflow(); + const id = "12345678-1234-4123-8123-123456789abc"; + const definition = { id, name: "Rows", nodes: source.nodes, links: [] }; + const op: Op = kind === "define_subgraph" + ? { ...fixture.op, op: kind, subgraph_id: id, subgraph_definition: definition } + : importOp(kind, { nodes: [], links: [], definitions: { subgraphs: [definition] } }); + const doc = mint({ nodes: [], links: [] }, catalog); + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, catalog)).toMatchObject({ definitions: { subgraphs: [{ nodes: [{ properties: { dynamicGroupRows: ids } }] }] } }); + doc.destroy(); + (source.nodes[0]!["properties"] as Record)["dynamicGroupRows"] = { loras: ["row-a"], weights: ids.weights }; + assertRejectedWithoutMutation({ nodes: [], links: [] }, op, "apply_failed", catalog); + }); + + it("refuses a tagged count change even when a declared-form apply caller has no catalog", () => { + const doc = mint(workflow("declared"), catalog); + const op: Op = { ...fixture.op, widget: "loras", value: 1 }; + const trailing: Op = { ...fixture.op, op_id: "c".repeat(32), widget: "after", value: "must not land" }; + const before = Y.encodeStateAsUpdate(doc); + expect(applyOps(doc, [op, trailing]).outcomes).toMatchObject([ + { outcome: "rejected", reason: { code: "malformed_op" } }, + { outcome: "rejected", reason: { code: "batch_aborted" } }, + ]); + expect(applyOps(doc, [op]).outcomes[0]?.outcome).toBe("rejected"); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + expect(doc.getMap("__applied").has(op.op_id)).toBe(false); + expect(doc.getMap("__applied").has(trailing.op_id)).toBe(false); + expect(applyOps(doc, [trailing]).outcomes[0]?.outcome).toBe("applied"); + doc.destroy(); + }); + + it("does not treat a serializer's non-widget count residue as a row controller", () => { + const source = workflow("declared"); + const node = source.nodes[0]!; + node.widgets_values = structuredClone(node["widgets_values_named"]) as Record; + const form = node.widgets_values_form as { order: string[] }; + form.order = form.order.filter((name) => name !== "loras"); + expect(() => mint(source, catalog)).toThrow(/dynamicGroupRows/); + assertRejectedWithoutMutation({ nodes: [], links: [] }, importOp("add_node", source), "invalid_node_payload", catalog); + }); + + it("preserves group names through workflow insertion without weakening other private-key scrubbing", () => { + const source = workflow("declared"); + const entry = structuredClone(catalog.types["CompositeDynamicGroup"]!); + entry.dynamic_groups!["__loras"] = entry.dynamic_groups!["loras"]!; + delete entry.dynamic_groups!["loras"]; + const renamedCatalog = { types: { CompositeDynamicGroup: entry } }; + const node = source.nodes[0]!; + const form = node.widgets_values_form as { order: string[] }; + form.order = form.order.map((name) => name.replace(/^loras(?=\.|$)/, "__loras")); + node["properties"] = { dynamicGroupRows: { __loras: ids.loras, weights: ids.weights }, __private: "drop" }; + const doc = mint({ nodes: [], links: [] }, renamedCatalog); + expect(applyOps(doc, [importOp("insert_workflow", source)], renamedCatalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, renamedCatalog).nodes[0]!["properties"]).toEqual({ dynamicGroupRows: { __loras: ids.loras, weights: ids.weights } }); + doc.destroy(); + }); + + it("rejects a sparse ID array before it can acquire an undefined row identity", () => { + const source = workflow(); + const sparse = ["row-a", "row-c"]; + delete sparse[1]; + (source.nodes[0]!["properties"] as Record)["dynamicGroupRows"] = { loras: sparse, weights: ids.weights }; + expect(() => mint(source, catalog)).toThrow(/dynamicGroupRows/); + }); + + it("fails closed on a snapshot whose stored count no longer matches its IDs", () => { + const doc = mint(workflow(), catalog); + const node = doc.getMap>("nodes").get("1")!; + (node.get("widgets") as Y.Map).set("loras", 1); + const before = Y.encodeStateAsUpdate(doc); + expect(() => readGraph(doc)).toThrow(/dynamicGroupRows/); + expect(() => project(doc, catalog)).toThrow(/dynamicGroupRows/); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + doc.destroy(); + }); + + it("preserves empty groups and saved rows above a newer maximum", () => { + const source = workflow("object"); + const values = source.nodes[0]!.widgets_values as Record; + values["weights"] = 0; + delete values["weights.0.seed"]; + delete values["weights.0.seed.0"]; + delete values["weights.0.weight"]; + (source.nodes[0]!["properties"] as Record)["dynamicGroupRows"] = { loras: ids.loras, weights: [] }; + const smaller = structuredClone(catalog); + smaller.types["CompositeDynamicGroup"]!.dynamic_groups!["loras"]!.max = 1; + const doc = mint(source, smaller); + expect(project(doc, smaller).nodes[0]!["properties"]).toEqual(source.nodes[0]!["properties"]); + expect((project(doc, smaller).nodes[0]!.widgets_values as unknown[])[1]).toBe(2); + doc.destroy(); + }); + + it.each(["top-level", "interior", "promoted"] as const)("refuses scalar resize of an ID-bearing group on the %s path", (route) => { + let source = workflow(); + let op: Op = { ...fixture.op, widget: "loras", value: 1 }; + if (route === "interior") { + source = { nodes: [{ id: 9, type: "def" }], links: [], definitions: { subgraphs: [{ id: "def", nodes: source.nodes, links: [] }] } }; + op = { ...op, path: ["9", "1"], inner_widget: "loras", promoted: null }; + } else if (route === "promoted") { + op = { ...op, promoted: { value_index: 1, instance_path: ["1"], host_widgets_values: ["head", 1] } }; + } + assertRejectedWithoutMutation(source, op, "malformed_op", catalog); + }); + + it("keeps IDs stable for field edits and unchanged count writes in both arrival orders", () => { + const seed = mint(workflow(), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const count: Op = { ...fixture.op, op_id: "b".repeat(32), widget: "loras", value: 2 }; + for (const ops of [[fixture.op, count], [count, fixture.op]]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, bytes); + expect(applyOps(doc, ops, catalog).outcomes.map((outcome) => outcome.outcome)).toEqual(["applied", "applied"]); + expect(project(doc, catalog).nodes[0]).toMatchObject({ properties: { dynamicGroupRows: ids }, widgets_values_named: { "weights.0.weight": 0.9 } }); + doc.destroy(); + } + seed.destroy(); + }); + + it("uses schema v6 and refuses an old document without relabelling", () => { + expect(SCHEMA_VERSION).toBe(6); + const doc = mint(workflow(), catalog); + doc.getMap("meta").set("schema_version", 5); + const before = Y.encodeStateAsUpdate(doc); + expect(() => project(doc, catalog)).toThrow(SchemaVersionError); + expect(() => readGraph(doc)).toThrow(SchemaVersionError); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + doc.destroy(); + }); +}); diff --git a/test/link-state-foundation.test.ts b/test/link-state-foundation.test.ts index 1ebea3f..86c728d 100644 --- a/test/link-state-foundation.test.ts +++ b/test/link-state-foundation.test.ts @@ -25,10 +25,10 @@ function workflow(): WorkflowJSON { }; } -describe("schema v5 retains first-class imported link state", () => { +describe("schema v6 retains first-class imported link state", () => { it("stores complete concrete, full-name promoted, and grown descriptors", () => { const doc = mint(workflow(), catalog); - expect(SCHEMA_VERSION).toBe(5); + expect(SCHEMA_VERSION).toBe(6); expect(readLinkState(doc)).toEqual({ "10": { version: 1, authority: "imported", tuple: [10, 1, 0, 2, 0, "IMAGE"], destination: { kind: "concrete", to_slot: 0, slot: { name: "images", type: "IMAGE", link: 10 } } }, "11": { version: 1, authority: "imported", tuple: [11, 1, 0, 3, 0, "IMAGE"], destination: { kind: "promoted", to_slot: 0, name: "nested.dynamic.image", slot: { name: "nested.dynamic.image", type: "IMAGE", link: 11, widget: { name: "image" } } } }, diff --git a/test/readonly-surface.test.ts b/test/readonly-surface.test.ts index 11817e3..87f8070 100644 --- a/test/readonly-surface.test.ts +++ b/test/readonly-surface.test.ts @@ -189,7 +189,7 @@ describe("read-only surface — it actually reads the document", () => { it("readMeta returns schema/catalog version and the §6 passthrough keys", () => { const meta = readMeta(fixtureDoc()); - expect(meta["schema_version"]).toBe(5); + expect(meta["schema_version"]).toBe(6); expect(meta["catalog_version"]).toBe(CATALOG_SHA); expect(meta["groups"]).toEqual([{ title: "g", bounding: [0, 0, 10, 10] }]); expect(meta["extra"]).toEqual({ ds: { scale: 1, offset: [0, 0] } }); @@ -473,7 +473,7 @@ describe("read-only surface — the KA-11 read gate (#38)", () => { } const UNREADABLE: [string, () => Y.Doc][] = [ - ["newer than this package", () => docWithSchemaVersion(6)], + ["newer than this package", () => docWithSchemaVersion(7)], ["older than this package", () => docWithSchemaVersion(1)], ["not an integer version", () => docWithSchemaVersion("1")], ["a zero version", () => docWithSchemaVersion(0)], @@ -529,7 +529,7 @@ describe("read-only surface — the KA-11 read gate (#38)", () => { // The positive control: without it every assertion above passes for a // surface that refused unconditionally. const doc = fixtureDoc(); - expect(readMeta(doc)["schema_version"]).toBe(5); + expect(readMeta(doc)["schema_version"]).toBe(6); expect(Object.keys(readGraph(doc).nodes).sort()).toEqual([ String(KSAMPLER_ID), String(NOTE_ID), @@ -709,7 +709,7 @@ describe("read-only surface — the KA-11 read gate (#38)", () => { // an untypable root as content instead, so the refusal type matches. const doc = new Y.Doc(); doc.getArray("nodes").push([1]); - metaMap(doc).set("schema_version", 6); + metaMap(doc).set("schema_version", 7); expect(() => project(doc, catalog)).toThrow(SchemaVersionError); expect(() => readGraph(doc)).toThrow(SchemaVersionError); expect(() => readStamps(doc)).toThrow(SchemaVersionError); diff --git a/test/schema.test.ts b/test/schema.test.ts index 269d90f..ff6f353 100644 --- a/test/schema.test.ts +++ b/test/schema.test.ts @@ -9,11 +9,11 @@ import { import { OPAQUE_WIDGETS_KEY, SCHEMA_VERSION, linksMap, nodesMap } from "../src/index.js"; describe("schema", () => { - it("pins SCHEMA_VERSION at 5", () => { - expect(SCHEMA_VERSION).toBe(5); + it("pins SCHEMA_VERSION at 6", () => { + expect(SCHEMA_VERSION).toBe(6); }); - it("initDoc creates the schema v5 layout with lazy clock reservations", () => { + it("initDoc creates the schema v6 layout with lazy clock reservations", () => { const doc = new Y.Doc(); initDoc(doc, "object_info@2026-08-01"); expect(nodesMap(doc)).toBeInstanceOf(Y.Map);