@prisma-next/cli 0.6.0-dev.1 → 0.6.0-dev.10

package/src/commands/migration-plan.ts

@@ -2,7 +2,6 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import {
-  APP_SPACE_ID,
   createControlStack,
   hasOperationPreview,
   type MigrationPlanOperation,
@@ -43,16 +42,9 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import { runContractSpaceExtensionMigrationsPass } from '../utils/contract-space-extension-migrations-pass';
-import {
-  formatContractSpaceDriftWarning,
-  runContractSpaceMigratePass,
-} from '../utils/contract-space-migrate-pass';
-import {
-  toExtensionInputs,
-  toExtensionMigrationsInputs,
-  toMigratePassInputs,
-} from '../utils/extension-pack-inputs';
+import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
+import { runContractSpaceSeedPhase } from '../utils/contract-space-seed-phase';
+import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -241,41 +233,30 @@ async function executeMigrationPlanCommand(
     );
   }
 
-  // Per-space migrate pass: drift detection + on-disk artefact emission for
-  // every loaded extension that exposes a `contractSpace`. Runs *before*
-  // the app-space no-op check so that an extension bump alone (with no
-  // 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.
-  // Single descriptor-import boundary: every consumer of `extensionPacks`
-  // goes through `toExtensionInputs` + a per-consumer adapter. AC11.
+  // Phase 1 — seed: unconditionally re-emit per-space pinned artefacts
+  // (contract.json / contract.d.ts / refs/head.json) and materialise any
+  // descriptor-shipped migration packages not yet on disk. Runs before
+  // the no-op check so that an extension bump alone (with no structural
+  // app-space change) still re-pins extension artefacts on disk.
   const canonicalExtensionInputs = toExtensionInputs(config.extensionPacks ?? []);
