@quereus/store 4.5.0 → 4.6.0

package/dist/src/common/store-table-scan.js

@@ -0,0 +1,821 @@
+/**
+ * The read path of the KVStore-backed virtual table: turning a pushed predicate
+ * into a byte window over the data store or a secondary index, iterating that
+ * window, and re-checking every pushed constraint under the column's real
+ * collation.
+ *
+ * Second layer of the store-table chain:
+ *   StoreTableBase -> StoreTableScan -> StoreTableConstraints -> StoreTable
+ */
+import { IndexConstraintOp, QuereusError, StatusCode, compareSqlValuesFast, createTypedComparator, hasSemanticOrdering, BINARY_COLLATION, decodeIdxStr, planKindFromCode, } from '@quereus/quereus';
+import { bytesToHex, compareBytes } from './bytes.js';
+import { buildIndexPrefixBounds, buildFullScanBounds, } from './key-builder.js';
+import { deserializeRow, } from './serialization.js';
+import { indexLeadingRangeIsOrderSafe, indexPrefixSeekIsCollationExact, pkOrderPreservingPrefixLength, resolveIndexKeyCollations } from './pk-key-resolution.js';
+import { StoreTableBase } from './store-table-base.js';
+/**
+ * Read-path layer of the generic KVStore-backed virtual table.
+ *
+ * Every arm below reads the EFFECTIVE row state (see
+ * {@link StoreTableBase.iterateEffective}), so a byte window narrowed here still
+ * honors read-your-own-writes.
+ */
+export class StoreTableScan extends StoreTableBase {
+    /**
+     * Query the table with optional filters.
+     *
+     * All three access arms read the EFFECTIVE row state: the committed store
+     * merged with this table's coordinator's pending ops when a transaction is
+     * active (read-your-own-writes — see {@link iterateEffective} /
+     * {@link readLiveRowByPk}). Merged emission stays in encoded-PK-key order,
+     * preserving the module's `providesOrdering` / `monotonicOn` advertisements.
+     */
+    async *query(filterInfo) {
+        const store = await this.ensureStore();
+        // Multi-seek (`plan=5`, an IN-list served as N point seeks) dispatches FIRST —
+        // before analyzePKAccess: the FilterInfo carries N*W EQ constraints, so on a
+        // table whose PK column is also the leading column of the chosen index,
+        // analyzePKAccess would match the FIRST equality and answer a single-value
+        // point lookup — one list value's rows, a silent wrong result.
+        const idxSpec = decodeIdxStr(filterInfo.idxStr);
+        if (idxSpec && planKindFromCode(idxSpec.plan) === 'multiSeek') {
+            yield* this.scanMultiSeek(idxSpec, filterInfo);
+            return;
+        }
+        const pkAccess = this.analyzePKAccess(filterInfo);
+        if (pkAccess.type === 'point') {
+            const row = await this.readLiveRowByPk(pkAccess.values);
+            if (row && this.matchesFilters(row, filterInfo, this.resolveFilterCollations(filterInfo))) {
+                yield row;
+            }
+            return;
+        }
+        if (pkAccess.type === 'range') {
+            yield* this.scanPKRange(store, pkAccess, filterInfo);
+            return;
+        }
+        // Secondary-index scan arm — reached only when the predicate did NOT resolve
+        // to a PK point/range (PK access is cheaper and already handled above). When
+        // the planner chose a secondary index (idxStr carries `idx=<name>(…)`), derive
+        // its byte window and iterate it instead of full-scanning.
+        const indexAccess = this.analyzeIndexAccess(filterInfo);
+        if (indexAccess) {
+            const indexStore = await this.ensureIndexStore(indexAccess.index.name);
+            yield* this.scanIndex(indexStore, indexAccess, filterInfo);
+            return;
+        }
+        // Full table scan
+        const collations = this.resolveFilterCollations(filterInfo);
+        const bounds = buildFullScanBounds();
+        for await (const entry of this.iterateEffective(store, bounds)) {
+            const row = deserializeRow(entry.value);
+            if (this.matchesFilters(row, filterInfo, collations)) {
+                yield row;
+            }
+        }
+    }
+    /**
+     * True when a byte window over the LEADING PK column reproduces the comparator's order
+     * — the precondition {@link buildPKRangeBounds} needs, and the exact condition
+     * `computeBestAccessPlan` (store-module-access-plan.ts) uses before claiming the range filters handled.
+     * When false, the range arm degrades to a full scan + `matchesFilters` residual.
+     */
+    leadingPkRangeIsOrderSafe() {
+        return pkOrderPreservingPrefixLength(this.db, this.tableSchema, this.pkKeyCollations, this.encodeOptions.collation ?? 'NOCASE') >= 1;
+    }
+    /**
+     * True when some PK member's logical type carries semantic ordering (TIMESPAN,
+     * JSON). Such PKs decline the point arm and full-scan, where
+     * {@link matchesFilters} applies the type's compare. Historically required —
+     * byte-key equality was a strict subset of the type's equality ('PT1H' ≡
+     * 'PT60M' elapsed-time-equal, byte-distinct) and a point window under-fetched
+     * with no residual able to resurrect a skipped row. Both types' key transforms
+     * (see {@link storeSemanticKeyTransform}) now make byte equality the type's
+     * equality, so the decline is conservative; re-opening is tracked in backlog
+     * `feat-reopen-timespan-store-seeks`. (Range windows and ordering
+     * advertisements are already declined by {@link keyOrderMatchesCollation}.)
+     */
+    pkHasSemanticOrderingMember() {
+        const schema = this.tableSchema;
+        return schema.primaryKeyDefinition.some(def => hasSemanticOrdering(schema.columns[def.index]?.logicalType));
+    }
+    /** Analyze filter info to determine PK access pattern. */
+    analyzePKAccess(filterInfo) {
+        const schema = this.tableSchema;
+        const pkColumns = schema.primaryKeyDefinition.map(pk => pk.index);
+        if (pkColumns.length === 0) {
+            return { type: 'scan' };
+        }
+        // Check for equality on all PK columns
+        const eqValues = new Array(pkColumns.length);
+        let allEq = true;
+        for (let i = 0; i < pkColumns.length; i++) {
+            const pkColIdx = pkColumns[i];
+            const eqConstraintEntry = filterInfo.constraints?.find(c => c.constraint.iColumn === pkColIdx && c.constraint.op === IndexConstraintOp.EQ);
+            if (eqConstraintEntry && eqConstraintEntry.argvIndex > 0) {
+                eqValues[i] = filterInfo.args[eqConstraintEntry.argvIndex - 1];
+            }
+            else {
+                allEq = false;
+                break;
+            }
+        }
+        if (allEq && !this.pkHasSemanticOrderingMember()) {
+            return { type: 'point', values: eqValues };
+        }
+        // Check for range constraints on first PK column
+        const firstPkCol = pkColumns[0];
+        const rangeOps = [IndexConstraintOp.LT, IndexConstraintOp.LE, IndexConstraintOp.GT, IndexConstraintOp.GE];
+        const rangeConstraints = filterInfo.constraints?.filter(c => c.constraint.iColumn === firstPkCol && rangeOps.includes(c.constraint.op)) || [];
+        // A range window is only sound when the leading PK column's key bytes order the way
+        // its comparator does; otherwise fall through to the full scan, where matchesFilters
+        // applies the range under the real comparator.
+        if (rangeConstraints.length > 0 && this.leadingPkRangeIsOrderSafe()) {
+            return {
+                type: 'range',
+                columnIndex: firstPkCol,
+                constraints: rangeConstraints.map(c => ({
+                    columnIndex: c.constraint.iColumn,
+                    op: c.constraint.op,
+                    value: c.argvIndex > 0 ? filterInfo.args[c.argvIndex - 1] : undefined,
+                })),
+            };
+        }
+        return { type: 'scan' };
+    }
+    /**
+     * Convert a leading-PK-column range access into one seek + early-terminate
+     * iterate window.
+     *
+     * Each LT/LE/GT/GE constraint's bound value is encoded under the SAME
+     * per-column DESC direction and key collation as the data keys (via
+     * {@link encodePkPrefixBounds}), giving the byte region `[lo, hi)` whose
+     * leading column equals that value (`lo = encode([x])`,
+     * `hi = incrementLastByte(lo)`). The op maps that region's endpoints onto a
+     * `gte`/`lt` window; because a DESC column bit-inverts its bytes (larger value
+     * ⇒ smaller bytes), the lower/upper assignment swaps with direction:
+     *
+     *   | 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 (BETWEEN ⇒ one lower + one upper; a redundant same-side
+     * pair ⇒ the tighter wins) we keep the MAX lower candidate for `gte` and the
+     * MIN upper candidate for `lt`. A candidate that resolves to `undefined` (an
+     * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
+     * SUPERSET, since {@link matchesFilters} stays the authoritative collation-aware
+     * 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).
+     *
+     * 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 `computeBestAccessPlan` (store-module-access-plan.ts)
+     * before it claims the range filters handled. A collation without the
+     * `orderPreserving` assertion costs the seek, never a row.
+     */
+    buildPKRangeBounds(access) {
+        const full = buildFullScanBounds();
+        const constraints = access.constraints;
+        if (!constraints || constraints.length === 0)
+            return full;
+        const dir = this.pkDirections[0];
+        let gte = full.gte;
+        let lt;
+        for (const c of constraints) {
+            if (c.value === undefined || c.value === null)
+                continue;
+            const { gte: lo, lt: hi } = this.encodePkPrefixBounds([c.value]);
+            const lower = !dir
+                ? (c.op === IndexConstraintOp.GE ? lo : c.op === IndexConstraintOp.GT ? hi : undefined)
+                : (c.op === IndexConstraintOp.LE ? lo : c.op === IndexConstraintOp.LT ? hi : undefined);
+            const upper = !dir
+                ? (c.op === IndexConstraintOp.LE ? hi : c.op === IndexConstraintOp.LT ? lo : undefined)
+                : (c.op === IndexConstraintOp.GE ? hi : c.op === IndexConstraintOp.GT ? lo : undefined);
+            if (lower && compareBytes(lower, gte) > 0)
+                gte = lower;
+            if (upper && (lt === undefined || compareBytes(upper, lt) < 0))
+                lt = upper;
+        }
+        return lt === undefined ? { gte } : { gte, lt };
+    }
+    /**
+     * Scan a leading-PK-column range, seeking to the window start and
+     * early-terminating at its end.
+     *
+     * {@link buildPKRangeBounds} converts the LT/LE/GT/GE constraints into one
+     * encoded-byte `gte`/`lt` window under the same per-column DESC directions and
+     * key collations the data keys use, so the iterate visits a SUPERSET of the
+     * qualifying rows (a collation widening or the bound-byte increment can
+     * over-fetch, never under-fetch). {@link matchesFilters} stays the authoritative
+     * collation-aware row filter. {@link iterateEffective} restricts the pending
+     * merge to the same `bounds`, so read-your-own-writes holds on the narrowed window.
+     */
+    async *scanPKRange(store, access, filterInfo) {
+        const collations = this.resolveFilterCollations(filterInfo);
+        const bounds = this.buildPKRangeBounds(access);
+        for await (const entry of this.iterateEffective(store, bounds)) {
+            const row = deserializeRow(entry.value);
+            if (this.matchesFilters(row, filterInfo, collations)) {
+                yield row;
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    resolveIndexFromIdxStr(idxStr) {
+        const spec = decodeIdxStr(idxStr);
+        if (!spec)
+            return null;
+        const name = spec.indexName;
+        if (!name || name === '_primary_')
+            return null;
+        const indexes = this.tableSchema?.indexes ?? [];
+        return indexes.find(i => i.name.toLowerCase() === name.toLowerCase()) ?? 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 each column's own key collation
+     * ({@link indexKeyCollations}); {@link matchesFilters} re-checks a fetched row under the
+     * index column's `COLLATE` else the table column's declared collation. The EQ/prefix
+     * window is EXACTLY the qualifying set when those two agree, which
+     * {@link indexPrefixSeekIsCollationExact} decides; the RANGE window additionally equates
+     * memcmp of the key bytes with the residual's comparison ORDER, which
+     * {@link indexRangeIsOrderSafe} decides. `tryIndexAccessPlan`
+     * (store-module-access-plan.ts) consults the SAME two predicates before claiming the
+     * filters handled, so the two decisions cannot disagree. Either failing returns null and
+     * the caller full-scans, where the residual is authoritative.
+     */
+    analyzeIndexAccess(filterInfo) {
+        const index = this.resolveIndexFromIdxStr(filterInfo.idxStr);
+        if (!index)
+            return null;
+        const indexCols = index.columns.map(c => c.index);
+        const indexDirections = index.columns.map(c => !!c.desc);
+        const indexCollations = this.indexKeyCollations(index);
+        // Contiguous leading-prefix EQ → point/prefix window. A prefix member whose
+        // logical type carries semantic ordering stops the prefix: its byte-equality
+        // window under-fetches the type's equality (see pkHasSemanticOrderingMember),
+        // and a skipped row cannot be resurrected by the residual.
+        const eqValues = [];
+        for (let i = 0; i < indexCols.length; i++) {
+            if (hasSemanticOrdering(this.tableSchema.columns[indexCols[i]]?.logicalType))
+                break;
+            const eq = filterInfo.constraints?.find(c => c.constraint.iColumn === indexCols[i]
+                && c.constraint.op === IndexConstraintOp.EQ
+                && c.argvIndex > 0);
+            if (!eq)
+                break;
+            eqValues.push(filterInfo.args[eq.argvIndex - 1]);
+        }
+        if (eqValues.length > 0) {
+            // Decline rather than fall through to the range arm: an EQ prefix whose key
+            // collation differs from the residual's comparison collation would under-fetch,
+            // and the planner declined the same shape, so the residual Filter is still there.
+            if (!indexPrefixSeekIsCollationExact(this.tableSchema.columns, index, indexCollations, eqValues.length)) {
+                return null;
+            }
+            const bounds = buildIndexPrefixBounds(eqValues, this.encodeOptions, indexDirections.slice(0, eqValues.length), indexCollations.slice(0, eqValues.length));
+            return { index, type: 'point', bounds };
+        }
+        // Else a range on the LEADING index column.
+        const leadingCol = indexCols[0];
+        const rangeOps = [IndexConstraintOp.LT, IndexConstraintOp.LE, IndexConstraintOp.GT, IndexConstraintOp.GE];
+        const rangeConstraints = (filterInfo.constraints ?? []).filter(c => c.constraint.iColumn === leadingCol && rangeOps.includes(c.constraint.op));
+        if (rangeConstraints.length > 0 && this.indexRangeIsOrderSafe(index)) {
+            const bounds = this.buildIndexRangeBounds(rangeConstraints.map(c => ({
+                op: c.constraint.op,
+                value: c.argvIndex > 0 ? filterInfo.args[c.argvIndex - 1] : undefined,
+            })), indexDirections[0], indexCollations[0]);
+            return { index, type: 'range', bounds };
+        }
+        return null;
+    }
+    /**
+     * Lazy cache behind {@link indexKeyCollations}: one resolved array per index-schema
+     * object, invalidated when the column array it was resolved against is replaced (an
+     * ALTER can retype a column without minting new index objects, so the index identity
+     * alone is not a safe key).
+     */
+    indexKeyCollationsCache = new WeakMap();
+    /**
+     * Per-column KEY collation for `index`'s own columns, memoized — see
+     * {@link resolveIndexKeyCollations}. The one resolution every scan-side encode site
+     * ({@link analyzeIndexAccess}, {@link buildIndexRangeBounds}, {@link scanMultiSeek})
+     * threads into `buildIndexPrefixBounds`, so a scan window can never address
+     * different bytes than the maintenance writes.
+     */
+    indexKeyCollations(index) {
+        const columns = this.tableSchema.columns;
+        const cached = this.indexKeyCollationsCache.get(index);
+        if (cached && cached.columns === columns)
+            return cached.collations;
+        const collations = resolveIndexKeyCollations(index, columns);
+        this.indexKeyCollationsCache.set(index, { columns, collations });
+        return collations;
+    }
+    /**
+     * Per-column comparators stating the store's actual index-key BYTE order for
+     * `indexName` — the `VirtualTable.getIndexComparator` isolation hook, mirroring
+     * `MemoryTable.getIndexComparator`. The isolation layer merges the overlay's pending
+     * rows against this table's index scan by `(indexKey, PK)` sort key and prefers these
+     * over its descriptor-derived fallback, so each column's comparator must reproduce
+     * the order {@link scanIndex} emits in:
+     *   - the column's KEY collation ({@link indexKeyCollations}: index COLLATE, else the
+     *     table column's declared collation, else BINARY) for text;
+     *   - the logical type's `compare` for a semantic-ordering column (its key bytes
+     *     encode through an order-preserving transform — see `storeSemanticKeyTransform`);
+     *   - negated for a DESC column (its key bytes are bit-inverted).
+     * Resolved against the MATERIALIZED schema so a hidden `_uc_*` name resolves too.
+     *
+     * NOTE: for a text column this states the COMPARATOR's order, which is the byte order
+     * only while the collation's key normalizer preserves order (`_isCollationOrderPreserving`
+     * — asserted by the built-ins, opt-in for a custom one; see keyOrderMatchesCollation).
+     * Under an equality-only custom collation the emitted byte order and this comparator can
+     * disagree, misplacing an overlay row within an index-key-equal group. Same exposure the
+     * isolation layer's descriptor fallback carried before this method existed, so nothing
+     * regressed; if a custom equality-only collation on an INDEX column ever ships, gate this
+     * on the assertion (returning undefined declines to the fallback, which is no better —
+     * the real fix is to make the store emit in comparator order or the merge tolerate it).
+     */
+    getIndexComparator(indexName) {
+        const schema = this.materializedSchema;
+        const index = schema.indexes?.find(ix => ix.name.toLowerCase() === indexName.toLowerCase());
+        if (!index)
+            return undefined;
+        const keyCollations = this.indexKeyCollations(index);
+        return index.columns.map((col, i) => {
+            const columnSchema = schema.columns[col.index];
+            const name = keyCollations[i];
+            const collationFunc = name ? this.collationResolver(name) : undefined;
+            const typedComparator = createTypedComparator(columnSchema.logicalType, collationFunc);
+            return col.desc
+                ? (a, b) => -typedComparator(a, b)
+                : typedComparator;
+        });
+    }
+    /**
+     * True when a byte window over the LEADING column of `index` reproduces the order the
+     * residual comparison uses. Delegates to {@link indexLeadingRangeIsOrderSafe} — the SAME
+     * call the range arm of `tryIndexAccessPlan` (store-module-access-plan.ts) makes before
+     * it marks the range filters handled, so the "build a window" and "mark handled"
+     * decisions cannot disagree. The memoized {@link indexKeyCollations} is passed as the
+     * key side, so the predicate judges the bytes this scan actually addresses.
+     */
+    indexRangeIsOrderSafe(index) {
+        return indexLeadingRangeIsOrderSafe(this.db, this.tableSchema.columns, index, this.indexKeyCollations(index));
+    }
+    /**
+     * 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 the leading index column's own key `collation`
+     * ({@link indexKeyCollations}) and 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).
+     */
+    buildIndexRangeBounds(constraints, dir, collation) {
+        const full = buildFullScanBounds();
+        let gte = full.gte;
+        let lt;
+        for (const c of constraints) {
+            if (c.value === undefined || c.value === null)
+                continue;
+            const { gte: lo, lt: hi } = buildIndexPrefixBounds([c.value], this.encodeOptions, [dir], [collation]);
+            const lower = !dir
+                ? (c.op === IndexConstraintOp.GE ? lo : c.op === IndexConstraintOp.GT ? hi : undefined)
+                : (c.op === IndexConstraintOp.LE ? lo : c.op === IndexConstraintOp.LT ? hi : undefined);
+            const upper = !dir
+                ? (c.op === IndexConstraintOp.LE ? hi : c.op === IndexConstraintOp.LT ? lo : undefined)
+                : (c.op === IndexConstraintOp.GE ? hi : c.op === IndexConstraintOp.GT ? lo : undefined);
+            if (lower && compareBytes(lower, gte) > 0)
+                gte = lower;
+            if (upper && (lt === undefined || compareBytes(upper, lt) < 0))
+                lt = upper;
+        }
+        return lt === undefined ? { gte } : { gte, lt };
+    }
+    /**
+     * 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).
+     */
+    async *scanIndex(indexStore, access, filterInfo, multi) {
+        // Re-check each resolved row under the INDEX's per-column collation (see
+        // matchesFilters): the planner dropped the residual based on the index
+        // column's collation, which an explicit index `COLLATE` can make differ from
+        // the table column's declared collation.
+        const indexCollations = multi?.collations
+            ?? this.resolveFilterCollations(filterInfo, this.indexColumnCollations(access.index));
+        for await (const entry of this.iterateEffective(indexStore, access.bounds)) {
+            // NOTE: a legacy index store (written before index values carried the data
+            // key) holds EMPTY values; a zero-length data key is not a row key, so skip
+            // it rather than resolve it to the wrong row. Because the access plan marked
+            // the filter handled and dropped the residual, an indexed query over such a
+            // store returns NOTHING rather than the matching rows — a silent wrong
+            // result, not an error. Backwards compatibility is waived project-wide
+            // (AGENTS.md) and no test provider carries on-disk data, so nothing exercises
+            // this today. If real persisted stores predating this format come into play,
+            // their indexes must be dropped + recreated (or the table rebuilt); the
+            // durable fix is to version-stamp the index store and rebuild on open, or to
+            // fall back to a full scan the first time an empty value is seen.
+            if (entry.value.length === 0)
+                continue;
+            // Cross-window dedup for a multi-seek: a data key an earlier window already
+            // YIELDED is skipped before the data-store read, so a duplicate costs no
+            // extra `get`. The seen-set is only ever ADDED to on a yield (below) — adding
+            // at visit time would let a stale index entry that fails its residual poison
+            // the set and suppress the row's live entry in a later window.
+            const dataKeyHex = multi ? bytesToHex(entry.value) : undefined;
+            if (dataKeyHex !== undefined && multi.seen.has(dataKeyHex))
+                continue;
+            // NOTE: one extra data-store `get` per matched index entry — the row lives
+            // in the data store, not the index (the index value carries only the data
+            // key, no covering payload). Fine now; if index-covered scans ever dominate
+            // a profile, consider storing the serialized row as a covering index value,
+            // at the cost of an index rewrite on EVERY column change (not just indexed
+            // columns) — deliberately not done here.
+            const row = await this.readEffectiveRowByKey(entry.value);
+            if (!row)
+                continue;
+            if (this.matchesFilters(row, filterInfo, indexCollations)
+                || (multi !== undefined && multi.extraTuples.some(fi => this.matchesFilters(row, fi, indexCollations)))) {
+                if (dataKeyHex !== undefined)
+                    multi.seen.add(dataKeyHex);
+                yield row;
+            }
+        }
+    }
+    /**
+     * Fail loudly on a multi-seek FilterInfo this table cannot serve. The plan already
+     * dropped the residual Filter, and {@link matchesFilters} ANDs every pushed
+     * constraint — so falling through to the scan arm would AND N mutually-exclusive
+     * equalities and return zero rows: a silent wrong answer, not a slow one.
+     */
+    multiSeekMalformed(filterInfo, why) {
+        throw new QuereusError(`Malformed multi-seek FilterInfo (idxStr '${filterInfo.idxStr}') on ${this.schemaName}.${this.tableName}: ${why}`, StatusCode.INTERNAL);
+    }
+    /**
+     * Decode a multi-seek FilterInfo into its N seek tuples of width W. Tuple i pairs
+     * `args[i*W … i*W+W-1]` with the same slice of `constraints` (argvIndex runs
+     * 1…N*W in order — see rule-select-access-path's multiSeek emission). A tuple with
+     * a NULL/undefined component is dropped: IN is set membership and a NULL component
+     * matches nothing. The planner pre-reduces literal lists, but a parameter-bound /
+     * mixed-binding list reaches here unreduced, so this skip is the only line of
+     * defense for those.
+     */
+    decodeMultiSeekTuples(spec, filterInfo) {
+        const seekWidth = Number.parseInt(spec.params.get('seekWidth') ?? '1', 10);
+        const inCount = Number.parseInt(spec.params.get('inCount') ?? '0', 10);
+        if (!Number.isInteger(seekWidth) || seekWidth < 1) {
+            this.multiSeekMalformed(filterInfo, `seekWidth=${spec.params.get('seekWidth')}`);
+        }
+        if (!Number.isInteger(inCount) || inCount < 1) {
+            this.multiSeekMalformed(filterInfo, `inCount=${spec.params.get('inCount')}`);
+        }
+        const constraints = filterInfo.constraints ?? [];
+        if (constraints.length < inCount * seekWidth) {
+            this.multiSeekMalformed(filterInfo, `${constraints.length} constraints for ${inCount}×${seekWidth} seek keys`);
+        }
+        if (filterInfo.args.length < inCount * seekWidth) {
+            this.multiSeekMalformed(filterInfo, `${filterInfo.args.length} args for ${inCount}×${seekWidth} seek keys`);
+        }
+        const tuples = [];
+        for (let t = 0; t < inCount; t++) {
+            const entries = constraints.slice(t * seekWidth, (t + 1) * seekWidth);
+            if (entries.some(e => e.constraint.op !== IndexConstraintOp.EQ || e.argvIndex <= 0)) {
+                this.multiSeekMalformed(filterInfo, `seek tuple ${t} carries a non-EQ or unbound constraint`);
+            }
+            const values = entries.map(e => filterInfo.args[e.argvIndex - 1]);
+            if (values.some(v => v === null || v === undefined))
+                continue;
+            tuples.push({ entries, values });
+        }
+        return { tuples, seekWidth };
+    }
+    /**
+     * Order one tuple's values to match `keyCols` (the leading index columns, or the
+     * PK definition) using each constraint entry's column. The plan's seek columns and
+     * the constraint list must agree; a tuple that does not cover exactly those
+     * columns is malformed.
+     */
+    orderTupleValues(tuple, keyCols, filterInfo) {
+        const byCol = new Map();
+        tuple.entries.forEach((e, i) => byCol.set(e.constraint.iColumn, tuple.values[i]));
+        if (byCol.size !== keyCols.length) {
+            this.multiSeekMalformed(filterInfo, `seek tuple covers ${byCol.size} columns, expected ${keyCols.length}`);
+        }
+        return keyCols.map(colIdx => {
+            if (!byCol.has(colIdx))
+                this.multiSeekMalformed(filterInfo, `seek tuple missing column ${colIdx}`);
+            return byCol.get(colIdx);
+        });
+    }
+    /**
+     * Serve a multi-seek (`plan=5`) FilterInfo: one point window per distinct
+     * IN-list tuple, scanned in ascending encoded-key order.
+     *
+     * Window order is not cosmetic. Encoded-byte order IS index-key order (per-column
+     * DESC inversion is baked into the bytes), and the isolation overlay merges an
+     * index scan with its pending rows by (indexKey, PK) — an out-of-order underlying
+     * stream misplaces overlay rows in the output. Two overlap hazards are folded
+     * away before scanning:
+     *   - Tuples whose encoded prefix byte-matches (duplicate bound parameters, or
+     *     case variants under a NOCASE key collation C) share ONE window, each kept
+     *     as a residual alternative — see {@link MultiSeekWindowContext}.
+     *   - A window with no finite upper bound (all-0xff prefix — see
+     *     buildIndexPrefixBounds) contains every later-sorting window outright (any
+     *     key ≥ an all-0xff prefix necessarily starts with it), so those windows fold
+     *     into it instead of re-scanning an overlapping range out of order.
+     *
+     * Emission is lazy per window — `… in (…) limit 1` stops after the first yielded
+     * row without materializing the remaining windows. Each window goes through
+     * {@link scanIndex} → {@link iterateEffective}, so read-your-own-writes and the
+     * stale-entry / deleted-row defenses hold per seek key.
+     */
+    async *scanMultiSeek(spec, filterInfo) {
+        const { tuples, seekWidth } = this.decodeMultiSeekTuples(spec, filterInfo);
+        if (spec.indexName === '_primary_') {
+            yield* this.scanMultiSeekPrimary(tuples, seekWidth, filterInfo);
+            return;
+        }
+        const index = this.resolveIndexFromIdxStr(filterInfo.idxStr);
+        if (!index)
+            this.multiSeekMalformed(filterInfo, `no index named '${spec.indexName}'`);
+        const indexCols = index.columns.map(c => c.index);
+        const indexDirections = index.columns.map(c => !!c.desc);
+        if (seekWidth > indexCols.length) {
+            this.multiSeekMalformed(filterInfo, `seekWidth ${seekWidth} exceeds ${index.name}'s ${indexCols.length} columns`);
+        }
+        const seekCols = indexCols.slice(0, seekWidth);
+        // The encoded byte windows below carry no residual able to resurrect a
+        // skipped row, so a seek column whose byte equality under-fetches the type's
+        // equality (TIMESPAN, JSON — see pkHasSemanticOrderingMember) cannot be
+        // multi-seeked. `tryIndexAccessPlan` (store-module-access-plan.ts) declines such plans; one
+        // arriving anyway is malformed.
+        if (seekCols.some(colIdx => hasSemanticOrdering(this.tableSchema.columns[colIdx]?.logicalType))) {
+            this.multiSeekMalformed(filterInfo, 'semantic-ordering seek column');
+        }
+        // Same rationale for the collation gate: the merged windows drop any tuple the
+        // bytes exclude, so a prefix whose key collation differs from the one the residual
+        // re-compares under would under-fetch with nothing left to repair it.
+        // `tryIndexAccessPlan` declines such plans through this same predicate; one
+        // arriving anyway is malformed. {@link analyzeIndexAccess} makes the point-window
+        // twin of this check.
+        const indexKeyCollations = this.indexKeyCollations(index);
+        if (!indexPrefixSeekIsCollationExact(this.tableSchema.columns, index, indexKeyCollations, seekWidth)) {
+            this.multiSeekMalformed(filterInfo, 'index key collation differs from the comparison collation');
+        }
+        // One window per distinct encoded tuple prefix (each column under its own key
+        // collation C — see indexKeyCollations); C-equal tuples merge into one window,
+        // each kept as a residual alternative.
+        const seekCollations = indexKeyCollations.slice(0, seekWidth);
+        const windows = new Map();
+        for (const tuple of tuples) {
+            const ordered = this.orderTupleValues(tuple, seekCols, filterInfo);
+            const bounds = buildIndexPrefixBounds(ordered, this.encodeOptions, indexDirections.slice(0, seekWidth), seekCollations);
+            const hex = bytesToHex(bounds.gte);
+            const info = { ...filterInfo, constraints: tuple.entries };
+            const existing = windows.get(hex);
+            if (existing)
+                existing.infos.push(info);
+            else
+                windows.set(hex, { bounds, infos: [info] });
+        }
+        if (windows.size === 0)
+            return; // every tuple had a NULL component — nothing matches
+        const sorted = [...windows.values()].sort((a, b) => compareBytes(a.bounds.gte, b.bounds.gte));
+        const disjoint = [];
+        for (const w of sorted) {
+            const last = disjoint[disjoint.length - 1];
+            if (last && last.bounds.lt === undefined)
+                last.infos.push(...w.infos);
+            else
+                disjoint.push(w);
+        }
+        const indexStore = await this.ensureIndexStore(index.name);
+        // Identical for every window (resolveFilterCollations dedups by column), so
+        // resolve once and thread it through.
+        const collations = this.resolveFilterCollations(filterInfo, this.indexColumnCollations(index));
+        const seen = new Set();
+        for (const w of disjoint) {
+            yield* this.scanIndex(indexStore, { index, type: 'point', bounds: w.bounds }, w.infos[0], { seen, collations, extraTuples: w.infos.slice(1) });
+        }
+    }
+    /**
+     * Multi-seek over the PRIMARY key: each tuple is a full PK, resolved by a point
+     * read in ascending encoded-data-key order (the table's native emission order).
+     *
+     * NOT reachable from this module's own plans today: `computeBestAccessPlan` (store-module-access-plan.ts)
+     * claims IN-list filters only for secondary indexes (see its EQ_OPS vs EQ_OR_IN_OPS
+     * split and tickets/backlog/feat-store-pk-in-list-multiseek). The branch exists so
+     * a `_primary_` multi-seek arriving from a future plan gets a correct answer rather
+     * than the scan arm's silent zero rows, and it is what PK-IN enablement will build on.
+     */
+    async *scanMultiSeekPrimary(tuples, seekWidth, filterInfo) {
+        const pkColumns = this.tableSchema.primaryKeyDefinition.map(pk => pk.index);
+        if (pkColumns.length === 0) {
+            this.multiSeekMalformed(filterInfo, 'primary-key multi-seek on a table with no primary key');
+        }
+        if (seekWidth !== pkColumns.length) {
+            this.multiSeekMalformed(filterInfo, `seekWidth ${seekWidth} does not cover the ${pkColumns.length}-column primary key`);
+        }
+        // Mirrors analyzePKAccess's conservative decline of the point arm for such PKs
+        // (see pkHasSemanticOrderingMember); with the residual gone there is no scan to
+        // degrade to, so fail loudly rather than risk an under-fetch.
+        if (this.pkHasSemanticOrderingMember()) {
+            this.multiSeekMalformed(filterInfo, 'semantic-ordering primary-key member');
+        }
+        // Dedup by encoded data key (collapses K-equal tuples), keeping every merged
+        // tuple's residual as an alternative — same rationale as the index branch.
+        const points = new Map();
+        for (const tuple of tuples) {
+            const ordered = this.orderTupleValues(tuple, pkColumns, filterInfo);
+            const key = this.encodeDataKey(ordered);
+            const hex = bytesToHex(key);
+            const info = { ...filterInfo, constraints: tuple.entries };
+            const existing = points.get(hex);
+            if (existing)
+                existing.infos.push(info);
+            else
+                points.set(hex, { key, infos: [info] });
+        }
+        const collations = this.resolveFilterCollations(filterInfo);
+        for (const p of [...points.values()].sort((a, b) => compareBytes(a.key, b.key))) {
+            const row = await this.readEffectiveRowByKey(p.key);
+            if (row && p.infos.some(fi => this.matchesFilters(row, fi, collations))) {
+                yield 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.
+     */
+    matchesFilters(row, filterInfo, collations) {
+        if (!filterInfo.constraints || filterInfo.constraints.length === 0) {
+            return true;
+        }
+        for (const constraintEntry of filterInfo.constraints) {
+            const { constraint, argvIndex } = constraintEntry;
+            if (constraint.iColumn < 0 || argvIndex <= 0) {
+                continue;
+            }
+            const rowValue = row[constraint.iColumn];
+            const filterValue = filterInfo.args[argvIndex - 1];
+            const collation = collations.get(constraint.iColumn) ?? BINARY_COLLATION;
+            // A semantic-ordering column (TIMESPAN, JSON) must filter under the type's
+            // compare — the same order the engine's operators and Sort use — or a pushed
+            // `d > 'PT90M'` would text-compare and drop rows the predicate admits. The
+            // comparator is built per row only on this rare column kind; if a profile
+            // ever shows it, resolve it once per scan alongside the collations.
+            const logicalType = this.tableSchema.columns[constraint.iColumn]?.logicalType;
+            const compare = hasSemanticOrdering(logicalType)
+                ? createTypedComparator(logicalType, collation)
+                : undefined;
+            if (!this.compareValues(rowValue, constraint.op, filterValue, collation, compare)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 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 `StoreTableConstraints`'
+     * 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`.
+     */
+    resolveFilterCollations(filterInfo, indexCollationNames) {
+        const resolved = new Map();
+        if (!filterInfo.constraints)
+            return resolved;
+        for (const { constraint, argvIndex } of filterInfo.constraints) {
+            if (constraint.iColumn < 0 || argvIndex <= 0)
+                continue;
+            if (resolved.has(constraint.iColumn))
+                continue;
+            const name = indexCollationNames?.has(constraint.iColumn)
+                ? indexCollationNames.get(constraint.iColumn)
+                : this.tableSchema.columns[constraint.iColumn]?.collation;
+            resolved.set(constraint.iColumn, name ? this.collationResolver(name) : BINARY_COLLATION);
+        }
+        return resolved;
+    }
+    /**
+     * 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.
+     */
+    indexColumnCollations(index) {
+        const cols = this.tableSchema.columns;
+        const map = new Map();
+        for (const c of index.columns) {
+            map.set(c.index, c.collation ?? cols[c.index]?.collation);
+        }
+        return map;
+    }
+    /**
+     * 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`).
+     */
+    compareValues(a, op, b, collationFunc, semanticCompare) {
+        if (a === null || b === null) {
+            return op === IndexConstraintOp.EQ ? a === b : false;
+        }
+        const cmp = semanticCompare ? semanticCompare(a, b) : compareSqlValuesFast(a, b, collationFunc);
+        switch (op) {
+            case IndexConstraintOp.EQ: return cmp === 0;
+            case IndexConstraintOp.NE: return cmp !== 0;
+            case IndexConstraintOp.LT: return cmp < 0;
+            case IndexConstraintOp.LE: return cmp <= 0;
+            case IndexConstraintOp.GT: return cmp > 0;
+            case IndexConstraintOp.GE: return cmp >= 0;
+            default: return true;
+        }
+    }
+}
+//# sourceMappingURL=store-table-scan.js.map