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

package/dist/{exports-BSTHn_rH.mjs → exports-6tjocFbX.mjs}

@@ -1,9 +1,10 @@
-import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
+import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
 import { type } from "arktype";
-import { collectOrderedParamRefs, isQueryAst, validateParamRefRefs } from "@prisma-next/sql-relational-core/ast";
+import { collectOrderedParamRefs, 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 { canonicalizeJson } from "@prisma-next/framework-components/utils";
 import { createSqlOperationRegistry } from "@prisma-next/sql-operations";
 import { buildCodecDescriptorRegistry } from "@prisma-next/sql-relational-core/codec-descriptor-registry";
 import { APP_SPACE_ID } from "@prisma-next/framework-components/control";
@@ -388,6 +389,46 @@ function lints(options) {
 	});
 }
 //#endregion
+//#region src/codecs/ast-codec-resolver.ts
+/**
+* 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 descriptor = descriptors.descriptorFor(ref.codecId);
+		if (!descriptor) throw runtimeError("RUNTIME.CODEC_DESCRIPTOR_MISSING", `No codec descriptor registered for codecId '${ref.codecId}'.`, { codecId: ref.codecId });
+		const validated = validateTypeParams$1(descriptor.paramsSchema, descriptor.isParameterized && ref.typeParams === void 0 ? {
+			...ref,
+			typeParams: {}
+		} : ref);
+		const ctx = instanceContextFor(ref);
+		const codec = descriptor.factory(validated)(ctx);
+		cache.set(key, codec);
+		return codec;
+	} };
+}
+function validateTypeParams$1(paramsSchema, ref) {
+	const result = paramsSchema["~standard"].validate(ref.typeParams);
+	if (result instanceof Promise) throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `paramsSchema for codec '${ref.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`, {
+		codecId: ref.codecId,
+		typeParams: ref.typeParams
+	});
+	if ("issues" in result && result.issues) {
+		const messages = result.issues.map((issue) => issue.message).join("; ");
+		throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `Invalid typeParams for codec '${ref.codecId}': ${messages}`, {
+			codecId: ref.codecId,
+			typeParams: ref.typeParams
+		});
+	}
+	return result.value;
+}
+//#endregion
 //#region src/sql-context.ts
 function createSqlExecutionStack(options) {
 	return createExecutionStack({
@@ -502,93 +543,124 @@ function validateColumnTypeParams(storage, codecDescriptors) {
 		});
 	}
 }
-function isResolvedCodec(candidate) {
-	return candidate !== null && typeof candidate === "object" && "id" in candidate && "decode" in candidate;
-}
 /**
-* Walk the contract's `storage.tables[].columns[]` and resolve each column to a `Codec` through the unified descriptor map. Per-instance behavior:
+* 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.
 *
-* - **typeRef columns**: reuse the resolved codec materialized once by `initializeTypeHelpers` for the `storage.types` entry. Multiple columns sharing one typeRef share one codec instance.
-* - **inline-typeParams columns**: call `descriptor.factory(typeParams) (ctx)` once per column (per-column anonymous instance).
-* - **non-parameterized columns**: call `descriptor.factory()(ctx)` once. The synthesized descriptor's factory is constant — every call returns the same shared codec instance — so columns sharing a non-parameterized codec id share one resolved codec without explicit caching.
+* Surfaces three classes of malformed contract that AST-bound codec resolution would otherwise mask silently:
 *
-* Codec-registry-unification spec § AC-4: every column resolves through one descriptor map without branching on parameterization. JSON-Schema validation, when required, lives inside the resolved codec's `decode` body (see `arktype-json`'s `ArktypeJsonCodecClass`); the framework no longer maintains a parallel validator registry.
+* - 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 buildContractCodecRegistry(contract, codecDescriptors, types, parameterizedDescriptors) {
-	const byColumn = /* @__PURE__ */ new Map();
-	const byCodecId = /* @__PURE__ */ new Map();
-	const ambiguousCodecIds = /* @__PURE__ */ new Set();
-	for (const descriptor of codecDescriptors.values()) {
-		if (descriptor.isParameterized) continue;
-		const ctx = {
-			name: `<shared:${descriptor.codecId}>`,
-			usedAt: []
-		};
-		const voidFactory = descriptor.factory;
-		byCodecId.set(descriptor.codecId, voidFactory(void 0)(ctx));
+function assertColumnCodecIntegrity(storage, codecDescriptors) {
+	for (const [tableName, table] of Object.entries(storage.tables)) for (const columnName of Object.keys(table.columns)) {
+		const ref = codecDescriptors.codecRefForColumn(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"
+			});
+		}
+		if (!descriptor.isParameterized && ref.typeParams !== void 0) 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"
+		});
 	}
