bazis 0.136.0 → 0.137.0

package/core/agent/session/entities.ts

@@ -1,4 +1,4 @@
-import { Column, DbContext, Entity, Index, Key } from "../../../library/orm";
+import { Column, DbContext, Entity, Index, Key, Nullable } from "../../../library/orm";
 
 /** Immutable v1 schema. These tables are owned exclusively by AgentSessionDbContext. */
 @Entity({ table: "bazis_agent_sessions_v1" })
@@ -6,42 +6,42 @@ import { Column, DbContext, Entity, Index, Key } from "../../../library/orm";
 @Index(["sessionId"], { unique: true })
 export class AgentSessionRowV1 {
   @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
-  @Column({ type: "uuid" }) sessionId = "";
-  @Column({ type: "uuid" }) invocationId = "";
-  @Column({ type: "text" }) createKey = "";
-  @Column({ type: "text" }) requestBinding = "";
-  @Column({ type: "text" }) ownerSubject = "";
-  @Column({ type: "text", nullable: true }) tenant?: string;
-  @Column({ type: "text" }) agentName = "";
-  @Column({ type: "text" }) implementationVersion = "";
-  @Column({ type: "text" }) bindingHash = "";
-  @Column({ type: "text" }) state = "created";
-  @Column({ type: "integer" }) revision = 0;
-  @Column({ type: "integer" }) steps = 0;
-  @Column({ type: "boolean" }) stopRequested = false;
-  @Column({ type: "integer" }) checkpointRevision = 0;
-  @Column({ type: "text", nullable: true }) ownerId?: string;
-  @Column({ type: "integer" }) ownerEpoch = 0;
-  @Column({ type: "datetime", nullable: true }) ownerLeaseUntil?: Date;
-  @Column({ type: "text", nullable: true }) runCommandId?: string;
-  @Column({ type: "datetime", nullable: true }) runDeadline?: Date;
-  @Column({ type: "integer" }) nextSequence = 1;
-  @Column({ type: "integer", nullable: true }) pendingIntentSequence?: number;
-  @Column({ type: "boolean" }) admissionReserved = false;
-  @Column({ type: "datetime" }) createdAt = new Date();
-  @Column({ type: "datetime" }) updatedAt = new Date();
+  @Nullable() @Column({ type: "uuid" }) sessionId = "";
+  @Nullable() @Column({ type: "uuid" }) invocationId = "";
+  @Nullable() @Column({ type: "text" }) createKey = "";
+  @Nullable() @Column({ type: "text" }) requestBinding = "";
+  @Nullable() @Column({ type: "text" }) ownerSubject = "";
+  @Nullable() @Column({ type: "text" }) tenant?: string;
+  @Nullable() @Column({ type: "text" }) agentName = "";
+  @Nullable() @Column({ type: "text" }) implementationVersion = "";
+  @Nullable() @Column({ type: "text" }) bindingHash = "";
+  @Nullable() @Column({ type: "text" }) state = "created";
+  @Nullable() @Column({ type: "integer" }) revision = 0;
+  @Nullable() @Column({ type: "integer" }) steps = 0;
+  @Nullable() @Column({ type: "boolean" }) stopRequested = false;
+  @Nullable() @Column({ type: "integer" }) checkpointRevision = 0;
+  @Nullable() @Column({ type: "text" }) ownerId?: string;
+  @Nullable() @Column({ type: "integer" }) ownerEpoch = 0;
+  @Nullable() @Column({ type: "datetime" }) ownerLeaseUntil?: Date;
+  @Nullable() @Column({ type: "text" }) runCommandId?: string;
+  @Nullable() @Column({ type: "datetime" }) runDeadline?: Date;
+  @Nullable() @Column({ type: "integer" }) nextSequence = 1;
+  @Nullable() @Column({ type: "integer" }) pendingIntentSequence?: number;
+  @Nullable() @Column({ type: "boolean" }) admissionReserved = false;
+  @Nullable() @Column({ type: "datetime" }) createdAt = new Date();
+  @Nullable() @Column({ type: "datetime" }) updatedAt = new Date();
 }
 
 @Entity({ table: "bazis_agent_session_checkpoints_v1" })
 @Index(["sessionId", "checkpointRevision"], { unique: true })
 export class AgentSessionCheckpointRowV1 {
   @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
-  @Column({ type: "uuid" }) sessionId = "";
-  @Column({ type: "integer" }) checkpointRevision = 0;
-  @Column({ type: "text" }) bindingHash = "";
-  @Column({ type: "text" }) keyId = "";
-  @Column({ type: "text" }) ciphertext = "";
-  @Column({ type: "datetime" }) createdAt = new Date();
+  @Nullable() @Column({ type: "uuid" }) sessionId = "";
+  @Nullable() @Column({ type: "integer" }) checkpointRevision = 0;
+  @Nullable() @Column({ type: "text" }) bindingHash = "";
+  @Nullable() @Column({ type: "text" }) keyId = "";
+  @Nullable() @Column({ type: "text" }) ciphertext = "";
+  @Nullable() @Column({ type: "datetime" }) createdAt = new Date();
 }
 
 @Entity({ table: "bazis_agent_session_journal_v1" })
