@prisma-next/framework-components 0.11.0-dev.9 → 0.12.0-dev.1

package/dist/codec-BFOsuHKK.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"codec-BFOsuHKK.d.mts","names":[],"sources":["../src/shared/codec-types.ts","../src/shared/codec-descriptor.ts","../src/shared/codec.ts"],"mappings":";;;;KAIY,UAAA;AAAZ;;;;;AAWA;;;;AAXA,UAWiB,QAAA;EAAA,SACN,OAAA;EAAA,SACA,UAAA,GAAa,SAAA;AAAA;;AAcxB;;;;;AAYA;;;;;UAZiB,gBAAA;EAAA,SACN,MAAA,GAAS,WAAA;AAAA;;;;;;;;;UAWH,WAAA;EACf,GAAA,CAAI,EAAA,WAAa,KAAA;EACjB,cAAA,CAAe,EAAA;EACf,OAAA,CAAQ,EAAA,WAAa,SAAA;EACrB,mBAAA,CAAoB,EAAA,UAAY,MAAA,EAAQ,MAAA;AAAA;AAAA,cAG7B,gBAAA,EAAkB,WAAA;;;;;AAc/B;;;UAAiB,oBAAA;EAAA,SACN,IAAA;AAAA;;;;UAMM,SAAA;EAAA,SACN,EAAA,GAAK,MAAA;AAAA;;;;cAMH,gBAAA,EAAkB,gBAAA;;;;;;;;;AA/C/B;;;;;UCDiB,eAAA;EDaW;EAAA,SCXjB,OAAA;EDYQ;EAAA,SCVR,MAAA,WAAiB,UAAA;EDac;EAAA,SCX/B,WAAA;EDWqC;EAAA,SCTrC,IAAA,GAAO,SAAA;EDMZ;EAAA,SCJK,YAAA,EAAc,gBAAA,CAAiB,CAAA;EDKxC;EAAA,SCHS,eAAA;EDIT;EAAA,SCFS,gBAAA,IAAoB,MAAA,EAAQ,CAAA;EDEhB;EAAA,SCAZ,OAAA,GAAU,MAAA,EAAQ,CAAA,MAAO,GAAA,EAAK,oBAAA,KAAyB,KAAA;AAAA;;;;;ADIlE;KCKY,kBAAA,GAAqB,eAAA;;;;ADSjC;;;;uBCAsB,mBAAA,4BAA+C,eAAA,CAAgB,OAAA;EAAA,kBACjE,OAAA;EAAA,kBACA,MAAA,WAAiB,UAAA;EAAA,kBACjB,WAAA;EAAA,SACT,IAAA,GAAO,SAAA;EAAA,kBAEE,YAAA,EAAc,gBAAA,CAAiB,OAAA;EDQtC;EAAA,ICLP,eAAA,CAAA;;EAKJ,gBAAA,CAAA,CAAkB,MAAA,EAAQ,OAAA;EDAmB;;;EAAA,SCKpC,OAAA,CACP,MAAA,EAAQ,OAAA,IACN,GAAA,EAAK,oBAAA,KAAyB,KAAA,kBAAuB,UAAA;AAAA;;;;;;;;;ADtD3D;;;;;AAYA;;;;;;;;UEViB,KAAA,sDAEU,UAAA,cAAwB,UAAA;EFS7C;EAAA,SEJK,EAAA,EAAI,EAAA;EFKb;EAAA,SEHS,aAAA,GAAgB,OAAA;EFIzB;EEFA,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,KAAA;EFEjC;EEArB,MAAA,CAAO,IAAA,EAAM,KAAA,EAAO,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,MAAA;EFChC;EECpB,UAAA,CAAW,KAAA,EAAO,MAAA,GAAS,SAAA;EFDK;EEGhC,UAAA,CAAW,IAAA,EAAM,SAAA,GAAY,MAAA;AAAA;AFA/B;;;;;AAAA,uBEQsB,SAAA,sDAEK,UAAA,cAAwB,UAAA,kDAGtC,KAAA,CAAM,EAAA,EAAI,OAAA,EAAS,KAAA,EAAO,MAAA;EAAA,SAMT,UAAA,EAAY,eAAA;;;;cAAZ,UAAA,EAAY,eAAA;EAAA,IAEpC,EAAA,CAAA,GAAM,EAAA;EAAA,SAID,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,KAAA;EAAA,SACtD,MAAA,CAAO,IAAA,EAAM,KAAA,EAAO,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,MAAA;EAAA,SACpD,UAAA,CAAW,KAAA,EAAO,MAAA,GAAS,SAAA;EAAA,SAC3B,UAAA,CAAW,IAAA,EAAM,SAAA,GAAY,MAAA;AAAA"}
+{"version":3,"file":"codec-BFOsuHKK.d.mts","names":[],"sources":["../src/shared/codec-types.ts","../src/shared/codec-descriptor.ts","../src/shared/codec.ts"],"mappings":";;;;KAIY,UAAA;AAAZ;;;;AAAsB;AAWtB;;;;AAXA,UAWiB,QAAA;EAAA,SACN,OAAA;EAAA,SACA,UAAA,GAAa,SAAS;AAAA;AAAA;AAcjC;;;;AAC+B;AAW/B;;;;;AA1BiC,UAchB,gBAAA;EAAA,SACN,MAAA,GAAS,WAAW;AAAA;;;;;;;;;UAWd,WAAA;EACf,GAAA,CAAI,EAAA,WAAa,KAAA;EACjB,cAAA,CAAe,EAAA;EACf,OAAA,CAAQ,EAAA,WAAa,SAAA;EACrB,mBAAA,CAAoB,EAAA,UAAY,MAAA,EAAQ,MAAA;AAAA;AAAA,cAG7B,gBAAA,EAAkB,WAK9B;;;;AAAA;AASD;;;UAAiB,oBAAA;EAAA,SACN,IAAI;AAAA;;;;UAME,SAAA;EAAA,SACN,EAAA,GAAK,MAAM;AAAA;;;AAMyB;cAAlC,gBAAA,EAAkB,gBAAgB;;;;;;;;AA7Dd;AAcjC;;;;AAC+B;UCFd,eAAA;EDaW;EAAA,SCXjB,OAAA;EDYQ;EAAA,SCVR,MAAA,WAAiB,UAAA;EDac;EAAA,SCX/B,WAAA;EDWqC;EAAA,SCTrC,IAAA,GAAO,SAAA;EDMZ;EAAA,SCJK,YAAA,EAAc,gBAAA,CAAiB,CAAA;EDKxC;EAAA,SCHS,eAAA;EDIT;EAAA,SCFS,gBAAA,IAAoB,MAAA,EAAQ,CAAA;EDEhB;EAAA,SCAZ,OAAA,GAAU,MAAA,EAAQ,CAAA,MAAO,GAAA,EAAK,oBAAA,KAAyB,KAAA;AAAA;;;;ADCD;AAGjE;KCKY,kBAAA,GAAqB,eAAe;;;ADA/C;AASD;;;;uBCAsB,mBAAA,4BAA+C,eAAA,CAAgB,OAAA;EAAA,kBACjE,OAAA;EAAA,kBACA,MAAA,WAAiB,UAAA;EAAA,kBACjB,WAAA;EAAA,SACT,IAAA,GAAO,SAAA;EAAA,kBAEE,YAAA,EAAc,gBAAA,CAAiB,OAAA;EDQtC;EAAA,ICLP,eAAA,CAAA;;EAKJ,gBAAA,CAAA,CAAkB,MAAA,EAAQ,OAAA;EDAmB;;;EAAA,SCKpC,OAAA,CACP,MAAA,EAAQ,OAAA,IACN,GAAA,EAAK,oBAAA,KAAyB,KAAA,kBAAuB,UAAA;AAAA;;;;;;;;ADpE1B;AAcjC;;;;AAC+B;AAW/B;;;;;;;;UEViB,KAAA,sDAEU,UAAA,cAAwB,UAAA;EFS7C;EAAA,SEJK,EAAA,EAAI,EAAA;EFKb;EAAA,SEHS,aAAA,GAAgB,OAAA;EFIzB;EEFA,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,KAAA;EFEjC;EEArB,MAAA,CAAO,IAAA,EAAM,KAAA,EAAO,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,MAAA;EFChC;EECpB,UAAA,CAAW,KAAA,EAAO,MAAA,GAAS,SAAA;EFDK;EEGhC,UAAA,CAAW,IAAA,EAAM,SAAA,GAAY,MAAA;AAAA;AFA/B;;;;AAKC;AALD,uBEQsB,SAAA,sDAEK,UAAA,cAAwB,UAAA,kDAGtC,KAAA,CAAM,EAAA,EAAI,OAAA,EAAS,KAAA,EAAO,MAAA;EAAA,SAMT,UAAA,EAAY,eAAA;;;AFJ3B;cEIe,UAAA,EAAY,eAAA;EAAA,IAEpC,EAAA,CAAA,GAAM,EAAA;EAAA,SAID,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,KAAA;EAAA,SACtD,MAAA,CAAO,IAAA,EAAM,KAAA,EAAO,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,MAAA;EAAA,SACpD,UAAA,CAAW,KAAA,EAAO,MAAA,GAAS,SAAA;EAAA,SAC3B,UAAA,CAAW,IAAA,EAAM,SAAA,GAAY,MAAA;AAAA"}

