bazis 0.96.1

package/core/orm/databaseConnector.ts

@@ -0,0 +1,108 @@
+import { InfraError, reader, requireValue, postgresConnectionOptions, type InfraConnector, type PostgresConfigShape } from "../infra";
+import type { AppConfig, ConfigRegistry } from "../kernel";
+import { postgres, type DatabaseProvider, type PostgresServerTimeouts } from "../../library/orm";
+import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
+
+/** Connect before the servers and ORM features: open the database before anyone asks for it. */
+const DATABASE_PHASE = -110;
+
+/** Optional operational fields belong to the ORM connection contract. */
+export interface PostgresOrmConfigShape extends PostgresConfigShape {
+  readonly max?: number;
+  readonly connectionTimeout?: number;
+  readonly idleTimeout?: number;
+  readonly maxLifetime?: number;
+  readonly tls?: "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+  readonly tlsCa?: string;
+  readonly operationTimeoutMs?: number;
+  readonly cancellationTimeoutMs?: number;
+  readonly cancellationMode?: "server" | "close";
+  readonly maxPendingOperations?: number;
+  readonly statementTimeoutMs?: number;
+  readonly lockTimeoutMs?: number;
+  readonly idleInTransactionTimeoutMs?: number;
+  readonly transactionTimeoutMs?: number;
+}
+
+function buildPostgresProvider<T extends PostgresOrmConfigShape>(config: AppConfig<T>, configs?: ConfigRegistry): DatabaseProvider {
+  const c = reader(config, configs);
+  const optional = (key: string) => c.has(key) ? c.get(key) : undefined;
+  const number = (key: string, allowZero = false): number | undefined => {
+    const value = optional(key);
+    if (value === undefined) return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < (allowZero ? 0 : 1) || value > 2_147_483_647) throw new InfraError(`Invalid PostgreSQL configuration field: ${key}.`);
+    return value;
+  };
+  const hostname = requireValue(c.get("host"), "host", "database");
+  const options: Record<string, unknown> = { ...postgresConnectionOptions(config, configs) };
+  for (const key of ["max", "connectionTimeout", "idleTimeout", "maxLifetime"] as const) {
+    const value = number(key, key === "idleTimeout" || key === "maxLifetime");
+    if (value !== undefined) options[key] = value;
+  }
+  // defineConfig keys are always present, so an empty tlsCa means "no additional CA".
+  const tls = optional("tls"), configuredCa = optional("tlsCa"), ca = configuredCa === "" ? undefined : configuredCa;
+  if (tls !== undefined) {
+    if (typeof tls !== "string" || !["disable", "allow", "prefer", "require", "verify-ca", "verify-full"].includes(tls)) throw new InfraError("Invalid PostgreSQL configuration field: tls.");
+    options.tls = tls;
+  }
+  if (ca !== undefined) {
+    if (typeof ca !== "string" || !ca.trim() || tls !== "verify-full") throw new InfraError("tlsCa requires a non-empty certificate and tls=verify-full.");
+    options.tls = { ca, serverName: hostname, rejectUnauthorized: true };
+  }
+  const serverTimeouts: Record<string, number> = {};
+  const cancellationMode = optional("cancellationMode");
+  if (cancellationMode !== undefined && cancellationMode !== "server" && cancellationMode !== "close") throw new InfraError("Invalid PostgreSQL configuration field: cancellationMode.");
+  for (const key of ["statementTimeoutMs", "lockTimeoutMs", "idleInTransactionTimeoutMs", "transactionTimeoutMs"] as const) {
+    const value = number(key); if (value !== undefined) serverTimeouts[key] = value;
+  }
+  return postgres({ options, operationTimeoutMs: number("operationTimeoutMs"), cancellationTimeoutMs: number("cancellationTimeoutMs"), cancellationMode, maxPendingOperations: number("maxPendingOperations"), serverTimeouts: serverTimeouts as PostgresServerTimeouts });
+}
+
+/**
+ * Database connection connector for `@Infra`: the bridge between infrastructure
+ * and the ORM (the EF Core model: the connection comes from outside, the ORM
+ * works on top of it).
+ *
+ * Takes the whole PostgreSQL subsystem config (`dbConfig` from
+ * `defineConfig("db", ...)`) and reads the declared keys itself. Publishes a
+ * `DatabaseProvider` under the shared {@link DATABASE_PROVIDER} token, opens it
+ * at start (phase −110, before ORM features and servers) and closes it at shutdown.
+ *
+ * Migrations stay with the feature (they depend on the model): `ormBazis: { context,
+ * entities, ensureCreated }` without `provider` works on top of this shared connection.
+ *
+ * ```ts
+ * export const dbConfig = defineConfig("db", {
+ *   default: { host: "db", port: 5432, database: "app", username: "postgres", password: secret("dev") },
+ * });
+ * @Infra({ db: ormBazisConnect(dbConfig) })
+ * export class AppInfra {}
+ *
+ * @Module({ ormBazis: { context: UsersDbContext, entities: [User], ensureCreated: true } })
+ * export class UsersModule {}  // consumer of the shared DATABASE_PROVIDER
+ * ```
+ */
+export function ormBazisConnect<T extends PostgresOrmConfigShape>(config: AppConfig<T>): InfraConnector<DatabaseProvider>;
+export function ormBazisConnect(
+  config: AppConfig<PostgresOrmConfigShape>,
+): InfraConnector<DatabaseProvider> {
+  return {
+    token: DATABASE_PROVIDER,
+    config,
+    phase: DATABASE_PHASE,
+    create(configs) {
+      return buildPostgresProvider(config, configs);
+    },
+    async connect(provider, signal) {
+      if (!(await provider.ping(signal))) {
+        throw new InfraError('Infra connector "database": postgres is not reachable.');
+      }
+    },
+    async dispose(provider) {
+      await provider.close();
+    },
+    healthCheck(provider, signal) {
+      return provider.ping(signal);
+    },
+  };
+}

