effectable 0.1.0 → 1.0.0-canary.2

package/README.md

@@ -1,10 +1,16 @@
 # Effectable
 
+[![npm](https://img.shields.io/npm/v/effectable.svg)](https://www.npmjs.com/package/effectable)
+[![CI](https://github.com/iamnikas/effectable/actions/workflows/ci.yml/badge.svg)](https://github.com/iamnikas/effectable/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/node/v/effectable.svg)](https://nodejs.org)
+[![ESLint](https://img.shields.io/badge/ESLint-10-4B32C3?logo=eslint&logoColor=white)](https://eslint.org)
+
 Reactive layer library: explicit bootstrap-path, Redux-RxJS store, base class with lifecycle, class-based HOC `connect`, and GraphRuntime with a declarative component tree (`h`, `compose`).
 
 ## Installation
 
-Requires **Node.js 18.18+** and **npm 9+**.
+Requires **Node.js 22+** and **npm 9+**.
 
 ```bash
 npm install effectable
@@ -42,7 +48,7 @@ Architecture overview: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 - Creates `EventBus`, `CommandBus`, `QueryBus`, and `HandleRegistry` when the caller does not pass them explicitly.
 - Mounts the root component via `GraphRuntime` (including ones wrapped with `connect`).
-- Returns a handle with `shutdown()` for graceful teardown: calls `onUnmount` in reverse order.
+- Returns a handle with `shutdown()` for graceful teardown: calls `onUnmount` children-first, then parent; siblings sequentially in compose order; async `onUnmount` is awaited. Default `shutdown()` is best-effort: it **resolves** even if cleanup or `onUnmount` fails. Pass `{ rejectOnCleanupError: true }` to reject with `Error` (one failure) or `AggregateError` (several). Same option and default as `GraphRuntime.unmount()`.
 - On startup failure, automatically cleans up already created runtime primitives.
 
 ### Bootstrap-path example
@@ -145,12 +151,24 @@ export const MyService = connect(store, mapStateToProps)(MyServiceRaw);
 - `effectable/connect` — connect, MapStateToProps, ConnectOptions
 - `effectable/runtime` — EventBus, CommandBus, QueryBus, HandleRegistry, BusDecorators (`wireRuntimeBuses`, **`wireRuntimeBusesAll`** — wire several handlers to the same bus set; process code usually reuses the same `commandBus` / `queryBus` / `eventBus` as `bootstrap(...).runtime`, without a second `createRuntimeBuses` / `HandleRegistry`)
 
+## Contributing
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint + lefthook). The same messages drive [semantic-release](https://semantic-release.app/) version bumps (`feat` → minor, `fix`/`perf` → patch, breaking → major).
+
+```text
+feat: add HandleRegistry autoRegister example
+fix: buffer setState during onMount
+docs: clarify bootstrap shutdown
+```
+
+After `npm ci`, lefthook installs a local `commit-msg` hook. CI also lint-checks PR commits. Prefer Conventional Commits for squash-merge titles too. Unused imports are an ESLint error, and the lefthook pre-commit hook runs `eslint --fix` automatically.
+
 ## Publishing
 
 - **Canary** (`develop`): `npm install effectable@canary`
-- **Stable** (`main` / tags `vX.Y.Z`): `npm install effectable`
+- **Stable** (`main`): `npm install effectable`
 
-Details: [docs/PUBLISHING.md](docs/PUBLISHING.md).
+Versions are bumped automatically by semantic-release in CI. Details: [docs/PUBLISHING.md](docs/PUBLISHING.md).
 
 ## License
 

package/build/bootstrap/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/bootstrap/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAwC,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAOzD,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAgIjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EACN,UAAU,SAAS,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,EAC1E,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY,EAE1C,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,GACnD,OAAO,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CA0ExE"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/bootstrap/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAwC,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAOzD,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAgIjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EACN,UAAU,SAAS,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,EAC1E,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY,EAE1C,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,GACnD,OAAO,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAkFxE"}

package/build/bootstrap/bootstrap.js

@@ -147,6 +147,11 @@ async function bootstrap(type, props, options) {
     // graphRuntime and rootInstance are guaranteed non-null at this point (running === true).
     const activeGraphRuntime = graphRuntime;
     const activeRootInstance = rootInstance;
+    /**
+     * Cached shutdown promise for concurrent shutdown callers.
+     * Ensures that multiple concurrent shutdown() calls await the same work.
+     */
+    let cachedShutdownPromise = null;
     return {
         name,
         rootInstance: activeRootInstance,
@@ -162,17 +167,18 @@ async function bootstrap(type, props, options) {
             }
             await activeGraphRuntime.reconcile((0, component_1.h)(type, props));
         },
-        async shutdown() {
+        async shutdown(options) {
+            if (cachedShutdownPromise !== null) {
+                return cachedShutdownPromise;
+            }
             if (!running) {
                 return;
             }
             running = false;
-            try {
-                await activeGraphRuntime.unmount();
-            }
-            finally {
+            cachedShutdownPromise = activeGraphRuntime.unmount(options).finally(() => {
                 clearOwnedRuntimePrimitives(runtime, owned);
-            }
+            });
+            return cachedShutdownPromise;
         },
     };
 }

package/build/bootstrap/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/bootstrap/bootstrap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/bootstrap/bootstrap.ts"],"names":[],"mappings":"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"}

package/build/bootstrap/types.d.ts

@@ -97,9 +97,15 @@ export interface BootstrapHandle<TComponent extends Component<unknown, TProps>,
     reconcile(): Promise<void>;
     /**
      * Idempotently shuts down the root runtime: unmounts the tree and clears owned buses.
+     * Accepts optional `rejectOnCleanupError` to make teardown errors observable.
+     * Default behavior remains non-breaking: resolves even with cleanup errors.
      *
+     * @param {object} [options] - shutdown options
+     * @param {boolean} [options.rejectOnCleanupError=false] - reject on cleanup errors
      * @returns {Promise<void>}
      */
-    shutdown(): Promise<void>;
+    shutdown(options?: {
+        rejectOnCleanupError?: boolean;
+    }): Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/build/bootstrap/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bootstrap/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;CAG9B,CAAC;AACX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,gCAAgC;;;CAGnC,CAAC;AACX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,wBAAwB,CAAC;IAC/B,SAAS,EAAE,6BAA6B,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CACzC,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACjC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAC/B,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,OAAO,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAC9B,UAAU,SAAS,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,EAC7C,MAAM,EACN,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,YAAY,EAAE,UAAU,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,EAAE,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,kDAAkD;IAClD,QAAQ,EAAE,4BAA4B,CAAC;IACvC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IACrB;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bootstrap/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;CAG9B,CAAC;AACX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,gCAAgC;;;CAGnC,CAAC;AACX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,wBAAwB,CAAC;IAC/B,SAAS,EAAE,6BAA6B,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CACzC,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACjC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAC/B,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,OAAO,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAC9B,UAAU,SAAS,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,EAC7C,MAAM,EACN,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,YAAY,EAAE,UAAU,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,EAAE,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,kDAAkD;IAClD,QAAQ,EAAE,4BAA4B,CAAC;IACvC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IACrB;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE"}

package/build/component/GraphRuntime.d.ts

@@ -4,10 +4,14 @@
  * Responsibilities:
  * - Materialize a VirtualServiceNode tree into real component instances (Fiber tree).
  * - Fiber-like reconcile: diff current vs next trees by key + type, assign effectTags.
+ *   Reconciliation mutates the live graph (not an isolated work-in-progress tree).
  * - Drive lifecycle via LifecycleEngine: startup in topological order (children before parent),
- *   shutdown in reverse order (parent before children).
+ *   shutdown in the same order (children before parent).
  * - Inject contexts (@UseContext) and bind refs on mount.
  * - Pass updated props into existing instances during reconcile.
+ * - Serialize all graph operations through a single operation queue.
+ * - Fail-stop on unrecoverable errors: mark runtime FAILED, reject later reconcile,
+ *   unmount stays safe.
  *
  * Current limitations:
  * - Work loop is synchronous (no priority lanes — next increment).
@@ -22,6 +26,22 @@ import type { FiberEffectTag, FiberInspectNode, VirtualServiceNode } from './typ
 import type { ContextScope } from './context';
 import type { RuntimeCommand, RuntimeEvent, RuntimeQuery } from '../runtime/types';
 import type { RuntimeBusesBundle } from '../runtime/BusDecorators';
+/**
+ * Runtime state literals.
+ * Private to GraphRuntime; reduced set without mounting/reconciling.
+ */
+declare const RUNTIME_STATE: {
+    readonly IDLE: "idle";
+    readonly ACTIVE: "active";
+    readonly FAILED: "failed";
+    readonly UNMOUNTING: "unmounting";
+    readonly UNMOUNTED: "unmounted";
+};
+/**
+ * Runtime state type derived from RUNTIME_STATE.
+ * Not exported from package index (internal diagnostic only).
+ */
+type RuntimeState = (typeof RUNTIME_STATE)[keyof typeof RUNTIME_STATE];
 /**
  * Runtime engine for a declarative component tree.
  *
@@ -35,13 +55,28 @@ import type { RuntimeBusesBundle } from '../runtime/BusDecorators';
 export declare class GraphRuntime {
     /** Current root fiber tree (current tree). */
     private currentRoot;
-    /** Whether unmount has completed. */
-    private unmounted;
     /**
      * Entry counter for {@link continueStableReconcileAsync} (test/debug probe).
      * Not reset automatically — compare before/after around reconcile.
      */
     private stableAsyncContinueCount;
+    /**
+     * Backing field for {@link GraphRuntime.state}. Writes and most reads go
+     * through the accessor; post-await re-reads use `_state` (TS 6 still narrows getters).
+     */
+    private _state;
+    /**
+     * Runtime state machine.
+     * IDLE → ACTIVE (on mount) → FAILED | UNMOUNTING → UNMOUNTED.
+     * FAILED is terminal: subsequent reconcile rejects, unmount is safe.
+     */
+    private get state();
+    private set state(value);
+    /**
+     * Terminal error captured by failStop().
+     * Stored to reject later reconcile calls with the same error.
+     */
+    private terminalError;
     /**
      * Runtime buses for auto-wiring decorators on nodes (optional, set in {@link GraphRuntime.mount}).
      */
@@ -81,10 +116,45 @@ export declare class GraphRuntime {
      * Set via the fourth argument of {@link GraphRuntime.mount}.
      */
     private onAutoReconcileError;
+    /**
+     * Operation queue: serializes reconcile and unmount.
+     * Each operation is a Promise-returning function executed sequentially.
+     */
+    private operationQueue;
+    /**
+     * Whether an operation is currently running.
+     */
+    private operationInProgress;
+    /**
+     * Cached unmount promise for concurrent unmount callers.
+     */
+    private cachedUnmountPromise;
+    /**
+     * Pending fail-stop teardown work.
+     * When failStop nulls currentRoot but destroy is async, this tracks the in-flight cleanup.
+     * unmount() must await this before concluding teardown is finished.
+     */
+    private pendingTeardown;
     /**
      * Instances are created only via {@link GraphRuntime.mount}; direct `new GraphRuntime()` is unavailable externally.
      */
     private constructor();
+    /**
+     * Fail-stop: mark the runtime as failed, disable scheduling, tear down the graph best-effort.
+     * After fail-stop:
+     * - state is FAILED
+     * - terminalError is set
+     * - currentRoot is null (even if destroyFiber throws)
+     * - later reconcile() rejects with the terminal error
+     * - unmount() is safe and joinable
+     *
+     * No failed reconcile leaves the runtime active with a partial graph.
+     * Primary-error rules: cleanup errors attached as rollbackErrors, never replace primary.
+     *
+     * @param {Error} error - unrecoverable error that triggered fail-stop
+     * @returns {void | Promise<void>}
+     */
+    private failStop;
     /**
      * Auto-wires runtime-bus decorators onto the instance before {@link LifecycleEngine.runStartup}.
      *
@@ -101,6 +171,84 @@ export declare class GraphRuntime {
      * @returns {void}
      */
     private disposeEffectableRuntimeBusWiring;
+    /**
+     * Identity-safe ref clearing: clears ref.current only if it still points to the expected owner.
+     * Prevents an old rollback from clearing a ref that a newer materialization already reused.
+     * No cast required (Component | null → unknown | null is assignable).
+     *
+     * @param {RefObject<unknown>} ref - ref object
+     * @param {Component<unknown, unknown>} expectedOwner - expected current owner
+     * @returns {void}
+     */
+    private clearRefSafe;
+    /**
+     * Centralized ref ownership transition.
+     * Handles every ref binding/clearing operation: add, remove, replace.
+     *
+     * Rules:
+     * - Clear previousRef only if it still points to expectedPreviousOwner (identity-safe).
+     * - Bind nextRef to instance if nextRef is provided.
+     * - previousRef and nextRef can be the same object (ref reuse) or different (ref swap).
+     * - Do not let an old disposer clear a newer owner.
+     *
+     * No casts: Component | null → unknown | null is assignable (widening).
+     *
+     * @param {RefObject<unknown> | undefined} previousRef - ref to clear (can be undefined if no previous ref)
+     * @param {Component<unknown, unknown> | null} expectedPreviousOwner - expected owner of previousRef (null if unknown)
+     * @param {RefObject<unknown> | undefined} nextRef - ref to bind to instance (can be undefined if removing ref)
+     * @param {Component<unknown, unknown> | null} instance - instance to bind nextRef to (null when clearing only)
+     * @returns {void}
+     */
+    private commitRef;
+    /**
+     * Finalize fiber destroy: dispose wiring, clear ref, update status.
+     * Collects errors when collectErrors is provided (best-effort cleanup).
+     * When collectErrors is null, errors are thrown immediately.
+     *
+     * Uses commitRef for identity-safe ref clearing.
+     *
+     * @param {RuntimeFiber<unknown>} fiber - fiber being finalized
+     * @param {Error[] | null} collectErrors - array to collect errors (null to throw)
+     * @returns {void}
+     */
+    private finalizeFiberDestroy;
+    /**
+     * Transactional rollback for failed fiber materialization.
+     * Releases acquired resources in reverse acquisition order:
+     * 1. disable scheduler hook
+     * 2. dispose runtime bus registrations
+     * 3. clear bound ref (identity-safe)
+     * 4. run failed-startup cleanup
+     * 5. destroy mounted children in reverse order
+     * 6. unlink the partial fiber
+     * Cleanup is best-effort: one failure does not skip remaining steps.
+     * Preserves the original materialization error; cleanup errors are attached.
+     * Rollback is idempotent.
+     *
+     * @param {RuntimeFiber<P>} fiber - fiber being rolled back
+     * @param {Error} primaryError - original materialization/startup error
+     * @returns {void | Promise<void>}
+     */
+    private rollbackFailedMaterialization;
+    /**
+     * Async continuation of rollback child destruction after one child's destroy returned a Promise.
+     *
+     * @param {RuntimeFiber<unknown>[]} children - mounted children
+     * @param {number} lastIdx - index of the last processed child
+     * @param {Promise<void>} pending - Promise from destroying the previous child
+     * @param {Error} primaryError - original materialization error
+     * @param {Error[]} cleanupErrors - accumulated cleanup errors
+     * @returns {Promise<void>}
+     */
+    private continueRollbackDestroyAsync;
+    /**
+     * Attaches cleanup errors to the primary error and rethrows.
+     *
+     * @param {Error} primaryError - original materialization error
+     * @param {Error[]} cleanupErrors - cleanup errors
+     * @returns {never}
+     */
+    private finalizeRollback;
     /**
      * Injects the scheduler hook onto the component instance after successful startup.
      * The hook is called from {@link Component.setState} and enqueues the fiber for automatic reconcile.
@@ -138,13 +286,34 @@ export declare class GraphRuntime {
      * - If an ancestor of the fiber is already queued → skip (ancestor covers the subtree).
      * - If descendants of the fiber are queued → remove them (fiber covers their subtrees).
      *
+     * Skip scheduling when runtime is FAILED.
+     *
      * @param {RuntimeFiber<unknown>} fiber - fiber whose subtree needs rebuild
      * @returns {void}
      */
     private scheduleUpdate;
+    /**
+     * Enqueues an operation and starts the queue processor if idle.
+     * Operations are executed sequentially; concurrent callers await the same in-flight operation.
+     * Serialize all graph mutations.
+     *
+     * @param {() => Promise<void>} operation - operation to enqueue
+     * @returns {Promise<void>}
+     */
+    private enqueueOperation;
+    /**
+     * Processes the operation queue: runs operations one at a time.
+     * Single serialized owner of tree mutations.
+     * Errors from individual operations are propagated to their callers but do not stop the queue.
+     *
+     * @returns {Promise<void>}
+     */
+    private processOperationQueue;
     /**
      * Queues one dirty-flush microtask and publishes {@link activeFlush} for await from `reconcile`.
      *
+     * Skip scheduling when runtime is FAILED.
+     *
      * @returns {void}
      */
     private scheduleDirtyFlushMicrotask;
@@ -154,6 +323,9 @@ export declare class GraphRuntime {
      * Guarded by the `flushing` flag against re-entrancy.
      * The chain of repeat passes is capped by {@link GRAPH_RUNTIME_MAX_DIRTY_FLUSH_PASSES}.
      *
+     * Respects state (UNMOUNTING/UNMOUNTED/FAILED) to cancel flush when unmount begins or failure occurs.
+     * On unrecoverable error, invokes onAutoReconcileError then fail-stops.
+     *
      * @returns {Promise<void>}
      */
     private flushDirtyFibers;
@@ -180,24 +352,35 @@ export declare class GraphRuntime {
     static mount<P = unknown>(root: VirtualServiceNode<P>, initialScope?: ContextScope, runtimeBuses?: RuntimeBusesBundle<RuntimeCommand, RuntimeQuery, RuntimeEvent>, onAutoReconcileError?: (err: unknown) => void): Promise<GraphRuntime>;
     /**
      * Reconciles against a new tree.
-     * Builds a work-in-progress tree, computes effectTags, applies changes:
+     * Diffs the current tree against the new one, computes effectTags, applies changes:
      * - PLACE: create and mount a new node
      * - UPDATE: update props on an existing instance, call onUpdate
      * - DELETE: unmount and destroy a node
      *
+     * All reconcile calls are serialized through the operation queue.
+     * Rejects with terminal error when runtime is FAILED.
+     *
      * @param {VirtualServiceNode<P>} nextTree - new virtual tree
      * @returns {Promise<void>}
-     * @throws {Error} if the runtime is already unmounted
+     * @throws {Error} if the runtime state is UNMOUNTING, UNMOUNTED, or FAILED
      */
     reconcile<P = unknown>(nextTree: VirtualServiceNode<P>): Promise<void>;
     /**
      * Fully unmounts the component tree.
-     * Calls onUnmount for each node in reverse order (children before parent) and
+     * Calls onUnmount for each node (children before parent) and
      * moves stages to destroyed via LifecycleEngine.
      *
+     * Unmount is serialized, cached promise returned for concurrent callers.
+     * Safe and joinable even when runtime is FAILED.
+     * Collects cleanup errors when `rejectOnCleanupError: true` is passed.
+     *
+     * @param {object} [options] - unmount options
+     * @param {boolean} [options.rejectOnCleanupError=false] - reject on cleanup errors
      * @returns {Promise<void>}
      */
-    unmount(): Promise<void>;
+    unmount(options?: {
+        rejectOnCleanupError?: boolean;
+    }): Promise<void>;
     /**
      * Returns the root component instance (for testing and introspection).
      *
@@ -205,7 +388,8 @@ export declare class GraphRuntime {
      */
     getRootInstance(): Component<unknown, unknown> | null;
     /**
-     * Whether the runtime is active (unmount has not been called).
+     * Whether the runtime is active (not failed and unmount has not been called).
+     * Returns false when state is FAILED.
      *
      * @returns {boolean}
      */
@@ -232,6 +416,13 @@ export declare class GraphRuntime {
      * @returns {number} accumulated counter
      */
     getStableAsyncContinueCount(): number;
+    /**
+     * Current runtime state.
+     * Test/debug probe; not a production API.
+     *
+     * @returns {RuntimeState} current state
+     */
+    getState(): RuntimeState;
     /**
      * Builds a deep readonly {@link FiberInspectNode} from a RuntimeFiber.
      *
@@ -263,7 +454,7 @@ export declare class GraphRuntime {
      * @param {LifecycleEngine} engine - lifecycle engine
      * @param {VirtualServiceNode<P>} vnode - virtual node
      * @param {VirtualServiceNode[]} childVnodes - all child vnodes
-     * @param {RuntimeFiber<unknown>[]} childFibers - already materialized child fibers
+     * @param {ContextScope} childScope - scope for child nodes
      * @param {Promise<RuntimeFiber<unknown>>} pending - Promise for the current child
      * @param {number} pendingIdx - index of the current child
      * @returns {Promise<RuntimeFiber<P>>}
@@ -275,19 +466,10 @@ export declare class GraphRuntime {
      * @template P node props type
      * @param {RuntimeFiber<P>} fiber - fiber of the subtree root node
      * @param {LifecycleEngine} engine - lifecycle engine for this node
-     * @param {RuntimeFiber<unknown>[]} childFibers - already mounted child fibers (for rollback on error)
      * @param {PromiseLike<import('./lifecycle').LifecycleTransitionResult>} pendingStartup - Promise of the `runStartup` result
      * @returns {Promise<RuntimeFiber<P>>} ready fiber, or rollback children and rethrow
      */
     private finalizeMaterializeAsync;
-    /**
-     * Unmounts already-mounted children when parent startup fails.
-     * Returns sync void if all demounts are sync, otherwise a Promise.
-     *
-     * @param {RuntimeFiber<unknown>[]} childFibers
-     * @returns {void | Promise<void>}
-     */
-    private destroyChildrenOnError;
     /**
      * Runs fiber-like reconcile for a single node.
      * If type and key match — UPDATE: update props, reconcile children.
@@ -362,15 +544,35 @@ export declare class GraphRuntime {
      * @returns {Promise<RuntimeFiber<unknown>[]>}
      */
     private continueStableReconcileAsync;
+    /**
+     * Validates that sibling keys are unique within a list.
+     * Follows React v16.5 keyed child reconciliation contract: duplicate keys are invalid.
+     * Throws a descriptive error including the duplicate key and parent component identity.
+     *
+     * @param {Array<{ vnode: { key?: string }; instance?: Component<unknown, unknown> | null }>} items - list of fibers or vnodes
+     * @param {RuntimeFiber<unknown>} parentFiber - parent fiber (for error message)
+     * @param {string} listName - "current" or "next" (for error message)
+     * @returns {void}
+     * @throws {Error} when duplicate keys are detected
+     */
+    private validateUniqueKeys;
     /**
      * Full-diff reconcile: keyed/unkeyed Map + destroy orphans.
      * Always async — internal branching is too complex for an efficient sync path.
      *
+     * Contract: Sibling keys must be unique (React v16.5 keyed child reconciliation).
+     * Validates both current and next children BEFORE any side effects.
+     * Throws deterministic error on duplicate keys to prevent lifecycle leaks.
+     *
+     * HOLE 3: On throw during PLACE, cleans up previously placed new nodes
+     * to prevent lifecycle leaks. Uses identity-safe check against currentChildren Set.
+     *
      * @param {RuntimeFiber<unknown>[]} currentChildren - current child fibers
      * @param {VirtualServiceNode[]} nextVnodes - new vnodes
      * @param {RuntimeFiber<unknown>} parentFiber - parent fiber
      * @param {ContextScope} childScope - children scope
      * @returns {Promise<RuntimeFiber<unknown>[]>}
+     * @throws {Error} when duplicate keys are detected in current or next children
      */
     private reconcileChildrenFullDiff;
     /**
@@ -406,7 +608,10 @@ export declare class GraphRuntime {
      * Returns `void` synchronously if the whole subtree is sync (up to 266x speedup
      * on an 85-node tree); otherwise a Promise. `await` works correctly with either union branch.
      *
+     * Collects cleanup errors via `collectErrors` parameter (best-effort cleanup).
+     *
      * @param {RuntimeFiber} fiber - fiber to destroy
+     * @param {Error[] | null} collectErrors - array to collect cleanup errors (null to throw immediately)
      * @returns {void | Promise<void>}
      */
     private destroyFiber;
@@ -417,6 +622,7 @@ export declare class GraphRuntime {
      * @param {Fiber[]} children - children list
      * @param {number} pendingIdx - index of the pending child
      * @param {PromiseLike<void>} pending - Promise from destroying the child
+     * @param {Error[] | null} collectErrors - array to collect cleanup errors
      * @returns {Promise<void>}
      */
     private continueDestroyAsync;
@@ -426,6 +632,7 @@ export declare class GraphRuntime {
      *
      * @param {RuntimeFiber<unknown>} fiber
      * @param {PromiseLike<unknown>} pendingShutdown
+     * @param {Error[] | null} collectErrors - array to collect cleanup errors
      * @returns {Promise<void>}
      */
     private finalizeDestroyAsync;
@@ -454,4 +661,5 @@ export declare class GraphRuntime {
  * @returns {FiberEffectTag}
  */
 export declare function makeFiberEffectTag(tag: FiberEffectTag): FiberEffectTag;
+export {};
 //# sourceMappingURL=GraphRuntime.d.ts.map

package/build/component/GraphRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GraphRuntime.d.ts","sourceRoot":"","sources":["../../src/component/GraphRuntime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GraphRuntime.d.ts","sourceRoot":"","sources":["../../src/component/GraphRuntime.ts"],"names":[],"mappings":"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"}