@prisma-next/core-control-plane 0.3.0-dev.5 → 0.3.0-dev.50

package/package.json

@@ -1,61 +1,54 @@
 {
   "name": "@prisma-next/core-control-plane",
-  "version": "0.3.0-dev.5",
+  "version": "0.3.0-dev.50",
   "type": "module",
   "sideEffects": false,
   "description": "Control plane domain actions, config types, validation, and error factories for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.26",
     "prettier": "^3.3.3",
-    "@prisma-next/contract": "0.3.0-dev.5",
-    "@prisma-next/operations": "0.3.0-dev.5",
-    "@prisma-next/utils": "0.3.0-dev.5"
+    "@prisma-next/contract": "0.3.0-dev.50",
+    "@prisma-next/operations": "0.3.0-dev.50",
+    "@prisma-next/utils": "0.3.0-dev.50"
   },
   "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/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",
     "src"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
-    "./config-types": {
-      "types": "./dist/exports/config-types.d.ts",
-      "import": "./dist/exports/config-types.js"
-    },
-    "./config-validation": {
-      "types": "./dist/exports/config-validation.d.ts",
-      "import": "./dist/exports/config-validation.js"
-    },
-    "./errors": {
-      "types": "./dist/exports/errors.d.ts",
-      "import": "./dist/exports/errors.js"
-    },
-    "./types": {
-      "types": "./dist/exports/types.d.ts",
-      "import": "./dist/exports/types.js"
-    },
-    "./emission": {
-      "types": "./dist/exports/emission.d.ts",
-      "import": "./dist/exports/emission.js"
-    },
-    "./schema-view": {
-      "types": "./dist/exports/schema-view.d.ts",
-      "import": "./dist/exports/schema-view.js"
-    }
+    "./config-types": "./dist/config-types.mjs",
+    "./config-validation": "./dist/config-validation.mjs",
+    "./emission": "./dist/emission.mjs",
+    "./errors": "./dist/errors.mjs",
+    "./schema-view": "./dist/schema-view.mjs",
+    "./stack": "./dist/stack.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/migration/control-plane"
   },
   "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"
+    "typecheck": "tsc --noEmit",
+    "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/src/config-types.ts

@@ -1,5 +1,5 @@
-import { dirname, join } from 'node:path';
 import { type } from 'arktype';
+import type { ContractSourceProvider } from './contract-source-types';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -20,21 +20,15 @@ export type CliDriver = ControlDriverInstance<string, string>;
  */
 export interface ContractConfig {
   /**
-   * Contract source. Can be a value or a function that returns a value (sync or async).
-   * If a function, it will be called to resolve the contract.
+   * Contract source provider. The provider is always async and must return
+   * a Result containing either ContractIR or structured diagnostics.
    */
-  readonly source: unknown | (() => unknown | Promise<unknown>);
+  readonly source: ContractSourceProvider;
   /**
    * Path to contract.json artifact. Defaults to 'src/prisma/contract.json'.
-   * This is the canonical location where other CLI commands can find the contract JSON.
+   * The .d.ts types file will be colocated (e.g., contract.json → contract.d.ts).
    */
   readonly output?: string;
-  /**
-   * Path to contract.d.ts artifact. Defaults to output with .d.ts extension.
-   * If output ends with .json, replaces .json with .d.ts.
-   * Otherwise, appends .d.ts to the directory containing output.
-   */
-  readonly types?: string;
 }
 
 /**
@@ -43,10 +37,12 @@ export interface ContractConfig {
  *
  * @template TFamilyId - The family ID (e.g., 'sql', 'document')
  * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TConnection - The driver connection input type (defaults to `unknown` for config flexibility)
  */
 export interface PrismaNextConfig<
   TFamilyId extends string = string,
   TTargetId extends string = string,
