@quereus/quereus 4.3.2 → 4.4.1

package/dist/src/runtime/emit/alter-table.js

@@ -5,15 +5,18 @@ import { QuereusError } from '../../common/errors.js';
 import { StatusCode } from '../../common/types.js';
 import { createLogger } from '../../common/logger.js';
 import { buildColumnIndexMap, withGeneratedColumnGraph, requireVtabModule, resolveNamedConstraintClass, validateCollationForType } from '../../schema/table.js';
-import { validateForeignKeyOverExistingRows, validateForeignKeyCollations, extractColumnLevelCheckConstraints, extractColumnLevelForeignKeys, extractColumnLevelUniqueConstraints } from '../../schema/constraint-builder.js';
+import { validateForeignKeyCollations, buildForeignKeyConstraintSchema, extractColumnLevelCheckConstraints, extractColumnLevelForeignKeys, extractColumnLevelUniqueConstraints } from '../../schema/constraint-builder.js';
 import { MemoryTableModule } from '../../vtab/memory/module.js';
 import { quoteIdentifier, expressionToString, astToString } from '../../emit/ast-stringify.js';
 import { renameTableInAst, renameColumnInAst, renameColumnInCheckExpression } from '../../schema/rename-rewriter.js';
+import { assertCatalogObjectPersistable, assertRenameDependentsPersistable } from '../../schema/catalog-persistability.js';
 import { tryFoldLiteral } from '../../parser/utils.js';
 import { isTruthy } from '../../util/comparison.js';
 import { assertDdlTransactionPolicy } from './ddl-transaction-policy.js';
+import { validateAndParse } from '../../types/validation.js';
 import { snapshotStaleMaterializedViews, propagateTableRenameToMaterializedViews, propagateColumnRenameToMaterializedViews, restoreUnaffectedMaterializedViews, attachMaintainedDerivation, detachMaintainedDerivation, } from './materialized-view-helpers.js';
 import { isMaintainedTable } from '../../schema/derivation.js';
+import { inferType } from '../../types/registry.js';
 const log = createLogger('runtime:emit:alter-table');
 /** A scheduled sub-program resolved to a callback the emitter invokes per row. */
 function qualifyTableName(schemaName, tableName) {
@@ -156,6 +159,20 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
     if (schema.getTable(newName)) {
         throw new QuereusError(`Table '${newName}' already exists`, StatusCode.ERROR);
     }
+    // Pre-flight, BEFORE the first side effect (`module.renameTable`): every catalog
+    // entry this rename would rewrite must still be persistable. Both the rename
+    // propagation and the store's catalog write are unfailable (notifier try/catch,
+    // then an async persist queue), so without this the statement reports success and
+    // the dependent silently diverges from — or vanishes from — the durable catalog.
+    if (isMaintainedTable(tableSchema)) {
+        // The renamed table is itself a materialized view: its own catalog entry moves
+        // (`materialized_view_removed` old → `materialized_view_added` new), so vet the
+        // prospective record's new KEY and DDL text. The self-reference rewrite
+        // `rewriteTableForTableRename` performs is not applied to the probe — it only
+        // substitutes `newName`, which is already under test as the record's own name.
+        assertCatalogObjectPersistable(rctx.db, 'materializedView', { ...tableSchema, name: newName });
+    }
+    assertRenameDependentsPersistable(rctx.db, schema, ast => renameTableInAst(ast, oldName, newName, tableSchema.schemaName));
     // Clone schema with new name
     const updatedTableSchema = {
         ...tableSchema,
@@ -169,6 +186,18 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
     if (module.renameTable) {
         await module.renameTable(rctx.db, tableSchema.schemaName, oldName, newName);
     }
+    // Events this transaction already recorded still carry the OLD name; relabel them so
+    // the commit delivers every event under the name the table has at delivery. AFTER the
+    // module call (a module failure must leave the batch as untouched as the catalog, and
+    // the store's `ddlCommitPendingOps` flushes its queued events into our batch DURING
+    // that call — those must be in the batch before we walk it), BEFORE the catalog swap,
+    // matching where the other ALTER arms call `remapBatchedDataEvents`.
+    //
+    // NOTE: batched SCHEMA events are deliberately out of scope here. A schema event
+    // records a DDL operation, not current state — relabelling `objectName` without
+    // rewriting its `ddl` text would produce an incoherent instruction. How a rename
+    // crosses the wire to a peer is `fix/sync-schema-migrations-replicate-empty-ddl`.
+    rctx.db._getEventEmitter().renameBatchedEvents(tableSchema.schemaName, oldName, newName);
     // The renamed table's own definition can name itself: a self-referencing FK's
     // `referencedTable`, a table-qualified CHECK expression, a table-qualified
     // partial-index predicate. Rewrite those BEFORE the catalog swap and the notify
@@ -238,6 +267,16 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
     if (oldName.toLowerCase() !== newNameLower && tableSchema.columnIndexMap.has(newNameLower)) {
         throw new QuereusError(`Column '${newName}' already exists in table '${tableSchema.name}'`, StatusCode.ERROR);
     }
+    // Pre-flight, BEFORE the first side effect (`module.alterTable`): the rewritten
+    // body of every dependent view / materialized view must still be persistable —
+    // same unfailable-propagation reasoning as the table-rename arm above. Shares one
+    // resolver with `propagateColumnRename` so the two passes cannot drift apart in
+    // code; what makes them agree at RUNTIME (the resolver reads the LIVE catalog, and
+    // this probe runs pre-mutation while the propagation runs post-) is that
+    // `isTableInUnaliasedScope` skips the renamed table itself and probes only OTHER
+    // sources, whose column sets this rename does not touch.
+    const resolveColumnInSource = buildColumnSourceResolver(rctx.db);
+    assertRenameDependentsPersistable(rctx.db, schema, ast => renameColumnInAst(ast, tableSchema.name, oldName, newName, tableSchema.schemaName, resolveColumnInSource));
     const existingCol = tableSchema.columns[colIndex];
     // Build a ColumnDef AST for the renamed column (preserving type info)
     const newColumnDef = {
@@ -265,6 +304,12 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
             columnIndexMap: buildColumnIndexMap(updatedCols),
         };
     }
+    // A rename moves no value and changes no arity, so the batched events' row images are
+    // already right — but their `changedColumns` still names the OLD column. Re-derive it
+    // against the new names with an identity row map, so no delivered event names a column
+    // the table no longer has. (Modules that emit at commit from their own queue read the
+    // current schema then, so they need nothing here.)
+    await rctx.db._getEventEmitter().remapBatchedDataEvents(tableSchema.schemaName, tableSchema.name, (row) => row, updatedTableSchema.columns.map(c => c.name));
     // Update the schema catalog
     schema.addTable(updatedTableSchema);
     // Snapshot pre-statement MV staleness BEFORE the notify below: the notify's
@@ -281,7 +326,7 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
     });
     // Propagate the rename into dependent objects (CHECK / FK / partial-index
     // predicates in this and other tables, view and materialized-view bodies).
