bazis 0.96.1

package/library/orm/Providers/PostgresSchema.decoder.ts

@@ -0,0 +1,107 @@
+import type { Row } from "./types";
+import type { IntrospectedColumn, IntrospectedIndex, IntrospectedForeignKey } from "../Schema/introspection";
+import { parseRenderedCheck } from "../Schema/CheckExpression";
+
+export function canonicalPostgresColumn(type: string, defaultExpression: string | null, identity: string): Pick<IntrospectedColumn, "physicalType" | "default" | "generation" | "unsupported"> {
+  const physicalType = canonicalPostgresType(type);
+  const defaultValue = canonicalPostgresDefault(defaultExpression, physicalType);
+  const generation = identity === "d" ? "identityByDefault" as const : defaultValue.kind === "uuidV4" ? "uuidDefault" as const : "none" as const;
+  return { physicalType, default: defaultValue.value, generation, unsupported: physicalType === "unknown" || defaultValue.unsupported || (identity !== "" && identity !== "d") };
+}
+
+export function canonicalPostgresType(type: string): "integer" | "real" | "text" | "boolean" | "datetime" | "json" | "uuid" | "unknown" {
+  switch (type.trim().toLowerCase()) {
+    case "smallint": case "integer": case "bigint": return "integer";
+    case "real": case "double precision": case "numeric": return "real";
+    case "text": case "character varying": case "character": return "text";
+    case "boolean": return "boolean";
+    case "timestamp with time zone": return "datetime";
+    case "json": case "jsonb": return "json";
+    case "uuid": return "uuid";
+    default: return "unknown";
+  }
+}
+
+/** Exact admission accepts only the physical spellings rendered by PostgresDialect. */
+export function exactPostgresType(type: string, canonical: IntrospectedColumn["physicalType"]): IntrospectedColumn["physicalType"] {
+  const raw = type.trim().toLowerCase();
+  switch (raw) {
+    case "bigint": case "double precision": case "text": case "boolean": case "timestamp with time zone": case "jsonb": case "uuid": return canonical;
+    default: return `${canonical ?? "unknown"}:${raw}`;
+  }
+}
+
+export function canonicalPostgresDefault(value: string | null, physicalType: string): { readonly value: IntrospectedColumn["default"]; readonly kind: "none" | "uuidV4"; readonly unsupported: boolean } {
+  if (value === null) return { value: { kind: "none" }, kind: "none", unsupported: false };
+  const raw = normalizePostgresDefault(value);
+  if (/^null$/i.test(raw)) return { value: { kind: "null" }, kind: "none", unsupported: false };
+  if (/^current_timestamp$/i.test(raw) || /^now\(\)$/i.test(raw)) return { value: { kind: "currentTimestamp" }, kind: "none", unsupported: false };
+  if (/^gen_random_uuid\(\)$/i.test(raw)) return { value: { kind: "uuidV4" }, kind: "uuidV4", unsupported: false };
+  if (/^(true|false)$/i.test(raw)) return { value: { kind: "boolean", value: /^true$/i.test(raw) }, kind: "none", unsupported: false };
+  if (/^-?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(raw)) {
+    const numeric = Number(raw);
+    if (Number.isFinite(numeric)) return { value: { kind: "number", value: numeric }, kind: "none", unsupported: false };
+  }
+  const string = raw.match(/^'((?:''|[^'])*)'$/);
+  if (string) {
+    const decoded = string[1]!.replaceAll("''", "'");
+    if (physicalType === "datetime") {
+      const temporal = canonicalTimestamp(decoded);
+      return temporal === undefined ? { value: { kind: "none" }, kind: "none", unsupported: true } : { value: { kind: "string", value: temporal }, kind: "none", unsupported: false };
+    }
+    if (physicalType === "json") {
+      try { const json = JSON.parse(decoded); if (json === null) return { value: { kind: "null" }, kind: "none", unsupported: false }; if (typeof json === "boolean") return { value: { kind: "boolean", value: json }, kind: "none", unsupported: false }; if (typeof json === "number" && Number.isFinite(json)) return { value: { kind: "number", value: json }, kind: "none", unsupported: false }; if (typeof json === "string") return { value: { kind: "string", value: json }, kind: "none", unsupported: false }; } catch { /* fail closed below */ }
+      return { value: { kind: "none" }, kind: "none", unsupported: true };
+    }
+    return { value: { kind: "string", value: decoded }, kind: "none", unsupported: false };
+  }
+  return { value: { kind: "none" }, kind: "none", unsupported: true };
+}
+function canonicalTimestamp(value: string): string | undefined {
+  const match = value.match(/^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(?:\.(\d+))?([+-]\d{2}(?::?\d{2})?|Z)$/u);
+  if (!match) return undefined;
+  let offset = match[4]!;
+  if (offset !== "Z" && !offset.includes(":")) offset = offset.length === 3 ? `${offset}:00` : `${offset.slice(0, 3)}:${offset.slice(3)}`;
+  const iso = `${match[1]}T${match[2]}${match[3] ? `.${match[3]}` : ""}${offset}`;
+  return Number.isNaN(Date.parse(iso)) ? undefined : new Date(iso).toISOString().replace(/\.000Z$/u, "Z");
+}
+
+function normalizePostgresDefault(value: string): string {
+  let current = value.trim();
+  for (;;) {
+    const next = stripPostgresOuter(stripPostgresCasts(current));
+    if (next === current) return next;
+    current = next;
+  }
+}
+function stripPostgresCasts(value: string): string { return value.replace(/::(?:[A-Za-z_][A-Za-z0-9_]*)(?:\s+[A-Za-z_][A-Za-z0-9_]*)*(?:\[\])?$/u, "").trim(); }
+function stripPostgresOuter(value: string): string { while (value.startsWith("(") && value.endsWith(")")) value = value.slice(1, -1).trim(); return value; }
+
+export function collectPostgresIndexes(rows: readonly Row[], exact = false): IntrospectedIndex[] {
+  const byName = new Map<string, { unique: boolean; columns: string[]; method: "btree" | undefined; backingConstraint: boolean; unsupported: boolean; predicate?: string }>();
+  for (const row of rows) {
+    const name = String(row.index_name); let index = byName.get(name);
+    if (!index) { index = { unique: row.is_unique === true, columns: [], method: String(row.method) === "btree" ? "btree" : undefined, backingConstraint: row.backing_constraint === true, unsupported: row.is_expression === true || row.is_valid !== true || row.is_ready !== true }; if (row.has_predicate === true) index.predicate = "unsupported"; byName.set(name, index); }
+    if (row.column_name == null || (exact && row.is_include === true)) index.unsupported = true; else index.columns.push(String(row.column_name));
+  }
+  return [...byName.entries()].map(([name, value]) => ({ name, unique: value.unique, columns: value.columns, method: value.method, backingConstraint: value.backingConstraint, predicate: value.predicate, unsupported: value.unsupported }));
+}
+
+export function collectPostgresForeignKeys(rows: readonly Row[], exact = false): IntrospectedForeignKey[] {
+  const byName = new Map<string, { columns: string[]; targetColumns: string[]; targetSchema: string; targetTable: string; onDelete: string; onUpdate: string; deferrable: boolean; unsupported: boolean }>();
+  for (const row of rows) {
+    const name = String(row.constraint_name); let foreignKey = byName.get(name);
+    if (!foreignKey) { const onDelete = postgresAction(String(row.delete_code)); const onUpdate = postgresAction(String(row.update_code)); foreignKey = { columns: [], targetColumns: [], targetSchema: String(row.target_schema), targetTable: String(row.target_table), onDelete: onDelete.value, onUpdate: onUpdate.value, deferrable: row.deferrable === true, unsupported: onDelete.unsupported || onUpdate.unsupported || String(row.match_code) !== "s" || (exact && row.validated !== true) }; byName.set(name, foreignKey); }
+    foreignKey.columns.push(String(row.column_name)); foreignKey.targetColumns.push(String(row.target_column));
+  }
+  return [...byName.entries()].map(([name, value]) => ({ name, ...value, targetSchema: value.targetSchema === "public" ? null : value.targetSchema }));
+}
+
+function postgresAction(code: string): { readonly value: string; readonly unsupported: boolean } { switch (code) { case "a": return { value: "noAction", unsupported: false }; case "r": return { value: "restrict", unsupported: false }; case "c": return { value: "cascade", unsupported: false }; case "n": return { value: "setNull", unsupported: false }; default: return { value: "unknown", unsupported: true }; } }
+
+export function canonicalPostgresCheck(name: string, definition: string): { readonly name: string; readonly expression: unknown; readonly unsupported: boolean } {
+  const body = definition.trim().match(/^CHECK\s*\((.*)\)$/isu)?.[1]?.replace(/::(?:[A-Za-z_][A-Za-z0-9_]*(?:\[\])?)/gu, "");
+  const expression = body === undefined ? undefined : parseRenderedCheck(body);
+  return { name, expression: expression ?? { kind: "unsupported" }, unsupported: expression === undefined };
+}
+

