@prisma-next/contract 0.3.0-dev.9 → 0.3.0-dev.90

package/package.json

@@ -1,51 +1,47 @@
 {
   "name": "@prisma-next/contract",
-  "version": "0.3.0-dev.9",
+  "version": "0.3.0-dev.90",
   "type": "module",
   "sideEffects": false,
   "description": "Data contract type definitions and JSON schema for Prisma Next",
   "dependencies": {
-    "@prisma-next/operations": "0.3.0-dev.9"
+    "@prisma-next/operations": "0.3.0-dev.90"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.16",
-    "tsup": "8.5.1",
+    "tsdown": "0.18.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.16",
-    "@prisma-next/test-utils": "0.0.1"
+    "vitest": "4.0.17",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",
     "src",
     "schemas"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
-    "./types": {
-      "types": "./dist/exports/types.d.ts",
-      "import": "./dist/exports/types.js"
-    },
-    "./pack-manifest-types": {
-      "types": "./dist/exports/pack-manifest-types.d.ts",
-      "import": "./dist/exports/pack-manifest-types.js"
-    },
-    "./ir": {
-      "types": "./dist/exports/ir.d.ts",
-      "import": "./dist/exports/ir.js"
-    },
-    "./framework-components": {
-      "types": "./dist/exports/framework-components.d.ts",
-      "import": "./dist/exports/framework-components.js"
-    },
-    "./schema-document": "./schemas/data-contract-document-v1.json"
+    "./framework-components": "./dist/framework-components.mjs",
+    "./ir": "./dist/ir.mjs",
+    "./types": "./dist/types.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/1-core/shared/contract"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts && tsc --project tsconfig.build.json",
+    "build": "tsdown",
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests",
     "typecheck": "tsc --project tsconfig.json --noEmit",
-    "lint": "biome check . --config-path ../../../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../biome.json",
-    "clean": "node ../../../../../scripts/clean.mjs"
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/schemas/data-contract-document-v1.json

@@ -24,10 +24,15 @@
       "enum": ["document"],
       "description": "Target family classification"
     },
-    "coreHash": {
+    "storageHash": {
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$",
-      "description": "SHA-256 hash of the core schema structure (models, fields, relations, storage layout)"
+      "description": "SHA-256 hash of the storage section (DB-satisfied expectations)"
+    },
+    "executionHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 hash of the execution section (client-side behavior)"
     },
     "profileHash": {
       "type": "string",
@@ -85,7 +90,7 @@
       "required": ["document"]
     }
   },
