bazis 0.96.1

package/core/kernel/errors/ShutdownTimeoutError.ts

@@ -0,0 +1,7 @@
+import { KernelError } from "./KernelError";
+
+export class ShutdownTimeoutError extends KernelError {
+  public constructor(public readonly timeoutMs: number) {
+    super(`Graceful shutdown did not finish within ${timeoutMs}ms.`);
+  }
+}

package/core/kernel/errors/StartupAbortedError.ts

@@ -0,0 +1,7 @@
+import { KernelError } from "./KernelError";
+
+export class StartupAbortedError extends KernelError {
+  public constructor() {
+    super("Application startup was aborted by a shutdown request.");
+  }
+}

package/core/kernel/errors/StartupTimeoutError.ts

@@ -0,0 +1,7 @@
+import { KernelError } from "./KernelError";
+
+export class StartupTimeoutError extends KernelError {
+  public constructor(public readonly timeoutMs: number) {
+    super(`Application startup did not finish within ${timeoutMs}ms.`);
+  }
+}

package/core/kernel/errors/index.ts

@@ -0,0 +1,5 @@
+export { ConfigKeyMissingError } from "./ConfigKeyMissingError";
+export { KernelError } from "./KernelError";
+export { ShutdownTimeoutError } from "./ShutdownTimeoutError";
+export { StartupAbortedError } from "./StartupAbortedError";
+export { StartupTimeoutError } from "./StartupTimeoutError";

package/core/kernel/events/EventBus.ts

@@ -0,0 +1,140 @@
+import { createToken, type ServiceResolver } from "../../di";
+import type { EventHandler, EventToken } from "./EventToken";
+import { awaitAbortable } from "../internal/awaitAbortable";
+
+/** A registered handler plus its dispatch order. */
+export interface EventSubscription<T> {
+  readonly handle: EventHandler<T>;
+  /** Lower runs first; ties keep registration order. Default: 0. */
+  readonly order: number;
+}
+
+/** Subscriptions are keyed enumerable services (key = event token id). */
+export const EVENT_HANDLER = createToken<EventSubscription<never>>("BazisEventHandler");
+
+/** Context handed to {@link PublishOptions.onError}. */
+export interface PublishErrorContext<T> {
+  readonly event: EventToken<T>;
+  readonly payload: T;
+}
+
+export interface PublishOptions<T = unknown> {
+  /** Cancels waiting and skips remaining handlers. Cancellation rejects even in isolate mode. */
+  readonly signal?: AbortSignal;
+  /**
+   * When true, handler failures never reject `publish` (observe them via
+   * {@link onError}). Use for fire-and-forget domain events where a faulty
+   * subscriber must not break the publisher. Default: false (failures throw).
+   */
+  readonly isolate?: boolean;
+  /** Per-handler timeout in ms; a slow handler fails with a timeout error. Default: none. */
+  readonly handlerTimeoutMs?: number;
+  /** Called for every handler failure (including timeouts) before aggregation. */
+  readonly onError?: (error: unknown, context: PublishErrorContext<T>) => void;
+}
+
+/** Raised when a handler exceeds {@link PublishOptions.handlerTimeoutMs}. */
+export class EventHandlerTimeoutError extends Error {
+  public constructor(eventName: string, timeoutMs: number) {
+    super(`Event "${eventName}" handler exceeded ${timeoutMs}ms.`);
+    this.name = "EventHandlerTimeoutError";
+  }
+}
+
+/**
+ * In-process typed event bus on top of DI. Handlers come from
+ * `resolveAllKeyed(EVENT_HANDLER, event.id)`, run sequentially in `order`
+ * (ties keep registration order), and — by default — every handler runs even
+ * when one fails, with failures aggregated and re-thrown.
+ *
+ * Use {@link publishScoped} to dispatch within a request/DI scope so handlers
+ * (e.g. `@OnEvent` methods on scoped services) can use scoped dependencies.
+ */
+export class EventBus {
+  public constructor(private readonly resolver: ServiceResolver) {}
+
+  public publish<T>(event: EventToken<T>, payload: T, options?: PublishOptions<T>): Promise<void> {
+    return this.dispatch(this.resolver, event, payload, options);
+  }
+
+  /** Publishes within a specific DI scope (e.g. `ctx.services` in an HTTP request). */
+  public publishScoped<T>(
+    scope: ServiceResolver,
+    event: EventToken<T>,
+    payload: T,
+    options?: PublishOptions<T>,
+  ): Promise<void> {
+    return this.dispatch(scope, event, payload, options);
+  }
+
+  private async dispatch<T>(
+    resolver: ServiceResolver,
+    event: EventToken<T>,
+    payload: T,
+    options?: PublishOptions<T>,
+  ): Promise<void> {
+    options?.signal?.throwIfAborted();
+    const subscriptions = resolver.resolveAllKeyed(EVENT_HANDLER, event.id) as readonly EventSubscription<T>[];
+    if (subscriptions.length === 0) {
+      return;
+    }
+    // Array.prototype.sort is stable (V8/Bun): equal orders keep registration order.
+    const ordered =
+      subscriptions.length === 1 ? subscriptions : [...subscriptions].sort((a, b) => a.order - b.order);
+
+    const errors: unknown[] = [];
+    for (let index = 0; index < ordered.length; index += 1) {
+      options?.signal?.throwIfAborted();
+      try {
+        await this.invoke(ordered[index]!.handle, payload, event, options?.handlerTimeoutMs, options?.signal);
+      } catch (error) {
+        options?.signal?.throwIfAborted();
+        errors.push(error);
+        try {
+          options?.onError?.(error, { event, payload });
+        } catch (observerError) {
+          // Error observation is not an event handler: it must not prevent
+          // later subscriptions from running. Report it with handler failures.
+          errors.push(observerError);
+        }
+      }
+    }
+    options?.signal?.throwIfAborted();
+    if (options?.isolate === true || errors.length === 0) {
+      return;
+    }
+    if (errors.length === 1) {
+      throw errors[0];
+    }
+    throw new AggregateError(errors, `Event "${event.name}" handlers failed.`);
+  }
+
+  private async invoke<T>(
+    handle: EventHandler<T>,
+    payload: T,
+    event: EventToken<T>,
+    timeoutMs: number | undefined,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    signal?.throwIfAborted();
+    const work = Promise.resolve().then(() => {
+      signal?.throwIfAborted();
+      return handle(payload);
+    });
+    if (timeoutMs === undefined || timeoutMs <= 0) {
+      await awaitAbortable(work, signal);
+      return;
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new EventHandlerTimeoutError(event.name, timeoutMs)), timeoutMs);
+    });
+    try {
+      await awaitAbortable(Promise.race([work, timeout]), signal);
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+    }
+  }
+}

