@quereus/quereus 0.2.1 → 0.4.5

package/src/planner/framework/pass.ts

@@ -0,0 +1,354 @@
+/**
+ * Optimization pass framework for multi-pass query optimization
+ *
+ * This framework enables rules to run in separate tree traversals,
+ * allowing for proper sequencing of transformations that require
+ * different traversal orders or multiple passes over the tree.
+ */
+
+import type { PlanNode } from '../nodes/plan-node.js';
+import type { OptContext } from './context.js';
+import type { RuleHandle } from './registry.js';
+import { createLogger } from '../../common/logger.js';
+import { performConstantFolding } from '../analysis/const-pass.js';
+import { createRuntimeExpressionEvaluator } from '../analysis/const-evaluator.js';
+
+const log = createLogger('optimizer:framework:pass');
+
+/**
+ * Traversal order for optimization passes
+ */
+export enum TraversalOrder {
+	/** Process children before parents */
+	BottomUp = 'bottom-up',
+	/** Process parents before children */
+	TopDown = 'top-down',
+}
+
+/**
+ * Definition of an optimization pass
+ */
+export interface OptimizationPass {
+	/** Unique identifier for this pass */
+	id: string;
+
+	/** Human-readable name for logging */
+	name: string;
+
+	/** Description of what this pass does */
+	description: string;
+
+	/** Traversal order for this pass */
+	traversalOrder: TraversalOrder;
+
+	/** Rules that belong to this pass (will be populated by registration) */
+	rules: RuleHandle[];
+
+	/** Optional custom execution logic (default uses standard rule application) */
+	execute?: (plan: PlanNode, context: OptContext) => PlanNode;
+
+	/** Whether this pass is enabled (default: true) */
+	enabled?: boolean;
+
+	/** Order in which passes execute (lower numbers first) */
+	order: number;
+}
+
+/**
+ * Standard optimization passes
+ */
+export enum PassId {
+	/** Pre-optimization constant folding */
+	ConstantFolding = 'constant-folding',
+
+	/** Structural transformations (pushdown, pullup, boundary sliding) */
+	Structural = 'structural',
+
+	/** Physical operator selection and implementation */
+	Physical = 'physical',
+
+	/** Post-optimization cleanup and caching */
+	PostOptimization = 'post-opt',
+
+	/** Final validation */
+	Validation = 'validation',
+}
+
+/**
+ * Create a standard optimization pass
+ */
+export function createPass(
+	id: string,
+	name: string,
+	description: string,
+	order: number,
+	traversalOrder: TraversalOrder = TraversalOrder.BottomUp
+): OptimizationPass {
+	return {
+		id,
+		name,
+		description,
+		traversalOrder,
+		rules: [],
+		enabled: true,
+		order
+	};
+}
+
+/**
+ * Create constant folding pass with custom execution
+ */
+function createConstantFoldingPass(): OptimizationPass {
+	return {
+		id: PassId.ConstantFolding,
+		name: 'Constant Folding',
+		description: 'Pre-evaluate constant expressions and fold them into the plan',
+		traversalOrder: TraversalOrder.BottomUp,
+		rules: [],
+		enabled: true,
+		order: 0,
+		execute: (plan: PlanNode, context: OptContext) => {
+			// Custom execution for constant folding
+			const evaluator = createRuntimeExpressionEvaluator(context.db);
+			const result = performConstantFolding(plan, evaluator);
+			log('Constant folding completed');
+			return result;
+		}
+	};
+}
+
+/**
+ * Standard pass definitions
+ */
+export const STANDARD_PASSES: OptimizationPass[] = [
+	createConstantFoldingPass(),
+
+	createPass(
+		PassId.Structural,
+		'Structural Transformations',
+		'Restructure the plan tree for optimal execution boundaries',
+		10,
+		TraversalOrder.TopDown
+	),
+
+	createPass(
+		PassId.Physical,
+		'Physical Selection',
+		'Convert logical operators to physical implementations',
+		20,
+		TraversalOrder.BottomUp
+	),
+
+	createPass(
+		PassId.PostOptimization,
+		'Post-Optimization',
+		'Final cleanup, materialization decisions, and caching',
+		30,
+		TraversalOrder.BottomUp
+	),
+
+	createPass(
+		PassId.Validation,
+		'Validation',
+		'Validate the correctness of the optimized plan',
+		40,
+		TraversalOrder.BottomUp
+	),
+];
+
+/**
+ * Pass manager for coordinating multi-pass optimization
+ */
+export class PassManager {
+	private passes: Map<string, OptimizationPass> = new Map();
+	private sortedPasses: OptimizationPass[] = [];
+
+	constructor() {
+		// Register standard passes
+		for (const pass of STANDARD_PASSES) {
+			this.registerPass(pass);
+		}
+	}
+
+	/**
+	 * Register an optimization pass
+	 */
+	registerPass(pass: OptimizationPass): void {
+		if (this.passes.has(pass.id)) {
+			log('Warning: Overwriting existing pass %s', pass.id);
+		}
+
+		this.passes.set(pass.id, pass);
+		this.updateSortedPasses();
+
+		log('Registered pass %s (order: %d, traversal: %s)',
+			pass.id, pass.order, pass.traversalOrder);
+	}
+
+	/**
+	 * Get a pass by ID
+	 */
+	getPass(id: string): OptimizationPass | undefined {
+		return this.passes.get(id);
+	}
+
+	/**
+	 * Add a rule to a specific pass
+	 */
+	addRuleToPass(passId: string, rule: RuleHandle): void {
+		const pass = this.passes.get(passId);
+		if (!pass) {
+			throw new Error(`Unknown pass: ${passId}`);
+		}
+
+		// Avoid duplicate registrations by rule ID within a pass
+		if (pass.rules.some(r => r.id === rule.id)) {
+			log('Skipping duplicate rule %s for pass %s', rule.id, passId);
+			return;
+		}
+
+		pass.rules.push(rule);
+		log('Added rule %s to pass %s', rule.id, passId);
+	}
+
+	/**
+	 * Get all passes in execution order
+	 */
+	getPasses(): readonly OptimizationPass[] {
+		return this.sortedPasses;
+	}
+
+	/**
+	 * Update sorted pass list after changes
+	 */
+	private updateSortedPasses(): void {
+		this.sortedPasses = Array.from(this.passes.values())
+			.filter(pass => pass.enabled !== false)
+			.sort((a, b) => a.order - b.order);
+	}
+
+	/**
+	 * Execute all passes on a plan
+	 */
+	execute(plan: PlanNode, context: OptContext): PlanNode {
+		return this.executeUpTo(plan, context);
+	}
+
+	/**
+	 * Execute passes up to and including the specified pass id
+	 */
+	executeUpTo(plan: PlanNode, context: OptContext, upToPassId?: string): PlanNode {
+		let currentPlan = plan;
+		for (const pass of this.sortedPasses) {
+			log('Starting pass: %s', pass.name);
+
+			if (pass.execute) {
+				// Custom execution logic
+				currentPlan = pass.execute(currentPlan, context);
+			} else {
+				// Standard rule-based execution
+				currentPlan = this.executeStandardPass(currentPlan, context, pass);
+			}
+
+			log('Completed pass: %s', pass.name);
+			if (upToPassId && pass.id === upToPassId) break;
+		}
+		return currentPlan;
+	}
+
+	/**
+	 * Execute a standard rule-based pass
+	 */
+	private executeStandardPass(
+		plan: PlanNode,
+		context: OptContext,
+		pass: OptimizationPass
+	): PlanNode {
+		// This will be implemented to traverse the tree in the specified order
+		// and apply the pass's rules at each node
+
+		if (pass.traversalOrder === TraversalOrder.TopDown) {
+			return this.traverseTopDown(plan, context, pass);
+		} else {
+			return this.traverseBottomUp(plan, context, pass);
+		}
+	}
+
+	/**
+	 * Top-down traversal with rule application
+	 */
+	private traverseTopDown(
+		node: PlanNode,
+		context: OptContext,
+		pass: OptimizationPass
+	): PlanNode {
+		// Apply rules to this node first
+		let currentNode = this.applyPassRules(node, context, pass);
+
+		// Then traverse children
+		const children = currentNode.getChildren();
+		if (children.length > 0) {
+			const newChildren = children.map(child =>
+				this.traverseTopDown(child, context, pass)
+			);
+
+			// Only create new node if children changed
+			const childrenChanged = children.some((child, i) => child !== newChildren[i]);
+			if (childrenChanged) {
+				currentNode = currentNode.withChildren(newChildren);
+			}
+		}
+
+		return currentNode;
+	}
+
+	/**
+	 * Bottom-up traversal with rule application
+	 */
+	private traverseBottomUp(
+		node: PlanNode,
+		context: OptContext,
+		pass: OptimizationPass
+	): PlanNode {
+		// Traverse children first
+		const children = node.getChildren();
+		let currentNode = node;
+
+		if (children.length > 0) {
+			const newChildren = children.map(child =>
+				this.traverseBottomUp(child, context, pass)
+			);
+
+			// Only create new node if children changed
+			const childrenChanged = children.some((child, i) => child !== newChildren[i]);
+			if (childrenChanged) {
+				currentNode = currentNode.withChildren(newChildren);
+			}
+		}
+
+		// Then apply rules to this node
+		return this.applyPassRules(currentNode, context, pass);
+	}
+
+	/**
+	 * Apply all rules in a pass to a node
+	 */
+	private applyPassRules(
+		node: PlanNode,
+		context: OptContext,
+		pass: OptimizationPass
+	): PlanNode {
+		let currentNode = node;
+		// Apply rules against the current node type only
+		for (const rule of pass.rules) {
+			if (rule.nodeType !== currentNode.nodeType) continue;
+			const result = rule.fn(currentNode, context);
+			if (result && result !== currentNode) {
+				log('Rule %s transformed node in pass %s', rule.id, pass.id);
+				currentNode = result;
+			}
+		}
+
+		return currentNode;
+	}
+}

