@quereus/quereus 0.2.0 → 0.4.0

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

@@ -1,148 +1,162 @@
 /**
  * Rule: Aggregate Streaming
  *
- * Transforms: AggregateNode → StreamAggregateNode (with Sort if needed)
- * Conditions: Logical aggregate node needs physical implementation
- * Benefits: Enables streaming aggregation with proper grouping order
+ * Required Characteristics:
+ * - Node must support aggregation operations (AggregationCapable interface)
+ * - Node must be relational (produces rows)
+ * - Node must be read-only (no side effects for streaming)
+ *
+ * Applied When:
+ * - Logical aggregate node needs physical streaming implementation
+ * - Source data can be processed incrementally
+ *
+ * Benefits: Enables streaming aggregation with proper grouping order, memory efficient processing
  */
 
 import { createLogger } from '../../../common/logger.js';
-import type { PlanNode } from '../../nodes/plan-node.js';
+import type { PlanNode, ScalarPlanNode, Attribute } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
-import { AggregateNode } from '../../nodes/aggregate-node.js';
 import { StreamAggregateNode } from '../../nodes/stream-aggregate.js';
 import { SortNode } from '../../nodes/sort.js';
+import {
+	PlanNodeCharacteristics,
+	CapabilityDetectors,
+	type AggregationCapable
+} from '../../framework/characteristics.js';
 
 const log = createLogger('optimizer:rule:aggregate-streaming');
 
 export function ruleAggregateStreaming(node: PlanNode, _context: OptContext): PlanNode | null {
-	// Guard: only apply to AggregateNode
-	if (!(node instanceof AggregateNode)) {
+	// Guard: node must support aggregation operations
+	if (!CapabilityDetectors.isAggregating(node)) {
 		return null;
 	}
 
 	log('Applying aggregate streaming rule to node %s', node.id);
 
-	// Source is already optimized by framework
-	const source = node.source;
-
-	// For now, always use StreamAggregate
-	// TODO: Check if source is ordered on groupBy columns
-	// TODO: Consider HashAggregate for unordered inputs
-
-	if (node.groupBy.length > 0) {
-		// Need to ensure ordering for streaming aggregate
-		// For now, always insert a sort
-		// TODO: Check if source already provides the required ordering
-		const sortKeys = node.groupBy.map(expr => ({
-			expression: expr,
-			direction: 'asc' as const,
-			nulls: undefined
-		}));
+	// Get aggregation characteristics
+	const aggregateNode = node as AggregationCapable;
+	const groupingKeys = aggregateNode.getGroupingKeys();
+	const aggregateExpressions = aggregateNode.getAggregateExpressions();
 
-		const sortNode = new SortNode(node.scope, source, sortKeys);
+	// Check if we can stream the aggregation over the source
+	const source = aggregateNode.getSource();
 
-		// 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);
-		}
+	// Check if streaming aggregation is beneficial
+	if (!aggregateNode.canStreamAggregate()) {
+		log('Node cannot use streaming aggregation, skipping');
+		return null;
+	}
 
-		// 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);
-			}
+	if (groupingKeys.length > 0) {
+		// Need to ensure ordering for streaming aggregate
+		// Check if source already provides the required ordering
+		const sourceOrdering = PlanNodeCharacteristics.getOrdering(source);
+		const needsSort = !isOrderedForGrouping(sourceOrdering, groupingKeys);
+
+		let sortedSource = source;
+		if (needsSort) {
+			// Insert sort to ensure proper grouping order
+			const sortKeys = groupingKeys.map(expr => ({
+				expression: expr,
+				direction: 'asc' as const,
+				nulls: undefined
+			}));
+
+			sortedSource = new SortNode(node.scope, source, sortKeys);
+			log('Inserted sort for grouping keys');
+		} else {
+			log('Source already provides required ordering for streaming');
 		}
 
-		// 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);
-			}
-		}
+		// Create combined attributes preserving attribute IDs
+		const finalAttrs = combineAttributes(node.getAttributes(), source.getAttributes());
 
-		const finalAttrs = deduped;
+		// Convert aggregate expressions to match StreamAggregateNode interface
+		const streamAggregates = aggregateExpressions.map(agg => ({
+			expression: agg.expr,
+			alias: agg.alias
+		}));
 
 		const result = new StreamAggregateNode(
 			node.scope,
-			sortNode,
-			node.groupBy,
-			node.aggregates,
+			sortedSource,
+			groupingKeys,
+			streamAggregates,
 			undefined, // estimatedCostOverride
-			finalAttrs // unique list
+			finalAttrs
 		);
 
