@zudojs/runtime 1.3.3 → 1.4.0

package/README.md

@@ -162,14 +162,27 @@ one on a running runtime moves it to `degraded` until it passes.
 
 ```typescript
 runtime.registerReadinessCheck("database", () => database.isConnected());
+runtime.registerReadinessCheck("cache", () => cache.isWarm(), { critical: false });
 
 await runtime.runReadinessChecks();
 
-runtime.ready; // false while any check fails
+runtime.ready; // false while any critical check fails
 runtime.health.state; // "healthy" | "degraded" | ...
-runtime.readiness.checks.get("database"); // per-check result and duration
+runtime.readiness.checks.get("database"); // per-check result, message and duration
+runtime.readiness.reason; // "Readiness checks failing: database."
 ```
 
+A check registered with `{ critical: false }` is evaluated and reported
+(health shows it as `degraded`) but never gates `ready`. A check that
+returns `false` carries the message `"Check returned false."`; one that
+throws or exceeds the timeout carries the error.
+
+Readiness is pinned at `false` in two situations regardless of the checks:
+while the runtime is `shutting_down` (entered by `stop()`, so a `/ready`
+probe that re-runs the checks during or after shutdown never reports
+ready again), and after a manual `tracker.markNotReady()`, which holds
+until `markReady()`.
+
 `runtime.health` is derived from the lifecycle state and the readiness
 checks: a running runtime is `healthy` when every check passes and
 `degraded` when any check fails; every other lifecycle state maps onto

package/dist/dependencyGraph/dependencyGraph.core.d.ts

@@ -21,4 +21,3 @@ export declare function resolveDependencies(modules: ReadonlyMap<string, readonl
  * does not exist.
  */
 export declare function validateDependencies(modules: ReadonlyMap<string, readonly string[]>): void;
-//# sourceMappingURL=dependencyGraph.core.d.ts.map

package/dist/dependencyGraph/dependencyGraph.core.js

@@ -122,4 +122,3 @@ export function validateDependencies(modules) {
         }
     }
 }
-//# sourceMappingURL=dependencyGraph.core.js.map

package/dist/dependencyGraph/dependencyGraph.type.d.ts

@@ -33,4 +33,3 @@ export interface CircularDependencyInfo {
     readonly moduleId: string;
     readonly dependencyId: string;
 }
-//# sourceMappingURL=dependencyGraph.type.d.ts.map

package/dist/dependencyGraph/dependencyGraph.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=dependencyGraph.type.js.map

package/dist/dependencyGraph/index.d.ts

@@ -3,4 +3,3 @@
  */
 export { buildDependencyGraph, resolveDependencies, validateDependencies, } from "./dependencyGraph.core.js";
 export type { DependencyNode, DependencyGraph, DependencyResolutionResult, CircularDependencyInfo, } from "./dependencyGraph.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/dependencyGraph/index.js

@@ -2,4 +2,3 @@
  * Module dependency graph and resolution.
  */
 export { buildDependencyGraph, resolveDependencies, validateDependencies, } from "./dependencyGraph.core.js";
-//# sourceMappingURL=index.js.map

package/dist/health/health.core.d.ts

@@ -9,4 +9,3 @@ import type { ReadinessTrackerState } from "../readiness/readiness.type.js";
  * directly onto a health state.
  */
 export declare function computeRuntimeHealth(state: RuntimeState, readiness: ReadinessTrackerState): RuntimeHealth;
-//# sourceMappingURL=health.core.d.ts.map

package/dist/health/health.core.js

@@ -52,4 +52,3 @@ export function computeRuntimeHealth(state, readiness) {
         timestamp: new Date(),
     });
 }
-//# sourceMappingURL=health.core.js.map

package/dist/health/index.d.ts

@@ -2,4 +2,3 @@
  * Runtime health computation.
  */
 export { computeRuntimeHealth } from "./health.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/health/index.js

@@ -2,4 +2,3 @@
  * Runtime health computation.
  */
 export { computeRuntimeHealth } from "./health.core.js";
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -25,4 +25,3 @@ export * from "./shutdown/index.js";
 export * from "./signalHandler/index.js";
 export * from "./runtimeError/index.js";
 export * from "./registry/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -27,4 +27,3 @@ export * from "./registry/index.js";
 // `testRuntime` is intentionally NOT exported from the package root: it
 // is a testing helper, and re-exporting it here put a test-only module
 // on the main entry point. Import it from "@zudojs/runtime/testing".
-//# sourceMappingURL=index.js.map

package/dist/lifecycle/index.d.ts

@@ -3,4 +3,3 @@
  */
 export { LifecycleManager } from "./lifecycle.core.js";
 export type { LifecyclePhase, LifecycleResult, LifecycleFailure, LifecycleContext, ManagedModule, LifecycleManagerOptions, ModuleContextServices, ModuleEventListener, } from "./lifecycle.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.js

@@ -2,4 +2,3 @@
  * Module lifecycle management.
  */
 export { LifecycleManager } from "./lifecycle.core.js";
-//# sourceMappingURL=index.js.map

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

@@ -38,4 +38,3 @@ export declare class LifecycleCancellation {
      */
     settle(): Promise<void>;
 }
-//# sourceMappingURL=lifecycle.cancellation.d.ts.map

package/dist/lifecycle/lifecycle.cancellation.js

@@ -89,4 +89,3 @@ async function releaseAbandonedModule(module, context, started, logger) {
         }
     }
 }
