@quereus/quereus 3.3.0 → 4.1.0

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

@@ -1,11 +1,16 @@
+import { emitCallFromPlan } from '../emitters.js';
+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, opsToMask, withGeneratedColumnGraph } from '../../schema/table.js';
+import { buildColumnIndexMap, withGeneratedColumnGraph, requireVtabModule, resolveNamedConstraintClass, validateCollationForType } from '../../schema/table.js';
+import { validateForeignKeyOverExistingRows, validateForeignKeyCollations, extractColumnLevelCheckConstraints, extractColumnLevelForeignKeys, extractColumnLevelUniqueConstraints } from '../../schema/constraint-builder.js';
 import { MemoryTableModule } from '../../vtab/memory/module.js';
-import { quoteIdentifier, expressionToString, selectToString } from '../../emit/ast-stringify.js';
+import { quoteIdentifier, expressionToString, astToString } from '../../emit/ast-stringify.js';
 import { renameTableInAst, renameColumnInAst, renameColumnInCheckExpression } from '../../schema/rename-rewriter.js';
 import { tryFoldLiteral } from '../../parser/utils.js';
+import { snapshotStaleMaterializedViews, propagateTableRenameToMaterializedViews, propagateColumnRenameToMaterializedViews, restoreUnaffectedMaterializedViews, attachMaintainedDerivation, detachMaintainedDerivation, } from './materialized-view-helpers.js';
+import { isMaintainedTable } from '../../schema/derivation.js';
 const log = createLogger('runtime:emit:alter-table');
 function qualifyTableName(schemaName, tableName) {
     const prefix = (schemaName && schemaName.toLowerCase() !== 'main')
@@ -13,27 +18,92 @@ function qualifyTableName(schemaName, tableName) {
         : '';
     return `${prefix}${quoteIdentifier(tableName)}`;
 }
-export function emitAlterTable(plan, _ctx) {
+export function emitAlterTable(plan, ctx) {
     const tableSchema = plan.table.tableSchema;
     const action = plan.action;
-    async function run(rctx) {
+    // 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.
+    const backfill = action.type === 'addColumn' ? action.backfill : undefined;
+    const checks = action.type === 'addColumn' ? action.checks : undefined;
+    const params = [
+        ...(backfill ? [emitCallFromPlan(backfill.node, ctx)] : []),
+        ...(checks?.predicates ?? []).map(p => emitCallFromPlan(p.node, ctx)),
+    ];
+    async function run(rctx, ...args) {
         // Ensure we're in a transaction before DDL (lazy/JIT transaction start)
         await rctx.db._ensureTransaction();
         const schemaManager = rctx.db.schemaManager;
         const schema = schemaManager.getSchemaOrFail(tableSchema.schemaName);
+        // A maintained table's shape is DEFINED by its derivation body — structural
+        // ALTERs would desynchronize (and, mechanically, drop the derivation when the
+        // module returns a fresh schema). Only rename and the derivation lifecycle
+        // verbs (SET MAINTAINED = re-attach, DROP MAINTAINED = detach) remain
+        // allowed. Tag actions must go through ALTER MATERIALIZED VIEW: the TABLE
+        // verb fires `table_modified`, not `materialized_view_modified`, so the tag
+        // edit would never reach the persisted maintained-table catalog entry.
+        if (isMaintainedTable(tableSchema)
+            && action.type !== 'renameTable'
+            && action.type !== 'setMaintained'
+            && action.type !== 'dropMaintained') {
+            throw new QuereusError(action.type === 'setTags' || action.type === 'dropTags'
+                ? `cannot ALTER TABLE '${tableSchema.name}': it is a materialized view — use ALTER MATERIALIZED VIEW for tags`
+                : `cannot ALTER '${tableSchema.name}': it is a materialized view — its shape is defined by the view body (drop and recreate to change it)`, StatusCode.ERROR);
+        }
         switch (action.type) {
             case 'renameTable':
                 return runRenameTable(rctx, tableSchema, schema, action.newName);
             case 'renameColumn':
                 return runRenameColumn(rctx, tableSchema, schema, action.oldName, action.newName);
-            case 'addColumn':
-                return runAddColumn(rctx, tableSchema, schema, action.column);
+            case 'addColumn': {
+                // Slot order set in `params`: backfill callback first (if any), then check callbacks.
+                const backfillCb = backfill ? args[0] : undefined;
+                const checkCbs = args.slice(backfill ? 1 : 0);
+                return runAddColumn(rctx, tableSchema, schema, action.column, backfill, backfillCb, checks, checkCbs);
+            }
             case 'dropColumn':
                 return runDropColumn(rctx, tableSchema, schema, action.name);
+            case 'dropConstraint':
+                return runDropConstraint(rctx, tableSchema, schema, action.name);
+            case 'renameConstraint':
+                return runRenameConstraint(rctx, tableSchema, schema, action.oldName, action.newName);
             case 'alterPrimaryKey':
                 return runAlterPrimaryKey(rctx, tableSchema, schema, action.columns);
             case 'alterColumn':
                 return runAlterColumn(rctx, tableSchema, schema, action);
+            case 'setTags': {
+                const target = action.target;
+                if (action.mode === 'merge') {
+                    // ADD TAGS — per-key merge onto the live tag set.
+                    if (target.kind === 'column')
+                        return runMergeColumnTags(rctx, tableSchema, target.columnName, action.tags);
+                    if (target.kind === 'constraint')
+                        return runMergeConstraintTags(rctx, tableSchema, target.constraintName, action.tags);
+                    return runMergeTableTags(rctx, tableSchema, action.tags);
+                }
+                // SET TAGS — whole-set replace.
+                if (target.kind === 'column')
+                    return runSetColumnTags(rctx, tableSchema, target.columnName, action.tags);
+                if (target.kind === 'constraint')
+                    return runSetConstraintTags(rctx, tableSchema, target.constraintName, action.tags);
+                return runSetTableTags(rctx, tableSchema, action.tags);
+            }
+            case 'dropTags': {
+                // DROP TAGS — per-key delete (atomic NOTFOUND if any key absent).
+                const target = action.target;
+                if (target.kind === 'column')
+                    return runDropColumnTags(rctx, tableSchema, target.columnName, action.keys);
+                if (target.kind === 'constraint')
+                    return runDropConstraintTags(rctx, tableSchema, target.constraintName, action.keys);
+                return runDropTableTags(rctx, tableSchema, action.keys);
+            }
+            case 'setMaintained':
+                return runSetMaintained(rctx, tableSchema, schema, action.columns, action.select);
+            case 'dropMaintained':
+                return runDropMaintained(rctx, tableSchema, schema);
         }
     }
     const note = (() => {
@@ -42,12 +112,30 @@ export function emitAlterTable(plan, _ctx) {
             case 'renameColumn': return `renameColumn(${tableSchema.name}.${action.oldName} -> ${action.newName})`;
             case 'addColumn': return `addColumn(${tableSchema.name}.${action.column.name})`;
             case 'dropColumn': return `dropColumn(${tableSchema.name}.${action.name})`;
+            case 'dropConstraint': return `dropConstraint(${tableSchema.name}.${action.name})`;
+            case 'renameConstraint': return `renameConstraint(${tableSchema.name}.${action.oldName} -> ${action.newName})`;
             case 'alterPrimaryKey': return `alterPrimaryKey(${tableSchema.name} -> [${action.columns.map(c => c.name).join(', ')}])`;
             case 'alterColumn': return `alterColumn(${tableSchema.name}.${action.columnName})`;
+            case 'setTags': {
+                const t = action.target;
+                const where = t.kind === 'column' ? `${tableSchema.name}.${t.columnName}`
+                    : t.kind === 'constraint' ? `${tableSchema.name}.constraint ${t.constraintName}`
+                        : tableSchema.name;
+                return action.mode === 'merge' ? `mergeTags(${where})` : `setTags(${where})`;
+            }
+            case 'dropTags': {
+                const t = action.target;
+                const where = t.kind === 'column' ? `${tableSchema.name}.${t.columnName}`
+                    : t.kind === 'constraint' ? `${tableSchema.name}.constraint ${t.constraintName}`
+                        : tableSchema.name;
+                return `dropTags(${where})`;
+            }
+            case 'setMaintained': return `setMaintained(${tableSchema.name})`;
+            case 'dropMaintained': return `dropMaintained(${tableSchema.name})`;
         }
     })();
     return {
-        params: [],
+        params,
         run: run,
         note,
     };
@@ -67,13 +155,18 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
     // BEFORE we mutate the in-memory catalog, so a module failure leaves the
     // catalog untouched. Modules that don't persist by table name can simply
     // omit the hook.
-    const module = tableSchema.vtabModule;
+    const module = requireVtabModule(tableSchema);
     if (module.renameTable) {
         await module.renameTable(rctx.db, tableSchema.schemaName, oldName, newName);
     }
     // Remove old, add new in the catalog
     schema.removeTable(oldName);
     schema.addTable(updatedTableSchema);
+    // Snapshot which MVs are stale BEFORE this statement's first schema-change
+    // notify: the MV propagation below restores staleness set by this very
+    // statement's events, but must never clear a pre-existing flag (the backing
+    // may already be behind; only REFRESH can safely clear that).
+    const preStaleMvs = snapshotStaleMaterializedViews(rctx.db);
     // Notify schema change
     rctx.db.schemaManager.getChangeNotifier().notifyChange({
         type: 'table_modified',
@@ -82,10 +175,32 @@ async function runRenameTable(rctx, tableSchema, schema, newName) {
         oldObject: tableSchema,
         newObject: updatedTableSchema,
     });
-    // Propagate the rename into dependent objects (CHECK / FK in this and other
-    // tables, view bodies). Best-effort AST rewrite — there is no global
-    // dependency tracker yet, so we walk the catalog and patch in-place.
-    propagateTableRename(rctx, tableSchema.schemaName, oldName, newName);
+    // Propagate the rename into dependent objects (CHECK / FK / partial-index
+    // predicates in this and other tables, view and materialized-view bodies).
+    // Best-effort AST rewrite — there is no global dependency tracker yet, so we
+    // walk the catalog and patch in-place.
+    await propagateTableRename(rctx, tableSchema.schemaName, oldName, newName, preStaleMvs);
+    // Renaming a MAINTAINED table is an ordinary table rename plus a maintenance
+    // re-key: the row-time plan is keyed by `schema.name`, so release the old key
+    // and re-register under the new one, then move the persisted MV catalog entry
+    // (`materialized_view_removed` old name → `materialized_view_added` new name).
+    if (isMaintainedTable(updatedTableSchema)) {
+        rctx.db.unregisterMaterializedView(tableSchema.schemaName, oldName);
+        rctx.db.registerMaterializedView(updatedTableSchema);
+        const notifier = rctx.db.schemaManager.getChangeNotifier();
+        notifier.notifyChange({
+            type: 'materialized_view_removed',
+            schemaName: tableSchema.schemaName,
+            objectName: oldName,
+            oldObject: tableSchema,
+        });
+        notifier.notifyChange({
+            type: 'materialized_view_added',
+            schemaName: tableSchema.schemaName,
+            objectName: newName,
+            newObject: updatedTableSchema,
+        });
+    }
     log('Renamed table %s.%s to %s', tableSchema.schemaName, oldName, newName);
     return null;
 }
@@ -106,7 +221,7 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
         constraints: buildConstraintsFromColumn(existingCol),
     };
     // Call module.alterTable if available (handles data-level changes)
-    const module = tableSchema.vtabModule;
+    const module = requireVtabModule(tableSchema);
     let updatedTableSchema;
     if (module.alterTable) {
         updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
@@ -127,6 +242,11 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
     }
     // Update the schema catalog
     schema.addTable(updatedTableSchema);
+    // Snapshot pre-statement MV staleness BEFORE the notify below: the notify's
+    // listener marks every dependent MV stale, and the propagation must be able to
+    // tell that statement-local staleness (restorable after a successful rewrite)
+    // apart from a pre-existing flag (never cleared — only REFRESH may).
+    const preStaleMvs = snapshotStaleMaterializedViews(rctx.db);
     rctx.db.schemaManager.getChangeNotifier().notifyChange({
         type: 'table_modified',
         schemaName: tableSchema.schemaName,
@@ -134,13 +254,13 @@ async function runRenameColumn(rctx, tableSchema, schema, oldName, newName) {
         oldObject: tableSchema,
         newObject: updatedTableSchema,
     });
-    // Propagate the rename into dependent objects (CHECK / FK in this and other
-    // tables, view bodies).
-    propagateColumnRename(rctx, tableSchema.schemaName, tableSchema.name, 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);
     log('Renamed column %s.%s.%s to %s', tableSchema.schemaName, tableSchema.name, oldName, newName);
     return null;
 }
-async function runAddColumn(rctx, tableSchema, schema, columnDef) {
+async function runAddColumn(rctx, tableSchema, schema, columnDef, backfill, backfillCb, checks, checkCbs) {
     // Validate column doesn't already exist
     if (tableSchema.columnIndexMap.has(columnDef.name.toLowerCase())) {
         throw new QuereusError(`Column '${columnDef.name}' already exists in table '${tableSchema.name}'`, StatusCode.ERROR);
@@ -149,23 +269,21 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef) {
     if (columnDef.constraints?.some(c => c.type === 'primaryKey')) {
         throw new QuereusError(`Cannot add a PRIMARY KEY column via ALTER TABLE`, StatusCode.ERROR);
     }
-    // Reject non-foldable DEFAULT expressions at DDL time. ADD COLUMN backfills
-    // existing rows with the DEFAULT value, so the expression must evaluate to a
-    // concrete literal at ALTER time. Column references, bind parameters, and
-    // non-deterministic function calls don't fold and are rejected per the
-    // determinism rule (consistent with CREATE TABLE's DEFAULT validation).
+    // The DEFAULT was validated at plan-build time through the shared DDL validator
+    // (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.
     const defaultConstraint = columnDef.constraints?.find(c => c.type === 'default');
-    if (defaultConstraint && defaultConstraint.expr && tryFoldLiteral(defaultConstraint.expr) === undefined) {
-        throw new QuereusError(`ALTER TABLE ADD COLUMN DEFAULT for '${columnDef.name}' must fold to a literal — column references, bind parameters, and non-deterministic expressions are not allowed`, StatusCode.ERROR);
-    }
     // Call module.alterTable for data + schema update
-    const module = tableSchema.vtabModule;
+    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. If the table
-    // is non-empty, reject before mutating any schema or data.
+    // 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.
     //
     // A module may opt out of this engine-generic rejection via the
     // `delegatesNotNullBackfill` capability (structurally-total modules that
@@ -174,21 +292,107 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef) {
     // `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) {
+    if (hasNotNull && !delegatesBackfill && !backfill) {
         const folded = defaultConstraint?.expr ? tryFoldLiteral(defaultConstraint.expr) : undefined;
-        const defaultIsNullish = !defaultConstraint || folded === undefined || folded === null;
+        const defaultIsNullish = !defaultConstraint?.expr || folded === null;
         if (defaultIsNullish) {
             await validateNotNullBackfill(rctx, tableSchema, columnDef.name);
         }
     }
-    // Extract column-level CHECK / FK constraints. Column-level UNIQUE is not enforced via
-    // table-level constraints; the existing rejection path in the manager handles it.
+    // 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);
-    const updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
-        type: 'addColumn',
-        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.
+    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
+    // computing the backfilled value and throw on a violation, so a CHECK-violating row aborts
+    // the ALTER inside the per-row hook — before any tree/batch swap — and the catalog is never
+    // mutated (mirrors the NOT NULL per-row path). This supersedes the post-backfill scan,
+    // which reads a stale pre-backfill snapshot for the evaluator path.
+    const checkSlot = backfill && checks ? createRowSlot(rctx, checks.rowDescriptor) : undefined;
+    const checkPredicates = checks?.predicates ?? [];
+    const backfillEvaluator = backfill && backfillCb && rowSlot
+        ? async (row) => {
+            rowSlot.set(row);
+            const valueRaw = backfillCb(rctx);
+            const value = (valueRaw instanceof Promise ? await valueRaw : valueRaw);
+            if (checkSlot && checkPredicates.length > 0 && checkCbs) {
+                checkSlot.set([...row, value]);
+                for (let i = 0; i < checkPredicates.length; i++) {
+                    const resultRaw = checkCbs[i](rctx);
+                    const result = (resultRaw instanceof Promise ? await resultRaw : resultRaw);
+                    // CHECK passes on truthy / NULL; fails on false / 0 (matches write-time semantics).
+                    if (result === false || result === 0) {
+                        const pred = checkPredicates[i];
+                        const hint = pred.exprText ? ` (${pred.exprText})` : '';
+                        throw new QuereusError(`CHECK constraint failed: ${pred.name ?? `_check_${columnDef.name}`}${hint}`, StatusCode.CONSTRAINT);
+                    }
+                }
+            }
+            return value;
+        }
+        : undefined;
+    // The slots are only needed while the module is appending the column (it calls the
+    // evaluator per existing row); close them as soon as that returns — before the CHECK
+    // scan below re-reads the table — so the backfill's context does not shadow the
+    // scan's own row context.
+    let updatedTableSchema;
+    try {
+        updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
+            type: 'addColumn',
+            columnDef,
+            backfillEvaluator,
+        });
+    }
+    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
@@ -212,12 +416,73 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef) {
     // generated-column edges form a cycle, this throws before we register the
     // new schema in the catalog.
     const enhancedTableSchema = withGeneratedColumnGraph(enhancedBase);
-    // Register the enhanced schema BEFORE backfill validation so that SQL bound
-    // during validation can resolve the new column.
-    schema.addTable(enhancedTableSchema);
-    if (newCheckConstraints.length > 0) {
+    // 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 {
-            await validateBackfillAgainstChecks(rctx, enhancedTableSchema, newCheckConstraints);
+            // 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);
+            }
         }
         catch (err) {
             // Revert: drop the column and restore the original catalog entry.
@@ -228,12 +493,18 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef) {
                 });
             }
             catch (revertErr) {
-                log('Failed to revert ADD COLUMN after CHECK violation: %s', revertErr.message);
+                log('Failed to revert ADD COLUMN after constraint violation: %s', revertErr.message);
             }
             schema.addTable(tableSchema);
             throw err;
         }
     }
