@quereus/quereus 0.1.0

package/src/parser/utils.ts

@@ -0,0 +1,10 @@
+import { quereusError } from '../common/errors.js';
+import { SqlValue } from '../common/types.js';
+import type { LiteralExpr } from './ast.js';
+
+export function getSyncLiteral(literal: LiteralExpr): SqlValue {
+	if (literal.value instanceof Promise) {
+		quereusError('Literal value is a promise');
+	}
+	return literal.value;
+}

package/src/parser/visitor.ts

@@ -0,0 +1,187 @@
+import { createLogger } from '../common/logger.js';
+import type * as AST from './ast.js';
+
+const log = createLogger('parser:visitor'); // Create logger instance
+const warnLog = log.extend('warn');
+
+
+/**
+ * Defines the callbacks for the AST visitor.
+ * Functions can return false to stop traversal down that branch.
+ */
+export interface AstVisitorCallbacks {
+	enterNode?: (node: AST.AstNode) => void | boolean;
+	exitNode?: (node: AST.AstNode) => void;
+	// Specific node type visitors (optional)
+	visitSelect?: (node: AST.SelectStmt) => void | boolean;
+	visitInsert?: (node: AST.InsertStmt) => void | boolean;
+	visitUpdate?: (node: AST.UpdateStmt) => void | boolean;
+	visitDelete?: (node: AST.DeleteStmt) => void | boolean;
+	visitValues?: (node: AST.ValuesStmt) => void | boolean;
+	visitTableSource?: (node: AST.TableSource) => void | boolean;
+	visitJoin?: (node: AST.JoinClause) => void | boolean;
+	visitFunctionSource?: (node: AST.FunctionSource) => void | boolean;
+	visitSubquerySource?: (node: AST.SubquerySource) => void | boolean;
+	visitBinaryExpr?: (node: AST.BinaryExpr) => void | boolean;
+	visitUnaryExpr?: (node: AST.UnaryExpr) => void | boolean;
+	visitCastExpr?: (node: AST.CastExpr) => void | boolean;
+	visitCollateExpr?: (node: AST.CollateExpr) => void | boolean;
+	visitFunctionExpr?: (node: AST.FunctionExpr) => void | boolean;
+	visitSubqueryExpr?: (node: AST.SubqueryExpr) => void | boolean;
+	visitWindowFunctionExpr?: (node: AST.WindowFunctionExpr) => void | boolean;
+	visitWindowDefinition?: (node: AST.WindowDefinition) => void | boolean;
+	visitLiteral?: (node: AST.LiteralExpr) => void;
+	visitIdentifier?: (node: AST.IdentifierExpr) => void;
+	visitColumn?: (node: AST.ColumnExpr) => void;
+	visitParameter?: (node: AST.ParameterExpr) => void;
+}
+/**
+ * Performs a depth-first traversal of the AST.
+ *
+ * @param node The starting AST node.
+ * @param callbacks An object containing visitor functions for different node types.
+ */
+export function traverseAst(node: AST.AstNode | undefined, callbacks: AstVisitorCallbacks): void {
+	if (!node) return;
+
+	if (callbacks.enterNode) {
+		const result = callbacks.enterNode(node);
+		if (result !== false) return; // Stop if enterNode returns false
+	}
+
+	// Call specific visitor if defined
+	const specificVisitorKey = `visit${node.type.charAt(0).toUpperCase() + node.type.slice(1)}` as keyof AstVisitorCallbacks;
+	if (callbacks[specificVisitorKey]) {
+		const specificVisitor = callbacks[specificVisitorKey] as (n: any) => void | boolean;
+		const result = specificVisitor(node);
+		if (result !== false) return; // Stop if specific visitor returns false
+	}
+
+	// Recursively traverse children based on node type
+	switch (node.type) {
+		case 'select': {
+			const stmt = node as AST.SelectStmt;
+			(stmt.columns ?? []).forEach(c => c.type === 'column' && traverseAst(c.expr, callbacks));
+			(stmt.from ?? []).forEach(f => traverseAst(f, callbacks));
+			traverseAst(stmt.where, callbacks);
+			(stmt.groupBy ?? []).forEach(g => traverseAst(g, callbacks));
+			traverseAst(stmt.having, callbacks);
+			(stmt.orderBy ?? []).forEach(o => traverseAst(o.expr, callbacks));
+			traverseAst(stmt.limit, callbacks);
+			traverseAst(stmt.offset, callbacks);
+			traverseAst(stmt.union, callbacks);
+			break;
+		}
+		case 'insert': {
+			const stmt = node as AST.InsertStmt;
+			traverseAst(stmt.table, callbacks);
+			(stmt.values ?? []).forEach(row => row.forEach(v => traverseAst(v, callbacks)));
+			traverseAst(stmt.select, callbacks);
+			break;
+		}
+		case 'update': {
+			const stmt = node as AST.UpdateStmt;
+			traverseAst(stmt.table, callbacks);
+			stmt.assignments.forEach(a => traverseAst(a.value, callbacks));
+			traverseAst(stmt.where, callbacks);
+			break;
+		}
+		case 'delete': {
+			const stmt = node as AST.DeleteStmt;
+			traverseAst(stmt.table, callbacks);
+			traverseAst(stmt.where, callbacks);
+			break;
+		}
+		case 'values': {
+			const stmt = node as AST.ValuesStmt;
+			stmt.values.forEach(row => row.forEach(v => traverseAst(v, callbacks)));
+			break;
+		}
+		case 'table':
+			// Handled by specific visitor or enterNode
+			break;
+		case 'join': {
+			const join = node as AST.JoinClause;
+			traverseAst(join.left, callbacks);
+			traverseAst(join.right, callbacks);
+			traverseAst(join.condition, callbacks);
+			break;
+		}
+		case 'functionSource': {
+			const funcSource = node as AST.FunctionSource;
+			traverseAst(funcSource.name, callbacks);
+			funcSource.args.forEach(a => traverseAst(a, callbacks));
+			break;
+		}
+		case 'subquerySource': {
+			const subqSource = node as AST.SubquerySource;
+			traverseAst(subqSource.subquery, callbacks);
+			break;
+		}
+		case 'binary': {
+			const expr = node as AST.BinaryExpr;
+			traverseAst(expr.left, callbacks);
+			traverseAst(expr.right, callbacks);
+			break;
+		}
+		case 'unary':
+		case 'cast':
+		case 'collate': {
+			traverseAst((node as AST.UnaryExpr | AST.CastExpr | AST.CollateExpr).expr, callbacks);
+			break;
+		}
+		case 'function': {
+			const func = node as AST.FunctionExpr;
+			func.args.forEach(a => traverseAst(a, callbacks));
+			break;
+		}
+		case 'subquery': {
+			const subq = node as AST.SubqueryExpr;
+			traverseAst(subq.query, callbacks);
+			break;
+		}
+		case 'windowFunction': {
+			const winFunc = node as AST.WindowFunctionExpr;
+			traverseAst(winFunc.function, callbacks);
+			traverseAst(winFunc.window, callbacks);
+			break;
+		}
+		case 'windowDefinition': {
+			const winDef = node as AST.WindowDefinition;
+			(winDef.partitionBy ?? []).forEach(p => traverseAst(p, callbacks));
+			(winDef.orderBy ?? []).forEach(o => traverseAst(o.expr, callbacks));
+			// traverseAst(winDef.frame, callbacks); // TODO: Traverse frame bounds if needed
+			break;
+		}
+		// Leaf nodes (literal, identifier, column, parameter) are handled by specific visitors or enterNode
+		case 'literal':
+		case 'identifier':
+		case 'column':
+		case 'parameter':
+			break;
+		// DDL / Transaction statements - might need traversal depending on use case
+		// Currently not traversing into them
+		case 'createTable':
+		case 'createIndex':
+		case 'createView':
+		case 'alterTable':
+		case 'drop':
+		case 'begin':
+		case 'commit':
+		case 'rollback':
+		case 'savepoint':
+		case 'release':
+		case 'pragma':
+		case 'with': // Usually handled separately before main traversal
+		case 'commonTableExpr': // Usually handled separately
+			break;
+		// Default case for unhandled node types
+		default:
+			warnLog(`AST Visitor: Unhandled node type: ${node.type}`);
+			break;
+	}
+
+	if (callbacks.exitNode) {
+		callbacks.exitNode(node);
+	}
+}

