@quereus/quereus 4.4.1 → 4.6.0

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

@@ -4,20 +4,21 @@ import { createRowSlot } from '../context-helpers.js';
 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 { buildColumnIndexMap, withGeneratedColumnGraph, requireVtabModule, resolveNamedConstraintClass, namedConstraintExists, assertConstraintNameFree, validateCollationForType, columnDefToSchema } from '../../schema/table.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 { assertUniqueConstraintIndexNameFree, assertUniqueConstraintNotDuplicated, uniqueConstraintColumnSetKey } from '../../schema/catalog.js';
 import { isTruthy } from '../../util/comparison.js';
-import { assertDdlTransactionPolicy } from './ddl-transaction-policy.js';
-import { validateAndParse } from '../../types/validation.js';
+import { assertDdlTransactionPolicy, isExplicitTransactionOpen } from './ddl-transaction-policy.js';
+import { emitAlterSchemaEvent } from './alter-schema-event.js';
+import { foldDefaultToType, 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');
+const warnLog = log.extend('warn');
 /** A scheduled sub-program resolved to a callback the emitter invokes per row. */
 function qualifyTableName(schemaName, tableName) {
     const prefix = (schemaName && schemaName.toLowerCase() !== 'main')
@@ -28,12 +29,13 @@ function qualifyTableName(schemaName, tableName) {
 export function emitAlterTable(plan, ctx) {
     const tableSchema = plan.table.tableSchema;
     const action = plan.action;
-    // An ADD COLUMN with a non-foldable DEFAULT carries a backfill scalar; emit it as a
-    // scheduled sub-program so the scheduler resolves it into a callback the run() body
-    // evaluates per existing row (via a row slot over the default's row descriptor). When the
-    // new column also carries a CHECK, its predicates ride alongside as further callbacks,
-    // evaluated per backfilled row against `[...existingRow, backfilledValue]`. Slot order is
-    // fixed: backfill first (present whenever checks are), then the checks in order.
+    // An ADD COLUMN with a per-row value source — a non-foldable DEFAULT, or a GENERATED
+    // ALWAYS AS expression — carries a backfill scalar; emit it as a scheduled sub-program
+    // so the scheduler resolves it into a callback the run() body evaluates per existing row
+    // (via a row slot over the backfill's row descriptor). When the new column also carries a
+    // CHECK, its predicates ride alongside as further callbacks, evaluated per backfilled row
+    // against `[...existingRow, backfilledValue]`. Slot order is fixed: backfill first
+    // (present whenever checks are), then the checks in order.
     const backfill = action.type === 'addColumn' ? action.backfill : undefined;
     const checks = action.type === 'addColumn' ? action.checks : undefined;
     const params = [
@@ -172,7 +174,7 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
         // 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));
+    assertRenameDependentsPersistable(rctx.db, schema, ast => renameTableInAst(ast, oldName, newName, tableSchema.schemaName), t => rewriteTableForTableRename(t, tableSchema.schemaName.toLowerCase(), oldName, newName));
     // Clone schema with new name
     const updatedTableSchema = {
         ...tableSchema,
@@ -198,6 +200,12 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
     // 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);
+    // Deferred constraint checks this transaction already parked carry evaluators compiled
+    // against the OLD name — their scan leaves would connect to a table that no longer
+    // exists (or, on a store backend, to an empty one, yielding a FALSE violation). Tell
+    // the queue so it re-points those entries and moves the bucket keyed by the table name.
+    // Same placement rationale as the event relabel above.
+    rctx.db.getDeferredConstraints().notifyTableRename(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
@@ -255,6 +263,11 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
     // names a vanished table. A module whose `renameTable` already did all its work (or
     // that keeps no per-name catalog) simply omits the hook.
     await module.finalizeRename?.(rctx.db, tableSchema.schemaName, oldName, newName);
+    // The public schema-change event, for a module with no emitter of its own — see
+    // {@link emitAlterSchemaEvent} for why every arm emits at its tail rather than
+    // alongside the module call. Names only the NEW table: `DatabaseSchemaChangeEvent`
+    // has no old-object-name field, and the emitting backends have the identical gap.
+    emitAlterSchemaEvent(rctx, tableSchema, { type: 'alter', objectType: 'table', objectName: newName });
     log('Renamed table %s.%s to %s', tableSchema.schemaName, oldName, newName);
     return null;
 }
@@ -268,7 +281,9 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
         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 —
+    // body of every dependent view / materialized view — and the rewritten record of
+    // every dependent table (its CHECK expressions, the referenced-column list of an FK
+    // pointing here, its partial-index predicates) — must still be persistable, on the
     // 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
@@ -276,7 +291,8 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
     // `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));
+    assertRenameDependentsPersistable(rctx.db, schema, ast => renameColumnInAst(ast, tableSchema.name, oldName, newName, tableSchema.schemaName, resolveColumnInSource), t => rewriteTableForColumnRename(t, tableSchema.schemaName.toLowerCase(), tableSchema.name, oldName, newName, resolveColumnInSource));
+    assertRenamedColumnBackingNamesFree(tableSchema, colIndex, oldName, newName);
     const existingCol = tableSchema.columns[colIndex];
     // Build a ColumnDef AST for the renamed column (preserving type info)
     const newColumnDef = {
@@ -327,9 +343,86 @@ 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, resolveColumnInSource);
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'alter', objectType: 'column',
+        objectName: tableSchema.name,
+        columnName: newName,
+        oldColumnName: oldName,
+    });
     log('Renamed column %s.%s.%s to %s', tableSchema.schemaName, tableSchema.name, oldName, newName);
     return null;
 }
+/**
+ * Refuses a RENAME COLUMN that would move an unnamed UNIQUE constraint's backing
+ * structure onto a name an index on the same table already holds.
+ *
+ * An unnamed UNIQUE is enforced by a structure named `_uc_<covered column names>`,
+ * derived from the LIVE column names and never recorded — so renaming a covered
+ * column moves that name. This is the same collision the four declaration paths
+ * already refuse (ADD CONSTRAINT, ADD COLUMN … unique, RENAME CONSTRAINT, and
+ * `SchemaManager.createIndex` from the index side), reached through a rename instead
+ * of a declaration. Left unguarded the user's index is silently reclassified as a
+ * hidden backing structure: it vanishes from `schema()` / `index_info()`, `DROP INDEX`
+ * answers `no such index`, and store-backed its `CREATE INDEX` line is dropped from
+ * the persisted catalog entry — after which the constraint's entries are built into
+ * that index's store and, on reopen, it stops rejecting duplicates.
+ *
+ * Placed before `module.alterTable` for the same reason those paths are: the store's
+ * `alterTable` persists, so a later throw would leave the damage on disk.
+ *
+ * Skips a case-only rename entirely: the derived name folds to the constraint's OWN
+ * pre-rename structure, which the memory backend materializes as a real index entry
+ * and the name-only guard would otherwise read as a collision (the same reason
+ * `runRenameConstraint` gates its check on `oldLower !== newLower`).
+ *
+ * Named and `derivedFromIndex` constraints are unaffected — neither takes a derived
+ * name. Two DIFFERENT unnamed constraints deriving one post-rename name is only
+ * reachable through duplicate unnamed UNIQUEs and is not this guard's problem.
+ *
+ * NOTE: name-only, like the declaration guards, so it also refuses the rename when the
+ * constraint is realized by a REUSED same-column-set index and therefore has no
+ * `_uc_*` structure to move — a legal rename turned away over a name nothing would
+ * have claimed. Deliberate: both backends decide reuse internally and at different
+ * times, so a reuse-aware check would make them disagree on which renames are legal.
+ * The refusal names both objects and is escapable by renaming the index first. If the
+ * false refusal ever bites, gate the check on the constraint actually holding a
+ * `_uc_*` structure — which means asking the module, not just `tableSchema.indexes`.
+ */
+function assertRenamedColumnBackingNamesFree(tableSchema, colIndex, oldName, newName) {
+    if (oldName.toLowerCase() === newName.toLowerCase())
+        return;
+    for (const uc of tableSchema.uniqueConstraints ?? []) {
+        if (uc.name !== undefined || uc.derivedFromIndex !== undefined)
+            continue;
+        if (!uc.columns.includes(colIndex))
+            continue;
+        const postRenameColumns = uc.columns.map(i => i === colIndex ? newName : (tableSchema.columns[i]?.name ?? String(i)));
+        assertUniqueConstraintIndexNameFree(tableSchema, undefined, postRenameColumns, `rename column '${oldName}' to '${newName}' on table '${tableSchema.name}'`);
+    }
+}
+/**
+ * Refuses an inline constraint on a new column whose *user-written* name is already taken —
+ * by a constraint on the table, or by an earlier inline constraint in the same ADD COLUMN
+ * (neither is on `tableSchema` yet). Same within-table rule ADD CONSTRAINT and RENAME
+ * CONSTRAINT enforce; see {@link assertConstraintNameFree} for the ordering constraints.
+ *
+ * Reads the RAW declaration rather than the extracted table constraints: the extractors
+ * auto-name an unnamed CHECK `_check_<column>`, and that synthesized name is not user
+ * identity — comparing it would refuse two unnamed CHECKs on one new column, which is
+ * legal. Only the three classes that occupy a named-constraint array are compared (a name
+ * on an inline NOT NULL / DEFAULT / PRIMARY KEY is not stored, so it cannot collide).
+ */
+function assertInlineConstraintNamesFree(tableSchema, columnDef) {
+    const seen = new Set();
+    for (const declared of columnDef.constraints) {
+        if (!declared.name)
+            continue;
+        if (declared.type !== 'check' && declared.type !== 'unique' && declared.type !== 'foreignKey')
+            continue;
+        assertConstraintNameFree(tableSchema, declared.name, seen);
+        seen.add(declared.name.toLowerCase());
+    }
+}
 async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, backfillCb, checks, checkCbs) {
     // Validate column doesn't already exist
     if (tableSchema.columnIndexMap.has(columnDef.name.toLowerCase())) {
@@ -343,21 +436,37 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
     // (bind params / bare columns / non-determinism rejected; `new.<column>` accepted)
     // 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.
+    // A GENERATED ALWAYS AS expression takes the same `backfill` route (always, since a
+    // generated column has no `defaultValue` any module could bulk-write), validated at
+    // plan-build with the generated-flavoured determinism check.
     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;
+    // Folded literal default, converted to the new column's declared type — the value a
+    // fresh INSERT under the same DEFAULT would store, and the same value each module
+    // folds for its own rows. Undefined when there is no default (a generated column
+    // included) or it does not fold — those carry `backfill` instead. Used by the NOT NULL
+    // gate below and by the batched-event remap's backfill value. An unconvertible literal
+    // (`integer default 'abc'`) throws MISMATCH here, before anything is mutated.
+    const foldedDefault = foldDefaultToType(defaultConstraint?.expr, inferType(columnDef.dataType), columnDef.name);
     // Call module.alterTable for data + schema update
     const module = requireVtabModule(tableSchema);
     if (!module.alterTable) {
         throw new QuereusError(`Module for table '${tableSchema.name}' does not support ALTER TABLE ADD COLUMN`, StatusCode.UNSUPPORTED);
     }
-    // NOT NULL without a usable DEFAULT cannot backfill existing rows. A DEFAULT whose
-    // folded value is NULL is equivalent to "no DEFAULT" for this purpose. A non-foldable
-    // expression default (carried in `backfill`) IS usable — its NOT NULL enforcement is
-    // deferred to the post-backfill scan — so it is not rejected here. If the table is
-    // non-empty and the default is nullish, reject before mutating any schema or data.
+    // NOT NULL without a usable value source cannot backfill existing rows. A DEFAULT whose
+    // folded value is NULL is equivalent to "no DEFAULT" for this purpose. A per-row source
+    // (carried in `backfill` — a non-foldable expression default or a GENERATED ALWAYS AS
+    // expression) IS usable: its NOT NULL enforcement is deferred to the module's per-row
+    // backfill, which rejects the ALTER if any row evaluates to NULL. If the table is
+    // non-empty and there is no usable source, reject before mutating any schema or data.
+    //
+    // Mandatoriness is RESOLVED, not read off the statement text: a column is NOT NULL
+    // either by an explicit `not null` or by the session `default_column_nullability`
+    // (which ships as `not_null`), so `add column x text default null` is a mandatory
+    // column with no value for the existing rows and must be refused. `columnDefToSchema`
+    // is the same resolver the memory module, the store module and the isolation layer's
+    // `deriveAddColumnBackfill` use, so a fourth spelling of the rule cannot drift. It
+    // also validates an explicit COLLATE and rejects DEFAULT + GENERATED ALWAYS AS on one
+    // column — both previously raised by the module mid-work, now pre-mutation.
     //
     // A module may opt out of this engine-generic rejection via the
     // `delegatesNotNullBackfill` capability (structurally-total modules that
@@ -365,8 +474,9 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
     // it declares the capability, the decision is left entirely to its
     // `alterTable`. Native modules leave it off, so this still fires for them.
     const delegatesBackfill = module.getCapabilities?.().delegatesNotNullBackfill === true;
-    const hasNotNull = columnDef.constraints?.some(c => c.type === 'notNull') ?? false;
-    if (hasNotNull && !delegatesBackfill && !backfill) {
+    const defaultNotNull = rctx.db.options.getStringOption('default_column_nullability') === 'not_null';
+    const resolvedNotNull = columnDefToSchema(columnDef, defaultNotNull, rctx.db.options.getStringOption('default_collation'), (n) => rctx.db.isCollationRegistered(n)).notNull;
+    if (resolvedNotNull && !delegatesBackfill && !backfill) {
         const defaultIsNullish = !defaultConstraint?.expr || foldedDefault === null;
         if (defaultIsNullish) {
             await validateNotNullBackfill(rctx, tableSchema, columnDef.name);
@@ -389,9 +499,37 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
         ...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.
+    // Refused before the column is materialized, so a duplicate name leaves the table
+    // completely untouched rather than relying on the revert path.
+    assertInlineConstraintNamesFree(tableSchema, columnDef);
+    // An inline `unique` builds an implicit backing structure named after the constraint
+    // — or `_uc_<column>` when unnamed — so reject before the column is materialized when
+    // that name is already an index on this table, or when the declaration merely repeats
+    // a UNIQUE the table already carries. The column does not exist yet, so both tests run
+    // off the column definition's own name (which is exactly what
+    // `extractColumnLevelUniqueConstraints` put in `columns`). Placed here, ahead of
+    // `module.alterTable`, so a refused statement leaves the table completely untouched
+    // rather than relying on the revert path.
+    //
+    // Duplicate-first, index-name-second — see the ordering rationale in
+    // `runAddConstraintViaModule`. `declaredColumnSets` carries the unnamed sets claimed by
+    // earlier inline constraints in THIS statement (`add column c … unique unique`); none
+    // of them is on `tableSchema` yet, so the guard cannot see them any other way.
+    const declaredColumnSets = new Set();
+    for (const constraint of inlineConstraints) {
+        if (constraint.type !== 'unique')
+            continue;
+        const columnNames = (constraint.columns ?? []).map(c => c.name);
+        const operation = `add ${constraint.name ? `constraint '${constraint.name}'` : 'UNIQUE'} column '${columnDef.name}' to table '${tableSchema.name}'`;
+        assertUniqueConstraintNotDuplicated(tableSchema, constraint.name, columnNames, operation, declaredColumnSets);
+        assertUniqueConstraintIndexNameFree(tableSchema, constraint.name, columnNames, operation);
+        if (constraint.name === undefined)
+            declaredColumnSets.add(uniqueConstraintColumnSetKey(columnNames));
+    }
+    // A per-row backfill derives each existing row's value from that row. Install a row slot
+    // over the backfill's row descriptor; the evaluator the module calls per existing row
+    // sets the slot to that row, so the expression's `new.<col>` refs (and the bare `<col>`
+    // refs a GENERATED ALWAYS AS expression uses) resolve to it.
     const rowSlot = backfill ? createRowSlot(rctx, backfill.rowDescriptor) : undefined;
     // When the new column carries a CHECK, install a second slot over the existing columns
     // plus the new column; we evaluate each predicate against `[...existingRow, value]` after
@@ -405,7 +543,15 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
         ? async (row) => {
             rowSlot.set(row);
             const valueRaw = backfillCb(rctx);
-            const value = (valueRaw instanceof Promise ? await valueRaw : valueRaw);
+            const evaluated = (valueRaw instanceof Promise ? await valueRaw : valueRaw);
+            // Convert to the new column's declared type BEFORE the CHECK predicates see it,
+            // matching the write path (`emitInsert` coerces at the top of the DML pipeline, so
+            // constraint checking and storage both see the declared form). `coerceTo` is unset
+            // when the expression's static type already IS the column's type — see
+            // `AddColumnBackfill.coerceTo` for why re-converting there would be destructive.
+            const value = backfill.coerceTo
+                ? validateAndParse(evaluated, backfill.coerceTo, columnDef.name)
+                : evaluated;
             if (checkSlot && checkPredicates.length > 0 && checkCbs) {
                 checkSlot.set([...row, value]);
                 for (let i = 0; i < checkPredicates.length; i++) {
@@ -507,9 +653,10 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
         // 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
+        // path only. A per-row (evaluator) backfill — non-foldable DEFAULT or GENERATED
+        // ALWAYS AS — 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) {
@@ -571,6 +718,17 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, back
         oldObject: tableSchema,
         newObject: finalTableSchema,
     });
+    // ONE event for the whole statement, even when the column declared inline constraints.
+    // The install loop above makes a second `module.alterTable(addConstraint)` round-trip per
+    // inline constraint, and an emitter-backed module therefore announces `alter`/`column`
+    // followed by an `alter`/`table` per constraint — an artifact of its internal call
+    // pattern, not a second thing the application did. The deliberate divergence from that
+    // shape: do not "fix" this into two events.
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'alter', objectType: 'column',
+        objectName: tableSchema.name,
+        columnName: columnDef.name,
+    });
     log('Added column %s to table %s.%s', columnDef.name, tableSchema.schemaName, tableSchema.name);
     return null;
 }
@@ -666,9 +824,10 @@ async function validateBackfillAgainstChecks(rctx, columnOnlySchema, newCheckCon
     }
 }
 /**
- * Rejects ADD COLUMN ... NOT NULL when no usable DEFAULT is supplied and the
- * table already has rows. The pre-mutation form means no rollback is needed —
- * the schema and module state are still untouched at this point.
+ * Rejects ADD COLUMN ... NOT NULL when no usable value source is supplied (no DEFAULT,
+ * a DEFAULT folding to NULL, and no per-row backfill) and the table already has rows.
+ * The pre-mutation form means no rollback is needed — the schema and module state are
+ * still untouched at this point.
  */
 async function validateNotNullBackfill(rctx, tableSchema, newColumnName) {
     const qualifiedTable = qualifyTableName(tableSchema.schemaName, tableSchema.name);
@@ -786,6 +945,13 @@ async function runDropColumn(rctx, tableSchema, schema, columnName) {
         oldObject: tableSchema,
         newObject: finalSchema,
     });
+    // `drop`, not `alter` — the arm removes an object. Matches what an emitter-backed module
+    // reports for the same statement.
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'drop', objectType: 'column',
+        objectName: tableSchema.name,
+        columnName,
+    });
     log('Dropped column %s from table %s.%s', columnName, tableSchema.schemaName, tableSchema.name);
     return null;
 }
@@ -820,6 +986,10 @@ async function runDropConstraint(rctx, tableSchema, schema, constraintName) {
         oldObject: tableSchema,
         newObject: updatedTableSchema,
     });
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'alter', objectType: 'table',
+        objectName: tableSchema.name,
+    });
     log('Dropped constraint %s from table %s.%s', constraintName, tableSchema.schemaName, tableSchema.name);
     return null;
 }
