@quereus/quereus 3.3.0 → 4.1.0

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

@@ -16,9 +16,12 @@ 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 { compareSqlValues, normalizeCollationName } from '../../../util/comparison.js';
 import { FilterNode } from '../../nodes/filter.js';
 import { extractConstraintsForTable, createTableInfoFromNode } from '../../analysis/constraint-extractor.js';
-import { LiteralNode } from '../../nodes/scalar.js';
+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';
 const log = createLogger('optimizer:rule:select-access-path');
 /**
@@ -177,27 +180,7 @@ function selectPhysicalNode(tableRef, accessPlan, constraints) {
     // Empty result optimization (e.g., IS NULL on NOT NULL column)
     if (accessPlan.rows === 0 && accessPlan.handledFilters.every(h => h)) {
         log('Using empty result (impossible predicate detected)');
-        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 createEmptyResultNode(tableRef);
     }
     // Create a default FilterInfo for the physical nodes
     const filterInfo = {
@@ -238,6 +221,9 @@ function selectPhysicalNode(tableRef, accessPlan, constraints) {
  */
 function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInfo, providesOrdering) {
     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;
@@ -272,29 +258,57 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         }
     }
     if (allEquality && eqBySeekCol.size === seekCols.length) {
+        // 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
+        // unsafe mismatch; keep the seek and re-apply a residual when the index is a
+        // provable superset (BINARY predicate over a coarser index). See
+        // `index-collation-mismatch-residual-filter`.
+        const cover = classifyCollationCover(seekCols.map(colIdx => ({ colIdx, constraint: eqBySeekCol.get(colIdx) })), true, indexColumnCollationLookup(tableRef.tableSchema, accessPlan), honorsCollatedRangeBounds);
+        if (!cover.useIndex) {
+            log('Declining index seek on %s (collation mismatch) — sequential scan + residual', physicalIndexName);
+            const scan = createSeqScan(tableRef);
+            return cover.residual ? new FilterNode(tableRef.scope, scan, cover.residual) : scan;
+        }
+        const finishSeek = (leaf) => cover.residual ? new FilterNode(tableRef.scope, leaf, cover.residual) : leaf;
         // Check for multi-value IN on a single-column seek (simple case)
         const hasMultiValueIn = [...eqBySeekCol.values()].some(c => c.op === 'IN' && Array.isArray(c.value) && c.value.length > 1);
         if (hasMultiValueIn && seekCols.length === 1) {
             // Multi-seek: IN on single-column index
             const colIdx = seekCols[0];
             const inConstraint = eqBySeekCol.get(colIdx);
-            const inValues = inConstraint.value;
-            // Use valueExpr nodes when available (mixed-binding IN from OR collapse),
-            // otherwise construct literal nodes from values
-            const seekKeys = Array.isArray(inConstraint.valueExpr)
-                ? inConstraint.valueExpr
-                : inValues.map(v => literalFromValue(tableRef.scope, v));
-            const inConstraints = inValues.map((_v, i) => ({
+            const rawValues = inConstraint.value;
+            let seekKeys;
+            if (Array.isArray(inConstraint.valueExpr)) {
+                // Mixed-binding IN (from OR collapse): some values are dynamic, so the
+                // runtime scan-layer dedup/NULL-skip stays authoritative — keep the raw
+                // list and let it perform set-membership at execution time.
+                seekKeys = inConstraint.valueExpr;
+            }
+            else {
+                // Pure-literal IN: collapse duplicate literals and drop NULLs so the
+                // advertised inCount reflects the effective distinct non-null seek count.
+                const effectiveValues = reduceLiteralSeekValues(rawValues);
+                if (effectiveValues.length === 0) {
+                    // Every seek key is NULL ⇒ no row can match. Emit an empty result
+                    // rather than a zero-key multi-seek (inCount=0 would parse back to no
+                    // equalityKeys and degrade to an unbounded full-index walk).
+                    log('IN-list is entirely NULL literals on %s — using empty result', physicalIndexName);
+                    return createEmptyResultNode(tableRef);
+                }
+                seekKeys = effectiveValues.map(v => literalFromValue(tableRef.scope, v));
+            }
+            const inConstraints = seekKeys.map((_sk, i) => ({
                 constraint: { iColumn: colIdx, op: IndexConstraintOp.EQ, usable: true },
                 argvIndex: i + 1,
             }));
             const fi = {
                 ...filterInfo,
                 constraints: inConstraints,
-                idxStr: `idx=${idxStrName}(0);plan=5;inCount=${inValues.length}`,
+                idxStr: `idx=${idxStrName}(0);plan=5;inCount=${seekKeys.length}`,
             };
-            log('Using index multi-seek on %s (IN with %d values)', physicalIndexName, inValues.length);
-            return new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement);
+            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));
         }
         if (hasMultiValueIn && seekCols.length > 1) {
             // Composite IN multi-seek: generate cross-product of all column values
@@ -314,9 +328,39 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
                     columnValues.push({ colIdx, values: [val] });
                 }
             }
