@quereus/store 4.11.0 → 4.12.1

package/dist/src/common/store-module-access-plan.js

@@ -8,7 +8,7 @@
  * advertise, and the scan layer there executes it. A plan that claims a filter the scan
  * cannot honor drops the residual Filter and returns wrong rows, so every soundness
  * predicate the two share lives in `pk-key-resolution.ts` (`keyOrderMatchesCollation`,
- * `indexLeadingRangeIsOrderSafe`, `pkOrderPreservingPrefixLength`) rather than being
+ * `indexRangeAtPositionIsOrderSafe`, `pkOrderPreservingPrefixLength`) rather than being
  * restated here. The declines that are NOT shared — partial indexes, the multi-seek cap,
  * and the semantic-ordering column ban on multi-seeks specifically — are stated in both
  * files, and changing one means changing the other.
@@ -17,21 +17,21 @@
  * no module state beyond the table's configured key collation, which the caller passes in.
  */
 import { AccessPlanBuilder, equalitySeekKeyCount, hasSemanticOrdering, isMultiValueEquality } from '@quereus/quereus';
-import { indexLeadingRangeIsOrderSafe, indexPrefixSeekIsCollationExact, pkOrderPreservingPrefixLength, resolveIndexKeyCollations, resolvePkKeyCollations, } from './pk-key-resolution.js';
+import { indexPrefixSeekIsCollationExact, indexRangeAtPositionIsOrderSafe, pkOrderPreservingPrefixLength, resolveIndexKeyCollations, resolvePkKeyCollations, } from './pk-key-resolution.js';
 /**
  * Planner-side constraint operator groups, as `BestAccessPlanRequest.filters` spells
  * them. Kept as one source of truth for the access-plan code below: {@link computeBestAccessPlan}
  * classifies each pushed filter with these, and {@link tryIndexAccessPlan} claims a filter as
  * handled only when it falls in the group the engine's access-path rule will consume.
- */
-const EQ_OPS = ['='];
-/**
- * Secondary-index arm ONLY: an IN is N equalities served as one multi-seek (`plan=5`),
- * whether its members are a literal list or a runtime-valued set. The primary-key arms
- * deliberately keep {@link EQ_OPS} — a `_primary_` multi-seek's emission order would
- * break the isolation layer's primary-key merge — so an IN on the PK declines here,
- * runtime-valued or not. PK IN support is deferred; see
- * tickets/backlog/feat-store-pk-in-list-multiseek.
+ *
+ * An IN is N equalities served as one multi-seek (`plan=5`), whether its members are a
+ * literal list or a runtime-valued set — so EVERY equality arm here, primary key and
+ * secondary index alike, fills its equality roles from this group. (The primary-key arms
+ * used to keep a `'='`-only group, on the reasoning that a `_primary_` multi-seek's
+ * emission order would break the isolation layer's primary-key merge. Both halves of that
+ * are now false: the merge bug was fixed as `bug-isolation-multiseek-merge-order`, and
+ * `StoreTableScan.scanMultiSeekPrimary` emits ascending by encoded data key — which IS
+ * primary-key order — specifically to satisfy it.)
  */
 const EQ_OR_IN_OPS = ['=', 'IN'];
 const LOWER_BOUND_OPS = ['>', '>='];
@@ -47,6 +47,69 @@ const RANGE_OPS = [...LOWER_BOUND_OPS, ...UPPER_BOUND_OPS];
 const MAX_MULTI_SEEK_KEYS = 1000;
 /** Cost of positioning one index seek, in the same unit as the per-row fetch cost. */
 const INDEX_SEEK_COST = 0.5;
