@quereus/quereus 3.3.0 → 4.1.0

package/dist/src/schema/manager.js

@@ -1,7 +1,13 @@
 import { Schema } from './schema.js';
+import { normalizeCollationName } from '../util/comparison.js';
 import { quereusError, QuereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
-import { buildColumnIndexMap, columnDefToSchema, findPKDefinition, opsToMask, mutationContextVarToSchema, extractGeneratedColumnDependencies, topoSortGeneratedColumns } from './table.js';
+import { buildColumnIndexMap, columnDefToSchema, findPKDefinition, opsToMask, mutationContextVarToSchema, extractGeneratedColumnDependencies, topoSortGeneratedColumns, requireVtabModule, resolveNamedConstraintClass, appendIndexToTableSchema } from './table.js';
+import { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, validateForeignKeyCollations } from './constraint-builder.js';
+import { normalizeBackingModule } from './view.js';
+import { isMaintainedTable } from './derivation.js';
+import { isHiddenImplicitIndex, findExposedImplicitConstraintIndex } from './catalog.js';
+import { buildLensBasisFkGate } from './lens-fk-discovery.js';
 import { createLogger } from '../common/logger.js';
 import { Parser } from '../parser/parser.js';
 import { traverseAst } from '../parser/visitor.js';
@@ -13,10 +19,49 @@ import { BuildTimeDependencyTracker } from '../planner/planning-context.js';
 import { GlobalScope } from '../planner/scopes/global.js';
 import { ParameterScope } from '../planner/scopes/param.js';
 import { hasNativeEventSupport } from '../util/event-support.js';
-import { quoteIdentifier } from '../emit/ast-stringify.js';
+import { quoteIdentifier, createViewToString, astToString } from '../emit/ast-stringify.js';
+import { materializeView, adoptMaterializedView, deriveBackingShape, backingShapeMatches, assertDeclaredColumnArity } from '../runtime/emit/materialized-view-helpers.js';
 const log = createLogger('schema:manager');
 const warnLog = log.extend('warn');
 const errorLog = log.extend('error');
+/**
+ * Shared frozen empty result for the reverse-FK lookup miss (the O(1)
+ * unreferenced-table gate), so the hot path allocates nothing per call.
+ */
+const EMPTY_REFERENCING_FKS = Object.freeze([]);
+/** Build the import spec from the `create materialized view` sugar form. */
+function maintainedImportFromMvStmt(stmt) {
+    return {
+        schemaName: stmt.view.schema,
+        name: stmt.view.name,
+        select: stmt.select,
+        columns: stmt.columns,
+        moduleName: stmt.moduleName,
+        moduleArgs: stmt.moduleArgs,
+        tags: stmt.tags,
+    };
+}
+/**
+ * Build the import spec from the canonical `create table … maintained as …` form
+ * (the unified-model persistence / export form). The rename list is read from the
+ * `maintained [(columns)]` clause, NOT the declared column list: its presence is
+ * the lossless flag that distinguishes an explicit MV-sugar rename (arity-locks —
+ * a widened source is a sited error) from an implicit `select *` body (reshapes to
+ * follow its source on reopen). `generateMaintainedTableDDL` emits the clause iff
+ * the derivation carries a rename, so this restores `derivation.columns` faithfully.
+ */
+function maintainedImportFromTableStmt(stmt) {
+    const maintained = stmt.maintained;
+    return {
+        schemaName: stmt.table.schema,
+        name: stmt.table.name,
+        select: maintained.select,
+        columns: maintained.columns,
+        moduleName: stmt.moduleName,
+        moduleArgs: stmt.moduleArgs,
+        tags: stmt.tags,
+    };
+}
 /**
  * Manages all schemas associated with a database connection (main, temp, attached).
  * Handles lookup resolution according to SQLite's rules.
@@ -38,6 +83,44 @@ export class SchemaManager {
      * See `assertion-hoist-cache.ts` and `core/database-assertions.ts`.
      */
     assertionHoistSuppressed = 0;
+    /**
+     * Re-entrancy guard: when truthy, the read-side materialized-view query-rewrite
+     * rule (`rule-materialized-view-rewrite.ts`) is suppressed. Set while planning a
+     * materialized view's own body for the purpose of (re)computing or maintaining
+     * its backing table (create / refresh / row-time-maintenance compile). Without
+     * it, the rewrite rule would recognize the MV's body as "answered from" the MV
+     * itself and rewrite it to scan the backing table being populated — reading a
+     * stale/empty snapshot instead of recomputing from the source.
+     */
+    mvRewriteSuppressed = 0;
+    /**
+     * Catalog-level reverse foreign-key index: referenced `schema.table`
+     * (lowercased) → the FKs that reference it. `null` ⇒ needs a (re)build from
+     * the live catalog on next access — a pure derived cache, nulled on every
+     * mutation that can add/drop/retarget an FK or add/remove a schema (see
+     * {@link invalidateReverseFkIndex}). See `getReferencingForeignKeys`.
+     */
+    reverseFkIndex = null;
+    /**
+     * Lens basis-FK gate: the set of basis `schema.table` keys (lowercased) that
+     * back ≥1 logical parent slot referenced by ≥1 logical FK — the logical-FK
+     * analogue of {@link reverseFkIndex}. `null` ⇒ rebuild from the live catalog on
+     * next access. A pure derived cache (built by {@link buildLensBasisFkGate}),
+     * nulled on every event that can change the underlying slot scan: lens deploy
+     * (no `SchemaChangeEvent` fires — `lens-compiler` calls
+     * {@link invalidateLensFkGate} directly), any `table_added`/`_modified`/`_removed`
+     * (basis-table catalog change, via the constructor listener), and schema
+     * attach/detach/reset (no event — invalidated directly).
+     *
+     * Soundness invariant (load-bearing): a stale gate that **under-reports** would
+     * silently drop logical FK enforcement (cascade not propagated / RESTRICT not
+     * enforced / divergent basis action not suppressed) — the fatal direction — so
+     * invalidation must be exhaustive. Built from, and reset alongside, the same
+     * catalog state the three lens FK paths scan, it never under-reports for the
+     * current catalog; over-reporting (a stray key ⇒ an on-hit scan that finds
+     * nothing) is harmless. See {@link basisTableBacksLogicalParentFk}.
+     */
+    lensFkGate = null;
     /**
      * Creates a new schema manager
      *
@@ -48,6 +131,27 @@ export class SchemaManager {
         // Ensure 'main' and 'temp' schemas always exist
         this.schemas.set('main', new Schema('main'));
         this.schemas.set('temp', new Schema('temp'));
+        // Self-subscribe so any table FK-lifecycle event invalidates the reverse FK
+        // index. An FK is declared on a table, and a table enters/leaves/changes the
+        // catalog ONLY through one of these events: `create table … references`
+        // (table_added), `alter table add/drop constraint` and FK retargets from a
+        // parent/column rename (table_modified), and `drop table` (table_removed) —
+        // so this is exhaustive. The body just nulls the cache (rebuild happens on
+        // next access, never inside the listener), so subscribing to our own notifier
+        // is order-independent and safe. Schema ATTACH/DETACH fire no event, so those
+        // invalidate directly in addSchema/getOrCreateSchema/removeSchema. The
+        // listener lifetime is the SchemaManager's (no disposal path to unsubscribe).
+        // The same table events also change basis-table resolution for the lens
+        // basis-FK gate (a basis table created after the gate was built is the
+        // under-report vector; a drop / column-rename can change which slot resolves
+        // to which basis), so reset it on the same events. Lens-slot lifecycle fires
+        // no event — `lens-compiler.deployLogicalSchema` invalidates the gate directly.
+        this.changeNotifier.addListener(event => {
+            if (event.type === 'table_added' || event.type === 'table_modified' || event.type === 'table_removed') {
+                this.invalidateReverseFkIndex();
+                this.invalidateLensFkGate();
+            }
+        });
     }
     /**
      * Sets the current default schema for unqualified names
@@ -224,7 +328,7 @@ export class SchemaManager {
         if (existing) {
             this.changeNotifier.notifyChange({
                 type: 'assertion_modified',
-                schemaName: schemaName,
+                schemaName: schema.name,
                 objectName: assertion.name,
                 oldObject: existing,
                 newObject: assertion,
@@ -233,7 +337,7 @@ export class SchemaManager {
         else {
             this.changeNotifier.notifyChange({
                 type: 'assertion_added',
-                schemaName: schemaName,
+                schemaName: schema.name,
                 objectName: assertion.name,
                 newObject: assertion,
             });
@@ -254,7 +358,7 @@ export class SchemaManager {
         if (removed) {
             this.changeNotifier.notifyChange({
                 type: 'assertion_removed',
-                schemaName: schemaName,
+                schemaName: schema.name,
                 objectName: name,
                 oldObject: existing,
             });
@@ -289,21 +393,80 @@ export class SchemaManager {
             this.assertionHoistSuppressed--;
         }
     }
+    /**
+     * True when the read-side materialized-view query-rewrite rule must be
+     * suppressed (the caller is currently planning an MV's own body to recompute or
+     * maintain its backing). Read by `rule-materialized-view-rewrite.ts`.
+     */
+    isMaterializedViewRewriteSuppressed() {
+        return this.mvRewriteSuppressed > 0;
+    }
+    /**
+     * Run a synchronous `fn` with the materialized-view query-rewrite rule
+     * suppressed. Re-entrant via a depth counter; always restores state, even on
+     * throw. Wrap every place that plans an MV body to (re)compute its backing.
+     */
+    withSuppressedMaterializedViewRewrite(fn) {
+        this.mvRewriteSuppressed++;
+        try {
+            return fn();
+        }
+        finally {
+            this.mvRewriteSuppressed--;
+        }
+    }
+    /** Async counterpart of {@link withSuppressedMaterializedViewRewrite}. */
+    async withSuppressedMaterializedViewRewriteAsync(fn) {
+        this.mvRewriteSuppressed++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.mvRewriteSuppressed--;
+        }
+    }
     /**
      * Adds a new schema (e.g., for ATTACH)
      *
      * @param name Name of the schema to add
+     * @param kind Whether the schema is module-backed (`physical`, default) or
+     *   design-only (`logical`). See `docs/lens.md` § Schema Kinds.
      * @returns The newly created schema
      * @throws QuereusError if the name conflicts with an existing schema
      */