package/library/orm/Providers/limits.ts

@@ -0,0 +1,29 @@
+import type { DatabaseProvider } from "./types";
+
+const DEFAULT_MAX_PARAMETERS_PER_COMMAND = 900;
+
+export function maxRowsPerInsert(provider: DatabaseProvider, columnsPerRow: number): number {
+  const maxParameters = positiveInteger(provider.limits?.maxParametersPerCommand, DEFAULT_MAX_PARAMETERS_PER_COMMAND);
+  const safeColumnsPerRow = Math.max(1, Math.floor(columnsPerRow));
+  const maxRowsByParams = Math.max(1, Math.floor(maxParameters / safeColumnsPerRow));
+  const providerRows = optionalPositiveInteger(provider.limits?.maxRowsPerInsert);
+  return providerRows === undefined ? maxRowsByParams : Math.max(1, Math.min(providerRows, maxRowsByParams));
+}
+
+export function maxParametersPerInList(provider: DatabaseProvider): number {
+  const maxParameters = positiveInteger(provider.limits?.maxParametersPerCommand, DEFAULT_MAX_PARAMETERS_PER_COMMAND);
+  const maxInList = positiveInteger(provider.limits?.maxParametersPerInList, maxParameters);
+  return Math.max(1, Math.min(maxInList, maxParameters));
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  const parsed = optionalPositiveInteger(value);
+  return parsed ?? fallback;
+}
+
+function optionalPositiveInteger(value: number | undefined): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.floor(value);
+}