package/src/planner/nodes/aggregate-node.ts

@@ -1,11 +1,13 @@
 import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode } from './plan-node.js';
+import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode, type PhysicalProperties } from './plan-node.js';
+import { ColumnReferenceNode } from './reference.js';
 import type { RelationType } from '../../common/datatype.js';
 import type { Scope } from '../scopes/scope.js';
 import { Cached } from '../../util/cached.js';
 import { formatExpressionList } from '../../util/plan-formatter.js';
 import { StatusCode } from '../../common/types.js';
 import { quereusError } from '../../common/errors.js';
+import type { AggregationCapable } from '../framework/characteristics.js';
 
 export interface AggregateExpression {
   expression: ScalarPlanNode;
@@ -13,11 +15,10 @@ export interface AggregateExpression {
 }
 
 /**
- * Represents an aggregation operation.
- * It takes an input relation and applies aggregate functions,
- * optionally grouping by specified expressions.
+ * Logical node representing an aggregate operation.
+ * Requires transformation to StreamAggregateNode or HashAggregateNode by optimizer.
  */
-export class AggregateNode extends PlanNode implements UnaryRelationalNode {
+export class AggregateNode extends PlanNode implements UnaryRelationalNode, AggregationCapable {
   override readonly nodeType = PlanNodeType.Aggregate;
 
   private outputTypeCache: Cached<RelationType>;
@@ -41,7 +42,7 @@ export class AggregateNode extends PlanNode implements UnaryRelationalNode {
   private getGroupByColumnName(expr: ScalarPlanNode, index: number): string {
     // If it's a column reference, use the column name
     if (expr.nodeType === PlanNodeType.ColumnReference) {
-      const colRef = expr as any; // ColumnReferenceNode
+      const colRef = expr as ColumnReferenceNode;
       return colRef.expression.name;
     }
     // Otherwise, use a generic name
@@ -118,7 +119,7 @@ export class AggregateNode extends PlanNode implements UnaryRelationalNode {
     return this.outputTypeCache.value;
   }
 
-  getAttributes(): Attribute[] {
+  getAttributes(): readonly Attribute[] {
     return this.attributesCache.value;
   }
 
@@ -186,6 +187,19 @@ export class AggregateNode extends PlanNode implements UnaryRelationalNode {
     }
   }
 
+  computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+    const sourcePhysical = childrenPhysical[0];
+    const groupCount = this.groupBy.length;
+    // If there is a GROUP BY, the group-by columns form a unique key on the output
+    // Output attribute indices for group-by are 0..groupCount-1 per buildAttributes
+    const uniqueKeys = groupCount > 0 ? [Array.from({ length: groupCount }, (_, i) => i)] : [[]];
+    return {
+      uniqueKeys,
+      estimatedRows: this.estimatedRows,
+      ordering: sourcePhysical?.ordering,
+    };
+  }
+
   override toString(): string {
     const parts: string[] = [];
 
@@ -217,6 +231,37 @@ export class AggregateNode extends PlanNode implements UnaryRelationalNode {
       }));
     }
 
+    // Expose logical unique keys: group-by columns (0..groupCount-1) or [[]] for global aggregate
+    const groupCount = this.groupBy.length;
+    (props as any).uniqueKeys = groupCount > 0 ? [Array.from({ length: groupCount }, (_, i) => i)] : [[]];
     return props;
   }
+
+  // AggregationCapable interface implementation
+  getGroupingKeys(): readonly ScalarPlanNode[] {
+    return this.groupBy;
+  }
+
+  getAggregateExpressions(): readonly { expr: ScalarPlanNode; alias: string; attributeId: number }[] {
+    const attributes = this.getAttributes();
+    const groupByCount = this.groupBy.length;
+
+    return this.aggregates.map((agg, index) => ({
+      expr: agg.expression,
+      alias: agg.alias,
+      attributeId: attributes[groupByCount + index].id
+    }));
+  }
+
+  requiresOrdering(): boolean {
+    return this.groupBy.length > 0; // Only requires ordering if we have GROUP BY
+  }
+
+  canStreamAggregate(): boolean {
+    return true; // AggregateNode can always be converted to streaming
+  }
+
+	getSource(): RelationalPlanNode {
+		return this.source;
+	}
 }

