@prisma-next/cli 0.12.0-dev.4 → 0.12.0-dev.40

package/src/commands/telemetry/index.ts

@@ -0,0 +1,107 @@
+import { userConfigPath, writeUserConfig } from '@prisma-next/cli-telemetry';
+import { Command } from 'commander';
+import {
+  addGlobalOptions,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../../utils/command-helpers';
+import { formatCommandHelp } from '../../utils/formatters/help';
+import {
+  type CommonCommandOptions,
+  parseGlobalFlags,
+  parseGlobalFlagsOrExit,
+} from '../../utils/global-flags';
+import { isCI } from '../../utils/is-ci';
+import { createTerminalUI } from '../../utils/terminal-ui';
+import { formatTelemetryStatusLines, resolveTelemetryStatus } from './status';
+
+function createTelemetryStatusCommand(): Command {
+  const command = new Command('status');
+  setCommandDescriptions(
+    command,
+    'Show whether anonymous CLI telemetry is enabled and why',
+    'Reports whether telemetry is currently enabled or disabled and the reason\n' +
+      '(default-on, stored opt-out, environment opt-out, or CI), the path to your\n' +
+      'user-level config file, and whether an installation ID has been stored.\n' +
+      'Read-only: never sends an event, never mints an ID, never writes anything.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    const ui = createTerminalUI(flags);
+    const status = resolveTelemetryStatus({ env: process.env, inCI: isCI() });
+    if (flags.json) {
+      ui.output(JSON.stringify(status));
+    } else {
+      for (const line of formatTelemetryStatusLines(status)) {
+        ui.output(line);
+      }
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryEnableCommand(): Command {
+  const command = new Command('enable');
+  setCommandDescriptions(
+    command,
+    'Enable anonymous CLI telemetry',
+    'Stores "enableTelemetry": true in your user-level config and mints an\n' +
+      'installation ID if one is not already stored.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: true });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: true, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry enabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryDisableCommand(): Command {
+  const command = new Command('disable');
+  setCommandDescriptions(
+    command,
+    'Disable anonymous CLI telemetry',
+    'Stores "enableTelemetry": false in your user-level config. No installation\n' +
+      'ID is minted and no event is sent.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: false });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: false, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry disabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+export function createTelemetryCommand(): Command {
+  const command = new Command('telemetry');
+  setCommandDescriptions(
+    command,
+    'Inspect and change anonymous CLI telemetry',
+    'Show telemetry status, or enable / disable anonymous CLI usage data.\n' +
+      'Telemetry is on by default (opt-out); see https://prisma-next.dev/docs/cli/telemetry\n' +
+      'for what is collected and why.',
+  );
+  setCommandExamples(command, [
+    'prisma-next telemetry status',
+    'prisma-next telemetry disable',
+    'prisma-next telemetry enable',
+  ]);
+  command.configureHelp({
+    formatHelp: (cmd) => formatCommandHelp({ command: cmd, flags: parseGlobalFlags({}) }),
+    subcommandDescription: () => '',
+  });
+  command.addCommand(createTelemetryStatusCommand());
+  command.addCommand(createTelemetryEnableCommand());
+  command.addCommand(createTelemetryDisableCommand());
+  return command;
+}

package/src/commands/telemetry/status.ts

@@ -0,0 +1,67 @@
+import { readUserConfig, resolveGating, userConfigPath } from '@prisma-next/cli-telemetry';
+
+/**
+ * Why telemetry resolves the way it does, in the order the CLI's
+ * `resolveTelemetryGate` evaluates: CI hard-disables first, then the env
+ * opt-outs, then the stored `enableTelemetry`, then the opt-out default.
+ */
+export type TelemetryStatusReason =
+  | 'ci'
+  | 'env-opt-out'
+  | 'stored-opt-out'
+  | 'stored-opt-in'
+  | 'default-on';
+
+export interface TelemetryStatus {
+  readonly enabled: boolean;
+  readonly reason: TelemetryStatusReason;
+  readonly configPath: string;
+  readonly installationIdStored: boolean;
+}
+
+/**
+ * Resolves the same gate the runtime uses (CI check + `resolveGating`) and
+ * projects it into a user-facing status. Pure read: never mints, never
+ * writes. The `installationId` value itself is never surfaced — only its
+ * presence — so `status` discloses nothing identifying.
+ */
+export function resolveTelemetryStatus(inputs: {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly inCI: boolean;
+}): TelemetryStatus {
+  const config = readUserConfig();
+  const configPath = userConfigPath();
+  const installationIdStored =
+    typeof config.installationId === 'string' && config.installationId.length > 0;
+
+  if (inputs.inCI) {
+    return { enabled: false, reason: 'ci', configPath, installationIdStored };
+  }
+
+  const gating = resolveGating({ env: inputs.env, config });
+  if (!gating.enabled) {
+    const reason: TelemetryStatusReason =
+      gating.reason === 'env-override' ? 'env-opt-out' : 'stored-opt-out';
+    return { enabled: false, reason, configPath, installationIdStored };
+  }
+
+  const reason: TelemetryStatusReason =
+    config.enableTelemetry === true ? 'stored-opt-in' : 'default-on';
+  return { enabled: true, reason, configPath, installationIdStored };
+}
+
+const REASON_EXPLANATION: Record<TelemetryStatusReason, string> = {
+  ci: 'CI environment detected — telemetry is hard-disabled.',
+  'env-opt-out': 'an environment opt-out is set (DO_NOT_TRACK / PRISMA_NEXT_DISABLE_TELEMETRY).',
+  'stored-opt-out': '"enableTelemetry": false is stored in your config.',
+  'stored-opt-in': '"enableTelemetry": true is stored in your config.',
+  'default-on': 'no explicit choice is stored, so the opt-out default applies.',
+};
+
+export function formatTelemetryStatusLines(status: TelemetryStatus): string[] {
+  return [
+    `Telemetry is ${status.enabled ? 'enabled' : 'disabled'}: ${REASON_EXPLANATION[status.reason]}`,
+    `Config file: ${status.configPath}`,
+    `Installation ID: ${status.installationIdStored ? 'stored' : 'not stored'}`,
+  ];
+}

package/src/control-api/client.ts

@@ -1,4 +1,8 @@
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import { emit as emitContractArtifacts } from '@prisma-next/emitter';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -29,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,
@@ -43,8 +47,8 @@ import type {
   EmitOptions,
   EmitResult,
   IntrospectOptions,
-  MigrationApplyOptions,
-  MigrationApplyResult,
+  MigrateOptions,
+  MigrateResult,
   OnControlProgress,
   SchemaVerifyOptions,
   SignOptions,
@@ -447,9 +451,15 @@ class ControlClientImpl implements ControlClient {
     return familyInstance.readAllMarkers({ driver });
   }
 
-  async migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult> {
+  /** Reads the per-migration journal; omit `space` to return every space. */
+  async readLedger(space?: string): Promise<readonly LedgerEntryRecord[]> {
+    const { driver, familyInstance } = await this.ensureConnected();
+    return familyInstance.readLedger({ driver, ...ifDefined('space', space) });
+  }
+
+  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)) {
@@ -464,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 {
@@ -5,6 +9,7 @@ import type {
   ControlExtensionDescriptor,
   ControlFamilyInstance,
   MigrationOperationPolicy,
+  MigrationPlannerConflict,
   MigrationPlanOperation,
   OperationPreview,
   TargetMigrationsCapability,
@@ -32,14 +37,19 @@ import type {
   OnControlProgress,
   PerSpaceExecutionEntry,
 } from '../types';
-import { applyMigration, buildPerSpaceBreakdown, collectOrdered } from './apply';
 import { stripOperations } from './migration-helpers';
+import {
+  buildPerSpaceBreakdown,
+  collectOrdered,
+  type OrderedResolution,
+  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 = {
@@ -48,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;
@@ -92,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,
@@ -175,6 +185,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
   onProgress?.({ action, kind: 'spanEnd', spanId: SPAN_IDS.plan, outcome: 'ok' });
 
   const orderedResolutions = collectOrdered(planResult.value.applyOrder, planResult.value.perSpace);
+  const plannerWarnings = aggregatePlannerWarnings(orderedResolutions);
 
   // The destination's structural shape comes from the app's plan — its
   // `destination` is the storage hash users see in CLI output.
@@ -202,16 +213,17 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
       preview,
       perSpace,
       summary,
+      ...ifDefined('warnings', plannerWarnings),
     });
   }
 
-  // 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,
@@ -228,6 +240,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
       summary: applied.failure.summary,
       ...ifDefined('why', applied.failure.why),
       meta: applied.failure.meta,
+      ...ifDefined('warnings', plannerWarnings),
     });
   }
 
@@ -246,9 +259,17 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
     operationsExecuted: applied.value.totalOpsExecuted,
     perSpace: applied.value.perSpace,
     summary,
+    ...ifDefined('warnings', plannerWarnings),
   });
 }
 
+function aggregatePlannerWarnings(
+  orderedResolutions: readonly OrderedResolution[],
+): readonly MigrationPlannerConflict[] | undefined {
+  const warnings = orderedResolutions.flatMap((r) => r.entry.warnings ?? []);
+  return warnings.length > 0 ? warnings : undefined;
+}
+
 /**
  * Compare the live `_prisma_marker` rows against the aggregate's
  * declared members. Any marker row whose `space` is not a member of
@@ -339,6 +360,7 @@ function wrapPlanResult(args: {
   readonly preview: OperationPreview | undefined;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const success: DbInitSuccess | DbUpdateSuccess = {
     mode: 'plan',
@@ -352,6 +374,7 @@ function wrapPlanResult(args: {
     },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -363,6 +386,7 @@ function wrapApplyResult(args: {
   readonly operationsExecuted: number;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const success: DbInitSuccess | DbUpdateSuccess = {
     mode: 'apply',
@@ -380,6 +404,7 @@ function wrapApplyResult(args: {
       : { storageHash: args.destination.storageHash },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -388,6 +413,7 @@ function buildRunnerFailure(args: {
   readonly summary: string;
   readonly why?: string;
   readonly meta: Record<string, unknown>;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const failure: DbInitFailure | DbUpdateFailure = {
     code: 'RUNNER_FAILED',
@@ -395,6 +421,7 @@ function buildRunnerFailure(args: {
     why: args.why,
     meta: args.meta,
     conflicts: undefined,
+    ...ifDefined('warnings', args.warnings),
   };
   return notOk(failure) as DbInitResult | DbUpdateResult;
 }

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 {
@@ -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,
@@ -276,7 +281,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     );
   }
 
-  const applied = await applyMigration({
+  const applied = await runMigration({
     aggregate,
     perSpacePlans,
     applyOrder,
@@ -285,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,
@@ -319,7 +324,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)`;
@@ -361,7 +366,13 @@ function buildAtHeadResolution(args: {
     displayOps: [],
     destinationContract: member.contract(),
     strategy: 'graph-walk',
-    migrationEdges: [],
+    migrationEdges: [
+      buildSynthMigrationEdge({
+        currentMarkerStorageHash: liveMarker?.storageHash,
+        destinationStorageHash: targetHash,
+        operationCount: 0,
+      }),
+    ],
   };
 }
 
@@ -389,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,
@@ -404,7 +415,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 +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,
@@ -455,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}"`,
@@ -481,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