@quereus/quereus 0.1.0

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

@@ -0,0 +1,172 @@
+/**
+ * Reference graph builder for materialization advisory
+ * Analyzes plan tree to identify nodes that would benefit from caching
+ */
+
+import { createLogger } from '../../common/logger.js';
+import type { PlanNode } from '../nodes/plan-node.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { JoinNode } from '../nodes/join-node.js';
+import type { OptimizerTuning } from '../optimizer-tuning.js';
+
+const log = createLogger('optimizer:cache:reference-graph');
+
+/**
+ * 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 class ReferenceGraphBuilder {
+	private refMap = new Map<PlanNode, RefStats>();
+	private visited = new Set<PlanNode>();
+
+	constructor(private tuning: OptimizerTuning) {}
+
+	/**
+	 * Build reference statistics for all nodes in the plan tree
+	 */
+	buildReferenceGraph(root: PlanNode): Map<PlanNode, RefStats> {
+		this.refMap.clear();
+		this.visited.clear();
+
+		// First pass: count parent references
+		this.countReferences(root, false);
+
+		// Second pass: identify loop contexts
+		this.identifyLoopContexts(root, false);
+
+		log('Built reference graph with %d nodes', this.refMap.size);
+		return new Map(this.refMap);
+	}
+
+	/**
+	 * First pass: count how many parents reference each node
+	 */
+	private countReferences(node: PlanNode, inLoop: boolean): void {
+		if (this.visited.has(node)) {
+			// Node seen again - increment parent count
+			const stats = this.refMap.get(node);
+			if (stats) {
+				stats.parentCount++;
+			}
+			return;
+		}
+
+		this.visited.add(node);
+
+		// Initialize stats for this node
+		const stats: RefStats = {
+			parentCount: 1, // First time seeing this node
+			appearsInLoop: inLoop,
+			estimatedRows: this.getEstimatedRows(node),
+			deterministic: this.isDeterministic(node)
+		};
+
+		this.refMap.set(node, stats);
+
+		// Recurse to children
+		this.visitChildren(node, (child) => {
+			this.countReferences(child, inLoop);
+		});
+	}
+
+	/**
+	 * Second pass: identify nodes that appear in loop contexts
+	 */
+	private identifyLoopContexts(node: PlanNode, inLoop: boolean): void {
+		const stats = this.refMap.get(node);
+		if (!stats) return;
+
+		// Update loop status if we're now in a loop context
+		if (inLoop && !stats.appearsInLoop) {
+			stats.appearsInLoop = true;
+			log('Node %s marked as appearing in loop', node.nodeType);
+		}
+
+		// Determine if children are in loop context
+		if (node instanceof JoinNode && node.joinType === 'inner') {
+			// Right side of nested loop join is in loop context
+			const [left, right] = node.getRelations();
+			this.identifyLoopContexts(left, inLoop);
+			this.identifyLoopContexts(right, true); // Right side is in loop
+		} else {
+			// Recurse to all children with current loop status
+			this.visitChildren(node, (child) => {
+				this.identifyLoopContexts(child, inLoop);
+			});
+		}
+	}
+
+	/**
+	 * Visit all children of a node
+	 */
+	private visitChildren(node: PlanNode, visitor: (child: PlanNode) => void): void {
+		// Visit scalar expression children
+		for (const child of node.getChildren()) {
+			visitor(child);
+		}
+
+		// Visit relational children
+		if ('getRelations' in node) {
+			for (const relation of (node as any).getRelations()) {
+				visitor(relation);
+			}
+		}
+	}
+
+	/**
+	 * Get estimated row count for a node
+	 */
+	private getEstimatedRows(node: PlanNode): number {
+		if ('estimatedRows' in node && typeof node.estimatedRows === 'number') {
+			return node.estimatedRows;
+		}
+		if (node.physical?.estimatedRows) {
+			return node.physical.estimatedRows;
+		}
+		return this.tuning.defaultRowEstimate;
+	}
+
+	/**
+	 * Determine if a node is deterministic
+	 */
+	private isDeterministic(node: PlanNode): boolean {
+		// Check physical properties first
+		if (node.physical?.deterministic !== undefined) {
+			return node.physical.deterministic;
+		}
+
+		// Node-type specific deterministic analysis
+		switch (node.nodeType) {
+			case PlanNodeType.TableScan:
+			case PlanNodeType.Values:
+			case PlanNodeType.Project:
+			case PlanNodeType.Filter:
+			case PlanNodeType.Sort:
+			case PlanNodeType.Aggregate:
+			case PlanNodeType.StreamAggregate:
+				return true;
+
+			case PlanNodeType.TableFunctionCall:
+				// Would need to check if the table function is deterministic
+				// For now, assume non-deterministic to be safe
+				return false;
+
+			default:
+				// Conservative default - assume deterministic unless proven otherwise
+				return true;
+		}
+	}
+}

