@quereus/quereus 0.2.0 → 0.4.0

package/src/core/database.ts

@@ -1,7 +1,8 @@
 import { createLogger } from '../common/logger.js';
 import { MisuseError, quereusError, QuereusError } from '../common/errors.js';
-import { StatusCode, type SqlParameters, type SqlValue } from '../common/types.js';
-import type { VirtualTableModule } from '../vtab/module.js';
+import { StatusCode, type SqlParameters, type SqlValue, type Row, type OutputValue } from '../common/types.js';
+import type { ScalarType } from '../common/datatype.js';
+import type { AnyVirtualTableModule } from '../vtab/module.js';
 import { Statement } from './statement.js';
 import { SchemaManager } from '../schema/manager.js';
 import type { TableSchema } from '../schema/table.js';
@@ -11,7 +12,6 @@ import { createScalarFunction, createAggregateFunction } from '../func/registrat
 import { FunctionFlags } from '../common/constants.js';
 import { MemoryTableModule } from '../vtab/memory/module.js';
 import type { VirtualTableConnection } from '../vtab/connection.js';
-
 import { BINARY_COLLATION, getCollation, NOCASE_COLLATION, registerCollation, RTRIM_COLLATION, type CollationFunction } from '../util/comparison.js';
 import { Parser, ParseError } from '../parser/parser.js';
 import * as AST from '../parser/ast.js';
@@ -19,20 +19,29 @@ import { buildBlock } from '../planner/building/block.js';
 import { emitPlanNode } from '../runtime/emitters.js';
 import { Scheduler } from '../runtime/scheduler.js';
 import type { RuntimeContext } from '../runtime/types.js';
-import type { BlockNode } from '../planner/nodes/block.js';
+import type { RowDescriptor } from '../planner/nodes/plan-node.js';
+import { BlockNode } from '../planner/nodes/block.js';
 import type { PlanningContext } from '../planner/planning-context.js';
 import { BuildTimeDependencyTracker } from '../planner/planning-context.js';
 import { ParameterScope } from '../planner/scopes/param.js';
 import { GlobalScope } from '../planner/scopes/global.js';
-import type { PlanNode } from '../planner/nodes/plan-node.js';
+import { PlanNode, type RelationalPlanNode, type ScalarPlanNode } from '../planner/nodes/plan-node.js';
+import { FilterNode } from '../planner/nodes/filter.js';
+import { BinaryOpNode } from '../planner/nodes/scalar.js';
+import { ParameterReferenceNode, ColumnReferenceNode, TableReferenceNode } from '../planner/nodes/reference.js';
 import { registerEmitters } from '../runtime/register.js';
 import { serializePlanTree, formatPlanTree } from '../planner/debug.js';
 import type { DebugOptions } from '../planner/planning-context.js';
 import { EmissionContext } from '../runtime/emission-context.js';
 import { Optimizer, DEFAULT_TUNING } from '../planner/optimizer.js';
+import type { OptimizerTuning } from '../planner/optimizer-tuning.js';
 import { registerBuiltinWindowFunctions } from '../func/builtins/builtin-window-functions.js';
 import { DatabaseOptionsManager } from './database-options.js';
 import type { InstructionTracer } from '../runtime/types.js';
+import { isAsyncIterable } from '../runtime/utils.js';
+import { DeclaredSchemaManager } from '../schema/declared-schema-manager.js';
+import { analyzeRowSpecific } from '../planner/analysis/constraint-extractor.js';
+import { DeferredConstraintQueue } from '../runtime/deferred-constraint-queue.js';
 
 const log = createLogger('core:database');
 const warnLog = log.extend('warn');
@@ -45,6 +54,7 @@ const debugLog = log.extend('debug');
  */
 export class Database {
 	public readonly schemaManager: SchemaManager;
+	public readonly declaredSchemaManager: DeclaredSchemaManager;
 	private isOpen = true;
 	private statements = new Set<Statement>();
 	private isAutocommit = true; // Manages transaction state
@@ -54,9 +64,16 @@ export class Database {
 	public readonly optimizer: Optimizer;
 	public readonly options: DatabaseOptionsManager;
 	private instructionTracer: InstructionTracer | undefined;
+	/** Per-transaction change tracking: base table name → serialized PK tuples */
+	private changeLog: Map<string, Set<string>> = new Map();
+	/** Savepoint layers for change tracking */
+	private changeLogLayers: Array<Map<string, Set<string>>> = [];
+	/** Deferred constraint evaluation queue */
+	private readonly deferredConstraints = new DeferredConstraintQueue(this);
 
 	constructor() {
 		this.schemaManager = new SchemaManager(this);
+		this.declaredSchemaManager = new DeclaredSchemaManager();
 		this.options = new DatabaseOptionsManager();
 		log("Database instance created.");
 
@@ -110,9 +127,8 @@ export class Database {
 						validatePlan: event.newValue as boolean
 					}
 				};
-				// Recreate optimizer with new tuning
-				(this as any).optimizer = new Optimizer(newTuning);
-				log('Optimizer recreated with validate_plan = %s', event.newValue);
+				this.updateOptimizerTuning(newTuning as OptimizerTuning);
+				log('Optimizer tuning updated with validate_plan = %s', event.newValue);
 			}
 		});
 