package/core/kernel/events/EventToken.ts

@@ -0,0 +1,17 @@
+/**
+ * Typed event identity (compile-safe analog of Spring ApplicationEvents).
+ * The payload type lives only in the type system; the symbol id is used as a
+ * service key for handler registrations — no reflection involved.
+ */
+export interface EventToken<T> {
+  readonly id: symbol;
+  readonly name: string;
+  /** Phantom field carrying the payload type; never set at runtime. */
+  readonly _payload?: T;
+}
+
+export function createEventToken<T>(name: string): EventToken<T> {
+  return { id: Symbol(name), name };
+}
+
+export type EventHandler<T> = (payload: T) => void | Promise<void>;

package/core/kernel/events/eventSubscribers.ts

@@ -0,0 +1,126 @@
+import {
+  DI,
+  Module,
+  singleton,
+  type Class,
+  type BazisModule,
+  type ProviderDefinition,
+  type ServiceResolver,
+} from "../../di";
+import { EVENT_HANDLER, type EventSubscription } from "./EventBus";
+import type { EventHandler, EventToken } from "./EventToken";
+
+// Bun runs TC39 decorators natively, but Symbol.metadata may be absent.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const SUBS_META = Symbol.for("bazis:events:subscriptions");
+
+interface SubscriptionDecl {
+  readonly eventId: symbol;
+  readonly eventName: string;
+  readonly methodName: string | symbol;
+  readonly order: number;
+}
+
+interface SubscriptionsCarrier {
+  [SUBS_META]?: SubscriptionDecl[];
+}
+
+export interface OnEventOptions {
+  /** Lower runs first; ties keep registration order. Default: 0. */
+  readonly order?: number;
+}
+
+/** Own (copy-on-write) subscription list — clones inherited declarations once. */
+function ownSubscriptions(carrier: SubscriptionsCarrier): SubscriptionDecl[] {
+  if (!Object.prototype.hasOwnProperty.call(carrier, SUBS_META)) {
+    carrier[SUBS_META] = carrier[SUBS_META] ? [...carrier[SUBS_META]] : [];
+  }
+  return carrier[SUBS_META]!;
+}
+
+/**
+ * Subscribes a method to a typed event:
+ *
+ * ```ts
+ * class OrderProjections {
+ *   @OnEvent(ORDER_CREATED)
+ *   onCreated(order: OrderCreated) { ... }
+ * }
+ * // register the host + its subscriptions:
+ * @Module({ imports: [eventsModule({ subscribers: [OrderProjections] })] })
+ * class AppModule {}
+ * ```
+ *
+ * The host is resolved through the publishing resolver, so a scoped subscriber
+ * published via `EventBus.publishScoped(scope, ...)` sees that scope's services.
+ */
+export function OnEvent<T>(event: EventToken<T>, options?: OnEventOptions) {
+  return (_value: (this: never, payload: T) => unknown, context: ClassMethodDecoratorContext): void => {
+    if (context.static) {
+      throw new Error("@OnEvent cannot be applied to static methods.");
+    }
+    ownSubscriptions(context.metadata as SubscriptionsCarrier).push({
+      eventId: event.id,
+      eventName: event.name,
+      methodName: context.name,
+      order: options?.order ?? 0,
+    });
+  };
+}
+
+/** Reads `@OnEvent` subscriptions declared on a class (own + inherited). */
+export function eventSubscriptionsOf(ctor: object): readonly SubscriptionDecl[] {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | SubscriptionsCarrier
+    | undefined;
+  return metadata?.[SUBS_META] ?? [];
+}
+
+/**
+ * `EVENT_HANDLER` registrations for every `@OnEvent` method of `HostClass`.
+ * Does not register the host itself — register it with the lifetime you need
+ * (`singleton`/`scoped`). Handlers resolve the host lazily through the
+ * publishing scope, so scope-bound dependencies work with `publishScoped`.
+ */
+export function withEventSubscribers(HostClass: Class<unknown>): ProviderDefinition[] {
+  return eventSubscriptionsOf(HostClass).map((sub) =>
+    DI.keyedTransient(
+      sub.eventId,
+      DI.factoryProviderWithResolver(
+        EVENT_HANDLER,
+        [],
+        (resolver: ServiceResolver): EventSubscription<never> => ({
+          order: sub.order,
+          handle: ((payload: never) => {
+            const host = resolver.resolve(HostClass) as Record<string | symbol, (value: unknown) => unknown>;
+            return host[sub.methodName]!.call(host, payload);
+          }) as EventHandler<never>,
+        }),
+      ),
+    ),
+  );
+}
+
+export interface EventsModuleConfig {
+  /**
+   * Event subscriber classes (with `@OnEvent` methods). Each is registered as a
+   * singleton with auto-resolved dependencies and wired to its events. For
+   * scoped subscribers, register the class yourself and use
+   * {@link withEventSubscribers} in `providers`.
+   */
+  readonly subscribers?: readonly Class<unknown>[];
+}
+
+/** Registers event subscribers and wires their `@OnEvent` methods to the bus. */
+export function eventsModule(config: EventsModuleConfig = {}): BazisModule {
+  const providers: ProviderDefinition[] = [];
+  for (const Subscriber of config.subscribers ?? []) {
+    providers.push(singleton(Subscriber), ...withEventSubscribers(Subscriber));
+  }
+
+  @Module({ providers })
+  class EventsModule {}
+
+  return EventsModule;
+}

