@prisma-next/migration-tools 0.0.1

package/dist/io-Dx98-h0p.mjs

@@ -0,0 +1,131 @@
+import { a as errorInvalidJson, c as errorMissingFile, o as errorInvalidManifest, r as errorDirectoryExists, s as errorInvalidSlug } from "./errors-DdSjGRqx.mjs";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { type } from "arktype";
+import { basename, dirname, join } from "pathe";
+
+//#region src/io.ts
+const MANIFEST_FILE = "migration.json";
+const OPS_FILE = "ops.json";
+const MAX_SLUG_LENGTH = 64;
+function hasErrnoCode(error, code) {
+	return error instanceof Error && error.code === code;
+}
+const MigrationManifestSchema = type({
+	from: "string",
+	to: "string",
+	migrationId: "string | null",
+	parentMigrationId: "string | null",
+	kind: "'regular' | 'baseline'",
+	fromContract: "object | null",
+	toContract: "object",
+	hints: type({
+		used: "string[]",
+		applied: "string[]",
+		plannerVersion: "string",
+		planningStrategy: "string"
+	}),
+	labels: "string[]",
+	"authorship?": type({
+		"author?": "string",
+		"email?": "string"
+	}),
+	"signature?": type({
+		keyId: "string",
+		value: "string"
+	}).or("null"),
+	createdAt: "string"
+});
+const MigrationOpsSchema = type({
+	id: "string",
+	label: "string",
+	operationClass: "'additive' | 'widening' | 'destructive'"
+}).array();
+async function writeMigrationPackage(dir, manifest, ops) {
+	await mkdir(dirname(dir), { recursive: true });
+	try {
+		await mkdir(dir);
+	} catch (error) {
+		if (hasErrnoCode(error, "EEXIST")) throw errorDirectoryExists(dir);
+		throw error;
+	}
+	await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: "wx" });
+	await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: "wx" });
+}
+async function readMigrationPackage(dir) {
+	const manifestPath = join(dir, MANIFEST_FILE);
+	const opsPath = join(dir, OPS_FILE);
+	let manifestRaw;
+	try {
+		manifestRaw = await readFile(manifestPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(MANIFEST_FILE, dir);
+		throw error;
+	}
+	let opsRaw;
+	try {
+		opsRaw = await readFile(opsPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(OPS_FILE, dir);
+		throw error;
+	}
+	let manifest;
+	try {
+		manifest = JSON.parse(manifestRaw);
+	} catch (e) {
+		throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
+	}
+	let ops;
+	try {
+		ops = JSON.parse(opsRaw);
+	} catch (e) {
+		throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
+	}
+	validateManifest(manifest, manifestPath);
+	validateOps(ops, opsPath);
+	return {
+		dirName: basename(dir),
+		dirPath: dir,
+		manifest,
+		ops
+	};
+}
+function validateManifest(manifest, filePath) {
+	const result = MigrationManifestSchema(manifest);
+	if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
+}
+function validateOps(ops, filePath) {
+	const result = MigrationOpsSchema(ops);
+	if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
+}
+async function readMigrationsDir(migrationsRoot) {
+	let entries;
+	try {
+		entries = await readdir(migrationsRoot);
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) return [];
+		throw error;
+	}
+	const packages = [];
+	for (const entry of entries.sort()) {
+		const entryPath = join(migrationsRoot, entry);
+		if (!(await stat(entryPath)).isDirectory()) continue;
+		const manifestPath = join(entryPath, MANIFEST_FILE);
+		try {
+			await stat(manifestPath);
+		} catch {
+			continue;
+		}
+		packages.push(await readMigrationPackage(entryPath));
+	}
+	return packages;
+}
+function formatMigrationDirName(timestamp, slug) {
+	const sanitized = slug.toLowerCase().replace(/[^a-z0-9]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+	if (sanitized.length === 0) throw errorInvalidSlug(slug);
+	const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);
+	return `${timestamp.getUTCFullYear()}${String(timestamp.getUTCMonth() + 1).padStart(2, "0")}${String(timestamp.getUTCDate()).padStart(2, "0")}T${String(timestamp.getUTCHours()).padStart(2, "0")}${String(timestamp.getUTCMinutes()).padStart(2, "0")}_${truncated}`;
+}
+
+//#endregion
+export { writeMigrationPackage as i, readMigrationPackage as n, readMigrationsDir as r, formatMigrationDirName as t };
+//# sourceMappingURL=io-Dx98-h0p.mjs.map

package/dist/io-Dx98-h0p.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-Dx98-h0p.mjs","names":["manifestRaw: string","opsRaw: string","manifest: MigrationManifest","ops: MigrationOps","entries: string[]","packages: MigrationPackage[]"],"sources":["../src/io.ts"],"sourcesContent":["import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { basename, dirname, join } from 'pathe';\nimport {\n  errorDirectoryExists,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMissingFile,\n} from './errors';\nimport type { MigrationManifest, MigrationOps, MigrationPackage } from './types';\n\nconst MANIFEST_FILE = 'migration.json';\nconst OPS_FILE = 'ops.json';\nconst MAX_SLUG_LENGTH = 64;\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error && (error as { code?: string }).code === code;\n}\n\nconst MigrationHintsSchema = type({\n  used: 'string[]',\n  applied: 'string[]',\n  plannerVersion: 'string',\n  planningStrategy: 'string',\n});\n\nconst MigrationManifestSchema = type({\n  from: 'string',\n  to: 'string',\n  migrationId: 'string | null',\n  parentMigrationId: 'string | null',\n  kind: \"'regular' | 'baseline'\",\n  fromContract: 'object | null',\n  toContract: 'object',\n  hints: MigrationHintsSchema,\n  labels: 'string[]',\n  'authorship?': type({\n    'author?': 'string',\n    'email?': 'string',\n  }),\n  'signature?': type({\n    keyId: 'string',\n    value: 'string',\n  }).or('null'),\n  createdAt: 'string',\n});\n\nconst MigrationOpSchema = type({\n  id: 'string',\n  label: 'string',\n  operationClass: \"'additive' | 'widening' | 'destructive'\",\n});\n\n// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.\nconst MigrationOpsSchema = MigrationOpSchema.array();\n\nexport async function writeMigrationPackage(\n  dir: string,\n  manifest: MigrationManifest,\n  ops: MigrationOps,\n): Promise<void> {\n  await mkdir(dirname(dir), { recursive: true });\n\n  try {\n    await mkdir(dir);\n  } catch (error) {\n    if (hasErrnoCode(error, 'EEXIST')) {\n      throw errorDirectoryExists(dir);\n    }\n    throw error;\n  }\n\n  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: 'wx' });\n  await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });\n}\n\nexport async function readMigrationPackage(dir: string): Promise<MigrationPackage> {\n  const manifestPath = join(dir, MANIFEST_FILE);\n  const opsPath = join(dir, OPS_FILE);\n\n  let manifestRaw: string;\n  try {\n    manifestRaw = await readFile(manifestPath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile(MANIFEST_FILE, dir);\n    }\n    throw error;\n  }\n\n  let opsRaw: string;\n  try {\n    opsRaw = await readFile(opsPath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile(OPS_FILE, dir);\n    }\n    throw error;\n  }\n\n  let manifest: MigrationManifest;\n  try {\n    manifest = JSON.parse(manifestRaw);\n  } catch (e) {\n    throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));\n  }\n\n  let ops: MigrationOps;\n  try {\n    ops = JSON.parse(opsRaw);\n  } catch (e) {\n    throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));\n  }\n\n  validateManifest(manifest, manifestPath);\n  validateOps(ops, opsPath);\n\n  return {\n    dirName: basename(dir),\n    dirPath: dir,\n    manifest,\n    ops,\n  };\n}\n\nfunction validateManifest(\n  manifest: unknown,\n  filePath: string,\n): asserts manifest is MigrationManifest {\n  const result = MigrationManifestSchema(manifest);\n  if (result instanceof type.errors) {\n    throw errorInvalidManifest(filePath, result.summary);\n  }\n}\n\nfunction validateOps(ops: unknown, filePath: string): asserts ops is MigrationOps {\n  const result = MigrationOpsSchema(ops);\n  if (result instanceof type.errors) {\n    throw errorInvalidManifest(filePath, result.summary);\n  }\n}\n\nexport async function readMigrationsDir(\n  migrationsRoot: string,\n): Promise<readonly MigrationPackage[]> {\n  let entries: string[];\n  try {\n    entries = await readdir(migrationsRoot);\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      return [];\n    }\n    throw error;\n  }\n\n  const packages: MigrationPackage[] = [];\n\n  for (const entry of entries.sort()) {\n    const entryPath = join(migrationsRoot, entry);\n    const entryStat = await stat(entryPath);\n    if (!entryStat.isDirectory()) continue;\n\n    const manifestPath = join(entryPath, MANIFEST_FILE);\n    try {\n      await stat(manifestPath);\n    } catch {\n      continue; // skip non-migration directories\n    }\n\n    packages.push(await readMigrationPackage(entryPath));\n  }\n\n  return packages;\n}\n\nexport function formatMigrationDirName(timestamp: Date, slug: string): string {\n  const sanitized = slug\n    .toLowerCase()\n    .replace(/[^a-z0-9]/g, '_')\n    .replace(/_+/g, '_')\n    .replace(/^_|_$/g, '');\n\n  if (sanitized.length === 0) {\n    throw errorInvalidSlug(slug);\n  }\n\n  const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);\n\n  const y = timestamp.getUTCFullYear();\n  const mo = String(timestamp.getUTCMonth() + 1).padStart(2, '0');\n  const d = String(timestamp.getUTCDate()).padStart(2, '0');\n  const h = String(timestamp.getUTCHours()).padStart(2, '0');\n  const mi = String(timestamp.getUTCMinutes()).padStart(2, '0');\n\n  return `${y}${mo}${d}T${h}${mi}_${truncated}`;\n}\n"],"mappings":"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"}

