@quereus/quereus 4.16.0 → 4.17.0

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

@@ -1,29 +1,50 @@
 /**
  * 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
+ * When a join's inner side bottoms out in a table-access leaf whose module can
+ * answer an equality seek on the join key, the leaf 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
  *
+ * Two admission arms for the inner leaf. A WALK leaf (plain full scan, or an
+ * ordering-only index walk) enforces nothing, so its `FilterInfo` may be
+ * replaced wholesale. A SEEK leaf (`IndexSeekNode`) already enforces the
+ * predicates the module claimed — `status = 'x'` below is nowhere else in the
+ * tree — so it is admitted by re-OFFERING those predicates to the module
+ * alongside the join key and re-applying whatever the module declines:
+ *
+ *   Join(inner, s, IndexSeek(big, [status='x']))
+ *     ON big.id = s.k
+ *       ──▶  Join(inner, s, Filter[status='x'](IndexSeek(big, keys=[s.k])))
+ *       or   Join(inner, s, IndexSeek(big, keys=[status='x', s.k]))   (composite index)
+ *
+ * The function takes `outer` / `inner` explicitly rather than reading a
+ * JoinNode's `left` / `right`: the caller asks for BOTH orientations of an
+ * inner join (seek the right driven by the left, and the mirror) and elects
+ * the cheaper — see `ruleJoinPhysicalSelection`. Here "outer" always means the
+ * side that will drive, and "inner" the side whose leaf becomes the seek,
+ * whichever JoinNode slot each came from.
+ *
  * 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
+ * module, cost it); the 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.
+ * equi-join on the walk arm, uncached (see `probeModule`); the seek arm runs
+ * ONE probe — its baseline is the displaced seek's recorded cost, a field read
+ * rather than a second probe. Cheap for both shipped modules; memoize by
+ * (table, offered constraints) 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';
@@ -33,28 +54,42 @@ import { BinaryOpNode } from '../../nodes/scalar.js';
 import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
 import { hasSemanticOrdering } from '../../../util/comparison.js';
 import { sharesSeekKeySpace } from '../../../types/builtin-types.js';
+import { hasRelationalDescendant } from '../../analysis/scalar-subqueries.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 { selectPhysicalNode, combineResidualExpressions, effectivePredicateCollation, } from '../access/rule-select-access-path.js';
+import { peelToSeekableAccessLeaf, 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';
+import { uniqueEnforcementCollations } from '../../../schema/unique-enforcement.js';
+import { collationRefines } from '../../../util/comparison.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.
+ * Join keys FIRST. Both the module (`claimFirstPerRole` in the store,
+ * `findEqualityMatches` in memory) and `selectPhysicalNode` pick the FIRST
+ * role-filling constraint per column, so when a pushed predicate and a join key
+ * land on the same column (`where b.id = 5` joined `on b.id = s.k`) this order
+ * is what makes the correlated seek the one that wins the column — the whole
+ * point of the candidate. Either leftover is then re-applied as a Filter.
  */
