bazis 0.96.1

package/library/orm/Query/SqlTranslator.ts

@@ -0,0 +1,195 @@
+import { OrmError } from "../errors";
+import { renderPostgresOnConflictDoNothing, renderPostgresSkipLocked } from "../Providers/PostgresDialect";
+import type { EntityModel, PropertyModel } from "../Metadata/types";
+import type { SqlDialect, SqlParam } from "../Providers/types";
+import { encodeProperty } from "../Providers/propertyConversion";
+import type { Condition } from "./conditions";
+import type { QueryPlan } from "./QueryPlan";
+
+export interface CompiledSql {
+  readonly sql: string;
+  readonly params: SqlParam[];
+}
+type ConditionValueEncoder = (property: PropertyModel, value: unknown) => SqlParam;
+
+/** Cache of the quoted column list per (model, dialect), built once. */
+const columnListCache = new WeakMap<EntityModel, Map<string, string>>();
+
+/** Quoted `"a", "b", ...` list of all entity columns (memoized). */
+export function quotedColumnList(model: EntityModel, dialect: SqlDialect): string {
+  let byDialect = columnListCache.get(model);
+  if (!byDialect) {
+    byDialect = new Map();
+    columnListCache.set(model, byDialect);
+  }
+  let list = byDialect.get(dialect.name);
+  if (list === undefined) {
+    list = model.properties.map((property) => dialect.quoteId(property.columnName)).join(", ");
+    byDialect.set(dialect.name, list);
+  }
+  return list;
+}
+
+/**
+ * Translates a query plan into parameterized SQL. Values go only into the
+ * parameter array (no concatenation of user data).
+ */
+export class SqlTranslator {
+  constructor(
+    private readonly model: EntityModel,
+    private readonly dialect: SqlDialect,
+  ) {}
+
+  /** SELECT of all columns (or a projection) with WHERE/ORDER/LIMIT/OFFSET. */
+  selectAll(plan: QueryPlan): CompiledSql {
+    const params: SqlParam[] = [];
+    const columns =
+      plan.projections.length > 0
+        ? plan.projections
+            .map(({ alias, property }) => {
+              const prop = this.requireProperty(property);
+              return `${this.dialect.quoteId(prop.columnName)} AS ${this.dialect.quoteId(alias)}`;
+            })
+            .join(", ")
+        : quotedColumnList(this.model, this.dialect);
+    let sql = `SELECT ${columns} FROM ${this.dialect.qualifyTable(this.model)}`;
+    sql += this.whereClause(plan, params);
+    sql += this.orderClause(plan);
+    sql += this.limitClause(plan, params);
+    if (plan.rowLock) {
+      sql += this.dialect.rowLockClause(plan.rowLock);
+      if (plan.skipLocked) sql += renderPostgresSkipLocked(this.dialect);
+    }
+    return { sql, params };
+  }
+
+  /** SELECT COUNT(*) with the same filters (without order/limit). */
+  selectCount(plan: QueryPlan): CompiledSql {
+    const params: SqlParam[] = [];
+    let sql = `SELECT COUNT(*) AS count FROM ${this.dialect.qualifyTable(this.model)}`;
+    sql += this.whereClause(plan, params);
+    return { sql, params };
+  }
+
+  /** Private immediate-DML renderers; the public query DSL remains unchanged. */
+  immediateUpdate(values: readonly { readonly property: PropertyModel; readonly value: SqlParam }[], conditions: readonly Condition[], encode: ConditionValueEncoder): CompiledSql {
+    const params: SqlParam[] = values.map((value) => value.value);
+    const assignments = values.map((value, index) => `${this.dialect.quoteId(value.property.columnName)} = ${this.dialect.parameter(index)}`).join(", ");
+    return { sql: `UPDATE ${this.dialect.qualifyTable(this.model)} SET ${assignments}${this.immediateWhere(conditions, params, encode)}`, params };
+  }
+
+  immediateDelete(conditions: readonly Condition[], encode: ConditionValueEncoder): CompiledSql {
+    const params: SqlParam[] = [];
+    return { sql: `DELETE FROM ${this.dialect.qualifyTable(this.model)}${this.immediateWhere(conditions, params, encode)}`, params };
+  }
+
+  private immediateWhere(conditions: readonly Condition[], params: SqlParam[], encode: ConditionValueEncoder): string {
+    if (conditions.length === 0) return "";
+    return ` WHERE ${conditions.map((condition) => this.condition(condition, params, encode)).join(" AND ")}`;
+  }
+
+  immediateInsert(values: readonly { readonly property: PropertyModel; readonly value: SqlParam }[], conflictColumns: readonly string[]): CompiledSql {
+    const params = values.map((value) => value.value);
+    const columns = values.map((value) => this.dialect.quoteId(value.property.columnName)).join(", ");
+    const placeholders = values.map((_value, index) => this.dialect.parameter(index)).join(", ");
+    return { sql: `INSERT INTO ${this.dialect.qualifyTable(this.model)} (${columns}) VALUES (${placeholders})${renderPostgresOnConflictDoNothing(this.dialect, conflictColumns)}`, params };
+  }
+
+  private whereClause(plan: QueryPlan, params: SqlParam[], encode: ConditionValueEncoder = (property, value) => encodeProperty(property, value, this.dialect)): string {
+    const parts: string[] = [];
+    if (!plan.ignoreQueryFilters) {
+      for (const filter of this.model.queryFilters) {
+        parts.push(this.condition(filter, params, encode));
+      }
+      if (this.model.softDeleteProperty) {
+        parts.push(this.condition({ kind: "null", property: this.model.softDeleteProperty, negated: false }, params, encode));
+      }
+    }
+    for (const condition of plan.conditions) {
+      parts.push(this.condition(condition, params, encode));
+    }
+    if (parts.length === 0) {
+      return "";
+    }
+    return ` WHERE ${parts.join(" AND ")}`;
+  }
+
+  private orderClause(plan: QueryPlan): string {
+    if (plan.orders.length === 0) {
+      return "";
+    }
+    const parts = plan.orders.map((order) => {
+      const column = this.requireProperty(order.property).columnName;
+      return `${this.dialect.quoteId(column)}${order.descending ? " DESC" : " ASC"}`;
+    });
+    return ` ORDER BY ${parts.join(", ")}`;
+  }
+
+  private limitClause(plan: QueryPlan, params: SqlParam[]): string {
+    let sql = "";
+    if (plan.limit !== undefined) {
+      sql += ` LIMIT ${this.dialect.parameter(params.length)}`;
+      params.push(plan.limit);
+    }
+    if (plan.offset !== undefined) {
+      sql += ` OFFSET ${this.dialect.parameter(params.length)}`;
+      params.push(plan.offset);
+    }
+    return sql;
+  }
+
+  private condition(condition: Condition, params: SqlParam[], encode: ConditionValueEncoder): string {
+    switch (condition.kind) {
+      case "compare": {
+        const property = this.requireProperty(condition.property);
+        const placeholder = this.dialect.parameter(params.length);
+        params.push(encode(property, condition.value));
+        // startsWith/endsWith/contains escape wildcards with `\`; this works
+        // only with an explicit `ESCAPE '\'` (otherwise `%`/`_` stay wildcards).
+        const escape = condition.escaped ? " ESCAPE '\\'" : "";
+        return `${this.dialect.quoteId(property.columnName)} ${condition.op} ${placeholder}${escape}`;
+      }
+      case "in": {
+        const property = this.requireProperty(condition.property);
+        if (condition.values.length === 0) {
+          return "0 = 1"; // an empty IN is always false
+        }
+        const placeholders = condition.values.map((value) => {
+          const placeholder = this.dialect.parameter(params.length);
+          params.push(encode(property, value));
+          return placeholder;
+        });
+        return `${this.dialect.quoteId(property.columnName)} IN (${placeholders.join(", ")})`;
+      }
+      case "tuples": {
+        if (condition.properties.length === 0 || condition.values.length === 0) return "0 = 1";
+        return `(${condition.values.map((tuple) => {
+          if (tuple.length !== condition.properties.length) throw new OrmError("Tuple predicate component count mismatch.");
+          return `(${tuple.map((value, index) => { const property = this.requireProperty(condition.properties[index]!); const placeholder = this.dialect.parameter(params.length); params.push(encode(property, value)); return `${this.dialect.quoteId(property.columnName)} = ${placeholder}`; }).join(" AND ")})`;
+        }).join(" OR ")})`;
+      }
+      case "null": {
+        const property = this.requireProperty(condition.property);
+        return `${this.dialect.quoteId(property.columnName)} IS ${condition.negated ? "NOT " : ""}NULL`;
+      }
+      case "and":
+      case "or": {
+        const left = this.condition(condition.left, params, encode);
+        const right = this.condition(condition.right, params, encode);
+        return `(${left} ${condition.kind === "and" ? "AND" : "OR"} ${right})`;
+      }
+      case "not":
+        return `NOT (${this.condition(condition.inner, params, encode)})`;
+    }
+  }
+
+  private requireProperty(propertyName: string): PropertyModel {
+    const property = this.model.propertyByName(propertyName);
+    if (!property) {
+      throw new OrmError(
+        `Property "${propertyName}" is not mapped on entity "${this.model.name}". Did you forget @Column()?`,
+      );
+    }
+    return property;
+  }
+}

