@quereus/quereus 0.1.0 → 0.2.0

package/src/runtime/context-helpers.ts

@@ -0,0 +1,191 @@
+import type { RuntimeContext } from './types.js';
+import type { RowDescriptor, RowGetter } from '../planner/nodes/plan-node.js';
+import type { SqlValue, Row } from '../common/types.js';
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+import { createLogger } from '../common/logger.js';
+
+const ctxLog = createLogger('runtime:context');
+const ctxLookupLog = createLogger('runtime:context:lookup');
+
+/**
+ * A mutable slot for efficient row context management in streaming operations.
+ * Avoids per-row Map mutations while maintaining context safety.
+ */
+export interface RowSlot {
+	/** Replace the current row (cheap field write) */
+	set(row: Row): void;
+	/** Tear down (removes descriptor from context) */
+	close(): void;
+}
+
+/**
+ * Create a row slot for efficient streaming context management.
+ * The slot installs a context entry once and updates it by reference.
+ * Perfect for scan/join/window operations that process many rows.
+ */
+export function createRowSlot(
+	rctx: RuntimeContext,
+	descriptor: RowDescriptor
+): RowSlot {
+	// Internal boxed reference - one allocation per slot
+	const ref = { current: undefined as Row | undefined };
+
+	// Install only once
+	rctx.context.set(descriptor, () => ref.current!);
+
+	const attrs = Object.keys(descriptor).filter(k => descriptor[parseInt(k)] !== undefined);
+	ctxLog('CREATE slot with attrs=[%s]', attrs.join(','));
+
+	return {
+		set(row: Row) {
+			ref.current = row;
+		},
+		close() {
+			rctx.context.delete(descriptor);
+			ctxLog('CLOSE slot with attrs=[%s]', attrs.join(','));
+		}
+	};
+}
+
+/**
+ * Resolve an attribute ID to its column value in the current context.
+ * Searches from newest (innermost) to oldest (outermost) scope.
+ */
+export function resolveAttribute(rctx: RuntimeContext, attributeId: number, columnName?: string): SqlValue {
+	// Iterate newest → oldest so the most recently pushed scope wins
+	const contextsReversed = Array.from(rctx.context.entries()).reverse();
+
+	ctxLookupLog('LOOKUP column %s (attr#%d) in %d contexts', columnName || '?', attributeId, contextsReversed.length);
+
+	for (const [descriptor, rowGetter] of contextsReversed) {
+		const columnIndex = descriptor[attributeId];
+		if (columnIndex !== undefined) {
+			const row = rowGetter();
+			if (Array.isArray(row) && columnIndex < row.length) {
+				ctxLookupLog('FOUND column %s at index %d in row', columnName || '?', columnIndex);
+				return row[columnIndex];
+			}
+		}
+	}
+
+	// Log available attributes for debugging
+	if (ctxLookupLog.enabled) {
+		ctxLookupLog('Available contexts:');
+		for (const [descriptor, _] of contextsReversed) {
+			const attrs = Object.keys(descriptor).filter(k => descriptor[parseInt(k)] !== undefined);
+			ctxLookupLog('  - Descriptor with attrs=[%s]', attrs.join(','));
+		}
+
+		// Log current plan execution stack if available
+		if (rctx.planStack && rctx.planStack.length > 0) {
+			const currentNode = rctx.planStack[rctx.planStack.length - 1];
+			ctxLookupLog('LOOKUP FAILED in node %s id=%d', currentNode.nodeType, currentNode.id);
+			ctxLookupLog('Execution stack: %s',
+				rctx.planStack.map(n => `${n.nodeType}#${n.id}`).join(' → '));
+		}
+	}
+
+	throw new QuereusError(
+		`No row context found for column ${columnName || `attr#${attributeId}`}. The column reference must be evaluated within the context of its source relation.`,
+		StatusCode.ERROR
+	);
+}
+
+/**
+ * Look up a specific column by descriptor and index.
+ * Useful when you already know which descriptor contains the column.
+ */
+export function lookupColumn(rctx: RuntimeContext, descriptor: RowDescriptor, columnIndex: number): SqlValue | undefined {
+	const rowGetter = rctx.context.get(descriptor);
+	if (!rowGetter) {
+		ctxLookupLog('LOOKUP by index %d - no context found', columnIndex);
+		return undefined;
+	}
+
+	const row = rowGetter();
+	if (Array.isArray(row) && columnIndex < row.length) {
+		ctxLookupLog('LOOKUP by index %d - found value', columnIndex);
+		return row[columnIndex];
+	}
+	ctxLookupLog('LOOKUP by index %d - index out of bounds', columnIndex);
+	return undefined;
+}
+
+/**
+ * Execute a function with a row context, ensuring proper cleanup.
+ * This is the recommended pattern for all row-processing emitters.
+ */
+export async function withAsyncRowContext<T>(
+	rctx: RuntimeContext,
+	descriptor: RowDescriptor,
+	rowGetter: RowGetter,
+	fn: () => T | Promise<T>
+): Promise<T> {
+	const attrs = Object.keys(descriptor).filter(k => descriptor[parseInt(k)] !== undefined);
+	ctxLog('PUSH async context with attrs=[%s]', attrs.join(','));
+
+	rctx.context.set(descriptor, rowGetter);
+	try {
+		return await fn();
+	} finally {
+		rctx.context.delete(descriptor);
+		ctxLog('POP async context with attrs=[%s]', attrs.join(','));
+	}
+}
+
+/**
+ * Execute a function with a row context, ensuring proper cleanup.
+ * This is the recommended pattern for all row-processing emitters.
+ */
+export function withRowContext<T>(
+	rctx: RuntimeContext,
+	descriptor: RowDescriptor,
+	rowGetter: RowGetter,
+	fn: () => T
+): T {
+	const attrs = Object.keys(descriptor).filter(k => descriptor[parseInt(k)] !== undefined);
+	ctxLog('PUSH context with attrs=[%s]', attrs.join(','));
+
+	rctx.context.set(descriptor, rowGetter);
+	try {
+		return fn();
+	} finally {
+		rctx.context.delete(descriptor);
+		ctxLog('POP context with attrs=[%s]', attrs.join(','));
+	}
+}
+
+/**
+ * Execute a generator function with row context management.
+ * Useful for streaming operations that process multiple rows.
+ */
+export async function* withRowContextGenerator<T>(
+	rctx: RuntimeContext,
+	descriptor: RowDescriptor,
+	rows: AsyncIterable<Row>,
+	fn: (row: Row) => AsyncIterable<T>
+): AsyncIterable<T> {
+	const attrs = Object.keys(descriptor).filter(k => descriptor[parseInt(k)] !== undefined);
+	let rowCount = 0;
+
+	for await (const row of rows) {
+		if (rowCount === 0) {
+			ctxLog('PUSH generator context with attrs=[%s]', attrs.join(','));
+		}
+		rctx.context.set(descriptor, () => row);
+		try {
+			yield* fn(row);
+			rowCount++;
+		} finally {
+			rctx.context.delete(descriptor);
+			if (ctxLog.enabled && rowCount % 1000 === 0) {
+				ctxLog('Generator context processed %d rows', rowCount);
+			}
+		}
+	}
+
+	if (rowCount > 0) {
+		ctxLog('POP generator context after %d rows', rowCount);
+	}
+}

