@quereus/quereus 0.1.0

package/src/runtime/cache/shared-cache.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared cache utilities based on the existing working cache emitter
+ * Provides reusable caching patterns for CacheNode, NLJ inner caching, and CTE materialization
+ */
+
+import type { Row } from '../../common/types.js';
+import { createLogger } from '../../common/logger.js';
+
+const log = createLogger('runtime:cache:shared');
+
+/**
+ * Cache strategy for handling overflow
+ */
+export type CacheStrategy = 'memory' | 'spill';
+
+/**
+ * Configuration for shared cache behavior
+ */
+export interface SharedCacheConfig {
+	/** Maximum rows before abandoning cache */
+	threshold: number;
+	/** Strategy when threshold exceeded */
+	strategy: CacheStrategy;
+	/** Optional identifier for logging */
+	name?: string;
+}
+
+/**
+ * Cache state for a shared cache instance
+ * Based on the proven closure pattern from the existing cache emitter
+ */
+export interface CacheState {
+	/** Cached result rows (undefined if not cached or abandoned) */
+	cachedResult?: Row[];
+	/** Whether caching was abandoned due to threshold */
+	cacheAbandoned: boolean;
+	/** Number of times cache has been consumed */
+	consumeCount: number;
+}
+
+/**
+ * Create a cache state object
+ */
+export function createCacheState(): CacheState {
+	return {
+		cachedResult: undefined,
+		cacheAbandoned: false,
+		consumeCount: 0
+	};
+}
+
+/**
+ * Shared cache implementation using the proven streaming-first pattern
+ * This is extracted from the existing working cache emitter
+ */
+export async function* streamWithCache(
+	sourceIterable: AsyncIterable<Row>,
+	config: SharedCacheConfig,
+	state: CacheState
+): AsyncIterable<Row> {
+	const { threshold, name = 'cache' } = config;
+
+	// If we already have cached data, return it
+	if (state.cachedResult) {
+		state.consumeCount++;
+		log('Serving %s from cache (access #%d, %d rows)',
+			name, state.consumeCount, state.cachedResult.length);
+		yield* state.cachedResult;
+		return;
+	}
+
+	// If we previously abandoned caching, just stream through
+	if (state.cacheAbandoned) {
+		log('%s cache abandoned due to previous threshold exceed, streaming directly', name);
+		yield* sourceIterable;
+		return;
+	}
+
+	// First time - pipeline results while building cache
+	log('Building %s cache with threshold %d while pipelining', name, threshold);
+	let cache: Row[] | undefined = [];
+
+	// Pipeline while caching (proven pattern from existing emitter)
+	for await (const row of sourceIterable) {
+		// Always yield immediately (streaming-first)
+		yield row;
+
+		// Try to cache if we haven't exceeded threshold
+		if (cache) {
+			if (cache.length < threshold) {
+				// Cache the row (deep copy to avoid reference issues)
+				cache.push([...row] as Row);
+			} else {
+				// Hit threshold - dump cache and abandon caching
+				log('%s cache threshold %d exceeded at row %d, dumping cache and continuing to pipeline',
+					name, threshold, cache.length);
+				cache = undefined;
+			}
+		}
+	}
+
+	// If we finished without exceeding threshold, cache is ready
+	if (cache) {
+		log('%s cache built successfully with %d rows', name, cache.length);
+		state.cachedResult = cache;
+	} else {
+		state.cacheAbandoned = true;
+	}
+}
+
+/**
+ * Factory function to create a reusable cache function
+ * Returns a function that can be called multiple times with different sources
+ */
+export function createCacheFunction(config: SharedCacheConfig) {
+	const state = createCacheState();
+
+	return async function* cachedIterable(source: AsyncIterable<Row>): AsyncIterable<Row> {
+		yield* streamWithCache(source, config, state);
+	};
+}
+
+/**
+ * Helper to wrap an async iterable with caching using the proven pattern
+ * This is the main utility that other components should use
+ */
+export function withSharedCache(
+	source: AsyncIterable<Row>,
+	config: SharedCacheConfig
+): {
+	iterable: AsyncIterable<Row>;
+	state: CacheState;
+} {
+	const state = createCacheState();
+
+	const iterable = {
+		async *[Symbol.asyncIterator](): AsyncIterator<Row> {
+			yield* streamWithCache(source, config, state);
+		}
+	};
+
+	return { iterable, state };
+}
+
+/**
+ * Get cache effectiveness metrics
+ */
+export function getCacheMetrics(state: CacheState): {
+	isCached: boolean;
+	isAbandoned: boolean;
+	consumeCount: number;
+	cachedRows?: number;
+} {
+	return {
+		isCached: !!state.cachedResult,
+		isAbandoned: state.cacheAbandoned,
+		consumeCount: state.consumeCount,
+		cachedRows: state.cachedResult?.length
+	};
+}
+
+/**
+ * Clear cache state (useful for testing or manual cache invalidation)
+ */
+export function clearCache(state: CacheState): void {
+	state.cachedResult = undefined;
+	state.cacheAbandoned = false;
+	state.consumeCount = 0;
+}

