@ultimat3/db 1.1.0 → 2.0.0

package/src/drift.ts

@@ -5,14 +5,26 @@
 
 import { baseClient, type DbClient } from './client';
 import { DbError } from './errors';
-import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
+import { foreignKeyTarget } from './foreign-key';
+import {
+  type ForeignKeyDescription,
+  findTable,
+  introspect,
+  type SchemaDescription,
+  type TableDescription,
+} from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
 
 export type DriftKind =
   | 'unexpected-column'
   | 'missing-column'
+  | 'changed-column'
   | 'unexpected-table'
-  | 'missing-table';
+  | 'missing-table'
+  | 'unknown-schema'
+  | 'missing-index'
+  | 'changed-index'
+  | 'missing-foreign-key';
 
 export interface DriftDifference {
   readonly kind: DriftKind;
@@ -48,6 +60,35 @@ function missingColumn(table: string, column: string): DriftDifference {
   };
 }
 
+/**
+ * The column exists on both sides and one of them lets it be `NULL`.
+ *
+ * This is the finding the expand/contract flow needs and never had. `generate.ts` emits a `NOT
+ * NULL` add as nullable plus a `-- backfill "c", then: … set not null;` comment, because the
+ * strict version cannot succeed on a populated table — and phase 2 is a comment, so it is a thing
+ * a human has to remember. Nobody did, and `compareTable` compared columns by name and by type
+ * while `snapshotOf` had recorded `nullable` all along, so the column stayed nullable forever
+ * against an entity schema that said otherwise, with `ok: true` on every check. The first
+ * `undefined` write then lands as `NULL` and crashes three services away from the migration.
+ *
+ * `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.
+ */
+function changedColumn(table: string, column: string, liveNullable: boolean): DriftDifference {
+  const clause = liveNullable ? 'set not null' : 'drop not null';
+  return {
+    kind: 'changed-column',
+    table,
+    column,
+    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`,
+    fix:
+      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
+      (liveNullable ? ' — backfill the existing NULLs first' : ''),
+  };
+}
+
 function unexpectedTable(table: string): DriftDifference {
   return {
     kind: 'unexpected-table',
@@ -68,17 +109,160 @@ function missingTable(table: string): DriftDifference {
   };
 }
 
+/**
+ * Not a difference between two schemas but the absence of one to compare against — reported
+ * through the same channel so it reaches an operator, since a check that quietly answered "clean"
+ * because it had nothing to check is the one failure mode drift detection cannot have.
+ */
+function unknownSchema(migrations: readonly Migration[]): DriftDifference {
+  const newest = [...migrations].sort((a, b) => (a.id < b.id ? -1 : 1)).at(-1);
+  return {
+    kind: 'unknown-schema',
+    table: '',
+    column: null,
+    cause:
+      `migration "${newest?.id ?? ''}" records no schema snapshot, so what this database owes ` +
+      'cannot be established',
+    // The same two remedies `X_MIGRATION_SNAPSHOT_MISSING` names, in the same order, because it is
+    // the same condition. It used to lead with `x db gen`, which raises that error and whose own
+    // fix pointed back here — a cycle a scaffolded app hit on its first `x db migrate`. The
+    // pathspec is a glob because this package is tier 1: only `@ultimat3/cli` knows the directory.
+    fix:
+      `git checkout -- "*${newest?.id ?? ''}.snapshot.json"   # or, if it was never written: ` +
+      `delete migration "${newest?.id ?? ''}" and rerun x db gen "${newest?.name ?? 'initial'}"`,
+  };
+}
+
+function missingIndex(table: string, index: string): DriftDifference {
+  return {
+    kind: 'missing-index',
+    table,
+    column: null,
+    cause: `table "${table}" is missing index "${index}" that migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+function changedIndex(table: string, index: string, detail: string): DriftDifference {
+  return {
+    kind: 'changed-index',
+    table,
+    column: null,
+    cause: `index "${index}" on "${table}" ${detail}, not what migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDifference {
+  return {
+    kind: 'missing-foreign-key',
+    table,
+    column: null,
+    cause:
+      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
+      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+/**
+ * Indexes migrations declare, against the ones the catalog holds — by column list and by
+ * uniqueness, which is what caught a composite index rebuilt with its columns the other way round
+ * while `ok: true` said the schema agreed.
+ *
+ * Only the declared side is judged. A live index no snapshot names is **not** drift: Postgres
+ * creates one for every primary key and every unique constraint, no migration declares those, and
+ * an index a DBA added is a planner decision rather than a schema divergence — reporting them
+ * would be eight findings against a correct database, which is how a drift check earns being
+ * ignored (`appTables` exists for the same reason).
+ *
+ * The predicate and the direction are deliberately **not** compared: the catalog returns its own
+ * rewriting of an expression (`(deleted_at IS NULL)`) and a snapshot holds the author's spelling,
+ * so a text comparison reports drift on two identical indexes. `x db gen` compares them instead,
+ * where both sides are generated — see `redefineIndex` in `generate.ts`. Named in
+ * `wiki/Known-Gaps.md`.
+ */
+function compareIndexes(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  const differences: DriftDifference[] = [];
+  const present = new Map(live.indexes.map((index) => [index.name, index]));
+  for (const index of expected.indexes) {
+    const counterpart = present.get(index.name);
+    if (counterpart === undefined) {
+      differences.push(missingIndex(live.name, index.name));
+      continue;
+    }
+    if (counterpart.columns.join(',') !== index.columns.join(',')) {
+      differences.push(
+        changedIndex(live.name, index.name, `covers (${counterpart.columns.join(', ')})`),
+      );
+      continue;
+    }
+    if (counterpart.unique !== index.unique) {
+      differences.push(
+        changedIndex(live.name, index.name, counterpart.unique ? 'is unique' : 'is not unique'),
+      );
+    }
+  }
+  return differences;
+}
+
+/**
+ * Foreign keys migrations declare, against the ones the catalog holds — matched on **where the key
+ * points**, never on its name. `snapshotOf` names one the way Postgres names an inline `references`
+ * clause (`posts_org_id_fkey`), a hand-written migration may have said `constraint fk_posts_org`,
+ * and a constraint that points the same columns at the same table is the same constraint whatever
+ * it is called; comparing the name would report drift on a database that is exactly right.
+ *
+ * `onDelete` is not compared either: the catalog spells it as a single character (`a`, `c`, `r`)
+ * and no generated clause declares one, so a snapshot has nothing truthful to hold there. Only the
+ * declared side is judged, for the reason `compareIndexes` gives. Named in `wiki/Known-Gaps.md`.
+ */
+function compareForeignKeys(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  // The same identity `x db gen` diffs on (`foreign-key.ts`): a generator and a detector that
+  // disagreed about whether two keys are the same key is drift on a correct database.
+  const present = new Set(live.foreignKeys.map(foreignKeyTarget));
+  return expected.foreignKeys
+    .filter((key) => !present.has(foreignKeyTarget(key)))
+    .map((key) => missingForeignKey(live.name, key));
+}
+
+/**
+ * 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.
+ */
+function keyColumnsOf(live: TableDescription, expected: TableDescription): ReadonlySet<string> {
+  return new Set([...live.primaryKey, ...expected.primaryKey]);
+}
+
 function compareTable(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
-  const expectedColumns = new Set(expected.columns.map((column) => column.name));
-  const liveColumns = new Set(live.columns.map((column) => column.name));
+  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);
   for (const column of live.columns) {
     if (expectedColumns.has(column.name)) continue;
     differences.push(unexpectedColumn(live.name, column.name));
   }
   for (const column of expected.columns) {
-    if (!liveColumns.has(column.name)) differences.push(missingColumn(live.name, column.name));
+    const counterpart = liveColumns.get(column.name);
+    if (counterpart === undefined) {
+      differences.push(missingColumn(live.name, column.name));
+      continue;
+    }
+    // Nullability, not the type: the catalog and a snapshot spell types differently often enough
+    // that comparing them here would report drift on a correct database, and `x db gen`'s
+    // `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(...compareIndexes(live, expected));
+  differences.push(...compareForeignKeys(live, expected));
   return differences;
 }
 
@@ -117,18 +301,60 @@ export function assertNoDrift(report: DriftReport): void {
 }
 
 /**
- * The schema migrations claim. Each generated migration carries the snapshot it leaves behind,
- * so the newest applied one with a snapshot is the expectation — no SQL is re-parsed.
+ * The schema the migration files themselves declare, ledger or no ledger, or `undefined` when
+ * they do not declare one. Each generated migration carries the snapshot it leaves behind, so the
+ * **newest** migration's snapshot is the claim — no SQL is re-parsed.
+ *
+ * The newest one, never the newest one that happens to have a snapshot: a later migration without
+ * a sidecar has changed the schema in ways nothing wrote down, so an earlier snapshot is not a
+ * partial answer but a wrong one. `0001` records `posts`, `0002` adds a column by hand, and
+ * reaching back to `0001` reports the column the database correctly holds as `unexpected-column`
+ * — drift against a schema that is exactly right, with `x db gen "add …"` as the fix for a
+ * migration that already exists.
+ *
+ * An empty list has nothing to declare and is `{ tables: [] }`, which is a real answer: an app
+ * with no migration yet owes the database no table.
+ *
+ * This is what `x db gen` diffs the app's entities against, and why generating a migration needs
+ * no database: the previous migration already wrote down what it left behind.
+ */
+export function declaredSchema(migrations: readonly Migration[]): SchemaDescription | undefined {
+  const ordered = [...migrations].sort((a, b) => (a.id < b.id ? -1 : 1));
+  const newest = ordered[ordered.length - 1];
+  if (newest === undefined) return { tables: [] };
+  return newest.snapshot;
+}
+
+/**
+ * The schema migrations claim to have *applied* — `declaredSchema` over the ledger's own subset,
+ * never a second reading of the same snapshots. Generation asks "what have we written down" and
+ * drift asks "what does this database owe us"; two answers, one implementation, so a snapshot can
+ * never mean one thing to `x db gen` and another to `x verify`.
  */
 export function expectedSchema(
   migrations: readonly Migration[],
   ledger: readonly LedgerRow[],
-): SchemaDescription {
+): SchemaDescription | undefined {
   const applied = new Set(ledger.map((row) => row.id));
-  const snapshots = [...migrations]
-    .filter((migration) => applied.has(migration.id) && migration.snapshot !== undefined)
-    .sort((a, b) => (a.id < b.id ? -1 : 1));
-  return snapshots[snapshots.length - 1]?.snapshot ?? { tables: [] };
+  return declaredSchema(migrations.filter((migration) => applied.has(migration.id)));
+}
+
+/**
+ * Framework bookkeeping is not app schema. The ledger, the job queue's tables, the outbox and
+ * every `@ultimat3/auth` table are created by `create table if not exists` at boot — no migration
+ * declares them and no snapshot carries them, so each one reads as `unexpected-table` against a
+ * 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
+ * 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.
+ */
+export const FRAMEWORK_TABLE_PREFIX = 'x_';
+
+/** The live schema minus framework bookkeeping — what a migration snapshot can be compared to. */
+export function appTables(live: SchemaDescription): SchemaDescription {
+  return { tables: live.tables.filter((t) => !t.name.startsWith(FRAMEWORK_TABLE_PREFIX)) };
 }
 
 export interface DriftOptions {
@@ -137,12 +363,29 @@ export interface DriftOptions {
   readonly schema?: string | undefined;
 }
 
+/**
+ * **The post-migrate verification**: the live database against the ledger it just wrote. This is
+ * the one drift question that needs a database, so it is asked where one is open — `runMigrations`
+ * in `@ultimat3/cli`, which is `x db migrate`, `x db reset` and `ROLE=migrate` alike.
+ *
+ * The other drift question — "the entity source was edited and no migration recorded it" — needs
+ * no database and is `x verify`'s `drift` step (`checkSourceDrift`, `@ultimat3/cli`). Two
+ * conditions, two detectors, one `X_DB_DRIFT`; a check that opened a database in CI could not run
+ * at all, and one that read files could not see a column added by hand.
+ */
 export async function checkDrift(options: DriftOptions): Promise<DriftReport> {
   const client = options.client ?? baseClient();
   const ledger = await readLedger(client);
+  const expected = expectedSchema(options.migrations, ledger);
+  // Unknowable, not clean: the newest applied migration wrote no snapshot, so there is nothing to
+  // compare the catalog to. Reported as its own difference rather than answered with a stale
+  // snapshot's verdict, because a wrong `ok: false` sends an author to fix a schema that is right
+  // 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({
     client,
     ...(options.schema === undefined ? {} : { schema: options.schema }),
   });
-  return diffSchema(live, expectedSchema(options.migrations, ledger));
+  return diffSchema(appTables(live), expected);
 }

package/src/errors.ts

@@ -2,7 +2,9 @@
 // fixes the situation — `X_DB_DRIFT` is the flagship and its rendering is byte-for-byte
 // pinned by the framework contract, so change its strings only with the contract.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, renderThrowable, stringField, UltimateError } from '@ultimat3/core';
+import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
+import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
 
 /**
  * Codes this package declares and owns. `X_DB_DRIFT` is db's: it is a statement about migrations
@@ -10,16 +12,28 @@ import { registerErrorCodes, UltimateError } from '@ultimat3/core';
  */
 export const DB_OWNED_ERROR_CODES = [
   'X_DB_UNAVAILABLE',
+  'X_DB_UNIQUE_VIOLATION',
+  'X_DB_FOREIGN_KEY_VIOLATION',
+  'X_DB_SERIALIZATION_FAILURE',
+  'X_DB_STATEMENT_TIMEOUT',
+  'X_DB_LOCK_TIMEOUT',
+  'X_DB_POOL_EXHAUSTED',
   'X_DB_DRIFT',
   'X_MIGRATION_CONFLICT',
   'X_MIGRATION_IRREVERSIBLE',
+  'X_MIGRATION_DESTRUCTIVE',
+  'X_MIGRATION_SNAPSHOT_MISSING',
+  'X_MIGRATE_CONCURRENT',
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
-  'X_READONLY_VIOLATION',
 ] as const;
 
-/** `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. Never titled here, never registered here. */
-export const DB_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+/**
+ * `@ultimat3/core`'s. Never titled here, never registered here. `X_ENV_MISSING` is core's word for
+ * "a variable this process was given is missing or invalid", and `DATABASE_POOL_MAX` is one — a
+ * db-local code for it would be a second answer to a question core already answers.
+ */
+export const DB_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED', 'X_ENV_MISSING'] as const;
 
 /** Every code db can throw: the ones it owns plus the ones it borrows. */
 export const DB_ERROR_CODES = [...DB_OWNED_ERROR_CODES, ...DB_BORROWED_ERROR_CODES] as const;
@@ -29,12 +43,20 @@ export type DbErrorCode = (typeof DB_ERROR_CODES)[number];
 
 export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_DB_UNAVAILABLE: 'cannot reach the database',
+  X_DB_UNIQUE_VIOLATION: 'a unique constraint rejected the row',
+  X_DB_FOREIGN_KEY_VIOLATION: 'a foreign key constraint rejected the row',
+  X_DB_SERIALIZATION_FAILURE: 'the transaction lost a serialization race',
+  X_DB_STATEMENT_TIMEOUT: 'the statement ran past its statement_timeout',
+  X_DB_LOCK_TIMEOUT: 'the statement waited past its lock_timeout',
+  X_DB_POOL_EXHAUSTED: 'no connection was available',
   X_DB_DRIFT: 'schema differs from migrations',
   X_MIGRATION_CONFLICT: 'the migration ledger disagrees with this build',
+  X_MIGRATE_CONCURRENT: 'another migrator holds the migration lock',
   X_MIGRATION_IRREVERSIBLE: 'this migration cannot be reversed without data loss',
+  X_MIGRATION_DESTRUCTIVE: 'this migration destroys data and does not say so',
+  X_MIGRATION_SNAPSHOT_MISSING: 'the newest migration records no schema snapshot',
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
-  X_READONLY_VIOLATION: 'a mutating statement reached a read-only client',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -81,6 +103,137 @@ export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
     sourceError,
   });
 
+/**
+ * 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
+ * failure this table exists to end.
+ *
+ * `X_DB_UNIQUE_VIOLATION`'s and `X_DB_FOREIGN_KEY_VIOLATION`'s take the constraint the server
+ * named, so the fix points at the one index or key that refused the row rather than at the idea
+ * of one; `driverError` substitutes the placeholder when the driver reported none.
+ */
+const SQLSTATE_FIXES: Readonly<Record<DbSqlStateCode, string>> = Object.freeze({
+  X_DB_UNIQUE_VIOLATION:
+    'upsertAll(rows, { onConflict: [...] }) over the columns {constraint} covers — ' +
+    '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',
+  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_POOL_EXHAUSTED:
+    'set DATABASE_POOL_MAX below max_connections / replicas (per-role default: POOL_PROFILES), ' +
+    'or cut the replica count',
+});
+
+/** Substituted into a fix when the driver named no constraint — `{constraint}`'s stand-in. */
+const UNNAMED_CONSTRAINT = 'the constraint named in cause';
+
+/**
+ * Every driver failure, typed by what the server actually said. The SQLSTATE has always been on
+ * the error — `isLedgerMissing` proved the read worked — and nothing exposed it, so a `23505`
+ * unique violation, a `40001` serialization failure and a `57014` timeout all reached the caller
+ * as `X_DB_UNAVAILABLE`, whose fix is "set DATABASE_URL to a reachable Postgres url". Two clicks
+ * racing a signup paged on-call for an outage that never happened.
+ *
+ * `X_DB_UNAVAILABLE` stays the answer for everything the table does not classify, including every
+ * failure that never reached a server: that code's meaning is unchanged, its fix is finally only
+ * given where it is true, and a new SQLSTATE arrives as a new row here rather than as a new
+ * `catch` at a call site.
+ */
+export const driverError = (detail: string, sourceError: unknown): DbError => {
+  const code = sqlStateCode(sourceError);
+  if (code === undefined) return dbUnavailable(detail, sourceError);
+  const state = sqlState(sourceError);
+  const constraint = stringField(sourceError, 'constraint');
+  return new DbError({
+    code,
+    cause: `${detail}: ${renderThrowable(sourceError)} [SQLSTATE ${state ?? '?????'}]`,
+    // A FUNCTION as the replacement, never the string: `String.replace` expands `$&`, `` $` ``,
+    // `$'` and `$$` inside a replacement literal, and a constraint name is the server's, not
+    // 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: SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
+    meta: {
+      sqlState: state,
+      ...(constraint === undefined ? {} : { constraint }),
+    },
+    sourceError,
+  });
+};
+
+/**
+ * The pool answered nothing inside `acquireTimeoutMs`. Distinct from the server's own `53300` and
+ * deliberately the same code: to a caller both mean "there was no connection for this unit of
+ * work", and a second code would split one runbook in two. Queueing forever instead turns
+ * exhaustion into a hang — `/readyz` joins the queue, the kubelet kills the pod, and the next pod
+ * inherits the same saturated database.
+ */
+export const poolAcquireTimeout = (waitedMs: number, max: number): DbError =>
+  new DbError({
+    code: 'X_DB_POOL_EXHAUSTED',
+    cause: `no connection came free within ${waitedMs}ms; every one of the pool's ${max} is in use`,
+    fix: SQLSTATE_FIXES.X_DB_POOL_EXHAUSTED,
+    meta: { waitedMs, max },
+  });
+
+/**
+ * `DATABASE_POOL_MAX` is the one pool knob an operator can reach without a rebuild, so a typo in it
+ * must refuse at boot rather than silently fall back to the role default — a fleet that ignored the
+ * value it was given is the failure the variable exists to prevent.
+ */
+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`,
+    fix: 'DATABASE_POOL_MAX=20   # a whole number of connections per process, or unset it',
+    meta: { received },
+  });
+
+/**
+ * `withTransaction(fn, { retry: n })` re-ran `fn` from the top `n` times and lost the race every
+ * time. The last driver error is kept as `sourceError` so the SQLSTATE survives, and the cause
+ * names the count because "it failed again" and "it failed 4 times in a row" are different
+ * problems: the second one is contention the application has to reduce, not a retry to add.
+ */
+export const serializationExhausted = (attempts: number, sourceError: unknown): DbError =>
+  new DbError({
+    code: 'X_DB_SERIALIZATION_FAILURE',
+    cause:
+      `the transaction lost its serialization race on all ${attempts} attempts: ` +
+      renderThrowable(sourceError),
+    fix:
+      'raise the retry budget — withTransaction(fn, { retry: 8 }) — or cut the contention: ' +
+      "narrow what the transaction reads, or drop to isolation: 'repeatable read'",
+    meta: { attempts },
+    sourceError,
+  });
+
+/**
+ * The migration advisory lock was still held when the wait ran out. `pg_advisory_lock` blocks with
+ * no timeout, so a migrator wedged on a partition — or OOM-killed with its backend still alive —
+ * left `helm upgrade --wait` sitting inside one statement, printing nothing, with the job never
+ * failing so `backoffLimit` never fired. A bounded `pg_try_advisory_lock` poll turns that into an
+ * exit code.
+ */
+export const migrateConcurrent = (lockKey: number, waitedMs: number): DbError =>
+  new DbError({
+    code: 'X_MIGRATE_CONCURRENT',
+    cause:
+      `another session still holds pg_advisory_lock(${lockKey}) after waiting ${waitedMs}ms, ` +
+      'so this migrator refused rather than block a deploy forever',
+    fix:
+      'psql "$DATABASE_URL" -c "select pid, application_name, state from pg_stat_activity ' +
+      "join pg_locks using (pid) where locktype = 'advisory'\"" +
+      '   # pg_terminate_backend(pid) the wedged migrator, then: x db migrate',
+    meta: { lockKey, waitedMs },
+  });
+
 /** The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync. */
 export const dbDrift = (tableName: string, columnName: string): DbError =>
   new DbError({
@@ -96,6 +249,64 @@ export const migrationConflict = (cause: string, fix: string): DbError =>
 export const migrationIrreversible = (cause: string, fix: string): DbError =>
   new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
 
+/**
+ * `packages/db/migrations/0000_initial.snapshot.json` → `packages/db/migrations/0000_initial.*` —
+ * every file that one migration owns, as one `rm` argument. Derived from the path the caller passed
+ * rather than rebuilt from a directory this package does not know: `db` is tier 1 and where an app
+ * keeps its migrations is `@ultimat3/cli`'s answer, not this one's.
+ */
+const snapshotSiblings = (file: string): string => file.replace(/\.snapshot\.json$/, '.*');
+
+/**
+ * `20260817120000_add_posts` → `add_posts`, the argument `x db gen` takes. The name is free text
+ * and only ever labels a *new* id, so an id carrying no stamp answers with itself rather than with
+ * the empty string — a `fix:` ending in `x db gen ""` is a command that cannot be run.
+ */
+const migrationNameOf = (id: string): string => id.replace(/^\d+_/, '') || id;
+
+/**
+ * The sidecar every generated migration writes is what the *next* generation diffs against, so a
+ * newest migration without one leaves nothing to diff. Refused rather than defaulted to the empty
+ * schema, which would generate `create table` for every table the database already holds.
+ */
+export const migrationSnapshotMissing = (id: string, file: string): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_SNAPSHOT_MISSING',
+    cause: `migration "${id}" records no schema snapshot (${file}), so there is nothing to diff against`,
+    // Two remedies, both commands, in the order they are safe to try. "restore from version
+    // control" alone was neither: on a scaffolded app the sidecar was never written, so there is
+    // nothing to restore — and the drift this refusal answers named `x db gen` as *its* fix, so
+    // the two errors pointed at each other and an app's first migration had no way out.
+    // `x db gen` is named only *after* the files it would trip over are gone.
+    fix:
+      `git checkout -- ${file}   # or, if it was never written: ` +
+      `rm ${snapshotSiblings(file)} && x db gen "${migrationNameOf(id)}"`,
+    meta: { id, file },
+  });
+
+/**
+ * One error per file, never one per statement: the marker declares the whole migration, so a
+ * second finding would repeat an instruction the first already gave. `file` is app-relative and
+ * arrives from the caller — `db` is tier 1 and does not know where an app keeps its migrations.
+ *
+ * Irreversible and destructive are two questions. `X_MIGRATION_IRREVERSIBLE` refuses to *generate*
+ * a plan whose `down` cannot restore the rows; this one refuses to *ship* a plan whose `up`
+ * destroys them without saying so — a retype is reversible in DDL and still rewrites every row.
+ */
+export const migrationDestructive = (
+  file: string,
+  first: DestructiveStatement,
+  more = 0,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_DESTRUCTIVE',
+    cause:
+      `${file} ${DESTRUCTIVE_CAUSE[first.kind]} and does not declare it` +
+      `${more === 0 ? '' : ` (and ${more} more destructive)`}: ${first.statement}`,
+    fix: `add the line "${DESTRUCTIVE_MARKER}" to ${file}, or regenerate it: x db gen "<name>" --allow-destructive`,
+    meta: { file, kind: first.kind, statements: more + 1 },
+  });
+
 export const sqlUnsafe = (received: string, position: number): DbError =>
   new DbError({
     code: 'X_SQL_UNSAFE',
@@ -114,6 +325,22 @@ export const identifierUnsafe = (name: string): DbError =>
     meta: { name },
   });
 