-	const parameterizedRepresentatives = /* @__PURE__ */ new Map();
-	for (const descriptor of codecDescriptors.values()) {
-		if (!descriptor.isParameterized) continue;
-		const ctx = {
-			name: `<shared:${descriptor.codecId}>`,
-			usedAt: []
-		};
-		const factory = descriptor.factory.bind(descriptor);
-		try {
-			parameterizedRepresentatives.set(descriptor.codecId, factory(void 0)(ctx));
-		} catch {}
+}
+/**
+* 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(t, c)` is a thin delegate over `forCodecRef(codecRefForColumn(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(contract.storage.types ?? {})) {
+		const key = refKeyOf({
+			codecId: typeInstance.codecId,
+			typeParams: typeInstance.typeParams
+		});
+		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 [tableName, table] of Object.entries(contract.storage.tables)) for (const [columnName, column] of Object.entries(table.columns)) {
-		const columnKey = `${tableName}.${columnName}`;
-		const descriptor = codecDescriptors.descriptorFor(column.codecId);
-		let resolvedCodec;
-		if (descriptor) {
-			const isParameterized = parameterizedDescriptors.has(column.codecId);
-			if (column.typeRef) {
-				const helper = types[column.typeRef];
-				if (isResolvedCodec(helper)) resolvedCodec = helper;
-			} else if (column.typeParams && isParameterized) {
-				const parameterizedDescriptor = parameterizedDescriptors.get(column.codecId);
-				if (parameterizedDescriptor) {
-					const validatedParams = validateTypeParams(column.typeParams, parameterizedDescriptor, {
-						tableName,
-						columnName
-					});
-					const ctx = {
-						name: `<col:${tableName}.${columnName}>`,
-						usedAt: [{
-							table: tableName,
-							column: columnName
-						}]
-					};
-					resolvedCodec = parameterizedDescriptor.factory(validatedParams)(ctx);
-				}
-			} else if (!isParameterized) {
-				const ctx = {
-					name: `<col:${tableName}.${columnName}>`,
-					usedAt: [{
-						table: tableName,
-						column: columnName
-					}]
-				};
-				resolvedCodec = descriptor.factory.bind(descriptor)(void 0)(ctx);
-			}
-		}
-		if (resolvedCodec) {
-			byColumn.set(columnKey, resolvedCodec);
-			const existing = byCodecId.get(column.codecId);
-			if (existing === void 0) byCodecId.set(column.codecId, resolvedCodec);
-			else if (existing !== resolvedCodec && parameterizedDescriptors.has(column.codecId)) ambiguousCodecIds.add(column.codecId);
+		if (column.typeRef !== void 0) continue;
+		const ref = codecDescriptors.codecRefForColumn(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 [tableName, table] of Object.entries(contract.storage.tables)) for (const columnName of Object.keys(table.columns)) {
+		const ref = codecDescriptors.codecRefForColumn(tableName, columnName);
+		if (!ref) continue;
+		resolver.forCodecRef(ref);
+	}
 	return {
 		forColumn(table, column) {
-			return byColumn.get(`${table}.${column}`);
+			const ref = codecDescriptors.codecRefForColumn(table, column);
+			return ref ? resolver.forCodecRef(ref) : void 0;
 		},
-		forCodecId(codecId) {
-			if (ambiguousCodecIds.has(codecId)) throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `Codec '${codecId}' resolves to multiple parameterized instances; column-aware dispatch is required.`, { codecId });
-			return byCodecId.get(codecId) ?? parameterizedRepresentatives.get(codecId);
+		forCodecRef(ref) {
+			return resolver.forCodecRef(ref);
 		}
 	};
 }
@@ -683,14 +755,15 @@ function createExecutionContext(options) {
 		const ops = contributor.queryOperations?.() ?? {};
 		for (const [name, op] of Object.entries(ops)) queryOperationRegistry.register(name, op);
 	}
-	const codecDescriptors = buildCodecDescriptorRegistry(allCodecDescriptors);
+	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, parameterizedCodecDescriptors);
 	return {
 		contract,
-		contractCodecs: buildContractCodecRegistry(contract, codecDescriptors, types, parameterizedCodecDescriptors),
+		contractCodecs: buildContractCodecRegistry(contract, codecDescriptors),
 		codecDescriptors,
 		queryOperations: queryOperationRegistry,
 		types,
@@ -817,33 +890,6 @@ function writeContractMarker(input) {
 	};
 }
 //#endregion
-//#region src/codecs/alias-resolver.ts
-/**
-* Build a map from query-local table aliases to their underlying source table names.
-*
-* Self-joins like `db.sql.post.as('p1').innerJoin(db.sql.post.as('p2'), …)` produce `ColumnRef`s whose `table` is the alias (`p1`, `p2`) — the SQL renderer needs the alias for `SELECT p1.id, …`. Codec dispatch keys `byColumn` by the underlying source table, so aliases must be resolved back to the source name for `forColumn(...)` to hit. Tables that already use their canonical name (no alias) are also entered so a single
-* lookup works for both shapes.
-*/
-function buildAliasMap(ast) {
-	const aliases = /* @__PURE__ */ new Map();
-	const recordSource = (source) => {
-		if (source.kind === "table-source") {
-			const key = source.alias ?? source.name;
-			aliases.set(key, source.name);
-		} else aliases.set(source.alias, source.alias);
-	};
-	if (ast.kind === "select") {
-		recordSource(ast.from);
-		for (const join of ast.joins ?? []) recordSource(join.source);
-	} else if (ast.kind === "raw-sql") {} else recordSource(ast.table);
-	return aliases;
-}
-function makeAliasResolver(ast) {
-	if (!ast) return (alias) => alias;
-	const map = buildAliasMap(ast);
-	return (alias) => map.get(alias) ?? alias;
-}
-//#endregion
 //#region src/codecs/decoding.ts
 const WIRE_PREVIEW_LIMIT = 100;
 const EMPTY_INCLUDE_ALIASES = /* @__PURE__ */ new Set();
