@quereus/store 4.3.0 → 4.3.2

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

@@ -9,7 +9,7 @@
  *   - Index stores: {schema}.{table}_idx_{name} - one per secondary index
  *   - Stats store: __stats__ - unified store for all table statistics, keyed by {schema}.{table}
  */
-import { VirtualTable, IndexConstraintOp, ConflictResolution, type Database, type ColumnSchema, type TableSchema, type Row, type FilterInfo, type SqlValue, type VirtualTableConnection, type UpdateArgs, type UpdateResult, type BackingRowChange } from '@quereus/quereus';
+import { VirtualTable, IndexConstraintOp, ConflictResolution, type Database, type CollationFunction, type CollationResolver, type ColumnSchema, type TableSchema, type TableIndexSchema, type UniqueConstraintSchema, type Row, type FilterInfo, type SqlValue, type VirtualTableConnection, type UpdateArgs, type UpdateResult, type BackingRowChange } from '@quereus/quereus';
 import type { IterateOptions, KVEntry, KVStore } from './kv-store.js';
 import type { StoreEventEmitter } from './events.js';
 import type { TransactionCoordinator } from './transaction.js';
@@ -19,32 +19,144 @@ import { type EncodeOptions } from './encoding.js';
 /**
  * Resolve the per-column KEY collation for each primary-key column.
  *
- * The store encodes PRIMARY KEY uniqueness/ordering PHYSICALLY in the key bytes,
- * so each text PK column's key must be encoded under that column's declared
- * collation (BINARY / NOCASE / RTRIM — the registered encoders). Returns one
- * entry per PK member, in `pkDef` order:
- *   - text member → its declared `collation` (normalized upper-case), or
+ * The store encodes PRIMARY KEY uniqueness/ordering PHYSICALLY in the key bytes, so each
+ * text-capable PK column's key must be encoded under the collation the engine actually
+ * COMPARES that column under. Returns one entry per PK member, in `pkDef` order:
+ *   - `isTextual` member (`text`) → its declared `collation` (normalized upper-case), or
  *     `fallback` (the table key collation K) when the column carries none.
- *   - non-text member → `undefined`: collation is meaningless for
+ *   - text-capable but not `isTextual` member — `any`, `json`, and the temporal types
+ *     (`date` / `time` / `datetime` / `timespan`) → hard-coded `'BINARY'`, see below.
+ *   - never-text member → `undefined`: collation is meaningless for
  *     integer/real/blob keys (they encode type-natively), so the encoder ignores
  *     it and the data/index key bytes are identical regardless.
  *
- * A custom comparator-only collation with no registered byte encoder still maps
- * to NOCASE bytes inside `encodeText` (its `?? NOCASE_ENCODER` fallback); that
- * residual is the same one documented for store UNIQUE enforcement and is out of
- * scope here. Shared by {@link StoreTable} (data-key + index-maintenance) and
+ * Note that `undefined` does NOT mean "encode type-natively" to `encodeValue` — it means
+ * "fall back to `options.collation`", the table key collation K. Only a never-text column
+ * may be left `undefined`, because only it never reaches the collation branch.
+ *
+ * Every name returned here is encoded through the key-normalizer resolver carried
+ * in `EncodeOptions.normalizers` (`db.getKeyNormalizerResolver()`), so a collation
+ * registered or overridden with `db.registerCollation` produces key bytes that agree
+ * with the comparator the store's UNIQUE enforcement uses. A collation that cannot
+ * key — unregistered, or registered with a comparator but no normalizer — is rejected
+ * at DDL time by {@link StoreTable.validateKeyCollations}, so no encode call ever has
+ * to fall back. Shared by {@link StoreTable} (data-key + index-maintenance) and
  * `StoreModule.buildIndexEntries` (index rebuild) so the PK suffix encoding can
  * never drift between the two.
  */
 export declare function resolvePkKeyCollations(pkDef: ReadonlyArray<{
     index: number;
 }>, columns: ReadonlyArray<ColumnSchema>, fallback: string): (string | undefined)[];
