@prisma-next/framework-components 0.5.0-dev.60 → 0.5.0-dev.61

package/src/control/control-stack.ts

@@ -1,4 +1,5 @@
-import type { CodecLookup } from '../shared/codec-types';
+import type { Codec } from '../shared/codec';
+import type { CodecLookup, CodecMeta } from '../shared/codec-types';
 import type {
   AuthoringContributions,
   AuthoringFieldNamespace,
@@ -270,27 +271,65 @@ export function assembleControlMutationDefaults(
 }
 
 export function extractCodecLookup(
-  descriptors: ReadonlyArray<Pick<ComponentMetadata & { id?: string }, 'types' | 'id'>>,
+  descriptors: ReadonlyArray<Pick<ComponentMetadata & { id: string }, 'types' | 'id'>>,
 ): CodecLookup {
-  const byId = new Map<string, import('../shared/codec-types').Codec>();
+  const byId = new Map<string, Codec>();
+  const targetTypesById = new Map<string, readonly string[]>();
+  const metaById = new Map<string, CodecMeta>();
+  const renderersById = new Map<string, (params: Record<string, unknown>) => string | undefined>();
   const owners = new Map<string, string>();
   for (const descriptor of descriptors) {
-    const codecInstances = descriptor.types?.codecTypes?.codecInstances;
-    if (!codecInstances) continue;
-    const descriptorId = descriptor.id ?? '<unknown>';
-    for (const codec of codecInstances) {
+    const codecTypes = descriptor.types?.codecTypes;
+    const descriptorId = descriptor.id;
+    // Descriptor-side metadata is the single source of truth for `targetTypes` / `meta` / `renderOutputType`. Every contributor ships a `codecDescriptors` list on `types.codecTypes`.
+    for (const codecDescriptor of codecTypes?.codecDescriptors ?? []) {
       assertUniqueCodecOwner({
-        codecId: codec.id,
+        codecId: codecDescriptor.codecId,
         owners,
         descriptorId,
-        entityLabel: 'codec instance',
-        entityOwnershipLabel: 'codec instance provider',
+        entityLabel: 'codec descriptor',
+        entityOwnershipLabel: 'codec descriptor provider',
       });
-      owners.set(codec.id, descriptorId);
-      byId.set(codec.id, codec);
+      owners.set(codecDescriptor.codecId, descriptorId);
+      if (Array.isArray(codecDescriptor.targetTypes)) {
+        targetTypesById.set(codecDescriptor.codecId, codecDescriptor.targetTypes);
+      }
+      if (codecDescriptor.meta !== undefined) {
+        metaById.set(codecDescriptor.codecId, codecDescriptor.meta);
+      }
+      if (typeof codecDescriptor.renderOutputType === 'function') {
+        renderersById.set(codecDescriptor.codecId, codecDescriptor.renderOutputType);
+      }
+      // Materialize a representative `Codec` instance for `byId.get()` so consumers reading the lookup's instance side (e.g. SQL renderer's cast-policy lookup, or the contract emitter's literal-default `encodeJson` resolver) keep finding the codec.
+      //
+      // Two cohorts:
+      // - Non-parameterized descriptors: factory must succeed; any throw is a real bug and we let it propagate (no silent try/catch).
+      // - Parameterized descriptors: try with empty params. Many parameterized codecs treat params as advisory (e.g. `pg/timestamptz@1` whose precision is rendered into the `nativeType` only and never read by the runtime codec), so an empty-params construction yields a usable representative for id-keyed lookups (e.g. emit-time literal-default encoding). Codecs whose factory genuinely requires params (e.g. `pg/vector@1` threading `length` into the runtime codec) will throw; for those, per-column instances are materialized at runtime by `buildContractCodecRegistry` and the id-keyed lookup miss is correct (the column-aware path resolves them).
+      if (!byId.has(codecDescriptor.codecId)) {
+        if (codecDescriptor.isParameterized) {
+          try {
+            const representative = codecDescriptor.factory({} as never)({
+              name: `<lookup:${codecDescriptor.codecId}>`,
+            } as Parameters<ReturnType<typeof codecDescriptor.factory>>[0]);
+            byId.set(codecDescriptor.codecId, representative);
+          } catch {
+            // Factory requires concrete params; skip representative materialization. Per-column instances are built at runtime; id-keyed lookup miss is the correct outcome here.
+          }
+        } else {
+          const representative = codecDescriptor.factory(undefined as never)({
+            name: `<lookup:${codecDescriptor.codecId}>`,
+          } as Parameters<ReturnType<typeof codecDescriptor.factory>>[0]);
+          byId.set(codecDescriptor.codecId, representative);
+        }
+      }
     }
   }
-  return { get: (id) => byId.get(id) };
+  return {
+    get: (id) => byId.get(id),
+    targetTypesFor: (id) => targetTypesById.get(id),
+    metaFor: (id) => metaById.get(id),
+    renderOutputTypeFor: (id, params) => renderersById.get(id)?.(params),
+  };
 }
 
 export function validateScalarTypeCodecIds(

package/src/exports/codec.ts

@@ -1,14 +1,27 @@
+/**
+ * Codec model: interfaces (consumer surface) plus abstract `Impl` classes (codec-author surface) plus the column packager.
+ *
+ * Consumers depend on the interfaces: {@link Codec}, {@link CodecDescriptor}, {@link AnyCodecDescriptor}, {@link ColumnSpec}, {@link ColumnTypeDescriptor}.
+ *
+ * Codec authors `extend` the abstract bases: {@link CodecImpl} and {@link CodecDescriptorImpl}. They write a per-codec column helper that calls `descriptor.factory(...)` directly and tie the helper to its descriptor with `satisfies ColumnHelperFor<D>` (or `ColumnHelperForStrict<D>`).
+ */
+
+export type { Codec } from '../shared/codec';
+export { CodecImpl } from '../shared/codec';
+export type { AnyCodecDescriptor, CodecDescriptor } from '../shared/codec-descriptor';
+export { CodecDescriptorImpl } from '../shared/codec-descriptor';
 export type {
-  Codec,
   CodecCallContext,
-  CodecDescriptor,
   CodecInstanceContext,
   CodecLookup,
   CodecMeta,
   CodecTrait,
 } from '../shared/codec-types';
-export {
-  emptyCodecLookup,
-  synthesizeNonParameterizedDescriptor,
-  voidParamsSchema,
-} from '../shared/codec-types';
+export { emptyCodecLookup, voidParamsSchema } from '../shared/codec-types';
+export type {
+  ColumnHelperFor,
+  ColumnHelperForStrict,
+  ColumnSpec,
+  ColumnTypeDescriptor,
+} from '../shared/column-spec';
+export { column } from '../shared/column-spec';

package/src/shared/codec-descriptor.ts

@@ -0,0 +1,87 @@
+/**
+ * Codec descriptor interface (consumer surface) and abstract `CodecDescriptorImpl` base (codec-author surface).
+ *
+ * Consumers depend on the {@link CodecDescriptor} interface — it is the codec-id-keyed source of truth for static metadata (`traits`, `targetTypes`, `meta`) and registration concerns (`paramsSchema`; optional `renderOutputType`). The runtime `Codec` instance returned by `factory(params)(ctx)` carries only the conversion behavior.
+ *
+ * Codec authors `extend` the {@link CodecDescriptorImpl} abstract class to declare their codec id, traits, target types, params schema, the `factory(params)` that materializes a typed `Codec<...>`, and (optionally) a `renderOutputType(params)` for the emit path.
+ *
+ * The factory's method-level generic is the load-bearing piece for literal preservation: per-codec column helpers invoke `descriptor.factory(...)` *directly*, and the direct call binds the generic at its call site. Type extraction (`ReturnType<D['factory']>`, structural matching) widens method generics to their constraint — that's why the column-helper surface is per-codec, not polymorphic.
+ */
+
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Codec } from './codec';
+import {
+  type CodecInstanceContext,
+  type CodecMeta,
+  type CodecTrait,
+  voidParamsSchema,
+} from './codec-types';
+
+/**
+ * Unified codec descriptor. Every codec in the framework registers through this shape — non-parameterized codecs use `P = void` and a constant factory that returns the same shared codec instance for every column; parameterized codecs use a non-empty `P` and a curried higher-order factory that returns a per-instance codec.
+ *
+ * The descriptor is the codec-id-keyed source of truth for static metadata (`traits`, `targetTypes`, `meta`) and registration concerns (`paramsSchema` for JSON-boundary validation; optional `renderOutputType` for the `contract.d.ts` emit path). The runtime `Codec` instance returned by `factory(params)(ctx)` carries only the conversion behavior.
+ *
+ * Whether a codec id "is parameterized" stops being a registration-time distinction — it's a property of `P` on the descriptor. The descriptor map indexes every descriptor by `codecId`; both `descriptorFor(codecId)` and `forColumn(table, column)` resolve through the same map without branching on parameterization.
+ *
+ * @template P - The shape of the params accepted by the factory (`void` for non-parameterized codecs; a record like `{ length: number }` for parameterized codecs).
+ *
+ * Codec-registry-unification project § Decision.
+ */
+export interface CodecDescriptor<P = void> {
+  /** The codec ID this descriptor applies to (e.g. `pg/vector@1`, `pg/text@1`). */
+  readonly codecId: string;
+  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
+  readonly traits: readonly CodecTrait[];
+  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
+  readonly targetTypes: readonly string[];
+  /** Optional family-specific metadata (e.g. SQL-side `db.sql.postgres.nativeType`). */
+  readonly meta?: CodecMeta;
+  /** Standard Schema validator for the factory's params. Validates JSON-sourced params at the contract boundary (PSL → IR; `contract.json` → runtime). For non-parameterized codecs (`P = void`), the schema validates `void`/`undefined` — the framework supplies no params at the call boundary. */
+  readonly paramsSchema: StandardSchemaV1<P>;
+  /** Whether this descriptor is parameterized — i.e. its `paramsSchema` is something other than the singleton `voidParamsSchema`. Consumers that need to gate column-aware dispatch (e.g. the `validateParamRefRefs` AST-builder pass) read this directly rather than threading a free-floating `(codecId) => boolean` callback. */
+  readonly isParameterized: boolean;
+  /** Emit-path string renderer for `contract.d.ts`. Returns the TypeScript output type expression for given params (e.g. `Vector<1536>`). Optional; absent renderers cause the emitter to fall back to the codec's base output type. Non-parameterized codecs typically omit it. */
+  readonly renderOutputType?: (params: P) => string | undefined;
+  /** The curried higher-order codec. For non-parameterized codecs, the factory is constant — every call returns the same shared codec instance. For parameterized codecs, the factory is called once per `storage.types` instance (or once per inline-`typeParams` column), with `ctx` carrying the column set the resulting codec serves. */
+  readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;
+}
+
+/**
+ * Variance-erased {@link CodecDescriptor} alias. `CodecDescriptor<P>` is invariant in `P` (the `factory` and `renderOutputType` slots use `P` contravariantly), so `CodecDescriptor<P>` does not extend `CodecDescriptor<unknown>` for specific `P`. Heterogeneous descriptor collections — e.g. `SqlStaticContributions.codecs:` returning a list that mixes parameterized and non-parameterized descriptors — type against this alias and narrow per codec id at the consumer.
+ *
+ * Codec-registry-unification spec § Decision: every codec resolves through one descriptor map; reads are non-branching.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: variance erasure for heterogeneous descriptor collections
+export type AnyCodecDescriptor = CodecDescriptor<any>;
+
+/**
+ * Abstract base class for concrete codec descriptors.
+ *
+ * Codec authors extend this class with their typed `TParams` and declare `codecId`, `traits`, `targetTypes`, `paramsSchema`, the curried `factory(params)`, and (optionally) `renderOutputType`.
+ *
+ * Implements the {@link CodecDescriptor} interface so a concrete subclass instance is directly usable wherever the framework expects a `CodecDescriptor<P>`.
+ */
+export abstract class CodecDescriptorImpl<TParams = void> implements CodecDescriptor<TParams> {
+  abstract readonly codecId: string;
+  abstract readonly traits: readonly CodecTrait[];
+  abstract readonly targetTypes: readonly string[];
+  readonly meta?: CodecMeta;
+
+  abstract readonly paramsSchema: StandardSchemaV1<TParams>;
+
+  /** Boolean derived from `paramsSchema`: `true` whenever the schema is not the singleton `voidParamsSchema`. The framework registry's `validateParamRefRefs` pass reads this through `descriptorFor(codecId).isParameterized` to gate column-ref enforcement. */
+  get isParameterized(): boolean {
+    return this.paramsSchema !== voidParamsSchema;
+  }
+
+  /** Optional emit-path string renderer for `contract.d.ts`. Returns the TypeScript output type expression for the given params (e.g. `Vector<1536>`). Non-parameterized codecs typically omit it. */
+  renderOutputType?(params: TParams): string | undefined;
+
+  /**
+   * Materialize a curried codec factory for the given params. Concrete subclasses override with a typed return type (e.g. `factory<N>(params: { length: N }): (ctx) => VectorCodec<N>`); per-codec helpers read the typed return at the *direct* call site, which is what preserves method-level generics. Type extraction (e.g. `ReturnType<D['factory']>`) widens method generics to their constraint — that's why the column-helper surface is per-codec, not polymorphic.
+   */
+  abstract factory(
+    params: TParams,
+  ): (ctx: CodecInstanceContext) => Codec<string, readonly CodecTrait[], unknown, unknown>;
+}

package/src/shared/codec-types.ts

@@ -1,212 +1,65 @@
-import type { JsonValue } from '@prisma-next/contract/types';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Codec } from './codec';
 
-export type CodecTrait =
-  | 'equality'
-  | 'order'
-  | 'boolean'
-  | 'numeric'
-  | 'textual'
-  /**
-   * The codec carries a per-instance `validate(value: unknown) =>
-   * JsonSchemaValidationResult` function on the resolved codec object that
-   * the framework's `JsonSchemaValidatorRegistry` consults at runtime. The
-   * trait gates the `extractValidator` cast from structurally-typed
-   * `unknown` to a typed validator view.
-   *
-   * Retirement target. The unified `CodecDescriptor` model moves
-   * validation into the resolved codec's `decode` body; the parallel
-   * `JsonSchemaValidatorRegistry` (and this trait alongside it) retires
-   * under TML-2357 (T3.5.12). Per-library JSON extensions like
-   * `@prisma-next/extension-arktype-json` already follow the new pattern.
-   */
-  | 'json-validator';
+export type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';
 
 /**
- * Per-call context the runtime threads to every `codec.encode` /
- * `codec.decode` invocation for a single `runtime.execute()` call.
+ * Per-call context the runtime threads to every `codec.encode` / `codec.decode` invocation for a single `runtime.execute()` call.
  *
  * The framework-level shape is family-agnostic and carries one field:
  *
- * - `signal?: AbortSignal` — per-query cancellation. The runtime returns
- *   a `RUNTIME.ABORTED` envelope when the signal aborts; codec authors
- *   who forward `signal` to their underlying SDK get true cancellation
- *   of in-flight network calls.
+ * - `signal?: AbortSignal` — per-query cancellation. The runtime returns a `RUNTIME.ABORTED` envelope when the signal aborts; codec authors who forward `signal` to their underlying SDK get true cancellation of in-flight network calls.
  *
- * Family layers extend this base with their own shape-of-call metadata:
- * the SQL family adds `column?: SqlColumnRef` via `SqlCodecCallContext`
- * (see `@prisma-next/sql-relational-core`). Mongo currently uses this
- * framework type unchanged. Column metadata is intentionally **not** on
- * the framework type — it is a SQL-family concept rooted in SQL's
- * `(table, column)` addressing model and would not generalise to other
- * families.
+ * Family layers extend this base with their own shape-of-call metadata: the SQL family adds `column?: SqlColumnRef` via `SqlCodecCallContext` (see `@prisma-next/sql-relational-core`). Mongo currently uses this framework type unchanged. Column metadata is intentionally **not** on the framework type — it is a SQL-family concept rooted in SQL's `(table, column)` addressing model and would not generalise to other families.
  *
- * The interface is named explicitly (not inlined) so future framework
- * fields and family extensions can land additively without breaking
- * codec author signatures.
+ * The interface is named explicitly (not inlined) so future framework fields and family extensions can land additively without breaking codec author signatures.
  */
 export interface CodecCallContext {
   readonly signal?: AbortSignal;
 }
 
 /**
- * A codec is the contract between an application value and its on-wire and
- * on-contract-disk representations.
+ * Codec-id-keyed read surface threaded into emit and authoring paths.
  *
- * The author's mental model is two JS-side types — `TInput` (the
- * application JS type) and `TWire` (the database driver wire format) —
- * plus `JsonValue` for build-time contract artifacts. The codec translates
- * `TInput` to `TWire` on writes and back on reads, and to/from `JsonValue`
- * during contract emission and loading.
- *
- * Three representations participate:
- * - **Input** (`TInput`): the JS type at the application boundary.
- * - **Wire** (`TWire`): the format exchanged with the database driver.
- * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.
- *
- * Codec methods split into two groups:
- *
- * - **Query-time** methods (`encode`, `decode`) run per row/parameter at the
- *   IO boundary; they are required and Promise-returning. The per-family
- *   codec factory accepts sync or async author functions and lifts sync
- *   ones to Promise-shaped methods automatically.
- * - **Build-time** methods (`encodeJson`, `decodeJson`, `renderOutputType`)
- *   run when the contract is serialized, loaded, or when client types are
- *   emitted. They stay synchronous so contract validation and client
- *   construction are synchronous.
- *
- * Target-family codec interfaces extend this base with target-shaped
- * metadata.
+ * - `get(id)` returns the runtime {@link Codec} instance for the codec id (used by `validateContract` for `decodeJson` of literal column defaults).
+ * - `targetTypesFor(id)` exposes the codec-id-keyed `targetTypes` metadata the runtime instance no longer carries (TML-2357). Returns the same array `CodecDescriptor.targetTypes` would; for Mongo (whose registration doesn't yet resolve through the unified descriptor map — TML-2324) the family-side assembly populates this directly from the contributor's codec metadata.
+ * - `metaFor(id)` exposes the codec-id-keyed `meta` (e.g. SQL-side `db.sql.postgres.nativeType`) the runtime instance no longer carries.
+ * - `renderOutputTypeFor(id, params)` exposes the codec-id-keyed `renderOutputType` renderer the runtime instance no longer carries. Returns `undefined` when the codec doesn't render a custom type or when the codec id is unknown.
  */
-export interface Codec<
-  Id extends string = string,
-  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
-  TWire = unknown,
-  TInput = unknown,
-> {
-  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
-  readonly id: Id;
-  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
-  readonly targetTypes: readonly string[];
-  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
-  readonly traits?: TTraits;
-  /** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(value) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
-  encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;
-  /** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(wire) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
-  decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;
-  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */
-  encodeJson(value: TInput): JsonValue;
-  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */
-  decodeJson(json: JsonValue): TInput;
-  /** Produces the TypeScript output type expression for a field given its `typeParams`. Synchronous; used during contract.d.ts emission. */
-  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
-}
-
 export interface CodecLookup {
   get(id: string): Codec | undefined;
+  targetTypesFor(id: string): readonly string[] | undefined;
+  metaFor(id: string): CodecMeta | undefined;
+  renderOutputTypeFor(id: string, params: Record<string, unknown>): string | undefined;
 }
 
 export const emptyCodecLookup: CodecLookup = {
   get: () => undefined,
+  targetTypesFor: () => undefined,
+  metaFor: () => undefined,
+  renderOutputTypeFor: () => undefined,
 };
 
 /**
- * Family-agnostic per-instance context supplied by the framework when
- * applying a higher-order codec factory. Allows stateful codecs (e.g.
- * column-scoped encryption) to derive per-instance state from the
- * materialization site.
+ * Family-agnostic per-instance context supplied by the framework when applying a higher-order codec factory. Allows stateful codecs (e.g. column-scoped encryption) to derive per-instance state from the materialization site.
  *
- * - `name` — the family-agnostic instance identity. For SQL, the runtime
- *   populates this as the `storage.types` instance name (e.g.
- *   `Embedding1536`) for typeRef-shaped columns, the synthesized
- *   anonymous instance name (`<anon:Document.embedding>`) for inline-
- *   `typeParams` columns, or a shared sentinel (`<shared:pg/text@1>`)
- *   for non-parameterized codec ids. Other families pick the analogous
- *   identity for their materialization sites.
+ * - `name` — the family-agnostic instance identity. For SQL, the runtime populates this as the `storage.types` instance name (e.g. `Embedding1536`) for typeRef-shaped columns, the synthesized anonymous instance name (`<anon:Document.embedding>`) for inline-`typeParams` columns, or a shared sentinel (`<shared:pg/text@1>`) for non-parameterized codec ids. Other families pick the analogous identity for their materialization sites.
  *
- * Family-specific extensions (e.g. {@link import('@prisma-next/sql-relational-core/ast').SqlCodecInstanceContext}
- * in the SQL layer) augment this base with domain-shaped column-set
- * metadata. Codec authors target the base when they don't read family-
- * specific metadata; they target the family extension when they do.
+ * Family-specific extensions (e.g. {@link import('@prisma-next/sql-relational-core/ast').SqlCodecInstanceContext} in the SQL layer) augment this base with domain-shaped column-set metadata. Codec authors target the base when they don't read family-specific metadata; they target the family extension when they do.
  */
 export interface CodecInstanceContext {
   readonly name: string;
 }
 
 /**
- * Family-agnostic codec metadata. Family-specific extensions augment the
- * base `db.<family>.<target>` block with native-type information; the base
- * shape is an empty object so non-relational codecs can carry no metadata.
+ * Family-agnostic codec metadata. Family-specific extensions augment the base `db.<family>.<target>` block with native-type information; the base shape is an empty object so non-relational codecs can carry no metadata.
  */
 export interface CodecMeta {
   readonly db?: Record<string, unknown>;
 }
 
 /**
- * Unified codec descriptor. Every codec in the framework registers through
- * this shape — non-parameterized codecs use `P = void` and a constant
- * factory that returns the same shared codec instance for every column;
- * parameterized codecs use a non-empty `P` and a curried higher-order
- * factory that returns a per-instance codec.
- *
- * The descriptor is the codec-id-keyed source of truth for static metadata
- * (`traits`, `targetTypes`, `meta`) and registration concerns
- * (`paramsSchema` for JSON-boundary validation; optional `renderOutputType`
- * for the `contract.d.ts` emit path). The runtime `Codec` instance returned
- * by `factory(params)(ctx)` carries only the conversion behavior.
- *
- * Whether a codec id "is parameterized" stops being a registration-time
- * distinction — it's a property of `P` on the descriptor. The descriptor
- * map indexes every descriptor by `codecId`; both `descriptorFor(codecId)`
- * and `forColumn(table, column)` resolve through the same map without
- * branching on parameterization.
- *
- * @template P - The shape of the params accepted by the factory (`void` for
- *   non-parameterized codecs; a record like `{ length: number }` for
- *   parameterized codecs).
- *
- * Codec-registry-unification project § Decision.
- */
-export interface CodecDescriptor<P = void> {
-  /** The codec ID this descriptor applies to (e.g. `pg/vector@1`, `pg/text@1`). */
-  readonly codecId: string;
-  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
-  readonly traits: readonly CodecTrait[];
-  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
-  readonly targetTypes: readonly string[];
-  /** Optional family-specific metadata (e.g. SQL-side `db.sql.postgres.nativeType`). */
-  readonly meta?: CodecMeta;
-  /**
-   * Standard Schema validator for the factory's params. Validates JSON-
-   * sourced params at the contract boundary (PSL → IR; `contract.json` →
-   * runtime). For non-parameterized codecs (`P = void`), the schema
-   * validates `void`/`undefined` — the framework supplies no params at the
-   * call boundary.
-   */
-  readonly paramsSchema: StandardSchemaV1<P>;
-  /**
-   * Emit-path string renderer for `contract.d.ts`. Returns the TypeScript
-   * output type expression for given params (e.g. `Vector<1536>`).
-   * Optional; absent renderers cause the emitter to fall back to the
-   * codec's base output type. Non-parameterized codecs typically omit it.
-   */
-  readonly renderOutputType?: (params: P) => string | undefined;
-  /**
-   * The curried higher-order codec. For non-parameterized codecs, the
-   * factory is constant — every call returns the same shared codec
-   * instance. For parameterized codecs, the factory is called once per
-   * `storage.types` instance (or once per inline-`typeParams` column),
-   * with `ctx` carrying the column set the resulting codec serves.
-   */
-  readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;
-}
-
-/**
- * Standard Schema validator for `void` params. Accepts only `undefined`
- * (or absent input); rejects any other value so a contract that tries to
- * thread `typeParams` through a non-parameterized codec id fails fast at
- * the JSON boundary instead of silently coercing the value away. Used by
- * the framework-supplied non-parameterized descriptor synthesizer.
+ * Standard Schema validator for `void` params. Accepts only `undefined` (or absent input); rejects any other value so a contract that tries to thread `typeParams` through a non-parameterized codec id fails fast at the JSON boundary instead of silently coercing the value away. Used by the framework-supplied non-parameterized descriptor synthesizer.
  */
 export const voidParamsSchema: StandardSchemaV1<void> = {
   '~standard': {
@@ -224,38 +77,3 @@ export const voidParamsSchema: StandardSchemaV1<void> = {
           },
   },
 };
-
-/**
- * Synthesize a `CodecDescriptor<void>` for a non-parameterized codec
- * runtime instance. The factory is constant — every call returns the same
- * shared codec instance — so columns sharing this codec id share one
- * resolved codec.
- *
- * Codec-registry-unification spec § Decision (Case T — non-parameterized
- * text codec). This is the bridge while non-parameterized codec
- * contributors still register through the legacy `codecs:` slot; once they
- * migrate to ship descriptors directly (TML-2357 T3.5.3), this synthesis
- * steps aside.
- */
-export function synthesizeNonParameterizedDescriptor(codec: Codec): CodecDescriptor<void> {
-  // The descriptor's `factory: (params: void) => (ctx: CodecInstanceContext)
-  // => Codec` is a constant for non-parameterized codecs — `params` is
-  // never read and the returned ctx-applier always yields the same shared
-  // codec. We rely on the descriptor's typed `factory` slot to infer the
-  // signatures rather than naming `void` locally (biome's
-  // `noConfusingVoidType` flags `void` outside return positions).
-  const sharedFactory = () => () => codec;
-  // Family-extended codecs (SQL `Codec`) carry an optional `meta` field
-  // that the base interface doesn't declare. Read it through a structural
-  // narrow so the synthesizer forwards it to the descriptor without losing
-  // type safety on the base shape.
-  const codecMeta = (codec as { readonly meta?: CodecMeta }).meta;
-  return {
-    codecId: codec.id,
-    traits: codec.traits ?? [],
-    targetTypes: codec.targetTypes,
-    paramsSchema: voidParamsSchema,
-    factory: sharedFactory,
-    ...(codecMeta !== undefined ? { meta: codecMeta } : {}),
-  };
-}

package/src/shared/codec.ts

@@ -0,0 +1,80 @@
+/**
+ * Codec interface (consumer surface) and abstract `CodecImpl` base (codec-author surface).
+ *
+ * Consumers depend on the {@link Codec} interface — it describes the runtime instance returned by a descriptor's curried factory and is what the framework threads through emit, validate, and execute paths.
+ *
+ * Codec authors `extend` the {@link CodecImpl} abstract class to declare a typed runtime codec instance. The class carries a variance-erased descriptor reference (`CodecDescriptor<any>`); `id` proxies through the descriptor so one source of truth governs both metadata reads and aliasing semantics (alias subclasses inherit the descriptor's id automatically).
+ *
+ * Class generic shape: `Id`, `TTraits`, `TWire`, `TInput`. Method generics on the codec subclass's own surface (e.g. arktype-json's schema generic, pgvector's dimension generic) flow through the subclass's constructor and propagate via the descriptor's typed `factory(params)` return at *direct* call sites.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+import type { CodecDescriptor } from './codec-descriptor';
+import type { CodecCallContext, CodecTrait } from './codec-types';
+
+/**
+ * A codec is the contract between an application value and its on-wire and on-contract-disk representations.
+ *
+ * The author's mental model is two JS-side types — `TInput` (the application JS type) and `TWire` (the database driver wire format) — plus `JsonValue` for build-time contract artifacts. The codec translates `TInput` to `TWire` on writes and back on reads, and to/from `JsonValue` during contract emission and loading.
+ *
+ * Three representations participate:
+ * - **Input** (`TInput`): the JS type at the application boundary.
+ * - **Wire** (`TWire`): the format exchanged with the database driver.
+ * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.
+ *
+ * The runtime instance carries only its `id` (the descriptor's `codecId`, set by the factory) and the four conversion methods. Static metadata (`traits`, `targetTypes`, `meta`) and the build-time `renderOutputType` renderer live on the {@link CodecDescriptor} keyed by `codecId` — the read-surface single source of truth. Consumers that need them resolve through `descriptorFor(codecId)`.
+ *
+ * Codec methods split into two groups:
+ *
+ * - **Query-time** methods (`encode`, `decode`) run per row/parameter at the IO boundary; they are required and Promise-returning. The per-family codec factory accepts sync or async author functions and lifts sync ones to Promise-shaped methods automatically.
+ * - **Build-time** methods (`encodeJson`, `decodeJson`) run when the contract is serialized or loaded. They stay synchronous so contract validation and client construction are synchronous.
+ *
+ * Target-family codec interfaces extend this base; family-specific concerns (e.g. the SQL `column?` per-call context) layer on through the `CodecCallContext` extension pattern.
+ */
+export interface Codec<
+  Id extends string = string,
+  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
+  TWire = unknown,
+  TInput = unknown,
+> {
+  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). The factory sets this to the descriptor's `codecId`; consumers use it as a back-reference for descriptor lookups and for decode-error diagnostics. */
+  readonly id: Id;
+  /** Phantom carrier for the `TTraits` generic; type-only, undefined at runtime. Runtime traits live on {@link CodecDescriptor.traits}. Implemented as a string-key phantom (`__codecTraits`) rather than `unique symbol` so bundlers that split `.d.ts` chunks do not strand symbol identity on chunk-private paths (the same `TS2742` family that the public re-export of `CodecTypes` works around). */
+  readonly __codecTraits?: TTraits;
+  /** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(value) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
+  encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;
+  /** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(wire) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
+  decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;
+  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */
+  encodeJson(value: TInput): JsonValue;
+  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */
+  decodeJson(json: JsonValue): TInput;
+}
+
+/**
+ * Abstract base class for concrete codec implementations.
+ *
+ * Codec authors extend this class with their typed `Id`, `TTraits`, `TWire`, `TInput` and override `encode`/`decode` (and optionally `encodeJson`/`decodeJson`). The runtime instance carries only its `id` (proxied through the descriptor so alias subclasses inherit the descriptor's id automatically) and the conversion methods — static metadata lives on the {@link CodecDescriptor}.
+ */
+export abstract class CodecImpl<
+  Id extends string = string,
+  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
+  TWire = unknown,
+  TInput = unknown,
+> implements Codec<Id, TTraits, TWire, TInput>
+{
+  /**
+   * Variance-erased descriptor reference. Concrete codec subclasses receive the typed descriptor in their own constructors and forward it via `super(descriptor)`; the variance erasure lives at this base because the abstract surface can't carry the concrete `TParams`.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: variance-erased descriptor reference; subclasses retain typed access via their own state
+  constructor(public readonly descriptor: CodecDescriptor<any>) {}
+
+  get id(): Id {
+    return this.descriptor.codecId as Id;
+  }
+
+  abstract encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;
+  abstract decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;
+  abstract encodeJson(value: TInput): JsonValue;
+  abstract decodeJson(json: JsonValue): TInput;
+}