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

package/src/ast/codec-types.ts

@@ -1,39 +1,51 @@
-import type { JsonValue } from '@prisma-next/contract/types';
-import type { Codec as BaseCodec, CodecTrait } from '@prisma-next/framework-components/codec';
-import { ifDefined } from '@prisma-next/utils/defined';
-import type { Type } from 'arktype';
-import type { O } from 'ts-toolbelt';
-
-export type { CodecTrait } from '@prisma-next/framework-components/codec';
+import type {
+  Codec as BaseCodec,
+  CodecCallContext,
+  CodecDescriptor,
+  CodecInstanceContext,
+  CodecTrait,
+} from '@prisma-next/framework-components/codec';
+
+export type {
+  CodecCallContext,
+  CodecDescriptor,
+  CodecTrait,
+} from '@prisma-next/framework-components/codec';
 
 /**
- * Descriptor for parameterized codecs that require type parameter validation.
- * Shared between adapter (compile-time) and runtime layers to avoid duplication.
+ * SQL-family addressing of a single column. The decode site populates a `SqlColumnRef` whenever it can resolve the cell to a single underlying `(table, column)` (the typical case for projected columns from a single-table source); cells the runtime cannot resolve (aggregate aliases, include aggregate fields, computed projections without a simple ref) get `column = undefined`.
  *
- * @template TParams - The shape of the type parameters (e.g., `{ length: number }`)
- * @template THelper - The type returned by the optional `init` hook
+ * The shape is a structural projection of the runtime's `ColumnRef` so the SQL decode site can reuse the resolution it already performs for `RUNTIME.DECODE_FAILED` envelope construction without allocating twice per cell.
  */
