@prisma-next/cli 0.5.0-dev.73 → 0.5.0-dev.75

package/src/commands/migration-apply.ts

@@ -1,11 +1,6 @@
-import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import {
-  errorNoInvariantPath,
-  errorUnknownInvariant,
-  MigrationToolsError,
-} from '@prisma-next/migration-tools/errors';
-import { findPathWithDecision } from '@prisma-next/migration-tools/migration-graph';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { readFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
+import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
@@ -14,12 +9,18 @@ import { Command } from 'commander';
 
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
-import type { MigrationApplyFailure, MigrationApplyStep } from '../control-api/types';
+import type {
+  AggregatePerSpaceExecutionEntry,
+  MigrationApplyFailure,
+  MigrationApplyPathDecision,
+} from '../control-api/types';
 import {
   CliStructuredError,
   type CliStructuredError as CliStructuredErrorType,
+  errorContractValidationFailed,
   errorDatabaseConnectionRequired,
   errorDriverRequired,
+  errorFileNotFound,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -30,13 +31,11 @@ import {
   collectDeclaredInvariants,
   loadMigrationPackages,
   maskConnectionUrl,
-  readContractEnvelope,
+  resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   targetSupportsMigrations,
-  toPathDecisionResult,
-  toStructuralEdge,
 } from '../utils/command-helpers';
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
@@ -51,34 +50,45 @@ interface MigrationApplyCommandOptions extends CommonCommandOptions {
   readonly ref?: string;
 }
 
+/**
+ * Per-space breakdown of an apply run. The CLI command surfaces these
+ * for both the JSON shape (`appliedSpaces[]`) and the human-readable
+ * formatter (per-space block — same shape `db init` / `db update`
+ * use, M6 sub-spec § Output shape contract).
+ */
 export interface MigrationApplyResult {
   readonly ok: boolean;
+  /** Number of contract spaces that had non-zero pending operations applied. */
   readonly migrationsApplied: number;
+  /** Total contract spaces visible in the aggregate (pending + already-up-to-date). */
   readonly migrationsTotal: number;
+  /**
+   * Marker hash for the **app member** post-apply. Surfaced for
+   * back-compat with single-space callers; per-space markers live on
+   * `perSpace[].marker.storageHash`.
+   */
   readonly markerHash: string;
   readonly applied: readonly {
+    readonly spaceId: string;
     readonly dirName: string;
-    readonly from: string | null;
+    readonly migrationHash: string;
+    readonly from: string;
     readonly to: string;
     readonly operationsExecuted: number;
   }[];
   readonly summary: string;
-  readonly pathDecision?: {
-    readonly fromHash: string;
-    readonly toHash: string;
-    readonly alternativeCount: number;
-    readonly tieBreakReasons: readonly string[];
-    readonly refName?: string;
-    readonly requiredInvariants: readonly string[];
-    readonly satisfiedInvariants: readonly string[];
-    readonly selectedPath: readonly {
-      readonly dirName: string;
-      readonly migrationHash: string;
-      readonly from: string;
-      readonly to: string;
-      readonly invariants: readonly string[];
-    }[];
-  };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). Always present for the aggregate-walking
+   * apply path.
+   */
+  readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
+  /**
+   * Path-decision data for the app member. Surfaced for back-compat
+   * with single-space callers (cli-journeys invariant tests).
+   * Absent for no-op applies where the app had nothing to do.
+   */
+  readonly pathDecision?: MigrationApplyPathDecision;
   readonly timings: {
     readonly total: number;
   };
@@ -92,17 +102,6 @@ function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType
   });
 }
 