package/dist/codec.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.mts","names":[],"sources":["../src/shared/column-spec.ts"],"mappings":";;;;;;;;;;KAkBY,oBAAA;EAAA,SACD,OAAA,EAAS,QAAA;EAAA,SACT,UAAA;EAAA,SACA,UAAA,GAAa,MAAA;EAAA,SACb,OAAA;AAAA;;;;;;UAQM,UAAA,cAAwB,MAAA,uCAC/B,oBAAA;EAAA,SACC,YAAA,GAAe,GAAA,EAAK,oBAAA,KAAyB,CAAA;EAAA,SAC7C,UAAA,EAAY,CAAA;AAAA;;;;;;iBAQP,MAAA,cAAoB,MAAA,8BAAA,CAClC,YAAA,GAAe,GAAA,EAAK,oBAAA,KAAyB,CAAA,EAC7C,OAAA,UACA,UAAA,EAAY,CAAA,EACZ,UAAA,WACC,UAAA,CAAW,CAAA,EAAG,CAAA;;AALjB;;;;KAoBY,eAAA,WAA0B,eAAA,aAEjC,IAAA,YACA,UAAA,UAAoB,kBAAA,CAAmB,CAAA;;;;KAMhC,qBAAA,WAAgC,eAAA,aAEvC,IAAA,YACA,UAAA,CAAW,UAAA,CAAW,UAAA,CAAW,CAAA,eAAgB,kBAAA,CAAmB,CAAA;;;;KAMpE,kBAAA,WAA6B,eAAA,SAChC,UAAA,CAAW,CAAA,wBAAyB,MAAA,oBAChC,UAAA,CAAW,CAAA"}
+{"version":3,"file":"codec.d.mts","names":[],"sources":["../src/shared/column-spec.ts"],"mappings":";;;;;;;;;AAsBkB;KAJN,oBAAA;EAAA,SACD,OAAA,EAAS,QAAA;EAAA,SACT,UAAA;EAAA,SACA,UAAA,GAAa,MAAM;EAAA,SACnB,OAAA;AAAA;;;;;;UAQM,UAAA,cAAwB,MAAA,uCAC/B,oBAAA;EAAA,SACC,YAAA,GAAe,GAAA,EAAK,oBAAA,KAAyB,CAAA;EAAA,SAC7C,UAAA,EAAY,CAAA;AAAA;;;;;;iBAQP,MAAA,cAAoB,MAAA,8BAAA,CAClC,YAAA,GAAe,GAAA,EAAK,oBAAA,KAAyB,CAAA,EAC7C,OAAA,UACA,UAAA,EAAY,CAAA,EACZ,UAAA,WACC,UAAA,CAAW,CAAA,EAAG,CAAA;AAbO;AAQxB;;;;AARwB,KA4BZ,eAAA,WAA0B,eAAA,aAEjC,IAAA,YACA,UAAA,UAAoB,kBAAA,CAAmB,CAAA;;;;KAMhC,qBAAA,WAAgC,eAAA,aAEvC,IAAA,YACA,UAAA,CAAW,UAAA,CAAW,UAAA,CAAW,CAAA,eAAgB,kBAAA,CAAmB,CAAA;;;;KAMpE,kBAAA,WAA6B,eAAA,SAChC,UAAA,CAAW,CAAA,wBAAyB,MAAA,oBAChC,UAAA,CAAW,CAAA"}