@@ -130,7 +146,7 @@ export class Database {
 			defaultValue: {},
 			description: 'Default virtual table module arguments',
 			onChange: (event) => {
-				this.schemaManager.setDefaultVTabArgs(event.newValue as Record<string, any>);
+				this.schemaManager.setDefaultVTabArgs(event.newValue as Record<string, SqlValue>);
 			}
 		});
 
@@ -220,7 +236,7 @@ export class Database {
 
 		if (batch.length === 0) return;
 
-		const needsImplicitTransaction = batch.length > 1
+		const needsImplicitTransaction = batch.length >= 1
 			&& this.isAutocommit
 			// has explicit transaction
 			&& !batch.some(
@@ -251,7 +267,7 @@ export class Database {
 
 					const runtimeCtx: RuntimeContext = {
 						db: this,
-						stmt: null as any, // No persistent Statement object for transient exec statements
+						stmt: undefined,
 						params: params ?? {},
 						context: new Map(),
 						tableContexts: new Map(),
@@ -261,9 +277,9 @@ export class Database {
 
 					void await scheduler.run(runtimeCtx);
 					// Nothing to do with the result, this is executed for side effects only
-
-				} catch (err: any) {
-					executionError = err instanceof QuereusError ? err : new QuereusError(err.message, StatusCode.ERROR, err);
+				} catch (err) {
+					const error = err instanceof Error ? err : new Error(String(err));
+					executionError = error instanceof QuereusError ? error : new QuereusError(error.message, StatusCode.ERROR, error);
 					break; // Stop processing further statements on error
 				}
 				// No explicit finalize for transient plan/scheduler used in exec loop
@@ -271,14 +287,10 @@ export class Database {
 
 		} finally {
 			if (needsImplicitTransaction) {
-				try {
-					if (executionError) {
-						await this.rollbackImplicitTransaction();
-					} else {
-						await this.commitImplicitTransaction();
-					}
-				} catch (txError) {
-					errorLog(`Error during implicit transaction ${executionError ? 'rollback' : 'commit'}: %O`, txError);
+				if (executionError) {
+					await this.rollbackImplicitTransaction();
+				} else {
+					await this.commitImplicitTransaction();
 				}
 			}
 		}
@@ -294,7 +306,7 @@ export class Database {
 	 * @param module The module implementation.
 	 * @param auxData Optional client data passed to xCreate/xConnect.
 	 */
-	registerVtabModule(name: string, module: VirtualTableModule<any, any>, auxData?: unknown): void {
+	registerVtabModule(name: string, module: AnyVirtualTableModule, auxData?: unknown): void {
 		this.checkOpen();
 		this.schemaManager.registerModule(name, module, auxData);
 	}
@@ -414,7 +426,7 @@ export class Database {
 			deterministic?: boolean;
 			flags?: number;
 		},
-		func: (...args: any[]) => SqlValue
+		func: (...args: SqlValue[]) => SqlValue
 	): void {
 		this.checkOpen();
 
@@ -438,7 +450,7 @@ export class Database {
 	 * Registers a user-defined aggregate function.
 	 *
 	 * @param name The name of the SQL function.
-	 * @param options Configuration: { numArgs: number, flags?: number, initialState?: any }.
+	 * @param options Configuration: { numArgs: number, flags?: number, initialState?: unknown }.
 	 * @param stepFunc The function called for each row (accumulator, ...args) => newAccumulator.
 	 * @param finalFunc The function called at the end (accumulator) => finalResult.
 	 */
@@ -447,10 +459,10 @@ export class Database {
 		options: {
 			numArgs: number;
 			flags?: number;
-			initialState?: any;
+			initialState?: unknown;
 		},
-		stepFunc: (acc: any, ...args: any[]) => any,
-		finalFunc: (acc: any) => SqlValue
+		stepFunc: (acc: unknown, ...args: SqlValue[]) => unknown,
+		finalFunc: (acc: unknown) => SqlValue
 	): void {
 		this.checkOpen();
 
@@ -518,7 +530,7 @@ export class Database {
 	 * @param option The option name
 	 * @param value The option value
 	 */
-	setOption(option: string, value: any): void {
+	setOption(option: string, value: unknown): void {
 		this.checkOpen();
 		this.options.setOption(option, value);
 	}
@@ -528,11 +540,16 @@ export class Database {
 	 * @param option The option name
 	 * @returns The option value
 	 */
-	getOption(option: string): any {
+	getOption(option: string): unknown {
 		this.checkOpen();
 		return this.options.getOption(option);
 	}
 
+	/** Update optimizer tuning in place */
+	private updateOptimizerTuning(tuning: OptimizerTuning): void {
+		this.optimizer.updateTuning(tuning);
+	}
+
 	/**
 	 * Registers a user-defined collation sequence.
 	 * @param name The name of the collation sequence (case-insensitive).
@@ -579,6 +596,136 @@ export class Database {
 		return getCollation(name);
 	}
 
+	/** Serialize a composite primary key tuple for set storage */
+	private serializeKeyTuple(values: SqlValue[]): string {
+		// JSON serialization is sufficient because SqlValue is JSON-safe in this engine
+		return JSON.stringify(values);
+	}
+
+	/** Add a key tuple to the current change log for a base table */
+	private addChange(baseTable: string, keyTuple: SqlValue[]): void {
+		const target = this.changeLogLayers.length > 0
+			? this.changeLogLayers[this.changeLogLayers.length - 1]
+			: this.changeLog;
+		const key = baseTable.toLowerCase();
+		if (!target.has(key)) target.set(key, new Set());
+		target.get(key)!.add(this.serializeKeyTuple(keyTuple));
+	}
+
+	public _queueDeferredConstraintRow(baseTable: string, constraintName: string, row: Row, descriptor: RowDescriptor, evaluator: (ctx: RuntimeContext) => OutputValue, connectionId?: string, contextRow?: Row, contextDescriptor?: RowDescriptor): void {
+		this.deferredConstraints.enqueue(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor);
+	}
+
+
+	/** @internal Flag to prevent new connections from starting transactions during constraint evaluation */
+	private evaluatingDeferredConstraints = false;
+	/** @internal Flag indicating we're in a coordinated multi-connection commit */
+	private inCoordinatedCommit = false;
+
+	public async runDeferredRowConstraints(): Promise<void> {
+		this.evaluatingDeferredConstraints = true;
+		try {
+			await this.deferredConstraints.runDeferredRows();
+		} finally {
+			this.evaluatingDeferredConstraints = false;
+		}
+	}
+
+	/** @internal Check if we should skip auto-beginning transactions on newly registered connections */
+	public _isEvaluatingDeferredConstraints(): boolean {
+		return this.evaluatingDeferredConstraints;
+	}
+
+	/** @internal Mark start of coordinated multi-connection commit */
+	public _beginCoordinatedCommit(): void {
+		this.inCoordinatedCommit = true;
+	}
+
+	/** @internal Mark end of coordinated multi-connection commit */
+	public _endCoordinatedCommit(): void {
+		this.inCoordinatedCommit = false;
+	}
+
+	/** @internal Check if we're in a coordinated commit (allows sibling layer validation) */
+	public _inCoordinatedCommit(): boolean {
+		return this.inCoordinatedCommit;
+	}
+
+	/** Public API used by DML emitters to record changes */
+	public _recordInsert(baseTable: string, newKey: SqlValue[]): void {
+		this.addChange(baseTable, newKey);
+	}
+
+	public _recordDelete(baseTable: string, oldKey: SqlValue[]): void {
+		this.addChange(baseTable, oldKey);
+	}
+
+	public _recordUpdate(baseTable: string, oldKey: SqlValue[], newKey: SqlValue[]): void {
+		this.addChange(baseTable, oldKey);
+		// If the PK changed, also record the new key
+		if (this.serializeKeyTuple(oldKey) !== this.serializeKeyTuple(newKey)) {
+			this.addChange(baseTable, newKey);
+		}
+	}
+
+	/** Savepoint change tracking */
+	public _beginSavepointLayer(): void {
+		this.changeLogLayers.push(new Map());
+		this.deferredConstraints.beginLayer();
+	}
+
+	public _rollbackSavepointLayer(): void {
+		// Discard the top layer
+		this.changeLogLayers.pop();
+		this.deferredConstraints.rollbackLayer();
+	}
+
+	public _releaseSavepointLayer(): void {
+		// Merge the top layer into previous or main log
+		const top = this.changeLogLayers.pop();
+		if (!top) return;
+		const target = this.changeLogLayers.length > 0 ? this.changeLogLayers[this.changeLogLayers.length - 1] : this.changeLog;
+		for (const [table, set] of top) {
+			if (!target.has(table)) target.set(table, new Set());
+			const tgt = target.get(table)!;
+			for (const k of set) tgt.add(k);
+		}
+		this.deferredConstraints.releaseLayer();
+	}
+
+	private getChangedBaseTables(): Set<string> {
+		const result = new Set<string>();
+		const collect = (m: Map<string, Set<string>>) => {
+			for (const [t, s] of m) { if (s.size > 0) result.add(t); }
+		};
+		collect(this.changeLog);
+		for (const layer of this.changeLogLayers) collect(layer);
+		return result;
+	}
+
+	public _clearChangeLog(): void {
+		this.changeLog.clear();
+		this.changeLogLayers = [];
+		this.deferredConstraints.clear();
+	}
+
+	/**
+	 * Marks that an explicit SQL BEGIN has started a transaction.
+	 * Ensures subsequently registered connections also begin a transaction.
+	 */
+	public markExplicitTransactionStart(): void {
+		this.inTransaction = true;
+		this.isAutocommit = false;
+	}
+
+	/**
+	 * Marks that an explicit SQL COMMIT/ROLLBACK has ended the transaction.
+	 */
+	public markExplicitTransactionEnd(): void {
+		this.inTransaction = false;
+		this.isAutocommit = true;
+	}
+
 	/**
 	 * Prepares, binds parameters, executes, and yields result rows for a query.
 	 * This is a high-level convenience method for iterating over query results.
@@ -636,9 +783,10 @@ export class Database {
 			const parser = new Parser();
 			try {
 				ast = parser.parse(originalSqlString);
-			} catch (e: any) {
-				errorLog("Failed to parse SQL for query plan: %O", e);
-				throw new QuereusError(`Parse error: ${e.message}`, StatusCode.ERROR, e);
+			} catch (err) {
+				const error = err instanceof Error ? err : new Error(String(err));
+				errorLog("Failed to parse SQL for query plan: %O", error);
+				throw error;
 			}
 		} else {
 			ast = sqlOrAst;
@@ -660,7 +808,7 @@ export class Database {
 	getDebugPlan(sql: string, options?: { verbose?: boolean; expandNodes?: string[]; maxDepth?: number }): string {
 		this.checkOpen();
 		const plan = this.getPlan(sql);
-		
+
 		if (options?.verbose) {
 			// Use the original detailed JSON format
 			return serializePlanTree(plan);
@@ -687,14 +835,14 @@ export class Database {
 
 		const stmt = new Statement(this, sql);
 		// Set debug options on the statement
-		(stmt as any)._debugOptions = debug;
+		(stmt as Statement & { _debugOptions?: DebugOptions })._debugOptions = debug;
 
 		this.statements.add(stmt);
 		return stmt;
 	}
 
 	/** @internal */
-	_getVtabModule(name: string): { module: VirtualTableModule<any, any>, auxData?: unknown } | undefined {
+	_getVtabModule(name: string): { module: AnyVirtualTableModule, auxData?: unknown } | undefined {
 		// Delegate to SchemaManager
 		return this.schemaManager.getModule(name);
 		// return this.registeredVTabs.get(name.toLowerCase()); // Old implementation
@@ -726,7 +874,8 @@ export class Database {
 			cteNodes: new Map(),
 			schemaDependencies: new BuildTimeDependencyTracker(),
 			schemaCache: new Map(),
-			cteReferenceCache: new Map()
+			cteReferenceCache: new Map(),
+			outputScopes: new Map()
 		};
 
 		return buildBlock(ctx, statements);
@@ -741,8 +890,9 @@ export class Database {
 		debugLog(`Registered connection ${connection.connectionId} for table ${connection.tableName}`);
 
 		// If we're already in a transaction (implicit or explicit),
-		// start a transaction on this new connection
-		if (this.inTransaction) {
+		// start a transaction on this new connection UNLESS we're evaluating deferred constraints
+		// (during which subqueries should read committed state without creating new transaction layers)
+		if (this.inTransaction && !this.evaluatingDeferredConstraints) {
 			try {
 				await connection.begin();
 				debugLog(`Started transaction on newly registered connection ${connection.connectionId}`);
@@ -750,6 +900,8 @@ export class Database {
 				errorLog(`Error starting transaction on newly registered connection ${connection.connectionId}: %O`, error);
 				// Don't throw here - just log the error to avoid breaking connection registration
 			}
+		} else if (this.evaluatingDeferredConstraints) {
+			debugLog(`Skipped transaction begin on connection ${connection.connectionId} (evaluating deferred constraints)`);
 		}
 	}
 
@@ -786,8 +938,13 @@ export class Database {
 	 * @returns Array of connections for the table
 	 */
 	getConnectionsForTable(tableName: string): VirtualTableConnection[] {
+		const normalized = tableName.toLowerCase();
+		const simpleName = normalized.includes('.') ? normalized.substring(normalized.lastIndexOf('.') + 1) : normalized;
 		return Array.from(this.activeConnections.values())
-			.filter(conn => conn.tableName === tableName);
+			.filter(conn => {
+				const connName = conn.tableName.toLowerCase();
+				return connName === normalized || connName === simpleName;
+			});
 	}
 
 	/**
@@ -822,21 +979,6 @@ export class Database {
 		if (!this.isOpen) throw new MisuseError("Database is closed");
 	}
 
-	/** Helper to execute simple commands (BEGIN, COMMIT, ROLLBACK) internally
-	 * This method is for commands that don't produce rows and don't need complex parameter handling.
-	*/
-	private async execSimple(sqlCommand: string): Promise<void> {
-		let stmt: Statement | null = null;
-		try {
-			stmt = this.prepare(sqlCommand);
-			await stmt.run();
-		} finally {
-			if (stmt) {
-				await stmt.finalize();
-			}
-		}
-	}
-
 	/**
 	 * Begin an implicit transaction and coordinate with virtual table connections
 	 */
@@ -867,26 +1009,346 @@ export class Database {
 	private async commitImplicitTransaction(): Promise<void> {
 		debugLog("Database: Committing implicit transaction.");
 
-		// Commit all active connections first
-		const connections = this.getAllConnections();
-		const commitPromises = connections.map(async (connection) => {
+		try {
+			const connectionsToCommit = this.getAllConnections();
+
+			// Evaluate global assertions and deferred row constraints BEFORE committing connections. If violated, rollback and abort.
+			await this.runGlobalAssertions();
+			await this.runDeferredRowConstraints();
+
+			// Mark coordinated commit to relax layer validation for sibling layers
+			this._beginCoordinatedCommit();
 			try {
-				await connection.commit();
-			} catch (error) {
-				errorLog(`Error committing transaction on connection ${connection.connectionId}: %O`, error);
-				throw error;
+				// Commit only the original connections (not any opened during constraint evaluation)
+				// Commit sequentially to avoid race conditions with layer promotion
+				for (const connection of connectionsToCommit) {
+					try {
+						await connection.commit();
+					} catch (error) {
+						errorLog(`Error committing transaction on connection ${connection.connectionId}: %O`, error);
+						throw error;
+					}
+				}
+			} finally {
+				this._endCoordinatedCommit();
 			}
-		});
+		} catch (e) {
+			// On pre-commit assertion failure (or commit error), rollback all connections
+			const conns = this.getAllConnections();
+			await Promise.allSettled(conns.map(c => c.rollback()));
+			throw e;
+		} finally {
+			this.inTransaction = false;
+			this.isAutocommit = true;
+			this.inImplicitTransaction = false;
+			this._clearChangeLog();
+		}
+	}
 
-		await Promise.all(commitPromises);
+	public async runGlobalAssertions(): Promise<void> {
+		const assertions = this.schemaManager.getAllAssertions();
+		if (assertions.length === 0) return;
 
-		// Reset database state
-		this.inTransaction = false;
-		this.isAutocommit = true;
-		this.inImplicitTransaction = false;
+		// Only evaluate assertions impacted by changed base tables
+		const changedBases = this.getChangedBaseTables();
+		if (changedBases.size === 0) return;
+
+		for (const assertion of assertions) {
+			const planSql = assertion.violationSql;
+			const parser = new Parser();
+			let ast: AST.Statement;
+			try {
+				ast = parser.parse(planSql) as AST.Statement;
+			} catch (err) {
+				const error = err instanceof Error ? err : new Error(String(err));
+				throw new QuereusError(
+					`Failed to parse deferred assertion '${assertion.name}': ${error.message}`,
+					StatusCode.INTERNAL,
+					error
+				);
+			}
+			const plan = this._buildPlan([ast]) as BlockNode;
+			const analyzed = this.optimizer.optimizeForAnalysis(plan, this) as BlockNode;
+
+			// Collect base tables and relationKeys in this plan
+			const relationKeyToBase = new Map<string, string>();
+			const baseTablesInPlan = new Set<string>();
+			this.collectTables(analyzed, relationKeyToBase, baseTablesInPlan);
+
+			// Determine impact: if assertion has no dependencies, treat as global and always impacted.
+			const hasDeps = baseTablesInPlan.size > 0;
+			let impacted = !hasDeps;
+			if (hasDeps) {
+				for (const b of baseTablesInPlan) { if (changedBases.has(b)) { impacted = true; break; } }
+			}
+			if (!impacted) continue;
+
+			// Classify instances as row/global
+			const classifications: Map<string, 'row' | 'global'> = analyzeRowSpecific(analyzed as unknown as RelationalPlanNode);
+
+			// If any changed base appears as a global instance, run full violation query once
+			let requiresGlobal = false;
+			for (const [relKey, klass] of classifications) {
+				if (klass === 'global') {
+					const base = relationKeyToBase.get(relKey);
+					if (base && changedBases.has(base)) { requiresGlobal = true; break; }
+				}
+			}
+
+			if (requiresGlobal) {
+				await this.executeViolationOnce(assertion.name, assertion.violationSql);
+				continue;
+			}
+
+			// Collect row-specific references that correspond to changed bases
+			const rowSpecificChanged: Array<{ relKey: string; base: string }> = [];
+			for (const [relKey, klass] of classifications) {
+				if (klass !== 'row') continue;
+				const base = relationKeyToBase.get(relKey);
+				if (base && changedBases.has(base)) rowSpecificChanged.push({ relKey, base });
+			}
+
+			if (rowSpecificChanged.length === 0) {
+				// No row-specific changed refs (or no refs at all) → run once globally.
+				await this.executeViolationOnce(assertion.name, assertion.violationSql);
+				continue;
+			}
+
+			// Execute parameterized variants per changed key for each row-specific reference; early-exit on violation
+			for (const { relKey, base } of rowSpecificChanged) {
+				await this.executeViolationPerChangedKeys(assertion.name, assertion.violationSql, analyzed, relKey, base);
+			}
+		}
+	}
+
+	private async executeViolationOnce(assertionName: string, sql: string): Promise<void> {
+		const stmt = await this.prepare(sql);
+		try {
+			for await (const _ of stmt.all()) {
+				throw new QuereusError(`Integrity assertion failed: ${assertionName}`, StatusCode.CONSTRAINT);
+			}
+		} finally {
+			await stmt.finalize();
+		}
+	}
+
+	private async executeViolationOnceFromPlan(assertionName: string, plan: BlockNode): Promise<void> {
+		const optimizedPlan = this.optimizer.optimize(plan, this) as BlockNode;
+		const emissionContext = new EmissionContext(this);
+		const rootInstruction = emitPlanNode(optimizedPlan, emissionContext);
+		const scheduler = new Scheduler(rootInstruction);
+
+		const runtimeCtx: RuntimeContext = {
+			db: this,
+			stmt: undefined,
+			params: {},
+			context: new Map(),
+			tableContexts: new Map(),
+			tracer: this.instructionTracer,
+			enableMetrics: this.options.getBooleanOption('runtime_stats'),
+		};
+
+		const result = await scheduler.run(runtimeCtx);
+		if (isAsyncIterable(result)) {
+			for await (const _ of result as AsyncIterable<unknown>) {
+				throw new QuereusError(`CHECK constraint failed: ${assertionName}`, StatusCode.CONSTRAINT);
+			}
+		}
+	}
+
+	private async executeViolationPerChangedKeysFromPlan(
+		assertionName: string,
+		analyzed: BlockNode,
+		targetRelationKey: string,
+		base: string
+	): Promise<void> {
+		const changedKeyTuples = this.getChangedKeyTuples(base);
+		if (changedKeyTuples.length === 0) return;
+
+		// Find PK indices for the base table
+		const [schemaName, tableName] = base.split('.');
+		const table = this._findTable(tableName, schemaName);
+		if (!table) {
+			throw new QuereusError(`Constraint references unknown table ${base}`, StatusCode.INTERNAL);
+		}
+		const pkIndices = table.primaryKeyDefinition.map(def => def.index);
+
+		// Prepare a rewritten plan with an injected Filter on the target relationKey
+		const rewritten = this.injectPkFilter(analyzed, targetRelationKey, base, pkIndices);
+		const optimizedPlan = this.optimizer.optimize(rewritten, this) as BlockNode;
 
-		// DON'T disconnect connections after successful commit - leave them for subsequent queries
-		// The data in committed connections should be visible to future operations
+		// Emit and execute for each changed PK tuple; stop on first violation row.
+		const emissionContext = new EmissionContext(this);
+		const rootInstruction = emitPlanNode(optimizedPlan, emissionContext);
+		const scheduler = new Scheduler(rootInstruction);
+
+		for (const tuple of changedKeyTuples) {
+			const params: Record<string, SqlValue> = {};
+			for (let i = 0; i < pkIndices.length; i++) {
+				params[`pk${i}`] = tuple[i];
+			}
+
+			const runtimeCtx: RuntimeContext = {
+				db: this,
+				stmt: undefined,
+				params,
+				context: new Map(),
+				tableContexts: new Map(),
+				tracer: this.instructionTracer,
+				enableMetrics: this.options.getBooleanOption('runtime_stats'),
+			};
+
+			// Run and detect first output row (violation)
+			const result = await scheduler.run(runtimeCtx);
+			if (isAsyncIterable(result)) {
+				for await (const _ of result as AsyncIterable<unknown>) {
+					throw new QuereusError(`CHECK constraint failed: ${assertionName}`, StatusCode.CONSTRAINT);
+				}
+			}
+		}
+	}
+
+	/** Execute a parameterized variant of the assertion once per changed key for a specific row-specific relationKey. */
+	private async executeViolationPerChangedKeys(
+		assertionName: string,
+		violationSql: string,
+		analyzed: BlockNode,
+		targetRelationKey: string,
+		base: string
+	): Promise<void> {
+		const changedKeyTuples = this.getChangedKeyTuples(base);
+		if (changedKeyTuples.length === 0) return;
+
+		// Find PK indices for the base table
+		const [schemaName, tableName] = base.split('.');
+		const table = this._findTable(tableName, schemaName);
+		if (!table) {
+			throw new QuereusError(`Assertion references unknown table ${base}`, StatusCode.INTERNAL);
+		}
+		const pkIndices = table.primaryKeyDefinition.map(def => def.index);
+
+		// Prepare a rewritten plan with an injected Filter on the target relationKey
+		const rewritten = this.injectPkFilter(analyzed, targetRelationKey, base, pkIndices);
+		const optimizedPlan = this.optimizer.optimize(rewritten, this) as BlockNode;
+
+		// Emit and execute for each changed PK tuple; stop on first violation row.
+		const emissionContext = new EmissionContext(this);
+		const rootInstruction = emitPlanNode(optimizedPlan, emissionContext);
+		const scheduler = new Scheduler(rootInstruction);
+
+		for (const tuple of changedKeyTuples) {
+			const params: Record<string, SqlValue> = {};
+			for (let i = 0; i < pkIndices.length; i++) {
+				params[`pk${i}`] = tuple[i];
+			}
+
+			const runtimeCtx: RuntimeContext = {
+				db: this,
+				stmt: undefined,
+				params,
+				context: new Map(),
+				tableContexts: new Map(),
+				tracer: this.instructionTracer,
+				enableMetrics: this.options.getBooleanOption('runtime_stats'),
+			};
+
+			// Run and detect first output row (violation)
+			const result = await scheduler.run(runtimeCtx);
+			if (isAsyncIterable(result)) {
+				for await (const _ of result as AsyncIterable<unknown>) {
+					throw new QuereusError(`Integrity assertion failed: ${assertionName}`, StatusCode.CONSTRAINT);
+				}
+			}
+		}
+	}
+
+	/** Gather all changed PK tuples for a base table across layers */
+	private getChangedKeyTuples(base: string): SqlValue[][] {
+		const lower = base.toLowerCase();
+		const tuples: SqlValue[][] = [];
+		const collect = (m: Map<string, Set<string>>): void => {
+			const set = m.get(lower);
+			if (!set) return;
+			for (const s of set) tuples.push(JSON.parse(s) as SqlValue[]);
+		};
+		collect(this.changeLog);
+		for (const layer of this.changeLogLayers) collect(layer);
+		return tuples;
+	}
+
+	/** Inject an equality Filter with named parameters :pk0, :pk1, ... at the earliest reference of targetRelationKey. */
+	private injectPkFilter(block: BlockNode, targetRelationKey: string, base: string, pkIndices: number[]): BlockNode {
+		const newStatements = block.getChildren().map(stmt => this.rewriteForPkFilter(stmt, targetRelationKey, base, pkIndices));
+		if (newStatements.every((s, i) => s === block.getChildren()[i])) return block;
+		return this.createBlockWithNewStatements(block, newStatements);
+	}
+
+	private rewriteForPkFilter(node: PlanNode, targetRelationKey: string, base: string, pkIndices: number[]): PlanNode {
+		// If this node is the target TableReference instance, wrap with a Filter
+		const maybe = this.tryWrapTableReference(node, targetRelationKey, base, pkIndices);
+		if (maybe) return maybe;
+
+		const originalChildren = node.getChildren();
+		if (!originalChildren || originalChildren.length === 0) return node;
+		const rewrittenChildren = originalChildren.map(child => this.rewriteForPkFilter(child, targetRelationKey, base, pkIndices));
+		const changed = rewrittenChildren.some((c, i) => c !== originalChildren[i]);
+		return changed ? node.withChildren(rewrittenChildren) : node;
+	}
+
+	private tryWrapTableReference(node: PlanNode, targetRelationKey: string, base: string, pkIndices: number[]): PlanNode | null {
+		if (!(node instanceof TableReferenceNode)) return null;
+		const tableSchema = node.tableSchema;
+		const schemaName = tableSchema.schemaName;
+		const tableName = tableSchema.name;
+		const relName = `${schemaName}.${tableName}`.toLowerCase();
+		const relKey = `${relName}#${node.id ?? 'unknown'}`;
+		if (relKey !== targetRelationKey) return null;
+
+		// Build predicate: AND(col_pk_i = :pk{i}) for all PK columns
+		const relational = node as RelationalPlanNode;
+		const scope = relational.scope;
+		const attributes = relational.getAttributes();
+
+		const makeColumnRef = (colIndex: number): ScalarPlanNode => {
+			const attr = attributes[colIndex];
+			const expr: AST.ColumnExpr = { type: 'column', name: attr.name, table: tableName, schema: schemaName };
+			return new ColumnReferenceNode(scope, expr, attr.type, attr.id, colIndex);
+		};
+
+		const makeParamRef = (i: number, type: ScalarType): ScalarPlanNode => {
+			const pexpr: AST.ParameterExpr = { type: 'parameter', name: `pk${i}` };
+			return new ParameterReferenceNode(scope, pexpr, `pk${i}`, type);
+		};
+
+		let predicate: ScalarPlanNode | null = null;
+		for (let i = 0; i < pkIndices.length; i++) {
+			const colIdx = pkIndices[i];
+			const left = makeColumnRef(colIdx);
+			const right = makeParamRef(i, attributes[colIdx].type);
+			const bexpr: AST.BinaryExpr = { type: 'binary', operator: '=', left: left.expression, right: right.expression };
+			const eqNode = new BinaryOpNode(scope, bexpr, left, right);
+			predicate = predicate
+				? new BinaryOpNode(scope, { type: 'binary', operator: 'AND', left: predicate.expression, right: eqNode.expression }, predicate, eqNode)
+				: eqNode;
+		}
+
+		if (!predicate) return null;
+
+		// Wrap the table reference with a FilterNode
+		return new FilterNode(scope, relational, predicate);
+	}
+
+	private collectTables(node: PlanNode, relToBase: Map<string, string>, bases: Set<string>): void {
+		for (const child of node.getChildren()) {
+			this.collectTables(child, relToBase, bases);
+		}
+		if (node instanceof TableReferenceNode) {
+			const schema = node.tableSchema;
+			const baseName = `${schema.schemaName}.${schema.name}`.toLowerCase();
+			bases.add(baseName);
+			const relKey = `${baseName}#${node.id ?? 'unknown'}`;
+			relToBase.set(relKey, baseName);
+		}
 	}
 
 	/**
@@ -902,7 +1364,7 @@ export class Database {
 				await connection.rollback();
 			} catch (error) {
 				errorLog(`Error rolling back transaction on connection ${connection.connectionId}: %O`, error);
-				// Don't throw here - we want to rollback as many as possible
+				// Continue attempting rollback for other connections.
 			}
 		});
 
@@ -913,5 +1375,9 @@ export class Database {
 		this.isAutocommit = true;
 		this.inImplicitTransaction = false;
 	}
+
+	private createBlockWithNewStatements(block: BlockNode, statements: PlanNode[]): BlockNode {
+		return new BlockNode(block.scope, statements, block.parameters);
+	}
 }