package/src/runtime/emission-context.ts

@@ -0,0 +1,310 @@
+import type { Database } from '../core/database.js';
+import type { SchemaManager } from '../schema/manager.js';
+import type { TableSchema } from '../schema/table.js';
+import type { FunctionSchema } from '../schema/function.js';
+import type { VirtualTableModule } from '../vtab/module.js';
+import { createLogger } from '../common/logger.js';
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+import type { CollationFunction } from '../util/comparison.js';
+
+const log = createLogger('runtime:emission-context');
+
+/**
+ * Represents a dependency on a schema object that was resolved during emission.
+ * Used for plan invalidation when schema changes.
+ */
+export interface SchemaDependency {
+	readonly type: 'table' | 'function' | 'vtab_module' | 'collation';
+	readonly schemaName?: string; // undefined for functions, collations, and vtab modules
+	readonly objectName: string;
+	readonly objectVersion?: number; // For future versioning support
+}
+
+/**
+ * Tracks schema dependencies and provides a unique identifier for a set of dependencies.
+ */
+export class DependencyTracker {
+	private dependencies = new Set<string>();
+	private _fingerprint: string | null = null;
+
+	/**
+	 * Records a dependency on a schema object.
+	 */
+	addDependency(dep: SchemaDependency): void {
+		const key = this.dependencyKey(dep);
+		this.dependencies.add(key);
+		this._fingerprint = null; // Invalidate cached fingerprint
+	}
+
+	/**
+	 * Gets all tracked dependencies.
+	 */
+	getDependencies(): SchemaDependency[] {
+		return Array.from(this.dependencies).map(key => this.parseDependencyKey(key));
+	}
+
+	/**
+	 * Gets a fingerprint representing the current set of dependencies.
+	 * This can be used to quickly check if dependencies have changed.
+	 */
+	getFingerprint(): string {
+		if (this._fingerprint === null) {
+			const sorted = Array.from(this.dependencies).sort();
+			this._fingerprint = sorted.join('|');
+		}
+		return this._fingerprint;
+	}
+
+	/**
+	 * Checks if this tracker has any dependencies that overlap with the given dependency.
+	 */
+	dependsOn(dep: SchemaDependency): boolean {
+		const key = this.dependencyKey(dep);
+		return this.dependencies.has(key);
+	}
+
+	/**
+	 * Clears all tracked dependencies.
+	 */
+	clear(): void {
+		this.dependencies.clear();
+		this._fingerprint = null;
+	}
+
+	private dependencyKey(dep: SchemaDependency): string {
+		const schema = dep.schemaName || '';
+		const version = dep.objectVersion || 0;
+		return `${dep.type}:${schema}:${dep.objectName}:${version}`;
+	}
+
+	private parseDependencyKey(key: string): SchemaDependency {
+		const [type, schemaName, objectName, versionStr] = key.split(':');
+		return {
+			type: type as SchemaDependency['type'],
+			schemaName: schemaName || undefined,
+			objectName,
+			objectVersion: parseInt(versionStr) || undefined
+		};
+	}
+}
+
+/**
+ * Context provided to emitters during plan emission.
+ * Allows schema lookups and tracks dependencies for plan invalidation.
+ * Also captures schema object references for runtime use.
+ */
+export class EmissionContext {
+	private readonly schemaManager: SchemaManager;
+	private readonly dependencyTracker = new DependencyTracker();
+	private readonly schemaSnapshot = new Map<string, any>();
+
+	constructor(public readonly db: Database) {
+		this.db = db;
+		this.schemaManager = db.schemaManager;
+	}
+
+	/**
+	 * Looks up a table schema and records the dependency.
+	 * Also captures the table reference for runtime use.
+	 */
+	findTable(tableName: string, schemaName?: string): TableSchema | undefined {
+		const table = this.schemaManager.findTable(tableName, schemaName);
+		if (table) {
+			const key = `table:${table.schemaName}:${table.name}`;
+			this.schemaSnapshot.set(key, table);
+			this.dependencyTracker.addDependency({
+				type: 'table',
+				schemaName: table.schemaName,
+				objectName: table.name
+			});
+			log('Recorded table dependency: %s.%s', table.schemaName, table.name);
+		}
+		return table;
+	}
+
+	/**
+	 * Looks up a function schema and records the dependency.
+	 * Also captures the function reference for runtime use.
+	 */
+	findFunction(funcName: string, numArgs: number): FunctionSchema | undefined {
+		const func = this.schemaManager.findFunction(funcName, numArgs);
+		if (func) {
+			const key = `function:${func.name}/${func.numArgs}`;
+			this.schemaSnapshot.set(key, func);
+			this.dependencyTracker.addDependency({
+				type: 'function',
+				objectName: `${func.name}/${func.numArgs}`
+			});
+			log('Recorded function dependency: %s/%d', func.name, func.numArgs);
+		}
+		return func;
+	}
+
+	/**
+	 * Looks up a virtual table module and records the dependency.
+	 * Also captures the module reference for runtime use.
+	 */
+	getVtabModule(moduleName: string): { module: VirtualTableModule<any, any>, auxData?: unknown } | undefined {
+		const moduleInfo = this.schemaManager.getModule(moduleName);
+		if (moduleInfo) {
+			const key = `vtab_module:${moduleName}`;
+			this.schemaSnapshot.set(key, moduleInfo);
+			this.dependencyTracker.addDependency({
+				type: 'vtab_module',
+				objectName: moduleName
+			});
+			log('Recorded vtab module dependency: %s', moduleName);
+		}
+		return moduleInfo;
+	}
+
+	/**
+	 * Looks up a collation and records the dependency.
+	 * Also captures the collation reference for runtime use.
+	 */
+	getCollation(collationName: string): CollationFunction | undefined {
+		const collation = this.db._getCollation(collationName);
+		if (collation) {
+			const key = `collation:${collationName}`;
+			this.schemaSnapshot.set(key, collation);
+			this.dependencyTracker.addDependency({
+				type: 'collation',
+				objectName: collationName
+			});
+			log('Recorded collation dependency: %s', collationName);
+		}
+		return collation;
+	}
+
+	/**
+	 * Gets the dependency tracker for this emission context.
+	 */
+	getDependencyTracker(): DependencyTracker {
+		return this.dependencyTracker;
+	}
+
+	/**
+	 * Gets a snapshot of all dependencies recorded during emission.
+	 */
+	getDependencies(): SchemaDependency[] {
+		return this.dependencyTracker.getDependencies();
+	}
+
+	/**
+	 * Gets a fingerprint representing all dependencies.
+	 */
+	getDependencyFingerprint(): string {
+		return this.dependencyTracker.getFingerprint();
+	}
+
+	/**
+	 * Provides access to the database instance for cases where direct access is needed.
+	 * Use sparingly - prefer the specific lookup methods above.
+	 */
+	getDatabase(): Database {
+		return this.db;
+	}
+
+	/**
+	 * Provides access to the schema manager for cases where direct access is needed.
+	 * Use sparingly - prefer the specific lookup methods above.
+	 */
+	getSchemaManager(): SchemaManager {
+		return this.schemaManager;
+	}
+
+	/**
+	 * Retrieves a captured schema object by its key.
+	 * This allows runtime instructions to use the schema objects that were
+	 * captured at emission time, providing consistency even if the schema changes.
+	 */
+	getCapturedSchemaObject<T = any>(key: string): T | undefined {
+		return this.schemaSnapshot.get(key) as T | undefined;
+	}
+
+	/**
+	 * Validates that all captured schema objects still exist in the current schema.
+	 * This can be called at the start of query execution to provide early error detection.
+	 * Only validates objects that were actually captured during emission.
+	 */
+	validateCapturedSchemaObjects(): void {
+		for (const [key, capturedObject] of this.schemaSnapshot.entries()) {
+			const [type, ...nameParts] = key.split(':');
+
+			switch (type) {
+				case 'table': {
+					const [schemaName, tableName] = nameParts;
+					const currentTable = this.schemaManager.findTable(tableName, schemaName);
+					if (!currentTable) {
+						throw new QuereusError(
+							`Table ${schemaName}.${tableName} was dropped after query was planned`,
+							StatusCode.ERROR
+						);
+					}
+					// Optionally check if it's the same object reference
+					if (currentTable !== capturedObject) {
+						log('Warning: Table %s.%s schema changed after query was planned', schemaName, tableName);
+					}
+					break;
+				}
+				case 'function': {
+					const funcKey = nameParts.join(':'); // Rejoin in case function name had colons
+					const [funcName, numArgsStr] = funcKey.split('/');
+					const numArgs = parseInt(numArgsStr);
+					const currentFunc = this.schemaManager.findFunction(funcName, numArgs);
+					if (!currentFunc) {
+						throw new QuereusError(
+							`Function ${funcName}/${numArgs} was removed after query was planned`,
+							StatusCode.ERROR
+						);
+					}
+					if (currentFunc !== capturedObject) {
+						log('Warning: Function %s/%d changed after query was planned', funcName, numArgs);
+					}
+					break;
+				}
+				case 'vtab_module': {
+					const moduleName = nameParts.join(':');
+					const currentModule = this.schemaManager.getModule(moduleName);
+					if (!currentModule) {
+						throw new QuereusError(
+							`Virtual table module ${moduleName} was unregistered after query was planned`,
+							StatusCode.ERROR
+						);
+					}
+					if (currentModule !== capturedObject) {
+						log('Warning: Virtual table module %s changed after query was planned', moduleName);
+					}
+					break;
+				}
+				case 'collation': {
+					const collationName = nameParts.join(':');
+					const currentCollation = this.db._getCollation(collationName);
+					if (!currentCollation) {
+						throw new QuereusError(
+							`Collation ${collationName} was removed after query was planned`,
+							StatusCode.ERROR
+						);
+					}
+					if (currentCollation !== capturedObject) {
+						log('Warning: Collation %s changed after query was planned', collationName);
+					}
+					break;
+				}
+				default:
+					log('Warning: Unknown schema object type in validation: %s', type);
+			}
+		}
+	}
+
+	/**
+	 * Gets the number of schema objects captured during emission.
+	 * Useful for debugging and testing.
+	 */
+	getCapturedObjectCount(): number {
+		return this.schemaSnapshot.size;
+	}
+}
+
+

