@quereus/store 4.5.0 → 4.7.0

package/dist/src/common/store-table-base.d.ts

@@ -0,0 +1,539 @@
+/**
+ * State and storage plumbing shared by every layer of the KVStore-backed virtual
+ * table: schema/key-encoding state, store + coordinator handles, statistics,
+ * transaction lifecycle, and the effective-read primitives (committed store
+ * merged with the coordinator's pending ops) the read and write paths build on.
+ *
+ * Base of the store-table layer chain:
+ *   StoreTableBase -> StoreTableScan -> StoreTableConstraints -> StoreTable
+ */
+import { VirtualTable, type Database, type CollationResolver, type TableSchema, type TableIndexSchema, type Row, type SqlValue, type TableStatistics, type VirtualTableConnection } from '@quereus/quereus';
+import type { IterateOptions, KVEntry, KVStore } from './kv-store.js';
+import type { DataChangeEvent, StoreEventEmitter } from './events.js';
+import type { TransactionCoordinator } from './transaction.js';
+import { StoreConnection } from './store-connection.js';
+import { type TableStats } from './serialization.js';
+import { type EncodeOptions, type KeyValueTransform } from './encoding.js';
+/**
+ * Configuration for a store table.
+ */
+export interface StoreTableConfig {
+    /** Collation for text keys. Default: 'NOCASE'. */
+    collation?: 'BINARY' | 'NOCASE';
+    /**
+     * Serialized-byte budget for a single index-build write batch (see
+     * `buildIndexEntries` (store-module-index-build.ts)). Parsed from the `max_batch_bytes` module
+     * arg; undefined falls back to the module default.
+     */
+    maxBatchBytes?: number;
+    /** Additional platform-specific options. */
+    [key: string]: unknown;
+}
+/**
+ * Interface for the store module that manages this table.
+ * Provides access to stores and coordinators.
+ */
+export interface StoreTableModule {
+    /** Get the data store for a table. */
+    getStore(schemaName: string, tableName: string, config: StoreTableConfig): Promise<KVStore>;
+    /** Get an index store for a table. */
+    getIndexStore(schemaName: string, tableName: string, indexName: string): Promise<KVStore>;
+    /** Get the stats store for a table. */
+    getStatsStore(schemaName: string, tableName: string): Promise<KVStore>;
+    /**
+     * Get the module's single shared transaction coordinator (one per storage
+     * module, shared by every table — the unit of cross-table atomicity).
+     * Synchronous: ops are addressed by explicit store handle, so obtaining a
+     * coordinator never requires opening storage.
+     */
+    getCoordinator(): TransactionCoordinator;
+    /** Save table DDL to persistent storage (unconditional put). */
+    saveTableDDL(tableSchema: TableSchema): Promise<void>;
+    /** Write table DDL only when the persisted entry is absent or differs. */
+    persistTableCatalogEntryIfChanged(tableSchema: TableSchema): Promise<void>;
+}
+/**
+ * Storage-facing base of the generic KVStore-backed virtual table.
+ *
+ * Holds the table's schema-derived key encoding state, its data/index/stats
+ * store handles and transaction coordinator, its statistics accounting, and the
+ * effective-row reads every higher layer issues. Platform-specific behavior is
+ * delegated to the {@link StoreTableModule}.
+ *
+ * NOTE: `export` here is required, not intentional API surface — `StoreTable extends`
+ * this class transitively, so TypeScript cannot emit its declaration unless every base
+ * in the chain is nameable (TS4020). The package index deliberately does not re-export
+ * this class or the two layers above it; if an API-surface extractor is ever added, it
+ * should treat them as internal rather than prompt a re-export.
+ */
+export declare abstract class StoreTableBase extends VirtualTable {
+    protected storeModule: StoreTableModule;
+    protected config: StoreTableConfig;
+    protected store: KVStore | null;
+    protected storeInitPromise: Promise<KVStore> | null;
+    protected indexStores: Map<string, KVStore>;
+    protected statsStore: KVStore | null;
+    protected coordinator: TransactionCoordinator | null;
+    /**
+     * Disposer returned by the coordinator's `registerCallbacks`, captured on the
+     * first {@link attachCoordinator}. Run by {@link dispose} at hard eviction to
+     * deregister this instance's {stats apply/discard} pair from the module-wide
+     * coordinator; null until attached, and nulled again after dispose.
+     */
+    private coordinatorDisposer;
+    protected connection: StoreConnection | null;
+    protected eventEmitter?: StoreEventEmitter;
+    protected encodeOptions: EncodeOptions;
+    protected pkDirections: boolean[];
+    /**
+     * Per-PK-column KEY collation (see {@link resolvePkKeyCollations}). Drives the
+     * physical encoding of every data key and the PK suffix of every secondary-index
+     * key, so a text PK column declared BINARY/NOCASE/RTRIM is keyed under its own
+     * collation rather than one fixed table-level collation. Recomputed on every
+     * {@link updateSchema} (an ALTER COLUMN SET COLLATE on a PK member changes it).
+     */
+    protected pkKeyCollations: (string | undefined)[];
+    /**
+     * Per-PK-column key-identity value transform (see {@link resolvePkKeyTransforms}).
+     * Threaded alongside {@link pkKeyCollations} into every data-key / PK-suffix /
+     * PK-prefix-bounds encode, so a semantic-ordering PK member (TIMESPAN) keys
+     * semantically-equal spellings to one physical key. Recomputed on every
+     * {@link updateSchema}.
+     */
+    protected pkKeyTransforms: (KeyValueTransform | undefined)[];
+    /**
+     * Per-PK-column typed EQUALITY comparator for the semantic-ordering members only —
+     * `undefined` for every other member, which `StoreTableConstraints.keysEqual` still compares with
+     * strict `!==` as before. Keeps self-PK exclusion and PK-identity questions in
+     * agreement with the physical key identity above ('PT1H' row IS the 'PT60M' row).
+     */
+    protected pkSemanticEquality: (((a: SqlValue, b: SqlValue) => number) | undefined)[];
+    /**
+     * `db.getCollationResolver()`, bound once at construction. Every collation-aware
+     * VALUE comparison this table makes — pushed-constraint re-check, UNIQUE conflict
+     * detection — resolves names through it, so a collation registered with
+     * `db.registerCollation` on *this* connection is honored rather than silently
+     * degraded to BINARY by the process-global built-in registry.
+     *
+     * Only the resolver closure is cached: it reads the live registry, so a collation
+     * registered after connect is still visible. Resolved *functions* are hoisted no
+     * further than the comparator or constraint check that resolved them.
+     *
+     * Its key-bytes counterpart, `db.getKeyNormalizerResolver()`, is bound into
+     * {@link encodeOptions} so the names in {@link pkKeyCollations} resolve to the same
+     * per-connection registry.
+     */
+    protected readonly collationResolver: CollationResolver;
+    protected ddlSaved: boolean;
+    protected cachedStats: TableStats | null;
+    protected pendingStatsDelta: number;
+    protected mutationCount: number;
+    protected statsFlushPending: boolean;
+    /**
+     * {@link tableSchema} with a hidden `_uc_*` secondary index materialized per
+     * non-derived UNIQUE constraint that no explicit index already covers (see
+     * {@link withImplicitUniqueIndexes}) — the schema that drives UNIQUE ENFORCEMENT
+     * (`StoreTableConstraints.findIndexForUniqueConstraint`) and physical index MAINTENANCE
+     * (`StoreTableConstraints.updateSecondaryIndexes`).
+     *
+     * Deliberately SEPARATE from the engine-facing {@link tableSchema}: the engine
+     * reads `tableInstance.tableSchema` at CREATE (`SchemaManager.finalizeCreatedTableSchema`)
+     * and the read-query planner reads the registered schema, and NEITHER may see
+     * `_uc_*` (mirrors the memory backend keeping its materialized schema
+     * manager-local; a plain UNIQUE gets no read-side plan from `_uc_*`, only
+     * enforcement). Recomputed alongside `tableSchema` in the constructor and
+     * {@link updateSchema}.
+     */
+    protected materializedSchema: TableSchema;
+    constructor(db: Database, storeModule: StoreTableModule, tableSchema: TableSchema, config: StoreTableConfig, eventEmitter?: StoreEventEmitter, isConnected?: boolean);
+    /**
+     * Reject, at DDL time, any collation this table's key encoding would need but cannot
+     * use — before a single row is written under bytes the connection cannot reproduce.
+     *
+     * A collation keys a persisted structure only if it carries a KEY NORMALIZER (the
+     * `(s) => string` whose output equality partitions strings exactly as its comparator
+     * does). `db.registerCollation(name, cmp)` with no `{ normalizer }` gives a collation
+     * that can order rows but not key them; an unregistered name gives nothing at all.
+     * Both raise here rather than at the first insert.
+     *
+     * Checked over exactly the collations the key encoding actually uses:
+     *   - every defined `pkKeyCollations` entry (text-capable PK columns);
+     *   - every defined index key collation of every index in the MATERIALIZED schema
+     *     (`resolveIndexKeyCollations` — the index column's COLLATE, else the table
+     *     column's declared collation, else BINARY; hidden `_uc_*` indexes included).
+     *
+     * Two deliberate consequences of validating the actual index key collations rather
+     * than blanket-requiring the table key collation K whenever any index column is
+     * text-capable (the pre-per-column-index-collation behavior):
+     *   - an index column declaring a comparator-only collation is rejected here instead
+     *     of silently keying under K;
+     *   - a table whose K has no normalizer but whose key encoding never uses K (all
+     *     index columns BINARY/type-native, PK needing no K) is no longer unopenable.
+     *
+     * Blast radius: this also fires on catalog rehydration. Reopening a persisted database
+     * from a connection that has not re-registered its custom collation now throws at
+     * CREATE-TABLE-from-catalog rather than silently reading rows under a key layout it
+     * cannot reproduce. See `docs/plugins.md`.
+     *
+     * Takes `pkKeyCollations` rather than reading the field so `updateSchema` can validate
+     * the incoming schema BEFORE it overwrites its own state with it.
+     */
+    private validateKeyCollations;
+    /**
+     * Throw-only half of {@link validateKeyCollations}: raise unless every name in
+     * `names` resolves to a registered key normalizer.
+     */
+    private assertCollationsCanKey;
+    /**
+     * Throw-only pre-check for `StoreModuleIndex.createIndex`: reject a NEW index whose
+     * key collations cannot key (comparator-only or unregistered), BEFORE the physical
+     * index store is created — so a rejection leaves no store directory behind even for
+     * an empty table (where the build itself would encode nothing and the later
+     * `updateSchema` validation would fire only after the store exists).
+     */
+    assertIndexKeyCollationsCanKey(indexSchema: TableIndexSchema): void;
+    /**
+     * Reject, at DDL time, a key member whose semantic-ordering logical type has no
+     * store key transform — before a single row is keyed under bytes whose order the
+     * type's `compare` (and so the isolation merge, the memory oracle, and Sort)
+     * disagrees with.
+     *
+     * A semantic-ordering type keys soundly only through an order- and
+     * identity-preserving transform ({@link storeSemanticKeyTransform}: the type's
+     * `groupKey`, or a store-local encoder like JSON's structural one). This gap used
+     * to be undetectable — JSON sat here transform-less for a release, keying in
+     * canonical-text order while every comparator ordered structurally, and the only
+     * symptom was a misaligned overlay merge deep inside a transaction. Unreachable
+     * today (TIMESPAN and JSON are both covered); it exists so the NEXT
+     * semantic-ordering type fails loudly at CREATE TABLE instead.
+     *
+     * Checked over the same materialized schema as {@link validateKeyCollations}:
+     * every PK member and every (explicit or hidden `_uc_*`) index column.
+     *
+     * CAVEAT: this can only check that a transform EXISTS — a `groupKey` that is
+     * identity-faithful but not order-preserving passes undetected, so a new type's
+     * transform still needs its byte order argued against its `compare` (see
+     * json-key.ts for the shape of that argument).
+     */
+    private validateSemanticKeyTransforms;
+    /** Get the table configuration. */
+    getConfig(): StoreTableConfig;
+    /** Get the table schema (engine-facing, WITHOUT the hidden `_uc_*` indexes). */
+    getSchema(): TableSchema;
+    /**
+     * Get the enforcement schema — {@link getSchema} plus the hidden `_uc_*`
+     * index materialized per non-derived UNIQUE. Used by the module to resolve the
+     * physical index store to build/tear down during ALTER; never registered with
+     * the engine.
+     */
+    getMaterializedSchema(): TableSchema;
+    /**
+     * Update the table schema after an ALTER TABLE / CREATE INDEX operation.
+     *
+     * Validates the incoming schema's key collations before adopting any of it, so a
+     * rejection leaves this table on its previous, consistent schema.
+     */
+    updateSchema(newSchema: TableSchema): void;
+    /**
+     * Mark the table's DDL as already persisted to the catalog, so the lazy
+     * first-store-access save in {@link initializeStore} is skipped. Called by
+     * `StoreModule.createIndex` / `dropIndex` after they eagerly write the catalog
+     * bundle, so a subsequent INSERT does not redundantly re-persist identical DDL.
+     */
+    markDdlSaved(): void;
+    /** Close and forget a cached index-store handle, if any. */
+    releaseIndexStore(indexName: string): Promise<void>;
+    /**
+     * Returns true if the table has at least one LIVE row — the open transaction's
+     * pending overlay over the committed store. Stops after the first hit.
+     *
+     * Effective (not committed-only) because its one caller, `ADD COLUMN`'s NOT
+     * NULL-without-DEFAULT rejection, must see rows the same transaction inserted:
+     * they are migrated too (the arm DDL-commits before `migrateRows`), and a
+     * committed-only probe would wave them through only to give them a NULL in a
+     * NOT NULL column. Conversely, a pending delete of the last row makes the table
+     * legitimately empty. Reading effectively keeps the check throw-only and
+     * BEFORE the DDL-commit, so a rejection leaves the transaction intact.
+     */
+    hasAnyRows(): Promise<boolean>;
+    /**
+     * Yield the LIVE value of `colIndex` for every row — the open transaction's
+     * pending overlay over the committed store. For throw-only ALTER COLUMN probes
+     * that must run BEFORE the arm's DDL-commit (see `StoreModule.ddlCommitPendingOps`):
+     * they have to see rows this transaction wrote, because those rows are rewritten
+     * too, and a rejection here must leave the transaction intact.
+     */
+    iterateEffectiveValuesAtIndex(colIndex: number): AsyncIterable<SqlValue>;
+    /**
+     * Count the LIVE rows whose column at `colIndex` holds NULL (see
+     * {@link iterateEffectiveValuesAtIndex} for why this reads effectively).
+     * Used by ALTER COLUMN SET NOT NULL to decide whether the tightening is safe.
+     */
+    rowsWithNullAtIndex(colIndex: number): Promise<number>;
+    /**
+     * Ensure the data store is open and DDL is persisted.
+     * Uses a promise-based singleton pattern to prevent race conditions
+     * when multiple concurrent queries access the same table.
+     */
+    protected ensureStore(): Promise<KVStore>;
+    /**
+     * Internal method to actually initialize the store.
+     * Only called once per table instance.
+     */
+    private initializeStore;
+    /**
+     * Get or create an index store for the given index name.
+     */
+    protected ensureIndexStore(indexName: string): Promise<KVStore>;
+    /**
+     * Read the persisted row count into {@link cachedStats} once per table instance,
+     * before any mutation can be tracked against it.
+     *
+     * `trackMutation` / `applyPendingStats` both seed a missing `cachedStats` with
+     * `rowCount: 0` and add their delta to it, so WITHOUT this priming the first write
+     * after a reopen silently restarted the count from zero: a table reopened with 500
+     * persisted rows reported 1 after a single insert, and the next
+     * {@link flushStats} made that durable. Nothing read the count for planning before,
+     * so the loss was invisible; it is not once {@link getKnownRowCount} prices access
+     * plans with it.
+     *
+     * Called from {@link initializeStore}, which every read and write path awaits
+     * before touching storage — so priming precedes the first `trackMutation` without
+     * any caller having to remember it. Costs one extra KV `get` per table per session.
+     *
+     * Statistics are advisory (same posture as `StoreModuleRename`'s stats re-key): a
+     * failure to open or read the stats store warns and leaves the count unknown rather
+     * than failing the storage open that carries the caller's actual query.
+     *
+     * NOTE: on that failure path the pre-fix behaviour returns for this table — the next
+     * `trackMutation` seeds `cachedStats` at 0 and a later {@link flushStats} makes the
+     * restarted count durable, silently discarding the persisted one. Tolerated because a
+     * stats-store read failure is already a storage-level fault and the count is advisory.
+     * If it ever needs to be safe, gate {@link flushStats} on a "primed or genuinely
+     * absent" flag rather than on `cachedStats` being non-null.
+     */
+    private primeStats;
+    /**
+     * Get or create the stats store.
+     */
+    protected ensureStatsStore(): Promise<KVStore>;
+    /**
+     * Resolve + cache the module's shared TransactionCoordinator and hook the
+     * stats lifecycle callbacks, WITHOUT creating or registering a connection.
+     * Synchronous (the coordinator is handle-addressed, never store-opening — see
+     * `StoreTableModule.getCoordinator`), so the backing host's resolution path can
+     * call it eagerly. Attaching matters for reads: `iterateEffective` /
+     * `readEffectiveRowByKey` consult `this.coordinator` for the pending merge, so a
+     * table whose only writer is the privileged backing host (which queues ops on the
+     * module coordinator, never through `update()`) must still hold the
+     * reference for its read paths to be reads-own-writes.
+     *
+     * The coordinator is module-wide, so its commit/rollback callback array holds
+     * one {stats apply/discard} pair per PARTICIPATING table; each table's
+     * `applyPendingStats` early-returns when its own `pendingStatsDelta` is 0, so a
+     * table that did no work contributes nothing. Registers only on first call per
+     * StoreTable instance (the `if (!this.coordinator)` guard); a fresh instance
+     * after drop+recreate re-registers against the shared coordinator. The OLD
+     * instance is not GC'd on its own — its callback closures capture `this` and
+     * stay pinned on the module-wide coordinator until {@link dispose} runs the
+     * captured disposer (called at the genuine eviction sites, see
+     * `StoreModule.tearDownTableStorage` / `renameTable`).
+     */
+    attachCoordinator(): TransactionCoordinator;
+    /**
+     * Ensure the coordinator is available and connection is registered.
+     */
+    protected ensureCoordinator(): Promise<TransactionCoordinator>;
+    /**
+     * Deliver one data-change event: buffered on the coordinator inside a transaction
+     * (fires on commit, discarded on rollback), emitted straight through otherwise.
+     * Every write path routes its event here so the two arms can never drift apart.
+     *
+     * Ordering within a transaction is the coordinator's queue order, which is the order
+     * these calls are made — the event contract's delete-before-insert promise for a
+     * relocating key change rides on that (docs/usage.md § Subscribing to Data Changes).
+     */
+    protected emitOrQueueDataChange(inTransaction: boolean, event: DataChangeEvent): void;
+    /** Apply pending stats on commit. */
+    protected applyPendingStats(): void;
+    /** Discard pending stats on rollback. */
+    protected discardPendingStats(): void;
+    /** Flush statistics to the stats store. */
+    protected flushStats(): Promise<void>;
+    /** Create a new connection for transaction support. */
+    createConnection(): Promise<VirtualTableConnection>;
+    /** Get the current connection. */
+    getConnection(): VirtualTableConnection | undefined;
+    /** Extract primary key values from a full row (positioned by column index). */
+    protected extractPK(row: Row): SqlValue[];
+    /**
+     * Resolve the PK cells an UPDATE/DELETE's `oldKeyValues` addresses.
+     *
+     * `UpdateArgs.oldKeyValues` is COMPACT — one cell per `primaryKeyDefinition`
+     * entry, in that order — NOT a full row positioned by column index. Every
+     * producer builds it that way (`pkIndices.map(i => row[i])` in the DML
+     * executor and in the isolation flush/overlay), and the memory module's
+     * `buildPrimaryKeyFromValues` asserts exactly this arity.
+     *
+     * Running it through {@link extractPK} instead only coincides when every PK
+     * column sits at the index matching its position in the PK definition. For a
+     * table whose PK is not its leading columns (e.g. a generated stored PK
+     * declared after the columns it derives from) that read lands past the end of
+     * the compact array and yields `undefined`.
+     */
+    protected pkFromKeyValues(keyValues: Row): SqlValue[];
+    /**
+     * Coerce each cell in `row` to its declared column logical type.
+     * Mirrors the memory-table path (MemoryTableManager.performInsert/performUpdate)
+     * so INTEGER/REAL affinity is applied and JSON columns are parsed into native
+     * objects before PK extraction, serialization, and index-key construction.
+     */
+    protected coerceRow(row: Row): Row;
+    /**
+     * Iterate the effective entry state of this table's data store within
+     * `bounds`: the committed `store.iterate` stream merged with the
+     * coordinator's pending ops for the data store (read-your-own-writes).
+     *
+     * Both inputs are sorted by encoded key bytes, so this is an
+     * order-preserving two-way merge: a pending put wins over a committed entry
+     * at the same key, a pending delete suppresses its committed entry, and
+     * pending puts outside `bounds` are excluded. With no active transaction
+     * (or an empty pending bucket) it degrades to the bare committed iterate.
+     *
+     * The pending side is the module coordinator's bucket for THIS table's data
+     * store handle (`store`) — every data op is queued under that exact handle, so
+     * a sibling table's pending ops (a different data-store handle) never bleed in.
+     */
+    protected iterateEffective(store: KVStore, bounds: IterateOptions, reverse?: boolean): AsyncIterable<KVEntry>;
+    /**
+     * Read the live row at `pk` — this transaction's pending overlay (a pending
+     * delete ⇒ gone; a pending put ⇒ its value) shadowing the committed store.
+     * Backs `query()`'s point-lookup arm and validates covering-MV conflict
+     * candidates against the source of truth.
+     */
+    protected readLiveRowByPk(pk: SqlValue[]): Promise<Row | null>;
+    /** Encode `pkValues` (in PK-definition order) exactly as the data store keys rows. */
+    encodeDataKey(pkValues: SqlValue[]): Uint8Array;
+    /**
+     * Byte bounds covering every data key whose leading PK columns equal
+     * `prefixValues` — encoded under the same per-column DESC directions and key
+     * collations as {@link encodeDataKey}, so seek + early-terminate addresses the
+     * exact slice. An empty prefix yields full-scan bounds.
+     */
+    encodePkPrefixBounds(prefixValues: SqlValue[]): {
+        gte: Uint8Array;
+        lt?: Uint8Array;
+    };
+    /**
+     * Effective (pending-over-committed) point read by encoded data key: a pending
+     * delete ⇒ null, a pending put ⇒ its value, else the committed store entry.
+     */
+    readEffectiveRowByKey(key: Uint8Array): Promise<Row | null>;
+    /**
+     * Effective ordered entry scan within `bounds` (see {@link iterateEffective}).
+     * Opens the data store first — which fires the lazy first-access `saveTableDDL`
+     * for a freshly created table, the catalog write a store-backed MV backing
+     * relies on to survive reopen.
+     */
+    iterateEffectiveEntries(bounds: IterateOptions, reverse?: boolean): AsyncIterable<KVEntry>;
+    /** Buffer a privileged row-count delta, applied at coordinator commit (host writes). */
+    trackPrivilegedMutation(delta: number): void;
+    /**
+     * Reset statistics to an absolute committed row count and flush immediately.
+     * Used by the host's `replaceContents` (create-fill / refresh), where the new
+     * count is exact, replacing any drifted delta-tracked estimate.
+     */
+    resetStats(rowCount: number): Promise<void>;
+    /**
+     * Open (and cache) the data store, firing the lazy first-access `saveTableDDL`.
+     * Public for the host's `replaceContents`, which writes the store directly.
+     */
+    openDataStore(): Promise<KVStore>;
+    /**
+     * Effective (pending-over-committed) point read by PK values — the public
+     * read an external writer issues before an upsert to learn the row's current
+     * image. Thin wrapper over the same private point-lookup that backs
+     * `StoreTableScan.query`'s point arm, so an external read merges pending-over-committed
+     * exactly like an engine read does.
+     */
+    readRowByPk(pk: SqlValue[]): Promise<Row | null>;
+    /**
+     * Begin a table-scoped transaction by ensuring the coordinator is active.
+     *
+     * Used by the isolation layer's flush path, which treats the underlying
+     * write as an independent mini-transaction. Idempotent: if the coordinator
+     * is already in a transaction (e.g. started by a registered connection),
+     * this is a no-op.
+     */
+    begin(): Promise<void>;
+    /**
+     * Commits a table-scoped transaction, flushing any buffered writes to the KV store.
+     * No-op if the coordinator is not currently in a transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back a table-scoped transaction, discarding any buffered writes.
+     * No-op if the coordinator is not currently in a transaction.
+     */
+    rollback(): Promise<void>;
+    /** Disconnect from the store. */
+    disconnect(): Promise<void>;
+    /**
+     * Hard teardown: fully detach this instance from the module-wide coordinator.
+     *
+     * Distinct from the per-scan {@link disconnect} (which only flushes stats and
+     * deliberately keeps the table hooked mid-life). Called ONLY at the genuine
+     * eviction sites — `StoreModule.tearDownTableStorage` (drop / reclaim) and
+     * `renameTable` — where this instance is removed from the module's `tables` map
+     * and will never be used again. It best-effort flushes any buffered stats (the
+     * backing store is about to be deleted / relocated, so this is the last chance,
+     * same posture as the teardown-time `disconnect` it replaces), then runs the
+     * coordinator disposer so this instance's {stats apply/discard} callback pair —
+     * and the `this` its closures capture — is spliced off the shared coordinator's
+     * array rather than pinned for the module's lifetime.
+     *
+     * Idempotent: the disposer is run at most once and both it and the coordinator
+     * reference are nulled, so a double-dispose is a no-op and a re-`attachCoordinator`
+     * after dispose registers a fresh pair instead of double-registering.
+     */
+    dispose(): Promise<void>;
+    /** Get the current estimated row count. */
+    getEstimatedRowCount(): Promise<number>;
+    /**
+     * The row count this instance can answer WITHOUT any I/O — `undefined` when no
+     * count has been read or maintained yet (a table nothing has touched this session,
+     * or one that has never been counted at all).
+     *
+     * Synchronous by design: `StoreModule.getBestAccessPlan` is a synchronous engine
+     * callback, so the only count it can price a plan with is one already in memory.
+     * {@link primeStats} is what makes that the common case rather than the rare one —
+     * it loads the persisted count when storage is first opened, which every read and
+     * write path does before it can reach the planner a second time.
+     *
+     * Includes the open transaction's buffered delta, so a statement that reads what
+     * its own transaction just wrote is costed against the size it will actually see.
+     */
+    getKnownRowCount(): number | undefined;
+    /**
+     * The `VirtualTable.getStatistics` contract: this table's SIZE, reported from the
+     * running count the write paths already maintain and persist, in O(1) — no scan.
+     *
+     * Column statistics are deliberately absent. The store keeps no value distribution
+     * (a distinct count or histogram would cost a full scan of the table or of an index),
+     * and `ANALYZE` reads an empty `columnStats` as "this module reported its size
+     * cheaply, collect the rest by scanning" (see `runtime/emit/analyze.ts`) — so
+     * implementing this method makes the count reachable without giving up the
+     * per-column statistics ANALYZE collects today.
+     *
+     * `rowCount` is delta-tracked rather than counted, so it can drift from the true
+     * count if a write path ever mis-accounts; `ANALYZE`'s scan is the reconciliation.
+     *
+     * `lastAnalyzed` is deliberately left unset: the only timestamp this table holds is
+     * `TableStats.updatedAt`, the moment the count last MOVED, which is a different fact
+     * — reporting it here would tell a staleness check the table had been analyzed.
+     */
+    getStatistics(): Promise<TableStatistics>;
+    /** Track a mutation and schedule lazy stats persistence. */
+    protected trackMutation(delta: number, inTransaction?: boolean): void;
+}
+//# sourceMappingURL=store-table-base.d.ts.map

package/dist/src/common/store-table-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-table-base.d.ts","sourceRoot":"","sources":["../../../src/common/store-table-base.ts"],"names":[],"mappings":"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"}