package/core/orm/encapsulationHook.ts

@@ -0,0 +1,19 @@
+import { registerNamedDependencyEncapsulationHook } from "../di/module/encapsulationHooks";
+import { IRepository } from "./repository";
+
+let registered = false;
+
+/** Allows closed `IRepository<Entity>` named deps when the module exports open generic `IRepository`. */
+export function registerRepositoryEncapsulationHook(): void {
+  if (registered) {
+    return;
+  }
+  registered = true;
+
+  registerNamedDependencyEncapsulationHook(({ depName, familiesVisible }) => {
+    if (depName.startsWith("IRepository<") && familiesVisible.has(IRepository.id)) {
+      return true;
+    }
+    return undefined;
+  });
+}

package/core/orm/index.ts

@@ -0,0 +1,95 @@
+// Integration of the ORM with the framework (DI/kernel). The pure engine is
+// `@/library/orm`; this layer adds the DI module, tokens, lifecycle
+// and health check. The engine is re-exported in full for convenience.
+export * from "../../library/orm";
+
+export { ormModule, type OrmModuleConfig } from "./ormModule";
+export { ormBazisConnect, type PostgresOrmConfigShape } from "./databaseConnector";
+export { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
+export { OrmConnectionLifecycle, OrmLifecycle, OrmProviderReadyLifecycle } from "./OrmLifecycle";
+export { IRepository, repositoryFor } from "./repository";
+export { registerRepositories } from "./registerRepositories";
+export { paginate, type PageResult } from "./listQuery";
+
+import { registerModuleMetadataExpander, type BazisModuleRef } from "../di";
+import { OrmOwnedStoreAdmissionError, type DbContext } from "../../library/orm";
+import { registerRepositoryEncapsulationHook } from "./encapsulationHook";
+import { ormModule, type OrmModuleConfig } from "./ormModule";
+import { readOwnedStoreRegistration, revalidateOwnedStoreRegistration } from "./ownedStoreContributions";
+
+registerRepositoryEncapsulationHook();
+
+/**
+ * Declarative `ormBazis` key for `@Module(...)`: a shorthand for
+ * `imports: [ormModule(config)]`. Accepts one config or an array. The DI core
+ * stays unaware of the ORM — this expander is registered here (side effect of
+ * importing `@/core/orm`) and run by `createContainer`.
+ *
+ * ```ts
+ * @Module({ ormBazis: { context: UsersDbContext, entities: [User], ensureCreated: true } })
+ * class UsersModule {}
+ * ```
+ */
+// Augment the declaring file, not the "../di" re-export: re-export targets
+// depend on program file order and silently stop merging in some projects.
+declare module "../di/module/types/BazisModule" {
+  interface BazisModuleMetadata {
+    readonly ormBazis?: OrmModuleConfig<DbContext> | readonly OrmModuleConfig<DbContext>[];
+  }
+}
+
+interface CachedDeclarativeOrm {
+  readonly config: object;
+  readonly module: BazisModuleRef;
+  readonly registration?: ReturnType<typeof readOwnedStoreRegistration>;
+  readonly context: unknown;
+  readonly entities: readonly unknown[] | undefined;
+  readonly ownedStore: unknown;
+  readonly ensureCreated: boolean | undefined;
+  readonly migrateOnStart: boolean | undefined;
+  readonly runMigrationsOnStart: boolean | undefined;
+  readonly migrations: readonly unknown[] | undefined;
+}
+const declarativeCache = new WeakMap<object, readonly CachedDeclarativeOrm[]>();
+
+function declaredOwnedStore(config: OrmModuleConfig<DbContext>): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(config, "ownedStore");
+  if (descriptor === undefined) return undefined;
+  if (!("value" in descriptor)) throw new OrmOwnedStoreAdmissionError("ORM_OWNED_STORE_IDENTITY_MISMATCH", "ORM_OWNED_STORE_IDENTITY_MISMATCH");
+  return descriptor.value;
+}
+
+registerModuleMetadataExpander((metadata): readonly BazisModuleRef[] => {
+  const orm = (metadata as { ormBazis?: OrmModuleConfig<DbContext> | readonly OrmModuleConfig<DbContext>[] }).ormBazis;
+  if (orm === undefined) {
+    return [];
+  }
+  const configs = Array.isArray(orm) ? orm : [orm];
+  const owned = configs.map((config) => declaredOwnedStore(config));
+  const cached = declarativeCache.get(metadata as object);
+  if (cached) {
+    if (cached.length !== configs.length || cached.some((entry, index) => entry.config !== configs[index])) throw new OrmOwnedStoreAdmissionError("ORM_OWNED_STORE_IDENTITY_MISMATCH", "ORM_OWNED_STORE_IDENTITY_MISMATCH");
+    for (let index = 0; index < cached.length; index += 1) {
+      const entry = cached[index]!;
+      const config = configs[index]!;
+      if (config.context !== entry.context
+        || config.entities?.length !== entry.entities?.length
+        || config.entities?.some((entity: unknown, entityIndex: number) => entity !== entry.entities?.[entityIndex])
+        || owned[index] !== entry.ownedStore
+        || config.ensureCreated !== entry.ensureCreated
+        || config.migrateOnStart !== entry.migrateOnStart
+        || config.runMigrationsOnStart !== entry.runMigrationsOnStart
+        || config.migrations !== entry.migrations) {
+        throw new OrmOwnedStoreAdmissionError("ORM_OWNED_STORE_IDENTITY_MISMATCH", "ORM_OWNED_STORE_IDENTITY_MISMATCH");
+      }
+      if (entry.registration) revalidateOwnedStoreRegistration(entry.registration);
+    }
+    return cached.map((entry) => entry.module);
+  }
+  const created = configs.map((config, index) => {
+    const module = ormModule(config);
+    return Object.freeze({ config: config as object, module, registration: readOwnedStoreRegistration(module), context: config.context, entities: config.entities === undefined ? undefined : Object.freeze([...config.entities]), ownedStore: owned[index], ensureCreated: config.ensureCreated, migrateOnStart: config.migrateOnStart, runMigrationsOnStart: config.runMigrationsOnStart, migrations: config.migrations });
+  });
+  if (owned.some((value) => value !== undefined)) declarativeCache.set(metadata as object, Object.freeze(created));
+  return created.map((entry) => entry.module);
+});