-    await propagateColumnRename(rctx, tableSchema.schemaName, tableSchema.name, oldName, newName, preStaleMvs);
+    await propagateColumnRename(rctx, tableSchema.schemaName, tableSchema.name, oldName, newName, preStaleMvs, resolveColumnInSource);
     log('Renamed column %s.%s.%s to %s', tableSchema.schemaName, tableSchema.name, oldName, newName);
     return null;
 }
@@ -299,6 +344,10 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
     // and, when it does not fold to a literal, compiled into `backfill` — the default
     // evaluated against the existing row, so `new.<column>` reads that row's sibling.
     const defaultConstraint = columnDef.constraints?.find(c => c.type === 'default');
+    // Folded literal default; undefined when there is no default or it does not fold
+    // (the latter carries `backfill` instead). Used by the NOT NULL gate below and by
+    // the batched-event remap's backfill value.
+    const foldedDefault = defaultConstraint?.expr ? tryFoldLiteral(defaultConstraint.expr) : undefined;
     // Call module.alterTable for data + schema update
     const module = requireVtabModule(tableSchema);
     if (!module.alterTable) {
@@ -318,19 +367,28 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
     const delegatesBackfill = module.getCapabilities?.().delegatesNotNullBackfill === true;
     const hasNotNull = columnDef.constraints?.some(c => c.type === 'notNull') ?? false;
     if (hasNotNull && !delegatesBackfill && !backfill) {
-        const folded = defaultConstraint?.expr ? tryFoldLiteral(defaultConstraint.expr) : undefined;
-        const defaultIsNullish = !defaultConstraint?.expr || folded === null;
+        const defaultIsNullish = !defaultConstraint?.expr || foldedDefault === null;
         if (defaultIsNullish) {
             await validateNotNullBackfill(rctx, tableSchema, columnDef.name);
         }
     }
-    // Extract column-level CHECK / FK constraints to merge into the engine-side schema below.
-    // Column-level UNIQUE is handled separately, right after the column is materialized (see
-    // the inline-UNIQUE block below): it routes through the module's `addConstraint` UNIQUE
-    // path — the same path `ALTER TABLE ADD CONSTRAINT … UNIQUE` uses — so it is materialized,
-    // enforced, and (for store-backed modules) persisted, symmetric with CREATE TABLE.
-    const newCheckConstraints = extractColumnLevelCheckConstraints(columnDef);
-    const newForeignKeys = extractColumnLevelForeignKeys(columnDef, tableSchema.schemaName);
+    // Synthesize the table-level equivalent of every constraint declared inline on the new
+    // column. All three kinds go to the module via `addConstraint` below — the same path
+    // `ALTER TABLE ADD CONSTRAINT` uses — so the module owns them exactly as it owns a
+    // constraint declared in CREATE TABLE, and they survive every later structural ALTER
+    // (which installs the module's returned schema in the catalog verbatim).
+    //
+    // Extracted BEFORE the column is materialized so a malformed declaration (e.g. a
+    // multi-parent-column FK on a single ADD COLUMN) throws while the table is still
+    // untouched. Install order within the loop is UNIQUE → CHECK → FK, so a column
+    // declaring several kinds reports the cheapest-to-explain violation first; the
+    // literal-default CHECK scan runs ahead of the whole loop (see below).
+    const inlineChecks = extractColumnLevelCheckConstraints(columnDef);
+    const inlineConstraints = [
+        ...extractColumnLevelUniqueConstraints(columnDef),
+        ...inlineChecks,
+        ...extractColumnLevelForeignKeys(columnDef),
+    ];
     // A non-foldable default backfills each existing row from its own value. Install a row
     // slot over the default's row descriptor; the evaluator the module calls per existing
     // row sets the slot to that row, so the default's `new.<col>` refs resolve to it.
@@ -369,185 +427,226 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
     // scan below re-reads the table — so the backfill's context does not shadow the
     // scan's own row context.
     let updatedTableSchema;
+    // Slot the module actually placed the new column at (the module API permits
+    // `insertAtIndex`; SQL always appends). Recorded so the revert paths below can apply
+    // the inverse event remap.
+    let addedColIndex;
     try {
         updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
             type: 'addColumn',
             columnDef,
             backfillEvaluator,
         });
