@zudojs/lifecycle 1.1.0 → 1.2.0

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
@@ -109,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
 });
 ```
@@ -118,6 +124,25 @@ createLifecycleManager({
 Per-component: `id`, `dependsOn`, `priority`, `critical`, `timeout`,
 `retry: { attempts, delay, maxDelay, backoff }`.
 
+`priority` orders components that share a dependency level, and it is a
+barrier rather than a hint: every component at one priority completes the
+phase before the next priority starts, so `priority: 10` really does start
+before `priority: 0`. Components sharing a priority still run together, up
+to `concurrency`. Shutdown mirrors it — within a level the lowest priority
+stops first and the highest stops last.
+
+`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

@@ -28,11 +28,21 @@ export interface LifecycleRegistrationOptions {
     readonly id?: string;
     /** IDs of components that must start before this one. */
     readonly dependsOn?: readonly string[];
-    /** Priority for ordering within the same dependency level. Higher = earlier. */
+    /**
+     * Priority for ordering within the same dependency level. Higher = earlier.
+     *
+     * Priority is a barrier, not a hint: every component at one priority
+     * finishes the phase before the next priority begins, and shutdown
+     * runs the mirror image (lowest priority stops first). Components
+     * sharing a priority still run concurrently.
+     */
     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,12 +23,29 @@ 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.
      */
     execute(registration: LifecycleRegistration, phase: LifecyclePhase, context: LifecycleContext): Promise<ExecutionResult>;
     /**
-     * Executes a stage of components in parallel with concurrency limit.
+     * Executes a stage of components, honouring priority as a barrier.
+     *
+     * The stage arrives already ordered by priority (descending for
+     * startup, ascending for shutdown). Components sharing a priority run
+     * together, limited by `concurrency`; the next priority group only
+     * begins once the previous one has settled. Launching the whole stage
+     * concurrently made `priority` observable only at `concurrency: 1`,
+     * so a `priority: 100` component documented as starting first lost
+     * the race to any sibling with a faster hook.
      */
     executeStage(registrations: readonly LifecycleRegistration[], phase: LifecyclePhase, context: LifecycleContext, concurrency: number): Promise<readonly ExecutionResult[]>;
 }

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);
@@ -72,17 +96,49 @@ export class LifecycleExecutor {
         };
     }
     /**
-     * Executes a stage of components in parallel with concurrency limit.
+     * Executes a stage of components, honouring priority as a barrier.
+     *
+     * The stage arrives already ordered by priority (descending for
+     * startup, ascending for shutdown). Components sharing a priority run
+     * together, limited by `concurrency`; the next priority group only
+     * begins once the previous one has settled. Launching the whole stage
+     * concurrently made `priority` observable only at `concurrency: 1`,
+     * so a `priority: 100` component documented as starting first lost
+     * the race to any sibling with a faster hook.
      */
     async executeStage(registrations, phase, context, concurrency) {
         const results = [];
-        await withConcurrency(registrations, concurrency, async (reg) => {
-            const result = await this.execute(reg, phase, context);
-            results.push(result);
-        });
+        for (const batch of groupByPriority(registrations)) {
+            await withConcurrency(batch, concurrency, async (reg) => {
+                const result = await this.execute(reg, phase, context);
+                results.push(result);
+            });
+        }
         return results;
     }
 }
