Skip to content

feat(nodeShell): assert node registration-identity invariants - #14443

Merged
mattmillerai merged 3 commits into
matt/be-5050-node-shell-statefrom
matt/be-5048-registration-invariants
Aug 18, 2026
Merged

mattmillerai merged 3 commits into
matt/be-5050-node-shell-statefrom
matt/be-5048-registration-invariants

Conversation

@mattmillerai

Copy link
Copy Markdown
Member

STACKED — merging lands on matt/be-5050-node-shell-state (#14257, which itself targets feature/ecs-migration), NOT main.

ELI-5

When a node joins or leaves a graph, the app files its "shell state" into a store so the renderer can draw it. Two ways that filing can go wrong today fail silently: filing a node that is already filed under a different workflow strands the old entry, and un-filing a state the store never held leaves a ghost the renderer keeps drawing. Both now trip an assertion (throws in DEV, reports via the assert reporter in prod) instead of drifting quietly. No behavior changes when the invariants hold.

What changed

src/core/graph/nodeShell/nodeShellState.ts

  • registerNodeState asserts node._graphId is unset or already equals graph.rootGraph.id before overwriting it. Membership is by state identity, so a node re-registered under a second root graph leaves its first bucket entry behind with nothing to remove it.
  • unregisterNodeState captures deleteNode's boolean instead of discarding it and asserts it. false means the bucket did not contain node._state — identity drift, e.g. _state reassigned after registration.

Both messages name the node id. _graphId is cleared before the assertion so a failing teardown still leaves the node detached rather than half-registered.

Deliberately not shipped: the duplicate-NodeState assertion

The third invariant asked for — asserting the store never holds two distinct NodeState objects for one (graphId, id) — was implemented (an auxiliary forward Map<string, NodeState> plus a Map<NodeState, string> reverse map per bucket, so a renumbered node still de-indexes by identity) and then reverted, because it is not a regression net on this base: it fires on legitimate existing behavior.

Evidence, all from the suite on this branch:

  • LGraph.serialise.test.ts > can (de)serialise node / group titles — new LGraph(data) (LGraph.ts:476 → configure:2636 → add:1092) keeps the persisted graph id, so a round-tripped copy shares a bucket with the graph it was serialised from and collides on every node id.
  • LGraph.test.ts > Link serialization goldens (4 tests) and LGraph.test.ts > deduplicateSubgraphNodeIds (via configure) > warns when configuring a host with legacy proxyWidgets… fail the same way.

That is 6 tests, green on this base and green again with the assertion removed — so this is the assertion's premise being wrong, not a latent bug those tests were hiding. subgraphDeduplication.ts guarantees id-uniqueness within one root graph; it says nothing about two live LGraph instances that carry the same id. Making duplicate ids assertable means giving each LGraph instance its own bucket identity rather than keying buckets by graph id — a separate change with real blast radius (getGraphNodesFor callers, clearGraph, the canvasStore.rootGraphId readers), not a rider on this one. docs/architecture/node-data-store.md records both the two shipped invariants and this gap.

Tests

nodeShellState.test.ts gains the two cases; both are red without the production change (verified by stashing it). The cross-root case needs an explicit second.id = createUuidv4() — two fresh LGraphs both sit at zeroUuid until configure, so they share a bucket and the invariant genuinely holds.

Verification

Targeted: nodeShellState.test.ts, nodeDataStore.test.ts, useNodeReplacement.test.ts, LGraph.test.ts, LGraph.serialise.test.ts — 82 tests pass, 0 fail. oxfmt --check clean.

Full vitest run was executed and is the reason the third assertion was reverted (it caught the 6 failures above). That run is not a clean-suite claim: this worktree borrows the parent clone's node_modules, which predates the minisearch dependency this branch adds, so 222 suites failed to resolve imports for reasons unrelated to the diff. Of the tests that did run, the only failures attributable to the diff were the 6 named above; the rest (assetService, useAssetGridSelection, onboardingCloudRoutes, …) are the same load-dependent set #14257 reported. A reviewer should treat repo-wide CI as the authority here, not this local run. Repo-wide pnpm typecheck was likewise not run locally — the diff is 11 lines of source plus tests, and both changed files typecheck under vitest's transform.

@coderabbitai

coderabbitai Bot commented Jul 31, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0e79ba8f-824f-449d-ac0d-ee8f23328613

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@mattmillerai mattmillerai added agent-coded Opened by the agent-work code loop cursor-review Trigger multi-model Cursor agent review on this PR labels Jul 31, 2026
@mattmillerai
mattmillerai marked this pull request as ready for review July 31, 2026 00:57
@dosubot dosubot Bot added the size:S This PR changes 10-29 lines, ignoring generated files. label Jul 31, 2026
@dosubot

dosubot Bot commented Jul 31, 2026

Copy link
Copy Markdown

📄 Knowledge review

Dosu skipped reviewing this PR because your organization has used its 200 included credits for the month. Your usage will reset on 2026-08-01. To have Dosu review this PR before then, ask your organization admin to upgrade to a pro account.


Leave Feedback Ask Dosu about ComfyUI_frontend Add Dosu to your team

@github-actions

github-actions Bot commented Jul 31, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 08/16/2026, 11:12:35 AM UTC

Links

🎭 Playwright: 🕵🏻 0 passed, 0 failed

📊 Browser Reports
  • chromium: ❌ Deployment failed
  • chromium-2x: ❌ Deployment failed
  • chromium-0.5x: ❌ Deployment failed
  • mobile-chrome: ❌ Deployment failed

📦 Bundle Size

⏳ Size data collection in progress…

⚡ Performance

⚠️ Performance tests failed. Check the CI workflow logs.

@codecov

codecov Bot commented Jul 31, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@                      Coverage Diff                       @@
##           matt/be-5050-node-shell-state   #14443   +/-   ##
==============================================================
  Coverage                          81.03%   81.04%           
==============================================================
  Files                               1899     1899           
  Lines                             109786   109795    +9     
  Branches                           34163    34167    +4     
==============================================================
+ Hits                               88969    88978    +9     
  Misses                             20423    20423           
  Partials                             394      394           
Flag Coverage Δ
unit 72.83% <100.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/core/graph/nodeShell/nodeShellState.ts 100.00% <100.00%> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

Found 5 finding(s).

Severity Count
🟠 High 2
🟡 Medium 2
🟢 Low 1

Panel: 8/8 reviewers contributed findings.

@dosubot dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. and removed size:S This PR changes 10-29 lines, ignoring generated files. labels Jul 31, 2026
@mattmillerai

Copy link
Copy Markdown
Member Author

STACKED — merging lands on matt/be-5050-node-shell-state (PR #14257, @mattmillerai), NOT main.

Merge #14257 first, or this PR's commits land on that branch rather than the default branch.

Review resolution pushed in c6e0242 — all five cursor-review threads addressed (1 code fix, 4 replies). Detail on the threads; the one code change: registerNodeState now deletes the previous root's bucket entry before re-registering, so the production path (where assert reports instead of throwing) no longer strands a ghost state. Covered by a DEV=false test that fails without it.

registerNodeState now refuses to re-register a node under a different root graph, and unregisterNodeState checks the store's delete result instead of discarding it.
assert throws only in DEV, so both invariant paths must leave the store
consistent on their own. registerNodeState now drops the previous root's
bucket entry before re-registering, instead of stranding a ghost the
renderer keeps drawing in production builds.
Deleting the previous root's bucket entry without clearing _graphId left
the node pointing at a bucket it no longer occupies, so a DEV throw could
cascade into the unregister-side drift assert.
@mattmillerai

Copy link
Copy Markdown
Member Author

STACKED — merging lands on matt/be-5050-node-shell-state (PR #14257, @mattmillerai), NOT main. Merge #14257 first, or this PR's commits land on that branch rather than the default branch.

Rebased onto the latest #14257 tip (af6567cdee) to clear a merge conflict — the base branch was rebased onto a newer main since this PR last synced, which is why GitHub showed CONFLICTING. Force-pushing the rebase now (same author, own feature branch); no review-thread content changes, all 5 cursor-review threads were already resolved in the prior push and carry forward unchanged.

Known blocker outside this PR's scope: the current base tree fails to build/test — src/lib/litegraph/src/LGraph.ts calls useLinkStore(), useRerouteStore(), and useNodeDataStore() without importing them. This was introduced by 20cd48ce26 ("refactor!: migrate entity state to dedicated stores"), which is below #14257 in the stack, not part of #14257's or #14443's own diff. #14257's own CI is fully red for the same reason. #14443 can't go green until that's fixed upstream and this branch is rebased again.

@mattmillerai
mattmillerai force-pushed the matt/be-5048-registration-invariants branch from 789cc6f to 097d2b7 Compare August 16, 2026 11:10
@github-actions github-actions Bot added the risk:R2 PR risk grade (advisory shadow check; grader-owned) label Aug 16, 2026
@mattmillerai
mattmillerai merged commit a80a5e1 into matt/be-5050-node-shell-state Aug 18, 2026
35 of 43 checks passed
@mattmillerai
mattmillerai deleted the matt/be-5048-registration-invariants branch August 18, 2026 20:32
mattmillerai added a commit that referenced this pull request Aug 20, 2026
**STACKED — merging lands on `matt/be-5050-node-shell-state` (#14257,
which itself targets `feature/ecs-migration`), NOT `main`.**

## ELI-5

When a node joins or leaves a graph, the app files its "shell state"
into a store so the renderer can draw it. Two ways that filing can go
wrong today fail silently: filing a node that is already filed under a
*different* workflow strands the old entry, and un-filing a state the
store never held leaves a ghost the renderer keeps drawing. Both now
trip an assertion (throws in DEV, reports via the assert reporter in
prod) instead of drifting quietly. No behavior changes when the
invariants hold.

## What changed

`src/core/graph/nodeShell/nodeShellState.ts`

- `registerNodeState` asserts `node._graphId` is unset or already equals
`graph.rootGraph.id` before overwriting it. Membership is by state
identity, so a node re-registered under a second root graph leaves its
first bucket entry behind with nothing to remove it.
- `unregisterNodeState` captures `deleteNode`'s boolean instead of
discarding it and asserts it. `false` means the bucket did not contain
`node._state` — identity drift, e.g. `_state` reassigned after
registration.

Both messages name the node id. `_graphId` is cleared before the
assertion so a failing teardown still leaves the node detached rather
than half-registered.

## Deliberately not shipped: the duplicate-`NodeState` assertion

The third invariant asked for — asserting the store never holds two
distinct `NodeState` objects for one `(graphId, id)` — was implemented
(an auxiliary forward `Map<string, NodeState>` plus a `Map<NodeState,
string>` reverse map per bucket, so a renumbered node still de-indexes
by identity) and then **reverted**, because it is not a regression net
on this base: it fires on legitimate existing behavior.

Evidence, all from the suite on this branch:

- `LGraph.serialise.test.ts > can (de)serialise node / group titles` —
`new LGraph(data)` (`LGraph.ts:476` → `configure:2636` → `add:1092`)
keeps the *persisted* graph id, so a round-tripped copy shares a bucket
with the graph it was serialised from and collides on every node id.
- `LGraph.test.ts > Link serialization goldens` (4 tests) and
`LGraph.test.ts > deduplicateSubgraphNodeIds (via configure) > warns
when configuring a host with legacy proxyWidgets…` fail the same way.

That is 6 tests, green on this base and green again with the assertion
removed — so this is the assertion's premise being wrong, not a latent
bug those tests were hiding. `subgraphDeduplication.ts` guarantees
id-uniqueness *within* one root graph; it says nothing about two live
`LGraph` instances that carry the same id. Making duplicate ids
assertable means giving each `LGraph` instance its own bucket identity
rather than keying buckets by graph id — a separate change with real
blast radius (`getGraphNodesFor` callers, `clearGraph`, the
`canvasStore.rootGraphId` readers), not a rider on this one.
`docs/architecture/node-data-store.md` records both the two shipped
invariants and this gap.

## Tests

`nodeShellState.test.ts` gains the two cases; both are red without the
production change (verified by stashing it). The cross-root case needs
an explicit `second.id = createUuidv4()` — two fresh `LGraph`s both sit
at `zeroUuid` until `configure`, so they share a bucket and the
invariant genuinely holds.

## Verification

Targeted: `nodeShellState.test.ts`, `nodeDataStore.test.ts`,
`useNodeReplacement.test.ts`, `LGraph.test.ts`,
`LGraph.serialise.test.ts` — 82 tests pass, 0 fail. `oxfmt --check`
clean.

Full `vitest run` was executed and is the reason the third assertion was
reverted (it caught the 6 failures above). That run is **not** a
clean-suite claim: this worktree borrows the parent clone's
`node_modules`, which predates the `minisearch` dependency this branch
adds, so 222 suites failed to resolve imports for reasons unrelated to
the diff. Of the tests that did run, the only failures attributable to
the diff were the 6 named above; the rest (`assetService`,
`useAssetGridSelection`, `onboardingCloudRoutes`, …) are the same
load-dependent set #14257 reported. A reviewer should treat repo-wide CI
as the authority here, not this local run. Repo-wide `pnpm typecheck`
was likewise not run locally — the diff is 11 lines of source plus
tests, and both changed files typecheck under vitest's transform.
DrJKL pushed a commit that referenced this pull request Aug 22, 2026
**STACKED — merging lands on `matt/be-5050-node-shell-state` (#14257,
which itself targets `feature/ecs-migration`), NOT `main`.**

## ELI-5

When a node joins or leaves a graph, the app files its "shell state"
into a store so the renderer can draw it. Two ways that filing can go
wrong today fail silently: filing a node that is already filed under a
*different* workflow strands the old entry, and un-filing a state the
store never held leaves a ghost the renderer keeps drawing. Both now
trip an assertion (throws in DEV, reports via the assert reporter in
prod) instead of drifting quietly. No behavior changes when the
invariants hold.

## What changed

`src/core/graph/nodeShell/nodeShellState.ts`

- `registerNodeState` asserts `node._graphId` is unset or already equals
`graph.rootGraph.id` before overwriting it. Membership is by state
identity, so a node re-registered under a second root graph leaves its
first bucket entry behind with nothing to remove it.
- `unregisterNodeState` captures `deleteNode`'s boolean instead of
discarding it and asserts it. `false` means the bucket did not contain
`node._state` — identity drift, e.g. `_state` reassigned after
registration.

Both messages name the node id. `_graphId` is cleared before the
assertion so a failing teardown still leaves the node detached rather
than half-registered.

## Deliberately not shipped: the duplicate-`NodeState` assertion

The third invariant asked for — asserting the store never holds two
distinct `NodeState` objects for one `(graphId, id)` — was implemented
(an auxiliary forward `Map<string, NodeState>` plus a `Map<NodeState,
string>` reverse map per bucket, so a renumbered node still de-indexes
by identity) and then **reverted**, because it is not a regression net
on this base: it fires on legitimate existing behavior.

Evidence, all from the suite on this branch:

- `LGraph.serialise.test.ts > can (de)serialise node / group titles` —
`new LGraph(data)` (`LGraph.ts:476` → `configure:2636` → `add:1092`)
keeps the *persisted* graph id, so a round-tripped copy shares a bucket
with the graph it was serialised from and collides on every node id.
- `LGraph.test.ts > Link serialization goldens` (4 tests) and
`LGraph.test.ts > deduplicateSubgraphNodeIds (via configure) > warns
when configuring a host with legacy proxyWidgets…` fail the same way.

That is 6 tests, green on this base and green again with the assertion
removed — so this is the assertion's premise being wrong, not a latent
bug those tests were hiding. `subgraphDeduplication.ts` guarantees
id-uniqueness *within* one root graph; it says nothing about two live
`LGraph` instances that carry the same id. Making duplicate ids
assertable means giving each `LGraph` instance its own bucket identity
rather than keying buckets by graph id — a separate change with real
blast radius (`getGraphNodesFor` callers, `clearGraph`, the
`canvasStore.rootGraphId` readers), not a rider on this one.
`docs/architecture/node-data-store.md` records both the two shipped
invariants and this gap.

## Tests

`nodeShellState.test.ts` gains the two cases; both are red without the
production change (verified by stashing it). The cross-root case needs
an explicit `second.id = createUuidv4()` — two fresh `LGraph`s both sit
at `zeroUuid` until `configure`, so they share a bucket and the
invariant genuinely holds.

## Verification

Targeted: `nodeShellState.test.ts`, `nodeDataStore.test.ts`,
`useNodeReplacement.test.ts`, `LGraph.test.ts`,
`LGraph.serialise.test.ts` — 82 tests pass, 0 fail. `oxfmt --check`
clean.

Full `vitest run` was executed and is the reason the third assertion was
reverted (it caught the 6 failures above). That run is **not** a
clean-suite claim: this worktree borrows the parent clone's
`node_modules`, which predates the `minisearch` dependency this branch
adds, so 222 suites failed to resolve imports for reasons unrelated to
the diff. Of the tests that did run, the only failures attributable to
the diff were the 6 named above; the rest (`assetService`,
`useAssetGridSelection`, `onboardingCloudRoutes`, …) are the same
load-dependent set #14257 reported. A reviewer should treat repo-wide CI
as the authority here, not this local run. Repo-wide `pnpm typecheck`
was likewise not run locally — the diff is 11 lines of source plus
tests, and both changed files typecheck under vitest's transform.
DrJKL pushed a commit that referenced this pull request Aug 22, 2026
**STACKED — merging lands on `matt/be-5050-node-shell-state` (#14257,
which itself targets `feature/ecs-migration`), NOT `main`.**

## ELI-5

When a node joins or leaves a graph, the app files its "shell state"
into a store so the renderer can draw it. Two ways that filing can go
wrong today fail silently: filing a node that is already filed under a
*different* workflow strands the old entry, and un-filing a state the
store never held leaves a ghost the renderer keeps drawing. Both now
trip an assertion (throws in DEV, reports via the assert reporter in
prod) instead of drifting quietly. No behavior changes when the
invariants hold.

## What changed

`src/core/graph/nodeShell/nodeShellState.ts`

- `registerNodeState` asserts `node._graphId` is unset or already equals
`graph.rootGraph.id` before overwriting it. Membership is by state
identity, so a node re-registered under a second root graph leaves its
first bucket entry behind with nothing to remove it.
- `unregisterNodeState` captures `deleteNode`'s boolean instead of
discarding it and asserts it. `false` means the bucket did not contain
`node._state` — identity drift, e.g. `_state` reassigned after
registration.

Both messages name the node id. `_graphId` is cleared before the
assertion so a failing teardown still leaves the node detached rather
than half-registered.

## Deliberately not shipped: the duplicate-`NodeState` assertion

The third invariant asked for — asserting the store never holds two
distinct `NodeState` objects for one `(graphId, id)` — was implemented
(an auxiliary forward `Map<string, NodeState>` plus a `Map<NodeState,
string>` reverse map per bucket, so a renumbered node still de-indexes
by identity) and then **reverted**, because it is not a regression net
on this base: it fires on legitimate existing behavior.

Evidence, all from the suite on this branch:

- `LGraph.serialise.test.ts > can (de)serialise node / group titles` —
`new LGraph(data)` (`LGraph.ts:476` → `configure:2636` → `add:1092`)
keeps the *persisted* graph id, so a round-tripped copy shares a bucket
with the graph it was serialised from and collides on every node id.
- `LGraph.test.ts > Link serialization goldens` (4 tests) and
`LGraph.test.ts > deduplicateSubgraphNodeIds (via configure) > warns
when configuring a host with legacy proxyWidgets…` fail the same way.

That is 6 tests, green on this base and green again with the assertion
removed — so this is the assertion's premise being wrong, not a latent
bug those tests were hiding. `subgraphDeduplication.ts` guarantees
id-uniqueness *within* one root graph; it says nothing about two live
`LGraph` instances that carry the same id. Making duplicate ids
assertable means giving each `LGraph` instance its own bucket identity
rather than keying buckets by graph id — a separate change with real
blast radius (`getGraphNodesFor` callers, `clearGraph`, the
`canvasStore.rootGraphId` readers), not a rider on this one.
`docs/architecture/node-data-store.md` records both the two shipped
invariants and this gap.

## Tests

`nodeShellState.test.ts` gains the two cases; both are red without the
production change (verified by stashing it). The cross-root case needs
an explicit `second.id = createUuidv4()` — two fresh `LGraph`s both sit
at `zeroUuid` until `configure`, so they share a bucket and the
invariant genuinely holds.

## Verification

Targeted: `nodeShellState.test.ts`, `nodeDataStore.test.ts`,
`useNodeReplacement.test.ts`, `LGraph.test.ts`,
`LGraph.serialise.test.ts` — 82 tests pass, 0 fail. `oxfmt --check`
clean.

Full `vitest run` was executed and is the reason the third assertion was
reverted (it caught the 6 failures above). That run is **not** a
clean-suite claim: this worktree borrows the parent clone's
`node_modules`, which predates the `minisearch` dependency this branch
adds, so 222 suites failed to resolve imports for reasons unrelated to
the diff. Of the tests that did run, the only failures attributable to
the diff were the 6 named above; the rest (`assetService`,
`useAssetGridSelection`, `onboardingCloudRoutes`, …) are the same
load-dependent set #14257 reported. A reviewer should treat repo-wide CI
as the authority here, not this local run. Repo-wide `pnpm typecheck`
was likewise not run locally — the diff is 11 lines of source plus
tests, and both changed files typecheck under vitest's transform.
@huang47 huang47 added the risk:high PR risk grade (advisory shadow check; grader-owned) label Sep 2, 2026 — with ChatGPT Codex Connector
@huang47 huang47 removed the risk:R2 PR risk grade (advisory shadow check; grader-owned) label Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-coded Opened by the agent-work code loop cursor-review Trigger multi-model Cursor agent review on this PR risk:high PR risk grade (advisory shadow check; grader-owned) size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants