prisma
diff --git a/‎packages/1-framework/3-tooling/cli/src/commands/migration-check.ts‎
Lines changed: 147 additions & 44 deletions b/‎packages/1-framework/3-tooling/cli/src/commands/migration-check.ts‎
Lines changed: 147 additions & 44 deletions
diff --git a/‎packages/1-framework/3-tooling/cli/src/utils/cli-errors.ts‎
Lines changed: 23 additions & 0 deletions b/‎packages/1-framework/3-tooling/cli/src/utils/cli-errors.ts‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎packages/1-framework/3-tooling/cli/src/utils/migration-path-target.ts‎
Lines changed: 21 additions & 0 deletions b/‎packages/1-framework/3-tooling/cli/src/utils/migration-path-target.ts‎
Lines changed: 21 additions & 0 deletions
@@ -8,25 +8,27 @@ import type {
 import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
 import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
 import { verifyMigrationHash } from '@prisma-next/migration-tools/hash';
-import { readMigrationsDir } from '@prisma-next/migration-tools/io';
-import { reconstructGraph } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
-import { parseMigrationRef } from '@prisma-next/migration-tools/ref-resolution';
+import {
+  parseMigrationRef,
+  type RefResolutionError,
+} from '@prisma-next/migration-tools/ref-resolution';
 import type { Refs } from '@prisma-next/migration-tools/refs';
-import { readRefs } from '@prisma-next/migration-tools/refs';
 import {
   isValidSpaceId,
   listContractSpaceDirectories,
   RESERVED_SPACE_SUBDIR_NAMES,
   spaceMigrationDirectory,
   spaceRefsDirectory,
 } 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 { join, relative } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   type CliStructuredError,
+  errorAmbiguousMigrationRef,
   errorInvalidSpaceId,
   errorSpaceNotFound,
   mapRefResolutionError,
@@ -53,6 +55,7 @@ import {
   findPackageByDirPath,
   looksLikePath,
   resolveAppTargetPath,
+  resolveTargetPathAcrossSpaces,
 } from '../utils/migration-path-target';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { INTEGRITY_FAILED, OK, PRECONDITION } from './migration-check/exit-codes';
@@ -308,6 +311,7 @@ interface MigrationCheckOutcome {
   readonly result?: MigrationCheckResult;
   readonly error?: CliStructuredError;
   readonly exitCode: number;
+  readonly resolvedSpaceId?: string;
 }
 
 async function executeMigrationCheckCommand(
@@ -317,7 +321,7 @@ async function executeMigrationCheckCommand(
   ui: TerminalUI,
 ): Promise<MigrationCheckOutcome> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } =
     resolveMigrationPaths(options.config, config);
 
   if (!flags.json && !flags.quiet) {
@@ -337,20 +341,22 @@ async function executeMigrationCheckCommand(
     ui.stderr(header);
   }
 
+  const loadedAggregate = await buildReadAggregate(config, { migrationsDir });
+  if (!loadedAggregate.ok) {
+    return { error: loadedAggregate.failure, exitCode: PRECONDITION };
+  }
+
+  const spaces = await enumerateCheckSpaces(loadedAggregate.value.aggregate, migrationsDir);
+
   if (target) {
     return await checkSingleTarget(target, {
+      spaces,
+      ...(options.space !== undefined ? { spaceFilter: options.space } : {}),
       appMigrationsDir,
       appMigrationsRelative,
-      refsDir,
     });
   }
 
-  const loadedAggregate = await buildReadAggregate(config, { migrationsDir });
-  if (!loadedAggregate.ok) {
-    return { error: loadedAggregate.failure, exitCode: PRECONDITION };
-  }
-
-  const spaces = await enumerateCheckSpaces(loadedAggregate.value.aggregate, migrationsDir);
   const checkResult = runMigrationCheck({
     spaces,
     ...(options.space !== undefined ? { spaceFilter: options.space } : {}),
@@ -382,53 +388,140 @@ async function executeMigrationCheckCommand(
   };
 }
 
-interface SingleTargetPaths {
+interface SingleTargetInputs {
+  readonly spaces: readonly CheckSpace[];
+  readonly spaceFilter?: string;
   readonly appMigrationsDir: string;
   readonly appMigrationsRelative: string;
-  readonly refsDir: string;
 }
 
 /**
- * Single-target (`check <ref/path>`) mode — app-space only by design (the
- * migration's space is pinned by the reference; multi-space single-target
- * resolution is a deliberate follow-up, see the slice spec § Out of scope).
- * Resolves the one referenced package and verifies its hash / manifest /
- * snapshot, plus the app-space orphan-manifest check the prior behaviour ran.
+ * Ranks ref-resolution failure kinds by how informative they are, so a
+ * single-target check surfaces the most useful failure across spaces instead of
+ * whichever space failed first. `not-found` (the input matched nothing here)
+ * says the least; a malformed input, a wrong grammar, or an in-space ambiguity
+ * all say more.
+ */
+function refFailureSpecificity(error: RefResolutionError): number {
+  switch (error.kind) {
+    case 'wrong-grammar':
+      return 3;
+    case 'ambiguous':
+      return 2;
+    case 'invalid-format':
+      return 1;
+    case 'not-found':
+      return 0;
+  }
+}
+
+/**
+ * Single-target (`check <ref/path>`) mode — resolves a migration reference
+ * across all contract spaces (or the one space narrowed by `--space <id>`).
+ *
+ * Resolution:
+ *   - filesystem path → find the owning space by checking which space's
+ *     `migrationsDir` contains the resolved path; falls back to app-relative
+ *     validation when the path is outside every space dir.
+ *   - ref → `parseMigrationRef` against each in-scope space; collect every
+ *     (space, package) hit; 0 hits = not-found, 1 = check it, >1 = ambiguity
+ *     error (qualify with `--space`).
+ *
+ * `--space <id>` is validated the same way the holistic path does it:
+ * invalid id → `errorInvalidSpaceId`; no on-disk space → `errorSpaceNotFound`.
  */
 async function checkSingleTarget(
   target: string,
-  paths: SingleTargetPaths,
+  inputs: SingleTargetInputs,
 ): Promise<MigrationCheckOutcome> {
-  const { appMigrationsDir, appMigrationsRelative, refsDir } = paths;
-  const loaded = await readMigrationsDir(appMigrationsDir);
-  const bundles: readonly OnDiskMigrationPackage[] = loaded.packages;
-  const appSpace: CheckSpace = {
-    spaceId: 'app',
-    packages: bundles,
-    refs: await readRefs(refsDir),
-    graph: reconstructGraph(bundles),
-    migrationsDir: appMigrationsDir,
-    refsDir,
-  };
+  const { spaces, spaceFilter, appMigrationsDir, appMigrationsRelative } = inputs;
 
-  const failures: CheckFailure[] = [...checkManifestFilesPresent(appSpace)];
+  if (spaceFilter !== undefined && !isValidSpaceId(spaceFilter)) {
+    return { error: errorInvalidSpaceId(spaceFilter), exitCode: PRECONDITION };
+  }
+  if (spaceFilter !== undefined && !spaces.some((s) => s.spaceId === spaceFilter)) {
+    return {
+      error: errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()),
+      exitCode: PRECONDITION,
+    };
+  }
 
+  const scopedSpaces =
+    spaceFilter !== undefined ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
+
+  let matchedSpace: CheckSpace | undefined;
   let matchedPkg: OnDiskMigrationPackage | undefined;
+
   if (looksLikePath(target)) {
-    const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
-    if (!resolved.ok) {
-      return { error: resolved.failure, exitCode: PRECONDITION };
+    const resolvedPath = resolveTargetPathAcrossSpaces(target, scopedSpaces);
+    if (resolvedPath !== null) {
+      for (const space of scopedSpaces) {
+        const found = findPackageByDirPath(space.packages, resolvedPath);
+        if (found) {
+          matchedSpace = space;
+          matchedPkg = found;
+          break;
+        }
+      }
+    } else {
+      // Path outside every space dir — fall back to app-relative validation
+      const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
+      if (!resolved.ok) {
+        return { error: resolved.failure, exitCode: PRECONDITION };
+      }
+      const appSpace = scopedSpaces.find((s) => s.spaceId === 'app');
+      if (appSpace) {
+        matchedSpace = appSpace;
+        matchedPkg = findPackageByDirPath(appSpace.packages, resolved.value);
+      }
     }
-    matchedPkg = findPackageByDirPath(bundles, resolved.value);
   } else {
-    const migResult = parseMigrationRef(target, { graph: appSpace.graph, refs: appSpace.refs });
-    if (!migResult.ok) {
-      return { error: mapRefResolutionError(migResult.failure), exitCode: PRECONDITION };
+    // Ref resolution: try each in-scope space, collect all hits.
+    const hits: Array<{ space: CheckSpace; pkg: OnDiskMigrationPackage }> = [];
+    let bestParseFailure: RefResolutionError | undefined;
+    for (const space of scopedSpaces) {
+      const migResult = parseMigrationRef(target, { graph: space.graph, refs: space.refs });
+      if (!migResult.ok) {
+        // Keep scanning — a later space may hold a hit that must not be discarded.
+        // When no space yields a hit, keep the most informative failure rather than
+        // whichever space failed first (the kind is space-dependent).
+        if (
+          bestParseFailure === undefined ||
+          refFailureSpecificity(migResult.failure) > refFailureSpecificity(bestParseFailure)
+        ) {
+          bestParseFailure = migResult.failure;
+        }
+        continue;
+      }
+      const pkg = space.packages.find(
+        (p) => p.metadata.migrationHash === migResult.value.migrationHash,
+      );
+      if (pkg) {
+        hits.push({ space, pkg });
+      }
+    }
+
+    if (hits.length > 1) {
+      const spaceIds = hits.map((h) => h.space.spaceId);
+      return {
+        error: errorAmbiguousMigrationRef(target, spaceIds),
+        exitCode: PRECONDITION,
+      };
+    }
+
+    if (hits.length === 1) {
+      matchedSpace = hits[0]!.space;
+      matchedPkg = hits[0]!.pkg;
+    } else if (bestParseFailure !== undefined) {
+      // The ref didn't resolve in any in-scope space — surface the most informative
+      // parse failure through the shared ref-resolution envelope (PN-RUN-3000) the
+      // earlier work established, rather than a bespoke string. (Ref-resolved-but-
+      // no-package falls through to the "not found on disk" result below.)
+      return { error: mapRefResolutionError(bestParseFailure), exitCode: PRECONDITION };
     }
-    matchedPkg = bundles.find((p) => p.metadata.migrationHash === migResult.value.migrationHash);
   }
 
-  if (!matchedPkg) {
+  if (!matchedPkg || !matchedSpace) {
     return {
       result: {
         ok: false,
@@ -439,6 +532,8 @@ async function checkSingleTarget(
     };
   }
 
+  const failures: CheckFailure[] = [...checkManifestFilesPresent(matchedSpace)];
+
   for (const f of ['migration.json', 'ops.json']) {
     const fail = checkFileExists(matchedPkg.dirPath, matchedPkg.dirName, f);
     if (fail) failures.push(fail);
@@ -457,15 +552,19 @@ async function checkSingleTarget(
   const snapshotFailure = checkSnapshotConsistency(matchedPkg);
   if (snapshotFailure) failures.push(snapshotFailure);
 
+  const resolvedSpaceId = matchedSpace.spaceId !== 'app' ? matchedSpace.spaceId : undefined;
+
   if (failures.length === 0) {
     return {
       result: { ok: true, failures: [], summary: 'All checks passed' },
       exitCode: OK,
+      ...ifDefined('resolvedSpaceId', resolvedSpaceId),
     };
   }
   return {
     result: { ok: false, failures, summary: `${failures.length} integrity failure(s)` },
     exitCode: INTEGRITY_FAILED,
+    ...ifDefined('resolvedSpaceId', resolvedSpaceId),
   };
 }
 
@@ -477,8 +576,9 @@ export function createMigrationCheckCommand(): Command {
     'Validates that on-disk migration packages are internally consistent\n' +
       '(hashes match, manifests are complete) and that the graph is well-formed\n' +
       '(edges connect, refs point at valid nodes). The whole-graph check spans\n' +
-      'every contract space by default; pass --space <id> to narrow to one, or\n' +
-      'a migration reference to check a single app-space package.\n' +
+      'every contract space by default; pass --space <id> to narrow to one. A\n' +
+      'migration reference checks a single package, resolved across all contract\n' +
+      'spaces (narrow with --space; an ambiguous reference is a precondition failure).\n' +
       'Offline — does not consult the database.\n' +
       'Exit codes: 0 = all checks passed, 2 = precondition failed\n' +
       '(unresolved target or unknown --space), 4 = integrity failure(s) found.',
@@ -487,6 +587,7 @@ export function createMigrationCheckCommand(): Command {
     'prisma-next migration check',
     'prisma-next migration check --space app',
     'prisma-next migration check 20260101-add-users',
+    'prisma-next migration check 20260101-add-users --space app',
     'prisma-next migration check --json',
   ]);
   setCommandSeeAlso(command, [
@@ -535,7 +636,9 @@ export function createMigrationCheckCommand(): Command {
         ui.output(JSON.stringify(result, null, 2));
       } else if (!flags.quiet) {
         if (result.ok) {
-          ui.log(`✔ ${result.summary}`);
+          const spaceSuffix =
+            outcome.resolvedSpaceId !== undefined ? `  (space: ${outcome.resolvedSpaceId})` : '';
+          ui.log(`✔ ${result.summary}${spaceSuffix}`);
         } else {
           for (const f of result.failures) {
             ui.log(`✗ [${f.pnCode}] ${f.where}: ${f.why}`);
 
@@ -374,6 +374,29 @@ export function requireLiveDatabase(args: {
  * Maps a `RefResolutionError` from the contract/migration reference
  * resolver into a CLI structured error envelope.
  */
+/**
+ * A migration ref (dirName or hash-prefix) resolves in more than one contract
+ * space. The user must qualify with `--space <id>` to disambiguate.
+ */
+export function errorAmbiguousMigrationRef(
+  ref: string,
+  spaceIds: readonly string[],
+): CliStructuredError {
+  const spaceList = spaceIds.join(', ');
+  return errorRuntime(
+    `Ambiguous migration reference: "${ref}" resolves in multiple spaces — qualify with --space <id>`,
+    {
+      why: `"${ref}" matches migrations in spaces: ${spaceList}.`,
+      fix: `Qualify with --space <id> to select one space. Available matching spaces: ${spaceList}.`,
+      meta: {
+        code: 'MIGRATION.AMBIGUOUS_MIGRATION_REF',
+        ref,
+        spaceIds: [...spaceIds],
+      },
+    },
+  );
+}
+
 export function mapRefResolutionError(error: RefResolutionError): CliStructuredError {
   switch (error.kind) {
     case 'not-found':
 
@@ -30,6 +30,27 @@ export function resolveAppTargetPath(
   return ok(targetPath);
 }
 
+/**
+ * Resolve a filesystem-path target to the migration dir that contains it,
+ * searching each in-scope space's `migrationsDir`. A path is explicit, so
+ * it can belong to at most one space — returns the first match, or `null`
+ * when the path falls outside every space dir.
+ */
+export function resolveTargetPathAcrossSpaces(
+  target: string,
+  spaces: ReadonlyArray<{ readonly migrationsDir: string }>,
+): string | null {
+  const targetPath = resolve(target);
+  for (const space of spaces) {
+    const rel = relative(space.migrationsDir, targetPath);
+    const isOutside = rel === '' || rel === '.' || rel.startsWith('..') || isAbsolute(rel);
+    if (!isOutside) {
+      return targetPath;
+    }
+  }
+  return null;
+}
+
 export function findPackageByDirPath(
   packages: readonly OnDiskMigrationPackage[],
   resolvedDirPath: string,