package/core/orm/listQuery.ts

@@ -0,0 +1,198 @@
+import type { FilterRule, ListQuery } from "../../library/jsonapi";
+import type { ColumnType, EntityModel, EntityQuery, FieldSelector, Operand, Predicate } from "../../library/orm";
+import { OrmError } from "../../library/orm";
+
+const MAX_ORM_PAGE_SIZE = 1_000;
+const MAX_ORM_PAGE_OFFSET = 10_000_000;
+
+/** Result page: the items and the total number of records (with filters applied). */
+export interface PageResult<T> {
+  readonly items: readonly T[];
+  readonly total: number;
+}
+
+/**
+ * Applies a universal {@link ListQuery} (filters/sorting/paging) to an ORM query
+ * and returns a page of items together with the total number of records.
+ *
+ * `total` is computed by a separate `count()` with the same filters but without
+ * paging, so the client can build page navigation.
+ *
+ * Field names in the `ListQuery` were already validated against the allow list
+ * by the parser (`parseListQuery`), so they are applied directly here. The ORM
+ * engine always parameterizes SQL: user values never get into the SQL text.
+ *
+ * ```ts
+ * const { items, total } = await paginate(repo.query(), query);
+ * return buildListDocument(items, query, total, { basePath: "/api/users" });
+ * ```
+ */
+export async function paginate<T extends object, R = T>(
+  query: EntityQuery<T, R>,
+  list: ListQuery,
+): Promise<PageResult<R>> {
+  validatePage(list);
+  const model = queryModel(query);
+  const hasFilter = list.filters.length > 0 || list.or.length > 0;
+  const filtered = hasFilter ? query.where((entity) => buildWhere(entity, list, model)) : query;
+
+  const total = await filtered.count();
+
+  let paged = filtered;
+  for (const sort of list.sort) {
+    paged =
+      sort.dir === "desc"
+        ? paged.orderByDescending((entity) => fieldOperand(entity, sort.field))
+        : paged.orderBy((entity) => fieldOperand(entity, sort.field));
+  }
+
+  // Pagination without every primary-key component as a tiebreaker is
+  // unstable: rows with equal sort values can move between pages.  `key` is
+  // deliberately absent for composite models, so the ordered `primaryKey`
+  // metadata is the authority here.
+  for (const keyField of primaryKeyFields(model)) {
+    if (!list.sort.some((sort) => sort.field === keyField)) {
+      paged = paged.orderBy((entity) => fieldOperand(entity, keyField));
+    }
+  }
+
+  const items = await paged.skip(list.page.offset).take(list.page.limit).toList();
+  return { items, total };
+}
+
+function validatePage(list: ListQuery): void {
+  const { limit, offset, number, size } = list.page;
+  if (!Number.isSafeInteger(limit) || limit <= 0 || limit > MAX_ORM_PAGE_SIZE) {
+    throw new OrmError(`List page limit must be an integer between 1 and ${MAX_ORM_PAGE_SIZE}.`);
+  }
+  if (!Number.isSafeInteger(size) || size <= 0 || size > MAX_ORM_PAGE_SIZE) {
+    throw new OrmError(`List page size must be an integer between 1 and ${MAX_ORM_PAGE_SIZE}.`);
+  }
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_ORM_PAGE_OFFSET) {
+    throw new OrmError(`List page offset must be an integer between 0 and ${MAX_ORM_PAGE_OFFSET}.`);
+  }
+  if (!Number.isSafeInteger(number) || number <= 0) {
+    throw new OrmError("List page number must be a positive integer.");
+  }
+}
+
+function queryModel<T extends object, R>(query: EntityQuery<T, R>): EntityModel {
+  // EntityQuery intentionally keeps its model protected. The core integration
+  // reads the stable metadata contract for typed filters and deterministic order.
+  return (query as unknown as { readonly model: EntityModel }).model;
+}
+
+function primaryKeyFields(model: EntityModel): readonly string[] {
+  if (model.key.length === 0) {
+    throw new OrmError("List pagination requires an entity primary key.");
+  }
+  return model.key.map((property) => property.propertyName);
+}
+
+/**
+ * Builds the final predicate: `filters` (AND) and OR groups (`(g0) OR (g1) OR ...`)
+ * joined with AND: `filters AND (g0 OR g1 ...)`.
+ * Called only when there is at least one condition (see `hasFilter` in paginate).
+ */
+function buildWhere<T extends object>(entity: FieldSelector<T>, list: ListQuery, model: EntityModel): Predicate {
+  const base = combineAnd(entity, list.filters, model);
+
+  let orCombined: Predicate | undefined;
+  for (const group of list.or) {
+    const groupPredicate = combineAnd(entity, group, model);
+    if (groupPredicate === undefined) {
+      continue;
+    }
+    orCombined = orCombined === undefined ? groupPredicate : orCombined.or(groupPredicate);
+  }
+
+  if (base === undefined) {
+    return orCombined as Predicate;
+  }
+  return orCombined === undefined ? base : base.and(orCombined);
+}
+
+function combineAnd<T extends object>(
+  entity: FieldSelector<T>,
+  rules: readonly FilterRule[],
+  model: EntityModel,
+): Predicate | undefined {
+  let combined: Predicate | undefined;
+  for (const rule of rules) {
+    const predicate = applyRule(fieldOperand(entity, rule.field), rule, model.propertyByName(rule.field)?.type);
+    combined = combined === undefined ? predicate : combined.and(predicate);
+  }
+  return combined;
+}
+
+function applyRule(operand: Operand, rule: FilterRule, type: ColumnType | undefined): Predicate {
+  switch (rule.op) {
+    case "eq":
+      return operand.eq(coerce(asScalar(rule.value), type));
+    case "ne":
+      return operand.ne(coerce(asScalar(rule.value), type));
+    case "gt":
+      return operand.gt(coerce(asScalar(rule.value), type));
+    case "gte":
+      return operand.gte(coerce(asScalar(rule.value), type));
+    case "lt":
+      return operand.lt(coerce(asScalar(rule.value), type));
+    case "lte":
+      return operand.lte(coerce(asScalar(rule.value), type));
+    case "like":
+      return operand.like(asScalar(rule.value));
+    case "contains":
+      return operand.contains(asScalar(rule.value));
+    case "startsWith":
+      return operand.startsWith(asScalar(rule.value));
+    case "endsWith":
+      return operand.endsWith(asScalar(rule.value));
+    case "in":
+      return operand.in(asArray(rule.value).map((value) => coerce(value, type)));
+    case "nin":
+      return operand.in(asArray(rule.value).map((value) => coerce(value, type))).not();
+    case "isNull":
+      return operand.isNull();
+    case "isNotNull":
+      return operand.isNotNull();
+  }
+}
+
+function fieldOperand<T extends object>(entity: FieldSelector<T>, field: string): Operand {
+  return (entity as Record<string, Operand>)[field] as Operand;
+}
+
+const NUMERIC = /^-?\d+(\.\d+)?$/;
+const INTEGER = /^-?\d+$/;
+
+/**
+ * The type is chosen by the column: text values must not go through Number, or
+ * leading zeros and precision are lost. The converter and dialect apply later.
+ */
+function coerce(value: string, type: ColumnType | undefined): string | number | bigint | boolean {
+  if (type !== "integer" && type !== "real" && type !== "boolean") {
+    return value;
+  }
+  if (type === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  }
+  if (value !== "" && NUMERIC.test(value)) {
+    const numeric = Number(value);
+    if (type === "integer" && INTEGER.test(value) && !Number.isSafeInteger(numeric)) {
+      return BigInt(value);
+    }
+    if (Number.isFinite(numeric)) {
+      return numeric;
+    }
+  }
+  return value;
+}
+
+function asScalar(value: string | readonly string[]): string {
+  return Array.isArray(value) ? (value[0] ?? "") : (value as string);
+}
+
+function asArray(value: string | readonly string[]): string[] {
+  return Array.isArray(value) ? [...value] : [value as string];
+}