+/**
+ * Splits an already-ordered stage into runs of equal priority.
+ *
+ * Consecutive grouping preserves whatever order the execution plan
+ * produced, so a caller that does not care about priority (every
+ * component at the default 0) still gets a single fully concurrent
+ * batch.
+ */
+function groupByPriority(registrations) {
+    const batches = [];
+    let current;
+    let currentPriority;
+    for (const reg of registrations) {
+        if (current === undefined || reg.priority !== currentPriority) {
+            current = [];
+            currentPriority = reg.priority;
+            batches.push(current);
+        }
+        current.push(reg);
+    }
+    return batches;
+}
 /** Calculates retry delay with backoff. */
 function calculateDelay(config, attempt) {
     const base = config.delay ?? 500;

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

@@ -3,16 +3,25 @@
  *
  * Async utilities for timeout, abort, and concurrency control.
  */
-import { LifecycleTimeoutError } from "@zudojs/errors";
+import { ErrorCode, LifecycleError, 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
@@ -40,11 +49,11 @@ export async function withTimeout(fn, timeoutMs, componentId, phase) {
  */
 export async function withAbort(fn, signal) {
     if (signal.aborted) {
-        throw new Error("Operation aborted");
+        throw abortError();
     }
     return new Promise((resolve, reject) => {
         const onAbort = () => {
-            reject(new Error("Operation aborted"));
+            reject(abortError());
         };
         signal.addEventListener("abort", onAbort, { once: true });
         // A synchronously throwing `fn` rejected via the Promise executor
@@ -70,6 +79,12 @@ export async function withAbort(fn, signal) {
         });
     });
 }
+/** The typed error surfaced when a `withAbort` operation is cancelled. */
+function abortError() {
+    return new LifecycleError("Operation aborted", {
+        code: ErrorCode.LIFECYCLE_COMPONENT,
+    });
+}
 /**
  * Executes async operations with a concurrency limit.
  */

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/lifecycleInternal/topologicalSort.core.d.ts

@@ -14,6 +14,13 @@ export type TopologicalStage = readonly string[];
 export declare function topologicalSort(graph: DependencyGraph, priorities?: ReadonlyMap<string, number>): readonly TopologicalStage[];
 /**
  * Performs reverse topological sort for shutdown ordering.
+ *
+ * Both the stage list AND each stage's contents are reversed, so a
+ * shutdown is the exact mirror of the startup order: within a stage the
+ * lowest-priority component is torn down first and the highest-priority
+ * one last. Only the stage list used to be reversed, which left every
+ * stage in descending-priority order — harmless while stages ran fully
+ * 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

@@ -42,9 +42,16 @@ export function topologicalSort(graph, priorities) {
 }
 /**
  * Performs reverse topological sort for shutdown ordering.
+ *
+ * Both the stage list AND each stage's contents are reversed, so a
+ * shutdown is the exact mirror of the startup order: within a stage the
+ * lowest-priority component is torn down first and the highest-priority
+ * one last. Only the stage list used to be reversed, which left every
+ * stage in descending-priority order — harmless while stages ran fully
+ * concurrently, but wrong now that priority is a real sub-stage barrier.
  */
 export function reverseTopologicalSort(graph, priorities) {
     const stages = topologicalSort(graph, priorities);
-    return Object.freeze([...stages].reverse().map((stage) => Object.freeze([...stage])));
+    return Object.freeze([...stages].reverse().map((stage) => Object.freeze([...stage].reverse())));
 }
 //# sourceMappingURL=topologicalSort.core.js.map

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"),
@@ -43,14 +49,12 @@ export class LifecycleManager {
             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 = {}) {
@@ -70,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;
     }
     /**
@@ -80,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() {
@@ -112,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,6 +6,7 @@
 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";
 /** Shutdown phases in execution order. */
 const SHUTDOWN_PHASES = [LifecyclePhase.STOP, LifecyclePhase.DISPOSE];
@@ -45,6 +46,9 @@ async function runShutdown(ctx) {
     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
@@ -62,6 +66,14 @@ async function runShutdown(ctx) {
         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", {
@@ -79,12 +91,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]);

package/dist/lifecycleRegistry/lifecycleRegistry.core.js

@@ -4,7 +4,8 @@
  * 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";
+import { ErrorCode, LifecycleError } from "@zudojs/errors";
 /**
  * Registry for lifecycle components.
  * Validates registration, builds dependency graph, and freezes on demand.
@@ -16,11 +17,17 @@ export class LifecycleRegistry {
     /** Registers a component with optional configuration. */
     register(component, options = {}) {
         if (this._frozen) {
-            throw new Error("Cannot register components after registry is frozen");
+            throw new LifecycleError("Cannot register components after registry is frozen", { code: ErrorCode.LIFECYCLE_COMPONENT });
         }
         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`);
+            throw new LifecycleError(`Component "${id}" is already registered`, {
+                code: ErrorCode.LIFECYCLE_COMPONENT,
+                componentId: id,
+            });
         }
         const registration = {
             id,
@@ -48,7 +55,11 @@ export class LifecycleRegistry {
         for (const [id, reg] of this._registrations) {
             for (const dep of reg.dependsOn) {
                 if (!this._registrations.has(dep)) {
-                    throw new Error(`Component "${id}" depends on "${dep}" which is not registered`);
+                    throw new LifecycleError(`Component "${id}" depends on "${dep}" which is not registered`, {
+                        code: ErrorCode.LIFECYCLE_DEPENDENCY,
+                        componentId: id,
+                        metadata: { dependency: dep },
+                    });
                 }
             }
         }

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,6 +1,6 @@
 {
   "name": "@zudojs/lifecycle",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Application and component lifecycle orchestration with state machine, dependency ordering, graceful shutdown, rollback, and signals.",
   "license": "MIT",
   "author": {
@@ -24,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/constants": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",