-		// Let framework set physical properties via markPhysical()
-		// Both SortNode and StreamAggregateNode have getPhysical() methods
-
-		log('Transformed AggregateNode to StreamAggregateNode with sort');
+		log('Transformed aggregation to StreamAggregateNode with %s', needsSort ? 'sort' : 'existing order');
 		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);
-			}
-		}
+		const finalAttrs = combineAttributes(node.getAttributes(), source.getAttributes());
 
-		// 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;
+		// Convert aggregate expressions to match StreamAggregateNode interface
+		const streamAggregates = aggregateExpressions.map(agg => ({
+			expression: agg.expr,
+			alias: agg.alias
+		}));
 
 		const result = new StreamAggregateNode(
 			node.scope,
 			source,
-			node.groupBy,
-			node.aggregates,
+			groupingKeys,
+			streamAggregates,
 			undefined, // estimatedCostOverride
-			finalAttrs // unique list
+			finalAttrs
 		);
 
-		// Let framework set physical properties via markPhysical()
-		// StreamAggregateNode has getPhysical() method
-
-		log('Transformed AggregateNode to StreamAggregateNode without sort');
+		log('Transformed aggregation to StreamAggregateNode without sort');
 		return result;
 	}
 }
+
+/**
+ * Check if source ordering matches grouping requirements for streaming
+ */
+function isOrderedForGrouping(
+	_ordering: { column: number; desc: boolean }[] | undefined,
+	_groupingKeys: readonly ScalarPlanNode[]
+): boolean {
+	// TODO: Implement proper ordering analysis
+	// For now, conservatively return false to always sort
+	// This should check if the ordering covers all grouping keys in order
+	return false;
+}
+
+/**
+ * Combine attributes from aggregate and source, avoiding duplicates by name
+ * This preserves attribute IDs while ensuring unique column names
+ */
+function combineAttributes(aggregateAttrs: readonly Attribute[], sourceAttrs: readonly Attribute[]): Attribute[] {
+	const seenNames = new Set<string>();
+	const combinedAttrs: Attribute[] = [];
+
+	// 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 deduplication pass
+	const uniqueByName = new Set<string>();
+	const deduped: any[] = [];
+	for (const attr of combinedAttrs) {
+		if (!uniqueByName.has(attr.name)) {
+			deduped.push(attr);
+			uniqueByName.add(attr.name);
+		}
+	}
+
+	return deduped;
+}

package/src/planner/rules/cache/rule-cte-optimization.ts

@@ -1,8 +1,14 @@
 /**
  * Rule: CTE Optimization
  *
- * Transforms: CTENode → CTENode (with caching when beneficial)
- * Conditions: CTE would benefit from materialization/caching
+ * Required Characteristics:
+ * - Node must support CTE operations (CTECapable interface)
+ * - Node must be relational (produces rows)
+ * - Source must be cacheable for materialization
+ *
+ * Applied When:
+ * - CTE would benefit from materialization/caching based on cost analysis
+ *
  * Benefits: Reduces redundant computation for repeated CTE access
  */
 
