@quereus/quereus 0.2.1 → 0.4.0

package/dist/src/planner/rules/join/rule-join-greedy-commute.js

@@ -0,0 +1,33 @@
+import { createLogger } from '../../../common/logger.js';
+import { JoinNode } from '../../nodes/join-node.js';
+const log = createLogger('optimizer:rule:join-greedy-commute');
+/**
+ * Rule: Join Greedy Commute
+ *
+ * Simple heuristic: for INNER joins, prefer the smaller input on the left to drive nested-loop-like cost.
+ * This uses children estimatedRows (influenced by pushdown/growth) and swaps left/right when beneficial.
+ *
+ * Safety:
+ * - INNER joins are commutative; ColumnReferenceNode uses attribute IDs, so swapping sides preserves semantics.
+ * - We do NOT change associativity; we only commute immediate children of a JoinNode.
+ */
+export function ruleJoinGreedyCommute(node, _context) {
+    if (!(node instanceof JoinNode))
+        return null;
+    if (node.joinType !== 'inner' && node.joinType !== 'cross')
+        return null;
+    const leftRows = node.getLeftSource().estimatedRows ?? Number.POSITIVE_INFINITY;
+    const rightRows = node.getRightSource().estimatedRows ?? Number.POSITIVE_INFINITY;
+    // Prefer known finite estimatedRows; also detect <=1 row driver on either side
+    const leftIsSingleton = node.getLeftSource().physical.uniqueKeys?.some(k => k.length === 0) === true;
+    const rightIsSingleton = node.getRightSource().physical.uniqueKeys?.some(k => k.length === 0) === true;
+    // If right is strictly better driver (smaller or singleton), swap
+    const shouldSwap = (rightIsSingleton && !leftIsSingleton) || (!rightIsSingleton && !leftIsSingleton && rightRows < leftRows);
+    if (!shouldSwap)
+        return null;
+    log('Commuting join children to place smaller input on the left (leftRows=%s, rightRows=%s)', String(leftRows), String(rightRows));
+    // Swap children; condition stays the same (attribute IDs are stable)
+    const swapped = new JoinNode(node.scope, node.getRightSource(), node.getLeftSource(), node.getJoinType(), node.getJoinCondition(), node.getUsingColumns());
+    return swapped;
+}
+//# sourceMappingURL=rule-join-greedy-commute.js.map

package/dist/src/planner/rules/join/rule-join-greedy-commute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-join-greedy-commute.js","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-join-greedy-commute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,MAAM,GAAG,GAAG,YAAY,CAAC,oCAAoC,CAAC,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAc,EAAE,QAAoB;IACxE,IAAI,CAAC,CAAC,IAAI,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAExE,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,aAAa,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAChF,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,aAAa,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAElF,+EAA+E;IAC/E,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;IACrG,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;IAEvG,kEAAkE;IAClE,MAAM,UAAU,GAAG,CAAC,gBAAgB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,gBAAgB,IAAI,CAAC,eAAe,IAAI,SAAS,GAAG,QAAQ,CAAC,CAAC;IAC7H,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE7B,GAAG,CAAC,wFAAwF,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAEnI,qEAAqE;IACrE,MAAM,OAAO,GAAG,IAAI,QAAQ,CAC1B,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,cAAc,EAAwB,EAC3C,IAAI,CAAC,aAAa,EAAwB,EAC1C,IAAI,CAAC,WAAW,EAAE,EAClB,IAAI,CAAC,gBAAgB,EAAE,EACvB,IAAI,CAAC,eAAe,EAAE,CACvB,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/planner/rules/join/rule-join-key-inference.d.ts

