@prisma-next/extension-arktype-json 0.5.0-dev.59 → 0.5.0-dev.61

package/src/core/arktype-json-codec.ts

@@ -1,395 +1,167 @@
 /**
- * Single source of truth for the arktype-json `arktype/json@1` codec.
+ * Arktype-json codec (TML-2357).
  *
- * Ships the per-library JSON-with-schema column factory (`arktypeJson`) and
- * the framework-registration descriptor (`arktypeJsonCodec`). The two
- * surfaces share one serialize/rehydrate pipeline keyed on arktype's
- * internal IR.
+ * Spec § Case 3: method-level generic over `S extends Type<unknown>`. The schema's TypeScript-level inferred type `S['infer']` is only available at the column-author site (where the user passes their typed schema), not at the descriptor's factory site (where only the serialized IR is available). This drives the shape:
  *
- * **Serialization** (column-author site, eager):
+ * 1. {@link ArktypeJsonCodecClass} extends {@link CodecImpl} and is generic over `TInferred` — the application-level JS type the schema validates to. The constructor takes both the descriptor (for `id` proxy) and the rehydrated arktype `Type` (closure-captured so encode/decode/encodeJson/decodeJson can validate through it). 2. {@link ArktypeJsonDescriptor} extends {@link CodecDescriptorImpl} over {@link
+ * ArktypeJsonTypeParams}. Factory rehydrates the schema from `params.jsonIr` and returns `(ctx) => new ArktypeJsonCodecClass<unknown>(this, schema)` — `S` is erased to `unknown` because the descriptor only sees IR. The runtime path through `descriptor.factory(params)` always exists (e.g. for `validateContract` re-materialization); it just loses the typed inferred shape. 3. {@link arktypeJsonColumn} is the column-author
+ * surface with the method-level generic over `S extends Type<unknown>`. It bypasses `descriptor.factory` because `S` is only available here, instead constructing the typed codec directly so `S['infer']` flows through `codecFactory`'s return into the column site's resolved output type. Eager serialization at this call site captures `expression` (for the emit-path renderer) and `jsonIr` (for runtime rehydration).
  *
- * - `expression`: `schema.expression` — arktype's TypeScript-source-like
- *   rendering used by the emit-path `renderOutputType` to produce the
- *   column's TS type in `contract.d.ts`.
- * - `jsonIr`: `schema.json` — arktype's internal IR. Lossless; the
- *   rehydration source consumed by `ark.schema(jsonIr)` at runtime.
- *
- * The pair is sufficient: `expression` round-trips with the rehydrated
- * schema (`ark.schema(jsonIr).expression === expression`) so the emit-path
- * output is stable across serialize/rehydrate.
- *
- * **Rehydration** (runtime, on factory invocation): `ark.schema(typeParams.jsonIr)`
- * returns a callable `Type`-like with `~standard`. The returned codec's
- * `decode` body validates wire payloads through the rehydrated schema and
- * throws `RUNTIME.JSON_SCHEMA_VALIDATION_FAILED` on rejection — no separate
- * validator-registry consultation.
- *
- * See the codec-registry-unification spec § Case J (JSON-with-schema).
+ * `satisfies ColumnHelperFor<ArktypeJsonDescriptor>` (coarse) is applied — the typeParams shape is verified. `ColumnHelperForStrict` is intentionally skipped: the descriptor's factory return is `ArktypeJsonCodecClass<unknown>` while the helper produces `ArktypeJsonCodecClass<S['infer']>`, and `Codec`'s `TInput` is invariant (used contravariantly in `encode`, covariantly in `decode`/`encodeJson`/`decodeJson`). Strict
+ * assignment fails by design; the explicit `expectTypeOf` tests in `test/arktype-json-codec.types.test-d.ts` cover the literal-preservation property the strict variant would otherwise enforce.
  */
 
 import type { JsonValue } from '@prisma-next/contract/types';