package/dist/types-CUnzoaLY.d.mts

@@ -0,0 +1,56 @@
+import { ContractIR } from "@prisma-next/contract/ir";
+import { MigrationPlanOperation } from "@prisma-next/core-control-plane/types";
+
+//#region src/types.d.ts
+interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+  readonly planningStrategy: string;
+}
+interface MigrationManifest {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationId: string | null;
+  readonly parentMigrationId: string | null;
+  readonly kind: 'regular' | 'baseline';
+  readonly fromContract: ContractIR | null;
+  readonly toContract: ContractIR;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  readonly authorship?: {
+    readonly author?: string;
+    readonly email?: string;
+  };
+  readonly signature?: {
+    readonly keyId: string;
+    readonly value: string;
+  } | null;
+  readonly createdAt: string;
+}
+type MigrationOps = readonly MigrationPlanOperation[];
+interface MigrationPackage {
+  readonly dirName: string;
+  readonly dirPath: string;
+  readonly manifest: MigrationManifest;
+  readonly ops: MigrationOps;
+}
+interface MigrationChainEntry {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationId: string | null;
+  readonly parentMigrationId: string | null;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+}
+interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly migrationById: ReadonlyMap<string, MigrationChainEntry>;
+  readonly childrenByParentId: ReadonlyMap<string | null, readonly MigrationChainEntry[]>;
+}
+//#endregion
+export { MigrationOps as a, MigrationManifest as i, MigrationGraph as n, MigrationPackage as o, MigrationHints as r, MigrationChainEntry as t };
+//# sourceMappingURL=types-CUnzoaLY.d.mts.map

