diff --git a/docs/adr/0003-crdt-based-layout-system.md b/docs/adr/0003-crdt-based-layout-system.md index db7d83d83be..9614935600c 100644 --- a/docs/adr/0003-crdt-based-layout-system.md +++ b/docs/adr/0003-crdt-based-layout-system.md @@ -150,7 +150,7 @@ history promised above is struck, and the Yjs document runs with the default `gc: true`, so it is a mergeable state record rather than a replayable one. Transmission stays a capability of the document rather than of the store: `applyUpdate` / `getStateAsUpdate` were removed as callerless (see -[Removed CRDT sync seam](../architecture/ecs-migration-plan.md)) and are a few +[Removed CRDT sync seam](../architecture/ecs/ecs-migration-plan.md)) and are a few lines against `this.ydoc` to reinstate. `LayoutOperation` is still the serializable command shape every mutation goes through. Producers supply the operation source; the store stamps its session actor at submission. diff --git a/docs/adr/0008-entity-component-system.md b/docs/adr/0008-entity-component-system.md index d9c8a7501ae..5da8f27d44d 100644 --- a/docs/adr/0008-entity-component-system.md +++ b/docs/adr/0008-entity-component-system.md @@ -272,7 +272,7 @@ System design is deferred to a future ADR. For detailed before/after walkthrough 4. **Incremental extraction** — migrate one component at a time from classes into its dedicated store, using the bridge layer for backward compatibility 5. **Deprecate class properties** — once all consumers read from the store, mark class properties as deprecated -For the phased migration roadmap with shipping milestones, see [ECS Migration Plan](../architecture/ecs-migration-plan.md). For the full target architecture, see [ECS Target Architecture](../architecture/ecs-target-architecture.md). For an inventory of existing stores that already partially implement ECS patterns, see [Proto-ECS Stores](../architecture/proto-ecs-stores.md). +For the phased migration roadmap with shipping milestones, see [ECS Migration Plan](../architecture/ecs/ecs-migration-plan.md). For the full target architecture, see [ECS Target Architecture](../architecture/ecs-target-architecture.md). For an inventory of existing stores that already partially implement ECS patterns, see [Proto-ECS Stores](../architecture/proto-ecs-stores.md). ### Relationship to ADR 0003 (Command Pattern / CRDT) @@ -331,7 +331,7 @@ Companion architecture documents that expand on the design in this ADR: | [Entity System Structural Problems](../architecture/entity-problems.md) | Detailed problem catalog with line-level code references motivating the ECS migration | | [Proto-ECS Stores](../architecture/proto-ecs-stores.md) | Inventory of existing Pinia stores that already partially implement ECS patterns | | [ECS Target Architecture](../architecture/ecs-target-architecture.md) | Full target architecture showing how entities and interactions transform under ECS | -| [ECS Migration Plan](../architecture/ecs-migration-plan.md) | Phased migration roadmap with shipping milestones and go/no-go criteria | +| [ECS Migration Plan](../architecture/ecs/ecs-migration-plan.md) | Phased migration roadmap with shipping milestones and go/no-go criteria | | [ECS Lifecycle Scenarios](../architecture/ecs-lifecycle-scenarios.md) | Before/after walkthroughs of lifecycle operations (node removal, link creation, etc.) | | [Subgraph Boundaries and Widget Promotion](../architecture/subgraph-boundaries-and-promotion.md) | Design rationale for modeling subgraphs as node components, not separate entities | | [Link Topology Store](../architecture/link-topology-store.md) | Design record for the `linkStore` — target-input-slot keying, root-scoped buckets, registration protocol | diff --git a/docs/architecture/appendix-ecs-pattern-survey.md b/docs/architecture/appendix-ecs-pattern-survey.md index 2e561a4c572..d68207963d1 100644 --- a/docs/architecture/appendix-ecs-pattern-survey.md +++ b/docs/architecture/appendix-ecs-pattern-survey.md @@ -386,6 +386,6 @@ keep the substrate at storage + identity and let Vue own scheduling. for the full target taxonomy and migration strategy. - [ECS Target Architecture](./ecs-target-architecture.md) for the full end-state shape. -- [ECS Migration Plan](./ecs-migration-plan.md) for shipping milestones. +- [ECS Migration Plan](./ecs/ecs-migration-plan.md) for shipping milestones. - [Appendix: Critical Analysis](./appendix-critical-analysis.md) for the independent verification of the architecture documents. diff --git a/docs/architecture/ecs-migration-plan.md b/docs/architecture/ecs-migration-plan.md deleted file mode 100644 index 09bb8c239e3..00000000000 --- a/docs/architecture/ecs-migration-plan.md +++ /dev/null @@ -1,1078 +0,0 @@ -# ECS Migration Plan - -A phased roadmap for migrating the litegraph entity system to the ECS -architecture described in [ADR 0008](../adr/0008-entity-component-system.md). -Each phase is independently shippable. Later phases depend on earlier ones -unless noted otherwise. - -For the problem analysis, see [Entity Problems](entity-problems.md). For the -target architecture, see [ECS Target Architecture](ecs-target-architecture.md). -For verified accuracy of these documents, see -[Appendix: Critical Analysis](appendix-critical-analysis.md). - -> **Target end-state (revised):** N dedicated Pinia stores keyed by composite -> string IDs, one store per concern (widget values, DOM widgets, layout, node -> outputs, subgraph navigation, preview exposure, link topology, reroute -> chains). The earlier "single unified -> World with branded numeric entity IDs and `getComponent`/`setComponent`" model -> was rejected. PR 12617 shipped the first stores against composite -> `graphId:nodeId:name` string keys (`WidgetId`). Phases below are reframed -> around dedicated stores; shipped work is marked ✅. - -## Planning assumptions - -- The bridge period is expected to span 2-3 release cycles. -- Bridge work is treated as transitional debt with explicit owners and sunset - checkpoints, not as a permanent architecture layer. -- Phase 5 is entered only by explicit go/no-go review against the criteria in - this document. - -## Phase 0: Foundation - -Zero behavioral risk. Prepares the codebase for extraction without changing -runtime semantics. All items are independently shippable. - -### 0a. Centralize version counter ✅ Shipped - -`LGraph.incrementVersion()` exists and is used everywhere. The counter is only -read for debug display in `LGraphCanvas.renderInfo()`; it is not used for -dirty-checking, caching, or reactivity. - -**Remaining cleanup:** One stray direct `_version++` at `LGraph.ts:831` should -be replaced with `incrementVersion()`. - -**Risk:** None. Mechanical one-line change; existing null guards preserved. - -### 0b. Add missing ID type aliases - -`NodeId`, `LinkId`, and `RerouteId` exist as type aliases. Two are missing: - -| Type | Definition | Location | -| ----------- | ---------- | ---------------------------------------------------------------- | -| `GroupId` | `number` | `LGraphGroup.ts` (currently implicit on `id: number` at line 39) | -| `SlotIndex` | `number` | `interfaces.ts` (slot positions are untyped `number` everywhere) | - -**Change:** Add the type aliases, update property declarations, re-export from -barrel (`litegraph.ts`). - -**Why:** Foundation for branded IDs. Type aliases are erased at compile time — -zero runtime impact. - -**Risk:** None. Type-only change. - -### 0c. Fix architecture doc errors - -Five factual errors verified during code review (see -[Appendix](appendix-critical-analysis.md#vii-summary-of-findings)): - -- `entity-problems.md`: `toJSON()` should be `toString()`, `execute()` should - be `doExecute()`, method count ~539 should be ~848, `configure()` is ~240 - lines not ~180 - ---- - -## Phase 1: Types and Dedicated Stores - -Introduces the ID type vocabulary and the dedicated stores. Phase 1 end-state is -N dedicated Pinia stores, each keyed by its own entity ID, coexisting with -legacy class instances. - -### 1a. Branded string ID types ✅ Shipped (PR 12617) - -`src/types/widgetId.ts` ships the branded string `WidgetId`: - -```ts -type WidgetId = string & { readonly __brand: 'WidgetId' } -``` - -Format: `graphId:nodeId:name`. A `parseWidgetId()` helper splits a `WidgetId` -back into its `{ graphId, nodeId, name }` parts at store boundaries. - -The composite string key carries the structural relationship (graph -> node -> -widget) directly in the key. There is no synthetic opaque number and no reverse -lookup index. - -**Consideration:** `NodeId = number | string`. The `string` branch exists for -subgraph-related nodes (GroupNode hack). The `WidgetId` format stringifies the -`nodeId` segment, so both numeric and string node IDs flow through unchanged. - -### 1b. Plain-data store state shapes - -Each dedicated store holds plain-data records for its concern — no methods on the -records, behavior lives in store actions and composables. State shapes mirror the -decomposition in ADR 0008 Section "Component Decomposition" (position, node type, -node visual, connectivity, execution, properties, widget container, link -endpoints). - -**Risk:** None. Type-only definitions. - -### 1c. Dedicated stores - -Phase 1 end-state is a set of dedicated Pinia stores, one per concern, each -keyed by its own entity ID — a composite string where the key has to carry the -graph relationship, a bare ID inside root-graph-scoped buckets where the bucket -already supplies it. Each store owns its data and exposes a narrow accessor -surface. There is no single container that fronts all entities. - -Shipped stores: - -| Store | File | -| -------------------------- | ----------------------------------------------- | -| `widgetValueStore` | `src/stores/widgetValueStore.ts` | -| `domWidgetStore` | `src/stores/domWidgetStore.ts` | -| `layoutStore` | `src/renderer/core/layout/store/layoutStore.ts` | -| `nodeOutputStore` | `src/stores/nodeOutputStore.ts` | -| `subgraphNavigationStore` | `src/stores/subgraphNavigationStore.ts` | -| `previewExposureStore` | `src/stores/previewExposureStore.ts` | -| `linkStore` ✅ PR 13436 | `src/stores/linkStore.ts` | -| `rerouteStore` ✅ PR 13449 | `src/stores/rerouteStore.ts` | -| `nodeDataStore` ✅ | `src/stores/nodeDataStore.ts` | - -`nodeBadgeStore` was shipped in PR 13458 and then deleted: badge rows are -cheaper to derive on read than to store, so `src/systems/badgeSystem.ts` -computes them from the stores that already own the inputs. No badge store -exists. See [Node Badge Store](node-badge-store.md) for the reversal. - -`linkStore` holds `LinkTopology` records (`src/types/linkTopology.ts`) in -root-graph-scoped buckets. Link identity is root-wide; input and output query -indexes use owner-qualified slot keys -(`` `${owningGraphId}:${nodeId}:${slot}` ``). Subgraphs share their root's -identity bucket while retaining owner-local queries and teardown. Floating -links remain in the root-wide identity map but are omitted from slot indexes. -Entity store registration is idempotent only when the existing entity has the -same owner and raw object identity. The stores perform every collision check at -the registration mutation boundary. -`rerouteStore` holds `RerouteChain` records keyed by `RerouteId` in -root-graph-scoped buckets; link membership is not stored but derived from the -links' `parentId` chains. -Design records: [Link Topology Store](link-topology-store.md), -[Reroute Chain Store](reroute-chain-store.md). - -`widgetValueStore` exposes `registerWidget`, `getWidget`, `setValue`, -`deleteWidget`, `getNodeWidgets`, and `clearGraph`, all `WidgetId`-native. There -is no shared `lastWidgetId` counter; identity comes from the composite key. - -Store scope is per workflow instance. Linked subgraph definitions can be reused -across instances, but mutable runtime state (widget values, execution state, -selection/transient view state) stays instance-scoped through `graphId` embedded -in each composite key. - -Subgraphs are not a separate store. Subgraph nesting is tracked in -`subgraphNavigationStore`. See -[Subgraph Boundaries](subgraph-boundaries-and-promotion.md) for the full model. - -**Risk:** Low. Stores are additive; integration happens in Phase 2. - ---- - -## Phase 2: Store Integration - -Connects the legacy class instances to the dedicated stores. Both old and new -code can read entity state; writes for not-yet-migrated concerns still go through -legacy classes. - -### 2a. Position reads through layoutStore - -`layoutStore` (`src/renderer/core/layout/store/layoutStore.ts`) already extracts -position data for nodes, links, and reroutes into Y.js CRDTs and is the source of -truth for layout. - -**Approach:** New code reads position via `layoutStore` queries (and -`useLayoutMutations(source)` for writes); legacy code continues to read `node.pos` -directly during the transition. No second copy of position data is introduced — -`layoutStore` stays authoritative. - -**Risk:** Medium. The legacy `node.pos` read path must stay consistent with -`layoutStore` during the transition. Watch for stale reads during render. - -### 2b. Consolidate widget callers onto widgetValueStore ✅ Largely shipped (PR 12617) - -`widgetValueStore` (`src/stores/widgetValueStore.ts`) holds widget state in -plain records keyed by `WidgetId` (`graphId:nodeId:name`) and is the source of -truth for widget values. PR 12617 reverted the earlier synthetic-numeric-ID -bridge approach. - -**Remaining work:** Consolidate the remaining widget callers onto -`widgetValueStore`. Reads use `getWidget(widgetId)` / `getNodeWidgets(graphId, -nodeId)`; writes use `setValue(widgetId, value)`; `parseWidgetId()` recovers the -`{ graphId, nodeId, name }` parts at boundaries. - -**Risk:** Low. The store is well-structured and `WidgetId`-native; identity comes -from the composite key with no separate lookup index. - -**Promoted-widget caveat:** ADR 0009 assigns promoted value widgets a -host-boundary identity (`host node locator + SubgraphInput.name`). Interior -source node/widget identity is preserved only as migration and diagnostic -metadata. - -### 2c. Node shell state ✅ Shipped - -Node shell state (`title`, `type`, `mode`, `flags`, colours, `shape`, -`resizable`, `showAdvanced`) lives in `nodeDataStore` as one plain `NodeState` -per node. **No copy is made.** `LGraphNode` constructs its `_state` and adopts -the store's reactive proxy at `LGraph.add`; the class fields are accessors over -that proxy, so class, store, and renderer read the same object. The -`incrementVersion()` re-sync hook this phase originally anticipated is -unnecessary — there is nothing to re-sync. - -Registration chokepoints are `LGraph.add` / `LGraph.remove`, with -identity-checked vacate (`toRaw` compare) so only the registered state can free -its key. Design record: [Node Data Store](node-data-store.md). - -**Risk:** taken. Shell-state fields moved from own enumerable data properties to -prototype accessors, so `Object.keys(node)` / `{ ...node }` no longer carry them, -and `type` is read-only. See node-data-store.md Decision 7 for the extension -migration map. - -### 2d. Renderer node lifecycle ✅ Shipped - -`useGraphNodeManager` is **deleted**. Its four responsibilities were resolved -rather than relocated: - -| Responsibility | Resolution | -| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| `VueNodeData` mirror + `node:property:changed` handlers | deleted; the renderer drills the `NodeState` proxy from `nodeDataStore` | -| `getNode()` / `nodeRefs` map | deleted; pinned state is read off the `NodeState` the renderer already holds, live-node lookups go to `graph.getNodeById` | -| `shallowReactive` graft onto `inputs` / `outputs` / `widgets` | deleted; see 2e | -| `layoutStore` seeding on add/remove | moved to `LGraph.add` / `LGraph.remove`, where the entity's geometry registers and unregisters with the entity itself | - -Two consequences worth recording: - -- The **`configuringGraph` deferral is gone.** `LGraph.add` registers the layout - entry with whatever geometry the node has; the `pos`/`size` setters already - write through to `layoutStore`, so `configure()` updates the entry as the real - values land. No `onAfterGraphConfigured` chaining, no `window.app` read. -- The **`onNodeAdded` replay loop is gone.** It re-fired `onNodeAdded` for every - pre-existing node on each graph switch, which leaked spurious node-added - notifications to unrelated subscribers (`useErrorClearingHooks` still carries - a guard written for exactly that). Geometry registers at attach and - unregisters at detach instead, so no bootstrap pass re-seeds a graph on entry. - -`useVueNodeLifecycle` is gone. `GraphCanvas` owns the Layout↔LiteGraph sync -lifecycle and no longer patches `onNodeAdded` — see 2g. - -### 2e. Slot reactivity ✅ Shipped - -Slot arrays and slot objects are reactive from construction, so the renderer -needs no reprojection pass: - -- `LGraphNode.inputs` / `.outputs` are accessors over `shallowReactive` arrays - (`_inputs` / `_outputs`, lazily created). Assignment replaces contents in - place, so the array identity the renderer subscribed to survives - `configure()`, `clone()`, and the several call sites that do - `node.inputs = node.inputs.filter(…)`. -- `NodeSlot`'s constructor returns `shallowReactive(this)`, making every - reference to a slot the tracked one. **Shallow is load-bearing:** nested values - (`boundingRect`, `_widget`, `pos`) stay raw, so identity comparisons like - `input._widget === widget` and the `WeakMap` slot-index cache in - `NodeInputSlot` keep working. A deep `reactive()` would break both. - -This deleted the `node:slot-label:changed` → `node.inputs = [...node.inputs]` -reprojection. The trigger itself stays (`useResolvedSelectedInputs` listens for -it); only the renderer's array-identity churn is gone. Renames now propagate -because `slot.label = …` is a tracked write. - -**Open item:** every slot property read in the canvas draw path now goes through -a proxy get trap. Benchmark against the Phase 4 "Render hot-path performance -gate" below before assuming this is free. - -### 2f. Slot arrays in nodeDataStore ✅ Shipped - -The renderer can ask what slots a node has without resolving the live -`LGraphNode`. `NodeState` carries the node's own `inputs` / `outputs` arrays -**by reference** — not a copy — so they register at the same `LGraph.add` / -`LGraph.remove` chokepoint as the rest of the shell state. This is the shape -`widgetValueStore` already uses for widget order: order data beside record data -in one store, rather than a new store per concern. - -Because the arrays are the node's, array order _is_ slot order and there is -nothing to keep in step. `NodeSlots.vue` no longer calls `getNodeByLocatorId` or -touches `app.rootGraph`; `LGraphNode.vue`'s `hasInputs` / `hasOutputs` / -`hasVideoInput` read the store too. - -**Why no keyed `SlotState` and no slot ids.** The draft above proposed -`getSlotKey(nodeId, index, isInput)`. That is not viable: slot index is a -property of the containing array, not of the slot, and ~25 sites permute it — -including `reorderSubgraphInputs` (`subgraphUtils.ts`), a _pure permutation_ with -no add or remove, reachable by dragging subgraph inputs in the right panel. An -index-keyed store must re-key on every one of them. `linkStore` shows the price: -it survives reorder only via six separate mechanisms, one of which -(`realignInputLinkSlots`, `linkDeduplication.ts`) is a load-time -corruption-repair pass added for the reorder case that was originally missed -(#3348). A link's key is derived from fields the link genuinely owns; a slot's -index is not slot state, so keying on it would be a mirror. - -Holding the array instead makes the question moot — no key, no ids, no re-keying, -no order sync. It rests on one Vue guarantee, which is pinned by test: `reactive()` -returns an already-`shallowReactive` value **unchanged**, so putting the node's -array in a reactive store record does not swap its identity or deep-wrap the -slots inside it. A _plain_ array in the same position would be wrapped — which is -why the arrays must stay `shallowReactive`. - -**Still deferred:** slot data is still class instances with behaviour -(`draw()`, `isValidTarget()`, `renderingColor()`). Splitting plain `SlotState` -rows out of `NodeInputSlot` / `NodeOutputSlot` — ADR 0008's "plain data -components" — is its own phase, and it needs a real consumer first: interaction -code (`useSlotLinkInteraction`) hands the live slot instance to litegraph's -`RenderLink`, and the badge system needs `node.constructor.nodeData.api_node` -and `isSubgraphNode()` alongside the slots, so slot rows alone would not unblock -it. - -### 2g. node:added / node:removed events ✅ Shipped - -`LGraphEventMap` had `node:before-removed` but no add-side counterpart, so every -consumer that needed to know about a node add wrapped the single -`graph.onNodeAdded` callback slot, saving and restoring the previous value. -**Four** did so concurrently: the renderer's empty-graph bootstrap, the -error-clearing hooks, the minimap, and node-added telemetry. Whichever restored -first put back the _pre-its-own-install_ value and silently discarded the others -— order-dependent, per graph switch. - -`LGraph.add` now dispatches `node:added` (after the node is attached and -registered) and `LGraph.remove` dispatches `node:removed` (after detach, so -`node.graph` is already null and execution ids must be derived from the -dispatching graph plus `node.id`). All four consumers are plain -`addEventListener` subscribers; none touches the callback slot. `onNodeAdded` / -`onNodeRemoved` remain for extension compatibility. - -`useNodeReplacement` bypasses `graph.add` by design (it swaps a node in place, -preserving the id), so `replaceWithMapping` announces the add itself. - -Prefer the events for anything new. The callback slots cannot be shared. - -### Store sunset criteria (applies to every Phase 2 concern) - -A legacy path can move from "transitional" to "removal candidate" only when: - -- All production reads for that concern flow through store accessors. -- All production writes for that concern flow through store actions. -- Serialization parity tests show no diff between legacy and store-driven paths. -- Extension compatibility tests pass without legacy-only fallback paths. - -These criteria prevent the dual path from becoming permanent by default. - -### Dual-path duration and maintenance controls - -To contain dual-path maintenance cost during Phases 2-4: - -- Every concern has a named owner and target sunset release. -- Every PR touching store-covered data paths must include parity tests for both - legacy and store-driven execution. -- Legacy fallback usage is instrumented in integration/e2e and reviewed every - milestone; upward trends block new dual-path expansion. -- Any concern that misses its target sunset release requires an explicit risk - review and revised removal plan. - ---- - -## Phase 3: Systems - -Introduce system functions that operate on store data. Systems coexist with -legacy methods — they don't replace them yet. - -### 3a. SerializationSystem (read-only) - -A function `serializeFromStores(): SerializedGraph` that produces workflow JSON -by querying the dedicated stores. Run alongside the existing `LGraph.serialize()` -in tests to verify equivalence. - -**Why first:** Serialization is read-only and has a clear correctness check -(output must match existing serialization). It exercises every store and proves -the stores contain sufficient data. - -**Risk:** Low. Runs in parallel with existing code; does not replace it. - -### 3b. VersionSystem - -Move change tracking behind a system that observes store mutations and -auto-increments the version counter, replacing scattered explicit increment -calls. - -**Dependency:** Requires Phase 2 store integration (otherwise the system doesn't -see changes). - -**Risk:** Medium. Must not miss any change that the scattered `_version++` -historically caught. - -### 3c. ConnectivitySystem (queries only) - -A system that answers connectivity queries by reading connectivity, slot, and -link-endpoint records from the relevant stores: - -- "What nodes are connected to this node's inputs?" -- "What links pass through this reroute?" -- "What is the execution order?" - -Does not perform mutations yet — just queries. Validates that store connectivity -data is complete and consistent with the class-based graph. - -> **Status (2026-07-05):** The reroute-membership query shipped as `linkStore` + -> `rerouteStore` (PRs 13436, 13449): "what links pass through this reroute" is -> derived per root graph by a cached reverse index over the links' `parentId` -> chains, and input-side connectivity is one lookup via -> `linkStore.isInputSlotConnected()` / `getInputSlotLink()`. -> -> **Status (2026-07-17):** Output-side queries shipped and the `output.links` -> mirror is deleted (PR 13479): `linkStore.isOutputSlotConnected()` / -> `getOutputSlotLinks()`, litegraph internals reading through -> `node/slotLinks.ts` (see -> [output slot connectivity](output-slot-connectivity.md)). Remaining: the -> `input.link` slot mirror and execution order. -> -> **Status (2026-07-18):** The `input.link` mirror is deleted (PR 13498) by the -> same recipe: a deprecated warning getter on `NodeInputSlot`, readers going -> through the `slotLinks` input helpers, and serialization deriving -> `inputs[].link` from the store. Remaining: execution order. - -**Risk:** Low. Read-only system with equivalence tests. - ---- - -## Phase 4: Write Path Migration - -Systems begin owning mutations. Legacy class methods delegate to stores and -systems. This is the highest-risk phase. - -### 4a. Position writes through layoutStore ✅ Shipped - -Planned as adding a compatibility shim; was mostly about deleting them. Every -entity now has exactly one write path, and the workarounds that existed because -writes bypassed it are gone. - -**One write path per entity.** Whole-value assignment through `pos` / `size` is -the normal path, and the setters commit to the store. `createGeometryView` -commits indexed writes too. Most in-repo indexed writes now use whole-value -assignments. The migration found three forms: - -| Form | Example | Where it hid | -| ------------------ | ------------------------------------ | -------------------- | -| Direct | `node.pos[0] += dx` | greppable | -| Helper-routed | `snapPoint(this.pos, snapTo)` | mutates its argument | -| Destructured local | `const { size } = this; size[0] = w` | not a `this.` write | - -The helper-routed form was the costly one: `LGraphNode.snapToGrid` never -reached the store, and `LGraph.configure` carried a local workaround -(`node.pos = [node.pos[0], node.pos[1]]`) for that one call site while three -others had none. - -**Groups and reroutes joined the store.** `GroupLayout` is id/position/size -with no zIndex or spatial index. Groups draw beneath nodes in insertion order, -and nothing queries them positionally. Geometry is a single -`setGroupBounds` operation, because `pos` and `size` are two views onto one -`Rectangle` and must never be stored apart. Reroutes went further: `posInternal` -is deleted, `pos` reads the stored point, and a reroute registers its own -geometry in its constructor, which removed two seeding sites. - -**`LGraphNode` no longer runs a continuous store-to-class sync.** When code -reads geometry, the node checks the global geometry version and copies the -stored rectangle into `_posSize` if its cache is stale. Serialization and legacy -rendering read current values through `this.pos` and `this.size` without walking -every node after each layout change. - -While Vue-node rendering is active, `notifyLayoutChanges` dirties the canvas for -node layout changes. For non-canvas `resizeNode` and `batchUpdateBounds` -operations, it also calls `onResize`; canvas resizes already own that callback -through `LGraphNode.setSize()`. It does not copy geometry into nodes. - -**Whole-value setters re-read after committing.** `_positionUpdated` and -`_sizeUpdated` write only their own half of `_posSize`, so stamping -`_geometryVersion` to the post-commit store version would mark the untouched -half fresh while it was still stale. The next commit of that half would then -publish the stale value to the store and to CRDT peers. Both invalidate and -refresh instead, which also picks up any value the store clamped or merged. - -**Deferred follow-up: extract geometry projection ownership.** Land this after -the node geometry facade and its CRDT-safety follow-up (PRs 14133 and 14480) so -the ownership and compensation rules are stable before moving them. Preserve -behavior while making one focused projection module responsible for the legacy -geometry cache: - -1. Move `_geometryVersion`, `_layoutRegistered`, and `refreshGeometry()` out of - `LGraphNode`. Keep ephemeral projection state private to the module, keyed by - node identity; do not add another entity store for compatibility-only state. -2. Make layout registration and removal call that module instead of coordinating - node flags and backing buffers directly. `LGraphNode.pos` and `.size` remain - compatibility accessors, but delegate synchronization rather than owning its - lifecycle. -3. Once the lifecycle has one owner, replace the store-wide geometry version - check with node-scoped invalidation. A geometry change should make only the - affected nodes refresh; unrelated node, group, and reroute operations should - not force every rendered node through a Yjs lookup. - -Completion requires no projection lifecycle fields or methods on `LGraphNode`, -no registration code that mutates such fields, unchanged extension-facing -`pos` / `size` behavior, and coverage for store-originated updates, indexed -writes, removal/re-addition, and CRDT compensation. - -**Open decisions:** - -1. The geometry views. The hand-written `size` Proxy is gone, replaced by - `createGeometryView` over `pos` and `size` on `LGraphNode` plus `pos`, - `size` and `bounding` on `LGraphGroup`. The views still handle the indexed - position write in `distributeNodes()` and extension writes such as - `node.size[1] = h`. Retiring them requires whole-value assignment in - `distributeNodes()` and a stable resize API for extensions. -2. Subgraph IO nodes have conforming write paths but no store entry. A keyed - entry needs subgraph scoping (`SUBGRAPH_INPUT_ID` is a constant shared by - every subgraph) and `Subgraph.id` is reassigned by `clear()`, so the key can - go stale. The link store rejected the same pattern. Nothing needs keyed - access, since callers reach them as `subgraph.inputNode`. -3. Two hit-testing systems: litegraph against class geometry, `layoutStore` - against a spatial index. Node bounds are duplicated between `_boundingRect` - and `NodeLayout.bounds`. - -### 4b. ConnectivitySystem mutations - -`connect()`, `disconnect()`, `removeNode()` operations implemented as system -functions over the connectivity stores. Legacy `LGraphNode.connect()` etc. -delegate to the system. - -**Extension API concern:** The current system fires callbacks at each step: - -- `onConnectInput()` / `onConnectOutput()` — can reject connections -- `onConnectionsChange()` — notifies after connection change -- `onRemoved()` — notifies after node removal - -These callbacks are the **extension API contract**. The ConnectivitySystem -must fire them at the same points in the operation, or extensions break. - -**Recommended approach:** The system emits lifecycle events that the bridge -layer translates into legacy callbacks. This preserves the contract without -the system knowing about the callback API. - -**Phase 4 callback contract (locked):** - -- `onConnectOutput()` and `onConnectInput()` run before any store mutation. -- If either callback rejects, abort with no store writes, no version bump, - and no lifecycle events. -- `onConnectionsChange()` fires synchronously after commit, preserving current - source-then-target ordering. -- Bridge lifecycle events remain internal. Legacy callbacks stay the public - compatibility API during Phase 4. - -> **Status (2026-07-05):** Link and reroute store registration now funnels -> through canonical `LGraph` mutation chokepoints: `_addLink`/`_removeLink` and -> `_addReroute`/`_removeReroute` pair every map mutation with store -> (un)registration, and `clear()` / subgraph-definition GC unregister whole -> graphs. The callback contract above remains (`output.links` was deleted in -> PR 13479, `input.link` in PR 13498). - -**Risk:** High. Extensions depend on callback ordering and timing. Must be -validated against real-world extensions. - -### 4c. Widget write path ✅ Largely shipped (PR 12617) - -`widgetValueStore.setValue()` is already the widget write path and the source of -truth for widget values. Remaining work routes the last legacy widget writers -through `setValue()` rather than mutating widget instances directly. - -**Risk:** Medium. The store is well-abstracted and `WidgetId`-native. The main -change is migrating the remaining direct-mutation call sites onto `setValue()`. - -### 4d. Layout write path and render decoupling - -Remove layout side effects from render incrementally by node family. - -**Approach:** - -1. Inventory `drawNode()` call paths that still trigger `arrange()`. -2. For one node family at a time, run `LayoutSystem` in update phase and mark - entities as layout-clean before render. -3. Keep a temporary compatibility fallback that runs legacy layout only for - non-migrated families. -4. Delete fallback once parity tests and frame-time budgets are met. - -**Risk:** High. Mixed-mode operation must avoid stale layout reads. Requires -family-level rollout and targeted regression tests. - -### Render hot-path performance gate - -Before enabling ECS render reads as default for any migrated family: - -- Benchmark representative workflows (200-node and 500-node minimum). -- Compare legacy vs ECS p95 frame time and mean draw cost. -- Block rollout on statistically significant regression beyond agreed budget - (default budget: 5% p95 frame-time regression ceiling). -- Capture profiler traces proving the dominant cost is not repeated store - accessor lookups. - -### Phase 3 -> 4 gate (required) - -Phase 4 starts only when all of the following are true: - -- A store/command-executor transaction wrapper exists and is used by connectivity - and widget write paths in integration tests. -- Undo batching parity is proven: one logical user action yields one undo - checkpoint in both legacy and store-driven paths. -- Callback timing and rejection semantics from Phase 4b are covered by - integration tests. -- A representative extension suite passes, including `rgthree-comfy`. -- Write-path re-entrancy tests prove there is no store <-> legacy feedback - loop. -- Layout migration for any enabled node family passes read-only render checks - (no `arrange()` writes during draw). -- Render hot-path benchmark gate passes for every family moving to store-first - reads. - ---- - -## Phase 5: Legacy Removal - -Remove bridge layers and deprecated class properties. This phase happens -per-component, not all at once. - -### 5a. Remove Position compatibility shim - -Once all position reads and writes go through `layoutStore`, remove the -compatibility shim and the `pos`/`size` properties from `LGraphNode`, `Reroute`, -`LGraphGroup`. - -### 5b. Remove widget class hierarchy - -Once all widget behavior is in systems, the 23+ widget subclasses can be -replaced with component data + system functions. `BaseWidget`, `NumberWidget`, -`ComboWidget`, etc. become configuration data rather than class instances. - -### 5c. Dissolve god objects - -`LGraphNode`, `LLink`, `LGraph` become thin shells — their only role is holding -the composite ID and delegating to the stores. Eventually, they can be removed -entirely, replaced by composite IDs + store queries. - -**Risk:** Very High. This is the irreversible step. Must be done only after -thorough validation that all consumers (including extensions) work with the -ECS path. - -### Phase 4 -> 5 exit criteria (required) - -Legacy removal starts only when all of the following are true: - -- The concern being removed has no remaining direct reads or writes outside - store/system APIs. -- Serialization equivalence tests pass continuously for one release cycle. -- A representative extension compatibility matrix is green, including - `rgthree-comfy`. -- Bridge instrumentation shows zero fallback-path usage in integration and e2e - suites. -- A rollback plan exists for each removal PR until the release is cut. -- ECS write path has run as default behind a kill switch for at least one full - release cycle. -- No unresolved P0/P1 extension regressions are attributed to ECS migration in - that cycle. - -### Phase 5 trigger packet (required before first legacy-removal PR) - -The team prepares a single go/no-go packet containing: - -- Phase 4 -> 5 criteria checklist with links to evidence. -- Extension compatibility matrix results. -- Bridge fallback usage report (must be zero for the target concern). -- Performance gate report for ECS render/read paths. -- Rollback owner, rollback steps, and release coordination sign-off. - ---- - -## Open Questions - -### CRDT / ECS coexistence - -`layoutStore` uses Y.js CRDTs for collaboration-ready position data -(per [ADR 0003](../adr/0003-crdt-based-layout-system.md)). The other dedicated -stores hold plain reactive data. These must coexist. - -`layoutStore` stays authoritative for layout (Phase 2a), so position data has a -single CRDT-backed home. Whether other stores need CRDT backing is open and -requires a separate ADR. - -**Questions to resolve:** - -- Should non-position stores also be CRDT-backed for collaboration? -- How does conflict resolution work when two users modify the same record? - -Settled: the stores do not need an operation log for undo/redo. `layoutStore` -carried one and nothing ever read it — undo/redo is snapshot-based through -`changeTracker` — so it was deleted. - -### Extension API preservation - -The current system exposes lifecycle callbacks on entity classes: - -| Callback | Class | Purpose | -| --------------------- | ------------ | ----------------------------------- | -| `onConnectInput` | `LGraphNode` | Validate/reject incoming connection | -| `onConnectOutput` | `LGraphNode` | Validate/reject outgoing connection | -| `onConnectionsChange` | `LGraphNode` | React to topology change | -| `onRemoved` | `LGraphNode` | Cleanup on deletion | -| `onAdded` | `LGraphNode` | Setup on graph insertion | -| `onConfigure` | `LGraphNode` | Post-deserialization hook | -| `onWidgetChanged` | `LGraphNode` | React to widget value change | - -Extensions register these callbacks to customize node behavior. The ECS -migration must preserve this contract or provide a documented migration path -for extension authors. - -**Recommended approach:** Define an `EntityLifecycleEvent` system that emits -typed events at the same points where callbacks currently fire. The bridge -layer translates events into legacy callbacks. Extensions can gradually adopt -event listeners instead of callbacks. - -**Phase 4 decisions:** - -- Rejection callbacks act as pre-commit guards (reject before store mutation). -- Callback dispatch remains synchronous during the bridge period. -- Callback order remains: output validation -> input validation -> commit -> - output change notification -> input change notification. - -### Removed layoutStore queries (custom-node audit pending) - -These `layoutStore` methods were deleted once their last in-repo caller went -away. They were never advertised as extension API, but `layoutStore` is -reachable from custom nodes, so Hyrum's law applies: someone may depend on -them. - -| Removed method | Was | -| ---------------------- | ----------------------------------------------- | -| `getAllNodes()` | Reactive map of every node layout, unscoped | -| `getNodesInBounds()` | Reactive node ids intersecting bounds | -| `queryNodeAtPoint()` | Top-zIndex node containing a point | -| `queryNodesInBounds()` | Node ids intersecting bounds, via spatial index | -| `queryItemsInBounds()` | Nodes, links, slots and reroutes in bounds | - -**Action required:** grep the custom-node ecosystem for these names before the -next release. If any have external dependents, restore them as deprecated -shims per [Extension API preservation](#extension-api-preservation) rather -than reintroducing the call sites. - -Note that the node-facing ones were also _wrong_ by the time they were -removed: node layout was keyed by bare `NodeId` with no root-graph scope, and -registration now happens for every graph including unopened subgraph -definitions, so any of these would have returned nodes the user cannot see. A -restored shim must take a `rootGraphId`, which node layout is now keyed by. - -### Removed CRDT sync seam (prior art for multiplayer) - -`layoutStore` carried three methods reserved for a networked future that has -not arrived: - -| Removed method | Was | -| -------------------- | --------------------------------------------- | -| `getYDoc()` | The raw `Y.Doc`, for a sync provider | -| `applyUpdate()` | `Y.applyUpdate` — merge a remote peer's ops | -| `getStateAsUpdate()` | `Y.encodeStateAsUpdate` — full-state snapshot | - -None had a caller. Removed as YAGNI, not as a change of direction: the layout -store is still a Yjs document and -[ADR 0003](../adr/0003-crdt-based-layout-system.md) still holds. Reinstating -them is a few lines against `this.ydoc`. - -Two things worth carrying forward when multiplayer is actually built, both -learned by deleting this: - -- `applyUpdate` bypassed `applyOperation`, so nothing that derives state from - the operation stream would have seen a remote change. `highestZIndex` (see - `allocateZIndex`) is exactly such a counter — a remote peer's node with a - higher `zIndex` would not have raised it, and the next allocation would - collide. Any real sync path must rebuild that kind of derived state from the - document, or observe `ynodes` rather than the operation stream. -- All three entity types are now keyed by `makeScopedLayoutKey(rootGraphId, id)`, - so two peers in different workflows cannot collide. They still share a bucket - across subgraphs of one root graph, which is safe only because node ids are - unique root-wide — `Subgraph` shares the root graph's `state`, so one counter - issues every id. A sync path that merges documents from peers holding - different workflows must not assume that invariant survives the merge. - -### Extension Migration Examples (old -> new) - -The bridge keeps legacy callbacks working, but extension authors can migrate -incrementally to ECS-native patterns. - -#### 1) Widget lookup by name - -```ts -// Legacy pattern -const seedWidget = node.widgets?.find((w) => w.name === 'seed') -seedWidget?.setValue(42) - -// Store pattern (composite WidgetId, no reverse-lookup index needed) -const seedWidgetId = widgetValueStore - .getNodeWidgets(graphId, nodeId) - .find((id) => parseWidgetId(id).name === 'seed') -if (seedWidgetId) { - widgetValueStore.setValue(seedWidgetId, 42) -} -``` - -#### 2) `onConnectionsChange` callback - -```ts -// Legacy pattern -nodeType.prototype.onConnectionsChange = function ( - side, - slot, - connected, - linkInfo -) { - updateExtensionState(this.id, side, slot, connected, linkInfo) -} - -// ECS pattern -lifecycleEvents.on('connection.changed', (event) => { - if (event.nodeId !== nodeId) return - updateExtensionState( - event.nodeId, - event.side, - event.slotIndex, - event.connected, - event.linkInfo - ) -}) -``` - -#### 3) `onRemoved` callback - -```ts -// Legacy pattern -nodeType.prototype.onRemoved = function () { - cleanupExtensionResources(this.id) -} - -// ECS pattern -lifecycleEvents.on('entity.removed', (event) => { - if (event.kind !== 'node' || event.entityId !== nodeId) return - cleanupExtensionResources(event.entityId) -}) -``` - -#### 4) `graph._version++` - -```ts -// Legacy pattern (do not add new usages) -graph._version++ - -// Transitional pattern (Phase 0a) -graph.incrementVersion() - -// Store-native pattern: mutate through the command/system API. -// VersionSystem bumps once at transaction commit. -executor.run({ - type: 'SetWidgetValue', - execute() { - widgetValueStore.setValue(widgetId, 42) - } -}) -``` - -**Question to resolve after compatibility parity:** - -- Should ECS-native lifecycle events stay synchronous after bridge removal, or - can they become asynchronous once legacy callback compatibility is dropped? - -### Atomicity and transactions - -The lifecycle scenarios claim operations are "atomic." This requires a -store/command-executor transaction — the ability to batch multiple store writes -and commit or rollback as a unit. `layoutStore` already wraps its mutations in -Y.js transactions; the command executor extends the same discipline across -stores. - -**Current state:** `beforeChange()` / `afterChange()` provide undo/redo -checkpoints but not true transactions. The graph can be in an inconsistent -state between these calls. Link topology mutations are centralized in -`linkStore`: endpoint updates validate their batch before mutation, and link -replacement validates ownership, identity, the expected incumbent, ID, and -target availability before changing its indexes. These operations are atomic -only within `linkStore`; they do not provide rollback across callbacks, layout, -reroutes, graph maps, versioning, or other stores. - -Centralizing each mutation point removes duplicated caller checks, reduces the -number of paths that can violate store invariants, and provides one place for -atomic validation and rollback as the migration continues. Command-executor -transactions should wrap these store mutation points rather than adding -caller-specific compensation. - -Input replacement commits new topology before old-link disconnect callbacks, so -callback queries see the replacement rather than an intermediate empty slot. - -**Rejected transitional options:** - -| Option | Why it was rejected | -| ---------------------------------------- | ---------------------------------------------------------------------------------- | -| Preflight in each graph caller | Duplicates store invariants and leaves a check-to-mutation race. | -| Disconnect, register, then restore | Callbacks and multi-store cleanup make the removed state unsafe to reconstruct. | -| Add caller-specific failure compensation | Spreads rollback policy across paths instead of establishing one transaction seam. | -| Normalize only in `createSubgraph` | Misses workflow load, paste, and conversion paths and can mutate caller input. | -| Add pseudo-live `LinkMap` iterators | Does not preserve native iterator semantics; cached snapshots preserve it instead. | - -**Phase 4 baseline semantics:** - -- Mutating systems run inside a single command-executor transaction. -- The bridge maps one executor transaction to one `beforeChange()` / - `afterChange()` bracket. -- Operations with multiple store writes (for example `connect()` touching - slots, links, and node metadata) still commit as one transaction and therefore - one undo entry. -- Failed transactions do not publish partial writes, lifecycle events, or - version increments. - -**Questions to resolve:** - -- How should the command-executor transaction interact with the Y.js - transactions that `layoutStore` already runs? -- Is eventual consistency acceptable for derived data updates between - transactions, or must post-transaction state always be immediately - consistent? - -### Keying strategy unification - -The dedicated stores use per-concern keying strategies: - -| Store | Key Format | -| ------------------------- | ------------------------------------------------------------------------------- | -| `widgetValueStore` | `WidgetId` (`graphId:nodeId:name`) | -| `domWidgetStore` | Widget UUID | -| `layoutStore` | Raw node/link IDs; `${rootGraphId}:${localId}` for group/reroute geometry | -| `nodeOutputStore` | `"${subgraphId}:${nodeId}"` | -| `subgraphNavigationStore` | subgraphId or `'root'` | -| `linkStore` | `` `${owningGraphId}:${nodeId}:${slot}` `` query indexes in root-scoped buckets | -| `rerouteStore` | `RerouteId`, root-graph-scoped buckets | -| `nodeDataStore` | `NodeState` identity (`Set`), root-graph-scoped buckets | - -ADR 0009 refines the promoted-widget target: promoted value widgets should use -host boundary identity (`host node locator + SubgraphInput.name`), not interior -source node/widget identity. - -Composite string keys won over synthetic numeric IDs. A widget is identified by -its relationship to a graph and node, and the `graphId:nodeId:name` key carries -that relationship directly. PR 12617 kept the composite string instead of an -opaque number, so no reverse lookup index is required — `parseWidgetId()` -recovers the parts on demand. - -**Resolution:** Self-documenting composite keys, parsed at boundaries. Each store -keeps the key format that matches its concern; there is no forced unification -under a single ID space. - -### Deferred topology follow-ups - -The scoped-topology migration now has the following boundaries and leaves the -remaining decisions for later work. - -**Implemented boundaries:** - -- `createSubgraphs` and `createSubgraph` share one immutable normalization - boundary used by workflow loading, direct creation, clipboard/paste, and - conversion. It creates shells first and fills leaves first without changing - caller input. Malformed same-owner duplicate IDs are deterministic: - first-wins and later duplicates are dropped because references cannot - disambiguate them. -- Graph clear uses one exact-entity teardown traversal. Lifecycle callbacks run - first while topology remains observable, followed by link, reroute, node, and - layout detachment. Only the root clear defensively clears whole store buckets. -- Root and subgraph serialization consume one owner-local topology partition. - It preserves the regular and floating wire categories in workflow output. - -**Still deferred:** - -- Keep entity identity flat and root-wide. Replacing it with owner-nested - identity would reverse the current architecture rather than simplify it. -- Keep `idsByOwner` for owner-local iteration and teardown; removing it would - replace indexed access with root-bucket scans. -- Keep cached reroute membership; recomputing it would add graph walks to read - paths. -- Do not restore the legacy `_links` mirror or broaden that compatibility - surface. -- Keep registration failure as an explicit return value rather than adding - thrown errors. -- `LinkMap` caches owner-local snapshots, but every topology mutation currently - invalidates all views, including endpoint-only updates. Profile Pinia revision - and cache-rebuild cost before considering owner-scoped revisions; do not - replace the cache with pseudo-live iterators or an `_links` mirror. -- Graph teardown now finishes exact detachment, defensive root-bucket clearing, - graph reset, and canvas clearing after a lifecycle callback fails, then - propagates that same failure. Lifecycle callbacks remain fail-fast, so later - callbacks do not run. This is the current chosen policy: it preserves callback - ordering and topology observation while preventing partially cleared graphs. - - | Future direction | Failure handling | Tradeoff | - | ------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- | - | **1. Current: finish teardown, then propagate first failure** | Fail fast; later callbacks do not run | Preserves current lifecycle semantics, but skips later notifications | - | 2. Run all callbacks, then report | Propagate the first failure or an aggregate | Completes notifications, but changes fail-fast behavior | - | 3. Finish and report without propagating | Swallow and report callback failures | Keeps clear callers running, but hides extension failures from them | - | 4. Detach first, then notify from a queue | Run callbacks after teardown | Simplifies teardown isolation, but breaks compatibility for callbacks that observe topology | - -- Keep the browser hydration test as the workflow-level composition check. -- Investigate separately whether link geometry in `layoutStore`, still keyed by - bare `LinkId`, can collide across simultaneously live root graphs. -- Document that root-wide identity lookup uses `rootGraphId`, while owner-local - iteration and slot queries use `graphScopeOf()` with the directly owning - graph. Callers should not construct root/owner pairs manually. -- Defer a persistent root-wide group ID index until profiling shows it is - warranted. `LGraph.add()` currently scans root and subgraph groups for each - group insertion, which can make loading G groups take quadratic time. A - `Set` per insertion has the same asymptotic cost, while a persistent index - duplicates lifecycle state. Defer evaluation of its real workflow load-speed - impact. Measure representative large workflow load, deserialization, paste, - and unpack paths first. If the scan has material impact, optimize the - insertion path while preserving the existing root-shared high-water allocator - and import-time collision repair. -- Defer floating reroute/link multi-store rollback. Normal root-shared link ID - allocation avoids collisions for minted IDs, while registration can reject - externally supplied runtime IDs that collide. Future transaction work should - wrap the centralized store mutation rather than add compensation here. -- Treat floating as one-ended link state, not a separate entity category. The - runtime topology collection is unified; `graph.links` and - `graph.floatingLinks` remain filtered compatibility views. Keep the separate - serialized `floatingLinks` field until a versioned workflow migration has - enough value to justify its extension and fixture impact. - ---- - -## Dependency Graph - -``` -Phase 0a (incrementVersion) ──── ✅ shipped (one stray cleanup remaining) -Phase 0b (ID type aliases) ───┐ -Phase 0c (doc fixes) ─────────┤── no dependencies between these - -Phase 1a (branded WidgetId) ── ✅ shipped (PR 12617) -Phase 1b (store state shapes) ─┐── depends on 1a -Phase 1c (dedicated stores) ──┘── widgetValueStore + 7 others shipped - (PR 12617; linkStore PR 13436; rerouteStore PR 13449) - -Phase 2a (Position via layoutStore) ─┐── depends on 1c -Phase 2b (Widget consolidation) ────┤── ✅ largely shipped; depends on 1a, 1c -Phase 2c (Node metadata stores) ────┘── depends on 1c - -Phase 3a (SerializationSystem) ─── depends on 2a, 2b, 2c -Phase 3b (VersionSystem) ──────── depends on 2c (store-level change tracking) -Phase 3c (ConnectivitySystem) ──── depends on 2c - -Phase 3->4 gate checklist ──────── depends on 3a, 3b, 3c - -Phase 4a (Position writes) ────── depends on 2a, 3b - Geometry projection ownership ── after PRs 14133, 14480; depends on 4a -Phase 4b (Connectivity mutations) ─ depends on 3c, 3->4 gate -Phase 4c (Widget writes) ─────── ✅ largely shipped; depends on 2b -Phase 4d (Layout decoupling) ─── depends on 2a, 3->4 gate - -Phase 4->5 exit criteria ──────── depends on all of Phase 4 - -Phase 5 (legacy removal) ─────── depends on 4->5 exit criteria -``` - -The dedicated stores (1c) are the hub: Phase 2 routes legacy data into them, -Phase 3 systems read from them, Phase 4 routes writes through them. - -## Risk Summary - -| Phase | Risk | Reversibility | Extension Impact | -| --------------------- | ---------- | ----------------------- | --------------------------- | -| 0 (Foundation) | None | Fully reversible | None | -| 1 (Types/Stores) | Low | New files, deletable | None | -| 2 (Store integration) | Low-Medium | Additive store reads | None | -| 3 (Systems) | Low-Medium | Systems run in parallel | None | -| 4 (Write path) | High | Two-way sync is fragile | Callbacks must be preserved | -| 5 (Legacy removal) | Very High | Irreversible | Extensions must migrate | - -The plan is designed so that Phases 0-3 can ship without any risk to -extensions or existing behavior. Phase 4 is where the real migration begins, -and Phase 5 is the point of no return. diff --git a/docs/architecture/ecs-target-architecture.md b/docs/architecture/ecs-target-architecture.md index d87c1479b0f..dbe3ade0544 100644 --- a/docs/architecture/ecs-target-architecture.md +++ b/docs/architecture/ecs-target-architecture.md @@ -604,4 +604,4 @@ behavior layer"] This diagram is intentionally high level. The operational Phase 4 -> 5 entry criteria (compatibility matrix, bridge fallback usage, rollback requirements) -are defined in [ecs-migration-plan.md](ecs-migration-plan.md). +are defined in [ecs-migration-plan.md](ecs/ecs-migration-plan.md). diff --git a/docs/architecture/ecs/ecs-decision-traceability.md b/docs/architecture/ecs/ecs-decision-traceability.md new file mode 100644 index 00000000000..b71f3b8383b --- /dev/null +++ b/docs/architecture/ecs/ecs-decision-traceability.md @@ -0,0 +1,76 @@ +# ECS decision traceability + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This audit maps the implementation on `feature/ecs-migration` to the principles in +[ADR 0003](../../adr/0003-crdt-based-layout-system.md) and +[ADR 0008](../../adr/0008-entity-component-system.md). The ADRs remain the +decision records; this audit neither replaces nor amends them. + +Status meanings: + +- `Implemented`: the observed implementation satisfies the principle for + its stated scope. +- `Partial`: an authoritative path exists, but legacy or uncovered concerns + remain. +- `Remaining`: the decision is not materially implemented. +- `Superseded`: a documented amendment replaced an ADR detail. + +For ownership by state concern, see the +[ECS State Authority Audit](ecs-state-authority-audit.md). Target descriptions +remain in [ECS Target Architecture](../ecs-target-architecture.md), and +sequencing is recorded in [ECS Migration Plan](ecs-migration-plan.md). + +## Traceability matrix + +| Principle | Status | Implementation | Verification evidence | Concrete remaining work | +| --------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Dedicated stores rather than a single World | **Implemented; original World superseded** | `useNodeDataStore`, `useWidgetValueStore`, `useLinkStore`, `useRerouteStore`, `layoutStore`, `useDomWidgetStore`, `useNodeOutputStore`, `useSubgraphNavigationStore`, and `usePreviewExposureStore` | Store tests cover registration, identity collisions, graph isolation, queries, and cleanup; ADR 0008's 2026-06-19 amendment explicitly replaces `world/*` | Continue moving the concerns still owned by LiteGraph classes; do not recreate a universal registry | +| Plain-data components | **Partial** | `NodeState`, `LinkTopology`, `RerouteChain`, widget state, layout records, and `BadgeData` are data records; stores and systems own their behavior | `nodeDataStore`, `linkStore`, and `rerouteStore` register records and return reactive proxies; `computeBadges` accepts and returns plain data | Extract slot data and remaining link visual/runtime state; `NodeInputSlot`, `NodeOutputSlot`, `LLink`, and widgets still contain behavior | +| Behavior in systems | **Partial** | `badgeSystem.computeBadges` is pure; `useLayoutMutations`, `graphLayoutAttachment`, `slotLinks`, and store actions isolate some behavior | `badgeSystem.test.ts`, layout operation tests, link/reroute store tests, and slot-link tests exercise behavior without a renderer | Move serialization, execution, connectivity orchestration, and render orchestration out of `LGraphNode`, `LGraph`, and `LGraphCanvas`; the ADR 0008 named systems are not generally present | +| Command-driven mutation | **Partial** | `LayoutOperation`, `layoutStore.applyOperation` / `applyOperations`, `useLayoutMutations`, and geometry attachment functions route layout writes through explicit operations | `layoutStore.test.ts` and `layoutMutations.test.ts` verify operation handling and batches; all Yjs layout mutations occur in store transactions | Define serializable command boundaries for node data, links, reroutes, widgets, slots, and graph lifecycle; their current store/class mutators are imperative and are not replayable commands | +| Graph and workflow scope | **Implemented for migrated stores** | `GraphScope`, `RootGraphId`, `OwningGraphId`, `graphScopeOf`; root buckets plus owner indexes in node/link/reroute stores; scoped layout keys; graph-prefixed `WidgetId` | Store tests cover root isolation, owner-local queries, duplicate IDs, and subgraph cases; browser coverage includes subgraph serialization and link identity collisions | Normalize older stores whose scope/key conventions differ; keep mutable state instance-scoped if linked subgraph definitions become shared | +| Entity lifecycle follows graph lifecycle | **Implemented for migrated concerns** | `LGraph.add` / `remove` register and unregister node, topology, reroute, and geometry state; `clearOwner`, `clearGraph`, `attach*Layout`, `detach*Layout`, and `detachGraphLayouts` perform teardown | Identity-checked deletion tests prevent one instance vacating another's key; graph clear and replacement tests cover teardown and transfer | Remove lifecycle ownership from `LGraph` only when a replacement coordinator exists; audit transient DOM widgets and compatibility registries for the same owner-scoped teardown guarantees | +| God-object reduction | **Partial** | Node shell, geometry, topology, reroute chains, widget values/order, and badge derivation have moved behind stores or systems | `NodeState` proxy drilling removed renderer mirrors; slot arrays are reactive by construction; topology reads use `slotLinks` | `LGraphNode`, `LGraph`, and `LGraphCanvas` still coordinate slots, widgets, mutation, serialization, execution, drawing, and input; extract only behind real consumers and parity tests | +| Extension behavior and serialization preserved during migration | **Partial** | Legacy class accessors adopt store proxies; `input.link` and `output.links` remain deprecated derived reads; class mutation APIs remain compatibility entry points; existing workflow format remains in use | LiteGraph serialization/configuration, extension, widget, clipboard, replacement, and browser tests exercise old surfaces; deprecation tests cover slot mirrors | Publish and complete migrations for direct slot writes and node property enumeration; preserve callbacks and old workflow loading while removing mirrors; no proof covers the entire custom-node ecosystem | +| CRDT-backed centralized layout | **Implemented for persistent entity geometry; partial overall** | Yjs owns node, group, and reroute geometry in `LayoutStoreImpl`; scoped keys, observers, geometry views, and `LayoutOperation` provide renderer-independent updates | `layoutStore.test.ts`, geometry-view tests, layout mutation tests, and Vue-node layout browser tests cover reads, writes, synchronization, and subgraphs | Link paths, slot bounds, and other hit-test geometry remain transient plain maps; integrate collaboration through the separate multiplayer contract rather than adding unused layout-store transport; undo/redo remains snapshot-based | + +## Observed boundaries + +- "Single source of truth" is per concern and workflow instance. It does not + mean one global store. +- The proxy-returning registration pattern avoids a second copy for node shell, + link topology, reroute chain, and widget state. A class accessor over the + registered proxy is a compatibility view, not another authority. +- Layout command coverage must not be generalized to all ECS mutation. The + other stores expose direct actions, and graph operations still coordinate + imperative class callbacks. +- Within this repository, Yjs supplies mergeable layout state and + notifications, not a retained application operation log or network + transport. ADR 0003's amendment records removal of those unused local seams. +- [`@comfyorg/comfy-multi-player`](https://github.com/Comfy-Org/comfy-multi-player) + separately implements a Yjs workflow document, stamped operation applier, + and canonical workflow projection for a server-host/browser-follower model. + Its contract leaves node positions, camera state, and other + layout concerns in the frontend layout document. This frontend branch does + not yet depend on or integrate that package, and its server document host is + still described as unmerged. +- Badges have no authoritative store. `badgeSystem` derives + transient `BadgeData` from authoritative settings, definitions, topology, + pricing, widget, and graph state. +- The migration preserves extension-facing object surfaces, but compatibility + has costs: enumerable node shell fields changed to accessors, direct slot + mirror writes are ignored, and callback preservation remains a release + constraint. + +## Reference records + +- [ADR 0003: Centralized Layout Management with CRDT](../../adr/0003-crdt-based-layout-system.md) +- [ADR 0008: Entity Component System](../../adr/0008-entity-component-system.md) +- [Node Data Store](../node-data-store.md) +- [Link Topology Store](../link-topology-store.md) +- [Reroute Chain Store](../reroute-chain-store.md) +- [Node Badge Store design history](../node-badge-store.md) +- [Output Slot Connectivity](../output-slot-connectivity.md) +- [`@comfyorg/comfy-multi-player`](https://github.com/Comfy-Org/comfy-multi-player) diff --git a/docs/architecture/ecs/ecs-documentation-audit.md b/docs/architecture/ecs/ecs-documentation-audit.md new file mode 100644 index 00000000000..23152cdc362 --- /dev/null +++ b/docs/architecture/ecs/ecs-documentation-audit.md @@ -0,0 +1,253 @@ +# ECS migration documentation audit (PR 14246) + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 +Scope: ADR 0003, ADR 0008, and architecture documents changed by PR 14246 + +The audit uses four document states: + +- `Current`: describes behavior shipped on this branch. +- `Partial`: a shipped bridge or subset, with remaining migration work. +- `Target`: desired architecture not yet implemented. +- `Historical`: superseded design retained to explain decisions. + +Verification confidence and missing behavioral scenarios are tracked in +[ecs-verification-audit.md](ecs-verification-audit.md). + +## ADR roles and current accuracy + +### ADR 0003: centralized CRDT layout + +The ADR is the decision authority for canonical geometry in `layoutStore`, Yjs +storage, mutation operations, and renderer-independent layout state. + +Status: `Partial`, despite the ADR header saying `Proposed`. Canonical +node/group/reroute geometry and scoped teardown are current. Collaboration, +multi-renderer inversion, and universal command-only mutation remain target. +The 2026-07-30 amendment accurately removes the unused operation log, but its +last sentence overstates command coverage. + +### ADR 0008: entity/component direction + +The ADR defines the architectural constraints and taxonomy: dedicated stores, +plain-data state, behavior outside components, graph ownership, and no +god-object growth. + +Status: `Partial`, also headed `Proposed`. The original World, numeric +entity brands, slot entities, and generalized systems are target or historical. +Dedicated stores for widgets, topology, reroute chains, node shell state, and +layout are current. Legacy classes remain compatibility shells and still host +substantial behavior. + +## Architecture-document inventory + +| Document | Role | Status and accuracy on this branch | +| -------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `appendix-ecs-pattern-survey.md` | External ECS pattern comparison | **Target/historical.** Useful rationale; its command-executor comparisons describe a future seam, not the current general mutation model. | +| `domain-glossary.md` | Canonical topology vocabulary | **Current.** The best terminology source for link, reroute, floating link, owner, and membership. It should be cited by topology records instead of redefining terms. | +| `ecs-lifecycle-scenarios.md` | Before/after operation narratives | **Mixed current/target.** Diagrams interleave shipped `_addLink`/store behavior with hypothetical `ConnectivitySystem`, scope retagging, command batches, and serialization systems without consistent labels. | +| `ecs-migration-plan.md` | Concise completed/remaining roadmap | **Current + target.** Links its detailed claims to focused audits. | +| `ecs-target-architecture.md` | End-state model and transition diagrams | **Target with current inserts.** Shipped sections for topology/layout are useful, but slot-mirror and keying text has stale statements. | +| `entity-interactions.md` | Baseline relationship map | **Current/partial.** Updated for stores, but the title correctly warns this remains the current legacy/store hybrid rather than the target ECS. | +| `entity-problems.md` | Motivation and structural debt | **Historical/current.** Some cited problems were reduced by this branch; retain them as historical motivation but mark resolved items. | +| `link-topology-store.md` | LinkStore decision record | **Historical + current amendments.** Initial target-slot identity design is superseded by link-ID primary authority and owner-qualified secondary indexes. | +| `node-badge-store.md` | Reversed badge-store decision | **Historical.** The "store" did not remain; current state is derived `nodeBadges()` in `src/systems/badgeSystem.ts`. Its reversal should be prominent in title/status. | +| `node-data-store.md` | Node shell extraction record | **Current/partial.** Accurate for `NodeState`, proxy adoption, renderer consumption, and teardown. Slot identity and broad command mutation remain deferred. | +| `output-slot-connectivity.md` | Removal of slot connectivity mirrors | **Current with stale pre-decision sections.** Decision 6 records the shipped result; Decisions 2 and 4 describe superseded implementation stages. | +| `proto-ecs-stores.md` | Cross-store inventory | **Current/partial.** Broadly useful, but several key-format and remaining-gap rows lag the branch. | +| `reroute-chain-store.md` | Reroute chain decision record | **Current plus one stale scope sentence.** Derived membership is accurate; `Reroute.pos` no longer mirrors layout state. | + +## Concrete contradictions and exact corrections + +### 1. Slot mirrors are described as still present + +ADR 0008's Slot amendment says `input.link` and +`output.links` "remain un-migrated." `ecs-target-architecture.md`, +`ecs-lifecycle-scenarios.md`, and `proto-ecs-stores.md` repeat that the class +mirrors remain or are a migration gap. On this branch, concrete slot accessors +are deprecated, non-enumerable, store-derived compatibility views; writes warn +and are ignored. There is no mutable connectivity mirror. + +Use the following wording: + +> Runtime slot connectivity is owned by `useLinkStore`. `NodeInputSlot.link` +> and `NodeOutputSlot.links` are deprecated, read-only compatibility accessors +> derived from the store; they are not authoritative fields. Slot identity and +> visual state remain class-side. + +### 2. LinkStore primary authority is misstated as target-slot keying + +ADR 0008, `ecs-lifecycle-scenarios.md`, and parts of +`link-topology-store.md` say a target input slot is the store key or primary +identity and that duplicate link IDs cannot collide. Current +`useLinkStore` maintains root-wide `RootTopologyBucket.byId` authority; +`targetIndex` and `originIndex` are owner-qualified secondary indexes. +Duplicate link IDs are rejected/reminted across sibling definitions. + +Use the following wording: + +> `LinkId` is the root-workflow-wide primary identity. `targetIndex` enforces +> one fully assigned link per owner-qualified target slot; `originIndex` +> supports fan-out queries. Floating links share the ID namespace but are +> absent from endpoint indexes until fully assigned. + +Update the ADR 0008 Link amendment, lifecycle load note, and key tables. + +### 3. Output `originIndex` is documented as derived computed state + +`output-slot-connectivity.md` Decision 2 shows a cached +`ComputedRef` rebuilt from `graphTopologies`. The implementation +stores `originIndex` in each `RootTopologyBucket` and maintains it atomically +with `byId` and `targetIndex` during registration, endpoint updates, and +deletion. + +Replace the computed-index pseudocode with: + +> `originIndex` is a reactive secondary index maintained in the same LinkStore +> mutation as primary topology and target occupancy. `getOutputSlotLinks` +> returns the indexed set; floating links are not indexed. + +Mark the old computed design **Historical**, not current. + +### 4. Command scope is generalized beyond implementation + +ADR 0003 says all spatial mutations use explicit commands; +ADR 0008 says all external mutations submit serializable, idempotent commands +and systems handle them. `ecs-lifecycle-scenarios.md` then attributes free +undo/redo and atomic command batches to all entity operations. Current command +records are layout-specific (`LayoutOperation`/`useLayoutMutations`), while +link, node, reroute, and widget stores expose imperative actions and classes +still coordinate callbacks. Undo/redo remains snapshot-based in +`ChangeTracker`. + +Use the following wording: + +> Command-shaped operations are current for layout mutations. A cross-store +> command executor, transactional rollback, and command-based undo/replay are +> targets. Other stores currently expose validated imperative actions; graph +> lifecycle methods remain orchestration boundaries. Undo/redo is snapshot +> based through `ChangeTracker`. + +Label `ConnectivitySystem`, `SerializationSystem`, and cross-store command +batches **Target** wherever diagrammed. + +### 5. Layout keying tables describe raw node/link IDs + +ADR 0008 and `proto-ecs-stores.md` still include variants of +"raw node/link IDs; scoped group/reroute IDs." ADR 0003's amendment and the +implementation scope nodes, groups, and reroutes with +`makeScopedLayoutKey(rootGraphId, id)`. Link segment geometry uses its separate +segment cache key and is not CRDT link topology. + +Use the following wording: + +> Persistent node, group, and reroute layout entries are keyed by +> `ScopedLayoutKey = makeScopedLayoutKey(rootGraphId, localId)`. Link topology +> does not live in LayoutStore. Transient link-segment geometry uses the +> segment-layout cache key and must not be listed as entity identity. + +### 6. Reroute position is called a remaining mirror + +The Scope section in `reroute-chain-store.md` says `Reroute.pos` is a class +field mirroring layout position. On this branch it is a compatibility geometry +view backed by the canonical layout entry; indexed and method mutations write +through. + +Use the following wording: + +> `Reroute.pos` is a stable compatibility view over LayoutStore geometry, not +> a second stored position. `RerouteChain` owns parent/floating topology; +> LayoutStore owns position. + +### 7. Dedicated-store lifecycle is over-uniform + +ADR 0008 says each dedicated store embeds graph scope in its +key and offers `clearGraph(graphId)`. Actual stores differ by concern: +LinkStore and RerouteStore use root buckets plus owner indexes; NodeDataStore +partitions by owning graph; LayoutStore uses root-scoped layout keys; global or +locator stores have different lifecycle contracts. + +Replace the universal rule with: + +> Every authoritative store defines an explicit workflow/owner lifecycle, but +> key shape and cleanup API are concern-specific. Inventory the primary +> identity, workflow bucket, owner association, and teardown operation +> separately. + +### 8. NodeDataStore scope tables omit owner partitioning + +`proto-ecs-stores.md` calls NodeDataStore simply root-scoped +and keyed by `NodeId`, which can imply one flat query namespace. The root bucket +owns ID uniqueness, while `NodeState.graphId` and owner indexes partition graph +membership and teardown. + +Describe the identity/lifecycle split explicitly: + +> Root workflow bucket + globally unique `NodeId`; owning `graphId` is an +> association/index used for graph-local queries and teardown, not an identity +> namespace. + +### 9. Badge record status is easy to misread + +A file named `node-badge-store.md` with `Status: Accepted` +looks like a current store design, although the record says the store was +deleted. ADR 0008 accurately records derivation, but inventories still count +stores inconsistently ("nine dedicated stores" while discussing the reversed +badge store nearby). + +Change the record status to `Historical: reversed` and add a +one-line current result immediately below the title: + +> Current result: no badge store; `nodeBadges()` derives `BadgeData` on read. + +Store counts should enumerate current stores or be removed. + +### 10. Lifecycle scenarios blur observation and destination + +`ecs-lifecycle-scenarios.md` labels tables "Current vs ECS" +but later prose uses future `ConnectivitySystem`, `SerializationSystem`, scope +retagging, command rollback, and free undo as though implemented. Some current +rows also retain deleted slot writes and old LinkStore keying. + +Prefix every diagram or table heading with `Current`, `Partial bridge`, or +`Target`. Keep current flows tied to stable symbols such as +`LGraph._addLink`, `useLinkStore.registerLink`, `detachGraphLayouts`, and +`ChangeTracker`; move hypothetical systems into target-only diagrams. + +## Recommended document status convention + +Use a small front matter block on every architecture record: + +```text +Status: Current | Partial | Target | Historical +Verified: YYYY-MM-DD against +Supersedes: +Superseded by: +``` + +For mixed documents, status each section with one of the same four labels. +Dated amendments should say what they supersede and should replace, not merely +append to, false summaries and key tables. Label pseudocode `Illustrative +target` unless it matches a named current symbol. Historical +records should remain available, but their title/status must prevent them from +being mistaken for API guidance. + +## Priority correction order + +1. Correct LinkStore primary identity, slot-mirror status, and duplicate-link + load behavior in ADR 0008 and lifecycle documentation. +2. Correct layout keying and command scope in ADR 0003/0008 summaries and all + inventory tables. +3. Mark `originIndex` computed pseudocode and the badge store as historical. +4. Split current and target lifecycle diagrams. +5. Remove store counts and other drift-prone aggregate claims. + +## Assessment + +The branch's documents contain the right decisions, but amendments often sit +beside unrevised earlier claims. The most consequential errors are not wording: +they reverse authority (target slot versus LinkId), retain deleted slot +mirrors, describe a derived `originIndex` that is actually maintained, broaden +layout commands into a general executor, and report obsolete layout keys. +Consistent current/partial/target/historical labels would make the records +usable without erasing their design history. diff --git a/docs/architecture/ecs/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md new file mode 100644 index 00000000000..c8e87a96c79 --- /dev/null +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -0,0 +1,171 @@ +# ECS extension compatibility audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This audit describes the implemented extension-facing contract. It does not +catalog every internal refactor. + +## Preserved behavior + +### Graph and type discovery + +- `LiteGraph.registered_node_types`, `registerNodeType()`, + `unregisterNodeType()`, `createNode()`, `getNodeType()`, and node-type + enumeration remain available in `LiteGraphGlobal.ts`. +- Slot registries (`registered_slot_*_types`, `slot_types_in/out`, and + `slot_types_default_in/out`) remain available. `auto_load_slot_types` retains + its constructor-based discovery behavior. +- Node `type`, slot `type`, `getInputDataType()`, `getOutputNodes()`, and search + helpers remain extension-visible. Store migration does not require extensions + to enumerate Pinia internals. + +### Geometry facade + +`LGraphNode.pos`, `size`, `boundingRect`, `getBounding()`, `setPos()`, and +`setSize()` remain the supported node facade. Reads project the authoritative +layout-store rectangle and writes commit through it. In-place typed-array size +mutations remain synchronized. Extensions should keep using node geometry, not +reach into `layoutStore` or depend on its scoped key format. + +### Lifecycle surface + +`node.onAdded(graph)`, `node.onRemoved()`, graph `onNodeAdded` / +`onNodeRemoved`, and `onConnectionsChange()` remain. Graph events +`node:added`, `node:before-removed`, and `node:removed` provide an additional +typed observation surface. Connection veto hooks (`onConnectInput`, +`onConnectOutput`) and normal connection callbacks remain in `LGraphNode.ts`. + +Removal ordering is intentional. `node:before-removed` and `onRemoved` occur +while the departing node can still identify its graph-owned state; cleanup is +completed before `node:removed`. Input replacement registers the new link +before old-link disconnect callbacks, so callback queries observe the +replacement rather than a transient empty input. + +## Deprecated compatibility behavior + +| Surface | Read behavior | Write / migration behavior | +| --------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `graph.links[id]` | Proxy-backed indexed access remains temporarily. | Use `graph.links.get(id)` and normal `Map` iteration. | +| `input.link` | Returns the current store-derived ID or `null` and emits deprecation telemetry. | Assignment is ignored. Use `isInputConnected()`, `getInputLink()`, `connect()`, or `disconnectInput()`. | +| `output.links` | Returns a fresh frozen ID array or `null` and emits telemetry. | Assignment and array mutation cannot change topology. Use node queries, `outputLinks()`, `connect()`, or `disconnectOutput()`. | +| `node.badgePosition` | Returns the fixed top-right position. | Assignment is ignored; badges always render top-right. | +| `LGraphCanvas.repositionNodesVueMode()` | Alias remains callable. | Use `applyNodePositions()`. | +| Graph `onBeforeChange` | Hook remains declared. | Prefer `LGraphCanvas.onBeforeChange`; graph hook is scheduled for removal. | + +Serialized slot `link`/`links` fields are still emitted for workflow +compatibility, but constructors strip those mirrors before rebuilding topology. +They are serialization data, not mutable runtime storage. + +## Changed behavior + +### Active Pinia is mandatory + +Constructing or configuring a root `LGraph` calls `useLinkStore()` immediately. +Tests, extensions, workers, and standalone LiteGraph consumers must install and +activate Pinia before graph construction. Missing Pinia is no longer interpreted +as an empty topology store. Subgraphs inherit the root's store context. + +### `graph.links` and `graph.floatingLinks` + +Both are owner-filtered `LinkMap` views over `linkStore`, not native `Map` +storage. `graph.links` contains complete links; `floatingLinks` contains links +with an unassigned endpoint. Reads, `size`, iteration, `forEach`, `clear`, and +`delete` retain Map-shaped behavior. Membership snapshots are cached by store +revision, so acquire a new iterator after topology changes. Do not call +`Map.prototype` methods with a view as receiver or inspect native Map storage. + +`LinkMap.set(id, link)` still returns the view, as `Map.set()` does. It rejects a +mismatched key (`id !== link.id`). Registration also rejects an occupied link ID +or complete target input and preserves the incumbent. Therefore `set()` does +not prove registration. Verify `get(id) === link`, allowing for the store-held +reactive object where applicable, or use graph connection APIs. + +`addFloatingLink()` now returns `LLink | undefined`. It returns the stored link +for success or idempotent re-registration, and `undefined` for collision. Never +retain or render the incoming object before checking. Full examples and +import-boundary rules are in +[Link registration migration](../../extensions/link-registration-migration.md). + +### Store-derived connectivity + +Topology is authoritative in `linkStore`; slot mirrors no longer drive links. +Callback code reading the deprecated accessors sees current store state. Code +that used `input.link = ...`, `output.links.push(...)`, or replacement of either +property is now a no-op and must move to graph/node mutation APIs. + +### Node shell properties and enumeration + +`id`, `type`, `title`, `flags`, `mode`, `color`, `bgcolor`, `shape`, +`showAdvanced`, `inputs`, and `outputs` are now accessors over `nodeDataStore` +state rather than instrumented own data properties. Ordinary reads and writes +remain, and tracked shell writes still emit `node:property:changed`. However, +`Object.keys(node)`, `for...in`, own-property descriptors, and object spread no +longer expose those fields exactly as before. Use named accessors and +`serialize()` instead of generic object enumeration. Changing `node.type` after +construction now warns and is deprecated; register/create the correct type or +replace the node instead. + +### Badges + +Extension entries in `node.badges`, including badge thunks, and `LGraphBadge` +content remain supported. Position customization changed: all badge rows render +at the top-right, and `badgePosition` is only an ignored compatibility accessor. +Derived first-party rows are recomputed on read; extension entries remain on +`node.badges` and render after them. + +## Unsupported behavior + +- `widgets_up` is detected and warned about but is not supported by the Vue + renderer. Use normal widget ordering/layout. +- Direct mutation of `input.link` or `output.links` is unsupported. +- Treating `LinkMap` as a native Map with internal slots, retaining iterators + across topology revisions, or assuming `set()` cannot reject is unsupported. +- Constructing a root graph without active Pinia is unsupported. +- Direct use of removed internal layout mutation paths is unsupported. Use + `LGraphNode` geometry accessors and `LGraphCanvas.applyNodePositions()`; do not + recreate `useGraphNodeManager`, `useVueNodeLifecycle`, or direct + `layoutMutations` coupling in extension code. +- Depending on configurable badge placement is unsupported. + +## Migration checklist + +1. Activate Pinia before creating any root graph in extension tests or isolated + runtimes. +2. Replace indexed link access and retained iterators with fresh Map-method + reads from `graph.links` / `floatingLinks`. +3. Handle `addFloatingLink()` failure and verify view insertions; do not choose + positive runtime IDs. Normalize persisted collisions during import. +4. Replace slot mirror writes with `connect`, `disconnectInput`, and + `disconnectOutput`; treat compatibility reads as transitional. +5. Use node/canvas geometry facades rather than layout-store APIs. +6. Remove `badgePosition` and `widgets_up` assumptions. +7. Preserve callback ordering assumptions only where covered below; subscribe + to graph events when observation is sufficient and no override is required. + +## Required follow-up evidence + +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/`. + +Before removing compatibility shims, collect ecosystem evidence for: + +- indexed `graph.links[id]`, direct slot writes, retained Map iterators, and + borrowed `Map.prototype` calls; +- graph construction outside the application Pinia bootstrap; +- `badgePosition`, `widgets_up`, and removed layout/composable imports; +- callback consumers that require the old transient-empty input replacement + state or depend on exact removal ordering; +- extensions mutating `registered_node_types` or slot registries directly, + including enumeration/property-descriptor assumptions; +- generic node serializers or inspectors depending on shell fields being own, + enumerable properties, and extensions changing `node.type` after creation; +- geometry consumers mutating `pos`/`size` by index and typed-array methods in + both canvas renderers. + +The identity consequences behind collisions and owner filtering are documented +in [ECS identity and scope audit](ecs-identity-scope-audit.md). Lifecycle test +scenarios remain in `ecs-lifecycle-scenarios.md`; planned API convergence belongs +in `ecs-migration-plan.md` rather than this compatibility record. diff --git a/docs/architecture/ecs/ecs-identity-scope-audit.md b/docs/architecture/ecs/ecs-identity-scope-audit.md new file mode 100644 index 00000000000..793c75ef28e --- /dev/null +++ b/docs/architecture/ecs/ecs-identity-scope-audit.md @@ -0,0 +1,126 @@ +# ECS identity and scope audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This document records the migration's implemented identity contract. It does +not broaden the accepted ADRs. + +## Scope model + +An open workflow has one root `LGraph`. Each contained `Subgraph` is an owning +graph. `graphScopeOf()` returns both identities: + +- `rootGraphId`: the root workflow UUID and the store/CRDT isolation boundary. +- `owningGraphId`: the UUID of the graph definition that owns the entity. + +A subgraph definition is stored once even when several `SubgraphNode` instances +reference it. Definition-scoped state is therefore shared by those instances. +Runtime execution paths are a separate identity domain. + +## Authoritative key table + +| Entity or key | Runtime identity / key | Scope and authority | Allocation / notes | +| --------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Root graph | `LGraph.id` UUID | Application/workflow | Serialized as the workflow graph ID. Root store buckets use `RootGraphId`. | +| Owning graph | root or `Subgraph.id` UUID | Root workflow | Serialized subgraph-definition ID; `GraphScope` pairs it with the root ID. | +| Node | `NodeId` | Owning graph logically; normalized unique across the recursive root workflow | `mintNodeId(root.state)`; numeric imported IDs advance the root allocator. String IDs are valid but do not advance it. | +| Node locator | root: ``; subgraph: `:` | Definition, not instance | `createNodeLocatorId()`; stable across every instance of one subgraph definition. | +| Node execution | `:...:` | Invocation path | `NodeExecutionId`; resolves nested runtime messages, not persisted component ownership. | +| Link | `LinkId` | Root bucket, partitioned by owning graph | `mintLinkId(root.state)`. `linkStore` is the identity authority; IDs must be unique throughout the root bucket. | +| Link target endpoint | `${owningGraphId}:${nodeId}:${slot}` | Owning graph in a root bucket | Private `targetKey()`; one non-floating link per input. | +| Link origin endpoint | `${owningGraphId}:${nodeId}:${slot}` | Owning graph in a root bucket | Private `originKey()`; indexes a set because outputs fan out. | +| Reroute | `RerouteId` | Root bucket, partitioned by owning graph | `mintRerouteId(root.state)`; `rerouteStore` rejects an ID already held in that root bucket. | +| Group | `GroupId` | Owning graph logically; layout key uses root | `mintGroupId(root.state)`; serialized in its owning graph. | +| Widget value | `${rootGraphId}:${encode(nodeId)}:${encode(name)}` | Root workflow | `widgetId()`; root-wide node ID uniqueness disambiguates widgets in nested definitions. | +| Node layout | `${rootGraphId}:${nodeId}` | Root workflow | `makeScopedLayoutKey()` in `layoutStore`; node IDs must therefore be root-unique. | +| Group layout | `${rootGraphId}:${groupId}` | Root workflow | Same layout-key constructor; relies on recursive group-ID normalization. | +| Reroute layout | `${rootGraphId}:${rerouteId}` | Root workflow | Same layout-key constructor; relies on recursive reroute-ID normalization. | +| Node output / preview | `NodeLocatorId` | Graph definition | `nodeOutputStore` maps execution IDs to locators before access. Multiple instances of one definition intentionally share the entry. | +| Slot geometry | `${nodeId}-in-${index}` / `${nodeId}-out-${index}` | Unscoped layout spatial index | `slotId()`; safe only while node IDs remain root-unique. | +| Link segment geometry | `${linkId}:${rerouteId ?? 'final'}` | Unscoped layout spatial index | `makeLinkSegmentKey()`; safe only while link and reroute IDs remain root-unique. | + +Stable definitions are in `src/types/graphScopeId.ts`, +`src/lib/litegraph/src/idAllocation.ts`, `src/types/nodeIdentification.ts`, +`src/types/widgetId.ts`, and `src/types/slotId.ts`. + +## Allocation and recursive ownership + +`LGraph.state` holds the four monotonic counters. Subgraphs delegate allocation +to the root state rather than maintaining independent ID spaces. During load, +`LGraph.reserveIds()` recursively observes IDs before new entities are minted. +`linkStore` and `rerouteStore` then store entities under a root bucket and an +owning-graph partition. Owner filtering prevents topology queries in one +definition from seeing another definition's entities even though IDs share a +root-wide allocation domain. + +Recursive subgraphs do not create an instance-local component namespace. +Topology, widgets, layout, and locator-based output data describe definitions. +Only `NodeExecutionId` includes the nested instance path. Code handling backend +events must resolve execution identity before reading definition-scoped output. + +## Collision normalization + +`normalizeSubgraphIds()` in +`src/lib/litegraph/src/subgraph/subgraphDeduplication.ts` traverses definitions +in dependency order. It preserves the first owner of an ID and remaps later +cross-definition node, link, reroute, and group collisions from the root +allocator. Node remaps also patch link endpoints, promoted-widget references, +and proxy-widget metadata. + +`deduplicateLinks()` in `src/lib/litegraph/src/linkDeduplication.ts` separately +enforces one live link per target slot, removes duplicate topology, remaps +references, and realigns serialized slot mirrors after nodes are configured. +Runtime registration is deliberately not a repair boundary. `linkStore` and +`rerouteStore` preserve the incumbent and reject colliding arrivals. + +## Persistence and transfer boundaries + +- `LGraph.asSerialisable()` writes each owning graph's local + entities and topology while retaining definition UUIDs and allocated IDs. +- Deserialization and import reserve and normalize the complete recursive set + before registration. This is the authoritative persisted-ID repair boundary. +- `LGraphCanvas.copyToClipboard()` serializes selected entities. Paste + regenerates copied subgraph UUIDs and remaps cloned entity IDs before + recursive insertion. +- `workflowToClipboardItems()` and `workflowService` flatten and + normalize recursively imported definitions before adding them to the root. +- `replaceWithMapping()` preserves the node ID and transfers + registered shell and layout ownership. New widgets register under the same + IDs and can adopt retained widget state; links continue to address the same + node identity. + +## Remaining distributed invariants and risks + +1. Root-wide uniqueness is enforced by a combination of allocator discipline, + import normalization, and rejecting stores, not by one composite key type. +2. Slot and link-segment geometry keys omit graph scope. A missed normalization + path can alias geometry even though topology queries are owner-filtered. +3. Layout keys include the root UUID but omit the owning graph UUID; recursive + node/group/reroute uniqueness remains mandatory. +4. `widgetId()` uses the root graph UUID, not the owning graph UUID. It assumes + graph UUIDs contain no colon; encoded node/name segments make their + separators safe. Layout parsing has the same UUID assumption. +5. Numeric-looking string node IDs affect layout and endpoint keys but allocator + observation only advances for integer conversion. Mixed imported ID forms + need continued collision coverage. +6. Locator-keyed outputs intentionally conflate instances of one definition. + Per-instance concurrent output retention would require execution-path keys. +7. Direct extension insertion that bypasses import normalization can be + rejected after partial surrounding work. Use graph APIs and handle failure; + see + [Link registration migration](../../extensions/link-registration-migration.md). + +## Evidence and remaining tests + +Current regression evidence includes `subgraphDeduplication.test.ts`, +`idAllocation.test.ts`, `linkStore.test.ts`, `rerouteStore.test.ts`, +`copyPaste.spec.ts`, `subgraphLinkIdentity.spec.ts`, and +`nodeReplacement.spec.ts`. + +Follow-up evidence should add adversarial recursive fixtures covering group and +reroute collisions together, string/numeric node-ID equivalence, clipboard +insertion into a root with occupied geometry keys, and concurrent outputs from +two instances of one subgraph. Planned lifecycle ownership details belong in +`ecs-lifecycle-scenarios.md`; target structure remains in +`ecs-target-architecture.md`. diff --git a/docs/architecture/ecs/ecs-lifecycle-audit.md b/docs/architecture/ecs/ecs-lifecycle-audit.md new file mode 100644 index 00000000000..35197c6a5be --- /dev/null +++ b/docs/architecture/ecs/ecs-lifecycle-audit.md @@ -0,0 +1,150 @@ +# ECS lifecycle audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This audit records the current lifecycle rather than restating the target +architecture. The governing records are +[ADR 0003](../../adr/0003-crdt-based-layout-system.md) and +[ADR 0008](../../adr/0008-entity-component-system.md). See also the +[decision traceability matrix](ecs-decision-traceability.md). + +## Scope and ownership model + +One loaded workflow has a root graph ID. Nodes, links, and reroutes in every +subgraph definition share the root bucket, but carry the ID of the graph that +directly owns them. `graphScopeOf` produces this pair. Node, link, and reroute +IDs are unique across the root. Widget and layout keys include the root graph +ID. + +| Concern | Runtime authority | Ownership index or attachment | +| ---------------------- | --------------------------- | ------------------------------------------------------------------------ | +| Node shell | `useNodeDataStore` | `byId` plus `idsByOwner`; `LGraphNode._graphScope` | +| Link topology | `useLinkStore` | `byId`, owner, target-slot, and origin-slot indexes; `LLink._graphScope` | +| Reroute chain | `useRerouteStore` | `chains` plus `idsByOwner`; `Reroute._graphScope` | +| Widget value/order | `useWidgetValueStore` | root graph ID, then `WidgetId` and node ID | +| Entity geometry | `layoutStore` | `makeScopedLayoutKey(rootGraphId, localId)` plus weak attachments | +| Legacy graph structure | `LGraph` and entity classes | `_nodes`, `_nodes_by_id`, `_subgraphs`, groups and callbacks | + +Subgraphs are ownership scopes and reusable definitions. They are not a +separate ECS entity kind. `LGraph.rootGraph`, `graphScopeOf`, and the root +graph's shared allocation state bind nested definitions to one workflow. + +## Lifecycle flow matrix + +| Entity | Create and register | Configure and read | Serialize | Remove and clear | +| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Node | `LGraph.add` assigns or remints the ID, sets `graph`, calls `registerNodeState`, registers widgets, inserts legacy indexes, runs add callbacks, then `attachNodeLayout`. | `LGraph.configure` adds every shell before calling `LGraphNode.configure`, so links and peer nodes resolve. Shell accessors read the adopted `NodeState` proxy; geometry accessors read the layout store. | `LGraphNode.serialize` reads accessors, slots, properties, and widget proxies. `LGraph.asSerialisable` serializes owner-local nodes and topology. | `LGraph.remove` disconnects topology, releases unreachable subgraphs, runs callbacks, unregisters state and layout, nulls `graph`, then removes legacy indexes. `clear` tears down all owned graphs before resetting containers. | +| Link | Connect paths construct `LLink`; `LGraph._addLink`, `addFloatingLink`, and store-backed `LinkMap` call `registerLinkTopology`. Registration adopts the store proxy and rejects ID or occupied-target collisions. | Endpoint getters read `_state`. Endpoint setters call `useLinkStore.updateEndpoint`; `parentId` and `type` write the proxy directly. `LinkMap` gives owner-filtered compatibility views. | `LLink.asSerialisable` reads topology state. `serialiseOwnedTopology` emits owner-local regular and floating links. | Disconnect orchestration unregisters topology before pruning reroutes. `_removeLink` also drops transient link geometry. Bulk paths call `unregisterAllLinkTopologies` or clear the root bucket. | +| Reroute | `LGraph.setReroute` allocates or observes an ID and creates a `Reroute`; `_addReroute` registers chain state, inserts the legacy map, then `materializeRerouteLayout`. | Chain fields read the adopted proxy. Position reads the layout store through `createGeometryView`. `linkIds` and `floatingLinkIds` are computed by `useRerouteStore.buildMembershipIndex` from link parent chains. | `Reroute.serialize` emits chain state and derived membership. `LGraph.asSerialisable` emits owner-local reroutes. | `removeReroute` rewires child reroutes and links before `_removeReroute` unregisters chain and layout. Disconnect also removes newly empty reroutes. Bulk teardown unregisters chains by owner or root. | +| Widget | Widget constructors hold detached state. After node ID and graph ownership exist, `BaseWidget.setNodeId` calls `registerWidget` and adopts its proxy. `LGraph.add` also records node widget order. | `BaseWidget.value` reads and writes `_state`. Named configure data restores by widget name; positional values remain a fallback. Dynamic-widget and promotion code use store actions for explicit removal. | `LGraphNode.serialize` emits plain `widgets_values` and `widgets_values_named`, skipping `serialize === false`. Object values are deproxied through JSON conversion. | Individual widgets call `deleteWidget`; root `LGraph.clear` calls `widgetValueStore.clearGraph`. Normal node removal does not independently delete every widget entry. | +| Layout | `attachNodeLayout`, `attachGroupLayout`, and `materializeRerouteLayout` adopt an existing entry or submit a serializable create operation. | Entity geometry accessors synchronize local array views with `layoutStore`; moves and resizes submit operations. Link and slot geometry is view-scoped, derived renderer data. | Nodes, groups, and reroutes serialize through entity accessors, not by dumping Yjs. Link/slot view geometry is not persisted. | Single detach submits a delete operation. `detachGraphLayouts` batches owner-local deletes in one Yjs transaction. Root clear submits `clearGraph`; `clearViewGeometry` separately drops renderer caches and listeners. | + +## Concrete sequences + +### Graph load and configure + +1. `LGraph.configure` dispatches `configuring`, starts the named-widget shadow + load, normalizes topology, and clears or detaches the old graph. +2. It adopts the graph ID and clears root buckets or only the current owner. +3. It registers links first, then reroutes, and normalizes subgraph definitions. +4. It creates every node shell and calls `LGraph.add` before any node configure. +5. It configures nodes in a second pass. Connection callbacks can now resolve + peer nodes and pre-registered links; widgets restore after slots. +6. It registers floating links, removes unreachable reroutes, realigns input + link indexes, creates groups, and updates execution order. +7. It runs proxy-widget migration, preview exposure, `onConfigure`, and canvas + restoration. The `configured` event and shadow-load cleanup run in `finally`. + +This ordering is part of the compatibility contract. Serialization, +registration, and subgraph tests require links before nodes, all nodes before +node configuration, and layout attachment before configure-time position +writes. + +### Node removal + +1. `LGraph.remove` rejects absent, protected, or already-removing nodes. The + module-level `nodesBeingRemoved` weak set is the reentrancy guard. +2. `removeNode` calls `beforeChange` and dispatches `node:before-removed` while + the node is still attached. +3. Inputs, outputs, and floating links disconnect. Unreachable subgraph + definitions run their node lifecycles before their stores and layouts leave. +4. `node.onRemoved` runs while `node.graph` is still set. +5. Node state and layout detach, then `node.graph` becomes `null`. +6. Canvas selection and graph indexes are removed. `onNodeRemoved` and + `node:removed` observe a detached node absent from `getNodeById`. +7. Change hooks, dirtying, and execution-order recomputation finish the flow. + +`LGraph.test.ts` pins these callback observations and guards recursive removal. + +### Replacement in place + +`replaceWithMapping` in `useNodeReplacement` does not perform remove plus add. +It prepares the new shell, verifies legacy indexes and both ownership +attachments, runs old `onRemoved`, then calls `transferReplacementOwnership`. +That function transfers layout first and the registered `NodeState` second. +Only then does the orchestrator swap `_nodes` and `_nodes_by_id`, attach graph +references, register new widgets, restore data, reconnect mappings, and issue +the replacement callbacks. The old node receives a detached copy of state. + +The preflight and second ownership check prevent a callback from silently +stealing the slot. Neither check rolls back arbitrary callback side effects or +a failure after ownership transfer. + +### Clear and subgraph release + +`LGraph.clear` always runs `resetAfterClear` in `finally`: + +1. `teardownOwnedGraphs` snapshots root plus known subgraphs and fires node + removal lifecycles while topology and graph references remain available. +2. Its `finally` expands ownership again, catching entities and subgraphs added + reentrantly, then unregisters all links, reroutes, nodes, and attachments. +3. Root reset clears preview, widget, link, reroute, node, and layout buckets, + assigns a fresh graph ID, and resets legacy containers and canvases. +4. A subgraph clear removes only that owner and submits individual layout + deletes, preserving siblings in the shared root bucket. + +Tests in `LGraph.test.ts` pin recursive callbacks, entities added during clear, +idempotent repeated clear, nested lifecycle count, selected-owner isolation, +and teardown after a callback throws. If one callback throws, later callbacks +do not run, but structural teardown completes before the error escapes. + +## Remaining lifecycle hazards + +- Lifecycle spans stores and legacy containers without one transaction. An + exception can expose a partly completed remove, replacement, or configure. +- Node add publishes the node and callbacks before its layout attaches. + `node:added` can read graph/store ownership but cannot assume geometry exists. +- Widget state is root-scoped and normal node removal does not clear all of its + widget IDs. Reuse and replacement rely on keyed registration; stale entries + can live until explicit widget deletion or root clear. +- Replacement has bespoke transfer semantics and no general rollback. It also + invokes extension callbacks inside the critical ownership sequence. +- Root clear changes the graph ID after clearing stores. References retaining + the old ID become detached by design, but consumers must not cache scope. +- Reroute removal rewires many reactive objects one at a time. Readers can see + intermediate chains; only the final derived membership is authoritative. +- `configure(keep_old)` detaches layout attachments and reuses legacy state. + It is not an append transaction and has weaker cleanup guarantees than clear. +- Extension callbacks remain reentrant and can mutate graph structure. The + weak-set guard covers repeated node removal only, not arbitrary cross-entity + mutation or callback compensation. + +## Implementation and test references + +- `src/lib/litegraph/src/LGraph.ts`: `add`, `remove`, `removeNode`, `clear`, + `teardownOwnedGraphs`, `configure`, `asSerialisable`, `_addLink`, + `_removeLink`, `_addReroute`, `_removeReroute`, `setReroute`, `removeReroute` +- `src/lib/litegraph/src/LGraphNode.ts`: `configure`, `serialize`, + `registerNodeState`, `unregisterNodeState`, `transferReplacementOwnership` +- `src/lib/litegraph/src/LLink.ts`: `applyEndpointPatch`, + `registerLinkTopology`, `unregisterAllLinkTopologies` +- `src/lib/litegraph/src/Reroute.ts`: chain and position accessors, + `unregisterAllRerouteChains` +- `src/lib/litegraph/src/widgets/BaseWidget.ts`: `setNodeId`, `value` +- `src/renderer/core/layout/operations/graphLayoutAttachment.ts`: all entity + attach, transfer, detach, and bulk-detach operations +- `src/platform/nodeReplacement/useNodeReplacement.ts`: `replaceWithMapping` +- Tests: `LGraph.test.ts`, `LGraphNode.nodeState.test.ts`, `LLink.store.test.ts`, + `Reroute.store.test.ts`, `widgetValueStore.test.ts`, and + `layoutStore.test.ts` diff --git a/docs/architecture/ecs/ecs-migration-plan.md b/docs/architecture/ecs/ecs-migration-plan.md new file mode 100644 index 00000000000..86a8650f8c7 --- /dev/null +++ b/docs/architecture/ecs/ecs-migration-plan.md @@ -0,0 +1,171 @@ +# ECS migration plan + +Status: Partial +Verified: 2026-08-16 against PR 14246 + +This plan records completed ECS migration work and the work that remains. +Detailed evidence and unresolved risks are in the focused audits under +[References](#references). + +The governing decisions remain +[ADR 0003](../../adr/0003-crdt-based-layout-system.md) and +[ADR 0008](../../adr/0008-entity-component-system.md). This plan does not amend +them. + +## Direction + +Runtime graph state is moving from mutable LiteGraph object graphs into +dedicated stores, one store per concern. Legacy classes remain compatibility +facades while extensions and renderers migrate. Behavior moves into systems +only when there is a concrete consumer and a tested replacement path. + +The implementation has no central ECS `World`. Each concern defines its own +identity, scope, storage, and cleanup. Layout uses Yjs. The other migrated +stores use reactive Pinia state. + +## Work completed + +| Concern | Current result | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Node shell | `nodeDataStore` owns `NodeState`. `LGraphNode` adopts the registered reactive proxy; renderer-only node mirrors and `useGraphNodeManager` were removed. | +| Link topology | `linkStore` owns `LinkTopology` by root-wide `LinkId`, with owner, target, and origin indexes. `LLink` endpoint properties are compatibility accessors over the registered state. | +| Slot connectivity | Input and output connectivity is derived from `linkStore`. `input.link` and `output.links` are deprecated read-only compatibility accessors; writes are ignored. | +| Reroute chains | `rerouteStore` owns parent/floating chain state. Link membership is derived from link parent chains rather than stored on reroutes. | +| Widget state | `widgetValueStore` owns widget values, render metadata, and root-scoped per-node order. `BaseWidget` adopts registered state. | +| Layout | Yjs-backed `layoutStore` owns persistent node, group, and reroute geometry. Entity lifecycle attaches geometry independently of renderer lifecycle, and layout writes use `LayoutOperation`. | +| Renderer integration | Vue and legacy renderers read the same persistent geometry. Renderer switches clear transient view geometry rather than reseeding entity layout. | +| Badges | Badge rows are derived by `badgeSystem`; the temporary badge store was removed. Badge data is transient and is not serialized or independently mutated. | +| Identity | Root graph allocation and import normalization enforce unique node, link, group, and reroute IDs across nested definitions. Owner indexes retain graph-local queries and teardown. | +| Lifecycle | Graph add, configure, replace, remove, subgraph release, and clear register, transfer, or release migrated state. Clear handles reentrant and failing removal callbacks; normal node removal can retain widget entries, and `configure(keep_old)` provides weaker cleanup. | +| Persistence | Serialization, subgraph conversion, copy/paste, and workflow insertion preserve the existing workflow format while normalizing conflicting identities. | +| Compatibility | Legacy graph, node, link, slot, widget, geometry, and callback surfaces remain available where practical. Changed behavior is documented in the extension migration references. | + +## Current boundaries + +The following boundaries remain: + +- `LGraph`, `LGraphNode`, `LLink`, `Reroute`, slot classes, and widget classes + still contain behavior and coordinate mutations. +- Only layout has serializable operation-shaped writes. Topology uses validated + store actions; node, reroute, widget, slot, and extension state still allow + direct reactive or class mutation. +- No transaction spans Pinia stores, Yjs, legacy registries, callbacks, and + undo history. Cross-store consistency relies on orchestration order. +- Undo and redo restore serialized snapshots. They do not replay or invert ECS + commands. +- `NodeState.inputs` and `outputs` contain slot class instances. Slot data is + not yet a plain component model. +- Widget order exists in both the store and `LGraphNode.widgets` during the + compatibility period. +- Live graph object registries and store records coexist and must be attached + and detached together. +- Link paths, slot bounds, and hit-test geometry are transient renderer caches, + not persistent layout components. + +## Work remaining + +### 1. Prove the current bridge + +Before broadening or removing compatibility paths: + +- Add mixed undo/redo coverage for node replacement or removal involving + links, reroutes, promoted widgets, and layout. +- Prove failed workflow configuration leaves no node, link, reroute, widget, + or layout ownership behind. +- Exercise recursive mixed-ID collisions through load, insertion, copy/paste, + save, and reload. +- Run a representative extension corpus against `LinkMap`, callback ordering, + deprecated slot accessors, active-Pinia setup, node property enumeration, + and geometry mutation. +- Establish measured renderer budgets for large-workflow drag, resize, link + interaction, navigation, and renderer switching. + +These are behavioral gates. Additional store-internal tests are lower priority +unless they cover a new invariant. + +### 2. Establish mutation boundaries + +- Define which graph-domain changes must become serializable commands and + which transient or derived changes intentionally remain outside command + history. +- Route topology rewires, reroute-chain edits, node shell changes, widget + changes, subgraph edits, replacement, and promotion through explicit mutation + boundaries instead of public proxy writes. +- Specify deterministic allocation, idempotency, rejection, and duplicate + delivery behavior for each command or batch. +- Introduce a workflow-level transaction boundary, or documented compensation + model, for changes spanning stores, layout, legacy registries, and callbacks. +- Define how command batches integrate with snapshot-based undo. Do not claim + replayable or command-based undo until this is implemented and tested. + +### 3. Extract remaining behavior + +- Move connectivity orchestration out of graph/node classes while preserving + synchronous validation and notification callbacks during the bridge period. +- Extract serialization only after stores contain sufficient authoritative + data and parity can be checked against the existing wire format. +- Move legacy geometry projection ownership out of `LGraphNode` without + changing `pos` and `size` extension behavior. +- Separate remaining link visual/runtime state when a renderer or interaction + system can consume plain records directly. +- Extract plain slot state only when it removes a real class dependency; retain + array order semantics and keep connectivity in `linkStore`. +- Move render and execution behavior incrementally rather than creating empty + system abstractions ahead of consumers. + +### 4. Retire compatibility paths + +A compatibility path can be removed per concern only when: + +- production reads and writes use the replacement API; +- serialization and undo parity are proven; +- extension usage has been measured and a migration is published; +- callback timing and rejection behavior are preserved or versioned; +- renderer performance meets the agreed budget; and +- rollback remains possible through the release containing the removal. + +Likely retirement candidates include deprecated slot connectivity accessors, +indexed `graph.links[id]`, legacy layout aliases, duplicate widget-order +ownership, and class-owned component fields. They should not be removed as one +large final phase. + +## Explicit non-goals + +- Reintroducing a universal `World` registry. +- Creating a store for derived badge rows. +- Making transient renderer geometry persistent or CRDT-backed. +- Making every store Yjs-backed without a collaboration requirement. +- Adding a frontend-owned operation log or transport to `layoutStore`; + collaboration belongs at the integration boundary with + `@comfyorg/comfy-multi-player`. +- Creating slot IDs or component stores solely to match an abstract ECS model. +- Removing extension facades before migration evidence exists. + +## Completion criteria + +The migration is complete when, for every durable graph-domain concern: + +1. One authority and one supported mutation boundary are documented. +2. Lifecycle registration, transfer, teardown, and failed-operation behavior + are explicit and tested across nested graphs. +3. Serialization and undo restore the same authoritative state. +4. Derived and transient data cannot become competing persisted authorities. +5. Legacy classes no longer own domain behavior that has a store/system owner. +6. Remaining compatibility APIs are deliberate supported surfaces rather than + synchronization bridges. +7. Extension and renderer compatibility meet documented correctness and + performance gates. + +## References + +- [Executive summary](ecs-migration-summary.md) +- [Decision traceability](ecs-decision-traceability.md) +- [State authority audit](ecs-state-authority-audit.md) +- [Lifecycle audit](ecs-lifecycle-audit.md) +- [Mutation audit](ecs-mutation-audit.md) +- [Identity and scope audit](ecs-identity-scope-audit.md) +- [Extension compatibility audit](ecs-extension-compatibility-audit.md) +- [Verification audit](ecs-verification-audit.md) +- [Documentation audit](ecs-documentation-audit.md) +- [ECS target architecture](../ecs-target-architecture.md) +- [Link registration migration](../../extensions/link-registration-migration.md) diff --git a/docs/architecture/ecs/ecs-migration-summary.md b/docs/architecture/ecs/ecs-migration-summary.md new file mode 100644 index 00000000000..758653a6f56 --- /dev/null +++ b/docs/architecture/ecs/ecs-migration-summary.md @@ -0,0 +1,65 @@ +# ECS migration summary + +Status: Partial +Verified: 2026-08-16 against PR 14246 + +The graph architecture is moving state and behavior out of LiteGraph classes +and into dedicated Pinia stores and focused systems. PR 14246 establishes the +main state-ownership bridge while preserving the existing workflow format, +renderers, and extension-facing classes. + +## Current result + +- `nodeDataStore` owns renderer-facing node shell state. +- `linkStore` owns link topology and slot connectivity. +- `rerouteStore` owns reroute chain state; membership is derived. +- `widgetValueStore` owns widget values, render metadata, and order. +- Yjs-backed `layoutStore` owns persistent node, group, and reroute geometry. +- `badgeSystem` derives transient badge rows instead of storing them. +- Graph lifecycle registers and transfers migrated state across root graphs and + nested subgraph definitions. Clear paths tear it down; normal node removal + can retain widget entries until explicit deletion or root clear. +- Identity normalization protects store ownership during load, copy/paste, + insertion, conversion, and replacement. + +Legacy classes remain compatibility facades. Node, link, reroute, and widget +state generally share the store's reactive object instead of maintaining a +second copy. + +## What remains + +The ECS is only partly command-driven: + +- Serializable operations currently cover layout, not all graph mutations. +- Cross-store changes have no workflow-wide transaction or rollback boundary. +- Undo/redo remains snapshot-based. +- Slots, widgets, and substantial graph behavior remain class-based. +- Widget order and live graph registries retain transitional dual + representations. +- Extension compatibility and large-workflow performance need broader evidence + before bridge APIs can be removed. + +The immediate priority is to prove mixed undo/load-failure behavior, recursive +identity handling, extension compatibility, and renderer performance. The next +architectural step is to define mutation and transaction boundaries before +extracting more systems or removing legacy facades. + +## Reference map + +| Question | Reference | +| ----------------------------------------------------------------- | --------------------------------------------------------------------- | +| What has shipped and what remains? | [Migration plan](ecs-migration-plan.md) | +| How does implementation align with ADR 0003 and ADR 0008? | [Decision traceability](ecs-decision-traceability.md) | +| Which source owns each kind of state? | [State authority audit](ecs-state-authority-audit.md) | +| How are entities registered, replaced, removed, and cleared? | [Lifecycle audit](ecs-lifecycle-audit.md) | +| Which writes are commands, store actions, or direct mutations? | [Mutation audit](ecs-mutation-audit.md) | +| How do IDs and graph scopes work? | [Identity and scope audit](ecs-identity-scope-audit.md) | +| What changes affect extensions? | [Extension compatibility audit](ecs-extension-compatibility-audit.md) | +| Which invariants are tested and where are the gaps? | [Verification audit](ecs-verification-audit.md) | +| Which existing architecture documents are stale or contradictory? | [Documentation audit](ecs-documentation-audit.md) | + +The ADRs remain the decision records: +[ADR 0003](../../adr/0003-crdt-based-layout-system.md) governs centralized +CRDT layout, and [ADR 0008](../../adr/0008-entity-component-system.md) governs +the ECS direction. These audits report implementation status without +modifying those decisions. diff --git a/docs/architecture/ecs/ecs-mutation-audit.md b/docs/architecture/ecs/ecs-mutation-audit.md new file mode 100644 index 00000000000..fb43d222e7c --- /dev/null +++ b/docs/architecture/ecs/ecs-mutation-audit.md @@ -0,0 +1,166 @@ +# ECS mutation audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This audit classifies current graph-domain writes and compares them with +[ADR 0003](../../adr/0003-crdt-based-layout-system.md) +and [ADR 0008](../../adr/0008-entity-component-system.md). The related +[decision traceability matrix](ecs-decision-traceability.md) maps each claim to +the wider design set. + +## Classification + +| Class | Current examples | Guarantees | Main gap | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Serializable layout operations | `layoutStore.applyOperation`, `applyOperations`; producers in `graphLayoutAttachment` and `layoutMutations` | Typed operation union, actor/source metadata, Yjs transaction, create/delete no-op guards, batch transaction | Operations have wall-clock timestamps; no durable operation log, inverse command, or workflow-wide transaction | +| Validated store actions | `linkStore.registerLink`, `replaceLink`, `updateEndpoints`, `deleteLink`; identity-checked register/delete in node and reroute stores; widget registration/order actions | Ownership checks; link endpoint batches validate before commit; duplicate identities and occupied input targets reject | Actions are not serializable commands and most do not support replay, inverse generation, or multi-store commit | +| Direct reactive-proxy writes | `LGraphNode` shell accessors, `BaseWidget.value`, `LLink.type` and `parentId`, `Reroute.parentId` and `floating`, slot objects and arrays | One reactive object is shared by class and store, so no mirror drifts; reroute setter blocks simple cycles | No command envelope, validation is field-specific, writes are not idempotent records, and nested mutation can bypass actions | +| Legacy orchestration | `LGraph.add/remove/clear/configure`, connect/disconnect, reroute splice/removal, subgraph promotion, `replaceWithMapping` | Preserves extension callbacks, serialization, graph indexes, and compatibility order | Imperative, reentrant, exception-sensitive sequences span stores and class containers without atomicity or rollback | +| Derived read-only data | Reroute membership, link owner views and slot indexes, badge projections, layout spatial indexes, renderer link/slot geometry | Recomputed from an authority; no second persisted copy | Some projections update after individual writes and can expose intermediate state; compatibility views still expose mutable shells | + +The first row is the only current implementation that matches ADR 0003's +command shape in a meaningful sense. The other rows may be centralized or +reactive, but that is not command-driven mutation. + +## Mutation inventory by concern + +| Concern | Authoritative writes | Classification | Notes | +| ------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Node identity and ownership | `nodeDataStore.registerNode`, `deleteNode`, `clearOwner`, `clearGraph` | Validated store actions | Registration and deletion compare raw object identity. Root-wide ID collision makes `LGraph.add` remint and retry. | +| Node shell | `LGraphNode` accessors over `_state`; configure assigns fields and mutates flags, slots, and properties | Direct proxy plus legacy orchestration | Registered ID is protected, but title, mode, visual state, slot arrays, and nested flags have no serializable operation. | +| Link identity and endpoints | `linkStore.replaceLink`, `updateEndpoint(s)`, `deleteLink` | Validated store actions | `updateEndpoints` validates all participants, vacates old indexes, patches, then reindexes as one synchronous action. | +| Link type and reroute terminus | `LLink.type`, `LLink.parentId` | Direct proxy writes | `parentId` mutation invalidates derived reroute membership through Vue tracking, but does not validate owner or chain existence. | +| Reroute identity | `rerouteStore.registerReroute`, `deleteReroute`, clear actions | Validated store actions | Raw identity and owner checks protect registration and deletion. | +| Reroute chain | `Reroute.parentId`, `floating`; `LGraph.createReroute/removeReroute` rewiring loops | Direct proxy plus legacy orchestration | Setter prevents a local parent cycle. Multi-entity splice/remove is a sequence, not a transaction. | +| Widget state | `widgetValueStore.registerWidget`, `setValue`, order and delete actions; `BaseWidget.value` | Store actions plus direct proxy writes | Registration can reuse existing state by type. Values and render state are freely mutable and have no owner transaction with node lifecycle. | +| Entity geometry | `LayoutOperation` handlers for node, reroute, and group create/move/resize/delete/clear | Serializable layout operations | `applyOperations` makes one Yjs transaction. Root-scoped keys and operation handlers make repeated create/delete no-ops. | +| Link/slot geometry | renderer tracking and `layoutStore` view maps | Derived or transient direct state | Cleared by `clearViewGeometry`; not serialized or part of entity history. | +| Graph membership and callbacks | arrays/maps in `LGraph`, `node.graph`, subgraph registry, execution order | Legacy orchestration | Store registration is interleaved with legacy publication and callbacks. | +| Properties and extension state | `node.properties`, callback-owned fields, node-specific widgets | Direct class writes | Open-ended extension data has no schema, validation, command form, or deterministic reducer. | +| Badges and reroute membership | `badgeSystem` computed projections; `rerouteStore.buildMembershipIndex` | Derived read-only data | Correctly omitted from serialization, command, and undo state as independent entities. | + +## ADR 0003 properties + +| Property | Layout operations | Store actions and proxy writes | Legacy graph operation | +| ------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | +| Serializable | Yes, for the `LayoutOperation` union | No common envelope; reactive objects may contain class instances | No; method calls and callbacks carry live references | +| Deterministic | Reducers mostly are; actor stamping is stable per session, but timestamps and z-index allocation are producer state | Link validation is deterministic for a fixed store snapshot. General proxy setters and extension callbacks are not | No. Callback order is defined, but callback behavior, ID allocation, and current graph state affect results | +| Idempotent | Create/delete/clear guard existing state. Move/resize/set are assignment-idempotent for equal payloads | Some register/delete actions are idempotent by identity. Array edits, increments, callback effects, and rewiring are not | No general request ID, precondition, or applied-command ledger | +| Replayable | Operation values can be reapplied, but the removed operation log means the system does not retain a replay stream | No | Workflow JSON can be reconfigured, which is state restoration rather than mutation replay | +| Undoable | Not by inverse operations. Current workflow undo restores snapshots | Not by action inverses | `beforeChange`/`afterChange` feed snapshot history; callbacks rerun during restoration paths | +| Transmittable | Yjs state updates can represent layout state, though public sync seams and operation history are absent | No command transport | No | + +The layout store is command-shaped, not a complete command bus. Its Yjs +document is a mergeable state record. `LayoutOperation.timestamp` is metadata, +not an ordering proof, and `allocateZIndex` depends on local store history. + +## Transaction boundaries and visibility + +### Boundaries that exist + +- `layoutStore.applyOperation` wraps one operation in `Y.Doc.transact`. +- `layoutStore.applyOperations` wraps a list in one Yjs transaction, then queues + one change record per applied operation. +- `linkStore.updateEndpoints` validates the complete endpoint set before any + mutation. Within one synchronous action it removes all placements, patches + all topologies, rebuilds indexes, and bumps revision once. +- Root and owner clear actions mutate one Pinia store synchronously. +- `LGraph.clear` uses `finally` so structural teardown completes after a node + lifecycle callback throws. + +### Boundaries that do not exist + +There is no transaction spanning Pinia stores, Yjs, `LGraph` containers, +entity back-references, callbacks, and snapshot history. Vue batching may delay +rendering, but it does not make those writes atomic. Examples: + +- Node add registers node state, widgets, legacy indexes, callbacks, and layout + in separate steps. A callback can observe or alter the in-progress state. +- Link connect commits topology before disconnect callbacks for the displaced + link. Tests pin that useful ordering, but nested callbacks can replace the + replacement and force the outer connect to abort. +- Reroute creation registers chain and layout separately, then rewires every + affected link and reroute through direct proxy assignments. +- Node removal disconnects many links, releases subgraphs, runs callbacks, + unregisters stores, deletes layout, and removes indexes without rollback. +- Root clear invokes six store clears and legacy reset in sequence. No reader + receives one workflow-level commit event covering all of them. +- Replacement transfers layout ownership and node-state ownership before + swapping legacy indexes and rebuilding widgets and connections. + +Cross-store consistency depends on orchestration order and tests, not an atomic +commit protocol. + +## Replay and undo today + +Workflow undo remains snapshot-based through the change tracker. Legacy +`beforeChange` and `afterChange` delimit user-visible edits, serialization +captures the graph, and undo configures a prior snapshot. Layout commands do +not independently drive undo, and Pinia store actions do not emit inverses. + +Command replay cannot reconstruct the whole workflow because only layout has +command values. Replaying a snapshot can also invoke configure and lifecycle +callbacks whose external effects are absent from the snapshot. Equal +serialized state does not imply equal callback history. + +## What must remain before "command-driven" is accurate system-wide + +The migration is not complete until all items below hold for every +authoritative graph-domain mutation, including extensions: + +1. Define serializable command schemas for node, link, reroute, widget, slot, + group, subgraph-definition, property, and promotion mutations. Commands must + carry stable IDs, graph scope, payload, source, and explicit preconditions. +2. Route class setters, store actions, connect/disconnect, configure-time edits, + replacement, dynamic widgets, and subgraph promotion through command + dispatch. Reactive proxies may remain read models, but must not be public + mutation channels. +3. Implement deterministic reducers. Remove wall-clock and local allocation + decisions from reducers; resolve IDs and z-order in command creation or with + deterministic allocation rules recorded in the command. +4. Specify idempotency for each command. Use assignment semantics plus + expected-version or expected-owner checks, and define duplicate-delivery + behavior. Multi-entity rewires need one batch command. +5. Add a workflow transaction coordinator that commits all affected stores, + layout state, legacy compatibility indexes, and derived invalidation as one + observable unit, or rolls them back. Pinia action boundaries are not enough. +6. Replace snapshot-only undo with command inverses or a documented hybrid that + records command batches and restores every authoritative concern. Define + whether extension callback effects are compensatable or excluded. +7. Provide a retained, ordered command stream or equivalent transport contract + for replay and CRDT transmission. Yjs layout state alone cannot replay graph + topology and widget mutations. +8. Move lifecycle callbacks outside reducer critical sections. Emit committed + events with plain data after success; prevent callbacks from mutating the + same transaction through legacy object references. +9. Close the extension boundary. Deprecate direct mutation of node properties, + slots, widgets, links, and graph maps, publish command APIs, and provide + migration behavior for existing custom nodes. +10. Prove the model with tests for duplicate delivery, deterministic replay, + inverse or snapshot parity, failed-batch rollback, nested subgraph scope, + and cross-store observer visibility. + +Until then, dedicated reactive stores hold an increasing share of entity state. +Layout mutation is operation-driven, topology has validated actions, and graph +mutation as a whole remains legacy-orchestrated and snapshot-undone. + +## Implementation and test references + +- `src/renderer/core/layout/store/layoutStore.ts`: `applyOperation`, + `applyOperations`, `applyOperationInTransaction`, operation handlers, + `clearGraph`, `clearViewGeometry` +- `src/renderer/core/layout/operations/graphLayoutAttachment.ts`: layout + operation producers and `detachGraphLayouts` +- `src/stores/linkStore.ts`: `replaceLink`, `validateEndpointUpdates`, + `updateEndpoints`, ownership and index maintenance +- `src/stores/nodeDataStore.ts`, `rerouteStore.ts`, `widgetValueStore.ts`: + registration, proxy adoption, clear, and direct mutable state +- `src/lib/litegraph/src/LGraph.ts`: graph orchestration, configure ordering, + clear, connect/remove helpers, and reroute rewiring +- `src/lib/litegraph/src/LGraphNode.ts`, `LLink.ts`, `Reroute.ts`, and + `widgets/BaseWidget.ts`: proxy-backed setters and compatibility shells +- `src/platform/nodeReplacement/useNodeReplacement.ts`: in-place replacement +- Tests: `layoutStore.test.ts`, `linkStore.test.ts`, `LLink.store.test.ts`, + `Reroute.store.test.ts`, `LGraph.test.ts`, `LGraphNode.nodeState.test.ts`, + and `widgetValueStore.test.ts` diff --git a/docs/architecture/ecs/ecs-state-authority-audit.md b/docs/architecture/ecs/ecs-state-authority-audit.md new file mode 100644 index 00000000000..66f120b1e0b --- /dev/null +++ b/docs/architecture/ecs/ecs-state-authority-audit.md @@ -0,0 +1,196 @@ +# ECS state authority audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This audit records state ownership on `feature/ecs-migration`. It distinguishes +authoritative records from compatibility accessors, derived projections, and +transient renderer caches. It identifies dual sources where the migration is +not complete. + +The governing decisions remain +[ADR 0003](../../adr/0003-crdt-based-layout-system.md) and +[ADR 0008](../../adr/0008-entity-component-system.md). See +[ECS Decision Traceability](ecs-decision-traceability.md) for principle-level +status and [ECS Target Architecture](../ecs-target-architecture.md) for the +target. + +## Node shell + +- **Authority:** `useNodeDataStore`; one store-backed `NodeState` in a root-flat, + owner-indexed bucket. As a transitional exception, its `inputs` and `outputs` + still contain `NodeInputSlot` and `NodeOutputSlot` instances. +- **Compatibility view/mirror:** `LGraphNode` fields are accessors over + `_state`, the store-returned reactive proxy. This is one object, not a copy. +- **Reads:** renderer components consume `NodeState`; legacy code reads + `LGraphNode.title`, `mode`, colors, flags, slot arrays, and related accessors. +- **Writes:** class setters and direct proxy writes; `registerNodeState` adopts + the proxy. These are not serializable commands. +- **Lifecycle:** `LGraph.add` registers; `LGraph.remove`, `clearOwner`, and + `clearGraph` unregister with raw-identity checks. +- **Risks:** `LGraphNode` still owns substantial non-shell state and behavior; + accessor fields differ from old enumerable own properties. +- **Desired endpoint:** store-owned plain node data, with class accessors only + as an explicitly supported extension adapter until callers migrate. + +## Layout + +- **Authority:** Yjs maps in `LayoutStoreImpl` for node, group, and reroute + position/size/bounds/z-order as applicable. +- **Compatibility view/mirror:** `LGraphNode`, `LGraphGroup`, and `Reroute` + geometry accessors/views read and write the store; local tuple buffers and + geometry versions support the legacy API and hot path. +- **Reads:** `getNodeLayoutRef`, geometry queries, `createGeometryView`, canvas + rendering, hit testing, and class geometry accessors. +- **Writes:** `LayoutOperation` through `applyOperation` / `applyOperations`, + `useLayoutMutations`, and `graphLayoutAttachment` helpers. +- **Lifecycle:** entity attach/detach follows `LGraph.add` / `remove`; root + teardown uses `layoutStore.clearGraph`, while owner detach removes entries. +- **Risks:** stale compatibility buffers are possible if synchronization + contracts regress; Yjs transport and operation history are absent by design. +- **Desired endpoint:** every durable geometry mutation remains command-based + and renderer-independent; compatibility buffers become read-through views. + +## Link topology + +- **Authority:** `useLinkStore` owns `LinkTopology` by link ID in root buckets, + with owner, target-slot, and origin-slot indexes. +- **Compatibility view/mirror:** `LLink._state` is the registered reactive + record. Endpoint class fields are accessors, not duplicate topology. +- **Reads:** `graphTopologies`, ID and endpoint queries, `slotLinks`, `LLink`, + canvas connectors, serialization, and reroute membership derivation. +- **Writes:** `registerLink`, `replaceLink`, `updateEndpoint(s)`, and + `deleteLink`, usually orchestrated by legacy graph/node connect APIs. +- **Lifecycle:** graph add/configure registers; disconnect/remove deletes; + `clearOwner` and `clearGraph` release indexed state. +- **Risks:** link visual/runtime fields remain on `LLink`; topology mutation is + transactional within the store but is not a serializable command protocol. +- **Desired endpoint:** topology and indexes remain singular store authority; + connectivity orchestration moves to a system without changing extensions or + serialized workflows. + +## Reroute chains + +- **Authority:** `useRerouteStore` owns plain `RerouteChain` parent/floating + state; membership is derived from `linkStore` parent chains. +- **Compatibility view/mirror:** `Reroute._chain` adopts the reactive store + record; `linkIds` and `floatingLinkIds` are derived views, not stored sets. +- **Reads:** reroute class accessors, graph/canvas traversal, serialization, and + `getMembership`'s computed reverse index. +- **Writes:** `registerReroute`, class chain accessors, and `deleteReroute`; + link membership changes by updating link topology. +- **Lifecycle:** graph registration/removal plus `clearOwner` / `clearGraph`; + computed membership is dropped with its owner. +- **Risks:** chain and layout are intentionally split across two stores; + malformed cycles and missing parents must remain bounded during traversal. +- **Desired endpoint:** keep chain state singular and membership derived; route + cross-store chain edits through one validated connectivity operation. + +## Widget value, render state, and order + +- **Authority:** `useWidgetValueStore` owns `WidgetState`, + `WidgetRenderState`, and per-node `WidgetId[]` order in root-workflow + buckets. +- **Compatibility view/mirror:** `BaseWidget` adopts store state, while + `LGraphNode.widgets` remains the ordered live widget-object collection used + by legacy drawing and extension APIs. **This is dual representation:** store + order and class array order require reconciliation. +- **Reads:** store getters power Vue/UI/pricing paths; legacy renderer, + serialization, and extensions read widget instances and `node.widgets`. +- **Writes:** `registerWidget`, `setValue`, `setNodeWidgetOrder`, deletion, and + legacy widget/class APIs. +- **Lifecycle:** widget construction/attachment registers; removal unregisters; + graph teardown calls `clearGraph`. +- **Risks:** renames and reordering can diverge across the store order and + object array; promoted widgets have host-boundary identity rules. +- **Desired endpoint:** store values/render metadata/order are canonical; + widget instances become behavior adapters assembled from that order. + +## Badges + +- **Authority:** no badge authority exists. Source stores own settings, node + definitions, colors, pricing inputs, widget values, and topology. +- **Compatibility view/mirror:** `nodeBadges` is a lazy computed projection; + `registerBadgeRowsProvider` is an app-to-litegraph rendering seam. +- **Reads:** canvas badge drawing requests plain `BadgeData` rows. +- **Writes:** none to badge rows; `computeBadges` derives them from `BadgeSources`. +- **Lifecycle:** one computed projection per node instance, released with that + instance/provider lifecycle; no serialization or graph cleanup record. +- **Risks:** the registration seam and class-dependent source gathering couple + the app system to live node instances. +- **Desired endpoint:** a render system gathers authoritative sources and passes + transient badge rows to renderers; do not add a badge cache/store by default. + +## Slots + +- **Authority:** slot identity, metadata, visuals, and behavior remain + `NodeInputSlot` / `NodeOutputSlot` instances in shallow-reactive node arrays; + `NodeState.inputs` / `outputs` hold those same arrays by reference. +- **Compatibility view/mirror:** `input.link` and `output.links` are deprecated, + store-derived reads; assignments warn and have no effect. Connectivity + authority is `linkStore` through `slotLinks`. +- **Reads:** renderer and interaction code read live slots; connectivity users + call `inputLinkId`, `outputLinks`, and node connection helpers. +- **Writes:** array mutation/reordering edits slot ownership/order; graph/node + connect APIs edit topology. Direct legacy mirror writes are ignored. +- **Lifecycle:** slots follow node construction/configuration/removal; topology + cleanup follows link and graph lifecycle. +- **Risks:** **dual authorities by concern** are legitimate but easy to blur: + slot object/array owns slot data/order, while `linkStore` owns connections. +- **Desired endpoint:** extract plain slot state only with a real consumer; + preserve array order semantics and keep connectivity exclusively store-owned. + +## Graph-instance registries and scope + +- **Authority:** `GraphScope` (`rootGraphId`, `owningGraphId`) defines migrated + store scope; `LGraph` remains the live graph-instance and lifecycle registry. +- **Compatibility view/mirror:** root buckets flatten identities while owner + indexes restore graph-local queries; `subgraphNavigationStore` tracks the + active navigation path, not graph-domain ownership. +- **Reads:** stores use `graphScopeOf`; graph algorithms and extensions still + traverse `LGraph._nodes`, links, reroutes, groups, and subgraphs. +- **Writes:** `LGraph.add`, remove, configure, and clear coordinate instances + and stores; dedicated stores enforce collision boundaries. +- **Lifecycle:** root clear drops the workflow bucket; owner clear detaches one + graph without deleting sibling owners in the same root. +- **Risks:** **dual registries remain:** live object collections in `LGraph` and + plain records/indexes in stores must attach and detach atomically. +- **Desired endpoint:** one explicit lifecycle coordinator maintains graph + instances as compatibility shells while stores own domain data. + +## Transient view geometry + +- **Authority:** `layoutStore` plain maps and spatial indexes own link paths, + link segments, slot bounds, and projected reroute hit-test geometry; + `canvasStore` owns current graph, selection, zoom, and canvas view state. +- **Compatibility view/mirror:** LiteGraph canvas fields and render-link objects + hold frame/interactions views; DOM widget positioning is in `domWidgetStore`. +- **Reads:** canvas draw, hover, hit testing, link interaction, Vue overlays, + and selection toolbox positioning. +- **Writes:** renderer synchronization calls `update*Layout` / clear methods; + canvas interactions update view stores and temporary render objects. +- **Lifecycle:** rebuilt or cleared on render/configuration/graph switch; + DOM widgets register/unregister or activate/deactivate separately. +- **Risks:** this geometry is intentionally not Yjs-backed or durable. Calling + it authoritative without the “transient view” qualifier would imply a second + layout source; stale caches can still produce visual/hit-test disagreement. +- **Desired endpoint:** derive and invalidate transient geometry from durable + layout/topology plus viewport state; never serialize or CRDT-replicate caches. + +## Dual-source boundaries + +1. Node, link, and reroute class fields generally share store proxies and are + compatibility views, not duplicate state. +2. Widget store order and `LGraphNode.widgets` are genuine dual + representations during migration. +3. Slot data/order remains class-array authority while slot connectivity is + separately authoritative in `linkStore`. +4. `LGraph` object registries and dedicated plain-data stores coexist and rely + on graph lifecycle chokepoints. +5. Durable entity geometry is Yjs-backed; link/slot/hit-test geometry is a + separate transient cache, not durable authority. + +Related design documents are [Node Data Store](../node-data-store.md), +[Link Topology Store](../link-topology-store.md), +[Reroute Chain Store](../reroute-chain-store.md), and +[Output Slot Connectivity](../output-slot-connectivity.md). diff --git a/docs/architecture/ecs/ecs-verification-audit.md b/docs/architecture/ecs/ecs-verification-audit.md new file mode 100644 index 00000000000..8aec214b8a9 --- /dev/null +++ b/docs/architecture/ecs/ecs-verification-audit.md @@ -0,0 +1,248 @@ +# ECS migration verification audit (PR 14246) + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 +Scope: Behavioral evidence added or materially changed by PR 14246 + +Evidence is grouped by invariant rather than implementation unit. A `Strong` +grade includes integration or browser evidence. `Good` covers meaningful +boundaries, while `Partial` indicates a material gap. + +For the accuracy and status audit of the accompanying design records, see +[ecs-documentation-audit.md](ecs-documentation-audit.md). + +## Evidence by invariant + +### Store collisions: Strong + +Invariant: IDs cannot overwrite an incumbent entity, owner scopes remain +isolated, and persisted collisions are normalized before registration. + +Representative evidence: + +- `src/stores/linkStore.test.ts`: contested targets, duplicate link IDs, + sibling-owner rejection, and atomic endpoint replacement. +- `src/stores/nodeDataStore.test.ts`: duplicate node identity and graph + isolation. +- `src/stores/rerouteStore.test.ts`: duplicate reroutes and owner isolation. +- `src/lib/litegraph/src/LGraph.test.ts`: persisted node, link, reroute, and + floating-link collision normalization. +- `browser_tests/tests/vueNodes/nodeStates/registration.spec.ts`: duplicate node + IDs remain visible in separate graph scopes. + +### Lifecycle teardown: Strong + +Invariant: add/remove/clear transfers or releases store ownership exactly once, +including reentrant and failing callbacks, without clearing sibling scopes. + +Representative evidence: + +- `src/lib/litegraph/src/LGraph.test.ts`: callback ordering, recursive removal, + entities added during clear, callback failure, idempotent root clear, and + owner-local subgraph clear. +- `src/lib/litegraph/src/LLink.store.test.ts`: root, subgraph, unconfigured, and + floating-link teardown; shared subgraph definitions remain registered. +- `src/lib/litegraph/src/Reroute.store.test.ts` and + `src/lib/litegraph/src/LGraphGroup.test.ts`: registration and clear behavior. +- `src/renderer/extensions/vueNodes/layout/useNodeLayout.test.ts`: workflow + replacement releases the originally retained graph. + +### Subgraph identity: Strong + +Invariant: one root allocates a unique runtime identity space while graph +ownership partitions queries; shared definitions retain ownership until their +last instance is gone. + +Representative evidence: + +- `src/lib/litegraph/src/idAllocation.test.ts` and + `src/lib/litegraph/src/LGraph.test.ts`: shared counters and cross-definition + deduplication. +- `src/lib/litegraph/src/subgraph/subgraphDeduplication.test.ts`: remaps every + regular/floating link reference and handles cyclic definition order. +- `src/lib/litegraph/src/subgraph/SubgraphSerialization.test.ts`: duplicate node + IDs and owner topology through reload. +- `browser_tests/tests/subgraph/subgraphLinkIdentity.spec.ts`: link identity and + reroute chains survive a real workflow load. + +### Serialization: Strong + +Invariant: store-backed runtime state emits the existing wire contract, +round-trips deterministically, and does not mutate caller-owned input while +normalizing aliases. + +Representative evidence: + +- `src/lib/litegraph/src/LGraph.test.ts`: byte-identical plain, rerouted, + floating-link, and reroute records; input immutability. +- `src/lib/litegraph/src/LGraph.serialise.test.ts`: links register after a JSON + round trip. +- `src/lib/litegraph/src/subgraph/SubgraphSerialization.test.ts`: interior + topology ordering, ownership, and rejected aliases. +- `src/lib/litegraph/src/node/slotUtils.test.ts`: output links serialize in + deterministic order and as `null` when empty. +- `browser_tests/tests/workflowPersistence.spec.ts` and + `browser_tests/tests/subgraph/subgraphSerialization.spec.ts`: browser-level + persistence checks. + +### Layout renderer toggle: Good + +Invariant: canonical node, slot, group, and reroute geometry remains coherent +across renderer changes and subgraph navigation. + +Representative evidence: + +- `browser_tests/tests/vueNodes/layout/rendererToggleGeometry.spec.ts`: slot and + node geometry across Vue-to-legacy round trips and repeated toggles. +- `browser_tests/tests/vueNodes/layout/subgraphLayoutSync.spec.ts`: layout sync in + an owned subgraph. +- `browser_tests/tests/vueNodes/rerouteGeometry.spec.ts`: reroute geometry across + navigation. +- `src/lib/litegraph/src/LGraphNode.test.ts`, + `src/lib/litegraph/src/LGraphGroup.test.ts`, and + `src/lib/litegraph/src/Reroute.store.test.ts`: legacy geometry views write + through and refresh from the store. + +### Widgets and promotions: Good + +Invariant: widget value identity is graph/host scoped, `null` is data rather +than absence, promotions preserve the interior/host mapping, and connectivity +reactively changes controls. + +Representative evidence: + +- `src/stores/widgetValueStore.graphReactivity.test.ts`: graph isolation, + nested promotions, duplicate names, and input-link reactivity. +- `src/lib/litegraph/src/subgraph/SubgraphWidgetPromotion.test.ts`: `null` + through promotion, reorder, serialization, and reload. +- `src/core/graph/subgraph/migration/proxyWidgetMigration.test.ts` and + `src/core/graph/subgraph/promotionUtils.test.ts`: migration and reorder + preservation. +- `src/components/rightSidePanel/parameters/WidgetActions.test.ts` and + `WidgetItem.test.ts`: user actions and linked-input state. +- `browser_tests/tests/appModeBuilder.spec.ts` and + `browser_tests/tests/vueNodes/widgets/widgetReactivity.spec.ts`: builder and + renderer integration. + +### Replacement: Good + +Invariant: replacing a same-ID node transfers registered shell/layout state and +live connectivity without allowing stale ownership to delete the replacement. + +Representative evidence: + +- `src/stores/nodeDataStore.test.ts`: same-ID state and geometry transfer; + mismatched identity does not transfer. +- `src/lib/litegraph/src/LLink.store.test.ts`: replacement commits before + callbacks and tolerates callback displacement. +- `src/lib/litegraph/src/node/slotLinks.test.ts`: atomic connected-input layout + replacement and stale-snapshot rejection. +- `browser_tests/tests/nodeReplacement.spec.ts`: replacement behavior through + the UI. + +### Clipboard and insertion: Good + +Invariant: copy/paste and insertion mint identities, retain geometry and +topology, and cannot hijack registrations owned by live entities. + +Representative evidence: + +- `src/lib/litegraph/src/LGraphCanvas.clipboard.test.ts`: stale reroute pruning, + live subgraph ownership, and reroute collision remapping. +- `src/core/graph/widgets/dynamicWidgets.test.ts`: group growth/shrink preserves + unrelated links and disconnects removed links. +- `src/lib/litegraph/src/LGraph.inputSlotRealign.test.ts`: rejected aliases and + slot movement realign registered topology. +- `browser_tests/tests/copyPaste.spec.ts`: pinned-node paste lands at the cursor. +- `browser_tests/tests/vueNodes/interactions/links/linkInteraction.spec.ts`: + floating-reroute interaction. + +### Badges: Good + +Invariant: badges are derived, reactive presentation data; pricing and source +rows update without a second authoritative store. + +Representative evidence: + +- `src/systems/badgeSystem.test.ts`: derivation, filtering, reactivity, and + identity-stable memoization. +- `src/systems/badgeSystem.pricing.test.ts`: relevant connectivity and graph-key + changes recompute pricing. +- `src/systems/badgeSystem.subgraph.test.ts`: wrapper aggregation and promoted + overrides. +- `src/renderer/extensions/vueNodes/composables/usePartitionedBadges.test.ts` + and `src/lib/litegraph/src/nodeBadgeDraw.test.ts`: Vue and legacy projections. + +### Performance: Partial + +Invariant: central stores and compatibility views do not introduce observable +hot-path regressions or reactive invalidation churn. + +Representative evidence: + +- `browser_tests/tests/performance.spec.ts`: large-graph legacy node drag. +- `src/lib/litegraph/src/LGraphNode.test.ts`: per-frame slot access does not + invalidate subscribers. +- `src/renderer/extensions/vueNodes/layout/useNodeDrag.test.ts`: one mutation + batch per animation frame. +- `src/renderer/extensions/vueNodes/composables/useVueNodeResizeTracking.test.ts`: + unchanged measurements avoid writes. + +### Extension behavior: Good + +Invariant: supported extension callbacks retain ordering and state visibility; +deprecated slot mirrors warn, remain derived, and cannot mutate authority. + +Representative evidence: + +- `src/lib/litegraph/src/node/NodeInputSlot.test.ts` and + `NodeOutputSlot.test.ts`: deprecation reads/writes and store-derived values. +- `src/lib/litegraph/src/node/slotEcosystemPatterns.test.ts`: duck-typed slots, + unknown keys, legacy `extra_info`, and collapsed rendering. +- `src/lib/litegraph/src/LGraphNode.test.ts` and + `src/lib/litegraph/src/node/slotLinks.test.ts`: callback-time committed state. +- `src/lib/litegraph/src/LGraphCanvas.drawConnections.test.ts`: normal internal + drawing and serialization do not emit deprecation warnings. +- `src/extensions/core/widgetInputs.test.ts`: stale extension-facing link state + recovers through the graph/store boundary. + +## Prioritized missing behavioral scenarios + +1. P0, undo/redo across a mixed transaction. Replace or remove a node with + links, reroutes, promoted widgets, and layout; undo and redo; assert every + store, callback-visible state, renderer, and serialization agree. Current + tests validate each concern but not transactional restoration across them. +2. P0, failed or interrupted workflow load. Force a configure callback to + throw after some nested definitions register, then load another workflow. + Assert no node/link/reroute/layout/widget ownership leaks from the failed + graph. +3. P1, deep mixed collision fixture. Load at least three nested/shared + definitions containing simultaneous node, link, reroute, group, and floating + link collisions; save/reload and verify reference remapping and byte-stable + second serialization. +4. P1, browser copy/paste of a connected subgraph. Paste a shared subgraph + with promoted widgets and rerouted external links, then delete original and + pasted instances in both orders. Verify ownership, values, and topology. +5. P1, renderer toggle plus navigation and history. Edit geometry in Vue, + navigate into/out of a subgraph, toggle legacy, undo/redo, and verify node, + slot, group, and reroute hit targets before saving. +6. P1, real extension compatibility corpus. Run representative extensions + that enumerate/spread slots, mutate deprecated `link`/`links`, use duck-typed + slots, and inspect callback state. Assert warnings and graceful behavior, + not merely type compatibility. +7. P2, promotion lifecycle after replacement. Replace a host node or remove + and recreate a shared definition while a nested promoted widget has a `null` + value and an external link; verify locator identity and cleanup. +8. P2, quantified renderer parity. Measure p50/p95 drag, toggle, and link + interaction frame time for representative 200- and 500-node workflows under + both renderers, with a checked threshold and warm-up policy. +9. P2, badge end-to-end settings parity. Toggle badge and pricing settings + in both renderers for root and subgraph nodes; verify updates after connect, + disconnect, replacement, and definition registration. + +## Assessment + +PR 14246 has strong behavioral coverage for identity, lifecycle, and wire +compatibility. The remaining verification risks are cross-store undo/load +failure atomicity, realistic extension execution, and quantified performance; +these matter more than adding further implementation-level store tests. diff --git a/docs/architecture/output-slot-connectivity.md b/docs/architecture/output-slot-connectivity.md index 8f44652dd74..07d83b352b4 100644 --- a/docs/architecture/output-slot-connectivity.md +++ b/docs/architecture/output-slot-connectivity.md @@ -1,10 +1,10 @@ # Output Slot Connectivity Date: 2026-07-06 -Status: Accepted (follow-up to the +Status: Accepted; follow-up to the [link topology store](link-topology-store.md); the minimal, non-breaking slice of the deferred `SlotConnection` component work in the -[ECS migration plan](ecs-migration-plan.md)) +[ECS migration plan](ecs/ecs-migration-plan.md) Design record for answering "is this output slot connected, and by what links?" from `linkStore` instead of the `output.links[]` mirror. It is diff --git a/docs/architecture/subgraph-boundaries-and-promotion.md b/docs/architecture/subgraph-boundaries-and-promotion.md index 61f24a82214..8557275ef1d 100644 --- a/docs/architecture/subgraph-boundaries-and-promotion.md +++ b/docs/architecture/subgraph-boundaries-and-promotion.md @@ -8,7 +8,7 @@ single deeper insight. For the structural problems motivating this work, see [Entity Problems](entity-problems.md). For the target architecture, see [ECS Target Architecture](ecs-target-architecture.md). For the phased migration -roadmap, see [ECS Migration Plan](ecs-migration-plan.md). +roadmap, see [ECS Migration Plan](ecs/ecs-migration-plan.md). --- @@ -567,7 +567,7 @@ documents in a follow-up pass after team review of this document: - [ECS Target Architecture](ecs-target-architecture.md) — World Overview diagram, Entity IDs diagram, component tables -- [ECS Migration Plan](ecs-migration-plan.md) — Phase 1c World type definition, +- [ECS Migration Plan](ecs/ecs-migration-plan.md) — Phase 1c World type definition, dependency graph - [ECS Lifecycle Scenarios](ecs-lifecycle-scenarios.md) — unpack flow uses `subgraphEntityId`