TML-2690: make rollback edges plannable and applyable via --to (#635)

Author: wmadden

docs/architecture docs/subsystems/7. Migration System.md

@@ -140,7 +140,7 @@ Additive structure is covered by core operations: create table, add nullable col
 
 ### `migration plan`
 
-`prisma-next migration plan` diffs a `from` contract against the current emitted contract and writes one or two attested migration packages. It is fully offline — no database connection. See [ADR 218](../adrs/ADR%20218%20-%20Refs%20with%20paired%20contract%20snapshots%20and%20universal%20graph-node%20invariant.md).
+`prisma-next migration plan` diffs a `from` contract against a `to` contract and writes one or two attested migration packages. It is fully offline — no database connection. See [ADR 218](../adrs/ADR%20218%20-%20Refs%20with%20paired%20contract%20snapshots%20and%20universal%20graph-node%20invariant.md).
 
 **Default `from` resolution** ([`resolveFromForPlan`](../../../packages/1-framework/3-tooling/cli/src/utils/plan-resolution.ts)):
 
@@ -150,16 +150,20 @@ Additive structure is covered by core operations: create table, add nullable col
 
 The from-contract materialises from the ref's paired snapshot (ref-resolved `from`) or from a bundle's `end-contract.json` (hash-resolved `from` on a graph node).
 
+**Default `to` resolution:** when `--to` is omitted, the destination is the emitted `contract.json`. When `--to <ref-or-hash>` is supplied, the same [contract-reference grammar](#refs-environment-targets) as `--from` applies (hash / prefix, ref name, migration directory, `<dir>^`, or filesystem path); the resolved contract becomes the planner destination and the source of `end-contract.json` / `.d.ts`. Use `--to <migration-dir>^` to plan a reverse (rollback) edge toward a predecessor state.
+
 **Emission cases:**
 
 | Case | Condition | Output |
 |---|---|---|
-| Greenfield | Graph empty, `from` = `null` | One bundle: `null → current_contract` |
-| Auto-baseline | Graph empty, `from` non-null, paired snapshot available | Two bundles: baseline `null → from` + delta `from → current` |
-| Normal delta | Graph non-empty, `from` is a graph node | One bundle: `from → current_contract` |
+| Greenfield | Graph empty, `from` = `null` | One bundle: `null → to_contract` |
+| Auto-baseline | Graph empty, `from` non-null, paired snapshot available | Two bundles: baseline `null → from` + delta `from → to_contract` |
+| Normal delta | Graph non-empty, `from` is a graph node | One bundle: `from → to_contract` |
 | Forgot-the-flag | Graph non-empty, `from` not a graph node | Refuse: `MIGRATION.HASH_NOT_IN_GRAPH` |
 | Snapshot missing | `from` non-null, no contract source | Refuse: `MIGRATION.SNAPSHOT_MISSING` |
 
+When `--to` is omitted, `to_contract` is the emitted contract; when `--to` is supplied, `to_contract` is the resolved destination.
+
 Plan-time refuse diagnostics name the resolved hash, list refs pointing at graph nodes, and suggest `--from <reachable-ref>`. Snapshot-missing diagnostics suggest `db update --advance-ref <name>` to repopulate or `ref delete <name>` to clear an orphan pointer.
 
 ## Authoring Surface
@@ -539,7 +543,7 @@ Top-level verbs:
 
 Migration namespace (artifacts and graph):
 
-- `prisma-next migration plan [--from <contract>] --name <slug>` — diff contracts and write a fully attested package (`migration.ts` + `migration.json` + `ops.json`) offline. Defaults `--from` to the `db` ref (falls back to greenfield when absent). Re-run `./migration.ts` after filling any `placeholder(...)` slots to rewrite `ops.json` and the `migrationHash`.
+- `prisma-next migration plan [--from <contract>] [--to <contract>] --name <slug>` — diff contracts and write a fully attested package (`migration.ts` + `migration.json` + `ops.json`) offline. Defaults `--from` to the `db` ref (falls back to greenfield when absent) and `--to` to the emitted contract. Both flags accept the full [contract-reference grammar](#refs-environment-targets). Re-run `./migration.ts` after filling any `placeholder(...)` slots to rewrite `ops.json` and the `migrationHash`.
 - `prisma-next migration new [--from <hash> --to <hash>] --name <slug>` — scaffold an empty `migration.ts` for hand-authoring.
 - `prisma-next migration status [--db <url>] [--to <contract>] [--from <contract>]` — path/pending question. Live (uses marker) or offline (uses `--from`).
 - `prisma-next migration log --db <url>` — applied execution history (reads the marker; offline reading of the ledger is also supported).
@@ -590,7 +594,7 @@ Structured diagnostics from plan-time and apply-time checks suggest concrete rec
 | `MIGRATION.HASH_NOT_IN_GRAPH` | `migration plan` or `ref set`: resolved hash not in graph | `migration plan --from <reachable-ref>` (e.g. `--from production`) |
 | `MIGRATION.SNAPSHOT_MISSING` | `migration plan`: ref pointer exists but paired snapshot absent | `db update --advance-ref <name>` to repopulate, or `ref delete <name>` to clear orphan pointer |
 | `MIGRATION.MARKER_MISMATCH` | `migrate`: live marker hash not a graph node (pre-DDL check) | `migration plan --from <graph-tip>`, or `ref set db <marker-hash>` if on-disk graph is canonical |
-| `MIGRATION.PATH_UNREACHABLE` | `migrate`: no path from marker to target in on-disk graph | `migration plan --from <marker-or-reachable> --to <target>` per improved `fix` payload |
+| `MIGRATION.PATH_UNREACHABLE` | `migrate`: no path from marker to target in on-disk graph | Plan the missing edge with `migration plan --from <marker-or-reachable> --to <target> --name <slug>`, then apply with `migrate --to <target>`. For a rollback, use `--to <migration-dir>^` in both steps — the planned reverse edge applies and moves the marker back without editing contract source. Review destructive (`DROP`) ops in the plan before applying. When the space has no on-disk migrations yet, omit `--from` and use `migration plan --to <target> --name <slug>` first. |
 
 After plain `migrate`, refresh a stale `db` ref with `db update` (no-op on DB when marker matches) or `migrate --advance-ref db` in the same invocation.
 

packages/1-framework/3-tooling/cli/README.md

@@ -932,25 +932,26 @@ The `contract.output` field specifies the path to `contract.json`. This is the c
 
 ### `prisma-next migration plan`
 
-Plan a migration from contract changes. Compares the emitted contract against the latest on-disk migration state and produces a new migration package with the required operations. No database connection is needed — fully offline.
+Plan a migration from contract changes. Compares a starting contract against a destination contract and produces a new migration package with the required operations. No database connection is needed — fully offline.
 
 ```bash
-prisma-next migration plan [--config <path>] [--name <slug>] [--from <hash>] [--json] [-v] [-q] [--color/--no-color]
+prisma-next migration plan [--config <path>] [--name <slug>] [--from <contract>] [--to <contract>] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 **Options:**
 - `--config <path>`: Path to `prisma-next.config.ts`
 - `--name <slug>`: Name slug for the migration directory (default: `migration`)
-- `--from <hash>`: Explicit starting contract hash (overrides latest migration target detection)
+- `--from <contract>`: Starting contract reference (hash, prefix, ref name, migration directory, `<dir>^`, or filesystem path). Defaults to the `db` ref (greenfield when absent).
+- `--to <contract>`: Destination contract reference (same grammar as `--from`). Defaults to the emitted `contract.json`. Use `--to <migration-dir>^` to plan a rollback toward a predecessor state.
 - `--json`: Output as JSON object
 - `-q, --quiet`: Quiet mode (errors only)
 - `-v, --verbose`: Verbose output (debug info, timings)
 
 **What it does:**
-1. Loads config and reads `contract.json` (the "to" contract)
+1. Loads config and resolves the destination contract: `--to <contract>` if provided, otherwise `contract.json`
 2. Reads existing migrations from `config.migrations.dir` (default: `migrations/`)
-3. Determines the starting point: `--from <hash>` if provided, otherwise the latest migration target
-4. Diffs the starting contract against the new contract using the target's migration planner
+3. Determines the starting point: `--from <contract>` if provided, otherwise the `db` ref (greenfield when absent)
+4. Diffs the starting contract against the destination using the target's migration planner
 5. Scaffolds a new migration package: `migration.ts` (containing `placeholder(...)` lambdas for any data transforms), `migration.json` (with a content-addressed `migrationHash` over the planned ops, or over `[]` when the planner could not lower any calls because of placeholders), `ops.json` (the planned ops, or `[]` in the placeholder-blocked case), and contract bookends. The package is **always** fully attested — there is no draft state on disk.
 6. If the plan has unfilled `placeholder(...)` slots, the command returns a successful `pendingPlaceholders` envelope (a warning, not a failure) asking the developer to fill in the slots before re-emitting. The on-disk `ops.json` is `[]` and `migrationHash` is the hash of `(metadata, [])`, so applying the migration as-written will not advance the storage hash to the intended destination — the runner's destination-hash post-check surfaces this as a state mismatch. After filling in the placeholders, run `node migrations/<dir>/migration.ts` to re-emit `ops.json` and the corresponding `migrationHash`. `PN-MIG-2001` is raised only at self-emit time when a slot is still unfilled.
 
@@ -961,7 +962,7 @@ prisma-next migration plan [--config <path>] [--name <slug>] [--from <hash>] [--
 - `migrations/<dir>/start-contract.{json,d.ts}` — bookend from the "from" side (when applicable)
 - `migrations/<dir>/end-contract.{json,d.ts}` — bookend from the "to" side
 
-**Branching with `--from`:** Use `--from` to create a migration edge from a specific contract hash instead of the latest migration target. This enables branched migration graphs where multiple environments diverge from a common ancestor.
+**Branching with `--from` and `--to`:** Use `--from` to create a migration edge from a specific contract hash instead of the default starting point. Use `--to` to plan toward any resolved contract — including a rollback via `<migration-dir>^` — instead of the emitted contract. This enables branched migration graphs and arbitrary-target (including reverse) edges without editing contract source.
 
 ### `prisma-next migration show`
 
@@ -1027,6 +1028,7 @@ prisma-next migrate [--db <url>] [--to <contract>] [--config <path>] [--json] [-
 
 **Options:**
 - `--db <url>`: Database connection string (optional; defaults to `config.db.connection`)
+- `--to <contract>`: Target contract reference (hash, prefix, ref name, migration directory, `<dir>^`, or filesystem path). When omitted, applies toward the emitted `contract.json`. When `--to` resolves to an on-disk graph node, verification and apply use that bundle's `end-contract.json` — so a planned rollback or other arbitrary-target edge applies without editing contract source.
 - `--ref <name>`: Target a named ref from `migrations/refs.json` instead of the current contract hash
 - `--config <path>`: Path to `prisma-next.config.ts`
 - `--json`: Output as JSON object
@@ -1036,12 +1038,14 @@ prisma-next migrate [--db <url>] [--to <contract>] [--config <path>] [--json] [-
 **What it does:**
 1. Reads migration packages from `config.migrations.dir`. Every package is attested — there is no on-disk draft state. The loader (`readMigrationPackage` in `@prisma-next/migration-tools/io`) rehashes `(metadata, ops)` for each `MigrationPackage` it returns and confirms the result matches the stored `migrationHash`. If a package has been hand-edited or partially written since emit, the load fails with `MIGRATION.HASH_MISMATCH` pointing at the offending directory and asks the developer to re-run `node migrations/<dir>/migration.ts` (or restore from version control).
 2. Reconstructs the migration graph from all loaded packages
-3. Determines the destination hash: from `--ref` (via `refs.json`) or from `contract.json`
+3. Determines the destination hash and apply contract: from `--to` / `--ref`, or from `contract.json` when neither is supplied
 4. Connects to the database and reads the current marker hash
 5. Finds the shortest path from the marker hash to the destination using graph pathfinding
 6. Executes each pending migration in order using the target's `MigrationRunner`
 7. Each migration runs in its own transaction with prechecks, postchecks, and idempotency checks enabled
-8. After each migration, the runner verifies the schema and updates the marker/ledger
+8. After each migration, the runner runs the migration's post-checks and verifies the resulting state matches the target contract's storage hash, then updates the marker/ledger
+
+**Rollback workflow:** When no on-disk edge reaches the target (for example `migrate --to <migration-dir>^`), the command refuses with `MIGRATION.PATH_UNREACHABLE` and suggests planning the missing edge with `migration plan --from <current> --to <target> --name <slug>`, then re-running `migrate --to <target>`. No contract-source edit is required.
 
 **Config requirements:** Requires `driver` and `db.connection` (or `--db`). `migrations.dir` is optional and defaults to `migrations/`.
 

packages/1-framework/3-tooling/cli/src/commands/migrate.ts

@@ -5,11 +5,9 @@ import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migrati
 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 { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { join } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import type {
@@ -42,6 +40,7 @@ import {
   setCommandExamples,
   targetSupportsMigrations,
 } from '../utils/command-helpers';
+import { mapContractAtError } from '../utils/contract-at-errors';
 import {
   loadContractSpaceAggregateForCli,
   refuseContractSpaceIntegrity,
@@ -198,14 +197,16 @@ async function executeMigrateCommand(
   }
 
   let refEntry: RefEntry | undefined;
+  let refName: string | undefined;
   if (toArg) {
-    const refs = await readRefs(refsDir);
+    const refs = aggregate.app.refs;
     const refResult = parseContractRef(toArg, { graph: aggregate.app.graph(), refs });
     if (!refResult.ok) {
       return notOk(mapRefResolutionError(refResult.failure));
     }
     if (refResult.value.provenance.kind === 'ref') {
-      const resolved = refs[refResult.value.provenance.refName];
+      refName = refResult.value.provenance.refName;
+      const resolved = refs[refName];
       if (resolved) refEntry = resolved;
     } else {
       refEntry = { hash: refResult.value.hash, invariants: [] };
@@ -237,7 +238,6 @@ async function executeMigrateCommand(
   }
 
   const appGraph = aggregate.app.graph();
-  const appBundles = aggregate.app.packages;
 
   const client = createControlClient({
     family: config.family,
@@ -285,8 +285,35 @@ async function executeMigrateCommand(
       ui.step('Loading contract spaces…');
     }
 
+    // When `--to` resolves to an on-disk graph node with a matching bundle,
+    // verify and apply against THAT bundle's destination contract via
+    // `contractAt` — not the emitted `contract.json`. With `--to` omitted,
+    // or a target with no matching bundle, the emitted contract stays the
+    // apply contract (the only migrate-specific default). The same
+    // `contractAt` artifacts feed the optional ref-advancement snapshot.
+    let applyContract: Contract = contractRaw;
+    let snapshotContractJson: Record<string, unknown> = JSON.parse(contractContent);
+    let snapshotContractDts: string | undefined;
+    if (toArg && refEntry) {
+      const targetHash = refEntry.hash;
+      const matchingBundle = aggregate.app.packages.find((p) => p.metadata.to === targetHash);
+      if (matchingBundle) {
+        try {
+          const at = await aggregate.app.contractAt(
+            targetHash,
+            refName !== undefined ? { refName } : undefined,
+          );
+          applyContract = at.contract;
+          snapshotContractJson = at.contractJson as Record<string, unknown>;
+          snapshotContractDts = at.contractDts;
+        } catch (error) {
+          return mapContractAtError(error, { artifactRole: 'to' });
+        }
+      }
+    }
+
     const applyResult = await client.migrationApply({
-      contract: contractRaw,
+      contract: applyContract,
       migrationsDir,
       ...ifDefined('refHash', refEntry?.hash),
       ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
@@ -301,37 +328,11 @@ async function executeMigrateCommand(
 
     let advancedRef: { name: string; hash: string } | null = null;
     if (options.advanceRef !== undefined) {
-      let contractJsonPathForSnapshot = contractPathAbsolute;
-      let contractJsonForSnapshot: Record<string, unknown> = JSON.parse(contractContent) as Record<
-        string,
-        unknown
-      >;
-      if (toArg && refEntry) {
-        const matchingBundle = appBundles.find((p) => p.metadata.to === refEntry.hash);
-        if (matchingBundle) {
-          const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
-          contractJsonPathForSnapshot = endContractPath;
-          try {
-            const raw = await readFile(endContractPath, 'utf-8');
-            contractJsonForSnapshot = JSON.parse(raw) as Record<string, unknown>;
-          } catch (error) {
-            if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-              return notOk(
-                errorFileNotFound(endContractPath, {
-                  why: `Bundle end-contract not found at ${endContractPath}`,
-                  fix: 'Re-emit the migration bundle or pick a different --to target.',
-                }),
-              );
-            }
-            throw error;
-          }
-        }
-      }
       try {
-        const contractIR = await readContractIR(
-          contractJsonForSnapshot,
-          contractJsonPathForSnapshot,
-        );
+        const contractIR =
+          snapshotContractDts !== undefined
+            ? { contract: snapshotContractJson, contractDts: snapshotContractDts }
+            : await readContractIR(snapshotContractJson, contractPathAbsolute);
         advancedRef = await executeRefAdvancement(
           refsDir,
           options.advanceRef,