@quereus/store 4.12.1 → 4.13.1

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

@@ -16,7 +16,8 @@
  * Free functions rather than a layer of the store-module chain — access planning reads
  * no module state beyond the table's configured key collation, which the caller passes in.
  */
-import { AccessPlanBuilder, equalitySeekKeyCount, hasSemanticOrdering, isMultiValueEquality } from '@quereus/quereus';
+import { AccessPlanBuilder, combineConjunctive, equalitySeekKeyCount, hasSemanticOrdering, isMultiValueEquality, selectivityFromHistogram, } from '@quereus/quereus';
+import { PARITY_COST_PROFILE } from './cost-profile.js';
 import { indexPrefixSeekIsCollationExact, indexRangeAtPositionIsOrderSafe, pkOrderPreservingPrefixLength, resolveIndexKeyCollations, resolvePkKeyCollations, } from './pk-key-resolution.js';
 /**
  * Planner-side constraint operator groups, as `BestAccessPlanRequest.filters` spells
@@ -45,71 +46,190 @@ const RANGE_OPS = [...LOWER_BOUND_OPS, ...UPPER_BOUND_OPS];
  * explosion.
  */
 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.
+ * FALLBACK rows each arm returns, as a fraction of the request's `estimatedRows` — shape
+ * constants, reached only when {@link resolveArmEstimate} cannot produce a per-predicate
+ * estimate from `tableSchema.statistics`. Concretely, a constant is still the estimate
+ * when:
  *
- * 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}.
+ *  - the table has never been `ANALYZE`d (`tableSchema.statistics` absent) — the common
+ *    case, which must plan byte-identically to the pre-statistics module;
+ *  - the snapshot was taken while the table was EMPTY (`rowCount` 0), so it describes
+ *    nothing and every `distinctCount` in it is 0 — see {@link resolveArmEstimate};
+ *  - any column filling an EQUALITY role in the arm has no per-column statistics (a
+ *    column added or renamed after the last `ANALYZE` — the arm falls back WHOLESALE
+ *    rather than mixing a measured factor with a shape constant);
+ *  - a pure `range` arm's bound cannot be answered by the column's histogram (no
+ *    histogram was built, the bound's value is a parameter unknown at plan time, or the
+ *    histogram declines). A `prefixRange` arm in the same position stays per-query — its
+ *    measured prefix factors carry the estimate and only the bound's factor falls back
+ *    to this constant.
  *
- * 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.
+ * `prefixRange` sits between the two other factors, as its window does: 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.
  *
- * 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.
+ * NOTE: the arms are exclusive per index, but two INDEXES compete on cost — and on an
+ * un-analyzed table 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, and `ANALYZE` largely resolves it: under real
+ * statistics the composite arm's estimate is the prefix's factor damped by the bound's,
+ * so it under-prices the single-column arm whenever the bound is at all selective. If
+ * the un-analyzed ranking ever shows up as a slow plan, the fix is `ANALYZE`, not a
+ * constant swap here.
  */
 const ARM_SELECTIVITY = {
     eq: 0.1,
     prefixRange: 0.15,
     range: 0.3,
 };
