@quereus/quereus 4.19.4 → 4.20.1

package/dist/src/schema/schema-differ.js

@@ -1,3 +1,4 @@
+import { implicitIndexNameForColumns } from './catalog.js';
 import { createTableToString, createViewToString, createMaterializedViewToString, createIndexToString, createAssertionToString, columnDefToString, quoteIdentifier, expressionToString, tagsBodyToString, tableConstraintsToString, constraintBodyToCanonicalString, createIndexBodyToCanonicalString, indexedColumnBareName, viewDefinitionToCanonicalString, astToString } from '../emit/ast-stringify.js';
 import { computeBodyHash, normalizeBackingModuleName, canonicalBackingModuleArgs } from './view.js';
 import { QuereusError } from '../common/errors.js';
@@ -6,10 +7,11 @@ import { createLogger } from '../common/logger.js';
 import { validateReservedTags } from './reserved-tags.js';
 import { raiseReservedTagDiagnostics } from './reserved-tags-policy.js';
 import { renameColumnInAst, renameColumnInCheckExpression, renameTableInAst, tableReferencedInAst, objectRefKey, singleSchemaObjectRefResolver } from './rename-rewriter.js';
+import { Parser } from '../parser/parser.js';
 import { cloneExpr, cloneQueryExpr } from '../planner/mutation/scope-transform.js';
 import { normalizeCollationName } from '../util/comparison.js';
 import { inferType } from '../types/registry.js';
-import { resolveDefaultCollation } from './table.js';
+import { resolveDefaultCollation, disambiguateAutoConstraintName } from './table.js';
 const log = createLogger('schema:differ');
 const warnLog = log.extend('warn');
 /** Reserved tag namespace prefix used for differ-recognized hints. */