+/**
+ * Cost of resolving ONE secondary-index entry to its row, in the same unit as the full
+ * scan's 1.0-per-row sequential read.
+ *
+ * A secondary-index path reads TWO stores per matched row — the index entry, then the row
+ * it names — where a sequential scan reads one row per row. `AccessPlanBuilder.eqMatch` /
+ * `.rangeScan` charge only the first (0.3 / 0.5 per row), so the `eq`, `prefixRange` and
+ * `range` seek arms add this term on top of the shape's own cost. The MULTI-SEEK arm does
+ * not; the measured reason is at that arm in {@link tryIndexAccessPlan}.
+ *
+ * Why 1.0: `StoreTableScan` resolves entries in `ROW_RESOLUTION_BATCH`-sized `getMany`
+ * batches (`store-table-scan.ts`: one store round trip per 256 entries, not per row), so a resolved row
+ * costs about what a sequentially-iterated row costs — the index path simply pays it ON TOP
+ * OF the entry read. Nothing here has been measured against real storage; it is a shape
+ * constant like {@link ARM_SELECTIVITY}, chosen for parity rather than from a benchmark.
+ *
+ * The constant is not freely tunable upward. Because {@link ARM_SELECTIVITY} is a fixed
+ * FRACTION of the table, every arm's cost is linear in `estimatedRows` and so is the full
+ * scan's — an arm either always prices above a sequential scan or never does, for a given
+ * constant. The switch-over points: the `range` arm (0.3 × N × (0.5 + R) > N) flips at
+ * R > 2.83, `prefixRange` at R > 6.17, `eq` at R > 9.7. So raising this past ~2.8 does not
+ * make range seeks "more expensive", it DISABLES them outright. Real per-column statistics
+ * (see the NOTE on {@link ARM_SELECTIVITY}) are what would make the comparison
+ * discriminate per query rather than per arm.
+ */
+const ROW_RESOLUTION_COST = 1.0;
+/**
+ * Estimated rows each arm returns, as a fraction of the request's `estimatedRows`. The
+ * store keeps no per-column histograms, so these are shape constants, not statistics.
+ *
+ * `prefixRange` sits between the two pre-existing factors, as its window does: it is
+ * narrower than a bare leading-column range (the prefix pins every column ahead of the
+ * bound) and wider than the pure-equality estimate, which stands for a prefix pinning
+ * every column the predicate names.
+ *
+ * NOTE: these are the store's biggest cost-model gap, and no per-row cost term closes it.
+ * They are shape constants, so `where col = ?` is modelled at 10% of the table whatever
+ * the predicate actually matches, and `request.estimatedRows` is the table's row count,
+ * not a selectivity-adjusted estimate. A predicate matching MOST of the table therefore
+ * still prices as an index seek returning 10% of it, and the full-scan comparison in
+ * {@link computeBestAccessPlan} cannot rescue it — the fix is real per-column statistics,
+ * not another constant here. Two things have to land for that: the store has to KEEP a
+ * value distribution (`StoreTableBase.getStatistics` reports the row count only — a
+ * distinct count or histogram would cost a scan, which is why `ANALYZE` collects the
+ * per-column half itself), and `BestAccessPlanRequest` has to CARRY it, which it does not
+ * today — the module sees `estimatedRows` and the filters, nothing else, so even an
+ * analyzed table plans identically. Until then every cost decision this file makes is
+ * per-ARM, never per-PREDICATE.
+ *
+ * NOTE: the arms are exclusive per index, but two INDEXES compete on cost — and an index
+ * on the equality prefix ALONE prices its `eq` arm cheaper (0.1) than the composite index
+ * prices its `prefixRange` arm (0.15), so a schema carrying both `(a)` and `(a, b)` picks
+ * `(a)` for `a = ? and b > ?` and leaves the `b` bound residual. Answers are unaffected.
+ * Fine while redundant prefix indexes are rare; if one shows up as a slow plan, either
+ * scale the `eq` factor by how many index columns the prefix actually pins, or drop
+ * `prefixRange` below `eq` — do not just swap the two constants, which would then mis-rank
+ * a genuine leading-column range.
+ */
+const ARM_SELECTIVITY = {
+    eq: 0.1,
+    prefixRange: 0.15,
+    range: 0.3,
+};
 /**
  * Build `handledFilters` by claiming ONLY the constraints `rule-select-access-path`
  * actually consumes: per seek column the FIRST '=' (equality seek), or the FIRST lower
@@ -82,12 +145,65 @@ function rangeRoles(colIdx) {
     return [{ colIdx, ops: LOWER_BOUND_OPS }, { colIdx, ops: UPPER_BOUND_OPS }];
 }
 /**
- * The one equality role each seek column of an equality/prefix seek fills. `ops` is
- * explicit so the PK arm ({@link EQ_OPS}) and the secondary-index arm
- * ({@link EQ_OR_IN_OPS}) cannot drift into each other — see the note on EQ_OR_IN_OPS.
+ * The one equality role each seek column of an equality/prefix seek fills — filled by a
+ * `'='` or a well-formed `IN` alike, on the primary-key arms and the secondary-index arm
+ * identically (see the note on {@link EQ_OR_IN_OPS}).
  */
