@zudojs/runtime 1.2.1 → 1.3.1

package/README.md

@@ -44,6 +44,116 @@ await runtime.stop();
 
 Modules start in dependency order and stop in reverse.
 
+## Lifecycle states
+
+`start()` walks the state machine in order:
+
+```
+created -> initializing -> initialized -> starting -> running -> stopping -> stopped
+```
+
+Every module's `onInitialize` runs while `runtime.state` is
+`initializing`; once all have initialized the runtime passes through
+`initialized` to `starting`, and every `onReady` runs under `starting`.
+`start()` resolves in `running`. A failure in any phase ends in `failed`,
+which is still stoppable. `created` may go straight to `stopped` (a
+`stop()` before `start()`). Only `stopped` is terminal:
+`isTerminalState("failed")` is `false`, because `stop()` moves a failed
+runtime on to `stopped`.
+
+## Startup failures
+
+If any module throws, the runtime rolls back (modules that already started
+are stopped and destroyed in reverse) and the state becomes `failed`.
+`start()` then rejects with a `RuntimeStartError` that wraps the error your
+module threw rather than re-throwing it: the original is `error.cause`,
+`error.phase` is `"initialize"` (an `onInitialize` threw) or `"start"` (an
+`onReady` threw), and `error.failedModuleId` names the module.
+
+Two subclasses of `RuntimeStartError` narrow it down:
+
+- `RuntimeInitializationError` — the failure was in the initialize phase
+  (an `onInitialize` threw, or the configuration manager failed to load).
+- `RuntimeRollbackError` — startup failed AND the rollback that followed
+  failed, so a module may still hold resources. `phase`,
+  `failedModuleId` and `cause` still describe the startup failure;
+  `originalError` is the error `start()` would otherwise have thrown, and
+  `rollbackError` is what failed during rollback (an `AggregateError`
+  when several modules failed). Call `stop()` to retry the release.
+
+A shutdown triggered by `SIGTERM`, `SIGINT` or a fatal error has no caller
+to reject; if it fails, the runtime logs a `RuntimeSignalError` (with the
+failure as `cause`) as the `error` field of its "Shutdown handler
+failed." entry.
+
+## Signals and exit codes
+
+With `handleSignals: true`, a `SIGTERM` or `SIGINT` runs a graceful
+`stop()`, and the runtime holds the process open until that shutdown has
+finished — every `onShutdown` and `onDestroy` hook runs, even when nothing
+else is keeping the event loop alive or a hook closes the last open socket
+before its async work is done. (Node's signal listeners do not keep the
+process alive by themselves; before this was fixed, a process with nothing
+else pending exited with code 0 mid-shutdown, still `running` or
+`stopping`.)
+
+When the shutdown is over the runtime lets the process exit on its own
+rather than calling `process.exit()`, so your own `SIGTERM` listeners and
+pending writes still finish:
+
+- clean shutdown: the exit code is left alone (0 unless you set one);
+- failed shutdown — `stop()` rejected (including an `onShutdown` that
+  outlives `shutdownTimeout`, which leaves the runtime `failed`), or a
+  module's hook failed (`status.shutdownFailures` is non-empty):
+  `process.exitCode` is set to `1` and the failure is logged as a
+  `RuntimeSignalError`. A failed stop publishes `runtime.failed`
+  (`phase: "stop"`) once;
+- fatal error (`exitOnFatalError`): `process.exit(1)` once shutdown ends;
+- second `SIGTERM`/`SIGINT` during shutdown (`forceExitOnSecondSignal`):
+  `process.exit(1)` at once.
+
+If something outside the runtime still holds a handle (a server you did not
+close in a module), the process stays up after the runtime has stopped, as
+it would without the runtime.
+
+```typescript
+import { RuntimeStartError } from "@zudojs/runtime";
+
+try {
+  await runtime.start();
+} catch (error) {
+  if (error instanceof RuntimeStartError) {
+    const original = error.cause; // what the module threw
+    logger.error(`Module ${error.failedModuleId} failed in ${error.phase}`, {
+      original,
+    });
+  }
+  await runtime.stop(); // release anything rollback did not reach
+}
+```
+
+A startup that outlives `startupTimeout` rejects with `RuntimeTimeoutError`,
+which has no cause.
+
+## Container ownership
+
+The runtime does not create the container; you pass it in, so by default
+you own it and `stop()` leaves it alone. Dispose it yourself after
+`stop()`:
+
+```typescript
+await runtime.stop();
+await container.dispose();
+```
+
+or hand ownership to the runtime with `disposeContainerOnStop: true`, and
+`stop()` disposes it after every module has shut down and been destroyed.
+A disposal failure does not fail `stop()`; it is logged and recorded in
+`runtime.status.shutdownFailures` under the id `"(container)"`
+(exported as `CONTAINER_SHUTDOWN_ID`).
+`createTestRuntime` (from `@zudojs/runtime/testing`) creates its own
+container and sets `disposeContainerOnStop: true`.
+
 ## Readiness and health
 
 Readiness checks are registered on the runtime and re-evaluated on demand.
@@ -104,7 +214,7 @@ Subscribe with `bus.on(type, handler)`; the payload types are in
 
 | Event | Payload |
 | --- | --- |
-| `runtime.initializing`, `runtime.running`, `runtime.stopping`, `runtime.stopped` | `RuntimeEventPayload` |
+| `runtime.initializing`, `runtime.initialized`, `runtime.starting`, `runtime.running`, `runtime.stopping`, `runtime.stopped` | `RuntimeEventPayload` |
 | `runtime.failed` | `RuntimeFailureEventPayload` |
 | `runtime.module.initializing` / `initialized` / `starting` / `started` / `stopping` / `stopped` / `failed` | `RuntimeModuleEventPayload` |
 | `runtime.shutdown.drain`, `runtime.shutdown.complete` | `RuntimeEventPayload` |
