@prisma-next/sql-runtime 0.5.0-dev.8 → 0.5.0-dev.80

package/src/codecs/decoding.ts

@@ -1,81 +1,134 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
-import { isRuntimeError, runtimeError } from '@prisma-next/framework-components/runtime';
-import type { Codec, CodecRegistry } from '@prisma-next/sql-relational-core/ast';
-import type { JsonSchemaValidatorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
-import { validateJsonValue } from './json-schema-validation';
+import {
+  checkAborted,
+  isRuntimeError,
+  raceAgainstAbort,
+  runtimeError,
+} from '@prisma-next/framework-components/runtime';
+import type {
+  AnyQueryAst,
+  Codec,
+  ContractCodecRegistry,
+  ProjectionItem,
+  SqlCodecCallContext,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
+import { makeAliasResolver } from './alias-resolver';
 
 type ColumnRef = { table: string; column: string };
-type ColumnRefIndex = Map<string, ColumnRef>;
+
+interface DecodeContext {
+  readonly aliases: ReadonlyArray<string> | undefined;
+  readonly codecs: ReadonlyMap<string, Codec>;
+  readonly columnRefs: ReadonlyMap<string, ColumnRef>;
+  readonly includeAliases: ReadonlySet<string>;
+}
 
 const WIRE_PREVIEW_LIMIT = 100;
+const EMPTY_INCLUDE_ALIASES: ReadonlySet<string> = new Set<string>();
 
-function resolveRowCodec(
-  alias: string,
-  plan: ExecutionPlan,
-  registry: CodecRegistry,
-): Codec | null {
-  const planCodecId = plan.meta.annotations?.codecs?.[alias] as string | undefined;
-  if (planCodecId) {
-    const codec = registry.get(planCodecId);
-    if (codec) {
-      return codec;
-    }
-  }
+function isAstBackedPlan(
+  plan: SqlExecutionPlan,
+): plan is SqlExecutionPlan & { readonly ast: AnyQueryAst } {
+  return plan.ast !== undefined;
+}
 
-  if (plan.meta.projectionTypes) {
-    const typeId = plan.meta.projectionTypes[alias];
-    if (typeId) {
-      const codec = registry.get(typeId);
-      if (codec) {
-        return codec;
-      }
-    }
+function projectionListFromAst(ast: AnyQueryAst): ReadonlyArray<ProjectionItem> | undefined {
+  if (ast.kind === 'select') {
+    return ast.projection;
   }
-
-  return null;
+  if (ast.kind === 'raw-sql') {
+    return undefined;
+  }
+  return ast.returning;
 }
 
-function buildColumnRefIndex(plan: ExecutionPlan): ColumnRefIndex | null {
-  const columns = plan.meta.refs?.columns;
-  if (!columns) return null;
-
-  const index: ColumnRefIndex = new Map();
-  for (const ref of columns) {
-    index.set(ref.column, ref);
+/**
+ * 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: ProjectionItem,
+  contractCodecs: ContractCodecRegistry | undefined,
+  aliasResolver: (alias: string) => string,
+): Codec | undefined {
+  if (contractCodecs) {
+    if (item.expr.kind === 'column-ref') {
+      const byColumn = contractCodecs.forColumn(aliasResolver(item.expr.table), item.expr.column);
+      // Only honour `byColumn` when its codec id agrees with `item.codecId`. They can legitimately disagree when an `OperationExpr`-shaped projection carries a single inner column-ref but transforms the value's codec (e.g. `cosineDistance(col, x)` projects `pg/float8@1` while the inner column-ref points at a `pg/vector@1` column).
+      if (byColumn && (item.codecId === undefined || 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 === undefined || byColumn.id === item.codecId)) return byColumn;
+    }
   }
-  return index;
+  if (item.codecId) {
+    return contractCodecs?.forCodecId(item.codecId);
+  }
+  return undefined;
 }
 
-function parseProjectionRef(value: string): ColumnRef | null {
-  if (value.startsWith('include:') || value.startsWith('operation:')) {
-    return null;
+function buildDecodeContext(
+  plan: SqlExecutionPlan,
+  contractCodecs: ContractCodecRegistry | undefined,
+): DecodeContext {
+  if (!isAstBackedPlan(plan)) {
+    return {
+      aliases: undefined,
+      codecs: new Map(),
+      columnRefs: new Map(),
+      includeAliases: EMPTY_INCLUDE_ALIASES,
+    };
   }
 
-  const separatorIndex = value.indexOf('.');
-  if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
-    return null;
+  const projection = projectionListFromAst(plan.ast);
+  if (!projection) {
+    return {
+      aliases: undefined,
+      codecs: new Map(),
+      columnRefs: new Map(),
+      includeAliases: EMPTY_INCLUDE_ALIASES,
+    };
   }
 
-  return {
-    table: value.slice(0, separatorIndex),
-    column: value.slice(separatorIndex + 1),
-  };
-}
+  const aliases: string[] = [];
+  const codecs = new Map<string, Codec>();
+  const columnRefs = new Map<string, ColumnRef>();
+  const includeAliases = new Set<string>();
+  const aliasResolver = makeAliasResolver(plan.ast);
 
-function resolveColumnRefForAlias(
-  alias: string,
-  projection: ExecutionPlan['meta']['projection'],
-  fallbackColumnRefIndex: ColumnRefIndex | null,
-): ColumnRef | undefined {
-  if (projection && !Array.isArray(projection)) {
-    const mappedRef = (projection as Record<string, string>)[alias];
-    if (typeof mappedRef !== 'string') {
-      return undefined;
+  for (const item of projection) {
+    aliases.push(item.alias);
+
+    const codec = resolveProjectionCodec(item, contractCodecs, aliasResolver);
+    if (codec) {
+      codecs.set(item.alias, codec);
+    }
+
+    if (item.expr.kind === 'column-ref') {
+      columnRefs.set(item.alias, {
+        table: aliasResolver(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 parseProjectionRef(mappedRef) ?? undefined;
   }
 
-  return fallbackColumnRefIndex?.get(alias);
+  return { aliases, codecs, columnRefs, includeAliases };
 }
 
 function previewWireValue(wireValue: unknown): string {
@@ -87,10 +140,6 @@ function previewWireValue(wireValue: unknown): string {
   return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);
 }
 
-function isJsonSchemaValidationError(error: unknown): boolean {
-  return isRuntimeError(error) && error.code === 'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED';
-}
-
 function wrapDecodeFailure(
   error: unknown,
   alias: string,
@@ -153,77 +202,82 @@ function decodeIncludeAggregate(alias: string, wireValue: unknown): unknown {
 }
 
 /**
- * Decodes a single field. Single-armed: every cell takes the same path —
- * `codec.decode → await → JSON-Schema validate → return plain value` — so
- * sync- and async-authored codecs are indistinguishable to callers.
+ * 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.
  */
 async function decodeField(
   alias: string,
   wireValue: unknown,
-  plan: ExecutionPlan,
-  registry: CodecRegistry,
-  jsonValidators: JsonSchemaValidatorRegistry | undefined,
-  projection: ExecutionPlan['meta']['projection'],
-  fallbackColumnRefIndex: ColumnRefIndex | null,
+  decodeCtx: DecodeContext,
+  rowCtx: SqlCodecCallContext,
 ): Promise<unknown> {
-  if (wireValue === null || wireValue === undefined) {
-    return wireValue;
+  if (wireValue === null) {
+    return null;
   }
 
-  const codec = resolveRowCodec(alias, plan, registry);
+  const codec = decodeCtx.codecs.get(alias);
   if (!codec) {
     return wireValue;
   }
 
-  const ref = resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex);
+  const ref = decodeCtx.columnRefs.get(alias);
 
-  let decoded: unknown;
-  try {
-    decoded = await codec.decode(wireValue);
-  } catch (error) {
-    wrapDecodeFailure(error, alias, ref, codec, wireValue);
+  // Per-cell ctx: the cell-level `column` is a `SqlColumnRef = { table, name }` projection of the resolved `ColumnRef = { table, column }` (same resolution `wrapDecodeFailure` uses below — no double work). Cells the runtime cannot resolve (aggregate aliases, computed projections without a simple ref) drop the `column` field entirely — explicitly cleared so a previously-populated `rowCtx.column` cannot leak through to
+  // unrelated cells. Destructuring (rather than `column: undefined`) is required because `SqlCodecCallContext.column` is declared `column?: SqlColumnRef` under `exactOptionalPropertyTypes`.
+  let cellCtx: SqlCodecCallContext;
+  if (ref) {
+    cellCtx = { ...rowCtx, column: { table: ref.table, name: ref.column } };
+  } else {
+    const { column: _drop, ...rowCtxWithoutColumn } = rowCtx;
+    cellCtx = rowCtxWithoutColumn;
   }
 
-  if (jsonValidators && ref) {
-    try {
-      validateJsonValue(jsonValidators, ref.table, ref.column, decoded, 'decode', codec.id);
-    } catch (error) {
-      if (isJsonSchemaValidationError(error)) throw error;
-      wrapDecodeFailure(error, alias, ref, codec, wireValue);
+  try {
+    return await codec.decode(wireValue, cellCtx);
+  } catch (error) {
+    // Codec-authored runtime envelopes (e.g. `RUNTIME.DECODE_FAILED` thrown from inside the codec body, or `RUNTIME.ABORTED` raised via `CodecCallContext.signal` per ADR 207) carry their own per-codec context — wrapping them again would erase that context and coerce the abort intent into a generic decode failure. Pass them through unchanged; only foreign errors get the `wrapDecodeFailure` envelope.
+    if (isRuntimeError(error)) {
+      throw error;
     }
+    wrapDecodeFailure(error, alias, ref, codec, wireValue);
   }
-
-  return decoded;
 }
 
 /**
- * Decodes a row by dispatching all per-cell codec calls concurrently via
- * `Promise.all`. Each cell follows the single-armed `decodeField` path.
- * Failures are wrapped in `RUNTIME.DECODE_FAILED` with `{ table, column,
- * codec }` (or `{ alias, codec }` when no column ref is resolvable) and the
- * original error attached on `cause`.
+ * Decodes a row by dispatching all per-cell codec calls concurrently via `Promise.all`. Each cell follows the single-armed `decodeField` path. Failures are wrapped in `RUNTIME.DECODE_FAILED` with `{ table, column, codec }` (or `{ alias, codec }` when no column ref is resolvable) and the original error attached on `cause`.
+ *
+ * When `rowCtx.signal` is provided:
+ *
+ * - **Already-aborted at entry** short-circuits with `RUNTIME.ABORTED` (`{ phase: 'decode' }`) before any `codec.decode` call is made.
+ * - **Mid-flight aborts** race the per-cell `Promise.all` against the signal so the runtime returns promptly even when codec bodies ignore it. In-flight bodies that ignore the signal complete in the background (cooperative cancellation).
+ * - Existing `RUNTIME.DECODE_FAILED` envelopes from codec bodies pass through unchanged (no double wrap).
  */
 export async function decodeRow(
   row: Record<string, unknown>,
-  plan: ExecutionPlan,
-  registry: CodecRegistry,
-  jsonValidators?: JsonSchemaValidatorRegistry,
+  plan: SqlExecutionPlan,
+  rowCtx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
 ): Promise<Record<string, unknown>> {
-  const projection = plan.meta.projection;
-
-  // Build a column-ref index when the projection alias-to-ref mapping is
-  // unavailable so that decode failures and JSON-Schema validation can both
-  // surface { table, column } from `meta.refs.columns` when present.
-  const fallbackColumnRefIndex =
-    !projection || Array.isArray(projection) ? buildColumnRefIndex(plan) : null;
-
-  let aliases: readonly string[];
-  if (projection && !Array.isArray(projection)) {
-    aliases = Object.keys(projection);
-  } else if (projection && Array.isArray(projection)) {
-    aliases = projection;
-  } else {
-    aliases = Object.keys(row);
+  checkAborted(rowCtx, 'decode');
+  const signal = rowCtx.signal;
+
+  const decodeCtx = buildDecodeContext(plan, contractCodecs);
+
+  const aliases = decodeCtx.aliases ?? Object.keys(row);
+
+  if (decodeCtx.aliases !== undefined) {
+    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: Promise<unknown>[] = [];
@@ -233,34 +287,18 @@ export async function decodeRow(
     const alias = aliases[i] as string;
     const wireValue = row[alias];
 
-    const projectionValue =
-      projection && typeof projection === 'object' && !Array.isArray(projection)
-        ? (projection as Record<string, string>)[alias]
-        : undefined;
-
-    if (typeof projectionValue === 'string' && projectionValue.startsWith('include:')) {
+    if (decodeCtx.includeAliases.has(alias)) {
       includeIndices.push({ index: i, alias, value: wireValue });
       tasks.push(Promise.resolve(undefined));
       continue;
     }
 
-    tasks.push(
-      decodeField(
-        alias,
-        wireValue,
-        plan,
-        registry,
-        jsonValidators,
-        projection,
-        fallbackColumnRefIndex,
-      ),
-    );
+    tasks.push(decodeField(alias, wireValue, decodeCtx, rowCtx));
   }
 
-  const settled = await Promise.all(tasks);
+  const settled = await raceAgainstAbort(Promise.all(tasks), signal, 'decode');
 
-  // Include aggregates are decoded synchronously after concurrent codec
-  // dispatch settles, so any decode failures upstream propagate first.
+  // Include aggregates are decoded synchronously after concurrent codec dispatch settles, so any decode failures upstream propagate first.
   for (const entry of includeIndices) {
     settled[entry.index] = decodeIncludeAggregate(entry.alias, entry.value);
   }

package/src/codecs/encoding.ts

@@ -1,32 +1,71 @@
-import type { ExecutionPlan, ParamDescriptor } from '@prisma-next/contract/types';
-import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { Codec, CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import {
+  checkAborted,
+  raceAgainstAbort,
+  runtimeError,
+} from '@prisma-next/framework-components/runtime';
+import {
+  type Codec,
+  type ContractCodecRegistry,
+  collectOrderedParamRefs,
+  type ParamRefBindingRefs,
+  type SqlCodecCallContext,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
+import { makeAliasResolver } from './alias-resolver';
 
+interface ParamMetadata {
+  readonly codecId: string | undefined;
+  readonly name: string | undefined;
+  readonly refs: ParamRefBindingRefs | undefined;
+}
+
+const NO_METADATA: ParamMetadata = Object.freeze({
+  codecId: undefined,
+  name: undefined,
+  refs: undefined,
+});
+
+/**
+ * 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(
-  paramDescriptor: ParamDescriptor,
-  registry: CodecRegistry,
-): Codec | null {
-  if (paramDescriptor.codecId) {
-    const codec = registry.get(paramDescriptor.codecId);
-    if (codec) {
-      return codec;
-    }
+  metadata: ParamMetadata,
+  contractCodecs: ContractCodecRegistry | undefined,
+  aliasResolver: (alias: string) => string,
+): Codec | undefined {
+  if (!metadata.codecId) return undefined;
+  if (metadata.refs && contractCodecs) {
+    const byColumn = contractCodecs.forColumn(
+      aliasResolver(metadata.refs.table),
+      metadata.refs.column,
+    );
+    // Only honour `byColumn` when its codec id agrees with the `ParamRef`'s declared `codecId`. They can legitimately disagree when a heuristic (e.g. the ORM's `refsFromLeft`) lifts column refs out of an `OperationExpr` that changed the codec id — e.g. `cosineDistance(p.embedding, x).lt(1)` carries `refs={post,embedding}` (a vector column) but the comparison side's codec is `pg/float8@1`. Trusting `byColumn` blindly would dispatch the float
+    // literal through the vector codec.
+    if (byColumn && byColumn.id === metadata.codecId) return byColumn;
   }
-
-  return null;
+  return contractCodecs?.forCodecId(metadata.codecId);
 }
 
-function paramLabel(paramDescriptor: ParamDescriptor, paramIndex: number): string {
-  return paramDescriptor.name ?? `param[${paramIndex}]`;
+function paramLabel(metadata: ParamMetadata, paramIndex: number): string {
+  return metadata.name ?? `param[${paramIndex}]`;
 }
 
 function wrapEncodeFailure(
   error: unknown,
-  paramDescriptor: ParamDescriptor,
+  metadata: ParamMetadata,
   paramIndex: number,
   codecId: string,
 ): never {
-  const label = paramLabel(paramDescriptor, paramIndex);
+  const label = paramLabel(metadata, paramIndex);
   const message = error instanceof Error ? error.message : String(error);
   const wrapped = runtimeError(
     'RUNTIME.ENCODE_FAILED',
@@ -38,66 +77,103 @@ function wrapEncodeFailure(
 }
 
 /**
- * Encodes a single parameter through its codec. Always awaits codec.encode so
- * a Promise can never leak into the driver, even if a sync-authored codec is
- * lifted to async by the codec() factory. Failures are wrapped in
- * `RUNTIME.ENCODE_FAILED` with `{ label, codec, paramIndex }` and the original
- * error attached on `cause`.
+ * Encodes a single parameter through its codec. Always awaits codec.encode so a Promise can never leak into the driver, even if a sync-authored codec is lifted to async by the codec factory. Failures are wrapped in `RUNTIME.ENCODE_FAILED` with `{ label, codec, paramIndex }` and the original error attached on `cause`.
+ *
+ * `ctx` is forwarded verbatim to `codec.encode` so codec authors who opt into the `(value, ctx)` arity see the same `SqlCodecCallContext` the runtime built for the surrounding `runtime.execute()` call. The ctx is always present; its `signal` field may be `undefined`. Encode call sites do not populate `ctx.column` — encode-time column context is the middleware's domain.
  */
 export async function encodeParam(
   value: unknown,
-  paramDescriptor: ParamDescriptor,
+  paramRef: {
+    readonly codecId?: string;
+    readonly name?: string;
+    readonly refs?: ParamRefBindingRefs;
+  },
+  paramIndex: number,
+  ctx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
+): Promise<unknown> {
+  return encodeParamValue(
+    value,
+    { codecId: paramRef.codecId, name: paramRef.name, refs: paramRef.refs },
+    paramIndex,
+    ctx,
+    contractCodecs,
+    (alias) => alias,
+  );
+}
+
+async function encodeParamValue(
+  value: unknown,
+  metadata: ParamMetadata,
   paramIndex: number,
-  registry: CodecRegistry,
+  ctx: SqlCodecCallContext,
+  contractCodecs: ContractCodecRegistry | undefined,
+  aliasResolver: (alias: string) => string,
 ): Promise<unknown> {
   if (value === null || value === undefined) {
     return null;
   }
 
-  const codec = resolveParamCodec(paramDescriptor, registry);
+  const codec = resolveParamCodec(metadata, contractCodecs, aliasResolver);
   if (!codec) {
     return value;
   }
 
   try {
-    return await codec.encode(value);
+    return await codec.encode(value, ctx);
   } catch (error) {
-    wrapEncodeFailure(error, paramDescriptor, paramIndex, codec.id);
+    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`.
+ * Encodes all parameters concurrently via `Promise.all`. Per parameter, sync-and async-authored codecs share the same path: `codec.encode → await → return`. Param-level failures are wrapped in `RUNTIME.ENCODE_FAILED`.
+ *
+ * When `ctx.signal` is provided:
+ *
+ * - **Already-aborted at entry** short-circuits with `RUNTIME.ABORTED` (`{ phase: 'encode' }`) before any `codec.encode` call is made — codecs can pin this with a per-call counter that stays at zero.
+ * - **Mid-flight abort** races the per-param `Promise.all` against `abortable(ctx.signal)`. The runtime returns `RUNTIME.ABORTED` promptly even if codec bodies ignore the signal; the in-flight bodies are abandoned and run to completion in the background (cooperative cancellation, see ADR 204).
+ * - Existing `RUNTIME.ENCODE_FAILED` envelopes that surface from a codec body before the runtime observes the abort pass through unchanged (no double wrap).
  */
 export async function encodeParams(
-  plan: ExecutionPlan,
-  registry: CodecRegistry,
+  plan: SqlExecutionPlan,
+  ctx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
 ): Promise<readonly unknown[]> {
+  checkAborted(ctx, 'encode');
+  const signal = ctx.signal;
+
   if (plan.params.length === 0) {
     return plan.params;
   }
 
-  const descriptorCount = plan.meta.paramDescriptors.length;
   const paramCount = plan.params.length;
+  const metadata: ParamMetadata[] = new Array(paramCount).fill(NO_METADATA);
 
-  const tasks: Promise<unknown>[] = new Array(paramCount);
-  for (let i = 0; i < paramCount; i++) {
-    const paramValue = plan.params[i];
-    const paramDescriptor = plan.meta.paramDescriptors[i];
-
-    if (!paramDescriptor) {
-      throw runtimeError(
-        'RUNTIME.MISSING_PARAM_DESCRIPTOR',
-        `Missing paramDescriptor for parameter at index ${i} (plan has ${paramCount} params, ${descriptorCount} descriptors). The planner must emit one descriptor per param; this is a contract violation.`,
-        { paramIndex: i, paramCount, descriptorCount },
-      );
+  if (plan.ast) {
+    const refs = collectOrderedParamRefs(plan.ast);
+    for (let i = 0; i < paramCount && i < refs.length; i++) {
+      const ref = refs[i];
+      if (ref) {
+        metadata[i] = { codecId: ref.codecId, name: ref.name, refs: ref.refs };
+      }
     }
+  }
+
+  const aliasResolver = makeAliasResolver(plan.ast);
 
-    tasks[i] = encodeParam(paramValue, paramDescriptor, i, registry);
+  const tasks: Promise<unknown>[] = new Array(paramCount);
+  for (let i = 0; i < paramCount; i++) {
+    tasks[i] = encodeParamValue(
+      plan.params[i],
+      metadata[i] ?? NO_METADATA,
+      i,
+      ctx,
+      contractCodecs,
+      aliasResolver,
+    );
   }
 
-  const encoded = await Promise.all(tasks);
-  return Object.freeze(encoded);
+  const settled = await raceAgainstAbort(Promise.all(tasks), signal, 'encode');
+  return Object.freeze(settled);
 }

package/src/codecs/validation.ts

@@ -1,7 +1,7 @@
 import type { Contract } from '@prisma-next/contract/types';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
-import type { CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
 
 export function extractCodecIds(contract: Contract<SqlStorage>): Set<string> {
   const codecIds = new Set<string>();
@@ -31,14 +31,14 @@ function extractCodecIdsFromColumns(contract: Contract<SqlStorage>): Map<string,
 }
 
 export function validateContractCodecMappings(
-  registry: CodecRegistry,
+  registry: CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
   const codecIds = extractCodecIdsFromColumns(contract);
   const invalidCodecs: Array<{ table: string; column: string; codecId: string }> = [];
 
   for (const [key, codecId] of codecIds.entries()) {
-    if (!registry.has(codecId)) {
+    if (registry.descriptorFor(codecId) === undefined) {
       const parts = key.split('.');
       const table = parts[0] ?? '';
       const column = parts[1] ?? '';
@@ -61,7 +61,7 @@ export function validateContractCodecMappings(
 }
 
 export function validateCodecRegistryCompleteness(
-  registry: CodecRegistry,
+  registry: CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
   validateContractCodecMappings(registry, contract);