-  "required": ["schemaVersion", "target", "targetFamily", "coreHash", "storage"],
+  "required": ["schemaVersion", "target", "targetFamily", "storageHash", "storage"],
   "$defs": {
     "DocCollection": {
       "type": "object",
@@ -103,7 +108,7 @@
           "properties": {
             "strategy": {
               "type": "string",
-              "enum": ["auto", "client", "uuid", "cuid", "objectId"],
+              "enum": ["auto", "client", "uuid", "objectId"],
               "description": "ID generation strategy"
             }
           }

package/src/exports/framework-components.ts

@@ -16,11 +16,20 @@ export type {
   ExtensionPackRef,
   FamilyDescriptor,
   FamilyInstance,
+  // Type renderers for parameterized codec emission
+  NormalizedTypeRenderer,
   PackRefBase,
   TargetBoundComponentDescriptor,
   TargetDescriptor,
   TargetInstance,
   TargetPackRef,
+  TypeRenderer,
+  TypeRendererFunction,
+  TypeRendererTemplate,
 } from '../framework-components';
 
-export { checkContractComponentRequirements } from '../framework-components';
+export {
+  checkContractComponentRequirements,
+  interpolateTypeTemplate,
+  normalizeRenderer,
+} from '../framework-components';

package/src/exports/types.ts

@@ -1,26 +1,50 @@
-// Shared types
-// Document family types
-// Plan types - target-family agnostic execution types
-// Emitter types (moved from @prisma-next/emitter)
 export type {
+  $,
+  Brand,
+  ColumnDefault,
+  ColumnDefaultLiteralInputValue,
+  ColumnDefaultLiteralValue,
   ContractBase,
   ContractMarkerRecord,
   DocCollection,
   DocIndex,
   DocumentContract,
   DocumentStorage,
+  ExecutionHashBase,
+  ExecutionMutationDefault,
+  ExecutionMutationDefaultValue,
   ExecutionPlan,
+  ExecutionSection,
   Expr,
   FieldType,
-  OperationManifest,
+  GenerateContractTypesOptions,
+  GeneratedValueSpec,
+  JsonPrimitive,
+  JsonValue,
   ParamDescriptor,
+  ParameterizedCodecDescriptor,
   PlanMeta,
   PlanRefs,
+  ProfileHashBase,
+  RenderTypeContext,
   ResultType,
   Source,
+  StorageHashBase,
+  TaggedBigInt,
+  TaggedLiteralValue,
+  TaggedRaw,
   TargetFamilyHook,
+  TypeRenderContext,
+  TypeRenderEntry,
+  TypeRenderer,
   TypesImportSpec,
   ValidationContext,
 } from '../types';
-// Type guards
-export { isDocumentContract } from '../types';
+export {
+  bigintJsonReplacer,
+  coreHash,
+  isDocumentContract,
+  isTaggedBigInt,
+  isTaggedRaw,
+  profileHash,
+} from '../types';

package/src/framework-components.ts

@@ -1,37 +1,156 @@
-import type { OperationManifest, TypesImportSpec } from './types';
-
-// ============================================================================
-// Framework Component Descriptor Base Types
-// ============================================================================
-//
-// Prisma Next uses a modular architecture where functionality is composed from
-// discrete "components". Each component has a descriptor that identifies it and
-// provides metadata. These base types define the shared structure for all
-// component descriptors across both control-plane (CLI/tooling) and runtime-plane.
-//
-// Component Hierarchy:
-//
-//   Family (e.g., 'sql', 'document')
-//     └── Target (e.g., 'postgres', 'mysql', 'mongodb')
-//           ├── Adapter (protocol/dialect implementation)
-//           ├── Driver (connection/execution layer)
-//           └── Extension (optional capabilities like pgvector)
-//
-// Key design decisions:
-// - "Component" terminology separates framework building blocks from delivery
-//   mechanism ("pack" refers to how components are packaged/distributed)
-// - `kind` is extensible (Kind extends string) - no closed union, allowing
-//   ecosystem authors to define new component kinds
-// - Target-bound descriptors are generic in TFamilyId and TTargetId for type-safe
-//   composition (e.g., TypeScript rejects Postgres adapter with MySQL target)
-// - Descriptors own declarative fields directly (version, types, operations, etc.)
-//   rather than nesting them under a `manifest` property
-//
-// ============================================================================
+import type { RenderTypeContext, TypesImportSpec } from './types';
+
+/**
+ * A template-based type renderer (structured form).
+ * Uses mustache-style placeholders (e.g., `Vector<{{length}}>`) that are
+ * replaced with typeParams values during rendering.
+ *
+ * @example
+ * ```ts
+ * { kind: 'template', template: 'Vector<{{length}}>' }
+ * // With typeParams { length: 1536 }, renders: 'Vector<1536>'
+ * ```
+ */
+export interface TypeRendererTemplate {
+  readonly kind: 'template';
+  /** Template string with `{{key}}` placeholders for typeParams values */
+  readonly template: string;
+}
+
+/**
+ * A function-based type renderer for full control over type expression generation.
+ *
+ * @example
+ * ```ts
+ * {
+ *   kind: 'function',
+ *   render: (params, ctx) => `Vector<${params.length}>`
+ * }
+ * ```
+ */
+export interface TypeRendererFunction {
+  readonly kind: 'function';
+  /** Render function that produces a TypeScript type expression */
+  readonly render: (params: Record<string, unknown>, ctx: RenderTypeContext) => string;
+}
+
+/**
+ * A raw template string type renderer (convenience form).
+ * Shorthand for TypeRendererTemplate - just the template string without wrapper.
+ *
+ * @example
+ * ```ts
+ * 'Vector<{{length}}>'
+ * // Equivalent to: { kind: 'template', template: 'Vector<{{length}}>' }
+ * ```
+ */
+export type TypeRendererString = string;
+
+/**
+ * A raw function type renderer (convenience form).
+ * Shorthand for TypeRendererFunction - just the function without wrapper.
+ *
+ * @example
+ * ```ts
+ * (params, ctx) => `Vector<${params.length}>`
+ * // Equivalent to: { kind: 'function', render: ... }
+ * ```
+ */
+export type TypeRendererRawFunction = (
+  params: Record<string, unknown>,
+  ctx: RenderTypeContext,
+) => string;
+
+/**
+ * Union of type renderer formats.
+ *
+ * Supports both structured forms (with `kind` discriminator) and convenience forms:
+ * - `string` - Template string with `{{key}}` placeholders (manifest-safe, JSON-serializable)
+ * - `function` - Render function for full control (requires runtime execution)
+ * - `{ kind: 'template', template: string }` - Structured template form
+ * - `{ kind: 'function', render: fn }` - Structured function form
+ *
+ * Templates are normalized to functions during pack assembly.
+ * **Prefer template strings** for most cases - they are JSON-serializable.
+ */
+export type TypeRenderer =
+  | TypeRendererString
+  | TypeRendererRawFunction
+  | TypeRendererTemplate
+  | TypeRendererFunction;
+
+/**
+ * Normalized type renderer - always a function after assembly.
+ * This is the form received by the emitter.
+ */
+export interface NormalizedTypeRenderer {
+  readonly codecId: string;
+  readonly render: (params: Record<string, unknown>, ctx: RenderTypeContext) => string;
+}
+
+/**
+ * Interpolates a template string with params values.
+ * Used internally by normalizeRenderer to compile templates to functions.
+ *
+ * @throws Error if a placeholder key is not found in params (except 'CodecTypes')
+ */
+export function interpolateTypeTemplate(
+  template: string,
+  params: Record<string, unknown>,
+  ctx: RenderTypeContext,
+): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => {
+    if (key === 'CodecTypes') return ctx.codecTypesName;
+    const value = params[key];
+    if (value === undefined) {
+      throw new Error(
+        `Missing template parameter "${key}" in template "${template}". ` +
+          `Available params: ${Object.keys(params).join(', ') || '(none)'}`,
+      );
+    }
+    return String(value);
+  });
+}
+
+/**
+ * Normalizes a TypeRenderer to function form.
+ * Called during pack assembly, not at emission time.
+ *
+ * Handles all TypeRenderer forms:
+ * - Raw string template: `'Vector<{{length}}>'`
+ * - Raw function: `(params, ctx) => ...`
+ * - Structured template: `{ kind: 'template', template: '...' }`
+ * - Structured function: `{ kind: 'function', render: fn }`
+ */
+export function normalizeRenderer(codecId: string, renderer: TypeRenderer): NormalizedTypeRenderer {
+  // Handle raw string (template shorthand)
+  if (typeof renderer === 'string') {
+    return {
+      codecId,
+      render: (params, ctx) => interpolateTypeTemplate(renderer, params, ctx),
+    };
+  }
+
+  // Handle raw function (function shorthand)
+  if (typeof renderer === 'function') {
+    return { codecId, render: renderer };
+  }
+
+  // Handle structured function form
+  if (renderer.kind === 'function') {
+    return { codecId, render: renderer.render };
+  }
+
+  // Handle structured template form
+  const { template } = renderer;
+  return {
+    codecId,
+    render: (params, ctx) => interpolateTypeTemplate(template, params, ctx),
+  };
+}
 
 /**
  * Declarative fields that describe component metadata.
- * These fields are owned directly by descriptors (not nested under a manifest).
  */
 export interface ComponentMetadata {
   /** Component version (semver) */
@@ -49,7 +168,35 @@ export interface ComponentMetadata {
 
   /** Type imports for contract.d.ts generation */
   readonly types?: {
-    readonly codecTypes?: { readonly import: TypesImportSpec };
+    readonly codecTypes?: {
+      /**
+       * Base codec types import spec.
+       * Optional: adapters typically provide this, extensions usually don't.
+       */
+      readonly import?: TypesImportSpec;
+      /**
+       * Optional renderers for parameterized codecs owned by this component.
+       * Key is codecId (e.g., 'pg/vector@1'), value is the type renderer.
+       *
+       * Templates are normalized to functions during pack assembly.
+       * Duplicate codecId across descriptors is a hard error.
+       */
+      readonly parameterized?: Record<string, TypeRenderer>;
+      /**
+       * Optional additional type-only imports required by parameterized renderers.
+       *
+       * These imports are included in generated `contract.d.ts` but are NOT treated as
+       * codec type maps (i.e., they should not be intersected into `export type CodecTypes = ...`).
+       *
+       * Example: `Vector<N>` for pgvector renderers that emit `Vector<{{length}}>`
+       */
+      readonly typeImports?: ReadonlyArray<TypesImportSpec>;
+      /**
+       * Optional control-plane hooks keyed by codecId.
+       * Used by family-specific planners/verifiers to handle storage types.
+       */
+      readonly controlPlaneHooks?: Record<string, unknown>;
+    };
     readonly operationTypes?: { readonly import: TypesImportSpec };
     readonly storage?: ReadonlyArray<{
       readonly typeId: string;
@@ -58,9 +205,6 @@ export interface ComponentMetadata {
       readonly nativeType?: string;
     }>;
   };
-
-  /** Operation manifests for building operation registries */
-  readonly operations?: ReadonlyArray<OperationManifest>;
 }
 
 /**
@@ -393,17 +537,6 @@ export type TargetBoundComponentDescriptor<TFamilyId extends string, TTargetId e
   | DriverDescriptor<TFamilyId, TTargetId>
   | ExtensionDescriptor<TFamilyId, TTargetId>;
 
-// ============================================================================
-// Framework Component Instance Base Types
-// ============================================================================
-//
-// These are minimal, identity-only interfaces for component instances.
-// They carry the component's identity (familyId, targetId) without any
-// behavior methods. Plane-specific interfaces (ControlFamilyInstance,
-// RuntimeFamilyInstance, etc.) extend these bases and add domain actions.
-//
-// ============================================================================
-
 /**
  * Base interface for family instances.
  *

package/src/ir.ts

@@ -1,3 +1,10 @@
+function ifDefined<K extends string, V>(
+  key: K,
+  value: V | undefined,
+): Record<never, never> | { [P in K]: V } {
+  return value !== undefined ? ({ [key]: value } as { [P in K]: V }) : {};
+}
+
 /**
  * ContractIR types and factories for building contract intermediate representation.
  * ContractIR is family-agnostic and used by authoring, emitter, and no-emit runtime.
@@ -6,12 +13,13 @@
 /**
  * ContractIR represents the intermediate representation of a contract.
  * It is family-agnostic and contains generic storage, models, and relations.
- * Note: coreHash and profileHash are computed by the emitter, not part of the IR.
+ * Note: storageHash/executionHash and profileHash are computed by the emitter, not part of the IR.
  */
 export interface ContractIR<
   TStorage extends Record<string, unknown> = Record<string, unknown>,
   TModels extends Record<string, unknown> = Record<string, unknown>,
   TRelations extends Record<string, unknown> = Record<string, unknown>,
+  TExecution extends Record<string, unknown> = Record<string, unknown>,
 > {
   readonly schemaVersion: string;
   readonly targetFamily: string;
@@ -19,6 +27,7 @@ export interface ContractIR<
   readonly models: TModels;
   readonly relations: TRelations;
   readonly storage: TStorage;
+  readonly execution?: TExecution;
   readonly extensionPacks: Record<string, unknown>;
   readonly capabilities: Record<string, Record<string, boolean>>;
   readonly meta: Record<string, unknown>;
@@ -27,26 +36,29 @@ export interface ContractIR<
 
 /**
  * Creates the header portion of a ContractIR.
- * Contains schema version, target, target family, core hash, and optional profile hash.
+ * Contains schema version, target, target family, storage hash, and optional profile hash.
  */
 export function irHeader(opts: {
   target: string;
   targetFamily: string;
-  coreHash: string;
-  profileHash?: string;
+  storageHash: string;
+  executionHash?: string | undefined;
+  profileHash?: string | undefined;
 }): {
   readonly schemaVersion: string;
   readonly target: string;
   readonly targetFamily: string;
-  readonly coreHash: string;
-  readonly profileHash?: string;
+  readonly storageHash: string;
+  readonly executionHash?: string | undefined;
+  readonly profileHash?: string | undefined;
 } {
   return {
     schemaVersion: '1',
     target: opts.target,
     targetFamily: opts.targetFamily,
-    coreHash: opts.coreHash,
-    ...(opts.profileHash !== undefined && { profileHash: opts.profileHash }),
+    storageHash: opts.storageHash,
+    ...ifDefined('executionHash', opts.executionHash),
+    ...ifDefined('profileHash', opts.profileHash),
   };
 }
 
@@ -82,13 +94,15 @@ export function contractIR<
   TStorage extends Record<string, unknown>,
   TModels extends Record<string, unknown>,
   TRelations extends Record<string, unknown>,
+  TExecution extends Record<string, unknown>,
 >(opts: {
   header: {
     readonly schemaVersion: string;
     readonly target: string;
     readonly targetFamily: string;
-    readonly coreHash: string;
-    readonly profileHash?: string;
+    readonly storageHash: string;
+    readonly executionHash?: string | undefined;
+    readonly profileHash?: string | undefined;
   };
   meta: {
     readonly capabilities: Record<string, Record<string, boolean>>;
@@ -99,8 +113,9 @@ export function contractIR<
   storage: TStorage;
   models: TModels;
   relations: TRelations;
-}): ContractIR<TStorage, TModels, TRelations> {
-  // ContractIR doesn't include coreHash or profileHash (those are computed by emitter)
+  execution?: TExecution;
+}): ContractIR<TStorage, TModels, TRelations, TExecution> {
+  // ContractIR doesn't include storageHash/executionHash or profileHash (those are computed by emitter)
   return {
     schemaVersion: opts.header.schemaVersion,
     target: opts.header.target,
@@ -109,5 +124,6 @@ export function contractIR<
     storage: opts.storage,
     models: opts.models,
     relations: opts.relations,
+    ...ifDefined('execution', opts.execution),
   };
 }