@ultimat3/db 23.0.0 → 25.0.0

package/src/drift-findings.ts

@@ -1,19 +1,13 @@
-// Single responsibility: what a schema difference is CALLED and what its `fix:` line says — one
-// constructor per `DriftKind`, and nothing that compares anything. Split out of `drift.ts` at the
-// 500-line ceiling, along the seam that file already drew: comparison decides *whether* two
-// schemas disagree, and this decides how the disagreement reads.
-//
-// The rendered `X_DB_DRIFT` output is byte-for-byte pinned by the framework contract and
-// duplicated in `@ultimat3/entity` — do not reword a `cause` without changing both.
-//
-// Two rules run through every one of them. A `fix:` is a command the reader can RUN: `x db
-// migrate` where the migration has not been applied, and the statement itself where it has, since
-// re-running the migrator applies nothing a ledger row already claims. And a difference names the
-// declared side's own spelling, never the catalog's, because the catalog's is Postgres' rewriting.
+// Single responsibility: what a schema difference is CALLED and what its `fix:` says — one
+// constructor per `DriftKind`, and nothing that compares anything (`drift.ts` decides whether two
+// schemas disagree). A `fix:` is ONE command a shell runs, and a difference names the declared
+// side's spelling, never the catalog's — which is Postgres' rewriting.
 
-import { onDeleteRule, rebuildForeignKey } from './foreign-key';
+import { psqlCommand } from './dependent-view';
+import { addForeignKey, dropForeignKey, onDeleteRule } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
+import { addPrimaryKey, dropPrimaryKey } from './primary-key';
 import { shellInertIdentifier } from './sql';
 
 export type DriftKind =
@@ -25,9 +19,12 @@ export type DriftKind =
   | 'unknown-schema'
   | 'missing-index'
   | 'changed-index'
+  | 'changed-primary-key'
   | 'missing-check'
   | 'missing-foreign-key'
   | 'changed-foreign-key'
+  // Constructed in `drift-append-only.ts`: an `appendOnly` table whose refusing trigger is gone.
+  | 'missing-append-only-trigger'
   // Constructed in `object-drift.ts`: a trigger, function, view, type or sequence in the live
   // database that replaying the migrations does not create.
   | 'unexpected-object';