package/library/orm/Providers/operationDeadline.ts

@@ -0,0 +1,43 @@
+import { OrmTransactionScopeError } from "../errors";
+
+export function positiveTimeout(value: number | undefined, fallback: number, name: string): number {
+  const result = value === undefined ? fallback : value;
+  if (!Number.isInteger(result) || result <= 0 || result > 2_147_483_647) throw new TypeError(`${name} must be an integer between 1 and 2147483647.`);
+  return result;
+}
+
+/** One deadline; disposing removes both the timer and the caller's listener. */
+export class OperationDeadline {
+  readonly controller = new AbortController();
+  readonly signal = this.controller.signal;
+  private readonly timer: ReturnType<typeof setTimeout>;
+  private readonly onAbort = () => this.controller.abort(new OrmTransactionScopeError("ORM operation was aborted."));
+
+  constructor(timeoutMs: number, private readonly parent?: AbortSignal) {
+    if (parent !== undefined && !(parent instanceof AbortSignal)) throw new TypeError("signal must be an AbortSignal.");
+    this.timer = setTimeout(() => this.controller.abort(new OrmTransactionScopeError("ORM operation deadline exceeded.")), timeoutMs);
+    if (parent?.aborted) this.onAbort();
+    else parent?.addEventListener("abort", this.onAbort, { once: true });
+  }
+
+  wait<T>(work: PromiseLike<T>): Promise<T> { return awaitWithSignal(work, this.signal); }
+
+  dispose(): void {
+    clearTimeout(this.timer);
+    this.parent?.removeEventListener("abort", this.onAbort);
+  }
+}
+
+/** The caller owns termination of work; racing alone never proves cleanup. */
+export function awaitWithSignal<T>(work: PromiseLike<T>, signal: AbortSignal): Promise<T> {
+  const pending = Promise.resolve(work);
+  if (signal.aborted) { void pending.catch(() => {}); return Promise.reject(signal.reason); }
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal.addEventListener("abort", abort, { once: true });
+    pending.then(
+      (value) => { signal.removeEventListener("abort", abort); resolve(value); },
+      (error) => { signal.removeEventListener("abort", abort); reject(error); },
+    );
+  });
+}