package/dist/codec.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"codec.mjs","names":[],"sources":["../src/shared/codec.ts","../src/shared/codec-types.ts","../src/shared/codec-descriptor.ts","../src/shared/column-spec.ts"],"sourcesContent":["/**\n * Codec interface (consumer surface) and abstract `CodecImpl` base (codec-author surface).\n *\n * 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.\n *\n * 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).\n *\n * 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.\n */\n\nimport type { JsonValue } from '@prisma-next/contract/types';\nimport type { CodecDescriptor } from './codec-descriptor';\nimport type { CodecCallContext, CodecTrait } from './codec-types';\n\n/**\n * A codec is the contract between an application value and its on-wire and on-contract-disk representations.\n *\n * 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.\n *\n * Three representations participate:\n * - **Input** (`TInput`): the JS type at the application boundary.\n * - **Wire** (`TWire`): the format exchanged with the database driver.\n * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.\n *\n * 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)`.\n *\n * Codec methods split into two groups:\n *\n * - **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.\n * - **Build-time** methods (`encodeJson`, `decodeJson`) run when the contract is serialized or loaded. They stay synchronous so contract validation and client construction are synchronous.\n *\n * 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.\n */\nexport interface Codec<\n  Id extends string = string,\n  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],\n  TWire = unknown,\n  TInput = unknown,\n> {\n  /** 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. */\n  readonly id: Id;\n  /** 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). */\n  readonly __codecTraits?: TTraits;\n  /** 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. */\n  encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;\n  /** 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. */\n  decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;\n  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */\n  encodeJson(value: TInput): JsonValue;\n  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `family.deserializeContract`. */\n  decodeJson(json: JsonValue): TInput;\n}\n\n/**\n * Abstract base class for concrete codec implementations.\n *\n * 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}.\n */\nexport abstract class CodecImpl<\n  Id extends string = string,\n  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],\n  TWire = unknown,\n  TInput = unknown,\n> implements Codec<Id, TTraits, TWire, TInput>\n{\n  /**\n   * 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`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: variance-erased descriptor reference; subclasses retain typed access via their own state\n  constructor(public readonly descriptor: CodecDescriptor<any>) {}\n\n  get id(): Id {\n    return this.descriptor.codecId as Id;\n  }\n\n  abstract encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;\n  abstract decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;\n  abstract encodeJson(value: TInput): JsonValue;\n  abstract decodeJson(json: JsonValue): TInput;\n}\n","import type { JsonValue } from '@prisma-next/contract/types';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Codec } from './codec';\n\nexport type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';\n\n/**\n * Serializable codec identity carried by every codec-bearing AST node.\n *\n * `(codecId, typeParams?)` is the single fact the runtime needs to materialize a codec via `descriptorFor(codecId).factory(typeParams)(ctx)`. The pair is content-keyed: two refs with the same `codecId` and structurally equal `typeParams` (regardless of object key ordering) resolve to the same memoized {@link Codec} instance.\n *\n * `typeParams` is `JsonValue`-constrained so the ref survives JSON serialization (relevant for AST-embedded migration ops). Non-parameterized codecs leave `typeParams` undefined; the descriptor's `paramsSchema` validates the value at the JSON boundary.\n *\n * Family-agnostic by design — both SQL and Mongo AST nodes carry `codec: CodecRef | undefined`, and the resolver is the only dispatch path that survives serialization.\n */\nexport interface CodecRef {\n  readonly codecId: string;\n  readonly typeParams?: JsonValue;\n}\n\n/**\n * Per-call context the runtime threads to every `codec.encode` / `codec.decode` invocation for a single `runtime.execute()` call.\n *\n * The framework-level shape is family-agnostic and carries one field:\n *\n * - `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.\n *\n * 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.\n *\n * The interface is named explicitly (not inlined) so future framework fields and family extensions can land additively without breaking codec author signatures.\n */\nexport interface CodecCallContext {\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Codec-id-keyed read surface threaded into emit and authoring paths.\n *\n * - `get(id)` returns the runtime {@link Codec} instance for the codec id (used by `family.deserializeContract` for `decodeJson` of literal column defaults).\n * - `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.\n * - `metaFor(id)` exposes the codec-id-keyed `meta` (e.g. SQL-side `db.sql.postgres.nativeType`) the runtime instance no longer carries.\n * - `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.\n */\nexport interface CodecLookup {\n  get(id: string): Codec | undefined;\n  targetTypesFor(id: string): readonly string[] | undefined;\n  metaFor(id: string): CodecMeta | undefined;\n  renderOutputTypeFor(id: string, params: Record<string, unknown>): string | undefined;\n}\n\nexport const emptyCodecLookup: CodecLookup = {\n  get: () => undefined,\n  targetTypesFor: () => undefined,\n  metaFor: () => undefined,\n  renderOutputTypeFor: () => undefined,\n};\n\n/**\n * 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.\n *\n * - `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, an inline-column sentinel (`<col:Document.embedding>`) for inline-`typeParams` columns, a shared codec-id sentinel (`<codec:pg/text@1>`) for non-parameterized codec ids, or the canonical cache key (`<codecId>:<canonicalizeJson(typeParams)>`) for ad-hoc refs the contract walk did not pre-populate. Other families pick the analogous identity for their materialization sites.\n *\n * 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.\n */\nexport interface CodecInstanceContext {\n  readonly name: string;\n}\n\n/**\n * 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.\n */\nexport interface CodecMeta {\n  readonly db?: Record<string, unknown>;\n}\n\n/**\n * 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.\n */\nexport const voidParamsSchema: StandardSchemaV1<void> = {\n  '~standard': {\n    version: 1,\n    vendor: 'prisma-next',\n    validate: (input) =>\n      input === undefined\n        ? { value: undefined }\n        : {\n            issues: [\n              {\n                message: 'unexpected typeParams for non-parameterized codec (void params expected)',\n              },\n            ],\n          },\n  },\n};\n","/**\n * Codec descriptor interface (consumer surface) and abstract `CodecDescriptorImpl` base (codec-author surface).\n *\n * 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.\n *\n * 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.\n *\n * 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.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Codec } from './codec';\nimport {\n  type CodecInstanceContext,\n  type CodecMeta,\n  type CodecTrait,\n  voidParamsSchema,\n} from './codec-types';\n\n/**\n * 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.\n *\n * 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.\n *\n * 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.\n *\n * @template P - The shape of the params accepted by the factory (`void` for non-parameterized codecs; a record like `{ length: number }` for parameterized codecs).\n *\n * Codec-registry-unification project § Decision.\n */\nexport interface CodecDescriptor<P = void> {\n  /** The codec ID this descriptor applies to (e.g. `pg/vector@1`, `pg/text@1`). */\n  readonly codecId: string;\n  /** Semantic traits for operator gating (e.g. equality, order, numeric). */\n  readonly traits: readonly CodecTrait[];\n  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */\n  readonly targetTypes: readonly string[];\n  /** Optional family-specific metadata (e.g. SQL-side `db.sql.postgres.nativeType`). */\n  readonly meta?: CodecMeta;\n  /** 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. */\n  readonly paramsSchema: StandardSchemaV1<P>;\n  /** Whether this descriptor is parameterized — i.e. its `paramsSchema` is something other than the singleton `voidParamsSchema`. Consumers that need to gate column-aware dispatch read this directly rather than threading a free-floating `(codecId) => boolean` callback. */\n  readonly isParameterized: boolean;\n  /** 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. */\n  readonly renderOutputType?: (params: P) => string | undefined;\n  /** 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. */\n  readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;\n}\n\n/**\n * 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.\n *\n * Codec-registry-unification spec § Decision: every codec resolves through one descriptor map; reads are non-branching.\n */\n// biome-ignore lint/suspicious/noExplicitAny: variance erasure for heterogeneous descriptor collections\nexport type AnyCodecDescriptor = CodecDescriptor<any>;\n\n/**\n * Abstract base class for concrete codec descriptors.\n *\n * Codec authors extend this class with their typed `TParams` and declare `codecId`, `traits`, `targetTypes`, `paramsSchema`, the curried `factory(params)`, and (optionally) `renderOutputType`.\n *\n * Implements the {@link CodecDescriptor} interface so a concrete subclass instance is directly usable wherever the framework expects a `CodecDescriptor<P>`.\n */\nexport abstract class CodecDescriptorImpl<TParams = void> implements CodecDescriptor<TParams> {\n  abstract readonly codecId: string;\n  abstract readonly traits: readonly CodecTrait[];\n  abstract readonly targetTypes: readonly string[];\n  readonly meta?: CodecMeta;\n\n  abstract readonly paramsSchema: StandardSchemaV1<TParams>;\n\n  /** Boolean derived from `paramsSchema`: `true` whenever the schema is not the singleton `voidParamsSchema`. */\n  get isParameterized(): boolean {\n    return this.paramsSchema !== voidParamsSchema;\n  }\n\n  /** 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. */\n  renderOutputType?(params: TParams): string | undefined;\n\n  /**\n   * 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.\n   */\n  abstract factory(\n    params: TParams,\n  ): (ctx: CodecInstanceContext) => Codec<string, readonly CodecTrait[], unknown, unknown>;\n}\n","/**\n * `column()` packager + `ColumnSpec<R, P>` shape + `ColumnHelperFor<D>` variants for tying per-codec column helpers to their descriptor.\n *\n * `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).\n *\n * `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>`.\n */\n\nimport type { CodecDescriptor } from './codec-descriptor';\nimport type { CodecInstanceContext } from './codec-types';\n\n/**\n * 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.\n *\n * 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.\n *\n * @template TCodecId Narrowed codec id literal for sites that thread a specific codec id through the type system.\n */\nexport type ColumnTypeDescriptor<TCodecId extends string = string> = {\n  readonly codecId: TCodecId;\n  readonly nativeType: string;\n  readonly typeParams?: Record<string, unknown> | undefined;\n  readonly typeRef?: string;\n};\n\n/**\n * 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`.\n *\n * Extends {@link ColumnTypeDescriptor} so `ColumnSpec` instances flow directly into contract-authoring sites that consume the descriptor shape — no structural mirroring required.\n */\nexport interface ColumnSpec<R, P extends Record<string, unknown> | undefined>\n  extends ColumnTypeDescriptor {\n  readonly codecFactory: (ctx: CodecInstanceContext) => R;\n  readonly typeParams: P;\n}\n\n/**\n * 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`.\n *\n * `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.\n */\nexport function column<R, P extends Record<string, unknown> | undefined>(\n  codecFactory: (ctx: CodecInstanceContext) => R,\n  codecId: string,\n  typeParams: P,\n  nativeType: string,\n): ColumnSpec<R, P> {\n  return {\n    codecFactory,\n    codecId,\n    typeParams,\n    nativeType,\n  };\n}\n\n/**\n * 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`).\n *\n * Use when the codec's `ReturnType<factory>` is unstable (e.g. heavily overloaded factories where extraction widens too much).\n */\n// 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\nexport type ColumnHelperFor<D extends CodecDescriptor<any>> = (\n  // biome-ignore lint/suspicious/noExplicitAny: helper signature is the verification subject; satisfies clauses can't narrow this without circular inference\n  ...args: any[]\n) => ColumnSpec<unknown, ColumnHelperParams<D>>;\n\n/**\n * 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`.\n */\n// 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\nexport type ColumnHelperForStrict<D extends CodecDescriptor<any>> = (\n  // biome-ignore lint/suspicious/noExplicitAny: helper signature is the verification subject; satisfies clauses can't narrow this without circular inference\n  ...args: any[]\n) => ColumnSpec<ReturnType<ReturnType<D['factory']>>, ColumnHelperParams<D>>;\n\n/**\n * 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.\n */\n// biome-ignore lint/suspicious/noExplicitAny: variance erasure — see above\ntype ColumnHelperParams<D extends CodecDescriptor<any>> =\n  Parameters<D['factory']>[0] extends Record<string, unknown>\n    ? Parameters<D['factory']>[0]\n    : undefined;\n"],"mappings":";;;;;;AA0DA,IAAsB,YAAtB,MAMA;CAK8B;;;;CAA5B,YAAY,YAAkD;EAAlC,KAAA,aAAA;;CAE5B,IAAI,KAAS;EACX,OAAO,KAAK,WAAW;;;;;ACtB3B,MAAa,mBAAgC;CAC3C,WAAW,KAAA;CACX,sBAAsB,KAAA;CACtB,eAAe,KAAA;CACf,2BAA2B,KAAA;CAC5B;;;;AAuBD,MAAa,mBAA2C,EACtD,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UACT,UAAU,KAAA,IACN,EAAE,OAAO,KAAA,GAAW,GACpB,EACE,QAAQ,CACN,EACE,SAAS,4EACV,CACF,EACF;CACR,EACF;;;;;;;;;;AC7BD,IAAsB,sBAAtB,MAA8F;CAI5F;;CAKA,IAAI,kBAA2B;EAC7B,OAAO,KAAK,iBAAiB;;;;;;;;;;ACjCjC,SAAgB,OACd,cACA,SACA,YACA,YACkB;CAClB,OAAO;EACL;EACA;EACA;EACA;EACD"}
+{"version":3,"file":"codec.mjs","names":[],"sources":["../src/shared/codec.ts","../src/shared/codec-types.ts","../src/shared/codec-descriptor.ts","../src/shared/column-spec.ts"],"sourcesContent":["/**\n * Codec interface (consumer surface) and abstract `CodecImpl` base (codec-author surface).\n *\n * 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.\n *\n * 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).\n *\n * 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.\n */\n\nimport type { JsonValue } from '@prisma-next/contract/types';\nimport type { CodecDescriptor } from './codec-descriptor';\nimport type { CodecCallContext, CodecTrait } from './codec-types';\n\n/**\n * A codec is the contract between an application value and its on-wire and on-contract-disk representations.\n *\n * 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.\n *\n * Three representations participate:\n * - **Input** (`TInput`): the JS type at the application boundary.\n * - **Wire** (`TWire`): the format exchanged with the database driver.\n * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.\n *\n * 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)`.\n *\n * Codec methods split into two groups:\n *\n * - **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.\n * - **Build-time** methods (`encodeJson`, `decodeJson`) run when the contract is serialized or loaded. They stay synchronous so contract validation and client construction are synchronous.\n *\n * 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.\n */\nexport interface Codec<\n  Id extends string = string,\n  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],\n  TWire = unknown,\n  TInput = unknown,\n> {\n  /** 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. */\n  readonly id: Id;\n  /** 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). */\n  readonly __codecTraits?: TTraits;\n  /** 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. */\n  encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;\n  /** 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. */\n  decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;\n  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */\n  encodeJson(value: TInput): JsonValue;\n  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `family.deserializeContract`. */\n  decodeJson(json: JsonValue): TInput;\n}\n\n/**\n * Abstract base class for concrete codec implementations.\n *\n * 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}.\n */\nexport abstract class CodecImpl<\n  Id extends string = string,\n  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],\n  TWire = unknown,\n  TInput = unknown,\n> implements Codec<Id, TTraits, TWire, TInput>\n{\n  /**\n   * 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`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: variance-erased descriptor reference; subclasses retain typed access via their own state\n  constructor(public readonly descriptor: CodecDescriptor<any>) {}\n\n  get id(): Id {\n    return this.descriptor.codecId as Id;\n  }\n\n  abstract encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;\n  abstract decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;\n  abstract encodeJson(value: TInput): JsonValue;\n  abstract decodeJson(json: JsonValue): TInput;\n}\n","import type { JsonValue } from '@prisma-next/contract/types';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Codec } from './codec';\n\nexport type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';\n\n/**\n * Serializable codec identity carried by every codec-bearing AST node.\n *\n * `(codecId, typeParams?)` is the single fact the runtime needs to materialize a codec via `descriptorFor(codecId).factory(typeParams)(ctx)`. The pair is content-keyed: two refs with the same `codecId` and structurally equal `typeParams` (regardless of object key ordering) resolve to the same memoized {@link Codec} instance.\n *\n * `typeParams` is `JsonValue`-constrained so the ref survives JSON serialization (relevant for AST-embedded migration ops). Non-parameterized codecs leave `typeParams` undefined; the descriptor's `paramsSchema` validates the value at the JSON boundary.\n *\n * Family-agnostic by design — both SQL and Mongo AST nodes carry `codec: CodecRef | undefined`, and the resolver is the only dispatch path that survives serialization.\n */\nexport interface CodecRef {\n  readonly codecId: string;\n  readonly typeParams?: JsonValue;\n}\n\n/**\n * Per-call context the runtime threads to every `codec.encode` / `codec.decode` invocation for a single `runtime.execute()` call.\n *\n * The framework-level shape is family-agnostic and carries one field:\n *\n * - `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.\n *\n * 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.\n *\n * The interface is named explicitly (not inlined) so future framework fields and family extensions can land additively without breaking codec author signatures.\n */\nexport interface CodecCallContext {\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Codec-id-keyed read surface threaded into emit and authoring paths.\n *\n * - `get(id)` returns the runtime {@link Codec} instance for the codec id (used by `family.deserializeContract` for `decodeJson` of literal column defaults).\n * - `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.\n * - `metaFor(id)` exposes the codec-id-keyed `meta` (e.g. SQL-side `db.sql.postgres.nativeType`) the runtime instance no longer carries.\n * - `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.\n */\nexport interface CodecLookup {\n  get(id: string): Codec | undefined;\n  targetTypesFor(id: string): readonly string[] | undefined;\n  metaFor(id: string): CodecMeta | undefined;\n  renderOutputTypeFor(id: string, params: Record<string, unknown>): string | undefined;\n}\n\nexport const emptyCodecLookup: CodecLookup = {\n  get: () => undefined,\n  targetTypesFor: () => undefined,\n  metaFor: () => undefined,\n  renderOutputTypeFor: () => undefined,\n};\n\n/**\n * 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.\n *\n * - `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, an inline-column sentinel (`<col:Document.embedding>`) for inline-`typeParams` columns, a shared codec-id sentinel (`<codec:pg/text@1>`) for non-parameterized codec ids, or the canonical cache key (`<codecId>:<canonicalizeJson(typeParams)>`) for ad-hoc refs the contract walk did not pre-populate. Other families pick the analogous identity for their materialization sites.\n *\n * 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.\n */\nexport interface CodecInstanceContext {\n  readonly name: string;\n}\n\n/**\n * 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.\n */\nexport interface CodecMeta {\n  readonly db?: Record<string, unknown>;\n}\n\n/**\n * 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.\n */\nexport const voidParamsSchema: StandardSchemaV1<void> = {\n  '~standard': {\n    version: 1,\n    vendor: 'prisma-next',\n    validate: (input) =>\n      input === undefined\n        ? { value: undefined }\n        : {\n            issues: [\n              {\n                message: 'unexpected typeParams for non-parameterized codec (void params expected)',\n              },\n            ],\n          },\n  },\n};\n","/**\n * Codec descriptor interface (consumer surface) and abstract `CodecDescriptorImpl` base (codec-author surface).\n *\n * 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.\n *\n * 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.\n *\n * 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.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Codec } from './codec';\nimport {\n  type CodecInstanceContext,\n  type CodecMeta,\n  type CodecTrait,\n  voidParamsSchema,\n} from './codec-types';\n\n/**\n * 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.\n *\n * 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.\n *\n * 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.\n *\n * @template P - The shape of the params accepted by the factory (`void` for non-parameterized codecs; a record like `{ length: number }` for parameterized codecs).\n *\n * Codec-registry-unification project § Decision.\n */\nexport interface CodecDescriptor<P = void> {\n  /** The codec ID this descriptor applies to (e.g. `pg/vector@1`, `pg/text@1`). */\n  readonly codecId: string;\n  /** Semantic traits for operator gating (e.g. equality, order, numeric). */\n  readonly traits: readonly CodecTrait[];\n  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */\n  readonly targetTypes: readonly string[];\n  /** Optional family-specific metadata (e.g. SQL-side `db.sql.postgres.nativeType`). */\n  readonly meta?: CodecMeta;\n  /** 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. */\n  readonly paramsSchema: StandardSchemaV1<P>;\n  /** Whether this descriptor is parameterized — i.e. its `paramsSchema` is something other than the singleton `voidParamsSchema`. Consumers that need to gate column-aware dispatch read this directly rather than threading a free-floating `(codecId) => boolean` callback. */\n  readonly isParameterized: boolean;\n  /** 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. */\n  readonly renderOutputType?: (params: P) => string | undefined;\n  /** 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. */\n  readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;\n}\n\n/**\n * 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.\n *\n * Codec-registry-unification spec § Decision: every codec resolves through one descriptor map; reads are non-branching.\n */\n// biome-ignore lint/suspicious/noExplicitAny: variance erasure for heterogeneous descriptor collections\nexport type AnyCodecDescriptor = CodecDescriptor<any>;\n\n/**\n * Abstract base class for concrete codec descriptors.\n *\n * Codec authors extend this class with their typed `TParams` and declare `codecId`, `traits`, `targetTypes`, `paramsSchema`, the curried `factory(params)`, and (optionally) `renderOutputType`.\n *\n * Implements the {@link CodecDescriptor} interface so a concrete subclass instance is directly usable wherever the framework expects a `CodecDescriptor<P>`.\n */\nexport abstract class CodecDescriptorImpl<TParams = void> implements CodecDescriptor<TParams> {\n  abstract readonly codecId: string;\n  abstract readonly traits: readonly CodecTrait[];\n  abstract readonly targetTypes: readonly string[];\n  readonly meta?: CodecMeta;\n\n  abstract readonly paramsSchema: StandardSchemaV1<TParams>;\n\n  /** Boolean derived from `paramsSchema`: `true` whenever the schema is not the singleton `voidParamsSchema`. */\n  get isParameterized(): boolean {\n    return this.paramsSchema !== voidParamsSchema;\n  }\n\n  /** 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. */\n  renderOutputType?(params: TParams): string | undefined;\n\n  /**\n   * 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.\n   */\n  abstract factory(\n    params: TParams,\n  ): (ctx: CodecInstanceContext) => Codec<string, readonly CodecTrait[], unknown, unknown>;\n}\n","/**\n * `column()` packager + `ColumnSpec<R, P>` shape + `ColumnHelperFor<D>` variants for tying per-codec column helpers to their descriptor.\n *\n * `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).\n *\n * `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>`.\n */\n\nimport type { CodecDescriptor } from './codec-descriptor';\nimport type { CodecInstanceContext } from './codec-types';\n\n/**\n * 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.\n *\n * 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.\n *\n * @template TCodecId Narrowed codec id literal for sites that thread a specific codec id through the type system.\n */\nexport type ColumnTypeDescriptor<TCodecId extends string = string> = {\n  readonly codecId: TCodecId;\n  readonly nativeType: string;\n  readonly typeParams?: Record<string, unknown> | undefined;\n  readonly typeRef?: string;\n};\n\n/**\n * 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`.\n *\n * Extends {@link ColumnTypeDescriptor} so `ColumnSpec` instances flow directly into contract-authoring sites that consume the descriptor shape — no structural mirroring required.\n */\nexport interface ColumnSpec<R, P extends Record<string, unknown> | undefined>\n  extends ColumnTypeDescriptor {\n  readonly codecFactory: (ctx: CodecInstanceContext) => R;\n  readonly typeParams: P;\n}\n\n/**\n * 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`.\n *\n * `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.\n */\nexport function column<R, P extends Record<string, unknown> | undefined>(\n  codecFactory: (ctx: CodecInstanceContext) => R,\n  codecId: string,\n  typeParams: P,\n  nativeType: string,\n): ColumnSpec<R, P> {\n  return {\n    codecFactory,\n    codecId,\n    typeParams,\n    nativeType,\n  };\n}\n\n/**\n * 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`).\n *\n * Use when the codec's `ReturnType<factory>` is unstable (e.g. heavily overloaded factories where extraction widens too much).\n */\n// 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\nexport type ColumnHelperFor<D extends CodecDescriptor<any>> = (\n  // biome-ignore lint/suspicious/noExplicitAny: helper signature is the verification subject; satisfies clauses can't narrow this without circular inference\n  ...args: any[]\n) => ColumnSpec<unknown, ColumnHelperParams<D>>;\n\n/**\n * 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`.\n */\n// 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\nexport type ColumnHelperForStrict<D extends CodecDescriptor<any>> = (\n  // biome-ignore lint/suspicious/noExplicitAny: helper signature is the verification subject; satisfies clauses can't narrow this without circular inference\n  ...args: any[]\n) => ColumnSpec<ReturnType<ReturnType<D['factory']>>, ColumnHelperParams<D>>;\n\n/**\n * 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.\n */\n// biome-ignore lint/suspicious/noExplicitAny: variance erasure — see above\ntype ColumnHelperParams<D extends CodecDescriptor<any>> =\n  Parameters<D['factory']>[0] extends Record<string, unknown>\n    ? Parameters<D['factory']>[0]\n    : undefined;\n"],"mappings":";;;;;;AA0DA,IAAsB,YAAtB,MAMA;CAK8B;;;;CAA5B,YAAY,YAAkD;EAAlC,KAAA,aAAA;CAAmC;CAE/D,IAAI,KAAS;EACX,OAAO,KAAK,WAAW;CACzB;AAMF;;;AC7BA,MAAa,mBAAgC;CAC3C,WAAW,KAAA;CACX,sBAAsB,KAAA;CACtB,eAAe,KAAA;CACf,2BAA2B,KAAA;AAC7B;;;;AAuBA,MAAa,mBAA2C,EACtD,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UACT,UAAU,KAAA,IACN,EAAE,OAAO,KAAA,EAAU,IACnB,EACE,QAAQ,CACN,EACE,SAAS,2EACX,CACF,EACF;AACR,EACF;;;;;;;;;;AC7BA,IAAsB,sBAAtB,MAA8F;CAI5F;;CAKA,IAAI,kBAA2B;EAC7B,OAAO,KAAK,iBAAiB;CAC/B;AAWF;;;;;;;;AC7CA,SAAgB,OACd,cACA,SACA,YACA,YACkB;CAClB,OAAO;EACL;EACA;EACA;EACA;CACF;AACF"}

