@prisma-next/cli 0.15.0 → 0.16.0-dev.10

package/src/commands/init/hygiene-gitattributes.ts

@@ -1,47 +1,60 @@
 import type { TargetId } from './templates/code-templates';
 
 /**
- * The schema-relative `.gitattributes` entries written for a freshly
- * initialised project (FR3.4). Mirrors the relevant subset of the
- * repo-root [`.gitattributes`](../../../../../../../../.gitattributes):
+ * The `.gitattributes` entries written for a freshly initialised project
+ * (FR3.4). Mirrors the relevant subset of the repo-root
+ * [`.gitattributes`](../../../../../../../../.gitattributes):
  *
  * - **Today**: `contract.json`, `contract.d.ts` are emitted on every
  *   `prisma-next contract emit`. Marking them `linguist-generated`
  *   keeps GitHub's diff stats honest and collapses the file in code
  *   review by default.
- * - **Forward-looking**: `end-contract.*`, `start-contract.*`, `ops.json`,
- *   `migration.json` are not yet emitted by `init` flows but will be
- *   produced by adjacent commands (lower / migration tooling). Adding
- *   them now matches Decision 5 (forward-looking subset) so the file
- *   does not need to be amended every time a new artefact lands.
+ * - **Forward-looking**: `ops.json`, `migration.json` are not yet emitted
+ *   by `init` flows but will be produced by adjacent commands (lower /
+ *   migration tooling). Adding them now matches Decision 5
+ *   (forward-looking subset) so the file does not need to be amended
+ *   every time a new artifact lands.
  *
- * Patterns are written relative to the schema directory so a user
- * who runs `init --schema-path db/contract.prisma` gets
- * `db/contract.json linguist-generated` — not the workspace-glob form
- * `<glob>/contract.json` (which would over-match any unrelated
+ * `ARTIFACT_FILENAMES` entries are written relative to the schema
+ * directory so a user who runs `init --schema-path db/contract.prisma`
+ * gets `db/contract.json linguist-generated` — not the workspace-glob
+ * form `<glob>/contract.json` (which would over-match any unrelated
  * `contract.json` the user has elsewhere) and not the absolute
- * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json` (which would silently break for a non-default
- * schema path).
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json` (which would silently
+ * break for a non-default schema path).
+ *
+ * The migration contract snapshot store (`migrations/snapshots/<hex>/`)
+ * is anchored to the migrations root instead, not the schema directory:
+ * migration package depth under `migrations/` varies (`app/<pkg>`,
+ * `<space>/<pkg>`, or a bare `<pkg>` in extension source repos), so no
+ * single schema-dir-relative pattern can reach every snapshot. See
+ * `STORE_GITATTRIBUTES_LINES` below.
  */