@@ -45,6 +42,66 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
+const RE_CHECK = 'then x db migrate, which re-checks';
+
+/** `set not null` is refused by the server while a row still holds NULL, and says so here. */
+const NULLS_FIRST = `refused while a row holds NULL there, so backfill those first; ${RE_CHECK}`;
+
+const CARRIES =
+  'a name in this difference carries a backtick, a dollar sign, a quote, a backslash or whitespace';
+
+const UNSPELLABLE = `${CARRIES}, so no statement here can spell it`;
+
+/**
+ * `x db migrate` is the fix where a migration has not been applied. Where it has, re-running the
+ * migrator applies nothing a ledger row already claims, so the fix is the statement itself —
+ * a repair made against THIS database, as one line a shell runs: the statement is `psql`'s
+ * argument (`psqlCommand`), never bare DDL beside a `#` — `#` is not a comment to Postgres and
+ * `alter` is not a program to a shell, so neither reader could run that line (axiom 4). Against
+ * this database and never "in a new migration": drift means this database left the migrations,
+ * and a migration would re-apply the repair to every database that is already right.
+ */
+export const repair = (path: string, statements: string, note = RE_CHECK): string =>
+  `${psqlCommand(`${path}${statements}`)}   # ${note}`;
+
+/**
+ * The same repair when no statement can be written — a name the screen refuses. Still a command
+ * that runs: a psql session, with what to do in it as the comment. No name rides in it, hostile
+ * or not; the `cause` holds them, and nobody pastes a cause.
+ */
+export const byHand = (steps: string, why = UNSPELLABLE): string =>
+  `psql "$DATABASE_URL"   # ${steps}, \\q, ${RE_CHECK} — ${why}`;
+
+/** The schema Postgres resolves an unqualified name in when a session sets nothing. */
+const DEFAULT_SCHEMA = 'public';
+
+/**
+ * What puts a statement in the schema its table was READ from: nothing for the default one — the
+ * text every app has seen — and `set search_path` in the same psql word for any other, so the
+ * table, and every table the statement references, resolves there. A `psql "$DATABASE_URL"`
+ * session starts on its own search_path: unqualified, `alter table "posts"` for a table in
+ * `tenant_a` fails, or lands on a same-named table in `public`. `null` for a schema no statement
+ * can spell.
+ */
+export const pathTo = (schema: string): string | null => {
+  if (schema === DEFAULT_SCHEMA) return '';
+  const name = shellInertIdentifier(schema);
+  return name === null ? null : `set search_path = ${name}; `;
+};
+
+/** A table as a psql PATTERN or a statement outside `pathTo`: qualified unless the default schema. */
+const qualified = (schema: string, table: string): string | null => {
+  const name = shellInertIdentifier(table);
+  if (name === null) return null;
+  if (schema === DEFAULT_SCHEMA) return name;
+  const space = shellInertIdentifier(schema);
+  return space === null ? null : `${space}.${name}`;
+};
+
+/** Every name inert in a shell AND writable as an identifier — the one screen, asked of each. */
+const spellable = (names: readonly string[]): boolean =>
+  names.every((name) => shellInertIdentifier(name) !== null);
+
 /**
  * The one `fix:` here whose second layer no quoting closes. `x db gen "add C"` puts the column
  * inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick substitute before `x` is reached at all
@@ -93,13 +150,16 @@ export function missingColumn(table: string, column: string): DriftDifference {
  *
  * `x db gen` is deliberately not the fix: it diffs types and indexes and has never emitted a
  * `set not null`, so naming it would send a reader to a command that generates an empty migration.
+ * The fix is the statement, run against this database (`repair`).
  */
 export function changedColumn(
+  schema: string,
   table: string,
   column: string,
   liveNullable: boolean,
 ): DriftDifference {
   const clause = liveNullable ? 'set not null' : 'drop not null';
+  const path = pathTo(schema);
   const relation = shellInertIdentifier(table);
   const attribute = shellInertIdentifier(column);
   return {
@@ -109,16 +169,15 @@ export function changedColumn(
     cause: liveNullable
       ? `table "${table}" allows NULL in column "${column}" that migrations declare not null`
       : `table "${table}" forbids NULL in column "${column}" that migrations declare nullable`,
-    // Both identifiers are the catalog's, so both go through the one screen. A refusal names the
-    // column as the thing it could not spell, which is what tells this line apart from
-    // `missingCheck`'s refusal in a report that carries both.
+    // Both identifiers are the catalog's, so both go through the one screen.
     fix:
-      relation === null || attribute === null
-        ? `${clause} on the column named in this difference, in a new migration, then ` +
-          'x db migrate — its table or column name carries a backtick, a dollar sign, a quote, ' +
-          'a backslash or whitespace, so no statement here can spell it'
-        : `alter table ${relation} alter column ${attribute} ${clause};   # in a new migration` +
-          (liveNullable ? ' — backfill the existing NULLs first' : ''),
+      path === null || relation === null || attribute === null
+        ? byHand(`alter column … ${clause} on the column this difference names`)
+        : repair(
+            path,
+            `alter table ${relation} alter column ${attribute} ${clause};`,
+            liveNullable ? NULLS_FIRST : RE_CHECK,
+          ),
   };
 }
 
@@ -134,22 +193,32 @@ export function changedColumn(
  * the relation is already there, and `x db migrate` then accepts a table its own SQL creates), or
  * nothing owns it and it should not be in this schema. No migration PATH is named: where an app
  * keeps its migrations is the CLI's fact, not this package's.
+ *
+ * Two repairs and one line, so the line leads with the command neither repair can skip — `\\d` on
+ * the table, through `psqlCommand`, which is what keeps a `'` in the name inside its shell word.
  */
-export function unexpectedTable(table: string): DriftDifference {
-  const name = shellInertIdentifier(table);
+export function unexpectedTable(schema: string, table: string): DriftDifference {
+  const name = qualified(schema, table);
+  // The comment repeats the name only when it holds no `'`: a shell that does not read `#` as a
+  // comment (interactive zsh, by default) would open a quote on one. The command is safe either
+  // way — `psqlCommand` escapes it inside its own word.
+  const spoken = name === null || name.includes("'") ? 'this table' : name;
   return {
     kind: 'unexpected-table',
     table,
     column: null,
     cause: `table "${table}" is not present in any migration`,
+    // The command is the harmless one — it SHOWS the table, which either repair needs first — and
+    // the two repairs are its comment.
     fix:
       name === null
-        ? 'claim it in a migration with create table if not exists, or drop it by hand — its ' +
-          'table name carries a backtick, a dollar sign, a quote, a backslash or whitespace, so ' +
-          'no statement here can spell it'
-        : `put a create table if not exists ${name} (…) statement in a migration — x db migrate ` +
-          'then accepts a table its own SQL creates — or, if nothing owns it, run ' +
-          `drop table ${name}; inside psql "$DATABASE_URL"`,
+        ? byHand(
+            `inspect the table this difference names with \\d, then claim it in a migration ` +
+              'with create table if not exists or drop it',
+          )
+        : `${psqlCommand(`\\d ${name}`)}   # nothing declares it: put create table if not exists ` +
+          `${spoken} (…) in a migration, then x db migrate — or, if nothing owns it, run ` +
+          `drop table ${spoken}; here`,
   };
 }
 
@@ -176,7 +245,7 @@ export function unknownSchema(migrations: readonly Migration[]): DriftDifference
   // id off the file and derives the name from it — so whoever can add a file to the migrations
   // directory picks what a reader pastes, and `$(…)` and a backtick substitute before `git` or `x`
   // is reached. The same screen `unexpectedColumn` and `changedColumn` already ran, on the one
-  // finding in this file that skipped it. Degraded to prose rather than escaped: a glob is not an
+  // finding in this file that skipped it. Degraded to a read-only command rather than escaped: a glob is not an
   // identifier and a migration description is not one either, so neither has a quoted form that
   // makes a hostile name safe. An EMPTY id is inert by construction and keeps its glob — that is
   // "no migrations at all", not a name this function refused to spell.
@@ -196,10 +265,10 @@ export function unknownSchema(migrations: readonly Migration[]): DriftDifference
     fix: spellable
       ? `git checkout -- "*${id}.snapshot.json"   # or, if it was never written: ` +
         `delete migration "${id}" and rerun x db gen "${name}"`
-      : 'restore the .snapshot.json committed beside the newest migration, or delete that ' +
-        'migration and rerun x db gen with its description — the migration named in this ' +
-        "difference's cause carries a backtick, a dollar sign, a quote, a backslash or " +
-        'whitespace in its file name, so no command here can spell it',
+      : 'git status --short -- "*.snapshot.json"   # shows the sidecar that is gone: git ' +
+        'checkout it, or delete that migration and rerun x db gen with its description — the ' +
+        "migration named in this difference's cause carries a backtick, a dollar sign, a " +
+        'quote, a backslash or whitespace in its file name, so no command here can spell it',
   };
 }
 
