@ultimat3/db 15.0.0 → 17.0.0

package/src/generated-column.ts

@@ -6,7 +6,9 @@
 import { assert } from '@ultimat3/core';
 import type { ColumnDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
-import type { ColumnDescription } from './introspect';
+import type { ColumnDescription, TableDescription } from './introspect';
+import type { MovedAside } from './retype-dependents';
+import { moveDependentsAside } from './retype-dependents';
 import { identifier } from './sql';
 
 /** How a column that moved was brought back into line — what the caller has to do next, if anything. */
@@ -68,14 +70,26 @@ export const isGenerated = (column: ColumnDescriptionLike): boolean =>
  * plain → generated (there is no `set expression` for a column that has none) and a column whose
  * recorded expression is unknown. `drop expression` is the one that HAS a statement, and it is the
  * generated → plain direction, which keeps the values it computed.
+ *
+ * **The rebuild moves the column's dependents aside first, and it is `retype-dependents.ts` that
+ * says which — never a second answer written here.** The `rebuilt`
+ * set `diffTable` carries into its index loop is keyed on an index's COLUMNS, so a partial index
+ * whose `where` names this column and whose key columns do not was dropped with the column by
+ * `drop column` and re-created by nothing: measured, the table came back with the index gone, the
+ * snapshot still recording it, and `down` unable to restore it. An invariant's CHECK reading the
+ * column is the same loss one arm over. `moveDependentsAside` drops each of them explicitly,
+ * restores them in `down`, and puts the name in `moved` — which is what makes the ordinary diff
+ * CREATE the declared one instead of comparing a definition that never moved.
  */
 export function regenerate(
-  table: string,
+  live: TableDescription,
   column: ColumnDescriptionLike,
   wantedType: string,
   recorded: ColumnDescription,
   plan: Plan,
+  moved: MovedAside,
 ): Regeneration {
+  const table = live.name;
   const wanted = column.generated ?? null;
   const held = recorded.generated ?? null;
   if (wanted === null && held === null) return 'unchanged';
@@ -89,6 +103,7 @@ export function regenerate(
   // column again. Reported as `rebuilt` so the caller can put the indexes back — an `add column`
   // implies none of them.
   if (held === null) {
+    moveDependentsAside(live, column.column, plan, moved);
     const dropColumn = `alter table ${identifier(table).text} drop column ${identifier(column.column).text};`;
     plan.up.push(
       dropColumn,
@@ -104,16 +119,26 @@ export function regenerate(
     );
     return 'rebuilt';
   }
-  let moved = false;
+  let changed = false;
+  // NOT `moveDependentsAside`, and the reason is measured rather than assumed. This ALTER trips the
+  // same `42883` (`operator does not exist: text > integer`, on a generated `integer` column under
+  // `where (doubled > 0)`) — but moving the index aside only relocates the failure to the
+  // `create index` that puts it back, because a predicate whose operator the NEW type has no
+  // resolution for cannot be written either. The plain path's dependents survive precisely because
+  // an untyped literal re-resolves (`status = 'published'` under an enum and under `text`), and a
+  // generated column reaching that shape needs its EXPRESSION changed in the same migration, which
+  // `regenerate` emits AFTER this statement. Left open deliberately, with the failure named.
   if (recorded.dataType !== wantedType) {
     plan.up.push(`${alterColumn(table, column.column)} type ${wantedType};`);
     plan.down.push(`${alterColumn(table, column.column)} type ${recorded.dataType};`);
-    moved = true;
+    changed = true;
   }
+  // Nothing moves for this one either, and here it is free: `set expression` recomputes every value
+  // and leaves the type alone, so nothing compiled against the type has anything to recompile.
   if (held !== wanted) {
     plan.up.push(`${alterColumn(table, column.column)} set expression as (${wanted});`);
     plan.down.push(`${alterColumn(table, column.column)} set expression as (${held});`);
-    moved = true;
+    changed = true;
   }
-  return moved ? 'altered' : 'unchanged';
+  return changed ? 'altered' : 'unchanged';
 }

package/src/index-ddl.ts

@@ -84,6 +84,57 @@ export function createIndex(table: string, index: IndexDescriptionLike): string
 /** `drop index "n";` — the one spelling, so a drop and its recreate cannot name it differently. */
 export const dropIndex = (name: string): string => `drop index ${identifier(name).text};`;
 
+/**
+ * Whether Postgres could be backing this RECORDED index with a UNIQUE constraint rather than
+ * holding it as an index of its own — which decides the only question `dropIndex` cannot answer.
+ *
+ * A UNIQUE constraint's index is unique, total, unordered and btree; `add constraint … unique`
+ * and a `unique` column clause can produce nothing else. So an index missing any one of those is
+ * provably an index, and `drop index` on it is right. Everything else is genuinely ambiguous —
+ * see `dropRecordedIndex`.
+ */
+export function mayBeConstraintBacked(index: IndexDescription): boolean {
+  return (
+    index.unique &&
+    !index.primary &&
+    index.where === null &&
+    index.order === null &&
+    indexMethodOf(index) === 'btree'
+  );
+}
+
+/**
+ * Remove a RECORDED index whose kind this generator cannot know, in statements that are correct
+ * on both databases it cannot tell apart.
+ *
+ * `TableDescription` carries no discriminator, and it cannot be given one that would help: the
+ * SAME declaration reaches the server as a CONSTRAINT or as an INDEX depending on which migration
+ * created it. A `unique` column on a table `createTable` writes emits `create table … slug text
+ * unique`, and Postgres backs that with a constraint named `posts_slug_key`; the same column
+ * gaining `unique` later takes `diffTable`'s `create unique index "posts_slug_key"` and is a plain
+ * index. `snapshotOf` records both as `{ unique: true, primary: false }`, and every sidecar already
+ * on disk was written that way — a new field could not classify one of them retroactively.
+ *
+ * Measured on 18.4 (`index-removal.live.test.ts`), which is why the pair and not a guess:
+ *
+ * | statement                                  | on a constraint's index | on a plain index |
+ * |--------------------------------------------|-------------------------|------------------|
+ * | `drop index "n"`                           | **2BP01**               | ok               |
+ * | `drop index if exists "n"`                 | **2BP01** — not suppressed | ok            |
+ * | `alter table … drop constraint if exists`  | drops it, index and all | notice, no-op    |
+ *
+ * Constraint first, then the index: reversed, the `drop index` reaches a constraint's index and is
+ * the 2BP01 this exists to avoid. Both halves carry `if exists`, so whichever one did nothing says
+ * so with a notice rather than 42704.
+ */
+export function dropRecordedIndex(table: string, index: IndexDescription): readonly string[] {
+  if (!mayBeConstraintBacked(index)) return [dropIndex(index.name)];
+  return [
+    `alter table ${identifier(table).text} drop constraint if exists ${identifier(index.name).text};`,
+    `drop index if exists ${identifier(index.name).text};`,
+  ];
+}
+
 /**
  * A RECORDED index as a declaration this generator can emit again — `declaredMethod`, never a
  * cast: the recorded side is typed open because the catalog shares the shape, and a method this

package/src/index-plan.ts

@@ -0,0 +1,119 @@
+// Single responsibility: which indexes an existing table gains, has rebuilt, or LOSES. Split out
+// of `generate.ts` along the seam `check-ddl.ts` and `index-ddl.ts` already drew — `generate.ts`
+// assembles a plan, `index-ddl.ts` writes the statements, and this file decides which of them go
+// in. `checkPlan` is its shape, deliberately: "what does the record hold that the declaration does
+// not" is one question, and a fourth spelling of it is the split axiom 1 refuses.
+//
+// The removal arm is why this file exists. `diffTable` walked `declaredIndexes(entity)` and matched
+// by name, with no reverse pass, so an index the entities stopped declaring stayed on the database
+// forever while the sidecar beside it stopped recording it — `examples/dummy` carried
+// `member_unique_per_org`, `members_tz_idx` and `post_slug_unique_per_org` through every
+// regeneration, and `x verify`'s drift step was green over all three because drift judges the
+// declared side. The same defect `foreignKeyPlan` closed on 2026-08-19, one arm over.
+//
+// KNOWN LIMIT, named rather than half-built: a UNIQUE index that a foreign key on ANOTHER table
+// still references cannot be dropped (2BP01), and this arm sees one table at a time. That
+// declaration is already broken — the key has nothing to point at — and the failure arrives with
+// the server's own words naming both ends.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import {
+  asDeclared,
+  createIndex,
+  dropIndex,
+  dropRecordedIndex,
+  impliedByColumnClause,
+  redefineIndex,
+} from './index-ddl';
+import type { TableDescription } from './introspect';
+import { declaredIndexes } from './invariant-ddl';
+
+/**
+ * What the rest of this migration has already done to the columns underneath the indexes — every
+ * field is a set of names some other arm produced, and each answers "this index is already gone".
+ */
+export interface IndexPlanContext {
+  /** Columns this migration ADDS, whose own `unique` clause brings an index Postgres names. */
+  readonly added: ReadonlySet<string>;
+  /** Columns `regenerate` dropped and re-added outright — every index over one went with it. */
+  readonly rebuilt: ReadonlySet<string>;
+  /** Indexes a retype already dropped ahead of its ALTER (`moveDependentsAside`). */
+  readonly moved: ReadonlySet<string>;
+}
+
+/**
+ * Which indexes an existing table gains, has rebuilt, or loses.
+ *
+ * Declared first and removed last, the order `checkPlan` uses. Both orders are safe — two indexes
+ * over the same columns may coexist for the length of one migration — so the tie goes to the file
+ * this one is a copy of.
+ *
+ * `down` is pushed FORWARDS and read backwards, because assembly reverses it: the restore of a
+ * removed index therefore lands after the drop of everything created beside it.
+ */
+export function indexPlan(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  context: IndexPlanContext,
+): void {
+  const indexed = new Map(live.indexes.map((index) => [index.name, index]));
+  const declared = new Set<string>();
+  for (const index of declaredIndexes(entity)) {
+    declared.add(index.name);
+    const recorded = indexed.get(index.name);
+    // A rebuilt column took its indexes down with it, and a retype dropped the ones whose
+    // predicate it could not survive — either way this one is CREATED rather than compared:
+    // `redefineIndex` sees a definition that never moved and would emit nothing at all.
+    const gone =
+      context.moved.has(index.name) || index.columns.some((each) => context.rebuilt.has(each));
+    if (recorded !== undefined && !gone) {
+      redefineIndex(entity.table, index, recorded, plan);
+      continue;
+    }
+    // `added` only: an index over a column that was already there is implied by no clause this
+    // migration emits, so it still needs a statement of its own.
+    if (impliedByColumnClause(entity, index, context.added)) continue;
+    plan.up.push(createIndex(entity.table, index));
+    // The plain drop, always: this migration CREATED it, with `create index`, so it is an index
+    // and never a constraint's — `dropRecordedIndex`'s ambiguity is about the recorded side only.
+    plan.down.push(dropIndex(index.name));
+  }
+  removeUndeclared(entity, live, plan, context, declared);
+}
+
+/**
+ * Every recorded index this entity no longer declares, dropped — and restored in `down` from what
+ * the SNAPSHOT recorded, never from what the entity declares, since the entity is precisely what
+ * stopped describing it. The rule the retype path already states.
+ *
+ * Four names are skipped, and each one is a statement Postgres would refuse or repeat:
+ *
+ * | skipped                                  | because |
+ * |------------------------------------------|---------|
+ * | `primary`                                | `drop index` on a primary key's index is 2BP01; the key is `TableDescription.primaryKey`, a different question |
+ * | already in `context.moved`               | a retype dropped it ahead of the ALTER — a second drop is 42704 |
+ * | over a column in `context.rebuilt`       | it went with the `drop column` half of `regenerate` — 42704 |
+ * | over a column this migration DROPS       | `alter table … drop column` takes it, so a drop beside it says nothing new. The rule `foreignKeyPlan` applies to a constraint on a dropped column |
+ *
+ * A doomed TABLE needs no arm: `generate.ts` only reaches a diff for a table an entity still
+ * declares, so `drop table` and this function never meet.
+ */
+function removeUndeclared(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  context: IndexPlanContext,
+  declared: ReadonlySet<string>,
+): void {
+  const columns = new Set(entity.columns.map((column) => column.column));
+  for (const recorded of live.indexes) {
+    if (recorded.primary || declared.has(recorded.name)) continue;
+    if (context.moved.has(recorded.name)) continue;
+    if (recorded.columns.some((column) => context.rebuilt.has(column))) continue;
+    if (!recorded.columns.every((column) => columns.has(column))) continue;
+    plan.up.push(...dropRecordedIndex(live.name, recorded));
+    plan.down.push(createIndex(live.name, asDeclared(recorded)));
+  }
+}

package/src/index.ts

@@ -23,25 +23,15 @@ export {
 export type {
   DbClient,
   DbConnection,
-  DbHealthReport,
-  PoolProfile,
   PostgresClient,
   PostgresClientOptions,
   ReservableClient,
 } from './client';
-export {
-  baseClient,
-  checkDb,
-  createPostgresClient,
-  db,
-  isReservable,
-  POOL_MAX_ENV,
-  POOL_PROFILES,
-  poolProfileFor,
-  setDbClient,
-} from './client';
+export { baseClient, createPostgresClient, db, isReservable, setDbClient } from './client';
 export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
+export type { DbHealthReport } from './db-health';
+export { checkDb } from './db-health';
 export { defaultClient, REPLICA_URL_ENV } from './default-client';
 export type { DestructiveKind, DestructiveStatement } from './destructive';
 export {
@@ -62,6 +52,7 @@ export {
   expectedSchema,
   FRAMEWORK_TABLE_PREFIX,
 } from './drift';
+export { dbDrift } from './drift-errors';
 export type {
   ColumnDescriptionLike,
   EntityDescriptionLike,
@@ -76,20 +67,13 @@ export {
   DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
-  dbDrift,
   dbNotImplemented,
   dbUnavailable,
   driverError,
   identifierUnsafe,
-  migrateConcurrent,
-  migrationConflict,
-  migrationDestructive,
-  migrationIrreversible,
-  migrationSnapshotMissing,
   multipleStatements,
   poolAcquireTimeout,
   poolMaxInvalid,
-  rollbackStepsInvalid,
   serializationExhausted,
   sqlUnsafe,
 } from './errors';
@@ -147,6 +131,15 @@ export {
   rollback,
   runningAppVersion,
 } from './migrate';
+export {
+  migrateConcurrent,
+  migrationConflict,
+  migrationDestructive,
+  migrationIrreversible,
+  migrationSnapshotMissing,
+  migrationViewDepends,
+  rollbackStepsInvalid,
+} from './migration-errors';
 export type { StatementAttribution, StatementEvent, StatementObserver } from './observe';
 export { setStatementObserver, statementObserver } from './observe';
 export type {
@@ -166,6 +159,8 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
+export type { PoolProfile } from './pool-profile';
+export { POOL_MAX_ENV, POOL_PROFILES, poolProfileFor } from './pool-profile';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
 export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
 export type { ReadOnlyRoleOptions } from './readonly-role';
@@ -182,7 +177,15 @@ export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope'
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
-export { identifier, isSqlFragment, join, literal, raw, sql } from './sql';
+export {
+  identifier,
+  isSqlFragment,
+  join,
+  literal,
+  raw,
+  shellInertIdentifier,
+  sql,
+} from './sql';
 export { stripSqlNoise } from './sql-noise';
 export type { DbSqlStateCode } from './sqlstate';
 export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';

package/src/migrate.ts

@@ -3,17 +3,13 @@
 // app-version fence is the `migrate` role's contract — a pod must refuse to migrate a database
 // another build already owns, because the alternative is two schemas racing during a rollout.
 
-import { appVersion } from '@ultimat3/core';
-import {
-  baseClient,
-  type DbClient,
-  type DbConnection,
-  isReservable,
-  poolProfileFor,
-} from './client';
-import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './errors';
+import { appVersion, finiteCount } from '@ultimat3/core';
+import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
+import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
+import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
+import { poolProfileFor } from './pool-profile';
 import { raw, sql } from './sql';
 import { SQLSTATE, sqlState } from './sqlstate';
 import { statementsOf } from './statement-split';
@@ -236,6 +232,9 @@ async function acquireLock(session: DbClient, waitMs: number): Promise<void> {
           sql`select pg_try_advisory_lock(${MIGRATION_LOCK_KEY}) as locked`,
         );
         if (row?.locked === true) return;
+        // `waitMs` is screened at both call sites: `NaN - elapsed` is `NaN`, `NaN <= 0` is false
+        // and `Bun.sleep(Math.min(POLL, NaN))` does not sleep — so an unbounded wait is not what a
+        // non-finite one produced, a tight spin re-taking `pg_try_advisory_lock` was.
         const remaining = waitMs - (performance.now() - started);
         if (remaining <= 0) {
           throw migrateConcurrent(MIGRATION_LOCK_KEY, Math.round(performance.now() - started));
@@ -316,7 +315,17 @@ async function setLockTimeout(tx: DbTx, lockTimeoutMs: number): Promise<void> {
  * same `ACCESS EXCLUSIVE` locks against the same tables.
  */
 function migrationLockTimeoutMs(explicit: number | undefined): number {
-  return explicit ?? poolProfileFor('migrate').lockTimeoutMs;
+  // Screened here, where BOTH `migrate()` and `rollback()` resolve it, and before either takes the
+  // advisory lock. `lockWaitMs` beside it was screened from the start and this one was not, so
+  // `Number(process.env.…)` on an unset variable travelled all the way to `SET LOCAL lock_timeout
+  // = NaN`, which the server rejects inside the migration's own transaction — the option that was
+  // wrong appears nowhere in what the deploy prints. `finiteCount`, never a second bound checker.
+  return finiteCount(
+    'migrate',
+    'lockTimeoutMs',
+    explicit ?? poolProfileFor('migrate').lockTimeoutMs,
+    0,
+  );
 }
 
 export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
@@ -328,7 +337,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
   return withAdvisoryLock(
     client,
     options.lock !== false,
-    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       await ensureLedger(session);
       const ledger = await readLedger(session);
@@ -348,6 +357,12 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
             await withTransaction(
               async (tx) => {
                 await setLockTimeout(tx, lockTimeoutMs);
+                // Before the first statement, never after the failure: a view compiled against a
+                // column this script retypes is `0A000` from the server with the view named only in
+                // a DETAIL field nothing prints, surfaced as "cannot reach the database". Costs one
+                // text scan and no round trip on a migration that retypes nothing, which is nearly
+                // all of them (`dependent-view.ts`).
+                await refuseDependentViews(tx, migration.up);
                 await applyScript(tx, migration.up);
                 const durationMs = Math.round(performance.now() - at);
                 await tx.execute(sql`
@@ -412,7 +427,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
   return withAdvisoryLock(
     client,
     options.lock !== false,
-    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       const ledger = await readLedger(session);
       const targets = [...ledger].reverse().slice(0, steps);
@@ -438,6 +453,9 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
             await withTransaction(
               async (tx) => {
                 await setLockTimeout(tx, lockTimeoutMs);
+                // Both directions: a reversal retypes the same column back, and a view created
+                // since the migration applied blocks it exactly as one created before would.
+                await refuseDependentViews(tx, migration.down);
                 await applyScript(tx, migration.down);
                 await tx.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
               },

package/src/migration-errors.ts

@@ -0,0 +1,132 @@
+// Single responsibility: the refusals a MIGRATION earns — the lock it could not take, a ledger that
+// disagrees with this build, a plan that cannot be reversed, a plan that destroys rows without
+// saying so, a snapshot that was never written, and a view standing in a retype's way. Split out of
+// `errors.ts` only because that file reached the 500-line ceiling, exactly as `invariant-errors.ts`
+// was: every code below is still declared, titled and registered there, and `DbError` is still the
+// one class. One direction only — nothing here is imported back.
+
+import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
+import { DbError } from './errors';
+
+/**
+ * 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 },
+  });
+
+export const migrationConflict = (cause: string, fix: string): DbError =>
+  new DbError({ code: 'X_MIGRATION_CONFLICT', cause, fix });
+
+export const migrationIrreversible = (cause: string, fix: string): DbError =>
+  new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
+
+/**
+ * A view standing in the way of a retype, refused one statement before Postgres would have.
+ *
+ * `restore` is the caller's, the way `migrationIrreversible`'s `fix:` is: it is a pair of
+ * `psql "$DATABASE_URL" -c '…'` invocations — the shape `migrationConflict` above already writes —
+ * built out of live catalog values through `identifier()`. This file may not import `sql.ts`: that
+ * module imports `identifierUnsafe` from here, and an import cycle around the module whose
+ * evaluation REGISTERS every code is not a cycle worth having for one quoted name.
+ */
+export const migrationViewDepends = (
+  view: string,
+  table: string,
+  column: string,
+  restore: string,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_VIEW_DEPENDS',
+    cause:
+      `view "${view}" is compiled against "${table}"."${column}", which this migration retypes; ` +
+      'Postgres answers 0A000 and rolls the whole migration back',
+    fix: restore,
+    meta: { view, table, column },
+  });
+
+/**
+ * A rollback step count this build cannot honour. `steps` reaches `Array.prototype.slice`, where a
+ * negative count counts from the END: `steps: -1` selected every applied migration except the
+ * newest and reversed four of five, which is the one class of mistake a rollback cannot undo.
+ * Refused rather than coerced, exactly as `DATABASE_POOL_MAX` is — a number silently reinterpreted
+ * as a different one is the failure a validated argument exists to prevent.
+ */
+export const rollbackStepsInvalid = (received: number): DbError =>
+  new DbError({
+    code: 'X_INVARIANT',
+    cause: `rollback was asked to reverse ${String(received)} migrations, which is not a positive integer`,
+    fix: 'rollback({ migrations, steps: 1 })   # a whole number of migrations, newest first',
+    meta: { steps: received },
+  });
+
+/**
+ * `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 },
+  });