bazis 0.96.1

package/core/kernel/logging/ConsoleLogger.ts

@@ -0,0 +1,68 @@
+import { redactSensitive, type SensitiveRedactionOptions } from "../../../library/redaction";
+import type { LogFields, LogLevel, Logger } from "./Logger";
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+const LEVEL_SINK: Record<LogLevel, (message: string) => void> = {
+  debug: (m) => console.debug(m),
+  info: (m) => console.info(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+};
+
+export interface ConsoleLoggerOptions {
+  /** Minimum level emitted. Default: "info". */
+  readonly minLevel?: LogLevel;
+  /** Prefix tag, e.g. the app name. */
+  readonly name?: string;
+  /** Structured fields are redacted by default; pass false only for trusted local debugging. */
+  readonly redaction?: SensitiveRedactionOptions | false;
+}
+
+function formatFields(fields: LogFields | undefined, redaction: SensitiveRedactionOptions | false): string {
+  if (!fields) {
+    return "";
+  }
+  try {
+    if (Object.keys(fields).length === 0) return "";
+    return ` ${JSON.stringify(redaction === false ? fields : redactSensitive(fields, redaction))}`;
+  } catch {
+    return " [Unserializable log fields]";
+  }
+}
+
+/** Default {@link Logger}: single-line, level-filtered output to the console. */
+export class ConsoleLogger implements Logger {
+  private readonly threshold: number;
+  private readonly prefix: string;
+  private readonly redaction: SensitiveRedactionOptions | false;
+
+  public constructor(options: ConsoleLoggerOptions = {}) {
+    this.threshold = LEVEL_ORDER[options.minLevel ?? "info"];
+    this.prefix = options.name ? `[${options.name}] ` : "";
+    this.redaction = options.redaction ?? {};
+  }
+
+  public debug(message: string, fields?: LogFields): void {
+    this.write("debug", message, fields);
+  }
+
+  public info(message: string, fields?: LogFields): void {
+    this.write("info", message, fields);
+  }
+
+  public warn(message: string, fields?: LogFields): void {
+    this.write("warn", message, fields);
+  }
+
+  public error(message: string, fields?: LogFields): void {
+    this.write("error", message, fields);
+  }
+
+  private write(level: LogLevel, message: string, fields?: LogFields): void {
+    if (LEVEL_ORDER[level] < this.threshold) {
+      return;
+    }
+    LEVEL_SINK[level](`${this.prefix}${level}: ${message}${formatFields(fields, this.redaction)}`);
+  }
+}

package/core/kernel/logging/Logger.ts

@@ -0,0 +1,22 @@
+import { createToken } from "../../di";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/** Structured context attached to a log line. */
+export interface LogFields {
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Minimal structured logging port. Inject via {@link LOGGER}; the kernel
+ * registers a {@link ConsoleLogger} by default (override with
+ * `Bazis.createBuilder(...).useLogger(...)`).
+ */
+export interface Logger {
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+}
+
+export const LOGGER = createToken<Logger>("Logger");

package/core/kernel/types/ConfigSource.ts

@@ -0,0 +1,9 @@
+/**
+ * A configuration source produces a flat map of dot-separated keys to string
+ * values (e.g. "db.host" -> "localhost"). Later sources override earlier ones.
+ */
+export interface ConfigSource {
+  /** Shown in diagnostics and error messages. */
+  readonly description: string;
+  load(): Record<string, string> | Promise<Record<string, string>>;
+}

package/core/kernel/types/EnvironmentName.ts

@@ -0,0 +1 @@
+export type EnvironmentName = "development" | "production" | "test";

package/core/kernel/types/KernelOptions.ts

@@ -0,0 +1,23 @@
+import type { EnvironmentName } from "./EnvironmentName";
+
+/** What the kernel does with unhandledRejection / uncaughtException. */
+export type UnhandledErrorPolicy = "shutdown" | "none";
+
+export interface KernelOptions {
+  /** Overrides BAZIS_ENV / NODE_ENV detection. */
+  readonly environment?: EnvironmentName;
+  /** Overrides the debug flag (default: true everywhere except production). */
+  readonly debug?: boolean;
+  /** Graceful shutdown budget: integer 0..2147483647ms. Default: 10000ms; 0 disables the limit. */
+  readonly shutdownTimeoutMs?: number;
+  /** Whole startup budget, including notifications: integer 0..2147483647ms. Default: 30000ms; 0 disables the limit. */
+  readonly startupTimeoutMs?: number;
+  /** Signals that trigger graceful shutdown. Default: SIGINT, SIGTERM. The built kernel snapshots unique values. */
+  readonly signals?: readonly NodeJS.Signals[];
+  /** Default: "shutdown" — an unhandled error triggers graceful stop with exit code 1. */
+  readonly unhandledErrorPolicy?: UnhandledErrorPolicy;
+  /** Default: true — the DI graph is fully validated at build. */
+  readonly validateOnBuild?: boolean;
+  /** Startup report in the console. Default: only outside production. */
+  readonly startupReport?: boolean;
+}

package/core/kernel/types/LifecycleHook.ts

@@ -0,0 +1,18 @@
+/**
+ * Granular lifecycle hooks (NestJS-style), discovered without reflection:
+ * register implementations under the LIFECYCLE_HOOK token (enumerable).
+ *
+ * Order: hooks run in module registration order (imports are loaded before
+ * the importing module, so the order is topological by the import graph).
+ * Shutdown hooks run in reverse.
+ */
+export interface LifecycleHook {
+  /** Before hosted services start (resources, caches, migrations). */
+  onInit?(): void | Promise<void>;
+  /** After every hosted service has started. */
+  onBootstrap?(): void | Promise<void>;
+  /** Graceful shutdown began; hosted services are already stopped. */
+  onShutdown?(signal?: string): void | Promise<void>;
+  /** Final cleanup right before the container is disposed. */
+  onDestroy?(): void | Promise<void>;
+}

package/core/kernel/types/index.ts

@@ -0,0 +1,4 @@
+export type { ConfigSource } from "./ConfigSource";
+export type { EnvironmentName } from "./EnvironmentName";
+export type { KernelOptions, UnhandledErrorPolicy } from "./KernelOptions";
+export type { LifecycleHook } from "./LifecycleHook";

package/core/orm/DATABASE_PROVIDER.ts

@@ -0,0 +1,5 @@
+import { createToken } from "../di";
+import type { DatabaseProvider } from "../../library/orm";
+
+/** Shared database connection published by the connection mode of `ormModule({ provider })`. */
+export const DATABASE_PROVIDER = createToken<DatabaseProvider>("DatabaseProvider");

package/core/orm/OrmHostedPlan.validator.ts

@@ -0,0 +1,55 @@
+import type { HostedService, HostedServicePlanValidator } from "../di";
+import { SchemaAdmissionError } from "../../library/orm";
+import { isOrmProviderLifecycle, isStrictSchemaPrerequisiteLifecycle } from "./strictSchemaHostedIdentity";
+
+/** Stateless strategy shared by ORM lifecycles; it owns no connection or application state. */
+export const ormHostedPlanValidator: HostedServicePlanValidator = Object.freeze({ validate: validateOrmHostedPlan });
+
+/** ORM-owned admission rules. Runs before any hosted service starts. */
+function validateOrmHostedPlan(services: readonly HostedService[]): void {
+  const owned = services.filter((service) => (service as { __bazisOrmOwnedStoreAdmission?: unknown }).__bazisOrmOwnedStoreAdmission === true);
+  for (const service of owned) {
+    if ((service.phase ?? 0) !== -105) throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "ORM owned-store admission has an invalid hosted phase.");
+    if (!services.some((candidate) => isOrmProviderLifecycle(candidate) && (candidate.phase ?? 0) === -110)) throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "ORM owned-store admission requires a provider lifecycle at phase -110.");
+  }
+  if (owned.length !== 0) {
+    for (const service of services) {
+      const framework = isOrmProviderLifecycle(service)
+        || (service as { __bazisOrmOwnedStoreAdmission?: unknown }).__bazisOrmOwnedStoreAdmission === true
+        || (service as { __bazisOrmLegacyLifecycle?: unknown }).__bazisOrmLegacyLifecycle === true
+        || isStrictSchemaPrerequisiteLifecycle(service);
+      if (!framework && (service.phase ?? 0) < 0) throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Application hosted services must use phase 0 or later with ORM owned-store admission.");
+    }
+  }
+  const strict = services.filter((service): service is HostedService & { readonly __bazisSchemaAdmission: { readonly unit: readonly string[]; readonly tables: readonly string[]; readonly foreignKeys: readonly { readonly source: string; readonly target: string }[] } } =>
+    (service as { __bazisSchemaAdmission?: unknown }).__bazisSchemaAdmission !== undefined,
+  );
+  if (strict.length === 0) return;
+  const owners = new Set<string>();
+  for (const service of strict) {
+    if ((service.phase ?? 0) !== -105) throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Schema admission has an invalid hosted phase.");
+    for (const table of service.__bazisSchemaAdmission.tables) { if (owners.has(table)) throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", "Schema admission table ownership conflicts."); owners.add(table); }
+    const unit = new Set(service.__bazisSchemaAdmission.unit);
+    for (const foreignKey of service.__bazisSchemaAdmission.foreignKeys) {
+      if (!unit.has(foreignKey.source) || !unit.has(foreignKey.target)) {
+        throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", "Schema admission foreign keys must target the same explicit unit.");
+      }
+    }
+  }
+  if (!services.some((service) => isOrmProviderLifecycle(service) && (service.phase ?? 0) === -110)) {
+    throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Schema admission requires a provider lifecycle at phase -110.");
+  }
+  for (const service of services) {
+    if ((service as { __bazisLegacySchemaAuthority?: unknown }).__bazisLegacySchemaAuthority === true) {
+      throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Schema admission and legacy ORM schema authority cannot be composed together.");
+    }
+    const framework = isOrmProviderLifecycle(service)
+      || isStrictSchemaPrerequisiteLifecycle(service)
+      || (service as { __bazisOrmLegacyLifecycle?: unknown }).__bazisOrmLegacyLifecycle === true
+      || (service as { __bazisSchemaAdmission?: unknown }).__bazisSchemaAdmission !== undefined
+      || (service as { __bazisOrmOwnedStoreAdmission?: unknown }).__bazisOrmOwnedStoreAdmission === true;
+    if (!framework && (service.phase ?? 0) < 0) {
+      throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Application hosted services must use phase 0 or later with schema admission.");
+    }
+  }
+}

package/core/orm/OrmLifecycle.ts

@@ -0,0 +1,146 @@
+import { ormHostedPlanValidator } from "./OrmHostedPlan.validator";
+import type { HostedService } from "../di";
+import { DatabaseFacade, type DbContextOptions, type Migration } from "../../library/orm";
+import { compileExpectedSchema } from "../../library/orm/Schema/ExpectedSchema";
+
+/**
+ * ORM lifecycle hosted service: at start it (optionally) creates the schema or
+ * runs the auto-migration; at shutdown it closes the connection/pool.
+ * Starts early (negative phase) so the database is ready before the servers.
+ */
+export class OrmLifecycle implements HostedService {
+  readonly planValidator = ormHostedPlanValidator;
+  readonly phase: number;
+  /** Internal hosted-plan marker; public hosted services never receive it. */
+  readonly __bazisOrmLegacyLifecycle = true;
+  /**
+   * Internal hosted-plan marker: this lifecycle changes the schema at phase -100
+   * without exact admission (`ensureCreated` on a non-PostgreSQL provider,
+   * `migrateOnStart` or startup migrations). The hosted-plan validator rejects
+   * it in a container that also uses exact schema admission.
+   */
+  readonly __bazisLegacySchemaAuthority: boolean;
+  /** Internal hosted-plan marker: tables and foreign keys of the phase -105 exact `ensureCreated` admission on PostgreSQL. */
+  readonly __bazisSchemaAdmission?: {
+    readonly unit: readonly string[];
+    readonly tables: readonly string[];
+    readonly foreignKeys: readonly { readonly source: string; readonly target: string }[];
+  };
+  private connectionClosed = false;
+  private closePromise?: Promise<void>;
+
+  constructor(
+    private readonly options: DbContextOptions,
+    private readonly ensureCreated: boolean,
+    private readonly migrateOnStart: boolean,
+    private readonly migrations: readonly Migration[] = [],
+    private readonly runMigrationsOnStart: boolean = false,
+    /**
+     * Whether this lifecycle owns the connection. `false` for the feature mode on
+     * top of the shared {@link DATABASE_PROVIDER}: the infrastructure owns the
+     * connection (the connection module / `@Infra` connector), and the feature
+     * must not close it at shutdown, or the shared pool would be closed twice.
+     */
+    private readonly ownsConnection: boolean = true,
+  ) {
+    this.phase = ensureCreated && options.provider.name === "postgres" ? -105 : -100;
+    this.__bazisLegacySchemaAuthority = this.phase === -100 && (ensureCreated || migrateOnStart || (runMigrationsOnStart && migrations.length > 0));
+    if (this.phase === -105) {
+      const expected = compileExpectedSchema(options.model);
+      const tables = Object.freeze(expected.tables.map((table) => `${table.schema}.${table.table}`));
+      this.__bazisSchemaAdmission = Object.freeze({
+        unit: tables,
+        tables,
+        foreignKeys: Object.freeze(expected.tables.flatMap((table) =>
+          table.foreignKeys.map((foreignKey) => Object.freeze({
+            source: `${table.schema}.${table.table}`,
+            target: `${foreignKey.target.schema}.${foreignKey.target.table}`,
+          })),
+        )),
+      });
+    }
+  }
+
+  async start(): Promise<void> {
+    const database = new DatabaseFacade(this.options.provider, this.options.model);
+    try {
+      if (this.ensureCreated) {
+        await database.ensureCreated();
+      }
+      if (this.migrateOnStart) {
+        const result = await database.migrate();
+        if (result.applied > 0) {
+          console.info(`[orm:migrate] applied ${result.applied} operation(s): ${result.operations.join(", ")}`);
+        }
+        for (const warning of result.warnings) {
+          console.warn(`[orm:migrate] ${warning}`);
+        }
+      }
+      if (this.runMigrationsOnStart && this.migrations.length > 0) {
+        const result = await database.migrateVersioned(this.migrations);
+        if (result.applied.length > 0) {
+          console.info(`[orm:migrations] applied: ${result.applied.join(", ")}`);
+        }
+      }
+    } catch (error) {
+      if (!this.ownsConnection) {
+        throw error;
+      }
+      try {
+        await this.closeOwnedConnection();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "ORM startup failed and connection rollback also failed.");
+      }
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.ownsConnection) {
+      await this.closeOwnedConnection();
+    }
+  }
+
+  private async closeOwnedConnection(): Promise<void> {
+    if (this.connectionClosed) {
+      return;
+    }
+    this.closePromise ??= this.options.provider.close().then(() => {
+      this.connectionClosed = true;
+    });
+    await this.closePromise;
+  }
+}
+
+/**
+ * Occupies the phase -110 provider slot that exact schema admission requires:
+ * it runs before the phase -105 admissions and the phase -100 ORM lifecycle,
+ * without taking connection ownership.
+ */
+export class OrmProviderReadyLifecycle implements HostedService {
+  readonly planValidator = ormHostedPlanValidator;
+  public readonly phase = -110;
+  readonly __bazisOrmProviderReady = true;
+  start(): void {}
+  stop(): void {}
+}
+
+/** Owns a provider published by connection-only `ormModule({ provider })`. */
+export class OrmConnectionLifecycle implements HostedService {
+  readonly planValidator = ormHostedPlanValidator;
+  public readonly phase = -110;
+  readonly __bazisOrmProviderReady = true;
+  private stopPromise?: Promise<void>;
+
+  public constructor(private readonly provider: DbContextOptions["provider"]) {}
+
+  public start(): void {
+    // DatabaseProvider has no separate connect contract; providers initialize
+    // lazily on first operation. This lifecycle exists to establish ownership.
+  }
+
+  public stop(): Promise<void> {
+    this.stopPromise ??= this.provider.close();
+    return this.stopPromise;
+  }
+}