@@ -232,12 +301,17 @@ export function changedIndex(table: string, index: string, detail: string): Drif
  * 'published'::text])))` — so a text comparison reports drift on a correct database forever, and
  * normalising it is an expression parser competing with the server's. Presence is not text.
  *
- * The `fix` is the statement, not `x db migrate`: the migration that declares this constraint is
- * already in the ledger, so re-running the migrator applies nothing. Same reasoning as
- * `changedColumn` and `changedForeignKey` — the declared side holds the author's own spelling of
- * the predicate, which is what makes an executable fix possible at all.
+ * The `fix` is the statement (`repair`), not `x db migrate`: the migration that declares this
+ * constraint is already in the ledger, so re-running the migrator applies nothing. Same reasoning
+ * as `changedColumn` and `changedForeignKey` — the declared side holds the author's own spelling
+ * of the predicate, which is what makes an executable fix possible at all.
  */
-export function missingCheck(table: string, check: CheckDescription): DriftDifference {
+export function missingCheck(
+  schema: string,
+  table: string,
+  check: CheckDescription,
+): DriftDifference {
+  const path = pathTo(schema);
   const relation = shellInertIdentifier(table);
   const constraint = shellInertIdentifier(check.name);
   return {
@@ -245,23 +319,18 @@ export function missingCheck(table: string, check: CheckDescription): DriftDiffe
     table,
     column: null,
     cause: `table "${table}" is missing check constraint "${check.name}" that migrations declare`,
-    // The command rides on the same line as the statement, and not only because `check` is a
-    // banned advice word the `errors` gate demands a command beside: writing the migration is half
-    // the repair and applying it is the other half, and `changedColumn`'s bare `# in a new
-    // migration` leaves the second half to be guessed.
-    //
     // Both NAMES go through the one screen; the EXPRESSION deliberately does not, and cannot. It
     // is a predicate, so no screen could accept `status in ('draft', 'published')` and reject a
     // second statement — and it is the DECLARED side's own text, out of the author's migration,
