@prisma-next/sql-relational-core 0.4.1 → 0.4.3

package/src/ast/codec-types.ts

@@ -1,14 +1,88 @@
 import type { JsonValue } from '@prisma-next/contract/types';
-import type { Codec as BaseCodec, CodecTrait } from '@prisma-next/framework-components/codec';
+import type {
+  Codec as BaseCodec,
+  CodecCallContext,
+  CodecInstanceContext,
+  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';
+export type { CodecCallContext, 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`.
+ *
+ * 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 SqlColumnRef {
+  readonly table: string;
+  readonly name: string;
+}
+
+/**
+ * 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 a `(value, ctx)` author function for the SQL
+ * `codec()` factory observe this type. The framework codec dispatch
+ * surface (and Mongo) sees only the base `CodecCallContext`.
+ */
+export interface SqlCodecCallContext extends CodecCallContext {
+  readonly column?: SqlColumnRef;
+}
+
+/**
+ * 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 }>;
+}
+
+/**
+ * Legacy adapter-level descriptor for parameterized codecs that require
+ * type-parameter validation at compile time. The runtime descriptor
+ * (`RuntimeParameterizedCodecDescriptor` in `@prisma-next/sql-runtime`)
+ * has migrated to the unified `CodecDescriptor<P>` shape with
+ * `factory: (P) => (CodecInstanceContext) => Codec`; this descriptor stays only because
+ * the SQL `Adapter.parameterizedCodecs()` surface still returns
+ * `CodecParamsDescriptor[]` (compile-time typeParams validation only,
+ * not runtime materialization).
+ *
+ * Retirement is tracked under TML-2357 T3.5.4 (single registration slot)
+ * — the adapter-level `parameterizedCodecs()` collapses into the unified
+ * runtime descriptor map once contributors migrate fully.
  *
  * @template TParams - The shape of the type parameters (e.g., `{ length: number }`)
  * @template THelper - The type returned by the optional `init` hook
@@ -27,6 +101,14 @@ export interface CodecParamsDescriptor<TParams = Record<string, unknown>, THelpe
    * 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.
+   *
+   * Predecessor pattern. The runtime descriptor's curried
+   * `factory: (P) => (CodecInstanceContext) => Codec` subsumes this hook — per-instance
+   * state lives on the resolved codec rather than in a parallel
+   * `TypeHelperRegistry` entry. Retirement tracked under TML-2357 T3.5.2
+   * (narrow runtime `Codec` interface) and T3.5.4 (single registration
+   * slot). Adapter-level callers reading codec-self-carried `init` should
+   * migrate to the runtime descriptor map's factory instead.
    */
   readonly init?: (params: TParams) => THelper;
 }
@@ -46,25 +128,97 @@ export interface CodecMeta {
 }
 
 /**
- * SQL codec interface — extends the framework base with SQL-specific fields.
+ * 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`).
  *
- * Codecs are pure, synchronous functions with no side effects or IO.
- * They provide deterministic conversion between database wire types and JS values,
- * and between JS values and contract JSON.
+ * `encode` and `decode` are redeclared here to narrow 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.
+ *
+ * Note: `paramsSchema` and `init` here are the legacy adapter-level slots
+ * mirrored from {@link CodecParamsDescriptor}. The runtime materialization
+ * path uses `RuntimeParameterizedCodecDescriptor` (in
+ * `@prisma-next/sql-runtime`) via the unified `CodecDescriptor<P>` shape;
+ * codec-self-carried `paramsSchema`/`init` retire under TML-2357 (T3.5.2
+ * narrows the runtime `Codec` interface; T3.5.4 collapses the parallel
+ * registration slots).
+ *
+ * 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,
-  TJs = unknown,
+  TInput = unknown,
   TParams = Record<string, unknown>,
   THelper = unknown,
-> extends BaseCodec<Id, TTraits, TWire, TJs> {
+> extends BaseCodec<Id, TTraits, TWire, TInput> {
+  encode(value: TInput, ctx: SqlCodecCallContext): Promise<TWire>;
+  decode(wire: TWire, ctx: SqlCodecCallContext): Promise<TInput>;
   readonly meta?: CodecMeta;
   readonly paramsSchema?: Type<TParams>;
+  /**
+   * Predecessor init hook. Retirement tracked under TML-2357 (T3.5.2 /
+   * T3.5.4); the unified runtime descriptor's
+   * `factory: (P) => (CodecInstanceContext) => Codec` is the replacement.
+   */
   readonly init?: (params: TParams) => THelper;
 }
 
+/**
+ * Contract-bound codec registry.
+ *
+ * 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 to either a per-
+ * instance parameterized codec (via `descriptor.factory(typeParams)(ctx)`)
+ * or the shared codec instance from the legacy `CodecRegistry` (for non-
+ * parameterized codecs). The dispatch path calls
+ * `forColumn(table, column).encode/decode(...)` and doesn't know whether
+ * the codec is parameterized.
+ *
+ * `forCodecId(codecId)` is a fallback for sites that don't carry the
+ * `(table, column)` ref through to the encode/decode call site —
+ * primarily the param-encoding path, where `ParamRef.refs` is not
+ * populated by the SQL builder today (every `ParamRef` carries `codecId`
+ * but not the column it relates to). For the parameterized codecs shipped
+ * at Phase B, encode is per-instance-stateless (pgvector formats
+ * `[v1,v2,v3]` regardless of length; JSON's `encode` is `JSON.stringify`
+ * regardless of schema), so a codec-id-keyed lookup yields a structurally
+ * equivalent encoder; the fallback is the bridge that lets the legacy
+ * `codecs:` registration retire from the dispatch path while staying as
+ * the codec-id-only source for now.
+ *
+ * The encode-side fallback is the AC-5-deferred carve-out documented in
+ * the codec-registry-unification spec § Non-functional constraints.
+ * TML-2357 retires the fallback by threading `ParamRef.refs` through
+ * column-bound construction sites.
+ */
+export interface ContractCodecRegistry {
+  /**
+   * 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.
+   */
+  forColumn(table: string, column: string): Codec | undefined;
+
+  /**
+   * Resolve a codec by id. Returns the same codec instance the legacy
+   * `CodecRegistry.get(codecId)` would return — for non-parameterized
+   * codecs that's the shared instance; for parameterized codecs that's
+   * a representative resolved instance. Used by sites that don't carry
+   * `(table, column)` through to the encode/decode call site (the AC-5
+   * carve-out path).
+   */
+  forCodecId(codecId: string): Codec | undefined;
+}
+
 /**
  * Registry interface for codecs organized by ID and by contract scalar type.
  *
@@ -180,30 +334,72 @@ class CodecRegistryImpl implements CodecRegistry {
 }
 
 /**
- * Codec factory - creates a codec with typeId and encode/decode functions.
- * Provides identity defaults for encodeJson/decodeJson when not supplied.
+ * 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.
+ */
+type JsonRoundTripConfig<TInput> = [TInput] extends [JsonValue]
+  ? {
+      encodeJson?: (value: TInput) => JsonValue;
+      decodeJson?: (json: JsonValue) => TInput;
+    }
+  : {
+      encodeJson: (value: TInput) => JsonValue;
+      decodeJson: (json: JsonValue) => TInput;
+    };
+
+/**
+ * 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`. Authors receive a second `ctx` options
+ * argument carrying the SQL-family per-call context; ignore it if you
+ * don't need it.
+ *
+ * Both `encode` and `decode` are required so `TInput` and `TWire` are
+ * always covered by an explicit author function — the factory installs
+ * no identity fallback. `encodeJson` and `decodeJson` default to identity
+ * **only when `TInput` is assignable to `JsonValue`**; otherwise both are
+ * required so the contract artifact stays JSON-safe.
  */
 export function codec<
   Id extends string,
-  const TTraits extends readonly CodecTrait[],
-  TWire,
-  TJs,
+  const TTraits extends readonly CodecTrait[] = readonly [],
+  TWire = unknown,
+  TInput = unknown,
   TParams = Record<string, unknown>,
   THelper = unknown,
->(config: {
-  typeId: Id;
-  targetTypes: readonly string[];
-  encode: (value: TJs) => TWire;
-  decode: (wire: TWire) => TJs;
-  encodeJson?: (value: TJs) => JsonValue;
-  decodeJson?: (json: JsonValue) => TJs;
-  meta?: CodecMeta;
-  paramsSchema?: Type<TParams>;
-  init?: (params: TParams) => THelper;
-  traits?: TTraits;
-  renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
-}): Codec<Id, TTraits, TWire, TJs, TParams, THelper> {
+>(
+  config: {
+    typeId: Id;
+    targetTypes: readonly string[];
+    encode: (value: TInput, ctx: SqlCodecCallContext) => TWire | Promise<TWire>;
+    decode: (wire: TWire, ctx: SqlCodecCallContext) => 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 runtime allocates one `SqlCodecCallContext` per `runtime.execute()`
+  // call (no caller-supplied `signal` produces `{}` instead of `undefined`)
+  // and threads it as a non-optional reference to every codec call. The
+  // author surface keeps the second parameter optional so single-arg
+  // `(value) => …` authors continue to satisfy the signature via
+  // TypeScript's bivariance for trailing parameters.
+  const userEncode = config.encode;
+  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,
@@ -215,10 +411,22 @@ export function codec<
       config.traits ? (Object.freeze([...config.traits]) as TTraits) : undefined,
     ),
     ...ifDefined('renderOutputType', config.renderOutputType),
-    encode: config.encode,
-    decode: config.decode,
-    encodeJson: (config.encodeJson ?? identity) as (value: TJs) => JsonValue,
-    decodeJson: (config.decodeJson ?? identity) as (json: JsonValue) => TJs,
+    encode: (value, ctx) => {
+      try {
+        return Promise.resolve(userEncode(value, ctx));
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    decode: (wire, ctx) => {
+      try {
+        return Promise.resolve(userDecode(wire, ctx));
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    encodeJson: (widenedConfig.encodeJson ?? identity) as (value: TInput) => JsonValue,
+    decodeJson: (widenedConfig.decodeJson ?? identity) as (json: JsonValue) => TInput,
   };
 }
 
@@ -228,9 +436,7 @@ export function codec<
 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 JsT> ? JsT : never;
-export type CodecOutput<T> =
-  T extends Codec<string, readonly CodecTrait[], unknown, infer JsT> ? JsT : never;
+  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;
 
@@ -242,7 +448,7 @@ export type ExtractCodecTypes<
 > = {
   readonly [K in keyof ScalarNames as ScalarNames[K] extends Codec<infer Id> ? Id : never]: {
     readonly input: CodecInput<ScalarNames[K]>;
-    readonly output: CodecOutput<ScalarNames[K]>;
+    readonly output: CodecInput<ScalarNames[K]>;
     readonly traits: CodecTraits<ScalarNames[K]>;
   };
 };
@@ -283,8 +489,8 @@ export interface CodecDefBuilder<
       readonly scalar: K;
       readonly codec: ScalarNames[K];
       readonly input: CodecInput<ScalarNames[K]>;
-      readonly output: CodecOutput<ScalarNames[K]>;
-      readonly jsType: CodecOutput<ScalarNames[K]>;
+      readonly output: CodecInput<ScalarNames[K]>;
+      readonly jsType: CodecInput<ScalarNames[K]>;
     };
   };
 
@@ -323,7 +529,7 @@ class CodecDefBuilderImpl<
       const codecImplTyped = codecImpl as Codec<string>;
       codecTypes[codecImplTyped.id] = {
         input: undefined as unknown as CodecInput<typeof codecImplTyped>,
-        output: undefined as unknown as CodecOutput<typeof codecImplTyped>,
+        output: undefined as unknown as CodecInput<typeof codecImplTyped>,
         traits: undefined as unknown as CodecTraits<typeof codecImplTyped>,
       };
     }
@@ -368,8 +574,8 @@ class CodecDefBuilderImpl<
       readonly scalar: K;
       readonly codec: ScalarNames[K];
       readonly input: CodecInput<ScalarNames[K]>;
-      readonly output: CodecOutput<ScalarNames[K]>;
-      readonly jsType: CodecOutput<ScalarNames[K]>;
+      readonly output: CodecInput<ScalarNames[K]>;
+      readonly jsType: CodecInput<ScalarNames[K]>;
     };
   } {
     const result: Record<
@@ -391,8 +597,8 @@ class CodecDefBuilderImpl<
         scalar: scalarName,
         codec: codec,
         input: undefined as unknown as CodecInput<typeof codec>,
-        output: undefined as unknown as CodecOutput<typeof codec>,
-        jsType: undefined as unknown as CodecOutput<typeof codec>,
+        output: undefined as unknown as CodecInput<typeof codec>,
+        jsType: undefined as unknown as CodecInput<typeof codec>,
       };
     }
 