package/core/orm/ormModule.ts

@@ -0,0 +1,173 @@
+import { DI, HOSTED_SERVICE, singletonValue, type BazisModuleRef, type ProviderDefinition } from "../di";
+import {
+  OrmError,
+  type DatabaseProvider,
+  type DbContext,
+  DbContextOptions,
+  type DbContextOptionsConfig,
+  type Migration,
+} from "../../library/orm";
+import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
+import { IRepository } from "./repository";
+import { registerRepositories } from "./registerRepositories";
+import {
+  buildOrmHealthCheck,
+  buildOrmHealthCheckFromToken,
+  buildOrmModuleProviders,
+  type OrmBuildConfig,
+} from "./buildOrmProviders";
+import { OrmConnectionLifecycle } from "./OrmLifecycle";
+import { attachOrmGraphContribution, attachOwnedStoreRegistration } from "./ownedStoreContributions";
+
+type EntityClass = new () => object;
+type ContextClass<TContext extends DbContext> = new (options: DbContextOptions) => TContext;
+
+/**
+ * The single ORM registration shape. One function, three scenarios depending
+ * on which fields are passed:
+ *
+ * - **Connection** (`{ provider }`, no `context`): a global module that
+ *   publishes the shared {@link DATABASE_PROVIDER}. Created once at the root.
+ * - **Feature** (`{ context, entities }`, no `provider`): a context and its
+ *   repositories connected to the shared {@link DATABASE_PROVIDER}.
+ * - **Standalone** (`{ context, entities, provider }`): a context with its own
+ *   provider (tests, isolated modules).
+ *
+ * The provider is a value (the ORM `postgres(...)`), not a nested module.
+ */
+export interface OrmModuleConfig<TContext extends DbContext> {
+  /** Context class (a DbContext subclass). Omitted in the "connection" mode. */
+  readonly context?: ContextClass<TContext>;
+  /** Entities mapped by this context. */
+  readonly entities?: readonly EntityClass[];
+  /**
+   * Database provider value (`postgres(...)`). Without it the context connects
+   * to the shared {@link DATABASE_PROVIDER} (feature mode).
+   */
+  readonly provider?: DatabaseProvider;
+  /** Validate entities before SaveChanges (default true). */
+  readonly validateOnSave?: boolean;
+  /** Create the schema at start (`CREATE TABLE IF NOT EXISTS`). Default false. */
+  readonly ensureCreated?: boolean;
+  /**
+   * Run the additive auto-migration at start for all context entities.
+   * Only the module decides how the schema is created. Default false.
+   */
+  readonly migrateOnStart?: boolean;
+  /** Versioned migrations (a compile-safe array). History is kept in `__BazisMigrations`. */
+  readonly migrations?: readonly Migration[];
+  /** Run `migrateVersioned` at start (default false). */
+  readonly runMigrationsOnStart?: boolean;
+  /** Retries on transient database errors in SaveChanges. */
+  readonly executionStrategy?: DbContextOptionsConfig["executionStrategy"];
+  /**
+   * Register the connection health check. Default: on for the "connection" and
+   * "standalone" modes, off for feature (the root turns it on).
+   */
+  readonly healthCheck?: boolean;
+  /** Register scoped `IRepository<T>` for the entities (default true). */
+  readonly registerRepositories?: boolean;
+  /** Modules holding the context's dependencies. */
+  readonly imports?: readonly BazisModuleRef[];
+  /** Approved owned PostgreSQL store descriptor; admission is owned by the core lifecycle. */
+  readonly ownedStore?: import("../../library/orm").OrmOwnedStoreDefinitionV1;
+}
+
+function defineFeatureOrmModule<TContext extends DbContext>(
+  config: OrmBuildConfig<TContext>,
+  providers: ProviderDefinition[],
+): BazisModuleRef {
+  const withRepositories = config.registerRepositories !== false;
+
+  return {
+    imports: config.imports,
+    providers,
+    exports: withRepositories ? [config.context, IRepository] : [config.context],
+    configure: withRepositories
+      ? (di) => registerRepositories(di, config.context, config.entities ?? [])
+      : undefined,
+  };
+}
+
+function defineConnectionModule(provider: DatabaseProvider, healthCheck: boolean): BazisModuleRef {
+  const providers: ProviderDefinition[] = [
+    singletonValue(DATABASE_PROVIDER, provider),
+    DI.singleton(
+      DI.factoryProvider(
+        HOSTED_SERVICE,
+        [DATABASE_PROVIDER],
+        (registered: DatabaseProvider) => new OrmConnectionLifecycle(registered),
+      ),
+    ),
+  ];
+  if (healthCheck) {
+    providers.push(buildOrmHealthCheck(provider));
+  }
+
+  return { global: true, providers, exports: [DATABASE_PROVIDER] };
+}
+
+/** Single ORM registration entry point (see {@link OrmModuleConfig}). */
+export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TContext>): BazisModuleRef {
+  if (config.ownedStore !== undefined) {
+    if (!config.context || !config.entities || config.entities.length === 0 || config.provider || config.ensureCreated || config.migrateOnStart || config.runMigrationsOnStart || config.migrations !== undefined) {
+      throw new OrmError("ORM owned store requires a context and entities and cannot compose startup schema or migration authority.");
+    }
+    // Provider factories outlive this call. Keep their context/entity view
+    // registration-local so a caller cannot mutate the descriptor afterwards
+    // and silently change the runtime graph behind its owned receipt.
+    const buildConfig = Object.freeze({ ...config, context: config.context, entities: Object.freeze([...config.entities]) }) as OrmBuildConfig<TContext>;
+    const module = defineFeatureOrmModule(buildConfig, buildOrmModuleProviders(buildConfig, DATABASE_PROVIDER));
+    attachOwnedStoreRegistration(module, buildConfig.context, buildConfig.entities ?? [], config.ownedStore);
+    return module;
+  }
+  if (config.ensureCreated && (config.migrateOnStart || config.runMigrationsOnStart || (config.migrations?.length ?? 0) > 0)) throw new OrmError("ensureCreated is mutually exclusive with ORM migration startup options.");
+  if (config.ensureCreated && config.provider?.name === "postgres" && config.context) throw new OrmError("PostgreSQL ensureCreated requires the shared DATABASE_PROVIDER from @Infra.");
+  // "Connection" mode: a provider only, no context.
+  if (!config.context) {
+    if (!config.provider) {
+      throw new OrmError("ormModule requires a `provider` (connection) and/or a `context` (feature).");
+    }
+    return defineConnectionModule(config.provider, config.healthCheck !== false);
+  }
+
+  const buildConfig = config as OrmBuildConfig<TContext>;
+
+  // Standalone: a context with its own provider value.
+  if (config.provider) {
+    // Only the static DbContextOptions are built eagerly here. Schema lifecycle
+    // flags and migrations are read at resolve time, because an owned-store graph
+    // may replace them with a container-local snapshot.
+    const standaloneOptions = new DbContextOptions({
+      provider: config.provider,
+      entities: config.entities ?? [],
+      validateOnSave: config.validateOnSave,
+      executionStrategy: config.executionStrategy,
+    });
+    const registration = Object.freeze({});
+    const providers = buildOrmModuleProviders(buildConfig, config.provider, registration, standaloneOptions);
+    if (buildConfig.healthCheck !== false) {
+      providers.push(buildOrmHealthCheck(config.provider));
+    }
+    const module = defineFeatureOrmModule(buildConfig, providers);
+    attachOrmGraphContribution(module, buildConfig.context, buildConfig.entities ?? [], config, registration);
+    return module;
+  }
+
+  // Feature: a context on the shared DATABASE_PROVIDER.
+  // The source config remains the ordinary-only compatibility path. When an
+  // owned store is present in this container, the graph compiler snapshots it
+  // once and the factories below resolve that same opaque registration view.
+  const registration = Object.freeze({});
+  const providers = buildOrmModuleProviders(buildConfig, DATABASE_PROVIDER, registration);
+  if (config.healthCheck === true) {
+    providers.push(buildOrmHealthCheckFromToken(DATABASE_PROVIDER));
+  }
+  const module = defineFeatureOrmModule(buildConfig, providers);
+  // `registration` is deliberately per ormModule call, not a token or public
+  // identity. It links this factory to its container-local graph snapshot.
+  attachOrmGraphContribution(module, buildConfig.context, buildConfig.entities ?? [], config, registration);
+  return module;
+}
+
+export { DATABASE_PROVIDER };