@quereus/store 3.3.0 → 4.0.0

package/dist/src/common/store-module.d.ts

@@ -12,17 +12,22 @@
  *   - {prefix}.__stats__ - Unified stats store (row counts for all tables)
  *   - Catalog store: __catalog__ - DDL metadata keyed by {schema}.{table}
  */
-import type { Database, TableSchema, TableIndexSchema, VirtualTableModule, BaseModuleConfig, BestAccessPlanRequest, BestAccessPlanResult, ModuleCapabilities, SchemaChangeInfo } from '@quereus/quereus';
+import type { Database, TableSchema, TableIndexSchema, VirtualTableModule, BaseModuleConfig, BestAccessPlanRequest, BestAccessPlanResult, ModuleCapabilities, SchemaChangeInfo, Schema, MappingAdvertisement, ViewSchema, MaintainedTableSchema, BackingHost, LensDeploymentSnapshot } from '@quereus/quereus';
 import type { KVStore, KVStoreProvider } from './kv-store.js';
 import type { StoreEventEmitter } from './events.js';
 import { TransactionCoordinator } from './transaction.js';
 import { StoreTable, type StoreTableConfig, type StoreTableModule } from './store-table.js';
 /**
  * Result of catalog rehydration.
+ *
+ * `views` / `materializedViews` are additive (existing consumers — e.g.
+ * `quoomb-web` — read only `.errors`). Errors from any phase land in `errors`.
  */
 export interface RehydrationResult {
     tables: string[];
     indexes: string[];
+    views: string[];
+    materializedViews: string[];
     errors: RehydrationError[];
 }
 /**
@@ -32,6 +37,14 @@ export interface RehydrationError {
     ddl: string;
     error: Error;
 }
+/**
+ * Listener the host binds via {@link StoreModule.setLensDeploymentListener} to
+ * forward a logical `apply schema` lens deployment onward (typically to the sync
+ * layer's basis-table lifecycle bookkeeping). Kept as a plain callback so
+ * `@quereus/store` stays free of a `@quereus/sync` dependency; the worker — which
+ * depends on both — wires the two together.
+ */
+export type LensDeploymentListener = (db: Database, logicalSchemaName: string, snapshot: LensDeploymentSnapshot) => void | Promise<void>;
 /**
  * Configuration options for StoreModule tables.
  */
