@quereus/quereus 0.7.2 → 0.7.4

package/src/planner/optimizer-tuning.ts

@@ -1,105 +0,0 @@
-/**
- * Optimizer tuning parameters - centralized configuration for magic numbers
- */
-export interface OptimizerTuning {
-	/** Row estimation defaults */
-	readonly defaultRowEstimate: number;
-
-	/** Maximum optimization depth to prevent infinite recursion */
-	readonly maxOptimizationDepth: number;
-
-	/** Join optimization */
-	readonly join: {
-		/** Minimum left side rows to consider caching right side */
-		readonly minLeftRowsForCaching: number;
-		/** Maximum right side rows to cache */
-		readonly maxRightRowsForCaching: number;
-		/** Cache threshold multiplier (rightSize * multiplier) */
-		readonly cacheThresholdMultiplier: number;
-		/** Maximum cache threshold */
-		readonly maxCacheThreshold: number;
-	};
-
-	/** CTE optimization */
-	readonly cte: {
-		/** Maximum CTE size to consider for caching */
-		readonly maxSizeForCaching: number;
-		/** Cache threshold multiplier for CTEs */
-		readonly cacheThresholdMultiplier: number;
-		/** Maximum cache threshold for CTEs */
-		readonly maxCacheThreshold: number;
-	};
-
-	/** Recursive CTE configuration */
-	readonly recursiveCte: {
-		/** Maximum iterations before recursive CTE is terminated (0 = unlimited) */
-		readonly maxIterations: number;
-		/** Default cache threshold for CTE self-references */
-		readonly defaultCacheThreshold: number;
-	};
-
-	/** Materialization advisory configuration */
-	readonly cache: {
-		/** Row threshold for switching from memory to spill strategy */
-		readonly spillThreshold: number;
-		/** Maximum memory buffer size for spill caches */
-		readonly maxSpillBuffer: number;
-		/** Whether spill caching is enabled */
-		readonly spillEnabled: boolean;
-	};
-
-	/** Development and debugging options */
-	readonly debug: {
-		/** Whether to validate physical plans before emission */
-		readonly validatePlan: boolean;
-	};
-
-	/** QuickPick join enumeration tuning */
-	readonly quickpick?: {
-		/** Maximum number of random greedy tours to evaluate */
-		readonly maxTours: number;
-		/** Time limit in milliseconds for enumeration (soft cap) */
-		readonly timeLimitMs: number;
-		/** Minimum estimated plan cost to trigger enumeration */
-		readonly minTriggerCost: number;
-		/** Enable/disable QuickPick globally */
-		readonly enabled: boolean;
-	};
-}
-
-/**
- * Default optimizer tuning parameters
- */
-export const DEFAULT_TUNING: OptimizerTuning = {
-	defaultRowEstimate: 1000,
-	maxOptimizationDepth: 50,
-	join: {
-		minLeftRowsForCaching: 1,
-		maxRightRowsForCaching: 50000,
-		cacheThresholdMultiplier: 2,
-		maxCacheThreshold: 10000
-	},
-	cte: {
-		maxSizeForCaching: 50000,
-		cacheThresholdMultiplier: 2,
-		maxCacheThreshold: 20000
-	},
-	recursiveCte: {
-		maxIterations: 10000,
-		defaultCacheThreshold: 10000
-	},
-	cache: {
-		spillThreshold: 100000,
-		maxSpillBuffer: 10000,
-		spillEnabled: true
-	},
-	debug: {
-		validatePlan: false // Default to disabled in production
-	},
-	quickpick: {
-		maxTours: 100,
-		timeLimitMs: 100,
-		minTriggerCost: 0,
-		enabled: true
-	}
-};

package/src/planner/optimizer.ts

