@zudojs/runtime 1.2.0 → 1.3.0

package/README.md

@@ -44,6 +44,86 @@ 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.
+
+```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 +184,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 +222,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.d.ts

@@ -50,6 +50,15 @@ export declare class LifecycleManager {
      * Initializes all modules in dependency order.
      */
     initialize(): Promise<LifecycleResult>;
+    /**
+     * Returns the first declared dependency of `moduleId` that is known to
+     * have failed or been skipped, or `undefined` when none has.
+     *
+     * Only direct dependencies are inspected: `blocked` already contains
+     * every module skipped by an earlier group, and groups are visited in
+     * dependency order, so the cascade is transitive.
+     */
+    private findBlockingDependency;
     /**
      * Initializes a single module, converting a throw into a failure.
      */

package/dist/lifecycle/lifecycle.core.js

@@ -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 }),
             });
         }
@@ -116,14 +115,44 @@ export class LifecycleManager {
         const groups = this.options.parallelInitialization
             ? depGraph.parallelGroups
             : depGraph.order.map((moduleId) => [moduleId]);
+        // Ids that must not have dependents initialized on top of them:
+        // modules whose own hook threw, plus modules already skipped for the
+        // same reason, so the skip cascades transitively. `continueOnFailure`
+        // used to consult only the failure COUNT, so a dependent of a broken
+        // module was initialized, readied, and reported as started — an API
+        // serving traffic against a database that never came up.
+        const blocked = new Set();
         for (const group of groups) {
             if (this.cancellation.isCancelled) {
                 break;
             }
-            const results = await Promise.all(group.map((moduleId) => this.initializeModule(moduleId)));
+            const runnable = [];
+            for (const moduleId of group) {
+                const blocker = this.findBlockingDependency(moduleId, blocked);
+                if (blocker === undefined) {
+                    runnable.push(moduleId);
+                    continue;
+                }
+                const failure = {
+                    moduleId,
+                    phase: "initialize",
+                    error: new RuntimeStartError(`Module "${moduleId}" was not initialized because its ` +
+                        `dependency "${blocker}" failed.`, { phase: "initialize", failedModuleId: blocker }),
+                    durationMs: 0,
+                };
+                failed.push(failure);
+                blocked.add(moduleId);
+                this.logger.error(`Module "${moduleId}" was skipped because its dependency "${blocker}" failed.`);
+                this.emitModuleEvent("runtime.module.failed", moduleId, "failed", {
+                    durationMs: 0,
+                    error: failure.error,
+                });
+            }
+            const results = await Promise.all(runnable.map((moduleId) => this.initializeModule(moduleId)));
             for (const result of results) {
                 if (result.failure) {
                     failed.push(result.failure);
+                    blocked.add(result.moduleId);
                 }
                 else if (!result.abandoned) {
                     succeeded.push(result.moduleId);
@@ -140,6 +169,18 @@ export class LifecycleManager {
             durationMs: Date.now() - startTime,
         });
     }
+    /**
+     * Returns the first declared dependency of `moduleId` that is known to
+     * have failed or been skipped, or `undefined` when none has.
+     *
+     * Only direct dependencies are inspected: `blocked` already contains
+     * every module skipped by an earlier group, and groups are visited in
+     * dependency order, so the cascade is transitive.
+     */
+    findBlockingDependency(moduleId, blocked) {
+        const dependencies = this.modules.get(moduleId)?.dependencies ?? [];
+        return dependencies.find((dependency) => blocked.has(dependency));
+    }
     /**
      * Initializes a single module, converting a throw into a failure.
      */

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

@@ -79,6 +79,14 @@ export interface LifecycleManagerOptions {
      * closing the same resources.
      */
     readonly shutdownTimeout?: number;
+    /**
+     * Keeps initializing and starting after a module fails.
+     *
+     * Only modules INDEPENDENT of the failure continue: a module that
+     * declares a failed (or already skipped) module in `dependencies` is
+     * never initialized or readied, and is reported in `failed` with the
+     * blocking dependency named. Defaults to false.
+     */
     readonly continueOnFailure?: boolean;
     /**
      * Receives one event per module per lifecycle phase.

package/dist/registry/registry.core.js

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

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

@@ -137,6 +137,16 @@ 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.
      */

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, RuntimeStateError, 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
@@ -285,27 +290,65 @@ export class DefaultRuntime {
             if (this.options.emitEvents) {
                 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.
@@ -318,18 +361,22 @@ export class DefaultRuntime {
         }
         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;
+            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 {

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

@@ -64,13 +64,15 @@ export type RuntimeModuleEventType = "runtime.module.initializing" | "runtime.mo
 /**
  * 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.core.js

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

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

@@ -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.js

@@ -1,3 +1,4 @@
+import { RuntimeSignalError } from "../runtimeError/runtimeError.base.js";
 /** Default grace period for a fatal-error shutdown. */
 const DEFAULT_FATAL_EXIT_TIMEOUT = 10_000;
 /**
@@ -146,8 +147,10 @@ export class SignalHandler {
         this.isShuttingDown = true;
         if (this.shutdownHandler) {
             return Promise.resolve(this.shutdownHandler()).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,
                 });
             });
         }

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.0",
+  "version": "1.3.0",
   "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.0",
-    "@zudojs/container": "1.1.1",
-    "@zudojs/core": "1.2.0",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/events": "1.1.0",
-    "@zudojs/logger": "1.2.0"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/container": "1.2.0",
+    "@zudojs/core": "1.2.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/events": "1.3.0",
+    "@zudojs/logger": "1.4.0"
   },
   "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"
   },