bazis 0.136.0 → 0.138.0

package/core/infra/connectors/postgres.ts

@@ -30,7 +30,9 @@ export interface PostgresConfigShape {
   readonly maxLifetime?: number;
 }
 
-export type PostgresSslMode = "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+/** The TLS modes of a PostgreSQL connection, for `configEnum(POSTGRES_SSL_MODES, "disable")`. */
+export const POSTGRES_SSL_MODES = ["disable", "allow", "prefer", "require", "verify-ca", "verify-full"] as const;
+export type PostgresSslMode = typeof POSTGRES_SSL_MODES[number];
 export interface PostgresConnectorOptions {
   readonly token?: InjectionToken<SQL>;
   /** Maximum pool drain before closing connections. Default 1000ms; 0 closes immediately. */
@@ -47,7 +49,7 @@ export function postgresConnectionOptions(config: AppConfig<PostgresConfigShape>
     return value;
   };
   const tls = c.has("tls") ? c.get("tls") : undefined;
-  if (tls !== undefined && !["disable", "allow", "prefer", "require", "verify-ca", "verify-full"].includes(String(tls))) throw new InfraError("postgres tls is invalid");
+  if (tls !== undefined && !(POSTGRES_SSL_MODES as readonly string[]).includes(String(tls))) throw new InfraError("postgres tls is invalid");
   return {
     hostname: requireValue(c.get("host"), "host", "postgres"),
     port: integer("port", 1, 65535),

package/core/infra/connectors/redis.ts

@@ -7,7 +7,8 @@ import {
   connectionCache,
   type DistributedCacheStores,
 } from "../../cache";
-import { createToken, DI, type InjectionToken, type ProviderDefinition } from "../../di";
+import { createToken, type InjectionToken, type ProviderDefinition } from "../../di";
+import { DI } from "../../di/lowLevel";
 import type { AppConfig, Secret } from "../../kernel";
 import { RedisDistributedCacheBackend, type RedisDistributedCacheTuning } from "../cache/RedisDistributedCacheBackend";
 import { reader, requireValue, settingNames } from "../connectorConfig";

package/core/infra/index.ts

@@ -10,7 +10,7 @@ export { reader, requireValue, settingNames, type ConfigReader } from "./connect
 export { codexAppServerConnect, ICodex } from "./connectors/codex";
 export { CodexError, RU_CODEX_MESSAGES, type CodexErrorCode, CODEX_MODEL_ID, CODEX_REASONING_EFFORT, type CodexClient, type CodexConfigShape, type CodexLogin, type CodexLoginMethod, type CodexModel, type CodexStatus, type CodexRunInput, type CodexChatMessage, type CodexTool, type CodexToolCall, type CodexToolResult } from "./connectors/codex/contracts";
 
-export { postgres, IPostgres, postgresConnectionOptions, type PostgresConfigShape, type PostgresSslMode, type PostgresConnectorOptions } from "./connectors/postgres";
+export { postgres, IPostgres, POSTGRES_SSL_MODES, postgresConnectionOptions, type PostgresConfigShape, type PostgresSslMode, type PostgresConnectorOptions } from "./connectors/postgres";
 export {
   redisConnect,
   IRedis,

package/core/kernel/KernelBuilder.ts

@@ -1,4 +1,5 @@
-import { DI, Global, Module, collectModuleConfigs, createContainer, type BazisModule, type BazisModuleRef, type ProviderDefinition } from "../di";
+import { Global, Module, collectModuleConfigs, createContainer, type BazisModule, type BazisModuleRef, type ProviderDefinition } from "../di";
+import { DI } from "../di/lowLevel";
 import { isBazisModuleClass } from "../di/module/Module";
 import { ApplicationLifetime } from "./ApplicationLifetime";
 import { Configuration, loadConfiguration } from "./config/Configuration";

package/core/kernel/config/ConfigRegistry.ts

@@ -1,4 +1,5 @@
-import { DI, type ProviderDefinition } from "../../di";
+import { type ProviderDefinition } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { KernelError } from "../errors";
 import type { EnvironmentName } from "../types";
 import type { Configuration } from "./Configuration";

package/core/kernel/config/addConfigOptions.ts

@@ -1,5 +1,6 @@
 import type { InjectionToken, Options, ProviderDefinition, ServiceCollection, ServiceResolver } from "../../di";
-import { DI, OPTIONS_STARTUP_VALIDATOR, OptionsValidationError } from "../../di";
+import { OPTIONS_STARTUP_VALIDATOR, OptionsValidationError } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { ConfigKeyMissingError } from "../errors";
 import { Configuration } from "./Configuration";
 

package/core/kernel/config/defineConfig.ts

@@ -15,7 +15,7 @@ registerNamedDependencyHint((name) => {
   const match = /^Config:(.+)$/.exec(name);
   if (!match) return undefined;
   const declaration = match[1] === "default" ? "defineConfig({ … })" : `defineConfig("${match[1]}", …)`;
-  return `The config ${declaration} is not declared in the application: add it to \`config\` of the module that uses it, or to runApp({ config }).`;
+  return `The config ${declaration} is not declared in the application: add it to \`config\` of the module that uses it, or to @App({ config }).`;
 });
 
 type Stand = "development" | "test" | "production";
@@ -38,14 +38,23 @@ export function configEnum<const V extends readonly [string | number, ...(string
   return declared;
 }
 const invalidEnums = new WeakMap<object, KernelError>();
-type Cell = Primitive | SecretSpec | ConfigEnum;
+export interface ConfigList { readonly __list: true; readonly default: readonly string[] }
+/**
+ * A list of strings: `readonly string[]` in the code, comma-separated in the
+ * environment (`BAZIS_TOOLS__HTTP__ALLOW=api.example.com,*.example.org`). Items
+ * are trimmed, empty ones are dropped.
+ */
+export function configList(defaultValue: readonly string[] = []): ConfigList {
+  return Object.freeze({ __list: true, default: Object.freeze([...defaultValue]) });
+}
+type Cell = Primitive | SecretSpec | ConfigEnum | ConfigList;
 type Defaults = Record<string, Cell>;
-export type ConfigValueType = Primitive | Secret;
+export type ConfigValueType = Primitive | Secret | readonly string[];
 export type ConfigShape = Record<string, ConfigValueType>;
-type Resolved<V> = V extends SecretSpec ? Secret : V extends ConfigEnum<infer E> ? E : V extends number ? number : V extends boolean ? boolean : string;
+type Resolved<V> = V extends SecretSpec ? Secret : V extends ConfigList ? readonly string[] : V extends ConfigEnum<infer E> ? E : V extends number ? number : V extends boolean ? boolean : string;
 type ResolveAll<D extends Defaults> = { [K in keyof D]: Resolved<D[K]> };
-type WidenCell<V> = V extends SecretSpec ? SecretSpec : V extends ConfigEnum<infer E> ? E : V extends number ? number : V extends boolean ? boolean : string;
-type CellFor<T> = [T] extends [Secret] ? SecretSpec : [T] extends [string] ? (string extends T ? string : ConfigEnum<T & string>) : [T] extends [number] ? (number extends T ? number : ConfigEnum<T & number>) : [T] extends [boolean] ? (boolean extends T ? boolean : never) : never;
+type WidenCell<V> = V extends SecretSpec ? SecretSpec : V extends ConfigList ? readonly string[] : V extends ConfigEnum<infer E> ? E : V extends number ? number : V extends boolean ? boolean : string;
+type CellFor<T> = [T] extends [Secret] ? SecretSpec : [T] extends [readonly string[]] ? ConfigList : [T] extends [string] ? (string extends T ? string : ConfigEnum<T & string>) : [T] extends [number] ? (number extends T ? number : ConfigEnum<T & number>) : [T] extends [boolean] ? (boolean extends T ? boolean : never) : never;
 type Declaration<T extends object> = { [K in keyof T]: CellFor<T[K]> };
 type OverrideFor<T> = T extends Secret ? SecretSpec : T;
 interface Rules<T extends object> {
@@ -76,18 +85,28 @@ export interface AppConfig<T extends object> extends ValidatableConfig {
 }
 export interface ConfigInspection {
   readonly key: string;
-  readonly type: "string" | "number" | "boolean" | "secret";
+  readonly type: "string" | "number" | "boolean" | "secret" | "list";
   readonly env: readonly string[];
   readonly source: string;
   readonly value: Primitive;
 }
-export interface ConfigView<T extends object> extends AppConfig<T> {
+/** The settings of one section as a service reads them. */
+export interface ResolvedConfigView<T extends object> extends AppConfig<T> {
   readonly environment: Stand;
   inspect(): readonly ConfigInspection[];
 }
-export interface ConfigDefinition<T extends object> extends AppConfig<T> {
-  readonly token: InjectionToken<ConfigView<T>>;
-  resolve(environment?: Stand, configuration?: Configuration): ConfigView<T>;
+/**
+ * The settings a service takes in its constructor. `T` is the declaration
+ * itself, `ConfigView<typeof mailConfig>`, so the settings are described once,
+ * by their defaults; or the shape of the settings, `ConfigView<MailConfig>`, for a
+ * declaration with an explicit type.
+ */
+export type ConfigView<T extends object> = ResolvedConfigView<T extends ConfigDefinition<infer Shape, string> ? Shape : T>;
+export interface ConfigDefinition<T extends object, P extends string = string> extends AppConfig<T> {
+  /** The name of the section: `mail`; `default` for a declaration without one. */
+  readonly prefix: P;
+  readonly token: InjectionToken<ResolvedConfigView<T>>;
+  resolve(environment?: Stand, configuration?: Configuration): ResolvedConfigView<T>;
 }
 const definitions = new WeakSet<object>();
 export function isConfigDefinition(config: ValidatableConfig): config is ConfigDefinition<object> {
@@ -118,8 +137,11 @@ function environmentNameProblem(name: string, claimed: ReadonlySet<string>): str
   return undefined;
 }
 
-function isSecret(cell: Cell): cell is SecretSpec { return typeof cell === "object" && cell !== null && "__secret" in cell; }
-function isEnum(cell: Cell): cell is ConfigEnum { return typeof cell === "object" && cell !== null && "__enum" in cell; }
+function isSecret(cell: unknown): cell is SecretSpec { return typeof cell === "object" && cell !== null && "__secret" in cell; }
+function isEnum(cell: unknown): cell is ConfigEnum { return typeof cell === "object" && cell !== null && "__enum" in cell; }
+function isList(cell: unknown): cell is ConfigList { return typeof cell === "object" && cell !== null && "__list" in cell; }
+/** `a, b,,c` → `["a", "b", "c"]`. */
+function listItems(raw: string): readonly string[] { return Object.freeze(raw.split(",").map((item) => item.trim()).filter((item) => item !== "")); }
 function copyCell(cell: Cell): Cell {
   if (isSecret(cell)) return secret(cell.default);
   if (isEnum(cell)) {
@@ -127,20 +149,27 @@ function copyCell(cell: Cell): Cell {
     if (problem !== undefined) throw problem;
     return Object.freeze({ ...cell, values: Object.freeze([...cell.values]) });
   }
+  if (isList(cell)) {
+    if (!Array.isArray(cell.default) || cell.default.some((item) => typeof item !== "string")) throw new KernelError("configList requires a list of strings.");
+    return configList(cell.default);
+  }
+  // A list in an environment section is written as it is read: `test: { hosts: ["a"] }`.
+  if (Array.isArray(cell)) return copyCell(configList(cell as readonly string[]));
   if (["string", "number", "boolean"].includes(typeof cell)) return cell;
-  throw new KernelError("Configuration supports only primitive values, secret() and configEnum().");
+  throw new KernelError("Configuration supports only primitive values, secret(), configEnum() and configList().");
 }
 function safeValue(key: string, value: ConfigValueType): Primitive {
-  if (value instanceof Secret || (typeof value === "string" && isSensitiveKey(key))) return "***";
-  if (typeof value !== "string") return value;
+  if (value instanceof Secret || ((typeof value === "string" || Array.isArray(value)) && isSensitiveKey(key))) return "***";
+  if (Array.isArray(value)) return value.join(", ");
+  if (typeof value !== "string") return value as Primitive;
   try {
     const url = new URL(value);
     if (url.username || url.password) { url.username = "***"; url.password = "***"; return redactSensitiveText(url.toString()); }
   } catch { /* Most strings are not URLs. */ }
   return redactSensitiveText(value);
 }
-export function defineConfig<const D extends Defaults>(schema: ConfigSchema<D>): ConfigDefinition<ResolveAll<D>>;
-export function defineConfig<const D extends Defaults>(prefix: string, schema: ConfigSchema<D>): ConfigDefinition<ResolveAll<D>>;
+export function defineConfig<const D extends Defaults>(schema: ConfigSchema<D>): ConfigDefinition<ResolveAll<D>, "default">;
+export function defineConfig<const P extends string, const D extends Defaults>(prefix: P, schema: ConfigSchema<D>): ConfigDefinition<ResolveAll<D>, P>;
 export function defineConfig<T extends object>(schema: SchemaFor<T>): ConfigDefinition<T>;
 export function defineConfig<T extends object>(prefix: string, schema: SchemaFor<T>): ConfigDefinition<T>;
 export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, maybeSchema?: ConfigSchema<Defaults>): ConfigDefinition<ConfigShape> {
@@ -157,6 +186,7 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
     // errors, instead of crashing the import of the file that declares it.
     const fail = (): never => { throw error; };
     definition = Object.freeze({
+      prefix: prefix || "default",
       token: Object.freeze(createToken<ConfigView<ConfigShape>>(`Config:${prefix || "default"}`)),
       resolve: fail,
       get: fail,
@@ -209,7 +239,7 @@ function createDefinition(prefix: string, input: ConfigSchema<Defaults>, declare
       const base = schema.default[key]!;
       const override = schema[environment]?.[key];
       const cell = override ?? base;
-      const type = isSecret(base) ? "secret" : isEnum(base) ? typeof base.default : typeof base;
+      const type = isSecret(base) ? "secret" : isList(base) ? "list" : isEnum(base) ? typeof base.default : typeof base;
       const candidates: { raw: string; source: string; priority: number; name: string }[] = [];
       for (const name of names.get(key)!) {
         const sourceKey = name.slice(ENV_PREFIX.length).toLowerCase().replaceAll("__", ".");
@@ -226,7 +256,7 @@ function createDefinition(prefix: string, input: ConfigSchema<Defaults>, declare
         const variables = [...new Set(winners.map(candidate => candidate.name))];
         issue(key, "conflict", `conflicting environment aliases: ${variables.join(" and ")} are set to different values; set only one`);
       }
-      const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
+      const raw: unknown = selected?.raw ?? (isSecret(cell) || isEnum(cell) || isList(cell) ? cell.default : cell);
       let value: ConfigValueType | undefined;
       if (type === "secret") {
         // secret("") reads like an empty default but would mean "required":
@@ -238,6 +268,11 @@ function createDefinition(prefix: string, input: ConfigSchema<Defaults>, declare
         // No "apiKey: …" in the hint: the console redaction would hide it.
         else if (environment === "production" && selected === undefined && override === undefined) issue(key, "development-secret", `production would use the development default secret from the code; set ${names.get(key)!.join(" or ")}, or declare ${key} in the production section`);
         else value = new Secret(raw);
+      } else if (type === "list") {
+        // From the environment a comma-separated string, from the code a list.
+        if (typeof raw === "string") value = listItems(raw);
+        else if (Array.isArray(raw) && (raw as unknown[]).every((item) => typeof item === "string")) value = Object.freeze([...(raw as string[])]);
+        else issue(key, "string", "expected a list of strings");
       } else if (type === "number") {
         const parsed = Number(raw);
         if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issue(key, "number", `expected a finite number${got(key, raw)}${source(key, selected)}`, from(selected));
@@ -273,6 +308,7 @@ function createDefinition(prefix: string, input: ConfigSchema<Defaults>, declare
     });
   };
   return Object.freeze({
+    prefix: prefix || "default",
     token: Object.freeze(createToken<ConfigView<ConfigShape>>(`Config:${prefix || "default"}`)),
     resolve,
     get: <K extends keyof ConfigShape>(key: K): ConfigShape[K] => resolve().get(key),

package/core/kernel/events/EventBus.ts

@@ -1,4 +1,5 @@
 import { createToken, type ServiceResolver } from "../../di";
+import { DI } from "../../di/lowLevel";
 import type { EventHandler, EventToken } from "./EventToken";
 import { awaitAbortable } from "../internal/awaitAbortable";
 

package/core/kernel/events/eventSubscribers.ts

@@ -1,5 +1,4 @@
 import {
-  DI,
   Module,
   singleton,
   type Class,
@@ -7,6 +6,7 @@ import {
   type ProviderDefinition,
   type ServiceResolver,
 } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { EVENT_HANDLER, type EventSubscription } from "./EventBus";
 import type { EventHandler, EventToken } from "./EventToken";
 

package/core/kernel/events/onEvent.ts

@@ -1,4 +1,5 @@
-import { DI, type ProviderDefinition, type ServiceCollection } from "../../di";
+import { type ProviderDefinition, type ServiceCollection } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { EVENT_HANDLER, type EventSubscription } from "./EventBus";
 import type { EventHandler, EventToken } from "./EventToken";
 

package/core/kernel/index.ts

@@ -16,12 +16,15 @@ export { Secret } from "./config/Secret";
 export {
   defineConfig,
   configEnum,
+  configList,
   secret,
   type AppConfig,
   type ConfigDefinition,
   type ConfigView,
+  type ResolvedConfigView,
   type ConfigInspection,
   type ConfigEnum,
+  type ConfigList,
   type ConfigSchema,
   type ConfigShape,
   type ConfigValueType,

package/core/orm/buildOrmProviders.ts

@@ -1,4 +1,6 @@
-import { DI, HOSTED_SERVICE, type InjectionToken, type ModuleOwnedContributionSnapshot, type ProviderDefinition, type ProviderDependencyList, type ServiceResolver } from "../di";
+import { HOSTED_SERVICE, type InjectionToken, type ModuleOwnedContributionSnapshot, type ProviderDefinition, type ProviderDependencyList, type ServiceResolver } from "../di";
+import { DI } from "../di/lowLevel";
+import { contextEntities } from "./contextEntities";
 import { getGeneratedClassDeps } from "../di/module/autoDeps";
 import { resolveDependencyList } from "../di/internal/resolveDependencyList";
 import { ConfigRegistry, HEALTH_CHECK, StartupReport } from "../kernel";
@@ -27,7 +29,7 @@ function createContextOptions<TContext extends DbContext>(
 ): DbContextOptions {
   return bindKeys(new DbContextOptions({
     provider,
-    entities: config.entities ?? [],
+    entities: contextEntities(config),
     validateOnSave: config.validateOnSave,
     executionStrategy: config.executionStrategy,
   }), serviceProvider);

package/core/orm/contextEntities.ts

@@ -0,0 +1,36 @@
+import { DbContext } from "../../library/orm";
+
+type EntityClass = new () => object;
+type ContextClass = abstract new (...parameters: never[]) => DbContext;
+
+/** The sets of a context class are read once: a class does not change. */
+const sets = new WeakMap<ContextClass, readonly EntityClass[] | Error>();
+
+function setsOf(context: ContextClass): readonly EntityClass[] | Error {
+  let known = sets.get(context);
+  if (known === undefined) {
+    try {
+      known = DbContext.entitiesOf(context as unknown as Parameters<typeof DbContext.entitiesOf>[0]);
+    } catch (error) {
+      known = error instanceof Error ? error : new Error(String(error));
+    }
+    sets.set(context, known);
+  }
+  return known;
+}
+
+/**
+ * The entities of a context: the listed ones in their order, then those of its
+ * sets (`this.set(...)`). A context whose constructor cannot run without its
+ * dependencies has only the listed ones, and with none listed that is an error.
+ */
+export function contextEntities(config: { readonly context?: ContextClass; readonly entities?: readonly EntityClass[] }): readonly EntityClass[] {
+  const listed = config.entities ?? [];
+  if (!config.context) return listed;
+  const ofSets = setsOf(config.context);
+  if (ofSets instanceof Error) {
+    if (listed.length === 0) throw ofSets;
+    return listed;
+  }
+  return ofSets.length === 0 ? listed : [...new Set([...listed, ...ofSets])];
+}

package/core/orm/databaseConnector.ts

@@ -1,7 +1,10 @@
 import { errorMessage, InfraError, reader, requireValue, postgresConnectionOptions, settingNames, type InfraConnector, type PostgresConfigShape } from "../infra";
-import { postgresAddress, serverVersion } from "../infra/connectors/postgres";
+import { POSTGRES_SSL_MODES, postgresAddress, serverVersion, type PostgresSslMode } from "../infra/connectors/postgres";
 import type { AppConfig, ConfigRegistry } from "../kernel";
 import { postgres, type DatabaseProvider, type PostgresServerTimeouts } from "../../library/orm";
+import { singletonValue } from "../di";
+import { HTTP_ERROR_MAPPER } from "../http/middlewareTokens";
+import { databaseHttpError } from "./databaseHttpError";
 import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
 
 /** Connect before the servers and ORM features: open the database before anyone asks for it. */
@@ -13,7 +16,7 @@ export interface PostgresOrmConfigShape extends PostgresConfigShape {
   readonly connectionTimeout?: number;
   readonly idleTimeout?: number;
   readonly maxLifetime?: number;
-  readonly tls?: "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+  readonly tls?: PostgresSslMode;
   readonly tlsCa?: string;
   readonly operationTimeoutMs?: number;
   readonly cancellationTimeoutMs?: number;
@@ -43,7 +46,7 @@ function buildPostgresProvider<T extends PostgresOrmConfigShape>(config: AppConf
   // 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.");
+    if (typeof tls !== "string" || !(POSTGRES_SSL_MODES as readonly string[]).includes(tls)) throw new InfraError("Invalid PostgreSQL configuration field: tls.");
     options.tls = tls;
   }
   if (ca !== undefined) {
@@ -96,6 +99,9 @@ export function ormBazisConnect(
     token: DATABASE_PROVIDER,
     config,
     phase: DATABASE_PHASE,
+    // Database errors answer by their meaning (409, 404, 422, 503) without a setting in the application.
+    providers: [singletonValue(HTTP_ERROR_MAPPER, databaseHttpError)],
+    exports: [HTTP_ERROR_MAPPER],
     create(configs) {
       const c = reader(config, configs);
       target = `PostgreSQL at ${String(c.get("host"))}:${String(c.get("port"))} (database "${String(c.get("database"))}", user "${String(c.get("username"))}")`;

package/core/orm/databaseHttpError.ts

@@ -0,0 +1,21 @@
+import { ConflictError, HttpError } from "../http/Errors/HttpError";
+import { englishHttpMessage, STATUS_MESSAGE_KEYS } from "../http/Errors/messages";
+import { UniqueViolationError } from "../../library/orm";
+import { databaseErrorStatus } from "./databaseErrorStatus";
+
+/**
+ * A database error as the HTTP answer for it: the statuses of
+ * {@link databaseErrorStatus}, and for a unique violation the text of
+ * `@Index({ conflict })` with the properties of the index in the details:
+ * `{ error, details: { code: "unique", fields: ["name"] } }`. The ORM registers
+ * it for every application with HTTP; the message never carries values of the row.
+ */
+export function databaseHttpError(error: unknown): HttpError | undefined {
+  if (error instanceof UniqueViolationError) {
+    return new ConflictError(error.conflict, { code: "unique", fields: [...error.properties] });
+  }
+  const status = databaseErrorStatus(error);
+  if (status === undefined) return undefined;
+  const key = STATUS_MESSAGE_KEYS[status] ?? (status >= 500 ? "serverError" : "clientError");
+  return new HttpError(status, englishHttpMessage(key), undefined, { key });
+}

package/core/orm/encryptedWith.ts

@@ -60,7 +60,7 @@ export function bindEncryptedColumns(options: DbContextOptions, registry: Config
       try {
         view = registry.get(binding.config) as { get(key: string): unknown };
       } catch {
-        throw new OrmError(`${where}: the config "${prefixOf(binding)}" is not declared in the application; add it to \`config\` of the module that owns ${entity.name} or to runApp({ config }).`);
+        throw new OrmError(`${where}: the config "${prefixOf(binding)}" is not declared in the application; add it to \`config\` of the module that owns ${entity.name} or to @App({ config }).`);
       }
       const value = view.get(binding.field);
       const secret = value instanceof Secret ? value.reveal() : value;

package/core/orm/index.ts

@@ -11,12 +11,14 @@ export { IRepository, repositoryFor } from "./repository";
 export { registerRepositories } from "./registerRepositories";
 export { paginate, type PageResult } from "./listQuery";
 export { databaseErrorStatus } from "./databaseErrorStatus";
+export { databaseHttpError } from "./databaseHttpError";
 export { encryptedWith } from "./encryptedWith";
 
 import { registerModuleMetadataExpander, type BazisModuleRef } from "../di";
 import { registerModuleDescriber } from "../kernel/report/moduleTree";
 import { OrmOwnedStoreAdmissionError, type DbContext } from "../../library/orm";
 import { registerRepositoryEncapsulationHook } from "./encapsulationHook";
+import { contextEntities } from "./contextEntities";
 import { ormModule, type OrmModuleConfig } from "./ormModule";
 import { readOwnedStoreRegistration, revalidateOwnedStoreRegistration } from "./ownedStoreContributions";
 
@@ -62,13 +64,22 @@ function declaredOwnedStore(config: OrmModuleConfig<DbContext>): unknown {
   return descriptor.value;
 }
 
+/** For the startup screen only: a context whose sets cannot be read shows what is listed. */
+function describedEntities(config: OrmModuleConfig<DbContext>): readonly unknown[] {
+  try {
+    return contextEntities(config);
+  } catch {
+    return config.entities ?? [];
+  }
+}
+
 // The module tree of the startup screen: `Task, Comment · TaskDbContext`.
 registerModuleDescriber((metadata) => {
   const orm = (metadata as { ormBazis?: OrmModuleConfig<DbContext> | readonly OrmModuleConfig<DbContext>[] }).ormBazis;
   if (orm === undefined) return [];
   return (Array.isArray(orm) ? orm : [orm]).map((config: OrmModuleConfig<DbContext>) => ({
     kind: "table" as const,
-    text: `${(config.entities ?? []).map((entity) => (entity as { name?: string }).name ?? "entity").join(", ") || "no entities"} · ${(config.context as { name?: string } | undefined)?.name ?? "DbContext"}`,
+    text: `${describedEntities(config).map((entity) => (entity as { name?: string }).name ?? "entity").join(", ") || "no entities"} · ${(config.context as { name?: string } | undefined)?.name ?? "DbContext"}`,
   }));
 });
 

package/core/orm/ormModule.ts

@@ -1,4 +1,5 @@
-import { DI, HOSTED_SERVICE, singletonValue, type BazisModuleRef, type ProviderDefinition } from "../di";
+import { HOSTED_SERVICE, singletonValue, type BazisModuleRef, type ProviderDefinition } from "../di";
+import { DI } from "../di/lowLevel";
 import {
   OrmError,
   type DatabaseProvider,
@@ -7,6 +8,9 @@ import {
   type DbContextOptionsConfig,
   type Migration,
 } from "../../library/orm";
+import { HTTP_ERROR_MAPPER } from "../http/middlewareTokens";
+import { databaseHttpError } from "./databaseHttpError";
+import { contextEntities } from "./contextEntities";
 import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
 import { IRepository } from "./repository";
 import { registerRepositories } from "./registerRepositories";
@@ -40,7 +44,12 @@ type ContextClass<TContext extends DbContext> = new (options: DbContextOptions,
 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. */
+  /**
+   * Entities of the context besides those of its sets: by default the context
+   * maps what it declares with `this.set(...)`. List here only an entity without
+   * a set, or every entity of a context whose constructor cannot run without its
+   * dependencies.
+   */
   readonly entities?: readonly EntityClass[];
   /**
    * Database provider value (`postgres(...)`). Without it the context connects
@@ -86,7 +95,7 @@ function defineFeatureOrmModule<TContext extends DbContext>(
     providers,
     exports: withRepositories ? [config.context, IRepository] : [config.context],
     configure: withRepositories
-      ? (di) => registerRepositories(di, config.context, config.entities ?? [])
+      ? (di) => registerRepositories(di, config.context, contextEntities(config))
       : undefined,
   };
 }
@@ -94,6 +103,8 @@ function defineFeatureOrmModule<TContext extends DbContext>(
 function defineConnectionModule(provider: DatabaseProvider, healthCheck: boolean): BazisModuleRef {
   const providers: ProviderDefinition[] = [
     singletonValue(DATABASE_PROVIDER, provider),
+    // Database errors answer by their meaning (409, 404, 422, 503) without a setting in the application.
+    singletonValue(HTTP_ERROR_MAPPER, databaseHttpError),
     DI.singleton(
       DI.factoryProvider(
         HOSTED_SERVICE,
@@ -112,7 +123,7 @@ function defineConnectionModule(provider: DatabaseProvider, healthCheck: boolean
 /** 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) {
+    if (!config.context || contextEntities(config).length === 0) {
       throw new OrmError("ORM owned store requires a context and entities.");
     }
     if (config.provider) {
@@ -124,7 +135,7 @@ export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TC
     // 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 buildConfig = Object.freeze({ ...config, context: config.context, entities: Object.freeze([...contextEntities(config)]) }) as OrmBuildConfig<TContext>;
     const module = defineFeatureOrmModule(buildConfig, buildOrmModuleProviders(buildConfig, DATABASE_PROVIDER));
     attachOwnedStoreRegistration(module, buildConfig.context, buildConfig.entities ?? [], config.ownedStore);
     return module;
@@ -148,7 +159,7 @@ export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TC
     // may replace them with a container-local snapshot.
     const standaloneOptions = new DbContextOptions({
       provider: config.provider,
-      entities: config.entities ?? [],
+      entities: contextEntities(config),
       validateOnSave: config.validateOnSave,
       executionStrategy: config.executionStrategy,
     });
@@ -158,7 +169,7 @@ export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TC
       providers.push(buildOrmHealthCheck(config.provider));
     }
     const module = defineFeatureOrmModule(buildConfig, providers);
-    attachOrmGraphContribution(module, buildConfig.context, buildConfig.entities ?? [], config, registration);
+    attachOrmGraphContribution(module, buildConfig.context, contextEntities(buildConfig), config, registration);
     return module;
   }
 
@@ -174,7 +185,7 @@ export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TC
   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);
+  attachOrmGraphContribution(module, buildConfig.context, contextEntities(buildConfig), config, registration);
   return module;
 }
 

package/core/orm/ownedStoreContributions.ts

@@ -6,6 +6,7 @@ import {
   type BazisModuleMetadata,
 } from "../di";
 import { OrmModel, type DbContext, type OrmOwnedStoreDefinitionV1 } from "../../library/orm";
+import { contextEntities } from "./contextEntities";
 import { compileExpectedSchema, type OrmExpectedSchema } from "../../library/orm/Schema/ExpectedSchema";
 import { isDefinedOrmOwnedStoreV1 } from "../../library/orm/Schema/OrmOwnedStore";
 import { defineOrmOwnedStoreV1 } from "../../library/orm/Schema/OrmOwnedStore";
@@ -159,7 +160,7 @@ export function ownedStoreRegistrations(snapshot: ModuleOwnedContributionSnapsho
     // view. Direct ordinary modules intentionally read their caller config at
     // build time, then both graph preflight and runtime factories use this copy.
     const source = entry.config as { readonly entities?: readonly EntityClass[]; readonly migrations?: readonly unknown[] } | undefined;
-    const entities = source === undefined ? entry.entities : Object.freeze([...(source.entities ?? [])]);
+    const entities = source === undefined ? entry.entities : Object.freeze([...contextEntities({ context: entry.context, entities: source.entities })]);
     // Migration instances remain caller-owned; only the sequence membership and
     // order are part of this container's effective config snapshot.
     const migrations = source?.migrations;

package/core/orm/registerRepositories.ts

@@ -1,4 +1,5 @@
-import { DI, type DiRegistrar } from "../di";
+import { type DiRegistrar } from "../di";
+import { DI } from "../di/lowLevel";
 import { Repository, type DbContext, type DbContextOptions } from "../../library/orm";
 import { repositoryFor } from "./repository";