@quereus/quereus 3.1.1 → 3.2.1

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

@@ -0,0 +1,592 @@
+/**
+ * Rule: Fan-out Lookup Join (FK→PK + 1:n cross + correlated scalar-aggregate
+ * subqueries)
+ *
+ * Clusters per-outer-row branches into one `FanOutLookupJoinNode` that drives
+ * them concurrently per outer row. A branch is either *at-most-one* (≤1 row per
+ * outer row) or *cross* (data-driven 1:n, Cartesian product per outer row):
+ *
+ *   1. **Join-spine branches.** A chain of N LEFT/INNER/CROSS nested-loop joins
+ *      from a common outer where every join's non-preserved side is a
+ *      parameterized equi-lookup. FK→PK-aligned lookups become at-most-one
+ *      branches (matching the alignment `ruleJoinElimination` trusts); lookups
+ *      that are *not* provably at-most-one (no FK, or FK→non-unique) become
+ *      `cross` branches whose 1:n product is bounded by the row/product guards
+ *      (`tuning.parallel.maxCrossBranchRows` / `maxCrossProduct`). A chain may
+ *      legitimately mix both modes.
+ *
+ *   2. **Subquery branches.** Correlated scalar-aggregate `ScalarSubqueryNode`s
+ *      found anywhere in the SELECT projection list — bare (`(select count(*)
+ *      from c where c.fk = o.k)`) or wrapped inside a scalar expression
+ *      (`coalesce((select sum(...) ...), 0)`, `json((select json_group_array(
+ *      ...) ...))`). A scalar aggregate with no GROUP BY emits exactly one row
+ *      per outer row regardless of how many child rows match — relationally an
+ *      `atMostOne-left` branch driven per outer row, exactly what the fan-out
+ *      node already does. The subquery's relational root is used verbatim as
+ *      the branch child (its correlation predicate is internal and resolves
+ *      through `rctx.context`); only the *inner* `ScalarSubqueryNode` is
+ *      rewritten to a column reference into the fan-out's wide row, leaving any
+ *      wrapping expression (`coalesce(<colref>, 0)`) intact.
+ *
+ * When the *combined* branch count clears `tuning.parallel.minBranches` AND the
+ * projected latency win covers the per-branch setup overhead, the cluster
+ * forms.
+ *
+ * Cost gate is anchored on `physical.expectedLatencyMs` — populated 0 for
+ * in-process / memory-vtab paths, non-zero for remote vtabs whose access plan
+ * declares per-call latency. As a consequence, with no remote-vtab plugin in
+ * tree the rule is inert by design (memory-vtab golden plans don't change).
+ *
+ * Join-spine branch eligibility mirrors `ruleJoinElimination`:
+ *   - AND-of-column-equalities ON-clause (any residual disqualifies the
+ *     branch — leave it as a normal nested-loop join),
+ *   - FK→PK alignment validated via `lookupCoveringFK` + `checkFkPkAlignment`,
+ *   - INNER branches additionally require NOT-NULL FK + row-preserving path
+ *     to the PK table.
+ *
+ * Subquery branch eligibility:
+ *   - a `ScalarSubqueryNode` reached anywhere in a projection's scalar
+ *     expression tree (bare or wrapped — `collectScalarSubqueries` finds it),
+ *   - the subquery is correlated,
+ *   - beneath pass-through wrappers the relational root is aggregate-shaped
+ *     with zero grouping keys (⇒ exactly one row per outer),
+ *   - the subquery exposes exactly one output attribute.
+ */
+import { createLogger } from '../../../common/logger.js';
+import { isRelationalNode, } from '../../nodes/plan-node.js';
+import { ProjectNode } from '../../nodes/project-node.js';
+import { FilterNode } from '../../nodes/filter.js';
+import { SortNode } from '../../nodes/sort.js';
+import { LimitOffsetNode } from '../../nodes/limit-offset.js';
+import { DistinctNode } from '../../nodes/distinct-node.js';
+import { AliasNode } from '../../nodes/alias-node.js';
+import { JoinNode, extractEquiPairsFromCondition } from '../../nodes/join-node.js';
+import { ScalarSubqueryNode } from '../../nodes/subquery.js';
+import { ColumnReferenceNode } from '../../nodes/reference.js';
+import { normalizePredicate } from '../../analysis/predicate-normalizer.js';
+import { checkFkPkAlignment, extractTableSchema } from '../../util/key-utils.js';
+import { lookupCoveringFK, isRowPreservingPathToTable } from '../../util/ind-utils.js';
+import { collectExternalReferences } from '../../cache/correlation-detector.js';
+import { CapabilityDetectors } from '../../framework/characteristics.js';
+import { isAndOfColumnEqualities } from './rule-join-elimination.js';
+import { FanOutLookupJoinNode, isCrossBranchMode, isLeftBranchMode } from '../../nodes/fanout-lookup-join-node.js';
+const log = createLogger('optimizer:rule:fanout-lookup-join');
+export function ruleFanOutLookupJoin(node, context) {
+    if (!(node instanceof ProjectNode))
+        return null;
+    const tuning = context.tuning.parallel;
+    if (tuning.minBranches < 2)
+        return null;
+    // Walk pass-through wrappers down to the first JoinNode or a non-wrapper
+    // bottom. Unlike the join-only v1, hitting a non-JoinNode/non-wrapper node
+    // is NOT a bail — it just means there is no join spine and that node is the
+    // outer (e.g. the `orders` access node for `select …, (subq) from orders`).
+    const chain = [];
+    let current = node.source;
+    while (true) {
+        if (current instanceof JoinNode)
+            break;
+        if (current instanceof FilterNode) {
+            chain.push({ kind: 'filter', node: current });
+            current = current.source;
+            continue;
+        }
+        if (current instanceof SortNode) {
+            chain.push({ kind: 'sort', node: current });
+            current = current.source;
+            continue;
+        }
+        if (current instanceof LimitOffsetNode) {
+            chain.push({ kind: 'limit', node: current });
+            current = current.source;
+            continue;
+        }
+        if (current instanceof DistinctNode) {
+            chain.push({ kind: 'distinct', node: current });
+            current = current.source;
+            continue;
+        }
+        if (current instanceof AliasNode) {
+            chain.push({ kind: 'alias', node: current });
+            current = current.source;
+            continue;
+        }
+        break;
+    }
+    // Collect the join chain top-to-bottom and find the outer subtree at the
+    // deepest left. With no join spine the outer is `current` itself.
+    const joins = [];
+    let walker = current;
+    while (walker instanceof JoinNode) {
+        joins.push(walker);
+        walker = walker.left;
+    }
+    const outerSubtree = walker;
+    const outerAttrs = outerSubtree.getAttributes();
+    // Join-spine branches. FK→PK alignment is validated against the outer
+    // subtree's schema, so a spine requires the outer to resolve to a single
+    // table schema (mirrors `ruleJoinElimination`). `extractTableSchema` is
+    // needed ONLY here — pure-subquery clusters skip it.
+    //
+    // Bottom-up walk: joins[joins.length - 1] is the innermost (its .left ==
+    // outerSubtree), joins[0] is the outermost. Process bottom-up so the order
+    // of `spineBranches` reflects the natural wide-row layout.
+    const spineBranches = [];
+    if (joins.length > 0) {
+        const outerSchema = extractTableSchema(outerSubtree);
+        if (!outerSchema)
+            return null;
+        for (let i = joins.length - 1; i >= 0; i--) {
+            const recognized = recognizeBranch(joins[i], outerSchema, outerAttrs);
+            if (!recognized) {
+                // A non-eligible branch in the middle breaks the cluster — without
+                // a way to keep that branch in the original nested-loop position we
+                // would change semantics. Bail out conservatively.
+                return null;
+            }
+            spineBranches.push(recognized);
+        }
+    }
+    // Subquery branches: correlated scalar-aggregate ScalarSubqueryNodes found
+    // anywhere in a projection's scalar expression tree — bare (`(subq)`) or
+    // wrapped inside a scalar expression (`coalesce((subq), 0)`, `json((subq))`).
+    // `collectScalarSubqueries` walks each projection's scalar tree without
+    // descending into a subquery's own relational body, so a nested inner
+    // subquery stays part of its enclosing branch child rather than clustering
+    // separately.
+    const subqueryBranches = [];
+    const outerAttrIds = new Set(outerAttrs.map(a => a.id));
+    const seenSubqueries = new Set();
+    for (const proj of node.projections) {
+        const candidates = [];
+        collectScalarSubqueries(proj.node, candidates);
+        for (const cand of candidates) {
+            if (seenSubqueries.has(cand))
+                continue;
+            const recognized = recognizeSubqueryBranch(cand, outerAttrIds);
+            if (recognized) {
+                seenSubqueries.add(cand);
+                subqueryBranches.push(recognized);
+            }
+        }
+    }
+    const totalBranches = spineBranches.length + subqueryBranches.length;
+    if (totalBranches < tuning.minBranches)
+        return null;
+    // Memory-safety gate (before clustering): a `cross` branch's 1:n fan-out
+    // makes the output the Cartesian product of the outer side and every cross
+    // branch. Refuse to cluster when a per-branch estimate or the whole product
+    // blows the configured caps — the chain then stays a streaming nested-loop
+    // join. Subquery branches are always at-most-one, so only spine branches can
+    // be cross (`cross` / `cross-left`). A `cross-left` branch still contributes a
+    // 1:n factor (its empty-match NULL-pad only adds the single preserved row), so
+    // it is gated identically to `cross`.
+    const crossLookups = spineBranches.filter(b => isCrossBranchMode(b.mode)).map(b => b.lookup);
+    if (!crossGuardsPass(outerSubtree, crossLookups, tuning))
+        return null;
+    // Cost gate over the COMBINED branch set. `expectedLatencyMs` is populated 0
+    // except on remote-vtab access plans (propagated up through the aggregate
+    // for subquery branches), so this skip keeps the rule inert for local chains.
+    let maxLatency = 0;
+    for (const b of spineBranches) {
+        const l = b.lookup.physical.expectedLatencyMs ?? 0;
+        if (l > maxLatency)
+            maxLatency = l;
+    }
+    for (const b of subqueryBranches) {
+        const l = b.subqueryRoot.physical.expectedLatencyMs ?? 0;
+        if (l > maxLatency)
+            maxLatency = l;
+    }
+    if (maxLatency === 0)
+        return null;
+    const concurrencyCap = Math.max(1, Math.min(tuning.concurrency, totalBranches));
+    const savings = (totalBranches - concurrencyCap) * maxLatency;
+    const overhead = totalBranches * tuning.branchSetupCost;
+    if (savings <= overhead)
+        return null;
+    // Build branch specs: spine branches first (preserving left-deep order),
+    // then subquery branches.
+    //
+    // A spine branch's `child` is the lookup wrapped in a FilterNode carrying
+    // the original equi-condition. A subquery branch's `child` is the subquery's
+    // relational root verbatim — its correlation predicate is already inside it.
+    // Both resolve outer-side references via `rctx.context`: the parent fork's
+    // snapshot carries the outer slot, set by `runFanOutLookupJoin` before the
+    // fork.
+    const branchSpecs = [];
+    for (const b of spineBranches) {
+        const parameterized = new FilterNode(node.scope, b.lookup, b.condition);
+        branchSpecs.push({
+            child: parameterized,
+            mode: b.mode,
+            outputAttrs: b.lookup.getAttributes(),
+            concurrencySafe: b.lookup.physical.concurrencySafe !== false,
+        });
+    }
+    for (const b of subqueryBranches) {
+        // Pin the branch to a single column (the scalar value) so its attribute
+        // count is invariant under the inner aggregate's logical→physical
+        // expansion. `attributeId: valueAttr.id` keeps the branch output attribute
+        // identical to what the outer projection's column reference targets.
+        const colRef = new ColumnReferenceNode(node.scope, columnExprFor(b.valueAttr.name), b.valueAttr.type, b.valueAttr.id, 0);
+        const projectedChild = new ProjectNode(node.scope, b.subqueryRoot, [{ node: colRef, alias: b.valueAttr.name, attributeId: b.valueAttr.id }]);
+        branchSpecs.push({
+            child: projectedChild,
+            mode: b.mode,
+            outputAttrs: projectedChild.getAttributes(),
+            concurrencySafe: b.concurrencySafe,
+        });
+    }
+    // `preserveAttributeIds` pins the wide-row layout: outer attrs + each
+    // branch's output attrs (nullable-widened for left-preserving branches —
+    // atMostOne-left / cross-left). The branch outputs are the lookups'/
+    // subqueries' own attributes, so any reference resolves by attribute ID
+    // regardless of wide-row position.
+    const preserveAttrs = [];
+    for (const a of outerAttrs)
+        preserveAttrs.push(a);
+    for (const spec of branchSpecs) {
+        const nullable = isLeftBranchMode(spec.mode);
+        for (const a of spec.outputAttrs) {
+            if (nullable && !a.type.nullable) {
+                preserveAttrs.push({ ...a, type: { ...a.type, nullable: true } });
+            }
+            else {
+                preserveAttrs.push(a);
+            }
+        }
+    }
+    const fanout = new FanOutLookupJoinNode(node.scope, outerSubtree, branchSpecs, concurrencyCap, preserveAttrs);
+    // Build the projection rewrite map. Each subquery branch's single output
+    // attribute materializes at a fixed wide-row index (outer + preceding branch
+    // outputs); replace the ScalarSubqueryNode in the projection with a column
+    // reference at that index. Correctness comes from the attribute ID (resolved
+    // via the row descriptor); the index is the runtime read position.
+    const subqueryReplacements = new Map();
+    let wideIndex = outerAttrs.length;
+    for (const b of spineBranches)
+        wideIndex += b.lookup.getAttributes().length;
+    for (const b of subqueryBranches) {
+        const outAttr = b.valueAttr;
+        // atMostOne-left can null-fill (empty children), so the read type is
+        // nullable; this matches the wide-row widening in `preserveAttrs`.
+        const colType = outAttr.type.nullable
+            ? outAttr.type
+            : { ...outAttr.type, nullable: true };
+        const colRef = new ColumnReferenceNode(node.scope, columnExprFor(outAttr.name), colType, outAttr.id, wideIndex);
+        subqueryReplacements.set(b.subqueryNode, colRef);
+        wideIndex += 1; // each subquery branch contributes exactly one column
+    }
+    log('Forming FanOutLookupJoin with %d branches (%d spine + %d subquery, cap=%d, maxLatency=%d)', totalBranches, spineBranches.length, subqueryBranches.length, concurrencyCap, maxLatency);
+    const rebuilt = rebuildChain(chain, fanout);
+    return rebuildProject(node, rebuilt, subqueryReplacements);
+}
+/** Minimal synthetic AST.ColumnExpr for a rewritten projection column ref. */
+function columnExprFor(name) {
+    return { type: 'column', name };
+}
+/**
+ * Collect every `ScalarSubqueryNode` reachable in a projection's scalar
+ * expression tree, in deterministic pre-order. A recognized subquery is a leaf
+ * for this walk: we push it and do NOT descend into its relational body, so a
+ * subquery nested *inside* another subquery's correlation predicate remains part
+ * of its enclosing branch child rather than being clustered as its own branch.
+ * (The relational body is filtered out by the `typeClass === 'scalar'` guard
+ * regardless, but stopping early keeps the intent explicit.)
+ */
+function collectScalarSubqueries(expr, out) {
+    if (expr instanceof ScalarSubqueryNode) {
+        out.push(expr);
+        return;
+    }
+    for (const child of expr.getChildren()) {
+        if (child.getType().typeClass === 'scalar') {
+            collectScalarSubqueries(child, out);
+        }
+    }
+}
+/**
+ * Rebuild a projection's scalar expression with each recognized
+ * `ScalarSubqueryNode` replaced by its `ColumnReferenceNode` into the fan-out's
+ * wide row, leaving the wrapping expression (`coalesce(<colref>, 0)`) intact.
+ * For a bare-subquery projection the root itself is in the map and is returned
+ * directly; for a wrapped subquery the tree is rebuilt via `withChildren` with
+ * only the matched inner node substituted. Returns the input unchanged when no
+ * descendant is a recognized subquery.
+ */
+function substituteSubqueries(expr, replacements) {
+    if (expr instanceof ScalarSubqueryNode) {
+        return replacements.get(expr) ?? expr;
+    }
+    const children = expr.getChildren();
+    if (children.length === 0)
+        return expr;
+    const newChildren = [];
+    let changed = false;
+    for (const child of children) {
+        if (child.getType().typeClass === 'scalar') {
+            const replaced = substituteSubqueries(child, replacements);
+            newChildren.push(replaced);
+            if (replaced !== child)
+                changed = true;
+        }
+        else {
+            newChildren.push(child);
+        }
+    }
+    if (!changed)
+        return expr;
+    return expr.withChildren(newChildren);
+}
+/**
+ * Recognize a correlated scalar-aggregate subquery as an `atMostOne-left`
+ * fan-out branch. Returns null when the subquery is not correlated, correlates
+ * to anything other than the outer subtree, is not aggregate-shaped with zero
+ * grouping keys beneath pass-through wrappers, or does not expose exactly one
+ * output attribute.
+ *
+ * The correlation must resolve *entirely* against `outerAttrIds`: at runtime
+ * the fan-out installs only the outer row's slot before forking each branch, so
+ * a subquery referencing a sibling spine-branch attribute (produced inside the
+ * fan-out, never installed as a slot) would fail to resolve its column at
+ * runtime. Rejecting it here keeps such a subquery as an ordinary correlated
+ * projection. (See `correlated subquery referencing a spine-branch attribute`
+ * in `parallel-fanout.spec.ts`.)
+ *
+ * The aggregate-shape test uses `CapabilityDetectors.isAggregating`, which
+ * matches both the logical `AggregateNode` and the physical
+ * `StreamAggregateNode` / `HashAggregateNode`, so it is robust to optimizer
+ * pass ordering (the subquery root may still be logical at structural time).
+ */
+function recognizeSubqueryBranch(scalarSubquery, outerAttrIds) {
+    const external = collectExternalReferences(scalarSubquery.subquery);
+    if (external.size === 0)
+        return null; // not correlated
+    for (const id of external) {
+        if (!outerAttrIds.has(id))
+            return null; // correlates beyond the outer subtree
+    }
+    // Descend pass-through wrappers (Project/Alias/Sort/LimitOffset) to the
+    // aggregate root.
+    let root = scalarSubquery.subquery;
+    while (!CapabilityDetectors.isAggregating(root)) {
+        if (root instanceof ProjectNode ||
+            root instanceof AliasNode ||
+            root instanceof SortNode ||
+            root instanceof LimitOffsetNode) {
+            root = root.source;
+            continue;
+        }
+        return null;
+    }
+    // Empty grouping ⇒ exactly one row per outer ⇒ at-most-one branch. A
+    // GROUP BY subquery may yield more than one row and is rejected here.
+    if (root.getGroupingKeys().length !== 0)
+        return null;
+    // A scalar subquery's relational root exposes exactly one output column at
+    // structural time (validated at build); its column-0 attribute is the
+    // scalar value the branch contributes.
+    const subAttrs = scalarSubquery.subquery.getAttributes();
+    if (subAttrs.length !== 1)
+        return null;
+    return {
+        subqueryNode: scalarSubquery,
+        subqueryRoot: scalarSubquery.subquery,
+        valueAttr: subAttrs[0],
+        mode: 'atMostOne-left',
+        concurrencySafe: scalarSubquery.subquery.physical.concurrencySafe !== false,
+    };
+}
+/**
+ * Decide whether `join`'s `right` side is a parameterized equi-lookup eligible
+ * for branch clustering, and at what cardinality `mode`. The FK side is sourced
+ * from `outerSchema` + `outerAttrs` — both the equi-pair's left attribute and
+ * its `outerAttrs` membership are checked, which is the safety net keeping
+ * per-join alignment honest in the presence of intermediate joins in the chain
+ * (the join's own `.left` resolves to a combined relation, so we cannot extract
+ * a single schema from it).
+ *
+ * Two cardinality outcomes:
+ *
+ *   - **at-most-one** (`atMostOne-left` / `atMostOne-inner`) — the lookup is
+ *     FK→PK aligned, so each outer row matches ≤1 lookup row. INNER additionally
+ *     requires a covering NOT-NULL FK + a row-preserving path (else it would
+ *     drop or duplicate rows the cluster cannot account for — bail to preserve
+ *     the nested-loop join).
+ *
+ *   - **cross** / **cross-left** — a clean parameterized equi-lookup whose
+ *     FK→PK alignment is *absent* (no FK, or FK→non-unique), so the
+ *     per-outer-row cardinality is data-driven (1:n). `inner` / `cross` join
+ *     types yield `cross` (inner-drop on an empty branch); a `left` join yields
+ *     `cross-left` (NULL-pad + preserve the outer row on an empty branch, with
+ *     nullable-widened branch outputs). The unbounded Cartesian product is gated
+ *     by the caller's row/product guards in both cases.
+ *
+ * Aligned-but-not-at-most-one INNER lookups (nullable FK, non-row-preserving
+ * path) are *not* reclassified as `cross`: FK→PK is still ≤1 match, so the issue
+ * is inner-drop semantics, not cardinality. They bail (return null) exactly as
+ * before, so the chain falls back to a nested-loop join.
+ */
+function recognizeBranch(join, outerSchema, outerAttrs) {
+    if (join.joinType !== 'left' && join.joinType !== 'inner' && join.joinType !== 'cross')
+        return null;
+    if (!join.condition)
+        return null;
+    const leftAttrs = join.left.getAttributes();
+    const rightAttrs = join.right.getAttributes();
+    const pairs = extractEquiPairsFromCondition(join.condition, leftAttrs, rightAttrs);
+    if (pairs.length === 0)
+        return null;
+    const normalized = normalizePredicate(join.condition);
+    if (!isAndOfColumnEqualities(normalized))
+        return null;
+    const outerAttrIdToIdx = new Map();
+    outerAttrs.forEach((a, i) => outerAttrIdToIdx.set(a.id, i));
+    // Translate each equi-pair from "(left subtree column index, right column
+    // index)" to "(outer column index, right column index)". The left subtree
+    // may span multiple joins, but the equi-pair's left attribute must
+    // originate in the outer subtree so the lookup is parameterizable from the
+    // outer row (and, for FK→PK, so the relationship makes sense).
+    const outerCols = [];
+    const rightCols = [];
+    for (const p of pairs) {
+        const leftAttrId = leftAttrs[p.left]?.id;
+        if (leftAttrId === undefined)
+            return null;
+        const outerIdx = outerAttrIdToIdx.get(leftAttrId);
+        if (outerIdx === undefined)
+            return null;
+        outerCols.push(outerIdx);
+        rightCols.push(p.right);
+    }
+    const rightSchema = extractTableSchema(join.right);
+    if (!rightSchema)
+        return null;
+    // At-most-one path: FK→PK alignment guarantees ≤1 match per outer row.
+    if (checkFkPkAlignment(outerSchema, rightSchema, outerCols, rightCols)) {
+        if (join.joinType === 'left') {
+            return { lookup: join.right, mode: 'atMostOne-left', condition: join.condition };
+        }
+        if (join.joinType === 'inner') {
+            const match = lookupCoveringFK(outerSchema, rightSchema, outerCols, rightCols);
+            if (!match || match.nullable)
+                return null;
+            if (!isRowPreservingPathToTable(join.right))
+                return null;
+            return { lookup: join.right, mode: 'atMostOne-inner', condition: join.condition };
+        }
+        // An aligned `cross` join type (unusual: a cross join carrying an
+        // equi-condition) falls through to the cross treatment below.
+    }
+    // Cross path: a clean parameterized equi-lookup that is not provably
+    // at-most-one (data-driven 1:n).
+    //   - INNER/CROSS ⇒ `cross` (inner-drop on an empty branch).
+    //   - LEFT ⇒ `cross-left` (NULL-pad + preserve the outer row on an empty
+    //     branch; branch output attributes are nullable-widened by the node /
+    //     `preserveAttrs`). Both contribute a 1:n factor gated by `crossGuardsPass`.
+    if (join.joinType === 'inner' || join.joinType === 'cross') {
+        return { lookup: join.right, mode: 'cross', condition: join.condition };
+    }
+    if (join.joinType === 'left') {
+        return { lookup: join.right, mode: 'cross-left', condition: join.condition };
+    }
+    return null;
+}
+/**
+ * Cross-branch memory guard. A `cross` branch contributes a *data-driven* (1:n)
+ * row count, so the fan-out's output is the Cartesian product of the outer side
+ * and every cross branch. Left ungated, that product can be unbounded, so we
+ * refuse to cluster when:
+ *
+ *   - any cross branch's lookup estimate exceeds `maxCrossBranchRows`, or
+ *   - `outer.estimatedRows × Π(cross-branch estimatedRows)` exceeds
+ *     `maxCrossProduct`.
+ *
+ * Unknown estimates are treated as exceeding the cap (return `false`) so a
+ * missing statistic never authorizes an unbounded product — the chain then
+ * stays a streaming / re-executing nested-loop join, which is already
+ * memory-safe. At-most-one branches are not passed in (they contribute ≤1 row
+ * per outer row and never widen the product).
+ */
+function crossGuardsPass(outer, crossLookups, tuning) {
+    if (crossLookups.length === 0)
+        return true;
+    const outerEst = rowEstimate(outer);
+    if (outerEst === undefined)
+        return false;
+    let product = outerEst;
+    for (const lk of crossLookups) {
+        const est = rowEstimate(lk);
+        if (est === undefined)
+            return false;
+        if (est > tuning.maxCrossBranchRows)
+            return false;
+        product *= est;
+        if (product > tuning.maxCrossProduct)
+            return false;
+    }
+    return true;
+}
+/**
+ * Best-available row estimate for a node: prefer the computed physical estimate
+ * (populated by the stats pass / `computePhysical`), falling back to the node's
+ * own `estimatedRows`. Returns `undefined` when neither is known — callers treat
+ * that conservatively.
+ */
+function rowEstimate(node) {
+    return node.physical?.estimatedRows ?? node.estimatedRows;
+}
+function rebuildChain(chain, bottom) {
+    let current = bottom;
+    // Chain was collected top→bottom (root pushed first); rebuild bottom→top.
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const entry = chain[i];
+        switch (entry.kind) {
+            case 'filter': {
+                current = new FilterNode(entry.node.scope, current, entry.node.predicate);
+                break;
+            }
+            case 'sort': {
+                current = new SortNode(entry.node.scope, current, entry.node.sortKeys);
+                break;
+            }
+            case 'limit': {
+                current = new LimitOffsetNode(entry.node.scope, current, entry.node.limit, entry.node.offset);
+                break;
+            }
+            case 'distinct': {
+                current = new DistinctNode(entry.node.scope, current);
+                break;
+            }
+            case 'alias': {
+                current = new AliasNode(entry.node.scope, current, entry.node.alias);
+                break;
+            }
+        }
+    }
+    return current;
+}
+function rebuildProject(project, newSource, subqueryReplacements) {
+    const attributes = project.getAttributes();
+    const newProjections = project.projections.map((p, i) => {
+        // Substitute recognized subquery node(s) anywhere in the projection's
+        // scalar tree with the column reference into the fan-out's wide row. A
+        // bare-subquery projection is replaced wholesale; a wrapped subquery has
+        // only its inner node swapped, leaving the wrapping expression intact. The
+        // projection keeps its own attributeId/alias.
+        const node = subqueryReplacements
+            ? substituteSubqueries(p.node, subqueryReplacements)
+            : p.node;
+        return {
+            node,
+            alias: p.alias,
+            attributeId: attributes[i].id,
+        };
+    });
+    if (!isRelationalNode(newSource)) {
+        throw new Error('rule-fanout-lookup-join: rebuilt source must be relational');
+    }
+    return new ProjectNode(project.scope, newSource, newProjections, undefined, attributes, project.preserveInputColumns);
+}
+//# sourceMappingURL=rule-fanout-lookup-join.js.map