package/core/kernel/events/kernelEvents.ts

@@ -0,0 +1,16 @@
+import type { EnvironmentName } from "../types";
+import { createEventToken } from "./EventToken";
+
+export interface ApplicationStartedEvent {
+  readonly environment: EnvironmentName;
+  /** Total time from build start to fully started, in milliseconds. */
+  readonly startupMs: number;
+}
+
+export interface ApplicationStoppingEvent {
+  readonly signal?: string;
+  readonly exitCode: number;
+}
+
+export const APPLICATION_STARTED = createEventToken<ApplicationStartedEvent>("bazis.application.started");
+export const APPLICATION_STOPPING = createEventToken<ApplicationStoppingEvent>("bazis.application.stopping");

package/core/kernel/events/onEvent.ts

@@ -0,0 +1,32 @@
+import { DI, type ProviderDefinition, type ServiceCollection } from "../../di";
+import { EVENT_HANDLER, type EventSubscription } from "./EventBus";
+import type { EventHandler, EventToken } from "./EventToken";
+
+/** Subscription tuning shared by {@link onEvent} / {@link addEventHandler}. */
+export interface SubscribeOptions {
+  /** Lower runs first; ties keep registration order. Default: 0. */
+  readonly order?: number;
+}
+
+function subscription<T>(handler: EventHandler<T>, options?: SubscribeOptions): EventSubscription<never> {
+  return { handle: handler as EventHandler<never>, order: options?.order ?? 0 };
+}
+
+/** Module-style subscription: drop the definition into `providers`. */
+export function onEvent<T>(
+  event: EventToken<T>,
+  handler: EventHandler<T>,
+  options?: SubscribeOptions,
+): ProviderDefinition {
+  return DI.keyedSingleton(event.id, DI.valueProvider(EVENT_HANDLER, subscription(handler, options)));
+}
+
+/** Collection-style subscription. */
+export function addEventHandler<T>(
+  services: ServiceCollection,
+  event: EventToken<T>,
+  handler: EventHandler<T>,
+  options?: SubscribeOptions,
+): void {
+  services.addKeyedSingleton(event.id, DI.valueProvider(EVENT_HANDLER, subscription(handler, options)));
+}

