@quereus/quereus 0.1.0 → 0.2.1

package/src/planner/rules/access/rule-select-access-path.ts

@@ -1,7 +1,7 @@
 /**
  * Rule: Select Access Path
  *
- * Transforms: TableScanNode → SeqScanNode | IndexScanNode | IndexSeekNode
+ * Transforms: TableReferenceNode → SeqScanNode | IndexScanNode | IndexSeekNode
  * Conditions: When logical table access needs to be made physical
  * Benefits: Enables cost-based access path selection and index utilization
  */
@@ -9,39 +9,36 @@
 import { createLogger } from '../../../common/logger.js';
 import type { PlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
-import { TableScanNode } from '../../nodes/scan.js';
-import { SeqScanNode, IndexScanNode, IndexSeekNode } from '../../nodes/physical-access-nodes.js';
+import { TableReferenceNode } from '../../nodes/reference.js';
+import { SeqScanNode, IndexScanNode, IndexSeekNode } from '../../nodes/table-access-nodes.js';
 import { seqScanCost } from '../../cost/index.js';
-import type { ColumnMeta, PredicateConstraint, BestAccessPlanRequest, BestAccessPlanResult, ConstraintOp } from '../../../vtab/best-access-plan.js';
+import type { ColumnMeta, PredicateConstraint, BestAccessPlanRequest, BestAccessPlanResult } from '../../../vtab/best-access-plan.js';
+import { FilterInfo } from '../../../vtab/filter-info.js';
+import type { IndexConstraintUsage } from '../../../vtab/index-info.js';
 
 const log = createLogger('optimizer:rule:select-access-path');
 
 export function ruleSelectAccessPath(node: PlanNode, context: OptContext): PlanNode | null {
-	// Guard: only apply to TableScanNode
-	if (!(node instanceof TableScanNode)) {
+	// Guard: only apply to TableReferenceNode
+	if (!(node instanceof TableReferenceNode)) {
 		return null;
 	}
 
-	// Guard: already physical
-	if (node.physical) {
-		return null;
-	}
-
-	log('Selecting access path for table %s', node.source.tableSchema.name);
+	log('Selecting access path for table %s', node.tableSchema.name);
 
 	try {
 		// Get table schema and virtual table module
-		const tableSchema = node.source.tableSchema;
+		const tableSchema = node.tableSchema;
 		const vtabModule = tableSchema.vtabModule;
 
 		// If no virtual table module, fall back to sequential scan
 		if (!vtabModule || typeof vtabModule !== 'object' || !('getBestAccessPlan' in vtabModule)) {
 			log('No getBestAccessPlan support, using sequential scan for %s', tableSchema.name);
-			return createSeqScan(node);
+			return createSeqScan(node, undefined);
 		}
 
 		// Extract constraints from current filter info
-		const constraints = extractConstraintsFromFilterInfo(node, tableSchema);
+		const constraints: PredicateConstraint[] = []; // TODO: Extract from parent Filter node if any
 
 		// Build request for getBestAccessPlan
 		const request: BestAccessPlanRequest = {
@@ -53,7 +50,7 @@ export function ruleSelectAccessPath(node: PlanNode, context: OptContext): PlanN
 				isUnique: col.primaryKey || false // For now, assume only PK columns are unique
 			} as ColumnMeta)),
 			filters: constraints,
-			estimatedRows: node.source.estimatedRows
+			estimatedRows: node.estimatedRows
 		};
 
 		// Call getBestAccessPlan
@@ -68,58 +65,43 @@ export function ruleSelectAccessPath(node: PlanNode, context: OptContext): PlanN
 		return physicalNode;
 
 	} catch (error) {
-		log('Error selecting access path for %s: %s', node.source.tableSchema.name, error);
+		log('Error selecting access path for %s: %s', node.tableSchema.name, error);
 		// Fall back to sequential scan on error
 		return createSeqScan(node);
 	}
 }
 