+/**
+ * True when `col` can produce a TEXT value at runtime, and so when its physical
+ * key bytes are produced by a collation normalizer rather than a type-native
+ * encoding. The `ColumnSchema`-shaped wrapper over the engine's
+ * {@link logicalTypeCanHoldText}; both collation-safety guards over the store's
+ * secondary indexes — the write-side {@link StoreTable.indexSeekHonorsEnforcementCollation}
+ * and the read-side `StoreModule.tryIndexAccessPlan` — exempt a never-text column
+ * from their K-vs-C comparison, so a false "non-text" answer is a silent
+ * wrong-result (a seek under the wrong collation, with the residual dropped).
+ */
+export declare function columnCanHoldText(col: ColumnSchema | undefined): boolean;
+/**
+ * True when a byte window — or a byte-order advertisement — over `column` is SOUND.
+ *
+ * The store physically orders rows by memcmp of each column's key bytes, which for a
+ * text-capable column are produced by `keyCollation`'s normalizer. A range seek (and the
+ * `providesOrdering` / `monotonicOn` advertisement) equates that byte order with the order
+ * `compareCollation`'s comparator defines. Two things must hold for that equation:
+ *
+ *  - **Same collation on both sides** (`compareCollation === keyCollation`). A `keyCollation`
+ *    merely COARSER than `compareCollation` — the relaxation the EQUALITY seek is allowed to
+ *    make, see `StoreModule.tryIndexAccessPlan` — is not enough here: it would need the key
+ *    normalizer to be monotone with respect to the OTHER collation's order. It generally is
+ *    not, even for built-ins: with `keyCollation = NOCASE` and `compareCollation = BINARY`,
+ *    'K' (U+212A KELVIN SIGN) is `> 'z'` under BINARY, yet its key bytes are
+ *    `toLowerCase('K') = 'k'`, which sorts BEFORE 'z' — the row falls outside a `> 'z'`
+ *    window and is silently dropped.
+ *  - **The normalizer preserves order** (`db._isCollationOrderPreserving`). `registerCollation`
+ *    promises only that a normalizer partitions strings the way the comparator calls them
+ *    equal; a custom pair may agree on equality and disagree on order.
+ *
+ * A never-text column is exempt: its key bytes are type-native and collation-independent.
+ *
+ * Returning `false` costs an optimization (the caller full-scans and lets the
+ * collation-aware `matchesFilters` residual decide); returning `true` wrongly is a silent
+ * wrong-result. Shared by `StoreTable`'s read arms and `StoreModule`'s access planner so the
+ * "mark handled" and "build a window" decisions can never disagree.
+ */
+export declare function keyOrderMatchesCollation(db: Database, column: ColumnSchema | undefined, keyCollation: string, compareCollation: string): boolean;
+/**
+ * How many LEADING primary-key members have key bytes whose memcmp order matches their
+ * declared collation's comparator order, per {@link keyOrderMatchesCollation}.
+ *
+ * `pkKeyCollations` is {@link resolvePkKeyCollations}' output for this table; an `undefined`
+ * entry belongs to a never-text member, which {@link keyOrderMatchesCollation} exempts
+ * outright — `tableKeyCollation` is passed only so the exempt branch has a name to ignore.
+ * The comparison collation is the column's declared one, which `reconcilePkCollations` has
+ * already aligned with the key collation for every *textual* PK member.
+ *
+ * What the advertisement is measured against is the order the planner's `Sort` would have
+ * produced, and `Sort` (like every scalar comparison) orders under the operand's COLLATION via
+ * `compareSqlValuesFast` — never through `logicalType.compare`. So a collation match is the
+ * whole question, even for a member whose type declares a `compare` that orders differently
+ * (`TIMESPAN.compare` ranks by `Temporal.Duration` total, `JSON_TYPE.compare` structurally).
+ * `MemoryTable`, whose primary-key BTree *is* keyed by `createTypedComparator`, advertises the
+ * type's order instead and so disagrees with its own `Sort` — tracked as
+ * `bug-memory-pk-btree-orders-by-logical-type-compare`, not something the store should copy.
+ *
+ * `0` ⇒ even the leading member is unsafe: no range seek, no PK-order advertisement.
+ * A prefix shorter than the PK truncates the ordering advertisement rather than voiding it.
+ */
+export declare function pkOrderPreservingPrefixLength(db: Database, schema: TableSchema, pkKeyCollations: ReadonlyArray<string | undefined>, tableKeyCollation: string): number;
+/**
+ * Deterministic name of the implicit covering index materialized for a
+ * NON-DERIVED UNIQUE constraint `uc`: the constraint's own name when it has one,
+ * else the auto-name `_uc_<colNames>`. This MUST equal the engine's
+ * `catalog.ts` `implicitIndexName`, so a name that ever reaches the catalog
+ * bundle generator is recognized as hidden / exposed-implicit rather than a user
+ * index.
+ */
+export declare function implicitUniqueIndexName(schema: TableSchema, uc: UniqueConstraintSchema): string;
+/**
+ * Return `schema` with a synthetic secondary index materialized into
+ * `schema.indexes` for every NON-DERIVED UNIQUE constraint that lacks one — the
+ * store analogue of `MemoryTableManager.ensureUniqueConstraintIndexes`.
+ *
+ * This is what lets a plain column- or table-level `UNIQUE` be enforced by a
+ * bounded index point-seek ({@link StoreTable.findUniqueConflictViaIndex})
+ * instead of an O(rows) full scan: DML maintenance
+ * ({@link StoreTable.updateSecondaryIndexes}) and the UNIQUE check both iterate
+ * `schema.indexes`, so once the `_uc_*` entry is present the physical index is
+ * maintained and seeked with no new code path.
+ *
+ * The result is held ONLY in {@link StoreTable.materializedSchema} (the
+ * enforcement copy), never in the engine-facing `tableSchema` the store returns
+ * from `getSchema()` / registers with the engine. So the read-query planner and
+ * the catalog bundle never see `_uc_*` (it is fully derived on open from
+ * `uniqueConstraints`); like the memory backend, a plain UNIQUE gets no read-side
+ * plan from `_uc_*`, only enforcement / maintenance.
+ *
+ * Idempotent — a name already present is left untouched — and returns a frozen
+ * schema (or the input unchanged when there is nothing to add). A
+ * `derivedFromIndex` UC is skipped (its `CREATE UNIQUE INDEX` is already in
+ * `schema.indexes`). A partial UNIQUE's synthetic index carries the SAME
+ * `uc.predicate` object reference, which
+ * {@link StoreTable.findIndexForUniqueConstraint} matches on identity.
+ */
+export declare function withImplicitUniqueIndexes(schema: TableSchema): TableSchema;
 /**
  * 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
+     * `StoreModule.buildIndexEntries`). Parsed from the `max_batch_bytes` module
+     * arg; undefined falls back to the module default.
+     */
+    maxBatchBytes?: number;
     /** Additional platform-specific options. */
     [key: string]: unknown;
 }