package/dist/components.d.mts

@@ -1,2 +1,34 @@
 import { S as checkContractComponentRequirements, _ as PackRefBase, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, g as FamilyPackRef, h as FamilyInstance, i as ComponentDescriptor, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, o as ContractComponentRequirementsCheckInput, p as ExtensionPackRef, r as AdapterPackRef, s as ContractComponentRequirementsCheckResult, t as AdapterDescriptor, u as DriverPackRef, v as TargetBoundComponentDescriptor, x as TargetPackRef, y as TargetDescriptor } from "./framework-components-CuoUhyB5.mjs";
-export { type AdapterDescriptor, type AdapterInstance, type AdapterPackRef, type ComponentDescriptor, type ComponentMetadata, type ContractComponentRequirementsCheckInput, type ContractComponentRequirementsCheckResult, type DriverDescriptor, type DriverInstance, type DriverPackRef, type ExtensionDescriptor, type ExtensionInstance, type ExtensionPackRef, type FamilyDescriptor, type FamilyInstance, type FamilyPackRef, type PackRefBase, type TargetBoundComponentDescriptor, type TargetDescriptor, type TargetInstance, type TargetPackRef, checkContractComponentRequirements };
+
+//#region src/shared/capabilities.d.ts
+/**
+ * Capability matrix merge primitive shared by emit-time and runtime stack composition.
+ *
+ * The CLI's `enrichContract` and the SQL runtime's `createExecutionContext` both need
+ * to fold a stack of component descriptors' `capabilities` declarations into a single
+ * matrix keyed by namespace. Keeping the primitive here lets both call sites stay
+ * byte-for-byte consistent without one depending on the other.
+ */
+/**
+ * Merge an ordered list of contributor capability declarations into a base matrix.
+ *
+ * Behaviour:
+ * - `base` and each contributor's `capabilities` are filtered through the same
+ *   structural extraction: non-plain-object namespace blocks are dropped,
+ *   non-boolean leaves inside a namespace block are dropped, and a namespace
+ *   block that ends up with zero boolean leaves is omitted entirely (so a
+ *   later contributor with a malformed namespace cannot erase a namespace
+ *   already present in `base`).
+ * - Non-plain-object `capabilities` on a contributor (including `undefined`,
+ *   `null`, arrays, primitives) are skipped silently — the contributor
+ *   contributes nothing.
+ * - Later contributors win on `(namespace, key)` collisions.
+ * - The returned object is fresh — neither `base` nor any contributor is mutated.
+ * - Output keys are sorted lexicographically at every plain-object level.
+ */
+declare function mergeCapabilityMatrices(base: Record<string, Record<string, boolean>>, contributors: ReadonlyArray<{
+  readonly capabilities?: unknown;
+}>): Record<string, Record<string, boolean>>;
+//#endregion
+export { type AdapterDescriptor, type AdapterInstance, type AdapterPackRef, type ComponentDescriptor, type ComponentMetadata, type ContractComponentRequirementsCheckInput, type ContractComponentRequirementsCheckResult, type DriverDescriptor, type DriverInstance, type DriverPackRef, type ExtensionDescriptor, type ExtensionInstance, type ExtensionPackRef, type FamilyDescriptor, type FamilyInstance, type FamilyPackRef, type PackRefBase, type TargetBoundComponentDescriptor, type TargetDescriptor, type TargetInstance, type TargetPackRef, checkContractComponentRequirements, mergeCapabilityMatrices };
+//# sourceMappingURL=components.d.mts.map

