@prisma-next/framework-components 0.5.0-dev.3 → 0.5.0-dev.31

package/src/execution/runtime-error.ts

@@ -0,0 +1,83 @@
+export interface RuntimeErrorEnvelope extends Error {
+  readonly code: string;
+  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+
+/**
+ * Stable code emitted by the runtime when an in-flight `execute()`
+ * is cancelled via the per-query `AbortSignal`. The envelope's
+ * `details.phase` distinguishes where the abort was observed:
+ *
+ * - `'encode'` — abort fired during `encodeParams` (SQL) or
+ *   `resolveValue` (Mongo).
+ * - `'decode'` — abort fired during `decodeRow` / `decodeField`.
+ * - `'stream'` — abort fired between rows or before any codec call
+ *   (already-aborted at entry).
+ */
+export const RUNTIME_ABORTED = 'RUNTIME.ABORTED' as const;
+
+/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
+export type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream';
+
+/**
+ * Type guard for the runtime-error envelope produced by `runtimeError`.
+ *
+ * Prefer this over duck-typing on `error.code` directly so consumers stay
+ * insulated from the envelope's internal shape.
+ */
+export function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof (error as { code?: unknown }).code === 'string' &&
+    'category' in error &&
+    'severity' in error
+  );
+}
+
+export function runtimeError(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>,
+): RuntimeErrorEnvelope {
+  const error = new Error(message) as RuntimeErrorEnvelope;
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+
+  return Object.assign(error, {
+    code,
+    category: resolveCategory(code),
+    severity: 'error' as const,
+    message,
+    details,
+  });
+}
+
+function resolveCategory(code: string): RuntimeErrorEnvelope['category'] {
+  const prefix = code.split('.')[0] ?? 'RUNTIME';
+  switch (prefix) {
+    case 'PLAN':
+    case 'CONTRACT':
+    case 'LINT':
+    case 'BUDGET':
+      return prefix;
+    default:
+      return 'RUNTIME';
+  }
+}
+
+/**
+ * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
+ * abort was observed (encode / decode / stream); cause carries `signal.reason`
+ * verbatim from the platform — native abort produces a `DOMException`,
+ * explicit `controller.abort(reason)` produces whatever the caller passed.
+ * No synthesis happens here.
+ */
+export function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope {
+  const envelope = runtimeError(RUNTIME_ABORTED, `Operation aborted during ${phase}`, { phase });
+  return Object.assign(envelope, { cause });
+}

package/src/{runtime-middleware.ts → execution/runtime-middleware.ts}

@@ -1,5 +1,5 @@
-import type { PlanMeta } from '@prisma-next/contract/types';
 import type { AsyncIterableResult } from './async-iterable-result';