package/src/planner/analysis/README.md

@@ -0,0 +1,93 @@
+# Constant Folding Implementation
+
+This directory contains the Phase 3 constant folding implementation for the Titan optimizer.
+
+## Overview
+
+The constant folding system implements the two-phase algorithm described in `docs/optimizer-const.md`:
+
+1. **Bottom-up classification**: Assign `ConstInfo` to every node during post-order DFS
+2. **Top-down propagation**: Walk relational tree carrying known constant attributes
+
+## Files
+
+### `const-pass.ts`
+Core constant folding analysis with:
+- `ConstInfo` types: `const`, `dep`, `non-const`
+- `classifyConstants()` - bottom-up classification using generic tree walking
+- `applyConstPropagation()` - top-down propagation and folding
+- Framework ready for runtime-based evaluation
+
+### `const-evaluator.ts`
+Runtime-based expression evaluation:
+- `createRuntimeExpressionEvaluator()` - uses existing runtime via mini-scheduler
+- Avoids duplicate expression interpreter by reusing `emitPlanNode()` + `Scheduler`
+- Minimal `RuntimeContext` for constant-only evaluation
+
+### `constraint-extractor.ts`
+Existing predicate analysis utilities (Phase 0 infrastructure).
+
+## Integration Points
+
+### Builder Level
+```typescript
+import { foldScalars } from '../util/fold-scalars.js';
+
+// In VALUES, default expressions, etc.
+const foldedExpr = foldScalars(originalExpression);
+```
+
+### Optimizer Rules
+Constant folding runs as early `rewrite` phase rules (priority 10) targeting nodes with expressions:
+- Project (projection expressions)
+- Filter (predicate expressions) 
+- Window, Aggregate, Sort, Values, Join
+
+### Key Design Principles
+
+✅ **Generic Tree Walking**: Uses `getChildren()`/`withChildren()` exclusively
+✅ **Minimal Node-Type Knowledge**: Only checks types for targeting, not folding logic
+✅ **Expression Boundary Triggering**: Only runs on relational nodes with expressions
+✅ **Functional Safety**: Only folds expressions marked as `functional` (pure + deterministic)
+✅ **Attribute ID Preservation**: Maintains column reference validity through transformations
+
+## Usage
+
+### Basic Builder Usage
+```typescript
+import { foldScalars } from '../util/fold-scalars.js';
+
+// Automatically fold constant expressions in builders
+const expr = buildExpression(ctx, ast);
+const folded = foldScalars(expr); // e.g., "1 + 2 * 3" → "7"
+```
+
+### Advanced Runtime-Based Usage
+```typescript
+import { classifyConstants, applyConstPropagation, createConstFoldingContext } from '../analysis/const-pass.js';
+import { createRuntimeExpressionEvaluator } from '../analysis/const-evaluator.js';
+
+// For complex expressions requiring runtime evaluation
+const evaluator = createRuntimeExpressionEvaluator(database);
+const ctx = createConstFoldingContext(evaluator);
+classifyConstants(planTree, ctx);
+const foldedTree = applyConstPropagation(relationalNode, ctx);
+```
+
+### Debug Tracing
+```bash
+# Enable constant folding debug output
+DEBUG=quereus:optimizer:folding* yarn test
+```
+
+## Current Status
+
+- ✅ Infrastructure complete with `functional` flag and generic tree walking
+- ✅ Synchronous folding for basic arithmetic/logical operations  
+- ✅ Optimizer rule integration using generic `getProducingExprs()` interface
+- ✅ `MaybePromise<SqlValue>` support for async subquery constant folding
+- ✅ Builder-level utility for immediate expression folding
+- 🔄 Runtime evaluation framework ready for complex expressions
+- 🔄 Advanced expression types (CASE, CAST, functions) need implementation
+
+The implementation provides immediate value through synchronous folding while supporting promise-based values for subquery constants, eliminating the "projection list" specificity through the generic `getProducingExprs()` interface. 

