@prisma-next/sql-runtime 0.5.0-dev.1 → 0.5.0-dev.11

package/dist/{exports-TJ70Qw3r.mjs → exports-BOHa3Emo.mjs}

@@ -1,11 +1,11 @@
-import { checkMiddlewareCompatibility, runtimeError } from "@prisma-next/framework-components/runtime";
+import { AsyncIterableResult, RuntimeCore, checkMiddlewareCompatibility, isRuntimeError, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
 import { createCodecRegistry, isQueryAst } from "@prisma-next/sql-relational-core/ast";
-import { AsyncIterableResult, createRuntimeCore, evaluateRawGuardrails, runtimeError as runtimeError$1 } from "@prisma-next/runtime-executor";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { checkContractComponentRequirements } from "@prisma-next/framework-components/components";
 import { createExecutionStack } from "@prisma-next/framework-components/execution";
 import { createSqlOperationRegistry } from "@prisma-next/sql-operations";
 import { type } from "arktype";
+import { createHash } from "node:crypto";
 
 //#region src/codecs/validation.ts
 function extractCodecIds(contract) {
@@ -202,6 +202,95 @@ function budgets(options) {
 	}
 }
 
+//#endregion
+//#region src/guardrails/raw.ts
+const SELECT_STAR_REGEX = /select\s+\*/i;
+const LIMIT_REGEX = /\blimit\b/i;
+const MUTATION_PREFIX_REGEX = /^(insert|update|delete|create|alter|drop|truncate)\b/i;
+const READ_ONLY_INTENTS = new Set([
+	"read",
+	"report",
+	"readonly"
+]);
+function evaluateRawGuardrails(plan, config) {
+	const lints$1 = [];
+	const budgets$1 = [];
+	const normalized = normalizeWhitespace(plan.sql);
+	const statementType = classifyStatement(normalized);
+	if (statementType === "select") {
+		if (SELECT_STAR_REGEX.test(normalized)) lints$1.push(createLint("LINT.SELECT_STAR", "error", "Raw SQL plan selects all columns via *", { sql: snippet(plan.sql) }));
+		if (!LIMIT_REGEX.test(normalized)) {
+			const severity = config?.budgets?.unboundedSelectSeverity ?? "error";
+			lints$1.push(createLint("LINT.NO_LIMIT", "warn", "Raw SQL plan omits LIMIT clause", { sql: snippet(plan.sql) }));
+			budgets$1.push(createBudget("BUDGET.ROWS_EXCEEDED", severity, "Raw SQL plan is unbounded and may exceed row budget", {
+				sql: snippet(plan.sql),
+				...config?.budgets?.estimatedRows !== void 0 ? { estimatedRows: config.budgets.estimatedRows } : {}
+			}));
+		}
+	}
+	if (isMutationStatement(statementType) && isReadOnlyIntent(plan.meta)) lints$1.push(createLint("LINT.READ_ONLY_MUTATION", "error", "Raw SQL plan mutates data despite read-only intent", {
+		sql: snippet(plan.sql),
+		intent: plan.meta.annotations?.["intent"]
+	}));
+	const refs = plan.meta.refs;
+	if (refs) evaluateIndexCoverage(refs, lints$1);
+	return {
+		lints: lints$1,
+		budgets: budgets$1,
+		statement: statementType
+	};
+}
+function evaluateIndexCoverage(refs, lints$1) {
+	const predicateColumns = refs.columns ?? [];
+	if (predicateColumns.length === 0) return;
+	const indexes = refs.indexes ?? [];
+	if (indexes.length === 0) {
+		lints$1.push(createLint("LINT.UNINDEXED_PREDICATE", "warn", "Raw SQL plan predicates lack supporting indexes", { predicates: predicateColumns }));
+		return;
+	}
+	if (!predicateColumns.every((column) => indexes.some((index) => index.table === column.table && index.columns.some((col) => col.toLowerCase() === column.column.toLowerCase())))) lints$1.push(createLint("LINT.UNINDEXED_PREDICATE", "warn", "Raw SQL plan predicates lack supporting indexes", { predicates: predicateColumns }));
+}
+function classifyStatement(sql) {
+	const trimmed = sql.trim();
+	const lower = trimmed.toLowerCase();
+	if (lower.startsWith("with")) {
+		if (lower.includes("select")) return "select";
+	}
+	if (lower.startsWith("select")) return "select";
+	if (MUTATION_PREFIX_REGEX.test(trimmed)) return "mutation";
+	return "other";
+}
+function isMutationStatement(statement) {
+	return statement === "mutation";
+}
+function isReadOnlyIntent(meta) {
+	const annotations = meta.annotations;
+	const intent = typeof annotations?.intent === "string" ? annotations.intent.toLowerCase() : void 0;
+	return intent !== void 0 && READ_ONLY_INTENTS.has(intent);
+}
+function normalizeWhitespace(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function snippet(sql) {
+	return normalizeWhitespace(sql).slice(0, 200);
+}
+function createLint(code, severity, message, details) {
+	return {
+		code,
+		severity,
+		message,
+		...details ? { details } : {}
+	};
+}
+function createBudget(code, severity, message, details) {
+	return {
+		code,
+		severity,
+		message,
+		...details ? { details } : {}
+	};
+}
+
 //#endregion
 //#region src/middleware/lints.ts
 function getFromSourceTableDetail(source) {
@@ -619,6 +708,7 @@ function formatErrorSummary(errors) {
 
 //#endregion
 //#region src/codecs/decoding.ts
+const WIRE_PREVIEW_LIMIT = 100;
 function resolveRowCodec(alias, plan, registry) {
 	const planCodecId = plan.meta.annotations?.codecs?.[alias];
 	if (planCodecId) {
@@ -662,72 +752,106 @@ function resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex) {
 	}
 	return fallbackColumnRefIndex?.get(alias);
 }
-function decodeRow(row, plan, registry, jsonValidators) {
-	const decoded = {};
+function previewWireValue(wireValue) {
+	if (typeof wireValue === "string") return wireValue.length > WIRE_PREVIEW_LIMIT ? `${wireValue.substring(0, WIRE_PREVIEW_LIMIT)}...` : wireValue;
+	return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);
+}
+function isJsonSchemaValidationError(error) {
+	return isRuntimeError(error) && error.code === "RUNTIME.JSON_SCHEMA_VALIDATION_FAILED";
+}
+function wrapDecodeFailure(error, alias, ref, codec$1, wireValue) {
+	const message = error instanceof Error ? error.message : String(error);
+	const wrapped = runtimeError("RUNTIME.DECODE_FAILED", `Failed to decode column ${ref ? `${ref.table}.${ref.column}` : alias} with codec '${codec$1.id}': ${message}`, {
+		...ref ? {
+			table: ref.table,
+			column: ref.column
+		} : { alias },
+		codec: codec$1.id,
+		wirePreview: previewWireValue(wireValue)
+	});
+	wrapped.cause = error;
+	throw wrapped;
+}
+function wrapIncludeAggregateFailure(error, alias, wireValue) {
+	const wrapped = runtimeError("RUNTIME.DECODE_FAILED", `Failed to parse JSON array for include alias '${alias}': ${error instanceof Error ? error.message : String(error)}`, {
+		alias,
+		wirePreview: previewWireValue(wireValue)
+	});
+	wrapped.cause = error;
+	throw wrapped;
+}
+function decodeIncludeAggregate(alias, wireValue) {
+	if (wireValue === null || wireValue === void 0) return [];
+	try {
+		let parsed;
+		if (typeof wireValue === "string") parsed = JSON.parse(wireValue);
+		else if (Array.isArray(wireValue)) parsed = wireValue;
+		else parsed = JSON.parse(String(wireValue));
+		if (!Array.isArray(parsed)) throw new Error(`Expected array for include alias '${alias}', got ${typeof parsed}`);
+		return parsed;
+	} catch (error) {
+		wrapIncludeAggregateFailure(error, alias, wireValue);
+	}
+}
+/**
+* Decodes a single field. Single-armed: every cell takes the same path —
+* `codec.decode → await → JSON-Schema validate → return plain value` — so
+* sync- and async-authored codecs are indistinguishable to callers.
+*/
+async function decodeField(alias, wireValue, plan, registry, jsonValidators, projection, fallbackColumnRefIndex) {
+	if (wireValue === null || wireValue === void 0) return wireValue;
+	const codec$1 = resolveRowCodec(alias, plan, registry);
+	if (!codec$1) return wireValue;
+	const ref = resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex);
+	let decoded;
+	try {
+		decoded = await codec$1.decode(wireValue);
+	} catch (error) {
+		wrapDecodeFailure(error, alias, ref, codec$1, wireValue);
+	}
+	if (jsonValidators && ref) try {
+		validateJsonValue(jsonValidators, ref.table, ref.column, decoded, "decode", codec$1.id);
+	} catch (error) {
+		if (isJsonSchemaValidationError(error)) throw error;
+		wrapDecodeFailure(error, alias, ref, codec$1, wireValue);
+	}
+	return decoded;
+}
+/**
+* Decodes a row by dispatching all per-cell codec calls concurrently via
+* `Promise.all`. Each cell follows the single-armed `decodeField` path.
+* Failures are wrapped in `RUNTIME.DECODE_FAILED` with `{ table, column,
+* codec }` (or `{ alias, codec }` when no column ref is resolvable) and the
+* original error attached on `cause`.
+*/
+async function decodeRow(row, plan, registry, jsonValidators) {
 	const projection = plan.meta.projection;
-	const fallbackColumnRefIndex = jsonValidators && (!projection || Array.isArray(projection)) ? buildColumnRefIndex(plan) : null;
+	const fallbackColumnRefIndex = !projection || Array.isArray(projection) ? buildColumnRefIndex(plan) : null;
 	let aliases;
 	if (projection && !Array.isArray(projection)) aliases = Object.keys(projection);
 	else if (projection && Array.isArray(projection)) aliases = projection;
 	else aliases = Object.keys(row);
-	for (const alias of aliases) {
+	const tasks = [];
+	const includeIndices = [];
+	for (let i = 0; i < aliases.length; i++) {
+		const alias = aliases[i];
 		const wireValue = row[alias];
 		const projectionValue = projection && typeof projection === "object" && !Array.isArray(projection) ? projection[alias] : void 0;
 		if (typeof projectionValue === "string" && projectionValue.startsWith("include:")) {
-			if (wireValue === null || wireValue === void 0) {
-				decoded[alias] = [];
-				continue;
-			}
-			try {
-				let parsed;
-				if (typeof wireValue === "string") parsed = JSON.parse(wireValue);
-				else if (Array.isArray(wireValue)) parsed = wireValue;
-				else parsed = JSON.parse(String(wireValue));
-				if (!Array.isArray(parsed)) throw new Error(`Expected array for include alias '${alias}', got ${typeof parsed}`);
-				decoded[alias] = parsed;
-			} catch (error) {
-				const decodeError = /* @__PURE__ */ new Error(`Failed to parse JSON array for include alias '${alias}': ${error instanceof Error ? error.message : String(error)}`);
-				decodeError.code = "RUNTIME.DECODE_FAILED";
-				decodeError.category = "RUNTIME";
-				decodeError.severity = "error";
-				decodeError.details = {
-					alias,
-					wirePreview: typeof wireValue === "string" && wireValue.length > 100 ? `${wireValue.substring(0, 100)}...` : String(wireValue).substring(0, 100)
-				};
-				throw decodeError;
-			}
-			continue;
-		}
-		if (wireValue === null || wireValue === void 0) {
-			decoded[alias] = wireValue;
-			continue;
-		}
-		const codec$1 = resolveRowCodec(alias, plan, registry);
-		if (!codec$1) {
-			decoded[alias] = wireValue;
-			continue;
-		}
-		try {
-			const decodedValue = codec$1.decode(wireValue);
-			if (jsonValidators) {
-				const ref = resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex);
-				if (ref) validateJsonValue(jsonValidators, ref.table, ref.column, decodedValue, "decode", codec$1.id);
-			}
-			decoded[alias] = decodedValue;
-		} catch (error) {
-			if (error instanceof Error && "code" in error && error.code === "RUNTIME.JSON_SCHEMA_VALIDATION_FAILED") throw error;
-			const decodeError = /* @__PURE__ */ new Error(`Failed to decode row alias '${alias}' with codec '${codec$1.id}': ${error instanceof Error ? error.message : String(error)}`);
-			decodeError.code = "RUNTIME.DECODE_FAILED";
-			decodeError.category = "RUNTIME";
-			decodeError.severity = "error";
-			decodeError.details = {
+			includeIndices.push({
+				index: i,
 				alias,
-				codec: codec$1.id,
-				wirePreview: typeof wireValue === "string" && wireValue.length > 100 ? `${wireValue.substring(0, 100)}...` : String(wireValue).substring(0, 100)
-			};
-			throw decodeError;
+				value: wireValue
+			});
+			tasks.push(Promise.resolve(void 0));
+			continue;
 		}
+		tasks.push(decodeField(alias, wireValue, plan, registry, jsonValidators, projection, fallbackColumnRefIndex));
 	}
+	const settled = await Promise.all(tasks);
+	for (const entry of includeIndices) settled[entry.index] = decodeIncludeAggregate(entry.alias, entry.value);
+	const decoded = {};
+	for (let i = 0; i < aliases.length; i++) decoded[aliases[i]] = settled[i];
 	return decoded;
 }
 
@@ -740,30 +864,166 @@ function resolveParamCodec(paramDescriptor, registry) {
 	}
 	return null;
 }
-function encodeParam(value, paramDescriptor, paramIndex, registry) {
+function paramLabel(paramDescriptor, paramIndex) {
+	return paramDescriptor.name ?? `param[${paramIndex}]`;
+}
+function wrapEncodeFailure(error, paramDescriptor, paramIndex, codecId) {
+	const label = paramLabel(paramDescriptor, paramIndex);
+	const wrapped = runtimeError("RUNTIME.ENCODE_FAILED", `Failed to encode parameter ${label} with codec '${codecId}': ${error instanceof Error ? error.message : String(error)}`, {
+		label,
+		codec: codecId,
+		paramIndex
+	});
+	wrapped.cause = error;
+	throw wrapped;
+}
+/**
+* Encodes a single parameter through its codec. Always awaits codec.encode so
+* a Promise can never leak into the driver, even if a sync-authored codec is
+* lifted to async by the codec() factory. Failures are wrapped in
+* `RUNTIME.ENCODE_FAILED` with `{ label, codec, paramIndex }` and the original
+* error attached on `cause`.
+*/
+async function encodeParam(value, paramDescriptor, paramIndex, registry) {
 	if (value === null || value === void 0) return null;
 	const codec$1 = resolveParamCodec(paramDescriptor, registry);
 	if (!codec$1) return value;
-	if (codec$1.encode) try {
-		return codec$1.encode(value);
+	try {
+		return await codec$1.encode(value);
 	} catch (error) {
-		const label = paramDescriptor.name ?? `param[${paramIndex}]`;
-		throw new Error(`Failed to encode parameter ${label}: ${error instanceof Error ? error.message : String(error)}`);
+		wrapEncodeFailure(error, paramDescriptor, paramIndex, codec$1.id);
 	}
-	return value;
 }
-function encodeParams(plan, registry) {
+/**
+* Encodes all parameters concurrently via `Promise.all`. Per parameter, sync-
+* and async-authored codecs share the same path: `codec.encode → await →
+* return`. Param-level failures are wrapped in `RUNTIME.ENCODE_FAILED`.
+*/
+async function encodeParams(plan, registry) {
 	if (plan.params.length === 0) return plan.params;
-	const encoded = [];
-	for (let i = 0; i < plan.params.length; i++) {
+	const descriptorCount = plan.meta.paramDescriptors.length;
+	const paramCount = plan.params.length;
+	const tasks = new Array(paramCount);
+	for (let i = 0; i < paramCount; i++) {
 		const paramValue = plan.params[i];
 		const paramDescriptor = plan.meta.paramDescriptors[i];
-		if (paramDescriptor) encoded.push(encodeParam(paramValue, paramDescriptor, i, registry));
-		else encoded.push(paramValue);
+		if (!paramDescriptor) throw runtimeError("RUNTIME.MISSING_PARAM_DESCRIPTOR", `Missing paramDescriptor for parameter at index ${i} (plan has ${paramCount} params, ${descriptorCount} descriptors). The planner must emit one descriptor per param; this is a contract violation.`, {
+			paramIndex: i,
+			paramCount,
+			descriptorCount
+		});
+		tasks[i] = encodeParam(paramValue, paramDescriptor, i, registry);
 	}
+	const encoded = await Promise.all(tasks);
 	return Object.freeze(encoded);
 }
 
+//#endregion
+//#region src/fingerprint.ts
+const STRING_LITERAL_REGEX = /'(?:''|[^'])*'/g;
+const NUMERIC_LITERAL_REGEX = /\b\d+(?:\.\d+)?\b/g;
+const WHITESPACE_REGEX = /\s+/g;
+/**
+* Computes a literal-stripped, normalized fingerprint of a SQL statement.
+*
+* The function strips string and numeric literals, collapses whitespace, and
+* lowercases the result before hashing — so two structurally equivalent
+* statements (with different parameter values) produce the same fingerprint.
+* Used by SQL telemetry to group queries.
+*/
+function computeSqlFingerprint(sql) {
+	const normalized = sql.replace(STRING_LITERAL_REGEX, "?").replace(NUMERIC_LITERAL_REGEX, "?").replace(WHITESPACE_REGEX, " ").trim().toLowerCase();
+	return `sha256:${createHash("sha256").update(normalized).digest("hex")}`;
+}
+
+//#endregion
+//#region src/marker.ts
+const MetaSchema = type({ "[string]": "unknown" });
+function parseMeta(meta) {
+	if (meta === null || meta === void 0) return {};
+	let parsed;
+	if (typeof meta === "string") try {
+		parsed = JSON.parse(meta);
+	} catch {
+		return {};
+	}
+	else parsed = meta;
+	const result = MetaSchema(parsed);
+	if (result instanceof type.errors) return {};
+	return result;
+}
+const ContractMarkerRowSchema = type({
+	core_hash: "string",
+	profile_hash: "string",
+	"contract_json?": "unknown | null",
+	"canonical_version?": "number | null",
+	"updated_at?": "Date | string",
+	"app_tag?": "string | null",
+	"meta?": "unknown | null"
+});
+function parseContractMarkerRow(row) {
+	const result = ContractMarkerRowSchema(row);
+	if (result instanceof type.errors) {
+		const messages = result.map((p) => p.message).join("; ");
+		throw new Error(`Invalid contract marker row: ${messages}`);
+	}
+	const validatedRow = result;
+	const updatedAt = validatedRow.updated_at ? validatedRow.updated_at instanceof Date ? validatedRow.updated_at : new Date(validatedRow.updated_at) : /* @__PURE__ */ new Date();
+	return {
+		storageHash: validatedRow.core_hash,
+		profileHash: validatedRow.profile_hash,
+		contractJson: validatedRow.contract_json ?? null,
+		canonicalVersion: validatedRow.canonical_version ?? null,
+		updatedAt,
+		appTag: validatedRow.app_tag ?? null,
+		meta: parseMeta(validatedRow.meta)
+	};
+}
+
+//#endregion
+//#region src/middleware/before-compile-chain.ts
+async function runBeforeCompileChain(middleware, initial, ctx) {
+	let current = initial;
+	for (const mw of middleware) {
+		if (!mw.beforeCompile) continue;
+		const result = await mw.beforeCompile(current, ctx);
+		if (result === void 0) continue;
+		if (result.ast === current.ast) continue;
+		ctx.log.debug?.({
+			event: "middleware.rewrite",
+			middleware: mw.name,
+			lane: current.meta.lane
+		});
+		current = result;
+	}
+	if (current.ast === initial.ast) return current;
+	const paramDescriptors = deriveParamDescriptorsFromAst(current.ast);
+	const meta = {
+		...current.meta,
+		paramDescriptors
+	};
+	return {
+		ast: current.ast,
+		meta
+	};
+}
+function deriveParamDescriptorsFromAst(ast) {
+	const refs = ast.collectParamRefs();
+	const seen = /* @__PURE__ */ new Set();
+	const descriptors = [];
+	for (const ref of refs) {
+		if (seen.has(ref)) continue;
+		seen.add(ref);
+		descriptors.push({
+			index: descriptors.length + 1,
+			...ref.name !== void 0 ? { name: ref.name } : {},
+			source: "dsl",
+			...ref.codecId !== void 0 ? { codecId: ref.codecId } : {}
+		});
+	}
+	return descriptors;
+}
+
 //#endregion
 //#region src/sql-family-adapter.ts
 var SqlFamilyAdapter = class {
@@ -787,93 +1047,214 @@ var SqlFamilyAdapter = class {
 
 //#endregion
 //#region src/sql-runtime.ts
-var SqlRuntimeImpl = class {
-	core;
+function isExecutionPlan(plan) {
+	return "sql" in plan;
+}
+var SqlRuntimeImpl = class extends RuntimeCore {
 	contract;
 	adapter;
+	driver;
+	familyAdapter;
 	codecRegistry;
 	jsonSchemaValidators;
+	sqlCtx;
+	verify;
 	codecRegistryValidated;
+	verified;
+	startupVerified;
+	_telemetry;
 	constructor(options) {
 		const { context, adapter, driver, verify, middleware, mode, log } = options;
+		if (middleware) for (const mw of middleware) checkMiddlewareCompatibility(mw, "sql", context.contract.target);
+		const sqlCtx = {
+			contract: context.contract,
+			mode: mode ?? "strict",
+			now: () => Date.now(),
+			log: log ?? {
+				info: () => {},
+				warn: () => {},
+				error: () => {}
+			}
+		};
+		super({
+			middleware: middleware ?? [],
+			ctx: sqlCtx
+		});
 		this.contract = context.contract;
 		this.adapter = adapter;
+		this.driver = driver;
+		this.familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
 		this.codecRegistry = context.codecs;
 		this.jsonSchemaValidators = context.jsonSchemaValidators;
+		this.sqlCtx = sqlCtx;
+		this.verify = verify;
 		this.codecRegistryValidated = false;
-		if (middleware) for (const mw of middleware) checkMiddlewareCompatibility(mw, "sql", context.contract.target);
-		this.core = createRuntimeCore({
-			familyAdapter: new SqlFamilyAdapter(context.contract, adapter.profile),
-			driver,
-			verify,
-			...ifDefined("middleware", middleware),
-			...ifDefined("mode", mode),
-			...ifDefined("log", log)
-		});
+		this.verified = verify.mode === "startup" ? false : verify.mode === "always";
+		this.startupVerified = false;
+		this._telemetry = null;
 		if (verify.mode === "startup") {
 			validateCodecRegistryCompleteness(this.codecRegistry, context.contract);
 			this.codecRegistryValidated = true;
 		}
 	}
-	ensureCodecRegistryValidated(contract) {
-		if (!this.codecRegistryValidated) {
-			validateCodecRegistryCompleteness(this.codecRegistry, contract);
-			this.codecRegistryValidated = true;
-		}
+	/**
+	* Lower a `SqlQueryPlan` (AST + meta) into a `SqlExecutionPlan` with
+	* encoded parameters ready for the driver. This is the single point at
+	* which params transition from app-layer values to driver wire-format.
+	*/
+	async lower(plan) {
+		const lowered = lowerSqlPlan(this.adapter, this.contract, plan);
+		return Object.freeze({
+			...lowered,
+			params: await encodeParams(lowered, this.codecRegistry)
+		});
 	}
-	toExecutionPlan(plan) {
-		const isSqlQueryPlan = (p) => {
-			return "ast" in p && !("sql" in p);
-		};
-		return isSqlQueryPlan(plan) ? lowerSqlPlan(this.adapter, this.contract, plan) : plan;
+	/**
+	* Default driver invocation. Production execution paths override the
+	* queryable target (e.g. transaction or connection) by going through
+	* `executeAgainstQueryable`; this implementation supports any caller of
+	* `super.execute(plan)` and the abstract-base contract.
+	*/
+	runDriver(exec) {
+		return this.driver.execute({
+			sql: exec.sql,
+			params: exec.params
+		});
 	}
-	executeAgainstQueryable(plan, queryable) {
-		this.ensureCodecRegistryValidated(this.contract);
-		const executablePlan = this.toExecutionPlan(plan);
-		const iterator = async function* (self) {
-			const encodedParams = encodeParams(executablePlan, self.codecRegistry);
-			const planWithEncodedParams = {
-				...executablePlan,
-				params: encodedParams
-			};
-			const coreIterator = queryable.execute(planWithEncodedParams);
-			for await (const rawRow of coreIterator) yield decodeRow(rawRow, executablePlan, self.codecRegistry, self.jsonSchemaValidators);
+	/**
+	* SQL pre-compile hook. Runs the registered middleware `beforeCompile`
+	* chain over the plan's draft (AST + meta) and returns a `SqlQueryPlan`
+	* with the rewritten AST and meta when the chain mutates them. The chain
+	* re-derives `meta.paramDescriptors` from the rewritten AST so descriptors
+	* stay in lockstep with the params the adapter will emit during lowering.
+	*/
+	async runBeforeCompile(plan) {
+		const rewrittenDraft = await runBeforeCompileChain(this.middleware, {
+			ast: plan.ast,
+			meta: plan.meta
+		}, this.sqlCtx);
+		return rewrittenDraft.ast === plan.ast ? plan : {
+			...plan,
+			ast: rewrittenDraft.ast,
+			meta: rewrittenDraft.meta
 		};
-		return new AsyncIterableResult(iterator(this));
 	}
 	execute(plan) {
-		return this.executeAgainstQueryable(plan, this.core);
+		return this.executeAgainstQueryable(plan, this.driver);
+	}
+	executeAgainstQueryable(plan, queryable) {
+		this.ensureCodecRegistryValidated();
+		const self = this;
+		const generator = async function* () {
+			const exec = isExecutionPlan(plan) ? Object.freeze({
+				...plan,
+				params: await encodeParams(plan, self.codecRegistry)
+			}) : await self.lower(await self.runBeforeCompile(plan));
+			self.familyAdapter.validatePlan(exec, self.contract);
+			self._telemetry = null;
+			if (!self.startupVerified && self.verify.mode === "startup") await self.verifyMarker();
+			if (!self.verified && self.verify.mode === "onFirstUse") await self.verifyMarker();
+			const startedAt = Date.now();
+			let outcome = null;
+			try {
+				if (self.verify.mode === "always") await self.verifyMarker();
+				const stream = runWithMiddleware(exec, self.middleware, self.ctx, () => queryable.execute({
+					sql: exec.sql,
+					params: exec.params
+				}));
+				for await (const rawRow of stream) yield await decodeRow(rawRow, exec, self.codecRegistry, self.jsonSchemaValidators);
+				outcome = "success";
+			} catch (error) {
+				outcome = "runtime-error";
+				throw error;
+			} finally {
+				if (outcome !== null) self.recordTelemetry(exec, outcome, Date.now() - startedAt);
+			}
+		};
+		return new AsyncIterableResult(generator());
 	}
 	async connection() {
-		const coreConn = await this.core.connection();
+		const driverConn = await this.driver.acquireConnection();
 		const self = this;
 		return {
 			async transaction() {
-				const coreTx = await coreConn.transaction();
-				return {
-					commit: coreTx.commit.bind(coreTx),
-					rollback: coreTx.rollback.bind(coreTx),
-					execute(plan) {
-						return self.executeAgainstQueryable(plan, coreTx);
-					}
-				};
+				const driverTx = await driverConn.beginTransaction();
+				return self.wrapTransaction(driverTx);
+			},
+			async release() {
+				await driverConn.release();
+			},
+			async destroy(reason) {
+				await driverConn.destroy(reason);
 			},
-			release: coreConn.release.bind(coreConn),
-			destroy: coreConn.destroy.bind(coreConn),
 			execute(plan) {
-				return self.executeAgainstQueryable(plan, coreConn);
+				return self.executeAgainstQueryable(plan, driverConn);
+			}
+		};
+	}
+	wrapTransaction(driverTx) {
+		const self = this;
+		return {
+			async commit() {
+				await driverTx.commit();
+			},
+			async rollback() {
+				await driverTx.rollback();
+			},
+			execute(plan) {
+				return self.executeAgainstQueryable(plan, driverTx);
 			}
 		};
 	}
 	telemetry() {
-		return this.core.telemetry();
+		return this._telemetry;
+	}
+	async close() {
+		await this.driver.close();
 	}
-	close() {
-		return this.core.close();
+	ensureCodecRegistryValidated() {
+		if (!this.codecRegistryValidated) {
+			validateCodecRegistryCompleteness(this.codecRegistry, this.contract);
+			this.codecRegistryValidated = true;
+		}
+	}
+	async verifyMarker() {
+		if (this.verify.mode === "always") this.verified = false;
+		if (this.verified) return;
+		const readStatement = this.familyAdapter.markerReader.readMarkerStatement();
+		const result = await this.driver.query(readStatement.sql, readStatement.params);
+		if (result.rows.length === 0) {
+			if (this.verify.requireMarker) throw runtimeError("CONTRACT.MARKER_MISSING", "Contract marker not found in database");
+			this.verified = true;
+			return;
+		}
+		const marker = parseContractMarkerRow(result.rows[0]);
+		const contract = this.contract;
+		if (marker.storageHash !== contract.storage.storageHash) throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database storage hash does not match contract", {
+			expected: contract.storage.storageHash,
+			actual: marker.storageHash
+		});
+		const expectedProfile = contract.profileHash ?? null;
+		if (expectedProfile !== null && marker.profileHash !== expectedProfile) throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database profile hash does not match contract", {
+			expectedProfile,
+			actualProfile: marker.profileHash
+		});
+		this.verified = true;
+		this.startupVerified = true;
+	}
+	recordTelemetry(plan, outcome, durationMs) {
+		const contract = this.contract;
+		this._telemetry = Object.freeze({
+			lane: plan.meta.lane,
+			target: contract.target,
+			fingerprint: computeSqlFingerprint(plan.sql),
+			outcome,
+			...durationMs !== void 0 ? { durationMs } : {}
+		});
 	}
 };
 function transactionClosedError() {
-	return runtimeError$1("RUNTIME.TRANSACTION_CLOSED", "Cannot read from a query result after the transaction has ended. Await the result or call .toArray() inside the transaction callback.", {});
+	return runtimeError("RUNTIME.TRANSACTION_CLOSED", "Cannot read from a query result after the transaction has ended. Await the result or call .toArray() inside the transaction callback.", {});
 }
 async function withTransaction(runtime, fn) {
 	const connection = await runtime.connection();
@@ -910,7 +1291,7 @@ async function withTransaction(runtime, fn) {
 				await transaction.rollback();
 			} catch (rollbackError) {
 				await destroyConnection(rollbackError);
-				const wrapped = runtimeError$1("RUNTIME.TRANSACTION_ROLLBACK_FAILED", "Transaction rollback failed after callback error", { rollbackError });
+				const wrapped = runtimeError("RUNTIME.TRANSACTION_ROLLBACK_FAILED", "Transaction rollback failed after callback error", { rollbackError });
 				wrapped.cause = error;
 				throw wrapped;
 			}
@@ -926,7 +1307,7 @@ async function withTransaction(runtime, fn) {
 			} catch {
 				await destroyConnection(commitError);
 			}
-			const wrapped = runtimeError$1("RUNTIME.TRANSACTION_COMMIT_FAILED", "Transaction commit failed", { commitError });
+			const wrapped = runtimeError("RUNTIME.TRANSACTION_COMMIT_FAILED", "Transaction commit failed", { commitError });
 			wrapped.cause = commitError;
 			throw wrapped;
 		}
@@ -950,4 +1331,4 @@ function createRuntime(options) {
 
 //#endregion
 export { readContractMarker as a, createSqlExecutionStack as c, lowerSqlPlan as d, extractCodecIds as f, ensureTableStatement as i, lints as l, validateContractCodecMappings as m, withTransaction as n, writeContractMarker as o, validateCodecRegistryCompleteness as p, ensureSchemaStatement as r, createExecutionContext as s, createRuntime as t, budgets as u };
-//# sourceMappingURL=exports-TJ70Qw3r.mjs.map
+//# sourceMappingURL=exports-BOHa3Emo.mjs.map