@prisma-next/cli 0.12.0-dev.33 → 0.12.0-dev.35

package/src/commands/migrate.ts

@@ -11,8 +11,8 @@ import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import type {
-  MigrationApplyFailure,
-  MigrationApplyPathDecision,
+  MigrateFailure,
+  MigratePathDecision,
   PerSpaceExecutionEntry,
 } from '../control-api/types';
 import {
@@ -76,14 +76,14 @@ export interface MigrateResult {
   }[];
   readonly summary: string;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
-  readonly pathDecision?: MigrationApplyPathDecision;
+  readonly pathDecision?: MigratePathDecision;
   readonly timings: {
     readonly total: number;
   };
   readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
 }
 
-function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
+function mapApplyFailure(failure: MigrateFailure): CliStructuredErrorType {
   if (failure.code === 'MIGRATION_PATH_NOT_FOUND') {
     return errorPathUnreachable(failure);
   }
@@ -136,7 +136,7 @@ async function executeMigrateCommand(
 
   // Construct the family instance up-front so the on-disk contract read
   // crosses the serializer seam (`familyInstance.deserializeContract`) at
-  // the read site. The downstream `client.migrationApply({ contract })`
+  // the read site. The downstream `client.migrate({ contract })`
   // re-validates internally (no harm — validation is idempotent), but
   // closing the gap at the read site is what makes the cast-pattern
   // lint enforceable and matches the other CLI commands. See TML-2536.
@@ -312,7 +312,7 @@ async function executeMigrateCommand(
       }
     }
 
-    const applyResult = await client.migrationApply({
+    const applyResult = await client.migrate({
       contract: applyContract,
       migrationsDir,
       ...ifDefined('refHash', refEntry?.hash),

package/src/control-api/client.ts

@@ -33,7 +33,7 @@ import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
 import { executeDbUpdate } from './operations/db-update';
 import { type ExecuteDbVerifyResult, executeDbVerify } from './operations/db-verify';
-import { executeMigrationApply } from './operations/migration-apply';
+import { executeMigrate } from './operations/migrate';
 
 import type {
   ControlActionName,
@@ -47,8 +47,8 @@ import type {
   EmitOptions,
   EmitResult,
   IntrospectOptions,
-  MigrationApplyOptions,
-  MigrationApplyResult,
+  MigrateOptions,
+  MigrateResult,
   OnControlProgress,
   SchemaVerifyOptions,
   SignOptions,
@@ -457,9 +457,9 @@ class ControlClientImpl implements ControlClient {
     return familyInstance.readLedger({ driver, ...ifDefined('space', space) });
   }
 
-  async migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult> {
+  async migrate(options: MigrateOptions): Promise<MigrateResult> {
     const { onProgress } = options;
-    await this.connectWithProgress(options.connection, 'migrationApply', onProgress);
+    await this.connectWithProgress(options.connection, 'migrate', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
@@ -474,7 +474,7 @@ class ControlClientImpl implements ControlClient {
       throw new ContractValidationError(message, error);
     }
 
-    return executeMigrationApply({
+    return executeMigrate({
       driver,
       familyInstance,
       contract,

package/src/control-api/operations/db-init.ts

@@ -8,14 +8,14 @@ import type {
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { DbInitResult, OnControlProgress } from '../types';
-import { executeApply } from './db-apply';
+import { executeRun } from './db-run';
 
 /**
  * Options for executing the `db init` operation.
  *
  * `db init` runs the loader → planner → runner pipeline:
  *
- * 1. {@link executeApply} loads a `ContractSpaceAggregate` via
+ * 1. {@link executeRun} loads a `ContractSpaceAggregate` via
  *    {@link import('@prisma-next/migration-tools/aggregate').loadContractSpaceAggregate}
  *    from the supplied descriptor set + on-disk on-disk artefacts.
  * 2. The aggregate planner runs with `callerPolicy.ignoreGraphFor`
@@ -68,7 +68,7 @@ export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extend
 export async function executeDbInit<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteDbInitOptions<TFamilyId, TTargetId>,
 ): Promise<DbInitResult> {
-  const result = await executeApply<TFamilyId, TTargetId>({
+  const result = await executeRun<TFamilyId, TTargetId>({
     driver: options.driver,
     familyInstance: options.familyInstance,
     contract: options.contract,

package/src/control-api/operations/{db-apply.ts → db-run.ts}

@@ -1,3 +1,7 @@
+/**
+ * Backs `db init` / `db update`. Strategy: introspect → planMigration; synth-for-app + graph-walk-extensions; plan-mode + orphan-marker preflight.
+ */
+
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -33,19 +37,19 @@ import type {
   OnControlProgress,
   PerSpaceExecutionEntry,
 } from '../types';
+import { stripOperations } from './migration-helpers';
 import {
-  applyMigration,
   buildPerSpaceBreakdown,
   collectOrdered,
   type OrderedResolution,
-} from './apply';
-import { stripOperations } from './migration-helpers';
+  runMigration,
+} from './run-migration';
 
 /**
- * Span IDs emitted via `onProgress` during the apply flow.
+ * Span IDs emitted via `onProgress` during the run flow.
  * Stable identifiers consumed by the structured-output renderer and by
  * tests asserting on span ids. The `apply` span itself is owned by
- * the {@link applyMigration} primitive — only the introspect / plan
+ * the {@link runMigration} primitive — only the introspect / plan
  * spans are emitted directly here.
  */
 const SPAN_IDS = {
@@ -54,13 +58,13 @@ const SPAN_IDS = {
 } as const;
 
 /**
- * Inputs shared by `db init` and `db update` apply flows.
+ * Inputs shared by `db init` and `db update` run flows.
  *
  * Accepts the already-validated app contract + descriptor list — the
  * loader gathers the rest from disk + descriptors. The CLI is the
  * descriptor-import boundary; everything downstream is descriptor-free.
  */
-export interface ExecuteApplyOptions<TFamilyId extends string, TTargetId extends string> {
+export interface ExecuteRunOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
   readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   readonly contract: Contract;
@@ -98,8 +102,8 @@ export interface ExecuteApplyOptions<TFamilyId extends string, TTargetId extends
  *    transaction across every space; failure on any space rolls back
  *    every space's writes.
  */
-export async function executeApply<TFamilyId extends string, TTargetId extends string>(
-  options: ExecuteApplyOptions<TFamilyId, TTargetId>,
+export async function executeRun<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteRunOptions<TFamilyId, TTargetId>,
 ): Promise<DbInitResult | DbUpdateResult> {
   const {
     driver,
@@ -213,13 +217,13 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
     });
   }
 
-  // 5. Apply mode: hand off to the shared `applyMigration` primitive.
+  // 5. Run mode: hand off to the shared `runMigration` primitive.
   // The runner-driving tail is identical for `db init` / `db update` /
   // `migrate` — only how each caller produces `perSpacePlans`
   // differs (synth + graph-walk via planMigration here; graph-walk
   // only for migrate). Each caller produces perSpacePlans differently;
-  // this helper handles the shared apply tail.
-  const applied = await applyMigration({
+  // this helper handles the shared run tail.
+  const applied = await runMigration({
     aggregate,
     perSpacePlans: planResult.value.perSpace,
     applyOrder: planResult.value.applyOrder,

package/src/control-api/operations/db-update.ts

@@ -9,7 +9,7 @@ import type {
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk } from '@prisma-next/utils/result';
 import type { DbUpdateResult, OnControlProgress } from '../types';
-import { executeApply } from './db-apply';
+import { executeRun } from './db-run';
 
 const DB_UPDATE_POLICY = {
   allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
@@ -71,7 +71,7 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
     const gate = await guardDestructiveChanges<TFamilyId, TTargetId>(sharedInputs);
     if (gate !== null) return gate;
   }
-  return (await executeApply<TFamilyId, TTargetId>({
+  return (await executeRun<TFamilyId, TTargetId>({
     ...sharedInputs,
     mode: options.mode,
   })) as DbUpdateResult;
@@ -85,9 +85,9 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
  * run.
  */
 async function guardDestructiveChanges<TFamilyId extends string, TTargetId extends string>(
-  sharedInputs: Omit<Parameters<typeof executeApply<TFamilyId, TTargetId>>[0], 'mode'>,
+  sharedInputs: Omit<Parameters<typeof executeRun<TFamilyId, TTargetId>>[0], 'mode'>,
 ): Promise<DbUpdateResult | null> {
-  const planResult = (await executeApply<TFamilyId, TTargetId>({
+  const planResult = (await executeRun<TFamilyId, TTargetId>({
     ...sharedInputs,
     mode: 'plan',
   })) as DbUpdateResult;

package/src/control-api/operations/{migration-apply.ts → migrate.ts}

@@ -1,3 +1,7 @@
+/**
+ * Backs the `migrate` command. Strategy: graph-walk-all-members, replay-only (no introspect/synth/planner).
+ */
+
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -25,14 +29,14 @@ import {
   buildContractSpaceAggregate,
 } from '../../utils/contract-space-aggregate-loader';
 import type {
-  MigrationApplyFailure,
-  MigrationApplyPathDecision,
-  MigrationApplyResult,
-  MigrationApplySuccess,
+  MigrateFailure,
+  MigratePathDecision,
+  MigrateResult,
+  MigrateSuccess,
   OnControlProgress,
   PerSpaceExecutionEntry,
 } from '../types';
-import { applyMigration, buildPerSpaceBreakdown } from './apply';
+import { buildPerSpaceBreakdown, runMigration } from './run-migration';
 
 /**
  * Inputs for the aggregate-walking `migrate` control-api
@@ -43,7 +47,7 @@ import { applyMigration, buildPerSpaceBreakdown } from './apply';
  * is the single descriptor-free seam between the CLI and the
  * aggregate runtime.
  */
-export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetId extends string> {
+export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
   readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   /** Already-validated app contract (the canonical "where we are heading" hash). */
@@ -96,16 +100,16 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
  *    marker to `member.headRef.hash` (or `refHash` for the app
  *    member when provided). Empty-graph members fail loudly — a
  *    "never planned" space is a user-error condition for replay.
- * 4. Hand off to {@link applyMigration} (the runner-driving tail
+ * 4. Hand off to {@link runMigration} (the runner-driving tail
  *    shared with `db init` / `db update`). Marker advancement is
  *    inside the per-space transaction.
  *
  * 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>,
-): Promise<MigrationApplyResult> {
+export async function executeMigrate<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteMigrateOptions<TFamilyId, TTargetId>,
+): Promise<MigrateResult> {
   const {
     driver,
     familyInstance,
@@ -277,7 +281,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     );
   }
 
-  const applied = await applyMigration({
+  const applied = await runMigration({
     aggregate,
     perSpacePlans,
     applyOrder,
@@ -286,12 +290,12 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     migrations,
     frameworkComponents,
     policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
-    action: 'migrationApply',
+    action: 'migrate',
     ...ifDefined('onProgress', onProgress),
   });
 
   if (!applied.ok) {
-    const failure: MigrationApplyFailure = {
+    const failure: MigrateFailure = {
       code: 'RUNNER_FAILED',
       summary: applied.failure.summary,
       why: applied.failure.why,
@@ -396,9 +400,9 @@ interface BuildSuccessArgs {
   readonly summary: string;
 }
 
-function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
+function buildSuccess(args: BuildSuccessArgs): MigrateSuccess {
   // The marker hash surfaced at the top level is the **app member's**
-  // post-apply marker (the top-level `markerHash` field).
+  // post-migrate marker (the top-level `markerHash` field).
   // Per-space markers live on `perSpace[].marker.storageHash`.
   const appResolution = args.orderedResolutions.find(
     (r) => r.spaceId === args.aggregate.app.spaceId,
@@ -423,7 +427,7 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
   });
 
   const appPlan = appResolution?.entry;
-  const pathDecision: MigrationApplyPathDecision | undefined = appPlan?.pathDecision
+  const pathDecision: MigratePathDecision | undefined = appPlan?.pathDecision
     ? {
         fromHash: appPlan.pathDecision.fromHash,
         toHash: appPlan.pathDecision.toHash,
@@ -462,10 +466,7 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
  *
  * @internal Exported for testing only.
  */
-export function buildNeverPlannedFailure(
-  spaceId: string,
-  targetHash: string,
-): MigrationApplyFailure {
+export function buildNeverPlannedFailure(spaceId: string, targetHash: string): MigrateFailure {
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary: `No on-disk migrations for contract space "${spaceId}"`,
@@ -488,7 +489,7 @@ export function buildPathNotFoundFailure(
   spaceId: string,
   marker: ContractMarkerRecordLike | null,
   targetHash: string,
-): MigrationApplyFailure {
+): MigrateFailure {
   const fromHash = marker?.storageHash ?? '<empty>';
   // The app-case phrasing names the user-visible condition (a
   // contract has been emitted that no on-disk migration reaches) so

package/src/control-api/operations/{apply.ts → run-migration.ts}

@@ -1,3 +1,8 @@
+/**
+ * Shared runner tail (`runMigration` + `buildPerSpaceBreakdown`/`collectOrdered`).
+ * Backs no command directly; consumed by db-run and migrate.
+ */
+
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
   ControlDriverInstance,
@@ -11,32 +16,32 @@ import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import type { OnControlProgress, PerSpaceExecutionEntry } from '../types';
 
 /**
- * Span id emitted via `onProgress` for the apply phase. Stable
+ * Span id emitted via `onProgress` for the run phase. Stable
  * identifier consumed by the structured-output renderer and by tests.
  */
-const APPLY_SPAN_ID = 'apply' as const;
+const RUN_SPAN_ID = 'apply' as const;
 
 /**
- * Action that originated this apply call. Threaded into `OnControlProgress`
+ * Action that originated this run call. Threaded into `OnControlProgress`
  * events so the parent CLI command can attribute the span correctly,
  * and used to compose action-specific summary phrasing.
  */
-export type ApplyAction = 'dbInit' | 'dbUpdate' | 'migrationApply';
+export type RunAction = 'dbInit' | 'dbUpdate' | 'migrate';
 
 /**
- * Failure variant emitted by {@link applyMigration} when the runner
- * itself rejects the apply. Mirrors the failure shape callers
+ * Failure variant emitted by {@link runMigration} when the runner
+ * itself rejects the run. Mirrors the failure shape callers
  * already wrap into their own action-specific failure envelopes
- * (`DbInitFailure`, `DbUpdateFailure`, `MigrationApplyFailure`) so each
+ * (`DbInitFailure`, `DbUpdateFailure`, `MigrateFailure`) so each
  * caller keeps owning its own discriminated failure code.
  */
-export interface ApplyRunnerFailure {
+export interface RunnerFailure {
   readonly summary: string;
   readonly why?: string;
   readonly meta: Record<string, unknown>;
 }
 
-export interface ApplyMigrationInputs<TFamilyId extends string, TTargetId extends string> {
+export interface RunMigrationInputs<TFamilyId extends string, TTargetId extends string> {
   readonly aggregate: ContractSpaceAggregate;
   /**
    * Per-space plans, keyed by `spaceId`. Produced by either the full
@@ -62,22 +67,22 @@ export interface ApplyMigrationInputs<TFamilyId extends string, TTargetId extend
   >;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   readonly policy: MigrationOperationPolicy;
-  readonly action: ApplyAction;
+  readonly action: RunAction;
   readonly onProgress?: OnControlProgress;
 }
 
 /**
  * Resolved per-space plan in canonical schedule order. Surfaced from
- * {@link applyMigration} to callers so each one can build its own
+ * {@link runMigration} to callers so each one can build its own
  * action-specific success envelope (e.g. `DbInitSuccess` vs
- * `MigrationApplySuccess`) without re-deriving the ordering.
+ * `MigrateSuccess`) without re-deriving the ordering.
  */
 export interface OrderedResolution {
   readonly spaceId: string;
   readonly entry: PerSpacePlan;
 }
 
-export interface ApplyMigrationValue {
+export interface RunMigrationValue {
   readonly orderedResolutions: readonly OrderedResolution[];
   readonly totalOpsPlanned: number;
   readonly totalOpsExecuted: number;
@@ -89,10 +94,10 @@ export interface ApplyMigrationValue {
   readonly perSpace: readonly PerSpaceExecutionEntry[];
 }
 
-export type ApplyMigrationResult = Result<ApplyMigrationValue, ApplyRunnerFailure>;
+export type RunMigrationResult = Result<RunMigrationValue, RunnerFailure>;
 
 /**
- * Runner-driving tail shared by every apply caller — `db init`,
+ * Runner-driving tail shared by every run caller — `db init`,
  * `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 runner in canonical order.
@@ -107,9 +112,9 @@ export type ApplyMigrationResult = Result<ApplyMigrationValue, ApplyRunnerFailur
  * so callers don't have to duplicate it; the `action` field on each
  * progress event is taken from the caller's `action` argument.
  */
-export async function applyMigration<TFamilyId extends string, TTargetId extends string>(
-  inputs: ApplyMigrationInputs<TFamilyId, TTargetId>,
-): Promise<ApplyMigrationResult> {
+export async function runMigration<TFamilyId extends string, TTargetId extends string>(
+  inputs: RunMigrationInputs<TFamilyId, TTargetId>,
+): Promise<RunMigrationResult> {
   const {
     aggregate,
     perSpacePlans,
@@ -130,7 +135,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
   onProgress?.({
     action,
     kind: 'spanStart',
-    spanId: APPLY_SPAN_ID,
+    spanId: RUN_SPAN_ID,
     label: progressLabelForAction(action),
   });
 
@@ -152,7 +157,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
   const runnerResult = await runner.execute({ driver, perSpaceOptions });
 
   if (!runnerResult.ok) {
-    onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'error' });
+    onProgress?.({ action, kind: 'spanEnd', spanId: RUN_SPAN_ID, outcome: 'error' });
     return notOk({
       summary: runnerResult.failure.summary,
       ...ifDefined('why', runnerResult.failure.why),
@@ -163,7 +168,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
       },
     });
   }
-  onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'ok' });
+  onProgress?.({ action, kind: 'spanEnd', spanId: RUN_SPAN_ID, outcome: 'ok' });
 
   const totalOpsPlanned = runnerResult.value.perSpaceResults.reduce(
     (sum, r) => sum + r.value.operationsPlanned,
@@ -195,7 +200,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
  * advances as the last step of each space's transaction) and `false`
  * for plan-mode (no marker has been written yet).
  *
- * Exported alongside {@link applyMigration} so plan-mode callers can
+ * Exported alongside {@link runMigration} so plan-mode callers can
  * assemble the same per-space block without going through the runner.
  */
 export function buildPerSpaceBreakdown(
@@ -244,18 +249,18 @@ export function collectOrdered(
 }
 
 /**
- * Action-appropriate label for the `spanStart` event the apply
- * primitive emits. `applyMigration` is shared by `db init`, `db update`,
+ * Action-appropriate label for the `spanStart` event the run
+ * primitive emits. `runMigration` is shared by `db init`, `db update`,
  * and `migrate`; the span label tracks the user-visible action
  * so structured-progress output reads naturally for each surface.
  */
-export function progressLabelForAction(action: ApplyAction): string {
+export function progressLabelForAction(action: RunAction): string {
   switch (action) {
     case 'dbInit':
       return 'Initialising database across spaces';
     case 'dbUpdate':
       return 'Updating database across spaces';
-    case 'migrationApply':
-      return 'Applying migration plan across spaces';
+    case 'migrate':
+      return 'Running migration plan across spaces';
   }
 }

package/src/control-api/types.ts

@@ -71,7 +71,7 @@ export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
   | 'dbVerify'
-  | 'migrationApply'
+  | 'migrate'
   | 'verify'
   | 'schemaVerify'
   | 'sign'
@@ -540,17 +540,17 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
 // ============================================================================
 
 /**
- * Options for the aggregate-walking `migrationApply` operation.
+ * Options for the aggregate-walking `migrate` operation.
  *
  * The control-api operation is responsible for: loading the
  * contract-space aggregate, reading per-space marker rows from the
  * live database, plotting per-space paths via `graphWalkStrategy`
  * (replay-only — no synth, no introspection), and dispatching
- * through the shared `applyMigration` primitive. The CLI command
+ * through the shared `runMigration` primitive. The CLI command
  * just resolves the descriptor surface (config, refs, contract
  * envelope, app-space migration packages) and hands the inputs in.
  */
-export interface MigrationApplyOptions {
+export interface MigrateOptions {
   /** Already-validated app contract (the canonical "where we are heading" hash). */
   readonly contract: unknown;
   /** Migrations root directory (`migrations/` under the project). */
@@ -575,7 +575,7 @@ export interface MigrationApplyOptions {
    */
   readonly refName?: string;
   /**
-   * Database connection. If provided, migrationApply will connect before executing.
+   * Database connection. If provided, migrate will connect before executing.
    * If omitted, the client must already be connected.
    */
   readonly connection?: unknown;
@@ -619,7 +619,7 @@ export interface MigrationApplyStep {
  * Per-space aggregate detail (markers, ops grouped by space) lives
  * on `perSpace[]`; this list is the per-edge view.
  */
-export interface MigrationApplyAppliedEntry {
+export interface MigrateRanEntry {
   readonly spaceId: string;
   readonly dirName: string;
   readonly migrationHash: string;
@@ -629,13 +629,13 @@ export interface MigrationApplyAppliedEntry {
 }
 
 /**
- * Successful migrationApply result. Carries both the top-level fields
- * (`markerHash` is the **app member's** post-apply marker) and the
+ * Successful migrate result. Carries both the top-level fields
+ * (`markerHash` is the **app member's** post-migrate marker) and the
  * per-space breakdown (`perSpace` — markers / operations in canonical
  * schedule order).
  */
 /**
- * Path-decision summary for the **app member** post-apply. Surfaced
+ * Path-decision summary for the **app member** post-migrate. Surfaced
  * at the top level (and consumed by the cli-journeys suite, which
  * inspects `requiredInvariants`/`satisfiedInvariants`/
  * `selectedPath` to validate invariant routing).
@@ -643,7 +643,7 @@ export interface MigrationApplyAppliedEntry {
  * Per-space path decisions for extension members are not surfaced —
  * extensions own their own ref/invariant control.
  */
-export interface MigrationApplyPathDecision {
+export interface MigratePathDecision {
   readonly fromHash: string;
   readonly toHash: string;
   readonly alternativeCount: number;
@@ -660,10 +660,10 @@ export interface MigrationApplyPathDecision {
   }[];
 }
 
-export interface MigrationApplySuccess {
+export interface MigrateSuccess {
   readonly migrationsApplied: number;
   readonly markerHash: string;
-  readonly applied: readonly MigrationApplyAppliedEntry[];
+  readonly applied: readonly MigrateRanEntry[];
   readonly summary: string;
   /**
    * Per-space breakdown in canonical schedule order (extensions
@@ -674,31 +674,31 @@ export interface MigrationApplySuccess {
   /**
    * Path-decision data for the app member. Present whenever the
    * graph-walk strategy ran for the app (i.e. always for the
-   * aggregate-walking apply path). Absent only for the no-op
+   * aggregate-walking migrate path). Absent only for the no-op
    * "Already up to date" early return when the app has no plan.
    */
-  readonly pathDecision?: MigrationApplyPathDecision;
+  readonly pathDecision?: MigratePathDecision;
 }
 
 /**
- * Failure codes for migrationApply operation.
+ * Failure codes for migrate operation.
  */
-export type MigrationApplyFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
+export type MigrateFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
 
 /**
- * Failure details for migrationApply operation.
+ * Failure details for migrate operation.
  */
-export interface MigrationApplyFailure {
-  readonly code: MigrationApplyFailureCode;
+export interface MigrateFailure {
+  readonly code: MigrateFailureCode;
   readonly summary: string;
   readonly why: string | undefined;
   readonly meta: Record<string, unknown> | undefined;
 }
 
 /**
- * Result type for migrationApply operation.
+ * Result type for migrate operation.
  */
-export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyFailure>;
+export type MigrateResult = Result<MigrateSuccess, MigrateFailure>;
 
 // ============================================================================
 // Standalone Contract Emit Types
@@ -892,17 +892,19 @@ export interface ControlClient {
   readLedger(space?: string): Promise<readonly LedgerEntryRecord[]>;
 
   /**
-   * Applies pre-planned on-disk migrations to the database.
+   * Advances the database along the migration graph to the target contract.
    * Each migration runs in its own transaction with full execution checks.
-   * Resume-safe: re-running after failure picks up from the last applied migration.
+   * Resume-safe: re-running after failure picks up from the last run migration.
    *
-   * @param options.originHash - Explicit source hash for the apply path
-   * @param options.destinationHash - Explicit destination hash for the apply path
-   * @param options.pendingMigrations - Ordered migrations to execute
-   * @returns Result pattern: Ok with applied details, NotOk with failure details
+   * @param options.contract - The target contract to migrate to
+   * @param options.migrationsDir - Root migrations directory (`migrations/` under the project)
+   * @param options.refHash - Optional app-space ref override hash
+   * @param options.refInvariants - Required invariants on the user-supplied ref
+   * @param options.refName - Resolved name of the user-supplied app-space ref
+   * @returns Result pattern: Ok with migration details, NotOk with failure details
    * @throws If not connected, target doesn't support migrations, or infrastructure failure
    */
-  migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult>;
+  migrate(options: MigrateOptions): Promise<MigrateResult>;
 
   /**
    * Introspects the database schema.