package/src/planner/analysis/const-evaluator.ts

@@ -0,0 +1,63 @@
+/**
+ * Runtime-based expression evaluator for constant folding
+ *
+ * This module provides evaluation of constant expressions using the existing runtime
+ * through a mini-scheduler, avoiding the need for a separate expression interpreter.
+ */
+
+import type { MaybePromise, OutputValue } from '../../common/types.js';
+import type { Database } from '../../core/database.js';
+import { emitPlanNode } from '../../runtime/emitters.js';
+import { EmissionContext } from '../../runtime/emission-context.js';
+import { Scheduler } from '../../runtime/scheduler.js';
+import type { RuntimeContext } from '../../runtime/types.js';
+import { createLogger } from '../../common/logger.js';
+import { PlanNode } from '../nodes/plan-node.js';
+
+const log = createLogger('optimizer:folding:eval');
+
+/**
+ * Create an expression evaluator that uses the runtime to evaluate constant expressions
+ */
+export function createRuntimeExpressionEvaluator(db: Database): (expr: PlanNode) => MaybePromise<OutputValue> {
+	return function evaluateExpression(expr: PlanNode): MaybePromise<OutputValue> {
+		log('Evaluating constant expression: %s', expr.nodeType);
+
+		try {
+			// Create temporary emission context
+			const emissionCtx = new EmissionContext(db);
+
+			// Emit the expression to an instruction
+			const instruction = emitPlanNode(expr, emissionCtx);
+
+			// Create a scheduler to execute the instruction
+			const scheduler = new Scheduler(instruction);
+
+			// Create minimal runtime context for evaluation
+			// No row context is needed since we only evaluate constant expressions
+			const runtimeCtx: RuntimeContext = {
+				db,
+				stmt: null, // No statement context needed for constants
+				params: {}, // No parameters needed for constants
+				context: new Map(), // No row context needed
+				tableContexts: new Map(), // No table contexts needed for constants
+				enableMetrics: false
+			};
+
+			// Execute and get the result
+			const result = scheduler.run(runtimeCtx);
+
+			// Ensure result is a valid OutputValue
+			if (result === undefined) {
+				throw new Error('Expression evaluation returned undefined');
+			}
+
+			log('Expression evaluated to: %s', result);
+			return result as MaybePromise<OutputValue>;
+
+		} catch (error) {
+			log('Failed to evaluate expression %s: %s', expr.nodeType, error);
+			throw new Error(`Expression evaluation failed: ${error}`);
+		}
+	};
+}