-function admitLeaf(right) {
-    const leaf = peelToAccessLeaf(right);
+function offerConstraints(joinKeys, pushed) {
+    return { combined: [...joinKeys, ...pushed], joinKeyCount: joinKeys.length };
+}
+/** Dispatch on the peeled leaf's kind; each arm owns its own gates. */
+function admitLeaf(inner) {
+    const leaf = peelToSeekableAccessLeaf(inner);
     if (!leaf) {
-        log('decline: right does not peel to an access leaf through Alias/Project/Filter');
+        log('decline: inner does not peel to an access leaf through Alias/Project/Filter');
         return null;
     }
+    return leaf instanceof IndexSeekNode ? admitSeekLeaf(leaf) : admitWalkLeaf(leaf);
+}
+/**
+ * WALK arm: an unconstrained every-row walk whose `FilterInfo` may be replaced
+ * wholesale — a plain full scan, or an ordering-only index walk (plan='scan').
+ * A pushed limit / offset is a directive the seek would not honor.
+ */
+function admitWalkLeaf(leaf) {
     const fi = leaf.filterInfo;
     const isEveryRowWalk = fi.accessPath?.kind === 'fullScan'
         || (fi.accessPath?.kind === 'index' && fi.accessPath.plan === 'scan');
@@ -69,7 +104,63 @@ function admitLeaf(right) {
         log('decline: leaf emission order is load-bearing (absorbed a Sort)');
         return null;
     }
-    return leaf;
+    return { leaf, pushed: [] };
+}
+/**
+ * SEEK arm: a leaf whose `FilterInfo` already enforces the predicates recorded
+ * in `pushedConstraints` (their residual Filter was dropped on the module's
+ * promise). Admitted when that record is complete and re-offerable; the caller
+ * re-offers it with the join key and re-applies whatever the module declines,
+ * so no recorded predicate can be lost. Same five gates as
+ * `rule-key-set-seek`'s `admitSeekLeaf`, for the same reasons.
+ */
+function admitSeekLeaf(leaf) {
+    const fi = leaf.filterInfo;
+    // Gate 1: a pushed limit / offset is a directive the re-planned seek would not
+    // honour, and unlike a predicate it cannot be re-applied by a Filter without
+    // changing which rows are dropped.
+    if (fi.limit !== undefined || fi.offset !== undefined) {
+        log('decline: seek leaf carries a pushed limit/offset');
+        return null;
+    }
+    // Gate 2: a seek whose enforced predicate we cannot describe is a seek we
+    // cannot safely re-plan.
+    if (!leaf.pushedConstraints || leaf.pushedConstraints.length === 0) {
+        log('decline: seek leaf records no pushed constraints');
+        return null;
+    }
+    // Gate 3: the seek's emission order absorbed a Sort; a re-planned seek emits
+    // in its own key order instead.
+    if (leaf.orderingLoadBearing) {
+        log('decline: seek leaf emission order is load-bearing (absorbed a Sort)');
+        return null;
+    }
+    for (const c of leaf.pushedConstraints) {
+        // Gate 4: a correlated pushed constraint means this leaf is already somebody
+        // else's per-outer-row seek (a lateral seek keyed on an enclosing scope);
+        // re-planning it would re-plan their correlation. (The caller's
+        // sibling-reference guard already blocks this rule's OWN output.)
+        //
+        // NOTE: this reads the RECORDED constraint's flag, where rule-key-set-seek's
+        // equivalent gate asks whether the leaf SUBTREE is correlated. The two agree
+        // only because `stampSeekProvenance` is the sole producer of
+        // `pushedConstraints` and records every constraint the seek consumed; a
+        // future rule that mints a correlated seek without recording the correlated
+        // constraint would slip past this gate. Switch to the subtree test if one
+        // ever does.
+        if (c.correlated === true) {
+            log('decline: seek leaf carries a correlated pushed constraint');
+            return null;
+        }
+        // Gate 5: this rule runs PostOptimization, so an expression re-applied here
+        // gets no further pass — a relational subquery inside it would reach emit
+        // unphysicalized, and would re-execute per outer row besides.
+        if (hasRelationalDescendant(c.sourceExpression)) {
+            log('decline: seek leaf pushed predicate contains a relational node');
+            return null;
+        }
+    }
+    return { leaf, pushed: leaf.pushedConstraints };
 }
 /**
  * Resolve each equi pair to (leaf column index, outer attribute position) and
@@ -141,17 +232,45 @@ function buildSeekPredicate(leaf, outer, resolved) {
     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.
+ * What the inner leaf costs TODAY, in the module's own currency. A seek leaf
+ * already records the module's answer for its own seek — `filterInfo.
+ * indexInfoOutput.estimatedCost` / `estimatedRows` are `accessPlan.cost` /
+ * `accessPlan.rows` verbatim (`makeIndexFilterInfo` spreads a base seeded with
+ * them and never overrides either) — while an unconstrained walk has to be
+ * asked. Comparing the combined seek against a bare scan instead would let a
+ * plan WORSE than the seek already in place win. Same baseline rule as
+ * rule-key-set-seek's `probeModuleCosts`.
+ *
+ * NOTE: `estimatedRows` is `makeFullScanFilterInfo`'s `accessPlan.rows || 1000`,
+ * so a module that answered its own seek with `rows: 0` (and did not claim every
+ * filter, which would have folded the access to an EmptyResult instead) or with
+ * no estimate at all reads back here as a 1000-row baseline the module never
+ * stated — the seek arm would then admit a candidate the cost gate should have
+ * declined. Both shipped modules always return a positive estimate for a seek,
+ * so this is unreachable today; if a third-party module reports 0 or omits
+ * `rows`, carry the module's own answer on the leaf instead of re-deriving it
+ * from the FilterInfo.
+ */
+function displacedPlan(leaf, ask) {
+    if (leaf instanceof IndexSeekNode) {
+        const out = leaf.filterInfo.indexInfoOutput;
+        return { cost: out.estimatedCost, rows: Number(out.estimatedRows) };
+    }
+    const scan = ask([]);
+    return { cost: scan.cost, rows: scan.rows };
+}
+/**
+ * Probe the module with the offered constraints and admit the seek only when
+ * the module's OWN answers say it beats the plan being displaced (`cost` no
+ * higher, `rows` strictly 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) {
+function probeModule(context, leaf, offered) {
     const tableSchema = leaf.tableSchema;
     const vtabModule = leaf.source.vtabModule;
     const getBestAccessPlan = vtabModule.getBestAccessPlan;
@@ -166,11 +285,12 @@ function probeModule(context, leaf, constraints) {
         validateAccessPlan(request, plan);
         return plan;
     };
+    const { combined, joinKeyCount } = offered;
     let seekPlan;
-    let scanPlan;
+    let baseline;
     try {
-        seekPlan = ask(constraints);
-        scanPlan = ask([]);
+        seekPlan = ask(combined);
+        baseline = displacedPlan(leaf, 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));
@@ -180,18 +300,32 @@ function probeModule(context, leaf, constraints) {
         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
+    // Every seek column must be one of the offered constraints — 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');
+    const offeredCols = new Set(combined.map(c => c.columnIndex));
+    if (!seekPlan.seekColumnIndexes.every(col => offeredCols.has(col))) {
+        log('decline: seek columns extend beyond the offered constraints');
         return null;
     }
+    // At least one seek column must come from a JOIN KEY. Without this the
+    // module can answer a seek leaf with the seek it already had: nothing is
+    // correlated, nothing is gained, and the rule would rebuild an identical
+    // leaf on every visit. (The rebuilt leaf's provenance is re-checked by
+    // identity in `tryIndexNestedLoop` — this is the cheap early exit.)
+    const joinKeyCols = new Set(combined.slice(0, joinKeyCount).map(c => c.columnIndex));
+    if (!seekPlan.seekColumnIndexes.some(col => joinKeyCols.has(col))) {
+        log('decline: the seek does not use the join key');
+        return null;
+    }
+    // Every JOIN-KEY constraint on a seek column must be claimed handled — the
+    // module must be promising to seek on the key we will emit. Pushed
+    // constraints need no such claim: a handled one is re-promised by the new
+    // seek or reattached by selectPhysicalNode, an unhandled one is re-applied
+    // by `reapplyDeclinedPushed` — either answer is honoured.
     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');
+    for (let i = 0; i < joinKeyCount; i++) {
+        if (seekCols.has(combined[i].columnIndex) && seekPlan.handledFilters[i] !== true) {
+            log('decline: module claimed a join-key seek column without handling its filter');
             return null;
         }
     }
@@ -200,67 +334,249 @@ function probeModule(context, leaf, constraints) {
         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);
+    // The module's own statement that the combined seek beats what it displaces:
+    // no dearer, and strictly fewer rows. Rows is the discriminator on purpose —
+    // the memory module prices every single-key equality seek identically (cost
+    // keyed to the seek-KEY count, not the rows matched), so a pushed
+    // `status = 'x'` seek and the join-key seek that would replace it tie on
+    // cost and differ only in rows; a strict cost test would leave the seek arm
+    // dead on that module for its headline shape.
+    if (seekPlan.rows === undefined || baseline.rows === undefined
+        || !(seekPlan.cost <= baseline.cost) || !(seekPlan.rows < baseline.rows)) {
+        log('decline: module costs do not favor the seek (seek %s/%s vs displaced %s/%s)', seekPlan.cost, seekPlan.rows, baseline.cost, baseline.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
+ * Re-apply the pushed constraints the module DECLINED (`handledFilters[i]
+ * !== true`) as a Filter directly above the rebuilt leaf. `selectPhysicalNode`
+ * re-promises the handled ones it consumed (recording them on the new seek's
+ * `pushedConstraints`) and reattaches the handled-but-unconsumed ones itself,
+ * but — exactly as for a user predicate, where `rule-grow-retrieve` owns the
+ * residual — it never touches a constraint the module did not claim. This is
+ * the third place, and with it every offered pushed constraint lands in
+ * exactly one of: re-promised, reattached, or re-applied here. Join-key
+ * leftovers need nothing: the ON condition retained above the join covers them.
+ *
+ * Folded into every Filter `selectPhysicalNode` may already have wrapped the
+ * seek in — it can stack two (a `COARSER_SAFE` collation residual, then a
+ * reattach above it) — so the seek carries one residual Filter rather than a
+ * stack. `combineResidualExpressions` de-duplicates by identity, so a declined
+ * BETWEEN comes back as its single `BetweenNode`.
+ */
+function reapplyDeclinedPushed(rebuilt, seekPlan, offered) {
+    const { combined, joinKeyCount } = offered;
+    const declined = combined.filter((_c, i) => i >= joinKeyCount && seekPlan.handledFilters[i] !== true);
+    if (declined.length === 0)
+        return rebuilt;
+    // Peel the whole Filter stack, outermost predicate first, so the result is one
+    // Filter — the same peel `rebuiltSeek` uses to find the seek underneath.
+    let below = rebuilt;
+    const existing = [];
+    while (below instanceof FilterNode) {
+        existing.push(below.predicate);
+        below = below.source;
+    }
+    // Non-empty input ⇒ defined result.
+    const predicate = combineResidualExpressions([...existing, ...declined.map(c => c.sourceExpression)]);
+    log('re-applying %d module-declined pushed constraint(s) above the seek', declined.length);
+    return new FilterNode(below.scope, below, predicate);
+}
+/**
+ * Every key the table enforces uniqueness on, each with the collation its
+ * columns are enforced under: the primary key (a member's own collation, else
+ * its column's — `ddl-generator` reads it the same way), every non-partial
+ * UNIQUE constraint (`uniqueEnforcementCollations`: the backing index's
+ * per-column COLLATE for an index-derived constraint, else the column's), and
+ * every non-partial UNIQUE index (its own per-column collation, else the
+ * column's — `appendIndexToTableSchema` normally mirrors these as derived
+ * constraints already; listed so a host-authored schema carrying the index
+ * alone is not missed). A partial key (`predicate` set) only constrains the
+ * rows its WHERE admits and proves nothing about the rest.
+ */
+function enforcedKeys(tableSchema) {
+    const columnCollation = (idx) => tableSchema.columns[idx]?.collation;
+    const keys = [];
+    const pk = tableSchema.primaryKeyDefinition;
+    if (pk.length > 0) {
+        keys.push({
+            columns: pk.map(k => k.index),
+            collations: pk.map(k => k.collation ?? columnCollation(k.index)),
+        });
+    }
+    for (const uc of tableSchema.uniqueConstraints ?? []) {
+        if (uc.predicate !== undefined || uc.columns.length === 0)
+            continue;
+        keys.push({ columns: uc.columns, collations: uniqueEnforcementCollations(tableSchema, uc) });
+    }
+    for (const ix of tableSchema.indexes ?? []) {
+        if (!ix.unique || ix.predicate !== undefined || ix.columns.length === 0)
+            continue;
+        keys.push({
+            columns: ix.columns.map(c => c.index),
+            collations: ix.columns.map(c => c.collation ?? columnCollation(c.index)),
+        });
+    }
+    return keys;
+}
+/**
+ * True when an equality's comparison collation is at least as fine as the
+ * key's enforcement collation — every pair of rows the equality treats as
+ * equal, the key treats as equal too, so uniqueness forbids a second match.
+ * {@link collationRefines} is the shared two-name test; a COARSER predicate
+ * fails it, so a `NOCASE` join key over a `BINARY` unique column (which admits
+ * `'a'` and `'A'`, two distinct stored rows that both match) declines.
+ *
+ * The source-shape gate is load-bearing, not defensive. `effectivePredicateCollation`
+ * answers BINARY for a shape it does not recognize — a safe DECLINE for its own
+ * caller (a BINARY-read predicate over a coarser index over-fetches and keeps its
+ * residual Filter) but the STRONGEST possible claim here, where BINARY refines
+ * everything. Every `op: '='` constraint today is minted by `extractBinaryConstraint`
+ * carrying its own `BinaryOpNode` (OR collapse emits only 'IN' / 'OR_RANGE'), so
+ * requiring that shape costs nothing now and makes a future `=` producer decline
+ * rather than be proved unique on a default.
+ */
+function equalityRefinesKey(constraint, keyCollation) {
+    if (!(constraint.sourceExpression instanceof BinaryOpNode))
+        return false;
+    return collationRefines(effectivePredicateCollation(constraint), keyCollation);
+}
+/**
+ * An equality pins ONE value per outer row only when its value side is
+ * deterministic. A constraint re-applied as a Filter is re-evaluated per inner
+ * row, so `b.id = random()` admits a different id on every row and several can
+ * pass — nothing upstream gates non-deterministic predicates out of pushdown
+ * (`rule-select-access-path` has no such test), so the proof must. A literal
+ * has no value expression and trivially qualifies; a correlated column
+ * reference is deterministic for the duration of one outer row.
+ */
+function pinsOneValue(constraint) {
+    const value = constraint.valueExpr;
+    if (value === undefined)
+        return true;
+    if (Array.isArray(value))
+        return false; // an IN list never reaches here (op !== '='); be explicit
+    return PlanNodeCharacteristics.isDeterministic(value);
+}
+/**
+ * PROOF — not an estimate — that the inner rebuilt from `combined` yields at
+ * most one row per outer row. `FanOutLookupJoinNode`'s `atMostOne-*` branch
+ * modes throw `QuereusError(CONSTRAINT)` at runtime on a second row, so the
+ * module's `rows: 1` estimate must not stand in: a module that estimates 1 and
+ * returns 2 would turn a working query into an error.
+ *
+ * Premise: every constraint in `combined` is enforced somewhere inside the
+ * rebuilt inner. That is total for the `=` constraints this proof reads, by
+ * construction rather than by argument — each one is either module-DECLINED, and
+ * `reapplyDeclinedPushed` re-applies every declined pushed constraint as a Filter
+ * (join-key leftovers need none: the ON condition the caller keeps above the seek
+ * covers them), or module-HANDLED, and a handled constraint is either consumed
+ * into the seek's bounds or recovered by `selectPhysicalNode`'s
+ * `reattachUnconsumedConstraints` — whose `RECLAIMABLE_OPS` set contains `'='`,
+ * so no equality can fall through it. A Filter only removes rows, so a constraint
+ * enforced by a filter rather than by the index counts just the same. Then: if
+ * some enforced key has EVERY column pinned by an equality whose collation
+ * refines the key's ({@link equalityRefinesKey}), any two surviving rows agree
+ * on the whole key and uniqueness forbids the second. Ranges, IN and OR_RANGE
+ * admit many values and never contribute. Over-fetch is harmless — a
+ * `COARSER_SAFE` seek's residual Filter re-applies the exact comparison above
+ * it — and the finer-index case (`MISMATCH_UNSAFE`) never reaches here: it
+ * degrades to a scan in `selectPhysicalNode` and `rebuiltSeek` declines the
+ * candidate first. NULL keys need no case: `col = NULL` matches nothing.
+ *
+ * Exported for direct unit coverage; it is the correctness core of the batched
+ * candidate.
+ */
+export function provesAtMostOne(tableSchema, combined) {
+    const equalitiesByColumn = new Map();
+    for (const c of combined) {
+        if (c.op !== '=' || !pinsOneValue(c))
+            continue;
+        const list = equalitiesByColumn.get(c.columnIndex);
+        if (list)
+            list.push(c);
+        else
+            equalitiesByColumn.set(c.columnIndex, [c]);
+    }
+    if (equalitiesByColumn.size === 0)
+        return false;
+    // A column pinned by several equalities (a pushed `b.id = 5` beside the join
+    // key) is proved by ANY one of them: the surviving rows satisfy all of them,
+    // so they are a subset of the rows the refining one admits.
+    return enforcedKeys(tableSchema).some(key => key.columns.every((col, i) => (equalitiesByColumn.get(col) ?? []).some(eq => equalityRefinesKey(eq, key.collations[i]))));
+}
+/**
+ * The `IndexSeekNode` under `rebuilt`'s collation-residual Filter, or null when
+ * `selectPhysicalNode` produced something else. It 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.
+ */
+function rebuiltSeek(rebuilt) {
+    let probe = rebuilt;
+    while (probe instanceof FilterNode)
+        probe = probe.source;
+    return probe instanceof IndexSeekNode ? probe : null;
+}
+/**
+ * Try to build an index-nested-loop candidate: the `inner` subtree rebuilt with
+ * its access leaf replaced by an `IndexSeekNode` correlated to `outer`, 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.
+ * `joinType` is the type the REBUILT join will have with `outer` on the left
+ * (so a mirrored inner join passes 'inner'). `equiPairs` must be non-empty and
+ * oriented left=outer / right=inner — the caller flips them for the mirror.
+ * `outerRows` is the outer side's row estimate, the same input hash and merge
+ * selection use for that side.
  */
-export function tryIndexNestedLoop(node, equiPairs, outerRows, context) {
+export function tryIndexNestedLoop(joinType, outer, inner, 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')
+    if (joinType !== 'inner' && joinType !== 'left' && joinType !== 'semi' && joinType !== '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');
+    if (PlanNodeCharacteristics.subtreeHasSideEffects(inner)) {
+        log('decline: inner side has side effects');
         return null;
     }
-    const leaf = admitLeaf(node.right);
-    if (!leaf)
+    const admitted = admitLeaf(inner);
+    if (!admitted)
         return null;
-    const resolved = resolvePairs(leaf, node.left, equiPairs);
+    const { leaf, pushed } = admitted;
+    const resolved = resolvePairs(leaf, outer, 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 predicate = buildSeekPredicate(leaf, outer, 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) ?? [];
+    const joinKeys = 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
+    if (joinKeys.length !== resolved.length || extraction.residualPredicate !== undefined
+        || !joinKeys.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);
+    const offered = offerConstraints(joinKeys, pushed);
+    const seekPlan = probeModule(context, leaf, offered);
     if (!seekPlan)
         return null;
     // Reuse the full access-path machinery: collation cover (over the real
@@ -268,24 +584,27 @@ export function tryIndexNestedLoop(node, equiPairs, outerRows, context) {
     // 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);
+    const rebuiltLeaf = selectPhysicalNode(leaf.source, seekPlan, [...offered.combined]);
+    const seek = rebuiltSeek(rebuiltLeaf);
+    if (!seek) {
+        log('decline: selectPhysicalNode did not produce an IndexSeek');
+        return null;
+    }
+    // The new seek must really be keyed on the join — its recorded provenance
+    // must include a join-key constraint by identity. Otherwise the module
+    // re-minted the seek it already had (a pushed equality on the seek column
+    // won the per-column pick) and nothing is correlated.
+    if (!seek.pushedConstraints?.some(c => joinKeys.includes(c))) {
+        log('decline: the rebuilt seek is not keyed on the join');
         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 };
+    const newLeaf = reapplyDeclinedPushed(rebuiltLeaf, seekPlan, offered);
+    const newInner = rebuildChain(inner, leaf, newLeaf);
+    const perSeekLatencyMs = inner.physical.expectedLatencyMs ?? 0;
+    const rowsPerSeek = seekPlan.rows;
+    const cost = indexNestedLoopJoinCost(outerRows, rowsPerSeek, perSeekLatencyMs);
+    const atMostOne = provesAtMostOne(tableSchema, offered.combined);
+    log('candidate: seek %s.%s via %s (%s rows/seek, cost %s for %s outer rows; %d pushed constraint(s) re-offered; at-most-one %s)', tableSchema.name, seekPlan.seekColumnIndexes.map(c => tableSchema.columns[c]?.name).join(','), seekPlan.indexName, seekPlan.rows, cost, outerRows, pushed.length, atMostOne ? 'proved' : 'unproved');
+    return { newInner, cost, rowsPerSeek, perSeekLatencyMs, atMostOne };
 }
 //# sourceMappingURL=index-nested-loop.js.map