@quereus/store 4.11.0 → 4.12.0

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

@@ -11,8 +11,44 @@ import { IndexConstraintOp, QuereusError, StatusCode, compareSqlValuesFast, crea
 import { bytesToHex, compareBytes } from './bytes.js';
 import { buildIndexPrefixBounds, buildFullScanBounds, } from './key-builder.js';
 import { deserializeRow, } from './serialization.js';
-import { indexLeadingRangeIsOrderSafe, indexPrefixSeekIsCollationExact, pkOrderPreservingPrefixLength, resolveIndexKeyCollations, resolveIndexKeyTransforms, semanticProbeIsKeyFaithful } from './pk-key-resolution.js';
+import { indexPrefixSeekIsCollationExact, indexRangeAtPositionIsOrderSafe, pkOrderPreservingPrefixLength, resolveIndexKeyCollations, resolveIndexKeyTransforms, semanticProbeIsKeyFaithful } from './pk-key-resolution.js';
 import { StoreTableBase } from './store-table-base.js';
+/**
+ * The pushed constraint ops that bound a byte window from one side. The scan-side twin of
+ * `store-module-access-plan.ts`'s `RANGE_OPS` (which names the same four in the planner's
+ * `PredicateConstraint` spelling), shared by all three window builders below so a new
+ * bound operator cannot reach one arm and not the others.
+ */
+const RANGE_CONSTRAINT_OPS = [
+    IndexConstraintOp.LT,
+    IndexConstraintOp.LE,
+    IndexConstraintOp.GT,
+    IndexConstraintOp.GE,
+];
+/**
+ * Index entries per row-resolution batch: the scan arms below collect up to this many
+ * surviving index entries (or multi-seek point keys) and resolve them with ONE
+ * {@link StoreTableBase.readEffectiveRowsByKeys} call, so an indexed read of N rows
+ * costs on the order of N / 256 store round trips instead of N serialized point reads
+ * (on IndexedDB, one readonly transaction instead of N). This is the bound
+ * {@link KVStore.getMany}'s "bounded by the caller" note refers to.
+ *
+ * 256 matches the iterate pager's default page (`paged-iterate.ts` DEFAULT_BATCH_SIZE)
+ * and makes the same trade that pager already makes and the {@link KVStore.iterate}
+ * contract documents: a little early-termination cost for throughput — `limit 1`
+ * collects one batch rather than one row — while keeping peak memory independent of
+ * the range size.
+ *
+ * NOTE: that early-termination cost is bounded but not free — `limit 1` deserializes up
+ * to 256 rows to yield one, and holds them all at once. It is charged against ROUND
+ * TRIPS, which is what dominates on the backends this exists for (the index side already
+ * pages 256 entries per read, so a stopped scan costs one data round trip either way),
+ * so it is accepted as-is. Revisit if a `limit`-shaped query (a correlated `EXISTS`, a
+ * semi-join probe) shows up in a profile as row-decode or allocation cost: the fix is a
+ * SMALLER FIRST batch that ramps toward this bound, which keeps a drain's round-trip
+ * count within a log factor while making a stopped scan cost ~one row again.
+ */
+export const ROW_RESOLUTION_BATCH = 256;
 /**
  * Read-path layer of the generic KVStore-backed virtual table.
  *
@@ -146,8 +182,7 @@ export class StoreTableScan extends StoreTableBase {
         }
         // 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)) || [];
+        const rangeConstraints = filterInfo.constraints?.filter(c => c.constraint.iColumn === firstPkCol && RANGE_CONSTRAINT_OPS.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.
@@ -286,24 +321,32 @@ export class StoreTableScan extends StoreTableBase {
      * 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.
+     * Three window shapes, in the order they are tried:
+     *
+     *  - a contiguous leading-prefix EQ plus a LT/LE/GT/GE bound on the NEXT index column
+     *    (the `prefixRangeSeek` / `plan=7` plan) — one `range` window covering just the
+     *    bounded slice INSIDE the prefix;
+     *  - a contiguous leading-prefix EQ alone → 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 → a `range` window.
+     *
+     * Returns null when none applies or when the index is unresolved.
+     * {@link matchesFilters} stays the authoritative row filter, so the window need only be
+     * a SUPERSET — which is why every degraded path below WIDENS (a prefix-range that
+     * cannot narrow falls back to the prefix window, a prefix that cannot encode a member
+     * stops short) rather than declining outright.
      *
      * 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.
+     * {@link indexPrefixSeekIsCollationExact} decides; a RANGE window additionally equates
+     * memcmp of the key bytes with the residual's comparison ORDER at the bounded column's
+     * position, which {@link indexRangeIsOrderSafe} decides. `tryIndexAccessPlan`
+     * (store-module-access-plan.ts) consults the SAME two predicates, at the same positions,
+     * before claiming the filters handled, so the two decisions cannot disagree. An EQ-prefix
+     * failure returns null and the caller full-scans, where the residual is authoritative.
      */
     analyzeIndexAccess(filterInfo) {
         const index = this.resolveIndexFromIdxStr(filterInfo.idxStr);
@@ -338,22 +381,96 @@ export class StoreTableScan extends StoreTableBase {
             if (!indexPrefixSeekIsCollationExact(this.tableSchema.columns, index, indexCollations, eqValues.length)) {
                 return null;
             }
+            // Prefix-equality + trailing-range. `prefixLen` comes from the idxStr rather
+            // than being re-inferred from the constraint list, so a plan that meant a
+            // different prefix length is caught instead of silently windowing the wrong
+            // columns. `prefixLen > eqValues.length` means an unfaithful semantic probe cut
+            // the prefix short above; the bound then belongs to a column the window no
+            // longer reaches, so it is dropped and the shorter prefix window (a strict
+            // superset) serves — {@link matchesFilters} still applies it.
+            const prefixLen = this.prefixRangeSeekLength(filterInfo, index);
+            if (prefixLen !== null && prefixLen <= eqValues.length) {
+                const bounds = this.buildPrefixRangeWindow(filterInfo, index, eqValues.slice(0, prefixLen));
+                if (bounds)
+                    return { index, type: 'range', bounds };
+            }
             const bounds = buildIndexPrefixBounds(eqValues, this.encodeOptions, indexDirections.slice(0, eqValues.length), indexCollations.slice(0, eqValues.length), this.indexKeyTransforms(index).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], this.tableSchema.columns[leadingCol]?.logicalType, this.indexKeyTransforms(index)[0]);
+        const rangeConstraints = this.rangeConstraintsOn(filterInfo, leadingCol);
+        if (rangeConstraints.length > 0 && this.indexRangeIsOrderSafe(index, 0)) {
+            const bounds = this.buildIndexRangeBounds([], rangeConstraints, indexDirections.slice(0, 1), indexCollations.slice(0, 1), this.tableSchema.columns[leadingCol]?.logicalType, this.indexKeyTransforms(index).slice(0, 1));
             return { index, type: 'range', bounds };
         }
         return null;
     }
+    /**
+     * The prefix length a `prefixRangeSeek` (`plan=7`) FilterInfo declares, or null when
+     * this FilterInfo is not one.
+     *
+     * Honoring the plan's own `prefixLen` — rather than re-deriving it from the constraint
+     * list — is what makes a plan/scan disagreement LOUD: a value outside `1 …
+     * index.columns.length - 1` cannot describe a window over this index, and the plan
+     * already dropped the residual for the filters it claimed, so guessing a length would
+     * silently address the wrong columns.
+     */
+    prefixRangeSeekLength(filterInfo, index) {
+        const spec = decodeIdxStr(filterInfo.idxStr);
+        if (!spec || planKindFromCode(spec.plan) !== 'prefixRangeSeek')
+            return null;
+        const raw = spec.params.get('prefixLen');
+        const prefixLen = Number.parseInt(raw ?? '', 10);
+        if (!Number.isInteger(prefixLen) || prefixLen < 1 || prefixLen >= index.columns.length) {
+            this.malformedFilterInfo('prefix-range seek', filterInfo, `prefixLen=${raw} against ${index.name}'s ${index.columns.length} columns`);
+        }
+        return prefixLen;
+    }
+    /** The pushed LT/LE/GT/GE constraints on `columnIndex`, paired with their bound values. */
+    rangeConstraintsOn(filterInfo, columnIndex) {
+        return (filterInfo.constraints ?? [])
+            .filter(c => c.constraint.iColumn === columnIndex && RANGE_CONSTRAINT_OPS.includes(c.constraint.op))
+            .map(c => ({
+            op: c.constraint.op,
+            value: c.argvIndex > 0 ? filterInfo.args[c.argvIndex - 1] : undefined,
+        }));
+    }
+    /**
+     * The narrowed window for a prefix-equality + trailing-range seek: the equality prefix
+     * bytes, further bounded by the LT/LE/GT/GE constraints on the index column right after
+     * it. Null when the trailing bound cannot be used, in which case the caller falls back
+     * to the plain prefix window — a strict SUPERSET, so the answer is unchanged and only
+     * the narrowing is lost. Two reasons for that:
+     *
+     *  - the trailing column's key bytes do not reproduce its residual comparator's ORDER
+     *    ({@link indexRangeIsOrderSafe}) — `tryIndexAccessPlan` degrades to the plain prefix
+     *    seek through the same predicate, so this is the matching scan-side move rather than
+     *    a disagreement;
+     *  - no bound constraint survived on that column at all (nothing to narrow with).
+     */
+    buildPrefixRangeWindow(filterInfo, index, prefixValues) {
+        const position = prefixValues.length;
+        const trailingCol = index.columns[position]?.index;
+        if (trailingCol === undefined)
+            return null;
+        if (!this.indexRangeIsOrderSafe(index, position))
+            return null;
+        // NOTE: a `plan=7` with NO bound on the trailing column is as structurally impossible
+        // as a bad `prefixLen` — `rule-select-access-path` only emits the plan once it has
+        // found a lower or upper bound, and `seekColumns` is advertised in index-column
+        // order, so `index.columns[prefixLen]` IS the column the rule bounded. It stays SOFT
+        // anyway because the two impossibilities fail differently: a wrong `prefixLen` would
+        // address the wrong columns (an under-fetch, a wrong answer), while a missing bound
+        // only fails to narrow. If a plan source ever does hand this over, the symptom is a
+        // slow query, not a wrong one — make it loud only if that silence starts hiding a
+        // real disagreement.
+        const rangeConstraints = this.rangeConstraintsOn(filterInfo, trailingCol);
+        if (rangeConstraints.length === 0)
+            return null;
+        const width = position + 1;
+        return this.buildIndexRangeBounds(prefixValues, rangeConstraints, index.columns.slice(0, width).map(c => !!c.desc), this.indexKeyCollations(index).slice(0, width), this.tableSchema.columns[trailingCol]?.logicalType, this.indexKeyTransforms(index).slice(0, width));
+    }
     /**
      * Lazy cache behind {@link indexKeyCollations}: one resolved array per index-schema
      * object, invalidated when the column array it was resolved against is replaced (an
@@ -443,25 +560,37 @@ export class StoreTableScan extends StoreTableBase {
         });
     }
     /**
-     * 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.
+     * True when a byte window bounded on index column `position` reproduces the order the
+     * residual comparison uses there. Delegates to {@link indexRangeAtPositionIsOrderSafe} —
+     * the SAME call `tryIndexAccessPlan` (store-module-access-plan.ts) makes, at the same
+     * position, 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.
+     *
+     * `position` is 0 for a standalone leading-column range and the prefix length for a
+     * prefix-equality + trailing-range window.
      */
-    indexRangeIsOrderSafe(index) {
-        return indexLeadingRangeIsOrderSafe(this.db, this.tableSchema.columns, index, this.indexKeyCollations(index));
+    indexRangeIsOrderSafe(index, position) {
+        return indexRangeAtPositionIsOrderSafe(this.db, this.tableSchema.columns, index, this.indexKeyCollations(index), position);
     }
     /**
-     * Convert leading-index-column LT/LE/GT/GE constraints into one encoded-byte
-     * `gte`/`lt` window — the secondary-index analogue of {@link buildPKRangeBounds}.
+     * Convert LT/LE/GT/GE constraints on ONE index column into a single encoded-byte
+     * `gte`/`lt` window, optionally nested inside a fixed equality prefix — 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:
+     * The bounded column sits at position `prefixValues.length`; `directions`,
+     * `collations` and `transforms` are the index's own per-column arrays sliced to cover
+     * the prefix AND that column. An empty `prefixValues` is the standalone leading-column
+     * range; a non-empty one is the trailing bound of a `prefixRangeSeek`.
+     *
+     * Each bound value is encoded BEHIND the prefix, under the bounded column's own key
+     * collation ({@link indexKeyCollations}) and DESC direction — exactly as
+     * {@link buildIndexKey} encodes that column — via {@link buildIndexPrefixBounds},
+     * giving the byte region `[lo, hi)` whose prefix columns equal `prefixValues` and whose
+     * bounded 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 — driven by the BOUNDED
+     * column's direction alone, since a DESC prefix column merely inverts bytes *inside* a
+     * prefix that stays fixed:
      *
      *   | op | ASC      | DESC     |
      *   |----|----------|----------|
@@ -470,29 +599,34 @@ export class StoreTableScan extends StoreTableBase {
      *   | 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).
-     * A bound over a semantic-ordering leading column (`logicalType`) whose VALUE has
-     * no faithful byte position ({@link semanticProbeIsKeyFaithful}) is skipped the
-     * same way — a dropped RANGE bound only widens the window, and matchesFilters
-     * reproduces the predicate under the type's compare; see the widen-vs-decline
-     * note on {@link buildPKRangeBounds}. `transform` is the leading column's key
-     * value transform ({@link indexKeyTransforms}), so a surviving bound addresses
-     * the same transformed bytes the index store holds.
+     * Both sides START at the prefix's own window (`[P, incr(P))`, or unbounded for an
+     * empty prefix) and are then tightened: keep the MAX lower and MIN upper across
+     * constraints. So every degraded path lands back on the prefix window, never wider:
+     * an `undefined` upper (an `hi` whose increment overflowed all-0xff), a NULL/missing
+     * bound value (the planner never pushes `= NULL`, and a range op against NULL rejects
+     * every row in matchesFilters), and a bound over a semantic-ordering column
+     * (`logicalType`) whose VALUE has no faithful byte position
+     * ({@link semanticProbeIsKeyFaithful}) are all simply skipped — a dropped RANGE bound
+     * only widens the window, and matchesFilters reproduces the predicate under the type's
+     * compare; see the widen-vs-decline note on {@link buildPKRangeBounds}. `transforms`
+     * carry each column's key value transform ({@link indexKeyTransforms}), so a surviving
+     * bound addresses the same transformed bytes the index store holds.
      */
-    buildIndexRangeBounds(constraints, dir, collation, logicalType, transform) {
-        const full = buildFullScanBounds();
-        let gte = full.gte;
-        let lt;
+    buildIndexRangeBounds(prefixValues, constraints, directions, collations, logicalType, transforms) {
+        const position = prefixValues.length;
+        const dir = directions[position];
+        // The prefix's own window is the fallback for BOTH sides: `buildIndexPrefixBounds`
+        // answers full-scan bounds for an empty prefix, reproducing the leading-column arm.
+        const base = buildIndexPrefixBounds([...prefixValues], this.encodeOptions, directions.slice(0, position), collations.slice(0, position), transforms.slice(0, position));
+        let gte = base.gte;
+        let lt = base.lt;
         for (const c of constraints) {
             if (c.value === undefined || c.value === null)
                 continue;
             // Widen, don't decline — see the doc comment above.
             if (!semanticProbeIsKeyFaithful(logicalType, c.value))
                 continue;
-            const { gte: lo, lt: hi } = buildIndexPrefixBounds([c.value], this.encodeOptions, [dir], [collation], [transform]);
+            const { gte: lo, lt: hi } = buildIndexPrefixBounds([...prefixValues, c.value], this.encodeOptions, directions, collations, transforms);
             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);
@@ -510,27 +644,36 @@ export class StoreTableScan extends StoreTableBase {
      * 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).
+     * One window of the producer/consumer pair below: {@link produceIndexEntries}
+     * walks the window's index entries and {@link resolveIndexEntries} resolves them
+     * to rows in {@link ROW_RESOLUTION_BATCH}-bounded batches — one
+     * {@link StoreTableBase.readEffectiveRowsByKeys} round trip per batch instead of
+     * one awaited point read per entry. A multi-seek runs the SAME consumer over the
+     * concatenation of every window's producer instead of calling this method — see
+     * {@link scanMultiSeek}.
      */
-    async *scanIndex(indexStore, access, filterInfo, multi) {
+    async *scanIndex(indexStore, access, filterInfo) {
         // 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)) {
+        const indexCollations = this.resolveFilterCollations(filterInfo, this.indexColumnCollations(access.index));
+        yield* this.resolveIndexEntries(this.produceIndexEntries(indexStore, access.bounds, [filterInfo]), indexCollations);
+    }
+    /**
+     * Producer half of the index-scan pair: walk one byte window's index entries —
+     * {@link iterateEffective} yields the committed 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) — and yield, per surviving entry, its data
+     * key plus the FilterInfos a resolved row may match. Entries stay in visit order
+     * end to end, so index-key order is preserved through the batching consumer.
+     *
+     * Only the defenses that need nothing but the entry itself run here, BEFORE the
+     * row read; everything row-dependent lives in {@link resolveRowBatch}.
+     */
+    async *produceIndexEntries(indexStore, bounds, infos, seen) {
+        for await (const entry of this.iterateEffective(indexStore, 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
@@ -544,31 +687,97 @@ export class StoreTableScan extends StoreTableBase {
             // 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
+            // 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);
+            // extra point read. This is only a PRE-check — a duplicate inside one
+            // not-yet-resolved batch is invisible to it and is caught by
+            // {@link resolveRowBatch}'s post-read re-check. The seen-set is only ever
+            // ADDED to on a yield (there) — 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.
+            let dataKeyHex;
+            if (seen) {
+                dataKeyHex = bytesToHex(entry.value);
+                if (seen.has(dataKeyHex))
+                    continue;
+            }
+            yield { dataKey: entry.value, dataKeyHex, infos };
+        }
+    }
+    /**
+     * Consumer half of the index-scan pair: collect up to {@link ROW_RESOLUTION_BATCH}
+     * produced entries and resolve each batch through {@link resolveRowBatch} — one
+     * store round trip per batch. Batching changes the round-trip count, never the row
+     * set or its order: batches are resolved and yielded in entry order.
+     *
+     * Early termination: a downstream `break` mid-batch finishes this generator, whose
+     * `for await` closes `entries` — and the iterate cursor under it — on the way out;
+     * no further batch is collected or read.
+     */
+    async *resolveIndexEntries(entries, collations, seen) {
+        let batch = [];
+        for await (const entry of entries) {
+            batch.push(entry);
+            if (batch.length >= ROW_RESOLUTION_BATCH) {
+                yield* this.resolveRowBatch(batch, collations, seen);
+                batch = [];
+            }
+        }
+        if (batch.length > 0) {
+            yield* this.resolveRowBatch(batch, collations, seen);
+        }
+    }
+    /**
+     * Resolve one bounded batch of index entries to rows — a single
+     * {@link StoreTableBase.readEffectiveRowsByKeys} call (which applies this
+     * transaction's pending deletes/puts BEFORE touching the committed store; the
+     * precedence is not re-implemented here) — then run the row-dependent defenses in
+     * entry order, 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 cannot shift later positions (the read answers positionally);
+     *  - the multi-seek `seen` set is RE-checked after the read: the producer's
+     *    pre-check ran before this batch was collected, so two entries at one data key
+     *    inside a single batch (a stale index entry) are only caught here — without
+     *    the re-check the row would yield twice;
+     *  - a row is accepted when it matches ANY of the entry's FilterInfos (the byte
+     *    window is only a superset, and a stale entry whose indexed column no longer
+     *    matches is dropped), and `seen` is added to on yield ALONE — a stale entry
+     *    that fails its residual must not suppress the row's live entry later.
+     *
+     * NOTE: still one data-store point read 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); batching collapses the reads' round trips, not their count.
+     * 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.
+     */
+    async *resolveRowBatch(batch, collations, seen) {
+        const rows = await this.readEffectiveRowsByKeys(batch.map(e => e.dataKey));
+        for (let i = 0; i < batch.length; i++) {
+            const row = rows[i];
             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);
+            const { dataKeyHex, infos } = batch[i];
+            if (seen && dataKeyHex !== undefined && seen.has(dataKeyHex))
+                continue;
+            if (infos.some(fi => this.matchesFilters(row, fi, collations))) {
+                if (seen && dataKeyHex !== undefined)
+                    seen.add(dataKeyHex);
                 yield row;
             }
         }
     }
+    /**
+     * Fail loudly on a structurally impossible FilterInfo — one whose own idxStr describes
+     * an access this table's schema cannot express. Not a soundness fallback: everything
+     * that is merely UNSERVEABLE degrades to a wider window plus the {@link matchesFilters}
+     * residual instead of raising. `kind` names the plan shape for the message.
+     */
+    malformedFilterInfo(kind, filterInfo, why) {
+        throw new QuereusError(`Malformed ${kind} FilterInfo (idxStr '${filterInfo.idxStr}') on ${this.schemaName}.${this.tableName}: ${why}`, StatusCode.INTERNAL);
+    }
     /**
      * Fail loudly on a multi-seek FilterInfo this table cannot serve. The plan already
      * dropped the residual Filter, and {@link matchesFilters} ANDs every pushed
@@ -576,7 +785,7 @@ export class StoreTableScan extends StoreTableBase {
      * 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);
+        this.malformedFilterInfo('multi-seek', filterInfo, why);
     }
     /**
      * Decode a multi-seek FilterInfo into its N seek tuples of width W. Tuple i pairs
@@ -645,16 +854,20 @@ export class StoreTableScan extends StoreTableBase {
      * 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}.
+     *     as a residual alternative — see {@link PendingIndexEntry}.
      *   - 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.
+     * Emission is lazy and batched ACROSS windows: every window's
+     * {@link produceIndexEntries} feeds ONE {@link resolveIndexEntries} consumer, whose
+     * batches are bounded by ENTRY count, not window count — so a hundred single-row
+     * windows collapse into a single row-resolution round trip, and
+     * `… in (…) limit 1` materializes at most one {@link ROW_RESOLUTION_BATCH} batch
+     * rather than every window. Each window's entries still come from
+     * {@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);
@@ -726,20 +939,45 @@ export class StoreTableScan extends StoreTableBase {
         // Identical for every window (resolveFilterCollations dedups by column), so
         // resolve once and thread it through.
         const collations = this.resolveFilterCollations(filterInfo, this.indexColumnCollations(index));
+        // Data-key hexes already YIELDED, across ALL windows — the multi-seek dedup set
+        // (see produceIndexEntries / resolveRowBatch for the pre-check / add-on-yield
+        // split). NOTE: holds one hex string per row the multi-seek yields, for the
+        // whole seek — the only unbounded allocation on this path. Windows are
+        // byte-disjoint, so the only real duplicate source is a stale index entry; if a
+        // large-result `IN` ever shows up as a memory problem, the set can be scoped
+        // per window (or dropped for a consistent store).
         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) });
+        // ONE consumer over the concatenation of every window's producer: the windows
+        // are sorted disjoint by encoded key, so the concatenation is already the
+        // emission order, and bounding batches by entry count gives the cross-window
+        // collapse (a hundred single-row windows become one round trip).
+        yield* this.resolveIndexEntries(this.produceMultiSeekEntries(indexStore, disjoint, seen), collations, seen);
+    }
+    /**
+     * Concatenate the disjoint multi-seek windows' producers, in window (byte) order.
+     * Each entry carries its window's full FilterInfo list — the primary tuple plus
+     * the byte-equal merged alternatives — so acceptance stays per row, in order (see
+     * {@link PendingIndexEntry}).
+     */
+    async *produceMultiSeekEntries(indexStore, windows, seen) {
+        for (const w of windows) {
+            yield* this.produceIndexEntries(indexStore, w.bounds, w.infos, seen);
         }
     }
     /**
      * 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.
+     * Reached from `computeBestAccessPlan`'s primary-key multi-seek arm
+     * (store-module-access-plan.ts), which claims a whole-primary-key `IN` — literal list
+     * or runtime-valued set — through `EQ_OR_IN_OPS` and advertises `_primary_` with every
+     * PK column as its seek columns. That arm declines exactly the two shapes the
+     * {@link multiSeekMalformed} throws below assert against (over the seek cap, and a
+     * semantic-ordering PK member), so a throw here means the plan and the scan disagreed.
+     *
+     * The ascending-encoded-key emission order is a contract, not an implementation
+     * detail: the isolation layer merges this stream with its overlay by primary key
+     * (`bug-isolation-multiseek-merge-order`), and the arm advertises PK ordering off it.
      */
     async *scanMultiSeekPrimary(tuples, seekWidth, filterInfo) {
         const pkColumns = this.tableSchema.primaryKeyDefinition.map(pk => pk.index);
@@ -772,10 +1010,20 @@ export class StoreTableScan extends StoreTableBase {
                 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;
+        const sorted = [...points.values()].sort((a, b) => compareBytes(a.key, b.key));
+        // Bounded batches over the sorted, deduplicated key list — "fetch N rows by
+        // key" is exactly the shape readEffectiveRowsByKeys batches (one round trip
+        // per ROW_RESOLUTION_BATCH keys, pending overlay resolved first, positional
+        // nulls for missing keys). Emission order is unchanged (ascending encoded data
+        // key), and a downstream break mid-batch reads no further batch.
+        for (let start = 0; start < sorted.length; start += ROW_RESOLUTION_BATCH) {
+            const slice = sorted.slice(start, start + ROW_RESOLUTION_BATCH);
+            const rows = await this.readEffectiveRowsByKeys(slice.map(p => p.key));
+            for (let i = 0; i < slice.length; i++) {
+                const row = rows[i];
+                if (row && slice[i].infos.some(fi => this.matchesFilters(row, fi, collations))) {
+                    yield row;
+                }
             }
         }
     }