@ultimat3/db 29.4.0 → 30.0.0

package/src/failure-store-pg.ts

@@ -0,0 +1,157 @@
+// The durable failure-bundle store: `x_failures`, written OUTSIDE the request's transaction (which
+// a 5xx rolled back), read by `x repro` and purged on a window the app chooses. Bundles only:
+// counts per fingerprint are `x_error_groups`' (one table per fact).
+
+import type { FailureBundle, FailureStore } from '@ultimat3/core';
+import { finiteCount, isJsonObject } from '@ultimat3/core';
+import type { DbClient } from './client';
+import { db } from './client';
+import { outsideTransaction } from './transaction';
+
+export const FAILURES_TABLE = 'x_failures';
+
+/**
+ * Applied by the boot (`FRAMEWORK_SCHEMA`), never by an app migration, whether or not capture is
+ * on — enabling it must not be the deploy that finds the table missing. `bundle` is the whole
+ * `FailureBundle`; the columns beside it are the lookups `x repro` makes.
+ */
+export const SQL_FAILURES_TABLE = `
+create table if not exists x_failures (
+  id          uuid        primary key,
+  fingerprint text        not null,
+  code        text        not null,
+  at          timestamptz not null,
+  request_id  text,
+  trace_id    text,
+  build       text,
+  primitive   text        not null,
+  name        text        not null,
+  bundle      jsonb       not null
+);
+
+create index if not exists x_failures_fingerprint_idx on x_failures (fingerprint, at desc);
+create index if not exists x_failures_request_idx on x_failures (request_id);
+create index if not exists x_failures_trace_idx on x_failures (trace_id);
+create index if not exists x_failures_at_idx on x_failures (at);
+`;
+
+/** The most bundles one `list` answers. */
+export const MAX_FAILURE_LIST = 200;
+
+export interface FailureSummary {
+  readonly id: string;
+  readonly fingerprint: string;
+  readonly code: string;
+  readonly at: string;
+  readonly requestId: string | null;
+  readonly name: string;
+  readonly build: string | null;
+}
+
+export interface PostgresFailureStore extends FailureStore {
+  /** By bundle id, request id or trace id — newest first. */
+  find(id: string): Promise<FailureBundle | undefined>;
+  /** The newest bundle of a group. */
+  latest(fingerprint: string): Promise<FailureBundle | undefined>;
+  list(options?: {
+    readonly code?: string;
+    readonly limit?: number;
+  }): Promise<readonly FailureSummary[]>;
+  purge(beforeMs: number): Promise<number>;
+}
+
+interface BundleRow {
+  readonly bundle: unknown;
+}
+
+const bundleOf = (rows: readonly BundleRow[]): FailureBundle | undefined => {
+  const raw = rows[0]?.bundle;
+  const parsed: unknown = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  // Written by `save` below from a `FailureBundle`; a row that is not an object is not one.
+  return isJsonObject(parsed) ? (parsed as unknown as FailureBundle) : undefined;
+};
+
+const iso = (value: unknown): string =>
+  value instanceof Date ? value.toISOString() : new Date(String(value)).toISOString();
+
+export function postgresFailureStore(
+  options: { readonly client?: DbClient } = {},
+): PostgresFailureStore {
+  const client = (): DbClient => options.client ?? db();
+  // Never inside the caller's transaction: the request that failed rolled it back.
+  const send = <T>(text: string, values: readonly unknown[]): Promise<readonly T[]> =>
+    outsideTransaction(() => client().query<T>({ text, values: [...values] }));
+  return {
+    async save(bundle) {
+      await send(
+        `insert into ${FAILURES_TABLE} (id, fingerprint, code, at, request_id, trace_id, build, primitive, name, bundle) values ($1, $2, $3, $4::timestamptz, $5, $6, $7, $8, $9, $10::text::jsonb) on conflict (id) do nothing`,
+        [
+          bundle.id,
+          bundle.fingerprint,
+          bundle.code,
+          new Date(bundle.at).toISOString(),
+          bundle.requestId,
+          bundle.traceId,
+          bundle.build,
+          bundle.primitive,
+          bundle.name,
+          JSON.stringify(bundle),
+        ],
+      );
+    },
+    async find(id) {
+      return bundleOf(
+        await send<BundleRow>(
+          `select bundle from ${FAILURES_TABLE} where id::text = $1 or request_id = $1 or trace_id = $1 order by at desc limit 1`,
+          [id],
+        ),
+      );
+    },
+    async latest(fingerprint) {
+      return bundleOf(
+        await send<BundleRow>(
+          `select bundle from ${FAILURES_TABLE} where fingerprint = $1 order by at desc limit 1`,
+          [fingerprint],
+        ),
+      );
+    },
+    async list(query = {}) {
+      const limit = Math.min(
+        finiteCount('postgresFailureStore.list', 'limit', query.limit ?? 50, 1),
+        MAX_FAILURE_LIST,
+      );
+      const rows = await send<Record<string, unknown>>(
+        `select id::text as id, fingerprint, code, at, request_id, name, build from ${FAILURES_TABLE}${query.code === undefined ? '' : ' where code = $2'} order by at desc limit $1`,
+        query.code === undefined ? [limit] : [limit, query.code],
+      );
+      return rows.map((row) => ({
+        id: String(row['id']),
+        fingerprint: String(row['fingerprint']),
+        code: String(row['code']),
+        at: iso(row['at']),
+        requestId: typeof row['request_id'] === 'string' ? row['request_id'] : null,
+        name: String(row['name']),
+        build: typeof row['build'] === 'string' ? row['build'] : null,
+      }));
+    },
+    async purge(beforeMs) {
+      const rows = await send<{ removed: number | string }>(
+        `with gone as (delete from ${FAILURES_TABLE} where at < $1::timestamptz returning 1) select count(*)::int as removed from gone`,
+        [new Date(beforeMs).toISOString()],
+      );
+      return Number(rows[0]?.removed ?? 0);
+    },
+  };
+}
+
+/**
+ * A `purge()` target (`@ultimat3/jobs`, structural): bundles older than `keepMs`, measured on the
+ * JOB's clock. No default window: how long user input may be kept is the app's decision.
+ */
+export function failurePurgeTarget(
+  store: Pick<PostgresFailureStore, 'purge'>,
+  options: { readonly keepMs: number },
+): { readonly name: string; purgeExpired(nowMs: number): Promise<number> } {
+  const keepMs = finiteCount('failurePurgeTarget', 'keepMs', options.keepMs, 1);
+  return { name: FAILURES_TABLE, purgeExpired: (nowMs) => store.purge(nowMs - keepMs) };
+}