@@ -1,332 +0,0 @@
-import { createLogger } from '../common/logger.js';
-import { PlanNode } from './nodes/plan-node.js';
-import { PlanNodeType } from './nodes/plan-node-type.js';
-import { OptimizerTuning, DEFAULT_TUNING } from './optimizer-tuning.js';
-
-// Re-export for convenience
-export { DEFAULT_TUNING };
-
-import { applyRules } from './framework/registry.js';
-import { tracePhaseStart, tracePhaseEnd, traceNodeStart, traceNodeEnd } from './framework/trace.js';
-import { defaultStatsProvider, type StatsProvider } from './stats/index.js';
-import { createOptContext, type OptContext } from './framework/context.js';
-import type { OptimizerDiagnostics } from './framework/context.js';
-import { PassManager, PassId } from './framework/pass.js';
-// Phase 2 rules
-import { ruleMaterializationAdvisory } from './rules/cache/rule-materialization-advisory.js';
-// Phase 1.5 rules
-import { ruleSelectAccessPath } from './rules/access/rule-select-access-path.js';
-import { ruleGrowRetrieve } from './rules/retrieve/rule-grow-retrieve.js';
-import { rulePredicatePushdown } from './rules/predicate/rule-predicate-pushdown.js';
-import { ruleJoinKeyInference } from './rules/join/rule-join-key-inference.js';
-import { ruleJoinGreedyCommute } from './rules/join/rule-join-greedy-commute.js';
-// Predicate pushdown rules
-// Core optimization rules
-import { ruleAggregateStreaming } from './rules/aggregate/rule-aggregate-streaming.js';
-import { ruleQuickPickJoinEnumeration } from './rules/join/rule-quickpick-enumeration.js';
-// Constraint rules removed - now handled in builders for correctness
-import { ruleCteOptimization } from './rules/cache/rule-cte-optimization.js';
-import { ruleMutatingSubqueryCache } from './rules/cache/rule-mutating-subquery-cache.js';
-// Phase 3 rules
-import { validatePhysicalTree } from './validation/plan-validator.js';
-import { Database } from '../core/database.js';
-import { performConstantFolding } from './analysis/const-pass.js';
-import { createRuntimeExpressionEvaluator } from './analysis/const-evaluator.js';
-
-const log = createLogger('optimizer');
-
-/**
- * The query optimizer transforms logical plan trees into physical plan trees
- */
-export class Optimizer {
-	private readonly stats: StatsProvider;
-	private readonly passManager: PassManager;
-	private lastDiagnostics: OptimizerDiagnostics | null = null;
-	public tuning: OptimizerTuning;
-
-	constructor(
-		tuning: OptimizerTuning = DEFAULT_TUNING,
-		stats?: StatsProvider
-	) {
-		this.stats = stats ?? defaultStatsProvider;
-		this.passManager = new PassManager();
-		this.tuning = tuning;
-
-		// Register rules to their appropriate passes only (no legacy globals)
-		this.registerRulesToPasses();
-	}
-
-	updateTuning(tuning: OptimizerTuning): void {
-		this.tuning = tuning;
-	}
-
-	private static globalRulesRegistered = false;
-
-	/**
-	 * Legacy method removed; keep empty to avoid duplicate registrations
-	 */
-
-	/**
-	 * Register rules with their appropriate passes
-	 */
-	private registerRulesToPasses(): void {
-		// Structural pass rules (top-down) - for operations that need parent context
-		// Register grow-retrieve for ALL relational node types
-		// The rule itself will determine if growth is possible
-		const relationalNodeTypes = [
-			PlanNodeType.Filter,
-			PlanNodeType.Project,
-			PlanNodeType.Sort,
-			PlanNodeType.LimitOffset,
-			PlanNodeType.Aggregate,
-			PlanNodeType.Distinct,
-			PlanNodeType.Join,
-			PlanNodeType.Window,
-			// Add any other relational node types as needed
-		];
-
-		for (const nodeType of relationalNodeTypes) {
-			this.passManager.addRuleToPass(PassId.Structural, {
-				id: `grow-retrieve-${nodeType}`,
-				nodeType,
-				phase: 'rewrite',
-				fn: ruleGrowRetrieve,
-				priority: 10
-			});
-		}
-
-		// Join key inference (structural/characteristic)
-		this.passManager.addRuleToPass(PassId.Structural, {
-			id: 'join-key-inference',
-			nodeType: PlanNodeType.Join,
-			phase: 'rewrite',
-			fn: ruleJoinKeyInference,
-			priority: 15
-		});
-
-		// Greedy join commute: place smaller input on the left to improve nested-loop-like costs
-		this.passManager.addRuleToPass(PassId.Structural, {
-			id: 'join-greedy-commute',
-			nodeType: PlanNodeType.Join,
-			phase: 'rewrite',
-			fn: ruleJoinGreedyCommute,
-			priority: 16
-		});
-
-		this.passManager.addRuleToPass(PassId.Structural, {
-			id: 'predicate-pushdown',
-			nodeType: PlanNodeType.Filter,
-			phase: 'rewrite',
-			fn: rulePredicatePushdown,
-			priority: 20
-		});
-
-		// Physical pass rules (bottom-up) - for logical to physical transformations
-		this.passManager.addRuleToPass(PassId.Physical, {
-			id: 'select-access-path',
-			nodeType: PlanNodeType.Retrieve,
-			phase: 'impl',
-			fn: ruleSelectAccessPath,
-			priority: 10
-		});
-
-		// QuickPick join enumeration (optional via tuning)
-		this.passManager.addRuleToPass(PassId.Physical, {
-			id: 'quickpick-join-enumeration',
-			nodeType: PlanNodeType.Join,
-			phase: 'impl',
-			fn: ruleQuickPickJoinEnumeration,
-			priority: 5
-		});
-
-		this.passManager.addRuleToPass(PassId.Physical, {
-			id: 'aggregate-streaming',
-			nodeType: PlanNodeType.Aggregate,
-			phase: 'impl',
-			fn: ruleAggregateStreaming,
-			priority: 20
-		});
-
-		// Post-optimization pass rules (bottom-up) - for cleanup and caching
-		this.passManager.addRuleToPass(PassId.PostOptimization, {
-			id: 'mutating-subquery-cache',
-			nodeType: PlanNodeType.Join,
-			phase: 'rewrite',
-			fn: ruleMutatingSubqueryCache,
-			priority: 10
-		});
-
-		this.passManager.addRuleToPass(PassId.PostOptimization, {
-			id: 'cte-optimization',
-			nodeType: PlanNodeType.CTE,
-			phase: 'rewrite',
-			fn: ruleCteOptimization,
-			priority: 20
-		});
-
-		// Register materialization advisory for multiple node types
-		const nodeTypesForMaterialization = [
-			PlanNodeType.Block,
-			PlanNodeType.ScalarSubquery,
-			PlanNodeType.Exists,
-			PlanNodeType.In,
-			PlanNodeType.Insert,
-			PlanNodeType.Update,
-			PlanNodeType.Delete,
-			PlanNodeType.CTE,
-			PlanNodeType.RecursiveCTE,
-			PlanNodeType.Returning,
-			PlanNodeType.ScalarFunctionCall,
-			PlanNodeType.CaseExpr,
-		];
-
-		for (const nodeType of nodeTypesForMaterialization) {
-			this.passManager.addRuleToPass(PassId.PostOptimization, {
-				id: `materialization-advisory-${nodeType}`,
-				nodeType,
-				phase: 'rewrite',
-				fn: ruleMaterializationAdvisory,
-				priority: 30
-			});
-		}
-
-		log('Registered rules to optimization passes');
-	}
-
-	/**
-	 * Optimize a plan tree by applying transformation rules
-	 */
-	optimize(plan: PlanNode, db: Database): PlanNode {
-		log('Starting optimization of plan', plan.nodeType);
-
-		// Create optimization context
-		const context = createOptContext(this, this.stats, this.tuning, db);
-
-		tracePhaseStart('optimization');
-		try {
-			// Execute all optimization passes
-			const optimizedPlan = this.passManager.execute(plan, context);
-
-			// Capture diagnostics snapshot for external consumers
-			this.lastDiagnostics = { ...context.diagnostics };
-
-			// Final validation (if enabled)
-			if (this.tuning.debug.validatePlan) {
-				log('Running plan validation');
-				try {
-					validatePhysicalTree(optimizedPlan);
-					log('Plan validation passed');
-				} catch (error) {
-					log('Plan validation failed: %s', error);
-					throw error;
-				}
-			}
-
-			return optimizedPlan;
-		} finally {
-			tracePhaseEnd('optimization');
-		}
-	}
-
-	/**
-	 * Run only non-physical passes to obtain a structurally rewritten logical plan
-	 * suitable for pre-physical analysis (e.g., row-specific classification).
-	 */
-	optimizeForAnalysis(plan: PlanNode, db: Database): PlanNode {
-		log('Starting pre-physical analysis optimization of plan', plan.nodeType);
-
-		const context = createOptContext(this, this.stats, this.tuning, db);
-		tracePhaseStart('pre-physical-analysis');
-		try {
-			// Execute only structural pass(es) and constant folding
-			const folded = this.performConstantFolding(plan, context);
-			const structuralOnly = this.passManager.executeUpTo(folded, context, PassId.Structural);
-			this.lastDiagnostics = { ...context.diagnostics };
-			return structuralOnly;
-		} finally {
-			tracePhaseEnd('pre-physical-analysis');
-		}
-	}
-
-	/**
-	 * Perform single-pass constant folding over the entire plan tree
-	 */
-	private performConstantFolding(plan: PlanNode, context: OptContext): PlanNode {
-		// Create runtime expression evaluator
-		const evaluator = createRuntimeExpressionEvaluator(context.db);
-
-		// Perform single-pass constant folding
-		const result = performConstantFolding(plan, evaluator);
-
-		log('Constant folding completed');
-		return result;
-	}
-
-	optimizeNode(node: PlanNode, context: OptContext): PlanNode {
-		traceNodeStart(node);
-
-		// Check if we've already optimized this exact node instance
-		const cached = context.optimizedNodes.get(node.id);
-		if (cached) {
-			log('Reusing optimized version of shared node %s (%s)', node.id, node.nodeType);
-			traceNodeEnd(node, cached);
-			return cached;
-		}
-
-		// Note: We removed the broken `if (node.physical)` check here
-		// The `physical` property is always truthy (it returns a PhysicalProperties object)
-		// Physical vs logical distinction should be handled by the rules themselves
-
-		// First optimize all children
-		const optimizedNode = this.optimizeChildren(node, context);
-
-		// Apply rules
-		const rulesApplied = applyRules(optimizedNode, context);
-
-		if (rulesApplied !== optimizedNode) {
-			// Rules transformed the node
-			log(`Rules applied to ${optimizedNode.nodeType}, transformed to ${rulesApplied.nodeType}`);
-			traceNodeEnd(node, rulesApplied);
-
-			// Cache the final result
-			context.optimizedNodes.set(node.id, rulesApplied);
-			return rulesApplied;
-		}
-
-		// No rule applied - assume node is physical
-		traceNodeEnd(node, optimizedNode);
-
-		// Cache the result even if no rules applied
-		context.optimizedNodes.set(node.id, optimizedNode);
-		return optimizedNode;
-	}
-
-	private optimizeChildren(node: PlanNode, context: OptContext): PlanNode {
-		// Generic tree walk using withChildren
-		const originalChildren = node.getChildren();
-		const optimizedChildren = originalChildren.map(child => this.optimizeNode(child, context));
-
-		// Check if any children changed
-		const childrenChanged = optimizedChildren.some((child, i) => child !== originalChildren[i]);
-
-		if (!childrenChanged) {
-			return node; // No changes
-		}
-
-		// Use withChildren to create new node with optimized children
-		// withChildren is a required contract - any errors should propagate
-		return node.withChildren(optimizedChildren);
-	}
-
-	/**
-	 * Get the statistics provider
-	 */
-	getStats(): StatsProvider {
-		return this.stats;
-	}
-
-	/** Get diagnostics from the last optimization run */
-	getLastDiagnostics(): OptimizerDiagnostics | null {
-		return this.lastDiagnostics;
-	}
-}