@@ -855,30 +901,8 @@ function projectionListFromAst(ast) {
 	if (ast.kind === "raw-sql") return;
 	return ast.returning;
 }
-/**
-* Resolve the per-cell codec for a projection item.
-*
-* When a `(table, column)` ref is available — either implicit on a `column-ref` expression or carried explicitly via `item.refs` for column-bound non-`column-ref` projections — prefer `contractCodecs.forColumn(table, column)`: that returns the per-instance codec materialized from the descriptor's factory for that column, encoding any per-instance state (typeParams like vector length, schema validators, etc.).
-*
-* The wrong-instance risk for parameterized codecs is closed off structurally:
-*
-* 1. `buildContractCodecRegistry` pre-populates `byCodecId` with one canonical instance per non-parameterized descriptor; parameterized descriptors are intentionally absent. 2. `forCodecId` rejects ambiguous parameterized fallbacks (`ambiguousCodecIds`). 3. The non-ambiguous parameterized case stores the column-correct per-instance codec under `byCodecId`, so the fall-through still resolves to the right instance.
-*
-* The `forCodecId` fallback otherwise covers projections that are *not* column-bound (computed projections, raw SQL aliases) but still carry a `codecId` (ADR 205 stamps every `ProjectionItem` with the producer's codec id).
-*
-* Codec-registry-unification spec § AC-4 / AC-5.
-*/
-function resolveProjectionCodec(item, contractCodecs, aliasResolver) {
-	if (contractCodecs) {
-		if (item.expr.kind === "column-ref") {
-			const byColumn = contractCodecs.forColumn(aliasResolver(item.expr.table), item.expr.column);
-			if (byColumn && (item.codecId === void 0 || byColumn.id === item.codecId)) return byColumn;
-		} else if (item.refs) {
-			const byColumn = contractCodecs.forColumn(aliasResolver(item.refs.table), item.refs.column);
-			if (byColumn && (item.codecId === void 0 || byColumn.id === item.codecId)) return byColumn;
-		}
-	}
-	if (item.codecId) return contractCodecs?.forCodecId(item.codecId);
+function resolveProjectionCodec(item, contractCodecs) {
+	if (item.codec && contractCodecs) return contractCodecs.forCodecRef(item.codec);
 }
 function buildDecodeContext(plan, contractCodecs) {
 	if (!isAstBackedPlan(plan)) return {
@@ -898,19 +922,14 @@ function buildDecodeContext(plan, contractCodecs) {
 	const codecs = /* @__PURE__ */ new Map();
 	const columnRefs = /* @__PURE__ */ new Map();
 	const includeAliases = /* @__PURE__ */ new Set();
-	const aliasResolver = makeAliasResolver(plan.ast);
 	for (const item of projection) {
 		aliases.push(item.alias);
-		const codec = resolveProjectionCodec(item, contractCodecs, aliasResolver);
+		const codec = resolveProjectionCodec(item, contractCodecs);
 		if (codec) codecs.set(item.alias, codec);
 		if (item.expr.kind === "column-ref") columnRefs.set(item.alias, {
-			table: aliasResolver(item.expr.table),
+			table: item.expr.table,
 			column: item.expr.column
 		});
-		else if (item.refs) columnRefs.set(item.alias, {
-			table: aliasResolver(item.refs.table),
-			column: item.refs.column
-		});
 		else if (item.expr.kind === "subquery" || item.expr.kind === "json-array-agg") includeAliases.add(item.alias);
 	}
 	return {
@@ -1035,29 +1054,11 @@ async function decodeRow(row, plan, rowCtx, contractCodecs) {
 //#endregion
 //#region src/codecs/encoding.ts
 const NO_METADATA = Object.freeze({
-	codecId: void 0,
-	name: void 0,
-	refs: void 0
+	codec: void 0,
+	name: void 0
 });
-/**
-* Resolve the codec for an outgoing param.
-*
-* Column-aware dispatch: when `metadata.refs` is populated by a column-bound construction site, prefer `contractCodecs.forColumn(refs.table, refs.column)` — that returns the per-instance codec the contract walk materialized for the `(table, column)` pair, encoding the column's typeParams (e.g. `vector(1024)` vs. `vector(1536)`).
-*
-* On a column-lookup miss the resolver falls through to `forCodecId`. The wrong-instance risk for parameterized codecs is closed off structurally:
-*
-* 1. `buildContractCodecRegistry` pre-populates `byCodecId` with one canonical instance per non-parameterized descriptor; parameterized descriptors are intentionally absent from this pre-population. 2. `forCodecId` rejects ambiguous parameterized fallbacks (`ambiguousCodecIds`) — if the contract walk resolved more than one distinct instance under a single parameterized id, the call throws rather than binding to
-* whichever landed first. 3. For the non-ambiguous parameterized case (a single column with that id), `byCodecId` stores the column-correct per-instance codec, so the fall-through still resolves to the right instance.
-*
-* Refs-less fallback: ParamRefs constructed outside a column-bound site (literals, transient builder state) carry a non-parameterized `codecId` whose dispatch is ambiguity-free. The validator pass (`validateParamRefRefs`) already enforced refs on every parameterized ParamRef before encode runs.
-*/
-function resolveParamCodec(metadata, contractCodecs, aliasResolver) {
-	if (!metadata.codecId) return void 0;
-	if (metadata.refs && contractCodecs) {
-		const byColumn = contractCodecs.forColumn(aliasResolver(metadata.refs.table), metadata.refs.column);
-		if (byColumn && byColumn.id === metadata.codecId) return byColumn;
-	}
-	return contractCodecs?.forCodecId(metadata.codecId);
+function resolveParamCodec(metadata, contractCodecs) {
+	if (metadata.codec && contractCodecs) return contractCodecs.forCodecRef(metadata.codec);
 }
 function paramLabel(metadata, paramIndex) {
 	return metadata.name ?? `param[${paramIndex}]`;
@@ -1072,13 +1073,14 @@ function wrapEncodeFailure(error, metadata, paramIndex, codecId) {
 	wrapped.cause = error;
 	throw wrapped;
 }
-async function encodeParamValue(value, metadata, paramIndex, ctx, contractCodecs, aliasResolver) {
+async function encodeParamValue(value, metadata, paramIndex, ctx, contractCodecs) {
 	if (value === null || value === void 0) return null;
-	const codec = resolveParamCodec(metadata, contractCodecs, aliasResolver);
+	const codec = resolveParamCodec(metadata, contractCodecs);
 	if (!codec) return value;
 	try {
 		return await codec.encode(value, ctx);
 	} catch (error) {
+		if (isRuntimeError(error)) throw error;
 		wrapEncodeFailure(error, metadata, paramIndex, codec.id);
 	}
 }
@@ -1102,15 +1104,13 @@ async function encodeParams(plan, ctx, contractCodecs) {
 		for (let i = 0; i < paramCount && i < refs.length; i++) {
 			const ref = refs[i];
 			if (ref) metadata[i] = {
-				codecId: ref.codecId,
-				name: ref.name,
-				refs: ref.refs
+				codec: ref.codec,
+				name: ref.name
 			};
 		}
 	}
-	const aliasResolver = makeAliasResolver(plan.ast);
 	const tasks = new Array(paramCount);
-	for (let i = 0; i < paramCount; i++) tasks[i] = encodeParamValue(plan.params[i], metadata[i] ?? NO_METADATA, i, ctx, contractCodecs, aliasResolver);
+	for (let i = 0; i < paramCount; i++) tasks[i] = encodeParamValue(plan.params[i], metadata[i] ?? NO_METADATA, i, ctx, contractCodecs);
 	const settled = await raceAgainstAbort(Promise.all(tasks), signal, "encode");
 	return Object.freeze(settled);
 }
@@ -1266,16 +1266,49 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 		}
 	}
 	/**
-	* 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.
+	* 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. 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.
+	* `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) {
-		validateParamRefRefs(plan.ast, this.codecDescriptors);
-		const lowered = lowerSqlPlan(this.adapter, this.contract, plan);
+		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({
-			...lowered,
-			params: await encodeParams(lowered, ctx, this.contractCodecs)
+			...draft,
+			params: await encodeParams(draft, ctx, this.contractCodecs)
 		});
 	}
 	/**
@@ -1319,12 +1352,26 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 			checkAborted(codecCtx, "stream");
 			let exec;
 			if (isExecutionPlan(plan)) {
-				if (plan.ast) validateParamRefRefs(plan.ast, self.codecDescriptors);
+				const preEncodeMutator = createSqlParamRefMutator(plan);
+				await runBeforeExecuteChain(plan, self.middleware, execMiddlewareCtx, preEncodeMutator);
 				exec = Object.freeze({
 					...plan,
-					params: await encodeParams(plan, codecCtx, self.contractCodecs)
+					params: await encodeParams({
+						...plan,
+						params: preEncodeMutator.currentParams()
+					}, codecCtx, self.contractCodecs)
 				});
-			} else exec = await self.lower(await self.runBeforeCompile(plan), codecCtx);
+			} 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);
+			}
 			self.familyAdapter.validatePlan(exec, self.contract);
 			self._telemetry = null;
 			if (!self.startupVerified && self.verify.mode === "startup") await self.verifyMarker();
@@ -1333,11 +1380,10 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 			let outcome = null;
 			try {
 				if (self.verify.mode === "always") await self.verifyMarker();
-				const paramsMutator = createSqlParamRefMutator(exec);
 				const iterator = runWithMiddleware(exec, self.middleware, execMiddlewareCtx, () => queryable.execute({
 					sql: exec.sql,
-					params: paramsMutator.currentParams()
-				}), paramsMutator)[Symbol.asyncIterator]();
+					params: exec.params
+				}))[Symbol.asyncIterator]();
 				try {
 					while (true) {
 						checkAborted(codecCtx, "stream");
@@ -1513,4 +1559,4 @@ function createRuntime(options) {
 //#endregion
 export { ensureTableStatement as a, createExecutionContext as c, budgets as d, parseContractMarkerRow as f, validateContractCodecMappings as g, validateCodecRegistryCompleteness as h, ensureSchemaStatement as i, createSqlExecutionStack as l, extractCodecIds as m, withTransaction as n, readContractMarker as o, lowerSqlPlan as p, APP_SPACE_ID as r, writeContractMarker as s, createRuntime as t, lints as u };
 
-//# sourceMappingURL=exports-BSTHn_rH.mjs.map
+//# sourceMappingURL=exports-6tjocFbX.mjs.map