@@ -841,6 +1011,17 @@ async function runRenameConstraint(rctx, tableSchema, schema, oldName, newName)
     if (oldLower !== newLower && namedConstraintExists(tableSchema, newName)) {
         throw new QuereusError(`Cannot rename constraint to '${newName}': a constraint with that name already exists in table '${tableSchema.name}'`, StatusCode.CONSTRAINT);
     }
+    // A UNIQUE constraint's implicit backing structure is named after the constraint, so
+    // the rename renames that structure too — reject when the new name is already an
+    // index on this table (the mirror of `SchemaManager.createIndex`'s refusal). Gated on
+    // `oldLower !== newLower` for the same reason the collision check above is: on the
+    // memory backend the constraint's OWN backing structure is a materialized index under
+    // the old name, which a case-only rename would otherwise match.
+    if (constraintClass === 'unique' && oldLower !== newLower) {
+        // No columns to pass: the renamed-to name is always a name, so the `_uc_<cols>`
+        // auto-name branch is unreachable from here.
+        assertUniqueConstraintIndexNameFree(tableSchema, newName, [], `rename constraint '${oldName}' to '${newName}' on table '${tableSchema.name}'`);
+    }
     const module = requireVtabModule(tableSchema);
     if (!module.alterTable) {
         throw new QuereusError(`Module for table '${tableSchema.name}' does not support ALTER TABLE RENAME CONSTRAINT`, StatusCode.UNSUPPORTED);
@@ -858,16 +1039,15 @@ async function runRenameConstraint(rctx, tableSchema, schema, oldName, newName)
         oldObject: tableSchema,
         newObject: updatedTableSchema,
     });