+        // Events this transaction already batched for the table still describe the
+        // pre-ADD column set; insert the backfilled value at the new slot so a listener
+        // at commit pairs value i with column i of the schema current at delivery.
+        // Covers the engine auto-event path and the store module (which flushed its
+        // queued events into the batch during the ALTER); the memory module's own
+        // pending-change log is reshaped inside its alterTable. Must run INSIDE this
+        // try: the backfill evaluator closes over rowSlot/checkSlot, which the finally
+        // below closes the moment the module returns.
+        addedColIndex = updatedTableSchema.columnIndexMap.get(columnDef.name.toLowerCase());
+        if (addedColIndex !== undefined) {
+            const insertAt = addedColIndex;
+            await rctx.db._getEventEmitter().remapBatchedDataEvents(tableSchema.schemaName, tableSchema.name, async (row) => {
+                // oldRow gets the SAME map as newRow: the literal default, or the backfill
+                // evaluator applied to the pre-image itself (the evaluator is a function of
+                // a row, and the pre-image is a row), falling back to NULL — the honest
+                // "column did not exist yet" placeholder, which errs toward REPORTING a
+                // change on the new column rather than suppressing one. Rejected: reusing
+                // the newRow result for oldRow (makes oldRow[new] === newRow[new] always,
+                // so a diffing consumer never syncs the added column); suppressing the
+                // pre-ALTER oldRow (silently turns updates into upserts).
+                let value = foldedDefault ?? null;
+                if (backfillEvaluator) {
+                    try {
+                        value = await backfillEvaluator(row);
+                    }
+                    catch {
+                        // Best-effort: a historical image may fail the evaluator (or its
+                        // CHECKs) where every live row backfilled cleanly. Never abort
+                        // the ALTER for an event image.
+                        value = null;
+                    }
+                }
+                return [...row.slice(0, insertAt), value, ...row.slice(insertAt)];
+            }, updatedTableSchema.columns.map(c => c.name));
+        }
     }
     finally {
         rowSlot?.close();
         checkSlot?.close();
     }