-    // where both names are the catalog's and a sidecar's. Narrower than "this line is safe", and
-    // it is the honest claim.
+    // where both names are the catalog's and a sidecar's. What `psqlCommand` does close is the
+    // shell layer: the statement is one single-quoted word, so nothing in the predicate expands.
     fix:
-      relation === null || constraint === null
-        ? 'add the constraint named in this difference back in a new migration, then ' +
-          'x db migrate — its table or constraint name carries a backtick, a dollar sign, a ' +
-          'quote, a backslash or whitespace, so no statement here can spell it'
-        : `alter table ${relation} add constraint ${constraint} ` +
-          `check (${check.expression});   # in a new migration, then x db migrate`,
+      path === null || relation === null || constraint === null
+        ? byHand('add the check constraint this difference names back')
+        : repair(
+            path,
+            `alter table ${relation} add constraint ${constraint} check (${check.expression});`,
+          ),
   };
 }
 
@@ -282,26 +351,109 @@ export function missingForeignKey(table: string, key: ForeignKeyDescription): Dr
  * — reported apart from `missing-foreign-key` because it is a different repair: the constraint is
  * there, and what changed is what happens to the child rows.
  *
- * The `fix` is the pair, not `x db migrate`: a rule cannot be altered in place, `add constraint`
- * alone is `42710` on a name already taken, and no `x db gen` diff emits either statement, so
- * naming a command would send a reader to one that generates an empty migration. Same reasoning
- * as `changedColumn`.
+ * The `fix` is the pair (`repair`), not `x db migrate`: a rule cannot be altered in place, `add
+ * constraint` alone is `42710` on a name already taken, and no `x db gen` diff emits either
+ * statement. Same reasoning as `changedColumn`.
+ *
+ * `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s, so every name is
+ * screened and the two writers are ASKED whether they can write the pair — never a second copy of
+ * their rules beside them. `identifier()` refuses a name holding a quote, a space or a backslash
+ * and `addForeignKey` refuses an `on delete` rule Postgres does not have: right for DDL this
+ * package SENDS, wrong for a `fix:`. `diffSchema` is documented pure and total, so a pair it
+ * cannot write is a psql session and a sentence, never a throw.
+ *
+ * The CAUSE names the constraint the database holds, whatever it is called: a refused name is out
+ * of the command, and the cause is where a reader still finds which key this is.
  */
 export function changedForeignKey(
+  schema: string,
   table: string,
   declared: ForeignKeyDescription,
   held: ForeignKeyDescription,
 ): DriftDifference {
   const rule = onDeleteRule(held.onDelete);
+  const rebuilt = (): string => {
+    const steps =
+      'drop the foreign key this difference names and add it back with the on delete rule ' +
+      'migrations declare';
+    const names = [
+      table,
+      held.name,
+      declared.name,
+      declared.referencedTable,
+      ...declared.columns,
+      ...declared.referencedColumns,
+    ];
+    const path = pathTo(schema);
+    if (path === null || !spellable(names)) return byHand(steps);
+    try {
+      return repair(path, `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`);
+    } catch {
+      return byHand(steps, 'the rule migrations declare is not one Postgres has');
+    }
+  };
   return {
     kind: 'changed-foreign-key',
     table,
     column: null,
     cause:
-      `foreign key on "${table}" (${declared.columns.join(', ')}) to ` +
+      `foreign key "${held.name}" on "${table}" (${declared.columns.join(', ')}) to ` +
       `"${declared.referencedTable}" ` +
       `${rule === null ? 'declares no on delete rule' : `is on delete ${rule}`}, not what ` +
       'migrations declare',
-    fix: `${rebuildForeignKey(table, declared, held)}   # in a new migration`,
+    fix: rebuilt(),
+  };
+}
+
+const PRIMARY_KEY_BY_HAND = byHand(
+  'drop the primary key this database holds, add the one migrations declare',
+  `${CARRIES} or is too long, so no statement here can spell it`,
+);
+
+const keyText = (columns: readonly string[]): string =>
+  columns.length === 0 ? 'no primary key' : `primary key (${columns.join(', ')})`;
+
+/**
+ * The two sides key the table differently — a different column list, a different ORDER, or a key
+ * on one side only. Its own kind rather than `changed-index` on `<table>_pkey`: that finding's fix
+ * is `x db migrate`, and the migration declaring this key is already in the ledger, so re-running
+ * the migrator applies nothing.
+ *
+ * The fix is ONE command a shell runs — the pair as `psql`'s argument (`repair`).
+ *
+ * `held` is the constraint the DATABASE holds — the live primary index's name, which is the
+ * constraint's — because that is the one a `drop constraint` has to spell. The writers are asked
+ * whether they can write each statement and a refusal degrades the whole line to prose, the rule
+ * `changedForeignKey` states: every name on the live side is the catalog's.
+ */
+export function changedPrimaryKey(
+  schema: string,
+  table: string,
+  live: readonly string[],
+  held: string | undefined,
+  declared: readonly string[],
+): DriftDifference {
+  const statements = (): string => {
+    const names = [table, ...declared, ...(held === undefined ? [] : [held])];
+    const path = pathTo(schema);
+    if (path === null || !spellable(names)) return PRIMARY_KEY_BY_HAND;
+    try {
+      const parts: string[] = [];
+      if (held !== undefined) parts.push(dropPrimaryKey(table, held, false));
+      if (declared.length > 0) parts.push(addPrimaryKey(table, declared));
+      return repair(path, parts.join(' '));
+    } catch {
+      return PRIMARY_KEY_BY_HAND;
+    }
+  };
+  return {
+    kind: 'changed-primary-key',
+    table,
+    column: null,
+    cause:
+      `table "${table}" has ${keyText(live)}${held === undefined ? '' : ` as constraint "${held}"`}, ` +
+      'and migrations declare ' +
+      (declared.length === 0 ? 'none' : `(${declared.join(', ')})`),
+    fix: statements(),
   };
 }

