@quereus/quereus 0.2.1 → 0.4.5

package/src/planner/optimizer.ts

@@ -6,16 +6,24 @@ import { OptimizerTuning, DEFAULT_TUNING } from './optimizer-tuning.js';
 // Re-export for convenience
 export { DEFAULT_TUNING };
 
-import { applyRules, registerRules, createRule } from './framework/registry.js';
+import { applyRules } from './framework/registry.js';
 import { tracePhaseStart, tracePhaseEnd, traceNodeStart, traceNodeEnd } from './framework/trace.js';
 import { defaultStatsProvider, type StatsProvider } from './stats/index.js';
 import { createOptContext, type OptContext } from './framework/context.js';
+import type { OptimizerDiagnostics } from './framework/context.js';
+import { PassManager, PassId } from './framework/pass.js';
 // Phase 2 rules
 import { ruleMaterializationAdvisory } from './rules/cache/rule-materialization-advisory.js';
 // Phase 1.5 rules
 import { ruleSelectAccessPath } from './rules/access/rule-select-access-path.js';
+import { ruleGrowRetrieve } from './rules/retrieve/rule-grow-retrieve.js';
+import { rulePredicatePushdown } from './rules/predicate/rule-predicate-pushdown.js';
+import { ruleJoinKeyInference } from './rules/join/rule-join-key-inference.js';
+import { ruleJoinGreedyCommute } from './rules/join/rule-join-greedy-commute.js';
+// Predicate pushdown rules
 // Core optimization rules
 import { ruleAggregateStreaming } from './rules/aggregate/rule-aggregate-streaming.js';
+import { ruleQuickPickJoinEnumeration } from './rules/join/rule-quickpick-enumeration.js';
 // Constraint rules removed - now handled in builders for correctness
 import { ruleCteOptimization } from './rules/cache/rule-cte-optimization.js';
 import { ruleMutatingSubqueryCache } from './rules/cache/rule-mutating-subquery-cache.js';
