@prisma-next/cli 0.5.0-dev.9 → 0.5.1

package/src/commands/migration-status.ts

@@ -1,18 +1,26 @@
-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,
+  errorUnknownInvariant,
+  MigrationToolsError,
+} from '@prisma-next/migration-tools/errors';
+import type { MigrationEdge, MigrationGraph } from '@prisma-next/migration-tools/graph';
 import {
   findPath,
   findPathWithDecision,
   findReachableLeaves,
-} from '@prisma-next/migration-tools/dag';
-import type { Refs } from '@prisma-next/migration-tools/refs';
+} from '@prisma-next/migration-tools/migration-graph';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import type { RefEntry, Refs } from '@prisma-next/migration-tools/refs';
 import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
-import type {
-  MigrationBundle,
-  MigrationChainEntry,
-  MigrationGraph,
-} from '@prisma-next/migration-tools/types';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { cyan, dim, magenta, yellow } from 'colorette';
@@ -20,17 +28,28 @@ import { Command } from 'commander';
 
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
-import { type CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import {
+  type CliStructuredError,
+  errorRuntime,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadAllBundles,
+  collectDeclaredInvariants,
+  loadMigrationPackages,
   maskConnectionUrl,
   readContractEnvelope,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   toPathDecisionResult,
+  toStructuralEdge,
 } from '../utils/command-helpers';
+import {
+  type BuildAggregateInputs,
+  buildContractSpaceAggregate,
+} from '../utils/contract-space-aggregate-loader';
 import {
   type EdgeStatus,
   type EdgeStatusKind,
@@ -61,13 +80,60 @@ export interface MigrationStatusEntry {
   readonly dirName: string;
   readonly from: string;
   readonly to: string;
-  readonly migrationId: string;
+  readonly migrationHash: string;
   readonly operationCount: number;
   readonly operationSummary: string;
   readonly hasDestructive: boolean;
   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 {
@@ -78,23 +144,55 @@ export interface MigrationStatusResult {
   readonly targetHash: string;
   readonly contractHash: string;
   readonly refs?: readonly StatusRef[];
+  /** Required invariants from the active ref, sorted ascending. Always present (`[]` when no `--ref` or the ref declares none) — knowable offline. */
+  readonly requiredInvariants: readonly string[];
+  /**
+   * Invariants the marker has applied at least once, intersected with
+   * `requiredInvariants` for display relevance. JSON consumers see only the
+   * subset overlapping the active ref's required set — the full unfiltered
+   * marker invariant list lives on `marker.invariants` (control plane) and
+   * is not surfaced here. Present only in `mode === 'online'`; absent when
+   * offline (the marker is unknown, not empty).
+   */
+  readonly appliedInvariants?: readonly string[];
+  /** required − applied. Present only in `mode === 'online'`; absent when offline. */
+  readonly missingInvariants?: readonly 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 migrationId: string;
+      readonly migrationHash: string;
       readonly from: string;
       readonly to: string;
+      readonly invariants: readonly string[];
     }[];
   };
   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 MigrationBundle[];
+  readonly bundles?: readonly OnDiskMigrationPackage[];
   readonly edgeStatuses?: readonly EdgeStatus[];
   readonly activeRefHash?: string;
   readonly activeRefName?: string;
@@ -154,7 +252,7 @@ export function deriveEdgeStatuses(
 ): EdgeStatus[] {
   if (mode === 'offline') return [];
 
-  const edgeKey = (e: MigrationChainEntry) => `${e.from}\0${e.to}`;
+  const edgeKey = (e: MigrationEdge) => `${e.from}\0${e.to}`;
 
   // No marker = empty DB — treat root as the marker (nothing applied, everything pending)
   const effectiveMarker = markerHash ?? EMPTY_CONTRACT_HASH;
@@ -224,8 +322,8 @@ export function deriveEdgeStatuses(
  * @param markerHash — the marker hash from the database, or undefined if no marker row / offline
  */
 function buildMigrationEntries(
-  chain: readonly MigrationChainEntry[],
-  packages: readonly MigrationBundle[],
+  chain: readonly MigrationEdge[],
+  packages: readonly OnDiskMigrationPackage[],
   mode: 'online' | 'offline',
   markerHash: string | undefined,
   edgeStatuses?: readonly EdgeStatus[],
@@ -261,7 +359,7 @@ function buildMigrationEntries(
       dirName: migration.dirName,
       from: migration.from,
       to: migration.to,
-      migrationId: migration.migrationId,
+      migrationHash: migration.migrationHash,
       operationCount: ops.length,
       operationSummary: summary,
       hasDestructive,
@@ -294,7 +392,7 @@ function resolveDisplayChain(
   graph: MigrationGraph,
   targetHash: string,
   markerHash: string | undefined,
-): readonly MigrationChainEntry[] | null {
+): readonly MigrationEdge[] | null {
   if (markerHash === undefined) {
     return findPath(graph, EMPTY_CONTRACT_HASH, targetHash);
   }
@@ -339,34 +437,146 @@ 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') {
+      // Count pending *migrations* (graph edges), not operations: a
+      // single authored migration that lowers to N ops or zero ops
+      // both count as exactly one pending unit of work for the user.
+      pendingCount = walked.result.migrationEdges?.length ?? 0;
+      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, migrationsDir, migrationsRelative, 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;
 
   let activeRefName: string | undefined;
   let activeRefHash: string | undefined;
+  let activeRefEntry: RefEntry | undefined;
   let allRefs: Refs = {};
   try {
     allRefs = await readRefs(refsDir);
   } catch (error) {
     if (MigrationToolsError.is(error)) {
-      return notOk(
-        errorRuntime(error.message, {
-          why: error.why,
-          fix: error.fix,
-          meta: { code: error.code },
-        }),
-      );
+      return notOk(mapMigrationToolsError(error));
     }
     throw error;
   }
@@ -374,21 +584,18 @@ async function executeMigrationStatusCommand(
   if (options.ref) {
     activeRefName = options.ref;
     try {
-      activeRefHash = resolveRef(allRefs, activeRefName).hash;
+      activeRefEntry = resolveRef(allRefs, activeRefName);
+      activeRefHash = activeRefEntry.hash;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
-        return notOk(
-          errorRuntime(error.message, {
-            why: error.why,
-            fix: error.fix,
-            meta: { code: error.code },
-          }),
-        );
+        return notOk(mapMigrationToolsError(error));
       }
       throw error;
     }
   }
 
+  const requiredInvariants: readonly string[] = [...(activeRefEntry?.invariants ?? [])].sort();
+
   const statusRefs: StatusRef[] = Object.entries(allRefs).map(([name, entry]) => ({
     name,
     hash: entry.hash,
@@ -398,7 +605,7 @@ async function executeMigrationStatusCommand(
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
-      { label: 'migrations', value: migrationsRelative },
+      { label: 'migrations', value: appMigrationsRelative },
     ];
     if (dbConnection && hasDriver) {
       details.push({ label: 'database', value: maskConnectionUrl(String(dbConnection)) });
@@ -406,6 +613,12 @@ async function executeMigrationStatusCommand(
     if (activeRefName) {
       details.push({ label: 'ref', value: activeRefName });
     }
+    if (activeRefEntry && activeRefEntry.invariants.length > 0) {
+      details.push({
+        label: 'required',
+        value: formatInvariantList(activeRefEntry.invariants),
+      });
+    }
     const header = formatStyledHeader({
       command: 'migration status',
       description: 'Show migration history and applied status',
@@ -429,15 +642,13 @@ async function executeMigrationStatusCommand(
     });
   }
 
-  let bundles: readonly MigrationBundle[];
+  let bundles: readonly OnDiskMigrationPackage[];
   let graph: MigrationGraph;
   try {
-    ({ bundles, graph } = await loadAllBundles(migrationsDir));
+    ({ bundles, graph } = await loadMigrationPackages(appMigrationsDir));
   } catch (error) {
     if (MigrationToolsError.is(error)) {
-      return notOk(
-        errorRuntime(error.message, { why: error.why, fix: error.fix, meta: { code: error.code } }),
-      );
+      return notOk(mapMigrationToolsError(error));
     }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
@@ -465,6 +676,7 @@ async function executeMigrationStatusCommand(
       contractHash,
       summary: 'No migrations found',
       diagnostics,
+      requiredInvariants,
     });
   }
 
@@ -492,7 +704,9 @@ 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({
@@ -504,8 +718,30 @@ async function executeMigrationStatusCommand(
     });
     try {
       await client.connect(dbConnection);
-      markerHash = (await client.readMarker())?.storageHash;
+      const marker = await client.readMarker();
+      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.
+      //
+      // Probe for the method first so we only swallow the
+      // unsupported-method case: older family instances may not
+      // implement `readAllMarkers` (per-space enumeration then falls
+      // back to "marker unknown"). Real query / runtime errors from
+      // an instance that *does* expose the method must propagate up
+      // — otherwise transient DB failures would silently degrade
+      // status to "markers unknown".
+      if (typeof client.readAllMarkers === 'function') {
+        allMarkers = await client.readAllMarkers();
+      } else {
+        // 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');
@@ -515,6 +751,63 @@ 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
+  // route fine because marker subtraction empties `effectiveRequired`.
+  // Offline: keep the check graph-strict (the marker is unknown, and a
+  // missing declarer is the dominant signal we can offer).
+  if (activeRefEntry && activeRefEntry.invariants.length > 0) {
+    const declared = collectDeclaredInvariants(graph);
+    const known = new Set<string>(declared);
+    if (mode === 'online') {
+      for (const id of markerInvariants) known.add(id);
+    }
+    const unknown = activeRefEntry.invariants.filter((id) => !known.has(id));
+    if (unknown.length > 0) {
+      return notOk(
+        mapMigrationToolsError(
+          errorUnknownInvariant({
+            ...ifDefined('refName', activeRefName),
+            unknown,
+            declared: [...declared].sort(),
+          }),
+        ),
+      );
+    }
+  }
+
   // Marker exists but is not in the migration graph and doesn't match the
   // contract hash. The DB is at an unknown state relative to the graph.
   // Bail out early with a clear diagnostic instead of rendering a confusing
@@ -560,6 +853,7 @@ async function executeMigrationStatusCommand(
       summary: `${bundles.length} migration(s) on disk`,
       diagnostics,
       markerHash,
+      requiredInvariants,
       ...(statusRefs.length > 0 ? { refs: statusRefs } : {}),
     });
   }
@@ -600,6 +894,7 @@ async function executeMigrationStatusCommand(
       summary: `${bundles.length} migration(s) on disk`,
       diagnostics,
       ...ifDefined('markerHash', markerHash),
+      requiredInvariants,
       ...(statusRefs.length > 0 ? { refs: statusRefs } : {}),
       graph,
       bundles,
@@ -624,14 +919,39 @@ async function executeMigrationStatusCommand(
   const pendingCount = edgeStatuses.filter((e) => e.status === 'pending').length;
   const appliedCount = edgeStatuses.filter((e) => e.status === 'applied').length;
 
+  let appliedInvariants: readonly string[] | undefined;
+  let missingInvariants: readonly string[] | undefined;
+  let effectiveRequired = new Set<string>();
+  if (mode === 'online') {
+    // Mirrors `migration-apply.ts`: compute `effectiveRequired = required −
+    // marker.invariants` directly, then derive the display fields from it.
+    // `appliedInvariants` is the intersection (`required ∩ marker`), which
+    // is what JSON consumers see for the active ref; the unfiltered set
+    // lives on `marker.invariants`.
+    const markerSet = new Set(markerInvariants);
+    effectiveRequired = new Set(requiredInvariants.filter((id) => !markerSet.has(id)));
+    appliedInvariants = requiredInvariants.filter((id) => markerSet.has(id));
+    missingInvariants = [...effectiveRequired].sort();
+  }
+
+  // The marker can match the structural target while still missing required
+  // invariants — for example, a self-edge that provides X, applied via a ref
+  // declaring X. `pendingCount` (structural) says zero in that case but
+  // `effectiveRequired` is non-empty, so up-to-date messaging would mislead.
+  const hasInvariantWork = effectiveRequired.size > 0;
+  const missingList = [...effectiveRequired].sort().join(', ');
+
   let summary: string;
   if (mode === 'online') {
     if (markerHash !== undefined && !graph.nodes.has(markerHash) && markerHash === contractHash) {
       summary = `${bundles.length} migration(s) on disk`;
     } else if (activeRefHash && markerHash !== undefined) {
-      summary = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName!);
-    } else if (pendingCount === 0) {
+      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName!);
+      summary = hasInvariantWork ? `${distance} — missing invariant(s): ${missingList}` : distance;
+    } else if (pendingCount === 0 && !hasInvariantWork) {
       summary = `Database is up to date (${appliedCount} migration${appliedCount !== 1 ? 's' : ''} applied)`;
+    } else if (pendingCount === 0 && hasInvariantWork) {
+      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply`;
     } else if (markerHash === undefined) {
       summary = `${pendingCount} pending migration(s) — database has no marker`;
     } else {
@@ -641,6 +961,37 @@ async function executeMigrationStatusCommand(
     summary = `${entries.length} migration(s) on disk`;
   }
 
+  let pathDecision: MigrationStatusResult['pathDecision'];
+  let routingUnreachable = false;
+  if (mode === 'online') {
+    const originHash = markerHash ?? EMPTY_CONTRACT_HASH;
+    const outcome = findPathWithDecision(graph, originHash, targetHash, {
+      ...ifDefined('refName', activeRefName),
+      required: effectiveRequired,
+    });
+    if (outcome.kind === 'ok') {
+      pathDecision = toPathDecisionResult(outcome.decision);
+    } else if (outcome.kind === 'unsatisfiable') {
+      return notOk(
+        mapMigrationToolsError(
+          errorNoInvariantPath({
+            ...ifDefined('refName', activeRefName),
+            required: [...effectiveRequired].sort(),
+            missing: outcome.missing,
+            structuralPath: outcome.structuralPath.map(toStructuralEdge),
+          }),
+        ),
+      );
+    } else {
+      // outcome.kind === 'unreachable' — origin (marker) has no structural
+      // path to the active target. `pendingCount` and `hasInvariantWork`
+      // both report zero in this case, but emitting MIGRATION.UP_TO_DATE
+      // would be wrong: the database simply cannot reach the requested
+      // ref/contract from its current state. Suppress UP_TO_DATE below.
+      routingUnreachable = true;
+    }
+  }
+
   if (mode === 'online') {
     if (markerHash !== undefined && !graph.nodes.has(markerHash) && markerHash === contractHash) {
       diagnostics.push({
@@ -657,7 +1008,16 @@ async function executeMigrationStatusCommand(
         message: `${pendingCount} migration(s) pending`,
         hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
       });
-    } else {
+    } else if (hasInvariantWork) {
+      diagnostics.push({
+        code: 'MIGRATION.INVARIANTS_PENDING',
+        severity: 'info',
+        message: `Missing required invariant(s): ${missingList}`,
+        hints: [
+          `Run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
+        ],
+      });
+    } else if (!routingUnreachable) {
       diagnostics.push({
         code: 'MIGRATION.UP_TO_DATE',
         severity: 'info',
@@ -667,14 +1027,6 @@ async function executeMigrationStatusCommand(
     }
   }
 
-  let pathDecision: MigrationStatusResult['pathDecision'];
-  if (mode === 'online' && markerHash !== undefined) {
-    const decision = findPathWithDecision(graph, markerHash, targetHash, activeRefName);
-    if (decision) {
-      pathDecision = toPathDecisionResult(decision);
-    }
-  }
-
   const result: MigrationStatusResult = {
     ok: true,
     mode,
@@ -684,6 +1036,9 @@ async function executeMigrationStatusCommand(
     summary,
     diagnostics,
     ...ifDefined('markerHash', markerHash),
+    requiredInvariants,
+    ...ifDefined('appliedInvariants', appliedInvariants),
+    ...ifDefined('missingInvariants', missingInvariants),
     ...(statusRefs.length > 0 ? { refs: statusRefs } : {}),
     ...ifDefined('pathDecision', pathDecision),
     graph,
@@ -691,6 +1046,8 @@ async function executeMigrationStatusCommand(
     edgeStatuses,
     ...ifDefined('activeRefHash', activeRefHash),
     ...ifDefined('activeRefName', activeRefName),
+    spaces: aggregateSpaces,
+    ...ifDefined('totalPendingAcrossSpaces', totalPendingAcrossSpaces),
   };
   return ok(result);
 }
@@ -724,13 +1081,19 @@ export function createMigrationStatusCommand(): Command {
 
       const exitCode = handleResult(result, flags, ui, (statusResult) => {
         if (flags.json) {
+          // Strip non-JSON-shape fields before emitting. These belong to
+          // the in-memory result so the human renderer can avoid
+          // recomputing them, but they would either bloat the wire format
+          // (graph, bundles, edgeStatuses) or expose internals
+          // (activeRefHash, activeRefName, diverged) that consumers should
+          // read off `pathDecision` / `refs` instead.
           const {
-            graph: _g,
-            bundles: _b,
-            edgeStatuses: _es,
-            activeRefHash: _arh,
-            activeRefName: _arn,
-            diverged: _d,
+            graph: _graph,
+            bundles: _bundles,
+            edgeStatuses: _edgeStatuses,
+            activeRefHash: _activeRefHash,
+            activeRefName: _activeRefName,
+            diverged: _diverged,
             ...jsonResult
           } = statusResult;
           ui.output(JSON.stringify(jsonResult, null, 2));
@@ -789,7 +1152,7 @@ function formatLegend(colorize: boolean): string {
   return c(dim, parts.join('  '));
 }
 
-function formatStatusSummary(result: MigrationStatusResult, colorize: boolean): string {
+export function formatStatusSummary(result: MigrationStatusResult, colorize: boolean): string {
   const c = (fn: (s: string) => string, s: string) => (colorize ? fn(s) : s);
   const lines: string[] = [];
 
@@ -797,11 +1160,16 @@ function formatStatusSummary(result: MigrationStatusResult, colorize: boolean):
   const pendingCount = result.migrations.filter((e) => e.status === 'pending').length;
 
   const hasWarnings = result.diagnostics?.some((d) => d.severity === 'warn') ?? false;
+  // INVARIANTS_PENDING is filed at severity 'info' (per ADR 208) so the
+  // warn-severity check above doesn't see it. It still represents pending
+  // work, so it must promote the summary off the success icon.
+  const hasInvariantPending =
+    result.diagnostics?.some((d) => d.code === 'MIGRATION.INVARIANTS_PENDING') ?? false;
 
   if (result.mode === 'online') {
     if (hasUnknown || hasWarnings) {
       lines.push(`${c(yellow, '⚠')} ${result.summary}`);
-    } else if (pendingCount === 0) {
+    } else if (pendingCount === 0 && !hasInvariantPending) {
       lines.push(`${c(cyan, '✔')} ${result.summary}`);
     } else {
       lines.push(`${c(yellow, '⧗')} ${result.summary}`);
@@ -810,6 +1178,15 @@ function formatStatusSummary(result: MigrationStatusResult, colorize: boolean):
     lines.push(result.summary);
   }
 
+  if (result.requiredInvariants.length > 0) {
+    if (result.appliedInvariants !== undefined && result.missingInvariants !== undefined) {
+      lines.push(`${c(dim, 'applied  ')}${formatInvariantList(result.appliedInvariants)}`);
+      lines.push(`${c(dim, 'missing  ')}${formatInvariantList(result.missingInvariants)}`);
+    } else {
+      lines.push(`${c(dim, 'applied  ')}(unknown — connect a database to evaluate)`);
+    }
+  }
+
   const warnings = result.diagnostics?.filter((d) => d.severity === 'warn') ?? [];
   for (const diag of warnings) {
     lines.push(`${c(yellow, '⚠')} ${diag.message}`);
@@ -818,9 +1195,59 @@ function formatStatusSummary(result: MigrationStatusResult, colorize: boolean):
     }
   }
 
+  // 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(', ');
+}
+
 function summarizeRefDistance(
   graph: MigrationGraph,
   markerHash: string,