-    addSchema(name) {
+    addSchema(name, kind = 'physical') {
         const lowerName = name.toLowerCase();
         if (this.schemas.has(lowerName)) {
             throw new QuereusError(`Schema '${name}' already exists`, StatusCode.ERROR);
         }
-        const schema = new Schema(lowerName);
+        const schema = new Schema(lowerName, kind);
         this.schemas.set(lowerName, schema);
-        log(`Added schema '%s'`, lowerName);
+        // ATTACH can bring (or, via later import, an attached schema can hold) a
+        // cross-schema FK target; this method fires no change event, so reset directly.
+        // A logical-schema ATTACH likewise brings lens slots, so reset the lens gate too.
+        this.invalidateReverseFkIndex();
+        this.invalidateLensFkGate();
+        log(`Added schema '%s' (kind=%s)`, lowerName, kind);
+        return schema;
+    }
+    /**
+     * Returns the named schema, lazily creating an empty (physical) one if absent.
+     * Used by the catalog-import paths ({@link importTable}/{@link importView}) so an
+     * object can rehydrate into a schema that holds no tables yet — making import
+     * order-independent. Unlike {@link addSchema} this never throws on an existing
+     * schema.
+     */
+    getOrCreateSchema(name) {
+        const lowerName = name.toLowerCase();
+        let schema = this.schemas.get(lowerName);
+        if (!schema) {
+            schema = new Schema(lowerName);
+            this.schemas.set(lowerName, schema);
+            // Fires no change event; a cross-schema FK can land in/under this schema, and
+            // a lens slot can later resolve a basis under it — reset both derived caches.
+            this.invalidateReverseFkIndex();
+            this.invalidateLensFkGate();
+        }
         return schema;
     }
     /**
@@ -324,7 +487,14 @@ export class SchemaManager {
             schema.clearTables();
             schema.clearViews();
             schema.clearAssertions();
+            schema.clearLensSlots();
             this.schemas.delete(lowerName);
+            // DETACH fires no change event, yet a cross-schema FK may have keyed
+            // under (or referenced from) this schema; reset directly. The schema's lens
+            // slots (cleared above) also leave the gate stale — a basis re-attach after a
+            // stale-but-non-null gate could under-report — so reset it too.
+            this.invalidateReverseFkIndex();
+            this.invalidateLensFkGate();
             log(`Removed schema '%s'`, name);
             return true;
         }
@@ -416,6 +586,49 @@ export class SchemaManager {
         const schema = this.schemas.get(targetSchemaName);
         return schema?.getView(viewName);
     }
+    /**
+     * Retrieves a maintained table (a table carrying a derivation — what
+     * `create materialized view` produces) by name.
+     *
+     * @param schemaName The schema name ('main', etc.). Defaults to current schema
+     * @param name The maintained table's name
+     */
+    getMaintainedTable(schemaName, name) {
+        const table = this.getTable(schemaName ?? undefined, name);
+        return isMaintainedTable(table) ? table : undefined;
+    }
+    /**
+     * Returns all maintained tables (derivation-bearing tables) across all schemas.
+     */
+    getAllMaintainedTables() {
+        const result = [];
+        for (const schema of this.schemas.values()) {
+            for (const table of schema.getAllTables()) {
+                if (isMaintainedTable(table))
+                    result.push(table);
+            }
+        }
+        return result;
+    }
+    /**
+     * Attaches (or replaces) a derivation on an already-registered table,
+     * swapping the registered record for `{...table, derivation}`. Fires no
+     * event — callers own the event discipline (create fires
+     * `materialized_view_added`; import stays silent). Returns the swapped
+     * maintained table.
+     *
+     * @throws QuereusError if the table is not registered.
+     */
+    attachDerivation(schemaName, tableName, derivation) {
+        const schema = this.getSchemaOrFail(schemaName);
+        const table = schema.getTable(tableName);
+        if (!table) {
+            throw new QuereusError(`Cannot attach derivation: table '${schemaName}.${tableName}' not found`, StatusCode.INTERNAL);
+        }
+        const maintained = { ...table, derivation };
+        schema.addTable(maintained);
+        return maintained;
+    }
     /**
      * Retrieves any schema item (table or view) by name. Checks views first
      *
@@ -446,6 +659,79 @@ export class SchemaManager {
         const tableSchema = this.getTable(targetSchemaName, tableName);
         return tableSchema?.tags;
     }
+    /**
+     * Freezes a whole-set tag replacement: an empty record stores `undefined`
+     * (so `tags IS NULL` and the differ's "no tags" both hold), a non-empty one a
+     * frozen copy. Shared by the three catalog-only tag setters.
+     */
+    freezeTags(tags) {
+        return Object.keys(tags).length > 0 ? Object.freeze({ ...tags }) : undefined;
+    }
+    /**
+     * Computes the next frozen tag record from the current one plus a per-key
+     * mutation, reusing {@link freezeTags} for the empty→`undefined` collapse.
+     *
+     *  - `merge`: shallow-overlay the new keys onto the current set (overwrite on
+     *    collision), keeping the rest. A merge of a non-empty payload can never empty
+     *    the set; an empty merge of an empty set collapses to `undefined`.
+     *  - `drop`: every listed key must currently be present (atomic). Any missing key
+     *    raises `NOTFOUND` naming the offenders and mutates nothing; otherwise the keys
+     *    are deleted and dropping the last key collapses to `undefined`. Key matching
+     *    is verbatim (case-sensitive), matching how `parseTags` stores keys.
+     */
+    mutateTagRecord(current, mutation) {
+        if (mutation.op === 'merge') {
+            return this.freezeTags({ ...(current ?? {}), ...mutation.tags });
+        }
+        const next = { ...(current ?? {}) };
+        const missing = mutation.keys.filter(k => !(k in next));
+        if (missing.length > 0) {
+            throw new QuereusError(`Tag key(s) not found: ${missing.join(', ')}`, StatusCode.NOTFOUND);
+        }
+        for (const k of mutation.keys)
+            delete next[k];
+        return this.freezeTags(next);
+    }
+    /**
+     * Re-registers a tag-only schema swap and fires `table_modified` so optimizer
+     * caches invalidate. Tags are excluded from the schema hash, so a tag-only swap
+     * is a structural no-op except for the metadata itself.
+     */
+    commitTagUpdate(targetSchemaName, oldSchema, newSchema) {
+        const schema = this.getSchemaOrFail(targetSchemaName);
+        schema.addTable(newSchema);
+        this.changeNotifier.notifyChange({
+            type: 'table_modified',
+            // Stored names of the swapped object, not the raw ALTER args — see
+            // canonicalSchemaName for the emitter/stored-name invariant. A raw
+            // `targetSchemaName` here (e.g. `alter index MAIN.idx set tags`) would
+            // miss the table dep's stored `'main'`.
+            schemaName: newSchema.schemaName,
+            objectName: newSchema.name,
+            oldObject: oldSchema,
+            newObject: newSchema,
+        });
+    }
+    /**
+     * Shared table-tag read-modify-write: fetches the live table (NOTFOUND if
+     * absent), computes the next tag record from its current `tags` via `compute`,
+     * and commits the swap (firing `table_modified`). `compute` decides
+     * replace / merge / drop; it may throw before any mutation (e.g. drop-of-absent
+     * NOTFOUND), leaving the catalog untouched. Reads the *live* schema each call so
+     * back-to-back ALTERs and prepared-statement reuse see the prior result.
+     */
+    updateTableTags(tableName, compute, schemaName) {
+        const targetSchemaName = schemaName ?? this.getCurrentSchemaName();
+        const tableSchema = this.getTable(targetSchemaName, tableName);
+        if (!tableSchema) {
+            throw new QuereusError(`Table '${tableName}' not found in schema '${targetSchemaName}'`, StatusCode.NOTFOUND);
+        }
+        const updatedSchema = {
+            ...tableSchema,
+            tags: compute(tableSchema.tags),
+        };
+        this.commitTagUpdate(targetSchemaName, tableSchema, updatedSchema);
+    }
     /**
      * Sets metadata tags on an existing table, replacing any existing tags.
      *
@@ -454,18 +740,456 @@ export class SchemaManager {
      * @param schemaName Optional schema name (defaults to current schema)
      */
     setTableTags(tableName, tags, schemaName) {
+        this.updateTableTags(tableName, () => this.freezeTags(tags), schemaName);
+    }
+    /**
+     * Merges `tags` into an existing table's tags — set/overwrite the listed keys,
+     * keep the rest (the `ALTER TABLE … ADD TAGS` primitive). An empty `tags` is a
+     * no-op (it does NOT clear). Reads the table's live tags at call time.
+     */
+    mergeTableTags(tableName, tags, schemaName) {
+        this.updateTableTags(tableName, current => this.mutateTagRecord(current, { op: 'merge', tags }), schemaName);
+    }
+    /**
+     * Drops the listed keys from an existing table's tags (the `ALTER TABLE …
+     * DROP TAGS` primitive). Atomic: every key must be present, else `NOTFOUND`
+     * names the missing key(s) and nothing is dropped. Dropping the last key(s)
+     * leaves `tags` undefined. An empty `keys` is a no-op.
+     */
+    dropTableTags(tableName, keys, schemaName) {
+        this.updateTableTags(tableName, current => this.mutateTagRecord(current, { op: 'drop', keys }), schemaName);
+    }
+    /**
+     * Shared column-tag read-modify-write: resolves the table and column (NOTFOUND
+     * on either miss), computes the column's next tag record from its current `tags`
+     * via `compute`, and commits the swap. Only the column's `tags` field changes;
+     * nullability / type / default / PK membership are untouched. `compute` may throw
+     * before any mutation (drop-of-absent NOTFOUND), leaving the catalog untouched.
+     */
+    updateColumnTags(tableName, columnName, compute, schemaName) {
         const targetSchemaName = schemaName ?? this.getCurrentSchemaName();
         const tableSchema = this.getTable(targetSchemaName, tableName);
         if (!tableSchema) {
             throw new QuereusError(`Table '${tableName}' not found in schema '${targetSchemaName}'`, StatusCode.NOTFOUND);
         }
-        const hasTags = Object.keys(tags).length > 0;
+        const colIndex = tableSchema.columnIndexMap.get(columnName.toLowerCase());
+        if (colIndex === undefined) {
+            throw new QuereusError(`Column '${columnName}' not found in table '${tableName}'`, StatusCode.NOTFOUND);
+        }
+        // Compute before building the new column array so a drop-of-absent NOTFOUND
+        // aborts before any swap.
+        const nextTags = compute(tableSchema.columns[colIndex].tags);
+        const newColumns = tableSchema.columns.map((c, i) => (i === colIndex ? { ...c, tags: nextTags } : c));
         const updatedSchema = {
             ...tableSchema,
-            tags: hasTags ? Object.freeze({ ...tags }) : undefined,
+            columns: Object.freeze(newColumns),
         };
+        this.commitTagUpdate(targetSchemaName, tableSchema, updatedSchema);
+    }
+    /**
+     * Sets metadata tags on a column of an existing table, replacing any existing
+     * tags on that column (empty record clears). Catalog-only — only the column's
+     * `tags` field changes; nullability / type / default / PK membership are
+     * untouched.
+     *
+     * @throws QuereusError(NOTFOUND) if the table or column does not exist.
+     */
+    setColumnTags(tableName, columnName, tags, schemaName) {
+        this.updateColumnTags(tableName, columnName, () => this.freezeTags(tags), schemaName);
+    }
+    /**
+     * Merges `tags` into a column's existing tags — set/overwrite the listed keys,
+     * keep the rest (`ALTER TABLE … ALTER COLUMN … ADD TAGS`). Empty `tags` is a
+     * no-op (does NOT clear).
+     *
+     * @throws QuereusError(NOTFOUND) if the table or column does not exist.
+     */
+    mergeColumnTags(tableName, columnName, tags, schemaName) {
+        this.updateColumnTags(tableName, columnName, current => this.mutateTagRecord(current, { op: 'merge', tags }), schemaName);
+    }
+    /**
+     * Drops the listed keys from a column's tags (`ALTER TABLE … ALTER COLUMN …
+     * DROP TAGS`). Atomic: every key must be present, else `NOTFOUND` names the
+     * missing key(s) and nothing is dropped. Empty `keys` is a no-op.
+     *
+     * @throws QuereusError(NOTFOUND) if the table or column does not exist, or any
+     *   listed key is absent.
+     */
+    dropColumnTags(tableName, columnName, keys, schemaName) {
+        this.updateColumnTags(tableName, columnName, current => this.mutateTagRecord(current, { op: 'drop', keys }), schemaName);
+    }
+    /**
+     * Shared named-constraint-tag read-modify-write: resolves the table (NOTFOUND if
+     * absent) and the single matching constraint class (check → unique → fk;
+     * NOTFOUND / ambiguous via {@link resolveNamedConstraintClass}), computes the
+     * matching constraint's next tag record from its current `tags` via `compute`,
+     * and commits. `compute` may throw before any mutation (drop-of-absent NOTFOUND);
+     * since it runs inside the array rebuild prior to `commitTagUpdate`, a throw
+     * leaves the catalog untouched.
+     */
+    updateConstraintTags(tableName, constraintName, compute, schemaName) {
+        const targetSchemaName = schemaName ?? this.getCurrentSchemaName();
+        const tableSchema = this.getTable(targetSchemaName, tableName);
+        if (!tableSchema) {
+            throw new QuereusError(`Table '${tableName}' not found in schema '${targetSchemaName}'`, StatusCode.NOTFOUND);
+        }
+        const lower = constraintName.toLowerCase();
+        // Resolve to exactly one class (check → unique → fk), or throw NOTFOUND/ambiguous.
+        const constraintClass = resolveNamedConstraintClass(tableSchema, constraintName);
+        const updatedSchema = { ...tableSchema };
+        if (constraintClass === 'check') {
+            updatedSchema.checkConstraints = Object.freeze(tableSchema.checkConstraints.map(c => (c.name?.toLowerCase() === lower ? { ...c, tags: compute(c.tags) } : c)));
+        }
+        else if (constraintClass === 'unique') {
+            updatedSchema.uniqueConstraints = Object.freeze(tableSchema.uniqueConstraints.map(c => (c.name?.toLowerCase() === lower ? { ...c, tags: compute(c.tags) } : c)));
+        }
+        else {
+            updatedSchema.foreignKeys = Object.freeze(tableSchema.foreignKeys.map(c => (c.name?.toLowerCase() === lower ? { ...c, tags: compute(c.tags) } : c)));
+        }
+        this.commitTagUpdate(targetSchemaName, tableSchema, updatedSchema);
+    }
+    /**
+     * Sets metadata tags on a NAMED table-level constraint (CHECK / UNIQUE /
+     * FOREIGN KEY), replacing any existing tags (empty record clears). Lookup order
+     * is checks → unique → foreign keys; a name present in more than one class is
+     * rejected as ambiguous. Unnamed constraints are not addressable.
+     *
+     * @throws QuereusError(NOTFOUND) if no named constraint matches.
+     * @throws QuereusError(ERROR) if the name is ambiguous across constraint classes.
+     */
+    setConstraintTags(tableName, constraintName, tags, schemaName) {
+        this.updateConstraintTags(tableName, constraintName, () => this.freezeTags(tags), schemaName);
+    }
+    /**
+     * Merges `tags` into a named constraint's existing tags — set/overwrite the
+     * listed keys, keep the rest (`ALTER TABLE … ALTER CONSTRAINT … ADD TAGS`).
+     * Empty `tags` is a no-op (does NOT clear).
+     *
+     * @throws QuereusError(NOTFOUND) if no named constraint matches.
+     * @throws QuereusError(ERROR) if the name is ambiguous across constraint classes.
+     */
+    mergeConstraintTags(tableName, constraintName, tags, schemaName) {
+        this.updateConstraintTags(tableName, constraintName, current => this.mutateTagRecord(current, { op: 'merge', tags }), schemaName);
+    }
+    /**
+     * Drops the listed keys from a named constraint's tags (`ALTER TABLE … ALTER
+     * CONSTRAINT … DROP TAGS`). Atomic: every key must be present, else `NOTFOUND`
+     * names the missing key(s) and nothing is dropped. Empty `keys` is a no-op.
+     *
+     * @throws QuereusError(NOTFOUND) if no named constraint matches, or any listed
+     *   key is absent.
+     * @throws QuereusError(ERROR) if the name is ambiguous across constraint classes.
+     */
+    dropConstraintTags(tableName, constraintName, keys, schemaName) {
+        this.updateConstraintTags(tableName, constraintName, current => this.mutateTagRecord(current, { op: 'drop', keys }), schemaName);
+    }
+    /**
+     * Shared view-tag read-modify-write: fetches the live view (NOTFOUND if
+     * absent), computes its next tag record from its current `tags` via `compute`,
+     * re-registers the swapped {@link ViewSchema}, and fires `view_modified` so a
+     * cached write-through plan that recorded a `view` dependency (every
+     * view-/MV-mediated write does — see `buildViewMutation`) is invalidated when
+     * the view's tags change (tag validation re-runs at plan time, so a
+     * newly-invalid tag must surface on the next run). This event is distinct
+     * from the (non-existent) plain-view create event, so it triggers no maintenance
+     * re-registration. `compute` decides replace / merge / drop and may throw before
+     * any mutation (drop-of-absent NOTFOUND), leaving the catalog untouched.
+     */
+    updateViewTags(viewName, compute, schemaName) {
+        const targetSchemaName = schemaName ?? this.getCurrentSchemaName();
         const schema = this.getSchemaOrFail(targetSchemaName);
-        schema.addTable(updatedSchema);
+        const view = schema.getView(viewName);
+        if (!view) {
+            throw new QuereusError(`View '${viewName}' not found in schema '${targetSchemaName}'`, StatusCode.NOTFOUND);
+        }
+        const updated = { ...view, tags: compute(view.tags) };
+        schema.addView(updated);
+        this.changeNotifier.notifyChange({
+            type: 'view_modified',
+            // Stored names of the swapped object, not the raw ALTER args — see
+            // canonicalSchemaName for the emitter/stored-name invariant. A
+            // case-differing ALTER (e.g. `alter view MAIN.MYVIEW` on
+            // `create view MyView` in `main`) would otherwise miss on either field.
+            schemaName: schema.name,
+            objectName: updated.name,
+            oldObject: view,
+            newObject: updated,
+        });
+    }
+    /**
+     * Sets metadata tags on an existing view, replacing any existing tags (empty
+     * record clears).
+     *
+     * @throws QuereusError(NOTFOUND) if the view does not exist.
+     */
+    setViewTags(viewName, tags, schemaName) {
+        this.updateViewTags(viewName, () => this.freezeTags(tags), schemaName);
+    }
+    /**
+     * Merges `tags` into an existing view's tags — set/overwrite the listed keys,
+     * keep the rest (`ALTER VIEW … ADD TAGS`). Empty `tags` is a no-op (does NOT
+     * clear). Reads the view's live tags at call time.
+     *
+     * @throws QuereusError(NOTFOUND) if the view does not exist.
+     */
+    mergeViewTags(viewName, tags, schemaName) {
+        this.updateViewTags(viewName, current => this.mutateTagRecord(current, { op: 'merge', tags }), schemaName);
+    }
+    /**
+     * Drops the listed keys from an existing view's tags (`ALTER VIEW … DROP TAGS`).
+     * Atomic: every key must be present, else `NOTFOUND` names the missing key(s)
+     * and nothing is dropped. Dropping the last key(s) leaves `tags` undefined. An
+     * empty `keys` is a no-op.
+     *
+     * @throws QuereusError(NOTFOUND) if the view does not exist, or any listed key
+     *   is absent.
+     */
+    dropViewTags(viewName, keys, schemaName) {
+        this.updateViewTags(viewName, current => this.mutateTagRecord(current, { op: 'drop', keys }), schemaName);
+    }
+    /**
+     * Shared materialized-view-tag read-modify-write: fetches the live maintained
+     * table (NOTFOUND if absent or derivation-less), computes its next tag record
+     * via `compute`, re-registers the swapped table (the shared `derivation`
+     * object rides the spread), and fires `materialized_view_modified`. The
+     * table's contents and the row-time maintenance plan are untouched (tags do
+     * not affect maintenance), so this never re-materializes — `_modified` is
+     * deliberately distinct from `materialized_view_added` (what create emits):
+     * the MV maintenance manager re-registers on `_added` but ignores
+     * `_modified`. The event invalidates a cached write-through plan that
+     * recorded a `view` dependency when the MV's tags change (tag validation
+     * re-runs at plan time). `compute` may throw before any mutation
+     * (drop-of-absent NOTFOUND), leaving the catalog untouched.
+     */
+    updateMaterializedViewTags(name, compute, schemaName) {
+        const targetSchemaName = schemaName ?? this.getCurrentSchemaName();
+        const schema = this.getSchemaOrFail(targetSchemaName);
+        const table = schema.getTable(name);
+        if (!isMaintainedTable(table)) {
+            throw new QuereusError(`Materialized view '${name}' not found in schema '${targetSchemaName}'`, StatusCode.NOTFOUND);
+        }
+        const updated = { ...table, tags: compute(table.tags) };
+        schema.addTable(updated);
+        this.changeNotifier.notifyChange({
+            type: 'materialized_view_modified',
+            // Stored names of the swapped object, not the raw ALTER args — see
+            // canonicalSchemaName for the emitter/stored-name invariant.
+            schemaName: schema.name,
+            objectName: updated.name,
+            oldObject: table,
+            newObject: updated,
+        });
+    }
+    /**
+     * Sets metadata tags on an existing materialized view, replacing any existing
+     * tags (empty record clears). Catalog-only — never re-materializes.
+     *
+     * @throws QuereusError(NOTFOUND) if the materialized view does not exist.
+     */
+    setMaterializedViewTags(name, tags, schemaName) {
+        this.updateMaterializedViewTags(name, () => this.freezeTags(tags), schemaName);
+    }
+    /**
+     * Merges `tags` into an existing materialized view's tags — set/overwrite the
+     * listed keys, keep the rest (`ALTER MATERIALIZED VIEW … ADD TAGS`). Empty
+     * `tags` is a no-op (does NOT clear). Catalog-only — never re-materializes.
+     *
+     * @throws QuereusError(NOTFOUND) if the materialized view does not exist.
+     */
+    mergeMaterializedViewTags(name, tags, schemaName) {
+        this.updateMaterializedViewTags(name, current => this.mutateTagRecord(current, { op: 'merge', tags }), schemaName);
+    }
+    /**
+     * Drops the listed keys from an existing materialized view's tags (`ALTER
+     * MATERIALIZED VIEW … DROP TAGS`). Atomic: every key must be present, else
+     * `NOTFOUND` names the missing key(s) and nothing is dropped. Empty `keys` is a
+     * no-op. Catalog-only — never re-materializes.
+     *
+     * @throws QuereusError(NOTFOUND) if the materialized view does not exist, or any
+     *   listed key is absent.
+     */
+    dropMaterializedViewTags(name, keys, schemaName) {
+        this.updateMaterializedViewTags(name, current => this.mutateTagRecord(current, { op: 'drop', keys }), schemaName);
+    }
+    /**
+     * Shared index-tag read-modify-write. Indexes live on their owning
+     * {@link TableSchema}, so this resolves the owner by index name, computes the
+     * matching {@link IndexSchema}'s next tag record from its current `tags` via
+     * `compute`, swaps it, re-registers the table, and fires `table_modified`
+     * (mirroring create/drop index) so optimizer caches invalidate.
+     *
+     * Hidden implicit covering structures (the auto-built BTree backing a UNIQUE
+     * constraint, not opted into catalog visibility) are not user-addressable and
+     * surface as NOTFOUND — their tags live on the originating constraint. `compute`
+     * runs before the index array is rebuilt, so a drop-of-absent NOTFOUND aborts
+     * before any swap.
+     */
+    updateIndexTags(indexName, compute, schemaName) {
+        const targetSchemaName = schemaName ?? this.getCurrentSchemaName();
+        const { oldSchema, newSchema } = this.resolveIndexTagSwap(targetSchemaName, indexName, compute);
+        this.commitTagUpdate(targetSchemaName, oldSchema, newSchema);
+    }
+    /**
+     * Resolve-and-swap core shared by {@link updateIndexTags} (live ALTER — commits
+     * via {@link commitTagUpdate}, firing `table_modified`) and the catalog-import
+     * path ({@link applyImportedIndexTags} — commits silently). Resolves `indexName`
+     * within `targetSchemaName` and returns the owning table plus its swapped
+     * replacement with the computed tags applied; mutates nothing itself.
+     */
+    resolveIndexTagSwap(targetSchemaName, indexName, compute) {
+        const schema = this.getSchemaOrFail(targetSchemaName);
+        const lower = indexName.toLowerCase();
+        // Primary path: a materialized IndexSchema — every real index, plus the
+        // memory backend's materialized implicit covering index. Tags live on the
+        // matched IndexSchema. A *hidden* implicit index is not user-addressable and
+        // is skipped here; it then fails the exposed-constraint fallback below
+        // (its name is materialized, so it is not "exposed and unmaterialized") and
+        // surfaces as NOTFOUND — preserving Phase 22/37 behavior.
+        for (const table of schema.getAllTables()) {
+            const matched = table.indexes?.find(idx => idx.name.toLowerCase() === lower);
+            if (!matched || isHiddenImplicitIndex(table, matched.name))
+                continue;
+            // Compute before rebuilding the index array so a drop-of-absent NOTFOUND
+            // aborts before any swap.
+            const nextTags = compute(matched.tags);
+            const updatedIndexes = table.indexes.map(idx => (idx.name.toLowerCase() === lower ? { ...idx, tags: nextTags } : idx));
+            return { oldSchema: table, newSchema: { ...table, indexes: Object.freeze(updatedIndexes) } };
+        }
+        // Fallback (store mode): the exposed implicit covering index is not
+        // materialized as an IndexSchema. Route its tags onto the originating UNIQUE
+        // constraint's `exposedIndexTags` — kept separate from `uc.tags`, which holds
+        // the exposure flag, so the flag never leaks into the surfaced index tags.
+        // `findExposedImplicitConstraintIndex` returns -1 for hidden/materialized
+        // implicit indexes, so they fall through to NOTFOUND.
+        for (const table of schema.getAllTables()) {
+            const ucIndex = findExposedImplicitConstraintIndex(table, indexName);
+            if (ucIndex < 0)
+                continue;
+            const constraints = table.uniqueConstraints;
+            // Compute before swapping so a drop-of-absent NOTFOUND aborts untouched.
+            const nextTags = compute(constraints[ucIndex].exposedIndexTags);
+            const updatedConstraints = constraints.map((uc, i) => {
+                if (i !== ucIndex)
+                    return uc;
+                const next = { ...uc };
+                if (nextTags)
+                    next.exposedIndexTags = nextTags;
+                else
+                    delete next.exposedIndexTags;
+                return next;
+            });
+            return { oldSchema: table, newSchema: { ...table, uniqueConstraints: Object.freeze(updatedConstraints) } };
+        }
+        throw new QuereusError(`Index '${indexName}' not found in schema '${targetSchemaName}'`, StatusCode.NOTFOUND);
+    }
+    /**
+     * Sets metadata tags on an existing index, replacing any existing tags (empty
+     * record clears).
+     *
+     * @throws QuereusError(NOTFOUND) if no user-visible index matches.
+     */
+    setIndexTags(indexName, tags, schemaName) {
+        this.updateIndexTags(indexName, () => this.freezeTags(tags), schemaName);
+    }
+    /**
+     * Merges `tags` into an existing index's tags — set/overwrite the listed keys,
+     * keep the rest (`ALTER INDEX … ADD TAGS`). Empty `tags` is a no-op (does NOT
+     * clear).
+     *
+     * @throws QuereusError(NOTFOUND) if no user-visible index matches.
+     */
+    mergeIndexTags(indexName, tags, schemaName) {
+        this.updateIndexTags(indexName, current => this.mutateTagRecord(current, { op: 'merge', tags }), schemaName);
+    }
+    /**
+     * Drops the listed keys from an existing index's tags (`ALTER INDEX … DROP
+     * TAGS`). Atomic: every key must be present, else `NOTFOUND` names the missing
+     * key(s) and nothing is dropped. Empty `keys` is a no-op.
+     *
+     * @throws QuereusError(NOTFOUND) if no user-visible index matches, or any listed
+     *   key is absent.
+     */
+    dropIndexTags(indexName, keys, schemaName) {
+        this.updateIndexTags(indexName, current => this.mutateTagRecord(current, { op: 'drop', keys }), schemaName);
+    }
+    /**
+     * Nulls the reverse FK index so it rebuilds from the live catalog on next
+     * access. Pure derived-cache reset — order-independent, called both from the
+     * self-subscribed change listener and from the schema attach/detach methods.
+     */
+    invalidateReverseFkIndex() {
+        this.reverseFkIndex = null;
+    }
+    /**
+     * Builds the reverse FK index from the live catalog, bucketing every FK under
+     * its resolved referenced `schema.table` key (cross-schema FKs key under their
+     * `referencedSchema`). Preserves schema-insertion → table → FK-declaration
+     * order within each bucket so the first-surviving-child RESTRICT pre-check and
+     * any error-message golden tests keep naming the same child.
+     */
+    buildReverseFkIndex() {
+        const index = new Map();
+        for (const schema of this._getAllSchemas()) {
+            for (const childTable of schema.getAllTables()) {
+                if (!childTable.foreignKeys)
+                    continue;
+                for (const fk of childTable.foreignKeys) {
+                    const refSchema = (fk.referencedSchema ?? childTable.schemaName).toLowerCase();
+                    const key = `${refSchema}.${fk.referencedTable.toLowerCase()}`;
+                    let bucket = index.get(key);
+                    if (!bucket) {
+                        bucket = [];
+                        index.set(key, bucket);
+                    }
+                    bucket.push({ childTable, fk });
+                }
+            }
+        }
+        return index;
+    }
+    /**
+     * Returns the FKs that reference `parentSchemaName.parentTableName`
+     * (case-insensitive), the shared primitive every parent-side referential scan
+     * uses to short-circuit. Returns a shared frozen empty array — the O(1) gate —
+     * when nothing references the table; otherwise exactly its referencing FKs.
+     * Lazily (re)builds the whole index from the live catalog on the first access
+     * after any schema mutation; a pure derived cache (over-reporting a since-dropped
+     * FK is harmless — each consumer re-checks arity/target in its per-FK body).
+     *
+     * The returned `fk` objects are the same references held in
+     * `childTable.foreignKeys` (identity preserved).
+     */
+    getReferencingForeignKeys(parentSchemaName, parentTableName) {
+        if (this.reverseFkIndex === null) {
+            this.reverseFkIndex = this.buildReverseFkIndex();
+        }
+        const key = `${parentSchemaName.toLowerCase()}.${parentTableName.toLowerCase()}`;
+        return this.reverseFkIndex.get(key) ?? EMPTY_REFERENCING_FKS;
+    }
+    /**
+     * Nulls the lens basis-FK gate so it rebuilds from the live catalog on next
+     * access. Pure derived-cache reset — order-independent (rebuild happens on next
+     * access, never inside a listener). Public because `lens-compiler` calls it after
+     * a lens (re)deploy, which mutates the slot set without firing a `SchemaChangeEvent`.
+     */
+    invalidateLensFkGate() {
+        this.lensFkGate = null;
+    }
+    /**
+     * O(1) gate for the three basis-keyed lens FK paths: does `schemaName.tableName`
+     * (case-insensitive) back ≥1 logical parent slot referenced by ≥1 logical FK?
+     * When `false`, `executeLensForeignKeyActions`,
+     * `assertLensRestrictsForParentMutation`, and `basisFksOverriddenByDivergentLensFk`
+     * early-return — the reverse-map slot scan they would run finds nothing. Lazily
+     * (re)builds {@link lensFkGate} on the first access after any invalidation, then
+     * does a single `Set.has`. See {@link buildLensBasisFkGate} for the build, and the
+     * {@link lensFkGate} doc-comment for the never-under-report soundness invariant.
+     */
+    basisTableBacksLogicalParentFk(schemaName, tableName) {
+        if (this.lensFkGate === null) {
+            this.lensFkGate = buildLensBasisFkGate(this);
+        }
+        return this.lensFkGate.has(`${schemaName.toLowerCase()}.${tableName.toLowerCase()}`);
     }
     /**
      * Asserts that no other table has FK rows referencing the table being dropped.
@@ -477,42 +1201,34 @@ export class SchemaManager {
             return;
         const parentSchemaLower = parentSchemaName.toLowerCase();
         const parentTableLower = parentTableName.toLowerCase();
-        for (const schema of this._getAllSchemas()) {
-            for (const childTable of schema.getAllTables()) {
-                if (!childTable.foreignKeys)
-                    continue;
-                // Skip the table being dropped itself — self-FK rows are going away with it.
-                if (childTable.schemaName.toLowerCase() === parentSchemaLower &&
-                    childTable.name.toLowerCase() === parentTableLower)
-                    continue;
-                for (const fk of childTable.foreignKeys) {
-                    if (fk.referencedTable.toLowerCase() !== parentTableLower)
-                        continue;
-                    const targetSchema = fk.referencedSchema ?? childTable.schemaName;
-                    if (targetSchema.toLowerCase() !== parentSchemaLower)
-                        continue;
-                    // MATCH SIMPLE: row is referencing iff every FK column is non-NULL.
-                    const childColNames = fk.columns.map(idx => quoteIdentifier(childTable.columns[idx].name));
-                    const whereClause = childColNames.map(c => `${c} IS NOT NULL`).join(' AND ');
-                    const schemaPrefix = childTable.schemaName.toLowerCase() !== 'main'
-                        ? `${quoteIdentifier(childTable.schemaName)}.`
-                        : '';
-                    const sql = `select 1 from ${schemaPrefix}${quoteIdentifier(childTable.name)} where ${whereClause} limit 1`;
-                    const stmt = this.db.prepare(sql);
-                    try {
-                        let referenced = false;
-                        for await (const _row of stmt._iterateRowsRaw()) {
-                            referenced = true;
-                            break;
-                        }
-                        if (referenced) {
-                            throw new QuereusError(`FOREIGN KEY constraint failed: cannot drop table '${parentTableName}' because table '${childTable.name}' still has rows referencing it`, StatusCode.CONSTRAINT);
-                        }
-                    }
-                    finally {
-                        await stmt.finalize();
-                    }
+        // The reverse FK index already keyed on the referenced schema.table, so the
+        // two discovery filters (referencedTable / targetSchema match) are satisfied
+        // by the lookup and drop out; every other line below is unchanged.
+        for (const { childTable, fk } of this.getReferencingForeignKeys(parentSchemaName, parentTableName)) {
+            // Skip the table being dropped itself — self-FK rows are going away with it.
+            if (childTable.schemaName.toLowerCase() === parentSchemaLower &&
+                childTable.name.toLowerCase() === parentTableLower)
+                continue;
+            // MATCH SIMPLE: row is referencing iff every FK column is non-NULL.
+            const childColNames = fk.columns.map(idx => quoteIdentifier(childTable.columns[idx].name));
+            const whereClause = childColNames.map(c => `${c} IS NOT NULL`).join(' AND ');
+            const schemaPrefix = childTable.schemaName.toLowerCase() !== 'main'
+                ? `${quoteIdentifier(childTable.schemaName)}.`
+                : '';
+            const sql = `select 1 from ${schemaPrefix}${quoteIdentifier(childTable.name)} where ${whereClause} limit 1`;
+            const stmt = this.db.prepare(sql);
+            try {
+                let referenced = false;
+                for await (const _row of stmt._iterateRowsRaw()) {
+                    referenced = true;
+                    break;
                 }
+                if (referenced) {
+                    throw new QuereusError(`FOREIGN KEY constraint failed: cannot drop table '${parentTableName}' because table '${childTable.name}' still has rows referencing it`, StatusCode.CONSTRAINT);
+                }
+            }
+            finally {
+                await stmt.finalize();
             }
         }
     }
@@ -544,56 +1260,64 @@ export class SchemaManager {
         // with the table). MATCH SIMPLE: a row is "referencing" iff every FK column
         // is non-NULL.
         await this.assertNoReferencingChildrenForDrop(schemaName, tableName);
-        // Remove any active connections for this table before destroying the module.
-        // Connections become stale once the table is dropped and must not be reused
-        // if the table is later recreated with the same name.
-        this.db.removeConnectionsForTable(schemaName, tableName);
-        let destroyPromise = null;
-        // Call destroy on the module, providing table details
+        // Call destroy on the module FIRST, awaiting it and PROPAGATING any rejection,
+        // BEFORE any engine-side teardown. A module may veto the drop (e.g. a
+        // schema-level inbound-FK guard that an emptied child cannot satisfy); by
+        // awaiting destroy before mutating connection/schema state we make the veto
+        // abort the statement atomically — on rejection the table stays in our schema
+        // map AND in the module's own catalogue, since neither has been touched yet.
+        // Awaiting here (rather than after removeTable, as before) also preserves the
+        // original "subsequent DDL/DML sees a clean slate" intent: destroy still
+        // completes before dropTable returns, just without swallowing its error.
         if (tableSchema.vtabModuleName) { // tableSchema is guaranteed to be defined here
             const moduleRegistration = this.getModule(tableSchema.vtabModuleName);
             if (moduleRegistration && moduleRegistration.module && moduleRegistration.module.destroy) {
                 log(`Calling destroy for VTab %s.%s via module %s`, schemaName, tableName, tableSchema.vtabModuleName);
-                destroyPromise = moduleRegistration.module.destroy(this.db, moduleRegistration.auxData, tableSchema.vtabModuleName, schemaName, tableName).catch(err => {
-                    errorLog(`Error during VTab module destroy for %s.%s: %O`, schemaName, tableName, err);
-                    // Potentially re-throw or handle as a critical error if destroy failure is problematic
-                });
+                // Module-facing stored-name contract (see canonicalSchemaName): hand the
+                // resolved table's canonical schemaName and stored display casing, never
+                // the raw `drop table T` spelling — so a module keying by the arg finds the
+                // create-time key, and the store's own `drop` schema-change event (which
+                // emits objectName: tableName) fires the stored name.
+                await moduleRegistration.module.destroy(this.db, moduleRegistration.auxData, tableSchema.vtabModuleName, tableSchema.schemaName, tableSchema.name);
+                log(`destroy completed for VTab %s.%s`, schemaName, tableName);
             }
             else {
                 warnLog(`VTab module %s (for table %s.%s) or its destroy method not found during dropTable.`, tableSchema.vtabModuleName, schemaName, tableName);
             }
         }
-        // Remove from schema map immediately
+        // destroy succeeded (or the module had none) — now tear down engine-side state.
+        // Remove any active connections for this table before removing it from the
+        // schema map. Connections become stale once the table is dropped and must not
+        // be reused if the table is later recreated with the same name.
+        this.db.removeConnectionsForTable(schemaName, tableName);
+        // Remove from schema map
         const removed = schema.removeTable(tableName);
         if (!removed && !ifExists) {
             // This should ideally not be reached if tableSchema was found above.
             // But as a safeguard if removeTable could fail for other reasons.
             throw new QuereusError(`Failed to remove table ${tableName} from schema ${schemaName}, though it was initially found.`, StatusCode.INTERNAL);
         }
-        // Notify schema change listeners if table was removed
+        // Notify schema change listeners if table was removed. Stored names of the
+        // dropped object, not the raw drop args — see canonicalSchemaName for the
+        // emitter/stored-name invariant.
         if (removed) {
             this.changeNotifier.notifyChange({
                 type: 'table_removed',
-                schemaName: schemaName,
-                objectName: tableName,
+                schemaName: tableSchema.schemaName,
+                objectName: tableSchema.name,
                 oldObject: tableSchema
             });
             // Emit auto schema event for modules without native event support
             const moduleReg = tableSchema.vtabModuleName ? this.getModule(tableSchema.vtabModuleName) : undefined;
-            if (this.db.hasSchemaListeners() && !hasNativeEventSupport(moduleReg?.module)) {
+            if (this.db._needsSchemaEvents() && !hasNativeEventSupport(moduleReg?.module)) {
                 this.db._getEventEmitter().emitAutoSchemaEvent(tableSchema.vtabModuleName ?? 'memory', {
                     type: 'drop',
                     objectType: 'table',
-                    schemaName: schemaName,
-                    objectName: tableName,
+                    schemaName: tableSchema.schemaName,
+                    objectName: tableSchema.name,
                 });
             }
         }
-        // Await destruction so subsequent DDL/DML sees a clean slate
-        if (destroyPromise) {
-            await destroyPromise;
-            log(`destroy completed for VTab %s.%s`, schemaName, tableName);
-        }
         return removed; // True if removed from schema, false if not found and ifExists was true.
     }
     /**
@@ -618,7 +1342,12 @@ export class SchemaManager {
             schema.clearFunctions();
             schema.clearViews();
             schema.clearAssertions();
+            schema.clearLensSlots();
         });
+        // Wiping every table + lens slot leaves both derived FK caches stale (this
+        // path fires no change event); reset so the next access rebuilds them empty.
+        this.invalidateReverseFkIndex();
+        this.invalidateLensFkGate();
         log("Cleared all schemas.");
     }
     /**
@@ -635,6 +1364,25 @@ export class SchemaManager {
         }
         return schema;
     }
+    /**
+     * Canonical form of a raw (statement-supplied) schema qualifier.
+     *
+     * The invalidation contract this anchors: stored `schemaName` on
+     * tables/views/MVs is canonical, and every schema-change emitter fires the
+     * *stored* names of the object it swapped. `Statement.compile()` compares
+     * recorded dependencies against events exactly, so a raw-cased name on
+     * either side silently misses cached-plan invalidation.
+     *
+     * `Schema.name` is invariantly lowercase (every construction site
+     * lowercases), so an existing schema canonicalizes through its Schema
+     * object; an absent one (a plan-time reference that may resolve by run
+     * time, a catalog import into a not-yet-created schema) folds the way the
+     * Schema constructor would. Existence is NOT validated here — lookup sites
+     * keep their own missing-schema handling.
+     */
+    canonicalSchemaName(raw) {
+        return this.schemas.get(raw.toLowerCase())?.name ?? raw.toLowerCase();
+    }
     /**
      * Retrieves a table from the specified schema
      *
@@ -673,19 +1421,22 @@ export class SchemaManager {
      * Builds column schemas from AST column/constraint definitions,
      * resolving PK membership and nullability.
      */
-    buildColumnSchemas(astColumns, astConstraints, defaultNotNull) {
-        const preliminaryColumnSchemas = astColumns.map(colDef => columnDefToSchema(colDef, defaultNotNull));
-        const { pkDef: pkDefinition, defaultConflict: pkDefaultConflict } = findPKDefinition(preliminaryColumnSchemas, astConstraints);
+    buildColumnSchemas(astColumns, astConstraints, defaultNotNull, defaultCollation = 'BINARY') {
+        const preliminaryColumnSchemas = astColumns.map(colDef => columnDefToSchema(colDef, defaultNotNull, defaultCollation));
+        const { pkDef: pkDefinition, defaultConflict: pkDefaultConflict, synthesized } = findPKDefinition(preliminaryColumnSchemas, astConstraints);
         const columns = preliminaryColumnSchemas.map((col, idx) => {
             const isPkColumn = pkDefinition.some(pkCol => pkCol.index === idx);
             const pkOrder = isPkColumn
                 ? pkDefinition.findIndex(pkC => pkC.index === idx) + 1
                 : 0;
+            // Only an explicitly-declared PK forces NOT NULL. A synthesized
+            // all-columns key (the no-PK fallback) leaves each column's declared
+            // nullability intact — see findPKDefinition.
             return {
                 ...col,
                 primaryKey: isPkColumn,
                 pkOrder,
-                notNull: isPkColumn ? true : col.notNull,
+                notNull: (isPkColumn && !synthesized) ? true : col.notNull,
             };
         });
         return { columns, pkDefinition, pkDefaultConflict };
@@ -746,7 +1497,7 @@ export class SchemaManager {
                         name: con.name ?? `_fk_${tableName}_${colDef.name}`,
                         columns: Object.freeze([childColIndex]),
                         referencedTable: fk.table,
-                        referencedSchema: schemaName,
+                        referencedSchema: fk.schema ?? schemaName,
                         referencedColumns: Object.freeze([]), // resolved at enforcement time
                         referencedColumnNames: fk.columns, // deferred resolution via resolveReferencedColumns
                         onDelete: fk.onDelete ?? 'restrict',
@@ -757,32 +1508,11 @@ export class SchemaManager {
                 }
             }
         }
-        // Table-level foreign keys
+        // Table-level foreign keys — delegate to the shared builder so the module
+        // `ADD CONSTRAINT` path and CREATE TABLE produce byte-identical schemas.
         for (const con of astConstraints ?? []) {
             if (con.type === 'foreignKey' && con.foreignKey && con.columns) {
-                const fk = con.foreignKey;
-                const childColIndices = con.columns.map(col => {
-                    const idx = columnIndexMap.get(col.name.toLowerCase());
-                    if (idx === undefined) {
-                        throw new QuereusError(`FK column '${col.name}' not found in table '${tableName}'`, StatusCode.ERROR);
-                    }
-                    return idx;
-                });
-                if (fk.columns && fk.columns.length !== childColIndices.length) {
-                    throw new QuereusError(`FK constraint '${con.name ?? `_fk_${tableName}_${con.columns.map(c => c.name).join('_')}`}' on table '${tableName}': child column count (${childColIndices.length}) does not match parent column count (${fk.columns.length})`, StatusCode.ERROR);
-                }
-                result.push({
-                    name: con.name ?? `_fk_${tableName}_${con.columns.map(c => c.name).join('_')}`,
-                    columns: Object.freeze(childColIndices),
-                    referencedTable: fk.table,
-                    referencedSchema: schemaName,
-                    referencedColumns: Object.freeze([]), // resolved at enforcement time
-                    referencedColumnNames: fk.columns, // deferred resolution via resolveReferencedColumns
-                    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,
-                });
+                result.push(buildForeignKeyConstraintSchema(con, columnIndexMap, tableName, schemaName));
             }
         }
         return result;
@@ -809,22 +1539,11 @@ export class SchemaManager {
                 }
             }
         }
