@quereus/quereus 0.2.0 → 0.4.0

package/dist/src/planner/rules/aggregate/rule-aggregate-streaming.js

@@ -1,113 +1,121 @@
 /**
  * Rule: Aggregate Streaming
  *
- * Transforms: AggregateNode → StreamAggregateNode (with Sort if needed)
- * Conditions: Logical aggregate node needs physical implementation
- * Benefits: Enables streaming aggregation with proper grouping order
+ * Required Characteristics:
+ * - Node must support aggregation operations (AggregationCapable interface)
+ * - Node must be relational (produces rows)
+ * - Node must be read-only (no side effects for streaming)
+ *
+ * Applied When:
+ * - Logical aggregate node needs physical streaming implementation
+ * - Source data can be processed incrementally
+ *
+ * Benefits: Enables streaming aggregation with proper grouping order, memory efficient processing
  */
 import { createLogger } from '../../../common/logger.js';
-import { AggregateNode } from '../../nodes/aggregate-node.js';
 import { StreamAggregateNode } from '../../nodes/stream-aggregate.js';
 import { SortNode } from '../../nodes/sort.js';
+import { PlanNodeCharacteristics, CapabilityDetectors } from '../../framework/characteristics.js';
 const log = createLogger('optimizer:rule:aggregate-streaming');
 export function ruleAggregateStreaming(node, _context) {
-    // Guard: only apply to AggregateNode
-    if (!(node instanceof AggregateNode)) {
+    // Guard: node must support aggregation operations
+    if (!CapabilityDetectors.isAggregating(node)) {
         return null;
     }
     log('Applying aggregate streaming rule to node %s', node.id);
-    // Source is already optimized by framework
-    const source = node.source;
-    // For now, always use StreamAggregate
-    // TODO: Check if source is ordered on groupBy columns
-    // TODO: Consider HashAggregate for unordered inputs
-    if (node.groupBy.length > 0) {
+    // Get aggregation characteristics
+    const aggregateNode = node;
+    const groupingKeys = aggregateNode.getGroupingKeys();
+    const aggregateExpressions = aggregateNode.getAggregateExpressions();
+    // Check if we can stream the aggregation over the source
+    const source = aggregateNode.getSource();
+    // Check if streaming aggregation is beneficial
+    if (!aggregateNode.canStreamAggregate()) {
+        log('Node cannot use streaming aggregation, skipping');
+        return null;
+    }
+    if (groupingKeys.length > 0) {
         // Need to ensure ordering for streaming aggregate
-        // For now, always insert a sort
-        // TODO: Check if source already provides the required ordering
-        const sortKeys = node.groupBy.map(expr => ({
-            expression: expr,
-            direction: 'asc',
-            nulls: undefined
-        }));
-        const sortNode = new SortNode(node.scope, source, sortKeys);
-        // Create combined attributes: AggregateNode attributes + source attributes
-        // This ensures both GROUP BY/aggregate AND source column attribute IDs are preserved
-        const aggregateAttrs = node.getAttributes();
-        const sourceAttrs = node.source.getAttributes();
-        // Deduplicate by column NAME to avoid duplicate columns like 'id'
-        // (The same logical column can have different attribute IDs between aggregate and source)
-        const seenNames = new Set();
-        const combinedAttrs = [];
-        // Add aggregate attributes first (GROUP BY + aggregates)
-        for (const attr of aggregateAttrs) {
-            combinedAttrs.push(attr);
-            seenNames.add(attr.name);
-        }
-        // Add source attributes that aren't already present by name
-        for (const attr of sourceAttrs) {
-            if (!seenNames.has(attr.name)) {
-                combinedAttrs.push(attr);
-                seenNames.add(attr.name);
-            }
+        // Check if source already provides the required ordering
+        const sourceOrdering = PlanNodeCharacteristics.getOrdering(source);
+        const needsSort = !isOrderedForGrouping(sourceOrdering, groupingKeys);
+        let sortedSource = source;
+        if (needsSort) {
+            // Insert sort to ensure proper grouping order
+            const sortKeys = groupingKeys.map(expr => ({
+                expression: expr,
+                direction: 'asc',
+                nulls: undefined
+            }));
+            sortedSource = new SortNode(node.scope, source, sortKeys);
+            log('Inserted sort for grouping keys');
         }
-        // Final safety-pass: filter duplicates that may have slipped through
-        const uniqueByName = new Set();
-        const deduped = [];
-        for (const attr of combinedAttrs) {
-            if (!uniqueByName.has(attr.name)) {
-                deduped.push(attr);
-                uniqueByName.add(attr.name);
-            }
+        else {
+            log('Source already provides required ordering for streaming');
         }
-        const finalAttrs = deduped;
-        const result = new StreamAggregateNode(node.scope, sortNode, node.groupBy, node.aggregates, undefined, // estimatedCostOverride
-        finalAttrs // unique list
-        );
-        // Let framework set physical properties via markPhysical()
-        // Both SortNode and StreamAggregateNode have getPhysical() methods
-        log('Transformed AggregateNode to StreamAggregateNode with sort');
+        // Create combined attributes preserving attribute IDs
+        const finalAttrs = combineAttributes(node.getAttributes(), source.getAttributes());
+        // Convert aggregate expressions to match StreamAggregateNode interface
+        const streamAggregates = aggregateExpressions.map(agg => ({
+            expression: agg.expr,
+            alias: agg.alias
+        }));
+        const result = new StreamAggregateNode(node.scope, sortedSource, groupingKeys, streamAggregates, undefined, // estimatedCostOverride
+        finalAttrs);
+        log('Transformed aggregation to StreamAggregateNode with %s', needsSort ? 'sort' : 'existing order');
         return result;
     }
     else {
         // No GROUP BY - can stream aggregate without sorting
-        // Create combined attributes: AggregateNode attributes + source attributes
-        // This ensures both GROUP BY/aggregate AND source column attribute IDs are preserved
-        const aggregateAttrs = node.getAttributes();
-        const sourceAttrs = node.source.getAttributes();
-        // Deduplicate by column NAME to avoid duplicate columns like 'id'
-        // (The same logical column can have different attribute IDs between aggregate and source)
-        const seenNames = new Set();
-        const combinedAttrs = [];
-        // Add aggregate attributes first (GROUP BY + aggregates)
-        for (const attr of aggregateAttrs) {
+        const finalAttrs = combineAttributes(node.getAttributes(), source.getAttributes());
+        // Convert aggregate expressions to match StreamAggregateNode interface
+        const streamAggregates = aggregateExpressions.map(agg => ({
+            expression: agg.expr,
+            alias: agg.alias
+        }));
+        const result = new StreamAggregateNode(node.scope, source, groupingKeys, streamAggregates, undefined, // estimatedCostOverride
+        finalAttrs);
+        log('Transformed aggregation to StreamAggregateNode without sort');
+        return result;
+    }
+}
+/**
+ * Check if source ordering matches grouping requirements for streaming
+ */
+function isOrderedForGrouping(_ordering, _groupingKeys) {
+    // TODO: Implement proper ordering analysis
+    // For now, conservatively return false to always sort
+    // This should check if the ordering covers all grouping keys in order
+    return false;
+}
+/**
+ * Combine attributes from aggregate and source, avoiding duplicates by name
+ * This preserves attribute IDs while ensuring unique column names
+ */
+function combineAttributes(aggregateAttrs, sourceAttrs) {
+    const seenNames = new Set();
+    const combinedAttrs = [];
+    // Add aggregate attributes first (GROUP BY + aggregates)
+    for (const attr of aggregateAttrs) {
+        combinedAttrs.push(attr);
+        seenNames.add(attr.name);
+    }
+    // Add source attributes that aren't already present by name
+    for (const attr of sourceAttrs) {
+        if (!seenNames.has(attr.name)) {
             combinedAttrs.push(attr);
             seenNames.add(attr.name);
         }
-        // Add source attributes that aren't already present by name
-        for (const attr of sourceAttrs) {
-            if (!seenNames.has(attr.name)) {
-                combinedAttrs.push(attr);
-                seenNames.add(attr.name);
-            }
-        }
-        // Final safety-pass: filter duplicates that may have slipped through
-        const uniqueByName = new Set();
-        const deduped = [];
-        for (const attr of combinedAttrs) {
-            if (!uniqueByName.has(attr.name)) {
-                deduped.push(attr);
-                uniqueByName.add(attr.name);
-            }
+    }
+    // Final deduplication pass
+    const uniqueByName = new Set();
+    const deduped = [];
+    for (const attr of combinedAttrs) {
+        if (!uniqueByName.has(attr.name)) {
+            deduped.push(attr);
+            uniqueByName.add(attr.name);
         }
-        const finalAttrs = deduped;
-        const result = new StreamAggregateNode(node.scope, source, node.groupBy, node.aggregates, undefined, // estimatedCostOverride
-        finalAttrs // unique list
-        );
-        // Let framework set physical properties via markPhysical()
-        // StreamAggregateNode has getPhysical() method
-        log('Transformed AggregateNode to StreamAggregateNode without sort');
-        return result;
     }
+    return deduped;
 }
 //# sourceMappingURL=rule-aggregate-streaming.js.map

package/dist/src/planner/rules/aggregate/rule-aggregate-streaming.js.map

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

package/dist/src/planner/rules/cache/rule-cte-optimization.d.ts

@@ -1,8 +1,14 @@
 /**
  * Rule: CTE Optimization
  *
- * Transforms: CTENode → CTENode (with caching when beneficial)
- * Conditions: CTE would benefit from materialization/caching
+ * Required Characteristics:
+ * - Node must support CTE operations (CTECapable interface)
+ * - Node must be relational (produces rows)
+ * - Source must be cacheable for materialization
+ *
+ * Applied When:
+ * - CTE would benefit from materialization/caching based on cost analysis
+ *
  * Benefits: Reduces redundant computation for repeated CTE access
  */
 import type { PlanNode } from '../../nodes/plan-node.js';

package/dist/src/planner/rules/cache/rule-cte-optimization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-cte-optimization.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-cte-optimization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAgDxF"}
+{"version":3,"file":"rule-cte-optimization.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-cte-optimization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAuDxF"}

package/dist/src/planner/rules/cache/rule-cte-optimization.js

@@ -1,35 +1,46 @@
 /**
  * Rule: CTE Optimization
  *
- * Transforms: CTENode → CTENode (with caching when beneficial)
- * Conditions: CTE would benefit from materialization/caching
+ * Required Characteristics:
+ * - Node must support CTE operations (CTECapable interface)
+ * - Node must be relational (produces rows)
+ * - Source must be cacheable for materialization
+ *
+ * Applied When:
+ * - CTE would benefit from materialization/caching based on cost analysis
+ *
  * Benefits: Reduces redundant computation for repeated CTE access
  */
 import { createLogger } from '../../../common/logger.js';
 import { CTENode } from '../../nodes/cte-node.js';
 import { CacheNode } from '../../nodes/cache-node.js';
-import { PlanNodeType } from '../../nodes/plan-node-type.js';
+import { CapabilityDetectors, CachingAnalysis, PlanNodeCharacteristics } from '../../framework/characteristics.js';
 const log = createLogger('optimizer:rule:cte-optimization');
 export function ruleCteOptimization(node, context) {
-    // Guard: only apply to CTENode
-    if (!(node instanceof CTENode)) {
+    // Guard: node must support CTE operations
+    if (!CapabilityDetectors.isCTE(node)) {
         return null;
     }
-    log('Optimizing CTENode %s', node.cteName);
+    // Get CTE characteristics
+    const cteNode = node;
+    log('Optimizing CTE %s', cteNode.cteName);
     // Source is already optimized by framework
-    const source = node.source;
+    const source = cteNode.getCTESource();
     // Heuristics for when to cache CTEs:
     // 1. CTE has materialization hint
     // 2. CTE is estimated to be reasonably sized
     // 3. CTE is not already cached
-    const sourceSize = source.estimatedRows ?? context.tuning.defaultRowEstimate;
-    const shouldCache = (node.materializationHint === 'materialized' ||
-        (sourceSize > 0 && sourceSize < context.tuning.cte.maxSizeForCaching)) && source.nodeType !== PlanNodeType.Cache;
+    const sourceSize = PlanNodeCharacteristics.estimatesRows(source);
+    const isAlreadyCached = CapabilityDetectors.isCached(source) && source.isCached();
+    const shouldCache = (cteNode.materializationHint === 'materialized' ||
+        (sourceSize > 0 && sourceSize < context.tuning.cte.maxSizeForCaching)) && !isAlreadyCached;
     if (shouldCache) {
-        log('Adding cache to CTE %s (estimated rows: %d)', node.cteName, sourceSize);
-        const cacheThreshold = Math.min(sourceSize * context.tuning.cte.cacheThresholdMultiplier, context.tuning.cte.maxCacheThreshold);
+        log('Adding cache to CTE %s (estimated rows: %d)', cteNode.cteName, sourceSize);
+        // Use characteristics-based cache threshold calculation
+        const cacheThreshold = Math.min(CachingAnalysis.getCacheThreshold(source), context.tuning.cte.maxCacheThreshold);
         const cachedSource = new CacheNode(source.scope, source, 'memory', cacheThreshold);
-        const result = new CTENode(node.scope, node.cteName, node.columns, cachedSource, node.materializationHint, node.isRecursive);
+        // Create new CTE with cached source (specific to CTENode implementation)
+        const result = new CTENode(node.scope, cteNode.cteName, cteNode.columns, cachedSource, cteNode.materializationHint, cteNode.isRecursive);
         log('Created CTE with caching');
         return result;
     }

package/dist/src/planner/rules/cache/rule-cte-optimization.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-cte-optimization.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-cte-optimization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,MAAM,GAAG,GAAG,YAAY,CAAC,iCAAiC,CAAC,CAAC;AAE5D,MAAM,UAAU,mBAAmB,CAAC,IAAc,EAAE,OAAmB;IACtE,+BAA+B;IAC/B,IAAI,CAAC,CAAC,IAAI,YAAY,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,uBAAuB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE3C,2CAA2C;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAE3B,qCAAqC;IACrC,kCAAkC;IAClC,6CAA6C;IAC7C,+BAA+B;IAC/B,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC;IAC7E,MAAM,WAAW,GAAG,CACnB,IAAI,CAAC,mBAAmB,KAAK,cAAc;QAC3C,CAAC,UAAU,GAAG,CAAC,IAAI,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CACrE,IAAI,MAAM,CAAC,QAAQ,KAAK,YAAY,CAAC,KAAK,CAAC;IAE5C,IAAI,WAAW,EAAE,CAAC;QACjB,GAAG,CAAC,6CAA6C,EAAE,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7E,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC9B,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,wBAAwB,EACxD,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,iBAAiB,CACpC,CAAC;QACF,MAAM,YAAY,GAAG,IAAI,SAAS,CACjC,MAAM,CAAC,KAAK,EACZ,MAAM,EACN,QAAQ,EACR,cAAc,CACd,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,OAAO,CACzB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,OAAO,EACZ,YAAY,EACZ,IAAI,CAAC,mBAAmB,EACxB,IAAI,CAAC,WAAW,CAChB,CAAC;QAEF,GAAG,CAAC,0BAA0B,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC,CAAC,2BAA2B;AACzC,CAAC"}
+{"version":3,"file":"rule-cte-optimization.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-cte-optimization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,uBAAuB,EAAmB,MAAM,oCAAoC,CAAC;AAEpI,MAAM,GAAG,GAAG,YAAY,CAAC,iCAAiC,CAAC,CAAC;AAE5D,MAAM,UAAU,mBAAmB,CAAC,IAAc,EAAE,OAAmB;IACtE,0CAA0C;IAC1C,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,0BAA0B;IAC1B,MAAM,OAAO,GAAG,IAAkB,CAAC;IACnC,GAAG,CAAC,mBAAmB,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C,2CAA2C;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAEtC,qCAAqC;IACrC,kCAAkC;IAClC,6CAA6C;IAC7C,+BAA+B;IAC/B,MAAM,UAAU,GAAG,uBAAuB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,eAAe,GAAG,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;IAClF,MAAM,WAAW,GAAG,CACnB,OAAO,CAAC,mBAAmB,KAAK,cAAc;QAC9C,CAAC,UAAU,GAAG,CAAC,IAAI,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CACrE,IAAI,CAAC,eAAe,CAAC;IAEtB,IAAI,WAAW,EAAE,CAAC;QACjB,GAAG,CAAC,6CAA6C,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAEhF,wDAAwD;QACxD,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC9B,eAAe,CAAC,iBAAiB,CAAC,MAAM,CAAC,EACzC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,iBAAiB,CACpC,CAAC;QAEF,MAAM,YAAY,GAAG,IAAI,SAAS,CACjC,MAAM,CAAC,KAAK,EACZ,MAAM,EACN,QAAQ,EACR,cAAc,CACd,CAAC;QAEF,yEAAyE;QACzE,MAAM,MAAM,GAAG,IAAI,OAAO,CACzB,IAAI,CAAC,KAAK,EACV,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,OAAO,EACf,YAAY,EACZ,OAAO,CAAC,mBAAmB,EAC3B,OAAO,CAAC,WAAW,CACnB,CAAC;QAEF,GAAG,CAAC,0BAA0B,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC,CAAC,2BAA2B;AACzC,CAAC"}

package/dist/src/planner/rules/cache/rule-materialization-advisory.d.ts

@@ -1,8 +1,15 @@
 /**
  * Rule: Materialization Advisory
  *
- * Transforms: Any relational node → CacheNode (when beneficial)
- * Conditions: Node would benefit from caching based on reference analysis
+ * Required Characteristics:
+ * - Node must be non-relational with relational children
+ * - Children must be cacheable based on reference analysis
+ * - Children must benefit from materialization
+ *
+ * Applied When:
+ * - Transition from non-relational to relational subtrees
+ * - Relational subtrees would benefit from caching
+ *
  * Benefits: Reduces redundant computation for repeated scans and loop contexts
  */
 import type { PlanNode } from '../../nodes/plan-node.js';

package/dist/src/planner/rules/cache/rule-materialization-advisory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-materialization-advisory.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-materialization-advisory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAK7D,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAsDhG"}
+{"version":3,"file":"rule-materialization-advisory.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-materialization-advisory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAM7D,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAqDhG"}

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

@@ -1,19 +1,26 @@
 /**
  * Rule: Materialization Advisory
  *
- * Transforms: Any relational node → CacheNode (when beneficial)
- * Conditions: Node would benefit from caching based on reference analysis
+ * Required Characteristics:
+ * - Node must be non-relational with relational children
+ * - Children must be cacheable based on reference analysis
+ * - Children must benefit from materialization
+ *
+ * Applied When:
+ * - Transition from non-relational to relational subtrees
+ * - Relational subtrees would benefit from caching
+ *
  * Benefits: Reduces redundant computation for repeated scans and loop contexts
  */
 import { createLogger } from '../../../common/logger.js';
 import { MaterializationAdvisory } from '../../cache/materialization-advisory.js';
+import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
 const log = createLogger('optimizer:rule:materialization-advisory');
 export function ruleMaterializationAdvisory(node, context) {
     // Apply this rule when we're at a non-relational node that has relational children
     // This captures transitions into relational subtrees (queries, subqueries, CTEs, etc.)
-    // Check if this is a non-relational node
-    const nodeType = node.getType();
-    if (nodeType.typeClass === 'relation') {
+    // Check if this is a non-relational node using characteristics
+    if (PlanNodeCharacteristics.isRelational(node)) {
         // This is already a relational node, don't apply here
         return null;
     }
@@ -23,7 +30,7 @@ export function ruleMaterializationAdvisory(node, context) {
         // No relational children, nothing to analyze
         return null;
     }
-    log('Applying materialization advisory at transition from %s to relational children', node.nodeType);
+    log('Applying materialization advisory at transition from %s to relational children', node.getType().typeClass);
     try {
         // Create advisory with current tuning parameters
         const advisory = new MaterializationAdvisory(context.tuning);
@@ -34,7 +41,7 @@ export function ruleMaterializationAdvisory(node, context) {
             const transformedRelation = advisory.analyzeAndTransform(relation);
             if (transformedRelation !== relation) {
                 anyTransformed = true;
-                log('Transformed relational subtree under %s', node.nodeType);
+                log('Transformed relational subtree under %s node', node.getType().typeClass);
             }
         }
         // If any relational children were transformed, we need to return a transformed node

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

@@ -1 +1 @@
-{"version":3,"file":"rule-materialization-advisory.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-materialization-advisory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAElF,MAAM,GAAG,GAAG,YAAY,CAAC,yCAAyC,CAAC,CAAC;AAEpE,MAAM,UAAU,2BAA2B,CAAC,IAAc,EAAE,OAAmB;IAC9E,mFAAmF;IACnF,uFAAuF;IAEvF,yCAAyC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAChC,IAAI,QAAQ,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QACvC,sDAAsD;QACtD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IACtC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,6CAA6C;QAC7C,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,gFAAgF,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAErG,IAAI,CAAC;QACJ,iDAAiD;QACjD,MAAM,QAAQ,GAAG,IAAI,uBAAuB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE7D,uEAAuE;QACvE,IAAI,cAAc,GAAG,KAAK,CAAC;QAE3B,sEAAsE;QACtE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,mBAAmB,GAAG,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YACnE,IAAI,mBAAmB,KAAK,QAAQ,EAAE,CAAC;gBACtC,cAAc,GAAG,IAAI,CAAC;gBACtB,GAAG,CAAC,yCAAyC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/D,CAAC;QACF,CAAC;QAED,oFAAoF;QACpF,0FAA0F;QAC1F,8EAA8E;QAC9E,IAAI,cAAc,EAAE,CAAC;YACpB,iDAAiD;YACjD,MAAM,aAAa,GAAG,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YACzD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO,aAAa,CAAC;YACtB,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAC;IAEb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,GAAG,CAAC,uCAAuC,EAAE,KAAK,CAAC,CAAC;QACpD,8CAA8C;QAC9C,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC"}
+{"version":3,"file":"rule-materialization-advisory.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-materialization-advisory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,MAAM,GAAG,GAAG,YAAY,CAAC,yCAAyC,CAAC,CAAC;AAEpE,MAAM,UAAU,2BAA2B,CAAC,IAAc,EAAE,OAAmB;IAC9E,mFAAmF;IACnF,uFAAuF;IAEvF,+DAA+D;IAC/D,IAAI,uBAAuB,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,sDAAsD;QACtD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IACtC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,6CAA6C;QAC7C,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,gFAAgF,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IAEhH,IAAI,CAAC;QACJ,iDAAiD;QACjD,MAAM,QAAQ,GAAG,IAAI,uBAAuB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE7D,uEAAuE;QACvE,IAAI,cAAc,GAAG,KAAK,CAAC;QAE3B,sEAAsE;QACtE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,mBAAmB,GAAG,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YACnE,IAAI,mBAAmB,KAAK,QAAQ,EAAE,CAAC;gBACtC,cAAc,GAAG,IAAI,CAAC;gBACtB,GAAG,CAAC,8CAA8C,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;YAC/E,CAAC;QACF,CAAC;QAED,oFAAoF;QACpF,0FAA0F;QAC1F,8EAA8E;QAC9E,IAAI,cAAc,EAAE,CAAC;YACpB,iDAAiD;YACjD,MAAM,aAAa,GAAG,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YACzD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO,aAAa,CAAC;YACtB,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAC;IAEb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,GAAG,CAAC,uCAAuC,EAAE,KAAK,CAAC,CAAC;QACpD,8CAA8C;QAC9C,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC"}

package/dist/src/planner/rules/cache/rule-mutating-subquery-cache.d.ts

@@ -1,11 +1,17 @@
 /**
  * Rule: Mutating Subquery Cache Injection
  *
- * Transforms: JoinNode with mutating right side → JoinNode with cached right side
- * Conditions: Right side contains operations with readonly=false physical property
+ * Required Characteristics:
+ * - Node must be a join operation (JoinCapable interface)
+ * - Right side must contain operations with side effects (readonly=false)
+ * - Right side must not already be cached
+ *
+ * Applied When:
+ * - Join has mutating operations on right side that could be executed multiple times
+ *
  * Benefits: Prevents mutating subqueries from being executed multiple times in nested loop joins
  */
 import { PlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
-export declare function ruleMutatingSubqueryCache(node: PlanNode, context: OptContext): PlanNode | null;
+export declare function ruleMutatingSubqueryCache(node: PlanNode, _context: OptContext): PlanNode | null;
 //# sourceMappingURL=rule-mutating-subquery-cache.d.ts.map

package/dist/src/planner/rules/cache/rule-mutating-subquery-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-mutating-subquery-cache.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-mutating-subquery-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAoD9F"}
+{"version":3,"file":"rule-mutating-subquery-cache.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-mutating-subquery-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAqD/F"}

package/dist/src/planner/rules/cache/rule-mutating-subquery-cache.js

@@ -1,79 +1,76 @@
 /**
  * Rule: Mutating Subquery Cache Injection
  *
- * Transforms: JoinNode with mutating right side → JoinNode with cached right side
- * Conditions: Right side contains operations with readonly=false physical property
+ * Required Characteristics:
+ * - Node must be a join operation (JoinCapable interface)
+ * - Right side must contain operations with side effects (readonly=false)
+ * - Right side must not already be cached
+ *
+ * Applied When:
+ * - Join has mutating operations on right side that could be executed multiple times
+ *
  * Benefits: Prevents mutating subqueries from being executed multiple times in nested loop joins
  */
 import { createLogger } from '../../../common/logger.js';
-import { PlanNode } from '../../nodes/plan-node.js';
-import { JoinNode } from '../../nodes/join-node.js';
 import { CacheNode } from '../../nodes/cache-node.js';
-import { PlanNodeType } from '../../nodes/plan-node-type.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { PlanNodeCharacteristics, CapabilityDetectors, CachingAnalysis } from '../../framework/characteristics.js';
 const log = createLogger('optimizer:rule:mutating-subquery-cache');
-export function ruleMutatingSubqueryCache(node, context) {
-    // Guard: only apply to JoinNode
-    if (!(node instanceof JoinNode)) {
+export function ruleMutatingSubqueryCache(node, _context) {
+    // Guard: node must support join operations
+    if (!CapabilityDetectors.isJoin(node)) {
         return null;
     }
-    log('Checking JoinNode for operations with side effects on right side');
-    // Check if the right side contains operations with side effects
-    const rightSide = node.right;
+    log('Checking join operation for side effects on right side');
+    // Get join-specific characteristics
+    const joinNode = node;
+    const rightSide = joinNode.getRightSource();
+    // Check if right side contains operations with side effects
     const hasSideEffects = containsOperationsWithSideEffects(rightSide);
     if (!hasSideEffects) {
         log('Right side does not contain operations with side effects, skipping');
         return null;
     }
     // Check if right side is already cached
-    if (rightSide.nodeType === PlanNodeType.Cache) {
+    if (CapabilityDetectors.isCached(rightSide) && rightSide.isCached()) {
         log('Right side is already cached, skipping');
         return null;
     }
     log('Detected operations with side effects on right side of join, injecting cache');
-    // Calculate appropriate cache threshold
-    const estimatedRows = rightSide.estimatedRows ?? context.tuning.defaultRowEstimate;
-    const threshold = Math.min(Math.max(estimatedRows * context.tuning.join.cacheThresholdMultiplier, 1000), context.tuning.join.maxCacheThreshold);
+    // Calculate appropriate cache threshold using characteristics
+    const threshold = CachingAnalysis.getCacheThreshold(rightSide);
     // Wrap the right side with a cache node
     const cachedRightSide = new CacheNode(rightSide.scope, rightSide, 'memory', threshold);
     // Create new join node with cached right side
-    const result = new JoinNode(node.scope, node.left, // Left side unchanged
-    cachedRightSide, // Right side now cached
-    node.joinType, node.condition, node.usingColumns);
+    // Note: We still need to use specific constructor since we don't have a generic join builder yet
+    const result = new JoinNode(node.scope, joinNode.getLeftSource(), cachedRightSide, joinNode.getJoinType(), joinNode.getJoinCondition(), 
+    // Special case: for JOINs, we also need to check if any of the join conditions
+    // reference columns from the mutating subquery (via USING clause)
+    joinNode.getUsingColumns());
     log('Successfully injected cache for operations with side effects (threshold: %d)', threshold);
     return result;
 }
 /**
  * Recursively check if a plan tree contains operations with side effects
+ * Uses characteristics-based analysis instead of hard-coded node type checks
  */
 function containsOperationsWithSideEffects(node) {
-    // Check if this node has side effects using physical properties
-    if (hasNodeSideEffects(node)) {
+    // Check this node's characteristics
+    if (PlanNodeCharacteristics.hasSideEffects(node)) {
         return true;
     }
-    // Recursively check children
+    // Recursively check all children
     for (const child of node.getChildren()) {
         if (containsOperationsWithSideEffects(child)) {
             return true;
         }
     }
-    // Check relational children if available
-    if ('getRelations' in node) {
-        for (const relation of node.getRelations()) {
-            if (containsOperationsWithSideEffects(relation)) {
-                return true;
-            }
+    // Check relational children if available (preserved for compatibility)
+    for (const relation of node.getRelations()) {
+        if (containsOperationsWithSideEffects(relation)) {
+            return true;
         }
     }
     return false;
 }
-/**
- * Check if a node has side effects using physical properties
- */
-function hasNodeSideEffects(node) {
-    // By the time rules run, all children should have physical properties set by the framework
-    if (!node.physical) {
-        throw new Error(`Internal error: Node ${node.nodeType}:${node.id} missing physical properties during rule application`);
-    }
-    return PlanNode.hasSideEffects(node.physical);
-}
 //# sourceMappingURL=rule-mutating-subquery-cache.js.map

package/dist/src/planner/rules/cache/rule-mutating-subquery-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-mutating-subquery-cache.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-mutating-subquery-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rule-mutating-subquery-cache.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-mutating-subquery-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,eAAe,EAAoB,MAAM,oCAAoC,CAAC;AAErI,MAAM,GAAG,GAAG,YAAY,CAAC,wCAAwC,CAAC,CAAC;AAEnE,MAAM,UAAU,yBAAyB,CAAC,IAAc,EAAE,QAAoB;IAC7E,2CAA2C;IAC3C,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,wDAAwD,CAAC,CAAC;IAE9D,oCAAoC;IACpC,MAAM,QAAQ,GAAG,IAAmB,CAAC;IACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC;IAE5C,4DAA4D;IAC5D,MAAM,cAAc,GAAG,iCAAiC,CAAC,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,cAAc,EAAE,CAAC;QACrB,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACb,CAAC;IAED,wCAAwC;IACxC,IAAI,mBAAmB,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC;QACrE,GAAG,CAAC,wCAAwC,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,8EAA8E,CAAC,CAAC;IAEpF,8DAA8D;IAC9D,MAAM,SAAS,GAAG,eAAe,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAE/D,wCAAwC;IACxC,MAAM,eAAe,GAAG,IAAI,SAAS,CACpC,SAAS,CAAC,KAAK,EACf,SAAS,EACT,QAAQ,EACR,SAAS,CACT,CAAC;IAEF,8CAA8C;IAC9C,iGAAiG;IACjG,MAAM,MAAM,GAAG,IAAI,QAAQ,CAC1B,IAAI,CAAC,KAAK,EACV,QAAQ,CAAC,aAAa,EAAE,EACxB,eAAe,EACf,QAAQ,CAAC,WAAW,EAAE,EACtB,QAAQ,CAAC,gBAAgB,EAAE;IAC3B,+EAA+E;IAC/E,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,CAC1B,CAAC;IAEF,GAAG,CAAC,8EAA8E,EAAE,SAAS,CAAC,CAAC;IAC/F,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,iCAAiC,CAAC,IAAc;IACxD,oCAAoC;IACpC,IAAI,uBAAuB,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,iCAAiC;IACjC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACxC,IAAI,iCAAiC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,uEAAuE;IACvE,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QAC5C,IAAI,iCAAiC,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,14 @@
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+/**
+ * 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 declare function ruleJoinGreedyCommute(node: PlanNode, _context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-join-greedy-commute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rule-join-greedy-commute.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/rule-join-greedy-commute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAK7D;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CA4B3F"}