@prisma-next/migration-tools 0.5.0-dev.3 → 0.5.0-dev.30

package/dist/exports/refs.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"refs.mjs","names":["raw: string","parsed: unknown"],"sources":["../../src/refs.ts"],"sourcesContent":["import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { dirname, join } from 'pathe';\nimport {\n  errorInvalidRefName,\n  errorInvalidRefs,\n  errorInvalidRefValue,\n  MigrationToolsError,\n} from './errors';\n\nexport type Refs = Readonly<Record<string, string>>;\n\nconst REF_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;\nconst REF_VALUE_PATTERN = /^sha256:(empty|[0-9a-f]{64})$/;\n\nexport function validateRefName(name: string): boolean {\n  if (name.length === 0) return false;\n  if (name.includes('..')) return false;\n  if (name.includes('//')) return false;\n  if (name.startsWith('.')) return false;\n  return REF_NAME_PATTERN.test(name);\n}\n\nexport function validateRefValue(value: string): boolean {\n  return REF_VALUE_PATTERN.test(value);\n}\n\nconst RefsSchema = type('Record<string, string>').narrow((refs, ctx) => {\n  for (const [key, value] of Object.entries(refs)) {\n    if (!validateRefName(key)) return ctx.mustBe(`valid ref names (invalid: \"${key}\")`);\n    if (!validateRefValue(value))\n      return ctx.mustBe(`valid contract hashes (invalid value for \"${key}\": \"${value}\")`);\n  }\n  return true;\n});\n\nexport async function readRefs(refsPath: string): Promise<Refs> {\n  let raw: string;\n  try {\n    raw = await readFile(refsPath, 'utf-8');\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      return {};\n    }\n    throw error;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    throw errorInvalidRefs(refsPath, 'Failed to parse as JSON');\n  }\n\n  const result = RefsSchema(parsed);\n  if (result instanceof type.errors) {\n    throw errorInvalidRefs(refsPath, result.summary);\n  }\n\n  return result;\n}\n\nexport async function writeRefs(refsPath: string, refs: Refs): Promise<void> {\n  for (const [key, value] of Object.entries(refs)) {\n    if (!validateRefName(key)) {\n      throw errorInvalidRefName(key);\n    }\n    if (!validateRefValue(value)) {\n      throw errorInvalidRefValue(value);\n    }\n  }\n\n  const sorted = Object.fromEntries(Object.entries(refs).sort(([a], [b]) => a.localeCompare(b)));\n\n  const dir = dirname(refsPath);\n  await mkdir(dir, { recursive: true });\n\n  const tmpPath = join(dir, `.refs.json.${Date.now()}.tmp`);\n  await writeFile(tmpPath, `${JSON.stringify(sorted, null, 2)}\\n`);\n  await rename(tmpPath, refsPath);\n}\n\nexport function resolveRef(refs: Refs, name: string): string {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  const hash = refs[name];\n  if (hash === undefined) {\n    throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n      why: `No ref named \"${name}\" exists in refs.json.`,\n      fix: `Available refs: ${Object.keys(refs).join(', ') || '(none)'}. Create a ref with: set the \"${name}\" key in migrations/refs.json.`,\n      details: { refName: name, availableRefs: Object.keys(refs) },\n    });\n  }\n\n  if (!validateRefValue(hash)) {\n    throw errorInvalidRefValue(hash);\n  }\n\n  return hash;\n}\n"],"mappings":";;;;;;AAYA,MAAM,mBAAmB;AACzB,MAAM,oBAAoB;AAE1B,SAAgB,gBAAgB,MAAuB;AACrD,KAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,KAAI,KAAK,SAAS,KAAK,CAAE,QAAO;AAChC,KAAI,KAAK,SAAS,KAAK,CAAE,QAAO;AAChC,KAAI,KAAK,WAAW,IAAI,CAAE,QAAO;AACjC,QAAO,iBAAiB,KAAK,KAAK;;AAGpC,SAAgB,iBAAiB,OAAwB;AACvD,QAAO,kBAAkB,KAAK,MAAM;;AAGtC,MAAM,aAAa,KAAK,yBAAyB,CAAC,QAAQ,MAAM,QAAQ;AACtE,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,EAAE;AAC/C,MAAI,CAAC,gBAAgB,IAAI,CAAE,QAAO,IAAI,OAAO,8BAA8B,IAAI,IAAI;AACnF,MAAI,CAAC,iBAAiB,MAAM,CAC1B,QAAO,IAAI,OAAO,6CAA6C,IAAI,MAAM,MAAM,IAAI;;AAEvF,QAAO;EACP;AAEF,eAAsB,SAAS,UAAiC;CAC9D,IAAIA;AACJ,KAAI;AACF,QAAM,MAAM,SAAS,UAAU,QAAQ;UAChC,OAAO;AACd,MAAI,iBAAiB,SAAU,MAA4B,SAAS,SAClE,QAAO,EAAE;AAEX,QAAM;;CAGR,IAAIC;AACJ,KAAI;AACF,WAAS,KAAK,MAAM,IAAI;SAClB;AACN,QAAM,iBAAiB,UAAU,0BAA0B;;CAG7D,MAAM,SAAS,WAAW,OAAO;AACjC,KAAI,kBAAkB,KAAK,OACzB,OAAM,iBAAiB,UAAU,OAAO,QAAQ;AAGlD,QAAO;;AAGT,eAAsB,UAAU,UAAkB,MAA2B;AAC3E,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,EAAE;AAC/C,MAAI,CAAC,gBAAgB,IAAI,CACvB,OAAM,oBAAoB,IAAI;AAEhC,MAAI,CAAC,iBAAiB,MAAM,CAC1B,OAAM,qBAAqB,MAAM;;CAIrC,MAAM,SAAS,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;CAE9F,MAAM,MAAM,QAAQ,SAAS;AAC7B,OAAM,MAAM,KAAK,EAAE,WAAW,MAAM,CAAC;CAErC,MAAM,UAAU,KAAK,KAAK,cAAc,KAAK,KAAK,CAAC,MAAM;AACzD,OAAM,UAAU,SAAS,GAAG,KAAK,UAAU,QAAQ,MAAM,EAAE,CAAC,IAAI;AAChE,OAAM,OAAO,SAAS,SAAS;;AAGjC,SAAgB,WAAW,MAAY,MAAsB;AAC3D,KAAI,CAAC,gBAAgB,KAAK,CACxB,OAAM,oBAAoB,KAAK;CAGjC,MAAM,OAAO,KAAK;AAClB,KAAI,SAAS,OACX,OAAM,IAAI,oBAAoB,yBAAyB,gBAAgB,KAAK,IAAI;EAC9E,KAAK,iBAAiB,KAAK;EAC3B,KAAK,mBAAmB,OAAO,KAAK,KAAK,CAAC,KAAK,KAAK,IAAI,SAAS,gCAAgC,KAAK;EACtG,SAAS;GAAE,SAAS;GAAM,eAAe,OAAO,KAAK,KAAK;GAAE;EAC7D,CAAC;AAGJ,KAAI,CAAC,iBAAiB,KAAK,CACzB,OAAM,qBAAqB,KAAK;AAGlC,QAAO"}
+{"version":3,"file":"refs.mjs","names":["raw: string","parsed: unknown","entries: string[]","refs: Record<string, RefEntry>"],"sources":["../../src/refs.ts"],"sourcesContent":["import { mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { dirname, join, relative } from 'pathe';\nimport {\n  errorInvalidRefFile,\n  errorInvalidRefName,\n  errorInvalidRefValue,\n  MigrationToolsError,\n} from './errors';\n\nexport interface RefEntry {\n  readonly hash: string;\n  readonly invariants: readonly string[];\n}\n\nexport type Refs = Readonly<Record<string, RefEntry>>;\n\nconst REF_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;\nconst REF_VALUE_PATTERN = /^sha256:(empty|[0-9a-f]{64})$/;\n\nexport function validateRefName(name: string): boolean {\n  if (name.length === 0) return false;\n  if (name.includes('..')) return false;\n  if (name.includes('//')) return false;\n  if (name.startsWith('.')) return false;\n  return REF_NAME_PATTERN.test(name);\n}\n\nexport function validateRefValue(value: string): boolean {\n  return REF_VALUE_PATTERN.test(value);\n}\n\nconst RefEntrySchema = type({\n  hash: 'string',\n  invariants: 'string[]',\n}).narrow((entry, ctx) => {\n  if (!validateRefValue(entry.hash))\n    return ctx.mustBe(`a valid contract hash (got \"${entry.hash}\")`);\n  return true;\n});\n\nfunction refFilePath(refsDir: string, name: string): string {\n  return join(refsDir, `${name}.json`);\n}\n\nfunction refNameFromPath(refsDir: string, filePath: string): string {\n  const rel = relative(refsDir, filePath);\n  return rel.replace(/\\.json$/, '');\n}\n\nexport async function readRef(refsDir: string, name: string): Promise<RefEntry> {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  const filePath = refFilePath(refsDir, name);\n  let raw: string;\n  try {\n    raw = await readFile(filePath, 'utf-8');\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n        why: `No ref file found at \"${filePath}\".`,\n        fix: `Create the ref with: prisma-next migration ref set ${name} <hash>`,\n        details: { refName: name, filePath },\n      });\n    }\n    throw error;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');\n  }\n\n  const result = RefEntrySchema(parsed);\n  if (result instanceof type.errors) {\n    throw errorInvalidRefFile(filePath, result.summary);\n  }\n\n  return result;\n}\n\nexport async function readRefs(refsDir: string): Promise<Refs> {\n  let entries: string[];\n  try {\n    entries = await readdir(refsDir, { recursive: true, encoding: 'utf-8' });\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      return {};\n    }\n    throw error;\n  }\n\n  const jsonFiles = entries.filter((entry) => entry.endsWith('.json'));\n  const refs: Record<string, RefEntry> = {};\n\n  for (const jsonFile of jsonFiles) {\n    const filePath = join(refsDir, jsonFile);\n    const name = refNameFromPath(refsDir, filePath);\n\n    let raw: string;\n    try {\n      raw = await readFile(filePath, 'utf-8');\n    } catch (error) {\n      // Tolerate the TOCTOU race between `readdir` and `readFile` (ENOENT) and\n      // benign EISDIR if a directory happens to end in `.json`. Anything else\n      // (EACCES, EIO, EMFILE, …) is a real failure and propagates so the CLI\n      // surfaces it rather than silently dropping the ref.\n      const code = error instanceof Error ? (error as { code?: string }).code : undefined;\n      if (code === 'ENOENT' || code === 'EISDIR') {\n        continue;\n      }\n      throw error;\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');\n    }\n\n    const result = RefEntrySchema(parsed);\n    if (result instanceof type.errors) {\n      throw errorInvalidRefFile(filePath, result.summary);\n    }\n\n    refs[name] = result;\n  }\n\n  return refs;\n}\n\nexport async function writeRef(refsDir: string, name: string, entry: RefEntry): Promise<void> {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n  if (!validateRefValue(entry.hash)) {\n    throw errorInvalidRefValue(entry.hash);\n  }\n\n  const filePath = refFilePath(refsDir, name);\n  const dir = dirname(filePath);\n  await mkdir(dir, { recursive: true });\n\n  const tmpPath = join(dir, `.${name.split('/').pop()}.json.${Date.now()}.tmp`);\n  await writeFile(\n    tmpPath,\n    `${JSON.stringify({ hash: entry.hash, invariants: [...entry.invariants] }, null, 2)}\\n`,\n  );\n  await rename(tmpPath, filePath);\n}\n\nexport async function deleteRef(refsDir: string, name: string): Promise<void> {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  const filePath = refFilePath(refsDir, name);\n  try {\n    await unlink(filePath);\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n        why: `No ref file found at \"${filePath}\".`,\n        fix: 'Run `prisma-next migration ref list` to see available refs.',\n        details: { refName: name, filePath },\n      });\n    }\n    throw error;\n  }\n\n  // Clean empty parent directories up to refsDir. Stop walking on the expected\n  // \"directory has siblings\" signal (ENOTEMPTY on Linux, EEXIST on some BSDs)\n  // and on ENOENT (concurrent removal). Anything else (EACCES, EIO, …) is a\n  // real failure and propagates.\n  let dir = dirname(filePath);\n  while (dir !== refsDir && dir.startsWith(refsDir)) {\n    try {\n      await rmdir(dir);\n      dir = dirname(dir);\n    } catch (error) {\n      const code = error instanceof Error ? (error as { code?: string }).code : undefined;\n      if (code === 'ENOTEMPTY' || code === 'EEXIST' || code === 'ENOENT') {\n        break;\n      }\n      throw error;\n    }\n  }\n}\n\nexport function resolveRef(refs: Refs, name: string): RefEntry {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  // Object.hasOwn gate: plain-object `refs` would otherwise let\n  // `refs['constructor']` return Object.prototype.constructor and bypass the\n  // UNKNOWN_REF throw. validateRefName accepts `\"constructor\"` as a name shape.\n  if (!Object.hasOwn(refs, name)) {\n    throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n      why: `No ref named \"${name}\" exists.`,\n      fix: `Available refs: ${Object.keys(refs).join(', ') || '(none)'}. Create a ref with: prisma-next migration ref set ${name} <hash>`,\n      details: { refName: name, availableRefs: Object.keys(refs) },\n    });\n  }\n\n  // biome-ignore lint/style/noNonNullAssertion: Object.hasOwn gate above guarantees this is defined\n  return refs[name]!;\n}\n"],"mappings":"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"}

