@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/schema/manager.d.ts

@@ -1,13 +1,24 @@
-import { Schema } from './schema.js';
+import { Schema, type SchemaKind } from './schema.js';
 import type { IntegrityAssertionSchema } from './assertion.js';
 import type { Database } from '../core/database.js';
-import type { TableSchema } from './table.js';
+import type { TableSchema, ForeignKeyConstraintSchema } from './table.js';
 import type { FunctionSchema } from './function.js';
 import { type SqlValue } from '../common/types.js';
 import type { AnyVirtualTableModule, BaseModuleConfig } from '../vtab/module.js';
 import type { ViewSchema } from './view.js';
+import { type MaintainedTableSchema, type TableDerivation } from './derivation.js';
 import type * as AST from '../parser/ast.js';
 import { SchemaChangeNotifier } from './change-events.js';
+/**
+ * One FK that references some parent table, paired with its declaring child
+ * table. Entries in the reverse FK index ({@link SchemaManager.getReferencingForeignKeys});
+ * `fk` is the same object reference held in `childTable.foreignKeys` (identity
+ * preserved).
+ */
+export interface ReferencingForeignKey {
+    readonly childTable: TableSchema;
+    readonly fk: ForeignKeyConstraintSchema;
+}
 /**
  * Generic options passed to VTab modules during CREATE TABLE.
  * Modules are responsible for interpreting these.
@@ -16,7 +27,48 @@ export interface GenericModuleCallOptions extends BaseModuleConfig {
     moduleArgs?: readonly string[];
     statementColumns?: readonly AST.ColumnDef[];
     statementConstraints?: readonly AST.TableConstraint[];
-    isTemporary?: boolean;
+}
+/**
+ * Options for {@link SchemaManager.importCatalog}, controlling the
+ * materialized-view adopt-without-refill fast path. Both default off: a plain
+ * `importCatalog(ddl)` always drops and refills a pre-existing same-module
+ * backing — the always-correct posture.
+ */
+export interface ImportCatalogOptions {
+    /**
+     * Caller-attested trust in pre-existing durable backings (adopt gate 5):
+     * the caller asserts the store has NOT crashed since those backings were
+     * last written — e.g. the store module sets this from its consumed
+     * clean-shutdown catalog marker. Without that attestation, a crash between
+     * two durable modules' commit acknowledgements could have left source and
+     * backing divergent on disk (coordinated commit is not 2PC), and the
+     * DDL-level adopt gates cannot see content divergence — so adopt is never
+     * taken and any divergence self-heals through the refill.
+     */
+    trustBackings?: boolean;
+    /**
+     * Shared adopt ledger for one rehydration session: lowercased qualified
+     * names (`schema.<table>`) of every maintained table adopted so far,
+     * appended on each successful adopt. A maintained table whose body reads
+     * another maintained table may only adopt when that upstream is IN this
+     * set — an upstream that was refilled this session may hold new content, so
+     * its dependents must refill too; an upstream that adopted is unchanged, so
+     * trust composes. Pass one Set across all `importCatalog` calls of the
+     * session (the store's MV fixpoint rounds compose through it). Omitting it
+     * means no maintained-table-sourced MV can adopt.
+     */
+    adoptedBackings?: Set<string>;
+    /**
+     * Lowercased qualified names (`schema.<table>`) of maintained tables whose
+     * `create materialized view` catalog entries have NOT yet imported this
+     * rehydration session. An entry whose body reads any of these is deferred
+     * (throws, to be retried in a later fixpoint round): its source table
+     * already exists as a *plain* pre-rehydrated table, so without this gate
+     * the dependent would adopt/refill against content its upstream's own
+     * import may be about to replace. (Pre-unification this ordering fell out
+     * of the body failing to plan until the upstream MV record existed.)
+     */
+    pendingDerivations?: ReadonlySet<string>;
 }
 /**
  * Manages all schemas associated with a database connection (main, temp, attached).
@@ -39,6 +91,44 @@ export declare class SchemaManager {
      * See `assertion-hoist-cache.ts` and `core/database-assertions.ts`.
      */
     private assertionHoistSuppressed;
