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

package/src/codecs/encoding.ts

@@ -6,6 +6,7 @@ import {
 import {
   type Codec,
   type CodecRegistry,
+  type ContractCodecRegistry,
   collectOrderedParamRefs,
   type SqlCodecCallContext,
 } from '@prisma-next/sql-relational-core/ast';
@@ -18,6 +19,39 @@ interface ParamMetadata {
 
 const NO_METADATA: ParamMetadata = Object.freeze({ codecId: undefined, name: undefined });
 
+/**
+ * Resolve the codec for an outgoing param.
+ *
+ * Phase B (and AC-5-deferred carve-out): `ParamRef` does not carry a
+ * `(table, column)` ref today — every `ParamRef` carries `codecId` but
+ * not the column it relates to. Encode-side dispatch therefore consults
+ * `contractCodecs.forCodecId(codecId)` (which itself prefers the
+ * contract-walk-derived shared codec, falling back to the legacy
+ * `CodecRegistry.get` for parameterized codec ids whose contracts don't
+ * have a column the walk could resolve through).
+ *
+ * For the parameterized codecs shipped at Phase B (pgvector, postgres
+ * json/jsonb), encode is per-instance-stateless w.r.t. params:
+ * - pgvector formats `[v1,v2,...]` regardless of declared length;
+ * - postgres json/jsonb encode is `JSON.stringify` regardless of schema.
+ *
+ * So the codec-id-keyed lookup yields a structurally equivalent encoder
+ * even when the resolved per-instance codec carries extra state (e.g. a
+ * compiled JSON-Schema validator used only by `decode`). TML-2357 retires
+ * the fallback by threading `ParamRef.refs` through column-bound
+ * construction sites.
+ */
+function resolveParamCodec(
+  metadata: ParamMetadata,
+  registry: CodecRegistry,
+  contractCodecs: ContractCodecRegistry | undefined,
+): Codec | undefined {
+  if (!metadata.codecId) return undefined;
+  const fromContract = contractCodecs?.forCodecId(metadata.codecId);
+  if (fromContract) return fromContract;
+  return registry.get(metadata.codecId);
+}
+
 function paramLabel(metadata: ParamMetadata, paramIndex: number): string {
   return metadata.name ?? `param[${paramIndex}]`;
 }
@@ -59,6 +93,7 @@ export async function encodeParam(
   paramIndex: number,
   registry: CodecRegistry,
   ctx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
 ): Promise<unknown> {
   return encodeParamValue(
     value,
@@ -66,6 +101,7 @@ export async function encodeParam(
     paramIndex,
     registry,
     ctx,
+    contractCodecs,
   );
 }
 
@@ -75,16 +111,13 @@ async function encodeParamValue(
   paramIndex: number,
   registry: CodecRegistry,
   ctx: SqlCodecCallContext,
+  contractCodecs: ContractCodecRegistry | undefined,
 ): Promise<unknown> {
   if (value === null || value === undefined) {
     return null;
   }
 
-  if (!metadata.codecId) {
-    return value;
-  }
-
-  const codec: Codec | undefined = registry.get(metadata.codecId);
+  const codec = resolveParamCodec(metadata, registry, contractCodecs);
   if (!codec) {
     return value;
   }
@@ -119,6 +152,7 @@ export async function encodeParams(
   plan: SqlExecutionPlan,
   registry: CodecRegistry,
   ctx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
 ): Promise<readonly unknown[]> {
   checkAborted(ctx, 'encode');
   const signal = ctx.signal;
@@ -142,7 +176,14 @@ export async function encodeParams(
 
   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, registry, ctx);
+    tasks[i] = encodeParamValue(
+      plan.params[i],
+      metadata[i] ?? NO_METADATA,
+      i,
+      registry,
+      ctx,
+      contractCodecs,
+    );
   }
 
   const settled = await raceAgainstAbort(Promise.all(tasks), signal, 'encode');

package/src/codecs/validation.ts

@@ -2,6 +2,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>();
@@ -30,15 +31,33 @@ function extractCodecIdsFromColumns(contract: Contract<SqlStorage>): Map<string,
   return codecIds;
 }
 
+interface CodecLookupForValidation {
+  has(id: string): boolean;
+}
+
+function adaptDescriptorRegistry(registry: CodecDescriptorRegistry): CodecLookupForValidation {
+  return { has: (id: string) => registry.descriptorFor(id) !== undefined };
+}
+
+function isDescriptorRegistry(
+  registry: CodecRegistry | CodecDescriptorRegistry,
+): registry is CodecDescriptorRegistry {
+  return 'descriptorFor' in registry;
+}
+
 export function validateContractCodecMappings(
-  registry: CodecRegistry,
+  registry: CodecRegistry | CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
+  const lookup: CodecLookupForValidation = isDescriptorRegistry(registry)
+    ? adaptDescriptorRegistry(registry)
+    : registry;
+
   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 (!lookup.has(codecId)) {
       const parts = key.split('.');
       const table = parts[0] ?? '';
       const column = parts[1] ?? '';
@@ -61,7 +80,7 @@ export function validateContractCodecMappings(
 }
 
 export function validateCodecRegistryCompleteness(
-  registry: CodecRegistry,
+  registry: CodecRegistry | CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
   validateContractCodecMappings(registry, contract);

package/src/sql-context.ts

@@ -1,4 +1,6 @@
 import type { Contract, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+import type { CodecDescriptor } from '@prisma-next/framework-components/codec';
+import { synthesizeNonParameterizedDescriptor } from '@prisma-next/framework-components/codec';
 import type { ComponentDescriptor } from '@prisma-next/framework-components/components';
 import { checkContractComponentRequirements } from '@prisma-next/framework-components/components';
 import {
@@ -14,7 +16,7 @@ import {
   type RuntimeTargetInstance,
 } from '@prisma-next/framework-components/execution';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import {
   createSqlOperationRegistry,
   type SqlOperationDescriptor,
@@ -22,39 +24,41 @@ import {
 import type {
   Adapter,
   AnyQueryAst,
-  CodecParamsDescriptor,
+  Codec,
   CodecRegistry,
+  ContractCodecRegistry,
   LoweredStatement,
+  SqlCodecInstanceContext,
   SqlDriver,
 } from '@prisma-next/sql-relational-core/ast';
 import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
 import type {
   AppliedMutationDefault,
+  CodecDescriptorRegistry,
   ExecutionContext,
   JsonSchemaValidateFn,
   JsonSchemaValidatorRegistry,
   MutationDefaultsOptions,
   TypeHelperRegistry,
 } from '@prisma-next/sql-relational-core/query-lane-context';
-import { type as arktype } from 'arktype';
 
 /**
  * Runtime parameterized codec descriptor.
- * Provides validation schema and optional init hook for codecs that support type parameters.
- * Used at runtime to validate typeParams and create type helpers.
  *
- * This is a type alias for `CodecParamsDescriptor` from the AST layer,
- * which is the shared definition used by both adapter and runtime.
+ * The unified `CodecDescriptor<P>` shape applied to parameterized codecs
+ * — `paramsSchema: StandardSchemaV1<P>` for JSON-boundary validation,
+ * `factory: (P) => (CodecInstanceContext) => Codec` for the curried higher-order codec.
+ * The factory is called once per `storage.types` instance (or once per
+ * inline-`typeParams` column); per-instance state lives in the closure.
+ *
+ * Codec-registry-unification spec § Decision.
  */
-export type RuntimeParameterizedCodecDescriptor<
-  TParams = Record<string, unknown>,
-  THelper = unknown,
-> = CodecParamsDescriptor<TParams, THelper>;
+export type RuntimeParameterizedCodecDescriptor<P = Record<string, unknown>> = CodecDescriptor<P>;
 
 export interface SqlStaticContributions {
   readonly codecs: () => CodecRegistry;
   // biome-ignore lint/suspicious/noExplicitAny: needed for covariance with concrete descriptor types
-  readonly parameterizedCodecs: () => ReadonlyArray<RuntimeParameterizedCodecDescriptor<any, any>>;
+  readonly parameterizedCodecs: () => ReadonlyArray<RuntimeParameterizedCodecDescriptor<any>>;
   readonly queryOperations?: () => ReadonlyArray<SqlOperationDescriptor>;
   readonly mutationDefaultGenerators?: () => ReadonlyArray<RuntimeMutationDefaultGenerator>;
 }
@@ -206,9 +210,16 @@ function validateTypeParams(
   codecDescriptor: RuntimeParameterizedCodecDescriptor,
   context: { typeName?: string; tableName?: string; columnName?: string },
 ): Record<string, unknown> {
-  const result = codecDescriptor.paramsSchema(typeParams);
-  if (result instanceof arktype.errors) {
-    const messages = result.map((p: { message: string }) => p.message).join('; ');
+  const result = codecDescriptor.paramsSchema['~standard'].validate(typeParams);
+  if (result instanceof Promise) {
+    throw runtimeError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
+      `paramsSchema for codec '${codecDescriptor.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`,
+      { ...context, codecId: codecDescriptor.codecId, typeParams },
+    );
+  }
+  if (result.issues) {
+    const messages = result.issues.map((issue) => issue.message).join('; ');
     const locationInfo = context.typeName
       ? `type '${context.typeName}'`
       : `column '${context.tableName}.${context.columnName}'`;
@@ -218,7 +229,7 @@ function validateTypeParams(
       { ...context, codecId: codecDescriptor.codecId, typeParams },
     );
   }
-  return result as Record<string, unknown>;
+  return result.value as Record<string, unknown>;
 }
 
 function collectParameterizedCodecDescriptors(
@@ -242,32 +253,116 @@ function collectParameterizedCodecDescriptors(
   return descriptors;
 }
 
+/**
+ * Build the unified descriptor map. Combines parameterized descriptors
+ * (which already ship as `CodecDescriptor`s) with synthesized descriptors
+ * for non-parameterized codecs registered through the legacy `codecs:`
+ * slot. Codec ids that ship a parameterized descriptor take precedence —
+ * even when the legacy registry registers a representative codec under
+ * the same id, the parameterized descriptor is the authoritative source.
+ *
+ * Codec-registry-unification spec § Decision: every codec resolves
+ * through one descriptor map; reads are non-branching.
+ */
+function buildCodecDescriptorRegistry(
+  codecRegistry: CodecRegistry,
+  parameterizedDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): CodecDescriptorRegistry {
+  type AnyDescriptor = CodecDescriptor<unknown>;
+  const byId = new Map<string, AnyDescriptor>();
+  const byTargetType = new Map<string, Array<AnyDescriptor>>();
+
+  function registerInIndices(descriptor: AnyDescriptor): void {
+    byId.set(descriptor.codecId, descriptor);
+    for (const targetType of descriptor.targetTypes) {
+      const list = byTargetType.get(targetType);
+      if (list) {
+        list.push(descriptor);
+      } else {
+        byTargetType.set(targetType, [descriptor]);
+      }
+    }
+  }
+
+  // The descriptor map is heterogeneous in `P` — each codec id has its own
+  // params shape. The public `CodecDescriptorRegistry` interface widens to
+  // `CodecDescriptor<unknown>` and consumers narrow per codec id at the
+  // call site (the descriptor's `paramsSchema` validates JSON-sourced
+  // params before the factory ever sees them, so the runtime narrow is
+  // safe). The cast at registration goes through `unknown` because
+  // `CodecDescriptor<P>` is invariant in `P` (the `factory` and
+  // `renderOutputType` slots use `P` contravariantly).
+  for (const descriptor of parameterizedDescriptors.values()) {
+    registerInIndices(descriptor as unknown as AnyDescriptor);
+  }
+
+  for (const codec of codecRegistry.values()) {
+    if (byId.has(codec.id)) continue;
+    registerInIndices(synthesizeNonParameterizedDescriptor(codec) as unknown as AnyDescriptor);
+  }
+
+  return {
+    descriptorFor(codecId: string): AnyDescriptor | undefined {
+      return byId.get(codecId);
+    },
+    *values(): IterableIterator<AnyDescriptor> {
+      yield* byId.values();
+    },
+    byTargetType(targetType: string): readonly AnyDescriptor[] {
+      return byTargetType.get(targetType) ?? Object.freeze([]);
+    },
+  };
+}
+
+function collectTypeRefSites(
+  storage: SqlStorage,
+): Map<string, Array<{ readonly table: string; readonly column: string }>> {
+  const sites = new Map<string, Array<{ readonly table: string; readonly column: string }>>();
+  for (const [tableName, table] of Object.entries(storage.tables)) {
+    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(
-  storageTypes: Record<string, StorageTypeInstance> | undefined,
+  storage: SqlStorage,
   codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
 ): TypeHelperRegistry {
   const helpers: TypeHelperRegistry = {};
+  const storageTypes = storage.types;
 
   if (!storageTypes) {
     return helpers;
   }
 
+  const typeRefSites = collectTypeRefSites(storage);
+
   for (const [typeName, typeInstance] of Object.entries(storageTypes)) {
     const descriptor = codecDescriptors.get(typeInstance.codecId);
 
-    if (descriptor) {
-      const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
-        typeName,
-      });
-
-      if (descriptor.init) {
-        helpers[typeName] = descriptor.init(validatedParams);
-      } else {
-        helpers[typeName] = typeInstance;
-      }
-    } else {
+    if (!descriptor) {
+      // No parameterized descriptor for this codec id — store the raw
+      // type instance for callers that need typeParams metadata.
       helpers[typeName] = typeInstance;
+      continue;
     }
+
+    const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
+      typeName,
+    });
+
+    const usedAt = typeRefSites.get(typeName) ?? [];
+    const ctx: SqlCodecInstanceContext = { name: typeName, usedAt };
+    helpers[typeName] = descriptor.factory(validatedParams)(ctx);
   }
 
   return helpers;
@@ -290,67 +385,217 @@ function validateColumnTypeParams(
 }
 
 /**
- * Builds a registry of compiled JSON Schema validators by scanning the contract
- * for columns whose codec descriptor provides an `init` hook returning `{ validate }`.
+ * View of a codec that exposes a per-instance JSON-schema `validate`
+ * function. Codecs declare this contract by including the
+ * `'json-validator'` `CodecTrait` in their `traits` array; the trait is
+ * the gate that lets `extractValidator` resolve from structurally-typed
+ * `unknown` to this typed view.
+ */
+type JsonValidatorCodec = {
+  readonly traits?: ReadonlyArray<unknown>;
+  readonly validate: JsonSchemaValidateFn;
+};
+
+function hasJsonValidatorTrait(candidate: unknown): candidate is JsonValidatorCodec {
+  if (candidate === null || typeof candidate !== 'object') return false;
+  const traits = (candidate as { readonly traits?: unknown }).traits;
+  if (!Array.isArray(traits)) return false;
+  if (!traits.includes('json-validator')) return false;
+  const validate = (candidate as { readonly validate?: unknown }).validate;
+  return typeof validate === 'function';
+}
+
+function extractValidator(candidate: unknown): JsonSchemaValidateFn | undefined {
+  return hasJsonValidatorTrait(candidate) ? candidate.validate : undefined;
+}
+
+function isResolvedCodec(candidate: unknown): candidate is Codec {
+  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:
+ *
+ * - **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.
  *
- * Handles both:
- * - Inline `typeParams.schema` on columns
- * - `typeRef` → `storage.types[ref]` with init hook results already in `types` registry
+ * Combines what `initializeTypeHelpers` (named-instance walk) and the
+ * old `buildJsonSchemaValidatorRegistry` (per-column walk) used to do
+ * separately: one walk over all columns, one resolved codec per column,
+ * one trait-gated validator extraction per column. The result drives
+ * both the dispatch registry (`ContractCodecRegistry.forColumn`) and the
+ * validator registry.
+ *
+ * Codec-registry-unification spec § AC-4: every column resolves through
+ * one descriptor map without branching on parameterization.
  */
-function buildJsonSchemaValidatorRegistry(
+function buildContractCodecRegistry(
   contract: Contract<SqlStorage>,
+  codecDescriptors: CodecDescriptorRegistry,
+  legacyCodecRegistry: CodecRegistry,
   types: TypeHelperRegistry,
-  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
-): JsonSchemaValidatorRegistry | undefined {
+  parameterizedDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): {
+  readonly registry: ContractCodecRegistry;
+  readonly jsonValidators: JsonSchemaValidatorRegistry | undefined;
+} {
+  const byColumn = new Map<string, Codec>();
+  const byCodecId = new Map<string, Codec>();
+  // Codec ids whose `byCodecId` entry is ambiguous — multiple distinct
+  // resolved instances landed under the same parameterized codec id (e.g.
+  // `Vector<1024>` and `Vector<1536>` both registering under
+  // `pg/vector@1`). The encode-side `forCodecId` fallback rejects these
+  // ids so a DSL-param without a column ref cannot silently bind to the
+  // wrong instance. Retires when AC-5's `ParamRef.refs` plumbing lands
+  // (TML-2357).
+  const ambiguousCodecIds = new Set<string>();
   const validators = new Map<string, JsonSchemaValidateFn>();
 
-  // Collect codec IDs that have init hooks (these produce { validate } helpers)
-  const codecIdsWithInit = new Set<string>();
-  for (const [codecId, descriptor] of codecDescriptors) {
-    if (descriptor.init) {
-      codecIdsWithInit.add(codecId);
-    }
-  }
-
-  if (codecIdsWithInit.size === 0) {
-    return undefined;
-  }
-
   for (const [tableName, table] of Object.entries(contract.storage.tables)) {
     for (const [columnName, column] of Object.entries(table.columns)) {
-      if (!codecIdsWithInit.has(column.codecId)) continue;
-
-      const key = `${tableName}.${columnName}`;
-
-      // Case 1: column references a named type → validator already compiled via init hook
-      if (column.typeRef) {
-        const helper = types[column.typeRef] as { validate?: JsonSchemaValidateFn } | undefined;
-        if (helper?.validate) {
-          validators.set(key, helper.validate);
+      const columnKey = `${tableName}.${columnName}`;
+      const descriptor = codecDescriptors.descriptorFor(column.codecId);
+
+      let resolvedCodec: Codec | undefined;
+
+      if (descriptor) {
+        const isParameterized = parameterizedDescriptors.has(column.codecId);
+
+        if (column.typeRef) {
+          // The named instance was already materialized once by
+          // `initializeTypeHelpers`; reuse it so multiple columns sharing
+          // the same typeRef share one codec instance (and any per-
+          // instance helper state on it).
+          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: SqlCodecInstanceContext = {
+              name: `<anon:${tableName}.${columnName}>`,
+              usedAt: [{ table: tableName, column: columnName }],
+            };
+            resolvedCodec = parameterizedDescriptor.factory(validatedParams)(ctx);
+          }
+        } else if (!isParameterized) {
+          // Non-parameterized column. Cache the resolved codec by codec
+          // id — the synthesized descriptor's factory is constant for
+          // non-parameterized codecs, so columns sharing this codec id
+          // share one resolved instance.
+          let cached = byCodecId.get(column.codecId);
+          if (!cached) {
+            const ctx: SqlCodecInstanceContext = {
+              name: `<shared:${column.codecId}>`,
+              usedAt: [{ table: tableName, column: columnName }],
+            };
+            // `synthesizeNonParameterizedDescriptor` produces a
+            // `CodecDescriptor<void>` whose factory ignores its params
+            // and ctx; the runtime's `void` value is `undefined`. The
+            // structural cast goes through `unknown` to satisfy the
+            // heterogeneous-`P` registry boundary (the factory's
+            // declared `P` is `any` here; the consumer narrows per
+            // codec id). The cast narrows the descriptor's
+            // family-agnostic `CodecInstanceContext` slot to the SQL
+            // `SqlCodecInstanceContext` we pass at this call site —
+            // function-argument contravariance makes the narrow safe
+            // (a callee that accepts the base will also accept the
+            // SQL extension). Per spec § Non-functional constraints.
+            const voidFactory = descriptor.factory as unknown as (
+              params: undefined,
+            ) => (ctx: SqlCodecInstanceContext) => Codec;
+            cached = voidFactory(undefined)(ctx);
+            byCodecId.set(column.codecId, cached);
+          }
+          resolvedCodec = cached;
         }
-        continue;
+        // else: parameterized codec id with no typeRef and no typeParams
+        // — this is the legitimate "undimensioned" form for codecs that
+        // ship a no-params column variant alongside a parameterized one
+        // (e.g. pgvector's `vectorColumn` vs. `vector(N)`). Leave
+        // `resolvedCodec` undefined; encode/decode for this column flows
+        // through `forCodecId` (the AC-5-deferred carve-out documented
+        // in `relational-core/src/ast/codec-types.ts`). The fallback
+        // works for these cases because their wire format is
+        // params-independent (vector formats `[v1,v2,...]` regardless
+        // of declared length).
       }
 
-      // Case 2: inline typeParams with schema → compile via init hook
-      if (column.typeParams) {
-        const descriptor = codecDescriptors.get(column.codecId);
-        if (descriptor?.init) {
-          const helper = descriptor.init(column.typeParams) as
-            | { validate?: JsonSchemaValidateFn }
-            | undefined;
-          if (helper?.validate) {
-            validators.set(key, helper.validate);
-          }
+      if (resolvedCodec) {
+        byColumn.set(columnKey, resolvedCodec);
+        const validate = extractValidator(resolvedCodec);
+        if (validate) {
+          validators.set(columnKey, validate);
+        }
+        const existing = byCodecId.get(column.codecId);
+        if (existing === undefined) {
+          byCodecId.set(column.codecId, resolvedCodec);
+        } else if (existing !== resolvedCodec && parameterizedDescriptors.has(column.codecId)) {
+          ambiguousCodecIds.add(column.codecId);
         }
       }
     }
   }
 
-  if (validators.size === 0) return undefined;
-  return {
-    get: (key: string) => validators.get(key),
-    size: validators.size,
+  const registry: ContractCodecRegistry = {
+    forColumn(table, column) {
+      return byColumn.get(`${table}.${column}`);
+    },
+    forCodecId(codecId) {
+      // Codec-id-only fallback for sites without a column ref (encode-
+      // side DSL params whose `ParamRef.refs` isn't populated). Prefer
+      // the contract-walk-derived shared codec; fall back to the legacy
+      // `codecRegistry.get` for parameterized codec ids whose contracts
+      // don't have a typeRef/typeParams column the walk could resolve
+      // through. The legacy fallback retires once `ParamRef.refs` is
+      // threaded everywhere (TML-2357).
+      //
+      // Reject ambiguous parameterized fallbacks: if the contract walk
+      // resolved more than one distinct codec instance under this id
+      // (e.g. multiple vector dimensions, multiple arktype-json
+      // schemas), the codec-id-keyed lookup cannot honor the call site
+      // — fail fast rather than bind to whichever instance happened to
+      // land first.
+      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) ?? legacyCodecRegistry.get(codecId);
+    },
   };
+
+  const jsonValidators: JsonSchemaValidatorRegistry | undefined =
+    validators.size > 0
+      ? {
+          get: (key: string) => validators.get(key),
+          size: validators.size,
+        }
+      : undefined;
+
+  return { registry, jsonValidators };
 }
 
 function collectMutationDefaultGenerators(
@@ -476,23 +721,32 @@ export function createExecutionContext<
   }
 
   const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(contributors);
+  const codecDescriptors = buildCodecDescriptorRegistry(
+    codecRegistry,
+    parameterizedCodecDescriptors,
+  );
   const mutationDefaultGeneratorRegistry = collectMutationDefaultGenerators(contributors);
 
   if (parameterizedCodecDescriptors.size > 0) {
     validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
   }
 
-  const types = initializeTypeHelpers(contract.storage.types, parameterizedCodecDescriptors);
+  const types = initializeTypeHelpers(contract.storage, parameterizedCodecDescriptors);
 
-  const jsonSchemaValidators = buildJsonSchemaValidatorRegistry(
-    contract,
-    types,
-    parameterizedCodecDescriptors,
-  );
+  const { registry: contractCodecs, jsonValidators: jsonSchemaValidators } =
+    buildContractCodecRegistry(
+      contract,
+      codecDescriptors,
+      codecRegistry,
+      types,
+      parameterizedCodecDescriptors,
+    );
 
   return {
     contract,
     codecs: codecRegistry,
+    contractCodecs,
+    codecDescriptors,
     queryOperations: queryOperationRegistry,
     types,
     ...(jsonSchemaValidators ? { jsonSchemaValidators } : {}),