-  const migratePass = await runContractSpaceMigratePass({
+  const seedResult = await runContractSpaceSeedPhase({
     migrationsDir,
-    extensionPacks: toMigratePassInputs(canonicalExtensionInputs),
+    extensionPacks: canonicalExtensionInputs,
   });
   if (!flags.json && !flags.quiet) {
-    for (const drift of migratePass.drifts) {
-      if (drift.kind === 'drift') {
-        ui.stderr(formatContractSpaceDriftWarning(drift));
+    for (const record of seedResult.seeded) {
+      if (record.action === 'updated') {
+        const pkgSuffix =
+          record.newMigrationDirs.length > 0
+            ? `; ${record.newMigrationDirs.length} new migration package(s) materialised`
+            : '';
+        ui.step(`Updated ${record.spaceId} to ${record.newHash}${pkgSuffix}`);
       }
     }
   }
-
-  // Materialise descriptor-shipped migration packages onto disk under
-  // `migrations/<spaceId>/<dirName>/` for any package not yet present.
-  // Idempotent (existing dirs are left untouched).
-  // Uses `planAllSpaces` for deterministic ordering + duplicate-spaceId
-  // detection.
-  const extensionMigrationsResult = await runContractSpaceExtensionMigrationsPass({
-    migrationsDir,
-    extensionPacks: toExtensionMigrationsInputs(canonicalExtensionInputs),
-  });
-  if (!flags.json && !flags.quiet) {
-    for (const entry of extensionMigrationsResult.emitted) {
-      ui.step(`Emitted ${entry.spaceId}/${entry.dirName}`);
-    }
-  }
+  const emittedExtensionDirs = seedResult.seeded.flatMap((r) =>
+    r.newMigrationDirs.map((dirName) => ({ spaceId: r.spaceId, dirName })),
+  );
 
   // Check for no-op (same hash means no changes)
   if (fromHash === toStorageHash) {
@@ -285,7 +266,7 @@ async function executeMigrationPlanCommand(
       from: fromHash,
       to: toStorageHash,
       operations: [],
-      emittedExtensionDirs: extensionMigrationsResult.emitted,
+      emittedExtensionDirs,
       summary: 'No changes detected between contracts',
       timings: { total: Date.now() - startTime },
     };
@@ -301,6 +282,25 @@ async function executeMigrationPlanCommand(
       }),
     );
   }
+
+  // Phase 2 — load: build the aggregate against the now-consistent disk
+  // state that phase 1 just seeded. The seed phase guarantees every
+  // declared extension has its head ref pinned, so the loader's
+  // declaredButUnmigrated precheck always passes here.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+  const aggregateResult = await buildContractSpaceAggregate({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: toContractJson,
+    extensionPacks: config.extensionPacks ?? [],
+    validateContract: (json: unknown) => familyInstance.validateContract(json),
+  });
+  if (!aggregateResult.ok) {
+    return notOk(aggregateResult.failure);
+  }
+  const aggregate = aggregateResult.value;
+
   const frameworkComponents = assertFrameworkComponentsCompatible(
     config.family.familyId,
     config.target.targetId,
@@ -328,17 +328,15 @@ async function executeMigrationPlanCommand(
   };
 
   try {
-    const stack = createControlStack(config);
-    const familyInstance = config.family.create(stack);
     const planner = migrations.createPlanner(familyInstance);
     const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
     const plannerResult = planner.plan({
-      contract: toContractJson,
+      contract: aggregate.app.contract,
       schema: fromSchema,
       policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
       fromContract,
       frameworkComponents,
-      spaceId: APP_SPACE_ID,
+      spaceId: aggregate.app.spaceId,
     });
     if (plannerResult.kind === 'failure') {
       return notOk(
@@ -421,7 +419,7 @@ async function executeMigrationPlanCommand(
         to: toStorageHash,
         dir: relative(process.cwd(), packageDir),
         operations: [],
-        emittedExtensionDirs: extensionMigrationsResult.emitted,
+        emittedExtensionDirs,
         pendingPlaceholders: true,
         summary:
           'Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
@@ -444,9 +442,9 @@ async function executeMigrationPlanCommand(
         label: op.label,
         operationClass: op.operationClass,
       })),
-      emittedExtensionDirs: extensionMigrationsResult.emitted,
+      emittedExtensionDirs,
       ...(preview !== undefined ? { preview } : {}),
-      summary: buildPlanSummary(plannedOps.length, extensionMigrationsResult.emitted.length),
+      summary: buildPlanSummary(plannedOps.length, emittedExtensionDirs.length),
       timings: { total: Date.now() - startTime },
     };
     return ok(result);

package/src/commands/migration-show.ts

@@ -1,6 +1,9 @@
-import type {
-  MigrationPlanOperation,
-  OperationPreview,
+import { readFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
+import {
+  createControlStack,
+  type MigrationPlanOperation,
+  type OperationPreview,
 } from '@prisma-next/framework-components/control';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { readMigrationPackage, readMigrationsDir } from '@prisma-next/migration-tools/io';
@@ -9,23 +12,29 @@ import {
   reconstructGraph,
 } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
-import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-tools/spaces';
+import { spaceMigrationDirectory } from '@prisma-next/migration-tools/spaces';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { relative, resolve } from 'pathe';
+import { isAbsolute, relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
   type CliStructuredError,
+  errorContractValidationFailed,
+  errorFileNotFound,
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  resolveContractPath,
+  resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatMigrationShowOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -37,8 +46,12 @@ interface MigrationShowOptions extends CommonCommandOptions {
   readonly config?: string;
 }
 
-export interface MigrationShowResult {
-  readonly ok: true;
+/**
+ * Details of one space's latest (or targeted) migration package.
+ */
+export interface MigrationShowSpacePresent {
+  readonly kind: 'present';
+  readonly spaceId: string;
   readonly dirName: string;
   readonly dirPath: string;
   readonly from: string | null;
@@ -51,19 +64,78 @@ export interface MigrationShowResult {
     readonly operationClass: string;
   }[];
   /**
-   * Family-agnostic textual preview of the migration's operations. Replaces
-   * the previous string-array DDL field. Always defined; statements is empty
-   * for a no-op migration or a family that does not implement the
-   * `OperationPreviewCapable` capability.
+   * Family-agnostic textual preview of the migration's operations. Always
+   * defined; statements is empty for a no-op migration or a family that does
+   * not implement the `OperationPreviewCapable` capability.
    */
   readonly preview: OperationPreview;
   readonly summary: string;
 }
 
+/**
+ * Placeholder for a loaded contract space that has no on-disk migration
+ * package — the extension descriptor declared the space but no migrations
+ * directory has been materialised for it yet. Surfaces the space in the
+ * response so JSON consumers see every loaded extension instead of having
+ * silently-skipped entries.
+ */
+export interface MigrationShowSpaceMissing {
+  readonly kind: 'missing';
+  readonly spaceId: string;
+  readonly summary: string;
+}
+
+export type MigrationShowSpaceResult = MigrationShowSpacePresent | MigrationShowSpaceMissing;
+
+export interface MigrationShowResult {
+  readonly ok: true;
+  /**
+   * Per-space results, ordered: app first, then extensions alphabetically
+   * (matching the aggregate's canonical ordering).
+   */
+  readonly spaces: readonly MigrationShowSpaceResult[];
+}
+
 function looksLikePath(target: string): boolean {
   return target.includes('/') || target.includes('\\');
 }
 
+/**
+ * Validate that a path-like `migration show` target resolves inside the app
+ * migrations directory. The returned result is always emitted under
+ * `aggregate.app.spaceId`, so accepting an extension-space (or otherwise
+ * external) path here would silently mislabel the result. Returns the
+ * resolved absolute path on success.
+ *
+ * `pathe.relative` can return an absolute path when the target cannot be
+ * expressed relative to the base (e.g. on Windows when `target` is on a
+ * different drive than `appMigrationsDir`). That case does not start with
+ * `..`, so the absolute-check below is required to reject cross-drive
+ * targets rather than mislabeling them as app-space.
+ */
+export function resolveAppTargetPath(
+  target: string,
+  appMigrationsDir: string,
+  appMigrationsRelative: string,
+): Result<string, CliStructuredError> {
+  const targetPath = resolve(target);
+  const relativeToApp = relative(appMigrationsDir, targetPath);
+  const isOutsideAppDir =
+    relativeToApp === '' ||
+    relativeToApp === '.' ||
+    relativeToApp.startsWith('..') ||
+    isAbsolute(relativeToApp);
+  if (isOutsideAppDir) {
+    return notOk(
+      errorRuntime('Target must point to an app-space migration', {
+        why: `Expected a path under ${appMigrationsRelative}, got ${target}`,
+        fix: 'Pass an app-space migration directory or use a hash prefix.',
+      }),
+    );
+  }
+  return ok(targetPath);
+}
+
 export function resolveByHashPrefix(
   packages: readonly OnDiskMigrationPackage[],
   prefix: string,
@@ -93,6 +165,71 @@ export function resolveByHashPrefix(
   );
 }
 
+/**
+ * Resolve the latest migration from a space directory.
+ *
+ * Returns `ok(null)` only when the directory is empty or absent (ENOENT is
+ * absorbed by `readMigrationsDir`). If `readMigrationsDir` returned packages
+ * but `findLatestMigration` cannot pick a leaf, the on-disk history is
+ * corrupt — return a runtime error rather than collapsing it to a `missing`
+ * placeholder, which would hide the corruption from the caller.
+ */
+export async function resolveLatestFromDir(
+  spaceDir: string,
+): Promise<Result<OnDiskMigrationPackage | null, CliStructuredError>> {
+  try {
+    const allPackages = await readMigrationsDir(spaceDir);
+    if (allPackages.length === 0) return ok(null);
+    const graph = reconstructGraph(allPackages);
+    const latestMigration = findLatestMigration(graph);
+    if (!latestMigration) {
+      return notOk(
+        errorRuntime('Could not resolve latest migration', {
+          why: `No latest migration found in ${relative(process.cwd(), spaceDir)}`,
+          fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
+        }),
+      );
+    }
+    const leafPkg = allPackages.find(
+      (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+    );
+    return ok(leafPkg ?? null);
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+}
+
+function pkgToSpaceResult(
+  spaceId: string,
+  pkg: OnDiskMigrationPackage,
+  client: ReturnType<typeof createControlClient>,
+): MigrationShowSpacePresent {
+  const ops = pkg.ops as readonly MigrationPlanOperation[];
+  const preview: OperationPreview = client.toOperationPreview(ops) ?? { statements: [] };
+  return {
+    kind: 'present',
+    spaceId,
+    dirName: pkg.dirName,
+    dirPath: relative(process.cwd(), pkg.dirPath),
+    from: pkg.metadata.from,
+    to: pkg.metadata.to,
+    migrationHash: pkg.metadata.migrationHash,
+    createdAt: pkg.metadata.createdAt,
+    operations: ops.map((op) => ({
+      id: op.id,
+      label: op.label,
+      operationClass: op.operationClass,
+    })),
+    preview,
+    summary: `${ops.length} operation(s)`,
+  };
+}
+
 async function executeMigrationShowCommand(
   target: string | undefined,
   options: MigrationShowOptions,
@@ -100,20 +237,16 @@ async function executeMigrationShowCommand(
   ui: TerminalUI,
 ): Promise<Result<MigrationShowResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const configPath = options.config
-    ? relative(process.cwd(), resolve(options.config))
-    : 'prisma-next.config.ts';
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } =
+    resolveMigrationPaths(options.config, config);
 
-  const migrationsDirRoot = resolve(
-    options.config ? resolve(options.config, '..') : process.cwd(),
-    config.migrations?.dir ?? 'migrations',
-  );
-  const appMigrationsDir = spaceMigrationDirectory(migrationsDirRoot, APP_SPACE_ID);
-  const appMigrationsRelative = relative(process.cwd(), appMigrationsDir);
+  const contractPathAbsolute = resolveContractPath(config);
+  const contractPath = relative(process.cwd(), contractPathAbsolute);
 
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
+      { label: 'contract', value: contractPath },
       { label: 'migrations', value: appMigrationsRelative },
     ];
     if (target) {
@@ -128,11 +261,73 @@ async function executeMigrationShowCommand(
     ui.stderr(header);
   }
 
-  let pkg: OnDiskMigrationPackage;
+  // Load the app contract so the aggregate loader can validate it.
+  let contractJsonContent: string;
+  try {
+    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      return notOk(
+        errorFileNotFound(contractPathAbsolute, {
+          why: `Contract file not found at ${contractPathAbsolute}`,
+          fix: `Run \`prisma-next contract emit\` to generate ${contractPath}`,
+        }),
+      );
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: 'Failed to read contract file',
+      }),
+    );
+  }
 
+  let appContract: Contract;
   try {
+    appContract = JSON.parse(contractJsonContent) as Contract;
+  } catch (error) {
+    return notOk(
+      errorContractValidationFailed(
+        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
+  }
+
+  // Build the aggregate against current disk state to enumerate all spaces.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+  const aggregateResult = await buildContractSpaceAggregate({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract,
+    extensionPacks: config.extensionPacks ?? [],
+    validateContract: (json: unknown) => familyInstance.validateContract(json),
+  });
+  if (!aggregateResult.ok) {
+    return notOk(aggregateResult.failure);
+  }
+  const aggregate = aggregateResult.value;
+
+  // `migration show` is an offline command; the control client is constructed
+  // purely to dispatch the family-specific `toOperationPreview` capability and
+  // is not connected to a database.
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    ...ifDefined('driver', config.driver),
+    extensionPacks: config.extensionPacks ?? [],
+  });
+
+  const spaces: MigrationShowSpaceResult[] = [];
+
+  // App space: honour the `target` argument (path or hash prefix) when provided.
+  try {
+    let appPkg: OnDiskMigrationPackage;
     if (target && looksLikePath(target)) {
-      pkg = await readMigrationPackage(resolve(target));
+      const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
+      if (!resolved.ok) return resolved;
+      appPkg = await readMigrationPackage(resolved.value);
     } else {
       const allPackages = await readMigrationsDir(appMigrationsDir);
       if (allPackages.length === 0) {
@@ -143,11 +338,10 @@ async function executeMigrationShowCommand(
           }),
         );
       }
-
       if (target) {
         const resolved = resolveByHashPrefix(allPackages, target);
         if (!resolved.ok) return resolved;
-        pkg = resolved.value;
+        appPkg = resolved.value;
       } else {
         const graph = reconstructGraph(allPackages);
         const latestMigration = findLatestMigration(graph);
@@ -170,51 +364,42 @@ async function executeMigrationShowCommand(
             }),
           );
         }
-        pkg = leafPkg;
+        appPkg = leafPkg;
       }
     }