+/**
+ * More than one command in a text that gets **spliced** — into `DECLARE … CURSOR FOR`, or sent
+ * whole on a driver that degrades to the simple protocol. `X_SQL_UNSAFE` rather than a validation
+ * code for the same reason `branchNameInvalid` uses it: a second command riding an interpolated
+ * statement is an injection, not a typo. Only the first is bounded by the guards `readOnlyQuery`
+ * just installed, so `SET LOCAL statement_timeout` was undone by the second while `guards` still
+ * reported `timeout:5000ms` — a defeated layer reported as an engaged one.
+ */
+export const multipleStatements = (statement: string, count: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `a read-only query must be ONE statement; this text holds ${count}: ${statement}`,
+    fix: 'await readOnlyQuery(first); await readOnlyQuery(second)   # one statement per call',
+    meta: { count },
+  });
+
 export const branchExists = (branch: string): DbError =>
   new DbError({
     code: 'X_BRANCH_EXISTS',
@@ -134,14 +361,6 @@ export const branchNameInvalid = (branch: string): DbError =>
     meta: { branch },
   });
 
-export const readonlyViolation = (statement: string, keyword: string): DbError =>
-  new DbError({
-    code: 'X_READONLY_VIOLATION',
-    cause: `a read-only client received a ${keyword.toUpperCase()} statement: ${statement}`,
-    fix: 'use db() instead of readOnly(db()), or rewrite the statement as a SELECT',
-    meta: { keyword },
-  });
-
 export const dbNotImplemented = (feature: string, fix: string): DbError =>
   new DbError({
     code: 'X_NOT_IMPLEMENTED',