package/dist/types-CUnzoaLY.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CUnzoaLY.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,cAAA;;EAAA,SAAA,OAAA,EAAc,SAAA,MAAA,EAAA;EAOd,SAAA,cAAiB,EAAA,MAAA;EAMT,SAAA,gBAAA,EAAA,MAAA;;AAEP,UARD,iBAAA,CAQC;EAAc,SAAA,IAAA,EAAA,MAAA;EAOpB,SAAA,EAAA,EAAA,MAAY;EAEP,SAAA,WAAgB,EAAA,MAAA,GAGZ,IAAA;EAIJ,SAAA,iBAAmB,EAAA,MAAA,GAAA,IAAA;EAUnB,SAAA,IAAA,EAAA,SAAc,GAAA,UAAA;EACb,SAAA,YAAA,EA7BO,UA6BP,GAAA,IAAA;EACoC,SAAA,UAAA,EA7B/B,UA6B+B;EAA7B,SAAA,KAAA,EA5BP,cA4BO;EAC6B,SAAA,MAAA,EAAA,SAAA,MAAA,EAAA;EAA7B,SAAA,UAAA,CAAA,EAAA;IACqB,SAAA,MAAA,CAAA,EAAA,MAAA;IAApB,SAAA,KAAA,CAAA,EAAA,MAAA;EACyC,CAAA;EAApC,SAAA,SAAA,CAAA,EAAA;IAAW,SAAA,KAAA,EAAA,MAAA;;;;;KAxB9B,YAAA,YAAwB;UAEnB,gBAAA;;;qBAGI;gBACL;;UAGC,mBAAA;;;;;;;;;UAUA,cAAA;kBACC;yBACO,6BAA6B;yBAC7B,6BAA6B;0BAC5B,oBAAoB;+BACf,oCAAoC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@prisma-next/migration-tools",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "On-disk migration persistence, attestation, and chain reconstruction for Prisma Next",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/core-control-plane": "workspace:*",
+    "@prisma-next/utils": "workspace:*",
+    "arktype": "catalog:",
+    "pathe": "^2.0.3"
+  },
+  "devDependencies": {
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./types": {
+      "types": "./dist/exports/types.d.mts",
+      "import": "./dist/exports/types.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"
+    },
+    "./dag": {
+      "types": "./dist/exports/dag.d.mts",
+      "import": "./dist/exports/dag.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/3-tooling/migration"
+  }
+}

