@prisma-next/cli 0.8.0 → 0.9.0-dev.2

package/src/commands/{migration-apply.ts → migrate.ts}

@@ -1,8 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
+import { createControlStack } from '@prisma-next/framework-components/control';
 import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
-import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -25,6 +27,7 @@ import {
   errorTargetMigrationNotSupported,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -44,29 +47,16 @@ import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
 import { TerminalUI } from '../utils/terminal-ui';
 
-interface MigrationApplyCommandOptions extends CommonCommandOptions {
+interface MigrateCommandOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
-  readonly ref?: string;
+  readonly to?: string;
 }
 
-/**
- * Per-space breakdown of an apply run. The CLI command surfaces these
- * for both the JSON shape (`appliedSpaces[]`) and the human-readable
- * formatter (per-space block — same shape `db init` / `db update`
- * use, M6 sub-spec § Output shape contract).
- */
-export interface MigrationApplyResult {
+export interface MigrateResult {
   readonly ok: boolean;
-  /** Number of contract spaces that had non-zero pending operations applied. */
   readonly migrationsApplied: number;
-  /** Total contract spaces visible in the aggregate (pending + already-up-to-date). */
   readonly migrationsTotal: number;
-  /**
-   * Marker hash for the **app member** post-apply. Surfaced for
-   * back-compat with single-space callers; per-space markers live on
-   * `perSpace[].marker.storageHash`.
-   */
   readonly markerHash: string;
   readonly applied: readonly {
     readonly spaceId: string;
@@ -77,17 +67,7 @@ export interface MigrationApplyResult {
     readonly operationsExecuted: number;
   }[];
   readonly summary: string;
-  /**
-   * Per-space breakdown in canonical schedule order (extensions
-   * alphabetically, then app). Always present for the aggregate-walking
-   * apply path.
-   */
   readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
-  /**
-   * Path-decision data for the app member. Surfaced for back-compat
-   * with single-space callers (cli-journeys invariant tests).
-   * Absent for no-op applies where the app had nothing to do.
-   */
   readonly pathDecision?: MigrationApplyPathDecision;
   readonly timings: {
     readonly total: number;
@@ -97,17 +77,17 @@ export interface MigrationApplyResult {
 function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
   return errorRuntime(failure.summary, {
     why: failure.why ?? 'Migration runner failed',
-    fix: 'Fix the issue and re-run `prisma-next migration apply` — previously applied migrations are preserved.',
+    fix: 'Fix the issue and re-run `prisma-next migrate --to <contract>` — previously applied migrations are preserved.',
     meta: failure.meta ?? {},
   });
 }
 
-async function executeMigrationApplyCommand(
-  options: MigrationApplyCommandOptions,
+async function executeMigrateCommand(
+  options: MigrateCommandOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
   startTime: number,
-): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
+): Promise<Result<MigrateResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
   const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
     resolveMigrationPaths(options.config, config);
@@ -116,8 +96,8 @@ async function executeMigrationApplyCommand(
   if (!dbConnection) {
     return notOk(
       errorDatabaseConnectionRequired({
-        why: `Database connection is required for migration apply (set db.connection in ${configPath}, or pass --db <url>)`,
-        commandName: 'migration apply',
+        why: `Database connection is required for migrate (set db.connection in ${configPath}, or pass --db <url>)`,
+        commandName: 'migrate',
       }),
     );
   }
@@ -125,7 +105,7 @@ async function executeMigrationApplyCommand(
   if (!config.driver) {
     return notOk(
       errorDriverRequired({
-        why: 'Config.driver is required for migration apply',
+        why: 'Config.driver is required for migrate',
       }),
     );
   }
@@ -139,12 +119,22 @@ async function executeMigrationApplyCommand(
   }
 
   let refEntry: RefEntry | undefined;
-  const refName = options.ref;
+  const toArg = options.to;
 
-  if (refName) {
+  if (toArg) {
     try {
       const refs = await readRefs(refsDir);
-      refEntry = resolveRef(refs, refName);
+      const { graph } = await loadMigrationPackages(appMigrationsDir);
+      const refResult = parseContractRef(toArg, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      if (refResult.value.provenance.kind === 'ref') {
+        const resolved = refs[refResult.value.provenance.refName];
+        if (resolved) refEntry = resolved;
+      } else {
+        refEntry = { hash: refResult.value.hash, invariants: [] };
+      }
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -153,25 +143,42 @@ async function executeMigrationApplyCommand(
     }
   }
 
-  // Resolve and parse the contract envelope. The aggregate-walking
-  // operation needs the validated app contract to load the aggregate.
+  // Construct the family instance up-front so the on-disk contract read
+  // crosses the serializer seam (`familyInstance.deserializeContract`) at
+  // the read site. The downstream `client.migrationApply({ contract })`
+  // re-validates internally (no harm — validation is idempotent), but
+  // closing the gap at the read site is what makes the cast-pattern
+  // lint enforceable and matches the other CLI commands. See TML-2536.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
   const contractPathAbsolute = resolveContractPath(config);
   let contractRaw: Contract;
+  let contractContent: string;
   try {
-    const contractContent = await readFile(contractPathAbsolute, 'utf-8');
-    contractRaw = JSON.parse(contractContent) as Contract;
+    contractContent = 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 a valid contract.json, then retry apply.',
+          fix: 'Run `prisma-next contract emit` to generate a valid contract.json, then retry.',
         }),
       );
     }
     return notOk(
       errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
+  }
+  try {
+    contractRaw = familyInstance.deserializeContract(JSON.parse(contractContent) as unknown);
+  } catch (error) {
+    return notOk(
+      errorContractValidationFailed(
+        `Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
         { where: { path: contractPathAbsolute } },
       ),
     );
@@ -188,21 +195,19 @@ async function executeMigrationApplyCommand(
         value: maskConnectionUrl(dbConnection),
       });
     }
-    if (refName) {
-      details.push({ label: 'ref', value: refName });
+    if (toArg) {
+      details.push({ label: 'to', value: toArg });
     }
     const header = formatStyledHeader({
-      command: 'migration apply',
-      description: 'Apply planned migrations to the database',
-      url: 'https://pris.ly/migration-apply',
+      command: 'migrate',
+      description: 'Apply planned migrations to advance the database',
+      url: 'https://pris.ly/migrate',
       details,
       flags,
     });
     ui.stderr(header);
   }
 
-  // Load app-space migration packages — the aggregate operation
-  // needs them to hydrate the app member's graph for graph-walk.
   let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
   try {
     appPackages = await loadMigrationPackages(appMigrationsDir);
@@ -224,13 +229,6 @@ async function executeMigrationApplyCommand(
   try {
     await client.connect(dbConnection);
 
-    // Pre-check unknown invariants against `(declared by app graph) ∪
-    // (already on the app marker)`. The marker side of the union
-    // catches the case where the ref carries an invariant whose
-    // declaring migration was retired (history rewritten) but whose
-    // id is recorded on the marker — surfacing UNKNOWN_INVARIANT
-    // there would be misleading because the database has already
-    // satisfied the requirement.
     if (refEntry && refEntry.invariants.length > 0) {
       const allMarkers = await client.readAllMarkers();
       const appMarker = allMarkers.get('app') ?? null;
@@ -242,7 +240,7 @@ async function executeMigrationApplyCommand(
         return notOk(
           mapMigrationToolsError(
             errorUnknownInvariant({
-              ...ifDefined('refName', refName),
+              ...ifDefined('refName', toArg),
               unknown,
               declared: [...declared].sort(),
             }),
@@ -261,7 +259,7 @@ async function executeMigrationApplyCommand(
       appMigrationPackages: appPackages.bundles,
       ...ifDefined('refHash', refEntry?.hash),
       ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
-      ...(refEntry !== undefined ? ifDefined('refName', refName) : {}),
+      ...(refEntry !== undefined ? ifDefined('refName', toArg) : {}),
     });
 
     if (!applyResult.ok) {
@@ -290,7 +288,7 @@ async function executeMigrationApplyCommand(
     }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Unexpected error during migration apply: ${error instanceof Error ? error.message : String(error)}`,
+        why: `Unexpected error during migrate: ${error instanceof Error ? error.message : String(error)}`,
       }),
     );
   } finally {
@@ -298,23 +296,29 @@ async function executeMigrationApplyCommand(
   }
 }
 
-export function createMigrationApplyCommand(): Command {
-  const command = new Command('apply');
+export function createMigrateCommand(): Command {
+  const command = new Command('migrate');
   setCommandDescriptions(
     command,
-    'Apply planned migrations to the database',
+    'Apply planned migrations to advance the database',
     'Walks every contract space (app + extensions) and applies pending\n' +
       'on-disk migrations in canonical order (extensions alphabetically,\n' +
-      'then app). Graph-walks the on-disk migration graph for every space —\n' +
-      "no introspection, no synth. Each space's marker advances inside its\n" +
-      "transaction; per-space failure rolls back every space's writes.",
+      'then app). Graph-walks the on-disk migration graph for every space.\n' +
+      'Use --to to target a specific contract (hash, ref name, migration dir).',
   );
-  setCommandExamples(command, ['prisma-next migration apply --db $DATABASE_URL']);
+  setCommandExamples(command, [
+    'prisma-next migrate --db $DATABASE_URL',
+    'prisma-next migrate --to production --db $DATABASE_URL',
+    'prisma-next migrate --to sha256:abc123 --db $DATABASE_URL',
+  ]);
   addGlobalOptions(command)
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--ref <name>', 'App-space target ref name from migrations/app/refs/')
-    .action(async (options: MigrationApplyCommandOptions) => {
+    .option(
+      '--to <contract>',
+      'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .action(async (options: MigrateCommandOptions) => {
       const flags = parseGlobalFlags(options);
       const startTime = Date.now();
 
@@ -323,13 +327,13 @@ export function createMigrationApplyCommand(): Command {
         interactive: flags.interactive,
       });
 
-      const result = await executeMigrationApplyCommand(options, flags, ui, startTime);
+      const result = await executeMigrateCommand(options, flags, ui, startTime);
 
-      const exitCode = handleResult(result, flags, ui, (applyResult) => {
+      const exitCode = handleResult(result, flags, ui, (migrateResult) => {
         if (flags.json) {
-          ui.output(JSON.stringify(applyResult, null, 2));
+          ui.output(JSON.stringify(migrateResult, null, 2));
         } else if (!flags.quiet) {
-          ui.log(formatMigrationApplyCommandOutput(applyResult, flags));
+          ui.log(formatMigrationApplyCommandOutput(migrateResult, flags));
         }
       });
 

package/src/commands/migration-check/exit-codes.ts

@@ -0,0 +1,3 @@
+export const OK = 0;
+export const PRECONDITION = 2;
+export const INTEGRITY_FAILED = 4;

package/src/commands/migration-check.ts

@@ -0,0 +1,369 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { verifyMigrationHash } from '@prisma-next/migration-tools/hash';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseMigrationRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
+import { Command } from 'commander';
+import { join, relative } from 'pathe';
+import { loadConfig } from '../config-loader';
+import {
+  addGlobalOptions,
+  loadMigrationPackages,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+  setCommandSeeAlso,
+} from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { TerminalUI } from '../utils/terminal-ui';
+import { INTEGRITY_FAILED, OK, PRECONDITION } from './migration-check/exit-codes';
+
+interface MigrationCheckOptions extends CommonCommandOptions {
+  readonly config?: string;
+}
+
+export interface CheckFailure {
+  readonly pnCode: string;
+  readonly where: string;
+  readonly why: string;
+  readonly fix: string;
+}
+
+export interface MigrationCheckResult {
+  readonly ok: boolean;
+  readonly failures: readonly CheckFailure[];
+  readonly summary: string;
+}
+
+/**
+ * Canonical user-facing locator for a check failure: the cwd-relative path
+ * to the migration package directory. Surfacing the same shape across every
+ * PN code means `--json` consumers can branch uniformly on `where`.
+ */
+function migrationPathRelative(dirPath: string): string {
+  return relative(process.cwd(), dirPath);
+}
+
+function migrationFileRelative(dirPath: string, fileName: string): string {
+  return join(migrationPathRelative(dirPath), fileName);
+}
+
+function checkFileExists(dirPath: string, dirName: string, fileName: string): CheckFailure | null {
+  if (!existsSync(join(dirPath, fileName))) {
+    return {
+      pnCode: 'PN-MIG-CHECK-002',
+      where: migrationFileRelative(dirPath, fileName),
+      why: `${fileName} is missing from ${dirName}`,
+      fix: 'Re-emit the migration package or restore from version control.',
+    };
+  }
+  return null;
+}
+
+/**
+ * Within-migration snapshot-consistency check (PN-MIG-CHECK-005).
+ *
+ * Compares the migration's stored `metadata.to` against the `storageHash`
+ * recorded in its on-disk `end-contract.json` snapshot. The two values are
+ * independent on-disk records of the same fact (the migration's destination
+ * contract); drift between them indicates the package is internally
+ * corrupt. Cross-migration consistency (one migration's end-contract.json
+ * agreeing with the next migration's start-contract.json) is a separate
+ * check that requires shadow execution and is deferred to
+ * `migration preflight`.
+ *
+ * Shared between the graph-wide and per-migration code paths so both report
+ * the same failure for the same on-disk state.
+ */
+function checkSnapshotConsistency(pkg: OnDiskMigrationPackage): CheckFailure | null {
+  const endContractPath = join(pkg.dirPath, 'end-contract.json');
+  if (!existsSync(endContractPath)) return null;
+  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 {
+        pnCode: '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.',
+      };
+    }
+  } catch {
+    return {
+      pnCode: 'PN-MIG-CHECK-006',
+      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.',
+    };
+  }
+  return null;
+}
+
+async function executeMigrationCheckCommand(
+  target: string | undefined,
+  options: MigrationCheckOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<{ result: MigrationCheckResult; exitCode: number }> {
+  const config = await loadConfig(options.config);
+  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  if (!flags.json && !flags.quiet) {
+    const details: Array<{ label: string; value: string }> = [
+      { label: 'config', value: configPath },
+      { label: 'migrations', value: appMigrationsRelative },
+    ];
+    if (target) {
+      details.push({ label: 'target', value: target });
+    }
+    const header = formatStyledHeader({
+      command: 'migration check',
+      description: 'Verify artifact and graph integrity',
+      details,
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  const failures: CheckFailure[] = [];
+
+  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
+  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
+  try {
+    const loaded = await loadMigrationPackages(appMigrationsDir);
+    bundles = loaded.bundles;
+    graph = loaded.graph;
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      const pnCode =
+        error.code === 'MIGRATION.HASH_MISMATCH' ? 'PN-MIG-CHECK-001' : 'PN-MIG-CHECK-002';
+      // Normalise to a cwd-relative path. `error.details.dir` is absolute
+      // (the migration-tools layer doesn't know the caller's cwd); the
+      // `filePath` fallback is also absolute. Surfacing the relative form
+      // matches the rest of the command's `where` shape and keeps `--json`
+      // consumers from having to special-case the bootstrap-failure path.
+      const rawWhere =
+        (error.details?.['dir'] as string) ?? (error.details?.['filePath'] as string) ?? null;
+      const where = rawWhere ? relative(process.cwd(), rawWhere) : 'unknown';
+      failures.push({
+        pnCode,
+        where,
+        why: error.why,
+        fix: error.fix,
+      });
+      return {
+        result: { ok: false, failures, summary: `${failures.length} integrity failure(s)` },
+        exitCode: INTEGRITY_FAILED,
+      };
+    }
+    throw error;
+  }
+
+  if (existsSync(appMigrationsDir)) {
+    const loadedDirNames = new Set(bundles.map((p) => p.dirName));
+    try {
+      const entries = readdirSync(appMigrationsDir);
+      for (const entry of entries) {
+        if (entry.startsWith('.') || entry.startsWith('_') || entry === 'refs') continue;
+        const entryPath = join(appMigrationsDir, entry);
+        try {
+          if (!statSync(entryPath).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+        if (!loadedDirNames.has(entry)) {
+          for (const f of ['migration.json', 'ops.json']) {
+            const fail = checkFileExists(entryPath, entry, f);
+            if (fail) failures.push(fail);
+          }
+        }
+      }
+    } catch {
+      // migrations dir unreadable — skip
+    }
+  }
+
+  if (target) {
+    const refs = await readRefs(refsDir);
+    const migResult = parseMigrationRef(target, { graph, refs });
+    if (!migResult.ok) {
+      const msg =
+        migResult.failure.kind === 'not-found'
+          ? `Migration "${target}" does not exist`
+          : migResult.failure.kind === 'wrong-grammar'
+            ? migResult.failure.message
+            : `Invalid migration reference: "${target}"`;
+      return {
+        result: { ok: false, failures: [], summary: msg },
+        exitCode: PRECONDITION,
+      };
+    }
+
+    const matchedPkg = bundles.find(
+      (p) => p.metadata.migrationHash === migResult.value.migrationHash,
+    );
+    if (!matchedPkg) {
+      return {
+        result: {
+          ok: false,
+          failures: [],
+          summary: `Migration package for "${target}" not found on disk`,
+        },
+        exitCode: PRECONDITION,
+      };
+    }
+
+    for (const f of ['migration.json', 'ops.json']) {
+      const fail = checkFileExists(matchedPkg.dirPath, matchedPkg.dirName, f);
+      if (fail) failures.push(fail);
+    }
+
+    const verification = verifyMigrationHash(matchedPkg);
+    if (!verification.ok) {
+      failures.push({
+        pnCode: 'PN-MIG-CHECK-001',
+        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.',
+      });
+    }
+
+    // PN-MIG-CHECK-005 must fire per-migration as well as graph-wide; both
+    // call sites delegate to the shared helper so the same on-disk drift
+    // produces the same failure regardless of how the user invoked check.
+    const snapshotFailure = checkSnapshotConsistency(matchedPkg);
+    if (snapshotFailure) failures.push(snapshotFailure);
+  } else {
+    for (const pkg of bundles) {
+      for (const f of ['migration.json', 'ops.json']) {
+        const fail = checkFileExists(pkg.dirPath, pkg.dirName, f);
+        if (fail) failures.push(fail);
+      }
+
+      const verification = verifyMigrationHash(pkg);
+      if (!verification.ok) {
+        failures.push({
+          pnCode: 'PN-MIG-CHECK-001',
+          where: migrationFileRelative(pkg.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.',
+        });
+      }
+    }
+
+    for (const pkg of bundles) {
+      const snapshotFailure = checkSnapshotConsistency(pkg);
+      if (snapshotFailure) failures.push(snapshotFailure);
+    }
+
+    const allToHashes = new Set(bundles.map((p) => p.metadata.to));
+    for (const pkg of bundles) {
+      const isReachable =
+        pkg.metadata.from === null ||
+        allToHashes.has(pkg.metadata.from) ||
+        pkg.metadata.from === 'sha256:empty';
+      if (!isReachable) {
+        failures.push({
+          pnCode: 'PN-MIG-CHECK-003',
+          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.',
+        });
+      }
+    }
+
+    try {
+      const refs = await readRefs(refsDir);
+      for (const [name, entry] of Object.entries(refs)) {
+        if (!graph.nodes.has(entry.hash)) {
+          failures.push({
+            pnCode: 'PN-MIG-CHECK-004',
+            where: relative(process.cwd(), join(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.`,
+          });
+        }
+      }
+    } catch {
+      // Refs unreadable — skip ref checks
+    }
+  }
+
+  if (failures.length === 0) {
+    return {
+      result: { ok: true, failures: [], summary: 'All checks passed' },
+      exitCode: OK,
+    };
+  }
+
+  return {
+    result: { ok: false, failures, summary: `${failures.length} integrity failure(s)` },
+    exitCode: INTEGRITY_FAILED,
+  };
+}
+
+export function createMigrationCheckCommand(): Command {
+  const command = new Command('check');
+  setCommandDescriptions(
+    command,
+    'Verify artifact and graph integrity',
+    '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). Offline — does not consult\n' +
+      'the database.',
+  );
+  setCommandExamples(command, [
+    'prisma-next migration check',
+    'prisma-next migration check 20260101-add-users',
+    'prisma-next migration check --json',
+  ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+  ]);
+  command.exitOverride();
+  addGlobalOptions(command)
+    .argument('[migration]', 'Migration reference (directory name or hash) to check')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (target: string | undefined, options: MigrationCheckOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+
+      let result: MigrationCheckResult;
+      let exitCode: number;
+      try {
+        ({ result, exitCode } = await executeMigrationCheckCommand(target, options, flags, ui));
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        result = { ok: false, failures: [], summary: msg };
+        exitCode = PRECONDITION;
+      }
+
+      if (flags.json) {
+        ui.output(JSON.stringify(result, null, 2));
+      } else if (!flags.quiet) {
+        if (result.ok) {
+          ui.log(`✔ ${result.summary}`);
+        } else {
+          for (const f of result.failures) {
+            ui.log(`✗ [${f.pnCode}] ${f.where}: ${f.why}`);
+            ui.log(`  fix: ${f.fix}`);
+          }
+          ui.log(`\n${result.summary}`);
+        }
+      }
+
+      process.exit(exitCode);
+    });
+
+  return command;
+}