@prisma-next/framework-components 0.13.0 → 0.14.0-dev.10

package/src/control/psl-ast.ts

@@ -7,6 +7,9 @@ export type {
   PslBlockParamValue,
   PslDiagnosticCode,
   PslExtensionBlock,
+  PslExtensionBlockAttribute,
+  PslExtensionBlockAttributeArg,
+  PslExtensionBlockParamBare,
   PslExtensionBlockParamList,
   PslExtensionBlockParamOption,
   PslExtensionBlockParamRef,
@@ -130,30 +133,6 @@ export interface PslModel {
   readonly comment?: string;
 }
 
-export interface PslEnumValue {
-  readonly kind: 'enumValue';
-  readonly name: string;
-  /**
-   * Optional storage label for the enum member, captured from a trailing
-   * `@map("...")` attribute on the member line. The parser populates this
-   * when the source PSL carries an explicit `@map`. Producers (e.g.
-   * `sqlSchemaIrToPslAst`) leave it unset; the printer emits `@map(...)`
-   * automatically when normalisation would change the printed member name
-   * (so an enum value `'in-progress'` becomes `inProgress @map("in-progress")`
-   * in PSL, preserving the round-trip).
-   */
-  readonly mapName?: string;
-  readonly span: PslSpan;
-}
-
-export interface PslEnum {
-  readonly kind: 'enum';
-  readonly name: string;
-  readonly values: readonly PslEnumValue[];
-  readonly attributes: readonly PslAttribute[];
-  readonly span: PslSpan;
-}
-
 /**
  * A reusable group of fields embedded in a model (a `type Name { … }` block) —
  * e.g. a MongoDB embedded document or a Postgres composite type. Unlike
@@ -202,7 +181,7 @@ export interface PslTypesBlock {
 export const UNSPECIFIED_PSL_NAMESPACE_ID = '__unspecified__';
 
 /** A value in {@link PslNamespace.entries}: a built-in entity node or an extension-contributed {@link PslExtensionBlock}. */
-export type PslNamespaceEntry = PslModel | PslEnum | PslCompositeType | PslExtensionBlock;
+export type PslNamespaceEntry = PslModel | PslCompositeType | PslExtensionBlock;
 
 /**
  * A namespace block, or the parser's synthesised `__unspecified__` bucket for
@@ -220,8 +199,6 @@ export interface PslNamespace {
   readonly entries: Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>>;
   /** Built-in models, from `entries['model']`. Extension kinds: {@link namespacePslExtensionBlocks}. */
   readonly models: readonly PslModel[];
-  /** Built-in enums, from `entries['enum']`. */
-  readonly enums: readonly PslEnum[];
   /** Built-in composite types, from `entries['compositeType']`. */
   readonly compositeTypes: readonly PslCompositeType[];
   readonly span: PslSpan;
@@ -255,12 +232,6 @@ class PslNamespaceNode implements PslNamespace {
     );
   }
 
