@prisma-next/cli 0.5.0-dev.74 → 0.5.0-dev.76

package/src/commands/migration-status.ts

@@ -1,4 +1,11 @@
-import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import {
+  createControlStack,
+  type MigrationPlanOperation,
+} from '@prisma-next/framework-components/control';
+import {
+  type ContractMarkerRecordLike,
+  graphWalkStrategy,
+} from '@prisma-next/migration-tools/aggregate';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import {
   errorNoInvariantPath,
@@ -39,6 +46,10 @@ import {
   toPathDecisionResult,
   toStructuralEdge,
 } from '../utils/command-helpers';
+import {
+  type BuildAggregateInputs,
+  buildContractSpaceAggregate,
+} from '../utils/contract-space-aggregate-loader';
 import {
   type EdgeStatus,
   type EdgeStatusKind,
@@ -76,6 +87,53 @@ export interface MigrationStatusEntry {
   readonly status: EdgeStatusKind | 'unknown';
 }
 
+/**
+ * Per-space status row in the aggregate-shaped status output.
+ *
+ * Surfaces, for each contract space:
+ *
+ * - `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`).
+ * - `pendingCount`: number of migration edges between marker and head.
+ *    Computed via {@link graphWalkStrategy}; 0 means the space is
+ *    already at head.
+ * - `status`: convenience tag the formatter uses to pick a glyph.
+ *    `'never-planned'` is reserved for spaces with non-empty head but
+ *    no on-disk migrations — which shouldn't happen if the loader's
+ *    integrity check passes.
+ *
+ * Online-only fields (`markerHash`, `status`) are absent when the
+ * command runs without a database connection.
+ */
+export interface MigrationStatusSpaceEntry {
+  readonly spaceId: string;
+  readonly kind: 'app' | 'extension';
+  readonly headHash: string;
+  readonly markerHash?: string | null;
+  readonly pendingCount?: number;
+  readonly status?: 'up-to-date' | 'pending' | 'no-marker' | 'never-planned' | 'unreachable';
+}
+
+/**
+ * Sum per-space `pendingCount` into a cross-space total, but only when
+ * every loaded space reports a defined `pendingCount`. Returns
+ * `undefined` if any space is on the marker-unknown / offline path
+ * (where `pendingCount` is intentionally absent), so JSON consumers can
+ * distinguish "no pending" from "unknown".
+ */
+export function computeTotalPendingAcrossSpaces(
+  spaces: readonly MigrationStatusSpaceEntry[],
+): number | undefined {
+  if (spaces.length === 0) return undefined;
+  let total = 0;
+  for (const s of spaces) {
+    if (s.pendingCount === undefined) return undefined;
+    total += s.pendingCount;
+  }
+  return total;
+}
+
 export type { StatusDiagnostic, StatusRef } from '../utils/migration-types';
 
 export interface MigrationStatusResult {
@@ -117,6 +175,22 @@ export interface MigrationStatusResult {
   };
   readonly summary: string;
   readonly diagnostics: readonly StatusDiagnostic[];
+  /**
+   * Aggregate enumeration of every on-disk contract space (app +
+   * extensions), in canonical schedule order (extensions
+   * alphabetically, then app). Present whenever the aggregate loader
+   * succeeded; absent in early-error returns (e.g. unreadable
+   * migrations directory) where the existing diagnostics already
+   * surface the failure.
+   *
+   * The legacy top-level fields (`migrations`, `markerHash`,
+   * `targetHash`, `pathDecision`, …) describe the **app member**
+   * specifically — back-compat with single-space callers. Per-space
+   * detail for extension members lives only on this list.
+   */
+  readonly spaces?: readonly MigrationStatusSpaceEntry[];
+  /** Cross-space pending-migration total (sum of `spaces[].pendingCount`). Present when `spaces` is. */
+  readonly totalPendingAcrossSpaces?: number;
   readonly graph?: MigrationGraph;
   readonly bundles?: readonly OnDiskMigrationPackage[];
   readonly edgeStatuses?: readonly EdgeStatus[];
@@ -363,16 +437,130 @@ function determineLimit(opts: MigrationStatusOptions) {
   return parsed;
 }
 
+/**
+ * Build the aggregate enumeration of contract spaces for the status
+ * output. Loads the aggregate from disk (lossy on failure — extension
+ * spaces are simply omitted, the existing single-space app behaviour
+ * keeps working), reads per-space marker rows when online, and uses
+ * {@link graphWalkStrategy} to compute each space's pending count.
+ *
+ * Sub-spec § `migration status` semantics — the aggregate-walking
+ * version reports per-space marker + pending state alongside the
+ * cross-space totals.
+ */
+export async function loadAggregateStatusSpaces(args: {
+  readonly targetId: string;
+  readonly migrationsDir: string;
+  readonly appContractRaw: unknown;
+  readonly extensionPacks: BuildAggregateInputs<string, string>['extensionPacks'];
+  readonly validateContract: BuildAggregateInputs<string, string>['validateContract'];
+  readonly markersBySpace: ReadonlyMap<string, ContractMarkerRecordLike> | null;
+}): Promise<readonly MigrationStatusSpaceEntry[]> {
+  const loadInputs: BuildAggregateInputs<string, string> = {
+    targetId: args.targetId,
+    migrationsDir: args.migrationsDir,
+    appContract: args.validateContract(args.appContractRaw),
+    extensionPacks: args.extensionPacks,
+    validateContract: args.validateContract,
+  };
+
+  const loaded = await buildContractSpaceAggregate(loadInputs);
+  if (!loaded.ok) {
+    // Loader failure (drift, layout violation, etc.) — surfacing it
+    // as a status diagnostic would duplicate `migration plan`'s job.
+    // The single-space app pipeline still runs; extensions are simply
+    // not enumerated.
+    return [];
+  }
+  const aggregate = loaded.value;
+
+  const orderedMembers = [...aggregate.extensions, aggregate.app];
+  const rows: MigrationStatusSpaceEntry[] = [];
+  for (const member of orderedMembers) {
+    const liveMarker = args.markersBySpace?.get(member.spaceId) ?? null;
+    const isApp = member.spaceId === aggregate.app.spaceId;
+
+    if (member.migrations.graph.nodes.size === 0) {
+      rows.push({
+        spaceId: member.spaceId,
+        kind: isApp ? 'app' : 'extension',
+        headHash: member.headRef.hash,
+        ...(args.markersBySpace !== null
+          ? {
+              markerHash: liveMarker?.storageHash ?? null,
+              status: member.headRef.hash === EMPTY_CONTRACT_HASH ? 'up-to-date' : 'never-planned',
+              pendingCount: 0,
+            }
+          : {}),
+      });
+      continue;
+    }
+
+    if (args.markersBySpace === null) {
+      rows.push({
+        spaceId: member.spaceId,
+        kind: isApp ? 'app' : 'extension',
+        headHash: member.headRef.hash,
+      });
+      continue;
+    }
+
+    const walked = graphWalkStrategy({
+      aggregateTargetId: aggregate.targetId,
+      member,
+      currentMarker: liveMarker,
+    });
+    let pendingCount = 0;
+    let status: MigrationStatusSpaceEntry['status'];
+    if (walked.kind === 'ok') {
+      pendingCount = walked.result.plan.operations.length;
+      if (liveMarker === null) {
+        status = pendingCount === 0 ? 'no-marker' : 'pending';
+      } else {
+        status = pendingCount === 0 ? 'up-to-date' : 'pending';
+      }
+    } else {
+      status = 'unreachable';
+    }
+
+    rows.push({
+      spaceId: member.spaceId,
+      kind: isApp ? 'app' : 'extension',
+      headHash: member.headRef.hash,
+      markerHash: liveMarker?.storageHash ?? null,
+      pendingCount,
+      ...(status ? { status } : {}),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Read the raw contract.json bytes from disk for the aggregate
+ * loader. Returns `null` if the file is missing or unparseable —
+ * the existing `readContractEnvelope` path will report the same
+ * problem via a status diagnostic, no need to double-surface.
+ */
+async function loadContractRawSafely(config: {
+  contract?: { output?: string };
+}): Promise<unknown | null> {
+  try {
+    const path = (await import('../utils/command-helpers')).resolveContractPath(config);
+    const raw = await (await import('node:fs/promises')).readFile(path, 'utf-8');
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+}
+
 async function executeMigrationStatusCommand(
   options: MigrationStatusOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationStatusResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { configPath, appMigrationsDir, appMigrationsRelative, migrationsDir, refsDir } =
+    resolveMigrationPaths(options.config, config);
 
   const dbConnection = options.db ?? config.db?.connection;
   const hasDriver = !!config.driver;
@@ -515,6 +703,7 @@ async function executeMigrationStatusCommand(
   let markerHash: string | undefined;
   let markerInvariants: readonly string[] = [];
   let mode: 'online' | 'offline' = 'offline';
+  let allMarkers: ReadonlyMap<string, ContractMarkerRecordLike> | null = null;
 
   if (dbConnection && hasDriver) {
     const client = createControlClient({
@@ -530,6 +719,21 @@ async function executeMigrationStatusCommand(
       markerHash = marker?.storageHash;
       markerInvariants = marker?.invariants ?? [];
       mode = 'online';
+      // Read every space's marker so the aggregate enumeration can
+      // surface per-space marker state. `readAllMarkers` mirrors what
+      // `db init` / `db update` already use to drive the multi-space
+      // planner; here it powers the aggregate status output.
+      try {
+        allMarkers = await client.readAllMarkers();
+      } catch {
+        // Older family instances may not implement `readAllMarkers`.
+        // Per-space enumeration falls back to "marker unknown" rather
+        // than failing the whole status command — leaving
+        // `allMarkers` as `null` signals "unknown" to the aggregate
+        // loader (an empty `Map` would instead mean "every space has
+        // no marker", which is a different condition).
+        allMarkers = null;
+      }
     } catch {
       if (!flags.json && !flags.quiet) {
         ui.warn('Could not connect to database — showing offline status');
@@ -539,6 +743,37 @@ async function executeMigrationStatusCommand(
     }
   }
 
+  // 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
+  // can't be loaded — a strict failure here would degrade the
+  // load-bearing app-space output for unrelated reasons.
+  const contractRawForAggregate = await loadContractRawSafely(config);
+  let aggregateSpaces: readonly MigrationStatusSpaceEntry[] = [];
+  if (contractRawForAggregate !== null) {
+    // The aggregate loader needs a typed-Contract producer. Build a
+    // real control stack so `validateContract` runs against a fully
+    // composed family instance — descriptors that read stack members
+    // during construction (e.g. codec lookups) get a consistent view.
+    const stack = createControlStack(config);
+    const familyInstance = config.family.create(stack);
+    try {
+      aggregateSpaces = await loadAggregateStatusSpaces({
+        targetId: config.target.targetId,
+        migrationsDir,
+        appContractRaw: contractRawForAggregate,
+        extensionPacks: config.extensionPacks ?? [],
+        validateContract: (json: unknown) => familyInstance.validateContract(json),
+        markersBySpace: allMarkers,
+      });
+    } catch {
+      // Loader failure short-circuits silently — the existing
+      // single-space app pipeline below still runs.
+      aggregateSpaces = [];
+    }
+  }
+  const totalPendingAcrossSpaces = computeTotalPendingAcrossSpaces(aggregateSpaces);
+
   // Pre-check unknown invariants. Online: union the graph's declared
   // invariants with the marker's recorded set so a retired-but-applied
   // invariant doesn't surface as MIGRATION.UNKNOWN_INVARIANT — apply would
@@ -803,6 +1038,8 @@ async function executeMigrationStatusCommand(
     edgeStatuses,
     ...ifDefined('activeRefHash', activeRefHash),
     ...ifDefined('activeRefName', activeRefName),
+    spaces: aggregateSpaces,
+    ...ifDefined('totalPendingAcrossSpaces', totalPendingAcrossSpaces),
   };
   return ok(result);
 }
@@ -950,9 +1187,55 @@ export function formatStatusSummary(result: MigrationStatusResult, colorize: boo
     }
   }
 
+  // Per-space section. Suppressed when there's no extension space —
+  // the legacy single-space output already covers the app member.
+  // When extensions exist, render every space (including the app)
+  // for consistency, plus a cross-space pending total + apply hint.
+  if (result.spaces?.some((s) => s.kind === 'extension')) {
+    const total = result.totalPendingAcrossSpaces ?? 0;
+    lines.push('');
+    lines.push(c(dim, 'spaces'));
+    for (const space of result.spaces) {
+      lines.push(formatSpaceLine(space, c));
+    }
+    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`,
+      );
+    }
+  }
+
   return lines.join('\n');
 }
 
+function formatSpaceLine(
+  space: MigrationStatusSpaceEntry,
+  c: (fn: (s: string) => string, s: string) => string,
+): string {
+  const glyph = (() => {
+    if (space.status === 'up-to-date' || space.status === 'no-marker') return c(cyan, '✓');
+    if (space.status === 'pending') return c(yellow, '⧗');
+    if (space.status === 'unreachable' || space.status === 'never-planned') return c(magenta, '✗');
+    return ' ';
+  })();
+  const tag = space.kind === 'app' ? '[app]' : '[ext]';
+  const head = space.headHash.slice(0, 8);
+  const marker =
+    space.markerHash === undefined
+      ? '(unknown)'
+      : space.markerHash === null
+        ? '(no marker)'
+        : space.markerHash.slice(0, 8);
+  const pending =
+    space.pendingCount === undefined
+      ? ''
+      : space.pendingCount === 0
+        ? c(dim, ' (up to date)')
+        : c(yellow, ` (${space.pendingCount} pending)`);
+  return `  ${glyph} ${c(dim, tag)} ${space.spaceId} → head ${c(dim, head)}, marker ${c(dim, marker)}${pending}`;
+}
+
 function formatInvariantList(ids: readonly string[]): string {
   return ids.length === 0 ? '(none)' : ids.join(', ');
 }

package/src/control-api/client.ts

@@ -461,16 +461,28 @@ class ControlClientImpl implements ControlClient {
       throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
+
     return executeMigrationApply({
       driver,
       familyInstance,
-      originHash: options.originHash,
-      destinationHash: options.destinationHash,
-      pendingMigrations: options.pendingMigrations,
+      contract,
       migrations: this.options.target.migrations,
       frameworkComponents,
+      migrationsDir: options.migrationsDir,
+      extensionPacks: this.options.extensionPacks ?? [],
       targetId: this.options.target.targetId,
-      ...(onProgress ? { onProgress } : {}),
+      appMigrationPackages: options.appMigrationPackages,
+      ...ifDefined('refHash', options.refHash),
+      ...ifDefined('refInvariants', options.refInvariants),
+      ...ifDefined('refName', options.refName),
+      ...ifDefined('onProgress', onProgress),
     });
   }
 

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

@@ -0,0 +1,290 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationOperationPolicy,
+  MultiSpaceCapableRunner,
+  MultiSpaceRunnerPerSpaceOptions,
+  TargetMigrationsCapability,
+} from '@prisma-next/framework-components/control';
+import { hasMultiSpaceRunner } from '@prisma-next/framework-components/control';
+import type {
+  AggregatePerSpacePlan,
+  ContractSpaceAggregate,
+} from '@prisma-next/migration-tools/aggregate';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { errorRunnerFailed } from '../../utils/cli-errors';
+import type { AggregatePerSpaceExecutionEntry, OnControlProgress } from '../types';
+
+/**
+ * Span id emitted via `onProgress` for the apply phase. Stable
+ * identifier consumed by the structured-output renderer and by tests.
+ */
+const APPLY_SPAN_ID = 'apply' as const;
+
+/**
+ * Action that originated this apply 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 AggregateApplyAction = 'dbInit' | 'dbUpdate' | 'migrationApply';
+
+/**
+ * Failure variant emitted by {@link applyAggregate} when the multi-space
+ * runner itself rejects the apply. Mirrors the failure shape callers
+ * already wrap into their own action-specific failure envelopes
+ * (`DbInitFailure`, `DbUpdateFailure`, `MigrationApplyFailure`) so each
+ * caller keeps owning its own discriminated failure code.
+ */
+export interface AggregateApplyRunnerFailure {
+  readonly summary: string;
+  readonly why?: string;
+  readonly meta: Record<string, unknown>;
+}
+
+export interface ApplyAggregateInputs<TFamilyId extends string, TTargetId extends string> {
+  readonly aggregate: ContractSpaceAggregate;
+  /**
+   * 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
+   * for every member). Either way, the runner consumes the same shape.
+   */
+  readonly perSpacePlans: ReadonlyMap<string, AggregatePerSpacePlan>;
+  /**
+   * Canonical schedule order — extensions alphabetically by `spaceId`,
+   * then app. Mirrors {@link import('@prisma-next/migration-tools/concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
+   * convention so `MultiSpaceRunnerFailure.failingSpace` attribution
+   * stays byte-for-byte stable across callers.
+   */
+  readonly applyOrder: readonly string[];
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId, unknown>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly policy: MigrationOperationPolicy;
+  readonly action: AggregateApplyAction;
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Resolved per-space plan in canonical schedule order. Surfaced from
+ * {@link applyAggregate} to callers so each one can build its own
+ * action-specific success envelope (e.g. `DbInitSuccess` vs
+ * `MigrationApplySuccess`) without re-deriving the ordering.
+ */
+export interface OrderedResolution {
+  readonly spaceId: string;
+  readonly entry: AggregatePerSpacePlan;
+}
+
+export interface ApplyAggregateValue {
+  readonly orderedResolutions: readonly OrderedResolution[];
+  readonly totalOpsPlanned: number;
+  readonly totalOpsExecuted: number;
+  /**
+   * Per-space breakdown ready to thread into action-specific success
+   * envelopes. Each entry carries the post-apply marker (live storage hash
+   * plus invariants) so callers can render it directly without re-reading.
+   */
+  readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
+}
+
+export type ApplyAggregateResult = Result<ApplyAggregateValue, AggregateApplyRunnerFailure>;
+
+/**
+ * Runner-driving tail shared by every aggregate apply caller — `db init`,
+ * `db update`, and `migration apply`. 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.
+ *
+ * Marker advancement is part of the runner's per-space transaction
+ * (the SQL family runner writes the marker as the last step of each
+ * space's transaction), so this primitive does not advance markers
+ * separately — by the time `executeAcrossSpaces` returns ok, every
+ * space's marker has been advanced to its plan's destination.
+ *
+ * Span emission (`spanStart 'apply'` / `spanEnd 'apply'`) is owned here
+ * 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 applyAggregate<TFamilyId extends string, TTargetId extends string>(
+  inputs: ApplyAggregateInputs<TFamilyId, TTargetId>,
+): Promise<ApplyAggregateResult> {
+  const {
+    aggregate,
+    perSpacePlans,
+    applyOrder,
+    driver,
+    familyInstance,
+    migrations,
+    frameworkComponents,
+    policy,
+    action,
+    onProgress,
+  } = inputs;
+
+  const orderedResolutions = collectOrdered(applyOrder, perSpacePlans);
+
+  const runner = migrations.createRunner(familyInstance);
+  if (!hasMultiSpaceRunner(runner)) {
+    throw errorRunnerFailed(
+      `Runner for target "${aggregate.targetId}" does not implement \`executeAcrossSpaces\``,
+      {
+        why: `${labelForAction(action)} requires multi-space-capable runners (today: every SQL family runner).`,
+      },
+    );
+  }
+
+  onProgress?.({
+    action,
+    kind: 'spanStart',
+    spanId: APPLY_SPAN_ID,
+    label: progressLabelForAction(action),
+  });
+
+  const perSpaceOptions: MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>[] =
+    orderedResolutions.map((r) => ({
+      space: r.spaceId,
+      plan: r.entry.plan,
+      driver,
+      destinationContract: r.entry.destinationContract,
+      policy,
+      frameworkComponents,
+      // 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
+      // `extras`. Tolerant mode still catches missing tables / columns.
+      // SQL family runners read `strictVerification` via structural
+      // typing.
+      strictVerification: false,
+    })) as MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>[];
+
+  const runnerResult = await (
+    runner as MultiSpaceCapableRunner<TFamilyId, TTargetId>
+  ).executeAcrossSpaces({ driver, perSpaceOptions });
+
+  if (!runnerResult.ok) {
+    onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'error' });
+    return notOk({
+      summary: runnerResult.failure.summary,
+      ...ifDefined('why', runnerResult.failure.why),
+      meta: {
+        ...(runnerResult.failure.meta ?? {}),
+        failingSpace: runnerResult.failure.failingSpace,
+      },
+    });
+  }
+  onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'ok' });
+
+  const totalOpsPlanned = runnerResult.value.perSpaceResults.reduce(
+    (sum, r) => sum + r.value.operationsPlanned,
+    0,
+  );
+  const totalOpsExecuted = runnerResult.value.perSpaceResults.reduce(
+    (sum, r) => sum + r.value.operationsExecuted,
+    0,
+  );
+
+  const perSpace = buildPerSpaceBreakdown(orderedResolutions, aggregate.app.spaceId, {
+    includeMarkers: true,
+  });
+
+  return ok({
+    orderedResolutions,
+    totalOpsPlanned,
+    totalOpsExecuted,
+    perSpace,
+  });
+}
+
+/**
+ * Project the planner's per-space resolutions into the
+ * `AggregatePerSpaceExecutionEntry[]` shape the CLI surfaces.
+ *
+ * `includeMarkers` is `true` for apply-mode (each space's marker is
+ * the `destination.storageHash` of its plan, which the runner
+ * advances as the last step of each space's transaction) and `false`
+ * for plan-mode (no marker has been written yet).
+ *
+ * Exported alongside {@link applyAggregate} so plan-mode callers can
+ * assemble the same per-space block without going through the runner.
+ */
+export function buildPerSpaceBreakdown(
+  orderedResolutions: readonly OrderedResolution[],
+  appSpaceId: string,
+  options: { readonly includeMarkers: boolean },
+): readonly AggregatePerSpaceExecutionEntry[] {
+  return orderedResolutions.map((r) => {
+    const operations = r.entry.displayOps.map((op) => ({
+      id: op.id,
+      label: op.label,
+      operationClass: op.operationClass,
+    }));
+    const base: AggregatePerSpaceExecutionEntry = {
+      spaceId: r.spaceId,
+      kind: r.spaceId === appSpaceId ? 'app' : 'extension',
+      operations,
+    };
+    if (!options.includeMarkers) return base;
+    return {
+      ...base,
+      marker: { storageHash: r.entry.plan.destination.storageHash },
+    };
+  });
+}
+
+/**
+ * Materialise the `applyOrder` ordering into resolved per-space
+ * entries. Throws if the planner output is missing a member listed
+ * in `applyOrder` — a wiring bug that should never reach runtime.
+ *
+ * Exported so callers building their own success envelopes after a
+ * plan-mode dispatch can replay the same ordering.
+ */
+export function collectOrdered(
+  applyOrder: readonly string[],
+  perSpace: ReadonlyMap<string, AggregatePerSpacePlan>,
+): readonly OrderedResolution[] {
+  return applyOrder.map((spaceId) => {
+    const entry = perSpace.get(spaceId);
+    if (!entry) {
+      throw new Error(`Aggregate planner output missing per-space plan for "${spaceId}"`);
+    }
+    return { spaceId, entry };
+  });
+}
+
+/**
+ * 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
+ * so structured-progress output reads naturally for each surface.
+ */
+export function progressLabelForAction(action: AggregateApplyAction): 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';
+  }
+}
+
+function labelForAction(action: AggregateApplyAction): string {
+  switch (action) {
+    case 'dbInit':
+      return 'db init';
+    case 'dbUpdate':
+      return 'db update';
+    case 'migrationApply':
+      return 'migration apply';
+  }
+}