+import type { QueryPlan } from './query-plan';
 import { runtimeError } from './runtime-error';
 
 export interface RuntimeLog {
@@ -22,33 +22,53 @@ export interface AfterExecuteResult {
   readonly completed: boolean;
 }
 
-export interface RuntimeMiddleware {
+/**
+ * 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;
-  beforeExecute?(plan: { readonly meta: PlanMeta }, ctx: RuntimeMiddlewareContext): Promise<void>;
-  onRow?(
-    row: Record<string, unknown>,
-    plan: { readonly meta: PlanMeta },
-    ctx: RuntimeMiddlewareContext,
-  ): Promise<void>;
+  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
   afterExecute?(
-    plan: { readonly meta: PlanMeta },
+    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 `ExecutionPlan<Row>` carries a phantom `_row?: Row`.
+ * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
  */
-export interface RuntimeExecutor<TPlan extends { readonly meta: PlanMeta }> {
-  execute<Row>(plan: TPlan & { readonly _row?: Row }): AsyncIterableResult<Row>;
+export interface RuntimeExecutor<TPlan extends QueryPlan> {
+  execute<Row>(
+    plan: TPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row>;
   close(): Promise<void>;
 }
 

package/src/exports/authoring.ts

@@ -10,7 +10,7 @@ export type {
   AuthoringTemplateValue,
   AuthoringTypeConstructorDescriptor,
   AuthoringTypeNamespace,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';
 export {
   instantiateAuthoringFieldPreset,
   instantiateAuthoringTypeConstructor,
@@ -19,4 +19,4 @@ export {
   isAuthoringTypeConstructorDescriptor,
   resolveAuthoringTemplateValue,
   validateAuthoringHelperArguments,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';

package/src/exports/codec.ts

@@ -1,2 +1,14 @@
-export type { Codec, CodecLookup, CodecTrait } from '../codec-types';
-export { emptyCodecLookup } from '../codec-types';
+export type {
+  Codec,
+  CodecCallContext,
+  CodecDescriptor,
+  CodecInstanceContext,
+  CodecLookup,
+  CodecMeta,
+  CodecTrait,
+} from '../shared/codec-types';
+export {
+  emptyCodecLookup,
+  synthesizeNonParameterizedDescriptor,
+  voidParamsSchema,
+} from '../shared/codec-types';

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,19 +1,29 @@
-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,
@@ -35,7 +45,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 +61,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 +91,7 @@ export {
   extractComponentIds,
   extractOperationTypeImports,
   extractQueryOperationTypeImports,
-} from '../control-stack';
+} from '../control/control-stack';
 export type {
   ControlMutationDefaultEntry,
   ControlMutationDefaultRegistry,
@@ -92,4 +106,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,22 @@
-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,
+  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-types.ts

@@ -0,0 +1,261 @@
+import type { JsonValue } from '@prisma-next/contract/types';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
+export type CodecTrait =
+  | 'equality'
+  | 'order'
+  | 'boolean'
+  | 'numeric'
+  | 'textual'
+  /**
+   * The codec carries a per-instance `validate(value: unknown) =>
+   * JsonSchemaValidationResult` function on the resolved codec object that
+   * the framework's `JsonSchemaValidatorRegistry` consults at runtime. The
+   * trait gates the `extractValidator` cast from structurally-typed
+   * `unknown` to a typed validator view.
+   *
+   * Retirement target. The unified `CodecDescriptor` model moves
+   * validation into the resolved codec's `decode` body; the parallel
+   * `JsonSchemaValidatorRegistry` (and this trait alongside it) retires
+   * under TML-2357 (T3.5.12). Per-library JSON extensions like
+   * `@prisma-next/extension-arktype-json` already follow the new pattern.
+   */
+  | 'json-validator';
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ *
+ * Codec methods split into two groups:
+ *
+ * - **Query-time** methods (`encode`, `decode`) run per row/parameter at the
+ *   IO boundary; they are required and Promise-returning. The per-family
+ *   codec factory accepts sync or async author functions and lifts sync
+ *   ones to Promise-shaped methods automatically.
+ * - **Build-time** methods (`encodeJson`, `decodeJson`, `renderOutputType`)
+ *   run when the contract is serialized, loaded, or when client types are
+ *   emitted. They stay synchronous so contract validation and client
+ *   construction are synchronous.
+ *
+ * Target-family codec interfaces extend this base with target-shaped
+ * metadata.
+ */
+export interface Codec<
+  Id extends string = string,
+  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
+  TWire = unknown,
+  TInput = unknown,
+> {
+  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
+  readonly id: Id;
+  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
+  readonly targetTypes: readonly string[];
+  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
+  readonly traits?: TTraits;
+  /** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(value) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
+  encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;
+  /** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(wire) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
+  decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;
+  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */
+  encodeJson(value: TInput): JsonValue;
+  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */
+  decodeJson(json: JsonValue): TInput;
+  /** Produces the TypeScript output type expression for a field given its `typeParams`. Synchronous; used during contract.d.ts emission. */
+  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
+}
+
+export interface CodecLookup {
+  get(id: string): Codec | undefined;
+}
+
+export const emptyCodecLookup: CodecLookup = {
+  get: () => 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>;
+}
+
+/**
+ * Unified codec descriptor. Every codec in the framework registers through
+ * this shape — non-parameterized codecs use `P = void` and a constant
+ * factory that returns the same shared codec instance for every column;
+ * parameterized codecs use a non-empty `P` and a curried higher-order
+ * factory that returns a per-instance codec.
+ *
+ * The descriptor is the codec-id-keyed source of truth for static metadata
+ * (`traits`, `targetTypes`, `meta`) and registration concerns
+ * (`paramsSchema` for JSON-boundary validation; optional `renderOutputType`
+ * for the `contract.d.ts` emit path). The runtime `Codec` instance returned
+ * by `factory(params)(ctx)` carries only the conversion behavior.
+ *
+ * Whether a codec id "is parameterized" stops being a registration-time
+ * distinction — it's a property of `P` on the descriptor. The descriptor
+ * map indexes every descriptor by `codecId`; both `descriptorFor(codecId)`
+ * and `forColumn(table, column)` resolve through the same map without
+ * branching on parameterization.
+ *
+ * @template P - The shape of the params accepted by the factory (`void` for
+ *   non-parameterized codecs; a record like `{ length: number }` for
+ *   parameterized codecs).
+ *
+ * Codec-registry-unification project § Decision.
+ */
+export interface CodecDescriptor<P = void> {
+  /** The codec ID this descriptor applies to (e.g. `pg/vector@1`, `pg/text@1`). */
+  readonly codecId: string;
+  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
+  readonly traits: readonly CodecTrait[];
+  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
+  readonly targetTypes: readonly string[];
+  /** Optional family-specific metadata (e.g. SQL-side `db.sql.postgres.nativeType`). */
+  readonly meta?: CodecMeta;
+  /**
+   * Standard Schema validator for the factory's params. Validates JSON-
+   * sourced params at the contract boundary (PSL → IR; `contract.json` →
+   * runtime). For non-parameterized codecs (`P = void`), the schema
+   * validates `void`/`undefined` — the framework supplies no params at the
+   * call boundary.
+   */
+  readonly paramsSchema: StandardSchemaV1<P>;
+  /**
+   * Emit-path string renderer for `contract.d.ts`. Returns the TypeScript
+   * output type expression for given params (e.g. `Vector<1536>`).
+   * Optional; absent renderers cause the emitter to fall back to the
+   * codec's base output type. Non-parameterized codecs typically omit it.
+   */
+  readonly renderOutputType?: (params: P) => string | undefined;
+  /**
+   * The curried higher-order codec. For non-parameterized codecs, the
+   * factory is constant — every call returns the same shared codec
+   * instance. For parameterized codecs, the factory is called once per
+   * `storage.types` instance (or once per inline-`typeParams` column),
+   * with `ctx` carrying the column set the resulting codec serves.
+   */
+  readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;
+}
+
+/**
+ * Standard Schema validator for `void` params. Accepts only `undefined`
+ * (or absent input); rejects any other value so a contract that tries to
+ * thread `typeParams` through a non-parameterized codec id fails fast at
+ * the JSON boundary instead of silently coercing the value away. Used by
+ * the framework-supplied non-parameterized descriptor synthesizer.
+ */
+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)',
+              },
+            ],
+          },
+  },
+};
+
+/**
+ * Synthesize a `CodecDescriptor<void>` for a non-parameterized codec
+ * runtime instance. The factory is constant — every call returns the same
+ * shared codec instance — so columns sharing this codec id share one
+ * resolved codec.
+ *
+ * Codec-registry-unification spec § Decision (Case T — non-parameterized
+ * text codec). This is the bridge while non-parameterized codec
+ * contributors still register through the legacy `codecs:` slot; once they
+ * migrate to ship descriptors directly (TML-2357 T3.5.3), this synthesis
+ * steps aside.
+ */
+export function synthesizeNonParameterizedDescriptor(codec: Codec): CodecDescriptor<void> {
+  // The descriptor's `factory: (params: void) => (ctx: CodecInstanceContext)
+  // => Codec` is a constant for non-parameterized codecs — `params` is
+  // never read and the returned ctx-applier always yields the same shared
+  // codec. We rely on the descriptor's typed `factory` slot to infer the
+  // signatures rather than naming `void` locally (biome's
+  // `noConfusingVoidType` flags `void` outside return positions).
+  const sharedFactory = () => () => codec;
+  // Family-extended codecs (SQL `Codec`) carry an optional `meta` field
+  // that the base interface doesn't declare. Read it through a structural
+  // narrow so the synthesizer forwards it to the descriptor without losing
+  // type safety on the base shape.
+  const codecMeta = (codec as { readonly meta?: CodecMeta }).meta;
+  return {
+    codecId: codec.id,
+    traits: codec.traits ?? [],
+    targetTypes: codec.targetTypes,
+    paramsSchema: voidParamsSchema,
+    factory: sharedFactory,
+    ...(codecMeta !== undefined ? { meta: codecMeta } : {}),
+  };
+}

package/dist/codec-types-B58nCJiu.d.mts

@@ -1,40 +0,0 @@
-import { JsonValue } from "@prisma-next/contract/types";
-
-//#region src/codec-types.d.ts
-type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';
-/**
- * Base codec interface for all target families.
- *
- * A codec maps between three representations of a value:
- * - **JS** (`TJs`): the JavaScript type used in application code
- * - **Wire** (`TWire`): the format sent to/from the database driver
- * - **JSON** (`JsonValue`): the JSON-safe form stored in contract artifacts
- *
- * Family-specific codec interfaces (SQL `Codec`, Mongo `MongoCodec`) extend
- * this base to add family-specific metadata.
- */
-interface Codec<Id extends string = string, TTraits extends readonly CodecTrait[] = readonly CodecTrait[], TWire = unknown, TJs = unknown> {
-  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
-  readonly id: Id;
-  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
-  readonly targetTypes: readonly string[];
-  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
-  readonly traits?: TTraits;
-  /** Converts a JS value to the wire format expected by the database driver. Optional when the driver accepts the JS type directly. */
-  encode?(value: TJs): TWire;
-  /** Converts a wire value from the database driver into the JS type. */
-  decode(wire: TWire): TJs;
-  /** Converts a JS value to a JSON-safe representation for contract serialization. Called during contract emission. */
-  encodeJson(value: TJs): JsonValue;
-  /** Converts a JSON representation back to the JS type. Called during contract loading via `validateContract`. */
-  decodeJson(json: JsonValue): TJs;
-  /** Produces the TypeScript output type expression for a field given its `typeParams`. Used during contract.d.ts emission. */
-  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
-}
-interface CodecLookup {
-  get(id: string): Codec | undefined;
-}
-declare const emptyCodecLookup: CodecLookup;
-//#endregion
-export { emptyCodecLookup as i, CodecLookup as n, CodecTrait as r, Codec as t };
-//# sourceMappingURL=codec-types-B58nCJiu.d.mts.map

package/dist/codec-types-B58nCJiu.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec-types-B58nCJiu.d.mts","names":[],"sources":["../src/codec-types.ts"],"sourcesContent":[],"mappings":";;;KAEY,UAAA;;AAAZ;AAaA;;;;;;;;;AAiBoB,UAjBH,KAiBG,CAAA,WAAA,MAAA,GAAA,MAAA,EAAA,gBAAA,SAfO,UAeP,EAAA,GAAA,SAf+B,UAe/B,EAAA,EAAA,QAAA,OAAA,EAAA,MAAA,OAAA,CAAA,CAAA;EAAM;EAEP,SAAA,EAAA,EAZJ,EAYI;EAAY;EAEC,SAAA,WAAA,EAAA,SAAA,MAAA,EAAA;EAAM;EAGrB,SAAA,MAAW,CAAA,EAbR,OAcD;EAGN;iBAfI,MAAM;;eAER,QAAQ;;oBAEH,MAAM;;mBAEP,YAAY;;gCAEC;;UAGf,WAAA;mBACE;;cAGN,kBAAkB"}