@@ -11,37 +17,43 @@ import type { PlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
 import { CTENode } from '../../nodes/cte-node.js';
 import { CacheNode } from '../../nodes/cache-node.js';
-import { PlanNodeType } from '../../nodes/plan-node-type.js';
+import { CapabilityDetectors, CachingAnalysis, PlanNodeCharacteristics, type CTECapable } from '../../framework/characteristics.js';
 
 const log = createLogger('optimizer:rule:cte-optimization');
 
 export function ruleCteOptimization(node: PlanNode, context: OptContext): PlanNode | null {
-	// Guard: only apply to CTENode
-	if (!(node instanceof CTENode)) {
+	// Guard: node must support CTE operations
+	if (!CapabilityDetectors.isCTE(node)) {
 		return null;
 	}
 
-	log('Optimizing CTENode %s', node.cteName);
+	// Get CTE characteristics
+	const cteNode = node as CTECapable;
+	log('Optimizing CTE %s', cteNode.cteName);
 
 	// Source is already optimized by framework
-	const source = node.source;
+	const source = cteNode.getCTESource();
 
 	// Heuristics for when to cache CTEs:
 	// 1. CTE has materialization hint
 	// 2. CTE is estimated to be reasonably sized
 	// 3. CTE is not already cached
-	const sourceSize = source.estimatedRows ?? context.tuning.defaultRowEstimate;
+	const sourceSize = PlanNodeCharacteristics.estimatesRows(source);
+	const isAlreadyCached = CapabilityDetectors.isCached(source) && source.isCached();
 	const shouldCache = (
-		node.materializationHint === 'materialized' ||
+		cteNode.materializationHint === 'materialized' ||
 		(sourceSize > 0 && sourceSize < context.tuning.cte.maxSizeForCaching)
-	) && source.nodeType !== PlanNodeType.Cache;
+	) && !isAlreadyCached;
 
 	if (shouldCache) {
-		log('Adding cache to CTE %s (estimated rows: %d)', node.cteName, sourceSize);
+		log('Adding cache to CTE %s (estimated rows: %d)', cteNode.cteName, sourceSize);
+
+		// Use characteristics-based cache threshold calculation
 		const cacheThreshold = Math.min(
-			sourceSize * context.tuning.cte.cacheThresholdMultiplier,
+			CachingAnalysis.getCacheThreshold(source),
 			context.tuning.cte.maxCacheThreshold
 		);
+
 		const cachedSource = new CacheNode(
 			source.scope,
 			source,
@@ -49,13 +61,14 @@ export function ruleCteOptimization(node: PlanNode, context: OptContext): PlanNo
 			cacheThreshold
 		);
 
+		// Create new CTE with cached source (specific to CTENode implementation)
 		const result = new CTENode(
 			node.scope,
-			node.cteName,
-			node.columns,
+			cteNode.cteName,
+			cteNode.columns,
 			cachedSource,
-			node.materializationHint,
-			node.isRecursive
+			cteNode.materializationHint,
+			cteNode.isRecursive
 		);
 
 		log('Created CTE with caching');

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

@@ -1,8 +1,15 @@
 /**
  * Rule: Materialization Advisory
  *
- * Transforms: Any relational node → CacheNode (when beneficial)
- * Conditions: Node would benefit from caching based on reference analysis
+ * Required Characteristics:
+ * - Node must be non-relational with relational children
+ * - Children must be cacheable based on reference analysis
+ * - Children must benefit from materialization
+ *
+ * Applied When:
+ * - Transition from non-relational to relational subtrees
+ * - Relational subtrees would benefit from caching
+ *
  * Benefits: Reduces redundant computation for repeated scans and loop contexts
  */
 
@@ -10,6 +17,7 @@ import { createLogger } from '../../../common/logger.js';
 import type { PlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
 import { MaterializationAdvisory } from '../../cache/materialization-advisory.js';
+import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
 
 const log = createLogger('optimizer:rule:materialization-advisory');
 
@@ -17,9 +25,8 @@ export function ruleMaterializationAdvisory(node: PlanNode, context: OptContext)
 	// 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.)
 
-	// Check if this is a non-relational node
-	const nodeType = node.getType();
-	if (nodeType.typeClass === 'relation') {
+	// Check if this is a non-relational node using characteristics
+	if (PlanNodeCharacteristics.isRelational(node)) {
 		// This is already a relational node, don't apply here
 		return null;
 	}
@@ -31,7 +38,7 @@ export function ruleMaterializationAdvisory(node: PlanNode, context: OptContext)
 		return null;
 	}
 
-	log('Applying materialization advisory at transition from %s to relational children', node.nodeType);
+	log('Applying materialization advisory at transition from %s to relational children', node.getType().typeClass);
 
 	try {
 		// Create advisory with current tuning parameters
@@ -45,7 +52,7 @@ export function ruleMaterializationAdvisory(node: PlanNode, context: OptContext)
 			const transformedRelation = advisory.analyzeAndTransform(relation);
 			if (transformedRelation !== relation) {
 				anyTransformed = true;
-				log('Transformed relational subtree under %s', node.nodeType);
+				log('Transformed relational subtree under %s node', node.getType().typeClass);
 			}
 		}
 

package/src/planner/rules/cache/rule-mutating-subquery-cache.ts

@@ -1,51 +1,55 @@
 /**
  * Rule: Mutating Subquery Cache Injection
  *
- * Transforms: JoinNode with mutating right side → JoinNode with cached right side
- * Conditions: Right side contains operations with readonly=false physical property
+ * Required Characteristics:
+ * - Node must be a join operation (JoinCapable interface)
+ * - Right side must contain operations with side effects (readonly=false)
+ * - Right side must not already be cached
+ *
+ * Applied When:
+ * - Join has mutating operations on right side that could be executed multiple times
+ *
  * Benefits: Prevents mutating subqueries from being executed multiple times in nested loop joins
  */
 
 import { createLogger } from '../../../common/logger.js';
 import { PlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
-import { JoinNode } from '../../nodes/join-node.js';
 import { CacheNode } from '../../nodes/cache-node.js';
-import { PlanNodeType } from '../../nodes/plan-node-type.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { PlanNodeCharacteristics, CapabilityDetectors, CachingAnalysis, type JoinCapable } from '../../framework/characteristics.js';
 
 const log = createLogger('optimizer:rule:mutating-subquery-cache');
 
-export function ruleMutatingSubqueryCache(node: PlanNode, context: OptContext): PlanNode | null {
-	// Guard: only apply to JoinNode
-	if (!(node instanceof JoinNode)) {
+export function ruleMutatingSubqueryCache(node: PlanNode, _context: OptContext): PlanNode | null {
+	// Guard: node must support join operations
+	if (!CapabilityDetectors.isJoin(node)) {
 		return null;
 	}
 
-	log('Checking JoinNode for operations with side effects on right side');
+	log('Checking join operation for side effects on right side');
 
-	// Check if the right side contains operations with side effects
-	const rightSide = node.right;
-	const hasSideEffects = containsOperationsWithSideEffects(rightSide);
+	// Get join-specific characteristics
+	const joinNode = node as JoinCapable;
+	const rightSide = joinNode.getRightSource();
 
+	// Check if right side contains operations with side effects
+	const hasSideEffects = containsOperationsWithSideEffects(rightSide);
 	if (!hasSideEffects) {
 		log('Right side does not contain operations with side effects, skipping');
 		return null;
 	}
 
 	// Check if right side is already cached
-	if (rightSide.nodeType === PlanNodeType.Cache) {
+	if (CapabilityDetectors.isCached(rightSide) && rightSide.isCached()) {
 		log('Right side is already cached, skipping');
 		return null;
 	}
 
 	log('Detected operations with side effects on right side of join, injecting cache');
 
-	// Calculate appropriate cache threshold
-	const estimatedRows = rightSide.estimatedRows ?? context.tuning.defaultRowEstimate;
-	const threshold = Math.min(
-		Math.max(estimatedRows * context.tuning.join.cacheThresholdMultiplier, 1000),
-		context.tuning.join.maxCacheThreshold
-	);
+	// Calculate appropriate cache threshold using characteristics
+	const threshold = CachingAnalysis.getCacheThreshold(rightSide);
 
 	// Wrap the right side with a cache node
 	const cachedRightSide = new CacheNode(
@@ -56,13 +60,16 @@ export function ruleMutatingSubqueryCache(node: PlanNode, context: OptContext):
 	);
 
 	// Create new join node with cached right side
+	// Note: We still need to use specific constructor since we don't have a generic join builder yet
 	const result = new JoinNode(
 		node.scope,
-		node.left, // Left side unchanged
-		cachedRightSide, // Right side now cached
-		node.joinType,
-		node.condition,
-		node.usingColumns
+		joinNode.getLeftSource(),
+		cachedRightSide,
+		joinNode.getJoinType(),
+		joinNode.getJoinCondition(),
+		// Special case: for JOINs, we also need to check if any of the join conditions
+		// reference columns from the mutating subquery (via USING clause)
+		joinNode.getUsingColumns()
 	);
 
 	log('Successfully injected cache for operations with side effects (threshold: %d)', threshold);
@@ -71,40 +78,27 @@ export function ruleMutatingSubqueryCache(node: PlanNode, context: OptContext):
 
 /**
  * Recursively check if a plan tree contains operations with side effects
+ * Uses characteristics-based analysis instead of hard-coded node type checks
  */
 function containsOperationsWithSideEffects(node: PlanNode): boolean {
-	// Check if this node has side effects using physical properties
-	if (hasNodeSideEffects(node)) {
+	// Check this node's characteristics
+	if (PlanNodeCharacteristics.hasSideEffects(node)) {
 		return true;
 	}
 
-	// Recursively check children
+	// Recursively check all children
 	for (const child of node.getChildren()) {
 		if (containsOperationsWithSideEffects(child)) {
 			return true;
 		}
 	}
 
-	// Check relational children if available
-	if ('getRelations' in node) {
-		for (const relation of (node as any).getRelations()) {
-			if (containsOperationsWithSideEffects(relation)) {
-				return true;
-			}
+	// Check relational children if available (preserved for compatibility)
+	for (const relation of node.getRelations()) {
+		if (containsOperationsWithSideEffects(relation)) {
+			return true;
 		}
 	}
 
 	return false;
 }
-
-/**
- * Check if a node has side effects using physical properties
- */
-function hasNodeSideEffects(node: PlanNode): boolean {
-	// By the time rules run, all children should have physical properties set by the framework
-	if (!node.physical) {
-		throw new Error(`Internal error: Node ${node.nodeType}:${node.id} missing physical properties during rule application`);
-	}
-
-	return PlanNode.hasSideEffects(node.physical);
-}

package/src/planner/rules/join/rule-join-greedy-commute.ts

@@ -0,0 +1,48 @@
+import { createLogger } from '../../../common/logger.js';
+import type { PlanNode, RelationalPlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+import { JoinNode } from '../../nodes/join-node.js';
+
+const log = createLogger('optimizer:rule:join-greedy-commute');
+
+/**
+ * Rule: Join Greedy Commute
+ *
+ * Simple heuristic: for INNER joins, prefer the smaller input on the left to drive nested-loop-like cost.
+ * This uses children estimatedRows (influenced by pushdown/growth) and swaps left/right when beneficial.
+ *
+ * Safety:
+ * - INNER joins are commutative; ColumnReferenceNode uses attribute IDs, so swapping sides preserves semantics.
+ * - We do NOT change associativity; we only commute immediate children of a JoinNode.
+ */
+export function ruleJoinGreedyCommute(node: PlanNode, _context: OptContext): PlanNode | null {
+  if (!(node instanceof JoinNode)) return null;
+  if (node.joinType !== 'inner' && node.joinType !== 'cross') return null;
+
+  const leftRows = node.getLeftSource().estimatedRows ?? Number.POSITIVE_INFINITY;
+  const rightRows = node.getRightSource().estimatedRows ?? Number.POSITIVE_INFINITY;
+
+  // Prefer known finite estimatedRows; also detect <=1 row driver on either side
+  const leftIsSingleton = node.getLeftSource().physical.uniqueKeys?.some(k => k.length === 0) === true;
+  const rightIsSingleton = node.getRightSource().physical.uniqueKeys?.some(k => k.length === 0) === true;
+
+  // If right is strictly better driver (smaller or singleton), swap
+  const shouldSwap = (rightIsSingleton && !leftIsSingleton) || (!rightIsSingleton && !leftIsSingleton && rightRows < leftRows);
+  if (!shouldSwap) return null;
+
+  log('Commuting join children to place smaller input on the left (leftRows=%s, rightRows=%s)', String(leftRows), String(rightRows));
+
+  // Swap children; condition stays the same (attribute IDs are stable)
+  const swapped = new JoinNode(
+    node.scope,
+    node.getRightSource() as RelationalPlanNode,
+    node.getLeftSource() as RelationalPlanNode,
+    node.getJoinType(),
+    node.getJoinCondition(),
+    node.getUsingColumns()
+  );
+
+  return swapped;
+}
+
+

package/src/planner/rules/join/rule-join-key-inference.ts

@@ -0,0 +1,35 @@
+import { createLogger } from '../../../common/logger.js';
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+import { JoinNode } from '../../nodes/join-node.js';
+import { BinaryOpNode } from '../../nodes/scalar.js';
+import { ColumnReferenceNode } from '../../nodes/reference.js';
+
+const log = createLogger('optimizer:rule:join-key-inference');
+
+/**
+ * Rule: Join Key Inference
+ *
+ * Detect simple equi-join predicates (left.col = right.pk) and propagate
+ * inner/cross join unique keys (already handled by JoinNode.computePhysical),
+ * with a hook for future FK->PK inference (not implemented here yet).
+ */
+export function ruleJoinKeyInference(node: PlanNode, _context: OptContext): PlanNode | null {
+  if (!(node instanceof JoinNode)) return null;
+  if (node.joinType !== 'inner' && node.joinType !== 'cross') return null;
+
+  const cond = node.getJoinCondition();
+  if (!cond || !(cond instanceof BinaryOpNode)) return null;
+  if (cond.expression.operator !== '=') return null;
+
+  // Simple left.col = right.col pattern check; placeholder for future FK->PK detection
+  const leftIsCol = cond.left instanceof ColumnReferenceNode;
+  const rightIsCol = cond.right instanceof ColumnReferenceNode;
+  if (!leftIsCol || !rightIsCol) return null;
+
+  log('Detected equi-join predicate; JoinNode.computePhysical will preserve side keys');
+  // No structural change needed now; computePhysical on JoinNode already preserves side keys
+  return null;
+}
+
+