package/core/orm/OrmOwnedStoreLifecycle.ts

@@ -0,0 +1,96 @@
+import { ormHostedPlanValidator } from "./OrmHostedPlan.validator";
+import type { HostedService } from "../di";
+import type { DatabaseProvider } from "../../library/orm";
+import { admitOwnedStoresV1, discardOwnedStoreAdmissionV1, publishOwnedStoreAdmissionV1, type OwnedStoreLeaseV1 } from "../../library/orm/Schema/OwnedStoreAdmission";
+import { OrmOwnedStoreAdmissionError } from "../../library/orm";
+import type { OwnedStoreRegistration } from "./ownedStoreContributions";
+import { preparedOwnedStoreRegistration } from "./ownedStoreContributions";
+
+const plans = new WeakMap<object, OrmOwnedStoreLifecycle>();
+
+export interface OwnedStorePlanHealth { check(): Promise<{ healthy: boolean; details?: string }>; }
+
+/** Container-local owner of the receipt and leases. It never owns the provider. */
+export class OrmOwnedStoreLifecycle implements HostedService {
+  readonly planValidator = ormHostedPlanValidator;
+  public readonly phase = -105;
+  public readonly __bazisOrmOwnedStoreAdmission = true;
+  private state: "idle" | "starting" | "ready" | "failed" | "closing" | "stopped" = "idle";
+  private startPromise?: Promise<void>;
+  private readonly controller = new AbortController();
+  private leases: readonly OwnedStoreLeaseV1[] = Object.freeze([]);
+
+  public constructor(private readonly provider: DatabaseProvider, private readonly registrations: readonly OwnedStoreRegistration[]) {}
+
+  public async start(signal?: AbortSignal): Promise<void> {
+    if (this.state === "ready") return;
+    if (this.state === "stopped" || this.state === "closing") throw new OrmOwnedStoreAdmissionError("ORM_OWNED_STORE_LOCK_UNAVAILABLE", "ORM_OWNED_STORE_LOCK_UNAVAILABLE");
+    this.startPromise ??= this.admit(signal);
+    return this.startPromise;
+  }
+
+  public async stop(): Promise<void> {
+    if (this.state === "idle" || this.state === "stopped") return;
+    this.state = "closing";
+    this.controller.abort();
+    try { await this.startPromise; } catch { /* a failed admission owns no lease */ }
+    for (const lease of this.leases) lease.revoke();
+    this.leases = Object.freeze([]);
+    this.state = "stopped";
+  }
+
+  public readonly health: OwnedStorePlanHealth = Object.freeze({
+    check: async () => this.state === "ready" && this.leases.length === this.registrations.length && this.leases.every((lease) => lease.active)
+      ? { healthy: true }
+      : { healthy: false, details: "ORM_OWNED_STORE_NOT_READY" },
+  });
+
+  private async admit(external: AbortSignal | undefined): Promise<void> {
+    this.state = "starting";
+    const signal = combineSignals(this.controller.signal, external);
+    try {
+      if (signal.aborted) throw unavailable();
+      const receipt = await admitOwnedStoresV1(this.provider, { stores: this.registrations.map(preparedOwnedStoreRegistration), signal });
+      if (signal.aborted || this.controller.signal.aborted) {
+        discardOwnedStoreAdmissionV1(receipt);
+        throw unavailable();
+      }
+      // Publication and ready are deliberately adjacent: no await can leave a
+      // committed receipt visible to an aborted graph.
+      const leases = publishOwnedStoreAdmissionV1(this.provider, receipt);
+      if (signal.aborted || this.controller.signal.aborted) {
+        for (const lease of leases) lease.revoke();
+        throw unavailable();
+      }
+      this.leases = leases;
+      this.state = "ready";
+    } catch (error) {
+      if (!this.controller.signal.aborted) this.state = "failed";
+      throw error;
+    }
+  }
+}
+
+/** One container owns one whole-graph admission plan, regardless of module count. */
+export function ownedStoreLifecycleFor(container: object, provider: DatabaseProvider, registrations: readonly OwnedStoreRegistration[]): OrmOwnedStoreLifecycle {
+  let plan = plans.get(container);
+  if (!plan) { plan = new OrmOwnedStoreLifecycle(provider, registrations); plans.set(container, plan); }
+  return plan;
+}
+
+/** Health must not activate a provider merely to observe a plan that has not started. */
+export function ownedStoreLifecycleHealthFor(container: object): OwnedStorePlanHealth | undefined {
+  return plans.get(container)?.health;
+}
+
+function unavailable(): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError("ORM_OWNED_STORE_LOCK_UNAVAILABLE", "ORM_OWNED_STORE_LOCK_UNAVAILABLE"); }
+
+function combineSignals(local: AbortSignal, external: AbortSignal | undefined): AbortSignal {
+  if (!external) return local;
+  if (local.aborted || external.aborted) { const controller = new AbortController(); controller.abort(); return controller.signal; }
+  const controller = new AbortController();
+  const abort = (): void => controller.abort();
+  local.addEventListener("abort", abort, { once: true });
+  external.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}