package/core/kernel/health/HealthCheckContracts.ts

@@ -0,0 +1,42 @@
+import { createToken, type ServiceCollection } from "../../di";
+
+export interface HealthCheckResult {
+  readonly healthy: boolean;
+  readonly details?: string;
+}
+
+export interface HealthCheck {
+  readonly name: string;
+  /** Shared by concurrent reports of one HealthService; signal aborts when all observers leave. */
+  check(signal?: AbortSignal): HealthCheckResult | Promise<HealthCheckResult>;
+}
+
+export interface HealthCheckOptions {
+  readonly timeoutMs?: number;
+  readonly checkTimeoutMs?: number;
+  readonly concurrency?: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface HealthReportEntry {
+  readonly name: string;
+  readonly healthy: boolean;
+  readonly details?: string;
+  readonly durationMs: number;
+}
+
+export interface HealthReport {
+  readonly healthy: boolean;
+  readonly checks: readonly HealthReportEntry[];
+}
+
+/** Enumerable token: register any number of checks. */
+export const HEALTH_CHECK = createToken<HealthCheck>("BazisHealthCheck");
+
+export function addHealthCheck(services: ServiceCollection, factory: () => HealthCheck): void {
+  services.addSingleton({
+    provide: HEALTH_CHECK,
+    useFactory: factory,
+    deps: [],
+  });
+}

package/core/kernel/health/HealthService.ts

@@ -0,0 +1,93 @@
+import type { ServiceResolver } from "../../di";
+import { redactSensitiveText } from "../../../library/redaction";
+import { awaitAbortable } from "../internal/awaitAbortable";
+import { KernelError } from "../errors";
+import { HEALTH_CHECK, type HealthCheck, type HealthCheckOptions, type HealthCheckResult, type HealthReport, type HealthReportEntry } from "./HealthCheckContracts";
+
+interface ActiveCheck {
+  readonly controller: AbortController;
+  readonly work: Promise<HealthCheckResult>;
+  observers: number;
+  settled: boolean;
+}
+
+/** Bounded concurrent checks; report order matches registration order. */
+export class HealthService {
+  private readonly active = new WeakMap<HealthCheck, ActiveCheck>();
+
+  public constructor(private readonly resolver: ServiceResolver) {}
+
+  public async check(options: HealthCheckOptions = {}): Promise<HealthReport> {
+    const timeoutMs = bounded(options.timeoutMs ?? 5000, "timeoutMs", 2147483647);
+    const checkTimeoutMs = bounded(options.checkTimeoutMs ?? 1000, "checkTimeoutMs", 2147483647);
+    const concurrency = bounded(options.concurrency ?? 4, "concurrency", 1024);
+    const checks = this.resolver.resolveAll(HEALTH_CHECK);
+    const entries: HealthReportEntry[] = new Array(checks.length);
+    const report = new AbortController();
+    const timer = setTimeout(() => report.abort(new Error("Health report timed out.")), timeoutMs);
+    const reportSignal = options.signal ? AbortSignal.any([options.signal, report.signal]) : report.signal;
+    let next = 0;
+    const worker = async (): Promise<void> => {
+      while (next < checks.length) {
+        const index = next++;
+        const check = checks[index]!;
+        const startedAt = performance.now();
+        const deadline = new AbortController();
+        const checkTimer = setTimeout(() => deadline.abort(new Error("Health check timed out.")), checkTimeoutMs);
+        const signal = AbortSignal.any([reportSignal, deadline.signal]);
+        try {
+          signal.throwIfAborted();
+          const result = await this.observe(check, signal);
+          entries[index] = {
+            name: check.name, healthy: result.healthy === true,
+            ...(result.details === undefined ? {} : { details: redactSensitiveText(result.details) }),
+            durationMs: performance.now() - startedAt,
+          };
+        } catch (error) {
+          entries[index] = { name: check.name, healthy: false, details: redactSensitiveText(error instanceof Error ? error.message : String(error)), durationMs: performance.now() - startedAt };
+        } finally { clearTimeout(checkTimer); }
+      }
+    };
+    try { await Promise.all(Array.from({ length: Math.min(concurrency, checks.length) }, worker)); }
+    finally { clearTimeout(timer); }
+    return { healthy: entries.every(entry => entry.healthy), checks: entries };
+  }
+
+  /** A deadline ends observation; it cannot prove that arbitrary user work stopped. */
+  private async observe(check: HealthCheck, signal: AbortSignal): Promise<HealthCheckResult> {
+    signal.throwIfAborted();
+    let active = this.active.get(check);
+    if (active?.controller.signal.aborted) {
+      throw new KernelError("Previous health check is still running after cancellation.");
+    }
+    if (active === undefined) {
+      const controller = new AbortController();
+      const work = Promise.resolve().then(() => {
+        controller.signal.throwIfAborted();
+        return check.check(controller.signal);
+      });
+      active = { controller, work, observers: 0, settled: false };
+      this.active.set(check, active);
+      const owned = active;
+      const settle = () => {
+        owned.settled = true;
+        if (this.active.get(check) === owned) this.active.delete(check);
+      };
+      // Observe late rejection too, including after every report timed out.
+      void work.then(settle, settle);
+    }
+    active.observers++;
+    try {
+      return await awaitAbortable(active.work, signal);
+    } finally {
+      active.observers--;
+      if (active.observers === 0 && !active.settled) {
+        active.controller.abort(signal.reason ?? new Error("Health check has no active observers."));
+      }
+    }
+  }
+}
+function bounded(value: number, name: string, max: number): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > max) throw new KernelError(`Health ${name} must be an integer from 1 to ${max}.`);
+  return value;
+}

