@prisma-next/sql-runtime 0.5.0-dev.3 → 0.5.0-dev.30

package/dist/{exports-BQZSVXXt.mjs → exports-Cq_9ZrU4.mjs}

@@ -1,11 +1,11 @@
-import { checkMiddlewareCompatibility, 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 { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
+import { type } from "arktype";
+import { collectOrderedParamRefs, createCodecRegistry, isQueryAst } from "@prisma-next/sql-relational-core/ast";
 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) {
@@ -73,31 +73,72 @@ function lowerSqlPlan(adapter, contract, queryPlan) {
 	});
 }
 
+//#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",
+	invariants: type("string").array()
+});
+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 updatedAt = result.updated_at ? result.updated_at instanceof Date ? result.updated_at : new Date(result.updated_at) : /* @__PURE__ */ new Date();
+	return {
+		storageHash: result.core_hash,
+		profileHash: result.profile_hash,
+		contractJson: result.contract_json ?? null,
+		canonicalVersion: result.canonical_version ?? null,
+		updatedAt,
+		appTag: result.app_tag ?? null,
+		meta: parseMeta(result.meta),
+		invariants: result.invariants
+	};
+}
+
 //#endregion
 //#region src/middleware/budgets.ts
 function hasAggregateWithoutGroupBy(ast) {
 	if (ast.groupBy !== void 0) return false;
 	return ast.projection.some((item) => item.expr.kind === "aggregate");
 }
-function estimateRowsFromAst(ast, tableRows, defaultTableRows, refs, hasAggregateWithoutGroup) {
+function primaryTableFromAst(ast) {
+	switch (ast.from.kind) {
+		case "table-source": return ast.from.name;
+		case "derived-table-source": return ast.from.alias;
+		default: return;
+	}
+}
+function estimateRowsFromAst(ast, tableRows, defaultTableRows, hasAggregateWithoutGroup) {
 	if (hasAggregateWithoutGroup) return 1;
-	const table = refs?.tables?.[0];
+	const table = primaryTableFromAst(ast);
 	if (!table) return null;
 	const tableEstimate = tableRows[table] ?? defaultTableRows;
 	if (ast.limit !== void 0) return Math.min(ast.limit, tableEstimate);
 	return tableEstimate;
 }
-function estimateRowsFromHeuristics(plan, tableRows, defaultTableRows) {
-	const table = plan.meta.refs?.tables?.[0];
-	if (!table) return null;
-	const tableEstimate = tableRows[table] ?? defaultTableRows;
-	const limit = plan.meta.annotations?.["limit"];
-	if (typeof limit === "number") return Math.min(limit, tableEstimate);
-	return tableEstimate;
-}
-function hasDetectableLimitFromHeuristics(plan) {
-	return typeof plan.meta.annotations?.["limit"] === "number";
-}
 function emitBudgetViolation(error, shouldBlock, ctx) {
 	if (shouldBlock) throw error;
 	ctx.log.warn({
@@ -118,11 +159,7 @@ function budgets(options) {
 		familyId: "sql",
 		async beforeExecute(plan, ctx) {
 			observedRowsByPlan.set(plan, { count: 0 });
-			if (isQueryAst(plan.ast)) {
-				if (plan.ast.kind === "select") return evaluateSelectAst(plan, plan.ast, ctx);
-				return;
-			}
-			return evaluateWithHeuristics(plan, ctx);
+			if (isQueryAst(plan.ast) && plan.ast.kind === "select") return evaluateSelectAst(plan.ast, ctx);
 		},
 		async onRow(_row, plan, _ctx) {
 			const state = observedRowsByPlan.get(plan);
@@ -145,9 +182,9 @@ function budgets(options) {
 			}
 		}
 	});
-	function evaluateSelectAst(plan, ast, ctx) {
+	function evaluateSelectAst(ast, ctx) {
 		const hasAggNoGroup = hasAggregateWithoutGroupBy(ast);
-		const estimated = estimateRowsFromAst(ast, tableRows, defaultTableRows, plan.meta.refs, hasAggNoGroup);
+		const estimated = estimateRowsFromAst(ast, tableRows, defaultTableRows, hasAggNoGroup);
 		const isUnbounded = ast.limit === void 0 && !hasAggNoGroup;
 		const shouldBlock = rowSeverity === "error" || ctx.mode === "strict";
 		if (isUnbounded) {
@@ -171,35 +208,83 @@ function budgets(options) {
 			maxRows
 		}), shouldBlock, ctx);
 	}
-	async function evaluateWithHeuristics(plan, ctx) {
-		const estimated = estimateRowsFromHeuristics(plan, tableRows, defaultTableRows);
-		const isUnbounded = !hasDetectableLimitFromHeuristics(plan);
-		const isSelect = plan.sql.trimStart().toUpperCase().startsWith("SELECT");
-		const shouldBlock = rowSeverity === "error" || ctx.mode === "strict";
-		if (isSelect && isUnbounded) {
-			if (estimated !== null && estimated >= maxRows) {
-				emitBudgetViolation(runtimeError("BUDGET.ROWS_EXCEEDED", "Unbounded SELECT query exceeds budget", {
-					source: "heuristic",
-					estimatedRows: estimated,
-					maxRows
-				}), shouldBlock, ctx);
-				return;
-			}
-			emitBudgetViolation(runtimeError("BUDGET.ROWS_EXCEEDED", "Unbounded SELECT query exceeds budget", {
-				source: "heuristic",
-				maxRows
-			}), shouldBlock, ctx);
-			return;
-		}
-		if (estimated !== null) {
-			if (estimated > maxRows) emitBudgetViolation(runtimeError("BUDGET.ROWS_EXCEEDED", "Estimated row count exceeds budget", {
-				source: "heuristic",
-				estimatedRows: estimated,
-				maxRows
-			}), shouldBlock, ctx);
-			return;
+}
+
+//#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"]
+	}));
+	return {
+		lints: lints$1,
+		budgets: budgets$1,
+		statement: statementType
+	};
+}
+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
@@ -516,7 +601,8 @@ const ensureTableStatement = {
     canonical_version int,
     updated_at timestamptz not null default now(),
     app_tag text,
-    meta jsonb not null default '{}'
+    meta jsonb not null default '{}',
+    invariants text[] not null default '{}'
   )`,
 	params: []
 };
@@ -529,56 +615,82 @@ function readContractMarker() {
       canonical_version,
       updated_at,
       app_tag,
-      meta
+      meta,
+      invariants
     from prisma_contract.marker
     where id = $1`,
 		params: [1]
 	};
 }