-function packageToStep(pkg: OnDiskMigrationPackage): MigrationApplyStep {
-  return {
-    dirName: pkg.dirName,
-    from: pkg.metadata.from,
-    to: pkg.metadata.to,
-    toContract: pkg.metadata.toContract,
-    operations: pkg.ops,
-    providedInvariants: pkg.metadata.providedInvariants,
-  };
-}
-
 async function executeMigrationApplyCommand(
   options: MigrationApplyCommandOptions,
   flags: GlobalFlags,
@@ -110,10 +109,8 @@ async function executeMigrationApplyCommand(
   startTime: number,
 ): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
+    resolveMigrationPaths(options.config, config);
 
   const dbConnection = options.db ?? config.db?.connection;
   if (!dbConnection) {
@@ -142,7 +139,6 @@ async function executeMigrationApplyCommand(
   }
 
   let refEntry: RefEntry | undefined;
-  let envelopeHash: string | undefined;
   const refName = options.ref;
 
   if (refName) {
@@ -155,20 +151,31 @@ async function executeMigrationApplyCommand(
       }
       throw error;
     }
-  } else {
-    try {
-      const envelope = await readContractEnvelope(config);
-      envelopeHash = envelope.storageHash;
-    } catch (error) {
+  }
+
+  // Resolve and parse the contract envelope. The aggregate-walking
+  // operation needs the validated app contract to load the aggregate.
+  const contractPathAbsolute = resolveContractPath(config);
+  let contractRaw: Contract;
+  try {
+    const contractContent = await readFile(contractPathAbsolute, 'utf-8');
+    contractRaw = JSON.parse(contractContent) as Contract;
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
       return notOk(
-        errorRuntime('Current contract is unavailable', {
-          why: `Failed to read contract: ${error instanceof Error ? error.message : String(error)}`,
+        errorFileNotFound(contractPathAbsolute, {
+          why: `Contract file not found at ${contractPathAbsolute}`,
           fix: 'Run `prisma-next contract emit` to generate a valid contract.json, then retry apply.',
         }),
       );
     }
+    return notOk(
+      errorContractValidationFailed(
+        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
   }
-  const destinationHash = refEntry?.hash ?? envelopeHash!;
 
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
@@ -194,10 +201,11 @@ async function executeMigrationApplyCommand(
     ui.stderr(header);
   }
 
-  // Read migrations and build migration chain model (offline — no DB needed)
-  let migrations: Awaited<ReturnType<typeof loadMigrationPackages>>;
+  // Load app-space migration packages — the aggregate operation
+  // needs them to hydrate the app member's graph for graph-walk.
+  let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
   try {
-    migrations = await loadMigrationPackages(appMigrationsDir);
+    appPackages = await loadMigrationPackages(appMigrationsDir);
   } catch (error) {
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
@@ -215,20 +223,20 @@ async function executeMigrationApplyCommand(
 
   try {
     await client.connect(dbConnection);
-    const marker = await client.readMarker();
 
-    // Pre-check unknown invariants against `(declared by graph) ∪
-    // (already on the marker)`. The union catches the edge case where the
-    // ref carries an invariant whose declaring migration was retired (e.g.
-    // history rewritten) but whose id is recorded on the marker —
-    // surfacing that as MIGRATION.UNKNOWN_INVARIANT would be misleading
-    // because the database has already satisfied the requirement, so the
-    // marker-subtraction below empties `effectiveRequired` and apply
-    // short-circuits to "Already up to date".
+    // Pre-check unknown invariants against `(declared by app graph) ∪
+    // (already on the app marker)`. The marker side of the union
+    // catches the case where the ref carries an invariant whose
+    // declaring migration was retired (history rewritten) but whose
+    // id is recorded on the marker — surfacing UNKNOWN_INVARIANT
+    // there would be misleading because the database has already
+    // satisfied the requirement.
     if (refEntry && refEntry.invariants.length > 0) {
-      const declared = collectDeclaredInvariants(migrations.graph);
+      const allMarkers = await client.readAllMarkers();
+      const appMarker = allMarkers.get('app') ?? null;
+      const declared = collectDeclaredInvariants(appPackages.graph);
       const known = new Set<string>(declared);
-      for (const id of marker?.invariants ?? []) known.add(id);
+      for (const id of appMarker?.invariants ?? []) known.add(id);
       const unknown = refEntry.invariants.filter((id) => !known.has(id));
       if (unknown.length > 0) {
         return notOk(
@@ -243,149 +251,17 @@ async function executeMigrationApplyCommand(
       }
     }
 
-    // --- No migrations on disk ---
-    if (migrations.bundles.length === 0) {
-      if (marker?.storageHash) {
-        return notOk(
-          errorRuntime('Database has state but no migrations exist', {
-            why: `The database marker hash "${marker.storageHash}" exists but no migrations were found in ${appMigrationsRelative}`,
-            fix: 'Ensure the migrations directory is correct. If the database was managed with `db init` or `db update`, run `prisma-next db sign` to update the marker.',
-            meta: { markerHash: marker.storageHash, migrationsDir: appMigrationsRelative },
-          }),
-        );
-      }
-      // Non-empty contract + no migrations = user needs to plan first.
-      if (destinationHash !== EMPTY_CONTRACT_HASH) {
-        return notOk(
-          errorRuntime('Current contract has no planned migrations', {
-            why: `No migrations were found in ${appMigrationsRelative}, but current contract hash is "${destinationHash}"`,
-            fix: 'Run `prisma-next migration plan` to create a migration for the current contract.',
-            meta: { destinationHash, migrationsDir: appMigrationsRelative },
-          }),
-        );
-      }
-      // Empty contract + no migrations = nothing to do.
-      return ok({
-        ok: true,
-        migrationsApplied: 0,
-        migrationsTotal: 0,
-        markerHash: EMPTY_CONTRACT_HASH,
-        applied: [],
-        summary: 'No migrations found',
-        timings: { total: Date.now() - startTime },
-      });
-    }
-
-    // --- Validate marker state ---
-
-    // The empty sentinel should never appear in a real marker row — if it does,
-    // the marker was corrupted and replaying all migrations would be dangerous.
-    if (marker?.storageHash === EMPTY_CONTRACT_HASH) {
-      return notOk(
-        errorRuntime('Database marker contains the empty sentinel hash', {
-          why: `The marker row exists but contains the empty sentinel value "${EMPTY_CONTRACT_HASH}". This should never happen — the marker should contain the hash of the last applied contract.`,
-          fix: 'The marker is corrupted. Run `prisma-next db sign` to overwrite it with the correct contract hash, or drop and recreate the database.',
-          meta: { markerHash: EMPTY_CONTRACT_HASH },
-        }),
-      );
-    }
-
-    const markerHash = marker?.storageHash;
-
-    if (markerHash !== undefined && !migrations.graph.nodes.has(markerHash)) {
-      return notOk(
-        errorRuntime('Database marker does not match any known migration', {
-          why: `The database marker hash "${markerHash}" is not found in the migration history at ${appMigrationsRelative}`,
-          fix: 'Ensure the migrations directory matches this database. If the database was managed with `db init` or `db update`, run `prisma-next db sign` to update the marker.',
-          meta: { markerHash, knownNodes: [...migrations.graph.nodes] },
-        }),
-      );
-    }
-
-    if (!migrations.graph.nodes.has(destinationHash)) {
-      return notOk(
-        errorRuntime('Current contract has no planned migration path', {
-          why: `Current contract hash "${destinationHash}" is not present in the migration history at ${appMigrationsRelative}`,
-          fix: 'Run `prisma-next migration plan` to create a migration for the current contract, then re-run apply.',
-          meta: { destinationHash, knownNodes: [...migrations.graph.nodes] },
-        }),
-      );
-    }
-
-    // "No marker" means the database is fresh — start from the empty contract hash.
-    const originHash = markerHash ?? EMPTY_CONTRACT_HASH;
-
-    const appliedInvariants = new Set(marker?.invariants ?? []);
-    const effectiveRequired = new Set(
-      (refEntry?.invariants ?? []).filter((id) => !appliedInvariants.has(id)),
-    );
-
-    const outcome = findPathWithDecision(migrations.graph, originHash, destinationHash, {
-      ...ifDefined('refName', refName),
-      required: effectiveRequired,
-    });
-    if (outcome.kind === 'unsatisfiable') {
-      return notOk(
-        mapMigrationToolsError(
-          errorNoInvariantPath({
-            ...ifDefined('refName', refName),
-            required: [...effectiveRequired].sort(),
-            missing: outcome.missing,
-            structuralPath: outcome.structuralPath.map(toStructuralEdge),
-          }),
-        ),
-      );
-    }
-    if (outcome.kind === 'unreachable') {
-      return notOk(
-        errorRuntime('No migration path from current state to target', {
-          why: `Cannot find a path from "${originHash}" to target "${destinationHash}"`,
-          fix: 'Check the migration history for gaps or inconsistencies.',
-          meta: { markerHash: originHash, destinationHash },
-        }),
-      );
-    }
-
-    const pathDecision = toPathDecisionResult(outcome.decision);
-
-    if (outcome.decision.selectedPath.length === 0) {
-      return ok({
-        ok: true,
-        migrationsApplied: 0,
-        migrationsTotal: 0,
-        markerHash: originHash,
-        applied: [],
-        summary: 'Already up to date',
-        pathDecision,
-        timings: { total: Date.now() - startTime },
-      });
-    }
-
-    const bundleByDir = new Map(migrations.bundles.map((b) => [b.dirName, b]));
-    const pendingMigrations: MigrationApplyStep[] = [];
-    for (const migration of outcome.decision.selectedPath) {
-      const pkg = bundleByDir.get(migration.dirName);
-      if (!pkg) {
-        return notOk(
-          errorRuntime(`Migration package not found: ${migration.dirName}`, {
-            why: `The migration directory for path segment ${migration.from} → ${migration.to} was not found`,
-            fix: 'Ensure all migration directories are present and intact.',
-          }),
-        );
-      }
-      pendingMigrations.push(packageToStep(pkg));
-    }
-
     if (!flags.quiet && !flags.json) {
-      for (const migration of pendingMigrations) {
-        ui.step(`Pending ${migration.dirName}`);
-      }
+      ui.step('Loading contract spaces…');
     }
 
     const applyResult = await client.migrationApply({
-      originHash,
-      destinationHash,
-      pendingMigrations,
+      contract: contractRaw,
+      migrationsDir,
+      appMigrationPackages: appPackages.bundles,
+      ...ifDefined('refHash', refEntry?.hash),
+      ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
+      ...(refEntry !== undefined ? ifDefined('refName', refName) : {}),
     });
 
     if (!applyResult.ok) {
@@ -397,17 +273,21 @@ async function executeMigrationApplyCommand(
     return ok({
       ok: true,
       migrationsApplied: value.migrationsApplied,
-      migrationsTotal: outcome.decision.selectedPath.length,
+      migrationsTotal: value.perSpace.length,
       markerHash: value.markerHash,
       applied: value.applied,
       summary: value.summary,
-      pathDecision,
+      perSpace: value.perSpace,
+      ...ifDefined('pathDecision', value.pathDecision),
       timings: { total: Date.now() - startTime },
     });
   } catch (error) {
     if (CliStructuredError.is(error)) {
       return notOk(error);
     }
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
         why: `Unexpected error during migration apply: ${error instanceof Error ? error.message : String(error)}`,
@@ -423,16 +303,17 @@ export function createMigrationApplyCommand(): Command {
   setCommandDescriptions(
     command,
     'Apply planned migrations to the database',
-    'Applies previously planned migrations (created by `migration plan`) to a live database.\n' +
-      'Compares the database marker against the migration history to determine which\n' +
-      'migrations are pending, then executes them sequentially. Each migration runs\n' +
-      'in its own transaction. Does not plan new migrations — run `migration plan` first.',
+    'Walks every contract space (app + extensions) and applies pending\n' +
+      'on-disk migrations in canonical order (extensions alphabetically,\n' +
+      'then app). Graph-walks the on-disk migration graph for every space —\n' +
+      "no introspection, no synth. Each space's marker advances inside its\n" +
+      "transaction; per-space failure rolls back every space's writes.",
   );
   setCommandExamples(command, ['prisma-next migration apply --db $DATABASE_URL']);
   addGlobalOptions(command)
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--ref <name>', 'Target ref name from migrations/refs/')
+    .option('--ref <name>', 'App-space target ref name from migrations/app/refs/')
     .action(async (options: MigrationApplyCommandOptions) => {
       const flags = parseGlobalFlags(options);
       const startTime = Date.now();

package/src/commands/migration-plan.ts

@@ -43,15 +43,16 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import {
-  type ExtensionMigrationsExtensionInput,
-  runContractSpaceExtensionMigrationsPass,
-} from '../utils/contract-space-extension-migrations-pass';
+import { runContractSpaceExtensionMigrationsPass } from '../utils/contract-space-extension-migrations-pass';
 import {
   formatContractSpaceDriftWarning,
-  type MigrateExtensionInput,
   runContractSpaceMigratePass,
 } from '../utils/contract-space-migrate-pass';
+import {
+  toExtensionInputs,
+  toExtensionMigrationsInputs,
+  toMigratePassInputs,
+} from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -71,6 +72,19 @@ export interface MigrationPlanResult {
   readonly from: string | null;
   readonly to: string;
   readonly dir?: string;
+  /**
+   * Extension-space migration packages materialised onto disk during this
+   * `plan` run. Each entry names a `migrations/<spaceId>/<dirName>/`
+   * tree the framework wrote alongside the app-space migration directory.
+   * Empty when the project has no extension packs declaring a contract
+   * space, or when every extension-space package is already on disk.
+   *
+   * Surfacing these in the result (rather than only via `ui.step` log
+   * lines) makes the cross-space side effect explicit to JSON consumers
+   * and the success-summary renderer — the same multi-space side effect
+   * that `migration apply` will replay.
+   */
+  readonly emittedExtensionDirs: readonly { readonly spaceId: string; readonly dirName: string }[];
   readonly operations: readonly {
     readonly id: string;
     readonly label: string;
@@ -233,16 +247,12 @@ async function executeMigrationPlanCommand(
   // structural app-space change) still re-pins extension artefacts on
   // disk. Drift warnings are non-fatal — the on-disk artefacts are refreshed
   // and the user is notified that the bump is being captured.
-  const extensionInputs: readonly MigrateExtensionInput[] = (config.extensionPacks ?? []).map(
-    (pack) => {
-      const cs = (pack as { readonly contractSpace?: MigrateExtensionInput['contractSpace'] })
-        .contractSpace;
-      return cs !== undefined ? { id: pack.id, contractSpace: cs } : { id: pack.id };
-    },
-  );
+  // Single descriptor-import boundary: every consumer of `extensionPacks`
+  // goes through `toExtensionInputs` + a per-consumer adapter. AC11.
+  const canonicalExtensionInputs = toExtensionInputs(config.extensionPacks ?? []);
   const migratePass = await runContractSpaceMigratePass({
     migrationsDir,
-    extensionPacks: extensionInputs,
+    extensionPacks: toMigratePassInputs(canonicalExtensionInputs),
   });
   if (!flags.json && !flags.quiet) {
     for (const drift of migratePass.drifts) {
@@ -257,19 +267,9 @@ async function executeMigrationPlanCommand(
   // Idempotent (existing dirs are left untouched).
   // Uses `planAllSpaces` for deterministic ordering + duplicate-spaceId
   // detection.
-  const extensionMigrationsInputs: readonly ExtensionMigrationsExtensionInput[] = (
-    config.extensionPacks ?? []
-  ).map((pack) => {
-    const cs = (
-      pack as {
-        readonly contractSpace?: ExtensionMigrationsExtensionInput['contractSpace'];
-      }
-    ).contractSpace;
-    return cs !== undefined ? { id: pack.id, contractSpace: cs } : { id: pack.id };
-  });
   const extensionMigrationsResult = await runContractSpaceExtensionMigrationsPass({
     migrationsDir,
-    extensionPacks: extensionMigrationsInputs,
+    extensionPacks: toExtensionMigrationsInputs(canonicalExtensionInputs),
   });
   if (!flags.json && !flags.quiet) {
     for (const entry of extensionMigrationsResult.emitted) {
@@ -285,6 +285,7 @@ async function executeMigrationPlanCommand(
       from: fromHash,
       to: toStorageHash,
       operations: [],
+      emittedExtensionDirs: extensionMigrationsResult.emitted,
       summary: 'No changes detected between contracts',
       timings: { total: Date.now() - startTime },
     };
@@ -420,6 +421,7 @@ async function executeMigrationPlanCommand(
         to: toStorageHash,
         dir: relative(process.cwd(), packageDir),
         operations: [],
+        emittedExtensionDirs: extensionMigrationsResult.emitted,
         pendingPlaceholders: true,
         summary:
           'Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
@@ -442,8 +444,9 @@ async function executeMigrationPlanCommand(
         label: op.label,
         operationClass: op.operationClass,
       })),
+      emittedExtensionDirs: extensionMigrationsResult.emitted,
       ...(preview !== undefined ? { preview } : {}),
-      summary: `Planned ${plannedOps.length} operation(s)`,
+      summary: buildPlanSummary(plannedOps.length, extensionMigrationsResult.emitted.length),
       timings: { total: Date.now() - startTime },
     };
     return ok(result);
@@ -501,7 +504,29 @@ export function createMigrationPlanCommand(): Command {
   return command;
 }
 
-function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFlags): string {
+/**
+ * Compose the success-line summary so the cross-space side effect
+ * (extension-space migration packages materialised on disk during
+ * this `plan` run) is visible in the top line — not just in the
+ * step log above it.
+ *
+ * Example outputs:
+ *   - `Planned 3 operation(s)` (app-space-only project)
+ *   - `Planned 3 operation(s); materialised 1 extension-space migration` (one extension)
+ *   - `Planned 3 operation(s); materialised 2 extension-space migrations` (two extensions)
+ *
+ * Locks AC3 at the summary-line level: a reader of the success line
+ * can tell that something happened beyond the app space.
+ */
+function buildPlanSummary(plannedOpsCount: number, emittedExtensionDirsCount: number): string {
+  const base = `Planned ${plannedOpsCount} operation(s)`;
+  if (emittedExtensionDirsCount === 0) return base;
+  const noun =
+    emittedExtensionDirsCount === 1 ? 'extension-space migration' : 'extension-space migrations';
+  return `${base}; materialised ${emittedExtensionDirsCount} ${noun}`;
+}
+
+export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFlags): string {
   const lines: string[] = [];
   const useColor = flags.color !== false;
 
@@ -509,10 +534,29 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
   const yellow_ = useColor ? (s: string) => `\x1b[33m${s}\x1b[0m` : (s: string) => s;
   const dim_ = useColor ? (s: string) => `\x1b[2m${s}\x1b[0m` : (s: string) => s;
 
+  // Renders the extension-space materialisation block + canonical apply-step
+  // hint shared by the no-op, placeholder, and full-plan branches. The app
+  // space short-circuits do not skip it: an extension-only bump emits new
+  // `migrations/<spaceId>/<dirName>/` directories on disk that the user
+  // still has to apply, so the success line must surface them.
+  function appendEmittedExtensions(): void {
+    if (result.emittedExtensionDirs.length === 0) return;
+    lines.push('');
+    lines.push(dim_('Emitted extension migrations:'));
+    for (const entry of result.emittedExtensionDirs) {
+      lines.push(dim_(`  ${entry.spaceId} → migrations/${entry.spaceId}/${entry.dirName}`));
+    }
+    lines.push('');
+    lines.push(
+      `Next: review the extension migrations above, then run ${green_('prisma-next migration apply')}.`,
+    );
+  }
+
   if (result.noOp) {
     lines.push(`${green_('✔')} No changes detected`);
     lines.push(dim_(`  from: ${result.from}`));
     lines.push(dim_(`  to:   ${result.to}`));
+    appendEmittedExtensions();
     return lines.join('\n');
   }
 
@@ -529,6 +573,7 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
       'Open migration.ts and replace each `placeholder(...)` call with your actual query.',
     );
     lines.push(`Then run: ${green_(`node ${result.dir ?? '<dir>'}/migration.ts`)}`);
+    appendEmittedExtensions();
     return lines.join('\n');
   }
 
@@ -541,11 +586,11 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
       const op = result.operations[i]!;
       const isLast = i === result.operations.length - 1;
       const treeChar = isLast ? '└' : '├';
-      const opClassLabel =
-        op.operationClass === 'destructive'
-          ? yellow_(`[${op.operationClass}]`)
-          : dim_(`[${op.operationClass}]`);
-      lines.push(`${dim_(treeChar)}─ ${op.label} ${opClassLabel}`);
+      // operationClass tag is intentionally NOT inlined per spec:
+      // a destructive footer warning still surfaces below this list.
+      const destructiveMarker =
+        op.operationClass === 'destructive' ? ` ${yellow_('(destructive)')}` : '';
+      lines.push(`${dim_(treeChar)}─ ${op.label}${destructiveMarker}`);
     }
 
     const hasDestructive = result.operations.some((op) => op.operationClass === 'destructive');
@@ -561,10 +606,22 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
   lines.push(dim_(`from:   ${result.from}`));
   lines.push(dim_(`to:     ${result.to}`));
   if (result.dir) {
-    lines.push(dim_(`dir:    ${result.dir}`));
+    lines.push(dim_(`App space → ${result.dir}`));
+  }
+  // Per-space block: surface the extension-space directories materialised
+  // alongside the app-space migration. Without this block the cross-space
+  // side effect is invisible in the success summary (e2e finding F1).
+  for (const entry of result.emittedExtensionDirs) {
+    lines.push(
+      dim_(`Extension space ${entry.spaceId} → migrations/${entry.spaceId}/${entry.dirName}`),
+    );
   }
 
   lines.push('');
+  // The "Next:" hint always points at the canonical apply path
+  // (`prisma-next migration apply`) regardless of how many spaces
+  // were materialised — `db update` is a dev-time convenience, not
+  // the canonical replay step.
   lines.push(
     `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migration apply')}.`,
   );