package/core/kernel/index.ts

@@ -0,0 +1,96 @@
+export { ApplicationLifetime } from "./ApplicationLifetime";
+export { Environment } from "./Environment";
+export { Kernel, type KernelRuntimeOptions, type KernelTimings } from "./Kernel";
+export { KernelBuilder, type RootModuleInput } from "./KernelBuilder";
+export { LifecycleCoordinator } from "./LifecycleCoordinator";
+export { Bazis } from "./Bazis";
+export { SupervisedHostedService, supervised, type RestartPolicy } from "./SupervisedHostedService";
+export { LIFECYCLE_HOOK, addLifecycleHook } from "./lifecycleHooks";
+export { LOGGER, type LogFields, type LogLevel, type Logger } from "./logging/Logger";
+export { ConsoleLogger, type ConsoleLoggerOptions } from "./logging/ConsoleLogger";
+
+export { Configuration, loadConfiguration } from "./config/Configuration";
+export { ConfigRegistry } from "./config/ConfigRegistry";
+export { Secret } from "./config/Secret";
+export {
+  defineConfig,
+  configEnum,
+  secret,
+  type AppConfig,
+  type ConfigDefinition,
+  type ConfigView,
+  type ConfigInspection,
+  type ConfigEnum,
+  type ConfigSchema,
+  type ConfigShape,
+  type ConfigValueType,
+  type SchemaFor,
+  type SecretSpec,
+  type ValidatableConfig,
+} from "./config/defineConfig";
+export { addConfigOptions, configOptions, type ConfigOptionsBinding } from "./config/addConfigOptions";
+export { argsSource, envSource, jsonFileSource, memorySource } from "./config/sources";
+
+export {
+  EVENT_HANDLER,
+  EventBus,
+  EventHandlerTimeoutError,
+  type EventSubscription,
+  type PublishErrorContext,
+  type PublishOptions,
+} from "./events/EventBus";
+export { createEventToken, type EventHandler, type EventToken } from "./events/EventToken";
+export {
+  OnEvent,
+  eventSubscriptionsOf,
+  eventsModule,
+  withEventSubscribers,
+  type EventsModuleConfig,
+  type OnEventOptions,
+} from "./events/eventSubscribers";
+export {
+  APPLICATION_STARTED,
+  APPLICATION_STOPPING,
+  type ApplicationStartedEvent,
+  type ApplicationStoppingEvent,
+} from "./events/kernelEvents";
+export { addEventHandler, onEvent, type SubscribeOptions } from "./events/onEvent";
+
+export {
+  HEALTH_CHECK,
+  addHealthCheck,
+  type HealthCheck,
+  type HealthCheckOptions,
+  type HealthCheckResult,
+  type HealthReport,
+  type HealthReportEntry,
+} from "./health/HealthCheckContracts";
+export { HealthService } from "./health/HealthService";
+
+export {
+  REQUEST_ID_HEADER,
+  REQUEST_ID_STATE_KEY,
+  TRACEPARENT_HEADER,
+  TRACEPARENT_STATE_KEY,
+  getOutboundCorrelationHeaders,
+  getRequestId,
+  getTraceparent,
+  runWithRequestContext,
+  runWithRequestContextAsync,
+  type RequestLogContext,
+} from "./correlation/requestContext";
+
+export {
+  ConfigKeyMissingError,
+  KernelError,
+  ShutdownTimeoutError,
+  StartupAbortedError,
+  StartupTimeoutError,
+} from "./errors";
+export type {
+  ConfigSource,
+  EnvironmentName,
+  KernelOptions,
+  LifecycleHook,
+  UnhandledErrorPolicy,
+} from "./types";

