@prisma-next/cli 0.16.0-dev.3 → 0.16.0-dev.30

package/src/commands/migration-check.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { loadConfig } from '@prisma-next/config-loader';
 import { createControlStack } from '@prisma-next/framework-components/control';
@@ -7,6 +7,12 @@ import type {
   IntegrityViolation,
 } from '@prisma-next/migration-tools/aggregate';
 import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
+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 type { MigrationGraph } from '@prisma-next/migration-tools/graph';
 import { verifyMigrationHash } from '@prisma-next/migration-tools/hash';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
@@ -18,7 +24,6 @@ import type { Refs } from '@prisma-next/migration-tools/refs';
 import {
   isValidSpaceId,
   listContractSpaceDirectories,
-  RESERVED_SPACE_SUBDIR_NAMES,
   spaceMigrationDirectory,
   spaceRefsDirectory,
 } from '@prisma-next/migration-tools/spaces';
@@ -92,32 +97,57 @@ function checkFileExists(
   return null;
 }
 
-function checkSnapshotConsistency(
+/**
+ * Snapshot-store consistency check for one migration package (D6.5):
+ * absent store entry is not an issue (runner independence, ADR 199 — a
+ * package dir with only `migration.json` + `ops.json` is legitimate); a
+ * present entry whose inner `storage.storageHash` disagrees with
+ * `pkg.metadata.to` is `MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH`; an unparseable store
+ * entry (or a malformed `to`) is `MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE`.
+ */
+async function checkSnapshotConsistency(
   spaceId: string,
   pkg: OnDiskMigrationPackage,
-): CheckFailure | null {
-  const endContractPath = join(pkg.dirPath, 'end-contract.json');
-  if (!existsSync(endContractPath)) return null;
+  migrationsDir: string,
+): Promise<CheckFailure | null> {
+  let snapshotDir: string;
   try {
-    const raw = JSON.parse(readFileSync(endContractPath, 'utf-8')) as Record<string, unknown>;
-    const storage = raw['storage'] as Record<string, unknown> | undefined;
-    const snapshotHash = storage?.['storageHash'];
-    if (typeof snapshotHash === 'string' && snapshotHash !== pkg.metadata.to) {
-      return {
-        space: spaceId,
-        code: 'MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH',
-        where: migrationPathRelative(pkg.dirPath),
-        why: `Migration "${pkg.dirName}" declares to=${pkg.metadata.to} but end-contract.json has storageHash=${snapshotHash}`,
-        fix: 'Re-emit the migration package so migration.json and end-contract.json agree.',
-      };
-    }
+    snapshotDir = contractSnapshotDir(migrationsDir, pkg.metadata.to);
   } catch {
     return {
       space: spaceId,
       code: 'MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE',
       where: migrationPathRelative(pkg.dirPath),
-      why: `Migration "${pkg.dirName}" has an unparseable end-contract.json.`,
-      fix: 'Re-emit the migration package to repair the snapshot file.',
+      why: `Migration "${pkg.dirName}" declares to="${pkg.metadata.to}", which is not a well-formed contract snapshot hash.`,
+      fix: 'Re-emit the migration package so migration.json declares a valid 64-hex to-hash.',
+    };
+  }
+
+  let raw: unknown;
+  try {
+    raw = await readContractSnapshotJson(migrationsDir, pkg.metadata.to);
+  } catch (error) {
+    if (MigrationToolsError.is(error) && error.code === 'MIGRATION.CONTRACT_SNAPSHOT_MISSING') {
+      return null;
+    }
+    return {
+      space: spaceId,
+      code: 'MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE',
+      where: migrationPathRelative(pkg.dirPath),
+      why: `Migration "${pkg.dirName}" has an unparseable contract snapshot at ${snapshotDir}/contract.json.`,
+      fix: 'Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.',
+    };
+  }
+  const record = raw !== null && typeof raw === 'object' ? (raw as Record<string, unknown>) : {};
+  const storage = record['storage'] as Record<string, unknown> | undefined;
+  const snapshotHash = storage?.['storageHash'];
+  if (typeof snapshotHash === 'string' && snapshotHash !== pkg.metadata.to) {
+    return {
+      space: spaceId,
+      code: 'MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH',
+      where: migrationPathRelative(pkg.dirPath),
+      why: `Migration "${pkg.dirName}" declares to=${pkg.metadata.to} but its contract snapshot has storageHash=${snapshotHash}`,
+      fix: 'Re-emit the migration package so migration.json and its contract snapshot agree.',
     };
   }
   return null;
@@ -137,6 +167,8 @@ export interface CheckSpace {
   readonly graph: MigrationGraph;
   readonly migrationsDir: string;
   readonly refsDir: string;
+  /** Migrations root the contract-snapshot store lives under — shared by every space. */
+  readonly projectMigrationsDir: string;
 }
 
 /**
@@ -152,9 +184,7 @@ export async function enumerateCheckSpaces(
   projectMigrationsDir: string,
 ): Promise<readonly CheckSpace[]> {
   const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
-  const onDiskSpaceIds = new Set(
-    candidateDirs.filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name)).filter(isValidSpaceId),
-  );
+  const onDiskSpaceIds = new Set(candidateDirs.filter(isValidSpaceId));
   const spaces: CheckSpace[] = [];
   for (const space of aggregate.spaces()) {
     const spaceId = space.spaceId;
@@ -168,6 +198,7 @@ export async function enumerateCheckSpaces(
       graph: space.graph(),
       migrationsDir,
       refsDir: spaceRefsDirectory(migrationsDir),
+      projectMigrationsDir,
     });
   }
   return spaces;
@@ -208,7 +239,7 @@ function checkReachability(space: CheckSpace): readonly CheckFailure[] {
     const isReachable =
       pkg.metadata.from === null ||
       allToHashes.has(pkg.metadata.from) ||
-      pkg.metadata.from === 'sha256:empty';
+      pkg.metadata.from === EMPTY_CONTRACT_HASH;
     if (!isReachable) {
       failures.push({
         space: space.spaceId,
@@ -238,12 +269,15 @@ function checkDanglingRefs(space: CheckSpace): readonly CheckFailure[] {
   return failures;
 }
 
-function checkSpace(space: CheckSpace): readonly CheckFailure[] {
+async function checkSpace(space: CheckSpace): Promise<readonly CheckFailure[]> {
+  const snapshotFailures = await Promise.all(
+    space.packages.map((pkg) =>
+      checkSnapshotConsistency(space.spaceId, pkg, space.projectMigrationsDir),
+    ),
+  );
   return [
     ...checkManifestFilesPresent(space),
-    ...space.packages
-      .map((pkg) => checkSnapshotConsistency(space.spaceId, pkg))
-      .filter((f): f is CheckFailure => f !== null),
+    ...snapshotFailures.filter((f): f is CheckFailure => f !== null),
     ...checkReachability(space),
     ...checkDanglingRefs(space),
   ];
@@ -272,9 +306,9 @@ export interface RunMigrationCheckInputs {
  * Aggregate-integrity violations (which already span every space) are folded
  * in by the caller, not here.
  */
-export function runMigrationCheck(
+export async function runMigrationCheck(
   inputs: RunMigrationCheckInputs,
-): Result<MigrationCheckResult, CliStructuredError> {
+): Promise<Result<MigrationCheckResult, CliStructuredError>> {
   const { spaces, spaceFilter } = inputs;
 
   if (spaceFilter !== undefined && !isValidSpaceId(spaceFilter)) {
@@ -287,7 +321,7 @@ export function runMigrationCheck(
   const scopedSpaces =
     spaceFilter !== undefined ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
 
-  const failures = scopedSpaces.flatMap(checkSpace);
+  const failures = (await Promise.all(scopedSpaces.map(checkSpace))).flat();
   if (failures.length === 0) {
     return ok({ ok: true, failures: [], summary: 'All checks passed' });
   }
@@ -301,7 +335,7 @@ async function loadAggregateIntegrityViolations(
   try {
     const contractJsonContent = await readFile(resolveContractPath(config), 'utf-8');
     const familyInstance = config.family.create(createControlStack(config));
-    const declaredExtensions = toDeclaredExtensionsFromRaw(config.extensionPacks ?? []);
+    const declaredExtensions = toDeclaredExtensionsFromRaw(config.extensions ?? []);
 
     const parsedAppContract: unknown = JSON.parse(contractJsonContent);
     const aggregate = await loadContractSpaceAggregate({
@@ -365,7 +399,7 @@ async function executeMigrationCheckCommand(
     });
   }
 
-  const checkResult = runMigrationCheck({
+  const checkResult = await runMigrationCheck({
     spaces,
     ...(options.space !== undefined ? { spaceFilter: options.space } : {}),
   });
@@ -558,7 +592,11 @@ async function checkSingleTarget(
     });
   }
 
-  const snapshotFailure = checkSnapshotConsistency(matchedSpace.spaceId, matchedPkg);
+  const snapshotFailure = await checkSnapshotConsistency(
+    matchedSpace.spaceId,
+    matchedPkg,
+    matchedSpace.projectMigrationsDir,
+  );
   if (snapshotFailure) failures.push(snapshotFailure);
 
   const resolvedSpaceId = matchedSpace.spaceId !== 'app' ? matchedSpace.spaceId : undefined;

package/src/commands/migration-list.ts

@@ -9,7 +9,6 @@ import {
   APP_SPACE_ID,
   isValidSpaceId,
   listContractSpaceDirectories,
-  RESERVED_SPACE_SUBDIR_NAMES,
 } from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
@@ -81,10 +80,7 @@ export function listRefsByContractHash(
 
 async function orderedOnDiskSpaceIds(projectMigrationsDir: string): Promise<readonly string[]> {
   const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
-  return candidateDirs
-    .filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name))
-    .filter(isValidSpaceId)
-    .sort(compareSpaceIds);
+  return candidateDirs.filter(isValidSpaceId).sort(compareSpaceIds);
 }
 
 /**

package/src/commands/migration-log.ts

@@ -84,7 +84,7 @@ export async function executeMigrationLogCommand(
     target: config.target,
     adapter: config.adapter,
     ...ifDefined('driver', config.driver),
-    extensionPacks: config.extensionPacks ?? [],
+    extensions: config.extensions ?? [],
   });
 
   try {

package/src/commands/migration-new.ts

@@ -14,12 +14,13 @@ 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';
 import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
-import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import {
-  copyFilesWithRename,
-  formatMigrationDirName,
-  writeMigrationPackage,
-} from '@prisma-next/migration-tools/io';
+  contractSnapshotDir,
+  snapshotsImportPathFrom,
+  writeContractSnapshot,
+} from '@prisma-next/migration-tools/contract-snapshot-store';
+import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
+import { formatMigrationDirName, writeMigrationPackage } from '@prisma-next/migration-tools/io';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import { findLatestMigration } from '@prisma-next/migration-tools/migration-graph';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
@@ -28,7 +29,6 @@ import { Command } from 'commander';
 import { join, relative } from 'pathe';
 import {
   CliStructuredError,
-  errorFileNotFound,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -133,7 +133,6 @@ async function executeMigrationNewCommand(
   const graph = aggregate.app.graph();
 
   let fromHash: string | null = null;
-  let fromContractSourceDir: string | null = null;
 
   if (packages.length > 0) {
     if (options.from) {
@@ -147,17 +146,10 @@ async function executeMigrationNewCommand(
         );
       }
       fromHash = match.metadata.to;
-      fromContractSourceDir = match.dirPath;
     } else {
       const latestMigration = findLatestMigration(graph);
       if (latestMigration) {
         fromHash = latestMigration.to;
-        const leafPkg = packages.find(
-          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
-        );
-        if (leafPkg) {
-          fromContractSourceDir = leafPkg.dirPath;
-        }
       }
     }
   }
@@ -204,44 +196,28 @@ async function executeMigrationNewCommand(
     assertFrameworkComponentsCompatible(config.family.familyId, config.target.targetId, [
       config.target,
       config.adapter,
-      ...(config.extensionPacks ?? []),
+      ...(config.extensions ?? []),
     ]);
 
     await writeMigrationPackage(packageDir, metadata, []);
     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'),
     ]);
-    if (fromContractSourceDir !== null) {
-      const sourceArtifacts = getEmittedArtifactPaths(
-        join(fromContractSourceDir, 'end-contract.json'),
-      );
-      try {
-        await copyFilesWithRename(packageDir, [
-          { sourcePath: sourceArtifacts.jsonPath, destName: 'start-contract.json' },
-          { sourcePath: sourceArtifacts.dtsPath, destName: 'start-contract.d.ts' },
-        ]);
-      } catch (error) {
-        if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-          return notOk(
-            errorFileNotFound(sourceArtifacts.jsonPath, {
-              why: `Predecessor migration is missing its destination contract snapshot at ${sourceArtifacts.jsonPath}`,
-              fix: '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.',
-            }),
-          );
-        }
-        throw error;
-      }
-    }
+    await writeContractSnapshot(migrationsDir, toStorageHash, {
+      contractJson: JSON.parse(contractJsonRaw) as unknown,
+      contractDts,
+    });
 
     const planner = migrations.createPlanner(controlAdapter);
     const emptyPlan = planner.emptyMigration(
       {
         packageDir,
-        contractJsonPath: join(packageDir, 'end-contract.json'),
+        contractJsonPath: join(contractSnapshotDir(migrationsDir, toStorageHash), 'contract.json'),
         fromHash,
         toHash: toStorageHash,
+        snapshotsImportPath: snapshotsImportPathFrom(packageDir, migrationsDir),
       },
       APP_SPACE_ID,
     );
@@ -277,7 +253,7 @@ export function createMigrationNewCommand(): Command {
   );
   setCommandExamples(command, [
     'prisma-next migration new --name split-name',
-    'prisma-next migration new --name custom-fk --from sha256:abc...',
+    'prisma-next migration new --name custom-fk --from abc123...',
   ]);
   addGlobalOptions(command)
     .option('--name <slug>', 'Migration name (used in directory name)')

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,21 +289,25 @@ 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({
     targetId: config.target.targetId,
     migrationsDir,
     appContract: toContract,
-    extensionPacks: config.extensionPacks ?? [],
+    extensions: config.extensions ?? [],
     deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
   if (!tolerantAggregateResult.ok) {
@@ -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,15 +371,15 @@ 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.
-  const canonicalExtensionInputs = toExtensionInputs(config.extensionPacks ?? []);
+  // app-space change) still re-pins extension artifacts on disk.
+  const canonicalExtensionInputs = toExtensionInputs(config.extensions ?? []);
   const seedResult = await runContractSpaceSeedPhase({
     migrationsDir,
-    extensionPacks: canonicalExtensionInputs,
+    extensions: canonicalExtensionInputs,
   });
   if (!flags.json && !flags.quiet) {
     for (const record of seedResult.seeded) {
@@ -449,7 +434,7 @@ async function executeMigrationPlanCommand(
     targetId: config.target.targetId,
     migrationsDir,
     appContract: toContract,
-    extensionPacks: config.extensionPacks ?? [],
+    extensions: config.extensions ?? [],
     deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
   if (!aggregateResult.ok) {
@@ -460,27 +445,29 @@ async function executeMigrationPlanCommand(
   const frameworkComponents = assertFrameworkComponentsCompatible(
     config.family.familyId,
     config.target.targetId,
-    [config.target, config.adapter, ...(config.extensionPacks ?? [])],
+    [config.target, config.adapter, ...(config.extensions ?? [])],
   );
 
-  // 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 });