@prisma-next/framework-components 0.5.0-dev.8 → 0.5.0-dev.81

package/src/exports/control.ts

@@ -1,21 +1,34 @@
-export type { MigratableTargetDescriptor, SchemaViewCapable } from '../control-capabilities';
-export { hasMigrations, hasSchemaView } from '../control-capabilities';
+export type { ImportRequirement } from '@prisma-next/ts-render';
+export type {
+  MigratableTargetDescriptor,
+  OperationPreviewCapable,
+  PslContractInferCapable,
+  SchemaViewCapable,
+} from '../control/control-capabilities';
+export {
+  hasMigrations,
+  hasMultiSpaceRunner,
+  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,
+  MigrationHints,
+  MigrationMetadata,
   MigrationOperationClass,
   MigrationOperationPolicy,
   MigrationPlan,
@@ -32,10 +45,19 @@ export type {
   MigrationRunnerResult,
   MigrationRunnerSuccessValue,
   MigrationScaffoldContext,
+  MultiSpaceCapableRunner,
+  MultiSpaceRunnerFailure,
+  MultiSpaceRunnerPerSpaceOptions,
+  MultiSpaceRunnerResult,
+  MultiSpaceRunnerSuccessValue,
   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 +69,31 @@ 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 {
+  ContractSpace,
+  ContractSpaceHeadRef,
+  MigrationPackage,
+} from '../control/control-spaces';
+export { APP_SPACE_ID } from '../control/control-spaces';
 export type {
   AssembledAuthoringContributions,
   ControlStack,
   CreateControlStackInput,
-} from '../control-stack';
+} from '../control/control-stack';
 export {
   assembleAuthoringContributions,
   assembleControlMutationDefaults,
@@ -77,7 +105,7 @@ export {
   extractComponentIds,
   extractOperationTypeImports,
   extractQueryOperationTypeImports,
-} from '../control-stack';
+} from '../control/control-stack';
 export type {
   ControlMutationDefaultEntry,
   ControlMutationDefaultRegistry,
@@ -92,4 +120,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,24 @@
-export { AsyncIterableResult } from '../async-iterable-result';
-export type { RuntimeErrorEnvelope } from '../runtime-error';
-export { isRuntimeError, 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,
+  ParamRefMutator,
+  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;
+}

package/src/shared/column-spec.ts

@@ -0,0 +1,83 @@
+/**
+ * `column()` packager + `ColumnSpec<R, P>` shape + `ColumnHelperFor<D>` variants for tying per-codec column helpers to their descriptor.
+ *
+ * `ColumnSpec<R, P>` extends {@link ColumnTypeDescriptor} so it remains a drop-in for contract authoring sites that consume `ColumnTypeDescriptor` shapes — both types live at the framework-components layer so the `extends` clause is real (no structural mirror).
+ *
+ * `column()` is a trivial, non-polymorphic packager. Generic over `R` (the codec instance type returned by the descriptor's curried factory) and `P` (the typeParams record). The framework does NOT try to infer `R` and `P` from a descriptor — that path is the variance trap. Per-codec helpers absorb the descriptor relationship instead and tie themselves to their descriptor via `satisfies ColumnHelperFor<D>` or `satisfies ColumnHelperForStrict<D>`.
+ */
+
+import type { CodecDescriptor } from './codec-descriptor';
+import type { CodecInstanceContext } from './codec-types';
+
+/**
+ * Authored column-type descriptor — the data shape an authoring site (PSL or TypeScript builders) attaches to a column to identify its codec and its native database type.
+ *
+ * Lives at the framework-components layer alongside the codec types so codec-author packages (e.g. column-spec / `column()` packagers) can extend it directly without crossing layer boundaries.
+ *
+ * @template TCodecId Narrowed codec id literal for sites that thread a specific codec id through the type system.
+ */
+export type ColumnTypeDescriptor<TCodecId extends string = string> = {
+  readonly codecId: TCodecId;
+  readonly nativeType: string;
+  readonly typeParams?: Record<string, unknown> | undefined;
+  readonly typeRef?: string;
+};
+
+/**
+ * Column spec carrying the codec factory closure alongside the {@link ColumnTypeDescriptor} fields. Codec authors return a `ColumnSpec` from per-codec column helpers; the runtime materializes the codec instance by calling `codecFactory(ctx)` once it knows the column's `CodecInstanceContext`.
+ *
+ * Extends {@link ColumnTypeDescriptor} so `ColumnSpec` instances flow directly into contract-authoring sites that consume the descriptor shape — no structural mirroring required.
+ */
+export interface ColumnSpec<R, P extends Record<string, unknown> | undefined>
+  extends ColumnTypeDescriptor {
+  readonly codecFactory: (ctx: CodecInstanceContext) => R;
+  readonly typeParams: P;
+}
+
+/**
+ * Trivial column packager. Per-codec helpers call this directly with the result of `descriptor.factory(params)` — direct method invocation binds the descriptor's method-level generic at the call site and the literal flows through `R`.
+ *
+ * `nativeType` is the column's database-native type spelling — the value the postgres adapter's migration planner, the SQL renderer's cast policy, and the contract's `meta.db.<family>.<target>.nativeType` slot read. Per-codec helpers pass the literal native-type string for their codec (e.g. `'text'`, `'int4'`, `'character varying'`); for codecs whose native-type spelling depends on parameters (none today; reserved for future shapes), the helper computes the rendered string before calling `column`. The framework does not derive the value from `codecId` — that mapping is target-specific and lives at the helper.
+ */
+export function column<R, P extends Record<string, unknown> | undefined>(
+  codecFactory: (ctx: CodecInstanceContext) => R,
+  codecId: string,
+  typeParams: P,
+  nativeType: string,
+): ColumnSpec<R, P> {
+  return {
+    codecFactory,
+    codecId,
+    typeParams,
+    nativeType,
+  };
+}
+
+/**
+ * Coarse `satisfies` shape — checks the helper's typeParams record matches the descriptor's factory params. Catches "wrong typeParams shape" wiring mistakes; does NOT catch "wrong descriptor's factory" mistakes (the codec slot is left as `unknown`).
+ *
+ * Use when the codec's `ReturnType<factory>` is unstable (e.g. heavily overloaded factories where extraction widens too much).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: variance erasure — `CodecDescriptor<P>` is invariant in P, so concrete subclasses do not extend `CodecDescriptor<unknown>`; matches the existing `AnyCodecDescriptor` pattern
+export type ColumnHelperFor<D extends CodecDescriptor<any>> = (
+  // biome-ignore lint/suspicious/noExplicitAny: helper signature is the verification subject; satisfies clauses can't narrow this without circular inference
+  ...args: any[]
+) => ColumnSpec<unknown, ColumnHelperParams<D>>;
+
+/**
+ * Strict `satisfies` shape — also checks the helper's codec is at least the *base* codec instance type the descriptor's factory returns. `ReturnType<ReturnType<D['factory']>>` widens method generics to their constraint, so this only sanity-checks the wiring at the base type level. Literal preservation comes from the direct `descriptor.factory(...)` call inside the helper, not from `satisfies`.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: variance erasure — `CodecDescriptor<P>` is invariant in P, so concrete subclasses do not extend `CodecDescriptor<unknown>`; matches the existing `AnyCodecDescriptor` pattern
+export type ColumnHelperForStrict<D extends CodecDescriptor<any>> = (
+  // biome-ignore lint/suspicious/noExplicitAny: helper signature is the verification subject; satisfies clauses can't narrow this without circular inference
+  ...args: any[]
+) => ColumnSpec<ReturnType<ReturnType<D['factory']>>, ColumnHelperParams<D>>;
+
+/**
+ * Coerce a descriptor's `factory` first parameter into the typeParams shape `ColumnSpec` accepts. Non-parameterized descriptors (factory with no params, or `params: void`) collapse to `undefined`; parameterized descriptors keep the params record shape.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: variance erasure — see above
+type ColumnHelperParams<D extends CodecDescriptor<any>> =
+  Parameters<D['factory']>[0] extends Record<string, unknown>
+    ? Parameters<D['factory']>[0]
+    : undefined;