@ultimat3/db 29.3.2 → 30.0.0

package/src/drift.ts

@@ -5,22 +5,27 @@
 
 import { baseClient, type DbClient } from './client';
 import { APPEND_ONLY_DRIFT_CODE, compareAppendOnly } from './drift-append-only';
-import type { DriftDifference } from './drift-findings';
+import type { DriftDifference, DriftKind } from './drift-findings';
 import {
   changedColumn,
   changedForeignKey,
-  changedIndex,
   changedPrimaryKey,
   missingCheck,
-  missingColumn,
-  missingForeignKey,
-  missingIndex,
-  missingTable,
+  notValidConstraint,
   unexpectedColumn,
   unexpectedTable,
   unknownSchema,
 } from './drift-findings';
-import { DbError } from './errors';
+import {
+  changedIndex,
+  missingColumn,
+  missingForeignKey,
+  missingIndex,
+  missingTable,
+} from './drift-missing';
+import { compareRowSecurity, ROW_SECURITY_DRIFT_CODE } from './drift-row-security';
+import { compareTriggers, LIFECYCLE_DRIFT_CODE, RETAIN_DRIFT_CODE } from './drift-triggers';
+import { DbError, type DbErrorCode } from './errors';
 import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
 import {
@@ -76,7 +81,7 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
   for (const index of expected.indexes) {
     const counterpart = present.get(index.name);
     if (counterpart === undefined) {
-      differences.push(missingIndex(live.name, index.name));
+      differences.push(missingIndex(live.schema, live.name, index));
       continue;
     }
     // The method first, and before the column list: a GIN index and a btree over the same column
@@ -86,27 +91,47 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
     // catalog reports as `btree` agree instead of reporting drift on a correct database.
     if (indexMethodOf(counterpart) !== indexMethodOf(index)) {
       differences.push(
-        changedIndex(live.name, index.name, `is a ${indexMethodOf(counterpart)} index`),
+        changedIndex(
+          live.schema,
+          live.name,
+          index,
+          counterpart,
+          `is a ${indexMethodOf(counterpart)} index`,
+        ),
       );
       continue;
     }
     if (counterpart.columns.join(',') !== index.columns.join(',')) {
       differences.push(
-        changedIndex(live.name, index.name, `covers (${counterpart.columns.join(', ')})`),
+        changedIndex(
+          live.schema,
+          live.name,
+          index,
+          counterpart,
+          `covers (${counterpart.columns.join(', ')})`,
+        ),
       );
       continue;
     }
     if (counterpart.unique !== index.unique) {
       differences.push(
-        changedIndex(live.name, index.name, counterpart.unique ? 'is unique' : 'is not unique'),
+        changedIndex(
+          live.schema,
+          live.name,
+          index,
+          counterpart,
+          counterpart.unique ? 'is unique' : 'is not unique',
+        ),
       );
       continue;
     }
     if ((counterpart.order ?? 'asc') !== (index.order ?? 'asc')) {
       differences.push(
         changedIndex(
+          live.schema,
           live.name,
-          index.name,
+          index,
+          counterpart,
           counterpart.order === 'desc' ? 'is descending' : 'is ascending',
         ),
       );
@@ -115,8 +140,10 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
     if ((counterpart.where === null) !== (index.where === null)) {
       differences.push(
         changedIndex(
+          live.schema,
           live.name,
-          index.name,
+          index,
+          counterpart,
           counterpart.where === null ? 'covers every row' : 'is partial',
         ),
       );
@@ -149,7 +176,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
   for (const key of expected.foreignKeys) {
     const counterpart = present.get(foreignKeyTarget(key));
     if (counterpart === undefined) {
-      differences.push(missingForeignKey(live.name, key));
+      differences.push(missingForeignKey(live.schema, live.name, key));
       continue;
     }
     if (onDeleteRule(counterpart.onDelete) !== onDeleteRule(key.onDelete)) {
@@ -186,6 +213,25 @@ function compareChecks(live: TableDescription, expected: TableDescription): Drif
     .map((check) => missingCheck(live.schema, live.name, check));
 }
 
+/**
+ * A declared constraint the catalog holds but never validated. Only the declared side, as everywhere
+ * here: a hand-written `NOT VALID` no snapshot records is the app's decision. Foreign keys are read
+ * by where they point, the identity `compareForeignKeys` uses, so a name the catalog holds and the
+ * snapshot does not still counts.
+ */
+function compareValidated(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  const unvalidated = new Set(live.notValidNames ?? []);
+  if (unvalidated.size === 0) return [];
+  const declared = new Set((expected.checks ?? []).map((check) => check.name));
+  const pointed = new Set(expected.foreignKeys.map(foreignKeyTarget));
+  for (const key of live.foreignKeys) {
+    if (pointed.has(foreignKeyTarget(key))) declared.add(key.name);
+  }
+  return [...unvalidated]
+    .filter((name) => declared.has(name))
+    .map((name) => notValidConstraint(live.schema, live.name, name));
+}
+
 /**
  * The two key lists, compared in ORDER. The comment that used to stand here said a key on one side
  * only "is a difference the key comparison owns" — and no key comparison existed, so a table
@@ -213,7 +259,7 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
   for (const column of expected.columns) {
     const counterpart = liveColumns.get(column.name);
     if (counterpart === undefined) {
-      differences.push(missingColumn(live.name, column.name));
+      differences.push(missingColumn(live.schema, live.name, column));
       continue;
     }
     // Nullability, not the type: the catalog and a snapshot spell types differently often enough
@@ -228,12 +274,23 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
   differences.push(...compareIndexes(live, expected));
   differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
+  differences.push(...compareValidated(live, expected));
   differences.push(...compareAppendOnly(live, expected));
+  differences.push(...compareRowSecurity(live, expected));
+  differences.push(...compareTriggers(live, expected));
   return differences;
 }
 
-/** Pure and total: the same inputs always produce the same ordered report. */
-export function diffSchema(live: SchemaDescription, expected: SchemaDescription): DriftReport {
+/**
+ * Pure and total: the same inputs always produce the same ordered report. `schema` is where the
+ * live side was read — a missing table has no live description to say so, and its repair has to
+ * create it there. Default `public`, `introspectSchema()`'s own.
+ */
+export function diffSchema(
+  live: SchemaDescription,
+  expected: SchemaDescription,
+  schema = 'public',
+): DriftReport {
   const differences: DriftDifference[] = [];
   for (const table of live.tables) {
     const counterpart = findTable(expected, table.name);
@@ -241,7 +298,9 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
     else differences.push(...compareTable(table, counterpart));
   }
   for (const table of expected.tables) {
-    if (findTable(live, table.name) === undefined) differences.push(missingTable(table.name));
+    if (findTable(live, table.name) === undefined) {
+      differences.push(missingTable(schema, table.name, table.columns, table.primaryKey));
+    }
   }
   differences.sort((a, b) => {
     if (a.table !== b.table) return a.table < b.table ? -1 : 1;
@@ -251,10 +310,18 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
   return { ok: differences.length === 0, differences };
 }
 
+/** The kinds that carry their own code — the guarantee each names is the entity's, not a column's. */
+const OWN_CODE: ReadonlyMap<DriftKind, DbErrorCode> = new Map<DriftKind, DbErrorCode>([
+  ['missing-append-only-trigger', APPEND_ONLY_DRIFT_CODE],
+  ['missing-row-security', ROW_SECURITY_DRIFT_CODE],
+  ['unexpected-row-security', ROW_SECURITY_DRIFT_CODE],
+  ['missing-lifecycle-trigger', LIFECYCLE_DRIFT_CODE],
+  ['retain-partitioned', RETAIN_DRIFT_CODE],
+]);
+
 export function driftError(difference: DriftDifference): DbError {
   return new DbError({
-    // One kind carries its own code — the guarantee it names is the entity's, not a column's.
-    code: difference.kind === 'missing-append-only-trigger' ? APPEND_ONLY_DRIFT_CODE : 'X_DB_DRIFT',
+    code: OWN_CODE.get(difference.kind) ?? 'X_DB_DRIFT',
     cause: difference.cause,
     fix: difference.fix,
     meta: { kind: difference.kind, table: difference.table, column: difference.column },
@@ -360,5 +427,5 @@ export async function checkDrift(options: DriftOptions): Promise<DriftReport> {
     client,
     ...(options.schema === undefined ? {} : { schema: options.schema }),
   });
-  return diffSchema(appTables(live), expected);
+  return diffSchema(appTables(live), expected, options.schema);
 }

package/src/entity-shape.ts

@@ -45,6 +45,16 @@ export interface ColumnDescriptionLike {
    * is REPORTED as unrendered rather than dropped (`unrendered.ts`).
    */
   readonly default?: ColumnDefaultLike | undefined;
+  /**
+   * Both ends of this `references()` are tenant-scoped, so the key is composite: `(column, this) ->
+   * target (targetColumn, its key)`. Absent or `null` is the plain key every older description
+   * declares. `@ultimat3/entity` decides it (`describeReferences`), and only the two physical names
+   * cross, because the rest of the key is already on this column.
+   */
+  readonly sameTenant?:
+    | { readonly column: string; readonly targetColumn: string }
+    | null
+    | undefined;
 }
 
 /**
@@ -97,6 +107,14 @@ export interface IndexDescriptionLike {
    * the declarer; this package cannot import it, so the method crosses the seam structurally.
    */
   readonly using?: IndexMethod | undefined;
+  /**
+   * `indexes: [{ on, concurrently: true }]`: build it with `create index concurrently` in a
+   * migration of its own that runs OUTSIDE a transaction (`concurrent-index.ts`), so a hot table
+   * keeps taking writes while it builds. HOW the index is built, never WHAT it is — so it is not
+   * part of the name, not recorded in a snapshot and never a reason to rebuild one. Absent is the
+   * plain, transactional `create index` every index was before it existed.
+   */
+  readonly concurrently?: boolean | undefined;
 }
 
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */
@@ -117,4 +135,61 @@ export interface EntityDescriptionLike {
    * Optional for the reason `invariants` is, and absent reads as "rows may change".
    */
   readonly appendOnly?: boolean | undefined;
+  /**
+   * `entity({ retired: ['legacy'] })`: physical columns old pods may still read and this release
+   * does not (`retired.ts`). Absent is none, for the reason `invariants` is optional.
+   */
+  readonly retired?: readonly string[] | undefined;
+  /**
+   * `entity(name, { view: { sql } })`: a relation Postgres derives, emitted by `generate-view.ts`
+   * and handed to no table arm. Absent is a table, for the reason `invariants` is optional.
+   */
+  readonly view?: { readonly sql: string; readonly materialized?: true | undefined } | undefined;
+  /**
+   * `entity({ history: true })`: every row change is recorded into `history.table` by a trigger
+   * (`generate-history.ts`). Absent is no history, for the reason `invariants` is optional.
+   */
+  readonly history?: HistoryDescriptionLike | undefined;
+  /**
+   * `references(…, { countedIn })` on a child key: counters the database keeps on this table
+   * (`generate-counter.ts`). Absent is none.
+   */
+  readonly counts?: readonly CounterDescriptionLike[] | undefined;
+  /** `entity({ retain })`: rows older than the window are swept by `purge()`. Absent is kept. */
+  readonly retain?: RetainDescriptionLike | undefined;
+}
+
+/** Where a table's row images go, and what its trigger needs to write one. Physical names. */
+export interface HistoryDescriptionLike {
+  /** The history table: `<table>_history`, an entity of its own. */
+  readonly table: string;
+  /** The parent's single primary-key column, recorded as `row_id`. */
+  readonly key: string;
+  /** The parent's tenant column, copied onto every history row, or `null`. */
+  readonly tenant: string | null;
+  /** Columns whose change alone records nothing: the counters the database keeps. */
+  readonly ignore: readonly string[];
+  /** `int8`/`numeric` columns the image stores as their digits, never a JSON number. */
+  readonly text?: readonly string[] | undefined;
+  /** `timestamptz` columns the image stores as a UTC ISO string, whatever the session zone. */
+  readonly instants?: readonly string[] | undefined;
+}
+
+/** One counter, physical names: `<this table>.<column>` counts `<table>` rows by `<references>`. */
+export interface CounterDescriptionLike {
+  readonly column: string;
+  /** The parent's key column the child's foreign key points at. */
+  readonly key: string;
+  /** The child table the trigger sits on. */
+  readonly table: string;
+  /** The child's foreign-key column. */
+  readonly references: string;
+  /** The child's soft-delete column: a stamped row is not counted. `null` when it has none. */
+  readonly softDelete: string | null;
+}
+
+/** `retain: { after, on }`, with `on` physical. */
+export interface RetainDescriptionLike {
+  readonly after: string;
+  readonly on: string;
 }

package/src/errors.ts

@@ -11,7 +11,8 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
+import { IDLE_IN_TRANSACTION_FIX, poolerOptionsRefusedFix } from './pooler-fix';
+import { type DbSqlStateCode, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';
 
 /**
  * Codes this package declares and owns. `X_DB_DRIFT` is db's: it is a statement about migrations
@@ -43,6 +44,20 @@ export const DB_OWNED_ERROR_CODES = [
   'X_DB_SIBLING_SCOPE_TIMEOUT',
   'X_APPEND_ONLY_TRIGGER_MISSING',
   'X_MIGRATION_APPEND_ONLY_BACKFILL',
+  'X_MIGRATION_CONCURRENT_IN_TRANSACTION',
+  'X_DB_TRANSACTION_CLOSED',
+  'X_MIGRATION_ROLLING_UNSAFE',
+  'X_DB_POOLER_OPTIONS_REFUSED',
+  'X_DB_POOLER_SESSION_REQUIRED',
+  'X_DB_STATEMENT_BOUND_LOST',
+  'X_DB_STATEMENT_BOUND_INVALID',
+  'X_MIGRATION_CONCURRENT_PARTITIONED',
+  'X_DB_ROW_SECURITY_BYPASSED',
+  'X_DB_ROW_SECURITY_DRIFT',
+  'X_KEYSET_NULL_KEY',
+  'X_MIGRATION_ROLLBACK_DESTRUCTIVE',
+  'X_ENTITY_RETAIN_INVALID',
+  'X_LIFECYCLE_TRIGGER_MISSING',
 ] as const;
 
 /**
@@ -94,6 +109,28 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_APPEND_ONLY_TRIGGER_MISSING: 'an append-only table has lost its refusing trigger',
   X_MIGRATION_APPEND_ONLY_BACKFILL:
     'a NOT NULL column added to an append-only table needs a default',
+  X_MIGRATION_CONCURRENT_IN_TRANSACTION:
+    'a concurrent index statement is in a migration that runs inside a transaction',
+  X_DB_TRANSACTION_CLOSED: 'statement on a finished transaction',
+  X_MIGRATION_ROLLING_UNSAFE:
+    'this drop or rename would break the pods still running the old release',
+  X_DB_POOLER_OPTIONS_REFUSED:
+    'the connection pooler refused the libpq options a pool connects with',
+  X_DB_POOLER_SESSION_REQUIRED:
+    'this role needs one backend per session, and a transaction pooler gives it none',
+  X_DB_STATEMENT_BOUND_LOST: "the session's statement bound is not the role's",
+  X_DB_STATEMENT_BOUND_INVALID:
+    'a statement bound is not a whole positive number of ms under the role bound',
+  X_MIGRATION_CONCURRENT_PARTITIONED: 'a concurrent index build names a partitioned table',
+  X_DB_ROW_SECURITY_BYPASSED: 'row security is on and the serving role is exempt from it',
+  X_DB_ROW_SECURITY_DRIFT: 'a tenant table and database.rowSecurity disagree about its policy',
+  X_KEYSET_NULL_KEY: 'a keyset page holds a null in one of its sort keys',
+  X_MIGRATION_ROLLBACK_DESTRUCTIVE:
+    'a rollback would serve an older build over a destructive migration',
+  X_ENTITY_RETAIN_INVALID:
+    'entity({ retain }) has no window, sits beside appendOnly, or is on a partitioned table',
+  X_LIFECYCLE_TRIGGER_MISSING:
+    'a history or counter trigger the migrations created is missing from the database',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -197,6 +234,18 @@ export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
     sourceError,
   });
 
+/**
+ * No answer past the role's bound plus the grace (`pool-sweep.ts`), so the server's own bound had to
+ * have answered and the path is dead. The same uncertainty as a connection closed mid-statement,
+ * which is why the cause says it. `X_DB_UNAVAILABLE` is deliberately left out of `DB_ERROR_RETRY`
+ * (unclassified, not terminal), so a job worker RE-RUNS the attempt: an autocommit write that landed
+ * runs again. At least once, as every job is: the write must be idempotent or inside a transaction.
+ */
+export const statementUnanswered = (excerpt: string, boundMs: number): DbError =>
+  dbUnavailable(
+    `no answer within ${boundMs}ms to: ${excerpt} — past the statement bound, so the path is dead and this pool is replaced; if this was an autocommit write it may have landed`,
+  );
+
 /**
  * One `fix:` per classified SQLSTATE, written once. Every one names a command that exists or an
  * edit the reader can make — a `23505` telling an operator the database is unreachable is the
@@ -215,14 +264,14 @@ const SQLSTATE_FIXES = Object.freeze<Record<DbSqlStateCode, string>>({
     'or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is',
   X_DB_FOREIGN_KEY_VIOLATION:
     'insert the row {constraint} points at first, in the same withTransaction(...) — ' +
-    'or drop the write, because the parent it names is gone',
+    "or drop the write, because the parent it names is gone or is not this tenant's",
   X_DB_SERIALIZATION_FAILURE:
     'withTransaction(fn, { retry: 3 })   # fn re-runs from the top, so it must be idempotent',
   X_DB_STATEMENT_TIMEOUT:
     'add the index this statement needs to the entity (indexes: [...]), then: x db gen "add index"',
   X_DB_LOCK_TIMEOUT:
-    `psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'"` +
-    '   # end the blocker, then re-run the statement',
+    "x db diagnostics --json | jq '.data.blockers.rows[] | {pid, blockedBy, blockerState}'" +
+    '   # end the blockedBy session or wait for it, then re-run the statement',
   X_DB_POOL_EXHAUSTED:
     'set DATABASE_POOL_MAX below max_connections / replicas (per-role default: POOL_PROFILES), ' +
     'or cut the replica count',
@@ -253,6 +302,24 @@ export const driverError = (statement: string, sourceError: unknown): DbError =>
   // `X_DB_UNAVAILABLE` said "set DATABASE_URL" to a developer whose database was fine.
   const code = sqlStateCode(sourceError) ?? 'X_DB_STATEMENT_FAILED';
   const constraint = stringField(sourceError, 'constraint');
+  // `08P01` is the protocol's general complaint, so the pooler's own sentence is what decides, and
+  // this one reached no statement: it is the connection every statement of the role would use.
+  if (
+    state === SQLSTATE.protocolViolation &&
+    renderThrowable(sourceError).includes('unsupported startup parameter')
+  ) {
+    // The identifier characters only: the server's text runs on past the name.
+    const parameter = /unsupported startup parameter(?: in options)?: ([A-Za-z0-9_.]+)/.exec(
+      stringField(sourceError, 'message') ?? renderThrowable(sourceError),
+    )?.[1];
+    return new DbError({
+      code: 'X_DB_POOLER_OPTIONS_REFUSED',
+      cause: `[SQLSTATE ${state}] ${renderThrowable(sourceError)} — statement: ${statement}`,
+      fix: poolerOptionsRefusedFix(parameter),
+      meta: { sqlState: state },
+      sourceError,
+    });
+  }
   return new DbError({
     code,
     // The server's SQLSTATE and message FIRST, the statement after: a cause is rendered on one
@@ -265,9 +332,11 @@ export const driverError = (statement: string, sourceError: unknown): DbError =>
     // ours — `$` is legal in a Postgres identifier, so `posts_$&_key` would splice the matched
     // `{constraint}` back into the fix line an author is meant to paste.
     fix:
-      code === 'X_DB_STATEMENT_FAILED'
-        ? `psql "$DATABASE_URL" -c "<the statement in cause>"   # SQLSTATE ${state} is the server's verdict on it: fix the SQL or the data it names, not the connection`
-        : SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
+      state === SQLSTATE.idleInTransactionTimeout
+        ? IDLE_IN_TRANSACTION_FIX
+        : code === 'X_DB_STATEMENT_FAILED'
+          ? `psql "$DATABASE_URL" -c "<the statement in cause>"   # SQLSTATE ${state} is the server's verdict on it: fix the SQL or the data it names, not the connection`
+          : SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
     meta: {
       sqlState: state,
       ...(constraint === undefined ? {} : { constraint }),
@@ -317,9 +386,11 @@ export const poolAcquireTimeout = (waitedMs: number, max: number): DbError =>
 export const poolMaxInvalid = (received: string): DbError =>
   new DbError({
     code: 'X_ENV_MISSING',
-    cause: `DATABASE_POOL_MAX is ${JSON.stringify(received)}, which is not a positive integer`,
+    // `describeValue`, never the value, in the cause AND meta: an operator who pasted a connection
+    // string here would read its password in the boot log and every `--json` payload.
+    cause: `DATABASE_POOL_MAX is ${describeValue(received)}, which is not a positive integer`,
     fix: 'DATABASE_POOL_MAX=20   # a whole number of connections per process, or unset it',
-    meta: { received },
+    meta: { received: describeValue(received) },
   });
 
 /**

package/src/expected-loop.ts

@@ -1,7 +1,7 @@
-// Single responsibility: the one way to declare that a loop of statements is deliberate, so a
-// statement-level diagnostic reports the loops nobody argued for and stays quiet about the rest.
-// A scope with a written reason — never a comment pragma and never a config list of exempt call
-// sites (axiom 1), because both put the argument somewhere other than the loop it defends.
+// Single responsibility: the one way to declare a loop of statements deliberate, or a statement a
+// whole-table read, so a diagnostic reports only what nobody argued for. A scope with a written
+// reason — never a comment pragma nor a config list of exempt call sites (axiom 1): both put the
+// argument somewhere other than the statement it defends.
 
 // The reason has to outlive every `await` inside the scope and a module-scope variable would be
 // shared by two concurrent loops, so it needs an async context — opened through core's one lazy
@@ -52,3 +52,33 @@ export function expectedQueryLoop<T>(reason: string, fn: () => T): T {
 export function expectedQueryLoopReason(): string | undefined {
   return storage.get();
 }
+
+const scans = asyncContext<string>('the expected-seq-scan reason');
+
+/**
+ * Run `fn` with every statement it issues marked as one that must read its table whole, carrying
+ * `reason`. The plan sweep `x exercise` runs reads it off each statement it saw, and lists the
+ * statement as exempt with the reason instead of `X_QUERY_UNINDEXED` — for a hand-written report
+ * over every row, never for a lookup that lacks its index. A table that is small by nature says so
+ * once, on the entity: `entity('plans', { scan: '<why>' })`. Same shape as `expectedQueryLoop`:
+ * required, non-blank, innermost wins, and a verdict suppressed — the statement still runs.
+ *
+ * ```ts
+ * await expectedSeqScan('the nightly digest reads every subscription once', () =>
+ *   db().query(sql`select id, email from subscriptions where active`),
+ * );
+ * ```
+ */
+export function expectedSeqScan<T>(reason: string, fn: () => T): T {
+  assert(
+    reason.trim() !== '',
+    'expectedSeqScan() was given a blank reason, so the scan it exempts carries no argument',
+    "pass why the statement must read the whole table: expectedSeqScan('the nightly digest reads every row once', fn)",
+  );
+  return scans.run(reason, fn);
+}
+
+/** The innermost `expectedSeqScan` reason in force, or `undefined` outside every scope. */
+export function expectedSeqScanReason(): string | undefined {
+  return scans.get();
+}

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) };
+}