package/dist/graph-BHPv-9Gl.d.mts

@@ -0,0 +1,28 @@
+//#region src/graph.d.ts
+/**
+ * An entry in the migration graph. All on-disk migrations are attested,
+ * so `migrationHash` is always a string.
+ */
+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[];
+}
+interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly migrationByHash: ReadonlyMap<string, MigrationEdge>;
+}
+//#endregion
+export { MigrationGraph as n, MigrationEdge as t };
+//# sourceMappingURL=graph-BHPv-9Gl.d.mts.map

package/dist/graph-BHPv-9Gl.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-BHPv-9Gl.d.mts","names":[],"sources":["../src/graph.ts"],"sourcesContent":[],"mappings":";;AAIA;AAeA;;AAEsD,UAjBrC,aAAA,CAiBqC;EAA7B,SAAA,IAAA,EAAA,MAAA;EAC6B,SAAA,EAAA,EAAA,MAAA;EAA7B,SAAA,aAAA,EAAA,MAAA;EACuB,SAAA,OAAA,EAAA,MAAA;EAApB,SAAA,SAAA,EAAA,MAAA;EAAW,SAAA,MAAA,EAAA,SAAA,MAAA,EAAA;;;;;;;;UAJtB,cAAA;kBACC;yBACO,6BAA6B;yBAC7B,6BAA6B;4BAC1B,oBAAoB"}