package/library/orm/Providers/ormOwnedStoreRuntime.ts

@@ -0,0 +1,19 @@
+import type { DatabaseProvider } from "./types";
+import { knownExecutionStrategyBase } from "../Saving/ExecutionStrategy";
+import { OrmOwnedStoreAdmissionError } from "../errors";
+import type { ExpectedTable } from "../Schema/ExpectedSchema";
+import type { OwnedStoreCatalogSnapshotV1, OwnedStoreRegistrySnapshotV1 } from "../Schema/OwnedStoreCatalog";
+import type { OrmCatalogScopeV1 } from "../Schema/OrmOwnedStore";
+
+export interface OwnedStoreSecondaryLockEntryV1 { readonly kind: "store" | "scope"; readonly preimage: Uint8Array; readonly key: bigint; }
+export interface OwnedStoreSecondaryLockPlanV1 { readonly stores: readonly OwnedStoreSecondaryLockEntryV1[]; readonly scopes: readonly OwnedStoreSecondaryLockEntryV1[]; }
+export type OwnedStoreCreateOperationV1 = { readonly kind: "createSchema"; readonly schema: string } | { readonly kind: "createTable"; readonly table: ExpectedTable } | { readonly kind: "addForeignKey"; readonly table: ExpectedTable; readonly foreignKey: ExpectedTable["foreignKeys"][number] } | { readonly kind: "createIndex"; readonly table: ExpectedTable; readonly index: ExpectedTable["indexes"][number] };
+export interface OwnedStoreIdentityInsertV1 { readonly storeKey: string; readonly contract: "bazis.orm-owned-store/v1"; readonly formatVersion: number; readonly ownedSchema: string; readonly tablePrefix: string; readonly ownedScopeHash: `sha256:${string}`; readonly modelHash: `sha256:${string}`; }
+export interface RegistryLockedOwnedStoreSessionV1 { readonly maxIdentifierLength: bigint; inspectRegistry(): Promise<OwnedStoreRegistrySnapshotV1>; lockSecondary(plan: OwnedStoreSecondaryLockPlanV1): Promise<SecondaryLockedOwnedStoreSessionV1>; }
+export interface SecondaryLockedOwnedStoreSessionV1 { inspectCatalog(scopes: readonly OrmCatalogScopeV1[]): Promise<OwnedStoreCatalogSnapshotV1>; createRegistryV1(): Promise<void>; applyCreateOperations(operations: readonly OwnedStoreCreateOperationV1[]): Promise<void>; insertIdentities(rows: readonly OwnedStoreIdentityInsertV1[]): Promise<void>; inspectRegistry(): Promise<OwnedStoreRegistrySnapshotV1>; }
+export interface PostgresOwnedStoreCapability { withOwnedStoreAdmission<T>(signal: AbortSignal | undefined, work: (session: RegistryLockedOwnedStoreSessionV1) => Promise<T>): Promise<T>; }
+const capabilities = new WeakMap<DatabaseProvider, PostgresOwnedStoreCapability>();
+
+export function registerPostgresOwnedStoreCapability(provider: DatabaseProvider, capability: PostgresOwnedStoreCapability): void { capabilities.set(provider, capability); }
+export function postgresOwnedStoreCapability(provider: DatabaseProvider): PostgresOwnedStoreCapability | undefined { const base = knownExecutionStrategyBase(provider); return base === undefined ? undefined : capabilities.get(base); }
+export function failure(code: OrmOwnedStoreAdmissionError["code"]): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(code, code); }

package/library/orm/Providers/ormTransactionRuntime.ts