package/src/foreign-key-plan.ts

@@ -1,7 +1,9 @@
-// Single responsibility: which foreign keys a migration must add or drop, and into which of the
-// two buckets each statement goes — `constraints` runs AFTER the table statements, `preDrops`
-// BEFORE them. `generate.ts` assembles the plan; `foreign-key.ts` writes the SQL.
+// Single responsibility: which foreign keys a migration adds or drops, and where each statement
+// goes — `constraints` AFTER the table statements, `preDrops` BEFORE them, or the deferred step for
+// a key on a live table, whose add and validate would scan it under a lock that stops writes.
+// `generate.ts` assembles the plan; `foreign-key.ts` writes the SQL.
 
+import { type ConcurrentPlan, contractKey, deferKey, targetIndexDeferred } from './concurrent-plan';
 import type { EntityDescriptionLike } from './entity-shape';
 import {
   addForeignKey,
@@ -9,9 +11,11 @@ import {
   foreignKeyTarget,
   keyId,
   onDeleteRule,
+  referenceParts,
   unrestorableNote,
 } from './foreign-key';
 import type { ForeignKeyDescription, TableDescription } from './introspect';
+import { sameTenantKeyName } from './same-tenant';
 
 /** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
 export interface Plan {
@@ -19,16 +23,6 @@ export interface Plan {
   readonly down: string[];
 }
 
-/**
- * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
- * clause that writes the constraint and the snapshot that records it must not disagree about what
- * it points at, or drift reports a key the database holds exactly as declared.
- */
-export function referenceParts(references: string): readonly [string, string] {
-  const [table = references, column = 'id'] = references.split('.');
-  return [table, column];
-}
-
 /**
  * The keys this entity declares, recorded so drift can see one dropped by hand. Recording
  * `foreignKeys: []` while the same run emitted a constraint was a snapshot claiming a constraint
@@ -43,12 +37,28 @@ export function referenceParts(references: string): readonly [string, string] {
  * `onDelete` is the column's own, and `addForeignKey` spells it: a rule recorded here while no
  * clause declared one would be a claim about the database that is not true, which is what it was
  * until the clause learned to write it out.
+ *
+ * A column carrying `sameTenant` is the composite `(tenant, column) -> target (tenant, target)`, under
+ * a name of its own so the plain key it replaces on a live table can stand until it validates
+ * (`sameTenantKeyName`). Its `set null` names the one column: bare, Postgres nulls every column of a
+ * key, and that includes the tenant.
  */
 export function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
   return entity.columns
     .filter((column) => column.references !== null)
     .map((column): ForeignKeyDescription => {
       const [table, key] = referenceParts(column.references ?? '');
+      const tenant = column.sameTenant;
+      if (tenant !== null && tenant !== undefined) {
+        const rule = column.onDelete ?? null;
+        return {
+          name: sameTenantKeyName(entity.table, column.column),
+          columns: [tenant.column, column.column],
+          referencedTable: table,
+          referencedColumns: [tenant.targetColumn, key],
+          onDelete: rule === 'set null' ? `set null (${column.column})` : rule,
+        };
+      }
       return {
         name: `${entity.table}_${column.column}_fkey`,
         columns: [column.column],
@@ -92,14 +102,35 @@ export function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescript
  * every table statement; one the entity dropped is left where the retype left it, because dropping
  * it a second time is `42704`; and one whose `on delete` moved comes back carrying the new rule.
  * Its `down` is the retype's, pushed where reversal puts it after both ends are back.
+ *
+ * WHICH PHASE. A key on a table in `live` goes to the deferred step (`deferKey`): `not valid`, then
+ * `validate`. So does a key on a table this migration creates whose target index only the deferred
+ * step builds, since `add constraint` before that index exists is `42830`. One path for every such
+ * key, whether or not its target index is new, so the question is never asked twice. Two stay
+ * transactional: a key on a new table over a target that already has its index (nothing to scan,
+ * byte-identical to what every table's first migration always said), and a retype's re-add, which
+ * holds ACCESS EXCLUSIVE for the rewrite already, so a second pass buys nothing and costs a window
+ * with no key. A recorded key whose column a deferred key now covers goes in the contract phase;
+ * until then the old key still guards every write.
  */
 export function foreignKeyPlan(
   entity: EntityDescriptionLike,
   live: TableDescription | undefined,
   plans: ConstraintPlans,
 ): void {
-  const { constraints, preDrops, doomed, predropped } = plans;
+  const { constraints, preDrops, doomed, predropped, concurrent } = plans;
   const wanted = foreignKeysOf(entity);
+  const movedByRetype = new Set(
+    (live?.foreignKeys ?? [])
+      .filter((key) => predropped.has(keyId(entity.table, key.name)))
+      .map(foreignKeyTarget),
+  );
+  const deferredColumns = new Set<string>();
+  const swapped = new Set<string>();
+  const defer = (key: ForeignKeyDescription, recorded?: ForeignKeyDescription): void => {
+    deferKey(entity.table, key, recorded, concurrent);
+    for (const column of key.columns) deferredColumns.add(column);
+  };
   const recordedKeys = (live?.foreignKeys ?? []).filter(
     (key) => !predropped.has(keyId(entity.table, key.name)),
   );
@@ -114,6 +145,19 @@ export function foreignKeyPlan(
       continue;
     }
     if (recorded === undefined) {
+      const onLiveTable = live !== undefined && !movedByRetype.has(foreignKeyTarget(key));
+      if (
+        onLiveTable ||
+        targetIndexDeferred(concurrent, key.referencedTable, key.referencedColumns)
+      ) {
+        // A recorded key repointed under its own name: the one ALTER is its contract too.
+        const named = recordedKeys.find((each) => each.name === key.name);
+        if (named !== undefined) swapped.add(named.name);
+        // Moved away from a table this migration drops: `preDrops` takes it first, and there is
+        // nothing to restore it onto, so the snapshot and the `down` treat this key as new.
+        defer(key, named !== undefined && doomed.has(named.referencedTable) ? undefined : named);
+        continue;
+      }
       constraints.up.push(addForeignKey(entity.table, key));
       constraints.down.push(dropForeignKey(entity.table, key.name));
       continue;
@@ -121,15 +165,13 @@ export function foreignKeyPlan(
     // The rule is not part of a key's identity, so the same key under a new one is a rebuild —
     // Postgres has no `alter constraint` for it, the same reason `redefineIndex` recreates.
     if (onDeleteRule(recorded.onDelete) === onDeleteRule(key.onDelete)) continue;
-    constraints.up.push(
-      dropForeignKey(entity.table, recorded.name),
-      addForeignKey(entity.table, key),
-    );
-    // Pushed forwards and read backwards, like `redefineIndex`: `down` is reversed at assembly.
-    constraints.down.push(
-      addForeignKey(entity.table, recorded),
-      dropForeignKey(entity.table, key.name),
-    );
+    // Under its own name the one ALTER swaps it; under another the recorded key holds till contract.
+    if (recorded.name === key.name) {
+      defer(key, recorded);
+    } else {
+      defer(key);
+      contractKey(entity.table, recorded, concurrent);
+    }
   }
   const declared = new Set(wanted.map(foreignKeyTarget));
   const columns = new Set(entity.columns.map((column) => column.column));
@@ -142,6 +184,11 @@ export function foreignKeyPlan(
       unrestorableDrop(entity.table, key.name, key.referencedTable, preDrops);
       continue;
     }
+    if (swapped.has(key.name)) continue;
+    if (key.columns.some((column) => deferredColumns.has(column))) {
+      contractKey(entity.table, key, concurrent);
+      continue;
+    }
     constraints.up.push(dropForeignKey(entity.table, key.name));
     constraints.down.push(addForeignKey(entity.table, key));
   }
@@ -160,6 +207,11 @@ export interface ConstraintPlans {
    * `add constraint`, and it is this function that writes it.
    */
   readonly predropped: ReadonlySet<string>;
+  /**
+   * The deferred step. Filled by every table's `diffTable` BEFORE this function runs for any table,
+   * since a key's own table says nothing about whether its target's index is deferred.
+   */
+  readonly concurrent: ConcurrentPlan;
 }
 
 /**

package/src/foreign-key.ts

@@ -40,6 +40,38 @@ export function onDeleteRule(raw: string | null): string | null {
 
 const WRITABLE = new Set(['cascade', 'restrict', 'set null', 'set default']);
 
+/**
+ * `set null (a, b)`: only those columns go, the form a composite key needs to keep its other half
+ * (Postgres 15+). The list is the rule's own text in a description and in the snapshot, so a key
+ * that changes it reads as a changed rule, and `introspectSchema()` answers in the same spelling.
+ */
+const SET_NULL_COLUMNS = /^set null \((.+)\)$/;
+
+/** The clause for a screened rule: `identifier` for each name, never the text as it arrived. */
+const ruleClause = (rule: string | null): string => {
+  if (rule === null) return '';
+  const listed = SET_NULL_COLUMNS.exec(rule)?.[1];
+  if (listed === undefined) return ` on delete ${rule}`;
+  return ` on delete set null (${quoted(listed.split(',').map((name) => name.trim()))})`;
+};
+
+/** Whether a rule is one `addClause` may write: a listed column has to be one of the key's own. */
+const isWritable = (rule: string, key: ForeignKeyDescription): boolean => {
+  const listed = SET_NULL_COLUMNS.exec(rule)?.[1];
+  if (listed === undefined) return WRITABLE.has(rule);
+  return listed.split(',').every((name) => key.columns.includes(name.trim()));
+};
+
+/**
+ * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
+ * clause that writes the constraint and the snapshot that records it must not disagree about what
+ * it points at, or drift reports a key the database holds exactly as declared.
+ */
+export function referenceParts(references: string): readonly [string, string] {
+  const [table = references, column = 'id'] = references.split('.');
+  return [table, column];
+}
+
 /**
  * A key's identity: its columns, its target table, its target columns — never its name. Postgres
  * names an inline `references` clause `<table>_<column>_fkey` and a hand-written migration may have
@@ -91,26 +123,65 @@ const quoted = (names: readonly string[]): string =>
  * `X_INVARIANT` rather than DDL, the same discipline `createIndex` applies to an index naming no
  * column: `entity()`'s option is a closed union, so only a hand-built description can get here.
  */
-export function addForeignKey(table: string, key: ForeignKeyDescription): string {
+export function addForeignKey(
+  table: string,
+  key: ForeignKeyDescription,
+  options: { readonly notValid?: boolean } = {},
+): string {
+  return (
+    `alter table ${identifier(table).text} ${addClause(table, key)}` +
+    `${options.notValid === true ? ' not valid' : ''};`
+  );
+}
+
+/** The `add constraint …` clause alone, with the rule screened. Both statement forms end in it. */
+function addClause(table: string, key: ForeignKeyDescription): string {
   const rule = onDeleteRule(key.onDelete);
   assert(
-    rule === null || WRITABLE.has(rule),
+    rule === null || isWritable(rule, key),
     `foreign key "${key.name}" on "${table}" declares an unknown on delete rule`,
     `references(() => target.id, { onDelete: 'cascade' })   # cascade | restrict | set null`,
   );
   return (
-    `alter table ${identifier(table).text} add constraint ${identifier(key.name).text} ` +
-    `foreign key (${quoted(key.columns)}) ` +
+    `add constraint ${identifier(key.name).text} foreign key (${quoted(key.columns)}) ` +
     `references ${identifier(key.referencedTable).text} (${quoted(key.referencedColumns)})` +
-    `${rule === null ? '' : ` on delete ${rule}`};`
+    ruleClause(rule)
   );
 }
 
+/**
+ * The deferred step's add: `not valid`, so it scans nothing and new writes are held to it at once.
+ *
+ * One ALTER and not a drop beside an add. `add constraint` has no `if not exists`, so the drop is
+ * what makes the step re-runnable — and two statements would each take a transaction of their own
+ * (`migration-step.ts`), leaving a same-named rebuild with no key at all between them.
+ */
+export function replaceForeignKeyNotValid(table: string, key: ForeignKeyDescription): string {
+  return (
+    `alter table ${identifier(table).text} drop constraint if exists ${identifier(key.name).text}, ` +
+    `${addClause(table, key)} not valid;`
+  );
+}
+
+/**
+ * Scans the rows a `not valid` constraint let stand, under SHARE UPDATE EXCLUSIVE on the table:
+ * reads and writes keep flowing. On a constraint that is already valid it does nothing, so a step
+ * failing after this statement re-runs it harmlessly.
+ */
+export function validateConstraint(table: string, name: string): string {
+  return `alter table ${identifier(table).text} validate constraint ${identifier(name).text};`;
+}
+
 /** The reverse. Dropping a constraint loses nothing the database cannot rebuild. */
 export function dropForeignKey(table: string, constraint: string): string {
   return `alter table ${identifier(table).text} drop constraint ${identifier(constraint).text};`;
 }
 
+/** The deferred step's drop, re-runnable: the step re-runs from its first statement on a failure. */
+export function dropForeignKeyIfExists(table: string, constraint: string): string {
+  return `alter table ${identifier(table).text} drop constraint if exists ${identifier(constraint).text};`;
+}
+
 /**
  * What a `down` says in place of an `add constraint` it cannot run: the key's table or its target
  * is dropped by this migration, so there is nothing to add the constraint back onto.

package/src/generate-counter.ts

@@ -0,0 +1,85 @@
+// Single responsibility: the trigger `references(…, { countedIn })` compiles to, and the
+// recount that makes a counter true again. The trigger sits on the CHILD and moves the parent's
+// integer in the same transaction, so `deleteWhere`, `upsertAll` and raw SQL keep it as an insert does.
+
+import type { CounterDescriptionLike } from './entity-shape';
+import { triggerInstall } from './generate-history';
+import type { TriggerRecord } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * `ultimate_count_<crc32 of parent.column>`: per counter, because each body names its own tables,
+ * and short, because a name past 63 bytes is truncated in silence and drift would compare the
+ * untruncated one forever. CRC32 is Bun's, stable across processes and platforms.
+ */
+export function counterTriggerName(parent: string, counter: CounterDescriptionLike): string {
+  const hash = Bun.hash.crc32(`${parent}.${counter.column}`).toString(16).padStart(8, '0');
+  return `ultimate_count_${hash}`;
+}
+
+/** Whether a row image (`old`/`new`) is counted: it names a parent and is not soft-deleted. */
+const counted = (image: 'old' | 'new', counter: CounterDescriptionLike): string =>
+  `${image}.${identifier(counter.references).text} is not null` +
+  (counter.softDelete === null
+    ? ''
+    : ` and ${image}.${identifier(counter.softDelete).text} is null`);
+
+const bump = (parent: string, counter: CounterDescriptionLike, image: string, sign: string) =>
+  `update ${identifier(parent).text} set ${identifier(counter.column).text} = ` +
+  `${identifier(counter.column).text} ${sign} 1 where ${identifier(counter.key).text} = ` +
+  `${image}.${identifier(counter.references).text};`;
+
+/**
+ * Old image out, new image in: an insert adds one, a delete takes one, a re-parent or a soft delete
+ * moves it. Lock order is the PARENT row, so a hot parent serializes its writers — `countBy` plus a
+ * cache is the alternative where that matters. `after … for each row`, so a refused write moves
+ * nothing, and `update of` the two columns that can change the answer, so no other update pays.
+ */
+export function counterTrigger(parent: string, counter: CounterDescriptionLike): TriggerRecord {
+  const name = counterTriggerName(parent, counter);
+  const fn =
+    `create or replace function ${identifier(name).text}() returns trigger language plpgsql as ` +
+    `$counter$ begin if tg_op <> 'INSERT' and ${counted('old', counter)} then ` +
+    `${bump(parent, counter, 'old', '-')} end if; if tg_op <> 'DELETE' and ` +
+    `${counted('new', counter)} then ${bump(parent, counter, 'new', '+')} end if; ` +
+    'return null; end; $counter$;';
+  const watched = [counter.references, ...(counter.softDelete === null ? [] : [counter.softDelete])]
+    .map((column) => identifier(column).text)
+    .join(', ');
+  return triggerInstall(
+    name,
+    { name, sql: fn },
+    `after insert or delete or update of ${watched}`,
+    counter.table,
+    '',
+  );
+}
+
+/** The true count of one parent row, as a correlated subquery over `parent` aliased `p`. */
+const truth = (counter: CounterDescriptionLike): string =>
+  `(select count(*)::integer from ${identifier(counter.table).text} c where ` +
+  `c.${identifier(counter.references).text} = p.${identifier(counter.key).text}` +
+  (counter.softDelete === null ? '' : ` and c.${identifier(counter.softDelete).text} is null`) +
+  ')';
+
+/**
+ * Sets every drifted counter to the truth. A migration adding a counter runs it once, so a table
+ * that already holds rows starts true; `x db recount --write` runs it again, by key range.
+ */
+export function recountSql(parent: string, counter: CounterDescriptionLike): string {
+  return (
+    `update ${identifier(parent).text} p set ${identifier(counter.column).text} = ${truth(counter)} ` +
+    `where p.${identifier(counter.column).text} is distinct from ${truth(counter)};`
+  );
+}
+
+/** The drifted rows, for `x db recount`'s report: key, stored and true count. */
+export function recountDriftSql(parent: string, counter: CounterDescriptionLike): string {
+  return (
+    `select p.${identifier(counter.key).text}::text as "key", ` +
+    `p.${identifier(counter.column).text} as "stored", ${truth(counter)} as "actual" ` +
+    `from ${identifier(parent).text} p ` +
+    `where p.${identifier(counter.column).text} is distinct from ${truth(counter)} ` +
+    `order by p.${identifier(counter.key).text}`
+  );
+}

package/src/generate-history.ts

@@ -0,0 +1,142 @@
+// Single responsibility: the two triggers `entity({ history: true })` compiles to. One records a
+// before and an after image of every row change into `<table>_history`; the other refuses every
+// rewrite of that history, and every delete but a purge's. Triggers and not the repository, because
+// only a trigger sees `updateWhere`, a cascade and raw SQL.
+
+import type { HistoryDescriptionLike } from './entity-shape';
+import type { TriggerRecord } from './introspect';
+import { identifier, literal } from './sql';
+
+/** On the PARENT table. One name everywhere: a trigger name is unique per table, never per schema. */
+export const HISTORY_TRIGGER = 'ultimate_history';
+/** On the HISTORY table. */
+export const HISTORY_GUARD_TRIGGER = 'ultimate_history_guard';
+export const HISTORY_FUNCTION = 'ultimate_record_history';
+export const HISTORY_GUARD_FUNCTION = 'ultimate_guard_history';
+
+/** The transaction-local settings the two functions read. `setLocal` is their one writer. */
+export const ACTOR_SETTING = 'x.actor';
+export const REQUEST_SETTING = 'x.request';
+export const PURGE_SETTING = 'x.purge';
+
+/** A JSON number's own digits, as text: `->>` spells a jsonb numeric exactly, scale included. */
+const DIGITS = { type: 'number', text: '{image} ->> k' };
+/** The instant `to_jsonb` spelled with the session's offset, re-spelled in UTC as `toISOString`. */
+const INSTANT = {
+  type: 'string',
+  text: `to_char(({image} ->> k)::timestamptz at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`,
+};
+
+/** One image's key `k` replaced by its text, when it holds the JSON type `to_jsonb` gave it. */
+const exact = (image: string, how: { readonly type: string; readonly text: string }): string =>
+  `if jsonb_typeof(${image} -> k) = '${how.type}' then ${image} := jsonb_set(${image}, array[k], ` +
+  `coalesce(to_jsonb(${how.text.replaceAll('{image}', image)}), ${image} -> k)); end if;`;
+
+/**
+ * One function for every history table: the trigger's arguments name the table, the key, the tenant
+ * column, the columns whose change alone records nothing (the counters the database keeps), and the
+ * columns `to_jsonb` spells otherwise than the row: an `int8`/`numeric` stored as its digits (a JSON
+ * number is a float to every reader past 2^53 and drops a scale's zeros), a `timestamptz` as UTC ISO
+ * to the millisecond (`to_jsonb` writes the SESSION zone's offset) — what the memory driver keeps.
+ * An argument a trigger installed before it existed reads NULL, and NULL is the empty list.
+ *
+ * `jsonb_populate_record` builds the history row, so every value lands in its column's own type —
+ * a uuid tenant from a jsonb text, with no cast spliced per table. A statement that changes nothing
+ * records nothing; the actor and request are what the WRITE'S transaction set, so a statement with
+ * no transaction around it records `null`, never a guess.
+ */
+export const HISTORY_FUNCTION_SQL =
+  `create or replace function ${identifier(HISTORY_FUNCTION).text}() returns trigger ` +
+  'language plpgsql as $history$ declare ' +
+  "source jsonb := case when tg_op = 'DELETE' then to_jsonb(old) else to_jsonb(new) end; " +
+  "prior jsonb := case when tg_op = 'INSERT' then null else to_jsonb(old) end; " +
+  'ignored text[] := tg_argv[3]::text[]; ' +
+  "digits text[] := coalesce(tg_argv[4], '{}')::text[]; " +
+  "instants text[] := coalesce(tg_argv[5], '{}')::text[]; " +
+  'k text; ' +
+  "begin if tg_op = 'UPDATE' and (prior - ignored) = (source - ignored) then return null; end if; " +
+  'foreach k in array digits loop ' +
+  `${exact('source', DIGITS)} ${exact('prior', DIGITS)} end loop; ` +
+  'foreach k in array instants loop ' +
+  `${exact('source', INSTANT)} ${exact('prior', INSTANT)} end loop; ` +
+  "execute format('insert into %I select * from jsonb_populate_record(null::%I, $1)', " +
+  'tg_argv[0], tg_argv[0]) using jsonb_build_object(' +
+  "'id', gen_random_uuid(), 'row_id', source ->> tg_argv[1], 'op', lower(tg_op), 'at', now(), " +
+  `'actor_id', nullif(current_setting('${ACTOR_SETTING}', true), ''), ` +
+  `'request_id', nullif(current_setting('${REQUEST_SETTING}', true), ''), ` +
+  "'before', prior, 'after', case when tg_op = 'DELETE' then null else source end) || " +
+  "case when tg_argv[2] = '' then '{}'::jsonb " +
+  'else jsonb_build_object(tg_argv[2], source -> tg_argv[2]) end; ' +
+  'return null; end; $history$;';
+
+/**
+ * Update refused always; delete refused unless `x.purge` names THIS table — `retainTarget` and a
+ * subject erase set it through `setLocal`. As `x.cross` is, this catches forgetting, not hostile SQL
+ * in the app's own process. The code leads the message and the SQLSTATE is `23001`, exactly as the
+ * append-only trigger's: a history table is append-only to everything but its sweep.
+ */
+export const HISTORY_GUARD_FUNCTION_SQL =
+  `create or replace function ${identifier(HISTORY_GUARD_FUNCTION).text}() returns trigger ` +
+  "language plpgsql as $history_guard$ begin if tg_op = 'DELETE' and " +
+  `current_setting('${PURGE_SETTING}', true) = tg_table_name then return old; end if; ` +
+  "raise exception 'X_ENTITY_APPEND_ONLY: % on %.% is refused, the table is history', " +
+  "tg_op, tg_table_schema, tg_table_name using errcode = '23001', hint = 'history is written " +
+  "by its trigger and removed only by purge({ entities: ''declared'' })'; end; $history_guard$;";
+
+/** Function, drop-if-exists, create: idempotent over a missing and a DISABLED trigger alike. */
+export const triggerInstall = (
+  name: string,
+  fn: { readonly name: string; readonly sql: string },
+  timing: string,
+  table: string,
+  args: string,
+): TriggerRecord => ({
+  name,
+  install: [
+    fn.sql,
+    `drop trigger if exists ${identifier(name).text} on ${identifier(table).text};`,
+    `create trigger ${identifier(name).text} ${timing} on ${identifier(table).text} for each row ` +
+      `execute function ${identifier(fn.name).text}(${args});`,
+  ],
+});
+
+/** A text[] literal of physical names — each one already a validated identifier. */
+const nameArray = (names: readonly string[]): string =>
+  literal(`{${names.map((name) => identifier(name).text).join(',')}}`).text;
+
+/** The parent's recording trigger and the history table's guard, keyed by the table each sits on. */
+export function historyTriggers(
+  parent: string,
+  history: HistoryDescriptionLike,
+): readonly (readonly [string, TriggerRecord])[] {
+  const args = [
+    literal(history.table).text,
+    literal(history.key).text,
+    literal(history.tenant ?? '').text,
+    nameArray(history.ignore),
+    nameArray(history.text ?? []),
+    nameArray(history.instants ?? []),
+  ].join(', ');
+  return [
+    [
+      parent,
+      triggerInstall(
+        HISTORY_TRIGGER,
+        { name: HISTORY_FUNCTION, sql: HISTORY_FUNCTION_SQL },
+        'after insert or update or delete',
+        parent,
+        args,
+      ),
+    ],
+    [
+      history.table,
+      triggerInstall(
+        HISTORY_GUARD_TRIGGER,
+        { name: HISTORY_GUARD_FUNCTION, sql: HISTORY_GUARD_FUNCTION_SQL },
+        'before update or delete',
+        history.table,
+        '',
+      ),
+    ],
+  ];
+}