-export interface CodecParamsDescriptor<TParams = Record<string, unknown>, THelper = unknown> {
-  /** The codec ID this descriptor applies to (e.g., 'pg/vector@1') */
-  readonly codecId: string;
+export interface SqlColumnRef {
+  readonly table: string;
+  readonly name: string;
+}
 
-  /**
-   * Arktype schema for validating typeParams.
-   * Used to validate both storage.types entries and inline column typeParams.
-   */
-  readonly paramsSchema: Type<TParams>;
+/**
+ * SQL-family per-call context. Extends the framework {@link CodecCallContext} (which carries `signal` only) with `column?: SqlColumnRef`, populated on **decode** call sites that can resolve a single underlying column ref. Encode call sites currently leave `column` undefined (encode-time column context is the middleware's domain).
+ *
+ * SQL codec authors writing codec methods observe this type via {@link SqlCodec}. The framework codec dispatch surface (and Mongo) sees only the base `CodecCallContext`.
+ */
+export interface SqlCodecCallContext extends CodecCallContext {
+  readonly column?: SqlColumnRef;
+}
 
-  /**
-   * Optional init hook called during runtime context creation.
-   * Receives validated params and returns a helper object to be stored in context.types.
-   * If not provided, the validated params are stored directly.
-   */
-  readonly init?: (params: TParams) => THelper;
+/**
+ * SQL-family per-instance context. Extends the framework {@link CodecInstanceContext} (`name` only) with `usedAt`, the set of `(table, column)` pairs the resolved codec serves.
+ *
+ * - For `typeRef` columns sharing one named `storage.types` instance, the array lists every referencing column — a column-scoped stateful codec (e.g. encryption) can derive aggregated per-instance state across all the columns sharing the named instance.
+ * - For inline-`typeParams` columns, the array has exactly one entry — the column that owns the inline params.
+ * - For shared non-parameterized codecs, the array carries one representative entry (the column that triggered materialization); the codec is shared across every column with that codec id, so the `usedAt` is informational only.
+ *
+ * SQL extensions consuming `usedAt` (e.g. column-scoped state derivation) type their factory parameter as `SqlCodecInstanceContext`. Extensions that don't read `usedAt` type their factory parameter as the family-agnostic {@link CodecInstanceContext} — a `SqlCodecInstanceContext` is structurally assignable to the base.
+ */
+export interface SqlCodecInstanceContext extends CodecInstanceContext {
+  readonly usedAt: ReadonlyArray<{ readonly table: string; readonly column: string }>;
 }
 
 /**
- * Codec metadata for database-specific type information.
- * Used for schema introspection and verification.
+ * Codec metadata for database-specific type information. Used for schema introspection and verification.
  */
 export interface CodecMeta {
   readonly db?: {
@@ -46,429 +58,85 @@ export interface CodecMeta {
 }
 
 /**
- * SQL codec — extends the framework codec base with SQL-specific metadata:
- * driver-native type info (`meta.db.sql.<dialect>.nativeType`) and an
- * optional parameterized-codec descriptor (`paramsSchema` + `init`) for
- * codecs that require type-parameter validation (e.g. `pg/vector@1`).
+ * SQL codec — extends the framework codec base by narrowing the per-call context to the SQL-family {@link SqlCodecCallContext} (adds `column?: SqlColumnRef`). TypeScript treats method-syntax declarations bivariantly, so the SQL narrowing is structurally compatible with the framework {@link BaseCodec} super-interface.
+ *
+ * Codec-id-keyed static metadata (`traits`, `targetTypes`, `meta`, `paramsSchema`, `renderOutputType`) lives on the unified {@link import('@prisma-next/framework-components/codec').CodecDescriptor} — the codec instance itself only carries `id` plus the four conversion methods.
  *
- * See `Codec` in `@prisma-next/framework-components/codec` for the codec
- * contract that this interface extends.
+ * See `Codec` in `@prisma-next/framework-components/codec` for the codec contract that this interface extends.
  */
 export interface Codec<
   Id extends string = string,
   TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
   TWire = unknown,
   TInput = unknown,
-  TParams = Record<string, unknown>,
-  THelper = unknown,
 > extends BaseCodec<Id, TTraits, TWire, TInput> {
-  readonly meta?: CodecMeta;
-  readonly paramsSchema?: Type<TParams>;
-  readonly init?: (params: TParams) => THelper;
+  encode(value: TInput, ctx: SqlCodecCallContext): Promise<TWire>;
+  decode(wire: TWire, ctx: SqlCodecCallContext): Promise<TInput>;
 }
 
 /**
- * Registry interface for codecs organized by ID and by contract scalar type.
+ * Contract-bound codec registry.
  *
- * The registry allows looking up codecs by their namespaced ID or by the
- * contract scalar types they handle. Multiple codecs may handle the same
- * scalar type; ordering in byScalar reflects preference (adapter first,
- * then packs, then app overrides).
- */
-export interface CodecRegistry {
-  get(id: string): Codec<string> | undefined;
-  has(id: string): boolean;
-  getByScalar(scalar: string): readonly Codec<string>[];
-  getDefaultCodec(scalar: string): Codec<string> | undefined;
-  register(codec: Codec<string>): void;
-  /** Returns true if the codec with this ID has the given trait. */
-  hasTrait(codecId: string, trait: CodecTrait): boolean;
-  /** Returns all traits for a codec, or an empty array if not found. */
-  traitsOf(codecId: string): readonly CodecTrait[];
-  [Symbol.iterator](): Iterator<Codec<string>>;
-  values(): IterableIterator<Codec<string>>;
-}
-
-/**
- * Implementation of CodecRegistry.
+ * The dispatch interface for encode/decode at runtime: built once at `ExecutionContext` construction time by walking the contract's `storage.tables[].columns[]` and resolving each column through its descriptor's factory (per-instance for parameterized columns; the cached shared codec for non-parameterized columns). The dispatch path calls `forColumn(table, column).encode/decode(...)` and doesn't know whether the codec
+ * is parameterized.
+ *
+ * `forCodecId(codecId)` is the refs-less fallback. Every column-bound `ParamRef` carries `refs: { table; column }` and the builder-pipeline `validateParamRefRefs` pass enforces refs on every parameterized `ParamRef` before encode runs, so this fallback is only reached for non-parameterized codec ids.
  */
-class CodecRegistryImpl implements CodecRegistry {
-  private readonly _byId = new Map<string, Codec<string>>();
-  private readonly _byScalar = new Map<string, Codec<string>[]>();
-
-  /**
-   * Map-like interface for codec lookup by ID.
-   * Example: registry.get('pg/text@1')
-   */
-  get(id: string): Codec<string> | undefined {
-    return this._byId.get(id);
-  }
-
+export interface ContractCodecRegistry {
   /**
-   * Check if a codec with the given ID is registered.
+   * Resolve the codec for `(table, column)`. Returns the per-instance parameterized codec for parameterized columns, the shared codec for non-parameterized columns, or `undefined` if the column is unknown or the codec isn't registered.
    */
-  has(id: string): boolean {
-    return this._byId.has(id);
-  }
+  forColumn(table: string, column: string): Codec | undefined;
 
   /**
-   * Get all codecs that handle a given scalar type.
-   * Returns an empty frozen array if no codecs are found.
-   * Example: registry.getByScalar('text') → [codec1, codec2, ...]
+   * Resolve a codec by id. For non-parameterized codecs this returns the canonical shared instance materialized once at context construction; for parameterized codecs it returns the column-resolved instance when a single column declares the codec id, or the `factory(undefined)` representative when the descriptor's factory is parameter-tolerant. Used by refs-less call sites; the validator pass guarantees the call site's
+   * `codecId` is non-parameterized (or parameter-tolerant) at this boundary.
    */
-  getByScalar(scalar: string): readonly Codec<string>[] {
-    return this._byScalar.get(scalar) ?? Object.freeze([]);
-  }
-
-  /**
-   * Get the default codec for a scalar type (first registered codec).
-   * Returns undefined if no codec handles this scalar type.
-   */
-  getDefaultCodec(scalar: string): Codec<string> | undefined {
-    const _codecs = this._byScalar.get(scalar);
-    return _codecs?.[0];
-  }
-
-  /**
-   * Register a codec in the registry.
-   * Throws an error if a codec with the same ID is already registered.
-   *
-   * @param codec - The codec to register
-   * @throws Error if a codec with the same ID already exists
-   */
-  register(codec: Codec<string>): void {
-    if (this._byId.has(codec.id)) {
-      throw new Error(`Codec with ID '${codec.id}' is already registered`);
-    }
-
-    this._byId.set(codec.id, codec);
-
-    // Update byScalar mapping
-    for (const scalarType of codec.targetTypes) {
-      const existing = this._byScalar.get(scalarType);
-      if (existing) {
-        existing.push(codec);
-      } else {
-        this._byScalar.set(scalarType, [codec]);
-      }
-    }
-  }
-
-  hasTrait(codecId: string, trait: CodecTrait): boolean {
-    const codec = this._byId.get(codecId);
-    return codec?.traits?.includes(trait) ?? false;
-  }
-
-  traitsOf(codecId: string): readonly CodecTrait[] {
-    return this._byId.get(codecId)?.traits ?? [];
-  }
-
-  /**
-   * Returns an iterator over all registered codecs.
-   * Useful for iterating through codecs from another registry.
-   */
-  *[Symbol.iterator](): Iterator<Codec<string>> {
-    for (const codec of this._byId.values()) {
-      yield codec;
-    }
-  }
-
-  /**
-   * Returns an iterable of all registered codecs.
-   */
-  values(): IterableIterator<Codec<string>> {
-    return this._byId.values();
-  }
+  forCodecId(codecId: string): Codec | undefined;
 }
 
 /**
- * Conditional bundle for `encodeJson`/`decodeJson`: when `TInput` is
- * structurally assignable to `JsonValue` the identity defaults are
- * sound and both fields are optional; otherwise both fields are
- * required so an author cannot silently produce a non-JSON-safe
- * contract artifact.
+ * Variance-erased descriptor type used for heterogeneous storage in collection containers and on the unified contributor `codecs:` slot. The descriptor's `factory` and `renderOutputType` are contravariant in `P`, so descriptors with different params shapes are not in a subtype relationship; collecting them into one container needs an explicit variance erasure rather than `CodecDescriptor<unknown>` (which is the
+ * narrowest, not the widest, of the family).
  */
-type JsonRoundTripConfig<TInput> = [TInput] extends [JsonValue]
-  ? {
-      encodeJson?: (value: TInput) => JsonValue;
-      decodeJson?: (json: JsonValue) => TInput;
-    }
-  : {
-      encodeJson: (value: TInput) => JsonValue;
-      decodeJson: (json: JsonValue) => TInput;
-    };
+// biome-ignore lint/suspicious/noExplicitAny: descriptor variance erasure — `P` is contravariant on the factory and renderOutputType slots, so heterogeneous descriptor storage cannot use `unknown`.
+export type AnyCodecDescriptor = CodecDescriptor<any>;
+
+type DescriptorResolvedCodec<D> =
+  D extends CodecDescriptor<infer _P> ? ReturnType<ReturnType<D['factory']>> : never;
+
+export type DescriptorCodecId<D> = D extends AnyCodecDescriptor ? D['codecId'] : never;
+
+export type DescriptorCodecInput<D> =
+  DescriptorResolvedCodec<D> extends BaseCodec<string, readonly CodecTrait[], unknown, infer In>
+    ? In
+    : never;
 
 /**
- * Construct a SQL codec from author functions and optional metadata.
- *
- * Author `encode` and `decode` as sync or async functions; the factory
- * produces a {@link Codec} whose query-time methods follow the boundary
- * contract documented on `Codec`.
+ * Resolve the trait union for a descriptor `D`.
  *
- * `encode` is optional — when omitted, an identity default is installed
- * (declaring "the input value already is the wire value", so `TInput` and
- * `TWire` are interchangeable for that codec). `decode` is always
- * required. `encodeJson` and `decodeJson` default to identity **only when
- * `TInput` is assignable to `JsonValue`**; otherwise both are required
- * so the contract artifact stays JSON-safe.
+ * Reads `traits` directly off the descriptor — concrete descriptor classes declare `override readonly traits = [...] as const`, which preserves the literal trait tuple at the descriptor type. Reading from the resolved codec instance (`CodecImpl<…, TTraits, …>`) would lose the literal because `Codec` carries `TTraits` only on its optional phantom slot (`readonly __codecTraits?: TTraits`); codecs extending `CodecImpl`
+ * have no required structural site that pins `TTraits`, so a descriptor-keyed extractor reading from the codec instance would widen to the broad `CodecTrait` union.
  */
-export function codec<
-  Id extends string,
-  const TTraits extends readonly CodecTrait[] = readonly [],
-  TWire = unknown,
-  TInput = unknown,
-  TParams = Record<string, unknown>,
-  THelper = unknown,
->(
-  config: {
-    typeId: Id;
-    targetTypes: readonly string[];
-    encode?: (value: TInput) => TWire | Promise<TWire>;
-    decode: (wire: TWire) => TInput | Promise<TInput>;
-    meta?: CodecMeta;
-    paramsSchema?: Type<TParams>;
-    init?: (params: TParams) => THelper;
-    traits?: TTraits;
-    renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
-  } & JsonRoundTripConfig<TInput>,
-): Codec<Id, TTraits, TWire, TInput, TParams, THelper> {
-  const identity = (v: unknown) => v;
-  // The synchronous identity default is only safe when the author has
-  // declared "the input is already the wire value" (i.e. TInput == TWire);
-  // it returns the value directly, never a Promise.
-  const userEncode = config.encode ?? ((value: TInput) => value as unknown as TWire);
-  const userDecode = config.decode;
-  // The conditional JsonRoundTripConfig narrows TInput|JsonValue at the
-  // boundary; widen back to the generic shape inside the factory body.
-  const widenedConfig = config as {
-    encodeJson?: (value: TInput) => JsonValue;
-    decodeJson?: (json: JsonValue) => TInput;
-  };
-  return {
-    id: config.typeId,
-    targetTypes: config.targetTypes,
-    ...ifDefined('meta', config.meta),
-    ...ifDefined('paramsSchema', config.paramsSchema),
-    ...ifDefined('init', config.init),
-    ...ifDefined(
-      'traits',
-      config.traits ? (Object.freeze([...config.traits]) as TTraits) : undefined,
-    ),
-    ...ifDefined('renderOutputType', config.renderOutputType),
-    encode: (value) => {
-      try {
-        return Promise.resolve(userEncode(value));
-      } catch (error) {
-        return Promise.reject(error);
-      }
-    },
-    decode: (wire) => {
-      try {
-        return Promise.resolve(userDecode(wire));
-      } catch (error) {
-        return Promise.reject(error);
-      }
-    },
-    encodeJson: (widenedConfig.encodeJson ?? identity) as (value: TInput) => JsonValue,
-    decodeJson: (widenedConfig.decodeJson ?? identity) as (json: JsonValue) => TInput,
-  };
+export type DescriptorCodecTraits<D> = D extends {
+  readonly traits: infer TTraits extends readonly CodecTrait[];
 }
+  ? TTraits[number] & CodecTrait
+  : never;
 
 /**
- * Type helpers to extract codec types.
- */
-export type CodecId<T> =
-  T extends Codec<infer Id> ? Id : T extends { readonly id: infer Id } ? Id : never;
-export type CodecInput<T> =
-  T extends Codec<string, readonly CodecTrait[], unknown, infer In> ? In : never;
-export type CodecTraits<T> =
-  T extends Codec<string, infer TTraits> ? TTraits[number] & CodecTrait : never;
-
-/**
- * Type helper to extract codec types from builder instance.
+ * Project a record of {@link AnyCodecDescriptor}s keyed by scalar name onto the codec-id-keyed `CodecTypes` shape consumed by emit and no-emit type pipelines (`{ readonly [codecId]: { input; output; traits } }`).
+ *
+ * Canonical extractor for the descriptor-keyed type pipeline; the legacy instance-keyed extractor and its `mkCodec`-bound builder retired alongside the carrier deletion.
  */
 export type ExtractCodecTypes<
-  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
+  ScalarNames extends {
+    readonly [K in keyof ScalarNames]: AnyCodecDescriptor;
+  } = Record<never, never>,
 > = {
-  readonly [K in keyof ScalarNames as ScalarNames[K] extends Codec<infer Id> ? Id : never]: {
-    readonly input: CodecInput<ScalarNames[K]>;
-    readonly output: CodecInput<ScalarNames[K]>;
-    readonly traits: CodecTraits<ScalarNames[K]>;
+  readonly [K in keyof ScalarNames as DescriptorCodecId<ScalarNames[K]>]: {
+    readonly input: DescriptorCodecInput<ScalarNames[K]>;
+    readonly output: DescriptorCodecInput<ScalarNames[K]>;
+    readonly traits: DescriptorCodecTraits<ScalarNames[K]>;
   };
 };
-
-/**
- * Type helper to extract data type IDs from builder instance.
- * Uses ExtractCodecTypes which preserves literal types as keys.
- * Since ExtractCodecTypes<Record<K, ScalarNames[K]>> has exactly one key (the Id),
- * we extract it by creating a mapped type that uses the Id as both key and value,
- * then extract the value type. This preserves literal types.
- */
-export type ExtractDataTypes<
-  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> },
-> = {
-  readonly [K in keyof ScalarNames]: {
-    readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
-  }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
-};
-
-/**
- * Builder interface for declaring codecs.
- */
-export interface CodecDefBuilder<
-  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
-> {
-  readonly CodecTypes: ExtractCodecTypes<ScalarNames>;
-
-  add<ScalarName extends string, CodecImpl extends Codec<string>>(
-    scalarName: ScalarName,
-    codecImpl: CodecImpl,
-  ): CodecDefBuilder<
-    O.Overwrite<ScalarNames, Record<ScalarName, CodecImpl>> & Record<ScalarName, CodecImpl>
-  >;
-
-  readonly codecDefinitions: {
-    readonly [K in keyof ScalarNames]: {
-      readonly typeId: ScalarNames[K] extends Codec<infer Id extends string> ? Id : never;
-      readonly scalar: K;
-      readonly codec: ScalarNames[K];
-      readonly input: CodecInput<ScalarNames[K]>;
-      readonly output: CodecInput<ScalarNames[K]>;
-      readonly jsType: CodecInput<ScalarNames[K]>;
-    };
-  };
-
-  readonly dataTypes: {
-    readonly [K in keyof ScalarNames]: {
-      readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
-    }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
-  };
-}
-
-/**
- * Implementation of CodecDefBuilder.
- */
-class CodecDefBuilderImpl<
-  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
-> implements CodecDefBuilder<ScalarNames>
-{
-  private readonly _codecs: ScalarNames;
-
-  public readonly CodecTypes: ExtractCodecTypes<ScalarNames>;
-  public readonly dataTypes: {
-    readonly [K in keyof ScalarNames]: {
-      readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
-    }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
-  };
-
-  constructor(codecs: ScalarNames) {
-    this._codecs = codecs;
-
-    // Populate CodecTypes from codecs
-    const codecTypes: Record<
-      string,
-      { readonly input: unknown; readonly output: unknown; readonly traits: unknown }
-    > = {};
-    for (const [, codecImpl] of Object.entries(this._codecs)) {
-      const codecImplTyped = codecImpl as Codec<string>;
-      codecTypes[codecImplTyped.id] = {
-        input: undefined as unknown as CodecInput<typeof codecImplTyped>,
-        output: undefined as unknown as CodecInput<typeof codecImplTyped>,
-        traits: undefined as unknown as CodecTraits<typeof codecImplTyped>,
-      };
-    }
-    this.CodecTypes = codecTypes as ExtractCodecTypes<ScalarNames>;
-
-    // Populate dataTypes from codecs - extract id property from each codec
-    // Build object preserving keys from ScalarNames
-    // Type assertion is safe because we know ScalarNames structure matches the return type
-    // biome-ignore lint/suspicious/noExplicitAny: dynamic codec mapping requires any
-    const dataTypes = {} as any;
-    for (const key in this._codecs) {
-      if (Object.hasOwn(this._codecs, key)) {
-        const codec = this._codecs[key] as Codec<string>;
-        dataTypes[key] = codec.id;
-      }
-    }
-    this.dataTypes = dataTypes as {
-      readonly [K in keyof ScalarNames]: {
-        readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
-      }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
-    };
-  }
-
-  add<ScalarName extends string, CodecImpl extends Codec<string>>(
-    scalarName: ScalarName,
-    codecImpl: CodecImpl,
-  ): CodecDefBuilder<
-    O.Overwrite<ScalarNames, Record<ScalarName, CodecImpl>> & Record<ScalarName, CodecImpl>
-  > {
-    return new CodecDefBuilderImpl({
-      ...this._codecs,
-      [scalarName]: codecImpl,
-    } as O.Overwrite<ScalarNames, Record<ScalarName, CodecImpl>> & Record<ScalarName, CodecImpl>);
-  }
-
-  /**
-   * Derive codecDefinitions structure.
-   */
-  get codecDefinitions(): {
-    readonly [K in keyof ScalarNames]: {
-      readonly typeId: ScalarNames[K] extends Codec<infer Id> ? Id : never;
-      readonly scalar: K;
-      readonly codec: ScalarNames[K];
-      readonly input: CodecInput<ScalarNames[K]>;
-      readonly output: CodecInput<ScalarNames[K]>;
-      readonly jsType: CodecInput<ScalarNames[K]>;
-    };
-  } {
-    const result: Record<
-      string,
-      {
-        typeId: string;
-        scalar: string;
-        codec: Codec;
-        input: unknown;
-        output: unknown;
-        jsType: unknown;
-      }
-    > = {};
-
-    for (const [scalarName, codecImpl] of Object.entries(this._codecs)) {
-      const codec = codecImpl as Codec<string>;
-      result[scalarName] = {
-        typeId: codec.id,
-        scalar: scalarName,
-        codec: codec,
-        input: undefined as unknown as CodecInput<typeof codec>,
-        output: undefined as unknown as CodecInput<typeof codec>,
-        jsType: undefined as unknown as CodecInput<typeof codec>,
-      };
-    }
-
-    return result as {
-      readonly [K in keyof ScalarNames]: {
-        readonly typeId: ScalarNames[K] extends Codec<infer Id extends string> ? Id : never;
-        readonly scalar: K;
-        readonly codec: ScalarNames[K];
-        readonly input: CodecInput<ScalarNames[K]>;
-        readonly output: CodecInput<ScalarNames[K]>;
-        readonly jsType: CodecInput<ScalarNames[K]>;
-      };
-    };
-  }
-}
-
-/**
- * Create a new codec registry.
- */
-export function createCodecRegistry(): CodecRegistry {
-  return new CodecRegistryImpl();
-}
-
-/**
- * Create a new codec definition builder.
- */
-export function defineCodecs(): CodecDefBuilder<Record<never, never>> {
-  return new CodecDefBuilderImpl({});
-}

package/src/ast/sql-codec-helpers.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared encode/decode/render constants and codec id literals for the six SQL base codecs (`sql/char@1`, `sql/varchar@1`, `sql/int@1`, `sql/float@1`, `sql/text@1`, `sql/timestamp@1`).
+ *
+ * The codec implementations live in `sql-codecs.ts` (TML-2357). This module retains only the conversion helpers + emit-path renderers the codec methods compose with — keeping a single source of truth for non-trivial conversions while the codec methods provide the framework-required `Promise<…>` boundary.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+
+export const SQL_CHAR_CODEC_ID = 'sql/char@1' as const;
+export const SQL_VARCHAR_CODEC_ID = 'sql/varchar@1' as const;
+export const SQL_INT_CODEC_ID = 'sql/int@1' as const;
+export const SQL_FLOAT_CODEC_ID = 'sql/float@1' as const;
+export const SQL_TEXT_CODEC_ID = 'sql/text@1' as const;
+export const SQL_TIMESTAMP_CODEC_ID = 'sql/timestamp@1' as const;
+
+export const sqlCharEncode = (value: string): string => value;
+export const sqlCharDecode = (wire: string): string => wire.trimEnd();
+export const sqlCharRenderOutputType = (typeParams: { readonly length?: number }) => {
+  const length = typeParams.length;
+  if (length === undefined) return undefined;
+  if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
+    throw new Error(
+      `renderOutputType: expected integer "length" in typeParams for Char, got ${String(length)}`,
+    );
+  }
+  return `Char<${length}>`;
+};
+
+export const sqlVarcharEncode = (value: string): string => value;
+export const sqlVarcharDecode = (wire: string): string => wire;
+export const sqlVarcharRenderOutputType = (typeParams: { readonly length?: number }) => {
+  const length = typeParams.length;
+  if (length === undefined) return undefined;
+  if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
+    throw new Error(
+      `renderOutputType: expected integer "length" in typeParams for Varchar, got ${String(length)}`,
+    );
+  }
+  return `Varchar<${length}>`;
+};
+
+export const sqlIntEncode = (value: number): number => value;
+export const sqlIntDecode = (wire: number): number => wire;
+
+export const sqlFloatEncode = (value: number): number => value;
+export const sqlFloatDecode = (wire: number): number => wire;
+
+export const sqlTextEncode = (value: string): string => value;
+export const sqlTextDecode = (wire: string): string => wire;
+
+export const sqlTimestampEncode = (value: Date): Date => value;
+export const sqlTimestampDecode = (wire: Date): Date => wire;
+export const sqlTimestampEncodeJson = (value: Date): JsonValue => value.toISOString();
+export const sqlTimestampDecodeJson = (json: JsonValue): Date => {
+  if (typeof json !== 'string') {
+    throw new Error(`Expected ISO date string for sql/timestamp@1, got ${typeof json}`);
+  }
+  const date = new Date(json);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid ISO date string for sql/timestamp@1: ${json}`);
+  }
+  return date;
+};
+export const sqlTimestampRenderOutputType = (typeParams: { readonly precision?: number }) => {
+  const precision = typeParams.precision;
+  if (precision === undefined) {
+    return 'Timestamp';
+  }
+  if (
+    typeof precision !== 'number' ||
+    !Number.isFinite(precision) ||
+    !Number.isInteger(precision)
+  ) {
+    throw new Error(
+      `renderOutputType: expected integer "precision" in typeParams for Timestamp, got ${String(precision)}`,
+    );
+  }
+  return `Timestamp<${precision}>`;
+};