@prisma-next/cli 0.11.0 → 0.12.0

package/src/commands/migration-plan.ts

@@ -1,13 +1,13 @@
-import { readFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } 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,
   type OperationPreview,
 } from '@prisma-next/framework-components/control';
+import { canonicalizeJson } from '@prisma-next/framework-components/utils';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import { deriveProvidedInvariants } from '@prisma-next/migration-tools/invariants';
@@ -17,10 +17,7 @@ import {
   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';
-import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
-import { readRefs } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative } from 'pathe';
@@ -34,24 +31,26 @@ import {
   errorTargetMigrationNotSupported,
   errorUnexpected,
   mapMigrationToolsError,
-  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
   getTargetMigrations,
-  loadMigrationPackages,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
+import {
+  buildContractSpaceAggregate,
+  loadContractSpaceAggregateForCli,
+} from '../utils/contract-space-aggregate-loader';
 import { runContractSpaceSeedPhase } from '../utils/contract-space-seed-phase';
 import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { resolveFromForPlan, resolveToForPlan } from '../utils/plan-resolution';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
@@ -59,55 +58,116 @@ interface MigrationPlanOptions extends CommonCommandOptions {
   readonly config?: string;
   readonly name?: string;
   readonly from?: string;
+  readonly to?: string;
 }
 
-/**
- * Load a predecessor migration's destination contract from its sibling
- * `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.
- *   - `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,
-  familyInstance: ControlFamilyInstance<string, unknown>,
-): Promise<Contract> {
-  const path = join(migrationDir, 'end-contract.json');
-  let raw: string;
-  try {
-    raw = await readFile(path, 'utf-8');
-  } catch (error) {
-    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-      throw errorFileNotFound(path, {
-        why: `Predecessor migration is missing its destination contract snapshot at ${path}`,
-        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;
+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;
+  readonly hasPlaceholders: boolean;
+};
+
+type TargetMigrationsApi = NonNullable<ReturnType<typeof getTargetMigrations>>;
+
+async function runPlannerLeg(
+  planner: ReturnType<TargetMigrationsApi['createPlanner']>,
+  migrations: TargetMigrationsApi,
+  frameworkComponents: ReturnType<typeof assertFrameworkComponentsCompatible>,
+  contract: Contract,
+  fromContract: Contract | null,
+  spaceId: string,
+): Promise<Result<PlannerSuccess, CliStructuredError>> {
+  const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
+  const plannerResult = planner.plan({
+    contract,
+    schema: fromSchema,
+    policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
+    fromContract,
+    frameworkComponents,
+    spaceId,
+  });
+  if (plannerResult.kind === 'failure') {
+    return notOk(
+      errorMigrationPlanningFailed({
+        conflicts: plannerResult.conflicts as readonly CliErrorConflict[],
+      }),
+    );
   }
+
+  let plannedOps: readonly MigrationPlanOperation[] = [];
+  let hasPlaceholders = false;
   try {
-    return familyInstance.deserializeContract(JSON.parse(raw) as unknown);
-  } catch (error) {
-    if (CliStructuredError.is(error)) {
-      throw error;
+    plannedOps = plannerResult.plan.operations;
+    if (plannedOps.length === 0) {
+      return notOk(
+        errorMigrationPlanningFailed({
+          conflicts: [
+            {
+              kind: 'unsupportedChange',
+              summary:
+                'Contract changed but planner produced no operations. ' +
+                'This indicates unsupported or ignored changes.',
+            },
+          ],
+        }),
+      );
+    }
+  } catch (e) {
+    if (CliStructuredError.is(e) && e.domain === 'MIG' && e.code === '2001') {
+      hasPlaceholders = true;
+    } else {
+      throw e;
     }
-    throw errorContractValidationFailed(
-      `Predecessor contract at ${path} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
-      { where: { path } },
-    );
   }
+
+  return ok({
+    plannedOps,
+    migrationTsContent: plannerResult.plan.renderTypeScript(),
+    hasPlaceholders,
+  });
+}
+
+async function writePlannedMigrationPackage(
+  packageDir: string,
+  fromHash: string | null,
+  toHash: string,
+  createdAt: Date,
+  leg: PlannerSuccess,
+): Promise<void> {
+  const opsForWrite = leg.hasPlaceholders ? [] : leg.plannedOps;
+  const metadataWithInvariants: Omit<MigrationMetadata, 'migrationHash'> = {
+    from: fromHash,
+    to: toHash,
+    providedInvariants: deriveProvidedInvariants(opsForWrite),
+    createdAt: createdAt.toISOString(),
+  };
+  const metadata: MigrationMetadata = {
+    ...metadataWithInvariants,
+    migrationHash: computeMigrationHash(metadataWithInvariants, opsForWrite),
+  };
+  await writeMigrationPackage(packageDir, metadata, opsForWrite);
+  await writeMigrationTs(packageDir, leg.migrationTsContent);
 }
 
 export interface MigrationPlanResult {
@@ -116,6 +176,7 @@ export interface MigrationPlanResult {
   readonly from: string | null;
   readonly to: string;
   readonly dir?: string;
+  readonly baselineDir?: string;
   /**
    * Extension-space migration packages materialised onto disk during this
    * `plan` run. Each entry names a `migrations/<spaceId>/<dirName>/`
@@ -125,7 +186,7 @@ export interface MigrationPlanResult {
    *
    * Surfacing these in the result (rather than only via `ui.step` log
    * lines) makes the cross-space side effect explicit to JSON consumers
-   * and the success-summary renderer — the same multi-space side effect
+   * and the success-summary renderer — the same cross-space side effect
    * that `migrate` will replay.
    */
   readonly emittedExtensionDirs: readonly { readonly spaceId: string; readonly dirName: string }[];
@@ -174,6 +235,9 @@ async function executeMigrationPlanCommand(
     if (options.from) {
       details.push({ label: 'from', value: options.from });
     }
+    if (options.to) {
+      details.push({ label: 'to', value: options.to });
+    }
     if (options.name) {
       details.push({ label: 'name', value: options.name });
     }
@@ -207,8 +271,7 @@ async function executeMigrationPlanCommand(
     );
   }
 
-  // Construct the family instance up-front so on-disk reads (the app
-  // contract here + every `readPredecessorEndContract` below) cross the
+  // Construct the family instance up-front so on-disk contract reads 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);
@@ -234,70 +297,84 @@ async function executeMigrationPlanCommand(
       }),
     );
   }
