@quereus/quereus 0.1.0

package/dist/src/planner/building/update.js

@@ -0,0 +1,152 @@
+import { UpdateNode } from '../nodes/update-node.js';
+import { DmlExecutorNode } from '../nodes/dml-executor-node.js';
+import { buildTableReference, buildTableScan } from './table.js';
+import { buildExpression } from './expression.js';
+import { PlanNode } from '../nodes/plan-node.js';
+import { FilterNode } from '../nodes/filter.js';
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+import { RegisteredScope } from '../scopes/registered.js';
+import { ColumnReferenceNode } from '../nodes/reference.js';
+import { SinkNode } from '../nodes/sink-node.js';
+import { ConstraintCheckNode } from '../nodes/constraint-check-node.js';
+import { RowOp } from '../../schema/table.js';
+import { ReturningNode } from '../nodes/returning-node.js';
+import { buildOldNewRowDescriptors } from '../../util/row-descriptor.js';
+export function buildUpdateStmt(ctx, stmt) {
+    const tableReference = buildTableReference({ type: 'table', table: stmt.table }, ctx);
+    // Plan the source of rows to update. This is typically the table itself, potentially filtered.
+    let sourceNode = buildTableScan({ type: 'table', table: stmt.table }, ctx);
+    // Create a new scope with the table columns registered for column resolution
+    const tableScope = new RegisteredScope(ctx.scope);
+    const sourceAttributes = sourceNode.getAttributes();
+    sourceNode.getType().columns.forEach((c, i) => {
+        const attr = sourceAttributes[i];
+        tableScope.registerSymbol(c.name.toLowerCase(), (exp, s) => new ColumnReferenceNode(s, exp, c.type, attr.id, i));
+    });
+    // Create a new planning context with the updated scope for WHERE clause resolution
+    const updateCtx = { ...ctx, scope: tableScope };
+    if (stmt.where) {
+        const filterExpression = buildExpression(updateCtx, stmt.where);
+        sourceNode = new FilterNode(updateCtx.scope, sourceNode, filterExpression);
+    }
+    const assignments = stmt.assignments.map(assign => {
+        // TODO: Validate assign.column against tableReference.tableSchema
+        const targetColumn = { type: 'column', name: assign.column, table: stmt.table.name, schema: stmt.table.schema };
+        return {
+            targetColumn, // Keep as AST for now, emitter can resolve index
+            value: buildExpression(updateCtx, assign.value),
+        };
+    });
+    // Create OLD/NEW attributes for UPDATE (used for both RETURNING and non-RETURNING paths)
+    const oldAttributes = tableReference.tableSchema.columns.map((col) => ({
+        id: PlanNode.nextAttrId(),
+        name: col.name,
+        type: {
+            typeClass: 'scalar',
+            affinity: col.affinity,
+            nullable: !col.notNull,
+            isReadOnly: false
+        },
+        sourceRelation: `OLD.${tableReference.tableSchema.name}`
+    }));
+    const newAttributes = tableReference.tableSchema.columns.map((col) => ({
+        id: PlanNode.nextAttrId(),
+        name: col.name,
+        type: {
+            typeClass: 'scalar',
+            affinity: col.affinity,
+            nullable: !col.notNull,
+            isReadOnly: false
+        },
+        sourceRelation: `NEW.${tableReference.tableSchema.name}`
+    }));
+    const { oldRowDescriptor, newRowDescriptor, flatRowDescriptor } = buildOldNewRowDescriptors(oldAttributes, newAttributes);
+    if (stmt.returning && stmt.returning.length > 0) {
+        // For RETURNING, create coordinated attribute IDs like we do for INSERT
+        const returningScope = new RegisteredScope(updateCtx.scope);
+        // Create consistent attribute IDs for all table columns (both NEW and OLD)
+        const newColumnAttributeIds = [];
+        const oldColumnAttributeIds = [];
+        newAttributes.forEach((attr, columnIndex) => {
+            newColumnAttributeIds[columnIndex] = attr.id;
+        });
+        oldAttributes.forEach((attr, columnIndex) => {
+            oldColumnAttributeIds[columnIndex] = attr.id;
+        });
+        tableReference.tableSchema.columns.forEach((tableColumn, columnIndex) => {
+            const newAttributeId = newAttributes[columnIndex].id;
+            const oldAttributeId = oldAttributes[columnIndex].id;
+            // Register the unqualified column name in the RETURNING scope (defaults to NEW values)
+            returningScope.registerSymbol(tableColumn.name.toLowerCase(), (exp, s) => {
+                return new ColumnReferenceNode(s, exp, {
+                    typeClass: 'scalar',
+                    affinity: tableColumn.affinity,
+                    nullable: !tableColumn.notNull,
+                    isReadOnly: false
+                }, newAttributeId, columnIndex);
+            });
+            // Also register the table-qualified form (table.column) - defaults to NEW values
+            const tblQualified = `${tableReference.tableSchema.name.toLowerCase()}.${tableColumn.name.toLowerCase()}`;
+            returningScope.registerSymbol(tblQualified, (exp, s) => new ColumnReferenceNode(s, exp, {
+                typeClass: 'scalar',
+                affinity: tableColumn.affinity,
+                nullable: !tableColumn.notNull,
+                isReadOnly: false
+            }, newAttributeId, columnIndex));
+            // Register NEW.column for UPDATE RETURNING (updated values)
+            returningScope.registerSymbol(`new.${tableColumn.name.toLowerCase()}`, (exp, s) => new ColumnReferenceNode(s, exp, {
+                typeClass: 'scalar',
+                affinity: tableColumn.affinity,
+                nullable: !tableColumn.notNull,
+                isReadOnly: false
+            }, newAttributeId, columnIndex));
+            // Register OLD.column for UPDATE RETURNING (original values)
+            returningScope.registerSymbol(`old.${tableColumn.name.toLowerCase()}`, (exp, s) => new ColumnReferenceNode(s, exp, {
+                typeClass: 'scalar',
+                affinity: tableColumn.affinity,
+                nullable: !tableColumn.notNull,
+                isReadOnly: false
+            }, oldAttributeId, columnIndex));
+        });
+        const returningProjections = stmt.returning.map(rc => {
+            // TODO: Support RETURNING *
+            if (rc.type === 'all')
+                throw new QuereusError('RETURNING * not yet supported', StatusCode.UNSUPPORTED);
+            // Infer alias from column name if not explicitly provided
+            let alias = rc.alias;
+            if (!alias && rc.expr.type === 'column') {
+                // For qualified column references like NEW.id or OLD.id, normalize to lowercase
+                if (rc.expr.table) {
+                    alias = `${rc.expr.table.toLowerCase()}.${rc.expr.name.toLowerCase()}`;
+                }
+                else {
+                    alias = rc.expr.name.toLowerCase();
+                }
+            }
+            const columnIndex = tableReference.tableSchema.columns.findIndex(col => col.name.toLowerCase() === (rc.expr.type === 'column' ? rc.expr.name.toLowerCase() : ''));
+            const projAttributeId = rc.expr.type === 'column' && columnIndex !== -1 ? newColumnAttributeIds[columnIndex] : undefined;
+            return {
+                node: buildExpression({ ...updateCtx, scope: returningScope }, rc.expr),
+                alias: alias,
+                attributeId: projAttributeId
+            };
+        });
+        // Create UpdateNode with both row descriptors for RETURNING coordination
+        const updateNodeWithDescriptor = new UpdateNode(updateCtx.scope, tableReference, assignments, sourceNode, stmt.onConflict, oldRowDescriptor, newRowDescriptor, flatRowDescriptor);
+        // For returning, we still need to execute the update before projecting
+        // Always inject ConstraintCheckNode for UPDATE operations (provides required metadata)
+        const constraintCheckNode = new ConstraintCheckNode(updateCtx.scope, updateNodeWithDescriptor, tableReference, RowOp.UPDATE, oldRowDescriptor, newRowDescriptor);
+        const updateExecutorNode = new DmlExecutorNode(updateCtx.scope, constraintCheckNode, tableReference, 'update');
+        // Return the RETURNING results from the executed update
+        return new ReturningNode(updateCtx.scope, updateExecutorNode, returningProjections);
+    }
+    // Step 1: Create UpdateNode that produces updated rows (but doesn't execute them)
+    // Create newRowDescriptor and oldRowDescriptor for constraint checking with NEW/OLD references
+    const updateNode = new UpdateNode(updateCtx.scope, tableReference, assignments, sourceNode, stmt.onConflict, oldRowDescriptor, newRowDescriptor, flatRowDescriptor);
+    // Step 2: inject constraint checking AFTER update row generation
+    const constraintCheckNode = new ConstraintCheckNode(updateCtx.scope, updateNode, tableReference, RowOp.UPDATE, oldRowDescriptor, newRowDescriptor);
+    const updateExecutorNode = new DmlExecutorNode(updateCtx.scope, constraintCheckNode, tableReference, 'update');
+    return new SinkNode(updateCtx.scope, updateExecutorNode, 'update');
+}
+//# sourceMappingURL=update.js.map

package/dist/src/planner/building/update.js.map

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

package/dist/src/planner/building/with.d.ts

@@ -0,0 +1,13 @@
+import type * as AST from '../../parser/ast.js';
+import type { PlanningContext } from '../planning-context.js';
+import { type CTEPlanNode } from '../nodes/cte-node.js';
+/**
+ * Builds plan nodes for Common Table Expressions (CTEs) within a WITH clause.
+ * Returns a map of CTE names to their corresponding CTENode instances.
+ */
+export declare function buildWithClause(ctx: PlanningContext, withClause: AST.WithClause): Map<string, CTEPlanNode>;
+/**
+ * Builds a plan node for a single Common Table Expression.
+ */
+export declare function buildCommonTableExpr(ctx: PlanningContext, cte: AST.CommonTableExpr, isRecursive: boolean, existingCTEs: Map<string, CTEPlanNode>, options?: AST.WithClauseOptions): CTEPlanNode;
+//# sourceMappingURL=with.d.ts.map

package/dist/src/planner/building/with.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with.d.ts","sourceRoot":"","sources":["../../../../src/planner/building/with.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AASjE;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,GAAG,CAAC,UAAU,GACxB,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAwB1B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,GAAG,CAAC,eAAe,EACxB,WAAW,EAAE,OAAO,EACpB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EACtC,OAAO,CAAC,EAAE,GAAG,CAAC,iBAAiB,GAC7B,WAAW,CAqDb"}

