@quereus/quereus 0.2.0 → 0.4.0

package/src/runtime/emit/recursive-cte.ts

@@ -1,5 +1,5 @@
 import type { RecursiveCTENode } from '../../planner/nodes/recursive-cte-node.js';
-import type { Instruction, RuntimeContext } from '../types.js';
+import type { Instruction, InstructionRun, RuntimeContext } from '../types.js';
 import type { EmissionContext } from '../emission-context.js';
 import { emitCallFromPlan, emitPlanNode } from '../emitters.js';
 import type { Row } from '../../common/types.js';
@@ -102,7 +102,7 @@ export function emitRecursiveCTE(plan: RecursiveCTENode, ctx: EmissionContext):
 
 	return {
 		params: [baseCaseInstruction, recursiveCaseInstruction],
-		run,
+		run: run as InstructionRun,
 		note: `recursiveCTE(${plan.cteName})`
 	};
 }

package/src/runtime/emit/remote-query.ts

@@ -0,0 +1,47 @@
+import type { Instruction, RuntimeContext } from '../types.js';
+import type { EmissionContext } from '../emission-context.js';
+import type { Row } from '../../common/types.js';
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+import type { RemoteQueryNode } from '../../planner/nodes/remote-query-node.js';
+import type { AnyVirtualTableModule } from '../../vtab/module.js';
+
+/**
+ * Emitter for RemoteQueryNode.
+ * Calls the virtual table's xExecutePlan() method to execute the pushed-down pipeline.
+ */
+export function emitRemoteQuery(plan: RemoteQueryNode, _ctx: EmissionContext): Instruction {
+	async function* run(rctx: RuntimeContext): AsyncIterable<Row> {
+		// Retrieve virtual table connection via module context
+		const { tableRef, moduleCtx } = plan;
+		// Get the table instance - need to resolve this from the table reference
+		const tableSchema = tableRef.tableSchema;
+		const vtabModule = (moduleCtx as { vtabModule?: AnyVirtualTableModule } | undefined)?.vtabModule ?? tableRef.vtabModule;
+
+		// Connect to the table to get the instance
+		const table = vtabModule.xConnect(
+			rctx.db,
+			undefined, // pAux
+			tableSchema.vtabModuleName,
+			tableSchema.schemaName,
+			tableSchema.name,
+			{} // empty config for now
+		);
+
+		if (!table.xExecutePlan) {
+			throw new QuereusError(
+				`Virtual table module for '${tableSchema.name}' does not implement xExecutePlan() ` +
+				`despite indicating support via supports() method.`,
+				StatusCode.INTERNAL
+			);
+		}
+
+		yield* table.xExecutePlan(rctx.db, plan.source, plan.moduleCtx);
+	}
+
+	return {
+		params: [],
+		run,
+		note: `remoteQuery(${plan.tableRef.tableSchema.name})`
+	};
+}

package/src/runtime/emit/retrieve.ts

@@ -0,0 +1,15 @@
+import type { RetrieveNode } from '../../planner/nodes/retrieve-node.js';
+import type { Instruction } from '../types.js';
+import type { EmissionContext } from '../emission-context.js';
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+
+export function emitRetrieve(plan: RetrieveNode, _ctx: EmissionContext): Instruction {
+	// RetrieveNode should always be rewritten by the optimizer's access path selection rule
+	// If we reach this point, it means the optimizer failed to convert it to a physical node
+	throw new QuereusError(
+		`RetrieveNode for table '${plan.tableRef.tableSchema.name}' was not rewritten to a physical access node. ` +
+		`This indicates the virtual table module has no supported access method (neither supports() nor getBestAccessPlan()).`,
+		StatusCode.INTERNAL
+	);
+}

package/src/runtime/emit/returning.ts

@@ -1,6 +1,6 @@
 import type { ReturningNode } from '../../planner/nodes/returning-node.js';
-import type { Instruction, RuntimeContext } from '../types.js';
-import type { Row } from '../../common/types.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
+import type { Row, OutputValue } from '../../common/types.js';
 import type { EmissionContext } from '../emission-context.js';
 import { emitPlanNode, emitCallFromPlan } from '../emitters.js';
 import { buildRowDescriptor } from '../../util/row-descriptor.js';