@@ -1398,11 +1400,12 @@ columnRenamesByTable, schemaName) {
     return { ...stmt, columns, where };
 }
 /**
- * Converts a column-level constraint carrying a name into the equivalent
- * table-level {@link AST.TableConstraint}, so it can be stringified into an
- * `ADD CONSTRAINT` fragment and diffed by name alongside table-level constraints.
- * Returns undefined for constraint kinds that are not lifecycle-managed named
- * constraints (NOT NULL / NULL / DEFAULT / COLLATE / GENERATED / PRIMARY KEY).
+ * Converts a column-level constraint into the equivalent table-level
+ * {@link AST.TableConstraint}, so it can be stringified into an `ADD CONSTRAINT`
+ * fragment and diffed (by name, or by body when unnamed) alongside table-level
+ * constraints. Returns undefined for constraint kinds that are not
+ * lifecycle-managed table constraints (NOT NULL / NULL / DEFAULT / COLLATE /
+ * GENERATED / PRIMARY KEY).
  */
 function columnConstraintToTableConstraint(columnName, cc) {
     switch (cc.type) {
@@ -1421,13 +1424,18 @@ function columnConstraintToTableConstraint(columnName, cc) {
     }
 }
 /**
- * Gathers declared *user-named* CHECK / UNIQUE / FOREIGN KEY constraints from a
- * declared table — both table-level and column-level (carrying an explicit name)
- * — keyed by lowercased name. PRIMARY KEY is excluded (handled by
- * `primaryKeyChange`); engine-synthesized `_`-prefixed names are excluded to stay
- * symmetric with the catalog's `namedConstraints`. On a name collision the first
+ * Gathers a declared table's CHECK / UNIQUE / FOREIGN KEY constraints — both
+ * table-level and column-level — split the way the catalog splits them:
+ * *user-named* ones keyed by lowercased name, and the rest (no name, or a
+ * reserved `_`-prefixed one) as a list in declaration order. PRIMARY KEY is
+ * excluded (handled by `primaryKeyChange`). On a user-name collision the first
  * wins (a duplicate user constraint name is a separate validation concern).
  *
+ * A column-level clause on a column `isAddedColumn` reports is skipped: `ADD
+ * COLUMN` renders the column's clauses inline (`columnDefToString`), so collecting
+ * it here would ADD the constraint a second time. A TABLE-level constraint over a
+ * new column is not carried by `ADD COLUMN` and is collected as usual.
+ *
  * `schemaName` is the schema this table is being diffed under (the differ runs
  * per schema — it is the CHILD schema for any FK declared here). It is threaded
  * into the canonical-body render so an FK's explicit own-schema qualifier folds
@@ -1435,33 +1443,34 @@ function columnConstraintToTableConstraint(columnName, cc) {
  * {@link constraintBodyToCanonicalString}); a genuine cross-schema parent stays a
  * body-change channel.
  */
-function collectDeclaredNamedConstraints(declaredTable, schemaName) {
-    const out = new Map();
-    const add = (name, tags, tc) => {
-        if (!name)
-            return;
-        const lower = name.toLowerCase();
-        if (lower.startsWith('_'))
+function collectDeclaredConstraints(declaredTable, schemaName, isAddedColumn) {
+    const named = new Map();
+    const unnamed = [];
+    const add = (tc, column) => {
+        const definition = constraintBodyToCanonicalString(tc, schemaName);
+        if (!tc.name || tc.name.startsWith('_')) {
+            unnamed.push({ name: tc.name, column, definition, bodyAst: tc });
             return;
-        if (out.has(lower))
+        }
+        const lower = tc.name.toLowerCase();
+        if (named.has(lower))
             return;
-        out.set(lower, { name, tags, ddl: tableConstraintsToString([tc]), definition: constraintBodyToCanonicalString(tc, schemaName), bodyAst: tc });
+        named.set(lower, { name: tc.name, tags: tc.tags, ddl: tableConstraintsToString([tc]), definition, bodyAst: tc });
     };
     for (const c of declaredTable.tableStmt.constraints ?? []) {
-        if (c.type === 'primaryKey')
-            continue;
-        add(c.name, c.tags, c);
+        if (c.type !== 'primaryKey')
+            add(c);
     }
     for (const col of declaredTable.tableStmt.columns) {
+        if (isAddedColumn(col.name.toLowerCase()))
+            continue;
         for (const cc of col.constraints ?? []) {
-            if (!cc.name)
-                continue;
             const tc = columnConstraintToTableConstraint(col.name, cc);
             if (tc)
-                add(cc.name, cc.tags, tc);
+                add(tc, col.name);
         }
     }
-    return out;
+    return { named, unnamed };
 }
 /**
  * Inverse-applies the in-diff column renames to a constraint's column list: maps
@@ -1654,6 +1663,141 @@ resolveDeclaredColumn) {
             return d.definition;
     }
 }
+/**
+ * Constraint lifecycle for CHECK / UNIQUE / FOREIGN KEY constraints with no
+ * user-addressable name (see `CatalogTable.unnamedConstraints`). With no name to
+ * key on, identity is the canonical body: declared and actual are matched as a
+ * multiset — each declared constraint consumes one actual with the same
+ * (rename-reconciled) body, so two identical unnamed CHECKs are two entries.
+ *
+ *   - declared, unmatched → ADD under a minted reserved name (see
+ *     {@link mintUnnamedConstraintName}), so the result is unnamed-class on the
+ *     next diff and droppable by name;
+ *   - actual, unmatched   → DROP by its stored auto-name. One stored with no name
+ *     (a CREATE-time table-level CHECK, any UNIQUE added unnamed) has no statement
+ *     that removes it: skipped when a dropped column takes it along (DROP COLUMN
+ *     prunes a UNIQUE / FK over the column), otherwise refused here — the
+ *     alternative is the silent no-op that leaves an upgraded database enforcing a
+ *     rule a fresh one does not.
+ *
+ * NOTE: tags on an unnamed constraint are not diffed — with no name there is
+ * nothing for `ALTER CONSTRAINT … SET TAGS` to address. A tag-only edit to an
+ * unnamed constraint is a no-op; name the constraint to manage its tags.
+ */
+function diffUnnamedConstraints(declared, actualTable, ctx) {
+    const unmatchedActual = [...(actualTable.unnamedConstraints ?? [])];
+    const unmatchedDeclared = [];
+    for (const d of declared) {
+        const body = ctx.reconcile(d);
+        // Among same-body actuals, keep the one with no stored name: of a pair, it is
+        // the one no DROP can reach, so leaving the other unmatched stays droppable.
+        let at = unmatchedActual.findIndex(a => a.definition === body && a.name === undefined);
+        if (at < 0)
+            at = unmatchedActual.findIndex(a => a.definition === body);
+        if (at >= 0)
+            unmatchedActual.splice(at, 1);
+        else
+            unmatchedDeclared.push(d);
+    }
+    const drops = [];
+    const undroppable = [];
+    for (const a of unmatchedActual) {
+        if (a.name !== undefined)
+            drops.push(a.name);
+        else if (!prunedByColumnDrop(a, ctx.droppedColumns))
+            undroppable.push(a);
+    }
+    if (undroppable.length > 0 && ctx.refuseUndroppable) {
+        throw new QuereusError(`Cannot drop unnamed constraint ${undroppable.map(a => `'${a.definition}'`).join(', ')} from table '${ctx.schemaName}.${actualTable.name}': `
+            + `it is no longer declared, but it was created without a name, so no statement can drop it. `
+            + `Keep declaring it, or rebuild the table; name constraints (constraint <name> …) to keep them droppable.`, StatusCode.ERROR);
+    }
+    const taken = constraintNamesAtAddTime(actualTable, ctx, drops);
+    const checkOrdinal = countActualChecks(actualTable);
+    const adds = unmatchedDeclared.map(d => tableConstraintsToString([{ ...d.bodyAst, name: mintUnnamedConstraintName(d, ctx.tableName, checkOrdinal, taken) }]));
+    return { adds, drops };
+}
+/** True when DROP COLUMN removes `a` on its own: it prunes a UNIQUE / FK over a dropped column (a CHECK instead blocks the drop). */
+function prunedByColumnDrop(a, droppedColumns) {
+    return a.kind !== 'check' && (a.bodyAst?.columns ?? []).some(c => droppedColumns.has(c.name.toLowerCase()));
+}
+/** CHECKs on the actual table — where an unnamed table-level CHECK's `_check_<n>` ordinal starts. */
+function countActualChecks(actualTable) {
+    return (actualTable.namedConstraints ?? []).filter(c => c.bodyAst?.type === 'check').length
+        + (actualTable.unnamedConstraints ?? []).filter(c => c.kind === 'check').length;
+}
+/**
+ * The lowercased constraint names a minted name must avoid at the point the
+ * `ADD CONSTRAINT` steps run (after every DROP / RENAME CONSTRAINT and ADD COLUMN
+ * of the table — see the phase order in `generateMigrationPlan`): the live names
+ * minus the dropped ones, plus every declared user name (each exists by then),
+ * plus — over-approximated — what `ADD COLUMN` mints for an inline clause on a new
+ * column. An unnamed UNIQUE's backing-structure name (`_uc_<cols>`) is included:
+ * a UNIQUE added under the same name would collide with that structure.
+ *
+ * NOTE: that backing name is derived from the PRE-rename column names, but a RENAME
+ * COLUMN in the same diff moves it to `_uc_<new cols>` before the ADDs run. A mint can
+ * only hit the moved name through a `_`-joined spelling clash (`unique (a_b)` beside a
+ * renamed `unique (a, b)`), and the engine refuses that ADD loudly; if it ever bites,
+ * derive the name over the post-rename columns.
+ */
+function constraintNamesAtAddTime(actualTable, ctx, unnamedDrops) {
+    const taken = new Set();
+    for (const c of actualTable.namedConstraints ?? [])
+        taken.add(c.name.toLowerCase());
+    for (const c of actualTable.unnamedConstraints ?? []) {
+        if (c.name !== undefined)
+            taken.add(c.name.toLowerCase());
+        else if (c.kind === 'unique')
+            taken.add(uniqueBackingName(c.bodyAst?.columns ?? []).toLowerCase());
+    }
+    for (const name of [...ctx.namedDrops, ...unnamedDrops])
+        taken.delete(name.toLowerCase());
+    for (const name of ctx.declaredNames)
+        taken.add(name);
+    for (const col of ctx.addedColumns) {
+        taken.add(`_check_${col}`.toLowerCase());
+        taken.add(`_fk_${ctx.tableName}_${col}`.toLowerCase());
+        taken.add(uniqueBackingName([{ name: col }]).toLowerCase());
+    }
+    return taken;
+}
+/** The structure name an unnamed UNIQUE over `columns` is backed by. */
+function uniqueBackingName(columns) {
+    return implicitIndexNameForColumns(undefined, columns.map(c => c.name));
+}
+/**
+ * The reserved `_`-prefixed name an unnamed constraint is ADDed under — reserved so
+ * the result stays in the unnamed class (body-matched, stable on re-diff), named so
+ * it can be dropped and its ADD undone. Each spells what the engine itself names
+ * the constraint where it names one:
+ *   - the `_`-name the declaration wrote, if any;
+ *   - column-level CHECK → `_check_<column>` (CREATE TABLE's mint);
+ *   - table-level CHECK  → `_check_<n>`, `n` from the table's CHECK count, bumped
+ *     until free (the `_check_<index>` label an unnamed CHECK's violation reports;
+ *     each mint registers in `taken`, so the next one bumps past it).
+ *     NOT left unnamed: `ALTER … ADD` would mint a user-class `check_<n>`, which
+ *     the next diff would drop and re-add forever;
+ *   - FOREIGN KEY → `_fk_<table>_<cols>` (both engine paths' mint);
+ *   - UNIQUE      → `_uc_<cols>` (the backing-structure name both paths use).
+ * Then disambiguated (`_<N>` suffix) against — and registered into — `taken`.
+ */
+function mintUnnamedConstraintName(d, tableName, checkOrdinal, taken) {
+    const tc = d.bodyAst;
+    if (d.name === undefined && tc.type === 'check' && d.column === undefined) {
+        let n = checkOrdinal;
+        while (taken.has(`_check_${n}`))
+            n++;
+        taken.add(`_check_${n}`);
+        return `_check_${n}`;
+    }
+    const columns = tc.columns ?? [];
+    const base = d.name
+        ?? (tc.type === 'check' ? `_check_${d.column}`
+            : tc.type === 'foreignKey' ? `_fk_${tableName}_${columns.map(c => c.name).join('_')}`
+                : uniqueBackingName(columns));
+    return disambiguateAutoConstraintName(base, taken);
+}
 /**
  * Resolves a declared table's column renames against its matched actual catalog
  * table — the map-building + {@link resolveRenames} step shared by both the
@@ -1784,10 +1928,11 @@ defaultCollation) {
     // `constraints` list AND column-level constraints carrying an explicit name
     // (e.g. `qty int constraint chk_qty check (qty > 0)`) — the actual catalog's
     // `namedConstraints` already merges both. PRIMARY KEY constraints are excluded
-    // (PK changes flow through `primaryKeyChange`); auto-prefixed (`_`) names are
-    // excluded to stay symmetric with the catalog (see catalog.ts) so an unnamed
-    // declared constraint never churns add/drop against its synthesized actual name.
-    const declaredNamedConstraints = collectDeclaredNamedConstraints(declaredTable, schemaName);
+    // (PK changes flow through `primaryKeyChange`). Unnamed and auto-prefixed (`_`)
+    // ones are matched by body instead, after the named lifecycle below (see
+    // `diffUnnamedConstraints`), mirroring the catalog's named / unnamed split.
+    const declaredConstraints = collectDeclaredConstraints(declaredTable, schemaName, lower => !colRenames.pairs.has(lower));
+    const declaredNamedConstraints = declaredConstraints.named;
     const actualNamedConstraints = new Map();
     for (const c of actualTable.namedConstraints ?? []) {
         actualNamedConstraints.set(c.name.toLowerCase(), c);
@@ -1862,6 +2007,21 @@ defaultCollation) {
             pureDropCount++;
         }
     }
+    // Unnamed constraints are not rename candidates, so they stay out of the
+    // require-hint counts.
+    const unnamed = diffUnnamedConstraints(declaredConstraints.unnamed, actualTable, {
+        tableName: declaredTable.tableStmt.table.name,
+        schemaName,
+        reconcile: d => reconciledDeclaredBody(d, diff.columnsToRename, tableRenames, actualTable.name, schemaName, columnRenamesByTable, resolveDeclaredColumn),
+        declaredNames: [...declaredNamedConstraints.keys()],
+        namedDrops: constraintsToDrop,
+        addedColumns: declaredTable.tableStmt.columns.filter(c => !colRenames.pairs.has(c.name.toLowerCase())).map(c => c.name),
+        droppedColumns: new Set(diff.columnsToDrop.map(c => c.toLowerCase())),
+        // A backing-module move recreates the table, so its alter diff is discarded.
+        refuseUndroppable: !diff.maintainedModuleMigration,
+    });
+    constraintsToDrop.push(...unnamed.drops);
+    constraintsToAdd.push(...unnamed.adds);
     if (constraintsToAdd.length > 0)
         diff.constraintsToAdd = constraintsToAdd;
     if (constraintsToDrop.length > 0)
@@ -2374,8 +2534,8 @@ function orderDropsByFKDependency(dropSet, actualTables) {
  */
 function comparisonDomainAlters(quotedTable, quotedCol, change) {
     const prefix = `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol}`;
-    const retype = change.dataType !== undefined ? [`${prefix} SET DATA TYPE ${change.dataType}`] : [];
-    const recollate = change.collation !== undefined ? [`${prefix} SET COLLATE ${change.collation}`] : [];
+    const retype = change.dataType !== undefined ? [{ sql: `${prefix} SET DATA TYPE ${change.dataType}`, attribute: 'dataType' }] : [];
+    const recollate = change.collation !== undefined ? [{ sql: `${prefix} SET COLLATE ${change.collation}`, attribute: 'collation' }] : [];
     return normalizeCollationName(change.collation ?? 'BINARY') === 'BINARY'
         ? [...recollate, ...retype]
         : [...retype, ...recollate];
@@ -2399,12 +2559,31 @@ export function generateMigrationDDL(diff, schemaName) {
  * them without re-lexing the text this function just produced. The remaining steps
  * are short template-built strings (renames, drops, column/constraint alters,
  * `SET TAGS`) and stay text-only.
+ *
+ * With `actual` — the pre-apply catalog `computeSchemaDiff` was handed — every step
+ * also carries its reversal (`undo` / `irreversible`, see {@link MigrationStep}),
+ * rendered by {@link UndoRenderer} at the step's own push site so a forward
+ * statement and its undo read together. Without it nothing about the undo is
+ * computed: `generateMigrationDDL` never passes a catalog, so `diff schema` output
+ * and cost are untouched.
  */
-export function generateMigrationPlan(diff, schemaName) {
+export function generateMigrationPlan(diff, schemaName, actual) {
     const statements = [];
     const schemaPrefix = (schemaName && schemaName !== 'main') ? `${quoteIdentifier(schemaName)}.` : '';
-    /** Appends a template-built step — text-only, so the apply path parses it as before. */
-    const pushText = (sql) => { statements.push({ sql }); };
+    const undo = actual ? new UndoRenderer(schemaName ?? 'main', schemaPrefix, actual) : undefined;
+    /**
+     * Appends a template-built step — text-only, so the apply path parses it as
+     * before. `undoOf` runs only when undo was requested, and renders the reversal
+     * for the catalog state THIS step runs in (Rule 1 of {@link MigrationStep.undo}).
+     */
+    const pushText = (sql, undoOf) => {
+        statements.push(undo ? { sql, ...undoOf(undo) } : { sql });
+    };
+    /** Appends a create bucket; each create undoes to the `DROP … IF EXISTS` of what it made. */
+    const pushCreates = (bucket, kind) => {
+        for (const create of bucket)
+            statements.push(undo ? { ...create, ...undo.dropCreated(create, kind) } : create);
+    };
     // Renames first — they free old names for subsequent creates and re-target
     // dependents (handled inside ALTER TABLE ... RENAME by the rename rewriter).
     // Only tables have a rename primitive. The other RenameOp kinds are metadata
@@ -2415,13 +2594,16 @@ export function generateMigrationPlan(diff, schemaName) {
     // the table-alter channel (RENAME CONSTRAINT below).
     for (const r of diff.renames) {
         if (r.kind === 'table') {
-            pushText(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(r.oldName)} RENAME TO ${quoteIdentifier(r.newName)}`);
+            pushText(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(r.oldName)} RENAME TO ${quoteIdentifier(r.newName)}`, () => ({ undo: [`ALTER TABLE ${schemaPrefix}${quoteIdentifier(r.newName)} RENAME TO ${quoteIdentifier(r.oldName)}`] }));
         }
         // Non-table rename ops emit no DDL here — see the note above.
     }
+    // Every later step runs — and is undone — with the table renames in force, so
+    // from here on the undo renderer reads the pre-apply catalog through them.
+    undo?.tableRenamesLanded(diff.renames);
     // Drop assertions first (they may reference tables)
     for (const name of diff.assertionsToDrop) {
-        pushText(`DROP ASSERTION IF EXISTS ${schemaPrefix}${quoteIdentifier(name)}`);
+        pushText(`DROP ASSERTION IF EXISTS ${schemaPrefix}${quoteIdentifier(name)}`, u => u.recreateAssertion(name));
     }
     // Detach maintained tables (`drop maintained`) EARLY — where MV drops ran
     // before — so a detach precedes any column op on that table AND any drop of its
@@ -2430,25 +2612,25 @@ export function generateMigrationPlan(diff, schemaName) {
     // flip's cross-table detach-v2 / attach-v1 pair falls out of this ordering.
     for (const alter of diff.tablesToAlter) {
         if (alter.dropMaintained) {
-            pushText(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(alter.tableName)} DROP MAINTAINED`);
+            pushText(`ALTER TABLE ${schemaPrefix}${quoteIdentifier(alter.tableName)} DROP MAINTAINED`, u => u.reattachAsBefore(alter.tableName));
         }
     }
     // Drop items (reverse order)
     for (const tableName of diff.tablesToDrop) {
-        pushText(`DROP TABLE IF EXISTS ${schemaPrefix}${quoteIdentifier(tableName)}`);
+        pushText(`DROP TABLE IF EXISTS ${schemaPrefix}${quoteIdentifier(tableName)}`, u => u.droppedTable(tableName));
     }
     for (const viewName of diff.viewsToDrop) {
-        pushText(`DROP VIEW IF EXISTS ${schemaPrefix}${quoteIdentifier(viewName)}`);
+        pushText(`DROP VIEW IF EXISTS ${schemaPrefix}${quoteIdentifier(viewName)}`, u => u.recreateView(viewName));
     }
     for (const indexName of diff.indexesToDrop) {
-        pushText(`DROP INDEX IF EXISTS ${schemaPrefix}${quoteIdentifier(indexName)}`);
+        pushText(`DROP INDEX IF EXISTS ${schemaPrefix}${quoteIdentifier(indexName)}`, u => u.recreateIndex(indexName));
     }
     // Create new items. A fresh maintained table rides `tablesToCreate` (rendered
     // as the `create materialized view` sugar) and re-materializes as part of its
     // create.
-    statements.push(...diff.tablesToCreate);
-    statements.push(...diff.viewsToCreate);
-    statements.push(...diff.indexesToCreate);
+    pushCreates(diff.tablesToCreate, 'table');
+    pushCreates(diff.viewsToCreate, 'view');
+    pushCreates(diff.indexesToCreate, 'index');
     // Assertion creates do NOT go here — they run last, after the table alters and
     // the maintained re-attaches. See the push at the end of this function.
     // Alter existing tables.
@@ -2468,47 +2650,56 @@ export function generateMigrationPlan(diff, schemaName) {
     for (const alter of diff.tablesToAlter) {
         const quotedTable = `${schemaPrefix}${quoteIdentifier(alter.tableName)}`;
         for (const r of alter.columnsToRename) {
-            pushText(`ALTER TABLE ${quotedTable} RENAME COLUMN ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`);
+            pushText(`ALTER TABLE ${quotedTable} RENAME COLUMN ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`, () => ({ undo: [`ALTER TABLE ${quotedTable} RENAME COLUMN ${quoteIdentifier(r.newName)} TO ${quoteIdentifier(r.oldName)}`] }));
+            undo?.columnRenameLanded(alter.tableName, r);
         }
         for (const colDef of alter.columnsToAdd) {
-            pushText(`ALTER TABLE ${quotedTable} ADD COLUMN ${colDef}`);
+            pushText(`ALTER TABLE ${quotedTable} ADD COLUMN ${colDef}`, u => u.dropAddedColumn(quotedTable, colDef));
         }
         for (const colAlter of alter.columnsToAlter) {
             const quotedCol = quoteIdentifier(colAlter.columnName);
+            const alterColumn = `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol}`;
             // A default the retype would choke on and this migration replaces anyway is
             // cleared BEFORE the comparison-domain phase (see `dropStaleDefaultFirst`).
             if (colAlter.dropStaleDefaultFirst) {
-                pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP DEFAULT`);
+                pushText(`${alterColumn} DROP DEFAULT`, u => u.undoDropDefault(alter.tableName, colAlter.columnName, alterColumn));
             }
             // SET DATA TYPE / SET COLLATE lead the per-column phase (both are
             // comparison-domain changes), before DEFAULT / NOT NULL.
-            for (const s of comparisonDomainAlters(quotedTable, quotedCol, colAlter))
-                pushText(s);
+            for (const s of comparisonDomainAlters(quotedTable, quotedCol, colAlter)) {
+                pushText(s.sql, u => s.attribute === 'dataType'
+                    ? u.retypedColumn(alter.tableName, colAlter.columnName)
+                    : u.undoSetCollation(alter.tableName, colAlter.columnName, alterColumn));
+            }
             if (colAlter.defaultValue !== undefined) {
                 if (colAlter.defaultValue === null) {
                     // Already dropped above when it preceded the retype.
                     if (!colAlter.dropStaleDefaultFirst) {
-                        pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP DEFAULT`);
+                        pushText(`${alterColumn} DROP DEFAULT`, u => u.undoDropDefault(alter.tableName, colAlter.columnName, alterColumn));
                     }
                 }
                 else {
-                    pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET DEFAULT ${expressionToString(colAlter.defaultValue)}`);
+                    // After `dropStaleDefaultFirst` the column reaches this step with no
+                    // default — the stale one was cleared earlier in this phase — so the
+                    // reversal is a plain DROP DEFAULT, not the pre-apply default (Rule 1).
+                    pushText(`${alterColumn} SET DEFAULT ${expressionToString(colAlter.defaultValue)}`, u => colAlter.dropStaleDefaultFirst
+                        ? { undo: [`${alterColumn} DROP DEFAULT`] }
+                        : u.undoSetDefault(alter.tableName, colAlter.columnName, alterColumn));
                 }
             }
             if (colAlter.notNull !== undefined) {
-                pushText(colAlter.notNull
-                    ? `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} SET NOT NULL`
-                    : `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedCol} DROP NOT NULL`);
+                pushText(colAlter.notNull ? `${alterColumn} SET NOT NULL` : `${alterColumn} DROP NOT NULL`, () => ({ undo: [colAlter.notNull ? `${alterColumn} DROP NOT NULL` : `${alterColumn} SET NOT NULL`] }));
             }
         }
         // Constraint lifecycle: RENAME (free a name) then DROP (remove a stale /
         // conflicting constraint), both BEFORE re-adds and before the PK change so a
         // dropped UNIQUE can't strand a PK dependency.
         for (const r of alter.constraintsToRename ?? []) {
-            pushText(`ALTER TABLE ${quotedTable} RENAME CONSTRAINT ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`);
+            pushText(`ALTER TABLE ${quotedTable} RENAME CONSTRAINT ${quoteIdentifier(r.oldName)} TO ${quoteIdentifier(r.newName)}`, () => ({ undo: [`ALTER TABLE ${quotedTable} RENAME CONSTRAINT ${quoteIdentifier(r.newName)} TO ${quoteIdentifier(r.oldName)}`] }));
+            undo?.constraintRenameLanded(alter.tableName, r);
         }
         for (const name of alter.constraintsToDrop ?? []) {
-            pushText(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quoteIdentifier(name)}`);
+            pushText(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quoteIdentifier(name)}`, u => u.readdConstraint(alter.tableName, name, quotedTable));
         }
         if (alter.primaryKeyChange) {
             const pkCols = alter.primaryKeyChange.newPkColumns
@@ -2519,16 +2710,16 @@ export function generateMigrationPlan(diff, schemaName) {
                 return s;
             })
                 .join(', ');
-            pushText(`ALTER TABLE ${quotedTable} ALTER PRIMARY KEY (${pkCols})`);
+            pushText(`ALTER TABLE ${quotedTable} ALTER PRIMARY KEY (${pkCols})`, u => u.restorePrimaryKey(alter.tableName, quotedTable));
         }
         // ADD CONSTRAINT after the PK change (a new UNIQUE / FK may align with the new
         // key) and after the column adds it may reference. CHECK adds apply in-place;
         // UNIQUE / FK adds depend on module ADD CONSTRAINT support (see constraintsToAdd).
         for (const frag of alter.constraintsToAdd ?? []) {
-            pushText(`ALTER TABLE ${quotedTable} ADD ${frag}`);
+            pushText(`ALTER TABLE ${quotedTable} ADD ${frag}`, u => u.dropAddedConstraint(quotedTable, frag));
         }
         for (const colName of alter.columnsToDrop) {
-            pushText(`ALTER TABLE ${quotedTable} DROP COLUMN ${quoteIdentifier(colName)}`);
+            pushText(`ALTER TABLE ${quotedTable} DROP COLUMN ${quoteIdentifier(colName)}`, u => u.droppedColumn(alter.tableName, colName));
         }
         // Tags phase — last, so a SET TAGS lands on the post-structural column /
         // constraint set (a tag set emitted alongside a RENAME COLUMN targets the
@@ -2539,15 +2730,17 @@ export function generateMigrationPlan(diff, schemaName) {
             // TABLE handler rejects a tag action on a maintained table). See
             // `TableAlterDiff.maintainedTags`.
             const tagVerb = alter.maintainedTags ? 'ALTER MATERIALIZED VIEW' : 'ALTER TABLE';
-            pushText(`${tagVerb} ${quotedTable} SET TAGS ${tagsBodyToString(alter.tableTagsChange)}`);
+            pushText(`${tagVerb} ${quotedTable} SET TAGS ${tagsBodyToString(alter.tableTagsChange)}`, u => u.restoreTableTags(alter.tableName, `${tagVerb} ${quotedTable}`));
         }
         for (const colAlter of alter.columnsToAlter) {
             if (colAlter.tags === undefined)
                 continue;
-            pushText(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quoteIdentifier(colAlter.columnName)} SET TAGS ${tagsBodyToString(colAlter.tags)}`);
+            const alterColumn = `ALTER TABLE ${quotedTable} ALTER COLUMN ${quoteIdentifier(colAlter.columnName)}`;
+            pushText(`${alterColumn} SET TAGS ${tagsBodyToString(colAlter.tags)}`, u => u.restoreColumnTags(alter.tableName, colAlter.columnName, alterColumn));
         }
         for (const ctc of alter.constraintTagsChanges ?? []) {
-            pushText(`ALTER TABLE ${quotedTable} ALTER CONSTRAINT ${quoteIdentifier(ctc.constraintName)} SET TAGS ${tagsBodyToString(ctc.tags)}`);
+            const alterConstraint = `ALTER TABLE ${quotedTable} ALTER CONSTRAINT ${quoteIdentifier(ctc.constraintName)}`;
+            pushText(`${alterConstraint} SET TAGS ${tagsBodyToString(ctc.tags)}`, u => u.restoreConstraintTags(alter.tableName, ctc.constraintName, alterConstraint));
         }
     }
     // Attach / re-attach maintained tables (`set maintained as`) LATE — where MV
@@ -2575,7 +2768,8 @@ export function generateMigrationPlan(diff, schemaName) {
                 select: alter.setMaintained.select,
             },
         };
-        statements.push({ sql: astToString(stmt), ast: stmt });
+        const step = { sql: astToString(stmt), ast: stmt };
+        statements.push(undo ? { ...step, ...undo.undoSetMaintained(alter) } : step);
     }
     // Assertion creates LAST — after every table alter and maintained re-attach, so
     // a body sees the final shape of every object. `CREATE ASSERTION` plans its
@@ -2584,7 +2778,7 @@ export function generateMigrationPlan(diff, schemaName) {
     // create ran in the create block, before `ADD COLUMN`. Nothing in a migration
     // depends on an assertion existing, so last is strictly safer. Assertion DROPs
     // stay first (see the top of this function).
-    statements.push(...diff.assertionsToCreate);
+    pushCreates(diff.assertionsToCreate, 'assertion');
     // In-place tag changes on views / indexes. These are leaf metadata writes (no
     // dependency ordering vs the table-alter block). The `?? []` keeps
     // generateMigrationDDL robust against hand-built diffs (some tests construct
@@ -2592,11 +2786,472 @@ export function generateMigrationPlan(diff, schemaName) {
     // table's tag-only change rides the table-alter block above (`SET TAGS`), not a
     // separate bucket.
     for (const vtc of diff.viewTagsChanges ?? []) {
-        pushText(`ALTER VIEW ${schemaPrefix}${quoteIdentifier(vtc.name)} SET TAGS ${tagsBodyToString(vtc.tags)}`);
+        const alterView = `ALTER VIEW ${schemaPrefix}${quoteIdentifier(vtc.name)}`;
+        pushText(`${alterView} SET TAGS ${tagsBodyToString(vtc.tags)}`, u => u.restoreViewTags(vtc.name, alterView));
     }
     for (const itc of diff.indexTagsChanges ?? []) {
-        pushText(`ALTER INDEX ${schemaPrefix}${quoteIdentifier(itc.name)} SET TAGS ${tagsBodyToString(itc.tags)}`);
+        const alterIndex = `ALTER INDEX ${schemaPrefix}${quoteIdentifier(itc.name)}`;
+        pushText(`${alterIndex} SET TAGS ${tagsBodyToString(itc.tags)}`, u => u.restoreIndexTags(itc.name, alterIndex));
     }
     return statements;
 }
+/** A step that changed nothing, so nothing has to be put back. */
+const NOTHING_TO_UNDO = { undo: [] };
+/** Case-insensitive identifier equality — how the catalog and the rename walkers compare names. */
+const sameName = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * The pre-apply spelling of a name as spelled NOW, given the renames in force:
+ * the old name when a rename landed on it, the name itself when none touched it,
+ * and `undefined` when a rename vacated it — nothing pre-apply answers to it any more.
+ */
+function preRenameName(renames, currentName) {
+    const landed = renames.find(r => sameName(r.newName, currentName));
+    if (landed)
+        return landed.oldName;
+    return renames.some(r => sameName(r.oldName, currentName)) ? undefined : currentName;
+}
+/**
+ * Renders each migration step's undo from the pre-apply catalog. The two rules
+ * {@link MigrationStep.undo} states are what every arm below honours:
+ *
+ * **Rule 1 — spell the target the way the forward step did.** The unwind runs in
+ * reverse, so when a step's undo runs every later step has already been taken back
+ * and the catalog is in the state the step itself left behind. The plan is pushed in
+ * execution order and this renderer is told about each rename as its step lands
+ * (`tableRenamesLanded`, `columnRenameLanded`, `constraintRenameLanded`), so every
+ * catalog lookup goes through exactly the renames in force at that step — a later
+ * `ALTER TABLE t …` step's undo names the post-rename `t`, and finds the pre-apply
+ * table under its old name.
+ *
+ * **Rule 2 — forward-apply the renames in force to anything taken from the catalog.**
+ * A restored constraint / view / assertion / derivation body, a column default and
+ * the old primary key are spelled with pre-rename names in the catalog; by Rule 1
+ * those renames are still in force when the undo runs, so {@link replayRenames}
+ * applies them forward — through the same `renameTableInAst` /
+ * `renameColumnInAst` / `renameColumnInCheckExpression` walkers the live rename
+ * propagation uses — before the body is emitted. This is the differ's
+ * rename-reconciled comparison (`reconciledDeclaredBody`) pointed the other way.
+ * Only renames whose steps PRECEDE this one count: a view dropped before the
+ * column-rename phase is restored with the old column names, because by the time
+ * its undo runs the column rename has already been reversed.
+ *
+ * Two policies keep the plan generator total over hand-built inputs:
+ *   - a target the pre-apply catalog does not mention undoes to nothing — the
+ *     forward step either is a no-op (`IF EXISTS`) or fails before changing anything;
+ *   - a catalog entry that lacks what its restore needs (no body AST, DDL that does
+ *     not parse) is reported as `irreversible` with the reason, never thrown.
+ *
+ * NOTE: the undo is rendered eagerly for every step at plan time, so once the apply
+ * path passes its catalog every apply pays it; the only non-trivial per-step cost is
+ * one small parse on the fragment arms (dropped index, added column / constraint).
+ * If plan generation ever shows up in profiles, render lazily on the failure path.
+ */
+class UndoRenderer {
+    schemaName;
+    schemaPrefix;
+    tables = new Map();
+    views = new Map();
+    indexes = new Map();
+    assertions = new Map();
+    resolveRef;
+    tableRenames = [];
+    columnRenames = [];
+    constraintRenames = [];
+    constructor(schemaName, schemaPrefix, actual) {
+        this.schemaName = schemaName;
+        this.schemaPrefix = schemaPrefix;
+        for (const t of actual.tables ?? [])
+            this.tables.set(t.name.toLowerCase(), t);
+        for (const v of actual.views ?? [])
+            this.views.set(v.name.toLowerCase(), v);
+        // NOTE: an index name is unique per table, not per schema, and the plan's
+        // `DROP INDEX` names it bare — so the first entry wins here, as it does there.
+        // If `indexesToDrop` ever carries the owning table, key this map by both.
+        for (const i of actual.indexes ?? [])
+            if (!this.indexes.has(i.name.toLowerCase()))
+                this.indexes.set(i.name.toLowerCase(), i);
+        for (const a of actual.assertions ?? [])
+            this.assertions.set(a.name.toLowerCase(), a);
+        this.resolveRef = singleSchemaObjectRefResolver(schemaName);
+    }
+    // --- Rename bookkeeping (Rule 1) ---
+    tableRenamesLanded(renames) {
+        this.tableRenames = renames.filter(r => r.kind === 'table');
+    }
+    columnRenameLanded(table, r) {
+        this.columnRenames.push({ table, oldName: r.oldName, newName: r.newName });
+    }
+    constraintRenameLanded(table, r) {
+        this.constraintRenames.push({ table, oldName: r.oldName, newName: r.newName });
+    }
+    // --- Arms ---
+    dropCreated(create, kind) {
+        const name = createdObjectName(create.ast, kind);
+        if (name === undefined)
+            return this.cannotUndo(create.sql, `its statement is not a create ${kind}`);
+        const verb = { table: 'DROP TABLE', view: 'DROP VIEW', index: 'DROP INDEX', assertion: 'DROP ASSERTION' }[kind];
+        return { undo: [`${verb} IF EXISTS ${this.schemaPrefix}${quoteIdentifier(name)}`] };
+    }
+    droppedTable(actualName) {
+        if (!this.tables.has(actualName.toLowerCase()))
+            return NOTHING_TO_UNDO;
+        return { irreversible: `dropping table "${actualName}" also discards its rows, and no statement can bring them back` };
+    }
+    droppedColumn(table, column) {
+        if (!this.columnNow(table, column))
+            return NOTHING_TO_UNDO;
+        return { irreversible: `dropping column "${column}" from table "${table}" discards the values stored in it, and no statement can bring them back` };
+    }
+    retypedColumn(table, column) {
+        if (!this.columnNow(table, column))
+            return NOTHING_TO_UNDO;
+        return { irreversible: `changing the type of column "${column}" in table "${table}" converts the values stored in it, and a conversion can lose information that no statement can bring back` };
+    }
+    recreateAssertion(name) {
+        const assertion = this.assertions.get(name.toLowerCase());
+        if (!assertion)
+            return NOTHING_TO_UNDO;
+        if (!assertion.check)
+            return this.cannotUndo(`DROP ASSERTION ${name}`, 'the pre-apply catalog carries no CHECK body for it');
+        const check = cloneExpr(assertion.check);
+        this.replayRenames(check, undefined, {});
+        const stmt = { type: 'createAssertion', name: { type: 'identifier', name: assertion.name }, check };
+        return { undo: [createAssertionToString(applyAssertionSchemaDefault(stmt, this.schemaName))] };
+    }
+    recreateView(name) {
+        const view = this.views.get(name.toLowerCase());
+        if (!view)
+            return NOTHING_TO_UNDO;
+        if (!view.select)
+            return this.cannotUndo(`DROP VIEW ${name}`, 'the pre-apply catalog carries no body for it');
+        const select = cloneQueryExpr(view.select);
+        this.replayRenames(select, undefined, {});
+        const stmt = {
+            type: 'createView',
+            view: { type: 'identifier', name: view.name },
+            ifNotExists: false,
+            columns: view.columns ? [...view.columns] : undefined,
+            select,
+            tags: view.tags ? { ...view.tags } : undefined,
+        };
+        return { undo: [createViewToString(applyViewSchemaDefault(stmt, this.schemaName))] };
+    }
+    recreateIndex(name) {
+        const index = this.indexes.get(name.toLowerCase());
+        if (!index)
+            return NOTHING_TO_UNDO;
+        // The catalog carries no structured index shape, only `generateIndexDDL`'s
+        // text — re-parsed here with the real parser rather than sliced.
+        const parsed = parseStatement(index.ddl);
+        if (!parsed.ok)
+            return this.cannotUndo(`DROP INDEX ${name}`, `its recorded DDL does not parse (${parsed.reason})`);
+        if (parsed.stmt.type !== 'createIndex')
+            return this.cannotUndo(`DROP INDEX ${name}`, 'its recorded DDL is not a create index statement');
+        const recreate = {
+            ...parsed.stmt,
+            ifNotExists: false,
+            index: { type: 'identifier', name: index.name },
+            table: { type: 'identifier', name: this.tableNameNow(index.tableName) },
+        };
+        if (recreate.where)
+            this.replayRenames(recreate.where, undefined, { schemaAuthoredBody: true });
+        return { undo: [createIndexToString(applyIndexDefaults(recreate, this.schemaName))] };
+    }
+    /** Undo of `DROP MAINTAINED`: the derivation the table carried before the apply. */
+    reattachAsBefore(table) {
+        const maintained = this.tableNow(table)?.maintained;
+        if (!maintained)
+            return NOTHING_TO_UNDO;
+        return this.setMaintainedFrom(maintained, table);
+    }
+    /**
+     * Undo of `SET MAINTAINED`. The table is plain at this step when it never was
+     * maintained OR when this same plan detached it earlier (the reshape leg:
+     * `drop maintained` → column ops → re-attach); either way the attach undoes to
+     * a detach, and the earlier detach's own undo restores the original derivation.
+     * A same-shape re-attach (no detach) replaced the derivation in place, so its
+     * undo re-attaches the pre-apply one.
+     */
+    undoSetMaintained(alter) {
+        const actual = this.tableNow(alter.tableName);
+        if (!actual)
+            return NOTHING_TO_UNDO;
+        if (!actual.maintained || alter.dropMaintained) {
+            return { undo: [`ALTER TABLE ${this.schemaPrefix}${quoteIdentifier(alter.tableName)} DROP MAINTAINED`] };
+        }
+        return this.setMaintainedFrom(actual.maintained, alter.tableName);
+    }
+    readdConstraint(table, name, quotedTable) {
+        // `constraintsToDrop` carries pre-apply names (a renamed constraint is never
+        // also dropped), so the lookup is direct rather than through the renames. An
+        // unnamed constraint is dropped by its stored auto-name, and re-added under it.
+        const actual = this.tableNow(table);
+        const constraint = actual?.namedConstraints?.find(c => sameName(c.name, name))
+            ?? actual?.unnamedConstraints?.find(c => c.name !== undefined && sameName(c.name, name));
+        if (!constraint)
+            return NOTHING_TO_UNDO;
+        if (!constraint.bodyAst)
+            return this.cannotUndo(`DROP CONSTRAINT ${name}`, 'the pre-apply catalog carries no body for it');
+        const body = this.forwardRenamedConstraint(constraint.bodyAst, table);
+        const fragment = tableConstraintsToString([{ ...body, name: constraint.name, tags: constraint.tags ? { ...constraint.tags } : undefined }]);
+        return { undo: [`ALTER TABLE ${quotedTable} ADD ${fragment}`] };
+    }
+    restorePrimaryKey(table, quotedTable) {
+        const actual = this.tableNow(table);
+        if (!actual)
+            return NOTHING_TO_UNDO;
+        if (actual.primaryKey.length === 0)
+            return this.cannotUndo(`ALTER PRIMARY KEY on ${table}`, 'the pre-apply catalog records no primary key for it');
+        const cols = actual.primaryKey
+            .map(pk => quoteIdentifier(this.columnNameNow(table, pk.columnName)) + (pk.desc ? ' desc' : ''))
+            .join(', ');
+        return { undo: [`ALTER TABLE ${quotedTable} ALTER PRIMARY KEY (${cols})`] };
+    }
+    dropAddedColumn(quotedTable, colDef) {
+        const parsed = parseStatement(`alter table "x" add column ${colDef}`);
+        if (!parsed.ok)
+            return this.cannotUndo(`ADD COLUMN ${colDef}`, `the column definition does not parse (${parsed.reason})`);
+        const action = parsed.stmt.type === 'alterTable' ? parsed.stmt.action : undefined;
+        if (action?.type !== 'addColumn')
+            return this.cannotUndo(`ADD COLUMN ${colDef}`, 'the column definition does not parse as one');
+        return { undo: [`ALTER TABLE ${quotedTable} DROP COLUMN ${quoteIdentifier(action.column.name)}`] };
+    }
+    dropAddedConstraint(quotedTable, fragment) {
+        const parsed = parseStatement(`alter table "x" add ${fragment}`);
+        if (!parsed.ok)
+            return this.cannotUndo(`ADD ${fragment}`, `the constraint fragment does not parse (${parsed.reason})`);
+        const action = parsed.stmt.type === 'alterTable' ? parsed.stmt.action : undefined;
+        if (action?.type !== 'addConstraint')
+            return this.cannotUndo(`ADD ${fragment}`, 'the fragment does not parse as a constraint');
+        if (!action.constraint.name)
+            return this.cannotUndo(`ADD ${fragment}`, 'the constraint has no name to drop it by');
+        return { undo: [`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quoteIdentifier(action.constraint.name)}`] };
+    }
+    /** Undo of `DROP DEFAULT`: put the pre-apply default back, or nothing when there was none. */
+    undoDropDefault(table, column, alterColumn) {
+        const prior = this.priorDefaultText(table, column);
+        return { undo: prior ? [`${alterColumn} SET DEFAULT ${prior}`] : [] };
+    }
+    /** Undo of `SET DEFAULT e`: the pre-apply default, or `DROP DEFAULT` when the column had none. */
+    undoSetDefault(table, column, alterColumn) {
+        const prior = this.priorDefaultText(table, column);
+        if (prior === undefined)
+            return NOTHING_TO_UNDO;
+        return { undo: [prior === null ? `${alterColumn} DROP DEFAULT` : `${alterColumn} SET DEFAULT ${prior}`] };
+    }
+    undoSetCollation(table, column, alterColumn) {
+        const actual = this.columnNow(table, column);
+        if (!actual)
+            return NOTHING_TO_UNDO;
+        return { undo: [`${alterColumn} SET COLLATE ${actual.collation || 'BINARY'}`] };
+    }
+    restoreTableTags(table, alterTable) {
+        const actual = this.tableNow(table);
+        return actual ? restoreTags(alterTable, actual.tags) : NOTHING_TO_UNDO;
+    }
+    restoreColumnTags(table, column, alterColumn) {
+        const actual = this.columnNow(table, column);
+        return actual ? restoreTags(alterColumn, actual.tags) : NOTHING_TO_UNDO;
+    }
+    restoreConstraintTags(table, constraint, alterConstraint) {
+        const actual = this.constraintNow(table, constraint);
+        return actual ? restoreTags(alterConstraint, actual.tags) : NOTHING_TO_UNDO;
+    }
+    restoreViewTags(view, alterView) {
+        const actual = this.views.get(view.toLowerCase());
+        return actual ? restoreTags(alterView, actual.tags) : NOTHING_TO_UNDO;
+    }
+    restoreIndexTags(index, alterIndex) {
+        const actual = this.indexes.get(index.toLowerCase());
+        return actual ? restoreTags(alterIndex, actual.tags) : NOTHING_TO_UNDO;
+    }
+    // --- Catalog lookups through the renames in force (Rule 1) ---
+    /**
+     * The pre-apply table a CURRENT table name denotes. A name a rename in force
+     * vacated (and nothing was renamed onto) denotes no pre-apply table: whatever
+     * sits under it now, this plan created.
+     */
+    tableNow(currentName) {
+        const actualName = preRenameName(this.tableRenames, currentName);
+        return actualName === undefined ? undefined : this.tables.get(actualName.toLowerCase());
+    }
+    /** The current spelling of a pre-apply table name. */
+    tableNameNow(actualName) {
+        return this.tableRenames.find(r => sameName(r.oldName, actualName))?.newName ?? actualName;
+    }
+    /** The pre-apply column a CURRENT column name denotes (both names as spelled now); see `tableNow` for a vacated name. */
+    columnNow(currentTable, currentColumn) {
+        const table = this.tableNow(currentTable);
+        if (!table)
+            return undefined;
+        const actualName = preRenameName(this.columnRenames.filter(r => sameName(r.table, currentTable)), currentColumn);
+        return actualName === undefined ? undefined : table.columns.find(c => sameName(c.name, actualName));
+    }
+    /** The current spelling of a pre-apply column name. */
+    columnNameNow(currentTable, actualColumn) {
+        return this.columnRenames.find(r => sameName(r.table, currentTable) && sameName(r.oldName, actualColumn))?.newName ?? actualColumn;
+    }
+    constraintNow(currentTable, currentName) {
+        const table = this.tableNow(currentTable);
+        if (!table)
+            return undefined;
+        const actualName = preRenameName(this.constraintRenames.filter(r => sameName(r.table, currentTable)), currentName);
+        return actualName === undefined ? undefined : table.namedConstraints?.find(c => sameName(c.name, actualName));
+    }
+    // --- Catalog-sourced bodies with the renames in force applied forward (Rule 2) ---
+    setMaintainedFrom(maintained, table) {
+        if (!maintained.select)
+            return this.cannotUndo(`the derivation of ${table}`, 'the pre-apply catalog carries no body for it');
+        const select = cloneQueryExpr(maintained.select);
+        this.replayRenames(select, undefined, {});
+        const stmt = {
+            type: 'alterTable',
+            table: this.schemaName !== 'main'
+                ? { type: 'identifier', name: table, schema: this.schemaName }
+                : { type: 'identifier', name: table },
+            action: { type: 'setMaintained', columns: maintained.columns, select },
+        };
+        return { undo: [astToString(stmt)] };
+    }
+    /** The pre-apply DEFAULT of a column, rendered: `null` when it had none, `undefined` when the column is unknown. */
+    priorDefaultText(table, column) {
+        const actual = this.columnNow(table, column);
+        if (!actual)
+            return undefined;
+        if (!actual.defaultValue)
+            return null;
+        const expr = cloneExpr(actual.defaultValue);
+        this.replayRenames(expr, table, { rowImageContext: true, schemaAuthoredBody: true });
+        return expressionToString(expr);
+    }
+    /**
+     * A clone of a pre-apply constraint body with the renames in force applied
+     * forward — the inverse of `reconciledDeclaredBody`, arm for arm: a CHECK's
+     * expression through the walkers (owning-table column renames seeded, other
+     * tables' by scope); a UNIQUE's column list; an FK's local list, its parent's
+     * column list under the parent's CURRENT name, then the parent name itself.
+     */
+    forwardRenamedConstraint(tc, owner) {
+        switch (tc.type) {
+            case 'check': {
+                const clone = { ...tc, expr: tc.expr ? cloneExpr(tc.expr) : undefined };
+                if (clone.expr)
+                    this.replayRenames(clone.expr, owner, { rowImageContext: true, schemaAuthoredBody: true });
+                return clone;
+            }
+            case 'unique': {
+                const clone = { ...tc, columns: tc.columns?.map(c => ({ ...c })) };
+                this.forwardRenameColumnList(clone.columns, owner);
+                return clone;
+            }
+            case 'foreignKey': {
+                const clone = {
+                    ...tc,
+                    columns: tc.columns?.map(c => ({ ...c })),
+                    foreignKey: tc.foreignKey
+                        ? { ...tc.foreignKey, columns: tc.foreignKey.columns ? [...tc.foreignKey.columns] : undefined }
+                        : tc.foreignKey,
+                };
+                this.forwardRenameColumnList(clone.columns, owner);
+                const fk = clone.foreignKey;
+                // Renames are within-schema, so a cross-schema parent is left alone.
+                if (fk && (!fk.schema || sameName(fk.schema, this.schemaName))) {
+                    const parentNow = this.tableNameNow(fk.table);
+                    if (fk.columns) {
+                        for (let i = 0; i < fk.columns.length; i++)
+                            fk.columns[i] = this.columnNameNow(parentNow, fk.columns[i]);
+                    }
+                    fk.table = parentNow;
+                }
+                return clone;
+            }
+            default:
+                return tc;
+        }
+    }
+    forwardRenameColumnList(columns, table) {
+        for (const col of columns ?? [])
+            col.name = this.columnNameNow(table, col.name);
+    }
+    /**
+     * Applies the renames in force to a body in place, in plan order: every table
+     * rename first (they are the plan's first steps), then each column rename as its
+     * step landed. Each call goes through the walker the live propagation uses for
+     * that body kind: a body OWNED by a table (a CHECK, a column default — `owner`
+     * set) takes the owning table's renames through the seeded CHECK walker in
+     * `'own'` row-image mode and other tables' renames through the plain scope walk
+     * in `'foreign'` mode; a free body (a view, assertion or derivation body, an
+     * index predicate) takes every rename through the plain walk in `'none'` mode.
+     * `tableOpts` is the body kind's `renameTableInAst` options, exactly as the
+     * matching `renameTableIn*` helper passes them.
+     */
+    replayRenames(node, owner, tableOpts) {
+        for (const r of this.tableRenames) {
+            renameTableInAst(node, {
+                oldName: r.oldName, newName: r.newName, schemaName: this.schemaName,
+                resolve: this.resolveRef, resolveAfter: this.resolveRef,
+            }, tableOpts);
+        }
+        this.columnRenames.forEach((r, replayedSoFar) => {
+            const targetKey = objectRefKey(this.schemaName, r.table);
+            const resolveColumn = this.columnResolverAfter(replayedSoFar);
+            if (owner !== undefined && sameName(r.table, owner)) {
+                renameColumnInCheckExpression(node, owner, r.oldName, r.newName, this.resolveRef, targetKey, 'own', resolveColumn);
+            }
+            else {
+                renameColumnInAst(node, r.table, r.oldName, r.newName, this.resolveRef, targetKey, owner !== undefined ? 'foreign' : 'none', resolveColumn);
+            }
+        });
+    }
+    /**
+     * Column-existence resolver for the scope-aware walks in {@link replayRenames}:
+     * "does this FROM source expose this column?" answered against the pre-apply
+     * catalog with the first `applied` column renames in force — the world the
+     * matching live rename statement ran in. Cross-schema sources and views answer
+     * false, as the differ's declared-side resolver does (conservative: worst case a
+     * ref that would have bound to an inner source is rewritten too).
+     */
+    columnResolverAfter(applied) {
+        const inForce = this.columnRenames.slice(0, applied);
+        return (schema, table, column) => {
+            if (schema !== this.schemaName.toLowerCase())
+                return false;
+            const actual = this.tableNow(table);
+            if (!actual)
+                return false;
+            const onTable = inForce.filter(r => sameName(r.table, table));
+            return actual.columns.some(c => sameName(onTable.find(r => sameName(r.oldName, c.name))?.newName ?? c.name, column));
+        };
+    }
+    cannotUndo(what, why) {
+        warnLog(`No undo for migration step ${what}: ${why}`);
+        return { irreversible: `${what} cannot be undone: ${why}` };
+    }
+}
+/** `<prefix> SET TAGS (<pre-apply tags>)`; an absent or empty set restores "no tags" as the explicit clear form. */
+function restoreTags(prefix, tags) {
+    return { undo: [`${prefix} SET TAGS ${tagsBodyToString(tags ? { ...tags } : undefined)}`] };
+}
+/** The name a create statement gives the object it makes, when it is a create of `kind`. */
+function createdObjectName(ast, kind) {
+    if (!ast)
+        return undefined;
+    switch (ast.type) {
+        case 'createTable': return kind === 'table' ? ast.table.name : undefined;
+        case 'createMaterializedView': return kind === 'table' ? ast.view.name : undefined;
+        case 'createView': return kind === 'view' ? ast.view.name : undefined;
+        case 'createIndex': return kind === 'index' ? ast.index.name : undefined;
+        case 'createAssertion': return kind === 'assertion' ? ast.name.name : undefined;
+        default: return undefined;
+    }
+}
+/** A parse that reports failure as data: the undo renderer must stay total over hand-built input. */
+function parseStatement(sql) {
+    try {
+        return { ok: true, stmt: new Parser().parse(sql) };
+    }
+    catch (e) {
+        return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+    }
+}
 //# sourceMappingURL=schema-differ.js.map