@prisma-next/migration-tools 0.5.0-dev.6 → 0.5.0-dev.60

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.5.0-dev.6",
+  "version": "0.5.0-dev.60",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
-  "description": "On-disk migration persistence, attestation, and chain reconstruction for Prisma Next",
+  "description": "On-disk migration persistence, hash verification, and chain reconstruction for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.29",
     "pathe": "^2.0.3",
     "prettier": "^3.6.2",
-    "@prisma-next/contract": "0.5.0-dev.6",
-    "@prisma-next/utils": "0.5.0-dev.6",
-    "@prisma-next/framework-components": "0.5.0-dev.6"
+    "@prisma-next/contract": "0.5.0-dev.60",
+    "@prisma-next/framework-components": "0.5.0-dev.60",
+    "@prisma-next/utils": "0.5.0-dev.60"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
@@ -27,21 +28,37 @@
     "node": ">=20"
   },
   "exports": {
-    "./types": {
-      "types": "./dist/exports/types.d.mts",
-      "import": "./dist/exports/types.mjs"
+    "./metadata": {
+      "types": "./dist/exports/metadata.d.mts",
+      "import": "./dist/exports/metadata.mjs"
+    },
+    "./package": {
+      "types": "./dist/exports/package.d.mts",
+      "import": "./dist/exports/package.mjs"
+    },
+    "./graph": {
+      "types": "./dist/exports/graph.d.mts",
+      "import": "./dist/exports/graph.mjs"
+    },
+    "./errors": {
+      "types": "./dist/exports/errors.d.mts",
+      "import": "./dist/exports/errors.mjs"
     },
     "./io": {
       "types": "./dist/exports/io.d.mts",
       "import": "./dist/exports/io.mjs"
     },
-    "./attestation": {
-      "types": "./dist/exports/attestation.d.mts",
-      "import": "./dist/exports/attestation.mjs"
+    "./hash": {
+      "types": "./dist/exports/hash.d.mts",
+      "import": "./dist/exports/hash.mjs"
+    },
+    "./invariants": {
+      "types": "./dist/exports/invariants.d.mts",
+      "import": "./dist/exports/invariants.mjs"
     },
-    "./dag": {
-      "types": "./dist/exports/dag.d.mts",
-      "import": "./dist/exports/dag.mjs"
+    "./migration-graph": {
+      "types": "./dist/exports/migration-graph.d.mts",
+      "import": "./dist/exports/migration-graph.mjs"
     },
     "./refs": {
       "types": "./dist/exports/refs.d.mts",

package/src/errors.ts

@@ -1,10 +1,30 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import { basename, dirname, relative } from 'pathe';
+
+/**
+ * Build the canonical "re-emit this package" remediation hint.
+ *
+ * Every on-disk migration package ships its own `migration.ts` author-time
+ * file. Running it regenerates `migration.json` and `ops.json` with the
+ * correct hash + metadata, so it is the right primitive whenever a single
+ * package's on-disk artifacts are missing, malformed, or otherwise corrupt.
+ * Pointing users at `migration plan` would emit a *new* package rather than
+ * heal the broken one.
+ */
+function reemitHint(dir: string, fallback?: string): string {
+  const relativeDir = relative(process.cwd(), dir);
+  const reemit = `Re-emit the package by running \`node "${relativeDir}/migration.ts"\``;
+  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;
+}
+
 /**
  * Structured error for migration tooling operations.
  *
  * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
- * the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
- * migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
- * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+ * the MIGRATION namespace. These are tooling-time errors (file I/O, hash
+ * verification, migration history reconstruction), distinct from the runtime
+ * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
+ * etc.).
  *
  * Fields:
  * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
@@ -55,7 +75,10 @@ export function errorDirectoryExists(dir: string): MigrationToolsError {
 export function errorMissingFile(file: string, dir: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {
     why: `Expected "${file}" in "${dir}" but the file does not exist.`,
-    fix: 'Ensure the migration directory contains both migration.json and ops.json. If the directory is corrupt, delete it and re-run migration plan.',
+    fix: reemitHint(
+      dir,
+      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+    ),
     details: { file, dir },
   });
 }
@@ -63,19 +86,52 @@ export function errorMissingFile(file: string, dir: string): MigrationToolsError
 export function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {
     why: `Failed to parse "${filePath}": ${parseError}`,
-    fix: 'Fix the JSON syntax error, or delete the migration directory and re-run migration plan.',
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, parseError },
   });
 }
 
 export function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {
-    why: `Manifest at "${filePath}" is invalid: ${reason}`,
-    fix: 'Ensure the manifest has all required fields (from, to, kind, toContract). If corrupt, delete and re-plan.',
+    why: `Migration manifest at "${filePath}" is invalid: ${reason}`,
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, reason },
   });
 }
 
+export function errorInvalidOperationEntry(index: number, reason: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.INVALID_OPERATION_ENTRY',
+    'Migration operation entry is malformed',
+    {
+      why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,
+      fix: "Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').",
+      details: { index, reason },
+    },
+  );
+}
+
+export function errorStaleContractBookends(args: {
+  readonly side: 'from' | 'to';
+  readonly metaHash: string | null;
+  readonly contractHash: string;
+}): MigrationToolsError {
+  const { side, metaHash, contractHash } = args;
+  // `meta.from` is `string | null` (null = baseline). Render `null` as a
+  // human-readable token in the diagnostic so the message stays clear when
+  // the mismatch is a baseline-vs-non-baseline disagreement.
+  const renderedMetaHash = metaHash === null ? 'null (baseline)' : `"${metaHash}"`;
+  return new MigrationToolsError(
+    'MIGRATION.STALE_CONTRACT_BOOKENDS',
+    'Migration manifest contract bookends disagree with describe()',
+    {
+      why: `migration.json stores ${side}Contract.storage.storageHash "${contractHash}", but describe() returned meta.${side} = ${renderedMetaHash}. The bookend is stale — most likely the migration's describe() was edited after the package was scaffolded by \`migration plan\`.`,
+      fix: 'Re-run `migration plan` to regenerate the package with fresh contract bookends, or restore the directory from version control.',
+      details: { side, metaHash, contractHash },
+    },
+  );
+}
+
 export function errorInvalidSlug(slug: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {
     why: `The slug "${slug}" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,
@@ -92,13 +148,17 @@ export function errorInvalidDestName(destName: string): MigrationToolsError {
   });
 }
 
-export function errorSameSourceAndTarget(dirName: string, hash: string): MigrationToolsError {
+export function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {
+  const dirName = basename(dir);
   return new MigrationToolsError(
     'MIGRATION.SAME_SOURCE_AND_TARGET',
-    'Migration has same source and target',
+    'Migration without data-transform operations has same source and target',
     {
-      why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
-      fix: 'Delete the invalid migration directory and re-run migration plan.',
+      why: `Migration "${dirName}" has from === to === "${hash}" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,
+      fix: reemitHint(
+        dir,
+        'and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted.',
+      ),
       details: { dirName, hash },
     },
   );
@@ -175,14 +235,147 @@ export function errorInvalidRefValue(value: string): MigrationToolsError {
   });
 }
 
-export function errorDuplicateMigrationId(migrationId: string): MigrationToolsError {
+export function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.DUPLICATE_MIGRATION_HASH',
+    'Duplicate migrationHash in migration graph',
+    {
+      why: `Multiple migrations share migrationHash "${migrationHash}". Each migration must have a unique content-addressed identity.`,
+      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',
+      details: { migrationHash },
+    },
+  );
+}
+
+export function errorInvalidInvariantId(invariantId: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {
+    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,
+    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. "backfill-user-phone", "users/backfill-phone", or "BackfillUserPhone".',
+    details: { invariantId },
+  });
+}
+
+export function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {
   return new MigrationToolsError(
-    'MIGRATION.DUPLICATE_MIGRATION_ID',
-    'Duplicate migrationId in migration graph',
+    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',
+    'Duplicate invariantId on a single migration',
     {
-      why: `Multiple migrations share migrationId "${migrationId}". Each migration must have a unique content-addressed identity.`,
-      fix: 'Regenerate one of the conflicting migrations so each migrationId is unique, then re-run migration commands.',
-      details: { migrationId },
+      why: `invariantId "${invariantId}" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,
+      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',
+      details: { invariantId },
     },
   );
 }
+
+export function errorProvidedInvariantsMismatch(
+  filePath: string,
+  stored: readonly string[],
+  derived: readonly string[],
+): MigrationToolsError {
+  const storedSet = new Set(stored);
+  const derivedSet = new Set(derived);
+  const missing = [...derivedSet].filter((id) => !storedSet.has(id));
+  const extra = [...storedSet].filter((id) => !derivedSet.has(id));
+  // When sets agree but arrays don't, the only difference is ordering — call
+  // it out so the reader doesn't stare at two visually-identical arrays.
+  // Canonical providedInvariants is sorted ascending; a manifest with the
+  // same ids in a different order is still a mismatch (the hash check would
+  // also fail), but the human-readable diagnostic is otherwise unhelpful.
+  const orderingOnly = missing.length === 0 && extra.length === 0;
+  const why = orderingOnly
+    ? `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`
+    : `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;
+  return new MigrationToolsError(
+    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',
+    'providedInvariants on migration.json disagrees with ops.json',
+    {
+      why,
+      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
+      details: { filePath, stored, derived, difference: { missing, extra } },
+    },
+  );
+}
+
+/**
+ * Wire-shape edge surfaced through the JSON envelope's
+ * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —
+ * authoring metadata (`createdAt`, `labels`) lives on `MigrationEdge` but
+ * is intentionally dropped here so the envelope stays stable across
+ * graph-internal refactors.
+ *
+ * Stability: any field added here is part of the public CLI JSON contract.
+ * Callers (CLI consumers, agents) must be able to treat
+ * `(dirName, migrationHash, from, to, invariants)` as the canonical shape.
+ */
+export interface NoInvariantPathStructuralEdge {
+  readonly dirName: string;
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly invariants: readonly string[];
+}
+
+export function errorNoInvariantPath(args: {
+  readonly refName?: string;
+  readonly required: readonly string[];
+  readonly missing: readonly string[];
+  readonly structuralPath: readonly NoInvariantPathStructuralEdge[];
+}): MigrationToolsError {
+  const { refName, required, missing, structuralPath } = args;
+  const refClause = refName ? `Ref "${refName}"` : 'Target';
+  const missingList = missing.map((id) => JSON.stringify(id)).join(', ');
+  const requiredList = required.map((id) => JSON.stringify(id)).join(', ');
+  return new MigrationToolsError(
+    'MIGRATION.NO_INVARIANT_PATH',
+    'No path covers the required invariants',
+    {
+      why: `${refClause} requires invariants the reachable path doesn't cover. required=[${requiredList}], missing=[${missingList}].`,
+      fix: 'Add a migration on the path that runs `dataTransform({ invariantId: "<id>", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.',
+      details: {
+        required,
+        missing,
+        structuralPath,
+        ...ifDefined('refName', refName),
+      },
+    },
+  );
+}
+
+export function errorUnknownInvariant(args: {
+  readonly refName?: string;
+  readonly unknown: readonly string[];
+  readonly declared: readonly string[];
+}): MigrationToolsError {
+  const { refName, unknown, declared } = args;
+  const refClause = refName ? `Ref "${refName}" declares` : 'Declares';
+  const unknownList = unknown.map((id) => JSON.stringify(id)).join(', ');
+  return new MigrationToolsError(
+    'MIGRATION.UNKNOWN_INVARIANT',
+    'Ref declares invariants no migration in the graph provides',
+    {
+      why: `${refClause} invariants no migration in the graph provides. unknown=[${unknownList}].`,
+      fix: 'Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.',
+      details: {
+        unknown,
+        declared,
+        ...ifDefined('refName', refName),
+      },
+    },
+  );
+}
+
+export function errorMigrationHashMismatch(
+  dir: string,
+  storedHash: string,
+  computedHash: string,
+): MigrationToolsError {
+  // Render a cwd-relative path in the human-readable diagnostic so users
+  // running CLI commands from the project root see a familiar short path.
+  // Keep the absolute path in `details.dir` for machine consumers.
+  const relativeDir = relative(process.cwd(), dir);
+  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {
+    why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relativeDir}". The migration.json or ops.json has been edited or partially written since emit.`,
+    fix: reemitHint(dir, 'or restore the directory from version control.'),
+    details: { dir, storedHash, computedHash },
+  });
+}

package/src/exports/errors.ts

@@ -0,0 +1,7 @@
+export {
+  errorInvalidJson,
+  errorNoInvariantPath,
+  errorUnknownInvariant,
+  MigrationToolsError,
+  type NoInvariantPathStructuralEdge,
+} from '../errors';

package/src/exports/graph.ts

@@ -0,0 +1 @@
+export type { MigrationEdge, MigrationGraph } from '../graph';

package/src/exports/hash.ts

@@ -0,0 +1,2 @@
+export type { VerifyResult } from '../hash';
+export { computeMigrationHash, verifyMigrationHash } from '../hash';

package/src/exports/invariants.ts

@@ -0,0 +1 @@
+export { deriveProvidedInvariants, validateInvariantId } from '../invariants';

package/src/exports/io.ts

@@ -3,7 +3,7 @@ export {
   formatMigrationDirName,
   readMigrationPackage,
   readMigrationsDir,
-  writeMigrationManifest,
+  writeMigrationMetadata,
   writeMigrationOps,
   writeMigrationPackage,
 } from '../io';

package/src/exports/metadata.ts

@@ -0,0 +1 @@
+export type { MigrationHints, MigrationMetadata } from '../metadata';

package/src/exports/{dag.ts → migration-graph.ts}

@@ -1,4 +1,4 @@
-export type { PathDecision } from '../dag';
+export type { PathDecision } from '../migration-graph';
 export {
   detectCycles,
   detectOrphans,
@@ -6,6 +6,7 @@ export {
   findLeaf,
   findPath,
   findPathWithDecision,
+  findPathWithInvariants,
   findReachableLeaves,
   reconstructGraph,
-} from '../dag';
+} from '../migration-graph';

package/src/exports/migration.ts

@@ -4,5 +4,4 @@ export {
   Migration,
   type MigrationArtifacts,
   type MigrationMeta,
-  printMigrationHelp,
 } from '../migration-base';

package/src/exports/package.ts

@@ -0,0 +1 @@
+export type { MigrationOps, MigrationPackage } from '../package';

package/src/graph-ops.ts

@@ -3,13 +3,18 @@ import { Queue } from './queue';
 /**
  * One step of a BFS traversal.
  *
- * `parent` and `incomingEdge` are `null` for start nodes — they were not
- * reached via any edge. For every other node they record the node and edge
- * by which this node was first reached.
+ * `parent` and `incomingEdge` are `null` for start states — they were not
+ * reached via any edge. For every other state they record the predecessor
+ * state and the edge by which this state was first reached.
+ *
+ * `state` is the BFS state, most often a string (graph node identifier) but
+ * can be a composite object. The string overload keeps the common case
+ * ergonomic; the generic overload accepts a caller-supplied `key` function
+ * that produces a stable equality key for dedup.
  */
-export interface BfsStep<E> {
-  readonly node: string;
-  readonly parent: string | null;
+export interface BfsStep<S, E> {
+  readonly state: S;
+  readonly parent: S | null;
   readonly incomingEdge: E | null;
 }
 
@@ -17,48 +22,70 @@ export interface BfsStep<E> {
  * Generic breadth-first traversal.
  *
  * Direction (forward/reverse) is expressed by the caller's `neighbours`
- * closure: return `{ next, edge }` pairs where `next` is the node to visit
+ * closure: return `{ next, edge }` pairs where `next` is the state to visit
  * next and `edge` is the edge that connects them. Callers that don't need
  * path reconstruction can ignore the `parent`/`incomingEdge` fields of each
  * yielded step.
  *
+ * Ordering — when the result needs to be deterministic (path-finding) the
+ * caller is responsible for sorting inside `neighbours`; this generator
+ * does not impose an ordering hook of its own. State-dependent orderings
+ * have full access to the source state inside the closure.
+ *
  * Stops are intrinsic — callers `break` out of the `for..of` loop when
  * they've found what they're looking for.
- *
- * `ordering`, if provided, controls the order in which neighbours of each
- * node are enqueued. Only matters for path-finding: a deterministic ordering
- * makes BFS return a deterministic shortest path when multiple exist.
  */
-export function* bfs<E>(
+export function bfs<E>(
   starts: Iterable<string>,
-  neighbours: (node: string) => Iterable<{ next: string; edge: E }>,
-  ordering?: (items: readonly { next: string; edge: E }[]) => readonly { next: string; edge: E }[],
-): Generator<BfsStep<E>> {
+  neighbours: (state: string) => Iterable<{ next: string; edge: E }>,
+): Generator<BfsStep<string, E>>;
+export function bfs<S, E>(
+  starts: Iterable<S>,
+  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,
+  key: (state: S) => string,
+): Generator<BfsStep<S, E>>;
+export function* bfs<S, E>(
+  starts: Iterable<S>,
+  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,
+  // Identity default for the string overload. TypeScript can't express
+  // "default applies only when S = string", so this cast bridges the
+  // generic implementation signature to the public overloads — which
+  // guarantee `key` is omitted only when S = string at the call site.
+  key: (state: S) => string = (state) => state as unknown as string,
+): Generator<BfsStep<S, E>> {
+  // Queue entries carry the state alongside its key so we don't recompute
+  // key() twice per visit (once on dedup, once on parent lookup). Composite
+  // keys can be non-trivial to compute; string-overload callers pay nothing
+  // since key() is identity there.
+  interface Entry {
+    readonly state: S;
+    readonly key: string;
+  }
   const visited = new Set<string>();
-  const parentMap = new Map<string, { parent: string; edge: E }>();
-  const queue = new Queue<string>();
+  const parentMap = new Map<string, { parent: S; edge: E }>();
+  const queue = new Queue<Entry>();
   for (const start of starts) {
-    if (!visited.has(start)) {
-      visited.add(start);
-      queue.push(start);
+    const k = key(start);
+    if (!visited.has(k)) {
+      visited.add(k);
+      queue.push({ state: start, key: k });
     }
   }
   while (!queue.isEmpty) {
-    const current = queue.shift();
-    const parentInfo = parentMap.get(current);
+    const { state: current, key: curKey } = queue.shift();
+    const parentInfo = parentMap.get(curKey);
     yield {
-      node: current,
+      state: current,
       parent: parentInfo?.parent ?? null,
       incomingEdge: parentInfo?.edge ?? null,
     };
 
-    const items = neighbours(current);
-    const toVisit = ordering ? ordering([...items]) : items;
-    for (const { next, edge } of toVisit) {
-      if (!visited.has(next)) {
-        visited.add(next);
-        parentMap.set(next, { parent: current, edge });
-        queue.push(next);
+    for (const { next, edge } of neighbours(current)) {
+      const k = key(next);
+      if (!visited.has(k)) {
+        visited.add(k);
+        parentMap.set(k, { parent: current, edge });
+        queue.push({ state: next, key: k });
       }
     }
   }

package/src/graph.ts

@@ -0,0 +1,25 @@
+/**
+ * An entry in the migration graph. All on-disk migrations are attested,
+ * so `migrationHash` is always a string.
+ */
+export interface MigrationEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s this edge provides.
+   * An empty array means the migration declares no routing-visible
+   * data transforms.
+   */
+  readonly invariants: readonly string[];
+}
+
+export interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly migrationByHash: ReadonlyMap<string, MigrationEdge>;
+}

package/src/hash.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeJson } from './canonicalize-json';
+import type { MigrationMetadata } from './metadata';
+import type { MigrationOps, MigrationPackage } from './package';
+
+export interface VerifyResult {
+  readonly ok: boolean;
+  readonly reason?: 'mismatch';
+  readonly storedHash: string;
+  readonly computedHash: string;
+}
+
+function sha256Hex(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+/**
+ * Content-addressed migration hash over (metadata envelope sans
+ * contracts/hints/signature, ops). See ADR 199 — Storage-only migration
+ * identity for the rationale: contracts are anchored separately by the
+ * storage-hash bookends inside the envelope; planner hints are advisory
+ * and must not affect identity.
+ *
+ * The integrity check is purely structural, not semantic. The function
+ * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
+ * and hashes the result. Target-specific operation payloads (`step.sql`,
+ * Mongo's pipeline AST, …) are hashed verbatim — no per-target
+ * normalization is required, because what's being verified is "do the
+ * on-disk bytes still produce their recorded hash", not "do two
+ * semantically-equivalent migrations hash the same". The latter is an
+ * emit-drift concern (ADR 192 step 2).
+ *
+ * The symmetry across write and read holds because `JSON.parse(
+ * JSON.stringify(x))` round-trips JSON-safe values losslessly and
+ * `sortKeys` is idempotent and deterministic — write-time and read-time
+ * canonicalization produce the same canonical bytes regardless of
+ * source-side key ordering or whitespace.
+ *
+ * The `migrationHash` field on the metadata is stripped before hashing
+ * so the function can be used both at write time (when no hash exists
+ * yet) and at verify time (rehashing an already-attested record).
+ */
+export function computeMigrationHash(
+  metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },
+  ops: MigrationOps,
+): string {
+  const {
+    migrationHash: _migrationHash,
+    signature: _signature,
+    fromContract: _fromContract,
+    toContract: _toContract,
+    hints: _hints,
+    ...strippedMeta
+  } = metadata;
+
+  const canonicalMetadata = canonicalizeJson(strippedMeta);
+  const canonicalOps = canonicalizeJson(ops);
+
+  const partHashes = [canonicalMetadata, canonicalOps].map(sha256Hex);
+  const hash = sha256Hex(canonicalizeJson(partHashes));
+
+  return `sha256:${hash}`;
+}
+
+/**
+ * Re-hash an in-memory migration package and compare against the stored
+ * `migrationHash`. See `computeMigrationHash` for the canonicalization rules.
+ *
+ * Returns `{ ok: true }` when the package is internally consistent, or
+ * `{ ok: false, reason: 'mismatch', storedHash, computedHash }` when it is
+ * not — typically a sign of FS corruption, partial writes, or a post-emit
+ * hand edit.
+ */
+export function verifyMigrationHash(pkg: MigrationPackage): VerifyResult {
+  const computed = computeMigrationHash(pkg.metadata, pkg.ops);
+
+  if (pkg.metadata.migrationHash === computed) {
+    return {
+      ok: true,
+      storedHash: pkg.metadata.migrationHash,
+      computedHash: computed,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: 'mismatch',
+    storedHash: pkg.metadata.migrationHash,
+    computedHash: computed,
+  };
+}