@quereus/quereus 0.1.0 → 0.2.1

package/src/runtime/emit/window.ts

@@ -1,6 +1,6 @@
 import type { WindowNode } from '../../planner/nodes/window-node.js';
 import type { Instruction, RuntimeContext } from '../types.js';
-import type { Row, SqlValue } from '../../common/types.js';
+import type { OutputValue, Row, SqlValue } from '../../common/types.js';
 import type { EmissionContext } from '../emission-context.js';
 import { emitPlanNode, emitCallFromPlan } from '../emitters.js';
 import { resolveWindowFunction } from '../../schema/window-function.js';
@@ -10,6 +10,7 @@ import { compareSqlValues, createOrderByComparatorFast, resolveCollation } from
 import { createLogger } from '../../common/logger.js';
 import { buildRowDescriptor } from '../../util/row-descriptor.js';
 import { RowDescriptor } from '../../planner/nodes/plan-node.js';
+import { withRowContext, withAsyncRowContext } from '../context-helpers.js';
 
 const log = createLogger('runtime:emit:window');
 
@@ -45,7 +46,7 @@ export function emitWindow(plan: WindowNode, ctx: EmissionContext): Instruction
 	async function* run(
 		rctx: RuntimeContext,
 		source: AsyncIterable<Row>,
-		...callbacks: Array<(ctx: RuntimeContext) => any>
+		...callbacks: Array<(ctx: RuntimeContext) => OutputValue>
 	): AsyncIterable<Row> {
 		log('Starting window function execution');
 
@@ -113,23 +114,22 @@ async function groupByPartitions(
 	const partitions = new Map<string, Row[]>();
 
 	for (const row of rows) {
-		rctx.context.set(sourceRowDescriptor, () => row);
-		try {
+		const partitionKey = await withAsyncRowContext(rctx, sourceRowDescriptor, () => row, async () => {
 			// Evaluate partition expressions
-			const partitionValues = partitionCallbacks.map(callback => callback(rctx));
+			const partitionValues = await Promise.all(partitionCallbacks.map(callback =>
+				callback(rctx)
+			));
 
 			// Create partition key
-			const partitionKey = partitionValues.map(val =>
+			return partitionValues.map(val =>
 				val === null ? 'NULL' : String(val)
 			).join('|');
+		});
 
-			if (!partitions.has(partitionKey)) {
-				partitions.set(partitionKey, []);
-			}
-			partitions.get(partitionKey)!.push(row);
-		} finally {
-			rctx.context.delete(sourceRowDescriptor);
+		if (!partitions.has(partitionKey)) {
+			partitions.set(partitionKey, []);
 		}
+		partitions.get(partitionKey)!.push(row);
 	}
 
 	return partitions;
@@ -142,9 +142,9 @@ async function* processPartition(
 	rctx: RuntimeContext,
 	sourceRowDescriptor: RowDescriptor,
 	outputRowDescriptor: RowDescriptor,
-	partitionCallbacks: Array<(ctx: RuntimeContext) => any>,
-	orderByCallbacks: Array<(ctx: RuntimeContext) => any>,
-	funcArgCallbacks: Array<((ctx: RuntimeContext) => any) | null>
+	partitionCallbacks: Array<(ctx: RuntimeContext) => OutputValue>,
+	orderByCallbacks: Array<(ctx: RuntimeContext) => OutputValue>,
+	funcArgCallbacks: Array<(ctx: RuntimeContext) => OutputValue | null>
 ): AsyncIterable<Row> {
 	// Sort rows according to ORDER BY specification
 	const sortedRows = await sortRows(
@@ -158,8 +158,8 @@ async function* processPartition(
 		const outputRow = [...currentRow];
 
 		// Set up context for current row
-		rctx.context.set(sourceRowDescriptor, () => currentRow);
-		try {
+		const outputValues = await withRowContext(rctx, sourceRowDescriptor, () => currentRow, async () => {
+			const values: SqlValue[] = [];
 			// Compute each window function
 			for (let funcIndex = 0; funcIndex < plan.functions.length; funcIndex++) {
 				const func = plan.functions[funcIndex];
@@ -169,7 +169,7 @@ async function* processPartition(
 				let value: SqlValue;
 
 				if (schema.kind === 'ranking') {
-					value = computeRankingFunction(
+					value = await computeRankingFunction(
 						func.functionName, sortedRows, currentIndex,
 						orderByCallbacks, rctx, sourceRowDescriptor
 					);
@@ -186,26 +186,23 @@ async function* processPartition(
 					);
 				}
 
-				outputRow.push(value);
+				values.push(value);
 			}
-		} finally {
-			rctx.context.delete(sourceRowDescriptor);
-		}
+			return values;
+		});
+
+		// Add computed values to output row
+		outputRow.push(...outputValues);
 
 		// Yield the output row
-		rctx.context.set(outputRowDescriptor, () => outputRow as Row);
-		try {
-			yield outputRow as Row;
-		} finally {
-			rctx.context.delete(outputRowDescriptor);
-		}
+		yield await withRowContext(rctx, outputRowDescriptor, () => outputRow as Row, () => outputRow as Row);
 	}
 }
 
 async function sortRows(
 	rows: Row[],
 	orderBy: any[],
-	orderByCallbacks: Array<(ctx: RuntimeContext) => any>,
+	orderByCallbacks: Array<(ctx: RuntimeContext) => OutputValue>,
 	rctx: RuntimeContext,
 	sourceRowDescriptor: RowDescriptor
 ): Promise<Row[]> {
@@ -220,34 +217,29 @@ async function sortRows(
 		const collationFunc = resolveCollation('BINARY');
 		return createOrderByComparatorFast(
 			orderClause.direction,
-			(orderClause as any).nullsOrdering,
+			orderClause.nulls,
 			collationFunc
 		);
 	});
 
-	return [...rows].sort((a, b) => {
+	// Pre-evaluate ORDER BY values for all rows to avoid async in sort
+	const rowsWithValues = await Promise.all(rows.map(async (row) => {
+		const values = await Promise.all(orderByCallbacks.map(async (callback) => {
+			return await withAsyncRowContext(rctx, sourceRowDescriptor, () => row, async () => {
+				const result = callback(rctx);
+				return await Promise.resolve(result);
+			});
+		}));
+		return { row, values };
+	}));
+
+	// Now sort using the pre-evaluated values
+	rowsWithValues.sort((a, b) => {
 		// Compare each ORDER BY expression in sequence
 		for (let i = 0; i < orderBy.length; i++) {
-			const callback = orderByCallbacks[i];
 			const comparator = orderByComparators[i];
-
-			// Evaluate expression for row A
-			rctx.context.set(sourceRowDescriptor, () => a);
-			let valueA: SqlValue;
-			try {
-				valueA = callback(rctx);
-			} finally {
-				rctx.context.delete(sourceRowDescriptor);
-			}
-
-			// Evaluate expression for row B
-			rctx.context.set(sourceRowDescriptor, () => b);
-			let valueB: SqlValue;
-			try {
-				valueB = callback(rctx);
-			} finally {
-				rctx.context.delete(sourceRowDescriptor);
-			}
+			const valueA = a.values[i] as SqlValue;
+			const valueB = b.values[i] as SqlValue;
 
 			// Use pre-created optimized comparator
 			const comparison = comparator(valueA, valueB);
@@ -262,16 +254,19 @@ async function sortRows(
 
 		return 0; // All ORDER BY expressions are equal
 	});
+
+	// Extract just the rows in sorted order
+	return rowsWithValues.map(item => item.row);
 }
 
-function computeRankingFunction(
+async function computeRankingFunction(
 	functionName: string,
 	sortedRows: Row[],
 	currentIndex: number,
 	orderByCallbacks: Array<(ctx: RuntimeContext) => any>,
 	rctx: RuntimeContext,
 	sourceRowDescriptor: RowDescriptor
-): number {
+): Promise<number> {
 	switch (functionName.toLowerCase()) {
 		case 'row_number':
 			return currentIndex + 1;
@@ -283,9 +278,9 @@ function computeRankingFunction(
 
 			for (let i = 0; i < currentIndex; i++) {
 				const prevRow = sortedRows[i];
-				if (!areRowsEqualInOrderBy(
+				if (!(await areRowsEqualInOrderBy(
 					prevRow, currentRow, orderByCallbacks, rctx, sourceRowDescriptor
-				)) {
+				))) {
 					rank = i + 2; // Rank is 1-based and accounts for ties
 				}
 			}
@@ -300,11 +295,11 @@ function computeRankingFunction(
 
 			for (let i = 0; i < currentIndex; i++) {
 				const prevRow = sortedRows[i];
-				if (!areRowsEqualInOrderBy(
+				if (!(await areRowsEqualInOrderBy(
 					prevRow, currentRow, orderByCallbacks, rctx, sourceRowDescriptor
-				)) {
+				))) {
 					// Create a key for this distinct set of ORDER BY values
-					const key = getOrderByKey(prevRow, orderByCallbacks, rctx, sourceRowDescriptor);
+					const key = await getOrderByKey(prevRow, orderByCallbacks, rctx, sourceRowDescriptor);
 					if (!seenValues.has(key)) {
 						seenValues.add(key);
 						denseRank++;
@@ -335,20 +330,20 @@ async function computeAggregateFunction(
 	// Determine frame bounds
 	const frameBounds = getFrameBounds(frame, sortedRows.length, currentIndex, hasOrderBy);
 
-	let accumulator = null;
+	let accumulator: any = null;
 	let rowCount = 0;
 
 	// Process rows within the frame
 	for (let i = frameBounds.start; i <= frameBounds.end; i++) {
 		const frameRow = sortedRows[i];
 
-		rctx.context.set(sourceRowDescriptor, () => frameRow);
-		try {
+		await withAsyncRowContext(rctx, sourceRowDescriptor, () => frameRow, async () => {
 			let argValue: SqlValue = null;
 
 			// Get argument value if callback exists
 			if (argCallback) {
-				argValue = argCallback(rctx);
+				const result = argCallback(rctx);
+				argValue = await Promise.resolve(result);
 			}
 
 			// Apply aggregate step function
@@ -356,9 +351,7 @@ async function computeAggregateFunction(
 				accumulator = schema.step(accumulator, argValue);
 				rowCount++;
 			}
-		} finally {
-			rctx.context.delete(sourceRowDescriptor);
-		}
+		});
 	}
 
 	// Apply final function
@@ -421,31 +414,25 @@ function getFrameBounds(
 	return { start, end };
 }
 
-function areRowsEqualInOrderBy(
+async function areRowsEqualInOrderBy(
 	rowA: Row,
 	rowB: Row,
 	orderByCallbacks: Array<(ctx: RuntimeContext) => any>,
 	rctx: RuntimeContext,
 	sourceRowDescriptor: RowDescriptor
-): boolean {
+): Promise<boolean> {
 	for (const callback of orderByCallbacks) {
 		// Get value for row A
-		rctx.context.set(sourceRowDescriptor, () => rowA);
-		let valueA: SqlValue;
-		try {
-			valueA = callback(rctx);
-		} finally {
-			rctx.context.delete(sourceRowDescriptor);
-		}
+		const valueA = await withAsyncRowContext(rctx, sourceRowDescriptor, () => rowA, async () => {
+			const result = callback(rctx);
+			return await Promise.resolve(result);
+		});
 
 		// Get value for row B
-		rctx.context.set(sourceRowDescriptor, () => rowB);
-		let valueB: SqlValue;
-		try {
-			valueB = callback(rctx);
-		} finally {
-			rctx.context.delete(sourceRowDescriptor);
-		}
+		const valueB = await withAsyncRowContext(rctx, sourceRowDescriptor, () => rowB, async () => {
+			const result = callback(rctx);
+			return await Promise.resolve(result);
+		});
 
 		// If any ORDER BY expression differs, rows are not equal
 		if (compareSqlValues(valueA, valueB) !== 0) {
@@ -456,17 +443,16 @@ function areRowsEqualInOrderBy(
 	return true; // All ORDER BY expressions are equal
 }
 
-function getOrderByKey(
+async function getOrderByKey(
 	row: Row,
 	orderByCallbacks: Array<(ctx: RuntimeContext) => any>,
 	rctx: RuntimeContext,
 	sourceRowDescriptor: RowDescriptor
-): string {
-	rctx.context.set(sourceRowDescriptor, () => row);
-	try {
-		const values = orderByCallbacks.map(callback => callback(rctx));
+): Promise<string> {
+	return await withAsyncRowContext(rctx, sourceRowDescriptor, () => row, async () => {
+		const values = await Promise.all(orderByCallbacks.map(callback =>
+			Promise.resolve(callback(rctx))
+		));
 		return values.map(val => val === null ? 'NULL' : String(val)).join('|');
-	} finally {
-		rctx.context.delete(sourceRowDescriptor);
-	}
+	});
 }

package/src/runtime/emitters.ts

@@ -61,12 +61,63 @@ export function getEmitterMeta(nodeType: PlanNodeType): EmitterMeta | undefined
 	return registration?.meta;
 }
 
+/**
+ * Wraps an instruction's run function with plan node stack tracking for debugging.
+ * Only adds overhead when tracing is enabled.
+ */
+function instrumentRunForTracing(plan: PlanNode, originalRun: InstructionRun): InstructionRun {
+	return function (ctx: RuntimeContext, ...args: any[]) {
+		const stack = (ctx.planStack = ctx.planStack || []);
+		stack.push(plan);
+
+		let result: any;
+		try {
+			result = originalRun(ctx, ...args);
+		} catch (err) {
+			// Synchronous error – pop immediately and re-throw
+			stack.pop();
+			throw err;
+		}
+
+		// If the result is an async iterable, defer the pop until iteration completes
+		if (result && typeof result === 'object' && Symbol.asyncIterator in result) {
+			const iterable = result as AsyncIterable<unknown>;
+			// Wrap iterable to pop stack in a finally block once iteration ends
+			return (async function* () {
+				try {
+					for await (const item of iterable) {
+						yield item;
+					}
+				} finally {
+					stack.pop();
+				}
+			})();
+		}
+
+		// If the result is a promise, pop once it settles
+		if (result && typeof (result as Promise<unknown>).then === 'function') {
+			return (result as Promise<unknown>).finally(() => {
+				stack.pop();
+			});
+		}
+
+		// Synchronous return value – pop immediately
+		stack.pop();
+		return result;
+	};
+}
+
 export function emitPlanNode(plan: PlanNode, ctx: EmissionContext): Instruction {
 	const registration = emitters.get(plan.nodeType);
 	if (!registration) {
 		throw new QuereusError(`No emitter registered for ${plan.nodeType}`, StatusCode.ERROR);
 	}
-	return registration.emitter(plan, ctx);
+	const instruction = registration.emitter(plan, ctx);
+	// Wrap with instrumentation for tracing
+	if (ctx.tracePlanStack) {
+		instruction.run = instrumentRunForTracing(plan, instruction.run);
+	}
+	return instruction;
 }
 
 /**

package/src/runtime/register.ts

@@ -13,7 +13,8 @@ import { emitDropTable } from './emit/drop-table.js';
 import { emitCreateView } from './emit/create-view.js';
 import { emitDropView } from './emit/drop-view.js';
 import { emitCTE } from './emit/cte.js';
-import { emitTableReference } from './emit/table-reference.js';
+import { emitCTEReference } from './emit/cte-reference.js';
+import { emitInternalRecursiveCTERef } from './emit/internal-recursive-cte-ref.js';
 import { emitInsert } from './emit/insert.js';
 import { emitUpdate } from './emit/update.js';
 import { emitDmlExecutor } from './emit/dml-executor.js';
@@ -45,7 +46,7 @@ import { emitLoopJoin } from './emit/join.js';
 import { emitCache } from './emit/cache.js';
 import { emitReturning } from './emit/returning.js';
 import { emitSink } from './emit/sink.js';
-import { emitCTEReference } from './emit/cte-reference.js';
+import { emitBetween } from './emit/between.js';
 
 let registered = false;
 
@@ -67,14 +68,14 @@ export function registerEmitters() {
 	registerEmitter(PlanNodeType.CaseExpr, emitCaseExpr as EmitterFunc);
 	registerEmitter(PlanNodeType.Cast, emitCast as EmitterFunc);
 	registerEmitter(PlanNodeType.Collate, emitCollate as EmitterFunc);
+	registerEmitter(PlanNodeType.Between, emitBetween as EmitterFunc);
 	registerEmitter(PlanNodeType.ScalarSubquery, emitScalarSubquery as EmitterFunc);
 	registerEmitter(PlanNodeType.Exists, emitExists as EmitterFunc);
 
 	// Relational emitters (mix of logical and physical for now)
 	registerEmitter(PlanNodeType.Block, emitBlock as EmitterFunc);
-	registerEmitter(PlanNodeType.TableReference, emitTableReference as EmitterFunc);
 	registerEmitter(PlanNodeType.CTEReference, emitCTEReference as EmitterFunc);
-	registerEmitter(PlanNodeType.TableScan, emitSeqScan as EmitterFunc);
+	registerEmitter(PlanNodeType.InternalRecursiveCTERef, emitInternalRecursiveCTERef as EmitterFunc);
 
 	// Physical access node emitters (Phase 1)
 	registerEmitter(PlanNodeType.SeqScan, emitSeqScan as EmitterFunc);

package/src/runtime/scheduler.ts

@@ -2,8 +2,10 @@ import type { Instruction, RuntimeContext, InstructionRuntimeStats } from "./typ
 import type { OutputValue, RuntimeValue, Row } from "../common/types.js";
 import { isAsyncIterable } from "./utils.js";
 import { createLogger } from "../common/logger.js";
+import { DefaultContextTracker } from './types.js';
 
 const log = createLogger('runtime:metrics');
+const contextLog = createLogger('runtime:context');
 
 type ResultDestination = number | null;
 
@@ -71,13 +73,28 @@ export class Scheduler {
 	}
 
 	run(ctx: RuntimeContext): OutputValue {
+		// Initialize context tracker if not already present
+		if (!ctx.contextTracker) {
+			ctx.contextTracker = new DefaultContextTracker();
+		}
+
+		let result: OutputValue;
+
 		if (ctx.enableMetrics) {
-			return this.runWithMetrics(ctx);
+			result = this.runWithMetrics(ctx);
 		} else if (!ctx.tracer) {
-			return this.runOptimized(ctx);
+			result = this.runOptimized(ctx);
 		} else {
-			return this.runWithTracing(ctx);
+			result = this.runWithTracing(ctx);
 		}
+
+		// Check for remaining contexts and warn rather than error
+		if (ctx.contextTracker && ctx.contextTracker.hasRemainingContexts()) {
+			const remaining = ctx.contextTracker.getRemainingContexts();
+			contextLog('Context leak detected - remaining contexts:', remaining.map(c => c.source));
+		}
+
+		return result;
 	}
 
 	private runOptimized(ctx: RuntimeContext): OutputValue {
@@ -164,7 +181,6 @@ export class Scheduler {
 			const args = instrArgs[i]!;	// Guaranteed not to contain promises
 			instrArgs[i] = undefined; // Clear args as we go to minimize memory usage.
 
-
 			// Trace input
 			ctx.tracer!.traceInput(i, instruction, args as RuntimeValue[]);
 
@@ -386,12 +402,12 @@ export class Scheduler {
 					stats.elapsedNs += process.hrtime.bigint() - start;
 					throw error;
 				});
-			} else {
-				// Sync result
-				stats.out += this.countOutputs(result);
-				stats.elapsedNs += process.hrtime.bigint() - start;
-				return result;
 			}
+
+			stats.out += this.countOutputs(result);
+			stats.elapsedNs += process.hrtime.bigint() - start;
+
+			return result;
 		} catch (error) {
 			stats.elapsedNs += process.hrtime.bigint() - start;
 			throw error;
@@ -406,13 +422,10 @@ export class Scheduler {
 		stats.in += this.countInputs(args);
 
 		try {
-			const result = instruction.run(ctx, ...args);
-			const resolved = result instanceof Promise ? await result : result;
-
-			stats.out += this.countOutputs(resolved);
+			const result = await instruction.run(ctx, ...args);
+			stats.out += this.countOutputs(result);
 			stats.elapsedNs += process.hrtime.bigint() - start;
-
-			return resolved;
+			return result;
 		} catch (error) {
 			stats.elapsedNs += process.hrtime.bigint() - start;
 			throw error;
@@ -420,65 +433,52 @@ export class Scheduler {
 	}
 
 	private countInputs(args: RuntimeValue[]): number {
-		let count = 0;
-		for (const arg of args) {
-			if (Array.isArray(arg)) {
-				count += arg.length; // Count array elements
-			} else if (isAsyncIterable(arg)) {
-				count += 1; // Count iterables as 1 (we can't know size without consuming)
+		return args.reduce((sum: number, arg) => {
+			if (isAsyncIterable(arg)) {
+				return sum + 1; // Count as 1 for async iterables (we don't know size)
+			} else if (Array.isArray(arg)) {
+				return sum + arg.length;
 			} else {
-				count += 1; // Count other values as 1
+				return sum + 1;
 			}
-		}
-		return count;
+		}, 0);
 	}
 
 	private countOutputs(result: OutputValue): number {
-		if (Array.isArray(result)) {
+		if (isAsyncIterable(result)) {
+			return 1; // Count as 1 for async iterables (we don't know size)
+		} else if (Array.isArray(result)) {
 			return result.length;
-		} else if (isAsyncIterable(result)) {
-			return 1; // Count iterables as 1 (we can't know size without consuming)
 		} else {
 			return 1;
 		}
 	}
 
 	private logAggregateMetrics(): void {
-		if (!log.enabled && !log.extend('stats').enabled) {
-			return;
-		}
-
-		const statsLog = log.extend('stats');
-		statsLog('Execution metrics summary:');
-
-		let totalTime = 0n;
-		for (let i = 0; i < this.instructions.length; i++) {
-			const instruction = this.instructions[i];
-			const stats = instruction.runtimeStats;
-			if (stats) {
-				const elapsedMs = Number(stats.elapsedNs) / 1_000_000;
-				totalTime += stats.elapsedNs;
-
-				statsLog('  [%d] %s: %d exec, %d in, %d out, %.2fms',
-					i,
-					instruction.note || 'unknown',
-					stats.executions,
-					stats.in,
-					stats.out,
-					elapsedMs
-				);
+		if (log.enabled) {
+			let totalExecutions = 0;
+			let totalElapsed = 0n;
+			let totalIn = 0;
+			let totalOut = 0;
+
+			for (const instruction of this.instructions) {
+				if (instruction.runtimeStats) {
+					totalExecutions += instruction.runtimeStats.executions;
+					totalElapsed += instruction.runtimeStats.elapsedNs;
+					totalIn += instruction.runtimeStats.in;
+					totalOut += instruction.runtimeStats.out;
+				}
 			}
-		}
 
-		const totalMs = Number(totalTime) / 1_000_000;
-		statsLog('Total execution time: %.2fms', totalMs);
+			log(`Aggregate metrics: ${totalExecutions} executions, ${totalElapsed / 1000n}μs elapsed, ${totalIn} inputs, ${totalOut} outputs`);
+		}
 	}
 
 	/**
 	 * Get runtime statistics for all instructions
 	 */
 	getMetrics(): InstructionRuntimeStats[] {
-		return this.instructions.map(instr => instr.runtimeStats || {
+		return this.instructions.map(instruction => instruction.runtimeStats || {
 			in: 0,
 			out: 0,
 			elapsedNs: 0n,

package/src/runtime/types.ts

@@ -5,6 +5,7 @@ import type { RowDescriptor, RowGetter, TableDescriptor, TableGetter } from "../
 import type { Scheduler } from "./scheduler.js";
 import type { EmissionContext } from "./emission-context.js";
 import type { VirtualTableConnection } from "../vtab/connection.js";
+import type { PlanNode } from '../planner/nodes/plan-node.js';
 
 export type RuntimeContext = {
 	db: Database;
@@ -20,6 +21,10 @@ export type RuntimeContext = {
 	activeConnection?: VirtualTableConnection;
 	/** Whether to collect runtime execution metrics */
 	enableMetrics: boolean;
+	/** Context tracking for debugging context leaks */
+	contextTracker?: ContextTracker;
+	/** Stack of currently executing plan nodes (only when tracing enabled) */
+	planStack?: PlanNode[];
 };
 
 export type InstructionRun = (ctx: RuntimeContext, ...args: any[]) => OutputValue;
@@ -189,3 +194,43 @@ export class CollectingInstructionTracer implements InstructionTracer {
 		return value;
 	}
 }
+
+/**
+ * Tracks context additions and removals for debugging context leaks
+ */
+export interface ContextTracker {
+	/** Record that a context was added */
+	addContext(descriptor: RowDescriptor, source: string): void;
+	/** Record that a context was removed */
+	removeContext(descriptor: RowDescriptor): void;
+	/** Get all remaining contexts with their sources */
+	getRemainingContexts(): Array<{ descriptor: RowDescriptor; source: string }>;
+	/** Check if there are any remaining contexts */
+	hasRemainingContexts(): boolean;
+}
+
+/**
+ * Default implementation of ContextTracker
+ */
+export class DefaultContextTracker implements ContextTracker {
+	private contexts = new Map<RowDescriptor, string>();
+
+	addContext(descriptor: RowDescriptor, source: string): void {
+		this.contexts.set(descriptor, source);
+	}
+
+	removeContext(descriptor: RowDescriptor): void {
+		this.contexts.delete(descriptor);
+	}
+
+	getRemainingContexts(): Array<{ descriptor: RowDescriptor; source: string }> {
+		return Array.from(this.contexts.entries()).map(([descriptor, source]) => ({
+			descriptor,
+			source
+		}));
+	}
+
+	hasRemainingContexts(): boolean {
+		return this.contexts.size > 0;
+	}
+}