package/dist/hash-BARZdVgW.mjs

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+
+//#region src/canonicalize-json.ts
+function sortKeys(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(sortKeys);
+	const sorted = {};
+	for (const key of Object.keys(value).sort()) sorted[key] = sortKeys(value[key]);
+	return sorted;
+}
+function canonicalizeJson(value) {
+	return JSON.stringify(sortKeys(value));
+}
+
+//#endregion
+//#region src/hash.ts
+function sha256Hex(input) {
+	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).
+*/
+function computeMigrationHash(metadata, ops) {
+	const { migrationHash: _migrationHash, signature: _signature, fromContract: _fromContract, toContract: _toContract, hints: _hints, ...strippedMeta } = metadata;
+	return `sha256:${sha256Hex(canonicalizeJson([canonicalizeJson(strippedMeta), canonicalizeJson(ops)].map(sha256Hex)))}`;
+}
+/**
+* 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.
+*/
+function verifyMigrationHash(pkg) {
+	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
+	};
+}
+
+//#endregion
+export { verifyMigrationHash as n, computeMigrationHash as t };
+//# sourceMappingURL=hash-BARZdVgW.mjs.map

package/dist/hash-BARZdVgW.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-BARZdVgW.mjs","names":["sorted: Record<string, unknown>"],"sources":["../src/canonicalize-json.ts","../src/hash.ts"],"sourcesContent":["function sortKeys(value: unknown): unknown {\n  if (value === null || typeof value !== 'object') {\n    return value;\n  }\n  if (Array.isArray(value)) {\n    return value.map(sortKeys);\n  }\n  const sorted: Record<string, unknown> = {};\n  for (const key of Object.keys(value).sort()) {\n    sorted[key] = sortKeys((value as Record<string, unknown>)[key]);\n  }\n  return sorted;\n}\n\nexport function canonicalizeJson(value: unknown): string {\n  return JSON.stringify(sortKeys(value));\n}\n","import { createHash } from 'node:crypto';\nimport { canonicalizeJson } from './canonicalize-json';\nimport type { MigrationMetadata } from './metadata';\nimport type { MigrationOps, MigrationPackage } from './package';\n\nexport interface VerifyResult {\n  readonly ok: boolean;\n  readonly reason?: 'mismatch';\n  readonly storedHash: string;\n  readonly computedHash: string;\n}\n\nfunction sha256Hex(input: string): string {\n  return createHash('sha256').update(input).digest('hex');\n}\n\n/**\n * Content-addressed migration hash over (metadata envelope sans\n * contracts/hints/signature, ops). See ADR 199 — Storage-only migration\n * identity for the rationale: contracts are anchored separately by the\n * storage-hash bookends inside the envelope; planner hints are advisory\n * and must not affect identity.\n *\n * The integrity check is purely structural, not semantic. The function\n * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`\n * and hashes the result. Target-specific operation payloads (`step.sql`,\n * Mongo's pipeline AST, …) are hashed verbatim — no per-target\n * normalization is required, because what's being verified is \"do the\n * on-disk bytes still produce their recorded hash\", not \"do two\n * semantically-equivalent migrations hash the same\". The latter is an\n * emit-drift concern (ADR 192 step 2).\n *\n * The symmetry across write and read holds because `JSON.parse(\n * JSON.stringify(x))` round-trips JSON-safe values losslessly and\n * `sortKeys` is idempotent and deterministic — write-time and read-time\n * canonicalization produce the same canonical bytes regardless of\n * source-side key ordering or whitespace.\n *\n * The `migrationHash` field on the metadata is stripped before hashing\n * so the function can be used both at write time (when no hash exists\n * yet) and at verify time (rehashing an already-attested record).\n */\nexport function computeMigrationHash(\n  metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },\n  ops: MigrationOps,\n): string {\n  const {\n    migrationHash: _migrationHash,\n    signature: _signature,\n    fromContract: _fromContract,\n    toContract: _toContract,\n    hints: _hints,\n    ...strippedMeta\n  } = metadata;\n\n  const canonicalMetadata = canonicalizeJson(strippedMeta);\n  const canonicalOps = canonicalizeJson(ops);\n\n  const partHashes = [canonicalMetadata, canonicalOps].map(sha256Hex);\n  const hash = sha256Hex(canonicalizeJson(partHashes));\n\n  return `sha256:${hash}`;\n}\n\n/**\n * Re-hash an in-memory migration package and compare against the stored\n * `migrationHash`. See `computeMigrationHash` for the canonicalization rules.\n *\n * Returns `{ ok: true }` when the package is internally consistent, or\n * `{ ok: false, reason: 'mismatch', storedHash, computedHash }` when it is\n * not — typically a sign of FS corruption, partial writes, or a post-emit\n * hand edit.\n */\nexport function verifyMigrationHash(pkg: MigrationPackage): VerifyResult {\n  const computed = computeMigrationHash(pkg.metadata, pkg.ops);\n\n  if (pkg.metadata.migrationHash === computed) {\n    return {\n      ok: true,\n      storedHash: pkg.metadata.migrationHash,\n      computedHash: computed,\n    };\n  }\n\n  return {\n    ok: false,\n    reason: 'mismatch',\n    storedHash: pkg.metadata.migrationHash,\n    computedHash: computed,\n  };\n}\n"],"mappings":";;;AAAA,SAAS,SAAS,OAAyB;AACzC,KAAI,UAAU,QAAQ,OAAO,UAAU,SACrC,QAAO;AAET,KAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,IAAI,SAAS;CAE5B,MAAMA,SAAkC,EAAE;AAC1C,MAAK,MAAM,OAAO,OAAO,KAAK,MAAM,CAAC,MAAM,CACzC,QAAO,OAAO,SAAU,MAAkC,KAAK;AAEjE,QAAO;;AAGT,SAAgB,iBAAiB,OAAwB;AACvD,QAAO,KAAK,UAAU,SAAS,MAAM,CAAC;;;;;ACHxC,SAAS,UAAU,OAAuB;AACxC,QAAO,WAAW,SAAS,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BzD,SAAgB,qBACd,UACA,KACQ;CACR,MAAM,EACJ,eAAe,gBACf,WAAW,YACX,cAAc,eACd,YAAY,aACZ,OAAO,QACP,GAAG,iBACD;AAQJ,QAAO,UAFM,UAAU,iBADJ,CAHO,iBAAiB,aAAa,EACnC,iBAAiB,IAAI,CAEU,CAAC,IAAI,UAAU,CAChB,CAAC;;;;;;;;;;;AActD,SAAgB,oBAAoB,KAAqC;CACvE,MAAM,WAAW,qBAAqB,IAAI,UAAU,IAAI,IAAI;AAE5D,KAAI,IAAI,SAAS,kBAAkB,SACjC,QAAO;EACL,IAAI;EACJ,YAAY,IAAI,SAAS;EACzB,cAAc;EACf;AAGH,QAAO;EACL,IAAI;EACJ,QAAQ;EACR,YAAY,IAAI,SAAS;EACzB,cAAc;EACf"}

