bazis 0.96.1

package/core/kernel/KernelBuilder.ts

@@ -0,0 +1,172 @@
+import { DI, Global, Module, collectModuleConfigs, createContainer, type BazisModule, type BazisModuleRef } from "../di";
+import { isBazisModuleClass } from "../di/module/Module";
+import { ApplicationLifetime } from "./ApplicationLifetime";
+import { Configuration, loadConfiguration } from "./config/Configuration";
+import { ConfigRegistry } from "./config/ConfigRegistry";
+import { argsSource, envSource } from "./config/sources";
+import { Environment } from "./Environment";
+import { EventBus } from "./events/EventBus";
+import { HealthService } from "./health/HealthService";
+import { Kernel, type KernelTimings } from "./Kernel";
+import { ConsoleLogger } from "./logging/ConsoleLogger";
+import { LOGGER, type Logger } from "./logging/Logger";
+import type { ConfigSource, EnvironmentName, KernelOptions, UnhandledErrorPolicy } from "./types";
+import { validateTimeout } from "./internal/validateTimeout";
+
+/** Root module or a profile factory (Spring profiles, but explicit). */
+export type RootModuleInput = BazisModuleRef | ((environment: Environment) => BazisModuleRef);
+
+function resolveUserRoot(rootModule: RootModuleInput, environment: Environment): BazisModuleRef {
+  if (typeof rootModule === "function") {
+    if (isBazisModuleClass(rootModule)) {
+      return rootModule as BazisModule;
+    }
+    return (rootModule as (environment: Environment) => BazisModuleRef)(environment);
+  }
+  return rootModule;
+}
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+const DEFAULT_SIGNALS: readonly NodeJS.Signals[] = ["SIGINT", "SIGTERM"];
+
+/**
+ * Mutable configuration phase (.NET HostApplicationBuilder). `build()`
+ * produces an immutable Kernel: config is loaded, the DI graph is built and
+ * validated, nothing can be registered afterwards.
+ */
+export class KernelBuilder {
+  private readonly configSources: ConfigSource[] = [];
+  private environmentName?: EnvironmentName;
+  private debugFlag?: boolean;
+  private shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  private startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT_MS;
+  private signals: readonly NodeJS.Signals[] = DEFAULT_SIGNALS;
+  private unhandledErrorPolicy: UnhandledErrorPolicy = "shutdown";
+  private validateOnBuild = true;
+  private startupReport?: boolean;
+  private logger?: Logger;
+
+  public constructor(private readonly rootModule: RootModuleInput) {}
+
+  /** Overrides the default {@link ConsoleLogger} registered under `LOGGER`. */
+  public useLogger(logger: Logger): this {
+    this.logger = logger;
+    return this;
+  }
+
+  public useOptions(options: KernelOptions): this {
+    if (options.environment !== undefined) this.environmentName = options.environment;
+    if (options.debug !== undefined) this.debugFlag = options.debug;
+    if (options.shutdownTimeoutMs !== undefined) this.shutdownTimeoutMs = options.shutdownTimeoutMs;
+    if (options.startupTimeoutMs !== undefined) this.startupTimeoutMs = options.startupTimeoutMs;
+    if (options.signals !== undefined) this.signals = options.signals;
+    if (options.unhandledErrorPolicy !== undefined) this.unhandledErrorPolicy = options.unhandledErrorPolicy;
+    if (options.validateOnBuild !== undefined) this.validateOnBuild = options.validateOnBuild;
+    if (options.startupReport !== undefined) this.startupReport = options.startupReport;
+    return this;
+  }
+
+  public useEnvironment(name: EnvironmentName, debug?: boolean): this {
+    this.environmentName = name;
+    if (debug !== undefined) {
+      this.debugFlag = debug;
+    }
+    return this;
+  }
+
+  public useShutdownTimeout(timeoutMs: number): this {
+    this.shutdownTimeoutMs = timeoutMs;
+    return this;
+  }
+
+  public useStartupTimeout(timeoutMs: number): this {
+    this.startupTimeoutMs = timeoutMs;
+    return this;
+  }
+
+  public useSignals(signals: readonly NodeJS.Signals[]): this {
+    this.signals = signals;
+    return this;
+  }
+
+  public useUnhandledErrorPolicy(policy: UnhandledErrorPolicy): this {
+    this.unhandledErrorPolicy = policy;
+    return this;
+  }
+
+  public useStartupReport(enabled: boolean): this {
+    this.startupReport = enabled;
+    return this;
+  }
+
+  /** Sources are merged in registration order: later sources override earlier ones. */
+  public addConfigSource(source: ConfigSource): this {
+    this.configSources.push(source);
+    return this;
+  }
+
+  public async build(): Promise<Kernel> {
+    validateTimeout("startupTimeoutMs", this.startupTimeoutMs);
+    validateTimeout("shutdownTimeoutMs", this.shutdownTimeoutMs);
+    const buildStartedAt = performance.now();
+
+    const environment =
+      this.environmentName !== undefined
+        ? new Environment(this.environmentName, this.debugFlag ?? this.environmentName !== "production")
+        : Environment.fromProcess(this.debugFlag);
+
+    const configStartedAt = performance.now();
+    const configuration = await loadConfiguration(this.configSources.length ? this.configSources : [envSource(), argsSource()]);
+    const configMs = performance.now() - configStartedAt;
+
+    const lifetime = new ApplicationLifetime();
+    const logger = this.logger ?? new ConsoleLogger({ minLevel: environment.debug ? "debug" : "info" });
+    const userRoot = resolveUserRoot(this.rootModule, environment);
+    const configs = collectModuleConfigs([userRoot]);
+    const configRegistry = new ConfigRegistry(configs, environment.name, configuration);
+
+    // Kernel infrastructure is a global module: any user module can depend on
+    // Environment / Configuration / ApplicationLifetime / EventBus without
+    // importing anything (NestJS @Global semantics).
+    @Global()
+    @Module({
+      providers: [
+        DI.singleton(DI.valueProvider(ConfigRegistry, configRegistry)),
+        ...configRegistry.providers,
+        DI.singleton(DI.valueProvider(Environment, environment)),
+        DI.singleton(DI.valueProvider(Configuration, configuration)),
+        DI.singleton(DI.valueProvider(ApplicationLifetime, lifetime)),
+        DI.singleton(DI.valueProvider(LOGGER, logger)),
+        DI.singleton(DI.factoryProviderWithResolver(EventBus, [], (resolver) => new EventBus(resolver))),
+        DI.singleton(DI.factoryProviderWithResolver(HealthService, [], (resolver) => new HealthService(resolver))),
+      ],
+    })
+    class BazisKernelInfraModule {}
+
+    @Module({
+      imports: [BazisKernelInfraModule, userRoot],
+    })
+    class BazisKernelModule {}
+
+    const kernelRootModule = BazisKernelModule;
+
+    const containerStartedAt = performance.now();
+    const container = createContainer(kernelRootModule, { validateOnBuild: this.validateOnBuild });
+    const containerMs = performance.now() - containerStartedAt;
+
+    const timings: KernelTimings = {
+      configMs,
+      containerMs,
+      buildStartedAt,
+    };
+
+    return new Kernel(container, environment, configuration, lifetime, timings, {
+      startupTimeoutMs: this.startupTimeoutMs,
+      shutdownTimeoutMs: this.shutdownTimeoutMs,
+      signals: this.signals,
+      unhandledErrorPolicy: this.unhandledErrorPolicy,
+      startupReport: this.startupReport ?? !environment.isProduction,
+    });
+  }
+}

