@ultimat3/db 14.0.0 → 16.0.0

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

@@ -81,15 +81,9 @@ export {
   dbUnavailable,
   driverError,
   identifierUnsafe,
-  migrateConcurrent,
-  migrationConflict,
-  migrationDestructive,
-  migrationIrreversible,
-  migrationSnapshotMissing,
   multipleStatements,
   poolAcquireTimeout,
   poolMaxInvalid,
-  rollbackStepsInvalid,
   serializationExhausted,
   sqlUnsafe,
 } from './errors';
@@ -147,6 +141,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 {

package/src/introspect.ts

@@ -87,6 +87,24 @@ export interface TableDescription {
    * would leave every already-generated app's invariants unenforced forever.
    */
   readonly checks?: readonly CheckDescription[] | undefined;
+  /**
+   * The catalog's half of `checks`, and a **separate field rather than the same one** — names
+   * only, `conname` for `contype = 'c'`, never a definition.
+   *
+   * The two readings cannot share `checks` because they are not the same value. A catalog read
+   * carries Postgres' own rewriting of the predicate and a declaration carries this generator's
+   * spelling, so a `checks` filled from `pg_constraint` would put a rewritten expression on the
+   * field `checkPlan` diffs against a generated one — every regenerated migration would then drop
+   * and re-add every constraint in the app, forever, because the two strings can never be equal.
+   * Splitting them means the type says which reading a value came from, and `checkPlan` cannot be
+   * handed a catalog value by accident.
+   *
+   * `snapshotOf` never writes it and `parseSnapshot` never reads it, so a sidecar carries `checks`
+   * alone. `introspect()` always answers with it, `[]` included: absent therefore means "nobody
+   * asked the catalog", which is what keeps `compareChecks` silent on a description that never
+   * read one instead of reporting every declared constraint as missing.
+   */
+  readonly checkNames?: readonly string[] | undefined;
 }
 
 export interface SchemaDescription {
@@ -135,6 +153,12 @@ interface ForeignKeyRow {
   readonly on_delete: string | null;
 }
 
+/** A CHECK constraint's NAME. There is deliberately no column for its definition — see `checkNames`. */
+interface CheckRow {
+  readonly table_name: string;
+  readonly constraint_name: string;
+}
+
 const byName = (a: { name: string }, b: { name: string }): number => (a.name < b.name ? -1 : 1);
 
 export async function introspect(options: IntrospectOptions = {}): Promise<SchemaDescription> {
@@ -206,7 +230,21 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     order by src.relname, c.conname
   `);
 
-  return buildSchema(schema, excluded, columns, indexes, foreignKeys);
+  // `conname` and nothing else. `pg_get_constraintdef(c.oid)` is one word further along this line
+  // and is the reason this query did not exist: it answers Postgres' rewriting of the predicate,
+  // which no generated spelling can ever equal, so reading it would make every drift check report
+  // a correct database as wrong. `contype = 'c'` is the CHECK constraints alone — Postgres 17
+  // onwards records a NOT NULL as `'n'`, and a domain's as `'c'` on the domain rather than here.
+  const checks = await client.query<CheckRow>(sql`
+    select src.relname as table_name, c.conname as constraint_name
+    from pg_constraint c
+    join pg_class src on src.oid = c.conrelid
+    join pg_namespace n on n.oid = src.relnamespace
+    where c.contype = 'c' and n.nspname = ${schema} and src.relkind = 'r'
+    order by src.relname, c.conname
+  `);
+
+  return buildSchema(schema, excluded, columns, indexes, foreignKeys, checks);
 }
 
 /** Pure, so the row -> description mapping is testable without a database. */
@@ -216,6 +254,7 @@ export function buildSchema(
   columns: readonly ColumnRow[],
   indexes: readonly IndexRow[],
   foreignKeys: readonly ForeignKeyRow[],
+  checks: readonly CheckRow[] = [],
 ): SchemaDescription {
   const names = [...new Set(columns.map((row) => row.table_name))]
     .filter((name) => !excluded.includes(name))
@@ -261,6 +300,12 @@ export function buildSchema(
           onDelete: row.on_delete,
         }))
         .sort(byName),
+      // Always written, `[]` included: this reading of a table HAS asked the catalog, and absence
+      // is reserved for a description that has not (`compareChecks` is silent on that one).
+      checkNames: checks
+        .filter((row) => row.table_name === name)
+        .map((row) => row.constraint_name)
+        .sort(),
     };
   });
 

package/src/migrate.ts

@@ -11,9 +11,10 @@ import {
   isReservable,
   poolProfileFor,
 } from './client';
-import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './errors';
+import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
+import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
 import { raw, sql } from './sql';
 import { SQLSTATE, sqlState } from './sqlstate';
 import { statementsOf } from './statement-split';
@@ -348,6 +349,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`
@@ -438,6 +445,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 },
+  });

package/src/retype-dependents.ts