-function equalityRoles(colIdxs, ops) {
-    return colIdxs.map(colIdx => ({ colIdx, ops }));
+function equalityRoles(colIdxs) {
+    return colIdxs.map(colIdx => ({ colIdx, ops: EQ_OR_IN_OPS }));
+}
+/**
+ * The longest LEADING run of `colIdxs` whose every column carries a filter that can fill
+ * an equality role, and what that run costs to seek.
+ *
+ * Per column the pin is the FIRST such filter ({@link equalitySeekKeyCount} — a `'='`, a
+ * non-empty literal `IN`, or a runtime-valued `IN` set). That is the same positional pick
+ * {@link claimFirstPerRole} claims and `rule-select-access-path`'s `eqBySeekCol` seeks on,
+ * so this module's claim and the rule's pick cannot disagree. A runtime-valued set
+ * contributes its `maxCount` ceiling — the worst case the engine may deliver — so every
+ * gate downstream judges the largest multi-seek it could ever be asked to perform.
+ *
+ * ONE helper for both the primary-key arms ({@link resolvePrimaryKeyPins}, which needs the
+ * run to cover the whole key) and the secondary-index arm (which takes whatever prefix it
+ * gets): separate copies of this loop are how a `'='`-only PK arm and an IN-claiming index
+ * arm drifted apart in the first place — see the note on {@link EQ_OR_IN_OPS}.
+ *
+ * `isMultiSeek` is NOT `seekKeyCount > 1`: a runtime-valued set is delivered as a `plan=5`
+ * multi-seek even at `maxCount === 1`, so it must be judged as one rather than as the plain
+ * point read its ceiling arithmetic would otherwise suggest. (`seekKeyCount > 1` implies
+ * the flag — every factor above 1 is a multi-value equality — so the flag only ever *adds*
+ * the `maxCount === 1` runtime-set case.)
+ */
+function resolveEqualityPins(filters, colIdxs) {
+    const cols = [];
+    let seekKeyCount = 1;
+    let isMultiSeek = false;
+    for (const colIdx of colIdxs) {
+        const pin = filters.find(f => f.columnIndex === colIdx && equalitySeekKeyCount(f) !== null);
+        if (!pin)
+            break;
+        cols.push(colIdx);
+        seekKeyCount *= equalitySeekKeyCount(pin);
+        if (isMultiValueEquality(pin))
+            isMultiSeek = true;
+    }
+    return { cols, seekKeyCount, isMultiSeek };
+}
+/**
+ * The equality pins covering the WHOLE primary key, or null when a member is unpinned.
+ *
+ * A per-column pin rather than a count of pinned columns: `a = 1 and a = 2` on a composite
+ * PK `(a, b)` pins `a`, finds nothing for `b`, and correctly reports the key unpinned.
+ * Counting raw equality filters instead would read that predicate as "both PK columns
+ * pinned", claim both filters handled, then — with no complete PK equality set to seek —
+ * degrade to a sequential scan whose residual has already been discarded, returning the
+ * whole table.
+ */
+function resolvePrimaryKeyPins(filters, pkColumns) {
+    if (pkColumns.length === 0)
+        return null;
+    const pins = resolveEqualityPins(filters, pkColumns);
+    return pins.cols.length === pkColumns.length ? pins : null;
 }
 /**
  * The access plan this module advertises for `request`, before the caller stamps the
@@ -102,36 +218,80 @@ function equalityRoles(colIdxs, ops) {
  */
 export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation) {
     const estimatedRows = request.estimatedRows ?? 1000;
-    // Check for primary key equality constraints. Count DISTINCT pinned PK columns:
-    // counting raw '=' filters would read `a = 1 and a = 2` on a composite PK (a, b)
-    // as "both PK columns pinned", claim both filters handled, then — with no
-    // complete PK equality set to seek — degrade to a sequential scan whose residual
-    // has already been discarded, returning the whole table.
     const pkColumns = tableInfo.primaryKeyDefinition.map(pk => pk.index);
-    const pinnedPkColumns = new Set(request.filters
-        .filter(f => f.columnIndex !== undefined && pkColumns.includes(f.columnIndex) && f.op === '=')
-        .map(f => f.columnIndex));
-    if (pinnedPkColumns.size === pkColumns.length && pkColumns.length > 0) {
-        // Full PK match - point lookup (single row; no monotonic advertisement)
+    // Hoisted ABOVE both primary-key arms: the multi-seek arm's ordering advertisement
+    // needs it, and it is cheap (a short loop over the PK members). Its other consumer is
+    // the leading-PK range arm below, which declines when the leading PK column's key
+    // bytes do not order the way its comparator does (`pkOrderPreservingPrefix === 0`):
+    // `StoreTable.analyzePKAccess` declines the byte window under exactly that condition,
+    // so claiming the range filters handled would drop the residual Filter and return the
+    // whole table.
+    const pkOrderPreservingPrefix = pkOrderPreservingPrefixLength(db, tableInfo, resolvePkKeyCollations(tableInfo.primaryKeyDefinition, tableInfo.columns, tableKeyCollation), tableKeyCollation);
+    // Primary-key equality arms. Both live INSIDE this branch — the multi-seek is tried
+    // BEFORE the leading-PK range arm below, which is what keeps a full-primary-key IN
+    // list from being shadowed by a range on the leading column (the general
+    // arm-competition problem is backlog `bug-store-pk-range-preempts-cheaper-index`; do
+    // not fix it here).
+    //
+    // **No collation gate, and that is not an oversight.** The secondary-index arm gates
+    // its equality window on `indexPrefixSeekIsCollationExact`; the PK arms need no
+    // equivalent, for two independent reasons:
+    //  - `reconcilePkCollations` (store-module-schema-rewrite.ts) rewrites an undecorated
+    //    text PK column's declared collation to the table key collation K at CREATE time,
+    //    so for every PK member the key collation, the declared collation, and the
+    //    collation `matchesFilters` re-compares under are the same name. The divergent
+    //    shape the secondary arm declines — a collation-blind `json`/temporal column under
+    //    an index column carrying an explicit non-BINARY `COLLATE` — cannot occur on a PK:
+    //    column DDL type-gates that `COLLATE` out, and those types are declined by the
+    //    semantic-ordering gate below anyway.
+    //  - `StoreTableScan.scanMultiSeekPrimary` re-applies `matchesFilters` per resolved
+    //    row, so even a hypothetical coarser window over-fetches and is trimmed rather
+    //    than under-fetching.
+    // The multi-seek is exactly the point arm run N times, so its collation exposure is
+    // the point arm's, unchanged.
+    //
+    // The one divergence neither reason covers is PREDICATE-side and invisible from here:
+    // `where pk collate nocase in (…)` over a BINARY key column would seek exact-case
+    // windows and UNDER-fetch. `PredicateConstraint` carries no collation, so this module
+    // cannot see it and always claims; `rule-select-access-path`'s `classifyCollationCover`
+    // (which reads the predicate's effective collation off the source expression) is what
+    // declines that shape to a scan + residual. A new PK arm inherits that protection only
+    // by going through the rule's index-aware path — one more reason `setSeekColumns` on
+    // the point arm below is load-bearing.
+    const pkPins = resolvePrimaryKeyPins(request.filters, pkColumns);
+    if (pkPins && !pkPins.isMultiSeek) {
+        // Full PK match - point lookup (single row; no monotonic advertisement).
+        //
+        // `setSeekColumns` is load-bearing now that this arm also claims a single-element
+        // `IN`: it routes the plan through `rule-select-access-path`'s INDEX-AWARE arm,
+        // whose `eqBySeekCol` accepts a one-element IN as an equality seek key. The legacy
+        // PK arm it would otherwise take matches `op === '='` only, so the claimed IN would
+        // be seeked nowhere and come back as a reattached residual over a full scan — the
+        // right rows at the wrong cost. For a plain `'='` the two arms build an identical
+        // `_primary_` `plan=2` seek under an identical collation-cover lookup.
         return AccessPlanBuilder
             .eqMatch(1, 0.1)
-            .setHandledFilters(claimFirstPerRole(request.filters, equalityRoles(pkColumns, EQ_OPS)))
+            .setHandledFilters(claimFirstPerRole(request.filters, equalityRoles(pkColumns)))
             .setIsSet(true)
             .setIndexName('_primary_')
+            .setSeekColumns(pkColumns)
             .setExplanation('Store primary key lookup')
             .build();
     }
+    if (pkPins) {
+        const plan = primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pkPins, estimatedRows, pkOrderPreservingPrefix);
+        // A gate decline FALLS THROUGH to the arms below rather than returning cost-only.
+        // That is safe: an `IN` is not in {@link RANGE_OPS}, so the leading-PK-range arm
+        // cannot grab it, and it lands on the secondary-index arms / full scan exactly as
+        // it did before this arm existed.
+        if (plan)
+            return plan;
+    }
     // Check for range constraints on the leading PK column.
     // The legacy access-path rule (rule-select-access-path.ts) only forwards
     // range bounds for primaryKeyDefinition[0]; ranges on later PK columns
     // are silently dropped if marked handled. So only claim handled=true
     // when the range is on the first PK column.
-    //
-    // The seek is also declined when the leading PK column's key bytes do not order the
-    // way its comparator does (`pkOrderPreservingPrefix === 0`): `StoreTable.analyzePKAccess`
-    // declines the byte window under exactly that condition, so claiming the range filters
-    // handled here would drop the residual Filter and return the whole table.
-    const pkOrderPreservingPrefix = pkOrderPreservingPrefixLength(db, tableInfo, resolvePkKeyCollations(tableInfo.primaryKeyDefinition, tableInfo.columns, tableKeyCollation), tableKeyCollation);
     const firstPkColumn = tableInfo.primaryKeyDefinition[0]?.index;
     const hasLeadingPkRange = firstPkColumn !== undefined
         && pkOrderPreservingPrefix >= 1
@@ -153,36 +313,87 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
         return { ...plan, ...buildPkOrderingAdvertisement(tableInfo, request, pkOrderPreservingPrefix) };
     }
     // Check for secondary index usage. `StoreTable.query` now implements the