-const ARTEFACT_FILENAMES: readonly string[] = [
+const ARTIFACT_FILENAMES: readonly string[] = [
   'contract.json',
   'contract.d.ts',
-  'end-contract.json',
-  'end-contract.d.ts',
-  'start-contract.json',
-  'start-contract.d.ts',
   'ops.json',
   'migration.json',
 ];
 
 const ATTRIBUTE = 'linguist-generated';
 
+/**
+ * Full `.gitattributes` lines for the migration contract snapshot store,
+ * already anchored to the migrations root — unlike `ARTIFACT_FILENAMES`,
+ * these are not combined with the schema-relative prefix.
+ */
+const STORE_GITATTRIBUTES_LINES: readonly string[] = [
+  `migrations/snapshots/**/contract.json ${ATTRIBUTE}`,
+  `migrations/snapshots/**/contract.d.ts ${ATTRIBUTE}`,
+];
+
 /**
  * Computes the `.gitattributes` lines this scaffold expects to own. Each
  * line has the shape `<path> linguist-generated`. The `target` parameter
  * is currently unused but accepted for symmetry with the other hygiene
  * helpers and to leave room for target-specific entries (e.g. a future
- * Mongo-only artefact) without a signature break.
+ * family-specific artifact) without a signature break.
  */
 export function requiredGitattributesLines(
   schemaDir: string,
@@ -49,7 +62,10 @@ export function requiredGitattributesLines(
 ): readonly string[] {
   const dir = schemaDir === '.' ? '' : schemaDir.replace(/\/+$/, '');
   const prefix = dir === '' ? '' : `${dir}/`;
-  return ARTEFACT_FILENAMES.map((file) => `${prefix}${file} ${ATTRIBUTE}`);
+  return [
+    ...ARTIFACT_FILENAMES.map((file) => `${prefix}${file} ${ATTRIBUTE}`),
+    ...STORE_GITATTRIBUTES_LINES,
+  ];
 }
 
 /**

package/src/commands/init/init.ts

@@ -48,7 +48,7 @@ import {
   renderInitOutro,
 } from './output';
 import { type ProbeOutcome, type ProbeOverrides, probeServerVersion } from './probe-db';
-import { findStaleArtefacts, removeDependency } from './reinit-cleanup';
+import { findStaleArtifacts, removeDependency } from './reinit-cleanup';
 import {
   DEFAULT_SKILL_SOURCES,
   formatSkillInstallCommand,
@@ -175,14 +175,14 @@ export async function runInit(
     { path: '.env.example', content: envExampleContent(inputs.target) },
   ];
 
-  // FR9.1 — on re-init, queue the previously-emitted contract artefacts
+  // FR9.1 — on re-init, queue the previously-emitted contract artifacts
   // for deletion so a target switch (or schema-shape change) does not
   // leave a stale `contract.json` / `contract.d.ts` next to the new
   // schema source. Detection is filesystem-only (no parsing of the
   // previous config) so the cleanup is safe to run before the write
   // phase: each path is checked for existence in the precondition,
   // and missing-on-disk-at-write-time is tolerated.
-  const filesToDelete: string[] = inputs.reinit ? [...findStaleArtefacts(baseDir, schemaDir)] : [];
+  const filesToDelete: string[] = inputs.reinit ? [...findStaleArtifacts(baseDir, schemaDir)] : [];
 
   // `init` delegates the skill to `npx skills add prisma/prisma-next#v<version>`,
   // so a hand-rolled `.agents/skills/prisma-next/SKILL.md` in the project
@@ -245,7 +245,7 @@ export async function runInit(
   }
 
   // FR3.4: idempotent .gitattributes — linguist-generated entries for
-  // the emitted artefacts so GitHub diff stats / code review collapse
+  // the emitted artifacts so GitHub diff stats / code review collapse
   // them by default.
   const gitattributesPath = join(baseDir, '.gitattributes');
   const existingGitattributes = existsSync(gitattributesPath)
@@ -373,7 +373,7 @@ export async function runInit(
     }
   }
 
-  // FR9.1 — delete stale artefacts after the new templates are written.
+  // FR9.1 — delete stale artifacts after the new templates are written.
   // Order is intentional: the names do not collide with `filesToWrite`
   // (we never write `contract.json` from this command — that's `contract
   // emit`'s job), so deletion *after* the writes guarantees we never
@@ -534,18 +534,21 @@ export async function runInit(
   if (validated instanceof Error || (validated as { problems?: unknown }).problems !== undefined) {
     // Route through `emitError` rather than throwing: the bare throw
     // bypassed `--json` envelope formatting and `exitCodeForError`, so a
-    // 5009 regression would surface as an uncaught exception in
-    // commander instead of the documented `INTERNAL_ERROR` envelope on
-    // the right channel.
+    // CLI.INIT_INVALID_OUTPUT_DOCUMENT regression would surface as an
+    // uncaught exception in commander instead of the documented
+    // `INTERNAL_ERROR` envelope on the right channel.
     return emitError(
       ui,
       flags,
-      new CliStructuredError('5009', 'Init produced an invalid output document', {
-        domain: 'CLI',
-        why: `The success document failed schema validation: ${String(validated)}`,
-        fix: 'This is a bug in prisma-next. Please report it with the full `-v` output.',
-        docsUrl: 'https://prisma-next.dev/docs/cli/init',
-      }),
+      new CliStructuredError(
+        'CLI.INIT_INVALID_OUTPUT_DOCUMENT',
+        'Init produced an invalid output document',
+        {
+          why: `The success document failed schema validation: ${String(validated)}`,
+          fix: 'This is a bug in prisma-next. Please report it with the full `-v` output.',
+          docsUrl: 'https://prisma-next.dev/docs/cli/init',
+        },
+      ),
     );
   }
 
@@ -582,10 +585,10 @@ function emitError(ui: TerminalUI, flags: GlobalFlags, error: CliStructuredError
  * Maps a structured init error to its documented exit code. Centralised so
  * the error → exit-code contract lives next to the codes themselves.
  *
- * `5009` (and the unknown-code default branch) routes to
- * `INIT_EXIT_INTERNAL_ERROR` because those represent prisma-next bugs the
- * user did not cause — surfacing them as `PRECONDITION` would mislead
- * automation into thinking the caller mis-invoked the CLI.
+ * `CLI.INIT_INVALID_OUTPUT_DOCUMENT` (and the unknown-code default branch)
+ * routes to `INIT_EXIT_INTERNAL_ERROR` because those represent prisma-next
+ * bugs the user did not cause — surfacing them as `PRECONDITION` would
+ * mislead automation into thinking the caller mis-invoked the CLI.
  *
  * See [exit-codes.ts](./exit-codes.ts) for the canonical list and
  * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes)
@@ -596,24 +599,24 @@ function emitError(ui: TerminalUI, flags: GlobalFlags, error: CliStructuredError
  */
 export function exitCodeForError(error: { readonly code: string }): number {
   switch (error.code) {
-    case '5002': // re-init needs --force — precondition
-    case '5003': // missing flags — precondition
-    case '5004': // invalid flag value — precondition
-    case '5005': // --strict-probe without --probe-db — precondition
-    case '5010': // invalid manifest (malformed package.json) — precondition
-    case '5011': // invalid tsconfig (unparseable JSONC) — precondition
-    case '5012': // probe failed under --strict-probe — precondition
-    case '5014': // --authoring / --schema-path extension mismatch — precondition
+    case 'CLI.INIT_REINIT_NEEDS_FORCE': // re-init needs --force — precondition
+    case 'CLI.INIT_MISSING_FLAGS': // missing flags — precondition
+    case 'CLI.INIT_INVALID_FLAG_VALUE': // invalid flag value — precondition
+    case 'CLI.INIT_STRICT_PROBE_WITHOUT_PROBE': // --strict-probe without --probe-db — precondition
+    case 'CLI.INIT_INVALID_MANIFEST': // invalid manifest (malformed package.json) — precondition
+    case 'CLI.INIT_INVALID_TSCONFIG': // invalid tsconfig (unparseable JSONC) — precondition
+    case 'CLI.INIT_PROBE_FAILED': // probe failed under --strict-probe — precondition
+    case 'CLI.INIT_AUTHORING_SCHEMA_PATH_MISMATCH': // --authoring / --schema-path extension mismatch — precondition
       return INIT_EXIT_PRECONDITION;
-    case '5006': // user aborted interactive prompt
+    case 'CLI.INIT_USER_ABORTED': // user aborted interactive prompt
       return INIT_EXIT_USER_ABORTED;
-    case '5007': // install failed
+    case 'CLI.INIT_INSTALL_FAILED': // install failed
       return INIT_EXIT_INSTALL_FAILED;
-    case '5008': // emit failed
+    case 'CLI.INIT_EMIT_FAILED': // emit failed
       return INIT_EXIT_EMIT_FAILED;
-    case '5009': // invalid output document — internal bug in prisma-next
+    case 'CLI.INIT_INVALID_OUTPUT_DOCUMENT': // invalid output document — internal bug in prisma-next
       return INIT_EXIT_INTERNAL_ERROR;
-    case '5013': // skill install failed
+    case 'CLI.INIT_SKILL_INSTALL_FAILED': // skill install failed
       return INIT_EXIT_SKILL_INSTALL_FAILED;
     default:
       // Any unexpected code is treated as an internal bug rather than
@@ -844,7 +847,7 @@ function formatCatalogWarning(
 /**
  * Recognised pnpm error signatures that justify a fallback to npm.
  *
- * These patterns indicate the published artefact itself is at fault
+ * These patterns indicate the published artifact itself is at fault
  * (a leaked `workspace:*` or `catalog:` specifier), not the user's
  * environment — pnpm is faithfully reporting "I cannot resolve this
  * registry version", and npm is willing to install it because npm

package/src/commands/init/output.ts

@@ -24,10 +24,9 @@ export const InitOutputSchema = type({
   filesWritten: 'string[]',
   /**
    * FR9.1 — files removed from disk during this run. Populated only on
-   * re-init when previously-emitted contract artefacts (`contract.json`,
-   * `contract.d.ts`, `start-/end-contract.*`, `ops.json`,
-   * `migration.json`) were left behind by an earlier run. Empty on a
-   * green-field init.
+   * re-init when previously-emitted contract artifacts (`contract.json`,
+   * `contract.d.ts`, `ops.json`, `migration.json`) were left behind by an
+   * earlier run. Empty on a green-field init.
    */
   filesDeleted: 'string[]',
   packagesInstalled: {
@@ -80,7 +79,7 @@ export function renderInitOutro(ui: TerminalUI, output: InitOutput, flags: Globa
 
   if (output.filesDeleted.length > 0) {
     lines.push('');
-    lines.push('Files deleted (stale contract artefacts):');
+    lines.push('Files deleted (stale contract artifacts):');
     for (const file of output.filesDeleted) {
       lines.push(`  • ${file}`);
     }

package/src/commands/init/reinit-cleanup.ts

@@ -4,41 +4,40 @@ import { join } from 'pathe';
 /**
  * Filenames the contract pipeline emits next to the user's schema source
  * (`<schemaDir>/contract.json`, `<schemaDir>/contract.d.ts`, …). Mirrors
- * `ARTEFACT_FILENAMES` in `hygiene-gitattributes.ts`; kept as a separate
- * constant here because the cleanup contract is target-agnostic and we
- * deliberately do not want a stale `start-contract.json` from a previous
- * target lingering after a re-init.
+ * the schema-dir-relative `ARTIFACT_FILENAMES` in `hygiene-gitattributes.ts`
+ * (not that file's migrations-root-anchored store lines, which are outside
+ * this command's scope — reinit only ever touches `schemaDir`); kept as a
+ * separate constant here because the cleanup contract is target-agnostic
+ * and we deliberately do not want a stale artifact from a previous target
+ * lingering after a re-init.
  *
- * If a future emit pipeline produces an additional artefact, add it here
- * **and** to the gitattributes list — the two stay in lockstep so the
- * file `init` advertises as `linguist-generated` is exactly the file
- * `init` is willing to delete on re-init.
+ * If a future emit pipeline produces an additional schema-dir artifact,
+ * add it here **and** to `ARTIFACT_FILENAMES` in `hygiene-gitattributes.ts`
+ * — the two stay in lockstep so the file `init` advertises as
+ * `linguist-generated` is exactly the file `init` is willing to delete on
+ * re-init.
  */
-const ARTEFACT_FILENAMES: readonly string[] = [
+const ARTIFACT_FILENAMES: readonly string[] = [
   'contract.json',
   'contract.d.ts',
-  'end-contract.json',
-  'end-contract.d.ts',
-  'start-contract.json',
-  'start-contract.d.ts',
   'ops.json',
   'migration.json',
 ];
 
 /**
- * Returns the schema-relative paths of stale contract artefacts the
+ * Returns the schema-relative paths of stale contract artifacts the
  * previous `init` run (or a `contract emit`) left behind in `schemaDir`.
  * Paths are returned relative to `baseDir` so the caller can plumb them
  * into `filesWritten`-style logging without re-deriving the path.
  *
  * Pure function: no filesystem mutation. Used by `runInit`'s precondition
  * phase (FR6.2 / NFR3 atomicity) so a downstream parse failure leaves
- * the artefacts on disk and the project byte-identical to its pre-init
+ * the artifacts on disk and the project byte-identical to its pre-init
  * state.
  */
-export function findStaleArtefacts(baseDir: string, schemaDir: string): readonly string[] {
+export function findStaleArtifacts(baseDir: string, schemaDir: string): readonly string[] {
   const result: string[] = [];
-  for (const filename of ARTEFACT_FILENAMES) {
+  for (const filename of ARTIFACT_FILENAMES) {
     const rel = join(schemaDir, filename);
     if (existsSync(join(baseDir, rel))) {
       result.push(rel);

package/src/commands/migrate.ts

@@ -831,6 +831,7 @@ async function executeMigrateCommand(
             : await readContractIR(snapshotContractJson, contractPathAbsolute);
         advancedRef = await executeRefAdvancement(
           refsDir,
+          migrationsDir,
           options.advanceRef,
           value.markerHash,
           contractIR,

package/src/commands/migration-check.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { loadConfig } from '@prisma-next/config-loader';
 import { createControlStack } from '@prisma-next/framework-components/control';
@@ -7,6 +7,11 @@ import type {
   IntegrityViolation,
 } from '@prisma-next/migration-tools/aggregate';
 import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
+import {
+  contractSnapshotDir,
+  readContractSnapshotJson,
+} from '@prisma-next/migration-tools/contract-snapshot-store';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
 import { verifyMigrationHash } from '@prisma-next/migration-tools/hash';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
@@ -18,7 +23,6 @@ import type { Refs } from '@prisma-next/migration-tools/refs';
 import {
   isValidSpaceId,
   listContractSpaceDirectories,
-  RESERVED_SPACE_SUBDIR_NAMES,
   spaceMigrationDirectory,
   spaceRefsDirectory,
 } from '@prisma-next/migration-tools/spaces';
@@ -83,7 +87,7 @@ function checkFileExists(
   if (!existsSync(join(dirPath, fileName))) {
     return {
       space: spaceId,
-      code: 'PN-MIG-CHECK-002',
+      code: 'MIGRATION.CHECK_FILE_MISSING',
       where: migrationFileRelative(dirPath, fileName),
       why: `${fileName} is missing from ${dirName}`,
       fix: 'Re-emit the migration package or restore from version control.',
@@ -92,32 +96,57 @@ function checkFileExists(
   return null;
 }
 
-function checkSnapshotConsistency(
+/**
+ * Snapshot-store consistency check for one migration package (D6.5):
+ * absent store entry is not an issue (runner independence, ADR 199 — a
+ * package dir with only `migration.json` + `ops.json` is legitimate); a
+ * present entry whose inner `storage.storageHash` disagrees with
+ * `pkg.metadata.to` is `MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH`; an unparseable store
+ * entry (or a malformed `to`) is `MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE`.
+ */
+async function checkSnapshotConsistency(
   spaceId: string,
   pkg: OnDiskMigrationPackage,
-): CheckFailure | null {
-  const endContractPath = join(pkg.dirPath, 'end-contract.json');
-  if (!existsSync(endContractPath)) return null;
+  migrationsDir: string,
+): Promise<CheckFailure | null> {
+  let snapshotDir: string;
   try {
-    const raw = JSON.parse(readFileSync(endContractPath, 'utf-8')) as Record<string, unknown>;
-    const storage = raw['storage'] as Record<string, unknown> | undefined;
-    const snapshotHash = storage?.['storageHash'];
-    if (typeof snapshotHash === 'string' && snapshotHash !== pkg.metadata.to) {
-      return {
-        space: spaceId,
-        code: 'PN-MIG-CHECK-005',
-        where: migrationPathRelative(pkg.dirPath),
-        why: `Migration "${pkg.dirName}" declares to=${pkg.metadata.to} but end-contract.json has storageHash=${snapshotHash}`,
-        fix: 'Re-emit the migration package so migration.json and end-contract.json agree.',
-      };
-    }
+    snapshotDir = contractSnapshotDir(migrationsDir, pkg.metadata.to);
   } catch {
     return {
       space: spaceId,
-      code: 'PN-MIG-CHECK-006',
+      code: 'MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE',
       where: migrationPathRelative(pkg.dirPath),
-      why: `Migration "${pkg.dirName}" has an unparseable end-contract.json.`,
-      fix: 'Re-emit the migration package to repair the snapshot file.',
+      why: `Migration "${pkg.dirName}" declares to="${pkg.metadata.to}", which is not a well-formed contract snapshot hash.`,
+      fix: 'Re-emit the migration package so migration.json declares a valid `sha256:<64hex>` to-hash.',
+    };
+  }
+
+  let raw: unknown;
+  try {
+    raw = await readContractSnapshotJson(migrationsDir, pkg.metadata.to);
+  } catch (error) {
+    if (MigrationToolsError.is(error) && error.code === 'MIGRATION.CONTRACT_SNAPSHOT_MISSING') {
+      return null;
+    }
+    return {
+      space: spaceId,
+      code: 'MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE',
+      where: migrationPathRelative(pkg.dirPath),
+      why: `Migration "${pkg.dirName}" has an unparseable contract snapshot at ${snapshotDir}/contract.json.`,
+      fix: 'Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.',
+    };
+  }
+  const record = raw !== null && typeof raw === 'object' ? (raw as Record<string, unknown>) : {};
+  const storage = record['storage'] as Record<string, unknown> | undefined;
+  const snapshotHash = storage?.['storageHash'];
+  if (typeof snapshotHash === 'string' && snapshotHash !== pkg.metadata.to) {
+    return {
+      space: spaceId,
+      code: 'MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH',
+      where: migrationPathRelative(pkg.dirPath),
+      why: `Migration "${pkg.dirName}" declares to=${pkg.metadata.to} but its contract snapshot has storageHash=${snapshotHash}`,
+      fix: 'Re-emit the migration package so migration.json and its contract snapshot agree.',
     };
   }
   return null;
@@ -137,6 +166,8 @@ export interface CheckSpace {
   readonly graph: MigrationGraph;
   readonly migrationsDir: string;
   readonly refsDir: string;
+  /** Migrations root the contract-snapshot store lives under — shared by every space. */
+  readonly projectMigrationsDir: string;
 }
 
 /**
@@ -152,9 +183,7 @@ export async function enumerateCheckSpaces(
   projectMigrationsDir: string,
 ): Promise<readonly CheckSpace[]> {
   const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
-  const onDiskSpaceIds = new Set(
-    candidateDirs.filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name)).filter(isValidSpaceId),
-  );
+  const onDiskSpaceIds = new Set(candidateDirs.filter(isValidSpaceId));
   const spaces: CheckSpace[] = [];
   for (const space of aggregate.spaces()) {
     const spaceId = space.spaceId;
@@ -168,6 +197,7 @@ export async function enumerateCheckSpaces(
       graph: space.graph(),
       migrationsDir,
       refsDir: spaceRefsDirectory(migrationsDir),
+      projectMigrationsDir,
     });
   }
   return spaces;
@@ -212,7 +242,7 @@ function checkReachability(space: CheckSpace): readonly CheckFailure[] {
     if (!isReachable) {
       failures.push({
         space: space.spaceId,
-        code: 'PN-MIG-CHECK-003',
+        code: 'MIGRATION.CHECK_UNREACHABLE_MIGRATION',
         where: migrationPathRelative(pkg.dirPath),
         why: `Migration "${pkg.dirName}" starts from ${pkg.metadata.from} which no other migration produces`,
         fix: 'This migration is unreachable in the graph. Delete it or re-emit a connecting migration.',
@@ -228,7 +258,7 @@ function checkDanglingRefs(space: CheckSpace): readonly CheckFailure[] {
     if (!space.graph.nodes.has(entry.hash)) {
       failures.push({
         space: space.spaceId,
-        code: 'PN-MIG-CHECK-004',
+        code: 'MIGRATION.CHECK_DANGLING_REF',
         where: relative(process.cwd(), join(space.refsDir, `${name}.json`)),
         why: `Ref "${name}" points at ${entry.hash} which does not exist in the migration graph`,
         fix: `Update the ref with \`prisma-next ref set ${name} <valid-hash>\` or delete it.`,
@@ -238,12 +268,15 @@ function checkDanglingRefs(space: CheckSpace): readonly CheckFailure[] {
   return failures;
 }
 
-function checkSpace(space: CheckSpace): readonly CheckFailure[] {
+async function checkSpace(space: CheckSpace): Promise<readonly CheckFailure[]> {
+  const snapshotFailures = await Promise.all(
+    space.packages.map((pkg) =>
+      checkSnapshotConsistency(space.spaceId, pkg, space.projectMigrationsDir),
+    ),
+  );
   return [
     ...checkManifestFilesPresent(space),
-    ...space.packages
-      .map((pkg) => checkSnapshotConsistency(space.spaceId, pkg))
-      .filter((f): f is CheckFailure => f !== null),
+    ...snapshotFailures.filter((f): f is CheckFailure => f !== null),
     ...checkReachability(space),
     ...checkDanglingRefs(space),
   ];
@@ -272,9 +305,9 @@ export interface RunMigrationCheckInputs {
  * Aggregate-integrity violations (which already span every space) are folded
  * in by the caller, not here.
  */
-export function runMigrationCheck(
+export async function runMigrationCheck(
   inputs: RunMigrationCheckInputs,
-): Result<MigrationCheckResult, CliStructuredError> {
+): Promise<Result<MigrationCheckResult, CliStructuredError>> {
   const { spaces, spaceFilter } = inputs;
 
   if (spaceFilter !== undefined && !isValidSpaceId(spaceFilter)) {
@@ -287,7 +320,7 @@ export function runMigrationCheck(
   const scopedSpaces =
     spaceFilter !== undefined ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
 
-  const failures = scopedSpaces.flatMap(checkSpace);
+  const failures = (await Promise.all(scopedSpaces.map(checkSpace))).flat();
   if (failures.length === 0) {
     return ok({ ok: true, failures: [], summary: 'All checks passed' });
   }
@@ -365,7 +398,7 @@ async function executeMigrationCheckCommand(
     });
   }
 
-  const checkResult = runMigrationCheck({
+  const checkResult = await runMigrationCheck({
     spaces,
     ...(options.space !== undefined ? { spaceFilter: options.space } : {}),
   });
@@ -522,7 +555,7 @@ async function checkSingleTarget(
       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
+      // parse failure through the shared ref-resolution envelope (CONTRACT.VERIFY_FAILED) 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 };
@@ -551,14 +584,18 @@ async function checkSingleTarget(
   if (!verification.ok) {
     failures.push({
       space: matchedSpace.spaceId,
-      code: 'PN-MIG-CHECK-001',
+      code: 'MIGRATION.CHECK_HASH_MISMATCH',
       where: migrationFileRelative(matchedPkg.dirPath, 'migration.json'),
       why: `Stored hash ${verification.storedHash} does not match recomputed hash ${verification.computedHash}`,
       fix: 'Re-emit the migration package or restore from version control.',
     });
   }
 
-  const snapshotFailure = checkSnapshotConsistency(matchedSpace.spaceId, matchedPkg);
+  const snapshotFailure = await checkSnapshotConsistency(
+    matchedSpace.spaceId,
+    matchedPkg,
+    matchedSpace.projectMigrationsDir,
+  );
   if (snapshotFailure) failures.push(snapshotFailure);
 
   const resolvedSpaceId = matchedSpace.spaceId !== 'app' ? matchedSpace.spaceId : undefined;

package/src/commands/migration-list.ts

@@ -9,7 +9,6 @@ import {
   APP_SPACE_ID,
   isValidSpaceId,
   listContractSpaceDirectories,
-  RESERVED_SPACE_SUBDIR_NAMES,
 } from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
@@ -81,10 +80,7 @@ export function listRefsByContractHash(
 
 async function orderedOnDiskSpaceIds(projectMigrationsDir: string): Promise<readonly string[]> {
   const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
-  return candidateDirs
-    .filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name))
-    .filter(isValidSpaceId)
-    .sort(compareSpaceIds);
+  return candidateDirs.filter(isValidSpaceId).sort(compareSpaceIds);
 }
 
 /**