@quereus/quereus 4.4.1 → 4.6.0

package/dist/src/planner/rules/join/equi-pair-extractor.js

@@ -7,8 +7,8 @@ import { BinaryOpNode } from '../../nodes/scalar.js';
 import { ColumnReferenceNode } from '../../nodes/reference.js';
 import { normalizePredicate } from '../../analysis/predicate-normalizer.js';
 import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
-import { operandCollation } from '../../analysis/comparison-collation.js';
-import { normalizeCollationName } from '../../../util/comparison.js';
+import { operandCollation, isValueDiscriminatingEquality, resolveComparisonCollation, } from '../../analysis/comparison-collation.js';
+import { semanticOrderingsAgree } from '../../../util/comparison.js';
 /**
  * Check whether `source`'s `physical.ordering` covers the given equi-pair
  * columns positionally for the chosen `side` (the merge-join emitter compares
@@ -94,30 +94,52 @@ export function combineResidual(base, extras) {
  * Extract equi-join pairs and residual predicates from an ON condition.
  * Returns null if no equi-pairs are found.
  *
- * **Collation gate.** A `l = r` column pair is recognized only when both
- * columns contribute the same collation. Every physical join algorithm this
- * extraction feeds (hash / merge / bloom) now resolves the pair's comparison
- * collation through the SAME provenance lattice as the canonical scalar
- * comparison (`resolveComparisonCollation` — symmetric, so the result no longer
- * depends on which side the algorithm reads first; ticket
- * `join-key-collation-resolution-alignment`). So the historical
- * resolution-order disagreement is gone — but the gate is **deliberately kept
- * conservative** for a second, independent reason: a *merge* join also requires
- * both inputs physically ordered under the key's comparison collation, and the
- * physical ordering property (`PhysicalProperties.ordering`) is collation-blind
- * (`{column, desc}` only) — a column's advertised ordering is implicitly under
- * its OWN declared collation. Admitting an asymmetric pair (declared NOCASE vs
- * defaulted BINARY → resolves NOCASE) would compare under NOCASE a side sorted
- * under BINARY, silently breaking the merge. Requiring matched collations keeps
- * the resolved key collation equal to each input's declared sort collation, so
- * the merge stays sound without the ordering property having to carry collation.
- * Loosening this gate is therefore an optimization gated on teaching the planner
- * ordering to track collation end-to-end — out of scope here. Mismatched pairs
- * demote to the residual, where the canonical scalar comparison (right-first but
- * via the same lattice) evaluates them; if no matched pair remains, the rule
- * doesn't fire and the generic join evaluates the whole condition. (Tickets
- * `collation-blind-equality-fact-extraction`,
- * `join-key-collation-resolution-alignment`.)
+ * **Collation handling — tagged, not gated.** A `l = r` column pair is
+ * extracted regardless of whether the two sides declare the same collation;
+ * every physical join algorithm this extraction feeds resolves the pair's
+ * comparison collation through the SAME symmetric provenance lattice as the
+ * canonical scalar comparison (`resolveComparisonCollation`; ticket
+ * `join-key-collation-resolution-alignment`), so a hash/bloom key over an
+ * asymmetric pair (declared NOCASE vs defaulted BINARY → resolves NOCASE)
+ * normalizes both sides identically and matches exactly what `=` matches.
+ * The two collation-derived properties that DO differ per pair travel on the
+ * pair itself (see {@link EquiJoinPair}):
+ *
+ * - `collationsMatch` — merge join's admission bit. Merge additionally needs
+ *   both inputs physically ordered under the key's comparison collation, and
+ *   `PhysicalProperties.ordering` is collation-blind (`{column, desc}` only);
+ *   a matched declared collation is what makes each input's advertised order
+ *   equal the merge comparator's order. The selection rules
+ *   (`rule-join-physical-selection`, `rule-monotonic-merge-join`) consider
+ *   merge only for matched pairs; hash/bloom take every pair.
+ * - `valueDiscriminating` — the fact-minting bit
+ *   (`isValueDiscriminatingEquality`). A non-BINARY comparison passes
+ *   value-DIFFERENT rows ('Bob' = 'bob' NOCASE), so the physical join nodes
+ *   exclude such pairs from key coverage / FD / EC / monotonicity
+ *   propagation while still keying the join on them. (Ticket
+ *   `collation-blind-equality-fact-extraction`.)
+ *
+ * One collation shape is still declined outright: a same-rank
+ * explicit/declared *conflict* (`resolveComparisonCollation` → `conflict`,
+ * e.g. declared NOCASE vs declared RTRIM). That is a plan-time user error
+ * surfaced by `BinaryOpNode.generateType`; extraction must neither throw nor
+ * admit the pair (the emitters' lattice resolution would throw), so the
+ * conjunct stays in the residual and the error surfaces at its own site.
+ *
+ * **Semantic-ordering gate.** A pair is likewise recognized only when both sides
+ * agree on semantic ordering — neither declares a semantic-ordering logical type,
+ * or both declare the SAME one ({@link semanticOrderingsAgree}). A MIXED pair
+ * (`timespan_col = text_col`) is what `=` evaluates through its generic path's
+ * runtime duration check, so it matches 'PT1H' against 'PT60M'; a physical join
+ * key comparing raw text would silently drop that row. The gate DECLINES rather
+ * than canonicalizing the key, because merge join also needs both inputs
+ * physically sorted in its comparator's order and a `timespan` side is sorted by
+ * elapsed time while a `text` side is sorted by text — no single comparator merges
+ * those two orders, so canonicalizing would fix hash join and leave merge join
+ * unsound. Declined pairs demote to the residual and the `=` operator's own
+ * semantics apply. See `docs/types.md`
+ * § "Semantic ordering"; ticket
+ * `mixed-type-equi-join-key-drops-semantic-matches`.
  */
 export function extractEquiPairs(condition, leftAttrIds, rightAttrIds) {
     if (!condition)
@@ -136,16 +158,19 @@ export function extractEquiPairs(condition, leftAttrIds, rightAttrIds) {
         let isEqui = false;
         if (n instanceof BinaryOpNode && n.expression.operator === '=') {
             if (n.left instanceof ColumnReferenceNode && n.right instanceof ColumnReferenceNode
-                && operandCollation(n.left) === operandCollation(n.right)) {
+                && semanticOrderingsAgree(n.left.getType().logicalType, n.right.getType().logicalType)
+                && resolveComparisonCollation(n.left.getType(), n.right.getType()).kind !== 'conflict') {
                 const lId = n.left.attributeId;
                 const rId = n.right.attributeId;
+                const collationsMatch = operandCollation(n.left) === operandCollation(n.right);
+                const valueDiscriminating = isValueDiscriminatingEquality(n.left, n.right);
                 if (leftAttrIds.has(lId) && rightAttrIds.has(rId)) {
-                    equiPairs.push({ leftAttrId: lId, rightAttrId: rId });
+                    equiPairs.push({ leftAttrId: lId, rightAttrId: rId, collationsMatch, valueDiscriminating });
                     equiPairNodes.push(n);
                     isEqui = true;
                 }
                 else if (leftAttrIds.has(rId) && rightAttrIds.has(lId)) {
-                    equiPairs.push({ leftAttrId: rId, rightAttrId: lId });
+                    equiPairs.push({ leftAttrId: rId, rightAttrId: lId, collationsMatch, valueDiscriminating });
                     equiPairNodes.push(n);
                     isEqui = true;
                 }
@@ -160,33 +185,4 @@ export function extractEquiPairs(condition, leftAttrIds, rightAttrIds) {
     const residual = combineResidual(undefined, residuals);
     return { equiPairs, residual, equiPairNodes };
 }
-/**
- * Convert USING-column names into equi-pairs given the left/right attributes.
- * Returns null if no pairs could be matched.
- *
- * Applies the same matched-collation gate as {@link extractEquiPairs}: a
- * USING pair over columns with differing declared collations is rejected
- * outright (USING has no residual to demote into — the whole extraction
- * returns null so the generic join handles the condition).
- */
-export function extractEquiPairsFromUsing(usingColumns, leftAttrs, rightAttrs) {
-    if (!usingColumns || usingColumns.length === 0)
-        return null;
-    const equiPairs = [];
-    for (const colName of usingColumns) {
-        const lower = colName.toLowerCase();
-        const leftAttr = leftAttrs.find(a => a.name.toLowerCase() === lower);
-        const rightAttr = rightAttrs.find(a => a.name.toLowerCase() === lower);
-        if (leftAttr && rightAttr) {
-            const lColl = normalizeCollationName(leftAttr.type?.collationName ?? 'BINARY');
-            const rColl = normalizeCollationName(rightAttr.type?.collationName ?? 'BINARY');
-            if (lColl !== rColl)
-                return null;
-            equiPairs.push({ leftAttrId: leftAttr.id, rightAttrId: rightAttr.id });
-        }
-    }
-    if (equiPairs.length === 0)
-        return null;
-    return { equiPairs, residual: undefined, equiPairNodes: equiPairs.map(() => undefined) };
-}
 //# sourceMappingURL=equi-pair-extractor.js.map

package/dist/src/planner/rules/join/equi-pair-extractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"equi-pair-extractor.js","sourceRoot":"","sources":["../../../../../src/planner/rules/join/equi-pair-extractor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"equi-pair-extractor.js","sourceRoot":"","sources":["../../../../../src/planner/rules/join/equi-pair-extractor.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/rules/join/index-nested-loop.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Index-nested-loop candidate construction for `rule-join-physical-selection`.
+ *
+ * When a join's inner (right) side bottoms out in a plain every-row walk over a
+ * table whose module can answer an equality seek on the join key, the walk is
+ * replaced by an `IndexSeekNode` whose seek keys are column references into the
+ * OUTER row. The node above stays the logical `JoinNode`, so the existing
+ * nested-loop emitter drives it: for each outer row it installs the outer row
+ * slot and re-opens the inner pipeline, and the seek-key expressions resolve
+ * through the runtime context by attribute id — the same machinery correlated
+ * subqueries already exercise.
+ *
+ *   Join(inner, s, SeqScan(big))          Join(inner, s, IndexSeek(big, keys=[s.k]))
+ *     ON big.id = s.k              ──▶      ON big.id = s.k
+ *   reads every row of big                 one seek per row of s
+ *
+ * This module only CONSTRUCTS the candidate (recognize the shape, probe the
+ * module, cost it); the four-way cost comparison and the join rebuild live in
+ * the caller. Every gate below declines by returning null, which leaves the
+ * nested-loop / hash / merge competition unchanged.
+ *
+ * NOTE: one extra pair of `getBestAccessPlan` probes runs per qualifying
+ * equi-join, uncached (see `probeModule`). Cheap for both shipped modules;
+ * memoize by (table, seek columns) only if a third-party module with an
+ * expensive planner shows up in optimization profiles — mirrors the
+ * rule-key-set-seek tripwire.
+ */
+import type { RelationalPlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import type { EquiJoinPair } from '../../nodes/join-utils.js';
+export interface IndexNestedLoopCandidate {
+    /** Rebuilt right subtree with the access leaf replaced by the correlated seek. */
+    readonly newRight: RelationalPlanNode;
+    /** Engine-currency cost, comparable with nestedLoop/hash/merge in the caller. */
+    readonly cost: number;
+}
+/**
+ * Try to build an index-nested-loop candidate for `node`: the right subtree
+ * rebuilt with its access leaf replaced by a correlated `IndexSeekNode`, plus
+ * its engine-currency cost. Returns null when any gate declines; the caller's
+ * nested-loop / hash / merge competition is then unchanged.
+ *
+ * `equiPairs` must be non-empty and oriented left=outer / right=inner (as
+ * `extractEquiPairs` produces for this join). `outerRows` is the caller's
+ * left-side estimate — the same input hash and merge selection use.
+ */
+export declare function tryIndexNestedLoop(node: JoinNode, equiPairs: readonly EquiJoinPair[], outerRows: number, context: OptContext): IndexNestedLoopCandidate | null;
+//# sourceMappingURL=index-nested-loop.d.ts.map

package/dist/src/planner/rules/join/index-nested-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-nested-loop.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/index-nested-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAgB9D,MAAM,WAAW,wBAAwB;IACxC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAiND;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GACjB,wBAAwB,GAAG,IAAI,CA2EjC"}

package/dist/src/planner/rules/join/index-nested-loop.js

@@ -0,0 +1,285 @@
+/**
+ * Index-nested-loop candidate construction for `rule-join-physical-selection`.
+ *
+ * When a join's inner (right) side bottoms out in a plain every-row walk over a
+ * table whose module can answer an equality seek on the join key, the walk is
+ * replaced by an `IndexSeekNode` whose seek keys are column references into the
+ * OUTER row. The node above stays the logical `JoinNode`, so the existing
+ * nested-loop emitter drives it: for each outer row it installs the outer row
+ * slot and re-opens the inner pipeline, and the seek-key expressions resolve
+ * through the runtime context by attribute id — the same machinery correlated
+ * subqueries already exercise.
+ *
+ *   Join(inner, s, SeqScan(big))          Join(inner, s, IndexSeek(big, keys=[s.k]))
+ *     ON big.id = s.k              ──▶      ON big.id = s.k
+ *   reads every row of big                 one seek per row of s
+ *
+ * This module only CONSTRUCTS the candidate (recognize the shape, probe the
+ * module, cost it); the four-way cost comparison and the join rebuild live in
+ * the caller. Every gate below declines by returning null, which leaves the
+ * nested-loop / hash / merge competition unchanged.
+ *
+ * NOTE: one extra pair of `getBestAccessPlan` probes runs per qualifying
+ * equi-join, uncached (see `probeModule`). Cheap for both shipped modules;
+ * memoize by (table, seek columns) only if a third-party module with an
+ * expensive planner shows up in optimization profiles — mirrors the
+ * rule-key-set-seek tripwire.
+ */
+import { createLogger } from '../../../common/logger.js';
+import { IndexScanNode, IndexSeekNode } from '../../nodes/table-access-nodes.js';
+import { FilterNode } from '../../nodes/filter.js';
+import { ColumnReferenceNode } from '../../nodes/reference.js';
+import { BinaryOpNode } from '../../nodes/scalar.js';
+import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
+import { hasSemanticOrdering } from '../../../util/comparison.js';
+import { extractConstraints, createTableInfoFromNode } from '../../analysis/constraint-extractor.js';
+import { selectPhysicalNode } from '../access/rule-select-access-path.js';
+import { peelToAccessLeaf, rebuildChain, buildProbeRequest } from '../shared/access-leaf.js';
+import { combineResidual } from './equi-pair-extractor.js';
+import { indexNestedLoopJoinCost } from '../../cost/index.js';
+import { validateAccessPlan } from '../../../vtab/best-access-plan.js';
+const log = createLogger('optimizer:rule:index-nested-loop');
+/**
+ * The inner leaf, when it is an unconstrained every-row walk whose `FilterInfo`
+ * may be replaced wholesale: a plain full scan, or an ordering-only index walk
+ * (plan='scan'). A leaf already carrying pushed constraints had its residual
+ * Filter dropped on the module's promise to enforce them; replacing its
+ * FilterInfo with our seek would silently drop those predicates
+ * (backlog/feat-index-nested-loop-over-pushed-constraints). A pushed
+ * limit / offset is likewise a directive the seek would not honor.
+ */
+function admitLeaf(right) {
+    const leaf = peelToAccessLeaf(right);
+    if (!leaf) {
+        log('decline: right does not peel to an access leaf through Alias/Project/Filter');
+        return null;
+    }
+    const fi = leaf.filterInfo;
+    const isEveryRowWalk = fi.accessPath?.kind === 'fullScan'
+        || (fi.accessPath?.kind === 'index' && fi.accessPath.plan === 'scan');
+    if (!isEveryRowWalk || fi.constraints.length !== 0
+        || fi.limit !== undefined || fi.offset !== undefined) {
+        log('decline: leaf is not an unconstrained every-row walk');
+        return null;
+    }
+    // A leaf whose emission order absorbed a SortNode is the only thing producing
+    // the query's ORDER BY; a seek emits in seek-key order instead.
+    if (leaf instanceof IndexScanNode && leaf.orderingLoadBearing) {
+        log('decline: leaf emission order is load-bearing (absorbed a Sort)');
+        return null;
+    }
+    return leaf;
+}
+/**
+ * Resolve each equi pair to (leaf column index, outer attribute position) and
+ * apply the two type gates that keep a raw-value seek from under-fetching. The
+ * seek key is passed through verbatim (no cast is applied to a dynamic value
+ * expression), so a cross-type key (INTEGER column vs REAL key) or a
+ * semantic-ordering key type ('PT1H' ≡ 'PT60M' but byte-distinct) can miss rows
+ * `=` considers equal — and the ON condition retained above the join cannot
+ * resurrect a row the seek never returned. Same two gates as
+ * rule-key-set-seek's resolveSeekColumns.
+ */
+function resolvePairs(leaf, outer, equiPairs) {
+    const leafAttrIndex = leaf.getAttributeIndex();
+    const leafAttrs = leaf.getAttributes();
+    const outerAttrIndex = outer.getAttributeIndex();
+    const outerAttrs = outer.getAttributes();
+    const resolved = [];
+    for (const pair of equiPairs) {
+        // A TableAccessNode's attributes are the table reference's, positionally
+        // 1:1 with tableSchema.columns — so this index IS the table column index.
+        const innerCol = leafAttrIndex.get(pair.rightAttrId) ?? -1;
+        if (innerCol === -1) {
+            log('decline: join key attr %d is not a leaf column', pair.rightAttrId);
+            return null;
+        }
+        const outerIdx = outerAttrIndex.get(pair.leftAttrId) ?? -1;
+        if (outerIdx === -1) {
+            log('decline: join key attr %d is not an outer column', pair.leftAttrId);
+            return null;
+        }
+        const innerType = leafAttrs[innerCol].type;
+        const outerType = outerAttrs[outerIdx].type;
+        if (innerType.logicalType.name !== outerType.logicalType.name) {
+            log('decline: logical types differ (%s vs %s)', innerType.logicalType.name, outerType.logicalType.name);
+            return null;
+        }
+        if (hasSemanticOrdering(innerType.logicalType) || hasSemanticOrdering(outerType.logicalType)) {
+            log('decline: semantic-ordering key type %s', innerType.logicalType.name);
+            return null;
+        }
+        resolved.push({ innerCol, outerIdx });
+    }
+    return resolved;
+}
+/**
+ * Build the seek predicate: `leaf.col = outer.col` per pair, ANDed. Inner side
+ * FIRST — the constraint extractor picks the first side it can map to the
+ * probed table as "the column", so this ordering is what makes the extraction
+ * come back oriented inner-column-seeks-on-outer-value (asserted by the
+ * caller). Construction mirrors `createSortForEquiPairs`.
+ */
+function buildSeekPredicate(leaf, outer, resolved) {
+    const leafAttrs = leaf.getAttributes();
+    const outerAttrs = outer.getAttributes();
+    const conjuncts = resolved.map(({ innerCol, outerIdx }) => {
+        const innerAttr = leafAttrs[innerCol];
+        const outerAttr = outerAttrs[outerIdx];
+        const innerRef = new ColumnReferenceNode(leaf.scope, { type: 'column', table: '', name: innerAttr.name, schema: '' }, innerAttr.type, innerAttr.id, innerCol);
+        const outerRef = new ColumnReferenceNode(outer.scope, { type: 'column', table: '', name: outerAttr.name, schema: '' }, outerAttr.type, outerAttr.id, outerIdx);
+        return new BinaryOpNode(leaf.scope, { type: 'binary', operator: '=', left: innerRef.expression, right: outerRef.expression }, innerRef, outerRef);
+    });
+    // resolved is never empty (caller requires ≥1 equi pair), so combineResidual
+    // always returns a node.
+    return combineResidual(undefined, conjuncts);
+}
+/**
+ * Probe the module twice — once with the synthesized join constraints, once
+ * with no filters — and admit the seek only when the module's OWN answers say a
+ * per-row seek beats its scan (`cost` and `rows` both smaller). Comparing
+ * module currency to module currency keeps the engine's cost units out of the
+ * module's — the same discipline as rule-key-set-seek's break-even.
+ *
+ * These requests are the ENGINE's, not the user's: a module that answers one
+ * with a plan `validateAccessPlan` rejects gets logged and declined, never
+ * thrown — the user's own query ran fine before this rule probed.
+ */
+function probeModule(context, leaf, constraints) {
+    const tableSchema = leaf.tableSchema;
+    const vtabModule = leaf.source.vtabModule;
+    const getBestAccessPlan = vtabModule.getBestAccessPlan;
+    if (typeof getBestAccessPlan !== 'function') {
+        log('decline: module has no getBestAccessPlan');
+        return null;
+    }
+    const tableRows = leaf.source.estimatedRows || undefined;
+    const ask = (filters) => {
+        const request = buildProbeRequest(tableSchema, tableRows, filters);
+        const plan = getBestAccessPlan.call(vtabModule, context.db, tableSchema, request);
+        validateAccessPlan(request, plan);
+        return plan;
+    };
+    let seekPlan;
+    let scanPlan;
+    try {
+        seekPlan = ask(constraints);
+        scanPlan = ask([]);
+    }
+    catch (e) {
+        log('decline: module %s answered a synthesized probe on %s with an invalid plan: %s', tableSchema.vtabModuleName, tableSchema.name, e instanceof Error ? e.message : String(e));
+        return null;
+    }
+    if (!seekPlan.indexName || !seekPlan.seekColumnIndexes || seekPlan.seekColumnIndexes.length === 0) {
+        log('decline: module did not claim an index seek');
+        return null;
+    }
+    // Every seek column must be one of our equality constraints, and every
+    // constraint the seek consumes must be claimed handled — otherwise the
+    // module answered a different question than the one we will emit.
+    const constraintCols = new Set(constraints.map(c => c.columnIndex));
+    if (!seekPlan.seekColumnIndexes.every(col => constraintCols.has(col))) {
+        log('decline: seek columns extend beyond the join constraints');
+        return null;
+    }
+    const seekCols = new Set(seekPlan.seekColumnIndexes);
+    for (let i = 0; i < constraints.length; i++) {
+        if (seekCols.has(constraints[i].columnIndex) && seekPlan.handledFilters[i] !== true) {
+            log('decline: module claimed a seek column without handling its filter');
+            return null;
+        }
+    }
+    // A module-supplied JS residual has no place to run in this path.
+    if (seekPlan.residualFilter) {
+        log('decline: module attached a residualFilter');
+        return null;
+    }
+    // The module's own statement that a seek beats a scan on this table.
+    if (seekPlan.rows === undefined || scanPlan.rows === undefined
+        || !(seekPlan.cost < scanPlan.cost) || !(seekPlan.rows < scanPlan.rows)) {
+        log('decline: module costs do not favor the seek (seek %s/%s vs scan %s/%s)', seekPlan.cost, seekPlan.rows, scanPlan.cost, scanPlan.rows);
+        return null;
+    }
+    return seekPlan;
+}
+/**
+ * Try to build an index-nested-loop candidate for `node`: the right subtree
+ * rebuilt with its access leaf replaced by a correlated `IndexSeekNode`, plus
+ * its engine-currency cost. Returns null when any gate declines; the caller's
+ * nested-loop / hash / merge competition is then unchanged.
+ *
+ * `equiPairs` must be non-empty and oriented left=outer / right=inner (as
+ * `extractEquiPairs` produces for this join). `outerRows` is the caller's
+ * left-side estimate — the same input hash and merge selection use.
+ */
+export function tryIndexNestedLoop(node, equiPairs, outerRows, context) {
+    // Only the left-driven join types: the nested-loop emitter installs the left
+    // row slot before re-opening the right pipeline (driveFromLeft), which is
+    // what makes the correlated seek keys resolve. `right` / `full` drive from
+    // the right with no left slot installed. `cross` never reaches here (no
+    // condition ⇒ no equi pairs).
+    const jt = node.joinType;
+    if (jt !== 'inner' && jt !== 'left' && jt !== 'semi' && jt !== 'anti')
+        return null;
+    // Purity gate. Determinism is deliberately NOT gated: the nested loop
+    // already re-executes the inner side once per outer row, so replacing a scan
+    // with a seek does not change how often a non-deterministic inner runs.
+    // (rule-key-set-seek gates determinism because it drains its key source
+    // exactly once — a different execution-count contract.)
+    if (PlanNodeCharacteristics.subtreeHasSideEffects(node.right)) {
+        log('decline: right side has side effects');
+        return null;
+    }
+    const leaf = admitLeaf(node.right);
+    if (!leaf)
+        return null;
+    const resolved = resolvePairs(leaf, node.left, equiPairs);
+    if (!resolved || resolved.length === 0)
+        return null;
+    // Synthesize `leaf.col = outer.col` and run it through the same constraint
+    // extraction a pushed user predicate gets.
+    const predicate = buildSeekPredicate(leaf, node.left, resolved);
+    const tableSchema = leaf.tableSchema;
+    const tInfo = createTableInfoFromNode(leaf.source, `${tableSchema.schemaName}.${tableSchema.name}`);
+    const extraction = extractConstraints(predicate, [tInfo]);
+    const constraints = extraction.constraintsByTable.get(tInfo.relationKey) ?? [];
+    // Orientation assertion: every conjunct must have extracted as an equality
+    // on an INNER column with a correlated (per-outer-row) binding, with nothing
+    // left over. Inner-side-first construction makes this hold today; the check
+    // is here so a future extractor change declines loudly instead of seeking on
+    // the wrong column.
+    if (constraints.length !== resolved.length || extraction.residualPredicate !== undefined
+        || !constraints.every(c => c.op === '=' && c.correlated === true
+            && tInfo.columnIndexMap.has(c.attributeId))) {
+        log('decline: constraint extraction did not return %d oriented correlated equalities', resolved.length);
+        return null;
+    }
+    const seekPlan = probeModule(context, leaf, constraints);
+    if (!seekPlan)
+        return null;
+    // Reuse the full access-path machinery: collation cover (over the real
+    // `innerCol = outerCol` source expressions, so the join key's RESOLVED
+    // comparison collation is what gets checked), composite seeks, NULL
+    // handling, and reattachUnconsumedConstraints all come from
+    // selectPhysicalNode.
+    const rebuiltLeaf = selectPhysicalNode(leaf.source, seekPlan, [...constraints]);
+    // Verify an IndexSeekNode actually came back. selectPhysicalNode degrades to
+    // a SeqScan + residual on a collation decline (MISMATCH_UNSAFE — the seek
+    // would under-fetch) and to an EmptyResultNode on an "impossible" predicate;
+    // both mean no index-nested-loop here. An EmptyResultNode in particular must
+    // NOT be adopted — it would be sound only if the join key were provably
+    // literal NULL, which a dynamic per-outer-row binding never is.
+    let probe = rebuiltLeaf;
+    while (probe instanceof FilterNode)
+        probe = probe.source;
+    if (!(probe instanceof IndexSeekNode)) {
+        log('decline: selectPhysicalNode did not produce an IndexSeek (got %s)', probe.nodeType);
+        return null;
+    }
+    const newRight = rebuildChain(node.right, leaf, rebuiltLeaf);
+    const latencyMs = node.right.physical.expectedLatencyMs ?? 0;
+    const cost = indexNestedLoopJoinCost(outerRows, seekPlan.rows, latencyMs);
+    log('candidate: seek %s.%s via %s (%s rows/seek, cost %s for %s outer rows)', tableSchema.name, seekPlan.seekColumnIndexes.map(c => tableSchema.columns[c]?.name).join(','), seekPlan.indexName, seekPlan.rows, cost, outerRows);
+    return { newRight, cost };
+}
+//# sourceMappingURL=index-nested-loop.js.map

package/dist/src/planner/rules/join/index-nested-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-nested-loop.js","sourceRoot":"","sources":["../../../../../src/planner/rules/join/index-nested-loop.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/rules/join/rule-fanout-batched-outer.js

@@ -75,14 +75,14 @@ import { EagerPrefetchNode } from '../../nodes/eager-prefetch-node.js';
 import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
 const log = createLogger('optimizer:rule:fanout-batched-outer');
 /**
- * Best-available row estimate for the fan-out's outer. The leaf access node
- * carries `physical.estimatedRows` but several pass-through wrappers (notably
- * `AliasNode`) propagate it via the `.estimatedRows` getter, which the leaves do
- * not all populate — so a value can be present on the leaf's `physical` yet
- * undefined on the wrapper above it. Read the node's own estimate first, then
- * descend single-relation pass-throughs (alias/filter/sort/…) to recover the
- * leaf's estimate. A multi-relation node (a join outer in a subquery cluster)
- * returns `undefined`, which the caller treats as failing the cardinality gate.
+ * Best-available row estimate for the fan-out's outer. Single-source relays now
+ * carry the leaf's `physical.estimatedRows` upward (`physicalSourceRows`), but not
+ * every wrapper does — a CTE reference or a set operation in between stamps
+ * nothing — so a value can be present on the leaf's `physical` yet undefined above
+ * it. Read the node's own estimate first, then descend single-relation
+ * pass-throughs (alias/filter/sort/…) to recover the leaf's estimate. A
+ * multi-relation node (a join outer in a subquery cluster) returns `undefined`,
+ * which the caller treats as failing the cardinality gate.
  */
 function outerRowEstimate(node) {
     const direct = node.physical?.estimatedRows ?? node.estimatedRows;

package/dist/src/planner/rules/join/rule-join-physical-selection.d.ts

@@ -3,14 +3,20 @@
  *
  * Required Characteristics:
  * - Node must be a logical JoinNode (not already a physical join)
- * - Node must have an equi-join predicate for hash/merge join consideration
+ * - Node must have an equi-join predicate for hash/merge/index-NL consideration
+ * - Neither side may be correlated (a correlated side must keep the
+ *   nested-loop driver — hash/merge drain a side outside any outer row's scope)
  *
  * Applied When:
- * - Logical JoinNode with equi-join predicates where hash or merge join is cheaper than nested loop
+ * - Logical JoinNode with equi-join predicates where hash join, merge join, or
+ *   an index-nested-loop (per-outer-row seek into the inner side, built by
+ *   `index-nested-loop.ts`) is cheaper than the plain nested loop
  *
- * Benefits: Replaces O(n*m) nested loop with O(n+m) hash/merge join for equi-joins
+ * Benefits: Replaces the O(n*m) nested loop with an O(n+m) hash/merge join, or
+ * with an O(n·seek) index-nested-loop when the inner side's module can answer
+ * an equality seek on the join key
  */
 import type { PlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
-export declare function ruleJoinPhysicalSelection(node: PlanNode, _context: OptContext): PlanNode | null;
+export declare function ruleJoinPhysicalSelection(node: PlanNode, context: OptContext): PlanNode | null;
 //# sourceMappingURL=rule-join-physical-selection.d.ts.map

package/dist/src/planner/rules/join/rule-join-physical-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-join-physical-selection.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-join-physical-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAiD,MAAM,0BAA0B,CAAC;AACxG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAiD7D,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CA+I/F"}
+{"version":3,"file":"rule-join-physical-selection.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-join-physical-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAiD,MAAM,0BAA0B,CAAC;AACxG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAmD7D,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAgN9F"}