@ultimat3/db 15.0.0 → 16.0.0

package/src/foreign-key-plan.ts

@@ -3,9 +3,15 @@
 // BEFORE them. `generate.ts` assembles the plan; `foreign-key.ts` writes the SQL.
 
 import type { EntityDescriptionLike } from './entity-shape';
-import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import {
+  addForeignKey,
+  dropForeignKey,
+  foreignKeyTarget,
+  keyId,
+  onDeleteRule,
+  unrestorableNote,
+} from './foreign-key';
 import type { ForeignKeyDescription, TableDescription } from './introspect';
-import { identifier } from './sql';
 
 /** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
 export interface Plan {
@@ -73,19 +79,31 @@ export function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescript
  * Both directions, because a snapshot may not lie: a removed `references()` used to emit nothing
  * while the snapshot beside it recorded `foreignKeys: []`, so the orphan constraint stayed on the
  * database *and* the record denied one the catalog holds — and `compareForeignKeys` judges the
- * declared side, so no drift check could ever see it. Not parity with a removed index either: that
- * leaves the snapshot correct by omission. The drop names the constraint the previous snapshot
+ * declared side, so no drift check could ever see it. This comment used to add "not parity with a
+ * removed index either: that leaves the snapshot correct by omission", which was **wrong** — a
+ * removed index lied in the identical way, and `index-plan.ts` is the arm that closed it. The drop names the constraint the previous snapshot
  * recorded, never the name this generator would have chosen — a hand-written `fk_legacy` is
  * `42704` under the generated spelling.
+ *
+ * `plans.predropped` names the constraints a RETYPE already took out of the way (`retype-keys.ts`),
+ * and it is read as "the schema does not record this key" — the same reading `checkPlan` gives its
+ * own `predropped` set. That is what makes this function the one writer of an `add constraint`
+ * after a retype: a key still declared is added back here, in the bucket that already runs after
+ * every table statement; one the entity dropped is left where the retype left it, because dropping
+ * it a second time is `42704`; and one whose `on delete` moved comes back carrying the new rule.
+ * Its `down` is the retype's, pushed where reversal puts it after both ends are back.
  */
 export function foreignKeyPlan(
   entity: EntityDescriptionLike,
   live: TableDescription | undefined,
   plans: ConstraintPlans,
 ): void {
-  const { constraints, preDrops, doomed } = plans;
+  const { constraints, preDrops, doomed, predropped } = plans;
   const wanted = foreignKeysOf(entity);
-  const held = new Map((live?.foreignKeys ?? []).map((key) => [foreignKeyTarget(key), key]));
+  const recordedKeys = (live?.foreignKeys ?? []).filter(
+    (key) => !predropped.has(keyId(entity.table, key.name)),
+  );
+  const held = new Map(recordedKeys.map((key) => [foreignKeyTarget(key), key]));
   for (const key of wanted) {
     const recorded = held.get(foreignKeyTarget(key));
     if (doomed.has(key.referencedTable)) {
@@ -115,7 +133,7 @@ export function foreignKeyPlan(
   }
   const declared = new Set(wanted.map(foreignKeyTarget));
   const columns = new Set(entity.columns.map((column) => column.column));
-  for (const key of live?.foreignKeys ?? []) {
+  for (const key of recordedKeys) {
     if (declared.has(foreignKeyTarget(key))) continue;
     // `drop column` takes the constraint with it, so a `drop constraint` after that statement is
     // `42704` on a constraint that is already gone.
@@ -136,19 +154,22 @@ export interface ConstraintPlans {
   readonly preDrops: Plan;
   /** The tables this migration drops, by name. */
   readonly doomed: ReadonlySet<string>;
+  /**
+   * Recorded keys a retype already dropped ahead of the ALTERs, by `keyId` (`retype-keys.ts`).
+   * Read as "not recorded", never as "leave it alone": the declared side still needs its
+   * `add constraint`, and it is this function that writes it.
+   */
+  readonly predropped: ReadonlySet<string>;
 }
 
 /**
  * A key whose target is being dropped: gone on the way up, a note on the way back.
  *
- * The note goes through `identifier` too. A `--` comment ends at the first newline, so a name
- * holding one is a second command on the line after it — the same escape `columnClause` closed,
- * one quoting rule short of the statement above it.
+ * The note itself is `unrestorableNote` (`foreign-key.ts`) and not a string built here —
+ * `retype-keys.ts` says the same thing about the same failed rollback, and two spellings of one
+ * fact is whichever module emitted last deciding what an operator reads.
  */
 function unrestorableDrop(table: string, constraint: string, target: string, preDrops: Plan): void {
   preDrops.up.push(dropForeignKey(table, constraint));
-  preDrops.down.push(
-    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
-      `cannot be restored; ${identifier(target).text} is gone`,
-  );
+  preDrops.down.push(unrestorableNote(table, constraint, target));
 }

package/src/foreign-key.ts

@@ -52,6 +52,19 @@ export function foreignKeyTarget(key: ForeignKeyDescription): string {
   return JSON.stringify([[...key.columns], key.referencedTable, [...key.referencedColumns]]);
 }
 
+/**
+ * Which constraint, on which table — a key's NAME, where `foreignKeyTarget` is its meaning.
+ *
+ * The two exist for opposite questions and neither substitutes for the other. Drift asks whether
+ * two keys point the same way and must ignore the name; a plan that has already DROPPED a
+ * constraint asks whether this is that exact constraint, which is the name and nothing else. The
+ * table is in it because two tables may each hold a `..._org_id_fkey`, and `checkPlan`'s
+ * `predropped` set is the same shape one file over.
+ */
+export function keyId(table: string, constraint: string): string {
+  return JSON.stringify([table, constraint]);
+}
+
 /**
  * Through `identifier`, never `"${…}"` — the package's one rule, which every name this file writes
  * now goes through. A name that closes its own quote produced a real `drop table` through
@@ -98,6 +111,26 @@ export function dropForeignKey(table: string, constraint: string): string {
   return `alter table ${identifier(table).text} drop constraint ${identifier(constraint).text};`;
 }
 
+/**
+ * What a `down` says in place of an `add constraint` it cannot run: the key's table or its target
+ * is dropped by this migration, so there is nothing to add the constraint back onto.
+ *
+ * ONE text, two writers — `foreign-key-plan.ts`'s `unrestorableDrop` (a key pointing at a doomed
+ * table) and `retype-keys.ts`'s `restore` (a key a retype moved aside whose ends are doomed).
+ * They spelled the same fact two ways and had already drifted, so an operator reading a failed
+ * rollback saw whichever module emitted last. It lives here because both import this module and
+ * neither imports the other.
+ *
+ * Every name goes through `identifier`, including `gone`: a `--` comment ends at the first
+ * newline, so a name holding one puts a second command on the line after it.
+ */
+export function unrestorableNote(table: string, constraint: string, gone: string): string {
+  return (
+    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
+    `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.

package/src/generate.ts

@@ -9,11 +9,11 @@ import { defaultExpression } from './column-default';
 import { isDestructive } from './destructive';
 import { dropOrder } from './drop-order';
 import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
-import { migrationIrreversible } from './errors';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
 import type { Regeneration } from './generated-column';
 import { generatedClause, isGenerated, regenerate } from './generated-column';
-import { createIndex, dropIndex, impliedByColumnClause, redefineIndex } from './index-ddl';
+import { createIndex, impliedByColumnClause } from './index-ddl';
+import { indexPlan } from './index-plan';
 import {
   type ColumnDescription,
   findTable,
@@ -21,31 +21,14 @@ import {
   type TableDescription,
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
+import { migrationIrreversible } from './migration-errors';
 import type { MovedAside } from './retype-dependents';
 import { moveDependentsAside } from './retype-dependents';
+import { moveKeysAside, retypedColumns, retypedIn } from './retype-keys';
 import { identifier } from './sql';
+import { sqlType } from './sql-type';
 import { type UnrenderedDeclaration, unrenderedComment, unrenderedOf } from './unrendered';
 
-const SQL_TYPES: Readonly<Record<string, string>> = {
-  uuid: 'uuid',
-  text: 'text',
-  // Bare `char` is `char(1)` in Postgres, and the only column carrying this kind is money's
-  // currency — a three-letter ISO 4217 code whose CHECK the entity emits on the same line.
-  // Without the length no currency ever fits the constraint the same statement demands.
-  char: 'char(3)',
-  boolean: 'boolean',
-  integer: 'integer',
-  bigint: 'bigint',
-  numeric: 'numeric',
-  timestamptz: 'timestamptz',
-  date: 'date',
-  jsonb: 'jsonb',
-};
-
-function sqlType(kind: string): string {
-  return SQL_TYPES[kind] ?? kind;
-}
-
 function columnClause(column: ColumnDescriptionLike): string {
   // The generation clause sits directly after the type, and `generatedClause` refuses the pairs
   // Postgres has no column for. Every other part below is unchanged and unreachable for a
@@ -160,15 +143,19 @@ function retypeColumn(
   recorded: ColumnDescription,
   plan: Plan,
   moved: MovedAside,
+  retyped: ReadonlySet<string>,
 ): Regeneration {
   const wanted = sqlType(column.kind);
   const table = live.name;
   // A generated column moves by its own rules — see `generated-column.ts`. Asked whenever EITHER
   // side is one, because becoming generated and ceasing to be are both changes with a statement.
   if (isGenerated(column) || recorded.generated !== undefined) {
-    return regenerate(table, column, wanted, recorded, plan);
+    return regenerate(live, column, wanted, recorded, plan, moved);
   }
-  if (recorded.dataType === wanted) return 'unchanged';
+  // The set, never `recorded.dataType === wanted` a second time: `retypedColumns` decided this for
+  // the whole schema before any statement was written, because the foreign keys a retype breaks
+  // are recorded on tables this diff is not looking at (`retype-keys.ts`).
+  if (!retyped.has(column.column)) return 'unchanged';
   moveDependentsAside(live, column.column, plan, moved);
   const alter = (type: string): string =>
     `alter table ${identifier(table).text} alter column ${identifier(column.column).text} ` +
@@ -178,7 +165,12 @@ function retypeColumn(
   return 'altered';
 }
 
-function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
+function diffTable(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  retyped: ReadonlySet<string>,
+): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
   // A column `regenerate` had to replace outright: `add column` implies no index, so every index
@@ -189,7 +181,7 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
-      if (retypeColumn(live, column, recorded, plan, moved) === 'rebuilt') {
+      if (retypeColumn(live, column, recorded, plan, moved, retyped) === 'rebuilt') {
         rebuilt.add(column.column);
       }
       continue;
@@ -216,23 +208,9 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     );
   }
 
-  const indexed = new Map(live.indexes.map((index) => [index.name, index]));
-  for (const index of declaredIndexes(entity)) {
-    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 = moved.indexes.has(index.name) || index.columns.some((each) => 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, added)) continue;
-    plan.up.push(createIndex(entity.table, index));
-    plan.down.push(dropIndex(index.name));
-  }
+  // Both directions, in `index-plan.ts`: a recorded index the entity no longer declares is DROPPED
+  // there, which is the arm this loop did not have for as long as it lived here.
+  indexPlan(entity, live, plan, { added, rebuilt, moved: moved.indexes });
 
   // Last: a CHECK may read a column this migration just added, and `add constraint` on a column
   // that does not exist yet is `42703`. `check-ddl.ts` owns which of them move; `rebuilt` because a
@@ -292,12 +270,20 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // Merged in BEFORE them, for the mirror-image reason: a key still pointing at a table this
   // migration drops makes that `drop table` `2BP01`.
   const preDrops: Plan = { up: [], down: [] };
+  // Ahead of EVERYTHING, and at the far end of `down`: a foreign key compiled against a column
+  // being retyped has to be gone before the first ALTER and back after the last one, and both ends
+  // of one key can move in two different entities' diffs (`retype-keys.ts`).
+  const preAlters: Plan = { up: [], down: [] };
   const wanted = new Set(options.entities.map((entity) => entity.table));
 
   const doomed = new Set(
     current.tables.filter((table) => !wanted.has(table.name)).map((table) => table.name),
   );
-  const plans: ConstraintPlans = { constraints, preDrops, doomed };
+  // Before the loop, because the answer spans it: `diffTable` is handed one entity's recorded row
+  // and the key that a retype of its column breaks is recorded on whichever table OWNS the key.
+  const retyped = retypedColumns(options.entities, current);
+  const predropped = moveKeysAside(current, retyped, doomed, preAlters);
+  const plans: ConstraintPlans = { constraints, preDrops, doomed, predropped };
 
   for (const entity of options.entities) {
     const live = findTable(current, entity.table);
@@ -307,7 +293,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
       plan.down.push(`drop table ${identifier(entity.table).text};`);
       continue;
     }
-    diffTable(entity, live, plan);
+    diffTable(entity, live, plan, retypedIn(retyped, entity.table));
     const kept = new Set(entity.columns.map((column) => column.column));
     for (const column of live.columns) {
       if (kept.has(column.name)) continue;
@@ -365,15 +351,17 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // `current`, not the entities alone: an `assert` whose CHECK a previous migration recorded is a
   // loss only because THIS plan drops it, and the recorded schema is the only thing that knows.
   const unrendered = unrenderedOf(options.entities, current);
-  const body = plan.up.join('\n');
+  const body = [...preAlters.up, ...plan.up].join('\n');
   const up = body.length === 0 ? body : unrenderedComment(unrendered) + body;
   return {
     id,
     name: options.name,
     fileName: `migrations/${id}.sql`,
     up,
-    // Reverse order: the last thing created is the first thing dropped.
-    down: [...plan.down].reverse().join('\n'),
+    // Reverse order: the last thing created is the first thing dropped. `preAlters` goes in at the
+    // FRONT here precisely so reversal puts it last — a key is added back only once both of its
+    // ends have been retyped back, which is every other statement in the script.
+    down: [...preAlters.down, ...plan.down].reverse().join('\n'),
     snapshot: snapshotOf(options.entities),
     destructive: isDestructive(up),
     unrendered,

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

@@ -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/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}`);
               },