package/core/kernel/LifecycleCoordinator.ts

@@ -0,0 +1,204 @@
+import { validateOptionsOnStart, type HostedService } from "../di";
+import type { Token } from "../di";
+import { LIFECYCLE_HOOK } from "./lifecycleHooks";
+import type { LifecycleHook } from "./types";
+import { ShutdownTimeoutError } from "./errors";
+import { awaitAbortable } from "./internal/awaitAbortable";
+import { resolveHostedServices, validateHostedServicePlan } from "../di/extensions/hosted-service";
+import { awaitShutdown } from "./internal/awaitShutdown";
+
+interface LifecycleResolver {
+  resolveAll<T>(token: Token<T>): readonly T[];
+}
+
+/**
+ * Orchestrates the boot/shutdown sequence:
+ * options fail-fast -> onInit hooks -> hosted services by ascending phase ->
+ * onBootstrap hooks; shutdown runs everything in reverse. A failed start rolls
+ * back already-started services. The overall shutdown time budget is owned by
+ * the {@link Kernel}, which bounds the whole graceful-stop sequence.
+ */
+export class LifecycleCoordinator {
+  private hooks: readonly LifecycleHook[] = [];
+  /** Hosted services in actual start order (stop iterates in reverse). */
+  private readonly started: HostedService[] = [];
+  private hostedCount = 0;
+  private hookWork?: Promise<void>;
+  private rollbackWork?: Promise<void>;
+  private rollbackError?: unknown;
+  private rollbackStartedAt?: number;
+
+  public constructor(private readonly resolver: LifecycleResolver) {}
+
+  public get startedHostedCount(): number {
+    return this.hostedCount;
+  }
+
+  public get hookCount(): number {
+    return this.hooks.length;
+  }
+
+  /** @internal The host must join actual cleanup before disposing hook dependencies. */
+  public waitForRollback(): Promise<void> {
+    return this.rollbackWork ?? Promise.resolve();
+  }
+
+  /** @internal Completed rollback failure, distinct from a deadline ending observation. */
+  public get rollbackFailure(): unknown {
+    return this.rollbackError;
+  }
+
+  /** @internal Container disposal uses the remaining part of the same deadline. */
+  public get rollbackElapsedMs(): number {
+    return this.rollbackStartedAt === undefined ? 0 : performance.now() - this.rollbackStartedAt;
+  }
+
+  public async start(signal?: AbortSignal, rollbackTimeoutMs = 0): Promise<void> {
+    signal?.throwIfAborted();
+    validateOptionsOnStart(this.resolver);
+    const hosted = resolveHostedServices(this.resolver);
+    const validation = validateHostedServicePlan(hosted, signal);
+    if (validation) await awaitAbortable(validation, signal);
+    this.hooks = this.resolver.resolveAll(LIFECYCLE_HOOK);
+
+    try {
+      for (let index = 0; index < this.hooks.length; index += 1) {
+        await this.invokeHook(() => (this.hooks[index] as LifecycleHook).onInit?.(), signal);
+      }
+
+      const phases = groupByPhase(hosted);
+      for (let phaseIndex = 0; phaseIndex < phases.length; phaseIndex += 1) {
+        const group = phases[phaseIndex] as HostedService[];
+        for (let index = 0; index < group.length; index += 1) {
+          const service = group[index] as HostedService;
+          const starting = Promise.resolve().then(() => {
+            signal?.throwIfAborted();
+            return service.start(signal);
+          });
+          try {
+            await awaitAbortable(starting, signal);
+          } catch (error) {
+            if (signal?.aborted) {
+              // A legacy service may ignore the signal and finish after startup
+              // has already been cancelled. Observe it and stop it immediately
+              // so the late listener/connection cannot escape rollback.
+              void starting.then(() => service.stop()).catch(() => undefined);
+            }
+            throw error;
+          }
+          this.started.push(service);
+        }
+      }
+      this.hostedCount = this.started.length;
+
+      for (let index = 0; index < this.hooks.length; index += 1) {
+        await this.invokeHook(() => (this.hooks[index] as LifecycleHook).onBootstrap?.(), signal);
+      }
+    } catch (error) {
+      try {
+        this.rollbackStartedAt = performance.now();
+        this.rollbackWork = this.rollbackStart(error);
+        await awaitShutdown(this.rollbackWork, rollbackTimeoutMs);
+      } catch (cleanupError) {
+        if (cleanupError instanceof ShutdownTimeoutError) {
+          cleanupError.cause = error;
+          throw cleanupError;
+        }
+        throw new AggregateError([error, cleanupError], "Startup failed and rollback also failed.", { cause: error });
+      }
+      throw error;
+    }
+  }
+
+  private invokeHook(callback: () => void | Promise<void>, signal?: AbortSignal): Promise<void> {
+    this.hookWork = Promise.resolve().then(() => {
+      signal?.throwIfAborted();
+      return callback();
+    });
+    return awaitAbortable(this.hookWork, signal);
+  }
+
+  /**
+   * Stops hosted services (reverse start order), then runs `onShutdown` and
+   * `onDestroy` hooks (reverse). Unbounded by design — the Kernel races the
+   * whole shutdown sequence against the configured timeout.
+   */
+  public async stopServices(signal?: string): Promise<void> {
+    const errors: unknown[] = [];
+
+    for (let index = this.started.length - 1; index >= 0; index -= 1) {
+      try {
+        await (this.started[index] as HostedService).stop();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    this.started.length = 0;
+
+    for (let index = this.hooks.length - 1; index >= 0; index -= 1) {
+      try {
+        await (this.hooks[index] as LifecycleHook).onShutdown?.(signal);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    for (let index = this.hooks.length - 1; index >= 0; index -= 1) {
+      try {
+        await (this.hooks[index] as LifecycleHook).onDestroy?.();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+
+    if (errors.length === 1) {
+      throw errors[0];
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(errors, "Shutdown finished with errors.");
+    }
+  }
+
+  // The deadline bounds the caller, not this work. An in-flight hook may still
+  // acquire resources and use hosted services: join it before tearing them down.
+  private async rollbackStart(startError: unknown): Promise<void> {
+    const errors: unknown[] = [];
+    try { await this.hookWork; }
+    catch (error) { if (error !== startError) errors.push(error); }
+    for (let index = this.started.length - 1; index >= 0; index -= 1) {
+      try {
+        await (this.started[index] as HostedService).stop();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    this.started.length = 0;
+    this.hostedCount = 0;
+    for (let index = this.hooks.length - 1; index >= 0; index -= 1) {
+      try {
+        await (this.hooks[index] as LifecycleHook).onDestroy?.();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) {
+      this.rollbackError = new AggregateError(errors, "Startup rollback failed.");
+      throw this.rollbackError;
+    }
+  }
+}
+
+/** Groups by ascending `phase` (default 0), keeping registration order inside a group. */
+function groupByPhase(services: readonly HostedService[]): HostedService[][] {
+  const byPhase = new Map<number, HostedService[]>();
+  for (let index = 0; index < services.length; index += 1) {
+    const service = services[index] as HostedService;
+    const phase = service.phase ?? 0;
+    const group = byPhase.get(phase);
+    if (group) {
+      group.push(service);
+    } else {
+      byPhase.set(phase, [service]);
+    }
+  }
+  return [...byPhase.entries()].sort((a, b) => a[0] - b[0]).map((entry) => entry[1]);
+}

package/core/kernel/README.md

@@ -0,0 +1,66 @@
+# Kernel Folder Map
+
+The bazis Application/Kernel layer: one application lifecycle on top of DI.
+Borrowed practices: .NET Generic Host (two-phase builder, lifetime, shutdown timeout),
+Spring (startup phases, events, profiles), Symfony (explicit Kernel, module config schema),
+NestJS (granular lifecycle hooks, global modules), all without reflection and AOT-compatible.
+
+Contracts of the lifecycle and configuration fixes: [partial passport](MODULE.md).
+
+## Entry point
+
+- `Bazis.ts`: the facade: the `Bazis.run(AppModule)` one-liner and `Bazis.createBuilder(...)` for fine tuning.
+- `KernelBuilder.ts`: the mutable configuration phase; `build()` returns an immutable `Kernel`.
+- `Kernel.ts`: the kernel: `start()/stop()/run()` with one shared operation for repeated calls, signals, unhandled errors, exit codes, startup report. The startup deadline also covers started callbacks and events.
+
+## Lifecycle
+
+- `LifecycleCoordinator.ts`: boot/shutdown order: options fail-fast → `onInit` → hosted services by phase → `onBootstrap`; shutdown in reverse order with `shutdownTimeout`; rollback when startup fails.
+- `ApplicationLifetime.ts`: injectable lifetime: `onStarted/onStopping/onStopped` + programmatic `stop(exitCode)`.
+- `lifecycleHooks.ts`: the `LIFECYCLE_HOOK` token (enumerable) + `addLifecycleHook`.
+- `Environment.ts`: the environment (`development|production|test`) from `BAZIS_ENV`/`NODE_ENV`, the `debug` flag.
+- `SupervisedHostedService.ts`: retry with exponential backoff; passes the startup signal and stops retrying on cancellation.
+- `logging/ConsoleLogger.ts`: the standard structured logger; fields are
+  redacted through `bazis/library/redaction` by default. Raw fields are
+  allowed only with an explicit `redaction: false` for trusted local
+  diagnostics.
+
+## Configuration (`config/`)
+
+- `Configuration.ts`: an own snapshot of the flat config (`db.host` → string), typed getters, `loadConfiguration`.
+- `defineConfig.ts`: an immutable declaration with environment overrides, a separate `resolve(environment?, configuration?)` and the `token` DI token. One declaration is used in several kernels.
+- `ConfigRegistry.ts`: one validated view of a declaration per kernel; `get(definition)` returns the same object as DI by `definition.token`.
+- `sources.ts`: sources: `memorySource`, `envSource` (`BAZIS_DB__HOST` → `db.host`), `argsSource` (`--db.host=x`), `jsonFileSource` (a file next to the binary).
+- `addConfigOptions.ts`: `configOptions(token, { bind, validate })`: validated module options read from `Configuration`; the kernel validates them all at startup with one error.
+- `Secret.ts`: a secret with redaction: `toString/toJSON/inspect` print `***`, the value is available only through `reveal()`.
+
+The [per-kernel configuration architecture](../../../../docs/architecture/MODULE_ARCHITECTURE.md#kernel-config-isolation)
+is implemented: the declaration is shared and immutable, while the environment and
+the computed values belong to each kernel. The temporary ban on reusing a declaration
+is lifted. A declaration's direct `get/has` are meant for standalone code; `ensureValid`
+no longer switches their environment. Contracts and checks are in the
+[passport](MODULE.md#config-isolation-decision) and the [config description](config/README.md).
+
+## Events (`events/`)
+
+- `EventToken.ts`: typed events without reflection (`createEventToken<T>`).
+- `EventBus.ts`: a bus on top of DI (`resolveAllKeyed`); handler errors are aggregated. An optional `signal` stops waiting and stops starting the remaining handlers, including the `isolate` mode. User code that is already running stays responsible for its effects.
+- `onEvent.ts`: subscription from a module (`providers: [onEvent(EVT, handler)]`) or a collection.
+- `kernelEvents.ts`: `APPLICATION_STARTED`, `APPLICATION_STOPPING`.
+
+## Health (`health/`)
+
+- `HealthCheckContracts.ts`: the `HEALTH_CHECK` token (enumerable), report types.
+- `HealthService.ts`: the aggregator: a failed check is marked unhealthy without failing the report; `kernel.health()`.
+
+## Errors (`errors/`)
+
+- `KernelError` (base), `StartupAbortedError`, `StartupTimeoutError`, `ShutdownTimeoutError`, `ConfigKeyMissingError`. When cleanup after a failed start times out, `ShutdownTimeoutError.cause` keeps the original error.
+
+## Principles
+
+- Two-phase: nothing can be registered after `build()`.
+- Kernel infrastructure (`Environment`, `Configuration`, `ApplicationLifetime`, `EventBus`, `HealthService`) is a global module: any module gets it without an import.
+- No reflection and no dynamic import; the config lives outside the binary.
+- The kernel works only at startup/shutdown; there are no runtime hot paths in it.
+- External code imports the kernel through `bazis/core/kernel`.

package/core/kernel/SupervisedHostedService.ts

@@ -0,0 +1,147 @@
+import type { HostedService, HostedServicePlanValidator } from "../di";
+import { validateHostedServicePlan, registerHostedServiceWrapper, type HostedServicePlanAdmission } from "../di/extensions/hosted-service";
+import { awaitAbortable } from "./internal/awaitAbortable";
+import { reportDiagnosticFailure } from "./internal/reportDiagnosticFailure";
+
+export interface RestartPolicy {
+  /** Total start attempts, including the first one. Default: 3. */
+  readonly maxAttempts?: number;
+  /** Initial pause before a retry; doubles each attempt. Default: 100ms. */
+  readonly backoffMs?: number;
+  /** Backoff cap. Default: 5000ms. */
+  readonly maxBackoffMs?: number;
+  /** Startup phase override; defaults to the concrete service's phase. */
+  readonly phase?: number;
+  /** Diagnostic notification before a retry; throws/returned rejections cannot stop recovery. */
+  readonly onRetry?: (attempt: number, error: unknown) => void;
+}
+
+/**
+ * Restart-with-backoff supervisor for hosted service startup: a transient
+ * start failure (DB not up yet, port busy) retries with exponential backoff
+ * instead of killing the whole application.
+ * The factory only constructs a service: hosts call it during plan admission.
+ * Validators see the complete plan of real service instances before startup.
+ */
+export class SupervisedHostedService implements HostedService {
+  public get phase(): number { return this.admittedPhase ?? this.policy.phase ?? 0; }
+  public readonly planValidator: HostedServicePlanValidator = {
+    validate: (plan, signal) => validateHostedServicePlan(plan, signal),
+  };
+  private inner?: HostedService;
+  private prepared?: HostedService;
+  private admission?: HostedServicePlanAdmission;
+  private admittedPhase?: number;
+  private starting?: Promise<void>;
+  private stopping?: Promise<void>;
+
+  public constructor(
+    private readonly factory: () => HostedService,
+    private readonly policy: RestartPolicy = {},
+  ) {
+    registerHostedServiceWrapper(this, {
+      explicitPhase: policy.phase,
+      prepare: () => this.inner ?? (this.prepared ??= this.factory()),
+      bind: admission => { this.admission = admission; this.admittedPhase = admission.phase; },
+    });
+  }
+
+  public start(signal?: AbortSignal): Promise<void> {
+    if (this.stopping) {
+      const stopping = this.stopping;
+      return stopping.then(() => {
+        if (this.stopping === stopping) this.stopping = undefined;
+        return this.start(signal);
+      });
+    }
+    return this.starting ??= Promise.resolve().then(() => this.startAttempts(signal));
+  }
+
+  private async startAttempts(signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted();
+    if (!this.admission) await validateHostedServicePlan([this], signal);
+    signal?.throwIfAborted();
+    const maxAttempts = Math.max(1, this.policy.maxAttempts ?? 3);
+    const initialBackoff = this.policy.backoffMs ?? 100;
+    const maxBackoff = this.policy.maxBackoffMs ?? 5_000;
+
+    for (let attempt = 1; ; attempt += 1) {
+      signal?.throwIfAborted();
+      const service = this.prepared!;
+      this.prepared = undefined;
+      try {
+        signal?.throwIfAborted();
+        await service.start(signal);
+        signal?.throwIfAborted();
+        this.inner = service;
+        return;
+      } catch (error) {
+        try {
+          await service.stop();
+        } catch (cleanupError) {
+          this.inner = service;
+          throw new SupervisedCleanupError(error, cleanupError);
+        }
+        signal?.throwIfAborted();
+        if (error instanceof SupervisedCleanupError) throw error;
+        if (attempt >= maxAttempts) {
+          throw error;
+        }
+        this.notifyRetry(attempt, error);
+        const backoff = Math.min(initialBackoff * 2 ** (attempt - 1), maxBackoff);
+        await waitForRetry(backoff, signal);
+        signal?.throwIfAborted();
+        // Construction and admission errors are configuration failures, not
+        // another started attempt. Never retry an unvalidated replacement.
+        const candidate = this.factory();
+        await this.admission!.replace(candidate, signal);
+        signal?.throwIfAborted();
+        this.prepared = candidate;
+      }
+    }
+  }
+
+  private notifyRetry(attempt: number, error: unknown): void {
+    try {
+      void Promise.resolve(this.policy.onRetry?.(attempt, error))
+        .catch(() => reportDiagnosticFailure("supervised.onRetry"));
+    } catch {
+      reportDiagnosticFailure("supervised.onRetry");
+    }
+  }
+
+  public stop(): Promise<void> {
+    return this.stopping ??= this.stopInner();
+  }
+
+  private async stopInner(): Promise<void> {
+    await this.starting?.catch(() => {});
+    if (this.inner) {
+      await this.inner.stop();
+      this.inner = undefined;
+    }
+    this.prepared = undefined;
+    this.admission = undefined;
+    this.starting = undefined;
+  }
+}
+
+class SupervisedCleanupError extends AggregateError {
+  public constructor(startError: unknown, cleanupError: unknown) {
+    super([startError, cleanupError], "Supervised service startup and cleanup failed; retry is unsafe.", { cause: startError });
+    this.name = "SupervisedCleanupError";
+  }
+}
+
+async function waitForRetry(backoffMs: number, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await awaitAbortable(new Promise<void>(resolve => { timer = setTimeout(resolve, backoffMs); }), signal);
+  } finally { if (timer !== undefined) clearTimeout(timer); }
+}
+
+/** Sugar for `addHostedService(services, supervised(() => new Worker(), { ... }))`. */
+export function supervised(factory: () => HostedService, policy?: RestartPolicy): () => HostedService {
+  return () => new SupervisedHostedService(factory, policy);
+}

package/core/kernel/config/ConfigRegistry.ts

@@ -0,0 +1,48 @@
+import { DI, type ProviderDefinition } from "../../di";
+import { KernelError } from "../errors";
+import type { EnvironmentName } from "../types";
+import type { Configuration } from "./Configuration";
+import { isConfigDefinition, type AppConfig, type ConfigDefinition, type ConfigInspection, type ConfigView, type ValidatableConfig } from "./defineConfig";
+
+/** One immutable set of resolved module configurations per kernel. */
+export class ConfigRegistry {
+  private readonly views = new Map<ValidatableConfig, AppConfig<object>>();
+  public readonly providers: readonly ProviderDefinition[];
+
+  public constructor(configs: readonly ValidatableConfig[], environment: EnvironmentName, source: Configuration) {
+    const providers: ProviderDefinition[] = [];
+    const issues: string[] = [];
+    const errors: unknown[] = [];
+    for (const config of new Set(configs)) {
+      try {
+        if (isConfigDefinition(config)) {
+          const view = config.resolve(environment, source);
+          this.views.set(config, view);
+          providers.push(DI.singleton(DI.valueProvider(config.token, view)));
+        } else {
+          const view = config.resolve?.(environment, source) ?? config;
+          view.ensureValid(environment);
+          this.views.set(config, view as AppConfig<object>);
+        }
+      } catch (error) {
+        errors.push(error);
+        issues.push(error instanceof Error ? error.message : "Configuration validation failed.");
+      }
+    }
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, `Configuration validation failed:\n${issues.join("\n")}`);
+    this.providers = Object.freeze(providers);
+  }
+
+  public get<T extends object>(config: ConfigDefinition<T>): ConfigView<T>;
+  public get<T extends object>(config: AppConfig<T>): AppConfig<T>;
+  public get<T extends object>(config: AppConfig<T>): AppConfig<T> {
+    const view = this.views.get(config);
+    if (view === undefined) throw new KernelError("Configuration was not declared in this kernel's module graph.");
+    return view as AppConfig<T>;
+  }
+
+  public inspect(): readonly ConfigInspection[] {
+    return Object.freeze([...this.views.values()].flatMap(view => "inspect" in view ? (view as ConfigView<object>).inspect() : []));
+  }
+}