@prisma-next/cli 0.12.0 → 0.13.0-dev.1

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

@@ -1,6 +1,7 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
+  ControlAdapterInstance,
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlFamilyInstance,
@@ -9,7 +10,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,
@@ -26,6 +27,7 @@ const DB_UPDATE_POLICY = {
  */
 export interface ExecuteDbUpdateOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterInstance<TFamilyId, TTargetId>;
   readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   readonly contract: Contract;
   readonly mode: 'plan' | 'apply';
@@ -56,6 +58,7 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
 ): Promise<DbUpdateResult> {
   const sharedInputs = {
     driver: options.driver,
+    adapter: options.adapter,
     familyInstance: options.familyInstance,
     contract: options.contract,
     migrations: options.migrations,
@@ -71,7 +74,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 +88,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/db-verify.ts

@@ -8,11 +8,12 @@ import type {
 } from '@prisma-next/framework-components/control';
 import {
   type ContractSpaceMember,
+  collectAggregateNamespaces,
   requireHeadRef,
   type VerifierOutput,
   verifyMigration,
 } from '@prisma-next/migration-tools/aggregate';
-import { castAs } from '@prisma-next/utils/casts';
+import { blindCast, castAs } from '@prisma-next/utils/casts';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { CliStructuredError } from '../../utils/cli-errors';
 import {
@@ -101,7 +102,12 @@ export async function executeDbVerify<TFamilyId extends string, TTargetId extend
   const markersBySpaceId = await familyInstance.readAllMarkers({ driver });
   const schemaIntrospection = skipSchema
     ? null
-    : await runIntrospection({ driver, familyInstance, onProgress });
+    : await runIntrospection({
+        driver,
+        familyInstance,
+        onProgress,
+        contract: collectAggregateNamespaces(aggregate),
+      });
 
   emitVerifySpan(onProgress, 'spanStart');
   const verifyResult = verifyMigration({
@@ -130,8 +136,9 @@ async function runIntrospection<TFamilyId extends string, TTargetId extends stri
   driver: ControlDriverInstance<TFamilyId, TTargetId>;
   familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
   onProgress: OnControlProgress | undefined;
+  contract: unknown;
 }): Promise<unknown> {
-  const { driver, familyInstance, onProgress } = args;
+  const { driver, familyInstance, onProgress, contract } = args;
   onProgress?.({
     action: 'dbVerify',
     kind: 'spanStart',
@@ -139,7 +146,7 @@ async function runIntrospection<TFamilyId extends string, TTargetId extends stri
     label: 'Introspecting database schema',
   });
   try {
-    const result = await familyInstance.introspect({ driver });
+    const result = await familyInstance.introspect({ driver, contract });
     onProgress?.({
       action: 'dbVerify',
       kind: 'spanEnd',
@@ -179,7 +186,10 @@ export function createPerMemberVerifier<TFamilyId extends string, TTargetId exte
       // The family's `TSchemaIR` is opaque to migration-tools; the
       // aggregate verifier passes through whatever we hand it. The
       // family expects its own IR shape on the way back.
-      schema: projectedSchema as never,
+      schema: blindCast<
+        never,
+        'family TSchemaIR is opaque to migration-tools; projectedSchema is passed straight through'
+      >(projectedSchema),
       strict: verifyMode === 'strict',
       frameworkComponents,
     });

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 {
@@ -7,6 +11,7 @@ import type {
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
 import {
+  buildSynthMigrationEdge,
   type ContractMarkerRecordLike,
   type ContractSpaceAggregate,
   type ContractSpaceMember,
@@ -24,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
@@ -42,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). */
@@ -95,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,
@@ -151,58 +156,36 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     // The aggregate passed the integrity gate, so every member's head ref
     // is resolved (the app's is synthesised from the live contract).
     const headRef = requireHeadRef(member);
-    const targetHash = isAppMember && refHash !== undefined ? refHash : headRef.hash;
+    const memberTargetHash = isAppMember && refHash !== undefined ? refHash : headRef.hash;
+    const memberRefInvariants = isAppMember && refHash !== undefined ? refInvariants : undefined;
     const liveMarker = markerRows.get(member.spaceId) ?? null;
 
-    // Empty-graph members fail loudly: replay needs an on-disk path
-    // and an empty graph means the user has never planned this space.
-    if (member.graph().nodes.size === 0) {
-      // Edge case: target == EMPTY (greenfield, nothing to do) or
-      // the live marker already matches the target. Loader integrity
-      // allows this for extensions whose head ref is the empty
-      // sentinel. Record a zero-op resolution so the aggregate result
-      // still surfaces the member in `perSpace[]` as already-at-head;
-      // the runner is not invoked for these members because they have
-      // no authored ops and (for greenfield extensions) no marker to
-      // advance.
-      const liveHash = liveMarker?.storageHash;
-      if (
-        targetHash === liveHash ||
-        (liveHash === undefined && targetHash === EMPTY_CONTRACT_HASH)
-      ) {
-        atHeadResolutions.set(
-          member.spaceId,
-          buildAtHeadResolution({
-            aggregateTargetId: aggregate.targetId,
-            member,
-            targetHash,
-            liveMarker,
-          }),
-        );
-        continue;
-      }
-      return notOk(buildNeverPlannedFailure(member.spaceId, targetHash));
-    }
-
-    const targetInvariants =
-      isAppMember && refHash !== undefined && refInvariants !== undefined
-        ? refInvariants
-        : headRef.invariants;
-    const targetMember: ContractSpaceMember =
-      targetHash === headRef.hash && targetInvariants === headRef.invariants
-        ? member
-        : { ...member, headRef: { hash: targetHash, invariants: targetInvariants } };
-
-    const walked = graphWalkStrategy({
-      aggregateTargetId: aggregate.targetId,
-      member: targetMember,
-      currentMarker: liveMarker,
-      ...(isAppMember && refName !== undefined ? { refName } : {}),
+    const outcome = planMemberPath({
+      member,
+      aggregate,
+      targetHash: memberTargetHash,
+      refInvariants: memberRefInvariants,
+      liveMarker,
+      ...(isAppMember ? { refName } : {}),
     });
-    if (walked.kind === 'unreachable') {
-      return notOk(buildPathNotFoundFailure(member.spaceId, liveMarker, targetHash));
+
+    if (outcome.kind === 'at-head') {
+      // Empty-graph member whose live marker already matches the target.
+      // Kept out of the runner schedule so we don't write spurious markers
+      // for greenfield extensions, but merged back into the success envelope
+      // so every loaded member is represented.
+      atHeadResolutions.set(member.spaceId, outcome.plan);
+      continue;
+    }
+    if (outcome.kind === 'never-planned') {
+      return notOk(buildNeverPlannedFailure(outcome.spaceId, outcome.targetHash));
+    }
+    if (outcome.kind === 'unreachable') {
+      return notOk(
+        buildPathNotFoundFailure(outcome.spaceId, outcome.liveMarker, outcome.targetHash),
+      );
     }
-    if (walked.kind === 'unsatisfiable') {
+    if (outcome.kind === 'unsatisfiable') {
       // Surface the canonical MIGRATION.NO_INVARIANT_PATH envelope
       // (the error rendering pipeline maps it to meta.code +
       // meta.required + meta.missing + meta.structuralPath that the
@@ -213,10 +196,12 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
       // string here would leave the structural lookup with a hash that
       // is never a graph node, producing an empty `structuralPath` and
       // a less actionable diagnostic.
-      const fromHash = liveMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
-      const structural = findPathWithDecision(targetMember.graph(), fromHash, targetHash, {
-        required: new Set<string>(),
-      });
+      const structural = findPathWithDecision(
+        outcome.targetMember.graph(),
+        outcome.liveHash,
+        memberTargetHash,
+        { required: new Set<string>() },
+      );
       const structuralPath =
         structural.kind === 'ok'
           ? structural.decision.selectedPath.map((edge) => ({
@@ -228,14 +213,14 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
             }))
           : [];
       throw errorNoInvariantPath({
-        ...(isAppMember && refName !== undefined ? { refName } : {}),
-        required: targetInvariants,
-        missing: walked.missing,
+        ...(outcome.refName !== undefined ? { refName: outcome.refName } : {}),
+        required: outcome.targetInvariants,
+        missing: outcome.missing,
         structuralPath,
       });
     }
 
-    perSpacePlans.set(member.spaceId, walked.result);
+    perSpacePlans.set(member.spaceId, outcome.plan);
   }
 
   const canonicalOrder = [...aggregate.extensions.map((m) => m.spaceId), aggregate.app.spaceId];
@@ -276,7 +261,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     );
   }
 
-  const applied = await applyMigration({
+  const applied = await runMigration({
     aggregate,
     perSpacePlans,
     applyOrder,
@@ -285,12 +270,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,
@@ -319,7 +304,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     includeMarkers: true,
   });
   const totalMigrationsApplied = applied.value.orderedResolutions.reduce(
-    (sum, r) => sum + (r.entry.migrationEdges?.length ?? 0),
+    (sum, r) => sum + r.entry.migrationEdges.length,
     0,
   );
   const summary = `Applied ${totalMigrationsApplied} migration(s) (${applied.value.totalOpsExecuted} operation(s)) across ${orderedAll.length} contract space(s)`;
@@ -335,6 +320,119 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
   );
 }
 
+/**
+ * Outcome variants for one member's path computation.
+ *
+ * Callers switch on `kind` and map to their own error representation:
+ * `executeMigrate` throws / returns `notOk`; `executeMigrateShowCommand`
+ * returns a CLI structured error. The shared discriminant guarantees both
+ * paths feed `graphWalkStrategy` the same inputs.
+ *
+ * @internal Exported for `executeMigrateShowCommand` to call.
+ */
+export type MemberPathOutcome =
+  | { readonly kind: 'ok'; readonly plan: PerSpacePlan }
+  | { readonly kind: 'at-head'; readonly plan: PerSpacePlan }
+  | { readonly kind: 'never-planned'; readonly spaceId: string; readonly targetHash: string }
+  | {
+      readonly kind: 'unreachable';
+      readonly spaceId: string;
+      readonly liveMarker: ContractMarkerRecordLike | null;
+      readonly targetHash: string;
+    }
+  | {
+      readonly kind: 'unsatisfiable';
+      readonly spaceId: string;
+      readonly isAppMember: boolean;
+      readonly missing: readonly string[];
+      readonly targetInvariants: readonly string[];
+      readonly targetMember: ContractSpaceMember;
+      readonly liveHash: string;
+      readonly refName: string | undefined;
+    };
+
+/**
+ * Compute the graph-walk path for one contract-space member.
+ *
+ * Encapsulates the invariant-correct input assembly that both
+ * `executeMigrate` and `executeMigrateShowCommand` must use:
+ * - `currentMarker` carries the full live marker including `invariants`
+ *   (not a stripped `{ storageHash, invariants: [] }` shell).
+ * - `targetInvariants` uses the caller-supplied `refInvariants` when a
+ *   `--to` ref was resolved (not always the file head ref's invariants).
+ *
+ * Both callers map the returned `MemberPathOutcome` to their own error
+ * representation; the path-compute logic is shared and identical.
+ *
+ * @internal Exported for `executeMigrateShowCommand`.
+ */
+export function planMemberPath({
+  member,
+  aggregate,
+  targetHash,
+  refInvariants,
+  liveMarker,
+  refName,
+}: {
+  readonly member: ContractSpaceMember;
+  readonly aggregate: Pick<ContractSpaceAggregate, 'targetId' | 'app'>;
+  readonly targetHash: string;
+  readonly refInvariants: readonly string[] | undefined;
+  readonly liveMarker: ContractMarkerRecordLike | null;
+  readonly refName?: string;
+}): MemberPathOutcome {
+  const isAppMember = member.spaceId === aggregate.app.spaceId;
+  const headRef = requireHeadRef(member);
+
+  if (member.graph().nodes.size === 0) {
+    const liveHash = liveMarker?.storageHash;
+    if (targetHash === liveHash || (liveHash === undefined && targetHash === EMPTY_CONTRACT_HASH)) {
+      return {
+        kind: 'at-head',
+        plan: buildAtHeadResolution({
+          aggregateTargetId: aggregate.targetId,
+          member,
+          targetHash,
+          liveMarker,
+        }),
+      };
+    }
+    return { kind: 'never-planned', spaceId: member.spaceId, targetHash };
+  }
+
+  const targetInvariants =
+    isAppMember && refInvariants !== undefined ? refInvariants : headRef.invariants;
+  const targetMember: ContractSpaceMember =
+    targetHash === headRef.hash && targetInvariants === headRef.invariants
+      ? member
+      : { ...member, headRef: { hash: targetHash, invariants: targetInvariants } };
+
+  const walked = graphWalkStrategy({
+    aggregateTargetId: aggregate.targetId,
+    member: targetMember,
+    currentMarker: liveMarker,
+    ...(isAppMember && refName !== undefined ? { refName } : {}),
+  });
+
+  if (walked.kind === 'unreachable') {
+    return { kind: 'unreachable', spaceId: member.spaceId, liveMarker, targetHash };
+  }
+  if (walked.kind === 'unsatisfiable') {
+    const liveHash = liveMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
+    return {
+      kind: 'unsatisfiable',
+      spaceId: member.spaceId,
+      isAppMember,
+      missing: walked.missing,
+      targetInvariants,
+      targetMember,
+      liveHash,
+      refName,
+    };
+  }
+  return { kind: 'ok', plan: walked.result };
+}
+
 /**
  * Build a zero-op {@link PerSpacePlan} for an empty-graph
  * member whose live marker already matches the target. Lets the apply
@@ -361,7 +459,13 @@ function buildAtHeadResolution(args: {
     displayOps: [],
     destinationContract: member.contract(),
     strategy: 'graph-walk',
-    migrationEdges: [],
+    migrationEdges: [
+      buildSynthMigrationEdge({
+        currentMarkerStorageHash: liveMarker?.storageHash,
+        destinationStorageHash: targetHash,
+        operationCount: 0,
+      }),
+    ],
   };
 }
 
@@ -389,9 +493,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,
@@ -404,7 +508,7 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
   // JSON-shape consumers (e.g. `parsed.applied.length` in integration
   // tests). The aggregate per-space breakdown lives on `perSpace[]`.
   const applied = args.orderedResolutions.flatMap((r) => {
-    const edges = r.entry.migrationEdges ?? [];
+    const edges = r.entry.migrationEdges;
     return edges.map((edge) => ({
       spaceId: r.spaceId,
       dirName: edge.dirName,
@@ -416,7 +520,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,
@@ -455,10 +559,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}"`,
@@ -481,7 +582,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),
   });
 
@@ -141,6 +146,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
     destinationContract: r.entry.destinationContract,
     policy,
     frameworkComponents,
+    migrationEdges: r.entry.migrationEdges,
     // Per-space post-apply schema verification is non-strict: each
     // space's `destinationContract` describes only its own slice; a
     // strict verifier would treat every other space's tables as
@@ -151,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),
@@ -162,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,
@@ -194,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(
@@ -243,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';
   }
 }