effectable 1.1.0 → 1.1.1-canary.1

package/build/component/GraphRuntime.js

@@ -354,8 +354,9 @@ class GraphRuntime {
         journal.rolledBack = true;
         const cleanupErrors = [];
         const instance = fiber.instance;
-        // 1. Disable scheduler hook
-        if (journal.schedulerHookAttached === true && instance !== null) {
+        // 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);
@@ -382,46 +383,29 @@ class GraphRuntime {
                 cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
             }
         }
-        // 4. Run failed-startup cleanup (if instance exists)
-        let cleanupPromise = null;
-        if (instance !== null) {
-            try {
-                const cleanupRes = fiber.engine.runFailedCleanup(instance, true);
-                if (isThenable(cleanupRes)) {
-                    cleanupPromise = cleanupRes;
-                }
-            }
-            catch (err) {
-                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
-            }
-        }
-        // 5. Destroy mounted children in reverse order.
+        // 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 destroyChildrenAndFinalize = () => {
+        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);
+                        return this.continueRollbackDestroyAsync(children, i, destroyRes, primaryError, cleanupErrors, fiber, instance);
                     }
                 }
                 catch (err) {
                     cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
                 }
             }
-            // 6. Finalize: attach cleanup errors to primary error
-            this.finalizeRollback(primaryError, cleanupErrors);
+            return this.finishRollbackParentCleanup(fiber, instance, primaryError, cleanupErrors);
         };
-        if (cleanupPromise !== null) {
-            return cleanupPromise.then(() => destroyChildrenAndFinalize(), (err) => {
-                cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
-                return destroyChildrenAndFinalize();
-            });
-        }
-        return destroyChildrenAndFinalize();
+        return destroyChildrenThenParentCleanup();
     }
     /**
      * Async continuation of rollback child destruction after one child's destroy returned a Promise.
@@ -431,9 +415,11 @@ class GraphRuntime {
      * @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) {
+    async continueRollbackDestroyAsync(children, lastIdx, pending, primaryError, cleanupErrors, fiber, instance) {
         try {
             await pending;
         }
@@ -451,6 +437,44 @@ class GraphRuntime {
                 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);
     }
     /**
@@ -486,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
@@ -608,16 +634,30 @@ class GraphRuntime {
         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 FAILED.
+     * 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.state === RUNTIME_STATE.FAILED || this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.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;
@@ -652,10 +692,20 @@ class GraphRuntime {
      */
     async flushDirtyFibers() {
         this.flushScheduled = false;
-        if (this.state === RUNTIME_STATE.FAILED || this.state === RUNTIME_STATE.UNMOUNTING || this.state === RUNTIME_STATE.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);
@@ -673,9 +723,17 @@ class GraphRuntime {
         }
         catch (error) {
             this.flushing = false;
-            // Notify error handler before fail-stop
+            // 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) {
-                this.onAutoReconcileError(error);
+                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));
@@ -694,9 +752,14 @@ class GraphRuntime {
                 this.dirtyFibers.clear();
                 this.dirtyFlushPassCount = 0;
                 const loopError = new Error(`GraphRuntime: dirty flush exceeded ${String(graphRuntime_constants_1.GRAPH_RUNTIME_MAX_DIRTY_FLUSH_PASSES)} passes (anti-loop)`);
-                // Notify error handler before fail-stop
+                // Same contract as the catch path: observer throw must not skip fail-stop.
                 if (this.onAutoReconcileError !== null) {
-                    this.onAutoReconcileError(loopError);
+                    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);
@@ -736,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;
@@ -748,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;
@@ -777,7 +840,13 @@ class GraphRuntime {
         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) {
@@ -1069,11 +1138,30 @@ class GraphRuntime {
                 mountedChildren: [],
             },
         };
-        // Recursively materialize children before running the parent's lifecycle
-        const 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');
+        // 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];
             let childRes;
@@ -1131,9 +1219,9 @@ class GraphRuntime {
             throw err;
         }
         // 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, startupRes);
         }
@@ -1225,8 +1313,8 @@ class GraphRuntime {
             }
             throw err;
         }
-        this.injectPreMountUpdateHook(instance, fiber);
-        const startupRes = engine.runStartup(instance);
+        // 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) {
             const error = resolved.error instanceof Error ? resolved.error : new Error(String(resolved.error));
@@ -1292,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));
         }
@@ -1328,7 +1418,7 @@ class GraphRuntime {
                 contextChanged = (0, context_1.injectContextFields)(instance, parentScope);
             }
             catch (error) {
-                const cleanupResult = this.runFiberFailedCleanup(current);
+                const cleanupResult = this.runFiberFailedCleanup(current, error);
                 if (isThenable(cleanupResult)) {
                     return cleanupResult.then(() => {
                         throw error;
@@ -1346,7 +1436,7 @@ class GraphRuntime {
                 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;
@@ -1355,15 +1445,16 @@ class GraphRuntime {
                 throw error;
             }
         }
-        // Commit ref transition: clear old ref if changed, bind new ref
-        this.commitRef(current.vnode.ref, instance, nextVnode.ref, 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;
@@ -1382,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.
@@ -1418,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;
@@ -1584,9 +1743,11 @@ class GraphRuntime {
                             nextChildren.push(isThenable(newRes) ? await newRes : newRes);
                         }
                     }
-                    // Destroy remaining unpaired current children (keyed)
+                    // 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);
+                        const d = this.destroyFiber(orphan, []);
                         if (isThenable(d)) {
                             await d;
                         }
@@ -1616,11 +1777,11 @@ class GraphRuntime {
                     }
                 }
             }
-            // Destroy remaining unpaired unkeyed children
+            // 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);
+                    const d = this.destroyFiber(orphan, []);
                     if (isThenable(d)) {
                         await d;
                     }