From 6c3614dea97f35026456a967307c1d194fbf893d Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 18:45:11 -0700 Subject: [PATCH 01/11] feat(cmp): add insert_workflow op (V1.5 agent subgraph TDD) TDD: https://www.notion.so/3d16d73d365081719b85ed515af98276 Ported from standalone PR: https://github.com/Comfy-Org/comfy-multi-player/pull/183 --- packages/comfy-multi-player/CHANGELOG.md | 8 + packages/comfy-multi-player/README.md | 7 +- .../comfy-multi-player/docs/INVARIANTS.md | 4 +- packages/comfy-multi-player/docs/ROADMAP.md | 4 + .../docs/api-contract-proposal.md | 8 + .../decisions/ADR-022-insert-workflow-op.md | 42 ++ .../docs/multiplayer-schema.md | 26 ++ .../scripts/check-import-graph.mjs | 2 +- packages/comfy-multi-player/src/applier.ts | 220 ++++++++- packages/comfy-multi-player/src/doc.ts | 10 +- packages/comfy-multi-player/src/index.ts | 3 +- packages/comfy-multi-player/src/remap.ts | 148 ++++++ packages/comfy-multi-player/src/stamps.ts | 8 +- packages/comfy-multi-player/src/types.ts | 38 +- .../test/batch-policy.test.ts | 4 +- .../test/convergence.test.ts | 2 + .../test/full-op-pool.permutation.test.ts | 2 + .../test/insert-workflow.test.ts | 433 ++++++++++++++++++ .../test/ka4-rejection-byte-identity.test.ts | 27 ++ .../test/readonly-surface.test.ts | 1 + .../test/types/invalid-states.negative.ts | 8 + 21 files changed, 986 insertions(+), 19 deletions(-) create mode 100644 packages/comfy-multi-player/docs/decisions/ADR-022-insert-workflow-op.md create mode 100644 packages/comfy-multi-player/src/remap.ts create mode 100644 packages/comfy-multi-player/test/insert-workflow.test.ts diff --git a/packages/comfy-multi-player/CHANGELOG.md b/packages/comfy-multi-player/CHANGELOG.md index 425f5b6236d..233185b0efc 100644 --- a/packages/comfy-multi-player/CHANGELOG.md +++ b/packages/comfy-multi-player/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to `@comfyorg/comfy-multi-player` are documented in this fil The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package uses semantic versioning. +## Unreleased + +### Added + +- Added the standalone `insert_workflow` op and `remapWorkflowIds` helper for + deterministic, collision-safe workflow-template insertion, including + deterministic whole-tree id remapping keyed by the operation envelope id. + ## 0.2.0 - 2026-08-30 ### Changed diff --git a/packages/comfy-multi-player/README.md b/packages/comfy-multi-player/README.md index f92b640e6c4..1b316eb9703 100644 --- a/packages/comfy-multi-player/README.md +++ b/packages/comfy-multi-player/README.md @@ -334,7 +334,7 @@ Every op carries the same envelope, minted by its creator before dispatch: } ``` -Six kinds, frozen: +Seven kinds, frozen: | Kind | Payload beyond the envelope | Batchable (authoring) | |---|---|---| @@ -345,6 +345,7 @@ Six kinds, frozen: | `set_widget` | `node_id`, `widget` (name, never index), `value`, optional `old`; an interior write adds `path` AND `inner_widget` together (`InteriorSetWidgetOp`); a promoted HOST write adds `promoted: {value_index, instance_path, host_widgets_values}` instead — a positional write into a subgraph instance's opaque array (schema Amendment A15) | yes | | `delete_node` | `node_id`, `removed_links` | yes | | `clear` | `removed_nodes` | no | +| `insert_workflow` | `workflow` containing top-level `nodes`, `links`, and optional `definitions.subgraphs`; ids must already be remapped collision-free by the minter | no | | `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 @@ -355,7 +356,7 @@ Compile-time assertions in `src/types.ts` pin that `FROZEN_OPS` is exactly is exactly `WireOp["op"]`, and that `BATCHABLE_OPS ⊆ FROZEN_OPS`, so the lists and the unions cannot drift apart silently. -**`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the six kinds it +**`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the seven kinds it can actually apply. `WireOp` is `Op` plus the deferred kinds a conforming peer may legally put on the wire, and it is what `ApplyFailure.op` and the stamp helpers take: a rejected `reset_doc` really does land in `failed.op`, so typing @@ -410,7 +411,7 @@ implementation to replay it with no failures. If you are building a submission surface in front of the applier, that admission layer is where `BATCHABLE_OPS` belongs. `test/batch-policy.test.ts` pins all of this. -The normative definition of the op envelope and the six kinds is +The normative definition of the original op envelope and six kinds is `docs/op-vocabulary-v1.md` in [comfy-cli](https://github.com/Comfy-Org/comfy-cli), which mints these ops on the agent side. The `Op` types here mirror those minted shapes field for field; diff --git a/packages/comfy-multi-player/docs/INVARIANTS.md b/packages/comfy-multi-player/docs/INVARIANTS.md index 5f3e51fdc0b..52d50d8ec34 100644 --- a/packages/comfy-multi-player/docs/INVARIANTS.md +++ b/packages/comfy-multi-player/docs/INVARIANTS.md @@ -35,12 +35,12 @@ This is the machine-addressable review log for the package. IDs are stable; do n **Amendment A9 closes three residual write-order holes:** values that clone but cannot be stored by Yjs are refused before `set_widget`, grow, and `add_node` writes; `connect.link_id` must satisfy both Y.Map-value and Y.Array-item domains; and non-iterable `delete_node.removed_links` is refused before the A7 node-presence gate or deletion. **Amendment A10 closes the reference-cycle hole and corrects the shallow write predicate from storability to encodability:** `applyOps` rejects cycles at A8's whole-op depth gate, while the write-site cycle guard independently protects `mint`; top-level `Date` values are refused at the write gate, and `mint` refuses out-of-int64 `BigInt` values because Yjs accepts but does not faithfully encode them. **Amendment A13 classifies every BigInt in an op envelope as `malformed_op` during A8's op-only canonicalization precondition, names its payload path, and therefore rejects before any document write or `op_id` record.** **Amendment A14 shape-validates `connect.link_type` as a string in the op-only precondition, before destination delete-wins or any write; arbitrary and unknown strings remain legal because this is not catalogue membership validation.** **Amendment A11 bounds the remaining breadth and size attack surface:** batches are capped before processing, while A8's whole-envelope canonicalization now caps collection entries and an approximate cost covering strings, keys, binary bytes, containers, and leaves. -The *rejection* half — "a rejected op leaves the doc untouched", stated in the `applyOps` module docstring in `src/applier.ts` and repeated as contract D4 — is swept table-driven in `test/ka4-rejection-byte-identity.test.ts`, one row per reachable rejection code across `add_node`, `set_widget`, `connect`, `connect`+grow, `delete_node`, `clear`, `reset_doc` and the envelope gate, asserting byte-identical `encodeStateAsUpdate` *and* that the `op_id` was not consumed. Completeness is enforced rather than asserted: one test compares the covered codes against `ALL_REJECTION_CODES`, and a second greps `src/applier.ts` for every `new OpRejectedError("…")` so a new code cannot be added without a row. **The four `connect` rejections this used to except are fixed (#34)** and are now ordinary rows in that sweep, asserting byte-identity and `op_id`-preservation like every other code; the block that deliberately asserted the bug is deleted and `KNOWN_KA4_VIOLATIONS` is kept empty so a regression has somewhere to be recorded. +The *rejection* half — "a rejected op leaves the doc untouched", stated in the `applyOps` module docstring in `src/applier.ts` and repeated as contract D4 — is swept table-driven in `test/ka4-rejection-byte-identity.test.ts`, one row per reachable rejection code across `add_node`, `insert_workflow`, `set_widget`, `connect`, `connect`+grow, `delete_node`, `clear`, `reset_doc` and the envelope gate, asserting byte-identical `encodeStateAsUpdate` *and* that the `op_id` was not consumed. Completeness is enforced rather than asserted: one test compares the covered codes against `ALL_REJECTION_CODES`, and a second greps `src/applier.ts` for every `new OpRejectedError("…")` so a new code cannot be added without a row. `insert_workflow` adds collision refusals for nodes and links; both validate before any write. **The four `connect` rejections this used to except are fixed (#34)** and are now ordinary rows in that sweep, asserting byte-identity and `op_id`-preservation like every other code; the block that deliberately asserted the bug is deleted and `KNOWN_KA4_VIOLATIONS` is kept empty so a regression has somewhere to be recorded. ### KA-5 — IDs are collision-free without coordination **Rule:** Use 53-bit random mint; document high-water marks are advisory, never allocators; FE stable IDs must be non-colliding strings. **Why:** Offline peers must create entities without a central allocator. -**Enforced by:** **UNGUARDED — see roadmap**. +**Enforced by:** `insert_workflow` derives scoped node, link, group, and definition ids from the immutable op envelope id plus each original id. It never reads high-water marks or current document state to allocate, so distinct operations remain collision-free and order-independent. General producer randomness remains **UNGUARDED — see roadmap**. ### KA-6 — Raw struct updates flow host → follower one-way only **Rule:** Followers never write the shared doc. diff --git a/packages/comfy-multi-player/docs/ROADMAP.md b/packages/comfy-multi-player/docs/ROADMAP.md index 4c2251185d6..3155088a2b7 100644 --- a/packages/comfy-multi-player/docs/ROADMAP.md +++ b/packages/comfy-multi-player/docs/ROADMAP.md @@ -4,6 +4,10 @@ V1 is an op-based Yjs document applier implemented once in the shared `@comfyorg/comfy-multi-player` TypeScript package. The frontend consumes its workspace source directly; the Node doc-host sidecar consumes an exact npm release built from that same source. Semantic ops are the replication unit; the widget catalog is sha256-pinned and fail-closed in the deployed architecture. +ADR-022 adds the seventh implemented kind, `insert_workflow`, for atomic template insertion. The +applier deterministically remaps whole-tree ids from the operation id, so distinct inserts cannot +collide and exact replay derives the same ids. + ## Guard gaps - ~~**Positive purity assertion (#22):**~~ **CLOSED.** `scripts/check-purity.mjs` asserts directly that the declared and resolved production dependency roots are exactly `{yjs}`, and `scripts/check-import-graph.mjs` asserts the same per source module via `src-runtime-dep-is-yjs-only`. A cross-language parity guard is still only warranted if a second-language implementation is proposed; the preferred policy remains no second implementation (tracked in the separate bullet below). diff --git a/packages/comfy-multi-player/docs/api-contract-proposal.md b/packages/comfy-multi-player/docs/api-contract-proposal.md index 1921b726c1f..f2a5efac1eb 100644 --- a/packages/comfy-multi-player/docs/api-contract-proposal.md +++ b/packages/comfy-multi-player/docs/api-contract-proposal.md @@ -18,6 +18,14 @@ still cheap. That will not stay true. ## Part 1 — decisions to ratify +### D0. Workflow templates insert as one standalone op + +**Accepted by ADR-022.** `insert_workflow` requires `nodes`; `links`, `groups`, and `definitions` +are optional and default to empty. Producers send raw workflows. The applier remaps every carried +id and internal reference deterministically from the op envelope id plus the original id and graph +scope. Different ops therefore cannot collide or depend on arrival order, while exact replay derives +the same ids and is idempotent. The op is stamped and not batchable. + ### D1. Widgets are addressed by name, not by position **Proposal.** A node's widget values live in a map keyed by widget name. The diff --git a/packages/comfy-multi-player/docs/decisions/ADR-022-insert-workflow-op.md b/packages/comfy-multi-player/docs/decisions/ADR-022-insert-workflow-op.md new file mode 100644 index 00000000000..f9a3a52d8bc --- /dev/null +++ b/packages/comfy-multi-player/docs/decisions/ADR-022-insert-workflow-op.md @@ -0,0 +1,42 @@ +# ADR-022: Atomic workflow-template insertion + +- **Status:** Accepted +- **Date:** 2026-09-11 +- **Decider:** Christian +- **Source:** ADR-T8, in-app-agent program TDD (Notion) + +## Context + +Agents and users need to insert a complete workflow template, including subgraph definitions, +without decomposing it into independently observable graph edits. Existing op shapes deliberately +reject definition-bearing payloads and cannot express that transaction safely. + +## Decision + +Add the non-batchable `insert_workflow` op. Its frozen envelope carries one authoritative `workflow` +with required top-level nodes and optional links, groups, and definitions. The applier remaps every +carried node, link, group, and nested-definition id to a deterministic string derived from the op +envelope id, graph scope, id kind, and original id. Producers emit the raw workflow unchanged. + +Internal node/link references and definition-instance types are rewritten to those derived ids. +Distinct insert ops therefore cannot collide, even when they carry the same raw ids; exact replay +derives the same ids and is a byte-identical no-op through the existing `op_id` gate. The operation +is one Yjs transaction and is stamped as its own register. + +## Consequences + +- Template insertion is atomic at the semantic-op boundary and deterministic on replay. +- Producers do not inspect document state or remap ids. +- Definition interiors retain scoped graph namespaces, all derived from the op id. +- Existing op schemas remain closed to definitions. + +## Invariants + +This decision touches KA-1, KA-2, KA-3, KA-4, KA-5, FC-1, FC-3, and FC-4. + +## Glossary + +- **ADR-T8:** the accepted in-app-agent program technical design for workflow insertion. +- **Canonical projection:** stable, key-sorted JSON used as the definition-content identity. +- **Envelope id:** the immutable `op_id` carried by the semantic operation. +- **Producer:** the cloud or CLI caller that emits the raw workflow payload. diff --git a/packages/comfy-multi-player/docs/multiplayer-schema.md b/packages/comfy-multi-player/docs/multiplayer-schema.md index 5c9152da424..5bda9f9f26b 100644 --- a/packages/comfy-multi-player/docs/multiplayer-schema.md +++ b/packages/comfy-multi-player/docs/multiplayer-schema.md @@ -44,6 +44,9 @@ Normative inputs, in precedence order: `fixtures/` (the evidence: three replayable sessions, six LWW vectors, the exported catalog, machine-captured findings). Every DECISION below cites the spike finding that forced it. +3. **ADR-022 / ADR-T8** — the local decision and accepted in-app-agent program + TDD add `insert_workflow` as the seventh implemented op without moving the + pinned comfy-cli vocabulary. --- @@ -2044,3 +2047,26 @@ separate input register still decides whether that identity may occupy the requested destination; losing that gate leaves no tuple or dangling reference. This adds an internal `__stamps` key, not a root-layout change, so `SCHEMA_VERSION` remains 2. + +--- + +## Amendment A19 — 2026-09-11 — atomic workflow-template insertion + +ADR-022 adds the standalone-only `insert_workflow` op. Its payload is one +authoritative workflow containing required top-level `nodes` and optional +`links`, `groups`, and `definitions`. The applier deterministically remaps every +inserted id from the immutable `op_id`, graph scope, id kind, and original id, +then rewrites internal references. Producers emit raw payloads. Distinct ops +cannot collide; exact replay derives the same ids. Duplicate ids within one raw +payload remain collision errors. Malformed link tuples are `malformed_op`. + +Definition ids and every nested definition-interior graph id are remapped in +scoped namespaces. Definition-instance `type` values are rewritten with them, +so a consumer definition id is never used as a live id and no live-definition +conflict path remains. + +The whole merge occurs in one Yjs transaction and claims the +`("insert_workflow", op_id)` stamp target. Exact replay is stopped by the +existing applied-op gate and is byte-identical. This adds graph content but no +new root or node-map layout, so `SCHEMA_VERSION` remains 2. Other op payloads +remain closed to definition-bearing fields. diff --git a/packages/comfy-multi-player/scripts/check-import-graph.mjs b/packages/comfy-multi-player/scripts/check-import-graph.mjs index 28993b42007..944114ccb5e 100644 --- a/packages/comfy-multi-player/scripts/check-import-graph.mjs +++ b/packages/comfy-multi-player/scripts/check-import-graph.mjs @@ -59,7 +59,7 @@ const root = process.env.IMPORT_GRAPH_ROOT || dirname(dirname(fileURLToPath(impo * not one per change. See `.agents/checks/import-graph.md` and the config's own * "NO includeOnly" comment. */ -const MIN_MODULES = Number(process.env.IMPORT_GRAPH_MIN_MODULES ?? 10); +const MIN_MODULES = Number(process.env.IMPORT_GRAPH_MIN_MODULES ?? 11); const cli = join(root, "node_modules", ".bin", "depcruise"); const run = spawnSync(cli, ["--output-type", "json", "src"], { diff --git a/packages/comfy-multi-player/src/applier.ts b/packages/comfy-multi-player/src/applier.ts index 58d5ed8b80b..e544d1501da 100644 --- a/packages/comfy-multi-player/src/applier.ts +++ b/packages/comfy-multi-player/src/applier.ts @@ -86,6 +86,7 @@ import { appliedMap, apush, arrayItemRefusal, + cloneForMap, countDefinitionInstances, createNodeMap, definitionsMap, @@ -100,16 +101,17 @@ import { stampsMap, widgetStorageOf, } from "./doc.js"; +import { remapInsertedWorkflowIds } from "./remap.js"; import { sha256Hex } from "./digest.js"; import { CMP_EVENT_SCHEMA_VERSION, emitCmpEvent, type CmpCallContext } from "./events.js"; +import { mint, mintDefinition } from "./mint.js"; +import { project, projectDefinition } from "./project.js"; import { MAX_OP_COST, MAX_OPS_PER_BATCH, MAX_PAYLOAD_DEPTH, opBoundsRefusal, } from "./limits.js"; -import { mintDefinition } from "./mint.js"; -import { projectDefinition } from "./project.js"; import { codePointCompare, compareStampKeys, stampKey, stampTargetKey, widgetTargetKey } from "./stamps.js"; import { DEFERRED_OPS, @@ -126,6 +128,7 @@ import { type GrowConnectOp, type GrowSpec, type InteriorSetWidgetOp, + type InsertWorkflowOp, type Op, type SetWidgetOp, type StampKey, @@ -443,9 +446,11 @@ function dispatch(doc: Y.Doc, op: Op, catalog?: WidgetCatalog): SuccessfulOutcom return applyClear(doc, op); case "define_subgraph": return applyDefineSubgraph(doc, op, catalog); + case "insert_workflow": + return applyInsertWorkflow(doc, op, catalog); default: // Exhaustiveness guard (issue #21): with every `Op` member cased above, - // `op` is `never` here. Add a sixth IMPLEMENTED kind to `Op` and this + // `op` is `never` here. Add an eighth IMPLEMENTED kind to `Op` and this // line stops compiling until it gets a `case`. // // Issue #17 removed the `case "reset_doc"` that used to sit here. It was @@ -617,8 +622,8 @@ function assertDefinitionIdsAvailable( doc: Y.Doc, definition: Record, excludedRootId?: string, + submitted = new Set(), ): void { - const submitted = new Set(); const visit = (candidate: Record, path: string): void => { const id = String(candidate.id); if (submitted.has(id)) throw new OpRejectedError("malformed_op", `define_subgraph: duplicate definition id '${id}' at ${path}`); @@ -745,6 +750,213 @@ function validateSerializableValue(value: unknown, path: string): void { throw new OpRejectedError("malformed_op", `define_subgraph: ${path} is not JSON-serializable`); } +// --------------------------------------------------------------------------- +// insert_workflow +// --------------------------------------------------------------------------- + +function canonicalJson(value: unknown): string { + if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; + if (typeof value === "object" && value !== null) { + return `{${Object.keys(value).sort(codePointCompare).map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record)[key])}`).join(",")}}`; + } + return JSON.stringify(value); +} + +function numericId(value: unknown): number | undefined { + if (typeof value === "number" && Number.isFinite(value)) return value; + if (typeof value === "string" && /^[0-9]+$/.test(value)) return parseInt(value, 10); + return undefined; +} + +function scrubPrivateKeys(value: unknown): unknown { + if (Array.isArray(value)) return value.map(scrubPrivateKeys); + if (typeof value !== "object" || value === null) return value; + const clean: Record = {}; + for (const [key, child] of Object.entries(value)) { + if (!key.startsWith("__")) clean[key] = scrubPrivateKeys(child); + } + return clean; +} + +function definitionId(value: unknown): string | undefined { + if (typeof value === "string" && value.length > 0) return value; + if (typeof value === "number" && Number.isFinite(value)) return String(value); + return undefined; +} + +function validateDefinitionInputs(subgraphs: unknown[]): void { + for (const candidate of subgraphs) { + if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { + throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition must be an object"); + } + const sg = candidate as Record; + const id = definitionId(sg["id"]); + if (id === undefined) { + throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition requires a valid id"); + } + const nested = (sg["definitions"] as { subgraphs?: unknown } | undefined)?.subgraphs; + if (nested !== undefined && !Array.isArray(nested)) { + throw new OpRejectedError("malformed_op", "insert_workflow: nested definitions.subgraphs must be an array"); + } + if (Array.isArray(nested)) validateDefinitionInputs(nested); + } +} + +function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetCatalog): SuccessfulOutcome { + const workflow = scrubPrivateKeys(op.workflow) as unknown; + if (typeof workflow !== "object" || workflow === null || Array.isArray(workflow)) { + throw new OpRejectedError("malformed_op", "insert_workflow: workflow must be an object"); + } + let wf = workflow as Record; + if (!Array.isArray(wf["nodes"]) || (wf["links"] !== undefined && !Array.isArray(wf["links"]))) { + throw new OpRejectedError("malformed_op", "insert_workflow: nodes and links must be arrays"); + } + const definitions = wf["definitions"]; + if (definitions !== undefined && (typeof definitions !== "object" || definitions === null || Array.isArray(definitions))) { + throw new OpRejectedError("malformed_op", "insert_workflow: definitions must be an object"); + } + const subgraphs = (definitions as { subgraphs?: unknown } | undefined)?.subgraphs; + if (subgraphs !== undefined && !Array.isArray(subgraphs)) { + throw new OpRejectedError("malformed_op", "insert_workflow: definitions.subgraphs must be an array"); + } + if (wf["groups"] !== undefined && !Array.isArray(wf["groups"])) { + throw new OpRejectedError("malformed_op", "insert_workflow: groups must be an array"); + } + validateDefinitionInputs((subgraphs as unknown[] | undefined) ?? []); + wf = remapInsertedWorkflowIds(wf as unknown as import("./types.js").WorkflowJSON, op.op_id) as unknown as Record; + const remappedDefinitions = wf["definitions"] as { subgraphs?: unknown[] } | undefined; + const remappedSubgraphs = remappedDefinitions?.subgraphs ?? []; + + const nodes = nodesMap(doc); + const links = linksMap(doc); + const stamps = stampsMap(doc); + const stamp = stampKey(op); + const seenNodes = new Set(); + for (const candidate of wf["nodes"] as unknown[]) { + if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { + throw new OpRejectedError("invalid_node_payload", "insert_workflow: every node must be an object"); + } + const node = candidate as { id?: unknown; type?: unknown }; + if (node.id === undefined || typeof node.type !== "string" || node.type.length === 0) { + throw new OpRejectedError("invalid_node_payload", "insert_workflow: every node requires id and type"); + } + const key = String(node.id); + if (seenNodes.has(key)) { + throw new OpRejectedError("node_id_collision", `insert_workflow: node id '${key}' collides`); + } + const existing = nodes.get(key); + if (existing) { + const incumbent = stamps.get(JSON.stringify(["insert_workflow_node", key])) as StampKey | undefined; + if (incumbent === undefined) { + throw new OpRejectedError("node_id_collision", `insert_workflow: node id '${key}' collides`); + } + if (compareStampKeys(stamp, incumbent) <= 0) return "lww-dropped"; + } + seenNodes.add(key); + } + const seenLinks = new Set(); + const linkWrites: unknown[][] = []; + for (const candidate of (wf["links"] as unknown[] | undefined) ?? []) { + if (!Array.isArray(candidate) || candidate[0] === undefined || candidate[1] === undefined || candidate[3] === undefined) { + throw new OpRejectedError("malformed_op", "insert_workflow: every link must be a tuple with an id and two endpoints"); + } + const key = String(candidate[0]); + if (seenLinks.has(key)) { + throw new OpRejectedError("link_id_collision", `insert_workflow: link id '${key}' collides`); + } + if (links.has(key)) { + const incumbent = stamps.get(JSON.stringify(["insert_workflow_link", key])) as StampKey | undefined; + if (incumbent === undefined) { + throw new OpRejectedError("link_id_collision", `insert_workflow: link id '${key}' collides`); + } + if (compareStampKeys(stamp, incumbent) <= 0) return "lww-dropped"; + } + seenLinks.add(key); + const source = String(candidate[1]); + const target = String(candidate[3]); + if ((!nodes.has(source) && !seenNodes.has(source)) || (!nodes.has(target) && !seenNodes.has(target))) { + continue; + } + linkWrites.push(candidate); + } + + const targetKey = stampTargetKey(op); + const prior = stamps.get(targetKey) as StampKey | undefined; + if (prior != null && compareStampKeys(stamp, prior) <= 0) return "lww-dropped"; + + if (remappedSubgraphs.length > 0 && !catalog) { + throw new OpRejectedError("catalog_required", "insert_workflow: the pinned catalog is required to encode definitions"); + } + const cat = catalog ?? { types: {} }; + const defs = definitionsMap(doc); + const submittedDefinitionIds = new Set(); + const definitionWrites: Array<[string, Y.Map, string]> = []; + for (const candidate of remappedSubgraphs) { + if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { + throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition must be an object"); + } + const sg = candidate as Record; + const id = definitionId(sg["id"])!; + validateSubgraphDefinition(sg, "workflow.definitions.subgraphs"); + validateDefinitionWidgets(sg, cat); + assertDefinitionIdsAvailable(doc, sg, undefined, submittedDefinitionIds); + const digest = sha256Hex(canonicalOp(sg as unknown as Op)); + definitionWrites.push([id, mintDefinition(sg, cat), digest]); + } + + const nodeWrites: Array<[string, unknown, Y.Map]> = []; + for (const candidate of wf["nodes"] as import("./types.js").WorkflowNode[]) { + const node = structuredClone(candidate); + const wv = node.widgets_values; + const entry = catalogEntry(catalog, node.type); + if (!catalog && Array.isArray(wv) && wv.length > 0) { + throw new OpRejectedError("catalog_required", `insert_workflow(${node.type}): positional widgets_values needs a catalog`); + } + rejectUnprojectableWidgets(node.type, wv, entry); + try { + nodeWrites.push([String(node.id), node.id, createNodeMap(node, entry?.widget_order)]); + } catch (err) { + throw new OpRejectedError("invalid_node_payload", `insert_workflow(${node.type}): ${err instanceof Error ? err.message : String(err)}`); + } + } + + for (const [id, definition, digest] of definitionWrites) { + mset(defs, id, definition); + setDefinitionDigest(doc, id, digest); + } + for (const link of linkWrites) { + const key = String((link as unknown[])[0]); + mset(links, key, cloneForMap(link, "insert_workflow: link")); + mset(stamps, JSON.stringify(["insert_workflow_link", key]), stamp); + } + for (const [key, id, nodeMap] of nodeWrites) { + clearObsoleteWidgetStamps(stamps, key); + mset(nodeMap, NODE_INCARNATION_KEY, `${op.op_id}:${key}`); + mset(nodes, key, nodeMap); + mset(stamps, JSON.stringify(["insert_workflow_node", key]), stamp); + mset(stamps, targetKey, stamp); + reconcileNodeLinkRefs(doc, id, nodeMap); + } + if (nodeWrites.length === 0) mset(stamps, targetKey, stamp); + + const meta = metaMap(doc); + if (Array.isArray(wf["groups"])) { + const currentGroups = Array.isArray(meta.get("groups")) ? meta.get("groups") as unknown[] : []; + const merged = new Map(); + for (const group of [...currentGroups, ...wf["groups"]]) merged.set(canonicalJson(group), group); + mset(meta, "groups", [...merged.entries()].sort(([a], [b]) => codePointCompare(a, b)).map(([, group]) => group)); + } + const currentNode = numericId(meta.get("last_node_id")) ?? 0; + const maxNode = Math.max(currentNode, ...nodeWrites.map(([, id]) => numericId(id) ?? currentNode)); + if (maxNode > currentNode) mset(meta, "last_node_id", maxNode); + const currentLink = numericId(meta.get("last_link_id")) ?? 0; + const maxLink = Math.max(currentLink, ...linkWrites.map((link) => numericId(link[0]) ?? currentLink)); + if (maxLink > currentLink) mset(meta, "last_link_id", maxLink); + return nodeWrites.length > 0 || linkWrites.length > 0 || definitionWrites.length > 0 || ((wf["groups"] as unknown[] | undefined)?.length ?? 0) > 0 + ? "applied" + : "no-op"; +} + // --------------------------------------------------------------------------- // add_node // --------------------------------------------------------------------------- diff --git a/packages/comfy-multi-player/src/doc.ts b/packages/comfy-multi-player/src/doc.ts index f0171eeeb2c..8def35dbab9 100644 --- a/packages/comfy-multi-player/src/doc.ts +++ b/packages/comfy-multi-player/src/doc.ts @@ -911,13 +911,19 @@ export function countDefinitionInstances(doc: Y.Doc, defId: string, catalog?: Wi } if (aliases.has(String(node.get("type") ?? ""))) count++; }); - definitionsMap(doc).forEach((dm) => { + const visit = (dm: Y.Map): void => { const inner = dm.get("nodes"); if (inner instanceof Y.Map) { inner.forEach((node: unknown) => { if (node instanceof Y.Map && aliases.has(String(node.get("type") ?? ""))) count++; }); } - }); + const container = dm.get("definitions"); + const nested = container instanceof Y.Map ? container.get("subgraphs") : undefined; + if (nested instanceof Y.Map) nested.forEach((child) => { + if (child instanceof Y.Map) visit(child); + }); + }; + definitionsMap(doc).forEach(visit); return count; } diff --git a/packages/comfy-multi-player/src/index.ts b/packages/comfy-multi-player/src/index.ts index 94527eb39f7..263a979e068 100644 --- a/packages/comfy-multi-player/src/index.ts +++ b/packages/comfy-multi-player/src/index.ts @@ -2,7 +2,7 @@ * @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 op vocabulary is frozen at six kinds; the + * and the server doc host. The op vocabulary is frozen at seven kinds; 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 @@ -55,6 +55,7 @@ export { type CmpEventSink, type CmpEventType, } from "./events.js"; +export { remapWorkflowIds, type RemapWorkflowIdsOptions } from "./remap.js"; /** * ADR-004 follower read-surface. These helpers expose the established wire * layout only so the frontend follower can consume host updates. They are diff --git a/packages/comfy-multi-player/src/remap.ts b/packages/comfy-multi-player/src/remap.ts new file mode 100644 index 00000000000..f1dfc518984 --- /dev/null +++ b/packages/comfy-multi-player/src/remap.ts @@ -0,0 +1,148 @@ +import type { WorkflowJSON, WorkflowNode } from "./types.js"; +import { sha256Hex } from "./digest.js"; + +export interface RemapWorkflowIdsOptions { + nodeIdStart: number; + linkIdStart: number; +} + +function derivedId(opId: string, scope: string, kind: string, original: unknown): string { + return `insert:${opId}:${scope}:${kind}:${encodeURIComponent(JSON.stringify(original))}`; +} + +function derivedDefinitionId(opId: string, scope: string, original: unknown): string { + const hex = sha256Hex(derivedId(opId, scope, "definition", original)); + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`; +} + +function remapGraph(graph: Record, opId: string, scope: string, definitionIds: Map): void { + const nodes = graph["nodes"] as WorkflowNode[]; + const links = (graph["links"] as unknown[] | undefined) ?? []; + const nodeIds = new Map(); + const linkIds = new Map(); + for (const node of nodes) nodeIds.set(node.id, derivedId(opId, scope, "node", node.id)); + for (const link of links) { + if (Array.isArray(link)) linkIds.set(link[0], derivedId(opId, scope, "link", link[0])); + else if (typeof link === "object" && link !== null) { + const record = link as { id?: unknown }; + linkIds.set(record.id, derivedId(opId, scope, "link", record.id)); + } + } + + for (const node of nodes) { + node.id = nodeIds.get(node.id)!; + if (definitionIds.has(node.type)) node.type = definitionIds.get(node.type)!; + if (Array.isArray(node.inputs)) { + for (const input of node.inputs) { + if (typeof input === "object" && input !== null && "link" in input) { + const record = input as { link?: unknown }; + if (linkIds.has(record.link)) record.link = linkIds.get(record.link); + } + } + } + if (Array.isArray(node.outputs)) { + for (const output of node.outputs) { + if (typeof output === "object" && output !== null && Array.isArray((output as { links?: unknown }).links)) { + const record = output as { links: unknown[] }; + record.links = record.links.map((id) => linkIds.get(id) ?? id); + } + } + } + } + graph["links"] = links.map((link) => { + if (Array.isArray(link)) { + link[0] = linkIds.get(link[0]) ?? link[0]; + link[1] = nodeIds.get(link[1]) ?? link[1]; + link[3] = nodeIds.get(link[3]) ?? link[3]; + } else if (typeof link === "object" && link !== null) { + const record = link as { id?: unknown; origin_id?: unknown; target_id?: unknown }; + record.id = linkIds.get(record.id) ?? record.id; + record.origin_id = nodeIds.get(record.origin_id) ?? record.origin_id; + record.target_id = nodeIds.get(record.target_id) ?? record.target_id; + } + return link; + }); + if (Array.isArray(graph["groups"])) { + graph["groups"] = (graph["groups"] as unknown[]).map((group) => { + if (typeof group === "object" && group !== null && !Array.isArray(group)) { + const record = group as { id?: unknown }; + if (record.id !== undefined) record.id = derivedId(opId, scope, "group", record.id); + } + return group; + }); + } +} + +/** Deterministically remap every id carried by an insertion op, including nested definition graphs. */ +export function remapInsertedWorkflowIds(wf: WorkflowJSON, opId: string): WorkflowJSON { + const out = structuredClone(wf) as WorkflowJSON & Record; + out.links ??= []; + out.groups ??= []; + const subgraphs = (out.definitions?.subgraphs ?? []) as Array>; + const definitionIds = new Map(); + const collect = (definitions: Array>, scope: string): void => { + for (const definition of definitions) { + const original = String(definition["id"]); + const remapped = derivedDefinitionId(opId, scope, original); + definitionIds.set(original, remapped); + const nested = (definition["definitions"] as { subgraphs?: Array> } | undefined)?.subgraphs ?? []; + collect(nested, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`); + } + }; + collect(subgraphs, "root"); + const rewrite = (definitions: Array>, scope: string): void => { + for (const definition of definitions) { + const original = String(definition["id"]); + definition["id"] = definitionIds.get(original)!; + remapGraph(definition, opId, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`, definitionIds); + const nested = (definition["definitions"] as { subgraphs?: Array> } | undefined)?.subgraphs ?? []; + rewrite(nested, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`); + } + }; + remapGraph(out, opId, "root", definitionIds); + rewrite(subgraphs, "root"); + return out; +} + +/** Remap only the top-level graph namespace; definition interiors are independent graphs. */ +export function remapWorkflowIds(wf: WorkflowJSON, opts: RemapWorkflowIdsOptions): WorkflowJSON { + const out = structuredClone(wf); + const nodeIds = new Map(); + const linkIds = new Map(); + + out.nodes.forEach((node, index) => nodeIds.set(node.id, opts.nodeIdStart + index)); + out.links.forEach((link, index) => { + if (Array.isArray(link)) linkIds.set(link[0], opts.linkIdStart + index); + }); + + out.nodes = out.nodes.map((node): WorkflowNode => { + const remapped = node as WorkflowNode; + remapped.id = nodeIds.get(node.id)!; + if (Array.isArray(remapped.inputs)) { + for (const input of remapped.inputs) { + if (typeof input === "object" && input !== null && "link" in input) { + const record = input as { link?: unknown }; + if (linkIds.has(record.link)) record.link = linkIds.get(record.link); + } + } + } + if (Array.isArray(remapped.outputs)) { + for (const output of remapped.outputs) { + if (typeof output === "object" && output !== null && Array.isArray((output as { links?: unknown }).links)) { + const record = output as { links: unknown[] }; + record.links = record.links.map((id) => linkIds.get(id) ?? id); + } + } + } + return remapped; + }); + + out.links = out.links.map((link) => { + if (!Array.isArray(link)) return link; + link[0] = linkIds.get(link[0]) ?? link[0]; + link[1] = nodeIds.get(link[1]) ?? link[1]; + link[3] = nodeIds.get(link[3]) ?? link[3]; + return link; + }); + return out; +} diff --git a/packages/comfy-multi-player/src/stamps.ts b/packages/comfy-multi-player/src/stamps.ts index 1e66105719a..da36e79d4f8 100644 --- a/packages/comfy-multi-player/src/stamps.ts +++ b/packages/comfy-multi-player/src/stamps.ts @@ -112,6 +112,12 @@ export function writeTarget(op: WireOp): unknown[] { return ["input", String(op.to_node), op.to_slot]; case "disconnect": return ["input", String(op.to_node), op.to_slot]; + case "insert_workflow": + // One insertion is one register: the op is idempotent by `op_id` (exact + // replay is a no-op via the applied-set gate), and two distinct + // insertions never contend because the minter allocates fresh ids + // (ADR-022). Keyed by op_id so a stamp lookup is per-insertion. + return ["insert_workflow", op.op_id]; case "clear": case "reset_doc": // Whole-document ops: no scalar register to contest, so the target is @@ -123,7 +129,7 @@ export function writeTarget(op: WireOp): unknown[] { return ["definition", op.subgraph_id]; default: // Exhaustiveness guard (issue #21): with every `WireOp` member cased - // above — the five `Op` kinds plus the deferred `reset_doc` — `op` is + // above — the six `Op` kinds plus the deferred `reset_doc` — `op` is // `never` here, so adding a kind to EITHER union fails `tsc` at this // line until it is given a write target. // diff --git a/packages/comfy-multi-player/src/types.ts b/packages/comfy-multi-player/src/types.ts index 67eed1585c4..e3fd9b7bd83 100644 --- a/packages/comfy-multi-player/src/types.ts +++ b/packages/comfy-multi-player/src/types.ts @@ -33,7 +33,16 @@ export const LEGACY_NODE_INCARNATION = "0"; // --------------------------------------------------------------------------- /** The implemented op kinds. `apply` rejects anything else loudly. */ -export const FROZEN_OPS = ["add_node", "connect", "disconnect", "set_widget", "delete_node", "clear", "define_subgraph"] as const; +export const FROZEN_OPS = [ + "add_node", + "connect", + "disconnect", + "set_widget", + "delete_node", + "clear", + "define_subgraph", + "insert_workflow", +] as const; /** Defined by the vocabulary but deferred (§1.6): rejected until un-deferred by amendment. */ export const DEFERRED_OPS = ["reset_doc"] as const; @@ -127,7 +136,7 @@ export interface OpBase { } // --------------------------------------------------------------------------- -// The seven declared op kinds: six implemented (`Op`) plus the deferred +// The eight declared op kinds: seven implemented (`Op`) plus the deferred // `reset_doc` (`DeferredOp`); together `WireOp`. "Frozen" now means // implemented — `FROZEN_OPS` is pinned to `Op["op"]` exactly (issue #17). // --------------------------------------------------------------------------- @@ -144,6 +153,27 @@ export interface AddNodeOp extends OpBase { node: WorkflowNode; } +/** + * Merge a workflow template (nodes, links, `definitions.subgraphs`) into an + * existing doc in one transaction (ADR-022; agent-subgraph TDD V1.5). + * + * The applier remaps every carried id deterministically from `op_id` and the + * original id. Exact replay therefore chooses the same ids, while distinct + * insert ops cannot collide or depend on document state. `links`, `groups`, + * and `definitions` are optional and default to empty. + */ +export interface InsertWorkflowOp extends OpBase { + op: "insert_workflow"; + /** The template to merge — AUTHORITATIVE, nodes inserted verbatim after id validation. */ + workflow: { + nodes: WorkflowNode[]; + links?: unknown[]; + groups?: unknown[]; + definitions?: { subgraphs?: unknown[]; [key: string]: unknown }; + [key: string]: unknown; + }; +} + /** Autogrow slot descriptor carried by a `connect` (vocabulary §1.2 / §8.4). */ export interface GrowSpec { /** Requested slot name (`images.image0` autogrow shape, or bare `image_2` for the inputcount family). */ @@ -431,7 +461,8 @@ export type Op = | SetWidgetOp | DeleteNodeOp | ClearOp - | DefineSubgraphOp; + | DefineSubgraphOp + | InsertWorkflowOp; /** * A kind the vocabulary declares but this package refuses to apply @@ -549,6 +580,7 @@ export interface WorkflowNode { export interface WorkflowJSON { nodes: WorkflowNode[]; links: unknown[]; + definitions?: { subgraphs?: unknown[]; [key: string]: unknown }; groups?: unknown[]; extra?: Record; [key: string]: unknown; diff --git a/packages/comfy-multi-player/test/batch-policy.test.ts b/packages/comfy-multi-player/test/batch-policy.test.ts index 04adcc5f39b..b0dc9b5a9cf 100644 --- a/packages/comfy-multi-player/test/batch-policy.test.ts +++ b/packages/comfy-multi-player/test/batch-policy.test.ts @@ -42,8 +42,8 @@ import { loadCatalog, loadSession, sessionFiles } from "./helpers.js"; const repoRoot = dirname(dirname(fileURLToPath(import.meta.url))); const batchable = new Set(BATCHABLE_OPS); -/** The two kinds the vocabulary calls standalone-only (§1.5, §1.6). */ -const STANDALONE_ONLY = ["clear", "reset_doc"]; +/** Kinds the vocabulary or ADR-022 calls standalone-only. */ +const STANDALONE_ONLY = ["clear", "insert_workflow", "reset_doc"]; const catalog: WidgetCatalog = { types: { Sampler: { widget_order: ["steps"] } } }; const base: WorkflowJSON = { diff --git a/packages/comfy-multi-player/test/convergence.test.ts b/packages/comfy-multi-player/test/convergence.test.ts index 56852a7c6cd..bedfd9af71c 100644 --- a/packages/comfy-multi-player/test/convergence.test.ts +++ b/packages/comfy-multi-player/test/convergence.test.ts @@ -53,6 +53,8 @@ function touchedNodes(op: WireOp): string[] { return [String(op.from_node), String(op.to_node)]; case "disconnect": return [String(op.to_node)]; + case "insert_workflow": + return op.workflow.nodes.map((node) => String(node.id)); case "clear": case "delete_node": case "reset_doc": diff --git a/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts b/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts index c3a62b93b8c..5624d8aca07 100644 --- a/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts +++ b/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts @@ -228,6 +228,8 @@ function makeOp( links: [], }, }; + case "insert_workflow": + return { ...env, op: "insert_workflow", workflow: { nodes: [node(140 + serial, "Aux", [], [], [value])], links: [] } }; case "reset_doc": return { ...env, op: "reset_doc", workflow: { nodes: [], links: [] } }; } diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts new file mode 100644 index 00000000000..18f7551afb9 --- /dev/null +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -0,0 +1,433 @@ +/** + * `insert_workflow` — merge a template workflow (nodes, links, + * `definitions.subgraphs`) into an existing doc in ONE transaction. + * + * TDD V1.5 (in-app-agent program, ADR-T8): today a template with subgraphs can + * only reach a live doc through a whole-doc reseed, because every other op + * schema rejects definition-bearing fields (KA-11). This op carries the + * template as an opaque payload the applier merges under the same guards the + * six existing kinds obey: collision-free ids (validated BEFORE any mutation, + * KA-4), definition dedupe/fork by content hash, exact-replay no-op through + * the op_id gate, and byte-identical doc on rejection. + * + * ID allocation belongs to the applier and is derived from the immutable op + * id plus each raw id, never from mutable document state. + */ +import { describe, expect, it } from "vitest"; +import * as Y from "yjs"; + +import { appliedMap } from "../src/doc.js"; +import { + OPAQUE_WIDGETS_KEY, + applyOps, + mint, + project, + remapWorkflowIds, + type Op, + type WidgetCatalog, + type WorkflowJSON, +} from "../src/index.js"; +import { appliedOpIds, noOpIds, rejectedOutcomeWithIndex } from "./apply-result-helpers.js"; + +const catalog: WidgetCatalog = { + types: { + Src: { widget_order: [] }, + Sink: { widget_order: ["inputcount"] }, + KSampler: { widget_order: ["seed", "steps"] }, + Inner: { widget_order: ["text"] }, + }, +}; + +function baseWorkflow(): WorkflowJSON { + return { + last_node_id: 7, + last_link_id: 7, + nodes: [ + { id: 1, type: "Src" }, + { id: 2, type: "Src" }, + { id: 3, type: "Sink", inputs: [{ name: "in", link: 7 }], widgets_values: [1] }, + { id: 4, type: "KSampler", widgets_values: [1, 2] }, + { id: 6, type: "def-1" }, + ], + links: [[7, 2, 0, 3, 0, "X"]], + definitions: { + subgraphs: [{ id: "def-1", name: "D", nodes: [{ id: 27, type: "Inner", widgets_values: ["t"] }], links: [] }], + }, + } as unknown as WorkflowJSON; +} + +/** A template with its OWN definition `def-2` and ids already disjoint from the base. */ +function template(): WorkflowJSON { + return { + nodes: [ + { id: 100, type: "Src", pos: [0, 0] }, + { id: 101, type: "def-2", inputs: [{ name: "a", link: 200 }] }, + ], + links: [[200, 100, 0, 101, 0, "X"]], + definitions: { + subgraphs: [{ id: "def-2", name: "E", nodes: [{ id: 5, type: "Inner", widgets_values: ["u"] }], links: [] }], + }, + } as unknown as WorkflowJSON; +} + +let seq = 0; +function env(): Pick { + return { + op_id: ("i" + String(seq++).padStart(4, "0")).padEnd(32, "0"), + actor: "a", + base_version: 1, + stamp: [1, "a"] as [number, string], + }; +} + +function insertOp(workflow: unknown, overrides: Partial = {}): Op { + return { ...env(), op: "insert_workflow", workflow, ...overrides } as unknown as Op; +} + +const bytes = (doc: Y.Doc): Buffer => Buffer.from(Y.encodeStateAsUpdate(doc)); + +function ids(wf: WorkflowJSON): unknown[] { + return (wf.nodes ?? []).map((n) => n.id); +} +function linkIds(wf: WorkflowJSON): unknown[] { + return (wf.links ?? []).map((l) => (l as unknown[])[0]); +} +function defIds(wf: WorkflowJSON): string[] { + const defs = (wf as { definitions?: { subgraphs?: { id: unknown }[] } }).definitions; + return (defs?.subgraphs ?? []).map((s) => String(s.id)); +} + +describe("insert_workflow: happy path", () => { + it("merges template nodes, links and definitions into the doc in one op", () => { + const doc = mint(baseWorkflow(), catalog); + const op = insertOp(template()); + const result = applyOps(doc, [op], catalog); + + expect(appliedOpIds(result)).toEqual([op.op_id]); + const wf = project(doc, catalog); + expect(ids(wf).slice(0, 5)).toEqual([1, 2, 3, 4, 6]); + expect(ids(wf).slice(5).every((id) => typeof id === "string" && id.includes(op.op_id))).toBe(true); + expect(linkIds(wf)[1]).toEqual(expect.stringContaining(op.op_id)); + expect(defIds(wf)[1]).toEqual(expect.stringContaining(op.op_id)); + // Inserted nodes project with their widgets resolved through the catalog. + const n100 = wf.nodes!.find((n) => n.pos?.[0] === 0)!; + expect(n100.type).toBe("Src"); + expect(n100.pos).toEqual([0, 0]); + const n101 = wf.nodes!.find((n) => n.type === defIds(wf)[1])!; + expect((n101.inputs?.[0] as { link?: unknown } | undefined)?.link).toBe(linkIds(wf)[1]); + expect(wf.last_node_id).toBe(7); + expect(wf.last_link_id).toBe(7); + }); + + it("is an exact-replay no-op through the op_id gate (no second copy)", () => { + const doc = mint(baseWorkflow(), catalog); + const op = insertOp(template()); + applyOps(doc, [op], catalog); + const before = bytes(doc); + const again = applyOps(doc, [op], catalog); + expect(noOpIds(again)).toEqual([op.op_id]); + expect(bytes(doc).equals(before)).toBe(true); + expect(ids(project(doc, catalog))).toHaveLength(7); + }); + + it("remaps a template definition even when its raw id matches live content", () => { + const doc = mint(baseWorkflow(), catalog); + const tpl = template(); + (tpl as { definitions: { subgraphs: unknown[] } }).definitions.subgraphs = [ + { id: "def-1", name: "D", nodes: [{ id: 27, type: "Inner", widgets_values: ["t"] }], links: [] }, + ]; + tpl.nodes![1] = { id: 101, type: "def-1", inputs: [{ name: "a", link: 200 }] }; + const op = insertOp(tpl); + const result = applyOps(doc, [op], catalog); + expect(appliedOpIds(result)).toEqual([op.op_id]); + const wf = project(doc, catalog); + expect(defIds(wf)).toHaveLength(2); + expect(defIds(wf)[1]).toContain(op.op_id); + expect(wf.nodes!.find((n) => n.id !== 6 && n.type === defIds(wf)[1])).toBeDefined(); + }); + + it("preserves opaque widgets_values for uncatalogued inserted nodes", () => { + const doc = mint(baseWorkflow(), catalog); + const tpl = { nodes: [{ id: 300, type: "Note", widgets_values: ["hello"] }], links: [] } as unknown as WorkflowJSON; + applyOps(doc, [insertOp(tpl)], catalog); + const wf = project(doc, catalog); + expect(wf.nodes!.find((n) => n.type === "Note")!.widgets_values).toEqual(["hello"]); + expect(OPAQUE_WIDGETS_KEY).toBeTruthy(); + }); + + it("accepts nodes without optional links, groups, or definitions", () => { + const doc = mint(baseWorkflow(), catalog); + const op = insertOp({ nodes: [{ id: 1, type: "Src", title: "minimal" }] }); + + expect(applyOps(doc, [op], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(project(doc, catalog).nodes!.find((node) => node.title === "minimal")?.id).toEqual(expect.stringContaining(op.op_id)); + }); + + it("merges groups deterministically without dropping existing groups", () => { + const seeded = { ...baseWorkflow(), groups: [{ title: "Base" }] } as WorkflowJSON; + const doc = mint(seeded, catalog); + applyOps(doc, [insertOp({ nodes: [], links: [], groups: [{ title: "Inserted" }] })], catalog); + + expect(project(doc, catalog).groups).toEqual([{ title: "Base" }, { title: "Inserted" }]); + }); + + it("scrubs private __ keys recursively from every inserted payload branch", () => { + const doc = mint(baseWorkflow(), catalog); + applyOps(doc, [insertOp({ + nodes: [{ id: 100, type: "Src", properties: { visible: true, __definition_digest: "node-secret" } }], + links: [], + groups: [{ title: "G", nested: { __private: "group-secret", visible: true } }], + definitions: { + subgraphs: [{ id: "def-2", nodes: [], links: [], metadata: { __definition_digest: "def-secret", visible: true } }], + }, + })], catalog); + + const json = JSON.stringify(project(doc, catalog)); + expect(json).not.toContain("__definition_digest"); + expect(json).not.toContain("__private"); + expect(json).toContain('"visible":true'); + }); + + it("makes colliding concurrent inserts converge in either legal arrival order", () => { + const seed = Y.encodeStateAsUpdate(mint(baseWorkflow(), catalog)); + const run = (ops: Op[]): WorkflowJSON => { + const doc = new Y.Doc(); + Y.applyUpdate(doc, seed); + for (const op of ops) applyOps(doc, [op], catalog); + return project(doc, catalog); + }; + const lower = insertOp( + { nodes: [{ id: 100, type: "Src", title: "lower" }, { id: 101, type: "Sink" }], links: [[200, 100, 0, 101, 0, "lower"]] }, + { op_id: "a".repeat(32), stamp: [2, "a"] }, + ); + const higher = insertOp( + { nodes: [{ id: 100, type: "Src", title: "higher" }, { id: 101, type: "Sink" }], links: [[200, 100, 0, 101, 0, "higher"]] }, + { op_id: "b".repeat(32), stamp: [3, "b"] }, + ); + + expect(run([lower, higher])).toEqual(run([higher, lower])); + expect(run([lower, higher]).nodes!.filter((node) => node.title === "lower" || node.title === "higher")).toHaveLength(2); + expect(run([lower, higher]).links!.filter((link) => ["lower", "higher"].includes((link as unknown[])[5] as string))).toHaveLength(2); + }); + + it("keeps valid inserted content when a carried link endpoint was concurrently deleted", () => { + const seed = Y.encodeStateAsUpdate(mint(baseWorkflow(), catalog)); + const insert = insertOp({ + nodes: [{ id: 100, type: "Src", title: "inserted source" }, { id: 101, type: "Sink", title: "inserted sink" }], + links: [[200, 100, 0, 101, 0, "valid"], [201, 100, 0, 1, 0, "missing endpoint"]], + groups: [{ title: "Inserted group" }], + definitions: { subgraphs: [{ id: "inserted-def", nodes: [], links: [] }] }, + }); + const remove = { + ...env(), op: "delete_node", node_id: 1, removed_links: [], stamp: [2, "b"], + } as unknown as Op; + const run = (ops: Op[]): WorkflowJSON => { + const doc = new Y.Doc(); + Y.applyUpdate(doc, seed); + for (const op of ops) applyOps(doc, [op], catalog); + return project(doc, catalog); + }; + + const deleteThenInsert = run([remove, insert]); + const insertThenDelete = run([insert, remove]); + expect(deleteThenInsert).toEqual(insertThenDelete); + expect(deleteThenInsert.nodes!.filter((node) => typeof node.title === "string" && node.title.startsWith("inserted"))).toHaveLength(2); + expect(deleteThenInsert.links!.filter((link) => (link as unknown[])[5] === "valid")).toHaveLength(1); + expect(deleteThenInsert.links!.some((link) => (link as unknown[])[5] === "missing endpoint")).toBe(false); + expect(deleteThenInsert.groups).toContainEqual({ title: "Inserted group" }); + expect(defIds(deleteThenInsert).some((id) => id.includes(insert.op_id))).toBe(true); + }); + + it("stores nested definitions as addressable maps for later interior set_widget", () => { + const doc = mint(baseWorkflow(), catalog); + const nested = { id: "nested-def", nodes: [{ id: 9, type: "Inner", widgets_values: ["before"] }], links: [] }; + const outer = { + id: "outer-def", name: "Outer", nodes: [{ id: 8, type: "nested-def" }], links: [], definitions: { subgraphs: [nested] }, + }; + applyOps(doc, [insertOp({ nodes: [{ id: 100, type: "outer-def" }], links: [], definitions: { subgraphs: [outer] } })], catalog); + const projected = project(doc, catalog) as { nodes: Array<{ id: string; type: string }>; definitions: { subgraphs: Array> } }; + const projectedOuter = projected.definitions.subgraphs.find((definition) => definition["name"] === "Outer") ?? projected.definitions.subgraphs.find((definition) => definition["id"] !== "def-1")!; + const projectedNested = (projectedOuter["definitions"] as { subgraphs: Array> }).subgraphs[0]!; + const outerNode = (projectedOuter["nodes"] as Array<{ id: string }>)[0]!; + const innerNode = (projectedNested["nodes"] as Array<{ id: string }>)[0]!; + const host = projected.nodes.find((node) => node.type === projectedOuter["id"])!; + const edit = { ...env(), op: "set_widget", node_id: host.id, path: [host.id, outerNode.id, innerNode.id], inner_widget: "text", value: "after" } as unknown as Op; + + expect(applyOps(doc, [edit], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + const defs = (project(doc, catalog) as { definitions: { subgraphs: Array> } }).definitions.subgraphs; + const updatedOuter = defs.find((definition) => definition.id === projectedOuter["id"]) as { + definitions: { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> }; + }; + expect(updatedOuter.definitions.subgraphs[0]!.nodes[0]!.widgets_values).toEqual(["after"]); + }); +}); + +describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from applied)", () => { + const cases: { name: string; workflow: unknown; code: string; withCatalog: boolean }[] = [ + { + name: "duplicate node id inside the template itself", + workflow: { nodes: [{ id: 100, type: "Src" }, { id: 100, type: "Src" }], links: [] }, + code: "node_id_collision", + withCatalog: true, + }, + { name: "missing workflow", workflow: undefined, code: "malformed_op", withCatalog: true }, + { name: "non-object workflow", workflow: "nope", code: "malformed_op", withCatalog: true }, + { name: "nodes is not an array", workflow: { nodes: {}, links: [] }, code: "malformed_op", withCatalog: true }, + { + name: "node without id/type", + workflow: { nodes: [{ pos: [0, 0] }], links: [] }, + code: "invalid_node_payload", + withCatalog: true, + }, + { + name: "positional widgets with no catalog", + workflow: { nodes: [{ id: 100, type: "KSampler", widgets_values: [1, 2] }], links: [] }, + code: "catalog_required", + withCatalog: false, + }, + ]; + + for (const c of cases) { + it(`rejects: ${c.name} → ${c.code}`, () => { + const doc = mint(baseWorkflow(), catalog); + const before = bytes(doc); + const op = insertOp(c.workflow); + const result = applyOps(doc, [op], c.withCatalog ? catalog : undefined); + expect(rejectedOutcomeWithIndex(result)!.code).toBe(c.code); + expect(bytes(doc).equals(before)).toBe(true); + expect(appliedMap(doc).has(op.op_id)).toBe(false); + }); + } + + it("remaps raw ids that collide with live ids without touching incumbents", () => { + const doc = mint(baseWorkflow(), catalog); + const before = bytes(doc); + const wf = { nodes: [{ id: 100, type: "Src" }, { id: 101, type: "Src" }, { id: 4, type: "Src" }], links: [] }; + expect(applyOps(doc, [insertOp(wf)], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(bytes(doc).equals(before)).toBe(false); + expect(project(doc, catalog).nodes!.find((node) => node.id === 4)?.type).toBe("KSampler"); + expect(ids(project(doc, catalog))).toHaveLength(8); + }); + + it("routes dangling link endpoints through the existing unknown-node no-op path", () => { + const doc = mint(baseWorkflow(), catalog); + const op = insertOp({ nodes: [], links: [[200, 100, 0, 999, 0, "X"]] }); + const result = applyOps(doc, [op], catalog); + + expect(result.outcomes[0]).toMatchObject({ outcome: "no-op" }); + expect(appliedMap(doc).has(op.op_id)).toBe(true); + }); + + it("rejects an id-less nested subgraph atomically", () => { + const doc = mint(baseWorkflow(), catalog); + const before = bytes(doc); + const op = insertOp({ + nodes: [{ id: 100, type: "Src" }], + links: [], + definitions: { + subgraphs: [{ id: "outer", nodes: [], links: [], definitions: { subgraphs: [{ nodes: [], links: [] }] } }], + }, + }); + + expect(rejectedOutcomeWithIndex(applyOps(doc, [op], catalog))!.code).toBe("malformed_op"); + expect(bytes(doc).equals(before)).toBe(true); + expect(appliedMap(doc).has(op.op_id)).toBe(false); + }); + + it("remaps a nested definition id already used in the live tree", () => { + const doc = mint(baseWorkflow(), catalog); + const op = insertOp({ + nodes: [{ id: 100, type: "outer" }], links: [], + definitions: { + subgraphs: [{ id: "outer", nodes: [], links: [], definitions: { subgraphs: [{ id: "def-1", nodes: [], links: [] }] } }], + }, + }); + + expect(applyOps(doc, [op], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + }); + + it("inserts same-raw-id definitions identically in either arrival order", () => { + const seed = Y.encodeStateAsUpdate(mint(baseWorkflow(), catalog)); + const makeDoc = (): Y.Doc => { + const doc = new Y.Doc(); + Y.applyUpdate(doc, seed); + return doc; + }; + const makeConflict = (name: string, nodeId: number, opId: string): Op => + insertOp( + { + nodes: [{ id: nodeId, type: "def-1" }], + links: [], + definitions: { subgraphs: [{ id: "def-1", name, nodes: [], links: [] }] }, + }, + { op_id: opId }, + ); + const first = makeConflict("A", 100, "a".repeat(32)); + const second = makeConflict("B", 101, "b".repeat(32)); + const docA = makeDoc(); + const docB = makeDoc(); + + expect(applyOps(docA, [first], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(applyOps(docA, [second], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(applyOps(docB, [second], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(applyOps(docB, [first], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(project(docA, catalog)).toEqual(project(docB, catalog)); + expect(defIds(project(docA, catalog))).toHaveLength(3); + }); + + it("never overwrites an occupied legacy fork-shaped id", () => { + const wf = baseWorkflow() as WorkflowJSON & { definitions: { subgraphs: Record[] } }; + wf.definitions.subgraphs.push({ id: "def-1-deadbeef", name: "Occupied", nodes: [], links: [] }); + const doc = mint(wf, catalog); + const before = bytes(doc); + const op = insertOp({ + nodes: [{ id: 100, type: "def-1" }], + links: [], + definitions: { subgraphs: [{ id: "def-1", name: "Different", nodes: [], links: [] }] }, + }); + + expect(applyOps(doc, [op], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + expect(bytes(doc).equals(before)).toBe(false); + const definitions = (project(doc, catalog) as { definitions: { subgraphs: { id: string; name: string }[] } }).definitions.subgraphs; + expect(definitions.find((definition) => definition.id === "def-1-deadbeef")!.name).toBe("Occupied"); + }); +}); + +describe("remapWorkflowIds (minter-side helper)", () => { + it("shifts node and link ids and rewrites every reference, leaving definitions untouched", () => { + const out = remapWorkflowIds(template(), { nodeIdStart: 8, linkIdStart: 8 }); + expect(ids(out)).toEqual([8, 9]); + expect(linkIds(out)).toEqual([8]); + const link = out.links![0] as unknown[]; + expect(link.slice(0, 5)).toEqual([8, 8, 0, 9, 0]); + expect(out.nodes![1]!.inputs).toEqual([{ name: "a", link: 8 }]); + expect(defIds(out)).toEqual(["def-2"]); + // Interior definition ids are a separate namespace: unchanged. + const inner = (out as { definitions: { subgraphs: { nodes: { id: unknown }[] }[] } }).definitions.subgraphs[0]!; + expect(inner.nodes[0]!.id).toBe(5); + }); + + it("rewrites output links arrays and does not mutate its input", () => { + const tpl = { + nodes: [ + { id: 1, type: "Src", outputs: [{ name: "o", links: [1, 2] }] }, + { id: 2, type: "Sink", inputs: [{ name: "in", link: 1 }] }, + { id: 3, type: "Sink", inputs: [{ name: "in", link: 2 }] }, + ], + links: [ + [1, 1, 0, 2, 0, "X"], + [2, 1, 0, 3, 0, "X"], + ], + } as unknown as WorkflowJSON; + const snapshot = structuredClone(tpl); + const out = remapWorkflowIds(tpl, { nodeIdStart: 10, linkIdStart: 20 }); + expect(tpl).toEqual(snapshot); + expect(ids(out)).toEqual([10, 11, 12]); + expect(out.nodes![0]!.outputs).toEqual([{ name: "o", links: [20, 21] }]); + expect(out.nodes![2]!.inputs).toEqual([{ name: "in", link: 21 }]); + expect(out.links).toEqual([ + [20, 10, 0, 11, 0, "X"], + [21, 10, 0, 12, 0, "X"], + ]); + }); +}); diff --git a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts index 3237fd86019..7d2f2a8cc94 100644 --- a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts +++ b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts @@ -187,6 +187,30 @@ const CASES: Row[] = [ }) as unknown as Op, }, + // ---- insert_workflow ---------------------------------------------------- + { + kind: "insert_workflow", + why: "duplicate raw node ids are ambiguous before deterministic remapping", + code: "node_id_collision", + build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [{ id: 1, type: "Src" }, { id: 1, type: "Src" }] } }) as Op, + }, + { + kind: "insert_workflow", + why: "duplicate raw link ids are ambiguous before deterministic remapping", + code: "link_id_collision", + build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [], links: [[7, 2, 0, 3, 0, "X"], [7, 2, 0, 3, 0, "X"]] } }) as Op, + }, + { + kind: "insert_workflow", + why: "duplicate raw definition ids are ambiguous before deterministic remapping", + code: "definition_conflict", + build: () => ({ + op: "insert_workflow", + ...env(), + workflow: { nodes: [], definitions: { subgraphs: [{ id: "d", nodes: [], links: [] }, { id: "d", nodes: [], links: [] }] } }, + }) as Op, + }, + // ---- set_widget ---------------------------------------------------------- { kind: "set_widget", @@ -657,6 +681,9 @@ const ALL_REJECTION_CODES = [ "op_deferred", "catalog_required", "invalid_node_payload", + "node_id_collision", + "link_id_collision", + "definition_conflict", "unknown_widget", "opaque_widgets", "widget_out_of_range", diff --git a/packages/comfy-multi-player/test/readonly-surface.test.ts b/packages/comfy-multi-player/test/readonly-surface.test.ts index 26ae06cad30..473bf7cb574 100644 --- a/packages/comfy-multi-player/test/readonly-surface.test.ts +++ b/packages/comfy-multi-player/test/readonly-surface.test.ts @@ -748,6 +748,7 @@ describe("read-only surface — classification", () => { "observedDocCounter", "validateLamportCounter", "observeLamport", + "remapWorkflowIds", "tickLamport", "persistLamportTick", "freezeLamportEnvelope", diff --git a/packages/comfy-multi-player/test/types/invalid-states.negative.ts b/packages/comfy-multi-player/test/types/invalid-states.negative.ts index 2c70f7775de..1e350d2b337 100644 --- a/packages/comfy-multi-player/test/types/invalid-states.negative.ts +++ b/packages/comfy-multi-player/test/types/invalid-states.negative.ts @@ -25,6 +25,7 @@ import type { ConnectOp, DeleteNodeOp, GrowConnectOp, + InsertWorkflowOp, InteriorSetWidgetOp, Op, ResetDocOp, @@ -196,6 +197,13 @@ declare function applyOpsSignature(ops: Op[]): void; // @ts-expect-error #17: the applier cannot be handed an op it always refuses. applyOpsSignature([reset]); +const insertWorkflow: InsertWorkflowOp = { + op: "insert_workflow", + ...env, + workflow: { nodes: [], links: [], definitions: { subgraphs: [] } }, +}; +const insertWorkflowAsOp: Op = insertWorkflow; + // --------------------------------------------------------------------------- // Positive controls — these MUST compile, or the gate above is vacuous // --------------------------------------------------------------------------- From 98636fcf9d83b159d3433444d27e75d982ddb4e6 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 19:02:01 -0700 Subject: [PATCH 02/11] refactor(cmp): insert_workflow reuses define_subgraph definition helpers --- packages/comfy-multi-player/src/applier.ts | 4 +-- .../test/full-op-pool.permutation.test.ts | 4 +-- .../test/insert-workflow.test.ts | 28 ++++++++++++++++--- .../test/ka4-rejection-byte-identity.test.ts | 4 +-- 4 files changed, 30 insertions(+), 10 deletions(-) diff --git a/packages/comfy-multi-player/src/applier.ts b/packages/comfy-multi-player/src/applier.ts index e544d1501da..bbcba65fd72 100644 --- a/packages/comfy-multi-player/src/applier.ts +++ b/packages/comfy-multi-player/src/applier.ts @@ -104,8 +104,8 @@ import { import { remapInsertedWorkflowIds } from "./remap.js"; import { sha256Hex } from "./digest.js"; import { CMP_EVENT_SCHEMA_VERSION, emitCmpEvent, type CmpCallContext } from "./events.js"; -import { mint, mintDefinition } from "./mint.js"; -import { project, projectDefinition } from "./project.js"; +import { mintDefinition } from "./mint.js"; +import { projectDefinition } from "./project.js"; import { MAX_OP_COST, MAX_OPS_PER_BATCH, diff --git a/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts b/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts index 5624d8aca07..e0039533082 100644 --- a/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts +++ b/packages/comfy-multi-player/test/full-op-pool.permutation.test.ts @@ -45,7 +45,7 @@ const PRECONDITIONS = [ "interior-or-inputcount", "promoted-or-autogrow", ] as const; -const PAIR_EXECUTIONS = 196_608; +const PAIR_EXECUTIONS = 248_832; const SAMPLED_RUNS = 1_696; const SAMPLED_EXECUTIONS = SAMPLED_RUNS * 2; const TOTAL_EXECUTIONS = PAIR_EXECUTIONS + SAMPLED_EXECUTIONS; @@ -544,7 +544,7 @@ describe("full op-pool permutation equivalence", () => { expect(runs).toBe(SAMPLED_RUNS); expect(executions).toBe(SAMPLED_EXECUTIONS); - expect(TOTAL_EXECUTIONS).toBe(200_000); + expect(TOTAL_EXECUTIONS).toBe(252_224); for (const [kind, count] of Object.entries(hits)) expect(count, `${kind} was not sampled`).toBeGreaterThan(0); expect(Object.values(taxonomy).reduce((sum, count) => sum + count, 0)).toBe(SAMPLED_RUNS); console.info("perm-4 sampled taxonomy", { diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index 18f7551afb9..2c67b0619e0 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -27,6 +27,7 @@ import { type WidgetCatalog, type WorkflowJSON, } from "../src/index.js"; +import { remapInsertedWorkflowIds } from "../src/remap.js"; import { appliedOpIds, noOpIds, rejectedOutcomeWithIndex } from "./apply-result-helpers.js"; const catalog: WidgetCatalog = { @@ -108,7 +109,7 @@ describe("insert_workflow: happy path", () => { expect(ids(wf).slice(0, 5)).toEqual([1, 2, 3, 4, 6]); expect(ids(wf).slice(5).every((id) => typeof id === "string" && id.includes(op.op_id))).toBe(true); expect(linkIds(wf)[1]).toEqual(expect.stringContaining(op.op_id)); - expect(defIds(wf)[1]).toEqual(expect.stringContaining(op.op_id)); + expect(defIds(wf).find((id) => id !== "def-1")).toMatch(/^[0-9a-f-]{36}$/); // Inserted nodes project with their widgets resolved through the catalog. const n100 = wf.nodes!.find((n) => n.pos?.[0] === 0)!; expect(n100.type).toBe("Src"); @@ -142,8 +143,9 @@ describe("insert_workflow: happy path", () => { expect(appliedOpIds(result)).toEqual([op.op_id]); const wf = project(doc, catalog); expect(defIds(wf)).toHaveLength(2); - expect(defIds(wf)[1]).toContain(op.op_id); - expect(wf.nodes!.find((n) => n.id !== 6 && n.type === defIds(wf)[1])).toBeDefined(); + const insertedDefinitionId = defIds(wf).find((id) => id !== "def-1")!; + expect(insertedDefinitionId).toMatch(/^[0-9a-f-]{36}$/); + expect(wf.nodes!.find((n) => n.id !== 6 && n.type === insertedDefinitionId)).toBeDefined(); }); it("preserves opaque widgets_values for uncatalogued inserted nodes", () => { @@ -235,7 +237,25 @@ describe("insert_workflow: happy path", () => { expect(deleteThenInsert.links!.filter((link) => (link as unknown[])[5] === "valid")).toHaveLength(1); expect(deleteThenInsert.links!.some((link) => (link as unknown[])[5] === "missing endpoint")).toBe(false); expect(deleteThenInsert.groups).toContainEqual({ title: "Inserted group" }); - expect(defIds(deleteThenInsert).some((id) => id.includes(insert.op_id))).toBe(true); + expect(defIds(deleteThenInsert).some((id) => id !== "def-1" && /^[0-9a-f-]{36}$/.test(id))).toBe(true); + }); + + it("rejects a remapped definition id already present anywhere in the stored tree", () => { + const op = insertOp(template()); + const remapped = remapInsertedWorkflowIds(template(), op.op_id); + const remappedId = String(remapped.definitions!.subgraphs![0]!.id); + const base = baseWorkflow(); + base.definitions!.subgraphs!.push({ id: remappedId, nodes: [], links: [] }); + const doc = mint(base, catalog); + const before = bytes(doc); + + const result = applyOps(doc, [op], catalog); + + expect(rejectedOutcomeWithIndex(result)).toMatchObject({ + index: 0, + code: "definition_conflict", + }); + expect(bytes(doc).equals(before)).toBe(true); }); it("stores nested definitions as addressable maps for later interior set_widget", () => { diff --git a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts index 7d2f2a8cc94..745508614d0 100644 --- a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts +++ b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts @@ -202,8 +202,8 @@ const CASES: Row[] = [ }, { kind: "insert_workflow", - why: "duplicate raw definition ids are ambiguous before deterministic remapping", - code: "definition_conflict", + why: "duplicate remapped definition ids violate define_subgraph tree uniqueness", + code: "malformed_op", build: () => ({ op: "insert_workflow", ...env(), From a924cb7c2e444abf27b021cc76506455724c91c3 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 19:33:30 -0700 Subject: [PATCH 03/11] test(cmp): type remapped definition fixture --- packages/comfy-multi-player/test/insert-workflow.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index 2c67b0619e0..e39ff0538db 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -243,7 +243,7 @@ describe("insert_workflow: happy path", () => { it("rejects a remapped definition id already present anywhere in the stored tree", () => { const op = insertOp(template()); const remapped = remapInsertedWorkflowIds(template(), op.op_id); - const remappedId = String(remapped.definitions!.subgraphs![0]!.id); + const remappedId = defIds(remapped)[0]!; const base = baseWorkflow(); base.definitions!.subgraphs!.push({ id: remappedId, nodes: [], links: [] }); const doc = mint(base, catalog); From 85d17483633617bd6f2410b1f7b1a54258bdf22b Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 20:11:22 -0700 Subject: [PATCH 04/11] fix(cmp): validate raw insert_workflow ids before remapping Reject missing and normalized-duplicate raw node or link IDs atomically as malformed_op before deterministic ID remapping. --- packages/comfy-multi-player/src/applier.ts | 8 ++-- .../test/insert-workflow.test.ts | 40 +++++++++++++++++-- .../test/ka4-rejection-byte-identity.test.ts | 34 ++++++++++++++-- 3 files changed, 71 insertions(+), 11 deletions(-) diff --git a/packages/comfy-multi-player/src/applier.ts b/packages/comfy-multi-player/src/applier.ts index bbcba65fd72..6768d3151d4 100644 --- a/packages/comfy-multi-player/src/applier.ts +++ b/packages/comfy-multi-player/src/applier.ts @@ -705,17 +705,17 @@ function validateSubgraphDefinition(definition: Record, path: s }); } -function assertUniqueNormalizedIds(values: unknown[], path: string, required = false): void { +function assertUniqueNormalizedIds(values: unknown[], path: string, required = false, operation = "define_subgraph"): void { const ids = new Set(); values.forEach((value, index) => { const id = Array.isArray(value) ? value[0] : isPlainRecord(value) ? value.id : undefined; if (id === undefined || id === null) { - if (required) throw new OpRejectedError("malformed_op", `define_subgraph: missing id at ${path}[${index}]`); + if (required) throw new OpRejectedError("malformed_op", `${operation}: missing id at ${path}[${index}]`); return; } const normalized = String(id); if (ids.has(normalized)) { - throw new OpRejectedError("malformed_op", `define_subgraph: duplicate normalized id '${normalized}' at ${path}[${index}]`); + throw new OpRejectedError("malformed_op", `${operation}: duplicate normalized id '${normalized}' at ${path}[${index}]`); } ids.add(normalized); }); @@ -822,6 +822,8 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC if (wf["groups"] !== undefined && !Array.isArray(wf["groups"])) { throw new OpRejectedError("malformed_op", "insert_workflow: groups must be an array"); } + assertUniqueNormalizedIds(wf["nodes"] as unknown[], "workflow.nodes", true, "insert_workflow"); + assertUniqueNormalizedIds((wf["links"] as unknown[] | undefined) ?? [], "workflow.links", true, "insert_workflow"); validateDefinitionInputs((subgraphs as unknown[] | undefined) ?? []); wf = remapInsertedWorkflowIds(wf as unknown as import("./types.js").WorkflowJSON, op.op_id) as unknown as Record; const remappedDefinitions = wf["definitions"] as { subgraphs?: unknown[] } | undefined; diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index e39ff0538db..fe25399107d 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -285,17 +285,47 @@ describe("insert_workflow: happy path", () => { describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from applied)", () => { const cases: { name: string; workflow: unknown; code: string; withCatalog: boolean }[] = [ { - name: "duplicate node id inside the template itself", + name: "exact duplicate raw node ids", workflow: { nodes: [{ id: 100, type: "Src" }, { id: 100, type: "Src" }], links: [] }, - code: "node_id_collision", + code: "malformed_op", + withCatalog: true, + }, + { + name: "normalized duplicate raw node ids", + workflow: { nodes: [{ id: 1, type: "Src" }, { id: "1", type: "Src" }], links: [] }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "missing raw node id", + workflow: { nodes: [{ type: "Src" }], links: [] }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "exact duplicate raw link ids", + workflow: { nodes: [], links: [[7, 1, 0, 2, 0, "X"], [7, 1, 0, 2, 0, "X"]] }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "normalized duplicate raw link ids", + workflow: { nodes: [], links: [[1, 1, 0, 2, 0, "X"], ["1", 1, 0, 2, 0, "X"]] }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "missing raw link id", + workflow: { nodes: [], links: [[undefined, 1, 0, 2, 0, "X"]] }, + code: "malformed_op", withCatalog: true, }, { name: "missing workflow", workflow: undefined, code: "malformed_op", withCatalog: true }, { name: "non-object workflow", workflow: "nope", code: "malformed_op", withCatalog: true }, { name: "nodes is not an array", workflow: { nodes: {}, links: [] }, code: "malformed_op", withCatalog: true }, { - name: "node without id/type", - workflow: { nodes: [{ pos: [0, 0] }], links: [] }, + name: "node without type", + workflow: { nodes: [{ id: 100, pos: [0, 0] }], links: [] }, code: "invalid_node_payload", withCatalog: true, }, @@ -311,10 +341,12 @@ describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from appl it(`rejects: ${c.name} → ${c.code}`, () => { const doc = mint(baseWorkflow(), catalog); const before = bytes(doc); + const projectedBefore = project(doc, catalog); const op = insertOp(c.workflow); const result = applyOps(doc, [op], c.withCatalog ? catalog : undefined); expect(rejectedOutcomeWithIndex(result)!.code).toBe(c.code); expect(bytes(doc).equals(before)).toBe(true); + expect(project(doc, catalog)).toEqual(projectedBefore); expect(appliedMap(doc).has(op.op_id)).toBe(false); }); } diff --git a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts index 745508614d0..b9c7cab0444 100644 --- a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts +++ b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts @@ -49,6 +49,7 @@ import { type WorkflowJSON, } from "../src/index.js"; import { appliedMap } from "../src/doc.js"; +import { remapInsertedWorkflowIds } from "../src/remap.js"; const catalog: WidgetCatalog = { types: { @@ -108,6 +109,7 @@ interface Row { /** The rejected outcome code the applier must return. */ code: string; build: () => Op; + seed?: (op: Op) => WorkflowJSON; } const CASES: Row[] = [ @@ -191,15 +193,39 @@ const CASES: Row[] = [ { kind: "insert_workflow", why: "duplicate raw node ids are ambiguous before deterministic remapping", - code: "node_id_collision", + code: "malformed_op", build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [{ id: 1, type: "Src" }, { id: 1, type: "Src" }] } }) as Op, }, { kind: "insert_workflow", why: "duplicate raw link ids are ambiguous before deterministic remapping", - code: "link_id_collision", + code: "malformed_op", build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [], links: [[7, 2, 0, 3, 0, "X"], [7, 2, 0, 3, 0, "X"]] } }) as Op, }, + { + kind: "insert_workflow", + why: "remapped node id collides with the live tree", + code: "node_id_collision", + build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [{ id: 1, type: "Src" }], links: [] } }) as Op, + seed: (op) => { + const workflow = baseWorkflow(); + const remapped = remapInsertedWorkflowIds((op as { workflow: WorkflowJSON }).workflow, op.op_id); + workflow.nodes!.push({ id: remapped.nodes![0]!.id, type: "Src" }); + return workflow; + }, + }, + { + kind: "insert_workflow", + why: "remapped link id collides with the live tree", + code: "link_id_collision", + build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [], links: [[7, 2, 0, 3, 0, "X"]] } }) as Op, + seed: (op) => { + const workflow = baseWorkflow(); + const remapped = remapInsertedWorkflowIds((op as { workflow: WorkflowJSON }).workflow, op.op_id); + workflow.links!.push([remapped.links![0]![0], 2, 0, 3, 0, "X"]); + return workflow; + }, + }, { kind: "insert_workflow", why: "duplicate remapped definition ids violate define_subgraph tree uniqueness", @@ -493,10 +519,10 @@ const KNOWN_KA4_VIOLATIONS: readonly string[] = []; describe("KA-4: a rejected op leaves the doc byte-identical and does not consume its op_id", () => { it.each(CASES.map((c) => [`${c.kind}: ${c.why} → ${c.code}`, c] as const))("%s", (_name, row) => { - const doc = mint(baseWorkflow(), catalog); + const op = row.build(); + const doc = mint(row.seed?.(op) ?? baseWorkflow(), catalog); const before = bytes(doc); const beforeProjection = project(doc, catalog); - const op = row.build(); const res = applyOps(doc, [op], catalog); From 21c4459ce8a37e1e0348842cbcd77c3ab5a72bad Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 20:25:37 -0700 Subject: [PATCH 05/11] test(comfy-multi-player): type indexed rejection value in ka4 byte-identity test Fixes TS7053 reported by the package typecheck gate (tsconfig.test.json) in the follower-contract CI job. --- .../test/ka4-rejection-byte-identity.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts index b9c7cab0444..a7016df8d4f 100644 --- a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts +++ b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts @@ -222,7 +222,8 @@ const CASES: Row[] = [ seed: (op) => { const workflow = baseWorkflow(); const remapped = remapInsertedWorkflowIds((op as { workflow: WorkflowJSON }).workflow, op.op_id); - workflow.links!.push([remapped.links![0]![0], 2, 0, 3, 0, "X"]); + const [remappedLinkId] = remapped.links![0] as [string, number, number, number, number, string]; + workflow.links!.push([remappedLinkId, 2, 0, 3, 0, "X"]); return workflow; }, }, From c925c44128662da73f6e4f288e84389be25ea1b7 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 21:00:18 -0700 Subject: [PATCH 06/11] fix(cmp): validate raw node/link IDs inside carried definitions before remapping --- packages/comfy-multi-player/src/applier.ts | 21 +++-- .../test/insert-workflow.test.ts | 77 +++++++++++++++++++ 2 files changed, 92 insertions(+), 6 deletions(-) diff --git a/packages/comfy-multi-player/src/applier.ts b/packages/comfy-multi-player/src/applier.ts index 6768d3151d4..c634138a8ed 100644 --- a/packages/comfy-multi-player/src/applier.ts +++ b/packages/comfy-multi-player/src/applier.ts @@ -784,8 +784,13 @@ function definitionId(value: unknown): string | undefined { return undefined; } -function validateDefinitionInputs(subgraphs: unknown[]): void { - for (const candidate of subgraphs) { +function validateRawGraphIds(nodes: unknown[], links: unknown[], path: string): void { + assertUniqueNormalizedIds(nodes, `${path}.nodes`, true, "insert_workflow"); + assertUniqueNormalizedIds(links, `${path}.links`, true, "insert_workflow"); +} + +function validateDefinitionInputs(subgraphs: unknown[], path = "workflow.definitions.subgraphs"): void { + subgraphs.forEach((candidate, index) => { if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition must be an object"); } @@ -794,12 +799,17 @@ function validateDefinitionInputs(subgraphs: unknown[]): void { if (id === undefined) { throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition requires a valid id"); } + if (!Array.isArray(sg["nodes"]) || (sg["links"] !== undefined && !Array.isArray(sg["links"]))) { + throw new OpRejectedError("malformed_op", "insert_workflow: definition nodes and links must be arrays"); + } + const definitionPath = `${path}[${index}]`; + validateRawGraphIds(sg["nodes"], (sg["links"] as unknown[] | undefined) ?? [], definitionPath); const nested = (sg["definitions"] as { subgraphs?: unknown } | undefined)?.subgraphs; if (nested !== undefined && !Array.isArray(nested)) { throw new OpRejectedError("malformed_op", "insert_workflow: nested definitions.subgraphs must be an array"); } - if (Array.isArray(nested)) validateDefinitionInputs(nested); - } + if (Array.isArray(nested)) validateDefinitionInputs(nested, `${definitionPath}.definitions.subgraphs`); + }); } function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetCatalog): SuccessfulOutcome { @@ -822,8 +832,7 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC if (wf["groups"] !== undefined && !Array.isArray(wf["groups"])) { throw new OpRejectedError("malformed_op", "insert_workflow: groups must be an array"); } - assertUniqueNormalizedIds(wf["nodes"] as unknown[], "workflow.nodes", true, "insert_workflow"); - assertUniqueNormalizedIds((wf["links"] as unknown[] | undefined) ?? [], "workflow.links", true, "insert_workflow"); + validateRawGraphIds(wf["nodes"] as unknown[], (wf["links"] as unknown[] | undefined) ?? [], "workflow"); validateDefinitionInputs((subgraphs as unknown[] | undefined) ?? []); wf = remapInsertedWorkflowIds(wf as unknown as import("./types.js").WorkflowJSON, op.op_id) as unknown as Record; const remappedDefinitions = wf["definitions"] as { subgraphs?: unknown[] } | undefined; diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index fe25399107d..89faf7bb4ab 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -320,6 +320,81 @@ describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from appl code: "malformed_op", withCatalog: true, }, + { + name: "definition normalized duplicate raw node ids", + workflow: { + nodes: [], + links: [], + definitions: { subgraphs: [{ id: "outer", nodes: [{ id: 1 }, { id: "1" }], links: [] }] }, + }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "definition missing raw node id", + workflow: { + nodes: [], + links: [], + definitions: { subgraphs: [{ id: "outer", nodes: [{ type: "Inner" }], links: [] }] }, + }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "definition normalized duplicate raw link ids", + workflow: { + nodes: [], + links: [], + definitions: { + subgraphs: [ + { + id: "outer", + nodes: [{ id: 10, type: "Inner" }, { id: 11, type: "Inner" }], + links: [[1, 10, 0, 11, 0, "X"], ["1", 10, 0, 11, 0, "X"]], + }, + ], + }, + }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "definition missing raw link id", + workflow: { + nodes: [], + links: [], + definitions: { + subgraphs: [ + { + id: "outer", + nodes: [{ id: 10, type: "Inner" }, { id: 11, type: "Inner" }], + links: [[undefined, 10, 0, 11, 0, "X"]], + }, + ], + }, + }, + code: "malformed_op", + withCatalog: true, + }, + { + name: "nested definition normalized duplicate raw node ids", + workflow: { + nodes: [], + links: [], + definitions: { + subgraphs: [ + { + id: "outer", + nodes: [], + links: [], + definitions: { subgraphs: [{ id: "inner", nodes: [{ id: 1 }, { id: "1" }], links: [] }] }, + }, + ], + }, + }, + code: "malformed_op", + withCatalog: true, + }, { name: "missing workflow", workflow: undefined, code: "malformed_op", withCatalog: true }, { name: "non-object workflow", workflow: "nope", code: "malformed_op", withCatalog: true }, { name: "nodes is not an array", workflow: { nodes: {}, links: [] }, code: "malformed_op", withCatalog: true }, @@ -348,6 +423,8 @@ describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from appl expect(bytes(doc).equals(before)).toBe(true); expect(project(doc, catalog)).toEqual(projectedBefore); expect(appliedMap(doc).has(op.op_id)).toBe(false); + expect(applyOps(doc, [op], c.withCatalog ? catalog : undefined)).toEqual(result); + expect(bytes(doc).equals(before)).toBe(true); }); } From bd69b418dcdee868f38787d61d170508c5df6c70 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 22:32:51 -0700 Subject: [PATCH 07/11] fix(cmp): drop dangling links inside nested insert_workflow definitions --- packages/comfy-multi-player/README.md | 12 +++- packages/comfy-multi-player/src/applier.ts | 11 ++-- packages/comfy-multi-player/src/remap.ts | 30 ++++++++-- .../test/insert-workflow.test.ts | 58 +++++++++++++++++++ 4 files changed, 102 insertions(+), 9 deletions(-) diff --git a/packages/comfy-multi-player/README.md b/packages/comfy-multi-player/README.md index 1b316eb9703..572ece95fb1 100644 --- a/packages/comfy-multi-player/README.md +++ b/packages/comfy-multi-player/README.md @@ -345,7 +345,7 @@ Seven kinds, frozen: | `set_widget` | `node_id`, `widget` (name, never index), `value`, optional `old`; an interior write adds `path` AND `inner_widget` together (`InteriorSetWidgetOp`); a promoted HOST write adds `promoted: {value_index, instance_path, host_widgets_values}` instead — a positional write into a subgraph instance's opaque array (schema Amendment A15) | yes | | `delete_node` | `node_id`, `removed_links` | yes | | `clear` | `removed_nodes` | no | -| `insert_workflow` | `workflow` containing top-level `nodes`, `links`, and optional `definitions.subgraphs`; ids must already be remapped collision-free by the minter | no | +| `insert_workflow` | `workflow` containing required `nodes` and optional `links`, `groups`, and `definitions`; minters submit raw ids and the applier remaps them | no | | `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 @@ -356,6 +356,16 @@ Compile-time assertions in `src/types.ts` pin that `FROZEN_OPS` is exactly is exactly `WireOp["op"]`, and that `BATCHABLE_OPS ⊆ FROZEN_OPS`, so the lists and the unions cannot drift apart silently. +For `insert_workflow`, submit raw node, link, group, and definition ids without +inspecting document state. The applier owns deterministic, tree-wide remapping; +each derived id incorporates the envelope `op_id`, graph scope, id kind, and +original id. A remapped definition id that collides anywhere in the stored +definition tree rejects the operation with `definition_conflict`. Duplicate or +missing raw ids reject it atomically with `malformed_op` at every definition +depth. Links with a missing origin or target node are dropped individually at +every depth, while valid sibling links remain. Private keys beginning with +`__` are recursively removed and never appear in the projected workflow. + **`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the seven kinds it can actually apply. `WireOp` is `Op` plus the deferred kinds a conforming peer may legally put on the wire, and it is what `ApplyFailure.op` and the stamp diff --git a/packages/comfy-multi-player/src/applier.ts b/packages/comfy-multi-player/src/applier.ts index c634138a8ed..4f7341e172f 100644 --- a/packages/comfy-multi-player/src/applier.ts +++ b/packages/comfy-multi-player/src/applier.ts @@ -101,7 +101,7 @@ import { stampsMap, widgetStorageOf, } from "./doc.js"; -import { remapInsertedWorkflowIds } from "./remap.js"; +import { linkHasMissingEndpoint, remapInsertedWorkflowIds } from "./remap.js"; import { sha256Hex } from "./digest.js"; import { CMP_EVENT_SCHEMA_VERSION, emitCmpEvent, type CmpCallContext } from "./events.js"; import { mintDefinition } from "./mint.js"; @@ -790,6 +790,7 @@ function validateRawGraphIds(nodes: unknown[], links: unknown[], path: string): } function validateDefinitionInputs(subgraphs: unknown[], path = "workflow.definitions.subgraphs"): void { + const ids = new Set(); subgraphs.forEach((candidate, index) => { if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition must be an object"); @@ -799,6 +800,10 @@ function validateDefinitionInputs(subgraphs: unknown[], path = "workflow.definit if (id === undefined) { throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition requires a valid id"); } + if (ids.has(id)) { + throw new OpRejectedError("malformed_op", `insert_workflow: duplicate definition id '${id}' at ${path}[${index}]`); + } + ids.add(id); if (!Array.isArray(sg["nodes"]) || (sg["links"] !== undefined && !Array.isArray(sg["links"]))) { throw new OpRejectedError("malformed_op", "insert_workflow: definition nodes and links must be arrays"); } @@ -883,9 +888,7 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC if (compareStampKeys(stamp, incumbent) <= 0) return "lww-dropped"; } seenLinks.add(key); - const source = String(candidate[1]); - const target = String(candidate[3]); - if ((!nodes.has(source) && !seenNodes.has(source)) || (!nodes.has(target) && !seenNodes.has(target))) { + if (linkHasMissingEndpoint(candidate, (id) => nodes.has(String(id)) || seenNodes.has(String(id)))) { continue; } linkWrites.push(candidate); diff --git a/packages/comfy-multi-player/src/remap.ts b/packages/comfy-multi-player/src/remap.ts index f1dfc518984..5cecf1b2064 100644 --- a/packages/comfy-multi-player/src/remap.ts +++ b/packages/comfy-multi-player/src/remap.ts @@ -15,12 +15,34 @@ function derivedDefinitionId(opId: string, scope: string, original: unknown): st return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`; } -function remapGraph(graph: Record, opId: string, scope: string, definitionIds: Map): void { +function linkEndpoints(link: unknown): [unknown, unknown] | undefined { + if (Array.isArray(link) && link[1] !== undefined && link[3] !== undefined) return [link[1], link[3]]; + if (typeof link === "object" && link !== null) { + const record = link as { origin_id?: unknown; target_id?: unknown }; + if (record.origin_id !== undefined && record.target_id !== undefined) return [record.origin_id, record.target_id]; + } + return undefined; +} + +export function linkHasMissingEndpoint(link: unknown, hasNode: (id: unknown) => boolean): boolean { + const endpoints = linkEndpoints(link); + return endpoints !== undefined && (!hasNode(endpoints[0]) || !hasNode(endpoints[1])); +} + +function remapGraph( + graph: Record, + opId: string, + scope: string, + definitionIds: Map, + dropDanglingLinks: boolean, +): void { const nodes = graph["nodes"] as WorkflowNode[]; - const links = (graph["links"] as unknown[] | undefined) ?? []; const nodeIds = new Map(); const linkIds = new Map(); for (const node of nodes) nodeIds.set(node.id, derivedId(opId, scope, "node", node.id)); + const links = ((graph["links"] as unknown[] | undefined) ?? []).filter( + (link) => !dropDanglingLinks || !linkHasMissingEndpoint(link, (id) => nodeIds.has(id)), + ); for (const link of links) { if (Array.isArray(link)) linkIds.set(link[0], derivedId(opId, scope, "link", link[0])); else if (typeof link === "object" && link !== null) { @@ -94,12 +116,12 @@ export function remapInsertedWorkflowIds(wf: WorkflowJSON, opId: string): Workfl for (const definition of definitions) { const original = String(definition["id"]); definition["id"] = definitionIds.get(original)!; - remapGraph(definition, opId, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`, definitionIds); + remapGraph(definition, opId, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`, definitionIds, true); const nested = (definition["definitions"] as { subgraphs?: Array> } | undefined)?.subgraphs ?? []; rewrite(nested, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`); } }; - remapGraph(out, opId, "root", definitionIds); + remapGraph(out, opId, "root", definitionIds, false); rewrite(subgraphs, "root"); return out; } diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index 89faf7bb4ab..b30144b9f89 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -99,6 +99,64 @@ function defIds(wf: WorkflowJSON): string[] { } describe("insert_workflow: happy path", () => { + it("drops a depth-2 object link with a missing endpoint and keeps its valid sibling", () => { + const nested = { + id: "nested", + nodes: [{ id: 1, type: "Src" }, { id: 2, type: "Sink" }], + links: [ + { id: 10, origin_id: 1, origin_slot: 0, target_id: 2, target_slot: 0, type: "valid" }, + { id: 11, origin_id: 1, origin_slot: 0, target_id: 999, target_slot: 0, type: "dangling" }, + ], + }; + const outer = { id: "outer", nodes: [], links: [], definitions: { subgraphs: [nested] } }; + + const remapped = remapInsertedWorkflowIds( + { nodes: [], definitions: { subgraphs: [outer] } } as unknown as WorkflowJSON, + "object-link-op".padEnd(32, "0"), + ) as unknown as { definitions: { subgraphs: Array<{ definitions: { subgraphs: Array<{ links: Array<{ type: string }> }> } }> } }; + const links = remapped.definitions.subgraphs[0]!.definitions.subgraphs[0]!.links; + + expect(links).toHaveLength(1); + expect(links[0]!.type).toBe("valid"); + }); + + it("drops a depth-3 array link with a missing endpoint", () => { + const deepest = { + id: "deepest", + nodes: [{ id: 1, type: "Src" }], + links: [[10, 1, 0, 999, 0, "dangling"]], + }; + const middle = { id: "middle", nodes: [], links: [], definitions: { subgraphs: [deepest] } }; + const outer = { id: "outer", nodes: [], links: [], definitions: { subgraphs: [middle] } }; + + const remapped = remapInsertedWorkflowIds( + { nodes: [], definitions: { subgraphs: [outer] } } as unknown as WorkflowJSON, + "array-link-op".padEnd(32, "0"), + ) as unknown as { definitions: { subgraphs: Array<{ definitions: { subgraphs: Array<{ definitions: { subgraphs: Array<{ links: unknown[] }> } }> } }> } }; + + expect(remapped.definitions.subgraphs[0]!.definitions.subgraphs[0]!.definitions.subgraphs[0]!.links).toEqual([]); + }); + + it("keeps valid links at every nested definition depth", () => { + const deepest = { + id: "deepest", + nodes: [{ id: 1, type: "Src" }, { id: 2, type: "Sink" }], + links: [[10, 1, 0, 2, 0, "valid"]], + }; + const outer = { id: "outer", nodes: [], links: [], definitions: { subgraphs: [deepest] } }; + + const remapped = remapInsertedWorkflowIds( + { nodes: [], definitions: { subgraphs: [outer] } } as unknown as WorkflowJSON, + "valid-link-op".padEnd(32, "0"), + ) as unknown as { definitions: { subgraphs: Array<{ definitions: { subgraphs: Array<{ links: unknown[][] }> } }> } }; + const links = remapped.definitions.subgraphs[0]!.definitions.subgraphs[0]!.links; + + expect(links).toHaveLength(1); + expect(links[0]![5]).toBe("valid"); + expect(links[0]![1]).toEqual(expect.stringContaining("valid-link-op")); + expect(links[0]![3]).toEqual(expect.stringContaining("valid-link-op")); + }); + it("merges template nodes, links and definitions into the doc in one op", () => { const doc = mint(baseWorkflow(), catalog); const op = insertOp(template()); From 35af4f7b256b47d11ca8a51cffe5bc69212d8d4a Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 23:23:12 -0700 Subject: [PATCH 08/11] fix: scope inserted workflow id remapping --- packages/comfy-multi-player/README.md | 5 +- packages/comfy-multi-player/src/remap.ts | 47 ++++++++------- .../test/insert-workflow.test.ts | 57 +++++++++++++++++++ 3 files changed, 89 insertions(+), 20 deletions(-) diff --git a/packages/comfy-multi-player/README.md b/packages/comfy-multi-player/README.md index 572ece95fb1..f3cf0738af3 100644 --- a/packages/comfy-multi-player/README.md +++ b/packages/comfy-multi-player/README.md @@ -359,7 +359,10 @@ and the unions cannot drift apart silently. For `insert_workflow`, submit raw node, link, group, and definition ids without inspecting document state. The applier owns deterministic, tree-wide remapping; each derived id incorporates the envelope `op_id`, graph scope, id kind, and -original id. A remapped definition id that collides anywhere in the stored +original id. Numeric and string aliases with the same normalized id refer to +the same node, including in link endpoints. Definition ids are scoped to their +containing graph, so repeated nested ids in separate branches derive distinct +ids. A remapped definition id that collides anywhere in the stored definition tree rejects the operation with `definition_conflict`. Duplicate or missing raw ids reject it atomically with `malformed_op` at every definition depth. Links with a missing origin or target node are dropped individually at diff --git a/packages/comfy-multi-player/src/remap.ts b/packages/comfy-multi-player/src/remap.ts index 5cecf1b2064..d2eb5ba7e53 100644 --- a/packages/comfy-multi-player/src/remap.ts +++ b/packages/comfy-multi-player/src/remap.ts @@ -24,6 +24,10 @@ function linkEndpoints(link: unknown): [unknown, unknown] | undefined { return undefined; } +function normalizedId(id: unknown): string { + return typeof id === "string" ? id : String(id); +} + export function linkHasMissingEndpoint(link: unknown, hasNode: (id: unknown) => boolean): boolean { const endpoints = linkEndpoints(link); return endpoints !== undefined && (!hasNode(endpoints[0]) || !hasNode(endpoints[1])); @@ -37,28 +41,29 @@ function remapGraph( dropDanglingLinks: boolean, ): void { const nodes = graph["nodes"] as WorkflowNode[]; - const nodeIds = new Map(); - const linkIds = new Map(); - for (const node of nodes) nodeIds.set(node.id, derivedId(opId, scope, "node", node.id)); + const nodeIds = new Map(); + const linkIds = new Map(); + // Numeric and string aliases normalized by validation name the same node. + for (const node of nodes) nodeIds.set(normalizedId(node.id), derivedId(opId, scope, "node", node.id)); const links = ((graph["links"] as unknown[] | undefined) ?? []).filter( - (link) => !dropDanglingLinks || !linkHasMissingEndpoint(link, (id) => nodeIds.has(id)), + (link) => !dropDanglingLinks || !linkHasMissingEndpoint(link, (id) => nodeIds.has(normalizedId(id))), ); for (const link of links) { - if (Array.isArray(link)) linkIds.set(link[0], derivedId(opId, scope, "link", link[0])); + if (Array.isArray(link)) linkIds.set(normalizedId(link[0]), derivedId(opId, scope, "link", link[0])); else if (typeof link === "object" && link !== null) { const record = link as { id?: unknown }; - linkIds.set(record.id, derivedId(opId, scope, "link", record.id)); + linkIds.set(normalizedId(record.id), derivedId(opId, scope, "link", record.id)); } } for (const node of nodes) { - node.id = nodeIds.get(node.id)!; + node.id = nodeIds.get(normalizedId(node.id))!; if (definitionIds.has(node.type)) node.type = definitionIds.get(node.type)!; if (Array.isArray(node.inputs)) { for (const input of node.inputs) { if (typeof input === "object" && input !== null && "link" in input) { const record = input as { link?: unknown }; - if (linkIds.has(record.link)) record.link = linkIds.get(record.link); + if (linkIds.has(normalizedId(record.link))) record.link = linkIds.get(normalizedId(record.link)); } } } @@ -66,21 +71,21 @@ function remapGraph( for (const output of node.outputs) { if (typeof output === "object" && output !== null && Array.isArray((output as { links?: unknown }).links)) { const record = output as { links: unknown[] }; - record.links = record.links.map((id) => linkIds.get(id) ?? id); + record.links = record.links.map((id) => linkIds.get(normalizedId(id)) ?? id); } } } } graph["links"] = links.map((link) => { if (Array.isArray(link)) { - link[0] = linkIds.get(link[0]) ?? link[0]; - link[1] = nodeIds.get(link[1]) ?? link[1]; - link[3] = nodeIds.get(link[3]) ?? link[3]; + link[0] = linkIds.get(normalizedId(link[0])) ?? link[0]; + link[1] = nodeIds.get(normalizedId(link[1])) ?? link[1]; + link[3] = nodeIds.get(normalizedId(link[3])) ?? link[3]; } else if (typeof link === "object" && link !== null) { const record = link as { id?: unknown; origin_id?: unknown; target_id?: unknown }; - record.id = linkIds.get(record.id) ?? record.id; - record.origin_id = nodeIds.get(record.origin_id) ?? record.origin_id; - record.target_id = nodeIds.get(record.target_id) ?? record.target_id; + record.id = linkIds.get(normalizedId(record.id)) ?? record.id; + record.origin_id = nodeIds.get(normalizedId(record.origin_id)) ?? record.origin_id; + record.target_id = nodeIds.get(normalizedId(record.target_id)) ?? record.target_id; } return link; }); @@ -101,8 +106,10 @@ export function remapInsertedWorkflowIds(wf: WorkflowJSON, opId: string): Workfl out.links ??= []; out.groups ??= []; const subgraphs = (out.definitions?.subgraphs ?? []) as Array>; - const definitionIds = new Map(); + const definitionIdsByScope = new Map>(); const collect = (definitions: Array>, scope: string): void => { + const definitionIds = new Map(); + definitionIdsByScope.set(scope, definitionIds); for (const definition of definitions) { const original = String(definition["id"]); const remapped = derivedDefinitionId(opId, scope, original); @@ -113,15 +120,17 @@ export function remapInsertedWorkflowIds(wf: WorkflowJSON, opId: string): Workfl }; collect(subgraphs, "root"); const rewrite = (definitions: Array>, scope: string): void => { + const definitionIds = definitionIdsByScope.get(scope)!; for (const definition of definitions) { const original = String(definition["id"]); definition["id"] = definitionIds.get(original)!; - remapGraph(definition, opId, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`, definitionIds, true); + const definitionScope = `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`; + remapGraph(definition, opId, definitionScope, definitionIdsByScope.get(definitionScope)!, true); const nested = (definition["definitions"] as { subgraphs?: Array> } | undefined)?.subgraphs ?? []; - rewrite(nested, `${scope}/definition:${encodeURIComponent(JSON.stringify(original))}`); + rewrite(nested, definitionScope); } }; - remapGraph(out, opId, "root", definitionIds, false); + remapGraph(out, opId, "root", definitionIdsByScope.get("root")!, false); rewrite(subgraphs, "root"); return out; } diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index b30144b9f89..02ca02ea902 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -99,6 +99,63 @@ function defIds(wf: WorkflowJSON): string[] { } describe("insert_workflow: happy path", () => { + it("resolves string link endpoints to normalized numeric node ids", () => { + const doc = mint(baseWorkflow(), catalog); + const op = insertOp({ + nodes: [{ id: 1, type: "Src", title: "alias source" }, { id: 2, type: "Sink", title: "alias sink" }], + links: [[3, "1", 0, "2", 0, "alias"]], + }); + + expect(applyOps(doc, [op], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + const workflow = project(doc, catalog); + const source = workflow.nodes!.find((node) => node.title === "alias source")!; + const sink = workflow.nodes!.find((node) => node.title === "alias sink")!; + const link = workflow.links!.find((candidate) => (candidate as unknown[])[5] === "alias") as unknown[]; + expect(link).toBeDefined(); + expect(link[1]).toBe(source.id); + expect(link[3]).toBe(sink.id); + }); + + it("scopes repeated nested definition ids to their sibling definition paths", () => { + const doc = mint(baseWorkflow(), catalog); + const nested = (name: string) => ({ id: "shared", name, nodes: [], links: [] }); + const op = insertOp({ + nodes: [], + links: [], + definitions: { + subgraphs: [ + { + id: "left", + name: "Left", + nodes: [{ id: 1, type: "shared" }], + links: [], + definitions: { subgraphs: [nested("Left shared")] }, + }, + { + id: "right", + name: "Right", + nodes: [{ id: 1, type: "shared" }], + links: [], + definitions: { subgraphs: [nested("Right shared")] }, + }, + ], + }, + }); + + expect(applyOps(doc, [op], catalog).outcomes[0]).toMatchObject({ outcome: "applied" }); + const definitions = project(doc, catalog).definitions!.subgraphs! as Array>; + const left = definitions.find((definition) => definition["name"] === "Left")!; + const right = definitions.find((definition) => definition["name"] === "Right")!; + const nestedId = (definition: Record): string => + String(((definition["definitions"] as { subgraphs: Array<{ id: unknown }> }).subgraphs[0]!).id); + const hostType = (definition: Record): string => + String(((definition["nodes"] as Array<{ type: unknown }>)[0]!).type); + + expect(nestedId(left)).not.toBe(nestedId(right)); + expect(hostType(left)).toBe(nestedId(left)); + expect(hostType(right)).toBe(nestedId(right)); + }); + it("drops a depth-2 object link with a missing endpoint and keeps its valid sibling", () => { const nested = { id: "nested", From ba68902c0b26390e99c8011e6145f3cce4922bea Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 11 Sep 2026 23:52:27 -0700 Subject: [PATCH 09/11] fix(cmp): scrub dropped dangling links from slot refs at every depth; fix README frozen-op count --- packages/comfy-multi-player/README.md | 2 +- packages/comfy-multi-player/src/remap.ts | 32 +++++--- .../test/insert-workflow.test.ts | 76 +++++++++++++++++++ .../test/ka4-rejection-byte-identity.test.ts | 7 +- 4 files changed, 104 insertions(+), 13 deletions(-) diff --git a/packages/comfy-multi-player/README.md b/packages/comfy-multi-player/README.md index f3cf0738af3..49a526b8e23 100644 --- a/packages/comfy-multi-player/README.md +++ b/packages/comfy-multi-player/README.md @@ -334,7 +334,7 @@ Every op carries the same envelope, minted by its creator before dispatch: } ``` -Seven kinds, frozen: +Eight kinds, frozen: | Kind | Payload beyond the envelope | Batchable (authoring) | |---|---|---| diff --git a/packages/comfy-multi-player/src/remap.ts b/packages/comfy-multi-player/src/remap.ts index d2eb5ba7e53..0d04cedd980 100644 --- a/packages/comfy-multi-player/src/remap.ts +++ b/packages/comfy-multi-player/src/remap.ts @@ -28,6 +28,12 @@ function normalizedId(id: unknown): string { return typeof id === "string" ? id : String(id); } +function linkId(link: unknown): unknown { + if (Array.isArray(link)) return link[0]; + if (typeof link === "object" && link !== null) return (link as { id?: unknown }).id; + return undefined; +} + export function linkHasMissingEndpoint(link: unknown, hasNode: (id: unknown) => boolean): boolean { const endpoints = linkEndpoints(link); return endpoints !== undefined && (!hasNode(endpoints[0]) || !hasNode(endpoints[1])); @@ -45,15 +51,15 @@ function remapGraph( const linkIds = new Map(); // Numeric and string aliases normalized by validation name the same node. for (const node of nodes) nodeIds.set(normalizedId(node.id), derivedId(opId, scope, "node", node.id)); - const links = ((graph["links"] as unknown[] | undefined) ?? []).filter( - (link) => !dropDanglingLinks || !linkHasMissingEndpoint(link, (id) => nodeIds.has(normalizedId(id))), - ); + const droppedLinkIds = new Set(); + const links = ((graph["links"] as unknown[] | undefined) ?? []).filter((link) => { + const dropped = dropDanglingLinks && linkHasMissingEndpoint(link, (id) => nodeIds.has(normalizedId(id))); + if (dropped) droppedLinkIds.add(normalizedId(linkId(link))); + return !dropped; + }); for (const link of links) { - if (Array.isArray(link)) linkIds.set(normalizedId(link[0]), derivedId(opId, scope, "link", link[0])); - else if (typeof link === "object" && link !== null) { - const record = link as { id?: unknown }; - linkIds.set(normalizedId(record.id), derivedId(opId, scope, "link", record.id)); - } + const id = linkId(link); + linkIds.set(normalizedId(id), derivedId(opId, scope, "link", id)); } for (const node of nodes) { @@ -63,7 +69,9 @@ function remapGraph( for (const input of node.inputs) { if (typeof input === "object" && input !== null && "link" in input) { const record = input as { link?: unknown }; - if (linkIds.has(normalizedId(record.link))) record.link = linkIds.get(normalizedId(record.link)); + const id = normalizedId(record.link); + if (droppedLinkIds.has(id)) record.link = null; + else if (linkIds.has(id)) record.link = linkIds.get(id); } } } @@ -71,7 +79,9 @@ function remapGraph( for (const output of node.outputs) { if (typeof output === "object" && output !== null && Array.isArray((output as { links?: unknown }).links)) { const record = output as { links: unknown[] }; - record.links = record.links.map((id) => linkIds.get(normalizedId(id)) ?? id); + record.links = record.links + .filter((id) => !droppedLinkIds.has(normalizedId(id))) + .map((id) => linkIds.get(normalizedId(id)) ?? id); } } } @@ -130,7 +140,7 @@ export function remapInsertedWorkflowIds(wf: WorkflowJSON, opId: string): Workfl rewrite(nested, definitionScope); } }; - remapGraph(out, opId, "root", definitionIdsByScope.get("root")!, false); + remapGraph(out, opId, "root", definitionIdsByScope.get("root")!, true); rewrite(subgraphs, "root"); return out; } diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index 02ca02ea902..4da9d3099c4 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -177,6 +177,82 @@ describe("insert_workflow: happy path", () => { expect(links[0]!.type).toBe("valid"); }); + it("scrubs a dropped depth-2 link from node slot references", () => { + const nested = { + id: "nested", + nodes: [ + { id: 1, type: "Src", outputs: [{ name: "out", links: [11, 10] }] }, + { id: 2, type: "Sink", inputs: [{ name: "in", link: 11 }] }, + ], + links: [ + [10, 1, 0, 2, 0, "valid"], + [11, 999, 0, 2, 0, "dangling"], + ], + }; + const outer = { id: "outer", nodes: [], links: [], definitions: { subgraphs: [nested] } }; + + const remapped = remapInsertedWorkflowIds( + { nodes: [], definitions: { subgraphs: [outer] } } as unknown as WorkflowJSON, + "nested-slot-op".padEnd(32, "0"), + ) as unknown as { + definitions: { + subgraphs: Array<{ + definitions: { subgraphs: Array<{ nodes: Array<{ inputs?: Array<{ link: unknown }>; outputs?: Array<{ links: unknown[] }> }>; links: unknown[][] }> }; + }>; + }; + }; + const graph = remapped.definitions.subgraphs[0]!.definitions.subgraphs[0]!; + + expect(graph.nodes[0]!.outputs![0]!.links).toEqual([graph.links[0]![0]]); + expect(graph.nodes[1]!.inputs![0]!.link).toBeNull(); + }); + + it("scrubs a dropped top-level link from node slot references", () => { + const remapped = remapInsertedWorkflowIds( + { + nodes: [ + { id: 1, type: "Src", outputs: [{ name: "out", links: [11, 10] }] }, + { id: 2, type: "Sink", inputs: [{ name: "in", link: 11 }] }, + ], + links: [ + [10, 1, 0, 2, 0, "valid"], + [11, 999, 0, 2, 0, "dangling"], + ], + } as unknown as WorkflowJSON, + "top-level-slot-op".padEnd(32, "0"), + ); + + const graph = remapped as unknown as { + nodes: Array<{ inputs?: Array<{ link: unknown }>; outputs?: Array<{ links: unknown[] }> }>; + links: unknown[][]; + }; + expect(graph.nodes[0]!.outputs![0]!.links).toEqual([graph.links[0]![0]]); + expect(graph.nodes[1]!.inputs![0]!.link).toBeNull(); + }); + + it("normalizes string aliases when scrubbing dropped link slot references", () => { + const remapped = remapInsertedWorkflowIds( + { + nodes: [ + { id: 1, type: "Src", outputs: [{ name: "out", links: ["11", 10] }] }, + { id: 2, type: "Sink", inputs: [{ name: "in", link: "11" }] }, + ], + links: [ + [10, 1, 0, 2, 0, "valid"], + [11, 999, 0, 2, 0, "dangling"], + ], + } as unknown as WorkflowJSON, + "string-alias-slot-op".padEnd(32, "0"), + ); + + const graph = remapped as unknown as { + nodes: Array<{ inputs?: Array<{ link: unknown }>; outputs?: Array<{ links: unknown[] }> }>; + links: unknown[][]; + }; + expect(graph.nodes[0]!.outputs![0]!.links).toEqual([graph.links[0]![0]]); + expect(graph.nodes[1]!.inputs![0]!.link).toBeNull(); + }); + it("drops a depth-3 array link with a missing endpoint", () => { const deepest = { id: "deepest", diff --git a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts index a7016df8d4f..aee050a3ecd 100644 --- a/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts +++ b/packages/comfy-multi-player/test/ka4-rejection-byte-identity.test.ts @@ -218,7 +218,12 @@ const CASES: Row[] = [ kind: "insert_workflow", why: "remapped link id collides with the live tree", code: "link_id_collision", - build: () => ({ op: "insert_workflow", ...env(), workflow: { nodes: [], links: [[7, 2, 0, 3, 0, "X"]] } }) as Op, + build: () => + ({ + op: "insert_workflow", + ...env(), + workflow: { nodes: [{ id: 2, type: "Src" }, { id: 3, type: "Sink" }], links: [[7, 2, 0, 3, 0, "X"]] }, + }) as Op, seed: (op) => { const workflow = baseWorkflow(); const remapped = remapInsertedWorkflowIds((op as { workflow: WorkflowJSON }).workflow, op.op_id); From 318fadd4e8b10bbe144aef5aeffbba301cbf6576 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Sat, 12 Sep 2026 00:26:26 -0700 Subject: [PATCH 10/11] fix(cmp): keep workflow id remapping internal Addresses review feedback:\nhttps://github.com/Comfy-Org/ComfyUI_frontend/pull/17501#discussion_r3995503934\nhttps://github.com/Comfy-Org/ComfyUI_frontend/pull/17501#discussion_r3995503936 --- packages/comfy-multi-player/CHANGELOG.md | 5 +- packages/comfy-multi-player/README.md | 4 +- packages/comfy-multi-player/src/index.ts | 3 +- packages/comfy-multi-player/src/remap.ts | 48 ------------------- packages/comfy-multi-player/src/stamps.ts | 2 +- packages/comfy-multi-player/src/types.ts | 4 +- .../test/insert-workflow.test.ts | 42 +--------------- .../test/readonly-surface.test.ts | 1 - .../test/type-negatives.test.ts | 2 +- .../test/types/invalid-states.negative.ts | 4 ++ 10 files changed, 14 insertions(+), 101 deletions(-) diff --git a/packages/comfy-multi-player/CHANGELOG.md b/packages/comfy-multi-player/CHANGELOG.md index 233185b0efc..affd08cce05 100644 --- a/packages/comfy-multi-player/CHANGELOG.md +++ b/packages/comfy-multi-player/CHANGELOG.md @@ -9,9 +9,8 @@ this package uses semantic versioning. ### Added -- Added the standalone `insert_workflow` op and `remapWorkflowIds` helper for - deterministic, collision-safe workflow-template insertion, including - deterministic whole-tree id remapping keyed by the operation envelope id. +- Added the standalone `insert_workflow` op with deterministic, collision-safe + whole-tree id remapping keyed by the operation envelope id. ## 0.2.0 - 2026-08-30 diff --git a/packages/comfy-multi-player/README.md b/packages/comfy-multi-player/README.md index 49a526b8e23..a403038068a 100644 --- a/packages/comfy-multi-player/README.md +++ b/packages/comfy-multi-player/README.md @@ -369,7 +369,7 @@ depth. Links with a missing origin or target node are dropped individually at every depth, while valid sibling links remain. Private keys beginning with `__` are recursively removed and never appear in the projected workflow. -**`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the seven kinds it +**`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the eight kinds it can actually apply. `WireOp` is `Op` plus the deferred kinds a conforming peer may legally put on the wire, and it is what `ApplyFailure.op` and the stamp helpers take: a rejected `reset_doc` really does land in `failed.op`, so typing @@ -424,7 +424,7 @@ implementation to replay it with no failures. If you are building a submission surface in front of the applier, that admission layer is where `BATCHABLE_OPS` belongs. `test/batch-policy.test.ts` pins all of this. -The normative definition of the original op envelope and six kinds is +The normative definition of the op envelope and eight kinds is `docs/op-vocabulary-v1.md` in [comfy-cli](https://github.com/Comfy-Org/comfy-cli), which mints these ops on the agent side. The `Op` types here mirror those minted shapes field for field; diff --git a/packages/comfy-multi-player/src/index.ts b/packages/comfy-multi-player/src/index.ts index 263a979e068..c9a1811d3d7 100644 --- a/packages/comfy-multi-player/src/index.ts +++ b/packages/comfy-multi-player/src/index.ts @@ -2,7 +2,7 @@ * @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 op vocabulary is frozen at seven kinds; the + * and the server doc host. The op vocabulary is frozen at eight kinds; 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 @@ -55,7 +55,6 @@ export { type CmpEventSink, type CmpEventType, } from "./events.js"; -export { remapWorkflowIds, type RemapWorkflowIdsOptions } from "./remap.js"; /** * ADR-004 follower read-surface. These helpers expose the established wire * layout only so the frontend follower can consume host updates. They are diff --git a/packages/comfy-multi-player/src/remap.ts b/packages/comfy-multi-player/src/remap.ts index 0d04cedd980..48b2d279db3 100644 --- a/packages/comfy-multi-player/src/remap.ts +++ b/packages/comfy-multi-player/src/remap.ts @@ -1,11 +1,6 @@ import type { WorkflowJSON, WorkflowNode } from "./types.js"; import { sha256Hex } from "./digest.js"; -export interface RemapWorkflowIdsOptions { - nodeIdStart: number; - linkIdStart: number; -} - function derivedId(opId: string, scope: string, kind: string, original: unknown): string { return `insert:${opId}:${scope}:${kind}:${encodeURIComponent(JSON.stringify(original))}`; } @@ -144,46 +139,3 @@ export function remapInsertedWorkflowIds(wf: WorkflowJSON, opId: string): Workfl rewrite(subgraphs, "root"); return out; } - -/** Remap only the top-level graph namespace; definition interiors are independent graphs. */ -export function remapWorkflowIds(wf: WorkflowJSON, opts: RemapWorkflowIdsOptions): WorkflowJSON { - const out = structuredClone(wf); - const nodeIds = new Map(); - const linkIds = new Map(); - - out.nodes.forEach((node, index) => nodeIds.set(node.id, opts.nodeIdStart + index)); - out.links.forEach((link, index) => { - if (Array.isArray(link)) linkIds.set(link[0], opts.linkIdStart + index); - }); - - out.nodes = out.nodes.map((node): WorkflowNode => { - const remapped = node as WorkflowNode; - remapped.id = nodeIds.get(node.id)!; - if (Array.isArray(remapped.inputs)) { - for (const input of remapped.inputs) { - if (typeof input === "object" && input !== null && "link" in input) { - const record = input as { link?: unknown }; - if (linkIds.has(record.link)) record.link = linkIds.get(record.link); - } - } - } - if (Array.isArray(remapped.outputs)) { - for (const output of remapped.outputs) { - if (typeof output === "object" && output !== null && Array.isArray((output as { links?: unknown }).links)) { - const record = output as { links: unknown[] }; - record.links = record.links.map((id) => linkIds.get(id) ?? id); - } - } - } - return remapped; - }); - - out.links = out.links.map((link) => { - if (!Array.isArray(link)) return link; - link[0] = linkIds.get(link[0]) ?? link[0]; - link[1] = nodeIds.get(link[1]) ?? link[1]; - link[3] = nodeIds.get(link[3]) ?? link[3]; - return link; - }); - return out; -} diff --git a/packages/comfy-multi-player/src/stamps.ts b/packages/comfy-multi-player/src/stamps.ts index da36e79d4f8..c505da5ff97 100644 --- a/packages/comfy-multi-player/src/stamps.ts +++ b/packages/comfy-multi-player/src/stamps.ts @@ -129,7 +129,7 @@ export function writeTarget(op: WireOp): unknown[] { return ["definition", op.subgraph_id]; default: // Exhaustiveness guard (issue #21): with every `WireOp` member cased - // above — the six `Op` kinds plus the deferred `reset_doc` — `op` is + // above — the eight `Op` kinds plus the deferred `reset_doc` — `op` is // `never` here, so adding a kind to EITHER union fails `tsc` at this // line until it is given a write target. // diff --git a/packages/comfy-multi-player/src/types.ts b/packages/comfy-multi-player/src/types.ts index e3fd9b7bd83..3b555cca9f8 100644 --- a/packages/comfy-multi-player/src/types.ts +++ b/packages/comfy-multi-player/src/types.ts @@ -1,7 +1,7 @@ /** * Types and constants for @comfyorg/comfy-multi-player. * - * The op vocabulary is frozen at six kinds; the normative contract is + * The op vocabulary is frozen at eight kinds; 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`), pinned by SHA at comfy-cli * `7e732242d971daf0d2d30f22f997abfacd78986e` (FC-10: never by branch — the @@ -136,7 +136,7 @@ export interface OpBase { } // --------------------------------------------------------------------------- -// The eight declared op kinds: seven implemented (`Op`) plus the deferred +// The nine declared op kinds: eight implemented (`Op`) plus the deferred // `reset_doc` (`DeferredOp`); together `WireOp`. "Frozen" now means // implemented — `FROZEN_OPS` is pinned to `Op["op"]` exactly (issue #17). // --------------------------------------------------------------------------- diff --git a/packages/comfy-multi-player/test/insert-workflow.test.ts b/packages/comfy-multi-player/test/insert-workflow.test.ts index 4da9d3099c4..40ff8908df5 100644 --- a/packages/comfy-multi-player/test/insert-workflow.test.ts +++ b/packages/comfy-multi-player/test/insert-workflow.test.ts @@ -6,7 +6,7 @@ * only reach a live doc through a whole-doc reseed, because every other op * schema rejects definition-bearing fields (KA-11). This op carries the * template as an opaque payload the applier merges under the same guards the - * six existing kinds obey: collision-free ids (validated BEFORE any mutation, + * seven existing kinds obey: collision-free ids (validated BEFORE any mutation, * KA-4), definition dedupe/fork by content hash, exact-replay no-op through * the op_id gate, and byte-identical doc on rejection. * @@ -22,7 +22,6 @@ import { applyOps, mint, project, - remapWorkflowIds, type Op, type WidgetCatalog, type WorkflowJSON, @@ -712,42 +711,3 @@ describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from appl expect(definitions.find((definition) => definition.id === "def-1-deadbeef")!.name).toBe("Occupied"); }); }); - -describe("remapWorkflowIds (minter-side helper)", () => { - it("shifts node and link ids and rewrites every reference, leaving definitions untouched", () => { - const out = remapWorkflowIds(template(), { nodeIdStart: 8, linkIdStart: 8 }); - expect(ids(out)).toEqual([8, 9]); - expect(linkIds(out)).toEqual([8]); - const link = out.links![0] as unknown[]; - expect(link.slice(0, 5)).toEqual([8, 8, 0, 9, 0]); - expect(out.nodes![1]!.inputs).toEqual([{ name: "a", link: 8 }]); - expect(defIds(out)).toEqual(["def-2"]); - // Interior definition ids are a separate namespace: unchanged. - const inner = (out as { definitions: { subgraphs: { nodes: { id: unknown }[] }[] } }).definitions.subgraphs[0]!; - expect(inner.nodes[0]!.id).toBe(5); - }); - - it("rewrites output links arrays and does not mutate its input", () => { - const tpl = { - nodes: [ - { id: 1, type: "Src", outputs: [{ name: "o", links: [1, 2] }] }, - { id: 2, type: "Sink", inputs: [{ name: "in", link: 1 }] }, - { id: 3, type: "Sink", inputs: [{ name: "in", link: 2 }] }, - ], - links: [ - [1, 1, 0, 2, 0, "X"], - [2, 1, 0, 3, 0, "X"], - ], - } as unknown as WorkflowJSON; - const snapshot = structuredClone(tpl); - const out = remapWorkflowIds(tpl, { nodeIdStart: 10, linkIdStart: 20 }); - expect(tpl).toEqual(snapshot); - expect(ids(out)).toEqual([10, 11, 12]); - expect(out.nodes![0]!.outputs).toEqual([{ name: "o", links: [20, 21] }]); - expect(out.nodes![2]!.inputs).toEqual([{ name: "in", link: 21 }]); - expect(out.links).toEqual([ - [20, 10, 0, 11, 0, "X"], - [21, 10, 0, 12, 0, "X"], - ]); - }); -}); diff --git a/packages/comfy-multi-player/test/readonly-surface.test.ts b/packages/comfy-multi-player/test/readonly-surface.test.ts index 473bf7cb574..26ae06cad30 100644 --- a/packages/comfy-multi-player/test/readonly-surface.test.ts +++ b/packages/comfy-multi-player/test/readonly-surface.test.ts @@ -748,7 +748,6 @@ describe("read-only surface — classification", () => { "observedDocCounter", "validateLamportCounter", "observeLamport", - "remapWorkflowIds", "tickLamport", "persistLamportTick", "freezeLamportEnvelope", diff --git a/packages/comfy-multi-player/test/type-negatives.test.ts b/packages/comfy-multi-player/test/type-negatives.test.ts index ebd91844690..6fe5256d0e7 100644 --- a/packages/comfy-multi-player/test/type-negatives.test.ts +++ b/packages/comfy-multi-player/test/type-negatives.test.ts @@ -49,7 +49,7 @@ const negatives = join(root, "test", "types", "invalid-states.negative.ts"); * tests green. An exact count also means ADDING a state without updating this * constant fails, which is the reminder you want. */ -const EXPECTED_DIRECTIVES = 13; +const EXPECTED_DIRECTIVES = 14; const DIRECTIVE = /^[ \t]*\/\/ @ts-expect-error\b/gm; describe("invalid op states are unrepresentable (issue #17)", () => { diff --git a/packages/comfy-multi-player/test/types/invalid-states.negative.ts b/packages/comfy-multi-player/test/types/invalid-states.negative.ts index 1e350d2b337..9f03c087077 100644 --- a/packages/comfy-multi-player/test/types/invalid-states.negative.ts +++ b/packages/comfy-multi-player/test/types/invalid-states.negative.ts @@ -34,6 +34,10 @@ import type { WireOp, } from "../../src/index.js"; +// ID remapping belongs to the applier and is derived from the op envelope. +// @ts-expect-error producer-side document-state-dependent remapping is not public. +import { remapWorkflowIds } from "../../src/index.js"; + const env = { op_id: "0".repeat(32), actor: "agent:t:1", From 8491ba33fafadfc3c02be47adde167d06ab586c7 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Sat, 12 Sep 2026 01:05:50 -0700 Subject: [PATCH 11/11] fix(cmp): retain nested widget edits across define_subgraph digest replacement Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/17501#discussion_r3995580949 --- packages/comfy-multi-player/src/applier.ts | 27 ++++++++++++++---- .../test/define-subgraph.test.ts | 28 +++++++++++++++++++ 2 files changed, 49 insertions(+), 6 deletions(-) diff --git a/packages/comfy-multi-player/src/applier.ts b/packages/comfy-multi-player/src/applier.ts index 4f7341e172f..236bcb66988 100644 --- a/packages/comfy-multi-player/src/applier.ts +++ b/packages/comfy-multi-player/src/applier.ts @@ -563,15 +563,15 @@ function definitionWidgetEdits( if (!Array.isArray(target) || target[0] !== "widget" || !Array.isArray(target[1])) continue; const path = target[1].map(String); const widget = target[3]; - if (path.length !== 2 || typeof widget !== "string") continue; - const oldNode = definitionNode(existing, path[0]!, path[1]!); - if (!oldNode) continue; - const oldWidgets = oldNode.get("widgets"); + if (path.length < 2 || typeof widget !== "string") continue; + const resolved = definitionNodeAtPath(existing, path); + if (!resolved) continue; + const oldWidgets = resolved.node.get("widgets"); if (oldWidgets instanceof Y.Map && oldWidgets.has(widget)) { edits.push({ targetKey, - definitionId: path[0]!, - nodeId: path[1]!, + definitionId: resolved.definitionId, + nodeId: path.at(-1)!, widget, value: structuredClone(oldWidgets.get(widget)), }); @@ -580,6 +580,21 @@ function definitionWidgetEdits( return edits; } +function definitionNodeAtPath( + root: Y.Map, + path: string[], +): { definitionId: string; node: Y.Map } | null { + let definitionId = path[0]!; + let node = definitionNode(root, definitionId, path[1]!); + if (!node) return null; + for (const nodeId of path.slice(2)) { + definitionId = String(node.get("type")); + node = definitionNode(root, definitionId, nodeId); + if (!node) return null; + } + return { definitionId, node }; +} + function restoreDefinitionWidgetEdits( doc: Y.Doc, replacement: Y.Map, diff --git a/packages/comfy-multi-player/test/define-subgraph.test.ts b/packages/comfy-multi-player/test/define-subgraph.test.ts index 13f6e936268..a07c217dfb8 100644 --- a/packages/comfy-multi-player/test/define-subgraph.test.ts +++ b/packages/comfy-multi-player/test/define-subgraph.test.ts @@ -172,6 +172,34 @@ describe("define_subgraph application", () => { expect(projected.nodes[0]!.widgets_values).toEqual([9]) }) + it("preserves nested widget edits across a digest-winning replacement in either legal order", () => { + const nestedId = "abcdefab-cdef-4abc-8def-abcdefabcdef" + const incumbent = { + ...definition(), + nodes: [{ id: 20, type: nestedId, inputs: [], outputs: [], widgets_values: [] }], + definitions: { subgraphs: [definition(nestedId, 1)] }, + } + const replacement = winningReplacement(incumbent, { + ...incumbent, + definitions: { subgraphs: [definition(nestedId, 2)] }, + }) + const first = { ...define(), subgraph_definition: incumbent } + const second = { ...define(), subgraph_definition: replacement } + const edit = { + op: "set_widget", ...envelope(), node_id: 10, path: [subgraphId, "20", "10"], inner_widget: "value", widget: "value", value: 80, + } as Op + + const projections = [[first, edit, second], [second, edit, first]].map((ops) => { + const doc = empty() + for (const op of ops) applyOps(doc, [op], catalog) + return project(doc, catalog) + }) + + expect(projections[0]).toEqual(projections[1]) + const projected = (projections[0]!.definitions as { subgraphs: Array<{ definitions: { subgraphs: Array<{ nodes: Array<{ widgets_values: unknown[] }> }> } }> }).subgraphs[0]! + expect(projected.definitions.subgraphs[0]!.nodes[0]!.widgets_values).toEqual([80]) + }) + it("rejects an edit to a node that exists only in the replaced definition", () => { const first = { ...definition(subgraphId, 2),