effectable 1.0.0 → 1.1.0-canary.10

package/build/component/GraphRuntime.js

@@ -5,10 +5,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).
@@ -41,6 +45,20 @@ function isThenable(value) {
         typeof value.then === 'function');
 }
 // ---------------------------------------------------------------------------
+// Runtime state machine
+// ---------------------------------------------------------------------------
+/**
+ * Runtime state literals.
+ * Private to GraphRuntime; reduced set without mounting/reconciling.
+ */
+const RUNTIME_STATE = {
+    IDLE: 'idle',
+    ACTIVE: 'active',
+    FAILED: 'failed',
+    UNMOUNTING: 'unmounting',
+    UNMOUNTED: 'unmounted',
+};
+// ---------------------------------------------------------------------------
 // GraphRuntime
 // ---------------------------------------------------------------------------
 /**
@@ -56,13 +74,32 @@ function isThenable(value) {
 class GraphRuntime {
     /** Current root fiber tree (current tree). */
     currentRoot = null;
-    /** Whether unmount has completed. */
-    unmounted = false;
     /**
      * Entry counter for {@link continueStableReconcileAsync} (test/debug probe).
      * Not reset automatically — compare before/after around reconcile.
      */
     stableAsyncContinueCount = 0;
+    /**
+     * 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).
+     */
+    _state = RUNTIME_STATE.IDLE;
+    /**
+     * Runtime state machine.
+     * IDLE → ACTIVE (on mount) → FAILED | UNMOUNTING → UNMOUNTED.
+     * FAILED is terminal: subsequent reconcile rejects, unmount is safe.
+     */
+    get state() {
+        return this._state;
+    }
+    set state(next) {
+        this._state = next;
+    }
+    /**
+     * Terminal error captured by failStop().
+     * Stored to reject later reconcile calls with the same error.
+     */
+    terminalError = null;
     /**
      * Runtime buses for auto-wiring decorators on nodes (optional, set in {@link GraphRuntime.mount}).
      */
@@ -102,10 +139,81 @@ class GraphRuntime {
      * Set via the fourth argument of {@link GraphRuntime.mount}.
      */
     onAutoReconcileError = null;
+    /**
+     * Operation queue: serializes reconcile and unmount.
+     * Each operation is a Promise-returning function executed sequentially.
+     */
+    operationQueue = [];
+    /**
+     * Whether an operation is currently running.
+     */
+    operationInProgress = false;
+    /**
+     * Cached unmount promise for concurrent unmount callers.
+     */
+    cachedUnmountPromise = null;
+    /**
+     * 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.
+     */
+    pendingTeardown = null;
     /**
      * Instances are created only via {@link GraphRuntime.mount}; direct `new GraphRuntime()` is unavailable externally.
      */
     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>}