package/src/runtime/emit/add-constraint.ts

@@ -0,0 +1,54 @@
+import type { AddConstraintNode } from '../../planner/nodes/add-constraint-node.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
+import type { EmissionContext } from '../emission-context.js';
+import { QuereusError } from '../../common/errors.js';
+import { SqlValue, StatusCode } from '../../common/types.js';
+import { createLogger } from '../../common/logger.js';
+import type { RowConstraintSchema } from '../../schema/table.js';
+import { opsToMask } from '../../schema/table.js';
+
+const log = createLogger('runtime:emit:add-constraint');
+
+export function emitAddConstraint(plan: AddConstraintNode, _ctx: EmissionContext): Instruction {
+	const tableSchema = plan.table.tableSchema;
+
+	async function run(_rctx: RuntimeContext): Promise<SqlValue> {
+		// Convert the AST constraint to a schema constraint object
+		const constraint = plan.constraint;
+
+		if (constraint.type !== 'check') {
+			throw new QuereusError(
+				`ADD CONSTRAINT ${constraint.type} is not yet implemented`,
+				StatusCode.UNSUPPORTED
+			);
+		}
+
+		if (!constraint.expr) {
+			throw new QuereusError(
+				'CHECK constraint requires an expression',
+				StatusCode.ERROR
+			);
+		}
+
+		// Create the constraint schema object
+		const constraintSchema: RowConstraintSchema = {
+			name: constraint.name || `check_${tableSchema.checkConstraints.length}`,
+			expr: constraint.expr,
+			operations: opsToMask(constraint.operations), // Convert operations array to bitmask
+		};
+
+		// Add the constraint to the table schema by creating a new frozen array
+		const updatedConstraints = [...tableSchema.checkConstraints, constraintSchema];
+		(tableSchema as any).checkConstraints = Object.freeze(updatedConstraints);
+
+		log('Added constraint %s to table %s', constraintSchema.name, tableSchema.name);
+
+		return null;
+	}
+
+	return {
+		params: [],
+		run: run as InstructionRun,
+		note: `addConstraint(${plan.table.tableSchema.name}, ${plan.constraint.name || 'unnamed'})`
+	};
+}