@@ -32,114 +40,157 @@ const log = createLogger('optimizer');
  */
 export class Optimizer {
 	private readonly stats: StatsProvider;
+	private readonly passManager: PassManager;
+	private lastDiagnostics: OptimizerDiagnostics | null = null;
+	public tuning: OptimizerTuning;
 
 	constructor(
-		public readonly tuning: OptimizerTuning = DEFAULT_TUNING,
+		tuning: OptimizerTuning = DEFAULT_TUNING,
 		stats?: StatsProvider
 	) {
 		this.stats = stats ?? defaultStatsProvider;
+		this.passManager = new PassManager();
+		this.tuning = tuning;
 
-		// Ensure global framework rules are registered once
-		Optimizer.ensureGlobalRulesRegistered();
+		// Register rules to their appropriate passes only (no legacy globals)
+		this.registerRulesToPasses();
+	}
+
+	updateTuning(tuning: OptimizerTuning): void {
+		this.tuning = tuning;
 	}
 
 	private static globalRulesRegistered = false;
 
 	/**
-	 * Ensure global framework rules are registered only once
+	 * Legacy method removed; keep empty to avoid duplicate registrations
 	 */
-	private static ensureGlobalRulesRegistered(): void {
-		if (Optimizer.globalRulesRegistered) {
-			return;
-		}
-		Optimizer.globalRulesRegistered = true;
 
-		const toRegister = [];
+	/**
+	 * Register rules with their appropriate passes
+	 */
+	private registerRulesToPasses(): void {
+		// Structural pass rules (top-down) - for operations that need parent context
+		// Register grow-retrieve for ALL relational node types
+		// The rule itself will determine if growth is possible
+		const relationalNodeTypes = [
+			PlanNodeType.Filter,
+			PlanNodeType.Project,
+			PlanNodeType.Sort,
+			PlanNodeType.LimitOffset,
+			PlanNodeType.Aggregate,
+			PlanNodeType.Distinct,
+			PlanNodeType.Join,
+			PlanNodeType.Window,
+			// Add any other relational node types as needed
+		];
 
-		// Note: Single-pass constant folding is done before rules
+		for (const nodeType of relationalNodeTypes) {
+			this.passManager.addRuleToPass(PassId.Structural, {
+				id: `grow-retrieve-${nodeType}`,
+				nodeType,
+				phase: 'rewrite',
+				fn: ruleGrowRetrieve,
+				priority: 10
+			});
+		}
 
-		// Mutating subquery cache injection - critical for correctness
-		toRegister.push(createRule(
-			'mutating-subquery-cache',
-			PlanNodeType.Join,
-			'rewrite',
-			ruleMutatingSubqueryCache,
-			20 // Very high priority - correctness fix to prevent multiple execution
-		));
-
-		// Phase 1.5 rules
-		toRegister.push(createRule(
-			'select-access-path',
-			PlanNodeType.TableReference,
-			'impl',
-			ruleSelectAccessPath,
-			25 // High priority - fundamental access path selection
-		));
-
-		// Core optimization rules (converted from old system)
-		toRegister.push(createRule(
-			'aggregate-streaming',
-			PlanNodeType.Aggregate,
-			'impl',
-			ruleAggregateStreaming,
-			40 // High priority - fundamental logical→physical transformation
-		));
-
-		// toRegister.push(createRule(
-		// 	'project-optimization',
-		// 	PlanNodeType.Project,
-		// 	'impl',
-		// 	ruleProjectOptimization,
-		// 	50 // Medium priority - basic optimization
-		// ));
-
-		// toRegister.push(createRule(
-		// 	'filter-optimization',
-		// 	PlanNodeType.Filter,
-		// 	'impl',
-		// 	ruleFilterOptimization,
-		// 	50 // Medium priority - basic optimization
-		// ));
-
-		toRegister.push(createRule(
-			'cte-optimization',
+		// Join key inference (structural/characteristic)
+		this.passManager.addRuleToPass(PassId.Structural, {
+			id: 'join-key-inference',
+			nodeType: PlanNodeType.Join,
+			phase: 'rewrite',
+			fn: ruleJoinKeyInference,
+			priority: 15
+		});
+
+		// Greedy join commute: place smaller input on the left to improve nested-loop-like costs
+		this.passManager.addRuleToPass(PassId.Structural, {
+			id: 'join-greedy-commute',
+			nodeType: PlanNodeType.Join,
+			phase: 'rewrite',
+			fn: ruleJoinGreedyCommute,
+			priority: 16
+		});
+
+		this.passManager.addRuleToPass(PassId.Structural, {
+			id: 'predicate-pushdown',
+			nodeType: PlanNodeType.Filter,
+			phase: 'rewrite',
+			fn: rulePredicatePushdown,
+			priority: 20
+		});
+
+		// Physical pass rules (bottom-up) - for logical to physical transformations
+		this.passManager.addRuleToPass(PassId.Physical, {
+			id: 'select-access-path',
+			nodeType: PlanNodeType.Retrieve,
+			phase: 'impl',
+			fn: ruleSelectAccessPath,
+			priority: 10
+		});
+
+		// QuickPick join enumeration (optional via tuning)
+		this.passManager.addRuleToPass(PassId.Physical, {
+			id: 'quickpick-join-enumeration',
+			nodeType: PlanNodeType.Join,
+			phase: 'impl',
+			fn: ruleQuickPickJoinEnumeration,
+			priority: 5
+		});
+
+		this.passManager.addRuleToPass(PassId.Physical, {
+			id: 'aggregate-streaming',
+			nodeType: PlanNodeType.Aggregate,
+			phase: 'impl',
+			fn: ruleAggregateStreaming,
+			priority: 20
+		});
+
+		// Post-optimization pass rules (bottom-up) - for cleanup and caching
+		this.passManager.addRuleToPass(PassId.PostOptimization, {
+			id: 'mutating-subquery-cache',
+			nodeType: PlanNodeType.Join,
+			phase: 'rewrite',
+			fn: ruleMutatingSubqueryCache,
+			priority: 10
+		});
+
+		this.passManager.addRuleToPass(PassId.PostOptimization, {
+			id: 'cte-optimization',
+			nodeType: PlanNodeType.CTE,
+			phase: 'rewrite',
+			fn: ruleCteOptimization,
+			priority: 20
+		});
+
+		// Register materialization advisory for multiple node types
+		const nodeTypesForMaterialization = [
+			PlanNodeType.Block,
+			PlanNodeType.ScalarSubquery,
+			PlanNodeType.Exists,
+			PlanNodeType.In,
+			PlanNodeType.Insert,
+			PlanNodeType.Update,
+			PlanNodeType.Delete,
 			PlanNodeType.CTE,
-			'impl',
-			ruleCteOptimization,
-			70 // Lower priority - caching optimization
-		));
-
-		// Phase 2 rules - Materialization advisory
-		// TODO: Can we apply this more generally rather than assuming certain node types?
-		// Register for all node types that can have relational children
-		const nodeTypesWithRelationalChildren = [
-			PlanNodeType.Block,           // Contains statements
-			PlanNodeType.ScalarSubquery,  // Contains relational subquery
-			PlanNodeType.Exists,          // Contains relational subquery
-			PlanNodeType.In,              // Can contain relational subquery
-			PlanNodeType.Insert,          // Has source relation
-			PlanNodeType.Update,          // Has source relation
-			PlanNodeType.Delete,          // Has source relation
-			PlanNodeType.CTE,             // Has definition relation
-			PlanNodeType.RecursiveCTE,    // Has anchor/recursive relations
-			PlanNodeType.Returning,       // Wraps DML operations
-			// Scalar nodes that might contain subqueries
-			PlanNodeType.ScalarFunctionCall,  // Function args might be subqueries
-			PlanNodeType.CaseExpr,            // CASE conditions might be subqueries
+			PlanNodeType.RecursiveCTE,
+			PlanNodeType.Returning,
+			PlanNodeType.ScalarFunctionCall,
+			PlanNodeType.CaseExpr,
 		];
 
-		for (const nodeType of nodeTypesWithRelationalChildren) {
-			toRegister.push(createRule(
-				'materialization-advisory',
+		for (const nodeType of nodeTypesForMaterialization) {
+			this.passManager.addRuleToPass(PassId.PostOptimization, {
+				id: `materialization-advisory-${nodeType}`,
 				nodeType,
-				'rewrite',
-				ruleMaterializationAdvisory,
-				90 // Low priority - run last for global analysis
-			));
+				phase: 'rewrite',
+				fn: ruleMaterializationAdvisory,
+				priority: 30
+			});
 		}
 
-		// Register all rules at once
-		registerRules(toRegister);
+		log('Registered rules to optimization passes');
 	}
 
 	/**
@@ -153,18 +204,17 @@ export class Optimizer {
 
 		tracePhaseStart('optimization');
 		try {
-			// Phase 0: Single-pass constant folding before other rules
-			log('Running constant folding pre-pass');
-			const constantFoldedPlan = this.performConstantFolding(plan, context);
+			// Execute all optimization passes
+			const optimizedPlan = this.passManager.execute(plan, context);
 
-			// Continue with rule-based optimization
-			const result = this.optimizeNode(constantFoldedPlan, context);
+			// Capture diagnostics snapshot for external consumers
+			this.lastDiagnostics = { ...context.diagnostics };
 
-			// Phase 3: Validate the physical plan before returning
+			// Final validation (if enabled)
 			if (this.tuning.debug.validatePlan) {
 				log('Running plan validation');
 				try {
-					validatePhysicalTree(result);
+					validatePhysicalTree(optimizedPlan);
 					log('Plan validation passed');
 				} catch (error) {
 					log('Plan validation failed: %s', error);
@@ -172,12 +222,32 @@ export class Optimizer {
 				}
 			}
 
-			return result;
+			return optimizedPlan;
 		} finally {
 			tracePhaseEnd('optimization');
 		}
 	}
 
+	/**
+	 * Run only non-physical passes to obtain a structurally rewritten logical plan
+	 * suitable for pre-physical analysis (e.g., row-specific classification).
+	 */
+	optimizeForAnalysis(plan: PlanNode, db: Database): PlanNode {
+		log('Starting pre-physical analysis optimization of plan', plan.nodeType);
+
+		const context = createOptContext(this, this.stats, this.tuning, db);
+		tracePhaseStart('pre-physical-analysis');
+		try {
+			// Execute only structural pass(es) and constant folding
+			const folded = this.performConstantFolding(plan, context);
+			const structuralOnly = this.passManager.executeUpTo(folded, context, PassId.Structural);
+			this.lastDiagnostics = { ...context.diagnostics };
+			return structuralOnly;
+		} finally {
+			tracePhaseEnd('pre-physical-analysis');
+		}
+	}
+
 	/**
 	 * Perform single-pass constant folding over the entire plan tree
 	 */
@@ -254,4 +324,9 @@ export class Optimizer {
 	getStats(): StatsProvider {
 		return this.stats;
 	}
+
+	/** Get diagnostics from the last optimization run */
+	getLastDiagnostics(): OptimizerDiagnostics | null {
+		return this.lastDiagnostics;
+	}
 }

package/src/planner/planning-context.ts

@@ -2,8 +2,8 @@ import type { SqlParameters } from '../common/types.js';
 import type { Database } from '../core/database.js';
 import type { SchemaManager } from '../schema/manager.js';
 import type { Scope } from './scopes/scope.js';
-import type { ScalarPlanNode } from './nodes/plan-node.js';
-import type { CTEPlanNode } from './nodes/cte-node.js';
+import type { PlanNode, ScalarPlanNode } from './nodes/plan-node.js';
+import type { CTEScopeNode } from './nodes/cte-node.js';
 import type { CTEReferenceNode } from './nodes/cte-reference-node.js';
 
 /**
@@ -17,6 +17,7 @@ export interface DebugOptions {
   /** Enable instruction program output */
   showProgram?: boolean;
   /** Custom debug context for additional logging */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   debugContext?: Record<string, any>;
 }
 
@@ -36,12 +37,14 @@ export interface SchemaDependency {
  */
 export class BuildTimeDependencyTracker {
 	private dependencies = new Set<string>();
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	private resolvedObjects = new Map<string, WeakRef<any>>();
 	private invalidationCallbacks = new Set<() => void>();
 
 	/**
 	 * Records a dependency on a schema object and stores a weak reference to it.
 	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	recordDependency(dep: SchemaDependency, object: any): void {
 		const key = this.dependencyKey(dep);
 		this.dependencies.add(key);
@@ -163,7 +166,7 @@ export interface PlanningContext {
    * This map contains all CTEs from the current WITH clause and any parent WITH clauses,
    * allowing subqueries in expressions to resolve CTE references correctly.
    */
-  readonly cteNodes?: Map<string, CTEPlanNode>;
+  readonly cteNodes?: Map<string, CTEScopeNode>;
 
   /**
    * Schema dependency tracker for this planning session.
@@ -173,6 +176,7 @@ export interface PlanningContext {
   /**
    * Schema object cache for resolved objects during planning.
    */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   readonly schemaCache: Map<string, any>;
 
   /**
@@ -180,4 +184,7 @@ export interface PlanningContext {
    * to the same CTE with the same alias. Key format: "cteName:alias"
    */
   cteReferenceCache?: Map<string, CTEReferenceNode>;
+
+  /** maps a RelationalPlanNode to its column scope during building */
+  readonly outputScopes: Map<PlanNode, Scope>;
 }

package/src/planner/resolve.ts

@@ -3,6 +3,7 @@ import * as AST from "../parser/ast.js";
 import { ColumnReferenceNode, FunctionReferenceNode, ParameterReferenceNode, TableReferenceNode } from "./nodes/reference.js";
 import { QuereusError } from "../common/errors.js";
 import { StatusCode } from "../common/types.js";
+import { isScalarNode, type ScalarPlanNode } from "./nodes/plan-node.js";
 
 export function resolveTable(scope: Scope, exp: AST.IdentifierExpr, selectedSchema: string = 'main'): TableReferenceNode | typeof Ambiguous | undefined {
 	// table: [schema.]name
@@ -28,7 +29,7 @@ export function resolveTable(scope: Scope, exp: AST.IdentifierExpr, selectedSche
 // 	throw new QuereusError(`${idName} isn't a pragma`, StatusCode.ERROR);
 // }
 
-export function resolveColumn(scope: Scope, exp: AST.ColumnExpr, selectedSchema: string = 'main'): ColumnReferenceNode | typeof Ambiguous | undefined {
+export function resolveColumn(scope: Scope, exp: AST.ColumnExpr, selectedSchema: string = 'main'): ScalarPlanNode | typeof Ambiguous | undefined {
 	const schemaQualifier = exp.schema;
 	const tableQualifier = exp.table;
 	const columnName = exp.name;
@@ -38,8 +39,8 @@ export function resolveColumn(scope: Scope, exp: AST.ColumnExpr, selectedSchema:
 			// Fully qualified: schema.table.column
 			const symbolKey = `${schemaQualifier}.${tableQualifier}.${columnName}`;
 			const result = scope.resolveSymbol(symbolKey, exp);
-			if (result === Ambiguous || result instanceof ColumnReferenceNode) {
-				return result;
+			if (result === Ambiguous || (result && isScalarNode(result))) {
+				return result as ScalarPlanNode | typeof Ambiguous;
 			}
 			throw new QuereusError(`${symbolKey} isn't a column`, StatusCode.ERROR);
 		} else {
@@ -47,15 +48,15 @@ export function resolveColumn(scope: Scope, exp: AST.ColumnExpr, selectedSchema:
 			// Try without schema first, then with schema if that fails
 			const unqualifiedKey = `${tableQualifier}.${columnName}`;
 			const result = scope.resolveSymbol(unqualifiedKey, exp);
-			if (result === Ambiguous || result instanceof ColumnReferenceNode) {
-				return result;
+			if (result === Ambiguous || (result && isScalarNode(result))) {
+				return result as ScalarPlanNode | typeof Ambiguous;
 			}
 
 			// If unqualified fails, try with the selected schema
 			const qualifiedKey = `${selectedSchema}.${tableQualifier}.${columnName}`;
 			const qualifiedResult = scope.resolveSymbol(qualifiedKey, exp);
-			if (qualifiedResult === Ambiguous || qualifiedResult instanceof ColumnReferenceNode) {
-				return qualifiedResult;
+			if (qualifiedResult === Ambiguous || (qualifiedResult && isScalarNode(qualifiedResult))) {
+				return qualifiedResult as ScalarPlanNode | typeof Ambiguous;
 			}
 
 			throw new QuereusError(`${unqualifiedKey} isn't a column`, StatusCode.ERROR);
@@ -63,8 +64,8 @@ export function resolveColumn(scope: Scope, exp: AST.ColumnExpr, selectedSchema:
 	} else {
 		// Unqualified: column
 		const result = scope.resolveSymbol(columnName, exp);
-		if (result === Ambiguous || result instanceof ColumnReferenceNode) {
-			return result;
+		if (result === Ambiguous || (result && isScalarNode(result))) {
+			return result as ScalarPlanNode | typeof Ambiguous;
 		}
 		throw new QuereusError(`Column not found: ${columnName}`, StatusCode.ERROR);
 	}

package/src/planner/rules/README.md

@@ -1,96 +1,96 @@
-# Optimizer Rules Directory
-
-This directory contains optimization rules for the Quereus Titan optimizer, organized by functional area.
-
-## Directory Structure
-
-```
-rules/
-├── rewrite/          # Logical-to-logical transformations
-│   ├── predicate-pushdown/
-│   ├── join-reordering/
-│   └── subquery-rewrite/
-├── access/           # Table access path optimization
-│   ├── index-selection/
-│   └── scan-strategy/
-├── join/             # Join algorithm selection and optimization
-│   ├── algorithm-selection/
-│   └── join-ordering/
-├── aggregate/        # Aggregation optimization
-│   ├── streaming/
-│   └── hash-aggregate/
-├── cache/            # Caching and materialization
-│   ├── materialization/
-│   └── cache-injection/
-└── physical/         # Physical property propagation
-    ├── ordering/
-    └── uniqueness/
-```
-
-## Rule Categories
-
-### Rewrite Rules (Logical → Logical)
-Transform logical plan structure without changing to physical nodes:
-- Predicate pushdown
-- Join reordering based on cardinality
-- Subquery → join conversions
-- Constant folding and elimination
-
-### Access Rules (Logical → Physical)
-Choose optimal table access strategies:
-- Index vs. sequential scan selection
-- Index seek vs. scan decisions
-- Column pruning integration
-
-### Join Rules (Logical → Physical)
-Select join algorithms and optimize join trees:
-- Nested loop vs. hash join selection
-- Join order optimization
-- Cache injection for inner sides
-
-### Aggregate Rules (Logical → Physical)
-Choose aggregation implementation strategies:
-- Stream vs. hash aggregation
-- Sort requirement analysis
-- Grouping optimization
-
-### Cache Rules
-Inject caching where beneficial:
-- CTE materialization decisions
-- Nested loop inner caching
-- Spill-to-disk strategies
-
-### Physical Rules
-Propagate and optimize physical properties:
-- Ordering preservation and requirements
-- Uniqueness key propagation
-- Constant and deterministic flags
-
-## Rule Naming Convention
-
-Rules follow the pattern: `rule-<description>.ts`
-
-Examples:
-- `rule-predicate-pushdown.ts`
-- `rule-aggregate-streaming.ts`
-- `rule-join-hash-conversion.ts`
-- `rule-cache-cte-materialization.ts`
-
-## Implementation Requirements
-
-Each rule must:
-1. Follow the function signature: `(node: PlanNode, optimizer: Optimizer) => PlanNode | null`
-2. Include comprehensive unit tests in co-located `.spec.ts` file
-3. Use consistent logging with `createLogger('optimizer:rule:<name>')`
-4. Preserve attribute IDs when creating new nodes
-5. Set appropriate physical properties using `PlanNode.setDefaultPhysical()`
-
-## Getting Started
-
-1. Choose the appropriate category directory
-2. Copy the rule template from `docs/optimizer-conventions.md`
-3. Implement the rule following the established patterns
-4. Add comprehensive unit tests
-5. Register the rule in the appropriate registry file
-
-See `docs/optimizer-conventions.md` for detailed implementation guidelines. 
+# Optimizer Rules Directory
+
+This directory contains optimization rules for the Quereus Titan optimizer, organized by functional area.
+
+## Directory Structure
+
+```
+rules/
+├── rewrite/          # Logical-to-logical transformations
+│   ├── predicate-pushdown/
+│   ├── join-reordering/
+│   └── subquery-rewrite/
+├── access/           # Table access path optimization
+│   ├── index-selection/
+│   └── scan-strategy/
+├── join/             # Join algorithm selection and optimization
+│   ├── algorithm-selection/
+│   └── join-ordering/
+├── aggregate/        # Aggregation optimization
+│   ├── streaming/
+│   └── hash-aggregate/
+├── cache/            # Caching and materialization
+│   ├── materialization/
+│   └── cache-injection/
+└── physical/         # Physical property propagation
+    ├── ordering/
+    └── uniqueness/
+```
+
+## Rule Categories
+
+### Rewrite Rules (Logical → Logical)
+Transform logical plan structure without changing to physical nodes:
+- Retrieve growth (modules handle pushdown via Retrieve pipelines)
+- Join reordering based on cardinality
+- Subquery → join conversions
+- Constant folding and elimination
+
+### Access Rules (Logical → Physical)
+Choose optimal table access strategies:
+- Index vs. sequential scan selection
+- Index seek vs. scan decisions
+- Column pruning integration
+
+### Join Rules (Logical → Physical)
+Select join algorithms and optimize join trees:
+- Nested loop vs. hash join selection
+- Join order optimization
+- Cache injection for inner sides
+
+### Aggregate Rules (Logical → Physical)
+Choose aggregation implementation strategies:
+- Stream vs. hash aggregation
+- Sort requirement analysis
+- Grouping optimization
+
+### Cache Rules
+Inject caching where beneficial:
+- CTE materialization decisions
+- Nested loop inner caching
+- Spill-to-disk strategies
+
+### Physical Rules
+Propagate and optimize physical properties:
+- Ordering preservation and requirements
+- Uniqueness key propagation
+- Constant and deterministic flags
+
+## Rule Naming Convention
+
+Rules follow the pattern: `rule-<description>.ts`
+
+Examples:
+- `rule-grow-retrieve.ts`
+- `rule-aggregate-streaming.ts`
+- `rule-join-hash-conversion.ts`
+- `rule-cache-cte-materialization.ts`
+
+## Implementation Requirements
+
+Each rule must:
+1. Follow the function signature: `(node: PlanNode, optimizer: Optimizer) => PlanNode | null`
+2. Include comprehensive unit tests in co-located `.spec.ts` file
+3. Use consistent logging with `createLogger('optimizer:rule:<name>')`
+4. Preserve attribute IDs when creating new nodes
+5. Set appropriate physical properties using `PlanNode.setDefaultPhysical()`
+
+## Getting Started
+
+1. Choose the appropriate category directory
+2. Copy the rule template from `docs/optimizer-conventions.md`
+3. Implement the rule following the established patterns
+4. Add comprehensive unit tests
+5. Register the rule in the appropriate registry file
+
+See `docs/optimizer-conventions.md` for detailed implementation guidelines.