bazis 0.136.0 → 0.138.0

package/core/workflow/tasks_module/model/WfTask.model.ts

@@ -1,4 +1,4 @@
-import { Column, Entity, Index, UUID } from "../../../orm";
+import { Column, Entity, Index, UUID, Nullable } from "../../../orm";
 import type { FormSpec, LocalizedText } from "../../../../library/workflow";
 
 /** `open` waits for someone, `claimed` is taken by one person, `completed` and `cancelled` are done. */
@@ -17,55 +17,71 @@ export class WfTask {
 
   /** The waiting token: one task per token. */
   @Index({ unique: true })
+  @Nullable()
   @Column({ type: "text" })
   tokenId = "";
 
   @Index()
+  @Nullable()
   @Column({ type: "text" })
   instanceId = "";
 
+  @Nullable()
   @Column({ type: "text" })
   processKey = "";
 
+  @Nullable()
   @Column({ type: "text" })
   nodeId = "";
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   partition: string | null = null;
 
+  @Nullable()
   @Column({ type: "json" })
   title: LocalizedText = "";
 
   /** The task of a trial run (WORKFLOW-002 §5.4, stage 5). */
+  @Nullable()
   @Column({ type: "boolean" })
   test = false;
 
   /** `role:<code>` or `user:<id>`. */
+  @Nullable()
   @Column({ type: "text" })
   assignee = "";
 
-  @Column({ type: "json", nullable: true })
+  @Nullable()
+  @Column({ type: "json" })
   form: FormSpec | null = null;
 
-  @Column({ type: "datetime", nullable: true })
+  @Nullable()
+  @Column({ type: "datetime" })
   dueAt: Date | null = null;
 
+  @Nullable()
   @Column({ type: "text" })
   status: TaskStatus = "open";
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   claimedById: string | null = null;
 
-  @Column({ type: "datetime", nullable: true })
+  @Nullable()
+  @Column({ type: "datetime" })
   claimedAt: Date | null = null;
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   completedById: string | null = null;
 
-  @Column({ type: "datetime", nullable: true })
+  @Nullable()
+  @Column({ type: "datetime" })
   completedAt: Date | null = null;
 
-  @Column({ type: "json", nullable: true })
+  @Nullable()
+  @Column({ type: "json" })
   output: Record<string, unknown> | null = null;
 
   @Column({ type: "createdAt" })

package/core/workflow/testing/index.ts

@@ -1,8 +1,10 @@
-import { DI } from "../../di";
+import { DI } from "../../di/lowLevel";
 import "../generated/deps";
 import { startTestApp, type TestApp, type TestAppOptions } from "../../testing";
+import { postgres } from "../../../library/orm";
 import { durationMs } from "../../../library/workflow";
 import { WorkflowClock } from "../contracts/WorkflowClock";
+import type { CodeProcess } from "../definitions_module/code/defineProcess";
 import type { WorkflowActor } from "../contracts/types";
 import { WorkflowJobs } from "../runtime_module/internal/WorkflowJobs";
 import { IWorkflowRuntime, type EmitOptions, type EmitResult, type HistoryEntry, type InstanceDetails, type StartInstance } from "../runtime_module/services/IWorkflowRuntime.service";
@@ -57,7 +59,11 @@ export interface TestWorkflow {
   readonly app: TestApp;
   readonly clock: ManualWorkflowClock;
   now(): Date;
-  /** Starts the latest version of a process from its manual start; jobs wait for {@link drain}. */
+  /**
+   * Starts the latest version of a process from its manual start; jobs wait for {@link drain}.
+   * Given the `defineProcess` result, the input is checked by its variables.
+   */
+  start<Input>(process: CodeProcess<Input, unknown>, options?: Partial<StartInstance<Input>>): Promise<InstanceDetails>;
   start(processKey: string, options?: Partial<StartInstance>): Promise<InstanceDetails>;
   emit(eventKey: string, payload?: unknown, options?: EmitOptions): Promise<EmitResult>;
   /** Completes the user task waiting at `nodeId` (through its task when the Tasks part is there). */
@@ -67,7 +73,11 @@ export interface TestWorkflow {
   /** Moves the clock forward (ISO duration or milliseconds), then {@link drain}. */
   advance(by: string | number): Promise<number>;
   instance(instanceId: string): Promise<InstanceDetails>;
+  /** The instance started with this `businessKey`, the newest one when there are several. */
+  instanceByKey(businessKey: string): Promise<InstanceDetails>;
   history(instanceId: string): Promise<readonly HistoryEntry[]>;
+  /** Calls a service of the application in a scope of its own, see `TestApp.use`. */
+  use: TestApp["use"];
   stop(): Promise<void>;
 }
 
@@ -77,7 +87,7 @@ export interface TestWorkflow {
  * deterministic. Needs PostgreSQL, as the workflow module does.
  *
  * ```ts
- * const wf = await testWorkflow(AppModule, { now: "2026-11-02T09:00:00Z" });
+ * const wf = await testWorkflow(OrdersApp, { now: "2026-11-02T09:00:00Z", http: false });
  * try {
  *   const order = await wf.start("order-approval", { input: { amount: 5000 } });
  *   await wf.drain();
@@ -127,7 +137,7 @@ export async function testWorkflow(root: Parameters<typeof startTestApp>[0], opt
     app,
     clock,
     now: () => clock.now(),
-    start: (processKey, start = {}) => inScope((scope) => scope.resolve(IWorkflowRuntime).start(processKey, { ...start, actor: start.actor ?? actor })),
+    start: (process: string | CodeProcess<unknown, unknown>, start: Partial<StartInstance> = {}) => inScope((scope) => scope.resolve(IWorkflowRuntime).start(typeof process === "string" ? process : process.key, { ...start, actor: start.actor ?? actor })),
     emit: (eventKey, payload, emitOptions = {}) => inScope((scope) => scope.resolve(IWorkflowRuntime).emit(eventKey, payload, { ...emitOptions, actor: emitOptions.actor ?? actor })),
     complete: (instanceId, nodeId, output = {}, by = actor) => inScope(async (scope) => {
       const runtime = scope.resolve(IWorkflowRuntime);
@@ -151,11 +161,43 @@ export async function testWorkflow(root: Parameters<typeof startTestApp>[0], opt
       return await drain();
     },
     instance: (instanceId) => inScope((scope) => scope.resolve(IWorkflowRuntime).instance(instanceId)),
+    instanceByKey: (businessKey) => inScope(async (scope) => {
+      const runtime = scope.resolve(IWorkflowRuntime);
+      const found = (await runtime.instances({ businessKey })).items[0];
+      if (found === undefined) throw new Error(`No instance was started with the business key ${JSON.stringify(businessKey)}`);
+      return await runtime.instance(found.id);
+    }),
+    use: app.use,
     history: (instanceId) => inScope((scope) => scope.resolve(IWorkflowRuntime).history(instanceId)),
     stop: () => app.stop(),
   };
 }
 
+/**
+ * Drops the tables of the workflow module, so the next start creates them anew:
+ * a clean state for a test database. Everything the module stored there is lost,
+ * so the name of the database must start with `test_` or end with `_test`, or
+ * `force` must say the loss is meant.
+ *
+ * ```ts
+ * beforeAll(() => dropWorkflowTables(process.env.TEST_DATABASE_URL!));
+ * ```
+ */
+export async function dropWorkflowTables(url: string, options: { readonly force?: boolean } = {}): Promise<void> {
+  const database = new URL(url).pathname.slice(1);
+  if (options.force !== true && !/^test_|_test$/.test(database)) {
+    throw new Error(`dropWorkflowTables: the database "${database}" does not look like a test one (test_… or …_test). Pass { force: true } to drop its workflow tables anyway.`);
+  }
+  const sql = postgres({ url });
+  try {
+    const tables = (await sql.query("SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tablename LIKE 'bazis\\_wf%'", [])) as { tablename: string }[];
+    if (tables.length > 0) await sql.execute(`DROP TABLE ${tables.map((table) => `"${table.tablename}"`).join(", ")} CASCADE`, []);
+    await sql.execute(`DO $$ BEGIN IF to_regclass('public.__bazis_orm_owned_stores_v1') IS NOT NULL THEN DELETE FROM "__bazis_orm_owned_stores_v1" WHERE store_key LIKE 'bazis.workflow.%'; END IF; END $$`, []);
+  } finally {
+    await sql.close();
+  }
+}
+
 function toTime(value: Date | string, what: string): number {
   const time = value instanceof Date ? value.getTime() : Date.parse(value);
   if (!Number.isFinite(time)) throw new Error(`The workflow clock ${what} must be a date, not ${JSON.stringify(value)}`);

package/index.ts

@@ -46,8 +46,11 @@ export {
   type GrpcContext, type GrpcModuleOptions,
 } from "./core/grpc";
 export {
+  App,
   runApp,
-  type RunAppOptions,
+  type AppClass,
+  type AppOptions,
+  type AppSettings,
   type RunAppUiAppInfo,
   type RunAppUiOptions,
   type RunAppUiSurfaceOptions,
@@ -67,8 +70,6 @@ export {
   createToken,
   scoped,
   singleton,
-  singletonFactory,
-  singletonFactoryWithResolver,
   singletonValue,
   transient,
   type ModuleConfig,

package/library/openapi/codegen.ts

@@ -47,7 +47,7 @@ const ERROR_HELPER_STATUS: Readonly<Record<string, number>> = {
   BadRequest: 400, Unauthorized: 401, Forbidden: 403, NotFound: 404, Conflict: 409,
 };
 const ERROR_CLASS_STATUS: Readonly<Record<string, number>> = {
-  BadRequestError: 400, UnauthorizedError: 401, ForbiddenError: 403, NotFoundError: 404,
+  BadRequestError: 400, UnauthorizedError: 401, ForbiddenError: 403, NotFoundError: 404, ConflictError: 409,
   PayloadTooLargeError: 413, UnsupportedMediaTypeError: 415, TooManyRequestsError: 429,
 };
 const OPENAPI_EMPTY_TYPE_NAMES = new Set(["HttpResult", "Response", "Blob", "ReadableStream", "Uint8Array"]);
@@ -333,7 +333,7 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
           return schemaFromOptionalExpression(unwrapped.arguments[0]);
         }
         if (CREATED_RESULT_HELPERS.has(name)) {
-          return schemaFromOptionalExpression(unwrapped.arguments[1]);
+          return schemaFromOptionalExpression(unwrapped.arguments[0]);
         }
         if (name === "StatusCode") {
           return schemaFromStatusCodeCall(unwrapped);

package/library/orm/DbContext.ts

@@ -11,6 +11,9 @@ import { OrmTransaction, type OrmTransactionScopeOptions } from "./Transactions/
 
 type EntityClass<T extends object> = new () => T;
 
+/** While a context is constructed only to read its sets: {@link DbContext.entitiesOf}. */
+let discovered: Set<EntityClass<object>> | undefined;
+
 /**
  * Base class of a database context (a scoped DI service). A subclass declares the sets:
  *
@@ -32,10 +35,39 @@ export abstract class DbContext {
   readonly #options: DbContextOptions;
   readonly #runtime: DbContextRuntime;
 
+  /**
+   * The entities a context declares with `this.set(...)`, in the order of its
+   * fields. The class is constructed once without a database and without its
+   * own constructor dependencies only to read the sets: a constructor that needs
+   * them fails here, and the entities are then listed by hand.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static entitiesOf(context: new (options: DbContextOptions, ...dependencies: any[]) => DbContext): readonly EntityClass<object>[] {
+    const previous = discovered;
+    const found = new Set<EntityClass<object>>();
+    discovered = found;
+    try {
+      new context(undefined as unknown as DbContextOptions);
+    } catch (error) {
+      throw new OrmError(`The entities of ${context.name} cannot be read from its sets: its constructor failed without its dependencies (${error instanceof Error ? error.message : String(error)}). List them: entities: [...].`);
+    } finally {
+      discovered = previous;
+    }
+    return [...found];
+  }
+
   constructor(options: DbContextOptions) {
+    if (discovered !== undefined) {
+      // Only the sets are read: nothing of the context works, and it is thrown away.
+      this.#options = options;
+      this.changeTracker = undefined as unknown as ChangeTracker;
+      this.#runtime = undefined as unknown as DbContextRuntime;
+      this.database = undefined as unknown as DatabaseFacade;
+      return;
+    }
     this.#options = options;
     this.changeTracker = new ChangeTracker();
-    const provider = observedProvider(this, options.provider);
+    const provider = observedProvider(this, options.provider, options.model);
     this.#runtime = { context: this, provider, models: options.model, tracker: this.changeTracker, runImmediateOperation: (operation) => monitorImmediateOperation(this, operation) };
     this.database = new DatabaseFacade(provider, options.model);
   }
@@ -47,6 +79,10 @@ export abstract class DbContext {
 
   /** Public access to a `DbSet` by entity class (for `Repository<T>` and generic scenarios). */
   setOf<T extends object>(entity: EntityClass<T>): DbSet<T> {
+    if (discovered !== undefined) {
+      discovered.add(entity);
+      return undefined as unknown as DbSet<T>;
+    }
     return new DbSet<T>(this.#options.model.requireByCtor(entity), this.#runtime);
   }
 

package/library/orm/Metadata/ModelBuilder.ts

@@ -59,6 +59,7 @@ export class ModelBuilder {
           columns: [property.columnName],
           unique: rawProp.index.unique,
           ...(rawProp.index.where === undefined ? {} : { where: rawProp.index.where }),
+          ...conflictOf(ctor.name, rawProp.index),
         });
       }
       if (rawProp.fkTarget) {
@@ -179,7 +180,7 @@ export class ModelBuilder {
         return property.columnName;
       });
       if (new Set(columns).size !== columns.length) throw new ModelBuildError(`Entity "${ctor.name}": index contains duplicate properties.`);
-      indexes.push({ name: declared.name ?? `ix_${(raw.table ?? defaultTableName(ctor.name)).toLowerCase()}_${columns.join("_")}`, columns, unique: declared.unique, ...(declared.where === undefined ? {} : { where: declared.where }) });
+      indexes.push({ name: declared.name ?? `ix_${(raw.table ?? defaultTableName(ctor.name)).toLowerCase()}_${columns.join("_")}`, columns, unique: declared.unique, ...(declared.where === undefined ? {} : { where: declared.where }), ...conflictOf(ctor.name, declared) });
     }
     const indexNames = new Set<string>();
     for (const index of indexes) {
@@ -255,12 +256,19 @@ export class ModelBuilder {
         `Entity "${entityName}": key "${raw.propertyName}" has keyGenerated=true but is not an integer identity key.`,
       );
     }
-    // The key and semantic timestamp fields are always NOT NULL.
-    const required =
-      isKey ||
-      raw.required === true ||
-      raw.nullable === false ||
-      resolved.impliedRequired === true;
+    // The key and semantic timestamp fields are always NOT NULL. Every other
+    // column says it itself: silence would be read as either by different readers.
+    const always = isKey || resolved.impliedRequired === true;
+    if (raw.required === true && raw.nullable === true) {
+      throw new ModelBuildError(`Entity "${entityName}": property "${raw.propertyName}" is marked both @Required() and @Nullable(). Keep one.`);
+    }
+    if (always && raw.nullable === true) {
+      throw new ModelBuildError(`Entity "${entityName}": property "${raw.propertyName}" is ${isKey ? "a key" : "a creation or change timestamp"} and cannot be @Nullable().`);
+    }
+    if (!always && raw.required !== true && raw.nullable !== true) {
+      throw new ModelBuildError(`Entity "${entityName}": property "${raw.propertyName}" does not say whether it may be empty. Mark it @Required() (NOT NULL) or @Nullable().`);
+    }
+    const required = always || raw.required === true;
     const databaseDefault = ModelBuilder.defaultFor(entityName, raw, storageType, isKey, generated, convention, required);
     const digits = ModelBuilder.decimalDigits(entityName, raw, storageType);
     return {
@@ -371,6 +379,14 @@ function isCanonicalRfc3339(value: string): boolean {
  * refused: PostgreSQL stores it in its own time zone form, so the declared
  * and the stored conditions could never be compared.
  */
+/** The text of a unique index for a rejected value; on any other index it would never be used. */
+function conflictOf(entity: string, index: { readonly unique: boolean; readonly conflict?: string }): { readonly conflict?: string } {
+  if (index.conflict === undefined) return {};
+  if (!index.unique) throw new ModelBuildError(`Entity "${entity}": conflict is the text of a unique index; this index is not unique.`);
+  if (typeof index.conflict !== "string" || index.conflict.trim() === "") throw new ModelBuildError(`Entity "${entity}": conflict of an index must be a non-empty text.`);
+  return { conflict: index.conflict };
+}
+
 function validateIndexCondition(entity: string, index: string, where: CheckAst, properties: readonly PropertyModel[]): void {
   validateCheckAst(where, properties, `Entity "${entity}": index "${index}" condition`);
   const byName = new Map(properties.map((property) => [property.propertyName, property]));

package/library/orm/Metadata/decorators.ts

@@ -30,8 +30,6 @@ export interface ColumnOptions {
   readonly name?: string;
   /** Type: physical (`text`, `datetime`, …) or semantic (`uuid`, `createdAt`, `updatedAt`). */
   readonly type?: ColumnOptionsType;
-  /** Allow NULL (default true; `@Required` sets false). */
-  readonly nullable?: boolean;
   /** Closed physical PostgreSQL default. It is not an application initializer or SQL fragment. */
   readonly default?: ColumnDefaultValue;
   /**
@@ -81,6 +79,12 @@ export interface IndexOptions<T extends object = any> {
    * The condition uses the same operators as `@Check`.
    */
   readonly where?: CheckPredicate<T>;
+  /**
+   * For a unique index: what to tell the client when a value is taken. Without it
+   * the answer is the standard text of 409. The names of the properties go to the
+   * details either way.
+   */
+  readonly conflict?: string;
 }
 export interface CompositeKeyOptions { readonly name?: string }
 export type ReferentialAction = "noAction" | "restrict" | "cascade" | "setNull";
@@ -104,7 +108,7 @@ export interface RawProperty {
   default?: ColumnDefaultValue;
   precision?: number;
   scale?: number;
-  index?: { unique: boolean; name?: string; where?: import("../Schema/CheckExpression").CheckAst };
+  index?: { unique: boolean; name?: string; where?: import("../Schema/CheckExpression").CheckAst; conflict?: string };
   /** `@ForeignKey(() => Principal)` on a scalar column, for the DDL FK. */
   fkTarget?: () => EntityClass;
   /** `@HasConversion(...)`: conversion before/after the dialect. */
@@ -136,7 +140,7 @@ export interface RawEntity {
   /** Soft-delete property name (see `@SoftDelete` / `@Entity({ softDelete })`). */
   softDeleteProperty?: string;
   keyDeclaration?: { properties: readonly string[]; name?: string; anchor: string; composite: boolean };
-  indexes?: Array<{ properties: readonly string[]; unique: boolean; name?: string; where?: import("../Schema/CheckExpression").CheckAst }>;
+  indexes?: Array<{ properties: readonly string[]; unique: boolean; name?: string; where?: import("../Schema/CheckExpression").CheckAst; conflict?: string }>;
   foreignKeys?: Array<{ properties: readonly string[]; target: () => EntityClass; name?: string; onDelete?: ReferentialAction; onUpdate?: ReferentialAction }>;
   checks?: Array<{ name: string; expression: import("../Schema/CheckExpression").CheckAst }>;
 }
@@ -297,19 +301,28 @@ export function Column(options: ColumnOptions = {}) {
     prop.default = options.default;
     prop.precision = options.precision;
     prop.scale = options.scale;
-    if (options.nullable !== undefined) {
-      prop.nullable = options.nullable;
-    }
   };
 }
 
-/** NOT NULL. */
+/**
+ * The column is NOT NULL. Every column says whether it may be empty, with this
+ * or with {@link Nullable}: a reader sees it on the column, and a column that
+ * says neither stops the start. Keys and the creation and change timestamps
+ * need no mark: they are always NOT NULL.
+ */
 export function Required() {
   return (_value: undefined, context: ClassFieldDecoratorContext): void => {
     ownProperty(context.metadata, fieldName(context)).required = true;
   };
 }
 
+/** The column allows NULL: the other of the two marks, see {@link Required}. */
+export function Nullable() {
+  return (_value: undefined, context: ClassFieldDecoratorContext): void => {
+    ownProperty(context.metadata, fieldName(context)).nullable = true;
+  };
+}
+
 /** Index on the property's column. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function Index<T extends object = any>(options?: IndexOptions<T>): (value: undefined, context: ClassFieldDecoratorContext) => void;
@@ -319,13 +332,13 @@ export function Index(first: IndexOptions | readonly [string, ...string[]] = {},
   if (Array.isArray(first)) {
     const where = options.where === undefined ? undefined : compileCheck(options.where);
     return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {
-      (ownRaw(context.metadata).indexes ??= []).push({ properties: [...first], unique: options.unique === true, name: options.name, ...(where === undefined ? {} : { where }) });
+      (ownRaw(context.metadata).indexes ??= []).push({ properties: [...first], unique: options.unique === true, name: options.name, ...(where === undefined ? {} : { where }), ...(options.conflict === undefined ? {} : { conflict: options.conflict }) });
     };
   }
   const propertyOptions = first as IndexOptions;
   const where = propertyOptions.where === undefined ? undefined : compileCheck(propertyOptions.where);
   return (_value: undefined, context: ClassFieldDecoratorContext): void => {
-    ownProperty(context.metadata, fieldName(context)).index = { unique: propertyOptions.unique === true, name: propertyOptions.name, ...(where === undefined ? {} : { where }) };
+    ownProperty(context.metadata, fieldName(context)).index = { unique: propertyOptions.unique === true, name: propertyOptions.name, ...(where === undefined ? {} : { where }), ...(propertyOptions.conflict === undefined ? {} : { conflict: propertyOptions.conflict }) };
   };
 }
 

package/library/orm/Metadata/types.ts

@@ -77,6 +77,8 @@ export interface IndexModel {
   readonly unique: boolean;
   /** Partial index condition over property names (`@Index({ where })`). */
   readonly where?: CheckAst;
+  /** What to tell the client when a unique index rejects a value (`@Index({ conflict })`). */
+  readonly conflict?: string;
 }
 export interface CheckModel { readonly name: string; readonly expression: CheckAst }
 

package/library/orm/Transactions/TransactionScopeCoordinator.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { DbContext } from "../DbContext";
-import { ConcurrentTransactionScopeError, differentProviderMessage, OrmDatabaseTimeError, OrmProviderIdentityMismatchError, OrmTransactionScopeError, translateDatabaseError } from "../errors";
+import { ConcurrentTransactionScopeError, differentProviderMessage, OrmDatabaseTimeError, OrmProviderIdentityMismatchError, OrmTransactionScopeError, describeViolation, translateDatabaseError, type ViolationModels } from "../errors";
 import { baseProvider, withPostgresScopeOptions, createObservedProvider, postgresTransactionCapability, rootAuthority, withProviderDispatchObserver, withoutProviderDispatchObserver, type CancellableProviderDispatch } from "../Providers/ormTransactionRuntime";
 import type { DatabaseProvider } from "../Providers/types";
 import { OrmTransaction, type OrmDatabaseTimeV1, type OrmTransactionScopeOptions } from "./OrmTransaction";
@@ -84,7 +84,7 @@ export function contextToken(context: object): object {
   return token;
 }
 
-export function observedProvider(context: object, provider: DatabaseProvider): DatabaseProvider {
+export function observedProvider(context: object, provider: DatabaseProvider, models?: ViolationModels): DatabaseProvider {
   contextProviders.set(context, provider);
   const token = contextToken(context);
   const authority = rootAuthority(provider);
@@ -92,7 +92,7 @@ export function observedProvider(context: object, provider: DatabaseProvider): D
     if (uncertainContexts.has(token)) return Promise.reject(new TransactionOutcomeUnknownError());
     // Known SQLSTATEs (unique, foreign key, check, not null, lock timeout)
     // reach the context's caller as ORM errors; the outcome check sees the raw one.
-    const guarded = () => operation().catch((error) => { if (postgresTransactionCapability(provider)?.isOutcomeUncertain?.(error)) uncertainContexts.add(token); throw translateDatabaseError(error); });
+    const guarded = () => operation().catch((error) => { if (postgresTransactionCapability(provider)?.isOutcomeUncertain?.(error)) uncertainContexts.add(token); const translated = translateDatabaseError(error); throw models === undefined ? translated : describeViolation(translated, models); });
     if (!view) return guarded();
     const frame = view.frame;
     if (frame.authority !== authority || !view.enrolled.has(token) || frame.state !== "active" || frame.activeChild !== undefined) {

package/library/orm/errors.ts

@@ -103,7 +103,7 @@ export class EntityNotMappedError extends OrmError {
         ? `No entity or dynamic model named "${name}" is registered in this DbContext. Register a dynamic table first: options.model.registerModel(buildDynamicModel({ name: "${name}", fields: [...] })).`
         : kind === "plain"
           ? `A plain object is not an entity class. For a dynamic table add the row through its set: db.setByName("Table").add(row).`
-          : `Type "${name}" is not mapped in this DbContext. Add it to ormModule({ entities: [...] }) and annotate it with @Entity().`,
+          : `Type "${name}" is not mapped in this DbContext. Declare a set for it in the context (this.set(${name})) or add it to entities of ormBazis, and annotate it with @Entity().`,
     );
   }
 }
@@ -168,6 +168,13 @@ export class OrmUndeclaredConflictTargetError extends OrmError {
 export class UniqueViolationError extends DbUpdateError {
   readonly constraint: string | undefined;
   readonly table: string | undefined;
+  /**
+   * The properties of the index or key that rejected the value, when a context
+   * with the entity of the table made the call; otherwise empty.
+   */
+  properties: readonly string[] = [];
+  /** `conflict` of the index: what to tell the client. */
+  conflict: string | undefined;
 
   constructor(cause: object) {
     const field = (name: string): string | undefined => {
@@ -284,3 +291,34 @@ export class OrmValidationError extends DbUpdateError {
     super(`Validation failed for "${entityName}": ${errors.map((error) => error.message).join("; ")}`);
   }
 }
+
+/** What a context knows of a table, to name the properties of a violated constraint. */
+export interface ViolationModels {
+  readonly entities: readonly {
+    readonly tableName: string;
+    readonly keyName?: string;
+    readonly key: readonly { readonly propertyName: string }[];
+    readonly properties: readonly { readonly propertyName: string; readonly columnName: string }[];
+    readonly indexes: readonly { readonly name: string; readonly columns: readonly string[]; readonly unique: boolean; readonly conflict?: string }[];
+  }[];
+}
+
+/** Names the properties behind a unique violation by the model of the context. Returns the same error. */
+export function describeViolation(error: unknown, models: ViolationModels): unknown {
+  if (!(error instanceof UniqueViolationError) || error.constraint === undefined || error.properties.length > 0) return error;
+  for (const entity of models.entities) {
+    if (error.table !== undefined && entity.tableName !== error.table) continue;
+    const index = entity.indexes.find((item) => item.unique && item.name === error.constraint);
+    if (index !== undefined) {
+      error.properties = index.columns.map((column) => entity.properties.find((property) => property.columnName === column)?.propertyName ?? column);
+      error.conflict = index.conflict;
+      return error;
+    }
+    // `pk_<table>` is the name this ORM gives; `<table>_pkey` is PostgreSQL's own, from an older schema.
+    if (error.constraint === (entity.keyName ?? `pk_${entity.tableName}`) || error.constraint === `${entity.tableName}_pkey`) {
+      error.properties = entity.key.map((property) => property.propertyName);
+      return error;
+    }
+  }
+  return error;
+}

package/library/orm/index.ts

@@ -12,6 +12,7 @@ export {
   OneToMany,
   QueryFilter,
   Required,
+  Nullable,
   Schema,
   SoftDelete,
   UpdatedAt,

package/library/terminal/messages.ts

@@ -148,7 +148,7 @@ const en = {
       dns: "the host name does not resolve — check the address",
       database: "the database does not exist — create it or fix the name",
       deadline: "give connect() its own deadline and fail with a clear message",
-      raiseLimit: "or raise the limit: runApp(…, { kernel: { startupTimeoutMs } })",
+      raiseLimit: "or raise the limit: @App({ kernel: { startupTimeoutMs } })",
     },
   },
   schema: { add: "+", none: "schema is up to date", warnings: "schema warnings" },
@@ -168,7 +168,7 @@ const en = {
   ready: {
     running: (app: string, ms: string) => `${app} is running · ready in ${ms}`,
     local: "Local", network: "Network", health: "Health", docs: "OpenAPI",
-    notExposed: (host: string) => `not exposed — listening on ${host} (set HOST=0.0.0.0)`,
+    notExposed: (host: string) => `not exposed — listening on ${host} (set BAZIS_HTTP__HOST=0.0.0.0)`,
     watching: (src: string) => `watching ${src} · restarts on change · logs below · Ctrl+C to stop`,
     noWatch: "logs below · Ctrl+C to stop",
     worker: (app: string, ms: string) => `${app} started · ready in ${ms}`,
@@ -240,7 +240,7 @@ const en = {
     codegenSkipped: "codegen skipped (--no-codegen) — run bazis codegen",
     needsDb: "this module uses a database: connect one with @Infra({ db: ormBazisConnect(dbConfig) })",
     needsTable: (moduleFile: string) => `its table is not created: add ensureCreated: true to ormBazis in ${moduleFile}, or write a migration`,
-    needsCache: "this module caches: pass runApp(AppModule, { cache: memory() })",
+    needsCache: "this module caches: add cache: memory() to @App",
     keptOnFailure: "scaffold files were kept — fix the error and run bazis codegen",
   },
   workflow: {
@@ -325,7 +325,7 @@ const ru: Messages = {
       dns: "имя хоста не разрешается — проверьте адрес",
       database: "базы данных нет — создайте её или исправьте имя",
       deadline: "дайте connect() свой срок и понятную ошибку",
-      raiseLimit: "или увеличьте предел: runApp(…, { kernel: { startupTimeoutMs } })",
+      raiseLimit: "или увеличьте предел: @App({ kernel: { startupTimeoutMs } })",
     },
   },
   schema: { add: "+", none: "схема актуальна", warnings: "предупреждения схемы" },
@@ -345,7 +345,7 @@ const ru: Messages = {
   ready: {
     running: (app, ms) => `${app} работает · готово за ${ms}`,
     local: "Локально", network: "Сеть", health: "Здоровье", docs: "OpenAPI",
-    notExposed: (host) => `недоступно снаружи — слушает ${host} (задайте HOST=0.0.0.0)`,
+    notExposed: (host) => `недоступно снаружи — слушает ${host} (задайте BAZIS_HTTP__HOST=0.0.0.0)`,
     watching: (src) => `слежу за ${src} · перезапуск при изменениях · журнал ниже · Ctrl+C — остановить`,
     noWatch: "журнал ниже · Ctrl+C — остановить",
     worker: (app, ms) => `${app} запущено · готово за ${ms}`,
@@ -417,7 +417,7 @@ const ru: Messages = {
     codegenSkipped: "кодогенерация пропущена (--no-codegen) — запустите bazis codegen",
     needsDb: "модулю нужна база данных: подключите её через @Infra({ db: ormBazisConnect(dbConfig) })",
     needsTable: (moduleFile) => `таблицу шаблон не создаёт: добавьте ensureCreated: true в ormBazis в ${moduleFile} или напишите миграцию`,
-    needsCache: "модуль кэширует: передайте runApp(AppModule, { cache: memory() })",
+    needsCache: "модуль кэширует: добавьте cache: memory() в @App",
     keptOnFailure: "файлы модуля оставлены — исправьте ошибку и запустите bazis codegen",
   },
   workflow: {

package/library/validation/README.md

@@ -48,7 +48,7 @@ More scenarios (complex conditions, async, nested objects) are in
 | `RuleEngine.ts` | the engine: one pass over the plan, sync/async, nested, cycle protection |
 | `RuleCompiler.ts` | compiles class rules into a plan + WeakMap cache (RegExp, enum Set) |
 | `RuleSet.ts` | rules as data without a class: `Validator.ruleSet({ field: options })` |
-| `MessageRegistry.ts` | message templates, placeholders, priority local > global > built-in; built-in texts are English, `RU_VALIDATION_MESSAGES` is a Russian set for `setDefaults` and `runApp({ language: "ru" })` |
+| `MessageRegistry.ts` | message templates, placeholders, priority local > global > built-in; built-in texts are English, `RU_VALIDATION_MESSAGES` is a Russian set for `setDefaults` and `@App({ language: "ru" })` |
 | `metadata.ts` | stores rules through `context.metadata` / `Symbol.metadata` |
 | `types/ValidatorOptions.ts` | all decorator options |
 | `types/ValidationCode.ts` | error codes |

package/library/validation/SPEC.md

@@ -473,7 +473,7 @@ so a valid object pays no allocations for it.
 Template priority: **the decorator's local `message` > global (`setDefaultMessages`) >
 built-in**. A string returned from `custom` wins over all of them.
 Built-in messages are English (`EN_VALIDATION_MESSAGES`); `RU_VALIDATION_MESSAGES` is a Russian set for `setDefaultMessages`.
-An HTTP application picks the language with `runApp({ language: "ru", messages })`: each
+An HTTP application picks the language with `@App({ language: "ru", messages })`: each
 `ValidationError` built from a template carries `params`, and the HTTP error handler
 re-renders it in the application language (a rule's own `message` has no `params` and
 stays as is). Priority there: `messages` > `setDefaultMessages` > the language set > English.

package/library/workflow/index.ts

@@ -20,6 +20,7 @@ export {
   type ProcessNode,
   type ProcessSettings,
 } from "./ProcessDocument";
+export type { BoundaryNodeKind, ConfiguredNodeKind, InputMapping, NodeConfigs, ProcessNodeOf, RetryPolicy, TimerConfig, TypedProcessFlow, TypedProcessNode } from "./nodeConfigs";
 export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, ISO_MOMENT, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
 export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, secretNames, type InstanceData } from "./paths";