@zudojs/lifecycle 1.0.0 → 1.1.1

package/README.md

@@ -3,6 +3,12 @@
 Application and component lifecycle orchestration with a state machine,
 dependency ordering, graceful shutdown, rollback, and signal handling.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-lifecycle](https://zudojs.oyinlola.site/docs/packages-lifecycle) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-lifecycle.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -48,7 +54,19 @@ If a **critical** component (the default) fails any startup phase,
 `start()` rolls the application back (`stop` → `dispose`) and then
 **rejects** with a `LifecycleStartError`. Register a component with
 `{ critical: false }` when its failure should not abort startup — the
-component is marked `FAILED` and startup continues.
+component is marked `FAILED` and startup continues. A failed component
+takes no further part in startup (its later hooks are not invoked), and
+components that `dependsOn` it are not started either: they are marked
+`FAILED` with a `LifecycleComponentError` naming the failed dependency,
+and their own `critical` flag decides whether startup aborts.
+
+Rollback only undoes phases that ran: `stop()` is called on components
+whose `start` phase ran, and `dispose()` on components whose
+`initialize` phase ran.
+
+Calling `shutdown()` while `start()` is in flight waits for the
+executing stage to settle, tears down, and makes `start()` reject with a
+`LifecycleStartError` — later stages are never launched.
 
 ## Shutdown
 
@@ -97,8 +115,8 @@ lifecycle.
 ```typescript
 createLifecycleManager({
   concurrency: 10,        // parallel component operations per stage
-  shutdownTimeout: 30_000, // global shutdown deadline (ms)
-  handleSignals: true,     // install process signal handlers
+  shutdownTimeout: 30_000, // global shutdown deadline (ms); Infinity = none
+  handleSignals: true,     // install signal handlers on start()
   signals: ["SIGINT", "SIGTERM"], // defaults to DEFAULT_SHUTDOWN_SIGNALS
 });
 ```
@@ -106,6 +124,18 @@ createLifecycleManager({
 Per-component: `id`, `dependsOn`, `priority`, `critical`, `timeout`,
 `retry: { attempts, delay, maxDelay, backoff }`.
 
+`timeout` and `shutdownTimeout` accept `Infinity` for "no bound"; NaN and
+negative values throw a `RangeError` when registered or constructed, and
+finite values above 2^31-1 ms are clamped to the largest timer delay.
+`retry` covers hooks that fail; a hook that times out is not retried,
+because it is still running and a second call would overlap it.
+`shutdown()` waits (within its deadline) for such an abandoned hook to
+settle before calling `stop()`.
+
+With `handleSignals`, SIGINT/SIGTERM listeners are installed by `start()`,
+not by the constructor, and removed once shutdown finishes. A second
+signal while shutdown is running exits the process with code 1.
+
 ## Use Cases
 
 - Coordinating service startup and shutdown

package/dist/lifecycleComponent/lifecycleComponent.type.d.ts

@@ -32,7 +32,10 @@ export interface LifecycleRegistrationOptions {
     readonly priority?: number;
     /** If true, application startup fails when this component fails. Defaults to true. */
     readonly critical?: boolean;
-    /** Timeout in ms for individual component operations. */
+    /**
+     * Timeout in ms for individual component operations. `Infinity` means
+     * no bound; NaN and negative values are rejected at registration.
+     */
     readonly timeout?: number;
     /** Retry configuration for failed operations. */
     readonly retry?: LifecycleRetryOptions;

package/dist/lifecycleExecutor/lifecycleExecutor.core.d.ts

@@ -23,6 +23,15 @@ export interface ExecutionResult {
  * Executes lifecycle component hooks with timeout, retry, and concurrency support.
  */
 export declare class LifecycleExecutor {
+    /** Hook invocations still running after their timeout fired. */
+    private readonly abandoned;
+    /**
+     * Resolves once every hook abandoned by a timeout has settled.
+     *
+     * Shutdown waits on this before stopping components, so `stop()`
+     * never overlaps a `start()` that is still running.
+     */
+    settleAbandoned(): Promise<void>;
     /**
      * Executes a single component hook.
      */

package/dist/lifecycleExecutor/lifecycleExecutor.core.js

@@ -5,11 +5,24 @@
  */
 import { withTimeout, withConcurrency } from "../lifecycleInternal/index.js";
 import { getComponentMethod } from "../lifecyclePhase/index.js";
-import { LifecycleComponentError } from "@zudojs/errors";
+import { LifecycleComponentError, LifecycleTimeoutError, } from "@zudojs/errors";
 /**
  * Executes lifecycle component hooks with timeout, retry, and concurrency support.
  */
 export class LifecycleExecutor {
+    /** Hook invocations still running after their timeout fired. */
+    abandoned = new Set();
+    /**
+     * Resolves once every hook abandoned by a timeout has settled.
+     *
+     * Shutdown waits on this before stopping components, so `stop()`
+     * never overlaps a `start()` that is still running.
+     */
+    async settleAbandoned() {
+        while (this.abandoned.size > 0) {
+            await Promise.allSettled([...this.abandoned]);
+        }
+    }
     /**
      * Executes a single component hook.
      */
@@ -36,12 +49,13 @@ export class LifecycleExecutor {
                 lastError ??= new LifecycleComponentError(registration.id, phase, context.signal.reason);
                 break;
             }
+            let invocation;
             try {
-                await withTimeout(async () => {
-                    const result = hook.call(registration.component, context);
-                    if (result instanceof Promise) {
-                        await result;
-                    }
+                await withTimeout(() => {
+                    invocation = (async () => {
+                        await hook.call(registration.component, context);
+                    })();
+                    return invocation;
                 }, registration.timeout, registration.id, phase);
                 return {
                     id: registration.id,
@@ -52,6 +66,16 @@ export class LifecycleExecutor {
             }
             catch (error) {
                 lastError = error;
+                // A timed-out hook is still running; withTimeout cannot cancel
+                // it. Retrying would run the same start() concurrently (three
+                // listen() calls on one port), so a timeout is final and the
+                // abandoned invocation is tracked for shutdown to wait on.
+                if (error instanceof LifecycleTimeoutError && invocation) {
+                    const abandoned = invocation.catch(() => undefined);
+                    this.abandoned.add(abandoned);
+                    void abandoned.finally(() => this.abandoned.delete(abandoned));
+                    break;
+                }
                 if (attempt < maxAttempts - 1) {
                     const delay = calculateDelay(retryConfig, attempt);
                     await sleep(delay, context.signal);

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

@@ -6,6 +6,10 @@
 /**
  * Executes an async operation with a timeout.
  * Throws LifecycleTimeoutError if the timeout is exceeded.
+ *
+ * `Infinity` runs the operation unbounded; values above the largest
+ * timer delay are clamped to it. NaN or a negative value rejects with a
+ * RangeError instead of arming a 1 ms timer.
  */
 export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, componentId: string, phase: string): Promise<T>;
 /**

package/dist/lifecycleInternal/asyncUtils.core.js

@@ -4,15 +4,24 @@
  * Async utilities for timeout, abort, and concurrency control.
  */
 import { LifecycleTimeoutError } from "@zudojs/errors";
+import { assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
 /**
  * Executes an async operation with a timeout.
  * Throws LifecycleTimeoutError if the timeout is exceeded.
+ *
+ * `Infinity` runs the operation unbounded; values above the largest
+ * timer delay are clamped to it. NaN or a negative value rejects with a
+ * RangeError instead of arming a 1 ms timer.
  */
 export async function withTimeout(fn, timeoutMs, componentId, phase) {
+    assertTimeoutBudget("timeout", timeoutMs);
+    if (!isBounded(timeoutMs)) {
+        return fn();
+    }
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             reject(new LifecycleTimeoutError(componentId, phase, timeoutMs));
-        }, timeoutMs);
+        }, toTimerDelay(timeoutMs));
         // The timer must be cleared on EVERY exit path. A synchronously
         // throwing `fn` used to escape before `.catch` was attached,
         // leaving an armed timer that kept the event loop alive for the
@@ -47,7 +56,19 @@ export async function withAbort(fn, signal) {
             reject(new Error("Operation aborted"));
         };
         signal.addEventListener("abort", onAbort, { once: true });
-        fn(signal)
+        // A synchronously throwing `fn` rejected via the Promise executor
+        // but skipped both `.then` branches, so its abort listener was
+        // never removed and accumulated on a long-lived signal.
+        let operation;
+        try {
+            operation = fn(signal);
+        }
+        catch (error) {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+            return;
+        }
+        operation
             .then((result) => {
             signal.removeEventListener("abort", onAbort);
             resolve(result);

package/dist/lifecycleInternal/index.d.ts

@@ -7,4 +7,5 @@ export { DependencyGraph } 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

@@ -6,4 +6,5 @@
 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

@@ -0,0 +1,30 @@
+/**
+ * @zudojs/lifecycle/internal/timeout-budget
+ *
+ * Validation and normalisation for millisecond budgets handed to timers.
+ */
+/** Largest delay `setTimeout` can represent (2^31 - 1 ms). */
+export declare const MAX_TIMER_DELAY = 2147483647;
+/**
+ * Validates a millisecond budget.
+ *
+ * `Infinity` is accepted and means "no bound". NaN, negative values and
+ * non-numbers are rejected up front: `setTimeout` silently turns them
+ * (and `Infinity`) into a 1 ms timer, and `LifecycleTimeoutError`'s
+ * constructor then threw inside that timer callback, which crashed the
+ * process instead of failing the component.
+ *
+ * @param name - Option name, used in the error message.
+ * @param value - The budget to check.
+ * @throws RangeError when the value is not a non-negative number.
+ */
+export declare function assertTimeoutBudget(name: string, value: unknown): void;
+/**
+ * Whether a validated budget actually bounds anything.
+ */
+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

@@ -0,0 +1,38 @@
+/**
+ * @zudojs/lifecycle/internal/timeout-budget
+ *
+ * Validation and normalisation for millisecond budgets handed to timers.
+ */
+/** Largest delay `setTimeout` can represent (2^31 - 1 ms). */
+export const MAX_TIMER_DELAY = 2_147_483_647;
+/**
+ * Validates a millisecond budget.
+ *
+ * `Infinity` is accepted and means "no bound". NaN, negative values and
+ * non-numbers are rejected up front: `setTimeout` silently turns them
+ * (and `Infinity`) into a 1 ms timer, and `LifecycleTimeoutError`'s
+ * constructor then threw inside that timer callback, which crashed the
+ * process instead of failing the component.
+ *
+ * @param name - Option name, used in the error message.
+ * @param value - The budget to check.
+ * @throws RangeError when the value is not a non-negative number.
+ */
+export function assertTimeoutBudget(name, value) {
+    if (typeof value !== "number" || Number.isNaN(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative number of milliseconds (Infinity for no bound), got ${String(value)}.`);
+    }
+}
+/**
+ * Whether a validated budget actually bounds anything.
+ */
+export function isBounded(value) {
+    return Number.isFinite(value);
+}
+/**
+ * Clamps a finite budget to what a timer can represent.
+ */
+export function toTimerDelay(value) {
+    return Math.min(Math.max(0, value), MAX_TIMER_DELAY);
+}
+//# sourceMappingURL=timeoutBudget.core.js.map

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

@@ -5,6 +5,7 @@
  * plus helper functions for component state transitions and event emission.
  */
 import { LifecycleState } from "@zudojs/constants";
+import type { LifecyclePhase } from "@zudojs/constants";
 import type { LifecycleStateMachine } from "../lifecycleState/lifecycleState.machine.js";
 import type { LifecycleRegistry } from "../lifecycleRegistry/lifecycleRegistry.core.js";
 import type { LifecycleExecutor } from "../lifecycleExecutor/lifecycleExecutor.core.js";
@@ -20,6 +21,16 @@ export interface LifecycleManagerContext {
     readonly shutdownTimeout: number;
     readonly componentStates: Map<string, LifecycleStateMachine>;
     readonly results: Map<string, ExecutionResult[]>;
+    /**
+     * Startup phases that were actually run for each component.
+     *
+     * 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.
+     */
+    readonly attempted: Map<string, Set<LifecyclePhase>>;
     startTime: number;
     /**
      * Cancellation source for the current run.
@@ -39,6 +50,16 @@ export interface LifecycleManagerContext {
      * teardown.
      */
     shutdownPromise?: Promise<void>;
+    /**
+     * The startup stage currently executing, if any.
+     *
+     * A shutdown requested mid-startup waits for this to settle before
+     * running `stop()`, so a component is never stopped while its own
+     * `start()` is still in flight, and startup checks for a requested
+     * shutdown before launching each further stage so no hook runs
+     * after teardown has completed.
+     */
+    inFlight?: Promise<unknown>;
 }
 /** Records an execution result against its component. */
 export declare function recordResult(ctx: LifecycleManagerContext, result: ExecutionResult): void;
@@ -47,6 +68,18 @@ export declare function recordResult(ctx: LifecycleManagerContext, result: Execu
  * No-op if the transition is not valid from the current state.
  */
 export declare function transitionComponent(ctx: LifecycleManagerContext, id: string, targetState: LifecycleState): void;
+/**
+ * Marks a component as FAILED regardless of its current state.
+ *
+ * Used for components that are skipped because a dependency failed:
+ * they have not entered the phase, so no validated transition leads to
+ * FAILED from their current (IDLE / INITIALIZED / STARTED) state.
+ */
+export declare function failComponent(ctx: LifecycleManagerContext, id: string): void;
+/** Records that a startup phase ran for a component. */
+export declare function markAttempted(ctx: LifecycleManagerContext, id: string, phase: LifecyclePhase): void;
+/** Returns whether a startup phase ran for a component. */
+export declare function wasAttempted(ctx: LifecycleManagerContext, id: string, phase: LifecyclePhase): boolean;
 /**
  * Transitions multiple component state machines to the same target state.
  */

package/dist/lifecycleManager/lifecycleManager.context.js

@@ -20,6 +20,26 @@ export function transitionComponent(ctx, id, targetState) {
         sm.transition(targetState);
     }
 }
+/**
+ * Marks a component as FAILED regardless of its current state.
+ *
+ * Used for components that are skipped because a dependency failed:
+ * they have not entered the phase, so no validated transition leads to
+ * FAILED from their current (IDLE / INITIALIZED / STARTED) state.
+ */
+export function failComponent(ctx, id) {
+    ctx.componentStates.get(id)?.forceState(LifecycleState.FAILED);
+}
+/** Records that a startup phase ran for a component. */
+export function markAttempted(ctx, id, phase) {
+    const phases = ctx.attempted.get(id) ?? new Set();
+    phases.add(phase);
+    ctx.attempted.set(id, phases);
+}
+/** Returns whether a startup phase ran for a component. */
+export function wasAttempted(ctx, id, phase) {
+    return ctx.attempted.get(id)?.has(phase) ?? false;
+}
 /**
  * Transitions multiple component state machines to the same target state.
  */

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

@@ -13,9 +13,16 @@ import { LifecycleEventEmitter } from "../lifecycleEvents/lifecycleEvents.core.j
 export interface LifecycleManagerOptions {
     /** Maximum concurrent component operations. */
     readonly concurrency?: number;
-    /** Global shutdown timeout in ms. */
+    /**
+     * Global shutdown timeout in ms. `Infinity` means no deadline; NaN
+     * and negative values are rejected by the constructor.
+     */
     readonly shutdownTimeout?: number;
-    /** Whether to automatically install signal handlers. */
+    /**
+     * Whether to install SIGINT/SIGTERM handlers. They are installed by
+     * `start()` (not the constructor) and removed once shutdown finishes,
+     * and a second signal during shutdown exits with code 1.
+     */
     readonly handleSignals?: boolean;
     /** Signals to listen for. */
     readonly signals?: readonly NodeJS.Signals[];
@@ -37,6 +44,8 @@ export declare class LifecycleManager {
     private readonly _ctx;
     private _startPromise?;
     private _removeSignalHandlers?;
+    private readonly _handleSignals;
+    private readonly _signals;
     constructor(options?: LifecycleManagerOptions);
     /** Registers a component with the lifecycle manager. */
     register(component: LifecycleComponent, options?: LifecycleRegistrationOptions): void;
@@ -50,6 +59,7 @@ export declare class LifecycleManager {
      * Idempotent — returns the same promise if called multiple times.
      */
     shutdown(): Promise<void>;
+    private releaseSignalHandlers;
     /** Returns the current application state. */
     get state(): LifecycleState;
     /** Returns the event emitter for lifecycle events. */

package/dist/lifecycleManager/lifecycleManager.core.js

@@ -12,6 +12,7 @@ import { LifecycleEventEmitter } from "../lifecycleEvents/lifecycleEvents.core.j
 import { installSignalHandlers } from "../lifecycleSignal/lifecycleSignal.handler.js";
 import { performStartup } from "./lifecycleManager.startup.js";
 import { performShutdown } from "./lifecycleManager.shutdown.js";
+import { assertTimeoutBudget } from "../lifecycleInternal/index.js";
 /**
  * Orchestrates application and component lifecycle.
  *
@@ -29,7 +30,12 @@ export class LifecycleManager {
     _ctx;
     _startPromise;
     _removeSignalHandlers;
+    _handleSignals;
+    _signals;
     constructor(options = {}) {
+        if (options.shutdownTimeout !== undefined) {
+            assertTimeoutBudget("shutdownTimeout", options.shutdownTimeout);
+        }
         this._ctx = {
             registry: new LifecycleRegistry(),
             state: new LifecycleStateMachine("application"),
@@ -39,17 +45,16 @@ export class LifecycleManager {
             shutdownTimeout: options.shutdownTimeout ?? LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT,
             componentStates: new Map(),
             results: new Map(),
+            attempted: new Map(),
             startTime: 0,
             controller: new AbortController(),
         };
-        if (options.handleSignals !== false) {
-            this._removeSignalHandlers = installSignalHandlers({
-                signals: options.signals,
-                handler: () => {
-                    void this.shutdown();
-                },
-            });
-        }
+        // Installing in the constructor disabled Ctrl-C for the whole
+        // process as soon as a manager existed (tests, libraries), and the
+        // listener outlived shutdown, so a process with a leaked handle
+        // could no longer be interrupted.
+        this._handleSignals = options.handleSignals !== false;
+        this._signals = options.signals;
     }
     /** Registers a component with the lifecycle manager. */
     register(component, options = {}) {
@@ -69,7 +74,20 @@ export class LifecycleManager {
         if (this._startPromise) {
             return this._startPromise;
         }
-        this._startPromise = performStartup(this._ctx);
+        if (this._handleSignals && this._removeSignalHandlers === undefined) {
+            this._removeSignalHandlers = installSignalHandlers({
+                signals: this._signals,
+                handler: () => {
+                    void this.shutdown();
+                },
+            });
+        }
+        this._startPromise = performStartup(this._ctx).catch(async (error) => {
+            // A failed startup rolls back through the shared shutdown.
+            await this._ctx.shutdownPromise?.catch(() => undefined);
+            this.releaseSignalHandlers();
+            throw error;
+        });
         return this._startPromise;
     }
     /**
@@ -79,7 +97,16 @@ export class LifecycleManager {
     async shutdown() {
         // performShutdown is itself single-flight, so a shutdown started by
         // startup rollback and one started here are the SAME run.
-        return performShutdown(this._ctx);
+        try {
+            await performShutdown(this._ctx);
+        }
+        finally {
+            this.releaseSignalHandlers();
+        }
+    }
+    releaseSignalHandlers() {
+        this._removeSignalHandlers?.();
+        this._removeSignalHandlers = undefined;
     }
     /** Returns the current application state. */
     get state() {
@@ -111,8 +138,7 @@ export class LifecycleManager {
      * component teardown — call `shutdown()` first for that.
      */
     dispose() {
-        this._removeSignalHandlers?.();
-        this._removeSignalHandlers = undefined;
+        this.releaseSignalHandlers();
         this._ctx.events.clear();
     }
 }

package/dist/lifecycleManager/lifecycleManager.shutdown.js

@@ -6,7 +6,8 @@
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-import { emitComponentFailed, recordResult, transitionComponent, } from "./lifecycleManager.context.js";
+import { isBounded, toTimerDelay } from "../lifecycleInternal/index.js";
+import { emitComponentFailed, recordResult, transitionComponent, wasAttempted, } from "./lifecycleManager.context.js";
 /** Shutdown phases in execution order. */
 const SHUTDOWN_PHASES = [LifecyclePhase.STOP, LifecyclePhase.DISPOSE];
 /**
@@ -38,6 +39,16 @@ async function runShutdown(ctx) {
     }
     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.
+    if (ctx.inFlight !== undefined) {
+        await raceDeadline(ctx, 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
@@ -72,12 +83,19 @@ async function runShutdown(ctx) {
  * 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();
-        }, remainingMs);
+        }, toTimerDelay(remainingMs));
     });
     try {
         await Promise.race([phase, expiry]);
@@ -91,11 +109,24 @@ async function raceDeadline(ctx, phase, remainingMs) {
     // rejection once the race has been decided.
     void phase.catch(() => { });
 }
-/** Executes a single shutdown phase across all registered components. */
+/**
+ * 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.
+ */
 async function executeShutdownPhase(ctx, phase) {
     const plan = buildExecutionPlan(ctx.registry.getAll(), phase);
     const context = createLifecycleContext(phase, ctx.startTime, ctx.controller.signal);
-    const failureState = phase === LifecyclePhase.STOP
+    const isStop = phase === LifecyclePhase.STOP;
+    const prerequisite = isStop
+        ? LifecyclePhase.START
+        : LifecyclePhase.INITIALIZE;
+    const successState = isStop
         ? LifecycleState.STOPPED
         : LifecycleState.DISPOSED;
     for (const stage of plan.stages) {
@@ -104,13 +135,30 @@ async function executeShutdownPhase(ctx, phase) {
             .filter((r) => r !== undefined);
         if (stageRegs.length === 0)
             continue;
+        const runnable = [];
         for (const reg of stageRegs) {
-            transitionComponent(ctx, reg.id, LifecycleState.STOPPING);
+            if (!wasAttempted(ctx, reg.id, prerequisite)) {
+                // Never reached the phase this hook undoes. It still ends up
+                // DISPOSED so status reflects the teardown.
+                if (!isStop) {
+                    transitionComponent(ctx, reg.id, LifecycleState.DISPOSED);
+                }
+                continue;
+            }
+            runnable.push(reg);
+            // Only the stop phase moves a component into STOPPING; dispose
+            // runs from STOPPED (or FAILED) and transitions straight to
+            // DISPOSED.
+            if (isStop) {
+                transitionComponent(ctx, reg.id, LifecycleState.STOPPING);
+            }
             ctx.events.emit("component:stopping", {
                 component: { componentId: reg.id },
             });
         }
-        const results = await ctx.executor.executeStage(stageRegs, phase, context, ctx.concurrency);
+        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
@@ -118,7 +166,7 @@ async function executeShutdownPhase(ctx, phase) {
         for (const result of results) {
             recordResult(ctx, result);
             if (result.success) {
-                transitionComponent(ctx, result.id, failureState);
+                transitionComponent(ctx, result.id, successState);
                 ctx.events.emit("component:stopped", {
                     component: { componentId: result.id, duration: result.duration },
                 });

package/dist/lifecycleManager/lifecycleManager.startup.js

@@ -4,10 +4,10 @@
  * Startup orchestration — initializes, starts, and readies components.
  */
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
-import { LifecycleStartError } from "@zudojs/errors";
+import { LifecycleComponentError, LifecycleStartError } from "@zudojs/errors";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-import { transitionComponent, transitionComponentBatch, emitComponentFailed, recordResult, } from "./lifecycleManager.context.js";
+import { transitionComponent, transitionComponentBatch, emitComponentFailed, failComponent, markAttempted, recordResult, } from "./lifecycleManager.context.js";
 import { performShutdown } from "./lifecycleManager.shutdown.js";
 /** Maps startup phases to their target component state after success. */
 const SUCCESS_STATE = {
@@ -68,6 +68,7 @@ export async function performStartup(ctx) {
         if (failedInit) {
             throw new LifecycleStartError(failedInit.id, failedInit.error);
         }
+        assertNotShuttingDown(ctx, LifecyclePhase.INITIALIZE);
         ctx.state.transition(LifecycleState.INITIALIZED);
         ctx.events.emit("application:initialized", {
             duration: Date.now() - ctx.startTime,
@@ -77,6 +78,7 @@ export async function performStartup(ctx) {
         if (failedStart) {
             throw new LifecycleStartError(failedStart.id, failedStart.error);
         }
+        assertNotShuttingDown(ctx, LifecyclePhase.START);
         ctx.state.transition(LifecycleState.STARTED);
         // A failing `ready` hook on a critical component used to be
         // ignored completely: no state change, no rollback, and start()
@@ -85,6 +87,7 @@ export async function performStartup(ctx) {
         if (failedReady) {
             throw new LifecycleStartError(failedReady.id, failedReady.error);
         }
+        assertNotShuttingDown(ctx, LifecyclePhase.READY);
         ctx.state.transition(LifecycleState.READY);
         ctx.events.emit("application:ready", {
             duration: Date.now() - ctx.startTime,
@@ -94,7 +97,10 @@ export async function performStartup(ctx) {
         // Rollback happens on exactly one path, so a completed teardown is
         // never re-entered and its DISPOSED state is never overwritten
         // with FAILED.
-        if (ctx.state.state !== LifecycleState.FAILED &&
+        // When the failure IS a requested shutdown, the teardown already
+        // owns the application state.
+        if (ctx.shutdownPromise === undefined &&
+            ctx.state.state !== LifecycleState.FAILED &&
             ctx.state.state !== LifecycleState.DISPOSED) {
             ctx.state.forceState(LifecycleState.FAILED);
         }
@@ -102,9 +108,40 @@ export async function performStartup(ctx) {
         throw error;
     }
 }
+/**
+ * Throws when a shutdown has been requested while startup is running.
+ *
+ * Startup used to keep launching later stages after `shutdown()` had
+ * already torn everything down: a component started that way was
+ * never stopped, and the eventual failure was an opaque
+ * LifecycleStateError from the DISPOSED → INITIALIZED transition.
+ */
+function assertNotShuttingDown(ctx, phase) {
+    if (ctx.shutdownPromise !== undefined) {
+        throw new LifecycleStartError("application", new LifecycleComponentError("application", phase, new Error("Startup was cancelled because shutdown was requested while the application was starting.")));
+    }
+}
 /**
  * Executes a single startup phase across all registered components.
  * Returns the failure of the first critical component, or undefined.
+ *
+ * Two bookkeeping rules apply to every stage:
+ *
+ * - A component that FAILED an earlier phase, or whose dependency has
+ *   failed, does not enter this phase. It used to have `start()` and
+ *   `ready()` invoked after its own `initialize()` had thrown, and its
+ *   dependents were started as if the dependency were healthy —
+ *   silently voiding the `dependsOn` contract. A skipped dependent is
+ *   recorded as FAILED with a LifecycleComponentError naming the
+ *   failed dependency, and its own `critical` flag decides whether
+ *   startup aborts.
+ *
+ * - Every result of a stage is recorded, transitioned and announced
+ *   before a critical failure aborts the phase. Returning on the first
+ *   failed result dropped the results of siblings in the same stage,
+ *   which were then left in INITIALIZING / STARTING forever (no
+ *   transition leads out of those states except to their success or
+ *   FAILED) even after rollback had disposed them.
  */
 async function executePhase(ctx, phase) {
     const plan = buildExecutionPlan(ctx.registry.getAll(), phase);
@@ -117,21 +154,62 @@ async function executePhase(ctx, phase) {
             .filter((r) => r !== undefined);
         if (stageRegs.length === 0)
             continue;
-        transitionComponentBatch(ctx, stageRegs.map((r) => r.id), EXECUTING_STATE[phase]);
+        assertNotShuttingDown(ctx, phase);
+        const runnable = [];
+        let criticalFailure;
         for (const reg of stageRegs) {
+            if (ctx.componentStates.get(reg.id)?.state === LifecycleState.FAILED) {
+                // Already failed in an earlier phase; nothing more to run.
+                continue;
+            }
+            const failedDependency = reg.dependsOn.find((dep) => ctx.componentStates.get(dep)?.state === LifecycleState.FAILED);
+            if (failedDependency === undefined) {
+                runnable.push(reg);
+                continue;
+            }
+            const skipped = {
+                id: reg.id,
+                phase,
+                duration: 0,
+                success: false,
+                error: new LifecycleComponentError(reg.id, phase, new Error(`Component "${reg.id}" was not started because its dependency "${failedDependency}" failed.`)),
+            };
+            recordResult(ctx, skipped);
+            failComponent(ctx, reg.id);
+            emitComponentFailed(ctx, skipped);
+            if (reg.critical) {
+                criticalFailure ??= { id: reg.id, error: skipped.error };
+            }
+        }
+        if (criticalFailure) {
+            ctx.state.forceState(LifecycleState.FAILED);
+            return criticalFailure;
+        }
+        if (runnable.length === 0)
+            continue;
+        transitionComponentBatch(ctx, runnable.map((r) => r.id), EXECUTING_STATE[phase]);
+        for (const reg of runnable) {
+            markAttempted(ctx, reg.id, phase);
             ctx.events.emit(events.begin, {
                 component: { componentId: reg.id },
             });
         }
-        const results = await ctx.executor.executeStage(stageRegs, phase, context, ctx.concurrency);
+        const pending = ctx.executor.executeStage(runnable, phase, context, ctx.concurrency);
+        ctx.inFlight = pending;
+        let results;
+        try {
+            results = await pending;
+        }
+        finally {
+            ctx.inFlight = undefined;
+        }
         for (const result of results) {
             recordResult(ctx, result);
             if (!result.success) {
                 transitionComponent(ctx, result.id, LifecycleState.FAILED);
                 emitComponentFailed(ctx, result);
                 if (ctx.registry.get(result.id)?.critical) {
-                    ctx.state.forceState(LifecycleState.FAILED);
-                    return { id: result.id, error: result.error };
+                    criticalFailure ??= { id: result.id, error: result.error };
                 }
             }
             else {
@@ -141,6 +219,10 @@ async function executePhase(ctx, phase) {
                 });
             }
         }
+        if (criticalFailure) {
+            ctx.state.forceState(LifecycleState.FAILED);
+            return criticalFailure;
+        }
     }
     return undefined;
 }

package/dist/lifecycleRegistry/lifecycleRegistry.core.js

@@ -4,7 +4,7 @@
  * Lifecycle registry — manages component registration, validation, and lookup.
  */
 import { LIFECYCLE_DEFAULT_TIMEOUT } from "@zudojs/constants";
-import { DependencyGraph } from "../lifecycleInternal/index.js";
+import { DependencyGraph, assertTimeoutBudget, } from "../lifecycleInternal/index.js";
 /**
  * Registry for lifecycle components.
  * Validates registration, builds dependency graph, and freezes on demand.
@@ -19,6 +19,9 @@ export class LifecycleRegistry {
             throw new Error("Cannot register components after registry is frozen");
         }
         const id = options.id ?? component.name;
+        if (options.timeout !== undefined) {
+            assertTimeoutBudget(`Component "${id}" timeout`, options.timeout);
+        }
         if (this._registrations.has(id)) {
             throw new Error(`Component "${id}" is already registered`);
         }

package/dist/lifecycleSignal/lifecycleSignal.handler.d.ts

@@ -9,6 +9,15 @@ export interface SignalHandlerOptions {
     readonly signals?: readonly NodeJS.Signals[];
     /** Function to call when a signal is received. */
     readonly handler: () => void;
+    /**
+     * Whether a second signal, received while the first is still being
+     * handled, exits the process with code 1. Defaults to `true`: the
+     * installed listener replaces Node's default exit, so without this a
+     * wedged shutdown could not be interrupted short of SIGKILL.
+     */
+    readonly forceExitOnSecondSignal?: boolean;
+    /** Exit hook, injected for testing. Defaults to `process.exit`. */
+    readonly exit?: (code: number) => void;
 }
 /** Default signal configuration for graceful shutdown. */
 export declare const DEFAULT_SHUTDOWN_SIGNALS: readonly NodeJS.Signals[];

package/dist/lifecycleSignal/lifecycleSignal.handler.js

@@ -15,9 +15,18 @@ export function installSignalHandlers(options) {
     // changing the constant had no effect on the actual default.
     const signals = options.signals ?? DEFAULT_SHUTDOWN_SIGNALS;
     const handler = options.handler;
+    const forceExit = options.forceExitOnSecondSignal ?? true;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    let received = false;
     const installed = [];
     for (const signal of signals) {
         const listener = () => {
+            if (received) {
+                if (forceExit)
+                    exit(1);
+                return;
+            }
+            received = true;
             handler();
         };
         process.on(signal, listener);

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/lifecycle",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Application and component lifecycle orchestration with state machine, dependency ordering, graceful shutdown, rollback, and signals.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -20,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/constants": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",