effectable 1.2.0-canary.4 → 1.2.0-canary.6

package/build/component/GraphRuntime.js

@@ -37,6 +37,7 @@ exports.makeFiberEffectTag = makeFiberEffectTag;
 const types_1 = require("./types");
 const lifecycle_1 = require("./lifecycle");
 const context_1 = require("./context");
+const refs_1 = require("./refs");
 const BusDecorators_1 = require("../runtime/BusDecorators");
 const graphRuntime_constants_1 = require("./graphRuntime.constants");
 /**
@@ -170,6 +171,12 @@ class GraphRuntime {
      * unmount() must await this before concluding teardown is finished.
      */
     pendingTeardown = null;
+    /**
+     * Imperative ref values bound for owners that expose `@UseImperativeHandle` methods.
+     * `commitRef` assigns a limited handle (not the Component instance) into `ref.current`;
+     * identity-safe clear must still recognize that handle as owned by the instance.
+     */
+    imperativeRefByOwner = new WeakMap();
     /**
      * Instances are created only via {@link GraphRuntime.mount}; direct `new GraphRuntime()` is unavailable externally.
      */
@@ -257,18 +264,47 @@ class GraphRuntime {
         delete fiber.effectableRuntimeBusDisposer;
     }
     /**
-     * Identity-safe ref clearing: clears ref.current only if it still points to the expected owner.
+     * Builds the value assigned to `ref.current` for a mounted instance.
+     *
+     * When the constructor declares `@UseImperativeHandle` methods, only those methods
+     * are exposed (bound to the instance) — matching the refs.ts / CONCEPT contract.
+     * Without an allowlist, the full instance is assigned (legacy escape hatch).
+     *
+     * @param {Component<unknown, unknown>} instance - mounted component instance
+     * @returns {unknown} instance or limited imperative handle object
+     */
+    resolveRefCurrentValue(instance) {
+        const methods = (0, refs_1.getImperativeHandleMethods)(instance.constructor);
+        if (methods.length === 0) {
+            this.imperativeRefByOwner.delete(instance);
+            return instance;
+        }
+        const handle = Object.create(null);
+        for (const { methodKey } of methods) {
+            const fn = instance[methodKey];
+            if (typeof fn !== 'function') {
+                throw new Error(`[Effectable.GraphRuntime] @UseImperativeHandle method is not a function: ${String(methodKey)}`);
+            }
+            handle[methodKey] = fn.bind(instance);
+        }
+        this.imperativeRefByOwner.set(instance, handle);
+        return handle;
+    }
+    /**
+     * Identity-safe ref clearing: clears ref.current only if it still points to the expected owner
+     * (full instance) or the limited imperative handle previously bound for that 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) {
+        const boundHandle = this.imperativeRefByOwner.get(expectedOwner);
+        if (ref.current === expectedOwner || (boundHandle !== undefined && ref.current === boundHandle)) {
             ref.current = null;
         }
+        this.imperativeRefByOwner.delete(expectedOwner);
     }
     /**
      * Centralized ref ownership transition.
@@ -276,12 +312,10 @@ class GraphRuntime {
      *
      * Rules:
      * - Clear previousRef only if it still points to expectedPreviousOwner (identity-safe).
-     * - Bind nextRef to instance if nextRef is provided.
+     * - Bind nextRef to the instance, or to a limited `@UseImperativeHandle` surface when declared.
      * - 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)
@@ -293,9 +327,27 @@ class GraphRuntime {
         if (previousRef !== undefined && previousRef !== nextRef && expectedPreviousOwner !== null) {
             this.clearRefSafe(previousRef, expectedPreviousOwner);
         }
-        // Bind next ref to instance (Component | null → unknown | null, no cast)
+        // Bind next ref: limited handle when @UseImperativeHandle is present, else full instance.
+        // Custom setters may assign `current` then throw. Without a catch, UPDATE ref-swap
+        // leaves the new ref holding the instance/handle while `fiber.vnode.ref` still points at
+        // the previous ref object — fail-stop finalize clears only the old ref (zombie nextRef).
+        // Materialize assign-then-throw is covered by journal.refBound (#96/#98); this path covers
+        // the UPDATE swap hole and is a safe no-op when the setter never assigned.
         if (nextRef !== undefined) {
-            nextRef.current = instance;
+            try {
+                nextRef.current = instance === null ? null : this.resolveRefCurrentValue(instance);
+            }
+            catch (error) {
+                if (instance !== null) {
+                    try {
+                        this.clearRefSafe(nextRef, instance);
+                    }
+                    catch {
+                        // Best-effort: do not mask the original setter error.
+                    }
+                }
+                throw error;
+            }
         }
     }
     /**
@@ -345,7 +397,7 @@ class GraphRuntime {
      * Transactional rollback for failed fiber materialization.
      * Releases acquired resources in reverse acquisition order:
      * 1. disable scheduler hook
-     * 2. destroy mounted children in reverse order
+     * 2. destroy mounted children in compose order (same as {@link destroyFiber})
      * 3. run failed-startup cleanup (parent onUnmount when startup ran)
      * 4. dispose runtime bus registrations
      * 5. clear bound ref (identity-safe)
@@ -382,16 +434,18 @@ class GraphRuntime {
                 cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
             }
         }
-        // 2. Destroy mounted children in reverse order BEFORE parent onUnmount / bus / ref.
-        // Documented teardown contract is children → parent; onUnmount was already after
-        // children, but bus dispose + ref clear still ran ahead of child destroy — child
-        // onUnmount could observe a nulled parent ref / dead parent bus subscriptions.
+        // 2. Destroy mounted children in compose order BEFORE parent onUnmount / bus / ref.
+        // Documented teardown contract is children → parent with siblings in compose
+        // order (matches destroyFiber / README shutdown). Reverse sibling order made
+        // failure-path onUnmount observe a different live-sibling set than clean unmount.
+        // Children must also run before bus dispose + ref clear so child onUnmount still
+        // sees a live parent ref / parent @On* subscriptions.
         // 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) {
+            for (let i = 0; i < children.length; i += 1) {
                 try {
                     const destroyRes = this.destroyFiber(children[i], cleanupErrors);
                     if (isThenable(destroyRes)) {
@@ -410,7 +464,7 @@ class GraphRuntime {
      * 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 {number} pendingIdx - index of the child whose destroy is pending
      * @param {Promise<void>} pending - Promise from destroying the previous child
      * @param {Error} primaryError - original materialization error
      * @param {Error[]} cleanupErrors - accumulated cleanup errors
@@ -418,14 +472,15 @@ class GraphRuntime {
      * @param {Component<unknown, unknown> | null} instance - parent instance (for post-child cleanup)
      * @returns {Promise<void>}
      */