-function writeContractMarker(input) {
-	const baseParams = [
-		1,
-		input.storageHash,
-		input.profileHash,
-		input.contractJson ?? null,
-		input.canonicalVersion ?? null,
-		input.appTag ?? null,
-		JSON.stringify(input.meta ?? {})
+/**
+* Variable columns that participate in INSERT/UPDATE alongside the
+* always-on `id = $1` and `updated_at = now()`. Each column declares
+* its name, optional cast type, and parameter value; the placeholder
+* (`$N`) is computed positionally below — adding or reordering a
+* column doesn't desync indices. `invariants` only appears when the
+* caller supplies it — see `WriteMarkerInput.invariants`.
+*/
+function markerColumns(input) {
+	return [
+		{
+			name: "core_hash",
+			param: input.storageHash
+		},
+		{
+			name: "profile_hash",
+			param: input.profileHash
+		},
+		{
+			name: "contract_json",
+			type: "jsonb",
+			param: input.contractJson ?? null
+		},
+		{
+			name: "canonical_version",
+			param: input.canonicalVersion ?? null
+		},
+		{
+			name: "app_tag",
+			param: input.appTag ?? null
+		},
+		{
+			name: "meta",
+			type: "jsonb",
+			param: JSON.stringify(input.meta ?? {})
+		},
+		...input.invariants !== void 0 ? [{
+			name: "invariants",
+			type: "text[]",
+			param: input.invariants
+		}] : []
 	];
+}
+function writeContractMarker(input) {
+	const placed = markerColumns(input).map((c, i) => ({
+		name: c.name,
+		expr: c.type ? `$${i + 2}::${c.type}` : `$${i + 2}`,
+		param: c.param
+	}));
+	const params = [1, ...placed.map((c) => c.param)];
+	const insertColumns = [
+		"id",
+		...placed.map((c) => c.name),
+		"updated_at"
+	].join(", ");
+	const insertValues = [
+		"$1",
+		...placed.map((c) => c.expr),
+		"now()"
+	].join(", ");
+	const setClauses = [...placed.map((c) => `${c.name} = ${c.expr}`), "updated_at = now()"].join(", ");
 	return {
 		insert: {
-			sql: `insert into prisma_contract.marker (
-        id,
-        core_hash,
-        profile_hash,
-        contract_json,
-        canonical_version,
-        updated_at,
-        app_tag,
-        meta
-      ) values (
-        $1,
-        $2,
-        $3,
-        $4::jsonb,
-        $5,
-        now(),
-        $6,
-        $7::jsonb
-      )`,
-			params: baseParams
+			sql: `insert into prisma_contract.marker (${insertColumns}) values (${insertValues})`,
+			params
 		},
 		update: {
-			sql: `update prisma_contract.marker set
-        core_hash = $2,
-        profile_hash = $3,
-        contract_json = $4::jsonb,
-        canonical_version = $5,
-        updated_at = now(),
-        app_tag = $6,
-        meta = $7::jsonb
-      where id = $1`,
-			params: baseParams
+			sql: `update prisma_contract.marker set ${setClauses} where id = $1`,
+			params
 		}
 	};
 }
@@ -619,149 +731,279 @@ function formatErrorSummary(errors) {
 
 //#endregion
 //#region src/codecs/decoding.ts
-function resolveRowCodec(alias, plan, registry) {
-	const planCodecId = plan.meta.annotations?.codecs?.[alias];
-	if (planCodecId) {
-		const codec$1 = registry.get(planCodecId);
-		if (codec$1) return codec$1;
-	}
-	if (plan.meta.projectionTypes) {
-		const typeId = plan.meta.projectionTypes[alias];
-		if (typeId) {
-			const codec$1 = registry.get(typeId);
-			if (codec$1) return codec$1;
+const WIRE_PREVIEW_LIMIT = 100;
+const EMPTY_INCLUDE_ALIASES = /* @__PURE__ */ new Set();
+function isAstBackedPlan(plan) {
+	return plan.ast !== void 0;
+}
+function projectionListFromAst(ast) {
+	if (ast.kind === "select") return ast.projection;
+	return ast.returning;
+}
+function buildDecodeContext(plan, registry) {
+	if (!isAstBackedPlan(plan)) return {
+		aliases: void 0,
+		codecs: /* @__PURE__ */ new Map(),
+		columnRefs: /* @__PURE__ */ new Map(),
+		includeAliases: EMPTY_INCLUDE_ALIASES
+	};
+	const projection = projectionListFromAst(plan.ast);
+	if (!projection) return {
+		aliases: void 0,
+		codecs: /* @__PURE__ */ new Map(),
+		columnRefs: /* @__PURE__ */ new Map(),
+		includeAliases: EMPTY_INCLUDE_ALIASES
+	};
+	const aliases = [];
+	const codecs = /* @__PURE__ */ new Map();
+	const columnRefs = /* @__PURE__ */ new Map();
+	const includeAliases = /* @__PURE__ */ new Set();
+	for (const item of projection) {
+		aliases.push(item.alias);
+		if (item.codecId) {
+			const codec$1 = registry.get(item.codecId);
+			if (codec$1) codecs.set(item.alias, codec$1);
 		}
+		if (item.expr.kind === "column-ref") columnRefs.set(item.alias, {
+			table: item.expr.table,
+			column: item.expr.column
+		});
+		else if (item.expr.kind === "subquery" || item.expr.kind === "json-array-agg") includeAliases.add(item.alias);
+	}
+	return {
+		aliases,
+		codecs,
+		columnRefs,
+		includeAliases
+	};
+}
+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);
 	}
-	return null;
 }
 /**
-* Builds a lookup index from column name → { table, column } ref.
-* Called once per decodeRow invocation to avoid O(aliases × refs) linear scans.
+* 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.
+*
+* The row-level `rowCtx` is repackaged into a per-cell
+* `SqlCodecCallContext` whose `column = { table, name }` is a structural
+* projection of the per-cell `ColumnRef = { table, column }` resolved from
+* the AST-backed `DecodeContext` (the same resolution `wrapDecodeFailure`
+* uses for envelope construction — one resolution per cell, two consumers).
+* Cells the runtime cannot resolve to a single underlying column (aggregate
+* aliases, computed projections without a simple ref) get
+* `column: undefined`, matching the spec contract that the runtime never
+* silently defaults this field.
 */
-function buildColumnRefIndex(plan) {
-	const columns = plan.meta.refs?.columns;
-	if (!columns) return null;
-	const index = /* @__PURE__ */ new Map();
-	for (const ref of columns) index.set(ref.column, ref);
-	return index;
-}
-function parseProjectionRef(value) {
-	if (value.startsWith("include:") || value.startsWith("operation:")) return null;
-	const separatorIndex = value.indexOf(".");
-	if (separatorIndex <= 0 || separatorIndex === value.length - 1) return null;
-	return {
-		table: value.slice(0, separatorIndex),
-		column: value.slice(separatorIndex + 1)
+async function decodeField(alias, wireValue, decodeCtx, jsonValidators, rowCtx) {
+	if (wireValue === null) return null;
+	const codec$1 = decodeCtx.codecs.get(alias);
+	if (!codec$1) return wireValue;
+	const ref = decodeCtx.columnRefs.get(alias);
+	let cellCtx;
+	if (ref) cellCtx = {
+		...rowCtx,
+		column: {
+			table: ref.table,
+			name: ref.column
+		}
 	};
-}
-function resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex) {
-	if (projection && !Array.isArray(projection)) {
-		const mappedRef = projection[alias];
-		if (typeof mappedRef !== "string") return;
-		return parseProjectionRef(mappedRef) ?? void 0;
+	else {
+		const { column: _drop, ...rowCtxWithoutColumn } = rowCtx;
+		cellCtx = rowCtxWithoutColumn;
+	}
+	let decoded;
+	try {
+		decoded = await codec$1.decode(wireValue, cellCtx);
+	} 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 fallbackColumnRefIndex?.get(alias);
+	return decoded;
 }
-function decodeRow(row, plan, registry, jsonValidators) {
-	const decoded = {};
-	const projection = plan.meta.projection;
-	const fallbackColumnRefIndex = jsonValidators && (!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) {
+/**
+* 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`.
+*
+* When `rowCtx.signal` is provided:
+*
+* - **Already-aborted at entry** short-circuits with `RUNTIME.ABORTED`
+*   (`{ phase: 'decode' }`) before any `codec.decode` call is made.
+* - **Mid-flight aborts** race the per-cell `Promise.all` against the
+*   signal so the runtime returns promptly even when codec bodies ignore
+*   it. In-flight bodies that ignore the signal complete in the
+*   background (cooperative cancellation).
+* - Existing `RUNTIME.DECODE_FAILED` envelopes from codec bodies pass
+*   through unchanged (no double wrap).
+*/
+async function decodeRow(row, plan, registry, jsonValidators, rowCtx) {
+	checkAborted(rowCtx, "decode");
+	const signal = rowCtx.signal;
+	const decodeCtx = buildDecodeContext(plan, registry);
+	const aliases = decodeCtx.aliases ?? Object.keys(row);
+	if (decodeCtx.aliases !== void 0) {
+		for (const alias of decodeCtx.aliases) if (!Object.hasOwn(row, alias)) throw runtimeError("RUNTIME.DECODE_FAILED", `Row missing projection alias "${alias}"`, {
+			alias,
+			expectedAliases: decodeCtx.aliases,
+			presentKeys: Object.keys(row)
+		});
+	}
+	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 = {
+		if (decodeCtx.includeAliases.has(alias)) {
+			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, decodeCtx, jsonValidators, rowCtx));
 	}
+	const settled = await raceAgainstAbort(Promise.all(tasks), signal, "decode");
+	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;
 }
 
 //#endregion
 //#region src/codecs/encoding.ts
-function resolveParamCodec(paramDescriptor, registry) {
-	if (paramDescriptor.codecId) {
-		const codec$1 = registry.get(paramDescriptor.codecId);
-		if (codec$1) return codec$1;
-	}
-	return null;
+const NO_METADATA = Object.freeze({
+	codecId: void 0,
+	name: void 0
+});
+function paramLabel(metadata, paramIndex) {
+	return metadata.name ?? `param[${paramIndex}]`;
+}
+function wrapEncodeFailure(error, metadata, paramIndex, codecId) {
+	const label = paramLabel(metadata, 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;
 }
-function encodeParam(value, paramDescriptor, paramIndex, registry) {
+async function encodeParamValue(value, metadata, paramIndex, registry, ctx) {
 	if (value === null || value === void 0) return null;
-	const codec$1 = resolveParamCodec(paramDescriptor, registry);
+	if (!metadata.codecId) return value;
+	const codec$1 = registry.get(metadata.codecId);
 	if (!codec$1) return value;
-	if (codec$1.encode) try {
-		return codec$1.encode(value);
+	try {
+		return await codec$1.encode(value, ctx);
 	} 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, metadata, 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`.
+*
+* When `ctx.signal` is provided:
+*
+* - **Already-aborted at entry** short-circuits with `RUNTIME.ABORTED`
+*   (`{ phase: 'encode' }`) before any `codec.encode` call is made — codecs
+*   can pin this with a per-call counter that stays at zero.
+* - **Mid-flight abort** races the per-param `Promise.all` against
+*   `abortable(ctx.signal)`. The runtime returns `RUNTIME.ABORTED` promptly
+*   even if codec bodies ignore the signal; the in-flight bodies are
+*   abandoned and run to completion in the background (cooperative
+*   cancellation, see ADR 204).
+* - Existing `RUNTIME.ENCODE_FAILED` envelopes that surface from a codec
+*   body before the runtime observes the abort pass through unchanged
+*   (no double wrap).
+*/
+async function encodeParams(plan, registry, ctx) {
+	checkAborted(ctx, "encode");
+	const signal = ctx.signal;
 	if (plan.params.length === 0) return plan.params;
-	const encoded = [];
-	for (let i = 0; i < plan.params.length; 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);
+	const paramCount = plan.params.length;
+	const metadata = new Array(paramCount).fill(NO_METADATA);
+	if (plan.ast) {
+		const refs = collectOrderedParamRefs(plan.ast);
+		for (let i = 0; i < paramCount && i < refs.length; i++) {
+			const ref = refs[i];
+			if (ref) metadata[i] = {
+				codecId: ref.codecId,
+				name: ref.name
+			};
+		}
 	}
-	return Object.freeze(encoded);
+	const tasks = new Array(paramCount);
+	for (let i = 0; i < paramCount; i++) tasks[i] = encodeParamValue(plan.params[i], metadata[i] ?? NO_METADATA, i, registry, ctx);
+	const settled = await raceAgainstAbort(Promise.all(tasks), signal, "encode");
+	return Object.freeze(settled);
+}
+
+//#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
@@ -806,102 +1048,234 @@ 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.
+	*
+	* `ctx: SqlCodecCallContext` is forwarded to `encodeParams` so per-query
+	* cancellation reaches every codec body during parameter encoding. The
+	* framework abstract typed this as `CodecCallContext`; the SQL family
+	* narrows it to the SQL-specific extension. SQL params do not populate
+	* `ctx.column` — encode-side column metadata is the middleware's domain.
+	*/
+	async lower(plan, ctx) {
+		const lowered = lowerSqlPlan(this.adapter, this.contract, plan);
+		return Object.freeze({
+			...lowered,
+			params: await encodeParams(lowered, this.codecRegistry, ctx)
+		});
 	}
-	async toExecutionPlan(plan) {
-		const isSqlQueryPlan = (p) => {
-			return "ast" in p && !("sql" in p);
-		};
-		if (!isSqlQueryPlan(plan)) return plan;
-		const rewrittenDraft = await runBeforeCompileChain(this.core.middleware, {
+	/**
+	* 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
+		});
+	}
+	/**
+	* SQL pre-compile hook. Runs the registered middleware `beforeCompile`
+	* chain over the plan's draft (AST + meta). Returns the original plan
+	* unchanged when no middleware rewrote the AST; otherwise returns a new
+	* plan carrying the rewritten AST and meta. The AST is the authoritative
+	* source of execution metadata, so a rewrite needs no sidecar
+	* reconciliation here — the lowering adapter and the encoder both walk
+	* the rewritten AST directly.
+	*/
+	async runBeforeCompile(plan) {
+		const rewrittenDraft = await runBeforeCompileChain(this.middleware, {
 			ast: plan.ast,
 			meta: plan.meta
-		}, this.core.middlewareContext);
-		const planToLower = rewrittenDraft.ast === plan.ast ? plan : {
+		}, this.sqlCtx);
+		return rewrittenDraft.ast === plan.ast ? plan : {
 			...plan,
-			ast: rewrittenDraft.ast
-		};
-		return lowerSqlPlan(this.adapter, this.contract, planToLower);
-	}
-	executeAgainstQueryable(plan, queryable) {
-		this.ensureCodecRegistryValidated(this.contract);
-		const iterator = async function* (self) {
-			const executablePlan = await self.toExecutionPlan(plan);
-			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);
+			ast: rewrittenDraft.ast,
+			meta: rewrittenDraft.meta
 		};
-		return new AsyncIterableResult(iterator(this));
 	}
-	execute(plan) {
-		return this.executeAgainstQueryable(plan, this.core);
+	execute(plan, options) {
+		return this.executeAgainstQueryable(plan, this.driver, options);
+	}
+	executeAgainstQueryable(plan, queryable, options) {
+		this.ensureCodecRegistryValidated();
+		const self = this;
+		const signal = options?.signal;
+		const codecCtx = signal === void 0 ? {} : { signal };
+		const generator = async function* () {
+			checkAborted(codecCtx, "stream");
+			const exec = isExecutionPlan(plan) ? Object.freeze({
+				...plan,
+				params: await encodeParams(plan, self.codecRegistry, codecCtx)
+			}) : await self.lower(await self.runBeforeCompile(plan), codecCtx);
+			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 iterator = runWithMiddleware(exec, self.middleware, self.ctx, () => queryable.execute({
+					sql: exec.sql,
+					params: exec.params
+				}))[Symbol.asyncIterator]();
+				try {
+					while (true) {
+						checkAborted(codecCtx, "stream");
+						const next = await iterator.next();
+						if (next.done) break;
+						yield await decodeRow(next.value, exec, self.codecRegistry, self.jsonSchemaValidators, codecCtx);
+					}
+				} finally {
+					await iterator.return?.();
+				}
+				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);
+			},
+			execute(plan, options) {
+				return self.executeAgainstQueryable(plan, driverConn, options);
+			}
+		};
+	}
+	wrapTransaction(driverTx) {
+		const self = this;
+		return {
+			async commit() {
+				await driverTx.commit();
+			},
+			async rollback() {
+				await driverTx.rollback();
 			},
-			release: coreConn.release.bind(coreConn),
-			destroy: coreConn.destroy.bind(coreConn),
-			execute(plan) {
-				return self.executeAgainstQueryable(plan, coreConn);
+			execute(plan, options) {
+				return self.executeAgainstQueryable(plan, driverTx, options);
 			}
 		};
 	}
 	telemetry() {
-		return this.core.telemetry();
+		return this._telemetry;
 	}
-	close() {
-		return this.core.close();
+	async close() {
+		await this.driver.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 = this.familyAdapter.markerReader.parseMarkerRow(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();
@@ -911,9 +1285,9 @@ async function withTransaction(runtime, fn) {
 		get invalidated() {
 			return invalidated;
 		},
-		execute(plan) {
+		execute(plan, options) {
 			if (invalidated) throw transactionClosedError();
-			const inner = transaction.execute(plan);
+			const inner = transaction.execute(plan, options);
 			const guarded = async function* () {
 				for await (const row of inner) {
 					if (invalidated) throw transactionClosedError();
@@ -938,7 +1312,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;
 			}
@@ -954,7 +1328,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;
 		}
@@ -977,5 +1351,5 @@ 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-BQZSVXXt.mjs.map
+export { readContractMarker as a, createSqlExecutionStack as c, parseContractMarkerRow as d, lowerSqlPlan as f, validateContractCodecMappings as h, ensureTableStatement as i, lints as l, validateCodecRegistryCompleteness as m, withTransaction as n, writeContractMarker as o, extractCodecIds as p, ensureSchemaStatement as r, createExecutionContext as s, createRuntime as t, budgets as u };
+//# sourceMappingURL=exports-Cq_9ZrU4.mjs.map