@zudojs/runtime 0.1.0 → 1.1.0

package/dist/runtime/runtime.core.js

@@ -1,27 +1,26 @@
-import { canTransition, isRunning, createStatus, } from "../runtimeState/index.js";
+import { assertTransition, canStart, canStop, hasFailed, isRunning, } from "../runtimeState/index.js";
 import { createRuntimeOptions } from "../runtimeOptions/index.js";
-import { createRuntimeContext } from "../runtimeContext/index.js";
-import { createRuntimeId } from "../runtimeContext/index.js";
+import { createRuntimeContext, withRuntimeContextState, } from "../runtimeContext/index.js";
 import { LifecycleManager } from "../lifecycle/index.js";
 import { executeStartup, rollbackStartup } from "../startup/index.js";
 import { executeShutdown } from "../shutdown/index.js";
 import { SignalHandler } from "../signalHandler/index.js";
 import { ReadinessTracker } from "../readiness/index.js";
-import { createRuntimeEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, } from "../runtimeEvents/index.js";
+import { computeRuntimeHealth } from "../health/index.js";
+import { createRuntimeEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, publishRuntimeEvent, } from "../runtimeEvents/index.js";
 import { createEvent } from "@zudojs/events";
-import { RuntimeStartError, RuntimeStopError, RuntimeStateError, RuntimeTimeoutError, RuntimeRollbackError, toRuntimeError, } from "../runtimeError/index.js";
+import { RuntimeStateError, toRuntimeError } from "../runtimeError/index.js";
 /**
  * Default runtime implementation.
  */
 export class DefaultRuntime {
     _state = "created";
-    _status;
-    _context;
-    _ready = false;
+    _contextBase;
     _startedAt;
     _stoppedAt;
     _failedAt;
     _error;
+    _shutdownFailures = [];
     options;
     modules;
     logger;
@@ -34,7 +33,7 @@ export class DefaultRuntime {
         this.options = createRuntimeOptions(options);
         this.modules = dependencies.modules;
         this.logger = dependencies.logger;
-        this._context = createRuntimeContext({
+        this._contextBase = createRuntimeContext({
             runtimeId: this.options.runtimeId,
             environment: this.options.environment,
             applicationName: this.options.applicationName,
@@ -42,11 +41,26 @@ export class DefaultRuntime {
             logger: dependencies.logger,
             container: dependencies.container,
             eventBus: dependencies.eventBus,
+            metadata: this.options.metadata,
         });
-        this._status = createStatus("created");
-        this.lifecycle = new LifecycleManager(this.modules, this.logger, dependencies.container, this.options.runtimeId, this.options.environment, {
+        this.lifecycle = new LifecycleManager(this.modules, this.logger, {
             shutdownTimeout: this.options.shutdownTimeout,
+            // Always false during startup: rollback depends on stopping at
+            // the first failure rather than pressing on into modules whose
+            // dependencies never came up.
             continueOnFailure: false,
+            parallelInitialization: this.options.parallelInitialization,
+            runtimeId: this.options.runtimeId,
+            onModuleEvent: (type, payload) => {
+                this.emitEvent(type, payload);
+            },
+        }, {
+            ...(dependencies.configuration !== undefined && {
+                configuration: dependencies.configuration,
+            }),
+            ...(dependencies.application !== undefined && {
+                application: dependencies.application,
+            }),
         });
         this.signalHandler = new SignalHandler(this.logger, {
             handleSignals: this.options.handleSignals,
@@ -54,6 +68,7 @@ export class DefaultRuntime {
         });
         this.readinessTracker = new ReadinessTracker({
             autoMarkReady: this.options.trackReadiness,
+            checkTimeout: this.options.readinessCheckTimeout,
         });
     }
     /**
@@ -66,19 +81,88 @@ export class DefaultRuntime {
      * Current runtime status.
      */
     get status() {
-        return this._status;
+        return Object.freeze({
+            state: this._state,
+            ready: this.ready,
+            running: isRunning(this._state),
+            startedAt: this._startedAt,
+            stoppedAt: this._stoppedAt,
+            failedAt: this._failedAt,
+            error: this._error,
+            shutdownFailures: this._shutdownFailures,
+        });
     }
     /**
      * Runtime context.
      */
     get context() {
-        return this._context;
+        return withRuntimeContextState(this._contextBase, {
+            status: this.status,
+            health: this.health,
+            ready: this.ready,
+            ...(this._startedAt !== undefined && { startedAt: this._startedAt }),
+            ...(this._stoppedAt !== undefined && { stoppedAt: this._stoppedAt }),
+            ...(this._failedAt !== undefined && { failedAt: this._failedAt }),
+            ...(this._error !== undefined && { error: this._error }),
+        });
+    }
+    /**
+     * Current runtime health, derived from the lifecycle state and the
+     * registered readiness checks.
+     */
+    get health() {
+        if (!this.options.trackHealth) {
+            return Object.freeze({
+                state: "unknown",
+                checks: Object.freeze([]),
+                timestamp: new Date(),
+            });
+        }
+        return computeRuntimeHealth(this._state, this.readinessTracker.getState());
+    }
+    /**
+     * Current readiness state, including per-check results.
+     */
+    get readiness() {
+        return this.readinessTracker.getState();
+    }
+    /**
+     * Registers a readiness check.
+     */
+    registerReadinessCheck(name, check) {
+        const previousHealth = this.health.state;
+        this.readinessTracker.registerCheck(name, check);
+        this.emitHealthChange(previousHealth);
+    }
+    /**
+     * Removes a readiness check.
+     */
+    removeReadinessCheck(name) {
+        const previousHealth = this.health.state;
+        const removed = this.readinessTracker.removeCheck(name);
+        if (removed) {
+            this.emitHealthChange(previousHealth);
+        }
+        return removed;
+    }
+    /**
+     * Re-evaluates every registered readiness check.
+     */
+    async runReadinessChecks() {
+        const previousHealth = this.health.state;
+        const previouslyReady = this.ready;
+        await this.readinessTracker.runChecks();
+        this.emitHealthChange(previousHealth);
+        if (this.options.emitEvents && this.ready !== previouslyReady) {
+            const state = this.readinessTracker.getState();
+            this.emitEvent("runtime.readiness.changed", createReadinessEventPayload(this.options.runtimeId, this._state, state.ready, state.reason));
+        }
     }
     /**
      * Whether the runtime is ready.
      */
     get ready() {
-        return this._ready;
+        return this.readinessTracker.isReady();
     }
     /**
      * Starts the runtime.
@@ -90,8 +174,11 @@ export class DefaultRuntime {
         if (this.startPromise) {
             return this.startPromise;
         }
-        if (!canTransition(this._state, "initializing")) {
-            throw new RuntimeStateError(`Cannot start runtime from state "${this._state}".`);
+        if (!canStart(this._state)) {
+            throw new RuntimeStateError(`Cannot start a runtime in state "${this._state}"; start is only valid from "created". ` +
+                (hasFailed(this._state)
+                    ? "This runtime failed to start; call stop() to release it and create a new one."
+                    : "Create a new runtime instead of restarting this one."));
         }
         this.startPromise = this.performStart();
         try {
@@ -104,6 +191,14 @@ export class DefaultRuntime {
     /**
      * Stops the runtime.
      */
+    /**
+     * Stops the runtime.
+     *
+     * A failed runtime is stoppable: startup rollback only reaches modules
+     * that were started, so this is the operator's route to releasing
+     * everything else. It is also idempotent — stopping an already-stopped
+     * runtime is a no-op rather than an error.
+     */
     async stop() {
         if (this._state === "stopped") {
             return;
@@ -111,13 +206,25 @@ export class DefaultRuntime {
         if (this.stopPromise) {
             return this.stopPromise;
         }
+        if (this.startPromise) {
+            // A stop requested while startup is in flight — typically a SIGTERM
+            // arriving while modules are still coming up — waits for startup to
+            // settle and then shuts down whatever it produced. Previously this
+            // threw `RuntimeStateError` ("cannot stop a runtime in state
+            // initializing"), so the signal handler logged "Shutdown failed" and
+            // the runtime carried on to `running` as if nothing had happened.
+            // Startup is bounded by `startupTimeout`, so this wait is too.
+            await this.startPromise.catch(() => undefined);
+            return this.stop();
+        }
         if (this._state === "created") {
             this._state = "stopped";
             this._stoppedAt = new Date();
+            this.signalHandler.unregister();
             return;
         }
-        if (!canTransition(this._state, "stopping")) {
-            throw new RuntimeStateError(`Cannot stop runtime from state "${this._state}".`);
+        if (!canStop(this._state)) {
+            throw new RuntimeStateError(`Cannot stop a runtime in state "${this._state}"; stop is valid from "created", "running" and "failed".`);
         }
         this.stopPromise = this.performStop();
         try {
@@ -132,26 +239,34 @@ export class DefaultRuntime {
      */
     async performStart() {
         this.transitionTo("initializing");
+        this.readinessTracker.setState("initializing", "Runtime is starting its modules.");
         if (this.options.emitEvents) {
             this.emitEvent("runtime.initializing");
         }
+        // Registered before startup rather than after: a SIGTERM arriving
+        // 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._context.eventBus, this.logger, this.options.emitEvents);
+            await executeStartup(this.lifecycle, this.options.runtimeId, this._contextBase.eventBus, this.logger, this.options.emitEvents, this.options.startupTimeout);
             this.transitionTo("running");
-            this._ready = true;
             this._startedAt = new Date();
-            this.readinessTracker.markReady("Runtime started successfully.");
+            // Evaluate any checks registered before startup instead of
+            // declaring readiness over the top of them. Force-marking ready
+            // here reported a runtime as ready while a dependency check was
+            // failing.
+            await this.readinessTracker.runChecks();
+            if (this.readinessTracker.hasChecks()) {
+                if (!this.ready) {
+                    this.logger.warn("Runtime started, but one or more readiness checks are failing.", { reason: this.readinessTracker.getState().reason });
+                }
+            }
+            else {
+                this.readinessTracker.markReady("Runtime started successfully.");
+            }
             if (this.options.emitEvents) {
                 this.emitEvent("runtime.running");
-                this.emitEvent("runtime.readiness.changed", createReadinessEventPayload(this.options.runtimeId, "running", true, "Runtime started successfully."));
+                this.emitEvent("runtime.readiness.changed", createReadinessEventPayload(this.options.runtimeId, "running", this.ready, this.readinessTracker.getState().reason));
             }
-            this.signalHandler.register(() => {
-                this.stop().catch((error) => {
-                    this.logger.error("Shutdown failed.", {
-                        errorMessage: error.message,
-                    });
-                });
-            });
             this.logger.info("Runtime is ready.", {
                 runtimeId: this.options.runtimeId,
                 environment: this.options.environment,
@@ -168,7 +283,12 @@ export class DefaultRuntime {
                 this.emitEvent("runtime.failed", createFailureEventPayload(this.options.runtimeId, "failed", runtimeError, "startup"));
             }
             try {
-                await rollbackStartup(this.lifecycle, this.logger);
+                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),
+                    });
+                }
             }
             catch (rollbackError) {
                 this.logger.error("Rollback failed.", {
@@ -186,22 +306,31 @@ export class DefaultRuntime {
      */
     async performStop() {
         this.transitionTo("stopping");
-        this._ready = false;
-        this.readinessTracker.markNotReady("Runtime is shutting down.");
+        this.readinessTracker.setState("shutting_down", "Runtime is shutting down.");
         if (this.options.emitEvents) {
             this.emitEvent("runtime.stopping");
         }
         try {
-            await executeShutdown(this.lifecycle, this.options.runtimeId, this._context.eventBus, this.logger, this.options.shutdownTimeout, this.options.emitEvents);
+            const result = await executeShutdown(this.lifecycle, this.options.runtimeId, this._contextBase.eventBus, this.logger, this.options.shutdownTimeout, this.options.emitEvents);
+            this._shutdownFailures = result.failures;
             this.transitionTo("stopped");
             this._stoppedAt = new Date();
-            this.signalHandler.unregister();
             if (this.options.emitEvents) {
                 this.emitEvent("runtime.stopped");
             }
-            this.logger.info("Runtime stopped.", {
-                runtimeId: this.options.runtimeId,
-            });
+            if (result.failures.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),
+                });
+            }
+            else {
+                this.logger.info("Runtime stopped.", {
+                    runtimeId: this.options.runtimeId,
+                });
+            }
         }
         catch (error) {
             const runtimeError = toRuntimeError(error, "shutdown");
@@ -216,31 +345,69 @@ export class DefaultRuntime {
             this.transitionTo("failed");
             throw runtimeError;
         }
+        finally {
+            // Released on both paths: leaving handlers attached after a failed
+            // stop keeps the process listening for a signal it can no longer
+            // act on.
+            this.signalHandler.unregister();
+        }
+    }
+    /**
+     * Runs shutdown in response to a termination signal.
+     */
+    async handleShutdownSignal() {
+        try {
+            await this.stop();
+        }
+        catch (error) {
+            this.logger.error("Shutdown failed.", {
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
+        }
     }
     /**
      * Transitions to a new state.
      */
     transitionTo(newState) {
         const oldState = this._state;
-        if (!canTransition(oldState, newState)) {
-            throw new RuntimeStateError(`Invalid state transition from "${oldState}" to "${newState}".`);
-        }
+        // Delegates to the exported assertion so the public state machine and
+        // the runtime cannot disagree about what a legal transition is.
+        assertTransition(oldState, newState);
+        const previousHealth = this.health.state;
         this._state = newState;
-        this._status = createStatus(newState);
         this.logger.debug(`Runtime state: ${oldState} -> ${newState}`);
+        this.emitHealthChange(previousHealth);
+    }
+    /**
+     * Emits `runtime.health.changed` when the derived health state has moved
+     * away from `previousHealth`. Health is derived rather than stored, so
+     * callers compare against a value captured before the change.
+     */
+    emitHealthChange(previousHealth) {
+        if (!this.options.emitEvents || !this.options.trackHealth) {
+            return;
+        }
+        const health = this.health;
+        if (health.state === previousHealth) {
+            return;
+        }
+        this.emitEvent("runtime.health.changed", createHealthEventPayload(this.options.runtimeId, this._state, previousHealth, health.state, health.checks.map((check) => ({
+            name: check.name,
+            healthy: check.healthy,
+        }))));
     }
     /**
      * Emits a runtime event.
      */
     emitEvent(eventType, payload) {
-        if (this.options.emitEvents && this._context.eventBus) {
+        if (this.options.emitEvents && this._contextBase.eventBus) {
             const eventPayload = payload ??
                 createRuntimeEventPayload(this.options.runtimeId, this._state);
             const event = createEvent({
                 type: eventType,
                 payload: eventPayload,
             });
-            this._context.eventBus.publish(event);
+            publishRuntimeEvent(this._contextBase.eventBus, this.logger, event);
         }
     }
 }

package/dist/runtimeContext/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Runtime context providing access to running application state.
  */
-export { createRuntimeContext, createRuntimeIdentity, } from "./runtimeContext.core.js";
+export { createRuntimeContext, withRuntimeContextState, } from "./runtimeContext.core.js";
 export { createRuntimeId, createCorrelationId, createRequestId, } from "./runtimeContext.factory.js";
-export type { RuntimeContext, RuntimeIdentity, RuntimeContextDependencies, RuntimeContextState, } from "./runtimeContext.type.js";
+export type { RuntimeContext, RuntimeContextDependencies, RuntimeContextState, } from "./runtimeContext.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtimeContext/index.js

@@ -1,6 +1,6 @@
 /**
  * Runtime context providing access to running application state.
  */
-export { createRuntimeContext, createRuntimeIdentity, } from "./runtimeContext.core.js";
+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

@@ -1,11 +1,20 @@
-import type { Environment } from "@zudojs/constants";
-import type { RuntimeContext, RuntimeContextDependencies, RuntimeIdentity } from "./runtimeContext.type.js";
+import type { RuntimeContext, RuntimeContextDependencies, RuntimeContextState } from "./runtimeContext.type.js";
 /**
  * Creates a runtime context.
  */
 export declare function createRuntimeContext(dependencies: RuntimeContextDependencies): RuntimeContext;
 /**
- * Creates runtime identity information.
+ * Returns a context reflecting the current runtime state.
+ *
+ * `createRuntimeContext` captures the dependencies that never change for
+ * the life of a runtime; the lifecycle-dependent fields are layered on top
+ * of that base each time the context is read, so callers never observe a
+ * stale snapshot.
+ *
+ * Every field of {@link RuntimeContextState} is applied. Previously only
+ * `startedAt` was, so `stoppedAt`, `failedAt` and `error` were computed by
+ * the runtime, passed in here, and silently dropped — the context claimed
+ * a clean runtime on the failure path.
  */
-export declare function createRuntimeIdentity(runtimeId: string, environment: Environment, applicationName: string, applicationVersion: string): RuntimeIdentity;
+export declare function withRuntimeContextState(base: RuntimeContext, state: RuntimeContextState): RuntimeContext;
 //# sourceMappingURL=runtimeContext.core.d.ts.map

package/dist/runtimeContext/runtimeContext.core.js

@@ -1,4 +1,3 @@
-import { createRuntimeId as generateRuntimeId } from "./runtimeContext.factory.js";
 import { createStatus } from "../runtimeState/runtimeState.core.js";
 /**
  * Creates a runtime context.
@@ -21,21 +20,33 @@ export function createRuntimeContext(dependencies) {
             timestamp: new Date(),
         },
         ready: false,
+        metadata: dependencies.metadata ?? Object.freeze({}),
     });
 }
 /**
- * Creates runtime identity information.
+ * Returns a context reflecting the current runtime state.
+ *
+ * `createRuntimeContext` captures the dependencies that never change for
+ * the life of a runtime; the lifecycle-dependent fields are layered on top
+ * of that base each time the context is read, so callers never observe a
+ * stale snapshot.
+ *
+ * Every field of {@link RuntimeContextState} is applied. Previously only
+ * `startedAt` was, so `stoppedAt`, `failedAt` and `error` were computed by
+ * the runtime, passed in here, and silently dropped — the context claimed
+ * a clean runtime on the failure path.
  */
-export function createRuntimeIdentity(runtimeId, environment, applicationName, applicationVersion) {
+export function withRuntimeContextState(base, state) {
     return Object.freeze({
-        runtimeId,
-        environment,
-        applicationName,
-        applicationVersion,
-        hostname: typeof process !== "undefined"
-            ? (process.env.HOSTNAME ?? "unknown")
-            : "unknown",
-        processId: typeof process !== "undefined" ? process.pid : 0,
+        ...base,
+        state: state.status.state,
+        status: state.status,
+        health: state.health,
+        ready: state.ready,
+        ...(state.startedAt !== undefined && { startedAt: state.startedAt }),
+        ...(state.stoppedAt !== undefined && { stoppedAt: state.stoppedAt }),
+        ...(state.failedAt !== undefined && { failedAt: state.failedAt }),
+        ...(state.error !== undefined && { error: state.error }),
     });
 }
 //# sourceMappingURL=runtimeContext.core.js.map

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

@@ -1,4 +1,5 @@
 import type { Environment } from "@zudojs/constants";
+import type { RuntimeError } from "@zudojs/errors";
 import type { Logger } from "@zudojs/logger";
 import type { EventBus } from "@zudojs/events";
 import type { Container } from "@zudojs/container";
@@ -7,6 +8,8 @@ import type { RuntimeId, RuntimeStatus, RuntimeState, RuntimeHealth } from "../r
  * Runtime context providing access to the running application state.
  */
 export interface RuntimeContext {
+    /** Additional runtime metadata supplied through runtime options. */
+    readonly metadata: Readonly<Record<string, unknown>>;
     readonly runtimeId: RuntimeId;
     readonly environment: Environment;
     readonly applicationName: string;
@@ -14,28 +17,24 @@ export interface RuntimeContext {
     readonly state: RuntimeState;
     readonly status: RuntimeStatus;
     readonly startedAt?: Date;
+    /** When the runtime last reached `stopped`. */
+    readonly stoppedAt?: Date;
+    /** When the runtime last reached `failed`. */
+    readonly failedAt?: Date;
+    /** The error that failed the runtime, if it has failed. */
+    readonly error?: RuntimeError;
     readonly logger: Logger;
     readonly container: Container;
     readonly eventBus: EventBus;
     readonly health: RuntimeHealth;
     readonly ready: boolean;
 }
-/**
- * Runtime identity information.
- */
-export interface RuntimeIdentity {
-    readonly runtimeId: RuntimeId;
-    readonly applicationName: string;
-    readonly applicationVersion: string;
-    readonly environment: Environment;
-    readonly hostname: string;
-    readonly processId: number;
-    readonly startedAt?: Date;
-}
 /**
  * Dependencies required to create the runtime context.
  */
 export interface RuntimeContextDependencies {
+    /** Additional runtime metadata, surfaced on the context. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
     readonly runtimeId: RuntimeId;
     readonly environment: Environment;
     readonly applicationName: string;
@@ -54,6 +53,6 @@ export interface RuntimeContextState {
     startedAt?: Date;
     stoppedAt?: Date;
     failedAt?: Date;
-    error?: Error;
+    error?: RuntimeError;
 }
 //# sourceMappingURL=runtimeContext.type.d.ts.map

package/dist/runtimeError/runtimeError.base.js

@@ -1,4 +1,4 @@
-import { RuntimeError, RuntimeStateError as BaseRuntimeStateError, ErrorCode, } from "@zudojs/errors";
+import { RuntimeError, RuntimeStateError as BaseRuntimeStateError, } from "@zudojs/errors";
 /**
  * Error thrown when an invalid runtime state is encountered.
  */

package/dist/runtimeEvents/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Runtime lifecycle events.
  */
-export { createRuntimeEventPayload, createModuleEventPayload, createFailureEventPayload, createHealthEventPayload, createReadinessEventPayload, } from "./runtimeEvents.core.js";
-export type { RuntimeEventType, RuntimeEventPayload, RuntimeModuleEventPayload, RuntimeFailureEventPayload, RuntimeHealthEventPayload, RuntimeReadinessEventPayload, RuntimeEventMap, } from "./runtimeEvents.type.js";
+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

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

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

@@ -1,3 +1,5 @@
+import type { Event } from "@zudojs/events";
+import type { RuntimeFailureState, RuntimeState } from "../runtimeState/runtimeState.type.js";
 import type { RuntimeEventPayload, RuntimeModuleEventPayload, RuntimeFailureEventPayload, RuntimeHealthEventPayload, RuntimeReadinessEventPayload } from "./runtimeEvents.type.js";
 /**
  * Creates a base runtime event payload.
@@ -13,7 +15,7 @@ export declare function createModuleEventPayload(runtimeId: string, state: strin
 /**
  * Creates a runtime failure event payload.
  */
-export declare function createFailureEventPayload(runtimeId: string, state: string, error: Error, phase: string, failedModuleId?: string): RuntimeFailureEventPayload;
+export declare function createFailureEventPayload(runtimeId: string, state: RuntimeState | RuntimeFailureState, error: Error, phase: string, failedModuleId?: string): RuntimeFailureEventPayload;
 /**
  * Creates a runtime health change event payload.
  */
@@ -25,4 +27,16 @@ export declare function createHealthEventPayload(runtimeId: string, state: strin
  * Creates a runtime readiness change event payload.
  */
 export declare function createReadinessEventPayload(runtimeId: string, state: string, ready: boolean, reason?: string): RuntimeReadinessEventPayload;
+/**
+ * Publishes a runtime lifecycle event without letting a failing handler,
+ * middleware, or a disposed bus turn into an unhandled promise rejection.
+ *
+ * Runtime events are informational; a failure to deliver one must never
+ * abort startup or shutdown, so the rejection is logged and swallowed.
+ */
+export declare function publishRuntimeEvent(eventBus: {
+    publish(event: Event): Promise<unknown>;
+}, logger: {
+    warn(message: string, context?: Record<string, unknown>): void;
+}, event: Event): void;
 //# sourceMappingURL=runtimeEvents.core.d.ts.map

package/dist/runtimeEvents/runtimeEvents.core.js

@@ -60,4 +60,30 @@ export function createReadinessEventPayload(runtimeId, state, ready, reason) {
         ...(reason !== undefined && { reason }),
     });
 }
+/**
+ * Publishes a runtime lifecycle event without letting a failing handler,
+ * middleware, or a disposed bus turn into an unhandled promise rejection.
+ *
+ * Runtime events are informational; a failure to deliver one must never
+ * abort startup or shutdown, so the rejection is logged and swallowed.
+ */
+export function publishRuntimeEvent(eventBus, logger, event) {
+    let result;
+    try {
+        result = eventBus.publish(event);
+    }
+    catch (error) {
+        logger.warn("Failed to publish runtime event.", {
+            eventType: event.type,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    void Promise.resolve(result).catch((error) => {
+        logger.warn("Failed to publish runtime event.", {
+            eventType: event.type,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+}
 //# sourceMappingURL=runtimeEvents.core.js.map