package/dist/src/planner/rules/join/rule-fanout-lookup-join.js.map

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

package/dist/src/planner/rules/parallel/rule-async-gather-union-all.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Rule: Async Gather UNION ALL
+ *
+ * Recognizes a chain of `SetOperationNode(op='unionAll')` and folds the entire
+ * left-deep (or arbitrary nesting) tree into a single N-ary
+ * `AsyncGatherNode({ kind: 'unionAll' })` that drives the N branches
+ * concurrently.
+ *
+ * Two gates must clear for the rewrite to fire:
+ *
+ *   1. **Concurrency safety.** Every flattened child must declare
+ *      `physical.concurrencySafe === true`. Any non-safe branch (mutating
+ *      subplan, serial-module read without a per-branch connection, holding a
+ *      non-reentrant cursor) poisons the rewrite — leave the chain as
+ *      sequential `SetOperationNode`s.
+ *
+ *   2. **Latency win.** The slowest child's `physical.expectedLatencyMs` must
+ *      meet `tuning.parallel.gatherThresholdMs`. `expectedLatencyMs` is 0 on
+ *      all in-process / memory-vtab paths, so the rule is inert by design in
+ *      local-only configurations (the no-rewrite invariant is locked by the
+ *      golden-plan sweep).
+ *
+ * The rule fires in `PassId.PostOptimization` after physical-property
+ * selection has finalized `expectedLatencyMs` / `concurrencySafe` on the
+ * leaves but before `materialization-advisory` so any cache wrapping the
+ * advisory would inject sits *inside* the gather's branches (preserving the
+ * parallel-drive intent of overlapping high-latency I/O with branch-local
+ * compute).
+ *
+ * Attribute IDs are preserved: the rewritten gather node inherits the
+ * outermost `SetOperationNode`'s attributes via `preserveAttributeIds`,
+ * which already mirrors the leftmost child's attributes per
+ * `SetOperationNode.buildAttributes`. Downstream consumers that referenced
+ * the SetOp's output (e.g. an enclosing `ORDER BY x`) continue to resolve
+ * unchanged.
+ *
+ * Idempotence: after the rewrite the root node is an `AsyncGatherNode`, not
+ * a `SetOperationNode`, so a second firing's matcher rejects immediately.
+ */
+import type { OptContext } from '../../framework/context.js';
+import type { PlanNode } from '../../nodes/plan-node.js';
+export declare function ruleAsyncGatherUnionAll(node: PlanNode, context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-async-gather-union-all.d.ts.map

package/dist/src/planner/rules/parallel/rule-async-gather-union-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-async-gather-union-all.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/parallel/rule-async-gather-union-all.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAsB,MAAM,0BAA0B,CAAC;AAO7E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CA+C5F"}