package/dist/src/planner/building/with.js

@@ -0,0 +1,112 @@
+import { CTENode } from '../nodes/cte-node.js';
+import { RecursiveCTENode } from '../nodes/recursive-cte-node.js';
+import { buildSelectStmt } from './select.js';
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+import { RegisteredScope } from '../scopes/registered.js';
+import { ColumnReferenceNode } from '../nodes/reference.js';
+/**
+ * Builds plan nodes for Common Table Expressions (CTEs) within a WITH clause.
+ * Returns a map of CTE names to their corresponding CTENode instances.
+ */
+export function buildWithClause(ctx, withClause) {
+    const cteNodes = new Map();
+    // Check for duplicate CTE names
+    const cteNames = new Set();
+    for (const cte of withClause.ctes) {
+        const cteName = cte.name.toLowerCase();
+        if (cteNames.has(cteName)) {
+            throw new QuereusError(`Duplicate CTE name '${cte.name}' in WITH clause`, StatusCode.ERROR);
+        }
+        cteNames.add(cteName);
+    }
+    // Build each CTE in order
+    // Note: For recursive CTEs, we may need to handle forward references
+    for (const cte of withClause.ctes) {
+        const cteNode = buildCommonTableExpr(ctx, cte, withClause.recursive, cteNodes, withClause.options);
+        cteNodes.set(cte.name.toLowerCase(), cteNode);
+    }
+    return cteNodes;
+}
+/**
+ * Builds a plan node for a single Common Table Expression.
+ */
+export function buildCommonTableExpr(ctx, cte, isRecursive, existingCTEs, options) {
+    // Create a context that includes previously defined CTEs in scope
+    // This allows later CTEs to reference earlier ones
+    const cteContext = { ...ctx };
+    // Add existing CTEs to the scope for forward references
+    const cteScope = new RegisteredScope(ctx.scope);
+    for (const [cteName, cteNode] of existingCTEs) {
+        const attributes = cteNode.getAttributes();
+        cteNode.getType().columns.forEach((col, i) => {
+            const attr = attributes[i];
+            // Register CTE columns with qualified names only to avoid conflicts with table columns
+            const qualifiedColumnName = `${cteName}.${col.name.toLowerCase()}`;
+            cteScope.registerSymbol(qualifiedColumnName, (exp, s) => new ColumnReferenceNode(s, exp, col.type, attr.id, i));
+        });
+    }
+    cteContext.scope = cteScope;
+    // Check if this is a recursive CTE with UNION structure
+    if (isRecursive && cte.query.type === 'select' && cte.query.compound) {
+        return buildRecursiveCTE(cteContext, cte, options);
+    }
+    // For non-recursive CTEs or recursive CTEs without UNION structure
+    let query;
+    if (cte.query.type === 'select') {
+        query = buildSelectStmt(cteContext, cte.query);
+    }
+    else {
+        // CTE can also be INSERT, UPDATE, or DELETE statements
+        throw new QuereusError('Non-SELECT CTEs are not yet supported', StatusCode.UNSUPPORTED);
+    }
+    // Determine materialization strategy
+    let materializationHint = cte.materializationHint;
+    if (!materializationHint) {
+        // Default strategy: materialize if CTE is likely to be reused
+        // For now, we'll default to not materialized for simplicity
+        materializationHint = 'not_materialized';
+    }
+    return new CTENode(ctx.scope, cte.name, cte.columns, query, materializationHint, isRecursive);
+}
+/**
+ * Builds a recursive CTE node from a CTE with UNION structure.
+ */
+function buildRecursiveCTE(ctx, cte, options) {
+    const selectStmt = cte.query;
+    // Validate recursive CTE structure - check for compound operation
+    if (!selectStmt.compound) {
+        throw new QuereusError(`Recursive CTE '${cte.name}' must use UNION or UNION ALL`, StatusCode.ERROR);
+    }
+    // Extract base case (the main SELECT) and recursive case (the compound part)
+    const baseCaseStmt = {
+        ...selectStmt,
+        compound: undefined
+    };
+    const recursiveCaseStmt = selectStmt.compound.select;
+    const isUnionAll = selectStmt.compound.op === 'unionAll';
+    // Build the base case query (without CTE self-reference)
+    const baseCaseQuery = buildSelectStmt(ctx, baseCaseStmt);
+    // Determine materialization strategy (recursive CTEs should typically be materialized)
+    const materializationHint = cte.materializationHint || 'materialized';
+    // Create the final recursive CTE node first (so we have the tableDescriptor)
+    const recursiveCTENode = new RecursiveCTENode(ctx.scope, cte.name, cte.columns, baseCaseQuery, baseCaseQuery, // Temporary - will be replaced with actual recursive case
+    isUnionAll, materializationHint, options?.maxRecursion);
+    // For the recursive case, we need to create a special context where the CTE name
+    // references the working table (this will be handled at runtime)
+    const recursiveContext = { ...ctx };
+    // Create a temporary CTE reference for the recursive case that shares the same tableDescriptor
+    const tempCteNode = new CTENode(ctx.scope, cte.name, cte.columns, baseCaseQuery, // Use base case as template
+    'materialized', true);
+    // Share the same tableDescriptor for runtime coordination
+    tempCteNode.tableDescriptor = recursiveCTENode.tableDescriptor;
+    // Create a map containing the recursive CTE reference
+    const recursiveCteMap = new Map();
+    recursiveCteMap.set(cte.name.toLowerCase(), tempCteNode);
+    // Build the recursive case query with the CTE map so it can find the table reference
+    const recursiveCaseQuery = buildSelectStmt(recursiveContext, recursiveCaseStmt, recursiveCteMap);
+    // Now update the recursive CTE node with the actual recursive case query
+    recursiveCTENode.setRecursiveCaseQuery(recursiveCaseQuery);
+    return recursiveCTENode;
+}
+//# sourceMappingURL=with.js.map