package/src/drift.ts

@@ -4,11 +4,13 @@
 // by the framework contract; `x verify` fails on it and `--json` carries every difference.
 
 import { baseClient, type DbClient } from './client';
+import { APPEND_ONLY_DRIFT_CODE, compareAppendOnly } from './drift-append-only';
 import type { DriftDifference } from './drift-findings';
 import {
   changedColumn,
   changedForeignKey,
   changedIndex,
+  changedPrimaryKey,
   missingCheck,
   missingColumn,
   missingForeignKey,
@@ -21,8 +23,14 @@ import {
 import { DbError } from './errors';
 import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
-import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
+import {
+  findTable,
+  introspectSchema,
+  type SchemaDescription,
+  type TableDescription,
+} from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
+import { sameColumns } from './primary-key';
 
 // Re-exported explicitly, never `export *`: `src/index.ts` publishes both from `'./drift'`, so the
 // split is invisible to `@ultimat3/db`'s public surface and no consumer moves with it.
@@ -145,7 +153,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
       continue;
     }
     if (onDeleteRule(counterpart.onDelete) !== onDeleteRule(key.onDelete)) {
-      differences.push(changedForeignKey(live.name, key, counterpart));
+      differences.push(changedForeignKey(live.schema, live.name, key, counterpart));
     }
   }
   return differences;
@@ -160,7 +168,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
  * before constraints were recorded: it declares nothing, so nothing can be missing. `live.checkNames`
  * absent is a description that never asked the catalog — a stub, a fake client's rows, a
  * `TableDescription` built by hand — and reading that as "the database holds none" is one finding
- * per declared constraint against a database nobody looked at. `introspect()` always answers with
+ * per declared constraint against a database nobody looked at. `introspectSchema()` always answers with
  * the field, `[]` included, so a real read is never mistaken for an unread one.
  *
  * Only the declared side is judged, the rule `compareIndexes` and `compareForeignKeys` both state:
@@ -175,26 +183,29 @@ function compareChecks(live: TableDescription, expected: TableDescription): Drif
   const present = new Set(held);
   return declared
     .filter((check) => !present.has(check.name))
-    .map((check) => missingCheck(live.name, check));
+    .map((check) => missingCheck(live.schema, live.name, check));
 }
 
 /**
- * A primary key column is `NOT NULL` in the catalog whether or not anything declared it — Postgres
- * adds the constraint with the key. Both sides are therefore read through the union of the two
- * primary keys, or a table whose snapshot spells its key column nullable reports a difference
- * against a database that is exactly right and cannot be anything else. The union, not one side:
- * a key present on only one of them is a difference the *key* comparison owns, and reporting it
- * again as a nullability change would be one fault with two findings.
+ * 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
+ * re-keyed by hand, or one whose key no migration ever produced, read `ok: true`.
  */