-            // Compute cross-product of value indices
-            const crossProduct = cartesianProduct(columnValues.map(cv => cv.values.map((_v, i) => i)));
             const seekWidth = seekCols.length;
+            // A column is pure-literal iff its constraint carries no value expression
+            // (a `valueExpr` is present only for dynamic/parameter or mixed bindings).
+            // When every component is literal we can reduce the cross-product at plan
+            // time; otherwise the runtime scan-layer dedup/NULL-skip is authoritative.
+            const allLiteral = seekCols.every(colIdx => eqBySeekCol.get(colIdx).valueExpr === undefined);
+            if (allLiteral) {
+                // Build the cross-product of actual literal tuples, then drop any tuple
+                // with a NULL component and collapse duplicates so inCount reflects the
+                // effective distinct non-null seek count.
+                const valueTuples = cartesianProduct(columnValues.map(cv => cv.values));
+                const effectiveTuples = reduceLiteralSeekTuples(valueTuples);
+                if (effectiveTuples.length === 0) {
+                    // Every cross-product tuple is NULL-bearing ⇒ no row can match.
+                    log('Composite IN cross-product on %s is entirely NULL-bearing — using empty result', physicalIndexName);
+                    return createEmptyResultNode(tableRef);
+                }
+                const seekKeys = effectiveTuples.flatMap(tuple => tuple.map(v => literalFromValue(tableRef.scope, v)));
+                const seekConstraints = seekKeys.map((_sk, i) => ({
+                    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}`,
+                };
+                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));
+            }
+            // Dynamic/mixed composite: keep the raw cross-product over value indices and
+            // let the runtime perform set-membership at execution time.
+            const crossProduct = cartesianProduct(columnValues.map(cv => cv.values.map((_v, i) => i)));
             // Build seekKeys — one ScalarPlanNode per value in flattened cross-product
             const seekKeys = crossProduct.flatMap(combo => combo.map((valueIdx, colPos) => {
                 const cv = columnValues[colPos];
@@ -336,7 +380,15 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
                 idxStr: `idx=${idxStrName}(0);plan=5;inCount=${crossProduct.length};seekWidth=${seekWidth}`,
             };
             log('Using composite index multi-seek on %s (cross-product of %d seeks, width %d)', physicalIndexName, crossProduct.length, seekWidth);
-            return new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement);
+            return finishSeek(new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement));
+        }
+        // A literal NULL in any seek column makes the (row-value) equality UNKNOWN ⇒
+        // no row can match. Emit an empty result rather than a doomed point-seek so
+        // EXPLAIN stays honest (EmptyResult, not a degraded IndexSeek/SeqScan). A
+        // dynamic `valueExpr` is left to the scan-layer runtime guard (Part A).
+        if ([...eqBySeekCol.values()].some(isLiteralNullEquality)) {
+            log('Equality seek on %s has a literal NULL key — using empty result', physicalIndexName);
+            return createEmptyResultNode(tableRef);
         }
         // Standard equality seek on all seek columns
         const seekKeys = seekCols.map(colIdx => {
@@ -356,7 +408,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             idxStr: `idx=${idxStrName}(0);plan=2`,
         };
         log('Using index seek on %s (equality)', physicalIndexName);
-        return new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement);
+        return finishSeek(new IndexSeekNode(tableRef.scope, tableRef, fi, physicalIndexName, seekKeys, false, providesOrdering, accessPlan.cost, advertisement));
     }
     // Check for prefix-equality + trailing-range pattern
     if (!allEquality && seekCols.length > 1) {
@@ -377,6 +429,44 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
             }
         }
         if (prefixEqCols.length > 0 && trailingRangeCol !== undefined) {
+            // 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) {
+                log('Prefix-range seek on %s has a literal NULL prefix key — using empty result', physicalIndexName);
+                return createEmptyResultNode(tableRef);
+            }
+            // Collation-cover: any collation mismatch on a prefix-range seek reorders
+            // 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);
+                if (!cover.useIndex) {
+                    log('Declining prefix-range seek on %s (collation mismatch) — sequential scan + residual', physicalIndexName);
+                    const scan = createSeqScan(tableRef);
+                    return cover.residual ? new FilterNode(tableRef.scope, scan, cover.residual) : scan;
+                }
+            }
             const seekKeys = [];
             const allConstraints = [];
             let argv = 1;
@@ -424,6 +514,22 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         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));
+        // 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 = [];
+            if (lower)
+                consumed.push({ colIdx: rangeCol, constraint: lower });
+            if (upper)
+                consumed.push({ colIdx: rangeCol, constraint: upper });
+            const cover = classifyCollationCover(consumed, 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);
+                return cover.residual ? new FilterNode(tableRef.scope, scan, cover.residual) : scan;
+            }
+        }
         const seekKeys = [];
         const rangeConstraints = [];
         let argv = 1;
@@ -450,6 +556,17 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
         seekCols.includes(c.columnIndex) && handledByCol.has(c.columnIndex));
     if (orRangeConstraint && orRangeConstraint.ranges) {
         const ranges = orRangeConstraint.ranges;
+        // 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.
+        {
+            const cover = classifyCollationCover([{ colIdx: orRangeConstraint.columnIndex, constraint: orRangeConstraint }], false, indexColumnCollationLookup(tableRef.tableSchema, accessPlan), honorsCollatedRangeBounds);
+            if (!cover.useIndex) {
+                log('Declining OR_RANGE seek on %s (collation mismatch) — sequential scan + residual', physicalIndexName);
+                const scan = createSeqScan(tableRef);
+                return cover.residual ? new FilterNode(tableRef.scope, scan, cover.residual) : scan;
+            }
+        }
         // Build seekKeys: for each range, emit lower value then upper value
         // Encode which ops each range has in rangeOps string
         const seekKeys = [];
@@ -508,6 +625,7 @@ function selectPhysicalNodeFromPlan(tableRef, accessPlan, constraints, filterInf
  */
 function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo, providesOrdering) {
     const advertisement = extractAdvertisement(accessPlan);
+    const honorsCollatedRangeBounds = accessPlan.honorsCollatedRangeBounds === true;
     // Analyze the access plan to determine node type
     const handledByCol = new Set();
     constraints.forEach((c, i) => {
@@ -525,6 +643,25 @@ function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo,
     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) {
+        // 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).
+        if (pkCols.some(pk => {
+            const c = eqByCol.get(pk.index);
+            return c !== undefined && isLiteralNullEquality(c);
+        })) {
+            log('PK equality seek has a literal NULL key — using empty result (legacy)');
+            return createEmptyResultNode(tableRef);
+        }
+        // Collation-cover: a PK seek whose column collation differs from the
+        // predicate's effective collation over/under-fetches. Keep the seek + residual
+        // for a coarser PK collation; decline to a scan + residual otherwise.
+        const cover = classifyCollationCover(pkCols.map(pk => ({ colIdx: pk.index, constraint: eqByCol.get(pk.index) })), true, primaryKeyCollationLookup(tableRef.tableSchema), honorsCollatedRangeBounds);
+        if (!cover.useIndex) {
+            log('Declining PK index seek (collation mismatch) — sequential scan + residual (legacy)');
+            const scan = createSeqScan(tableRef);
+            return cover.residual ? new FilterNode(tableRef.scope, scan, cover.residual) : scan;
+        }
         const seekKeys = pkCols.map(pk => {
             const c = eqByCol.get(pk.index);
             if (c.valueExpr && !Array.isArray(c.valueExpr))
@@ -541,7 +678,8 @@ function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo,
             idxStr: 'idx=_primary_(0);plan=2',
         };
         log('Using index seek on primary key (legacy)');
-        return new IndexSeekNode(tableRef.scope, tableRef, fi, 'primary', seekKeys, false, providesOrdering, accessPlan.cost, advertisement);
+        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
@@ -550,6 +688,21 @@ function selectPhysicalNodeLegacy(tableRef, accessPlan, constraints, filterInfo,
         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 === '<='));
+        // 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 = [];
+            if (lower)
+                consumed.push({ colIdx: primaryFirstCol, constraint: lower });
+            if (upper)
+                consumed.push({ colIdx: primaryFirstCol, constraint: upper });
+            const cover = classifyCollationCover(consumed, false, primaryKeyCollationLookup(tableRef.tableSchema), honorsCollatedRangeBounds);
+            if (!cover.useIndex) {
+                log('Declining PK range seek (collation mismatch) — sequential scan + residual (legacy)');
+                const scan = createSeqScan(tableRef);
+                return cover.residual ? new FilterNode(tableRef.scope, scan, cover.residual) : scan;
+            }
+        }
         const seekKeys = [];
         const rangeConstraints = [];
         let argv = 1;
@@ -639,4 +792,249 @@ function literalFromValue(scope, value) {
     const lit = { type: 'literal', value };
     return new LiteralNode(scope, lit);
 }
+/**
+ * Build the canonical empty-relation leaf used when a predicate is provably
+ * unsatisfiable (e.g. an IN-list whose literals are all NULL — every seek key
+ * is skipped at runtime). Shared by the impossible-predicate optimization and
+ * 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);
+}
+/**
+ * True when an equality constraint resolves to a *literal* SQL NULL — `col = null`
+ * or single-value `col IN (null)` carrying no dynamic value expression. SQL NULL
+ * equality is UNKNOWN under three-valued logic, so such a point-seek matches no
+ * row; the planner emits an {@link createEmptyResultNode} instead of a doomed
+ * point-seek (mirrors the all-NULL IN-list reduction in {@link reduceLiteralSeekValues}).
+ *
+ * A dynamic single `valueExpr` (parameter/correlated binding) is deliberately NOT
+ * treated as literal: its NULL-ness is unknown at plan time and is handled by the
+ * scan-layer runtime guard (`seekKeyHasNull`) instead. This mirrors the
+ * literal-vs-dynamic discrimination used where `seekKeys` are materialized
+ * (`c.valueExpr && !Array.isArray(c.valueExpr)` ⇒ dynamic). A dynamic single-value
+ * `IN (?)` carries an *array* `valueExpr` and an `undefined` placeholder value, so
+ * the effective-value check below also rejects it.
+ */
+function isLiteralNullEquality(c) {
+    if (c.valueExpr && !Array.isArray(c.valueExpr))
+        return false;
+    const val = c.op === 'IN' && Array.isArray(c.value)
+        ? c.value[0]
+        : c.value;
+    return val === null;
+}
+/**
+ * Reduce a list of *literal* IN seek values to the effective distinct, non-null
+ * set, so the multi-seek's advertised `inCount` matches the number of seeks the
+ * runtime actually performs. Mirrors the runtime set-membership semantics in
+ * `scan-layer.ts`: a NULL seek key contributes no match (skipped), and duplicate
+ * seek keys collapse.
+ *
+ * This is a strict *subset* of the runtime dedup — it only collapses values that
+ * are equal under the default binary comparator, since the column's collation is
+ * unknown at plan time. The runtime remains the authority and may collapse
+ * further (e.g. NOCASE case-variants that hit the same index entry). Literal-only:
+ * dynamic/parameter seek values are never reduced here.
+ */
+function reduceLiteralSeekValues(values) {
+    const result = [];
+    for (const v of values) {
+        if (v === null)
+            continue;
+        if (result.some(kept => compareSqlValues(kept, v) === 0))
+            continue;
+        result.push(v);
+    }
+    return result;
+}
+/**
+ * Composite analogue of {@link reduceLiteralSeekValues}: drop any cross-product
+ * tuple with a NULL component (mirrors `scan-layer.ts`'s `seekKeyHasNull` for
+ * row-value seeks — a NULL component makes the comparison NULL ⇒ no match) and
+ * collapse duplicate tuples. Tuples are compared componentwise under the default
+ * binary comparator; literal-only, same subset rationale as the scalar case.
+ */
+function reduceLiteralSeekTuples(tuples) {
+    const result = [];
+    for (const tuple of tuples) {
+        if (tuple.some(v => v === null))
+            continue;
+        const isDup = result.some(kept => kept.length === tuple.length && kept.every((kv, i) => compareSqlValues(kv, tuple[i]) === 0));
+        if (isDup)
+            continue;
+        result.push(tuple);
+    }
+    return result;
+}
+/**
+ * Resolve a predicate constraint's effective comparison collation at plan time
+ * via the shared helpers in `analysis/comparison-collation.ts` (one resolution
+ * for plan-time facts and runtime behavior — they cannot drift): the symmetric
+ * provenance lattice (explicit COLLATE > declared column collation > defaults
+ * > BINARY). An IN merges the condition with every listed value / the subquery
+ * column (`emitIn`); a BETWEEN bound resolves against the tested expression
+ * per bound (`emitBetween`). The result is normalized.
+ */
+function effectivePredicateCollation(constraint) {
+    const src = constraint.sourceExpression;
+    if (src instanceof BinaryOpNode) {
+        return effectiveComparisonCollation(src.left, src.right);
+    }
+    if (src instanceof InNode) {
+        return effectiveInCollation(src);
+    }
+    if (src instanceof BetweenNode) {
+        // BETWEEN desugars to `expr >= lo AND expr <= hi`; each comparison
+        // resolves its collation independently through the lattice.
+        // extractBetweenConstraints emits two constraints sharing this BetweenNode
+        // source — `op: '>='`/`'>'` for the lower bound, `'<='`/`'<'` for the
+        // upper — so the constraint's op selects which bound's collation applies. A
+        // `COLLATE` on a bound survives folding (it rides on the bound's type), so
+        // the bound collation can and must reach this point.
+        const bound = (constraint.op === '<=' || constraint.op === '<') ? src.upper : src.lower;
+        return effectiveBetweenBoundCollation(src.expr, bound);
+    }
+    // OR_RANGE carries an OR BinaryOpNode source (handled above); any other shape
+    // defaults to BINARY, which only ever drives a (safe) decline on mismatch.
+    return 'BINARY';
+}
+/**
+ * Build a collation lookup for the columns of a module-provided index. Secondary
+ * index columns carry their own (already-normalized) collation; the primary key
+ * (`_primary_`/`primary`) falls back to the table column's declared collation.
+ */
+function indexColumnCollationLookup(tableSchema, accessPlan) {
+    const indexName = accessPlan.indexName;
+    const isPrimary = indexName === '_primary_' || indexName === 'primary';
+    const index = isPrimary ? undefined : tableSchema.indexes?.find(i => i.name === indexName);
+    return (colIdx) => {
+        if (isPrimary) {
+            return normalizeCollationName(tableSchema.columns[colIdx]?.collation ?? 'BINARY');
+        }
+        const idxCol = index?.columns.find(c => c.index === colIdx);
+        return normalizeCollationName(idxCol?.collation ?? 'BINARY');
+    };
+}
+/**
+ * Build a collation lookup for primary-key columns (used by the legacy seek path,
+ * which addresses the PK directly without a module-provided index identity).
+ */
+function primaryKeyCollationLookup(tableSchema) {
+    return (colIdx) => normalizeCollationName(tableSchema.columns[colIdx]?.collation ?? 'BINARY');
+}
+/**
+ * Cover relation for a single seek column. See {@link CollationCover}.
+ *
+ * `honorsCollatedRangeBounds` is the module's advertisement (off by default) that its
+ * runtime filters range bounds under the index collation rather than BINARY; it gates
+ * the non-BINARY range MATCH and is ignored for equality.
+ */
+function classifyConstraintCover(predColl, indexColl, isEquality, honorsCollatedRangeBounds) {
+    if (isEquality) {
+        if (predColl === indexColl)
+            return 'MATCH';
+        // BINARY equality ⟹ equal under any collation, so a non-BINARY index over-fetches
+        // a superset that an equality residual can recover. NOCASE/RTRIM are mutually
+        // incomparable and a finer index under-fetches — neither is salvageable.
+        if (predColl === 'BINARY' && indexColl !== 'BINARY') {
+            return 'COARSER_SAFE';
+        }
+        return 'MISMATCH_UNSAFE';
+    }
+    // Range (non-equality) seek. A BINARY-over-BINARY range always reproduces the
+    // predicate. A collation-MATCHED non-BINARY range (predColl === indexColl ≠ BINARY)
+    // reproduces it ONLY when the module's runtime filters the bounds — and
+    // early-terminates the walk — under that same index collation; the in-memory vtab
+    // does (`plan-filter.ts` / `scan-layer.ts`, threaded via `scan-plan.ts`), as does
+    // the store (collation-aware post-fetch filter, `StoreTable.compareValues`), and both
+    // advertise `honorsCollatedRangeBounds`, whereas a module that bound-filters BINARY
+    // would under-fetch case/space variants. Any collation MISMATCH reorders the walked
+    // window relative to the predicate's intended order and is never a recoverable
+    // superset (unlike a COARSER_SAFE equality), so it always declines.
+    if (predColl === indexColl && (predColl === 'BINARY' || honorsCollatedRangeBounds))
+        return 'MATCH';
+    return 'MISMATCH_UNSAFE';
+}
+/**
+ * Classify a seek's consumed constraints by the collation-cover relation and derive
+ * an aggregate decision:
+ *  - any `MISMATCH_UNSAFE` → decline the seek; the caller scans and re-applies the
+ *    AND of *all* consumed constraints as a residual (so the scan stays filtered).
+ *  - else all `MATCH` → use the seek with no residual.
+ *  - else (some `COARSER_SAFE`) → use the seek but re-apply the AND of the
+ *    `COARSER_SAFE` constraints as a residual to discard the over-fetched rows.
+ *
+ * `isEquality` gates the `COARSER_SAFE` class: a coarser index can only over-fetch a
+ * *superset* for an equality/IN seek. For a range/prefix-range/OR_RANGE seek a
+ * collation mismatch reorders the index, so the walked window is not a superset and
+ * any mismatch is `MISMATCH_UNSAFE`. `honorsCollatedRangeBounds` (the module's
+ * advertisement, off by default) gates the collation-matched non-BINARY range MATCH;
+ * it is forwarded to {@link classifyConstraintCover} and ignored for equality.
+ */
+function classifyCollationCover(consumed, isEquality, collationForColumn, honorsCollatedRangeBounds) {
+    const allResiduals = [];
+    const coarserResiduals = [];
+    let anyUnsafe = false;
+    for (const { colIdx, constraint } of consumed) {
+        allResiduals.push(constraint.sourceExpression);
+        const predColl = effectivePredicateCollation(constraint);
+        const indexColl = collationForColumn(colIdx);
+        const cover = classifyConstraintCover(predColl, indexColl, isEquality, honorsCollatedRangeBounds);
+        if (cover === 'COARSER_SAFE') {
+            coarserResiduals.push(constraint.sourceExpression);
+        }
+        else if (cover === 'MISMATCH_UNSAFE') {
+            anyUnsafe = true;
+        }
+    }
+    if (anyUnsafe) {
+        return { useIndex: false, residual: combineResidualExpressions(allResiduals) };
+    }
+    if (coarserResiduals.length > 0) {
+        return { useIndex: true, residual: combineResidualExpressions(coarserResiduals) };
+    }
+    return { useIndex: true };
+}
+/**
+ * AND-combine residual `sourceExpression`s into one predicate, de-duplicating by
+ * identity (a BETWEEN yields two constraints sharing one source node). Mirrors the
+ * `combineParts`/`combineResiduals` shape in constraint-extractor.ts.
+ */
+function combineResidualExpressions(exprs) {
+    const unique = [];
+    for (const e of exprs) {
+        if (!unique.includes(e))
+            unique.push(e);
+    }
+    if (unique.length === 0)
+        return undefined;
+    let acc = unique[0];
+    for (let i = 1; i < unique.length; i++) {
+        const right = unique[i];
+        const ast = { type: 'binary', operator: 'AND', left: acc.expression, right: right.expression };
+        acc = new BinaryOpNode(acc.scope, ast, acc, right);
+    }
+    return acc;
+}
 //# sourceMappingURL=rule-select-access-path.js.map