package/dist/components.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.mts","names":[],"sources":["../src/shared/capabilities.ts"],"mappings":";;;;;;AAqEA;;;;;;;;;;;;;;;;;;;AAGwB;;;iBAHR,uBAAA,CACd,IAAA,EAAM,MAAA,SAAe,MAAA,oBACrB,YAAA,EAAc,aAAA;EAAA,SAAyB,YAAA;AAAA,KACtC,MAAA,SAAe,MAAA"}

package/dist/components.mjs

@@ -1,2 +1,65 @@
 import { t as checkContractComponentRequirements } from "./framework-components-FdqmlGUj.mjs";
-export { checkContractComponentRequirements };
+import { blindCast } from "@prisma-next/utils/casts";
+//#region src/shared/capabilities.ts
+/**
+* Capability matrix merge primitive shared by emit-time and runtime stack composition.
+*
+* The CLI's `enrichContract` and the SQL runtime's `createExecutionContext` both need
+* to fold a stack of component descriptors' `capabilities` declarations into a single
+* matrix keyed by namespace. Keeping the primitive here lets both call sites stay
+* byte-for-byte consistent without one depending on the other.
+*/
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sortDeep(value) {
+	if (Array.isArray(value)) return value.map(sortDeep);
+	if (!isPlainObject(value)) return value;
+	const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+	const next = {};
+	for (const [key, child] of entries) next[key] = sortDeep(child);
+	return next;
+}
+function extractCapabilityMatrix(value) {
+	if (!isPlainObject(value)) return {};
+	const out = {};
+	for (const [namespace, maybeCaps] of Object.entries(value)) {
+		if (!isPlainObject(maybeCaps)) continue;
+		const caps = {};
+		for (const [key, flag] of Object.entries(maybeCaps)) if (typeof flag === "boolean") caps[key] = flag;
+		if (Object.keys(caps).length > 0) out[namespace] = caps;
+	}
+	return out;
+}
+/**
+* Merge an ordered list of contributor capability declarations into a base matrix.
+*
+* Behaviour:
+* - `base` and each contributor's `capabilities` are filtered through the same
+*   structural extraction: non-plain-object namespace blocks are dropped,
+*   non-boolean leaves inside a namespace block are dropped, and a namespace
+*   block that ends up with zero boolean leaves is omitted entirely (so a
+*   later contributor with a malformed namespace cannot erase a namespace
+*   already present in `base`).
+* - Non-plain-object `capabilities` on a contributor (including `undefined`,
+*   `null`, arrays, primitives) are skipped silently — the contributor
+*   contributes nothing.
+* - Later contributors win on `(namespace, key)` collisions.
+* - The returned object is fresh — neither `base` nor any contributor is mutated.
+* - Output keys are sorted lexicographically at every plain-object level.
+*/
+function mergeCapabilityMatrices(base, contributors) {
+	const merged = extractCapabilityMatrix(base);
+	for (const contributor of contributors) {
+		const extracted = extractCapabilityMatrix(contributor.capabilities);
+		for (const [namespace, capabilities] of Object.entries(extracted)) merged[namespace] = {
+			...merged[namespace] ?? {},
+			...capabilities
+		};
+	}
+	return blindCast(sortDeep(merged));
+}
+//#endregion
+export { checkContractComponentRequirements, mergeCapabilityMatrices };
+
+//# sourceMappingURL=components.mjs.map

