From 58a21ebcf22e3c83683faef3757723d938d6ab49 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Sun, 11 Oct 2026 14:58:44 +0900 Subject: [PATCH] feat: add atomic DynamicGroup row operations --- README.md | 5 + docs/INVARIANTS.md | 4 +- docs/decisions/EXCEPTIONS.md | 2 + docs/multiplayer-schema.md | 37 +- fixtures/golden-vectors/wire-layout.json | 10 +- src/applier.ts | 337 ++++++++- src/collab-trace.ts | 10 + src/compact.ts | 25 + src/doc.ts | 5 +- src/dynamic-combos.ts | 10 +- src/dynamic-row-ops.ts | 204 ++++++ src/dynamic-row-state.ts | 310 ++++++++ src/dynamic-row-topology.ts | 472 ++++++++++++ src/index.ts | 9 +- src/project.ts | 79 ++- src/read.ts | 35 +- src/stamps.ts | 14 + src/types.ts | 77 +- src/widget-form.ts | 4 +- src/widget-identity.ts | 8 + test/atomic-dynamic-group-rows.test.ts | 670 ++++++++++++++++++ test/clock.test.ts | 4 +- test/convergence.test.ts | 7 + test/doc-mint-mutation-survivors.test.ts | 2 +- test/dynamic-group-row-identity.test.ts | 12 +- test/link-state-foundation.test.ts | 4 +- .../full-op-pool.permutation.test.ts | 28 +- test/readonly-surface.test.ts | 12 +- test/schema.test.ts | 6 +- 29 files changed, 2313 insertions(+), 89 deletions(-) create mode 100644 src/dynamic-row-ops.ts create mode 100644 src/dynamic-row-state.ts create mode 100644 src/dynamic-row-topology.ts create mode 100644 test/atomic-dynamic-group-rows.test.ts diff --git a/README.md b/README.md index c38cc91..69c3be0 100644 --- a/README.md +++ b/README.md @@ -380,6 +380,11 @@ ADR-032 and schema Amendment A21. | `delete_node` | `node_id`, `removed_links` | yes | | `clear` | `removed_nodes` | no | | `insert_workflow` | `workflow` containing required raw-ID `nodes` plus optional `links`, `groups`, and `definitions`; the applier remaps IDs deterministically from `op_id` | no | +| `dynamic_group_insert_rows` | Row owner/lifetime/group, immutable anchor, complete field values; row IDs derive from op ID and ordinal. Provisional schema-v7 extension | yes | +| `dynamic_group_set_row` | Row owner/lifetime/group/ID and field values; optional promoted host address. Provisional schema-v7 extension | yes | +| `dynamic_group_delete_rows` | Row owner/lifetime/group and row IDs, delete-wins. Provisional schema-v7 extension | yes | +| `dynamic_group_connect` | Row/field address, source output, link identity and input/link types. Provisional schema-v7 extension | yes | +| `dynamic_group_disconnect` | Row/field address. Provisional schema-v7 extension | yes | | `reset_doc` | see [open questions](docs/api-contract-proposal.md) — currently rejected `op_deferred` by this package | no | `FROZEN_OPS`, `DEFERRED_OPS`, and `BATCHABLE_OPS` are exported so you can check diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 4ee9481..8d56734 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -24,7 +24,7 @@ This is the machine-addressable review log for the package. IDs are stable; do n **Rule:** Applier, projection, and mint have zero DOM/framework/LiteGraph/server-only dependencies and run identically in browser and host; assert `yjs`-only directly, not merely by denylist. **Why:** A peer, edge, browser, and Node host must execute one implementation identically. Schema v3 added the first-class `__link_state` root; v4 adds `__clock_reservations`, keeping `__stamps` limited to winning write-target stamps. Private alpha has no compatibility reader: old layouts are re-minted, while `migrate()` refuses to relabel them. -**Enforced by:** `scripts/check-purity.mjs` (package level), `scripts/check-import-graph.mjs` + `.dependency-cruiser.cjs` rule `src-runtime-dep-is-yjs-only` (module-graph level, per source module), `test/purity.test.ts`, `test/parity.test.ts`, and [`purity`](../.agents/checks/purity.md). Cross-language implementations must pass the canonical golden vectors in `fixtures/golden-vectors/`. The current schema §1 root-map NAMES (`nodes`, `links`, `definitions`, `meta`, `__applied`, `__stamps`, `__link_state`, `__clock_reservations`) and the reserved per-node `__widgets_opaque`, `__incarnation` and (Amendment A24) `__widgets_form` keys are the shared wire layout. Before schema v3 added `__link_state`, the historical inventory was seven names: six roots plus that reserved widget key. Those seven were pinned by name in `test/doc-mint-mutation-survivors.test.ts`; every other reader in this package went through `nodesMap()`/`linksMap()`/… , so a consistent rename was invisible to most of the suite: measured one key at a time against the pre-existing tests, renaming `links`, `definitions`, `__applied` or `__stamps` left 277/277 green, while `nodes` reddened 2 and `meta` reddened 6. Four of those historical seven names had no holder at all before this file. The current nine names are additionally published as the language-agnostic vector `fixtures/golden-vectors/wire-layout.json` and held against the ENCODED bootstrap snapshot, against a replica that has only those bytes, and against this file and schema §1, by `test/wire-layout-contract.test.ts` — so a rename must move code, vector and both documents together, which is what makes a deliberate one visible in review. **Scoped, because the wording invites the wider reading:** that test does NOT force the `SCHEMA_VERSION` bump or the old-layout disposition KA-11 and schema §1/§10 require of a layout change. Its last case checks only that the three declarations of `SCHEMA_VERSION` agree with each other, and a rename applied consistently to all four places leaves them agreeing at 1 — measured, with that file fully green. The bump obligation is **UNGUARDED — see roadmap**; only its consistency once taken is held. +**Enforced by:** `scripts/check-purity.mjs` (package level), `scripts/check-import-graph.mjs` + `.dependency-cruiser.cjs` rule `src-runtime-dep-is-yjs-only` (module-graph level, per source module), `test/purity.test.ts`, `test/parity.test.ts`, and [`purity`](../.agents/checks/purity.md). Cross-language implementations must pass the canonical golden vectors in `fixtures/golden-vectors/`. The current schema §1 root-map NAMES (`nodes`, `links`, `definitions`, `meta`, `__applied`, `__stamps`, `__link_state`, `__clock_reservations`) and the reserved per-node `__widgets_opaque`, `__incarnation` and (Amendment A24) `__widgets_form`, (Amendment A27) `__dynamic_group_state` node keys and `__dynamic_group_slot` input marker are the shared wire layout. Before schema v3 added `__link_state`, the historical inventory was seven names: six roots plus that reserved widget key. Those seven were pinned by name in `test/doc-mint-mutation-survivors.test.ts`; every other reader in this package went through `nodesMap()`/`linksMap()`/… , so a consistent rename was invisible to most of the suite: measured one key at a time against the pre-existing tests, renaming `links`, `definitions`, `__applied` or `__stamps` left 277/277 green, while `nodes` reddened 2 and `meta` reddened 6. Four of those historical seven names had no holder at all before this file. The current nine names are additionally published as the language-agnostic vector `fixtures/golden-vectors/wire-layout.json` and held against the ENCODED bootstrap snapshot, against a replica that has only those bytes, and against this file and schema §1, by `test/wire-layout-contract.test.ts` — so a rename must move code, vector and both documents together, which is what makes a deliberate one visible in review. **Scoped, because the wording invites the wider reading:** that test does NOT force the `SCHEMA_VERSION` bump or the old-layout disposition KA-11 and schema §1/§10 require of a layout change. Its last case checks only that the three declarations of `SCHEMA_VERSION` agree with each other, and a rename applied consistently to all four places leaves them agreeing at 1 — measured, with that file fully green. The bump obligation is **UNGUARDED — see roadmap**; only its consistency once taken is held. ### KA-4 — The applier is deterministic and idempotent **Rule:** Same op-set + causal order gives the same projection; an identical duplicate `op_id` is a true no-op with byte-identical `encodeStateAsUpdate`, while reuse with a different canonical payload is rejected without mutation. @@ -115,6 +115,8 @@ 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. +Schema v7 adds private atomic row registers and stable row link destinations (schema A27). A v6 reader cannot project them; v1–v6 layouts remain refused. `test/atomic-dynamic-group-rows.test.ts` holds stable addressing, exact retry bytes, row wire keys and opposite-order row replay. Reader/host adoption and FE sign-off remain required before rollout. + ### 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 30ad0a7..c220d16 100644 --- a/docs/decisions/EXCEPTIONS.md +++ b/docs/decisions/EXCEPTIONS.md @@ -26,3 +26,5 @@ is retained as history, not authorization to accept unprojectable writes. | 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. | + +| 2026-10-11 (PROPOSED) | FC-10 / KA-12 | A27 adds five package-local DynamicGroup row operations and schema-v7 private registers/link destinations. They are not in the pinned upstream vocabulary. Tagged rows require a supplied compatible group catalog and stable-ID operations; writer min/max admission is separate from receiver replay. The draft implements the requested full row-editing contract without enabling producers or claiming consumer sign-off. | `src/dynamic-row-state.ts`, `src/dynamic-row-ops.ts`, `src/dynamic-row-topology.ts`, `src/applier.ts`; schema Amendment A27 | Owner and approval: maintainer's to assign. Sunset: adopt/pin the reviewed CLI and FE producer contract, wire admission into the host sequence-CAS, and verify compatible readers before rollout. | diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index bd4cb3e..8e58ba7 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -1,6 +1,6 @@ -# Multiplayer workflow-document schema — v6 +# Multiplayer workflow-document schema — v7 -`SCHEMA_VERSION = 6` +`SCHEMA_VERSION = 7` > **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 = 6`, stored in `meta.schema_version` at mint. +- `SCHEMA_VERSION = 7`, 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 @@ -2515,3 +2515,34 @@ Ordinary scalar count changes on tagged groups are refused before mutation on to 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. + + +## Amendment A27 — 2026-10-11 — Atomic DynamicGroup row operations (schema v7) + +This is a provisional package contract, stacked on A26. It is not yet an adopted producer vocabulary or a release approval. Core `object_info`, numbered prompt inputs and node execution arguments do not change. + +Five new operations require `node_id`, `node_incarnation` and `group`. An optional nonempty `path` lists containing subgraph instances; `node_id` identifies the leaf separately. Structural/default writes retain §5.3's shared-definition refusal. + +| Operation | Payload | Effect | +| --- | --- | --- | +| `dynamic_group_insert_rows` | `after_row_id: string | null`, `rows: Record[]` | Inserts complete creator-supplied field values after an immutable row anchor. Each ID is `row::`; receivers never allocate IDs or write current defaults. | +| `dynamic_group_set_row` | `row_id`, `values` | Claims one LWW register per supplied field. An optional `host_path` plus `host_incarnation` writes a materialized promoted host value instead of the shared definition default. | +| `dynamic_group_delete_rows` | distinct nonempty `row_ids` | Permanently tombstones those row identities; a late edit cannot target their successors. | +| `dynamic_group_connect` | `row_id`, `field`, `from_node`, `from_slot`, `link_id`, `link_type`, `input_type` | Claims the logical row input and the existing normalized complete-link identity independently. | +| `dynamic_group_disconnect` | `row_id`, `field` | Clears that logical input, retaining its winning stamp. It does not create a converted socket for an unconverted widget. | + +Insertion anchors survive deletion. Concurrent siblings sort by descending creator stamp, with the immutable baseline continuation last. A row's field writes, links and delete-wins state can arrive before its insertion; pending records remain hidden until their anchor chain reaches the baseline. Distinct fields merge independently. Delete-wins is permanent for an ID, so reinsertion uses a new operation ID. Reusing an insertion identity with a different digest remains refused after compaction. + +The private node key `__dynamic_group_state` holds a Y.Map per group, with `fields`, `initial_ids` and row-ID-keyed `records`. Records retain immutable insertion anchor/stamp/digest, winning field values, converted slot data and semantic deletion tombstones. Field dictionaries are stored as entry arrays so literal names such as `__proto__` survive lib0 decoding. Baseline node properties, host positions and input placement stay immutable internally. Existing converted inputs become private `__dynamic_group_slot` markers. Projection derives the live manifest/count, numbered names, declared form and named/ordered sidecars. A workflow payload cannot forge either private key. + +Row fields claim `["dynamic_group_widget", owner, incarnation, group, row_id, field]`; row connections claim the corresponding `dynamic_group_input` target. Interior `owner` is the canonical definition/leaf pair. Promoted values use a separate target including both host and leaf owners/lifetimes. Every register reads the creator's in-op stamp, including when transport envelope fields disagree. The existing op ledger still makes exact retries byte-identical. + +A `dynamic_group` durable link destination adds group, row ID, field and target incarnation to the existing version-1 descriptor. Interior link identity is scoped by canonical definition ID rather than the route spelling. Its baseline tuple index is placement only; the stable fields determine the projected index. Reassigning a normalized link ID scrubs the previous row owner too. Concrete input claims and Autogrow materialization remain independent of the complete-link winner; reranking a grown family cannot move a link owned by another destination. Winning input claims retire previous reconstruction descriptors even while their sources are absent. Source restoration can recover the logical connection, but cannot write a private input marker or attach it to a deleted row/new target lifetime. + +Projection removes a deleted row's converted inputs and backing links, then walks definition input ports, exposures, proxy widgets, host values and external links bottom-up, including two-level promotions. Unrelated inputs, dangling tuples and serializer fields are retained. Materialized instance paths refuse structural row edits on self-described or non-positional promoted hosts before mutation; a stable host write refuses missing or ambiguous bindings. Legacy numeric row input writes and positional promoted writes into row-controlled hosts are refused, so a shifted index cannot write a different row. Untagged nodes retain the old paths. + +`admitDynamicGroupRowOp` is read-only preflight for the writer's existing sequence-CAS transaction. It checks current lifetimes, known anchors/rows, supplied template fields, current min/max and source/host bindings before persistence. Writers must rerun it after a CAS conflict. It does not reserve a server sequence or replace host authorization. Replay applies an already-admitted op set without rechecking transient min/max: shrink/growth can arrive in the reverse order. This PR does not wire admission into a live host, CLI or frontend, and does not enable tools or producers. + +Schema v7 fences v6 readers that cannot interpret private row markers/registers or stable link destinations. Every old document remains fail-closed and must be re-minted from source with coordinated readers/hosts; no relabelling migration is provided. `compact` starts a new Yjs lineage but copies raw row-aware graph storage, winning stamps, immutable anchors and semantic tombstones. This removes Yjs struct history and the old applied ledger, not semantic row history. Tombstone retention, realistic churn/performance, consumer parity and end-to-end producer adoption still require validation before release. + +Tests use the existing composite catalog fixture and rejection oracle. The dedicated suite covers middle-row changes, opposite-order replay, pending rows, per-field conflicts, exact retry bytes, compaction/reconnect, converted links, source lifecycles, one/two-level promotions, mixed socket/widget host ordinals and read-only admission. The full op-pool matrix includes all five kinds. Its standing `delete_node.removed_links` alias risk is retained explicitly rather than claimed fixed. No corpus expectation is regenerated from this applier. diff --git a/fixtures/golden-vectors/wire-layout.json b/fixtures/golden-vectors/wire-layout.json index d101b75..fab9b4d 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 \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, + "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. Amendment A27 uses schema v7 for private dynamic_group_state node registers and dynamic_group_slot input markers; old readers cannot interpret them. These reserved fields are created only by row operations and never emitted as workflow fields.", + "schema_version": 7, "roots": { "nodes": "nodes", "links": "links", @@ -15,6 +15,10 @@ "reserved_node_keys": { "opaque_widgets": "__widgets_opaque", "node_incarnation": "__incarnation", - "widget_form": "__widgets_form" + "widget_form": "__widgets_form", + "dynamic_group_state": "__dynamic_group_state" + }, + "reserved_input_keys": { + "dynamic_group_slot": "__dynamic_group_slot" } } diff --git a/src/applier.ts b/src/applier.ts index 2683d2b..2813934 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -99,6 +99,7 @@ import { nodesMap, nodeIncarnation, resolveDefinition, + ROOT_LINK_STATE, stampsMap, widgetStorageOf, } from "./doc.js"; @@ -108,6 +109,7 @@ import { formFinalOccurrence, formIndexOf, storedWidgetFormOf, + WIDGET_FORM_KEY, } from "./widget-form.js"; import { linkHasMissingEndpoint, remapInsertedWorkflowIds } from "./remap.js"; import { sha256Hex } from "./digest.js"; @@ -154,6 +156,13 @@ import { import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js"; import { groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import { dynamicGroupRowsOf } from "./dynamic-group-rows.js"; +import { commitRowMutation, prepareRowMutation, validateRowOp, rowFieldStamp } from "./dynamic-row-ops.js"; +import { activeRowGroups, currentRowIds, storedRowGroup, groupRows, liveRowIds, rowSlot, encodeRowRecord, decodeRowRecord, type RowSlot } from "./dynamic-row-state.js"; +import type { ConcreteConnectOp, DynamicGroupRowOp } from "./types.js"; +import { promotedRowValueIndex, rowTopologySnapshot, rowControlledHostInputs } from "./dynamic-row-topology.js"; +import { DYNAMIC_GROUP_SLOT_KEY } from "./types.js"; +import { assertReadableSchema } from "./schema-version.js"; +import { dynamicGroupRowId } from "./dynamic-row-ops.js"; import { optionOwnedWidgets, projectedLength, widgetLayoutForWidgets, widgetOrderForValues, widgetOrderForWidgets } from "./dynamic-combos.js"; import { NODE_INCARNATION_KEY, WRITABLE_NODE_FIELDS } from "./types.js"; @@ -253,7 +262,7 @@ export function applyOps(doc: Y.Doc, ops: Op[], catalog?: WidgetCatalog, context } let outcome: Exclude = "applied"; doc.transact(() => { - outcome = dispatch(doc, op, catalog); + outcome = dispatch(doc, op, catalog, digest); // comfy-cli records the op_id even for delete-wins/LWW-dropped no-ops. mset(bookkeeping, op.op_id, digest); }, op.actor); @@ -558,7 +567,7 @@ function validateEnvelope(op: WireOp): void { type SuccessfulOutcome = "applied" | "no-op" | "lww-dropped"; -function dispatch(doc: Y.Doc, op: Op, catalog?: WidgetCatalog): SuccessfulOutcome { +function dispatch(doc: Y.Doc, op: Op, catalog: WidgetCatalog | undefined, digest: string): SuccessfulOutcome { switch (op.op) { case "add_node": return applyAddNode(doc, op, catalog); @@ -578,6 +587,12 @@ function dispatch(doc: Y.Doc, op: Op, catalog?: WidgetCatalog): SuccessfulOutcom return applyDefineSubgraph(doc, op, catalog); case "insert_workflow": return applyInsertWorkflow(doc, op, catalog); + case "dynamic_group_insert_rows": + case "dynamic_group_set_row": + case "dynamic_group_delete_rows": + case "dynamic_group_connect": + case "dynamic_group_disconnect": + return applyDynamicGroupRows(doc, op, catalog, digest); default: // Exhaustiveness guard (issue #21): with every `Op` member cased above, // `op` is `never` here. Add a seventh IMPLEMENTED kind to `Op` and this @@ -596,6 +611,227 @@ function dispatch(doc: Y.Doc, op: Op, catalog?: WidgetCatalog): SuccessfulOutcom } } +function applyDynamicGroupRows(doc: Y.Doc, op: DynamicGroupRowOp, catalog: WidgetCatalog | undefined, digest: string): SuccessfulOutcome { + assertReadableSchema(doc, "DynamicGroup"); + validateRowOp(op); + const resolved = resolveDynamicRowTarget(doc, op, catalog); + const node = resolved?.node; + if (!node || nodeIncarnation(node) !== op.node_incarnation) return "no-op"; + const entry = catalogEntry(catalog, String(node.get("type"))); + if (!entry) throw new OpRejectedError("catalog_required", "DynamicGroup: pinned group catalog is required"); + preflightRowHostShapes(doc, op); + const owner = op.path ? resolved!.canonicalPath : String(op.node_id); + const stamps = stampsMap(doc); + const plan = prepareRowMutation(node, owner, op, entry, stamps, digest); + if (op.op === "dynamic_group_set_row" && op.host_path !== undefined) return applyPromotedDynamicRow(doc, node, owner, op, catalog, stamps); + const scope = op.path ? interiorConnectScope(resolveDefinition(doc, resolved!.canonicalPath[0]!)!, resolved!.canonicalPath[0]!) : undefined; + if (op.op === "dynamic_group_connect") return applyDynamicRowConnection(doc, node, owner, op, scope, plan, stamps); + if (op.op === "dynamic_group_disconnect") return applyDynamicRowDisconnect(doc, node, owner, op, scope, plan, stamps); + commitRowMutation(node, op.group, plan, stamps); + return plan.outcome; +} + +function preflightRowHostShapes(doc: Y.Doc, op: DynamicGroupRowOp): void { + if (op.op !== "dynamic_group_insert_rows" && op.op !== "dynamic_group_delete_rows") return; + let nodes = nodesMap(doc); + for (const container of op.path ?? []) { + const host = nodes.get(container); + if (!host) return; + if (rowControlledHostInputs(doc, host).length > 0 && (host.has(WIDGET_FORM_KEY) || !Array.isArray(host.get(OPAQUE_WIDGETS_KEY)))) throw new OpRejectedError("malformed_op", "DynamicGroup: structural edits require positional promoted host storage"); + const inner = resolveDefinition(doc, String(host.get("type")))?.get("nodes"); + if (!(inner instanceof Y.Map)) return; + nodes = inner as Y.Map>; + } +} + +function applyDynamicRowDisconnect(doc: Y.Doc, node: Y.Map, owner: string | string[], op: Extract, scope: InteriorGraphScope | undefined, plan: ReturnType, stamps: Y.Map): SuccessfulOutcome { + commitRowMutation(node, op.group, plan, stamps); + const target = rowFieldStamp(owner, op.node_incarnation, op.group, op.row_id, op.field, "dynamic_group_input"); + if (plan.stamps.has(target)) { + retireRowInputLinks(doc, op, scope, rowSlot(plan.group.records.get(op.row_id), op.field)?.original_index); + const prior = rowSlot(plan.group.records.get(op.row_id), op.field)?.data["link"]; + if (prior !== undefined && prior !== null) { if (scope) removeLinkInScope(scope, prior); else removeLink(doc, prior); } + } + + return plan.outcome; +} + +function resolveDynamicRowTarget(doc: Y.Doc, op: DynamicGroupRowOp, catalog?: WidgetCatalog): InteriorResolution | null { + if (op.op === "dynamic_group_set_row" && op.host_path !== undefined) return readRowOwner(doc, op); + if (op.path) return resolveInteriorNode(doc, [...op.path, String(op.node_id)], catalog, op.node_incarnation); + const node = nodesMap(doc).get(String(op.node_id)); + return node ? { node, canonicalPath: [String(op.node_id)] } : null; +} + +function applyDynamicRowConnection(doc: Y.Doc, node: Y.Map, owner: string | string[], op: Extract, scope: InteriorGraphScope | undefined, plan: ReturnType, stamps: Y.Map): SuccessfulOutcome { + const nodes = scope?.nodes ?? nodesMap(doc); + const source = nodes.get(String(op.from_node)); + const proxy: ConcreteConnectOp = { ...op, op: "connect", to_node: op.node_id, to_slot: 0 }; + const outputs = source ? requireOutputSlot(source, proxy) : null; + const refusal = arrayItemRefusal(op.link_id) ?? mapValueRefusal(op.link_id); + if (refusal) throw new OpRejectedError("malformed_op", refusal); + const prior = rowSlot(plan.group.records.get(op.row_id), op.field)?.data["link"]; + const inputTarget = rowFieldStamp(owner, op.node_incarnation, op.group, op.row_id, op.field, "dynamic_group_input"); + const inputWon = plan.stamps.has(inputTarget); + if (inputWon) { + commitRowMutation(node, op.group, plan, stamps); + retireRowInputLinks(doc, op, scope, rowSlot(plan.group.records.get(op.row_id), op.field)?.original_index); + if (prior !== undefined && prior !== null && String(prior) !== String(op.link_id)) { + if (scope) removeLinkInScope(scope, prior); else removeLink(doc, prior); + } + } + const claimed = claimLinkIdentity(doc, proxy, scope); + if (!inputWon) return "lww-dropped"; + const slot = setRowSlotLink(node, op.group, op.row_id, op.field, claimed && source ? op.link_id : null)!; + if (claimed) installDynamicRowConnection(doc, op, scope, slot, outputs, stamps); + return plan.outcome; +} + +function retireRowInputLinks(doc: Y.Doc, op: Extract, scope: InteriorGraphScope | undefined, baselineIndex: number | null | undefined): void { + const states = scope ? scope.definition.get(ROOT_LINK_STATE) : linkStateMap(doc); + if (!(states instanceof Y.Map)) return; + const retired: string[] = []; + states.forEach((raw, id) => { + const state = raw as OperationLinkState; + if (String(state.tuple[3]) !== String(op.node_id) || (op.op === "dynamic_group_connect" && id === String(op.link_id))) return; + const dst = state.destination; + const matches = dst.kind === "dynamic_group" + ? dst.node_incarnation === op.node_incarnation && dst.group === op.group && dst.row_id === op.row_id && dst.field === op.field + : baselineIndex != null && dst.to_slot === baselineIndex; + if (matches) retired.push(id); + }); + for (const id of retired) { if (scope) removeLinkInScope(scope, id); else removeLink(doc, id); } +} + +function setRowSlotLink(node: Y.Map, group: string, rowId: string, field: string, link: unknown): RowSlot | null { + const rows = storedRowGroup(node, group)?.get("records"); + if (!(rows instanceof Y.Map)) return null; + const raw = rows.get(rowId); + const row = raw === undefined ? undefined : decodeRowRecord(raw); + if (!rowSlot(row, field)) return null; + const next = structuredClone(row!); + next.slots[field]!.data["link"] = link; + mset(rows, rowId, encodeRowRecord(next)); + return next.slots[field]!; +} + +function installDynamicRowConnection(doc: Y.Doc, op: Extract, scope: InteriorGraphScope | undefined, slot: RowSlot, outputs: Y.Array | null, stamps: Y.Map): void { + const links = scope?.links ?? linksMap(doc); + const toSlot = slot.original_index ?? 0; + const tuple: LinkTuple = [op.link_id, op.from_node, op.from_slot, op.node_id, toSlot, op.link_type]; + if (outputs) mset(links, String(op.link_id), scope ? { id: op.link_id, origin_id: op.from_node, origin_slot: op.from_slot, target_id: op.node_id, target_slot: toSlot, type: op.link_type } : tuple); + const states = scope ? scopedRowLinkState(scope.definition) : linkStateMap(doc); + const state: OperationLinkState = { version: LINK_STATE_DESCRIPTOR_VERSION, authority: { kind: "operation", stamp: stampKey(op) }, tuple, + destination: { kind: "dynamic_group", to_slot: toSlot, slot: structuredClone(slot.data), group: op.group, row_id: op.row_id, field: op.field, node_incarnation: op.node_incarnation } }; + mset(states, String(op.link_id), state); + if (!outputs) return; + const output = outputs.get(op.from_slot) as Y.Map; + let refs = output.get("links"); + if (!(refs instanceof Y.Array)) { refs = new Y.Array(); mset(output, "links", refs); } + if (!(refs as Y.Array).toArray().some((id) => String(id) === String(op.link_id))) apush(refs as Y.Array, op.link_id); + if (scope) recordInteriorLinkOrder(scope.definition, stamps, String(op.link_id), stampKey(op)); +} + +function applyPromotedDynamicRow(doc: Y.Doc, node: Y.Map, owner: string | string[], op: Extract, catalog: WidgetCatalog | undefined, stamps: Y.Map): SuccessfulOutcome { + const plan = promotedRowWrite(doc, node, owner, op, catalog, stamps); + if (!plan) return "no-op"; + if (plan.writes.size === 0) return "lww-dropped"; + mset(plan.host, OPAQUE_WIDGETS_KEY, plan.next); + for (const [key, stamp] of plan.writes) mset(stamps, key, stamp); + return "applied"; +} + +function promotedRowWrite(doc: Y.Doc, node: Y.Map, owner: string | string[], op: Extract, catalog: WidgetCatalog | undefined, stamps: Pick, "get">): { host: Y.Map; next: unknown[]; writes: Map } | null { + const hostPath = op.host_path!; + const hostTarget = resolveInteriorNode(doc, hostPath, catalog, op.host_incarnation, false); + const host = hostTarget?.node; + if (!host || nodeIncarnation(host) !== op.host_incarnation) return null; + const raw = host.get(OPAQUE_WIDGETS_KEY); + if (!Array.isArray(raw)) throw new OpRejectedError("malformed_op", "DynamicGroup: promoted host requires positional values"); + const next = structuredClone(raw); + const writes = new Map(); + for (const [field, value] of Object.entries(op.values)) { + const index = promotedRowValueIndex(doc, host, node, op.group, op.row_id, field); + if (index === null || index >= next.length) throw new OpRejectedError("malformed_op", "DynamicGroup: row field is not materialized on the requested host"); + const hostOwner = hostPath.length === 1 ? hostPath[0]! : hostTarget!.canonicalPath; + const key = JSON.stringify(["dynamic_group_host", hostOwner, op.host_incarnation, owner, op.node_incarnation, op.group, op.row_id, field]); + const prior = stamps.get(key) as StampKey | undefined; + if (prior && compareStampKeys(stampKey(op), prior) <= 0) continue; + next[index] = structuredClone(value); + writes.set(key, stampKey(op)); + } + return { host, next, writes }; +} + +/** Run inside the writer's existing sequence-CAS admission before persisting an op. */ +export function admitDynamicGroupRowOp(doc: Y.Doc, op: DynamicGroupRowOp, catalog: WidgetCatalog): void { + assertReadableSchema(doc, "admitDynamicGroupRowOp"); + inspectOps([op]); + validateRowOp(op); + if (!doc.share.has("nodes")) throw new OpRejectedError("malformed_op", "DynamicGroup: owner is absent"); + if (op.path && !doc.share.has("definitions")) throw new OpRejectedError("malformed_op", "DynamicGroup: interior owner is absent"); + let target: InteriorResolution | null = null; + if (op.path) target = resolveInteriorNode(doc, [...op.path, String(op.node_id)], catalog, op.node_incarnation, false); + if (op.op === "dynamic_group_set_row" && op.host_path !== undefined) target = readRowOwner(doc, op); + const node = op.path ? target?.node : nodesMap(doc).get(String(op.node_id)); + if (!node || nodeIncarnation(node) !== op.node_incarnation) throw new OpRejectedError("malformed_op", "DynamicGroup: owner lifetime is stale"); + const entry = catalogEntry(catalog, String(node.get("type"))); + if (!entry) throw new OpRejectedError("catalog_required", "DynamicGroup: pinned catalog is required"); + preflightRowHostShapes(doc, op); + const data = groupRows(node, op.group, entry); + const meta = entry.dynamic_groups![op.group]!; + checkRowAdmissionBounds(op, data, meta.min, meta.max); + const owner = target?.canonicalPath ?? String(op.node_id); + const stamps = doc.share.has("__stamps") ? doc.getMap("__stamps") : new Map(); + prepareRowMutation(node, owner, op, entry, stamps, opDigest(op)); + if (op.op === "dynamic_group_connect") preflightAdmittedRowConnection(doc, op, target); + if (op.op === "dynamic_group_set_row" && op.host_path && !promotedRowWrite(doc, node, owner, op, catalog, stamps)) throw new OpRejectedError("malformed_op", "DynamicGroup: promoted host lifetime is stale"); +} + +function preflightAdmittedRowConnection(doc: Y.Doc, op: Extract, target: InteriorResolution | null): void { + const scope = op.path ? interiorConnectScope(resolveDefinition(doc, target!.canonicalPath[0]!)!, target!.canonicalPath[0]!) : undefined; + const source = (scope?.nodes ?? nodesMap(doc)).get(String(op.from_node)); + if (!source) throw new OpRejectedError("malformed_op", "DynamicGroup: connection source is absent"); + requireOutputSlot(source, { ...op, op: "connect", to_node: op.node_id, to_slot: 0 }); +} + +function checkRowAdmissionBounds(op: DynamicGroupRowOp, data: ReturnType, min: number, max: number): void { + const live = new Set(liveRowIds(data)); + let count = live.size; + if (op.op === "dynamic_group_insert_rows") { + if (op.after_row_id !== null && data.records.get(op.after_row_id)?.created === undefined) throw new OpRejectedError("malformed_op", "DynamicGroup: insertion anchor is unknown"); + count += op.rows.filter((_row, index) => data.records.get(dynamicGroupRowId(op.op_id, index))?.created === undefined).length; + if (count > max) throw new OpRejectedError("malformed_op", "DynamicGroup: insertion exceeds max rows"); + } else if (op.op === "dynamic_group_delete_rows") { + if (op.row_ids.some((id) => data.records.get(id)?.created === undefined)) throw new OpRejectedError("malformed_op", "DynamicGroup: deletion targets an unknown row"); + count -= op.row_ids.filter((id) => live.has(id)).length; + if (count < min) throw new OpRejectedError("malformed_op", "DynamicGroup: deletion falls below min rows"); + } else if (data.records.get(op.row_id)?.created === undefined) { + throw new OpRejectedError("malformed_op", "DynamicGroup: target row is unknown"); + } +} + +function readRowOwner(doc: Y.Doc, op: DynamicGroupRowOp): InteriorResolution | null { + let nodes = nodesMap(doc); + let owner: string[] | null = null; + for (const container of op.path ?? []) { + const host = nodes.get(container); + const definition = resolveDefinition(doc, host ? String(host.get("type")) : container); + const interior = definition?.get("nodes"); + if (!(interior instanceof Y.Map)) return null; + nodes = interior as Y.Map>; + owner = [String(definition!.get("id")), String(op.node_id)]; + } + const node = nodes.get(String(op.node_id)); + return node ? { node, canonicalPath: owner ?? [String(op.node_id)] } : null; +} + +function scopedRowLinkState(definition: Y.Map): Y.Map { + let state = definition.get("__link_state"); + if (!(state instanceof Y.Map)) { state = new Y.Map(); mset(definition, "__link_state", state); } + return state as Y.Map; +} + function applyDefineSubgraph( doc: Y.Doc, op: DefineSubgraphOp, @@ -1918,6 +2154,7 @@ function applyPromotedHostWrite( mset(stamps, targetKey, key); return "applied"; case "positional": { + if (rowControlledHostInputs(doc, target).length > 0) throw new OpRejectedError("malformed_op", "promoted row values require a row-ID operation"); const current = target.get(OPAQUE_WIDGETS_KEY); const next: unknown[] = Array.isArray(current) ? structuredClone(current) : []; if (next.length <= promoted.valueIndex) { @@ -1966,11 +2203,17 @@ 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")); + const rows = currentRowIds(node); 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") ?? "")); + if (rows && !entry && Object.keys(rows).some((name) => widget.startsWith(`${name}.`) && /^(0|[1-9]\d*)\./.test(widget.slice(name.length + 1)))) { + throw new OpRejectedError("catalog_required", "indexed row writes require a compatible group catalog and row ID"); + } + if (rows && isDynamicGroupField(entry, widget)) { + throw new OpRejectedError("malformed_op", "indexed row fields require a row-ID operation"); + } const refusal = groupCountRefusal(entry, widget, value); if (refusal) throw new OpRejectedError("malformed_op", refusal); if (groupOf(entry, widget) && storedWidgetFormOf(node)) { @@ -1981,6 +2224,30 @@ function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog } } +function rejectUnstableInputIndex(doc: Y.Doc, node: Y.Map, index: number, catalog?: WidgetCatalog): void { + const input = node.get("inputs"); + if (!(input instanceof Y.Array)) return; + const entry = catalogEntry(catalog, String(node.get("type"))); + const ids = currentRowIds(node); + let boundary = Infinity; + const hostRows = rowControlledHostInputs(doc, node); + if (hostRows.length > 0) boundary = Math.min(boundary, ...hostRows); + input.forEach((slot, position) => { + if (!(slot instanceof Y.Map)) return; + const name = slot.get("name"); + if (slot.has(DYNAMIC_GROUP_SLOT_KEY) || (ids && typeof name === "string" && isDynamicGroupField(entry, name))) boundary = Math.min(boundary, position); + }); + const projection = rowTopologySnapshot(doc)?.nodes.find((candidate) => String(candidate.id) === String(node.get("id"))); + if (projection && Array.isArray(projection.inputs)) { + for (let position = 0; position < input.length; position++) { + const old = input.get(position); + const current = projection.inputs[position] as Record | undefined; + if (old instanceof Y.Map && old.get("name") !== current?.["name"]) { boundary = Math.min(boundary, position); break; } + } + } + if (index >= boundary) throw new OpRejectedError("malformed_op", "row-controlled inputs require a row-ID connection address"); +} + function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): SuccessfulOutcome { const { interior, promoted } = validateWidgetOp(op); // Interior paths have several legal spellings (definition id and instance @@ -2494,7 +2761,7 @@ function interiorConnectScope(definition: Y.Map, definitionId: string): return { nodes: nodes as Y.Map>, links, definition }; } -function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorGraphScope): SuccessfulOutcome { +function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorGraphScope, catalog?: WidgetCatalog): SuccessfulOutcome { const linkRefusal = arrayItemRefusal(op.link_id) ?? mapValueRefusal(op.link_id); if (linkRefusal !== null) { throw new OpRejectedError("malformed_op", `connect: link_id: ${linkRefusal}`); @@ -2503,6 +2770,7 @@ function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorGraphSco const src = scope.nodes.get(String(op.from_node)); const dst = scope.nodes.get(String(op.to_node)); if (!dst) return "no-op"; + rejectUnstableInputIndex(doc, dst, op.to_slot as number, catalog); const sourceOutputs = src ? requireOutputSlot(src, op) : null; const toIdx = op.to_slot as number; const inputs = dst.get("inputs"); @@ -2642,7 +2910,7 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe if (op.path && op.path.length > 0) { const scope = resolveInteriorGraphScope(doc, op, catalog); if (scope === null) return "no-op"; - return applyInteriorConnect(doc, op, scope); + return applyInteriorConnect(doc, op, scope, catalog); } const nodes = nodesMap(doc); @@ -2709,9 +2977,10 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe // Autogrow is NOT a shared register: every grow mints its own slot keyed by // `grow_id`, so two concurrent grows onto one base both survive and there // is nothing to gate (vocabulary §1.2 / amendment v1.2's carve-out). - if (!claimLinkIdentity(doc, op)) return "lww-dropped"; - if (!src) return "no-op"; // source concurrently deleted → no-op (delete wins) - return growInputSlot(doc, dst, op, count, catalog); + const identityWon = claimLinkIdentity(doc, op); + if (!src) return identityWon ? "no-op" : "lww-dropped"; + const index = growInputSlot(doc, dst, op, count, catalog); + return identityWon ? index : "lww-dropped"; } // `to_slot`'s type was settled by `requireOpOnlyValid`. const toIdx = op.to_slot as number; @@ -2720,6 +2989,7 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe } function claimConcreteInput(dst: Y.Map, toIdx: number): boolean { + rejectUnstableInputIndex(doc, dst, toIdx, catalog); const ins = dst.get("inputs"); // STATE-DEPENDENT half only: the op-only domain (integer, non-negative) was // settled by `requireOpOnlyValid` above, before any document read. @@ -2734,7 +3004,7 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe throw new OpRejectedError("input_slot_missing", `connect: input slot ${toIdx} is not a slot record`); } - if (!claimLinkIdentity(doc, op)) return false; + const identityWon = claimLinkIdentity(doc, op); // ---- The concrete-input LWW register (op-vocabulary-v1.md amendment v1.2) // @@ -2768,7 +3038,8 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe mset(stamps, targetKey, key); const prev = slot.get("link"); if (prev != null && prev !== op.link_id) removeLink(doc, prev); - return true; + if (!identityWon) mset(slot, "link", null); + return identityWon; } const toIdx = claimDestination(dst); @@ -2835,7 +3106,7 @@ function operationLinkDestination( function claimLinkIdentity(doc: Y.Doc, op: ConnectOp, scope?: InteriorGraphScope): boolean { const stamps = stampsMap(doc); const normalizedId = String(op.link_id); - const targetKey = JSON.stringify(["link", ...(scope && op.path ? [op.path.map(String)] : []), normalizedId]); + const targetKey = JSON.stringify(["link", ...(scope ? [[String(scope.definition.get("id"))]] : []), normalizedId]); const prior = stamps.get(targetKey) as StampKey | undefined; const key = stampKey(op); if (prior != null && compareStampKeys(key, prior) <= 0) return false; @@ -3081,7 +3352,7 @@ function normalizeGrowFamily( } const linkId = snapshot["grow_id"]; const link = linksMap(doc).get(String(linkId)); - if (Array.isArray(link)) { + if (Array.isArray(link) && String(link[3]) === String(toNode)) { const updated = [...link]; updated[4] = positions[rank]; mset(linksMap(doc), String(linkId), updated); @@ -3209,6 +3480,8 @@ function removeLink(doc: Y.Doc, linkId: unknown): void { function removeLinkInScope(scope: InteriorGraphScope, linkId: unknown): void { const key = String(linkId); if (scope.links.has(key)) mdel(scope.links, key); + const states = scope.definition.get("__link_state"); + if (states instanceof Y.Map && states.has(key)) mdel(states, key); scrubNodeLinkRefs(scope.nodes, (candidate) => candidate != null && String(candidate) === key); const linkOrder = scope.definition.get("link_order"); if (Array.isArray(linkOrder)) { @@ -3226,6 +3499,16 @@ function scrubNodeLinkRefs( shouldRemove: (linkId: unknown) => boolean, ): void { nodes.forEach((node) => { + for (const [group, data] of activeRowGroups(node)) { + const rows = storedRowGroup(node, group)!.get("records") as Y.Map; + for (const [id, raw] of data.records) { + const selected = Object.entries(raw.slots).filter(([_field, slot]) => shouldRemove(slot.data["link"])); + if (selected.length === 0) continue; + const next = structuredClone(raw); + for (const [field] of selected) next.slots[field]!.data["link"] = null; + mset(rows, id, encodeRowRecord(next)); + } + } const ins = node.get("inputs"); if (ins instanceof Y.Array) { ins.forEach((slot: unknown) => { @@ -3457,14 +3740,10 @@ function restoreDurableLinks(doc: Y.Doc, nodeId: unknown): void { const outs = src.get("outputs"); if (!(outs instanceof Y.Array) || !(outs.get(tuple[2]) instanceof Y.Map)) return; - const slot = restoreDestinationInput(dst, state); - if (slot === null) return; - const incumbent = slot.get("link"); - if (incumbent != null && String(incumbent) !== String(tuple[0])) return; + if (!restoreLinkDestination(dst, state)) return; const links = linksMap(doc); if (!links.has(linkKey)) mset(links, linkKey, structuredClone(tuple)); - mset(slot, "link", tuple[0]); const outPort = outs.get(tuple[2]) as Y.Map; let outLinks = outPort.get("links"); if (!(outLinks instanceof Y.Array)) { @@ -3477,6 +3756,27 @@ function restoreDurableLinks(doc: Y.Doc, nodeId: unknown): void { }); } +function restoreLinkDestination(dst: Y.Map, state: OperationLinkState): boolean { + if (state.destination.kind === "dynamic_group") return restoreRowDestination(dst, state); + const slot = restoreDestinationInput(dst, state); + if (slot === null) return false; + const incumbent = slot.get("link"); + if (incumbent != null && String(incumbent) !== String(state.tuple[0])) return false; + mset(slot, "link", state.tuple[0]); + return true; +} + +function restoreRowDestination(dst: Y.Map, state: OperationLinkState): boolean { + const destination = state.destination; + if (destination.kind !== "dynamic_group" || nodeIncarnation(dst) !== destination.node_incarnation) return false; + const group = activeRowGroups(dst).get(destination.group); + const row = group?.records.get(destination.row_id); + const slot = rowSlot(row, destination.field); + if (!row || row.created === undefined || row.deleted || !slot) return false; + if (slot.data["link"] != null && String(slot.data["link"]) !== String(state.tuple[0])) return false; + return setRowSlotLink(dst, destination.group, destination.row_id, destination.field, state.tuple[0]) !== null; +} + function restoreDestinationInput(dst: Y.Map, state: OperationLinkState): Y.Map | null { let ins = dst.get("inputs"); if (!(ins instanceof Y.Array)) { @@ -3494,7 +3794,7 @@ function restoreDestinationInput(dst: Y.Map, state: OperationLinkState) inputArray.insert(slotIndex, [slot]); } const slot = inputArray.get(destination.to_slot); - return slot instanceof Y.Map ? slot : null; + return slot instanceof Y.Map && !slot.has(DYNAMIC_GROUP_SLOT_KEY) ? slot : null; } /** @@ -3577,6 +3877,7 @@ function applyDisconnect(doc: Y.Doc, op: DisconnectOp): SuccessfulOutcome { const nodes = nodesMap(doc); const dst = nodes.get(String(op.to_node)); if (!dst) return retireStrandedLink(doc, op) ? "applied" : "no-op"; + rejectUnstableInputIndex(doc, dst, op.to_slot); const ins = dst.get("inputs"); if (!(ins instanceof Y.Array) || op.to_slot >= ins.length) { diff --git a/src/collab-trace.ts b/src/collab-trace.ts index 5fe7d1e..1e962e2 100644 --- a/src/collab-trace.ts +++ b/src/collab-trace.ts @@ -5,6 +5,8 @@ * format and intentionally exposes no replay, merge, comparator, Yjs, or mint * API. Consumers render captured decisions; they must never recompute them. */ +import { validateRowOp } from "./dynamic-row-ops.js"; +import type { DynamicGroupRowOp } from "./types.js"; import { assertNever } from "./exhaustive.js"; import { compareStampKeys } from "./stamps.js"; import { FROZEN_OPS, WRITABLE_NODE_FIELDS, type Op, type StampKey } from "./types.js"; @@ -461,6 +463,14 @@ function assertOpPayload(value: unknown, context: string) { case "clear": assertNodeIdArray(required(payload, "removed_nodes", context), `${context}.removed_nodes`); break; + case "dynamic_group_insert_rows": + case "dynamic_group_set_row": + case "dynamic_group_delete_rows": + case "dynamic_group_connect": + case "dynamic_group_disconnect": + try { validateRowOp(payload as unknown as DynamicGroupRowOp); } + catch (error) { invalid(context, error instanceof Error ? error.message : "invalid row operation"); } + break; case "define_subgraph": asString(required(payload, "subgraph_id", context), `${context}.subgraph_id`); asRecord(required(payload, "subgraph_definition", context), `${context}.subgraph_definition`); diff --git a/src/compact.ts b/src/compact.ts index 4a8d92b..8f9c494 100644 --- a/src/compact.ts +++ b/src/compact.ts @@ -72,6 +72,7 @@ import { project } from "./project.js"; import { docCatalogPin } from "./read.js"; import { assertReadableSchema } from "./schema-version.js"; import { LEGACY_NODE_INCARNATION, NODE_INCARNATION_KEY, type WidgetCatalog } from "./types.js"; +import { rowTopologySnapshot } from "./dynamic-row-topology.js"; /** Meta internals that mint re-derives from the projection; copying them would shadow the fresh value. */ const REDERIVED_META_INTERNALS: readonly string[] = ["__definitions_extra"]; @@ -86,6 +87,11 @@ export function compact(doc: Y.Doc, catalog: WidgetCatalog): Y.Doc { assertReadableSchema(doc, "compact"); const fresh = mint(project(doc, catalog), catalog, docCatalogPin(doc)); fresh.transact(() => { + if (rowTopologySnapshot(doc) !== null) { + replaceStorage(nodesMap(doc), nodesMap(fresh)); + replaceStorage(doc.getMap("links"), fresh.getMap("links")); + replaceStorage(definitionsMap(doc), definitionsMap(fresh)); + } carryNodeIncarnations(nodesMap(doc), nodesMap(fresh)); carryDefinitionInternals(definitionsMap(doc), definitionsMap(fresh)); carryMetaInternals(doc, fresh); @@ -96,6 +102,25 @@ export function compact(doc: Y.Doc, catalog: WidgetCatalog): Y.Doc { return fresh; } +function cloneStorage(value: unknown): unknown { + if (value instanceof Y.Map) { + const clone = new Y.Map(); + value.forEach((child, key) => clone.set(key, cloneStorage(child))); + return clone; + } + if (value instanceof Y.Array) { + const clone = new Y.Array(); + clone.push(value.toArray().map(cloneStorage)); + return clone; + } + return structuredClone(value); +} + +function replaceStorage(from: Y.Map, to: Y.Map): void { + for (const key of [...to.keys()]) to.delete(key); + from.forEach((value, key) => to.set(key, cloneStorage(value) as T)); +} + function carryNodeIncarnations(from: Y.Map>, to: Y.Map>): void { from.forEach((node, key) => { const target = to.get(key); diff --git a/src/doc.ts b/src/doc.ts index 01f1f13..358044b 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -31,6 +31,8 @@ import { SCHEMA_VERSION, type WidgetCatalog, type WidgetCatalogEntry, + DYNAMIC_GROUP_STATE_KEY, + DYNAMIC_GROUP_SLOT_KEY, type WorkflowNode, } from "./types.js"; import { widgetIdentityFromStorageKey, widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; @@ -814,6 +816,7 @@ function plainToYMap(obj: Record, what: string): Y.Map function slotToYMap(slot: unknown, what: string): Y.Map | unknown { // A non-record slot is stored as an ITEM of the inputs/outputs Y.Array. if (!isPlainObject(slot)) return cloneForArray(slot, what); + if (Object.hasOwn(slot, DYNAMIC_GROUP_SLOT_KEY)) throw new TypeError(`${what}: reserved DynamicGroup slot marker`); const m = new Y.Map(); for (const [k, v] of Object.entries(slot)) { if (k === "links" && Array.isArray(v)) { @@ -978,7 +981,7 @@ export function createNodeMap(node: WorkflowNode, widgetOrder?: readonly string[ // `project()` from the derived form, so storing it again would be a // second copy of the layout that a later write could contradict. continue; - } else if (k === OPAQUE_WIDGETS_KEY || k === "widgets" || k === NODE_INCARNATION_KEY || k === WIDGET_FORM_KEY) { + } else if (k === OPAQUE_WIDGETS_KEY || k === "widgets" || k === NODE_INCARNATION_KEY || k === WIDGET_FORM_KEY || k === DYNAMIC_GROUP_STATE_KEY) { // Both are DOC-INTERNAL storage keys owned by this module (schema §1.2); // a workflow node carries `widgets_values`, never either of these. An // untrusted payload that sets them directly would shadow the name-keyed diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index f0da13b..e300c13 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -20,11 +20,9 @@ * An entry without `dynamic_combos` or `dynamic_groups` is unchanged, so * the value-blind behaviour (BE-9176 `_extra_N` placeholders) is untouched. */ -import * as Y from "yjs"; - import { assertDynamicGroupCatalog, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js"; -import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; +import { widgetOccurrenceAt, widgetStorageKey, type WidgetValues } from "./widget-identity.js"; type Combos = Record; @@ -131,7 +129,7 @@ export function widgetOrderForValues(entry: WidgetCatalogEntry | undefined, wv: } /** The layout for a document node's name-keyed widgets map: order plus read-time defaults. */ -export function widgetLayoutForWidgets(entry: WidgetCatalogEntry, widgets: Y.Map | undefined): WidgetLayout { +export function widgetLayoutForWidgets(entry: WidgetCatalogEntry, widgets: WidgetValues | undefined): WidgetLayout { const combos = combosOf(entry); if (!hasDynamicWidgetLayout(entry)) return { order: entry.widget_order, defaults: new Map() }; return expand(entry, combos ?? {}, (name, _index, occurrence) => @@ -142,7 +140,7 @@ export function widgetLayoutForWidgets(entry: WidgetCatalogEntry, widgets: Y.Map /** The order for a document node's name-keyed widgets map. */ export function widgetOrderForWidgets( entry: WidgetCatalogEntry, - widgets: Y.Map | undefined, + widgets: WidgetValues | undefined, ): readonly string[] { return widgetLayoutForWidgets(entry, widgets).order; } @@ -151,7 +149,7 @@ export function widgetOrderForWidgets( * The node's projected `widgets_values` length: one past the highest slot * that holds a stored value OR shows a read-time default. */ -export function projectedLength(layout: WidgetLayout, widgets: Y.Map | undefined): number { +export function projectedLength(layout: WidgetLayout, widgets: WidgetValues | undefined): number { let max = -1; layout.order.forEach((name, index) => { if ( diff --git a/src/dynamic-row-ops.ts b/src/dynamic-row-ops.ts new file mode 100644 index 0000000..666b368 --- /dev/null +++ b/src/dynamic-row-ops.ts @@ -0,0 +1,204 @@ +import * as Y from "yjs"; +import { adel, mdel, mset, mapValueRefusal } from "./doc.js"; +import { compareStampKeys, stampKey } from "./stamps.js"; +import { DYNAMIC_GROUP_SLOT_KEY, DYNAMIC_GROUP_STATE_KEY, OpRejectedError, type DynamicGroupRowOp, type StampKey, type WidgetCatalogEntry } from "./types.js"; +import { groupRows, liveRowIds, rowField, storedRowGroup, encodeRowRecord, type DynamicRowGroup, type DynamicRowRecord } from "./dynamic-row-state.js"; +import { widgetIdentityFromStorageKey } from "./widget-identity.js"; + +export function dynamicGroupRowId(opId: string, ordinal: number): string { + if (!/^[0-9a-f]{32}$/.test(opId) || !Number.isSafeInteger(ordinal) || ordinal < 0) throw new TypeError("DynamicGroup: invalid insertion identity"); + return `row:${opId}:${String(ordinal)}`; +} + +function refuse(message: string): never { + throw new OpRejectedError("malformed_op", `DynamicGroup: ${message}`); +} + +function nonempty(value: unknown): value is string { + return typeof value === "string" && value.length > 0; +} + +function valueRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function nodeId(value: unknown): boolean { + return nonempty(value) || (typeof value === "number" && Number.isSafeInteger(value)); +} + +export function validateRowOp(op: DynamicGroupRowOp): void { + if (!nonempty(op.group) || !nonempty(op.node_incarnation) || !/^[0-9a-f]{32}$/.test(op.op_id)) refuse("group, node lifetime and immutable insertion identity are required"); + if (!nodeId(op.node_id)) refuse("node_id is required"); + if (op.path !== undefined && (!Array.isArray(op.path) || op.path.length === 0 || [...op.path].some((part) => !nonempty(part)))) refuse("path must contain container instance IDs"); + if (op.stamp === undefined) refuse("creator stamp is required"); + if (op.op === "dynamic_group_insert_rows") return validateInsertion(op); + if (op.op === "dynamic_group_delete_rows") return validateDeletion(op); + validateRowEditOrLink(op); +} + +function validateValues(value: unknown): void { + if (!valueRecord(value) || Object.keys(value).length === 0) refuse("row values must be a nonempty field object"); + for (const field of Object.values(value)) { + const refusal = mapValueRefusal(structuredClone(field)); + if (refusal) refuse(refusal); + } +} + +function validateInsertion(op: Extract): void { + if (op.after_row_id !== null && !nonempty(op.after_row_id)) refuse("after_row_id must be a row ID or null"); + if (!Array.isArray(op.rows) || op.rows.length === 0) refuse("insertion requires at least one row"); + for (const value of op.rows) validateValues(value); + if (op.rows.some((_row, index) => dynamicGroupRowId(op.op_id, index) === op.after_row_id)) refuse("an insertion cannot anchor to one of its own rows"); +} +function validateDeletion(op: Extract): void { + if (!Array.isArray(op.row_ids) || op.row_ids.length === 0 || [...op.row_ids].some((id) => !nonempty(id)) || new Set(op.row_ids).size !== op.row_ids.length) refuse("deletion requires distinct row IDs"); +} +function validateRowEditOrLink(op: Exclude): void { + if (!nonempty(op.row_id)) refuse("row_id is required"); + if (op.op === "dynamic_group_set_row") validateRowValues(op); + else validateRowConnection(op); +} + +function validateRowValues(op: Extract): void { + validateValues(op.values); + if (op.host_path !== undefined && (!Array.isArray(op.host_path) || op.host_path.length === 0 || [...op.host_path].some((id) => !nonempty(id)) || !nonempty(op.host_incarnation))) refuse("a host path requires its lifetime"); + if (op.host_path === undefined && op.host_incarnation !== undefined) refuse("host lifetime has no host path"); +} +function validateRowConnection(op: Extract): void { + if (!nonempty(op.field)) refuse("field is required"); + if (op.op === "dynamic_group_connect") { + if (!nodeId(op.from_node) || !Number.isSafeInteger(op.from_slot) || op.from_slot < 0 || !nonempty(op.link_type) || !nonempty(op.input_type)) refuse("connection needs a source node, slot and input/link types"); + if (!nodeId(op.link_id)) refuse("link identity is required"); + } +} + +export function rowFieldStamp(owner: string | string[], incarnation: string, group: string, row: string, field: string, kind = "dynamic_group_widget"): string { + return JSON.stringify([kind, owner, incarnation, group, row, field]); +} + +export interface RowMutationPlan { + group: DynamicRowGroup; + writes: Map; + stamps: Map; + outcome: "applied" | "no-op" | "lww-dropped"; +} + +export function prepareRowMutation(node: Y.Map, owner: string | string[], op: DynamicGroupRowOp, entry: WidgetCatalogEntry, stamps: Pick, "get">, digest: string): RowMutationPlan { + const group = groupRows(node, op.group, entry); + const writes = new Map(); + const stampWrites = new Map(); + const key = stampKey(op); + const live = new Set(liveRowIds(group)); + let changed = false; + let visible = false; + function row(id: string): DynamicRowRecord { + const current = writes.get(id) ?? group.records.get(id) ?? { values: {}, slots: {} }; + const next = structuredClone(current); + writes.set(id, next); + return next; + } + function claim(id: string, field: string, kind?: string): boolean { + const target = rowFieldStamp(owner, op.node_incarnation, op.group, id, field, kind); + const prior = stamps.get(target) as StampKey | undefined; + if (prior && compareStampKeys(key, prior) <= 0) return false; + stampWrites.set(target, key); + changed = true; + return true; + } + function known(values: Record, complete: boolean): void { + if (Object.keys(values).some((field) => !group.fields.includes(field)) || (complete && group.fields.some((field) => !Object.hasOwn(values, field)))) refuse("fields must match the group template"); + } + function insertRows(op: Extract): void { + op.rows.forEach((values, index) => { + known(values, true); + const id = dynamicGroupRowId(op.op_id, index); + const next = row(id); + if (next.created !== undefined && next.insert_digest !== digest) throw new OpRejectedError("op_id_reuse", "DynamicGroup: row insertion identity was reused"); + if (next.created === undefined) { + next.after = index === 0 ? op.after_row_id : dynamicGroupRowId(op.op_id, index - 1); + next.created = key; + next.insert_digest = digest; + changed = true; + } + for (const [field, value] of Object.entries(values)) if (claim(id, field)) next.values = { ...next.values, [field]: structuredClone(value) }; + visible ||= !next.deleted; + }); + + } + function setRow(op: Extract): void { + known(op.values, false); + const next = row(op.row_id); + for (const [field, value] of Object.entries(op.values)) if (claim(op.row_id, field)) next.values = { ...next.values, [field]: structuredClone(value) }; + visible = live.has(op.row_id); + + } + function deleteRows(op: Extract): void { + for (const id of op.row_ids) { + const next = row(id); + if (!next.deleted || compareStampKeys(key, next.deleted) > 0) { + next.deleted = key; + claim(id, "", "dynamic_group_delete"); + } + visible ||= live.has(id); + } + + } + function linkRow(op: Extract): void { + if (!group.fields.includes(op.field)) refuse("connection field is not in the group template"); + const next = row(op.row_id); + if (claim(op.row_id, op.field, "dynamic_group_input")) { + const prior = Object.hasOwn(next.slots, op.field) ? next.slots[op.field] : undefined; + if (!prior && op.op === "dynamic_group_disconnect") return; + const slot = prior ?? { original_index: null, data: { type: op.op === "dynamic_group_connect" ? op.input_type : "*", widget: { name: op.field } } }; + if (op.op === "dynamic_group_connect" && slot.data["type"] !== op.input_type) refuse("input type disagrees with the stored row slot"); + slot.data["link"] = op.op === "dynamic_group_connect" ? op.link_id : null; + next.slots = { ...next.slots, [op.field]: slot }; + } + visible = live.has(op.row_id); + + } + if (op.op === "dynamic_group_insert_rows") insertRows(op); + else if (op.op === "dynamic_group_set_row") setRow(op); + else if (op.op === "dynamic_group_delete_rows") deleteRows(op); + else linkRow(op); + let outcome: RowMutationPlan["outcome"] = "lww-dropped"; + if (changed) outcome = visible ? "applied" : "no-op"; + return { group, writes, stamps: stampWrites, outcome }; +} + +export function commitRowMutation(node: Y.Map, groupName: string, plan: RowMutationPlan, stamps: Y.Map): void { + if (plan.outcome === "lww-dropped") return; + let stored = storedRowGroup(node, groupName); + if (!stored) { + const rows = new Y.Map(); + for (const [id, row] of plan.group.records) rows.set(id, encodeRowRecord(row)); + stored = new Y.Map(); + stored.set("fields", [...plan.group.fields]); + stored.set("initial_ids", [...plan.group.initial_ids]); + stored.set("records", rows); + let groups = node.get(DYNAMIC_GROUP_STATE_KEY); + if (!(groups instanceof Y.Map)) { + groups = new Y.Map(); + mset(node, DYNAMIC_GROUP_STATE_KEY, groups); + } + mset(groups as Y.Map, groupName, stored); + replaceInitialRowSlots(node, groupName, plan.group); + } + const rows = stored.get("records") as Y.Map; + for (const [id, row] of plan.writes) mset(rows, id, encodeRowRecord(row)); + for (const [target, key] of plan.stamps) mset(stamps, target, key); +} + +function replaceInitialRowSlots(node: Y.Map, groupName: string, group: DynamicRowGroup): void { + const widgets = node.get("widgets"); + if (widgets instanceof Y.Map) for (const name of [...widgets.keys()]) if (rowField(widgetIdentityFromStorageKey(name).name, groupName, group.fields)) mdel(widgets, name); + const inputs = node.get("inputs"); + if (!(inputs instanceof Y.Array)) return; + for (const [id, row] of group.records) for (const [field, slot] of Object.entries(row.slots)) { + if (slot.original_index === null) continue; + const marker = new Y.Map(); + marker.set(DYNAMIC_GROUP_SLOT_KEY, { group: groupName, row_id: id, field }); + adel(inputs, slot.original_index); + inputs.insert(slot.original_index, [marker]); + } +} diff --git a/src/dynamic-row-state.ts b/src/dynamic-row-state.ts new file mode 100644 index 0000000..2af6e5b --- /dev/null +++ b/src/dynamic-row-state.ts @@ -0,0 +1,310 @@ +import * as Y from "yjs"; +import { dynamicGroupRowsOf } from "./dynamic-group-rows.js"; +import { compareStampKeys, codePointCompare } from "./stamps.js"; +import { DYNAMIC_GROUP_STATE_KEY, DYNAMIC_GROUP_SLOT_KEY, type StampKey, type WidgetCatalogEntry } from "./types.js"; +import { storedWidgetFormOf, type StoredWidgetForm } from "./widget-form.js"; +import { widgetStorageKey, widgetIdentityFromStorageKey, type WidgetValues } from "./widget-identity.js"; + +export interface RowSlot { + original_index: number | null; + data: Record; +} + +/** Only winning values, immutable insertion data and delete-wins state are retained. */ +export interface DynamicRowRecord { + after?: string | null; + created?: StampKey | null; + insert_digest?: string; + deleted?: StampKey; + values: Record; + slots: Record; +} + +interface StoredRowRecord extends Omit { + values: [string, unknown][]; + slots: [string, RowSlot][]; +} + +/** Entry arrays preserve literal field names through lib0 object decoding. */ +export function encodeRowRecord(row: DynamicRowRecord): StoredRowRecord { + const copy = structuredClone(row); + return { ...copy, values: Object.entries(copy.values), slots: Object.entries(copy.slots) }; +} + +export function decodeRowRecord(raw: unknown): DynamicRowRecord { + if (!plainRecord(raw) || !entryArray(raw["values"]) || !entryArray(raw["slots"])) throw new TypeError("DynamicGroup: malformed row record"); + return { ...raw, values: Object.fromEntries(raw["values"]), slots: Object.fromEntries(raw["slots"]) } as DynamicRowRecord; +} + +function entryArray(value: unknown): value is [string, unknown][] { + return Array.isArray(value) && [...value].every((pair) => Array.isArray(pair) && pair.length === 2 && typeof pair[0] === "string") + && new Set(value.map((pair) => (pair as unknown[])[0])).size === value.length; +} + +export interface DynamicRowGroup { + fields: string[]; + initial_ids: string[]; + records: Map; +} + +export interface RowInputMarker { group: string; row_id: string; field: string } + +export function rowSlot(row: DynamicRowRecord | undefined, field: string): RowSlot | undefined { + return row && Object.hasOwn(row.slots, field) ? row.slots[field] : undefined; +} + +export function rowField(name: string, group: string, fields: readonly string[]): { index: number; field: string } | null { + if (!name.startsWith(`${group}.`)) return null; + const suffix = name.slice(group.length + 1); + const dot = suffix.indexOf("."); + const index = suffix.slice(0, dot); + const field = suffix.slice(dot + 1); + return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number.isSafeInteger(Number(index)) && fields.includes(field) + ? { index: Number(index), field } : null; +} + +export function storedRowGroup(node: Y.Map, group: string): Y.Map | null { + const state = node.get(DYNAMIC_GROUP_STATE_KEY); + if (state === undefined) return null; + if (!(state instanceof Y.Map)) throw new TypeError("DynamicGroup: malformed row state"); + const data = state.get(group); + if (data === undefined) return null; + if (!(data instanceof Y.Map)) throw new TypeError(`DynamicGroup ${group}: malformed group state`); + return data; +} + +export function readRowGroup(data: Y.Map): DynamicRowGroup { + const fields = data.get("fields"); + const ids = data.get("initial_ids"); + const records = data.get("records"); + if (!Array.isArray(fields) || fields.length === 0 || [...fields].some((field) => typeof field !== "string" || field.length === 0) || new Set(fields).size !== fields.length || !Array.isArray(ids) + || [...ids].some((id) => typeof id !== "string" || id.length === 0) || new Set(ids).size !== ids.length || !(records instanceof Y.Map)) { + throw new TypeError("DynamicGroup: malformed group storage"); + } + const rows = new Map(); + records.forEach((raw, id) => { + const row = decodeRowRecord(raw); + if (!plainRecord(row.values) || !plainRecord(row.slots) || Object.keys(row.values).some((field) => !fields.includes(field))) { + throw new TypeError("DynamicGroup: malformed row values or slots"); + } + if ((row.after !== undefined && row.after !== null && typeof row.after !== "string") || (row.created !== undefined && row.created !== null && !validStamp(row.created)) || (row.deleted !== undefined && !validStamp(row.deleted))) throw new TypeError("DynamicGroup: malformed row ordering state"); + for (const [field, slot] of Object.entries(row.slots)) { + if (!fields.includes(field) || !plainRecord(slot) || !plainRecord(slot.data) || (slot.original_index !== null && (!Number.isSafeInteger(slot.original_index) || slot.original_index < 0))) throw new TypeError("DynamicGroup: malformed row slot"); + } + rows.set(id, row); + }); + return { fields: fields as string[], initial_ids: ids as string[], records: rows }; +} + +function plainRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function validStamp(value: unknown): value is StampKey { + return Array.isArray(value) && value.length === 3 && Number.isSafeInteger(value[0]) && typeof value[1] === "string" && typeof value[2] === "string"; +} + +export function initialRowGroup(node: Y.Map, group: string, fields: readonly string[]): DynamicRowGroup { + const ids = dynamicGroupRowsOf(node.get("properties"))?.[group]; + if (!ids) throw new TypeError(`DynamicGroup ${group}: producer-owned row IDs are required`); + const widgets = node.get("widgets"); + if (!(widgets instanceof Y.Map)) throw new TypeError(`DynamicGroup ${group}: named widget storage is required`); + const records = new Map(); + ids.forEach((id, index) => { + const values: Record = Object.create(null) as Record; + for (const field of fields) { + const key = widgetStorageKey(`${group}.${String(index)}.${field}`); + if (widgets.has(key)) values[field] = structuredClone(widgets.get(key)); + } + records.set(id, { after: index === 0 ? null : ids[index - 1]!, created: null, values, slots: {} }); + }); + const inputs = node.get("inputs"); + if (inputs instanceof Y.Array) inputs.forEach((slot, index) => { + if (!(slot instanceof Y.Map) || typeof slot.get("name") !== "string") return; + const parsed = rowField(slot.get("name") as string, group, fields); + if (!parsed) return; + const id = ids[parsed.index]; + if (id === undefined) throw new TypeError(`DynamicGroup ${group}: input has no row ID`); + const row = records.get(id)!; + if (Object.hasOwn(row.slots, parsed.field)) throw new TypeError(`DynamicGroup ${group}: duplicate row input`); + row.slots = { ...row.slots, [parsed.field]: { original_index: index, data: structuredClone(slot.toJSON()) as Record } }; + }); + return { fields: [...fields], initial_ids: [...ids], records }; +} + +export function groupRows(node: Y.Map, group: string, entry: WidgetCatalogEntry): DynamicRowGroup { + const metadata = entry.dynamic_groups?.[group]; + if (!metadata) throw new TypeError(`DynamicGroup ${group}: group metadata is required`); + const stored = storedRowGroup(node, group); + if (!stored) return initialRowGroup(node, group, metadata.widgets); + const data = readRowGroup(stored); + if (JSON.stringify(data.fields) !== JSON.stringify(metadata.widgets)) throw new TypeError(`DynamicGroup ${group}: catalog fields changed`); + return data; +} + +export function liveRowIds(group: DynamicRowGroup): string[] { + assertAcyclicAnchors(group); + const children = new Map(); + for (const [id, row] of group.records) { + if (row.created === undefined || row.after === undefined) continue; + const siblings = children.get(row.after) ?? []; + siblings.push(id); + children.set(row.after, siblings); + } + for (const siblings of children.values()) siblings.sort((a, b) => { + const left = group.records.get(a)!.created; + const right = group.records.get(b)!.created; + if (left === null && right !== null) return 1; + if (left !== null && right === null) return -1; + return left && right ? compareStampKeys(right, left) || codePointCompare(a, b) : codePointCompare(a, b); + }); + const stack = [...(children.get(null) ?? [])].reverse(); + const visited = new Set(); + const live: string[] = []; + while (stack.length > 0) { + const id = stack.pop()!; + if (visited.has(id)) throw new TypeError("DynamicGroup: cyclic row anchors"); + visited.add(id); + const row = group.records.get(id)!; + if (!row.deleted) live.push(id); + stack.push(...[...(children.get(id) ?? [])].reverse()); + } + return live; +} + +function assertAcyclicAnchors(group: DynamicRowGroup): void { + const complete = new Set(); + for (const id of group.records.keys()) { + const path = new Set(); + let current: string | null | undefined = id; + while (current != null && !complete.has(current)) { + if (path.has(current)) throw new TypeError("DynamicGroup: cyclic row anchors"); + const row = group.records.get(current); + if (!row || row.created === undefined) break; + path.add(current); + current = row.after; + } + for (const visited of path) complete.add(visited); + } +} + +export function activeRowGroups(node: Y.Map): Map { + const result = new Map(); + const state = node.get(DYNAMIC_GROUP_STATE_KEY); + if (state === undefined) return result; + if (!(state instanceof Y.Map)) throw new TypeError("DynamicGroup: malformed row state"); + state.forEach((data, group) => { + if (!(data instanceof Y.Map)) throw new TypeError("DynamicGroup: malformed group state"); + result.set(group, readRowGroup(data)); + }); + return result; +} + +export function currentRowIds(node: Y.Map): Record | null { + const baseline = dynamicGroupRowsOf(node.get("properties")); + if (!baseline) return null; + const rows = { ...baseline }; + for (const [name, group] of activeRowGroups(node)) rows[name] = liveRowIds(group); + return rows; +} + +export function rowWidgetValues(node: Y.Map): WidgetValues { + const widgets = node.get("widgets"); + if (!node.has(DYNAMIC_GROUP_STATE_KEY) && widgets instanceof Y.Map) return widgets; + const result = new Map(); + if (widgets instanceof Y.Map) widgets.forEach((value, key) => result.set(key, value)); + for (const [name, group] of activeRowGroups(node)) { + for (const key of result.keys()) if (rowField(widgetIdentityFromStorageKey(key).name, name, group.fields)) result.delete(key); + const ids = liveRowIds(group); + result.set(widgetStorageKey(name), ids.length); + ids.forEach((id, index) => { + const row = group.records.get(id)!; + for (const [field, value] of Object.entries(row.values)) result.set(widgetStorageKey(`${name}.${String(index)}.${field}`), value); + }); + } + return result; +} + +export function rowWidgetForm(node: Y.Map): StoredWidgetForm | null { + const source = storedWidgetFormOf(node); + if (!source) return null; + const groups = activeRowGroups(node); + if (groups.size === 0) return source; + const form = structuredClone(source); + for (const [name, group] of groups) { + const ids = liveRowIds(group); + if (JSON.stringify(ids) === JSON.stringify(group.initial_ids)) continue; + const order: string[] = []; + for (const field of form.order) { + if (rowField(field, name, group.fields)) continue; + order.push(field); + if (field === name) ids.forEach((_id, index) => group.fields.forEach((child) => order.push(`${name}.${String(index)}.${child}`))); + } + if (form.keys) { + const retained = form.keys.filter((key) => !rowField(key, name, group.fields)); + const at = retained.indexOf(name); + retained.splice(at + 1, 0, ...order.filter((key) => rowField(key, name, group.fields))); + form.keys = retained; + } + form.order = order; + } + return form; +} + +export interface RowInputProjection { + inputs: unknown[]; + indices: Map; + rows: Map; + renames: Map; +} + +export function rowEndpointKey(group: string, row: string, field: string): string { + return JSON.stringify([group, row, field]); +} + +export function rowInputProjection(node: Y.Map): RowInputProjection { + const source = node.get("inputs"); + const raw = source instanceof Y.Array ? source.toArray() : []; + const groups = activeRowGroups(node); + const positions = new Map>(); + const renames = new Map(); + for (const [name, group] of groups) { + const ids = liveRowIds(group); + positions.set(name, new Map(ids.map((id, index) => [id, index]))); + group.initial_ids.forEach((id, index) => group.fields.forEach((field) => { + const current = positions.get(name)!.get(id); + renames.set(`${name}.${String(index)}.${field}`, current === undefined ? null : `${name}.${String(current)}.${field}`); + })); + } + const inputs: unknown[] = []; + const indices = new Map(); + const rows = new Map(); + function append(marker: RowInputMarker, slot: RowSlot): void { + const index = positions.get(marker.group)?.get(marker.row_id); + if (index === undefined) return; + const name = `${marker.group}.${String(index)}.${marker.field}`; + const data = structuredClone(slot.data); + data["name"] = name; + if (typeof data["widget"] === "object" && data["widget"] !== null) data["widget"] = { ...data["widget"] as object, name }; + rows.set(rowEndpointKey(marker.group, marker.row_id, marker.field), inputs.length); + if (slot.original_index !== null) indices.set(slot.original_index, inputs.length); + inputs.push(data); + } + raw.forEach((slot, index) => { + const value = slot instanceof Y.Map ? slot.toJSON() as Record : slot; + const marker = typeof value === "object" && value !== null ? (value as Record)[DYNAMIC_GROUP_SLOT_KEY] as RowInputMarker | undefined : undefined; + if (marker) { + const data = rowSlot(groups.get(marker.group)?.records.get(marker.row_id), marker.field); + if (!data) throw new TypeError("DynamicGroup: input marker has no row slot"); + append(marker, data); + } else { + indices.set(index, inputs.length); + inputs.push(structuredClone(value)); + } + }); + for (const [name, group] of groups) for (const id of liveRowIds(group)) for (const field of group.fields) { + const slot = rowSlot(group.records.get(id), field); + if (slot?.original_index === null) append({ group: name, row_id: id, field }, slot); + } + return { inputs, indices, rows, renames }; +} diff --git a/src/dynamic-row-topology.ts b/src/dynamic-row-topology.ts new file mode 100644 index 0000000..02c2f1d --- /dev/null +++ b/src/dynamic-row-topology.ts @@ -0,0 +1,472 @@ +import * as Y from "yjs"; +import { OPAQUE_WIDGETS_KEY, ROOT_DEFINITIONS, ROOT_LINK_STATE, ROOT_NODES, nodeIncarnation } from "./doc.js"; +import { DYNAMIC_GROUP_SLOT_KEY, DYNAMIC_GROUP_STATE_KEY, type WorkflowJSON, type WorkflowNode } from "./types.js"; +import { activeRowGroups, rowInputProjection, rowSlot, type RowInputProjection, type RowInputMarker } from "./dynamic-row-state.js"; +import { dynamicGroupRowsOf } from "./dynamic-group-rows.js"; + +interface InputChange { name: string; widget?: string | null; index: number | null } +export interface DefinitionRowView { + original: Record[]; + changes: InputChange[]; + widget_indices: number[]; + proxy_names: Map; +} + +interface LinkFields { id: unknown; from: unknown; fromSlot: number; to: unknown; toSlot: number } + +function record(value: unknown): Record | null { + return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record : null; +} + +function linkFields(value: unknown): LinkFields | null { + if (Array.isArray(value)) return { id: value[0], from: value[1], fromSlot: value[2] as number, to: value[3], toSlot: value[4] as number }; + const data = record(value); + return data ? { id: data["id"], from: data["origin_id"], fromSlot: data["origin_slot"] as number, to: data["target_id"], toSlot: data["target_slot"] as number } : null; +} + +function updateLink(value: unknown, fromSlot: number, toSlot: number): unknown { + if (Array.isArray(value)) { + const result = [...value]; result[2] = fromSlot; result[4] = toSlot; return result; + } + return { ...record(value), origin_slot: fromSlot, target_slot: toSlot }; +} + +function root(doc: Y.Doc, key: string): Y.Map | undefined { + return doc.share.has(key) ? doc.getMap(key) : undefined; +} + +function rawInputs(node: Y.Map): unknown[] { + const inputs = node.get("inputs"); + return inputs instanceof Y.Array ? inputs.toArray().map((slot) => { + const data = slot instanceof Y.Map ? slot.toJSON() as Record : slot; + const marker = record(data)?.[DYNAMIC_GROUP_SLOT_KEY] as RowInputMarker | undefined; + if (!marker) return data; + return rowSlot(activeRowGroups(node).get(marker.group)?.records.get(marker.row_id), marker.field)?.data; + }) : []; +} + +function allDefinitions(doc: Y.Doc): Map> { + const definitions = new Map>(); + function visit(value: unknown): void { + if (!(value instanceof Y.Map)) return; + const id = String(value.get("id")); + if (definitions.has(id)) return; + definitions.set(id, value); + const nested = value.get("definitions"); + const children = nested instanceof Y.Map ? nested.get("subgraphs") : undefined; + if (children instanceof Y.Map) children.forEach(visit); + } + root(doc, ROOT_DEFINITIONS)?.forEach(visit); + return definitions; +} + +function projectedDefinitions(workflow: WorkflowJSON): Map> { + const result = new Map>(); + function visit(value: unknown): void { + const definition = record(value); + if (!definition) return; + result.set(String(definition["id"]), definition); + const children = record(definition["definitions"])?.["subgraphs"]; + if (Array.isArray(children)) children.forEach(visit); + } + workflow.definitions?.subgraphs?.forEach(visit); + return result; +} + +function matchingInput(input: Record, view: DefinitionRowView): number { + const byId = input["id"] === undefined ? -1 : view.original.findIndex((slot) => slot["id"] === input["id"]); + if (byId >= 0) return byId; + const matches = view.original.map((slot, index) => slot["name"] === input["name"] ? index : -1).filter((index) => index >= 0); + if (matches.length > 1) throw new TypeError("DynamicGroup: ambiguous promoted input name"); + return matches[0] ?? -1; +} + +function hostWidgetValues(node: WorkflowNode, view: DefinitionRowView): void { + if (!Array.isArray(node.widgets_values) || node.widgets_values.length === 0) return; + const proxies = record(node["properties"])?.["proxyWidgets"]; + if (Array.isArray(proxies) && proxies.length === node.widgets_values.length) { + node.widgets_values = node.widgets_values.filter((_value, index) => { + const pair = proxies[index] as unknown; + return !Array.isArray(pair) || view.proxy_names.get(JSON.stringify(pair.map(String))) !== null; + }); + return; + } + const order = node.widgets_values.length === view.original.length ? view.original.map((_slot, index) => index) : view.widget_indices; + node.widgets_values = node.widgets_values.filter((_value, index) => { + const slot = order[index]; + return slot === undefined || view.changes[slot]?.index !== null; + }); +} + +/** Project row-aware topology from stable addresses without changing stored indices. */ +export function projectRowTopology(doc: Y.Doc, workflow: WorkflowJSON): WorkflowJSON { + const defs = allDefinitions(doc); + const sources = [root(doc, ROOT_NODES), ...[...defs.values()].map((definition) => definition.get("nodes"))]; + if (!sources.some((nodes) => nodes instanceof Y.Map && [...nodes.values()].some((node) => node instanceof Y.Map && node.has(DYNAMIC_GROUP_STATE_KEY)))) return workflow; + const projected = projectedDefinitions(workflow); + const views = new Map(); + const visiting = new Set(); + + function definitionFor(type: unknown): Y.Map | undefined { + const direct = defs.get(String(type)); + if (direct) return direct; + const byName = [...defs.values()].filter((definition) => definition.get("name") === type); + return byName.length === 1 ? byName[0] : undefined; + } + + function processDefinition(definition: Y.Map): DefinitionRowView { + const id = String(definition.get("id")); + const cached = views.get(id); + if (cached) return cached; + const raw = definition.get("inputs"); + const original = Array.isArray(raw) ? raw.map((slot) => record(slot) ?? {}) : []; + const empty: DefinitionRowView = { original, changes: original.map((slot, index) => ({ name: String(slot["name"] ?? ""), index })), widget_indices: [], proxy_names: new Map() }; + if (visiting.has(id)) return empty; + visiting.add(id); + const output = projected.get(id); + if (!output) { views.set(id, empty); visiting.delete(id); return empty; } + const sourceNodes = definition.get("nodes") as Y.Map>; + const sourceLinks = definition.get("links") as Y.Map; + const nodeViews = processNodes(sourceNodes, output["nodes"] as WorkflowNode[] ?? []); + const inputNode = record(definition.get("inputNode")); + const boundary = inputNode?.["id"] ?? -10; + const oldLinks = [...sourceLinks.values()]; + const affected = new Set(); + const oldWidgetNames = new Map(); + for (const value of oldLinks) { + const link = linkFields(value); + if (!link || String(link.from) !== String(boundary)) continue; + const target = sourceNodes.get(String(link.to)); + const input = target ? record(rawInputs(target)[link.toSlot]) : null; + const widget = record(input?.["widget"]); + if (typeof widget?.["name"] === "string") oldWidgetNames.set(link.fromSlot, widget["name"]); + } + const first = rewriteLinks(output["links"] as unknown[] ?? [], nodeViews, affected, sourceNodes, definition.get(ROOT_LINK_STATE) as Y.Map | undefined); + const dropped = new Set(oldLinks.filter((value) => { + const id = linkFields(value)?.id; + return String(linkFields(value)?.from) === String(boundary) && !first.some((candidate) => String(linkFields(candidate)?.id) === String(id)); + }).map((value) => linkFields(value)!.fromSlot)); + const hasBacking = new Set(first.filter((value) => String(linkFields(value)?.from) === String(boundary)).map((value) => linkFields(value)!.fromSlot)); + const changes: InputChange[] = []; + const nextInputs: Record[] = []; + original.forEach((slot, index) => { + const name = String(slot["name"] ?? ""); + if (dropped.has(index) && !hasBacking.has(index)) { + changes.push({ name, index: null, widget: null }); + return; + } + let widget: string | undefined; + for (const value of oldLinks) { + const link = linkFields(value); + if (!link || String(link.from) !== String(boundary) || link.fromSlot !== index) continue; + const before = oldWidgetNames.get(index); + const view = nodeViews.get(String(link.to)); + if (before && view?.renames.has(before)) widget = view.renames.get(before) ?? undefined; + } + const renamed = widget && name === oldWidgetNames.get(index) ? widget : name; + const links = first.filter((value) => { const link = linkFields(value); return link && String(link.from) === String(boundary) && link.fromSlot === index; }); + const next = structuredClone(slot); + next["name"] = renamed; + if (Array.isArray(slot["linkIds"])) next["linkIds"] = links.map((value) => linkFields(value)!.id); + changes.push({ name: renamed, index: nextInputs.length, ...(widget ? { widget } : {}) }); + nextInputs.push(next); + }); + const finalLinks = first.flatMap((value) => { + const link = linkFields(value)!; + if (String(link.from) !== String(boundary)) return [value]; + const index = changes[link.fromSlot]?.index; + if (index === null) { affected.add(String(link.id)); return []; } + return [updateLink(value, index ?? link.fromSlot, link.toSlot)]; + }); + if (Array.isArray(output["inputs"])) output["inputs"] = nextInputs; + output["links"] = finalLinks; + transformExposures(output, nodeViews); + synchronizeRefs(output["nodes"] as WorkflowNode[] ?? [], finalLinks, affected, nodeViews); + const proxyNames = new Map(); + for (const [nodeId, view] of nodeViews) for (const [name, next] of view.renames) proxyNames.set(JSON.stringify([nodeId, name]), next); + const view = { original, changes, widget_indices: [...oldWidgetNames.keys()].sort((a, b) => a - b), proxy_names: proxyNames }; + views.set(id, view); + visiting.delete(id); + return view; + } + + function processNodes(source: Y.Map>, nodes: WorkflowNode[]): Map { + const result = new Map(); + for (const output of nodes) { + const input = source.get(String(output.id)); + if (!input) continue; + const base = rowInputProjection(input); + const definition = definitionFor(input.get("type")); + if (definition) { + const child = processDefinition(definition); + const raw = rawInputs(input); + const next: unknown[] = []; + const indices = new Map(); + raw.forEach((value, index) => { + const slot = record(value); + if (!slot) { indices.set(index, next.length); next.push(value); return; } + const oldIndex = matchingInput(slot, child); + const change = child.changes[oldIndex]; + if (change?.index === null) { + const oldWidget = record(slot["widget"])?.["name"]; + if (typeof oldWidget === "string") base.renames.set(oldWidget, null); + return; + } + const updated = structuredClone(slot); + if (change) { + updated["name"] = change.name; + if (change.widget && record(updated["widget"])) updated["widget"] = { ...record(updated["widget"]), name: change.widget }; + const oldWidget = record(slot["widget"])?.["name"]; + if (typeof oldWidget === "string" && change.widget) base.renames.set(oldWidget, change.widget); + } + indices.set(index, next.length); + next.push(updated); + }); + base.inputs = next; + base.indices = indices; + hostWidgetValues(output, child); + const properties = record(output["properties"]); + if (Array.isArray(properties?.["proxyWidgets"])) properties["proxyWidgets"] = (properties["proxyWidgets"] as unknown[]).flatMap((pair) => { + if (!Array.isArray(pair)) return [pair]; + const key = JSON.stringify(pair.map(String)); + if (!child.proxy_names.has(key)) return [pair]; + const name = child.proxy_names.get(key); + return name === null ? [] : [[pair[0], name]]; + }); + } + if (output.inputs !== undefined) output.inputs = base.inputs; + result.set(String(output.id), base); + } + for (const output of nodes) { + const properties = record(output["properties"]); + if (!properties || !Array.isArray(properties["proxyWidgets"])) continue; + properties["proxyWidgets"] = (properties["proxyWidgets"] as unknown[]).flatMap((pair) => { + if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[1] !== "string") return [pair]; + const names = result.get(String(pair[0]))?.renames; + if (!names?.has(pair[1])) return [pair]; + const name = names.get(pair[1]); + return name === null ? [] : [[pair[0], name]]; + }); + } + return result; + } + + function transformExposures(graph: Record, nodes: Map): void { + if (!Array.isArray(graph["widgets"])) return; + graph["widgets"] = (graph["widgets"] as unknown[]).flatMap((value) => { + const exposed = record(value); + if (!exposed || typeof exposed["name"] !== "string") return [value]; + const names = nodes.get(String(exposed["id"]))?.renames; + if (!names?.has(exposed["name"])) return [value]; + const name = names.get(exposed["name"]); + return name === null ? [] : [{ ...exposed, name }]; + }); + } + + function rewriteLinks(links: unknown[], nodes: Map, affected: Set, source: Y.Map>, states?: Y.Map): unknown[] { + return links.flatMap((value) => { + const link = linkFields(value); + if (!link) return [value]; + const view = nodes.get(String(link.to)); + if (!view) return [value]; + const state = record(states?.get(String(link.id))); + const destination = record(state?.["destination"]); + const row = destination?.["kind"] === "dynamic_group"; + const target = source.get(String(link.to)); + if (row && target && nodeIncarnation(target) !== destination["node_incarnation"]) { affected.add(String(link.id)); return []; } + const index = row ? view.rows.get(JSON.stringify([destination["group"], destination["row_id"], destination["field"]])) : view.indices.get(link.toSlot); + const original = source.get(String(link.to)); + const originalCount = original ? rawInputs(original).length : 0; + if (index === undefined && !row && (link.toSlot >= originalCount || link.toSlot < 0)) return [value]; + if (index === undefined) { affected.add(String(link.id)); return []; } + return [updateLink(value, link.fromSlot, index)]; + }); + } + + function synchronizeRefs(nodes: WorkflowNode[], links: unknown[], affected: Set, views: Map): void { + const live = new Set(links.map((value) => String(linkFields(value)?.id))); + for (const node of nodes) { + synchronizeInputs(node, links, live, affected, views.get(String(node.id))); + synchronizeOutputs(node, live, affected); + } + } + function synchronizeInputs(node: WorkflowNode, links: unknown[], live: Set, affected: Set, view?: RowInputProjection): void { + if (!Array.isArray(node.inputs)) return; + for (const value of node.inputs) { + const slot = record(value); + if (slot && affected.has(String(slot["link"])) && !live.has(String(slot["link"]))) slot["link"] = null; + } + for (const index of view?.rows.values() ?? []) { + const slot = record(node.inputs[index]); + const occupant = links.map(linkFields).find((link) => link && String(link.to) === String(node.id) && link.toSlot === index); + if (slot) slot["link"] = occupant?.id ?? null; + } + } + function synchronizeOutputs(node: WorkflowNode, live: Set, affected: Set): void { + if (!Array.isArray(node.outputs)) return; + for (const value of node.outputs) { + const slot = record(value); + if (Array.isArray(slot?.["links"])) slot["links"] = (slot["links"] as unknown[]).filter((id) => !affected.has(String(id)) || live.has(String(id))); + } + } + + const nodes = root(doc, ROOT_NODES) as Y.Map> | undefined; + if (nodes) { + const nodeViews = processNodes(nodes, workflow.nodes); + const affected = new Set(); + workflow.links = rewriteLinks(workflow.links, nodeViews, affected, nodes, root(doc, ROOT_LINK_STATE)); + synchronizeRefs(workflow.nodes, workflow.links, affected, nodeViews); + } + for (const definition of defs.values()) processDefinition(definition); + return workflow; +} + +/** Minimal topology source for the catalog-free follower snapshot. */ +export function rowTopologySnapshot(doc: Y.Doc): WorkflowJSON | null { + if (![...doc.store.clients.values()].some((structs) => structs.length > 0)) return null; + const definitions = allDefinitions(doc); + const graphs = [root(doc, ROOT_NODES), ...[...definitions.values()].map((definition) => definition.get("nodes"))]; + if (!graphs.some((nodes) => nodes instanceof Y.Map && [...nodes.values()].some((node) => node instanceof Y.Map && node.has(DYNAMIC_GROUP_STATE_KEY)))) return null; + function nodeData(node: Y.Map, id: string): WorkflowNode { + const data: WorkflowNode = { id, type: String(node.get("type")) }; + for (const key of ["inputs", "outputs"]) { + const values = node.get(key); + if (values instanceof Y.Array) data[key] = values.toArray().map((value) => value instanceof Y.Map ? structuredClone(value.toJSON()) : structuredClone(value)); + } + if (node.has("properties")) data["properties"] = structuredClone(node.get("properties")); + if (node.has(OPAQUE_WIDGETS_KEY)) data.widgets_values = structuredClone(node.get(OPAQUE_WIDGETS_KEY)) as unknown[]; + return data; + } + function graphData(nodes: unknown, links: unknown): WorkflowJSON { + const result: WorkflowJSON = { nodes: [], links: [] }; + if (nodes instanceof Y.Map) nodes.forEach((node, id) => { if (node instanceof Y.Map) result.nodes.push(nodeData(node, id)); }); + if (links instanceof Y.Map) result.links = [...links.values()].map((link) => structuredClone(link)); + return result; + } + const result = graphData(root(doc, ROOT_NODES), root(doc, "links")); + result.definitions = { subgraphs: [...definitions.values()].map((definition) => { + const graph = graphData(definition.get("nodes"), definition.get("links")); + return { ...graph, id: definition.get("id"), inputNode: structuredClone(definition.get("inputNode")), inputs: structuredClone(definition.get("inputs")), widgets: structuredClone(definition.get("widgets")) }; + }) }; + return projectRowTopology(doc, result); +} + +/** Baseline host inputs whose backing address depends on a DynamicGroup row. */ +export function rowControlledHostInputs(doc: Y.Doc, host: Y.Map): number[] { + const definitions = allDefinitions(doc); + const visiting = new Set>(); + function controlled(node: Y.Map, index: number): boolean { + const inputs = node.get("inputs"); + const raw = inputs instanceof Y.Array ? inputs.get(index) : undefined; + const slot = raw instanceof Y.Map ? raw.toJSON() as Record : record(raw); + if (slot?.[DYNAMIC_GROUP_SLOT_KEY]) return true; + const name = record(slot?.["widget"])?.["name"]; + const rows = dynamicGroupRowsOf(node.get("properties")); + if (rows && typeof name === "string" && Object.keys(rows).some((group) => name.startsWith(`${group}.`) && /^(0|[1-9]\d*)\./.test(name.slice(group.length + 1)))) return true; + const child = definitions.get(String(node.get("type"))); + const declared = child?.get("inputs"); + if (!child || !Array.isArray(declared)) return false; + return declared.some((input, ordinal) => record(input)?.["name"] === slot?.["name"] && fromDefinition(child, ordinal)); + } + function fromDefinition(definition: Y.Map, index: number): boolean { + if (visiting.has(definition)) return false; + visiting.add(definition); + try { + const nodes = definition.get("nodes"); + const links = definition.get("links"); + const boundary = record(definition.get("inputNode"))?.["id"] ?? -10; + if (!(nodes instanceof Y.Map) || !(links instanceof Y.Map)) return false; + return [...links.values()].some((value) => { + const link = linkFields(value); + const node = link ? nodes.get(String(link.to)) : undefined; + return link && String(link.from) === String(boundary) && link.fromSlot === index && node instanceof Y.Map && controlled(node, link.toSlot); + }); + } finally { visiting.delete(definition); } + } + const definition = definitions.get(String(host.get("type"))); + const inputs = definition?.get("inputs"); + return definition && Array.isArray(inputs) ? inputs.map((_input, index) => index).filter((index) => fromDefinition(definition, index)) : []; +} + +/** Resolve a promoted field to its immutable baseline host-value position. */ +export function promotedRowValueIndex(doc: Y.Doc, host: Y.Map, target: Y.Map, group: string, rowId: string, field: string): number | null { + const definitions = allDefinitions(doc); + const visiting = new Set>(); + function matches(node: Y.Map, inputIndex: number): boolean { + if (node === target) { + const source = node.get("inputs"); + const slot = source instanceof Y.Array ? source.get(inputIndex) : undefined; + const data = slot instanceof Y.Map ? slot.toJSON() as Record : record(slot); + const marker = data?.[DYNAMIC_GROUP_SLOT_KEY] as RowInputMarker | undefined; + if (marker) return marker.group === group && marker.row_id === rowId && marker.field === field; + const ids = record(node.get("properties"))?.["dynamicGroupRows"]; + const list = record(ids)?.[group]; + const index = Array.isArray(list) ? list.indexOf(rowId) : -1; + return index >= 0 && record(data?.["widget"])?.["name"] === `${group}.${String(index)}.${field}`; + } + const definition = definitions.get(String(node.get("type"))); + if (!definition || visiting.has(definition)) return false; + const inputs = rawInputs(node); + const name = record(inputs[inputIndex])?.["name"]; + const declared = definition.get("inputs"); + const indices = Array.isArray(declared) ? declared.map((value, index) => record(value)?.["name"] === name ? index : -1).filter((index) => index >= 0) : []; + return indices.some((index) => fromDefinition(definition, index)); + } + function fromDefinition(definition: Y.Map, index: number): boolean { + visiting.add(definition); + try { + const nodes = definition.get("nodes"); + const links = definition.get("links"); + if (!(nodes instanceof Y.Map) || !(links instanceof Y.Map)) return false; + const boundary = record(definition.get("inputNode"))?.["id"] ?? -10; + return [...links.values()].some((value) => { + const link = linkFields(value); + const child = link ? nodes.get(String(link.to)) : undefined; + return link && String(link.from) === String(boundary) && link.fromSlot === index && child instanceof Y.Map && matches(child, link.toSlot); + }); + } finally { visiting.delete(definition); } + } + const definition = definitions.get(String(host.get("type"))); + const declared = definition?.get("inputs"); + if (!definition || !Array.isArray(declared)) return null; + const proxies = record(host.get("properties"))?.["proxyWidgets"]; + const values = host.get(OPAQUE_WIDGETS_KEY); + if (Array.isArray(proxies) && Array.isArray(values) && proxies.length === values.length) { + return promotedProxyIndex(definition, proxies, matches); + } + const indices = declared.map((_input, index) => index).filter((index) => fromDefinition(definition, index)); + if (indices.length > 1) throw new TypeError("DynamicGroup: promoted row field has ambiguous host bindings"); + const index = indices[0]; + if (index === undefined) return null; + if (Array.isArray(values) && values.length === declared.length) return index; + const rank = widgetBackedPortIndices(definition).indexOf(index); + return rank < 0 ? null : rank; +} + +function widgetBackedPortIndices(definition: Y.Map): number[] { + const nodes = definition.get("nodes"); + const links = definition.get("links"); + if (!(nodes instanceof Y.Map) || !(links instanceof Y.Map)) return []; + const boundary = record(definition.get("inputNode"))?.["id"] ?? -10; + const backed = new Set(); + for (const value of links.values()) { + const link = linkFields(value); + const child = link ? nodes.get(String(link.to)) : undefined; + if (!link || String(link.from) !== String(boundary) || !(child instanceof Y.Map)) continue; + const input = record(rawInputs(child)[link.toSlot]); + if (record(input?.["widget"])) backed.add(link.fromSlot); + } + return [...backed].sort((a, b) => a - b); +} + +function promotedProxyIndex(definition: Y.Map, proxies: unknown[], matches: (node: Y.Map, index: number) => boolean): number | null { + const nodes = definition.get("nodes"); + if (!(nodes instanceof Y.Map)) return null; + const bound = proxies.map((pair, ordinal) => { + if (!Array.isArray(pair)) return -1; + const child = nodes.get(String(pair[0])); + if (!(child instanceof Y.Map)) return -1; + return rawInputs(child).some((input, index) => record(input)?.["name"] === pair[1] && matches(child, index)) ? ordinal : -1; + }).filter((index) => index >= 0); + return bound.length === 1 ? bound[0]! : null; +} diff --git a/src/index.ts b/src/index.ts index 1b09138..e97fd31 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,8 +2,9 @@ * @comfyorg/comfy-multi-player — shared workflow-document package. * * One implementation of op→doc semantics, used identically by the browser - * and the server doc host. The public vocabulary declares nine operation - * kinds: eight implemented kinds plus the deferred `reset_doc` kind. The + * and the server doc host. The surface declares fourteen implemented operation + * kinds plus the deferred `reset_doc` kind, including the provisional A27 + * row contract. The * normative contract is comfy-cli's `docs/op-vocabulary-v1.md` and the stamp * shapes minted by `comfy_cli/workflow_ops.py` (`_new_op`), both pinned at * comfy-cli commit `7e732242d971daf0d2d30f22f997abfacd78986e` — by SHA and @@ -20,7 +21,7 @@ * - `compact(doc, catalog)` — fresh-checkpoint re-mint (schema §4 rule 2): * a new-lineage Y.Doc with the same projection, live stamps, incarnations, * link state and clock reservations but an empty `__applied` ledger and no - * tombstone history; the host owns the replica cutover; + * old Yjs struct history; semantic row tombstones remain. The host owns cutover; * - `applyOps(doc, ops, catalog?)` — idempotent, LWW-gated, abort-remainder * op application (schema §2–§4); * - `inspectOps(ops)` — pure validation and canonical bytes/digest/stamp @@ -95,6 +96,8 @@ export { type WidgetValuesForm, } from "./widget-form.js"; export { applyOps, inspectOps } from "./applier.js"; +export { admitDynamicGroupRowOp } from "./applier.js"; +export { dynamicGroupRowId } from "./dynamic-row-ops.js"; export { project } from "./project.js"; export { mint } from "./mint.js"; export { compact } from "./compact.js"; diff --git a/src/project.ts b/src/project.ts index c2184a5..7aa3970 100644 --- a/src/project.ts +++ b/src/project.ts @@ -49,16 +49,19 @@ 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 { assertDynamicGroupRowCatalog, assertDynamicGroupRowCounts } from "./dynamic-group-rows.js"; import { hasDynamicWidgetLayout, optionOwnedWidgets, projectedLength, widgetLayoutForWidgets } from "./dynamic-combos.js"; import { widgetIdentityFromStorageKey, widgetOccurrenceAt, widgetStorageKey, widgetIndexOf } from "./widget-identity.js"; import { WIDGET_FORM_FIELD, WIDGET_FORM_KEY, projectWidgetForm, - storedWidgetFormOf, } from "./widget-form.js"; import { numericId } from "./remap.js"; +import { activeRowGroups, currentRowIds, rowInputProjection, rowWidgetForm, rowWidgetValues, rowField, liveRowIds } from "./dynamic-row-state.js"; +import { DYNAMIC_GROUP_STATE_KEY } from "./types.js"; +import type { WidgetValues } from "./widget-identity.js"; +import { projectRowTopology } from "./dynamic-row-topology.js"; /** Sorted-by-id comparator: numeric when both ids are numbers, else string order. */ function idCompare(a: unknown, b: unknown): number { @@ -130,7 +133,7 @@ function positionalIndexOf(order: readonly string[], name: string): number { /** Identity-keyed widgets map → positional widgets_values (§7 rule 2). */ function widgetsToPositional( nodeType: string, - widgets: Y.Map, + widgets: WidgetValues, catalog: WidgetCatalog, ): unknown[] { if (widgets.size === 0) return []; @@ -203,19 +206,19 @@ function projectWidgets( // (schema §1.2): emitted VERBATIM, no catalog lookup, no re-keying. return structuredClone(ym.get(OPAQUE_WIDGETS_KEY)); case "named": - return widgetsToPositional(nodeType, ym.get("widgets") as Y.Map, catalog); + return widgetsToPositional(nodeType, rowWidgetValues(ym), catalog); case "self": { // A24: rebuilt in the shape the producer serialized, from the node's own // declared order plus the stored residue. No catalog lookup — the // mapping this needs arrived with the node. - const form = storedWidgetFormOf(ym); - const widgets = ym.get("widgets"); + const form = rowWidgetForm(ym); + const widgets = rowWidgetValues(ym); // An unreadable form is not self-described (`storedWidgetFormOf`), so // `widgetStorageOf` and this read can only disagree on doc state no // writer here produces. Fall back to the catalog path rather than // inventing a shape, which keeps the KA-12 refusal loud. - if (!form) return widgetsToPositional(nodeType, widgets as Y.Map, catalog); - return projectWidgetForm(form, widgets instanceof Y.Map ? widgets : undefined); + if (!form) return widgetsToPositional(nodeType, widgets, catalog); + return projectWidgetForm(form, widgets); } default: return assertNever(storage, "project: widget-storage strategy"); @@ -226,12 +229,12 @@ 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")); + const rows = currentRowIds(ym); 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); + const widgets = rowWidgetValues(ym); + assertDynamicGroupRowCounts(rows, (name) => widgets.get(widgetStorageKey(name, 0))); ym.forEach((v, k) => { - if (k === NODE_INCARNATION_KEY) { + if (k === NODE_INCARNATION_KEY || k === DYNAMIC_GROUP_STATE_KEY) { return; } else if (k === OPAQUE_WIDGETS_KEY || k === "widgets" || k === WIDGET_FORM_KEY) { // All three storage keys project to the same workflow key; which one is @@ -241,7 +244,7 @@ function projectNode(ym: Y.Map, catalog: WidgetCatalog): WorkflowNode { // through `project()` -> `mint()` (which is what `compact()` is) has to // give it back or the next mint loses the layout. out["widgets_values"] = projectWidgets(nodeType, ym, catalog); - const form = storedWidgetFormOf(ym); + const form = rowWidgetForm(ym); if (form) out[WIDGET_FORM_FIELD] = { order: [...form.order] }; } else if (v instanceof Y.Array) { const projector = k === "outputs" ? projectOutputSlot : projectSlot; @@ -252,9 +255,57 @@ function projectNode(ym: Y.Map, catalog: WidgetCatalog): WorkflowNode { out[k] = structuredClone(v); } }); + projectRowSidecars(ym, out, widgets, rows); return out as WorkflowNode; } +function projectRowSidecars(ym: Y.Map, out: Record, widgets: WidgetValues, rows: ReturnType): void { + const groups = activeRowGroups(ym); + if (groups.size > 0) { + if (out["inputs"] !== undefined) out["inputs"] = rowInputProjection(ym).inputs; + if (rows) out["properties"] = { ...out["properties"] as object, dynamicGroupRows: rows }; + projectNamedRows(out, widgets, groups); + projectOrderedRows(out, widgets, groups); + } +} + +function projectOrderedRows(out: Record, widgets: WidgetValues, groups: ReturnType): void { + if (!Array.isArray(out["widgets_values_ordered"])) return; + let ordered = structuredClone(out["widgets_values_ordered"]) as Record[]; + for (const [name, group] of groups) { + const previous = ordered; + const firstRow = previous.findIndex((entry) => typeof entry["name"] === "string" && rowField(entry["name"], name, group.fields)); + ordered = previous.filter((entry) => typeof entry["name"] !== "string" || !rowField(entry["name"], name, group.fields)); + const controller = ordered.findIndex((entry) => entry["name"] === name && entry["occurrence"] === 0); + if (controller < 0 && firstRow < 0) continue; + if (controller >= 0) ordered[controller] = { ...ordered[controller], value: widgets.get(widgetStorageKey(name)) }; + const entries = liveRowIds(group).flatMap((id, index) => group.fields.map((field) => { + const oldIndex = group.initial_ids.indexOf(id); + const oldName = `${name}.${String(oldIndex)}.${field}`; + const prior = previous.find((entry) => entry["name"] === oldName && entry["occurrence"] === 0); + const widget = `${name}.${String(index)}.${field}`; + return { ...prior, name: widget, occurrence: 0, value: structuredClone(widgets.get(widgetStorageKey(widget))) }; + })); + ordered.splice(controller >= 0 ? controller + 1 : firstRow, 0, ...entries); + } + out["widgets_values_ordered"] = ordered; +} + +function projectNamedRows(out: Record, widgets: WidgetValues, groups: ReturnType): void { + const named = out["widgets_values_named"]; + if (typeof named === "object" && named !== null && !Array.isArray(named)) { + const rebuilt = { ...named as Record }; + for (const [name, group] of groups) { + for (const key of Object.keys(rebuilt)) if (rowField(key, name, group.fields)) delete rebuilt[key]; + widgets.forEach((value, key) => { + const identity = widgetIdentityFromStorageKey(key); + if (identity.occurrence === 0 && (identity.name === name || rowField(identity.name, name, group.fields))) rebuilt[identity.name] = structuredClone(value); + }); + } + out["widgets_values_named"] = rebuilt; + } +} + /** * Structural gate for one entry of a nodes map (#13). * @@ -470,5 +521,5 @@ export function project(doc: Y.Doc, catalog: WidgetCatalog): WorkflowJSON { wf["definitions"] = out; } - return wf as WorkflowJSON; + return projectRowTopology(doc, wf as WorkflowJSON); } diff --git a/src/read.ts b/src/read.ts index 007919b..3d994bb 100644 --- a/src/read.ts +++ b/src/read.ts @@ -57,8 +57,10 @@ */ import * as Y from "yjs"; -import { assertDynamicGroupRowCounts, dynamicGroupRowsOf } from "./dynamic-group-rows.js"; +import { assertDynamicGroupRowCounts } from "./dynamic-group-rows.js"; import { widgetStorageKey } from "./widget-identity.js"; +import { currentRowIds, rowWidgetForm, rowWidgetValues } from "./dynamic-row-state.js"; +import { rowTopologySnapshot } from "./dynamic-row-topology.js"; import { OPAQUE_WIDGETS_KEY, ROOT_APPLIED, @@ -69,7 +71,7 @@ import { ROOT_STAMPS, } from "./doc.js"; import { assertReadableSchema } from "./schema-version.js"; -import { LINK_STATE_DESCRIPTOR_VERSION } from "./types.js"; +import { DYNAMIC_GROUP_STATE_KEY, LINK_STATE_DESCRIPTOR_VERSION } from "./types.js"; import { WIDGET_FORM_KEY } from "./widget-form.js"; /** @@ -377,9 +379,16 @@ 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); + const rows = currentRowIds(node); + const widgets = rowWidgetValues(node); + if (node.has(DYNAMIC_GROUP_STATE_KEY)) { + const values: Record = Object.create(null) as Record; + widgets.forEach((value, key) => { values[key] = value; }); + out["widgets"] = snapshot(values, 1); + } + const form = rowWidgetForm(node); + if (form) out[WIDGET_FORM_KEY] = snapshot(form, 1); + assertDynamicGroupRowCounts(rows, (name) => widgets.get(widgetStorageKey(name, 0))); if (rows) out["dynamicGroupRows"] = snapshot(rows, 1); nodes[id] = Object.freeze(out) as NodeSnapshot; }); @@ -388,6 +397,17 @@ export function readGraph(doc: Y.Doc): GraphSnapshot { rootMap(doc, ROOT_LINKS)?.forEach((raw, id) => { links[id] = snapshot(raw, 1); }); + const topology = rowTopologySnapshot(doc); + if (topology) { + for (const key of Object.keys(links)) delete links[key]; + for (const raw of topology.links) if (Array.isArray(raw)) links[String(raw[0])] = snapshot(raw, 1); + for (const node of topology.nodes) { + const prior = nodes[String(node.id)]; + if (prior?.[OPAQUE_WIDGETS_KEY] !== undefined && node.widgets_values !== undefined) { + nodes[String(node.id)] = Object.freeze({ ...prior, [OPAQUE_WIDGETS_KEY]: snapshot(node.widgets_values, 1) }); + } + } + } return Object.freeze({ nodes: Object.freeze(nodes), links: Object.freeze(links) }); } @@ -537,9 +557,10 @@ export function readLinkState(doc: Y.Doc): Readonly> { !validId(tuple[3]) || !validSlot(tuple[4]) || destination === undefined || !validSlot(destination["to_slot"]) || destination["to_slot"] !== tuple[4] || !validSlotRecord || (slotRecord !== undefined && String(slotRecord["link"]) !== String(tuple[0])) || - !["concrete", "promoted", "autogrow"].includes(String(destination["kind"])) || + !["concrete", "promoted", "autogrow", "dynamic_group"].includes(String(destination["kind"])) || !validRequest || - (destination["kind"] === "promoted" && typeof destination["name"] !== "string")) { + (destination["kind"] === "promoted" && typeof destination["name"] !== "string") || + (destination["kind"] === "dynamic_group" && ["group", "row_id", "field", "node_incarnation"].some((key) => typeof destination[key] !== "string" || destination[key] === ""))) { throw new TypeError(`readLinkState: link ${id} has an unsupported or malformed descriptor`); } } diff --git a/src/stamps.ts b/src/stamps.ts index a1b5c8f..f079fe0 100644 --- a/src/stamps.ts +++ b/src/stamps.ts @@ -152,6 +152,12 @@ export function writeTarget(op: WireOp): unknown[] { return [op.op]; case "define_subgraph": return ["definition", op.subgraph_id]; + case "dynamic_group_insert_rows": + case "dynamic_group_delete_rows": + case "dynamic_group_set_row": + case "dynamic_group_connect": + case "dynamic_group_disconnect": + return dynamicRowTarget(op); default: // Exhaustiveness guard (issue #21): with every `WireOp` member cased // above — the six `Op` kinds plus the deferred `reset_doc` — `op` is @@ -190,3 +196,11 @@ export function widgetTargetKey(nodeId: unknown, incarnation: string, widget: st export function stampTargetKey(op: WireOp): string { return JSON.stringify(writeTarget(op)); } + +function dynamicRowTarget(op: Extract): unknown[] { + const owner = op.path ? [...op.path.map(String), String(op.node_id)] : String(op.node_id); + const target: unknown[] = [op.op, owner, op.node_incarnation, op.group]; + if (op.op === "dynamic_group_insert_rows") return [...target, op.op_id]; + if (op.op === "dynamic_group_delete_rows") return [...target, [...op.row_ids].sort()]; + return [...target, op.row_id]; +} diff --git a/src/types.ts b/src/types.ts index de6563a..a2d552a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -5,8 +5,8 @@ * stamp shapes minted by `comfy_cli/workflow_ops.py` (`_new_op`), pinned by * SHA at comfy-cli `7e732242d971daf0d2d30f22f997abfacd78986e` (FC-10: never by * branch — the branch this file used to cite has since been deleted upstream). - * `set_node_field` is the one package-local, provisional addition; ADR-032 - * records its closed field set and the upstream reconciliation requirement. + * `set_node_field` (ADR-032) and the five DynamicGroup row operations + * (schema A27) are package-local, provisional additions pending adoption. * Every `§` below is a section of that revision; see docs/upstream-pins.json * for the pin registry and the amendments upstream has added since. * The doc layout + op semantics reference is docs/multiplayer-schema.md. @@ -20,7 +20,11 @@ * 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 = 6; +export const SCHEMA_VERSION = 7; + +/** Private row registers and input-placement markers, never workflow fields. */ +export const DYNAMIC_GROUP_STATE_KEY = "__dynamic_group_state"; +export const DYNAMIC_GROUP_SLOT_KEY = "__dynamic_group_slot"; /** Version of an imported destination reconstruction descriptor in `__link_state`. */ export const LINK_STATE_DESCRIPTOR_VERSION = 1; @@ -44,7 +48,8 @@ export interface ImportedLinkState { export type OperationLinkDestination = | { kind: "concrete"; to_slot: number; slot: Record } | { kind: "promoted"; to_slot: number; name: string; slot: Record } - | { kind: "autogrow"; to_slot: number; slot: Record; request: GrowSpec }; + | { kind: "autogrow"; to_slot: number; slot: Record; request: GrowSpec } + | { kind: "dynamic_group"; to_slot: number; slot: Record; group: string; row_id: string; field: string; node_incarnation: string }; /** Durable intent created by an installed connect, owned by its A18 operation stamp. */ export interface OperationLinkState { @@ -76,13 +81,19 @@ export const FROZEN_OPS = [ "clear", "define_subgraph", "insert_workflow", + "dynamic_group_insert_rows", + "dynamic_group_set_row", + "dynamic_group_delete_rows", + "dynamic_group_connect", + "dynamic_group_disconnect", ] as const; /** Defined by the vocabulary but deferred (§1.6): rejected until un-deferred by amendment. */ export const DEFERRED_OPS = ["reset_doc"] as const; /** - * Kinds accepted inside a multi-op batch by comfy-cli's `apply_specs` — the + * Kinds accepted inside a multi-op batch; the five A27 row kinds remain + * provisional package extensions. The other kinds follow comfy-cli's `apply_specs` — the * **spec-authoring** surface (`comfy workflow apply` / `foreach`), which takes * edit *specs* and MINTS ops. `clear` and `reset_doc` rewrite the whole * document, so a spec batch containing either is rejected whole, before @@ -111,6 +122,11 @@ export const BATCHABLE_OPS = [ "set_node_field", "delete_node", "define_subgraph", + "dynamic_group_insert_rows", + "dynamic_group_set_row", + "dynamic_group_delete_rows", + "dynamic_group_connect", + "dynamic_group_disconnect", ] as const; /** A kind `applyOps` implements. */ @@ -199,6 +215,54 @@ export interface AddNodeOp extends OpBase { node: WorkflowNode; } +export interface DynamicGroupAddress { + node_id: NodeId; + /** Container instances; node_id names the leaf, not another path segment. */ + path?: [string, ...string[]]; + node_incarnation: string; + group: string; +} + +export interface DynamicGroupInsertRowsOp extends OpBase, DynamicGroupAddress { + op: "dynamic_group_insert_rows"; + after_row_id: string | null; + /** Complete creator-supplied field values; IDs derive from op_id and ordinal. */ + rows: Record[]; +} + +export interface DynamicGroupSetRowOp extends OpBase, DynamicGroupAddress { + op: "dynamic_group_set_row"; + row_id: string; + values: Record; + /** Optional visible host; absent edits the owning node's defaults. */ + host_path?: [string, ...string[]]; + host_incarnation?: string; +} + +export interface DynamicGroupDeleteRowsOp extends OpBase, DynamicGroupAddress { + op: "dynamic_group_delete_rows"; + row_ids: string[]; +} + +export interface DynamicGroupConnectOp extends OpBase, DynamicGroupAddress { + op: "dynamic_group_connect"; + row_id: string; + field: string; + from_node: NodeId; + from_slot: number; + link_id: NodeId; + link_type: string; + input_type: string; +} + +export interface DynamicGroupDisconnectOp extends OpBase, DynamicGroupAddress { + op: "dynamic_group_disconnect"; + row_id: string; + field: string; +} + +export type DynamicGroupRowOp = DynamicGroupInsertRowsOp | DynamicGroupSetRowOp | DynamicGroupDeleteRowsOp | DynamicGroupConnectOp | DynamicGroupDisconnectOp; + /** * Merge a workflow template (nodes, links, `definitions.subgraphs`) into an * existing doc in one transaction (ADR-022; agent-subgraph TDD V1.5). @@ -554,7 +618,8 @@ export type Op = | DeleteNodeOp | ClearOp | DefineSubgraphOp - | InsertWorkflowOp; + | InsertWorkflowOp + | DynamicGroupRowOp; /** * A kind the vocabulary declares but this package refuses to apply diff --git a/src/widget-form.ts b/src/widget-form.ts index 22f8933..0e496f5 100644 --- a/src/widget-form.ts +++ b/src/widget-form.ts @@ -63,7 +63,7 @@ */ import type * as Y from "yjs"; -import { widgetIndexOf, widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; +import { widgetIndexOf, widgetOccurrenceAt, widgetStorageKey, type WidgetValues } from "./widget-identity.js"; /** Producer-supplied node field carrying the declaration (workflow JSON). */ export const WIDGET_FORM_FIELD = "widgets_values_form"; @@ -278,7 +278,7 @@ export function formFinalOccurrence(form: StoredWidgetForm, name: string, occurr */ export function projectWidgetForm( form: StoredWidgetForm, - widgets: Y.Map | undefined, + widgets: WidgetValues | undefined, ): unknown { const read = (name: string, occurrence: number): unknown => { const key = widgetStorageKey(name, occurrence); diff --git a/src/widget-identity.ts b/src/widget-identity.ts index 9f41d61..c8cfc21 100644 --- a/src/widget-identity.ts +++ b/src/widget-identity.ts @@ -4,6 +4,14 @@ export interface WidgetIdentity { occurrence: number; } +/** Read-only widget values, backed by either stored Yjs data or a derived row view. */ +export interface WidgetValues { + readonly size: number; + get(key: string): unknown; + has(key: string): boolean; + forEach(callback: (value: unknown, key: string) => void): void; +} + /** * Occurrence zero keeps the legacy key so selectors and single-name catalogs * retain their existing storage. Reserved-looking names are escaped into the diff --git a/test/atomic-dynamic-group-rows.test.ts b/test/atomic-dynamic-group-rows.test.ts new file mode 100644 index 0000000..d3ba2cc --- /dev/null +++ b/test/atomic-dynamic-group-rows.test.ts @@ -0,0 +1,670 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; +import * as Y from "yjs"; +import { admitDynamicGroupRowOp, applyOps, compact, mint, project, readGraph, stampKey, compareStampKeys, type DynamicGroupRowOp, type Op, 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 }; +const catalog: WidgetCatalog = { types: { ...fixture.catalog.types, FloatLiteral: { widget_order: ["value"] } } }; +const env = (id: number) => ({ op_id: id.toString(16).padStart(32, "0"), actor: "agent:a", base_version: id, stamp: [id, "agent:a"] as [number, string] }); +const rowId = (id: number, ordinal = 0) => `row:${env(id).op_id}:${String(ordinal)}`; +const values = (name: string, strength: number, enabled = true) => ({ lora_name: `${name}.safetensors`, strength, enabled }); + +function workflow(linked = false): WorkflowJSON { + const result = structuredClone(fixture.workflow); + const node = result.nodes[0]!; + node.widgets_values = { + ...(node["widgets_values_named"] as Record), loras: 3, + ...Object.fromEntries([values("A", 0.1), values("B", 0.2), values("C", 0.3, false)].flatMap((row, index) => + Object.entries(row).map(([field, value]) => [`loras.${String(index)}.${field}`, value]))), + }; + node["widgets_values_named"] = structuredClone(node.widgets_values); + node["properties"] = { dynamicGroupRows: { loras: ["A", "B", "C"], weights: ["W"] } }; + node.inputs = [ + { name: "model", type: "MODEL", link: null }, + ...[0, 1, 2].map((index) => ({ name: `loras.${String(index)}.strength`, type: "FLOAT", widget: { name: `loras.${String(index)}.strength` }, link: linked ? 21 + index : null })), + { name: "after", type: "STRING", widget: { name: "after" }, link: null }, + ]; + if (linked) { + for (const [index, strength] of [0.1, 0.2, 0.3].entries()) { + result.nodes.push({ id: 101 + index, type: "FloatLiteral", inputs: [], outputs: [{ name: "FLOAT", type: "FLOAT", links: [21 + index] }], widgets_values: [strength] }); + result.links.push([21 + index, 101 + index, 0, 1, 1 + index, "FLOAT"]); + } + } + return result; +} + +const address = { node_id: 1, node_incarnation: "0", group: "loras" }; +const remove = (ids: string[], id = 1): Extract => ({ ...env(id), ...address, op: "dynamic_group_delete_rows", row_ids: ids }); +const edit = (row: string, fields: Record, id = 2): Extract => ({ ...env(id), ...address, op: "dynamic_group_set_row", row_id: row, values: fields }); +const insert = (after: string | null, rows: Record[], id = 3): Extract => ({ ...env(id), ...address, op: "dynamic_group_insert_rows", after_row_id: after, rows }); +const connect = (row: string, id = 7): Extract => ({ ...env(id), ...address, op: "dynamic_group_connect", row_id: row, field: "strength", from_node: 103, from_slot: 0, link_id: 31, link_type: "FLOAT", input_type: "FLOAT" }); + +function promotedWorkflow(nested: boolean): WorkflowJSON { + const source = workflow(); + const leaf = source.nodes[0]!; + leaf.inputs = [0, 1, 2].map((index) => ({ name: `loras.${String(index)}.strength`, type: "FLOAT", widget: { name: `loras.${String(index)}.strength` }, link: 11 + index })); + const def = { + id: "inner-definition", inputNode: { id: -10 }, outputNode: { id: -20 }, + inputs: [0, 1, 2].map((index) => ({ id: `port-${String(index)}`, name: `loras.${String(index)}.strength`, type: "FLOAT", linkIds: [11 + index] })), + outputs: [], nodes: [leaf], widgets: [0, 1, 2].map((index) => ({ id: 1, name: `loras.${String(index)}.strength` })), + links: [0, 1, 2].map((index) => ({ id: 11 + index, origin_id: -10, origin_slot: index, target_id: 1, target_slot: index, type: "FLOAT" })), + }; + const host = (id: number, type: string) => ({ id, type, + inputs: [0, 1, 2].map((index) => ({ id: `port-${String(index)}`, name: `loras.${String(index)}.strength`, type: "FLOAT", widget: { name: `loras.${String(index)}.strength` }, link: null as number | null })), outputs: [], + widgets_values: [0.4, 0.5, 0.6], properties: { proxyWidgets: [0, 1, 2].map((index) => [nested && id === 9 ? "2" : "1", `loras.${String(index)}.strength`]) }, + }); + const rootHost = host(9, nested ? "outer-definition" : "inner-definition"); + rootHost.inputs.forEach((slot, index) => { slot.link = 21 + index; }); + const outerHost = host(2, "inner-definition"); + outerHost.inputs.forEach((slot, index) => { slot.link = 31 + index; }); + const outer = { + id: "outer-definition", inputNode: { id: -10 }, outputNode: { id: -20 }, inputs: structuredClone(def.inputs).map((slot, index) => ({ ...slot, linkIds: [31 + index] })), outputs: [], nodes: [outerHost], + widgets: [0, 1, 2].map((index) => ({ id: 2, name: `loras.${String(index)}.strength` })), + links: [0, 1, 2].map((index) => ({ id: 31 + index, origin_id: -10, origin_slot: index, target_id: 2, target_slot: index, type: "FLOAT" })), + }; + return { + nodes: [rootHost, ...[0, 1, 2].map((index) => ({ id: 101 + index, type: "FloatLiteral", inputs: [], outputs: [{ name: "FLOAT", type: "FLOAT", links: [21 + index] }], widgets_values: [0.4 + index / 10] }))], + links: [0, 1, 2].map((index) => [21 + index, 101 + index, 0, 9, index, "FLOAT"]), + definitions: { subgraphs: nested ? [def, outer] : [def] }, + }; +} + +function target(doc: Y.Doc) { + return project(doc, catalog).nodes.find((node) => node.id === 1)!; +} + +describe("atomic DynamicGroup row operations", () => { + it("deletes a middle row while preserving surviving values and siblings", () => { + const doc = mint(workflow(), catalog); + expect(applyOps(doc, [remove(["B"])], catalog).outcomes[0]?.outcome).toBe("applied"); + const node = target(doc); + expect(node["properties"]).toEqual({ dynamicGroupRows: { loras: ["A", "C"], weights: ["W"] } }); + expect(node["widgets_values_named"]).toMatchObject({ loras: 2, "loras.0.lora_name": "A.safetensors", "loras.1.lora_name": "C.safetensors", "loras.1.strength": 0.3, "loras.1.enabled": false, "weights.0.seed": 5, "weights.0.seed.0": "fixed", "mode.steps": 7, after: "tail" }); + expect(node["widgets_values_named"]).not.toHaveProperty("loras.2.strength"); + expect(readGraph(doc).nodes["1"]!.widgets).toMatchObject({ loras: 2, "loras.1.strength": 0.3, "loras.1.enabled": false }); + doc.destroy(); + }); + + it("converges a middle deletion and a surviving-row edit in both orders", () => { + const seed = mint(workflow(), catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [remove(["B"]), edit("C", { strength: 0.7 })]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, order, catalog).outcomes.map((outcome) => outcome.outcome)).toEqual(["applied", "applied"]); + expect(target(doc)["widgets_values_named"]).toMatchObject({ loras: 2, "loras.1.lora_name": "C.safetensors", "loras.1.strength": 0.7 }); + const before = Y.encodeStateAsUpdate(doc); + applyOps(doc, order, catalog); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + doc.destroy(); + } + seed.destroy(); + }); + + it("does not apply a deleted-row edit to a newly inserted row at its old position", () => { + const seed = mint(workflow(), catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [remove(["B"]), edit("B", { strength: 999 }), insert("A", [values("D", 0.4)])]; + const orders = [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]; + let expected: unknown; + for (const indices of orders) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, indices.map((index) => ops[index]!), catalog).outcomes.every((outcome) => outcome.outcome !== "rejected"), indices.join(",")).toBe(true); + expect(target(doc)["properties"]).toMatchObject({ dynamicGroupRows: { loras: ["A", rowId(3), "C"] } }); + expect(target(doc)["widgets_values_named"]).toMatchObject({ "loras.1.lora_name": "D.safetensors", "loras.1.strength": 0.4, "loras.2.strength": 0.3 }); + const actual = canonicalize(project(doc, catalog)); + if (expected === undefined) expected = actual; + else expect(actual, indices.join(",")).toEqual(expected); + doc.destroy(); + } + expect(orders).toHaveLength(6); + seed.destroy(); + }); + + it("orders concurrent insertions at the same anchor by their creator stamps", () => { + const wide = structuredClone(catalog); + wide.types["CompositeDynamicGroup"]!.dynamic_groups!["loras"]!.max = 6; + const seed = mint(workflow(), wide); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [insert("A", [values("D", 0.4), values("E", 0.5)], 3), insert("A", [values("F", 0.6)], 4)]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + for (const op of order) { + admitDynamicGroupRowOp(doc, op as DynamicGroupRowOp, wide); + expect(applyOps(doc, [op], wide).outcomes[0]?.outcome).toBe("applied"); + } + expect(target(doc)["properties"]).toMatchObject({ dynamicGroupRows: { loras: ["A", rowId(4), rowId(3), rowId(3, 1), "B", "C"] } }); + doc.destroy(); + } + seed.destroy(); + }); + + it("retains deletion and field registers when they arrive before their insertion", () => { + const seed = mint(workflow(), catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [insert("A", [values("D", 0.4)], 3), edit(rowId(3), { strength: 0.8 }, 4), remove([rowId(3)], 5)]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, order, catalog).outcomes.every((outcome) => outcome.outcome !== "rejected")).toBe(true); + expect(target(doc)["properties"]).toMatchObject({ dynamicGroupRows: { loras: ["A", "B", "C"] } }); + expect(target(doc)["widgets_values_named"]).toMatchObject({ "loras.1.lora_name": "B.safetensors", "loras.2.strength": 0.3 }); + doc.destroy(); + } + seed.destroy(); + }); + + it("merges independent fields and resolves the overlapping field by LWW", () => { + const seed = mint(workflow(), catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [edit("C", { strength: 0.7, enabled: true }, 2), edit("C", { lora_name: "new.safetensors", strength: 0.9 }, 3)]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, order, catalog).outcomes.every((outcome) => outcome.outcome !== "rejected")).toBe(true); + expect(target(doc)["widgets_values_named"]).toMatchObject({ "loras.2.lora_name": "new.safetensors", "loras.2.strength": 0.9, "loras.2.enabled": true }); + doc.destroy(); + } + seed.destroy(); + }); + + it("validates all fields before any part of a row edit is written", () => { + const source = workflow(); + assertRejectedWithoutMutation(source, edit("C", { strength: 0.9, unknown: "must not land" }), "malformed_op", catalog); + expect(source.nodes[0]!.widgets_values).toMatchObject({ "loras.2.strength": 0.3 }); + }); + + it("reindexes surviving connections and removes only the deleted row's links", () => { + const doc = mint(workflow(true), catalog); + expect(applyOps(doc, [remove(["B"])], catalog).outcomes[0]?.outcome).toBe("applied"); + const result = project(doc, catalog); + expect(result.links).toEqual([[21, 101, 0, 1, 1, "FLOAT"], [23, 103, 0, 1, 2, "FLOAT"]]); + expect(target(doc).inputs).toEqual([ + { name: "model", type: "MODEL", link: null }, + { name: "loras.0.strength", type: "FLOAT", widget: { name: "loras.0.strength" }, link: 21 }, + { name: "loras.1.strength", type: "FLOAT", widget: { name: "loras.1.strength" }, link: 23 }, + { name: "after", type: "STRING", widget: { name: "after" }, link: null }, + ]); + expect(result.nodes.find((node) => node.id === 102)!.outputs).toEqual([{ name: "FLOAT", type: "FLOAT", links: [] }]); + expect(readGraph(doc).links).toEqual({ "21": result.links[0], "23": result.links[1] }); + doc.destroy(); + }); + + it("carries row anchors and tombstones through compaction and encoded reconnect", () => { + const doc = mint(workflow(true), catalog); + const ops = [insert("B", [values("D", 0.4)], 3), remove(["B"], 4)]; + expect(applyOps(doc, ops, catalog).outcomes.every((outcome) => outcome.outcome !== "rejected")).toBe(true); + const checkpoint = compact(doc, catalog); + expect(canonicalize(project(checkpoint, catalog))).toEqual(canonicalize(project(doc, catalog))); + const fork = new Y.Doc(); + Y.applyUpdate(fork, Y.encodeStateAsUpdate(checkpoint)); + expect(applyOps(fork, [edit("C", { strength: 0.8 }, 5)], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(target(fork)["properties"]).toMatchObject({ dynamicGroupRows: { loras: ["A", rowId(3), "C"] } }); + expect(target(fork)["widgets_values_named"]).toMatchObject({ "loras.1.lora_name": "D.safetensors", "loras.2.strength": 0.8 }); + expect(applyOps(fork, [insert("B", [values("E", 0.5)], 6)], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(target(fork)["properties"]).toMatchObject({ dynamicGroupRows: { loras: ["A", rowId(6), rowId(3), "C"] } }); + checkpoint.destroy(); + fork.destroy(); + doc.destroy(); + }); + + it("connects a surviving row by ID in either order with a middle deletion", () => { + const seed = mint(workflow(true), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const ops = [remove(["B"]), connect("C")]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).links).toEqual([[21, 101, 0, 1, 1, "FLOAT"], [31, 103, 0, 1, 2, "FLOAT"]]); + expect(target(doc).inputs![2]).toMatchObject({ name: "loras.1.strength", link: 31 }); + doc.destroy(); + } + seed.destroy(); + }); + + it("does not attach a deleted-row connect to its successor", () => { + const seed = mint(workflow(true), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const ops = [remove(["B"]), connect("B")]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).links).toEqual([[21, 101, 0, 1, 1, "FLOAT"], [23, 103, 0, 1, 2, "FLOAT"]]); + doc.destroy(); + } + seed.destroy(); + }); + + it.each([false, true])("removes promotions and external links through nested=%s while preserving surviving host values", (nested) => { + const doc = mint(promotedWorkflow(nested), catalog); + const op = { ...remove(["B"]), path: nested ? ["9", "2"] : ["9"] } as Op; + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + const result = project(doc, catalog); + expect(result.links).toEqual([[21, 101, 0, 9, 0, "FLOAT"], [23, 103, 0, 9, 1, "FLOAT"]]); + expect(result.nodes.find((node) => node.id === 9)).toMatchObject({ widgets_values: [0.4, 0.6], inputs: [{ name: "loras.0.strength", link: 21 }, { name: "loras.1.strength", link: 23 }] }); + const definitions = result.definitions!.subgraphs as Record[]; + for (const definition of definitions) { + expect(definition["inputs"]).toEqual([ + { id: "port-0", name: "loras.0.strength", type: "FLOAT", linkIds: [definition["id"] === "inner-definition" ? 11 : 31] }, + { id: "port-2", name: "loras.1.strength", type: "FLOAT", linkIds: [definition["id"] === "inner-definition" ? 13 : 33] }, + ]); + expect(definition["widgets"]).toEqual([{ id: definition["id"] === "inner-definition" ? 1 : 2, name: "loras.0.strength" }, { id: definition["id"] === "inner-definition" ? 1 : 2, name: "loras.1.strength" }]); + } + expect(readGraph(doc).nodes["9"]!["__widgets_opaque"]).toEqual([0.4, 0.6]); + doc.destroy(); + }); + + it.each([false, true])("edits a surviving promoted value by row ID through nested=%s in either order", (nested) => { + const seed = mint(promotedWorkflow(nested), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const path = nested ? ["9", "2"] : ["9"]; + const ops = [{ ...remove(["B"]), path }, { ...edit("C", { strength: 0.9 }, 8), path, host_path: ["9"], host_incarnation: "0" }] as Op[]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).nodes.find((node) => node.id === 9)!.widgets_values).toEqual([0.4, 0.9]); + doc.destroy(); + } + seed.destroy(); + }); + + it("checks current min/max during admission without changing the document", () => { + const bounded = structuredClone(catalog); + bounded.types["CompositeDynamicGroup"]!.dynamic_groups!["loras"]!.min = 2; + const doc = mint(workflow(), bounded); + const before = Y.encodeStateAsUpdate(doc); + const roots = [...doc.share.keys()]; + expect(() => admitDynamicGroupRowOp(doc, insert("A", [values("D", 0.4)]) as DynamicGroupRowOp, bounded)).toThrow(/max rows/); + expect(() => admitDynamicGroupRowOp(doc, remove(["A", "B"]) as DynamicGroupRowOp, bounded)).toThrow(/min rows/); + expect(() => admitDynamicGroupRowOp(doc, remove(["B"]) as DynamicGroupRowOp, bounded)).not.toThrow(); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + expect([...doc.share.keys()]).toEqual(roots); + doc.destroy(); + }); + + it("replays admitted growth and shrink without rechecking transient receiver counts", () => { + const seed = mint(workflow(), catalog); + const removed = remove(["B"]); + const added = insert("A", [values("D", 0.4)]); + const original = Y.encodeStateAsUpdate(seed); + admitDynamicGroupRowOp(seed, removed as DynamicGroupRowOp, catalog); + applyOps(seed, [removed], catalog); + admitDynamicGroupRowOp(seed, added as DynamicGroupRowOp, catalog); + applyOps(seed, [added], catalog); + const fork = new Y.Doc(); Y.applyUpdate(fork, original); + expect(applyOps(fork, [added, removed], catalog).outcomes.every((value) => value.outcome !== "rejected")).toBe(true); + expect(canonicalize(project(fork, catalog))).toEqual(canonicalize(project(seed, catalog))); + fork.destroy(); seed.destroy(); + }); + + it("does not use a definition's socket ordinal as a promoted widget-value ordinal", () => { + const source = promotedWorkflow(false); + const definition = source.definitions!.subgraphs![0] as Record; + (definition["inputs"] as unknown[]).unshift({ id: "model-port", name: "model", type: "MODEL", linkIds: [] }); + (definition["links"] as Record[]).forEach((link) => { link["origin_slot"] = Number(link["origin_slot"]) + 1; }); + const host = source.nodes[0]!; + host.inputs!.unshift({ id: "model-port", name: "model", type: "MODEL", link: null }); + (source.links as unknown[][]).forEach((link) => { link[4] = Number(link[4]) + 1; }); + const doc = mint(source, catalog); + const op = { ...edit("C", { strength: 0.9 }, 8), path: ["9"], host_path: ["9"], host_incarnation: "0" } as Op; + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, catalog).nodes.find((node) => node.id === 9)!.widgets_values).toEqual([0.4, 0.5, 0.9]); + doc.destroy(); + }); + + it("refuses a numeric address that can move with row deletion but retains the fixed socket prefix", () => { + const source = workflow(true); + const numeric: Op = { ...env(8), op: "connect", from_node: 101, from_slot: 0, to_node: 1, to_slot: 2, link_id: 31, link_type: "FLOAT" }; + assertRejectedWithoutMutation(source, numeric, "malformed_op", catalog); + const doc = mint(source, catalog); + expect(applyOps(doc, [{ ...numeric, to_slot: 0 }], catalog).outcomes[0]?.outcome).toBe("applied"); + doc.destroy(); + }); + + it.each([false, true])("refuses positional promoted writes on row-controlled hosts through nested=%s", (nested) => { + const source = promotedWorkflow(nested); + const op: Op = { ...env(8), op: "set_widget", node_id: 9, widget: "loras.1.strength", value: 9, + promoted: { value_index: 1, host_widgets_values: [0.4, 0.5, 0.6] } }; + assertRejectedWithoutMutation(source, op, "malformed_op", catalog); + }); + + it("does not materialize a converted socket when disconnecting an unconverted widget", () => { + const doc = mint(workflow(), catalog); + const op = { ...env(8), ...address, op: "dynamic_group_disconnect", row_id: "C", field: "enabled" } as Op; + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).not.toBe("rejected"); + expect(target(doc).inputs).toHaveLength(5); + expect(target(doc).inputs!.some((slot) => (slot as Record)["name"] === "loras.2.enabled")).toBe(false); + doc.destroy(); + }); + + it("restores a row connection after its source is removed and re-added, in both causal orders", () => { + const seed = mint(workflow(true), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const deletion: Op = { ...env(8), op: "delete_node", node_id: 103, removed_links: [] }; + const source = workflow(true).nodes.find((node) => node.id === 103)!; + const addition: Op = { ...env(9), op: "add_node", node_id: 103, class_type: "FloatLiteral", pos: [0, 0], node: source }; + for (const ops of [[connect("C"), deletion, addition], [deletion, connect("C"), addition]]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, ops, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).links).toContainEqual([31, 103, 0, 1, 3, "FLOAT"]); + expect(target(doc).inputs![3]).toMatchObject({ name: "loras.2.strength", link: 31 }); + const slot = (doc.getMap("nodes").get("1") as Y.Map).get("inputs") as Y.Array>; + expect(slot.get(3).has("link")).toBe(false); + doc.destroy(); + } + seed.destroy(); + }); + + it("does not restore a deleted row when its source is re-added", () => { + const doc = mint(workflow(true), catalog); + const source = workflow(true).nodes.find((node) => node.id === 103)!; + const ops: Op[] = [connect("C"), remove(["C"], 8), { ...env(9), op: "delete_node", node_id: 103, removed_links: [] }, { ...env(10), op: "add_node", node_id: 103, class_type: "FloatLiteral", pos: [0, 0], node: source }]; + expect(applyOps(doc, ops, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).links.some((link) => (link as unknown[])[0] === 31)).toBe(false); + expect(target(doc).inputs).toHaveLength(4); + doc.destroy(); + }); + + it("moves a normalized link ID between rows without resurrecting a stale slot pointer", () => { + const seed = mint(workflow(true), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const ops = [{ ...connect("A", 7), link_id: "31" }, connect("C", 8)] as Op[]; + for (const order of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).links).toEqual([[22, 102, 0, 1, 2, "FLOAT"], [31, 103, 0, 1, 3, "FLOAT"]]); + expect(target(doc).inputs![1]).toMatchObject({ link: null }); + expect(target(doc).inputs![3]).toMatchObject({ link: 31 }); + doc.destroy(); + } + seed.destroy(); + }); + + it("takes the row-field winner from the creator stamp rather than the transport envelope", () => { + const seed = mint(workflow(), catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const low = { ...edit("C", { strength: 0.8 }, 2), base_version: 100, stamp: [1, "agent:a"] } as Op; + const high = { ...edit("C", { strength: 0.9 }, 3), base_version: 1, stamp: [2, "agent:a"] } as Op; + expect(low.base_version).toBeGreaterThan(high.base_version); + expect(compareStampKeys(stampKey(low), stampKey(high))).toBe(-1); + for (const ops of [[low, high], [high, low]]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, ops, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(target(doc)["widgets_values_named"]).toMatchObject({ "loras.2.strength": 0.9 }); + doc.destroy(); + } + seed.destroy(); + }); + + it.each([ + { ...connect("C"), from_node: undefined }, + { ...connect("C"), link_id: Infinity }, + { ...insert("A", [values("D", 0.4)]), rows: new Array(1) }, + { ...remove(["B"]), row_ids: new Array(1) }, + { ...edit("C", { strength: 0.9 }), stamp: [] }, + { ...edit("C", { strength: 0.9 }), stamp: undefined }, + ])("refuses malformed row payloads before writes: $op", (op) => { + assertRejectedWithoutMutation(workflow(true), op as Op, "malformed_op", catalog); + }); + + it("preflights missing source slots and incomplete host bindings during readonly admission", () => { + const doc = mint(workflow(true), catalog); + const before = Y.encodeStateAsUpdate(doc); + expect(() => admitDynamicGroupRowOp(doc, { ...connect("C"), from_slot: 9 } as DynamicGroupRowOp, catalog)).toThrow(/output slot/); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + doc.destroy(); + const promoted = mint(promotedWorkflow(false), catalog); + const bytes = Y.encodeStateAsUpdate(promoted); + const op = { ...edit("C", { strength: 0.9, enabled: false }, 8), path: ["9"], host_path: ["9"], host_incarnation: "0" } as DynamicGroupRowOp; + expect(() => admitDynamicGroupRowOp(promoted, op, catalog)).toThrow(/not materialized/); + expect(Y.encodeStateAsUpdate(promoted)).toEqual(bytes); + promoted.destroy(); + }); + + it("keeps the declared widget form and ordered sidecar aligned across middle-row deletion", () => { + const source = workflow(); + const values = source.nodes[0]!.widgets_values as Record; + source.nodes[0]!["widgets_values_form"] = { order: Object.keys(values) }; + source.nodes[0]!["widgets_values_ordered"] = Object.entries(values).map(([name, value]) => ({ name, occurrence: 0, value, extension_entry: name })); + const doc = mint(source, catalog); + expect(applyOps(doc, [remove(["B"])], catalog).outcomes[0]?.outcome).toBe("applied"); + const result = target(doc); + expect(result["widgets_values_ordered"]).toEqual(expect.arrayContaining([ + { name: "loras", occurrence: 0, value: 2, extension_entry: "loras" }, + { name: "loras.1.strength", occurrence: 0, value: 0.3, extension_entry: "loras.2.strength" }, + { name: "after", occurrence: 0, value: "tail", extension_entry: "after" }, + ])); + expect((result["widgets_values_ordered"] as Record[]).some((entry) => entry["name"] === "loras.2.strength")).toBe(false); + expect(canonicalize(project(mint(project(doc, catalog), catalog), catalog))).toEqual(canonicalize(project(doc, catalog))); + doc.destroy(); + }); + + it("retains an independent second group's row edits when the first group is structurally changed", () => { + const doc = mint(workflow(), catalog); + const other = { ...edit("W", { seed: 99, "seed.0": "randomize" }, 8), group: "weights" } as Op; + expect(applyOps(doc, [remove(["B"]), other], catalog).outcomes.map((result) => result.outcome)).toEqual(["applied", "applied"]); + expect(target(doc)["widgets_values_named"]).toMatchObject({ loras: 2, weights: 1, "weights.0.seed": 99, "weights.0.seed.0": "randomize", "weights.0.weight": 0.25, "mode.steps": 7 }); + doc.destroy(); + }); + + it("retires a pending row connection when its source is absent during disconnect", () => { + const doc = mint(workflow(true), catalog); + const disconnect = { ...env(9), ...address, op: "dynamic_group_disconnect", row_id: "C", field: "strength" } as Op; + const source = workflow(true).nodes.find((node) => node.id === 103)!; + const ops: Op[] = [connect("C"), { ...env(8), op: "delete_node", node_id: 103, removed_links: [] }, disconnect, { ...env(10), op: "add_node", node_id: 103, class_type: "FloatLiteral", pos: [0, 0], node: source }]; + expect(applyOps(doc, ops, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + expect(project(doc, catalog).links.some((link) => (link as unknown[])[0] === 31)).toBe(false); + expect(target(doc).inputs![3]).toMatchObject({ link: null }); + doc.destroy(); + }); + + it("lets a higher complete-link identity retire an input claim that already lost its ID", () => { + const source = workflow(true); + delete source.nodes[0]!["properties"]; + source.nodes.push({ id: 200, type: "FloatLiteral", widgets_values: [0], inputs: [{ name: "value", type: "FLOAT", link: null }] }); + const seed = mint(source, catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const low: Op = { ...env(7), op: "connect", from_node: 103, from_slot: 0, to_node: 1, to_slot: 2, link_id: 31, link_type: "FLOAT" }; + const high: Op = { ...low, ...env(8), to_node: 200, to_slot: 0 }; + for (const order of [[low, high], [high, low]]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + const result = project(doc, catalog); + expect(result.links).toEqual([[21, 101, 0, 1, 1, "FLOAT"], [23, 103, 0, 1, 3, "FLOAT"], [31, 103, 0, 200, 0, "FLOAT"]]); + expect(result.nodes.find((node) => node.id === 1)!.inputs![2]).toMatchObject({ link: null }); + doc.destroy(); + } + seed.destroy(); + }); + + it("rejects producer-forged private row storage and slot markers", () => { + const state = workflow(); + state.nodes[0]!["__dynamic_group_state"] = {}; + expect(() => mint(state, catalog)).toThrow(/reserved key/); + const marker = workflow(); + (marker.nodes[0]!.inputs![1] as Record)["__dynamic_group_slot"] = { group: "loras", row_id: "B", field: "strength" }; + expect(() => mint(marker, catalog)).toThrow(/reserved DynamicGroup slot/); + }); + + it("preserves non-default subgraph boundary IDs in catalog-free reconnect snapshots", () => { + const source = promotedWorkflow(false); + const definition = source.definitions!.subgraphs![0] as Record; + definition["inputNode"] = { id: -30 }; + (definition["links"] as Record[]).forEach((link) => { link["origin_id"] = -30; }); + const doc = mint(source, catalog); + const op = { ...remove(["B"]), path: ["9"] } as Op; + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + const result = project(doc, catalog); + expect(readGraph(doc).links).toEqual(Object.fromEntries((result.links as unknown[][]).map((link) => [String(link[0]), link]))); + expect(readGraph(doc).nodes["9"]!["__widgets_opaque"]).toEqual([0.4, 0.6]); + doc.destroy(); + }); + + it("spells the private row wire keys in the encoded snapshot and recovers them by their published names", () => { + const layout = JSON.parse(readFileSync(new URL("../fixtures/golden-vectors/wire-layout.json", import.meta.url), "utf8")) as { reserved_node_keys: { dynamic_group_state: string }; reserved_input_keys: { dynamic_group_slot: string } }; + const doc = mint(workflow(), catalog); + applyOps(doc, [remove(["B"])], catalog); + const bytes = Y.encodeStateAsUpdate(doc); + for (const name of [layout.reserved_node_keys.dynamic_group_state, layout.reserved_input_keys.dynamic_group_slot]) { + const token = Buffer.concat([Buffer.from([Buffer.byteLength(name)]), Buffer.from(name)]); + expect(Buffer.from(bytes).includes(token), name).toBe(true); + } + const fork = new Y.Doc(); Y.applyUpdate(fork, bytes); + const node = fork.getMap("nodes").get("1") as Y.Map; + expect(node.get(layout.reserved_node_keys.dynamic_group_state)).toBeInstanceOf(Y.Map); + const input = (node.get("inputs") as Y.Array>).get(2); + expect(input.get(layout.reserved_input_keys.dynamic_group_slot)).toEqual({ group: "loras", row_id: "B", field: "strength" }); + expect(readGraph(fork).nodes["1"]!.dynamicGroupRows).toMatchObject({ loras: ["A", "C"] }); + fork.destroy(); doc.destroy(); + }); + + it("treats prototype-looking template fields as literal row identities", () => { + const source = workflow(true); + const literal = structuredClone(catalog); + literal.types["CompositeDynamicGroup"]!.dynamic_groups!["loras"]!.widgets = ["constructor", "__proto__", "enabled"]; + const rename = (name: string) => name.replace(/\.lora_name$/, ".constructor").replace(/\.strength$/, ".__proto__"); + const node = source.nodes[0]!; + node.widgets_values = Object.fromEntries(Object.entries(node.widgets_values as Record).map(([name, value]) => [rename(name), value])); + node["widgets_values_named"] = structuredClone(node.widgets_values); + node.inputs!.forEach((slot) => { + const value = slot as Record; + value["name"] = rename(String(value["name"])); + if (value["widget"]) value["widget"] = { name: value["name"] }; + }); + const doc = mint(source, literal); + const op = edit("C", { ["__proto__"]: 0.8, constructor: "new.safetensors" }); + expect(applyOps(doc, [remove(["B"]), op], literal).outcomes.map((result) => result.outcome)).toEqual(["applied", "applied"]); + const result = project(doc, literal); + expect(result.nodes[0]!["widgets_values_named"]).toMatchObject({ "loras.1.__proto__": 0.8, "loras.1.constructor": "new.safetensors" }); + expect(result.nodes[0]!.inputs![2]).toMatchObject({ name: "loras.1.__proto__", link: 23 }); + const fork = new Y.Doc(); Y.applyUpdate(fork, Y.encodeStateAsUpdate(doc)); + expect(canonicalize(project(fork, literal))).toEqual(canonicalize(result)); + fork.destroy(); + doc.destroy(); + }); + + it("resolves promoted values by proxy order when it differs from input-port order", () => { + const source = promotedWorkflow(false); + source.nodes[0]!.widgets_values = [0.6, 0.4, 0.5]; + source.nodes[0]!["properties"] = { proxyWidgets: [["1", "loras.2.strength"], ["1", "loras.0.strength"], ["1", "loras.1.strength"]] }; + const doc = mint(source, catalog); + const ops = [{ ...edit("C", { strength: 0.9 }, 8), path: ["9"], host_path: ["9"], host_incarnation: "0" }, { ...remove(["B"]), path: ["9"] }] as Op[]; + expect(applyOps(doc, ops, catalog).outcomes.map((result) => result.outcome)).toEqual(["applied", "applied"]); + expect(project(doc, catalog).nodes.find((node) => node.id === 9)).toMatchObject({ widgets_values: [0.9, 0.4], properties: { proxyWidgets: [["1", "loras.1.strength"], ["1", "loras.0.strength"]] } }); + doc.destroy(); + }); + + it("refuses encoded anchor cycles even when they have no reachable root", () => { + const doc = mint(workflow(), catalog); + applyOps(doc, [edit("C", { strength: 0.9 })], catalog); + const node = doc.getMap("nodes").get("1") as Y.Map; + const group = (node.get("__dynamic_group_state") as Y.Map>).get("loras")!; + const records = group.get("records") as Y.Map>; + records.set("A", { ...records.get("A"), after: "C" }); + const fork = new Y.Doc(); Y.applyUpdate(fork, Y.encodeStateAsUpdate(doc)); + expect(() => readGraph(fork)).toThrow(/cyclic row anchors/); + fork.destroy(); doc.destroy(); + }); + + it("refuses unsupported self-described promoted-host layouts before structural writes", () => { + const source = promotedWorkflow(false); + source.nodes[0]!["widgets_values_form"] = { order: ["loras.0.strength", "loras.1.strength", "loras.2.strength"] }; + const initial = mint(source, catalog); + expect(project(initial, catalog).nodes[0]!.widgets_values).toEqual([0.4, 0.5, 0.6]); + initial.destroy(); + assertRejectedWithoutMutation(source, { ...remove(["B"]), path: ["9"] } as Op, "malformed_op", catalog); + }); + + it.each([false, true])("materializes a losing Autogrow request without moving the winning row=%s link", (row) => { + const source = workflow(true); + if (!row) delete source.nodes[0]!["properties"]; + source.nodes.push({ id: 200, type: "FloatLiteral", widgets_values: [0], inputs: [{ name: "value", type: "FLOAT", link: null }] }); + const seed = mint(source, catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const grown: Op = { ...env(9), op: "connect", from_node: 103, from_slot: 0, to_node: 200, link_id: 41, link_type: "FLOAT", grow: { name: "values.value0", type: "FLOAT" } }; + const low: Op = { ...grown, ...env(7), link_id: 31, grow: { name: "values.value1", type: "FLOAT" } }; + const high: Op = row ? connect("C", 8) : { ...env(8), op: "connect", from_node: 103, from_slot: 0, to_node: 1, to_slot: 3, link_id: 31, link_type: "FLOAT" }; + for (const order of [[grown, low, high], [grown, high, low]]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + const result = project(doc, catalog); + expect(result.nodes.find((node) => node.id === 200)!.inputs).toEqual([ + { name: "value", type: "FLOAT", link: null }, + { name: "values.value1", type: "FLOAT", link: null, grow_id: 31 }, + { name: "values.value0", type: "FLOAT", link: 41, grow_id: 41 }, + ]); + expect(result.links).toContainEqual([31, 103, 0, 1, 3, "FLOAT"]); + expect(result.links).toContainEqual([41, 103, 0, 200, 2, "FLOAT"]); + doc.destroy(); + } + seed.destroy(); + }); + + it("uses the existing widget-key escaping for reserved-looking controller names", () => { + const name = "\u0000widget-occurrence:loras"; + const source = workflow(); + const escaped = structuredClone(catalog); + const entry = escaped.types["CompositeDynamicGroup"]!; + entry.widget_order = entry.widget_order.map((field) => field === "loras" ? name : field); + entry.dynamic_groups![name] = entry.dynamic_groups!["loras"]!; + delete entry.dynamic_groups!["loras"]; + const node = source.nodes[0]!; + node.widgets_values = Object.fromEntries(Object.entries(node.widgets_values as Record).map(([field, value]) => [field.replace(/^loras/, name), value])); + node["widgets_values_named"] = structuredClone(node.widgets_values); + node["properties"] = { dynamicGroupRows: { [name]: ["A", "B", "C"], weights: ["W"] } }; + node.inputs = []; + const doc = mint(source, escaped); + const ops = [{ ...remove(["B"]), group: name }, { ...edit("C", { strength: 0.9 }), group: name }] as Op[]; + expect(applyOps(doc, ops, escaped).outcomes.map((result) => result.outcome)).toEqual(["applied", "applied"]); + expect(project(doc, escaped).nodes[0]!["widgets_values_named"]).toMatchObject({ [name]: 2, [`${name}.1.strength`]: 0.9 }); + const fork = new Y.Doc(); Y.applyUpdate(fork, Y.encodeStateAsUpdate(doc)); + expect(canonicalize(project(fork, escaped))).toEqual(canonicalize(project(doc, escaped))); + fork.destroy(); doc.destroy(); + }); + + it("owns interior link identity by canonical definition rather than its instance-route spelling", () => { + const source = promotedWorkflow(false); + const definition = source.definitions!.subgraphs![0] as Record; + (definition["nodes"] as unknown[]).push({ id: 103, type: "FloatLiteral", inputs: [], outputs: [{ name: "FLOAT", type: "FLOAT", links: [] }], widgets_values: [0.3] }); + const seed = mint(source, catalog); + const bytes = Y.encodeStateAsUpdate(seed); + const low = { ...connect("A", 7), path: ["9"] } as Op; + const high = { ...connect("C", 8), path: ["inner-definition"] } as Op; + for (const order of [[low, high], [high, low]]) { + const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); + expect(applyOps(doc, order, catalog).outcomes.every((result) => result.outcome !== "rejected")).toBe(true); + const inner = project(doc, catalog).definitions!.subgraphs![0] as Record; + expect(inner["links"]).toEqual(expect.arrayContaining([{ id: 31, origin_id: 103, origin_slot: 0, target_id: 1, target_slot: 2, type: "FLOAT" }])); + doc.destroy(); + } + seed.destroy(); + }); + + it("does not restore an old row link into an activated new target lifetime", () => { + const source = workflow(true); + const doc = mint(source, catalog); + const node = structuredClone(source.nodes[0]!); + node.inputs!.forEach((slot) => { (slot as Record)["link"] = null; }); + const producer = source.nodes.find((candidate) => candidate.id === 103)!; + const added = env(10); + const ops: Op[] = [connect("C"), + { ...env(9), op: "delete_node", node_id: 1, removed_links: [] }, + { ...added, op: "add_node", node_id: 1, node_incarnation: added.op_id, class_type: "CompositeDynamicGroup", pos: [0, 0], node }, + { ...edit("C", { enabled: true }, 11), node_incarnation: added.op_id } as Op, + { ...env(12), op: "delete_node", node_id: 103, removed_links: [] }, + { ...env(13), op: "add_node", node_id: 103, class_type: "FloatLiteral", pos: [0, 0], node: producer }, + ]; + const result = applyOps(doc, ops, catalog); + expect(result.outcomes.every((outcome) => outcome.outcome !== "rejected")).toBe(true); + expect(result.outcomes[3]?.outcome).toBe("applied"); + expect(doc.getMap("links").has("31")).toBe(false); + expect(project(doc, catalog).links.some((link) => (link as unknown[])[0] === 31)).toBe(false); + expect(target(doc).inputs![3]).toMatchObject({ link: null }); + doc.destroy(); + }); +}); diff --git a/test/clock.test.ts b/test/clock.test.ts index dfefc15..dc100df 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, 5, 7])("refuses unsupported schema %s without migration or reservation", async (version) => { + it.each([undefined, 1, 2, 3, 4, 5, 6, 8])("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 ?? 6)).toThrow(/schema/); + expect(() => migrate(doc, version ?? 7)).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/convergence.test.ts b/test/convergence.test.ts index db52f7a..7d5713e 100644 --- a/test/convergence.test.ts +++ b/test/convergence.test.ts @@ -66,6 +66,13 @@ function touchedNodes(op: WireOp): string[] { return []; case "define_subgraph": return [String(op.subgraph_id)]; + case "dynamic_group_connect": + return [String(op.from_node), String(op.path?.[0] ?? op.node_id)]; + case "dynamic_group_insert_rows": + case "dynamic_group_set_row": + case "dynamic_group_delete_rows": + case "dynamic_group_disconnect": + return [String(op.path?.[0] ?? op.node_id)]; default: return assertNever(op, "convergence.touchedNodes"); } diff --git a/test/doc-mint-mutation-survivors.test.ts b/test/doc-mint-mutation-survivors.test.ts index 04a77c7..46c838f 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(6); + expect(doc.getMap("meta").get("schema_version")).toBe(7); // 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 index 42dd149..587ba16 100644 --- a/test/dynamic-group-row-identity.test.ts +++ b/test/dynamic-group-row-identity.test.ts @@ -13,6 +13,8 @@ const fixture = JSON.parse(readFileSync(new URL("./fixtures/dynamic-group-compos }; const { catalog } = fixture; const ids = { loras: ["row-a", "row-c"], weights: ["row-a"] }; +const rowEdit: Op = { op: "dynamic_group_set_row", op_id: fixture.op.op_id, actor: fixture.op.actor, stamp: fixture.op.stamp, base_version: fixture.op.base_version, + node_id: 1, node_incarnation: "0", group: "weights", row_id: "row-a", values: { weight: 0.9 } }; function workflow(shape: "array" | "object" | "declared" = "array"): WorkflowJSON { const result = structuredClone(shape === "declared" ? fixture.explicit_form_workflow : fixture.workflow); @@ -62,7 +64,7 @@ describe("DynamicGroup row identity reader", () => { 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 }; + const op: Op = { ...rowEdit, path: ["9"] }; 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 }, @@ -222,7 +224,7 @@ describe("DynamicGroup row identity reader", () => { 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]]) { + for (const ops of [[rowEdit, count], [count, rowEdit]]) { const doc = new Y.Doc(); Y.applyUpdate(doc, bytes); expect(applyOps(doc, ops, catalog).outcomes.map((outcome) => outcome.outcome)).toEqual(["applied", "applied"]); @@ -232,10 +234,10 @@ describe("DynamicGroup row identity reader", () => { seed.destroy(); }); - it("uses schema v6 and refuses an old document without relabelling", () => { - expect(SCHEMA_VERSION).toBe(6); + it("uses schema v7 and refuses an old document without relabelling", () => { + expect(SCHEMA_VERSION).toBe(7); const doc = mint(workflow(), catalog); - doc.getMap("meta").set("schema_version", 5); + doc.getMap("meta").set("schema_version", 6); const before = Y.encodeStateAsUpdate(doc); expect(() => project(doc, catalog)).toThrow(SchemaVersionError); expect(() => readGraph(doc)).toThrow(SchemaVersionError); diff --git a/test/link-state-foundation.test.ts b/test/link-state-foundation.test.ts index 86c728d..bb1314f 100644 --- a/test/link-state-foundation.test.ts +++ b/test/link-state-foundation.test.ts @@ -25,10 +25,10 @@ function workflow(): WorkflowJSON { }; } -describe("schema v6 retains first-class imported link state", () => { +describe("schema v7 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(6); + expect(SCHEMA_VERSION).toBe(7); 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/permutation/full-op-pool.permutation.test.ts b/test/permutation/full-op-pool.permutation.test.ts index 44e5440..c64935c 100644 --- a/test/permutation/full-op-pool.permutation.test.ts +++ b/test/permutation/full-op-pool.permutation.test.ts @@ -7,7 +7,7 @@ * equivalence classes, both arrival orders, and both batch boundaries. * Longer streams are fixed-seed fast-check samples with shrinking * left enabled. The default tier rotates actor/stamp classes across all - * 64 kind pairs × 8 states (2,048 executions), plus 128 seeded streams (256 executions). + * 196 kind pairs × 8 states (6,272 executions), plus 128 seeded streams (256 executions). * Every frozen kind still meets every state, both orders, and both batch modes. * * Amendment A6 / docs/decisions/EXCEPTIONS.md and schema §2.5 item 2 are the @@ -54,8 +54,8 @@ const PRECONDITIONS = [ "promoted-or-autogrow", ] as const; // Keep the full pre-separation domain in the dedicated exhaustive CI job: -// 81 kind pairs × 8 states × 2 actor pairs × 4 stamp pairs × 2 orders × 2 batches. -const PAIR_EXECUTIONS = 20_736; +// 196 kind pairs × 8 states × 2 actor pairs × 4 stamp pairs × 2 orders × 2 batches. +const PAIR_EXECUTIONS = 50_176; const SAMPLED_RUNS = 1_696; const SAMPLE_SEED = 0x4f70504; @@ -69,6 +69,7 @@ const catalog: WidgetCatalog = { Source: { widget_order: ["value"] }, Sink: { widget_order: ["count"] }, Aux: { widget_order: ["value"] }, + Rows: { widget_order: ["rows"], dynamic_groups: { rows: { min: 0, max: 4, widgets: ["value"], defaults: { value: 0 } } } }, }, }; @@ -105,6 +106,7 @@ function base(precondition: Precondition): WorkflowJSON { node(30, "Aux", [], [], [2]), node(40, "Aux", [], [], [3]), node(57, DEF, [{ name: "width", type: "INT", link: null, widget: { name: "width" } }], [], [640]), + { id: 60, type: "Rows", inputs: [{ name: "rows.0.value", type: "VALUE", widget: { name: "rows.0.value" }, link: null }], outputs: [], widgets_values: { rows: 1, "rows.0.value": 0 }, properties: { dynamicGroupRows: { rows: ["row"] } } }, ]; if (precondition === "source-missing") nodes.splice(nodes.findIndex((candidate) => candidate.id === 10), 1); if (precondition === "destination-missing") nodes.splice(nodes.findIndex((candidate) => candidate.id === 20), 1); @@ -250,6 +252,16 @@ function makeOp( return { ...env, op: "insert_workflow", workflow: { nodes: [node(140 + serial, "Aux", [], [], [value])], links: [] } }; case "reset_doc": return { ...env, op: "reset_doc", workflow: { nodes: [], links: [] } }; + case "dynamic_group_insert_rows": + return { ...env, op: kind, node_id: 60, node_incarnation: "0", group: "rows", after_row_id: "row", rows: [{ value }] }; + case "dynamic_group_set_row": + return { ...env, op: kind, node_id: 60, node_incarnation: "0", group: "rows", row_id: "row", values: { value } }; + case "dynamic_group_delete_rows": + return { ...env, op: kind, node_id: 60, node_incarnation: "0", group: "rows", row_ids: ["row"] }; + case "dynamic_group_connect": + return { ...env, op: kind, node_id: 60, node_incarnation: "0", group: "rows", row_id: "row", field: "value", from_node: 10, from_slot: 0, link_id: 100 + side, link_type: "VALUE", input_type: "VALUE" }; + case "dynamic_group_disconnect": + return { ...env, op: kind, node_id: 60, node_incarnation: "0", group: "rows", row_id: "row", field: "value" }; } } @@ -383,10 +395,10 @@ function normalizeSourceDeleteAutogrow(workflow: WorkflowJSON, ops: readonly Wir function removedLinkAliases(ops: readonly WireOp[]): Set { const aliases = new Set(); - for (const connect of ops.filter((op): op is Extract => - op.op === "connect" && op.grow?.promoted === true)) { + for (const connect of ops.filter((op): op is Extract => + op.op === "dynamic_group_connect" || (op.op === "connect" && op.grow?.promoted === true))) { for (const deletion of ops.filter((op): op is Extract => op.op === "delete_node")) { - if (String(deletion.node_id) !== String(connect.to_node) && + if (String(deletion.node_id) !== String(connect.op === "dynamic_group_connect" ? connect.node_id : connect.to_node) && deletion.removed_links.some((linkId) => String(linkId) === String(connect.link_id))) { aliases.add(String(connect.link_id)); } @@ -508,8 +520,8 @@ const PERMUTATION_TIERS: Array<[ expectedPairs: number, sampledRuns: number, ]> = [ - // Scales as (frozen kinds)² × 32; nine kinds since `set_node_field`. - ["representative", [], 15_000, 2_592, 128], + // Scales as (frozen kinds)² × 32; fourteen implemented kinds. + ["representative", [], 15_000, 6_272, 128], ["exhaustive", ["exhaustive"], 900_000, PAIR_EXECUTIONS, SAMPLED_RUNS], ]; diff --git a/test/readonly-surface.test.ts b/test/readonly-surface.test.ts index 87f8070..3ad6814 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(6); + expect(meta["schema_version"]).toBe(7); 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(7)], + ["newer than this package", () => docWithSchemaVersion(8)], ["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(6); + expect(readMeta(doc)["schema_version"]).toBe(7); 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", 7); + metaMap(doc).set("schema_version", 8); expect(() => project(doc, catalog)).toThrow(SchemaVersionError); expect(() => readGraph(doc)).toThrow(SchemaVersionError); expect(() => readStamps(doc)).toThrow(SchemaVersionError); @@ -751,6 +751,10 @@ describe("read-only surface — classification", () => { * is a read, to bring it under the no-live-handle proofs above. */ const OP_LAYER_AND_TYPES: readonly string[] = [ + "admitDynamicGroupRowOp", + "dynamicGroupRowId", + "DYNAMIC_GROUP_STATE_KEY", + "DYNAMIC_GROUP_SLOT_KEY", "applyOps", "inspectOps", "project", diff --git a/test/schema.test.ts b/test/schema.test.ts index ff6f353..e988c16 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 6", () => { - expect(SCHEMA_VERSION).toBe(6); + it("pins SCHEMA_VERSION at 7", () => { + expect(SCHEMA_VERSION).toBe(7); }); - it("initDoc creates the schema v6 layout with lazy clock reservations", () => { + it("initDoc creates the schema v7 layout with lazy clock reservations", () => { const doc = new Y.Doc(); initDoc(doc, "object_info@2026-08-01"); expect(nodesMap(doc)).toBeInstanceOf(Y.Map);