@@ -54,7 +166,7 @@ export interface StoreTableConfig {
  */
 export interface StoreTableModule {
     /** Get the data store for a table. */
-    getStore(tableKey: string, config: StoreTableConfig): Promise<KVStore>;
+    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. */
@@ -117,6 +229,22 @@ export declare class StoreTable extends VirtualTable {
      * {@link updateSchema} (an ALTER COLUMN SET COLLATE on a PK member changes it).
      */
     protected pkKeyCollations: (string | 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;
@@ -124,12 +252,66 @@ export declare class StoreTable extends VirtualTable {
     protected statsFlushPending: boolean;
     private readonly predicateCache;
     private readonly indexPredicateCache;
+    /**
+     * {@link tableSchema} with a hidden `_uc_*` secondary index materialized per
+     * non-derived UNIQUE constraint (see {@link withImplicitUniqueIndexes}) — the
+     * schema that drives UNIQUE ENFORCEMENT ({@link findIndexForUniqueConstraint})
+     * and physical index MAINTENANCE ({@link 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}.
+     */
+    private materializedSchema;
     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);
+     *   - the table key collation K, but only when it is reachable — a secondary index
+     *     encodes a TEXT-CAPABLE index column's bytes under K (`buildIndexKey`).
+     *
+     * So neither a table with an integer PK and no secondary index, nor one whose every
+     * index column is type-natively keyed, is made unopenable by a K it never encodes with.
+     *
+     * 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;
     /** Get the table configuration. */
     getConfig(): StoreTableConfig;
-    /** Get the table schema. */
+    /** Get the table schema (engine-facing, WITHOUT the hidden `_uc_*` indexes). */
     getSchema(): TableSchema;
-    /** Update the table schema after an ALTER TABLE operation. */
+    /**
+     * 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
@@ -141,26 +323,68 @@ export declare class StoreTable extends VirtualTable {
     /** Close and forget a cached index-store handle, if any. */
     releaseIndexStore(indexName: string): Promise<void>;
     /**
-     * Returns true if the table has at least one stored row. Stops after the first hit.
+     * 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>;
     /**
-     * Scan every row, checking whether the column at `colIndex` ever holds NULL.
+     * 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>;
     /**
      * Apply a per-row mapping function to every stored row, in place (re-writing
-     * the same key). The mapper may throw QuereusError — propagated to the caller.
+     * the same key). The mapper may throw QuereusError — propagated to the caller;
+     * the batch is written only after every row maps, so a throw leaves the store
+     * untouched.
+     *
+     * NOTE: reads and writes the COMMITTED store, outside the coordinator. Sound
+     * only because every caller calls `StoreModule.ddlCommitPendingOps` first, so
+     * "committed" is "everything live". A caller that skips that flush would leave
+     * its transaction's pending rows unmapped, and they would replay unconverted
+     * over the rewritten store at commit.
      */
     mapRowsAtIndex(colIndex: number, mapper: (value: SqlValue) => SqlValue): Promise<void>;
     /**
      * Re-key every stored row under a new primary-key definition.
      *
-     * Two-pass: the first pass reads every row and computes the new data keys,
-     * tracking duplicates. On collision we throw `CONSTRAINT` without touching
-     * the store. The second pass batches deletes of displaced old keys and puts
-     * of new (key, row) pairs. Rows whose new key matches the old key are no-ops.
+     * Two-pass, signatures-only pass 1: the first pass computes each row's new data
+     * key and retains only a `Set` of key SIGNATURES (hex of the key bytes) to detect
+     * collisions — two distinct old keys collapsing to one new key under a coarser
+     * collation or a narrower PK. On collision we throw `CONSTRAINT` without touching
+     * the store. The second pass RE-SCANS the same committed store, recomputes each
+     * new key, and batches deletes of displaced old keys + puts of new (key, row)
+     * pairs into ONE atomic batch. Rows whose new key matches the old key are no-ops.
+     *
+     * Holding signatures instead of whole rows halves peak memory: the prior design
+     * retained the entire table in a map AND again in the batch. The re-scan trades
+     * O(rows) CPU (a second iterate + newKey recompute) for not buffering the table
+     * twice. Pass 1 and pass 2 iterate the SAME bounds over the SAME committed store
+     * and see identical rows: nothing writes between them — we are single-threaded
+     * within the ALTER, outside the coordinator, and every caller ran
+     * `StoreModule.ddlCommitPendingOps` first so "committed" is "everything live".
+     *
+     * The final single `batch.write()` is the ONLY thing making the re-key
+     * all-or-nothing — do not chunk-flush it. Its residual peak (the batch still holds
+     * every changed row) is irreducible without breaking atomicity; tracked separately
+     * in `debt-store-atomic-batch-bounded-memory`.
      *
      * Only the data store is rewritten — secondary indexes are rebuilt by the
      * caller (the keys embed the PK suffix, so they must be rebuilt whenever
@@ -287,6 +511,13 @@ export declare class StoreTable extends VirtualTable {
      * a sibling table's pending ops (a different data-store handle) never bleed in.
      */
     protected iterateEffective(store: KVStore, bounds: IterateOptions, reverse?: boolean): AsyncIterable<KVEntry>;
+    /**
+     * True when a byte window over the LEADING PK column reproduces the comparator's order
+     * — the precondition {@link buildPKRangeBounds} needs, and the exact condition
+     * `StoreModule.computeBestAccessPlan` uses before claiming the range filters handled.
+     * When false, the range arm degrades to a full scan + `matchesFilters` residual.
+     */
+    protected leadingPkRangeIsOrderSafe(): boolean;
     /** Analyze filter info to determine PK access pattern. */
     protected analyzePKAccess(filterInfo: FilterInfo): PKAccessPattern;
     /**
@@ -316,11 +547,16 @@ export declare class StoreTable extends VirtualTable {
      * row filter. A NULL/missing bound value is likewise skipped (the planner never
      * pushes `= NULL`, and a range op against NULL rejects every row in matchesFilters).
      *
-     * Falls back to a full scan when the leading text PK column declares a
-     * comparator-only collation with no registered byte encoder: `encodeText` would
-     * silently key it under NOCASE bytes that do not track the column's logical
-     * order, so a derived window could UNDER-fetch. A non-text leading column has
-     * `pkKeyCollations[0] === undefined` and encodes type-natively — always safe.
+     * NOTE: a range window over a text PK column is sound only when the column's key
+     * normalizer is ORDER-preserving with respect to its comparator — i.e. the comparator
+     * orders two strings the way memcmp orders their normalized bytes. That is NOT implied
+     * by `db.registerCollation`'s normalizer contract, which promises only an equality
+     * partition, and a built-in NAME may be re-registered with a comparator + normalizer
+     * pair that preserves equality while inverting order. This method is therefore only
+     * ever reached under {@link leadingPkRangeIsOrderSafe} — enforced by
+     * {@link analyzePKAccess} here and mirrored by `StoreModule.computeBestAccessPlan`
+     * before it claims the range filters handled. A collation without the
+     * `orderPreserving` assertion costs the seek, never a row.
      */
     protected buildPKRangeBounds(access: PKAccessPattern): IterateOptions;
     /**
@@ -336,18 +572,148 @@ export declare class StoreTable extends VirtualTable {
      * merge to the same `bounds`, so read-your-own-writes holds on the narrowed window.
      */
     protected scanPKRange(store: KVStore, access: PKAccessPattern, filterInfo: FilterInfo): AsyncIterable<Row>;
-    /** Check if a row matches the filter constraints. */
-    protected matchesFilters(row: Row, filterInfo: FilterInfo): boolean;
     /**
-     * Compare two values according to an operator, under `collation` (the column's
-     * declared collation; undefined ⇒ BINARY). Delegates to the engine's
-     * `compareSqlValues`, so the LT/LE/GT/GE range bounds honour a NOCASE/RTRIM
-     * column collation rather than a raw BINARY JS comparison — the capability
+     * Resolve the secondary index chosen by the planner from `filterInfo.idxStr`.
+     *
+     * The planner emits `idx=<name>(<n>);plan=…` when its access plan set both an
+     * `indexName` and `seekColumnIndexes` (see `getBestAccessPlan` and
+     * rule-select-access-path.ts). Decoding goes through the engine's shared
+     * `decodeIdxStr`, so the store, the in-memory vtab, and the isolation overlay all
+     * read one format. Returns null for the PK/scan sentinels (`_primary_`, `fullscan`,
+     * `empty`), an idxStr that names no index, or a name absent from `schema.indexes` —
+     * every one of which routes back to a PK/full-scan arm.
+     */
+    protected resolveIndexFromIdxStr(idxStr: string | null): TableIndexSchema | null;
+    /**
+     * Analyze filter info to determine a secondary-index access pattern, mirroring
+     * {@link analyzePKAccess} but over the index chosen in `idxStr`.
+     *
+     * A contiguous leading-prefix EQ on the index columns yields a `point` window
+     * (the prefix covers every entry sharing those leading values — an index seek
+     * is a PREFIX scan, not a single row, since the index need not be unique and
+     * the PK suffix varies); otherwise a range (LT/LE/GT/GE) on the LEADING index
+     * column yields a `range` window. Returns null when neither applies or when the
+     * index is unresolved. {@link matchesFilters} stays the authoritative row filter,
+     * so the window need only be a SUPERSET.
+     *
+     * Index-column bytes are encoded under the table key collation K (NOT the index's
+     * per-column declared collation — see `buildIndexKey`), while `matchesFilters` compares
+     * under the index column's effective collation C. The EQ/prefix window is a superset
+     * whenever K is coarser-or-equal to C, which `StoreModule.tryIndexAccessPlan` checked
+     * before it named this index. The RANGE window additionally needs byte order to BE
+     * comparator order, so it is gated on {@link keyOrderMatchesCollation} (which demands
+     * `C === K` plus K's `orderPreserving` assertion); when that fails we return null and
+     * the caller full-scans.
+     */
+    protected analyzeIndexAccess(filterInfo: FilterInfo): IndexAccessPattern | null;
+    /**
+     * True when a byte window over `leadingCol` of `index` reproduces the comparator's
+     * order. Mirrors the range arm of `StoreModule.tryIndexAccessPlan`: the window's bytes
+     * come from the table key collation K, the residual compares under the index column's
+     * effective collation C, so both must be the same order-preserving collation.
+     */
+    protected indexRangeIsOrderSafe(index: TableIndexSchema, leadingCol: number): boolean;
+    /**
+     * Convert leading-index-column LT/LE/GT/GE constraints into one encoded-byte
+     * `gte`/`lt` window — the secondary-index analogue of {@link buildPKRangeBounds}.
+     *
+     * Each bound value is encoded under {@link encodeOptions} (the table key collation K
+     * and its normalizer resolver) and the leading index column's DESC `dir` — exactly as
+     * {@link buildIndexKey} encodes
+     * that column — via {@link buildIndexPrefixBounds}, giving the byte region
+     * `[lo, hi)` whose leading column equals that value. The op maps that region's
+     * endpoints onto `gte`/`lt`, with the same DESC lower/upper SWAP as the PK path:
+     *
+     *   | op | ASC      | DESC     |
+     *   |----|----------|----------|
+     *   | GE | gte = lo | lt  = hi |
+     *   | GT | gte = hi | lt  = lo |
+     *   | LE | lt  = hi | gte = lo |
+     *   | LT | lt  = lo | gte = hi |
+     *
+     * Across constraints keep the MAX lower and MIN upper. An `undefined` upper (an
+     * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
+     * SUPERSET. A NULL/missing bound value is skipped (the planner never pushes
+     * `= NULL`, and a range op against NULL rejects every row in matchesFilters).
+     */
+    protected buildIndexRangeBounds(constraints: Array<{
+        op: IndexConstraintOp;
+        value?: SqlValue;
+    }>, dir: boolean): IterateOptions;
+    /**
+     * Scan a secondary index over `access.bounds`, resolving each index entry to its
+     * base row and re-filtering.
+     *
+     * {@link iterateEffective} yields the committed index entries merged with this
+     * transaction's pending index puts/deletes (read-your-own-writes over the
+     * index), in index-key byte order — the order the isolation overlay merge relies
+     * on (`isolated-table.ts` § buildSortKey). We resolve each entry to its row via
+     * its stored data-key value WITHOUT reordering, so index-key order is preserved.
+     *
+     * Defense in depth mirroring the memory layer's live-recheck: a resolved-null
+     * row (the entry's row was deleted — a pending index delete would normally
+     * suppress the entry, but a committed entry can lag) is skipped, and every
+     * resolved row is re-checked by {@link matchesFilters} (the byte window is only
+     * a superset, and a stale entry whose indexed column no longer matches is
+     * dropped).
+     */
+    protected scanIndex(indexStore: KVStore, access: IndexAccessPattern, filterInfo: FilterInfo): AsyncIterable<Row>;
+    /**
+     * Check if a row matches the filter constraints.
+     *
+     * `collations` maps a constrained column index to the comparison function that
+     * column must be re-checked under; every caller builds it once per scan with
+     * {@link resolveFilterCollations}, whose doc comment explains how the name is
+     * chosen. A column absent from the map compares BINARY — the same result
+     * {@link resolveFilterCollations} produces for an undeclared collation, and the
+     * only reachable absence, since both walk the constraint list under identical
+     * skip conditions.
+     */
+    protected matchesFilters(row: Row, filterInfo: FilterInfo, collations: ReadonlyMap<number, CollationFunction>): boolean;
+    /**
+     * Resolve, ONCE per scan, the comparison collation function for every pushed
+     * constraint column, keyed by column index.
+     *
+     * The name for a column is its DECLARED collation (absent ⇒ BINARY) — the same
+     * resolution the access path's collation-cover analysis uses
+     * (indexColumnCollationLookup / primaryKeyCollationLookup) when it decides a
+     * pushed constraint is fully covered, and the same source this file's UNIQUE
+     * checks compare under. On a collation MATCH the planner drops the residual
+     * Filter, so {@link matchesFilters} alone must reproduce the predicate.
+     *
+     * `indexCollationNames` (from {@link indexColumnCollations}) overrides the
+     * declared name for the secondary-index scan arm: the planner's MATCH there is
+     * against the INDEX column's collation, which an explicit `COLLATE` on the index
+     * can make differ from the table column's.
+     *
+     * Names resolve against {@link collationResolver}, so an unregistered collation
+     * raises `no such collation sequence` at scan setup rather than byte-ordering
+     * every row.
+     *
+     * NOTE: rebuilt on every `query()` / `scanPKRange()` / `scanIndex()` call — one
+     * registry lookup per distinct constrained column, dwarfed by the scan's I/O. If a
+     * point-lookup-heavy profile ever shows it, memoize on the `FilterInfo`.
+     */
+    protected resolveFilterCollations(filterInfo: FilterInfo, indexCollationNames?: ReadonlyMap<number, string | undefined>): ReadonlyMap<number, CollationFunction>;
+    /**
+     * Effective per-column comparison collation for a secondary index's columns:
+     * the index column's own `COLLATE` when present, else the underlying table
+     * column's declared collation. Mirrors the resolution `StoreModule`'s
+     * index-maintenance UNIQUE dedup uses (`indexCol.collation ?? tableColumn`), so
+     * a re-checked index-scan row compares under the same collation the planner used
+     * to justify dropping (or keeping) the residual Filter.
+     */
+    protected indexColumnCollations(index: TableIndexSchema): Map<number, string | undefined>;
+    /**
+     * Compare two values according to an operator, under `collationFunc` (already
+     * resolved by {@link resolveFilterCollations} against this database's collation
+     * registry). So the LT/LE/GT/GE range bounds honour a NOCASE/RTRIM/custom column
+     * collation rather than a raw BINARY JS comparison — the capability
      * `StoreModule.getBestAccessPlan` advertises via `honorsCollatedRangeBounds`.
      * NULL on either side fails every operator except EQ-with-both-NULL (the
      * internal point-lookup convention; the planner never pushes `= NULL`).
      */
-    protected compareValues(a: SqlValue, op: IndexConstraintOp, b: SqlValue, collation?: string): boolean;
+    protected compareValues(a: SqlValue, op: IndexConstraintOp, b: SqlValue, collationFunc: CollationFunction): boolean;
     /** Perform an update operation (INSERT, UPDATE, DELETE). */
     update(args: UpdateArgs): Promise<UpdateResult>;
     /**
@@ -397,6 +763,105 @@ export declare class StoreTable extends VirtualTable {
      * (change-tracking, row-time MV maintenance, FK cascade, auto-events).
      */
     protected checkUniqueConstraints(inTransaction: boolean, newRow: Row, selfPks: SqlValue[][], onConflict: ConflictResolution | undefined, evicted: Row[]): Promise<UpdateResult | null>;
+    /**
+     * Route one UNIQUE constraint's conflict search to the cheapest SOUND finder,
+     * in descending preference:
+     *
+     *  1. A linked row-time covering MV — its backing table (hosted by any
+     *     backing-host-capable module — memory by default, this store module under
+     *     `using store` — queried through the db with reads-own-writes) answers the
+     *     uniqueness question, mirroring the memory enforcement path.
+     *  2. A physical secondary index realizing the constraint — one prefix seek
+     *     instead of a full table scan (see {@link findIndexForUniqueConstraint}).
+     *  3. The full data-store scan ({@link findUniqueConflict}) — always correct,
+     *     O(rows) per checked row.
+     *
+     * Every finder returns the SAME `{pk, row}` shape, so the caller's conflict
+     * action (ABORT / IGNORE / REPLACE eviction) is finder-independent.
+     */
+    private findUniqueConflictFor;
+    /**
+     * The `schema.indexes` entry whose physical index store can serve `uc`'s
+     * conflict search as a point seek, or undefined when none can.
+     *
+     * Every non-derived UNIQUE now carries a materialized implicit index
+     * (`_uc_*`, see {@link withImplicitUniqueIndexes}), so — like the memory
+     * backend — a plain column- or table-level `UNIQUE` is index-servable, not
+     * only an explicit `CREATE INDEX`. A UC is index-servable when:
+     *
+     *  - it is index-derived (`derivedFromIndex`, from `CREATE UNIQUE INDEX`) and
+     *    its named index is still present — the index's partial predicate then
+     *    equals the constraint's by construction (`appendIndexToTableSchema`); or
+     *  - some index's columns equal `uc.columns` positionally AND whose predicate
+     *    is the SAME object as `uc.predicate` (reference identity — the implicit
+     *    materializer sets it that way). For a FULL UNIQUE that is
+     *    `undefined === undefined`, which also admits any user full index over the
+     *    same columns. For a PARTIAL `unique(...) where p` it admits only the
+     *    co-scoped `_uc_*` (which holds exactly the in-scope rows); an arbitrary
+     *    user partial index with a DIFFERENT predicate object stays conservative
+     *    (declined → full scan), because it physically omits rows the constraint
+     *    still covers. The serving index need not be UNIQUE — a plain index over
+     *    the constrained columns still holds every in-scope row.
+     *
+     * Collation guard (see {@link indexSeekHonorsEnforcementCollation}) may still
+     * reject the found index, which routes the check back to the full scan.
+     */
+    private findIndexForUniqueConstraint;
+    /**
+     * True when a point seek into the index realizing `uc` returns a SUPERSET of
+     * the constraint's true conflict set — the only condition under which the
+     * seek may replace the full scan.
+     *
+     * An index key's leading (index-column) bytes are encoded under the TABLE KEY
+     * collation K (`buildIndexKey` passes `this.encodeOptions`), NOT the index's
+     * declared per-column COLLATE and NOT the constraint's enforcement collation
+     * C (`uniqueEnforcementCollations` — the index's per-column COLLATE for an
+     * index-derived UC, else the declared column collation). A seek therefore
+     * fetches exactly `{rows K-equal to newRow}` while the re-validation keeps
+     * `{rows C-equal to newRow}`. Soundness needs
+     * `{C-equal} ⊆ {K-equal}`, i.e. K must be COARSER-OR-EQUAL to C per column:
+     *
+     *  - non-text column → its bytes are type-native, collation-independent: safe.
+     *  - C == K → the sets coincide: safe.
+     *  - K = NOCASE, C = BINARY → K strictly coarser: safe superset.
+     *  - otherwise (K = BINARY over C = NOCASE/RTRIM; K = NOCASE over C = RTRIM)
+     *    the seek UNDER-fetches and a real duplicate would be silently accepted:
+     *    reject, so the caller full-scans.
+     *
+     * Same direction and same admitted cases as the read-side guard in
+     * `StoreModule.tryIndexAccessPlan`; conservative rather than exhaustive
+     * (K = RTRIM over C = BINARY is provably safe but declined), which costs an
+     * optimization, never correctness. The coarseness test is only sound for the
+     * built-in names: a custom K equals a custom C only when the index column names
+     * that same collation, and otherwise falls through to the full scan.
+     */
+    private indexSeekHonorsEnforcementCollation;
+    /**
+     * The index analogue of {@link findUniqueConflict}: seek the index realizing
+     * `uc` at the point formed by `newRow`'s constrained-column values, and
+     * re-validate each resolved candidate exactly as the full scan does.
+     *
+     * The seek encodes ALL of `uc.columns` (positionally aligned with the index's
+     * columns, guaranteed by `appendIndexToTableSchema` / the column-set match in
+     * {@link findIndexForUniqueConstraint}) as a leading prefix of the index key,
+     * under the same key collation and per-column DESC directions
+     * {@link updateSecondaryIndexes} used to write it. The remaining suffix is the
+     * row's PK, so the window spans every entry sharing those column values.
+     * {@link iterateEffective} merges this transaction's pending index puts/deletes
+     * over the committed entries, giving read-your-own-writes; each entry resolves
+     * to its LIVE row through the data key stored as the entry's value.
+     *
+     * The seek only narrows the CANDIDATE set to a superset (guaranteed by
+     * {@link indexSeekHonorsEnforcementCollation}); the authoritative comparison is
+     * the identical self-PK exclusion, per-column enforcement-collation compare,
+     * and partial-predicate scope check the full scan performs. A partial index
+     * already excludes out-of-scope rows physically — the predicate re-check is
+     * kept as defense in depth.
+     *
+     * Returns {@link INDEX_UNUSABLE} rather than a (possibly wrong) answer when an
+     * entry carries a legacy empty value.
+     */
+    private findUniqueConflictViaIndex;
     /**
      * Scan committed + pending data rows for a row matching `newRow` on
      * `uc.columns` whose PK is not in `selfPks`. For partial UNIQUE, candidates
@@ -451,7 +916,7 @@ export declare class StoreTable extends VirtualTable {
      * Declared secondary-UNIQUE enforcement for maintenance writes — the store
      * mirror of the memory manager's `enforceSecondaryUniqueOnMaintenance` (see
      * `vtab/backing-host.ts` § Constraint validation for the contract and
-     * docs/materialized-views.md § Derived-row constraint validation for the
+     * docs/mv-constraints.md § Derived-row constraint validation for the
      * semantics). Called by `StoreBackingHost.applyMaintenance` AFTER the op
      * batch lands in the coordinator's pending state: post-batch is load-bearing
      * (a `replace-all` diff applies puts before deletes, so a per-op check would
@@ -466,8 +931,10 @@ export declare class StoreTable extends VirtualTable {
      * and would miss a same-batch colliding pair. The conflict action is a hard
      * abort (a derivation write carries no user OR clause, and a declared
      * `on conflict replace`/`ignore` default must not evict or drop derived
-     * rows). Per-image cost is one effective scan — the same full-scan posture
-     * the store's DML UNIQUE enforcement already takes.
+     * rows). Per-image cost is one effective full scan: unlike the DML path
+     * ({@link findUniqueConflictFor}), this one is NOT routed through
+     * {@link findUniqueConflictViaIndex}, because a backing table keeps no
+     * secondary indexes by design — there is never an index store to seek.
      *
      * Zero overhead when the table declares no secondary UNIQUE (every MV-sugar
      * backing, and most maintained tables): one empty-array check.
@@ -585,5 +1052,17 @@ interface PKAccessPattern {
         value?: SqlValue;
     }>;
 }
+/**
+ * Secondary-index access pattern analysis result: the chosen index plus the
+ * encoded byte window {@link StoreTable.scanIndex} iterates. `point` is a
+ * leading-prefix EQ window, `range` a leading-column LT/LE/GT/GE window; both
+ * resolve to a `bounds` scan (an index seek is always a prefix scan, never a
+ * single entry).
+ */
+interface IndexAccessPattern {
+    index: TableIndexSchema;
+    type: 'point' | 'range';
+    bounds: IterateOptions;
+}
 export {};
 //# sourceMappingURL=store-table.d.ts.map