-    async continueRollbackDestroyAsync(children, lastIdx, pending, primaryError, cleanupErrors, fiber, instance) {
+    async continueRollbackDestroyAsync(children, pendingIdx, 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) {
+        // Remaining siblings in compose order (pendingIdx+1 … n-1), matching destroyFiber.
+        for (let i = pendingIdx + 1; i < children.length; i += 1) {
             try {
                 const destroyRes = this.destroyFiber(children[i], cleanupErrors);
                 if (isThenable(destroyRes)) {
@@ -1138,6 +1193,221 @@ class GraphRuntime {
     // ---------------------------------------------------------------------------
     // Materialize
     // ---------------------------------------------------------------------------
+    /**
+     * Runs deferred {@link LifecycleEngine.runStartup} for a fiber subtree in
+     * children→parent order (siblings in compose order).
+     *
+     * Call only after the subtree (and any later siblings that must observe
+     * publishes) have completed bus wiring. Idempotent for fibers that already
+     * started.
+     *
+     * @param {RuntimeFiber<unknown>} fiber - subtree root
+     * @returns {void | Promise<void>}
+     */
+    flushDeferredLifecycleTree(fiber) {
+        const children = fiber.children;
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            const childFlush = this.flushDeferredLifecycleTree(child);
+            if (isThenable(childFlush)) {
+                return this.continueFlushDeferredLifecycleAsync(fiber, children, i, childFlush);
+            }
+        }
+        return this.runDeferredLifecycleIfNeeded(fiber);
+    }
+    /**
+     * Async continuation of {@link flushDeferredLifecycleTree} after a child flush returns a Promise.
+     *
+     * @param {RuntimeFiber<unknown>} fiber - subtree root
+     * @param {RuntimeFiber<unknown>[]} children - child fibers
+     * @param {number} pendingIdx - index of the pending child
+     * @param {PromiseLike<void>} pending - pending child flush
+     * @returns {Promise<void>}
+     */
+    async continueFlushDeferredLifecycleAsync(fiber, children, pendingIdx, pending) {
+        await pending;
+        for (let i = pendingIdx + 1; i < children.length; i++) {
+            const childFlush = this.flushDeferredLifecycleTree(children[i]);
+            if (isThenable(childFlush)) {
+                await childFlush;
+            }
+        }
+        const selfRes = this.runDeferredLifecycleIfNeeded(fiber);
+        if (isThenable(selfRes)) {
+            await selfRes;
+        }
+    }
+    /**
+     * Runs startup + update-hook injection when {@link FiberConstructionJournal.lifecycleDeferred}
+     * is set; no-op otherwise.
+     *
+     * @param {RuntimeFiber<unknown>} fiber - fiber to start
+     * @returns {void | Promise<void>}
+     */
+    runDeferredLifecycleIfNeeded(fiber) {
+        const journal = fiber.constructionJournal;
+        if (journal === undefined || journal.lifecycleDeferred !== true) {
+            return;
+        }
+        const instance = fiber.instance;
+        if (instance === null) {
+            journal.lifecycleDeferred = false;
+            return;
+        }
+        const startupRes = fiber.engine.runStartup(instance, { deferFailedCleanup: true });
+        if (isThenable(startupRes)) {
+            return this.finalizeDeferredLifecycleAsync(fiber, startupRes);
+        }
+        if (!startupRes.ok) {
+            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 error;
+        }
+        journal.lifecycleDeferred = false;
+        fiber.lifecycleStatus = fiber.engine.getStatus();
+        fiber.effectTag = null;
+        journal.schedulerHookAttached = true;
+        this.injectUpdateHook(instance, fiber);
+    }
+    /**
+     * Async path for {@link runDeferredLifecycleIfNeeded} when startup returns a Promise.
+     *
+     * @param {RuntimeFiber<unknown>} fiber - fiber being started
+     * @param {PromiseLike<import('./lifecycle').LifecycleTransitionResult>} pendingStartup - pending startup
+     * @returns {Promise<void>}
+     */
+    async finalizeDeferredLifecycleAsync(fiber, pendingStartup) {
+        const result = await pendingStartup;
+        const journal = fiber.constructionJournal;
+        const instance = fiber.instance;
+        if (!result.ok) {
+            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 error;
+        }
+        journal.lifecycleDeferred = false;
+        fiber.lifecycleStatus = fiber.engine.getStatus();
+        fiber.effectTag = null;
+        if (instance !== null) {
+            journal.schedulerHookAttached = true;
+            this.injectUpdateHook(instance, fiber);
+        }
+    }
+    /**
+     * After bus wiring: either defer lifecycle (sibling/parent batching) or flush
+     * deferred children and run this fiber's startup.
+     *
+     * @template P node props type
+     * @param {RuntimeFiber<P>} fiber - fiber that just finished wiring
+     * @param {Component<unknown, P>} instance - component instance
+     * @param {LifecycleEngine} engine - lifecycle engine
+     * @param {boolean} deferLifecycle - when true, skip startup until a parent flush
+     * @returns {RuntimeFiber<P> | Promise<RuntimeFiber<P>>}
+     */
+    completeMaterializeAfterWiring(fiber, instance, engine, deferLifecycle) {
+        const journal = fiber.constructionJournal;
+        if (deferLifecycle) {
+            journal.lifecycleDeferred = true;
+            return fiber;
+        }
+        // Children were materialized with deferLifecycle=true — start them (and their
+        // subtrees) before this node's onMount so sibling/parent @On* handlers exist.
+        // If a deferred sibling fails during flush after an earlier sibling started,
+        // roll back this parent (destroys all mounted children) — same contract as
+        // the pre-defer depth-first materialize catch around each child.
+        try {
+            const children = fiber.children;
+            for (let i = 0; i < children.length; i++) {
+                const childFlush = this.flushDeferredLifecycleTree(children[i]);
+                if (isThenable(childFlush)) {
+                    return this.continueCompleteMaterializeAfterWiringAsync(fiber, instance, engine, children, i, childFlush);
+                }
+            }
+            return this.runMaterializeStartup(fiber, instance, engine);
+        }
+        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;
+        }
+    }
+    /**
+     * Async continuation after a deferred child flush during materialize completion.
+     *
+     * @template P node props type
+     * @param {RuntimeFiber<P>} fiber - parent fiber
+     * @param {Component<unknown, P>} instance - parent instance
+     * @param {LifecycleEngine} engine - parent engine
+     * @param {RuntimeFiber<unknown>[]} children - child fibers
+     * @param {number} pendingIdx - pending child index
+     * @param {PromiseLike<void>} pending - pending flush
+     * @returns {Promise<RuntimeFiber<P>>}
+     */
+    async continueCompleteMaterializeAfterWiringAsync(fiber, instance, engine, children, pendingIdx, pending) {
+        try {
+            await pending;
+            for (let i = pendingIdx + 1; i < children.length; i++) {
+                const childFlush = this.flushDeferredLifecycleTree(children[i]);
+                if (isThenable(childFlush)) {
+                    await childFlush;
+                }
+            }
+            return this.runMaterializeStartup(fiber, instance, engine);
+        }
+        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;
+        }
+    }
+    /**
+     * Runs startup for a fiber that is completing materialize (not deferred).
+     *
+     * @template P node props type
+     * @param {RuntimeFiber<P>} fiber - fiber
+     * @param {Component<unknown, P>} instance - instance
+     * @param {LifecycleEngine} engine - engine
+     * @returns {RuntimeFiber<P> | Promise<RuntimeFiber<P>>}
+     */
+    runMaterializeStartup(fiber, instance, engine) {
+        const startupRes = engine.runStartup(instance, { deferFailedCleanup: true });
+        if (isThenable(startupRes)) {
+            return this.finalizeMaterializeAsync(fiber, engine, startupRes);
+        }
+        if (!startupRes.ok) {
+            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 error;
+        }
+        fiber.lifecycleStatus = engine.getStatus();
+        fiber.effectTag = null;
+        fiber.constructionJournal.schedulerHookAttached = true;
+        this.injectUpdateHook(instance, fiber);
+        return fiber;
+    }
     /**
      * Creates a RuntimeFiber for a virtual node: instantiates the component,
      * injects contexts, builds the child scope (for ContextProvider),
@@ -1150,9 +1420,11 @@ class GraphRuntime {
      * @param {VirtualServiceNode<P>} vnode - virtual node
      * @param {RuntimeFiber | null} parentFiber - parent fiber
      * @param {ContextScope} parentScope - parent scope
+     * @param {boolean} [deferLifecycle=false] - when true, wire buses but defer onMount
+     *   until {@link flushDeferredLifecycleTree} (used for sibling batching)
      * @returns {RuntimeFiber<P> | Promise<RuntimeFiber<P>>}
      */
-    materialize(vnode, parentFiber, parentScope) {
+    materialize(vnode, parentFiber, parentScope, deferLifecycle = false) {
         const engine = new lifecycle_1.LifecycleEngine();
         // Constructor is stored as ComponentConstructor<unknown> for covariance,
         // but invoked with concrete props P. The cast is safe: P extends unknown.
@@ -1209,11 +1481,32 @@ class GraphRuntime {
             }
             throw error;
         }
+        // Wire parent buses BEFORE children materialize/onMount. Children run onMount while
+        // descending; if the parent is not subscribed yet, child publishes to @OnEvent /
+        // @OnCommand on the parent are silently dropped (mirror of #80 teardown order).
+        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;
+        }
         for (let i = 0; i < childVnodes.length; i++) {
             const childVnode = childVnodes[i];
             let childRes;
             try {
-                childRes = this.materialize(childVnode, fiber, childScope);
+                // Defer child lifecycle so all siblings (and this parent) finish bus wiring
+                // before any onMount runs — otherwise earlier-sibling publishes miss later
+                // siblings' @On* handlers (and parent handlers miss child onMount publishes).
+                childRes = this.materialize(childVnode, fiber, childScope, true);
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -1227,17 +1520,21 @@ class GraphRuntime {
             }
             if (isThenable(childRes)) {
                 // Hit an async child — continue the materialization tail in the async continuation.
-                return this.continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childScope, childRes, i);
+                return this.continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childScope, childRes, i, deferLifecycle);
             }
             fiber.constructionJournal.mountedChildren.push(childRes);
         }
         fiber.children = fiber.constructionJournal.mountedChildren;
-        // Bind ref to the instance (centralized via commitRef)
+        // Bind ref to the instance (centralized via commitRef).
+        // Mark refBound/refOwner BEFORE commitRef: a setter may assign `current`
+        // then throw. If the flags were set only after a successful return,
+        // rollback would skip the identity-safe clear and leave a zombie ref
+        // (root was never published, so failStop cannot reclaim it).
         if (vnode.ref !== undefined) {
             try {
-                this.commitRef(undefined, null, vnode.ref, instance);
                 fiber.constructionJournal.refBound = true;
                 fiber.constructionJournal.refOwner = instance;
+                this.commitRef(undefined, null, vnode.ref, instance);
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -1250,47 +1547,12 @@ class GraphRuntime {
                 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;
-        }
-        // Run lifecycle after all children are materialized.
-        // 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);
-        }
-        if (!startupRes.ok) {
-            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 error;
-        }
-        fiber.lifecycleStatus = engine.getStatus();
-        fiber.effectTag = null;
-        fiber.constructionJournal.schedulerHookAttached = true;
-        this.injectUpdateHook(instance, fiber);
-        return fiber;
+        // Parent buses already wired before children (see above). Do not wire again here.
+        return this.completeMaterializeAfterWiring(fiber, instance, engine, deferLifecycle);
     }
     /**
      * Async continuation of {@link materialize} after a child returned a Promise.
-     * Finishes remaining child fibers with `await`, then runs parent startup.
+     * Finishes remaining child fibers with `await`, then completes wiring / lifecycle.
      *
      * @param {RuntimeFiber<P>} fiber - current fiber
      * @param {Component<unknown, P>} instance - component instance
@@ -1300,9 +1562,10 @@ class GraphRuntime {
      * @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
+     * @param {boolean} deferLifecycle - parent defer flag from {@link materialize}
      * @returns {Promise<RuntimeFiber<P>>}
      */
-    async continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childScope, pending, pendingIdx) {
+    async continueMaterializeAsync(fiber, instance, engine, vnode, childVnodes, childScope, pending, pendingIdx, deferLifecycle) {
         const journal = fiber.constructionJournal;
         try {
             journal.mountedChildren.push(await pending);
@@ -1318,7 +1581,7 @@ class GraphRuntime {
         for (let i = pendingIdx + 1; i < childVnodes.length; i++) {
             const childVnode = childVnodes[i];
             try {
-                const childRes = this.materialize(childVnode, fiber, childScope);
+                const childRes = this.materialize(childVnode, fiber, childScope, true);
                 const resolvedChild = isThenable(childRes) ? await childRes : childRes;
                 journal.mountedChildren.push(resolvedChild);
             }
@@ -1332,11 +1595,12 @@ class GraphRuntime {
             }
         }
         fiber.children = journal.mountedChildren;
+        // Mark refBound/refOwner BEFORE commitRef (see sync materialize path).
         if (vnode.ref !== undefined) {
             try {
-                this.commitRef(undefined, null, vnode.ref, instance);
                 journal.refBound = true;
                 journal.refOwner = instance;
+                this.commitRef(undefined, null, vnode.ref, instance);
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -1347,35 +1611,9 @@ class GraphRuntime {
                 throw error;
             }
         }
-        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) {
-            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 error;
-        }
-        fiber.lifecycleStatus = engine.getStatus();
-        fiber.effectTag = null;
-        journal.schedulerHookAttached = true;
-        this.injectUpdateHook(instance, fiber);
-        return fiber;
+        // Parent buses were wired before the child loop in materialize(); async continuation
+        // must not register handlers a second time.
+        return this.completeMaterializeAfterWiring(fiber, instance, engine, deferLifecycle);
     }
     /**
      * Async finalization of {@link materialize} when child fibers were gathered synchronously but {@link LifecycleEngine.runStartup} returned a Promise.
@@ -1417,9 +1655,12 @@ class GraphRuntime {
      * @param {VirtualServiceNode<P>} nextVnode - new virtual node
      * @param {RuntimeFiber | null} parentFiber - parent fiber
      * @param {ContextScope} parentScope - parent scope
+     * @param {boolean} [deferLifecycle=false] - when true, REPLACE materialize wires buses but
+     *   defers onMount until the sibling batch flush in {@link reconcileChildren} (same contract
+     *   as PLACE). Root reconcile must leave this false — nothing else flushes the root.
      * @returns {Promise<RuntimeFiber<P>>}
      */
-    reconcileFiber(current, nextVnode, parentFiber, parentScope) {
+    reconcileFiber(current, nextVnode, parentFiber, parentScope, deferLifecycle = false) {
         const sameType = current.vnode.type === nextVnode.type;
         const sameKey = (current.vnode.key ?? null) === (nextVnode.key ?? null);
         if (sameType && sameKey) {
@@ -1429,11 +1670,15 @@ class GraphRuntime {
         // Sync fast-path if both destroy and materialize completed synchronously.
         // 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.
+        //
+        // When deferLifecycle is set (child reconcile batch), REPLACE must not run onMount
+        // before later sibling buses are wired — otherwise a replaced publisher's mount-time
+        // publish is silently dropped by a not-yet-wired PLACE/REPLACE listener beside it.
         const destroyRes = this.destroyFiber(current, []);
         if (isThenable(destroyRes)) {
-            return destroyRes.then(() => this.materialize(nextVnode, parentFiber, parentScope));
+            return destroyRes.then(() => this.materialize(nextVnode, parentFiber, parentScope, deferLifecycle));
         }
-        return this.materialize(nextVnode, parentFiber, parentScope);
+        return this.materialize(nextVnode, parentFiber, parentScope, deferLifecycle);
     }
     /**
      * Updates an existing fiber: applies new props to the instance,
@@ -1591,12 +1836,13 @@ class GraphRuntime {
             fiber.lifecycleStatus = fiber.engine.getStatus();
             attachCleanupErrors();
         };
-        for (let i = children.length - 1; i >= 0; i -= 1) {
+        // Siblings in compose order — same contract as destroyFiber / clean unmount.
+        for (let i = 0; i < children.length; 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) {
+                        for (let j = i + 1; j < children.length; j += 1) {
                             try {
                                 const r = this.destroyFiber(children[j], cleanupErrors);
                                 if (isThenable(r)) {
@@ -1610,7 +1856,7 @@ class GraphRuntime {
                         return finishParent();
                     }, async (err) => {
                         cleanupErrors.push(err instanceof Error ? err : new Error(String(err)));
-                        for (let j = i - 1; j >= 0; j -= 1) {
+                        for (let j = i + 1; j < children.length; j += 1) {
                             try {
                                 const r = this.destroyFiber(children[j], cleanupErrors);
                                 if (isThenable(r)) {
@@ -1753,7 +1999,7 @@ class GraphRuntime {
             const n = nextVnodes.length;
             const stableResult = [];
             for (let i = 0; i < n; i++) {
-                const reconciled = this.reconcileFiber(currentChildren[i], nextVnodes[i], parentFiber, childScope);
+                const reconciled = this.reconcileFiber(currentChildren[i], nextVnodes[i], parentFiber, childScope, true);
                 if (isThenable(reconciled)) {
                     return this.continueStableReconcileAsync(stableResult, reconciled, i, nextVnodes, currentChildren, parentFiber, childScope);
                 }
@@ -1780,7 +2026,7 @@ class GraphRuntime {
         this.stableAsyncContinueCount += 1;
         resultSoFar.push(await pending);
         for (let i = pendingIdx + 1; i < nextVnodes.length; i++) {
-            const reconciled = this.reconcileFiber(currentChildren[i], nextVnodes[i], parentFiber, childScope);
+            const reconciled = this.reconcileFiber(currentChildren[i], nextVnodes[i], parentFiber, childScope, true);
             resultSoFar.push(isThenable(reconciled) ? await reconciled : reconciled);
         }
         return resultSoFar;
@@ -1874,18 +2120,18 @@ class GraphRuntime {
                                 throw new Error(`[Effectable] GraphRuntime: fiber with key "${nextKey}" not found in map.`);
                             }
                             keyedCurrentMap.delete(nextKey);
-                            const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
+                            const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope, true);
                             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);
+                            const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope, true);
                             nextChildren.push(isThenable(reconciledRes) ? await reconciledRes : reconciledRes);
                         }
                         else {
-                            // New node — PLACE
-                            const newRes = this.materialize(nextVnode, parentFiber, childScope);
+                            // New node — PLACE: defer startup so later sibling buses wire first.
+                            const newRes = this.materialize(nextVnode, parentFiber, childScope, true);
                             nextChildren.push(isThenable(newRes) ? await newRes : newRes);
                         }
                     }
@@ -1913,12 +2159,12 @@ class GraphRuntime {
                     if (unkeyedIdx < unkeyedCurrent.length) {
                         const currentFiber = unkeyedCurrent[unkeyedIdx];
                         unkeyedIdx += 1;
-                        const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope);
+                        const reconciledRes = this.reconcileFiber(currentFiber, nextVnode, parentFiber, childScope, true);
                         nextChildren.push(isThenable(reconciledRes) ? await reconciledRes : reconciledRes);
                     }
                     else {
-                        // New node — PLACE
-                        const newRes = this.materialize(nextVnode, parentFiber, childScope);
+                        // New node — PLACE: defer startup so later sibling buses wire first.
+                        const newRes = this.materialize(nextVnode, parentFiber, childScope, true);
                         nextChildren.push(isThenable(newRes) ? await newRes : newRes);
                     }
                 }
@@ -1933,6 +2179,15 @@ class GraphRuntime {
                     }
                 }
             }
+            // Flush PLACE/REPLACE startups in compose order after every new sibling is wired.
+            for (const child of nextChildren) {
+                if (child.constructionJournal?.lifecycleDeferred === true) {
+                    const flush = this.flushDeferredLifecycleTree(child);
+                    if (isThenable(flush)) {
+                        await flush;
+                    }
+                }
+            }
             return nextChildren;
         }
         catch (primaryError) {