@prisma-next/cli 0.8.0-dev.9 → 0.9.0-dev.1

package/src/commands/migration-new.ts

@@ -8,7 +8,7 @@
  * verbatim.
  */
 
-import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { APP_SPACE_ID, createControlStack } from '@prisma-next/framework-components/control';
@@ -73,11 +73,17 @@ async function executeMigrationNewCommand(
   const config = await loadConfig(options.config);
   const { appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.config, config);
 
+  // Construct the family instance up-front so the on-disk contract read
+  // below crosses the serializer seam (`familyInstance.deserializeContract`)
+  // at the read site, not somewhere downstream. See TML-2536.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
   const contractPathAbsolute = resolveContractPath(config);
 
   let contractJsonContent: string;
   try {
-    contractJsonContent = readFileSync(contractPathAbsolute, 'utf-8');
+    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
   } catch (error) {
     if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
       return notOk(
@@ -90,24 +96,20 @@ async function executeMigrationNewCommand(
     throw error;
   }
 
-  let toContractJson: Contract;
+  let toContract: Contract;
   try {
-    toContractJson = JSON.parse(contractJsonContent) as Contract;
+    toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
     return notOk(
       errorRuntime('Contract JSON is invalid', {
-        why: `Failed to parse ${contractPathAbsolute}: ${error instanceof Error ? error.message : String(error)}`,
+        why: `Failed to deserialize ${contractPathAbsolute}: ${error instanceof Error ? error.message : String(error)}`,
         fix: 'Run `prisma-next contract emit` to regenerate the contract',
       }),
     );
   }
 
-  const toStorageHash = (
-    (toContractJson as unknown as Record<string, unknown>)['storage'] as
-      | Record<string, unknown>
-      | undefined
-  )?.['storageHash'] as string | undefined;
-  if (!toStorageHash) {
+  const toStorageHash = toContract.storage?.storageHash;
+  if (typeof toStorageHash !== 'string') {
     return notOk(
       errorRuntime('Contract is missing storageHash', {
         why: `Contract at ${contractPathAbsolute} has no storageHash`,
@@ -236,8 +238,6 @@ async function executeMigrationNewCommand(
       }
     }
 
-    const stack = createControlStack(config);
-    const familyInstance = config.family.create(stack);
     const planner = migrations.createPlanner(familyInstance);
     const emptyPlan = planner.emptyMigration(
       {

package/src/commands/migration-plan.ts

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import {
+  type ControlFamilyInstance,
   createControlStack,
   hasOperationPreview,
   type MigrationPlanOperation,
@@ -62,16 +63,27 @@ interface MigrationPlanOptions extends CommonCommandOptions {
 
 /**
  * Load a predecessor migration's destination contract from its sibling
- * `end-contract.json` on disk. The manifest no longer inlines the
- * contract; the planner reads it from the canonical on-disk artefact
- * authored by a previous `migration plan` run.
+ * `end-contract.json` on disk and route it through the family's
+ * `ContractSerializer` (via `deserializeContract`) so the in-memory shape
+ * is the hydrated `Contract` every other caller sees. Bypassing this
+ * seam was the root cause of TML-2536: a raw `JSON.parse(...) as Contract`
+ * here let polymorphic `storage.types` entries reach the planner without
+ * the `kind` discriminator the planner dispatches on.
  *
- * Throws `CliStructuredError` with `errorFileNotFound` when the
- * sibling file is missing — the user has likely deleted or never
- * authored the snapshot, and the message names the file and points
- * them at re-emitting from the source.
+ * Throws `CliStructuredError` with:
+ *   - `errorFileNotFound` when the sibling file is missing — the user
+ *     has likely deleted or never authored the snapshot, and the
+ *     message names the file and points them at re-emitting from the
+ *     source.
+ *   - `errorContractValidationFailed` when the JSON parses but the
+ *     family deserializer rejects it (legacy untagged shape, structural
+ *     mismatch, etc.) — the message names the predecessor's path so
+ *     the operator can locate the bad snapshot.
  */
-async function readPredecessorEndContract(migrationDir: string): Promise<Contract> {
+async function readPredecessorEndContract(
+  migrationDir: string,
+  familyInstance: ControlFamilyInstance<string, unknown>,
+): Promise<Contract> {
   const path = join(migrationDir, 'end-contract.json');
   let raw: string;
   try {
@@ -85,7 +97,17 @@ async function readPredecessorEndContract(migrationDir: string): Promise<Contrac
     }
     throw error;
   }
-  return JSON.parse(raw) as Contract;
+  try {
+    return familyInstance.deserializeContract(JSON.parse(raw) as unknown);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      throw error;
+    }
+    throw errorContractValidationFailed(
+      `Predecessor contract at ${path} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
+      { where: { path } },
+    );
+  }
 }
 
 export interface MigrationPlanResult {
@@ -185,19 +207,26 @@ async function executeMigrationPlanCommand(
     );
   }
 
-  let toContractJson: Contract;
+  // Construct the family instance up-front so on-disk reads (the app
+  // contract here + every `readPredecessorEndContract` below) cross the
+  // serializer seam at the read site, not after the planner has already
+  // started dispatching on raw shapes. See TML-2536.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
+  let toContract: Contract;
   try {
-    toContractJson = JSON.parse(contractJsonContent) as Contract;
+    toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
     return notOk(
       errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        `Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
         { where: { path: contractPathAbsolute } },
       ),
     );
   }
 
-  const rawStorageHash = toContractJson.storage?.storageHash;
+  const rawStorageHash = toContract.storage?.storageHash;
   if (typeof rawStorageHash !== 'string') {
     return notOk(
       errorContractValidationFailed('Contract is missing storageHash', {
@@ -235,7 +264,7 @@ async function executeMigrationPlanCommand(
         );
       }
       fromContractSourceDir = matchingBundle.dirPath;
-      fromContract = await readPredecessorEndContract(fromContractSourceDir);
+      fromContract = await readPredecessorEndContract(fromContractSourceDir, familyInstance);
     } else {
       const latestMigration = findLatestMigration(graph);
       if (latestMigration) {
@@ -245,7 +274,7 @@ async function executeMigrationPlanCommand(
         );
         if (leafPkg) {
           fromContractSourceDir = leafPkg.dirPath;
-          fromContract = await readPredecessorEndContract(fromContractSourceDir);
+          fromContract = await readPredecessorEndContract(fromContractSourceDir, familyInstance);
         }
       }
     }
@@ -324,26 +353,16 @@ async function executeMigrationPlanCommand(
   // Phase 2 — load: build the aggregate against the now-consistent disk
   // state that phase 1 just seeded. The seed phase guarantees every
   // declared extension has its head ref pinned, so the loader's
-  // declaredButUnmigrated precheck always passes here.
-  const stack = createControlStack(config);
-  const familyInstance = config.family.create(stack);
-  let validatedAppContract: Contract;
-  try {
-    validatedAppContract = familyInstance.validateContract(toContractJson);
-  } catch (error) {
-    return notOk(
-      errorContractValidationFailed(
-        `Contract validation failed: ${error instanceof Error ? error.message : String(error)}`,
-        { where: { path: contractPathAbsolute } },
-      ),
-    );
-  }
+  // declaredButUnmigrated precheck always passes here. The app contract
+  // was already routed through `familyInstance.deserializeContract` at the
+  // read site above (see TML-2536), so it's the hydrated `Contract`
+  // here — no second validation pass needed.
   const aggregateResult = await buildContractSpaceAggregate({
     targetId: config.target.targetId,
     migrationsDir,
-    appContract: validatedAppContract,
+    appContract: toContract,
     extensionPacks: config.extensionPacks ?? [],
-    validateContract: (json: unknown) => familyInstance.validateContract(json),
+    deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
   if (!aggregateResult.ok) {
     return notOk(aggregateResult.failure);

package/src/commands/migration-show.ts

@@ -370,26 +370,30 @@ async function executeMigrationShowCommand(
     );
   }
 
+  // Construct the family instance up-front so the on-disk app contract
+  // read crosses the serializer seam (`familyInstance.deserializeContract`)
+  // at the read site. See TML-2536.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
   let appContract: Contract;
   try {
-    appContract = JSON.parse(contractJsonContent) as Contract;
+    appContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
     return notOk(
       errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        `Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
         { where: { path: contractPathAbsolute } },
       ),
     );
   }
 
-  const stack = createControlStack(config);
-  const familyInstance = config.family.create(stack);
   const aggregateResult = await buildContractSpaceAggregate({
     targetId: config.target.targetId,
     migrationsDir,
     appContract,
     extensionPacks: config.extensionPacks ?? [],
-    validateContract: (json: unknown) => familyInstance.validateContract(json),
+    deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
   if (!aggregateResult.ok) {
     return notOk(aggregateResult.failure);

package/src/commands/migration-status.ts

@@ -437,15 +437,15 @@ export async function loadAggregateStatusSpaces(args: {
   readonly migrationsDir: string;
   readonly appContractRaw: unknown;
   readonly extensionPacks: BuildAggregateInputs<string, string>['extensionPacks'];
-  readonly validateContract: BuildAggregateInputs<string, string>['validateContract'];
+  readonly deserializeContract: BuildAggregateInputs<string, string>['deserializeContract'];
   readonly markersBySpace: ReadonlyMap<string, ContractMarkerRecordLike> | null;
 }): Promise<readonly MigrationStatusSpaceEntry[]> {
   const loadInputs: BuildAggregateInputs<string, string> = {
     targetId: args.targetId,
     migrationsDir: args.migrationsDir,
-    appContract: args.validateContract(args.appContractRaw),
+    appContract: args.deserializeContract(args.appContractRaw),
     extensionPacks: args.extensionPacks,
-    validateContract: args.validateContract,
+    deserializeContract: args.deserializeContract,
   };
 
   const loaded = await buildContractSpaceAggregate(loadInputs);
@@ -774,7 +774,7 @@ async function executeMigrationStatusCommand(
   let aggregateSpaces: readonly MigrationStatusSpaceEntry[] = [];
   if (contractRawForAggregate !== null) {
     // The aggregate loader needs a typed-Contract producer. Build a
-    // real control stack so `validateContract` runs against a fully
+    // real control stack so `deserializeContract` runs against a fully
     // composed family instance — descriptors that read stack members
     // during construction (e.g. codec lookups) get a consistent view.
     const stack = createControlStack(config);
@@ -785,7 +785,7 @@ async function executeMigrationStatusCommand(
         migrationsDir,
         appContractRaw: contractRawForAggregate,
         extensionPacks: config.extensionPacks ?? [],
-        validateContract: (json: unknown) => familyInstance.validateContract(json),
+        deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
         markersBySpace: allMarkers,
       });
     } catch {

package/src/control-api/client.ts

@@ -201,7 +201,7 @@ class ControlClientImpl implements ControlClient {
     // Validate contract using family instance
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -254,7 +254,7 @@ class ControlClientImpl implements ControlClient {
     // Validate contract using family instance
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -308,7 +308,7 @@ class ControlClientImpl implements ControlClient {
     // Validate contract using family instance
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -361,7 +361,7 @@ class ControlClientImpl implements ControlClient {
 
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -392,7 +392,7 @@ class ControlClientImpl implements ControlClient {
 
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -418,18 +418,10 @@ class ControlClientImpl implements ControlClient {
     await this.connectWithProgress(options.connection, 'dbVerify', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
-    let contract: Contract;
-    try {
-      contract = familyInstance.validateContract(options.contract);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
-    }
-
     return executeDbVerify({
       driver,
       familyInstance,
-      contract,
+      contract: options.contract,
       migrationsDir: options.migrationsDir,
       targetId: this.options.target.targetId,
       extensionPacks: this.options.extensionPacks ?? [],
@@ -466,7 +458,7 @@ class ControlClientImpl implements ControlClient {
 
     let contract: Contract;
     try {
-      contract = familyInstance.validateContract(options.contract);
+      contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ContractValidationError(message, error);
@@ -641,10 +633,20 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
-      const enrichedIR = enrichContract(contractRaw as Contract, this.frameworkComponents ?? []);
+      // Blind cast: `contractRaw` is the unverified provider
+      // payload — `enrichContract` only adds capability + extension
+      // metadata onto whatever shape it receives. The structural
+      // check happens immediately afterwards via
+      // `familyInstance.deserializeContract(enrichedIR)`, which is
+      // the seam-of-record and the only thing that may surface
+      // structural errors to the caller.
+      const enrichedIR = enrichContract(
+        contractRaw as unknown as Contract,
+        this.frameworkComponents ?? [],
+      );
 
       try {
-        this.familyInstance.validateContract(enrichedIR);
+        this.familyInstance.deserializeContract(enrichedIR);
       } catch (error) {
         onProgress?.({
           action: 'emit',

package/src/control-api/operations/contract-emit.ts

@@ -232,8 +232,19 @@ export async function executeContractEmit(
         config.target.targetId,
         rawComponents,
       );
-      const enrichedIR = enrichContract(validatedContract.value as Contract, frameworkComponents);
-      familyInstance.validateContract(enrichedIR);
+      // Blind cast: `validateProviderResult` upstream has already
+      // pinned `validatedContract.value` to the provider's loose
+      // `Contract` envelope, but the local `Contract` type at this
+      // call site is the precise structural interface. Re-narrowing
+      // the envelope into the precise type is exactly what the
+      // `familyInstance.deserializeContract(enrichedIR)` call on the
+      // next line does — the cast just defers the structural check
+      // by one statement so `enrichContract` can decorate first.
+      const enrichedIR = enrichContract(
+        validatedContract.value as unknown as Contract,
+        frameworkComponents,
+      );
+      familyInstance.deserializeContract(enrichedIR);
       // Each target's descriptor ships a `contractSerializer` SPI; the
       // framework canonicalizer threads its `serializeContract` so the
       // on-disk JSON envelope is constructed by target-owned code

package/src/control-api/operations/db-apply-aggregate.ts

@@ -116,7 +116,7 @@ export async function executeAggregateApply<TFamilyId extends string, TTargetId
     migrationsDir,
     appContract: contract,
     extensionPacks,
-    validateContract: (json) => familyInstance.validateContract(json),
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
   };
   const loaded = await buildContractSpaceAggregate(loadInputs);
   if (!loaded.ok) {

package/src/control-api/operations/db-verify.ts

@@ -120,7 +120,7 @@ function buildLoadInputs<TFamilyId extends string, TTargetId extends string>(
     migrationsDir: options.migrationsDir,
     appContract: options.contract,
     extensionPacks: options.extensionPacks,
-    validateContract: (json) => options.familyInstance.validateContract(json),
+    deserializeContract: (json) => options.familyInstance.deserializeContract(json),
   };
 }
 

package/src/control-api/operations/migration-apply.ts

@@ -137,7 +137,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     migrationsDir,
     appContract: contract,
     extensionPacks,
-    validateContract: (json) => familyInstance.validateContract(json),
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
     appMigrationPackages,
   };
   const loaded = await buildContractSpaceAggregate(loadInputs);

package/src/control-api/types.ts

@@ -2,7 +2,7 @@ import type {
   ContractSourceDiagnostics,
   ContractSourceProvider,
 } from '@prisma-next/config/config-types';
-import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -118,7 +118,7 @@ export type OnControlProgress = (event: ControlProgressEvent) => void;
  * Options for the verify operation.
  */
 export interface VerifyOptions {
-  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.deserializeContract() */
   readonly contract: unknown;
   /**
    * Database connection. If provided, verify will connect before executing.
@@ -134,7 +134,7 @@ export interface VerifyOptions {
  * Options for the schemaVerify operation.
  */
 export interface SchemaVerifyOptions {
-  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.deserializeContract() */
   readonly contract: unknown;
   /**
    * Whether to use strict mode for schema verification.
@@ -156,7 +156,7 @@ export interface SchemaVerifyOptions {
  * Options for the sign operation.
  */
 export interface SignOptions {
-  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.deserializeContract() */
   readonly contract: unknown;
   /**
    * Path to the contract file (for metadata in the result).
@@ -180,7 +180,7 @@ export interface SignOptions {
  * Options for the dbInit operation.
  */
 export interface DbInitOptions {
-  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.deserializeContract() */
   readonly contract: unknown;
   /**
    * Mode for the dbInit operation.
@@ -209,7 +209,7 @@ export interface DbInitOptions {
  * Options for the dbUpdate operation.
  */
 export interface DbUpdateOptions {
-  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.deserializeContract() */
   readonly contract: unknown;
   /**
    * Mode for the dbUpdate operation.
@@ -251,7 +251,13 @@ export interface DbUpdateOptions {
  * portion of the verifier.
  */
 export interface DbVerifyOptions {
-  readonly contract: unknown;
+  /**
+   * Already-deserialized contract. Callers cross the family
+   * `deserializeContract` seam at the read site (TML-2536) and pass the
+   * hydrated value through unchanged; this op no longer re-runs the
+   * SerializerBase pipeline.
+   */
+  readonly contract: Contract;
   readonly migrationsDir: string;
   readonly strict: boolean;
   readonly skipSchema: boolean;

package/src/load-ts-contract.ts

@@ -212,7 +212,15 @@ export async function loadContractFromTs(
 
     validatePurity(contract);
 
-    return contract as Contract;
+    // Blind cast: the loaded module was authored by user code
+    // (typically via `defineContract` / a contract builder) and
+    // its runtime shape is structurally a `Contract`, but the
+    // dynamic import collapses the source typing. The contract
+    // structural validation that asserts the shape happens
+    // downstream at the `familyInstance.deserializeContract` seam
+    // (e.g. in `executeContractEmit`); this helper only checks
+    // purity here.
+    return contract as unknown as Contract;
   } catch (error) {
     try {
       if (tempFile) {

package/src/utils/contract-space-aggregate-loader.ts

@@ -120,7 +120,7 @@ export interface BuildAggregateInputs<TFamilyId extends string, TTargetId extend
   readonly migrationsDir: string;
   readonly appContract: Contract;
   readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
-  readonly validateContract: (contractJson: unknown) => Contract;
+  readonly deserializeContract: (contractJson: unknown) => Contract;
   /**
    * App-space migration packages to hydrate the app member's
    * migration graph with. Defaults to `[]` (matches the `db init` /
@@ -165,7 +165,7 @@ export async function buildContractSpaceAggregate<
     migrationsDir: inputs.migrationsDir,
     appContract: inputs.appContract,
     declaredExtensions,
-    validateContract: inputs.validateContract,
+    deserializeContract: inputs.deserializeContract,
     appMigrationPackages: inputs.appMigrationPackages ?? [],
   };