-  get enums(): readonly PslEnum[] {
-    return blindCast<readonly PslEnum[], 'entries[enum] holds only PslEnum by construction'>(
-      Object.values(this.entries['enum'] ?? {}),
-    );
-  }
-
   get compositeTypes(): readonly PslCompositeType[] {
     return blindCast<
       readonly PslCompositeType[],
@@ -286,7 +257,6 @@ export function makePslNamespace(init: {
  */
 export function makePslNamespaceEntries(
   models: readonly PslModel[],
-  enums: readonly PslEnum[],
   compositeTypes: readonly PslCompositeType[],
   extensionBlocks: readonly PslExtensionBlock[],
 ): Readonly<Record<string, Readonly<Record<string, PslNamespaceEntry>>>> {
@@ -300,14 +270,6 @@ export function makePslNamespaceEntries(
     container['model'] = Object.freeze(map);
   }
 
-  if (enums.length > 0) {
-    const map: Record<string, PslEnum> = {};
-    for (const e of enums) {
-      map[e.name] = e;
-    }
-    container['enum'] = Object.freeze(map);
-  }
-
   if (compositeTypes.length > 0) {
     const map: Record<string, PslCompositeType> = {};
     for (const ct of compositeTypes) {
@@ -350,17 +312,6 @@ export function flatPslModels(ast: PslDocumentAst): readonly PslModel[] {
   );
 }
 
-/**
- * Returns all enums from every namespace in document order.
- */
-export function flatPslEnums(ast: PslDocumentAst): readonly PslEnum[] {
-  return ast.namespaces.flatMap((ns) =>
-    blindCast<PslEnum[], 'enum kind map contains only PslEnum by construction'>(
-      Object.values(ns.entries['enum'] ?? {}),
-    ),
-  );
-}
-
 /**
  * Returns all composite types from every namespace in document order.
  */
@@ -379,20 +330,18 @@ export function flatPslCompositeTypes(ast: PslDocumentAst): readonly PslComposit
  * that is **not** in this set was contributed by an extension-block descriptor.
  *
  * Built-in keys match the PSL keyword used on each block type:
- * `'model'`, `'enum'`, `'compositeType'`.
+ * `'model'`, `'compositeType'`. The `'enum'` keyword is claimed by the
+ * extension-block grammar via a registered descriptor, so `entries['enum']`
+ * holds `PslExtensionBlock` nodes and is returned by `namespacePslExtensionBlocks`.
  */
-export const BUILTIN_PSL_KIND_KEYS: ReadonlySet<string> = new Set([
-  'model',
-  'enum',
-  'compositeType',
-]);
+export const BUILTIN_PSL_KIND_KEYS: ReadonlySet<string> = new Set(['model', 'compositeType']);
 
 /**
  * Returns all extension-contributed blocks in the given namespace, in
  * insertion order (the order the parser encountered them in the source).
  *
- * Reads from `namespace.entries`, skipping the three built-in kind keys
- * (`'model'`, `'enum'`, `'compositeType'`). All remaining kind maps contain
+ * Reads from `namespace.entries`, skipping the built-in kind keys
+ * (`'model'`, `'compositeType'`). All remaining kind maps contain
  * only `PslExtensionBlock` nodes by construction (see `makePslNamespaceEntries`).
  */
 export function namespacePslExtensionBlocks(ns: PslNamespace): readonly PslExtensionBlock[] {

package/src/control/psl-extension-block-validator.ts

@@ -107,15 +107,17 @@ export function validateExtensionBlock(
   const nodeKeys = new Set(Object.keys(node.parameters));
 
   // 1. Unknown parameters — keys in the node not in the descriptor.
-  for (const key of nodeKeys) {
-    if (!descriptorKeys.has(key)) {
-      const captured = node.parameters[key];
-      diagnostics.push({
-        code: 'PSL_EXTENSION_UNKNOWN_PARAMETER',
-        message: `Unknown parameter "${key}" in "${descriptor.keyword}" block "${node.name}". The descriptor does not declare this parameter.`,
-        sourceId,
-        span: captured?.span ?? node.span,
-      });
+  if (!descriptor.variadicParameters) {
+    for (const key of nodeKeys) {
+      if (!descriptorKeys.has(key)) {
+        const captured = node.parameters[key];
+        diagnostics.push({
+          code: 'PSL_EXTENSION_UNKNOWN_PARAMETER',
+          message: `Unknown parameter "${key}" in "${descriptor.keyword}" block "${node.name}". The descriptor does not declare this parameter.`,
+          sourceId,
+          span: captured?.span ?? node.span,
+        });
+      }
     }
   }
 

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,9 @@ export type {
   ColumnTypeDescriptor,
 } from '../shared/column-spec';
 export { column } from '../shared/column-spec';
+export {
+  CONTRACT_CODEC_DESCRIPTOR_MISSING,
+  materializeCodec,
+  resolveCodecDescriptorOrThrow,
+  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/exports/ir.ts

@@ -1,8 +1,10 @@
 export { domainElementCoordinates } from '../ir/domain';
+export type { AnyEntityKindDescriptor, EntityKindDescriptor } from '../ir/entity-kind';
+export { hydrateNamespaceEntities } from '../ir/entity-kind';
 export type { IRNode } from '../ir/ir-node';
 export { freezeNode, IRNodeBase } from '../ir/ir-node';
 export type { Namespace } from '../ir/namespace';
 export { NamespaceBase, UNBOUND_NAMESPACE_ID } from '../ir/namespace';
 export type { EntityCoordinate, Storage } from '../ir/storage';
-export { elementCoordinates } from '../ir/storage';
+export { elementCoordinates, entityAt, isPlainRecord } from '../ir/storage';
 export type { StorageType } from '../ir/storage-type';

package/src/ir/entity-kind.ts

@@ -0,0 +1,54 @@
+import { blindCast } from '@prisma-next/utils/casts';
+import type { Type } from 'arktype';
+
+export interface EntityKindDescriptor<Input, Node> {
+  readonly kind: string;
+  // Type<unknown>, not Type<Input>: AnyEntityKindDescriptor widens Input to never, which would force an unusable Type<never>; concrete descriptors still carry their real schema.
+  readonly schema: Type<unknown>;
+  readonly construct: (input: Input) => Node;
+}
+
+export type AnyEntityKindDescriptor = EntityKindDescriptor<never, unknown>;
+
+/**
+ * Hydrates a namespace's entities from raw JSON maps into IR class instances.
+ *
+ * For each kind in `entries`: if the descriptor map has a descriptor,
+ * construct each inner-map value; otherwise freeze-and-carry (`'carry'`)
+ * or throw naming the kind and nsId (`'fail'`).
+ *
+ * The single boundary cast hands `value` to `descriptor.construct` as its
+ * `Input`. The value satisfies the kind's `Input` either by the
+ * entries-input contract at authoring time or by prior `validateStorage`
+ * validation at hydration time.
+ */
+export function hydrateNamespaceEntities(
+  entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,
+  onUnknown: 'carry' | 'fail',
+  nsId?: string,
+): Record<string, Readonly<Record<string, unknown>>> {
+  const result: Record<string, Readonly<Record<string, unknown>>> = {};
+  for (const [kind, rawMap] of Object.entries(entries)) {
+    const descriptor = kinds.get(kind);
+    if (descriptor !== undefined) {
+      const built: Record<string, unknown> = {};
+      for (const [name, value] of Object.entries(rawMap)) {
+        built[name] = descriptor.construct(
+          blindCast<
+            never,
+            "value is this kind's descriptor Input: when authoring, the typed entries-input contract produces it; when hydrating, it was validated against descriptor.schema before this loop. The never target is AnyEntityKindDescriptor's erased Input parameter."
+          >(value),
+        );
+      }
+      result[kind] = Object.freeze(built);
+    } else if (onUnknown === 'carry') {
+      result[kind] = Object.freeze(rawMap);
+    } else {
+      throw new Error(
+        `Unknown entries key "${kind}" in namespace "${nsId ?? '?'}"; no hydration factory registered for this entity kind`,
+      );
+    }
+  }
+  return result;
+}

package/src/ir/storage.ts

@@ -1,7 +1,11 @@
+import { isPlainRecord } from '@prisma-next/contract/is-plain-record';
 import type { StorageBase } from '@prisma-next/contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import type { IRNode } from './ir-node';
 import type { Namespace } from './namespace';
 
+export { isPlainRecord };
+
 /**
  * Canonical address for a named entity in Contract IR / Schema IR.
  *
@@ -30,11 +34,11 @@ export interface EntityCoordinate {
  * value, yielded as {@link EntityCoordinate} tuples with
  * `plane: 'storage'` (the parameter type binds the plane).
  *
- * Iterates each namespace's `entries` slot maps structurally. Skips
+ * Iterates each namespace's `entries` kind maps structurally. Skips
  * non-object `entries`; `id` and `kind` are not walked (`kind` is
  * non-enumerable on concretions). For every entity-kind key under
  * `entries` whose value is a non-null object, yields one coordinate per
- * entity name in that map. No family-specific slot vocabulary is required.
+ * entity name in that map. No family-specific kind vocabulary is required.
  */
 export function* elementCoordinates(
   storage: Pick<StorageBase, 'namespaces'>,
@@ -42,15 +46,37 @@ export function* elementCoordinates(
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
     const entries = ns.entries;
     if (entries === null || typeof entries !== 'object') continue;
-    for (const [entityKind, slot] of Object.entries(entries)) {
-      if (slot === null || typeof slot !== 'object') continue;
-      for (const entityName of Object.keys(slot)) {
+    for (const [entityKind, kindMap] of Object.entries(entries)) {
+      if (kindMap === null || typeof kindMap !== 'object') continue;
+      for (const entityName of Object.keys(kindMap)) {
         yield { plane: 'storage', namespaceId, entityKind, entityName };
       }
     }
   }
 }
 
+/**
+ * Looks up a single entity in a `Storage`-shaped value by its full coordinate.
+ * Returns `undefined` if the namespace, entity kind, or entity name is absent.
+ * The type parameter is a caller assertion — the walk itself is structural
+ * and cannot verify the entity's shape.
+ */
+export function entityAt<T = unknown>(
+  storage: Pick<StorageBase, 'namespaces'>,
+  coord: Pick<EntityCoordinate, 'namespaceId' | 'entityKind' | 'entityName'>,
+): T | undefined {
+  const ns = storage.namespaces[coord.namespaceId];
+  if (ns === undefined) return undefined;
+  const entries = ns.entries;
+  if (!isPlainRecord(entries)) return undefined;
+  const kindMap = entries[coord.entityKind];
+  if (!isPlainRecord(kindMap)) return undefined;
+  if (!Object.hasOwn(kindMap, coord.entityName)) return undefined;
+  return blindCast<T | undefined, 'caller asserts the entity type at this coordinate'>(
+    kindMap[coord.entityName],
+  );
+}
+
 /**
  * Framework-level promise that every Contract IR / Schema IR carries a
  * collection of namespaces keyed by namespace id. Family storage
@@ -66,7 +92,7 @@ export function* elementCoordinates(
  * is honest at every layer.
  *
  * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,
- * serializers) can dispatch on `Storage`-typed slots through the same
+ * serializers) can dispatch on `Storage`-typed fields through the same
  * IR-node alphabet as every other node — the structural dual already
  * holds in code (every concrete storage class extends an IR-node base);
  * the interface promotion makes the typing honest.

package/src/shared/codec-descriptor.ts

@@ -43,6 +43,8 @@ export interface CodecDescriptor<P = void> {
   readonly isParameterized: boolean;
   /** Emit-path string renderer for `contract.d.ts`. Returns the TypeScript output type expression for given params (e.g. `Vector<1536>`). Optional; absent renderers cause the emitter to fall back to the codec's base output type. Non-parameterized codecs typically omit it. */
   readonly renderOutputType?: (params: P) => string | undefined;
+  /** Emit-path string renderer for the `contract.d.ts` *input* position (create/update values). Returns the TypeScript input type expression for given params. Optional; absent renderers fall back to the codec's base input type. A codec supplies this when its write type is narrower than the generic codec input — e.g. an enum whose input should be the literal member union, not `string`. */
+  readonly renderInputType?: (params: P) => string | undefined;
   /** The curried higher-order codec. For non-parameterized codecs, the factory is constant — every call returns the same shared codec instance. For parameterized codecs, the factory is called once per `storage.types` instance (or once per inline-`typeParams` column), with `ctx` carrying the column set the resulting codec serves. */
   readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;
 }
@@ -78,6 +80,9 @@ export abstract class CodecDescriptorImpl<TParams = void> implements CodecDescri
   /** Optional emit-path string renderer for `contract.d.ts`. Returns the TypeScript output type expression for the given params (e.g. `Vector<1536>`). Non-parameterized codecs typically omit it. */
   renderOutputType?(params: TParams): string | undefined;
 
+  /** Optional emit-path string renderer for the `contract.d.ts` input position. Returns the TypeScript input type expression for the given params; supplied when the write type is narrower than the generic codec input (e.g. an enum's literal member union). */
+  renderInputType?(params: TParams): string | undefined;
+
   /**
    * Materialize a curried codec factory for the given params. Concrete subclasses override with a typed return type (e.g. `factory<N>(params: { length: N }): (ctx) => VectorCodec<N>`); per-codec helpers read the typed return at the *direct* call site, which is what preserves method-level generics. Type extraction (e.g. `ReturnType<D['factory']>`) widens method generics to their constraint — that's why the column-helper surface is per-codec, not polymorphic.
    */

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.
@@ -46,6 +46,26 @@ export interface CodecLookup {
   targetTypesFor(id: string): readonly string[] | undefined;
   metaFor(id: string): CodecMeta | undefined;
   renderOutputTypeFor(id: string, params: Record<string, unknown>): string | undefined;
+  /** Codec-id-keyed `renderInputType` renderer for the `contract.d.ts` input position. Optional so existing lookups need not provide it; returns `undefined` when the codec renders no custom input type or the id is unknown. */
+  renderInputTypeFor?(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 = {