package/src/planner/nodes/array-index-node.ts

@@ -22,7 +22,7 @@ export class ArrayIndexNode extends PlanNode implements ZeroAryScalarNode {
 		this.expression = {
 			type: 'literal',
 			value: `[${index}]`
-		} as AST.LiteralExpr;
+		} satisfies AST.LiteralExpr;
 	}
 
 	getType(): ScalarType {

package/src/planner/nodes/cache-node.ts

@@ -4,6 +4,7 @@ import type { RelationType } from '../../common/datatype.js';
 import type { Scope } from '../scopes/scope.js';
 import { StatusCode } from '../../common/types.js';
 import { quereusError } from '../../common/errors.js';
+import type { CacheCapable } from '../framework/characteristics.js';
 
 export type CacheStrategy = 'memory' | 'spill'; // Future: spill-to-disk
 
@@ -14,7 +15,7 @@ export type CacheStrategy = 'memory' | 'spill'; // Future: spill-to-disk
  * subsequent iterations from the cached result. It implements
  * smart threshold-based policies to avoid excessive memory usage.
  */
-export class CacheNode extends PlanNode implements UnaryRelationalNode {
+export class CacheNode extends PlanNode implements UnaryRelationalNode, CacheCapable {
 	readonly nodeType = PlanNodeType.Cache;
 
 	constructor(
@@ -28,7 +29,7 @@ export class CacheNode extends PlanNode implements UnaryRelationalNode {
 	}
 
 	// Cache preserves source attributes exactly
-	getAttributes(): Attribute[] {
+	getAttributes(): readonly Attribute[] {
 		return this.source.getAttributes();
 	}
 
@@ -80,6 +81,14 @@ export class CacheNode extends PlanNode implements UnaryRelationalNode {
 		return this.source.estimatedRows;
 	}
 
+	getCacheStrategy(): string {
+		return this.strategy;
+	}
+
+	isCached(): boolean {
+		return true;
+	}
+
 	override toString(): string {
 		return `CACHE (${this.strategy}, threshold=${this.threshold})`;
 	}

package/src/planner/nodes/constraint-check-node.ts

@@ -1,5 +1,5 @@
 import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor, type ScalarPlanNode, isRelationalNode } from './plan-node.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor, type ScalarPlanNode, isRelationalNode, isScalarNode } from './plan-node.js';
 import { PlanNodeType } from './plan-node-type.js';
 import type { TableReferenceNode } from './reference.js';
 import type { RelationType } from '../../common/datatype.js';
@@ -9,6 +9,9 @@ import type { RowConstraintSchema } from '../../schema/table.js';
 export interface ConstraintCheck {
   constraint: RowConstraintSchema;  // The constraint metadata
   expression: ScalarPlanNode;       // Pre-built expression node
+  deferrable?: boolean;
+  initiallyDeferred?: boolean;
+  containsSubquery: boolean;        // Cached result of subquery detection
 }
 
 /**
@@ -26,7 +29,10 @@ export class ConstraintCheckNode extends PlanNode implements RelationalPlanNode
     public readonly oldRowDescriptor: RowDescriptor | undefined,
     public readonly newRowDescriptor: RowDescriptor | undefined,
     public readonly flatRowDescriptor: RowDescriptor,
-    public readonly constraintChecks: ConstraintCheck[]
+    public readonly constraintChecks: ConstraintCheck[],
+    public readonly mutationContextValues?: Map<string, ScalarPlanNode>, // Mutation context value expressions
+    public readonly contextAttributes?: Attribute[], // Mutation context attributes
+    public readonly contextDescriptor?: RowDescriptor, // Mutation context row descriptor
   ) {
     super(scope);
   }
@@ -35,7 +41,7 @@ export class ConstraintCheckNode extends PlanNode implements RelationalPlanNode
     return this.source.getType();
   }
 
-  getAttributes(): Attribute[] {
+  getAttributes(): readonly Attribute[] {
     // ConstraintCheck passes through the same attributes as its source
     return this.source.getAttributes();
   }
@@ -69,7 +75,7 @@ export class ConstraintCheckNode extends PlanNode implements RelationalPlanNode
     // Type check constraint expressions
     for (let i = 0; i < newConstraintExprs.length; i++) {
       const expr = newConstraintExprs[i];
-      if (!('getType' in expr) || typeof (expr as any).getType !== 'function') {
+      if (!isScalarNode(expr)) {
         throw new Error(`ConstraintCheckNode: constraint child ${i + 1} must be a ScalarPlanNode`);
       }
     }
@@ -95,7 +101,10 @@ export class ConstraintCheckNode extends PlanNode implements RelationalPlanNode
       this.oldRowDescriptor,
       this.newRowDescriptor,
       this.flatRowDescriptor,
-      newConstraintChecks
+      newConstraintChecks,
+      this.mutationContextValues,
+      this.contextAttributes,
+      this.contextDescriptor
     );
   }
 

package/src/planner/nodes/create-assertion-node.ts

@@ -0,0 +1,51 @@
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type VoidNode, type PhysicalProperties } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { VoidType } from '../../common/datatype.js';
+import type * as AST from '../../parser/ast.js';
+
+/**
+ * Represents creating a global integrity assertion.
+ * This is a DDL operation that adds an assertion to the schema.
+ */
+export class CreateAssertionNode extends PlanNode implements VoidNode {
+  override readonly nodeType = PlanNodeType.CreateAssertion;
+
+  constructor(
+    scope: Scope,
+    public readonly name: string,
+    public readonly checkExpression: AST.Expression,
+  ) {
+    super(scope);
+  }
+
+  getType(): VoidType {
+    return { typeClass: 'void' };
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return [];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 0) {
+      throw new Error(`CreateAssertionNode expects 0 children, got ${newChildren.length}`);
+    }
+    return this; // No children, so no change
+  }
+
+  override toString(): string {
+    return `CREATE ASSERTION ${this.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      name: this.name,
+      checkExpression: this.checkExpression.toString?.() || 'complex expression',
+    };
+  }
+
+  override computePhysical(_children: readonly PhysicalProperties[]): Partial<PhysicalProperties> {
+    return { readonly: false };
+  }
+}

package/src/planner/nodes/create-index-node.ts

@@ -2,7 +2,7 @@ import type * as AST from '../../parser/ast.js';
 import type { Scope } from '../scopes/scope.js';
 import { PhysicalProperties, VoidNode } from './plan-node.js';
 import { PlanNodeType } from './plan-node-type.js';
-import { expressionToString } from '../../util/ast-stringify.js';
+import { astToString, expressionToString } from '../../util/ast-stringify.js';
 
 /**
  * Represents a CREATE INDEX statement in the logical query plan.
@@ -31,7 +31,7 @@ export class CreateIndexNode extends VoidNode {
       ifNotExists: this.statementAst.ifNotExists,
       columns: this.statementAst.columns.map(col => col.name || expressionToString(col.expr!)),
       hasWhereClause: !!this.statementAst.where,
-      statement: expressionToString(this.statementAst as any) // Convert AST to string
+      statement: astToString(this.statementAst)
     };
   }
 

package/src/planner/nodes/create-table-node.ts

@@ -2,7 +2,7 @@ import type * as AST from '../../parser/ast.js';
 import type { Scope } from '../scopes/scope.js';
 import { PhysicalProperties, VoidNode } from './plan-node.js';
 import { PlanNodeType } from './plan-node-type.js';
-import { expressionToString } from '../../util/ast-stringify.js';
+import { astToString } from '../../util/ast-stringify.js';
 
 /**
  * Represents a CREATE TABLE statement in the logical query plan.
@@ -25,7 +25,7 @@ export class CreateTableNode extends VoidNode {
     return {
       table: this.statementAst.table.name,
       schema: this.statementAst.table.schema,
-      statement: expressionToString(this.statementAst as any) // Convert AST to string
+      statement: astToString(this.statementAst)
     };
   }