@prisma-next/sql-relational-core 0.5.0-dev.60 → 0.5.0-dev.62

package/src/codec-descriptor-registry.ts

@@ -0,0 +1,52 @@
+import type { CodecDescriptor } from '@prisma-next/framework-components/codec';
+import type { AnyCodecDescriptor } from './ast/codec-types';
+import type { CodecDescriptorRegistry } from './query-lane-context';
+
+/**
+ * Build a {@link CodecDescriptorRegistry} from a flat descriptor list.
+ *
+ * Used by:
+ * - Each codec-shipping package's `core/registry.ts` to expose a package-scoped registry as the public consumer surface (replacing raw descriptor-array exports). See ADR 208.
+ * - The runtime's `buildExecutionContext` to construct the contract-bound combined registry from every contributor's `codecs:` slot.
+ *
+ * The descriptor map is heterogeneous in `P` — each codec id has its own params shape. The public {@link CodecDescriptorRegistry} interface widens to `CodecDescriptor<unknown>` and consumers narrow per codec id at the call site (the descriptor's `paramsSchema` validates JSON-sourced params before the factory ever sees them, so the runtime narrow is safe). The cast at registration goes through `unknown` because
+ * `CodecDescriptor<P>` is invariant in `P` (the `factory` and `renderOutputType` slots use `P` contravariantly).
+ */
+export function buildCodecDescriptorRegistry(
+  allDescriptors: ReadonlyArray<AnyCodecDescriptor>,
+): CodecDescriptorRegistry {
+  type AnyDescriptor = CodecDescriptor<unknown>;
+  const byId = new Map<string, AnyDescriptor>();
+  const byTargetType = new Map<string, Array<AnyDescriptor>>();
+
+  for (const descriptor of allDescriptors) {
+    if (byId.has(descriptor.codecId)) {
+      throw new Error(
+        `Duplicate codec descriptor id: '${descriptor.codecId}' — registered twice during registry construction. ` +
+          'Each codecId must be contributed by exactly one component (target / adapter / extension pack).',
+      );
+    }
+    const widened = descriptor as unknown as AnyDescriptor;
+    byId.set(descriptor.codecId, widened);
+    for (const targetType of descriptor.targetTypes) {
+      const list = byTargetType.get(targetType);
+      if (list) {
+        list.push(widened);
+      } else {
+        byTargetType.set(targetType, [widened]);
+      }
+    }
+  }
+
+  return {
+    descriptorFor(codecId: string): AnyDescriptor | undefined {
+      return byId.get(codecId);
+    },
+    *values(): IterableIterator<AnyDescriptor> {
+      yield* byId.values();
+    },
+    byTargetType(targetType: string): readonly AnyDescriptor[] {
+      return byTargetType.get(targetType) ?? Object.freeze([]);
+    },
+  };
+}

package/src/exports/ast.ts

@@ -1,6 +1,8 @@
 export * from '../ast/adapter-types';
 export * from '../ast/codec-types';
 export * from '../ast/driver-types';
+export * from '../ast/sql-codec-helpers';
 export * from '../ast/sql-codecs';
 export * from '../ast/types';
 export * from '../ast/util';
+export * from '../ast/validate-param-refs';

package/src/exports/codec-descriptor-registry.ts

@@ -0,0 +1 @@
+export * from '../codec-descriptor-registry';

package/src/expression.ts