@@ -19,7 +19,7 @@ export function emitReturning(plan: ReturningNode, ctx: EmissionContext): Instru
 	async function* run(
 		rctx: RuntimeContext,
 		executorRows: AsyncIterable<Row>,
-		...projectionCallbacks: Array<(ctx: RuntimeContext) => any>
+		...projectionCallbacks: Array<(ctx: RuntimeContext) => OutputValue>
 	): AsyncIterable<Row> {
 		// Project the results from the executor rows
 		yield* withRowContextGenerator(rctx, sourceRowDescriptor, executorRows, async function* (_sourceRow) {
@@ -35,7 +35,7 @@ export function emitReturning(plan: ReturningNode, ctx: EmissionContext): Instru
 
 	return {
 		params: [executorInstruction, ...projectionEvaluators],
-		run,
+		run: run as InstructionRun,
 		note: `returning(${plan.projections.length} cols)`
 	};
 }

package/src/runtime/emit/scalar-function.ts

@@ -1,5 +1,5 @@
 import type { ScalarFunctionCallNode } from '../../planner/nodes/function.js';
-import type { Instruction, RuntimeContext } from '../types.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
 import { emitPlanNode, createValidatedInstruction } from '../emitters.js';
 import { QuereusError } from '../../common/errors.js';
 import { StatusCode, type SqlValue, type OutputValue } from '../../common/types.js';
@@ -36,7 +36,7 @@ export function emitScalarFunctionCall(plan: ScalarFunctionCallNode, ctx: Emissi
 
 	return createValidatedInstruction(
 		[...operandExprs],
-		run as any,
+		run as InstructionRun,
 		ctx,
 		`${plan.expression.name}(${plan.operands.length})`
 	);

package/src/runtime/emit/scan.ts

@@ -2,10 +2,10 @@ import { StatusCode, type Row } from "../../common/types.js";
 import { SeqScanNode, IndexScanNode, IndexSeekNode } from "../../planner/nodes/table-access-nodes.js";
 import { QuereusError } from "../../common/errors.js";
 import type { VirtualTable } from "../../vtab/table.js";
-import type { BaseModuleConfig } from "../../vtab/module.js";
+import type { BaseModuleConfig, AnyVirtualTableModule } from "../../vtab/module.js";
 import type { Instruction, RuntimeContext } from "../types.js";
 import type { EmissionContext } from "../emission-context.js";
-import { createValidatedInstruction } from "../emitters.js";
+import { createValidatedInstruction, emitPlanNode } from "../emitters.js";
 import { disconnectVTable } from "../utils.js";
 import { buildRowDescriptor } from "../../util/row-descriptor.js";
 import { createRowSlot } from "../context-helpers.js";
@@ -30,9 +30,9 @@ export function emitSeqScan(plan: SeqScanNode | IndexScanNode | IndexSeekNode, c
 	// Capture the module info key for runtime retrieval
 	const moduleKey = `vtab_module:${schema.vtabModuleName}`;
 
-	async function* run(runtimeCtx: RuntimeContext): AsyncIterable<Row> {
+  async function* run(runtimeCtx: RuntimeContext, ...dynamicArgs: any[]): AsyncIterable<Row> {
 		// Use the captured module info instead of doing a fresh lookup
-		const capturedModuleInfo = ctx.getCapturedSchemaObject<{ module: any, auxData?: unknown }>(moduleKey);
+		const capturedModuleInfo = ctx.getCapturedSchemaObject<{ module: AnyVirtualTableModule, auxData?: unknown }>(moduleKey);
 		if (!capturedModuleInfo) {
 			throw new QuereusError(`Virtual table module '${schema.vtabModuleName}' was not captured during emission`, StatusCode.INTERNAL);
 		}
@@ -43,8 +43,8 @@ export function emitSeqScan(plan: SeqScanNode | IndexScanNode | IndexSeekNode, c
 		}
 
 		let vtabInstance: VirtualTable;
-		try {
-			const options: BaseModuleConfig = {}; // TODO: Populate options from plan.source.tableSchema.vtabArgs or similar if needed
+    try {
+      const options: BaseModuleConfig = (schema.vtabArgs ?? {}) as BaseModuleConfig;
 			vtabInstance = module.xConnect(
 				runtimeCtx.db,
 				capturedModuleInfo.auxData,
@@ -66,7 +66,15 @@ export function emitSeqScan(plan: SeqScanNode | IndexScanNode | IndexSeekNode, c
 
 		const rowSlot = createRowSlot(runtimeCtx, rowDescriptor);
 		try {
-			const asyncRowIterable = vtabInstance.xQuery(plan.filterInfo);
+      // If this is an IndexSeek with dynamic seek keys, populate args from params
+      const effectiveFilterInfo = (() => {
+        if (plan instanceof IndexSeekNode && dynamicArgs && dynamicArgs.length > 0) {
+          return { ...plan.filterInfo, args: dynamicArgs };
+        }
+        return plan.filterInfo;
+      })();
+
+      const asyncRowIterable = vtabInstance.xQuery(effectiveFilterInfo);
 			for await (const row of asyncRowIterable) {
 				rowSlot.set(row);
 				yield row;
@@ -81,10 +89,18 @@ export function emitSeqScan(plan: SeqScanNode | IndexScanNode | IndexSeekNode, c
 		}
 	}
 
-	return createValidatedInstruction(
-		[],
-		run,
-		ctx,
-		`${plan.nodeType}(${schema.name})`
-	);
+  // Emit parameter instructions for dynamic seek keys (IndexSeek only)
+  const params: Instruction[] = [];
+  if (plan instanceof IndexSeekNode) {
+    for (const key of plan.getSeekKeys()) {
+      params.push(emitPlanNode(key, ctx));
+    }
+  }
+
+  return createValidatedInstruction(
+    params,
+    run,
+    ctx,
+    `${plan.nodeType}(${schema.name})`
+  );
 }

package/src/runtime/emit/schema-declarative.ts

@@ -0,0 +1,205 @@
+import type { EmissionContext } from '../emission-context.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
+import { createLogger } from '../../common/logger.js';
+import { StatusCode, type Row, type SqlValue } from '../../common/types.js';
+import { QuereusError } from '../../common/errors.js';
+import { collectSchemaCatalog } from '../../schema/catalog.js';
+import { computeSchemaDiff, generateMigrationDDL } from '../../schema/schema-differ.js';
+import { computeShortSchemaHash } from '../../schema/schema-hasher.js';
+import type * as AST from '../../parser/ast.js';
+import type { PlanNode } from '../../planner/nodes/plan-node.js';
+
+const log = createLogger('runtime:emit:declare');
+
+export function emitDeclareSchema(plan: PlanNode, _ctx: EmissionContext): Instruction {
+	const declareStmt = (plan as unknown as { statementAst: AST.DeclareSchemaStmt }).statementAst;
+
+	const run = (rctx: RuntimeContext): Row => {
+		const schemaName = declareStmt.schemaName || 'main';
+		log('DECLARE SCHEMA %s', schemaName);
+
+		// Clear previous declaration and seed data for this schema
+		rctx.db.declaredSchemaManager.clearSeedData(schemaName);
+
+		// Store the declared schema
+		rctx.db.declaredSchemaManager.setDeclaredSchema(schemaName, declareStmt);
+
+		// Process seed data if present
+		for (const item of declareStmt.items) {
+			if (item.type === 'declaredSeed' && item.seedData) {
+				const tableName = item.tableName;
+				const rows = Array.from(item.seedData) as Array<SqlValue[]>;
+				rctx.db.declaredSchemaManager.setSeedData(schemaName, tableName, rows);
+				log('Stored seed data for %s.%s (%d rows)', schemaName, tableName, rows.length);
+			}
+		}
+
+		// Return empty row to satisfy type system (void result)
+		return [];
+	};
+
+	return {
+		params: [],
+		run: run as InstructionRun,
+		note: `declare schema ${declareStmt.schemaName || 'main'}`
+	};
+}
+
+export function emitDiffSchema(plan: PlanNode, _ctx: EmissionContext): Instruction {
+	const diffStmt = (plan as unknown as { statementAst: AST.DiffSchemaStmt }).statementAst;
+
+	const run = async function* (rctx: RuntimeContext): AsyncIterable<Row> {
+		const schemaName = diffStmt.schemaName || 'main';
+		log('DIFF SCHEMA %s', schemaName);
+
+		// Get declared schema
+		const declaredSchema = rctx.db.declaredSchemaManager.getDeclaredSchema(schemaName);
+		if (!declaredSchema) {
+			throw new QuereusError(`No declared schema found for '${schemaName}'`, StatusCode.ERROR);
+		}
+
+		// Collect actual catalog
+		const actualCatalog = collectSchemaCatalog(rctx.db, schemaName);
+
+		// Compute diff
+		const diff = computeSchemaDiff(declaredSchema, actualCatalog);
+
+		// Generate migration DDL statements
+		const migrationStatements = generateMigrationDDL(diff, schemaName);
+
+		// Return each DDL statement as a row
+		// This allows users to fetch the DDL and execute it themselves with custom logic
+		for (const ddl of migrationStatements) {
+			yield [ddl];
+		}
+	};
+
+	return {
+		params: [],
+		run: run as InstructionRun,
+		note: `diff schema ${diffStmt.schemaName || 'main'}`
+	};
+}
+
+export function emitApplySchema(plan: PlanNode, _ctx: EmissionContext): Instruction {
+	const applyStmt = (plan as unknown as { statementAst: AST.ApplySchemaStmt }).statementAst;
+
+	const run = async (rctx: RuntimeContext): Promise<Row> => {
+		const schemaName = applyStmt.schemaName || 'main';
+		log('APPLY SCHEMA %s', schemaName);
+
+		// Get declared schema
+		const declaredSchema = rctx.db.declaredSchemaManager.getDeclaredSchema(schemaName);
+		if (!declaredSchema) {
+			throw new QuereusError(`No declared schema found for '${schemaName}'`, StatusCode.ERROR);
+		}
+
+		// Ensure the target schema exists (create if it doesn't, except for main/temp)
+		const lowerSchemaName = schemaName.toLowerCase();
+		if (lowerSchemaName !== 'main' && lowerSchemaName !== 'temp') {
+			if (!rctx.db.schemaManager.getSchema(schemaName)) {
+				rctx.db.schemaManager.addSchema(schemaName);
+				log('Created schema: %s', schemaName);
+			}
+		}
+
+		// Collect actual catalog
+		const actualCatalog = collectSchemaCatalog(rctx.db, schemaName);
+
+		// Compute diff
+		const diff = computeSchemaDiff(declaredSchema, actualCatalog);
+
+		// Generate migration DDL
+		const migrationStatements = generateMigrationDDL(diff, schemaName);
+
+		// Execute each migration statement
+		for (const ddl of migrationStatements) {
+			log('Executing migration DDL: %s', ddl);
+			try {
+				await rctx.db.exec(ddl);
+			} catch (e) {
+				log('Migration failed for DDL: %s', ddl);
+				throw e;
+			}
+		}
+
+		// Apply seed data if requested
+		if (applyStmt.withSeed) {
+			const allSeedData = rctx.db.declaredSchemaManager.getAllSeedData(schemaName);
+			log('Seed data available for %d tables', allSeedData.size);
+			for (const [tableName, rows] of allSeedData) {
+				log('Applying seed data to %s.%s (%d rows)', schemaName, tableName, rows.length);
+
+				// Qualify table name with schema if not main
+				const qualifiedTableName = (schemaName && schemaName.toLowerCase() !== 'main')
+					? `${schemaName}.${tableName}`
+					: tableName;
+
+				// Delete existing rows, then insert seed rows in one batch
+				const deleteAndInsertSql = [
+					`DELETE FROM ${qualifiedTableName}`,
+					...rows.map(row => {
+						const values = row.map(v =>
+							v === null ? 'NULL' :
+							typeof v === 'string' ? `'${v.replace(/'/g, "''")}'` :
+							typeof v === 'number' || typeof v === 'bigint' ? String(v) :
+							'NULL'
+						).join(', ');
+						return `INSERT INTO ${qualifiedTableName} VALUES (${values})`;
+					})
+				].join('; ');
+
+				log('Executing seed SQL (length=%d): %s', deleteAndInsertSql.length, deleteAndInsertSql);
+				try {
+					await rctx.db.exec(deleteAndInsertSql);
+					log('Seed application succeeded for table %s', tableName);
+				} catch (e) {
+					log('Seed application failed for table %s: %O', tableName, e);
+					throw e;
+				}
+			}
+		}
+
+		// Return empty row to satisfy type system (void result)
+		return [];
+	};
+
+	return {
+		params: [],
+		run: run as InstructionRun,
+		note: `apply schema ${applyStmt.schemaName || 'main'}${applyStmt.withSeed ? ' with seed' : ''}`
+	};
+}
+
+export function emitExplainSchema(plan: PlanNode, _ctx: EmissionContext): Instruction {
+	const explainStmt = (plan as unknown as { statementAst: AST.ExplainSchemaStmt }).statementAst;
+
+	const run = async function* (rctx: RuntimeContext): AsyncIterable<Row> {
+		const schemaName = explainStmt.schemaName || 'main';
+		log('EXPLAIN SCHEMA %s', schemaName);
+
+		// Get declared schema
+		const declaredSchema = rctx.db.declaredSchemaManager.getDeclaredSchema(schemaName);
+		if (!declaredSchema) {
+			throw new QuereusError(`No declared schema found for '${schemaName}'`, StatusCode.ERROR);
+		}
+
+		// Compute hash
+		const hash = await computeShortSchemaHash(declaredSchema);
+
+		// Return hash with version if specified
+		const result = explainStmt.version
+			? `version:${explainStmt.version},hash:${hash}`
+			: `hash:${hash}`;
+
+		yield [result];
+	};
+
+	return {
+		params: [],
+		run: run as InstructionRun,
+		note: `explain schema ${explainStmt.schemaName || 'main'}`
+	};
+}
+
+

package/src/runtime/emit/sequencing.ts

@@ -1,7 +1,7 @@
 import type { SequencingNode } from '../../planner/nodes/sequencing-node.js';
-import type { Instruction, RuntimeContext } from '../types.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
 import { emitPlanNode } from '../emitters.js';
-import { type Row } from '../../common/types.js';
+import type { Row } from '../../common/types.js';
 import type { EmissionContext } from '../emission-context.js';
 
 export function emitSequencing(plan: SequencingNode, ctx: EmissionContext): Instruction {
@@ -18,7 +18,7 @@ export function emitSequencing(plan: SequencingNode, ctx: EmissionContext): Inst
 
 	return {
 		params: [sourceInstruction],
-		run: run as any,
+		run: run as InstructionRun,
 		note: `sequencing(${plan.sequenceColumnName})`
 	};
 }

package/src/runtime/emit/set-operation.ts

@@ -1,5 +1,5 @@
 import type { SetOperationNode } from '../../planner/nodes/set-operation-node.js';
-import type { Instruction, RuntimeContext } from '../types.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
 import type { EmissionContext } from '../emission-context.js';
 import { emitPlanNode } from '../emitters.js';
 import type { Row } from '../../common/types.js';
@@ -87,25 +87,25 @@ export function emitSetOperation(plan: SetOperationNode, ctx: EmissionContext):
     }
   }
 
-  let runFunc: any;
+  let run: InstructionRun;
   switch (plan.op) {
     case 'unionAll':
-      runFunc = runUnionAll;
+      run = runUnionAll as InstructionRun;
       break;
     case 'union':
-      runFunc = runUnionDistinct;
+      run = runUnionDistinct as InstructionRun;
       break;
     case 'intersect':
-      runFunc = runIntersect;
+      run = runIntersect as InstructionRun;
       break;
     case 'except':
-      runFunc = runExcept;
+      run = runExcept as InstructionRun;
       break;
   }
 
   return {
     params: [leftInst, rightInst],
-    run: runFunc as any,
+    run,
     note: plan.op
   };
 }

package/src/runtime/emit/sort.ts

@@ -1,5 +1,5 @@
 import type { SortNode } from '../../planner/nodes/sort.js';
-import type { Instruction, RuntimeContext } from '../types.js';
+import type { Instruction, RuntimeContext, InstructionRun } from '../types.js';
 import { emitPlanNode, emitCallFromPlan } from '../emitters.js';
 import { type SqlValue, type Row, type MaybePromise } from '../../common/types.js';
 import type { EmissionContext } from '../emission-context.js';
@@ -69,7 +69,7 @@ export function emitSort(plan: SortNode, ctx: EmissionContext): Instruction {
 
 	return {
 		params: [sourceInstruction, ...sortKeyInstructions],
-		run: run as any,
+		run: run as InstructionRun,
 		note: `sort(${plan.sortKeys.length} keys)`
 	};
 }

package/src/runtime/emit/subquery.ts

@@ -1,17 +1,17 @@
+import type { InNode, ExistsNode, ScalarSubqueryNode } from '../../planner/nodes/subquery.js';
 import type { Instruction, InstructionRun, RuntimeContext } from '../types.js';
-import type { InNode, ScalarSubqueryNode, ExistsNode } from '../../planner/nodes/subquery.js';
 import { emitPlanNode } from '../emitters.js';
 import type { SqlValue, Row } from '../../common/types.js';
-import { compareSqlValuesFast, resolveCollation } from '../../util/comparison.js';
 import type { EmissionContext } from '../emission-context.js';
 import { QuereusError } from '../../common/errors.js';
 import { StatusCode } from '../../common/types.js';
 import { BTree } from 'inheritree';
+import { compareSqlValuesFast, resolveCollation } from '../../util/comparison.js';
 import { ConstantNode } from '../../planner/nodes/plan-node.js';
 
 export function emitScalarSubquery(plan: ScalarSubqueryNode, ctx: EmissionContext): Instruction {
 
-	async function run(rctx: RuntimeContext, input: AsyncIterable<Row>): Promise<SqlValue> {
+	async function run(_rctx: RuntimeContext, input: AsyncIterable<Row>): Promise<SqlValue> {
 		let result: SqlValue = null;
 		let seen = false;
 
@@ -33,7 +33,7 @@ export function emitScalarSubquery(plan: ScalarSubqueryNode, ctx: EmissionContex
 
 	return {
 		params: [innerInstruction],
-		run,
+		run: run as InstructionRun,
 		note: 'SCALAR_SUBQUERY'
 	};
 }
@@ -77,7 +77,7 @@ export function emitIn(plan: InNode, ctx: EmissionContext): Instruction {
 
 		return {
 			params: [sourceInstruction, conditionExpr],
-			run: runSubqueryStreaming as any,
+			run: runSubqueryStreaming as InstructionRun,
 			note: `IN (subquery)`
 		};
 	} else if (plan.values) {
@@ -116,7 +116,7 @@ export function emitIn(plan: InNode, ctx: EmissionContext): Instruction {
 
 			if (values.some(val => val instanceof Promise)) {
 				// Must resolve promises at runtime
-				runFunc = async (rctx: RuntimeContext, condition: SqlValue): Promise<SqlValue> => {
+				runFunc = (async (rctx: RuntimeContext, condition: SqlValue): Promise<SqlValue> => {
 					const resolved = await Promise.all(values);
 
 					for (const value of resolved) {
@@ -128,7 +128,7 @@ export function emitIn(plan: InNode, ctx: EmissionContext): Instruction {
 					}
 
 					return innerConstantRun(rctx, condition);
-				}
+				}) as InstructionRun;
 			} else {
 				for (const value of values) {
 					if (value === null) {
@@ -137,7 +137,7 @@ export function emitIn(plan: InNode, ctx: EmissionContext): Instruction {
 					}
 					tree.insert(value as SqlValue);
 				}
-			runFunc = innerConstantRun;
+				runFunc = innerConstantRun as InstructionRun;
 			}
 
 			const conditionExpr = emitPlanNode(plan.condition, ctx);
@@ -176,7 +176,7 @@ export function emitIn(plan: InNode, ctx: EmissionContext): Instruction {
 
 			return {
 				params: [conditionExpr, ...valueExprs],
-				run: runDynamicValues as any,
+				run: runDynamicValues as InstructionRun,
 				note: `IN (${plan.values.length} dynamic values)`
 			};
 		}
@@ -197,7 +197,7 @@ export function emitExists(plan: ExistsNode, ctx: EmissionContext): Instruction
 
 	return {
 		params: [innerInstruction],
-		run,
+		run: run as InstructionRun,
 		note: 'EXISTS'
 	};
 }

package/src/runtime/emit/transaction.ts

@@ -39,6 +39,10 @@ export function emitTransaction(plan: TransactionNode, _ctx: EmissionContext): I
 						throw error;
 					}
 				}
+				// Reflect explicit transaction state in Database
+				rctx.db.markExplicitTransactionStart();
+				// Reset any prior change tracking at the start of an explicit transaction
+				rctx.db._clearChangeLog();
 				return null;
 			};
 			note = `BEGIN ${plan.mode || 'DEFERRED'}`;
@@ -46,17 +50,40 @@ export function emitTransaction(plan: TransactionNode, _ctx: EmissionContext): I
 		}
 		case 'commit': {
 			run = async (rctx: RuntimeContext) => {
-				const connections = rctx.db.getAllConnections();
-				log(`COMMIT: Found ${connections.length} active connections`);
+				// Snapshot connections before evaluating deferred constraints
+				// (constraint evaluation may open additional connections that shouldn't be committed)
+				const connectionsToCommit = rctx.db.getAllConnections();
+				log(`COMMIT: Found ${connectionsToCommit.length} active connections`);
 
-				for (const connection of connections) {
+				try {
+					// Evaluate global assertions and deferred row-level constraints BEFORE committing connections.
+					await rctx.db.runGlobalAssertions();
+					await rctx.db.runDeferredRowConstraints();
+
+					// Mark coordinated commit to relax layer validation for sibling layers
+					rctx.db._beginCoordinatedCommit();
 					try {
-						await connection.commit();
-						log(`COMMIT: Successfully called on connection ${connection.connectionId}`);
-					} catch (error) {
-						log(`COMMIT: Error on connection ${connection.connectionId}: %O`, error);
-						throw error;
+						// Commit sequentially to avoid race conditions with layer promotion
+						for (const connection of connectionsToCommit) {
+							try {
+								await connection.commit();
+								log(`COMMIT: Successfully called on connection ${connection.connectionId}`);
+							} catch (error) {
+								log(`COMMIT: Error on connection ${connection.connectionId}: %O`, error);
+								throw error;
+							}
+						}
+					} finally {
+						rctx.db._endCoordinatedCommit();
 					}
+				} catch (e) {
+					// If assertions fail (or a commit throws), rollback all connections
+					await Promise.allSettled(rctx.db.getAllConnections().map(c => c.rollback()));
+					throw e;
+				} finally {
+					// Always mark end of explicit transaction and clear change tracking
+					rctx.db.markExplicitTransactionEnd();
+					rctx.db._clearChangeLog();
 				}
 				return null;
 			};
@@ -80,6 +107,8 @@ export function emitTransaction(plan: TransactionNode, _ctx: EmissionContext): I
 							throw error;
 						}
 					}
+					// Discard top change layer
+					rctx.db._rollbackSavepointLayer();
 					return null;
 				};
 				note = `ROLLBACK TO SAVEPOINT ${plan.savepoint}`;
@@ -97,6 +126,9 @@ export function emitTransaction(plan: TransactionNode, _ctx: EmissionContext): I
 							throw error;
 						}
 					}
+					// Reflect explicit transaction end and clear change tracking
+					rctx.db.markExplicitTransactionEnd();
+					rctx.db._clearChangeLog();
 					return null;
 				};
 				note = 'ROLLBACK';
@@ -122,6 +154,10 @@ export function emitTransaction(plan: TransactionNode, _ctx: EmissionContext): I
 						throw error;
 					}
 				}
+				// Mark database as in explicit transaction (savepoints require explicit transaction context)
+				rctx.db.markExplicitTransactionStart();
+				// Track change layer
+				rctx.db._beginSavepointLayer();
 				return null;
 			};
 			note = `SAVEPOINT ${plan.savepoint}`;
@@ -146,6 +182,8 @@ export function emitTransaction(plan: TransactionNode, _ctx: EmissionContext): I
 						throw error;
 					}
 				}
+				// Merge top change layer into below
+				rctx.db._releaseSavepointLayer();
 				return null;
 			};
 			note = `RELEASE SAVEPOINT ${plan.savepoint}`;