-    // Materialize + enforce any inline column-level UNIQUE(s) on the new column. CREATE TABLE
-    // routes inline UNIQUE through `extractUniqueConstraints`; `ALTER TABLE ADD CONSTRAINT …
-    // UNIQUE` routes it through `module.alterTable({ addConstraint })`. The imperative ADD
-    // COLUMN path reaches neither, so without this an inline UNIQUE would be silently dropped —
-    // never materialized, enforced, or rejected. Convert each into the equivalent table-level
-    // constraint over the just-added column and feed it to the same addConstraint path, so the
-    // module builds/reuses its covering structure, validates the existing rows (throwing
-    // CONSTRAINT on the first duplicate), and (store) persists. Each call returns a schema
-    // carrying the new column + the unique constraint (+ memory covering index); thread the
-    // latest forward so the CHECK/FK merge below layers naturally on top.
-    //
-    // Ordering: the column is already materialized (so it resolves in `columnIndexMap`), and the
-    // engine catalog is untouched until the first `schema.addTable` below. So on a UNIQUE failure
-    // (e.g. a literal DEFAULT that backfills the same value to ≥2 existing rows → immediate
-    // duplicate) we only drop the just-added column from the module and rethrow — no catalog
-    // restore. The module's own addConstraint already rolled back its half-built covering
-    // structure before throwing.
-    const inlineUniqueConstraints = extractColumnLevelUniqueConstraints(columnDef);
-    for (const uniqueConstraint of inlineUniqueConstraints) {
-        try {
-            updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
-                type: 'addConstraint',
-                constraint: uniqueConstraint,
-            });
-        }
-        catch (err) {
-            try {
-                await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
-                    type: 'dropColumn',
-                    columnName: columnDef.name,
-                });
-            }
-            catch (revertErr) {
-                log('Failed to revert ADD COLUMN after inline UNIQUE violation: %s', revertErr.message);
-            }
-            throw err;
-        }
-    }
-    // Resolve the new child column index in the freshly returned schema for any FK constraints.
-    const newColIdx = updatedTableSchema.columnIndexMap.get(columnDef.name.toLowerCase());
-    const resolvedForeignKeys = newColIdx !== undefined
-        ? newForeignKeys.map(fk => ({ ...fk, columns: Object.freeze([newColIdx]) }))
-        : newForeignKeys;
-    // Merge new column-level CHECK / FK into the table-level constraint sets so the
-    // existing constraint-builder picks them up for INSERT/UPDATE enforcement.
-    const mergedChecks = newCheckConstraints.length > 0
-        ? Object.freeze([...updatedTableSchema.checkConstraints, ...newCheckConstraints])
-        : updatedTableSchema.checkConstraints;
-    const mergedForeignKeys = resolvedForeignKeys.length > 0
-        ? Object.freeze([...(updatedTableSchema.foreignKeys ?? []), ...resolvedForeignKeys])
-        : updatedTableSchema.foreignKeys;
-    const enhancedBase = {
-        ...updatedTableSchema,
-        checkConstraints: mergedChecks,
-        foreignKeys: mergedForeignKeys,
-    };
-    // Recompute the generated-column dependency graph. If the added column is
-    // generated and its expression references an unknown column, or any new
-    // generated-column edges form a cycle, this throws before we register the
-    // new schema in the catalog.
-    const enhancedTableSchema = withGeneratedColumnGraph(enhancedBase);
-    // The optimizer trusts a DECLARED constraint as a proven invariant, which makes
-    // the existing-row validators below fold away their own work if the new constraint
-    // is already live:
-    //   - A new FK seeds an inclusion dependency `child.fk ⊆ parent.pk`; the FK
-    //     validator's `not exists` anti-join folds to EmptyRelation under
-    //     `ruleAntiJoinFkEmpty` (+ the INDs seeded at TableReferenceNode).
-    //   - A new CHECK `<p>` seeds a domain constraint on the scan; the CHECK post-scan's
-    //     own `where not (<p>)` folds to EmptyRelation under `ruleFilterContradiction`
-    //     (the domain `<p>` and the predicate `not <p>` are jointly unsatisfiable).
-    // Either fold makes validation trust the very invariant it is checking and silently
-    // admit a violating row. So register the new COLUMN with only the PRE-EXISTING
-    // (already-proven) constraints for the validation pass, then register the full schema
-    // — with the new FK(s) and CHECK(s) — only once validation passes. This mirrors the
-    // ADD CONSTRAINT path, which validates before swapping the constraint into the live
-    // schema. Pre-existing constraints are kept: they held before this ALTER, so folding
-    // against them is sound and preserves the optimizer's reach.
-    const hasNewForeignKeys = resolvedForeignKeys.length > 0;
-    const hasNewChecks = newCheckConstraints.length > 0;
-    const usesIntermediateSchema = hasNewForeignKeys || hasNewChecks;
-    const validationSchema = usesIntermediateSchema
-        ? withGeneratedColumnGraph({
-            ...enhancedBase,
-            checkConstraints: updatedTableSchema.checkConstraints,
-            foreignKeys: updatedTableSchema.foreignKeys,
-        })
-        : enhancedTableSchema;
-    schema.addTable(validationSchema);
-    // Validate new CHECK constraints against the (already-backfilled) rows AND validate
-    // existing rows against any new column-level FK, reverting (drop the column + restore
-    // the original catalog entry) on a violation. Both run inside a single try/revert
-    // region so that when both a new CHECK and a new FK exist and either fails, the same
-    // revert path fires.
-    //
-    // CHECK is gated on `!backfill`: NOT NULL of a per-row default is enforced by the module
-    // during backfill (it has the values in-hand and throws before the column is committed),
-    // and the per-row (evaluator) default path already enforced each CHECK inside the backfill
-    // hook above (against the freshly-computed value, not a stale snapshot). The CHECK post-scan
-    // is therefore only correct for the literal-default path, whose values were bulk-written by
-    // the module without a per-row hook.
-    //
-    // FK runs for ALL default kinds. It is a cross-table existence check, not a per-row
-    // predicate, so it must be a post-`alterTable` scan: the scan sees both the bulk-written
-    // (literal) and per-row-evaluated backfilled values, and for a self-referential FK it reads
-    // a consistent post-alter table (a per-row hook would have to query the very table being
-    // rebuilt). It reuses `validateForeignKeyOverExistingRows` — the same MATCH-SIMPLE,
-    // pragma-gated validator the ADD CONSTRAINT path calls — so the two paths can never drift.
-    const runCheckScan = !backfill && newCheckConstraints.length > 0;
-    if (runCheckScan || hasNewForeignKeys) {
-        try {
-            // Reject any new FK whose child/parent column collations declare a same-rank
-            // conflict (the conflict enforcement would raise at first DML). Pure schema
-            // check — no row scan, pragma-independent — but kept inside this try/revert
-            // region so a conflict drops the just-materialized column and restores the
-            // original catalog, leaving the table untouched. `enhancedTableSchema` carries
-            // the new column so the child FK column resolves.
-            for (const fk of resolvedForeignKeys) {
-                validateForeignKeyCollations(rctx.db, enhancedTableSchema, fk);
-            }
-            if (runCheckScan) {
-                await validateBackfillAgainstChecks(rctx, validationSchema, newCheckConstraints);
-            }
-            for (const fk of resolvedForeignKeys) {
-                // `enhancedTableSchema` supplies only column-name resolution here; the LIVE
-                // schema the planner reads is `validationSchema`, which omits the new FK(s)
-                // and CHECK(s), so the anti-join is not folded.
-                await validateForeignKeyOverExistingRows(rctx.db, enhancedTableSchema, fk);
-            }
+    // The column is materialized; now install the inline constraints. Names of the CHECK /
+    // FK ones the module has accepted so far, so a later failure can hand each back to
+    // `dropConstraint` before the column itself goes (see {@link revertAddColumn}).
+    const installedConstraintNames = [];
+    let finalTableSchema;
+    try {
+        // Recompute the generated-column dependency graph. If the added column is generated
+        // and its expression references an unknown column, or any new generated-column edges
+        // form a cycle, this throws — and the revert below undoes the materialization.
+        const columnOnlySchema = withGeneratedColumnGraph(updatedTableSchema);
+        // Register the COLUMN-ONLY schema before installing any inline constraint. Two
+        // properties depend on this ordering, and both are easy to break:
+        //
+        //  - The module's FK arm validates existing rows with SQL planned against the LIVE
+        //    catalog, so the new column has to resolve there. Likewise the CHECK backfill
+        //    scan below.
+        //  - The new constraint must NOT be live while its own validation runs. The optimizer
+        //    trusts a DECLARED constraint as a proven invariant: a declared FK seeds the
+        //    inclusion dependency `child.fk ⊆ parent.pk` and folds the validator's own
+        //    `not exists` anti-join to EmptyRelation (`ruleAntiJoinFkEmpty`); a declared CHECK
+        //    `<p>` seeds a domain constraint that folds the CHECK scan's `where not (<p>)`
+        //    away (`ruleFilterContradiction`). Either fold makes validation trust the very
+        //    thing it is checking and silently admit a violating row. The module holds each
+        //    new constraint in its own cached schema until that constraint's validation
+        //    passes, and the catalog only learns of them from `finalTableSchema` below.
+        //
+        // Pre-existing constraints stay live throughout: they held before this ALTER, so
+        // folding against them is sound and preserves the optimizer's reach.
+        schema.addTable(columnOnlySchema);
+        // Validate the backfilled values against each inline CHECK, for the literal-default
+        // path only. A per-row (evaluator) default already enforced its CHECKs inside the
+        // backfill hook above — against the freshly-computed value rather than this scan's
+        // stale pre-backfill snapshot — and the module enforces NOT NULL there too. Runs
+        // before the whole install loop below, so on a column declaring several kinds a
+        // CHECK violation is reported ahead of a UNIQUE or FK one.
+        if (!backfill && inlineChecks.length > 0) {
+            await validateBackfillAgainstChecks(rctx, columnOnlySchema, inlineChecks);
         }
-        catch (err) {
-            // Revert: drop the column and restore the original catalog entry.
-            try {
-                await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
-                    type: 'dropColumn',
-                    columnName: columnDef.name,
-                });
+        // Starts as the column-only schema so a column with no inline constraint needs no
+        // further work; each accepted constraint replaces it with the module's answer.
+        //
+        // NOTE: one module round-trip per inline constraint — each takes the module's
+        // schema-change latch and, store-backed, writes the table's DDL again. Fine at the
+        // counts SQL produces (a column declares 0 or 1 of each kind); if a batched
+        // `addConstraint` arm ever appears, or ADD COLUMN becomes hot, hand the whole set
+        // over in one call instead.
+        let current = columnOnlySchema;
+        for (const constraint of inlineConstraints) {
+            // A CHECK / FK is dropped by NAME on the revert path, so resolve the name the
+            // module will store BEFORE handing the constraint over. UNIQUE needs no entry:
+            // an unnamed one has no name to drop by, and the module's own DROP COLUMN
+            // prunes a UNIQUE over the dropped column (which CHECK / FK are not).
+            let installedName;
+            if (constraint.type === 'foreignKey') {
+                // Reject a same-rank child/parent collation conflict (which enforcement would
+                // raise at the first DML) BEFORE `module.alterTable`, so a rejected ALTER never
+                // reaches the module's persistence side effects — mirroring
+                // `runAddConstraintViaModule`. Built with the same builder and columnIndexMap
+                // the module uses, so the name and column indices are identical to its own.
+                const fk = buildForeignKeyConstraintSchema(constraint, columnOnlySchema.columnIndexMap, tableSchema.name, tableSchema.schemaName);
+                validateForeignKeyCollations(rctx.db, columnOnlySchema, fk);
+                installedName = fk.name;
             }
-            catch (revertErr) {
-                log('Failed to revert ADD COLUMN after constraint violation: %s', revertErr.message);
+            else if (constraint.type === 'check') {
+                installedName = constraint.name; // always set by the extractor
             }
-            schema.addTable(tableSchema);
-            throw err;
+            // The module materializes (UNIQUE's covering structure), validates the existing
+            // rows as the kind requires (UNIQUE duplicates, pragma-gated MATCH SIMPLE FK
+            // orphans) and — store-backed — persists. Thread the returned schema forward so
+            // each constraint layers on the last. The module's answer carries no
+            // generated-column bookkeeping of its own, so re-derive it each round.
+            const withConstraint = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
+                type: 'addConstraint',
+                constraint,
+            });
+            current = withGeneratedColumnGraph(withConstraint);
+            if (installedName !== undefined)
+                installedConstraintNames.push(installedName);
         }
+        finalTableSchema = current;
     }
-    // Validation passed — commit the full schema (with the new FK(s)/CHECK(s)) into the
-    // catalog. Skipped when no intermediate schema was used, in which case
-    // `validationSchema === enhancedTableSchema` is already registered.
-    if (usesIntermediateSchema) {
-        schema.addTable(enhancedTableSchema);
+    catch (err) {
+        await revertAddColumn(rctx, tableSchema, schema, columnDef.name, addedColIndex, installedConstraintNames);
+        throw err;
     }
+    // Every constraint validated and installed — publish the module's final schema.
+    schema.addTable(finalTableSchema);
     rctx.db.schemaManager.getChangeNotifier().notifyChange({
         type: 'table_modified',
         schemaName: tableSchema.schemaName,
         objectName: tableSchema.name,
         oldObject: tableSchema,
-        newObject: enhancedTableSchema,
+        newObject: finalTableSchema,
     });
     log('Added column %s to table %s.%s', columnDef.name, tableSchema.schemaName, tableSchema.name);
     return null;
 }
 /**
- * Runs each new CHECK against existing rows. We rely on the just-registered
- * enhanced schema so SQL can resolve the new column. Any row matching
+ * Undoes a partially-applied ADD COLUMN, leaving the table exactly as it was: hands each
+ * inline CHECK / FK the module already accepted back to `dropConstraint` (newest first),
+ * drops the column, un-remaps the batched events, and restores the original catalog entry.
+ *
+ * The constraints must go before the column: neither built-in module prunes a CHECK / FK
+ * over a dropped column, so a stranded one would keep naming a column the table no longer
+ * has. (An inline UNIQUE needs no explicit drop — both modules prune a UNIQUE over the
+ * dropped column, and an unnamed one has no name to drop by.)
+ *
+ * Best-effort on the module half: a revert failure is logged, never thrown, so it cannot
+ * mask the original violation. Restoring the catalog entry is a no-op when the ALTER failed
+ * before registering anything (the original schema is still the live one).
+ *
+ * NOTE: the hand-back is by NAME, so it assumes a name resolves to the constraint this
+ * ALTER installed. A pre-existing constraint can legitimately share an auto-name (nothing
+ * rejects `constraint _check_w check (…)` on a table that later gets `add column w …
+ * check (…)`; `create table` collides the same way), and today both modules' DROP
+ * CONSTRAINT removes every match, which lands on the right end state. If constraint-name
+ * resolution ever narrows to a single match, revert must instead identify the installed
+ * constraint by identity — otherwise it can drop the pre-existing one and leave ours.
+ */
+async function revertAddColumn(rctx, tableSchema, schema, columnName, addedColIndex, installedConstraintNames) {
+    try {
+        const module = requireVtabModule(tableSchema);
+        // Unreachable: runAddColumn requires `alterTable` before materializing anything.
+        if (!module.alterTable)
+            return;
+        for (let i = installedConstraintNames.length - 1; i >= 0; i--) {
+            await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
+                type: 'dropConstraint',
+                constraintName: installedConstraintNames[i],
+            });
+        }
+        await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
+            type: 'dropColumn',
+            columnName,
+        });
+        await remapEventsForRevertedAddColumn(rctx, tableSchema, addedColIndex);
+    }
+    catch (revertErr) {
+        log('Failed to revert ADD COLUMN %s.%s.%s: %s', tableSchema.schemaName, tableSchema.name, columnName, revertErr.message);
+    }
+    schema.addTable(tableSchema);
+}
+/**
+ * Inverse of {@link runAddColumn}'s batched-event remap, for its revert paths: the
+ * just-added column has been dropped from the module again, so the batched events must
+ * drop the slot too or they keep describing a column the table no longer has. No-op when
+ * the forward remap never ran (`addedColIndex` undefined). Best-effort like the forward
+ * remap — never masks the original constraint error.
+ */
+async function remapEventsForRevertedAddColumn(rctx, tableSchema, addedColIndex) {
+    if (addedColIndex === undefined)
+        return;
+    await rctx.db._getEventEmitter().remapBatchedDataEvents(tableSchema.schemaName, tableSchema.name, (row) => row.filter((_, i) => i !== addedColIndex), tableSchema.columns.map(c => c.name));
+}
+/**
+ * Runs each new CHECK against the (already-backfilled) existing rows. Relies on the
+ * just-registered column-only schema so SQL can resolve the new column while the CHECK
+ * itself is not yet declared — declaring it first would let `ruleFilterContradiction`
+ * fold this scan's own `not (<check_expr>)` to EmptyRelation. Any row matching
  * `not (<check_expr>)` is a violation and aborts the ALTER.
  */