package/dist/invariants-BmrTBQ0A.mjs

@@ -0,0 +1,42 @@
+import { i as errorDuplicateInvariantInEdge, s as errorInvalidInvariantId } from "./errors-Bl3cKiM8.mjs";
+
+//#region src/invariants.ts
+/**
+* Hygiene check for `invariantId`. Rejects empty values plus any
+* whitespace or control character (including Unicode whitespace like
+* NBSP and em space, which are visually identical to ASCII space and
+* routinely sneak in via paste).
+*/
+function validateInvariantId(invariantId) {
+	if (invariantId.length === 0) return false;
+	return !/[\p{Cc}\p{White_Space}]/u.test(invariantId);
+}
+/**
+* Walk a migration's operations and produce its `providedInvariants`
+* aggregate: the sorted, deduplicated list of `invariantId`s declared
+* by data-transform ops. Ops without `operationClass === 'data'` are
+* skipped; data ops without an `invariantId` are skipped.
+*
+* Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+* `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+*/
+function deriveProvidedInvariants(ops) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const op of ops) {
+		const invariantId = readInvariantId(op);
+		if (invariantId === void 0) continue;
+		if (!validateInvariantId(invariantId)) throw errorInvalidInvariantId(invariantId);
+		if (seen.has(invariantId)) throw errorDuplicateInvariantInEdge(invariantId);
+		seen.add(invariantId);
+	}
+	return [...seen].sort();
+}
+function readInvariantId(op) {
+	if (op.operationClass !== "data") return void 0;
+	const candidate = op.invariantId;
+	return typeof candidate === "string" ? candidate : void 0;
+}
+
+//#endregion
+export { validateInvariantId as n, deriveProvidedInvariants as t };
+//# sourceMappingURL=invariants-BmrTBQ0A.mjs.map

