@zudojs/lifecycle 1.2.3 → 1.3.0

package/dist/lifecycleInternal/index.d.ts

@@ -4,8 +4,8 @@
  * Internal utilities: dependency graph, topological sort, async helpers.
  */
 export { DependencyGraph } from "./dependencyGraph.core.js";
+export type { DependencyGraphValidationOptions } from "./dependencyGraph.core.js";
 export { topologicalSort, reverseTopologicalSort, } from "./topologicalSort.core.js";
 export type { TopologicalStage } from "./topologicalSort.core.js";
 export { withTimeout, withAbort, withConcurrency } from "./asyncUtils.core.js";
 export { MAX_TIMER_DELAY, assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycleInternal/index.js

@@ -7,4 +7,3 @@ export { DependencyGraph } from "./dependencyGraph.core.js";
 export { topologicalSort, reverseTopologicalSort, } from "./topologicalSort.core.js";
 export { withTimeout, withAbort, withConcurrency } from "./asyncUtils.core.js";
 export { MAX_TIMER_DELAY, assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycleInternal/timeoutBudget.core.d.ts

@@ -27,4 +27,3 @@ export declare function isBounded(value: number): boolean;
  * Clamps a finite budget to what a timer can represent.
  */
 export declare function toTimerDelay(value: number): number;
-//# sourceMappingURL=timeoutBudget.core.d.ts.map

package/dist/lifecycleInternal/timeoutBudget.core.js

@@ -35,4 +35,3 @@ export function isBounded(value) {
 export function toTimerDelay(value) {
     return Math.min(Math.max(0, value), MAX_TIMER_DELAY);
 }
-//# sourceMappingURL=timeoutBudget.core.js.map

package/dist/lifecycleInternal/topologicalSort.core.d.ts

@@ -9,7 +9,18 @@ export type TopologicalStage = readonly string[];
 /**
  * Performs topological sort on a dependency graph,
  * grouping independent components into parallel stages.
- * Components within the same stage are ordered by priority (higher first).
+ * Components within the same stage are ordered by priority (higher
+ * first) and then by the order they were added to the graph.
+ *
+ * Runs in O(V + E) — each node is queued once when its last dependency
+ * is placed. A rescan of every remaining node per stage made a long
+ * chain quadratic (a 20 000-component chain took seconds to order).
+ *
+ * Throws LifecycleDependencyError, naming the actual loop, when the
+ * graph is cyclic. The error used to list every node that was still
+ * blocked, which for one three-node loop meant naming the whole
+ * application. Undeclared nodes (see `DependencyGraph.validate`) sort
+ * as leaves.
  */
 export declare function topologicalSort(graph: DependencyGraph, priorities?: ReadonlyMap<string, number>): readonly TopologicalStage[];
 /**
@@ -23,4 +34,3 @@ export declare function topologicalSort(graph: DependencyGraph, priorities?: Rea
  * concurrently, but wrong now that priority is a real sub-stage barrier.
  */
 export declare function reverseTopologicalSort(graph: DependencyGraph, priorities?: ReadonlyMap<string, number>): readonly TopologicalStage[];
-//# sourceMappingURL=topologicalSort.core.d.ts.map

package/dist/lifecycleInternal/topologicalSort.core.js

@@ -7,36 +7,56 @@ import { LifecycleDependencyError } from "@zudojs/errors";
 /**
  * Performs topological sort on a dependency graph,
  * grouping independent components into parallel stages.
- * Components within the same stage are ordered by priority (higher first).
+ * Components within the same stage are ordered by priority (higher
+ * first) and then by the order they were added to the graph.
+ *
+ * Runs in O(V + E) — each node is queued once when its last dependency
+ * is placed. A rescan of every remaining node per stage made a long
+ * chain quadratic (a 20 000-component chain took seconds to order).
+ *
+ * Throws LifecycleDependencyError, naming the actual loop, when the
+ * graph is cyclic. The error used to list every node that was still
+ * blocked, which for one three-node loop meant naming the whole
+ * application. Undeclared nodes (see `DependencyGraph.validate`) sort
+ * as leaves.
  */
 export function topologicalSort(graph, priorities) {
     const nodes = graph.getNodes();
+    const position = new Map();
     const inDegree = new Map();
-    for (const node of nodes) {
-        const deps = graph.getDependencies(node);
-        inDegree.set(node, deps.length);
-    }
+    let ready = [];
+    nodes.forEach((node, index) => {
+        position.set(node, index);
+        const degree = graph.getDependencies(node).length;
+        inDegree.set(node, degree);
+        if (degree === 0)
+            ready.push(node);
+    });
+    const byPriorityThenPosition = (a, b) => {
+        const pa = priorities?.get(a) ?? 0;
+        const pb = priorities?.get(b) ?? 0;
+        return pb - pa || position.get(a) - position.get(b);
+    };
     const stages = [];
-    const remaining = new Set(nodes);
-    while (remaining.size > 0) {
-        const ready = [...remaining].filter((node) => inDegree.get(node) === 0);
-        if (ready.length === 0 && remaining.size > 0) {
-            throw new LifecycleDependencyError([...remaining]);
-        }
-        ready.sort((a, b) => {
-            const pa = priorities?.get(a) ?? 0;
-            const pb = priorities?.get(b) ?? 0;
-            return pb - pa;
-        });
+    let placed = 0;
+    while (ready.length > 0) {
+        ready.sort(byPriorityThenPosition);
         stages.push(Object.freeze(ready));
+        placed += ready.length;
+        const next = [];
         for (const node of ready) {
-            remaining.delete(node);
-            const dependents = graph.getDependents(node);
-            for (const dep of dependents) {
-                const current = inDegree.get(dep) ?? 0;
-                inDegree.set(dep, current - 1);
+            for (const dependent of graph.getDependents(node)) {
+                const remaining = (inDegree.get(dependent) ?? 0) - 1;
+                inDegree.set(dependent, remaining);
+                if (remaining === 0)
+                    next.push(dependent);
             }
         }
+        ready = next;
+    }
+    if (placed < nodes.length) {
+        const cycle = graph.findCycle();
+        throw new LifecycleDependencyError(cycle ?? nodes.filter((node) => (inDegree.get(node) ?? 0) > 0));
     }
     return stages;
 }
@@ -54,4 +74,3 @@ export function reverseTopologicalSort(graph, priorities) {
     const stages = topologicalSort(graph, priorities);
     return Object.freeze([...stages].reverse().map((stage) => Object.freeze([...stage].reverse())));
 }
-//# sourceMappingURL=topologicalSort.core.js.map

package/dist/lifecycleManager/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { LifecycleManager, createLifecycleManager, } from "./lifecycleManager.core.js";
 export type { LifecycleManagerOptions } from "./lifecycleManager.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycleManager/index.js

@@ -4,4 +4,3 @@
  * Lifecycle manager — the main orchestration entry point.
  */
 export { LifecycleManager, createLifecycleManager, } from "./lifecycleManager.core.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycleManager/lifecycleManager.context.d.ts

@@ -10,7 +10,7 @@ import type { LifecycleStateMachine } from "../lifecycleState/lifecycleState.mac
 import type { LifecycleRegistry } from "../lifecycleRegistry/lifecycleRegistry.core.js";
 import type { LifecycleExecutor } from "../lifecycleExecutor/lifecycleExecutor.core.js";
 import type { LifecycleEventEmitter } from "../lifecycleEvents/lifecycleEvents.core.js";
-import type { ExecutionResult } from "../lifecycleExecutor/lifecycleExecutor.core.js";
+import type { ExecutionResult } from "../lifecycleExecutor/lifecycleExecutor.type.js";
 /** Internal context passed to startup/shutdown orchestration functions. */
 export interface LifecycleManagerContext {
     readonly registry: LifecycleRegistry;
@@ -22,16 +22,25 @@ export interface LifecycleManagerContext {
     readonly componentStates: Map<string, LifecycleStateMachine>;
     readonly results: Map<string, ExecutionResult[]>;
     /**
-     * Startup phases that were actually run for each component.
+     * Startup phases each component reached.
      *
      * Shutdown consults this so `stop()` is only invoked on components
-     * whose `start` phase ran and `dispose()` only on components whose
-     * `initialize` phase ran. Rollback after an early failure used to
-     * call `stop()` on components that had never started, which for a
-     * real server throws and was then reported as a component failure.
+     * whose `start` completed or timed out, and `dispose()` only on
+     * components whose `initialize` was invoked. Rollback after an early
+     * failure used to call `stop()` on components that had never
+     * started, which for a real server throws and was then reported as
+     * a component failure.
      */
     readonly attempted: Map<string, Set<LifecyclePhase>>;
     startTime: number;
+    /** Whether the shutdown deadline expired during the current teardown. */
+    shutdownTimedOut: boolean;
+    /**
+     * Components whose shutdown hook is executing right now, with the
+     * time the stage began. The deadline handler fails exactly these
+     * when it expires.
+     */
+    shutdownInFlight?: Map<string, number>;
     /**
      * Cancellation source for the current run.
      *
@@ -92,4 +101,3 @@ export declare function emitComponentFailed(ctx: LifecycleManagerContext, result
     error?: unknown;
     duration: number;
 }): void;
-//# sourceMappingURL=lifecycleManager.context.d.ts.map

package/dist/lifecycleManager/lifecycleManager.context.js

@@ -60,4 +60,3 @@ export function emitComponentFailed(ctx, result) {
         },
     });
 }
-//# sourceMappingURL=lifecycleManager.context.js.map

package/dist/lifecycleManager/lifecycleManager.core.d.ts

@@ -7,7 +7,7 @@
 import { LifecycleState } from "@zudojs/constants";
 import type { LifecycleComponent, LifecycleRegistrationOptions } from "../lifecycleComponent/lifecycleComponent.type.js";
 import { LifecycleRegistry } from "../lifecycleRegistry/lifecycleRegistry.core.js";
-import type { ExecutionResult } from "../lifecycleExecutor/lifecycleExecutor.core.js";
+import type { ExecutionResult } from "../lifecycleExecutor/lifecycleExecutor.type.js";
 import { LifecycleEventEmitter } from "../lifecycleEvents/lifecycleEvents.core.js";
 /** Options for creating a lifecycle manager. */
 export interface LifecycleManagerOptions {
@@ -57,11 +57,22 @@ export declare class LifecycleManager {
     /**
      * Shuts down the application lifecycle.
      * Idempotent — returns the same promise if called multiple times.
+     *
+     * Always resolves, even when `shutdownTimeout` expires: a signal
+     * handler awaiting it must not crash the process. Expiry is reported
+     * through {@link shutdownTimedOut}, the `application:shutdown-timeout`
+     * event, and a FAILED status (with a LifecycleTimeoutError result)
+     * for every component whose hook was still running.
      */
     shutdown(): Promise<void>;
     private releaseSignalHandlers;
     /** Returns the current application state. */
     get state(): LifecycleState;
+    /**
+     * Whether the last (or current) shutdown ran out of `shutdownTimeout`
+     * before every component was stopped and disposed.
+     */
+    get shutdownTimedOut(): boolean;
     /** Returns the event emitter for lifecycle events. */
     get events(): LifecycleEventEmitter;
     /** Returns the registry. */
@@ -81,4 +92,3 @@ export declare class LifecycleManager {
 }
 /** Creates a new lifecycle manager. */
 export declare function createLifecycleManager(options?: LifecycleManagerOptions): LifecycleManager;
-//# sourceMappingURL=lifecycleManager.core.d.ts.map

package/dist/lifecycleManager/lifecycleManager.core.js

@@ -36,17 +36,32 @@ export class LifecycleManager {
         if (options.shutdownTimeout !== undefined) {
             assertTimeoutBudget("shutdownTimeout", options.shutdownTimeout);
         }
+        const events = new LifecycleEventEmitter();
         this._ctx = {
             registry: new LifecycleRegistry(),
             state: new LifecycleStateMachine("application"),
-            executor: new LifecycleExecutor(),
-            events: new LifecycleEventEmitter(),
+            executor: new LifecycleExecutor({
+                // Retries used to be invisible: a backoff delay could only be
+                // inferred from wall-clock timing.
+                onRetry: (notice) => {
+                    events.emit("component:retrying", {
+                        component: {
+                            componentId: notice.id,
+                            attempt: notice.attempt,
+                            delay: notice.delay,
+                            error: notice.error,
+                        },
+                    });
+                },
+            }),
+            events,
             concurrency: options.concurrency ?? LIFECYCLE_DEFAULT_CONCURRENCY,
             shutdownTimeout: options.shutdownTimeout ?? LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT,
             componentStates: new Map(),
             results: new Map(),
             attempted: new Map(),
             startTime: 0,
+            shutdownTimedOut: false,
             controller: new AbortController(),
         };
         // Installing in the constructor disabled Ctrl-C for the whole
@@ -93,6 +108,12 @@ export class LifecycleManager {
     /**
      * Shuts down the application lifecycle.
      * Idempotent — returns the same promise if called multiple times.
+     *
+     * Always resolves, even when `shutdownTimeout` expires: a signal
+     * handler awaiting it must not crash the process. Expiry is reported
+     * through {@link shutdownTimedOut}, the `application:shutdown-timeout`
+     * event, and a FAILED status (with a LifecycleTimeoutError result)
+     * for every component whose hook was still running.
      */
     async shutdown() {
         // performShutdown is itself single-flight, so a shutdown started by
@@ -112,6 +133,13 @@ export class LifecycleManager {
     get state() {
         return this._ctx.state.state;
     }
+    /**
+     * Whether the last (or current) shutdown ran out of `shutdownTimeout`
+     * before every component was stopped and disposed.
+     */
+    get shutdownTimedOut() {
+        return this._ctx.shutdownTimedOut;
+    }
     /** Returns the event emitter for lifecycle events. */
     get events() {
         return this._ctx.events;
@@ -146,4 +174,3 @@ export class LifecycleManager {
 export function createLifecycleManager(options) {
     return new LifecycleManager(options);
 }
-//# sourceMappingURL=lifecycleManager.core.js.map

package/dist/lifecycleManager/lifecycleManager.deadline.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @zudojs/lifecycle/manager/deadline
+ *
+ * Global shutdown deadline: races a phase against the remaining budget
+ * and reports expiry instead of letting it pass silently.
+ */
+import type { LifecyclePhase } from "@zudojs/constants";
+import type { LifecycleManagerContext } from "./lifecycleManager.context.js";
+/**
+ * Resolves when the phase finishes or the shutdown budget runs out.
+ *
+ * On expiry {@link expireShutdown} runs, so the deadline is never
+ * silent, and the timer is always cleared so it can never hold the
+ * event loop open. The abandoned phase promise never surfaces as an
+ * unhandled rejection once the race has been decided.
+ */
+export declare function raceDeadline(ctx: LifecycleManagerContext, phase: LifecyclePhase, work: Promise<void>, remainingMs: number): Promise<void>;
+/**
+ * Records that the shutdown deadline has expired. Idempotent.
+ *
+ * The run's AbortController is aborted so in-flight hooks observing
+ * `context.signal` unwind; every component whose hook was still
+ * running is recorded as FAILED with a LifecycleTimeoutError (its
+ * status used to stay STOPPING forever); and one
+ * `application:shutdown-timeout` event is emitted. Shutdown itself
+ * still resolves — a signal handler awaiting it must not crash the
+ * process — and `LifecycleManager.shutdownTimedOut` reports the outcome.
+ */
+export declare function expireShutdown(ctx: LifecycleManagerContext, phase: LifecyclePhase): void;

package/dist/lifecycleManager/lifecycleManager.deadline.js

@@ -0,0 +1,79 @@
+/**
+ * @zudojs/lifecycle/manager/deadline
+ *
+ * Global shutdown deadline: races a phase against the remaining budget
+ * and reports expiry instead of letting it pass silently.
+ */
+import { LifecycleTimeoutError } from "@zudojs/errors";
+import { isBounded, toTimerDelay } from "../lifecycleInternal/index.js";
+import { emitComponentFailed, failComponent, recordResult, } from "./lifecycleManager.context.js";
+/**
+ * Resolves when the phase finishes or the shutdown budget runs out.
+ *
+ * On expiry {@link expireShutdown} runs, so the deadline is never
+ * silent, and the timer is always cleared so it can never hold the
+ * event loop open. The abandoned phase promise never surfaces as an
+ * unhandled rejection once the race has been decided.
+ */
+export async function raceDeadline(ctx, phase, work, remainingMs) {
+    // An unbounded budget (shutdownTimeout: Infinity) waits for the work.
+    // Handing Infinity to setTimeout fired after 1 ms and abandoned every
+    // stop()/dispose() while reporting the application DISPOSED.
+    if (!isBounded(remainingMs)) {
+        await work.catch(() => { });
+        return;
+    }
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            expireShutdown(ctx, phase);
+            resolve();
+        }, toTimerDelay(remainingMs));
+    });
+    try {
+        await Promise.race([work, expiry]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+    void work.catch(() => { });
+}
+/**
+ * Records that the shutdown deadline has expired. Idempotent.
+ *
+ * The run's AbortController is aborted so in-flight hooks observing
+ * `context.signal` unwind; every component whose hook was still
+ * running is recorded as FAILED with a LifecycleTimeoutError (its
+ * status used to stay STOPPING forever); and one
+ * `application:shutdown-timeout` event is emitted. Shutdown itself
+ * still resolves — a signal handler awaiting it must not crash the
+ * process — and `LifecycleManager.shutdownTimedOut` reports the outcome.
+ */
+export function expireShutdown(ctx, phase) {
+    if (ctx.shutdownTimedOut)
+        return;
+    ctx.shutdownTimedOut = true;
+    const error = new LifecycleTimeoutError("application", phase, ctx.shutdownTimeout);
+    ctx.controller.abort(error);
+    const now = Date.now();
+    for (const [id, startedAt] of ctx.shutdownInFlight ?? []) {
+        const result = {
+            id,
+            phase,
+            duration: now - startedAt,
+            success: false,
+            timedOut: true,
+            error: new LifecycleTimeoutError(id, phase, ctx.shutdownTimeout),
+        };
+        recordResult(ctx, result);
+        failComponent(ctx, id);
+        emitComponentFailed(ctx, result);
+    }
+    ctx.shutdownInFlight = undefined;
+    ctx.events.emit("application:shutdown-timeout", {
+        error,
+        duration: now - ctx.startTime,
+    });
+}

package/dist/lifecycleManager/lifecycleManager.shutdown.d.ts

@@ -12,4 +12,3 @@ import type { LifecycleManagerContext } from "./lifecycleManager.context.js";
  * running overlapping ones.
  */
 export declare function performShutdown(ctx: LifecycleManagerContext): Promise<void>;
-//# sourceMappingURL=lifecycleManager.shutdown.d.ts.map

package/dist/lifecycleManager/lifecycleManager.shutdown.js

@@ -6,10 +6,24 @@
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-import { isBounded, toTimerDelay } from "../lifecycleInternal/index.js";
 import { emitComponentFailed, recordResult, transitionComponent, wasAttempted, } from "./lifecycleManager.context.js";
+import { expireShutdown, raceDeadline } from "./lifecycleManager.deadline.js";
 /** Shutdown phases in execution order. */
 const SHUTDOWN_PHASES = [LifecyclePhase.STOP, LifecyclePhase.DISPOSE];
+/**
+ * Per-phase component events. Dispose used to reuse the stop pair, so
+ * a listener saw every component "stopped" twice.
+ */
+const PHASE_EVENTS = {
+    [LifecyclePhase.STOP]: {
+        begin: "component:stopping",
+        end: "component:stopped",
+    },
+    [LifecyclePhase.DISPOSE]: {
+        begin: "component:disposing",
+        end: "component:disposed",
+    },
+};
 /**
  * Performs the full shutdown sequence: stop → dispose.
  *
@@ -37,43 +51,41 @@ async function runShutdown(ctx) {
             ctx.state.forceState(LifecycleState.STOPPING);
         }
     }
+    ctx.shutdownTimedOut = false;
     ctx.events.emit("application:stopping", {});
     const deadline = Date.now() + ctx.shutdownTimeout;
     // A startup stage still executing must settle before its components
     // are stopped, otherwise `stop()` overlaps the component's own
     // `start()`. Startup itself refuses to launch further stages once
-    // `shutdownPromise` is set, so this wait is bounded by one stage.
+    // `shutdownPromise` is set, and each hook in the stage is bounded by
+    // its component timeout, so this wait is bounded by one stage.
+    //
+    // Hooks abandoned by a component timeout are NOT waited for here:
+    // the executor makes each component's stop()/dispose() wait for that
+    // component's own abandoned hook, bounded by its timeout, so one
+    // hung start() no longer holds every other component's teardown
+    // until the global deadline.
     if (ctx.inFlight !== undefined) {
-        await raceDeadline(ctx, ctx.inFlight.then(() => undefined, () => undefined), Math.max(deadline - Date.now(), 1));
+        await raceDeadline(ctx, LifecyclePhase.STOP, ctx.inFlight.then(() => undefined, () => undefined), Math.max(deadline - Date.now(), 1));
     }
-    // Hooks abandoned by a component timeout are still running; stopping
-    // their component now would overlap its own start().
-    await raceDeadline(ctx, ctx.executor.settleAbandoned(), Math.max(deadline - Date.now(), 1));
-    // The shutdown deadline used to be checked only BETWEEN the two
-    // phases, so a single hook that never settled hung shutdown (and the
-    // process) forever. Race the whole phase against the remaining
-    // budget and abort the run's signal when it expires, so hooks that
-    // honour cancellation stop and the rest are abandoned.
+    // The whole phase is raced against the remaining budget; expiry is
+    // recorded by expireShutdown (components FAILED, event emitted,
+    // signal aborted) rather than passing silently.
     for (const phase of SHUTDOWN_PHASES) {
         const remaining = deadline - Date.now();
-        if (remaining <= 0) {
-            ctx.controller.abort(new Error(`Lifecycle shutdown exceeded its ${ctx.shutdownTimeout}ms deadline.`));
+        if (ctx.shutdownTimedOut || remaining <= 0) {
+            expireShutdown(ctx, phase);
             break;
         }
+        if (phase === LifecyclePhase.DISPOSE) {
+            ctx.events.emit("application:disposing", {});
+        }
         try {
-            await raceDeadline(ctx, executeShutdownPhase(ctx, phase), remaining);
+            await raceDeadline(ctx, phase, executeShutdownPhase(ctx, phase), remaining);
         }
         catch {
             // Shutdown must continue even if individual components fail.
         }
-        // A stop()/dispose() hook that blew its own component timeout joins
-        // the abandoned set DURING this phase, so the pre-phase settle above
-        // cannot have covered it. Without this wait, DISPOSE ran on top of a
-        // stop() that was still draining and shutdown() resolved (reporting
-        // DISPOSED) while the hook kept running — the exact overlap the
-        // pre-phase settle was added to prevent. Still bounded by the global
-        // shutdown deadline.
-        await raceDeadline(ctx, ctx.executor.settleAbandoned(), Math.max(deadline - Date.now(), 1));
     }
     ctx.state.forceState(LifecycleState.DISPOSED);
     ctx.events.emit("application:stopped", {
@@ -83,49 +95,17 @@ async function runShutdown(ctx) {
         duration: Date.now() - ctx.startTime,
     });
 }
-/**
- * Resolves when the phase finishes or the shutdown budget runs out.
- *
- * On expiry the run's AbortController is aborted so in-flight hooks
- * observing `context.signal` unwind, and the timer is always cleared
- * so it can never hold the event loop open.
- */
-async function raceDeadline(ctx, phase, remainingMs) {
-    // An unbounded budget (shutdownTimeout: Infinity) waits for the phase.
-    // Handing Infinity to setTimeout fired after 1 ms and abandoned every
-    // stop()/dispose() while reporting the application DISPOSED.
-    if (!isBounded(remainingMs)) {
-        await phase.catch(() => { });
-        return;
-    }
-    let timer;
-    const expiry = new Promise((resolve) => {
-        timer = setTimeout(() => {
-            ctx.controller.abort(new Error(`Lifecycle shutdown exceeded its ${ctx.shutdownTimeout}ms deadline.`));
-            resolve();
-        }, toTimerDelay(remainingMs));
-    });
-    try {
-        await Promise.race([phase, expiry]);
-    }
-    finally {
-        if (timer !== undefined) {
-            clearTimeout(timer);
-        }
-    }
-    // The abandoned phase promise must never surface as an unhandled
-    // rejection once the race has been decided.
-    void phase.catch(() => { });
-}
 /**
  * Executes a single shutdown phase across all registered components.
  *
  * A hook only runs for components that reached the matching startup
- * phase: `stop()` when `start` ran, `dispose()` when `initialize` ran.
- * Rollback after an early failure — and `shutdown()` on a manager that
- * was never started — used to call `stop()` on components that had
- * never started; a real server's `close()` throws in that situation
- * and the phantom failure was then recorded against the component.
+ * phase: `stop()` when `start` completed (or timed out, so its outcome
+ * is unknown), `dispose()` when `initialize` was invoked at all — a
+ * failed initialize may still hold resources. Rollback used to call
+ * `stop()` on a component whose own `start()` had just thrown, and on
+ * non-critical components that never came up; a real server's
+ * `close()` throws in that situation and the phantom failure was then
+ * recorded against the component.
  */
 async function executeShutdownPhase(ctx, phase) {
     const plan = buildExecutionPlan(ctx.registry.getAll(), phase);
@@ -137,7 +117,10 @@ async function executeShutdownPhase(ctx, phase) {
     const successState = isStop
         ? LifecycleState.STOPPED
         : LifecycleState.DISPOSED;
+    const events = PHASE_EVENTS[phase];
     for (const stage of plan.stages) {
+        if (ctx.shutdownTimedOut)
+            return;
         const stageRegs = stage.components
             .map((id) => ctx.registry.get(id))
             .filter((r) => r !== undefined);
@@ -160,22 +143,31 @@ async function executeShutdownPhase(ctx, phase) {
             if (isStop) {
                 transitionComponent(ctx, reg.id, LifecycleState.STOPPING);
             }
-            ctx.events.emit("component:stopping", {
+            ctx.events.emit(events.begin, {
                 component: { componentId: reg.id },
             });
         }
         if (runnable.length === 0)
             continue;
-        const results = await ctx.executor.executeStage(runnable, phase, context, ctx.concurrency);
-        // Shutdown results used to be discarded entirely: a component whose
-        // stop() or dispose() threw was still reported as cleanly STOPPED,
-        // its failure never reached getStatus() or the event stream, and
-        // operators had no way to learn a resource had leaked.
+        const startedAt = Date.now();
+        ctx.shutdownInFlight = new Map(runnable.map((reg) => [reg.id, startedAt]));
+        let results;
+        try {
+            results = await ctx.executor.executeStage(runnable, phase, context, ctx.concurrency);
+        }
+        finally {
+            ctx.shutdownInFlight = undefined;
+        }
+        // Results arriving after the deadline expired belong to hooks the
+        // deadline already reported as timed out. Recording them would emit
+        // events after shutdown() has resolved and overwrite that verdict.
+        if (ctx.shutdownTimedOut)
+            return;
         for (const result of results) {
             recordResult(ctx, result);
             if (result.success) {
                 transitionComponent(ctx, result.id, successState);
-                ctx.events.emit("component:stopped", {
+                ctx.events.emit(events.end, {
                     component: { componentId: result.id, duration: result.duration },
                 });
                 continue;
@@ -185,4 +177,3 @@ async function executeShutdownPhase(ctx, phase) {
         }
     }
 }
-//# sourceMappingURL=lifecycleManager.shutdown.js.map

package/dist/lifecycleManager/lifecycleManager.startup.d.ts

@@ -14,4 +14,3 @@ import type { LifecycleManagerContext } from "./lifecycleManager.context.js";
  * just been torn down.
  */
 export declare function performStartup(ctx: LifecycleManagerContext): Promise<void>;
-//# sourceMappingURL=lifecycleManager.startup.d.ts.map