@@ -57,16 +70,69 @@ export interface StoreModuleConfig extends BaseModuleConfig {
 export declare class StoreModule implements VirtualTableModule<StoreTable, StoreModuleConfig>, StoreTableModule {
     private provider;
     private stores;
-    private coordinators;
+    /**
+     * The single transaction coordinator shared by every {@link StoreTable} this
+     * module owns — the unit of cross-table atomicity (see {@link getCoordinator}).
+     * Lives for the module's lifetime: a single table's drop must NOT evict it
+     * (sibling tables still use it); only {@link closeAll} clears it.
+     */
+    private moduleCoordinator?;
     private tables;
     private eventEmitter?;
+    /**
+     * Optional listener wired by the host (the worker) to forward a logical
+     * `apply schema` lens deployment to the sync layer's lifecycle bookkeeping.
+     * The store module is the only basis-backing host with both persistence and a
+     * `db` handle, so it is the forwarder; `@quereus/store` must not depend on
+     * `@quereus/sync`, so the listener is a plain callback the worker binds.
+     */
+    private lensDeploymentListener?;
+    /** Unsubscribe thunk for the engine `SchemaChangeNotifier` listener, set on first hook with a `db`. */
+    private schemaListenerUnsub?;
+    /** The `Database` whose notifier we subscribed to. One module instance serves one `Database`. */
+    private subscribedDb?;
+    /**
+     * Serialized chain of pending catalog writes triggered by engine schema-change
+     * events (catalog-only tag swaps). `notifyChange` invokes listeners synchronously
+     * and does not await them, so the actual read-compare-write runs here, in order,
+     * and is drained by `closeAll` (and `whenCatalogPersisted`) before the provider closes.
+     */
+    private persistQueue;
+    /**
+     * The JSON-serialized stale-MV set last enqueued onto {@link persistQueue} (the
+     * `\x00meta\x00stale_mvs` value), or `undefined` when no baseline is established
+     * for the current subscription. The schema-change listener compares each
+     * recomputed set against this so an unrelated `table_modified` (e.g. a tag swap
+     * that changes no MV's staleness) costs no extra fsync. Reset to `undefined`
+     * whenever a fresh `Database` is subscribed ({@link ensureSchemaSubscription}) so
+     * a reopened module re-establishes the baseline from the first relevant event (or
+     * the rehydrate tail).
+     */
+    private lastPersistedStaleMvs;
+    /**
+     * Whether the provider exposes an atomic cross-store commit domain
+     * ({@link KVStoreProvider.beginAtomicBatch}) — the capability the MV adopt fast
+     * path's gate-5 drop hinges on. Fixed for the provider's lifetime, so cached at
+     * construction (and used as the single gate for both writing AND reading the durable
+     * stale-MV set). Gating the **write** on it is load-bearing for soundness, not just an
+     * fsync saving: only an atomic-capable session — whose commits can never tear a source
+     * from its same-module backing — ever writes the durable set, so the set a later atomic
+     * session reads was necessarily written under that same no-tear guarantee. A persistent
+     * non-atomic provider therefore can never leave a torn-but-"not-stale" set for an atomic
+     * reopen to trust (it writes none); such a store falls back to the clean-shutdown marker.
+     */
+    private readonly atomicProvider;
     constructor(provider: KVStoreProvider, eventEmitter?: StoreEventEmitter);
     /**
      * Returns capability flags for this module.
      *
-     * The base StoreModule does NOT provide transaction isolation.
-     * Without isolation, queries see only committed data (no read-your-own-writes
-     * within a transaction). To enable isolation, wrap with IsolationModule:
+     * The base StoreModule does NOT provide transaction isolation: there is no
+     * snapshot isolation and no cross-connection isolation (readers on other
+     * connections see only committed data). Within a transaction, reads through
+     * the table's shared coordinator DO see that transaction's own pending
+     * writes (read-your-own-writes — `StoreTable.query` merges the pending op
+     * view over the committed store). For full isolation, wrap with
+     * IsolationModule:
      *
      * ```typescript
      * import { IsolationModule, MemoryTableModule } from '@quereus/quereus';
@@ -81,14 +147,132 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * ```
      */
     getCapabilities(): ModuleCapabilities;
+    /**
+     * Generic-module mapping advertisements: assembled from the `quereus.lens.decomp.*`
+     * reserved tags on this basis schema's tables. Returns `[]` when the schema has no
+     * such tags, leaving the lens default mapper on its name-match path.
+     * See `docs/lens.md` § The Default Mapper.
+     */
+    getMappingAdvertisements(_db: Database, basisSchema: Schema): readonly MappingAdvertisement[];
+    /**
+     * Backing-host capability (engine `vtab/backing-host.ts`): resolve the
+     * privileged surface for a store table this module owns, or undefined when the
+     * table is unknown to it. The host binds the CURRENT (StoreTable, coordinator)
+     * pair — `destroy` evicts both maps, so a drop+recreate yields fresh instances
+     * and the returned host is pinned to one backing-table incarnation (the engine
+     * resolves hosts fresh per call, never caching them). Resolution goes through
+     * {@link getOrReconnectTable} so a rehydrated-but-untouched (or rename-evicted)
+     * backing still resolves; the ownership pre-check keeps the reconnect fallback
+     * from adopting a registered table owned by a different module (`vtabModule`
+     * must be this StoreModule, or a wrapper — IsolationModule — exposing it as
+     * `underlying`). Attaching the coordinator eagerly makes the shared
+     * StoreTable's read paths merge the host's pending writes (reads-own-writes
+     * for a `select` from the MV mid-transaction).
+     */
+    getBackingHost(db: Database, schemaName: string, tableName: string): BackingHost | undefined;
+    /**
+     * Resolve a {@link StoreTable} this module owns, reconnecting a
+     * rehydrated-but-untouched (or rename-evicted) table via
+     * {@link getOrReconnectTable}. The ownership pre-check keeps the reconnect
+     * fallback from adopting a registered table owned by a DIFFERENT module:
+     * `vtabModule` must be this StoreModule, or a wrapper (IsolationModule)
+     * exposing it as `underlying`. Returns undefined for an unknown/non-owned
+     * table. Shared by {@link getBackingHost} and
+     * {@link getTableForExternalWrite}; neither attaches a coordinator here —
+     * each layers its own pending-state policy on top.
+     */
+    private resolveOwnedTable;
+    /**
+     * Resolve the live {@link StoreTable} for an externally-applied write to a
+     * SOURCE table (committed put/delete + secondary-index + stats maintenance via
+     * {@link StoreTable.applyExternalRowChanges}). Returns undefined when the table
+     * is not this module's.
+     *
+     * Resolution goes through {@link resolveOwnedTable} (the shared ownership
+     * pre-check + reconnect fallback). Unlike `getBackingHost` it attaches no
+     * coordinator: external writes target committed storage, and the before-image
+     * read (`readEffectiveRowByKey`) merges any already-attached coordinator's
+     * pending state on its own (none when the table is freshly reconnected).
+     */
+    getTableForExternalWrite(db: Database, schemaName: string, tableName: string): StoreTable | undefined;
     /**
      * Get the event emitter for this module.
      */
     getEventEmitter(): StoreEventEmitter | undefined;
+    /**
+     * Bind (or clear, with `undefined`) the lens-deployment forwarder. The host
+     * (worker) calls this to route a logical `apply schema`'s deployment to the
+     * sync layer; see {@link notifyLensDeployment}.
+     */
+    setLensDeploymentListener(listener: LensDeploymentListener | undefined): void;
+    /**
+     * Engine `notifyLensDeployment` hook: a logical `apply schema X` fires this on
+     * every registered module once the lens catalog mutation + snapshot rotation
+     * complete (see `VirtualTableModule.notifyLensDeployment`). The store module —
+     * the basis-backing host — forwards the deployment to the bound listener so the
+     * sync layer can update its basis-table lifecycle bookkeeping.
+     *
+     * INVERSION OF THE ENGINE FIRING CONTRACT: the engine documents that a throwing
+     * notification aborts `apply schema X`. We deliberately wrap the listener in
+     * try/catch and SWALLOW (structured-log only) here — lifecycle bookkeeping is
+     * advisory and must never brick a schema apply. A bookkeeping bug is a logged
+     * warning, not a failed deploy.
+     */
+    notifyLensDeployment(db: Database, logicalSchemaName: string, snapshot: LensDeploymentSnapshot): Promise<void>;
     /**
      * Get the KVStoreProvider used by this module.
      */
     getProvider(): KVStoreProvider;
+    /**
+     * Build the set of physical store names this module's data/index stores
+     * currently occupy in `schemaName`, mapping each name to a human description
+     * of the logical object that owns it (for sited collision messages).
+     *
+     * Physical store names are built by string concatenation (`{schema}.{table}` /
+     * `{schema}.{table}_idx_{index}`) and the `_idx_` delimiter is itself a legal
+     * substring of any identifier, so two distinct logical objects (e.g. index
+     * `archive` on `t` and a sibling table `t_idx_archive`) can collapse to the
+     * same physical name. This set is the authoritative occupancy used by
+     * {@link assertStoreNameFree} to reject such a collision at CREATE time.
+     *
+     * The occupancy is the union of two sources, robust to lazy connection and the
+     * isolation wrapper (see the ticket's "Enumeration source" section):
+     *   1. `this.tables` — every store table this module touched this session.
+     *   2. the target schema's catalog tables whose `vtabModule === this` and which
+     *      are not views — store-backed tables not yet lazily connected.
+     * Names embed the schema prefix, so cross-schema entries never collide and no
+     * per-schema filter on `this.tables` is needed. Memory-backed siblings and
+     * views own no store in this provider and are excluded (the `=== this` /
+     * `!isView` filter) to avoid false-positive rejects.
+     *
+     * No self-exclusion: at each guarded call the candidate object is not yet
+     * registered (create/createIndex run before the engine adds it) so it cannot
+     * self-collide; and for renameTable the renamed table's OWN stores stay in the
+     * set deliberately. Any overlap between a name the rename introduces and an
+     * own current store is a footprint-swap rename (`t` with index `x` → `t_idx_x`,
+     * or table `u_idx_x` with index `x` → `u`) that providers cannot relocate
+     * safely — relocation order determines whether a source is clobbered before it
+     * is moved — while no benign rename produces such an overlap. Keeping own
+     * stores in the set therefore causes no false rejects and keeps the
+     * reject-before-any-side-effect guarantee uniform.
+     */
+    private collectOccupiedStoreNames;
+    /**
+     * Throws `StatusCode.ERROR` when `candidate` (a physical store name produced by
+     * the key-builder for an object about to be created/renamed) already names an
+     * existing data or index store in `schemaName`. `candidateDesc` describes the
+     * incoming logical object; the message names the candidate physical store and
+     * both conflicting logical objects and is actionable (rename one of them).
+     *
+     * Must run BEFORE any storage side-effect (`getStore` / `getIndexStore` / the
+     * physical relocation): the provider opens/creates the store eagerly, so a
+     * guard that ran after would already have aliased the colliding object's store.
+     *
+     * Callers checking several candidates against the same occupancy (renameTable
+     * checks the new data store plus every relocated index store) pass a
+     * precomputed `occupied` map so the occupancy is collected once, not per call.
+     */
+    private assertStoreNameFree;
     /**
      * Creates a new store-backed table.
      * Called by CREATE TABLE.
@@ -106,11 +290,59 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
     /**
      * Destroys a store table and its storage.
      */
-    destroy(_db: Database, _pAux: unknown, _moduleName: string, schemaName: string, tableName: string): Promise<void>;
+    destroy(db: Database, _pAux: unknown, _moduleName: string, schemaName: string, tableName: string): Promise<void>;
+    /**
+     * Reclaim the local storage of a DETACHED basis table by name — the store-side
+     * target of the sync layer's basis-eviction sweep
+     * (`SyncManager.evictExpiredBasisTables`, `docs/migration.md` § 4 Contract).
+     *
+     * Unlike {@link destroy}, the table is no longer in the engine schema (it was
+     * removed from the basis on detach; only its physical storage lingered), so
+     * there is no `db`/schema to consult and NO schema-change event is emitted — the
+     * engine already saw the detach. The caller (the sync recorder) supplies the
+     * captured secondary-index name list it retained from before detach, because the
+     * table schema (and its index list) is gone: passing the exact names avoids the
+     * provider prefix-scanning `{table}_idx_`, which can clobber a sibling table
+     * literally named `{table}_idx_<x>`.
+     *
+     * Idempotent: any cached handles are evicted and disconnected, then the data /
+     * index / stats stores and the catalog DDL are removed. Storage already gone (a
+     * prior real `drop table` ran `destroy`) is treated as success — the provider's
+     * `deleteTableStores` no-ops on absent stores and `removeTableDDL` no-ops on an
+     * absent key.
+     */
+    reclaimDetachedTable(schemaName: string, tableName: string, indexNames: readonly string[]): Promise<void>;
+    /**
+     * Tear down a table's in-memory handles and physical storage: evict the cached
+     * StoreTable / store / coordinator (synchronously, before any await, so a
+     * concurrent reconnect cannot observe a stale instance mid-teardown), disconnect
+     * the handle, delete the provider's data / index / stats stores (by the exact
+     * index names — never a `{table}_idx_` prefix scan, which could clobber a sibling
+     * table literally named `{table}_idx_<x>`), and remove the catalog DDL.
+     *
+     * Shared by {@link destroy} (live `drop table`) and {@link reclaimDetachedTable}
+     * (post-detach eviction). The caller owns the index-name source (live schema vs.
+     * the captured pre-detach list) and any schema-change event. Idempotent: the
+     * provider no-ops on absent stores and `removeTableDDL` no-ops on an absent key.
+     */
+    private tearDownTableStorage;
+    /**
+     * Returns the connected StoreTable for `schemaName.tableName`, lazily
+     * reconnecting from the engine's schema registry when absent.
+     *
+     * `renameTable` evicts the old key from `this.tables` and expects the next
+     * `connect()` to repopulate under the new name, but `apply schema` can run
+     * follow-up DDL (ALTER TABLE, CREATE/DROP INDEX) against the new name
+     * without an intervening connect. Mirror connect()'s schemaManager lookup
+     * so that DDL finds the moved table. Safe for the index paths because
+     * SchemaManager calls the module BEFORE mutating the registered table
+     * schema, so the reconnected cache matches what a connected instance holds.
+     */
+    private getOrReconnectTable;
     /**
      * Creates an index on a store-backed table.
      */
-    createIndex(_db: Database, schemaName: string, tableName: string, indexSchema: TableIndexSchema): Promise<void>;
+    createIndex(db: Database, schemaName: string, tableName: string, indexSchema: TableIndexSchema): Promise<void>;
     /**
      * Drops an index on a store-backed table.
      *
@@ -119,7 +351,7 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * synthesized from it, tagged with `derivedFromIndex`), releases the
      * cached index-store handle, and tears down the underlying index store.
      */
-    dropIndex(_db: Database, schemaName: string, tableName: string, indexName: string): Promise<void>;
+    dropIndex(db: Database, schemaName: string, tableName: string, indexName: string): Promise<void>;
     /**
      * Build index entries for all existing rows in a table.
      *
@@ -130,6 +362,37 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * atomically.
      */
     private buildIndexEntries;
+    /**
+     * Clear and rebuild every secondary index of `schema` against the (already
+     * re-encoded) data store. Secondary-index keys embed the PK suffix, so they must
+     * be rewritten whenever the data-store PK key bytes change — which happens both
+     * on `ALTER PRIMARY KEY` (the PK columns change) and on an `ALTER COLUMN … SET
+     * COLLATE` on a PK member (a PK column's key collation changes). Shared by both
+     * arms so the clear-then-rebuild stays identical. `schema` must already be the
+     * post-ALTER schema (its `primaryKeyDefinition` + column collations drive the new
+     * PK-suffix encoding via {@link buildIndexEntries}).
+     */
+    private rebuildSecondaryIndexes;
+    /**
+     * Validates the existing rows in `dataStore` against a UNIQUE constraint,
+     * throwing `CONSTRAINT` on the first duplicate before any schema mutation.
+     * Used by `ADD CONSTRAINT UNIQUE` (validate against the current collation) and
+     * by `SET COLLATE` (pass an `updatedSchema` whose altered column carries the
+     * NEW collation, so the dedup is performed under it). Mirrors the duplicate
+     * detection in {@link buildIndexEntries}: a `seen` Set keyed on a per-column
+     * collation-aware signature of the constrained values, with SQL NULL semantics
+     * (a row with any NULL constrained value never counts as a duplicate) and the
+     * partial `predicate` honored.
+     *
+     * No index store is written — store UNIQUE enforcement is a full-scan over
+     * `uniqueConstraints` at write time. The signature is built by
+     * {@link serializeRowKey} with one normalizer per constrained column drawn from
+     * `tableSchema.columns[idx].collation`, so a per-column NOCASE/RTRIM collation
+     * is honored (matching write-time `compareSqlValues` enforcement). Residual: a
+     * custom comparator-only collation has no string normalizer and falls back to
+     * BINARY for the dedup (see docs/schema.md store-collation note).
+     */
+    private validateUniqueOverExistingRows;
     /**
      * Alters an existing store table's structure (ADD/DROP/RENAME COLUMN).
      * Performs eager row migration for ADD and DROP, schema-only update for RENAME.
@@ -149,8 +412,23 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
     renameTable(db: Database, schemaName: string, oldName: string, newName: string): Promise<void>;
     /**
      * Modern access planning interface.
+     *
+     * Every plan is stamped with `honorsCollatedRangeBounds`: the store's post-fetch
+     * row filter (`StoreTable.matchesFilters` → `compareValues`) compares each pushed
+     * constraint — including LT/LE/GT/GE range bounds — under the column's declared
+     * collation, so the access path's collation-cover analysis may keep a
+     * collation-matched non-BINARY (NOCASE/RTRIM) PK range/BETWEEN seek instead of
+     * declining to a SeqScan + residual (see `classifyConstraintCover` in
+     * rule-select-access-path.ts). The seek really does narrow: `StoreTable.scanPKRange`
+     * (via `StoreTable.buildPKRangeBounds`) encodes the LT/LE/GT/GE bounds under the
+     * same per-column key collations the data keys use and iterates that
+     * seek-start/early-termination window. The window is a SUPERSET, so the post-fetch
+     * row filter still reproduces the exact collation semantics — and a comparator-only
+     * collation with no byte encoder safely falls back to a full scan. Mirrors the
+     * memory module's advertisement.
      */
     getBestAccessPlan(_db: Database, tableInfo: TableSchema, request: BestAccessPlanRequest): BestAccessPlanResult;
+    private computeBestAccessPlan;
     /**
      * Compute the PK-ordering advertisement for a scan-style plan. Returns the
      * `providesOrdering` / `monotonicOn` / `supportsAsofRight` fields for a plan
@@ -189,38 +467,320 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      */
     getStatsStore(schemaName: string, tableName: string): Promise<KVStore>;
     /**
-     * Get or create a transaction coordinator for a table.
+     * Get (lazily constructing) the SINGLE transaction coordinator shared by every
+     * table this module owns — the unit of cross-table atomicity. Every
+     * {@link StoreTable} attaches to the same instance, so a transaction touching
+     * several of the module's tables commits/rolls back as one all-or-nothing
+     * batch.
+     *
+     * Synchronously constructible: ops are addressed by explicit store handle, so
+     * the coordinator never needs to open a store to be created. This lets callers
+     * that must stay synchronous (e.g. a `BackingHost.connect()`) obtain a working
+     * coordinator before any table's store has been opened.
+     */
+    getCoordinator(): TransactionCoordinator;
+    /**
+     * Build the catalog entry for a table: its CREATE TABLE DDL, one
+     * `CREATE [UNIQUE] INDEX` statement per persistable secondary index, and one
+     * `alter index … set tags (…)` statement per exposed implicit index carrying
+     * user tags, newline-joined into a single multi-statement bundle keyed by
+     * `{schema}.{table}`.
+     *
+     * Bundling the indexes into the table's own entry means every existing
+     * re-persist path — `saveTableDDL` (each `alterTable` arm, `renameTable`) and
+     * the `table_modified` listener (`persistCatalogIfChanged`) — carries the
+     * indexes along for free, and `removeTableDDL` drops them with the table. The
+     * bundle is consumed on reopen by `rehydrateCatalog` → `importCatalog`, whose
+     * `parser.parseAll` splits it AST-by-AST (never on `\n`) and imports each
+     * statement in document order, so the table registers before its indexes.
+     *
+     * Both the table DDL and the index DDL are emitted without a `db` arg, keeping
+     * the persistence-safe fully-qualified form. Hidden implicit covering indexes
+     * (the auto-built BTree backing a declared UNIQUE constraint) are excluded —
+     * they are a backing detail that round-trips via the table's UNIQUE constraint,
+     * not as a standalone CREATE INDEX. For store tables `buildTableSchemaFromAST`
+     * synthesizes none of those, so in practice every index is included; the guard
+     * is defensive. A `CREATE UNIQUE INDEX`'s derived UNIQUE constraint is already
+     * excluded from the table DDL by the generator, so it round-trips solely via
+     * its own `CREATE UNIQUE INDEX` line — no doubling.
+     *
+     * An *exposed* implicit index (a non-derived UNIQUE constraint tagged
+     * `quereus.expose_implicit_index = true`, never materialized in store mode)
+     * must NOT get a synthetic `CREATE INDEX` line — re-import would materialize a
+     * real `IndexSchema` and change the store-mode shape. Its user tags
+     * (`UniqueConstraintSchema.exposedIndexTags`) instead ride a trailing
+     * `alter index … set tags` line, which `importDDL` re-applies silently after
+     * the CREATE TABLE in the same entry has registered the constraint. Empty tag
+     * records emit no line, and `exposedImplicitIndexes` returns `[]` for
+     * memory-mode tables (name materialized) and orders descriptors by the
+     * `uniqueConstraints` array, so the bundle stays byte-deterministic — which
+     * the compare-write in `persistCatalogIfChanged` relies on.
      */
-    getCoordinator(tableKey: string, config: StoreTableConfig): Promise<TransactionCoordinator>;
+    private buildCatalogEntry;
     /**
-     * Save table DDL to the catalog store.
+     * Save table DDL (bundled with its secondary index DDL) to the catalog store.
      */
     saveTableDDL(tableSchema: TableSchema): Promise<void>;
     /**
-     * Load all DDL statements from the catalog store.
-     * Used to restore persisted tables on startup.
+     * Load all DDL **values** from the catalog store (keys discarded).
+     * Used to restore persisted tables on startup and by tests asserting persisted DDL.
+     * Note: this returns table, view, AND materialized-view entries intermixed —
+     * {@link rehydrateCatalog} uses {@link loadCatalogEntries} (keys retained) to
+     * classify them. Meta entries (e.g. the clean-shutdown marker) are not DDL
+     * and are filtered out.
      */
     loadAllDDL(): Promise<string[]>;
     /**
-     * Rehydrate persisted catalog into the in-memory schema manager.
+     * Load every catalog entry as `{ key, ddl }`. Unlike {@link loadAllDDL} (values
+     * only) this retains the key so {@link rehydrateCatalog} can classify each entry
+     * (table / view / materialized view) by its reserved key prefix.
+     */
+    private loadCatalogEntries;
+    /**
+     * Rehydrate the persisted catalog into the in-memory schema manager, in
+     * dependency order.
+     *
+     * Establishes the engine schema-change subscription up front (so a reopened DB
+     * persists subsequent DDL even when its first post-reopen statement is a view/MV,
+     * which never routes through a module hook — all the lazy subscription points are
+     * table hooks). Then loads every catalog entry once, classifies each by its key
+     * prefix into {tables, views, materialized views}, and imports in three phases:
+     *
+     *   1. **Tables** — `importCatalog` (connect to existing storage; refresh connected
+     *      `StoreTable` schemas).
+     *   2. **Views** — `importCatalog` (engine silent-register; body validation deferred
+     *      to query time, so order among views — and view-over-MV / view-over-view —
+     *      does not matter, and no schema-change event fires → phase 2 writes nothing).
+     *   3. **Materialized views** — `importCatalog` per entry (engine re-materialize:
+     *      rebuilds the memory backing from current source data, re-registers row-time
+     *      maintenance, re-runs the eligibility gate — the same core the create emitter
+     *      uses, but silent: no `materialized_view_added` fires, so phase 3 writes
+     *      nothing back to the catalog). A store-hosted backing that phase 1 already
+     *      rehydrated is **adopted without the refill** when the engine's adopt gates
+     *      pass — see the clean-shutdown marker below.
+     *
+     * **Clean-shutdown marker.** Before anything loads, the reserved
+     * `\x00meta\x00clean_shutdown` catalog entry (written by {@link closeAll} after
+     * every batch flushed) is consumed: parsed into `{ trusted, staleAtClose }`, then
+     * **deleted immediately** — single-use, so a crash later in this session (or a
+     * second rehydrate without an intervening clean close) is detected at the next open
+     * and every adopt falls back to the always-correct drop+refill, self-healing any
+     * crash-window divergence (coordinated commit is not 2PC across stores). The marker
+     * payload is the JSON set of MVs that were **stale-at-close** (row-time maintenance
+     * detached, so the durable backing may be behind); phase 3 withholds trust per-entry
+     * for those — `trustBackings: trusted && !staleAtClose.has(name)` — so a
+     * stale-at-close MV refills (recomputing content and re-arming maintenance) while
+     * every live-at-close MV keeps the fast path. The one shared `adoptedBackings` set
+     * composes across fixpoint rounds (an upstream MV adopted in round 1 enables its
+     * dependent in round 2, while a refilled — or stale-at-close — upstream is never
+     * added to it, forcing dependents to refill).
+     *
+     * **MV-over-MV ordering** is handled by a fixpoint retry rather than a static topo
+     * sort: an MV's resolved `sourceTables` are computed at import time, not serialized
+     * in the DDL, so they are unavailable before import. Each round passes the names of
+     * every OTHER still-pending MV entry as `pendingDerivations`; the engine defers any
+     * entry whose body reads one (its source already pre-exists as a phase-1 plain
+     * table, so the body would otherwise plan against content the upstream's own import
+     * may be about to replace). The loop repeats while any MV makes progress — robust to
+     * arbitrary nesting depth. A genuinely unbuildable MV — a missing (e.g. memory)
+     * source, or an unresolvable cycle — makes no progress in a round and is recorded in
+     * `errors`.
      *
-     * Loads all DDL from the catalog store and imports each entry
-     * individually. Parse failures are collected rather than fatal,
-     * so a single corrupt entry does not prevent other tables from
-     * loading.
+     * Per-entry errors in any phase are collected (not fatal) so one bad object does not
+     * abort the rest.
      *
-     * Call after `db.registerModule()` (and `db.setDefaultVtabName()`
-     * if DDL may lack a USING clause).
+     * Call after `db.registerModule()` (and `db.setDefaultVtabName()` if DDL may lack a
+     * USING clause).
      */
     rehydrateCatalog(db: Database): Promise<RehydrationResult>;
+    /**
+     * Consume the clean-shutdown marker, deleting it in the same breath (single-use).
+     *
+     * Returns `{ trusted, staleAtClose }`:
+     * - `trusted` — the marker was present AND its payload parsed as a string array.
+     *   Absence (a fresh store, a crash, or a prior rehydrate without an intervening
+     *   {@link closeAll}) yields `false`, so every adopt this session falls back to
+     *   refill.
+     * - `staleAtClose` — the qualified lowercased `schema.mv` names that were
+     *   stale-at-close (written by {@link closeAll}); those MVs refill even under trust.
+     *
+     * Conservative parse: any unparseable / wrong-shape payload (including a legacy
+     * bare `'1'`, which parses to a number, not an array) degrades to
+     * `{ trusted: false, staleAtClose: ∅ }` — refill everything — rather than
+     * trust-everything. The marker is deleted regardless of parse outcome.
+     */
+    private consumeCleanShutdownMarker;
     /**
      * Remove DDL from the catalog store when a table is dropped.
      */
     removeTableDDL(schemaName: string, tableName: string): Promise<void>;
+    /**
+     * Persist a plain view's catalog entry (DDL via `generateViewDDL`), keyed by its
+     * reserved view prefix. Compare-write (skip identical) — see
+     * {@link persistObjectCatalogEntryIfChanged}.
+     */
+    saveViewDDL(view: ViewSchema): Promise<void>;
+    /** Remove a plain view's catalog entry (on DROP VIEW). */
+    removeViewDDL(schemaName: string, viewName: string): Promise<void>;
+    /**
+     * Persist a materialized view's catalog entry (DDL via `generateMaintainedTableDDL`
+     * over the maintained table — the unified record), keyed by its reserved MV
+     * prefix. Compare-write (skip identical) — see
+     * {@link persistObjectCatalogEntryIfChanged}.
+     */
+    saveMaterializedViewDDL(mv: MaintainedTableSchema): Promise<void>;
+    /** Remove a materialized view's catalog entry (on DROP MATERIALIZED VIEW). */
+    removeMaterializedViewDDL(schemaName: string, mvName: string): Promise<void>;
+    /**
+     * Compare-write a view/MV catalog entry: write only when the entry is absent or its
+     * DDL differs from `newDDL` (skip identical). Unlike the table path's
+     * {@link persistCatalogIfChanged} there is **no** absent→skip self-filter — a view/MV
+     * belongs to this db's catalog unconditionally (one module instance serves one
+     * Database). Skipping identical writes makes any event whose regenerated DDL is
+     * unchanged (e.g. a `materialized_view_refreshed`) a no-op, so a second consecutive
+     * reopen yields identical catalog bytes. (Rehydration itself fires no view/MV events
+     * at all — `importCatalog` is silent.)
+     */
+    private persistObjectCatalogEntryIfChanged;
     /**
      * Parse module configuration from vtab args.
      */
     private parseConfig;
+    /**
+     * Subscribe (once) to the engine's `SchemaChangeNotifier` so catalog-only
+     * mutations that bypass `module.alterTable` — notably `ALTER … SET TAGS` and the
+     * programmatic `setTableTags`/`setColumnTags`/`setConstraintTags` — still re-persist
+     * the table's catalog DDL. Called lazily from the first `create`/`connect`/
+     * `alterTable` hook that hands us a `db`.
+     *
+     * One `StoreModule` instance is assumed to serve one `Database`. A later hook
+     * carrying a *different* `db` keeps the existing subscription (multi-database
+     * sharing of a single module instance is out of scope) and logs.
+     */
+    private ensureSchemaSubscription;
+    /**
+     * Engine schema-change listener. Persists the catalog incrementally for the events
+     * that bypass `module.alterTable` / `module.destroy`:
+     *
+     * - `table_modified` — every catalog-only tag swap (and the redundant follow-up a
+     *   structural ALTER fires). Keeps a connected `StoreTable`'s cached schema consistent
+     *   (SET TAGS does not call `updateSchema`) then read-compare-writes the table bundle.
+     * - `view_added` / `view_modified` / `view_removed` — plain `CREATE`/`ALTER … SET TAGS`/
+     *   `DROP VIEW` (the engine fires these from the runtime emitters).
+     * - `materialized_view_added` / `_modified` / `_refreshed` / `_removed` — MV lifecycle.
+     *   Like `table_modified`, the `_added`/`_modified`/`_refreshed` arms also synchronously
+     *   refresh the connected `StoreTable`'s cached schema so a tag change (e.g.
+     *   `quereus.sync.replicate`) takes effect immediately without reopen.
+     *
+     * Unlike the table path there is **no** catalog-absent self-filter for view/MV
+     * add/remove: one `StoreModule` instance serves one `Database`, so that database's
+     * views/MVs belong in its catalog unconditionally. A MEMORY-hosted maintained table
+     * fires `table_added`/`table_removed`/`table_modified` like any table; those stay
+     * ignored (`table_added`/`table_removed` fall through; its `table_modified` is
+     * catalog-absent → skipped), so only the MV entry persists for it. A STORE-hosted
+     * maintained table additionally persists its own table bundle through the ordinary
+     * store-table machinery (which phase-1 rehydrate connects for the adopt fast path).
+     *
+     * Synchronous by contract (`notifyChange` does not await listeners); every async write
+     * rides `persistQueue`, drained by `closeAll`/`whenCatalogPersisted`.
+     *
+     * After dispatching the event's own catalog persistence, the listener recomputes the
+     * durable stale-MV set and compare-writes it (see {@link persistStaleMvSetIfChanged}).
+     * Because the engine's MV manager subscribes to the same notifier in the `Database`
+     * constructor — before this lazy subscription — its listener runs first, so the
+     * `derivation.stale` flags are already current when this recompute reads them.
+     */
+    private onEngineSchemaChange;
+    /** Dispatch a single engine schema-change event to its catalog-persistence arm. */
+    private dispatchSchemaChange;
+    /**
+     * The qualified lowercased `schema.mv` names of every maintained table currently
+     * marked `derivation.stale` — an MV whose row-time maintenance detached mid-session
+     * (a body-relevant `table_modified`/`table_removed` on a source, or a cascade
+     * backing-invalidation), so its durable backing may be behind. The single source of
+     * truth for both the clean-shutdown marker payload and the durable stale-MV set.
+     *
+     * No subscribed db ⇒ the empty set: every path that can mark an MV stale requires a
+     * session in which this module observed the db (a store source create/connect or
+     * `rehydrateCatalog`, both of which subscribe), so a session without `subscribedDb`
+     * never detached any persisted MV's maintenance. Memory-backed MVs that appear here
+     * are harmless — their catalog entries always refill (no phase-1 pre-existing
+     * backing), so withholding trust from them is a no-op.
+     */
+    private computeStaleMvSet;
+    /**
+     * Recompute the durable stale-MV set and, only when it differs from the last value
+     * enqueued this subscription ({@link lastPersistedStaleMvs}), enqueue a `sync: true`
+     * point-write of it onto {@link persistQueue}. The compare-skip keeps an unrelated
+     * `table_modified` (a tag swap that changes no MV's staleness) from costing an fsync.
+     *
+     * The recompute reads `derivation.stale` synchronously (the flags are current at
+     * listener-dispatch time); the field is updated synchronously at enqueue time, and
+     * `persistQueue` serializes the writes in order, so the field always names the last
+     * enqueued value. Riding `persistQueue` (rather than a bare `put`) also serializes
+     * this `sync` behind the triggering event's own source-DDL compare-write, so the
+     * stale-set becomes durable no-later-than the source DDL that caused the staleness —
+     * the ordering the adopt soundness argument depends on.
+     */
+    private persistStaleMvSetIfChanged;
+    /**
+     * Write the durable stale-MV set (`\x00meta\x00stale_mvs`) with `sync: true`. Unlike
+     * the clean-shutdown marker this entry is persistent current-truth — overwritten as
+     * staleness changes, never deleted — so a crash leaves the last synced value intact.
+     * The `sync` mirrors the marker-consume delete's durability discipline (and carries
+     * the same documented backend caveat: a backend without a durability knob no-ops it).
+     */
+    private writeDurableStaleMvSet;
+    /**
+     * Read + conservative-parse the durable stale-MV set, mirroring
+     * {@link consumeCleanShutdownMarker}'s parse discipline (but READ-only — never
+     * deleted). Returns:
+     * - `{ present: false }` — no entry on disk (a pre-atomic store, or an upgrade where
+     *   the capability was gained but no stale-set has been written yet) → the caller
+     *   falls back to the clean-shutdown marker path.
+     * - `{ present: true, stale }` — the parsed set of qualified `schema.mv` names.
+     * - `{ present: true, stale: null }` — a present but unparseable / wrong-shape payload
+     *   → the caller refills everything (the always-safe posture).
+     */
+    private readDurableStaleMvSet;
+    /**
+     * Shared MV add/modify/refresh handling. Narrow defensively — a derivation-less
+     * payload would be an engine bug, so skip. Otherwise, mirror `table_modified`:
+     * synchronously refresh a connected `StoreTable`'s cached schema (so a tag change
+     * such as `quereus.sync.replicate` takes effect immediately without reopen) before
+     * enqueuing the catalog DDL persist.
+     */
+    private refreshConnectedMaterializedView;
+    /**
+     * Append a catalog-persistence task to the serialized `persistQueue`, so successive
+     * mutations (e.g. SET TAGS (a=1) then SET TAGS ()) apply in order and are drained by
+     * `closeAll`/`whenCatalogPersisted` before the provider closes. Errors are
+     * swallowed+logged to mirror `notifyChange`'s own try/catch contract — a listener
+     * rejection must never escape.
+     */
+    private enqueuePersist;
+    /**
+     * Read-compare-write the catalog DDL for a table that just fired `table_modified`.
+     *
+     * - **Absent** catalog entry → the table is not store-backed in this catalog (a
+     *   memory table in the same `db`, or a store table never persisted) → skip. This
+     *   self-filters foreign-module tables without relying on `vtabModule` identity
+     *   (which points at the isolation wrapper when wrapped).
+     * - **Present** but identical DDL → skip (no redundant write). This is what makes a
+     *   structural ALTER — whose own `alterTable` already wrote the final DDL, then fires
+     *   `table_modified` with that same final schema — a no-op here (no double-write).
+     * - **Present** and different DDL → re-persist (the tag swap; or a beneficial
+     *   propagated rewrite of a dependent store table).
+     */
+    private persistCatalogIfChanged;
+    /**
+     * Resolve once all catalog writes queued by async schema-change listeners
+     * (catalog-only tag swaps) have settled. A durability barrier: `closeAll` awaits
+     * it internally; callers/tests that need the persisted catalog current without a
+     * full close can await it directly. Never rejects — queued errors are logged in
+     * the chain.
+     */
+    whenCatalogPersisted(): Promise<void>;
     /**
      * Close all stores.
      */