+    // 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);
+    }
     rctx.db.schemaManager.getChangeNotifier().notifyChange({
         type: 'table_modified',
         schemaName: tableSchema.schemaName,
@@ -244,46 +515,6 @@ async function runAddColumn(rctx, tableSchema, schema, columnDef) {
     log('Added column %s to table %s.%s', columnDef.name, tableSchema.schemaName, tableSchema.name);
     return null;
 }
-function extractColumnLevelCheckConstraints(columnDef) {
-    const result = [];
-    for (const con of columnDef.constraints ?? []) {
-        if (con.type !== 'check' || !con.expr)
-            continue;
-        result.push({
-            name: con.name ?? `_check_${columnDef.name}`,
-            expr: con.expr,
-            operations: opsToMask(con.operations),
-            tags: con.tags && Object.keys(con.tags).length > 0 ? Object.freeze({ ...con.tags }) : undefined,
-        });
-    }
-    return result;
-}
-function extractColumnLevelForeignKeys(columnDef, defaultSchemaName) {
-    const result = [];
-    for (const con of columnDef.constraints ?? []) {
-        if (con.type !== 'foreignKey' || !con.foreignKey)
-            continue;
-        const fk = con.foreignKey;
-        // child column index gets resolved by caller after module.alterTable returns
-        // the updated schema with the new column appended.
-        if (fk.columns && fk.columns.length !== 1) {
-            throw new QuereusError(`FK constraint '${con.name ?? `_fk_${columnDef.name}`}' on ADD COLUMN '${columnDef.name}': child column count (1) does not match parent column count (${fk.columns.length})`, StatusCode.ERROR);
-        }
-        result.push({
-            name: con.name ?? `_fk_${columnDef.name}`,
-            columns: Object.freeze([]),
-            referencedTable: fk.table,
-            referencedSchema: defaultSchemaName,
-            referencedColumns: Object.freeze([]),
-            referencedColumnNames: fk.columns,
-            onDelete: fk.onDelete ?? 'restrict',
-            onUpdate: fk.onUpdate ?? 'restrict',
-            deferred: fk.initiallyDeferred ?? false,
-            tags: con.tags && Object.keys(con.tags).length > 0 ? Object.freeze({ ...con.tags }) : undefined,
-        });
-    }
-    return result;
-}
 /**
  * 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
@@ -352,7 +583,7 @@ async function runDropColumn(rctx, tableSchema, schema, columnName) {
         }
     }
     // Call module.alterTable for data + schema update
-    const module = tableSchema.vtabModule;
+    const module = requireVtabModule(tableSchema);
     if (!module.alterTable) {
         throw new QuereusError(`Module for table '${tableSchema.name}' does not support ALTER TABLE DROP COLUMN`, StatusCode.UNSUPPORTED);
     }
@@ -375,18 +606,112 @@ async function runDropColumn(rctx, tableSchema, schema, columnName) {
     log('Dropped column %s from table %s.%s', columnName, tableSchema.schemaName, tableSchema.name);
     return null;
 }
+/**
+ * DROP CONSTRAINT <name> — removes a named table-level constraint (CHECK / UNIQUE
+ * / FOREIGN KEY). Resolves the class up front (NOTFOUND / ambiguous surfaced here
+ * with a clear error before any module call), rejects dropping a UNIQUE constraint
+ * that is the synthesized side of an explicit `CREATE UNIQUE INDEX` (the index is
+ * the user's — `DROP INDEX` is the correct primitive), then routes the rewrite
+ * through `module.alterTable` so persistent modules re-persist their DDL. The
+ * module owns the actual array rewrite and, for a UNIQUE, tearing down the
+ * implicit covering index that backs it.
+ */
+async function runDropConstraint(rctx, tableSchema, schema, constraintName) {
+    const constraintClass = resolveNamedConstraintClass(tableSchema, constraintName);
+    if (constraintClass === 'unique') {
+        rejectDerivedFromIndex(tableSchema, constraintName, 'DROP');
+    }
+    const module = requireVtabModule(tableSchema);
+    if (!module.alterTable) {
+        throw new QuereusError(`Module for table '${tableSchema.name}' does not support ALTER TABLE DROP CONSTRAINT`, StatusCode.UNSUPPORTED);
+    }
+    const updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
+        type: 'dropConstraint',
+        constraintName,
+    });
+    schema.addTable(updatedTableSchema);
+    rctx.db.schemaManager.getChangeNotifier().notifyChange({
+        type: 'table_modified',
+        schemaName: tableSchema.schemaName,
+        objectName: tableSchema.name,
+        oldObject: tableSchema,
+        newObject: updatedTableSchema,
+    });
+    log('Dropped constraint %s from table %s.%s', constraintName, tableSchema.schemaName, tableSchema.name);
+    return null;
+}
+/**
+ * RENAME CONSTRAINT <old> TO <new> — name-level rename of a named table-level
+ * constraint. Resolves the class up front, rejects a no-op / collision (the new
+ * name must not already address a constraint), and rejects renaming a UNIQUE
+ * derived from an explicit index. Routed through `module.alterTable`.
+ */
+async function runRenameConstraint(rctx, tableSchema, schema, oldName, newName) {
+    const constraintClass = resolveNamedConstraintClass(tableSchema, oldName);
+    if (constraintClass === 'unique') {
+        rejectDerivedFromIndex(tableSchema, oldName, 'RENAME');
+    }
+    // Collision: the new name must not already address an existing named constraint
+    // (unless it's a case-only change of the same constraint).
+    const oldLower = oldName.toLowerCase();
+    const newLower = newName.toLowerCase();
+    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);
+    }
+    const module = requireVtabModule(tableSchema);
+    if (!module.alterTable) {
+        throw new QuereusError(`Module for table '${tableSchema.name}' does not support ALTER TABLE RENAME CONSTRAINT`, StatusCode.UNSUPPORTED);
+    }
+    const updatedTableSchema = await module.alterTable(rctx.db, tableSchema.schemaName, tableSchema.name, {
+        type: 'renameConstraint',
+        oldName,
+        newName,
+    });
+    schema.addTable(updatedTableSchema);
+    rctx.db.schemaManager.getChangeNotifier().notifyChange({
+        type: 'table_modified',
+        schemaName: tableSchema.schemaName,
+        objectName: tableSchema.name,
+        oldObject: tableSchema,
+        newObject: updatedTableSchema,
+    });
+    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
+ * shadow — dropping/renaming it alone would strand the index, so the user must
+ * operate on the index (`DROP INDEX`) instead.
+ */
+function rejectDerivedFromIndex(tableSchema, constraintName, op) {
+    const lower = constraintName.toLowerCase();
+    const uc = (tableSchema.uniqueConstraints ?? []).find(c => c.name?.toLowerCase() === lower);
+    if (uc?.derivedFromIndex) {
+        throw new QuereusError(`Cannot ${op} CONSTRAINT '${constraintName}' on '${tableSchema.name}': it is backed by index '${uc.derivedFromIndex}' (created via CREATE UNIQUE INDEX). Use DROP INDEX '${uc.derivedFromIndex}' instead.`, StatusCode.CONSTRAINT);
+    }
+}
 async function runAlterColumn(rctx, tableSchema, schema, action) {
     const colIndex = tableSchema.columnIndexMap.get(action.columnName.toLowerCase());
     if (colIndex === undefined) {
         throw new QuereusError(`Column '${action.columnName}' not found in table '${tableSchema.name}'`, StatusCode.ERROR);
     }
-    // Guard: at most one of the three attribute changes per statement.
-    const populated = [action.setNotNull !== undefined, action.setDataType !== undefined, action.setDefault !== undefined];
+    // Guard: at most one of the four attribute changes per statement.
+    const populated = [action.setNotNull !== undefined, action.setDataType !== undefined, action.setDefault !== undefined, action.setCollation !== undefined];
     const populatedCount = populated.filter(Boolean).length;
     if (populatedCount !== 1) {
-        throw new QuereusError(`ALTER COLUMN requires exactly one of SET/DROP NOT NULL, SET DATA TYPE, SET/DROP DEFAULT (got ${populatedCount})`, StatusCode.INTERNAL);
+        throw new QuereusError(`ALTER COLUMN requires exactly one of SET/DROP NOT NULL, SET DATA TYPE, SET/DROP DEFAULT, SET COLLATE (got ${populatedCount})`, StatusCode.INTERNAL);
     }
-    // Cannot alter a PRIMARY KEY column's nullability or data type.
+    // Cannot alter a PRIMARY KEY column's nullability or data type. (SET COLLATE on
+    // a PK column IS permitted — the module re-keys the primary structure under the
+    // new collation; see runAlterColumn module contract.)
     if (tableSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
         if (action.setNotNull === false) {
             throw new QuereusError(`Cannot DROP NOT NULL on PRIMARY KEY column '${action.columnName}'`, StatusCode.CONSTRAINT);
@@ -395,7 +720,21 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
             throw new QuereusError(`Cannot SET DATA TYPE on PRIMARY KEY column '${action.columnName}'`, StatusCode.CONSTRAINT);
         }
     }
-    const module = tableSchema.vtabModule;
+    // SET COLLATE: validate the collation against the column's logical type up front
+    // (same error shape as CREATE TABLE), so an unknown collation is rejected before
+    // any module round-trip / re-sort. The module re-normalizes and applies it.
+    if (action.setCollation !== undefined) {
+        validateCollationForType(action.setCollation, tableSchema.columns[colIndex].logicalType, action.columnName);
+    }
+    // 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
+    // time). DROP DEFAULT (`setDefault === null`) needs no validation.
+    if (action.setDefault !== undefined && action.setDefault !== null) {
+        const hasMutationContext = !!tableSchema.mutationContext && tableSchema.mutationContext.length > 0;
+        rctx.db.schemaManager.validateAlterColumnDefault(action.setDefault, action.columnName, tableSchema.name, hasMutationContext);
+    }
+    const module = requireVtabModule(tableSchema);
     if (!module.alterTable) {
         throw new QuereusError(`Module for table '${tableSchema.name}' does not support ALTER COLUMN`, StatusCode.UNSUPPORTED);
     }
@@ -405,6 +744,7 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
         setNotNull: action.setNotNull,
         setDataType: action.setDataType,
         setDefault: action.setDefault,
+        setCollation: action.setCollation,
     });
     schema.addTable(updatedTableSchema);
     rctx.db.schemaManager.getChangeNotifier().notifyChange({
@@ -417,6 +757,73 @@ async function runAlterColumn(rctx, tableSchema, schema, action) {
     log('Altered column %s.%s.%s', tableSchema.schemaName, tableSchema.name, action.columnName);
     return null;
 }
+/**
+ * Catalog-only metadata-tag mutations. Tags touch no stored row and no physical
+ * layout, so these never call `module.alterTable` — they delegate to the
+ * SchemaManager setters, which swap the in-memory schema and fire `table_modified`
+ * (so optimizer caches invalidate). This makes SET TAGS succeed even on modules
+ * without an `alterTable` hook.
+ *
+ * NOTE: store-backed modules persist DDL from their own `alterTable`, which this
+ * path deliberately bypasses. The generic store module recovers the tag change by
+ * subscribing to these `table_modified` events and re-writing its catalog DDL, so
+ * table / column / named-constraint tag swaps now survive reconnect for store
+ * tables (index and view/MV tag persistence is still pending — see backlog tickets
+ * `store-secondary-index-persistence` / `store-view-mv-persistence`).
+ */
+function runSetTableTags(rctx, tableSchema, tags) {
+    rctx.db.schemaManager.setTableTags(tableSchema.name, tags, tableSchema.schemaName);
+    log('Set tags on table %s.%s', tableSchema.schemaName, tableSchema.name);
+    return null;
+}
+function runSetColumnTags(rctx, tableSchema, columnName, tags) {
+    rctx.db.schemaManager.setColumnTags(tableSchema.name, columnName, tags, tableSchema.schemaName);
+    log('Set tags on column %s.%s.%s', tableSchema.schemaName, tableSchema.name, columnName);
+    return null;
+}
+function runSetConstraintTags(rctx, tableSchema, constraintName, tags) {
+    rctx.db.schemaManager.setConstraintTags(tableSchema.name, constraintName, tags, tableSchema.schemaName);
+    log('Set tags on constraint %s.%s.%s', tableSchema.schemaName, tableSchema.name, constraintName);
+    return null;
+}
+// ── ADD TAGS (per-key merge) ──
+// Each delegates to the matching SchemaManager merge setter, which reads the
+// table's *live* tags at execution time (not the plan-time snapshot), so a
+// prepared/reused ADD TAGS or back-to-back ALTERs compose onto the prior result.
+function runMergeTableTags(rctx, tableSchema, tags) {
+    rctx.db.schemaManager.mergeTableTags(tableSchema.name, tags, tableSchema.schemaName);
+    log('Merged tags on table %s.%s', tableSchema.schemaName, tableSchema.name);
+    return null;
+}
+function runMergeColumnTags(rctx, tableSchema, columnName, tags) {
+    rctx.db.schemaManager.mergeColumnTags(tableSchema.name, columnName, tags, tableSchema.schemaName);
+    log('Merged tags on column %s.%s.%s', tableSchema.schemaName, tableSchema.name, columnName);
+    return null;
+}
+function runMergeConstraintTags(rctx, tableSchema, constraintName, tags) {
+    rctx.db.schemaManager.mergeConstraintTags(tableSchema.name, constraintName, tags, tableSchema.schemaName);
+    log('Merged tags on constraint %s.%s.%s', tableSchema.schemaName, tableSchema.name, constraintName);
+    return null;
+}
+// ── DROP TAGS (per-key delete) ──
+// Each delegates to the matching SchemaManager drop setter, which validates that
+// every listed key is present (atomic NOTFOUND) before mutating, again against the
+// live tags at execution time.
+function runDropTableTags(rctx, tableSchema, keys) {
+    rctx.db.schemaManager.dropTableTags(tableSchema.name, keys, tableSchema.schemaName);
+    log('Dropped tags on table %s.%s', tableSchema.schemaName, tableSchema.name);
+    return null;
+}
+function runDropColumnTags(rctx, tableSchema, columnName, keys) {
+    rctx.db.schemaManager.dropColumnTags(tableSchema.name, columnName, keys, tableSchema.schemaName);
+    log('Dropped tags on column %s.%s.%s', tableSchema.schemaName, tableSchema.name, columnName);
+    return null;
+}
+function runDropConstraintTags(rctx, tableSchema, constraintName, keys) {
+    rctx.db.schemaManager.dropConstraintTags(tableSchema.name, constraintName, keys, tableSchema.schemaName);
+    log('Dropped tags on constraint %s.%s.%s', tableSchema.schemaName, tableSchema.name, constraintName);
+    return null;
+}
 async function runAlterPrimaryKey(rctx, tableSchema, schema, columns) {
     const newPkDef = columns.map(col => {
         const idx = tableSchema.columnIndexMap.get(col.name.toLowerCase());
@@ -438,7 +845,7 @@ async function runAlterPrimaryKey(rctx, tableSchema, schema, columns) {
         seen.add(pk.index);
     }
     // Try native module re-key first
-    const module = tableSchema.vtabModule;
+    const module = requireVtabModule(tableSchema);
     if (module.alterTable) {
         try {
             const schemaChangePk = newPkDef.map(pk => ({ index: pk.index, desc: pk.desc ?? false }));
@@ -477,7 +884,7 @@ async function runAlterPrimaryKey(rctx, tableSchema, schema, columns) {
 async function rebuildTableWithNewShape(rctx, tableSchema, schema, survivingColumns, newPkDef) {
     const tableName = tableSchema.name;
     const schemaName = tableSchema.schemaName;
-    const module = tableSchema.vtabModule;
+    const module = requireVtabModule(tableSchema);
     if (module instanceof MemoryTableModule) {
         await rebuildMemoryTable(rctx, tableSchema, schema, module, survivingColumns, newPkDef);
     }
@@ -556,6 +963,16 @@ async function rebuildMemoryTable(rctx, tableSchema, schema, module, survivingCo
         // 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
@@ -613,6 +1030,64 @@ export function buildShadowTableDdl(tableSchema, shadowName, survivingColumns, n
     }
     return createDdl;
 }
+/**
+ * SET MAINTAINED [(cols)] AS <body> — attach a derivation to a plain table, or
+ * atomically replace an already-maintained table's derivation (the differ's
+ * body-change primitive). All gates, the verify-by-diff reconcile, the
+ * catalog/registration flip, the consumer cascade, and the lifecycle event
+ * (`materialized_view_added` on fresh attach, `materialized_view_modified` on
+ * re-attach) live in the shared {@link attachMaintainedDerivation} core.
+ * Resolved against the LIVE table (the build-time schema may be a cached
+ * statement's snapshot).
+ *
+ * The optional `columns` rename list selects the attach mode:
+ *  - present ⇒ EXPLICIT: the body outputs are renamed positionally to it, the
+ *    list is recorded as `derivation.columns`, and a same-arity name drift
+ *    reshapes (renames) the backing in place to the listed names — the differ's
+ *    lossless re-attach of an MV-sugar `(a, c)` rename;
+ *  - absent ⇒ IMPLICIT: the body's natural names are recorded (undefined), and a
+ *    differing derived shape reshapes the backing to follow the body — now also
+ *    over a prior-explicit record (the deliberate "go implicit" re-attach).
+ * Both pass `allowReshape` (the verb is the reshape-permitting path; create stays
+ * strict).
+ */
+async function runSetMaintained(rctx, tableSchema, schema, columns, select) {
+    const live = schema.getTable(tableSchema.name);
+    if (!live) {
+        throw new QuereusError(`no such table: ${tableSchema.name}`, StatusCode.ERROR);
+    }
+    const explicit = columns !== undefined && columns.length > 0;
+    // Any omitted-insert defaults ride inside `select` (→ derivation.selectAst).
+    await attachMaintainedDerivation(rctx.db, live, select, 
+    /*recordedColumns*/ explicit ? columns : undefined, 
+    /*positionalRename*/ explicit, /*allowReshape*/ true, 
+    /*discardBackingOnFailure*/ true);
+    log('Attached derivation to table %s.%s', live.schemaName, live.name);
+    return null;
+}
+/**
+ * DROP MAINTAINED — detach the table's derivation (see
+ * {@link detachMaintainedDerivation}: catalog-only, rows intact, maintenance
+ * stops, the table becomes ordinary and user-writable). Allowed on a STALE
+ * maintained table too — the flag leaves with the derivation. Resolved against
+ * the LIVE table.
+ */
+async function runDropMaintained(rctx, tableSchema, schema) {
+    const live = schema.getTable(tableSchema.name);
+    if (!live || !isMaintainedTable(live)) {
+        throw new QuereusError(`cannot drop maintained on '${tableSchema.name}': it is not a maintained table`, StatusCode.ERROR);
+    }
+    const plain = detachMaintainedDerivation(rctx.db, live);
+    // Retire the durable backing store the attach materialized, migrating its
+    // rows back into ordinary storage so the detached table stays readable and
+    // user-writable. `detachMaintainedDerivation` stays SYNC (catalog-only); the
+    // async store retirement rides here, in its sole caller. A no-op for modules
+    // that omit the hook (memory detaches catalog-only — one physical storage).
+    const module = requireVtabModule(live);
+    await module.retireBackingForAttach?.(rctx.db, plain.schemaName, plain.name, plain);
+    log('Detached derivation from table %s.%s', live.schemaName, live.name);
+    return null;
+}
 /**
  * Generic rebuild via shadow table SQL for non-memory modules.
  */
@@ -640,18 +1115,23 @@ async function rebuildViaShadowTable(rctx, tableSchema, schema, survivingColumns
 }
 /**
  * Propagates a table rename into every dependent schema object the catalog
- * knows about: CHECK expressions, FK references, and view bodies. Walks every
- * schema (not just the renamed table's home schema) so cross-schema FK
- * references are picked up. View `selectAst` is mutated in place because the
- * planner re-walks it on every reference.
+ * knows about: CHECK expressions, FK references, partial-index predicates,
+ * view bodies, and materialized-view bodies. Walks every schema (not just the
+ * renamed table's home schema) so cross-schema FK references are picked up.
+ * View `selectAst` is mutated in place because the planner re-walks it on
+ * every reference.
  */
-function propagateTableRename(rctx, renamedSchemaName, oldName, newName) {
-    const notifier = rctx.db.schemaManager.getChangeNotifier();
+async function propagateTableRename(rctx, renamedSchemaName, oldName, newName, preStaleMvs) {
     for (const schema of rctx.db.schemaManager._getAllSchemas()) {
-        propagateTableRenameInSchema(schema, renamedSchemaName, oldName, newName, notifier);
+        await propagateTableRenameInSchema(rctx.db, schema, renamedSchemaName, oldName, newName, preStaleMvs);
     }
+    // After all per-schema rewrites and their cascade events: restore any MV this
+    // statement's events marked stale that the rename provably did not affect
+    // (e.g. a dependent of another source whose only change was an FK rewrite).
+    await restoreUnaffectedMaterializedViews(rctx.db, preStaleMvs);
 }
-function propagateTableRenameInSchema(schema, renamedSchemaName, oldName, newName, notifier) {
+async function propagateTableRenameInSchema(db, schema, renamedSchemaName, oldName, newName, preStaleMvs) {
+    const notifier = db.schemaManager.getChangeNotifier();
     const renamedSchemaLower = renamedSchemaName.toLowerCase();
     for (const table of Array.from(schema.getAllTables())) {
         // Skip the just-renamed table when iterating the home schema; the FK
@@ -671,12 +1151,33 @@ function propagateTableRenameInSchema(schema, renamedSchemaName, oldName, newNam
     }
     if (schema.name.toLowerCase() === renamedSchemaLower) {
         for (const view of Array.from(schema.getAllViews())) {
-            const changed = renameTableInAst(view.selectAst, oldName, newName, renamedSchemaName);
-            if (changed) {
-                const updatedView = { ...view, sql: selectToString(view.selectAst) };
+            // The body walk also descends the trailing `with defaults (…)` clause
+            // (now stored on `selectAst.defaults`), so a clause-only rewrite — a
+            // defaults-expr subquery referencing the renamed table even when the body
+            // never names it — flips `bodyChanged` and fires the (single) view_modified.
+            const bodyChanged = renameTableInAst(view.selectAst, oldName, newName, renamedSchemaName);
+            if (bodyChanged) {
+                const updatedView = { ...view, sql: astToString(view.selectAst) };
                 schema.addView(updatedView);
+                // The rewriter mutated `view.selectAst` (including its defaults clause) in
+                // place, so `oldObject` shares the rewritten AST (only `newObject.sql`
+                // differs). No consumer reads `oldObject.selectAst`; mirrors the table
+                // loop above (no clone).
+                notifier.notifyChange({
+                    type: 'view_modified',
+                    schemaName: schema.name,
+                    objectName: updatedView.name,
+                    oldObject: view,
+                    newObject: updatedView,
+                });
             }
         }
+        // Materialized views: same in-place body rewrite as plain views ("MV ≡
+        // faster view"), plus the derived-field re-key, row-time re-registration,
+        // and staleness discipline the MV record needs. Runs AFTER the view loop
+        // so a body reading the renamed table through a view re-plans against the
+        // already-rewritten view.
+        await propagateTableRenameToMaterializedViews(db, schema, renamedSchemaName, oldName, newName, preStaleMvs);
     }
 }
 function rewriteTableForTableRename(table, renamedSchemaLower, oldName, newName) {
@@ -698,27 +1199,43 @@ function rewriteTableForTableRename(table, renamedSchemaLower, oldName, newName)
         changed = true;
         return { ...fk, referencedTable: newName };
     });
+    // Partial-index predicates: the AST is mutated in place, so the derived
+    // UNIQUE constraint of a unique partial index (which shares the predicate
+    // by reference — see appendIndexToTableSchema) is rewritten with it.
+    const newIndexes = (table.indexes ?? []).map(idx => {
+        const rewrote = renameTableInAst(idx.predicate, oldName, newName, renamedSchemaLower);
+        if (!rewrote)
+            return idx;
+        changed = true;
+        return { ...idx };
+    });
     if (!changed)
         return table;
     return Object.freeze({
         ...table,
         checkConstraints: Object.freeze(newChecks),
         foreignKeys: table.foreignKeys ? Object.freeze(newFks) : table.foreignKeys,
+        indexes: table.indexes ? Object.freeze(newIndexes) : table.indexes,
     });
 }
-function propagateColumnRename(rctx, renamedSchemaName, tableName, oldCol, newCol) {
+async function propagateColumnRename(rctx, renamedSchemaName, tableName, oldCol, newCol, preStaleMvs) {
     const schemaManager = rctx.db.schemaManager;
-    const notifier = schemaManager.getChangeNotifier();
     const resolveColumnInSource = (s, t, col) => {
         const targetSchema = schemaManager.getSchema(s);
         const targetTable = targetSchema?.getTable(t);
         return targetTable?.columnIndexMap.has(col.toLowerCase()) ?? false;
     };
     for (const schema of schemaManager._getAllSchemas()) {
-        propagateColumnRenameInSchema(schema, renamedSchemaName, tableName, oldCol, newCol, notifier, resolveColumnInSource);
+        await propagateColumnRenameInSchema(rctx.db, schema, renamedSchemaName, tableName, oldCol, newCol, resolveColumnInSource, preStaleMvs);
     }
+    // After all per-schema rewrites and their cascade events: restore any MV this
+    // statement's events marked stale that the rename provably did not affect — a
+    // body that never names the renamed column, or a `select *` body whose output
+    // is a pure name shift (carried onto the live backing by the pass).
+    await restoreUnaffectedMaterializedViews(rctx.db, preStaleMvs);
 }
-function propagateColumnRenameInSchema(schema, renamedSchemaName, tableName, oldCol, newCol, notifier, resolveColumnInSource) {
+async function propagateColumnRenameInSchema(db, schema, renamedSchemaName, tableName, oldCol, newCol, resolveColumnInSource, preStaleMvs) {
+    const notifier = db.schemaManager.getChangeNotifier();
     const renamedSchemaLower = renamedSchemaName.toLowerCase();
     for (const table of Array.from(schema.getAllTables())) {
         const updated = rewriteTableForColumnRename(table, renamedSchemaLower, tableName, oldCol, newCol, resolveColumnInSource);
@@ -735,12 +1252,37 @@ function propagateColumnRenameInSchema(schema, renamedSchemaName, tableName, old
     }
     if (schema.name.toLowerCase() === renamedSchemaLower) {
         for (const view of Array.from(schema.getAllViews())) {
-            const changed = renameColumnInAst(view.selectAst, tableName, oldCol, newCol, renamedSchemaName);
-            if (changed) {
-                const updatedView = { ...view, sql: selectToString(view.selectAst) };
+            // The body walk also descends the trailing `with defaults (…)` clause (now
+            // on `selectAst.defaults`): the entry `column` (a base column of the view's
+            // FROM table, usually projected away) rewrites via the same scope-aware
+            // synthetic probe as a `with inverse` target, and the entry exprs rewrite in
+            // the FROM frame — so a clause-only change flips `bodyChanged`. The live
+            // `resolveColumnInSource` keeps the walk scope-aware so an unqualified ref
+            // inside a defaults-expr subquery that binds a like-named column on its own
+            // FROM is not false-captured (the differ's inverse reconcile passes the
+            // declared-side resolver for parity).
+            const bodyChanged = renameColumnInAst(view.selectAst, tableName, oldCol, newCol, renamedSchemaName, resolveColumnInSource);
+            if (bodyChanged) {
+                const updatedView = { ...view, sql: astToString(view.selectAst) };
                 schema.addView(updatedView);
+                // The rewriter mutated `view.selectAst` (including its defaults clause) in
+                // place, so `oldObject` shares the rewritten AST (only `sql` differs). No
+                // consumer reads `oldObject.selectAst`; mirrors the table loop above (no clone).
+                notifier.notifyChange({
+                    type: 'view_modified',
+                    schemaName: schema.name,
+                    objectName: updatedView.name,
+                    oldObject: view,
+                    newObject: updatedView,
+                });
             }
         }
+        // Materialized views: same in-place body rewrite as plain views, then the
+        // MV-specific tail — backing-column rename for a shifted output name,
+        // row-time re-registration, staleness discipline (the listener marked every
+        // dependent MV stale during the rename's notify; only statement-local
+        // staleness is cleared, per the pre-statement snapshot).
+        await propagateColumnRenameToMaterializedViews(db, schema, renamedSchemaName, tableName, oldCol, newCol, preStaleMvs, resolveColumnInSource);
     }
 }
 function rewriteTableForColumnRename(table, renamedSchemaLower, tableName, oldCol, newCol, resolveColumnInSource) {
@@ -779,12 +1321,26 @@ function rewriteTableForColumnRename(table, renamedSchemaLower, tableName, oldCo
         changed = true;
         return { ...fk, referencedColumnNames: Object.freeze(newRefNames) };
     });
+    // Partial-index predicates resolve unqualified refs against the indexed
+    // table, the same implicit seed CHECK expressions use. As with checks, the
+    // AST is mutated in place, so the derived UNIQUE constraint of a unique
+    // partial index (sharing the predicate by reference) is rewritten with it.
+    const newIndexes = (table.indexes ?? []).map(idx => {
+        const rewrote = isRenamedTable
+            ? renameColumnInCheckExpression(idx.predicate, tableName, oldCol, newCol, renamedSchemaLower, resolveColumnInSource)
+            : renameColumnInAst(idx.predicate, tableName, oldCol, newCol, renamedSchemaLower);
+        if (!rewrote)
+            return idx;
+        changed = true;
+        return { ...idx };
+    });
     if (!changed)
         return table;
     return Object.freeze({
         ...table,
         checkConstraints: Object.freeze(newChecks),
         foreignKeys: table.foreignKeys ? Object.freeze(newFks) : table.foreignKeys,
+        indexes: table.indexes ? Object.freeze(newIndexes) : table.indexes,
     });
 }
 /**