-  const toStorageHash = rawStorageHash;
+  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`.
+  let toArtifacts: { contractJson: unknown; contractDts: string } | null = null;
 
-  // Read existing migrations and determine "from" contract
   let fromContract: Contract | null = null;
   let fromHash: string | null = null;
   let fromContractSourceDir: string | null = null;
+  let snapshotStartContract: { contractJson: unknown; contractDts: string } | null = null;
+  let isAutoBaseline = false;
 
-  try {
-    const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
+  const tolerantAggregateResult = await loadContractSpaceAggregateForCli({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: toContract,
+    extensionPacks: config.extensionPacks ?? [],
+    deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
+  });
+  if (!tolerantAggregateResult.ok) {
+    return notOk(tolerantAggregateResult.failure);
+  }
+  const resolutionMember = tolerantAggregateResult.value.app;
 
-    if (options.from) {
-      const refs = await readRefs(resolveMigrationPaths(options.config, config).refsDir);
-      const refResult = parseContractRef(options.from, { graph, refs });
-      if (!refResult.ok) {
-        return notOk(mapRefResolutionError(refResult.failure));
-      }
-      fromHash = refResult.value.hash;
-      const matchingBundle = bundles.find((p) => p.metadata.to === fromHash);
-      if (!matchingBundle) {
-        return notOk(
-          errorUnexpected(
-            `No migration bundle found for --from "${options.from}" (resolved hash: ${fromHash})`,
-            {
-              why: `The ref resolved successfully but no on-disk migration package has an end-contract hash matching ${fromHash}.`,
-              fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
-            },
-          ),
-        );
-      }
-      fromContractSourceDir = matchingBundle.dirPath;
-      fromContract = await readPredecessorEndContract(fromContractSourceDir, familyInstance);
-    } else {
-      const latestMigration = findLatestMigration(graph);
-      if (latestMigration) {
-        fromHash = latestMigration.to;
-        const leafPkg = bundles.find(
-          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
-        );
-        if (leafPkg) {
-          fromContractSourceDir = leafPkg.dirPath;
-          fromContract = await readPredecessorEndContract(fromContractSourceDir, familyInstance);
-        }
-      }
-    }
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    // `readPredecessorEndContract` raises a `CliStructuredError` directly
-    // for the missing-snapshot case so the operator gets a precise
-    // why/fix; pass it through unchanged rather than re-wrapping.
-    if (CliStructuredError.is(error)) {
-      return notOk(error);
+  const resolutionResult = await resolveFromForPlan({
+    optionsFrom: options.from,
+    member: resolutionMember,
+  });
+
+  if (!resolutionResult.ok) {
+    return notOk(resolutionResult.failure);
+  }
+
+  switch (resolutionResult.value.kind) {
+    case 'greenfield':
+      break;
+    case 'graph-node':
+      fromHash = resolutionResult.value.fromHash;
+      fromContract = resolutionResult.value.fromContract;
+      fromContractSourceDir = resolutionResult.value.sourceDir;
+      break;
+    case 'snapshot':
+      fromHash = resolutionResult.value.fromHash;
+      fromContract = resolutionResult.value.fromContract;
+      snapshotStartContract = {
+        contractJson: resolutionResult.value.contractJson,
+        contractDts: resolutionResult.value.contractDts,
+      };
+      break;
+    case 'auto-baseline':
+      fromHash = resolutionResult.value.fromHash;
+      fromContract = resolutionResult.value.fromContract;
+      snapshotStartContract = {
+        contractJson: resolutionResult.value.contractJson,
+        contractDts: resolutionResult.value.contractDts,
+      };
+      isAutoBaseline = true;
+      break;
+  }
+
+  // `--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.*`
+  // change.
+  if (options.to !== undefined) {
+    const toResolution = await resolveToForPlan(options.to, {
+      member: resolutionMember,
+    });
+    if (!toResolution.ok) {
+      return notOk(toResolution.failure);
     }
-    // Wrap unexpected (non-MigrationToolsError) failures from the migration
-    // load phase in a structured CLI envelope. Letting them throw would
-    // bypass `handleResult()` and crash the command — see CLI structured-
-    // errors guideline (CliStructuredError + Result pattern).
-    const message = error instanceof Error ? error.message : String(error);
-    return notOk(
-      errorUnexpected(message, {
-        why: `Unexpected error while loading migrations: ${message}`,
-      }),
-    );
+    toContract = toResolution.value.contract;
+    toStorageHash = toResolution.value.hash;
+    toArtifacts = {
+      contractJson: toResolution.value.contractJson,
+      contractDts: toResolution.value.contractDts,
+    };
   }
 
   // Phase 1 — seed: unconditionally re-emit per-space pinned artefacts
@@ -325,8 +402,10 @@ async function executeMigrationPlanCommand(
     r.newMigrationDirs.map((dirName) => ({ spaceId: r.spaceId, dirName })),
   );
 
-  // Check for no-op (same hash means no changes)
-  if (fromHash === toStorageHash) {
+  // Check for no-op (same hash means no changes). Auto-baseline is exempt:
+  // an empty graph with db ref at the current contract still needs a
+  // null → fromHash baseline bundle so migrate can anchor the marker.
+  if (fromHash === toStorageHash && !isAutoBaseline) {
     const result: MigrationPlanResult = {
       ok: true,
       noOp: true,
@@ -375,97 +454,204 @@ async function executeMigrationPlanCommand(
     [config.target, config.adapter, ...(config.extensionPacks ?? [])],
   );
 
-  // Build manifest and write migration package
-  const timestamp = new Date();
-  const slug = options.name ?? 'migration';
-  const dirName = formatMigrationDirName(timestamp, slug);
-  const packageDir = join(appMigrationsDir, dirName);
-
-  const baseMetadata: Omit<MigrationMetadata, 'migrationHash' | 'providedInvariants'> = {
-    from: fromHash,
-    to: toStorageHash,
-    hints: {
-      used: [],
-      applied: [],
-      plannerVersion: '2.0.0',
-    },
-    labels: [],
-    createdAt: timestamp.toISOString(),
-  };
+  // 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> {
+    if (toArtifacts !== null) {
+      await writeSnapshotContractArtifacts(
+        packageDir,
+        toArtifacts.contractJson,
+        toArtifacts.contractDts,
+        'end-contract',
+      );
+      return;
+    }
+    const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+    await copyFilesWithRename(packageDir, [
+      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
+      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
+    ]);
+  }
 
   try {
     const planner = migrations.createPlanner(familyInstance);
-    const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
-    const plannerResult = planner.plan({
-      contract: aggregate.app.contract,
-      schema: fromSchema,
-      policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
-      fromContract,
-      frameworkComponents,
-      spaceId: aggregate.app.spaceId,
-    });
-    if (plannerResult.kind === 'failure') {
-      return notOk(
-        errorMigrationPlanningFailed({
-          conflicts: plannerResult.conflicts as readonly CliErrorConflict[],
-        }),
+
+    if (
+      isAutoBaseline &&
+      fromHash !== null &&
+      fromContract !== null &&
+      snapshotStartContract !== null
+    ) {
+      const baselineTimestamp = new Date();
+      const deltaTimestamp = new Date(baselineTimestamp.getTime() + 60_000);
+      const baselineDirName = formatMigrationDirName(baselineTimestamp, 'baseline');
+      const deltaDirName = formatMigrationDirName(deltaTimestamp, options.name ?? 'migration');
+      const baselinePackageDir = join(appMigrationsDir, baselineDirName);
+      const deltaPackageDir = join(appMigrationsDir, deltaDirName);
+
+      const baselineLeg = await runPlannerLeg(
+        planner,
+        migrations,
+        frameworkComponents,
+        fromContract,
+        null,
+        aggregate.app.spaceId,
       );
-    }
+      if (!baselineLeg.ok) {
+        return notOk(baselineLeg.failure);
+      }
 
-    // Accessing .operations triggers toOp() on each call. If any call
-    // is a DataTransformCall with an unfilled placeholder stub, toOp()
-    // throws PN-MIG-2001. We catch that here so the migration can still
-    // be scaffolded with `ops: []`; the user fills the placeholder, then
-    // re-runs `node migration.ts` to attest with the real ops.
-    let plannedOps: readonly MigrationPlanOperation[] = [];
-    let hasPlaceholders = false;
-    try {
-      plannedOps = plannerResult.plan.operations;
-      if (plannedOps.length === 0) {
-        return notOk(
-          errorMigrationPlanningFailed({
-            conflicts: [
-              {
-                kind: 'unsupportedChange',
-                summary:
-                  'Contract changed but planner produced no operations. ' +
-                  'This indicates unsupported or ignored changes.',
-              },
-            ],
-          }),
-        );
+      await writePlannedMigrationPackage(
+        baselinePackageDir,
+        null,
+        fromHash,
+        baselineTimestamp,
+        baselineLeg.value,
+      );
+      await writeSnapshotContractArtifacts(
+        baselinePackageDir,
+        snapshotStartContract.contractJson,
+        snapshotStartContract.contractDts,
+        'end-contract',
+      );
+
+      if (fromHash === toStorageHash) {
+        const baselineOps = baselineLeg.value.hasPlaceholders ? [] : baselineLeg.value.plannedOps;
+        if (baselineLeg.value.hasPlaceholders) {
+          const baselineDir = relative(process.cwd(), baselinePackageDir);
+          const result: MigrationPlanResult = {
+            ok: true,
+            noOp: false,
+            from: fromHash,
+            to: toStorageHash,
+            dir: baselineDir,
+            baselineDir,
+            operations: [],
+            emittedExtensionDirs,
+            pendingPlaceholders: true,
+            summary:
+              'Planned baseline with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
+            timings: { total: Date.now() - startTime },
+          };
+          return ok(result);
+        }
+
+        const preview = hasOperationPreview(familyInstance)
+          ? familyInstance.toOperationPreview(baselineOps)
+          : undefined;
+        const result: MigrationPlanResult = {
+          ok: true,
+          noOp: false,
+          from: fromHash,
+          to: toStorageHash,
+          baselineDir: relative(process.cwd(), baselinePackageDir),
+          operations: baselineOps.map((op) => ({
+            id: op.id,
+            label: op.label,
+            operationClass: op.operationClass,
+          })),
+          emittedExtensionDirs,
+          ...(preview !== undefined ? { preview } : {}),
+          summary: buildAutoBaselinePlanSummary(0, emittedExtensionDirs.length),
+          timings: { total: Date.now() - startTime },
+        };
+        return ok(result);
+      }
+
+      const deltaLeg = await runPlannerLeg(
+        planner,
+        migrations,
+        frameworkComponents,
+        aggregate.app.contract(),
+        fromContract,
+        aggregate.app.spaceId,
+      );
+      if (!deltaLeg.ok) {
+        return notOk(deltaLeg.failure);
       }
-    } catch (e) {
-      if (CliStructuredError.is(e) && e.domain === 'MIG' && e.code === '2001') {
-        hasPlaceholders = true;
-      } else {
-        throw e;
+
+      await writePlannedMigrationPackage(
+        deltaPackageDir,
+        fromHash,
+        toStorageHash,
+        deltaTimestamp,
+        deltaLeg.value,
+      );
+      await writeDestinationEndContract(deltaPackageDir);
+      await writeSnapshotStartContract(
+        deltaPackageDir,
+        snapshotStartContract.contractJson,
+        snapshotStartContract.contractDts,
+      );
+
+      const deltaOps = deltaLeg.value.hasPlaceholders ? [] : deltaLeg.value.plannedOps;
+      if (deltaLeg.value.hasPlaceholders) {
+        const result: MigrationPlanResult = {
+          ok: true,
+          noOp: false,
+          from: fromHash,
+          to: toStorageHash,
+          dir: relative(process.cwd(), deltaPackageDir),
+          baselineDir: relative(process.cwd(), baselinePackageDir),
+          operations: [],
+          emittedExtensionDirs,
+          pendingPlaceholders: true,
+          summary:
+            'Planned baseline + migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
+          timings: { total: Date.now() - startTime },
+        };
+        return ok(result);
       }
+
+      const preview = hasOperationPreview(familyInstance)
+        ? familyInstance.toOperationPreview(deltaOps)
+        : undefined;
+      const result: MigrationPlanResult = {
+        ok: true,
+        noOp: false,
+        from: fromHash,
+        to: toStorageHash,
+        dir: relative(process.cwd(), deltaPackageDir),
+        baselineDir: relative(process.cwd(), baselinePackageDir),
+        operations: deltaOps.map((op) => ({
+          id: op.id,
+          label: op.label,
+          operationClass: op.operationClass,
+        })),
+        emittedExtensionDirs,
+        ...(preview !== undefined ? { preview } : {}),
+        summary: buildAutoBaselinePlanSummary(deltaOps.length, emittedExtensionDirs.length),
+        timings: { total: Date.now() - startTime },
+      };
+      return ok(result);
     }
 
-    const migrationTsContent = plannerResult.plan.renderTypeScript();
-
-    // Always-attest: compute migrationHash over (metadata, ops). When
-    // placeholders blocked lowering, ops is `[]` and the hash is computed
-    // over the empty list — re-emitting after the user fills the placeholder
-    // produces a different hash (over the real ops). This is intentional;
-    // there is no on-disk "draft" state.
-    const opsForWrite = hasPlaceholders ? [] : plannedOps;
-    const metadataWithInvariants: Omit<MigrationMetadata, 'migrationHash'> = {
-      ...baseMetadata,
-      providedInvariants: deriveProvidedInvariants(opsForWrite),
-    };
-    const metadata: MigrationMetadata = {
-      ...metadataWithInvariants,
-      migrationHash: computeMigrationHash(metadataWithInvariants, opsForWrite),
-    };
+    const timestamp = new Date();
+    const slug = options.name ?? 'migration';
+    const dirName = formatMigrationDirName(timestamp, slug);
+    const packageDir = join(appMigrationsDir, dirName);
 
-    await writeMigrationPackage(packageDir, metadata, opsForWrite);
-    const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
-    await copyFilesWithRename(packageDir, [
-      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
-      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
-    ]);
+    const deltaLeg = await runPlannerLeg(
+      planner,
+      migrations,
+      frameworkComponents,
+      aggregate.app.contract(),
+      fromContract,
+      aggregate.app.spaceId,
+    );
+    if (!deltaLeg.ok) {
+      return notOk(deltaLeg.failure);
+    }
+
+    await writePlannedMigrationPackage(
+      packageDir,
+      fromHash,
+      toStorageHash,
+      timestamp,
+      deltaLeg.value,
+    );
+    await writeDestinationEndContract(packageDir);
     if (fromContractSourceDir !== null) {
       const sourceArtifacts = getEmittedArtifactPaths(
         join(fromContractSourceDir, 'end-contract.json'),
@@ -474,10 +660,15 @@ async function executeMigrationPlanCommand(
         { 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 writeMigrationTs(packageDir, migrationTsContent);
 
-    if (hasPlaceholders) {
+    if (deltaLeg.value.hasPlaceholders) {
       const result: MigrationPlanResult = {
         ok: true,
         noOp: false,
@@ -494,6 +685,7 @@ async function executeMigrationPlanCommand(
       return ok(result);
     }
 
+    const plannedOps = deltaLeg.value.plannedOps;
     const preview = hasOperationPreview(familyInstance)
       ? familyInstance.toOperationPreview(plannedOps)
       : undefined;
@@ -542,6 +734,7 @@ export function createMigrationPlanCommand(): Command {
   setCommandExamples(command, [
     'prisma-next migration plan',
     'prisma-next migration plan --name add-users-table',
+    'prisma-next migration plan --to <migration-dir>^ --name rollback',
   ]);
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
@@ -550,6 +743,10 @@ export function createMigrationPlanCommand(): Command {
       '--from <contract>',
       'Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
+    .option(
+      '--to <contract>',
+      'Destination contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path); defaults to the emitted contract',
+    )
     .action(async (options: MigrationPlanOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();
@@ -593,6 +790,17 @@ function buildPlanSummary(plannedOpsCount: number, emittedExtensionDirsCount: nu
   return `${base}; materialised ${emittedExtensionDirsCount} ${noun}`;
 }
 
+function buildAutoBaselinePlanSummary(
+  deltaOpsCount: number,
+  emittedExtensionDirsCount: number,
+): string {
+  const base = `Planned baseline + ${deltaOpsCount} operation(s)`;
+  if (emittedExtensionDirsCount === 0) return base;
+  const noun =
+    emittedExtensionDirsCount === 1 ? 'extension-space migration' : 'extension-space migrations';
+  return `${base}; materialised ${emittedExtensionDirsCount} ${noun}`;
+}
+
 export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFlags): string {
   const lines: string[] = [];
   const useColor = flags.color !== false;
@@ -672,6 +880,9 @@ export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: Gl
 
   lines.push(dim_(`from:   ${result.from}`));
   lines.push(dim_(`to:     ${result.to}`));
+  if (result.baselineDir) {
+    lines.push(dim_(`Baseline → ${result.baselineDir}`));
+  }
   if (result.dir) {
     lines.push(dim_(`App space → ${result.dir}`));
   }
@@ -689,8 +900,12 @@ export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: Gl
   // (`prisma-next migrate`) regardless of how many spaces were
   // materialised — `db update` is a dev-time convenience, not the
   // canonical replay step.
+  const reviewTarget =
+    result.baselineDir !== undefined && result.dir !== undefined
+      ? `${result.baselineDir} and ${result.dir}`
+      : (result.baselineDir ?? result.dir ?? '<dir>');
   lines.push(
-    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migrate')}.`,
+    `Next: review ${green_(reviewTarget)} if needed, then run ${green_('prisma-next migrate')}.`,
   );
 
   if (result.preview && result.preview.statements.length > 0) {