@quereus/quereus 4.3.1 → 4.4.0

package/dist/src/planner/cache/materialization-advisory.js

@@ -5,6 +5,8 @@
 import { createLogger } from '../../common/logger.js';
 import { isRelationalNode } from '../nodes/plan-node.js';
 import { CacheNode } from '../nodes/cache-node.js';
+import { CTENode } from '../nodes/cte-node.js';
+import { RecursiveCTENode } from '../nodes/recursive-cte-node.js';
 import { PlanNodeType } from '../nodes/plan-node-type.js';
 import { ReferenceGraphBuilder } from './reference-graph.js';
 import { isCorrelatedSubquery } from './correlation-detector.js';
@@ -24,28 +26,166 @@ export class MaterializationAdvisory {
      * Returns the transformed tree or the original if no caching was added
      */
     analyzeAndTransform(root) {
-        // Build reference graph
+        // Build reference graph (exactly once per optimize — shared by both the
+        // CTE materialize-mark rewrite and the CacheNode recommendations below)
         const refGraph = this.referenceBuilder.buildReferenceGraph(root);
-        // Build recommendations
+        // Count references to each recursive CTE by its working-table descriptor.
+        // A multi-referenced recursive CTE is DUPLICATED into distinct
+        // RecursiveCTENode instances by earlier passes (each copy then has
+        // parentCount 1), but every copy preserves the one `tableDescriptor`
+        // identity — so summing parent counts per descriptor recovers the true
+        // reference count. A single-reference recursive CTE is never duplicated
+        // (one CTEReference parent, one path), so its descriptor sums to 1.
+        const recursiveRefsByDescriptor = new Map();
+        for (const [node, stats] of refGraph) {
+            if (node instanceof RecursiveCTENode) {
+                recursiveRefsByDescriptor.set(node.tableDescriptor, (recursiveRefsByDescriptor.get(node.tableDescriptor) ?? 0) + stats.parentCount);
+            }
+        }
+        // Mark multi-referenced / MATERIALIZED-hinted CTEs for shared
+        // materialization at emission. Memoized by node identity so a CTENode
+        // shared by several CTEReferenceNode parents is rewritten ONCE and the
+        // parents keep pointing at the same marked instance — emitCTE keys its
+        // per-execution buffer on that shared node's plan id. (Recursive CTEs use
+        // the descriptor count above instead — see markCTEMaterialization.)
+        const markMemo = new Map();
+        const markedRoot = this.markCTEMaterialization(root, refGraph, recursiveRefsByDescriptor, markMemo);
+        // Nodes inside any recursive CTE's recursive-case subtree must NEVER be
+        // cached. The recursive case is re-evaluated on every semi-naïve iteration
+        // against the changing working table (delta), so a CacheNode there would
+        // freeze it to the first iteration's rows — dropping rows (UNION DISTINCT
+        // terminates early) or looping forever (UNION ALL). This bites specifically
+        // when a recursive CTE is referenced 2+ times: earlier passes duplicate it
+        // into distinct instances that SHARE one recursive-case subtree, inflating
+        // that subtree's parent count to ≥2 and otherwise tripping the multi-parent
+        // cache rule. Collected for EVERY recursive CTE (not only multi-referenced
+        // ones): a single-reference recursive case never trips the multi-parent rule
+        // so excluding it is normally a no-op, but the exclusion is uniform because
+        // caching a working-table-dependent node is wrong regardless of ref count.
+        // NOTE: conservative — excludes EVERY node in a recursive-case subtree,
+        // including a subquery that never reads the working table (safe to cache).
+        // If an expensive working-table-independent subquery inside a recursive case
+        // ever shows up as slow, narrow this to only working-table-dependent nodes.
+        const noCacheNodes = new Set();
+        for (const [node] of refGraph) {
+            if (node instanceof RecursiveCTENode) {
+                this.collectSubtree(node.recursiveCaseQuery, noCacheNodes);
+            }
+        }
+        // Build recommendations. Keys are re-mapped through the mark memo so a
+        // recommendation lands on the (possibly rewritten) node instance that is
+        // actually present in the marked tree.
         const recommendations = new Map();
         for (const [node, stats] of refGraph) {
             // Only consider relational nodes for caching
             if (!isRelationalNode(node)) {
                 continue;
             }
+            if (noCacheNodes.has(node)) {
+                continue;
+            }
             const recommendation = this.adviseCaching(node, stats);
             if (recommendation.shouldCache) {
-                recommendations.set(node, recommendation);
+                recommendations.set(markMemo.get(node) ?? node, recommendation);
                 log('Recommending cache for %s: %s', node.nodeType, recommendation.reason);
             }
         }
         if (recommendations.size === 0) {
             log('No caching opportunities identified');
-            return root;
+            return markedRoot;
         }
         log('Found %d caching opportunities', recommendations.size);
         // Transform the tree by wrapping recommended nodes with CacheNode
-        return this.transformTree(root, recommendations);
+        return this.transformTree(markedRoot, recommendations);
+    }
+    /**
+     * Decide whether a non-recursive {@link CTENode} must be materialized once per
+     * statement execution. An explicit NOT MATERIALIZED hint is honored (the user
+     * opted into re-execution per reference); otherwise an explicit MATERIALIZED
+     * hint or two-plus references trips the mark.
+     *
+     * Recursive CTEs ({@link RecursiveCTENode}) do NOT flow through here — they run
+     * through the working-table machinery (emitRecursiveCTE), not emitCTE, and are
+     * marked by a dedicated branch in {@link markCTEMaterialization} that gates
+     * purely on reference count (the hint is deliberately ignored — see there).
+     */
+    shouldMaterializeCTE(node, stats) {
+        if (node.isRecursive)
+            return false;
+        if (node.materializationHint === 'not_materialized')
+            return false;
+        return node.materializationHint === 'materialized' || (stats?.parentCount ?? 0) >= 2;
+    }
+    /**
+     * Top-down memoized rewrite that sets the `materialize` flag on CTE nodes:
+     * on a non-recursive {@link CTENode} where {@link shouldMaterializeCTE} says so,
+     * and on a {@link RecursiveCTENode} whose working-table descriptor is referenced
+     * two-plus times (`recursiveRefsByDescriptor`).
+     *
+     * The memo (keyed by node identity) keeps a shared CTENode shared: the plain
+     * {@link transformChildren} walk is NOT memoized, so routing this mark through it
+     * would rebuild the CTENode once per referencing parent — two distinct marked
+     * instances with different plan ids, and emitCTE's per-execution buffer key
+     * would never match across references. (Recursive CTEs are already duplicated
+     * per parent by earlier passes; emitRecursiveCTE keys its buffer on the shared
+     * `tableDescriptor` instead of the plan id, so the mark just needs to land on
+     * every copy — which the descriptor count guarantees.)
+     */
+    markCTEMaterialization(node, refGraph, recursiveRefsByDescriptor, memo) {
+        const cached = memo.get(node);
+        if (cached) {
+            return cached;
+        }
+        const children = node.getChildren();
+        const newChildren = children.map(child => this.markCTEMaterialization(child, refGraph, recursiveRefsByDescriptor, memo));
+        const childrenChanged = newChildren.some((child, idx) => child !== children[idx]);
+        let result;
+        if (node instanceof CTENode && !node.materialize && this.shouldMaterializeCTE(node, refGraph.get(node))) {
+            const newSource = (childrenChanged ? newChildren[0] : node.source);
+            result = new CTENode(node.scope, node.cteName, node.columns, newSource, node.materializationHint, node.isRecursive, true);
+            log('Marked CTE %s for shared materialization', node.cteName);
+        }
+        else if (node instanceof RecursiveCTENode && !node.materialize && (recursiveRefsByDescriptor.get(node.tableDescriptor) ?? 0) >= 2) {
+            // Multi-referenced recursive CTE: drive the recursion once per execution
+            // into a shared buffer that every reference replays (emitRecursiveCTE),
+            // instead of each reference driving its own semi-naïve loop. Two
+            // interleaved drives share one working-table `tableDescriptor` and clobber
+            // each other's delta — the double-reference runaway this fixes.
+            //
+            // Gated on the DESCRIPTOR reference count, not this node's parentCount:
+            // earlier passes duplicate the shared node per reference (each copy then
+            // has parentCount 1), so per-node counting would miss it. The
+            // materializationHint is deliberately ignored — honoring NOT MATERIALIZED
+            // on a multi-referenced recursive CTE would re-introduce exactly that
+            // runaway, so correctness beats the hint here. `tableDescriptor` identity
+            // is preserved so the InternalRecursiveCTERefNode in the recursive case
+            // still resolves the same working table AND every duplicate keys the same
+            // shared buffer.
+            const withMarkedChildren = (childrenChanged ? node.withChildren(newChildren) : node);
+            result = withMarkedChildren.withMaterialize(true);
+            log('Marked recursive CTE %s for shared buffering (%d references)', node.cteName, recursiveRefsByDescriptor.get(node.tableDescriptor) ?? 0);
+        }
+        else if (childrenChanged) {
+            result = node.withChildren(newChildren);
+        }
+        else {
+            result = node;
+        }
+        memo.set(node, result);
+        return result;
+    }
+    /**
+     * Collect a node and every descendant (via `getChildren()`) into `out`.
+     * `out` doubles as the visited set, so a shared subtree is walked once.
+     */
+    collectSubtree(node, out) {
+        if (out.has(node)) {
+            return;
+        }
+        out.add(node);
+        for (const child of node.getChildren()) {
+            this.collectSubtree(child, out);
+        }
     }
     /**
      * Core advisory algorithm
@@ -79,44 +219,40 @@ export class MaterializationAdvisory {
                 reason: 'Correlated subquery - must re-execute for each outer row'
             };
         }
-        // Rule 4: Single-parent nodes that don't appear in loops typically don't benefit from caching
-        if (stats.parentCount <= 1 && !stats.appearsInLoop) {
+        // Rule 4: Single-parent nodes typically don't benefit from caching.
+        // (Loop-context caching for nested-loop join right sides is handled
+        // separately by rule-nested-loop-right-cache during physical optimization.)
+        if (stats.parentCount <= 1) {
             return {
                 shouldCache: false,
                 strategy: 'memory',
                 threshold: 0,
-                reason: 'Single parent, not in loop'
+                reason: 'Single parent'
             };
         }
-        // Rule 5: Multi-parent nodes benefit from caching
-        if (stats.parentCount > 1) {
-            const strategy = this.selectStrategy(stats.estimatedRows);
-            const threshold = this.calculateThreshold(stats.estimatedRows, strategy);
+        // Rule 5a: CTE and recursive-CTE nodes never take a CacheNode wrap. A
+        // multi-referenced (or MATERIALIZED-hinted) CTE is handled by the
+        // CTENode/RecursiveCTENode.materialize mark (see markCTEMaterialization) —
+        // emitCTE / emitRecursiveCTE buffer it once per execution. A CacheNode wrap
+        // here could never land anyway: CTEReferenceNode.withChildren rejects a
+        // non-CTE child, so transformChildren silently dropped the wrap.
+        if (node.nodeType === PlanNodeType.CTE || node.nodeType === PlanNodeType.RecursiveCTE) {
             return {
-                shouldCache: true,
-                strategy,
-                threshold,
-                reason: `Multiple parents (${stats.parentCount})`
+                shouldCache: false,
+                strategy: 'memory',
+                threshold: 0,
+                reason: 'CTE — shared materialization handled by the materialize mark'
             };
         }
-        // Rule 6: Nodes in loop contexts benefit from caching even with single parent
-        if (stats.appearsInLoop) {
-            // Check if the estimated size is reasonable for caching
-            if (stats.estimatedRows > this.tuning.join.maxRightRowsForCaching) {
-                return {
-                    shouldCache: false,
-                    strategy: 'memory',
-                    threshold: 0,
-                    reason: `In loop but too large (${stats.estimatedRows} rows)`
-                };
-            }
+        // Rule 5: Multi-parent nodes benefit from caching
+        if (stats.parentCount > 1) {
             const strategy = this.selectStrategy(stats.estimatedRows);
             const threshold = this.calculateThreshold(stats.estimatedRows, strategy);
             return {
                 shouldCache: true,
                 strategy,
                 threshold,
-                reason: 'Appears in loop context'
+                reason: `Multiple parents (${stats.parentCount})`
             };
         }
         // Default: no caching
@@ -174,21 +310,27 @@ export class MaterializationAdvisory {
         return transformedNode;
     }
     /**
-     * Transform children of a node
-     * This handles both scalar and relational children using a simpler approach
+     * Recurse into every child of a node and splice back any rewritten children.
      */
     transformChildren(node, recommendations) {
-        // For nodes that we know how to handle, transform their children
-        // For others, return the node as-is (the optimizer will handle it)
-        // First, try to transform scalar children using withChildren
-        const scalarChildren = node.getChildren();
-        const transformedScalarChildren = scalarChildren.map(child => this.transformTree(child, recommendations));
-        const scalarChanged = transformedScalarChildren.some((child, idx) => child !== scalarChildren[idx]);
-        if (scalarChanged) {
+        // getChildren() is the full child set — scalar AND relational
+        // (getRelations ⊆ getChildren). Recurse into every child; if any comes
+        // back wrapped in a CacheNode (or otherwise rewritten), splice the new
+        // children back in via withChildren.
+        const children = node.getChildren();
+        const transformedChildren = children.map(child => this.transformTree(child, recommendations));
+        const childrenChanged = transformedChildren.some((child, idx) => child !== children[idx]);
+        if (childrenChanged) {
             // Let withChildren handle the transformation
             // This will maintain proper attribute IDs and node structure
+            // NOTE: this catch degrades to "no caching for this subtree" (returns
+            // the untransformed node, dropping every CacheNode under it) rather
+            // than propagating like reference-graph does. Kept swallowing because
+            // it's perf-only — an uncached subtree still computes correct results —
+            // so a withChildren quirk shouldn't fail planning. If missed caching
+            // ever needs to be a hard error, promote this to a throw.
             try {
-                return node.withChildren(transformedScalarChildren);
+                return node.withChildren(transformedChildren);
             }
             catch (e) {
                 // If withChildren fails, log and return original
@@ -196,10 +338,11 @@ export class MaterializationAdvisory {
                 return node;
             }
         }
-        // If no scalar children changed, check if this node has relational children
-        // that might need caching. For now, we'll return the node as-is and let
-        // individual optimization rules handle relational transformations.
-        // This is safer than trying to recreate complex nodes.
+        // Nothing under this node changed. Because getChildren() already includes
+        // relational children, any recommended CacheNode deeper in the tree was
+        // spliced in via the withChildren branch above and propagated up — there
+        // are no untransformed relational children left for other rules to handle.
+        // Return the node unchanged.
         return node;
     }
 }

package/dist/src/planner/cache/materialization-advisory.js.map

@@ -1 +1 @@
-{"version":3,"file":"materialization-advisory.js","sourceRoot":"","sources":["../../../../src/planner/cache/materialization-advisory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"materialization-advisory.js","sourceRoot":"","sources":["../../../../src/planner/cache/materialization-advisory.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/cache/reference-graph.d.ts

@@ -16,16 +16,12 @@ import type { OptimizerTuning } from '../optimizer-tuning.js';
 export interface RefStats {
     /** Number of parent nodes referencing this node */
     parentCount: number;
-    /** Whether this node appears on the inner side of a nested loop or correlated subquery */
-    appearsInLoop: boolean;
     /** Estimated number of rows this node produces */
     estimatedRows: number;
     /** Whether this node is deterministic (same inputs produce same outputs) */
     deterministic: boolean;
     /** Parent nodes that reference this node (for debugging) */
     parents: Set<PlanNode>;
-    /** Estimated execution multiplier due to loop contexts */
-    loopMultiplier: number;
 }
 /**
  * Builds a reference graph for materialization decisions
@@ -43,7 +39,20 @@ export declare class ReferenceGraphBuilder {
      */
     private buildReferences;
     /**
-     * Visit all children of a node
+     * Visit every distinct child of a node exactly once.
+     *
+     * `getChildren()` is the full child set (scalar + relational); `getRelations()`
+     * is a subset of it (the base implementation is
+     * `getChildren().filter(isRelationalNode)`). `buildReferences` never early-returns
+     * on an already-seen node, so visiting a relational child from BOTH loops re-walks
+     * its whole subtree once per level — exponential in the relational-spine depth.
+     * Deduping to one visit per child collapses that back to a single linear walk;
+     * it is behavior-preserving because the parent `Set` already dedups parent counts
+     * and both loops carry the same `childContext`, so no stat changes.
+     *
+     * A `getChildren()` / `getRelations()` throw is a real bug, not an expected state,
+     * so it now propagates (no-silent-exceptions) — the previous catch silently dropped
+     * the whole subtree from the graph, which would suppress caching without a trace.
      */
     private visitAllChildren;
     /**

package/dist/src/planner/cache/reference-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-graph.d.ts","sourceRoot":"","sources":["../../../../src/planner/cache/reference-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,aAAa,EAAE,OAAO,CAAC;IACvB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;CACvB;AAcD;;GAEG;AACH,qBAAa,qBAAqB;IAGrB,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,MAAM,CAAiC;gBAE3B,MAAM,EAAE,eAAe;IAE3C;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAqB5D;;OAEG;IACH,OAAO,CAAC,eAAe;IA4CvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiCxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACH,OAAO,CAAC,eAAe;CAQvB"}
+{"version":3,"file":"reference-graph.d.ts","sourceRoot":"","sources":["../../../../src/planner/cache/reference-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;CACvB;AAUD;;GAEG;AACH,qBAAa,qBAAqB;IAGrB,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,MAAM,CAAiC;gBAE3B,MAAM,EAAE,eAAe;IAE3C;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAmB5D;;OAEG;IACH,OAAO,CAAC,eAAe;IAqCvB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACH,OAAO,CAAC,eAAe;CAQvB"}

package/dist/src/planner/cache/reference-graph.js

@@ -32,8 +32,6 @@ export class ReferenceGraphBuilder {
         // Build the reference graph with proper parent tracking
         const context = {
             parent: null,
-            inLoop: false,
-            loopIterations: 1
         };
         this.buildReferences(root, context);
         log('Built reference graph with %d nodes', this.refMap.size);
@@ -52,11 +50,9 @@ export class ReferenceGraphBuilder {
             // First time seeing this node
             stats = {
                 parentCount: 0,
-                appearsInLoop: context.inLoop,
                 estimatedRows: this.getEstimatedRows(node),
                 deterministic: this.isDeterministic(node),
                 parents: new Set(),
-                loopMultiplier: context.loopIterations
             };
             this.refMap.set(node, stats);
         }
@@ -65,55 +61,51 @@ export class ReferenceGraphBuilder {
             stats.parents.add(context.parent);
             stats.parentCount++;
         }
-        // Update loop context
-        if (context.inLoop) {
-            stats.appearsInLoop = true;
-            stats.loopMultiplier = Math.max(stats.loopMultiplier, context.loopIterations);
-        }
-        // Create child context - for now, we propagate the parent context
-        // In the future, if nodes expose execution strategy hints, we could use those
+        // Recurse with this node as the parent. Loop / execution-strategy context
+        // is intentionally NOT tracked here: this builder works on logical nodes
+        // and makes no assumptions about nested-loop vs hash/merge execution.
+        // Nested-loop right-side caching is handled by rule-nested-loop-right-cache
+        // during physical optimization, where the driver side is known.
         const childContext = {
             parent: node,
-            inLoop: context.inLoop,
-            loopIterations: context.loopIterations
         };
         // Visit all children uniformly
         this.visitAllChildren(node, childContext);
     }
     /**
-     * Visit all children of a node
+     * Visit every distinct child of a node exactly once.
+     *
+     * `getChildren()` is the full child set (scalar + relational); `getRelations()`
+     * is a subset of it (the base implementation is
+     * `getChildren().filter(isRelationalNode)`). `buildReferences` never early-returns
+     * on an already-seen node, so visiting a relational child from BOTH loops re-walks
+     * its whole subtree once per level — exponential in the relational-spine depth.
+     * Deduping to one visit per child collapses that back to a single linear walk;
+     * it is behavior-preserving because the parent `Set` already dedups parent counts
+     * and both loops carry the same `childContext`, so no stat changes.
+     *
+     * A `getChildren()` / `getRelations()` throw is a real bug, not an expected state,
+     * so it now propagates (no-silent-exceptions) — the previous catch silently dropped
+     * the whole subtree from the graph, which would suppress caching without a trace.
      */
     visitAllChildren(node, childContext) {
-        // 1. Scalar children (expressions)
-        try {
-            const children = node.getChildren();
-            for (const child of children) {
-                if (child) {
-                    this.buildReferences(child, childContext);
-                }
+        const visited = new Set();
+        for (const child of node.getChildren()) {
+            if (child && !visited.has(child)) {
+                visited.add(child);
+                this.buildReferences(child, childContext);
             }
         }
-        catch (e) {
-            log('Warning: Failed to get children for node %s: %s', node.nodeType, e);
-        }
-        // 2. Relational children
-        // Note: getRelations() returns a subset of getChildren() for nodes that have relational children
-        // We need to be careful not to double-count, but since we're using a Set for parents,
-        // and checking if we've already added a parent, this should be fine
+        // Defensive: pick up any relation not already surfaced by getChildren().
+        // With the base getRelations() this loop is a no-op, but a node that
+        // overrides getRelations() to expose an extra relation still gets counted.
         if (isRelationalNode(node)) {
-            try {
-                const relations = node.getRelations();
-                for (const relation of relations) {
-                    if (relation) {
-                        // For now, treat all relational children the same
-                        // In the future, nodes could provide hints about execution patterns
-                        this.buildReferences(relation, childContext);
-                    }
+            for (const relation of node.getRelations()) {
+                if (relation && !visited.has(relation)) {
+                    visited.add(relation);
+                    this.buildReferences(relation, childContext);
                 }
             }
-            catch (e) {
-                log('Warning: Failed to get relations for node %s: %s', node.nodeType, e);
-            }
         }
     }
     /**

package/dist/src/planner/cache/reference-graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"reference-graph.js","sourceRoot":"","sources":["../../../../src/planner/cache/reference-graph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reference-graph.js","sourceRoot":"","sources":["../../../../src/planner/cache/reference-graph.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/cost/index.d.ts

@@ -127,11 +127,17 @@ export declare function chooseCheapest<T>(options: Array<{
     option: T;
 }>): T;
 /**
- * The maintenance strategies the incremental substrate names. Mirrors
- * `MaintenancePlan['kind']` in core/database-materialized-views.ts (the maintenance
- * arms reference this type for their `kind`/`chosenStrategy` fields).
- */
-export type MaintenanceStrategy = 'inverse-projection' | 'residual-recompute' | 'full-rebuild';
+ * The maintenance strategies the incremental substrate **costs** — a subset of
+ * `MaintenancePlan['kind']` in core/database-materialized-views.ts, plus
+ * `'delta-aggregate'`: the arithmetic fast path INSIDE the `'residual-recompute'` arm
+ * (the plan kind stays `'residual-recompute'`; the apply path routes on the plan's
+ * `delta` descriptor). The arms the cost model does not distinguish (`'prefix-delete'`,
+ * `'join-residual'`) record the strategy they are costed as (`'residual-recompute'`) in
+ * their `chosenStrategy`. Each arm builder calls {@link selectMaintenanceStrategy} with
+ * its own sound set and rejects any answer outside it as INTERNAL, so the gate can never
+ * hand back a strategy no arm implements (docs/invariants.md MV-007).
+ */
+export type MaintenanceStrategy = 'inverse-projection' | 'residual-recompute' | 'delta-aggregate' | 'full-rebuild';
 /**
  * Default source row count above which a per-write `'full-rebuild'` is pathological under
  * the synchronous (row-time, in-transaction) policy: every DML statement on the source
@@ -161,6 +167,12 @@ export interface MaintenanceSourceStats {
     forwardBodyCost: number;
     /** No-stats fallback multiplier; the gate supplies tuning.deltaPerRowFallbackRatio. */
     fallbackRatio?: number;
+    /** Expected fraction of changes to a **tighten-only** (min/max) delta-aggregate body
+     *  that retract and so fall back to the key-filtered residual for their group. Set at
+     *  create only for a `'delta-aggregate'` body carrying a tighten column (min/max, or a
+     *  join-semilattice UDAF — `merge`, no `negate`); blended into the delta cost by
+     *  {@link maintenanceCost}. Absent/0 ⇒ pure-group body, delta cost unchanged. */
+    deltaTightenFallbackRatio?: number;
 }
 /**
  * Backward (maintenance-direction) cost of applying `strategy` to `changeCardinality`
@@ -176,6 +188,19 @@ export interface MaintenanceSourceStats {
  *    group. With stats, costed against rows-per-group (tableRows / distinctGroupsEstimate);
  *    with no stats, falls back to the legacy `deltaPerRowFallbackRatio` heuristic so
  *    behaviour is unchanged on the no-stats path.
+ *  - `'delta-aggregate'`: O(1) arithmetic per changed row plus one read-modify-write of
+ *    the stored group row per affected group — no source read, no residual re-execution.
+ *    Modeled as an index seek + reprojection per change (the same shape as
+ *    inverse-projection), CAPPED at half the residual per-group cost: per affected
+ *    group the delta does strictly less work than the residual (one point RMW vs a
+ *    key-filtered body re-execution over that group's source rows), so it must cost
+ *    strictly below `'residual-recompute'` for every stats input — including a
+ *    small/empty source at create time, where the residual's no-stats fallback
+ *    (`forwardBodyCost × ratio`) shrinks below any fixed constant. A body carrying a
+ *    **tighten-only** (min/max) column blends in `deltaTightenFallbackRatio` — the expected
+ *    fraction of retracting changes that re-derive their group from the full residual — so
+ *    it costs strictly more than a pure-group body but, for the small create-time estimate,
+ *    still below the always-residual arm.
  *  - `'full-rebuild'`: re-evaluate the whole body once — the always-correct floor,
  *    independent of changeCardinality.
  */

package/dist/src/planner/cost/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/planner/cost/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/planner/cost/index.ts"],"names":[],"mappings":"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"}