@zudojs/core 1.1.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Application lifecycle management, execution context propagation, and runtime orchestration for Zudojs applications.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-core](https://zudojs.oyinlola.site/docs/packages-core) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-core.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -43,6 +49,8 @@ await app.start(); // restart: a fresh runtime is created
 await app.shutdown(); // stop + dispose; cannot be restarted afterwards
 ```
 
+When `runtime.mode` is omitted, it is derived from `NODE_ENV` with `resolveEnvironment()` from `@zudojs/constants` (`prod` / `Production` → `"production"`, `staging` → `"production"`, `test` → `"test"`, unset → `"development"`).
+
 `createApplication` wires the standard graph (container, configuration manager, logger, module registry/loader/lifecycle, runtime, application lifecycle). Every piece can also be assembled by hand:
 
 ```typescript
@@ -66,6 +74,8 @@ const app = await Application.create({
 });
 ```
 
+A failed `lifecycle.start()` stops, in reverse order, every participant whose `start()` completed, so a retry starts from the first one again. `dispose()` only reaches participants whose `initialize()` ran.
+
 ## Runtime
 
 `createRuntime(dependencies, options)` returns a single-use runtime:
@@ -77,14 +87,14 @@ FAILED is reachable from every non-terminal state via fail() or a failure.
 
 - `start()` loads, initializes, and starts modules through the bootstrap pipeline; `getStatus().bootstrap` reports counts, errors, and duration.
 - `stop()` stops and destroys modules through the shutdown pipeline; `getStatus().shutdown` reports the same.
-- `startup.timeoutMs` / `shutdown.timeoutMs` abort the pipeline with a `RuntimeTimeoutError`; the abandoned pipeline can never surface an unhandled rejection.
+- `startup.timeoutMs` / `shutdown.timeoutMs` abort the pipeline with a `RuntimeTimeoutError`; the abandoned pipeline can never surface an unhandled rejection. A timed-out bootstrap starts no further phase or module hook; the hook still running finishes, and the runtime then stops and destroys whatever it brought up. `stop()` waits for that teardown.
 - `continueOnInitializeError` / `continueOnStartError` (and the stop/destroy equivalents) make the runtime finish with `success: false` and the failures listed instead of throwing.
 - Every error the runtime throws extends `RuntimeError` (which itself extends `RuntimeError` from `@zudojs/errors`), so `isRuntimeError()` from either package recognises it.
 - `runtime.context` is the runtime's immutable `RuntimeExecutionContext` (`executionId` = runtime id, `service` = runtime name, `metadata.runtimeId/runtimeName/runtimeMode/runtimeRole` plus `RuntimeOptions.metadata`); `runtime.timing` holds the state-transition timestamps; `runtime.contextStorage` is the `ContextStorage` the context is established in (`RuntimeDependencies.contextStorage`, default `getDefaultContextStorage()`).
 
 ### Signals
 
-When `signals.handleSigint` / `handleSigterm` / `handleSighup` are on (SIGINT and SIGTERM default to on), the runtime registers handlers on start and removes them on stop, failure, or dispose. The first signal triggers a graceful `stop()`. A second signal during shutdown is logged and ignored unless `signals.forceExitOnSecondSignal` is explicitly enabled, in which case the process exits with `signals.forceExitCode`. `handleUncaughtException` / `handleUnhandledRejection` mark the runtime failed and stop it. The runtime never calls `process.exit()` otherwise.
+When `signals.handleSigint` / `handleSigterm` / `handleSighup` are on (SIGINT and SIGTERM default to on), the runtime registers handlers on start and removes them on stop, failure, or dispose. The first signal triggers a graceful `stop()`. A second signal during shutdown exits the process with `signals.forceExitCode` (default 1); set `signals.forceExitOnSecondSignal: false` to log and ignore it instead. `handleUncaughtException` / `handleUnhandledRejection` mark the runtime failed, stop it, and then exit the process with code 1, because the installed handler suppresses Node's own crash and the process would otherwise end with code 0. `signals.fatalExitTimeout` (default 10000 ms) bounds a shutdown that hangs; set `signals.exitOnFatalError: false` to stop the runtime and keep the process running. The runtime never calls `process.exit()` otherwise.
 
 ## Modules
 
@@ -120,14 +130,14 @@ onInitialize → onReady → onShutdown → onDestroy
 
 ## Execution context
 
-There is one execution-context model: the immutable `ExecutionContext` (`createExecutionContext`, `deriveExecutionContext`, `withExecutionMetadata`) propagated by `ContextStorage`, which wraps `AsyncLocalStorage`. `run(context, fn)` and `runDerived(overrides, fn)` establish a context for the callback and everything it awaits, `runWithValues(context, values, fn)` additionally binds a `ContextValues` collection (read back with `getValues()`), and `capture()` / `runSnapshot(snapshot, fn)` carry a context across queue or timer boundaries. `getDefaultContextStorage()` is the process-wide instance every component uses unless another is injected.
+There is one execution-context model: the immutable `ExecutionContext` (`createExecutionContext`, `deriveExecutionContext`, `withExecutionMetadata`) propagated by `ContextStorage`, which wraps `AsyncLocalStorage`. `run(context, fn)` and `runDerived(overrides, fn)` establish a context for the callback and everything it awaits, `runWithValues(context, values, fn)` additionally binds a `ContextValues` collection (read back with `getValues()`; `run()` starts a new execution without the enclosing execution's values, `runDerived()` keeps them), and `capture()` / `runSnapshot(snapshot, fn)` carry a context across queue or timer boundaries. `getDefaultContextStorage()` is the process-wide instance every component uses unless another is injected.
 
 Propagation is real at runtime:
 
 - `runtime.start()` and `runtime.stop()` run the bootstrap and shutdown pipelines inside `runtime.contextStorage.run(runtime.context, ...)`.
 - Each module hook (`onInitialize`, `onReady`, `onShutdown`, `onDestroy`) runs in a context derived from it: `module` is the module id, `operation` is the hook name, and `{ moduleId, phase }` is merged into `metadata`. `ModuleLifecycleOptions.contextStorage` selects the storage (default: the shared one).
 - `Application.start()` / `stop()` / `shutdown()` run lifecycle participants inside the runtime's context as well.
-- `createApplication` threads one storage (`CreateApplicationOptions.contextStorage`) through the `ApplicationContext` (`getContextStorage()`), the container's `currentScope` (so `"scoped"` providers resolve once per execution context), the module lifecycle, the runtime, and the logger.
+- `createApplication` threads one storage (`CreateApplicationOptions.contextStorage`) through the `ApplicationContext` (`getContextStorage()`), the container's `currentScope` (so `"scoped"` providers resolve once per execution context; resolving one outside any execution context, or from a singleton's factory, throws a `DependencyResolutionError`), the module lifecycle, the runtime, and the logger.
 
 ```typescript
 import { defineModule, getDefaultContextStorage } from "@zudojs/core";

package/dist/configuration/configurationManager.manager.js

@@ -219,7 +219,7 @@ export class ConfigurationManager {
         }
         if (!this.missingSetConfigurationWarned) {
             this.missingSetConfigurationWarned = true;
-            console.warn("ConfigurationManager: the configured ConfigurationProvider does not implement setConfiguration(); loaded configuration will not be pushed into the provider.");
+            process.emitWarning("ConfigurationManager: the configured ConfigurationProvider does not implement setConfiguration(); loaded configuration will not be pushed into the provider.", { type: "ZudojsCoreWarning", code: "ZUDOJS_CONFIG_PROVIDER_NO_SET" });
         }
     }
     emit(event) {

package/dist/container/container.d.ts

@@ -12,8 +12,8 @@ export interface ContainerOptions {
      *   new Container({ currentScope: () => storage.get() })
      *
      * "scoped" providers resolve to one instance per returned object.
-     * When it returns undefined and no explicit scope is active, scoped
-     * providers behave as transient.
+     * When it returns undefined and no explicit scope is active, resolving
+     * a scoped provider throws a DependencyResolutionError.
      */
     readonly currentScope?: () => object | undefined;
 }
@@ -29,6 +29,8 @@ export declare class Container {
     private readonly currentScope;
     private readonly resolving;
     private activeScope;
+    /** The singleton under construction, if any; see assertScopedResolvable. */
+    private captor;
     constructor(options?: ContainerOptions);
     /**
      * Registers a provider in the container.

package/dist/container/container.js

@@ -1,4 +1,5 @@
 import { ProviderNotFoundError, ProviderAlreadyRegisteredError, InvalidProviderError, DependencyResolutionError, } from "../errors/exceptions.js";
+import { assertScopedResolvable } from "./container.lifetime.js";
 /**
  * Dependency Injection container for Zudojs applications.
  *
@@ -11,6 +12,8 @@ export class Container {
     currentScope;
     resolving = [];
     activeScope;
+    /** The singleton under construction, if any; see assertScopedResolvable. */
+    captor;
     constructor(options = {}) {
         this.currentScope = options.currentScope;
     }
@@ -80,6 +83,9 @@ export class Container {
         if (registration.scope === "singleton" && registration.resolved) {
             return registration.instance;
         }
+        if (registration.scope === "scoped") {
+            assertScopedResolvable(token, this.captor, scopeKey, this.resolving);
+        }
         if (registration.scope === "scoped" && scopeKey) {
             if (registration.scopedInstances.has(scopeKey)) {
                 return registration.scopedInstances.get(scopeKey);
@@ -109,8 +115,12 @@ export class Container {
             return provider.useValue;
         }
         const previousScope = this.activeScope;
+        const previousCaptor = this.captor;
         this.resolving.push(token);
         this.activeScope = scopeKey;
+        if (registration.scope === "singleton") {
+            this.captor = token;
+        }
         try {
             if ("useFactory" in provider) {
                 return provider.useFactory(this);
@@ -125,6 +135,7 @@ export class Container {
         finally {
             this.resolving.pop();
             this.activeScope = previousScope;
+            this.captor = previousCaptor;
         }
     }
 }

package/dist/container/container.lifetime.d.ts

@@ -0,0 +1,21 @@
+import type { Token } from "./token.js";
+/**
+ * Rejects a "scoped" resolution that would outlive or escape its scope.
+ *
+ * - A scoped provider resolved (directly or transitively) while a
+ *   singleton is being constructed would be captured by that singleton
+ *   and served to every later scope: one request's user, tenant or
+ *   transaction leaking into all the others. This is the captive
+ *   dependency error mature DI containers raise.
+ * - A scoped provider resolved with no active scope has nothing to be
+ *   scoped to. It used to behave as transient, which hid the missing
+ *   scope; it now fails like `@zudojs/container`'s ScopedResolutionError.
+ *
+ * @param token - The scoped token being resolved.
+ * @param captor - The singleton currently under construction, if any.
+ * @param scopeKey - The active scope key, if any.
+ * @param chain - The current resolution chain, for the diagnostic.
+ * @throws DependencyResolutionError when either rule is broken.
+ */
+export declare function assertScopedResolvable(token: Token<unknown>, captor: Token<unknown> | undefined, scopeKey: object | undefined, chain: readonly Token<unknown>[]): void;
+//# sourceMappingURL=container.lifetime.d.ts.map

package/dist/container/container.lifetime.js

@@ -0,0 +1,39 @@
+import { DependencyResolutionError } from "../errors/exceptions.js";
+/**
+ * Rejects a "scoped" resolution that would outlive or escape its scope.
+ *
+ * - A scoped provider resolved (directly or transitively) while a
+ *   singleton is being constructed would be captured by that singleton
+ *   and served to every later scope: one request's user, tenant or
+ *   transaction leaking into all the others. This is the captive
+ *   dependency error mature DI containers raise.
+ * - A scoped provider resolved with no active scope has nothing to be
+ *   scoped to. It used to behave as transient, which hid the missing
+ *   scope; it now fails like `@zudojs/container`'s ScopedResolutionError.
+ *
+ * @param token - The scoped token being resolved.
+ * @param captor - The singleton currently under construction, if any.
+ * @param scopeKey - The active scope key, if any.
+ * @param chain - The current resolution chain, for the diagnostic.
+ * @throws DependencyResolutionError when either rule is broken.
+ */
+export function assertScopedResolvable(token, captor, scopeKey, chain) {
+    if (captor !== undefined) {
+        throw new DependencyResolutionError(`Captive dependency: singleton "${describe(captor)}" cannot depend on ` +
+            `scoped "${describe(token)}". Register the consumer as "scoped" or ` +
+            `"transient", or resolve the scoped dependency lazily per call.`, [...chain, token]);
+    }
+    if (scopeKey === undefined) {
+        throw new DependencyResolutionError(`Scoped provider "${describe(token)}" was resolved outside any scope. ` +
+            `Resolve it through container.createScope() or inside an execution ` +
+            `context.`, [...chain, token]);
+    }
+}
+function describe(token) {
+    if (typeof token === "function")
+        return token.name || "anonymous class";
+    if (typeof token === "symbol")
+        return token.description ?? token.toString();
+    return String(token);
+}
+//# sourceMappingURL=container.lifetime.js.map

package/dist/container/scope.d.ts

@@ -15,7 +15,9 @@ export type Scope =
  * example the current ExecutionContext of an HTTP request,
  * background job, message consumption, or RPC call).
  *
- * When no scope is active, scoped providers behave as transient.
+ * Resolving a scoped provider with no active scope, or from inside a
+ * singleton's construction (a captive dependency), throws a
+ * DependencyResolutionError.
  */
  | "scoped"
 /**

package/dist/context/provider/contextStorage.storage.d.ts

@@ -30,6 +30,14 @@ export declare class ContextStorage {
      *
      * The context is automatically available to all asynchronous
      * operations created within the callback.
+     *
+     * A new execution starts without ContextValues: values bound by an
+     * enclosing `runWithValues` belong to that execution (its tenant,
+     * user, transaction) and must not leak into an unrelated one started
+     * from inside its async scope, such as a listener or consumer created
+     * during a request. Re-entering the execution that is already current
+     * keeps its values. Use `runDerived` or `runWithValues` to carry
+     * values on purpose.
      */
     run<T>(context: ExecutionContext, callback: () => T): T;
     /**

package/dist/context/provider/contextStorage.storage.js

@@ -24,9 +24,20 @@ export class ContextStorage {
      *
      * The context is automatically available to all asynchronous
      * operations created within the callback.
+     *
+     * A new execution starts without ContextValues: values bound by an
+     * enclosing `runWithValues` belong to that execution (its tenant,
+     * user, transaction) and must not leak into an unrelated one started
+     * from inside its async scope, such as a listener or consumer created
+     * during a request. Re-entering the execution that is already current
+     * keeps its values. Use `runDerived` or `runWithValues` to carry
+     * values on purpose.
      */
     run(context, callback) {
-        return this.storage.run(context, callback);
+        if (context === this.storage.getStore()) {
+            return this.storage.run(context, callback);
+        }
+        return this.storage.run(context, () => this.valuesStorage.exit(callback));
     }
     /**
      * Returns the current execution context.

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

@@ -39,9 +39,12 @@ export interface LifecycleOptions {
  *
  *   CREATED → INITIALIZING → INITIALIZED → STARTING → RUNNING
  *   RUNNING → STOPPING → STOPPED → (STARTING → RUNNING) restart
- *   any phase failure → FAILED; initialize()/start() retry from FAILED
- *   resume with the participant that failed; stop() from FAILED unwinds
- *   whatever started.
+ *   any phase failure → FAILED; initialize() retries from FAILED resume
+ *   with the participant that failed. A failed start() is rolled back:
+ *   every participant whose start() completed is stopped in reverse
+ *   order, so a retry starts again from the first one. dispose() only
+ *   reaches participants whose initialize() ran (including one that
+ *   threw, which may have acquired resources before failing).
  *
  * Concurrent callers of the same phase share the in-flight promise.
  */
@@ -52,6 +55,8 @@ export declare class Lifecycle {
     private readonly continueOnShutdownError;
     private initializedCount;
     private startedCount;
+    /** Participants whose initialize() was invoked, whether or not it threw. */
+    private initializeAttempted;
     private disposed;
     private failedPhase;
     private initializePromise;

package/dist/lifecycle/core/lifecycle.js

@@ -1,4 +1,5 @@
 import { InvalidStateError } from "../../errors/exceptions.js";
+import { rollbackStartedParticipants } from "./lifecycle.rollback.js";
 /** Lifecycle states supported by the Zudojs application runtime. */
 export const LifecycleState = {
     CREATED: "created",
@@ -18,9 +19,12 @@ export const LifecycleState = {
  *
  *   CREATED → INITIALIZING → INITIALIZED → STARTING → RUNNING
  *   RUNNING → STOPPING → STOPPED → (STARTING → RUNNING) restart
- *   any phase failure → FAILED; initialize()/start() retry from FAILED
- *   resume with the participant that failed; stop() from FAILED unwinds
- *   whatever started.
+ *   any phase failure → FAILED; initialize() retries from FAILED resume
+ *   with the participant that failed. A failed start() is rolled back:
+ *   every participant whose start() completed is stopped in reverse
+ *   order, so a retry starts again from the first one. dispose() only
+ *   reaches participants whose initialize() ran (including one that
+ *   threw, which may have acquired resources before failing).
  *
  * Concurrent callers of the same phase share the in-flight promise.
  */
@@ -31,6 +35,8 @@ export class Lifecycle {
     continueOnShutdownError;
     initializedCount = 0;
     startedCount = 0;
+    /** Participants whose initialize() was invoked, whether or not it threw. */
+    initializeAttempted = 0;
     disposed = false;
     failedPhase;
     initializePromise;
@@ -194,7 +200,8 @@ export class Lifecycle {
         }
         this.disposed = true;
         const errors = [];
-        for (let i = this.participants.length - 1; i >= 0; i--) {
+        // A participant whose initialize() never ran has nothing to release.
+        for (let i = this.initializeAttempted - 1; i >= 0; i--) {
             const participant = this.participants[i];
             try {
                 this.logger?.debug("Disposing lifecycle participant", {
@@ -213,6 +220,7 @@ export class Lifecycle {
         }
         this.initializedCount = 0;
         this.startedCount = 0;
+        this.initializeAttempted = 0;
         if (errors.length > 0 && !this.continueOnShutdownError) {
             this.state = LifecycleState.FAILED;
             this.failedPhase = "dispose";
@@ -255,6 +263,7 @@ export class Lifecycle {
                 this.logger?.debug("Initializing lifecycle participant", {
                     participant: participant.name,
                 });
+                this.initializeAttempted = Math.max(this.initializeAttempted, i + 1);
                 await participant.initialize?.();
                 this.initializedCount = i + 1;
             }
@@ -285,9 +294,13 @@ export class Lifecycle {
             this.logger?.info("Application startup completed");
         }
         catch (error) {
+            this.logger?.error("Application startup failed", error);
+            // Roll back rather than leave earlier participants running until
+            // someone remembers to call shutdown().
+            await rollbackStartedParticipants(this.participants, this.startedCount, this.logger);
+            this.startedCount = 0;
             this.state = LifecycleState.FAILED;
             this.failedPhase = "start";
-            this.logger?.error("Application startup failed", error);
             throw error;
         }
     }

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

@@ -0,0 +1,18 @@
+import type { Logger } from "../../logging/core/logger.js";
+import type { LifecycleParticipant } from "./lifecycle.js";
+/**
+ * Stops, in reverse order, the first `count` participants after a
+ * failed start.
+ *
+ * Only participants whose `start()` completed are stopped; the one
+ * that threw is left to its own error handling, as `stop()` has always
+ * done. Stop failures are logged and returned; they never mask the
+ * start error.
+ *
+ * @param participants - Registered participants, in start order.
+ * @param count - How many leading participants started successfully.
+ * @param logger - Optional logger for rollback diagnostics.
+ * @returns The errors raised by `stop()` hooks during the rollback.
+ */
+export declare function rollbackStartedParticipants(participants: readonly LifecycleParticipant[], count: number, logger: Logger | undefined): Promise<readonly unknown[]>;
+//# sourceMappingURL=lifecycle.rollback.d.ts.map

package/dist/lifecycle/core/lifecycle.rollback.js

@@ -0,0 +1,34 @@
+/**
+ * Stops, in reverse order, the first `count` participants after a
+ * failed start.
+ *
+ * Only participants whose `start()` completed are stopped; the one
+ * that threw is left to its own error handling, as `stop()` has always
+ * done. Stop failures are logged and returned; they never mask the
+ * start error.
+ *
+ * @param participants - Registered participants, in start order.
+ * @param count - How many leading participants started successfully.
+ * @param logger - Optional logger for rollback diagnostics.
+ * @returns The errors raised by `stop()` hooks during the rollback.
+ */
+export async function rollbackStartedParticipants(participants, count, logger) {
+    const errors = [];
+    for (let i = count - 1; i >= 0; i--) {
+        const participant = participants[i];
+        try {
+            logger?.debug("Rolling back lifecycle participant", {
+                participant: participant.name,
+            });
+            await participant.stop?.();
+        }
+        catch (error) {
+            errors.push(error);
+            logger?.error("Failed to roll back lifecycle participant", error, {
+                participant: participant.name,
+            });
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=lifecycle.rollback.js.map

package/dist/modules/moduleLifecycle/moduleLifecycle.lifecycle.js

@@ -29,7 +29,7 @@ export class ModuleLifecycleManager {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
             try {
-                return await executeLifecyclePhase(this.getStartupOrder(), "initialize", "initializing", "initialized", options.continueOnError ?? this.options.continueOnInitializeError, this.registry, this.loader, this.states, this.contextStorage);
+                return await executeLifecyclePhase(this.getStartupOrder(), "initialize", "initializing", "initialized", options.continueOnError ?? this.options.continueOnInitializeError, this.registry, this.loader, this.states, this.contextStorage, options.signal);
             }
             catch (error) {
                 await this.rollbackAfterFailure(error, { stopFirst: false });
@@ -41,7 +41,7 @@ export class ModuleLifecycleManager {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
             try {
-                return await executeLifecyclePhase(this.getStartupOrder(), "start", "starting", "started", options.continueOnError ?? this.options.continueOnStartError, this.registry, this.loader, this.states, this.contextStorage);
+                return await executeLifecyclePhase(this.getStartupOrder(), "start", "starting", "started", options.continueOnError ?? this.options.continueOnStartError, this.registry, this.loader, this.states, this.contextStorage, options.signal);
             }
             catch (error) {
                 await this.rollbackAfterFailure(error, { stopFirst: true });

package/dist/modules/moduleLifecycle/moduleLifecycle.stateMachine.d.ts

@@ -38,7 +38,7 @@ export declare function isModuleDestroyed(moduleId: ModuleId, states: LifecycleS
 export declare function invokeLifecycleHook(module: Module, step: ModuleLifecycleStep, context: ModuleContext, contextStorage?: ContextStorage, phase?: ModuleLifecyclePhase): Promise<void>;
 export declare function canModuleEnterPhase(moduleId: ModuleId, hook: ModuleLifecycleStep, states: LifecycleStateMap): boolean;
 export declare function setLifecycleState(moduleId: ModuleId, phase: ModuleLifecyclePhase, states: LifecycleStateMap, error?: unknown): void;
-export declare function executeLifecyclePhase(order: readonly ModuleId[], hook: ModuleLifecycleStep, activePhase: ModuleLifecyclePhase, completedPhase: ModuleLifecyclePhase, continueOnError: boolean, registry: ModuleRegistry, loader: ModuleLoader, states: LifecycleStateMap, contextStorage?: ContextStorage): Promise<{
+export declare function executeLifecyclePhase(order: readonly ModuleId[], hook: ModuleLifecycleStep, activePhase: ModuleLifecyclePhase, completedPhase: ModuleLifecyclePhase, continueOnError: boolean, registry: ModuleRegistry, loader: ModuleLoader, states: LifecycleStateMap, contextStorage?: ContextStorage, signal?: AbortSignal): Promise<{
     readonly completed: readonly ModuleId[];
     readonly failed: readonly ModuleId[];
     readonly skipped: readonly ModuleLifecycleSkip[];

package/dist/modules/moduleLifecycle/moduleLifecycle.stateMachine.js

@@ -146,13 +146,15 @@ const REQUIRED_DEPENDENCY_PHASES = {
     initialize: ["initialized", "starting", "started"],
     start: ["started"],
 };
-export async function executeLifecyclePhase(order, hook, activePhase, completedPhase, continueOnError, registry, loader, states, contextStorage) {
+export async function executeLifecyclePhase(order, hook, activePhase, completedPhase, continueOnError, registry, loader, states, contextStorage, signal) {
     const completed = [];
     const failed = [];
     const skipped = [];
     const blocked = new Set();
     const requiredDependencyPhases = REQUIRED_DEPENDENCY_PHASES[hook];
     for (const moduleId of order) {
+        if (signal?.aborted)
+            break;
         const registration = registry.get(moduleId);
         if (!registration?.instance)
             continue;

package/dist/modules/moduleLifecycle/moduleLifecycle.type.d.ts

@@ -98,6 +98,13 @@ export interface ModuleLifecyclePhaseOptions {
      * runtime that drives it.
      */
     readonly continueOnError?: boolean;
+    /**
+     * Abandons the phase once aborted: no further module hook is started.
+     * A hook already running completes and its module keeps the phase it
+     * reached, so a later stop()/destroy() tears it down. The runtime
+     * passes its startup-timeout signal here.
+     */
+    readonly signal?: AbortSignal;
 }
 import { ModuleOperationError } from "../moduleError/moduleError.lifecycle.js";
 /**

package/dist/runtime/runtime.d.ts

@@ -135,6 +135,7 @@ export declare class DefaultRuntime implements Runtime {
     private _startPromise;
     private _stopPromise;
     private _unwound;
+    private _unwindPromise;
     constructor(dependencies: RuntimeDependencies, options?: RuntimeOptions);
     get state(): RuntimeState;
     get context(): RuntimeExecutionContext;
@@ -158,6 +159,7 @@ export declare class DefaultRuntime implements Runtime {
      * logged and swallowed; the runtime stays FAILED.
      */
     private unwind;
+    private performUnwind;
     /**
      * Runs an operation inside the runtime's execution context so that
      * module hooks, container factories, and loggers reached from it

package/dist/runtime/runtime.js

@@ -37,6 +37,7 @@ export class DefaultRuntime {
     _startPromise;
     _stopPromise;
     _unwound = false;
+    _unwindPromise;
     constructor(dependencies, options = {}) {
         this._options = resolveRuntimeOptions(options);
         this._application = dependencies.application;
@@ -203,9 +204,15 @@ export class DefaultRuntime {
             this.fail(error);
             this._logger.error("Runtime failed to start.", error, this.logContext());
             // The module subsystem has already rolled back when the module
-            // lifecycle manager threw; a timed-out bootstrap is still
-            // running and must not be unwound concurrently.
-            if (!(error instanceof RuntimeTimeoutError)) {
+            // lifecycle manager threw. A timed-out bootstrap is still
+            // running: its teardown is queued behind the lifecycle manager's
+            // lock, so it runs once the in-flight hook settles and reaches
+            // every module that came up late. start() rejects now; stop()
+            // waits for that teardown.
+            if (error instanceof RuntimeTimeoutError) {
+                void this.unwind();
+            }
+            else {
                 await this.unwind();
             }
             throw error;
@@ -236,7 +243,11 @@ export class DefaultRuntime {
      * Best-effort module unwinding used after a failure. Errors are
      * logged and swallowed; the runtime stays FAILED.
      */
-    async unwind() {
+    unwind() {
+        this._unwindPromise ??= this.performUnwind();
+        return this._unwindPromise;
+    }
+    async performUnwind() {
         if (this._unwound)
             return;
         try {

package/dist/runtime/runtimeBootstrap/pipeline/runtimeBootstrap.pipeline.d.ts

@@ -38,7 +38,9 @@ export declare function createBootstrapPipelineState(): BootstrapPipelineState;
  *   throws; the thrown error is NOT pushed to `errors` here — the
  *   caller records it exactly once.
  * - Once `signal` is aborted (timeout) the pipeline stops publishing
- *   phase changes so an abandoned run cannot mutate the owner.
+ *   phase changes so an abandoned run cannot mutate the owner, starts
+ *   no further phase, and the lifecycle manager starts no further
+ *   module hook.
  */
 export declare function executeBootstrapPipeline(options: ResolvedBootstrapOptions, services: BootstrapPipelineServices, state: BootstrapPipelineState, signal: AbortSignal, setPhase: (phase: RuntimeBootstrapPhase) => void, log: BootstrapLogFn): Promise<void>;
 export declare function createBootstrapResult(success: boolean, phase: RuntimeBootstrapPhase, counters: BootstrapCounters, errors: readonly RuntimeBootstrapErrorInfo[], startedAt: Date, completedAt: Date): RuntimeBootstrapResult;

package/dist/runtime/runtimeBootstrap/pipeline/runtimeBootstrap.pipeline.js

@@ -15,7 +15,9 @@ export function createBootstrapPipelineState() {
  *   throws; the thrown error is NOT pushed to `errors` here — the
  *   caller records it exactly once.
  * - Once `signal` is aborted (timeout) the pipeline stops publishing
- *   phase changes so an abandoned run cannot mutate the owner.
+ *   phase changes so an abandoned run cannot mutate the owner, starts
+ *   no further phase, and the lifecycle manager starts no further
+ *   module hook.
  */
 export async function executeBootstrapPipeline(options, services, state, signal, setPhase, log) {
     const publish = (phase) => {
@@ -29,13 +31,22 @@ export async function executeBootstrapPipeline(options, services, state, signal,
     if (options.loadModules) {
         await loadModules(services.moduleLoader, identity, state, publish, log);
     }
-    if (options.initializeModules) {
-        await runLifecyclePhase("initializing", "initialized", () => services.moduleLifecycle.initialize(phaseOptions(options.continueOnInitializeError)), services.moduleLifecycle, options.continueOnInitializeError, (count) => {
+    // Every phase and every module hook checks the signal: a timed-out
+    // bootstrap must not bring modules up after the runtime has already
+    // reported a failed start.
+    if (options.initializeModules && !signal.aborted) {
+        await runLifecyclePhase("initializing", "initialized", () => services.moduleLifecycle.initialize({
+            ...phaseOptions(options.continueOnInitializeError),
+            signal,
+        }), services.moduleLifecycle, options.continueOnInitializeError, (count) => {
             state.counters.initializedModules = count;
         }, (message, opts) => new RuntimeInitializationError(message, { ...identity, ...opts }), state, publish, log);
     }
-    if (options.startModules) {
-        await runLifecyclePhase("starting", "started", () => services.moduleLifecycle.start(phaseOptions(options.continueOnStartError)), services.moduleLifecycle, options.continueOnStartError, (count) => {
+    if (options.startModules && !signal.aborted) {
+        await runLifecyclePhase("starting", "started", () => services.moduleLifecycle.start({
+            ...phaseOptions(options.continueOnStartError),
+            signal,
+        }), services.moduleLifecycle, options.continueOnStartError, (count) => {
             state.counters.startedModules = count;
         }, (message, opts) => new RuntimeStartError(message, {
             ...identity,

package/dist/runtime/runtimeOptions/runtimeOptions.defaults.js

@@ -26,8 +26,10 @@ export const DEFAULT_RUNTIME_OPTIONS = Object.freeze({
         handleSighup: false,
         handleUncaughtException: true,
         handleUnhandledRejection: true,
-        forceExitOnSecondSignal: false,
+        forceExitOnSecondSignal: true,
         forceExitCode: 1,
+        exitOnFatalError: true,
+        fatalExitTimeout: 10_000,
     },
     diagnostics: {
         startupLogging: true,

package/dist/runtime/runtimeOptions/runtimeOptions.mode.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeEnvironmentVariables } from "../runtimeEnvironment/runtimeEnvironment.type.js";
+import type { RuntimeMode } from "./runtimeOptions.type.js";
+/**
+ * Derives the runtime mode used when `RuntimeOptions.mode` is not set.
+ *
+ * `NODE_ENV` is read through `resolveEnvironment()` from `@zudojs/constants`,
+ * so every layer maps the same value to the same environment (`prod` and
+ * `Production` are production, unset is development). `staging` has no
+ * runtime mode of its own and runs as `production`.
+ *
+ * @param variables - Environment variables to read instead of `process.env`.
+ */
+export declare function resolveDefaultRuntimeMode(variables?: RuntimeEnvironmentVariables): RuntimeMode;
+//# sourceMappingURL=runtimeOptions.mode.d.ts.map

package/dist/runtime/runtimeOptions/runtimeOptions.mode.js

@@ -0,0 +1,16 @@
+import { resolveEnvironment } from "@zudojs/constants";
+/**
+ * Derives the runtime mode used when `RuntimeOptions.mode` is not set.
+ *
+ * `NODE_ENV` is read through `resolveEnvironment()` from `@zudojs/constants`,
+ * so every layer maps the same value to the same environment (`prod` and
+ * `Production` are production, unset is development). `staging` has no
+ * runtime mode of its own and runs as `production`.
+ *
+ * @param variables - Environment variables to read instead of `process.env`.
+ */
+export function resolveDefaultRuntimeMode(variables) {
+    const environment = resolveEnvironment(variables === undefined ? undefined : { ...variables });
+    return environment === "staging" ? "production" : environment;
+}
+//# sourceMappingURL=runtimeOptions.mode.js.map

package/dist/runtime/runtimeOptions/runtimeOptions.resolver.js

@@ -1,4 +1,5 @@
 import { DEFAULT_RUNTIME_OPTIONS } from "./runtimeOptions.defaults.js";
+import { resolveDefaultRuntimeMode } from "./runtimeOptions.mode.js";
 import { validateRuntimeName, validateRuntimeTimeout, assertRuntimeMode, assertRuntimeRole, } from "./runtimeOptions.validation.js";
 /**
  * Resolves partial runtime options into a complete immutable runtime configuration.
@@ -14,14 +15,16 @@ export function resolveRuntimeOptions(options = {}) {
      * accepted silently and make the environment report neither
      * production, development, nor test.
      */
-    assertRuntimeMode(options.mode ?? DEFAULT_RUNTIME_OPTIONS.mode);
+    const mode = options.mode ?? resolveDefaultRuntimeMode(options.environment?.variables);
+    assertRuntimeMode(mode);
     assertRuntimeRole(options.role ?? DEFAULT_RUNTIME_OPTIONS.role);
     validateRuntimeName(options.name);
     validateRuntimeTimeout(startup.timeoutMs, "startup");
     validateRuntimeTimeout(shutdown.timeoutMs, "shutdown");
+    validateRuntimeTimeout(signals.fatalExitTimeout, "fatal exit");
     const resolved = {
         name: options.name ?? DEFAULT_RUNTIME_OPTIONS.name,
-        mode: options.mode ?? DEFAULT_RUNTIME_OPTIONS.mode,
+        mode,
         role: options.role ?? DEFAULT_RUNTIME_OPTIONS.role,
         startup: {
             autoLoadModules: startup.autoLoadModules ??
@@ -58,6 +61,10 @@ export function resolveRuntimeOptions(options = {}) {
             forceExitOnSecondSignal: signals.forceExitOnSecondSignal ??
                 DEFAULT_RUNTIME_OPTIONS.signals.forceExitOnSecondSignal,
             forceExitCode: signals.forceExitCode ?? DEFAULT_RUNTIME_OPTIONS.signals.forceExitCode,
+            exitOnFatalError: signals.exitOnFatalError ??
+                DEFAULT_RUNTIME_OPTIONS.signals.exitOnFatalError,
+            fatalExitTimeout: signals.fatalExitTimeout ??
+                DEFAULT_RUNTIME_OPTIONS.signals.fatalExitTimeout,
         },
         diagnostics: {
             startupLogging: diagnostics.startupLogging ??
@@ -87,5 +94,6 @@ export function validateRuntimeOptions(options) {
     validateRuntimeName(options.name);
     validateRuntimeTimeout(options.startup?.timeoutMs, "startup");
     validateRuntimeTimeout(options.shutdown?.timeoutMs, "shutdown");
+    validateRuntimeTimeout(options.signals?.fatalExitTimeout, "fatal exit");
 }
 //# sourceMappingURL=runtimeOptions.resolver.js.map

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

@@ -63,12 +63,27 @@ export interface RuntimeSignalOptions {
     /**
      * When a second termination signal arrives while a graceful stop is
      * already in progress, exit the process immediately with
-     * `forceExitCode`. Off by default: the second signal is logged and
-     * ignored.
+     * `forceExitCode`. On by default, matching `@zudojs/runtime`: an
+     * operator pressing Ctrl-C again on a stuck shutdown is asking for
+     * exactly that. Set to `false` to log and ignore the second signal.
      */
     readonly forceExitOnSecondSignal?: boolean;
     /** Exit code used by `forceExitOnSecondSignal`. Defaults to 1. */
     readonly forceExitCode?: number;
+    /**
+     * After an uncaught exception or unhandled rejection has stopped the
+     * runtime, exit the process with code 1. On by default: the
+     * installed handler suppresses Node's own crash, so without this the
+     * process exited 0 and supervisors never restarted or alerted. Set to
+     * `false` to stop the runtime and leave the process running.
+     */
+    readonly exitOnFatalError?: boolean;
+    /**
+     * How long that fatal-error shutdown may take before the process
+     * exits anyway, in milliseconds. `0` waits for the shutdown however
+     * long it takes. Defaults to 10000.
+     */
+    readonly fatalExitTimeout?: number;
 }
 /**
  * Options controlling runtime diagnostics.
@@ -97,6 +112,7 @@ export interface RuntimeEnvironmentOverrides {
  */
 export interface RuntimeOptions {
     readonly name?: string;
+    /** Omitted: derived from NODE_ENV by `resolveEnvironment()` (@zudojs/constants); staging runs as production. */
     readonly mode?: RuntimeMode;
     readonly role?: RuntimeRole;
     readonly startup?: RuntimeStartupOptions;

package/dist/runtime/runtimeOptions/runtimeOptions.validation.d.ts

@@ -22,5 +22,5 @@ export declare function validateRuntimeName(name: string | undefined): void;
 /**
  * Validates a runtime timeout.
  */
-export declare function validateRuntimeTimeout(timeout: number | undefined, field: "startup" | "shutdown"): void;
+export declare function validateRuntimeTimeout(timeout: number | undefined, field: "startup" | "shutdown" | "fatal exit"): void;
 //# sourceMappingURL=runtimeOptions.validation.d.ts.map

package/dist/runtime/runtimeSignals/runtimeSignals.d.ts

@@ -1,5 +1,11 @@
 import type { Logger } from "../../logging/core/logger.js";
 import type { RuntimeSignalOptions } from "../runtimeOptions/runtimeOptions.type.js";
+/**
+ * Fatal-exit settings are optional on the manager so that a
+ * hand-assembled `signals` object from before they existed still
+ * type-checks; they default to exiting after 10 seconds.
+ */
+type ManagerSignalOptions = Required<Omit<RuntimeSignalOptions, "exitOnFatalError" | "fatalExitTimeout">> & Pick<RuntimeSignalOptions, "exitOnFatalError" | "fatalExitTimeout">;
 /**
  * Termination signals the runtime can react to.
  */
@@ -39,7 +45,7 @@ export interface RuntimeSignalHandlers {
  * Options for the signal manager.
  */
 export interface RuntimeSignalManagerOptions {
-    readonly signals: Required<RuntimeSignalOptions>;
+    readonly signals: ManagerSignalOptions;
     readonly target?: RuntimeSignalTarget;
     readonly logger?: Logger;
 }
@@ -52,8 +58,11 @@ export interface RuntimeSignalManagerOptions {
  *   `unregister()`; both are idempotent.
  * - The first termination signal triggers `onSignal` (graceful stop).
  * - A second termination signal while the first is still being
- *   handled is logged and ignored, unless `forceExitOnSecondSignal`
- *   is on, in which case `target.exit(forceExitCode)` is called.
+ *   handled exits with `forceExitCode` when `forceExitOnSecondSignal`
+ *   is on (the default), and is logged and ignored otherwise.
+ * - An uncaught exception or unhandled rejection runs the fatal
+ *   handler and then exits with code 1, unless `exitOnFatalError` is
+ *   off; `fatalExitTimeout` bounds a shutdown that hangs.
  * - `process.exit` is never called otherwise.
  */
 export declare class RuntimeSignalManager {
@@ -88,6 +97,8 @@ export declare class RuntimeSignalManager {
     unregister(): void;
     private createListener;
     private handleSignal;
+    private runFatal;
     private run;
 }
+export {};
 //# sourceMappingURL=runtimeSignals.d.ts.map

package/dist/runtime/runtimeSignals/runtimeSignals.fatal.d.ts

@@ -0,0 +1,29 @@
+import type { Logger } from "../../logging/core/logger.js";
+import type { RuntimeSignalTarget } from "./runtimeSignals.js";
+/** Default grace period for a fatal-error shutdown, in milliseconds. */
+export declare const DEFAULT_FATAL_EXIT_TIMEOUT = 10000;
+/**
+ * How a fatal process event (uncaughtException, unhandledRejection)
+ * ends the process.
+ */
+export interface RuntimeFatalExitPolicy {
+    /** Exit non-zero once the fatal-error shutdown settles. */
+    readonly exitOnFatalError: boolean;
+    /** Exit anyway if that shutdown takes longer than this. */
+    readonly fatalExitTimeout: number;
+    /** Exit code used for a fatal exit. */
+    readonly exitCode: number;
+}
+/**
+ * Runs the runtime's fatal-error handler and then ends the process
+ * with a non-zero code.
+ *
+ * Installing an `uncaughtException` listener suppresses Node's own
+ * crash, so without an explicit exit the process either ended with
+ * code 0 (supervisors saw a clean exit and never restarted or alerted)
+ * or lingered as a stopped zombie behind any open handle. The grace
+ * timer bounds a shutdown that hangs; both are skipped when
+ * `exitOnFatalError` is off.
+ */
+export declare function runFatalHandler(handler: () => void | Promise<void> | undefined, target: RuntimeSignalTarget | undefined, policy: RuntimeFatalExitPolicy, logger: Logger | undefined, event: string): void;
+//# sourceMappingURL=runtimeSignals.fatal.d.ts.map

package/dist/runtime/runtimeSignals/runtimeSignals.fatal.js

@@ -0,0 +1,51 @@
+/** Default grace period for a fatal-error shutdown, in milliseconds. */
+export const DEFAULT_FATAL_EXIT_TIMEOUT = 10_000;
+/**
+ * Runs the runtime's fatal-error handler and then ends the process
+ * with a non-zero code.
+ *
+ * Installing an `uncaughtException` listener suppresses Node's own
+ * crash, so without an explicit exit the process either ended with
+ * code 0 (supervisors saw a clean exit and never restarted or alerted)
+ * or lingered as a stopped zombie behind any open handle. The grace
+ * timer bounds a shutdown that hangs; both are skipped when
+ * `exitOnFatalError` is off.
+ */
+export function runFatalHandler(handler, target, policy, logger, event) {
+    const exit = () => {
+        if (!policy.exitOnFatalError)
+            return;
+        target?.exit?.(policy.exitCode);
+    };
+    let timer;
+    if (policy.exitOnFatalError && policy.fatalExitTimeout > 0) {
+        timer = setTimeout(() => {
+            logger?.error(`Runtime shutdown after ${event} timed out; exiting.`, {
+                event,
+                timeoutMs: policy.fatalExitTimeout,
+            });
+            exit();
+        }, Math.min(policy.fatalExitTimeout, 2_147_483_647));
+        timer.unref?.();
+    }
+    const finish = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        exit();
+    };
+    let result;
+    try {
+        result = handler();
+    }
+    catch (error) {
+        logger?.error(`Runtime ${event} handler failed.`, error, { event });
+        finish();
+        return;
+    }
+    void Promise.resolve(result)
+        .catch((error) => {
+        logger?.error(`Runtime ${event} handler failed.`, error, { event });
+    })
+        .finally(finish);
+}
+//# sourceMappingURL=runtimeSignals.fatal.js.map

package/dist/runtime/runtimeSignals/runtimeSignals.js

@@ -1,3 +1,4 @@
+import { DEFAULT_FATAL_EXIT_TIMEOUT, runFatalHandler, } from "./runtimeSignals.fatal.js";
 /**
  * Registers and removes process signal/exception handlers on behalf
  * of the runtime.
@@ -7,8 +8,11 @@
  *   `unregister()`; both are idempotent.
  * - The first termination signal triggers `onSignal` (graceful stop).
  * - A second termination signal while the first is still being
- *   handled is logged and ignored, unless `forceExitOnSecondSignal`
- *   is on, in which case `target.exit(forceExitCode)` is called.
+ *   handled exits with `forceExitCode` when `forceExitOnSecondSignal`
+ *   is on (the default), and is logged and ignored otherwise.
+ * - An uncaught exception or unhandled rejection runs the fatal
+ *   handler and then exits with code 1, unless `exitOnFatalError` is
+ *   off; `fatalExitTimeout` bounds a shutdown that hangs.
  * - `process.exit` is never called otherwise.
  */
 export class RuntimeSignalManager {
@@ -91,11 +95,11 @@ export class RuntimeSignalManager {
                 };
             case "uncaughtException":
                 return ((error) => {
-                    this.run(() => this._handlers?.onUncaughtException(error), "uncaughtException");
+                    this.runFatal(() => this._handlers?.onUncaughtException(error), "uncaughtException");
                 });
             case "unhandledRejection":
                 return ((reason) => {
-                    this.run(() => this._handlers?.onUnhandledRejection(reason), "unhandledRejection");
+                    this.runFatal(() => this._handlers?.onUnhandledRejection(reason), "unhandledRejection");
                 });
             default:
                 return () => { };
@@ -118,6 +122,13 @@ export class RuntimeSignalManager {
         });
         this.run(() => this._handlers?.onSignal(signal), signal);
     }
+    runFatal(handler, event) {
+        runFatalHandler(handler, this._target, {
+            exitOnFatalError: this._signals.exitOnFatalError ?? true,
+            fatalExitTimeout: this._signals.fatalExitTimeout ?? DEFAULT_FATAL_EXIT_TIMEOUT,
+            exitCode: 1,
+        }, this._logger, event);
+    }
     run(handler, event) {
         try {
             const result = handler();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Application lifecycle management, execution context propagation, and runtime orchestration for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/constants": "1.1.0"
   },
   "license": "MIT",
   "author": {