@@ -0,0 +1,117 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { DatabaseProvider, DbExecutor, ExecuteResult, Row, SchemaAdmissionScope } from "./types";
+import { knownExecutionStrategyBase } from "../Saving/ExecutionStrategy";
+import type { OrmTransactionScopeOptions, OrmDatabaseTimeV1 } from "../Transactions/OrmTransaction";
+
+export type TransactionOperationObserver = <T>(operation: () => Promise<T>) => Promise<T>;
+
+function observedExecutor(executor: DbExecutor, observe: TransactionOperationObserver): DbExecutor {
+  return {
+    query: (sql, params) => observe(() => executor.query(sql, params)),
+    execute: (sql, params) => observe(() => executor.execute(sql, params)),
+  };
+}
+export interface CancellableProviderDispatch { cancel(): unknown; readonly settled: Promise<unknown>; }
+export type ProviderDispatchObserver = (dispatch: CancellableProviderDispatch) => void;
+const dispatchObservers = new AsyncLocalStorage<ProviderDispatchObserver>();
+
+/** Private ALS bridge used only by provider implementations and the coordinator. */
+export function withProviderDispatchObserver<T>(observer: ProviderDispatchObserver, work: () => T): T {
+  return dispatchObservers.run(observer, work);
+}
+export function withoutProviderDispatchObserver<T>(work: () => T): T { return dispatchObservers.exit(work); }
+export function observeProviderDispatch(dispatch: CancellableProviderDispatch): void { dispatchObservers.getStore()?.(dispatch); }
+
+const ROOTS = new WeakMap<DatabaseProvider, object>();
+const scopeOptions = new AsyncLocalStorage<OrmTransactionScopeOptions>();
+export function withPostgresScopeOptions<T>(options: OrmTransactionScopeOptions, work: () => T): T { return scopeOptions.run(options, work); }
+export function withoutPostgresScopeOptions<T>(work: () => T): T { return scopeOptions.exit(work); }
+export function currentPostgresScopeOptions(): OrmTransactionScopeOptions | undefined { return scopeOptions.getStore(); }
+
+interface PostgresTransactionCapability {
+  readonly operationTimeoutMs?: number;
+  readonly isOutcomeUncertain?: (error: unknown) => boolean;
+  readonly operationSignal?: () => AbortSignal | undefined;
+  readonly databaseTime: () => Promise<OrmDatabaseTimeV1>;
+  readonly assertScopedClose: () => void | Promise<void>;
+  readonly quarantine: () => Promise<void>;
+  /** The physical owner settles cancellation and rollback itself; the
+   * coordinator must not rely on native Query.cancel or a timed drain. */
+  readonly quarantineOnPendingDispatch?: boolean;
+}
+const POSTGRES_CAPABILITIES = new WeakMap<DatabaseProvider, PostgresTransactionCapability>();
+
+/** Private registration: PostgreSQL exposes no transaction internals in DatabaseProvider. */
+export function registerPostgresTransactionCapability(provider: DatabaseProvider, capability: PostgresTransactionCapability): void {
+  POSTGRES_CAPABILITIES.set(provider, capability);
+}
+
+export function postgresTransactionCapability(provider: DatabaseProvider): PostgresTransactionCapability | undefined {
+  const base = baseProvider(provider);
+  return base ? POSTGRES_CAPABILITIES.get(base) : undefined;
+}
+
+/** Private identity is deliberately object identity, never connection settings. */
+export function rootAuthority(provider: DatabaseProvider): object {
+  const base = knownExecutionStrategyBase(provider) ?? provider;
+  let authority = ROOTS.get(base);
+  if (!authority) {
+    authority = {};
+    ROOTS.set(base, authority);
+  }
+  return authority;
+}
+
+export function baseProvider(provider: DatabaseProvider): DatabaseProvider | undefined {
+  return knownExecutionStrategyBase(provider);
+}
+
+/** Explicit proxy preserves prototype-owned provider methods without object spread. */
+export function createObservedProvider(provider: DatabaseProvider, observe: TransactionOperationObserver, capture?: () => TransactionOperationObserver): DatabaseProvider {
+  const schema = provider.schemaAdmissionCapability;
+  const fenceSchemaScope = (scope: SchemaAdmissionScope): SchemaAdmissionScope => {
+    const scopedObserve = capture?.() ?? observe;
+    const executor = observedExecutor(scope, scopedObserve);
+    const privateScope = scope as SchemaAdmissionScope & { executeSchemaAdmission?: (sql: string, operation: string) => Promise<ExecuteResult> };
+    const result: SchemaAdmissionScope & { executeSchemaAdmission?: (sql: string, operation: string) => Promise<ExecuteResult> } = {
+      query: executor.query,
+      execute: executor.execute,
+      introspectExpected: (expected) => scopedObserve(() => scope.introspectExpected(expected)),
+    };
+    if (privateScope.executeSchemaAdmission) {
+      result.executeSchemaAdmission = (sql, operation) => scopedObserve(() => privateScope.executeSchemaAdmission!(sql, operation));
+    }
+    return result;
+  };
+  const result = {
+    name: provider.name,
+    dialect: provider.dialect,
+    limits: provider.limits,
+    diagnostics: provider.diagnostics?.bind(provider),
+    query: (sql, params): Promise<Row[]> => observe(() => provider.query(sql, params)),
+    execute: (sql, params): Promise<ExecuteResult> => observe(() => provider.execute(sql, params)),
+    transaction: (work): Promise<unknown> => observe(() => provider.transaction((executor) => work(observedExecutor(executor, capture?.() ?? observe)))),
+    transactionScope: provider.transactionScope ? (work): Promise<unknown> => observe(() => provider.transactionScope!((executor) => work(observedExecutor(executor, capture?.() ?? observe)))) : undefined,
+    isTransactionActive: provider.isTransactionActive?.bind(provider),
+    afterCommit: provider.afterCommit?.bind(provider),
+    afterRollback: provider.afterRollback?.bind(provider),
+    ping: (signal?: AbortSignal): Promise<boolean> => observe(() => provider.ping(signal)),
+    introspect: () => observe(() => provider.introspect()),
+    schemaAdmissionCapability: schema ? {
+      version: schema.version,
+      provider: schema.provider,
+      distributedLock: schema.distributedLock,
+      transactionalDdl: schema.transactionalDdl,
+      exactIntrospection: schema.exactIntrospection,
+      withSchemaAdmission: (schemas, work) => observe(() => schema.withSchemaAdmission(schemas, (scope) => work(fenceSchemaScope(scope)))),
+    } : undefined,
+    withMigrationLock: provider.withMigrationLock ? (work) => observe(() => provider.withMigrationLock!(() => observe(work))) : undefined,
+    listen: provider.listen ? (channel, handler) => observe(() => provider.listen!(channel, handler)) : undefined,
+    notify: provider.notify ? (channel, payload) => observe(() => provider.notify!(channel, payload)) : undefined,
+    // A transaction view must never own, and therefore never close, the root pool.
+    close: () => provider.close(),
+  } as DatabaseProvider;
+  const base = baseProvider(provider);
+  if (base) ROOTS.set(result, rootAuthority(base));
+  return result;
+}