-    // secondary-index scan arm (leading-prefix EQ point / leading-column range),
+    // secondary-index scan arm (leading-prefix EQ point / leading-column range /
+    // prefix-equality + trailing-column range),
     // so we advertise the index with `indexName` + `seekColumns` and mark the
     // covered filters handled — subject to the range arm's order-safety gate in
     // {@link tryIndexAccessPlan}. A cost-only plan (no seek) is kept as a fallback
     // when no index yields a sound seek, preserving the prior "cheaper cost, filters
     // unhandled, residual retained" behavior.
+    //
+    // The sequential scan this module would otherwise fall back to, built up-front so the
+    // seek arms can be PRICED AGAINST its cost below: `rule-select-access-path` takes
+    // whatever single plan this function returns and never compares it with an alternative,
+    // so a seek that costs more than reading the table start to finish is only rejected if
+    // the module rejects it here. Built once and re-explained on the way out rather than
+    // re-deriving `AccessPlanBuilder.fullScan`'s cost formula for the comparison — the
+    // drift {@link AccessPlanBuilder.addCost} exists to prevent.
+    const scanPlan = {
+        ...AccessPlanBuilder
+            .fullScan(estimatedRows)
+            .setHandledFilters(new Array(request.filters.length).fill(false))
+            .setExplanation('Store full table scan')
+            .build(),
+        ...buildPkOrderingAdvertisement(tableInfo, request, pkOrderPreservingPrefix),
+    };
     const indexes = tableInfo.indexes || [];
     let bestSeekPlan = null;
     let costOnlyFallback = null;
     for (const index of indexes) {
         if (index.columns.length === 0)
             continue;
-        const plan = tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows);
-        if (!plan)
+        const candidate = tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows);
+        if (!candidate)
             continue;
+        const { plan } = candidate;
         // A fully-handled seek (indexName + seekColumns set) is a candidate: keep the
         // cheapest one seen so far rather than the first, so declaration order of the
         // indexes doesn't decide the plan. Strict '<' so ties keep the first candidate,
         // matching MemoryTableModule.findBestAccessPlan's `indexPlan.cost < bestPlan.cost`.
         if (plan.seekColumnIndexes && plan.seekColumnIndexes.length > 0) {
-            if (!bestSeekPlan || plan.cost < bestSeekPlan.cost)
-                bestSeekPlan = plan;
+            if (!bestSeekPlan || plan.cost < bestSeekPlan.plan.cost)
+                bestSeekPlan = candidate;
             continue;
         }
         // Otherwise remember the first cost-only advertisement as a fallback.
         if (!costOnlyFallback)
             costOnlyFallback = plan;
     }