@@ -49,26 +49,26 @@ export class AgentSessionCheckpointRowV1 {
 @Index(["sessionId", "commandId"], { unique: false })
 export class AgentSessionJournalRowV1 {
   @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
-  @Column({ type: "uuid" }) eventId = "";
-  @Column({ type: "uuid" }) sessionId = "";
-  @Column({ type: "integer" }) sequence = 0;
-  @Column({ type: "integer" }) aggregateRevision = 0;
-  @Column({ type: "text" }) kind = "";
-  @Column({ type: "text", nullable: true }) commandId?: string;
-  @Column({ type: "text" }) projectionJson = "{}";
-  @Column({ type: "text", nullable: true }) binding?: string;
-  @Column({ type: "datetime" }) occurredAt = new Date();
+  @Nullable() @Column({ type: "uuid" }) eventId = "";
+  @Nullable() @Column({ type: "uuid" }) sessionId = "";
+  @Nullable() @Column({ type: "integer" }) sequence = 0;
+  @Nullable() @Column({ type: "integer" }) aggregateRevision = 0;
+  @Nullable() @Column({ type: "text" }) kind = "";
+  @Nullable() @Column({ type: "text" }) commandId?: string;
+  @Nullable() @Column({ type: "text" }) projectionJson = "{}";
+  @Nullable() @Column({ type: "text" }) binding?: string;
+  @Nullable() @Column({ type: "datetime" }) occurredAt = new Date();
 }
 
 @Entity({ table: "bazis_agent_session_admission_v1" })
 @Index(["bucket"], { unique: true })
 export class AgentSessionAdmissionRowV1 {
   @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
-  @Column({ type: "text" }) bucket = "";
-  @Column({ type: "text" }) configHash = "";
-  @Column({ type: "integer" }) maxActiveRuns = 8;
-  @Column({ type: "integer" }) activeReservations = 0;
-  @Column({ type: "datetime" }) updatedAt = new Date();
+  @Nullable() @Column({ type: "text" }) bucket = "";
+  @Nullable() @Column({ type: "text" }) configHash = "";
+  @Nullable() @Column({ type: "integer" }) maxActiveRuns = 8;
+  @Nullable() @Column({ type: "integer" }) activeReservations = 0;
+  @Nullable() @Column({ type: "datetime" }) updatedAt = new Date();
 }
 
 export class AgentSessionDbContext extends DbContext {

package/core/http/Decorators/metadata.ts

@@ -1,5 +1,6 @@
 import type { Class } from "../../di";
 import type { ActionFilterHooks, HttpMiddleware } from "../Middleware/types";
+import type { HttpResult } from "../Results/HttpResult";
 
 // Same one-line polyfill as the validation module: Bun executes TC39
 // decorators natively, Symbol.metadata may be missing in the runtime.
@@ -26,6 +27,8 @@ export interface CatchDeclaration {
 export interface ActionMeta {
   routes: RouteDeclaration[];
   httpCode?: number;
+  /** `nullAs` of the route options: the result that stands for `null`. */
+  nullAs?: () => HttpResult;
   produces?: string;
   consumes?: string;
   version?: string;

package/core/http/Decorators/routes.ts

@@ -1,5 +1,6 @@
 import type { HttpMiddleware } from "../Middleware/types";
 import { HttpSetupError } from "../Errors/HttpError";
+import type { HttpResult } from "../Results/HttpResult";
 import { ownActionMeta, ownRoutes } from "./metadata";
 
 type MethodDecorator = (value: (...args: never[]) => unknown, context: ClassMethodDecoratorContext) => void;
@@ -27,6 +28,11 @@ export interface RouteOptions {
   readonly version?: string;
   /** Route middleware (= `@Middleware` on the method). */
   readonly middleware?: readonly HttpMiddleware[];
+  /**
+   * What `null` or `undefined` from the action means, as a result helper:
+   * `{ nullAs: NotFound }` answers 404 with the standard body instead of 204.
+   */
+  readonly nullAs?: () => HttpResult;
   /** Maximum body size: an integer and a binary unit together, for example `4mb`. */
   readonly maxBodySize?: `${bigint}${"b" | "kb" | "mb" | "gb"}`;
 }
@@ -59,6 +65,12 @@ function route(httpMethod: string, templateOrOptions?: string | RouteOptions, ma
       if (options.middleware !== undefined) {
         action.middleware.push(...options.middleware);
       }
+      if (options.nullAs !== undefined) {
+        if (typeof options.nullAs !== "function") {
+          throw new HttpSetupError("nullAs must be a result helper, for example NotFound.");
+        }
+        action.nullAs = options.nullAs;
+      }
       if (options.maxBodySize !== undefined) {
         const maxBodyBytes = parseRouteMaxBodySize(options.maxBodySize);
         if (action.maxBodyBytes !== undefined && action.maxBodyBytes !== maxBodyBytes) {

package/core/http/Errors/HttpError.ts

@@ -1,6 +1,6 @@
 import { KernelError } from "../../kernel";
 import type { ModelValidationIssue } from "../Binding/modelValidator";
-import { englishHttpMessage, type HttpMessageKey, type LocalizedMessage, type MessageParams } from "./messages";
+import { englishHttpMessage, STATUS_MESSAGE_KEYS, type HttpMessageKey, type LocalizedMessage, type MessageParams } from "./messages";
 
 /**
  * Base class for errors that map directly to an HTTP response.
@@ -59,6 +59,14 @@ export class NotFoundError extends HttpError {
   }
 }
 
+/** The request conflicts with what is stored: the name is taken, the record changed meanwhile. */
+export class ConflictError extends HttpError {
+  constructor(message?: string, details?: unknown) {
+    const [text, localized] = textOf(message, "conflict");
+    super(409, text, details, localized);
+  }
+}
+
 export class MethodNotAllowedError extends HttpError {
   constructor(readonly allow: readonly string[]) {
     super(405, englishHttpMessage("methodNotAllowed"), undefined, { key: "methodNotAllowed" });
@@ -116,3 +124,9 @@ export function frameworkBadRequest(key: HttpMessageKey, params?: MessageParams,
  * KernelError: the start reports it as a configuration error of the code.
  */
 export class HttpSetupError extends KernelError {}
+
+/** An error of a status with the framework text for it, translated at the response: what an empty result helper stands for. */
+export function httpErrorOfStatus(status: number): HttpError {
+  const key = STATUS_MESSAGE_KEYS[status] ?? (status >= 500 ? "serverError" : "clientError");
+  return new HttpError(status, englishHttpMessage(key), undefined, { key });
+}

package/core/http/HttpServer.ts

@@ -19,10 +19,10 @@ import { defaultAuthorizeChecks } from "./Authorization/metadata";
 import type { Router } from "./Routing/Router";
 import { parseRequestPath } from "./Routing/template";
 import { assertVersioningOptions, createVersionReader, type VersionReader } from "./Versioning/VersionReader";
-import { HTTP_ERROR_HOOK, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOrder } from "./middlewareTokens";
+import { HTTP_ERROR_HOOK, HTTP_ERROR_MAPPER, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOrder } from "./middlewareTokens";
 import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions, HttpServerOptions } from "./options";
 import { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
-import { HttpSetupError } from "./Errors/HttpError";
+import { HttpSetupError, type HttpError } from "./Errors/HttpError";
 import { clientAddress, trustedProxies, type TrustedProxies } from "./HttpContext/clientAddress";
 import { EN_HTTP_MESSAGES, formatMessage, languageHeaders, type HttpMessageKey, type MessageParams, type SelectedLanguage } from "./Errors/messages";
 import { getModelValidator, type ModelValidator } from "./Binding/modelValidator";
@@ -180,6 +180,7 @@ export class HttpServer implements HostedService {
         ...(this.options.languages ? { languages: this.options.languages } : {}),
         ...this.options.errorHandler,
         onUnexpectedError: this.collectErrorHook(),
+        map: this.collectErrorMapper(),
       }),
     );
     this.shortCircuitChain = [...serverChain];
@@ -332,6 +333,22 @@ export class HttpServer implements HostedService {
     };
   }
 
+  /** Explicit `options.errorHandler.map` first, then DI {@link HTTP_ERROR_MAPPER} mappers; the first answer wins. */
+  private collectErrorMapper(): ((error: unknown) => HttpError | undefined) | undefined {
+    const explicit = this.options.errorHandler?.map;
+    const mappers = [...(explicit === undefined ? [] : [explicit]), ...this.resolver.resolveAll(HTTP_ERROR_MAPPER)];
+    if (mappers.length === 0) {
+      return undefined;
+    }
+    return (error) => {
+      for (const mapper of mappers) {
+        const mapped = mapper(error);
+        if (mapped !== undefined) return mapped;
+      }
+      return undefined;
+    };
+  }
+
   /** Explicit `options.routeMiddlewareComposer` (order 0) merged with DI {@link ROUTE_MIDDLEWARE_COMPOSER}. */
   private collectRouteComposer(): RouteMiddlewareComposer | undefined {
     const explicit = this.options.routeMiddlewareComposer

package/core/http/Middleware/errorHandler.ts

@@ -28,6 +28,12 @@ export interface ErrorHandlerOptions {
    * mistake and is not logged or sent to `onUnexpectedError`.
    */
   status?: (error: unknown) => number | undefined;
+  /**
+   * Turns a non-{@link HttpError} failure into an HttpError, with its own text
+   * and details; `HTTP_ERROR_MAPPER` registrations are merged in. Asked before
+   * {@link status}. A mapped 5xx is still logged as unexpected.
+   */
+  map?: (error: unknown) => HttpError | undefined;
   /**
    * Logger for unexpected errors when {@link logError} is absent: one `error`
    * line with the method, path, request id and the redacted error. The server
@@ -114,7 +120,16 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
   return async (ctx, next) => {
     try {
       await next();
-    } catch (error) {
+    } catch (thrown) {
+      let error = thrown;
+      if (!(thrown instanceof HttpError) && options.map !== undefined) {
+        let mapped: HttpError | undefined;
+        try { mapped = options.map(thrown); } catch { mapped = undefined; }
+        if (mapped instanceof HttpError) {
+          if (mapped.status >= 500) safelyReportUnexpected(options, log, ctx, thrown);
+          error = mapped;
+        }
+      }
       const selected = options.languages?.select(ctx.header("accept-language"));
       const text = textRenderer(selected?.localize);
       const language = languageHeaders(options.languages, selected);

package/core/http/OpenApi/openApiDocument.ts

@@ -87,7 +87,42 @@ function collectOpenApiOperations(
       }
     }
   }
-  return operations;
+  return withCreatedLocation(operations);
+}
+
+/**
+ * Documents the automatic `Location` of a 201: the server sets it when the
+ * body has `id` and a GET route answers `<path>/<id>`.
+ */
+function withCreatedLocation(operations: OpenApiCatalogOperation[]): OpenApiCatalogOperation[] {
+  const itemPaths = new Set<string>();
+  for (const operation of operations) {
+    const parent = /^(.*)\/\{[^{}/]+\}$/u.exec(operation.path)?.[1];
+    if (operation.httpMethod === "GET" && parent !== undefined) {
+      itemPaths.add(parent);
+    }
+  }
+  return operations.map((operation) => {
+    const created = operation.responses["201"];
+    if (!created || !itemPaths.has(operation.path.replace(/\/+$/u, ""))) {
+      return operation;
+    }
+    return {
+      ...operation,
+      responses: {
+        ...operation.responses,
+        "201": {
+          ...created,
+          headers: {
+            Location: {
+              description: "Address of the created item, when the response has `id`.",
+              schema: { type: "string" },
+            },
+          },
+        },
+      },
+    };
+  });
 }
 
 interface CreateOperationInput {
@@ -140,7 +175,7 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
             },
           }
         : { description: "Success" },
-      ...errorResponses(errorStatuses(input.bindings, authorized, generatedOperation?.errors)),
+      ...errorResponses(errorStatuses(input.bindings, authorized, generatedOperation?.errors, input.action)),
     },
     authorized,
     ...(version !== undefined ? { versions: [version] } : {}),
@@ -380,15 +415,19 @@ function successStatus(method: string, action: ActionMeta, generated: number | u
 /**
  * Errors the operation can answer with: 400 when the request carries values
  * that are converted or validated (body, list query, query and header values
- * and models, typed route parameters), 401/403 under @Authorize, and the
- * errors the method body returns or throws itself.
+ * and models, typed route parameters), 401/403 under @Authorize, the status of
+ * `nullAs`, and the errors the method body returns or throws itself.
  */
 function errorStatuses(
   bindings: readonly ParameterBinding[],
   authorized: boolean,
   generated: readonly number[] | undefined,
+  action: ActionMeta,
 ): number[] {
   const statuses = new Set(generated ?? []);
+  // `nullAs: NotFound` is an answer of the route the method body does not show.
+  const instead = action.nullAs?.().status;
+  if (instead !== undefined && instead >= 400) statuses.add(instead);
   const validated = bindings.some((binding) =>
     binding.source === "body" || binding.source === "list" || binding.source === "query" || binding.source === "header"
     || binding.source === "queryModel" || binding.source === "headerModel"

package/core/http/Results/normalize.ts

@@ -1,4 +1,5 @@
 import type { HttpContext } from "../HttpContext/HttpContext";
+import { httpErrorOfStatus } from "../Errors/HttpError";
 import { HttpResult } from "./HttpResult";
 
 /** Per-action response defaults coming from decorators. */
@@ -7,6 +8,26 @@ export interface ResponseDefaults {
   httpCode?: number;
   /** `@Produces(...)` value. */
   produces?: string;
+  /** `nullAs` of the route: the result that stands for `null` and `undefined`. */
+  nullAs?: () => HttpResult;
+  /**
+   * Address of a created item for an automatic `Location` header: given the
+   * `id` of a 201 body, returns the address or `undefined` when the
+   * application has no GET route for it.
+   */
+  locate?: (ctx: HttpContext, id: string | number) => string | undefined;
+}
+
+/** `id` of a 201 body that can name the created item. */
+function createdItemId(body: unknown): string | number | undefined {
+  if (body === null || typeof body !== "object" || Array.isArray(body) || isBinaryBody(body)) {
+    return undefined;
+  }
+  const id = (body as { id?: unknown }).id;
+  if (typeof id === "number" && Number.isFinite(id)) {
+    return id;
+  }
+  return typeof id === "string" && id !== "" ? id : undefined;
 }
 
 type ResponseBody = ConstructorParameters<typeof Response>[0];
@@ -26,15 +47,24 @@ function isBinaryBody(body: unknown): body is Blob | Uint8Array | ArrayBuffer |
  * - `string` — text/plain (unless `@Produces` says otherwise);
  * - `Blob`/bytes/stream — binary passthrough;
  * - any other object/array/number/boolean — JSON;
- * - `undefined`/`null` — empty body, 204 (or `@HttpCode`).
+ * - `undefined`/`null` — empty body, 204 (or `@HttpCode`), unless the route says `nullAs`.
  *
  * Status priority: result helper > `@HttpCode` > `ctx.res.status(...)` > default.
  * Headers from `ctx.res.header(...)` are merged into every non-raw response.
+ *
+ * A 201 without `Location` whose body is an object with `id` gets
+ * `Location: <request path>/<id>` when a GET route answers that address.
  */
 export function normalizeResult(result: unknown, ctx: HttpContext, defaults: ResponseDefaults): Response {
   if (result instanceof Response) {
     return result;
   }
+  if ((result === null || result === undefined) && defaults.nullAs !== undefined) {
+    const instead = defaults.nullAs();
+    // An error goes through the error handler: the standard body, in the language of the request.
+    if (instead.status >= 400) throw httpErrorOfStatus(instead.status);
+    result = instead;
+  }
 
   const builderStatus = ctx.res.statusOverride;
   const builderHeaders = ctx.res.headers;
@@ -63,6 +93,13 @@ export function normalizeResult(result: unknown, ctx: HttpContext, defaults: Res
   for (const [name, value] of builderHeaders) {
     headers.append(name, value);
   }
+  if (status === 201 && defaults.locate && !headers.has("location")) {
+    const id = createdItemId(body);
+    const location = id === undefined ? undefined : defaults.locate(ctx, id);
+    if (location !== undefined) {
+      headers.set("location", location);
+    }
+  }
 
   let payload: ResponseBody = null;
   if (body === undefined || body === null) {

package/core/http/Results/results.ts

@@ -5,8 +5,11 @@ export function Ok(body?: unknown): HttpResult {
   return new HttpResult(200, body);
 }
 
-/** 201 Created with optional Location header. */
-export function Created(location?: string, body?: unknown): HttpResult {
+/**
+ * 201 Created. Without `location` the server derives it: a body with `id`
+ * gets `Location: <request path>/<id>` when a GET route answers that address.
+ */
+export function Created(body?: unknown, location?: string): HttpResult {
   return new HttpResult(201, body, location ? [["location", location]] : undefined);
 }
 

package/core/http/Routing/RouterBuilder.ts

@@ -23,7 +23,7 @@ export interface RegisteredRoute {
   readonly anonymous: boolean;
 }
 import { Router, type RouteAction } from "./Router";
-import { joinPaths, parseTemplate } from "./template";
+import { joinPaths, parseRequestPath, parseTemplate } from "./template";
 
 type ControllerInstance = Record<string | symbol, (...args: unknown[]) => unknown>;
 
@@ -43,6 +43,8 @@ export class RouterBuilder {
   private readonly authorizeComposer: RouteMiddlewareComposer;
   /** Every route of the last {@link build}, in registration order. */
   readonly routes: RegisteredRoute[] = [];
+  /** Router of the last {@link build}: automatic `Location` looks up GET routes in it. */
+  private router?: Router;
 
   constructor(
     /** Middleware prepended to every route: [logger?, cors?, errorHandler, ...global]. */
@@ -58,6 +60,7 @@ export class RouterBuilder {
 
   build(controllers: readonly Class<object>[]): Router {
     const router = new Router();
+    this.router = router;
     for (const controllerClass of controllers) {
       const meta = controllerMetaOf(controllerClass);
       if (!meta?.isController) {
@@ -122,6 +125,23 @@ export class RouterBuilder {
     }
   }
 
+  /**
+   * Address of an item created by a request: the request path plus `/<id>`,
+   * but only when a GET route of this application answers it.
+   */
+  private locateCreated(ctx: HttpContext, id: string | number): string | undefined {
+    const segments = parseRequestPath(ctx.url.pathname);
+    if (!segments || !this.router) {
+      return undefined;
+    }
+    const value = String(id);
+    const match = this.router.match("GET", [...segments, value], ctx.apiVersion);
+    if (match.kind !== "matched") {
+      return undefined;
+    }
+    return `${ctx.url.pathname.replace(/\/+$/u, "")}/${encodeURIComponent(value)}`;
+  }
+
   /**
    * Precompiles binding + ActionFilter.before as a boundary middleware and
    * controller execution + ActionFilter.after as the terminal. This lets
@@ -138,7 +158,12 @@ export class RouterBuilder {
     const catches = meta.catches;
     const bindings = resolveGeneratedBindings(controllerClass, methodName);
     assertBindingsFresh(controllerClass, methodName, bindings);
-    const responseDefaults = { httpCode: action.httpCode, produces: action.produces };
+    const responseDefaults = {
+      httpCode: action.httpCode,
+      nullAs: action.nullAs,
+      produces: action.produces,
+      locate: (ctx: HttpContext, id: string | number) => this.locateCreated(ctx, id),
+    };
     const bindingDefaults = { consumes: action.consumes };
     const token = controllerClass as unknown as Token<object>;
     const boundArguments = new WeakMap<HttpContext, readonly unknown[]>();

package/core/http/index.ts

@@ -18,10 +18,12 @@ export type { OpenApiDocsOptions } from "../../library/openapi";
 export { composeRouteMiddlewareComposers } from "./composeRouteMiddlewareComposers";
 export {
   HTTP_ERROR_HOOK,
+  HTTP_ERROR_MAPPER,
   ROUTE_MIDDLEWARE_COMPOSER,
   SERVER_MIDDLEWARE,
   sortByOrder,
   type HttpErrorHook,
+  type HttpErrorMapper,
   type RouteMiddlewareComposerRegistration,
   type ServerMiddlewareRegistration,
 } from "./middlewareTokens";
@@ -131,6 +133,7 @@ export type { ActionFilterHooks, HttpMiddleware } from "./Middleware/types";
 // Errors
 export {
   BadRequestError,
+  ConflictError,
   ForbiddenError,
   HttpError,
   HttpSetupError,

package/core/http/middlewareTokens.ts

@@ -1,4 +1,5 @@
 import { createToken } from "../di";
+import type { HttpError } from "./Errors/HttpError";
 import type { HttpContext } from "./HttpContext/HttpContext";
 import type { HttpMiddleware } from "./Middleware/types";
 import type { RouteMiddlewareComposer } from "./options";
@@ -39,6 +40,17 @@ export type HttpErrorHook = (ctx: HttpContext, error: unknown) => void;
 /** Enumerable token: register any number of unexpected-error hooks. */
 export const HTTP_ERROR_HOOK = createToken<HttpErrorHook>("BazisHttpErrorHook");
 
+/**
+ * Turns a failure that is not an {@link HttpError} into one: a module that owns
+ * a kind of errors says how they answer. `undefined` leaves the error to the
+ * next mapper and then to 500. The ORM registers one for database errors.
+ * Collected via `resolveAll`.
+ */
+export type HttpErrorMapper = (error: unknown) => HttpError | undefined;
+
+/** Enumerable token: register any number of error mappers. */
+export const HTTP_ERROR_MAPPER = createToken<HttpErrorMapper>("BazisHttpErrorMapper");
+
 /** Stable order by `order ?? 0` (registration order preserved within a tier). */
 export function sortByOrder<T extends { readonly order?: number }>(items: readonly T[]): T[] {
   return [...items]

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.136.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.137.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

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/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,