@quereus/quereus 0.1.0

package/src/planner/framework/physical-utils.ts

@@ -0,0 +1,210 @@
+/**
+ * Physical property utilities for the Titan optimizer
+ * Provides helpers for handling ordering, unique keys, and property propagation
+ */
+
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import type { ColumnReferenceNode } from '../nodes/reference.js';
+
+/**
+ * Ordering specification for a column
+ */
+export interface Ordering {
+	/** Column index */
+	column: number;
+	/** True for descending order */
+	desc: boolean;
+}
+
+/**
+ * Extract ordering from sort keys if they are trivial column references
+ * Returns undefined if any sort key is not a simple column reference
+ */
+export function extractOrderingFromSortKeys(
+	sortKeys: readonly { expression: ScalarPlanNode; direction: 'asc' | 'desc' }[],
+	sourceAttributes: readonly { id: number }[]
+): Ordering[] | undefined {
+	const ordering: Ordering[] = [];
+
+	for (const sortKey of sortKeys) {
+		// Check if this is a trivial column reference
+		if (sortKey.expression.nodeType !== PlanNodeType.ColumnReference) {
+			return undefined; // Non-trivial expression, cannot determine ordering
+		}
+
+		const columnRef = sortKey.expression as unknown as ColumnReferenceNode;
+
+		// Find the column index in the source attributes
+		const columnIndex = sourceAttributes.findIndex(attr => attr.id === columnRef.attributeId);
+		if (columnIndex === -1) {
+			return undefined; // Column not found in source
+		}
+
+		ordering.push({
+			column: columnIndex,
+			desc: sortKey.direction === 'desc'
+		});
+	}
+
+	return ordering;
+}
+
+/**
+ * Check if a scalar expression is a trivial column reference
+ */
+export function isTrivialColumnReference(expr: ScalarPlanNode): boolean {
+	return expr.nodeType === PlanNodeType.ColumnReference;
+}
+
+/**
+ * Extract column index from a column reference if it exists in the given attributes
+ */
+export function getColumnIndex(
+	columnRef: ColumnReferenceNode,
+	attributes: Array<{ id: number }>
+): number | undefined {
+	const index = attributes.findIndex(attr => attr.id === columnRef.attributeId);
+	return index >= 0 ? index : undefined;
+}
+
+/**
+ * Merge ordering requirements between parent and child
+ * Returns undefined if orderings are incompatible
+ */
+export function mergeOrderings(
+	parent: Ordering[] | undefined,
+	child: Ordering[] | undefined
+): Ordering[] | undefined {
+	// If parent has no ordering requirements, use child's ordering
+	if (!parent || parent.length === 0) {
+		return child;
+	}
+
+	// If child provides no ordering, parent requirements cannot be satisfied
+	if (!child || child.length === 0) {
+		return undefined;
+	}
+
+	// Check if child ordering satisfies parent requirements
+	if (parent.length > child.length) {
+		return undefined; // Child provides fewer columns than parent needs
+	}
+
+	// Verify each parent requirement is satisfied by child
+	for (let i = 0; i < parent.length; i++) {
+		const parentOrder = parent[i];
+		const childOrder = child[i];
+
+		if (parentOrder.column !== childOrder.column ||
+			parentOrder.desc !== childOrder.desc) {
+			return undefined; // Ordering mismatch
+		}
+	}
+
+	// Parent requirements are satisfied, return child's full ordering
+	return child;
+}
+
+/**
+ * Check if two orderings are compatible (one satisfies the other)
+ */
+export function orderingsCompatible(
+	required: Ordering[] | undefined,
+	provided: Ordering[] | undefined
+): boolean {
+	if (!required || required.length === 0) {
+		return true; // No requirements
+	}
+
+	if (!provided || provided.length === 0) {
+		return false; // Requirements exist but nothing provided
+	}
+
+	if (required.length > provided.length) {
+		return false; // Not enough columns provided
+	}
+
+	// Check prefix compatibility
+	for (let i = 0; i < required.length; i++) {
+		const req = required[i];
+		const prov = provided[i];
+
+		if (req.column !== prov.column || req.desc !== prov.desc) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Check if orderings are exactly equal
+ */
+export function orderingsEqual(
+	a: Ordering[] | undefined,
+	b: Ordering[] | undefined
+): boolean {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	if (a.length !== b.length) return false;
+
+	for (let i = 0; i < a.length; i++) {
+		if (a[i].column !== b[i].column || a[i].desc !== b[i].desc) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Reverse an ordering (flip ASC/DESC)
+ */
+export function reverseOrdering(ordering: Ordering[]): Ordering[] {
+	return ordering.map(ord => ({ ...ord, desc: !ord.desc }));
+}
+
+/**
+ * Check if unique keys guarantee distinctness for given columns
+ */
+export function uniqueKeysImplyDistinct(
+	uniqueKeys: number[][],
+	projectedColumns: number[]
+): boolean {
+	// Check if any unique key is a subset of projected columns
+	return uniqueKeys.some(key =>
+		key.every(col => projectedColumns.includes(col))
+	);
+}
+
+/**
+ * Project unique keys through a projection
+ * Returns keys that are still unique after projection
+ */
+export function projectUniqueKeys(
+	uniqueKeys: number[][],
+	columnMapping: Map<number, number> // oldColumn -> newColumn
+): number[][] {
+	const result: number[][] = [];
+
+	for (const key of uniqueKeys) {
+		const projectedKey: number[] = [];
+		let keyIsValid = true;
+
+		for (const col of key) {
+			const newCol = columnMapping.get(col);
+			if (newCol === undefined) {
+				keyIsValid = false;
+				break; // Key column not in projection
+			}
+			projectedKey.push(newCol);
+		}
+
+		if (keyIsValid) {
+			result.push(projectedKey);
+		}
+	}
+
+	return result;
+}

package/src/planner/framework/registry.ts

@@ -0,0 +1,274 @@
+/**
+ * Rule registration and management framework for the Titan optimizer
+ * Provides centralized rule registry with tracing and loop detection
+ */
+
+import { createLogger } from '../../common/logger.js';
+import type { PlanNode } from '../nodes/plan-node.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import type { OptContext } from './context.js';
+import { traceRuleStart, traceRuleEnd } from './trace.js';
+import { StatusCode } from '../../common/types.js';
+import { quereusError } from '../../common/errors.js';
+
+const log = createLogger('optimizer:framework:registry');
+
+/**
+ * Rule function signature for optimization transformations
+ */
+export type RuleFn = (node: PlanNode, context: OptContext) => PlanNode | null;
+
+/**
+ * Rule phases for categorizing optimization rules
+ */
+export type RulePhase = 'rewrite' | 'impl';
+
+/**
+ * Handle for registered optimization rules
+ */
+export interface RuleHandle {
+	/** Unique identifier for this rule */
+	id: string;
+	/** Node type this rule applies to */
+	nodeType: PlanNodeType;
+	/** Phase classification */
+	phase: RulePhase;
+	/** Rule implementation function */
+	fn: RuleFn;
+	/** Optional priority (lower numbers run first) */
+	priority?: number;
+}
+
+/**
+ * Global rule registry
+ */
+class RuleRegistry {
+	private rules = new Map<PlanNodeType, RuleHandle[]>();
+	private visitedRules = new Map<string, Set<string>>(); // nodeId -> ruleIds applied
+
+	/**
+	 * Register a new optimization rule
+	 */
+	registerRule(handle: RuleHandle): void {
+		if (!this.rules.has(handle.nodeType)) {
+			this.rules.set(handle.nodeType, []);
+		}
+
+		const nodeRules = this.rules.get(handle.nodeType)!;
+
+		// Check for duplicate rule IDs
+		if (nodeRules.some(r => r.id === handle.id)) {
+			quereusError(`Optimization rule '${handle.id}' already registered for node type ${handle.nodeType}`, StatusCode.INTERNAL);
+		}
+
+		// Insert rule maintaining priority order (lower priority first)
+		const priority = handle.priority ?? 100;
+		const insertIndex = nodeRules.findIndex(r => (r.priority ?? 100) > priority);
+		if (insertIndex === -1) {
+			nodeRules.push(handle);
+		} else {
+			nodeRules.splice(insertIndex, 0, handle);
+		}
+
+		log('Registered rule %s for %s (phase: %s, priority: %d)',
+			handle.id, handle.nodeType, handle.phase, priority);
+	}
+
+	/**
+	 * Get all rules for a specific node type
+	 */
+	rulesFor(nodeType: PlanNodeType): readonly RuleHandle[] {
+		return this.rules.get(nodeType) ?? [];
+	}
+
+	/**
+	 * Check if a rule has already been applied to a node
+	 */
+	hasRuleBeenApplied(nodeId: string, ruleId: string): boolean {
+		const nodeVisited = this.visitedRules.get(nodeId);
+		return nodeVisited?.has(ruleId) ?? false;
+	}
+
+	/**
+	 * Mark a rule as applied to a node
+	 */
+	markRuleApplied(nodeId: string, ruleId: string): void {
+		if (!this.visitedRules.has(nodeId)) {
+			this.visitedRules.set(nodeId, new Set());
+		}
+		this.visitedRules.get(nodeId)!.add(ruleId);
+	}
+
+	/**
+	 * Clear visited rules (typically called at start of optimization)
+	 */
+	clearVisitedRules(): void {
+		this.visitedRules.clear();
+	}
+
+	/**
+	 * Get all registered rules (for debugging)
+	 */
+	getAllRules(): Map<PlanNodeType, readonly RuleHandle[]> {
+		const result = new Map<PlanNodeType, readonly RuleHandle[]>();
+		for (const [nodeType, rules] of this.rules) {
+			result.set(nodeType, [...rules]);
+		}
+		return result;
+	}
+
+	/**
+	 * Get statistics about rule application
+	 */
+	getStats(): { totalRules: number; nodesWithRules: number; appliedRules: number } {
+		let totalRules = 0;
+		for (const rules of this.rules.values()) {
+			totalRules += rules.length;
+		}
+
+		let appliedRules = 0;
+		for (const ruleSet of this.visitedRules.values()) {
+			appliedRules += ruleSet.size;
+		}
+
+		return {
+			totalRules,
+			nodesWithRules: this.visitedRules.size,
+			appliedRules
+		};
+	}
+}
+
+/**
+ * Global registry instance
+ */
+const globalRegistry = new RuleRegistry();
+
+/**
+ * Register an optimization rule
+ */
+export function registerRule(handle: RuleHandle): void {
+	globalRegistry.registerRule(handle);
+}
+
+/**
+ * Get rules for a specific node type
+ */
+export function rulesFor(nodeType: PlanNodeType): readonly RuleHandle[] {
+	return globalRegistry.rulesFor(nodeType);
+}
+
+/**
+ * Check if a rule has been applied to a node
+ */
+export function hasRuleBeenApplied(nodeId: string, ruleId: string): boolean {
+	return globalRegistry.hasRuleBeenApplied(nodeId, ruleId);
+}
+
+/**
+ * Mark a rule as applied to a node
+ */
+export function markRuleApplied(nodeId: string, ruleId: string): void {
+	globalRegistry.markRuleApplied(nodeId, ruleId);
+}
+
+/**
+ * Clear all visited rule tracking
+ */
+export function clearVisitedRules(): void {
+	globalRegistry.clearVisitedRules();
+}
+
+/**
+ * Get registry statistics
+ */
+export function getRegistryStats(): { totalRules: number; nodesWithRules: number; appliedRules: number } {
+	return globalRegistry.getStats();
+}
+
+/**
+ * Get all registered rules (for debugging/tooling)
+ */
+export function getAllRules(): Map<PlanNodeType, readonly RuleHandle[]> {
+	return globalRegistry.getAllRules();
+}
+
+/**
+ * Apply rules to a node with tracing and loop detection
+ */
+export function applyRules(node: PlanNode, context: OptContext): PlanNode {
+	const applicableRules = rulesFor(node.nodeType);
+
+	if (applicableRules.length === 0) {
+		return node;
+	}
+
+	let currentNode = node;
+	let appliedAnyRule = false;
+
+	for (const rule of applicableRules) {
+		// Skip if rule already applied to this node
+		if (hasRuleBeenApplied(currentNode.id, rule.id)) {
+			log('Skipping rule %s for node %s (already applied)', rule.id, currentNode.id);
+			continue;
+		}
+
+		try {
+			const ruleLog = createLogger(`optimizer:rule:${rule.id}`);
+
+			// Trace rule start
+			traceRuleStart(rule, currentNode);
+			ruleLog('Applying rule to node %s', currentNode.id);
+
+			const result = rule.fn(currentNode, context);
+
+						if (result && result !== currentNode) {
+				ruleLog('Rule transformed %s to %s', currentNode.nodeType, result.nodeType);
+				markRuleApplied(currentNode.id, rule.id);
+
+				// Trace successful transformation
+				traceRuleEnd(rule, currentNode, result);
+
+				currentNode = result;
+				appliedAnyRule = true;
+			} else {
+				ruleLog('Rule not applicable to node %s', currentNode.id);
+
+				// Trace rule not applicable
+				traceRuleEnd(rule, currentNode, null);
+			}
+		} catch (error) {
+			const errorMsg = error instanceof Error ? error.message : String(error);
+			log('Rule %s failed on node %s: %s', rule.id, currentNode.id, errorMsg);
+			// Continue with other rules rather than failing entire optimization
+		}
+	}
+
+	if (appliedAnyRule) {
+		log('Applied rules to node %s, result: %s', node.id, currentNode.nodeType);
+	}
+
+	return currentNode;
+}
+
+/**
+ * Convenience function to register multiple rules at once
+ */
+export function registerRules(rules: RuleHandle[]): void {
+	for (const rule of rules) {
+		registerRule(rule);
+	}
+}
+
+/**
+ * Helper to create rule handles with common patterns
+ */
+export function createRule(
+	id: string,
+	nodeType: PlanNodeType,
+	phase: RulePhase,
+	fn: RuleFn,
+	priority?: number
+): RuleHandle {
+	return { id, nodeType, phase, fn, priority };
+}