@prisma/orm-family-sql 0.16.0-dev.36

package/dist/runtime.mjs

@@ -0,0 +1,1606 @@
+import { t as createSqlOperationRegistry } from "./dist-C_q1_QR9.mjs";
+import { A as PreparedParamRef, B as isQueryAst } from "./types-BgkZru_1-H7yfikSQ.mjs";
+import { t as collectOrderedParamRefs } from "./util-DQQgv2j1-D6INZaRG.mjs";
+import { t as createSqlParamRefMutator } from "./middleware-CMr4CHNz-DHIUdxlm.mjs";
+import { t as buildCodecDescriptorRegistry } from "./codec-descriptor-registry-BJVJRftS.mjs";
+import { isStructuredError } from "@prisma/orm-framework/utils/structured-error";
+import { createHash } from "node:crypto";
+import { assertNever } from "@prisma/orm-framework/utils/internal-error";
+import { blindCast } from "@prisma/orm-framework/utils/casts";
+import { ifDefined } from "@prisma/orm-framework/utils/defined";
+import { canonicalStringify } from "@prisma/orm-framework/utils/canonical-stringify";
+import { materializeCodec, resolveCodecDescriptorOrThrow } from "@prisma/orm-framework/components/codec";
+import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeError } from "@prisma/orm-framework/components/runtime";
+import { canonicalizeJson } from "@prisma/orm-framework/components/utils";
+import { checkContractComponentRequirements, mergeCapabilityMatrices } from "@prisma/orm-framework/components/components";
+import { createExecutionStack } from "@prisma/orm-framework/components/execution";
+import { hashContent } from "@prisma/orm-framework/utils/hash-content";
+//#region ../../../2-sql/5-runtime/dist/exports-DcRj136z.mjs
+/**
+* Build an {@link AstCodecResolver} bound to a descriptor registry and a per-call instance-context factory.
+*
+* The instance-context factory lets callers control `name` / `usedAt` for refs the AST supplies (e.g. AST-embedded migration ops where the materialisation site is the AST node, not a contract column). The contract-walk pre-population path constructs its own contexts and invokes the resolver with those refs to seed the cache.
+*/
+function createAstCodecResolver(descriptors, instanceContextFor) {
+	const cache = /* @__PURE__ */ new Map();
+	return { forCodecRef(ref) {
+		const key = `${ref.codecId}:${canonicalizeJson(ref.typeParams)}`;
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const codec = materializeCodec(resolveCodecDescriptorOrThrow((id) => descriptors.descriptorFor(id), ref, "RUNTIME.CODEC_DESCRIPTOR_MISSING"), ref, instanceContextFor(ref));
+		cache.set(key, codec);
+		return codec;
+	} };
+}
+/**
+* Build a contract-free {@link ContractCodecRegistry} that resolves codecs
+* purely from AST-supplied {@link import('@internal/framework-components/codec').CodecRef}s
+* against a target's descriptor registry.
+*
+* Dispatch is driven entirely by `CodecRef`s embedded in AST nodes; no
+* contract walk is needed. `forColumn` always returns `undefined` — this
+* registry carries no column-to-codec mappings.
+*/
+function createAstCodecRegistry(descriptors) {
+	const resolver = createAstCodecResolver(descriptors, (ref) => ({
+		name: ref.codecId,
+		usedAt: []
+	}));
+	return {
+		forColumn: () => void 0,
+		forCodecRef: (ref) => resolver.forCodecRef(ref)
+	};
+}
+const NO_METADATA = Object.freeze({
+	codec: void 0,
+	name: void 0
+});
+function deriveParamMetadata(ast) {
+	return collectOrderedParamRefs(ast).map((ref) => {
+		return {
+			codec: ref.codec,
+			name: ref.name
+		};
+	});
+}
+function resolveParamCodec(metadata, contractCodecs) {
+	if (metadata.codec && contractCodecs) return contractCodecs.forCodecRef(metadata.codec);
+}
+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;
+}
+async function encodeParamValue(value, metadata, paramIndex, ctx, contractCodecs) {
+	if (value === null || value === void 0) return null;
+	const codec = resolveParamCodec(metadata, contractCodecs);
+	if (!codec) return value;
+	if (metadata.codec?.many) {
+		if (!Array.isArray(value)) wrapEncodeFailure(/* @__PURE__ */ new TypeError(`expected an array for many-typed parameter, got ${typeof value}`), metadata, paramIndex, codec.id);
+		const encoded = [];
+		for (let i = 0; i < value.length; i++) {
+			const elem = value[i];
+			if (elem === null || elem === void 0) {
+				encoded.push(null);
+				continue;
+			}
+			try {
+				encoded.push(await codec.encode(elem, ctx));
+			} catch (error) {
+				if (isStructuredError(error)) throw error;
+				wrapEncodeFailure(error, metadata, paramIndex, codec.id);
+			}
+		}
+		return encoded;
+	}
+	try {
+		return await codec.encode(value, ctx);
+	} catch (error) {
+		if (isStructuredError(error)) throw error;
+		wrapEncodeFailure(error, metadata, paramIndex, codec.id);
+	}
+}
+/**
+* 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 structured envelopes (any dotted-code error passing `isStructuredError`, e.g. `RUNTIME.ENCODE_FAILED`) that surface from a codec body before the runtime observes the abort pass through unchanged (no double wrap).
+*/
+async function encodeParams(plan, ctx, contractCodecs) {
+	return encodeParamsWithMetadata(plan.params, deriveParamMetadata(plan.ast), ctx, contractCodecs);
+}
+async function encodeParamsWithMetadata(values, metadata, ctx, contractCodecs) {
+	checkAborted(ctx, "encode");
+	const signal = ctx.signal;
+	if (values.length === 0) return values;
+	const tasks = values.map((value, i) => encodeParamValue(value, metadata[i] ?? NO_METADATA, i, ctx, contractCodecs));
+	const settled = await raceAgainstAbort(Promise.all(tasks), signal, "encode");
+	return Object.freeze(settled);
+}
+function extractCodecIds(contract) {
+	const codecIds = /* @__PURE__ */ new Set();
+	for (const ns of Object.values(contract.storage.namespaces)) for (const table of Object.values(ns.entries.table ?? {})) for (const column of Object.values(table.columns)) {
+		const codecId = column.codecId;
+		codecIds.add(codecId);
+	}
+	return codecIds;
+}
+function extractColumnCodecRefs(contract) {
+	const refs = [];
+	for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) for (const [columnName, column] of Object.entries(table.columns)) refs.push({
+		namespaceId,
+		table: tableName,
+		column: columnName,
+		codecId: column.codecId
+	});
+	return refs;
+}
+function validateContractCodecMappings(registry, contract) {
+	const invalidCodecs = extractColumnCodecRefs(contract).filter((ref) => registry.descriptorFor(ref.codecId) === void 0);
+	if (invalidCodecs.length > 0) {
+		const details = {
+			contractTarget: contract.target,
+			invalidCodecs
+		};
+		throw runtimeError("RUNTIME.CODEC_MISSING", `Missing codec implementations for column codecIds: ${invalidCodecs.map((c) => `${c.namespaceId}.${c.table}.${c.column} (${c.codecId})`).join(", ")}`, details);
+	}
+}
+function validateCodecRegistryCompleteness(registry, contract) {
+	validateContractCodecMappings(registry, contract);
+}
+/**
+* Lowers a SQL query plan to an executable Plan by calling the adapter's lower method.
+*
+* Ad-hoc lowerings produce only `{kind: 'literal'}` slots; this helper
+* unwraps them into the bare-value array `SqlExecutionPlan` exposes.
+* Encountering a `{kind: 'bind'}` slot here means the caller passed an
+* AST containing `PreparedParamRef` to the ad-hoc execute path — that's a
+* caller error, surfaced as `RUNTIME.PREPARE_BIND_ON_ADHOC`.
+*/
+function lowerSqlPlan(adapter, contract, queryPlan) {
+	const lowered = adapter.lower(queryPlan.ast, {
+		contract,
+		params: queryPlan.params
+	});
+	const params = lowered.params.map((slot) => {
+		if (slot.kind === "literal") return slot.value;
+		throw runtimeError("RUNTIME.PREPARE_BIND_ON_ADHOC", `Ad-hoc execute received a bind-site slot for '${slot.name}' — bind-site references are only valid inside runtime.prepare(...).`, { name: slot.name });
+	});
+	return Object.freeze({
+		sql: lowered.sql,
+		params,
+		ast: queryPlan.ast,
+		meta: queryPlan.meta
+	});
+}
+function hasAggregateWithoutGroupBy(ast) {
+	if (ast.groupBy !== void 0) return false;
+	return ast.projection.some((item) => item.expr.kind === "aggregate");
+}
+function primaryTableFromAst(ast) {
+	if (ast.from === void 0) return void 0;
+	switch (ast.from.kind) {
+		case "table-source": return ast.from.name;
+		case "derived-table-source": return ast.from.alias;
+		case "function-source": return ast.from.fn;
+		// v8 ignore next 4
+		default: return assertNever(ast.from, `Unsupported source kind: ${ast.from.kind}`);
+	}
+}
+function estimateRowsFromAst(ast, tableRows, defaultTableRows, hasAggregateWithoutGroup) {
+	if (hasAggregateWithoutGroup) return 1;
+	const primaryTable = primaryTableFromAst(ast);
+	const tableEstimate = (primaryTable !== void 0 ? tableRows[primaryTable] : void 0) ?? defaultTableRows;
+	if (typeof ast.limit === "number") return Math.min(ast.limit, tableEstimate);
+	return tableEstimate;
+}
+function emitBudgetViolation(error, shouldBlock, ctx) {
+	if (shouldBlock) throw error;
+	ctx.log.warn({
+		code: error.code,
+		message: error.message,
+		details: error.details
+	});
+}
+function budgets(options) {
+	const maxRows = options?.maxRows ?? 1e4;
+	const defaultTableRows = options?.defaultTableRows ?? 1e4;
+	const tableRows = options?.tableRows ?? {};
+	const maxLatencyMs = options?.maxLatencyMs ?? 1e3;
+	const rowSeverity = options?.severities?.rowCount ?? "error";
+	const latencySeverity = options?.severities?.latency ?? "warn";
+	const observedRowsByPlan = /* @__PURE__ */ new WeakMap();
+	return Object.freeze({
+		name: "budgets",
+		familyId: "sql",
+		async beforeExecute(plan, ctx) {
+			observedRowsByPlan.set(plan, { count: 0 });
+			if (isQueryAst(plan.ast) && plan.ast.kind === "select") return evaluateSelectAst(plan.ast, ctx);
+		},
+		async onRow(_row, plan, _ctx) {
+			const state = observedRowsByPlan.get(plan);
+			if (!state) return;
+			state.count += 1;
+			if (state.count > maxRows) throw runtimeError("BUDGET.ROWS_EXCEEDED", "Observed row count exceeds budget", {
+				source: "observed",
+				observedRows: state.count,
+				maxRows
+			});
+		},
+		async afterExecute(_plan, result, ctx) {
+			const latencyMs = result.latencyMs;
+			if (latencyMs > maxLatencyMs) {
+				const shouldBlock = latencySeverity === "error" || ctx.mode === "strict";
+				emitBudgetViolation(runtimeError("BUDGET.TIME_EXCEEDED", "Query latency exceeds budget", {
+					latencyMs,
+					maxLatencyMs
+				}), shouldBlock, ctx);
+			}
+		}
+	});
+	function evaluateSelectAst(ast, ctx) {
+		const hasAggNoGroup = hasAggregateWithoutGroupBy(ast);
+		const estimated = estimateRowsFromAst(ast, tableRows, defaultTableRows, hasAggNoGroup);
+		const isUnbounded = ast.limit === void 0 && !hasAggNoGroup;
+		const shouldBlock = rowSeverity === "error" || ctx.mode === "strict";
+		if (isUnbounded) {
+			emitBudgetViolation(runtimeError("BUDGET.ROWS_EXCEEDED", "Unbounded SELECT query exceeds budget", estimated >= maxRows ? {
+				source: "ast",
+				estimatedRows: estimated,
+				maxRows
+			} : {
+				source: "ast",
+				maxRows
+			}), shouldBlock, ctx);
+			return;
+		}
+		if (estimated > maxRows) emitBudgetViolation(runtimeError("BUDGET.ROWS_EXCEEDED", "Estimated row count exceeds budget", {
+			source: "ast",
+			estimatedRows: estimated,
+			maxRows
+		}), shouldBlock, ctx);
+	}
+}
+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 = /* @__PURE__ */ new Set([
+	"read",
+	"report",
+	"readonly"
+]);
+function evaluateRawGuardrails(plan, config) {
+	const lints = [];
+	const budgets = [];
+	const normalized = normalizeWhitespace(plan.sql);
+	const statementType = classifyStatement(normalized);
+	if (statementType === "select") {
+		if (SELECT_STAR_REGEX.test(normalized)) lints.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.push(createLint("LINT.NO_LIMIT", "warn", "Raw SQL plan omits LIMIT clause", { sql: snippet(plan.sql) }));
+			budgets.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.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,
+		budgets,
+		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 } : {}
+	};
+}
+function getFromSourceTableDetail(source) {
+	switch (source.kind) {
+		case "table-source": return source.name;
+		case "derived-table-source": return source.alias;
+		case "function-source": return source.fn;
+		// v8 ignore next 4
+		default: return assertNever(source, `Unsupported source kind: ${source.kind}`);
+	}
+}
+function evaluateAstLints(ast) {
+	const findings = [];
+	switch (ast.kind) {
+		case "delete":
+			if (ast.where === void 0) findings.push({
+				code: "LINT.DELETE_WITHOUT_WHERE",
+				severity: "error",
+				message: "DELETE without WHERE clause blocks execution to prevent accidental full-table deletion",
+				details: { table: ast.table.name }
+			});
+			break;
+		case "update":
+			if (ast.where === void 0) findings.push({
+				code: "LINT.UPDATE_WITHOUT_WHERE",
+				severity: "error",
+				message: "UPDATE without WHERE clause blocks execution to prevent accidental full-table update",
+				details: { table: ast.table.name }
+			});
+			break;
+		case "select":
+			if (ast.limit === void 0) {
+				const table = ast.from !== void 0 ? getFromSourceTableDetail(ast.from) : void 0;
+				findings.push({
+					code: "LINT.NO_LIMIT",
+					severity: "warn",
+					message: "Unbounded SELECT may return large result sets",
+					...ifDefined("details", table !== void 0 ? { table } : void 0)
+				});
+			}
+			if (ast.selectAllIntent !== void 0) {
+				const table = ast.selectAllIntent.table;
+				findings.push({
+					code: "LINT.SELECT_STAR",
+					severity: "warn",
+					message: "Query selects all columns via selectAll intent",
+					...ifDefined("details", table !== void 0 ? { table } : void 0)
+				});
+			}
+			break;
+		case "insert": break;
+		case "raw-sql": break;
+		// v8 ignore next 2
+		default: assertNever(ast, `Unsupported AST kind: ${ast.kind}`);
+	}
+	return findings;
+}
+function getConfiguredSeverity(code, options) {
+	const severities = options?.severities;
+	if (!severities) return void 0;
+	switch (code) {
+		case "LINT.SELECT_STAR": return severities.selectStar;
+		case "LINT.NO_LIMIT": return severities.noLimit;
+		case "LINT.DELETE_WITHOUT_WHERE": return severities.deleteWithoutWhere;
+		case "LINT.UPDATE_WITHOUT_WHERE": return severities.updateWithoutWhere;
+		case "LINT.READ_ONLY_MUTATION": return severities.readOnlyMutation;
+		default: return;
+	}
+}
+/**
+* AST-first lint middleware for SQL plans. When `plan.ast` is a SQL QueryAst, inspects
+* the AST structurally. When `plan.ast` is missing, falls back to raw heuristic
+* guardrails or skips linting depending on `fallbackWhenAstMissing`.
+*
+* Rules (AST-based):
+* - DELETE without WHERE: blocks execution (configurable severity, default error)
+* - UPDATE without WHERE: blocks execution (configurable severity, default error)
+* - Unbounded SELECT: warn/error (severity from noLimit)
+* - SELECT * intent: warn/error (severity from selectStar)
+*
+* Fallback: When ast is missing, `fallbackWhenAstMissing: 'raw'` uses heuristic
+* SQL parsing; `'skip'` skips all lints. Default is `'raw'`.
+*/
+function lints(options) {
+	const fallback = options?.fallbackWhenAstMissing ?? "raw";
+	return Object.freeze({
+		name: "lints",
+		familyId: "sql",
+		async beforeExecute(plan, ctx) {
+			const findings = [];
+			if (isQueryAst(plan.ast)) {
+				findings.push(...evaluateAstLints(plan.ast));
+				if (plan.ast.kind === "raw-sql") findings.push(...evaluateRawGuardrails(plan).lints);
+			} else if (fallback !== "skip") findings.push(...evaluateRawGuardrails(plan).lints);
+			for (const lint of findings) {
+				const effectiveSeverity = getConfiguredSeverity(lint.code, options) ?? lint.severity;
+				if (effectiveSeverity === "error") throw runtimeError(lint.code, lint.message, lint.details);
+				if (effectiveSeverity === "warn") ctx.log.warn({
+					code: lint.code,
+					message: lint.message,
+					details: lint.details
+				});
+			}
+		}
+	});
+}
+var PreparedStatementImpl = class {
+	sql;
+	ast;
+	meta;
+	slots;
+	decodeContext;
+	paramMetadata;
+	constructor(internals) {
+		this.sql = internals.sql;
+		this.ast = internals.ast;
+		this.meta = internals.meta;
+		this.slots = internals.slots;
+		this.decodeContext = internals.decodeContext;
+		this.paramMetadata = internals.paramMetadata;
+		Object.freeze(this);
+	}
+	execute(target, params, options) {
+		return target.executePrepared(this, params, options);
+	}
+};
+function documentScopedCodecTypes(contract) {
+	return blindCast(contract.storage.types);
+}
+function createSqlExecutionStack(options) {
+	return createExecutionStack({
+		target: options.target,
+		adapter: options.adapter,
+		driver: options.driver,
+		extensions: options.extensions
+	});
+}
+function assertExecutionStackContractRequirements(contract, stack) {
+	const providedComponentIds = /* @__PURE__ */ new Set([
+		stack.target.id,
+		stack.adapter.id,
+		...stack.extensions.map((pack) => pack.id)
+	]);
+	const result = checkContractComponentRequirements({
+		contract,
+		expectedTargetFamily: "sql",
+		expectedTargetId: stack.target.targetId,
+		providedComponentIds
+	});
+	if (result.familyMismatch) throw runtimeError("RUNTIME.CONTRACT_FAMILY_MISMATCH", `Contract target family '${result.familyMismatch.actual}' does not match runtime family '${result.familyMismatch.expected}'.`, {
+		actual: result.familyMismatch.actual,
+		expected: result.familyMismatch.expected
+	});
+	if (result.targetMismatch) throw runtimeError("RUNTIME.CONTRACT_TARGET_MISMATCH", `Contract target '${result.targetMismatch.actual}' does not match runtime target descriptor '${result.targetMismatch.expected}'.`, {
+		actual: result.targetMismatch.actual,
+		expected: result.targetMismatch.expected
+	});
+	if (result.missingExtensionPackIds.length > 0) {
+		const packIds = result.missingExtensionPackIds;
+		throw runtimeError("RUNTIME.MISSING_EXTENSION_PACK", `Contract requires extension pack(s) ${packIds.map((id) => `'${id}'`).join(", ")}, but runtime descriptors do not provide matching component(s).`, { packIds });
+	}
+}
+function validateTypeParams(typeParams, descriptor, context) {
+	const result = descriptor.paramsSchema["~standard"].validate(typeParams);
+	if (result instanceof Promise) throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `paramsSchema for codec '${descriptor.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`, {
+		...context,
+		codecId: descriptor.codecId,
+		typeParams
+	});
+	if (result.issues) {
+		const messages = result.issues.map((issue) => issue.message).join("; ");
+		throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `Invalid typeParams for ${context.typeName ? `type '${context.typeName}'` : `column '${context.tableName}.${context.columnName}'`} (codecId: ${descriptor.codecId}): ${messages}`, {
+			...context,
+			codecId: descriptor.codecId,
+			typeParams
+		});
+	}
+	return result.value;
+}
+/**
+* Collect every {@link CodecDescriptor} contributed by the SQL stack and partition into "parameterized" vs "non-parameterized" via the descriptor's own {@link CodecDescriptorImpl.isParameterized} getter. The getter is the canonical discriminator — a `paramsSchema` identity check would misroute any descriptor that doesn't reuse the exact `voidParamsSchema` singleton (e.g. a non-parameterized codec authoring its own no-op schema).
+*
+* The unified descriptor list collapses the legacy split (a separate slot used to register parameterized codecs) — every codec id resolves through the same map (codec-registry-unification spec § Decision).
+*/
+function collectCodecDescriptors(contributors) {
+	const all = [];
+	const parameterized = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	for (const contributor of contributors) for (const descriptor of contributor.codecs()) {
+		if (seen.has(descriptor.codecId)) throw runtimeError("RUNTIME.DUPLICATE_CODEC", `Duplicate codec descriptor for codecId '${descriptor.codecId}'.`, { codecId: descriptor.codecId });
+		seen.add(descriptor.codecId);
+		all.push(descriptor);
+		if (descriptor.isParameterized) parameterized.set(descriptor.codecId, descriptor);
+	}
+	return {
+		all,
+		parameterized
+	};
+}
+function collectTypeRefSites(storage) {
+	const sites = /* @__PURE__ */ new Map();
+	for (const ns of Object.values(storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) for (const [columnName, column] of Object.entries(table.columns)) {
+		if (typeof column.typeRef !== "string") continue;
+		const list = sites.get(column.typeRef);
+		const entry = {
+			table: tableName,
+			column: columnName
+		};
+		if (list) list.push(entry);
+		else sites.set(column.typeRef, [entry]);
+	}
+	return sites;
+}
+function initializeTypeHelpers(storage, documentTypes, codecDescriptors) {
+	const helpers = {};
+	if (!documentTypes) return helpers;
+	const typeRefSites = collectTypeRefSites(storage);
+	for (const [typeName, typeInstance] of Object.entries(documentTypes)) {
+		const codecId = typeInstance.codecId;
+		const typeParams = typeInstance.typeParams;
+		const descriptor = codecDescriptors.get(codecId);
+		if (!descriptor) {
+			helpers[typeName] = typeInstance;
+			continue;
+		}
+		const validatedParams = validateTypeParams(typeParams ?? {}, descriptor, { typeName });
+		const ctx = {
+			name: typeName,
+			usedAt: typeRefSites.get(typeName) ?? []
+		};
+		helpers[typeName] = descriptor.factory(validatedParams)(ctx);
+	}
+	return helpers;
+}
+function validateColumnTypeParams(storage, codecDescriptors) {
+	for (const ns of Object.values(storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) for (const [columnName, column] of Object.entries(table.columns)) if (column.typeParams) {
+		const descriptor = codecDescriptors.get(column.codecId);
+		if (descriptor) validateTypeParams(column.typeParams, descriptor, {
+			tableName,
+			columnName
+		});
+	}
+}
+/**
+* Build-time contract-integrity check: every `(table, column)` resolves to a {@link CodecRef} whose `codecId` is registered and whose `typeParams` presence matches the descriptor's `isParameterized` flag.
+*
+* Surfaces three classes of malformed contract that AST-bound codec resolution would otherwise mask silently:
+*
+* - column references a codecId no contributor registered → `RUNTIME.CODEC_DESCRIPTOR_MISSING`.
+* - parameterized codec, no `typeParams` (legacy "tolerate refs without params" shape) → `RUNTIME.CODEC_PARAMETERIZATION_MISMATCH`.
+* - non-parameterized codec, `typeParams` supplied → `RUNTIME.CODEC_PARAMETERIZATION_MISMATCH`.
+*
+* Runs unconditionally from `createExecutionContext` so contract bugs fail fast at construction time instead of silently skipping affected columns in the codec registry's pre-population walk.
+*/
+function assertColumnCodecIntegrity(storage, codecDescriptors) {
+	for (const [namespaceId, ns] of Object.entries(storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) for (const columnName of Object.keys(table.columns)) {
+		const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
+		if (!ref) continue;
+		const descriptor = codecDescriptors.descriptorFor(ref.codecId);
+		if (!descriptor) throw runtimeError("RUNTIME.CODEC_DESCRIPTOR_MISSING", `Column '${tableName}.${columnName}' references codec '${ref.codecId}' but no contributor registered a codec descriptor for that codecId. Add the extension pack that owns the codec to the runtime stack.`, {
+			table: tableName,
+			column: columnName,
+			codecId: ref.codecId
+		});
+		if (descriptor.isParameterized && ref.typeParams === void 0) {
+			const probe = descriptor.paramsSchema["~standard"].validate({});
+			if (probe instanceof Promise) {
+				probe.catch(() => {});
+				throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `Column '${tableName}.${columnName}' uses parameterized codec '${ref.codecId}' whose paramsSchema returned a Promise; paramsSchema must be a synchronous Standard Schema validator. Return a value/issues result directly instead of a Promise.`, {
+					table: tableName,
+					column: columnName,
+					codecId: ref.codecId
+				});
+			}
+			if ("issues" in probe && !!probe.issues) throw runtimeError("RUNTIME.CODEC_PARAMETERIZATION_MISMATCH", `Column '${tableName}.${columnName}' uses parameterized codec '${ref.codecId}' but no typeParams are supplied. Provide typeParams on the column, or use a typeRef pointing at a storage.types entry that carries them.`, {
+				table: tableName,
+				column: columnName,
+				codecId: ref.codecId,
+				expected: "parameterized",
+				actual: "no typeParams"
+			});
+		}
+		const refTypeParams = ref.typeParams;
+		const refHasTypeParamKeys = refTypeParams !== void 0 && refTypeParams !== null && typeof refTypeParams === "object" && !Array.isArray(refTypeParams) && Object.keys(refTypeParams).length > 0;
+		if (!descriptor.isParameterized && refHasTypeParamKeys) throw runtimeError("RUNTIME.CODEC_PARAMETERIZATION_MISMATCH", `Column '${tableName}.${columnName}' supplies typeParams to non-parameterized codec '${ref.codecId}'. Remove the typeParams or switch to a parameterized codec id.`, {
+			table: tableName,
+			column: columnName,
+			codecId: ref.codecId,
+			expected: "non-parameterized",
+			actual: "has typeParams"
+		});
+	}
+}
+/**
+* Build a {@link ContractCodecRegistry} that resolves codecs exclusively through the `forCodecRef` content-keyed cache.
+*
+* One pre-population pass walks `storage.types` and `storage.tables[].columns[]` to seed the resolver's per-ref instance context with the *aggregated* `usedAt` set for each canonical `(codecId, typeParams)` key. The same codec materialised through `forColumn` or `forCodecRef` is therefore one instance with one `SqlCodecInstanceContext` — stateful codecs reading `usedAt` see the full column set regardless of which surface the caller used.
+*
+* Per-key instance-name policy:
+*
+* - typeRef-shared columns use the `storage.types[name]` name.
+* - inline-`typeParams` columns use `<col:Table.column>` (the first column observed at that key; additional columns sharing the key extend `usedAt`).
+* - non-parameterized codec ids use `<codec:codecId>`, aggregating every column on that codec id into one `usedAt` set.
+* - ad-hoc refs the contract walk did not pre-populate (e.g. AST-supplied refs from deserialised migration ops) fall back to the canonical cache key `${codecId}:${canonicalizeJson(typeParams)}` — the only structurally honest identity for an ad-hoc ref, distinct per `(codecId, typeParams)`.
+*
+* Contract integrity is enforced upstream by {@link assertColumnCodecIntegrity}: every column must reference a registered `codecId` whose `descriptor.isParameterized` flag matches the presence of `typeParams` (via `codecRefForColumn`). The pre-population walk and `forColumn` therefore make no defensive checks — malformed columns fail fast at `createExecutionContext` construction with `RUNTIME.CODEC_DESCRIPTOR_MISSING` or `RUNTIME.CODEC_PARAMETERIZATION_MISMATCH` rather than being silently skipped here.
+*
+* `forColumn(ns, t, c)` is a thin delegate over `forCodecRef(codecRefForColumn(ns, t, c))`; encode/decode hot paths read the resolver directly via `forCodecRef`. The only `undefined` `forColumn` returns is the legitimate "no such column in the contract" case.
+*/
+function buildContractCodecRegistry(contract, codecDescriptors) {
+	const refKeyOf = (ref) => `${ref.codecId}:${canonicalizeJson(ref.typeParams)}`;
+	const usedAtByKey = /* @__PURE__ */ new Map();
+	const nameByKey = /* @__PURE__ */ new Map();
+	const typeRefSites = collectTypeRefSites(contract.storage);
+	for (const [typeName, typeInstance] of Object.entries(documentScopedCodecTypes(contract) ?? {})) {
+		const instanceTypeParams = typeInstance.typeParams;
+		const key = refKeyOf(instanceTypeParams !== void 0 && Object.keys(instanceTypeParams).length > 0 ? {
+			codecId: typeInstance.codecId,
+			typeParams: instanceTypeParams
+		} : { codecId: typeInstance.codecId });
+		const sites = typeRefSites.get(typeName) ?? [];
+		const existing = usedAtByKey.get(key);
+		if (existing) existing.push(...sites);
+		else {
+			usedAtByKey.set(key, [...sites]);
+			nameByKey.set(key, typeName);
+		}
+	}
+	for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) for (const [columnName, column] of Object.entries(table.columns)) {
+		if (column.typeRef !== void 0) continue;
+		const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
+		if (!ref) continue;
+		const key = refKeyOf(ref);
+		const site = {
+			table: tableName,
+			column: columnName
+		};
+		const existing = usedAtByKey.get(key);
+		if (existing) existing.push(site);
+		else {
+			usedAtByKey.set(key, [site]);
+			const name = ref.typeParams !== void 0 ? `<col:${tableName}.${columnName}>` : `<codec:${ref.codecId}>`;
+			nameByKey.set(key, name);
+		}
+	}
+	const resolver = createAstCodecResolver(codecDescriptors, (ref) => {
+		const key = refKeyOf(ref);
+		return {
+			name: nameByKey.get(key) ?? key,
+			usedAt: usedAtByKey.get(key) ?? []
+		};
+	});
+	for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) for (const columnName of Object.keys(table.columns)) {
+		const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
+		if (!ref) continue;
+		resolver.forCodecRef(ref);
+	}
+	return {
+		forColumn(namespaceId, table, column) {
+			const ref = codecDescriptors.codecRefForColumn(namespaceId, table, column);
+			return ref ? resolver.forCodecRef(ref) : void 0;
+		},
+		forCodecRef(ref) {
+			return resolver.forCodecRef(ref);
+		}
+	};
+}
+function assertMutationDefaultGeneratorsAvailable(contract, generatorRegistry) {
+	const defaults = contract.execution?.mutations.defaults ?? [];
+	if (defaults.length === 0) return;
+	const missing = /* @__PURE__ */ new Set();
+	for (const mutationDefault of defaults) for (const phase of [mutationDefault.onCreate, mutationDefault.onUpdate]) {
+		if (!phase) continue;
+		if (phase.kind === "generator" && !generatorRegistry.has(phase.id)) missing.add(phase.id);
+	}
+	if (missing.size === 0) return;
+	const ids = Array.from(missing);
+	throw runtimeError("RUNTIME.MUTATION_DEFAULT_GENERATOR_MISSING", `Contract requires mutation default generator(s) ${ids.map((id) => `'${id}'`).join(", ")}, but no runtime component provides them.`, { ids });
+}
+function collectMutationDefaultGenerators(contributors) {
+	const generators = /* @__PURE__ */ new Map();
+	const owners = /* @__PURE__ */ new Map();
+	for (const contributor of contributors) {
+		const nextGenerators = contributor.mutationDefaultGenerators?.() ?? [];
+		for (const generator of nextGenerators) {
+			const existingOwner = owners.get(generator.id);
+			if (existingOwner !== void 0) throw runtimeError("RUNTIME.DUPLICATE_MUTATION_DEFAULT_GENERATOR", `Duplicate mutation default generator '${generator.id}'.`, {
+				id: generator.id,
+				existingOwner,
+				incomingOwner: contributor.id
+			});
+			generators.set(generator.id, generator);
+			owners.set(generator.id, contributor.id);
+		}
+	}
+	return generators;
+}
+function computeExecutionDefaultValue(spec, generatorRegistry) {
+	switch (spec.kind) {
+		case "generator": {
+			const generator = generatorRegistry.get(spec.id);
+			if (!generator) throw runtimeError("RUNTIME.MUTATION_DEFAULT_GENERATOR_MISSING", `Contract references mutation default generator '${spec.id}' but no runtime component provides it.`, { id: spec.id });
+			return generator.generate(spec.params);
+		}
+	}
+}
+function applyMutationDefaults(contract, generatorRegistry, options) {
+	const defaults = contract.execution?.mutations.defaults ?? [];
+	if (defaults.length === 0) return [];
+	const isEmptyUpdate = options.op === "update" && Object.keys(options.values).length === 0;
+	const applied = [];
+	const appliedColumns = /* @__PURE__ */ new Set();
+	const rowCache = /* @__PURE__ */ new Map();
+	for (const mutationDefault of defaults) {
+		if (mutationDefault.ref.table !== options.table) continue;
+		if (mutationDefault.ref.namespace !== options.namespace) continue;
+		const defaultSpec = options.op === "create" ? mutationDefault.onCreate : mutationDefault.onUpdate;
+		if (!defaultSpec) continue;
+		if (isEmptyUpdate) continue;
+		const columnName = mutationDefault.ref.column;
+		if (Object.hasOwn(options.values, columnName) || appliedColumns.has(columnName)) continue;
+		applied.push({
+			column: columnName,
+			value: resolveScopedValue(defaultSpec, generatorRegistry, rowCache, options.defaultValueCache)
+		});
+		appliedColumns.add(columnName);
+	}
+	return applied;
+}
+function resolveScopedValue(spec, generatorRegistry, rowCache, queryCache) {
+	if (spec.kind !== "generator") return computeExecutionDefaultValue(spec, generatorRegistry);
+	const cache = scopedCache(generatorRegistry.get(spec.id)?.stability, rowCache, queryCache);
+	if (!cache) return computeExecutionDefaultValue(spec, generatorRegistry);
+	if (cache.has(spec.id)) return cache.get(spec.id);
+	const value = computeExecutionDefaultValue(spec, generatorRegistry);
+	cache.set(spec.id, value);
+	return value;
+}
+function scopedCache(stability, rowCache, queryCache) {
+	switch (stability) {
+		case "row": return rowCache;
+		case "query": return queryCache;
+		default: return;
+	}
+}
+function createExecutionContext(options) {
+	const { stack, driver } = options;
+	assertExecutionStackContractRequirements(options.contract, stack);
+	const capabilityContributors = [
+		stack.target,
+		stack.adapter,
+		...driver ? [driver] : [],
+		...stack.extensions
+	];
+	const mergedCapabilities = mergeCapabilityMatrices(options.contract.capabilities, capabilityContributors);
+	const contract = {
+		...options.contract,
+		capabilities: mergedCapabilities
+	};
+	const contributors = [
+		stack.target,
+		stack.adapter,
+		...stack.extensions
+	];
+	const { all: allCodecDescriptors, parameterized: parameterizedCodecDescriptors } = collectCodecDescriptors(contributors);
+	const queryOperationRegistry = createSqlOperationRegistry();
+	for (const contributor of contributors) {
+		const ops = contributor.queryOperations?.() ?? {};
+		for (const [name, op] of Object.entries(ops)) queryOperationRegistry.register(name, op);
+	}
+	const codecDescriptors = buildCodecDescriptorRegistry(allCodecDescriptors, contract.storage);
+	assertColumnCodecIntegrity(contract.storage, codecDescriptors);
+	const mutationDefaultGeneratorRegistry = collectMutationDefaultGenerators(contributors);
+	assertMutationDefaultGeneratorsAvailable(contract, mutationDefaultGeneratorRegistry);
+	if (parameterizedCodecDescriptors.size > 0) validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
+	const types = initializeTypeHelpers(contract.storage, documentScopedCodecTypes(contract), parameterizedCodecDescriptors);
+	return {
+		contract,
+		contractCodecs: buildContractCodecRegistry(contract, codecDescriptors),
+		codecDescriptors,
+		queryOperations: queryOperationRegistry,
+		types,
+		applyMutationDefaults: (options) => applyMutationDefaults(contract, mutationDefaultGeneratorRegistry, options)
+	};
+}
+const WIRE_PREVIEW_LIMIT = 100;
+const EMPTY_INCLUDE_ALIASES = /* @__PURE__ */ new Set();
+function projectionListFromAst(ast) {
+	if (ast.kind === "select") return ast.projection;
+	if (ast.kind === "raw-sql") return;
+	return ast.returning;
+}
+function resolveProjectionCodec(item, contractCodecs) {
+	if (item.codec && contractCodecs) return contractCodecs.forCodecRef(item.codec);
+}
+const EMPTY_MANY_ALIASES = /* @__PURE__ */ new Set();
+function buildDecodeContext(ast, contractCodecs) {
+	const projection = projectionListFromAst(ast);
+	if (!projection || projection.length === 0) return {
+		aliases: void 0,
+		codecs: /* @__PURE__ */ new Map(),
+		columnRefs: /* @__PURE__ */ new Map(),
+		includeAliases: EMPTY_INCLUDE_ALIASES,
+		manyAliases: EMPTY_MANY_ALIASES
+	};
+	const aliases = [];
+	const codecs = /* @__PURE__ */ new Map();
+	const columnRefs = /* @__PURE__ */ new Map();
+	const includeAliases = /* @__PURE__ */ new Set();
+	const manyAliases = /* @__PURE__ */ new Set();
+	for (const item of projection) {
+		aliases.push(item.alias);
+		const codec = resolveProjectionCodec(item, contractCodecs);
+		if (codec) codecs.set(item.alias, codec);
+		if (item.codec?.many) manyAliases.add(item.alias);
+		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,
+		manyAliases
+	};
+}
+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 wrapDecodeFailure(error, alias, ref, codec, 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.id}': ${message}`, {
+		...ref ? {
+			table: ref.table,
+			column: ref.column
+		} : { alias },
+		codec: codec.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 {
+		if (typeof wireValue === "string") return JSON.parse(wireValue);
+		if (typeof wireValue === "object") return wireValue;
+		return JSON.parse(String(wireValue));
+	} catch (error) {
+		wrapIncludeAggregateFailure(error, alias, wireValue);
+	}
+}
+/**
+* Decodes a single field. Single-armed: every cell takes the same path — `codec.decode → await → return plain value` — so sync- and async-authored codecs are indistinguishable to callers. JSON-Schema validation, when required, lives inside the resolved codec's `decode` body (e.g. `arktype-json` validates against its rehydrated schema and throws `RUNTIME.JSON_SCHEMA_VALIDATION_FAILED` from `decode` directly); there is
+* no separate validator-registry pass.
+*
+* 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.
+*
+* For `many`-flagged aliases the driver has already parsed the wire form into a JS array; this function maps the element codec over that array element-by-element, passing `null` elements through unchanged. Element-level failures surface through the existing `RUNTIME.DECODE_FAILED` envelope with the column/codec context from the parent cell.
+*/
+async function decodeField(alias, wireValue, decodeCtx, rowCtx) {
+	if (wireValue === null) return null;
+	const codec = decodeCtx.codecs.get(alias);
+	if (!codec) return wireValue;
+	const ref = decodeCtx.columnRefs.get(alias);
+	let cellCtx;
+	if (ref) cellCtx = {
+		...rowCtx,
+		column: {
+			table: ref.table,
+			name: ref.column
+		}
+	};
+	else {
+		const { column: _drop, ...rowCtxWithoutColumn } = rowCtx;
+		cellCtx = rowCtxWithoutColumn;
+	}
+	if (decodeCtx.manyAliases.has(alias)) {
+		if (!Array.isArray(wireValue)) wrapDecodeFailure(/* @__PURE__ */ new TypeError(`expected an array from the driver for many-typed column, got ${typeof wireValue}`), alias, ref, codec, wireValue);
+		const decoded = [];
+		for (const elem of wireValue) {
+			if (elem === null || elem === void 0) {
+				decoded.push(null);
+				continue;
+			}
+			try {
+				decoded.push(await codec.decode(elem, cellCtx));
+			} catch (error) {
+				if (isStructuredError(error)) throw error;
+				wrapDecodeFailure(error, alias, ref, codec, elem);
+			}
+		}
+		return decoded;
+	}
+	try {
+		return await codec.decode(wireValue, cellCtx);
+	} catch (error) {
+		if (isStructuredError(error)) throw error;
+		wrapDecodeFailure(error, alias, ref, codec, wireValue);
+	}
+}
+/**
+* Decodes a row by dispatching all per-cell codec calls concurrently via `Promise.all`. Each cell follows the single-armed `decodeField` path. Structured envelopes thrown by codec bodies (anything passing `isStructuredError`) pass through unchanged; all other 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 structured envelopes (any dotted-code error passing `isStructuredError`, e.g. `RUNTIME.DECODE_FAILED`) from codec bodies pass through unchanged (no double wrap).
+*/
+async function decodeRow(row, decodeCtx, rowCtx) {
+	checkAborted(rowCtx, "decode");
+	const signal = rowCtx.signal;
+	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];
+		if (decodeCtx.includeAliases.has(alias)) {
+			includeIndices.push({
+				index: i,
+				alias,
+				value: wireValue
+			});
+			tasks.push(Promise.resolve(void 0));
+			continue;
+		}
+		tasks.push(decodeField(alias, wireValue, decodeCtx, 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;
+}
+/**
+* Computes a stable content hash for a lowered SQL execution plan.
+*
+* Internally builds an unambiguous canonical-stringified preimage from
+* three components:
+*
+* 1. `meta.storageHash` — discriminates by schema. A migration changes the
+*    storage hash, which invalidates cached entries automatically.
+* 2. `exec.sql` — the raw lowered SQL text. Two queries with different
+*    structure produce different keys. Note that we deliberately do **not**
+*    use `computeSqlFingerprint` here: that helper strips literals to group
+*    executions by statement shape (used by telemetry), which is the
+*    opposite of what a content hash needs — we want per-execution
+*    discrimination, not per-statement-shape grouping.
+* 3. `exec.params` — the bound parameters. `canonicalStringify` produces a
+*    deterministic serialization that is stable across object key
+*    insertion order and that distinguishes types JSON would otherwise
+*    conflate (e.g. `BigInt(1)` vs `1`).
+*
+* The components are wrapped in an object and canonicalized as a single
+* unit (rather than concatenated with a delimiter) so component
+* boundaries are unambiguous: any character appearing inside `sql` or
+* `storageHash` cannot bleed across components and produce a collision
+* with a different split of the same characters.
+*
+* The canonical string is then piped through `hashContent` to produce a
+* bounded, opaque digest. See `@internal/utils/hash-content` for the
+* rationale.
+*
+* @internal
+*/
+function computeSqlContentHash(exec) {
+	return hashContent(canonicalStringify({
+		storageHash: exec.meta.storageHash,
+		sql: exec.sql,
+		params: exec.params
+	}));
+}
+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 createHash("sha256").update(normalized).digest("hex");
+}
+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;
+	}
+	return current;
+}
+function normalizeSpec(spec) {
+	if (typeof spec === "string") return {
+		codec: { codecId: spec },
+		nullable: false
+	};
+	return {
+		codec: spec.typeParams !== void 0 ? {
+			codecId: spec.codecId,
+			typeParams: spec.typeParams
+		} : { codecId: spec.codecId },
+		nullable: spec.nullable === true
+	};
+}
+var BindSiteExpression = class {
+	returnType;
+	#ast;
+	constructor(ref, returnType) {
+		this.#ast = ref;
+		this.returnType = returnType;
+	}
+	buildAst() {
+		return this.#ast;
+	}
+};
+function buildBindSiteParams(declaration) {
+	const params = {};
+	for (const [name, spec] of Object.entries(declaration)) {
+		const { codec, nullable } = normalizeSpec(spec);
+		params[name] = new BindSiteExpression(PreparedParamRef.of(name, codec), {
+			codecId: codec.codecId,
+			nullable
+		});
+	}
+	return Object.freeze(params);
+}
+/**
+* Resolve a PreparedStatement's slot order to the unencoded values it
+* will carry into encode. Literal slots come from the lowered AST;
+* bind slots are looked up by name on `userParams`. Missing user params
+* surface `RUNTIME.PREPARE_MISSING_PARAM` so the caller cannot silently
+* bind `undefined`.
+*/
+function resolvePreparedSlotValues(ps, userParams) {
+	return ps.slots.map((slot) => {
+		if (slot.kind === "literal") return slot.value;
+		if (!Object.hasOwn(userParams, slot.name)) throw runtimeError("RUNTIME.PREPARE_MISSING_PARAM", `Prepared statement execute is missing parameter '${slot.name}'`, { name: slot.name });
+		return userParams[slot.name];
+	});
+}
+var SqlFamilyAdapter = class {
+	contract;
+	markerReader;
+	constructor(contract, adapterProfile) {
+		this.contract = contract;
+		this.markerReader = adapterProfile;
+	}
+	validatePlan(plan, contract) {
+		if (plan.meta.target !== contract.target) throw runtimeError("PLAN.TARGET_MISMATCH", "Plan target does not match runtime target", {
+			planTarget: plan.meta.target,
+			runtimeTarget: contract.target
+		});
+		if (plan.meta.storageHash !== contract.storage.storageHash) throw runtimeError("PLAN.HASH_MISMATCH", "Plan storage hash does not match runtime contract", {
+			planStorageHash: plan.meta.storageHash,
+			runtimeStorageHash: contract.storage.storageHash
+		});
+	}
+};
+function isExecutionPlan(plan) {
+	return "sql" in plan;
+}
+// v8 ignore next 2
+const noopLogSink = () => {};
+const noopLog = {
+	info: noopLogSink,
+	warn: noopLogSink,
+	error: noopLogSink
+};
+/**
+* Abstract family-layer base for SQL runtimes. Subclass to build a target runtime
+* (e.g. `PostgresRuntimeImpl`); app code should consume the `Runtime` interface returned
+* by the target factories, never this class directly.
+*/
+var SqlRuntimeBase = class extends RuntimeCore {
+	contract;
+	adapter;
+	driver;
+	familyAdapter;
+	contractCodecs;
+	codecDescriptors;
+	sqlCtx;
+	verifyMarkerOption;
+	verifyMarkerPromise;
+	#preparedStatementHandles = /* @__PURE__ */ new WeakMap();
+	codecRegistryValidated;
+	_telemetry;
+	constructor(options) {
+		const { context, adapter, driver, verifyMarker, 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 ?? noopLog,
+			contentHash: (exec) => computeSqlContentHash(exec),
+			scope: "runtime",
+			planExecutionId: ""
+		};
+		super({
+			middleware: middleware ?? [],
+			ctx: sqlCtx
+		});
+		this.contract = context.contract;
+		this.adapter = adapter;
+		this.driver = driver;
+		this.familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
+		this.contractCodecs = context.contractCodecs;
+		this.codecDescriptors = context.codecDescriptors;
+		this.sqlCtx = sqlCtx;
+		this.verifyMarkerOption = verifyMarker ?? "onFirstUse";
+		this.codecRegistryValidated = false;
+		this.verifyMarkerPromise = this.verifyMarkerOption === false ? Promise.resolve() : null;
+		this._telemetry = null;
+	}
+	/**
+	* Lower a `SqlQueryPlan` (AST + meta) into a `SqlExecutionPlan`
+	* with encoded parameters ready for the driver.
+	*
+	* Implementation note: SQL splits lower-then-encode across
+	* {@link lowerToDraft} + {@link encodeDraftParams} so the runtime
+	* can fire the `beforeExecute` middleware chain between them
+	* (cipherstash bulk-encrypt, for example, mutates pre-encode
+	* `ParamRef.value` slots). This protected hook composes the two
+	* back into the cross-family `lower()` shape `RuntimeCore.execute`
+	* expects, and is called from the no-middleware fast paths /
+	* fixtures that hit `RuntimeCore`'s default template directly.
+	* `execute()` overrides the template and uses the split form so
+	* `beforeExecute` lands between the two halves.
+	*
+	* `ctx: SqlCodecCallContext` is forwarded to `encodeParams` so
+	* per-query cancellation reaches every codec body during parameter
+	* encoding. SQL params do not populate `ctx.column` — encode-side
+	* column metadata is the middleware's domain.
+	*/
+	async lower(plan, ctx) {
+		const draft = this.lowerToDraft(plan);
+		return await this.encodeDraftParams(draft, ctx);
+	}
+	/**
+	* AST → pre-encode draft. The returned plan has `sql` rendered and
+	* `params` populated with the user-domain values the lowering site
+	* collected from `ParamRef` nodes. No codec encode has happened
+	* yet; consumers can mutate `params` via the `SqlParamRefMutator`
+	* before {@link encodeDraftParams} runs.
+	*/
+	lowerToDraft(plan) {
+		return lowerSqlPlan(this.adapter, this.contract, plan);
+	}
+	/**
+	* Encode a draft plan's params through the per-column codecs and
+	* freeze the result into the final `SqlExecutionPlan` the driver
+	* sees. Errors surface as `RUNTIME.ENCODE_FAILED` envelopes from
+	* {@link encodeParams}.
+	*/
+	async encodeDraftParams(draft, ctx) {
+		return Object.freeze({
+			...draft,
+			params: await encodeParams(draft, ctx, this.contractCodecs)
+		});
+	}
+	/**
+	* Default driver invocation required by the abstract `RuntimeCore` contract. Every production path overrides `execute()` and routes through `executeAgainstQueryable`, so this hook is defensive only — subclasses that delegate back to `super.execute()` would land here.
+	*/
+	// v8 ignore next 6
+	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.sqlCtx);
+		return rewrittenDraft.ast === plan.ast ? plan : {
+			...plan,
+			ast: rewrittenDraft.ast,
+			meta: rewrittenDraft.meta
+		};
+	}
+	execute(plan, options) {
+		return this.executeAgainstQueryable(plan, this.driver, options);
+	}
+	executePrepared(ps, params, options) {
+		return this.executePreparedAgainstQueryable(ps, params, this.driver, options);
+	}
+	/**
+	* Returns the raw driver connection. The connection is a `SqlQueryable` — SQL
+	* issued on it runs below the middleware/codec/telemetry pipeline. It carries
+	* its own lifecycle (`release`/`destroy`/`beginTransaction`); the caller owns
+	* disposal.
+	*/
+	acquireRawConnection() {
+		return this.driver.acquireConnection();
+	}
+	async *streamRows(exec, decodeContext, driverCall, codecCtx, execMiddlewareCtx) {
+		this.familyAdapter.validatePlan(exec, this.contract);
+		this._telemetry = null;
+		if (this.verifyMarkerPromise === null) this.verifyMarkerPromise = this.verifyMarker();
+		await this.verifyMarkerPromise;
+		const startedAt = Date.now();
+		let outcome = null;
+		try {
+			const iterator = runWithMiddleware(exec, this.middleware, execMiddlewareCtx, driverCall)[Symbol.asyncIterator]();
+			try {
+				while (true) {
+					checkAborted(codecCtx, "stream");
+					const next = await iterator.next();
+					if (next.done) break;
+					yield await decodeRow(next.value, decodeContext, codecCtx);
+				}
+			} finally {
+				await iterator.return?.();
+			}
+			outcome = "success";
+		} catch (error) {
+			outcome = "runtime-error";
+			throw error;
+		} finally {
+			if (outcome !== null) this.recordTelemetry(exec, outcome, Date.now() - startedAt);
+		}
+	}
+	/**
+	* Execute a plan against a caller-supplied queryable, running the full
+	* middleware/codec/telemetry pipeline. Use `acquireRawConnection` to obtain a
+	* queryable that subclasses can bind typed plans to.
+	*/
+	executeAgainstQueryable(plan, queryable, options) {
+		this.ensureCodecRegistryValidated();
+		const self = this;
+		const signal = options?.signal;
+		const scope = options?.scope ?? "runtime";
+		const codecCtx = signal === void 0 ? {} : { signal };
+		const execMiddlewareCtx = {
+			...self.ctx,
+			...ifDefined("signal", signal),
+			...scope !== "runtime" ? { scope } : {},
+			planExecutionId: crypto.randomUUID()
+		};
+		const generator = async function* () {
+			checkAborted(codecCtx, "stream");
+			let exec;
+			if (isExecutionPlan(plan)) {
+				const preEncodeMutator = createSqlParamRefMutator(plan);
+				await runBeforeExecuteChain(plan, self.middleware, execMiddlewareCtx, preEncodeMutator);
+				exec = Object.freeze({
+					...plan,
+					params: await encodeParams({
+						...plan,
+						params: preEncodeMutator.currentParams()
+					}, codecCtx, self.contractCodecs)
+				});
+			} else {
+				const compiled = await self.runBeforeCompile(plan);
+				const draft = self.lowerToDraft(compiled);
+				const preEncodeMutator = createSqlParamRefMutator(draft);
+				await runBeforeExecuteChain(draft, self.middleware, execMiddlewareCtx, preEncodeMutator);
+				const draftWithMutations = Object.freeze({
+					...draft,
+					params: preEncodeMutator.currentParams()
+				});
+				exec = await self.encodeDraftParams(draftWithMutations, codecCtx);
+			}
+			const decodeContext = buildDecodeContext(exec.ast, self.contractCodecs);
+			yield* self.streamRows(exec, decodeContext, () => queryable.execute({
+				sql: exec.sql,
+				params: exec.params
+			}), codecCtx, execMiddlewareCtx);
+		};
+		return new AsyncIterableResult(generator());
+	}
+	async prepare(declaration, callback) {
+		this.ensureCodecRegistryValidated();
+		const userPlan = callback(buildBindSiteParams(declaration));
+		const finalPlan = await this.runBeforeCompile(userPlan);
+		const orderedRefs = collectOrderedParamRefs(finalPlan.ast);
+		const referencedNames = /* @__PURE__ */ new Set();
+		for (const ref of orderedRefs) if (ref.kind === "prepared-param-ref") referencedNames.add(ref.name);
+		const missing = Object.keys(declaration).filter((name) => !referencedNames.has(name));
+		if (missing.length > 0) throw runtimeError("RUNTIME.PREPARE_UNUSED_PARAM", `Prepared statement declaration includes parameter${missing.length === 1 ? "" : "s"} not referenced by the callback's plan: ${missing.join(", ")}`, { unused: missing });
+		const lowered = this.adapter.lower(finalPlan.ast, {
+			contract: this.contract,
+			params: orderedRefs.map((r) => r.kind === "param-ref" ? r.value : void 0)
+		});
+		const decodeContext = buildDecodeContext(finalPlan.ast, this.contractCodecs);
+		const paramMetadata = deriveParamMetadata(finalPlan.ast);
+		return new PreparedStatementImpl(Object.freeze({
+			sql: lowered.sql,
+			ast: finalPlan.ast,
+			meta: finalPlan.meta,
+			slots: lowered.params,
+			decodeContext,
+			paramMetadata
+		}));
+	}
+	/**
+	* Execute a prepared statement against a caller-supplied queryable, running
+	* the full middleware/codec/telemetry pipeline.
+	*/
+	executePreparedAgainstQueryable(ps, userParams, queryable, options) {
+		this.ensureCodecRegistryValidated();
+		const self = this;
+		const signal = options?.signal;
+		const scope = options?.scope ?? "runtime";
+		const codecCtx = signal === void 0 ? {} : { signal };
+		const execMiddlewareCtx = {
+			...self.ctx,
+			...ifDefined("signal", signal),
+			...scope !== "runtime" ? { scope } : {},
+			planExecutionId: crypto.randomUUID()
+		};
+		const generator = async function* () {
+			checkAborted(codecCtx, "stream");
+			const preEncodeValues = resolvePreparedSlotValues(ps, userParams);
+			const preEncodeExec = {
+				sql: ps.sql,
+				params: preEncodeValues,
+				ast: ps.ast,
+				meta: ps.meta
+			};
+			const mutator = createSqlParamRefMutator(preEncodeExec);
+			await runBeforeExecuteChain(preEncodeExec, self.middleware, execMiddlewareCtx, mutator);
+			const encodedParams = await encodeParamsWithMetadata(mutator.currentParams(), ps.paramMetadata, codecCtx, self.contractCodecs);
+			const exec = {
+				sql: ps.sql,
+				params: encodedParams,
+				ast: ps.ast,
+				meta: ps.meta
+			};
+			const handles = self.#preparedStatementHandles;
+			const request = {
+				sql: exec.sql,
+				params: exec.params,
+				handle: {
+					get: () => handles.get(ps),
+					set: (value) => {
+						handles.set(ps, value);
+					}
+				}
+			};
+			yield* self.streamRows(exec, ps.decodeContext, () => queryable.executePrepared(request), codecCtx, execMiddlewareCtx);
+		};
+		return new AsyncIterableResult(generator());
+	}
+	async connection() {
+		const driverConn = await this.driver.acquireConnection();
+		const self = this;
+		return {
+			async transaction() {
+				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,
+					scope: "connection"
+				});
+			},
+			executePrepared(ps, params, options) {
+				return self.executePreparedAgainstQueryable(ps, params, driverConn, {
+					...options,
+					scope: "connection"
+				});
+			}
+		};
+	}
+	wrapTransaction(driverTx) {
+		const self = this;
+		return {
+			async commit() {
+				await driverTx.commit();
+			},
+			async rollback() {
+				await driverTx.rollback();
+			},
+			execute(plan, options) {
+				return self.executeAgainstQueryable(plan, driverTx, {
+					...options,
+					scope: "transaction"
+				});
+			},
+			executePrepared(ps, params, options) {
+				return self.executePreparedAgainstQueryable(ps, params, driverTx, {
+					...options,
+					scope: "transaction"
+				});
+			}
+		};
+	}
+	telemetry() {
+		return this._telemetry;
+	}
+	async close() {
+		await this.driver.close();
+	}
+	ensureCodecRegistryValidated() {
+		if (!this.codecRegistryValidated) {
+			validateCodecRegistryCompleteness(this.codecDescriptors, this.contract);
+			this.codecRegistryValidated = true;
+		}
+	}
+	async verifyMarker() {
+		const readResult = await this.familyAdapter.markerReader.readMarker(this.driver);
+		const expectedStorageHash = this.contract.storage.storageHash;
+		const expectedProfileHash = this.contract.profileHash ?? null;
+		const expected = {
+			storageHash: expectedStorageHash,
+			profileHash: expectedProfileHash
+		};
+		if (readResult.kind !== "present") {
+			this.sqlCtx.log.warn({
+				code: "CONTRACT.MARKER_MISSING",
+				scope: "marker-verification",
+				expected,
+				actual: null,
+				message: "Contract marker not found in database"
+			});
+			return;
+		}
+		const marker = readResult.record;
+		const storageHashMatch = marker.storageHash === expectedStorageHash;
+		const profileHashMatch = expectedProfileHash === null || marker.profileHash === expectedProfileHash;
+		if (!storageHashMatch || !profileHashMatch) this.sqlCtx.log.warn({
+			code: "CONTRACT.MARKER_MISMATCH",
+			scope: "marker-verification",
+			expected,
+			actual: {
+				storageHash: marker.storageHash,
+				profileHash: marker.profileHash ?? null
+			},
+			message: "Contract marker hash does not match runtime contract"
+		});
+	}
+	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("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();
+	const transaction = await connection.transaction();
+	let invalidated = false;
+	async function* guardedStream(inner) {
+		if (invalidated) throw transactionClosedError();
+		for await (const row of inner) {
+			yield row;
+			if (invalidated) throw transactionClosedError();
+		}
+	}
+	const txContext = {
+		get invalidated() {
+			return invalidated;
+		},
+		execute(plan, options) {
+			if (invalidated) throw transactionClosedError();
+			return new AsyncIterableResult(guardedStream(transaction.execute(plan, options)));
+		},
+		executePrepared(ps, params, options) {
+			if (invalidated) throw transactionClosedError();
+			return new AsyncIterableResult(guardedStream(transaction.executePrepared(ps, params, options)));
+		}
+	};
+	let connectionDisposed = false;
+	const destroyConnection = async (reason) => {
+		if (connectionDisposed) return;
+		connectionDisposed = true;
+		await connection.destroy(reason).catch(() => void 0);
+	};
+	try {
+		let result;
+		try {
+			result = await fn(txContext);
+		} catch (error) {
+			try {
+				await transaction.rollback();
+			} catch (rollbackError) {
+				await destroyConnection(rollbackError);
+				const wrapped = runtimeError("RUNTIME.TRANSACTION_ROLLBACK_FAILED", "Transaction rollback failed after callback error", { rollbackError });
+				wrapped.cause = error;
+				throw wrapped;
+			}
+			throw error;
+		} finally {
+			invalidated = true;
+		}
+		try {
+			await transaction.commit();
+		} catch (commitError) {
+			try {
+				await transaction.rollback();
+			} catch {
+				await destroyConnection(commitError);
+			}
+			const wrapped = runtimeError("RUNTIME.TRANSACTION_COMMIT_FAILED", "Transaction commit failed", { commitError });
+			wrapped.cause = commitError;
+			throw wrapped;
+		}
+		return result;
+	} finally {
+		if (!connectionDisposed) await connection.release();
+	}
+}
+//#endregion
+export { PreparedStatementImpl, SqlRuntimeBase, budgets, createAstCodecRegistry, createExecutionContext, createSqlExecutionStack, deriveParamMetadata, encodeParamsWithMetadata, extractCodecIds, lints, lowerSqlPlan, validateCodecRegistryCompleteness, validateContractCodecMappings, withTransaction };
+
+//# sourceMappingURL=runtime.mjs.map