@zudojs/core 1.0.0 → 1.2.0

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

@@ -2,7 +2,8 @@ import type { Module, ModuleId } from "../module.js";
 import type { ModuleDefinition } from "../moduleDefinition.definition.js";
 import type { ModuleRegistration, ModuleRegistry } from "../moduleRegistry/index.js";
 import type { ModuleLoader } from "../moduleLoader/index.js";
-import type { ModuleLifecycleOptions, ModuleLifecycleResult, ModuleLifecycleState } from "./moduleLifecycle.type.js";
+import type { ModuleLifecycleOptions, ModuleLifecyclePhaseOptions, ModuleLifecycleResult, ModuleLifecycleState } from "./moduleLifecycle.type.js";
+import type { ModuleDependency } from "../moduleDependency/moduleDependency.type.js";
 /**
  * Module lifecycle manager.
  * Initializes, starts, stops, and destroys modules in dependency order.
@@ -15,10 +16,10 @@ export declare class ModuleLifecycleManager {
     private readonly states;
     private operation;
     constructor(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions);
-    initialize(): Promise<ModuleLifecycleResult>;
-    start(): Promise<ModuleLifecycleResult>;
-    stop(): Promise<ModuleLifecycleResult>;
-    destroy(): Promise<ModuleLifecycleResult>;
+    initialize(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    start(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    stop(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    destroy(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
     /**
      * Rolls back modules that completed earlier phases after a
      * startup failure.
@@ -55,6 +56,14 @@ export declare class ModuleLifecycleManager {
      * optional dependency on the given module.
      */
     private getLoadedDependents;
+    /**
+     * Dependencies of a registered module: those declared on the
+     * definition plus any the loaded instance declares itself
+     * (`Module.dependencies`, e.g. via the BaseModule constructor).
+     * Instance-declared dependencies are required; a definition
+     * entry for the same id wins so optional/version flags survive.
+     */
+    private resolveDependencies;
     startApplication(): Promise<{
         readonly initialized: ModuleLifecycleResult;
         readonly started: ModuleLifecycleResult;
@@ -69,11 +78,27 @@ export declare class ModuleLifecycleManager {
     isInitialized(moduleId: ModuleId): boolean;
     isStarted(moduleId: ModuleId): boolean;
     isDestroyed(moduleId: ModuleId): boolean;
+    /**
+     * Builds the dependency graph over the loaded modules only.
+     *
+     * Lifecycle phases run for loaded modules, so a registered but
+     * unloaded definition (autoLoad: false) must not be able to
+     * break them with a missing or circular dependency of its own.
+     * Dependencies of a loaded module that are not loaded are kept
+     * as edges so the ordering reports them as missing.
+     */
     private createGraph;
     private getStartupOrder;
     private getShutdownOrder;
     private runExclusive;
 }
+/**
+ * Resolves the dependencies of a registration: definition-declared
+ * dependencies plus the ids the loaded instance declares through
+ * `Module.dependencies`. Shared by the lifecycle manager and the
+ * loader so both agree on the graph.
+ */
+export declare function resolveRegistrationDependencies(registry: ModuleRegistry, registration: ModuleRegistration): readonly ModuleDependency[];
 /** Creates a module lifecycle manager. */
 export declare function createModuleLifecycleManager(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions): ModuleLifecycleManager;
 //# sourceMappingURL=moduleLifecycle.lifecycle.d.ts.map

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

@@ -25,11 +25,11 @@ export class ModuleLifecycleManager {
         };
         this.contextStorage = options.contextStorage ?? getDefaultContextStorage();
     }
-    async initialize() {
+    async initialize(options = {}) {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
             try {
-                return await executeLifecyclePhase(this.getStartupOrder(), "initialize", "initializing", "initialized", 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 });
@@ -37,11 +37,11 @@ export class ModuleLifecycleManager {
             }
         });
     }
-    async start() {
+    async start(options = {}) {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
             try {
-                return await executeLifecyclePhase(this.getStartupOrder(), "start", "starting", "started", 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 });
@@ -49,16 +49,16 @@ export class ModuleLifecycleManager {
             }
         });
     }
-    async stop() {
+    async stop(options = {}) {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
-            return executeLifecyclePhase(this.getShutdownOrder(), "stop", "stopping", "stopped", this.options.continueOnStopError, this.registry, this.loader, this.states, this.contextStorage);
+            return executeLifecyclePhase(this.getShutdownOrder(), "stop", "stopping", "stopped", options.continueOnError ?? this.options.continueOnStopError, this.registry, this.loader, this.states, this.contextStorage);
         });
     }