+/**
+ * The `ANALYZE`-collected statistics for the table column at `colIdx`, or undefined when
+ * the table has none or the column is not covered.
+ *
+ * `columnStats` is keyed by LOWERCASE COLUMN NAME while this file works in column index,
+ * so the lookup goes index → current column name → stats. That direction is what keeps a
+ * post-`ANALYZE` `ALTER TABLE` safe: a RENAMED column's current name is absent from the
+ * map (falls back to the shape constant), and a DROPPED column shifts later indexes onto
+ * their own current names — a miss or the right entry, never a neighbour's numbers.
+ */
+function columnStatsFor(tableInfo, stats, colIdx) {
+    const name = tableInfo.columns[colIdx]?.name;
+    return name === undefined ? undefined : stats.columnStats.get(name.toLowerCase());
+}
+/**
+ * The histogram-answered selectivity of the range bound(s) on `colIdx`, or undefined
+ * when the histogram cannot answer them (then the caller falls back to a shape
+ * constant).
+ *
+ * Reads the FIRST lower and FIRST upper bound in `filters` order — the same positional
+ * pick {@link claimFirstPerRole} claims and `rule-select-access-path` seeks on, so the
+ * bound being priced is the bound being served. Each bound needs a plan-time value
+ * (`f.value !== undefined`; a parameter binding has none) and a histogram verdict; a
+ * present bound that cannot be answered makes the whole factor undefined rather than
+ * half-measured. Both formulas are the engine's: a single bound is
+ * `selectivityFromHistogram` verbatim, and a two-sided range combines as
+ * `max(0, lowSel + highSel - 1)` — `CatalogStatsProvider.estimateLeaf`'s BETWEEN
+ * arithmetic, which models the two bounds as the anti-correlated pair they are rather
+ * than damped-independent conjuncts.
+ *
+ * NOTE: that is the engine's number for `v between 10 and 20` but not for the same range
+ * spelled `v > 10 and v < 20` — the engine reaches this arithmetic only from a `Between`
+ * node and folds two separate comparisons through `combineConjunctive` instead (roughly 2x
+ * looser; `estimateConjunction` carries its own note saying same-column pairing is what
+ * would fix it). The tighter number is kept here deliberately: it is the more accurate of
+ * the two, and a claimed range leaves no residual `Filter` carrying the engine's competing
+ * estimate for the optimizer to compare it against. If the engine ever pairs same-column
+ * bounds the two spellings converge with no change on this side; if a plan is measured
+ * going wrong on the gap before then, it is the ENGINE's conjunction that should move.
+ */
+function rangeBoundSelectivity(stats, colStats, filters, colIdx) {
+    const histogram = colStats.histogram;
+    if (!histogram)
+        return undefined;
+    const boundSel = (ops) => {
+        const bound = filters.find(f => f.columnIndex === colIdx && ops.includes(f.op));
+        if (!bound)
+            return { present: false, sel: undefined };
+        return {
+            present: true,
+            sel: bound.value === undefined
+                ? undefined
+                : selectivityFromHistogram(histogram, bound.op, bound.value, stats.rowCount),
+        };
+    };
+    const low = boundSel(LOWER_BOUND_OPS);
+    const high = boundSel(UPPER_BOUND_OPS);
+    if ((low.present && low.sel === undefined) || (high.present && high.sel === undefined))
+        return undefined;
+    if (low.sel !== undefined && high.sel !== undefined)
+        return Math.max(0, low.sel + high.sel - 1);
+    return low.sel ?? high.sel;
+}
+/**
+ * The per-predicate row estimate for one arm: equality columns in `eqCols`, plus — for
+ * the `range` / `prefixRange` arms — the bound on `rangeCol`.
+ *
+ * **The design rule this implements: the estimate must be the number the engine's
+ * `CatalogStatsProvider` would produce for the same predicate.** A seek's advertised
+ * `rows` and the estimate the residual `Filter` above it carries describe the same row
+ * set; two different numbers would have the optimizer comparing two different worlds. So
+ * every formula here is `estimateLeaf`'s — equality is `1 / max(distinctCount, 1)`, a
+ * bound is the histogram's verdict ({@link rangeBoundSelectivity}) — and the factors
+ * combine through the engine's own `combineConjunctive` (damped independence), never a
+ * restated product.
+ *
+ * `statsBacked` — the flag the veto, the multi-seek's resolution charge, and `vetoCost`
+ * all key off — means the estimate is per-QUERY rather than a shape constant: every
+ * equality column had real statistics, and at least one factor was measured. An arm that
+ * is not statistics-backed returns exactly {@link ARM_SELECTIVITY}'s constant, so an
+ * un-analyzed table plans byte-identically to the pre-statistics module. A missing
+ * equality column falls back WHOLESALE (no mixing a measured factor with a constant);
+ * only a `prefixRange` arm's unanswerable BOUND degrades softly, contributing the arm
+ * constant as its factor while the measured prefix keeps the estimate per-query.
+ *
+ * A fraction of `request.estimatedRows`, deliberately, even though the histogram/NDV
+ * numbers are ratios of `statistics.rowCount`: `estimatedRows` is the figure the rest of
+ * the plan was costed with, and both snapshots come from the same `ANALYZE` unless the
+ * planner overrode the size — in which case following the override is the engine-wide
+ * rule (see `sizeRequestFromLiveCount`).
+ */
+function resolveArmEstimate(tableInfo, filters, arm, eqCols, rangeCol) {
+    const fallback = { selectivity: ARM_SELECTIVITY[arm], statsBacked: false };
+    const stats = tableInfo.statistics;
+    // A snapshot taken while the table was EMPTY describes nothing — every `distinctCount`
+    // is 0, no histogram was built — so it is treated as no statistics at all rather than
+    // applied. Both halves of the design rule demand it: the engine short-circuits the same
+    // case (`estimatePredicateSelectivity` returns 0 outright on `rowCount === 0` and never
+    // reaches `estimateLeaf`'s formulas), and applying the snapshot anyway reads `1 / max(0,
+    // 1)` as "this equality matches EVERY row" — the opposite extreme — which prices the arm
+    // above a scan and hands the veto a table it should never have judged. That is reachable
+    // in ordinary use: `analyze` in a bootstrap script that runs before the data load leaves
+    // the request sized from the LIVE row count while these numbers still say zero, so every
+    // equality on the table would scan until someone re-analyzed it.
+    if (!stats || stats.rowCount <= 0)
+        return fallback;
+    const factors = [];
+    for (const colIdx of eqCols) {
+        const colStats = columnStatsFor(tableInfo, stats, colIdx);
+        if (!colStats)
+            return fallback;
+        // NOTE: `1/D` assumes uniformity, so an equality on a skewed column (a 99/1
+        // two-valued flag) is still mispriced for the common value. The histogram carries
+        // per-bucket distinct counts and could answer equality too, but the engine's
+        // `CatalogStatsProvider.estimateLeaf` prices `=` as `1/D`, and this file's design
+        // rule is to match it — if a skewed equality is ever measured planning wrong, move
+        // BOTH the engine and this factor to the histogram together.
+        //
+        // NOTE: `distinctCount` counts distinct NON-NULL values but the factor is applied
+        // against the full row count, so a mostly-NULL column over-estimates its matches
+        // (NULL rows never match an equality). Same treatment as skew: the engine prices it
+        // this way, so this file does too — fix both together or neither.
+        factors.push(1 / Math.max(colStats.distinctCount, 1));
+    }
+    if (rangeCol !== undefined) {
+        const colStats = columnStatsFor(tableInfo, stats, rangeCol);
+        const boundFactor = colStats
+            ? rangeBoundSelectivity(stats, colStats, filters, rangeCol)
+            : undefined;
+        if (boundFactor !== undefined) {
+            factors.push(boundFactor);
+        }
+        else if (eqCols.length === 0) {
+            // A pure `range` arm with no histogram answer has no measured factor at all —
+            // that IS the fallback case, not a degraded estimate.
+            return fallback;
+        }
+        else {
+            // `prefixRange` with a measured prefix: the bound alone degrades to the arm
+            // constant as its factor; the estimate stays per-query on the prefix's strength.
+            factors.push(ARM_SELECTIVITY[arm]);
+        }
+    }
+    return { selectivity: combineConjunctive(factors), statsBacked: true };
+}
 /**
  * Build `handledFilters` by claiming ONLY the constraints `rule-select-access-path`
  * actually consumes: per seek column the FIRST '=' (equality seek), or the FIRST lower
@@ -215,9 +335,18 @@ function resolvePrimaryKeyPins(filters, pkColumns) {
  * K for an undecorated text PK member. The secondary-index arm never sees it: index key
  * bytes encode under each index column's own collation, so {@link tryIndexAccessPlan}
  * judges its filters against that instead.
+ *
+ * `costProfile` is the BACKEND's declared price for a random point read and a seek key,
+ * resolved once per module (`StoreModuleBase.costProfile`) and passed in for the same
+ * reason `tableKeyCollation` is: this function reads no module state of its own.
  */