-    if (bestSeekPlan)
-        return bestSeekPlan;
+    if (bestSeekPlan) {
+        //
+        // The MULTI-SEEK arm is exempt, and that is a measured decision rather than an
+        // oversight. `rule-key-set-seek` (engine side) does not consume this arm as a PLAN —
+        // it probes `getBestAccessPlan` with SYNTHESIZED runtime-set filters at 2 and 1000
+        // keys, reads the two costs as a straight line, and interpolates the key count at
+        // which the seek would overtake a scan. A probe answer that stops naming an index is
+        // read as "the module declined" and the whole rewrite is abandoned. Since nothing
+        // here distinguishes a probe from a user's own `col in (…)`, substituting this
+        // module's own scan verdict at 1000 keys silently switches key-set semi joins off:
+        // MEASURED, it fails 11 tests in `key-set-seek-store.spec.ts` on tables of 200 and
+        // 300 rows where the seek is unambiguously the right plan at the key counts actually
+        // used. The arm's brakes stay `inCount × INDEX_SEEK_COST` (which is what the engine
+        // interpolates) and {@link MAX_MULTI_SEEK_KEYS}; the engine makes the scan comparison
+        // this exemption skips, off the same numbers.
+        //
+        // Ties keep the seek: it returns fewer rows for the rest of the plan to carry.
+        if (bestSeekPlan.isMultiSeek || bestSeekPlan.plan.cost <= scanPlan.cost)
+            return bestSeekPlan.plan;
+        // Losing the seek is SAFE, never a wrong answer: the scan claims no filters, so the
+        // engine keeps every one of them as a residual Filter and the row set is identical.
+        // Deliberately returns the scan rather than falling through to `costOnlyFallback`
+        // below — a cost-only plan performs this same sequential scan while advertising an
+        // index arm's (cheaper) cost, so falling through would undo the comparison.
+        //
+        // NOTE: a vetoed seek is indistinguishable from a DECLINE to the engine, and
+        // `rule-key-set-seek` reads a probe answer that names no index as "the module
+        // declined" and abandons its rewrite. Harmless while the veto is reachable only
+        // where an arm's estimate is the whole table (a one-row table, per the arithmetic on
+        // {@link ROW_RESOLUTION_COST}) — a key-set seek there is worthless anyway. If real
+        // per-column statistics ever make the veto fire on tables worth seeking, the
+        // comparison has to exempt any request carrying a runtime-valued set, not just the
+        // arm this module happens to pick for it.
+        return { ...scanPlan, explains: 'Store full table scan (cheaper than the best index seek)' };
+    }
     // NOTE: a cost-only plan carries no PK-order advertisement even though the store still
     // iterates in PK key order for it (`StoreTable.query` full-scans), so `... where v > 'x'
     // order by <pk>` picks up a Sort it did not need. Still true, just rarer than it was: an
@@ -200,14 +411,65 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
         return costOnlyFallback;
     // Fallback to full scan. The store iterates rows in PK key order
     // (see StoreTable.query / store.iterate over buildFullScanBounds), so
-    // the scan is monotonic on the leading PK column. Advertise that so
+    // the scan is monotonic on the leading PK column. `scanPlan` advertises that so
     // downstream rules (merge-join, asof-scan) can fire on store-backed
     // tables, matching memory-mode behavior.