package/dist/components.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.mjs","names":[],"sources":["../src/shared/capabilities.ts"],"sourcesContent":["/**\n * Capability matrix merge primitive shared by emit-time and runtime stack composition.\n *\n * The CLI's `enrichContract` and the SQL runtime's `createExecutionContext` both need\n * to fold a stack of component descriptors' `capabilities` declarations into a single\n * matrix keyed by namespace. Keeping the primitive here lets both call sites stay\n * byte-for-byte consistent without one depending on the other.\n */\n\nimport { blindCast } from '@prisma-next/utils/casts';\n\ntype CapabilityMatrix = Record<string, Record<string, boolean>>;\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction sortDeep(value: unknown): unknown {\n  if (Array.isArray(value)) {\n    return value.map(sortDeep);\n  }\n  if (!isPlainObject(value)) {\n    return value;\n  }\n  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));\n  const next: Record<string, unknown> = {};\n  for (const [key, child] of entries) {\n    next[key] = sortDeep(child);\n  }\n  return next;\n}\n\nfunction extractCapabilityMatrix(value: unknown): CapabilityMatrix {\n  if (!isPlainObject(value)) return {};\n\n  const out: CapabilityMatrix = {};\n  for (const [namespace, maybeCaps] of Object.entries(value)) {\n    if (!isPlainObject(maybeCaps)) continue;\n    const caps: Record<string, boolean> = {};\n    for (const [key, flag] of Object.entries(maybeCaps)) {\n      if (typeof flag === 'boolean') {\n        caps[key] = flag;\n      }\n    }\n    if (Object.keys(caps).length > 0) {\n      out[namespace] = caps;\n    }\n  }\n\n  return out;\n}\n\n/**\n * Merge an ordered list of contributor capability declarations into a base matrix.\n *\n * Behaviour:\n * - `base` and each contributor's `capabilities` are filtered through the same\n *   structural extraction: non-plain-object namespace blocks are dropped,\n *   non-boolean leaves inside a namespace block are dropped, and a namespace\n *   block that ends up with zero boolean leaves is omitted entirely (so a\n *   later contributor with a malformed namespace cannot erase a namespace\n *   already present in `base`).\n * - Non-plain-object `capabilities` on a contributor (including `undefined`,\n *   `null`, arrays, primitives) are skipped silently — the contributor\n *   contributes nothing.\n * - Later contributors win on `(namespace, key)` collisions.\n * - The returned object is fresh — neither `base` nor any contributor is mutated.\n * - Output keys are sorted lexicographically at every plain-object level.\n */\nexport function mergeCapabilityMatrices(\n  base: Record<string, Record<string, boolean>>,\n  contributors: ReadonlyArray<{ readonly capabilities?: unknown }>,\n): Record<string, Record<string, boolean>> {\n  const merged: CapabilityMatrix = extractCapabilityMatrix(base);\n\n  for (const contributor of contributors) {\n    const extracted = extractCapabilityMatrix(contributor.capabilities);\n    for (const [namespace, capabilities] of Object.entries(extracted)) {\n      merged[namespace] = {\n        ...(merged[namespace] ?? {}),\n        ...capabilities,\n      };\n    }\n  }\n\n  return blindCast<\n    CapabilityMatrix,\n    \"sortDeep preserves the matrix shape but the recursive generic relationship can't be expressed to TS\"\n  >(sortDeep(merged));\n}\n"],"mappings":";;;;;;;;;;;AAaA,SAAS,cAAc,OAAkD;CACvE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,SAAS,OAAyB;CACzC,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,IAAI,QAAQ;CAE3B,IAAI,CAAC,cAAc,KAAK,GACtB,OAAO;CAET,MAAM,UAAU,OAAO,QAAQ,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;CAC3E,MAAM,OAAgC,CAAC;CACvC,KAAK,MAAM,CAAC,KAAK,UAAU,SACzB,KAAK,OAAO,SAAS,KAAK;CAE5B,OAAO;AACT;AAEA,SAAS,wBAAwB,OAAkC;CACjE,IAAI,CAAC,cAAc,KAAK,GAAG,OAAO,CAAC;CAEnC,MAAM,MAAwB,CAAC;CAC/B,KAAK,MAAM,CAAC,WAAW,cAAc,OAAO,QAAQ,KAAK,GAAG;EAC1D,IAAI,CAAC,cAAc,SAAS,GAAG;EAC/B,MAAM,OAAgC,CAAC;EACvC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,SAAS,GAChD,IAAI,OAAO,SAAS,WAClB,KAAK,OAAO;EAGhB,IAAI,OAAO,KAAK,IAAI,EAAE,SAAS,GAC7B,IAAI,aAAa;CAErB;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,wBACd,MACA,cACyC;CACzC,MAAM,SAA2B,wBAAwB,IAAI;CAE7D,KAAK,MAAM,eAAe,cAAc;EACtC,MAAM,YAAY,wBAAwB,YAAY,YAAY;EAClE,KAAK,MAAM,CAAC,WAAW,iBAAiB,OAAO,QAAQ,SAAS,GAC9D,OAAO,aAAa;GAClB,GAAI,OAAO,cAAc,CAAC;GAC1B,GAAG;EACL;CAEJ;CAEA,OAAO,UAGL,SAAS,MAAM,CAAC;AACpB"}

package/dist/control.d.mts

@@ -6,6 +6,7 @@ import { t as EmissionSpi } from "./emission-types-CMv_053d.mjs";
 import { m as PslDocumentAst } from "./psl-ast-BDXL7iCg.mjs";
 import { Contract, ContractMarkerRecord } from "@prisma-next/contract/types";
 import { ImportRequirement, ImportRequirement as ImportRequirement$1 } from "@prisma-next/ts-render";
+import { PreserveEmptyPredicate, StorageSort } from "@prisma-next/contract/hashing";
 import { JsonObject } from "@prisma-next/utils/json";
 import { Result } from "@prisma-next/utils/result";
 
@@ -49,6 +50,22 @@ interface ContractSerializer<TContract> {
    * fields, normalizing numeric encodings) do that work here.
    */
   serializeContract(contract: TContract): JsonObject;
+  /**
+   * Optional family-contributed preserve-empty predicate for the
+   * framework canonicalizer. When present, the canonicalizer calls this
+   * inside its default-omission walk to let the family veto the stripping
+   * of empty objects/arrays/`false` values at family-specific storage paths.
+   * Families whose storage has no such special-case paths omit this hook.
+   */
+  readonly shouldPreserveEmpty?: PreserveEmptyPredicate;
+  /**
+   * Optional family-contributed storage sort hook for the framework
+   * canonicalizer. When present, the canonicalizer applies this to the
+   * serialized `storage` subtree after the omission walk and before the
+   * final key sort. Families that need deterministic ordering of storage
+   * arrays (e.g. SQL `indexes`/`uniques`) supply this hook.
+   */
+  readonly sortStorage?: StorageSort;
 }
 //#endregion
 //#region src/control/control-result-types.d.ts