+    /**
+     * 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.
+     */
+    private mvRewriteSuppressed;
+    /**
+     * 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`.
+     */
+    private reverseFkIndex;
+    /**
+     * 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}.
+     */
+    private lensFkGate;
     /**
      * Creates a new schema manager
      *
@@ -162,14 +252,38 @@ export declare class SchemaManager {
      * state, even when `fn` throws.
      */
     withSuppressedAssertionHoist<T>(fn: () => T): T;
+    /**
+     * 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(): boolean;
+    /**
+     * 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<T>(fn: () => T): T;
+    /** Async counterpart of {@link withSuppressedMaterializedViewRewrite}. */
+    withSuppressedMaterializedViewRewriteAsync<T>(fn: () => Promise<T>): Promise<T>;
     /**
      * 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: string): Schema;
+    addSchema(name: string, kind?: SchemaKind): 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.
+     */
+    private getOrCreateSchema;
     /**
      * Removes a schema (e.g., for DETACH)
      *
@@ -211,6 +325,28 @@ export declare class SchemaManager {
      * @returns The ViewSchema or undefined if not found
      */
     getView(schemaName: string | null, viewName: string): ViewSchema | undefined;
+    /**
+     * 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: string | null | undefined, name: string): MaintainedTableSchema | undefined;
+    /**
+     * Returns all maintained tables (derivation-bearing tables) across all schemas.
+     */
+    getAllMaintainedTables(): MaintainedTableSchema[];
+    /**
+     * 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: string, tableName: string, derivation: TableDerivation): MaintainedTableSchema;
     /**
      * Retrieves any schema item (table or view) by name. Checks views first
      *
@@ -227,6 +363,40 @@ export declare class SchemaManager {
      * @returns The tags record or undefined if no tags are set
      */
     getTableTags(tableName: string, schemaName?: string): Readonly<Record<string, SqlValue>> | undefined;
+    /**
+     * 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.
+     */
+    private freezeTags;
+    /**
+     * 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.
+     */
+    private mutateTagRecord;
+    /**
+     * 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.
+     */
+    private commitTagUpdate;
+    /**
+     * 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.
+     */
+    private updateTableTags;
     /**
      * Sets metadata tags on an existing table, replacing any existing tags.
      *
@@ -235,6 +405,261 @@ export declare class SchemaManager {
      * @param schemaName Optional schema name (defaults to current schema)
      */
     setTableTags(tableName: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, keys: readonly string[], schemaName?: string): void;
+    /**
+     * 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.
+     */
+    private updateColumnTags;
+    /**
+     * 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: string, columnName: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, columnName: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, columnName: string, keys: readonly string[], schemaName?: string): void;
+    /**
+     * 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.
+     */
+    private updateConstraintTags;
+    /**
+     * 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: string, constraintName: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, constraintName: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, constraintName: string, keys: readonly string[], schemaName?: string): void;
+    /**
+     * 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.
+     */
+    private updateViewTags;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, keys: readonly string[], schemaName?: string): void;
+    /**
+     * 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.
+     */
+    private updateMaterializedViewTags;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, keys: readonly string[], schemaName?: string): void;
+    /**
+     * 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.
+     */
+    private updateIndexTags;
+    /**
+     * 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.
+     */
+    private resolveIndexTagSwap;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, tags: Record<string, SqlValue>, schemaName?: string): void;
+    /**
+     * 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: string, keys: readonly string[], schemaName?: string): void;
+    /**
+     * 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.
+     */
+    private invalidateReverseFkIndex;
+    /**
+     * 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.
+     */
+    private buildReverseFkIndex;
+    /**
+     * 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: string, parentTableName: string): readonly ReferencingForeignKey[];
+    /**
+     * 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(): void;
+    /**
+     * 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: string, tableName: string): boolean;
     /**
      * Asserts that no other table has FK rows referencing the table being dropped.
      * Self-referential FKs are skipped — those rows go away with the table.
@@ -270,6 +695,23 @@ export declare class SchemaManager {
      * @throws QuereusError if the schema does not exist
      */
     getSchemaOrFail(name: string): 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: string): string;
     /**
      * Retrieves a table from the specified schema
      *
@@ -308,6 +750,18 @@ export declare class SchemaManager {
      * Shared by both createTable (new storage) and importTable (existing storage).
      */
     private buildTableSchemaFromAST;