package/src/planner/cost/index.ts

@@ -0,0 +1,169 @@
+/**
+ * Cost model helpers for query optimization
+ * Provides consistent cost estimation formulas across the optimizer
+ */
+
+import { quereusError } from "../../common/errors.js";
+import { StatusCode } from "../../common/types.js";
+
+/**
+ * Basic cost constants (in arbitrary "virtual CPU units")
+ */
+export const COST_CONSTANTS = {
+	/** Cost per row for sequential scan */
+	SEQ_SCAN_PER_ROW: 1.0,
+	/** Base cost for starting a sequential scan */
+	SEQ_SCAN_BASE: 0.1,
+
+	/** Cost per row for index seek */
+	INDEX_SEEK_PER_ROW: 0.3,
+	/** Base cost for index seek operation */
+	INDEX_SEEK_BASE: 0.5,
+
+	/** Cost per row for index scan */
+	INDEX_SCAN_PER_ROW: 0.5,
+	/** Base cost for index scan operation */
+	INDEX_SCAN_BASE: 0.3,
+
+	/** Cost per row for sorting */
+	SORT_PER_ROW: 2.0,
+	/** Log base for sort cost calculations */
+	SORT_LOG_BASE: 2,
+
+	/** Cost per row for filtering */
+	FILTER_PER_ROW: 0.2,
+
+	/** Cost per row for projection */
+	PROJECT_PER_ROW: 0.1,
+
+	/** Cost per output row for aggregation */
+	AGGREGATE_PER_GROUP: 1.5,
+	/** Cost per input row for aggregation */
+	AGGREGATE_PER_INPUT_ROW: 0.3,
+
+	/** Cost per row for nested loop join (inner side) */
+	NL_JOIN_PER_INNER_ROW: 0.1,
+	/** Cost per row for nested loop join (outer side) */
+	NL_JOIN_PER_OUTER_ROW: 1.0,
+
+	/** Cost per row for hash join build phase */
+	HASH_JOIN_BUILD_PER_ROW: 0.8,
+	/** Cost per row for hash join probe phase */
+	HASH_JOIN_PROBE_PER_ROW: 0.4,
+
+	/** Cost per row for distinct operation */
+	DISTINCT_PER_ROW: 1.2,
+
+	/** Cost per row for limit operation */
+	LIMIT_PER_ROW: 0.05,
+
+	/** Cost per row for cache access */
+	CACHE_ACCESS_PER_ROW: 0.1,
+	/** Cost per row for cache population */
+	CACHE_POPULATE_PER_ROW: 0.2,
+} as const;
+
+/**
+ * Calculate cost for sequential scan
+ */
+export function seqScanCost(rows: number): number {
+	return COST_CONSTANTS.SEQ_SCAN_BASE + (rows * COST_CONSTANTS.SEQ_SCAN_PER_ROW);
+}
+
+/**
+ * Calculate cost for index seek (point lookup or tight range)
+ */
+export function indexSeekCost(rows: number): number {
+	return COST_CONSTANTS.INDEX_SEEK_BASE + (rows * COST_CONSTANTS.INDEX_SEEK_PER_ROW);
+}
+
+/**
+ * Calculate cost for index scan (range scan with ordering)
+ */
+export function indexScanCost(rows: number): number {
+	return COST_CONSTANTS.INDEX_SCAN_BASE + (rows * COST_CONSTANTS.INDEX_SCAN_PER_ROW);
+}
+
+/**
+ * Calculate cost for sorting operation
+ * Uses O(n log n) complexity
+ */
+export function sortCost(rows: number): number {
+	if (rows <= 1) return COST_CONSTANTS.SORT_PER_ROW;
+	return rows * Math.log2(rows) * COST_CONSTANTS.SORT_PER_ROW;
+}
+
+/**
+ * Calculate cost for filter operation
+ */
+export function filterCost(inputRows: number): number {
+	return inputRows * COST_CONSTANTS.FILTER_PER_ROW;
+}
+
+/**
+ * Calculate cost for projection operation
+ */
+export function projectCost(rows: number, projectionCount: number = 1): number {
+	return rows * projectionCount * COST_CONSTANTS.PROJECT_PER_ROW;
+}
+
+/**
+ * Calculate cost for aggregation operation
+ */
+export function aggregateCost(inputRows: number, outputRows: number): number {
+	return (inputRows * COST_CONSTANTS.AGGREGATE_PER_INPUT_ROW) +
+		   (outputRows * COST_CONSTANTS.AGGREGATE_PER_GROUP);
+}
+
+/**
+ * Calculate cost for nested loop join
+ */
+export function nestedLoopJoinCost(outerRows: number, innerRows: number): number {
+	return (outerRows * COST_CONSTANTS.NL_JOIN_PER_OUTER_ROW) +
+		   (outerRows * innerRows * COST_CONSTANTS.NL_JOIN_PER_INNER_ROW);
+}
+
+/**
+ * Calculate cost for hash join
+ */
+export function hashJoinCost(buildRows: number, probeRows: number): number {
+	return (buildRows * COST_CONSTANTS.HASH_JOIN_BUILD_PER_ROW) +
+		   (probeRows * COST_CONSTANTS.HASH_JOIN_PROBE_PER_ROW);
+}
+
+/**
+ * Calculate cost for distinct operation
+ */
+export function distinctCost(rows: number): number {
+	// Distinct typically involves sorting or hashing
+	return rows * COST_CONSTANTS.DISTINCT_PER_ROW;
+}
+
+/**
+ * Calculate cost for limit operation
+ */
+export function limitCost(inputRows: number, limitValue: number): number {
+	const processedRows = Math.min(inputRows, limitValue);
+	return processedRows * COST_CONSTANTS.LIMIT_PER_ROW;
+}
+
+/**
+ * Calculate cost for cache operations
+ */
+export function cacheCost(rows: number, accessCount: number = 1): number {
+	const populateCost = rows * COST_CONSTANTS.CACHE_POPULATE_PER_ROW;
+	const accessCost = rows * accessCount * COST_CONSTANTS.CACHE_ACCESS_PER_ROW;
+	return populateCost + accessCost;
+}
+
+/**
+ * Helper to choose the minimum cost option
+ */
+export function chooseCheapest<T>(options: Array<{ cost: number; option: T }>): T {
+	if (options.length === 0) {
+		quereusError('No options provided to chooseCheapest', StatusCode.INTERNAL);
+	}
+	return options.reduce((min, current) =>
+		current.cost < min.cost ? current : min
+	).option;
+}