package/library/orm/Providers/propertyConversion.ts

@@ -0,0 +1,14 @@
+import type { PropertyModel } from "../Metadata/types";
+import type { SqlDialect, SqlParam } from "./types";
+
+/** Encodes a property value: converter -> dialect. */
+export function encodeProperty(property: PropertyModel, value: unknown, dialect: SqlDialect): SqlParam {
+  const modelValue = property.converter ? property.converter.toProvider(value) : value;
+  return dialect.encode(modelValue, property.type);
+}
+
+/** Decodes a column value: dialect -> converter. */
+export function decodeProperty(property: PropertyModel, value: unknown, dialect: SqlDialect): unknown {
+  const providerValue = dialect.decode(value, property.type);
+  return property.converter ? property.converter.fromProvider(providerValue) : providerValue;
+}

package/library/orm/Providers/resolvedForeignKey.ts

@@ -0,0 +1,16 @@
+import type { ColumnType, EntityModel } from "../Metadata/types";
+import type { ForeignKeyConstraint } from "./types";
+
+/** Internal model-backed DDL metadata. Legacy caller-supplied constraints keep
+ * their existing columnType and schema.table string contract. */
+interface ResolvedForeignKey {
+  readonly target: EntityModel;
+  readonly columnTypes: ReadonlyMap<string, ColumnType | "uuid">;
+}
+const resolved = new WeakMap<ForeignKeyConstraint, ResolvedForeignKey>();
+export function bindResolvedForeignKey(constraint: ForeignKeyConstraint, metadata: ResolvedForeignKey): void {
+  resolved.set(constraint, metadata);
+}
+export function resolvedForeignKey(constraint: ForeignKeyConstraint): ResolvedForeignKey | undefined {
+  return resolved.get(constraint);
+}

package/library/orm/Providers/transactionCallbacks.ts