+    return scanPlan;
+}
+/**
+ * The `_primary_` multi-seek advertisement for a WHOLE-primary-key IN (`where pk in (…)`,
+ * or a runtime-valued set on the PK), or null when a gate declines it.
+ *
+ * `StoreTableScan.scanMultiSeekPrimary` is the runtime twin: it encodes one data key per
+ * tuple, deduplicates, sorts ascending by encoded key, and point-reads each in bounded
+ * batches. Both gates below mirror one of its `multiSeekMalformed` throws, which stay in
+ * place as the assertion that the plan never produced a shape it cannot serve.
+ */
+function primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pins, estimatedRows, pkOrderPreservingPrefix) {
+    if (pins.seekKeyCount > MAX_MULTI_SEEK_KEYS)
+        return null;
+    // Mirrors `StoreTableScan.pkHasSemanticOrderingMember`, which `scanMultiSeekPrimary`
+    // throws `multiSeekMalformed` on: N merged point windows ARE the whole access, with
+    // the residual already dropped, so an IN member with no faithful byte position would
+    // silently lose its tuple's rows. The single-value point arm has an escape this does
+    // not (it can decline to the scan arm per PROBE), which is why only this one declines
+    // per SCHEMA. Re-opening it is backlog `feat-store-semantic-key-multiseek`.
+    if (pkColumns.some(colIdx => hasSemanticOrdering(tableInfo.columns[colIdx]?.logicalType)))
+        return null;
+    // The PK is unique, so each seek key matches at most one row — no `multiRows` clamp
+    // artifact (contrast the secondary arm's), and no ROW_RESOLUTION_COST: the point read
+    // IS the row read, with no index-entry → row indirection to charge for.
+    //
+    // `Math.max(1, …)` is LOAD-BEARING, not defensive. `rows: 0` on a plan that claims
+    // every filter makes `rule-select-access-path` replace the whole table access with an
+    // `EmptyResultNode` (its "the module proved the predicate unsatisfiable" fold), so a
+    // table that is empty at PLAN time would return nothing for rows written by the same
+    // statement.
+    const rows = Math.max(1, Math.min(estimatedRows, pins.seekKeyCount));
     const plan = AccessPlanBuilder
-        .fullScan(estimatedRows)
-        .setHandledFilters(new Array(request.filters.length).fill(false))
-        .setExplanation('Store full table scan')
+        // `setIsSet(false)` is likewise load-bearing: `eqMatch` defaults `isSet` to
+        // `rows <= 1`, which a one-key runtime set would satisfy.
+        .eqMatch(rows, pins.seekKeyCount * INDEX_SEEK_COST)
+        .setIsSet(false)
+        .setIndexName('_primary_')
+        // EVERY primary-key column, in `primaryKeyDefinition` order: `scanMultiSeekPrimary`
+        // throws when `seekWidth` does not cover the whole key, and the rule derives
+        // `seekWidth` from this list.
+        .setSeekColumns(pkColumns)
+        .setHandledFilters(claimFirstPerRole(request.filters, equalityRoles(pkColumns)))
+        .setExplanation(`Store primary key multi-seek(${pins.seekKeyCount})`)
         .build();
+    // This arm returns straight out of the PK branch, so it never reaches the
+    // seek-versus-scan comparison further down `computeBestAccessPlan` — the same
+    // exemption the secondary multi-seek arm gets explicitly, for the same reason:
+    // `rule-key-set-seek` reads this cost as a straight line at 2 and 1000 keys and
+    // abandons its rewrite if either probe stops naming an index. Do not "fix" this by
+    // adding the comparison.
+    //
+    // `scanMultiSeekPrimary` sorts its points ascending by encoded data key, which IS
+    // primary-key order (per-column DESC inversion is baked into the bytes), so the plan
+    // goes through the same ordering gate every other primary-key arm uses and
+    // `… where pk in (…) order by pk` elides its Sort.
     return { ...plan, ...buildPkOrderingAdvertisement(tableInfo, request, pkOrderPreservingPrefix) };
 }
 /**
@@ -215,8 +477,9 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
  * the index is not usable for this predicate.
  *
  * Usable = a contiguous leading-prefix EQ on the index columns (an index seek /
- * point), or a LT/LE/GT/GE range on the LEADING index column. These mirror the
- * two windows `StoreTable.analyzeIndexAccess` can build.
+ * point), a LT/LE/GT/GE range on the LEADING index column, or a strict leading-prefix EQ
+ * plus a LT/LE/GT/GE range on the NEXT index column (`prefixRange`, `plan=7`). These
+ * mirror the three windows `StoreTable.analyzeIndexAccess` can build.
  *
  * **Collation safety.** Index-column key bytes are encoded under each column's own key
  * collation (`resolveIndexKeyCollations`); `StoreTable.matchesFilters` re-checks a fetched
@@ -229,13 +492,22 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
  *    the same resolution the residual uses); a collation-blind column (`json`, the
  *    temporal types) under an index column with an explicit non-BINARY COLLATE does not
  *    (its key bytes are hard-BINARY) and declines.
- *  - RANGE — {@link indexLeadingRangeIsOrderSafe}: the same agreement PLUS the collation's
- *    `orderPreserving` assertion, because a byte window also equates memcmp of the key
- *    bytes with the residual comparator's order.
+ *  - RANGE — {@link indexRangeAtPositionIsOrderSafe}: the same agreement PLUS the
+ *    collation's `orderPreserving` assertion, because a byte window also equates memcmp of
+ *    the key bytes with the residual comparator's order. Asked at position 0 for a
+ *    leading-column range, and at the prefix length for a `prefixRange` trailing bound —
+ *    whose PREFIX additionally passes the EQUALITY gate above.
  *
  * `StoreTable.analyzeIndexAccess` gates its windows on the same two helpers, so the "mark
  * handled" and "build a window" decisions cannot disagree. A decline returns a cost-only
  * plan: cheaper cost, filters unhandled, residual retained; correct, just not sped up.
+ *
+ * **Cost.** Each single-window seek arm pays {@link ROW_RESOLUTION_COST} per row it expects
+ * to return, on top of the `AccessPlanBuilder` shape's own per-row term: the shape prices
+ * reading the index ENTRY, and the store must then read the ROW that entry names out of the
+ * data store. Two arms deliberately do NOT pay it — a cost-only decline (it resolves
+ * nothing; the scan reads rows directly) and the multi-seek, for the measured reason
+ * recorded at that arm below.
  */
 function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
     // Exclude PARTIAL indexes from access planning: neither the engine nor this
@@ -247,65 +519,83 @@ function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
     if (index.predicate)
         return null;
     const indexColIndexes = index.columns.map(c => c.index);
-    // Contiguous leading-prefix equality → point/prefix seek. An IN filter counts as
-    // an equality here (it is N equalities, served as one multi-seek by
-    // StoreTable.scanMultiSeek); `inCount` is the cross-product of the per-column
-    // seek-key counts (1 for a plain '='), matching the rule's seek-key count. The
-    // FIRST role-filling filter per column is what the rule seeks on, so its
-    // cardinality is the one that counts.
-    //
-    // A runtime-valued IN set contributes its `maxCount` ceiling — the worst case the
-    // engine may deliver — so every gate below (the MAX_MULTI_SEEK_KEYS cap, the
-    // semantic-ordering decline) judges it against the largest multi-seek it could
-    // ever be asked to perform.
-    const eqCols = [];
-    let inCount = 1;
-    // `isMultiSeek` is NOT `inCount > 1`: a runtime set is delivered as a `plan=5`
-    // multi-seek even at `maxCount === 1`, so the gates below must judge it as one
-    // rather than as the plain EQ its ceiling arithmetic would otherwise suggest.
-    // (`inCount > 1` implies this flag — every factor above 1 is a multi-value
-    // equality — so the flag only ever *adds* the maxCount-1 runtime-set case.)
-    let isMultiSeek = false;
-    for (const colIdx of indexColIndexes) {
-        const eqFilter = request.filters.find(f => f.columnIndex === colIdx && equalitySeekKeyCount(f) !== null);
-        if (!eqFilter)
-            break;
-        eqCols.push(colIdx);
-        inCount *= equalitySeekKeyCount(eqFilter);
-        if (isMultiValueEquality(eqFilter))
-            isMultiSeek = true;
-    }
+    // Contiguous leading-prefix equality → point/prefix seek. An IN filter counts as an
+    // equality here (it is N equalities, served as one multi-seek by
+    // StoreTable.scanMultiSeek); `inCount` is the cross-product of the per-column seek-key
+    // counts, matching the rule's seek-key count. See {@link resolveEqualityPins} for the
+    // positional pick and the runtime-set ceiling both arms share.
+    const { cols: eqCols, seekKeyCount: inCount, isMultiSeek } = resolveEqualityPins(request.filters, indexColIndexes);
     const leadingCol = indexColIndexes[0];
     const hasLeadingRange = request.filters.some(f => f.columnIndex === leadingCol && RANGE_OPS.includes(f.op));