package/dist/src/planner/building/with.js.map

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

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

@@ -0,0 +1,66 @@
+/**
+ * Materialization advisory framework
+ * Decides when and how to inject caching based on reference graph analysis
+ */
+import type { PlanNode } from '../nodes/plan-node.js';
+import { type CacheStrategy } from '../nodes/cache-node.js';
+import type { OptimizerTuning } from '../optimizer-tuning.js';
+/**
+ * Cache recommendation for a specific node
+ */
+export interface CacheRecommendation {
+    /** Whether to inject caching for this node */
+    shouldCache: boolean;
+    /** Recommended cache strategy */
+    strategy: CacheStrategy;
+    /** Recommended cache threshold */
+    threshold: number;
+    /** Reason for the recommendation (for debugging) */
+    reason: string;
+}
+/**
+ * Materialization advisory that analyzes plan trees and recommends caching
+ */
+export declare class MaterializationAdvisory {
+    private tuning;
+    private referenceBuilder;
+    constructor(tuning: OptimizerTuning);
+    /**
+     * Analyze a plan tree and return caching recommendations
+     */
+    analyzeTree(root: PlanNode): Map<PlanNode, CacheRecommendation>;
+    /**
+     * Apply caching recommendations to a plan tree
+     */
+    applyCaching(root: PlanNode, recommendations: Map<PlanNode, CacheRecommendation>): PlanNode;
+    /**
+     * Core advisory algorithm
+     */
+    private adviseCaching;
+    /**
+ * Select appropriate cache strategy based on estimated size
+ */
+    private selectStrategy;
+    /**
+     * Calculate appropriate cache threshold
+     */
+    private calculateThreshold;
+    /**
+     * Check if a node is relational (can be cached)
+     */
+    private isRelationalNode;
+    /**
+     * Transform a node tree by applying cache recommendations
+     */
+    private transformNode;
+    /**
+     * Transform children of a node
+     */
+    private transformChildren;
+    /**
+     * Recreate a node with new relational children
+     * This is a simplified version - in practice, would need comprehensive node cloning
+     */
+    private recreateNodeWithNewRelations;
+}
+//# sourceMappingURL=materialization-advisory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"materialization-advisory.d.ts","sourceRoot":"","sources":["../../../../src/planner/cache/materialization-advisory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAsB,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB,iCAAiC;IACjC,QAAQ,EAAE,aAAa,CAAC;IACxB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAGvB,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,gBAAgB,CAAwB;gBAE5B,MAAM,EAAE,eAAe;IAI3C;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAqB/D;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,CAAC,QAAQ,EAAE,mBAAmB,CAAC,GAAG,QAAQ;IAI3F;;OAEG;IACH,OAAO,CAAC,aAAa;IA4EpB;;GAEE;IACH,OAAO,CAAC,cAAc;IAStB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;OAGG;IACH,OAAO,CAAC,4BAA4B;CASpC"}

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