+     */
+    failStop(error) {
+        // Idempotent: if already failed, skip
+        if (this.state === RUNTIME_STATE.FAILED || this.state === RUNTIME_STATE.UNMOUNTED) {
+            return;
+        }
+        this.state = RUNTIME_STATE.FAILED;
+        this.terminalError = error;
+        // Disable scheduling immediately
+        this.dirtyFibers.clear();
+        this.flushScheduled = false;
+        // Best-effort teardown of the current/partial graph
+        // MUST set currentRoot = null even if destroyFiber throws
+        if (this.currentRoot !== null) {
+            const root = this.currentRoot;
+            this.currentRoot = null;
+            // Collect cleanup errors during fail-stop (attach as rollbackErrors)
+            const cleanupErrors = [];
+            const destroyRes = this.destroyFiber(root, cleanupErrors);
+            if (isThenable(destroyRes)) {
+                // Async path: track pending teardown so unmount() can join
+                this.pendingTeardown = destroyRes
+                    .then(() => {
+                    if (cleanupErrors.length > 0) {
+                        error.rollbackErrors = cleanupErrors;
+                    }
+                })
+                    .finally(() => {
+                    this.pendingTeardown = null;
+                });
+                return this.pendingTeardown;
+            }
+            // Sync path: attach cleanup errors immediately
+            if (cleanupErrors.length > 0) {
+                error.rollbackErrors = cleanupErrors;
+            }
+        }
+    }
     /**
      * Auto-wires runtime-bus decorators onto the instance before {@link LifecycleEngine.runStartup}.
      *
@@ -136,6 +244,252 @@ class GraphRuntime {
         }
         delete fiber.effectableRuntimeBusDisposer;
     }
+    /**
+     * 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}
+     */
+    clearRefSafe(ref, expectedOwner) {
+        if (ref.current === expectedOwner) {
+            ref.current = null;
+        }
+    }
+    /**
+     * 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}
+     */
+    commitRef(previousRef, expectedPreviousOwner, nextRef, instance) {
+        // Clear previous ref if it's different from next (ref swap) or if next is undefined (ref removal)
+        if (previousRef !== undefined && previousRef !== nextRef && expectedPreviousOwner !== null) {
+            this.clearRefSafe(previousRef, expectedPreviousOwner);
+        }
+        // Bind next ref to instance (Component | null → unknown | null, no cast)
+        if (nextRef !== undefined) {
+            nextRef.current = instance;
+        }
+    }
+    /**
+     * 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}
+     */
+    finalizeFiberDestroy(fiber, collectErrors) {
+        // Dispose runtime bus wiring
+        if (collectErrors !== null) {
+            try {
+                this.disposeEffectableRuntimeBusWiring(fiber);
+            }
+            catch (err) {
+                collectErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        else {
+            this.disposeEffectableRuntimeBusWiring(fiber);
+        }
+        // Clear ref via commitRef (identity-safe clearing)
+        const ref = fiber.vnode.ref;
+        const instance = fiber.instance;
+        if (ref !== undefined && instance !== null) {
+            if (collectErrors !== null) {
+                try {
+                    this.commitRef(ref, instance, undefined, null);
+                }
+                catch (err) {
+                    collectErrors.push(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            else {
+                this.commitRef(ref, instance, undefined, null);
+            }
+        }
+        // Update lifecycle status
+        fiber.lifecycleStatus = fiber.engine.getStatus();
+    }
+    /**
+     * 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>}
+     */
+    rollbackFailedMaterialization(fiber, primaryError) {
+        const journal = fiber.constructionJournal;
+        if (journal === undefined || journal.rolledBack === true) {
+            return;
+        }
+        journal.rolledBack = true;
+        const cleanupErrors = [];
+        const instance = fiber.instance;
+        // 1. Disable scheduler hook (pre-mount buffer may be attached before children,
+        // before journal.schedulerHookAttached is set after successful startup).
+        if (instance !== null) {
+            try {
+                this.clearUpdateHook(instance);
+                this.dirtyFibers.delete(fiber);
+            }
+            catch (err) {
+                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        // 2. Dispose runtime bus registrations
+        if (journal.busWiringAttached === true) {
+            try {
+                this.disposeEffectableRuntimeBusWiring(fiber);
+            }
+            catch (err) {
+                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        // 3. Clear bound ref (identity-safe)
+        if (journal.refBound === true && fiber.vnode.ref !== undefined && journal.refOwner !== undefined) {
+            try {
+                this.commitRef(fiber.vnode.ref, journal.refOwner, undefined, null);
+            }
+            catch (err) {
+                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        // 4. Destroy mounted children in reverse order BEFORE parent onUnmount.
+        // Documented teardown contract is children → parent; running parent
+        // runFailedCleanup first left children alive during parent onUnmount and
+        // also called parent onUnmount when startup never ran (wasMounted=true).
+        // Pass cleanupErrors so nested destroy is best-effort: a throwing
+        // ref-clear/disposer on one grandchild must not skip remaining siblings.
+        // Those nodes were never attached to currentRoot, so failStop cannot reclaim them.
+        const destroyChildrenThenParentCleanup = () => {
+            const children = journal.mountedChildren;
+            for (let i = children.length - 1; i >= 0; i -= 1) {
+                try {
+                    const destroyRes = this.destroyFiber(children[i], cleanupErrors);
+                    if (isThenable(destroyRes)) {
+                        return this.continueRollbackDestroyAsync(children, i, destroyRes, primaryError, cleanupErrors, fiber, instance);
+                    }
+                }
+                catch (err) {
+                    cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            return this.finishRollbackParentCleanup(fiber, instance, primaryError, cleanupErrors);
+        };
+        return destroyChildrenThenParentCleanup();
+    }
+    /**
+     * 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
+     * @param {RuntimeFiber<unknown>} fiber - parent fiber being rolled back
+     * @param {Component<unknown, unknown> | null} instance - parent instance (for post-child cleanup)
+     * @returns {Promise<void>}
+     */
+    async continueRollbackDestroyAsync(children, lastIdx, pending, primaryError, cleanupErrors, fiber, instance) {
+        try {
+            await pending;
+        }
+        catch (err) {
+            cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+        }
+        for (let i = lastIdx - 1; i >= 0; i -= 1) {
+            try {
+                const destroyRes = this.destroyFiber(children[i], cleanupErrors);
+                if (isThenable(destroyRes)) {
+                    await destroyRes;
+                }
+            }
+            catch (err) {
+                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        const cleanupRes = this.finishRollbackParentCleanup(fiber, instance, primaryError, cleanupErrors);
+        if (isThenable(cleanupRes)) {
+            await cleanupRes;
+        }
+    }
+    /**
+     * After rollback destroyed children: run parent failed-cleanup only when startup
+     * actually ran (`status !== 'registered'`), then attach cleanup errors and rethrow.
+     *
+     * @param {RuntimeFiber<unknown>} fiber - parent fiber being rolled back
+     * @param {Component<unknown, unknown> | null} instance - parent instance
+     * @param {Error} primaryError - original materialization error
+     * @param {Error[]} cleanupErrors - accumulated cleanup errors
+     * @returns {void | Promise<void>} always rejects via {@link finalizeRollback}
+     */
+    finishRollbackParentCleanup(fiber, instance, primaryError, cleanupErrors) {
+        if (instance !== null) {
+            // `registered` ⇒ runStartup never entered; do not invent an onUnmount.
+            // `failed` (deferFailedCleanup) / other post-startup statuses ⇒ wasMounted.
+            const wasMounted = fiber.engine.getStatus() !== 'registered';
+            if (wasMounted) {
+                try {
+                    const cleanupRes = fiber.engine.runFailedCleanup(instance, true);
+                    if (isThenable(cleanupRes)) {
+                        return cleanupRes.then(() => {
+                            this.finalizeRollback(primaryError, cleanupErrors);
+                        }, (err) => {
+                            cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+                            this.finalizeRollback(primaryError, cleanupErrors);
+                        });
+                    }
+                }
+                catch (err) {
+                    cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            fiber.lifecycleStatus = fiber.engine.getStatus();
+        }
+        this.finalizeRollback(primaryError, cleanupErrors);
+    }
+    /**
+     * Attaches cleanup errors to the primary error and rethrows.
+     *
+     * @param {Error} primaryError - original materialization error
+     * @param {Error[]} cleanupErrors - cleanup errors
+     * @returns {never}
+     */
+    finalizeRollback(primaryError, cleanupErrors) {
+        if (cleanupErrors.length > 0) {
+            primaryError.rollbackErrors = cleanupErrors;
+        }
+        throw primaryError;
+    }
     /**
      * 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.
@@ -156,10 +510,12 @@ class GraphRuntime {
         }
     }
     /**
-     * Pre-mount buffer: `setState` during `onMount` cannot yet schedule reconcile
-     * (the live hook is injected after startup). Marks the fiber; {@link injectUpdateHook}
-     * after startup will call {@link scheduleUpdate}
-     * (deferred until the mount pass completes).
+     * Pre-mount buffer: `setState` cannot yet schedule reconcile (the live hook is
+     * injected after startup). Marks the fiber; {@link injectUpdateHook} after
+     * startup will call {@link scheduleUpdate} (deferred until the mount pass completes).
+     *
+     * Injected before child materialization so descendant `onMount` callbacks that
+     * `setState` an ancestor are buffered instead of silently dropped.
      *
      * @param {Component<unknown, unknown>} instance - instance before/during startup
      * @param {RuntimeFiber<unknown>} fiber - instance fiber
@@ -188,11 +544,13 @@ 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}
      */
     scheduleUpdate(fiber) {
-        if (this.unmounted) {
+        if (this.state === RUNTIME_STATE.FAILED || this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.UNMOUNTED) {
             return;
         }
         // If any ancestor is already queued — this fiber will be rebuilt as part of the ancestor
@@ -221,23 +579,93 @@ class GraphRuntime {
         // Schedule microtask dirty-flush
         this.scheduleDirtyFlushMicrotask();
     }
+    /**
+     * 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>}
+     */
+    async enqueueOperation(operation) {
+        return new Promise((resolve, reject) => {
+            this.operationQueue.push(async () => {
+                try {
+                    await operation();
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            if (!this.operationInProgress) {
+                // Start processing without awaiting to allow concurrent enqueuing
+                void this.processOperationQueue();
+            }
+        });
+    }
+    /**
+     * 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>}
+     */
+    async processOperationQueue() {
+        if (this.operationInProgress) {
+            return;
+        }
+        this.operationInProgress = true;
+        try {
+            while (this.operationQueue.length > 0) {
+                const operation = this.operationQueue.shift();
+                if (operation === undefined) {
+                    break;
+                }
+                try {
+                    await operation();
+                }
+                catch {
+                    // Error is already propagated to the caller via the promise wrapper
+                    // Continue processing the queue (don't poison it forever)
+                }
+            }
+        }
+        finally {
+            this.operationInProgress = false;
+        }
+        // setState during reconcile/unmount defers the microtask (operationInProgress).
+        // Kick once the queue is idle so the flush cannot overlap in-flight graph mutations.
+        if (this.dirtyFibers.size > 0 && this._state === RUNTIME_STATE.ACTIVE) {
+            this.scheduleDirtyFlushMicrotask();
+        }
+    }
     /**
      * Queues one dirty-flush microtask and publishes {@link activeFlush} for await from `reconcile`.
      *
+     * Skip scheduling when runtime is not ACTIVE (IDLE / FAILED / UNMOUNTING / UNMOUNTED),
+     * a public graph operation is in flight, or an async flush is already running. Callers that
+     * mutate `dirtyFibers` during those windows must kick this method again after the tree is
+     * ACTIVE and idle ({@link GraphRuntime.mount} / {@link processOperationQueue}), or after the
+     * outer flush finishes (end-of-pass kick).
+     *
      * @returns {void}
      */
     scheduleDirtyFlushMicrotask() {
-        if (this.flushScheduled || this.unmounted) {
+        // Skip while an async flush is in flight: setState during PLACE/onMount only
+        // enqueues dirtyFibers; the outer pass kicks the next microtask when it finishes.
+        if (this.flushScheduled ||
+            this.flushing ||
+            this.operationInProgress ||
+            this.state !== RUNTIME_STATE.ACTIVE) {
             return;
         }
         this.flushScheduled = true;
         const flushWork = new Promise((resolve) => {
             queueMicrotask(() => {
                 this.flushDirtyFibers()
-                    .catch((err) => {
-                    if (this.onAutoReconcileError !== null) {
-                        this.onAutoReconcileError(err);
-                    }
+                    .catch(() => {
+                    // Error already handled in flushDirtyFibers (onAutoReconcileError + fail-stop)
                 })
                     .finally(() => {
                     resolve();
@@ -257,21 +685,34 @@ 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>}
      */
     async flushDirtyFibers() {
         this.flushScheduled = false;
-        if (this.unmounted || this.flushing) {
+        if (this.state === RUNTIME_STATE.FAILED || this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.UNMOUNTED) {
             this.dirtyFibers.clear();
             return;
         }
+        // Re-entrant call while an async flush awaits: keep dirtyFibers for the outer
+        // pass's end-of-flush kick. Clearing here would silently drop setState updates.
+        if (this.flushing) {
+            return;
+        }
+        // Do not mutate the graph until mount has published currentRoot, and never
+        // overlap a public reconcile/unmount (those leave dirtyFibers queued).
+        if (this.state !== RUNTIME_STATE.ACTIVE || this.operationInProgress) {
+            return;
+        }
         this.dirtyFlushPassCount += 1;
         this.flushing = true;
         const snapshot = Array.from(this.dirtyFibers);
         this.dirtyFibers.clear();
         try {
             for (const fiber of snapshot) {
-                if (this.unmounted) {
+                if (this._state === RUNTIME_STATE.FAILED || this._state === RUNTIME_STATE.UNMOUNTING || this._state === RUNTIME_STATE.UNMOUNTED) {
                     break;
                 }
                 const res = this.reconcileDirtyFiber(fiber);
@@ -280,15 +721,52 @@ class GraphRuntime {
                 }
             }
         }
+        catch (error) {
+            this.flushing = false;
+            // Notify error handler before fail-stop. The hook must not be allowed to
+            // skip fail-stop: a throwing observer would leave the runtime ACTIVE with
+            // fibers already run through runFiberFailedCleanup, and the microtask
+            // `.catch(() => {})` would swallow the failure silently.
+            if (this.onAutoReconcileError !== null) {
+                try {
+                    this.onAutoReconcileError(error);
+                }
+                catch {
+                    // Observer/logging failures are non-fatal relative to fail-stop.
+                }
+            }
+            // Fail-stop on unrecoverable dirty-flush error
+            const failError = error instanceof Error ? error : new Error(String(error));
+            const failRes = this.failStop(failError);
+            if (isThenable(failRes)) {
+                await failRes;
+            }
+            throw failError;
+        }
         finally {
             this.flushing = false;
         }
         // If new dirty fibers appeared during flush — schedule the next pass
-        if (this.dirtyFibers.size > 0 && !this.unmounted) {
+        if (this.dirtyFibers.size > 0 && this.state === RUNTIME_STATE.ACTIVE) {
             if (this.dirtyFlushPassCount >= graphRuntime_constants_1.GRAPH_RUNTIME_MAX_DIRTY_FLUSH_PASSES) {
                 this.dirtyFibers.clear();
                 this.dirtyFlushPassCount = 0;
-                throw new Error(`GraphRuntime: dirty flush exceeded ${String(graphRuntime_constants_1.GRAPH_RUNTIME_MAX_DIRTY_FLUSH_PASSES)} passes (anti-loop)`);
+                const loopError = new Error(`GraphRuntime: dirty flush exceeded ${String(graphRuntime_constants_1.GRAPH_RUNTIME_MAX_DIRTY_FLUSH_PASSES)} passes (anti-loop)`);
+                // Same contract as the catch path: observer throw must not skip fail-stop.
+                if (this.onAutoReconcileError !== null) {
+                    try {
+                        this.onAutoReconcileError(loopError);
+                    }
+                    catch {
+                        // Observer/logging failures are non-fatal relative to fail-stop.
+                    }
+                }
+                // Fail-stop on loop limit
+                const failRes = this.failStop(loopError);
+                if (isThenable(failRes)) {
+                    await failRes;
+                }
+                throw loopError;
             }
             this.scheduleDirtyFlushMicrotask();
         }
@@ -306,7 +784,7 @@ class GraphRuntime {
      * @returns {void | Promise<void>}
      */
     reconcileDirtyFiber(fiber) {
-        if (this.unmounted) {
+        if (this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.UNMOUNTED) {
             return;
         }
         const instance = fiber.instance;
@@ -321,7 +799,7 @@ class GraphRuntime {
                 return childrenRes.then((nextChildren) => {
                     fiber.children = nextChildren;
                 }, (error) => {
-                    const cleanupResult = this.runFiberFailedCleanup(fiber);
+                    const cleanupResult = this.runFiberFailedCleanup(fiber, error);
                     if (isThenable(cleanupResult)) {
                         return cleanupResult.then(() => {
                             throw error;
@@ -333,7 +811,7 @@ class GraphRuntime {
             fiber.children = childrenRes;
         }
         catch (error) {
-            const cleanupResult = this.runFiberFailedCleanup(fiber);
+            const cleanupResult = this.runFiberFailedCleanup(fiber, error);
             if (isThenable(cleanupResult)) {
                 return cleanupResult.then(() => {
                     throw error;
@@ -359,63 +837,179 @@ class GraphRuntime {
         const rt = new GraphRuntime();
         rt.effectableRuntimeBuses = typeof runtimeBuses === 'undefined' ? null : runtimeBuses;
         rt.onAutoReconcileError = typeof onAutoReconcileError === 'function' ? onAutoReconcileError : null;
-        const res = rt.materialize(root, null, initialScope);
-        rt.currentRoot = isThenable(res) ? await res : res;
-        return rt;
+        try {
+            const res = rt.materialize(root, null, initialScope);
+            rt.currentRoot = isThenable(res) ? await res : res;
+            if (rt._state === RUNTIME_STATE.FAILED) {
+                throw rt.terminalError ?? new Error('[Effectable] GraphRuntime: terminal failure during mount.');
+            }
+            rt.state = RUNTIME_STATE.ACTIVE;
+            if (rt.dirtyFibers.size > 0) {
+                rt.scheduleDirtyFlushMicrotask();
+            }
+            return rt;
+        }
+        catch (error) {
+            // Fail-stop on unrecoverable mount error
+            const failError = error instanceof Error ? error : new Error(String(error));
+            const failRes = rt.failStop(failError);
+            if (isThenable(failRes)) {
+                await failRes;
+            }
+            throw failError;
+        }
     }
     /**
      * 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
      */
     async reconcile(nextTree) {
-        if (this.unmounted) {
-            throw new Error('[Effectable] GraphRuntime: reconcile attempted after unmount.');
-        }
-        if (this.currentRoot === null) {
-            throw new Error('[Effectable] GraphRuntime: currentRoot is not initialized.');
-        }
-        // Await the full dirty-flush chain (including re-schedule) — otherwise manual
-        // reconcile overlaps the snapshot auto-flush.
-        while (this.activeFlush !== null) {
-            await this.activeFlush;
-        }
-        if (this.unmounted) {
-            throw new Error('[Effectable] GraphRuntime: reconcile attempted after unmount.');
-        }
-        // Manual reconcile covers the whole tree from the root: cancel pending auto-flush
-        // to avoid double-mounting components from concurrent reconcile paths.
-        this.dirtyFibers.clear();
-        this.flushScheduled = false;
-        this.dirtyFlushPassCount = 0;
-        const res = this.reconcileFiber(this.currentRoot, nextTree, null, this.currentRoot.scope);
-        this.currentRoot = isThenable(res) ? await res : res;
+        // Reject immediately if unmount has started or completed
+        if (this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.UNMOUNTED) {
+            throw new Error('[Effectable] GraphRuntime: reconcile attempted after unmount started.');
+        }
+        // Reject immediately if runtime is in failed state
+        if (this.state === RUNTIME_STATE.FAILED) {
+            throw this.terminalError || new Error('[Effectable] GraphRuntime: reconcile attempted after terminal failure.');
+        }
+        // Serialize via operation queue
+        await this.enqueueOperation(async () => {
+            // Double-check after queue wait
+            if (this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.UNMOUNTED) {
+                throw new Error('[Effectable] GraphRuntime: reconcile attempted after unmount started.');
+            }
+            if (this.state === RUNTIME_STATE.FAILED) {
+                throw this.terminalError || new Error('[Effectable] GraphRuntime: reconcile attempted after terminal failure.');
+            }
+            if (this.currentRoot === null) {
+                throw new Error('[Effectable] GraphRuntime: currentRoot is not initialized.');
+            }
+            // Await the full dirty-flush chain (including re-schedule) — otherwise manual
+            // reconcile overlaps the snapshot auto-flush.
+            while (this.activeFlush !== null) {
+                await this.activeFlush;
+            }
+            if (this._state === RUNTIME_STATE.UNMOUNTING || this._state === RUNTIME_STATE.UNMOUNTED) {
+                throw new Error('[Effectable] GraphRuntime: reconcile attempted after unmount started.');
+            }
+            if (this._state === RUNTIME_STATE.FAILED) {
+                throw this.terminalError || new Error('[Effectable] GraphRuntime: reconcile attempted after terminal failure.');
+            }
+            // Manual reconcile covers the whole tree from the root: cancel pending auto-flush
+            // to avoid double-mounting components from concurrent reconcile paths.
+            this.dirtyFibers.clear();
+            this.flushScheduled = false;
+            this.dirtyFlushPassCount = 0;
+            try {
+                const res = this.reconcileFiber(this.currentRoot, nextTree, null, this.currentRoot.scope);
+                this.currentRoot = isThenable(res) ? await res : res;
+            }
+            catch (error) {
+                // Fail-stop on unrecoverable reconcile error
+                // Let failStop destroy current tree and null currentRoot (single owner)
+                const failError = error instanceof Error ? error : new Error(String(error));
+                const failRes = this.failStop(failError);
+                if (isThenable(failRes)) {
+                    await failRes;
+                }
+                throw failError;
+            }
+        });
     }
     /**
      * 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>}
      */
-    async unmount() {
-        if (this.unmounted) {
+    async unmount(options) {
+        const rejectOnCleanupError = options?.rejectOnCleanupError === true;
+        // If unmount is in progress, return the cached promise (HOLE 1)
+        // Must check BEFORE the UNMOUNTED early-return so concurrent callers join the in-flight unmount
+        if (this.cachedUnmountPromise !== null) {
+            return this.cachedUnmountPromise;
+        }
+        // If unmount already completed, return immediately
+        if (this.state === RUNTIME_STATE.UNMOUNTED) {
             return;
         }
-        this.unmounted = true;
-        if (this.currentRoot !== null) {
-            const d = this.destroyFiber(this.currentRoot);
-            if (isThenable(d)) {
-                await d;
-            }
-            this.currentRoot = null;
+        // Transition to UNMOUNTING state (reject new reconcile calls)
+        // If already FAILED, stay FAILED until unmount completes
+        if (this.state !== RUNTIME_STATE.FAILED) {
+            this.state = RUNTIME_STATE.UNMOUNTING;
         }
+        // Create and cache the unmount promise
+        this.cachedUnmountPromise = this.enqueueOperation(async () => {
+            // Double-check unmounted state
+            if (this.state === RUNTIME_STATE.UNMOUNTED) {
+                return;
+            }
+            // Cancel any pending dirty flush
+            this.dirtyFibers.clear();
+            this.flushScheduled = false;
+            // Wait for in-flight dirty flush to complete
+            if (this.activeFlush !== null) {
+                try {
+                    await this.activeFlush;
+                }
+                catch {
+                    // Ignore flush errors during unmount
+                }
+            }
+            // HOLE 1: stay UNMOUNTING during destroy (not UNMOUNTED)
+            // If already FAILED, keep FAILED state through destroy
+            // State transition to UNMOUNTED happens AFTER destroy completes
+            // If pendingTeardown is active (fail-stop in progress), await it first
+            if (this.pendingTeardown !== null) {
+                try {
+                    await this.pendingTeardown;
+                }
+                catch {
+                    // Ignore errors — they are already attached to the fail-stop primary error
+                }
+            }
+            if (this.currentRoot !== null) {
+                // Collect cleanup errors during unmount
+                const cleanupErrors = [];
+                const d = this.destroyFiber(this.currentRoot, cleanupErrors);
+                if (isThenable(d)) {
+                    await d;
+                }
+                this.currentRoot = null;
+                // HOLE 1: set UNMOUNTED only after destroy finishes
+                // Transition even if FAILED — unmount is the terminal operation
+                this.state = RUNTIME_STATE.UNMOUNTED;
+                // Reject with cleanup errors when requested
+                if (rejectOnCleanupError && cleanupErrors.length > 0) {
+                    if (cleanupErrors.length === 1) {
+                        throw cleanupErrors[0];
+                    }
+                    throw new AggregateError(cleanupErrors, 'Cleanup errors during unmount');
+                }
+            }
+            else {
+                // No root to destroy — transition to UNMOUNTED
+                this.state = RUNTIME_STATE.UNMOUNTED;
+            }
+        });
+        return this.cachedUnmountPromise;
     }
     /**
      * Returns the root component instance (for testing and introspection).
@@ -429,12 +1023,13 @@ class GraphRuntime {
         return this.currentRoot.instance;
     }
     /**
-     * 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}
      */
     isActive() {
-        return !this.unmounted;
+        return this.state === RUNTIME_STATE.ACTIVE;
     }
     /**
      * Readonly snapshot of the root fiber tree for test/debug introspection.
@@ -470,6 +1065,15 @@ class GraphRuntime {
     getStableAsyncContinueCount() {
         return this.stableAsyncContinueCount;
     }
+    /**
+     * Current runtime state.
+     * Test/debug probe; not a production API.
+     *
+     * @returns {RuntimeState} current state
+     */
+    getState() {
+        return this.state;
+    }
     /**
      * Builds a deep readonly {@link FiberInspectNode} from a RuntimeFiber.
      *
@@ -530,44 +1134,110 @@ class GraphRuntime {
             effectTag: types_1.FIBER_EFFECT_TAG.PLACE,
             engine,
             scope: parentScope,
+            constructionJournal: {
+                mountedChildren: [],
+            },
         };
-        // Recursively materialize children before running the parent's lifecycle
-        const childVnodes = this.getChildVnodes(instance, vnode.children);
-        const childFibers = [];
+        // Buffer setState before children mount: a descendant onMount may call
+        // ancestor setState (via props callback). Without this hook, that update
+        // mutates state but never schedules reconcile.
+        this.injectPreMountUpdateHook(instance, fiber);
+        // compose() / duplicate-key validation can throw after the pre-mount hook is
+        // attached. Roll back so the hook is cleared (otherwise the failed fiber is
+        // abandoned with a live SCHEDULE_UPDATE_HOOK and no teardown).
+        let childVnodes;
+        try {
+            childVnodes = this.getChildVnodes(instance, vnode.children);
+            // Validate unique keys BEFORE materialization (Option A: React v16.5 contract)
+            // Prevent partial tree construction when duplicate keys are present
+            this.validateUniqueKeys(childVnodes.map(vnode => ({ vnode, instance: null })), fiber, 'current');
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+            if (isThenable(rollbackRes)) {
+                return rollbackRes.then(() => {
+                    throw error;
+                });
+            }
+            throw error;
+        }
         for (let i = 0; i < childVnodes.length; i++) {
             const childVnode = childVnodes[i];
-            const childRes = this.materialize(childVnode, fiber, childScope);
+            let childRes;
+            try {
+                childRes = this.materialize(childVnode, fiber, childScope);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+                if (isThenable(rollbackRes)) {
+                    return rollbackRes.then(() => {
+                        throw error;
+                    });
+                }
+                throw error;
+            }
             if (isThenable(childRes)) {
                 // Hit an async child — continue the materialization tail in the async continuation.
-                return this.continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childFibers, childRes, i);
+                return this.continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childScope, childRes, i);
             }
-            childFibers.push(childRes);
+            fiber.constructionJournal.mountedChildren.push(childRes);
         }
-        fiber.children = childFibers;
-        // Bind ref to the instance
+        fiber.children = fiber.constructionJournal.mountedChildren;
+        // Bind ref to the instance (centralized via commitRef)
         if (vnode.ref !== undefined) {
-            vnode.ref.current = instance;
+            try {
+                this.commitRef(undefined, null, vnode.ref, instance);
+                fiber.constructionJournal.refBound = true;
+                fiber.constructionJournal.refOwner = instance;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+                if (isThenable(rollbackRes)) {
+                    return rollbackRes.then(() => {
+                        throw error;
+                    });
+                }
+                throw error;
+            }
+        }
+        try {
+            this.attachEffectableRuntimeBusWiring(instance, fiber);
+            if (fiber.effectableRuntimeBusDisposer !== undefined) {
+                fiber.constructionJournal.busWiringAttached = true;
+            }
+        }
+        catch (err) {
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, err instanceof Error ? err : new Error(String(err)));
+            if (isThenable(rollbackRes)) {
+                return rollbackRes.then(() => {
+                    throw err;
+                });
+            }
+            throw err;
         }
-        this.attachEffectableRuntimeBusWiring(instance, fiber);
         // Run lifecycle after all children are materialized.
-        // Pre-mount hook buffers setState from onMount until injectUpdateHook.
-        this.injectPreMountUpdateHook(instance, fiber);
-        const startupRes = engine.runStartup(instance);
+        // Pre-mount hook was injected before children (covers ancestor setState
+        // from descendant onMount and setState during this node's onMount).
+        const startupRes = engine.runStartup(instance, { deferFailedCleanup: true });
         if (isThenable(startupRes)) {
-            return this.finalizeMaterializeAsync(fiber, engine, childFibers, startupRes);
+            return this.finalizeMaterializeAsync(fiber, engine, startupRes);
         }
         if (!startupRes.ok) {
-            // Unmount already-mounted children when parent startup fails
-            const destroyChain = this.destroyChildrenOnError(childFibers);
-            if (isThenable(destroyChain)) {
-                return destroyChain.then(() => {
-                    throw startupRes.error;
+            const error = startupRes.error instanceof Error ? startupRes.error : new Error(String(startupRes.error));
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+            if (isThenable(rollbackRes)) {
+                return rollbackRes.then(() => {
+                    throw error;
                 });
             }
-            throw startupRes.error;
+            throw error;
         }
         fiber.lifecycleStatus = engine.getStatus();
         fiber.effectTag = null;
+        fiber.constructionJournal.schedulerHookAttached = true;
         this.injectUpdateHook(instance, fiber);
         return fiber;
     }
@@ -580,38 +1250,83 @@ 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>>}
      */
-    async continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childFibers, pending, pendingIdx) {
-        const childScope = this.buildChildScope(instance, fiber.scope);
-        childFibers.push(await pending);
+    async continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childScope, pending, pendingIdx) {
+        const journal = fiber.constructionJournal;
+        try {
+            journal.mountedChildren.push(await pending);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+            if (isThenable(rollbackRes)) {
+                await rollbackRes;
+            }
+            throw error;
+        }
         for (let i = pendingIdx + 1; i < childVnodes.length; i++) {
             const childVnode = childVnodes[i];
-            const childRes = this.materialize(childVnode, fiber, childScope);
-            childFibers.push(isThenable(childRes) ? await childRes : childRes);
+            try {
+                const childRes = this.materialize(childVnode, fiber, childScope);
+                const resolvedChild = isThenable(childRes) ? await childRes : childRes;
+                journal.mountedChildren.push(resolvedChild);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+                if (isThenable(rollbackRes)) {
+                    await rollbackRes;
+                }
+                throw error;
+            }
         }
-        fiber.children = childFibers;
+        fiber.children = journal.mountedChildren;
         if (vnode.ref !== undefined) {
-            vnode.ref.current = instance;
+            try {
+                this.commitRef(undefined, null, vnode.ref, instance);
+                journal.refBound = true;
+                journal.refOwner = instance;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+                if (isThenable(rollbackRes)) {
+                    await rollbackRes;
+                }
+                throw error;
+            }
         }
-        this.attachEffectableRuntimeBusWiring(instance, fiber);
-        this.injectPreMountUpdateHook(instance, fiber);
-        const startupRes = engine.runStartup(instance);
+        try {
+            this.attachEffectableRuntimeBusWiring(instance, fiber);
+            if (fiber.effectableRuntimeBusDisposer !== undefined) {
+                journal.busWiringAttached = true;
+            }
+        }
+        catch (err) {
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, err instanceof Error ? err : new Error(String(err)));
+            if (isThenable(rollbackRes)) {
+                await rollbackRes;
+            }
+            throw err;
+        }
+        // Pre-mount hook already injected at the start of materialize (before children).
+        const startupRes = engine.runStartup(instance, { deferFailedCleanup: true });
         const resolved = isThenable(startupRes) ? await startupRes : startupRes;
         if (!resolved.ok) {
-            for (const c of childFibers) {
-                const d = this.destroyFiber(c);
-                if (isThenable(d)) {
-                    await d;
-                }
+            const error = resolved.error instanceof Error ? resolved.error : new Error(String(resolved.error));
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+            if (isThenable(rollbackRes)) {
+                await rollbackRes;
             }
-            throw resolved.error;
+            throw error;
         }
         fiber.lifecycleStatus = engine.getStatus();
         fiber.effectTag = null;
+        journal.schedulerHookAttached = true;
         this.injectUpdateHook(instance, fiber);
         return fiber;
     }
@@ -621,59 +1336,28 @@ 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
      */
-    async finalizeMaterializeAsync(fiber, engine, childFibers, pendingStartup) {
+    async finalizeMaterializeAsync(fiber, engine, pendingStartup) {
         const result = await pendingStartup;
+        const journal = fiber.constructionJournal;
         if (!result.ok) {
-            for (const c of childFibers) {
-                const d = this.destroyFiber(c);
-                if (isThenable(d)) {
-                    await d;
-                }
+            const error = result.error instanceof Error ? result.error : new Error(String(result.error));
+            const rollbackRes = this.rollbackFailedMaterialization(fiber, error);
+            if (isThenable(rollbackRes)) {
+                await rollbackRes;
             }
-            throw result.error;
+            throw error;
         }
         fiber.lifecycleStatus = engine.getStatus();
         fiber.effectTag = null;
         if (fiber.instance !== null) {
+            journal.schedulerHookAttached = true;
             this.injectUpdateHook(fiber.instance, fiber);
         }
         return fiber;
     }
-    /**
-     * 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>}
-     */
-    destroyChildrenOnError(childFibers) {
-        let pending = null;
-        let startIdx = 0;
-        for (let i = 0; i < childFibers.length; i++) {
-            const d = this.destroyFiber(childFibers[i]);
-            if (isThenable(d)) {
-                pending = d;
-                startIdx = i + 1;
-                break;
-            }
-        }
-        if (pending === null) {
-            return;
-        }
-        return (async () => {
-            await pending;
-            for (let i = startIdx; i < childFibers.length; i++) {
-                const d = this.destroyFiber(childFibers[i]);
-                if (isThenable(d)) {
-                    await d;
-                }
-            }
-        })();
-    }
     // ---------------------------------------------------------------------------
     // Reconcile
     // ---------------------------------------------------------------------------
@@ -696,7 +1380,9 @@ class GraphRuntime {
         }
         // Type or key changed — destroy the old node, create a new one.
         // Sync fast-path if both destroy and materialize completed synchronously.
-        const destroyRes = this.destroyFiber(current);
+        // Collect cleanup errors (ref clear / disposer) so a throwing finalize cannot
+        // abort REPLACE and fail-stop the surviving tree — same best-effort contract as unmount.
+        const destroyRes = this.destroyFiber(current, []);
         if (isThenable(destroyRes)) {
             return destroyRes.then(() => this.materialize(nextVnode, parentFiber, parentScope));
         }
@@ -725,15 +1411,32 @@ class GraphRuntime {
         else {
             instance.props = nextVnode.props;
         }
+        // Re-inject context fields when parent scope changed
+        let contextChanged = false;
+        if (current.scope !== parentScope) {
+            try {
+                contextChanged = (0, context_1.injectContextFields)(instance, parentScope);
+            }
+            catch (error) {
+                const cleanupResult = this.runFiberFailedCleanup(current, error);
+                if (isThenable(cleanupResult)) {
+                    return cleanupResult.then(() => {
+                        throw error;
+                    });
+                }
+                throw error;
+            }
+        }
         // Build scope for child nodes (ContextProvider may have updated values)
         const childScope = this.buildChildScope(instance, parentScope);
-        // Call onUpdate if props changed
-        if (prevProps !== instance.props && current.engine.canUpdate()) {
+        // Call onUpdate if props or context changed (React 16.5 class-component style: one hook)
+        const propsChanged = prevProps !== instance.props;
+        if ((propsChanged || contextChanged) && current.engine.canUpdate()) {
             try {
                 instance.onUpdate(prevProps, instance.props);
             }
             catch (error) {
-                const cleanupResult = this.runFiberFailedCleanup(current);
+                const cleanupResult = this.runFiberFailedCleanup(current, error);
                 if (isThenable(cleanupResult)) {
                     return cleanupResult.then(() => {
                         throw error;
@@ -742,17 +1445,16 @@ class GraphRuntime {
                 throw error;
             }
         }
-        // Update ref
-        if (nextVnode.ref !== undefined) {
-            nextVnode.ref.current = instance;
-        }
         // Reconcile child nodes (sync fast-path if all children are sync).
+        // Ref commit is deferred to applyFiberUpdate so a compose()/child-reconcile
+        // failure cannot leave nextRef.current pointing at an instance that failStop
+        // will destroy while fiber.vnode.ref still holds the previous ref.
         let nextChildVnodes;
         try {
             nextChildVnodes = this.getChildVnodes(instance, nextVnode.children);
         }
         catch (error) {
-            const cleanupResult = this.runFiberFailedCleanup(current);
+            const cleanupResult = this.runFiberFailedCleanup(current, error);
             if (isThenable(cleanupResult)) {
                 return cleanupResult.then(() => {
                     throw error;
@@ -771,28 +1473,91 @@ class GraphRuntime {
         return current;
     }
     /**
-     * Fiber cleanup after update/compose error: `runFailedCleanup` + bus dispose.
-     * Does not leave the node in `ready`.
+     * Fiber cleanup after update/compose error: destroy children first (children → parent),
+     * then `runFailedCleanup` + bus dispose. Does not leave the node in `ready`.
+     * Child destroy / disposer errors are attached to `primaryError.rollbackErrors` when provided
+     * so fail-stop observability still surfaces them (children are no longer destroyed in failStop).
      *
      * @param {RuntimeFiber<unknown>} fiber - fiber that failed
+     * @param {unknown} [primaryError] - originating error to attach cleanup failures onto
      * @returns {void | Promise<void>}
      */
-    runFiberFailedCleanup(fiber) {
+    runFiberFailedCleanup(fiber, primaryError) {
         const instance = fiber.instance;
         if (instance === null) {
             return;
         }
         this.clearUpdateHook(instance);
         this.dirtyFibers.delete(fiber);
-        const cleanupResult = fiber.engine.runFailedCleanup(instance, true);
-        if (isThenable(cleanupResult)) {
-            return cleanupResult.then(() => {
-                this.disposeEffectableRuntimeBusWiring(fiber);
-                fiber.lifecycleStatus = fiber.engine.getStatus();
-            });
+        const cleanupErrors = [];
+        const children = fiber.children;
+        const attachCleanupErrors = () => {
+            if (cleanupErrors.length > 0 &&
+                primaryError instanceof Error) {
+                const existing = primaryError.rollbackErrors;
+                primaryError.rollbackErrors =
+                    existing !== undefined ? existing.concat(cleanupErrors) : cleanupErrors.slice();
+            }
+        };
+        const finishParent = () => {
+            fiber.children = [];
+            const cleanupResult = fiber.engine.runFailedCleanup(instance, true);
+            if (isThenable(cleanupResult)) {
+                return cleanupResult.then(() => {
+                    this.disposeEffectableRuntimeBusWiring(fiber);
+                    fiber.lifecycleStatus = fiber.engine.getStatus();
+                    attachCleanupErrors();
+                }, (err) => {
+                    cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+                    this.disposeEffectableRuntimeBusWiring(fiber);
+                    fiber.lifecycleStatus = fiber.engine.getStatus();
+                    attachCleanupErrors();
+                    throw err;
+                });
+            }
+            this.disposeEffectableRuntimeBusWiring(fiber);
+            fiber.lifecycleStatus = fiber.engine.getStatus();
+            attachCleanupErrors();
+        };
+        for (let i = children.length - 1; i >= 0; i -= 1) {
+            try {
+                const destroyRes = this.destroyFiber(children[i], cleanupErrors);
+                if (isThenable(destroyRes)) {
+                    return destroyRes.then(async () => {
+                        for (let j = i - 1; j >= 0; j -= 1) {
+                            try {
+                                const r = this.destroyFiber(children[j], cleanupErrors);
+                                if (isThenable(r)) {
+                                    await r;
+                                }
+                            }
+                            catch (err) {
+                                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+                            }
+                        }
+                        return finishParent();
+                    }, async (err) => {
+                        cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+                        for (let j = i - 1; j >= 0; j -= 1) {
+                            try {
+                                const r = this.destroyFiber(children[j], cleanupErrors);
+                                if (isThenable(r)) {
+                                    await r;
+                                }
+                            }
+                            catch (inner) {
+                                cleanupErrors.push(inner instanceof Error ? inner : new Error(String(inner)));
+                            }
+                        }
+                        return finishParent();
+                    });
+                }
+            }
+            catch (err) {
+                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
         }
-        this.disposeEffectableRuntimeBusWiring(fiber);
-        fiber.lifecycleStatus = fiber.engine.getStatus();
+        return finishParent();
     }
     /**
      * Applies the reconcile result to the current fiber in-place.
@@ -807,6 +1572,11 @@ class GraphRuntime {
      * @returns {void}
      */
     applyFiberUpdate(current, nextVnode, parentFiber, parentScope, nextChildren) {
+        const instance = current.instance;
+        if (instance !== null) {
+            // Commit ref only after compose + child reconcile succeeded.
+            this.commitRef(current.vnode.ref, instance, nextVnode.ref, instance);
+        }
         current.vnode = nextVnode;
         current.parentFiber = parentFiber;
         current.children = nextChildren;
@@ -869,17 +1639,60 @@ class GraphRuntime {
         }
         return resultSoFar;
     }
+    /**
+     * 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
+     */
+    validateUniqueKeys(items, parentFiber, listName) {
+        const seenKeys = new Set();
+        for (const item of items) {
+            const key = item.vnode.key;
+            if (key !== undefined) {
+                if (seenKeys.has(key)) {
+                    const parentInstance = parentFiber.instance;
+                    const parentName = parentInstance !== null
+                        ? parentInstance.constructor.name
+                        : 'unknown';
+                    throw new Error(`[Effectable] GraphRuntime: duplicate key "${key}" in ${listName} children of ${parentName}. ` +
+                        `Sibling keys must be unique (React v16.5 keyed child reconciliation contract). ` +
+                        `Duplicates cause undefined matching behavior and lifecycle leaks.`);
+                }
+                seenKeys.add(key);
+            }
+        }
+    }
     /**
      * 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
      */
     async reconcileChildrenFullDiff(currentChildren, nextVnodes, parentFiber, childScope) {
+        // Validate unique keys BEFORE any side effects (Option A: React v16.5 contract)
+        this.validateUniqueKeys(currentChildren, parentFiber, 'current');
+        this.validateUniqueKeys(nextVnodes.map(vnode => ({ vnode, instance: null })), parentFiber, 'next');
+        // HOLE 3: Build identity Set of currentChildren for rollback
+        // Used to distinguish UPDATE (same object) from PLACE/REPLACE (new object)
+        const currentChildrenSet = new Set(currentChildren);
         // Check for keyed children before creating a Map (6.06x speedup for unkeyed-only)
         let hasKeyedCurrent = false;
         for (const child of currentChildren) {
@@ -891,33 +1704,67 @@ class GraphRuntime {
         const unkeyedCurrent = [];
         const nextChildren = [];
         let unkeyedIdx = 0;
-        if (hasKeyedCurrent) {
-            // Acquire Map from the depth-indexed pool (5.1x: Map.clear() vs new Map())
-            const keyedCurrentMap = this.acquireKeyedMap();
-            this.reconcileDepth++;
-            try {
-                // Build map of current children by key (for keyed matching)
-                for (const child of currentChildren) {
-                    const key = child.vnode.key;
-                    if (key !== undefined) {
-                        keyedCurrentMap.set(key, child);
+        try {
+            if (hasKeyedCurrent) {
+                // Acquire Map from the depth-indexed pool (5.1x: Map.clear() vs new Map())
+                const keyedCurrentMap = this.acquireKeyedMap();
+                this.reconcileDepth++;
+                try {
+                    // Build map of current children by key (for keyed matching)
+                    for (const child of currentChildren) {
+                        const key = child.vnode.key;
+                        if (key !== undefined) {
+                            keyedCurrentMap.set(key, child);
+                        }
+                        else {
+                            unkeyedCurrent.push(child);
+                        }
                     }
-                    else {
-                        unkeyedCurrent.push(child);
+                    for (const nextVnode of nextVnodes) {
+                        const nextKey = nextVnode.key;
+                        if (nextKey !== undefined && keyedCurrentMap.has(nextKey)) {
+                            const currentFiber = keyedCurrentMap.get(nextKey);
+                            if (currentFiber === undefined) {
+                                throw new Error(`[Effectable] GraphRuntime: fiber with key "${nextKey}" not found in map.`);
+                            }
+                            keyedCurrentMap.delete(nextKey);
+                            const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
+                            nextChildren.push(isThenable(reconciledRes) ? await reconciledRes : reconciledRes);
+                        }
+                        else if (nextKey === undefined && unkeyedIdx < unkeyedCurrent.length) {
+                            const currentFiber = unkeyedCurrent[unkeyedIdx];
+                            unkeyedIdx += 1;
+                            const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
+                            nextChildren.push(isThenable(reconciledRes) ? await reconciledRes : reconciledRes);
+                        }
+                        else {
+                            // New node — PLACE
+                            const newRes = this.materialize(nextVnode, parentFiber, childScope);
+                            nextChildren.push(isThenable(newRes) ? await newRes : newRes);
+                        }
                     }
-                }
-                for (const nextVnode of nextVnodes) {
-                    const nextKey = nextVnode.key;
-                    if (nextKey !== undefined && keyedCurrentMap.has(nextKey)) {
-                        const currentFiber = keyedCurrentMap.get(nextKey);
-                        if (currentFiber === undefined) {
-                            throw new Error(`[Effectable] GraphRuntime: fiber with key "${nextKey}" not found in map.`);
+                    // Destroy remaining unpaired current children (keyed).
+                    // Best-effort: collect finalize errors so one throwing ref clear cannot
+                    // skip remaining orphans and fail-stop the whole runtime.
+                    for (const [, orphan] of keyedCurrentMap) {
+                        const d = this.destroyFiber(orphan, []);
+                        if (isThenable(d)) {
+                            await d;
                         }
-                        keyedCurrentMap.delete(nextKey);
-                        const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
-                        nextChildren.push(isThenable(reconciledRes) ? await reconciledRes : reconciledRes);
                     }
-                    else if (nextKey === undefined && unkeyedIdx < unkeyedCurrent.length) {
+                }
+                finally {
+                    this.reconcileDepth--;
+                    this.releaseKeyedMap();
+                }
+            }
+            else {
+                // No keyed children — skip Map, positional reconcile
+                for (const child of currentChildren) {
+                    unkeyedCurrent.push(child);
+                }
+                for (const nextVnode of nextVnodes) {
+                    if (unkeyedIdx < unkeyedCurrent.length) {
                         const currentFiber = unkeyedCurrent[unkeyedIdx];
                         unkeyedIdx += 1;
                         const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
@@ -929,49 +1776,48 @@ class GraphRuntime {
                         nextChildren.push(isThenable(newRes) ? await newRes : newRes);
                     }
                 }
-                // Destroy remaining unpaired current children (keyed)
-                for (const [, orphan] of keyedCurrentMap) {
-                    const d = this.destroyFiber(orphan);
+            }
+            // Destroy remaining unpaired unkeyed children (best-effort finalize errors).
+            for (let i = unkeyedIdx; i < unkeyedCurrent.length; i += 1) {
+                const orphan = unkeyedCurrent[i];
+                if (orphan !== undefined) {
+                    const d = this.destroyFiber(orphan, []);
                     if (isThenable(d)) {
                         await d;
                     }
                 }
             }
-            finally {
-                this.reconcileDepth--;
-                this.releaseKeyedMap();
-            }
-        }
-        else {
-            // No keyed children — skip Map, positional reconcile
-            for (const child of currentChildren) {
-                unkeyedCurrent.push(child);
-            }
-            for (const nextVnode of nextVnodes) {
-                if (unkeyedIdx < unkeyedCurrent.length) {
-                    const currentFiber = unkeyedCurrent[unkeyedIdx];
-                    unkeyedIdx += 1;
-                    const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
-                    nextChildren.push(isThenable(reconciledRes) ? await reconciledRes : reconciledRes);
+            return nextChildren;
+        }
+        catch (primaryError) {
+            // HOLE 3: On throw, clean up new fibers in nextChildren
+            // that are NOT identity-in currentChildren (PLACE/REPLACE results).
+            // Do not destroy UPDATE siblings (same object as current child).
+            const rollbackErrors = [];
+            for (const child of nextChildren) {
+                // Skip if this fiber is identity-in currentChildren (UPDATE, not PLACE/REPLACE)
+                if (currentChildrenSet.has(child)) {
+                    continue;
                 }
-                else {
-                    // New node — PLACE
-                    const newRes = this.materialize(nextVnode, parentFiber, childScope);
-                    nextChildren.push(isThenable(newRes) ? await newRes : newRes);
+                // New fiber (PLACE or REPLACE result) — destroy it
+                try {
+                    const d = this.destroyFiber(child, rollbackErrors);
+                    if (isThenable(d)) {
+                        await d;
+                    }
                 }
-            }
-        }
-        // Destroy remaining unpaired unkeyed children
-        for (let i = unkeyedIdx; i < unkeyedCurrent.length; i += 1) {
-            const orphan = unkeyedCurrent[i];
-            if (orphan !== undefined) {
-                const d = this.destroyFiber(orphan);
-                if (isThenable(d)) {
-                    await d;
+                catch (err) {
+                    rollbackErrors.push(err instanceof Error ? err : new Error(String(err)));
                 }
             }
+            // Attach rollback errors to primary error (pattern)
+            if (rollbackErrors.length > 0) {
+                const error = primaryError instanceof Error ? primaryError : new Error(String(primaryError));
+                error.rollbackErrors = rollbackErrors;
+                throw error;
+            }
+            throw primaryError;
         }
-        return nextChildren;
     }
     /**
      * Whether children are stable: same count, same type and key per position.
@@ -1031,17 +1877,31 @@ 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>}
      */
-    destroyFiber(fiber) {
+    destroyFiber(fiber, collectErrors = null) {
         const children = fiber.children;
         const n = children.length;
         // Sync recursion over children until the first async
         for (let i = 0; i < n; i++) {
-            const childRes = this.destroyFiber(children[i]);
-            if (isThenable(childRes)) {
-                return this.continueDestroyAsync(fiber, children, i, childRes);
+            try {
+                const childRes = this.destroyFiber(children[i], collectErrors);
+                if (isThenable(childRes)) {
+                    return this.continueDestroyAsync(fiber, children, i, childRes, collectErrors);
+                }
+            }
+            catch (err) {
+                // Best-effort cleanup — collect error and continue
+                if (collectErrors !== null) {
+                    collectErrors.push(err instanceof Error ? err : new Error(String(err)));
+                }
+                else {
+                    throw err;
+                }
             }
         }
         const instance = fiber.instance;
@@ -1052,15 +1912,17 @@ class GraphRuntime {
         this.dirtyFibers.delete(fiber);
         const shutdownRes = fiber.engine.runShutdown(instance);
         if (isThenable(shutdownRes)) {
-            return this.finalizeDestroyAsync(fiber, shutdownRes);
+            return this.finalizeDestroyAsync(fiber, shutdownRes, collectErrors);
         }
-        this.disposeEffectableRuntimeBusWiring(fiber);
-        // Clear ref after unmount
-        const ref = fiber.vnode.ref;
-        if (ref !== undefined) {
-            ref.current = null;
+        // Collect shutdown errors for observability
+        if (!shutdownRes.ok) {
+            if (collectErrors !== null) {
+                collectErrors.push(shutdownRes.error instanceof Error ? shutdownRes.error : new Error(String(shutdownRes.error)));
+            }
         }
-        fiber.lifecycleStatus = fiber.engine.getStatus();
+        // Always finalize the fiber even if shutdown failed (best-effort cleanup)
+        // finalizeFiberDestroy uses commitRef for identity-safe ref clearing
+        this.finalizeFiberDestroy(fiber, collectErrors);
     }
     /**
      * Async continuation of {@link destroyFiber} after one of the children returned a Promise.
@@ -1069,14 +1931,37 @@ 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>}
      */
-    async continueDestroyAsync(fiber, children, pendingIdx, pending) {
-        await pending;
+    async continueDestroyAsync(fiber, children, pendingIdx, pending, collectErrors = null) {
+        // Best-effort cleanup — await pending child
+        try {
+            await pending;
+        }
+        catch (err) {
+            if (collectErrors !== null) {
+                collectErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+            else {
+                throw err;
+            }
+        }
+        // Continue destroying remaining children even if previous failed
         for (let i = pendingIdx + 1; i < children.length; i++) {
-            const r = this.destroyFiber(children[i]);
-            if (isThenable(r)) {
-                await r;
+            try {
+                const r = this.destroyFiber(children[i], collectErrors);
+                if (isThenable(r)) {
+                    await r;
+                }
+            }
+            catch (err) {
+                if (collectErrors !== null) {
+                    collectErrors.push(err instanceof Error ? err : new Error(String(err)));
+                }
+                else {
+                    throw err;
+                }
             }
         }
         const instance = fiber.instance;
@@ -1087,14 +1972,21 @@ class GraphRuntime {
         this.dirtyFibers.delete(fiber);
         const shutdownRes = fiber.engine.runShutdown(instance);
         if (isThenable(shutdownRes)) {
-            await shutdownRes;
+            const asyncRes = await shutdownRes;
+            if (typeof asyncRes === 'object' && asyncRes !== null && 'ok' in asyncRes && !asyncRes.ok) {
+                if (collectErrors !== null) {
+                    collectErrors.push(asyncRes.error instanceof Error ? asyncRes.error : new Error(String(asyncRes.error)));
+                }
+            }
         }
-        this.disposeEffectableRuntimeBusWiring(fiber);
-        const ref = fiber.vnode.ref;
-        if (ref !== undefined) {
-            ref.current = null;
+        else if (!shutdownRes.ok) {
+            if (collectErrors !== null) {
+                collectErrors.push(shutdownRes.error instanceof Error ? shutdownRes.error : new Error(String(shutdownRes.error)));
+            }
         }
-        fiber.lifecycleStatus = fiber.engine.getStatus();
+        // Always finalize even if shutdown failed
+        // finalizeFiberDestroy uses commitRef for identity-safe ref clearing
+        this.finalizeFiberDestroy(fiber, collectErrors);
     }
     /**
      * Async finalization of {@link destroyFiber} when children were destroyed synchronously
@@ -1102,16 +1994,21 @@ class GraphRuntime {
      *
      * @param {RuntimeFiber<unknown>} fiber
      * @param {PromiseLike<unknown>} pendingShutdown
+     * @param {Error[] | null} collectErrors - array to collect cleanup errors
      * @returns {Promise<void>}
      */
-    async finalizeDestroyAsync(fiber, pendingShutdown) {
-        await pendingShutdown;
-        this.disposeEffectableRuntimeBusWiring(fiber);
-        const ref = fiber.vnode.ref;
-        if (ref !== undefined) {
-            ref.current = null;
+    async finalizeDestroyAsync(fiber, pendingShutdown, collectErrors = null) {
+        const shutdownRes = await pendingShutdown;
+        // Collect shutdown errors for observability
+        if (typeof shutdownRes === 'object' && shutdownRes !== null && 'ok' in shutdownRes && !shutdownRes.ok) {
+            if (collectErrors !== null) {
+                const err = shutdownRes.error;
+                collectErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
         }
-        fiber.lifecycleStatus = fiber.engine.getStatus();
+        // Always finalize even if shutdown failed
+        // finalizeFiberDestroy uses commitRef for identity-safe ref clearing
+        this.finalizeFiberDestroy(fiber, collectErrors);
     }
     // ---------------------------------------------------------------------------
     // Helpers