-async function validateBackfillAgainstChecks(rctx, enhancedTableSchema, newCheckConstraints) {
-    const qualifiedTable = qualifyTableName(enhancedTableSchema.schemaName, enhancedTableSchema.name);
+async function validateBackfillAgainstChecks(rctx, columnOnlySchema, newCheckConstraints) {
+    const qualifiedTable = qualifyTableName(columnOnlySchema.schemaName, columnOnlySchema.name);
     for (const cc of newCheckConstraints) {
+        // `extractColumnLevelCheckConstraints` skips an expression-less CHECK, so this
+        // cannot fire — but silently skipping a constraint we were asked to validate
+        // would admit a violating row, so say so loudly rather than `continue`.
+        if (!cc.expr) {
+            throw new QuereusError(`CHECK constraint ${cc.name ? `'${cc.name}' ` : ''}on ALTER TABLE ADD COLUMN has no expression`, StatusCode.INTERNAL);
+        }
         const checkSql = expressionToString(cc.expr);
         const sql = `select 1 from ${qualifiedTable} where not (${checkSql}) limit 1`;
         const stmt = rctx.db.prepare(sql);
@@ -558,7 +657,7 @@ async function validateBackfillAgainstChecks(rctx, enhancedTableSchema, newCheck
                 break;
             }
             if (violated) {
-                throw new QuereusError(`CHECK constraint ${cc.name ? `'${cc.name}' ` : ''}violated by backfilled rows in ALTER TABLE ADD COLUMN on '${enhancedTableSchema.name}'`, StatusCode.CONSTRAINT);
+                throw new QuereusError(`CHECK constraint ${cc.name ? `'${cc.name}' ` : ''}violated by backfilled rows in ALTER TABLE ADD COLUMN on '${columnOnlySchema.name}'`, StatusCode.CONSTRAINT);
             }
         }
         finally {
@@ -668,6 +767,13 @@ async function runDropColumn(rctx, tableSchema, schema, columnName) {
         type: 'dropColumn',
         columnName,
     });
+    // Events this transaction already batched for the table still carry the pre-drop
+    // arity; drop the slot so a listener at commit pairs value i with column i of the
+    // schema current at delivery (and `changedColumns` never names the dropped column).
+    // Pure slot filter — no failure mode. Covers the engine auto-event path and the
+    // store module (which flushed its queued events into the batch during the ALTER);
+    // the memory module's own pending-change log is reshaped inside its alterTable.
+    await rctx.db._getEventEmitter().remapBatchedDataEvents(tableSchema.schemaName, tableSchema.name, (row) => row.filter((_, i) => i !== colIndex), updatedTableSchema.columns.map(c => c.name));
     // Recompute the generated-column dependency graph against the post-drop
     // column array — old indices in the previous map are invalid.
     const finalSchema = withGeneratedColumnGraph(updatedTableSchema);
@@ -803,6 +909,16 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
     if (action.setCollation !== undefined) {
         validateCollationForType(action.setCollation, tableSchema.columns[colIndex].logicalType, action.columnName, (n) => rctx.db.isCollationRegistered(n));
     }
+    // SET DATA TYPE: the column keeps its current collation, so the NEW type has to accept it —
+    // otherwise the ALTER mints a column shape CREATE TABLE would refuse and generateTableDDL
+    // cannot round-trip (a store-backed table with such a column is silently dropped on rehydrate).
+    // Same validator, same error text as CREATE TABLE / SET COLLATE. Rejects uniformly whether the
+    // collation was user-declared or inherited from `pragma default_collation`: `collationExplicit`
+    // is not persisted, so keying on it would coerce before a reopen and reject after one.
+    // Remedy: `SET COLLATE binary` first, then retype.
+    if (action.setDataType !== undefined) {
+        validateCollationForType(tableSchema.columns[colIndex].collation, inferType(action.setDataType), action.columnName, (n) => rctx.db.isCollationRegistered(n));
+    }
     // Route a SET DEFAULT through the same DDL validator CREATE TABLE uses, so the
     // stored default is consistent with what INSERT will accept: bind params / bare
     // columns / non-determinism rejected, `new.<column>` accepted (deferred to INSERT
@@ -823,6 +939,18 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
         setDefault: action.setDefault,
         setCollation: action.setCollation,
     });
