@quereus/store 4.5.0 → 4.7.0

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

@@ -11,57 +11,30 @@
  *   - Index stores: {schema}.{table}_idx_{name} - one per secondary index
  *   - {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, Schema, MappingAdvertisement, ViewSchema, MaintainedTableSchema, BackingHost, LensDeploymentSnapshot, CatalogObjectKind } from '@quereus/quereus';
-import type { EffectiveRowSource } 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[];
-}
-/**
- * An error encountered while rehydrating a single DDL entry.
- */
-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.
+ * The class is layered across eight files, each adding one job to the one below:
+ *   `store-module-base.ts`         - module state, store handles, coordinator, name collisions
+ *   `store-module-catalog.ts`      - the catalog store: DDL entries, shutdown marker, stale-MV set
+ *   `store-module-schema-sync.ts`  - rehydration, lazy reconnect, engine schema-change subscription
+ *   `store-module-index.ts`        - CREATE / DROP INDEX and the implicit `_uc_*` store reconcile
+ *   `store-module-alter-column.ts` - ALTER TABLE ... ALTER COLUMN
+ *   `store-module-alter.ts`        - ALTER TABLE dispatch and every other arm
+ *   `store-module-rename.ts`       - ALTER TABLE ... RENAME TO (two-phase)
+ *   `store-module.ts`              - this file: module lifecycle, capabilities, backing host
+ *
+ * Three groups read no module state and are free functions instead of layers:
+ *   `store-module-access-plan.ts`    - which access path this module advertises
+ *   `store-module-index-build.ts`    - index population + UNIQUE validation over a row stream
+ *   `store-module-schema-rewrite.ts` - pure schema-to-schema rewrites around DDL
+ *
+ * A layer may call downward, never upward. Nothing enforces that explicitly — it holds
+ * because a base class cannot name a subclass member, so an upward call fails to compile.
  */
-export interface StoreModuleConfig extends BaseModuleConfig {
-    /** Collation for text keys. Default: 'NOCASE'. */
-    collation?: 'BINARY' | 'NOCASE';
-    /**
-     * Serialized-byte budget for a single index-build write batch (see
-     * {@link StoreModule.buildIndexEntries}). Set from the `max_batch_bytes`
-     * module arg; a missing / non-positive value falls back to
-     * {@link DEFAULT_MAX_BATCH_BYTES}. Module-wide, not per-index.
-     */
-    maxBatchBytes?: number;
-    /** Additional platform-specific options. */
-    [key: string]: unknown;
-}
+import type { BackingHost, BestAccessPlanRequest, BestAccessPlanResult, Database, LensDeploymentSnapshot, MappingAdvertisement, ModuleCapabilities, Schema, TableSchema, VirtualTableModule } from '@quereus/quereus';
+import { StoreTable } from './store-table.js';
+import type { StoreTableModule } from './store-table-base.js';
+import { StoreModuleRename } from './store-module-rename.js';
+import type { LensDeploymentListener, StoreModuleConfig } from './store-module-base.js';
 /**
  * Generic store module that works with any KVStoreProvider.
  *
@@ -75,62 +48,7 @@ export interface StoreModuleConfig extends BaseModuleConfig {
  * db.registerModule('store', module);
  * ```
  */
