@prisma-next/cli 0.16.0-dev.2 → 0.16.0-dev.20

package/src/commands/migration-plan.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { loadConfig } from '@prisma-next/config-loader';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
@@ -9,15 +9,14 @@ import {
   type OperationPreview,
   type SchemaOwnership,
 } from '@prisma-next/framework-components/control';
-import { canonicalizeJson } from '@prisma-next/framework-components/utils';
+import {
+  snapshotsImportPathFrom,
+  writeContractSnapshot,
+} from '@prisma-next/migration-tools/contract-snapshot-store';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import { deriveProvidedInvariants } from '@prisma-next/migration-tools/invariants';
-import {
-  copyFilesWithRename,
-  formatMigrationDirName,
-  writeMigrationPackage,
-} from '@prisma-next/migration-tools/io';
+import { formatMigrationDirName, writeMigrationPackage } from '@prisma-next/migration-tools/io';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
@@ -62,27 +61,6 @@ interface MigrationPlanOptions extends CommonCommandOptions {
   readonly to?: string;
 }
 
-async function writeSnapshotContractArtifacts(
-  packageDir: string,
-  contractJson: unknown,
-  contractDts: string,
-  artifactBasename: 'start-contract' | 'end-contract',
-): Promise<void> {
-  await mkdir(packageDir, { recursive: true });
-  const jsonContent = `${canonicalizeJson(contractJson)}\n`;
-  const dtsContent = contractDts.endsWith('\n') ? contractDts : `${contractDts}\n`;
-  await writeFile(join(packageDir, `${artifactBasename}.json`), jsonContent);
-  await writeFile(join(packageDir, `${artifactBasename}.d.ts`), dtsContent);
-}
-
-async function writeSnapshotStartContract(
-  packageDir: string,
-  contractJson: unknown,
-  contractDts: string,
-): Promise<void> {
-  await writeSnapshotContractArtifacts(packageDir, contractJson, contractDts, 'start-contract');
-}
-
 type PlannerSuccess = {
   readonly plannedOps: readonly MigrationPlanOperation[];
   readonly migrationTsContent: string;
@@ -99,6 +77,7 @@ async function runPlannerLeg(
   fromContract: Contract | null,
   spaceId: string,
   ownership: SchemaOwnership,
+  snapshotsImportPath: string,
 ): Promise<Result<PlannerSuccess, CliStructuredError>> {
   const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
   const plannerResult = planner.plan({
@@ -114,6 +93,7 @@ async function runPlannerLeg(
     // space in the aggregate, so it stays a genuine drop; a table another
     // space owns is never dropped.
     ownership,
+    snapshotsImportPath,
   });
   if (plannerResult.kind === 'failure') {
     return notOk(
@@ -309,14 +289,18 @@ async function executeMigrationPlanCommand(
   let toStorageHash: string = rawStorageHash;
 
   // When `--to <ref>` resolves a non-default destination, these carry its raw
-  // artifacts so the planned package's `end-contract.*` is written from the
-  // resolved target rather than copied from the emitted `contract.json`.
+  // artifacts so the planned package's destination snapshot store entry is
+  // written from the resolved target rather than copied from the emitted
+  // `contract.json`.
   let toArtifacts: { contractJson: unknown; contractDts: string } | null = null;
 
   let fromContract: Contract | null = null;
   let fromHash: string | null = null;
-  let fromContractSourceDir: string | null = null;
-  let snapshotStartContract: { contractJson: unknown; contractDts: string } | null = null;
+  let snapshotStartContract: {
+    readonly fromHash: string;
+    readonly contractJson: unknown;
+    readonly contractDts: string;
+  } | null = null;
   let isAutoBaseline = false;
 
   const tolerantAggregateResult = await loadContractSpaceAggregateForCli({
@@ -346,12 +330,12 @@ async function executeMigrationPlanCommand(
     case 'graph-node':
       fromHash = resolutionResult.value.fromHash;
       fromContract = resolutionResult.value.fromContract;
-      fromContractSourceDir = resolutionResult.value.sourceDir;
       break;
-    case 'snapshot':
+    case 'ref':
       fromHash = resolutionResult.value.fromHash;
       fromContract = resolutionResult.value.fromContract;
       snapshotStartContract = {
+        fromHash: resolutionResult.value.fromHash,
         contractJson: resolutionResult.value.contractJson,
         contractDts: resolutionResult.value.contractDts,
       };
@@ -360,6 +344,7 @@ async function executeMigrationPlanCommand(
       fromHash = resolutionResult.value.fromHash;
       fromContract = resolutionResult.value.fromContract;
       snapshotStartContract = {
+        fromHash: resolutionResult.value.fromHash,
         contractJson: resolutionResult.value.contractJson,
         contractDts: resolutionResult.value.contractDts,
       };
@@ -369,7 +354,7 @@ async function executeMigrationPlanCommand(
 
   // `--to <ref>` swaps the planner destination to an arbitrary resolved
   // contract (e.g. an ancestor / rollback target). The from-side resolution
-  // above is untouched; only the destination + its emitted `end-contract.*`
+  // above is untouched; only the destination + its snapshot store entry
   // change.
   if (options.to !== undefined) {
     const toResolution = await resolveToForPlan(options.to, {
@@ -386,11 +371,11 @@ async function executeMigrationPlanCommand(
     };
   }
 
-  // Phase 1 — seed: unconditionally re-emit per-space pinned artefacts
+  // Phase 1 — seed: unconditionally re-emit per-space pinned artifacts
   // (contract.json / contract.d.ts / refs/head.json) and materialise any
   // descriptor-shipped migration packages not yet on disk. Runs before
   // the no-op check so that an extension bump alone (with no structural
-  // app-space change) still re-pins extension artefacts on disk.
+  // app-space change) still re-pins extension artifacts on disk.
   const canonicalExtensionInputs = toExtensionInputs(config.extensionPacks ?? []);
   const seedResult = await runContractSpaceSeedPhase({
     migrationsDir,
@@ -463,24 +448,26 @@ async function executeMigrationPlanCommand(
     [config.target, config.adapter, ...(config.extensionPacks ?? [])],
   );
 
-  // Write the planned package's destination `end-contract.*`. With `--to`, the
-  // resolved target's raw artifacts are written; otherwise the emitted
-  // `contract.json` / `contract.d.ts` are copied verbatim (today's behaviour).
-  async function writeDestinationEndContract(packageDir: string): Promise<void> {
+  // Write the planned package's destination contract into the snapshot store.
+  // With `--to`, the resolved target's raw artifacts are written; otherwise
+  // the emitted `contract.json` / `contract.d.ts` are read from disk.
+  async function writeDestinationSnapshot(destHash: string): Promise<void> {
     if (toArtifacts !== null) {
-      await writeSnapshotContractArtifacts(
-        packageDir,
-        toArtifacts.contractJson,
-        toArtifacts.contractDts,
-        'end-contract',
-      );
+      await writeContractSnapshot(migrationsDir, destHash, {
+        contractJson: toArtifacts.contractJson,
+        contractDts: toArtifacts.contractDts,
+      });
       return;
     }
     const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
-    await copyFilesWithRename(packageDir, [
-      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
-      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
+    const [contractJsonRaw, contractDts] = await Promise.all([
+      readFile(destinationArtifacts.jsonPath, 'utf-8'),
+      readFile(destinationArtifacts.dtsPath, 'utf-8'),
     ]);
+    await writeContractSnapshot(migrationsDir, destHash, {
+      contractJson: JSON.parse(contractJsonRaw) as unknown,
+      contractDts,
+    });
   }
 
   try {
@@ -507,6 +494,7 @@ async function executeMigrationPlanCommand(
         null,
         aggregate.app.spaceId,
         aggregate,
+        snapshotsImportPathFrom(baselinePackageDir, migrationsDir),
       );
       if (!baselineLeg.ok) {
         return notOk(baselineLeg.failure);
@@ -519,12 +507,10 @@ async function executeMigrationPlanCommand(
         baselineTimestamp,
         baselineLeg.value,
       );
-      await writeSnapshotContractArtifacts(
-        baselinePackageDir,
-        snapshotStartContract.contractJson,
-        snapshotStartContract.contractDts,
-        'end-contract',
-      );
+      await writeContractSnapshot(migrationsDir, fromHash, {
+        contractJson: snapshotStartContract.contractJson,
+        contractDts: snapshotStartContract.contractDts,
+      });
 
       if (fromHash === toStorageHash) {
         const baselineOps = baselineLeg.value.hasPlaceholders ? [] : baselineLeg.value.plannedOps;
@@ -577,6 +563,7 @@ async function executeMigrationPlanCommand(
         fromContract,
         aggregate.app.spaceId,
         aggregate,
+        snapshotsImportPathFrom(deltaPackageDir, migrationsDir),
       );
       if (!deltaLeg.ok) {
         return notOk(deltaLeg.failure);
@@ -589,12 +576,11 @@ async function executeMigrationPlanCommand(
         deltaTimestamp,
         deltaLeg.value,
       );
-      await writeDestinationEndContract(deltaPackageDir);
-      await writeSnapshotStartContract(
-        deltaPackageDir,
-        snapshotStartContract.contractJson,
-        snapshotStartContract.contractDts,
-      );
+      await writeDestinationSnapshot(toStorageHash);
+      await writeContractSnapshot(migrationsDir, fromHash, {
+        contractJson: snapshotStartContract.contractJson,
+        contractDts: snapshotStartContract.contractDts,
+      });
 
       const deltaOps = deltaLeg.value.hasPlaceholders ? [] : deltaLeg.value.plannedOps;
       if (deltaLeg.value.hasPlaceholders) {
@@ -651,6 +637,7 @@ async function executeMigrationPlanCommand(
       fromContract,
       aggregate.app.spaceId,
       aggregate,
+      snapshotsImportPathFrom(packageDir, migrationsDir),
     );
     if (!deltaLeg.ok) {
       return notOk(deltaLeg.failure);
@@ -663,21 +650,12 @@ async function executeMigrationPlanCommand(
       timestamp,
       deltaLeg.value,
     );
-    await writeDestinationEndContract(packageDir);
-    if (fromContractSourceDir !== null) {
-      const sourceArtifacts = getEmittedArtifactPaths(
-        join(fromContractSourceDir, 'end-contract.json'),
-      );
-      await copyFilesWithRename(packageDir, [
-        { sourcePath: sourceArtifacts.jsonPath, destName: 'start-contract.json' },
-        { sourcePath: sourceArtifacts.dtsPath, destName: 'start-contract.d.ts' },
-      ]);
-    } else if (snapshotStartContract !== null) {
-      await writeSnapshotStartContract(
-        packageDir,
-        snapshotStartContract.contractJson,
-        snapshotStartContract.contractDts,
-      );
+    await writeDestinationSnapshot(toStorageHash);
+    if (snapshotStartContract !== null) {
+      await writeContractSnapshot(migrationsDir, snapshotStartContract.fromHash, {
+        contractJson: snapshotStartContract.contractJson,
+        contractDts: snapshotStartContract.contractDts,
+      });
     }
 
     if (deltaLeg.value.hasPlaceholders) {
@@ -953,10 +931,9 @@ export type PrefixResolutionFailure =
  *
  * Note: matches `metadata.to` (the contract hash this migration produces),
  * not `metadata.migrationHash` (the package's content-addressed identity).
- * Tries exact match first, then prefix match (auto-prepending `sha256:` when
- * the needle omits the scheme). Returns the matched package on success, or a
- * discriminated failure indicating whether the prefix was ambiguous or simply
- * not found.
+ * Tries exact match first, then prefix match. Returns the matched package on
+ * success, or a discriminated failure indicating whether the prefix was
+ * ambiguous or simply not found.
  *
  * @internal Exported for testing only.
  */
@@ -967,8 +944,7 @@ export function resolveBundleByPrefix<T extends { metadata: { to: string } }>(
   const exact = bundles.find((p) => p.metadata.to === needle);
   if (exact) return ok(exact);
 
-  const prefixWithScheme = needle.startsWith('sha256:') ? needle : `sha256:${needle}`;
-  const candidates = bundles.filter((p) => p.metadata.to.startsWith(prefixWithScheme));
+  const candidates = bundles.filter((p) => p.metadata.to.startsWith(needle));
 
   if (candidates.length === 1) return ok(candidates[0]!);
   if (candidates.length > 1) return notOk({ reason: 'ambiguous', count: candidates.length });

package/src/commands/migration-show.ts

@@ -228,7 +228,7 @@ export function createMigrationShowCommand(): Command {
   );
   setCommandExamples(command, [
     'prisma-next migration show 20260101_100000_add_user',
-    'prisma-next migration show sha256:a1b2c3',
+    'prisma-next migration show a1b2c3',
     'prisma-next migration show 20260101_100000_add_user --json',
   ]);
   setCommandSeeAlso(command, [

package/src/commands/migration-status.ts

@@ -111,8 +111,7 @@ interface MigrationStatusCommandResult {
 }
 
 function shortDisplayHash(hash: string): string {
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, 12);
+  return hash.slice(0, 12);
 }
 
 function resolveTarget(contractHash: string, activeRefHash: string | undefined): string {
@@ -660,10 +659,10 @@ export function createMigrationStatusCommand(): Command {
   setCommandExamples(command, [
     'prisma-next migration status --db $DATABASE_URL',
     'prisma-next migration status --to production --db $DATABASE_URL',
-    'prisma-next migration status --from sha256:abc --to production',
-    'prisma-next migration status --from sha256:abc --to production --json',
-    'prisma-next migration status --ascii --from sha256:abc --to production',
-    'prisma-next migration status --legend --from sha256:abc --to production',
+    'prisma-next migration status --from abc123 --to production',
+    'prisma-next migration status --from abc123 --to production --json',
+    'prisma-next migration status --ascii --from abc123 --to production',
+    'prisma-next migration status --legend --from abc123 --to production',
   ]);
   setCommandSeeAlso(command, [
     { verb: 'migration log', oneLiner: 'Show executed migration history' },

package/src/commands/ref.ts

@@ -1,16 +1,19 @@
-import { readFile } from 'node:fs/promises';
 import { loadConfig } from '@prisma-next/config-loader';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import {
+  contractSnapshotDir,
+  readContractSnapshotJson,
+} from '@prisma-next/migration-tools/contract-snapshot-store';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { findLatestMigration, isGraphNode } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
-  deleteRefPaired,
+  deleteRef,
   readRefs,
   validateRefName,
   validateRefValue,
-  writeRefPaired,
+  writeRef,
 } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -34,7 +37,6 @@ import {
 import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatCommandHelp } from '../utils/formatters/help';
 import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
-import { readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI } from '../utils/terminal-ui';
 
@@ -114,26 +116,29 @@ export async function executeRefSetCommand(
       return notOk(errorRefSetBundleNotFound(resolvedHash));
     }
 
-    const contractJsonPath = join(matchingBundle.dirPath, 'end-contract.json');
-    let contractJson: Record<string, unknown>;
+    const contractJsonPath = join(
+      contractSnapshotDir(migrationsDir, resolvedHash),
+      'contract.json',
+    );
     try {
-      const raw = await readFile(contractJsonPath, 'utf-8');
-      contractJson = JSON.parse(raw) as Record<string, unknown>;
+      await readContractSnapshotJson(migrationsDir, resolvedHash);
     } catch (readError) {
-      if (readError instanceof Error && (readError as NodeJS.ErrnoException).code === 'ENOENT') {
+      if (
+        MigrationToolsError.is(readError) &&
+        readError.code === 'MIGRATION.CONTRACT_SNAPSHOT_MISSING'
+      ) {
         return notOk(
           errorFileNotFound(contractJsonPath, {
-            why: `Migration bundle for hash ${resolvedHash} is missing its end-contract snapshot at ${contractJsonPath}`,
-            fix: 'Run `pnpm fixtures:check`, or re-emit the migration so its end-contract.json is restored.',
+            why: `Migration bundle for hash ${resolvedHash} is missing its contract snapshot at ${contractJsonPath}`,
+            fix: 'Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.',
           }),
         );
       }
       throw readError;
     }
 
-    const contractIR = await readContractIR(contractJson, contractJsonPath);
     const entry: RefEntry = { hash: resolvedHash, invariants: [] };
-    await writeRefPaired(refsDir, name, entry, contractIR);
+    await writeRef(refsDir, name, entry);
     return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -148,7 +153,7 @@ export async function executeRefDeleteCommand(
   try {
     const config = await loadConfig(options.config);
     const { refsDir } = resolveMigrationPaths(options.config, config);
-    await deleteRefPaired(refsDir, name);
+    await deleteRef(refsDir, name);
     return ok({ ok: true as const, ref: name, deleted: true as const });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);

package/src/control-api/client.ts

@@ -609,7 +609,6 @@ class ControlClientImpl implements ControlClient {
       const sourceContext = {
         composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
         composedExtensionContracts: stack.extensionContracts,
-        scalarTypeDescriptors: stack.scalarTypeDescriptors,
         authoringContributions: stack.authoringContributions,
         codecLookup: stack.codecLookup,
         controlMutationDefaults: stack.controlMutationDefaults,

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

@@ -197,7 +197,6 @@ export async function executeContractEmit(
     const sourceContext = {
       composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
       composedExtensionContracts: stack.extensionContracts,
-      scalarTypeDescriptors: stack.scalarTypeDescriptors,
       authoringContributions: stack.authoringContributions,
       codecLookup: stack.codecLookup,
       controlMutationDefaults: stack.controlMutationDefaults,

package/src/control-api/operations/format.ts

@@ -1,8 +1,9 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { EOL } from 'node:os';
 import { loadConfig } from '@prisma-next/config-loader';
-import { type FormatOptions, format, PslFormatError } from '@prisma-next/psl-parser/format';
+import { type FormatOptions, format } from '@prisma-next/psl-parser/format';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { isStructuredError } from '@prisma-next/utils/structured-error';
 import { CliStructuredError, errorRuntime, errorUnexpected } from '../../utils/cli-errors';
 
 export interface FormatOperationOptions {
@@ -71,12 +72,12 @@ export async function executeFormat(
   try {
     formatted = format(contents, formatOptions);
   } catch (error) {
-    if (error instanceof PslFormatError) {
+    if (isStructuredError(error) && error.code === 'PSL.PARSE_FAILED') {
       return notOk(
         errorRuntime('Cannot format PSL with parse errors', {
           why: error.message,
           fix: 'Fix the parse errors in your schema and try again.',
-          meta: { diagnostics: error.diagnostics },
+          meta: { diagnostics: error.meta?.['diagnostics'] },
         }),
       );
     }

package/src/utils/cli-errors.ts

@@ -215,22 +215,30 @@ export function errorPlanForgotTheFlag(
   });
 }
 
+/**
+ * `viaRef: true` (the default) mirrors migration-tools' `errorRefNotResolvable`:
+ * a ref name with no pointer file, where the fallback hash isn't a graph
+ * node either — there's nothing to materialize a contract from.
+ * `viaRef: false` is a distinct, ref-independent case: an explicit `--from
+ * <hash>` that doesn't name a ref, on an empty migration graph, so there is
+ * no graph node and no ref to resolve a contract through.
+ */
 export function errorSnapshotMissing(
   identifier: string,
   options?: { readonly viaRef?: boolean },
 ): CliStructuredError {
   const viaRef = options?.viaRef !== false;
   const fix = viaRef
-    ? `Run "prisma-next db update --advance-ref ${identifier}" to repopulate the snapshot, or "prisma-next ref delete ${identifier}" to clear the orphan pointer.`
-    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;
+    ? `Create the ref with "prisma-next ref set ${identifier} <hash>" (or advance it via "prisma-next db update --advance-ref ${identifier}"), or pass a hash that is a node in the migration graph.`
+    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name (its contract resolves through the snapshot store), or run db update first.`;
   return errorRuntime(
     viaRef
-      ? `Ref "${identifier}" has no paired contract snapshot`
+      ? `Ref "${identifier}" is not resolvable`
       : `No contract source for from-hash "${identifier}"`,
     {
       why: viaRef
-        ? `Ref "${identifier}" exists but its paired snapshot files are missing.`
-        : `Hash "${identifier}" is not a graph node and no paired ref snapshot supplies a contract.`,
+        ? `Ref "${identifier}" has no pointer file, and the hash being resolved is not a node in the migration graph either.`
+        : `Hash "${identifier}" is not a node in the migration graph (the graph is empty), and it does not name a ref either.`,
       fix,
       meta: {
         code: 'MIGRATION.SNAPSHOT_MISSING',

package/src/utils/contract-at-errors.ts

@@ -1,6 +1,5 @@
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { notOk, type Result } from '@prisma-next/utils/result';
-import { join } from 'pathe';
 import {
   CliStructuredError,
   errorContractValidationFailed,
@@ -16,7 +15,7 @@ export function mapContractAtError(
 ): Result<never, CliStructuredError> {
   if (MigrationToolsError.is(error)) {
     switch (error.code) {
-      case 'MIGRATION.SNAPSHOT_MISSING': {
+      case 'MIGRATION.REF_NOT_RESOLVABLE': {
         const refName =
           typeof error.details?.['refName'] === 'string'
             ? error.details['refName']
@@ -27,18 +26,13 @@ export function mapContractAtError(
       }
       case 'MIGRATION.CONTRACT_DESERIALIZATION_FAILED': {
         const filePath =
-          typeof error.details?.['filePath'] === 'string'
-            ? error.details['filePath']
-            : 'ref-snapshot';
+          typeof error.details?.['filePath'] === 'string' ? error.details['filePath'] : 'unknown';
         const message =
           typeof error.details?.['message'] === 'string' ? error.details['message'] : error.message;
-        const isRefSnapshot = filePath.endsWith('.contract.json');
         return notOk(
           errorContractValidationFailed(
-            isRefSnapshot
-              ? `Ref snapshot contract failed to deserialize: ${message}`
-              : `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
-            { where: { path: isRefSnapshot ? 'ref-snapshot' : filePath } },
+            `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
+            { where: { path: filePath } },
           ),
         );
       }
@@ -66,22 +60,19 @@ export function mapContractAtError(
             fix: error.fix,
           }),
         );
-      case 'MIGRATION.FILE_MISSING': {
-        const file =
-          typeof error.details?.['file'] === 'string' ? error.details['file'] : 'end-contract.json';
-        const dir = typeof error.details?.['dir'] === 'string' ? error.details['dir'] : '';
-        const jsonPath = dir ? join(dir, 'end-contract.json') : file;
+      case 'MIGRATION.CONTRACT_SNAPSHOT_MISSING': {
+        const expectedPath =
+          typeof error.details?.['expectedPath'] === 'string'
+            ? error.details['expectedPath']
+            : 'migrations/snapshots/';
         const role = options?.artifactRole ?? 'from';
         return notOk(
-          errorFileNotFound(jsonPath, {
+          errorFileNotFound(expectedPath, {
             why:
               role === 'to'
-                ? `Target migration is missing its destination contract snapshot at ${jsonPath}`
-                : `Predecessor migration is missing its destination contract snapshot at ${jsonPath}`,
-            fix:
-              role === 'to'
-                ? 'Re-emit the target migration so its sibling `end-contract.json` / `end-contract.d.ts` are restored, then re-run this command.'
-                : 'Re-emit the predecessor migration (`prisma-next migration plan` from its source) so its sibling `end-contract.json` is restored, then re-run this command.',
+                ? `Target migration is missing its contract snapshot at ${expectedPath}`
+                : `Predecessor migration is missing its contract snapshot at ${expectedPath}`,
+            fix: 'Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.',
           }),
         );
       }

package/src/utils/contract-space-seed-phase.ts

@@ -2,7 +2,7 @@ import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migr
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import type { MigrationOps } from '@prisma-next/migration-tools/package';
 import {
-  emitContractSpaceArtefacts,
+  emitContractSpaceArtifacts,
   planAllSpaces,
   readContractSpaceHeadRef,
   type SpacePlanOutput,
@@ -53,7 +53,7 @@ export interface ContractSpaceSeedPhaseInputs {
  * - `action: 'unchanged'` — the on-disk head already matched the
  *   descriptor and no new migration packages needed to be written.
  *
- * Either way, the artefacts (`contract.json`, `contract.d.ts`,
+ * Either way, the artifacts (`contract.json`, `contract.d.ts`,
  * `refs/head.json`) are re-emitted: the framework owns those files and
  * makes the re-emit observably idempotent at the byte level.
  */
@@ -75,9 +75,11 @@ export interface ContractSpaceSeedPhaseResult {
  * For every extension that exposes a `contractSpace`:
  *
  * 1. Read the on-disk head ref (returns `null` on first emit).
- * 2. Re-emit `contract.json` / `contract.d.ts` / `refs/head.json`
- *    unconditionally via {@link emitContractSpaceArtefacts}. The
- *    framework owns these files; re-emit is the contract.
+ * 2. Write the head contract into the migrations-root snapshot store
+ *    (write-if-absent, keyed by hash) and unconditionally re-emit
+ *    `refs/head.json`, via {@link emitContractSpaceArtifacts}. The
+ *    framework owns `refs/head.json`; re-emit is the contract for that
+ *    file. The snapshot itself is only written once per distinct hash.
  * 3. Materialise any descriptor-shipped migration packages not yet on
  *    disk via {@link materialiseExtensionMigrationPackageIfMissing}.
  *    Existing packages are left untouched (by-existence skip).
@@ -144,7 +146,7 @@ export async function runContractSpaceSeedPhase(
     const onDiskHeadRef = await readContractSpaceHeadRef(inputs.migrationsDir, space.spaceId);
     const priorHash = onDiskHeadRef?.hash ?? null;
 
-    await emitContractSpaceArtefacts(inputs.migrationsDir, space.spaceId, {
+    await emitContractSpaceArtifacts(inputs.migrationsDir, space.spaceId, {
       contract: descriptor.contractJson,
       contractDts: buildPlaceholderContractDts(space.spaceId),
       headRef: { hash: descriptor.headRef.hash, invariants: descriptor.headRef.invariants },

package/src/utils/formatters/migration-graph-labels.ts

@@ -104,8 +104,7 @@ function abbreviateHash(hash: string, hashLength: number, emptySource: string):
   if (hash === EMPTY_CONTRACT_HASH) {
     return emptySource;
   }
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, hashLength);
+  return hash.slice(0, hashLength);
 }
 
 interface ContractOverlayNames {

package/src/utils/formatters/migration-list-data-column.ts

@@ -18,8 +18,7 @@ export function migrationListEmptySource(glyphMode: GlyphMode): string {
 }
 
 export function abbreviateContractHash(hash: string): string {
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, MIGRATION_LIST_HASH_WIDTH);
+  return hash.slice(0, MIGRATION_LIST_HASH_WIDTH);
 }
 
 export function padFromHashColumn(text: string, width: number): string {