@@ -402,8 +608,8 @@ class CodecDefBuilderImpl<
         readonly scalar: K;
         readonly codec: ScalarNames[K];
         readonly input: CodecInput<ScalarNames[K]>;
-        readonly output: CodecOutput<ScalarNames[K]>;
-        readonly jsType: CodecOutput<ScalarNames[K]>;
+        readonly output: CodecInput<ScalarNames[K]>;
+        readonly jsType: CodecInput<ScalarNames[K]>;
       };
     };
   }

package/src/ast/sql-codecs.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from '@prisma-next/contract/types';
 import { type as arktype } from 'arktype';
 import { codec, defineCodecs } from './codec-types';
 
@@ -104,12 +105,28 @@ const sqlTextCodec = codec({
   decode: (wire: string): string => wire,
 });
 
-const sqlTimestampCodec = codec({
+const sqlTimestampCodec = codec<
+  typeof SQL_TIMESTAMP_CODEC_ID,
+  readonly ['equality', 'order'],
+  Date,
+  Date
+>({
   typeId: SQL_TIMESTAMP_CODEC_ID,
   targetTypes: ['timestamp'],
   traits: ['equality', 'order'],
-  encode: (value: string | Date): string => (value instanceof Date ? value.toISOString() : value),
-  decode: (wire: string | Date): string => (wire instanceof Date ? wire.toISOString() : wire),
+  encode: (value: Date): Date => value,
+  decode: (wire: Date): Date => wire,
+  encodeJson: (value: Date): JsonValue => value.toISOString(),
+  decodeJson: (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;
+  },
   paramsSchema: precisionParamsSchema,
   renderOutputType: (typeParams) => {
     const precision = typeParams['precision'];