package/src/attestation.ts

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import { canonicalizeContract } from '@prisma-next/core-control-plane/emission';
+import { join } from 'pathe';
+import { canonicalizeJson } from './canonicalize-json';
+import { readMigrationPackage } from './io';
+import type { MigrationManifest, MigrationOps } from './types';
+
+export interface VerifyResult {
+  readonly ok: boolean;
+  readonly reason?: 'draft' | 'mismatch';
+  readonly storedMigrationId?: string;
+  readonly computedMigrationId?: string;
+}
+
+function sha256Hex(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+export function computeMigrationId(manifest: MigrationManifest, ops: MigrationOps): string {
+  const {
+    migrationId: _migrationId,
+    signature: _signature,
+    fromContract: _fromContract,
+    toContract: _toContract,
+    ...strippedMeta
+  } = manifest;
+
+  const canonicalManifest = canonicalizeJson(strippedMeta);
+  const canonicalOps = canonicalizeJson(ops);
+
+  const canonicalFromContract =
+    manifest.fromContract !== null ? canonicalizeContract(manifest.fromContract) : 'null';
+  const canonicalToContract = canonicalizeContract(manifest.toContract);
+
+  const partHashes = [
+    canonicalManifest,
+    canonicalOps,
+    canonicalFromContract,
+    canonicalToContract,
+  ].map(sha256Hex);
+  const hash = sha256Hex(canonicalizeJson(partHashes));
+
+  return `sha256:${hash}`;
+}
+
+export async function attestMigration(dir: string): Promise<string> {
+  const pkg = await readMigrationPackage(dir);
+  const migrationId = computeMigrationId(pkg.manifest, pkg.ops);
+
+  const updated = { ...pkg.manifest, migrationId };
+  await writeFile(join(dir, 'migration.json'), JSON.stringify(updated, null, 2));
+
+  return migrationId;
+}
+
+export async function verifyMigration(dir: string): Promise<VerifyResult> {
+  const pkg = await readMigrationPackage(dir);
+
+  if (pkg.manifest.migrationId === null) {
+    return { ok: false, reason: 'draft' };
+  }
+
+  const computed = computeMigrationId(pkg.manifest, pkg.ops);
+
+  if (pkg.manifest.migrationId === computed) {
+    return { ok: true, storedMigrationId: pkg.manifest.migrationId, computedMigrationId: computed };
+  }
+
+  return {
+    ok: false,
+    reason: 'mismatch',
+    storedMigrationId: pkg.manifest.migrationId,
+    computedMigrationId: computed,
+  };
+}

package/src/canonicalize-json.ts

@@ -0,0 +1,17 @@
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = sortKeys((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+export function canonicalizeJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}

package/src/dag.ts

@@ -0,0 +1,280 @@
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/core-control-plane/constants';
+import {
+  errorAmbiguousLeaf,
+  errorDuplicateMigrationId,
+  errorNoRoot,
+  errorSelfLoop,
+} from './errors';
+import type { MigrationChainEntry, MigrationGraph, MigrationPackage } from './types';
+
+export function reconstructGraph(packages: readonly MigrationPackage[]): MigrationGraph {
+  const nodes = new Set<string>();
+  const forwardChain = new Map<string, MigrationChainEntry[]>();
+  const reverseChain = new Map<string, MigrationChainEntry[]>();
+  const migrationById = new Map<string, MigrationChainEntry>();
+  const childrenByParentId = new Map<string | null, MigrationChainEntry[]>();
+
+  for (const pkg of packages) {
+    const { from, to } = pkg.manifest;
+
+    if (from === to) {
+      throw errorSelfLoop(pkg.dirName, from);
+    }
+
+    nodes.add(from);
+    nodes.add(to);
+
+    const migration: MigrationChainEntry = {
+      from,
+      to,
+      migrationId: pkg.manifest.migrationId,
+      parentMigrationId: pkg.manifest.parentMigrationId,
+      dirName: pkg.dirName,
+      createdAt: pkg.manifest.createdAt,
+      labels: pkg.manifest.labels,
+    };
+
+    if (migration.migrationId !== null) {
+      if (migrationById.has(migration.migrationId)) {
+        throw errorDuplicateMigrationId(migration.migrationId);
+      }
+      migrationById.set(migration.migrationId, migration);
+    }
+
+    const parentId = migration.parentMigrationId;
+    const siblings = childrenByParentId.get(parentId);
+    if (siblings) {
+      siblings.push(migration);
+    } else {
+      childrenByParentId.set(parentId, [migration]);
+    }
+
+    const fwd = forwardChain.get(from);
+    if (fwd) {
+      fwd.push(migration);
+    } else {
+      forwardChain.set(from, [migration]);
+    }
+
+    const rev = reverseChain.get(to);
+    if (rev) {
+      rev.push(migration);
+    } else {
+      reverseChain.set(to, [migration]);
+    }
+  }
+
+  return { nodes, forwardChain, reverseChain, migrationById, childrenByParentId };
+}
+
+/**
+ * Walk the parent-migration chain to find the latest migration.
+ * Returns the migration with no children, or null for an empty graph.
+ * Throws AMBIGUOUS_LEAF if the chain branches.
+ */
+export function findLatestMigration(graph: MigrationGraph): MigrationChainEntry | null {
+  if (graph.nodes.size === 0) {
+    return null;
+  }
+
+  const roots = graph.childrenByParentId.get(null);
+  if (!roots || roots.length === 0) {
+    throw errorNoRoot([...graph.nodes].sort());
+  }
+
+  if (roots.length > 1) {
+    throw errorAmbiguousLeaf(roots.map((e) => e.to));
+  }
+
+  let current = roots[0];
+  if (!current) {
+    throw errorNoRoot([...graph.nodes].sort());
+  }
+
+  for (let depth = 0; depth < graph.migrationById.size + 1 && current; depth++) {
+    const children: readonly MigrationChainEntry[] | undefined =
+      current.migrationId !== null ? graph.childrenByParentId.get(current.migrationId) : undefined;
+
+    if (!children || children.length === 0) {
+      return current;
+    }
+
+    if (children.length > 1) {
+      throw errorAmbiguousLeaf(children.map((e) => e.to));
+    }
+
+    current = children[0];
+  }
+
+  throw errorNoRoot([...graph.nodes].sort());
+}
+
+/**
+ * Find the leaf contract hash of the migration chain.
+ * Convenience wrapper around findLatestMigration.
+ */
+export function findLeaf(graph: MigrationGraph): string {
+  const migration = findLatestMigration(graph);
+  return migration ? migration.to : EMPTY_CONTRACT_HASH;
+}
+
+/**
+ * Find the ordered chain of migrations from `fromHash` to `toHash` by walking the
+ * parent-migration chain. Returns the sub-sequence of migrations whose cumulative path
+ * goes from `fromHash` to `toHash`.
+ *
+ * This reconstructs the full chain from root to leaf via parent pointers, then
+ * extracts the segment between the two hashes. This correctly handles revisited
+ * contract hashes (e.g. A→B→A) because it operates on migrations, not nodes.
+ */
+export function findPath(
+  graph: MigrationGraph,
+  fromHash: string,
+  toHash: string,
+): readonly MigrationChainEntry[] | null {
+  if (fromHash === toHash) return [];
+
+  const chain = buildChain(graph);
+  if (!chain) return null;
+
+  let startIdx = -1;
+  if (chain.length > 0 && chain[0]?.from === fromHash) {
+    startIdx = 0;
+  } else {
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (chain[i]?.to === fromHash) {
+        startIdx = i + 1;
+        break;
+      }
+    }
+  }
+
+  if (startIdx === -1) return null;
+
+  let endIdx = -1;
+  for (let i = chain.length - 1; i >= startIdx; i--) {
+    if (chain[i]?.to === toHash) {
+      endIdx = i + 1;
+      break;
+    }
+  }
+
+  if (endIdx === -1) return null;
+
+  return chain.slice(startIdx, endIdx);
+}
+
+/**
+ * Build the full ordered chain of migrations from root to leaf by following
+ * parent pointers. Returns null if the chain cannot be reconstructed
+ * (e.g. missing root, branches).
+ */
+function buildChain(graph: MigrationGraph): readonly MigrationChainEntry[] | null {
+  const roots = graph.childrenByParentId.get(null);
+  if (!roots || roots.length !== 1) return null;
+
+  const chain: MigrationChainEntry[] = [];
+  let current: MigrationChainEntry | undefined = roots[0];
+
+  for (let depth = 0; depth < graph.migrationById.size + 1 && current; depth++) {
+    chain.push(current);
+    const children =
+      current.migrationId !== null ? graph.childrenByParentId.get(current.migrationId) : undefined;
+    if (!children || children.length === 0) break;
+    if (children.length > 1) return null;
+    current = children[0];
+  }
+
+  return chain;
+}
+
+export function detectCycles(graph: MigrationGraph): readonly string[][] {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+
+  const color = new Map<string, number>();
+  const parent = new Map<string, string | null>();
+  const cycles: string[][] = [];
+
+  for (const node of graph.nodes) {
+    color.set(node, WHITE);
+  }
+
+  function dfs(u: string): void {
+    color.set(u, GRAY);
+
+    const outgoing = graph.forwardChain.get(u);
+    if (outgoing) {
+      for (const edge of outgoing) {
+        const v = edge.to;
+        if (color.get(v) === GRAY) {
+          // Back edge found — reconstruct cycle
+          const cycle: string[] = [v];
+          let cur = u;
+          while (cur !== v) {
+            cycle.push(cur);
+            cur = parent.get(cur) ?? v;
+          }
+          cycle.reverse();
+          cycles.push(cycle);
+        } else if (color.get(v) === WHITE) {
+          parent.set(v, u);
+          dfs(v);
+        }
+      }
+    }
+
+    color.set(u, BLACK);
+  }
+
+  for (const node of graph.nodes) {
+    if (color.get(node) === WHITE) {
+      parent.set(node, null);
+      dfs(node);
+    }
+  }
+
+  return cycles;
+}
+
+export function detectOrphans(graph: MigrationGraph): readonly MigrationChainEntry[] {
+  if (graph.nodes.size === 0) return [];
+
+  const reachable = new Set<string>();
+  const rootMigrations = graph.childrenByParentId.get(null) ?? [];
+  const emptyRootExists = rootMigrations.some(
+    (migration) => migration.from === EMPTY_CONTRACT_HASH,
+  );
+  const rootHashes = emptyRootExists
+    ? [EMPTY_CONTRACT_HASH]
+    : [...new Set(rootMigrations.map((migration) => migration.from))];
+  const queue: string[] = rootHashes.length > 0 ? rootHashes : [EMPTY_CONTRACT_HASH];
+
+  for (const hash of queue) {
+    reachable.add(hash);
+  }
+
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (node === undefined) break;
+    const outgoing = graph.forwardChain.get(node);
+    if (!outgoing) continue;
+
+    for (const migration of outgoing) {
+      if (!reachable.has(migration.to)) {
+        reachable.add(migration.to);
+        queue.push(migration.to);
+      }
+    }
+  }
+
+  const orphans: MigrationChainEntry[] = [];
+  for (const [from, migrations] of graph.forwardChain) {
+    if (!reachable.has(from)) {
+      orphans.push(...migrations);
+    }
+  }
+
+  return orphans;
+}