-import type { ColumnTypeDescriptor } from '@prisma-next/contract-authoring';
-import type {
-  Codec,
-  CodecDescriptor,
-  CodecInstanceContext,
+import {
+  type AnyCodecDescriptor,
+  type CodecCallContext,
+  CodecDescriptorImpl,
+  CodecImpl,
+  type CodecInstanceContext,
+  type ColumnHelperFor,
+  type ColumnSpec,
+  column,
 } from '@prisma-next/framework-components/codec';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import { codec } from '@prisma-next/sql-relational-core/ast';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { ArkErrors, ark, type Type, type } from 'arktype';
 
-// ── Constants ────────────────────────────────────────────────────────────
-
 /** Codec id for arktype-backed JSON columns. Library-bound, not target-bound. */
 export const ARKTYPE_JSON_CODEC_ID = 'arktype/json@1' as const;
 
 /** Native storage type backing the codec. JSONB on Postgres; binary, indexable. */
 export const ARKTYPE_JSON_NATIVE_TYPE = 'jsonb' as const;
 
-// ── typeParams shape ─────────────────────────────────────────────────────
-
 /**
- * Eagerly serialized typeParams for the arktype-json column. Carried in
- * the contract IR; the runtime descriptor's factory rehydrates `jsonIr`
- * and the emitter consumes `expression`.
+ * Eagerly serialized typeParams for the arktype-json column. Carried in the contract IR; the runtime descriptor's factory rehydrates `jsonIr` and the emitter consumes `expression`.
  */
 export type ArktypeJsonTypeParams = {
   /**
-   * Arktype's TypeScript-source-like rendering of the schema. Read by
-   * `renderOutputType` to emit the column's TS type into `contract.d.ts`.
-   * Stable across the serialize/rehydrate cycle: the rehydrated schema's
-   * `expression` matches the source schema's.
+   * Arktype's TypeScript-source-like rendering of the schema. Read by `renderOutputType` to emit the column's TS type into `contract.d.ts`. Stable across the serialize/rehydrate cycle: the rehydrated schema's `expression` matches the source schema's.
    */
   readonly expression: string;
   /**
-   * Arktype's internal IR for the schema. Lossless; the rehydration
-   * source. Schema-shape — `ark.schema(jsonIr)` reconstructs a callable
-   * `Type`-like structurally identical to the original `type(definition)`
-   * output.
+   * Arktype's internal IR for the schema. Lossless; the rehydration source. Schema-shape — `ark.schema(jsonIr)` reconstructs a callable `Type`-like structurally identical to the original `type(definition)` output.
    */
   readonly jsonIr: object;
 };
 
-// ── Curried higher-order codec factory ───────────────────────────────────
-
-/**
- * Codec instance returned by `arktypeJson(schema)(ctx)` and by
- * `arktypeJsonCodec.factory(typeParams)(ctx)`. The `TInferred` slot
- * carries the arktype schema's inferred output type.
- */
-export type ArktypeJsonCodec<TInferred> = Codec<
-  typeof ARKTYPE_JSON_CODEC_ID,
-  readonly ['equality'],
-  string,
-  TInferred
->;
-
-/**
- * Structural narrow of arktype's `Type` — the surface our codec depends
- * on: a callable validator that returns `inferOut | ArkErrors`, plus the
- * `expression` string for emit-path rendering.
- *
- * Avoids depending on the precise generics of arktype's `Type<t, $>` so
- * schemas built in any scope (the default `Ark` from `type(...)` AND the
- * minimal scope from `ark.schema(...)`) satisfy the same contract.
- */
 type ArktypeSchemaLike = ((value: unknown) => unknown) & {
   readonly expression: string;
 };
 
-/**
- * Type predicate for `ArktypeSchemaLike`. Lets the column-author
- * factory narrow `unknown` schemas to the structural shape the codec
- * depends on after the explicit field guards run, so the descriptor
- * builder doesn't fall back to a `as unknown as` cast.
- */
 function isArktypeSchemaLike(value: unknown): value is ArktypeSchemaLike {
   if (typeof value !== 'function') return false;
   const expression = (value as { readonly expression?: unknown }).expression;
   return typeof expression === 'string';
 }
 
-/**
- * Build the curried factory for a rehydrated arktype schema. The factory's
- * returned codec carries the schema in its closure; `decode` validates
- * wire payloads via `schema(parsed)`, throwing
- * `RUNTIME.JSON_SCHEMA_VALIDATION_FAILED` on rejection.
- *
- * Encode is `JSON.stringify` — the schema validates the input shape only
- * at the read boundary (decode), matching the JSON-validator philosophy:
- * the payload may have been written by any source (this writer, a
- * previous version of the schema, a manual SQL `INSERT`); validate when
- * reading, not when writing.
- *
- * Author bodies are sync; main's `codec({...})` factory promise-lifts
- * `encode`/`decode` into the framework-required `Promise<…>` boundary
- * shape (per ADR 204).
- */
-function arktypeJsonCodecForSchema<TInferred>(
-  schema: ArktypeSchemaLike,
-): (ctx: CodecInstanceContext) => ArktypeJsonCodec<TInferred> {
-  // Shared schema check used by both `decode` (wire → JS) and
-  // `decodeJson` (JsonValue → JS). Either entry point must reject
-  // payloads that don't match the schema; without the shared validator,
-  // any caller that hands parsed JSON straight to the codec would bypass
-  // schema enforcement and return unchecked data.
-  function validateSchema(value: unknown): TInferred {
-    const result = schema(value);
-    if (result instanceof ArkErrors) {
-      throw runtimeError(
-        'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED',
-        `arktype-json schema validation failed (decode): ${result.summary}`,
-        { codecId: ARKTYPE_JSON_CODEC_ID, issues: result.summary },
-      );
-    }
-    // arktype's call-result is `inferOut | ArkErrors`; the ArkErrors
-    // branch is excluded above. The cast threads the caller-supplied
-    // generic onto the structurally-typed validation output.
-    return result as TInferred;
-  }
-
-  // Derive both `encode` (wire string) and `encodeJson` (JsonValue)
-  // outputs from the same `JSON.stringify` → `JSON.parse` round-trip,
-  // then validate the normalized payload through the schema. Without
-  // this normalization, a non-JSON-safe runtime value (e.g. a class
-  // instance, a function field on a narrowed type) could slip through
-  // `encodeJson` unchanged while `encode` silently dropped or
-  // transformed it — producing wire payloads the codec's own decode
-  // path would later reject. The serialize/parse round-trip also
-  // produces the JSON-safe shape required by the contract IR's
-  // `JsonValue` surface, so `encodeJson` no longer needs a blind cast.
-  function serializeToJsonSafe(value: TInferred): { wire: string; json: JsonValue } {
-    // `JSON.stringify` returns `string | undefined` — `undefined`
-    // happens when the input is `undefined` itself or contains only
-    // unserializable values (functions, symbols). Reject explicitly so
-    // the caller sees the schema-failure code rather than a downstream
-    // `JSON.parse(undefined)` SyntaxError.
-    const wire: string | undefined = JSON.stringify(value);
-    if (typeof wire !== 'string') {
-      throw runtimeError(
-        'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED',
-        `arktype-json value is not representable as JSON (codecId: ${ARKTYPE_JSON_CODEC_ID})`,
-        { codecId: ARKTYPE_JSON_CODEC_ID },
-      );
-    }
-    const json = JSON.parse(wire) as JsonValue;
-    // Validate the normalized payload — the round-trip strips
-    // class-prototype shape and arktype-narrowed fields, and the
-    // schema must still accept the result. Run validation and discard
-    // its return value (we keep `json` as the JsonValue, not the
-    // schema's `inferOut` which already matches `TInferred`).
-    validateSchema(json);
-    return { wire, json };
+function validateSchema<TInferred>(schema: ArktypeSchemaLike, value: unknown): TInferred {
+  const result = schema(value);
+  if (result instanceof ArkErrors) {
+    throw runtimeError(
+      'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED',
+      `arktype-json schema validation failed (decode): ${result.summary}`,
+      { codecId: ARKTYPE_JSON_CODEC_ID, issues: result.summary },
+    );
   }
-
-  return (_ctx) =>
-    codec<typeof ARKTYPE_JSON_CODEC_ID, readonly ['equality'], string, TInferred>({
-      typeId: ARKTYPE_JSON_CODEC_ID,
-      targetTypes: [ARKTYPE_JSON_NATIVE_TYPE],
-      traits: ['equality'] as const,
-      encode: (value: TInferred): string => serializeToJsonSafe(value).wire,
-      decode: (wire: string): TInferred => validateSchema(JSON.parse(wire)),
-      encodeJson: (value: TInferred): JsonValue => serializeToJsonSafe(value).json,
-      decodeJson: (json: JsonValue) => validateSchema(json),
-    }) as ArktypeJsonCodec<TInferred>;
+  return result as TInferred;
 }
 
-// ── Column-author surface ────────────────────────────────────────────────
-
-/**
- * Curried column-author factory for arktype-validated JSON columns.
- *
- * Usage:
- *
- * ```ts
- * import { type } from 'arktype';
- * import { arktypeJson } from '@prisma-next/extension-arktype-json/column-types';
- *
- * const ProductSchema = type({ name: 'string', price: 'number' });
- *
- * const Product = {
- *   columns: {
- *     id: textCodec,
- *     settings: arktypeJson(ProductSchema),
- *     //        ^? ColumnTypeDescriptor with type :: (ctx) => Codec<…, { name: string; price: number }>
- *   },
- * };
- * ```
- *
- * The schema's inferred output flows through `S['infer']` so the no-emit
- * `FieldOutputType` resolver produces the precise TS type at the column
- * site. Eager serialization at this call site captures `expression` (for
- * the emit-path renderer) and `jsonIr` (for runtime rehydration).
- *
- * @throws {Error} if the schema doesn't expose `expression` and `json`
- *   fields (i.e. is not an arktype `Type`). The factory validates the
- *   schema shape at the call site so configuration errors surface during
- *   contract authoring, not at runtime.
- */
-export function arktypeJson<S extends Type<unknown>>(
-  schema: S,
-): ColumnTypeDescriptor & {
-  readonly codecId: typeof ARKTYPE_JSON_CODEC_ID;
-  readonly nativeType: typeof ARKTYPE_JSON_NATIVE_TYPE;
-  readonly typeParams: ArktypeJsonTypeParams;
-  readonly type: (ctx: CodecInstanceContext) => ArktypeJsonCodec<S['infer']>;
-} {
-  // Reject non-callable / non-arktype-shaped lookalikes before any
-  // property reads. An object shaped like `{ expression, json }` would
-  // otherwise pass the field checks and only explode on the first
-  // `decode`/`decodeJson` call, defeating the early authoring-time
-  // guard this factory provides. The `isArktypeSchemaLike` predicate
-  // narrows `schema` so the descriptor builder hands the typed shape
-  // straight to the curried factory — no `as unknown as` cast.
-  if (!isArktypeSchemaLike(schema)) {
-    throw new Error(
-      typeof schema !== 'function'
-        ? 'arktypeJson(schema) expects a callable arktype Type.'
-        : 'arktypeJson(schema) expects an arktype Type (missing `expression: string`).',
+function serializeToJsonSafe<TInferred>(
+  schema: ArktypeSchemaLike,
+  value: TInferred,
+): { wire: string; json: JsonValue } {
+  const wire: string | undefined = JSON.stringify(value);
+  if (typeof wire !== 'string') {
+    throw runtimeError(
+      'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED',
+      `arktype-json value is not representable as JSON (codecId: ${ARKTYPE_JSON_CODEC_ID})`,
+      { codecId: ARKTYPE_JSON_CODEC_ID },
     );
   }
-  const jsonIr: unknown = (schema as { readonly json?: unknown }).json;
-  if (jsonIr === null || typeof jsonIr !== 'object') {
-    throw new Error('arktypeJson(schema) expects an arktype Type (missing `json` IR).');
-  }
-  return {
-    codecId: ARKTYPE_JSON_CODEC_ID,
-    nativeType: ARKTYPE_JSON_NATIVE_TYPE,
-    typeParams: { expression: schema.expression, jsonIr },
-    type: arktypeJsonCodecForSchema<S['infer']>(schema),
-  } as const;
+  const json = JSON.parse(wire) as JsonValue;
+  validateSchema(schema, json);
+  return { wire, json };
 }
 
-// ── Framework-registration descriptor ────────────────────────────────────
-
-/**
- * Standard Schema validator for the descriptor's typeParams. Asserts the
- * shape `{ expression: string; jsonIr: object }` at the contract IR
- * boundary; deeper IR-shape validation happens implicitly when
- * `ark.schema(jsonIr)` reparses (corrupt IR throws there).
- *
- * Eats its own dog food: the validator is itself an arktype schema.
- */
-const arktypeJsonParamsSchema = type({
-  expression: 'string',
-  jsonIr: 'object',
-});
-
-/**
- * Rehydrate an arktype schema from the serialized IR. Throws a clean
- * error if the IR is corrupt — the "corruption-of-contract.json" case.
- */
 function rehydrateSchema(jsonIr: object): ArktypeSchemaLike {
+  let rehydrated: unknown;
   try {
-    return ark.schema(jsonIr) as unknown as ArktypeSchemaLike;
+    rehydrated = ark.schema(jsonIr);
   } catch (error) {
     throw runtimeError(
       'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED',
+      /* c8 ignore next — the `String(error)` fallback covers throws of non-Error values; arktype only throws Error subclasses, so this branch is defensive only. */
       `Failed to rehydrate arktype schema from contract IR: ${error instanceof Error ? error.message : String(error)}`,
       { codecId: ARKTYPE_JSON_CODEC_ID, jsonIr },
     );
   }
+  /* c8 ignore start — defensive: ark.schema either throws (handled above) or returns a callable Type with `expression: string`. The structural guard is kept so a future ark internal change can't silently slip a non-callable past us. */
+  if (!isArktypeSchemaLike(rehydrated)) {
+    throw runtimeError(
+      'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED',
+      `Rehydrated arktype schema does not have the expected callable + 'expression: string' shape (codecId: ${ARKTYPE_JSON_CODEC_ID})`,
+      { codecId: ARKTYPE_JSON_CODEC_ID, jsonIr },
+    );
+  }
+  /* c8 ignore stop */
+  return rehydrated;
 }
 
-/**
- * Render the emit-path TS type for an arktype-json column. Reads the
- * eagerly-extracted `expression` directly — the round-trip stability
- * guarantee (rehydrated schema's `expression` matches the source's)
- * means the rendered output is consistent across serialize/rehydrate.
- */
 function renderArktypeJsonOutputType(params: ArktypeJsonTypeParams): string {
   const expression = params.expression.trim();
   return expression.length > 0 ? expression : 'unknown';
 }
 
-/**
- * Build a permissive `renderOutputType` that accepts the framework's
- * generic typeParams shape and dispatches to the type-narrow renderer
- * once the input is structurally an `ArktypeJsonTypeParams`.
- */
-function renderArktypeJsonOutputTypeFromUnknownParams(
-  typeParams: Record<string, unknown>,
-): string | undefined {
-  const expression = typeParams['expression'];
-  const jsonIr = typeParams['jsonIr'];
-  if (typeof expression !== 'string' || jsonIr === null || typeof jsonIr !== 'object') {
-    return undefined;
-  }
-  return renderArktypeJsonOutputType({ expression, jsonIr });
-}
-
-/**
- * Emit-only `Codec` instance for `arktype/json@1`. Threaded through the
- * pack-meta's `codecInstances` array so the emitter's `CodecLookup` can
- * find a `renderOutputType` for the codec id (the emitter consults the
- * codec-id-keyed `CodecLookup` at the framework boundary; the unified
- * descriptor's `renderOutputType` is the long-term home for the renderer
- * but the emit-path glue still routes through `CodecLookup`).
- *
- * All conversion methods are sentinels that throw if invoked — runtime
- * materialization always goes through `arktypeJsonCodec.factory`'s
- * curried `(params) => (ctx) => Codec`, never through this instance.
- * `encodeJson`/`decodeJson` throw alongside `encode`/`decode` so a
- * mistaken contract-load that resolved to this stub fails fast at the
- * JSON boundary instead of silently returning unvalidated payloads. A
- * future cleanup could route the emit path through the descriptor map
- * directly and retire this shim.
- */
-const ARKTYPE_JSON_RUNTIME_DISPATCH_ERROR =
-  'arktype-json codec instances must be materialized via the descriptor factory; this is an emit-only stub';
-
-export const arktypeJsonEmitCodec: Codec<
+export class ArktypeJsonCodecClass<TInferred> extends CodecImpl<
   typeof ARKTYPE_JSON_CODEC_ID,
   readonly ['equality'],
   string,
-  unknown
-> = {
-  id: ARKTYPE_JSON_CODEC_ID,
-  targetTypes: [ARKTYPE_JSON_NATIVE_TYPE],
-  traits: ['equality'] as const,
-  encode: () => Promise.reject(new Error(ARKTYPE_JSON_RUNTIME_DISPATCH_ERROR)),
-  decode: () => Promise.reject(new Error(ARKTYPE_JSON_RUNTIME_DISPATCH_ERROR)),
-  encodeJson: () => {
-    throw new Error(ARKTYPE_JSON_RUNTIME_DISPATCH_ERROR);
-  },
-  decodeJson: () => {
-    throw new Error(ARKTYPE_JSON_RUNTIME_DISPATCH_ERROR);
-  },
-  renderOutputType: renderArktypeJsonOutputTypeFromUnknownParams,
-};
+  TInferred
+> {
+  constructor(
+    descriptor: ArktypeJsonDescriptor,
+    private readonly schema: ArktypeSchemaLike,
+  ) {
+    super(descriptor);
+  }
 
-/**
- * Framework-registration descriptor for the arktype-json codec. Registered
- * through the SQL runtime's `parameterizedCodecs:` slot. `sql-runtime`'s
- * `initializeTypeHelpers` (and per-column walk in
- * `buildContractCodecRegistry`) calls `arktypeJsonCodec.factory(typeParams)
- * (ctx)` once per `storage.types` instance (or once per inline-typeParams
- * column) to materialize the resolved codec carrying the rehydrated
- * schema.
- *
- * Per Phase B of codec-registry-unification, `descriptorFor('arktype/json@1')`
- * returns this descriptor and its `traits`/`targetTypes` are the codec-id-
- * keyed source of truth — no parallel placeholder on the legacy `codecs:`
- * slot is needed (the runtime descriptor ships `codecs: () => createCodecRegistry()`
- * — empty).
- */
-export const arktypeJsonCodec: CodecDescriptor<ArktypeJsonTypeParams> = {
-  codecId: ARKTYPE_JSON_CODEC_ID,
-  traits: ['equality'] as const,
-  targetTypes: [ARKTYPE_JSON_NATIVE_TYPE] as const,
-  paramsSchema: arktypeJsonParamsSchema,
-  renderOutputType: renderArktypeJsonOutputType,
-  factory: (params) => {
+  async encode(value: TInferred, _ctx: CodecCallContext): Promise<string> {
+    return serializeToJsonSafe(this.schema, value).wire;
+  }
+
+  async decode(wire: string, _ctx: CodecCallContext): Promise<TInferred> {
+    return validateSchema<TInferred>(this.schema, JSON.parse(wire));
+  }
+
+  encodeJson(value: TInferred): JsonValue {
+    return serializeToJsonSafe(this.schema, value).json;
+  }
+
+  decodeJson(json: JsonValue): TInferred {
+    return validateSchema<TInferred>(this.schema, json);
+  }
+}
+
+const arktypeJsonParamsSchema = type({
+  expression: 'string',
+  jsonIr: 'object',
+}) satisfies StandardSchemaV1<ArktypeJsonTypeParams>;
+
+export class ArktypeJsonDescriptor extends CodecDescriptorImpl<ArktypeJsonTypeParams> {
+  override readonly codecId = ARKTYPE_JSON_CODEC_ID;
+  override readonly traits = ['equality'] as const;
+  override readonly targetTypes = [ARKTYPE_JSON_NATIVE_TYPE] as const;
+  override readonly paramsSchema: StandardSchemaV1<ArktypeJsonTypeParams> = arktypeJsonParamsSchema;
+  override renderOutputType(params: ArktypeJsonTypeParams): string {
+    return renderArktypeJsonOutputType(params);
+  }
+  override factory(
+    params: ArktypeJsonTypeParams,
+  ): (ctx: CodecInstanceContext) => ArktypeJsonCodecClass<unknown> {
     const schema = rehydrateSchema(params.jsonIr);
     /* c8 ignore start — defensive parity check; not exercised by typical contracts */
-    // The rehydrated schema's `expression` should match the serialized
-    // one; diverging means contract.json was hand-edited out from under
-    // the emit-path renderer. Surface as a soft warning at materialization
-    // time so the caller knows their emit output may not match the
-    // runtime schema. The runtime keeps using the schema rehydrated from
-    // `jsonIr` — that's the lossless source — so the worst case is an
-    // emit-vs-runtime divergence at a single column, not a runtime
-    // failure.
     const rehydratedExpression = (schema as { readonly expression?: unknown }).expression;
     if (typeof rehydratedExpression === 'string' && rehydratedExpression !== params.expression) {
       console.warn(
@@ -397,6 +169,49 @@ export const arktypeJsonCodec: CodecDescriptor<ArktypeJsonTypeParams> = {
       );
     }
     /* c8 ignore stop */
-    return arktypeJsonCodecForSchema<unknown>(schema);
-  },
-};
+    return () => new ArktypeJsonCodecClass<unknown>(this, schema);
+  }
+}
+
+export const arktypeJsonDescriptor = new ArktypeJsonDescriptor();
+
+/**
+ * Per-codec column helper for `arktype/json@1`. Method-level generic over `S extends Type<unknown>` so the column site preserves the schema's inferred TS type in the resolved codec (`ArktypeJsonCodecClass<S['infer']>`). Bypasses `descriptor.factory` because `S` is only available at the column-author site; constructs the typed codec directly with the closure-captured schema.
+ *
+ * Eager serialization at this call site captures `expression` (for the emit-path renderer) and `jsonIr` (for runtime rehydration via the descriptor's factory).
+ *
+ * @throws {Error} if the schema doesn't expose `expression` and `json` fields (i.e. is not an arktype `Type`). Validates the schema shape at the call site so configuration errors surface during contract authoring, not at runtime.
+ */
+export function arktypeJsonColumn<S extends Type<unknown>>(
+  schema: S,
+): ColumnSpec<ArktypeJsonCodecClass<S['infer']>, ArktypeJsonTypeParams> {
+  if (!isArktypeSchemaLike(schema)) {
+    throw new Error(
+      typeof schema !== 'function'
+        ? 'arktypeJsonColumn(schema) expects a callable arktype Type.'
+        : 'arktypeJsonColumn(schema) expects an arktype Type (missing `expression: string`).',
+    );
+  }
+  const jsonIr: unknown = (schema as { readonly json?: unknown }).json;
+  if (jsonIr === null || typeof jsonIr !== 'object') {
+    throw new Error('arktypeJsonColumn(schema) expects an arktype Type (missing `json` IR).');
+  }
+  const params: ArktypeJsonTypeParams = { expression: schema.expression, jsonIr };
+  return column(
+    (_ctx: CodecInstanceContext) =>
+      new ArktypeJsonCodecClass<S['infer']>(arktypeJsonDescriptor, schema),
+    arktypeJsonDescriptor.codecId,
+    params,
+    ARKTYPE_JSON_NATIVE_TYPE,
+  );
+}
+
+arktypeJsonColumn satisfies ColumnHelperFor<ArktypeJsonDescriptor>;
+// Note: `ColumnHelperForStrict` is intentionally not applied — `Codec` is invariant in `TInput` (encode contravariant, decode covariant), so `ArktypeJsonCodecClass<S['infer']>` is not assignable to `ArktypeJsonCodecClass<unknown>` (the descriptor.factory return). `expectTypeOf` tests cover the literal-preservation property strict satisfies would otherwise enforce.
+
+/**
+ * Codec instance returned by `arktypeJsonColumn(schema).codecFactory(ctx)` and by `arktypeJsonDescriptor.factory(typeParams)(ctx)`. The `TInferred` slot carries the arktype schema's inferred output type at the column-author site; descriptor-side factories erase to `unknown`.
+ */
+export type ArktypeJsonCodec<TInferred> = ArktypeJsonCodecClass<TInferred>;
+
+export const codecDescriptors: readonly AnyCodecDescriptor[] = [arktypeJsonDescriptor];

package/src/core/pack-meta.ts

@@ -1,24 +1,14 @@
 /**
  * arktype-json pack metadata.
  *
- * The pack metadata is the framework-composition entry point: control-
- * stack assembly reads `types.codecTypes.import` to thread the type-side
- * imports into emitted `contract.d.ts`, and `types.storage` declares the
- * codec id's storage backing (`jsonb` on Postgres).
+ * The pack metadata is the framework-composition entry point: control-stack assembly reads `types.codecTypes.import` to thread the type-side imports into emitted `contract.d.ts`, and `types.storage` declares the codec id's storage backing (`jsonb` on Postgres).
  *
- * Per Phase B of codec-registry-unification, runtime materialization
- * flows through the unified descriptor map (`arktypeJsonCodec`
- * parameterized descriptor), not through the legacy runtime codec
- * lookup. This metadata still carries an emit-only `Codec` instance
- * (`arktypeJsonEmitCodec`) under `codecInstances` so the framework
- * emitter's codec-id-keyed `CodecLookup` can resolve `renderOutputType`
- * at emit time — that shim retires when the emit path consults the
- * descriptor map directly (TML-2357). Control-stack consumers read
- * codec metadata from `descriptorFor('arktype/json@1')`.
+ * Per TML-2357 runtime materialization flows through the unified descriptor map (`arktypeJsonDescriptor`) and the emit path consults `descriptorFor('arktype/json@1').renderOutputType` directly — no per-library "emit-only Codec" stub.
  */
 
 import type { CodecTypes } from '../types/codec-types';
-import { ARKTYPE_JSON_CODEC_ID, arktypeJsonEmitCodec } from './arktype-json-codec';
+import { ARKTYPE_JSON_CODEC_ID } from './arktype-json-codec';
+import { arktypeJsonCodecRegistry } from './registry';
 
 const arktypeJsonPackMetaBase = {
   kind: 'extension',
@@ -29,13 +19,7 @@ const arktypeJsonPackMetaBase = {
   capabilities: {},
   types: {
     codecTypes: {
-      // The emitter's `CodecLookup` is the codec-id-keyed source of
-      // truth for `renderOutputType` at the framework emit-path
-      // boundary. We thread an emit-only `Codec` instance carrying the
-      // `renderOutputType` here so the lookup resolves; runtime
-      // materialization goes through the unified descriptor's
-      // `factory: (P) => (CodecInstanceContext) => Codec`, never through this shim.
-      codecInstances: [arktypeJsonEmitCodec],
+      codecDescriptors: Array.from(arktypeJsonCodecRegistry.values()),
       import: {
         package: '@prisma-next/extension-arktype-json/codec-types',
         named: 'CodecTypes',
@@ -54,9 +38,7 @@ const arktypeJsonPackMetaBase = {
 } as const;
 
 /**
- * Public pack metadata. The phantom `__codecTypes` field threads the
- * codec-types map's literal type into the pack ref so contract-builder
- * generics can pick it up; it is never accessed at runtime.
+ * Public pack metadata. The phantom `__codecTypes` field threads the codec-types map's literal type into the pack ref so contract-builder generics can pick it up; it is never accessed at runtime.
  */
 export const arktypeJsonPackMeta: typeof arktypeJsonPackMetaBase & {
   readonly __codecTypes?: CodecTypes;

package/src/core/registry.ts

@@ -0,0 +1,11 @@
+import { buildCodecDescriptorRegistry } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
+import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
+import { codecDescriptors } from './arktype-json-codec';
+
+/**
+ * Registry of every codec descriptor shipped by `@prisma-next/extension-arktype-json`.
+ *
+ * Public consumer surface for the arktype-json codec set. Currently a single entry (`arktype/json@1`); the registry shape stays consistent with the other codec-shipping packages so consumers don't need to special-case extensions. See ADR 208.
+ */
+export const arktypeJsonCodecRegistry: CodecDescriptorRegistry =
+  buildCodecDescriptorRegistry(codecDescriptors);

package/src/exports/codecs.ts

@@ -1,6 +1,11 @@
-export type { ArktypeJsonCodec, ArktypeJsonTypeParams } from '../core/arktype-json-codec';
+export type {
+  ArktypeJsonCodec,
+  ArktypeJsonDescriptor,
+  ArktypeJsonTypeParams,
+} from '../core/arktype-json-codec';
 export {
   ARKTYPE_JSON_CODEC_ID,
   ARKTYPE_JSON_NATIVE_TYPE,
-  arktypeJsonCodec,
+  arktypeJsonColumn,
 } from '../core/arktype-json-codec';
+export { arktypeJsonCodecRegistry } from '../core/registry';

package/src/exports/column-types.ts

@@ -1,2 +1,2 @@
 export type { ArktypeJsonCodec, ArktypeJsonTypeParams } from '../core/arktype-json-codec';
-export { arktypeJson } from '../core/arktype-json-codec';
+export { arktypeJsonColumn as arktypeJson } from '../core/arktype-json-codec';