@@ -0,0 +1,45 @@
+import { PostCommitError } from "../errors";
+import type { TransactionCallback } from "./types";
+
+const commitFinalizers = new WeakSet<TransactionCallback>();
+
+/** Non-barrel tracker cleanup. A confirmed commit releases provisional
+ * identities before user callbacks, regardless of registration order. */
+export function registerPostCommitFinalizer(callback: TransactionCallback): void {
+  commitFinalizers.add(callback);
+}
+
+export async function runPostCommitCallbacks(callbacks: readonly TransactionCallback[]): Promise<void> {
+  const errors = await collectCallbackErrors(callbacks, true);
+  errors.push(...await collectCallbackErrors(callbacks, false));
+  if (errors.length > 0) {
+    throw new PostCommitError(errors);
+  }
+}
+
+export async function runRollbackCallbacks(
+  callbacks: readonly TransactionCallback[],
+  transactionError: unknown,
+): Promise<never> {
+  const callbackErrors = await collectCallbackErrors(callbacks);
+  if (callbackErrors.length === 0) {
+    throw transactionError;
+  }
+  throw new AggregateError(
+    [transactionError, ...callbackErrors],
+    "Transaction rolled back, but one or more rollback callbacks also failed.",
+  );
+}
+
+async function collectCallbackErrors(callbacks: readonly TransactionCallback[], finalizers?: boolean): Promise<unknown[]> {
+  const errors: unknown[] = [];
+  for (const callback of callbacks) {
+    if (finalizers !== undefined && commitFinalizers.has(callback) !== finalizers) continue;
+    try {
+      await callback();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  return errors;
+}

package/library/orm/Providers/transactionOutcome.ts

@@ -0,0 +1,82 @@
+import { DbUpdateError } from "../errors";
+import type { TransactionCallback } from "./types";
+
+/** The server's final outcome could not be confirmed after (auto)commit or cancellation. */
+export class TransactionOutcomeUnknownError extends DbUpdateError {
+  readonly code = "ORM_TRANSACTION_OUTCOME_UNKNOWN";
+  readonly outcome = "unknown";
+  constructor(override readonly cause?: unknown, readonly phase: "commit" | "cancellation" = "commit") {
+    super(phase === "commit"
+      ? "Transaction outcome is unknown. Reconcile database state and use a new DbContext before saving again."
+      : "Transaction cancellation is unconfirmed. Reconcile database state and use a new DbContext before saving again.");
+  }
+}
+
+export function isUnknownTransactionOutcome(error: unknown): boolean {
+  const pending = [error];
+  const seen = new Set<unknown>();
+  while (pending.length) {
+    const current = pending.pop();
+    if (current === null || (typeof current !== "object" && typeof current !== "function") || seen.has(current)) continue;
+    // Excessively wrapped failures are not safe candidates for automatic replay.
+    if (seen.size >= 256) return true;
+    seen.add(current);
+    try {
+      const code = Object.getOwnPropertyDescriptor(current, "code");
+      if (code && "value" in code && code.value === "ORM_TRANSACTION_OUTCOME_UNKNOWN") return true;
+      const cause = Object.getOwnPropertyDescriptor(current, "cause");
+      if (cause && "value" in cause) pending.push(cause.value);
+      if (current instanceof AggregateError) {
+        const errors = Object.getOwnPropertyDescriptor(current, "errors");
+        if (errors && "value" in errors && Array.isArray(errors.value)) {
+          if (errors.value.length > 256) return true;
+          for (let index = 0; index < errors.value.length; index++) {
+            const child = Object.getOwnPropertyDescriptor(errors.value, String(index));
+            if (child && "value" in child) pending.push(child.value);
+          }
+        }
+      }
+    } catch { /* Never replace the original failure while classifying it. */ }
+  }
+  return false;
+}
+
+/** Only an explicit server rollback/constraint rejection proves COMMIT failed.
+ * Connection errors (including SQLSTATE 08xxx) never establish that fact. */
+export function isConfirmedCommitRejection(error: unknown): boolean {
+  if (error === null || typeof error !== "object") return false;
+  try {
+    for (const name of ["errno", "code"]) {
+      const descriptor = Object.getOwnPropertyDescriptor(error, name);
+      const code: unknown = descriptor && "value" in descriptor ? descriptor.value : undefined;
+      if (typeof code === "string" && /^(?:40[0-9A-Z]{3}|23[0-9A-Z]{3})$/.test(code) && code !== "40003") return true;
+    }
+  } catch { return false; }
+  return false;
+}
+
+/** An explicit statement ErrorResponse proves PostgreSQL rejected this command.
+ * Transport loss, shutdown and statement_completion_unknown cannot prove that
+ * an autocommit command did not commit before its response was lost. */
+export function isConfirmedStatementRejection(error: unknown): boolean {
+  if (error === null || typeof error !== "object") return false;
+  try {
+    for (const name of ["errno", "code"]) {
+      const descriptor = Object.getOwnPropertyDescriptor(error, name);
+      const code: unknown = descriptor && "value" in descriptor ? descriptor.value : undefined;
+      if (typeof code === "string" && /^[0-9A-Z]{5}$/.test(code)
+        && !/^(?:00|01|02|08)/.test(code) && code !== "40003" && !/^57P0[123]$/.test(code)) return true;
+    }
+  } catch { return false; }
+  return false;
+}
+
+// ORM rollback hooks also own provisional tracker state. On an unknown
+// outcome notify only those internal hooks, never user afterRollback callbacks.
+const uncertaintyHooks = new WeakMap<TransactionCallback, () => void>();
+export function registerTransactionUncertainty(callback: TransactionCallback, uncertain: () => void): void {
+  uncertaintyHooks.set(callback, uncertain);
+}
+export function notifyTransactionUncertainty(callbacks: readonly TransactionCallback[]): void {
+  for (const callback of callbacks) uncertaintyHooks.get(callback)?.();
+}

package/library/orm/Providers/transactionScopes.ts

@@ -0,0 +1,78 @@
+import { ConcurrentTransactionScopeError } from "../errors";
+import type { AfterCommitCallback, TransactionCallback } from "./types";
+
+/** Callback frame owned by one top-level transaction or nested savepoint. */
+export interface TransactionCallbackScope {
+  readonly afterCommit: AfterCommitCallback[];
+  readonly afterRollback: TransactionCallback[];
+  readonly parent?: TransactionCallbackScope;
+  activeChild?: symbol;
+  rollbackOnly?: unknown;
+}
+
+export interface ChildTransactionScope {
+  readonly callbacks: TransactionCallbackScope;
+  readonly ownership: symbol;
+}
+
+export function createTransactionCallbackScope(
+  parent?: TransactionCallbackScope,
+): TransactionCallbackScope {
+  return {
+    afterCommit: [],
+    afterRollback: [],
+    ...(parent === undefined ? {} : { parent }),
+  };
+}
+
+/**
+ * Claims the parent's single connection/savepoint stack synchronously. Nested
+ * scopes are still allowed because they receive their own callback frame.
+ */
+export function beginChildTransactionScope(parent: TransactionCallbackScope): ChildTransactionScope {
+  if (parent.activeChild !== undefined) {
+    throw new ConcurrentTransactionScopeError();
+  }
+  const ownership = Symbol("bazis.transaction-scope");
+  parent.activeChild = ownership;
+  return { callbacks: createTransactionCallbackScope(parent), ownership };
+}
+
+export function endChildTransactionScope(
+  parent: TransactionCallbackScope,
+  ownership: symbol,
+): void {
+  if (parent.activeChild === ownership) {
+    parent.activeChild = undefined;
+  }
+}
+
+/** Successful savepoint release makes its callbacks part of the parent. */
+export function mergeTransactionScopeCallbacks(
+  parent: TransactionCallbackScope,
+  child: TransactionCallbackScope,
+): void {
+  parent.afterCommit.push(...child.afterCommit);
+  parent.afterRollback.push(...child.afterRollback);
+  if (child.rollbackOnly !== undefined && parent.rollbackOnly === undefined) {
+    parent.rollbackOnly = child.rollbackOnly;
+  }
+}
+
+/** A failed savepoint cleanup poisons the whole physical transaction. */
+export function markTransactionRollbackOnly(
+  scope: TransactionCallbackScope,
+  error: unknown,
+): void {
+  let current: TransactionCallbackScope | undefined = scope;
+  while (current !== undefined) {
+    current.rollbackOnly ??= error;
+    current = current.parent;
+  }
+}
+
+export function assertTransactionCanCommit(scope: TransactionCallbackScope): void {
+  if (scope.rollbackOnly !== undefined) {
+    throw scope.rollbackOnly;
+  }
+}