package/src/runtime/emission-context.ts

@@ -98,9 +98,12 @@ export class EmissionContext {
 	private readonly schemaManager: SchemaManager;
 	private readonly dependencyTracker = new DependencyTracker();
 	private readonly schemaSnapshot = new Map<string, any>();
+	public readonly tracePlanStack: boolean;
 
-	constructor(public readonly db: Database) {
-		this.db = db;
+	constructor(
+		public readonly db: Database,
+	) {
+		this.tracePlanStack = !!db.getOption('trace_plan_stack').value;
 		this.schemaManager = db.schemaManager;
 	}
 

package/src/runtime/emit/aggregate.ts

@@ -56,10 +56,10 @@ function compareDistinctValues(a: SqlValue | SqlValue[], b: SqlValue | SqlValue[
  * This traverses up the tree to find the original table scan or similar node.
  */
 function findSourceRelation(node: PlanNode): PlanNode {
-	// Keep going up until we find a table scan or values node
+	// Keep going up until we find a values node
 	let current = node;
 	while (current) {
-		if (current.nodeType === 'TableScan' || current.nodeType === 'Values' || current.nodeType === 'SingleRow') {
+		if (current.nodeType === 'Values' || current.nodeType === 'SingleRow') {
 			return current;
 		}
 		// Get the first relational source
@@ -79,11 +79,12 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 
 	// Create row descriptors for context
 	const sourceAttributes = plan.source.getAttributes();
-	const sourceRowDescriptor = buildRowDescriptor(sourceAttributes);
 
-	const sourceRelationRowDescriptor = sourceRelation !== plan.source
+	// Create separate descriptors for group yielding to avoid conflicts with source row processing
+	const groupSourceRowDescriptor = buildRowDescriptor(sourceAttributes);
+	const groupSourceRelationRowDescriptor = sourceRelation !== plan.source
 		? buildRowDescriptor((sourceRelation as any).getAttributes?.() || sourceAttributes)
-		: sourceRowDescriptor;
+		: groupSourceRowDescriptor;
 
 	ctxLog('StreamAggregate setup: source=%s, sourceRelation=%s', plan.source.nodeType, sourceRelation.nodeType);
 	ctxLog('Source attributes: %O', sourceAttributes.map(attr => `${attr.name}(#${attr.id})`));
@@ -95,13 +96,16 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 	// Create output row descriptor for the StreamAggregate's output
 	const outputRowDescriptor = buildRowDescriptor(plan.getAttributes());
 
+	// Create scan row descriptor for source relation attributes (for Filter evaluation)
+	const scanRowDescriptor = buildRowDescriptor(sourceAttributes);
+
 	// CRITICAL FIX: Create a combined descriptor that includes BOTH output and source attributes
 	// This allows correlated subqueries to access original table attributes
-	const combinedRowDescriptor: RowDescriptor = [...outputRowDescriptor];
+	const combinedRowDescriptor: RowDescriptor = {...outputRowDescriptor};
 	sourceAttributes.forEach((attr, index) => {
 		// Only add if not already present in output (avoid conflicts)
 		if (combinedRowDescriptor[attr.id] === undefined) {
-			combinedRowDescriptor[attr.id] = index;
+			combinedRowDescriptor[attr.id] = Object.keys(outputRowDescriptor).length + index;
 		}
 	});
 
@@ -182,15 +186,16 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 				) : new BTree<SqlValue | SqlValue[], SqlValue | SqlValue[]>((val: SqlValue | SqlValue[]) => val, compareDistinctValues) // Empty tree for non-distinct
 			);
 
+			// Track the last source row for representative row in combined descriptor
+			let lastSourceRow: Row | null = null;
+
 			// Process all rows
 			for await (const row of sourceRows) {
-				// Set the current row in the runtime context for evaluation using row descriptors
-				ctx.context.set(sourceRowDescriptor, () => row);
-				logContextPush(sourceRowDescriptor, 'source-row', sourceAttributes);
-				if (sourceRelation !== plan.source) {
-					ctx.context.set(sourceRelationRowDescriptor, () => row);
-					logContextPush(sourceRelationRowDescriptor, 'source-relation-row');
-				}
+				lastSourceRow = row;
+
+				// Set the current row in the runtime context for Filter and aggregate evaluation
+				ctx.context.set(scanRowDescriptor, () => row);
+				logContextPush(scanRowDescriptor, 'scan-row', sourceAttributes);
 
 				try {
 					// For each aggregate, call its step function
@@ -234,18 +239,14 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 						}
 					}
 				} finally {
-					// Clean up context for this row
-					logContextPop(sourceRowDescriptor, 'source-row');
-					ctx.context.delete(sourceRowDescriptor);
-					if (sourceRelation !== plan.source) {
-						logContextPop(sourceRelationRowDescriptor, 'source-relation-row');
-						ctx.context.delete(sourceRelationRowDescriptor);
-					}
+					// Clean up scan context for this row
+					logContextPop(scanRowDescriptor, 'scan-row');
+					ctx.context.delete(scanRowDescriptor);
 				}
 			}
 
 			// Finalize and yield the result
-			const resultRow: SqlValue[] = [];
+			const aggregateRow: SqlValue[] = [];
 			for (let i = 0; i < plan.aggregates.length; i++) {
 				const schema = aggregateSchemas[i];
 
@@ -256,18 +257,28 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 					finalValue = accumulators[i];
 				}
 
-				resultRow.push(finalValue);
+				aggregateRow.push(finalValue);
 			}
 
+			// Build combined row with aggregate results + representative source row
+			const fullRow = lastSourceRow ? [...aggregateRow, ...lastSourceRow] : aggregateRow;
+
 			// Set up combined context for the result row (includes both output and source attributes)
-			ctx.context.set(outputRowDescriptor, () => resultRow);
-			logContextPush(outputRowDescriptor, 'output-row');
-			// Note: For no GROUP BY case, we can't preserve source row context since we processed multiple rows
+			if (lastSourceRow) {
+				ctx.context.set(scanRowDescriptor, () => lastSourceRow);
+				logContextPush(scanRowDescriptor, 'aggregate-rep-row');
+			}
+			ctx.context.set(combinedRowDescriptor, () => fullRow);
+			logContextPush(combinedRowDescriptor, 'aggregate-full-row');
 			try {
-				yield resultRow;
+				yield aggregateRow;
 			} finally {
-				logContextPop(outputRowDescriptor, 'output-row');
-				ctx.context.delete(outputRowDescriptor);
+				logContextPop(combinedRowDescriptor, 'aggregate-full-row');
+				ctx.context.delete(combinedRowDescriptor);
+				if (lastSourceRow) {
+					logContextPop(scanRowDescriptor, 'aggregate-rep-row');
+					ctx.context.delete(scanRowDescriptor);
+				}
 			}
 		} else {
 			// Handle GROUP BY case with streaming aggregation
@@ -278,17 +289,19 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 			let currentSourceRow: Row | null = null; // Track the current group's representative row
 			let currentAccumulators: any[] = [];
 			let currentDistinctTrees: BTree<SqlValue | SqlValue[], SqlValue | SqlValue[]>[] = [];
+			let cleanupPreviousGroupContext: (() => void) | null = null;
 
 			// Process all rows
 			for await (const row of sourceRows) {
-				// Set the current row in the runtime context for evaluation using row descriptors
-				ctx.context.set(sourceRowDescriptor, () => row);
-				logContextPush(sourceRowDescriptor, 'source-row', sourceAttributes);
-				if (sourceRelation !== plan.source) {
-					ctx.context.set(sourceRelationRowDescriptor, () => row);
-					logContextPush(sourceRelationRowDescriptor, 'source-relation-row');
+				if (cleanupPreviousGroupContext) {
+					cleanupPreviousGroupContext();
+					cleanupPreviousGroupContext = null;
 				}
 
+				// Set the current row in the runtime context for Filter and GROUP BY evaluation
+				ctx.context.set(scanRowDescriptor, () => row);
+				logContextPush(scanRowDescriptor, 'scan-row', sourceAttributes);
+
 				try {
 					// Evaluate GROUP BY expressions to determine the group
 					const groupValues: SqlValue[] = [];
@@ -323,11 +336,14 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 
 					// Check if we've moved to a new group using proper SQL value comparison
 					if (currentGroupKey !== null && compareGroupKeys(currentGroupKey, groupValues) !== 0) {
+						// CRITICAL: Save the previous group's representative row before yielding
+						const previousGroupSourceRow = currentSourceRow;
+
 						// Yield the previous group's results
-						const resultRow: SqlValue[] = [];
+						const aggregateRow: SqlValue[] = [];
 
 						// First, add the GROUP BY values
-						resultRow.push(...currentGroupValues);
+						aggregateRow.push(...currentGroupValues);
 
 						// Then, add the finalized aggregate values
 						for (let i = 0; i < plan.aggregates.length; i++) {
@@ -340,37 +356,49 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 								finalValue = currentAccumulators[i];
 							}
 
-							resultRow.push(finalValue);
+							aggregateRow.push(finalValue);
 						}
 
-						// Set up combined context that allows access to both
-						// the aggregated result AND the original source row attributes
-						ctx.context.set(outputRowDescriptor, () => resultRow);
-						logContextPush(outputRowDescriptor, 'output-row-groupby');
-						if (currentSourceRow) {
-							// Also provide access to a representative source row for this group
-							// This enables correlated subqueries to access original table attributes
-							ctx.context.set(sourceRowDescriptor, () => currentSourceRow!);
-							logContextPush(sourceRowDescriptor, 'source-row-groupby', sourceAttributes);
+						// Build combined row with aggregate results + representative source row
+						const fullRow = previousGroupSourceRow ? [...aggregateRow, ...previousGroupSourceRow] : aggregateRow;
+
+						// Set up context with the PREVIOUS group's representative row (not the current row)
+						if (previousGroupSourceRow) {
+							ctx.context.set(scanRowDescriptor, () => previousGroupSourceRow);
+							logContextPush(scanRowDescriptor, 'group-rep-row');
+						}
+						ctx.context.set(combinedRowDescriptor, () => fullRow);
+						logContextPush(combinedRowDescriptor, 'output-row-groupby');
+						if (previousGroupSourceRow) {
+							// Use the previous group's representative row for HAVING evaluation
+							// Use separate descriptors to avoid conflicts with source row processing
+							ctx.context.set(groupSourceRowDescriptor, () => previousGroupSourceRow!);
+							logContextPush(groupSourceRowDescriptor, 'source-row-groupby', sourceAttributes);
 							if (sourceRelation !== plan.source) {
-								ctx.context.set(sourceRelationRowDescriptor, () => currentSourceRow!);
-								logContextPush(sourceRelationRowDescriptor, 'source-relation-row-groupby');
+								ctx.context.set(groupSourceRelationRowDescriptor, () => previousGroupSourceRow!);
+								logContextPush(groupSourceRelationRowDescriptor, 'source-relation-row-groupby');
 							}
 						}
-						try {
-							yield resultRow;
-						} finally {
-							logContextPop(outputRowDescriptor, 'output-row-groupby');
-							ctx.context.delete(outputRowDescriptor);
-							if (currentSourceRow) {
-								logContextPop(sourceRowDescriptor, 'source-row-groupby');
-								ctx.context.delete(sourceRowDescriptor);
+
+						// Defer context cleanup
+						cleanupPreviousGroupContext = () => {
+							logContextPop(combinedRowDescriptor, 'output-row-groupby');
+							ctx.context.delete(combinedRowDescriptor);
+							if (previousGroupSourceRow) {
+								logContextPop(scanRowDescriptor, 'group-rep-row');
+								ctx.context.delete(scanRowDescriptor);
+							}
+							if (previousGroupSourceRow) {
+								logContextPop(groupSourceRowDescriptor, 'source-row-groupby');
+								ctx.context.delete(groupSourceRowDescriptor);
 								if (sourceRelation !== plan.source) {
-									logContextPop(sourceRelationRowDescriptor, 'source-relation-row-groupby');
-									ctx.context.delete(sourceRelationRowDescriptor);
+									logContextPop(groupSourceRelationRowDescriptor, 'source-relation-row-groupby');
+									ctx.context.delete(groupSourceRelationRowDescriptor);
 								}
 							}
-						}
+						};
+
+						yield aggregateRow;
 
 						// Reset for new group
 						currentAccumulators = aggregateSchemas.map(schema => {
@@ -392,6 +420,8 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 								compareDistinctValues
 							) : new BTree<SqlValue | SqlValue[], SqlValue | SqlValue[]>((val: SqlValue | SqlValue[]) => val, compareDistinctValues)
 						);
+						// Set representative row for the new group (which is the current row)
+						currentSourceRow = row;
 					}
 
 					// Initialize if first group
@@ -415,12 +445,13 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 								compareDistinctValues
 							) : new BTree<SqlValue | SqlValue[], SqlValue | SqlValue[]>((val: SqlValue | SqlValue[]) => val, compareDistinctValues)
 						);
+						// Set representative row for the first group
+						currentSourceRow = row;
 					}
 
 					// Update current group
 					currentGroupKey = groupValues;
 					currentGroupValues = groupValues;
-					currentSourceRow = row; // Keep a representative row for this group
 
 					// For each aggregate, call its step function using the pre-evaluated arguments
 					for (let i = 0; i < plan.aggregates.length; i++) {
@@ -444,22 +475,23 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 						}
 					}
 				} finally {
-					// Clean up context for this row
-					logContextPop(sourceRowDescriptor, 'source-row');
-					ctx.context.delete(sourceRowDescriptor);
-					if (sourceRelation !== plan.source) {
-						logContextPop(sourceRelationRowDescriptor, 'source-relation-row');
-						ctx.context.delete(sourceRelationRowDescriptor);
-					}
+					// Clean up scan context for this row
+					logContextPop(scanRowDescriptor, 'scan-row');
+					ctx.context.delete(scanRowDescriptor);
 				}
 			}
 