package/dist/invariants-BmrTBQ0A.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants-BmrTBQ0A.mjs","names":[],"sources":["../src/invariants.ts"],"sourcesContent":["import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';\nimport { errorDuplicateInvariantInEdge, errorInvalidInvariantId } from './errors';\nimport type { MigrationOps } from './package';\n\n/**\n * Hygiene check for `invariantId`. Rejects empty values plus any\n * whitespace or control character (including Unicode whitespace like\n * NBSP and em space, which are visually identical to ASCII space and\n * routinely sneak in via paste).\n */\nexport function validateInvariantId(invariantId: string): boolean {\n  if (invariantId.length === 0) return false;\n  return !/[\\p{Cc}\\p{White_Space}]/u.test(invariantId);\n}\n\n/**\n * Walk a migration's operations and produce its `providedInvariants`\n * aggregate: the sorted, deduplicated list of `invariantId`s declared\n * by data-transform ops. Ops without `operationClass === 'data'` are\n * skipped; data ops without an `invariantId` are skipped.\n *\n * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and\n * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.\n */\nexport function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {\n  const seen = new Set<string>();\n  for (const op of ops) {\n    const invariantId = readInvariantId(op);\n    if (invariantId === undefined) continue;\n    if (!validateInvariantId(invariantId)) {\n      throw errorInvalidInvariantId(invariantId);\n    }\n    if (seen.has(invariantId)) {\n      throw errorDuplicateInvariantInEdge(invariantId);\n    }\n    seen.add(invariantId);\n  }\n  return [...seen].sort();\n}\n\nfunction readInvariantId(op: MigrationPlanOperation): string | undefined {\n  if (op.operationClass !== 'data') return undefined;\n  const candidate = (op as { invariantId?: unknown }).invariantId;\n  return typeof candidate === 'string' ? candidate : undefined;\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,oBAAoB,aAA8B;AAChE,KAAI,YAAY,WAAW,EAAG,QAAO;AACrC,QAAO,CAAC,2BAA2B,KAAK,YAAY;;;;;;;;;;;AAYtD,SAAgB,yBAAyB,KAAsC;CAC7E,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,MAAM,KAAK;EACpB,MAAM,cAAc,gBAAgB,GAAG;AACvC,MAAI,gBAAgB,OAAW;AAC/B,MAAI,CAAC,oBAAoB,YAAY,CACnC,OAAM,wBAAwB,YAAY;AAE5C,MAAI,KAAK,IAAI,YAAY,CACvB,OAAM,8BAA8B,YAAY;AAElD,OAAK,IAAI,YAAY;;AAEvB,QAAO,CAAC,GAAG,KAAK,CAAC,MAAM;;AAGzB,SAAS,gBAAgB,IAAgD;AACvE,KAAI,GAAG,mBAAmB,OAAQ,QAAO;CACzC,MAAM,YAAa,GAAiC;AACpD,QAAO,OAAO,cAAc,WAAW,YAAY"}

package/dist/metadata-BP1cmU7Z.d.mts

@@ -0,0 +1,50 @@
+import { Contract } from "@prisma-next/contract/types";
+
+//#region src/metadata.d.ts
+interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+}
+/**
+ * In-memory migration metadata envelope. Every migration is content-addressed:
+ * the `migrationHash` is a hash over the metadata envelope plus the operations
+ * list, computed at write time. There is no draft state — a migration
+ * directory either exists with fully attested metadata or it does not.
+ *
+ * When the planner cannot lower an operation because of an unfilled
+ * `placeholder(...)` slot, the migration is still written with `migrationHash`
+ * hashed over `ops: []`. Re-running self-emit after the user fills the
+ * placeholder produces a *different* `migrationHash` (committed to the real
+ * ops); this is intentional.
+ *
+ * The on-disk JSON shape in `migration.json` matches this type field-for-field
+ * — `JSON.stringify(metadata, null, 2)` is the canonical writer output.
+ */
+interface MigrationMetadata {
+  readonly migrationHash: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly fromContract: Contract | null;
+  readonly toContract: Contract;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
+  readonly authorship?: {
+    readonly author?: string;
+    readonly email?: string;
+  };
+  readonly signature?: {
+    readonly keyId: string;
+    readonly value: string;
+  } | null;
+  readonly createdAt: string;
+}
+//#endregion
+export { MigrationMetadata as n, MigrationHints as t };
+//# sourceMappingURL=metadata-BP1cmU7Z.d.mts.map