@@ -142,6 +252,7 @@ createRuntime(dependencies, {
   trackHealth: true,
   readinessCheckTimeout: 5_000, // 0 removes the bound
   parallelInitialization: false, // initialize each depth group at once
+  disposeContainerOnStop: false, // true: stop() disposes the container
   metadata: { region: "eu-west-1" },
 });
 ```

package/dist/lifecycle/lifecycle.core.js

@@ -2,7 +2,7 @@ import { createConfigurationManager } from "@zudojs/core";
 import { createModuleEventPayload } from "../runtimeEvents/runtimeEvents.core.js";
 import { resolveDependencies } from "../dependencyGraph/index.js";
 import { LifecycleCancellation } from "./lifecycle.cancellation.js";
-import { RuntimeDependencyError, RuntimeStartError, RuntimeStateError, } from "../runtimeError/index.js";
+import { RuntimeDependencyError, RuntimeInitializationError, RuntimeStartError, RuntimeStateError, } from "../runtimeError/index.js";
 /**
  * Manages the lifecycle of runtime modules.
  */
@@ -75,8 +75,7 @@ export class LifecycleManager {
             await this.configuration.initialize();
         }
         catch (error) {
-            throw new RuntimeStartError("Configuration failed to load.", {
-                phase: "initialize",
+            throw new RuntimeInitializationError("Configuration failed to load.", {
                 ...(error instanceof Error && { cause: error }),
             });
         }

package/dist/runtime/runtime.core.d.ts

@@ -137,12 +137,26 @@ export declare class DefaultRuntime implements Runtime {
      * Performs runtime startup.
      */
     private performStart;
+    /**
+     * Walks `initializing` -> `initialized` -> `starting` once every module
+     * has initialized, before the first `onReady` hook runs.
+     */
+    private enterStartingPhase;
+    /**
+     * Disposes the container when the runtime owns it
+     * (`disposeContainerOnStop`). Returns the failure to record, if any.
+     */
+    private releaseContainer;
     /**
      * Performs runtime shutdown.
      */
     private performStop;
     /**
      * Runs shutdown in response to a termination signal.
+     *
+     * Rejects when the stop failed or a module failed to shut down, so the
+     * signal handler logs a `RuntimeSignalError` and sets a non-zero exit
+     * code. Swallowing the failure here let a broken shutdown exit with 0.
      */
     private handleShutdownSignal;
     /**

package/dist/runtime/runtime.core.js

@@ -4,12 +4,13 @@ import { createRuntimeContext, withRuntimeContextState, } from "../runtimeContex
 import { LifecycleManager } from "../lifecycle/index.js";
 import { executeStartup, rollbackStartup } from "../startup/index.js";
 import { executeShutdown } from "../shutdown/index.js";
+import { disposeRuntimeContainer } from "../shutdown/shutdown.container.js";
 import { SignalHandler } from "../signalHandler/index.js";
 import { ReadinessTracker } from "../readiness/index.js";
 import { computeRuntimeHealth } from "../health/index.js";
 import { createRuntimeEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, publishRuntimeEvent, } from "../runtimeEvents/index.js";
 import { createEvent } from "@zudojs/events";
-import { RuntimeStateError, toRuntimeError } from "../runtimeError/index.js";
+import { RuntimeRollbackError, RuntimeStartError, RuntimeStateError, RuntimeStopError, toRuntimeError, } from "../runtimeError/index.js";
 /**
  * Default runtime implementation.
  */
@@ -224,6 +225,10 @@ export class DefaultRuntime {
             this._state = "stopped";
             this._stoppedAt = new Date();
             this.signalHandler.unregister();
+            const containerFailure = await this.releaseContainer();
+            if (containerFailure !== undefined) {
+                this._shutdownFailures = [containerFailure];
+            }
             return;
         }
         if (!canStop(this._state)) {
@@ -250,7 +255,7 @@ export class DefaultRuntime {
         // while modules are still coming up must be handled, not ignored.
         this.signalHandler.register(() => this.handleShutdownSignal());
         try {
-            await executeStartup(this.lifecycle, this.options.runtimeId, this._contextBase.eventBus, this.logger, this.options.emitEvents, this.options.startupTimeout);
+            await executeStartup(this.lifecycle, this.options.runtimeId, this._contextBase.eventBus, this.logger, this.options.emitEvents, this.options.startupTimeout, () => this.enterStartingPhase());
             this.transitionTo("running");
             this._startedAt = new Date();
             // Evaluate any checks registered before startup instead of
@@ -282,31 +287,73 @@ export class DefaultRuntime {
             this.logger.error("Runtime failed to start.", {
                 errorMessage: runtimeError.message,
             });
-            if (this.options.emitEvents) {
+            // A module failure was already published by executeStartup, with the
+            // failing module and phase; publishing it again here reported one
+            // failure twice. A timeout or other error is published here.
+            const alreadyPublished = error instanceof RuntimeStartError && error.failedModuleId !== undefined;
+            if (this.options.emitEvents && !alreadyPublished) {
                 this.emitEvent("runtime.failed", createFailureEventPayload(this.options.runtimeId, "failed", runtimeError, "startup"));
             }
+            let rollbackError;
             try {
                 const rollbackFailures = await rollbackStartup(this.lifecycle, this.logger);
                 if (rollbackFailures.length > 0) {
                     this.logger.error("Rollback completed with failures.", {
                         failedModules: rollbackFailures.map((failure) => failure.moduleId),
                     });
+                    rollbackError =
+                        rollbackFailures.length === 1
+                            ? rollbackFailures[0].error
+                            : new AggregateError(rollbackFailures.map((failure) => failure.error), `${rollbackFailures.length} modules failed to roll back: ` +
+                                rollbackFailures.map((f) => f.moduleId).join(", ") +
+                                ".");
                 }
             }
-            catch (rollbackError) {
+            catch (caught) {
+                rollbackError =
+                    caught instanceof Error ? caught : new Error(String(caught));
                 this.logger.error("Rollback failed.", {
-                    errorMessage: rollbackError instanceof Error
-                        ? rollbackError.message
-                        : String(rollbackError),
+                    errorMessage: rollbackError.message,
                 });
             }
+            // A rollback that failed leaves resources behind; say so rather than
+            // reporting only the startup failure. The startup failure stays
+            // reachable as `originalError`, and `cause` is unchanged.
+            const thrown = rollbackError === undefined
+                ? runtimeError
+                : new RuntimeRollbackError(runtimeError, rollbackError);
+            this._error = thrown;
             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;
+            throw thrown;
+        }
+    }
+    /**
+     * Walks `initializing` -> `initialized` -> `starting` once every module
+     * has initialized, before the first `onReady` hook runs.
+     */
+    enterStartingPhase() {
+        this.transitionTo("initialized");
+        if (this.options.emitEvents) {
+            this.emitEvent("runtime.initialized");
+        }
+        this.transitionTo("starting");
+        if (this.options.emitEvents) {
+            this.emitEvent("runtime.starting");
         }
     }
+    /**
+     * Disposes the container when the runtime owns it
+     * (`disposeContainerOnStop`). Returns the failure to record, if any.
+     */
+    async releaseContainer() {
+        if (!this.options.disposeContainerOnStop) {
+            return undefined;
+        }
+        return disposeRuntimeContainer(this._contextBase.container, this.logger);
+    }
     /**
      * Performs runtime shutdown.
      */
@@ -316,20 +363,29 @@ export class DefaultRuntime {
         if (this.options.emitEvents) {
             this.emitEvent("runtime.stopping");
         }
+        // `executeShutdown` publishes `runtime.failed` itself when it rejects,
+        // so the catch below only publishes for a failure raised after it.
+        // Publishing on both paths delivered every failed stop twice.
+        let shutdownSettled = false;
         try {
             const result = await executeShutdown(this.lifecycle, this.options.runtimeId, this._contextBase.eventBus, this.logger, this.options.shutdownTimeout, this.options.emitEvents);
-            this._shutdownFailures = result.failures;
+            shutdownSettled = true;
+            const containerFailure = await this.releaseContainer();
+            this._shutdownFailures =
+                containerFailure === undefined
+                    ? result.failures
+                    : [...result.failures, containerFailure];
             this.transitionTo("stopped");
             this._stoppedAt = new Date();
             if (this.options.emitEvents) {
                 this.emitEvent("runtime.stopped");
             }
-            if (result.failures.length > 0) {
+            if (this._shutdownFailures.length > 0) {
                 // A teardown that dropped modules on the floor must not read as
                 // a clean stop; `status.shutdownFailures` records what failed.
                 this.logger.warn("Runtime stopped with module failures.", {
                     runtimeId: this.options.runtimeId,
-                    failedModules: result.failures.map((failure) => failure.moduleId),
+                    failedModules: this._shutdownFailures.map((failure) => failure.moduleId),
                 });
             }
             else {
@@ -345,7 +401,7 @@ export class DefaultRuntime {
             this.logger.error("Runtime failed to stop.", {
                 errorMessage: runtimeError.message,
             });
-            if (this.options.emitEvents) {
+            if (this.options.emitEvents && shutdownSettled) {
                 this.emitEvent("runtime.failed", createFailureEventPayload(this.options.runtimeId, "failed", runtimeError, "stop"));
             }
             this.transitionTo("failed");
@@ -360,14 +416,22 @@ export class DefaultRuntime {
     }
     /**
      * Runs shutdown in response to a termination signal.
+     *
+     * Rejects when the stop failed or a module failed to shut down, so the
+     * signal handler logs a `RuntimeSignalError` and sets a non-zero exit
+     * code. Swallowing the failure here let a broken shutdown exit with 0.
      */
     async handleShutdownSignal() {
-        try {
-            await this.stop();
-        }
-        catch (error) {
-            this.logger.error("Shutdown failed.", {
-                errorMessage: error instanceof Error ? error.message : String(error),
+        await this.stop();
+        const failures = this._shutdownFailures;
+        if (failures.length > 0) {
+            throw new RuntimeStopError(`Runtime stopped with ${failures.length} module failure(s): ` +
+                failures.map((failure) => failure.moduleId).join(", ") +
+                ".", {
+                phase: "shutdown",
+                cause: failures.length === 1
+                    ? failures[0].error
+                    : new AggregateError(failures.map((failure) => failure.error)),
             });
         }
     }

package/dist/runtimeError/runtimeError.base.d.ts

@@ -28,11 +28,18 @@ export declare class RuntimeStopError extends RuntimeError {
     });
 }
 /**
- * Error thrown when runtime initialization fails.
+ * Error thrown when startup fails during initialization: a module's
+ * `onInitialize` threw, or the configuration manager failed to load.
+ *
+ * A {@link RuntimeStartError} with `phase: "initialize"`, so handlers
+ * written against `RuntimeStartError` keep matching. `cause` is the
+ * original error and `failedModuleId` names the module (absent for a
+ * configuration failure).
  */
-export declare class RuntimeInitializationError extends RuntimeError {
+export declare class RuntimeInitializationError extends RuntimeStartError {
     constructor(message: string, options?: {
         readonly cause?: Error;
+        readonly failedModuleId?: string;
     });
 }
 /**
@@ -44,9 +51,17 @@ export declare class RuntimeTimeoutError extends RuntimeError {
     constructor(operation: string, timeoutMs: number);
 }
 /**
- * Error thrown when runtime rollback fails.
+ * Error thrown when startup failed and the rollback that followed failed
+ * too, so some module may still hold resources.
+ *
+ * A {@link RuntimeStartError} describing the ORIGINAL failure: `phase`,
+ * `failedModuleId` and `cause` (what the module threw) match the error
+ * `start()` would otherwise have rejected with, which is kept whole as
+ * `originalError`. `rollbackError` is what failed during rollback (an
+ * `AggregateError` when several modules failed). Call `stop()` to retry
+ * releasing what rollback did not reach.
  */
-export declare class RuntimeRollbackError extends RuntimeError {
+export declare class RuntimeRollbackError extends RuntimeStartError {
     readonly originalError: Error;
     readonly rollbackError: Error;
     constructor(originalError: Error, rollbackError: Error);
@@ -67,11 +82,18 @@ export declare class RuntimeDependencyError extends RuntimeError {
     constructor(moduleId: string, dependencyId: string);
 }
 /**
- * Error thrown when runtime receives multiple signals.
+ * Reports a shutdown triggered by a signal (`SIGTERM`, `SIGINT`, or
+ * `"fatal"` for an uncaught exception or unhandled rejection) that failed.
+ *
+ * Signal listeners have no caller to throw to, so the signal handler logs
+ * this error (as the `error` field of its "Shutdown handler failed." log
+ * entry) with the shutdown failure as `cause`.
  */
 export declare class RuntimeSignalError extends RuntimeError {
     readonly signal: string;
-    constructor(signal: string);
+    constructor(signal: string, options?: {
+        readonly cause?: unknown;
+    });
 }
 /**
  * Converts an unknown error to a RuntimeError.

package/dist/runtimeError/runtimeError.base.js

@@ -41,15 +41,22 @@ export class RuntimeStopError extends RuntimeError {
     }
 }
 /**
- * Error thrown when runtime initialization fails.
+ * Error thrown when startup fails during initialization: a module's
+ * `onInitialize` threw, or the configuration manager failed to load.
+ *
+ * A {@link RuntimeStartError} with `phase: "initialize"`, so handlers
+ * written against `RuntimeStartError` keep matching. `cause` is the
+ * original error and `failedModuleId` names the module (absent for a
+ * configuration failure).
  */
-export class RuntimeInitializationError extends RuntimeError {
+export class RuntimeInitializationError extends RuntimeStartError {
     constructor(message, options = {}) {
         super(message, {
-            cause: options.cause,
-            metadata: {
-                phase: "initialization",
-            },
+            phase: "initialize",
+            ...(options.cause !== undefined && { cause: options.cause }),
+            ...(options.failedModuleId !== undefined && {
+                failedModuleId: options.failedModuleId,
+            }),
         });
     }
 }
@@ -71,18 +78,30 @@ export class RuntimeTimeoutError extends RuntimeError {
     }
 }
 /**
- * Error thrown when runtime rollback fails.
+ * Error thrown when startup failed and the rollback that followed failed
+ * too, so some module may still hold resources.
+ *
+ * A {@link RuntimeStartError} describing the ORIGINAL failure: `phase`,
+ * `failedModuleId` and `cause` (what the module threw) match the error
+ * `start()` would otherwise have rejected with, which is kept whole as
+ * `originalError`. `rollbackError` is what failed during rollback (an
+ * `AggregateError` when several modules failed). Call `stop()` to retry
+ * releasing what rollback did not reach.
  */
-export class RuntimeRollbackError extends RuntimeError {
+export class RuntimeRollbackError extends RuntimeStartError {
     originalError;
     rollbackError;
     constructor(originalError, rollbackError) {
-        super("Runtime rollback failed. Original error suppressed.", {
-            cause: rollbackError,
-            metadata: {
-                originalErrorMessage: originalError.message,
-                rollbackErrorMessage: rollbackError.message,
-            },
+        const start = originalError instanceof RuntimeStartError ? originalError : undefined;
+        const cause = start !== undefined && start.cause instanceof Error
+            ? start.cause
+            : originalError;
+        super(`${originalError.message} Rollback also failed: ${rollbackError.message}`, {
+            phase: start?.phase ?? "startup",
+            cause,
+            ...(start?.failedModuleId !== undefined && {
+                failedModuleId: start.failedModuleId,
+            }),
         });
         this.originalError = originalError;
         this.rollbackError = rollbackError;
@@ -120,12 +139,25 @@ export class RuntimeDependencyError extends RuntimeError {
     }
 }
 /**
- * Error thrown when runtime receives multiple signals.
+ * Reports a shutdown triggered by a signal (`SIGTERM`, `SIGINT`, or
+ * `"fatal"` for an uncaught exception or unhandled rejection) that failed.
+ *
+ * Signal listeners have no caller to throw to, so the signal handler logs
+ * this error (as the `error` field of its "Shutdown handler failed." log
+ * entry) with the shutdown failure as `cause`.
  */
 export class RuntimeSignalError extends RuntimeError {
     signal;
-    constructor(signal) {
-        super(`Runtime received unexpected signal "${signal}".`, {
+    constructor(signal, options = {}) {
+        const detail = options.cause === undefined
+            ? undefined
+            : options.cause instanceof Error
+                ? options.cause.message
+                : String(options.cause);
+        super(detail === undefined
+            ? `Runtime received unexpected signal "${signal}".`
+            : `Shutdown triggered by "${signal}" failed: ${detail}`, {
+            ...(options.cause instanceof Error && { cause: options.cause }),
             metadata: {
                 signal,
             },

package/dist/runtimeEvents/runtimeEvents.type.d.ts

@@ -3,9 +3,10 @@ import type { RuntimeFailureState, RuntimeState } from "../runtimeState/runtimeS
  * Runtime lifecycle events.
  *
  * These events are emitted through the EventBus when
- * the runtime transitions through its lifecycle.
+ * the runtime transitions through its lifecycle. Derived from
+ * {@link RuntimeEventMap}, so every event with a payload type is named here.
  */
-export type RuntimeEventType = "runtime.initializing" | "runtime.running" | "runtime.stopping" | "runtime.stopped" | "runtime.failed" | "runtime.module.initializing" | "runtime.module.initialized" | "runtime.module.starting" | "runtime.module.started" | "runtime.module.stopping" | "runtime.module.stopped" | "runtime.module.failed" | "runtime.shutdown.drain" | "runtime.shutdown.complete" | "runtime.health.changed" | "runtime.readiness.changed";
+export type RuntimeEventType = keyof RuntimeEventMap;
 /**
  * Base payload for all runtime events.
  */
@@ -60,17 +61,19 @@ export interface RuntimeReadinessEventPayload extends RuntimeEventPayload {
 /**
  * Event types carrying a {@link RuntimeModuleEventPayload}.
  */
-export type RuntimeModuleEventType = "runtime.module.initializing" | "runtime.module.initialized" | "runtime.module.starting" | "runtime.module.started" | "runtime.module.stopping" | "runtime.module.stopped" | "runtime.module.failed";
+export type RuntimeModuleEventType = Extract<RuntimeEventType, `runtime.module.${string}`>;
 /**
  * Maps event types to their payload types.
  *
- * Every entry here is emitted by the runtime. Entries for events nothing
- * ever published (`runtime.created`, `runtime.initialized`,
- * `runtime.starting`) were removed rather than left as names a consumer
- * could subscribe to and never hear from.
+ * Every entry here is emitted by the runtime. `runtime.created` is not:
+ * nothing is subscribed before construction. `runtime.initialized` and
+ * `runtime.starting` are published between module initialization and the
+ * first `onReady` hook.
  */
 export interface RuntimeEventMap {
     "runtime.initializing": RuntimeEventPayload;
+    "runtime.initialized": RuntimeEventPayload;
+    "runtime.starting": RuntimeEventPayload;
     "runtime.running": RuntimeEventPayload;
     "runtime.stopping": RuntimeEventPayload;
     "runtime.stopped": RuntimeEventPayload;

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

@@ -98,6 +98,20 @@ export interface RuntimeOptions {
      * @default false
      */
     readonly parallelInitialization?: boolean;
+    /**
+     * Whether `stop()` disposes the container passed in `dependencies`.
+     *
+     * The caller that created the container owns it, so by default the
+     * runtime leaves it alone: dispose it yourself after `stop()`, or set
+     * this to hand ownership to the runtime. It is disposed after every
+     * module has shut down and been destroyed (or on `stop()` of a runtime
+     * that never started). A disposal failure is recorded in
+     * `status.shutdownFailures` under `"(container)"` rather than failing
+     * the stop. `createTestRuntime` creates its own container and sets this.
+     *
+     * @default false
+     */
+    readonly disposeContainerOnStop?: boolean;
     /**
      * Additional runtime metadata.
      */
@@ -123,6 +137,7 @@ export interface ResolvedRuntimeOptions {
     readonly trackHealth: boolean;
     readonly readinessCheckTimeout: number;
     readonly parallelInitialization: boolean;
+    readonly disposeContainerOnStop: boolean;
     readonly metadata: Readonly<Record<string, unknown>>;
 }
 /**
@@ -141,6 +156,7 @@ export declare const DEFAULT_RUNTIME_OPTIONS: Readonly<{
     readonly trackHealth: true;
     readonly readinessCheckTimeout: 5000;
     readonly parallelInitialization: false;
+    readonly disposeContainerOnStop: false;
     readonly applicationVersion: "0.1.0";
     readonly metadata: Readonly<{}>;
 }>;

package/dist/runtimeOptions/runtimeOptions.type.js

@@ -14,6 +14,7 @@ export const DEFAULT_RUNTIME_OPTIONS = Object.freeze({
     trackHealth: true,
     readinessCheckTimeout: 5_000,
     parallelInitialization: false,
+    disposeContainerOnStop: false,
     applicationVersion: "0.1.0",
     // `metadata` is required on ResolvedRuntimeOptions, so it needs a
     // default; without one the resolved options claimed a value the

package/dist/runtimeState/runtimeState.core.d.ts

@@ -4,7 +4,13 @@ import type { RuntimeState, RuntimeStatus } from "./runtimeState.type.js";
  */
 export declare const RUNTIME_STATE_TRANSITIONS: Readonly<Record<RuntimeState, readonly RuntimeState[]>>;
 /**
- * Terminal runtime states.
+ * Terminal runtime states: no further transition is possible.
+ *
+ * Only `stopped`. `failed` is NOT terminal: `stop()` is allowed from it
+ * (`failed -> stopping -> stopped`) so an operator can release whatever
+ * startup rollback did not reach. It used to be listed here, so
+ * `isTerminalState("failed")` claimed a state was final while `stop()`
+ * still moved out of it.
  */
 export declare const TERMINAL_STATES: readonly RuntimeState[];
 /**
@@ -28,7 +34,9 @@ export declare function canTransition(from: RuntimeState, to: RuntimeState): boo
  */
 export declare function assertTransition(from: RuntimeState, to: RuntimeState): void;
 /**
- * Returns whether the runtime is in a terminal state.
+ * Returns whether the runtime is in a terminal state (`stopped`).
+ *
+ * `failed` is not terminal: call `stop()` to release it.
  */
 export declare function isTerminalState(state: RuntimeState): boolean;
 /**

package/dist/runtimeState/runtimeState.core.js

@@ -4,8 +4,12 @@ import { RuntimeStateError } from "../runtimeError/runtimeError.base.js";
  */
 export const RUNTIME_STATE_TRANSITIONS = Object.freeze({
     created: ["initializing", "stopped", "failed"],
-    initializing: ["initialized", "running", "failed"],
-    initialized: ["starting", "running", "failed"],
+    // Startup walks every state in order: modules initialize under
+    // "initializing", the runtime passes through "initialized", and modules'
+    // onReady hooks run under "starting". The shortcuts straight to
+    // "running" were never taken once the runtime entered these states.
+    initializing: ["initialized", "failed"],
+    initialized: ["starting", "failed"],
     starting: ["running", "failed"],
     running: ["stopping", "failed"],
     stopping: ["stopped", "failed"],
@@ -17,11 +21,16 @@ export const RUNTIME_STATE_TRANSITIONS = Object.freeze({
     failed: ["stopping", "stopped"],
 });
 /**
- * Terminal runtime states.
+ * Terminal runtime states: no further transition is possible.
+ *
+ * Only `stopped`. `failed` is NOT terminal: `stop()` is allowed from it
+ * (`failed -> stopping -> stopped`) so an operator can release whatever
+ * startup rollback did not reach. It used to be listed here, so
+ * `isTerminalState("failed")` claimed a state was final while `stop()`
+ * still moved out of it.
  */
 export const TERMINAL_STATES = Object.freeze([
     "stopped",
-    "failed",
 ]);
 /**
  * Runtime states from which startup is allowed.
@@ -59,7 +68,9 @@ export function assertTransition(from, to) {
     }
 }
 /**
- * Returns whether the runtime is in a terminal state.
+ * Returns whether the runtime is in a terminal state (`stopped`).
+ *
+ * `failed` is not terminal: call `stop()` to release it.
  */
 export function isTerminalState(state) {
     return TERMINAL_STATES.includes(state);

package/dist/shutdown/index.d.ts

@@ -2,4 +2,5 @@
  * Runtime shutdown sequence.
  */
 export { executeShutdown } from "./shutdown.core.js";
+export { CONTAINER_SHUTDOWN_ID } from "./shutdown.container.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/shutdown/index.js

@@ -2,4 +2,5 @@
  * Runtime shutdown sequence.
  */
 export { executeShutdown } from "./shutdown.core.js";
+export { CONTAINER_SHUTDOWN_ID } from "./shutdown.container.js";
 //# sourceMappingURL=index.js.map

package/dist/shutdown/shutdown.container.d.ts

@@ -0,0 +1,22 @@
+import type { Container } from "@zudojs/container";
+import type { Logger } from "@zudojs/logger";
+import type { LifecycleFailure } from "../lifecycle/lifecycle.type.js";
+/**
+ * The `moduleId` under which a container disposal failure is reported in
+ * `status.shutdownFailures`. Parenthesised so it cannot collide with a
+ * real module id.
+ */
+export declare const CONTAINER_SHUTDOWN_ID = "(container)";
+/**
+ * Disposes the runtime's container after its modules have shut down.
+ *
+ * Runs only when the runtime owns the container
+ * (`disposeContainerOnStop: true`, which `createTestRuntime` sets). A
+ * disposal failure does not fail the stop, matching module teardown
+ * failures: it is logged and returned so it lands in
+ * `status.shutdownFailures`.
+ *
+ * @returns The failure, or `undefined` when disposal succeeded.
+ */
+export declare function disposeRuntimeContainer(container: Container, logger: Logger): Promise<LifecycleFailure | undefined>;
+//# sourceMappingURL=shutdown.container.d.ts.map

package/dist/shutdown/shutdown.container.js

@@ -0,0 +1,37 @@
+/**
+ * The `moduleId` under which a container disposal failure is reported in
+ * `status.shutdownFailures`. Parenthesised so it cannot collide with a
+ * real module id.
+ */
+export const CONTAINER_SHUTDOWN_ID = "(container)";
+/**
+ * Disposes the runtime's container after its modules have shut down.
+ *
+ * Runs only when the runtime owns the container
+ * (`disposeContainerOnStop: true`, which `createTestRuntime` sets). A
+ * disposal failure does not fail the stop, matching module teardown
+ * failures: it is logged and returned so it lands in
+ * `status.shutdownFailures`.
+ *
+ * @returns The failure, or `undefined` when disposal succeeded.
+ */
+export async function disposeRuntimeContainer(container, logger) {
+    const startedAt = Date.now();
+    try {
+        await container.dispose();
+        return undefined;
+    }
+    catch (error) {
+        const failure = {
+            moduleId: CONTAINER_SHUTDOWN_ID,
+            phase: "destroy",
+            error: error instanceof Error ? error : new Error(String(error)),
+            durationMs: Date.now() - startedAt,
+        };
+        logger.error("Runtime container failed to dispose.", {
+            errorMessage: failure.error.message,
+        });
+        return failure;
+    }
+}
+//# sourceMappingURL=shutdown.container.js.map

package/dist/signalHandler/signalHandler.core.d.ts

@@ -28,6 +28,12 @@ export interface SignalHandlerOptions {
     readonly fatalExitTimeout?: number;
     /** Exit hook, injected for testing. Defaults to `process.exit`. */
     readonly exit?: (code: number) => void;
+    /**
+     * Exit-code hook, injected for testing. Defaults to setting
+     * `process.exitCode`. Called with `1` when a signal-triggered shutdown
+     * fails; a clean shutdown leaves the exit code alone.
+     */
+    readonly setExitCode?: (code: number) => void;
 }
 /**
  * Signal handler for process lifecycle events.
@@ -39,6 +45,7 @@ export declare class SignalHandler {
     private isShuttingDown;
     private registered;
     private forcedExitTimer;
+    private flushedPendingSignals;
     constructor(logger: Logger, options: SignalHandlerOptions);
     /**
      * Registers signal handlers.
@@ -60,6 +67,11 @@ export declare class SignalHandler {
     get shuttingDown(): boolean;
     private handleTermination;
     private handleInterruption;
+    /**
+     * Gives a signal delivered just before the loop drained one turn to be
+     * dispatched, once per registration so an idle process still exits.
+     */
+    private handleBeforeExit;
     /**
      * Handles uncaught exceptions.
      *
@@ -77,6 +89,9 @@ export declare class SignalHandler {
      *
      * A second termination signal exits immediately: an operator pressing
      * Ctrl-C again on a stuck shutdown is asking for exactly that.
+     *
+     * The event loop is held open until the shutdown settles, and a failed
+     * shutdown sets a non-zero exit code.
      */
     private initiateShutdown;
     private exit;

package/dist/signalHandler/signalHandler.core.js

@@ -1,3 +1,5 @@
+import { RuntimeSignalError } from "../runtimeError/runtimeError.base.js";
+import { flushPendingSignals, holdEventLoop, setProcessExitCode, } from "./signalHandler.keepAlive.js";
 /** Default grace period for a fatal-error shutdown. */
 const DEFAULT_FATAL_EXIT_TIMEOUT = 10_000;
 /**
@@ -10,6 +12,7 @@ export class SignalHandler {
     isShuttingDown = false;
     registered = false;
     forcedExitTimer = null;
+    flushedPendingSignals = false;
     constructor(logger, options) {
         this.logger = logger;
         this.options = options;
@@ -28,8 +31,10 @@ export class SignalHandler {
         this.registered = true;
         this.isShuttingDown = false;
         if (this.options.handleSignals) {
+            this.flushedPendingSignals = false;
             process.on("SIGTERM", this.handleTermination);
             process.on("SIGINT", this.handleInterruption);
+            process.on("beforeExit", this.handleBeforeExit);
         }
         if (this.options.handleFatalErrors) {
             process.on("uncaughtException", this.handleUncaughtException);
@@ -54,6 +59,7 @@ export class SignalHandler {
         if (this.options.handleSignals) {
             process.off("SIGTERM", this.handleTermination);
             process.off("SIGINT", this.handleInterruption);
+            process.off("beforeExit", this.handleBeforeExit);
         }
         if (this.options.handleFatalErrors) {
             process.off("uncaughtException", this.handleUncaughtException);
@@ -77,6 +83,16 @@ export class SignalHandler {
         this.logger.info("Received SIGINT signal.");
         this.initiateShutdown("SIGINT");
     };
+    /**
+     * Gives a signal delivered just before the loop drained one turn to be
+     * dispatched, once per registration so an idle process still exits.
+     */
+    handleBeforeExit = () => {
+        if (this.flushedPendingSignals || this.isShuttingDown)
+            return;
+        this.flushedPendingSignals = true;
+        flushPendingSignals();
+    };
     /**
      * Handles uncaught exceptions.
      *
@@ -131,6 +147,9 @@ export class SignalHandler {
      *
      * A second termination signal exits immediately: an operator pressing
      * Ctrl-C again on a stuck shutdown is asking for exactly that.
+     *
+     * The event loop is held open until the shutdown settles, and a failed
+     * shutdown sets a non-zero exit code.
      */
     initiateShutdown(source) {
         if (this.isShuttingDown) {
@@ -144,12 +163,19 @@ export class SignalHandler {
             return;
         }
         this.isShuttingDown = true;
-        if (this.shutdownHandler) {
-            return Promise.resolve(this.shutdownHandler()).catch((error) => {
+        const handler = this.shutdownHandler;
+        if (handler) {
+            const release = holdEventLoop();
+            return new Promise((resolve) => resolve(handler()))
+                .catch((error) => {
+                const signalError = new RuntimeSignalError(source, { cause: error });
                 this.logger.error("Shutdown handler failed.", {
-                    errorMessage: error instanceof Error ? error.message : String(error),
+                    errorMessage: signalError.message,
+                    error: signalError,
                 });
-            });
+                (this.options.setExitCode ?? setProcessExitCode)(1);
+            })
+                .finally(release);
         }
     }
     exit(code) {

package/dist/signalHandler/signalHandler.keepAlive.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Keeping the process alive while a signal-triggered shutdown runs.
+ *
+ * Node's signal listeners do not hold the event loop open. A SIGTERM
+ * handled while nothing else was keeping the loop alive — or whose
+ * shutdown closed the last open handle before an `onShutdown` hook had
+ * finished — let the process exit mid-shutdown with code 0, the runtime
+ * still `running` or `stopping`, and the remaining hooks never run.
+ *
+ * @module signalHandler/signalHandler.keepAlive
+ */
+/**
+ * Holds the event loop open until the returned release function is called.
+ *
+ * The handle is a ref'd interval that does nothing, so the process stays
+ * up exactly as long as the shutdown it guards.
+ */
+export declare function holdEventLoop(): () => void;
+/**
+ * Runs one more event-loop turn so a signal that was already delivered,
+ * but not yet dispatched, reaches its listener.
+ *
+ * A process that signals itself (`process.kill(process.pid, "SIGTERM")`)
+ * with nothing else keeping the loop alive otherwise exits without ever
+ * polling for the signal, so the listener never runs.
+ */
+export declare function flushPendingSignals(): void;
+/** Sets the exit code the process ends with once the loop drains. */
+export declare function setProcessExitCode(code: number): void;
+//# sourceMappingURL=signalHandler.keepAlive.d.ts.map

package/dist/signalHandler/signalHandler.keepAlive.js

@@ -0,0 +1,45 @@
+/**
+ * Keeping the process alive while a signal-triggered shutdown runs.
+ *
+ * Node's signal listeners do not hold the event loop open. A SIGTERM
+ * handled while nothing else was keeping the loop alive — or whose
+ * shutdown closed the last open handle before an `onShutdown` hook had
+ * finished — let the process exit mid-shutdown with code 0, the runtime
+ * still `running` or `stopping`, and the remaining hooks never run.
+ *
+ * @module signalHandler/signalHandler.keepAlive
+ */
+/** Longest delay a Node timer accepts; the timer never fires in practice. */
+const KEEP_ALIVE_INTERVAL = 2_147_483_647;
+/**
+ * Holds the event loop open until the returned release function is called.
+ *
+ * The handle is a ref'd interval that does nothing, so the process stays
+ * up exactly as long as the shutdown it guards.
+ */
+export function holdEventLoop() {
+    const handle = setInterval(() => undefined, KEEP_ALIVE_INTERVAL);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(handle);
+    };
+}
+/**
+ * Runs one more event-loop turn so a signal that was already delivered,
+ * but not yet dispatched, reaches its listener.
+ *
+ * A process that signals itself (`process.kill(process.pid, "SIGTERM")`)
+ * with nothing else keeping the loop alive otherwise exits without ever
+ * polling for the signal, so the listener never runs.
+ */
+export function flushPendingSignals() {
+    setImmediate(() => undefined);
+}
+/** Sets the exit code the process ends with once the loop drains. */
+export function setProcessExitCode(code) {
+    process.exitCode = code;
+}
+//# sourceMappingURL=signalHandler.keepAlive.js.map

package/dist/startup/startup.core.d.ts

@@ -4,8 +4,11 @@ import { LifecycleManager } from "../lifecycle/index.js";
 import type { LifecycleFailure } from "../lifecycle/lifecycle.type.js";
 /**
  * Executes the startup sequence.
+ *
+ * @param onInitialized - Called once every module has initialized and
+ *   before any `onReady` hook runs.
  */
-export declare function executeStartup(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, emitEvents: boolean, startupTimeout?: number): Promise<void>;
+export declare function executeStartup(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, emitEvents: boolean, startupTimeout?: number, onInitialized?: () => void): Promise<void>;
 /**
  * Rolls back a failed startup.
  */

package/dist/startup/startup.core.js

@@ -1,7 +1,7 @@
 import { createEvent } from "@zudojs/events";
 import { createFailureEventPayload, publishRuntimeEvent, } from "../runtimeEvents/index.js";
 import { LifecycleManager } from "../lifecycle/index.js";
-import { RuntimeStartError, RuntimeTimeoutError, } from "../runtimeError/index.js";
+import { RuntimeInitializationError, RuntimeStartError, RuntimeTimeoutError, } from "../runtimeError/index.js";
 /** Largest delay a timer can represent. */
 const MAX_TIMER_DELAY = 2_147_483_647;
 /**
@@ -40,14 +40,17 @@ async function withStartupTimeout(operation, timeoutMs, onTimeout) {
 }
 /**
  * Executes the startup sequence.
+ *
+ * @param onInitialized - Called once every module has initialized and
+ *   before any `onReady` hook runs.
  */
-export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emitEvents, startupTimeout = 0) {
-    return withStartupTimeout(runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents), startupTimeout, () => lifecycle.cancel());
+export async function executeStartup(lifecycle, runtimeId, eventBus, logger, emitEvents, startupTimeout = 0, onInitialized) {
+    return withStartupTimeout(runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents, onInitialized), startupTimeout, () => lifecycle.cancel());
 }
 /**
  * Runs the startup sequence.
  */
-async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
+async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents, onInitialized) {
     // 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();
@@ -62,8 +65,7 @@ async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
                 payload: createFailureEventPayload(runtimeId, "initialization_failed", failure.error, "initialize", failure.moduleId),
             }));
         }
-        throw new RuntimeStartError(`Module "${failure.moduleId}" failed during initialization.`, {
-            phase: "initialize",
+        throw new RuntimeInitializationError(`Module "${failure.moduleId}" failed during initialization.`, {
             failedModuleId: failure.moduleId,
             cause: failure.error,
         });
@@ -72,6 +74,10 @@ async function runStartup(lifecycle, runtimeId, eventBus, logger, emitEvents) {
         modules: initResult.succeeded,
         durationMs: initResult.durationMs,
     });
+    // Lets the runtime enter "initialized" and "starting" between the two
+    // phases, so onReady hooks observe "starting" rather than
+    // "initializing".
+    onInitialized?.();
     const startResult = await lifecycle.start();
     if (lifecycle.cancelled) {
         return;

package/dist/testRuntime/testRuntime.core.d.ts

@@ -10,6 +10,9 @@ import type { RuntimeOptions } from "../runtimeOptions/runtimeOptions.type.js";
 /**
  * Creates a test runtime with mock infrastructure.
  *
+ * The runtime owns the container it creates, so `stop()` disposes it
+ * (`disposeContainerOnStop: true`; pass `false` to keep it).
+ *
  * @param modules - Optional modules to register.
  * @param options - Optional runtime options overrides.
  * @returns A runtime instance ready for testing.

package/dist/testRuntime/testRuntime.core.js

@@ -11,6 +11,9 @@ import { DefaultRuntime } from "../runtime/runtime.core.js";
 /**
  * Creates a test runtime with mock infrastructure.
  *
+ * The runtime owns the container it creates, so `stop()` disposes it
+ * (`disposeContainerOnStop: true`; pass `false` to keep it).
+ *
  * @param modules - Optional modules to register.
  * @param options - Optional runtime options overrides.
  * @returns A runtime instance ready for testing.
@@ -38,6 +41,8 @@ export function createTestRuntime(modules = [], options = {}) {
         shutdownTimeout: 5000,
         startupTimeout: 10000,
         emitEvents: false,
+        // The test runtime created this container, so it owns and releases it.
+        disposeContainerOnStop: true,
         ...options,
     };
     return new DefaultRuntime(dependencies, runtimeOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/runtime",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Application lifecycle orchestrator with dependency ordering, rollback, signals, and readiness checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,17 +22,17 @@
     "!dist/.tsbuildinfo"
   ],
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "dependencies": {
-    "@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"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/container": "1.2.1",
+    "@zudojs/core": "1.2.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/events": "1.3.1",
+    "@zudojs/logger": "1.4.1"
   },
   "license": "MIT",
   "author": {
@@ -52,7 +52,7 @@
     "orchestrator",
     "services"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-runtime",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },