@quereus/quereus 4.3.1 → 4.4.0

package/dist/src/planner/rules/access/rule-select-access-path.js

@@ -16,6 +16,9 @@ import { RetrieveNode } from '../../nodes/retrieve-node.js';
 import { RemoteQueryNode } from '../../nodes/remote-query-node.js';
 import { SeqScanNode, IndexScanNode, IndexSeekNode, EmptyResultNode } from '../../nodes/table-access-nodes.js';
 import { seqScanCost } from '../../cost/index.js';
+import { makeEmptyFilterInfo, makeFullScanFilterInfo } from '../../../vtab/filter-info.js';
+import { PRIMARY_INDEX_NAME, PRIMARY_PHYSICAL_INDEX_NAME, resolveIndexDescriptor } from '../../../vtab/index-descriptor.js';
+import { encodeIdxStr, makeIdxStrSpec } from '../../../vtab/idx-str.js';
 import { compareSqlValues, normalizeCollationName } from '../../../util/comparison.js';
 import { FilterNode } from '../../nodes/filter.js';
 import { extractConstraintsForTable, createTableInfoFromNode } from '../../analysis/constraint-extractor.js';
@@ -23,7 +26,64 @@ import { LiteralNode, BinaryOpNode, BetweenNode } from '../../nodes/scalar.js';
 import { InNode } from '../../nodes/subquery.js';
 import { effectiveBetweenBoundCollation, effectiveComparisonCollation, effectiveInCollation } from '../../analysis/comparison-collation.js';
 import { IndexConstraintOp } from '../../../common/constants.js';
+import { isIndexStyleContext } from '../shared/index-style-context.js';
 const log = createLogger('optimizer:rule:select-access-path');
+const warnLog = createLogger('optimizer:rule:select-access-path').extend('warn');
+/**
+ * Resolve the structured {@link AccessPath} for an index arm.
+ *
+ * `indexName` is the name that lands in `idxStr` — `accessPlan.indexName` for a seek,
+ * `accessPlan.orderingIndexName` for an ordering-only walk, `_primary_` for the legacy
+ * arms. When the engine cannot resolve it (a per-plan alias the module minted without
+ * supplying an `indexDescriptor`) we record `unresolvedIndex` and warn, rather than
+ * guessing: an order-sensitive consumer must be able to refuse the plan.
+ */
+function buildIndexAccessPath(tableSchema, accessPlan, indexName, plan) {
+    const index = resolveIndexDescriptor(tableSchema, accessPlan, indexName);
+    if (index)
+        return { kind: 'index', index, plan };
+    warnLog('access plan for table %s named index %s which the engine cannot resolve; module should return indexDescriptor', tableSchema.name, indexName);
+    return { kind: 'unresolvedIndex', indexName, plan };
+}
+/**
+ * Derive a seek/scan FilterInfo from the arm's shared `base`: the encoded `idxStr` and
+ * the structured `accessPath` are both projections of the same (indexName, plan, params)
+ * triple, so they cannot drift.
+ */
+function makeIndexFilterInfo(base, tableSchema, accessPlan, indexName, plan, constraints, params) {
+    const idxStr = encodeIdxStr(makeIdxStrSpec(indexName, plan, params));
+    return {
+        ...base,
+        constraints,
+        idxStr,
+        accessPath: buildIndexAccessPath(tableSchema, accessPlan, indexName, plan),
+        indexInfoOutput: {
+            ...base.indexInfoOutput,
+            idxStr,
+            // Reflect the seek's consumed constraints so EXPLAIN's matchedClauses
+            // counts them; `base` is seeded from a full scan and carries none.
+            aConstraintUsage: constraints.map(c => ({ argvIndex: c.argvIndex, omit: true })),
+        },
+    };
+}
+/**
+ * Derive the FilterInfo for an ordering-only index walk (`plan=0`). Unlike a seek this
+ * also stamps `indexInfoOutput.idxStr` and `orderByConsumed`, because the runtime reads
+ * the consumed-ordering flag off the IndexInfo rather than the FilterInfo.
+ */
+function makeOrderedScanFilterInfo(base, tableSchema, accessPlan, indexName) {
+    const idxStr = encodeIdxStr(makeIdxStrSpec(indexName, 'scan'));
+    return {
+        ...base,
+        idxStr,
+        accessPath: buildIndexAccessPath(tableSchema, accessPlan, indexName, 'scan'),
+        indexInfoOutput: {
+            ...base.indexInfoOutput,
+            idxStr,
+            orderByConsumed: true,
+        },
+    };
+}
 /**
  * Extract the monotonic-ordering advertisement from a `BestAccessPlanResult`,
  * or return undefined when nothing is advertised. The result is forwarded to
@@ -117,7 +177,7 @@ function createIndexBasedAccess(retrieveNode, context) {
         // Use pre-computed access plan from grow rule
         log('Using pre-computed access plan from grow rule');
         accessPlan = retrieveNode.moduleCtx.accessPlan;
-        constraints = retrieveNode.moduleCtx.originalConstraints || [];
+        constraints = retrieveNode.moduleCtx.originalConstraints;
         residualPredicate = retrieveNode.moduleCtx.residualPredicate;
     }
     else {
@@ -141,7 +201,14 @@ function createIndexBasedAccess(retrieveNode, context) {
     }
     // Choose physical node based on access plan
     const physicalLeaf = selectPhysicalNode(retrieveNode.tableRef, accessPlan, constraints);
-    // If the Retrieve source contained a pipeline (e.g., Filter/Sort/Project), rebuild it above the physical leaf
+    // If the Retrieve source contained a pipeline (e.g., Filter/Sort/Project), rebuild it above the physical leaf.
+    //
+    // NOTE: on this path (no index-style moduleCtx) an absorbed `Filter` in `source` is
+    // preserved verbatim, so a constraint that `reattachUnconsumedConstraints` recovers is
+    // already applied above — the reattached `Filter` is then redundant, not wrong. Only
+    // reachable for a module exposing BOTH `supports()` (declining here) and
+    // `getBestAccessPlan()`. If that ever shows up as a duplicated predicate in EXPLAIN,
+    // pass the consumed set out and skip the reattach when `source !== tableRef`.
     let rebuiltPipeline = physicalLeaf;
     if (retrieveNode.source !== retrieveNode.tableRef) {
         log('Rebuilding Retrieve pipeline above physical access node');
@@ -173,6 +240,45 @@ function rebuildPipelineWithNewLeaf(pipelineRoot, oldLeaf, newLeaf) {
     });
     return pipelineRoot.withChildren(newChildren);
 }
+/**
+ * The constraint operators this rule can turn into seek bounds, and therefore the
+ * only ones {@link reattachUnconsumedConstraints} can recover when a module claims
+ * a filter the rule never consumes.
+ *
+ * NOTE: ops outside this set (IS NULL / IS NOT NULL / LIKE / GLOB / MATCH / NOT IN) are never
+ * pushed into FilterInfo by this rule, so a module claiming one is taken at its word.
+ * Sound today: the only such claim is memory's tautological IS NOT NULL on a NOT NULL
+ * column. If a module ever claims a non-tautological non-seek op, its predicate is lost
+ * — widen this set, or make grow-retrieve refuse the claim.
+ */
+const RECLAIMABLE_OPS = new Set(['=', 'IN', '>', '>=', '<', '<=', 'OR_RANGE']);
+/**
+ * `handledFilters[i] === true` is a module's promise that filter `i` will be enforced
+ * somewhere else — and the only "somewhere else" available is `FilterInfo.constraints`
+ * (the seek bounds this rule builds). This rule consumes at most one constraint per
+ * column per role: the first `=`/`IN`, the first lower bound, the first upper bound.
+ * A module that claims a redundant same-column same-role filter (`v > 10 and v > 30`)
+ * therefore hands the planner a predicate that is seeked nowhere and — because
+ * `rule-grow-retrieve` residualizes only *unhandled* constraints — filtered nowhere.
+ *
+ * Reattach those as a residual `Filter` so an over-claiming module costs a redundant
+ * predicate evaluation, never a wrong answer. Skipped for an `EmptyResultNode` leaf
+ * (filtering an empty relation is dead weight) and restricted to {@link RECLAIMABLE_OPS}.
+ */
+function reattachUnconsumedConstraints(tableRef, accessPlan, constraints, consumed, leaf) {
+    if (leaf instanceof EmptyResultNode)
+        return leaf;
+    const lost = constraints.filter((c, i) => accessPlan.handledFilters[i] === true
+        && !consumed.has(c)
+        && RECLAIMABLE_OPS.has(c.op));
+    if (lost.length === 0)
+        return leaf;
+    const predicate = combineResidualExpressions(lost.map(c => c.sourceExpression));
+    if (!predicate)
+        return leaf;
+    log('Reattaching %d handled-but-unconsumed constraint(s) as a residual filter', lost.length);
+    return new FilterNode(tableRef.scope, leaf, predicate);
+}
 /**
  * Select the appropriate physical node based on access plan
  */
@@ -182,51 +288,34 @@ function selectPhysicalNode(tableRef, accessPlan, constraints) {
         log('Using empty result (impossible predicate detected)');
         return createEmptyResultNode(tableRef);
     }
-    // Create a default FilterInfo for the physical nodes
-    const filterInfo = {
-        idxNum: 0,
-        idxStr: 'fullscan',
-        constraints: [],
-        args: [],
-        indexInfoOutput: {
-            nConstraint: 0,
-            aConstraint: [],
-            nOrderBy: 0,
-            aOrderBy: [],
-            aConstraintUsage: [],
-            idxNum: 0,
-            idxStr: 'fullscan',
-            orderByConsumed: false,
-            estimatedCost: accessPlan.cost,
-            estimatedRows: BigInt(accessPlan.rows || 1000),
-            idxFlags: 0,
-            colUsed: 0n,
-        }
-    };
+    // Default FilterInfo for the physical nodes. Each index arm below spreads this and
+    // overrides `idxStr` / `accessPath` for the index it chose.
+    const filterInfo = makeFullScanFilterInfo(accessPlan.cost, accessPlan.rows || 1000);
     // Convert OrderingSpec[] to the format expected by physical nodes
     const providesOrdering = accessPlan.providesOrdering?.map(spec => ({
         column: spec.columnIndex,
         desc: spec.desc
     }));
+    const consumed = new Set();
     // --- Index-aware path: use module-provided index identity ---
-    if (accessPlan.indexName && accessPlan.seekColumnIndexes && accessPlan.seekColumnIndexes.length > 0) {
-        return selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInfo, providesOrdering);
-    }
     // --- Legacy fallback: infer access method from constraints and PK definition ---
-    return selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo, providesOrdering);
+    const leaf = (accessPlan.indexName && accessPlan.seekColumnIndexes && accessPlan.seekColumnIndexes.length > 0)
+        ? selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInfo, providesOrdering, consumed)
+        : selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo, providesOrdering, consumed);
+    return reattachUnconsumedConstraints(tableRef, accessPlan, constraints, consumed, leaf);
 }
 /**
  * Index-aware physical node selection using module-provided indexName and seekColumnIndexes.
  * Works for both primary key and secondary indexes.
  */
-function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInfo, providesOrdering) {
+function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInfo, providesOrdering, consumed) {
     const advertisement = extractAdvertisement(accessPlan);
     // Whether this module's runtime honours the index collation for range bounds —
     // gates the collation-matched non-BINARY range/prefix seek (see classifyConstraintCover).
     const honorsCollatedRangeBounds = accessPlan.honorsCollatedRangeBounds === true;
     const seekCols = accessPlan.seekColumnIndexes;
     // Map accessPlan.indexName to physical node indexName ('_primary_' → 'primary')
-    const physicalIndexName = accessPlan.indexName === '_primary_' ? 'primary' : accessPlan.indexName;
+    const physicalIndexName = accessPlan.indexName === PRIMARY_INDEX_NAME ? PRIMARY_PHYSICAL_INDEX_NAME : accessPlan.indexName;
     // idxStr uses the raw name (scan-plan builder maps '_primary_' → 'primary')
     const idxStrName = accessPlan.indexName;
     // Build a map of constraints by column index for quick lookup
@@ -242,6 +331,14 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         if (accessPlan.handledFilters[i] === true)
             handledByCol.add(c.columnIndex);
     });
+    // Per-column, per-role pickers. Each returns the FIRST constraint in `constraints`
+    // order filling that role — the positional contract module authors must claim
+    // against (see docs/module-authoring.md). Redundant same-role duplicates are never
+    // picked and are recovered by `reattachUnconsumedConstraints`.
+    const isHandled = (c) => handledByCol.has(c.columnIndex);
+    const findPrefixEq = (colIdx) => (constraintsByCol.get(colIdx) ?? []).find(c => (c.op === '=' || (c.op === 'IN' && Array.isArray(c.value) && c.value.length === 1)) && isHandled(c));
+    const findLower = (colIdx) => (constraintsByCol.get(colIdx) ?? []).find(c => (c.op === '>' || c.op === '>=') && isHandled(c));
+    const findUpper = (colIdx) => (constraintsByCol.get(colIdx) ?? []).find(c => (c.op === '<' || c.op === '<=') && isHandled(c));
     // Check if all seek columns have equality constraints (=, single-value IN, or multi-value IN)
     const eqBySeekCol = new Map();
     let allEquality = true;
@@ -258,6 +355,11 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         }
     }
     if (allEquality && eqBySeekCol.size === seekCols.length) {
+        // Every arm below returns, and each consumes exactly the per-seek-column
+        // equality constraints — as seek keys, or (on a collation decline) as the
+        // residual re-applied above the scan.
+        for (const c of eqBySeekCol.values())
+            consumed.add(c);
         // Collation-cover analysis: a seek over an index whose per-column collation
         // differs from the predicate's effective comparison collation is NOT a
         // complete substitute for the predicate. Decline (scan + residual) on an
@@ -302,11 +404,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
                 constraint: { iColumn: colIdx, op: IndexConstraintOp.EQ, usable: true },
                 argvIndex: i + 1,
             }));
-            const fi = {
-                ...filterInfo,
-                constraints: inConstraints,
-                idxStr: `idx=${idxStrName}(0);plan=5;inCount=${seekKeys.length}`,
-            };
+            const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'multiSeek', inConstraints, new Map([['inCount', String(seekKeys.length)]]));
             log('Using index multi-seek on %s (IN with %d values)', physicalIndexName, seekKeys.length);
             return finishSeek(new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement));
         }
@@ -357,11 +455,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
                     constraint: { iColumn: seekCols[i % seekWidth], op: IndexConstraintOp.EQ, usable: true },
                     argvIndex: i + 1,
                 }));
-                const fi = {
-                    ...filterInfo,
-                    constraints: seekConstraints,
-                    idxStr: `idx=${idxStrName}(0);plan=5;inCount=${effectiveTuples.length};seekWidth=${seekWidth}`,
-                };
+                const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'multiSeek', seekConstraints, new Map([['inCount', String(effectiveTuples.length)], ['seekWidth', String(seekWidth)]]));
                 log('Using composite index multi-seek on %s (cross-product of %d distinct non-null seeks, width %d)', physicalIndexName, effectiveTuples.length, seekWidth);
                 return finishSeek(new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement));
             }
@@ -381,11 +475,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
                 constraint: { iColumn: seekCols[i % seekWidth], op: IndexConstraintOp.EQ, usable: true },
                 argvIndex: i + 1,
             }));
-            const fi = {
-                ...filterInfo,
-                constraints: seekConstraints,
-                idxStr: `idx=${idxStrName}(0);plan=5;inCount=${crossProduct.length};seekWidth=${seekWidth}`,
-            };
+            const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'multiSeek', seekConstraints, new Map([['inCount', String(crossProduct.length)], ['seekWidth', String(seekWidth)]]));
             log('Using composite index multi-seek on %s (cross-product of %d seeks, width %d)', physicalIndexName, crossProduct.length, seekWidth);
             return finishSeek(new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement));
         }
@@ -403,11 +493,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             constraint: { iColumn: colIdx, op: IndexConstraintOp.EQ, usable: true },
             argvIndex: i + 1,
         }));
-        const fi = {
-            ...filterInfo,
-            constraints: eqConstraints,
-            idxStr: `idx=${idxStrName}(0);plan=2`,
-        };
+        const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'eqSeek', eqConstraints);
         log('Using index seek on %s (equality)', physicalIndexName);
         return finishSeek(new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement));
     }
@@ -416,31 +502,34 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         const prefixEqCols = [];
         let trailingRangeCol;
         for (const colIdx of seekCols) {
-            const colConstraints = constraintsByCol.get(colIdx) ?? [];
-            const eqConstraint = colConstraints.find(c => (c.op === '=' || (c.op === 'IN' && Array.isArray(c.value) && c.value.length === 1)) &&
-                handledByCol.has(c.columnIndex));
-            if (eqConstraint) {
+            if (findPrefixEq(colIdx)) {
                 prefixEqCols.push(colIdx);
             }
             else {
-                const hasRange = colConstraints.some(c => ['>', '>=', '<', '<='].includes(c.op) && handledByCol.has(c.columnIndex));
-                if (hasRange)
+                if (findLower(colIdx) || findUpper(colIdx))
                     trailingRangeCol = colIdx;
                 break;
             }
         }
         if (prefixEqCols.length > 0 && trailingRangeCol !== undefined) {
+            const prefixConstraints = prefixEqCols.map(colIdx => ({ colIdx, constraint: findPrefixEq(colIdx) }));
+            const lower = findLower(trailingRangeCol);
+            const upper = findUpper(trailingRangeCol);
+            // Every arm below returns, consuming the prefix equalities plus the first
+            // lower/upper trailing bound — as seek keys, or (on a collation decline) as
+            // the residual re-applied above the scan.
+            for (const { constraint } of prefixConstraints)
+                consumed.add(constraint);
+            if (lower)
+                consumed.add(lower);
+            if (upper)
+                consumed.add(upper);
             // A literal NULL in any prefix-equality column makes every row-value
             // comparison UNKNOWN ⇒ no match. Emit an empty result rather than relying
             // on the runtime prefix walk breaking on the first row. Part A does not
             // cover this path (it walks via `equalityPrefix`, not `equalityKey`), so
             // the plan-time check is the robustness guarantee here.
-            const prefixHasLiteralNull = prefixEqCols.some(colIdx => {
-                const c = (constraintsByCol.get(colIdx) ?? []).find(c => (c.op === '=' || (c.op === 'IN' && Array.isArray(c.value) && c.value.length === 1)) &&
-                    handledByCol.has(c.columnIndex));
-                return c !== undefined && isLiteralNullEquality(c);
-            });
-            if (prefixHasLiteralNull) {
+            if (prefixConstraints.some(({ constraint }) => isLiteralNullEquality(constraint))) {
                 log('Prefix-range seek on %s has a literal NULL prefix key — using empty result', physicalIndexName);
                 return createEmptyResultNode(tableRef);
             }
@@ -448,20 +537,12 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             // the walked index window (it is no longer a contiguous superset), so it
             // cannot be salvaged with a residual — decline to a scan + residual.
             {
-                const consumed = [];
-                for (const colIdx of prefixEqCols) {
-                    const c = (constraintsByCol.get(colIdx) ?? []).find(c => (c.op === '=' || (c.op === 'IN' && Array.isArray(c.value) && c.value.length === 1)) &&
-                        handledByCol.has(c.columnIndex));
-                    consumed.push({ colIdx, constraint: c });
-                }
-                const trailing = constraintsByCol.get(trailingRangeCol) ?? [];
-                const lo = trailing.find(c => (c.op === '>' || c.op === '>=') && handledByCol.has(c.columnIndex));
-                const hi = trailing.find(c => (c.op === '<' || c.op === '<=') && handledByCol.has(c.columnIndex));
-                if (lo)
-                    consumed.push({ colIdx: trailingRangeCol, constraint: lo });
-                if (hi)
-                    consumed.push({ colIdx: trailingRangeCol, constraint: hi });
-                const cover = classifyCollationCover(consumed, false, indexColumnCollationLookup(tableRef.tableSchema, accessPlan), honorsCollatedRangeBounds);
+                const coverConstraints = [...prefixConstraints];
+                if (lower)
+                    coverConstraints.push({ colIdx: trailingRangeCol, constraint: lower });
+                if (upper)
+                    coverConstraints.push({ colIdx: trailingRangeCol, constraint: upper });
+                const cover = classifyCollationCover(coverConstraints, false, indexColumnCollationLookup(tableRef.tableSchema, accessPlan), honorsCollatedRangeBounds);
                 if (!cover.useIndex) {
                     log('Declining prefix-range seek on %s (collation mismatch) — sequential scan + residual', physicalIndexName);
                     const scan = createSeqScan(tableRef);
@@ -472,17 +553,12 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             const allConstraints = [];
             let argv = 1;
             // Add prefix equality values
-            for (const colIdx of prefixEqCols) {
-                const c = (constraintsByCol.get(colIdx) ?? []).find(c => (c.op === '=' || (c.op === 'IN' && Array.isArray(c.value) && c.value.length === 1)) &&
-                    handledByCol.has(c.columnIndex));
-                seekKeys.push(equalitySeekKey(tableRef.scope, c));
+            for (const { colIdx, constraint } of prefixConstraints) {
+                seekKeys.push(equalitySeekKey(tableRef.scope, constraint));
                 allConstraints.push({ constraint: { iColumn: colIdx, op: IndexConstraintOp.EQ, usable: true }, argvIndex: argv });
                 argv++;
             }
             // Add trailing range values
-            const trailingConstraints = constraintsByCol.get(trailingRangeCol) ?? [];
-            const lower = trailingConstraints.find(c => (c.op === '>' || c.op === '>=') && handledByCol.has(c.columnIndex));
-            const upper = trailingConstraints.find(c => (c.op === '<' || c.op === '<=') && handledByCol.has(c.columnIndex));
             if (lower) {
                 allConstraints.push({ constraint: { iColumn: trailingRangeCol, op: opToIndexOp(lower.op), usable: true }, argvIndex: argv });
                 seekKeys.push(lower.valueExpr && !Array.isArray(lower.valueExpr) ? lower.valueExpr : literalFromValue(tableRef.scope, lower.value));
@@ -493,35 +569,43 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
                 seekKeys.push(upper.valueExpr && !Array.isArray(upper.valueExpr) ? upper.valueExpr : literalFromValue(tableRef.scope, upper.value));
                 argv++;
             }
-            const fi = {
-                ...filterInfo,
-                constraints: allConstraints,
-                idxStr: `idx=${idxStrName}(0);plan=7;prefixLen=${prefixEqCols.length}`,
-            };
+            const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'prefixRangeSeek', allConstraints, new Map([['prefixLen', String(prefixEqCols.length)]]));
             log('Using index prefix-range seek on %s (prefix=%d cols)', physicalIndexName, prefixEqCols.length);
             return new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, true, providesOrdering, accessPlan.cost, advertisement);
         }
     }
-    // Check for range constraints on the seek columns
-    // Use the first (or only) seek column that has range constraints
-    const rangeCol = seekCols.find(colIdx => {
-        const colConstraints = constraintsByCol.get(colIdx) ?? [];
-        return colConstraints.some(c => ['>', '>=', '<', '<='].includes(c.op) && handledByCol.has(c.columnIndex));
-    });
+    // Check for range constraints on the LEADING seek column only. A standalone range
+    // seek emits its bounds positionally into `seekKeys` and the runtime applies them to
+    // the index's leading column, so a range on a *later* seek column is usable only via
+    // the prefix-range path above — which requires every preceding seek column to be
+    // pinned by a single-valued equality. Picking a later column here would bound the
+    // leading column with the wrong value and silently drop rows (`a in (1,2) and b > 15`
+    // over an index on `(a, b)`: the multi-value IN is not a prefix key, so `b`'s bound
+    // would be seeked against `a`). When the leading column carries no bound we decline;
+    // `reattachUnconsumedConstraints` re-applies the claimed range as a residual.
+    const leadingSeekCol = seekCols[0];
+    const rangeCol = (leadingSeekCol !== undefined && (findLower(leadingSeekCol) || findUpper(leadingSeekCol)))
+        ? leadingSeekCol
+        : undefined;
     if (rangeCol !== undefined) {
-        const colConstraints = constraintsByCol.get(rangeCol) ?? [];
-        const lower = colConstraints.find(c => (c.op === '>' || c.op === '>=') && handledByCol.has(c.columnIndex));
-        const upper = colConstraints.find(c => (c.op === '<' || c.op === '<=') && handledByCol.has(c.columnIndex));
+        const lower = findLower(rangeCol);
+        const upper = findUpper(rangeCol);
+        // Both arms below return, consuming the first lower/upper bound — as seek
+        // bounds, or (on a collation decline) as the residual above the scan.
+        if (lower)
+            consumed.add(lower);
+        if (upper)
+            consumed.add(upper);
         // Collation-cover: a range seek under a collation that differs from the
         // predicate's reorders the index window, so it is never a superset — decline
         // to a scan + residual on any mismatch.
         {
-            const consumed = [];
+            const coverConstraints = [];
             if (lower)
-                consumed.push({ colIdx: rangeCol, constraint: lower });
+                coverConstraints.push({ colIdx: rangeCol, constraint: lower });
             if (upper)
-                consumed.push({ colIdx: rangeCol, constraint: upper });
-            const cover = classifyCollationCover(consumed, false, indexColumnCollationLookup(tableRef.tableSchema, accessPlan), honorsCollatedRangeBounds);
+                coverConstraints.push({ colIdx: rangeCol, constraint: upper });
+            const cover = classifyCollationCover(coverConstraints, false, indexColumnCollationLookup(tableRef.tableSchema, accessPlan), honorsCollatedRangeBounds);
             if (!cover.useIndex) {
                 log('Declining range seek on %s (collation mismatch) — sequential scan + residual', physicalIndexName);
                 const scan = createSeqScan(tableRef);
@@ -541,11 +625,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             seekKeys.push(upper.valueExpr && !Array.isArray(upper.valueExpr) ? upper.valueExpr : literalFromValue(tableRef.scope, upper.value));
             argv++;
         }
-        const fi = {
-            ...filterInfo,
-            constraints: rangeConstraints,
-            idxStr: `idx=${idxStrName}(0);plan=3`,
-        };
+        const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'rangeSeek', rangeConstraints);
         log('Using index seek (range) on %s', physicalIndexName);
         return new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, true, providesOrdering, accessPlan.cost, advertisement);
     }
@@ -554,6 +634,9 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         seekCols.includes(c.columnIndex) && handledByCol.has(c.columnIndex));
     if (orRangeConstraint && orRangeConstraint.ranges) {
         const ranges = orRangeConstraint.ranges;
+        // Both arms below return, consuming this OR_RANGE — as the multi-range seek's
+        // bounds, or (on a collation decline) as the residual above the scan.
+        consumed.add(orRangeConstraint);
         // Collation-cover: an OR_RANGE seek walks multiple index windows whose order
         // follows the index collation; any mismatch makes them non-supersets, so
         // decline to a scan + residual.
@@ -589,28 +672,16 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             constraint: { iColumn: orRangeConstraint.columnIndex, op: IndexConstraintOp.GE, usable: true },
             argvIndex: i + 1,
         }));
-        const fi = {
-            ...filterInfo,
-            constraints: orRangeConstraints,
-            idxStr: `idx=${idxStrName}(0);plan=6;rangeCount=${ranges.length};rangeOps=${rangeOps.join(',')}`,
-        };
+        const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, idxStrName, 'multiRangeSeek', orRangeConstraints, new Map([['rangeCount', String(ranges.length)], ['rangeOps', rangeOps.join(',')]]));
         log('Using index multi-range seek on %s (%d ranges)', physicalIndexName, ranges.length);
         return new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, true, providesOrdering, accessPlan.cost, advertisement);
     }
     // Ordering-only index scan
     if (providesOrdering) {
         const orderingIndexName = accessPlan.orderingIndexName ?? physicalIndexName;
-        const orderingIdxStr = orderingIndexName === 'primary' ? '_primary_' : orderingIndexName;
+        const orderingIdxStr = orderingIndexName === PRIMARY_PHYSICAL_INDEX_NAME ? PRIMARY_INDEX_NAME : orderingIndexName;
         log('Using index scan (ordering provided by %s)', orderingIndexName);
-        const orderingFilterInfo = {
-            ...filterInfo,
-            idxStr: `idx=${orderingIdxStr}(0);plan=0`,
-            indexInfoOutput: {
-                ...filterInfo.indexInfoOutput,
-                idxStr: `idx=${orderingIdxStr}(0);plan=0`,
-                orderByConsumed: true,
-            }
-        };
+        const orderingFilterInfo = makeOrderedScanFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, orderingIdxStr);
         return new IndexScanNode(tableRef.scope, tableRef, orderingFilterInfo, orderingIndexName, providesOrdering, accessPlan.cost, advertisement);
     }
     // Fall back to sequential scan
@@ -621,7 +692,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
  * Legacy physical node selection for backward compatibility when module
  * doesn't provide indexName/seekColumnIndexes (PK-based heuristics).
  */
-function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo, providesOrdering) {
+function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo, providesOrdering, consumed) {
     const advertisement = extractAdvertisement(accessPlan);
     const honorsCollatedRangeBounds = accessPlan.honorsCollatedRangeBounds === true;
     // Analyze the access plan to determine node type
@@ -630,17 +701,27 @@ function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo,
         if (accessPlan.handledFilters[i] === true)
             handledByCol.add(c.columnIndex);
     });
-    const eqHandled = constraints.filter(c => c.op === '=');
-    const hasEqualityConstraints = eqHandled.length > 0;
+    // Every '=' constraint, handled or not: an unhandled one still makes a sound seek key
+    // (grow-retrieve keeps it in the residual), so it may complete a PK cover.
+    const eqConstraints = constraints.filter(c => c.op === '=');
+    const hasEqualityConstraints = eqConstraints.length > 0;
     const hasRangeConstraints = constraints.some(c => ['>', '>=', '<', '<='].includes(c.op) && handledByCol.has(c.columnIndex));
     const maybeRows = accessPlan.rows || 0;
     const pkCols = tableRef.tableSchema.primaryKeyDefinition ?? [];
+    // FIRST '=' per column, matching the positional contract the index-aware path and
+    // `docs/module-authoring.md` state. Keeping the last would seek on a constraint a
+    // module claiming positionally never expected to be consumed.
     const eqByCol = new Map();
-    for (const c of eqHandled)
-        eqByCol.set(c.columnIndex, c);
+    for (const c of eqConstraints)
+        if (!eqByCol.has(c.columnIndex))
+            eqByCol.set(c.columnIndex, c);
     const coversPk = pkCols.length > 0 && pkCols.every(pk => eqByCol.has(pk.index));
     const treatAsHandledPk = coversPk && pkCols.every(pk => handledByCol.has(pk.index) || eqByCol.has(pk.index));
     if ((hasEqualityConstraints && coversPk || treatAsHandledPk) && maybeRows <= 10) {
+        // Every arm below returns, consuming the per-PK-column equality — as a seek
+        // key, or (on a collation decline) as the residual re-applied above the scan.
+        for (const pk of pkCols)
+            consumed.add(eqByCol.get(pk.index));
         // A literal NULL in any PK column makes the point-seek UNKNOWN ⇒ no row can
         // match. Emit an empty result instead of a doomed seek (mirrors the
         // index-aware path; the scan-layer runtime guard covers the dynamic case).
@@ -665,31 +746,38 @@ function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo,
             constraint: { iColumn: pk.index, op: IndexConstraintOp.EQ, usable: true },
             argvIndex: i + 1,
         }));
-        const fi = {
-            ...filterInfo,
-            constraints: eqConstraints,
-            idxStr: 'idx=_primary_(0);plan=2',
-        };
+        const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, PRIMARY_INDEX_NAME, 'eqSeek', eqConstraints);
         log('Using index seek on primary key (legacy)');
         const pkSeek = new IndexSeekNode(tableRef.scope, tableRef, fi, 'primary', seekKeys, false, providesOrdering, accessPlan.cost, advertisement);
         return cover.residual ? new FilterNode(tableRef.scope, pkSeek, cover.residual) : pkSeek;
     }