package/library/orm/Query/conditions.ts

@@ -0,0 +1,127 @@
+/**
+ * AST of WHERE conditions and a Proxy DSL to build it.
+ *
+ * Instead of parsing JS lambdas (unsafe and slow), the predicate is built
+ * through a Proxy: `x => x.age.gt(18).and(x.name.startsWith("A"))`. `x.age`
+ * returns a column operand, comparison methods produce AST nodes, and
+ * `.and()/.or()/.not()` combine them. No user strings in the SQL, only parameters.
+ *
+ * Note: `&&`/`||` are not intercepted; use `.and()/.or()`.
+ */
+
+export type CompareOp = "=" | "<>" | ">" | ">=" | "<" | "<=" | "LIKE";
+
+export type Condition =
+  | {
+      readonly kind: "compare";
+      readonly property: string;
+      readonly op: CompareOp;
+      readonly value: unknown;
+      /** For LIKE from startsWith/endsWith/contains: add `ESCAPE '\'`. */
+      readonly escaped?: boolean;
+    }
+  | { readonly kind: "in"; readonly property: string; readonly values: readonly unknown[] }
+  | { readonly kind: "tuples"; readonly properties: readonly string[]; readonly values: readonly (readonly unknown[])[] }
+  | { readonly kind: "null"; readonly property: string; readonly negated: boolean }
+  | { readonly kind: "and" | "or"; readonly left: Condition; readonly right: Condition }
+  | { readonly kind: "not"; readonly inner: Condition };
+
+/** Predicate result: a wrapper over an AST node with logical combinators. */
+export class Predicate {
+  constructor(readonly node: Condition) {}
+
+  and(other: Predicate): Predicate {
+    return new Predicate({ kind: "and", left: this.node, right: other.node });
+  }
+  or(other: Predicate): Predicate {
+    return new Predicate({ kind: "or", left: this.node, right: other.node });
+  }
+  not(): Predicate {
+    return new Predicate({ kind: "not", inner: this.node });
+  }
+}
+
+/** Column operand: the entry point for building conditions on a property. */
+export class Operand<T = unknown> {
+  constructor(readonly property: string) {}
+
+  private compare(op: CompareOp, value: unknown): Predicate {
+    return new Predicate({ kind: "compare", property: this.property, op, value });
+  }
+
+  /** LIKE with escaped wildcards (needs `ESCAPE '\'` in SQL). */
+  private likeEscaped(pattern: string): Predicate {
+    return new Predicate({ kind: "compare", property: this.property, op: "LIKE", value: pattern, escaped: true });
+  }
+
+  eq(value: T): Predicate {
+    return value === null ? this.isNull() : this.compare("=", value);
+  }
+  ne(value: T): Predicate {
+    return value === null ? this.isNotNull() : this.compare("<>", value);
+  }
+  gt(value: OrderedValue<T>): Predicate {
+    return this.compare(">", value);
+  }
+  gte(value: OrderedValue<T>): Predicate {
+    return this.compare(">=", value);
+  }
+  lt(value: OrderedValue<T>): Predicate {
+    return this.compare("<", value);
+  }
+  lte(value: OrderedValue<T>): Predicate {
+    return this.compare("<=", value);
+  }
+  like(pattern: TextValue<T>): Predicate {
+    return this.compare("LIKE", pattern);
+  }
+  startsWith(value: TextValue<T>): Predicate {
+    return this.likeEscaped(`${escapeLike(value)}%`);
+  }
+  endsWith(value: TextValue<T>): Predicate {
+    return this.likeEscaped(`%${escapeLike(value)}`);
+  }
+  contains(value: TextValue<T>): Predicate {
+    return this.likeEscaped(`%${escapeLike(value)}%`);
+  }
+  in(values: readonly T[]): Predicate {
+    return new Predicate({ kind: "in", property: this.property, values: [...values] });
+  }
+  isNull(): Predicate {
+    return new Predicate({ kind: "null", property: this.property, negated: false });
+  }
+  isNotNull(): Predicate {
+    return new Predicate({ kind: "null", property: this.property, negated: true });
+  }
+}
+
+/** `%` and `_` in startsWith/endsWith/contains must not act as wildcards. */
+function escapeLike(value: string): string {
+  return value.replace(/[%_\\]/g, (char) => `\\${char}`);
+}
+
+type OrderedValue<T> = unknown extends T ? unknown
+  : NonNullable<T> extends string | number | bigint | Date ? NonNullable<T> : never;
+type TextValue<T> = unknown extends T ? string : NonNullable<T> extends string ? string : never;
+
+/** Field selector (for where/orderBy). Returns a typed property operand. */
+export type FieldSelector<T> = {
+  readonly [K in keyof T]-?: Operand<T[K]>;
+};
+
+/** Predicate function passed to where. */
+export type PredicateFn<T> = (entity: FieldSelector<T>) => Predicate;
+
+/** Sorting needs only the column name, whatever the type of its value. */
+export type KeySelectorFn<T> = (entity: FieldSelector<T>) => Pick<Operand, "property">;
+
+const FIELD_PROXY: ProxyHandler<object> = {
+  get(_target, property): Operand {
+    return new Operand(String(property));
+  },
+};
+
+/** Creates a Proxy selector of the entity fields. */
+export function fieldSelector<T>(): FieldSelector<T> {
+  return new Proxy({}, FIELD_PROXY) as FieldSelector<T>;
+}