+  TConnection = unknown,
 > {
   readonly family: ControlFamilyDescriptor<TFamilyId>;
   readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
@@ -56,10 +52,25 @@ export interface PrismaNextConfig<
    * Driver descriptor for DB-connected CLI commands.
    * Required for DB-connected commands (e.g., db verify).
    * Optional for commands that don't need database access (e.g., emit).
+   * The driver's connection type matches the TConnection config parameter.
+   */
+  readonly driver?: ControlDriverDescriptor<
+    TFamilyId,
+    TTargetId,
+    ControlDriverInstance<TFamilyId, TTargetId>,
+    TConnection
+  >;
+  /**
+   * Database connection configuration.
+   * The connection type is driver-specific (e.g., URL string for Postgres).
    */
-  readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId>;
   readonly db?: {
-    readonly url?: string;
+    /**
+     * Driver-specific connection input.
+     * For Postgres: a connection string (URL).
+     * For other drivers: may be a structured object.
+     */
+    readonly connection?: TConnection;
   };
   /**
    * Contract configuration. Specifies source and artifact locations.
@@ -70,12 +81,12 @@ export interface PrismaNextConfig<
 
 /**
  * Arktype schema for ContractConfig validation.
- * Validates that source is present and output/types are strings when provided.
+ * Validates presence/shape only.
+ * contract.source is validated as a provider function at runtime in defineConfig().
  */
 const ContractConfigSchema = type({
-  source: 'unknown', // Can be value or function - runtime check needed
+  source: 'unknown', // Runtime check enforces provider function shape
   'output?': 'string',
-  'types?': 'string',
 });
 
 /**
@@ -98,7 +109,6 @@ const PrismaNextConfigSchema = type({
  *
  * Normalization:
  * - contract.output defaults to 'src/prisma/contract.json' if missing
- * - contract.types defaults to output with .d.ts extension if missing
  *
  * @param config - Raw config input from user
  * @returns Normalized config IR with defaults applied
@@ -116,33 +126,18 @@ export function defineConfig<TFamilyId extends string = string, TTargetId extend
 
   // Normalize contract config if present
   if (config.contract) {
-    // Validate contract.source is a value or function (runtime check)
+    // Validate contract.source provider function shape at runtime.
     const source = config.contract.source;
-    if (
-      source !== null &&
-      typeof source !== 'object' &&
-      typeof source !== 'function' &&
-      typeof source !== 'string' &&
-      typeof source !== 'number' &&
-      typeof source !== 'boolean'
-    ) {
-      throw new Error(
-        'Config.contract.source must be a value (object, string, number, boolean, null) or a function',
-      );
+    if (typeof source !== 'function') {
+      throw new Error('Config.contract.source must be a provider function');
     }
 
     // Apply defaults
     const output = config.contract.output ?? 'src/prisma/contract.json';
-    const types =
-      config.contract.types ??
-      (output.endsWith('.json')
-        ? `${output.slice(0, -5)}.d.ts`
-        : join(dirname(output), 'contract.d.ts'));
 
     const normalizedContract: ContractConfig = {
       source: config.contract.source,
       output,
-      types,
     };
 
     // Return normalized config

package/src/config-validation.ts

@@ -256,15 +256,17 @@ export function validateConfig(config: unknown): asserts config is PrismaNextCon
         why: 'Config.contract.source is required when contract is provided',
       });
     }
+
+    if (typeof contract['source'] !== 'function') {
+      throw errorConfigValidation('contract.source', {
+        why: 'Config.contract.source must be a provider function',
+      });
+    }
+
     if (contract['output'] !== undefined && typeof contract['output'] !== 'string') {
       throw errorConfigValidation('contract.output', {
         why: 'Config.contract.output must be a string when provided',
       });
     }
-    if (contract['types'] !== undefined && typeof contract['types'] !== 'string') {
-      throw errorConfigValidation('contract.types', {
-        why: 'Config.contract.types must be a string when provided',
-      });
-    }
   }
 }

package/src/contract-source-types.ts

@@ -0,0 +1,28 @@
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { Result } from '@prisma-next/utils/result';
+
+export interface ContractSourceDiagnosticPosition {
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+}
+
+export interface ContractSourceDiagnosticSpan {
+  readonly start: ContractSourceDiagnosticPosition;
+  readonly end: ContractSourceDiagnosticPosition;
+}
+
+export interface ContractSourceDiagnostic {
+  readonly code: string;
+  readonly message: string;
+  readonly sourceId?: string;
+  readonly span?: ContractSourceDiagnosticSpan;
+}
+
+export interface ContractSourceDiagnostics {
+  readonly summary: string;
+  readonly diagnostics: readonly ContractSourceDiagnostic[];
+  readonly meta?: Record<string, unknown>;
+}
+
+export type ContractSourceProvider = () => Promise<Result<ContractIR, ContractSourceDiagnostics>>;

package/src/emission/canonicalization.ts

@@ -1,19 +1,37 @@
-import type { ContractIR } from '@prisma-next/contract/ir';
+import { bigintJsonReplacer } from '@prisma-next/contract/types';
 import { isArrayEqual } from '@prisma-next/utils/array-equal';
+import { ifDefined } from '@prisma-next/utils/defined';
 
 type NormalizedContract = {
   schemaVersion: string;
   targetFamily: string;
   target: string;
-  coreHash?: string;
+  storageHash?: string;
+  executionHash?: string;
   profileHash?: string;
   models: Record<string, unknown>;
   relations: Record<string, unknown>;
   storage: Record<string, unknown>;
+  execution?: Record<string, unknown>;
   extensionPacks: Record<string, unknown>;
   capabilities: Record<string, Record<string, boolean>>;
   meta: Record<string, unknown>;
-  sources: Record<string, unknown>;
+};
+
+export type CanonicalContractInput = {
+  schemaVersion: string;
+  targetFamily: string;
+  target: string;
+  models: Record<string, unknown>;
+  relations: Record<string, unknown>;
+  storage: Record<string, unknown>;
+  execution?: Record<string, unknown>;
+  extensionPacks: Record<string, unknown>;
+  capabilities: Record<string, Record<string, boolean>>;
+  meta: Record<string, unknown>;
+  storageHash?: string;
+  executionHash?: string;
+  profileHash?: string;
 };
 
 const TOP_LEVEL_ORDER = [
@@ -21,19 +39,22 @@ const TOP_LEVEL_ORDER = [
   'canonicalVersion',
   'targetFamily',
   'target',
-  'coreHash',
+  'storageHash',
+  'executionHash',
   'profileHash',
   'models',
+  'relations',
   'storage',
+  'execution',
   'capabilities',
   'extensionPacks',
   'meta',
-  'sources',
 ] as const;
 
 function isDefaultValue(value: unknown): boolean {
   if (value === false) return true;
   if (value === null) return false;
+  if (value instanceof Date) return false;
   if (Array.isArray(value) && value.length === 0) return true;
   if (typeof value === 'object' && value !== null) {
     const keys = Object.keys(value);
@@ -47,6 +68,10 @@ function omitDefaults(obj: unknown, path: readonly string[]): unknown {
     return obj;
   }
 
+  if (obj instanceof Date) {
+    return obj;
+  }
+
   if (Array.isArray(obj)) {
     return obj.map((item) => omitDefaults(item, path));
   }
@@ -69,6 +94,13 @@ function omitDefaults(obj: unknown, path: readonly string[]): unknown {
       continue;
     }
 
+    // Strip 'noAction' referential actions (the database default) for hash stability.
+    // A contract with explicit `onDelete: 'noAction'` is semantically identical to
+    // one that omits `onDelete` entirely, so they should produce the same hash.
+    if ((key === 'onDelete' || key === 'onUpdate') && value === 'noAction') {
+      continue;
+    }
+
     if (isDefaultValue(value)) {
       const isRequiredModels = isArrayEqual(currentPath, ['models']);
       const isRequiredTables = isArrayEqual(currentPath, ['storage', 'tables']);
@@ -76,7 +108,11 @@ function omitDefaults(obj: unknown, path: readonly string[]): unknown {
       const isRequiredExtensionPacks = isArrayEqual(currentPath, ['extensionPacks']);
       const isRequiredCapabilities = isArrayEqual(currentPath, ['capabilities']);
       const isRequiredMeta = isArrayEqual(currentPath, ['meta']);
-      const isRequiredSources = isArrayEqual(currentPath, ['sources']);
+      const isRequiredExecutionDefaults = isArrayEqual(currentPath, [
+        'execution',
+        'mutations',
+        'defaults',
+      ]);
       const isExtensionNamespace = currentPath.length === 2 && currentPath[0] === 'extensionPacks';
       const isModelRelations =
         currentPath.length === 3 &&
@@ -100,6 +136,16 @@ function omitDefaults(obj: unknown, path: readonly string[]): unknown {
           ['storage', 'tables', 'foreignKeys'],
         );
 
+      // Preserve per-FK `constraint` and `index` booleans (even when `false`)
+      // so that hash distinguishes `false` from absent.
+      // Path: ['storage', 'tables', <tableName>, 'foreignKeys', 'constraint' | 'index']
+      const isFkBooleanField =
+        currentPath.length === 5 &&
+        currentPath[0] === 'storage' &&
+        currentPath[1] === 'tables' &&
+        currentPath[3] === 'foreignKeys' &&
+        (key === 'constraint' || key === 'index');
+
       if (
         !isRequiredModels &&
         !isRequiredTables &&
@@ -107,12 +153,13 @@ function omitDefaults(obj: unknown, path: readonly string[]): unknown {
         !isRequiredExtensionPacks &&
         !isRequiredCapabilities &&
         !isRequiredMeta &&
-        !isRequiredSources &&
+        !isRequiredExecutionDefaults &&
         !isExtensionNamespace &&
         !isModelRelations &&
         !isTableUniques &&
         !isTableIndexes &&
-        !isTableForeignKeys
+        !isTableForeignKeys &&
+        !isFkBooleanField
       ) {
         continue;
       }
@@ -129,6 +176,10 @@ function sortObjectKeys(obj: unknown): unknown {
     return obj;
   }
 
+  if (obj instanceof Date) {
+    return obj;
+  }
+
   if (Array.isArray(obj)) {
     return obj.map((item) => sortObjectKeys(item));
   }
@@ -219,9 +270,7 @@ function orderTopLevel(obj: Record<string, unknown>): Record<string, unknown> {
   return ordered;
 }
 
-export function canonicalizeContract(
-  ir: ContractIR & { coreHash?: string; profileHash?: string },
-): string {
+export function canonicalizeContract(ir: CanonicalContractInput): string {
   const normalized: NormalizedContract = {
     schemaVersion: ir.schemaVersion,
     targetFamily: ir.targetFamily,
@@ -229,19 +278,17 @@ export function canonicalizeContract(
     models: ir.models,
     relations: ir.relations,
     storage: ir.storage,
+    ...ifDefined('execution', ir.execution),
     extensionPacks: ir.extensionPacks,
     capabilities: ir.capabilities,
     meta: ir.meta,
-    sources: ir.sources,
   };
-
-  if (ir.coreHash !== undefined) {
-    normalized.coreHash = ir.coreHash;
-  }
-
-  if (ir.profileHash !== undefined) {
-    normalized.profileHash = ir.profileHash;
-  }
+  Object.assign(
+    normalized,
+    ifDefined('storageHash', ir.storageHash),
+    ifDefined('executionHash', ir.executionHash),
+    ifDefined('profileHash', ir.profileHash),
+  );
 
   const withDefaultsOmitted = omitDefaults(normalized, []) as NormalizedContract;
   const withSortedIndexes = sortIndexesAndUniques(withDefaultsOmitted.storage);
@@ -249,5 +296,5 @@ export function canonicalizeContract(
   const withSortedKeys = sortObjectKeys(withSortedStorage) as Record<string, unknown>;
   const withOrderedTopLevel = orderTopLevel(withSortedKeys);
 
-  return JSON.stringify(withOrderedTopLevel, null, 2);
+  return JSON.stringify(withOrderedTopLevel, bigintJsonReplacer, 2);
 }

package/src/emission/emit.ts

@@ -1,10 +1,47 @@
 import type { ContractIR } from '@prisma-next/contract/ir';
 import type { TargetFamilyHook, ValidationContext } from '@prisma-next/contract/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { type } from 'arktype';
 import { format } from 'prettier';
 import { canonicalizeContract } from './canonicalization';
-import { computeCoreHash, computeProfileHash } from './hashing';
+import { computeExecutionHash, computeProfileHash, computeStorageHash } from './hashing';
 import type { EmitOptions, EmitResult } from './types';
 
+const CanonicalMetaSchema = type({
+  '[string]': 'unknown',
+});
+
+const CanonicalContractSchema = type({
+  '+': 'reject',
+  schemaVersion: 'string',
+  targetFamily: 'string',
+  target: 'string',
+  models: type({ '[string]': 'unknown' }),
+  relations: type({ '[string]': 'unknown' }),
+  storage: type({ '[string]': 'unknown' }),
+  'execution?': type({ '[string]': 'unknown' }),
+  extensionPacks: type({ '[string]': 'unknown' }),
+  capabilities: type({
+    '[string]': type({
+      '[string]': 'boolean',
+    }),
+  }),
+  meta: CanonicalMetaSchema,
+});
+
+function assertCanonicalArtifactShape(value: unknown): void {
+  const result = CanonicalContractSchema(value);
+  if (result instanceof type.errors) {
+    const issues = result
+      .map((error) => {
+        const path = error.path?.toString() ?? '<root>';
+        return `${path}: ${error.message}`;
+      })
+      .join('; ');
+    throw new Error(`ContractIR canonical artifact validation failed: ${issues}`);
+  }
+}
+
 function validateCoreStructure(ir: ContractIR): void {
   if (!ir.targetFamily) {
     throw new Error('ContractIR must have targetFamily');
@@ -33,9 +70,6 @@ function validateCoreStructure(ir: ContractIR): void {
   if (!ir.meta || typeof ir.meta !== 'object') {
     throw new Error('ContractIR must have meta');
   }
-  if (!ir.sources || typeof ir.sources !== 'object') {
-    throw new Error('ContractIR must have sources');
-  }
 }
 
 export async function emit(
@@ -43,40 +77,51 @@ export async function emit(
   options: EmitOptions,
   targetFamily: TargetFamilyHook,
 ): Promise<EmitResult> {
-  const { operationRegistry, codecTypeImports, operationTypeImports, extensionIds } = options;
+  const {
+    operationRegistry,
+    codecTypeImports,
+    operationTypeImports,
+    extensionIds,
+    parameterizedRenderers,
+    parameterizedTypeImports,
+  } = options;
 
   validateCoreStructure(ir);
 
   const ctx: ValidationContext = {
-    ...(operationRegistry ? { operationRegistry } : {}),
-    ...(codecTypeImports ? { codecTypeImports } : {}),
-    ...(operationTypeImports ? { operationTypeImports } : {}),
-    ...(extensionIds ? { extensionIds } : {}),
+    ...ifDefined('operationRegistry', operationRegistry),
+    ...ifDefined('codecTypeImports', codecTypeImports),
+    ...ifDefined('operationTypeImports', operationTypeImports),
+    ...ifDefined('extensionIds', extensionIds),
   };
   targetFamily.validateTypes(ir, ctx);
 
   targetFamily.validateStructure(ir);
 
-  const contractJson = {
+  const canonicalContract = {
     schemaVersion: ir.schemaVersion,
     targetFamily: ir.targetFamily,
     target: ir.target,
     models: ir.models,
     relations: ir.relations,
     storage: ir.storage,
+    ...ifDefined('execution', ir.execution),
     extensionPacks: ir.extensionPacks,
     capabilities: ir.capabilities,
     meta: ir.meta,
-    sources: ir.sources,
-  } as const;
+  };
+  assertCanonicalArtifactShape(canonicalContract);
 
-  const coreHash = computeCoreHash(contractJson);
-  const profileHash = computeProfileHash(contractJson);
+  const storageHash = computeStorageHash(canonicalContract);
+  const executionHash = canonicalContract.execution
+    ? computeExecutionHash(canonicalContract)
+    : undefined;
+  const profileHash = computeProfileHash(canonicalContract);
 
-  const contractWithHashes: ContractIR & { coreHash?: string; profileHash?: string } = {
-    ...ir,
-    schemaVersion: contractJson.schemaVersion,
-    coreHash,
+  const contractWithHashes = {
+    ...canonicalContract,
+    storageHash,
+    ...ifDefined('executionHash', executionHash),
     profileHash,
   };
 
@@ -91,16 +136,31 @@ export async function emit(
     ...contractJsonObj,
     _generated: {
       warning: '⚠️  GENERATED FILE - DO NOT EDIT',
-      message: 'This file is automatically generated by "prisma-next emit".',
-      regenerate: 'To regenerate, run: prisma-next emit',
+      message: 'This file is automatically generated by "prisma-next contract emit".',
+      regenerate: 'To regenerate, run: prisma-next contract emit',
     },
   };
   const contractJsonString = JSON.stringify(contractJsonWithMeta, null, 2);
 
+  const generateOptions =
+    parameterizedRenderers || parameterizedTypeImports
+      ? {
+          ...ifDefined('parameterizedRenderers', parameterizedRenderers),
+          ...ifDefined('parameterizedTypeImports', parameterizedTypeImports),
+        }
+      : undefined;
+
+  const contractTypeHashes = {
+    storageHash,
+    ...ifDefined('executionHash', executionHash),
+    profileHash,
+  };
   const contractDtsRaw = targetFamily.generateContractTypes(
     ir,
     codecTypeImports ?? [],
     operationTypeImports ?? [],
+    contractTypeHashes,
+    generateOptions,
   );
   const contractDts = await format(contractDtsRaw, {
     parser: 'typescript',
@@ -112,7 +172,8 @@ export async function emit(
   return {
     contractJson: contractJsonString,
     contractDts,
-    coreHash,
+    storageHash,
+    ...ifDefined('executionHash', executionHash),
     profileHash,
   };
 }