From 90b97e732b24b07b8b190d0f9b6c4e5d39675643 Mon Sep 17 00:00:00 2001 From: Amp Date: Sun, 16 Aug 2026 01:52:52 +0000 Subject: [PATCH 1/5] docs: map ECS migration status and remaining work Amp-Thread-ID: https://ampcode.com/threads/T-01a0080d-5de1-7308-b5a1-6f4c8a93cbe1 --- .../architecture/ecs-decision-traceability.md | 69 + docs/architecture/ecs-documentation-audit.md | 252 ++++ .../ecs-extension-compatibility-audit.md | 170 +++ docs/architecture/ecs-identity-scope-audit.md | 125 ++ docs/architecture/ecs-lifecycle-audit.md | 150 ++ docs/architecture/ecs-migration-plan.md | 1235 +++-------------- docs/architecture/ecs-migration-summary.md | 64 + docs/architecture/ecs-mutation-audit.md | 167 +++ .../architecture/ecs-state-authority-audit.md | 194 +++ docs/architecture/ecs-verification-audit.md | 249 ++++ 10 files changed, 1603 insertions(+), 1072 deletions(-) create mode 100644 docs/architecture/ecs-decision-traceability.md create mode 100644 docs/architecture/ecs-documentation-audit.md create mode 100644 docs/architecture/ecs-extension-compatibility-audit.md create mode 100644 docs/architecture/ecs-identity-scope-audit.md create mode 100644 docs/architecture/ecs-lifecycle-audit.md create mode 100644 docs/architecture/ecs-migration-summary.md create mode 100644 docs/architecture/ecs-mutation-audit.md create mode 100644 docs/architecture/ecs-state-authority-audit.md create mode 100644 docs/architecture/ecs-verification-audit.md diff --git a/docs/architecture/ecs-decision-traceability.md b/docs/architecture/ecs-decision-traceability.md new file mode 100644 index 00000000000..3a9454df105 --- /dev/null +++ b/docs/architecture/ecs-decision-traceability.md @@ -0,0 +1,69 @@ +# ECS Decision Traceability + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This document traces the implementation on `feature/ecs-migration` to the +principles recorded 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 is an implementation audit, not a replacement decision +or a proposal. + +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** — an ADR detail was replaced by a documented amendment. + +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; reintroduce transport APIs only when collaboration has a caller; 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. +- Yjs currently supplies mergeable layout state and notifications, not an + application operation log. ADR 0003's amendment records removal of the + unused history and transport seams. +- Badges intentionally 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) diff --git a/docs/architecture/ecs-documentation-audit.md b/docs/architecture/ecs-documentation-audit.md new file mode 100644 index 00000000000..8140e035c65 --- /dev/null +++ b/docs/architecture/ecs-documentation-audit.md @@ -0,0 +1,252 @@ +# 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 + +This is an accuracy audit, not a proposed rewrite. It distinguishes: + +- **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 + +**Role:** 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 + +**Role:** architectural constraint 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.** Rewritten by this change to remove phased commentary and link 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 + +**Contradiction:** 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. + +**Correction:** replace “mirror remains” with: + +> 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 + +**Contradiction:** 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. + +**Correction:** use: + +> `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 + +**Contradiction:** `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. + +**Correction:** 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 + +**Contradiction:** 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`. + +**Correction:** say: + +> 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 + +**Contradiction:** 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. + +**Correction:** use: + +> 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 + +**Contradiction:** `reroute-chain-store.md` Scope 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. + +**Correction:** state: + +> `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 + +**Contradiction:** ADR 0008 says each dedicated store embeds graph scope in its +key and offers `clearGraph(graphId)`. Actual stores differ deliberately: +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. + +**Correction:** 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 + +**Contradiction:** `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. + +**Correction:** 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 + +**Contradiction:** 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). + +**Correction:** 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 + +**Contradiction:** `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. + +**Correction:** prefix every diagram/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. Pseudocode must be labeled +**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. + +## Conclusion + +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-extension-compatibility-audit.md b/docs/architecture/ecs-extension-compatibility-audit.md new file mode 100644 index 00000000000..42b97de00ac --- /dev/null +++ b/docs/architecture/ecs-extension-compatibility-audit.md @@ -0,0 +1,170 @@ +# ECS Extension Compatibility Audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +The categories below describe the implemented extension-facing contract, not +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()` is not +proof of registration: verify `get(id) === link` (allowing for the store-held +reactive object where applicable), or use graph connection APIs. + +`addFloatingLink()` now returns `LLink | undefined`: 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-identity-scope-audit.md b/docs/architecture/ecs-identity-scope-audit.md new file mode 100644 index 00000000000..16696c37274 --- /dev/null +++ b/docs/architecture/ecs-identity-scope-audit.md @@ -0,0 +1,125 @@ +# ECS Identity and Scope Audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This document records the identity contract implemented by the migration; 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 + +- **Serialization:** `LGraph.asSerialisable()` writes each owning graph's local + entities and topology while retaining definition UUIDs and allocated IDs. +- **Deserialization/import:** reserve and normalize the complete recursive set + before registration. This is the authoritative persisted-ID repair boundary. +- **Clipboard:** `LGraphCanvas.copyToClipboard()` serializes selected entities; + paste regenerates copied subgraph UUIDs and remaps cloned entity IDs before + recursive insertion. +- **Insertion:** `workflowToClipboardItems()` and `workflowService` flatten and + normalize recursively imported definitions before adding them to the root. +- **Replacement:** `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 follow-up + +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-lifecycle-audit.md b/docs/architecture/ecs-lifecycle-audit.md new file mode 100644 index 00000000000..4a24bce9ecc --- /dev/null +++ b/docs/architecture/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 lifecycle that exists now. It does not restate 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 compatibility behavior. In particular, links before nodes, +all nodes before node configure, and layout attachment before configure-time +position writes are contracts pinned by serialization, registration, and +subgraph tests. + +### 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. They do not roll 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. + +## Stable 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-migration-plan.md b/docs/architecture/ecs-migration-plan.md index 09bb8c239e3..ad2bf10cc68 100644 --- a/docs/architecture/ecs-migration-plan.md +++ b/docs/architecture/ecs-migration-plan.md @@ -1,1078 +1,169 @@ # 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. +Status: Partial +Verified: 2026-08-16 against PR 14246 -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). +This document records what the ECS migration has delivered and what remains. +It is a roadmap, not a design history. Detailed evidence and unresolved risks +live in the focused audits linked under [References](#references). -> **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 +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. -| 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. +## 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 implemented model is not a central ECS `World`. Identity, scope, storage, +and cleanup are concern-specific. 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. Teardown handles reentrant and failing removal callbacks. | +| 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 migration is substantial but incomplete: + +- `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. +- Restoring an operation log or transport API before there is a consumer. +- 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-migration-summary.md b/docs/architecture/ecs-migration-summary.md new file mode 100644 index 00000000000..2865cc246ca --- /dev/null +++ b/docs/architecture/ecs-migration-summary.md @@ -0,0 +1,64 @@ +# ECS Migration Executive Summary + +Status: Partial +Verified: 2026-08-16 against PR 14246 + +The graph architecture is moving from state and behavior concentrated in +LiteGraph classes to 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, transfers, and tears down migrated state across + root graphs and nested subgraph definitions. +- Identity normalization protects store ownership during load, copy/paste, + insertion, conversion, and replacement. + +Legacy classes remain compatibility facades. For node, link, reroute, and +widget state, they generally share the store's reactive object rather than +maintaining a second copy. + +## What remains + +This is not yet a fully command-driven ECS: + +- 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-mutation-audit.md b/docs/architecture/ecs-mutation-audit.md new file mode 100644 index 00000000000..64f5021f43f --- /dev/null +++ b/docs/architecture/ecs-mutation-audit.md @@ -0,0 +1,167 @@ +# ECS Mutation Audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This audit classifies the writes that make up graph-domain mutation today and +tests the result against [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 therefore rests on orchestration order and tests, not +on 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. + +This has two consequences. First, command replay cannot reconstruct the whole +workflow because only layout has command values. Second, replaying a snapshot +can invoke configure and lifecycle callbacks whose external effects are not in +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, the accurate description is: entity state is increasingly held in +dedicated reactive stores; layout mutation is operation-driven; topology has +validated actions; graph mutation as a whole remains legacy-orchestrated and +snapshot-undone. + +## Stable 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-state-authority-audit.md b/docs/architecture/ecs-state-authority-audit.md new file mode 100644 index 00000000000..33d73ca1323 --- /dev/null +++ b/docs/architecture/ecs-state-authority-audit.md @@ -0,0 +1,194 @@ +# ECS State Authority Audit + +Status: Current implementation audit +Verified: 2026-08-16 against PR 14246 + +This is an audit of observed state ownership on `feature/ecs-migration`. It +distinguishes an authoritative record from a compatibility accessor, derived +projection, or transient renderer cache. Dual sources are called out rather +than presented as completed migration. + +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 plain `NodeState` in a root-flat, + owner-indexed bucket. +- **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. + +## Summary of 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. + +Design details: [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-verification-audit.md b/docs/architecture/ecs-verification-audit.md new file mode 100644 index 00000000000..b762bb97e62 --- /dev/null +++ b/docs/architecture/ecs-verification-audit.md @@ -0,0 +1,249 @@ +# 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 + +This audit groups evidence by invariant rather than implementation unit. Grades +measure behavioral confidence: **Strong** includes integration/browser +evidence, **Good** covers meaningful boundaries, and **Partial** has 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. + +## Conclusion + +PR 14246 has strong behavioral coverage for identity, lifecycle, and wire +compatibility. Its principal 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. From 4b094edf6ce85b4291dc32b1a1ca4a0eb277bedb Mon Sep 17 00:00:00 2001 From: Amp Date: Sun, 16 Aug 2026 05:28:30 +0000 Subject: [PATCH 2/5] docs: organize ECS migration references Amp-Thread-ID: https://ampcode.com/threads/T-01a0080d-5de1-7308-b5a1-6f4c8a93cbe1 --- docs/adr/0003-crdt-based-layout-system.md | 2 +- docs/adr/0008-entity-component-system.md | 4 +- .../appendix-ecs-pattern-survey.md | 2 +- docs/architecture/ecs-target-architecture.md | 2 +- .../{ => ecs}/ecs-decision-traceability.md | 59 +++++++++++-------- .../{ => ecs}/ecs-documentation-audit.md | 0 .../ecs-extension-compatibility-audit.md | 3 +- .../{ => ecs}/ecs-identity-scope-audit.md | 3 +- .../{ => ecs}/ecs-lifecycle-audit.md | 4 +- .../{ => ecs}/ecs-migration-plan.md | 12 ++-- .../{ => ecs}/ecs-migration-summary.md | 8 +-- .../{ => ecs}/ecs-mutation-audit.md | 4 +- .../{ => ecs}/ecs-state-authority-audit.md | 15 ++--- .../{ => ecs}/ecs-verification-audit.md | 0 docs/architecture/output-slot-connectivity.md | 2 +- .../subgraph-boundaries-and-promotion.md | 4 +- 16 files changed, 69 insertions(+), 55 deletions(-) rename docs/architecture/{ => ecs}/ecs-decision-traceability.md (81%) rename docs/architecture/{ => ecs}/ecs-documentation-audit.md (100%) rename docs/architecture/{ => ecs}/ecs-extension-compatibility-audit.md (99%) rename docs/architecture/{ => ecs}/ecs-identity-scope-audit.md (99%) rename docs/architecture/{ => ecs}/ecs-lifecycle-audit.md (99%) rename docs/architecture/{ => ecs}/ecs-migration-plan.md (95%) rename docs/architecture/{ => ecs}/ecs-migration-summary.md (93%) rename docs/architecture/{ => ecs}/ecs-mutation-audit.md (99%) rename docs/architecture/{ => ecs}/ecs-state-authority-audit.md (96%) rename docs/architecture/{ => ecs}/ecs-verification-audit.md (100%) 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-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-decision-traceability.md b/docs/architecture/ecs/ecs-decision-traceability.md similarity index 81% rename from docs/architecture/ecs-decision-traceability.md rename to docs/architecture/ecs/ecs-decision-traceability.md index 3a9454df105..44d5a3be150 100644 --- a/docs/architecture/ecs-decision-traceability.md +++ b/docs/architecture/ecs/ecs-decision-traceability.md @@ -4,8 +4,9 @@ Status: Current implementation audit Verified: 2026-08-16 against PR 14246 This document traces the implementation on `feature/ecs-migration` to the -principles recorded in [ADR 0003](../adr/0003-crdt-based-layout-system.md) and -[ADR 0008](../adr/0008-entity-component-system.md). The ADRs remain the +principles recorded 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 is an implementation audit, not a replacement decision or a proposal. @@ -20,22 +21,22 @@ Status meanings: 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). +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; reintroduce transport APIs only when collaboration has a caller; undo/redo remains snapshot-based | +| 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 @@ -47,9 +48,16 @@ is recorded in [ECS Migration Plan](ecs-migration-plan.md). - 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. -- Yjs currently supplies mergeable layout state and notifications, not an - application operation log. ADR 0003's amendment records removal of the - unused history and transport seams. +- 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 deliberately 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 intentionally have no authoritative store. `badgeSystem` derives transient `BadgeData` from authoritative settings, definitions, topology, pricing, widget, and graph state. @@ -60,10 +68,11 @@ is recorded in [ECS Migration Plan](ecs-migration-plan.md). ## 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) +- [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-documentation-audit.md b/docs/architecture/ecs/ecs-documentation-audit.md similarity index 100% rename from docs/architecture/ecs-documentation-audit.md rename to docs/architecture/ecs/ecs-documentation-audit.md diff --git a/docs/architecture/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md similarity index 99% rename from docs/architecture/ecs-extension-compatibility-audit.md rename to docs/architecture/ecs/ecs-extension-compatibility-audit.md index 42b97de00ac..4757cfca660 100644 --- a/docs/architecture/ecs-extension-compatibility-audit.md +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -84,7 +84,8 @@ reactive object where applicable), or use graph connection APIs. `addFloatingLink()` now returns `LLink | undefined`: 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). +rules are in +[Link registration migration](../../extensions/link-registration-migration.md). ### Store-derived connectivity diff --git a/docs/architecture/ecs-identity-scope-audit.md b/docs/architecture/ecs/ecs-identity-scope-audit.md similarity index 99% rename from docs/architecture/ecs-identity-scope-audit.md rename to docs/architecture/ecs/ecs-identity-scope-audit.md index 16696c37274..bef42cbab33 100644 --- a/docs/architecture/ecs-identity-scope-audit.md +++ b/docs/architecture/ecs/ecs-identity-scope-audit.md @@ -108,7 +108,8 @@ Runtime registration is deliberately not a repair boundary: `linkStore` and 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). + see + [Link registration migration](../../extensions/link-registration-migration.md). ## Evidence and follow-up diff --git a/docs/architecture/ecs-lifecycle-audit.md b/docs/architecture/ecs/ecs-lifecycle-audit.md similarity index 99% rename from docs/architecture/ecs-lifecycle-audit.md rename to docs/architecture/ecs/ecs-lifecycle-audit.md index 4a24bce9ecc..6f8b5de0601 100644 --- a/docs/architecture/ecs-lifecycle-audit.md +++ b/docs/architecture/ecs/ecs-lifecycle-audit.md @@ -5,8 +5,8 @@ Verified: 2026-08-16 against PR 14246 This audit records the lifecycle that exists now. It does not restate 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 +[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 diff --git a/docs/architecture/ecs-migration-plan.md b/docs/architecture/ecs/ecs-migration-plan.md similarity index 95% rename from docs/architecture/ecs-migration-plan.md rename to docs/architecture/ecs/ecs-migration-plan.md index ad2bf10cc68..4416cd68d82 100644 --- a/docs/architecture/ecs-migration-plan.md +++ b/docs/architecture/ecs/ecs-migration-plan.md @@ -8,8 +8,8 @@ It is a roadmap, not a design history. Detailed evidence and unresolved risks live in the focused audits linked 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 +[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 @@ -135,7 +135,9 @@ large final phase. - Creating a store for derived badge rows. - Making transient renderer geometry persistent or CRDT-backed. - Making every store Yjs-backed without a collaboration requirement. -- Restoring an operation log or transport API before there is a consumer. +- 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. @@ -165,5 +167,5 @@ The migration is complete when, for every durable graph-domain concern: - [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) +- [ECS target architecture](../ecs-target-architecture.md) +- [Link registration migration](../../extensions/link-registration-migration.md) diff --git a/docs/architecture/ecs-migration-summary.md b/docs/architecture/ecs/ecs-migration-summary.md similarity index 93% rename from docs/architecture/ecs-migration-summary.md rename to docs/architecture/ecs/ecs-migration-summary.md index 2865cc246ca..91d74cdd92a 100644 --- a/docs/architecture/ecs-migration-summary.md +++ b/docs/architecture/ecs/ecs-migration-summary.md @@ -58,7 +58,7 @@ extracting more systems or removing legacy facades. | 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. +[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-mutation-audit.md b/docs/architecture/ecs/ecs-mutation-audit.md similarity index 99% rename from docs/architecture/ecs-mutation-audit.md rename to docs/architecture/ecs/ecs-mutation-audit.md index 64f5021f43f..b2677e78981 100644 --- a/docs/architecture/ecs-mutation-audit.md +++ b/docs/architecture/ecs/ecs-mutation-audit.md @@ -4,8 +4,8 @@ Status: Current implementation audit Verified: 2026-08-16 against PR 14246 This audit classifies the writes that make up graph-domain mutation today and -tests the result against [ADR 0003](../adr/0003-crdt-based-layout-system.md) -and [ADR 0008](../adr/0008-entity-component-system.md). The related +tests the result against [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. diff --git a/docs/architecture/ecs-state-authority-audit.md b/docs/architecture/ecs/ecs-state-authority-audit.md similarity index 96% rename from docs/architecture/ecs-state-authority-audit.md rename to docs/architecture/ecs/ecs-state-authority-audit.md index 33d73ca1323..97f0614948f 100644 --- a/docs/architecture/ecs-state-authority-audit.md +++ b/docs/architecture/ecs/ecs-state-authority-audit.md @@ -9,10 +9,11 @@ projection, or transient renderer cache. Dual sources are called out rather than presented as completed migration. The governing decisions remain -[ADR 0003](../adr/0003-crdt-based-layout-system.md) and -[ADR 0008](../adr/0008-entity-component-system.md). See +[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. +status and [ECS Target Architecture](../ecs-target-architecture.md) for the +target. ## Node shell @@ -188,7 +189,7 @@ status and [ECS Target Architecture](ecs-target-architecture.md) for the target. 5. Durable entity geometry is Yjs-backed; link/slot/hit-test geometry is a separate transient cache, not durable authority. -Design details: [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). +Design details: [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-verification-audit.md b/docs/architecture/ecs/ecs-verification-audit.md similarity index 100% rename from docs/architecture/ecs-verification-audit.md rename to docs/architecture/ecs/ecs-verification-audit.md diff --git a/docs/architecture/output-slot-connectivity.md b/docs/architecture/output-slot-connectivity.md index 8f44652dd74..2961a559993 100644 --- a/docs/architecture/output-slot-connectivity.md +++ b/docs/architecture/output-slot-connectivity.md @@ -4,7 +4,7 @@ Date: 2026-07-06 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` From cdcf616e1bd2119a825b5930462f43755099c2b2 Mon Sep 17 00:00:00 2001 From: Amp Date: Sun, 16 Aug 2026 05:48:14 +0000 Subject: [PATCH 3/5] docs: refine ECS migration prose Amp-Thread-ID: https://ampcode.com/threads/T-01a0080d-5de1-7308-b5a1-6f4c8a93cbe1 --- .../ecs/ecs-decision-traceability.md | 22 +++-- .../ecs/ecs-documentation-audit.md | 85 ++++++++++--------- .../ecs/ecs-extension-compatibility-audit.md | 24 +++--- .../ecs/ecs-identity-scope-audit.md | 22 ++--- docs/architecture/ecs/ecs-lifecycle-audit.md | 20 ++--- docs/architecture/ecs/ecs-migration-plan.md | 16 ++-- .../architecture/ecs/ecs-migration-summary.md | 18 ++-- docs/architecture/ecs/ecs-mutation-audit.md | 27 +++--- .../ecs/ecs-state-authority-audit.md | 14 +-- .../ecs/ecs-verification-audit.md | 53 ++++++------ 10 files changed, 149 insertions(+), 152 deletions(-) diff --git a/docs/architecture/ecs/ecs-decision-traceability.md b/docs/architecture/ecs/ecs-decision-traceability.md index 44d5a3be150..b71f3b8383b 100644 --- a/docs/architecture/ecs/ecs-decision-traceability.md +++ b/docs/architecture/ecs/ecs-decision-traceability.md @@ -1,23 +1,21 @@ -# ECS Decision Traceability +# ECS decision traceability Status: Current implementation audit Verified: 2026-08-16 against PR 14246 -This document traces the implementation on `feature/ecs-migration` to the -principles recorded in +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 is an implementation audit, not a replacement decision -or a proposal. +decision records; this audit neither replaces nor amends them. Status meanings: -- **Implemented** — the observed implementation satisfies the principle for +- `Implemented`: the observed implementation satisfies the principle for its stated scope. -- **Partial** — an authoritative path exists, but legacy or uncovered concerns +- `Partial`: an authoritative path exists, but legacy or uncovered concerns remain. -- **Remaining** — the decision is not materially implemented. -- **Superseded** — an ADR detail was replaced by a documented amendment. +- `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 @@ -40,7 +38,7 @@ sequencing is recorded in [ECS Migration Plan](ecs-migration-plan.md). ## Observed boundaries -- “Single source of truth” is per concern and workflow instance. It does not +- "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 @@ -54,11 +52,11 @@ sequencing is recorded in [ECS Migration Plan](ecs-migration-plan.md). - [`@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 deliberately leaves node positions, camera state, and other + 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 intentionally have no authoritative store. `badgeSystem` derives +- 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 diff --git a/docs/architecture/ecs/ecs-documentation-audit.md b/docs/architecture/ecs/ecs-documentation-audit.md index 8140e035c65..23152cdc362 100644 --- a/docs/architecture/ecs/ecs-documentation-audit.md +++ b/docs/architecture/ecs/ecs-documentation-audit.md @@ -1,15 +1,15 @@ -# ECS Migration Documentation Audit (PR 14246) +# 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 -This is an accuracy audit, not a proposed rewrite. It distinguishes: +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. +- `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). @@ -18,10 +18,10 @@ Verification confidence and missing behavioral scenarios are tracked in ### ADR 0003: centralized CRDT layout -**Role:** decision authority for canonical geometry in `layoutStore`, Yjs +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 +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 @@ -29,10 +29,11 @@ last sentence overstates command coverage. ### ADR 0008: entity/component direction -**Role:** architectural constraint and taxonomy: dedicated stores, plain-data -state, behavior outside components, graph ownership, and no god-object growth. +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 +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 @@ -45,12 +46,12 @@ substantial behavior. | `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.** Rewritten by this change to remove phased commentary and link detailed claims to focused audits. | +| `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-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. | @@ -60,14 +61,14 @@ substantial behavior. ### 1. Slot mirrors are described as still present -**Contradiction:** ADR 0008’s Slot amendment says `input.link` and -`output.links` “remain un-migrated.” `ecs-target-architecture.md`, +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. -**Correction:** replace “mirror remains” with: +Use the following wording: > Runtime slot connectivity is owned by `useLinkStore`. `NodeInputSlot.link` > and `NodeOutputSlot.links` are deprecated, read-only compatibility accessors @@ -76,14 +77,14 @@ and are ignored. There is no mutable connectivity mirror. ### 2. LinkStore primary authority is misstated as target-slot keying -**Contradiction:** ADR 0008, `ecs-lifecycle-scenarios.md`, and parts of +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. -**Correction:** use: +Use the following wording: > `LinkId` is the root-workflow-wide primary identity. `targetIndex` enforces > one fully assigned link per owner-qualified target slot; `originIndex` @@ -94,13 +95,13 @@ Update the ADR 0008 Link amendment, lifecycle load note, and key tables. ### 3. Output `originIndex` is documented as derived computed state -**Contradiction:** `output-slot-connectivity.md` Decision 2 shows a cached +`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. -**Correction:** replace the computed-index pseudocode with: +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` @@ -110,7 +111,7 @@ Mark the old computed design **Historical**, not current. ### 4. Command scope is generalized beyond implementation -**Contradiction:** ADR 0003 says all spatial mutations use explicit commands; +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 @@ -119,7 +120,7 @@ link, node, reroute, and widget stores expose imperative actions and classes still coordinate callbacks. Undo/redo remains snapshot-based in `ChangeTracker`. -**Correction:** say: +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 @@ -132,13 +133,13 @@ batches **Target** wherever diagrammed. ### 5. Layout keying tables describe raw node/link IDs -**Contradiction:** 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 +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. -**Correction:** use: +Use the following wording: > Persistent node, group, and reroute layout entries are keyed by > `ScopedLayoutKey = makeScopedLayoutKey(rootGraphId, localId)`. Link topology @@ -147,12 +148,12 @@ segment cache key and is not CRDT link topology. ### 6. Reroute position is called a remaining mirror -**Contradiction:** `reroute-chain-store.md` Scope says `Reroute.pos` is a class +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. -**Correction:** state: +Use the following wording: > `Reroute.pos` is a stable compatibility view over LayoutStore geometry, not > a second stored position. `RerouteChain` owns parent/floating topology; @@ -160,13 +161,13 @@ through. ### 7. Dedicated-store lifecycle is over-uniform -**Contradiction:** ADR 0008 says each dedicated store embeds graph scope in its -key and offers `clearGraph(graphId)`. Actual stores differ deliberately: +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. -**Correction:** replace the universal rule with: +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 @@ -175,12 +176,12 @@ locator stores have different lifecycle contracts. ### 8. NodeDataStore scope tables omit owner partitioning -**Contradiction:** `proto-ecs-stores.md` calls NodeDataStore simply root-scoped +`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. -**Correction:** describe the identity/lifecycle split explicitly: +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 @@ -188,13 +189,13 @@ membership and teardown. ### 9. Badge record status is easy to misread -**Contradiction:** a file named `node-badge-store.md` with `Status: Accepted` +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 +stores inconsistently ("nine dedicated stores" while discussing the reversed badge store nearby). -**Correction:** change the record status to **Historical — reversed** and add a +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. @@ -203,13 +204,13 @@ Store counts should enumerate current stores or be removed. ### 10. Lifecycle scenarios blur observation and destination -**Contradiction:** `ecs-lifecycle-scenarios.md` labels tables “Current vs ECS” +`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. -**Correction:** prefix every diagram/table heading with **Current**, **Partial -bridge**, or **Target**. Keep current flows tied to stable symbols such as +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. @@ -226,8 +227,8 @@ 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. Pseudocode must be labeled -**Illustrative target** unless it matches a named current symbol. Historical +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. @@ -241,9 +242,9 @@ being mistaken for API guidance. 4. Split current and target lifecycle diagrams. 5. Remove store counts and other drift-prone aggregate claims. -## Conclusion +## Assessment -The branch’s documents contain the right decisions, but amendments often sit +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 diff --git a/docs/architecture/ecs/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md index 4757cfca660..c8e87a96c79 100644 --- a/docs/architecture/ecs/ecs-extension-compatibility-audit.md +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -1,10 +1,10 @@ -# ECS Extension Compatibility Audit +# ECS extension compatibility audit Status: Current implementation audit Verified: 2026-08-16 against PR 14246 -The categories below describe the implemented extension-facing contract, not -every internal refactor. +This audit describes the implemented extension-facing contract. It does not +catalog every internal refactor. ## Preserved behavior @@ -36,7 +36,7 @@ reach into `layoutStore` or depend on its scoped key format. 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 +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 @@ -77,14 +77,14 @@ revision, so acquire a new iterator after topology changes. Do not call `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()` is not -proof of registration: verify `get(id) === link` (allowing for the store-held -reactive object where applicable), or use graph connection APIs. - -`addFloatingLink()` now returns `LLink | undefined`: 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 +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 diff --git a/docs/architecture/ecs/ecs-identity-scope-audit.md b/docs/architecture/ecs/ecs-identity-scope-audit.md index bef42cbab33..793c75ef28e 100644 --- a/docs/architecture/ecs/ecs-identity-scope-audit.md +++ b/docs/architecture/ecs/ecs-identity-scope-audit.md @@ -1,10 +1,10 @@ -# ECS Identity and Scope Audit +# ECS identity and scope audit Status: Current implementation audit Verified: 2026-08-16 against PR 14246 -This document records the identity contract implemented by the migration; it -does not broaden the accepted ADRs. +This document records the migration's implemented identity contract. It does +not broaden the accepted ADRs. ## Scope model @@ -71,21 +71,21 @@ 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 +Runtime registration is deliberately not a repair boundary. `linkStore` and `rerouteStore` preserve the incumbent and reject colliding arrivals. ## Persistence and transfer boundaries -- **Serialization:** `LGraph.asSerialisable()` writes each owning graph's local +- `LGraph.asSerialisable()` writes each owning graph's local entities and topology while retaining definition UUIDs and allocated IDs. -- **Deserialization/import:** reserve and normalize the complete recursive set +- Deserialization and import reserve and normalize the complete recursive set before registration. This is the authoritative persisted-ID repair boundary. -- **Clipboard:** `LGraphCanvas.copyToClipboard()` serializes selected entities; - paste regenerates copied subgraph UUIDs and remaps cloned entity IDs before +- `LGraphCanvas.copyToClipboard()` serializes selected entities. Paste + regenerates copied subgraph UUIDs and remaps cloned entity IDs before recursive insertion. -- **Insertion:** `workflowToClipboardItems()` and `workflowService` flatten and +- `workflowToClipboardItems()` and `workflowService` flatten and normalize recursively imported definitions before adding them to the root. -- **Replacement:** `replaceWithMapping()` preserves the node ID and transfers +- `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. @@ -111,7 +111,7 @@ Runtime registration is deliberately not a repair boundary: `linkStore` and see [Link registration migration](../../extensions/link-registration-migration.md). -## Evidence and follow-up +## Evidence and remaining tests Current regression evidence includes `subgraphDeduplication.test.ts`, `idAllocation.test.ts`, `linkStore.test.ts`, `rerouteStore.test.ts`, diff --git a/docs/architecture/ecs/ecs-lifecycle-audit.md b/docs/architecture/ecs/ecs-lifecycle-audit.md index 6f8b5de0601..35197c6a5be 100644 --- a/docs/architecture/ecs/ecs-lifecycle-audit.md +++ b/docs/architecture/ecs/ecs-lifecycle-audit.md @@ -1,10 +1,10 @@ -# ECS Lifecycle Audit +# ECS lifecycle audit Status: Current implementation audit Verified: 2026-08-16 against PR 14246 -This audit records the lifecycle that exists now. It does not restate the -target architecture. The governing records are +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). @@ -56,10 +56,10 @@ graph's shared allocation state bind nested definitions to one workflow. 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 compatibility behavior. In particular, links before nodes, -all nodes before node configure, and layout attachment before configure-time -position writes are contracts pinned by serialization, registration, and -subgraph tests. +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 @@ -88,8 +88,8 @@ 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. They do not roll back arbitrary callback side effects or a -failure after ownership transfer. +stealing the slot. Neither check rolls back arbitrary callback side effects or +a failure after ownership transfer. ### Clear and subgraph release @@ -130,7 +130,7 @@ do not run, but structural teardown completes before the error escapes. weak-set guard covers repeated node removal only, not arbitrary cross-entity mutation or callback compensation. -## Stable implementation and test references +## Implementation and test references - `src/lib/litegraph/src/LGraph.ts`: `add`, `remove`, `removeNode`, `clear`, `teardownOwnedGraphs`, `configure`, `asSerialisable`, `_addLink`, diff --git a/docs/architecture/ecs/ecs-migration-plan.md b/docs/architecture/ecs/ecs-migration-plan.md index 4416cd68d82..381efb8579d 100644 --- a/docs/architecture/ecs/ecs-migration-plan.md +++ b/docs/architecture/ecs/ecs-migration-plan.md @@ -1,11 +1,11 @@ -# ECS Migration Plan +# ECS migration plan Status: Partial Verified: 2026-08-16 against PR 14246 -This document records what the ECS migration has delivered and what remains. -It is a roadmap, not a design history. Detailed evidence and unresolved risks -live in the focused audits linked under [References](#references). +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 @@ -19,9 +19,9 @@ 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 implemented model is not a central ECS `World`. Identity, scope, storage, -and cleanup are concern-specific. Layout uses Yjs; the other migrated stores -use reactive Pinia state. +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 @@ -42,7 +42,7 @@ use reactive Pinia state. ## Current boundaries -The migration is substantial but incomplete: +The following boundaries remain: - `LGraph`, `LGraphNode`, `LLink`, `Reroute`, slot classes, and widget classes still contain behavior and coordinate mutations. diff --git a/docs/architecture/ecs/ecs-migration-summary.md b/docs/architecture/ecs/ecs-migration-summary.md index 91d74cdd92a..6602f27f72a 100644 --- a/docs/architecture/ecs/ecs-migration-summary.md +++ b/docs/architecture/ecs/ecs-migration-summary.md @@ -1,12 +1,12 @@ -# ECS Migration Executive Summary +# ECS migration summary Status: Partial Verified: 2026-08-16 against PR 14246 -The graph architecture is moving from state and behavior concentrated in -LiteGraph classes to 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. +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 @@ -21,13 +21,13 @@ workflow format, renderers, and extension-facing classes. - Identity normalization protects store ownership during load, copy/paste, insertion, conversion, and replacement. -Legacy classes remain compatibility facades. For node, link, reroute, and -widget state, they generally share the store's reactive object rather than -maintaining a second copy. +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 -This is not yet a fully command-driven ECS: +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. diff --git a/docs/architecture/ecs/ecs-mutation-audit.md b/docs/architecture/ecs/ecs-mutation-audit.md index b2677e78981..fb43d222e7c 100644 --- a/docs/architecture/ecs/ecs-mutation-audit.md +++ b/docs/architecture/ecs/ecs-mutation-audit.md @@ -1,10 +1,10 @@ -# ECS Mutation Audit +# ECS mutation audit Status: Current implementation audit Verified: 2026-08-16 against PR 14246 -This audit classifies the writes that make up graph-domain mutation today and -tests the result against [ADR 0003](../../adr/0003-crdt-based-layout-system.md) +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. @@ -89,8 +89,8 @@ rendering, but it does not make those writes atomic. Examples: - Replacement transfers layout ownership and node-state ownership before swapping legacy indexes and rebuilding widgets and connections. -Cross-store consistency therefore rests on orchestration order and tests, not -on an atomic commit protocol. +Cross-store consistency depends on orchestration order and tests, not an atomic +commit protocol. ## Replay and undo today @@ -99,10 +99,10 @@ Workflow undo remains snapshot-based through the change tracker. Legacy captures the graph, and undo configures a prior snapshot. Layout commands do not independently drive undo, and Pinia store actions do not emit inverses. -This has two consequences. First, command replay cannot reconstruct the whole -workflow because only layout has command values. Second, replaying a snapshot -can invoke configure and lifecycle callbacks whose external effects are not in -the snapshot. Equal serialized state does not imply equal callback history. +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 @@ -141,12 +141,11 @@ authoritative graph-domain mutation, including extensions: inverse or snapshot parity, failed-batch rollback, nested subgraph scope, and cross-store observer visibility. -Until then, the accurate description is: entity state is increasingly held in -dedicated reactive stores; layout mutation is operation-driven; topology has -validated actions; graph mutation as a whole remains legacy-orchestrated and -snapshot-undone. +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. -## Stable implementation and test references +## Implementation and test references - `src/renderer/core/layout/store/layoutStore.ts`: `applyOperation`, `applyOperations`, `applyOperationInTransaction`, operation handlers, diff --git a/docs/architecture/ecs/ecs-state-authority-audit.md b/docs/architecture/ecs/ecs-state-authority-audit.md index 97f0614948f..d5f03ab895f 100644 --- a/docs/architecture/ecs/ecs-state-authority-audit.md +++ b/docs/architecture/ecs/ecs-state-authority-audit.md @@ -1,12 +1,12 @@ -# ECS State Authority Audit +# ECS state authority audit Status: Current implementation audit Verified: 2026-08-16 against PR 14246 -This is an audit of observed state ownership on `feature/ecs-migration`. It -distinguishes an authoritative record from a compatibility accessor, derived -projection, or transient renderer cache. Dual sources are called out rather -than presented as completed migration. +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 @@ -176,7 +176,7 @@ target. - **Desired endpoint:** derive and invalidate transient geometry from durable layout/topology plus viewport state; never serialize or CRDT-replicate caches. -## Summary of dual-source boundaries +## Dual-source boundaries 1. Node, link, and reroute class fields generally share store proxies and are compatibility views, not duplicate state. @@ -189,7 +189,7 @@ target. 5. Durable entity geometry is Yjs-backed; link/slot/hit-test geometry is a separate transient cache, not durable authority. -Design details: [Node Data Store](../node-data-store.md), +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 index b762bb97e62..8aec214b8a9 100644 --- a/docs/architecture/ecs/ecs-verification-audit.md +++ b/docs/architecture/ecs/ecs-verification-audit.md @@ -1,20 +1,19 @@ -# ECS Migration Verification Audit (PR 14246) +# 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 -This audit groups evidence by invariant rather than implementation unit. Grades -measure behavioral confidence: **Strong** includes integration/browser -evidence, **Good** covers meaningful boundaries, and **Partial** has a material -gap. +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 +### Store collisions: Strong Invariant: IDs cannot overwrite an incumbent entity, owner scopes remain isolated, and persisted collisions are normalized before registration. @@ -31,7 +30,7 @@ Representative evidence: - `browser_tests/tests/vueNodes/nodeStates/registration.spec.ts`: duplicate node IDs remain visible in separate graph scopes. -### Lifecycle teardown — Strong +### Lifecycle teardown: Strong Invariant: add/remove/clear transfers or releases store ownership exactly once, including reentrant and failing callbacks, without clearing sibling scopes. @@ -48,7 +47,7 @@ Representative evidence: - `src/renderer/extensions/vueNodes/layout/useNodeLayout.test.ts`: workflow replacement releases the originally retained graph. -### Subgraph identity — Strong +### Subgraph identity: Strong Invariant: one root allocates a unique runtime identity space while graph ownership partitions queries; shared definitions retain ownership until their @@ -66,7 +65,7 @@ Representative evidence: - `browser_tests/tests/subgraph/subgraphLinkIdentity.spec.ts`: link identity and reroute chains survive a real workflow load. -### Serialization — Strong +### Serialization: Strong Invariant: store-backed runtime state emits the existing wire contract, round-trips deterministically, and does not mutate caller-owned input while @@ -86,7 +85,7 @@ Representative evidence: `browser_tests/tests/subgraph/subgraphSerialization.spec.ts`: browser-level persistence checks. -### Layout renderer toggle — Good +### Layout renderer toggle: Good Invariant: canonical node, slot, group, and reroute geometry remains coherent across renderer changes and subgraph navigation. @@ -104,7 +103,7 @@ Representative evidence: `src/lib/litegraph/src/Reroute.store.test.ts`: legacy geometry views write through and refresh from the store. -### Widgets and promotions — Good +### 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 @@ -125,7 +124,7 @@ Representative evidence: `browser_tests/tests/vueNodes/widgets/widgetReactivity.spec.ts`: builder and renderer integration. -### Replacement — Good +### Replacement: Good Invariant: replacing a same-ID node transfers registered shell/layout state and live connectivity without allowing stale ownership to delete the replacement. @@ -141,7 +140,7 @@ Representative evidence: - `browser_tests/tests/nodeReplacement.spec.ts`: replacement behavior through the UI. -### Clipboard and insertion — Good +### Clipboard and insertion: Good Invariant: copy/paste and insertion mint identities, retain geometry and topology, and cannot hijack registrations owned by live entities. @@ -158,7 +157,7 @@ Representative evidence: - `browser_tests/tests/vueNodes/interactions/links/linkInteraction.spec.ts`: floating-reroute interaction. -### Badges — Good +### Badges: Good Invariant: badges are derived, reactive presentation data; pricing and source rows update without a second authoritative store. @@ -174,7 +173,7 @@ Representative evidence: - `src/renderer/extensions/vueNodes/composables/usePartitionedBadges.test.ts` and `src/lib/litegraph/src/nodeBadgeDraw.test.ts`: Vue and legacy projections. -### Performance — Partial +### Performance: Partial Invariant: central stores and compatibility views do not introduce observable hot-path regressions or reactive invalidation churn. @@ -189,7 +188,7 @@ Representative evidence: - `src/renderer/extensions/vueNodes/composables/useVueNodeResizeTracking.test.ts`: unchanged measurements avoid writes. -### Extension behavior — Good +### Extension behavior: Good Invariant: supported extension callbacks retain ordering and state visibility; deprecated slot mirrors warn, remain derived, and cannot mutate authority. @@ -209,41 +208,41 @@ Representative evidence: ## Prioritized missing behavioral scenarios -1. **P0 — undo/redo across a mixed transaction.** Replace or remove a node with +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 +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 +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 +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, +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 +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 +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 +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 +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. -## Conclusion +## Assessment PR 14246 has strong behavioral coverage for identity, lifecycle, and wire -compatibility. Its principal verification risks are cross-store undo/load +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. From b70a627bcffecd794dad969369bd467922aeae28 Mon Sep 17 00:00:00 2001 From: Alexander Brown Date: Sun, 16 Aug 2026 02:26:58 -0700 Subject: [PATCH 4/5] Update docs/architecture/output-slot-connectivity.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/architecture/output-slot-connectivity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/output-slot-connectivity.md b/docs/architecture/output-slot-connectivity.md index 2961a559993..86229ac8e72 100644 --- a/docs/architecture/output-slot-connectivity.md +++ b/docs/architecture/output-slot-connectivity.md @@ -4,7 +4,7 @@ Date: 2026-07-06 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/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 From 08ac4086ddd8956dae7aaa881b733238960fb8b4 Mon Sep 17 00:00:00 2001 From: Amp Date: Mon, 17 Aug 2026 08:25:40 +0000 Subject: [PATCH 5/5] docs: address ECS audit review Amp-Thread-ID: https://ampcode.com/threads/T-01a0080d-5de1-7308-b5a1-6f4c8a93cbe1 --- docs/architecture/ecs/ecs-migration-plan.md | 28 +++++++++---------- .../architecture/ecs/ecs-migration-summary.md | 5 ++-- .../ecs/ecs-state-authority-audit.md | 5 ++-- docs/architecture/output-slot-connectivity.md | 2 +- 4 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/architecture/ecs/ecs-migration-plan.md b/docs/architecture/ecs/ecs-migration-plan.md index 381efb8579d..86a8650f8c7 100644 --- a/docs/architecture/ecs/ecs-migration-plan.md +++ b/docs/architecture/ecs/ecs-migration-plan.md @@ -25,20 +25,20 @@ 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. Teardown handles reentrant and failing removal callbacks. | -| 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. | +| 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 diff --git a/docs/architecture/ecs/ecs-migration-summary.md b/docs/architecture/ecs/ecs-migration-summary.md index 6602f27f72a..758653a6f56 100644 --- a/docs/architecture/ecs/ecs-migration-summary.md +++ b/docs/architecture/ecs/ecs-migration-summary.md @@ -16,8 +16,9 @@ renderers, and extension-facing classes. - `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, transfers, and tears down migrated state across - root graphs and nested subgraph definitions. +- 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. diff --git a/docs/architecture/ecs/ecs-state-authority-audit.md b/docs/architecture/ecs/ecs-state-authority-audit.md index d5f03ab895f..66f120b1e0b 100644 --- a/docs/architecture/ecs/ecs-state-authority-audit.md +++ b/docs/architecture/ecs/ecs-state-authority-audit.md @@ -17,8 +17,9 @@ target. ## Node shell -- **Authority:** `useNodeDataStore`; one plain `NodeState` in a root-flat, - owner-indexed bucket. +- **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 diff --git a/docs/architecture/output-slot-connectivity.md b/docs/architecture/output-slot-connectivity.md index 86229ac8e72..07d83b352b4 100644 --- a/docs/architecture/output-slot-connectivity.md +++ b/docs/architecture/output-slot-connectivity.md @@ -1,7 +1,7 @@ # 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/ecs-migration-plan.md)