package/src/planner/debug/logger-utils.ts

@@ -0,0 +1,68 @@
+/**
+ * Debug namespace utilities for the Titan optimizer
+ * Provides standardized logger creation and debug conventions
+ */
+
+import { createLogger } from '../../common/logger.js';
+
+/**
+ * Create a logger for optimizer rules
+ * @param ruleName The name of the optimization rule
+ * @returns A debug logger with the standard optimizer:rule namespace
+ */
+export function ruleLog(ruleName: string) {
+	return createLogger(`optimizer:rule:${ruleName}`);
+}
+
+/**
+ * Create a logger for optimizer validation
+ * @param component The validation component (e.g., 'plan', 'attributes', 'ordering')
+ * @returns A debug logger with the standard optimizer:validate namespace
+ */
+export function validateLog(component: string = '') {
+	const namespace = component ? `optimizer:validate:${component}` : 'optimizer:validate';
+	return createLogger(namespace);
+}
+
+/**
+ * Create a logger for runtime statistics
+ * @param component The stats component (e.g., 'metrics', 'summary', 'cache')
+ * @returns A debug logger with the standard runtime:stats namespace
+ */
+export function statsLog(component: string = '') {
+	const namespace = component ? `runtime:stats:${component}` : 'runtime:stats';
+	return createLogger(namespace);
+}
+
+/**
+ * Create a logger for constant folding operations
+ * @param component The folding component (e.g., 'evaluation', 'binary-ops', 'functions')
+ * @returns A debug logger with the standard optimizer:folding namespace
+ */
+export function foldingLog(component: string = '') {
+	const namespace = component ? `optimizer:folding:${component}` : 'optimizer:folding';
+	return createLogger(namespace);
+}
+
+/**
+ * Create a logger for plan emission
+ * @param emitterName The name of the emitter
+ * @returns A debug logger with the standard runtime:emit namespace
+ */
+export function emitLog(emitterName: string) {
+	return createLogger(`runtime:emit:${emitterName}`);
+}
+
+
+
+
+
+/**
+ * Examples of debug namespace usage
+ *
+ * Enable all optimizer rules: DEBUG=optimizer:rule:* yarn test
+ * Enable plan validation: DEBUG=optimizer:validate yarn test
+ * Enable runtime stats: DEBUG=runtime:stats yarn test
+ * Enable specific rule: DEBUG=optimizer:rule:aggregate-streaming yarn test
+ * Enable everything: DEBUG=* yarn test
+ */