@@ -0,0 +1,187 @@
+/**
+ * Materialization advisory framework
+ * Decides when and how to inject caching based on reference graph analysis
+ */
+import { createLogger } from '../../common/logger.js';
+import { CacheNode } from '../nodes/cache-node.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { ReferenceGraphBuilder } from './reference-graph.js';
+const log = createLogger('optimizer:cache:materialization');
+/**
+ * Materialization advisory that analyzes plan trees and recommends caching
+ */
+export class MaterializationAdvisory {
+    tuning;
+    referenceBuilder;
+    constructor(tuning) {
+        this.tuning = tuning;
+        this.referenceBuilder = new ReferenceGraphBuilder(tuning);
+    }
+    /**
+     * Analyze a plan tree and return caching recommendations
+     */
+    analyzeTree(root) {
+        const refGraph = this.referenceBuilder.buildReferenceGraph(root);
+        const recommendations = new Map();
+        for (const [node, stats] of refGraph) {
+            // Only consider relational nodes for caching
+            if (!this.isRelationalNode(node)) {
+                continue;
+            }
+            const recommendation = this.adviseCaching(node, stats);
+            recommendations.set(node, recommendation);
+            if (recommendation.shouldCache) {
+                log('Recommending cache for %s: %s', node.nodeType, recommendation.reason);
+            }
+        }
+        return recommendations;
+    }
+    /**
+     * Apply caching recommendations to a plan tree
+     */
+    applyCaching(root, recommendations) {
+        return this.transformNode(root, recommendations);
+    }
+    /**
+     * Core advisory algorithm
+     */
+    adviseCaching(node, stats) {
+        // Rule 1: Non-deterministic nodes should not be cached
+        if (!stats.deterministic) {
+            return {
+                shouldCache: false,
+                strategy: 'memory',
+                threshold: 0,
+                reason: 'Non-deterministic node'
+            };
+        }
+        // Rule 2: Nodes that are already cached don't need additional caching
+        if (node.nodeType === PlanNodeType.Cache) {
+            return {
+                shouldCache: false,
+                strategy: 'memory',
+                threshold: 0,
+                reason: 'Already cached'
+            };
+        }
+        // Rule 3: Single-parent nodes that don't appear in loops typically don't benefit from caching
+        if (stats.parentCount <= 1 && !stats.appearsInLoop) {
+            return {
+                shouldCache: false,
+                strategy: 'memory',
+                threshold: 0,
+                reason: 'Single parent, not in loop'
+            };
+        }
+        // Rule 4: 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: `Multiple parents (${stats.parentCount})`
+            };
+        }
+        // Rule 5: 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)`
+                };
+            }
+            const strategy = this.selectStrategy(stats.estimatedRows);
+            const threshold = this.calculateThreshold(stats.estimatedRows, strategy);
+            return {
+                shouldCache: true,
+                strategy,
+                threshold,
+                reason: 'Appears in loop context'
+            };
+        }
+        // Default: no caching
+        return {
+            shouldCache: false,
+            strategy: 'memory',
+            threshold: 0,
+            reason: 'No caching criteria met'
+        };
+    }
+    /**
+ * Select appropriate cache strategy based on estimated size
+ */
+    selectStrategy(estimatedRows) {
+        // Use tuning configuration for strategy selection
+        if (this.tuning.cache.spillEnabled && estimatedRows > this.tuning.cache.spillThreshold) {
+            return 'spill';
+        }
+        return 'memory';
+    }
+    /**
+     * Calculate appropriate cache threshold
+     */
+    calculateThreshold(estimatedRows, strategy) {
+        const multiplier = this.tuning.join.cacheThresholdMultiplier;
+        const maxThreshold = strategy === 'spill' ?
+            this.tuning.join.maxCacheThreshold * 2 : // Allow larger thresholds for spill
+            this.tuning.join.maxCacheThreshold;
+        return Math.min(Math.max(estimatedRows * multiplier, 1000), // Minimum threshold
+        maxThreshold);
+    }
+    /**
+     * Check if a node is relational (can be cached)
+     */
+    isRelationalNode(node) {
+        return 'getAttributes' in node && typeof node.getAttributes === 'function';
+    }
+    /**
+     * Transform a node tree by applying cache recommendations
+     */
+    transformNode(node, recommendations) {
+        // First, recursively transform children
+        const transformedNode = this.transformChildren(node, recommendations);
+        // Check if this node should be cached
+        const recommendation = recommendations.get(node);
+        if (recommendation?.shouldCache && this.isRelationalNode(transformedNode)) {
+            log('Injecting %s cache for %s (threshold: %d)', recommendation.strategy, transformedNode.nodeType, recommendation.threshold);
+            return new CacheNode(transformedNode.scope, transformedNode, recommendation.strategy, recommendation.threshold);
+        }
+        return transformedNode;
+    }
+    /**
+     * Transform children of a node
+     */
+    transformChildren(node, recommendations) {
+        // Handle different node types that have children
+        // For nodes with relational children, we need to transform them
+        if ('getRelations' in node) {
+            const relations = node.getRelations();
+            const transformedRelations = relations.map((rel) => this.transformNode(rel, recommendations));
+            // Check if any relations were transformed
+            if (transformedRelations.some((rel, idx) => rel !== relations[idx])) {
+                // Need to create a new node with transformed relations
+                return this.recreateNodeWithNewRelations(node, transformedRelations);
+            }
+        }
+        // If no transformations needed, return original node
+        return node;
+    }
+    /**
+     * Recreate a node with new relational children
+     * This is a simplified version - in practice, would need comprehensive node cloning
+     */
+    recreateNodeWithNewRelations(node, _newRelations) {
+        // TODO: This is a simplified implementation
+        // In practice, would need to handle all node types properly
+        // For now, just return the original node
+        // This would need to be expanded to handle all node types
+        log('Node recreation not yet implemented for %s', node.nodeType);
+        return node;
+    }
+}
+//# sourceMappingURL=materialization-advisory.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,53 @@
+/**
+ * Reference graph builder for materialization advisory
+ * Analyzes plan tree to identify nodes that would benefit from caching
+ */
+import type { PlanNode } from '../nodes/plan-node.js';
+import type { OptimizerTuning } from '../optimizer-tuning.js';
+/**
+ * Statistics about how a node is referenced in the plan tree
+ */
+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;
+}
+/**
+ * Builds a reference graph for materialization decisions
+ */
+export declare class ReferenceGraphBuilder {
+    private tuning;
+    private refMap;
+    private visited;
+    constructor(tuning: OptimizerTuning);
+    /**
+     * Build reference statistics for all nodes in the plan tree
+     */
+    buildReferenceGraph(root: PlanNode): Map<PlanNode, RefStats>;
+    /**
+     * First pass: count how many parents reference each node
+     */
+    private countReferences;
+    /**
+     * Second pass: identify nodes that appear in loop contexts
+     */
+    private identifyLoopContexts;
+    /**
+     * Visit all children of a node
+     */
+    private visitChildren;
+    /**
+     * Get estimated row count for a node
+     */
+    private getEstimatedRows;
+    /**
+     * Determine if a node is deterministic
+     */
+    private isDeterministic;
+}
+//# sourceMappingURL=reference-graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference-graph.d.ts","sourceRoot":"","sources":["../../../../src/planner/cache/reference-graph.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD,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;CACvB;AAED;;GAEG;AACH,qBAAa,qBAAqB;IAIrB,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAuB;gBAElB,MAAM,EAAE,eAAe;IAE3C;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAc5D;;OAEG;IACH,OAAO,CAAC,eAAe;IA4BvB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAwB5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAcrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACH,OAAO,CAAC,eAAe;CA2BvB"}