@prisma-next/framework-components 0.13.0-dev.2 → 0.13.0-dev.21

package/src/execution/runtime-error.ts

@@ -1,9 +1,8 @@
-export interface RuntimeErrorEnvelope extends Error {
-  readonly code: string;
-  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
-  readonly severity: 'error';
-  readonly details?: Record<string, unknown>;
-}
+import type { RuntimeErrorEnvelope } from '../shared/runtime-error';
+import { runtimeError } from '../shared/runtime-error';
+
+export type { RuntimeErrorEnvelope } from '../shared/runtime-error';
+export { isRuntimeError, runtimeError } from '../shared/runtime-error';
 
 /**
  * Stable code emitted by the runtime when an in-flight `execute()`
@@ -30,55 +29,6 @@ export type RuntimeAbortedPhase =
   | 'afterExecute'
   | 'onRow';
 
-/**
- * Type guard for the runtime-error envelope produced by `runtimeError`.
- *
- * Prefer this over duck-typing on `error.code` directly so consumers stay
- * insulated from the envelope's internal shape.
- */
-export function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {
-  return (
-    error instanceof Error &&
-    'code' in error &&
-    typeof (error as { code?: unknown }).code === 'string' &&
-    'category' in error &&
-    'severity' in error
-  );
-}
-
-export function runtimeError(
-  code: string,
-  message: string,
-  details?: Record<string, unknown>,
-): RuntimeErrorEnvelope {
-  const error = new Error(message) as RuntimeErrorEnvelope;
-  Object.defineProperty(error, 'name', {
-    value: 'RuntimeError',
-    configurable: true,
-  });
-
-  return Object.assign(error, {
-    code,
-    category: resolveCategory(code),
-    severity: 'error' as const,
-    message,
-    details,
-  });
-}
-
-function resolveCategory(code: string): RuntimeErrorEnvelope['category'] {
-  const prefix = code.split('.')[0] ?? 'RUNTIME';
-  switch (prefix) {
-    case 'PLAN':
-    case 'CONTRACT':
-    case 'LINT':
-    case 'BUDGET':
-      return prefix;
-    default:
-      return 'RUNTIME';
-  }
-}
-
 /**
  * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
  * abort was observed — codec call sites (`encode` / `decode` / `stream`)

package/src/exports/authoring.ts

@@ -3,6 +3,7 @@ export type {
   AuthoringArgumentDescriptor,
   AuthoringColumnDefaultTemplate,
   AuthoringContributions,
+  AuthoringDiagnosticSink,
   AuthoringEntityContext,
   AuthoringEntityTypeDescriptor,
   AuthoringEntityTypeFactoryOutput,

package/src/exports/codec.ts

@@ -16,6 +16,7 @@ export type {
   CodecLookup,
   CodecMeta,
   CodecRef,
+  CodecRegistry,
   CodecTrait,
 } from '../shared/codec-types';
 export { emptyCodecLookup, voidParamsSchema } from '../shared/codec-types';
@@ -26,3 +27,4 @@ export type {
   ColumnTypeDescriptor,
 } from '../shared/column-spec';
 export { column } from '../shared/column-spec';
+export { materializeCodec, validateCodecTypeParams } from '../shared/resolve-codec';

package/src/exports/control.ts

@@ -47,7 +47,6 @@ export type {
   MigrationRunnerSuccessValue,
   MigrationScaffoldContext,
   OpFactoryCall,
-  SerializedQueryPlan,
   TargetMigrationsCapability,
 } from '../control/control-migration-types';
 export type {

package/src/shared/codec-types.ts

@@ -36,7 +36,7 @@ export interface CodecCallContext {
 /**
  * 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 `family.deserializeContract` for `decodeJson` of literal column defaults).
+ * - `get(id)` returns a representative {@link Codec} instance for the codec id (used by `family.deserializeContract` for `decodeJson` of literal column defaults). For parameterized codecs whose factory requires concrete params, this may return `undefined` — use `CodecRegistry.forCodecRef` instead.
  * - `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.
@@ -48,6 +48,24 @@ export interface CodecLookup {
   renderOutputTypeFor(id: string, params: Record<string, unknown>): string | undefined;
 }
 
+/**
+ * Full codec registry — the read surface of {@link CodecLookup} plus codec resolution by ref or
+ * column coordinate. Built once by `extractCodecLookup` and passed by reference to adapters and
+ * other consumers that need to materialise codecs at runtime.
+ *
+ * - `forCodecRef(ref)` materialises a codec from a {@link CodecRef}. Throws
+ *   `RUNTIME.CODEC_DESCRIPTOR_MISSING` for unknown ids and `RUNTIME.TYPE_PARAMS_INVALID` on param
+ *   schema rejection.
+ * - `forColumn(namespaceId, table, column)` returns the codec for a specific column coordinate, or
+ *   `undefined` when no column-to-codec mapping is present. This registry is contract-free so it
+ *   always returns `undefined` — the method exists so the object structurally satisfies the SQL
+ *   `ContractCodecRegistry` interface.
+ */
+export interface CodecRegistry extends CodecLookup {
+  forCodecRef(ref: CodecRef): Codec;
+  forColumn(namespaceId: string, table: string, column: string): Codec | undefined;
+}
+
 export const emptyCodecLookup: CodecLookup = {
   get: () => undefined,
   targetTypesFor: () => undefined,

package/src/shared/framework-authoring.ts

@@ -10,6 +10,7 @@ import {
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Type } from 'arktype';
+import type { CodecLookup } from './codec-types';
 import type { PslBlockParam } from './psl-extension-block';
 
 export type AuthoringArgRef = {
@@ -109,9 +110,30 @@ export type AuthoringFieldNamespace = {
  * discover what the factory actually needs to read (codec lookup,
  * namespace registry, …).
  */
+/**
+ * A write-only sink that a factory may push authoring-time diagnostics into.
+ * The concrete type pushed must be structurally compatible with whatever the
+ * consumer accumulates (typically `ContractSourceDiagnostic[]`); the framework
+ * layer deliberately does not depend on that concrete type.
+ */
+export interface AuthoringDiagnosticSink {
+  push(d: {
+    readonly code: string;
+    readonly message: string;
+    readonly sourceId: string;
+    readonly span?: unknown;
+  }): void;
+}
+
 export interface AuthoringEntityContext {
   readonly family: string;
   readonly target: string;
+  /** Codec registry available to factories that need to validate or decode values. */
+  readonly codecLookup?: CodecLookup;
+  /** Source file identifier threaded into diagnostics emitted by the factory. */
+  readonly sourceId?: string;
+  /** Push channel for authoring-time diagnostics emitted by the factory. */
+  readonly diagnostics?: AuthoringDiagnosticSink;
 }
 
 export interface AuthoringEntityTypeTemplateOutput {
@@ -186,6 +208,21 @@ export interface AuthoringPslBlockDescriptor {
   readonly discriminator: string;
   readonly name: { readonly required: boolean };
   readonly parameters: Record<string, PslBlockParam>;
+  /**
+   * When `true`, the block body accepts a variadic tail of parameters beyond
+   * the declared set. The block body may contain: fields (model-style),
+   * `key = value` parameters, and `@@` attributes. With `variadicParameters`,
+   * bare identifiers (keys without a `= value`) and undeclared `key = value`
+   * pairs flow into the variadic tail — their semantics belong to the
+   * lowering, not the parser.
+   *
+   * A key that IS declared in `parameters` must still be supplied as
+   * `key = value`; a bare occurrence of a declared key is a diagnostic.
+   *
+   * When `false` (default), the validator emits `PSL_EXTENSION_UNKNOWN_PARAMETER`
+   * for keys absent from `parameters`.
+   */
+  readonly variadicParameters?: boolean;
 }
 
 export type AuthoringPslBlockDescriptorNamespace = {
@@ -329,13 +366,29 @@ export function hasRegisteredFieldNamespace(
   return !isAuthoringFieldPresetDescriptor(contributions.field[namespace]);
 }
 
-function isPlainNamespaceObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+function isCopyableNamespaceObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function deepCopyNamespace(
+  source: Record<string, unknown>,
+  isLeafDescriptor: (value: unknown) => boolean,
+): Record<string, unknown> {
+  const copy: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    copy[key] =
+      isCopyableNamespaceObject(value) && !isLeafDescriptor(value)
+        ? deepCopyNamespace(value, isLeafDescriptor)
+        : value;
+  }
+  return copy;
 }
 
 /**
  * Merges `source` into `target` recursively at the descriptor-namespace
- * level. `leafGuard` decides which values are descriptors (terminal
+ * level. `isLeafDescriptor` decides which values are descriptors (terminal
  * merge points; same-path registrations across components are reported
  * as duplicates) versus sub-namespaces (recursion targets).
  *
@@ -355,7 +408,7 @@ export function mergeAuthoringNamespaces(
   target: Record<string, unknown>,
   source: Record<string, unknown>,
   path: readonly string[],
-  leafGuard: (value: unknown) => boolean,
+  isLeafDescriptor: (value: unknown) => boolean,
   label: string,
 ): void {
   const assertSafePath = (currentPath: readonly string[]) => {
@@ -376,12 +429,19 @@ export function mergeAuthoringNamespaces(
     const existingValue = hasExistingValue ? target[key] : undefined;
 
     if (!hasExistingValue) {
-      target[key] = sourceValue;
+      // Deep-copy plain-object sub-namespaces so subsequent merges don't mutate
+      // objects owned by source packs. Leaf descriptors and class instances are
+      // passed by reference — leaves are identity values; class instances carry
+      // prototype getters that spread would destroy.
+      target[key] =
+        isCopyableNamespaceObject(sourceValue) && !isLeafDescriptor(sourceValue)
+          ? deepCopyNamespace(sourceValue, isLeafDescriptor)
+          : sourceValue;
       continue;
     }
 
-    const existingIsLeaf = leafGuard(existingValue);
-    const sourceIsLeaf = leafGuard(sourceValue);
+    const existingIsLeaf = isLeafDescriptor(existingValue);
+    const sourceIsLeaf = isLeafDescriptor(sourceValue);
 
     if (existingIsLeaf || sourceIsLeaf) {
       throw new Error(
@@ -389,17 +449,17 @@ export function mergeAuthoringNamespaces(
       );
     }
 
-    if (!isPlainNamespaceObject(existingValue) || !isPlainNamespaceObject(sourceValue)) {
+    if (!isCopyableNamespaceObject(existingValue) || !isCopyableNamespaceObject(sourceValue)) {
       throw new Error(
         `Invalid authoring ${label} helper "${currentPath.join('.')}". Expected a sub-namespace object or a recognized descriptor; received a malformed value.`,
       );
     }
 
-    mergeAuthoringNamespaces(existingValue, sourceValue, currentPath, leafGuard, label);
+    mergeAuthoringNamespaces(existingValue, sourceValue, currentPath, isLeafDescriptor, label);
   }
 }
 
-function collectAuthoringLeafPaths(
+function collectDescriptorPaths(
   namespace: Readonly<Record<string, unknown>>,
   isLeaf: (value: unknown) => boolean,
   path: readonly string[] = [],
@@ -413,29 +473,25 @@ function collectAuthoringLeafPaths(
     }
     if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
       paths.push(
-        ...collectAuthoringLeafPaths(
-          value as Readonly<Record<string, unknown>>,
-          isLeaf,
-          currentPath,
-        ),
+        ...collectDescriptorPaths(value as Readonly<Record<string, unknown>>, isLeaf, currentPath),
       );
     }
   }
   return paths;
 }
 
-interface AuthoringLeafEntry {
+interface DescriptorEntry {
   readonly path: string;
   readonly discriminator: string;
 }
 
-function collectAuthoringLeafDiscriminators(
+function collectDescriptorEntries(
   namespace: Readonly<Record<string, unknown>>,
   isLeaf: (value: unknown) => boolean,
   label: string,
   path: readonly string[] = [],
-): AuthoringLeafEntry[] {
-  const entries: AuthoringLeafEntry[] = [];
+): DescriptorEntry[] {
+  const entries: DescriptorEntry[] = [];
   for (const [key, value] of Object.entries(namespace)) {
     const currentPath = [...path, key];
     if (isLeaf(value)) {
@@ -479,7 +535,7 @@ function collectAuthoringLeafDiscriminators(
           );
         }
       }
-      entries.push(...collectAuthoringLeafDiscriminators(record, isLeaf, label, currentPath));
+      entries.push(...collectDescriptorEntries(record, isLeaf, label, currentPath));
     }
   }
   return entries;
@@ -491,7 +547,7 @@ function collectAuthoringLeafDiscriminators(
  * lowering factory lookup dispatches by discriminator, so one would silently
  * shadow the other. Catch duplicates before building any dispatch map.
  */
-function assertUniqueDiscriminators(entries: readonly AuthoringLeafEntry[], label: string): void {
+function assertUniqueDiscriminators(entries: readonly DescriptorEntry[], label: string): void {
   const seen = new Map<string, string>();
   for (const { path, discriminator } of entries) {
     const existing = seen.get(discriminator);
@@ -504,23 +560,50 @@ function assertUniqueDiscriminators(entries: readonly AuthoringLeafEntry[], labe
   }
 }
 
+function collectPslBlockDescriptorEntries(
+  namespace: Readonly<Record<string, unknown>>,
+  path: readonly string[] = [],
+): DescriptorEntry[] {
+  const entries: DescriptorEntry[] = [];
+  for (const [key, value] of Object.entries(namespace)) {
+    const currentPath = [...path, key];
+    if (isAuthoringPslBlockDescriptor(value)) {
+      entries.push({
+        path: currentPath.join('.'),
+        discriminator: value.discriminator,
+      });
+      continue;
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const record = blindCast<
+        Readonly<Record<string, unknown>>,
+        'walker descends into psl block namespace'
+      >(value);
+      const hasKind = record['kind'] === 'pslBlock';
+      const hasKeyword = typeof record['keyword'] === 'string';
+      const hasDiscriminator = typeof record['discriminator'] === 'string';
+      if (hasKind || (hasKeyword && hasDiscriminator)) {
+        throw new Error(
+          `Malformed authoring pslBlock contribution at "${currentPath.join('.')}". The value carries descriptor keys (kind/keyword/discriminator) but does not satisfy the pslBlock descriptor shape. Fix the contribution so it is a complete descriptor, or remove the stray keys if it was meant to be a sub-namespace.`,
+        );
+      }
+      entries.push(...collectPslBlockDescriptorEntries(record, currentPath));
+    }
+  }
+  return entries;
+}
+
 /**
- * Every `pslBlockDescriptors` entry needs a matching `entityTypes` factory
- * (same discriminator): the parser would otherwise produce an AST node
- * nothing can lower to an IR class instance. The link is one-directional
- * — an `entityTypes` factory may stand alone (e.g. `enum`, reachable from
- * the TypeScript builder without any PSL block).
+ * Every `pslBlockDescriptors` entry requires a matching `entityTypes` factory
+ * with the same discriminator. An `entityTypes` factory may stand alone (e.g.
+ * `enum`, reachable from the TypeScript builder without any PSL block).
  */
 function assertPslBlocksHaveFactories(
   entityTypeNamespace: AuthoringEntityTypeNamespace,
   pslBlockNamespace: AuthoringPslBlockDescriptorNamespace,
 ): void {
-  const blockEntries = collectAuthoringLeafDiscriminators(
-    pslBlockNamespace,
-    isAuthoringPslBlockDescriptor,
-    'pslBlock',
-  );
-  const entityEntries = collectAuthoringLeafDiscriminators(
+  const blockEntries = collectPslBlockDescriptorEntries(pslBlockNamespace);
+  const entityEntries = collectDescriptorEntries(
     entityTypeNamespace,
     isAuthoringEntityTypeDescriptor,
     'entityType',
@@ -547,13 +630,13 @@ export function assertNoCrossRegistryCollisions(
   pslBlockNamespace: AuthoringPslBlockDescriptorNamespace = {},
 ): void {
   const typePaths = new Set(
-    collectAuthoringLeafPaths(typeNamespace, isAuthoringTypeConstructorDescriptor),
+    collectDescriptorPaths(typeNamespace, isAuthoringTypeConstructorDescriptor),
   );
   const fieldPaths = new Set(
-    collectAuthoringLeafPaths(fieldNamespace, isAuthoringFieldPresetDescriptor),
+    collectDescriptorPaths(fieldNamespace, isAuthoringFieldPresetDescriptor),
   );
   const entityPaths = new Set(
-    collectAuthoringLeafPaths(entityTypeNamespace, isAuthoringEntityTypeDescriptor),
+    collectDescriptorPaths(entityTypeNamespace, isAuthoringEntityTypeDescriptor),
   );
   // Within-registry duplicate detection is handled upstream by the merge
   // walker (`mergeAuthoringNamespaces` in control-stack.ts and

package/src/shared/psl-extension-block.ts

@@ -70,7 +70,16 @@ export type PslDiagnosticCode =
    * A `ref`-kind parameter identifier does not resolve to a declared entity of
    * the required `refKind` within the declared scope.
    */
-  | 'PSL_EXTENSION_UNRESOLVED_REF';
+  | 'PSL_EXTENSION_UNRESOLVED_REF'
+  /**
+   * A parameter key appears more than once in an extension block body.
+   * The first occurrence is kept; subsequent occurrences emit this diagnostic.
+   */
+  | 'PSL_EXTENSION_DUPLICATE_PARAMETER'
+  /**
+   * A `@@`-prefixed block-attribute line inside an extension block has invalid syntax.
+   */
+  | 'PSL_INVALID_EXTENSION_BLOCK_ATTRIBUTE';
 
 /**
  * Descriptor vocabulary for a single parameter on a declared block.
@@ -118,14 +127,17 @@ export interface PslBlockParamList {
 /**
  * The parsed representation of a single parameter value on a uniform
  * extension-block AST node. Mirrors the `PslBlockParam` descriptor
- * vocabulary:
+ * vocabulary, plus `bare` for keyonly entries:
  *
  * - `ref`    → `PslExtensionBlockParamRef` — a raw identifier string
  *   (resolution runs in the validator, not the parser).
- * - `value`  → `PslExtensionBlockParamValue` — a raw PSL literal string
+ * - `value`  → `PslExtensionBlockParamScalarValue` — a raw PSL literal string
  *   (codec validation runs in the validator).
  * - `option` → `PslExtensionBlockParamOption` — the chosen token.
  * - `list`   → `PslExtensionBlockParamList` — ordered list of the above.
+ * - `bare`   → `PslExtensionBlockParamBare` — a bare identifier line with no
+ *   `= value` (e.g. `Low` in an enum2 block). The name is the key in
+ *   `parameters`; the interpreting consumer decides the default value.
  *
  * These shapes are intentionally minimal. The validator and lowering refine
  * and consume them; the generic framework parser produces them.
@@ -134,7 +146,8 @@ export type PslExtensionBlockParamValue =
   | PslExtensionBlockParamRef
   | PslExtensionBlockParamScalarValue
   | PslExtensionBlockParamOption
-  | PslExtensionBlockParamList;
+  | PslExtensionBlockParamList
+  | PslExtensionBlockParamBare;
 
 export interface PslExtensionBlockParamRef {
   readonly kind: 'ref';
@@ -160,6 +173,38 @@ export interface PslExtensionBlockParamList {
   readonly span: PslSpan;
 }
 
+/**
+ * A bare identifier line inside an extension block — a key with no `= value`.
+ * Emitted when a line matches `/^[A-Za-z_]\w*$/` with no assignment. The
+ * consumer decides what default value (if any) to apply.
+ */
+export interface PslExtensionBlockParamBare {
+  readonly kind: 'bare';
+  readonly span: PslSpan;
+}
+
+/**
+ * A positional argument on a block attribute, e.g. the `"pg/text@1"` in
+ * `@@type("pg/text@1")`.
+ */
+export interface PslExtensionBlockAttributeArg {
+  readonly kind: 'positional';
+  readonly value: string;
+  readonly span: PslSpan;
+}
+
+/**
+ * A `@@`-prefixed block-level attribute parsed inside an extension block,
+ * e.g. `@@type("pg/text@1")`. Block attributes are captured generically
+ * — the parser does not validate attribute names or argument shapes; that
+ * is a concern of the block's interpreter.
+ */
+export interface PslExtensionBlockAttribute {
+  readonly name: string;
+  readonly args: readonly PslExtensionBlockAttributeArg[];
+  readonly span: PslSpan;
+}
+
 /**
  * Base shape for a uniform extension-contributed top-level PSL block
  * node, as produced by the generic framework parser and consumed by the
@@ -173,12 +218,18 @@ export interface PslExtensionBlockParamList {
  *   parameter names from the descriptor; values are the parsed parameter
  *   representations. Only parameters present in the source are included
  *   — absence of a required parameter is a validator concern, not a
- *   parser concern.
+ *   parser concern. Insertion order is preserved; the first occurrence of a
+ *   duplicate key is retained and subsequent occurrences emit
+ *   `PSL_EXTENSION_DUPLICATE_PARAMETER`.
+ * - `blockAttributes` are `@@`-prefixed attribute lines inside the block, in
+ *   declaration order. Captured generically — names and args are not validated
+ *   by the parser.
  * - `span` covers the full block from keyword to closing brace.
  */
 export interface PslExtensionBlock {
   readonly kind: string;
   readonly name: string;
   readonly parameters: Record<string, PslExtensionBlockParamValue>;
+  readonly blockAttributes: readonly PslExtensionBlockAttribute[];
   readonly span: PslSpan;
 }

package/src/shared/resolve-codec.ts

@@ -0,0 +1,64 @@
+import { blindCast } from '@prisma-next/utils/casts';
+import type { Codec } from './codec';
+import type { AnyCodecDescriptor } from './codec-descriptor';
+import type { CodecInstanceContext, CodecRef } from './codec-types';
+import { runtimeError } from './runtime-error';
+
+/**
+ * Validates `ref.typeParams` against `descriptor.paramsSchema`.
+ *
+ * Parameterized codecs that omit `typeParams` have it normalized to `{}` before
+ * validation (mirrors `ast-codec-resolver.ts` semantics). Throws
+ * `RUNTIME.TYPE_PARAMS_INVALID` when the validator returns a `Promise` or
+ * reports issues.
+ */
+export function validateCodecTypeParams(descriptor: AnyCodecDescriptor, ref: CodecRef): unknown {
+  const normalized =
+    descriptor.isParameterized && ref.typeParams === undefined ? { ...ref, typeParams: {} } : ref;
+
+  const result = blindCast<
+    { value: unknown } | { issues: ReadonlyArray<{ message: string }> } | Promise<unknown>,
+    'Standard Schema validate returns unknown; the spec guarantees this union shape'
+  >(descriptor.paramsSchema['~standard'].validate(normalized.typeParams));
+
+  if (result instanceof Promise) {
+    throw runtimeError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
+      `paramsSchema for codec '${ref.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`,
+      { codecId: ref.codecId, typeParams: ref.typeParams },
+    );
+  }
+
+  if ('issues' in result && result.issues) {
+    const messages = result.issues.map((issue) => issue.message).join('; ');
+    throw runtimeError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
+      `Invalid typeParams for codec '${ref.codecId}': ${messages}`,
+      { codecId: ref.codecId, typeParams: ref.typeParams },
+    );
+  }
+
+  return blindCast<{ value: unknown }, 'issues guard above rules out the issues branch'>(result)
+    .value;
+}
+
+/**
+ * Resolves a `Codec` instance: validates `ref.typeParams` via
+ * {@link validateCodecTypeParams} then calls `descriptor.factory(validated)(ctx)`.
+ *
+ * The descriptor's `factory` is typed against its own `P`; the registry erases
+ * `P` to `any`, so the factory is narrowed to `(params: unknown) => (ctx) => Codec`
+ * at the call boundary. The `paramsSchema` validates the input above before we
+ * forward it, so the narrowing is safe by construction.
+ */
+export function materializeCodec(
+  descriptor: AnyCodecDescriptor,
+  ref: CodecRef,
+  ctx: CodecInstanceContext,
+): Codec {
+  const validated = validateCodecTypeParams(descriptor, ref);
+  return blindCast<
+    (params: unknown) => (ctx: CodecInstanceContext) => Codec,
+    'registry erases P to any; paramsSchema validates input before forwarding'
+  >(descriptor.factory)(validated)(ctx);
+}

package/src/shared/runtime-error.ts

@@ -0,0 +1,50 @@
+export interface RuntimeErrorEnvelope extends Error {
+  readonly code: string;
+  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+
+/**
+ * Type guard for the runtime-error envelope produced by `runtimeError`.
+ *
+ * Prefer this over duck-typing on `error.code` directly so consumers stay
+ * insulated from the envelope's internal shape.
+ */
+export function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof (error as { code?: unknown }).code === 'string' &&
+    'category' in error &&
+    'severity' in error
+  );
+}
+
+export function runtimeError(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>,
+): RuntimeErrorEnvelope {
+  const error = Object.assign(new Error(message), {
+    code,
+    category: resolveCategory(code),
+    severity: 'error' as const,
+    ...(details !== undefined ? { details } : {}),
+  });
+  Object.defineProperty(error, 'name', { value: 'RuntimeError', configurable: true });
+  return error;
+}
+
+function resolveCategory(code: string): RuntimeErrorEnvelope['category'] {
+  const prefix = code.split('.')[0] ?? 'RUNTIME';
+  switch (prefix) {
+    case 'PLAN':
+    case 'CONTRACT':
+    case 'LINT':
+    case 'BUDGET':
+      return prefix;
+    default:
+      return 'RUNTIME';
+  }
+}

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

@@ -1 +0,0 @@
-{"version":3,"file":"codec-DCQAerzB.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;;EAKJ,gBAAA,EAAkB,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,IAAM,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"}