package/core/orm/buildOrmProviders.ts

@@ -0,0 +1,152 @@
+import { DI, HOSTED_SERVICE, type InjectionToken, type ModuleOwnedContributionSnapshot, type ProviderDefinition } from "../di";
+import { HEALTH_CHECK } from "../kernel";
+import { DbContextOptions, type DatabaseProvider, type DbContext } from "../../library/orm";
+import { OrmLifecycle } from "./OrmLifecycle";
+import { ownedStoreLifecycleFor, ownedStoreLifecycleHealthFor } from "./OrmOwnedStoreLifecycle";
+import { effectiveOrmModuleConfig, ownedStoreRegistrations } from "./ownedStoreContributions";
+import { SERVICE_PROVIDER } from "../di";
+import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
+import type { OrmModuleConfig } from "./ormModule";
+
+type EntityClass = new () => object;
+type ContextClass<TContext extends DbContext> = new (options: DbContextOptions) => TContext;
+
+type OrmBuildConfig<TContext extends DbContext> = OrmModuleConfig<TContext> & {
+  readonly context: ContextClass<TContext>;
+};
+
+function createContextOptions<TContext extends DbContext>(
+  config: OrmBuildConfig<TContext>,
+  provider: DatabaseProvider,
+): DbContextOptions {
+  return new DbContextOptions({
+    provider,
+    entities: config.entities ?? [],
+    validateOnSave: config.validateOnSave,
+    executionStrategy: config.executionStrategy,
+  });
+}
+
+function createOrmLifecycle<TContext extends DbContext>(
+  config: OrmBuildConfig<TContext>,
+  options: DbContextOptions,
+  ownsConnection: boolean,
+): OrmLifecycle {
+  return new OrmLifecycle(
+    options,
+    config.ensureCreated === true,
+    config.migrateOnStart === true,
+    config.migrations ?? [],
+    config.runMigrationsOnStart === true,
+    ownsConnection,
+  );
+}
+
+
+function isInjectionToken(value: unknown): value is InjectionToken<DatabaseProvider> {
+  return typeof value === "object" && value !== null && "id" in value && "description" in value;
+}
+
+function effectiveConfigFor<TContext extends DbContext>(
+  serviceProvider: unknown,
+  registrationIdentity: object | undefined,
+  fallback: OrmBuildConfig<TContext>,
+): OrmBuildConfig<TContext> {
+  const container = serviceProvider as import("../di").DiContainer;
+  const snapshot = {
+    getProviderContributions: container.getModuleOwnedProviderContributions.bind(container),
+    getMetadataContributions: container.getModuleOwnedMetadataContributions.bind(container),
+  } as unknown as ModuleOwnedContributionSnapshot;
+  ownedStoreRegistrations(snapshot);
+  return effectiveOrmModuleConfig(snapshot, registrationIdentity, fallback);
+}
+
+export function buildOrmModuleProviders<TContext extends DbContext>(
+  config: OrmBuildConfig<TContext>,
+  providerOrToken: DatabaseProvider | InjectionToken<DatabaseProvider>,
+  registrationIdentity?: object,
+  optionsAtModuleCall?: DbContextOptions,
+): ProviderDefinition[] {
+  if (isInjectionToken(providerOrToken)) {
+    const token = providerOrToken;
+    const providers: ProviderDefinition[] = [
+      DI.scoped(
+        DI.factoryProvider(config.context, [token, SERVICE_PROVIDER] as const, (provider: DatabaseProvider, serviceProvider) => {
+          const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
+          return new current.context(createContextOptions(current, provider));
+        }),
+      ),
+      DI.singleton(
+        DI.factoryProvider(HOSTED_SERVICE, [token, SERVICE_PROVIDER] as const, (provider: DatabaseProvider, serviceProvider) => {
+          const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
+          // Feature mode: the connection is shared (DATABASE_PROVIDER) and owned by
+          // the infrastructure; only ensureCreated/migrations here, no close.
+          if (current.ownedStore !== undefined) {
+            const container = serviceProvider as import("../di").DiContainer;
+            const records = ownedStoreRegistrations({
+              getProviderContributions: (channel) => container.getModuleOwnedProviderContributions(channel),
+              getMetadataContributions: (channel) => container.getModuleOwnedMetadataContributions(channel),
+            });
+            return ownedStoreLifecycleFor(container, provider, records);
+          }
+          return createOrmLifecycle(current, createContextOptions(current, provider), false);
+        }),
+      ),
+    ];
+    if (config.ownedStore !== undefined) {
+      providers.push(DI.singleton(DI.factoryProvider(HEALTH_CHECK, [SERVICE_PROVIDER], (serviceProvider) => {
+        const container = serviceProvider as unknown as import("../di").DiContainer;
+        return { name: `orm-owned-store:${config.ownedStore!.storeKey}`, check: () => ownedStoreLifecycleHealthFor(container)?.check() ?? Promise.resolve({ healthy: false, details: "ORM_OWNED_STORE_NOT_READY" }) };
+      })));
+    }
+    return providers;
+  }
+
+  const provider = providerOrToken;
+  const providers: ProviderDefinition[] = [
+    DI.scoped(DI.factoryProvider(config.context, [SERVICE_PROVIDER], (serviceProvider) => {
+      const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
+      const context = current === config ? config.context : current.context;
+      return new context(current === config && optionsAtModuleCall !== undefined ? optionsAtModuleCall : createContextOptions(current, provider));
+    })),
+    // Standalone mode: the context owns its provider and closes it.
+    DI.singleton(DI.factoryProvider(HOSTED_SERVICE, [SERVICE_PROVIDER], (serviceProvider) => {
+      const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
+      return createOrmLifecycle(current, current === config && optionsAtModuleCall !== undefined ? optionsAtModuleCall : createContextOptions(current, provider), true);
+    })),
+  ];
+  return providers;
+}
+
+/** Connection health check for a concrete provider value. */
+export function buildOrmHealthCheck(provider: DatabaseProvider): ProviderDefinition {
+  return DI.singleton(
+    DI.factoryProvider(HEALTH_CHECK, [], () => ({
+      name: `database:${provider.name}`,
+      check: () => checkProviderHealth(provider),
+    })),
+  );
+}
+
+/** Connection health check through the shared {@link DATABASE_PROVIDER} (feature mode). */
+export function buildOrmHealthCheckFromToken(token: InjectionToken<DatabaseProvider>): ProviderDefinition {
+  return DI.singleton(
+    DI.factoryProvider(HEALTH_CHECK, [token], (provider: DatabaseProvider) => ({
+      name: `database:${provider.name}`,
+      check: () => checkProviderHealth(provider),
+    })),
+  );
+}
+
+async function checkProviderHealth(provider: DatabaseProvider): Promise<{ healthy: boolean; details?: string }> {
+  const connected = await provider.ping();
+  const diagnostics = provider.diagnostics?.() ?? [];
+  const hasError = diagnostics.some((diagnostic) => diagnostic.severity === "error");
+  const details = diagnostics.map((diagnostic) => `${diagnostic.severity}:${diagnostic.code}: ${diagnostic.message}`);
+  return {
+    healthy: connected && !hasError,
+    ...(details.length === 0 ? {} : { details: details.join("; ") }),
+  };
+}
+
+export type { ContextClass, EntityClass, OrmBuildConfig };