-        // Table-level unique constraints
+        // Table-level unique constraints — delegate to the shared builder (DRY with
+        // the module `ADD CONSTRAINT` path).
         for (const con of astConstraints ?? []) {
             if (con.type === 'unique' && con.columns && con.columns.length > 0) {
-                const colIndices = con.columns.map(col => {
-                    const idx = columnIndexMap.get(col.name.toLowerCase());
-                    if (idx === undefined) {
-                        throw new QuereusError(`UNIQUE constraint column '${col.name}' not found`, StatusCode.ERROR);
-                    }
-                    return idx;
-                });
-                result.push({
-                    name: con.name,
-                    columns: Object.freeze(colIndices),
-                    defaultConflict: con.onConflict,
-                    tags: con.tags && Object.keys(con.tags).length > 0 ? Object.freeze({ ...con.tags }) : undefined,
-                });
+                result.push(buildUniqueConstraintSchema(con, columnIndexMap));
             }
         }
         return result;
@@ -833,13 +1552,24 @@ export class SchemaManager {
      * Builds a base TableSchema from an AST CREATE TABLE statement.
      * Shared by both createTable (new storage) and importTable (existing storage).
      */
-    buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo) {
-        const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
+    buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo, 
+    /**
+     * Session `default_collation` for columns with no explicit COLLATE. The
+     * caller decides: `createTable` passes the live session option (user-authored
+     * CREATE), `importTable` passes `'BINARY'` (persisted DDL already made any
+     * non-BINARY collation explicit, so an omitted COLLATE is canonical BINARY).
+     */
+    defaultCollation = 'BINARY') {
+        // Stored schemaName is canonical (see canonicalSchemaName); the table name
+        // keeps its declared display casing.
+        const targetSchemaName = stmt.table.schema
+            ? this.canonicalSchemaName(stmt.table.schema)
+            : this.getCurrentSchemaName();
         const tableName = stmt.table.name;
         const defaultNullability = this.db.options.getStringOption('default_column_nullability');
         const defaultNotNull = defaultNullability === 'not_null';
         const astColumns = stmt.columns || [];
-        const { columns, pkDefinition, pkDefaultConflict } = this.buildColumnSchemas(astColumns, stmt.constraints, defaultNotNull);
+        const { columns, pkDefinition, pkDefaultConflict } = this.buildColumnSchemas(astColumns, stmt.constraints, defaultNotNull, defaultCollation);
         const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints);
         const columnIndexMap = buildColumnIndexMap(columns);
         const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, targetSchemaName);