+    // Events this transaction already batched still carry the PRE-conversion value at
+    // the altered column (`SET DATA TYPE`'s normalization, `SET NOT NULL`'s null →
+    // DEFAULT backfill); rewrite it so a listener at commit sees the value the
+    // committed row holds. The conversion is engine-derivable (the same
+    // `validateAndParse` the memory module's converter wraps), so no module-contract
+    // change. `SET COLLATE` / `SET DEFAULT` / `DROP NOT NULL` move no stored value and
+    // need no remap — in particular the primary-key `SET COLLATE` re-key leaves every
+    // event's key and row images valid as-is.
+    const eventValueRemap = alterColumnEventValueRemap(tableSchema, colIndex, action);
+    if (eventValueRemap) {
+        await rctx.db._getEventEmitter().remapBatchedDataEvents(tableSchema.schemaName, tableSchema.name, (row) => row.map((v, i) => i === colIndex ? eventValueRemap(v) : v), updatedTableSchema.columns.map(c => c.name));
+    }
     schema.addTable(updatedTableSchema);
     rctx.db.schemaManager.getChangeNotifier().notifyChange({
         type: 'table_modified',
@@ -834,6 +962,51 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
     log('Altered column %s.%s.%s', tableSchema.schemaName, tableSchema.name, action.columnName);
     return null;
 }
+/**
+ * The per-value map {@link runAlterColumn}'s batched-event remap applies at the altered
+ * column, or undefined when the ALTER moves no stored value (SET COLLATE, SET DEFAULT,
+ * DROP NOT NULL, an alias retype). The returned function is TOTAL — an unconvertible
+ * historical event image keeps its raw value rather than aborting the ALTER; the module
+ * already validated every value the transaction can actually SEE, so a failure here is
+ * confined to a superseded intermediate image.
+ */
+function alterColumnEventValueRemap(tableSchema, colIndex, action) {
+    if (action.setDataType !== undefined) {
+        const newLogicalType = inferType(action.setDataType);
+        // Alias retype (`varchar(50)` IS TEXT): schema-only, values untouched.
+        if (newLogicalType === tableSchema.columns[colIndex].logicalType)
+            return undefined;
+        const columnName = tableSchema.columns[colIndex].name;
+        return (v) => {
+            if (v === null)
+                return v; // retype leaves NULLs untouched, matching the module's conversion
+            try {
+                return validateAndParse(v, newLogicalType, columnName);
+            }
+            catch {
+                // NOTE: the surviving raw value is honest about what the row held, but its
+                // JS type no longer matches the column's logical type — the delivered
+                // contract is positional (value i belongs to column i), not typed. Only
+                // reachable for a superseded intermediate image (e.g. insert 'zzz' →
+                // update to '42' → retype to integer delivers oldRow ['zzz']). If a
+                // consumer ever type-validates delivered images, revisit: the options are
+                // NULL (loses the value) or dropping the image (loses the event).
+                return v;
+            }
+        };
+    }
+    if (action.setNotNull === true) {
+        // SET NOT NULL backfill: null → the folded literal DEFAULT, the same map the
+        // module applies. No usable literal default means the module either found no
+        // NULLs (nothing to remap) or rejected the ALTER before reaching here.
+        const defaultExpr = tableSchema.columns[colIndex].defaultValue;
+        const folded = defaultExpr ? tryFoldLiteral(defaultExpr) : undefined;
+        if (folded === undefined || folded === null)
+            return undefined;
+        return (v) => (v === null ? folded : v);
+    }
+    return undefined;
+}
 /**
  * Catalog-only metadata-tag mutations. Tags touch no stored row and no physical
  * layout, so these never call `module.alterTable` — they delegate to the
@@ -1295,13 +1468,23 @@ function rewriteTableForTableRename(table, renamedSchemaLower, oldName, newName)
         indexes: table.indexes ? Object.freeze(newIndexes) : table.indexes,
     });
 }
-async function propagateColumnRename(rctx, renamedSchemaName, tableName, oldCol, newCol, preStaleMvs) {
-    const schemaManager = rctx.db.schemaManager;
-    const resolveColumnInSource = (s, t, col) => {
-        const targetSchema = schemaManager.getSchema(s);
+/**
+ * The catalog-backed {@link ResolveColumnInSource} the column-rename rewriters consult
+ * to keep their unqualified-reference walk scope-aware. Built once per statement and
+ * shared by the pre-flight probe in {@link runRenameColumn} and the real propagation
+ * below, so the two cannot drift apart. Note it resolves against the LIVE catalog on
+ * every call, so sharing it does not by itself freeze the answer between the two passes
+ * — see the pre-flight's comment for why they agree anyway.
+ */
+function buildColumnSourceResolver(db) {
+    return (s, t, col) => {
+        const targetSchema = db.schemaManager.getSchema(s);
         const targetTable = targetSchema?.getTable(t);
         return targetTable?.columnIndexMap.has(col.toLowerCase()) ?? false;
     };
+}
+async function propagateColumnRename(rctx, renamedSchemaName, tableName, oldCol, newCol, preStaleMvs, resolveColumnInSource) {
+    const schemaManager = rctx.db.schemaManager;
     for (const schema of schemaManager._getAllSchemas()) {
         await propagateColumnRenameInSchema(rctx.db, schema, renamedSchemaName, tableName, oldCol, newCol, resolveColumnInSource, preStaleMvs);
     }