@@ -114,6 +131,13 @@ interface BaseSchemaIssue {
 }
 interface EnumValuesChangedIssue {
   readonly kind: 'enum_values_changed';
+  /**
+   * Namespace coordinate of the enum type that changed values. Populated by
+   * family verifiers that have the coordinate in scope when constructing the
+   * issue. Downstream planners trust this field as the authoritative subject
+   * coordinate and do not re-derive it by name lookup.
+   */
+  readonly namespaceId: string;
   readonly typeName: string;
   readonly addedValues: readonly string[];
   readonly removedValues: readonly string[];
@@ -261,12 +285,12 @@ interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR> extends Fam
    * table itself is missing).
    *
    * `space` is required at every call site so the type system surfaces
-   * every place that needs to thread the value: callers in single-app
+   * every place that needs to thread the value: callers in app-only
    * paths pass {@link import('./control-spaces').APP_SPACE_ID}
    * (`'app'`); per-extension callers pass the extension's space id.
    * Defaulting at the family-interface level was a silent bug door —
-   * it let multi-space-aware callers forget to pass `space` and
-   * collapse onto the app's marker row.
+   * it let callers forget to pass `space` and collapse onto the app's
+   * marker row.
    *
    * Families whose underlying storage doesn't yet support per-space
    * markers (Mongo, today) accept `space` for interface conformance and
@@ -392,20 +416,6 @@ interface ControlExtensionDescriptor<TFamilyId extends string, TTargetId extends
 }
 //#endregion
 //#region src/control/control-migration-types.d.ts
-/**
- * Planner provenance recorded inside {@link MigrationMetadata}.
- *
- * `used` / `applied` track which migration hints the planner consulted
- * vs. which it actually applied during emission; `plannerVersion`
- * pins the planner build that produced the migration so future
- * verification passes can recognise plans authored against an older
- * planner.
- */
-interface MigrationHints {
-  readonly used: readonly string[];
-  readonly applied: readonly string[];
-  readonly plannerVersion: string;
-}
 /**
  * In-memory migration metadata envelope. Every migration is
  * content-addressed: the `migrationHash` is a hash over the metadata
@@ -435,8 +445,6 @@ interface MigrationMetadata {
   readonly migrationHash: string;
   readonly from: string | null;
   readonly to: string;
-  readonly hints: MigrationHints;
-  readonly labels: readonly string[];
   /**
    * Sorted, deduplicated list of `invariantId`s declared by the
    * migration's data-transform ops. Always present; an empty array
@@ -562,11 +570,10 @@ interface MigrationPlan {
   /**
    * Contract space this plan applies to. Runners cross-check
    * `options.space` against `plan.spaceId` so the marker row gets keyed
-   * by the right space when applying via `executeAcrossSpaces`.
+   * by the right space when applying via {@link MigrationRunner.execute}.
    *
-   * Optional for backward compatibility with single-space callers that
-   * pre-date the contract-space aggregate; when present, runners
-   * enforce that it matches `options.space`.
+   * Optional because not every plan carries a space id; when present,
+   * runners enforce that it matches `options.space`.
    */
   readonly spaceId?: string;
   /**
@@ -648,12 +655,23 @@ interface MigrationPlannerFailureResult {
  */
 type MigrationPlannerResult = MigrationPlannerSuccessResult | MigrationPlannerFailureResult;
 /**
- * Success value for migration runner execution.
+ * Per-space success payload returned inside
+ * {@link MigrationRunnerSuccessValue.perSpaceResults}.
  */
-interface MigrationRunnerSuccessValue {
+interface MigrationRunnerPerSpaceSuccessValue {
   readonly operationsPlanned: number;
   readonly operationsExecuted: number;
 }
+/**
+ * Success value for migration runner execution across one or more contract
+ * spaces.
+ */
+interface MigrationRunnerSuccessValue {
+  readonly perSpaceResults: ReadonlyArray<{
+    readonly space: string;
+    readonly value: MigrationRunnerPerSpaceSuccessValue;
+  }>;
+}
 /**
  * Failure details for migration runner execution.
  */
@@ -666,6 +684,11 @@ interface MigrationRunnerFailure {
   readonly why?: string;
   /** Optional metadata for debugging and UX (e.g., schema issues, SQL state). */
   readonly meta?: Record<string, unknown>;
+  /**
+   * Identifier of the space whose plan caused the rollback when
+   * {@link MigrationRunner.execute} processes multiple spaces.
+   */
+  readonly failingSpace?: string;
 }
 /**
  * Result type for migration runner execution.
@@ -755,54 +778,20 @@ interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends
  * @template TFamilyId - The family ID (e.g., 'sql', 'document')
  * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  */
-interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
-  /**
-   * Execute a migration plan against the configured driver.
-   *
-   * The `plan` parameter is trusted input. Callers are responsible for
-   * upstream verification of the originating migration package — typically
-   * by obtaining the package via `readMigrationPackage` from
-   * `@prisma-next/migration-tools/io`, which performs hash-integrity checks
-   * at the load boundary. Runners do not re-verify the plan and assume the
-   * `(metadata, ops)` pair on disk has not been tampered with since emit.
-   */
-  execute(options: {
-    readonly plan: MigrationPlan;
-    readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
-    readonly destinationContract: unknown;
-    readonly policy: MigrationOperationPolicy;
-    readonly callbacks?: {
-      onOperationStart?(op: MigrationPlanOperation): void;
-      onOperationComplete?(op: MigrationPlanOperation): void;
-    };
-    /**
-     * Execution-time checks configuration.
-     * All checks default to `true` (enabled) when omitted.
-     */
-    readonly executionChecks?: MigrationRunnerExecutionChecks;
-    /**
-     * Active framework components participating in this composition.
-     * Families/targets can interpret this list to derive family-specific metadata.
-     * All components must have matching familyId and targetId.
-     */
-    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
-  }): Promise<MigrationRunnerResult>;
-}
 /**
- * Per-space input for {@link MultiSpaceCapableRunner.executeAcrossSpaces}.
+ * Per-space input for {@link MigrationRunner.execute}.
  *
- * Mirrors the single-space `MigrationRunner.execute` options, extended with a
- * required `space` identifier. Each entry's `driver` must reference the same
- * connection the outer transaction is opened on (typically the same value as
- * the top-level `driver` on `executeAcrossSpaces`).
+ * Each entry's `driver` must reference the same connection the outer
+ * transaction is opened on (typically the same value as the top-level
+ * `driver` on `execute`). An apply that targets one space passes a
+ * one-element `perSpaceOptions` list.
  *
  * Family-specific runners (e.g. the SQL family's `SqlMigrationRunner`) define
  * a richer per-space option shape that is structurally compatible with this
- * one — additional optional fields (e.g. SQL's `strictVerification`,
- * `schemaName`, `callbacks`) are tolerated by the underlying runner without
- * affecting cross-target wiring.
+ * one — additional optional fields (e.g. SQL's `schemaName`, `callbacks`) are
+ * tolerated by the underlying runner without affecting cross-target wiring.
  */
