bazis 0.136.0 → 0.137.0

package/core/kernel/config/defineConfig.ts

@@ -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/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,5 @@
 import { DI, HOSTED_SERVICE, type InjectionToken, type ModuleOwnedContributionSnapshot, type ProviderDefinition, type ProviderDependencyList, type ServiceResolver } from "../di";
+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 +28,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/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

@@ -7,6 +7,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 +43,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 +94,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 +102,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 +122,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 +134,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 +158,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 +168,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 +184,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/scripts/di-generate.ts

@@ -189,6 +189,8 @@ interface ConstructorDependencies {
   readonly unsupportedParameter?: { readonly index: number; readonly name: string; readonly type: string };
 }
 let classDeps = new Map<ts.ClassDeclaration, readonly CollectedDependency[]>();
+/** `permissions` of the target's modules: the exported constant and its file. */
+let permissionDeclarations = new Map<string, { readonly name: string; readonly file: string }>();
 let inferredDiClasses = new Set<ts.ClassDeclaration>();
 let explicitlyBoundDiClasses = new Set<ts.ClassDeclaration>();
 // Known runtime token names: createToken descriptions + class names usable as class-tokens.
@@ -505,7 +507,7 @@ function collectDynamicImportDiagnostics(source: ts.SourceFile, target: string,
 
 function resetTargetAnalysis(files: Set<string>, generatedDir: string): void {
   activeGeneratedDir = generatedDir;
-  classDeps = new Map(); inferredDiClasses = new Set(); explicitlyBoundDiClasses = new Set();
+  classDeps = new Map(); inferredDiClasses = new Set(); explicitlyBoundDiClasses = new Set(); permissionDeclarations = new Map();
   tokenDescriptions = new Set(); configPrefixesByType = new Map(); knownClassNames = new Set(); warnings = []; fatalErrors = [];
   httpBindings = {}; httpControllerFiles = {}; openApiSchemas = {}; openApiOperations = {};
   grpcBindings = new Map();
@@ -555,6 +557,8 @@ async function generateTarget(name: string, reachable: Set<string>, production:
   stageWrite(`${generatedDir}/httpRequestModels.ts`, requestModels);
   stageWrite(`${generatedDir}/httpListModels.ts`, listModels);
   stageWrite(`${generatedDir}/openapi.ts`, openApi);
+  if (permissionDeclarations.size > 0) stageWrite(`${generatedDir}/permissions.ts`, renderPermissions());
+  else stageRemove(`${generatedDir}/permissions.ts`);
   // Generated before 0.99.0, when agents were classes; nothing imports it now.
   stageRemove(`${generatedDir}/agentCatalog.ts`);
   stageWrite(`${generatedDir}/runtime.ts`, renderGeneratedRuntime(name));
@@ -708,6 +712,15 @@ function renderGeneratedRuntime(targetId: string): string {
 }
 
 /** Sources of this target as codegen saw them; read back by the generated runtime. */
+/** Types only: the keys of the target's permissions for `can`, `access.can`, `access.filter` and `defineRoles`. */
+function renderPermissions(): string {
+  const entries = [...permissionDeclarations.values()].sort((left, right) => left.file.localeCompare(right.file) || left.name.localeCompare(right.name));
+  const lines = ["// This file is auto-generated by `bazis codegen`.", "// Do not edit manually.", 'import type { PermissionsOf } from "bazis/core/access";'];
+  entries.forEach((entry, index) => lines.push(`import type { ${entry.name} as Permissions_${index} } from ${JSON.stringify(toModuleSpecifierFrom(activeGeneratedDir, entry.file))};`));
+  lines.push("", 'declare module "bazis/core/access" {', `  interface BazisPermissions extends ${entries.map((_, index) => `PermissionsOf<typeof Permissions_${index}>`).join(", ")} {}`, "}", "");
+  return lines.join("\n");
+}
+
 function renderSourceFingerprint(): string {
   const files = sourceEntries.map((entry) => entry.filePath).sort();
   const framework = JSON.parse(readFileSync(path.join(FRAMEWORK_DIR, "package.json"), "utf8")).version as string;
@@ -832,6 +845,8 @@ function collectTokenDescriptions(source: ts.SourceFile): void {
   const visit = (node: ts.Node): void => {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.arguments.length > 0) {
       const firstArg = node.arguments[0];
+      // defineConfig({ default: … }) without a section: its token is Config:default.
+      if (node.expression.text === "defineConfig" && firstArg && !ts.isStringLiteralLike(firstArg)) tokenDescriptions.add("Config:default");
       if (firstArg && ts.isStringLiteralLike(firstArg)) {
         if (node.expression.text === "createToken" || node.expression.text === "createOpenGenericTokenFamily") {
           tokenDescriptions.add(firstArg.text);
@@ -873,7 +888,9 @@ function resolveConfigViewDeps(): void {
       if (prefixes.length !== 1) {
         classDeps.delete(declaration);
         if (needsInferredDiDeps(declaration)) {
-          fatalErrors.push(prefixes.length === 0
+          fatalErrors.push(typeName.startsWith("typeof ")
+            ? `BAZIS_DI_CONFIG_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", but ${typeName.slice(7)} is not a declaration whose section codegen can read. Declare it as defineConfig("name", { default: {...} }) with a literal name and without a type argument.`
+            : prefixes.length === 0
             ? `BAZIS_DI_CONFIG_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", but no defineConfig<${typeName}>(...) declaration was found. Declare the configuration with an explicit type argument, for example defineConfig<${typeName}>("name", { default: {...} }).`
             : `BAZIS_DI_CONFIG_AMBIGUOUS: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", which matches several declarations: ${prefixes.map((prefix) => `"${prefix}"`).join(", ")}. Give each declaration its own type.`);
         }
@@ -987,6 +1004,9 @@ function collectDiClassRegistrations(source: ts.SourceFile): void {
       const classes = properties.get(name);
       if (classes && ts.isArrayLiteralExpression(classes)) for (const entry of classes.elements) record(entry);
     }
+    // `references: { "orders.order": OrderReferences }`: the field registers the classes.
+    const references = objectFor(properties.get("references"));
+    if (references) for (const entry of propertiesOf(references).values()) record(entry);
     const imports = properties.get("imports");
     if (imports && ts.isArrayLiteralExpression(imports)) for (const entry of imports.elements) recordModule(entry);
   };
@@ -1093,12 +1113,33 @@ function collectProviderFormErrors(source: ts.SourceFile): void {
     const target = call && callee(call);
     return target?.name === "ormEntityTools" && target.file?.endsWith("/core/tools/orm/ormEntityTools.ts") === true;
   };
+  /**
+   * `permissions: orderPermissions`: the exported constant goes to the generated
+   * `permissions.ts`, which makes its keys the type of `can` and `defineRoles`.
+   * A framework pack names its own in its sources.
+   */
+  const collectPermissions = (module: string, initializer: ts.Expression): void => {
+    let symbol = ts.isIdentifier(initializer) ? checker.getSymbolAtLocation(initializer) : undefined;
+    if (symbol && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    const file = normalizeProjectPath((declaration ?? initializer).getSourceFile().fileName);
+    // A framework pack names its permissions in its own sources.
+    if (file.includes("/node_modules/") || isFrameworkPackPath(file)) return;
+    const fileSymbol = declaration && checker.getSymbolAtLocation(declaration.getSourceFile());
+    const exported = fileSymbol && symbol && checker.getExportsOfModule(fileSymbol).find((entry) => (entry.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(entry) : entry) === symbol);
+    if (!declaration || !ts.isVariableDeclaration(declaration) || exported === undefined) {
+      fatalErrors.push(`BAZIS_ACCESS_PERMISSIONS_FORM: ${sourceLocation(initializer)}: permissions of ${module}: "${text(initializer)}" — export the result of definePermissions(...) as a constant and name it here, so that its keys become the type of can(...) and defineRoles(...).`);
+      return;
+    }
+    permissionDeclarations.set(`${file}\0${exported.name}`, { name: exported.name, file });
+  };
   const checkModule = (module: string, argument: ts.Expression | undefined): void => {
     const object = argument && resolved(argument, ts.isObjectLiteralExpression);
     if (!object) return;
     for (const property of object.properties) {
       if (!ts.isPropertyAssignment(property)) continue;
       const field = property.name.getText().replace(/["']/g, "");
+      if (field === "permissions") collectPermissions(module, property.initializer);
       if (field !== "providers" && !CLASS_LISTS.includes(field)) continue;
       const list = resolved(property.initializer, ts.isArrayLiteralExpression);
       if (!list) {
@@ -1182,6 +1223,13 @@ function readInheritedConstructorDeps(node: ts.ClassDeclaration): ConstructorDep
   return { deps };
 }
 
+/** The section of a `defineConfig("mail", …)` declaration by its type: the literal of its `prefix`. */
+function configPrefixOf(type: ts.Type): string | undefined {
+  const prefix = type.getProperty("prefix");
+  const literal = prefix && checker.getTypeOfSymbol(prefix);
+  return literal?.isStringLiteral() ? literal.value : undefined;
+}
+
 function dependencyFromType(type: ts.Type): CollectedDependency | undefined {
   if (type.flags & ts.TypeFlags.TypeParameter) return undefined;
   const symbol = type.getSymbol();
@@ -1191,8 +1239,11 @@ function dependencyFromType(type: ts.Type): CollectedDependency | undefined {
   const name = declaration?.name?.text ?? type.aliasSymbol?.name ?? symbol?.name;
   if (!name || BUILTIN_DEPENDENCY_NAMES.has(name)) return undefined;
   const arguments_ = type.flags & ts.TypeFlags.Object ? checker.getTypeArguments(type as ts.TypeReference) : [];
-  if (name === "ConfigView") {
-    const configType = arguments_[0];
+  if (name === "ConfigView" || name === "ResolvedConfigView") {
+    // ConfigView<typeof mailConfig>: the declaration carries the name of its section in its type.
+    const declared = type.aliasTypeArguments?.[0] && configPrefixOf(type.aliasTypeArguments[0]);
+    if (declared !== undefined) return { name: `Config:${declared}` };
+    const configType = type.aliasTypeArguments?.[0] ?? arguments_[0];
     const configTypeName = configType && (configType.aliasSymbol?.name ?? configType.getSymbol()?.name);
     return configTypeName ? { name: `ConfigView<${configTypeName}>` } : undefined;
   }
@@ -1244,6 +1295,12 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
 
     if (refName === "ConfigView" && paramType && ts.isTypeReferenceNode(paramType)) {
       const configType = paramType.typeArguments?.[0];
+      if (configType && ts.isTypeQueryNode(configType)) {
+        // ConfigView<typeof mailConfig>: the declaration carries the name of its section in its type.
+        const declared = configPrefixOf(checker.getTypeFromTypeNode(configType));
+        deps.push({ name: declared === undefined ? `ConfigView<${configType.getText()}>` : `Config:${declared}`, ...optionalFlag });
+        continue;
+      }
       const configTypeName = configType ? getDependencyTypeName(configType) : undefined;
       if (configTypeName) {
         deps.push({ name: `ConfigView<${configTypeName}>`, ...optionalFlag });

package/core/tools/StandardTools.module.ts

@@ -16,7 +16,7 @@ import { ConfigSecretStore, SecretStore } from "./secrets/SecretStore";
   config: [toolsConfig],
   references: { "orm.entity": OrmEntityReferences, "orm.field": OrmFieldReferences },
   tools: [HttpRequestTool],
-  providers: [singleton(OrmEntityReferences), singleton(OrmFieldReferences), singleton(SecretStore, ConfigSecretStore)],
+  providers: [singleton(SecretStore, ConfigSecretStore)],
   exports: [SecretStore],
 })
 export class StandardToolsModule {}

package/core/tools/contracts/Tools.config.ts

@@ -1,29 +1,35 @@
-import { defineConfig } from "../../kernel";
+import { configList, defineConfig } from "../../kernel";
 
 /**
- * Settings of the standard Tools. `http.allow` is the comma-separated list of hosts
- * `http.request` may reach: `api.example.com`, `*.example.com`, `localhost:8080`.
+ * Settings of the standard Tools. `http.allow` is the list of hosts `http.request`
+ * may reach, comma-separated in the environment: `api.example.com`, `*.example.com`,
+ * `localhost:8080`.
  * Empty by default: requests go nowhere. `http.allowPrivateNetworks` lets it reach
  * private and loopback addresses of a listed host: intranet services, tests.
  * `http.callers` says who may call it: `workflow`, `agent`.
  */
 export interface ToolsSettings {
-  readonly "http.allow": string;
-  readonly "http.callers": string;
+  readonly "http.allow": readonly string[];
+  readonly "http.callers": readonly string[];
   readonly "http.allowPrivateNetworks": boolean;
   readonly "http.maxResponseBytes": number;
   readonly "http.timeoutMs": number;
 }
 
+/** A host, a subdomain pattern or an IPv6 address in brackets, with an optional port. */
+const HOST = /^(\*\.)?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?(:\d{1,5})?$|^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+
 export const toolsConfig = defineConfig<ToolsSettings>("tools", {
   default: {
-    "http.allow": "",
-    "http.callers": "workflow",
+    "http.allow": configList(),
+    "http.callers": configList(["workflow"]),
     "http.allowPrivateNetworks": false,
     "http.maxResponseBytes": 1_048_576,
     "http.timeoutMs": 30_000,
   },
   validate: {
+    "http.allow": (value) => value.find((item) => !HOST.test(item)) === undefined ? undefined : `must list hosts like api.example.com, *.example.com or localhost:8080; ${JSON.stringify(value.find((item) => !HOST.test(item)))} is not one`,
+    "http.callers": (value) => (value.every((item) => /^[a-z][a-z0-9_.-]{0,63}$/.test(item)) ? undefined : "must list caller ids like workflow, agent"),
     "http.maxResponseBytes": (value) => (Number.isSafeInteger(value) && value >= 1 && value <= 104_857_600 ? undefined : "must be an integer 1–104857600"),
     "http.timeoutMs": (value) => (Number.isSafeInteger(value) && value >= 1 && value <= 600_000 ? undefined : "must be an integer 1–600000"),
   },