package/library/orm/Query/materialize.ts

@@ -0,0 +1,39 @@
+import type { EntityModel } from "../Metadata/types";
+import type { Row, SqlDialect } from "../Providers/types";
+import { decodeProperty } from "../Providers/propertyConversion";
+
+/**
+ * Hydrates a result row into an entity instance. A real class instance is
+ * created (the constructor is called without arguments), then columns are
+ * mapped to properties with reverse type conversion (through the dialect).
+ */
+export function materialize<T extends object>(model: EntityModel, row: Row, dialect: SqlDialect): T {
+  const entity = new model.ctor() as Record<string, unknown>;
+  for (const property of model.properties) {
+    if (property.columnName in row) {
+      entity[property.propertyName] = decodeProperty(property, row[property.columnName], dialect);
+    }
+  }
+  return entity as T;
+}
+
+/** Projects a row into a plain object by the alias -> property list. */
+export function materializeProjection(
+  model: EntityModel,
+  row: Row,
+  dialect: SqlDialect,
+  projections: readonly { readonly alias: string; readonly property: string }[],
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const { alias, property: propertyName } of projections) {
+    const property = model.propertyByName(propertyName);
+    if (!property) {
+      continue;
+    }
+    const column = alias in row ? alias : property.columnName;
+    if (column in row) {
+      result[alias] = decodeProperty(property, row[column], dialect);
+    }
+  }
+  return result;
+}

