From b3f44e471844f0629099294c7ddfb1fd36a6a94d Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 16 Sep 2026 22:32:37 -0700 Subject: [PATCH 1/6] feat: support scoped interior connects --- src/applier.ts | 150 ++++++++++++++- src/stamps.ts | 3 + src/types.ts | 2 + test/interior-connect.regression.test.ts | 222 +++++++++++++++++++++++ 4 files changed, 372 insertions(+), 5 deletions(-) create mode 100644 test/interior-connect.regression.test.ts diff --git a/src/applier.ts b/src/applier.ts index 2cf4f110..b1883a57 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1171,6 +1171,15 @@ function requireOutputSlot(src: Y.Map, op: ConnectOp): Y.Array function requireOpOnlyValid(op: ConnectOp): void { requireOutputSlotDomain(op); + if (op.path !== undefined) { + if (!Array.isArray(op.path) || op.path.length === 0) { + throw new OpRejectedError("malformed_op", "connect: path must be a non-empty array when present"); + } + if (op.grow != null) { + throw new OpRejectedError("malformed_op", "connect: interior autogrow is not supported"); + } + } + if (op.node_incarnation !== undefined && (typeof op.node_incarnation !== "string" || op.node_incarnation.length === 0)) { throw new OpRejectedError("malformed_op", "connect: node_incarnation must be a non-empty string"); } @@ -1218,11 +1227,121 @@ function requireOpOnlyValid(op: ConnectOp): void { } } +interface InteriorConnectScope { + nodes: Y.Map>; + links: Y.Map; + definition: Y.Map; +} + +/** Resolve the definition owned by the instance at an interior connect path. */ +function resolveInteriorConnectScope( + doc: Y.Doc, + op: ConnectOp, + catalog?: WidgetCatalog, +): InteriorConnectScope | null { + if (!op.path || op.path.length === 0) return null; + const host = resolveInteriorNode(doc, op.path.map(String), catalog); + if (host === null) return null; + const hostType = String(host.get("type") ?? ""); + const definition = resolveDefinition(doc, hostType); + if (!definition) { + throw new OpRejectedError( + "not_a_subgraph", + `node ${String(host.get("id"))} is not a subgraph; cannot connect inside it`, + ); + } + const definitionId = String(definition.get("id") ?? hostType); + const instances = countDefinitionInstances(doc, definitionId, catalog); + if (instances > 1) { + throw new OpRejectedError( + "shared_definition_unforked", + `definition ${definitionId} is instantiated ${instances} times; interior writes to shared definitions are rejected until forking is specced (schema §5.3)`, + ); + } + const nodes = definition.get("nodes"); + const links = definition.get("links"); + if (!(nodes instanceof Y.Map) || !(links instanceof Y.Map)) { + throw new OpRejectedError("malformed_op", `subgraph definition ${definitionId} has malformed graph storage`); + } + return { nodes: nodes as Y.Map>, links, definition }; +} + +function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorConnectScope): SuccessfulOutcome { + const linkRefusal = arrayItemRefusal(op.link_id) ?? mapValueRefusal(op.link_id); + if (linkRefusal !== null) { + throw new OpRejectedError("malformed_op", `connect: link_id: ${linkRefusal}`); + } + + const src = scope.nodes.get(String(op.from_node)); + const dst = scope.nodes.get(String(op.to_node)); + if (!dst) return "no-op"; + const sourceOutputs = src ? requireOutputSlot(src, op) : null; + const toIdx = op.to_slot as number; + const inputs = dst.get("inputs"); + if (!(inputs instanceof Y.Array) || toIdx >= inputs.length) { + throw new OpRejectedError( + "input_slot_missing", + `connect: input slot ${String(toIdx)} not found on node ${String(op.to_node)}`, + ); + } + const input = inputs.get(toIdx); + if (!(input instanceof Y.Map)) { + throw new OpRejectedError("input_slot_missing", `connect: input slot ${toIdx} is not a slot record`); + } + + if (!claimLinkIdentity(doc, op, scope)) return "lww-dropped"; + const stamps = stampsMap(doc); + const targetKey = stampTargetKey(op); + const prior = stamps.get(targetKey) as StampKey | undefined; + const key = stampKey(op); + if (prior != null && compareStampKeys(key, prior) <= 0) return "lww-dropped"; + mset(stamps, targetKey, key); + + const previous = input.get("link"); + if (previous != null && previous !== op.link_id) removeLinkInScope(scope, previous); + if (!src || !sourceOutputs) return "no-op"; + + const linkKey = String(op.link_id); + if (!scope.links.has(linkKey)) { + mset(scope.links, linkKey, { + id: op.link_id, + origin_id: op.from_node, + origin_slot: op.from_slot, + target_id: op.to_node, + target_slot: toIdx, + type: op.link_type, + }); + } + const linkOrder = scope.definition.get("link_order"); + const orderedIds = Array.isArray(linkOrder) ? [...linkOrder] : []; + if (!orderedIds.some((id) => String(id) === linkKey)) { + orderedIds.push(linkKey); + mset(scope.definition, "link_order", orderedIds); + } + mset(input, "link", op.link_id); + const output = sourceOutputs.get(op.from_slot) as Y.Map; + let outputLinks = output.get("links"); + if (!(outputLinks instanceof Y.Array)) { + outputLinks = new Y.Array(); + mset(output, "links", outputLinks); + } + if (!(outputLinks as Y.Array).toArray().includes(op.link_id)) { + apush(outputLinks as Y.Array, op.link_id); + } + return "applied"; +} + function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): SuccessfulOutcome { // OP-ONLY validation first, before ANY document read decides the outcome // (KA-4, Amendment A6). requireOpOnlyValid(op); + if (op.path && op.path.length > 0) { + const scope = resolveInteriorConnectScope(doc, op, catalog); + if (scope === null) return "no-op"; + return applyInteriorConnect(doc, op, scope); + } + const nodes = nodesMap(doc); const dst = nodes.get(String(op.to_node)); // The destination is gone → the target slot does not exist and never will @@ -1363,17 +1482,21 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe } /** Claim the normalized complete-tuple link register (schema Amendment A18). */ -function claimLinkIdentity(doc: Y.Doc, op: ConnectOp): boolean { +function claimLinkIdentity(doc: Y.Doc, op: ConnectOp, scope?: InteriorConnectScope): boolean { const stamps = stampsMap(doc); const normalizedId = String(op.link_id); - const targetKey = JSON.stringify(["link", normalizedId]); + const targetKey = JSON.stringify(["link", ...(scope && op.path ? [op.path.map(String)] : []), normalizedId]); const prior = stamps.get(targetKey) as StampKey | undefined; const key = stampKey(op); if (prior != null && compareStampKeys(key, prior) <= 0) return false; - const links = linksMap(doc); + const links = scope?.links ?? linksMap(doc); if (links.has(normalizedId)) mdel(links, normalizedId); - scrubLinkRefs(doc, (candidate) => candidate != null && String(candidate) === normalizedId); + if (scope) { + scrubNodeLinkRefs(scope.nodes, (candidate) => candidate != null && String(candidate) === normalizedId); + } else { + scrubLinkRefs(doc, (candidate) => candidate != null && String(candidate) === normalizedId); + } mset(stamps, targetKey, key); return true; } @@ -1707,9 +1830,26 @@ function removeLink(doc: Y.Doc, linkId: unknown): void { scrubLinkRefs(doc, (candidate) => candidate != null && String(candidate) === key); } +function removeLinkInScope(scope: InteriorConnectScope, linkId: unknown): void { + const key = String(linkId); + if (scope.links.has(key)) mdel(scope.links, key); + scrubNodeLinkRefs(scope.nodes, (candidate) => candidate != null && String(candidate) === key); + const linkOrder = scope.definition.get("link_order"); + if (Array.isArray(linkOrder)) { + mset(scope.definition, "link_order", linkOrder.filter((id) => String(id) !== key)); + } +} + /** Scrub input/output references selected by one shared link-id predicate. */ function scrubLinkRefs(doc: Y.Doc, shouldRemove: (linkId: unknown) => boolean): void { - nodesMap(doc).forEach((node) => { + scrubNodeLinkRefs(nodesMap(doc), shouldRemove); +} + +function scrubNodeLinkRefs( + nodes: Y.Map>, + shouldRemove: (linkId: unknown) => boolean, +): void { + nodes.forEach((node) => { const ins = node.get("inputs"); if (ins instanceof Y.Array) { ins.forEach((slot: unknown) => { diff --git a/src/stamps.ts b/src/stamps.ts index f3064cf1..0655388b 100644 --- a/src/stamps.ts +++ b/src/stamps.ts @@ -109,6 +109,9 @@ export function writeTarget(op: WireOp): unknown[] { } return ["input", String(op.to_node), "grow", String(op.grow.name).split(".", 1)[0]]; } + if (op.path && op.path.length > 0) { + return ["input", op.path.map(String), String(op.to_node), op.to_slot]; + } return ["input", String(op.to_node), op.to_slot]; case "disconnect": return ["input", String(op.to_node), op.to_slot]; diff --git a/src/types.ts b/src/types.ts index 4ac9e737..aa4bc1f6 100644 --- a/src/types.ts +++ b/src/types.ts @@ -215,6 +215,8 @@ export interface PromotedHostWrite { /** Fields every `connect` carries, whichever way its destination slot is addressed. */ interface ConnectOpBase extends OpBase { op: "connect"; + /** Non-empty subgraph-instance path for a connect inside its definition. */ + path?: [NodeId, ...NodeId[]]; /** Link identity, minted at op-mint time (int in comfy-cli). */ link_id: NodeId; from_node: NodeId; diff --git a/test/interior-connect.regression.test.ts b/test/interior-connect.regression.test.ts new file mode 100644 index 00000000..f6b20ed1 --- /dev/null +++ b/test/interior-connect.regression.test.ts @@ -0,0 +1,222 @@ +import { describe, expect, it } from "vitest"; +import * as Y from "yjs"; +import { + applyOps, + mint, + project, + type ConnectOp, + type WidgetCatalog, + type WorkflowJSON, +} from "../src/index.js"; +import { appliedMap } from "../src/doc.js"; + +const catalog: WidgetCatalog = { + types: { + Source: { widget_order: [] }, + Sink: { widget_order: [] }, + }, +}; + +const workflow = { + nodes: [{ id: 100, type: "definition-1", inputs: [], outputs: [] }], + links: [], + definitions: { + subgraphs: [ + { + id: "definition-1", + nodes: [ + { + id: 1, + type: "Source", + inputs: [], + outputs: [{ name: "text", type: "STRING", links: null }], + }, + { + id: 2, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: null }], + outputs: [], + }, + ], + links: [], + }, + ], + }, +} as unknown as WorkflowJSON; + +function connect(overrides: Partial = {}): ConnectOp { + return { + op: "connect", + op_id: "interiorconnect0000000000000001", + actor: "human:a", + base_version: 1, + stamp: [1, "human:a"], + path: ["100"], + link_id: 41, + from_node: 1, + from_slot: 0, + to_node: 2, + to_slot: 0, + link_type: "STRING", + ...overrides, + } as ConnectOp; +} + +function definitionOf(doc: Y.Doc) { + return (project(doc, catalog).definitions as { + subgraphs: Array<{ + nodes: Array<{ + id: number; + inputs?: Array<{ link: number | null }>; + outputs?: Array<{ links: number[] | null }>; + }>; + links: Array<{ id: number }>; + }>; + }).subgraphs[0]!; +} + +describe("interior connect regression", () => { + it("applies and projects a concrete link inside one subgraph definition", () => { + const doc = mint(workflow, catalog); + const op = connect(); + + expect(applyOps(doc, [op], catalog).outcomes).toEqual([ + { op_id: op.op_id, outcome: "applied" }, + ]); + + const definitions = project(doc, catalog).definitions as { + subgraphs: Array<{ + nodes: Array<{ + id: number; + inputs?: Array<{ link: number | null }>; + outputs?: Array<{ links: number[] | null }>; + }>; + links: unknown[]; + }>; + }; + const definition = definitions.subgraphs[0]!; + + expect(definition.links).toEqual([ + { + id: 41, + origin_id: 1, + origin_slot: 0, + target_id: 2, + target_slot: 0, + type: "STRING", + }, + ]); + expect(definition.nodes.find(({ id }) => id === 1)?.outputs?.[0]?.links).toEqual([41]); + expect(definition.nodes.find(({ id }) => id === 2)?.inputs?.[0]?.link).toBe(41); + }); + + it.each([ + ["empty path", { path: [] }], + [ + "interior autogrow", + { + grow: { name: "text", type: "STRING", grow_id: "grow-1" }, + to_slot: undefined, + }, + ], + ])("rejects %s before changing document bytes or consuming op_id", (_name, invalid) => { + const doc = mint(workflow, catalog); + const op = connect(invalid as unknown as Partial); + const before = Y.encodeStateAsUpdate(doc); + + const result = applyOps(doc, [op], catalog); + + expect(result.outcomes).toEqual([ + { + op_id: op.op_id, + outcome: "rejected", + reason: { code: "malformed_op", message: expect.any(String) }, + }, + ]); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + expect(appliedMap(doc).has(op.op_id)).toBe(false); + }); + + it("refuses an interior write when two instances share the definition", () => { + const shared = structuredClone(workflow) as unknown as WorkflowJSON; + shared.nodes.push({ id: 101, type: "definition-1", inputs: [], outputs: [] }); + const doc = mint(shared, catalog); + const op = connect(); + const before = Y.encodeStateAsUpdate(doc); + + const result = applyOps(doc, [op], catalog); + + expect(result.outcomes).toEqual([ + { + op_id: op.op_id, + outcome: "rejected", + reason: { code: "shared_definition_unforked", message: expect.any(String) }, + }, + ]); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + expect(appliedMap(doc).has(op.op_id)).toBe(false); + }); + + it("uses path-scoped input stamps and converges on the higher-stamped link", () => { + const low = connect(); + const high = connect({ + op_id: "interiorconnect0000000000000002", + stamp: [2, "human:b"], + actor: "human:b", + base_version: 2, + link_id: 42, + }); + + for (const order of [[low, high], [high, low]]) { + const doc = mint(workflow, catalog); + applyOps(doc, order, catalog); + const definition = definitionOf(doc); + expect(definition.links.map(({ id }) => id)).toEqual([42]); + expect(definition.nodes.find(({ id }) => id === 1)?.outputs?.[0]?.links).toEqual([42]); + expect(definition.nodes.find(({ id }) => id === 2)?.inputs?.[0]?.link).toBe(42); + } + }); + + it("treats an identical interior-connect retry as a byte-identical no-op", () => { + const doc = mint(workflow, catalog); + const op = connect(); + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + const afterFirstApply = Y.encodeStateAsUpdate(doc); + + expect(applyOps(doc, [op], catalog).outcomes).toEqual([ + { op_id: op.op_id, outcome: "no-op" }, + ]); + expect(Y.encodeStateAsUpdate(doc)).toEqual(afterFirstApply); + }); + + it("keeps top-level and interior bookkeeping distinct when link ids collide", () => { + const withRootGraph = structuredClone(workflow) as unknown as WorkflowJSON; + withRootGraph.nodes.push( + { + id: 1, + type: "Source", + inputs: [], + outputs: [{ name: "text", type: "STRING", links: null }], + }, + { + id: 2, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: null }], + outputs: [], + }, + ); + const doc = mint(withRootGraph, catalog); + const root = connect({ op_id: "rootconnect000000000000000001" }); + delete root.path; + const interior = connect({ op_id: "interiorconnect0000000000000003", stamp: [2, "human:a"] }); + + expect(applyOps(doc, [root, interior], catalog).outcomes.map(({ outcome }) => outcome)).toEqual([ + "applied", + "applied", + ]); + + const projected = project(doc, catalog); + expect(projected.links).toEqual([[41, 1, 0, 2, 0, "STRING"]]); + expect(definitionOf(doc).links.map(({ id }) => id)).toEqual([41]); + }); +}); From 9b5583bd230f5729caea7d5b53996dc2fe54564c Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 16 Sep 2026 22:39:44 -0700 Subject: [PATCH 2/6] test: expose independent interior link arrival-order divergence --- test/interior-connect.regression.test.ts | 38 ++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/test/interior-connect.regression.test.ts b/test/interior-connect.regression.test.ts index f6b20ed1..7e756b90 100644 --- a/test/interior-connect.regression.test.ts +++ b/test/interior-connect.regression.test.ts @@ -189,6 +189,44 @@ describe("interior connect regression", () => { expect(Y.encodeStateAsUpdate(doc)).toEqual(afterFirstApply); }); + // Recovery PR 198 must preserve KA-4 for independent links, not just one contested input. + it("regression: independent interior connects project identically in both arrival orders", () => { + const independent = structuredClone(workflow); + const definitions = independent.definitions as { + subgraphs: Array<{ nodes: WorkflowJSON["nodes"] }>; + }; + definitions.subgraphs[0]!.nodes.push({ + id: 3, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: null }], + outputs: [], + }); + const seed = mint(independent, catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const first = connect(); + const second = connect({ + op_id: "independentconnect0000000000002", + stamp: [2, "human:b"], + actor: "human:b", + link_id: 42, + to_node: 3, + }); + const projections = [[first, second], [second, first]].map((order) => { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, order, catalog).outcomes.map(({ outcome }) => outcome)).toEqual([ + "applied", + "applied", + ]); + const projection = definitionOf(doc); + expect(projection.links.map(({ id }) => id).sort()).toEqual([41, 42]); + expect(projection.nodes.find(({ id }) => id === 2)?.inputs?.[0]?.link).toBe(41); + expect(projection.nodes.find(({ id }) => id === 3)?.inputs?.[0]?.link).toBe(42); + return project(doc, catalog); + }); + expect(projections[0]).toEqual(projections[1]); + }); + it("keeps top-level and interior bookkeeping distinct when link ids collide", () => { const withRootGraph = structuredClone(workflow) as unknown as WorkflowJSON; withRootGraph.nodes.push( From 8419e16c02c713ec16794f918923d5f79a5f0159 Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 16 Sep 2026 23:04:42 -0700 Subject: [PATCH 3/6] fix: stabilize interior link addition order --- src/applier.ts | 11 ++-- src/interior-link-order.ts | 40 +++++++++++++ src/mint.ts | 6 +- src/project.ts | 12 ++-- test/interior-connect.regression.test.ts | 75 ++++++++++++++++++++++++ 5 files changed, 132 insertions(+), 12 deletions(-) create mode 100644 src/interior-link-order.ts diff --git a/src/applier.ts b/src/applier.ts index b1883a57..2228c225 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -128,6 +128,7 @@ import { type WidgetCatalog, type WireOp, } from "./types.js"; +import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js"; import { NODE_INCARNATION_KEY } from "./types.js"; /** @@ -1313,10 +1314,10 @@ function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorConnectS }); } const linkOrder = scope.definition.get("link_order"); - const orderedIds = Array.isArray(linkOrder) ? [...linkOrder] : []; - if (!orderedIds.some((id) => String(id) === linkKey)) { - orderedIds.push(linkKey); - mset(scope.definition, "link_order", orderedIds); + const orderedIds: unknown[] = Array.isArray(linkOrder) ? [...linkOrder] : []; + const nextOrder = addInteriorLinkOrder(orderedIds, linkKey, key); + if (nextOrder !== orderedIds) { + mset(scope.definition, "link_order", nextOrder); } mset(input, "link", op.link_id); const output = sourceOutputs.get(op.from_slot) as Y.Map; @@ -1836,7 +1837,7 @@ function removeLinkInScope(scope: InteriorConnectScope, linkId: unknown): void { scrubNodeLinkRefs(scope.nodes, (candidate) => candidate != null && String(candidate) === key); const linkOrder = scope.definition.get("link_order"); if (Array.isArray(linkOrder)) { - mset(scope.definition, "link_order", linkOrder.filter((id) => String(id) !== key)); + mset(scope.definition, "link_order", removeInteriorLinkOrder(linkOrder, key)); } } diff --git a/src/interior-link-order.ts b/src/interior-link-order.ts new file mode 100644 index 00000000..dc240d67 --- /dev/null +++ b/src/interior-link-order.ts @@ -0,0 +1,40 @@ +import { compareStampKeys } from "./stamps.js"; +import type { StampKey } from "./types.js"; + +interface AddedInteriorLinkOrderMarker { + __cmp_added_links: Record; +} + +function isAddedMarker(value: unknown): value is AddedInteriorLinkOrderMarker { + if (value === null || typeof value !== "object" || Array.isArray(value)) return false; + const entry = value as Partial; + return entry.__cmp_added_links !== null && typeof entry.__cmp_added_links === "object"; +} + +export function addInteriorLinkOrder(order: unknown[], id: string, stamp: StampKey): unknown[] { + if (order.some((entry) => !isAddedMarker(entry) && String(entry) === id)) return order; + const marker = order.find(isAddedMarker); + const additions = { ...(marker?.__cmp_added_links ?? {}), [id]: stamp }; + return [...order.filter((entry) => !isAddedMarker(entry)), id, { __cmp_added_links: additions }]; +} + +/** Preserve imported order, then deterministically order links added by ops. */ +export function projectInteriorLinkOrder(order: unknown[]): string[] { + const marker = order.find(isAddedMarker); + const additions = marker?.__cmp_added_links ?? {}; + const ids = order.filter((entry) => !isAddedMarker(entry)).map(String); + const imported = ids.filter((id) => !(id in additions)); + const added = ids.filter((id) => id in additions); + added.sort((a, b) => compareStampKeys(additions[a]!, additions[b]!)); + return [...imported, ...added]; +} + +export function removeInteriorLinkOrder(order: unknown[], id: string): unknown[] { + const marker = order.find(isAddedMarker); + const additions = { ...(marker?.__cmp_added_links ?? {}) }; + delete additions[id]; + const retained = order.filter((entry) => isAddedMarker(entry) || String(entry) !== id); + return marker + ? [...retained.filter((entry) => !isAddedMarker(entry)), { __cmp_added_links: additions }] + : retained; +} diff --git a/src/mint.ts b/src/mint.ts index b5cb95e0..81072a22 100644 --- a/src/mint.ts +++ b/src/mint.ts @@ -47,9 +47,9 @@ interface SubgraphDef { * map through `catalog` — schema §1.2); * - `definitions.subgraphs` into the first-class `definitions` root map * (schema §5.1), with interior node/link mint order preserved in plain - * `node_order`/`link_order` registers (interior order is static in v1 — - * only `set_widget` is subgraph-scoped); non-`subgraphs` keys of the - * definitions container are kept in the internal `__definitions_extra` + * `node_order`/`link_order` registers; later interior links retain this + * imported prefix and project in deterministic stamp order; + * non-`subgraphs` keys of the definitions container are kept in the internal `__definitions_extra` * meta key and merged back at projection; * - every other top-level key into meta as opaque passthrough (schema §6); * - `schema_version` + the pinned `catalogVersion` into meta. diff --git a/src/project.ts b/src/project.ts index 1052926b..f85185d4 100644 --- a/src/project.ts +++ b/src/project.ts @@ -19,8 +19,8 @@ * * Subgraph definitions project as `{...extra, subgraphs: [...]}` with * definitions sorted by id and each definition's interior nodes/links in - * mint order (`node_order`/`link_order` — interior order is static in v1 - * because only `set_widget` is subgraph-scoped). + * mint order (`node_order`/`link_order`); links added by semantic ops follow + * imported links in deterministic stamp order. */ import * as Y from "yjs"; @@ -33,6 +33,7 @@ import { widgetStorageOf, } from "./doc.js"; import { assertNever } from "./exhaustive.js"; +import { projectInteriorLinkOrder } from "./interior-link-order.js"; import { assertReadableSchema } from "./schema-version.js"; import { NODE_INCARNATION_KEY, type WidgetCatalog, type WorkflowJSON, type WorkflowNode } from "./types.js"; @@ -213,7 +214,7 @@ function tryProjectNode(value: unknown, catalog: WidgetCatalog): WorkflowNode | return projectNode(value, catalog); } -/** Definition Y.Map → subgraph definition JSON, interior nodes/links in mint order. */ +/** Definition Y.Map → subgraph JSON, preserving mint order before deterministic additions. */ function projectDefinition(dm: Y.Map, catalog: WidgetCatalog): Record { const out: Record = Object.create(null) as Record; dm.forEach((v, k) => { @@ -225,7 +226,10 @@ function projectDefinition(dm: Y.Map, catalog: WidgetCatalog): Record tryProjectNode(v.get(id), catalog)) .filter((node): node is WorkflowNode => node !== null); } else if (k === "links" && v instanceof Y.Map) { - const order = (dm.get("link_order") as string[] | undefined) ?? [...v.keys()].sort(); + const storedOrder = dm.get("link_order"); + const order = Array.isArray(storedOrder) + ? projectInteriorLinkOrder(storedOrder) + : [...v.keys()].sort(); out[k] = order.filter((id) => v.has(id)).map((id) => structuredClone(v.get(id))); } else { out[k] = structuredClone(v); diff --git a/test/interior-connect.regression.test.ts b/test/interior-connect.regression.test.ts index 7e756b90..94ce797a 100644 --- a/test/interior-connect.regression.test.ts +++ b/test/interior-connect.regression.test.ts @@ -227,6 +227,81 @@ describe("interior connect regression", () => { expect(projections[0]).toEqual(projections[1]); }); + it("preserves asymmetric imported order ahead of deterministically ordered additions", () => { + const imported = structuredClone(workflow) as unknown as WorkflowJSON & { + definitions: { subgraphs: Array<{ nodes: WorkflowJSON["nodes"]; links: Array> }> }; + }; + const definition = imported.definitions.subgraphs[0]!; + (definition.nodes[0]!.outputs as Array<{ links: number[] | null }>)[0]!.links = [90, 7]; + (definition.nodes[1]!.inputs as Array<{ link: number | null }>)[0]!.link = 90; + definition.nodes.push( + { + id: 3, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: 7 }], + outputs: [], + }, + { + id: 4, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: null }], + outputs: [], + }, + { + id: 5, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: null }], + outputs: [], + }, + ); + definition.links = [ + { id: 90, origin_id: 1, origin_slot: 0, target_id: 2, target_slot: 0, type: "STRING" }, + { id: 7, origin_id: 1, origin_slot: 0, target_id: 3, target_slot: 0, type: "STRING" }, + ]; + const snapshot = Y.encodeStateAsUpdate(mint(imported, catalog)); + const first = connect({ to_node: 4, link_id: 41 }); + const second = connect({ + op_id: "independentconnect0000000000002", + stamp: [2, "human:b"], + actor: "human:b", + base_version: 2, + to_node: 5, + link_id: 42, + }); + + for (const order of [[first, second], [second, first]]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + applyOps(doc, order, catalog); + expect(definitionOf(doc).links.map(({ id }) => id)).toEqual([90, 7, 41, 42]); + } + }); + + it("removes a replaced imported link without disturbing surviving imported order", () => { + const imported = structuredClone(workflow) as unknown as WorkflowJSON & { + definitions: { subgraphs: Array<{ nodes: WorkflowJSON["nodes"]; links: Array> }> }; + }; + const definition = imported.definitions.subgraphs[0]!; + (definition.nodes[0]!.outputs as Array<{ links: number[] | null }>)[0]!.links = [90, 7]; + (definition.nodes[1]!.inputs as Array<{ link: number | null }>)[0]!.link = 90; + definition.nodes.push({ + id: 3, + type: "Sink", + inputs: [{ name: "text", type: "STRING", link: 7 }], + outputs: [], + }); + definition.links = [ + { id: 90, origin_id: 1, origin_slot: 0, target_id: 2, target_slot: 0, type: "STRING" }, + { id: 7, origin_id: 1, origin_slot: 0, target_id: 3, target_slot: 0, type: "STRING" }, + ]; + const doc = mint(imported, catalog); + + expect(applyOps(doc, [connect()], catalog).outcomes[0]?.outcome).toBe("applied"); + + expect(definitionOf(doc).links.map(({ id }) => id)).toEqual([7, 41]); + expect(definitionOf(doc).nodes.find(({ id }) => id === 1)?.outputs?.[0]?.links).toEqual([7, 41]); + }); + it("keeps top-level and interior bookkeeping distinct when link ids collide", () => { const withRootGraph = structuredClone(workflow) as unknown as WorkflowJSON; withRootGraph.nodes.push( From d94aa21310a13aa659660ea5784037b8da90bcc0 Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 16 Sep 2026 23:11:43 -0700 Subject: [PATCH 4/6] test: pin prototype-named interior link order --- test/interior-connect.regression.test.ts | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/test/interior-connect.regression.test.ts b/test/interior-connect.regression.test.ts index 94ce797a..ffed3795 100644 --- a/test/interior-connect.regression.test.ts +++ b/test/interior-connect.regression.test.ts @@ -302,6 +302,25 @@ describe("interior connect regression", () => { expect(definitionOf(doc).nodes.find(({ id }) => id === 1)?.outputs?.[0]?.links).toEqual([7, 41]); }); + // https://github.com/Comfy-Org/comfy-multi-player/pull/198 + it("regression: prototype-named imported link ids retain their original order", () => { + const imported = { + ...workflow, + definitions: { + subgraphs: [{ + id: "definition-1", + nodes: [], + links: [ + { id: "constructor", origin_id: 1, origin_slot: 0, target_id: 2, target_slot: 0, type: "STRING" }, + { id: "ordinary", origin_id: 1, origin_slot: 0, target_id: 3, target_slot: 0, type: "STRING" }, + ], + }], + }, + } as unknown as WorkflowJSON; + expect(definitionOf(mint(imported, catalog)).links.map(({ id }) => id)) + .toEqual(["constructor", "ordinary"]); + }); + it("keeps top-level and interior bookkeeping distinct when link ids collide", () => { const withRootGraph = structuredClone(workflow) as unknown as WorkflowJSON; withRootGraph.nodes.push( From 36a2751229e7885a53a23f6bf4b157c7057647ed Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 16 Sep 2026 23:17:29 -0700 Subject: [PATCH 5/6] test: pin winning interior rewrite order across permutations --- test/interior-connect.regression.test.ts | 25 ++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/test/interior-connect.regression.test.ts b/test/interior-connect.regression.test.ts index ffed3795..91f76680 100644 --- a/test/interior-connect.regression.test.ts +++ b/test/interior-connect.regression.test.ts @@ -227,6 +227,31 @@ describe("interior connect regression", () => { expect(projections[0]).toEqual(projections[1]); }); + // https://github.com/Comfy-Org/comfy-multi-player/pull/198 + it("regression: a winning same-id rewrite updates addition order in all six permutations", () => { + const independent = structuredClone(workflow); + const definitions = independent.definitions as { + subgraphs: Array<{ nodes: WorkflowJSON["nodes"] }>; + }; + definitions.subgraphs[0]!.nodes.push({ + id: 3, type: "Sink", inputs: [{ name: "text", type: "STRING", link: null }], outputs: [], + }); + const snapshot = Y.encodeStateAsUpdate(mint(independent, catalog)); + const early = connect(); + const middle = connect({ op_id: "middle", stamp: [2, "human:a"], link_id: 42, to_node: 3 }); + const late = connect({ op_id: "late", stamp: [3, "human:a"] }); + const orders = [[early, middle, late], [early, late, middle], [middle, early, late], + [middle, late, early], [late, early, middle], [late, middle, early]]; + expect(orders).toHaveLength(6); + for (const order of orders) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + applyOps(doc, order, catalog); + expect.soft(definitionOf(doc).links.map(({ id }) => id), order.map((op) => op.op_id).join(",")) + .toEqual([42, 41]); + } + }); + it("preserves asymmetric imported order ahead of deterministically ordered additions", () => { const imported = structuredClone(workflow) as unknown as WorkflowJSON & { definitions: { subgraphs: Array<{ nodes: WorkflowJSON["nodes"]; links: Array> }> }; From e9a1f6badc1d3f89ac9ab6bb0c534a6efe725b08 Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 16 Sep 2026 23:38:39 -0700 Subject: [PATCH 6/6] fix: persist canonical interior link ordering across replay --- docs/multiplayer-schema.md | 31 ++++++++++----- src/applier.ts | 17 ++++++++- src/interior-link-order.ts | 48 +++++++++--------------- test/interior-connect.regression.test.ts | 15 +++++++- 4 files changed, 67 insertions(+), 44 deletions(-) diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 869a0501..553ee502 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -581,20 +581,31 @@ node/link arrays are **not** sorted at projection — the §7 sorted-by-id rule applies to the top-level arrays only. Python's `canonical` sorts `definitions.subgraphs` by id but leaves each definition's interior arrays in authored order, and the fixtures pin that (`session-subgraph`'s def lists -node 27 before node 3). Since only `set_widget` is subgraph-scoped, interior -membership and order are static after mint; the def Y.Map therefore stores -plain `node_order`/`link_order` registers (written once at mint) and -projection emits interior arrays in that order. Definitions themselves -project sorted by definition id. +node 27 before node 3). The def Y.Map stores plain scalar +`node_order`/`link_order` registers, and projection emits interior arrays in +that order. Interior `connect` preserves surviving imported links as an +authored-order prefix and sorts op-added links after them by winning stamp. +The scalar `link_order` itself is updated to that canonical order; projection +does not depend on an object marker hidden inside the array. Definitions +themselves project sorted by definition id. + +Added-link ordering stamps use the internal `__stamps` key +`["interior_link_order", String(definition_id), String(link_id)]`. A winning +same-ID rewrite refreshes that stamp; rewriting a still-present imported link +does not reclassify it as an addition. Definition IDs identify unique +definitions. These are additional internal stamp entries, not a new root or +scalar-array layout; as with Amendment A18, `SCHEMA_VERSION` remains 2. ### 5.2 Addressing: three forms, one write target -Only `set_widget` is subgraph-scoped in the frozen vocabulary (spike Q6; -error strings captured verbatim in `fixtures/findings.json`): +The frozen spike supported only subgraph-scoped `set_widget` (spike Q6; +historical error strings remain in `fixtures/findings.json`). The current +package also supports `connect` with a non-empty instance `path`: -- `connect` structurally refuses interior endpoints ("a link cannot cross - the subgraph boundary") and promoted-widget targets ("promoted widget (a - value), not a link input"). +- Interior `connect` resolves both endpoints within one definition and rejects + interior autogrow and writes to shared, unforked definitions. Input stamps + include the path; normalized link identity stamps do too. This does not + enable cross-boundary wiring or an interior `disconnect` operation. - `add_node`/`delete_node` cannot address interior nodes at all. `set_widget` accepts three address forms — flat promoted (`57.text`, routed diff --git a/src/applier.ts b/src/applier.ts index 2228c225..ba8c26c6 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1315,8 +1315,21 @@ function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorConnectS } const linkOrder = scope.definition.get("link_order"); const orderedIds: unknown[] = Array.isArray(linkOrder) ? [...linkOrder] : []; - const nextOrder = addInteriorLinkOrder(orderedIds, linkKey, key); - if (nextOrder !== orderedIds) { + const definitionId = String(scope.definition.get("id") ?? ""); + const orderStampKey = (candidate: string) => + JSON.stringify(["interior_link_order", definitionId, candidate]); + const additions: Record = Object.create(null) as Record; + for (const candidate of orderedIds.map(String)) { + const addedStamp = stamps.get(orderStampKey(candidate)); + if (Array.isArray(addedStamp)) additions[candidate] = addedStamp as StampKey; + } + const wasAdded = Object.hasOwn(additions, linkKey); + const wasPresent = orderedIds.some((candidate) => String(candidate) === linkKey); + const nextOrder = addInteriorLinkOrder(orderedIds, linkKey, key, additions); + if (!wasPresent || wasAdded) { + mset(stamps, orderStampKey(linkKey), key); + } + if (nextOrder.some((candidate, index) => candidate !== orderedIds[index]) || nextOrder.length !== orderedIds.length) { mset(scope.definition, "link_order", nextOrder); } mset(input, "link", op.link_id); diff --git a/src/interior-link-order.ts b/src/interior-link-order.ts index dc240d67..183be0f0 100644 --- a/src/interior-link-order.ts +++ b/src/interior-link-order.ts @@ -1,40 +1,28 @@ import { compareStampKeys } from "./stamps.js"; import type { StampKey } from "./types.js"; -interface AddedInteriorLinkOrderMarker { - __cmp_added_links: Record; -} - -function isAddedMarker(value: unknown): value is AddedInteriorLinkOrderMarker { - if (value === null || typeof value !== "object" || Array.isArray(value)) return false; - const entry = value as Partial; - return entry.__cmp_added_links !== null && typeof entry.__cmp_added_links === "object"; -} - -export function addInteriorLinkOrder(order: unknown[], id: string, stamp: StampKey): unknown[] { - if (order.some((entry) => !isAddedMarker(entry) && String(entry) === id)) return order; - const marker = order.find(isAddedMarker); - const additions = { ...(marker?.__cmp_added_links ?? {}), [id]: stamp }; - return [...order.filter((entry) => !isAddedMarker(entry)), id, { __cmp_added_links: additions }]; +export function addInteriorLinkOrder( + order: unknown[], + id: string, + stamp: StampKey, + priorAdditions: Record, +): string[] { + const ids = order.map(String); + const wasAdded = Object.hasOwn(priorAdditions, id); + if (ids.includes(id) && !wasAdded) return ids; + const additions = { ...priorAdditions, [id]: stamp }; + const withId = ids.includes(id) ? ids : [...ids, id]; + const imported = withId.filter((candidate) => !Object.hasOwn(additions, candidate)); + const added = withId.filter((candidate) => Object.hasOwn(additions, candidate)); + added.sort((a, b) => compareStampKeys(additions[a]!, additions[b]!)); + return [...imported, ...added]; } -/** Preserve imported order, then deterministically order links added by ops. */ +/** The stored scalar order is already canonical for unchanged-schema readers. */ export function projectInteriorLinkOrder(order: unknown[]): string[] { - const marker = order.find(isAddedMarker); - const additions = marker?.__cmp_added_links ?? {}; - const ids = order.filter((entry) => !isAddedMarker(entry)).map(String); - const imported = ids.filter((id) => !(id in additions)); - const added = ids.filter((id) => id in additions); - added.sort((a, b) => compareStampKeys(additions[a]!, additions[b]!)); - return [...imported, ...added]; + return order.map(String); } export function removeInteriorLinkOrder(order: unknown[], id: string): unknown[] { - const marker = order.find(isAddedMarker); - const additions = { ...(marker?.__cmp_added_links ?? {}) }; - delete additions[id]; - const retained = order.filter((entry) => isAddedMarker(entry) || String(entry) !== id); - return marker - ? [...retained.filter((entry) => !isAddedMarker(entry)), { __cmp_added_links: additions }] - : retained; + return order.filter((entry) => String(entry) !== id); } diff --git a/test/interior-connect.regression.test.ts b/test/interior-connect.regression.test.ts index 91f76680..37f4cca3 100644 --- a/test/interior-connect.regression.test.ts +++ b/test/interior-connect.regression.test.ts @@ -244,11 +244,22 @@ describe("interior connect regression", () => { [middle, late, early], [late, early, middle], [late, middle, early]]; expect(orders).toHaveLength(6); for (const order of orders) { - const doc = new Y.Doc(); + let doc = new Y.Doc(); Y.applyUpdate(doc, snapshot); - applyOps(doc, order, catalog); + for (const op of order) { + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).not.toBe("rejected"); + // Resume on a new replica after every op: ordering metadata must persist. + const resumed = new Y.Doc(); + Y.applyUpdate(resumed, Y.encodeStateAsUpdate(doc)); + doc.destroy(); + doc = resumed; + } expect.soft(definitionOf(doc).links.map(({ id }) => id), order.map((op) => op.op_id).join(",")) .toEqual([42, 41]); + const storedDefinition = doc.getMap>("definitions").get("definition-1"); + const rawOrder = storedDefinition?.get("link_order"); + expect.soft(rawOrder, order.map((op) => op.op_id).join(",")).toEqual(["42", "41"]); + expect.soft((rawOrder as unknown[]).every((entry) => typeof entry === "string")).toBe(true); } });