package/dist/metadata-BP1cmU7Z.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-BP1cmU7Z.d.mts","names":[],"sources":["../src/metadata.ts"],"sourcesContent":[],"mappings":";;;UAEiB,cAAA;;EAAA,SAAA,OAAA,EAAc,SAAA,MAAA,EAAA;EAqBd,SAAA,cAAiB,EAAA,MAAA;;;;;;;;;;;;;;;;;UAAjB,iBAAA;;;;yBAIQ;uBACF;kBACL"}

package/dist/op-schema-DZKFua46.mjs

@@ -0,0 +1,14 @@
+import { type } from "arktype";
+
+//#region src/op-schema.ts
+const MigrationOpSchema = type({
+	id: "string",
+	label: "string",
+	operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
+	"invariantId?": "string"
+});
+const MigrationOpsSchema = MigrationOpSchema.array();
+
+//#endregion
+export { MigrationOpsSchema as n, MigrationOpSchema as t };
+//# sourceMappingURL=op-schema-DZKFua46.mjs.map

package/dist/op-schema-DZKFua46.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-schema-DZKFua46.mjs","names":[],"sources":["../src/op-schema.ts"],"sourcesContent":["import { type } from 'arktype';\n\nexport const MigrationOpSchema = type({\n  id: 'string',\n  label: 'string',\n  operationClass: \"'additive' | 'widening' | 'destructive' | 'data'\",\n  'invariantId?': 'string',\n});\n\n// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.\nexport const MigrationOpsSchema = MigrationOpSchema.array();\n"],"mappings":";;;AAEA,MAAa,oBAAoB,KAAK;CACpC,IAAI;CACJ,OAAO;CACP,gBAAgB;CAChB,gBAAgB;CACjB,CAAC;AAGF,MAAa,qBAAqB,kBAAkB,OAAO"}

