From d5d7a487e8cec2b8c297976755592521a67c2362 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sun, 23 Aug 2026 07:14:40 +0000 Subject: [PATCH 1/8] audit: enumerate graph-level atomicity of registerNodeState/replaceLink/updateEndpoints All six graph-level call sites are already atomic (validate-before-mutate). Documents the call-site map in the ECS extension compatibility audit with a table row per site plus a declared-non-atomic edge case: mintLinkId advances state.lastLinkId before replaceLinkTopology is called, leaving a cosmetic ID gap on rejection but no topology corruption. Pins these contracts via src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts (7 passing tests + 1 it.fails asserting the mintLinkId edge case). --- .../ecs/ecs-extension-compatibility-audit.md | 26 ++ .../src/node/graphCallSiteAtomicity.test.ts | 267 ++++++++++++++++++ 2 files changed, 293 insertions(+) create mode 100644 src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts diff --git a/docs/architecture/ecs/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md index ffe6998d71b..b625e2a9385 100644 --- a/docs/architecture/ecs/ecs-extension-compatibility-audit.md +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -187,6 +187,32 @@ is later architecture work outside this data-centralization phase. 7. Preserve callback ordering assumptions only where covered below; subscribe to graph events when observation is sufficient and no override is required. +## Graph-level call-site atomicity audit + +Audited against `345eddfef` (2026-08-24). All graph-level callers of +`attachNodeToStores` (via `registerNodeState`), `replaceLink` (via +`replaceLinkTopology`), and `updateEndpoints` follow validate-then-mutate +ordering. No non-atomic sites were found. + +| Call site | Function called | Atomic? | Notes | +| ------------------------------------------------------ | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LGraph.add()` (`LGraph.ts:1169`) | `attachNodeToStores` → `registerNodeState` | Yes | `attachNodeToStores` retries with a fresh minted id on collision; `node.graph = this` is set before the call but graph arrays mutate only after registration succeeds. | +| `LGraphNode.connect()` (`LGraphNode.ts:3171`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before any topology mutation when `replaceLinkTopology` returns `false`. `finalizeInputLinkRemoval`, slot updates, and `onConnectionsChange` all follow the guard. | +| `SubgraphInput.connect()` (`SubgraphInput.ts:102`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `_disconnectNodeInput`, `linkIds.push`, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | +| `SubgraphOutput.connect()` (`SubgraphOutput.ts:73`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `existingLink.disconnect`, `linkIds[0]` assignment, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | +| `replaceNodeInputs()` (`node/slotLinks.ts:187`) | `updateEndpoints` | Yes | Returns `[]` on `!result.ok` before `node.inputs.splice` or `finalizeInputLinkRemoval`. | +| `realignInputLinkSlots()` (`linkDeduplication.ts:154`) | `updateEndpoints` | Yes | Breaks the pass loop on `!result.ok` before firing any `onConnectionsChange` callbacks. | + +### Declared-non-atomic edge cases + +These are cosmetic side effects that leave no graph inconsistency. They are +pinned by `it.fails` assertions in +`src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts`. + +| Edge case | Observable partial state | Severity | +| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `mintLinkId` runs before `replaceLinkTopology` in `LGraphNode.connect()`, `SubgraphInput.connect()`, and `SubgraphOutput.connect()`. | `graph.state.lastLinkId` advances even when `replaceLinkTopology` is rejected, creating a gap in the link ID sequence. No topology is corrupted; no dangling link or double-registered slot results. | Cosmetic — IDs remain unique and monotonic, just non-contiguous. | + ## Required follow-up evidence Existing evidence includes `LLink.store.test.ts`, `NodeInputSlot.test.ts`, diff --git a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts new file mode 100644 index 00000000000..1265a1e1d97 --- /dev/null +++ b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts @@ -0,0 +1,267 @@ +/** + * Atomicity contracts for graph-level call sites of attachNodeToStores, + * replaceLinkTopology, and updateEndpoints. + * + * Every site validated-then-mutates: a store rejection leaves no committed + * graph mutation. The one declared edge case is the cosmetic ID gap created + * by mintLinkId before replaceLinkTopology is called; that is documented in + * docs/architecture/ecs/ecs-extension-compatibility-audit.md under + * "Declared-non-atomic edge cases". + */ +import { createTestingPinia } from '@pinia/testing' +import { setActivePinia } from 'pinia' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { realignInputLinkSlots } from '@/lib/litegraph/src/linkDeduplication' +import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph' +import type { ISerialisedNode } from '@/lib/litegraph/src/types/serialisation' +import { useLinkStore } from '@/stores/linkStore' + +// --------------------------------------------------------------------------- +// Fixtures +// --------------------------------------------------------------------------- + +function connectedPair() { + const graph = new LGraph() + const source = new LGraphNode('Source') + source.addOutput('out', 'INT') + graph.add(source) + + const target = new LGraphNode('Target') + target.addInput('in', 'INT') + graph.add(target) + + const link = source.connect(0, target, 0)! + return { graph, source, target, link } +} + +// --------------------------------------------------------------------------- +// attachNodeToStores call site: LGraph.add() +// --------------------------------------------------------------------------- + +describe('attachNodeToStores – LGraph.add() atomicity', () => { + beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) + + it('resolves an id collision by re-minting before mutating graph arrays', () => { + // Pre-plant a node so its id is already taken in the store. + const graph = new LGraph() + const planted = new LGraphNode('Planted') + graph.add(planted) + + // The collision candidate starts with the same id as the planted node. + const candidate = new LGraphNode('Candidate') + candidate.id = planted.id + + graph.add(candidate) + + // Both nodes are registered with unique ids. + expect(candidate.id).not.toBe(planted.id) + expect(graph._nodes).toHaveLength(2) + // Each node appears exactly once under its id. + expect(graph._nodes_by_id[planted.id]).toBe(planted) + expect(graph._nodes_by_id[candidate.id]).toBe(candidate) + }) + + it('never adds a node to _nodes before store registration succeeds', () => { + const graph = new LGraph() + // Confirm the node is fully registered on first access to _nodes. + const node = new LGraphNode('N') + graph.add(node) + + expect(graph._nodes).toContain(node) + expect(node._graphScope).toBeDefined() + }) +}) + +// --------------------------------------------------------------------------- +// replaceLinkTopology call site: LGraphNode.connect() +// --------------------------------------------------------------------------- + +describe('replaceLinkTopology – LGraphNode.connect() atomicity', () => { + beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) + + it('leaves the graph unchanged when the store rejects replaceLink', () => { + const { source, target, link } = connectedPair() + const graph = source.graph! + + const linksBefore = graph.links.size + const inputLinkBefore = target.getInputLink(0)?.id + + // Force every replaceLink call to fail. + vi.spyOn(useLinkStore(), 'replaceLink').mockReturnValue(undefined) + + // Attempt a second connection to the same input slot. + const second = new LGraphNode('Second') + second.addOutput('out', 'INT') + graph.add(second) + const result = second.connect(0, target, 0) + + // connect() returns null or undefined on rejection. + expect(result).toBeFalsy() + // The link store is unchanged. + expect(graph.links.size).toBe(linksBefore) + // The original link on the target input is still intact. + expect(target.getInputLink(0)?.id).toBe(inputLinkBefore) + // The incumbent link from the first source is still registered. + expect(graph.links.get(link.id)).toBeDefined() + }) + + it('commits the replacement and removes the incumbent on success', () => { + const graph = new LGraph() + const source1 = new LGraphNode('S1') + source1.addOutput('out', 'INT') + graph.add(source1) + const source2 = new LGraphNode('S2') + source2.addOutput('out', 'INT') + graph.add(source2) + const target = new LGraphNode('T') + target.addInput('in', 'INT') + graph.add(target) + + const first = source1.connect(0, target, 0)! + expect(graph.links.get(first.id)).toBeDefined() + + const second = source2.connect(0, target, 0)! + // The new link is registered. + expect(graph.links.get(second.id)).toBeDefined() + // The old link is gone. + expect(graph.links.has(first.id)).toBe(false) + // The target input reflects the new link. + expect(target.getInputLink(0)?.id).toBe(second.id) + }) + + /** + * Declared edge case (cosmetic, not a graph inconsistency): + * mintLinkId increments state.lastLinkId before replaceLinkTopology. + * A rejection wastes the minted id, leaving a gap in the sequence. + * The graph's _topology_ remains consistent — no dangling link, no + * double-registered slot. Only the monotonic counter advances. + */ + it.fails('does not advance lastLinkId when the store rejects replaceLink', () => { + const { source, target } = connectedPair() + const graph = source.graph! + const idBefore = Number(graph.state.lastLinkId) + + vi.spyOn(useLinkStore(), 'replaceLink').mockReturnValue(undefined) + + const second = new LGraphNode('S2') + second.addOutput('out', 'INT') + graph.add(second) + second.connect(0, target, 0) + + // This assertion FAILS: lastLinkId was already incremented by mintLinkId + // before the store call. The gap is cosmetic — no topology corruption. + expect(Number(graph.state.lastLinkId)).toBe(idBefore) + }) +}) + +// --------------------------------------------------------------------------- +// updateEndpoints call site: replaceNodeInputs (slotLinks.ts) +// --------------------------------------------------------------------------- + +describe('updateEndpoints – replaceNodeInputs() atomicity', () => { + beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) + + it('does not splice node.inputs when updateEndpoints is rejected', () => { + const graph = new LGraph() + const source = new LGraphNode('S') + source.addOutput('out', 'INT') + graph.add(source) + const target = new LGraphNode('T') + target.addInput('a', 'INT') + target.addInput('b', 'INT') + graph.add(target) + source.connect(0, target, 0) + source.connect(0, target, 1) + + const inputsBefore = [...target.inputs] + + // The last test in legacySlotLinkMutations.test.ts already exercises the + // "keeps the input layout when the endpoint batch is rejected" path via + // removeInput. Here we drive it through the store rejection directly. + vi.spyOn(useLinkStore(), 'updateEndpoints').mockReturnValue({ + ok: false, + error: { code: 'occupied-target', message: 'forced rejection' } + }) + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + + // removeInput triggers replaceNodeInputs → updateEndpoints. + target.removeInput(0) + + expect(consoleError).toHaveBeenCalledWith( + 'Failed to replace node inputs', + expect.objectContaining({ code: 'occupied-target' }) + ) + // node.inputs is unchanged — no partial splice committed. + expect(target.inputs.map((i) => i.name)).toEqual( + inputsBefore.map((i) => i.name) + ) + // Both links are still registered. + expect(graph.links.size).toBe(2) + }) + + it('splices inputs and updates endpoints together on success', () => { + const graph = new LGraph() + const source = new LGraphNode('S') + source.addOutput('out', 'INT') + graph.add(source) + const target = new LGraphNode('T') + target.addInput('a', 'INT') + target.addInput('b', 'INT') + graph.add(target) + source.connect(0, target, 0) + source.connect(0, target, 1) + + const linkAtB = target.getInputLink(1)! + + // Remove slot 0; slot 1 (with its link) shifts to slot 0. + target.removeInput(0) + + expect(target.inputs).toHaveLength(1) + expect(target.inputs[0].name).toBe('b') + // The surviving link now targets slot 0. + expect(target.getInputLink(0)?.id).toBe(linkAtB.id) + expect(graph.links.size).toBe(1) + }) +}) + +// --------------------------------------------------------------------------- +// updateEndpoints call site: realignInputLinkSlots (linkDeduplication.ts) +// --------------------------------------------------------------------------- + +describe('updateEndpoints – realignInputLinkSlots() atomicity', () => { + beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) + + it('does not fire onConnectionsChange when updateEndpoints is rejected', () => { + const graph = new LGraph() + const source = new LGraphNode('S') + source.addOutput('out', 'INT') + graph.add(source) + const target = new LGraphNode('T') + target.addInput('x', 'INT') + graph.add(target) + source.connect(0, target, 0) + + const onConnectionsChange = vi.fn() + target.onConnectionsChange = onConnectionsChange + + vi.spyOn(useLinkStore(), 'updateEndpoints').mockReturnValue({ + ok: false, + error: { code: 'unowned-topology', message: 'forced' } + }) + vi.spyOn(console, 'error').mockImplementation(() => {}) + + const serialized = [ + { + id: target.id, + inputs: [ + { name: 'x', link: target.getInputLink(0)!.id as unknown as number } + ] + } + ] as unknown as ISerialisedNode[] + realignInputLinkSlots(graph, serialized) + + // onConnectionsChange must not fire — no partial side effects. + expect(onConnectionsChange).not.toHaveBeenCalled() + }) +}) From 19e680b74eeccabe0b43bf1ad80075b10cb45e8a Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Tue, 25 Aug 2026 10:19:51 -0700 Subject: [PATCH 2/8] test: exercise rejected endpoint realignment Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/15721#discussion_r3850920052 --- .../src/node/graphCallSiteAtomicity.test.ts | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts index 1265a1e1d97..aec0100d5aa 100644 --- a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts +++ b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts @@ -232,23 +232,26 @@ describe('updateEndpoints – replaceNodeInputs() atomicity', () => { describe('updateEndpoints – realignInputLinkSlots() atomicity', () => { beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) - it('does not fire onConnectionsChange when updateEndpoints is rejected', () => { + it('keeps the original connection when updateEndpoints is rejected', () => { const graph = new LGraph() const source = new LGraphNode('S') source.addOutput('out', 'INT') graph.add(source) const target = new LGraphNode('T') + target.addInput('other', 'INT') target.addInput('x', 'INT') graph.add(target) - source.connect(0, target, 0) + const link = source.connect(0, target, 0)! const onConnectionsChange = vi.fn() target.onConnectionsChange = onConnectionsChange - vi.spyOn(useLinkStore(), 'updateEndpoints').mockReturnValue({ - ok: false, - error: { code: 'unowned-topology', message: 'forced' } - }) + const updateEndpoints = vi + .spyOn(useLinkStore(), 'updateEndpoints') + .mockReturnValue({ + ok: false, + error: { code: 'unowned-topology', message: 'forced' } + }) vi.spyOn(console, 'error').mockImplementation(() => {}) const serialized = [ @@ -261,7 +264,13 @@ describe('updateEndpoints – realignInputLinkSlots() atomicity', () => { ] as unknown as ISerialisedNode[] realignInputLinkSlots(graph, serialized) + expect(updateEndpoints).toHaveBeenCalledOnce() + expect(updateEndpoints).toHaveReturnedWith( + expect.objectContaining({ ok: false }) + ) // onConnectionsChange must not fire — no partial side effects. expect(onConnectionsChange).not.toHaveBeenCalled() + expect(target.getInputLink(0)?.id).toBe(link.id) + expect(target.getInputLink(1)).toBeNull() }) }) From 6a45076718664c9f815b814f07752700040d9c1e Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Tue, 1 Sep 2026 14:58:21 -0700 Subject: [PATCH 3/8] test(litegraph): adapt realignInputLinkSlots call to tuple-iterable signature main (#16235) changed realignInputLinkSlots to take Iterable<[NodeId, Pick]>; the atomicity test still passed ISerialisedNode[], which broke Lint/Format typecheck in the merge group. --- .../src/node/graphCallSiteAtomicity.test.ts | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts index aec0100d5aa..1ceb9bbafe3 100644 --- a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts +++ b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts @@ -254,15 +254,11 @@ describe('updateEndpoints – realignInputLinkSlots() atomicity', () => { }) vi.spyOn(console, 'error').mockImplementation(() => {}) - const serialized = [ - { - id: target.id, - inputs: [ - { name: 'x', link: target.getInputLink(0)!.id as unknown as number } - ] - } - ] as unknown as ISerialisedNode[] - realignInputLinkSlots(graph, serialized) + const nodeData: Pick = { + id: target.id, + inputs: [{ name: 'x', type: 'INT', link: target.getInputLink(0)!.id }] + } + realignInputLinkSlots(graph, [[target.id, nodeData]]) expect(updateEndpoints).toHaveBeenCalledOnce() expect(updateEndpoints).toHaveReturnedWith( From 5bb423a9184d050b2f6d7e38068976c5da01bfbf Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 22:29:26 +0000 Subject: [PATCH 4/8] test: cover rejected node store registration Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/15721#discussion_r3908834482 --- .../src/node/graphCallSiteAtomicity.test.ts | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts index 1ceb9bbafe3..d49d759e303 100644 --- a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts +++ b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts @@ -16,6 +16,7 @@ import { realignInputLinkSlots } from '@/lib/litegraph/src/linkDeduplication' import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph' import type { ISerialisedNode } from '@/lib/litegraph/src/types/serialisation' import { useLinkStore } from '@/stores/linkStore' +import { useNodeDataStore } from '@/stores/nodeDataStore' // --------------------------------------------------------------------------- // Fixtures @@ -62,14 +63,16 @@ describe('attachNodeToStores – LGraph.add() atomicity', () => { expect(graph._nodes_by_id[candidate.id]).toBe(candidate) }) - it('never adds a node to _nodes before store registration succeeds', () => { + it('leaves graph indexes unchanged when store registration throws', () => { const graph = new LGraph() - // Confirm the node is fully registered on first access to _nodes. const node = new LGraphNode('N') - graph.add(node) + vi.spyOn(useNodeDataStore(), 'registerNode').mockImplementation(() => { + throw new Error('forced registration failure') + }) - expect(graph._nodes).toContain(node) - expect(node._graphScope).toBeDefined() + expect(() => graph.add(node)).toThrow('forced registration failure') + expect(graph._nodes).toEqual([]) + expect(graph._nodes_by_id).toEqual({}) }) }) From dd570b8dfd703fb229838e9e77f36d27795fae4c Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 22:33:36 +0000 Subject: [PATCH 5/8] docs: refresh graph atomicity audit Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/15721#discussion_r3908834466 https://github.com/Comfy-Org/ComfyUI_frontend/pull/15721#discussion_r3908834472 https://github.com/Comfy-Org/ComfyUI_frontend/pull/15721#discussion_r3908834476 --- .../ecs/ecs-extension-compatibility-audit.md | 41 +++++++++++-------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/architecture/ecs/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md index b625e2a9385..15ab0d061b1 100644 --- a/docs/architecture/ecs/ecs-extension-compatibility-audit.md +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -189,29 +189,34 @@ is later architecture work outside this data-centralization phase. ## Graph-level call-site atomicity audit -Audited against `345eddfef` (2026-08-24). All graph-level callers of +Audited against `d196434c1b` (2026-09-01). All graph-level callers of `attachNodeToStores` (via `registerNodeState`), `replaceLink` (via -`replaceLinkTopology`), and `updateEndpoints` follow validate-then-mutate -ordering. No non-atomic sites were found. - -| Call site | Function called | Atomic? | Notes | -| ------------------------------------------------------ | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `LGraph.add()` (`LGraph.ts:1169`) | `attachNodeToStores` → `registerNodeState` | Yes | `attachNodeToStores` retries with a fresh minted id on collision; `node.graph = this` is set before the call but graph arrays mutate only after registration succeeds. | -| `LGraphNode.connect()` (`LGraphNode.ts:3171`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before any topology mutation when `replaceLinkTopology` returns `false`. `finalizeInputLinkRemoval`, slot updates, and `onConnectionsChange` all follow the guard. | -| `SubgraphInput.connect()` (`SubgraphInput.ts:102`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `_disconnectNodeInput`, `linkIds.push`, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | -| `SubgraphOutput.connect()` (`SubgraphOutput.ts:73`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `existingLink.disconnect`, `linkIds[0]` assignment, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | -| `replaceNodeInputs()` (`node/slotLinks.ts:187`) | `updateEndpoints` | Yes | Returns `[]` on `!result.ok` before `node.inputs.splice` or `finalizeInputLinkRemoval`. | -| `realignInputLinkSlots()` (`linkDeduplication.ts:154`) | `updateEndpoints` | Yes | Breaks the pass loop on `!result.ok` before firing any `onConnectionsChange` callbacks. | +`replaceLinkTopology`), and direct `updateEndpoints` batches were re-verified. +Each rejected registration or endpoint batch leaves its graph indexes or +topology unchanged. No non-atomic sites were found within those batch +boundaries. + +| Call site | Function called | Atomic? | Notes | +| ------------------------------------------------------------------ | ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LGraph.add()` (`LGraph.ts:1316`) | `attachNodeToStores` → `registerNodeState` | Yes | `attachNodeToStores` retries with a fresh minted id on collision; `node.graph = this` is set before the call but graph arrays mutate only after registration succeeds. | +| `LGraphNode.connect()` (`LGraphNode.ts:3221`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before any topology mutation when `replaceLinkTopology` returns `false`. `finalizeInputLinkRemoval`, slot updates, and `onConnectionsChange` all follow the guard. | +| `SubgraphInput.connect()` (`subgraph/SubgraphInput.ts:102`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `_disconnectNodeInput`, `linkIds.push`, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | +| `SubgraphOutput.connect()` (`subgraph/SubgraphOutput.ts:73`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `existingLink.disconnect`, `linkIds[0]` assignment, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | +| `replaceNodeInputs()` (`node/slotLinks.ts:192`) | `updateEndpoints` | Yes | Returns on `!result.ok` before `node.inputs.splice` or `finalizeInputLinkRemoval`. | +| reminted endpoint remap in `LGraph.configure()` (`LGraph.ts:2949`) | `updateEndpoints` | Yes | Marks configuration as errored on `!result.ok`; the rejected endpoint batch does not mutate topology. Node and link registrations completed before this batch remain. | +| `realignInputLinkSlots()` (`linkDeduplication.ts:200`) | `updateEndpoints` | Yes | A rejected endpoint batch fires no callbacks and marks its blocked links as skipped. The pass loop continues, so later successful batches for remaining links can fire `onConnectionsChange`. | ### Declared-non-atomic edge cases -These are cosmetic side effects that leave no graph inconsistency. They are -pinned by `it.fails` assertions in -`src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts`. +This cosmetic side effect leaves no graph inconsistency. The +`LGraphNode.connect()` case is pinned by an `it.fails` assertion in +`src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts`; the equivalent +subgraph call sites remain audit findings rather than executable assertions. -| Edge case | Observable partial state | Severity | -| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `mintLinkId` runs before `replaceLinkTopology` in `LGraphNode.connect()`, `SubgraphInput.connect()`, and `SubgraphOutput.connect()`. | `graph.state.lastLinkId` advances even when `replaceLinkTopology` is rejected, creating a gap in the link ID sequence. No topology is corrupted; no dangling link or double-registered slot results. | Cosmetic — IDs remain unique and monotonic, just non-contiguous. | +| Edge case | Observable partial state | Severity | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `mintLinkId` runs before `replaceLinkTopology` in `LGraphNode.connect()`. | `graph.state.lastLinkId` advances even when `replaceLinkTopology` is rejected, creating a gap in the link ID sequence. No topology is corrupted; no dangling link or double-registered slot results. | Cosmetic — IDs remain unique and monotonic, just non-contiguous. | +| `mintLinkId` also runs first in `SubgraphInput.connect()` and `SubgraphOutput.connect()`; these cases are audited but not pinned by this test file. | The subgraph's `state.lastLinkId` likewise advances on rejection without changing topology. | Cosmetic — IDs remain unique and monotonic, just non-contiguous. | ## Required follow-up evidence From 78c6042d616e895c567057ee97cb9f9f09c6ca2b Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Fri, 11 Sep 2026 01:28:24 -0700 Subject: [PATCH 6/8] test: use the global testing pinia in the atomicity spec The comfy/use-global-pinia rule landed on main after this branch opened and fails on the per-describe createTestingPinia calls. vitest.setup.ts already installs a fresh testing pinia before every test. --- .../src/node/graphCallSiteAtomicity.test.ts | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts index d49d759e303..814feffff7f 100644 --- a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts +++ b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts @@ -8,9 +8,7 @@ * docs/architecture/ecs/ecs-extension-compatibility-audit.md under * "Declared-non-atomic edge cases". */ -import { createTestingPinia } from '@pinia/testing' -import { setActivePinia } from 'pinia' -import { beforeEach, describe, expect, it, vi } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { realignInputLinkSlots } from '@/lib/litegraph/src/linkDeduplication' import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph' @@ -41,8 +39,6 @@ function connectedPair() { // --------------------------------------------------------------------------- describe('attachNodeToStores – LGraph.add() atomicity', () => { - beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) - it('resolves an id collision by re-minting before mutating graph arrays', () => { // Pre-plant a node so its id is already taken in the store. const graph = new LGraph() @@ -81,8 +77,6 @@ describe('attachNodeToStores – LGraph.add() atomicity', () => { // --------------------------------------------------------------------------- describe('replaceLinkTopology – LGraphNode.connect() atomicity', () => { - beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) - it('leaves the graph unchanged when the store rejects replaceLink', () => { const { source, target, link } = connectedPair() const graph = source.graph! @@ -163,8 +157,6 @@ describe('replaceLinkTopology – LGraphNode.connect() atomicity', () => { // --------------------------------------------------------------------------- describe('updateEndpoints – replaceNodeInputs() atomicity', () => { - beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) - it('does not splice node.inputs when updateEndpoints is rejected', () => { const graph = new LGraph() const source = new LGraphNode('S') @@ -233,8 +225,6 @@ describe('updateEndpoints – replaceNodeInputs() atomicity', () => { // --------------------------------------------------------------------------- describe('updateEndpoints – realignInputLinkSlots() atomicity', () => { - beforeEach(() => setActivePinia(createTestingPinia({ stubActions: false }))) - it('keeps the original connection when updateEndpoints is rejected', () => { const graph = new LGraph() const source = new LGraphNode('S') From 87b06ac1080c763e0bc095d7afb62686aef0f884 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Fri, 11 Sep 2026 01:28:54 -0700 Subject: [PATCH 7/8] audit: scope the graph-level atomicity claim to its verified population The section claimed all graph-level callers of attachNodeToStores, replaceLink and updateEndpoints had been re-verified, but the table only covered sites inside src/lib/litegraph. Two direct store callers outside it were never looked at: the remote connect applier in graphMutations.ts and replaceNodesInPlace in useNodeReplacement.ts. State the audited population explicitly, name the two routes into the same store functions that remain out of scope, add both missing rows, and refresh the drifted line numbers. The graphMutations.ts site is atomic only by precondition: the store signals rejection with a bare undefined, and nothing at the call site would stop detachLinkSlots from clearing the occupant's endpoint slots. Its guard was added incidentally by #16219 and had no test; pin it with a spec that stubs replaceLink to reject and asserts the occupant keeps its topology and slots. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/15721#discussion_r3912719902 --- .../ecs/ecs-extension-compatibility-audit.md | 87 +++++++++++++++---- src/core/graph/graphMutations.test.ts | 43 +++++++++ 2 files changed, 112 insertions(+), 18 deletions(-) diff --git a/docs/architecture/ecs/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md index 15ab0d061b1..4742d5da3b3 100644 --- a/docs/architecture/ecs/ecs-extension-compatibility-audit.md +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -189,22 +189,72 @@ is later architecture work outside this data-centralization phase. ## Graph-level call-site atomicity audit -Audited against `d196434c1b` (2026-09-01). All graph-level callers of -`attachNodeToStores` (via `registerNodeState`), `replaceLink` (via -`replaceLinkTopology`), and direct `updateEndpoints` batches were re-verified. -Each rejected registration or endpoint batch leaves its graph indexes or -topology unchanged. No non-atomic sites were found within those batch -boundaries. - -| Call site | Function called | Atomic? | Notes | -| ------------------------------------------------------------------ | ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `LGraph.add()` (`LGraph.ts:1316`) | `attachNodeToStores` → `registerNodeState` | Yes | `attachNodeToStores` retries with a fresh minted id on collision; `node.graph = this` is set before the call but graph arrays mutate only after registration succeeds. | -| `LGraphNode.connect()` (`LGraphNode.ts:3221`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before any topology mutation when `replaceLinkTopology` returns `false`. `finalizeInputLinkRemoval`, slot updates, and `onConnectionsChange` all follow the guard. | -| `SubgraphInput.connect()` (`subgraph/SubgraphInput.ts:102`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `_disconnectNodeInput`, `linkIds.push`, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | -| `SubgraphOutput.connect()` (`subgraph/SubgraphOutput.ts:73`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `existingLink.disconnect`, `linkIds[0]` assignment, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | -| `replaceNodeInputs()` (`node/slotLinks.ts:192`) | `updateEndpoints` | Yes | Returns on `!result.ok` before `node.inputs.splice` or `finalizeInputLinkRemoval`. | -| reminted endpoint remap in `LGraph.configure()` (`LGraph.ts:2949`) | `updateEndpoints` | Yes | Marks configuration as errored on `!result.ok`; the rejected endpoint batch does not mutate topology. Node and link registrations completed before this batch remain. | -| `realignInputLinkSlots()` (`linkDeduplication.ts:200`) | `updateEndpoints` | Yes | A rejected endpoint batch fires no callbacks and marks its blocked links as skipped. The pass loop continues, so later successful batches for remaining links can fire `onConnectionsChange`. | +Audited against `3d7c5d4df3` (2026-09-11). The audited population is every +call site outside `src/stores/linkStore.ts` itself that reaches one of: + +- `attachNodeToStores` (which wraps `registerNodeState`); +- `useLinkStore().replaceLink`, whether through `replaceLinkTopology` or + called on the store directly; +- `useLinkStore().updateEndpoints` as a multi-update batch. + +The table is the complete result of grepping those three identifiers across +`src/`, not a sample. Two other routes into the same store functions are +deliberately **out of scope and unaudited**: `useLinkStore().registerLink` +(the fresh-registration path, reached only from `registerLinkTopology`), and +the single-patch `LLink.updateEndpoints` → `updateEndpoint` wrapper, which has +no sibling mutations to leave half-applied. + +Every site in the table rejects without leaving graph indexes or topology +inconsistent. One of them — the remote `connect` applier in +`graphMutations.ts` — is atomic only because of a precondition validated +elsewhere, and is called out below. + +| Call site | Function called | Atomic? | Notes | +| --------------------------------------------------------------------- | ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LGraph.add()` (`LGraph.ts:1383`) | `attachNodeToStores` → `registerNodeState` | Yes | `attachNodeToStores` retries with a fresh minted id on collision; `node.graph = this` is set before the call but graph arrays mutate only after registration succeeds. | +| `LGraphNode.connect()` (`LGraphNode.ts:3211`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before any topology mutation when `replaceLinkTopology` returns `false`. `finalizeInputLinkRemoval`, slot updates, and `onConnectionsChange` all follow the guard. | +| `SubgraphInput.connect()` (`subgraph/SubgraphInput.ts:102`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `_disconnectNodeInput`, `linkIds.push`, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | +| `SubgraphOutput.connect()` (`subgraph/SubgraphOutput.ts:73`) | `replaceLinkTopology` → `replaceLink` | Yes | Returns before `existingLink.disconnect`, `linkIds[0]` assignment, and `anchorRerouteChain` when `replaceLinkTopology` returns `false`. | +| remote `connect` applier in `graphMutations.ts:713` | `replaceLink` (direct store call) | Cond. | `if (!replacement) break` precedes `detachLinkSlots` and the `updateNodeSlots` writes. Atomic only by that guard plus the `prepare()` precondition — see below. | +| `replaceNodeInputs()` (`node/slotLinks.ts:192`) | `updateEndpoints` | Yes | Returns on `!result.ok` before `node.inputs.splice` or `finalizeInputLinkRemoval`. | +| reminted endpoint remap in `LGraph.configure()` (`LGraph.ts:3203`) | `updateEndpoints` | Yes | Marks configuration as errored on `!result.ok`; the rejected endpoint batch does not mutate topology. Node and link registrations completed before this batch remain. | +| `realignInputLinkSlots()` (`linkDeduplication.ts:240`) | `updateEndpoints` | Yes | A rejected endpoint batch fires no callbacks and marks its blocked links as skipped. The pass loop continues, so later successful batches for remaining links can fire `onConnectionsChange`. | +| `replaceNodesInPlace()` (`nodeReplacement/useNodeReplacement.ts:308`) | `updateEndpoints` | Yes | The only site that rolls back rather than returning early: shell ownership moves to the replacement before the batch, and `!topologyResult.ok` reverses it with `transferReplacementOwnership(newNode, node)` before bailing out. | + +### `graphMutations.ts` is atomic by precondition, not locally + +The remote `connect` applier is the one audited site whose atomicity does not +follow from reading the call site alone. The store's rejection signal is a +plain `undefined` return, and the surrounding code performs three further +mutations (`detachLinkSlots`, `linkPresentationStore.take`, and two +`updateNodeSlots` writes) that all assume the replacement was placed. + +Two layers keep it correct, and only one of them was written for this purpose: + +1. `prepare()` rejects the whole batch before any write when the incoming link + id is already owned by a sibling graph. That is the only way `replaceLink` + can reject from this call site: the displaced occupant is read back out of + the same target index `replaceLink` validates against, so neither the + ownership check nor the occupied-slot check can fire. +2. The `if (!replacement) break` guard, added by #16219 (2026-09-08) as a side + effect of link-presentation work rather than as an atomicity fix. + +Because layer 1 makes the rejection unreachable, layer 2 has no test that +exercises it through the public API. `leaves the target occupant attached when +the link store rejects the replacement` in +`src/core/graph/graphMutations.test.ts` stubs `replaceLink` to return +`undefined` and asserts the occupant keeps both its topology and its endpoint +slots; deleting the `break` fails it. Without that guard — the shape this code +had before #16219 — a sibling-owned id collision that reached `commit()` left +the occupant's topology registered and target-indexed while its endpoint slots +were cleared. + +Removing layer 1 alone is not graph corruption but is still a silent failure: +`batch()` returns `true` having dropped a queued `connect`. + +A durable fix would be for `replaceLink` to return a discriminated result like +`updateEndpoints` does, so the rejection cannot be dropped by omission. That is +out of scope for this audit. ### Declared-non-atomic edge cases @@ -222,8 +272,9 @@ subgraph call sites remain audit findings rather than executable assertions. Existing evidence includes `LLink.store.test.ts`, `NodeInputSlot.test.ts`, `NodeOutputSlot.test.ts`, `slotLinks.test.ts`, `LGraphNode.test.ts`, -`LGraph.test.ts`, `nodeBadgeDraw.test.ts`, and browser geometry/registration -specs under `browser_tests/tests/vueNodes/`. +`LGraph.test.ts`, `graphMutations.test.ts`, `useNodeReplacement.test.ts`, +`nodeBadgeDraw.test.ts`, and browser geometry/registration specs under +`browser_tests/tests/vueNodes/`. Before removing compatibility shims, collect ecosystem evidence for: diff --git a/src/core/graph/graphMutations.test.ts b/src/core/graph/graphMutations.test.ts index 5ba0bd0c778..1187361d3d8 100644 --- a/src/core/graph/graphMutations.test.ts +++ b/src/core/graph/graphMutations.test.ts @@ -125,6 +125,49 @@ describe('graphMutations', () => { expect(presentation.getPresentation(scope, toLinkId(10))).toBeUndefined() }) + it('leaves the target occupant attached when the link store rejects the replacement', () => { + const graph = mutations() + graph.batch(context, (batch) => { + batch.addNode(node(1)) + batch.addNode(node(2)) + batch.addNode(node(3)) + batch.connect({ + id: 50, + originNodeId: 1, + originSlot: 0, + targetNodeId: 3, + targetSlot: 0, + type: 'IMAGE', + originOutputs: [{ name: 'out', type: 'IMAGE', links: [50] }], + targetInputs: [{ name: 'in', type: 'IMAGE', link: 50 }] + }) + }) + + const links = useLinkStore() + vi.spyOn(links, 'replaceLink').mockReturnValueOnce(undefined) + + graph.connect( + { + id: 51, + originNodeId: 2, + originSlot: 0, + targetNodeId: 3, + targetSlot: 0, + type: 'IMAGE' + }, + context + ) + + const nodes = useNodeDataStore().getGraphNodesFor('root', 'root') + expect(links.getInputSlotLink(scope, toNodeId(3), 0)?.id).toBe(toLinkId(50)) + expect(nodes.find(({ id }) => id === toNodeId(3))?.inputs[0].link).toBe( + toLinkId(50) + ) + expect( + nodes.find(({ id }) => id === toNodeId(1))?.outputs[0].links + ).toEqual([toLinkId(50)]) + }) + it('preserves presentation when a remote batch reconnects the same link id', () => { const graph = mutations() const link = { From 7fe319c47b185ecdba4341acbcde12b9e38db597 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Fri, 11 Sep 2026 01:53:04 -0700 Subject: [PATCH 8/8] test: assert slot identity and callback suppression on rejected input splice --- .../litegraph/src/node/graphCallSiteAtomicity.test.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts index 814feffff7f..139aec6530e 100644 --- a/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts +++ b/src/lib/litegraph/src/node/graphCallSiteAtomicity.test.ts @@ -170,6 +170,10 @@ describe('updateEndpoints – replaceNodeInputs() atomicity', () => { source.connect(0, target, 1) const inputsBefore = [...target.inputs] + const linkAtA = target.getInputLink(0)!.id + const linkAtB = target.getInputLink(1)!.id + const onInputRemoved = vi.fn() + target.onInputRemoved = onInputRemoved // The last test in legacySlotLinkMutations.test.ts already exercises the // "keeps the input layout when the endpoint batch is rejected" path via @@ -193,6 +197,11 @@ describe('updateEndpoints – replaceNodeInputs() atomicity', () => { ) // Both links are still registered. expect(graph.links.size).toBe(2) + // Which link sits in which slot, not just how many survive. + expect(target.getInputLink(0)?.id).toBe(linkAtA) + expect(target.getInputLink(1)?.id).toBe(linkAtB) + // A rejected splice must not have announced a removal. + expect(onInputRemoved).not.toHaveBeenCalled() }) it('splices inputs and updates endpoints together on success', () => {