package/library/orm/README.md

@@ -0,0 +1,256 @@
+# ORM (`bazis` / `bazis/library/orm`)
+
+The ORM uses TC39 decorators, `DbContext`/`DbSet`, a scoped Unit of Work and
+parameterized SQL without runtime npm dependencies.
+
+## Queries and saving
+
+```ts
+// db.users is the DbSet of a model with the fields tenantId:string and age:number.
+const adults = await db.users
+  .where(user => user.tenantId.eq("team-a").and(user.age.gte(18)))
+  .orderBy(user => user.id)
+  .take(20)
+  .asNoTracking()
+  .toList();
+```
+
+The field type is kept in Operand<T>: age.eq("18") and age.contains("18") are
+TypeScript errors. eq/ne/in take the field type; strings support LIKE/contains,
+ordered values gt/gte/lt/lte. For null there are isNull/isNotNull, and eq(null) is
+allowed on nullable fields. Dynamic models with unknown keep the dynamic API.
+
+Conditions are combined with .and/.or/.not. JavaScript `&&`, `||` and `!` create no
+SQL conditions. `di:generate` reports such operations over the Predicate type in the
+sources of the chosen target and stops generation before files are replaced. This is
+a build check: running JS/any or sources without codegen does not get this guarantee.
+After changing a query, run `di:generate` and the TypeScript check.
+
+The write boundary is DbContext.saveChanges(), which saves all changes of the context.
+IRepository.saveChanges() stays an alias of the same operation. For new services,
+inject the domain DbContext so the save scope is visible in the code.
+[More about repositories](Repository/README.md).
+
+## PostgreSQL exact ensureCreated
+
+A production PostgreSQL schema is described once with the explicit
+`ormBazis.entities` list and entity decorators. The shared connection belongs to
+`@Infra`; a feature does not create its own PostgreSQL provider.
+
+```ts
+import { Column, DbContext, Entity, ForeignKey, Infra, Key, Module, Schema, ormBazisConnect } from "bazis";
+
+@Schema("billing")
+@Entity({ table: "orders" })
+class Order {
+  @Key(["tenantId", "orderId"], { name: "pk_orders" })
+  @Column({ type: "text" }) tenantId = "";
+  @Column({ type: "text" }) orderId = "";
+}
+
+@Schema("billing")
+@Entity({ table: "lines" })
+@ForeignKey(() => Order, { name: "fk_lines_order", properties: ["tenantId", "orderId"] })
+class OrderLine {
+  @Key(["tenantId", "lineId"]) @Column({ type: "text" }) tenantId = "";
+  @Column({ type: "text" }) lineId = "";
+  @Column({ type: "text" }) orderId = "";
+}
+
+class BillingContext extends DbContext {}
+@Infra({ db: ormBazisConnect(dbConfig) }) class AppInfra {}
+@Module({ ormBazis: { context: BillingContext, entities: [Order, OrderLine], ensureCreated: true } })
+class BillingModule {}
+```
+
+`@Key()` declares a single primary-key component. `@Key(["a", "b"])`
+declares the sole ordered composite key tuple; `@UUID()` declares a v4 UUID
+key generated by PostgreSQL, and `@UUID({ version: "v7" })` a time-ordered v7
+key that the ORM assigns before INSERT (native `uuid` column, no default). `@ForeignKey`, `@Index`, `@Check` and `@Schema` contribute to the same
+expected physical schema.
+
+For PostgreSQL, `ensureCreated()` acquires sorted advisory locks per physical
+schema and runs all catalog reads and DDL on one reserved-session transaction:
+
+1. classifies the complete declared PostgreSQL diff before any DDL;
+2. creates missing schemas and whole missing tables, or applies only safe additions;
+3. safe existing-table additions are nullable columns, non-null columns with a closed literal `@Column({ default })`, immediate CHECK/FK and ordinary/unique B-tree indexes;
+4. re-introspect and exact-verify before commit.
+
+Column order is ignored, but type/nullability/default/generation and named,
+ordered PK/FK/index/CHECK contracts are exact. A type/null/default/generation/
+PK change, rename/drop, generated/UUID existing-table column, `NOT NULL`
+column without a usable literal default, or changed/unknown object stops startup
+with `ORM_SCHEMA_MIGRATION_REQUIRED` and executes zero DDL. No backfill,
+rebuild, `IF NOT EXISTS` or concurrent index build is performed.
+
+`SchemaMigrationRequiredError` and `SchemaVerificationError` include the table,
+object, difference code, expected ORM state and actual database state in `message`.
+The existing `code` and structured `verification.differences` remain available.
+For example, an extra column produces:
+
+```text
+PostgreSQL schema change requires an explicit migration.
+- Table "public"."dm_table", object "bazis_drill_unexpected": column exists in the database but is absent from the ORM model (column.unexpected); expected (ORM): absent; actual (database): present.
+Check the application version and target database. Align the ORM model and database schema; apply an explicit migration if a database change is intended.
+```
+
+These diagnostics use the verifier's safe descriptors. Literal defaults and CHECK
+expressions remain represented by SHA-256 fingerprints; SQL, driver errors and row
+values are not added to the message. The message alone does not establish that the
+target database is outdated or should be modified: first check the application and
+database pairing. `Bazis.run()` prints the redacted nested error details without
+console depth collapsing them to `[Object ...]`.
+
+`ColumnOptions.default` is a closed physical literal (`null | boolean | number |
+string`), not SQL and not an entity initializer. It is supported only by the
+PostgreSQL exact path.
+
+Direct `context.database.ensureCreated()` uses the same PostgreSQL admission
+engine.
+
+## Other ORM capabilities
+
+- `where`, ordering, pagination, include and typed scalar/composite lookup;
+- snapshot tracking and transactional `saveChanges()`;
+- declarative FK/index/CHECK metadata;
+- explicit additive `migrate()` and legacy versioned `Migration[]` paths.
+
+The additive migration paths are separate from PostgreSQL exact admission.
+
+## Saving and retrying after an error
+
+`saveChanges()` inside `database.transaction()` joins the current transaction. An
+error of such a save forbids its COMMIT, even if the calling code caught the
+exception. To recover inside an outer transaction, use `transactionScope()` with a
+savepoint. Automatic save retries inside an active transaction are disabled.
+
+A unique constraint violation (SQLSTATE 23505) in `saveChanges()` arrives as
+`UniqueViolationError` (a `DbUpdateError` subclass) with the `constraint` and
+`table` fields and the original driver error in `cause`; the changes of this save are
+rolled back. Catch it to answer 409 without a check up front: the index decides, so
+there is no race. Other driver errors are not wrapped.
+
+If there is no reliable answer after COMMIT is sent, the ORM throws `DbUpdateError`
+with `code: "ORM_TRANSACTION_OUTCOME_UNKNOWN"`. `ExecutionStrategy` and `withRetry`
+do not retry such an operation, including a user `isTransient`.
+All contexts that saved changes in this transaction block further `saveChanges()`.
+First reconcile the result against the database data, then continue in a new
+`DbContext`. The received keys are kept for the reconciliation; having a key or the
+`Unchanged` state does not prove COMMIT. User `afterCommit` and `afterRollback` are
+not called on an unknown outcome.
+
+After a confirmed rollback the keys and tracking are restored. A confirmed COMMIT
+with a handler error keeps the existing `PostCommitError` contract.
+
+The native `Bun.SQL Query.cancel()` on the pinned Bun 1.4.0 did not confirm
+cancelling an already running query: six checks on PostgreSQL 17.11 left the query
+active after 1.5 seconds. `cancelled === true` alone does not prove cancellation.
+On leaving `transactionScope()` with an unfinished operation the ORM forbids COMMIT.
+If an unfinished PostgreSQL query remains, the ORM forbids further work on this
+reservation and calls `pg_cancel_backend` through a separate service Bun.SQL
+connection. It waits for the cancel command's response, the completion of the
+original native queries, a confirmed ROLLBACK and a readback of the same backend
+identity. After that the connection can be reused.
+The broken `Query.cancel()` is not used on this path. For unfinished user JS without
+SQL a 5-second wait limit is kept; an explicit cancellation signal also interrupts that wait.
+
+A long query inside the callback can be cancelled from outside:
+
+```ts
+await db.transactionScope(async (tx) => {
+  await tx.databaseTime();
+  await db.database.querySqlRaw("SELECT pg_sleep({0})", 30);
+}, { signal: AbortSignal.timeout(1_000) });
+```
+
+An already aborted signal rejects the call before BEGIN. When an active scope is
+cancelled, new and deferred operations are blocked. Server cancellation rolls back the
+whole physical transaction, including the outer one when a nested scope is cancelled;
+a caught error does not allow its COMMIT. After the callback and its operations
+finish, control passes to the provider: its operation timeout applies until the COMMIT
+response. The signal is passed to `reserve({ signal })`; a connection handed out late
+is closed without BEGIN. `options.timeoutMs` bounds waiting for a connection, BEGIN,
+the callback, SQL and COMMIT; the default is the provider's `operationTimeoutMs`
+(30 seconds). Confirming a cancellation has a separate `cancellationTimeoutMs`
+budget (5 seconds), and releasing the resource one more such budget. This is not a
+promise to finish the whole call within `timeoutMs`. User afterCommit/afterRollback
+have their own execution time; a late cancellation does not change a confirmed
+COMMIT. Arbitrary JS is not stopped, but its late calls into the ORM are forbidden.
+
+If the SQL completion and the rollback on the same backend are not confirmed, the ORM
+returns `ORM_TRANSACTION_OUTCOME_UNKNOWN` with `phase: "cancellation"`. The user
+rollback callback is not called. All contexts included in the scope block new SQL
+and saves; reconcile the result through a new context. A lost COMMIT response keeps
+`phase: "commit"`. There is no automatic retry.
+
+With an explicit `cancellationMode: "close"` the former policy of closing and
+checking that the backend is gone is kept. In this mode on Bun 1.4.0 **fast
+cancellation over TLS is not confirmed**: the connection-close Promise settles, but
+SQL on the server may stay active. In a check of a 10-second query the backend stayed
+active after five seconds; the ORM returned an unknown outcome within its budget. With
+an explicitly configured server `statementTimeoutMs: 600` a separate check ended with
+a confirmed rollback in 641 ms. The server limit counts from the start of the SQL, so
+it does not guarantee such a delay from any later abort.
+
+`postgres({ operationTimeoutMs, cancellationTimeoutMs, cancellationMode, maxPendingOperations,
+serverTimeouts, onOperation })` configures the provider policy.
+`cancellationMode` takes `server` (the default) or `close`. The server mode uses a
+lazy service pool max=1 in addition to the working pool, with the same credentials
+and TLS. Both pools close together with the provider. Borrowed advisory locks are
+released explicitly after a confirmed rollback, before the connection is returned.
+After a forced close the pool checks later reservations with SELECT 1 before user
+work. A native connection timeout on admission allows one retry within the shared
+deadline; business SQL, the callback and COMMIT are not retried. The check adds one
+round trip after such a failure until the provider is recreated; a regular confirmed
+server cancellation does not enable it.
+
+The SQL check of PID/backend_start/query_start is not atomic against the system
+reusing the PID; this API does not give the PID+secret guarantee of the protocol.
+`serverTimeouts` supports `statementTimeoutMs`, `lockTimeoutMs`,
+`idleInTransactionTimeoutMs`, `transactionTimeoutMs` (the last one is PostgreSQL 17+).
+The settings are applied with SET LOCAL and checked at BEGIN; by default the server
+limits do not change. Root query/execute and ping have a client deadline, but the
+SET LOCAL profile applies only inside transactions. Unfinished native operations hold
+a slot until they actually finish; the default limit is 256, with a bounded reserve
+for cleanup. `statistics()` and `onOperation` show the number of such operations,
+durations and unknown outcomes without SQL or parameters.
+
+The ORM connector passes the pool, connection and TLS settings and the listed limits.
+Units, validation and a connection example are in the
+[core/orm passport](../../core/orm/MODULE.md).
+
+Results of the current server mode, real AbortSignal TCP/TLS scenarios and binary
+qualification are in the [integration report](https://github.com/asus97178/osnova/blob/33a4513a56abb43a1694e7a6e56373187b928a70/docs/audits/orm-server-cancel-integration-2026-09-14.md).
+Earlier physical checks of the close mode confirmed cancellation in 395–402 ms,
+rollback, key restoration, advisory lock release, an unaffected neighboring active
+query in the same pool and further saves. This is a measurement of a local run, not a
+deadline for any environment. [Fix and evidence](https://github.com/asus97178/osnova/blob/33a4513a56abb43a1694e7a6e56373187b928a70/docs/audits/orm-2026-09-14-cancellation-fix.md),
+[cancellation contract](MODULE.md). A direct `Bun.SQL Query.cancel()` call stays a
+separate failed gate from the [earlier qualification](https://github.com/asus97178/osnova/blob/33a4513a56abb43a1694e7a6e56373187b928a70/docs/audits/orm-2026-09-14-qualification.md).
+New time limits, network failures, TLS and binary execution are described in the
+[hardening report](https://github.com/asus97178/osnova/blob/33a4513a56abb43a1694e7a6e56373187b928a70/docs/audits/orm-bun-sql-hardening-2026-09-14.md).
+
+`findForUpdate()` refreshes only a clean tracked entity. Unsaved regular assignments,
+JSON/Date changes and an explicit `update()` cause a rejection before the values are
+overwritten. Models with only a generated key are saved with separate
+`INSERT DEFAULT VALUES` inside the shared transaction.
+
+## Physical types and SQL names
+
+A PostgreSQL FK to a native UUID key gets the physical `uuid` type; the logical
+`PropertyModel.type` and converters are kept. This applies to explicit FKs,
+navigations and dynamic models, including composite relations and PK/FK chains.
+Incompatible types are rejected before DDL. Existing columns are not converted
+automatically: a mismatch needs a separate migration. Exact admission rejects
+`GENERATED ALWAYS` if the model declares `BY DEFAULT`.
+
+`PostgresDialect.quoteId()` quotes **one** name:
+`quoteId("external.name")` returns `"external.name"`. For a table with a schema use
+`qualifyTable(model)` or join a separately quoted schema and name. The old
+`tableName` format of dynamic models is kept; the ORM uses the original schema and
+table components without splitting on dots. A manually passed
+`ForeignKeyConstraint.referencedTable` keeps the existing `schema.table` format.
+
+`include()` uses the `KeyTuple` semantics shared with the identity map for references
+and collections, including `bigint`, `Date` and converter-backed binary keys.