package/dist/package-5HCCg0z-.d.mts

@@ -0,0 +1,21 @@
+import { n as MigrationMetadata } from "./metadata-BP1cmU7Z.mjs";
+import { MigrationPlanOperation } from "@prisma-next/framework-components/control";
+
+//#region src/package.d.ts
+type MigrationOps = readonly MigrationPlanOperation[];
+/**
+ * An on-disk migration directory (a "package") with its parsed metadata and
+ * operations. Returned from `readMigrationPackage` / `readMigrationsDir` only
+ * after the loader has verified the package's integrity (hash recomputation
+ * against the stored `migrationHash`); holding a `MigrationPackage` value
+ * therefore implies the package is internally consistent.
+ */
+interface MigrationPackage {
+  readonly dirName: string;
+  readonly dirPath: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: MigrationOps;
+}
+//#endregion
+export { MigrationPackage as n, MigrationOps as t };
+//# sourceMappingURL=package-5HCCg0z-.d.mts.map

package/dist/package-5HCCg0z-.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-5HCCg0z-.d.mts","names":[],"sources":["../src/package.ts"],"sourcesContent":[],"mappings":";;;;KAGY,YAAA,YAAwB;;AAApC;AASA;;;;;UAAiB,gBAAA;;;qBAGI;gBACL"}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.5.0-dev.3",
+  "version": "0.5.0-dev.30",
   "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.3",
-    "@prisma-next/framework-components": "0.5.0-dev.3",
-    "@prisma-next/utils": "0.5.0-dev.3"
+    "@prisma-next/framework-components": "0.5.0-dev.30",
+    "@prisma-next/utils": "0.5.0-dev.30",
+    "@prisma-next/contract": "0.5.0-dev.30"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
@@ -27,21 +27,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,29 @@
+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 +74,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 +85,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 +147,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',
     {
       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.',
+      fix: reemitHint(
+        dir,
+        'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+      ),
       details: { dirName, hash },
     },
   );
@@ -175,14 +234,79 @@ 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 } },
+    },
+  );
+}
+
+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 @@
+export { errorInvalidJson, MigrationToolsError } 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';