-export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation) {
+export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation, costProfile) {
     const estimatedRows = request.estimatedRows ?? 1000;
+    // Whether ANY pushed filter is a runtime-valued set. Detected once, on the REQUEST:
+    // such a request is engine-synthesized (`rule-key-set-seek`'s probes, or the key-set
+    // semi join itself) and must never be answered with this module's own scan verdict,
+    // whichever arm ends up serving it — see the exemption at the seek-vs-scan comparison.
+    const requestCarriesRuntimeSet = request.filters.some(f => f.runtimeSet !== undefined);
     const pkColumns = tableInfo.primaryKeyDefinition.map(pk => pk.index);
     // 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
@@ -279,7 +408,7 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
             .build();
     }
     if (pkPins) {
-        const plan = primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pkPins, estimatedRows, pkOrderPreservingPrefix);
+        const plan = primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pkPins, estimatedRows, pkOrderPreservingPrefix, costProfile);
         // 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
@@ -342,7 +471,7 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
     for (const index of indexes) {
         if (index.columns.length === 0)
             continue;
-        const candidate = tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows);
+        const candidate = tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows, costProfile);
         if (!candidate)
             continue;
         const { plan } = candidate;
@@ -360,38 +489,54 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
             costOnlyFallback = plan;
     }
     if (bestSeekPlan) {
+        // Two narrow exemptions skip the seek-vs-scan comparison outright:
+        //
+        //  - **A request carrying a runtime-valued set** (`filter.runtimeSet`). Such a
+        //    request is only ever built by the engine — `rule-key-set-seek`'s synthesized
+        //    probes and the key-set semi join itself — and the engine reads a probe answer
+        //    that names no index as "the module declined", abandoning the whole rewrite.
+        //    So this module must NEVER substitute its own scan verdict there: the engine
+        //    makes the scan comparison itself, interpolating a break-even from the module's
+        //    costs at 2 and 1000 keys. Detected on the REQUEST rather than on the winning
+        //    arm, because the probe must survive whichever arm this module happens to pick
+        //    for it. (Substituting a scan verdict at 1000 keys was MEASURED to fail 11
+        //    tests in `key-set-seek-store.spec.ts` on 200-and-300-row tables where the seek
+        //    is unambiguously right at the key counts actually used.)
+        //  - **A multi-seek whose row estimate is not statistics-backed.** Its
+        //    `min(N, inCount × 0.1N)` union reaches the whole table at ten seek keys, so
+        //    beyond that the figure is a CLAMP rather than an estimate — vetoing on it
+        //    would judge the estimator's artifact. A statistics-backed multi-seek clamps
+        //    only at `inCount ≈ distinctCount`, which is the honest saturation point, so it
+        //    faces the comparison like every other arm — a literal `col in (…900 values…)`
+        //    over an analyzed 100-row table now correctly loses to the scan.
         //
-        // 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.
+        // **The comparison judges the candidate at `vetoCost`, which is `plan.cost` itself
+        // exactly when the arm's row estimate is statistics-backed.** A per-query estimate
+        // lets the backend's declared profile decide the arm's fate per query: on
+        // IndexedDB (`pointRead: 3.0`) the `range` arm's break-even is
+        // 1/(0.5 + 3.0) ≈ 0.286 of the table, so a range the histogram puts at 25% seeks
+        // and one it puts at 35% scans — the discrimination the declared profile exists to
+        // buy. An arm still priced by an {@link ARM_SELECTIVITY} shape constant is instead
+        // judged at PARITY `pointRead`, settled when the IndexedDB profile was measured:
+        // a fixed fraction makes the veto arm-DISABLING rather than arm-tuning (the
+        // flip-point arithmetic is at the top of this file, where the profile's terms are
+        // introduced), IndexedDB's measured band straddles the `range` arm's flip point
+        // exactly, and the error is wildly asymmetric — disabling the arm costs up to 25×
+        // when the real predicate is selective, keeping it costs ~10% in the case the
+        // constant describes. So the declared profile decides per QUERY once the estimate
+        // is real, and falls back to the parity price where the estimate is still a shape
+        // constant. `cost-profile.spec.ts` pins both halves of that policy.
         //
         // Ties keep the seek: it returns fewer rows for the rest of the plan to carry.
-        if (bestSeekPlan.isMultiSeek || bestSeekPlan.plan.cost <= scanPlan.cost)
+        const exemptFromVeto = requestCarriesRuntimeSet
+            || (bestSeekPlan.isMultiSeek && !bestSeekPlan.statsBacked);
+        if (exemptFromVeto || bestSeekPlan.vetoCost <= 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
@@ -425,7 +570,7 @@ export function computeBestAccessPlan(db, tableInfo, request, tableKeyCollation)
  * 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) {
+function primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pins, estimatedRows, pkOrderPreservingPrefix, profile) {
     if (pins.seekKeyCount > MAX_MULTI_SEEK_KEYS)
         return null;
     // Mirrors `StoreTableScan.pkHasSemanticOrderingMember`, which `scanMultiSeekPrimary`
@@ -437,8 +582,16 @@ function primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pins, estimatedR
     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.
+    // artifact (contrast the secondary arm's), and no separate `profile.pointRead` term: the
+    // point read IS the row read, with no index-entry → row indirection to charge for.
+    //
+    // NOTE: this arm is therefore slightly OVER-charged on a backend that declares an
+    // expensive profile — `profile.seekPositioning` prices "position an index window AND
+    // read the row it names", and here there is no index window (IndexedDB: ≈ 3 units of
+    // real cost, charged 5). Accepted rather than split into a third knob: a second
+    // multi-seek term would double the tuning surface to model a bias whose only effect is
+    // that a very large `where pk in (…)` prefers a scan slightly sooner than it should.
+    // Revisit only if a primary-key IN is ever measured planning wrong because of it.
     //
     // `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
@@ -449,7 +602,7 @@ function primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pins, estimatedR
     const plan = AccessPlanBuilder
         // `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)
+        .eqMatch(rows, pins.seekKeyCount * profile.seekPositioning)
         .setIsSet(false)
         .setIndexName('_primary_')
         // EVERY primary-key column, in `primaryKeyDefinition` order: `scanMultiSeekPrimary`
@@ -459,12 +612,20 @@ function primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pins, estimatedR
         .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.
+    // This arm returns straight out of the PK branch, so it never reaches the seek-versus-scan
+    // comparison further down `computeBestAccessPlan` — structurally what the secondary arms
+    // state as `requestCarriesRuntimeSet`, and ONE rule for both: a request the engine
+    // synthesized to probe this module must never be answered with the module's own scan
+    // verdict. `rule-key-set-seek` reads this cost as a straight line at 2 and 1000 keys and
+    // abandons its whole rewrite if either probe stops naming an index; the engine makes the
+    // scan comparison itself, off the break-even it interpolates from those two costs. Do not
+    // "fix" this by adding the comparison.
+    //
+    // The PK arm is exempt unconditionally where the secondary arms are exempt per request,
+    // and that is not a divergence: a literal `where pk in (…)` is priced honestly here with
+    // or without statistics (the PK is unique, so `D = N` and `min(estimatedRows, K)` already
+    // IS the per-predicate estimate — nothing for `ANALYZE` to sharpen), so there is no
+    // clamp artifact for a veto to correct.
     //
     // `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
@@ -502,14 +663,22 @@ function primaryKeyMultiSeekPlan(tableInfo, request, pkColumns, pins, estimatedR
  * 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.
+ * **Rows.** Each arm's row estimate comes from {@link resolveArmEstimate}: per-predicate
+ * when the table's `ANALYZE`-collected statistics cover the arm's columns, the
+ * {@link ARM_SELECTIVITY} shape constant otherwise — with `statsBacked` recording which.
+ *
+ * **Cost.** Each single-window seek arm pays the backend's declared `profile.pointRead`
+ * 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. A cost-only decline deliberately does not pay it (it
+ * resolves nothing; the scan reads rows directly), and the multi-seek pays it exactly when
+ * its row estimate is statistics-backed — the reason is recorded at that arm below. Every
+ * candidate also carries a `vetoCost`, the price the seek-vs-scan comparison in
+ * {@link computeBestAccessPlan} judges it at: the declared cost itself for a
+ * statistics-backed arm, the arm repriced at PARITY `pointRead` otherwise (reasoning at
+ * that site).
  */
-function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
+function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows, profile) {
     // Exclude PARTIAL indexes from access planning: neither the engine nor this
     // module checks that the query's WHERE implies the index predicate, so seeking
     // a partial index for a query it doesn't cover would silently drop the rows the
@@ -574,20 +743,31 @@ function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
         seekCols = eqCols;
     }
     const isRange = arm !== 'eq';
-    const rows = Math.max(1, Math.floor(estimatedRows * ARM_SELECTIVITY[arm]));
+    // Resolved AFTER the prefixRange→eq degradation above, so the estimate prices the arm
+    // actually advertised (a degraded arm's unclaimed bound survives in the residual and
+    // must not narrow this estimate). For a multi-seek, `eq`'s estimate is PER SEEK KEY —
+    // one full equality tuple — which is exactly what the union arithmetic below wants.
+    const { selectivity, statsBacked } = resolveArmEstimate(tableInfo, request.filters, arm, arm === 'range' ? [] : eqCols, arm === 'eq' ? undefined : (arm === 'range' ? leadingCol : trailingRangeCol));
+    const rows = Math.max(1, Math.floor(estimatedRows * selectivity));
     /** 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()
+    /** The arm's shape plus one per-fetched-row resolution term at the given price. */
+    const seekingArm = (pointRead) => armShape().addCost(rows * pointRead);
+    const costOnly = (why) => {
+        const 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,
-    });
+            .build();
+        return {
+            plan,
+            // Cost-only resolves nothing, so its cost carries no `pointRead` term to reprice —
+            // and it never reaches the comparison anyway (it claims no seek columns).
+            vetoCost: plan.cost,
+            // Likewise immaterial; false states the fact — this plan seeks nothing at all.
+            isMultiSeek: false,
+            statsBacked,
+        };
+    };
     if (arm === 'range') {
         if (!indexRangeAtPositionIsOrderSafe(db, tableInfo.columns, index, indexKeyCollations, 0)) {
             return costOnly('cost-only; index range needs an order-preserving key collation');
@@ -631,13 +811,16 @@ function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
         // 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:
+        // **This arm pays the per-row `profile.pointRead` exactly when `statsBacked`.** It
+        // resolves every entry it matches, like the single-window arms do, so the physics
+        // always says charge it; what varies is whether `multiRows` is an ESTIMATE worth
+        // charging against — and that is precisely what `statsBacked` records.
+        //
+        // UNBACKED, `rows` is the fixed 0.1 × N equality shape constant, so
+        // `min(N, inCount × rows)` reaches the whole table at ten seek keys, and at two or
+        // three on a handful-of-rows table. Beyond that the figure is a CLAMP — "the whole
+        // table" — rather than an estimate of what the keys match, and 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
@@ -645,36 +828,74 @@ function tryIndexAccessPlan(db, tableInfo, request, index, estimatedRows) {
         //     `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.
+        //
+        // BACKED, `rows` is `N/D` for the seek column, so `inCount × rows` only reaches N as
+        // `inCount` approaches `D` — the honest saturation point (at `inCount = D` the IN list
+        // really does name every value the column holds). The two failure modes above both
+        // dissolve there: the 3-to-4-row key-set tables are covered by the `runtimeSet`
+        // exemption at the veto site regardless of statistics, and the probe cost stays a
+        // straight line in K (`K·seekPositioning + min(N, K·N/D)·(0.3 + pointRead)`) until the
+        // clamp bites at `K ≈ D`, which is where a scan genuinely is cheaper.
+        //
+        // NOTE: charging it DOES change which key-set semi joins the engine rewrites. The
+        // engine fits a chord through this cost at 2 and 1000 keys and solves for a break-even;
+        // the honest cost is higher, so a rewrite stops firing once the seek keys approach the
+        // table's own row count — 1000 keys over a 1000-row table now scans, correctly. The
+        // answer never moves (`column-statistics-plan.spec.ts` pins that), and large tables are
+        // untouched (10k keys into 10M rows is still nowhere near the clamp). If an ANALYZE is
+        // ever measured making a real key-set join SLOWER, the thing to look at is the chord,
+        // not this term: the true cost is concave (linear, then flat once `multiRows` clamps at
+        // `K = D`), so a two-point interpolation under-reads it in between.
+        //
+        // Charging it also fixes the mis-ranking the unbacked case still carries: against
+        // another index's `eq` arm (which always pays the term) a small-key IN looks cheaper
+        // than it is — `where a in (x, y) and b = ?` over an un-analyzed 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. `ANALYZE` is now the fix for that; the residual unbacked case
+        // is backlog/debt-store-multi-seek-union-row-estimate.
         const multiRows = Math.min(estimatedRows, inCount * rows);
+        const multiSeekShape = AccessPlanBuilder.eqMatch(multiRows, inCount * profile.seekPositioning);
+        if (statsBacked)
+            multiSeekShape.addCost(multiRows * profile.pointRead);
+        const plan = multiSeekShape
+            .setIsSet(false)
+            .setHandledFilters(handledFilters)
+            .setIndexName(index.name)
+            .setSeekColumns(seekCols)
+            .setExplanation(`Store index multi-seek(${inCount}) on ${index.name}`)
+            .build();
         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(),
+            plan,
+            // Statistics-backed: the declared profile decides this arm's fate per query, so the
+            // veto price IS the declared price. Unbacked: no `pointRead` term was charged, so
+            // there is nothing to reprice at parity — and the arm is exempt from the veto
+            // anyway. `plan.cost` is right either way.
+            vetoCost: plan.cost,
             isMultiSeek: true,
+            statsBacked,
         };
     }
     const armLabel = arm === 'prefixRange'
         ? `prefix-range seek(prefix=${eqCols.length})`
         : arm === 'range' ? 'range scan' : 'seek';
+    const plan = seekingArm(profile.pointRead)
+        .setHandledFilters(handledFilters)
+        .setIndexName(index.name)
+        .setSeekColumns(seekCols)
+        .setExplanation(`Store index ${armLabel} on ${index.name}`)
+        .build();
     return {
-        plan: seekingArm()
-            .setHandledFilters(handledFilters)
-            .setIndexName(index.name)
-            .setSeekColumns(seekCols)
-            .setExplanation(`Store index ${armLabel} on ${index.name}`)
-            .build(),
+        plan,
+        // Statistics-backed: `rows` discriminates per query, so the backend's DECLARED price
+        // decides this arm's fate per query — that discrimination is what declaring a profile
+        // buys. Otherwise judged at parity, because a shape constant makes the veto
+        // arm-disabling rather than arm-tuning (full reasoning at the veto site). The parity
+        // price is re-derived from `armShape()` rather than adjusted off `plan.cost`, so it is
+        // the exact number the pre-profile module produced rather than a float round trip
+        // through the declared one.
+        vetoCost: statsBacked ? plan.cost : seekingArm(PARITY_COST_PROFILE.pointRead).build().cost,
         isMultiSeek: false,
+        statsBacked,
     };
 }
 /**