@quereus/quereus 2.8.0 → 2.9.0

package/dist/src/planner/rules/join/rule-lateral-top1-asof.js

@@ -0,0 +1,405 @@
+/**
+ * Rule: Recognize lateral-top-1 over asof predicate, replace with AsofScanNode.
+ *
+ * Pattern (the rule peels through these in any nesting order, ignoring AliasNode):
+ *
+ *     JoinNode (joinType ∈ {inner, left, cross} with `on true` or no condition)
+ *       left:  Left
+ *       right: AliasNode? | ProjectNode | LimitOffsetNode(LIMIT 1, no OFFSET) | SortNode
+ *                 ...peeled in any nesting order...
+ *                 └─ FilterNode (ANDed: q.K op left.K  AND  q.P_i = left.P_i ...)
+ *                       └─ <physical right> with monotonicOn(K) and accessCapabilities.asofRight
+ *
+ * The right side must be correlated against the left (uses outer columns). On
+ * a successful match we emit an AsofScanNode preserving the JoinNode's output
+ * attribute IDs; otherwise we return null and the existing physical-join
+ * selection takes over.
+ */
+import { createLogger } from '../../../common/logger.js';
+import { isRelationalNode } from '../../nodes/plan-node.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { AsofScanNode } from '../../nodes/asof-scan-node.js';
+import { ProjectNode } from '../../nodes/project-node.js';
+import { LimitOffsetNode } from '../../nodes/limit-offset.js';
+import { SortNode } from '../../nodes/sort.js';
+import { FilterNode } from '../../nodes/filter.js';
+import { AliasNode } from '../../nodes/alias-node.js';
+import { BinaryOpNode, LiteralNode } from '../../nodes/scalar.js';
+import { ColumnReferenceNode, TableReferenceNode } from '../../nodes/reference.js';
+import { RetrieveNode } from '../../nodes/retrieve-node.js';
+import { isCorrelatedSubquery } from '../../cache/correlation-detector.js';
+const log = createLogger('optimizer:rule:lateral-top1-asof');
+/**
+ * Peel the right subtree of the lateral, looking for the canonical
+ * (Project | LimitOffset | Sort | Alias)* → Filter chain.
+ */
+function peelLateral(right) {
+    let project;
+    let limit;
+    let sort;
+    let cursor = right;
+    let safety = 16;
+    while (safety-- > 0) {
+        if (cursor instanceof AliasNode) {
+            cursor = cursor.source;
+            continue;
+        }
+        if (cursor instanceof ProjectNode) {
+            if (project)
+                return null; // multiple Projects not handled
+            project = cursor;
+            cursor = cursor.source;
+            continue;
+        }
+        if (cursor instanceof LimitOffsetNode) {
+            if (limit)
+                return null;
+            limit = cursor;
+            cursor = cursor.source;
+            continue;
+        }
+        if (cursor instanceof SortNode) {
+            if (sort)
+                return null;
+            sort = cursor;
+            cursor = cursor.source;
+            continue;
+        }
+        break;
+    }
+    if (!limit || !sort || !(cursor instanceof FilterNode))
+        return null;
+    return { filter: cursor, limit, sort, project };
+}
+/** Verify that the limit is the literal integer 1 and there's no offset. */
+function isLimitOne(limit) {
+    if (limit.offset && !isLiteralZeroOrUndefined(limit.offset))
+        return false;
+    if (!limit.limit)
+        return false;
+    if (!(limit.limit instanceof LiteralNode))
+        return false;
+    const v = limit.limit.expression.value;
+    if (typeof v === 'number')
+        return v === 1;
+    if (typeof v === 'bigint')
+        return v === 1n;
+    return false;
+}
+/** A null-or-zero literal for OFFSET. */
+function isLiteralZeroOrUndefined(node) {
+    if (!(node instanceof LiteralNode))
+        return false;
+    const v = node.expression.value;
+    if (v === null || v === undefined)
+        return true;
+    if (typeof v === 'number')
+        return v === 0;
+    if (typeof v === 'bigint')
+        return v === 0n;
+    return false;
+}
+/**
+ * Verify the SortNode has a single key that is a trivial column reference and
+ * a definite direction. Returns the attribute id and direction, or null.
+ */
+function extractSortAttrId(sort) {
+    if (sort.sortKeys.length !== 1)
+        return null;
+    const key = sort.sortKeys[0];
+    if (key.direction !== 'desc' && key.direction !== 'asc')
+        return null;
+    if (!(key.expression instanceof ColumnReferenceNode))
+        return null;
+    return { attrId: key.expression.attributeId, direction: key.direction };
+}
+/** Walk an AND tree, returning each leaf conjunct. */
+function flattenAnd(node) {
+    const result = [];
+    const stack = [node];
+    while (stack.length) {
+        const cur = stack.pop();
+        if (cur instanceof BinaryOpNode && cur.expression.operator === 'AND') {
+            stack.push(cur.left, cur.right);
+        }
+        else {
+            result.push(cur);
+        }
+    }
+    return result;
+}
+/**
+ * Classify each conjunct of the lateral's Filter.
+ *
+ * `rightAttrIds` is the set of attribute IDs defined within the lateral's
+ * inner subtree (anything below the Filter). The asof inequality must
+ * resolve to (right K op left K); equalities must resolve to (right P = left P).
+ *
+ * Returns null when any conjunct does not fit the asof shape.
+ */
+function classifyPredicates(conjuncts, rightAttrIds) {
+    let asof;
+    const partition = [];
+    for (const c of conjuncts) {
+        if (!(c instanceof BinaryOpNode))
+            return null;
+        if (!(c.left instanceof ColumnReferenceNode) || !(c.right instanceof ColumnReferenceNode))
+            return null;
+        const op = c.expression.operator;
+        const lAttrId = c.left.attributeId;
+        const rAttrId = c.right.attributeId;
+        const lFromRight = rightAttrIds.has(lAttrId);
+        const rFromRight = rightAttrIds.has(rAttrId);
+        // Both sides referencing the same side are not valid asof shape.
+        if (lFromRight === rFromRight)
+            return null;
+        // Canonicalize as (right side, left side).
+        const rightAttrId = lFromRight ? lAttrId : rAttrId;
+        const leftAttrId = lFromRight ? rAttrId : lAttrId;
+        if (op === '=') {
+            partition.push({ leftAttrId, rightAttrId });
+            continue;
+        }
+        // Asof inequality. Two directions are supported:
+        //   'desc' — right ≤ left (latest right ≤ left); strict variant: right < left.
+        //   'asc'  — right ≥ left (earliest right ≥ left); strict variant: right > left.
+        // All operator forms canonicalize to (right op left) before mapping:
+        //   - q.K <= t.K  → desc, strict=false        - q.K >= t.K  → asc, strict=false
+        //   - q.K <  t.K  → desc, strict=true         - q.K >  t.K  → asc, strict=true
+        //   - t.K >= q.K  → desc, strict=false        - t.K <= q.K  → asc, strict=false
+        //   - t.K >  q.K  → desc, strict=true         - t.K <  q.K  → asc, strict=true
+        let strict;
+        let direction;
+        if (lFromRight) {
+            // op is between (right.col, left.col)
+            if (op === '<=') {
+                strict = false;
+                direction = 'desc';
+            }
+            else if (op === '<') {
+                strict = true;
+                direction = 'desc';
+            }
+            else if (op === '>=') {
+                strict = false;
+                direction = 'asc';
+            }
+            else if (op === '>') {
+                strict = true;
+                direction = 'asc';
+            }
+        }
+        else {
+            // op is between (left.col, right.col); flip
+            if (op === '>=') {
+                strict = false;
+                direction = 'desc';
+            }
+            else if (op === '>') {
+                strict = true;
+                direction = 'desc';
+            }
+            else if (op === '<=') {
+                strict = false;
+                direction = 'asc';
+            }
+            else if (op === '<') {
+                strict = true;
+                direction = 'asc';
+            }
+        }
+        if (strict === undefined || direction === undefined)
+            return null;
+        if (asof)
+            return null; // multiple asof inequalities — bail
+        asof = { rightAttrId, leftAttrId, strict, direction };
+    }
+    if (!asof)
+        return null;
+    return { asof, partition };
+}
+/**
+ * Find the table reference at the bottom of a structural pipeline (Filter →
+ * AliasNode → ProjectNode → ... → Retrieve → TableReference).
+ *
+ * Returns null when the chain branches or terminates before reaching a leaf
+ * that's a direct TableReference.
+ */
+function findTableReference(node) {
+    let cur = node;
+    let safety = 64;
+    while (safety-- > 0) {
+        if (cur instanceof TableReferenceNode)
+            return cur;
+        if (cur instanceof RetrieveNode) {
+            cur = cur.tableRef;
+            continue;
+        }
+        const relChildren = cur.getChildren().filter(isRelationalNode);
+        if (relChildren.length !== 1)
+            return null;
+        cur = relChildren[0];
+    }
+    return null;
+}
+/**
+ * Probe the table's vtab module to see if its best-access plan would advertise
+ * `supportsAsofRight` and `monotonicOn` on `column` for an ordered, unfiltered
+ * scan. If the module lacks `getBestAccessPlan`, returns false.
+ */
+function tableAdvertisesAsof(context, tableRef, column) {
+    const vtabModule = tableRef.vtabModule;
+    if (!vtabModule.getBestAccessPlan)
+        return false;
+    const tableSchema = tableRef.tableSchema;
+    const columns = tableSchema.columns.map((col, index) => ({
+        index,
+        name: col.name,
+        type: col.logicalType,
+        isPrimaryKey: col.primaryKey || false,
+        isUnique: col.primaryKey || false,
+    }));
+    const request = {
+        columns,
+        filters: [],
+        requiredOrdering: [{ columnIndex: column, desc: false }],
+        estimatedRows: tableRef.estimatedRows ?? undefined,
+    };
+    try {
+        const plan = vtabModule.getBestAccessPlan(context.db, tableSchema, request);
+        if (!plan.supportsAsofRight)
+            return false;
+        if (!plan.monotonicOn)
+            return false;
+        if (plan.monotonicOn.columnIndex !== column)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isTriviallyTrue(condition) {
+    if (condition instanceof LiteralNode) {
+        const v = condition.expression.value;
+        return v === true || v === 1 || v === 1n;
+    }
+    return false;
+}
+/**
+ * Build right output column indices and preserve the projection's attribute IDs
+ * (so the parent of the JoinNode keeps seeing the same attribute IDs after the
+ * rewrite).
+ *
+ * Returns null when any projection isn't a trivial column reference into the
+ * Filter source.
+ */
+function resolveProjectedRightAttrs(project, joinAttrs, leftAttrCount, filterSourceAttrs) {
+    const filterIdToIndex = new Map(filterSourceAttrs.map((a, i) => [a.id, i]));
+    const rightOutputAttrs = joinAttrs.slice(leftAttrCount);
+    if (!project) {
+        // No projection — emit the filter source's columns directly. Attribute
+        // IDs match the filter source already (Project/Alias would have wrapped
+        // otherwise).
+        return {
+            columnIndices: filterSourceAttrs.map((_, i) => i),
+            attrs: rightOutputAttrs.slice(),
+        };
+    }
+    // With a projection: each projection node must be a trivial column ref into
+    // the filter source. Map its source attribute id → column index.
+    const projections = project.projections;
+    if (projections.length !== rightOutputAttrs.length)
+        return null;
+    const columnIndices = [];
+    for (let i = 0; i < projections.length; i++) {
+        const projNode = projections[i].node;
+        if (!(projNode instanceof ColumnReferenceNode))
+            return null;
+        const idx = filterIdToIndex.get(projNode.attributeId);
+        if (idx === undefined)
+            return null;
+        columnIndices.push(idx);
+    }
+    return {
+        columnIndices,
+        attrs: rightOutputAttrs.slice(),
+    };
+}
+export function ruleLateralTop1Asof(node, context) {
+    if (!(node instanceof JoinNode))
+        return null;
+    const joinType = node.joinType;
+    // LATERAL is meaningful for inner / left / cross with `ON TRUE` (or no condition).
+    if (joinType !== 'inner' && joinType !== 'left' && joinType !== 'cross')
+        return null;
+    // JoinNode condition must be absent or trivially true (LATERAL ON TRUE).
+    if (node.condition && !isTriviallyTrue(node.condition))
+        return null;
+    // Right subtree must be correlated against the outer (left) attributes.
+    if (!isCorrelatedSubquery(node.right))
+        return null;
+    const peeled = peelLateral(node.right);
+    if (!peeled)
+        return null;
+    if (!isLimitOne(peeled.limit))
+        return null;
+    const sortInfo = extractSortAttrId(peeled.sort);
+    if (sortInfo === null)
+        return null;
+    // The Filter's source defines the right attribute set we'll classify against.
+    const filterSourceAttrs = peeled.filter.source.getAttributes();
+    const rightAttrIds = new Set(filterSourceAttrs.map(a => a.id));
+    const conjuncts = flattenAnd(peeled.filter.predicate);
+    const classified = classifyPredicates(conjuncts, rightAttrIds);
+    if (!classified)
+        return null;
+    // Sort key must match the asof match attribute on the right.
+    if (classified.asof.rightAttrId !== sortInfo.attrId)
+        return null;
+    // Sort direction must match the asof direction (desc → latest-le, asc → earliest-ge).
+    if (sortInfo.direction !== classified.asof.direction)
+        return null;
+    // Locate the underlying table reference at the bottom of the lateral.
+    const tableRef = findTableReference(peeled.filter.source);
+    if (!tableRef) {
+        log('Right subtree does not bottom out in a TableReference');
+        return null;
+    }
+    // Translate the asof match attribute id to a table column index.
+    const tableAttrs = tableRef.getAttributes();
+    const matchColumnIdx = tableAttrs.findIndex(a => a.id === classified.asof.rightAttrId);
+    if (matchColumnIdx === -1) {
+        log('Asof match attr %d is not a column of the underlying table', classified.asof.rightAttrId);
+        return null;
+    }
+    // Probe the vtab module for asofRight + monotonicOn(K).
+    if (!tableAdvertisesAsof(context, tableRef, matchColumnIdx)) {
+        log('Vtab module does not advertise monotonicOn(col=%d) + asofRight', matchColumnIdx);
+        return null;
+    }
+    // Left must be monotonic on the match attribute (its cursor cannot regress
+    // per partition). Without this, the streaming scan would produce wrong rows
+    // for left rows whose match value decreases. We require global
+    // monotonicOn(left.matchAttr) — stronger than "monotonic within partition"
+    // but the only check we can make uniformly. The user can wrap the left in
+    // `ORDER BY matchAttr` to satisfy this.
+    const leftMonotonic = node.left.physical?.monotonicOn?.find(m => m.attrId === classified.asof.leftAttrId);
+    if (!leftMonotonic) {
+        log('Left input is not monotonicOn(left.matchAttr=%d); skipping asof rewrite', classified.asof.leftAttrId);
+        return null;
+    }
+    // Resolve the right output projection (preserving the original Project's
+    // attribute IDs so the parent of the join keeps the same IDs after rewrite).
+    const joinAttrs = node.getAttributes();
+    const leftAttrCount = node.left.getAttributes().length;
+    const projection = resolveProjectedRightAttrs(peeled.project, joinAttrs, leftAttrCount, filterSourceAttrs);
+    if (!projection) {
+        log('Lateral projection is non-trivial; skipping');
+        return null;
+    }
+    const asof = new AsofScanNode(node.scope, node.left, peeled.filter.source, { leftAttrId: classified.asof.leftAttrId, rightAttrId: classified.asof.rightAttrId }, classified.partition, classified.asof.strict, classified.asof.direction, joinType === 'left', projection.columnIndices, projection.attrs);
+    log('Recognized lateral-top-1 asof: outer=%s, direction=%s, strict=%s, partitions=%d', joinType === 'left', classified.asof.direction, classified.asof.strict, classified.partition.length);
+    return asof;
+}
+//# sourceMappingURL=rule-lateral-top1-asof.js.map

package/dist/src/planner/rules/join/rule-lateral-top1-asof.js.map

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

package/dist/src/planner/rules/join/rule-monotonic-merge-join.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Rule: Monotonic Merge Join
+ *
+ * Required Characteristics:
+ * - Node must be a logical JoinNode (not already physical)
+ * - Both inputs advertise `MonotonicOn` on (at least) one of the equi-pair
+ *   attributes, with matching direction (ASC for v1, since the merge-join
+ *   emitter assumes ASC ordering).
+ *
+ * Why this rule exists alongside `rule-join-physical-selection`:
+ * The existing rule chooses merge-join when both sources' `physical.ordering`
+ * matches the equi-pair attribute order positionally. That misses the canonical
+ * case where a merge-join's *output* declares `monotonicOn = [l.X, r.X]` but
+ * `ordering` reflects only the left side — a parent join on `r.X` then sees
+ * the right ordering implicitly through `monotonicOn` but not through
+ * `ordering[0]`. This rule looks the equi-pair attrs up directly in
+ * `monotonicOn`, recognising those (and other future MonotonicOn-propagating
+ * paths) without sorting.
+ *
+ * Out of scope (TODO):
+ * - Composite monotonic-on prefixes (multi-key streaming merge keyed on
+ *   `(X, Y)` when both sides are jointly monotonic on the prefix).
+ * - Right and full outer joins — emitter doesn't support them today.
+ * - Recognising `monotonicOn(asc)` vs `monotonicOn(desc)` by reversing one
+ *   side via Sort. That defeats this rule's premise (the rule's whole point is
+ *   that no sort is needed because both sides are already monotonic).
+ */
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+export declare function ruleMonotonicMergeJoin(node: PlanNode, _context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-monotonic-merge-join.d.ts.map

package/dist/src/planner/rules/join/rule-monotonic-merge-join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-monotonic-merge-join.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-monotonic-merge-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAA6B,MAAM,0BAA0B,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAU7D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAwF5F"}

package/dist/src/planner/rules/join/rule-monotonic-merge-join.js

@@ -0,0 +1,113 @@
+/**
+ * Rule: Monotonic Merge Join
+ *
+ * Required Characteristics:
+ * - Node must be a logical JoinNode (not already physical)
+ * - Both inputs advertise `MonotonicOn` on (at least) one of the equi-pair
+ *   attributes, with matching direction (ASC for v1, since the merge-join
+ *   emitter assumes ASC ordering).
+ *
+ * Why this rule exists alongside `rule-join-physical-selection`:
+ * The existing rule chooses merge-join when both sources' `physical.ordering`
+ * matches the equi-pair attribute order positionally. That misses the canonical
+ * case where a merge-join's *output* declares `monotonicOn = [l.X, r.X]` but
+ * `ordering` reflects only the left side — a parent join on `r.X` then sees
+ * the right ordering implicitly through `monotonicOn` but not through
+ * `ordering[0]`. This rule looks the equi-pair attrs up directly in
+ * `monotonicOn`, recognising those (and other future MonotonicOn-propagating
+ * paths) without sorting.
+ *
+ * Out of scope (TODO):
+ * - Composite monotonic-on prefixes (multi-key streaming merge keyed on
+ *   `(X, Y)` when both sides are jointly monotonic on the prefix).
+ * - Right and full outer joins — emitter doesn't support them today.
+ * - Recognising `monotonicOn(asc)` vs `monotonicOn(desc)` by reversing one
+ *   side via Sort. That defeats this rule's premise (the rule's whole point is
+ *   that no sort is needed because both sides are already monotonic).
+ */
+import { createLogger } from '../../../common/logger.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { MergeJoinNode } from '../../nodes/merge-join-node.js';
+import { nestedLoopJoinCost, hashJoinCost, mergeJoinCost } from '../../cost/index.js';
+import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
+import { extractEquiPairs, extractEquiPairsFromUsing, combineResidual, isMergeReadyOnAllPairs } from './equi-pair-extractor.js';
+const log = createLogger('optimizer:rule:monotonic-merge-join');
+export function ruleMonotonicMergeJoin(node, _context) {
+    if (!(node instanceof JoinNode))
+        return null;
+    const joinType = node.joinType;
+    if (joinType !== 'inner' && joinType !== 'left' && joinType !== 'semi' && joinType !== 'anti')
+        return null;
+    const leftAttrs = node.left.getAttributes();
+    const rightAttrs = node.right.getAttributes();
+    const leftAttrIds = new Set(leftAttrs.map(a => a.id));
+    const rightAttrIds = new Set(rightAttrs.map(a => a.id));
+    const extracted = node.condition
+        ? extractEquiPairs(node.condition, leftAttrIds, rightAttrIds)
+        : extractEquiPairsFromUsing(node.usingColumns, leftAttrs, rightAttrs);
+    if (!extracted || extracted.equiPairs.length === 0)
+        return null;
+    // Defer to `rule-join-physical-selection` whenever both sides' physical
+    // ordering already covers ALL equi-pairs in merge-ready order. The
+    // ordering-based path produces a multi-key merge join with full
+    // unique-key propagation; demoting pairs to residual here would lose that
+    // propagation. Our rule is meant to *extend* recognition, not regress it.
+    if (isMergeReadyOnAllPairs(node.left, node.right, extracted.equiPairs))
+        return null;
+    const leftMon = PlanNodeCharacteristics.getMonotonicOn(node.left);
+    const rightMon = PlanNodeCharacteristics.getMonotonicOn(node.right);
+    if (leftMon.length === 0 || rightMon.length === 0)
+        return null;
+    // Find equi-pairs where BOTH sides are MonotonicOn on their respective
+    // attrId with matching direction. v1 requires ASC because the merge-join
+    // emitter assumes ASC; DESC-DESC streaming would need a reversed compareKeys.
+    const matchedIndices = [];
+    for (let i = 0; i < extracted.equiPairs.length; i++) {
+        const pair = extracted.equiPairs[i];
+        const l = leftMon.find(m => m.attrId === pair.leftAttrId && m.direction === 'asc');
+        if (!l)
+            continue;
+        const r = rightMon.find(m => m.attrId === pair.rightAttrId && m.direction === 'asc');
+        if (!r)
+            continue;
+        matchedIndices.push(i);
+    }
+    if (matchedIndices.length === 0)
+        return null;
+    // v1: pick a single driving equi-pair. Other equi-pairs (matched or not)
+    // must be evaluated as residual conjuncts — the merge-join emitter assumes
+    // the right side is sorted lexicographically across ALL listed equi-pair
+    // columns, which we cannot guarantee for non-driving keys.
+    // TODO: composite monotonic-on prefixes — recognise when both sides are
+    // jointly MonotonicOn on a multi-key prefix and use multiple driving keys.
+    const drivingIndex = matchedIndices[0];
+    const driving = [extracted.equiPairs[drivingIndex]];
+    // Residualize the rest. For pairs that originated from a real `=` BinaryOpNode
+    // (ON-condition path), reuse the original node. For USING-derived pairs,
+    // `equiPairNodes[i]` is undefined — bail out and let the existing
+    // ordering-based rule handle USING-with-multiple-pairs.
+    const extras = [];
+    for (let i = 0; i < extracted.equiPairs.length; i++) {
+        if (i === drivingIndex)
+            continue;
+        const orig = extracted.equiPairNodes[i];
+        if (!orig)
+            return null;
+        extras.push(orig);
+    }
+    const residual = combineResidual(extracted.residual, extras);
+    // Cost gate: even with the precondition met, hash or nested-loop may win
+    // on tiny inputs. Don't regress those.
+    const leftRows = node.left.estimatedRows ?? 100;
+    const rightRows = node.right.estimatedRows ?? 100;
+    const mergeC = mergeJoinCost(leftRows, rightRows, false, false);
+    const hashC = hashJoinCost(Math.min(leftRows, rightRows), Math.max(leftRows, rightRows));
+    const nlC = nestedLoopJoinCost(leftRows, rightRows);
+    if (Math.min(hashC, nlC) < mergeC) {
+        log('Skipping monotonic-merge: cheaper alternative exists (merge=%.2f, hash=%.2f, nl=%.2f)', mergeC, hashC, nlC);
+        return null;
+    }
+    log('Selecting monotonic merge-join on equi-pair %d=%d (merge=%.2f, hash=%.2f, nl=%.2f)', driving[0].leftAttrId, driving[0].rightAttrId, mergeC, hashC, nlC);
+    return new MergeJoinNode(node.scope, node.left, node.right, joinType, driving, residual, node.getAttributes().slice());
+}
+//# sourceMappingURL=rule-monotonic-merge-join.js.map

package/dist/src/planner/rules/join/rule-monotonic-merge-join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-monotonic-merge-join.js","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-monotonic-merge-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEhI,MAAM,GAAG,GAAG,YAAY,CAAC,qCAAqC,CAAC,CAAC;AAEhE,MAAM,UAAU,sBAAsB,CAAC,IAAc,EAAE,QAAoB;IAC1E,IAAI,CAAC,CAAC,IAAI,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAE3G,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;IAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAExD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS;QAC/B,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,YAAY,CAAC;QAC7D,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACvE,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhE,wEAAwE;IACxE,mEAAmE;IACnE,gEAAgE;IAChE,0EAA0E;IAC1E,0EAA0E;IAC1E,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpF,MAAM,OAAO,GAAG,uBAAuB,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,uBAAuB,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/D,uEAAuE;IACvE,yEAAyE;IACzE,8EAA8E;IAC9E,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC;QACnF,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC;QACrF,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7C,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,2DAA2D;IAC3D,wEAAwE;IACxE,2EAA2E;IAC3E,MAAM,YAAY,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,OAAO,GAAmB,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAEpE,+EAA+E;IAC/E,yEAAyE;IACzE,kEAAkE;IAClE,wDAAwD;IACxD,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC,KAAK,YAAY;YAAE,SAAS;QACjC,MAAM,IAAI,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE7D,yEAAyE;IACzE,uCAAuC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,GAAG,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,GAAG,CAAC;IAClD,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;IACzF,MAAM,GAAG,GAAG,kBAAkB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC;QACnC,GAAG,CAAC,uFAAuF,EAC1F,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,oFAAoF,EACvF,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAEpE,OAAO,IAAI,aAAa,CACvB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,KAAK,EACV,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,IAAI,CAAC,aAAa,EAAE,CAAC,KAAK,EAAiB,CAC3C,CAAC;AACH,CAAC"}

package/dist/src/planner/rules/window/rule-monotonic-window.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Rule: Monotonic streaming window
+ *
+ * Recognizes a `WindowNode` whose source already streams in
+ * `[PARTITION BY..., ORDER BY[0]]` order — `physical.monotonicOn` covers the
+ * leading ORDER BY key and `physical.ordering` shows the partition keys as an
+ * emit-order prefix — and tags it with a `streaming` config so the runtime
+ * can switch from the buffer-and-sort path to a one-pass streaming emitter.
+ *
+ * Per-function recognition (all functions in the WindowNode must qualify; if
+ * any one falls through we keep the buffered path):
+ *
+ *   - `ROW_NUMBER` / `RANK` / `DENSE_RANK`
+ *   - `LAG(expr [, n [, default]])` / `LEAD(expr [, n [, default]])` with `n`
+ *     being a non-negative integer literal
+ *   - `FIRST_VALUE(expr)` / `LAST_VALUE(expr)` (last_value uses default frame ==
+ *     current row, so it's the trivial expr-on-current-row evaluation)
+ *   - `SUM` / `COUNT` / `AVG` / `MIN` / `MAX` over the default frame
+ *     (`UNBOUNDED PRECEDING TO CURRENT ROW`, ROWS or RANGE — RANGE handles peer
+ *     groups via delayed emit at peer boundaries)
+ *   - `SUM` / `COUNT` / `AVG` / `MIN` / `MAX` / `FIRST_VALUE` / `LAST_VALUE`
+ *     over a sliding frame `ROWS BETWEEN n PRECEDING AND m FOLLOWING` (literal
+ *     non-negative integers `n`, `m`) or `RANGE BETWEEN <num> PRECEDING AND
+ *     <num> FOLLOWING` (single numeric ORDER BY, literal non-negative offsets)
+ *
+ * Bail conditions:
+ *
+ *   - leading ORDER BY key is not a trivial column reference
+ *   - source's `monotonicOn` doesn't cover the leading key (or direction differs)
+ *   - source's `ordering` prefix doesn't include the full ORDER BY key set
+ *   - PARTITION BY columns aren't an emit-order prefix of the source ordering
+ *   - any partition-by expression is non-trivial (not a column reference)
+ *   - any function falls outside the recognized set, or is `DISTINCT`
+ *   - frame is anything other than the default (or the explicit equivalent
+ *     `UNBOUNDED PRECEDING TO CURRENT ROW` in `ROWS` or `RANGE`), or a
+ *     supported sliding shape (see above)
+ *
+ * Out of scope (deferred): NTILE/PERCENT_RANK/CUME_DIST (need partition size up
+ * front), DISTINCT aggregates, asymmetric sliding shapes
+ * (`UNBOUNDED PRECEDING AND m FOLLOWING`, `n PRECEDING AND UNBOUNDED FOLLOWING`,
+ * `CURRENT ROW AND m FOLLOWING`), splitting a mixed WindowNode into streaming +
+ * buffered halves.
+ */
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+export declare function ruleMonotonicWindow(node: PlanNode, _context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-monotonic-window.d.ts.map

package/dist/src/planner/rules/window/rule-monotonic-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-monotonic-window.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/window/rule-monotonic-window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AA8J7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAiJzF"}