@zudojs/runtime 1.1.0 → 1.2.1

package/README.md

@@ -2,6 +2,12 @@
 
 Application lifecycle orchestrator with dependency ordering, rollback, signals, and readiness checks.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-runtime](https://zudojs.oyinlola.site/docs/packages-runtime) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-runtime.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -126,6 +132,9 @@ createRuntime(dependencies, {
   runtimeId: "rt_custom", // generated when omitted
   handleSignals: true, // SIGTERM/SIGINT trigger a graceful stop
   handleFatalErrors: true, // uncaughtException/unhandledRejection
+  exitOnFatalError: true, // exit(1) once a fatal-error shutdown finishes
+  fatalExitTimeout: 10_000, // exit(1) anyway if that shutdown hangs
+  forceExitOnSecondSignal: true, // a second SIGTERM/SIGINT exits at once
   startupTimeout: 60_000,
   shutdownTimeout: 30_000,
   emitEvents: true,
@@ -137,6 +146,17 @@ createRuntime(dependencies, {
 });
 ```
 
+`startupTimeout` abandons the startup: no further module hook starts,
+and a module whose `onInitialize` or `onReady` finishes after the timeout
+is shut down and destroyed as soon as it settles. `stop()` waits for that
+teardown (bounded by `shutdownTimeout`), so a stopped runtime never has a
+live module behind it. A second `stop()` after a shutdown timeout joins
+the teardown still running rather than calling `onShutdown` again.
+
+A configuration manager that fails to load fails startup with a
+`RuntimeStartError` (`phase: "initialize"`) instead of letting modules
+initialize against partial configuration.
+
 `parallelInitialization` initializes modules that share a dependency depth
 concurrently. They do not depend on one another by construction, but
 enabling it surfaces any ordering a module assumed without declaring, so

package/dist/lifecycle/lifecycle.cancellation.d.ts

@@ -0,0 +1,41 @@
+import type { Logger } from "@zudojs/logger";
+import type { Module, ModuleContext } from "@zudojs/core";
+/**
+ * Tracks module hooks that are still running after their startup was
+ * abandoned (by a startup timeout or a rollback).
+ *
+ * `Promise.race` cannot cancel the losing side, so a slow `onInitialize`
+ * or `onReady` keeps running after the runtime has already reported a
+ * failed start. Without this bookkeeping the late module came up with no
+ * owner left to stop it: a timed-out boot reported `failed` and then
+ * `stopped` while the module's server was listening.
+ */
+export declare class LifecycleCancellation {
+    private cancelled;
+    private readonly running;
+    private readonly releases;
+    /** Whether the current startup has been abandoned. */
+    get isCancelled(): boolean;
+    /** Abandons the current startup. Idempotent. */
+    cancel(): void;
+    /** Clears the cancelled flag for a new startup. */
+    reset(): void;
+    /** Whether a hook for `moduleId` is currently running. */
+    isRunning(moduleId: string): boolean;
+    /**
+     * Records a running hook for `moduleId` until it settles.
+     */
+    track<T>(moduleId: string, hook: Promise<T>): Promise<T>;
+    /**
+     * Tears down a module whose hook completed after the startup was
+     * abandoned: `onShutdown` when it had reached `onReady`, then
+     * `onDestroy`. The teardown is tracked so {@link settle} waits for it.
+     */
+    release(module: Module, context: ModuleContext, started: boolean, logger: Logger): Promise<void>;
+    /**
+     * Waits until every abandoned hook has settled and every late module
+     * has been torn down.
+     */
+    settle(): Promise<void>;
+}
+//# sourceMappingURL=lifecycle.cancellation.d.ts.map

package/dist/lifecycle/lifecycle.cancellation.js

@@ -0,0 +1,92 @@
+/**
+ * Tracks module hooks that are still running after their startup was
+ * abandoned (by a startup timeout or a rollback).
+ *
+ * `Promise.race` cannot cancel the losing side, so a slow `onInitialize`
+ * or `onReady` keeps running after the runtime has already reported a
+ * failed start. Without this bookkeeping the late module came up with no
+ * owner left to stop it: a timed-out boot reported `failed` and then
+ * `stopped` while the module's server was listening.
+ */
+export class LifecycleCancellation {
+    cancelled = false;
+    running = new Map();
+    releases = new Set();
+    /** Whether the current startup has been abandoned. */
+    get isCancelled() {
+        return this.cancelled;
+    }
+    /** Abandons the current startup. Idempotent. */
+    cancel() {
+        this.cancelled = true;
+    }
+    /** Clears the cancelled flag for a new startup. */
+    reset() {
+        this.cancelled = false;
+    }
+    /** Whether a hook for `moduleId` is currently running. */
+    isRunning(moduleId) {
+        return this.running.has(moduleId);
+    }
+    /**
+     * Records a running hook for `moduleId` until it settles.
+     */
+    track(moduleId, hook) {
+        this.running.set(moduleId, hook);
+        const clear = () => {
+            if (this.running.get(moduleId) === hook) {
+                this.running.delete(moduleId);
+            }
+        };
+        hook.then(clear, clear);
+        return hook;
+    }
+    /**
+     * Tears down a module whose hook completed after the startup was
+     * abandoned: `onShutdown` when it had reached `onReady`, then
+     * `onDestroy`. The teardown is tracked so {@link settle} waits for it.
+     */
+    release(module, context, started, logger) {
+        const release = releaseAbandonedModule(module, context, started, logger);
+        this.releases.add(release);
+        void release.finally(() => this.releases.delete(release));
+        return release;
+    }
+    /**
+     * Waits until every abandoned hook has settled and every late module
+     * has been torn down.
+     */
+    async settle() {
+        while (this.running.size > 0 || this.releases.size > 0) {
+            await Promise.allSettled([...this.running.values(), ...this.releases]);
+        }
+    }
+}
+/**
+ * Runs `onShutdown` (when the module had started) and `onDestroy` for a
+ * module that finished a hook after its startup was abandoned.
+ */
+async function releaseAbandonedModule(module, context, started, logger) {
+    logger.warn(`Module "${module.id}" finished a lifecycle hook after startup was abandoned; tearing it down.`);
+    if (started && module.onShutdown) {
+        try {
+            await module.onShutdown(context);
+        }
+        catch (error) {
+            logger.error(`Abandoned module "${module.id}" failed to shut down.`, {
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (module.onDestroy) {
+        try {
+            await module.onDestroy(context);
+        }
+        catch (error) {
+            logger.error(`Abandoned module "${module.id}" failed to destroy.`, {
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+//# sourceMappingURL=lifecycle.cancellation.js.map

package/dist/lifecycle/lifecycle.core.d.ts

@@ -11,10 +11,17 @@ export declare class LifecycleManager {
     private readonly onModuleEvent;
     private readonly runtimeId;
     private initializedModules;
+    /**
+     * Modules whose `onInitialize` threw. They may have acquired resources
+     * before failing, so teardown still runs their `onDestroy`, matching
+     * `@zudojs/lifecycle` and `@zudojs/core`.
+     */
+    private failedInitializations;
     private startedModules;
     private readonly configuration;
     private readonly application;
     private readonly contexts;
+    private readonly cancellation;
     constructor(modules: ReadonlyMap<string, Module>, logger: Logger, options?: LifecycleManagerOptions, services?: ModuleContextServices);
     /**
      * Publishes a per-module lifecycle event.
@@ -28,10 +35,30 @@ export declare class LifecycleManager {
      * so that `context.getConfiguration()` is usable from the first hook.
      */
     private ensureConfigurationReady;
+    /**
+     * Abandons an in-flight startup.
+     *
+     * No further module hook is started, and any module whose hook is
+     * still running when it settles is shut down and destroyed rather than
+     * left running with no owner. Called on a startup timeout and by
+     * {@link rollback}.
+     */
+    cancel(): void;
+    /** Whether the current startup has been abandoned by {@link cancel}. */
+    get cancelled(): boolean;
     /**
      * Initializes all modules in dependency order.
      */
     initialize(): Promise<LifecycleResult>;
+    /**
+     * Returns the first declared dependency of `moduleId` that is known to
+     * have failed or been skipped, or `undefined` when none has.
+     *
+     * Only direct dependencies are inspected: `blocked` already contains
+     * every module skipped by an earlier group, and groups are visited in
+     * dependency order, so the cascade is transitive.
+     */
+    private findBlockingDependency;
     /**
      * Initializes a single module, converting a throw into a failure.
      */

package/dist/lifecycle/lifecycle.core.js

@@ -1,7 +1,8 @@
 import { createConfigurationManager } from "@zudojs/core";
 import { createModuleEventPayload } from "../runtimeEvents/runtimeEvents.core.js";
 import { resolveDependencies } from "../dependencyGraph/index.js";
-import { RuntimeDependencyError, RuntimeStateError, } from "../runtimeError/index.js";
+import { LifecycleCancellation } from "./lifecycle.cancellation.js";
+import { RuntimeDependencyError, RuntimeStartError, RuntimeStateError, } from "../runtimeError/index.js";
 /**
  * Manages the lifecycle of runtime modules.
  */
@@ -12,10 +13,17 @@ export class LifecycleManager {
     onModuleEvent;
     runtimeId;
     initializedModules = [];
+    /**
+     * Modules whose `onInitialize` threw. They may have acquired resources
+     * before failing, so teardown still runs their `onDestroy`, matching
+     * `@zudojs/lifecycle` and `@zudojs/core`.
+     */
+    failedInitializations = [];
     startedModules = [];
     configuration;
     application;
     contexts = new Map();
+    cancellation = new LifecycleCancellation();
     constructor(modules, logger, options = {}, services = {}) {
         this.modules = modules;
         this.logger = logger;
@@ -24,7 +32,6 @@ export class LifecycleManager {
         this.onModuleEvent = options.onModuleEvent;
         this.runtimeId = options.runtimeId ?? "";
         this.options = {
-            shutdownTimeout: options.shutdownTimeout ?? 30_000,
             continueOnFailure: options.continueOnFailure ?? false,
             // Defaults to sequential: initializing a whole depth group at once
             // is a real behaviour change for modules that assume ordering
@@ -62,15 +69,33 @@ export class LifecycleManager {
         if (this.configuration.isReady()) {
             return;
         }
+        // Fail closed: a configuration that did not load must not let
+        // modules initialize against partial or unvalidated state.
         try {
             await this.configuration.initialize();
         }
         catch (error) {
-            this.logger.warn("Configuration failed to load.", {
-                error: error instanceof Error ? error.message : String(error),
+            throw new RuntimeStartError("Configuration failed to load.", {
+                phase: "initialize",
+                ...(error instanceof Error && { cause: error }),
             });
         }
     }
+    /**
+     * Abandons an in-flight startup.
+     *
+     * No further module hook is started, and any module whose hook is
+     * still running when it settles is shut down and destroyed rather than
+     * left running with no owner. Called on a startup timeout and by
+     * {@link rollback}.
+     */
+    cancel() {
+        this.cancellation.cancel();
+    }
+    /** Whether the current startup has been abandoned by {@link cancel}. */
+    get cancelled() {
+        return this.cancellation.isCancelled;
+    }
     /**
      * Initializes all modules in dependency order.
      */
@@ -79,7 +104,9 @@ export class LifecycleManager {
         // Reset the per-run bookkeeping. Appending across runs would make a
         // stop-then-start cycle initialize and stop every module twice.
         this.initializedModules = [];
+        this.failedInitializations = [];
         this.startedModules = [];
+        this.cancellation.reset();
         await this.ensureConfigurationReady();
         const succeeded = [];
         const failed = [];
@@ -89,15 +116,47 @@ export class LifecycleManager {
         const groups = this.options.parallelInitialization
             ? depGraph.parallelGroups
             : depGraph.order.map((moduleId) => [moduleId]);
+        // Ids that must not have dependents initialized on top of them:
+        // modules whose own hook threw, plus modules already skipped for the
+        // same reason, so the skip cascades transitively. `continueOnFailure`
+        // used to consult only the failure COUNT, so a dependent of a broken
+        // module was initialized, readied, and reported as started — an API
+        // serving traffic against a database that never came up.
+        const blocked = new Set();
         for (const group of groups) {
-            const results = await Promise.all(group.map((moduleId) => this.initializeModule(moduleId)));
+            if (this.cancellation.isCancelled) {
+                break;
+            }
+            const runnable = [];
+            for (const moduleId of group) {
+                const blocker = this.findBlockingDependency(moduleId, blocked);
+                if (blocker === undefined) {
+                    runnable.push(moduleId);
+                    continue;
+                }
+                const failure = {
+                    moduleId,
+                    phase: "initialize",
+                    error: new RuntimeStartError(`Module "${moduleId}" was not initialized because its ` +
+                        `dependency "${blocker}" failed.`, { phase: "initialize", failedModuleId: blocker }),
+                    durationMs: 0,
+                };
+                failed.push(failure);
+                blocked.add(moduleId);
+                this.logger.error(`Module "${moduleId}" was skipped because its dependency "${blocker}" failed.`);
+                this.emitModuleEvent("runtime.module.failed", moduleId, "failed", {
+                    durationMs: 0,
+                    error: failure.error,
+                });
+            }
+            const results = await Promise.all(runnable.map((moduleId) => this.initializeModule(moduleId)));
             for (const result of results) {
                 if (result.failure) {
                     failed.push(result.failure);
+                    blocked.add(result.moduleId);
                 }
-                else {
+                else if (!result.abandoned) {
                     succeeded.push(result.moduleId);
-                    this.initializedModules.push(result.moduleId);
                 }
             }
             if (failed.length > 0 && !this.options.continueOnFailure) {
@@ -111,6 +170,18 @@ export class LifecycleManager {
             durationMs: Date.now() - startTime,
         });
     }
+    /**
+     * Returns the first declared dependency of `moduleId` that is known to
+     * have failed or been skipped, or `undefined` when none has.
+     *
+     * Only direct dependencies are inspected: `blocked` already contains
+     * every module skipped by an earlier group, and groups are visited in
+     * dependency order, so the cascade is transitive.
+     */
+    findBlockingDependency(moduleId, blocked) {
+        const dependencies = this.modules.get(moduleId)?.dependencies ?? [];
+        return dependencies.find((dependency) => blocked.has(dependency));
+    }
     /**
      * Initializes a single module, converting a throw into a failure.
      */
@@ -131,8 +202,16 @@ export class LifecycleManager {
         this.emitModuleEvent("runtime.module.initializing", moduleId, "initializing");
         try {
             if (module.onInitialize) {
-                await module.onInitialize(this.createModuleContext(module));
+                await this.cancellation.track(moduleId, Promise.resolve(module.onInitialize(this.createModuleContext(module))));
             }
+            if (this.cancellation.isCancelled) {
+                await this.cancellation.release(module, this.createModuleContext(module), false, this.logger);
+                return { moduleId, abandoned: true };
+            }
+            // Recorded as soon as it succeeds, not after its whole depth group:
+            // a rollback that runs while a sibling is still initializing must
+            // still reach this module.
+            this.initializedModules.push(moduleId);
             const durationMs = Date.now() - startedAt;
             this.logger.debug(`Module "${moduleId}" initialized.`, { durationMs });
             this.emitModuleEvent("runtime.module.initialized", moduleId, "initialized", {
@@ -150,6 +229,12 @@ export class LifecycleManager {
             this.logger.error(`Module "${moduleId}" failed during initialization.`, {
                 error: failure.error,
             });
+            if (this.cancellation.isCancelled) {
+                await this.cancellation.release(module, this.createModuleContext(module), false, this.logger);
+            }
+            else {
+                this.failedInitializations.push(moduleId);
+            }
             this.emitModuleEvent("runtime.module.failed", moduleId, "failed", {
                 durationMs: failure.durationMs,
                 error: failure.error,
@@ -165,8 +250,10 @@ export class LifecycleManager {
         this.startedModules = [];
         const succeeded = [];
         const failed = [];
-        for (const moduleId of this.initializedModules) {
+        for (const moduleId of [...this.initializedModules]) {
             const module = this.modules.get(moduleId);
+            if (this.cancellation.isCancelled)
+                break;
             if (!module)
                 continue;
             const moduleStartTime = Date.now();
@@ -174,7 +261,18 @@ export class LifecycleManager {
             try {
                 if (module.onReady) {
                     const context = this.createModuleContext(module);
-                    await module.onReady(context);
+                    await this.cancellation
+                        .track(moduleId, Promise.resolve(module.onReady(context)))
+                        .catch(async (error) => {
+                        if (this.cancellation.isCancelled) {
+                            await this.cancellation.release(module, context, false, this.logger);
+                        }
+                        throw error;
+                    });
+                }
+                if (this.cancellation.isCancelled) {
+                    await this.cancellation.release(module, this.createModuleContext(module), true, this.logger);
+                    break;
                 }
                 succeeded.push(moduleId);
                 this.startedModules.push(moduleId);
@@ -218,11 +316,15 @@ export class LifecycleManager {
         const startTime = Date.now();
         const succeeded = [];
         const failed = [];
+        await this.cancellation.settle();
         const reversedModules = [...this.startedModules].reverse();
         for (const moduleId of reversedModules) {
             const module = this.modules.get(moduleId);
             if (!module)
                 continue;
+            // Removed before its hook runs, so a second stop() (for example
+            // after a shutdown timeout) never calls onShutdown on it again.
+            this.startedModules = this.startedModules.filter((id) => id !== moduleId);
             const moduleStartTime = Date.now();
             this.emitModuleEvent("runtime.module.stopping", moduleId, "stopping");
             try {
@@ -268,7 +370,12 @@ export class LifecycleManager {
         const startTime = Date.now();
         const succeeded = [];
         const failed = [];
-        const reversedModules = [...this.startedModules, ...this.initializedModules]
+        await this.cancellation.settle();
+        const reversedModules = [
+            ...this.startedModules,
+            ...this.initializedModules,
+            ...this.failedInitializations,
+        ]
             .filter((id, index, arr) => arr.indexOf(id) === index)
             .reverse();
         for (const moduleId of reversedModules) {
@@ -303,6 +410,7 @@ export class LifecycleManager {
         // rebuilds the lists from scratch.
         this.startedModules = [];
         this.initializedModules = [];
+        this.failedInitializations = [];
         this.contexts.clear();
         return Object.freeze({
             phase: "destroy",
@@ -322,6 +430,7 @@ export class LifecycleManager {
      */
     async rollback() {
         const failures = [];
+        this.cancellation.cancel();
         for (const moduleId of [...this.startedModules].reverse()) {
             const module = this.modules.get(moduleId);
             if (!module?.onShutdown)
@@ -343,9 +452,14 @@ export class LifecycleManager {
                 });
             }
         }
-        for (const moduleId of [...this.initializedModules].reverse()) {
+        for (const moduleId of [
+            ...this.initializedModules,
+            ...this.failedInitializations,
+        ].reverse()) {
             const module = this.modules.get(moduleId);
-            if (!module?.onDestroy)
+            // A module whose hook is still running is torn down by the
+            // cancellation once that hook settles, never concurrently with it.
+            if (!module?.onDestroy || this.cancellation.isRunning(moduleId))
                 continue;
             const startedAt = Date.now();
             try {
@@ -368,6 +482,7 @@ export class LifecycleManager {
         // later shutdown does not stop modules a second time.
         this.startedModules = [];
         this.initializedModules = [];
+        this.failedInitializations = [];
         this.contexts.clear();
         return failures;
     }

package/dist/lifecycle/lifecycle.type.d.ts

@@ -72,7 +72,21 @@ export type ModuleEventListener = (type: RuntimeModuleEventType, payload: Runtim
  * Options for lifecycle management.
  */
 export interface LifecycleManagerOptions {
+    /**
+     * @deprecated Has no effect. Shutdown is bounded as a whole by
+     * `RuntimeOptions.shutdownTimeout`; bounding each module's hook here
+     * would let `onDestroy` run while a timed-out `onShutdown` is still
+     * closing the same resources.
+     */
     readonly shutdownTimeout?: number;
+    /**
+     * Keeps initializing and starting after a module fails.
+     *
+     * Only modules INDEPENDENT of the failure continue: a module that
+     * declares a failed (or already skipped) module in `dependencies` is
+     * never initialized or readied, and is reported in `failed` with the
+     * blocking dependency named. Defaults to false.
+     */
     readonly continueOnFailure?: boolean;
     /**
      * Receives one event per module per lifecycle phase.

package/dist/registry/registry.core.js

@@ -4,6 +4,7 @@
  * Manages multiple runtime instances for scenarios where Zudojs
  * runs multiple applications or workers in a single process.
  */
+import { RuntimeStateError } from "../runtimeError/index.js";
 /**
  * Runtime registry for managing multiple runtime instances.
  *
@@ -19,7 +20,7 @@ export class RuntimeRegistry {
      */
     register(id, runtime) {
         if (this.runtimes.has(id)) {
-            throw new Error(`Runtime "${id}" is already registered.`);
+            throw new RuntimeStateError(`Runtime "${id}" is already registered.`);
         }
         this.runtimes.set(id, runtime);
     }
@@ -56,7 +57,7 @@ export class RuntimeRegistry {
     require(id) {
         const runtime = this.runtimes.get(id);
         if (!runtime) {
-            throw new Error(`Runtime "${id}" not found.`);
+            throw new RuntimeStateError(`Runtime "${id}" not found.`);
         }
         return runtime;
     }

package/dist/runtime/runtime.core.js

@@ -65,6 +65,9 @@ export class DefaultRuntime {
         this.signalHandler = new SignalHandler(this.logger, {
             handleSignals: this.options.handleSignals,
             handleFatalErrors: this.options.handleFatalErrors,
+            forceExitOnSecondSignal: this.options.forceExitOnSecondSignal,
+            exitOnFatalError: this.options.exitOnFatalError,
+            fatalExitTimeout: this.options.fatalExitTimeout,
         });
         this.readinessTracker = new ReadinessTracker({
             autoMarkReady: this.options.trackReadiness,
@@ -298,6 +301,9 @@ export class DefaultRuntime {
                 });
             }
             this.transitionTo("failed");
+            // A rolled-back runtime owns nothing, so it must not keep owning the
+            // process's signals and fatal-error handlers either.
+            this.signalHandler.unregister();
             throw runtimeError;
         }
     }

package/dist/runtimeOptions/runtimeOptions.core.js

@@ -1,5 +1,6 @@
 import { DEFAULT_RUNTIME_OPTIONS } from "./runtimeOptions.type.js";
 import { createRuntimeId } from "../runtimeContext/runtimeContext.factory.js";
+import { RuntimeError } from "@zudojs/errors";
 /**
  * Resolves runtime options with defaults applied.
  *
@@ -24,19 +25,40 @@ export function resolveRuntimeOptions(options) {
  */
 export function validateRuntimeOptions(options) {
     if (!options.environment) {
-        throw new Error("Runtime environment is required.");
+        throw new RuntimeError("Runtime environment is required.", {
+            metadata: { option: "environment" },
+        });
     }
     if (!options.applicationName) {
-        throw new Error("Application name is required.");
+        throw new RuntimeError("Application name is required.", {
+            metadata: { option: "applicationName" },
+        });
     }
     if (options.shutdownTimeout <= 0) {
-        throw new Error("Shutdown timeout must be positive.");
+        throw new RuntimeError("Shutdown timeout must be positive.", {
+            metadata: { option: "shutdownTimeout", value: options.shutdownTimeout },
+        });
     }
     if (options.startupTimeout <= 0) {
-        throw new Error("Startup timeout must be positive.");
+        throw new RuntimeError("Startup timeout must be positive.", {
+            metadata: { option: "startupTimeout", value: options.startupTimeout },
+        });
+    }
+    if (!Number.isFinite(options.fatalExitTimeout) || options.fatalExitTimeout < 0) {
+        throw new RuntimeError(`Fatal exit timeout must be a finite, non-negative number, got ${options.fatalExitTimeout}.`, {
+            metadata: {
+                option: "fatalExitTimeout",
+                value: options.fatalExitTimeout,
+            },
+        });
     }
     if (options.readinessCheckTimeout < 0) {
-        throw new Error(`Readiness check timeout must be zero or positive, got ${options.readinessCheckTimeout}. Use 0 to run checks without a bound.`);
+        throw new RuntimeError(`Readiness check timeout must be zero or positive, got ${options.readinessCheckTimeout}. Use 0 to run checks without a bound.`, {
+            metadata: {
+                option: "readinessCheckTimeout",
+                value: options.readinessCheckTimeout,
+            },
+        });
     }
 }
 /**

package/dist/runtimeOptions/runtimeOptions.type.d.ts

@@ -31,6 +31,25 @@ export interface RuntimeOptions {
      * @default true
      */
     readonly handleFatalErrors?: boolean;
+    /**
+     * Whether a second SIGTERM/SIGINT during shutdown exits immediately
+     * with code 1.
+     * @default true
+     */
+    readonly forceExitOnSecondSignal?: boolean;
+    /**
+     * Whether an uncaught exception or unhandled rejection exits the
+     * process with code 1 once shutdown finishes. Set to `false` to stop
+     * the runtime but leave the process running.
+     * @default true
+     */
+    readonly exitOnFatalError?: boolean;
+    /**
+     * How long a fatal-error shutdown may take before the process exits
+     * anyway, in milliseconds.
+     * @default 10000
+     */
+    readonly fatalExitTimeout?: number;
     /**
      * Graceful shutdown timeout in milliseconds.
      * @default 30000
@@ -94,6 +113,9 @@ export interface ResolvedRuntimeOptions {
     readonly applicationVersion: string;
     readonly handleSignals: boolean;
     readonly handleFatalErrors: boolean;
+    readonly forceExitOnSecondSignal: boolean;
+    readonly exitOnFatalError: boolean;
+    readonly fatalExitTimeout: number;
     readonly shutdownTimeout: number;
     readonly startupTimeout: number;
     readonly emitEvents: boolean;
@@ -109,6 +131,9 @@ export interface ResolvedRuntimeOptions {
 export declare const DEFAULT_RUNTIME_OPTIONS: Readonly<{
     readonly handleSignals: true;
     readonly handleFatalErrors: true;
+    readonly forceExitOnSecondSignal: true;
+    readonly exitOnFatalError: true;
+    readonly fatalExitTimeout: 10000;
     readonly shutdownTimeout: 30000;
     readonly startupTimeout: 60000;
     readonly emitEvents: true;

package/dist/runtimeOptions/runtimeOptions.type.js

@@ -4,6 +4,9 @@
 export const DEFAULT_RUNTIME_OPTIONS = Object.freeze({
     handleSignals: true,
     handleFatalErrors: true,
+    forceExitOnSecondSignal: true,
+    exitOnFatalError: true,
+    fatalExitTimeout: 10_000,
     shutdownTimeout: 30_000,
     startupTimeout: 60_000,
     emitEvents: true,

package/dist/shutdown/shutdown.core.js

@@ -4,6 +4,27 @@ import { LifecycleManager } from "../lifecycle/index.js";
 import { RuntimeStopError, RuntimeTimeoutError, } from "../runtimeError/index.js";
 /** Largest delay a timer can represent. */
 const MAX_TIMER_DELAY = 2_147_483_647;
+/**
+ * Teardown still running for a lifecycle, including one abandoned by a
+ * shutdown timeout. A later stop() joins it instead of calling every
+ * module's `onShutdown` a second time while the first is still closing.
+ */
+const inProgress = new WeakMap();
+/**
+ * Starts the teardown for `lifecycle`, or joins the one already running.
+ */
+function shutdownOnce(lifecycle, logger) {
+    const existing = inProgress.get(lifecycle);
+    if (existing !== undefined) {
+        logger.warn("A previous shutdown is still running; waiting for it.");
+        return existing;
+    }
+    const teardown = performShutdown(lifecycle, logger).finally(() => {
+        inProgress.delete(lifecycle);
+    });
+    inProgress.set(lifecycle, teardown);
+    return teardown;
+}
 /**
  * Executes the shutdown sequence with timeout.
  *
@@ -24,7 +45,7 @@ export async function executeShutdown(lifecycle, runtimeId, eventBus, logger, sh
         }));
     }
     logger.info("Initiating graceful shutdown.", { timeoutMs: shutdownTimeout });
-    const stopPromise = performShutdown(lifecycle, logger);
+    const stopPromise = shutdownOnce(lifecycle, logger);
     // The shutdown promise keeps running if the timeout wins; attach a
     // handler now so its eventual rejection is never unhandled.
     stopPromise.catch(() => { });

package/dist/startup/startup.core.js

@@ -11,7 +11,7 @@ const MAX_TIMER_DELAY = 2_147_483_647;
  * a module whose `onInitialize` never settles hung the boot forever with
  * no diagnostic. The timer is cleared whichever side wins.
  */
-async function withStartupTimeout(operation, timeoutMs) {
+async function withStartupTimeout(operation, timeoutMs, onTimeout) {
     if (timeoutMs <= 0) {
         return operation;
     }
@@ -20,7 +20,13 @@ async function withStartupTimeout(operation, timeoutMs) {
     operation.catch(() => { });
     let timer;
     const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new RuntimeTimeoutError("startup", timeoutMs)), Math.min(timeoutMs, MAX_TIMER_DELAY));
+        timer = setTimeout(() => {
+            // Abandon the startup before reporting the timeout, so no further
+            // module hook starts and a hook still running tears its module
+            // down when it settles instead of leaving it live.
+            onTimeout();
+            reject(new RuntimeTimeoutError("startup", timeoutMs));
+        }, Math.min(timeoutMs, MAX_TIMER_DELAY));
         timer.unref?.();
     });
     try {
@@ -36,7 +42,7 @@ async function withStartupTimeout(operation, timeoutMs) {
  * Executes the startup sequence.
  */
 export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emitEvents, startupTimeout = 0) {
-    return withStartupTimeout(runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents), startupTimeout);
+    return withStartupTimeout(runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents), startupTimeout, () => lifecycle.cancel());
 }
 /**
  * Runs the startup sequence.
@@ -45,6 +51,9 @@ async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
     // Per-module `runtime.module.*` events are emitted by the lifecycle
     // manager, which is the only layer that knows which module is running.
     const initResult = await lifecycle.initialize();
+    if (lifecycle.cancelled) {
+        return;
+    }
     if (initResult.failed.length > 0) {
         const failure = initResult.failed[0];
         if (emitEvents && eventBus) {
@@ -64,6 +73,9 @@ async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
         durationMs: initResult.durationMs,
     });
     const startResult = await lifecycle.start();
+    if (lifecycle.cancelled) {
+        return;
+    }
     if (startResult.failed.length > 0) {
         const failure = startResult.failed[0];
         if (emitEvents && eventBus) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/runtime",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Application lifecycle orchestrator with dependency ordering, rollback, signals, and readiness checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,13 +27,12 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/container": "1.1.0",
-    "@zudojs/config": "1.0.1",
-    "@zudojs/logger": "1.1.0",
-    "@zudojs/events": "1.0.1",
-    "@zudojs/core": "1.1.0"
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/container": "1.1.2",
+    "@zudojs/core": "1.2.1",
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/events": "1.2.0",
+    "@zudojs/logger": "1.3.0"
   },
   "license": "MIT",
   "author": {