-//# sourceMappingURL=lifecycle.cancellation.js.map

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

@@ -102,4 +102,3 @@ export declare class LifecycleManager {
     getStartedModules(): readonly string[];
     private buildModuleDependencyGraph;
 }
-//# sourceMappingURL=lifecycle.core.d.ts.map

package/dist/lifecycle/lifecycle.core.js

@@ -555,4 +555,3 @@ export class LifecycleManager {
         return resolveDependencies(moduleDeps);
     }
 }
-//# sourceMappingURL=lifecycle.core.js.map

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

@@ -109,4 +109,3 @@ export interface LifecycleManagerOptions {
      */
     readonly parallelInitialization?: boolean;
 }
-//# sourceMappingURL=lifecycle.type.d.ts.map

package/dist/lifecycle/lifecycle.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=lifecycle.type.js.map

package/dist/readiness/index.d.ts

@@ -2,5 +2,4 @@
  * Runtime readiness tracking.
  */
 export { ReadinessTracker } from "./readiness.core.js";
-export type { ReadinessState, ReadinessCheck, ReadinessCheckFn, ReadinessTrackerState, ReadinessOptions, } from "./readiness.type.js";
-//# sourceMappingURL=index.d.ts.map
+export type { ReadinessState, ReadinessCheck, ReadinessCheckFn, ReadinessCheckOptions, ReadinessInitialCheck, ReadinessTrackerState, ReadinessOptions, } from "./readiness.type.js";

package/dist/readiness/index.js

@@ -2,4 +2,3 @@
  * Runtime readiness tracking.
  */
 export { ReadinessTracker } from "./readiness.core.js";
-//# sourceMappingURL=index.js.map

package/dist/readiness/readiness.check.d.ts

@@ -0,0 +1,26 @@
+import type { ReadinessCheck, ReadinessCheckFn } from "./readiness.type.js";
+/**
+ * How long a single readiness check may run before it counts as failed.
+ *
+ * Without a bound, one hanging probe hangs the readiness endpoint
+ * indefinitely — a health check that never answers is worse than one
+ * that answers "unhealthy".
+ */
+export declare const DEFAULT_CHECK_TIMEOUT = 5000;
+/**
+ * Runs a check under a timeout, clearing the timer either way.
+ *
+ * The timer is deliberately NOT `unref`'d. It is cleared as soon as the
+ * check settles, so it never outlives a healthy check; while a check
+ * hangs it is the only thing guaranteeing an answer. Unref'd, a short
+ * script that awaited `runChecks()` on a hanging check exited with
+ * "unsettled top-level await" (code 13) instead of recording a timeout.
+ */
+export declare function runCheckWithTimeout(name: string, fn: ReadinessCheckFn, timeoutMs: number): Promise<boolean>;
+/**
+ * Evaluates one check and produces the result to record for it.
+ *
+ * A check that returns `false` used to be recorded with no message at
+ * all, indistinguishable from one that was never run.
+ */
+export declare function evaluateReadinessCheck(name: string, fn: ReadinessCheckFn, timeoutMs: number, critical: boolean): Promise<ReadinessCheck>;

package/dist/readiness/readiness.check.js

