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

package/src/execution/runtime-middleware.ts

@@ -0,0 +1,182 @@
+import type { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan, QueryPlan } from './query-plan';
+import { runtimeError } from './runtime-error';
+
+export interface RuntimeLog {
+  info(event: unknown): void;
+  warn(event: unknown): void;
+  error(event: unknown): void;
+  debug?(event: unknown): void;
+}
+
+export interface RuntimeMiddlewareContext {
+  readonly contract: unknown;
+  readonly mode: 'strict' | 'permissive';
+  readonly now: () => number;
+  readonly log: RuntimeLog;
+  /**
+   * Returns a stable string identifying the (storage, statement, params)
+   * tuple of an execution. Two semantically equivalent executions return
+   * the same string. Used by middleware that need per-execution identity
+   * (caching, request coalescing).
+   *
+   * The family runtime owns the implementation:
+   * - SQL: `meta.storageHash` + `exec.sql` + `canonicalStringify(exec.params)`
+   * - Mongo: `meta.storageHash` + `canonicalStringify({ ...exec.command })`
+   *
+   * The method is `async` because the underlying digest helper
+   * (`hashContent`) uses the WebCrypto API, whose `crypto.subtle.digest`
+   * primitive is asynchronous by design.
+   *
+   * The returned string is intended to be consumed directly as a `Map` key
+   * — it is not (and should not be) further hashed by callers.
+   */
+  contentHash(exec: ExecutionPlan): Promise<string>;
+}
+
+export interface AfterExecuteResult {
+  readonly rowCount: number;
+  readonly latencyMs: number;
+  readonly completed: boolean;
+  /**
+   * Indicates where the rows observed during this execution came from.
+   *
+   * - `'driver'` — the default. Rows came from the underlying driver via
+   *   `runDriver` / `runWithMiddleware`'s normal path.
+   * - `'middleware'` — a `RuntimeMiddleware.intercept` hook short-circuited
+   *   execution and supplied the rows directly. The driver was not invoked.
+   *
+   * Observers (telemetry, lints, budgets) that need to distinguish between
+   * driver-served and middleware-served executions read this field.
+   * Observers that don't care can ignore it.
+   */
+  readonly source: 'driver' | 'middleware';
+}
+
+/**
+ * Result of a successful `RuntimeMiddleware.intercept` hook.
+ *
+ * Carries the rows that the middleware wishes to return in place of
+ * invoking the driver. The runtime iterates `rows` in order and yields
+ * each row to the consumer; `beforeExecute`, `runDriver`, and `onRow` are
+ * all skipped on the hit path. `afterExecute` still fires with
+ * `source: 'middleware'`.
+ *
+ * `rows` accepts both `Iterable` (arrays, sync generators) and
+ * `AsyncIterable` (async generators). `for await` natively handles both
+ * via `Symbol.asyncIterator` / `Symbol.iterator` fallback, so the
+ * orchestrator does not need to branch on the variant. Cached arrays in
+ * the cache middleware are the common case; streaming variants support
+ * future use cases like mock layers replaying recordings.
+ *
+ * Row shape is `Record<string, unknown>` — the same untyped shape
+ * `onRow` receives. The SQL runtime decodes intercepted rows through its
+ * normal codec pass, so interceptors cache and return raw (undecoded)
+ * rows.
+ */
+export interface InterceptResult {
+  readonly rows: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
+}
+
+/**
+ * Family-agnostic middleware SPI parameterized over the plan marker.
+ *
+ * `TPlan` defaults to the framework `QueryPlan` marker so a generic
+ * middleware (e.g. cross-family telemetry) can be authored without
+ * naming a family. Family-specific middleware (`SqlMiddleware`,
+ * `MongoMiddleware`) narrow `TPlan` to their concrete plan type.
+ */
+export interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
+  readonly name: string;
+  readonly familyId?: string;
+  readonly targetId?: string;
+  /**
+   * Optional short-circuit hook. Runs inside `runWithMiddleware`, after
+   * the orchestrator receives the lowered plan and before any
+   * `beforeExecute` hook fires. Middleware run in registration order; the
+   * first to return a non-`undefined` `InterceptResult` wins, and
+   * subsequent middleware's `intercept` does not fire.
+   *
+   * On a hit, `beforeExecute`, `runDriver`, and `onRow` are all skipped.
+   * `afterExecute` still fires with `source: 'middleware'`.
+   *
+   * Returning `undefined` (or omitting the hook entirely) signals
+   * passthrough — execution proceeds through the normal driver path.
+   *
+   * Errors thrown inside `intercept` are rethrown by `runWithMiddleware`
+   * as the original `Error` — no envelope is guaranteed at this layer.
+   * Before rethrowing, `afterExecute` fires with `completed: false` and
+   * `source: 'middleware'`. Errors thrown by `afterExecute` during the
+   * error path remain swallowed (existing semantics, unchanged).
+   *
+   * Used by middleware that need to short-circuit execution and supply
+   * rows directly: caching, mocks, rate limiting, circuit breaking.
+   */
+  intercept?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<InterceptResult | undefined>;
+  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  afterExecute?(
+    plan: TPlan,
+    result: AfterExecuteResult,
+    ctx: RuntimeMiddlewareContext,
+  ): Promise<void>;
+}
+
+/**
+ * Optional per-`execute` options accepted by every family runtime.
+ *
+ * `signal` is the per-query cancellation signal. The runtime threads the
+ * signal through to every codec call for the query and uses it to short-
+ * circuit the row stream with `RUNTIME.ABORTED` when the caller aborts.
+ * Omitting the option (or passing `undefined`) preserves today's behavior
+ * bit-for-bit.
+ */
+export interface RuntimeExecuteOptions {
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Cross-family SPI for any runtime that can execute plans and be shut down.
+ * Each family runtime (SQL, Mongo) satisfies this interface — SQL nominally,
+ * Mongo structurally (due to its phantom Row parameter using a unique symbol).
+ *
+ * The `_row` intersection on `execute` connects the `Row` type parameter to the
+ * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
+ */
+export interface RuntimeExecutor<TPlan extends QueryPlan> {
+  execute<Row>(
+    plan: TPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row>;
+  close(): Promise<void>;
+}
+
+export function checkMiddlewareCompatibility(
+  middleware: RuntimeMiddleware,
+  runtimeFamilyId: string,
+  runtimeTargetId: string,
+): void {
+  if (middleware.targetId !== undefined && middleware.familyId === undefined) {
+    throw runtimeError(
+      'RUNTIME.MIDDLEWARE_INCOMPATIBLE',
+      `Middleware '${middleware.name}' specifies targetId '${middleware.targetId}' without familyId`,
+      { middleware: middleware.name, targetId: middleware.targetId },
+    );
+  }
+
+  if (middleware.familyId !== undefined && middleware.familyId !== runtimeFamilyId) {
+    throw runtimeError(
+      'RUNTIME.MIDDLEWARE_FAMILY_MISMATCH',
+      `Middleware '${middleware.name}' requires family '${middleware.familyId}' but the runtime is configured for family '${runtimeFamilyId}'`,
+      { middleware: middleware.name, middlewareFamilyId: middleware.familyId, runtimeFamilyId },
+    );
+  }
+
+  if (middleware.targetId !== undefined && middleware.targetId !== runtimeTargetId) {
+    throw runtimeError(
+      'RUNTIME.MIDDLEWARE_TARGET_MISMATCH',
+      `Middleware '${middleware.name}' requires target '${middleware.targetId}' but the runtime is configured for target '${runtimeTargetId}'`,
+      { middleware: middleware.name, middlewareTargetId: middleware.targetId, runtimeTargetId },
+    );
+  }
+}

package/src/exports/authoring.ts

@@ -10,13 +10,16 @@ export type {
   AuthoringTemplateValue,
   AuthoringTypeConstructorDescriptor,
   AuthoringTypeNamespace,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';
 export {
+  assertNoCrossRegistryCollisions,
+  hasRegisteredFieldNamespace,
   instantiateAuthoringFieldPreset,
   instantiateAuthoringTypeConstructor,
   isAuthoringArgRef,
   isAuthoringFieldPresetDescriptor,
   isAuthoringTypeConstructorDescriptor,
+  mergeAuthoringNamespaces,
   resolveAuthoringTemplateValue,
   validateAuthoringHelperArguments,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';

package/src/exports/codec.ts

@@ -1,2 +1,27 @@
-export type { Codec, CodecLookup, CodecTrait } from '../codec-types';
-export { emptyCodecLookup } from '../codec-types';
+/**
+ * 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 {
+  CodecCallContext,
+  CodecInstanceContext,
+  CodecLookup,
+  CodecMeta,
+  CodecTrait,
+} 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/exports/components.ts

@@ -20,5 +20,5 @@ export type {
   TargetDescriptor,
   TargetInstance,
   TargetPackRef,
-} from '../framework-components';
-export { checkContractComponentRequirements } from '../framework-components';
+} from '../shared/framework-components';
+export { checkContractComponentRequirements } from '../shared/framework-components';

package/src/exports/control.ts

@@ -1,21 +1,30 @@
-export type { MigratableTargetDescriptor, SchemaViewCapable } from '../control-capabilities';
-export { hasMigrations, hasSchemaView } from '../control-capabilities';
+export type {
+  MigratableTargetDescriptor,
+  OperationPreviewCapable,
+  PslContractInferCapable,
+  SchemaViewCapable,
+} from '../control/control-capabilities';
+export {
+  hasMigrations,
+  hasOperationPreview,
+  hasPslContractInfer,
+  hasSchemaView,
+} from '../control/control-capabilities';
 export type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
   ControlExtensionDescriptor,
   ControlFamilyDescriptor,
   ControlTargetDescriptor,
-} from '../control-descriptors';
+} from '../control/control-descriptors';
 export type {
   ControlAdapterInstance,
   ControlDriverInstance,
   ControlExtensionInstance,
   ControlFamilyInstance,
   ControlTargetInstance,
-} from '../control-instances';
+} from '../control/control-instances';
 export type {
-  DataTransformOperation,
   MigrationOperationClass,
   MigrationOperationPolicy,
   MigrationPlan,
@@ -35,7 +44,11 @@ export type {
   OpFactoryCall,
   SerializedQueryPlan,
   TargetMigrationsCapability,
-} from '../control-migration-types';
+} from '../control/control-migration-types';
+export type {
+  OperationPreview,
+  OperationPreviewStatement,
+} from '../control/control-operation-preview';
 export type {
   BaseSchemaIssue,
   EmitContractResult,
@@ -47,25 +60,25 @@ export type {
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
-} from '../control-result-types';
+} from '../control/control-result-types';
 export {
   VERIFY_CODE_HASH_MISMATCH,
   VERIFY_CODE_MARKER_MISSING,
   VERIFY_CODE_SCHEMA_FAILURE,
   VERIFY_CODE_TARGET_MISMATCH,
-} from '../control-result-types';
+} from '../control/control-result-types';
 export type {
   CoreSchemaView,
   SchemaNodeKind,
   SchemaTreeNodeOptions,
   SchemaTreeVisitor,
-} from '../control-schema-view';
-export { SchemaTreeNode } from '../control-schema-view';
+} from '../control/control-schema-view';
+export { SchemaTreeNode } from '../control/control-schema-view';
 export type {
   AssembledAuthoringContributions,
   ControlStack,
   CreateControlStackInput,
-} from '../control-stack';
+} from '../control/control-stack';
 export {
   assembleAuthoringContributions,
   assembleControlMutationDefaults,
@@ -77,7 +90,7 @@ export {
   extractComponentIds,
   extractOperationTypeImports,
   extractQueryOperationTypeImports,
-} from '../control-stack';
+} from '../control/control-stack';
 export type {
   ControlMutationDefaultEntry,
   ControlMutationDefaultRegistry,
@@ -92,4 +105,4 @@ export type {
   ParsedDefaultFunctionCall,
   SourceDiagnostic,
   SourceSpan,
-} from '../mutation-default-types';
+} from '../shared/mutation-default-types';

package/src/exports/emission.ts

@@ -2,5 +2,5 @@ export type {
   EmissionSpi,
   GenerateContractTypesOptions,
   ValidationContext,
-} from '../emission-types';
-export type { TypesImportSpec } from '../types-import-spec';
+} from '../control/emission-types';
+export type { TypesImportSpec } from '../shared/types-import-spec';

package/src/exports/execution.ts

@@ -4,14 +4,14 @@ export type {
   RuntimeExtensionDescriptor,
   RuntimeFamilyDescriptor,
   RuntimeTargetDescriptor,
-} from '../execution-descriptors';
+} from '../execution/execution-descriptors';
 export type {
   RuntimeAdapterInstance,
   RuntimeDriverInstance,
   RuntimeExtensionInstance,
   RuntimeFamilyInstance,
   RuntimeTargetInstance,
-} from '../execution-instances';
-export { assertRuntimeContractRequirementsSatisfied } from '../execution-requirements';
-export type { ExecutionStack, ExecutionStackInstance } from '../execution-stack';
-export { createExecutionStack, instantiateExecutionStack } from '../execution-stack';
+} from '../execution/execution-instances';
+export { assertRuntimeContractRequirementsSatisfied } from '../execution/execution-requirements';
+export type { ExecutionStack, ExecutionStackInstance } from '../execution/execution-stack';
+export { createExecutionStack, instantiateExecutionStack } from '../execution/execution-stack';

package/src/exports/psl-ast.ts

@@ -0,0 +1 @@
+export * from '../control/psl-ast';

package/src/exports/runtime.ts

@@ -1,11 +1,23 @@
-export { AsyncIterableResult } from '../async-iterable-result';
-export type { RuntimeErrorEnvelope } from '../runtime-error';
-export { runtimeError } from '../runtime-error';
+export { AsyncIterableResult } from '../execution/async-iterable-result';
+export type { ExecutionPlan, QueryPlan, ResultType } from '../execution/query-plan';
+export { checkAborted, raceAgainstAbort } from '../execution/race-against-abort';
+export { runWithMiddleware } from '../execution/run-with-middleware';
+export type { RuntimeCoreOptions } from '../execution/runtime-core';
+export { RuntimeCore } from '../execution/runtime-core';
+export type { RuntimeAbortedPhase, RuntimeErrorEnvelope } from '../execution/runtime-error';
+export {
+  isRuntimeError,
+  RUNTIME_ABORTED,
+  runtimeAborted,
+  runtimeError,
+} from '../execution/runtime-error';
 export type {
   AfterExecuteResult,
+  InterceptResult,
+  RuntimeExecuteOptions,
   RuntimeExecutor,
   RuntimeLog,
   RuntimeMiddleware,
   RuntimeMiddlewareContext,
-} from '../runtime-middleware';
-export { checkMiddlewareCompatibility } from '../runtime-middleware';
+} from '../execution/runtime-middleware';
+export { checkMiddlewareCompatibility } from '../execution/runtime-middleware';

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

@@ -0,0 +1,79 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Codec } from './codec';
+
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export interface CodecCallContext {
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Codec-id-keyed read surface threaded into emit and authoring paths.
+ *
+ * - `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 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.
+ *
+ * - `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.
+ */
+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.
+ */
+export interface CodecMeta {
+  readonly db?: Record<string, unknown>;
+}
+
+/**
+ * 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': {
+    version: 1,
+    vendor: 'prisma-next',
+    validate: (input) =>
+      input === undefined
+        ? { value: undefined }
+        : {
+            issues: [
+              {
+                message: 'unexpected typeParams for non-parameterized codec (void params expected)',
+              },
+            ],
+          },
+  },
+};

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;
+}