package/src/planner/analysis/const-pass.ts

@@ -0,0 +1,270 @@
+/**
+ * Constant folding analysis for the Titan optimizer
+ *
+ * This module implements efficient single-pass constant folding:
+ * 1. Bottom-up classification: Assign ConstInfo to every node during post-order DFS
+ * 2. Top-down border detection: Identify const nodes whose parents are non-const
+ * 3. Replacement: Replace border nodes with appropriate literals
+ */
+
+import { PlanNode } from '../nodes/plan-node.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { type SqlValue, type MaybePromise, OutputValue } from '../../common/types.js';
+import { LiteralNode } from '../nodes/scalar.js';
+import { createLogger } from '../../common/logger.js';
+
+const log = createLogger('optimizer:folding');
+
+/**
+ * Constant information classification for plan nodes
+ */
+interface ConstInfoConst {
+	kind: 'const';
+	node: PlanNode; // Store the const node itself, not its value
+}
+
+interface ConstInfoDep {
+	kind: 'dep';
+	deps: Set<number>; // Set of AttributeId
+}
+
+interface ConstInfoVar {
+	kind: 'non-const';
+}
+
+type ConstInfo = ConstInfoConst | ConstInfoDep | ConstInfoVar;
+
+/**
+ * Context for constant folding analysis
+ */
+export interface ConstFoldingContext {
+	/** Map from node ID to ConstInfo classification */
+	constInfo: Map<string, ConstInfo>;
+	/** Border nodes that need evaluation (nodeId -> node) */
+	borderNodes: Map<string, PlanNode>;
+	/** Evaluation function for border expressions */
+	evaluateExpression: (node: PlanNode) => MaybePromise<OutputValue>;
+}
+
+/**
+ * Create a new constant folding context
+ */
+export function createConstFoldingContext(
+	evaluateExpression: (node: PlanNode) => MaybePromise<OutputValue>
+): ConstFoldingContext {
+	return {
+		constInfo: new Map(),
+		borderNodes: new Map(),
+		evaluateExpression
+	};
+}
+
+/**
+ * Perform complete single-pass constant folding on a plan tree
+ * This is the main entry point for efficient constant folding
+ */
+export function performConstantFolding(
+	root: PlanNode,
+	evaluateExpression: (node: PlanNode) => MaybePromise<OutputValue>
+): PlanNode {
+	const ctx = createConstFoldingContext(evaluateExpression);
+
+	// Phase 1: Bottom-up classification
+	classifyConstants(root, ctx);
+
+	// Phase 2: Top-down border detection with dependency resolution
+	detectBorderNodes(root, ctx, new Set());
+
+	// Phase 3: Replace border nodes
+	return replaceBorderNodes(root, ctx);
+}
+
+/**
+ * Perform bottom-up constant classification on a plan tree
+ */
+export function classifyConstants(root: PlanNode, ctx: ConstFoldingContext): void {
+	// Post-order DFS - classify children before parent
+	const children = root.getChildren();
+	for (const child of children) {
+		classifyConstants(child, ctx);
+	}
+
+	// Classify this node based on its type and children
+	const constInfo = classifyNode(root, ctx);
+	ctx.constInfo.set(root.id, constInfo);
+
+	log('Classified node %s (%s): %s', root.id, root.nodeType,
+		constInfo.kind === 'const' ? `const` :
+		constInfo.kind === 'dep' ? `dep([${Array.from(constInfo.deps).join(',')}])` :
+		'non-const');
+}
+
+/**
+ * Classify a single node - works for ANY node type
+ */
+function classifyNode(node: PlanNode, ctx: ConstFoldingContext): ConstInfo {
+	// Rule 1: Any node with physical.constant === true
+	if (node.physical.constant) {
+		if ('getValue' in node) {
+			return { kind: 'const', node: node };
+		}
+		throw new Error(`Node ${node} is constant but does not implement getValue()`);
+	}
+
+	// Rule 2: ColumnReference → dep with {attrId}
+	if (node.nodeType === PlanNodeType.ColumnReference) {
+		const colRef = node as any; // ColumnReferenceNode
+		return { kind: 'dep', deps: new Set([colRef.attributeId]) };
+	}
+
+	// Rule 3: Any other node - check if functional and inspect children
+	if (!PlanNode.isFunctional(node.physical)) {
+		return { kind: 'non-const' };
+	}
+
+	// Inspect children (works for both scalar and relational children)
+	const childConstInfos = node.getChildren().map(child => {
+		const childInfo = ctx.constInfo.get(child.id);
+		if (!childInfo) {
+			throw new Error(`No ConstInfo found for child node ${child.id}`);
+		}
+		return childInfo;
+	});
+
+	// If all children are const → this node is const
+	if (childConstInfos.every(info => info.kind === 'const')) {
+		return { kind: 'const', node: node };
+	}
+
+	// If all children ∈ {const, dep} → dep with union of child deps
+	if (childConstInfos.every(info => info.kind === 'const' || info.kind === 'dep')) {
+		const allDeps = new Set<number>();
+		for (const info of childConstInfos) {
+			if (info.kind === 'dep') {
+				for (const dep of info.deps) {
+					allDeps.add(dep);
+				}
+			}
+		}
+		return { kind: 'dep', deps: allDeps };
+	}
+
+	// Otherwise → non-const
+	return { kind: 'non-const' };
+}
+
+/**
+ * Top-down border detection with dependency resolution
+ * A border node is:
+ * - A const node (always foldable)
+ * - A dep node whose dependencies are all resolved by known constant attributes
+ */
+function detectBorderNodes(
+	node: PlanNode,
+	ctx: ConstFoldingContext,
+	knownConstAttrs: Set<number> = new Set()
+): void {
+	const nodeInfo = ctx.constInfo.get(node.id);
+
+	// Check if this node is a border node
+	if (nodeInfo?.kind === 'const') {
+		// Const nodes are always border nodes
+		ctx.borderNodes.set(node.id, node);
+		log('Detected const border node: %s (%s)', node.id, node.nodeType);
+		// Don't recurse into const subtrees - they'll all be replaced
+		return;
+	} else if (nodeInfo?.kind === 'dep') {
+		// Dep nodes become border nodes if all dependencies are resolved
+		if (isSubsetOf(nodeInfo.deps, knownConstAttrs)) {
+			ctx.borderNodes.set(node.id, node);
+			log('Detected resolved dep border node: %s (%s) - deps %s resolved by %s',
+				node.id, node.nodeType,
+				Array.from(nodeInfo.deps).join(','),
+				Array.from(knownConstAttrs).join(','));
+			// Don't recurse - this entire subtree will be replaced
+			return;
+		}
+	}
+
+	// Update known constant attributes for this scope
+	const updatedKnownAttrs = new Set(knownConstAttrs);
+
+	// If this is a relational node that produces expressions, check what new constants it introduces
+	if (node.getType().typeClass === 'relation' && 'getProducingExprs' in node) {
+		const producingExprs = (node as any).getProducingExprs();
+
+		if (producingExprs) {
+			for (const [attrId, expr] of producingExprs) {
+				const exprInfo = ctx.constInfo.get(expr.id);
+
+				if (exprInfo?.kind === 'const') {
+					// This expression produces a constant attribute
+					updatedKnownAttrs.add(attrId);
+					log('Node %s produces constant attribute %d', node.id, attrId);
+				} else if (exprInfo?.kind === 'dep' && isSubsetOf(exprInfo.deps, knownConstAttrs)) {
+					// This expression's dependencies are resolved, so it produces a constant
+					updatedKnownAttrs.add(attrId);
+					log('Node %s produces resolved constant attribute %d (was dep on %s)',
+						node.id, attrId, Array.from(exprInfo.deps).join(','));
+				}
+			}
+		}
+	}
+
+	// Recurse to children with updated known constant attributes
+	for (const child of node.getChildren()) {
+		detectBorderNodes(child, ctx, updatedKnownAttrs);
+	}
+}
+
+/**
+ * Utility function to check if set A is a subset of set B
+ */
+function isSubsetOf<T>(setA: Set<T>, setB: Set<T>): boolean {
+	if (setA.size === 0) return true; // Empty set is subset of everything
+	for (const elem of setA) {
+		if (!setB.has(elem)) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Replace border nodes with appropriate literals
+ */
+function replaceBorderNodes(node: PlanNode, ctx: ConstFoldingContext): PlanNode {
+	// If this node is a border node, replace it
+	if (ctx.borderNodes.has(node.id)) {
+		try {
+			const evaluatedValue = ctx.evaluateExpression(node);
+
+			// Choose replacement type based on node type
+			if (node.getType().typeClass === 'scalar') {
+				const literalExpr = { type: 'literal' as const, value: evaluatedValue as SqlValue };
+				const replacement = new LiteralNode(node.scope, literalExpr);
+				log('Replaced scalar border node %s with LiteralNode', node.id);
+				return replacement;
+			} else {
+				// Relational node - replace with TableLiteralNode
+				// TODO: Handle relational evaluation properly
+				log('Relational border node %s detected but not yet implemented', node.id);
+				return node;
+			}
+		} catch (error) {
+			log('Failed to evaluate border node %s: %s', node.id, error);
+			return node;
+		}
+	}
+
+	// Recursively replace children
+	const children = node.getChildren();
+	const replacedChildren = children.map(child => replaceBorderNodes(child, ctx));
+
+	// If any children changed, create new node
+	if (replacedChildren.some((child, i) => child !== children[i])) {
+		return node.withChildren(replacedChildren);
+	}
+
+	return node;
+}