-function keyColumnsOf(live: TableDescription, expected: TableDescription): ReadonlySet<string> {
-  return new Set([...live.primaryKey, ...expected.primaryKey]);
+function comparePrimaryKey(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  if (sameColumns(live.primaryKey, expected.primaryKey)) return [];
+  const held = live.indexes.find((index) => index.primary)?.name;
+  return [changedPrimaryKey(live.schema, live.name, live.primaryKey, held, expected.primaryKey)];
 }
 
 function compareTable(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
   const expectedColumns = new Map(expected.columns.map((column) => [column.name, column]));
   const liveColumns = new Map(live.columns.map((column) => [column.name, column]));
-  const keyColumns = keyColumnsOf(live, expected);
+  // A primary key column is `NOT NULL` in the catalog whether or not anything declared it —
+  // Postgres adds the constraint with the key — so a snapshot spelling its key column nullable is
+  // not drift. The DECLARED key only: a column the database alone keys stays NOT NULL after the
+  // stray constraint is dropped, which is a second fault and reported as one.
+  const keyColumns = new Set(expected.primaryKey);
   for (const column of live.columns) {
     if (expectedColumns.has(column.name)) continue;
     differences.push(unexpectedColumn(live.name, column.name));
@@ -210,12 +221,14 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
     // `retypeColumn` already owns that question where both sides are generated.
     if (keyColumns.has(column.name)) continue;
     if (column.nullable !== counterpart.nullable) {
-      differences.push(changedColumn(live.name, column.name, counterpart.nullable));
+      differences.push(changedColumn(live.schema, live.name, column.name, counterpart.nullable));
     }
   }
+  differences.push(...comparePrimaryKey(live, expected));
   differences.push(...compareIndexes(live, expected));
   differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
+  differences.push(...compareAppendOnly(live, expected));
   return differences;
 }
 
@@ -224,7 +237,7 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
   const differences: DriftDifference[] = [];
   for (const table of live.tables) {
     const counterpart = findTable(expected, table.name);
-    if (counterpart === undefined) differences.push(unexpectedTable(table.name));
+    if (counterpart === undefined) differences.push(unexpectedTable(table.schema, table.name));
     else differences.push(...compareTable(table, counterpart));
   }
   for (const table of expected.tables) {
@@ -240,7 +253,8 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
 
 export function driftError(difference: DriftDifference): DbError {
   return new DbError({
-    code: 'X_DB_DRIFT',
+    // 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',
     cause: difference.cause,
     fix: difference.fix,
     meta: { kind: difference.kind, table: difference.table, column: difference.column },
@@ -254,7 +268,7 @@ export function driftError(difference: DriftDifference): DbError {
  * (`driftFindings`), and `x verify`'s `drift` step is the *source* detector (`checkSourceDrift`),
  * which never reaches this function. There is no `x db drift` command.
  */
-export function assertNoDrift(report: DriftReport): void {
+export function assertNoSchemaDrift(report: DriftReport): void {
   const first = report.differences[0];
   if (first !== undefined) throw driftError(first);
 }
@@ -305,7 +319,7 @@ export function expectedSchema(
  * schema that is in fact correct. The `x_` prefix is the convention every framework table already
  * follows, so a table a future package adds needs no second list here.
  *
- * `introspect()` keeps its own narrower default (`x_migrations` alone) on purpose: the admin
+ * `introspectSchema()` keeps its own narrower default (`x_migrations` alone) on purpose: the admin
  * dashboard's schema view and the MCP `schema.describe` tool legitimately show `x_users`. Only
  * drift wants the whole namespace gone, so only drift declares it.
  */
@@ -342,7 +356,7 @@ export async function checkDrift(options: DriftOptions): Promise<DriftReport> {
   // and a wrong `ok: true` is the failure this check exists to prevent.
   if (expected === undefined)
     return { ok: false, differences: [unknownSchema(options.migrations)] };
-  const live = await introspect({
+  const live = await introspectSchema({
     client,
     ...(options.schema === undefined ? {} : { schema: options.schema }),
   });

package/src/entity-shape.ts

@@ -112,4 +112,9 @@ export interface EntityDescriptionLike {
    * none", which is what every hand-built description in this package's own tests is.
    */
   readonly invariants?: readonly InvariantDescriptionLike[] | undefined;
+  /**
+   * `entity({ appendOnly: true })`: the table refuses UPDATE and DELETE (`generate-append-only.ts`).
+   * Optional for the reason `invariants` is, and absent reads as "rows may change".
+   */
+  readonly appendOnly?: boolean | undefined;
 }

package/src/errors.ts

@@ -38,6 +38,11 @@ export const DB_OWNED_ERROR_CODES = [
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
   'X_SCHEMA_DUMP_DRIFT',
+  'X_DB_TRANSACTION_ABORTED',
+  'X_DB_COMMIT_UNKNOWN',
+  'X_DB_SIBLING_SCOPE_TIMEOUT',
+  'X_APPEND_ONLY_TRIGGER_MISSING',
+  'X_MIGRATION_APPEND_ONLY_BACKFILL',
 ] as const;
 
 /**
@@ -83,6 +88,12 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
   X_SCHEMA_DUMP_DRIFT: 'the committed schema dump is not what the migrations produce',
+  X_DB_TRANSACTION_ABORTED: 'the server rolled the transaction back',
+  X_DB_COMMIT_UNKNOWN: 'the connection was lost while COMMIT was in flight',
+  X_DB_SIBLING_SCOPE_TIMEOUT: 'a nested transaction scope waited too long for its sibling',
+  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',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -279,7 +290,7 @@ export const drainTimeout = (ms: number, role: string): DbError =>
   new DbError({
     code: 'X_DB_DRAIN_TIMEOUT',
     cause: `the ${role} pool still held connections after ${String(ms)}ms, so close() stopped waiting`,
-    fix: `find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in createPostgresClient({ profile }) for the ${role} role`,
+    fix: `find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in postgresClient({ profile }) for the ${role} role`,
     meta: { drainTimeoutMs: ms, role },
   });
 
@@ -416,10 +427,3 @@ export const isolationLevelInvalid = (received: unknown): DbError =>
     cause: `an isolation level must be one of 'read committed', 'repeatable read' or 'serializable'; got ${describeValue(received)}`,
     fix: "withTransaction(fn, { isolation: 'serializable' })   # or 'repeatable read', or 'read committed'",
   });
-
-export const dbNotImplemented = (feature: string, fix: string): DbError =>
-  new DbError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is not implemented by this driver`,
-    fix,
-  });

package/src/fake.ts

@@ -49,7 +49,7 @@ const DEFAULT_STUBS: readonly Stub[] = [
   { match: /pg_try_advisory_lock/, response: { rows: [{ locked: true }] } },
 ];
 
-export function createRecordingClient(): RecordingClient {
+export function recordingClient(): RecordingClient {
   const statements: RecordedStatement[] = [];
   const stubs: Stub[] = [...DEFAULT_STUBS];
 

package/src/foreign-key.ts

@@ -130,37 +130,3 @@ export function unrestorableNote(table: string, constraint: string, gone: string
     `cannot be restored; ${identifier(gone).text} is gone`
   );
 }
-
-/**
- * The drop/add pair that moves a key's `on delete` rule — a rebuild, because Postgres has no
- * `alter constraint` for it — for a `fix:` line an author pastes into a new migration.
- *
- * It lives here, beside the two writers, because it is the one caller reading values neither of
- * them may assume: `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s. Both
- * writers refuse rather than guess — `identifier()` on a name holding a quote, a space or a
- * backslash (all three legal inside a quoted Postgres name), and `addForeignKey` on an `on delete`
- * rule Postgres does not have. That is exactly right for DDL this package SENDS and wrong for a
- * `fix:` line: `diffSchema` is documented pure and total, so a pair it cannot write is a sentence,
- * never a throw — a drift check that raises in place of its report hands the caller an exception
- * where a verdict was asked for. The constraint is still named, because it is the only thing
- * identifying which one, quoted by `JSON.stringify`, which escapes rather than refuses; nothing
- * runs this string either way.
- */
-export function rebuildForeignKey(
-  table: string,
-  declared: ForeignKeyDescription,
-  held: ForeignKeyDescription,
-): string {
-  // The writers are ASKED whether they can write the pair — never a second copy of their rules
-  // beside them, which is the copy that drifts. A refusal is the answer, and nothing here reads
-  // the thrown value.
-  try {
-    return `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`;
-  } catch {
-    return (
-      `drop constraint ${JSON.stringify(held.name)} on table ${JSON.stringify(table)} and add ` +
-      'it back with the on delete rule the migrations declare — by hand: x db gen cannot ' +
-      'write this pair'
-    );
-  }
-}