@@ -867,7 +1597,6 @@ export class SchemaManager {
             checkConstraints: Object.freeze(checkConstraints),
             foreignKeys: foreignKeys.length > 0 ? Object.freeze(foreignKeys) : undefined,
             uniqueConstraints: uniqueConstraints.length > 0 ? Object.freeze(uniqueConstraints) : undefined,
-            isTemporary: !!stmt.isTemporary,
             isView: false,
             vtabModuleName: moduleName,
             vtabArgs: effectiveModuleArgs,
@@ -880,6 +1609,48 @@ export class SchemaManager {
             tags: stmt.tags && Object.keys(stmt.tags).length > 0 ? Object.freeze({ ...stmt.tags }) : undefined,
         };
     }
+    /**
+     * Builds a **logical** TableSchema spec from a declared CREATE TABLE AST,
+     * for use as the `logicalTable` of a lens slot (see `schema/lens.ts`).
+     *
+     * Reuses the same column / PK / constraint extraction as a physical table
+     * (so the spec is a faithful design), but carries **no** `vtabModule`
+     * (`vtabModuleName: ''`, `isLogical: true`) — a logical table is never
+     * registered or executed; its compiled effective body is registered as a
+     * `ViewSchema`. Module association / indexes / storage are rejected upstream
+     * by the lens compiler before this is called.
+     */
+    buildLogicalTableSchema(stmt, schemaName) {
+        const tableName = stmt.table.name;
+        const defaultNullability = this.db.options.getStringOption('default_column_nullability');
+        const defaultNotNull = defaultNullability === 'not_null';
+        // User-authored declaration shares the CREATE surface, so honor the session default.
+        const defaultCollation = normalizeCollationName(this.db.options.getStringOption('default_collation'));
+        const astColumns = stmt.columns || [];
+        const { columns, pkDefinition, pkDefaultConflict } = this.buildColumnSchemas(astColumns, stmt.constraints, defaultNotNull, defaultCollation);
+        const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints);
+        const columnIndexMap = buildColumnIndexMap(columns);
+        const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, schemaName);
+        const uniqueConstraints = this.extractUniqueConstraints(astColumns, stmt.constraints, columnIndexMap);
+        return {
+            name: tableName,
+            schemaName,
+            columns: Object.freeze(columns),
+            columnIndexMap,
+            primaryKeyDefinition: pkDefinition,
+            primaryKeyDefaultConflict: pkDefaultConflict,
+            checkConstraints: Object.freeze(checkConstraints),
+            foreignKeys: foreignKeys.length > 0 ? Object.freeze(foreignKeys) : undefined,
+            uniqueConstraints: uniqueConstraints.length > 0 ? Object.freeze(uniqueConstraints) : undefined,
+            isView: false,
+            isLogical: true,
+            // Logical tables carry no module — they are a design, not storage.
+            vtabModule: undefined,
+            vtabModuleName: '',
+            estimatedRows: 0,
+            tags: stmt.tags && Object.keys(stmt.tags).length > 0 ? Object.freeze({ ...stmt.tags }) : undefined,
+        };
+    }
     /**
      * Walks an expression AST and rejects bind-parameter and (optionally)
      * column-reference nodes. Used by DDL-time DEFAULT/CHECK validators where
@@ -890,6 +1661,15 @@ export class SchemaManager {
      */
     rejectIllegalReferences(expr, options) {
         let offendingType;
+        // A column reference nested inside a subquery is scoped to that subquery's own
+        // FROM, not the row being inserted, so it is not an illegal sibling-row
+        // reference — only top-level (depth-0) columns are. This is what lets a DEFAULT
+        // author a self-referencing allocator like
+        // `coalesce((select max(rid) from t), 0) + mutation_ordinal()` (the
+        // shared-key-via-default surrogate recipe — docs/view-updateability.md
+        // § Mutation Context). Parameters stay rejected at any depth.
+        let subqueryDepth = 0;
+        const isQueryBoundary = (node) => node.type === 'select' || node.type === 'subquery' || node.type === 'exists';
         traverseAst(expr, {
             enterNode: (node) => {
                 if (offendingType)
@@ -898,10 +1678,22 @@ export class SchemaManager {
                     offendingType = 'parameter';
                     return false;
                 }
-                if (options.rejectColumns && node.type === 'column') {
-                    offendingType = 'column';
-                    return false;
+                if (options.rejectColumns && node.type === 'column' && subqueryDepth === 0) {
+                    // `new.<column>` is an explicit, legal read of a value the INSERT
+                    // supplies for a sibling column (resolved against the row scope at
+                    // INSERT time); only a bare (unqualified) column is the illegal
+                    // sibling reference rejected here.
+                    if (node.table?.toLowerCase() !== 'new') {
+                        offendingType = 'column';
+                        return false;
+                    }
                 }
+                if (isQueryBoundary(node))
+                    subqueryDepth += 1;
+            },
+            exitNode: (node) => {
+                if (isQueryBoundary(node))
+                    subqueryDepth -= 1;
             },
         });
         if (offendingType === 'parameter') {
@@ -925,10 +1717,45 @@ export class SchemaManager {
      * context variable, and the build attempt is permitted to fail —
      * scope resolution is deferred to row-time).
      */
-    validateDefaultDeterminism(columns, tableName, hasMutationContext) {
+    /** True when a DEFAULT expression embeds a subquery (scalar subquery / EXISTS / SELECT). */
+    defaultEmbedsSubquery(expr) {
+        let found = false;
+        traverseAst(expr, {
+            enterNode: (node) => {
+                if (node.type === 'select' || node.type === 'subquery' || node.type === 'exists') {
+                    found = true;
+                    return false;
+                }
+            },
+        });
+        return found;
+    }
+    /** True when a DEFAULT expression reads the row being written via `new.<column>`. */
+    defaultReferencesNewRow(expr) {
+        let found = false;
+        traverseAst(expr, {
+            enterNode: (node) => {
+                if (found)
+                    return false;
+                if (node.type === 'column' && node.table?.toLowerCase() === 'new') {
+                    found = true;
+                    return false;
+                }
+            },
+        });
+        return found;
+    }
+    /**
+     * Build the throwaway planning context (global + parameter scope, no table/row
+     * scope) used to compile a DEFAULT expression for DDL-time validation. The table's
+     * columns are intentionally absent so a bare-column reference fails to build —
+     * which the bare-column pre-walk has already rejected for the strict case, and
+     * which the deferral path tolerates for `new.`/subquery/mutation-context defaults.
+     */
+    makeDdlValidationContext() {
         const globalScope = new GlobalScope(this.db.schemaManager);
         const parameterScope = new ParameterScope(globalScope);
-        const planningCtx = {
+        return {
             db: this.db,
             schemaManager: this.db.schemaManager,
             parameters: {},
@@ -939,43 +1766,104 @@ export class SchemaManager {
             cteReferenceCache: new Map(),
             outputScopes: new Map()
         };
-        for (const col of columns) {
-            if (!col.defaultValue || typeof col.defaultValue !== 'object' || col.defaultValue === null || !('type' in col.defaultValue)) {
-                continue;
-            }
-            this.rejectIllegalReferences(col.defaultValue, {
-                rejectColumns: !hasMutationContext,
-                formatParamError: () => `DEFAULT for column '${col.name}' in table '${tableName}' may not reference bind parameters.`,
-                formatColumnError: () => `DEFAULT for column '${col.name}' in table '${tableName}' may not reference columns; use a generated column instead.`,
-            });
-            let defaultExpr;
-            try {
-                defaultExpr = buildExpression(planningCtx, col.defaultValue);
+    }
+    /**
+     * Validate a single DEFAULT expression — the per-default core of
+     * {@link validateDefaultDeterminism}, factored out so the ALTER COLUMN SET DEFAULT
+     * path ({@link validateAlterColumnDefault}) routes through the identical checks:
+     * bind parameters and (absent a mutation context) bare columns rejected up front,
+     * non-determinism rejected unless `allowNonDeterministic`, and a `new.<column>` /
+     * subquery / mutation-context default deferred to INSERT time (it cannot build
+     * here without the row/table scope; determinism is re-checked when the row scope
+     * is established).
+     */
+    validateOneDefault(planningCtx, defaultValue, columnName, tableName, hasMutationContext, allowNonDeterministic, ddlPhase) {
+        this.rejectIllegalReferences(defaultValue, {
+            rejectColumns: !hasMutationContext,
+            formatParamError: () => `DEFAULT for column '${columnName}' in table '${tableName}' may not reference bind parameters.`,
+            formatColumnError: () => `DEFAULT for column '${columnName}' in table '${tableName}' may not reference a bare column; use 'new.<column>' to read a value supplied by the INSERT, or a generated column instead.`,
+        });
+        let defaultExpr;
+        // A DEFAULT that embeds a subquery may forward-reference the table being
+        // created (a self-referencing allocator — `select max(rid) from t` on `t`):
+        // the table is not yet registered here, so the build legitimately fails.
+        // A DEFAULT that reads `new.<column>` resolves only against the row scope
+        // established at INSERT time, so it likewise cannot build here. Either way
+        // determinism is re-checked at INSERT time (both the single-source insert
+        // expansion and the shared-key envelope re-validate the compiled default),
+        // so defer rather than reject. Other build failures (a typo'd function /
+        // bare column) stay strict.
+        const defaultEmbedsSubquery = this.defaultEmbedsSubquery(defaultValue);
+        const defaultReferencesNewRow = this.defaultReferencesNewRow(defaultValue);
+        try {
+            defaultExpr = buildExpression(planningCtx, defaultValue);
+        }
+        catch (e) {
+            if (hasMutationContext || defaultEmbedsSubquery || defaultReferencesNewRow) {
+                // Column-style identifiers in DEFAULT may resolve to mutation
+                // context variables at INSERT time; a subquery may forward-reference
+                // the table being created; `new.<column>` resolves against the INSERT
+                // row scope. The row/table scope isn't available here, so a build
+                // failure isn't necessarily a bug. Determinism is re-checked at
+                // INSERT time.
+                log('Skipping determinism validation for default on column %s.%s at %s time (deferred to INSERT%s): %s', tableName, columnName, ddlPhase, hasMutationContext ? ', mutation context present' : defaultEmbedsSubquery ? ', embeds subquery' : ', references new row', e.message);
             }
-            catch (e) {
-                if (hasMutationContext) {
-                    // Column-style identifiers in DEFAULT may resolve to mutation
-                    // context variables at INSERT time; the row scope isn't
-                    // available here, so a build failure isn't necessarily a bug.
-                    // Determinism is re-checked at INSERT time.
-                    log('Skipping determinism validation for default on column %s.%s at CREATE TABLE time (deferred to INSERT, mutation context present): %s', tableName, col.name, e.message);
-                }
-                else {
-                    const message = e instanceof Error ? e.message : String(e);
-                    const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
-                    throw new QuereusError(`DEFAULT for column '${col.name}' in table '${tableName}' is invalid: ${message}`, code, e instanceof Error ? e : undefined);
-                }
+            else {
+                const message = e instanceof Error ? e.message : String(e);
+                const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
+                throw new QuereusError(`DEFAULT for column '${columnName}' in table '${tableName}' is invalid: ${message}`, code, e instanceof Error ? e : undefined);
             }
-            if (!defaultExpr)
+        }
+        if (!defaultExpr)
+            return;
+        if (allowNonDeterministic)
+            return;
+        const result = checkDeterministic(defaultExpr);
+        if (!result.valid) {
+            throw new QuereusError(`Non-deterministic expression not allowed in DEFAULT for column '${columnName}' in table '${tableName}'. ` +
+                `Expression: ${result.expression}. ` +
+                `Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`, StatusCode.ERROR);
+        }
+    }
+    validateDefaultDeterminism(columns, tableName, hasMutationContext, allowNonDeterministic = false) {
+        const planningCtx = this.makeDdlValidationContext();
+        for (const col of columns) {
+            if (!col.defaultValue || typeof col.defaultValue !== 'object' || col.defaultValue === null || !('type' in col.defaultValue)) {
                 continue;
-            const result = checkDeterministic(defaultExpr);
-            if (!result.valid) {
-                throw new QuereusError(`Non-deterministic expression not allowed in DEFAULT for column '${col.name}' in table '${tableName}'. ` +
-                    `Expression: ${result.expression}. ` +
-                    `Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`, StatusCode.ERROR);
             }
+            this.validateOneDefault(planningCtx, col.defaultValue, col.name, tableName, hasMutationContext, allowNonDeterministic, 'CREATE TABLE');
         }
     }
+    /**
+     * Validate a DEFAULT expression supplied by an `ALTER COLUMN … SET DEFAULT`,
+     * routing it through the same checks CREATE TABLE applies so the stored default is
+     * consistent with what INSERT will accept: bind parameters and (absent a mutation
+     * context) bare columns are rejected, non-determinism is rejected unless the
+     * `nondeterministic_schema` option is set, and a `new.<column>` default is accepted
+     * with the build/determinism check deferred to INSERT time. DROP DEFAULT (a null
+     * expression) never reaches here. Called from the ALTER TABLE runtime emitter.
+     */
+    validateAlterColumnDefault(defaultExpr, columnName, tableName, hasMutationContext) {
+        this.validateDdlDefault(defaultExpr, columnName, tableName, hasMutationContext, 'ALTER COLUMN SET DEFAULT');
+    }
+    /**
+     * Validate a DEFAULT supplied by `ALTER TABLE ADD COLUMN`, routing it through the
+     * same checks CREATE TABLE / ALTER COLUMN apply so the stored default is consistent
+     * with what INSERT (and the per-row backfill) will accept: bind parameters and
+     * (absent a mutation context) bare columns are rejected, non-determinism is rejected
+     * unless `nondeterministic_schema` is set, and a `new.<column>` default is accepted
+     * with its build deferred — it reads the existing row's sibling during backfill and
+     * the INSERT-supplied sibling for future inserts. Called from the ALTER TABLE
+     * statement builder (`buildAlterTableStmt`) at plan-build time.
+     */
+    validateAddColumnDefault(defaultExpr, columnName, tableName, hasMutationContext) {
+        this.validateDdlDefault(defaultExpr, columnName, tableName, hasMutationContext, 'ALTER TABLE ADD COLUMN');
+    }
+    /** Shared body for the ALTER-time DEFAULT validators (ALTER COLUMN SET DEFAULT / ADD COLUMN). */
+    validateDdlDefault(defaultExpr, columnName, tableName, hasMutationContext, ddlPhase) {
+        const allowNonDet = this.db.options.getBooleanOption('nondeterministic_schema');
+        this.validateOneDefault(this.makeDdlValidationContext(), defaultExpr, columnName, tableName, hasMutationContext, allowNonDet, ddlPhase);
+    }
     /**
      * Validates that CHECK constraint expressions don't call non-deterministic
      * functions and don't reference bind parameters. Walks the AST and looks
@@ -984,13 +1872,15 @@ export class SchemaManager {
      * CHECK expressions reference table columns whose scope is not yet
      * established at CREATE TABLE time.
      */
-    validateCheckConstraintDeterminism(checkConstraints, tableName) {
+    validateCheckConstraintDeterminism(checkConstraints, tableName, allowNonDeterministic = false) {
         for (const cc of checkConstraints) {
             const constraintName = cc.name ?? `_check_${tableName}`;
             this.rejectIllegalReferences(cc.expr, {
                 rejectColumns: false,
                 formatParamError: () => `CHECK constraint '${constraintName}' on table '${tableName}' may not reference bind parameters.`,
             });
+            if (allowNonDeterministic)
+                continue;
             let offendingExpr;
             traverseAst(cc.expr, {
                 enterNode: (node) => {
@@ -1057,7 +1947,8 @@ export class SchemaManager {
         if (!tableSchema) {
             throw new QuereusError(`no such table: ${tableName}`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
         }
-        if (!tableSchema.vtabModule.createIndex) {
+        const vtabModule = requireVtabModule(tableSchema);
+        if (!vtabModule.createIndex) {
             throw new QuereusError(`Virtual table module '${tableSchema.vtabModuleName}' for table '${tableName}' does not support CREATE INDEX.`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
         }
         const existingIndex = tableSchema.indexes?.find(idx => idx.name.toLowerCase() === indexName.toLowerCase());
@@ -1070,27 +1961,36 @@ export class SchemaManager {
         }
         const indexSchema = this.buildIndexSchema(stmt, tableSchema, tableName, indexName);
         try {
-            await tableSchema.vtabModule.createIndex(this.db, targetSchemaName, tableName, indexSchema);
+            // Module-facing stored-name contract (see canonicalSchemaName): hand the
+            // module the resolved table's canonical schemaName and stored display
+            // casing, never the raw `create index … on T` spelling — a module may key
+            // storage/registries by these args verbatim. `indexSchema.name` is the
+            // *new* index's own name (the future stored name), left as-spelled.
+            await vtabModule.createIndex(this.db, tableSchema.schemaName, tableSchema.name, indexSchema);
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
             const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
             throw new QuereusError(`createIndex failed for index '${indexName}' on table '${tableName}': ${message}`, code, e instanceof Error ? e : undefined, stmt.loc?.start.line, stmt.loc?.start.column);
         }
-        const updatedTableSchema = this.addIndexToTableSchema(tableSchema, indexSchema);
+        const updatedTableSchema = appendIndexToTableSchema(tableSchema, indexSchema);
         const schema = this.getSchemaOrFail(targetSchemaName);
         schema.addTable(updatedTableSchema);
         this.changeNotifier.notifyChange({
             type: 'table_modified',
-            schemaName: targetSchemaName,
-            objectName: tableName,
+            // Stored names of the swapped table, not the raw statement spelling — see
+            // canonicalSchemaName for the emitter/stored-name invariant. A raw
+            // `create index … on T` (stored `t`) or an unqualified CREATE INDEX against
+            // a `MAIN.`-created table would otherwise miss the cached plan's table dep.
+            schemaName: updatedTableSchema.schemaName,
+            objectName: updatedTableSchema.name,
             oldObject: tableSchema,
             newObject: updatedTableSchema
         });
         this.emitAutoSchemaEventIfNeeded(tableSchema.vtabModuleName, {
             type: 'create',
             objectType: 'index',
-            schemaName: targetSchemaName,
+            schemaName: updatedTableSchema.schemaName,
             objectName: indexName,
         });
         log(`Successfully created index %s on table %s.%s`, indexName, targetSchemaName, tableName);
@@ -1100,12 +2000,13 @@ export class SchemaManager {
      */
     buildIndexSchema(stmt, tableSchema, tableName, indexName) {
         const indexColumns = stmt.columns.map((indexedCol) => {
-            if (indexedCol.expr) {
-                throw new QuereusError(`Indices on expressions are not supported yet.`, StatusCode.ERROR, undefined, indexedCol.expr.loc?.start.line, indexedCol.expr.loc?.start.column);
-            }
-            const colName = indexedCol.name;
+            // The parser folds `col COLLATE x` into a collate expression over a bare
+            // column reference; resolveImportedIndexColumn unwraps that form to a
+            // { name, collation } pair, mirroring importIndex. A genuine expression
+            // index (non-column operand) resolves to an unset name and is rejected.
+            const { name: colName, collation } = resolveImportedIndexColumn(indexedCol);
             if (!colName) {
-                throw new QuereusError(`Indexed column must be a simple column name.`, StatusCode.ERROR);
+                throw new QuereusError(`Indices on expressions are not supported yet.`, StatusCode.ERROR, undefined, indexedCol.expr?.loc?.start.line, indexedCol.expr?.loc?.start.column);
             }
             const tableColIndex = tableSchema.columnIndexMap.get(colName.toLowerCase());
             if (tableColIndex === undefined) {
@@ -1115,7 +2016,7 @@ export class SchemaManager {
             return {
                 index: tableColIndex,
                 desc: indexedCol.direction === 'desc',
-                collation: indexedCol.collation || tableColSchema.collation
+                collation: normalizeCollationName(collation || tableColSchema.collation || 'BINARY')
             };
         });
         return {
@@ -1126,29 +2027,6 @@ export class SchemaManager {
             tags: stmt.tags && Object.keys(stmt.tags).length > 0 ? Object.freeze({ ...stmt.tags }) : undefined,
         };
     }
-    /**
-     * Returns a new TableSchema with the given index appended. If the index is
-     * unique, also adds a matching uniqueConstraint so the mutation manager
-     * enforces uniqueness on insert/update through its existing checks.
-     */
-    addIndexToTableSchema(tableSchema, indexSchema) {
-        const updatedIndexes = [...(tableSchema.indexes || []), indexSchema];
-        const result = {
-            ...tableSchema,
-            indexes: Object.freeze(updatedIndexes),
-        };
-        if (indexSchema.unique) {
-            const newConstraint = {
-                name: indexSchema.name,
-                columns: Object.freeze(indexSchema.columns.map(c => c.index)),
-                predicate: indexSchema.predicate,
-                derivedFromIndex: indexSchema.name,
-            };
-            const updatedConstraints = [...(tableSchema.uniqueConstraints ?? []), newConstraint];
-            result.uniqueConstraints = Object.freeze(updatedConstraints);
-        }
-        return result;
-    }
     /**
      * Drops a secondary index from the table that owns it.
      * Searches all tables in the target schema to find the owning table.
@@ -1180,11 +2058,18 @@ export class SchemaManager {
             }
             throw new QuereusError(`no such index: ${indexName}`, StatusCode.ERROR);
         }
+        // Stored display casing of the dropped index — the raw `indexName` arg may
+        // differ in case. Computed *before* the module call so module.dropIndex
+        // receives the stored name (the module-facing stored-name contract; see
+        // canonicalSchemaName), keeping a case-divergent `DROP INDEX iDx` from
+        // missing a module handle/registry keyed by the stored `idx` (e.g. the
+        // store's StoreTable.indexStores cache). Also reused by the events below.
+        const storedIndexName = ownerTable.indexes.find(idx => idx.name.toLowerCase() === lowerIndexName).name;
         // Call module.dropIndex if the module supports it
         const moduleReg = ownerTable.vtabModuleName ? this.getModule(ownerTable.vtabModuleName) : undefined;
         if (moduleReg?.module?.dropIndex) {
             try {
-                await moduleReg.module.dropIndex(this.db, schemaName, ownerTable.name, indexName);
+                await moduleReg.module.dropIndex(this.db, ownerTable.schemaName, ownerTable.name, storedIndexName);
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
@@ -1193,7 +2078,7 @@ export class SchemaManager {
             }
         }
         // Remove the index from the table schema, along with any uniqueConstraint
-        // that was synthesized from this index (see addIndexToTableSchema).
+        // that was synthesized from this index (see appendIndexToTableSchema).
         const updatedIndexes = (ownerTable.indexes || []).filter(idx => idx.name.toLowerCase() !== lowerIndexName);
         const updatedUniqueConstraints = (ownerTable.uniqueConstraints ?? []).filter(uc => uc.derivedFromIndex?.toLowerCase() !== lowerIndexName);
         const updatedTableSchema = {
@@ -1206,7 +2091,9 @@ export class SchemaManager {
         schema.addTable(updatedTableSchema);
         this.changeNotifier.notifyChange({
             type: 'table_modified',
-            schemaName,
+            // Stored names of the swapped table, not the raw drop args — see
+            // canonicalSchemaName for the emitter/stored-name invariant.
+            schemaName: ownerTable.schemaName,
             objectName: ownerTable.name,
             oldObject: ownerTable,
             newObject: updatedTableSchema
@@ -1214,18 +2101,19 @@ export class SchemaManager {
         this.emitAutoSchemaEventIfNeeded(ownerTable.vtabModuleName, {
             type: 'drop',
             objectType: 'index',
-            schemaName,
-            objectName: indexName,
+            schemaName: ownerTable.schemaName,
+            objectName: storedIndexName,
         });
         log(`Successfully dropped index %s from table %s.%s`, indexName, schemaName, ownerTable.name);
     }
     /**
      * Emits an auto schema event for modules that don't have native event support,
-     * if any schema listeners are registered.
+     * if the engine needs schema events — i.e. any `onSchemaChange` or
+     * `onTransactionCommit` listener is registered (see `Database._needsSchemaEvents`).
      */
     emitAutoSchemaEventIfNeeded(moduleName, event) {
         const moduleReg = moduleName ? this.getModule(moduleName) : undefined;
-        if (this.db.hasSchemaListeners() && !hasNativeEventSupport(moduleReg?.module)) {
+        if (this.db._needsSchemaEvents() && !hasNativeEventSupport(moduleReg?.module)) {
             this.db._getEventEmitter().emitAutoSchemaEvent(moduleName ?? 'memory', event);
         }
     }
@@ -1237,7 +2125,36 @@ export class SchemaManager {
      * @returns A Promise that resolves to the created TableSchema.
      * @throws QuereusError on errors (e.g., module not found, create fails, table exists).
      */
-    async createTable(stmt) {
+    /**
+     * Builds the {@link TableSchema} a CREATE TABLE statement WOULD register,
+     * without touching the module or the catalog. Resolution matches
+     * {@link createTable} exactly (same module-info resolution, same live-session
+     * default collation), so the result is byte-for-byte what registration would
+     * produce. Used by the maintained-table create path
+     * (`createMaintainedTable`) to verify the declared shape against the
+     * derivation body BEFORE any catalog registration — the all-or-nothing
+     * posture of `create table … maintained as`.
+     */
+    buildDeclaredTableSchema(stmt) {
+        const { moduleName, effectiveModuleArgs, moduleInfo } = this.resolveModuleInfo(stmt);
+        const defaultCollation = normalizeCollationName(this.db.options.getStringOption('default_collation'));
+        return this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo, defaultCollation);
+    }
+    /**
+     * `preferBacking` routes the module instantiation through the durable backing
+     * seam — `createBacking?() ?? create()`, the SAME preference
+     * {@link createBackingTable} uses — instead of `module.create` directly. It is
+     * set ONLY by the maintained-table create path (`createMaintainedTable`), so a
+     * durable-backing module (e.g. lamina) builds the basis `RowStore` that
+     * `getBackingHost` later resolves for row-time maintenance; without it the table
+     * is an ordinary relational collection with no basis store, and the maintained
+     * fill throws `backing host not found`. An ordinary user CREATE leaves it false
+     * and stays byte-for-byte on `module.create`. A module without `createBacking`
+     * (e.g. memory) falls through to `create` regardless, so the flag is a no-op
+     * there. Every gate above (determinism, FK-collation) runs identically in both
+     * modes — the flag only selects the factory method.
+     */
+    async createTable(stmt, preferBacking = false) {
         const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
         const tableName = stmt.table.name;
         const schema = this.getSchema(targetSchemaName);
@@ -1265,13 +2182,32 @@ export class SchemaManager {
             throw new QuereusError(`${itemType} ${targetSchemaName}.${tableName} already exists`, StatusCode.CONSTRAINT, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
         }
         const { moduleName, effectiveModuleArgs, moduleInfo } = this.resolveModuleInfo(stmt);
-        const baseTableSchema = this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo);
+        // User-authored CREATE: omitted-COLLATE columns resolve under the live session default.
+        const defaultCollation = normalizeCollationName(this.db.options.getStringOption('default_collation'));
+        const baseTableSchema = this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo, defaultCollation);
         const hasMutationContext = !!baseTableSchema.mutationContext && baseTableSchema.mutationContext.length > 0;
-        this.validateDefaultDeterminism(baseTableSchema.columns, tableName, hasMutationContext);
-        this.validateCheckConstraintDeterminism(baseTableSchema.checkConstraints, tableName);
+        // `nondeterministic_schema = true` lifts the strict-rejection gate at CREATE TABLE.
+        // The captured artifact at the vtab.update() frontier is fully resolved per row, so
+        // defaults / CHECKs / generated columns containing non-determinism remain replay-safe
+        // (see docs/architecture.md § Constraints and docs/module-authoring.md § Mutation Statements).
+        // The bind-parameter / column-reference pre-walks inside the validators still run
+        // in both modes — those are scope checks, not determinism checks.
+        const allowNonDet = this.db.options.getBooleanOption('nondeterministic_schema');
+        this.validateDefaultDeterminism(baseTableSchema.columns, tableName, hasMutationContext, allowNonDet);
+        this.validateCheckConstraintDeterminism(baseTableSchema.checkConstraints, tableName, allowNonDet);
         let tableInstance;
         try {
-            tableInstance = await moduleInfo.module.create(this.db, baseTableSchema);
+            // `preferBacking` (set only by the maintained-table create path) routes
+            // through the durable backing seam — the SAME `createBacking?() ?? create()`
+            // preference {@link createBackingTable} uses — so a durable-backing module
+            // builds the basis `RowStore` that `getBackingHost` later resolves for
+            // row-time maintenance. An ordinary user CREATE leaves it false and stays
+            // byte-for-byte on `module.create`; a module without `createBacking` (memory)
+            // falls through to `create` regardless.
+            const create = preferBacking
+                ? (moduleInfo.module.createBacking?.bind(moduleInfo.module) ?? moduleInfo.module.create.bind(moduleInfo.module))
+                : moduleInfo.module.create.bind(moduleInfo.module);
+            tableInstance = await create(this.db, baseTableSchema);
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -1279,8 +2215,81 @@ export class SchemaManager {
             throw new QuereusError(`Module '${moduleName}' create failed for table '${tableName}': ${message}`, code, e instanceof Error ? e : undefined, stmt.loc?.start.line, stmt.loc?.start.column);
         }
         const completeTableSchema = this.finalizeCreatedTableSchema(tableInstance, tableName, targetSchemaName, moduleName, effectiveModuleArgs, moduleInfo);
+        // Reject a FK whose child/parent column collations declare a same-rank conflict
+        // — the same conflict FK enforcement raises at first DML, surfaced here at CREATE.
+        // `completeTableSchema` is post-reconcile (the store's `reconcilePkCollations` ran
+        // inside `module.create`), so an implicit-default text PK reconciled to the store's
+        // NOCASE keeps `collationExplicit` unset → contributes the engine floor, never a
+        // false conflict. Done BEFORE `addTable` so a conflicting FK leaves the catalog
+        // clean (a self-ref FK resolves against `completeTableSchema` itself). Deliberately
+        // only here — never in `buildTableSchemaFromAST` or the import/rehydrate path, so a
+        // legacy persisted conflicting FK reloads fine and still surfaces at DML.
+        for (const fk of completeTableSchema.foreignKeys ?? []) {
+            validateForeignKeyCollations(this.db, completeTableSchema, fk);
+        }
         schema.addTable(completeTableSchema);
         log(`Successfully created table %s.%s using module %s`, targetSchemaName, tableName, moduleName);
+        this.changeNotifier.notifyChange({
+            type: 'table_added',
+            // Stored names of the registered table — see canonicalSchemaName for the
+            // emitter/stored-name invariant.
+            schemaName: completeTableSchema.schemaName,
+            objectName: completeTableSchema.name,
+            newObject: completeTableSchema
+        });
+        this.emitAutoSchemaEventIfNeeded(moduleName, {
+            type: 'create',
+            objectType: 'table',
+            schemaName: completeTableSchema.schemaName,
+            objectName: completeTableSchema.name,
+        });
+        return completeTableSchema;
+    }
+    /**
+     * Creates a backing table from a pre-built `TableSchema` rather than a
+     * CREATE TABLE AST. Used by materialized views, whose backing-table columns
+     * and primary key are derived from the optimized body relation (carrying
+     * full {@link import('../common/datatype.js').ScalarType} fidelity that a
+     * round-trip through SQL type strings would lose).
+     *
+     * Reuses the same internal sequence as {@link createTable} —
+     * `finalizeCreatedTableSchema` → `addTable` → `table_added` notify — so the
+     * backing table behaves like any other table, except the instance is built via
+     * the module's optional `createBacking` when present (`createBacking?() ??
+     * create()`): a durable-backing module routes the backing into its durable
+     * store there; modules without it fall through to `create` (today's behavior).
+     * The supplied schema must carry `vtabModule`/`vtabModuleName` (typically
+     * `memory`).
+     */
+    async createBackingTable(tableSchema) {
+        const targetSchemaName = tableSchema.schemaName;
+        const tableName = tableSchema.name;
+        const schema = this.getSchema(targetSchemaName);
+        if (!schema) {
+            throw new QuereusError(`Internal error: Schema '${targetSchemaName}' not found.`, StatusCode.INTERNAL);
+        }
+        if (schema.getTable(tableName) || schema.getView(tableName)) {
+            throw new QuereusError(`Backing table ${targetSchemaName}.${tableName} already exists`, StatusCode.CONSTRAINT);
+        }
+        const moduleName = tableSchema.vtabModuleName;
+        const moduleInfo = this.getModule(moduleName);
+        if (!moduleInfo || !moduleInfo.module) {
+            throw new QuereusError(`No virtual table module named '${moduleName}'`, StatusCode.ERROR);
+        }
+        let tableInstance;
+        try {
+            const create = moduleInfo.module.createBacking?.bind(moduleInfo.module)
+                ?? moduleInfo.module.create.bind(moduleInfo.module);
+            tableInstance = await create(this.db, tableSchema);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
+            throw new QuereusError(`Module '${moduleName}' backing create failed for '${tableName}': ${message}`, code, e instanceof Error ? e : undefined);
+        }
+        const completeTableSchema = this.finalizeCreatedTableSchema(tableInstance, tableName, targetSchemaName, moduleName, tableSchema.vtabArgs ?? {}, moduleInfo);
+        schema.addTable(completeTableSchema);
+        log(`Successfully created backing table %s.%s using module %s`, targetSchemaName, tableName, moduleName);
         this.changeNotifier.notifyChange({
             type: 'table_added',
             schemaName: targetSchemaName,
@@ -1299,25 +2308,46 @@ export class SchemaManager {
      * Import catalog objects from DDL statements without triggering storage creation.
      * Used when connecting to existing storage that already contains data.
      *
+     * Options enable the materialized-view **adopt-without-refill fast path**
+     * (see {@link importMaterializedView}); omitted, every MV refills — the
+     * always-correct default.
+     *
      * This method:
      * 1. Parses each DDL statement
-     * 2. Registers the schema objects (tables, indexes)
-     * 3. Calls module.connect() instead of module.create()
+     * 2. Registers the schema objects (tables, indexes, views, materialized views)
+     * 3. Calls module.connect() instead of module.create() for tables (a
+     *    materialized view's memory backing is re-materialized instead — see
+     *    {@link importMaterializedView})
      * 4. Skips schema change hooks (since these are existing objects)
      *
-     * @param ddlStatements Array of DDL strings (CREATE TABLE, CREATE INDEX, etc.)
+     * Each DDL string may hold **one or more** statements: a catalog entry can
+     * bundle a `CREATE TABLE` immediately followed by the `CREATE INDEX`es that
+     * belong to it. Statements within an entry are imported in document order, so
+     * a table always precedes the indexes that reference it. (Because every
+     * table's indexes are co-located with it in one entry, no global
+     * table-before-index ordering across entries is required.)
+     *
+     * @param ddlStatements Array of DDL strings (each one or more CREATE TABLE / CREATE INDEX, etc.)
+     * @param options Adopt-fast-path options for materialized views — see {@link ImportCatalogOptions}
      * @returns Array of imported object names
      */
-    async importCatalog(ddlStatements) {
-        const imported = { tables: [], indexes: [] };
+    async importCatalog(ddlStatements, options) {
+        const imported = { tables: [], indexes: [], views: [], materializedViews: [] };
         for (const ddl of ddlStatements) {
             try {
-                const result = await this.importSingleDDL(ddl);
-                if (result.type === 'table') {
-                    imported.tables.push(result.name);
-                }
-                else if (result.type === 'index') {
-                    imported.indexes.push(result.name);
+                for (const result of await this.importDDL(ddl, options)) {
+                    if (result.type === 'table') {
+                        imported.tables.push(result.name);
+                    }
+                    else if (result.type === 'index') {
+                        imported.indexes.push(result.name);
+                    }
+                    else if (result.type === 'view') {
+                        imported.views.push(result.name);
+                    }
+                    else {
+                        imported.materializedViews.push(result.name);
+                    }
                 }
             }
             catch (e) {
@@ -1326,26 +2356,285 @@ export class SchemaManager {
                 throw e;
             }
         }
-        log('Imported catalog: %d tables, %d indexes', imported.tables.length, imported.indexes.length);
+        log('Imported catalog: %d tables, %d indexes, %d views, %d materialized views', imported.tables.length, imported.indexes.length, imported.views.length, imported.materializedViews.length);
         return imported;
     }
     /**
-     * Import a single DDL statement without creating storage.
+     * Import every statement in a DDL string without creating storage, in document
+     * order. A single string may carry several statements (a table bundled with
+     * its indexes); single-statement entries remain valid. An `alter index … tags`
+     * statement (the store bundle's vehicle for exposed-implicit-index user tags)
+     * applies silently against the just-imported table and contributes no result
+     * entry — it modifies an existing object rather than importing one. Any other
+     * unsupported statement type throws — `rehydrateCatalog` relies on this
+     * fail-loud contract to record import errors rather than silently dropping
+     * objects.
      */
-    async importSingleDDL(ddl) {
+    async importDDL(ddl, options) {
         const parser = new Parser();
         const statements = parser.parseAll(ddl);
-        if (statements.length !== 1) {
-            throw new QuereusError(`importCatalog expects exactly one statement per DDL, got ${statements.length}`, StatusCode.ERROR);
+        const results = [];
+        for (const stmt of statements) {
+            if (stmt.type === 'createTable') {
+                const createTable = stmt;
+                // Unified model: a maintained table persists/exports as the canonical
+                // `create table … maintained as <body>` form (see generateMaintainedTableDDL).
+                // That re-parses as a createTable carrying a `maintained` clause, so route
+                // it through the same re-materialize/adopt path as the MV sugar — the plain
+                // `importTable` connect path would try (and fail) to reconnect an ephemeral
+                // backing that was never persisted.
+                if (createTable.maintained) {
+                    results.push(await this.importMaterializedView(maintainedImportFromTableStmt(createTable), options));
+                }
+                else {
+                    results.push(await this.importTable(createTable));
+                }
+            }
+            else if (stmt.type === 'createIndex') {
+                results.push(await this.importIndex(stmt));
+            }
+            else if (stmt.type === 'createView') {
+                // Plain views import silently (body planning deferred to first reference).
+                results.push(this.importView(stmt));
+            }
+            else if (stmt.type === 'createMaterializedView') {
+                // Materialized views re-materialize (backing rebuilt from current source
+                // data, row-time maintenance re-registered) — silent like the other arms.
+                // Under `options.trustBackings` a pre-existing durable backing that
+                // passes every adopt gate is adopted without the refill.
+                results.push(await this.importMaterializedView(maintainedImportFromMvStmt(stmt), options));
+            }
+            else if (stmt.type === 'alterIndex') {
+                // Tag re-application on an already-imported object — no result entry.
+                this.applyImportedIndexTags(stmt);
+            }
+            else {
+                throw new QuereusError(`importCatalog does not support statement type: ${stmt.type}`, StatusCode.ERROR);
+            }
+        }
+        return results;
+    }
+    /**
+     * Apply an `alter index … {set|add|drop} tags` statement during catalog import,
+     * **silently** — no `notifyChange`, mirroring {@link importTable}/{@link importIndex}
+     * (a store rehydrating its own catalog must not re-emit persistence events).
+     * Shares {@link resolveIndexTagSwap} with the live {@link updateIndexTags} path,
+     * so the bundle's statement resolves exactly as a user-issued ALTER would —
+     * materialized `IndexSchema` first, then the exposed-implicit-constraint
+     * fallback (the store-bundle case: the `alter index` line follows its
+     * `CREATE TABLE` in the same entry, so the constraint is already registered).
+     * All three action forms map through the shared `freezeTags`/`mutateTagRecord`
+     * helpers, though the bundle generator only emits the whole-set replace form.
+     * An unresolvable target throws NOTFOUND — the bundle and its alter line come
+     * from one `TableSchema` snapshot, so a miss indicates real corruption, which
+     * `rehydrateCatalog` records per-entry.
+     */
+    applyImportedIndexTags(stmt) {
+        const targetSchemaName = stmt.name.schema ?? this.getCurrentSchemaName();
+        const action = stmt.action;
+        let compute;
+        if (action.type === 'dropTags') {
+            compute = current => this.mutateTagRecord(current, { op: 'drop', keys: action.keys });
+        }
+        else if (action.mode === 'merge') {
+            compute = current => this.mutateTagRecord(current, { op: 'merge', tags: action.tags });
         }
-        const stmt = statements[0];
-        if (stmt.type === 'createTable') {
-            return this.importTable(stmt);
+        else {
+            compute = () => this.freezeTags(action.tags);
+        }
+        const { newSchema } = this.resolveIndexTagSwap(targetSchemaName, stmt.name.name, compute);
+        this.getSchemaOrFail(targetSchemaName).addTable(newSchema);
+        log(`Applied imported index tags for %s in schema %s`, stmt.name.name, targetSchemaName);
+    }
+    /**
+     * Import a plain view from its parsed DDL **without planning the body**.
+     * Registration is silent — no `notifyChange` fires, mirroring
+     * {@link importTable}/{@link importIndex} (a store rehydrating its own catalog
+     * must not re-emit persistence events). Body validation is deferred to first
+     * reference, exactly as {@link importTable} defers create-time work via
+     * `connect`: this makes view rehydration order-independent — a view over
+     * another view, a materialized view, or a not-yet-imported relation registers
+     * regardless of phase order, and a broken body surfaces only when queried.
+     *
+     * The stored `sql` is the canonical {@link createViewToString} rendering (not
+     * the raw entry text, which may bundle several statements). Synchronous: unlike
+     * table/index import there is no module storage to bind, so there is nothing to
+     * await.
+     */
+    importView(stmt) {
+        // Create the schema if absent (mirrors importTable) so a view rehydrates
+        // even into a schema that holds no tables; its `.name` is the canonical
+        // stored schemaName (see canonicalSchemaName).
+        const schema = this.getOrCreateSchema(stmt.view.schema || this.getCurrentSchemaName());
+        const targetSchemaName = schema.name;
+        const viewName = stmt.view.name;
+        const viewSchema = {
+            name: viewName,
+            schemaName: targetSchemaName,
+            sql: createViewToString(stmt),
+            // Any `with defaults (…)` rides inside stmt.select (→ selectAst).
+            selectAst: stmt.select,
+            columns: stmt.columns ? Object.freeze([...stmt.columns]) : undefined,
+            tags: stmt.tags && Object.keys(stmt.tags).length > 0 ? Object.freeze({ ...stmt.tags }) : undefined,
+        };
+        schema.addView(viewSchema);
+        log(`Imported view %s.%s`, targetSchemaName, viewName);
+        return { type: 'view', name: `${targetSchemaName}.${viewName}` };
+    }
+    /**
+     * Import a materialized view from its parsed DDL by re-materializing it
+     * through the shared {@link materializeView} core: the body is re-planned
+     * against the current (already-imported) sources, the memory backing table is
+     * rebuilt and filled, and row-time maintenance is re-registered — the same
+     * work the create emitter does, minus the `materialized_view_added` event (a
+     * store rehydrating its own catalog must not re-emit persistence events;
+     * `table_added` still fires for the backing table, exactly as on create).
+     *
+     * Unlike {@link importView}, the body plans EAGERLY (the backing cannot be
+     * filled without running it), so MV import is order-dependent: the body's
+     * sources — including another MV's backing for MV-over-MV — must already be
+     * registered. The store's `rehydrateCatalog` orders MVs after tables/views
+     * and resolves MV-over-MV chains by fixpoint retry. A body that cannot plan,
+     * fills with duplicate keys, or fails the row-time eligibility gate in
+     * `registerMaterializedView` throws (after {@link materializeView} rolls the
+     * half-built backing back), and the caller records it as a per-entry
+     * rehydration error.
+     *
+     * **Adopt fast path.** A pre-existing table at the backing name in the MV's
+     * own backing module (a durable host's phase-1 rehydration of its backing)
+     * is ADOPTED — registered as-is, no body re-execution — iff ALL gates pass
+     * (see {@link tryAdoptPreExistingBacking}); otherwise it is dropped and the
+     * MV refills through {@link materializeView}. Only import ever adopts —
+     * create and refresh are unchanged.
+     */
+    async importMaterializedView(spec, options) {
+        // Canonical stored schemaName (see canonicalSchemaName) — the schema itself
+        // is created below, after the DML-body gate.
+        const targetSchemaName = this.canonicalSchemaName(spec.schemaName || this.getCurrentSchemaName());
+        const viewName = spec.name;
+        // A DML body (insert/update/delete … returning) parses but is un-creatable —
+        // `planViewBody` rejects it at build time. Reject it here too, BEFORE
+        // materializing: a corrupt or hand-edited catalog entry would otherwise
+        // EXECUTE the mutation against live source tables during rehydrate.
+        if (spec.select.type === 'insert' || spec.select.type === 'update' || spec.select.type === 'delete') {
+            throw new QuereusError(`${spec.select.type.toUpperCase()} cannot be used as a materialized view body`, StatusCode.ERROR);
+        }
+        // Create the schema if absent (mirrors importTable/importView) so an MV
+        // rehydrates even into a schema that holds no tables.
+        this.getOrCreateSchema(targetSchemaName);
+        // Honor the re-parsed `using <module>(...)` clause (the generator emits it
+        // only when non-default). An unknown or capability-less module throws from
+        // buildBackingTableSchema inside materializeView — the caller records it
+        // as a per-entry rehydration error.
+        const backing = normalizeBackingModule(spec.moduleName, spec.moduleArgs);
+        const def = {
+            schemaName: targetSchemaName,
+            viewName,
+            // Any `with defaults (…)` rides inside spec.select (→ selectAst).
+            selectAst: spec.select,
+            bodySql: astToString(spec.select),
+            columns: spec.columns,
+            tags: spec.tags ? Object.freeze({ ...spec.tags }) : undefined,
+            backingModuleName: backing.storedModuleName,
+            backingModuleArgs: backing.storedModuleArgs,
+        };
+        // Derive the backing shape ONCE for the whole import (ordering gate, adopt
+        // gates, and the refill all read it). Throws when the body cannot plan —
+        // deliberately BEFORE any drop, so a not-yet-resolvable body (the store's
+        // MV-over-MV fixpoint: a dependent fails until its upstream's round lands)
+        // errors per-entry with any pre-existing backing preserved — data-safe.
+        const shape = deriveBackingShape(this.db, def.bodySql, def.columns);
+        // Declared-column arity mismatch: the entry can NEVER materialize, so throw
+        // with the backing preserved rather than dropping durable rows for nothing.
+        assertDeclaredColumnArity(def, shape);
+        // Ordering gate: a body source that is itself a pending maintained-table
+        // entry (its own `create materialized view` not yet imported this session)
+        // already pre-exists as a *plain* table, so the body PLANS — but its content
+        // may be about to be replaced by the upstream's own import. Defer this entry
+        // to a later fixpoint round (per-entry error; the store retries).
+        for (const src of shape.sourceTables) {
+            if (options?.pendingDerivations?.has(src)) {
+                throw new QuereusError(`cannot import materialized view '${targetSchemaName}.${viewName}' yet: source '${src}' is a maintained table whose own catalog entry has not imported this session`, StatusCode.ERROR);
+            }
         }
-        else if (stmt.type === 'createIndex') {
-            return this.importIndex(stmt);
+        // A durable backing-host module may have rehydrated the maintained table
+        // itself (phase 1: a plain `create table` bundle under the same name)
+        // before this MV catalog entry imports (phase 3). A pre-existing
+        // derivation-less table owned by the MV's own backing module IS that
+        // rehydrated backing: adopt it when every gate passes, else drop it and
+        // re-materialize from the body. A table in a DIFFERENT module is not
+        // ours — fail the entry rather than dropping user data. The create
+        // emitter keeps the plain collision error.
+        const preExisting = this.getTable(targetSchemaName, viewName);
+        if (preExisting) {
+            if (isMaintainedTable(preExisting)) {
+                throw new QuereusError(`cannot import materialized view '${targetSchemaName}.${viewName}': a maintained table with the same name already exists`, StatusCode.CONSTRAINT);
+            }
+            if ((preExisting.vtabModuleName ?? '').toLowerCase() === backing.moduleName) {
+                if (options?.trustBackings && await this.tryAdoptPreExistingBacking(def, preExisting, backing.moduleName, options.adoptedBackings, shape)) {
+                    log(`Adopted materialized view %s.%s (durable backing trusted; refill skipped)`, targetSchemaName, viewName);
+                    return { type: 'materializedView', name: `${targetSchemaName}.${viewName}` };
+                }
+                await this.dropTable(targetSchemaName, viewName, /*ifExists*/ true);
+            }
+            else {
+                throw new QuereusError(`cannot import materialized view '${targetSchemaName}.${viewName}': table '${viewName}' already exists in module '${preExisting.vtabModuleName}', not the MV's backing module '${backing.moduleName}'`, StatusCode.CONSTRAINT);
+            }
         }
-        throw new QuereusError(`importCatalog does not support statement type: ${stmt.type}`, StatusCode.ERROR);
+        await materializeView(this.db, def, shape);
+        log(`Imported materialized view %s.%s`, targetSchemaName, viewName);
+        return { type: 'materializedView', name: `${targetSchemaName}.${viewName}` };
+    }
+    /**
+     * The adopt-without-refill gate check + adopt for a pre-existing same-module
+     * backing during MV import. Returns true when the backing was adopted; false
+     * means "fall back to drop+refill". `shape` is the caller's pre-derived
+     * backing shape (derived before any drop — see {@link importMaterializedView}).
+     * Gates, of five (the caller already verified gate 1, same-module, and
+     * gate 5, `trustBackings`):
+     *
+     * 2. **Shape** — `backingShapeMatches(preExisting, shape)`: the persisted
+     *    backing is column-for-column what the re-planned body would build
+     *    (names, logical types, not-null, collation, physical PK).
+     * 3. **bodyHash** — automatic by construction: the catalog persists DDL and
+     *    import re-parses it, recomputing `computeBodyHash` from the same
+     *    canonical definition — there is no independently persisted hash that
+     *    could diverge, so no runtime check is possible or needed.
+     * 4. **Sources** — every table the body reads lives in the SAME module as
+     *    the backing (one storage substrate ⇒ the divergence window is the
+     *    documented crash window the marker attests against; a cross-module
+     *    source — e.g. memory — was itself just recomputed, so persisted backing
+     *    rows may be stale relative to it), AND every source that is itself a
+     *    maintained table was ADOPTED this session (`adoptedBackings`) — a
+     *    refilled upstream may hold new content its dependents must reflect.
+     *    (The caller's pending-derivations gate guarantees every maintained
+     *    source's own entry has already imported, so derivation presence is
+     *    decidable here.)
+     *
+     * A throw from `adoptMaterializedView` itself (the row-time eligibility gate
+     * in registration) propagates — per-entry error, backing left registered as
+     * a plain (derivation-less) table.
+     */
+    async tryAdoptPreExistingBacking(def, preExisting, backingModuleName, adoptedBackings, shape) {
+        if (!backingShapeMatches(preExisting, shape))
+            return false;
+        for (const qualified of shape.sourceTables) {
+            const dot = qualified.indexOf('.');
+            const sourceSchema = dot >= 0 ? qualified.slice(0, dot) : this.getCurrentSchemaName();
+            const sourceName = dot >= 0 ? qualified.slice(dot + 1) : qualified;
+            const source = this.getTable(sourceSchema, sourceName);
+            if (!source)
+                return false;
+            if ((source.vtabModuleName ?? '').toLowerCase() !== backingModuleName)
+                return false;
+            // A maintained-table source is another MV's backing; require it was
+            // adopted, not refilled, this session.
+            if (isMaintainedTable(source) && !adoptedBackings?.has(qualified))
+                return false;
+        }
+        await adoptMaterializedView(this.db, def, preExisting, shape);
+        adoptedBackings?.add(`${def.schemaName}.${def.viewName}`.toLowerCase());
+        return true;
     }
     /**
      * Import a table schema without calling module.create().
@@ -1355,26 +2644,45 @@ export class SchemaManager {
         const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
         const tableName = stmt.table.name;
         const { moduleName, effectiveModuleArgs, moduleInfo } = this.resolveModuleInfo(stmt);
-        const tableSchema = this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo);
+        // Rehydrate path: persisted DDL already made any non-BINARY collation explicit,
+        // so an omitted COLLATE is canonical BINARY regardless of the live session default.
+        const tableSchema = this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo, 'BINARY');
         try {
-            await moduleInfo.module.connect(this.db, moduleInfo.auxData, moduleName, targetSchemaName, tableName, effectiveModuleArgs, tableSchema);
+            // Module-facing stored-name contract (see canonicalSchemaName): the
+            // rehydrated connect receives `tableSchema`'s canonical schemaName and
+            // stored display casing, never the raw persisted-DDL spelling — a module
+            // keying storage by the args addresses the same physical store it created.
+            await moduleInfo.module.connect(this.db, moduleInfo.auxData, moduleName, tableSchema.schemaName, tableSchema.name, effectiveModuleArgs, tableSchema);
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
             throw new QuereusError(`Module '${moduleName}' connect failed during import for table '${tableName}': ${message}`, StatusCode.ERROR);
         }
-        let schema = this.getSchema(targetSchemaName);
-        if (!schema) {
-            const lowerSchemaName = targetSchemaName.toLowerCase();
-            schema = new Schema(lowerSchemaName);
-            this.schemas.set(lowerSchemaName, schema);
-        }
+        const schema = this.getOrCreateSchema(tableSchema.schemaName);
         schema.addTable(tableSchema);
+        // Catalog rehydration registers FK-bearing tables silently (no `table_added`
+        // fires) and via `getOrCreateSchema`, which only resets when it *creates* a
+        // schema — so importing a child into an existing schema (e.g. `main`) would
+        // otherwise leave a stale reverse FK index. Cold reopen masks this (the index
+        // is built lazily only after rehydration completes), but a re-import onto a
+        // live, already-built index would under-report — the fatal direction. Reset
+        // directly so the silent-import path upholds the same invariant as the events.
+        // The lens basis-FK gate shares this vector: a basis table imported silently
+        // after the gate was built would otherwise leave it under-reporting too.
+        this.invalidateReverseFkIndex();
+        this.invalidateLensFkGate();
         log(`Imported table %s.%s using module %s`, targetSchemaName, tableName, moduleName);
-        return { type: 'table', name: `${targetSchemaName}.${tableName}` };
+        return { type: 'table', name: `${tableSchema.schemaName}.${tableSchema.name}` };
     }
     /**
      * Import an index schema without calling module.createIndex().
+     *
+     * Reconstructs the index with full fidelity from the re-parsed DDL so a
+     * `CREATE [UNIQUE] INDEX ... (col [COLLATE x]) [WHERE ...]` survives a
+     * catalog round-trip: per-column collation, the UNIQUE flag, the partial
+     * predicate, and (for a unique index) the synthesized `derivedFromIndex`
+     * UNIQUE constraint — mirroring the live `buildIndexSchema` + the shared
+     * {@link appendIndexToTableSchema} that {@link createIndex} uses.
      */
     async importIndex(stmt) {
         const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
@@ -1385,9 +2693,10 @@ export class SchemaManager {
         if (!tableSchema) {
             throw new QuereusError(`Cannot import index '${indexName}': table '${tableName}' not found`, StatusCode.ERROR);
         }
-        // Build index columns schema
+        // Build index columns schema. Mirrors buildIndexSchema's collation resolution
+        // (per-column COLLATE → table column collation → BINARY).
         const indexColumns = stmt.columns.map(col => {
-            const colName = col.name;
+            const { name: colName, collation } = resolveImportedIndexColumn(col);
             if (!colName) {
                 throw new QuereusError(`Expression-based index columns are not supported during import`, StatusCode.ERROR);
             }
@@ -1395,26 +2704,52 @@ export class SchemaManager {
             if (colIdx === undefined) {
                 throw new QuereusError(`Column '${colName}' not found in table '${tableName}'`, StatusCode.ERROR);
             }
+            const tableColSchema = tableSchema.columns[colIdx];
             return {
                 index: colIdx,
                 desc: col.direction === 'desc',
+                collation: normalizeCollationName(collation || tableColSchema.collation || 'BINARY'),
             };
         });
         const indexSchema = {
             name: indexName,
             columns: Object.freeze(indexColumns),
+            unique: stmt.isUnique || undefined,
+            predicate: stmt.where,
             tags: stmt.tags && Object.keys(stmt.tags).length > 0 ? Object.freeze({ ...stmt.tags }) : undefined,
         };
-        // Add index to table without calling module.createIndex()
-        const updatedIndexes = [...(tableSchema.indexes || []), indexSchema];
-        const updatedTableSchema = {
-            ...tableSchema,
-            indexes: Object.freeze(updatedIndexes),
-        };
+        // Append the index (and synthesize the derived UNIQUE constraint when
+        // unique) without calling module.createIndex() — the storage already exists.
+        const updatedTableSchema = appendIndexToTableSchema(tableSchema, indexSchema);
         const schema = this.getSchemaOrFail(targetSchemaName);
         schema.addTable(updatedTableSchema);
         log(`Imported index %s on table %s.%s`, indexName, targetSchemaName, tableName);
         return { type: 'index', name: `${targetSchemaName}.${tableName}.${indexName}` };
     }
 }
+/**
+ * Resolves an indexed-column AST node to its underlying column name and optional
+ * collation, for catalog import.
+ *
+ * The parser folds `col COLLATE x` into a `collate` expression wrapping a bare
+ * column reference (see `indexedColumn()` in parser.ts), leaving `col.name`
+ * unset. Since `generateIndexDDL` always emits an explicit `COLLATE <c>` per
+ * column, *every* generated index DDL re-parses into this collate-wrapped form —
+ * so unwrapping it is required for the common case, not just non-BINARY
+ * collations. A genuine expression index (non-column operand) returns an unset
+ * name and is rejected by the caller.
+ */
+function resolveImportedIndexColumn(col) {
+    // Bare column reference (`col [ASC|DESC]`) — name set directly by the parser.
+    if (col.name) {
+        return { name: col.name, collation: col.collation };
+    }
+    // Collate-wrapped column (`col COLLATE x`) — unwrap to the column + collation.
+    const expr = col.expr;
+    if (expr?.type === 'collate' && expr.expr.type === 'column' && !expr.expr.table && !expr.expr.schema) {
+        return { name: expr.expr.name, collation: expr.collation };
+    }
+    // Anything else is a genuine expression index — unsupported on import.
+    return { name: undefined, collation: undefined };
+}
 //# sourceMappingURL=manager.js.map