package/src/planner/planning-context.ts

@@ -1,190 +0,0 @@
-import type { SqlParameters } from '../common/types.js';
-import type { Database } from '../core/database.js';
-import type { SchemaManager } from '../schema/manager.js';
-import type { Scope } from './scopes/scope.js';
-import type { PlanNode, ScalarPlanNode } from './nodes/plan-node.js';
-import type { CTEScopeNode } from './nodes/cte-node.js';
-import type { CTEReferenceNode } from './nodes/cte-reference-node.js';
-
-/**
- * Debug options for query planning and execution.
- */
-export interface DebugOptions {
-  /** Enable runtime instruction tracing (logs inputs/outputs) */
-  traceInstructions?: boolean;
-  /** Enable detailed plan tree output */
-  showPlan?: boolean;
-  /** Enable instruction program output */
-  showProgram?: boolean;
-  /** Custom debug context for additional logging */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  debugContext?: Record<string, any>;
-}
-
-/**
- * Represents a dependency on a schema object that was resolved during planning.
- * Used for plan invalidation when schema changes.
- */
-export interface SchemaDependency {
-	readonly type: 'table' | 'function' | 'vtab_module' | 'collation';
-	readonly schemaName?: string; // undefined for functions, collations, and vtab modules
-	readonly objectName: string;
-	readonly objectVersion?: number; // For future versioning support
-}
-
-/**
- * Tracks schema dependencies during planning and provides invalidation callbacks.
- */
-export class BuildTimeDependencyTracker {
-	private dependencies = new Set<string>();
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	private resolvedObjects = new Map<string, WeakRef<any>>();
-	private invalidationCallbacks = new Set<() => void>();
-
-	/**
-	 * Records a dependency on a schema object and stores a weak reference to it.
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	recordDependency(dep: SchemaDependency, object: any): void {
-		const key = this.dependencyKey(dep);
-		this.dependencies.add(key);
-		this.resolvedObjects.set(key, new WeakRef(object));
-	}
-
-	/**
-	 * Adds a callback to be invoked when schema dependencies become invalid.
-	 */
-	addInvalidationCallback(callback: () => void): () => void {
-		this.invalidationCallbacks.add(callback);
-		return () => this.invalidationCallbacks.delete(callback);
-	}
-
-	/**
-	 * Checks if all dependencies are still valid by verifying weak references.
-	 */
-	checkIntegrity(): boolean {
-		for (const [_key, weakRef] of this.resolvedObjects.entries()) {
-			if (weakRef.deref() === undefined) {
-				// Object was garbage collected, dependency is invalid
-				return false;
-			}
-		}
-		return true;
-	}
-
-	/**
-	 * Gets all tracked dependencies.
-	 */
-	getDependencies(): SchemaDependency[] {
-		return Array.from(this.dependencies).map(key => this.parseDependencyKey(key));
-	}
-
-	/**
-	 * Checks if any dependencies are tracked.
-	 */
-	hasAnyDependencies(): boolean {
-		return this.dependencies.size > 0;
-	}
-
-	/**
-	 * Notifies all invalidation callbacks.
-	 */
-	notifyInvalidation(): void {
-		for (const callback of this.invalidationCallbacks) {
-			try {
-				callback();
-			} catch (error) {
-				console.error('Error in schema invalidation callback:', error);
-			}
-		}
-	}
-
-	private dependencyKey(dep: SchemaDependency): string {
-		const schema = dep.schemaName || '';
-		const version = dep.objectVersion || 0;
-		return `${dep.type}:${schema}:${dep.objectName}:${version}`;
-	}
-
-	private parseDependencyKey(key: string): SchemaDependency {
-		const [type, schemaName, objectName, versionStr] = key.split(':');
-		return {
-			type: type as SchemaDependency['type'],
-			schemaName: schemaName || undefined,
-			objectName,
-			objectVersion: parseInt(versionStr) || undefined
-		};
-	}
-}
-
-/**
- * Provides contextual information necessary during the query planning phase.
- * This object is passed to various planning functions to give them access to
- * the database schema, current symbol resolution scope, and other relevant details.
- */
-export interface PlanningContext {
-  /**
-   * The Database instance, providing access to the schema manager, function registry, etc.
-   */
-  readonly db: Database;
-
-  /**
-   * The SchemaManager instance, for direct access if needed (also available via db.schemaManager).
-   */
-  readonly schemaManager: SchemaManager; // Redundant if db is present, but can be convenient
-
-  /**
-   * The current Scope for symbol resolution (columns, parameters, CTEs).
-   * Planning functions for nested structures (like subqueries) will typically create a new Scope
-   * with the current scope as its parent and pass that down in a new PlanningContext.
-   */
-  readonly scope: Scope;
-
-	/**
-	 * The current parameters for the statement, as discovered by references.
-	 */
-	readonly parameters: SqlParameters;
-
-  /**
-   * Debug options controlling tracing and diagnostics output.
-   */
-  readonly debug?: DebugOptions;
-
-  /**
-   * Aggregates from the SELECT list (used when building HAVING expressions).
-   * This allows buildExpression to recognize when an aggregate function in HAVING
-   * refers to an already-computed aggregate from SELECT.
-   */
-  readonly aggregates?: Array<{
-    expression: ScalarPlanNode;
-    alias: string;
-    columnIndex: number;
-    attributeId: number;
-  }>;
-
-  /**
-   * Active CTEs available in the current planning context.
-   * This map contains all CTEs from the current WITH clause and any parent WITH clauses,
-   * allowing subqueries in expressions to resolve CTE references correctly.
-   */
-  readonly cteNodes?: Map<string, CTEScopeNode>;
-
-  /**
-   * Schema dependency tracker for this planning session.
-   */
-  readonly schemaDependencies: BuildTimeDependencyTracker;
-
-  /**
-   * Schema object cache for resolved objects during planning.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly schemaCache: Map<string, any>;
-
-  /**
-   * Cache for CTE reference nodes to ensure consistent attribute IDs across multiple references
-   * to the same CTE with the same alias. Key format: "cteName:alias"
-   */
-  cteReferenceCache?: Map<string, CTEReferenceNode>;
-
-  /** maps a RelationalPlanNode to its column scope during building */
-  readonly outputScopes: Map<PlanNode, Scope>;
-}