-export declare class StoreModule implements VirtualTableModule<StoreTable, StoreModuleConfig>, StoreTableModule {
-    private provider;
-    private stores;
-    /**
-     * 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);
+export declare class StoreModule extends StoreModuleRename implements VirtualTableModule<StoreTable, StoreModuleConfig>, StoreTableModule {
     /**
      * Returns capability flags for this module.
      *
@@ -169,7 +87,7 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * 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)
+     * `StoreModuleSchemaSync.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
@@ -181,7 +99,7 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
     /**
      * 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
+     * `StoreModuleSchemaSync.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
@@ -203,16 +121,27 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * 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 `onRegister` hook: subscribe to the database's schema-change notifier the
+     * moment this module is registered, before any statement can run.
+     *
+     * Views and materialized views never route through a module table hook, so without
+     * this the module would only learn its `Database` from the first
+     * `create`/`connect`/`alterTable`/`rehydrateCatalog` — and a `create view` issued
+     * before that (the first statement of a brand-new database, say) would fire
+     * `view_added` at a module that is not listening yet and silently never persist.
+     *
+     * Idempotent with the lazy call sites; a second `Database` logs
+     * `ensureSchemaSubscription`'s "different Database" warning here rather than at first
+     * table use (a warning, not a throw — one module instance still serves one Database).
+     */
+    onRegister(db: Database, _moduleName: string): void;
     /**
      * Engine `notifyLensDeployment` hook: a logical `apply schema X` fires this on
      * every registered module once the lens catalog mutation + snapshot rotation
@@ -227,60 +156,6 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * 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.
@@ -334,330 +209,6 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * 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.
-     *
-     * `rows` — an {@link EffectiveRowSource} supplied by a wrapper module (the isolation
-     * layer) — replaces this module's own rows as the set the UNIQUE duplicate check judges.
-     * When present the check runs UP FRONT, before `getIndexStore` opens the index-store
-     * directory, so a rejection leaves no directory behind; and `buildIndexEntries` then
-     * populates the physical index from this module's own (committed) rows with its in-pass
-     * dup check disabled. Those two row sets legitimately differ — the wrapper's transaction
-     * may have deleted a committed duplicate — and an index entry with no live row behind it
-     * is harmless (see the entry-resolution note in `buildIndexEntries`).
-     */
-    createIndex(db: Database, schemaName: string, tableName: string, indexSchema: TableIndexSchema, rows?: EffectiveRowSource): Promise<void>;
-    /**
-     * Drops an index on a store-backed table.
-     *
-     * Mirrors createIndex: refreshes the connected StoreTable's cached
-     * tableSchema (removing the index entry and any UNIQUE constraint
-     * 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>;
-    /**
-     * Build index entries for all existing rows in a table.
-     *
-     * `dataEntries` is the row stream to index. Callers choose its visibility:
-     * `createIndex` passes the table's EFFECTIVE stream (committed + pending, so
-     * an open transaction's rows are indexed too), while `rebuildSecondaryIndexes`
-     * passes the raw committed stream — it runs immediately after an ALTER has
-     * re-encoded the data store in place, and any pending ops still address the
-     * pre-ALTER key bytes.
-     *
-     * For UNIQUE indexes, performs an in-pass duplicate check (honoring partial
-     * predicates and SQL NULL semantics: multiple NULLs are allowed) and throws
-     * CONSTRAINT before any entries are written. Mirrors the memory module's
-     * populateNewIndex so `CREATE UNIQUE INDEX` over duplicated data fails
-     * atomically. `skipDuplicateCheck` suppresses it: `createIndex` sets it when a
-     * wrapper module supplied the rows to judge, having already validated them (see
-     * {@link validateUniqueIndexOverRows}). Judging `dataEntries` too would reject a
-     * committed duplicate the wrapper's transaction has already deleted.
-     *
-     * `normalizers` MUST be the owning connection's `db.getKeyNormalizerResolver()` —
-     * the same resolver `StoreTable.encodeOptions` carries. A rebuild that resolved
-     * collations any other way would re-encode the PK suffix under different bytes than
-     * the table writes at maintenance time, silently corrupting the index.
-     */
-    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}). `normalizers` is the owning
-     * connection's `db.getKeyNormalizerResolver()` — see {@link buildIndexEntries}.
-     *
-     * NOTE: reads the data store committed-only and writes the index stores outside the
-     * coordinator. Sound only because every caller calls {@link ddlCommitPendingOps}
-     * first, so this module's "committed" is "everything live". A caller that skips that
-     * flush would rebuild an index missing its transaction's pending rows.
-     *
-     * `skipDuplicateCheck` suppresses {@link buildIndexEntries}' in-pass UNIQUE check.
-     * The value-rewriting / key-transform ALTER COLUMN arm sets it: its pre-mutation
-     * UNIQUE re-validation already judged the ISSUING connection's effective rows (a
-     * wrapper's overlay included), and this rebuild sees only THIS module's committed
-     * rows — a superset that may retain a row the wrapper's transaction has deleted, so
-     * judging it here would spuriously reject a duplicate pair the probe correctly
-     * accepted. Mirrors the memory module's deliberately non-enforcing base rebuild
-     * (the probe is the only guard).
-     */
-    private rebuildSecondaryIndexes;
-    /**
-     * Validates `rows` 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.
-     *
-     * `rows` MUST be the rows the DDL-issuing connection can SEE. Ordinarily that is this
-     * table's EFFECTIVE stream (committed rows merged with the open transaction's own
-     * pending puts/deletes — `StoreTable.iterateEffectiveEntries`, adapted by
-     * {@link rowsFromEntries}); when a wrapper module holds the pending rows outside this
-     * module it hands them down as an `EffectiveRowSource` instead. Either way, a
-     * committed-only stream would let a duplicate inserted earlier in the same transaction
-     * slip past validation and land in the table once the transaction commits.
-     *
-     * No index store is written — store UNIQUE enforcement is a full-scan over
-     * `uniqueConstraints` at write time. The signature is built by
-     * {@link dedupeRowSignature} with one normalizer per constrained column, resolved from
-     * `tableSchema.columns[idx].collation` through the connection's
-     * `db.getKeyNormalizerResolver()`, so a per-column collation registered with
-     * `db.registerCollation` is honored (matching write-time `compareSqlValues`
-     * enforcement). A comparator-only collation raises: rows that cannot be bucketed
-     * cannot be deduped. Columns whose declared type can never hold text take the
-     * identity normalizer and so never raise.
-     */
-    private validateUniqueOverExistingRows;
-    /**
-     * Index-shaped twin of {@link validateUniqueOverExistingRows}, used by
-     * {@link createIndex} when a wrapper module supplies the rows to judge. Dedupes on the
-     * index's own columns under the index column's COLLATE (falling back to the table
-     * column's), so it enforces exactly what `buildIndexEntries`' suppressed in-pass check
-     * would have — over the wrapper's rows instead of this module's committed ones.
-     */
-    private validateUniqueIndexOverRows;
-    /**
-     * Flush the module's buffered writes before a DDL operation that physically
-     * rewrites or relocates storage.
-     *
-     * Such a DDL cannot honor the coordinator's buffer: pending ops are
-     * `(keyBytes, valueBytes, store)` triples computed at DML time under the
-     * PRE-DDL schema, and every physical rewrite (`StoreTable.rekeyRows` /
-     * `migrateRows`, the provider's directory move) reads and writes the COMMITTED
-     * store directly. Replaying stale-schema ops over the rewritten store on the
-     * eventual commit corrupts, loses, or misfiles those rows. So an `ALTER TABLE`
-     * that touches storage is effectively DDL-committing on a store-backed table:
-     * flush NOW, before the first physical read, so the rewrite sees every live row
-     * and there is nothing left to replay afterwards.
-     *
-     * Consequences, both deliberate:
-     * - The coordinator is module-wide, so this commits the WHOLE module
-     *   transaction — every table's pending ops, not just the altered/renamed
-     *   table's — in one all-or-nothing batch. An ALTER cannot half-commit some
-     *   sibling tables.
-     * - Validation running AFTER this point (e.g. `rekeyRows`' duplicate-key pass,
-     *   which must see pending rows because a pending insert can itself be the
-     *   duplicate) throws with the enclosing transaction already flushed. The store
-     *   stays unmutated — only the transaction is gone. Validation that does NOT
-     *   need pending rows belongs before the call, so the transaction survives it.
-     *
-     * Subsequent `commit()` calls on the same coordinator are no-ops
-     * (`inTransaction` is cleared), which keeps the enclosing transaction safe.
-     * The savepoint stack is cleared too, so a later `ROLLBACK TO` / `RELEASE` that
-     * the engine still broadcasts warns and degrades rather than throwing — see
-     * `TransactionCoordinator.rollbackToSavepoint`, which mirrors the memory
-     * module's identical posture.
-     */
-    private ddlCommitPendingOps;
-    /**
-     * Alters an existing store table's structure. Resolves the table, captures the
-     * pre-alter schema, and dispatches to the per-change-type `alter*` helper below;
-     * the helper does the arm's work (row migration, physical re-key, constraint
-     * validation, DDL persist) and returns the updated TableSchema for the engine to
-     * register. The shared preamble (schema subscription, reconnect, not-found throw,
-     * `defaultNotNull`) lives here so every arm sees the same resolved state.
-     */
-    alterTable(db: Database, schemaName: string, tableName: string, change: SchemaChangeInfo, rows?: EffectiveRowSource): Promise<TableSchema>;
-    /**
-     * Build / tear down the physical index stores backing implicit UNIQUE indexes
-     * (`_uc_*`) after an ALTER, by diffing the implicit-index NAMES of the old vs new
-     * constraint sets:
-     *   - a name newly PRESENT (ADD CONSTRAINT UNIQUE, or the target half of a
-     *     RENAME CONSTRAINT / rename of an unnamed UC's column) has its physical store
-     *     populated from this module's effective rows;
-     *   - a name newly ABSENT (DROP CONSTRAINT UNIQUE, or the source half of a rename)
-     *     has its store torn down, so a later re-ADD does not reopen stale entries.
-     *
-     * The SCHEMA entry itself is materialized/removed by `withImplicitUniqueIndexes`
-     * on the arm's `table.updateSchema`; only the physical store needs this. Runs after
-     * every ALTER but is a no-op whenever the implicit-index name set is unchanged
-     * (incl. PK / collation / data-type ALTERs, whose same-name physical re-encode is
-     * already done by {@link rebuildSecondaryIndexes}).
-     *
-     * `oldSchema` carries the pre-ALTER `uniqueConstraints` (its `.indexes` may be
-     * de-materialized — the diff reads `uniqueConstraints`, not `.indexes`).
-     *
-     * NOTE: the build populates from THIS module's own effective rows (committed + this
-     * transaction's pending), never a wrapper's — mirroring `createIndex`. Under the
-     * isolation layer the wrapper's rows are what ADD CONSTRAINT's validation judged;
-     * the physical index legitimately fills from this module's committed rows and an
-     * entry with no live row behind it is harmless (both readers resolve to the live
-     * row). Duplicates were already rejected by `validateUniqueOverExistingRows` (ADD)
-     * or cannot exist (RENAME leaves data unchanged), so the in-pass check is skipped.
-     */
-    private reconcileImplicitUniqueIndexStores;
-    /**
-     * The physical index-store names a table owns for DROP / RENAME TABLE to relocate
-     * or reclaim: the MATERIALIZED index set — every explicit `CREATE INDEX` PLUS the
-     * hidden `_uc_*` realizing each plain UNIQUE. Reading only `getSchema().indexes`
-     * (the engine-facing schema, which carries no `_uc_*`) would strand a `_uc_*` store
-     * on disk after DROP TABLE, and — worse — after RENAME TABLE leave the renamed
-     * table seeking a freshly-created EMPTY `_uc_*` store, silently accepting a
-     * duplicate of a pre-rename row. Prefers the cached StoreTable's own materialized
-     * schema; falls back to materializing the schema-manager copy when the instance is
-     * already gone.
-     */
-    private materializedIndexNames;
-    /** Close + delete the physical store of an implicit UNIQUE index. Mirrors `dropIndex`. */
-    private tearDownImplicitUniqueIndexStore;
-    /**
-     * ADD COLUMN arm of {@link alterTable}: append the new column, eagerly migrate
-     * each row (literal or per-row backfill), and persist. Behavior-preserving
-     * extraction of the former `switch` arm.
-     *
-     * The store always appends. A caller-chosen `insertAtIndex` (module-API only; SQL never
-     * produces one) is rejected unless it names the append position, rather than silently
-     * landing the column somewhere the caller did not ask for.
-     */
-    private alterAddColumn;
-    /** DROP COLUMN arm of {@link alterTable}: drop the column slot, reindex PK / indexes /
-     *  UNIQUE, migrate rows, and persist. Behavior-preserving extraction. */
-    private alterDropColumn;
-    /** RENAME COLUMN arm of {@link alterTable}: schema-only rewrite (columns, indexes, self-FK,
-     *  in-place predicate / CHECK AST rewrite) and persist. Behavior-preserving extraction. */
-    private alterRenameColumn;
-    /** ALTER PRIMARY KEY arm of {@link alterTable}: physically re-key the data store, rebuild
-     *  secondary indexes, and persist. Behavior-preserving extraction. */
-    private alterPrimaryKeyChange;
-    /** ADD CONSTRAINT arm of {@link alterTable}: validate existing rows as the constraint kind
-     *  (UNIQUE / FOREIGN KEY / CHECK) requires, then persist. Behavior-preserving extraction. */
-    private alterAddConstraint;
-    /** DROP CONSTRAINT arm of {@link alterTable}: schema-only catalog rewrite dropping a named
-     *  constraint, then persist. Behavior-preserving extraction. */
-    private alterDropConstraint;
-    /** RENAME CONSTRAINT arm of {@link alterTable}: schema-only rename of a named constraint,
-     *  then persist. A renamed named-UNIQUE changes its implicit `_uc_*` index name, so
-     *  `reconcileImplicitUniqueIndexStores` (run after this arm) MOVES the physical store —
-     *  tears down the old-named store and rebuilds the new-named one from effective rows. */
-    private alterRenameConstraint;
-    /** ALTER COLUMN arm of {@link alterTable}: change one attribute (NOT NULL / data type /
-     *  default / collation), running the physical re-key + existing-row re-validation the
-     *  collation / PK paths require, then persist. Behavior-preserving extraction. */
-    private alterColumnChange;
-    /**
-     * SET NOT NULL / DROP NOT NULL sub-branch of {@link alterColumnChange}. Returns the
-     * new column schema, or null when the column is already in the desired nullability
-     * (the pre-refactor `return oldSchema` no-op). Mutates nothing: the NULL-backfill
-     * probe is throw-only, and the backfill itself is returned as a deferred
-     * `valueConvert` (null → DEFAULT) the caller applies only after every throw-only
-     * check — including the UNIQUE re-validation over the backfilled values — has passed.
-     *
-     * `rows` is the wrapper-supplied effective row source (the isolation overlay). When present,
-     * the reject-vs-backfill decision scans it instead of `table.rowsWithNullAtIndex`: behind the
-     * isolation layer the issuer's pending inserts live in the wrapper's overlay, not this store,
-     * so the store's own count would miss them and wrongly accept the ALTER. The committed-store
-     * `mapRowsAtIndex` backfill is unchanged — the overlay-resident pending rows are the isolation
-     * layer's job (its overlay migration), this store only owns its committed rows.
-     */
-    private alterColumnSetNotNull;
-    /**
-     * SET DATA TYPE sub-branch of {@link alterColumnChange}. Returns the retyped column
-     * schema. Mutates nothing: for every retype between DIFFERENT logical types, a
-     * throw-only convert pass over the live rows proves every value convertible, and the
-     * conversion itself is returned as a deferred `valueConvert` the caller applies only
-     * after every throw-only check — including the UNIQUE re-validation over the converted
-     * values — has passed. Gated on logical-type IDENTITY, not the physical storage class:
-     * `inferType` flattens aliases to the shared type object (`varchar(50)` IS `TEXT_TYPE`),
-     * so an alias retype is schema-only, while a same-class retype (text → date) still
-     * rejects values the new type refuses and rewrites the rest to the new type's
-     * canonical spelling ('2024-06-05T00:00:00Z' → '2024-06-05') — exactly as an INSERT
-     * would have stored them.
-     *
-     * A retype of a PRIMARY KEY member is refused here rather than converted: the rewrite
-     * below is `mapRowsAtIndex`, a payload-only rewrite that reuses `entry.key` verbatim, so
-     * a PK column's physical key bytes would stay encoded under the OLD type while the value
-     * moves to the new one — unfindable by any lookup under the new encoding, and the same
-     * `keyTransformChanged` path in the caller would re-key from the pre-rewrite values before
-     * this rewrite ever ran (see the NOTE above the `valueConvert` block in
-     * {@link alterColumnChange}). Every live SQL caller already refuses this earlier (the
-     * engine's `runAlterColumn` and the materialized-view reshape's inexpressibility check),
-     * so this only guards a direct module call — mirrors the memory backend's carve-out
-     * (`MemoryTableManager.alterColumn`).
-     */
-    private alterColumnSetDataType;
-    /**
-     * SET COLLATE sub-branch of {@link alterColumnChange}. Returns the recollated column
-     * schema with `collationChanged` set when the collation bytes actually change (a bare
-     * metadata flip keeps it false), or null when the column is already explicit in the
-     * desired collation (the pre-refactor `return oldSchema` no-op). Synchronous — no
-     * row scan happens here; the caller runs the re-validation / re-key the flag gates.
-     */
-    private alterColumnSetCollation;
-    /**
-     * Rename a store-backed table.
-     *
-     * Drops every in-memory reference to the old name (so the coordinator, open
-     * handles, and cached StoreTable instance don't linger with stale paths),
-     * delegates physical storage relocation to the provider, then rewrites the
-     * persistent catalog DDL under the new key. After this returns, the next
-     * access to `newName` will reconnect via `connect()` and open fresh stores
-     * against the moved directories.
-     */
-    renameTable(db: Database, schemaName: string, oldName: string, newName: string): Promise<void>;
-    /**
-     * Second phase of a two-phase RENAME TABLE (see {@link renameTable}). The engine calls
-     * this at the END of ALTER TABLE ... RENAME TO — AFTER its `propagateTableRename` has
-     * rewritten every dependent object that named `oldName` and enqueued their corrective
-     * catalog writes onto {@link persistQueue}. `renameTable` deliberately left `oldName`'s
-     * catalog entry in place; here we drain those dependent writes to durability and only
-     * THEN drop the old entry. During the window both entries coexist on disk, so every
-     * dependent resolves against one of them and every intermediate catalog set rehydrates
-     * into a working database.
-     *
-     * The old-entry delete rides `persistQueue` behind the dependents' already-enqueued
-     * writes (FIFO), so it can only run after them, and the drain below awaits the whole
-     * chain. Errors are swallowed+logged (the {@link enqueuePersist} contract): a failed
-     * delete leaves the old entry present — a visible, droppable orphan, strictly safer
-     * than a dependent stranded against a vanished table.
-     *
-     * NOTE: full cross-table atomicity — bundling this old-entry delete together with every
-     * dependent rewrite into one `provider.beginAtomicBatch` commit — would eliminate even
-     * the transient two-entry window (and the physical-move orphan `renameTableStores`
-     * leaves), but only on atomic providers, and the dependent set is known only to the
-     * engine post-propagate. That is the atomic-provider hardening path; out of scope here.
-     */
-    finalizeRename(_db: Database, schemaName: string, oldName: string, _newName: string): Promise<void>;
     /**
      * Modern access planning interface.
      *
@@ -679,431 +230,14 @@ export declare class StoreModule implements VirtualTableModule<StoreTable, Store
      * ORDER-PRESERVING — byte order and comparator order must coincide, or the seek would
      * under-fetch and the ordering advertisement would elide a Sort it must not. That gate
      * needs the connection's collation registry, hence `db` is threaded down.
-     */
-    getBestAccessPlan(db: Database, tableInfo: TableSchema, request: BestAccessPlanRequest): BestAccessPlanResult;
-    private computeBestAccessPlan;
-    /**
-     * Build the access plan for one secondary index against `request`, or null when
-     * the index is not usable for this predicate.
-     *
-     * Usable = a contiguous leading-prefix EQ on the index columns (an index seek /
-     * point), or a LT/LE/GT/GE range on the LEADING index column. These mirror the
-     * two windows {@link StoreTable.analyzeIndexAccess} can build.
-     *
-     * **Collation-safety guard against under-fetch.** The store's index-column
-     * window is encoded under the table key collation K, but `matchesFilters`
-     * compares under the COLUMN's declared collation. Marking a filter handled drops
-     * the residual Filter, so the K-window must be a guaranteed SUPERSET of the
-     * qualifying rows. That holds only when K is coarser-or-equal to the column's
-     * declared collation. To stay provably safe with minimal logic we mark the
-     * covered filters handled — setting `indexName` + `seekColumns` — only when every
-     * seek column is non-text, OR its declared collation equals K, OR (K = NOCASE
-     * while the column is BINARY, i.e. K strictly coarser). Otherwise we return a
-     * cost-only plan (cheaper cost, filters unhandled, residual retained — correct,
-     * just not sped up). K itself always keys: `StoreTable`'s constructor rejects a
-     * table whose key encoding would need a collation it cannot resolve to a normalizer.
-     *
-     * NOTE: the coarser-K relaxation is sound for EQUALITY only. A RANGE window equates
-     * memcmp of K-normalized bytes with C's comparator order, which a merely coarser K does
-     * not give — under K = NOCASE and C = BINARY, 'K' (U+212A) is `> 'z'` yet keys as 'k',
-     * before 'z'. So the range arm demands `C === K` *and* K's `orderPreserving` assertion,
-     * via the shared {@link keyOrderMatchesCollation}; `StoreTable.analyzeIndexAccess`
-     * declines the same windows, so the two decisions cannot disagree. The cost is that a
-     * default-K (NOCASE) table with an index on a plain BINARY text column loses its index
-     * RANGE seek and falls back to the cost-only plan; EQ seeks are unchanged.
-     */
-    private tryIndexAccessPlan;
-    /**
-     * Compute the PK-ordering advertisement for a scan-style plan. Returns the
-     * `providesOrdering` / `monotonicOn` / `supportsAsofRight` fields for a plan
-     * whose iteration is driven by the primary-key key order (full scan or PK
-     * range scan).
-     *
-     * `providesOrdering` is set only when it actually matches what the caller
-     * needs:
-     *   - When the request carries `requiredOrdering`, claim it only if the
-     *     requested keys form a prefix of the PK with matching directions.
-     *     Claiming PK order against an `ORDER BY <other column>` would cause
-     *     the absorb-Sort rule to drop the Sort and yield wrong-order rows.
-     *   - When no `requiredOrdering` is present, advertise the full PK
-     *     ordering so downstream rules (merge-join, sort elision after a
-     *     filter) can opportunistically use it.
-     *
-     * `monotonicOn` reflects the access path itself and is independent of any
-     * `requiredOrdering`; it always advertises the leading PK column. Strict
-     * monotonicity is claimed iff the PK is single-column — composite PKs can
-     * repeat values on the leading column.
-     *
-     * Returns an empty object when there is no PK (heap-only table) — without a
-     * leading key column there is no natural emit order.
-     *
-     * Every claim here is about the PHYSICAL key-byte order the store iterates in, but the
-     * consumers of `providesOrdering` / `monotonicOn` reason in the columns' COLLATION order.
-     * `orderPreservingPrefix` (from {@link pkOrderPreservingPrefixLength}) is how many leading
-     * PK members those two orders provably agree on: the advertisement is truncated to that
-     * prefix, and voided entirely when even the leading member disagrees — otherwise the
-     * absorb-Sort rule would elide a Sort and hand the caller byte-ordered rows.
-     */
-    private buildPkOrderingAdvertisement;
-    /**
-     * Get or create a data store for a table.
-     */
-    getStore(schemaName: string, tableName: string, _config: StoreTableConfig): Promise<KVStore>;
-    /**
-     * Get or create an index store for a table.
-     */
-    getIndexStore(schemaName: string, tableName: string, indexName: string): Promise<KVStore>;
-    /**
-     * Get or create a stats store for a table.
-     */
-    getStatsStore(schemaName: string, tableName: string): Promise<KVStore>;
-    /**
-     * 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.
-     */
-    private buildCatalogEntry;
-    /**
-     * Encode a bundle of persisted schema text (DDL) for the catalog store.
-     * The guard is {@link assertPersistableDdlText} — see it for why the FULL text
-     * is checked, not just the object's name.
-     */
-    private encodeCatalogDDL;
-    /**
-     * Save table DDL (bundled with its secondary index DDL) to the catalog store.
-     */
-    saveTableDDL(tableSchema: TableSchema): Promise<void>;
-    /**
-     * 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[]>;
-    /**
-     * 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`.
-     *
-     * 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).
-     */
-    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>;
-    /**
-     * Pre-flight veto (see `VirtualTableModule.assertCatalogObjectPersistable`): refuse a
-     * view / materialized view whose catalog entry this module could not durably write.
-     *
-     * It runs exactly the derivation the write path runs — {@link viewCatalogEntry} /
-     * {@link maintainedViewCatalogEntry} build the key (rejecting an unencodable
-     * identifier) and {@link assertPersistableDdlText} checks the generated DDL text —
-     * so the veto and the write cannot disagree about what is persistable. It is the only
-     * synchronous path a rejection can travel: the actual save is chained onto
-     * `persistQueue` behind a `SchemaChangeNotifier` listener, and both layers swallow.
      *
-     * Gated on `subscribedDb === db`: this module persists a view/MV only while subscribed
-     * to that `Database`'s change notifier ({@link ensureSchemaSubscription}, driven by the
-     * first `create`/`connect`/`alterTable`/`rehydrateCatalog`). A module registered but
-     * never handed a `db` writes nothing, so vetoing there would reject a definition that
-     * loses nothing. The gate becomes removable if persistence is ever made unconditional
-     * (`bug-store-untouched-table-and-early-view-never-persisted`).
+     * The request is sized from the table's own maintained row count when the planner
+     * supplied no estimate — see {@link sizeRequestFromLiveCount}.
      */
-    assertCatalogObjectPersistable(db: Database, kind: CatalogObjectKind, object: ViewSchema | TableSchema): 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>;
+    getBestAccessPlan(db: Database, tableInfo: TableSchema, request: BestAccessPlanRequest): BestAccessPlanResult;
     /**
      * Close all stores.
      */
     closeAll(): Promise<void>;
-    /**
-     * Get a table by schema and name.
-     */
-    getTable(schemaName: string, tableName: string): StoreTable | undefined;
 }
 //# sourceMappingURL=store-module.d.ts.map