@@ -7,10 +7,7 @@ import { OperationExpr, ParamRef } from './ast/types';
 export type ScopeField = { codecId: string; nullable: boolean };
 
 /**
- * A typed SQL expression. Identity is carried by the `returnType` descriptor
- * (inherited from `QueryOperationReturn` and narrowed to `T`) — distinct `T`
- * makes distinct Expression types structurally. `buildAst()` materialises the
- * underlying AST node.
+ * A typed SQL expression. Identity is carried by the `returnType` descriptor (inherited from `QueryOperationReturn` and narrowed to `T`) — distinct `T` makes distinct Expression types structurally. `buildAst()` materialises the underlying AST node.
  */
 export type Expression<T extends ScopeField> = QueryOperationReturn & {
   readonly returnType: T;
@@ -34,9 +31,9 @@ type NullSuffix<N> = N extends true ? null : never;
  * An expression or literal value targeting a specific codec.
  *
  * Accepts any of:
- *   - An `Expression` whose codec matches exactly
- *   - A raw JS value of the codec's `input` type
- *   - `null` when `Nullable` is true
+ * - An `Expression` whose codec matches exactly
+ * - A raw JS value of the codec's `input` type
+ * - `null` when `Nullable` is true
  */
 export type CodecExpression<
   CodecId extends string,
@@ -48,11 +45,9 @@ export type CodecExpression<
   | NullSuffix<Nullable>;
 
 /**
- * An expression or literal value targeting any codec whose trait set contains
- * all the required traits.
+ * An expression or literal value targeting any codec whose trait set contains all the required traits.
  *
- * Resolves the trait set to the union of matching codec identities via
- * `CodecIdsWithTrait`, then reuses `CodecExpression` for the codec-id form.
+ * Resolves the trait set to the union of matching codec identities via `CodecIdsWithTrait`, then reuses `CodecExpression` for the codec-id form.
  */
 export type TraitExpression<
   Traits extends readonly string[],
@@ -63,16 +58,42 @@ export type TraitExpression<
 /**
  * Resolve a raw value or an Expression into an AST expression node.
  *
- * When `value` is an Expression (duck-typed by its `buildAst` method), the AST
- * it wraps is returned. Otherwise the value is embedded as a ParamRef tagged
- * with `codecId` (if given). Pass `codecId` to encode the literal with a
- * specific codec — most operations do.
+ * When `value` is an Expression (duck-typed by its `buildAst` method), the AST it wraps is returned. Otherwise the value is embedded as a ParamRef tagged with `codecId` (if given) and optionally `refs: { table, column }` (if the caller knows the column-bound site).
+ *
+ * For parameterized codec ids (e.g. `pg/vector@1`), encode-side dispatch requires `refs` to select the per-instance codec — so operation implementations that compare a column to a user-supplied value should derive `refs` from the column-bound side and pass it down. Non-parameterized codec ids (e.g. `pg/int4@1`) tolerate refs-less ParamRefs; the validator pass enforces refs only for parameterized ids.
  */
-export function toExpr(value: unknown, codecId?: string): AstExpression {
+export function toExpr(
+  value: unknown,
+  codecId?: string,
+  refs?: { table: string; column: string },
+): AstExpression {
   if (isExpressionLike(value)) {
     return value.buildAst();
   }
-  return ParamRef.of(value, codecId ? { codecId } : undefined);
+  if (codecId === undefined && refs === undefined) return ParamRef.of(value);
+  return ParamRef.of(value, {
+    ...(codecId !== undefined ? { codecId } : {}),
+    ...(refs !== undefined ? { refs } : {}),
+  });
+}
+
+/**
+ * Derive `(table, column)` refs from an expression-like value when it carries column-bound metadata. Returns `undefined` for non-column-bound expressions and for raw scalar values.
+ *
+ * Two sources are consulted, in order: 1. An optional `refs` slot on the `Expression` wrapper (the SQL builder's `ExpressionImpl` records `(table, column)` for top-level fields whose AST is `IdentifierRef` — the AST stays bare to preserve SQL rendering, the metadata lives on the wrapper). 2. The wrapped AST when it's already a `ColumnRef` (the namespaced field-proxy form, or operation impls passing column-bound exprs
+ * directly).
+ *
+ * Operation implementations call this on the column-bound side of a comparison and forward the refs to {@link toExpr} on the user-value side, so the resulting `ParamRef` carries the table+column required by encode-side `forColumn` dispatch.
+ */
+export function refsOf(value: unknown): { table: string; column: string } | undefined {
+  if (!isExpressionLike(value)) return undefined;
+  const wrapperRefs = (value as { refs?: { table: string; column: string } }).refs;
+  if (wrapperRefs) return { table: wrapperRefs.table, column: wrapperRefs.column };
+  const ast = value.buildAst();
+  if (ast.kind === 'column-ref') {
+    return { table: ast.table, column: ast.column };
+  }
+  return undefined;
 }
 
 function isExpressionLike(value: unknown): value is Expression<ScopeField> {
@@ -87,9 +108,7 @@ function isExpressionLike(value: unknown): value is Expression<ScopeField> {
 export interface BuildOperationSpec<R extends ScopeField> {
   readonly method: string;
   /**
-   * The operation's arguments. The first element is the self argument (the
-   * value the operation is being applied to); the rest are the remaining
-   * user-supplied arguments.
+   * The operation's arguments. The first element is the self argument (the value the operation is being applied to); the rest are the remaining user-supplied arguments.
    */
   readonly args: readonly [AstExpression, ...AstExpression[]];
   readonly returns: R & ParamSpec;
@@ -97,9 +116,7 @@ export interface BuildOperationSpec<R extends ScopeField> {
 }
 
 /**
- * Construct an OperationExpr AST node and wrap it as a typed Expression.
- * Operation implementations use this to turn their user-facing arguments into
- * the AST node the compilation pipeline eventually lowers to SQL.
+ * Construct an OperationExpr AST node and wrap it as a typed Expression. Operation implementations use this to turn their user-facing arguments into the AST node the compilation pipeline eventually lowers to SQL.
  */
 export function buildOperation<R extends ScopeField>(spec: BuildOperationSpec<R>): Expression<R> {
   const [self, ...rest] = spec.args;

package/src/query-lane-context.ts

@@ -2,83 +2,31 @@ import type { Contract } from '@prisma-next/contract/types';
 import type { CodecDescriptor } from '@prisma-next/framework-components/codec';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlOperationRegistry } from '@prisma-next/sql-operations';
-import type { CodecRegistry, ContractCodecRegistry } from './ast/codec-types';
+import type { ContractCodecRegistry } from './ast/codec-types';
 
 /**
- * Codec-id-keyed accessor for descriptor metadata. The unified read API
- * for codec-id-keyed metadata (`traits`, `targetTypes`, `meta`) — non-
- * branching for parameterized vs. non-parameterized codecs since every
- * codec ships as (or is synthesized into) a `CodecDescriptor`.
- *
- * See codec-registry-unification spec § Decision and AC-3.
+ * Codec-id-keyed accessor for descriptor metadata. The unified read API for codec-id-keyed metadata (`traits`, `targetTypes`, `meta`) — non-branching for parameterized vs. non-parameterized codecs. Every codec ships natively as a `CodecDescriptor` through the unified `codecs:` contributor slot (see ADR 208).
  */
 export interface CodecDescriptorRegistry {
   /**
-   * Descriptors carry distinct param shapes per codec id; the registry is
-   * heterogeneous and the consumer narrows per codec.
+   * Descriptors carry distinct param shapes per codec id; the registry is heterogeneous and the consumer narrows per codec.
    */
   descriptorFor(codecId: string): CodecDescriptor<unknown> | undefined;
   /**
-   * All registered descriptors. Used by `validateCodecRegistryCompleteness`
-   * and other startup-time consumers that enumerate descriptors.
+   * All registered descriptors. Used by `validateCodecRegistryCompleteness` and other startup-time consumers that enumerate descriptors.
    */
   values(): IterableIterator<CodecDescriptor<unknown>>;
   /**
-   * Descriptors indexed by `targetTypes[i]` (each scalar type the codec
-   * advertises). Multiple descriptors may map to the same scalar type;
-   * ordering reflects registration order.
+   * Descriptors indexed by `targetTypes[i]` (each scalar type the codec advertises). Multiple descriptors may map to the same scalar type; ordering reflects registration order.
    */
   byTargetType(targetType: string): readonly CodecDescriptor<unknown>[];
 }
 
 /**
- * Registry of initialized type helpers from storage.types.
- * Each key is a type name from storage.types, and the value is:
- * - The result of the codec's init hook (if provided), or
- * - The full StorageTypeInstance metadata (codecId, nativeType, typeParams) if no init hook
+ * Registry of initialized type helpers from storage.types. Each key is a type name from storage.types, and the value is the resolved codec materialized once for that named instance via `descriptor.factory(typeParams)(ctx)` (or the raw `StorageTypeInstance` metadata for codec ids whose descriptor isn't registered).
  */
 export type TypeHelperRegistry = Record<string, unknown>;
 
-// =============================================================================
-// JSON Schema Validation Types
-// =============================================================================
-
-/**
- * A single validation error from JSON Schema validation.
- */
-export interface JsonSchemaValidationError {
-  readonly path: string;
-  readonly message: string;
-  readonly keyword: string;
-}
-
-/**
- * Result of a JSON Schema validation.
- */
-export type JsonSchemaValidationResult =
-  | { readonly valid: true }
-  | { readonly valid: false; readonly errors: ReadonlyArray<JsonSchemaValidationError> };
-
-/**
- * A compiled JSON Schema validate function.
- * Returns a structured result indicating whether the value conforms to the schema.
- */
-export type JsonSchemaValidateFn = (value: unknown) => JsonSchemaValidationResult;
-
-/**
- * Registry of compiled JSON Schema validators for columns with typed JSON/JSONB.
- *
- * Built during context creation by scanning the contract for columns whose codec
- * descriptor provides an `init` hook that returns a `{ validate }` helper.
- * Keys are `"table.column"` (e.g., `"user.metadata"`).
- */
-export interface JsonSchemaValidatorRegistry {
-  /** Get the compiled validator for a column. Key format: "table.column". */
-  get(key: string): JsonSchemaValidateFn | undefined;
-  /** Number of registered validators. */
-  readonly size: number;
-}
-
 export type MutationDefaultsOp = 'create' | 'update';
 
 export type AppliedMutationDefault = {
@@ -91,14 +39,8 @@ export type MutationDefaultsOptions = {
   readonly table: string;
   readonly values: Record<string, unknown>;
   /**
-   * Per-ORM-operation cache for generators that declare
-   * `stability: 'query'`. The caller passes the same `Map` across every
-   * `applyMutationDefaults` invocation in one bulk operation; the
-   * framework keys by `generatorId` so the same value is reused across
-   * all rows and columns. Generators with `stability: 'row'` use a
-   * fresh per-call cache the framework manages internally; generators
-   * with `stability: 'field'` skip caching entirely. Omit to make every
-   * call independent (degrades `'query'` to per-call behavior).
+   * Per-ORM-operation cache for generators that declare `stability: 'query'`. The caller passes the same `Map` across every `applyMutationDefaults` invocation in one bulk operation; the framework keys by `generatorId` so the same value is reused across all rows and columns. Generators with `stability: 'row'` use a fresh per-call cache the framework manages internally; generators with `stability: 'field'` skip caching
+   * entirely. Omit to make every call independent (degrades `'query'` to per-call behavior).
    */
   readonly defaultValueCache?: Map<string, unknown>;
 };
@@ -106,50 +48,26 @@ export type MutationDefaultsOptions = {
 /**
  * Minimal context interface for SQL query lanes.
  *
- * Lanes only need contract, operations, and codecs to build typed ASTs and attach
- * operation builders. This interface explicitly excludes runtime concerns like
- * adapters, connection management, and transaction state.
+ * Lanes only need contract, operations, and codecs to build typed ASTs and attach operation builders. This interface explicitly excludes runtime concerns like adapters, connection management, and transaction state.
  */
 export interface ExecutionContext<TContract extends Contract<SqlStorage> = Contract<SqlStorage>> {
   readonly contract: TContract;
   /**
-   * Codec registry indexed by codec id. Source of shared, non-parameterized
-   * codec instances; also used as the codec-id-only fallback at the
-   * `forCodecId` boundary while AC-5's `ParamRef.refs` plumbing remains
-   * deferred (TML-2357).
-   */
-  readonly codecs: CodecRegistry;
-  /**
-   * Contract-bound codec registry built once at context-construction time
-   * by walking the contract's columns and resolving each to its per-
-   * instance codec (parameterized columns) or the shared codec from the
-   * legacy registry (non-parameterized columns). The dispatch path
-   * (`encodeParam` / `decodeRow`) consults `forColumn(table, column)`
-   * when the call site has the ref, falling back to `forCodecId(codecId)`
-   * otherwise. Codec-registry-unification spec § AC-4.
+   * Contract-bound codec registry built once at context-construction time by walking the contract's columns and resolving each through its descriptor's factory. The dispatch path (`encodeParam` / `decodeRow`) consults `forColumn(table, column)` for column-bound call sites; `forCodecId(codecId)` is the refs-less fallback, permitted only for non-parameterized codec ids (the builder-pipeline validator pass enforces refs on
+   * every parameterized `ParamRef`). Pre-populated with one canonical instance per non-parameterized descriptor so `forCodecId` covers refs-less codec ids that no contract column declares.
    */
   readonly contractCodecs: ContractCodecRegistry;
   /**
-   * Codec-id-keyed descriptor map. Single source of truth for codec-id-
-   * keyed metadata (`traits`, `targetTypes`, `meta`) — every codec,
-   * parameterized or not, resolves through this map without branching.
-   * Codec-registry-unification spec § AC-3.
+   * Codec-id-keyed descriptor map. Single source of truth for codec-id-keyed metadata (`traits`, `targetTypes`, `meta`) — every codec, parameterized or not, resolves through this map without branching.
    */
   readonly codecDescriptors: CodecDescriptorRegistry;
   readonly queryOperations: SqlOperationRegistry;
   /**
-   * Type helper registry for parameterized types.
-   * Schema builders expose these helpers via schema.types.
+   * Type helper registry for parameterized types. Schema builders expose these helpers via schema.types.
    */
   readonly types: TypeHelperRegistry;
   /**
-   * Compiled JSON Schema validators for typed JSON/JSONB columns.
-   * Present only when the contract declares columns with JSON Schema typeParams.
-   */
-  readonly jsonSchemaValidators?: JsonSchemaValidatorRegistry;
-  /**
-   * Applies execution-time mutation defaults for the given table.
-   * Returns the applied defaults (caller-provided values always win).
+   * Applies execution-time mutation defaults for the given table. Returns the applied defaults (caller-provided values always win).
    */
   applyMutationDefaults(options: MutationDefaultsOptions): ReadonlyArray<AppliedMutationDefault>;
 }

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

@@ -1,313 +0,0 @@
-import { Type } from "arktype";
-import { JsonValue } from "@prisma-next/contract/types";
-import { Codec, CodecCallContext, CodecCallContext as CodecCallContext$1, CodecInstanceContext, CodecTrait, CodecTrait as CodecTrait$1 } from "@prisma-next/framework-components/codec";
-import { O } from "ts-toolbelt";
-
-//#region src/ast/codec-types.d.ts
-
-/**
- * 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.
- */
-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`.
- */
-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.
- */
-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
- */
-interface CodecParamsDescriptor<TParams = Record<string, unknown>, THelper = unknown> {
-  /** The codec ID this descriptor applies to (e.g., 'pg/vector@1') */
-  readonly codecId: string;
-  /**
-   * Arktype schema for validating typeParams.
-   * Used to validate both storage.types entries and inline column typeParams.
-   */
-  readonly paramsSchema: Type<TParams>;
-  /**
-   * 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;
-}
-/**
- * Codec metadata for database-specific type information.
- * Used for schema introspection and verification.
- */
-interface CodecMeta {
-  readonly db?: {
-    readonly sql?: {
-      readonly postgres?: {
-        readonly nativeType: string;
-      };
-    };
-  };
-}
-/**
- * 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`).
- *
- * `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.
- */
-interface Codec$1<Id$1 extends string = string, TTraits$1 extends readonly CodecTrait[] = readonly CodecTrait[], TWire = unknown, TInput = unknown, TParams = Record<string, unknown>, THelper = unknown> extends Codec<Id$1, TTraits$1, 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.
- */
-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$1 | 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$1 | undefined;
-}
-/**
- * Registry interface for codecs organized by ID and by contract scalar type.
- *
- * 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).
- */
-interface CodecRegistry {
-  get(id: string): Codec$1<string> | undefined;
-  has(id: string): boolean;
-  getByScalar(scalar: string): readonly Codec$1<string>[];
-  getDefaultCodec(scalar: string): Codec$1<string> | undefined;
-  register(codec: Codec$1<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$1<string>>;
-  values(): IterableIterator<Codec$1<string>>;
-}
-/**
- * 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.
- */
-declare function codec<Id$1 extends string, const TTraits$1 extends readonly CodecTrait[] = readonly [], TWire = unknown, TInput = unknown, TParams = Record<string, unknown>, THelper = unknown>(config: {
-  typeId: Id$1;
-  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$1;
-  renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
-} & JsonRoundTripConfig<TInput>): Codec$1<Id$1, TTraits$1, TWire, TInput, TParams, THelper>;
-/**
- * Type helpers to extract codec types.
- */
-type CodecId<T> = T extends Codec$1<infer Id> ? Id : T extends {
-  readonly id: infer Id;
-} ? Id : never;
-type CodecInput<T> = T extends Codec$1<string, readonly CodecTrait[], unknown, infer In> ? In : never;
-type CodecTraits<T> = T extends Codec$1<string, infer TTraits> ? TTraits[number] & CodecTrait : never;
-/**
- * Type helper to extract codec types from builder instance.
- */
-type ExtractCodecTypes<ScalarNames extends { readonly [K in keyof ScalarNames]: Codec$1<string> } = Record<never, never>> = { readonly [K in keyof ScalarNames as ScalarNames[K] extends Codec$1<infer Id> ? Id : never]: {
-  readonly input: CodecInput<ScalarNames[K]>;
-  readonly output: CodecInput<ScalarNames[K]>;
-  readonly traits: CodecTraits<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.
- */
-type ExtractDataTypes<ScalarNames extends { readonly [K in keyof ScalarNames]: Codec$1<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.
- */
-interface CodecDefBuilder<ScalarNames extends { readonly [K in keyof ScalarNames]: Codec$1<string> } = Record<never, never>> {
-  readonly CodecTypes: ExtractCodecTypes<ScalarNames>;
-  add<ScalarName extends string, CodecImpl extends Codec$1<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$1<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]>>] };
-}
-/**
- * Create a new codec registry.
- */
-declare function createCodecRegistry(): CodecRegistry;
-/**
- * Create a new codec definition builder.
- */
-declare function defineCodecs(): CodecDefBuilder<Record<never, never>>;
-//#endregion
-export { codec as _, CodecInput as a, CodecRegistry as c, ContractCodecRegistry as d, ExtractCodecTypes as f, SqlColumnRef as g, SqlCodecInstanceContext as h, CodecId as i, CodecTrait$1 as l, SqlCodecCallContext as m, CodecCallContext$1 as n, CodecMeta as o, ExtractDataTypes as p, CodecDefBuilder as r, CodecParamsDescriptor as s, Codec$1 as t, CodecTraits as u, createCodecRegistry as v, defineCodecs as y };
-//# sourceMappingURL=codec-types-DJEaWT36.d.mts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"codec-types-DJEaWT36.d.mts","names":[],"sources":["../src/ast/codec-types.ts"],"sourcesContent":[],"mappings":"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"}