+    // A named constraint is not an `objectType` of its own, so the arm reports the TABLE it
+    // reshaped — same as an emitter-backed module does.
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'alter', objectType: 'table',
+        objectName: tableSchema.name,
+    });
     log('Renamed constraint %s.%s.%s to %s', tableSchema.schemaName, tableSchema.name, oldName, newName);
     return null;
 }
-/** True when `name` addresses any named CHECK / UNIQUE / FOREIGN KEY constraint. */
-function namedConstraintExists(tableSchema, name) {
-    const lower = name.toLowerCase();
-    return (tableSchema.checkConstraints ?? []).some(c => c.name?.toLowerCase() === lower)
-        || (tableSchema.uniqueConstraints ?? []).some(c => c.name?.toLowerCase() === lower)
-        || (tableSchema.foreignKeys ?? []).some(c => c.name?.toLowerCase() === lower);
-}
 /**
  * Rejects DROP/RENAME of a UNIQUE constraint that was synthesized from an explicit
  * `CREATE UNIQUE INDEX` (`derivedFromIndex` set). That constraint is the index's
@@ -959,6 +1139,14 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
         oldObject: tableSchema,
         newObject: updatedTableSchema,
     });
+    // All four attribute forms (SET/DROP NOT NULL, SET DATA TYPE, SET/DROP DEFAULT,
+    // SET COLLATE) report the same `alter`/`column` shape — the event says which column
+    // changed, not which attribute.
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'alter', objectType: 'column',
+        objectName: tableSchema.name,
+        columnName: action.columnName,
+    });
     log('Altered column %s.%s.%s', tableSchema.schemaName, tableSchema.name, action.columnName);
     return null;
 }
@@ -996,11 +1184,17 @@ function alterColumnEventValueRemap(tableSchema, colIndex, action) {
         };
     }
     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;
+        // SET NOT NULL backfill: null → the folded-and-CONVERTED literal DEFAULT, the same
+        // map the module applies to its rows. No usable literal default means the module
+        // either found no NULLs (nothing to remap) or rejected the ALTER before reaching here.
+        //
+        // NOTE: `foldDefaultToType` throws MISMATCH on an unconvertible literal, and this
+        // runs AFTER the module mutated. Unreachable today — every module folds the same
+        // DEFAULT through the same helper up front and rejects the ALTER there, so a literal
+        // that fails here would already have failed. If a module ever stops folding eagerly,
+        // catch here and return undefined rather than aborting a completed ALTER.
+        const col = tableSchema.columns[colIndex];
+        const folded = foldDefaultToType(col.defaultValue, col.logicalType, col.name);
         if (folded === undefined || folded === null)
             return undefined;
         return (v) => (v === null ? folded : v);
@@ -1094,12 +1288,33 @@ async function runAlterPrimaryKey(rctx, tableSchema, schema, columns) {
         }
         seen.add(pk.index);
     }
+    // Column indices of the key being retired and the one replacing it. Both index the
+    // CURRENT column layout — ALTER PRIMARY KEY adds and drops no column — so they are
+    // also indices into the batched events' row images, which any earlier ALTER in this
+    // transaction has already remapped to that layout.
+    const oldPkIndices = tableSchema.primaryKeyDefinition.map(pk => pk.index);
+    const newPkIndices = newPkDef.map(pk => pk.index);
     // Try native module re-key first
     const module = requireVtabModule(tableSchema);
     if (module.alterTable) {
         try {
             const schemaChangePk = newPkDef.map(pk => ({ index: pk.index, desc: pk.desc ?? false }));
             const updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, { type: 'alterPrimaryKey', newPkColumns: schemaChangePk });
+            // Events this transaction already recorded identify their rows by the RETIRED
+            // key; re-derive each from its own row image so the commit delivers every event
+            // under the key 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: this sits inside the try whose catch falls through to the rebuild, so an
+            // UNSUPPORTED raised BELOW it (only reachable via a `table_modified` listener, as
+            // `schema.addTable` raises no UNSUPPORTED) would re-key twice. The second pass is
+            // idempotent for every event except a PK-moving update, whose image tie-break no
+            // longer recognizes the already-rewritten key. If anything below this line gains
+            // a real UNSUPPORTED path, narrow the try to the `module.alterTable` call.
+            rctx.db._getEventEmitter().rekeyBatchedDataEvents(tableSchema.schemaName, tableSchema.name, oldPkIndices, newPkIndices);
             schema.addTable(updatedTableSchema);
             rctx.db.schemaManager.getChangeNotifier().notifyChange({
                 type: 'table_modified',
@@ -1108,39 +1323,96 @@ async function runAlterPrimaryKey(rctx, tableSchema, schema, columns) {
                 oldObject: tableSchema,
                 newObject: updatedTableSchema,
             });
+            // NOTE: inside the try whose catch falls through to the rebuild — same caveat as
+            // the re-key above. The emit raises no UNSUPPORTED (the gate either emits or
+            // does not), so it cannot itself trigger the fallback.
+            emitAlterSchemaEvent(rctx, tableSchema, {
+                type: 'alter', objectType: 'table',
+                objectName: tableSchema.name,
+            });
             log('Altered primary key of %s.%s (native)', tableSchema.schemaName, tableSchema.name);
             return null;
         }
         catch (e) {
             if (e instanceof QuereusError && e.code === StatusCode.UNSUPPORTED) {
-                // Fall through to rebuild
+                // Fall through to rebuild. The swallow is the documented protocol
+                // (docs/module-authoring.md § `alterPrimaryKey`), but a swallowed error must
+                // still leave a trace — this is the only record that the native re-key was
+                // attempted and declined.
+                warnLog('Module %s declined an in-place re-key of %s.%s (UNSUPPORTED: %s); falling back to a shadow-table rebuild', tableSchema.vtabModuleName ?? '<unknown>', tableSchema.schemaName, tableSchema.name, e.message);
             }
             else {
                 throw e;
             }
         }
     }
-    // Rebuild fallback
+    // Rebuild fallback. Two preconditions, both refusals rather than repairs — see
+    // `rebuildViaShadowTable` for why neither has a correct outcome. Checked here, after the
+    // native attempt, so both entry paths into the rebuild (no `alterTable` hook at all; the
+    // hook raised UNSUPPORTED) are covered by one check each; a module that raised
+    // UNSUPPORTED has by contract mutated nothing, so a refusal here leaves the catalog, the
+    // table and the enclosing transaction untouched. Capability first: it is unconditional,
+    // so it is the more informative answer when both apply.
+    if (!module.renameTable) {
+        throw new QuereusError(`Module '${tableSchema.vtabModuleName ?? '<unknown>'}' does not support ALTER PRIMARY KEY on table `
+            + `'${tableSchema.name}': it cannot re-key in place (it implements no 'alterTable' hook, or the `
+            + `hook declined), and the engine's fallback rebuild finishes by renaming a shadow table over `
+            + `this one — without 'renameTable' the module would keep the rows under the shadow name and `
+            + `the rebuilt table could not be opened.`, StatusCode.UNSUPPORTED);
+    }
+    // NOTE: refused on every `DdlTransactionality` tier, including a module declaring
+    // 'transactional'. None does today; if one appears its DROP + RENAME would roll back
+    // together with the row copy, making this refusal over-broad — exempt that tier then, the
+    // way `assertDdlTransactionPolicy` already does.
+    if (isExplicitTransactionOpen(rctx.db)) {
+        throw new QuereusError(`ALTER PRIMARY KEY on table '${tableSchema.name}' is not allowed inside an explicit transaction: `
+            + `module '${tableSchema.vtabModuleName ?? '<unknown>'}' cannot re-key in place, so the statement `
+            + `would fall back to a shadow-table rebuild whose DROP + RENAME survives ROLLBACK while its row `
+            + `copy does not — a rollback would leave an empty table and destroy rows committed before this `
+            + `transaction began. COMMIT or ROLLBACK first, then re-issue in autocommit mode.`, StatusCode.ERROR);
+    }
     await rebuildTableWithNewShape(rctx, tableSchema, schema, tableSchema.columns.map(c => c.name), newPkDef);
+    // A DEFENSIVE NO-OP on this path today, not the working re-key the native arm above does.
+    // Nothing can be in the batch for this table by now: the rebuild's own events are
+    // suppressed (see `rebuildViaShadowTable`), the ALTER statement writes no rows of its own,
+    // and the explicit-transaction refusal above rules out earlier same-transaction writes.
+    // Kept anyway — it costs one walk of an empty batch, and it is the correct call the moment
+    // that transaction guard is loosened; deleting it would quietly make this arm's
+    // as-of-delivery `key` guarantee depend on the guard staying exactly as it is. Every column
+    // survives the rebuild in order (`survivingColumns` above is the full list), so the indices
+    // would still line up with the event images.
+    rctx.db._getEventEmitter().rekeyBatchedDataEvents(tableSchema.schemaName, tableSchema.name, oldPkIndices, newPkIndices);
+    // The rebuild's own four statements are silent (`rebuildViaShadowTable` runs them inside
+    // `withPublicEventsSuppressed`, which also swallows the inner RENAME TO arm's event). This
+    // emit is OUTSIDE that scope, so the re-key itself reports exactly one `alter`/`table` —
+    // the same shape the native branch above reports.
+    //
+    // NOTE: this arm is the one place where a module WITH its own emitter can end up reporting
+    // nothing — it raised UNSUPPORTED instead of emitting, and the gate below then suppresses
+    // the engine's fallback because the module registration advertises native support. No such
+    // module exists today (memory re-keys in place, the store handles `alterPrimaryKey`
+    // natively), so the path is unreachable. If an emitter-backed module ever declines the
+    // re-key, teach the gate that a rebuild fallback owns the event regardless of the module's
+    // emitter.
+    emitAlterSchemaEvent(rctx, tableSchema, {
+        type: 'alter', objectType: 'table',
+        objectName: tableSchema.name,
+    });
     log('Altered primary key of %s.%s (rebuild)', tableSchema.schemaName, tableSchema.name);
     return null;
 }
 /**
- * Rebuilds a table with a new column projection and/or primary key.
- * For MemoryTable: builds a new table via the module API and copies rows directly,
- * bypassing SQL execution to avoid transaction-layer isolation issues.
- * For other modules: uses shadow-table SQL approach with DROP+RENAME.
+ * Rebuilds a table with a new column projection and/or primary key, via the
+ * shadow-table SQL approach with DROP+RENAME. This is the fallback for a module
+ * whose `alterTable` throws `UNSUPPORTED` for `alterPrimaryKey` (or omits the
+ * hook); the built-in memory and store modules both re-key in place and never
+ * reach it. See `rebuildViaShadowTable` for the two preconditions
+ * `runAlterPrimaryKey` checks before calling this.
  */
 async function rebuildTableWithNewShape(rctx, tableSchema, schema, survivingColumns, newPkDef) {
     const tableName = tableSchema.name;
     const schemaName = tableSchema.schemaName;
-    const module = requireVtabModule(tableSchema);
-    if (module instanceof MemoryTableModule) {
-        await rebuildMemoryTable(rctx, tableSchema, schema, module, survivingColumns, newPkDef);
-    }
-    else {
-        await rebuildViaShadowTable(rctx, tableSchema, schema, survivingColumns, newPkDef);
-    }
+    await rebuildViaShadowTable(rctx, tableSchema, schema, survivingColumns, newPkDef);
     const finalSchema = schema.getTable(tableName);
     if (finalSchema) {
         rctx.db.schemaManager.getChangeNotifier().notifyChange({
@@ -1152,87 +1424,6 @@ async function rebuildTableWithNewShape(rctx, tableSchema, schema, survivingColu
         });
     }
 }
-/**
- * MemoryTable rebuild: builds a new table via module.create() and copies rows
- * directly from the old manager, then swaps in the module and catalog.
- */
-async function rebuildMemoryTable(rctx, tableSchema, schema, module, survivingColumns, newPkDef) {
-    const tableName = tableSchema.name;
-    const schemaName = tableSchema.schemaName;
-    const oldKey = `${schemaName}.${tableName}`.toLowerCase();
-    const oldMgr = module.tables.get(oldKey);
-    if (!oldMgr) {
-        throw new QuereusError(`Table '${tableName}' not found in module`, StatusCode.INTERNAL);
-    }
-    // Build column index mapping: old column index → new column index
-    const survivingIndices = [];
-    const newColumns = [];
-    for (const colName of survivingColumns) {
-        const oldIdx = tableSchema.columnIndexMap.get(colName.toLowerCase());
-        if (oldIdx === undefined)
-            continue;
-        survivingIndices.push(oldIdx);
-        newColumns.push(tableSchema.columns[oldIdx]);
-    }
-    // Remap PK indices from old schema to new column order
-    const remappedPk = newPkDef.map(pk => {
-        const newIdx = survivingIndices.indexOf(pk.index);
-        if (newIdx === -1) {
-            throw new QuereusError(`PK column index ${pk.index} not in surviving columns`, StatusCode.INTERNAL);
-        }
-        return { ...pk, index: newIdx };
-    });
-    // Build new schema
-    const newSchema = Object.freeze({
-        ...tableSchema,
-        columns: Object.freeze(newColumns),
-        columnIndexMap: buildColumnIndexMap(newColumns),
-        primaryKeyDefinition: Object.freeze(remappedPk),
-        indexes: Object.freeze([]),
-    });
-    // Create the new table via the module API (goes directly to base layer)
-    const shadowName = `${tableName}__rekey_${Date.now()}`;
-    const shadowSchema = Object.freeze({ ...newSchema, name: shadowName });
-    await module.create(rctx.db, shadowSchema);
-    const shadowMgr = module.tables.get(`${schemaName}.${shadowName}`.toLowerCase());
-    if (!shadowMgr) {
-        throw new QuereusError(`Shadow table manager not found after create`, StatusCode.INTERNAL);
-    }
-    try {
-        // Copy rows from old table to new, projecting surviving columns
-        const rows = oldMgr.scanAllRows();
-        for (const oldRow of rows) {
-            const newRow = survivingIndices.map(i => oldRow[i]);
-            shadowMgr.insertRow(newRow);
-        }
-        // Swap: remove old, remove shadow, re-register shadow under old name
-        module.tables.delete(oldKey);
-        module.tables.delete(`${schemaName}.${shadowName}`.toLowerCase());
-        shadowMgr.renameTable(tableName);
-        module.tables.set(oldKey, shadowMgr);
-        // Update catalog
-        schema.removeTable(tableName);
-        schema.addTable(shadowMgr.tableSchema);
-        // The old manager is now orphaned. Any active VirtualTableConnection bound
-        // to it (e.g. from a prior insert in this session) is stale and must not be
-        // reused against the rebuilt table — a reused-stale + fresh connection pair
-        // leaves two candidates registered for the same table name, which trips
-        // DeferredConstraintQueue.findConnection at the next commit. Mirror the
-        // drop-table path's cleanup (schema/manager.ts dropTable). The orphaned
-        // manager and its pending layer are discarded with the old manager, so no
-        // rollback is needed; this intentionally bypasses implicit-transaction
-        // deferral, exactly as drop table relies on.
-        rctx.db.removeConnectionsForTable(schemaName, tableName);
-    }
-    catch (e) {
-        // Clean up shadow on failure
-        try {
-            module.tables.delete(`${schemaName}.${shadowName}`.toLowerCase());
-        }
-        catch { /* ignore */ }
-        throw e;
-    }
-}
 /**
  * Build the shadow-table CREATE TABLE DDL used by the non-memory rebuild path.
  *
@@ -1339,9 +1530,29 @@ async function runDropMaintained(rctx, tableSchema, schema) {
     return null;
 }
 /**
- * Generic rebuild via shadow table SQL for non-memory modules.
+ * Generic rebuild via shadow table SQL, for a module without a native
+ * `alterPrimaryKey`.
+ *
+ * Two preconditions the caller (`runAlterPrimaryKey`) enforces, because this rebuild has no
+ * correct outcome without them:
+ *
+ *  - **The module must implement `renameTable`.** The last step renames the shadow table over
+ *    the original; a module that files its rows under the table's name and never hears about
+ *    the rename keeps them under the shadow name while the catalog says otherwise, and the
+ *    rebuilt table cannot be connected at all.
+ *  - **No explicit transaction may be open.** The two halves have different transactional
+ *    lifetimes: the schema half (DROP + RENAME) escapes ROLLBACK on every
+ *    `DdlTransactionality` tier a built-in module reaches, while the row copy is staged in the
+ *    transaction and IS undone. A ROLLBACK would therefore keep the new empty table and
+ *    discard the copy of the rows it replaced — destroying data committed before the
+ *    transaction began. Making the schema half roll back needs transactional DDL no module
+ *    offers; making the data half survive would commit part of the user's transaction behind
+ *    their back.
+ *
+ * The four statements are engine scaffolding, not statements the application issued, so the
+ * whole rebuild runs with the PUBLIC event channels suppressed — see the scope inside.
  */
-async function rebuildViaShadowTable(rctx, tableSchema, schema, survivingColumns, newPkDef) {
+async function rebuildViaShadowTable(rctx, tableSchema, _schema, survivingColumns, newPkDef) {
     const tableName = tableSchema.name;
     const schemaName = tableSchema.schemaName;
     const shadowName = `${tableName}__rekey_${Date.now()}`;
@@ -1349,19 +1560,40 @@ async function rebuildViaShadowTable(rctx, tableSchema, schema, survivingColumns
     const qualifiedTable = qualifyTableName(schemaName, tableName);
     const createDdl = buildShadowTableDdl(tableSchema, shadowName, survivingColumns, newPkDef);
     const projection = survivingColumns.map(c => quoteIdentifier(c)).join(', ');
-    try {
-        await rctx.db._execWithinTransaction(createDdl);
-        await rctx.db._execWithinTransaction(`insert into ${qualifiedShadow} (${projection}) select ${projection} from ${qualifiedTable}`);
-        await rctx.db._execWithinTransaction(`drop table ${qualifiedTable}`);
-        await rctx.db._execWithinTransaction(`alter table ${qualifiedShadow} rename to ${quoteIdentifier(tableName)}`);
-    }
-    catch (e) {
+    // The rebuild's statements are ordinary SQL, so without this scope they would raise
+    // ordinary notifications describing the scaffolding rather than what the user asked for:
+    // the copy announces every existing row as a fresh `insert` (relabelled onto the real
+    // table by the trailing rename), and the create/drop pair announces a timestamped table
+    // created and the real one dropped. A re-key changes no row and replaces no table, so all
+    // of that is wrong. Covers the failure cleanup below too — a shadow table nobody was told
+    // about must not announce its own drop.
+    //
+    // Only the PUBLIC channels are suppressed. The internal catalog change notifier keeps
+    // firing throughout (it is what invalidates the optimizer's and the write path's cached
+    // schemas), which is why the rebuilt table is immediately plannable under its new key.
+    //
+    // NOTE: a module whose own emitter defers delivery to its own commit — rather than
+    // emitting during the write — can still leak the copy's inserts, because its events
+    // arrive after this scope has closed. Conditional, not a live defect: no module that
+    // reaches this rebuild behaves that way (memory and the store both re-key in place and
+    // never enter it). If one ever does, suppression has to become name-keyed (covering the
+    // shadow name as well as the real one) or the events have to be dropped out of the batch
+    // after the fact.
+    await rctx.db._getEventEmitter().withPublicEventsSuppressed(async () => {
         try {
-            await rctx.db._execWithinTransaction(`drop table if exists ${qualifiedShadow}`);
+            await rctx.db._execWithinTransaction(createDdl);
+            await rctx.db._execWithinTransaction(`insert into ${qualifiedShadow} (${projection}) select ${projection} from ${qualifiedTable}`);
+            await rctx.db._execWithinTransaction(`drop table ${qualifiedTable}`);
+            await rctx.db._execWithinTransaction(`alter table ${qualifiedShadow} rename to ${quoteIdentifier(tableName)}`);
         }
-        catch { /* ignore */ }
-        throw e;
-    }
+        catch (e) {
+            try {
+                await rctx.db._execWithinTransaction(`drop table if exists ${qualifiedShadow}`);
+            }
+            catch { /* ignore */ }
+            throw e;
+        }
+    });
 }
 /**
  * Propagates a table rename into every dependent schema object the catalog