@@ -0,0 +1,70 @@
+/**
+ * How long a single readiness check may run before it counts as failed.
+ *
+ * Without a bound, one hanging probe hangs the readiness endpoint
+ * indefinitely — a health check that never answers is worse than one
+ * that answers "unhealthy".
+ */
+export const DEFAULT_CHECK_TIMEOUT = 5_000;
+/**
+ * Runs a check under a timeout, clearing the timer either way.
+ *
+ * The timer is deliberately NOT `unref`'d. It is cleared as soon as the
+ * check settles, so it never outlives a healthy check; while a check
+ * hangs it is the only thing guaranteeing an answer. Unref'd, a short
+ * script that awaited `runChecks()` on a hanging check exited with
+ * "unsettled top-level await" (code 13) instead of recording a timeout.
+ */
+export async function runCheckWithTimeout(name, fn, timeoutMs) {
+    if (timeoutMs <= 0) {
+        return fn();
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve(fn()),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`Readiness check "${name}" did not settle within ${timeoutMs}ms.`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Evaluates one check and produces the result to record for it.
+ *
+ * A check that returns `false` used to be recorded with no message at
+ * all, indistinguishable from one that was never run.
+ */
+export async function evaluateReadinessCheck(name, fn, timeoutMs, critical) {
+    const startedAt = Date.now();
+    try {
+        const ready = await runCheckWithTimeout(name, fn, timeoutMs);
+        return {
+            name,
+            ready,
+            critical,
+            lastCheckedAt: new Date(),
+            durationMs: Date.now() - startedAt,
+            ...(ready ? {} : { message: "Check returned false." }),
+        };
+    }
+    catch (error) {
+        return {
+            name,
+            ready: false,
+            critical,
+            lastCheckedAt: new Date(),
+            durationMs: Date.now() - startedAt,
+            message: error instanceof Error
+                ? `Check threw an error: ${error.message}`
+                : "Check threw an error",
+        };
+    }
+}

package/dist/readiness/readiness.core.d.ts

@@ -1,6 +1,12 @@
-import type { ReadinessState, ReadinessCheckFn, ReadinessTrackerState, ReadinessOptions } from "./readiness.type.js";
+import type { ReadinessState, ReadinessCheckFn, ReadinessCheckOptions, ReadinessTrackerState, ReadinessOptions } from "./readiness.type.js";
 /**
  * Tracks runtime readiness state.
+ *
+ * Two things pin readiness at `false` regardless of what the checks
+ * say: the `shutting_down` state (entered by the runtime in `stop()`)
+ * and a manual `markNotReady()`, which holds until `markReady()`.
+ * Before, the next `runChecks()` — a `/ready` probe, typically —
+ * overwrote both and sent traffic to an instance that was going away.
  */
 export declare class ReadinessTracker {
     private state;
@@ -9,6 +15,7 @@ export declare class ReadinessTracker {
     private readonly autoMarkReady;
     private readonly checkTimeout;
     private ready;
+    private held;
     private reason?;
     private running;
     constructor(options?: ReadinessOptions);
@@ -17,9 +24,11 @@ export declare class ReadinessTracker {
      *
      * The check function is retained so it can be re-evaluated later by
      * `updateCheck(name)` or `runChecks()`. Registration does not run the
-     * check: it starts out not-ready until it is first evaluated.
+     * check: it starts out not-ready until it is first evaluated. Pass
+     * `{ critical: false }` for a check that should be reported but must
+     * not gate readiness.
      */
-    registerCheck(name: string, check: ReadinessCheckFn): void;
+    registerCheck(name: string, check: ReadinessCheckFn, options?: ReadinessCheckOptions): void;
     /**
      * Removes a readiness check.
      *
@@ -42,19 +51,13 @@ export declare class ReadinessTracker {
      */
     hasChecks(): boolean;
     /**
-     * Runs a single check and records its result and duration.
-     */
-    private evaluateCheck;
-    /**
-     * Runs a check under a timeout, clearing the timer either way.
-     */
-    private withCheckTimeout;
-    /**
-     * Marks the runtime as ready.
+     * Marks the runtime as ready and releases a `markNotReady()` hold.
+     * Ignored while `shutting_down`; leave that state with `setState()`.
      */
     markReady(reason?: string): void;
     /**
-     * Marks the runtime as not ready.
+     * Marks the runtime as not ready and holds it there: automatic
+     * evaluation will not report ready again until `markReady()`.
      */
     markNotReady(reason?: string): void;
     /**
@@ -69,9 +72,11 @@ export declare class ReadinessTracker {
      * Returns the current readiness state.
      */
     getState(): ReadinessTrackerState;
+    private evaluate;
+    private becomeNotReady;
     /**
-     * Evaluates overall readiness based on registered checks.
+     * Evaluates overall readiness from the critical checks. Never acts
+     * while shutting down or under a manual hold.
      */
     private evaluateReadiness;
 }
-//# sourceMappingURL=readiness.core.d.ts.map

package/dist/readiness/readiness.core.js

@@ -1,14 +1,13 @@
+import { DEFAULT_CHECK_TIMEOUT, evaluateReadinessCheck, } from "./readiness.check.js";
 import { RuntimeStateError } from "../runtimeError/index.js";
-/**
- * How long a single readiness check may run before it counts as failed.
- *
- * Without a bound, one hanging probe hangs the readiness endpoint
- * indefinitely — a health check that never answers is worse than one
- * that answers "unhealthy".
- */
-const DEFAULT_CHECK_TIMEOUT = 5_000;
 /**
  * Tracks runtime readiness state.
+ *
+ * Two things pin readiness at `false` regardless of what the checks
+ * say: the `shutting_down` state (entered by the runtime in `stop()`)
+ * and a manual `markNotReady()`, which holds until `markReady()`.
+ * Before, the next `runChecks()` — a `/ready` probe, typically —
+ * overwrote both and sent traffic to an instance that was going away.
  */
 export class ReadinessTracker {
     state = "not_ready";
@@ -17,15 +16,14 @@ export class ReadinessTracker {
     autoMarkReady;
     checkTimeout;
     ready = false;
+    held = false;
     reason;
     running;
     constructor(options = {}) {
         this.autoMarkReady = options.autoMarkReady ?? true;
         this.checkTimeout = options.checkTimeout ?? DEFAULT_CHECK_TIMEOUT;
-        if (options.initialChecks) {
-            for (const check of options.initialChecks) {
-                this.registerCheck(check.name, check.check);
-            }
+        for (const check of options.initialChecks ?? []) {
+            this.registerCheck(check.name, check.check, { critical: check.critical });
         }
     }
     /**
@@ -33,13 +31,16 @@ export class ReadinessTracker {
      *
      * The check function is retained so it can be re-evaluated later by
      * `updateCheck(name)` or `runChecks()`. Registration does not run the
-     * check: it starts out not-ready until it is first evaluated.
+     * check: it starts out not-ready until it is first evaluated. Pass
+     * `{ critical: false }` for a check that should be reported but must
+     * not gate readiness.
      */
-    registerCheck(name, check) {
+    registerCheck(name, check, options = {}) {
         this.checkFns.set(name, check);
         this.checks.set(name, {
             name,
             ready: false,
+            critical: options.critical ?? true,
             lastCheckedAt: new Date(),
             durationMs: 0,
         });
@@ -58,7 +59,8 @@ export class ReadinessTracker {
         }
         if (this.autoMarkReady &&
             this.checks.size === 0 &&
-            this.state === "degraded") {
+            this.state === "degraded" &&
+            !this.held) {
             // `degraded` is only ever entered from `ready` because a check
             // failed. Removing the last check leaves nothing failing, so the
             // tracker returns to ready — otherwise `evaluateReadiness()` (which
@@ -85,7 +87,7 @@ export class ReadinessTracker {
         if (fn === undefined) {
             throw new RuntimeStateError(`Readiness check "${name}" is not registered.`);
         }
-        await this.evaluateCheck(name, fn);
+        await this.evaluate(name, fn);
         this.evaluateReadiness();
     }
     /**
@@ -99,7 +101,7 @@ export class ReadinessTracker {
         }
         this.running = (async () => {
             try {
-                await Promise.all([...this.checkFns].map(([name, fn]) => this.evaluateCheck(name, fn)));
+                await Promise.all([...this.checkFns].map(([name, fn]) => this.evaluate(name, fn)));
                 this.evaluateReadiness();
             }
             finally {
@@ -115,73 +117,24 @@ export class ReadinessTracker {
         return this.checkFns.size > 0;
     }
     /**
-     * Runs a single check and records its result and duration.
-     */
-    async evaluateCheck(name, fn) {
-        const startedAt = Date.now();
-        try {
-            const result = await this.withCheckTimeout(name, fn);
-            this.checks.set(name, {
-                name,
-                ready: result,
-                lastCheckedAt: new Date(),
-                durationMs: Date.now() - startedAt,
-            });
-        }
-        catch (error) {
-            this.checks.set(name, {
-                name,
-                ready: false,
-                lastCheckedAt: new Date(),
-                durationMs: Date.now() - startedAt,
-                message: error instanceof Error
-                    ? `Check threw an error: ${error.message}`
-                    : "Check threw an error",
-            });
-        }
-    }
-    /**
-     * Runs a check under a timeout, clearing the timer either way.
-     */
-    async withCheckTimeout(name, fn) {
-        if (this.checkTimeout <= 0) {
-            return fn();
-        }
-        let timer;
-        try {
-            return await Promise.race([
-                Promise.resolve(fn()),
-                new Promise((_, reject) => {
-                    timer = setTimeout(() => {
-                        reject(new Error(`Readiness check "${name}" did not settle within ${this.checkTimeout}ms.`));
-                    }, this.checkTimeout);
-                    timer.unref?.();
-                }),
-            ]);
-        }
-        finally {
-            if (timer !== undefined) {
-                clearTimeout(timer);
-            }
-        }
-    }
-    /**
-     * Marks the runtime as ready.
+     * Marks the runtime as ready and releases a `markNotReady()` hold.
+     * Ignored while `shutting_down`; leave that state with `setState()`.
      */
     markReady(reason) {
+        if (this.state === "shutting_down")
+            return;
+        this.held = false;
         this.state = "ready";
         this.ready = true;
         this.reason = reason;
     }
     /**
-     * Marks the runtime as not ready.
+     * Marks the runtime as not ready and holds it there: automatic
+     * evaluation will not report ready again until `markReady()`.
      */
     markNotReady(reason) {
-        this.ready = false;
-        this.reason = reason;
-        if (this.state === "ready") {
-            this.state = "degraded";
-        }
+        this.held = true;
+        this.becomeNotReady(reason);
     }
     /**
      * Updates the readiness state.
@@ -190,6 +143,7 @@ export class ReadinessTracker {
         this.state = state;
         if (state === "ready") {
             this.ready = true;
+            this.held = false;
         }
         else if (state === "not_ready" || state === "shutting_down") {
             this.ready = false;
@@ -213,19 +167,34 @@ export class ReadinessTracker {
             reason: this.reason,
         });
     }
+    async evaluate(name, fn) {
+        const critical = this.checks.get(name)?.critical ?? true;
+        this.checks.set(name, await evaluateReadinessCheck(name, fn, this.checkTimeout, critical));
+    }
+    becomeNotReady(reason) {
+        this.ready = false;
+        this.reason = reason;
+        if (this.state === "ready") {
+            this.state = "degraded";
+        }
+    }
     /**
-     * Evaluates overall readiness based on registered checks.
+     * Evaluates overall readiness from the critical checks. Never acts
+     * while shutting down or under a manual hold.
      */
     evaluateReadiness() {
-        if (this.autoMarkReady && this.checks.size > 0) {
-            const allReady = [...this.checks.values()].every((check) => check.ready);
-            if (allReady && !this.ready) {
-                this.markReady("All readiness checks passed.");
-            }
-            else if (!allReady && this.ready) {
-                this.markNotReady("One or more readiness checks failed.");
-            }
+        if (!this.autoMarkReady || this.checks.size === 0)
+            return;
+        if (this.state === "shutting_down" || this.held)
+            return;
+        const failing = [...this.checks.values()]
+            .filter((check) => check.critical && !check.ready)
+            .map((check) => check.name);
+        if (failing.length > 0) {
+            this.becomeNotReady(`Readiness checks failing: ${failing.join(", ")}.`);
+        }
+        else if (!this.ready) {
+            this.markReady("All readiness checks passed.");
         }
     }
 }
-//# sourceMappingURL=readiness.core.js.map

package/dist/readiness/readiness.type.d.ts

@@ -1,5 +1,9 @@
 /**
  * Readiness state of the runtime.
+ *
+ * `shutting_down` is sticky: once entered (the runtime does so in
+ * `stop()`), automatic evaluation and `markReady()` never report ready
+ * again; only `setState()` leaves it.
  */
 export type ReadinessState = "not_ready" | "initializing" | "ready" | "degraded" | "shutting_down";
 /**
@@ -8,6 +12,10 @@ export type ReadinessState = "not_ready" | "initializing" | "ready" | "degraded"
 export interface ReadinessCheck {
     readonly name: string;
     readonly ready: boolean;
+    /**
+     * Why the check is not ready: the error it threw, the timeout it hit,
+     * or `"Check returned false."`. Absent while it passes.
+     */
     readonly message?: string;
     readonly lastCheckedAt: Date;
     /**
@@ -15,11 +23,25 @@ export interface ReadinessCheck {
      * `0` for a check that has been registered but not yet run.
      */
     readonly durationMs: number;
+    /**
+     * Whether a failure of this check makes the runtime not ready.
+     *
+     * A non-critical check is still evaluated and reported — health shows
+     * it as `degraded` — but never gates `ready`. Defaults to true.
+     */
+    readonly critical: boolean;
 }
 /**
  * A readiness check function.
  */
 export type ReadinessCheckFn = () => boolean | Promise<boolean>;
+/**
+ * Options for a single readiness check.
+ */
+export interface ReadinessCheckOptions {
+    /** See {@link ReadinessCheck.critical}. Defaults to true. */
+    readonly critical?: boolean;
+}
 /**
  * Readiness tracker state.
  */
@@ -29,6 +51,13 @@ export interface ReadinessTrackerState {
     readonly ready: boolean;
     readonly reason?: string;
 }
+/**
+ * A check registered through {@link ReadinessOptions.initialChecks}.
+ */
+export interface ReadinessInitialCheck extends ReadinessCheckOptions {
+    readonly name: string;
+    readonly check: ReadinessCheckFn;
+}
 /**
  * Options for readiness tracking.
  */
@@ -36,10 +65,7 @@ export interface ReadinessOptions {
     /**
      * Initial readiness checks to register.
      */
-    readonly initialChecks?: ReadonlyArray<{
-        readonly name: string;
-        readonly check: ReadinessCheckFn;
-    }>;
+    readonly initialChecks?: ReadonlyArray<ReadinessInitialCheck>;
     /**
      * Whether to automatically mark as ready when all checks pass.
      * @default true
@@ -51,4 +77,3 @@ export interface ReadinessOptions {
      */
     readonly checkTimeout?: number;
 }
-//# sourceMappingURL=readiness.type.d.ts.map

package/dist/readiness/readiness.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=readiness.type.js.map

package/dist/registry/index.d.ts

@@ -2,4 +2,3 @@
  * @zudojs/runtime — Registry Barrel
  */
 export { RuntimeRegistry } from "./registry.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.js

@@ -2,4 +2,3 @@
  * @zudojs/runtime — Registry Barrel
  */
 export { RuntimeRegistry } from "./registry.core.js";
-//# sourceMappingURL=index.js.map

package/dist/registry/registry.core.d.ts

@@ -84,4 +84,3 @@ export declare class RuntimeRegistry {
      */
     clear(): void;
 }
-//# sourceMappingURL=registry.core.d.ts.map

package/dist/registry/registry.core.js

@@ -163,4 +163,3 @@ export class RuntimeRegistry {
         this.runtimes.clear();
     }
 }
-//# sourceMappingURL=registry.core.js.map

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

@@ -5,7 +5,7 @@ import type { ConfigurationManager, Module, ModuleContext } from "@zudojs/core";
 import type { RuntimeState, RuntimeStatus, RuntimeHealth } from "../runtimeState/index.js";
 import type { RuntimeOptions } from "../runtimeOptions/index.js";
 import type { RuntimeContext } from "../runtimeContext/index.js";
-import type { ReadinessCheckFn, ReadinessTrackerState } from "../readiness/index.js";
+import type { ReadinessCheckFn, ReadinessCheckOptions, ReadinessTrackerState } from "../readiness/index.js";
 /**
  * Zudojs runtime interface.
  *
@@ -25,9 +25,11 @@ export interface Runtime {
      *
      * A registered check starts out failing until it is first evaluated by
      * `runReadinessChecks`, so registering one on a running runtime moves it
-     * to `degraded` until the check passes.
+     * to `degraded` until the check passes. Pass `{ critical: false }` for
+     * a check that is reported (and shows in `health`) but must not gate
+     * `ready`.
      */
-    registerReadinessCheck(name: string, check: ReadinessCheckFn): void;
+    registerReadinessCheck(name: string, check: ReadinessCheckFn, options?: ReadinessCheckOptions): void;
     /**
      * Removes a readiness check. Returns whether one was registered.
      */
@@ -104,7 +106,7 @@ export declare class DefaultRuntime implements Runtime {
     /**
      * Registers a readiness check.
      */
-    registerReadinessCheck(name: string, check: ReadinessCheckFn): void;
+    registerReadinessCheck(name: string, check: ReadinessCheckFn, options?: ReadinessCheckOptions): void;
     /**
      * Removes a readiness check.
      */
@@ -178,4 +180,3 @@ export declare class DefaultRuntime implements Runtime {
  * Creates a runtime instance.
  */
 export declare function createRuntime(dependencies: RuntimeDependencies, options: RuntimeOptions): Runtime;
-//# sourceMappingURL=runtime.core.d.ts.map

package/dist/runtime/runtime.core.js

@@ -133,9 +133,9 @@ export class DefaultRuntime {
     /**
      * Registers a readiness check.
      */
-    registerReadinessCheck(name, check) {
+    registerReadinessCheck(name, check, options) {
         const previousHealth = this.health.state;
-        this.readinessTracker.registerCheck(name, check);
+        this.readinessTracker.registerCheck(name, check, options);
         this.emitHealthChange(previousHealth);
     }
     /**
@@ -487,4 +487,3 @@ export class DefaultRuntime {
 export function createRuntime(dependencies, options) {
     return new DefaultRuntime(dependencies, options);
 }
-//# sourceMappingURL=runtime.core.js.map

package/dist/runtimeContext/index.d.ts

@@ -4,4 +4,3 @@
 export { createRuntimeContext, withRuntimeContextState, } from "./runtimeContext.core.js";
 export { createRuntimeId, createCorrelationId, createRequestId, } from "./runtimeContext.factory.js";
 export type { RuntimeContext, RuntimeContextDependencies, RuntimeContextState, } from "./runtimeContext.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/runtimeContext/index.js

@@ -3,4 +3,3 @@
  */
 export { createRuntimeContext, withRuntimeContextState, } from "./runtimeContext.core.js";
 export { createRuntimeId, createCorrelationId, createRequestId, } from "./runtimeContext.factory.js";
-//# sourceMappingURL=index.js.map

package/dist/runtimeContext/runtimeContext.core.d.ts

@@ -17,4 +17,3 @@ export declare function createRuntimeContext(dependencies: RuntimeContextDepende
  * a clean runtime on the failure path.
  */
 export declare function withRuntimeContextState(base: RuntimeContext, state: RuntimeContextState): RuntimeContext;
-//# sourceMappingURL=runtimeContext.core.d.ts.map

package/dist/runtimeContext/runtimeContext.core.js

@@ -49,4 +49,3 @@ export function withRuntimeContextState(base, state) {
         ...(state.error !== undefined && { error: state.error }),
     });
 }
-//# sourceMappingURL=runtimeContext.core.js.map

package/dist/runtimeContext/runtimeContext.factory.d.ts

@@ -11,4 +11,3 @@ export declare function createCorrelationId(): string;
  * Generates a request ID.
  */
 export declare function createRequestId(): string;
-//# sourceMappingURL=runtimeContext.factory.d.ts.map

package/dist/runtimeContext/runtimeContext.factory.js

@@ -17,4 +17,3 @@ export function createCorrelationId() {
 export function createRequestId() {
     return `req_${randomUUID().replace(/-/g, "")}`;
 }
-//# sourceMappingURL=runtimeContext.factory.js.map

package/dist/runtimeContext/runtimeContext.type.d.ts

@@ -55,4 +55,3 @@ export interface RuntimeContextState {
     failedAt?: Date;
     error?: RuntimeError;
 }
-//# sourceMappingURL=runtimeContext.type.d.ts.map

package/dist/runtimeContext/runtimeContext.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=runtimeContext.type.js.map

package/dist/runtimeError/index.d.ts

@@ -2,4 +2,3 @@
  * Runtime error types.
  */
 export { RuntimeStateError, RuntimeStartError, RuntimeStopError, RuntimeInitializationError, RuntimeTimeoutError, RuntimeRollbackError, RuntimeCircularDependencyError, RuntimeDependencyError, RuntimeSignalError, toRuntimeError, } from "./runtimeError.base.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/runtimeError/index.js

@@ -2,4 +2,3 @@
  * Runtime error types.
  */
 export { RuntimeStateError, RuntimeStartError, RuntimeStopError, RuntimeInitializationError, RuntimeTimeoutError, RuntimeRollbackError, RuntimeCircularDependencyError, RuntimeDependencyError, RuntimeSignalError, toRuntimeError, } from "./runtimeError.base.js";
-//# sourceMappingURL=index.js.map

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

@@ -99,4 +99,3 @@ export declare class RuntimeSignalError extends RuntimeError {
  * Converts an unknown error to a RuntimeError.
  */
 export declare function toRuntimeError(error: unknown, phase?: string): RuntimeError;
-//# sourceMappingURL=runtimeError.base.d.ts.map

package/dist/runtimeError/runtimeError.base.js

@@ -178,4 +178,3 @@ export function toRuntimeError(error, phase = "unknown") {
         metadata: { phase },
     });
 }
-//# sourceMappingURL=runtimeError.base.js.map

package/dist/runtimeEvents/index.d.ts

@@ -3,4 +3,3 @@
  */
 export { publishRuntimeEvent, createRuntimeEventPayload, createModuleEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, } from "./runtimeEvents.core.js";
 export type { RuntimeEventType, RuntimeModuleEventType, RuntimeEventPayload, RuntimeModuleEventPayload, RuntimeFailureEventPayload, RuntimeHealthEventPayload, RuntimeReadinessEventPayload, RuntimeEventMap, } from "./runtimeEvents.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/runtimeEvents/index.js

@@ -2,4 +2,3 @@
  * Runtime lifecycle events.
  */
 export { publishRuntimeEvent, createRuntimeEventPayload, createModuleEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, } from "./runtimeEvents.core.js";
-//# sourceMappingURL=index.js.map

package/dist/runtimeEvents/runtimeEvents.core.d.ts

@@ -39,4 +39,3 @@ export declare function publishRuntimeEvent(eventBus: {
 }, logger: {
     warn(message: string, context?: Record<string, unknown>): void;
 }, event: Event): void;
-//# sourceMappingURL=runtimeEvents.core.d.ts.map

package/dist/runtimeEvents/runtimeEvents.core.js

@@ -86,4 +86,3 @@ export function publishRuntimeEvent(eventBus, logger, event) {
         });
     });
 }
-//# sourceMappingURL=runtimeEvents.core.js.map

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

@@ -90,4 +90,3 @@ export interface RuntimeEventMap {
     "runtime.health.changed": RuntimeHealthEventPayload;
     "runtime.readiness.changed": RuntimeReadinessEventPayload;
 }
-//# sourceMappingURL=runtimeEvents.type.d.ts.map

package/dist/runtimeEvents/runtimeEvents.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=runtimeEvents.type.js.map

package/dist/runtimeOptions/index.d.ts

@@ -4,4 +4,3 @@
 export { resolveRuntimeOptions, validateRuntimeOptions, createRuntimeOptions, } from "./runtimeOptions.core.js";
 export { DEFAULT_RUNTIME_OPTIONS } from "./runtimeOptions.type.js";
 export type { RuntimeOptions, ResolvedRuntimeOptions, } from "./runtimeOptions.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/runtimeOptions/index.js

@@ -3,4 +3,3 @@
  */
 export { resolveRuntimeOptions, validateRuntimeOptions, createRuntimeOptions, } from "./runtimeOptions.core.js";
 export { DEFAULT_RUNTIME_OPTIONS } from "./runtimeOptions.type.js";
-//# sourceMappingURL=index.js.map

package/dist/runtimeOptions/runtimeOptions.core.d.ts

@@ -16,4 +16,3 @@ export declare function validateRuntimeOptions(options: ResolvedRuntimeOptions):
  * Creates a runtime options object with all defaults applied.
  */
 export declare function createRuntimeOptions(options: ResolvedRuntimeOptions): ResolvedRuntimeOptions;
-//# sourceMappingURL=runtimeOptions.core.d.ts.map

package/dist/runtimeOptions/runtimeOptions.core.js

@@ -69,4 +69,3 @@ export function createRuntimeOptions(options) {
     validateRuntimeOptions(resolved);
     return resolved;
 }
-//# sourceMappingURL=runtimeOptions.core.js.map

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

@@ -160,4 +160,3 @@ export declare const DEFAULT_RUNTIME_OPTIONS: Readonly<{
     readonly applicationVersion: "0.1.0";
     readonly metadata: Readonly<{}>;
 }>;
-//# sourceMappingURL=runtimeOptions.type.d.ts.map

package/dist/runtimeOptions/runtimeOptions.type.js

@@ -21,4 +21,3 @@ export const DEFAULT_RUNTIME_OPTIONS = Object.freeze({
     // runtime never had.
     metadata: Object.freeze({}),
 });
-//# sourceMappingURL=runtimeOptions.type.js.map

package/dist/runtimeState/index.d.ts

@@ -3,4 +3,3 @@
  */
 export { RUNTIME_STATE_TRANSITIONS, TERMINAL_STATES, STARTABLE_STATES, STOPPABLE_STATES, canTransition, assertTransition, isTerminalState, canStart, canStop, isRunning, hasFailed, createStatus, } from "./runtimeState.core.js";
 export type { RuntimeState, RuntimeFailureState, RuntimeId, RuntimeStatus, RuntimeShutdownFailure, RuntimeHealthState, RuntimeHealth, RuntimeHealthCheck, } from "./runtimeState.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/runtimeState/index.js

@@ -2,4 +2,3 @@
  * Runtime state types and state machine.
  */
 export { RUNTIME_STATE_TRANSITIONS, TERMINAL_STATES, STARTABLE_STATES, STOPPABLE_STATES, canTransition, assertTransition, isTerminalState, canStart, canStop, isRunning, hasFailed, createStatus, } from "./runtimeState.core.js";
-//# sourceMappingURL=index.js.map

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

@@ -59,4 +59,3 @@ export declare function hasFailed(state: RuntimeState): boolean;
  * Creates a runtime status snapshot.
  */
 export declare function createStatus(state: RuntimeState): RuntimeStatus;
-//# sourceMappingURL=runtimeState.core.d.ts.map

package/dist/runtimeState/runtimeState.core.js

@@ -109,4 +109,3 @@ export function createStatus(state) {
         running: state === "running",
     });
 }
-//# sourceMappingURL=runtimeState.core.js.map

package/dist/runtimeState/runtimeState.type.d.ts

@@ -65,4 +65,3 @@ export interface RuntimeHealthCheck {
     readonly message?: string;
     readonly durationMs: number;
 }
-//# sourceMappingURL=runtimeState.type.d.ts.map

package/dist/runtimeState/runtimeState.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=runtimeState.type.js.map

package/dist/shutdown/index.d.ts

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

package/dist/shutdown/index.js

@@ -3,4 +3,3 @@
  */
 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

@@ -19,4 +19,3 @@ export declare const CONTAINER_SHUTDOWN_ID = "(container)";
  * @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

@@ -34,4 +34,3 @@ export async function disposeRuntimeContainer(container, logger) {
         return failure;
     }
 }
-//# sourceMappingURL=shutdown.container.js.map

package/dist/shutdown/shutdown.core.d.ts

@@ -24,4 +24,3 @@ export interface ShutdownResult {
  * identical to one that shut down cleanly.
  */
 export declare function executeShutdown(lifecycle: LifecycleManager, runtimeId: string, eventBus: EventBus | undefined, logger: Logger, shutdownTimeout: number, emitEvents: boolean): Promise<ShutdownResult>;
-//# sourceMappingURL=shutdown.core.d.ts.map

package/dist/shutdown/shutdown.core.js

@@ -50,11 +50,15 @@ export async function executeShutdown(lifecycle, runtimeId, eventBus, logger, sh
     // handler now so its eventual rejection is never unhandled.
     stopPromise.catch(() => { });
     let timer;
+    // Not unref'd: the timer is cleared as soon as the race settles, and
+    // while a module's onShutdown hangs it is the only thing that will
+    // ever settle it. Unref'd, a script that awaited stop() with nothing
+    // else on the loop exited (code 13, "unsettled top-level await")
+    // instead of reporting the RuntimeTimeoutError.
     const timeoutPromise = new Promise((_, reject) => {
         timer = setTimeout(() => {
             reject(new RuntimeTimeoutError("shutdown", shutdownTimeout));
         }, Math.min(Math.max(0, shutdownTimeout), MAX_TIMER_DELAY));
-        timer.unref?.();
     });
     try {
         const failures = await Promise.race([stopPromise, timeoutPromise]);
@@ -131,4 +135,3 @@ async function performShutdown(lifecycle, logger) {
     });
     return failures;
 }
-//# sourceMappingURL=shutdown.core.js.map

package/dist/signalHandler/index.d.ts

@@ -2,4 +2,3 @@
  * Process signal handling.
  */
 export { SignalHandler } from "./signalHandler.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/signalHandler/index.js

@@ -2,4 +2,3 @@
  * Process signal handling.
  */
 export { SignalHandler } from "./signalHandler.core.js";
-//# sourceMappingURL=index.js.map

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

@@ -96,4 +96,3 @@ export declare class SignalHandler {
     private initiateShutdown;
     private exit;
 }
-//# sourceMappingURL=signalHandler.core.d.ts.map

package/dist/signalHandler/signalHandler.core.js

@@ -183,4 +183,3 @@ export class SignalHandler {
         exit(code);
     }
 }
-//# sourceMappingURL=signalHandler.core.js.map

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

@@ -27,4 +27,3 @@ export declare function holdEventLoop(): () => void;
 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

@@ -42,4 +42,3 @@ export function flushPendingSignals() {
 export function setProcessExitCode(code) {
     process.exitCode = code;
 }
-//# sourceMappingURL=signalHandler.keepAlive.js.map

package/dist/startup/index.d.ts

@@ -2,4 +2,3 @@
  * Runtime startup sequence.
  */
 export { executeStartup, rollbackStartup } from "./startup.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/startup/index.js

@@ -2,4 +2,3 @@
  * Runtime startup sequence.
  */
 export { executeStartup, rollbackStartup } from "./startup.core.js";
-//# sourceMappingURL=index.js.map

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

@@ -13,4 +13,3 @@ export declare function executeStartup(lifecycle: LifecycleManager, runtimeId: s
  * Rolls back a failed startup.
  */
 export declare function rollbackStartup(lifecycle: LifecycleManager, logger: Logger): Promise<readonly LifecycleFailure[]>;
-//# sourceMappingURL=startup.core.d.ts.map

package/dist/startup/startup.core.js

@@ -112,4 +112,3 @@ export async function rollbackStartup(lifecycle, logger) {
     });
     return failures;
 }
-//# sourceMappingURL=startup.core.js.map

package/dist/testRuntime/index.d.ts

@@ -7,4 +7,3 @@
  */
 export type { MockModule } from "./testRuntime.core.js";
 export { createTestRuntime, createMockModule, withTestRuntime, } from "./testRuntime.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/testRuntime/index.js

@@ -6,4 +6,3 @@
  * main entry point.
  */
 export { createTestRuntime, createMockModule, withTestRuntime, } from "./testRuntime.core.js";
-//# sourceMappingURL=index.js.map

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

@@ -53,4 +53,3 @@ export declare function createMockModule(id: string, dependencies?: string[]): M
  * @param options - Optional runtime options.
  */
 export declare function withTestRuntime<T>(fn: (runtime: DefaultRuntime) => Promise<T>, modules?: Module[], options?: Partial<RuntimeOptions>): Promise<T>;
-//# sourceMappingURL=testRuntime.core.d.ts.map

package/dist/testRuntime/testRuntime.core.js

@@ -100,4 +100,3 @@ export async function withTestRuntime(fn, modules = [], options = {}) {
         await runtime.stop();
     }
 }
-//# sourceMappingURL=testRuntime.core.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/runtime",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "Application lifecycle orchestrator with dependency ordering, rollback, signals, and readiness checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,12 +27,12 @@
     "vitest": "^5.0.1"
   },
   "dependencies": {
-    "@zudojs/constants": "1.1.4",
-    "@zudojs/container": "1.2.3",
-    "@zudojs/core": "1.2.4",
-    "@zudojs/errors": "1.3.2",
-    "@zudojs/events": "1.3.3",
-    "@zudojs/logger": "1.4.3"
+    "@zudojs/constants": "1.2.0",
+    "@zudojs/container": "1.3.0",
+    "@zudojs/core": "1.3.0",
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/events": "1.4.0",
+    "@zudojs/logger": "1.5.0"
   },
   "license": "MIT",
   "author": {