+    // Prefix-equality + trailing-range: the equality prefix is a STRICT, non-empty prefix
+    // of the index columns and the NEXT index column carries a bound. `StoreTable
+    // .analyzeIndexAccess` builds the matching one-window `[prefix||bound]` range.
+    //
+    // A multi-value prefix is EXCLUDED: `rule-select-access-path` can only seek a
+    // single-valued prefix key, so `a in (1, 2) and b > 15` over `(a, b)` would come back
+    // as a sequential scan with both predicates residual — worse than the multi-seek this
+    // index can still serve on the IN alone. MemoryTableModule.evaluateIndexAccess records
+    // the same restriction for the same reason.
+    const nextCol = eqCols.length > 0 && eqCols.length < indexColIndexes.length
+        ? indexColIndexes[eqCols.length]
+        : undefined;
+    const trailingRangeCol = (!isMultiSeek && nextCol !== undefined
+        && request.filters.some(f => f.columnIndex === nextCol && RANGE_OPS.includes(f.op)))
+        ? nextCol
+        : undefined;
     let seekCols;
-    let isRange;
-    if (eqCols.length > 0) {
+    let arm;
+    if (trailingRangeCol !== undefined) {
+        seekCols = [...eqCols, trailingRangeCol];
+        arm = 'prefixRange';
+    }
+    else if (eqCols.length > 0) {
         seekCols = eqCols;
-        isRange = false;
+        arm = 'eq';
     }
     else if (hasLeadingRange) {
         seekCols = [leadingCol];
-        isRange = true;
+        arm = 'range';
     }
     else {
         return null; // this index cannot serve this predicate
     }
-    const rows = isRange
-        ? Math.max(1, Math.floor(estimatedRows * 0.3))
-        : Math.max(1, Math.floor(estimatedRows * 0.1));
-    const costOnly = (why) => (isRange ? AccessPlanBuilder.rangeScan(rows, 0.2) : AccessPlanBuilder.eqMatch(rows, 0.3))
-        .setHandledFilters(new Array(request.filters.length).fill(false))
-        .setExplanation(`Store index scan on ${index.name} (${why})`)
-        .build();
     // Collation gates — see the doc comment above. `StoreTable.analyzeIndexAccess` declines
-    // exactly the same windows through the same two helpers.
+    // exactly the same windows through the same two helpers, at the same positions.
     const indexKeyCollations = resolveIndexKeyCollations(index, tableInfo.columns);
-    if (isRange) {
-        if (!indexLeadingRangeIsOrderSafe(db, tableInfo.columns, index, indexKeyCollations)) {
+    // A trailing bound whose byte order does not reproduce its residual comparator's order
+    // costs only the bound, not the whole plan: DEGRADE to the equality-prefix seek and
+    // leave the bound unclaimed, so it survives in the residual Filter. The scan side makes
+    // the same move (a `plan=2` eqSeek arrives and it windows the prefix), and keeping the
+    // prefix seek is strictly better than the cost-only fallback below.
+    if (arm === 'prefixRange'
+        && !indexRangeAtPositionIsOrderSafe(db, tableInfo.columns, index, indexKeyCollations, eqCols.length)) {
+        arm = 'eq';
+        seekCols = eqCols;
+    }
+    const isRange = arm !== 'eq';
+    const rows = Math.max(1, Math.floor(estimatedRows * ARM_SELECTIVITY[arm]));
+    /** The arm's shape — `AccessPlanBuilder`'s per-row index-entry term, no resolution. */
+    const armShape = () => isRange ? AccessPlanBuilder.rangeScan(rows, 0.2) : AccessPlanBuilder.eqMatch(rows, 0.3);
+    /** The arm's shape plus the per-fetched-row {@link ROW_RESOLUTION_COST}. */
+    const seekingArm = () => armShape().addCost(rows * ROW_RESOLUTION_COST);
+    const costOnly = (why) => ({
+        plan: armShape()
+            .setHandledFilters(new Array(request.filters.length).fill(false))
+            .setExplanation(`Store index scan on ${index.name} (${why})`)
+            .build(),
+        // Cost-only never reaches the comparison (it claims no seek columns), so the flag
+        // is immaterial; false states the fact — this plan seeks nothing at all.
+        isMultiSeek: false,
+    });
+    if (arm === 'range') {
+        if (!indexRangeAtPositionIsOrderSafe(db, tableInfo.columns, index, indexKeyCollations, 0)) {
             return costOnly('cost-only; index range needs an order-preserving key collation');
         }
     }
-    else if (!indexPrefixSeekIsCollationExact(tableInfo.columns, index, indexKeyCollations, seekCols.length)) {
+    else if (!indexPrefixSeekIsCollationExact(tableInfo.columns, index, indexKeyCollations, eqCols.length)) {
+        // Covers the `prefixRange` arm's PREFIX too: its pinned columns need exactly the
+        // equality arm's guarantee, and its trailing column was gated just above.
         return costOnly('cost-only; index key collation differs from the comparison collation');
     }
     // Multi-seek declines. Cost-only keeps the residual, so the answer stays right
@@ -324,29 +614,68 @@ function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
         // backlog `feat-store-semantic-key-multiseek`.
         return costOnly('cost-only; semantic-ordering seek column cannot multi-seek');
     }
-    // Claim positionally — see {@link claimFirstPerRole}.
-    const handledFilters = claimFirstPerRole(request.filters, isRange ? rangeRoles(leadingCol) : equalityRoles(eqCols, EQ_OR_IN_OPS));
+    // Claim positionally — see {@link claimFirstPerRole}. The `prefixRange` arm claims the
+    // prefix equalities AND the first lower/upper bound on the trailing column; a redundant
+    // same-side bound (`date > a and date > b`) stays unclaimed and survives in the residual.
+    // A prefixRange DEGRADED to 'eq' above claims the prefix only, so its trailing bounds
+    // likewise survive.
+    const handledFilters = claimFirstPerRole(request.filters, arm === 'range'
+        ? rangeRoles(leadingCol)
+        : arm === 'prefixRange'
+            ? [...equalityRoles(eqCols), ...rangeRoles(trailingRangeCol)]
+            : equalityRoles(eqCols));
     if (isMultiSeek) {
         // Multi-seek (plan=5): inCount point seeks, `rows` matched per seek key. The
         // per-seek positioning term keeps a 500-key IN over a 10-row table from pricing
         // below a full scan and issuing 500 seeks to read 10 rows. `isSet` false mirrors
         // MemoryTableModule.evaluateIndexAccess's setIsSet(!isMultiSeek). No ordering is
         // advertised — window emission order is encoded-key order, not any column order.
+        //
+        // NOTE: this arm alone does NOT pay {@link ROW_RESOLUTION_COST}, though it resolves
+        // every entry it matches exactly like the single-window arms do. The reason is
+        // `multiRows`, not the physics: `inCount × rows` reaches `estimatedRows` at ten seek
+        // keys (`rows` is the fixed 0.1 × N equality shape constant) and at two or three on a
+        // handful-of-rows table, so beyond that the figure is a CLAMP — "the whole table" —
+        // rather than an estimate of what the keys match. Charging a per-row term against a
+        // clamp prices the estimator's artifact:
+        //   - MEASURED: it fails 16 tests in `key-set-seek-store.spec.ts`, every one a
+        //     runtime key-set semi join over a 3-to-4-row table that stops seeking.
+        //   - The engine's `rule-key-set-seek` interpolates a break-even from THIS cost at 2
+        //     and 1000 keys. With the term, `cost(1000 keys) = 500 + 1.3 × N` exceeds a scan's
+        //     `N` for every N, so the break-even can never reach the engine's 1000-key ceiling
+        //     — key sets above ~710 keys would stop seeking on a table of ANY size, including
+        //     the 10M-row tables where an index seek is the entire point.
+        // The price of leaving it off is a narrower mis-ranking: against another index's `eq`
+        // arm (which does pay the term) a small-key IN now looks relatively cheaper than it
+        // is — `where a in (x, y) and b = ?` over a 1000-row table prices ix_a at 61 and ix_b
+        // at 130 and picks ix_a, though ix_a's own estimate says it fetches 200 rows to ix_b's
+        // 100. Charging the term everywhere fixes that ranking and breaks the feature above;
+        // the union estimate has to stop clamping before both can hold. See
+        // backlog/debt-store-multi-seek-union-row-estimate.
         const multiRows = Math.min(estimatedRows, inCount * rows);
-        return AccessPlanBuilder.eqMatch(multiRows, inCount * INDEX_SEEK_COST)
-            .setIsSet(false)
+        return {
+            plan: AccessPlanBuilder.eqMatch(multiRows, inCount * INDEX_SEEK_COST)
+                .setIsSet(false)
+                .setHandledFilters(handledFilters)
+                .setIndexName(index.name)
+                .setSeekColumns(seekCols)
+                .setExplanation(`Store index multi-seek(${inCount}) on ${index.name}`)
+                .build(),
+            isMultiSeek: true,
+        };
+    }
+    const armLabel = arm === 'prefixRange'
+        ? `prefix-range seek(prefix=${eqCols.length})`
+        : arm === 'range' ? 'range scan' : 'seek';
+    return {
+        plan: seekingArm()
             .setHandledFilters(handledFilters)
             .setIndexName(index.name)
             .setSeekColumns(seekCols)
-            .setExplanation(`Store index multi-seek(${inCount}) on ${index.name}`)
-            .build();
-    }
-    return (isRange ? AccessPlanBuilder.rangeScan(rows, 0.2) : AccessPlanBuilder.eqMatch(rows, 0.3))
-        .setHandledFilters(handledFilters)
-        .setIndexName(index.name)
-        .setSeekColumns(seekCols)
-        .setExplanation(`Store index ${isRange ? 'range scan' : 'seek'} on ${index.name}`)
-        .build();
+            .setExplanation(`Store index ${armLabel} on ${index.name}`)
+            .build(),
+        isMultiSeek: false,
+    };
 }
 /**
  * Compute the PK-ordering advertisement for a scan-style plan. Returns the