-interface MultiSpaceRunnerPerSpaceOptions<TFamilyId extends string = string, TTargetId extends string = string> {
+interface MigrationRunnerPerSpaceOptions<TFamilyId extends string = string, TTargetId extends string = string> {
   readonly space: string;
   readonly plan: MigrationPlan;
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
@@ -810,38 +799,36 @@ interface MultiSpaceRunnerPerSpaceOptions<TFamilyId extends string = string, TTa
   readonly policy: MigrationOperationPolicy;
   readonly executionChecks?: MigrationRunnerExecutionChecks;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  /**
+   * When `false`, schema verification tolerates objects owned by sibling
+   * contract spaces. Aggregate apply passes `false` per space because each
+   * `destinationContract` describes only that space's slice.
+   */
+  readonly strictVerification?: boolean;
+  /**
+   * Paths and metadata forwarded to schema verification diagnostics.
+   */
+  readonly context?: OperationContext;
 }
-interface MultiSpaceRunnerSuccessValue {
-  readonly perSpaceResults: ReadonlyArray<{
-    readonly space: string;
-    readonly value: MigrationRunnerSuccessValue;
-  }>;
-}
-interface MultiSpaceRunnerFailure extends MigrationRunnerFailure {
-  /** Identifier of the space whose plan caused the rollback. */
-  readonly failingSpace: string;
-}
-type MultiSpaceRunnerResult = Result<MultiSpaceRunnerSuccessValue, MultiSpaceRunnerFailure>;
-/**
- * Optional capability for runners that can apply a list of per-space plans.
- * Atomicity semantics differ by family:
- *
- * - SQL (`SqlMigrationRunner`) opens one outer transaction across every
- *   space; a failure on any space rolls back every space's writes.
- * - Mongo (`mongoTargetDescriptor`) cannot wrap most DDL ops in a session
- *   transaction (TML-2408), so it iterates per-space without an outer
- *   transaction and relies on per-space-internal verify-gated marker
- *   atomicity. Earlier-advanced markers are not rolled back when a later
- *   space fails; re-running resumes from the failing space.
- *
- * The capability is declared at the framework layer so CLI utilities can
- * route through it without importing any specific family directly.
- */
-interface MultiSpaceCapableRunner<TFamilyId extends string = string, TTargetId extends string = string> {
-  executeAcrossSpaces(options: {
+interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
+  /**
+   * Apply one or more per-space migration plans against the configured driver.
+   *
+   * Each plan is trusted input. Callers are responsible for upstream
+   * verification of the originating migration package — typically by
+   * obtaining the package via `readMigrationPackage` from
+   * `@prisma-next/migration-tools/io`, which performs hash-integrity checks
+   * at the load boundary. Runners do not re-verify plans and assume the
+   * `(metadata, ops)` pairs on disk have not been tampered with since emit.
+   *
+   * Atomicity semantics differ by family: SQL targets open one outer
+   * transaction across every space; Mongo iterates per-space without an
+   * outer transaction and relies on per-space verify-gated marker atomicity.
+   */
+  execute(options: {
     readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
-    readonly perSpaceOptions: ReadonlyArray<MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>>;
-  }): Promise<MultiSpaceRunnerResult>;
+    readonly perSpaceOptions: ReadonlyArray<MigrationRunnerPerSpaceOptions<TFamilyId, TTargetId>>;
+  }): Promise<MigrationRunnerResult>;
 }
 /**
  * Optional capability interface for targets that support migrations.
@@ -979,18 +966,6 @@ interface OperationPreviewCapable {
   toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
 }
 declare function hasOperationPreview<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & OperationPreviewCapable;
-/**
- * Capability declaring that a runner can apply per-space plans inside a
- * single outer transaction. The SQL family (`SqlMigrationRunner`) implements
- * this with a true outer transaction. The Mongo family implements a
- * degenerate single-space shim (Mongo per-space is a non-goal per the
- * extension-contract-spaces project spec — TML-2397).
- *
- * The CLI's shared `applyAggregate` primitive uses this guard so that
- * `db init` / `db update` / `migrate` route uniformly through one
- * dispatch path regardless of family.
- */
-declare function hasMultiSpaceRunner<TFamilyId extends string, TTargetId extends string>(runner: MigrationRunner<TFamilyId, TTargetId>): runner is MigrationRunner<TFamilyId, TTargetId> & MultiSpaceCapableRunner<TFamilyId, TTargetId>;
 //#endregion
 //#region src/control/control-spaces.d.ts
 /**
@@ -1118,5 +1093,5 @@ interface SchemaVerifyResult {
   readonly issues: readonly SchemaIssue[];
 }
 //#endregion
-export { APP_SPACE_ID, type AssembledAuthoringContributions, type BaseSchemaIssue, type ContractSerializer, type ContractSpace, type ContractSpaceHeadRef, type ControlAdapterDescriptor, type ControlAdapterInstance, type ControlDriverDescriptor, type ControlDriverInstance, type ControlExtensionDescriptor, type ControlExtensionInstance, type ControlFamilyDescriptor, type ControlFamilyInstance, type ControlMutationDefaultEntry, type ControlMutationDefaultRegistry, type ControlMutationDefaults, type ControlStack, type ControlTargetDescriptor, type ControlTargetInstance, type CoreSchemaView, type CreateControlStackInput, type DefaultFunctionLoweringContext, type DefaultFunctionLoweringHandler, type DefaultFunctionRegistry, type DefaultFunctionRegistryEntry, type EmitContractResult, type EnumValuesChangedIssue, type ImportRequirement, type IntrospectSchemaResult, type LoweredDefaultResult, type LoweredDefaultValue, type MigratableTargetDescriptor, type MigrationHints, type MigrationMetadata, type MigrationOperationClass, type MigrationOperationPolicy, type MigrationPackage, type MigrationPlan, type MigrationPlanOperation, type MigrationPlanWithAuthoringSurface, type MigrationPlanner, type MigrationPlannerConflict, type MigrationPlannerFailureResult, type MigrationPlannerResult, type MigrationPlannerSuccessResult, type MigrationRunner, type MigrationRunnerExecutionChecks, type MigrationRunnerFailure, type MigrationRunnerResult, type MigrationRunnerSuccessValue, type MigrationScaffoldContext, type MultiSpaceCapableRunner, type MultiSpaceRunnerFailure, type MultiSpaceRunnerPerSpaceOptions, type MultiSpaceRunnerResult, type MultiSpaceRunnerSuccessValue, type MutationDefaultGeneratorDescriptor, type OpFactoryCall, type OperationContext, type OperationPreview, type OperationPreviewCapable, type OperationPreviewStatement, type ParsedDefaultFunctionCall, type PslContractInferCapable, type SchemaIssue, SchemaTreeNode, type SchemaTreeNodeOptions, type SchemaTreeVisitor, type SchemaVerificationNode, type SchemaVerifier, type SchemaVerifyOptions, type SchemaVerifyResult, type SchemaViewCapable, type SchemaViewNodeKind, type SerializedQueryPlan, type SignDatabaseResult, type SourceDiagnostic, type SourceSpan, type TargetMigrationsCapability, VERIFY_CODE_HASH_MISMATCH, VERIFY_CODE_MARKER_MISSING, VERIFY_CODE_SCHEMA_FAILURE, VERIFY_CODE_TARGET_MISMATCH, type VerifyDatabaseResult, type VerifyDatabaseSchemaResult, assembleAuthoringContributions, assembleControlMutationDefaults, assembleScalarTypeDescriptors, assertUniqueCodecOwner, createControlStack, extractCodecLookup, extractCodecTypeImports, extractComponentIds, extractQueryOperationTypeImports, hasMigrations, hasMultiSpaceRunner, hasOperationPreview, hasPslContractInfer, hasSchemaView };
+export { APP_SPACE_ID, type AssembledAuthoringContributions, type BaseSchemaIssue, type ContractSerializer, type ContractSpace, type ContractSpaceHeadRef, type ControlAdapterDescriptor, type ControlAdapterInstance, type ControlDriverDescriptor, type ControlDriverInstance, type ControlExtensionDescriptor, type ControlExtensionInstance, type ControlFamilyDescriptor, type ControlFamilyInstance, type ControlMutationDefaultEntry, type ControlMutationDefaultRegistry, type ControlMutationDefaults, type ControlStack, type ControlTargetDescriptor, type ControlTargetInstance, type CoreSchemaView, type CreateControlStackInput, type DefaultFunctionLoweringContext, type DefaultFunctionLoweringHandler, type DefaultFunctionRegistry, type DefaultFunctionRegistryEntry, type EmitContractResult, type EnumValuesChangedIssue, type ImportRequirement, type IntrospectSchemaResult, type LoweredDefaultResult, type LoweredDefaultValue, type MigratableTargetDescriptor, type MigrationMetadata, type MigrationOperationClass, type MigrationOperationPolicy, type MigrationPackage, type MigrationPlan, type MigrationPlanOperation, type MigrationPlanWithAuthoringSurface, type MigrationPlanner, type MigrationPlannerConflict, type MigrationPlannerFailureResult, type MigrationPlannerResult, type MigrationPlannerSuccessResult, type MigrationRunner, type MigrationRunnerExecutionChecks, type MigrationRunnerFailure, type MigrationRunnerPerSpaceOptions, type MigrationRunnerPerSpaceSuccessValue, type MigrationRunnerResult, type MigrationRunnerSuccessValue, type MigrationScaffoldContext, type MutationDefaultGeneratorDescriptor, type OpFactoryCall, type OperationContext, type OperationPreview, type OperationPreviewCapable, type OperationPreviewStatement, type ParsedDefaultFunctionCall, type PslContractInferCapable, type SchemaIssue, SchemaTreeNode, type SchemaTreeNodeOptions, type SchemaTreeVisitor, type SchemaVerificationNode, type SchemaVerifier, type SchemaVerifyOptions, type SchemaVerifyResult, type SchemaViewCapable, type SchemaViewNodeKind, type SerializedQueryPlan, type SignDatabaseResult, type SourceDiagnostic, type SourceSpan, type TargetMigrationsCapability, VERIFY_CODE_HASH_MISMATCH, VERIFY_CODE_MARKER_MISSING, VERIFY_CODE_SCHEMA_FAILURE, VERIFY_CODE_TARGET_MISMATCH, type VerifyDatabaseResult, type VerifyDatabaseSchemaResult, assembleAuthoringContributions, assembleControlMutationDefaults, assembleScalarTypeDescriptors, assertUniqueCodecOwner, createControlStack, extractCodecLookup, extractCodecTypeImports, extractComponentIds, extractQueryOperationTypeImports, hasMigrations, hasOperationPreview, hasPslContractInfer, hasSchemaView };
 //# sourceMappingURL=control.d.mts.map