@@ -0,0 +1,135 @@
+// Single responsibility: which RECORDED objects a retype of one column breaks, and the statements
+// that take them out of the way before the ALTER and put them back in the `down`.
+//
+// Postgres compiles a partial index's predicate and a CHECK's expression against the column's type
+// at creation and cannot recompile either: `alter table "posts" alter column "status" type text
+// using "status"::text` answers `42883 operator does not exist: text = post_status` and the
+// migration aborts mid-run — inside `ROLE=migrate`, with the ledger recording nothing. Measured on
+// Postgres 18.4 (`generate-retype.live.test.ts`), one dependent shape at a time:
+//
+// | recorded object                          | survives the ALTER |
+// |------------------------------------------|--------------------|
+// | btree on the column, plain or unique      | yes — Postgres rebuilds it itself |
+// | composite btree including the column      | yes |
+// | partial index whose predicate names it    | **no — 42883** |
+// | partial index naming another column       | yes |
+// | CHECK whose expression names it           | **no — 42883** |
+//
+// So only an expression that MENTIONS the column is dependent, and dropping the rest would be a
+// table scan per index for nothing.
+
+import { addCheck, dropCheck } from './check-ddl';
+import type { Plan } from './foreign-key-plan';
+import { asDeclared, createIndex, dropIndex } from './index-ddl';
+import type { CheckDescription, IndexDescription, TableDescription } from './introspect';
+import { IDENTIFIER_PART, noiseAt } from './sql-scan';
+
+/**
+ * Whether `expression` reads `column`, over-approximating on purpose.
+ *
+ * The two errors are not symmetrical. A dependent object missed is `42883` in the release phase;
+ * one reported that was not is a rebuild nobody asked for — so every ambiguous case answers `true`,
+ * and the folding is case-insensitive because Postgres folds an unquoted identifier to lower case
+ * and `"Status"` naming a different column is a rarity beside a predicate this must not miss.
+ *
+ * What it does NOT count is noise, through this package's one lexer (`sql-scan.ts`): the `status`
+ * in `where kind = 'status'` is data, not a reference, and the one in `-- status` is prose. A
+ * QUOTED identifier is counted — `"status"` is the reference the catalog stores for an author who
+ * quoted it, and skipping it as noise is exactly the miss that ends in `42883`.
+ */
+export function referencesColumn(expression: string, column: string): boolean {
+  const wanted = column.toLowerCase();
+  let at = 0;
+  while (at < expression.length) {
+    const noise = noiseAt(expression, at);
+    if (noise !== null) {
+      if (
+        noise.kind === 'identifier' &&
+        expression.slice(at + 1, noise.end - 1).toLowerCase() === wanted
+      ) {
+        return true;
+      }
+      at = noise.end;
+      continue;
+    }
+    if (!IDENTIFIER_PART.test(expression[at] ?? '')) {
+      at += 1;
+      continue;
+    }
+    let end = at;
+    while (end < expression.length && IDENTIFIER_PART.test(expression[end] ?? '')) end += 1;
+    if (expression.slice(at, end).toLowerCase() === wanted) return true;
+    at = end;
+  }
+  return false;
+}
+
+/** The recorded objects a retype of `column` cannot leave in place. */
+export interface RetypeDependents {
+  /**
+   * Partial indexes whose predicate reads the column. A `primary` one is structurally impossible —
+   * a primary key index has no predicate — which is what keeps `drop index` off the two indexes
+   * Postgres refuses it on: a primary key's and a unique constraint's.
+   */
+  readonly indexes: readonly IndexDescription[];
+  /** CHECK constraints whose expression reads the column. */
+  readonly checks: readonly CheckDescription[];
+}
+
+/**
+ * What a retype of `table`.`column` breaks, read off the RECORDED schema — never the catalog.
+ * `x db gen` runs with no database open, so a hand-added expression index over the same column is
+ * invisible here and still `42883`; what this can see is every object a migration wrote down.
+ */
+export function retypeDependents(column: string, live: TableDescription): RetypeDependents {
+  return {
+    indexes: live.indexes.filter(
+      (index) => !index.primary && index.where !== null && referencesColumn(index.where, column),
+    ),
+    checks: (live.checks ?? []).filter((check) => referencesColumn(check.expression, column)),
+  };
+}
+
+/**
+ * What this plan has already dropped ahead of a retype — names only, because that is all the two
+ * readers need. The ordinary diff runs AFTER the ALTER and must not act on an object that is no
+ * longer there: the index loop CREATES a name in `indexes` instead of comparing it (a `drop index`
+ * on a name already dropped is `42704`, and a definition that never moved would emit nothing at
+ * all, leaving the table with no index), and `checkPlan` neither drops nor re-adds a name in
+ * `checks` — the declared side is added back by its own arm, and a recorded constraint the entity
+ * no longer declares is simply gone, which is what `checkPlan` would have done to it anyway.
+ */
+export interface MovedAside {
+  readonly indexes: Set<string>;
+  readonly checks: Set<string>;
+}
+
+/**
+ * Drop every dependent in `up`, restore it in `down`, and record what was moved.
+ *
+ * `down` is reversed at assembly, so the restores are pushed FORWARDS here and the retype's own
+ * reversal is pushed after them — the reversed script therefore reads: retype back to the old
+ * type, then recreate the objects that were compiled against it. Restoring first would recreate a
+ * predicate against a type the column no longer has, which is `42883` in the other direction.
+ *
+ * What is restored is what the snapshot RECORDED, never what the entity declares: an object still
+ * declared is re-created by the ordinary diff, one statement later, in its current shape.
+ */
+export function moveDependentsAside(
+  live: TableDescription,
+  column: string,
+  plan: Plan,
+  moved: MovedAside,
+): void {
+  const dependents = retypeDependents(column, live);
+  for (const index of dependents.indexes) {
+    plan.up.push(dropIndex(index.name));
+    plan.down.push(createIndex(live.name, asDeclared(index)));
+    moved.indexes.add(index.name);
+  }
+  for (const check of dependents.checks) {
+    plan.up.push(dropCheck(live.name, check.name));
+    plan.down.push(addCheck(live.name, check));
+    moved.checks.add(check.name);
+  }
+}