+    /**
+     * 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: AST.CreateTableStmt, schemaName: string): TableSchema;
     /**
      * Walks an expression AST and rejects bind-parameter and (optionally)
      * column-reference nodes. Used by DDL-time DEFAULT/CHECK validators where
@@ -331,7 +785,53 @@ export declare class SchemaManager {
      * context variable, and the build attempt is permitted to fail —
      * scope resolution is deferred to row-time).
      */
+    /** True when a DEFAULT expression embeds a subquery (scalar subquery / EXISTS / SELECT). */
+    private defaultEmbedsSubquery;
+    /** True when a DEFAULT expression reads the row being written via `new.<column>`. */
+    private defaultReferencesNewRow;
+    /**
+     * 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.
+     */
+    private makeDdlValidationContext;
+    /**
+     * 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).
+     */
+    private validateOneDefault;
     private validateDefaultDeterminism;
+    /**
+     * 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: AST.Expression, columnName: string, tableName: string, hasMutationContext: boolean): void;
+    /**
+     * 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: AST.Expression, columnName: string, tableName: string, hasMutationContext: boolean): void;
+    /** Shared body for the ALTER-time DEFAULT validators (ALTER COLUMN SET DEFAULT / ADD COLUMN). */
+    private validateDdlDefault;
     /**
      * Validates that CHECK constraint expressions don't call non-deterministic
      * functions and don't reference bind parameters. Walks the AST and looks
@@ -357,12 +857,6 @@ export declare class SchemaManager {
      * Builds an IndexSchema from AST column definitions, validating against the table schema.
      */
     private buildIndexSchema;
-    /**
-     * 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.
-     */
-    private addIndexToTableSchema;
     /**
      * Drops a secondary index from the table that owns it.
      * Searches all tables in the target schema to find the owning table.
@@ -374,7 +868,8 @@ export declare class SchemaManager {
     dropIndex(schemaName: string, indexName: string, ifExists?: boolean): Promise<void>;
     /**
      * 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`).
      */
     private emitAutoSchemaEventIfNeeded;
     /**
@@ -385,28 +880,184 @@ export declare class SchemaManager {
      * @returns A Promise that resolves to the created TableSchema.
      * @throws QuereusError on errors (e.g., module not found, create fails, table exists).
      */
-    createTable(stmt: AST.CreateTableStmt): Promise<TableSchema>;
+    /**
+     * 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: AST.CreateTableStmt): TableSchema;
+    /**
+     * `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.
+     */
+    createTable(stmt: AST.CreateTableStmt, preferBacking?: boolean): Promise<TableSchema>;
+    /**
+     * 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`).
+     */
+    createBackingTable(tableSchema: TableSchema): Promise<TableSchema>;
     /**
      * 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
      */
-    importCatalog(ddlStatements: string[]): Promise<{
+    importCatalog(ddlStatements: string[], options?: ImportCatalogOptions): Promise<{
         tables: string[];
         indexes: string[];
+        views: string[];
+        materializedViews: string[];
     }>;
     /**
-     * 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.
+     */
+    private importDDL;
+    /**
+     * 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.
+     */
+    private applyImportedIndexTags;
+    /**
+     * 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.
      */
-    private importSingleDDL;
+    private importView;
+    /**
+     * 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.
+     */
+    private importMaterializedView;
+    /**
+     * 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.
+     */
+    private tryAdoptPreExistingBacking;
     /**
      * Import a table schema without calling module.create().
      * Uses module.connect() to bind to existing storage.
@@ -414,6 +1065,13 @@ export declare class SchemaManager {
     private importTable;
     /**
      * 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.
      */
     private importIndex;
 }