-/**
- * Extract predicate constraints from FilterInfo
- */
-function extractConstraintsFromFilterInfo(node: TableScanNode, _tableSchema: any): PredicateConstraint[] {
-	const constraints: PredicateConstraint[] = [];
-
-	// Extract from FilterInfo.indexInfoOutput.aConstraint if available
-	const indexConstraints = node.filterInfo.indexInfoOutput.aConstraint;
-	if (indexConstraints) {
-		for (let i = 0; i < indexConstraints.length; i++) {
-			const constraint = indexConstraints[i];
-
-			if (constraint && constraint.usable) {
-				constraints.push({
-					columnIndex: constraint.iColumn,
-					op: mapConstraintOp(constraint.op),
-					usable: constraint.usable,
-					// Note: actual value would need to be extracted from args
-					value: undefined
-				});
-			}
-		}
-	}
-
-	return constraints;
-}
-
-/**
- * Map internal constraint op to public constraint op
- */
-function mapConstraintOp(_internalOp: number): ConstraintOp {
-	// This mapping would need to be based on the actual constants used
-	// For now, assume equality - in a real implementation this would map
-	// from IndexConstraintOp constants to ConstraintOp
-	return '=';
-}
-
 /**
  * Select the appropriate physical node based on access plan
  */
 function selectPhysicalNode(
-	originalNode: TableScanNode,
+	originalNode: TableReferenceNode,
 	accessPlan: BestAccessPlanResult,
 	constraints: PredicateConstraint[]
 ): SeqScanNode | IndexScanNode | IndexSeekNode {
 
+	// Create a default FilterInfo for the physical nodes
+	const filterInfo: FilterInfo = {
+		idxNum: 0,
+		idxStr: 'fullscan',
+		constraints: [],
+		args: [],
+		indexInfoOutput: {
+			nConstraint: 0,
+			aConstraint: [],
+			nOrderBy: 0,
+			aOrderBy: [],
+			aConstraintUsage: [] as IndexConstraintUsage[],
+			idxNum: 0,
+			idxStr: 'fullscan',
+			orderByConsumed: false,
+			estimatedCost: accessPlan.cost,
+			estimatedRows: BigInt(accessPlan.rows || 1000),
+			idxFlags: 0,
+			colUsed: 0n,
+		}
+	};
+
 	// Analyze the access plan to determine node type
 	const hasEqualityConstraints = constraints.some(c => c.op === '=' && accessPlan.handledFilters[constraints.indexOf(c)]);
 	const hasRangeConstraints = constraints.some(c => ['>', '>=', '<', '<='].includes(c.op) && accessPlan.handledFilters[constraints.indexOf(c)]);
@@ -136,8 +118,8 @@ function selectPhysicalNode(
 		log('Using index seek (equality constraint, small result)');
 		return new IndexSeekNode(
 			originalNode.scope,
-			originalNode.source,
-			originalNode.filterInfo,
+			originalNode,
+			filterInfo,
 			'primary', // Default to primary index
 			[], // seekKeys would be populated from constraints
 			false, // not a range
@@ -149,8 +131,8 @@ function selectPhysicalNode(
 		log('Using index scan (range constraints or ordering)');
 		return new IndexScanNode(
 			originalNode.scope,
-			originalNode.source,
-			originalNode.filterInfo,
+			originalNode,
+			filterInfo,
 			'primary', // Default to primary index
 			providesOrdering,
 			accessPlan.cost
@@ -158,21 +140,43 @@ function selectPhysicalNode(
 	} else {
 		// Fall back to sequential scan
 		log('Using sequential scan (no beneficial index access)');
-		return createSeqScan(originalNode, accessPlan.cost);
+		return createSeqScan(originalNode, filterInfo, accessPlan.cost);
 	}
 }
 
 /**
  * Create a sequential scan node
  */
-function createSeqScan(originalNode: TableScanNode, cost?: number): SeqScanNode {
-	const tableRows = originalNode.source.estimatedRows || 1000;
+function createSeqScan(originalNode: TableReferenceNode, filterInfo?: FilterInfo, cost?: number): SeqScanNode {
+	const tableRows = originalNode.estimatedRows || 1000;
 	const scanCost = cost ?? seqScanCost(tableRows);
 
+	// Create default FilterInfo if not provided
+	const effectiveFilterInfo = filterInfo || {
+		idxNum: 0,
+		idxStr: 'fullscan',
+		constraints: [],
+		args: [],
+		indexInfoOutput: {
+			nConstraint: 0,
+			aConstraint: [],
+			nOrderBy: 0,
+			aOrderBy: [],
+			aConstraintUsage: [] as IndexConstraintUsage[],
+			idxNum: 0,
+			idxStr: 'fullscan',
+			orderByConsumed: false,
+			estimatedCost: scanCost,
+			estimatedRows: BigInt(tableRows),
+			idxFlags: 0,
+			colUsed: 0n,
+		}
+	};
+
 	const seqScan = new SeqScanNode(
 		originalNode.scope,
-		originalNode.source,
-		originalNode.filterInfo,
+		originalNode,
+		effectiveFilterInfo,
 		scanCost
 	);
 

package/src/planner/rules/aggregate/rule-aggregate-streaming.ts

@@ -42,13 +42,49 @@ export function ruleAggregateStreaming(node: PlanNode, _context: OptContext): Pl
 
 		const sortNode = new SortNode(node.scope, source, sortKeys);
 
+		// Create combined attributes: AggregateNode attributes + source attributes
+		// This ensures both GROUP BY/aggregate AND source column attribute IDs are preserved
+		const aggregateAttrs = node.getAttributes();
+		const sourceAttrs = node.source.getAttributes();
+
+		// Deduplicate by column NAME to avoid duplicate columns like 'id'
+		// (The same logical column can have different attribute IDs between aggregate and source)
+		const seenNames = new Set<string>();
+		const combinedAttrs: typeof aggregateAttrs = [];
+
+		// Add aggregate attributes first (GROUP BY + aggregates)
+		for (const attr of aggregateAttrs) {
+			combinedAttrs.push(attr);
+			seenNames.add(attr.name);
+		}
+
+		// Add source attributes that aren't already present by name
+		for (const attr of sourceAttrs) {
+			if (!seenNames.has(attr.name)) {
+				combinedAttrs.push(attr);
+				seenNames.add(attr.name);
+			}
+		}
+
+		// Final safety-pass: filter duplicates that may have slipped through
+		const uniqueByName = new Set<string>();
+		const deduped: typeof combinedAttrs = [];
+		for (const attr of combinedAttrs) {
+			if (!uniqueByName.has(attr.name)) {
+				deduped.push(attr);
+				uniqueByName.add(attr.name);
+			}
+		}
+
+		const finalAttrs = deduped;
+
 		const result = new StreamAggregateNode(
 			node.scope,
 			sortNode,
 			node.groupBy,
 			node.aggregates,
 			undefined, // estimatedCostOverride
-			node.getAttributes() // **CRITICAL**: Preserve original attribute IDs
+			finalAttrs // unique list
 		);
 
 		// Let framework set physical properties via markPhysical()
@@ -58,13 +94,49 @@ export function ruleAggregateStreaming(node: PlanNode, _context: OptContext): Pl
 		return result;
 	} else {
 		// No GROUP BY - can stream aggregate without sorting
+		// Create combined attributes: AggregateNode attributes + source attributes
+		// This ensures both GROUP BY/aggregate AND source column attribute IDs are preserved
+		const aggregateAttrs = node.getAttributes();
+		const sourceAttrs = node.source.getAttributes();
+
+		// Deduplicate by column NAME to avoid duplicate columns like 'id'
+		// (The same logical column can have different attribute IDs between aggregate and source)
+		const seenNames = new Set<string>();
+		const combinedAttrs: typeof aggregateAttrs = [];
+
+		// Add aggregate attributes first (GROUP BY + aggregates)
+		for (const attr of aggregateAttrs) {
+			combinedAttrs.push(attr);
+			seenNames.add(attr.name);
+		}
+
+		// Add source attributes that aren't already present by name
+		for (const attr of sourceAttrs) {
+			if (!seenNames.has(attr.name)) {
+				combinedAttrs.push(attr);
+				seenNames.add(attr.name);
+			}
+		}
+
+		// Final safety-pass: filter duplicates that may have slipped through
+		const uniqueByName = new Set<string>();
+		const deduped: typeof combinedAttrs = [];
+		for (const attr of combinedAttrs) {
+			if (!uniqueByName.has(attr.name)) {
+				deduped.push(attr);
+				uniqueByName.add(attr.name);
+			}
+		}
+
+		const finalAttrs = deduped;
+
 		const result = new StreamAggregateNode(
 			node.scope,
 			source,
 			node.groupBy,
 			node.aggregates,
 			undefined, // estimatedCostOverride
-			node.getAttributes() // **CRITICAL**: Preserve original attribute IDs
+			finalAttrs // unique list
 		);
 
 		// Let framework set physical properties via markPhysical()

package/src/planner/rules/cache/rule-materialization-advisory.ts

@@ -14,46 +14,50 @@ import { MaterializationAdvisory } from '../../cache/materialization-advisory.js
 const log = createLogger('optimizer:rule:materialization-advisory');
 
 export function ruleMaterializationAdvisory(node: PlanNode, context: OptContext): PlanNode | null {
-	// This is a global rule that analyzes the entire tree
-	// It should only be applied to root nodes to avoid duplicate analysis
+	// Apply this rule when we're at a non-relational node that has relational children
+	// This captures transitions into relational subtrees (queries, subqueries, CTEs, etc.)
 
-	// Simple heuristic: only apply to certain root-level node types
-	// to avoid analyzing the same tree multiple times
-	const rootNodeTypes = new Set([
-		'Select', 'Insert', 'Update', 'Delete', 'Block', 'CTE'
-	]);
+	// Check if this is a non-relational node
+	const nodeType = node.getType();
+	if (nodeType.typeClass === 'relation') {
+		// This is already a relational node, don't apply here
+		return null;
+	}
 
-	if (!rootNodeTypes.has(node.nodeType)) {
+	// Check if this node has any relational children
+	const relations = node.getRelations();
+	if (relations.length === 0) {
+		// No relational children, nothing to analyze
 		return null;
 	}
 
-	log('Applying materialization advisory to tree rooted at %s', node.nodeType);
+	log('Applying materialization advisory at transition from %s to relational children', node.nodeType);
 
 	try {
 		// Create advisory with current tuning parameters
 		const advisory = new MaterializationAdvisory(context.tuning);
 
-		// Analyze the tree for caching opportunities
-		const recommendations = advisory.analyzeTree(node);
-
-		// Count how many cache recommendations were made
-		const cacheCount = Array.from(recommendations.values())
-			.filter(rec => rec.shouldCache).length;
+		// We need to analyze and potentially transform each relational subtree
+		let anyTransformed = false;
 
-		if (cacheCount === 0) {
-			log('No caching opportunities identified');
-			return null;
+		// For each relational child, analyze and transform its entire subtree
+		for (const relation of relations) {
+			const transformedRelation = advisory.analyzeAndTransform(relation);
+			if (transformedRelation !== relation) {
+				anyTransformed = true;
+				log('Transformed relational subtree under %s', node.nodeType);
+			}
 		}
 
-		log('Found %d caching opportunities', cacheCount);
-
-		// Apply the caching recommendations
-		const cachedTree = advisory.applyCaching(node, recommendations);
-
-		// If the tree was modified, return the new tree
-		if (cachedTree !== node) {
-			log('Applied materialization advisory, tree modified');
-			return cachedTree;
+		// If any relational children were transformed, we need to return a transformed node
+		// However, since we can't easily reconstruct the parent node with new relational children
+		// (as discussed in the earlier implementation), we'll analyze the entire node
+		if (anyTransformed) {
+			// Re-analyze the entire tree rooted at this node
+			const fullTransform = advisory.analyzeAndTransform(node);
+			if (fullTransform !== node) {
+				return fullTransform;
+			}
 		}
 
 		return null;

package/src/planner/scopes/base.ts

@@ -6,22 +6,5 @@ import { type Scope, Ambiguous } from './scope.js';
  * Scope that tracks references.
  */
 export abstract class BaseScope implements Scope {
-	/** References that have been resolved through this scope. */
-	private _references: PlanNode[] = [];
-
 	abstract resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined;
-
-	/**
-	 * Returns all references that have been resolved through this scope.
-	 * This includes references from both this scope and any parent scopes.
-	 *
-	 * @returns An array of all resolved references.
-	 */
-	getReferences(): readonly PlanNode[] {
-		return this._references;
-	}
-
-	addReference(reference: PlanNode): void {
-		this._references.push(reference);
-	}
 }

package/src/planner/scopes/empty.ts

@@ -1,5 +1,3 @@
-import { QuereusError } from '../../common/errors.js';
-import { StatusCode } from '../../common/types.js';
 import * as AST from '../../parser/ast.js';
 import type { PlanNode } from '../nodes/plan-node.js';
 import { type Scope, Ambiguous } from './scope.js';
@@ -10,13 +8,5 @@ export class EmptyScope implements Scope {
 		return undefined;
 	}
 
-	getReferences(): readonly PlanNode[] {
-		return [];
-	}
-
-	addReference(_reference: PlanNode): void {
-		throw new QuereusError('EmptyScope does not support adding references.', StatusCode.MISUSE);
-	}
-
 	static readonly instance = new EmptyScope();
 }

package/src/planner/scopes/multi.ts

@@ -31,7 +31,6 @@ export class MultiScope extends BaseScope {
 				return Ambiguous;
 			}
 			if (result) {
-				this.addReference(result);
 				return result;
 			}
 		}

package/src/planner/scopes/param.ts

@@ -76,7 +76,6 @@ export class ParameterScope extends BaseScope {
 			return this.parentScope.resolveSymbol(symbolKey, expression);
 		}
 
-		this.addReference(parameterNode!);
 		return parameterNode;
 	}
 

package/src/planner/scopes/registered.ts

@@ -10,9 +10,6 @@ import { type ReferenceCallback, type Scope, Ambiguous } from './scope.js';
  * based on the current position in the PlanNode tree.
  */
 export class RegisteredScope implements Scope {
-	/** References that have been resolved through this scope. */
-	private _references: PlanNode[] = [];
-
 	/** Symbols that have been registered in this scope. */
 	private registeredSymbols: Map<string, ReferenceCallback> = new Map();
 
@@ -43,9 +40,7 @@ export class RegisteredScope implements Scope {
 	resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined {
 		const reference = this.registeredSymbols.get(symbolKey.toLowerCase());
 		if (reference) {
-			const node = reference(expression, this);
-			this.addReference(node);
-			return node;
+			return reference(expression, this);
 		}
 		if (this.parent) {
 			return this.parent.resolveSymbol(symbolKey, expression);
@@ -53,20 +48,6 @@ export class RegisteredScope implements Scope {
 		return undefined;
 	}
 
-	/**
-	 * Returns all references that have been resolved through this scope.
-	 * This includes references from both this scope and any parent scopes.
-	 *
-	 * @returns An array of all resolved references.
-	 */
-	getReferences(): readonly PlanNode[] {
-		return this._references;
-	}
-
-	addReference(reference: PlanNode): void {
-		this._references.push(reference);
-	}
-
 	/**
 	 * Returns all symbols that have been registered in this scope.
 	 *

package/src/planner/scopes/scope.ts

@@ -13,16 +13,4 @@ export type ReferenceCallback = (expression: AST.Expression, currentScope: Scope
  */
 export interface Scope {
 	resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined;
-
-	/**
-	 * Returns all references that have been resolved through this scope.
-	 * This includes references from both this scope and any parent scopes.
-	 *
-	 * @returns An array of all resolved references.
-	 */
-	getReferences(): readonly PlanNode[];
-
-	addReference(reference: PlanNode): void;
 }
-
-

package/src/planner/validation/plan-validator.ts

@@ -3,7 +3,7 @@
  * Validates that a plan tree meets all invariants before emission
  */
 
-import { PlanNode, type RelationalPlanNode } from '../nodes/plan-node.js';
+import { isRelationalNode, PlanNode, type RelationalPlanNode } from '../nodes/plan-node.js';
 import { PlanNodeType } from '../nodes/plan-node-type.js';
 import { QuereusError } from '../../common/errors.js';
 import { StatusCode } from '../../common/types.js';
@@ -299,13 +299,6 @@ function validateOrdering(ordering: any[], columnCount: number, nodePath: string
 	}
 }
 
-/**
- * Check if a node is a relational node
- */
-function isRelationalNode(node: PlanNode): boolean {
-	return 'getAttributes' in node && typeof (node as any).getAttributes === 'function';
-}
-
 /**
  * Check if a node type is a DDL node that doesn't produce attributes
  */