-    async destroy() {
+    async destroy(options = {}) {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
-            return executeLifecyclePhase(this.getShutdownOrder(), "destroy", "destroying", "destroyed", this.options.continueOnDestroyError, this.registry, this.loader, this.states, this.contextStorage);
+            return executeLifecyclePhase(this.getShutdownOrder(), "destroy", "destroying", "destroyed", options.continueOnError ?? this.options.continueOnDestroyError, this.registry, this.loader, this.states, this.contextStorage);
         });
     }
     /**
@@ -178,14 +178,22 @@ export class ModuleLifecycleManager {
                 continue;
             if (registration.state !== "loaded")
                 continue;
-            const dependsOnModule = this.registry
-                .getDependencies(registration.definition.id)
-                .some((dependency) => dependency.id === moduleId);
+            const dependsOnModule = this.resolveDependencies(registration).some((dependency) => dependency.id === moduleId);
             if (dependsOnModule)
                 dependents.push(registration.definition.id);
         }
         return dependents;
     }
+    /**
+     * Dependencies of a registered module: those declared on the
+     * definition plus any the loaded instance declares itself
+     * (`Module.dependencies`, e.g. via the BaseModule constructor).
+     * Instance-declared dependencies are required; a definition
+     * entry for the same id wins so optional/version flags survive.
+     */
+    resolveDependencies(registration) {
+        return resolveRegistrationDependencies(this.registry, registration);
+    }
     async startApplication() {
         /*
          * When continueOn*Error is disabled, phase failures are
@@ -220,21 +228,31 @@ export class ModuleLifecycleManager {
     isDestroyed(moduleId) {
         return isModuleDestroyed(moduleId, this.states);
     }
+    /**
+     * Builds the dependency graph over the loaded modules only.
+     *
+     * Lifecycle phases run for loaded modules, so a registered but
+     * unloaded definition (autoLoad: false) must not be able to
+     * break them with a missing or circular dependency of its own.
+     * Dependencies of a loaded module that are not loaded are kept
+     * as edges so the ordering reports them as missing.
+     */
     createGraph() {
-        const nodes = this.registry.getAll().map((r) => ({
+        const nodes = this.registry
+            .getAll()
+            .filter((r) => r.state === "loaded")
+            .map((r) => ({
             id: r.definition.id,
-            dependencies: this.registry.getDependencies(r.definition.id),
+            dependencies: this.resolveDependencies(r),
             version: r.definition.version,
         }));
         return createModuleDependencyGraph(nodes);
     }
     getStartupOrder() {
-        const order = resolveModuleStartupOrder(this.createGraph());
-        return Object.freeze(order.filter((id) => this.registry.get(id)?.state === "loaded"));
+        return resolveModuleStartupOrder(this.createGraph());
     }
     getShutdownOrder() {
-        const order = resolveModuleShutdownOrder(this.createGraph());
-        return Object.freeze(order.filter((id) => this.registry.get(id)?.state === "loaded"));
+        return resolveModuleShutdownOrder(this.createGraph());
     }
     async runExclusive(operation) {
         while (this.operation)
@@ -253,6 +271,29 @@ export class ModuleLifecycleManager {
         }
     }
 }
+/**
+ * Resolves the dependencies of a registration: definition-declared
+ * dependencies plus the ids the loaded instance declares through
+ * `Module.dependencies`. Shared by the lifecycle manager and the
+ * loader so both agree on the graph.
+ */
+export function resolveRegistrationDependencies(registry, registration) {
+    const declared = registry.getDependencies(registration.definition.id);
+    const instanceDependencies = registration.instance?.dependencies ?? [];
+    if (instanceDependencies.length === 0)
+        return declared;
+    const seen = new Set(declared.map((dependency) => dependency.id));
+    const merged = [...declared];
+    for (const id of instanceDependencies) {
+        if (typeof id !== "string" || id.length === 0 || seen.has(id))
+            continue;
+        if (id === registration.definition.id)
+            continue;
+        seen.add(id);
+        merged.push(Object.freeze({ id, optional: false }));
+    }
+    return Object.freeze(merged);
+}
 /** Creates a module lifecycle manager. */
 export function createModuleLifecycleManager(registry, loader, options = {}) {
     return new ModuleLifecycleManager(registry, loader, options);

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

@@ -86,6 +86,26 @@ export interface ModuleLifecycleOptions {
      */
     readonly contextStorage?: ContextStorage;
 }
+/**
+ * Per-call overrides accepted by the ModuleLifecycleManager phase
+ * methods (initialize/start/stop/destroy).
+ */
+export interface ModuleLifecyclePhaseOptions {
+    /**
+     * Overrides the manager's continueOn*Error setting for this one
+     * phase run. The runtime passes its own startup/shutdown flags
+     * here so a hand-assembled manager cannot disagree with the
+     * 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";
 /**
  * Error thrown when a module lifecycle operation fails.

package/dist/modules/moduleLoader/moduleLoader.loader.js

@@ -76,6 +76,56 @@ export class ModuleLoader {
      */
     async loadClosure(requested, options) {
         const closure = this.collectClosure(requested);
+        const loaded = [];
+        const alreadyLoaded = [];
+        const order = [];
+        /*
+         * Instances may declare dependencies of their own
+         * (Module.dependencies) that the definition does not list.
+         * Those are only known after instantiation, so the closure is
+         * extended and loaded in rounds until nothing new appears.
+         */
+        let pending = new Set(closure.keys());
+        while (pending.size > 0) {
+            const graph = this.createGraph([...closure.values()]);
+            const roundOrder = resolveModuleStartupOrder(graph).filter((id) => pending.has(id));
+            const discovered = [];
+            for (const moduleId of roundOrder) {
+                const registration = this.registry.get(moduleId);
+                if (!registration)
+                    throw new ModuleLoadError(moduleId, new Error(`Module "${moduleId}" disappeared from the registry during loading.`));
+                order.push(moduleId);
+                let instance;
+                if (registration.state === "loaded" && registration.instance) {
+                    instance = registration.instance;
+                    alreadyLoaded.push(instance);
+                }
+                else {
+                    instance = await this.instantiate(registration.definition);
+                    loaded.push(instance);
+                }
+                for (const dependencyId of instance.dependencies ?? []) {
+                    if (closure.has(dependencyId))
+                        continue;
+                    if (!this.registry.has(dependencyId))
+                        throw new MissingModuleDependencyError(moduleId, dependencyId);
+                    discovered.push(dependencyId);
+                }
+            }
+            const extra = this.collectClosure(discovered);
+            pending = new Set();
+            for (const [id, definition] of extra) {
+                if (closure.has(id))
+                    continue;
+                closure.set(id, definition);
+                pending.add(id);
+            }
+        }
+        /*
+         * Skipped modules are determined after loading so that an
+         * autoLoad:false module pulled in by an instance-declared
+         * dependency is reported as loaded, not skipped.
+         */
         const skipped = [];
         if (options.reportSkipped) {
             for (const definition of this.registry.getDefinitions()) {
@@ -84,28 +134,6 @@ export class ModuleLoader {
                 }
             }
         }
-        if (closure.size === 0)
-            return {
-                loaded: [],
-                alreadyLoaded: [],
-                skipped: Object.freeze([...skipped]),
-                order: [],
-            };
-        const graph = this.createGraph([...closure.values()]);
-        const order = resolveModuleStartupOrder(graph);
-        const loaded = [];
-        const alreadyLoaded = [];
-        for (const moduleId of order) {
-            const registration = this.registry.get(moduleId);
-            if (!registration)
-                throw new ModuleLoadError(moduleId, new Error(`Module "${moduleId}" disappeared from the registry during loading.`));
-            if (registration.state === "loaded" && registration.instance) {
-                alreadyLoaded.push(registration.instance);
-                continue;
-            }
-            const instance = await this.instantiate(registration.definition);
-            loaded.push(instance);
-        }
         return {
             loaded: Object.freeze([...loaded]),
             alreadyLoaded: Object.freeze([...alreadyLoaded]),
@@ -174,9 +202,17 @@ export class ModuleLoader {
                  * they cannot enumerate or reach undeclared modules.
                  */
                 moduleContexts: (dependencyId) => this.contexts.get(dependencyId),
-                declaredDependencies: this.registry
-                    .getDependencies(moduleId)
-                    .map((dependency) => dependency.id),
+                /*
+                 * Dependencies declared by the instance itself
+                 * (Module.dependencies) are honoured alongside the
+                 * definition's, matching the lifecycle ordering.
+                 */
+                declaredDependencies: [
+                    ...this.registry
+                        .getDependencies(moduleId)
+                        .map((dependency) => dependency.id),
+                    ...(module.dependencies ?? []),
+                ],
             });
             this.contexts.set(moduleId, context);
             this.registry.setState(moduleId, "loaded", { instance: module });

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(), 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(), 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,
@@ -44,6 +55,19 @@ export async function executeBootstrapPipeline(options, services, state, signal,
         }), state, publish, log);
     }
 }
+/**
+ * Per-phase options handed to the ModuleLifecycleManager.
+ *
+ * The runtime's continueOn*Error flag can only relax the manager: when
+ * it is on, the manager must keep going too (otherwise it would roll
+ * every module back and throw, and the runtime would report READY
+ * with nothing running). When it is off the manager keeps its own
+ * setting; a permissive manager then returns the failures and the
+ * runtime throws and unwinds.
+ */
+function phaseOptions(continueOnError) {
+    return continueOnError ? { continueOnError: true } : {};
+}
 async function loadModules(moduleLoader, identity, state, publish, log) {
     publish("loading");
     log("debug", "Loading runtime modules.");

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.
@@ -8,12 +9,22 @@ export function resolveRuntimeOptions(options = {}) {
     const shutdown = options.shutdown ?? {};
     const signals = options.signals ?? {};
     const diagnostics = options.diagnostics ?? {};
+    /*
+     * Mode and role are validated here, not only in
+     * validateRuntimeOptions(): an unknown mode would otherwise be
+     * accepted silently and make the environment report neither
+     * production, development, nor test.
+     */
+    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 ??
@@ -50,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 ??
@@ -79,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