package/core/kernel/internal/awaitAbortable.ts

@@ -0,0 +1,18 @@
+/** Stops awaiting without abandoning observation of the underlying operation. */
+export function awaitAbortable<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return operation;
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      signal.removeEventListener("abort", onAbort);
+      reject(signal.reason);
+    };
+    // Observe even an already-cancelled operation: a late rejection must not
+    // become an unhandled error after the owning lifecycle has shut down.
+    operation.then(
+      value => { signal.removeEventListener("abort", onAbort); resolve(value); },
+      error => { signal.removeEventListener("abort", onAbort); reject(error); },
+    );
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/core/kernel/internal/awaitShutdown.ts

@@ -0,0 +1,21 @@
+import { ShutdownTimeoutError } from "../errors";
+
+/** A deadline ends observation; the owner must retain the actual cleanup work. */
+export async function awaitShutdown(work: Promise<void>, timeoutMs: number, elapsedMs = 0): Promise<void> {
+  if (timeoutMs === 0) return work;
+  if (elapsedMs >= timeoutMs) {
+    void work.catch(() => undefined);
+    throw new ShutdownTimeoutError(timeoutMs);
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      work,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new ShutdownTimeoutError(timeoutMs)), Math.max(0, timeoutMs - elapsedMs));
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/core/kernel/internal/reportDiagnosticFailure.ts

@@ -0,0 +1,8 @@
+/** Fixed text avoids exposing arbitrary observer errors, secrets or user inspection hooks. */
+export function reportDiagnosticFailure(component: "supervised.onRetry" | "startup.cleanup"): void {
+  try {
+    void Promise.resolve(console.error(`[bazis] ${component} failed.`)).catch(() => undefined);
+  } catch {
+    // A broken diagnostic sink cannot change the owning operation's outcome.
+  }
+}

package/core/kernel/internal/validateTimeout.ts

@@ -0,0 +1,8 @@
+import { KernelError } from "../errors";
+
+/** Native timers overflow beyond this bound; zero explicitly disables a limit. */
+export function validateTimeout(name: string, timeoutMs: number): void {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 2_147_483_647) {
+    throw new KernelError(`${name} must be an integer between 0 and 2147483647 milliseconds.`);
+  }
+}

package/core/kernel/lifecycleHooks.ts

@@ -0,0 +1,18 @@
+import type { ServiceCollection } from "../di";
+import { createToken } from "../di";
+import type { LifecycleHook } from "./types";
+
+/**
+ * Enumerable token for lifecycle hooks. Register any number of them:
+ * `singleton(LIFECYCLE_HOOK, MyHook)` in a module or `addLifecycleHook(...)`
+ * on a collection.
+ */
+export const LIFECYCLE_HOOK = createToken<LifecycleHook>("BazisLifecycleHook");
+
+export function addLifecycleHook(services: ServiceCollection, factory: () => LifecycleHook): void {
+  services.addSingleton({
+    provide: LIFECYCLE_HOOK,
+    useFactory: factory,
+    deps: [],
+  });
+}