@prisma-next/cli 0.8.0-dev.1 → 0.8.0-dev.10

package/src/commands/migration-status.ts

@@ -19,8 +19,9 @@ import {
   findReachableLeaves,
 } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry, Refs } from '@prisma-next/migration-tools/refs';
-import { readRefs, resolveRef } 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 { cyan, dim, magenta, yellow } from 'colorette';
@@ -33,6 +34,7 @@ import {
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -43,6 +45,7 @@ import {
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
+  setCommandSeeAlso,
   toPathDecisionResult,
   toStructuralEdge,
 } from '../utils/command-helpers';
@@ -70,10 +73,8 @@ import { TerminalUI } from '../utils/terminal-ui';
 interface MigrationStatusOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
-  readonly ref?: string;
-  readonly graph?: boolean;
-  readonly limit?: string;
-  readonly all?: boolean;
+  readonly to?: string;
+  readonly from?: string;
 }
 
 export interface MigrationStatusEntry {
@@ -94,7 +95,7 @@ export interface MigrationStatusEntry {
  *
  * - `headHash`: the on-disk head ref's hash (where the space is going).
  * - `markerHash`: the live marker hash for the space, or null if no
- *    marker has been written yet (greenfield, or pre-`migration apply`).
+ *    marker has been written yet (greenfield, or pre-`migrate`).
  * - `pendingCount`: number of migration edges between marker and head.
  *    Computed via {@link graphWalkStrategy}; 0 means the space is
  *    already at head.
@@ -420,23 +421,6 @@ function resolveDisplayChain(
   return toTarget;
 }
 
-const DEFAULT_LIMIT = 10;
-
-function determineLimit(opts: MigrationStatusOptions) {
-  if (opts.all) {
-    // No limit
-    return;
-  }
-  if (!opts.limit) {
-    return DEFAULT_LIMIT;
-  }
-  const parsed = Number.parseInt(opts.limit, 10);
-  if (Number.isNaN(parsed)) {
-    return DEFAULT_LIMIT;
-  }
-  return parsed;
-}
-
 /**
  * Build the aggregate enumeration of contract spaces for the status
  * output. Loads the aggregate from disk (lossy on failure — extension
@@ -581,11 +565,32 @@ async function executeMigrationStatusCommand(
     throw error;
   }
 
-  if (options.ref) {
-    activeRefName = options.ref;
+  let fromOverrideHash: string | undefined;
+
+  if (options.to || options.from) {
     try {
-      activeRefEntry = resolveRef(allRefs, activeRefName);
-      activeRefHash = activeRefEntry.hash;
+      const { graph: earlyGraph } = await loadMigrationPackages(appMigrationsDir);
+
+      if (options.to) {
+        const refResult = parseContractRef(options.to, { graph: earlyGraph, refs: allRefs });
+        if (!refResult.ok) {
+          return notOk(mapRefResolutionError(refResult.failure));
+        }
+        activeRefHash = refResult.value.hash;
+        if (refResult.value.provenance.kind === 'ref') {
+          const resolvedRefName = refResult.value.provenance.refName;
+          activeRefName = resolvedRefName;
+          activeRefEntry = allRefs[resolvedRefName];
+        }
+      }
+
+      if (options.from) {
+        const fromResult = parseContractRef(options.from, { graph: earlyGraph, refs: allRefs });
+        if (!fromResult.ok) {
+          return notOk(mapRefResolutionError(fromResult.failure));
+        }
+        fromOverrideHash = fromResult.value.hash;
+      }
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -613,6 +618,9 @@ async function executeMigrationStatusCommand(
     if (activeRefName) {
       details.push({ label: 'ref', value: activeRefName });
     }
+    if (options.from) {
+      details.push({ label: 'from', value: options.from });
+    }
     if (activeRefEntry && activeRefEntry.invariants.length > 0) {
       details.push({
         label: 'required',
@@ -696,8 +704,8 @@ async function executeMigrationStatusCommand(
         severity: 'warn',
         message: 'There are multiple valid migration paths — you must select a target',
         hints: [
-          "Use '--ref <name>' to select a target",
-          "Or 'prisma-next migration ref set <name> <hash>' to create one",
+          "Use '--to <contract>' to select a target",
+          "Or 'prisma-next ref set <name> <hash>' to create one",
         ],
       });
     }
@@ -751,6 +759,12 @@ async function executeMigrationStatusCommand(
     }
   }
 
+  if (fromOverrideHash !== undefined) {
+    markerHash = fromOverrideHash;
+    mode = 'offline';
+    allMarkers = null;
+  }
+
   // Build the aggregate enumeration of contract spaces. Lossy on
   // failure (extensions are simply omitted) so the existing
   // single-space app pipeline below still runs even if extensions
@@ -863,7 +877,7 @@ async function executeMigrationStatusCommand(
       code: 'MIGRATION.NO_MARKER',
       severity: 'warn',
       message: 'Database has not been initialized — no migration marker found',
-      hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
+      hints: ["Run 'prisma-next migrate' to apply pending migrations"],
     });
   }
 
@@ -923,7 +937,7 @@ async function executeMigrationStatusCommand(
   let missingInvariants: readonly string[] | undefined;
   let effectiveRequired = new Set<string>();
   if (mode === 'online') {
-    // Mirrors `migration-apply.ts`: compute `effectiveRequired = required −
+    // Mirrors `migrate.ts`: compute `effectiveRequired = required −
     // marker.invariants` directly, then derive the display fields from it.
     // `appliedInvariants` is the intersection (`required ∩ marker`), which
     // is what JSON consumers see for the active ref; the unfiltered set
@@ -945,17 +959,17 @@ async function executeMigrationStatusCommand(
   if (mode === 'online') {
     if (markerHash !== undefined && !graph.nodes.has(markerHash) && markerHash === contractHash) {
       summary = `${bundles.length} migration(s) on disk`;
-    } else if (activeRefHash && markerHash !== undefined) {
-      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName!);
+    } else if (activeRefHash && activeRefName && markerHash !== undefined) {
+      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName);
       summary = hasInvariantWork ? `${distance} — missing invariant(s): ${missingList}` : distance;
     } else if (pendingCount === 0 && !hasInvariantWork) {
       summary = `Database is up to date (${appliedCount} migration${appliedCount !== 1 ? 's' : ''} applied)`;
     } else if (pendingCount === 0 && hasInvariantWork) {
-      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply`;
+      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migrate --to ${activeRefName ?? '<ref>'}' to apply`;
     } else if (markerHash === undefined) {
       summary = `${pendingCount} pending migration(s) — database has no marker`;
     } else {
-      summary = `${pendingCount} pending migration(s) — run 'prisma-next migration apply' to apply`;
+      summary = `${pendingCount} pending migration(s) — run 'prisma-next migrate' to apply`;
     }
   } else {
     summary = `${entries.length} migration(s) on disk`;
@@ -997,8 +1011,7 @@ async function executeMigrationStatusCommand(
       diagnostics.push({
         code: 'MIGRATION.MARKER_NOT_IN_HISTORY',
         severity: 'warn',
-        message:
-          'Database matches the current contract but was updated directly (not via migration apply)',
+        message: 'Database matches the current contract but was updated directly (not via migrate)',
         hints: ["Run 'prisma-next migration plan' to plan a migration to your current contract"],
       });
     } else if (pendingCount > 0) {
@@ -1006,7 +1019,7 @@ async function executeMigrationStatusCommand(
         code: 'MIGRATION.DATABASE_BEHIND',
         severity: 'info',
         message: `${pendingCount} migration(s) pending`,
-        hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
+        hints: ["Run 'prisma-next migrate' to apply pending migrations"],
       });
     } else if (hasInvariantWork) {
       diagnostics.push({
@@ -1014,7 +1027,7 @@ async function executeMigrationStatusCommand(
         severity: 'info',
         message: `Missing required invariant(s): ${missingList}`,
         hints: [
-          `Run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
+          `Run 'prisma-next migrate --to ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
         ],
       });
     } else if (!routingUnreachable) {
@@ -1056,37 +1069,41 @@ export function createMigrationStatusCommand(): Command {
   const command = new Command('status');
   setCommandDescriptions(
     command,
-    'Show migration history and applied status',
-    'Displays the migration history in order. When a database connection\n' +
-      'is available, shows which migrations are applied and which are pending.\n' +
-      'Without a database connection, shows the history from disk only.',
+    'Show migration path and pending status',
+    'Shows which migrations are pending between the database marker and\n' +
+      'the target contract. Requires a database connection for live status.\n' +
+      'Use `migration graph` for topology, `migration log` for history,\n' +
+      'and `migration list` for on-disk enumeration.',
   );
   setCommandExamples(command, [
-    'prisma-next migration status',
     'prisma-next migration status --db $DATABASE_URL',
+    'prisma-next migration status --to production --db $DATABASE_URL',
+  ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration log', oneLiner: 'Show executed migration history' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
   ]);
   addGlobalOptions(command)
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--ref <name>', 'Target ref name from migrations/refs/')
-    .option('--graph', 'Show the full migration graph with all branches')
-    .option('--limit <n>', 'Maximum number of migrations to display (default: 10)')
-    .option('--all', 'Show full history (disables truncation)')
+    .option(
+      '--to <contract>',
+      'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .option(
+      '--from <contract>',
+      'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
+    )
     .action(async (options: MigrationStatusOptions) => {
       const flags = parseGlobalFlags(options);
-
       const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
 
       const result = await executeMigrationStatusCommand(options, flags, ui);
 
       const exitCode = handleResult(result, flags, ui, (statusResult) => {
         if (flags.json) {
-          // Strip non-JSON-shape fields before emitting. These belong to
-          // the in-memory result so the human renderer can avoid
-          // recomputing them, but they would either bloat the wire format
-          // (graph, bundles, edgeStatuses) or expose internals
-          // (activeRefHash, activeRefName, diverged) that consumers should
-          // read off `pathDecision` / `refs` instead.
           const {
             graph: _graph,
             bundles: _bundles,
@@ -1101,7 +1118,6 @@ export function createMigrationStatusCommand(): Command {
           const colorize = flags.color !== false;
 
           if (statusResult.graph) {
-            const limit = determineLimit(options);
             const renderInput = migrationGraphToRenderInput({
               graph: statusResult.graph,
               mode: statusResult.mode,
@@ -1113,16 +1129,13 @@ export function createMigrationStatusCommand(): Command {
               edgeStatuses: statusResult.edgeStatuses,
             });
 
-            const graphToRender =
-              options.graph || statusResult.diverged
-                ? renderInput.graph
-                : extractRelevantSubgraph(renderInput.graph, renderInput.relevantPaths);
-            const dagreOptions =
-              !options.graph && isLinearGraph(graphToRender) ? { ranksep: 1 } : undefined;
+            const graphToRender = statusResult.diverged
+              ? renderInput.graph
+              : extractRelevantSubgraph(renderInput.graph, renderInput.relevantPaths);
+            const dagreOptions = isLinearGraph(graphToRender) ? { ranksep: 1 } : undefined;
             const renderOptions = {
               ...renderInput.options,
               colorize,
-              ...ifDefined('limit', limit),
               ...ifDefined('dagreOptions', dagreOptions),
             };
             const graphOutput = graphRenderer.render(graphToRender, renderOptions);
@@ -1209,7 +1222,7 @@ export function formatStatusSummary(result: MigrationStatusResult, colorize: boo
     if (total > 0) {
       lines.push('');
       lines.push(
-        `${c(yellow, '⧗')} ${total} pending migration(s) across ${result.spaces.length} space(s) — run 'prisma-next migration apply' to apply`,
+        `${c(yellow, '⧗')} ${total} pending migration(s) across ${result.spaces.length} space(s) — run 'prisma-next migrate' to apply`,
       );
     }
   }

package/src/commands/{migration-ref.ts → ref.ts}

@@ -1,8 +1,8 @@
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
   deleteRef,
-  readRef,
   readRefs,
   validateRefName,
   validateRefValue,
@@ -16,9 +16,11 @@ import {
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  loadMigrationPackages,
   resolveMigrationPaths,
   setCommandDescriptions,
 } from '../utils/command-helpers';
@@ -34,13 +36,6 @@ interface RefSetResult {
   readonly invariants: readonly string[];
 }
 
-interface RefGetResult {
-  readonly ok: true;
-  readonly ref: string;
-  readonly hash: string;
-  readonly invariants: readonly string[];
-}
-
 interface RefDeleteResult {
   readonly ok: true;
   readonly ref: string;
@@ -66,53 +61,42 @@ function cliErrorInvalidRefName(name: string): CliStructuredError {
   });
 }
 
-function cliErrorInvalidRefValue(hash: string): CliStructuredError {
-  return errorRuntime(`Invalid contract hash "${hash}"`, {
-    why: `"${hash}" is not a valid contract hash`,
-    fix: 'Contract hashes must match the format "sha256:<64 hex chars>". Copy the hash from `prisma-next contract emit` or `migration status --json`.',
-  });
-}
-
-async function executeRefSetCommand(
+export async function executeRefSetCommand(
   name: string,
-  hash: string,
+  contractInput: string,
   options: { config?: string },
 ): Promise<Result<RefSetResult, CliStructuredError>> {
   if (!validateRefName(name)) {
     return notOk(cliErrorInvalidRefName(name));
   }
-  if (!validateRefValue(hash)) {
-    return notOk(cliErrorInvalidRefValue(hash));
-  }
 
   try {
     const config = await loadConfig(options.config);
-    const { refsDir } = resolveMigrationPaths(options.config, config);
-    const entry: RefEntry = { hash, invariants: [] };
+    const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+
+    let resolvedHash: string;
+    if (validateRefValue(contractInput)) {
+      resolvedHash = contractInput;
+    } else {
+      const { graph } = await loadMigrationPackages(appMigrationsDir);
+      const refs = await readRefs(refsDir);
+      const refResult = parseContractRef(contractInput, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      resolvedHash = refResult.value.hash;
+    }
+
+    const entry: RefEntry = { hash: resolvedHash, invariants: [] };
     await writeRef(refsDir, name, entry);
-    return ok({ ok: true as const, ref: name, hash, invariants: [] });
-  } catch (error) {
-    if (error instanceof CliStructuredError) return notOk(error);
-    return notOk(mapError(error));
-  }
-}
-
-async function executeRefGetCommand(
-  name: string,
-  options: { config?: string },
-): Promise<Result<RefGetResult, CliStructuredError>> {
-  try {
-    const config = await loadConfig(options.config);
-    const { refsDir } = resolveMigrationPaths(options.config, config);
-    const entry = await readRef(refsDir, name);
-    return ok({ ok: true as const, ref: name, hash: entry.hash, invariants: entry.invariants });
+    return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
     return notOk(mapError(error));
   }
 }
 
-async function executeRefDeleteCommand(
+export async function executeRefDeleteCommand(
   name: string,
   options: { config?: string },
 ): Promise<Result<RefDeleteResult, CliStructuredError>> {
@@ -127,7 +111,7 @@ async function executeRefDeleteCommand(
   }
 }
 
-async function executeRefListCommand(options: {
+export async function executeRefListCommand(options: {
   config?: string;
 }): Promise<Result<RefListResult, CliStructuredError>> {
   try {
@@ -145,12 +129,15 @@ function createRefSetCommand(): Command {
   const command = new Command('set');
   setCommandDescriptions(
     command,
-    'Set a ref to a contract hash',
-    'Sets a named ref to point to a contract hash in migrations/refs/.',
+    'Set a ref to a contract reference',
+    'Sets a named ref to point to a resolved contract reference (hash, alias, or path) in migrations/refs/.',
   );
   addGlobalOptions(command)
     .argument('<name>', 'Ref name (e.g., staging, production)')
-    .argument('<hash>', 'Contract hash to point to')
+    .argument(
+      '<contract>',
+      'Contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(
       async (
@@ -174,37 +161,6 @@ function createRefSetCommand(): Command {
   return command;
 }
 
-function createRefGetCommand(): Command {
-  const command = new Command('get');
-  setCommandDescriptions(
-    command,
-    'Get the hash for a ref',
-    'Reads a named ref from migrations/refs/ and prints its contract hash.',
-  );
-  addGlobalOptions(command)
-    .argument('<name>', 'Ref name to look up')
-    .option('--config <path>', 'Path to prisma-next.config.ts')
-    .action(
-      async (
-        name: string,
-        options: { config?: string; json?: string | boolean; quiet?: boolean },
-      ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
-        const result = await executeRefGetCommand(name, options);
-        const exitCode = handleResult(result, flags, ui, (value) => {
-          if (flags.json) {
-            ui.output(JSON.stringify(value));
-          } else {
-            ui.output(value.hash);
-          }
-        });
-        process.exit(exitCode);
-      },
-    );
-  return command;
-}
-
 function createRefDeleteCommand(): Command {
   const command = new Command('delete');
   setCommandDescriptions(command, 'Delete a ref', 'Removes a named ref from migrations/refs/.');
@@ -262,20 +218,11 @@ function createRefListCommand(): Command {
   return command;
 }
 
-export {
-  cliErrorInvalidRefName,
-  cliErrorInvalidRefValue,
-  executeRefDeleteCommand,
-  executeRefGetCommand,
-  executeRefListCommand,
-  executeRefSetCommand,
-};
-
-export function createMigrationRefCommand(): Command {
+export function createRefCommand(): Command {
   const command = new Command('ref');
   setCommandDescriptions(
     command,
-    'Manage migration refs',
+    'Manage contract refs',
     'Manage named refs in migrations/refs/. Refs map logical environment\n' +
       'names (e.g., staging, production) to contract hashes.',
   );
@@ -284,7 +231,6 @@ export function createMigrationRefCommand(): Command {
     subcommandDescription: () => '',
   });
   command.addCommand(createRefSetCommand());
-  command.addCommand(createRefGetCommand());
   command.addCommand(createRefDeleteCommand());
   command.addCommand(createRefListCommand());
   return command;

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

@@ -49,7 +49,7 @@ export interface ApplyAggregateInputs<TFamilyId extends string, TTargetId extend
    * Per-space plans, keyed by `spaceId`. Produced by either the full
    * {@link planAggregate} pipeline (`db init` / `db update` — synth
    * for the app, graph-walk for extensions) or by direct
-   * {@link graphWalkStrategy} calls (`migration apply` — graph-walk
+   * {@link graphWalkStrategy} calls (`migrate` — graph-walk
    * for every member). Either way, the runner consumes the same shape.
    */
   readonly perSpacePlans: ReadonlyMap<string, AggregatePerSpacePlan>;
@@ -100,7 +100,7 @@ export type ApplyAggregateResult = Result<ApplyAggregateValue, AggregateApplyRun
 
 /**
  * Runner-driving tail shared by every aggregate apply caller — `db init`,
- * `db update`, and `migration apply`. Consumes already-resolved per-space
+ * `db update`, and `migrate`. Consumes already-resolved per-space
  * plans (the planner-vs-replay distinction is owned by the caller) and
  * dispatches them to the multi-space runner in canonical order.
  *
@@ -264,7 +264,7 @@ export function collectOrdered(
 /**
  * Action-appropriate label for the `spanStart` event the apply
  * primitive emits. `applyAggregate` is shared by `db init`, `db update`,
- * and `migration apply`; the span label tracks the user-visible action
+ * and `migrate`; the span label tracks the user-visible action
  * so structured-progress output reads naturally for each surface.
  */
 export function progressLabelForAction(action: AggregateApplyAction): string {
@@ -285,6 +285,6 @@ function labelForAction(action: AggregateApplyAction): string {
     case 'dbUpdate':
       return 'db update';
     case 'migrationApply':
-      return 'migration apply';
+      return 'migrate';
   }
 }

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

@@ -207,9 +207,10 @@ export async function executeAggregateApply<TFamilyId extends string, TTargetId
 
   // 5. Apply mode: hand off to the shared `applyAggregate` primitive.
   // The runner-driving tail is identical for `db init` / `db update` /
-  // `migration apply` — only how each caller produces `perSpacePlans`
+  // `migrate` — only how each caller produces `perSpacePlans`
   // differs (synth + graph-walk via planAggregate here; graph-walk
-  // only for migration apply). See M6 sub-spec § Required changes 1.
+  // only for migrate). Each caller produces perSpacePlans differently;
+  // this helper handles the shared apply tail.
   const applied = await applyAggregate({
     aggregate,
     perSpacePlans: planResult.value.perSpace,

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

@@ -34,7 +34,7 @@ import type {
 import { applyAggregate, buildPerSpaceBreakdown } from './apply-aggregate';
 
 /**
- * Inputs for the aggregate-walking `migration apply` control-api
+ * Inputs for the aggregate-walking `migrate` control-api
  * operation.
  *
  * The CLI command resolves the descriptor surface (config, refs,
@@ -110,7 +110,8 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
  *    shared with `db init` / `db update`). Marker advancement is
  *    inside the per-space transaction.
  *
- * Sub-spec § `migration apply` semantics + § Required changes 1.
+ * Encodes the replay-only contract: every contract space must have an
+ * authored migration graph on disk before this operation can advance it.
  */
 export async function executeMigrationApply<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteMigrationApplyOptions<TFamilyId, TTargetId>,
@@ -461,7 +462,7 @@ function buildNeverPlannedFailure(spaceId: string, targetHash: string): Migratio
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary: `No on-disk migrations for contract space "${spaceId}"`,
-    why: `migration apply is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}". Run \`prisma-next migration plan\` first to materialise the path.`,
+    why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}". Run \`prisma-next migration plan\` first to materialise the path.`,
     meta: { spaceId, target: targetHash, kind: 'neverPlanned' },
   };
 }

package/src/control-api/types.ts

@@ -2,7 +2,7 @@ import type {
   ContractSourceDiagnostics,
   ContractSourceProvider,
 } from '@prisma-next/config/config-types';
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -590,7 +590,6 @@ export interface MigrationApplyStep {
   readonly dirName: string;
   readonly from: string | null;
   readonly to: string;
-  readonly toContract: Contract;
   readonly operations: readonly MigrationPlanOperation[];
   /**
    * Sorted, deduplicated invariant ids from `migration.json.providedInvariants`.

package/src/migration-cli.ts

@@ -3,7 +3,7 @@
  * `node migration.ts` directly.
  *
  * Naming: this is *not* a "migration runner" in the apply-time sense. The
- * apply-time runner is the thing `prisma-next migration apply` uses to
+ * apply-time runner is the thing `prisma-next migrate` uses to
  * execute migration JSON ops against a database. `MigrationCLI` is the
  * tiny CLI surface owned by an authored `migration.ts` file: parse the
  * file's argv, load the project's `prisma-next.config.ts`, assemble a

package/src/utils/cli-errors.ts

@@ -25,6 +25,7 @@ import {
 } from '@prisma-next/errors/control';
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -85,3 +86,39 @@ export function mapMigrationToolsError(error: MigrationToolsError): CliStructure
     meta: { code: error.code, ...(error.details ?? {}) },
   });
 }
+
+/**
+ * Maps a `RefResolutionError` from the contract/migration reference
+ * resolver into a CLI structured error envelope.
+ */
+export function mapRefResolutionError(error: RefResolutionError): CliStructuredError {
+  switch (error.kind) {
+    case 'not-found':
+      return errorRuntime(`Not a known ${error.grammar} reference: "${error.input}"`, {
+        why: `No ${error.grammar} matching "${error.input}" exists in the migration graph or refs index.`,
+        fix:
+          error.grammar === 'contract'
+            ? 'Provide a valid contract hash, ref name, or migration directory name.'
+            : 'Provide a valid migration directory name or migration hash.',
+        meta: { input: error.input, grammar: error.grammar },
+      });
+    case 'ambiguous':
+      return errorRuntime(`Ambiguous ${error.grammar} reference: "${error.input}"`, {
+        why: `"${error.input}" matches multiple ${error.grammar}s: ${error.candidates.join(', ')}`,
+        fix: 'Provide a longer prefix or use the full hash to disambiguate.',
+        meta: { input: error.input, candidates: error.candidates, grammar: error.grammar },
+      });
+    case 'wrong-grammar':
+      return errorRuntime(error.message, {
+        why: error.message,
+        fix: error.fix,
+        meta: { input: error.input, expectedGrammar: error.expectedGrammar },
+      });
+    case 'invalid-format':
+      return errorRuntime(`Invalid reference format: "${error.input}"`, {
+        why: error.reason,
+        fix: 'Provide a valid contract hash, ref name, or migration directory name.',
+        meta: { input: error.input },
+      });
+  }
+}