+			if (cleanupPreviousGroupContext) {
+				cleanupPreviousGroupContext();
+				cleanupPreviousGroupContext = null;
+			}
+
 			// Yield the final group if any rows were processed
 			if (currentGroupKey !== null) {
-				const resultRow: SqlValue[] = [];
+				const aggregateRow: SqlValue[] = [];
 
 				// First, add the GROUP BY values
-				resultRow.push(...currentGroupValues);
+				aggregateRow.push(...currentGroupValues);
 
 				// Then, add the finalized aggregate values
 				for (let i = 0; i < plan.aggregates.length; i++) {
@@ -472,31 +504,45 @@ export function emitStreamAggregate(plan: StreamAggregateNode, ctx: EmissionCont
 						finalValue = currentAccumulators[i];
 					}
 
-					resultRow.push(finalValue);
+					aggregateRow.push(finalValue);
 				}
 
-				// CRITICAL FIX: Set up combined context for final group
-				ctx.context.set(outputRowDescriptor, () => resultRow);
-				logContextPush(outputRowDescriptor, 'final-output-row');
+				// Build combined row with aggregate results + representative source row
+				const fullRow = currentSourceRow ? [...aggregateRow, ...currentSourceRow] : aggregateRow;
+
+				// Set up context for final group with correct source row
+				if (currentSourceRow) {
+					ctx.context.set(scanRowDescriptor, () => currentSourceRow);
+					logContextPush(scanRowDescriptor, 'final-group-rep-row');
+				}
+				ctx.context.set(combinedRowDescriptor, () => fullRow);
+				logContextPush(combinedRowDescriptor, 'final-output-row');
 				if (currentSourceRow) {
-					ctx.context.set(sourceRowDescriptor, () => currentSourceRow);
-					logContextPush(sourceRowDescriptor, 'final-source-row', sourceAttributes);
+					// Use the final group's representative row for HAVING evaluation
+					// Use separate descriptors to avoid conflicts with source row processing
+					ctx.context.set(groupSourceRowDescriptor, () => currentSourceRow!);
+					logContextPush(groupSourceRowDescriptor, 'final-source-row', sourceAttributes);
 					if (sourceRelation !== plan.source) {
-						ctx.context.set(sourceRelationRowDescriptor, () => currentSourceRow);
-						logContextPush(sourceRelationRowDescriptor, 'final-source-relation-row');
+						ctx.context.set(groupSourceRelationRowDescriptor, () => currentSourceRow!);
+						logContextPush(groupSourceRelationRowDescriptor, 'final-source-relation-row');
 					}
 				}
+
 				try {
-					yield resultRow;
+					yield aggregateRow;
 				} finally {
-					logContextPop(outputRowDescriptor, 'final-output-row');
-					ctx.context.delete(outputRowDescriptor);
+					logContextPop(combinedRowDescriptor, 'final-output-row');
+					ctx.context.delete(combinedRowDescriptor);
+					if (currentSourceRow) {
+						logContextPop(scanRowDescriptor, 'final-group-rep-row');
+						ctx.context.delete(scanRowDescriptor);
+					}
 					if (currentSourceRow) {
-						logContextPop(sourceRowDescriptor, 'final-source-row');
-						ctx.context.delete(sourceRowDescriptor);
+						logContextPop(groupSourceRowDescriptor, 'final-source-row');
+						ctx.context.delete(groupSourceRowDescriptor);
 						if (sourceRelation !== plan.source) {
-							logContextPop(sourceRelationRowDescriptor, 'final-source-relation-row');
-							ctx.context.delete(sourceRelationRowDescriptor);
+							logContextPop(groupSourceRelationRowDescriptor, 'final-source-relation-row');
+							ctx.context.delete(groupSourceRelationRowDescriptor);
 						}
 					}
 				}

package/src/runtime/emit/between.ts

@@ -0,0 +1,51 @@
+import type { SqlValue } from "../../common/types.js";
+import type { Instruction, InstructionRun, RuntimeContext } from "../types.js";
+import type { BetweenNode } from "../../planner/nodes/scalar.js";
+import { emitPlanNode } from "../emitters.js";
+import { compareSqlValuesFast, resolveCollation } from "../../util/comparison.js";
+import { coerceForComparison } from "../../util/coercion.js";
+import type { EmissionContext } from "../emission-context.js";
+
+export function emitBetween(plan: BetweenNode, ctx: EmissionContext): Instruction {
+	// Pre-resolve collation function for optimal performance (using BINARY as default for BETWEEN)
+	const collationFunc = resolveCollation('BINARY');
+
+	function run(ctx: RuntimeContext, value: SqlValue, lowerBound: SqlValue, upperBound: SqlValue): SqlValue {
+		// SQL BETWEEN logic: value BETWEEN lower AND upper
+		// Equivalent to: value >= lower AND value <= upper
+		// NULL handling: if any operand is NULL, result is NULL
+		if (value === null || lowerBound === null || upperBound === null) {
+			return null;
+		}
+
+		// Apply type coercion before comparison
+		const [coercedValue1, coercedLower] = coerceForComparison(value, lowerBound);
+		const [coercedValue2, coercedUpper] = coerceForComparison(value, upperBound);
+
+		// Use pre-resolved collation function for optimal performance
+		const lowerResult = compareSqlValuesFast(coercedValue1, coercedLower, collationFunc);
+		const upperResult = compareSqlValuesFast(coercedValue2, coercedUpper, collationFunc);
+
+		// value >= lowerBound AND value <= upperBound
+		const betweenResult = (lowerResult >= 0 && upperResult <= 0) ? 1 : 0;
+
+		// Handle NOT BETWEEN
+		if (plan.expression.not) {
+			return betweenResult ? 0 : 1;
+		}
+
+		return betweenResult;
+	}
+
+	const valueExpr = emitPlanNode(plan.expr, ctx);
+	const lowerExpr = emitPlanNode(plan.lower, ctx);
+	const upperExpr = emitPlanNode(plan.upper, ctx);
+
+	const notPrefix = plan.expression.not ? 'NOT ' : '';
+
+	return {
+		params: [valueExpr, lowerExpr, upperExpr],
+		run: run as InstructionRun,
+		note: `${notPrefix}BETWEEN`
+	};
+}