+    spaces.push(pkgToSpaceResult(aggregate.app.spaceId, appPkg, client));
   } catch (error) {
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
     }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read migration: ${error instanceof Error ? error.message : String(error)}`,
+        why: `Failed to read app-space migration: ${error instanceof Error ? error.message : String(error)}`,
       }),
     );
   }
 
-  const ops = pkg.ops as readonly MigrationPlanOperation[];
-
-  // `migration show` is an offline command; the control client is constructed
-  // purely to dispatch the family-specific `toOperationPreview` capability and
-  // is not connected to a database.
-  const client = createControlClient({
-    family: config.family,
-    target: config.target,
-    adapter: config.adapter,
-    ...(config.driver ? { driver: config.driver } : {}),
-    extensionPacks: config.extensionPacks ?? [],
-  });
-  const preview: OperationPreview = client.toOperationPreview(ops) ?? { statements: [] };
+  // Extension spaces: always emit one entry per loaded extension so the
+  // response enumerates every space the aggregate knows about. Spaces
+  // with no on-disk migration package yet (e.g. an extension was declared
+  // but never `migrate`d) become `kind: 'missing'` placeholders instead
+  // of being silently skipped.
+  for (const ext of aggregate.extensions) {
+    const extSpaceDir = spaceMigrationDirectory(migrationsDir, ext.spaceId);
+    const extPkgResult = await resolveLatestFromDir(extSpaceDir);
+    if (!extPkgResult.ok) return extPkgResult;
+    if (extPkgResult.value !== null) {
+      spaces.push(pkgToSpaceResult(ext.spaceId, extPkgResult.value, client));
+    } else {
+      spaces.push({
+        kind: 'missing',
+        spaceId: ext.spaceId,
+        summary: 'No on-disk migration package for this space',
+      });
+    }
+  }
 
-  const result: MigrationShowResult = {
-    ok: true,
-    dirName: pkg.dirName,
-    dirPath: relative(process.cwd(), pkg.dirPath),
-    from: pkg.metadata.from,
-    to: pkg.metadata.to,
-    migrationHash: pkg.metadata.migrationHash,
-    createdAt: pkg.metadata.createdAt,
-    operations: ops.map((op) => ({
-      id: op.id,
-      label: op.label,
-      operationClass: op.operationClass,
-    })),
-    preview,
-    summary: `${ops.length} operation(s)`,
-  };
-  return ok(result);
+  return ok({ ok: true, spaces });
 }
 
 export function createMigrationShowCommand(): Command {
@@ -222,16 +407,16 @@ export function createMigrationShowCommand(): Command {
   setCommandDescriptions(
     command,
     'Display migration package contents',
-    'Shows the operations, statement preview, and metadata for a migration package.\n' +
-      'Accepts a directory path, a hash prefix (git-style), or defaults to the\n' +
-      'latest migration.',
+    'Shows the operations, statement preview, and metadata for every loaded contract\n' +
+      'space (app + extensions). Accepts a directory path or hash prefix to target a\n' +
+      'specific app-space migration; defaults to the latest per space.',
   );
   setCommandExamples(command, [
     'prisma-next migration show',
     'prisma-next migration show sha256:a1b2c3',
   ]);
   addGlobalOptions(command)
-    .argument('[target]', 'Migration directory path or migrationHash prefix (defaults to latest)')
+    .argument('[target]', 'App-space migration path or migrationHash prefix (defaults to latest)')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationShowOptions) => {
       const flags = parseGlobalFlags(options);

package/src/commands/migration-status.ts

@@ -513,7 +513,10 @@ export async function loadAggregateStatusSpaces(args: {
     let pendingCount = 0;
     let status: MigrationStatusSpaceEntry['status'];
     if (walked.kind === 'ok') {
-      pendingCount = walked.result.plan.operations.length;
+      // 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 {
@@ -723,15 +726,20 @@ async function executeMigrationStatusCommand(
       // 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 {
+      //
+      // 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();
-      } 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).
+      } 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 {

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

@@ -127,16 +127,18 @@ export async function executeAggregateApply<TFamilyId extends string, TTargetId
   // 2. Read live DB state (markers + schema).
   const markerRows = await familyInstance.readAllMarkers({ driver });
 
-  // 2a. Orphan-marker pre-flight: refuse to apply when a marker row
-  // exists for a space that is not declared in the aggregate.
-  // Mirrors the M2 marker-check that `db init` / `db update` ran via
-  // `runContractSpaceVerifierMarkerCheck`. Runs before planning so a
-  // user with an orphaned marker (e.g. a retired extension whose
-  // migrations directory has been removed) is told to clean it up
-  // rather than silently advancing the app's marker.
-  const orphanMarkerError = detectOrphanMarkers(aggregate, markerRows);
-  if (orphanMarkerError !== null) {
-    throw orphanMarkerError;
+  // 2a. Orphan-marker pre-flight: refuse to *apply* when a marker row
+  // exists for a space that is not declared in the aggregate. Plan mode
+  // (`db init/update --dry-run`) must still be able to introspect the
+  // aggregate plan in this state — a retired extension whose marker
+  // happens to linger should not block the user from inspecting what a
+  // run would do. Apply mode tells the user to clean up the orphan
+  // before silently advancing the app's marker.
+  if (mode === 'apply') {
+    const orphanMarkerError = detectOrphanMarkers(aggregate, markerRows);
+    if (orphanMarkerError !== null) {
+      throw orphanMarkerError;
+    }
   }
 
   onProgress?.({