-    if (hasRangeConstraints) {
-        const rangeCols = constraints
-            .filter(c => ['>', '>=', '<', '<='].includes(c.op) && handledByCol.has(c.columnIndex))
-            .sort((a, b) => a.columnIndex - b.columnIndex);
-        const primaryFirstCol = (tableRef.tableSchema.primaryKeyDefinition?.[0]?.index) ?? (rangeCols[0]?.columnIndex ?? 0);
-        const lower = rangeCols.find(c => c.columnIndex === primaryFirstCol && (c.op === '>' || c.op === '>='));
-        const upper = rangeCols.find(c => c.columnIndex === primaryFirstCol && (c.op === '<' || c.op === '<='));
+    const rangeCols = constraints
+        .filter(c => ['>', '>=', '<', '<='].includes(c.op) && handledByCol.has(c.columnIndex))
+        .sort((a, b) => a.columnIndex - b.columnIndex);
+    const primaryFirstCol = (tableRef.tableSchema.primaryKeyDefinition?.[0]?.index) ?? (rangeCols[0]?.columnIndex ?? 0);
+    const lower = rangeCols.find(c => c.columnIndex === primaryFirstCol && (c.op === '>' || c.op === '>='));
+    const upper = rangeCols.find(c => c.columnIndex === primaryFirstCol && (c.op === '<' || c.op === '<='));
+    // A PK range seek needs at least one bound on the LEADING PK column: seek keys are
+    // positional and the runtime walks the primary key. When every handled range sits on
+    // a later PK column there is nothing to seek with, and a zero-key `IndexSeekNode`
+    // would be a full index walk dressed up as a seek. Decline instead — the claimed
+    // range comes back as a residual via `reattachUnconsumedConstraints`.
+    if (hasRangeConstraints && (lower || upper)) {
+        // Both arms below return, consuming the first lower/upper bound on the leading
+        // PK column — as seek bounds, or (on a collation decline) as the scan residual.
+        if (lower)
+            consumed.add(lower);
+        if (upper)
+            consumed.add(upper);
         // Collation-cover: a PK range seek under a mismatched collation reorders the
         // walked window, so decline to a scan + residual on any mismatch.
         {
-            const consumed = [];
+            const coverConstraints = [];
             if (lower)
-                consumed.push({ colIdx: primaryFirstCol, constraint: lower });
+                coverConstraints.push({ colIdx: primaryFirstCol, constraint: lower });
             if (upper)
-                consumed.push({ colIdx: primaryFirstCol, constraint: upper });
-            const cover = classifyCollationCover(consumed, false, primaryKeyCollationLookup(tableRef.tableSchema), honorsCollatedRangeBounds);
+                coverConstraints.push({ colIdx: primaryFirstCol, constraint: upper });
+            const cover = classifyCollationCover(coverConstraints, false, primaryKeyCollationLookup(tableRef.tableSchema), honorsCollatedRangeBounds);
             if (!cover.useIndex) {
                 log('Declining PK range seek (collation mismatch) — sequential scan + residual (legacy)');
                 const scan = createSeqScan(tableRef);
@@ -709,36 +797,20 @@ function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo,
             seekKeys.push(upper.valueExpr && !Array.isArray(upper.valueExpr) ? upper.valueExpr : literalFromValue(tableRef.scope, upper.value));
             argv++;
         }
-        const fi = {
-            ...filterInfo,
-            constraints: rangeConstraints,
-            idxStr: 'idx=_primary_(0);plan=3',
-        };
+        const fi = makeIndexFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, PRIMARY_INDEX_NAME, 'rangeSeek', rangeConstraints);
         log('Using index seek (range) on primary key (legacy)');
         return new IndexSeekNode(tableRef.scope, tableRef, fi, 'primary', seekKeys, true, providesOrdering, accessPlan.cost, advertisement);
     }
     if (providesOrdering) {
-        const indexName = accessPlan.orderingIndexName ?? 'primary';
+        const indexName = accessPlan.orderingIndexName ?? PRIMARY_PHYSICAL_INDEX_NAME;
         log('Using index scan (ordering provided by %s)', indexName);
-        const indexIdxStr = indexName === 'primary' ? '_primary_' : indexName;
-        const orderingFilterInfo = {
-            ...filterInfo,
-            idxStr: `idx=${indexIdxStr}(0);plan=0`,
-            indexInfoOutput: {
-                ...filterInfo.indexInfoOutput,
-                idxStr: `idx=${indexIdxStr}(0);plan=0`,
-                orderByConsumed: true,
-            }
-        };
+        const indexIdxStr = indexName === PRIMARY_PHYSICAL_INDEX_NAME ? PRIMARY_INDEX_NAME : indexName;
+        const orderingFilterInfo = makeOrderedScanFilterInfo(filterInfo, tableRef.tableSchema, accessPlan, indexIdxStr);
         return new IndexScanNode(tableRef.scope, tableRef, orderingFilterInfo, indexName, providesOrdering, accessPlan.cost, advertisement);
     }
     log('Using sequential scan (no beneficial index access)');
     return createSeqScan(tableRef, filterInfo, accessPlan.cost);
 }
-// Narrow module context originating from grow-retrieve index-style fallback
-function isIndexStyleContext(ctx) {
-    return !!ctx && typeof ctx === 'object' && ctx.kind === 'index-style';
-}
 /**
  * Create a sequential scan node
  */
@@ -746,26 +818,7 @@ function createSeqScan(tableRef, filterInfo, cost) {
     const tableRows = tableRef.estimatedRows || 1000;
     const scanCost = cost ?? seqScanCost(tableRows);
     // Create default FilterInfo if not provided
-    const effectiveFilterInfo = filterInfo || {
-        idxNum: 0,
-        idxStr: 'fullscan',
-        constraints: [],
-        args: [],
-        indexInfoOutput: {
-            nConstraint: 0,
-            aConstraint: [],
-            nOrderBy: 0,
-            aOrderBy: [],
-            aConstraintUsage: [],
-            idxNum: 0,
-            idxStr: 'fullscan',
-            orderByConsumed: false,
-            estimatedCost: scanCost,
-            estimatedRows: BigInt(tableRows),
-            idxFlags: 0,
-            colUsed: 0n,
-        }
-    };
+    const effectiveFilterInfo = filterInfo ?? makeFullScanFilterInfo(scanCost, tableRows);
     const seqScan = new SeqScanNode(tableRef.scope, tableRef, effectiveFilterInfo, scanCost);
     return seqScan;
 }
@@ -824,27 +877,7 @@ function equalitySeekKey(scope, c) {
  * the literal-IN reduction below.
  */
 function createEmptyResultNode(tableRef) {
-    const emptyFilterInfo = {
-        idxNum: 0,
-        idxStr: 'empty',
-        constraints: [],
-        args: [],
-        indexInfoOutput: {
-            nConstraint: 0,
-            aConstraint: [],
-            nOrderBy: 0,
-            aOrderBy: [],
-            aConstraintUsage: [],
-            idxNum: 0,
-            idxStr: 'empty',
-            orderByConsumed: false,
-            estimatedCost: 0,
-            estimatedRows: 0n,
-            idxFlags: 0,
-            colUsed: 0n,
-        }
-    };
-    return new EmptyResultNode(tableRef.scope, tableRef, emptyFilterInfo, 0);
+    return new EmptyResultNode(tableRef.scope, tableRef, makeEmptyFilterInfo(), 0);
 }
 /**
  * True when an equality constraint resolves to a *literal* SQL NULL — `col = null`