@@ -0,0 +1,11 @@
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+/**
+ * Rule: Join Key Inference
+ *
+ * Detect simple equi-join predicates (left.col = right.pk) and propagate
+ * inner/cross join unique keys (already handled by JoinNode.computePhysical),
+ * with a hook for future FK->PK inference (not implemented here yet).
+ */
+export declare function ruleJoinKeyInference(node: PlanNode, _context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-join-key-inference.d.ts.map

package/dist/src/planner/rules/join/rule-join-key-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-join-key-inference.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-join-key-inference.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAgB1F"}

package/dist/src/planner/rules/join/rule-join-key-inference.js

@@ -0,0 +1,32 @@
+import { createLogger } from '../../../common/logger.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { BinaryOpNode } from '../../nodes/scalar.js';
+import { ColumnReferenceNode } from '../../nodes/reference.js';
+const log = createLogger('optimizer:rule:join-key-inference');
+/**
+ * Rule: Join Key Inference
+ *
+ * Detect simple equi-join predicates (left.col = right.pk) and propagate
+ * inner/cross join unique keys (already handled by JoinNode.computePhysical),
+ * with a hook for future FK->PK inference (not implemented here yet).
+ */
+export function ruleJoinKeyInference(node, _context) {
+    if (!(node instanceof JoinNode))
+        return null;
+    if (node.joinType !== 'inner' && node.joinType !== 'cross')
+        return null;
+    const cond = node.getJoinCondition();
+    if (!cond || !(cond instanceof BinaryOpNode))
+        return null;
+    if (cond.expression.operator !== '=')
+        return null;
+    // Simple left.col = right.col pattern check; placeholder for future FK->PK detection
+    const leftIsCol = cond.left instanceof ColumnReferenceNode;
+    const rightIsCol = cond.right instanceof ColumnReferenceNode;
+    if (!leftIsCol || !rightIsCol)
+        return null;
+    log('Detected equi-join predicate; JoinNode.computePhysical will preserve side keys');
+    // No structural change needed now; computePhysical on JoinNode already preserves side keys
+    return null;
+}
+//# sourceMappingURL=rule-join-key-inference.js.map

package/dist/src/planner/rules/join/rule-join-key-inference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-join-key-inference.js","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-join-key-inference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,MAAM,GAAG,GAAG,YAAY,CAAC,mCAAmC,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAc,EAAE,QAAoB;IACvE,IAAI,CAAC,CAAC,IAAI,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAExE,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;IACrC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,YAAY,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAElD,qFAAqF;IACrF,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,YAAY,mBAAmB,CAAC;IAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,YAAY,mBAAmB,CAAC;IAC7D,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE3C,GAAG,CAAC,gFAAgF,CAAC,CAAC;IACtF,2FAA2F;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/planner/rules/join/rule-quickpick-enumeration.d.ts

@@ -0,0 +1,4 @@
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+export declare function ruleQuickPickJoinEnumeration(node: PlanNode, context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-quickpick-enumeration.d.ts.map

package/dist/src/planner/rules/join/rule-quickpick-enumeration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-quickpick-enumeration.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-quickpick-enumeration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAsC,MAAM,0BAA0B,CAAC;AAE7F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAyL7D,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CA4EjG"}

package/dist/src/planner/rules/join/rule-quickpick-enumeration.js

@@ -0,0 +1,233 @@
+import { createLogger } from '../../../common/logger.js';
+import { isRelationalNode } from '../../nodes/plan-node.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { normalizePredicate } from '../../analysis/predicate-normalizer.js';
+import { BinaryOpNode } from '../../nodes/scalar.js';
+import { ColumnReferenceNode } from '../../nodes/reference.js';
+const log = createLogger('optimizer:rule:quickpick');
+function extractJoinGraph(node) {
+    // Flatten INNER/CROSS join subtree into leaves (relations) and equi-predicates between them
+    const relations = [];
+    const attrIdToRel = new Map();
+    const pairToConds = new Map();
+    function addRelation(rel) {
+        const idx = relations.length;
+        relations.push(rel);
+        for (const attr of rel.getAttributes()) {
+            attrIdToRel.set(attr.id, idx);
+        }
+        return idx;
+    }
+    function addPairCond(aIdx, bIdx, cond) {
+        const [x, y] = aIdx < bIdx ? [aIdx, bIdx] : [bIdx, aIdx];
+        const key = `${x}:${y}`;
+        if (!pairToConds.has(key))
+            pairToConds.set(key, []);
+        pairToConds.get(key).push(cond);
+    }
+    function visit(n) {
+        if (n instanceof JoinNode) {
+            // Only enumerate INNER/CROSS joins; bail if OUTER join encountered
+            if (n.getJoinType() !== 'inner' && n.getJoinType() !== 'cross') {
+                relations.length = 0; // mark failure
+                return;
+            }
+            visit(n.getLeftSource());
+            visit(n.getRightSource());
+            // Analyze equi-join predicates
+            const cond = n.getJoinCondition();
+            if (cond) {
+                const norm = normalizePredicate(cond);
+                const stack = [norm];
+                while (stack.length) {
+                    const expr = stack.pop();
+                    if (expr instanceof BinaryOpNode && expr.expression.operator === 'AND') {
+                        stack.push(expr.left, expr.right);
+                    }
+                    else if (expr instanceof BinaryOpNode && expr.expression.operator === '=') {
+                        if (expr.left instanceof ColumnReferenceNode && expr.right instanceof ColumnReferenceNode) {
+                            const lRel = attrIdToRel.get(expr.left.attributeId);
+                            const rRel = attrIdToRel.get(expr.right.attributeId);
+                            if (lRel !== undefined && rRel !== undefined && lRel !== rRel) {
+                                addPairCond(lRel, rRel, expr);
+                            }
+                        }
+                    }
+                }
+            }
+            return;
+        }
+        if (isRelationalNode(n)) {
+            addRelation(n);
+            return;
+        }
+        // Traverse generic children otherwise
+        for (const c of n.getChildren())
+            visit(c);
+    }
+    visit(node);
+    if (relations.length === 0)
+        return null; // failure or non-join
+    // Build predicates array (AND-combine multiple per pair later during plan build)
+    const predicates = [];
+    for (const [key, conds] of pairToConds) {
+        const [aStr, bStr] = key.split(':');
+        const a = parseInt(aStr, 10);
+        const b = parseInt(bStr, 10);
+        // Leave multiple conditions to be AND-combined when consumed
+        const combined = conds.length === 1 ? conds[0] : conds.reduce((acc, cur) => new BinaryOpNode(relations[a].scope, { type: 'binary', operator: 'AND' }, acc, cur));
+        predicates.push({ leftIndex: a, rightIndex: b, condition: combined });
+    }
+    return { relations, predicates };
+}
+function estimatePlanCost(plan) {
+    // Use total cost, but apply penalties for cross products (no predicates between recent components)
+    // and reward key-covered joins via lower estimatedRows coming from computePhysical.
+    // Total cost already accumulates subtree costs; keep it as primary signal.
+    return plan.getTotalCost();
+}
+function buildLeftDeepPlan(order, graph) {
+    let current = null;
+    const chosen = new Set();
+    for (let i = 0; i < order.length; i++) {
+        const idx = order[i];
+        if (current === null) {
+            current = graph.relations[idx];
+            chosen.add(idx);
+            continue;
+        }
+        const next = graph.relations[idx];
+        // Gather all predicates that connect next to the chosen set
+        const connectors = [];
+        for (const p of graph.predicates) {
+            const connects = (chosen.has(p.leftIndex) && p.rightIndex === idx) || (chosen.has(p.rightIndex) && p.leftIndex === idx);
+            if (connects)
+                connectors.push(p.condition);
+        }
+        const cond = connectors.length === 0 ? undefined : connectors.reduce((acc, cur) => acc ? new BinaryOpNode(current.scope, { type: 'binary', operator: 'AND' }, acc, cur) : cur, undefined);
+        current = new JoinNode(current.scope, current, next, 'inner', cond);
+        chosen.add(idx);
+    }
+    return current;
+}
+// Greedy bushy: repeatedly merge the pair of components with minimal estimated join cost
+function buildBushyPlan(graph) {
+    const components = graph.relations.map((r, i) => ({ members: new Set([i]), plan: r }));
+    function predicatesBetween(a, b) {
+        const conns = [];
+        for (const p of graph.predicates) {
+            const lInA = a.members.has(p.leftIndex);
+            const rInA = a.members.has(p.rightIndex);
+            const lInB = b.members.has(p.leftIndex);
+            const rInB = b.members.has(p.rightIndex);
+            const crosses = (lInA && rInB) || (rInA && lInB);
+            if (crosses)
+                conns.push(p.condition);
+        }
+        if (conns.length === 0)
+            return undefined;
+        return conns.reduce((acc, cur) => acc ? new BinaryOpNode(graph.relations[0].scope, { type: 'binary', operator: 'AND' }, acc, cur) : cur, undefined);
+    }
+    while (components.length > 1) {
+        let bestI = -1, bestJ = -1;
+        let bestCost = Number.POSITIVE_INFINITY;
+        let bestPlan = null;
+        for (let i = 0; i < components.length; i++) {
+            for (let j = i + 1; j < components.length; j++) {
+                const a = components[i];
+                const b = components[j];
+                const cond = predicatesBetween(a, b);
+                const joined = new JoinNode(a.plan.scope, a.plan, b.plan, 'inner', cond);
+                const cost = estimatePlanCost(joined);
+                if (cost < bestCost) {
+                    bestCost = cost;
+                    bestI = i;
+                    bestJ = j;
+                    bestPlan = joined;
+                }
+            }
+        }
+        // Merge best pair
+        const a = components[bestI];
+        const b = components[bestJ];
+        const merged = { members: new Set([...a.members, ...b.members]), plan: bestPlan };
+        // Remove higher index first
+        components.splice(bestJ, 1);
+        components.splice(bestI, 1);
+        components.push(merged);
+    }
+    return components[0].plan;
+}
+export function ruleQuickPickJoinEnumeration(node, context) {
+    const qk = context.tuning.quickpick;
+    if (!qk?.enabled)
+        return null;
+    if (!(node instanceof JoinNode))
+        return null;
+    const graph = extractJoinGraph(node);
+    if (!graph)
+        return null;
+    if (graph.relations.length < 3)
+        return null; // Only helpful for 3+ relations
+    const baselineCost = estimatePlanCost(node);
+    if (baselineCost < (qk.minTriggerCost ?? 0))
+        return null;
+    const maxTours = qk.maxTours ?? 100;
+    let bestPlan = null;
+    let bestCost = Number.POSITIVE_INFINITY;
+    // Try multiple strategies: left-deep greedy from small bases and bushy greedy
+    const sizes = graph.relations.map(r => r.estimatedRows ?? 1e9);
+    const baseOrder = [...graph.relations.keys()].sort((a, b) => (sizes[a] - sizes[b]));
+    const start = Date.now();
+    let tours = 0;
+    while (tours < maxTours && (Date.now() - start) <= (qk.timeLimitMs ?? 100)) {
+        // Greedy NN tour: start with random among top-2 smallest
+        const startIdx = baseOrder[Math.min(tours % 2, baseOrder.length - 1)];
+        const remaining = new Set(graph.relations.keys());
+        remaining.delete(startIdx);
+        const order = [startIdx];
+        while (remaining.size > 0) {
+            let bestNext = null;
+            let bestIncCost = Number.POSITIVE_INFINITY;
+            for (const cand of remaining) {
+                // Prefer connected joins (has predicate to chosen set); penalize cross-products
+                const connected = graph.predicates.some(p => (order.some(o => o === p.leftIndex) && p.rightIndex === cand) ||
+                    (order.some(o => o === p.rightIndex) && p.leftIndex === cand));
+                const plan = buildLeftDeepPlan([...order, cand], graph);
+                let cost = estimatePlanCost(plan);
+                if (!connected)
+                    cost *= 10; // strong penalty for cross product
+                if (cost < bestIncCost) {
+                    bestIncCost = cost;
+                    bestNext = cand;
+                }
+            }
+            order.push(bestNext);
+            remaining.delete(bestNext);
+        }
+        const plan = buildLeftDeepPlan(order, graph);
+        const cost = estimatePlanCost(plan);
+        if (cost < bestCost) {
+            bestCost = cost;
+            bestPlan = plan;
+        }
+        tours++;
+    }
+    // Bushy attempt (one per invocation)
+    const bushy = buildBushyPlan(graph);
+    const bushyCost = estimatePlanCost(bushy);
+    if (bushyCost < bestCost) {
+        bestCost = bushyCost;
+        bestPlan = bushy;
+    }
+    if (!bestPlan)
+        return null;
+    // Always record diagnostics for visibility
+    context.diagnostics.quickpick = { tours, bestCost };
+    if (bestCost < baselineCost * 0.9) {
+        log('QuickPick replaced join plan (%.2f -> %.2f)', baselineCost, bestCost);
+        return bestPlan;
+    }
+    return null;
+}
+//# sourceMappingURL=rule-quickpick-enumeration.js.map

package/dist/src/planner/rules/join/rule-quickpick-enumeration.js.map

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

package/dist/src/planner/rules/predicate/rule-predicate-pushdown.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Rule: Predicate Pushdown (characteristic-driven)
+ *
+ * Goal: Move Filter predicates downward across safe commuting nodes (Sort, Distinct, eligible Project)
+ * and into the Retrieve pipeline boundary so modules can execute or exploit them.
+ *
+ * Safe moves implemented now:
+ * - Across Sort: always safe (ordering unaffected by selection)
+ * - Across Distinct: safe for selection predicates (commute)
+ * - Across Project: only if predicate references attribute IDs available below the Project source
+ *   (we verify attribute-id coverage), and we keep predicate unchanged (IDs preserved by design)
+ * - Into Retrieve: wrap Retrieve.source with a Filter
+ *
+ * Non-moves (for now):
+ * - Across Limit/Offset (changes semantics)
+ * - Across Aggregate/Window/Join (requires deeper analysis)
+ */
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+export declare function rulePredicatePushdown(node: PlanNode, _context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-predicate-pushdown.d.ts.map

package/dist/src/planner/rules/predicate/rule-predicate-pushdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-predicate-pushdown.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/predicate/rule-predicate-pushdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAsB,MAAM,0BAA0B,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAe7D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAc3F"}

package/dist/src/planner/rules/predicate/rule-predicate-pushdown.js

@@ -0,0 +1,125 @@
+/**
+ * Rule: Predicate Pushdown (characteristic-driven)
+ *
+ * Goal: Move Filter predicates downward across safe commuting nodes (Sort, Distinct, eligible Project)
+ * and into the Retrieve pipeline boundary so modules can execute or exploit them.
+ *
+ * Safe moves implemented now:
+ * - Across Sort: always safe (ordering unaffected by selection)
+ * - Across Distinct: safe for selection predicates (commute)
+ * - Across Project: only if predicate references attribute IDs available below the Project source
+ *   (we verify attribute-id coverage), and we keep predicate unchanged (IDs preserved by design)
+ * - Into Retrieve: wrap Retrieve.source with a Filter
+ *
+ * Non-moves (for now):
+ * - Across Limit/Offset (changes semantics)
+ * - Across Aggregate/Window/Join (requires deeper analysis)
+ */
+import { createLogger } from '../../../common/logger.js';
+import { isRelationalNode } from '../../nodes/plan-node.js';
+import { PlanNodeType } from '../../nodes/plan-node-type.js';
+import { FilterNode } from '../../nodes/filter.js';
+import { SortNode } from '../../nodes/sort.js';
+import { DistinctNode } from '../../nodes/distinct-node.js';
+import { ProjectNode } from '../../nodes/project-node.js';
+import { RetrieveNode } from '../../nodes/retrieve-node.js';
+import { CapabilityDetectors } from '../../framework/characteristics.js';
+import { normalizePredicate } from '../../analysis/predicate-normalizer.js';
+import { collectBindingsInExpr } from '../../analysis/binding-collector.js';
+import { extractConstraints, createTableInfoFromNode } from '../../analysis/constraint-extractor.js';
+const log = createLogger('optimizer:rule:predicate-pushdown');
+export function rulePredicatePushdown(node, _context) {
+    // Only act on Filter nodes
+    if (node.nodeType !== PlanNodeType.Filter)
+        return null;
+    const filter = node;
+    const normalized = normalizePredicate(filter.predicate);
+    // If no relational child, nothing to do
+    if (!isRelationalNode(filter.source))
+        return null;
+    const pushed = tryPushDown(filter.source, normalized, filter.scope);
+    if (!pushed)
+        return null;
+    return pushed;
+}
+function tryPushDown(child, predicate, scope) {
+    // Reach a Retrieve boundary: insert only the supported portion inside pipeline
+    if (child instanceof RetrieveNode) {
+        log('Pushing predicate into Retrieve pipeline (supported-only)');
+        const tableInfo = createTableInfoFromNode(child.tableRef, `${child.tableRef.tableSchema.name}`);
+        const extraction = extractConstraints(predicate, [tableInfo]);
+        const supported = extraction.supportedPredicateByTable?.get(tableInfo.relationKey);
+        if (!supported) {
+            log('No supported portion for this retrieve; not pushing');
+            return null;
+        }
+        const newInner = new FilterNode(child.source.scope, child.source, supported);
+        const newBindings = [
+            ...(child.bindings ?? []),
+            ...collectBindingsInExpr(supported, child.tableRef)
+        ];
+        const updatedRetrieve = child.withPipeline(newInner, child.moduleCtx, newBindings);
+        // If the supported portion equals the whole filter, remove original filter; else keep residual above
+        if (!extraction.residualPredicate) {
+            return updatedRetrieve;
+        }
+        return new FilterNode(scope, updatedRetrieve, extraction.residualPredicate);
+    }
+    // Across Sort
+    if (child instanceof SortNode) {
+        log('Pushing predicate below Sort');
+        const under = child.source;
+        const newUnder = new FilterNode(under.scope, under, predicate);
+        return new SortNode(child.scope, newUnder, child.sortKeys);
+    }
+    // Across Distinct
+    if (child instanceof DistinctNode) {
+        log('Pushing predicate below Distinct');
+        const under = child.source;
+        const newUnder = new FilterNode(under.scope, under, predicate);
+        return new DistinctNode(child.scope, newUnder);
+    }
+    // Across eligible Project
+    if (child instanceof ProjectNode) {
+        if (canPushAcrossProject(child, predicate)) {
+            log('Pushing predicate below Project (eligible)');
+            const under = child.source;
+            const newUnder = new FilterNode(under.scope, under, predicate);
+            // Rebuild Project with same projections over the filtered source
+            return new ProjectNode(child.scope, newUnder, child.projections, undefined, undefined, child.preserveInputColumns);
+        }
+        return null;
+    }
+    // Default: do not push across other nodes
+    return null;
+}
+function canPushAcrossProject(project, predicate) {
+    // If project preserves input columns and all predicate-attested attributes exist below, it's safe.
+    const sourceAttrIds = new Set(project.source.getAttributes().map(a => a.id));
+    const referenced = collectReferencedAttributeIds(predicate);
+    for (const id of referenced) {
+        if (!sourceAttrIds.has(id))
+            return false;
+    }
+    return true;
+}
+function collectReferencedAttributeIds(expr) {
+    const ids = new Set();
+    walkExpr(expr, node => {
+        if (CapabilityDetectors.isColumnReference(node)) {
+            ids.add(node.attributeId);
+        }
+    });
+    return ids;
+}
+function walkExpr(expr, fn) {
+    fn(expr);
+    for (const c of expr.getChildren()) {
+        // Only scalar children
+        if (!isRelationalNode(c)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            walkExpr(c, fn);
+        }
+    }
+}
+//# sourceMappingURL=rule-predicate-pushdown.js.map

package/dist/src/planner/rules/predicate/rule-predicate-pushdown.js.map

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

package/dist/src/planner/rules/retrieve/rule-grow-retrieve.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Rule: Grow Retrieve
+ *
+ * Structural sliding rule that maximizes the query segment each virtual table module can execute.
+ * This is a bottom-up transformation that slides RetrieveNode boundaries upward to encompass
+ * as much of the query pipeline as each module can handle.
+ *
+ * Applied When:
+ * - Node is a unary relational operation (Filter, Project, Sort, LimitOffset)
+ * - Child is a RetrieveNode
+ * - Virtual table module supports executing the expanded pipeline
+ *
+ * Benefits:
+ * - Maximizes push-down opportunities for query-based modules
+ * - Provides fallback support for index-style modules via constraint extraction
+ * - Establishes optimal module execution boundaries before cost-based optimization
+ */
+import { type PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+export declare function ruleGrowRetrieve(node: PlanNode, context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-grow-retrieve.d.ts.map

package/dist/src/planner/rules/retrieve/rule-grow-retrieve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-grow-retrieve.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/retrieve/rule-grow-retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAoB,KAAK,QAAQ,EAA2B,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAkC7D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAgHrF"}