@prisma-next/migration-tools 0.11.0-dev.5 → 0.11.0-dev.50

package/dist/{invariants-0daYEzyo.mjs → invariants-CCOAyg6c.mjs}

@@ -1,4 +1,4 @@
-import { a as errorDuplicateInvariantInEdge, l as errorInvalidInvariantId } from "./errors-DGYwcwXs.mjs";
+import { a as errorDuplicateInvariantInEdge, l as errorInvalidInvariantId } from "./errors-4YabujxZ.mjs";
 //#region src/invariants.ts
 /**
 * Hygiene check for `invariantId`. Rejects empty values plus any
@@ -54,4 +54,4 @@ function readInvariantId(op) {
 //#endregion
 export { validateInvariantId as n, deriveProvidedInvariants as t };
 
-//# sourceMappingURL=invariants-0daYEzyo.mjs.map
+//# sourceMappingURL=invariants-CCOAyg6c.mjs.map

package/dist/{invariants-0daYEzyo.mjs.map → invariants-CCOAyg6c.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"invariants-0daYEzyo.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 ops in the migration. Ops without an `invariantId` are skipped.\n *\n * Both `data`-class ops (data-transforms, e.g. backfills) and\n * `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle\n * via `installEqlBundleOp`) may declare invariantIds: the\n * `operationClass` axis classifies *policy gating* (which kinds of ops\n * a `db init` / `db update` policy permits), while `invariantId`\n * classifies *marker bookkeeping* (which named bundles of work a\n * future regeneration knows to skip). The two concerns are\n * intentionally orthogonal — an extension can ship additive\n * non-IR-derivable DDL (the only way the planner can know the bundle\n * is already applied is via the invariantId on the marker) without\n * needing to mis-classify it as `data`-class.\n *\n * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and\n * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.\n *\n * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md\n *   — extension migrations carry `invariantId`s on additive ops; e.g.\n *   cipherstash's `installEqlBundle` and structural `create-*` ops are\n *   additive-class but carry `cipherstash:*` invariantIds.\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 (!Object.hasOwn(op, 'invariantId')) return undefined;\n  const candidate = (op as { invariantId?: unknown }).invariantId;\n  return typeof candidate === 'string' ? candidate : undefined;\n}\n"],"mappings":";;;;;;;;AAUA,SAAgB,oBAAoB,aAA8B;CAChE,IAAI,YAAY,WAAW,GAAG,OAAO;CACrC,OAAO,CAAC,2BAA2B,KAAK,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BtD,SAAgB,yBAAyB,KAAsC;CAC7E,MAAM,uBAAO,IAAI,KAAa;CAC9B,KAAK,MAAM,MAAM,KAAK;EACpB,MAAM,cAAc,gBAAgB,GAAG;EACvC,IAAI,gBAAgB,KAAA,GAAW;EAC/B,IAAI,CAAC,oBAAoB,YAAY,EACnC,MAAM,wBAAwB,YAAY;EAE5C,IAAI,KAAK,IAAI,YAAY,EACvB,MAAM,8BAA8B,YAAY;EAElD,KAAK,IAAI,YAAY;;CAEvB,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM;;AAGzB,SAAS,gBAAgB,IAAgD;CACvE,IAAI,CAAC,OAAO,OAAO,IAAI,cAAc,EAAE,OAAO,KAAA;CAC9C,MAAM,YAAa,GAAiC;CACpD,OAAO,OAAO,cAAc,WAAW,YAAY,KAAA"}
+{"version":3,"file":"invariants-CCOAyg6c.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 ops in the migration. Ops without an `invariantId` are skipped.\n *\n * Both `data`-class ops (data-transforms, e.g. backfills) and\n * `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle\n * via `installEqlBundleOp`) may declare invariantIds: the\n * `operationClass` axis classifies *policy gating* (which kinds of ops\n * a `db init` / `db update` policy permits), while `invariantId`\n * classifies *marker bookkeeping* (which named bundles of work a\n * future regeneration knows to skip). The two concerns are\n * intentionally orthogonal — an extension can ship additive\n * non-IR-derivable DDL (the only way the planner can know the bundle\n * is already applied is via the invariantId on the marker) without\n * needing to mis-classify it as `data`-class.\n *\n * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and\n * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.\n *\n * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md\n *   — extension migrations carry `invariantId`s on additive ops; e.g.\n *   cipherstash's `installEqlBundle` and structural `create-*` ops are\n *   additive-class but carry `cipherstash:*` invariantIds.\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 (!Object.hasOwn(op, 'invariantId')) return undefined;\n  const candidate = (op as { invariantId?: unknown }).invariantId;\n  return typeof candidate === 'string' ? candidate : undefined;\n}\n"],"mappings":";;;;;;;;AAUA,SAAgB,oBAAoB,aAA8B;CAChE,IAAI,YAAY,WAAW,GAAG,OAAO;CACrC,OAAO,CAAC,2BAA2B,KAAK,WAAW;AACrD;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,yBAAyB,KAAsC;CAC7E,MAAM,uBAAO,IAAI,IAAY;CAC7B,KAAK,MAAM,MAAM,KAAK;EACpB,MAAM,cAAc,gBAAgB,EAAE;EACtC,IAAI,gBAAgB,KAAA,GAAW;EAC/B,IAAI,CAAC,oBAAoB,WAAW,GAClC,MAAM,wBAAwB,WAAW;EAE3C,IAAI,KAAK,IAAI,WAAW,GACtB,MAAM,8BAA8B,WAAW;EAEjD,KAAK,IAAI,WAAW;CACtB;CACA,OAAO,CAAC,GAAG,IAAI,EAAE,KAAK;AACxB;AAEA,SAAS,gBAAgB,IAAgD;CACvE,IAAI,CAAC,OAAO,OAAO,IAAI,aAAa,GAAG,OAAO,KAAA;CAC9C,MAAM,YAAa,GAAiC;CACpD,OAAO,OAAO,cAAc,WAAW,YAAY,KAAA;AACrD"}

package/dist/{io-BPLfzvZe.mjs → io-BHl0amF0.mjs}

@@ -1,6 +1,6 @@
-import { C as errorProvidedInvariantsMismatch, c as errorInvalidDestName, d as errorInvalidManifest, g as errorInvalidSlug, i as errorDirectoryExists, u as errorInvalidJson, v as errorMigrationHashMismatch, y as errorMissingFile } from "./errors-DGYwcwXs.mjs";
-import { n as verifyMigrationHash } from "./hash-Cr4WIr4Z.mjs";
-import { t as deriveProvidedInvariants } from "./invariants-0daYEzyo.mjs";
+import { C as errorProvidedInvariantsMismatch, c as errorInvalidDestName, d as errorInvalidManifest, g as errorInvalidSlug, i as errorDirectoryExists, t as MigrationToolsError, u as errorInvalidJson, v as errorMigrationHashMismatch, y as errorMissingFile } from "./errors-4YabujxZ.mjs";
+import { n as verifyMigrationHash } from "./hash--Y7vCpN3.mjs";
+import { t as deriveProvidedInvariants } from "./invariants-CCOAyg6c.mjs";
 import { n as MigrationOpsSchema } from "./op-schema-D5qkXfEf.mjs";
 import { basename, dirname, join, resolve } from "pathe";
 import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
@@ -17,12 +17,6 @@ const MigrationMetadataSchema = type({
 	from: "string > 0 | null",
 	to: "string",
 	migrationHash: "string",
-	hints: type({
-		used: "string[]",
-		applied: "string[]",
-		plannerVersion: "string"
-	}),
-	labels: "string[]",
 	providedInvariants: "string[]",
 	createdAt: "string"
 });
@@ -177,6 +171,52 @@ async function readMigrationPackage(dir) {
 	if (!verification.ok) throw errorMigrationHashMismatch(absoluteDir, verification.storedHash, verification.computedHash);
 	return pkg;
 }
+/**
+* Reads a migration package's manifest and ops without running hash or
+* invariants verification. Returns `null` when the files cannot be read or
+* parsed (i.e. when the package is genuinely unloadable).
+*
+* Used by {@link readMigrationsDir} to retain a package whose hash or
+* invariants diverge from what is stored on disk — the raw content is still
+* useful for display / querying; only integrity is in question.
+*/
+async function readMigrationPackageRaw(dir) {
+	const absoluteDir = resolve(dir);
+	const manifestPath = join(absoluteDir, MANIFEST_FILE);
+	const opsPath = join(absoluteDir, OPS_FILE);
+	let manifestRaw;
+	try {
+		manifestRaw = await readFile(manifestPath, "utf-8");
+	} catch {
+		return null;
+	}
+	let opsRaw;
+	try {
+		opsRaw = await readFile(opsPath, "utf-8");
+	} catch {
+		return null;
+	}
+	let metadata;
+	try {
+		metadata = JSON.parse(manifestRaw);
+	} catch {
+		return null;
+	}
+	let ops;
+	try {
+		ops = JSON.parse(opsRaw);
+	} catch {
+		return null;
+	}
+	if (MigrationMetadataSchema(metadata) instanceof type.errors) return null;
+	if (MigrationOpsSchema(ops) instanceof type.errors) return null;
+	return {
+		dirName: basename(absoluteDir),
+		dirPath: absoluteDir,
+		metadata,
+		ops
+	};
+}
 function arraysEqual(a, b) {
 	if (a.length !== b.length) return false;
 	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
@@ -190,15 +230,24 @@ function validateOps(ops, filePath) {
 	const result = MigrationOpsSchema(ops);
 	if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
 }
+function packageLoadProblemDetailFromError(error) {
+	if (MigrationToolsError.is(error)) return error.why;
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
 async function readMigrationsDir(migrationsRoot) {
 	let entries;
 	try {
 		entries = await readdir(migrationsRoot);
 	} catch (error) {
-		if (hasErrnoCode(error, "ENOENT")) return [];
+		if (hasErrnoCode(error, "ENOENT")) return {
+			packages: [],
+			problems: []
+		};
 		throw error;
 	}
 	const packages = [];
+	const problems = [];
 	for (const entry of entries.sort()) {
 		const entryPath = join(migrationsRoot, entry);
 		if (!(await stat(entryPath)).isDirectory()) continue;
@@ -208,9 +257,47 @@ async function readMigrationsDir(migrationsRoot) {
 		} catch {
 			continue;
 		}
-		packages.push(await readMigrationPackage(entryPath));
+		let pkg;
+		try {
+			pkg = await readMigrationPackage(entryPath);
+		} catch (error) {
+			const dirName = entry;
+			if (MigrationToolsError.is(error)) {
+				if (error.code === "MIGRATION.HASH_MISMATCH") {
+					const details = error.details;
+					const rawPkg = await readMigrationPackageRaw(entryPath);
+					if (rawPkg !== null) packages.push(rawPkg);
+					problems.push({
+						kind: "hashMismatch",
+						dirName,
+						stored: typeof details?.["storedHash"] === "string" ? details["storedHash"] : "",
+						computed: typeof details?.["computedHash"] === "string" ? details["computedHash"] : ""
+					});
+					continue;
+				}
+				if (error.code === "MIGRATION.PROVIDED_INVARIANTS_MISMATCH") {
+					const rawPkg = await readMigrationPackageRaw(entryPath);
+					if (rawPkg !== null) packages.push(rawPkg);
+					problems.push({
+						kind: "providedInvariantsMismatch",
+						dirName
+					});
+					continue;
+				}
+			}
+			problems.push({
+				kind: "packageUnloadable",
+				dirName,
+				detail: packageLoadProblemDetailFromError(error)
+			});
+			continue;
+		}
+		packages.push(pkg);
 	}
-	return packages;
+	return {
+		packages,
+		problems
+	};
 }
 function formatMigrationDirName(timestamp, slug) {
 	const sanitized = slug.toLowerCase().replace(/[^a-z0-9]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
@@ -221,4 +308,4 @@ function formatMigrationDirName(timestamp, slug) {
 //#endregion
 export { materialiseMigrationPackage as a, writeMigrationMetadata as c, materialiseExtensionMigrationPackageIfMissing as i, writeMigrationOps as l, copyFilesWithRename as n, readMigrationPackage as o, formatMigrationDirName as r, readMigrationsDir as s, MANIFEST_FILE as t, writeMigrationPackage as u };
 
-//# sourceMappingURL=io-BPLfzvZe.mjs.map
+//# sourceMappingURL=io-BHl0amF0.mjs.map

package/dist/io-BHl0amF0.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-BHl0amF0.mjs","names":[],"sources":["../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';\nimport type {\n  MigrationMetadata,\n  MigrationPackage,\n} from '@prisma-next/framework-components/control';\nimport { type } from 'arktype';\nimport { basename, dirname, join, resolve } from 'pathe';\nimport {\n  errorDirectoryExists,\n  errorInvalidDestName,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMigrationHashMismatch,\n  errorMissingFile,\n  errorProvidedInvariantsMismatch,\n  MigrationToolsError,\n} from './errors';\nimport { verifyMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport { MigrationOpsSchema } from './op-schema';\nimport type { MigrationOps, OnDiskMigrationPackage } from './package';\n\nexport const 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 MigrationMetadataSchema = type({\n  '+': 'reject',\n  from: 'string > 0 | null',\n  to: 'string',\n  migrationHash: 'string',\n  providedInvariants: 'string[]',\n  createdAt: 'string',\n});\n\nexport async function writeMigrationPackage(\n  dir: string,\n  metadata: MigrationMetadata,\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(metadata, null, 2), {\n    flag: 'wx',\n  });\n  await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });\n}\n\n/**\n * Materialise an in-memory {@link MigrationPackage} to a per-space\n * directory on disk.\n *\n * Writes two files under `<targetDir>/<pkg.dirName>/`:\n *\n * - `migration.json` — the manifest (pretty-printed, matches\n *   {@link writeMigrationPackage}'s output for byte-for-byte parity with\n *   app-space migrations).\n * - `ops.json` — the operation list (pretty-printed).\n *\n * Distinct verb from the lower-level {@link writeMigrationPackage}\n * (which takes constituent `(metadata, ops)`): callers reading\n * `materialise…` know they are persisting a struct-typed package.\n *\n * Overwrite-idempotent: the per-package directory is cleared before\n * each emit, so re-running against the same `targetDir` produces\n * byte-identical contents and never leaves stale files behind. The\n * lower-level {@link writeMigrationPackage} stays strict because the\n * CLI authoring path (`migration plan` / `migration new`) deliberately\n * refuses to clobber an existing authored migration; this helper is\n * the re-emit path that is supposed to converge on a single canonical\n * on-disk shape.\n *\n * The per-space head contract lives at\n * `<projectMigrationsDir>/<spaceId>/contract.json` (written by\n * {@link import('./emit-contract-space-artefacts').emitContractSpaceArtefacts}),\n * not inside the per-package directory. The runner reads only\n * `migration.json` + `ops.json` from each package.\n */\nexport async function materialiseMigrationPackage(\n  targetDir: string,\n  pkg: MigrationPackage,\n): Promise<void> {\n  const dir = join(targetDir, pkg.dirName);\n  await rm(dir, { recursive: true, force: true });\n  await writeMigrationPackage(dir, pkg.metadata, pkg.ops);\n}\n\n/**\n * Idempotent variant of {@link materialiseMigrationPackage}: writes the\n * package only if `<targetDir>/<pkg.dirName>/` does not already exist on\n * disk as a directory; returns `{ written: false }` when the package\n * directory is present (no rewrite, no comparison — by-existence skip).\n *\n * Concretely:\n *   - existing directory → skip silently, return `{ written: false }`.\n *   - missing path → write three files via {@link materialiseMigrationPackage},\n *     return `{ written: true }`.\n *   - path exists but is not a directory (file/symlink) → treated as\n *     missing; {@link materialiseMigrationPackage} will attempt creation\n *     and fail with an appropriate OS error.\n *   - any other I/O error from `stat` → propagated unchanged.\n *\n * Used by the CLI's `runContractSpaceExtensionMigrationsPass` to\n * materialise extension migration packages into a project's\n * `migrations/<spaceId>/` directory, and by extension-package tests\n * that mirror the same idempotent-rematerialise property locally\n * without taking a CLI dependency.\n */\nexport async function materialiseExtensionMigrationPackageIfMissing(\n  targetDir: string,\n  pkg: MigrationPackage,\n): Promise<{ readonly written: boolean }> {\n  const pkgDir = join(targetDir, pkg.dirName);\n  if (await directoryExists(pkgDir)) {\n    return { written: false };\n  }\n  await materialiseMigrationPackage(targetDir, pkg);\n  return { written: true };\n}\n\nasync function directoryExists(p: string): Promise<boolean> {\n  try {\n    return (await stat(p)).isDirectory();\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) return false;\n    throw error;\n  }\n}\n\n/**\n * Copy a list of files into `destDir`, optionally renaming each one.\n *\n * The destination directory is created (with `recursive: true`) if it\n * does not already exist. Each source path is copied byte-for-byte into\n * `destDir/<destName>`; missing sources throw `ENOENT`. The helper is\n * intentionally generic: callers own the list of files (e.g. a contract\n * emitter's emitted output) and the naming convention (e.g. renaming\n * the destination contract to `end-contract.*` and the source contract\n * to `start-contract.*`).\n */\nexport async function copyFilesWithRename(\n  destDir: string,\n  files: readonly { readonly sourcePath: string; readonly destName: string }[],\n): Promise<void> {\n  await mkdir(destDir, { recursive: true });\n  for (const file of files) {\n    if (basename(file.destName) !== file.destName) {\n      throw errorInvalidDestName(file.destName);\n    }\n    await copyFile(file.sourcePath, join(destDir, file.destName));\n  }\n}\n\nexport async function writeMigrationMetadata(\n  dir: string,\n  metadata: MigrationMetadata,\n): Promise<void> {\n  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\\n`);\n}\n\nexport async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {\n  await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\\n`);\n}\n\nexport async function readMigrationPackage(dir: string): Promise<OnDiskMigrationPackage> {\n  const absoluteDir = resolve(dir);\n  const manifestPath = join(absoluteDir, MANIFEST_FILE);\n  const opsPath = join(absoluteDir, 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, absoluteDir);\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, absoluteDir);\n    }\n    throw error;\n  }\n\n  let metadata: MigrationMetadata;\n  try {\n    metadata = 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  validateMetadata(metadata, manifestPath);\n  validateOps(ops, opsPath);\n\n  // Re-derive before the hash check so format/duplicate diagnostics\n  // fire with their dedicated codes rather than as a generic hash mismatch.\n  const derivedInvariants = deriveProvidedInvariants(ops);\n  if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) {\n    throw errorProvidedInvariantsMismatch(\n      manifestPath,\n      metadata.providedInvariants,\n      derivedInvariants,\n    );\n  }\n\n  const pkg: OnDiskMigrationPackage = {\n    dirName: basename(absoluteDir),\n    dirPath: absoluteDir,\n    metadata,\n    ops,\n  };\n\n  const verification = verifyMigrationHash(pkg);\n  if (!verification.ok) {\n    throw errorMigrationHashMismatch(\n      absoluteDir,\n      verification.storedHash,\n      verification.computedHash,\n    );\n  }\n\n  return pkg;\n}\n\n/**\n * Reads a migration package's manifest and ops without running hash or\n * invariants verification. Returns `null` when the files cannot be read or\n * parsed (i.e. when the package is genuinely unloadable).\n *\n * Used by {@link readMigrationsDir} to retain a package whose hash or\n * invariants diverge from what is stored on disk — the raw content is still\n * useful for display / querying; only integrity is in question.\n */\nasync function readMigrationPackageRaw(dir: string): Promise<OnDiskMigrationPackage | null> {\n  const absoluteDir = resolve(dir);\n  const manifestPath = join(absoluteDir, MANIFEST_FILE);\n  const opsPath = join(absoluteDir, OPS_FILE);\n\n  let manifestRaw: string;\n  try {\n    manifestRaw = await readFile(manifestPath, 'utf-8');\n  } catch {\n    return null;\n  }\n  let opsRaw: string;\n  try {\n    opsRaw = await readFile(opsPath, 'utf-8');\n  } catch {\n    return null;\n  }\n\n  let metadata: MigrationMetadata;\n  try {\n    metadata = JSON.parse(manifestRaw);\n  } catch {\n    return null;\n  }\n  let ops: MigrationOps;\n  try {\n    ops = JSON.parse(opsRaw);\n  } catch {\n    return null;\n  }\n\n  const result = MigrationMetadataSchema(metadata);\n  if (result instanceof type.errors) return null;\n\n  const opsResult = MigrationOpsSchema(ops);\n  if (opsResult instanceof type.errors) return null;\n\n  return {\n    dirName: basename(absoluteDir),\n    dirPath: absoluteDir,\n    metadata,\n    ops,\n  };\n}\n\nfunction arraysEqual(a: readonly string[], b: readonly string[]): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) return false;\n  }\n  return true;\n}\n\nfunction validateMetadata(\n  metadata: unknown,\n  filePath: string,\n): asserts metadata is MigrationMetadata {\n  const result = MigrationMetadataSchema(metadata);\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\n/**\n * A per-package load-time problem returned by {@link readMigrationsDir}.\n *\n * Three variants, matching the relocated throws from the load path:\n *\n * - `hashMismatch` — stored `migrationHash` differs from the recomputed value.\n *   The package is **retained** in the returned `packages` array.\n * - `providedInvariantsMismatch` — `migration.json` declares different\n *   `providedInvariants` than `ops.json` implies.  The package is **retained**.\n * - `packageUnloadable` — the manifest is missing, unparseable, or schema-\n *   invalid.  The package is **omitted** from `packages`.\n *\n * Callers that need the `spaceId` context (e.g. the aggregate loader) attach\n * it when converting to {@link import('./integrity-violation').IntegrityViolation}.\n */\nexport type PackageLoadProblem =\n  | {\n      readonly kind: 'hashMismatch';\n      readonly dirName: string;\n      readonly stored: string;\n      readonly computed: string;\n    }\n  | { readonly kind: 'providedInvariantsMismatch'; readonly dirName: string }\n  | { readonly kind: 'packageUnloadable'; readonly dirName: string; readonly detail: string };\n\n/**\n * Result returned by {@link readMigrationsDir}.\n *\n * - `packages` — every package that could be read; hash-mismatched and\n *   invariants-mismatched packages are included here (the problem is\n *   represented rather than fatal).\n * - `problems` — one entry per package that had a load-time issue.\n *   `packageUnloadable` entries are **not** in `packages`.\n */\nexport interface ReadMigrationsDirResult {\n  readonly packages: readonly OnDiskMigrationPackage[];\n  readonly problems: readonly PackageLoadProblem[];\n}\n\nfunction packageLoadProblemDetailFromError(error: unknown): string {\n  if (MigrationToolsError.is(error)) return error.why;\n  if (error instanceof Error) return error.message;\n  return String(error);\n}\n\nexport async function readMigrationsDir(migrationsRoot: string): Promise<ReadMigrationsDirResult> {\n  let entries: string[];\n  try {\n    entries = await readdir(migrationsRoot);\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      return { packages: [], problems: [] };\n    }\n    throw error;\n  }\n\n  const packages: OnDiskMigrationPackage[] = [];\n  const problems: PackageLoadProblem[] = [];\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    let pkg: OnDiskMigrationPackage;\n    try {\n      pkg = await readMigrationPackage(entryPath);\n    } catch (error) {\n      const dirName = entry;\n      if (MigrationToolsError.is(error)) {\n        if (error.code === 'MIGRATION.HASH_MISMATCH') {\n          const details = error.details;\n          const rawPkg = await readMigrationPackageRaw(entryPath);\n          if (rawPkg !== null) packages.push(rawPkg);\n          problems.push({\n            kind: 'hashMismatch',\n            dirName,\n            stored: typeof details?.['storedHash'] === 'string' ? details['storedHash'] : '',\n            computed: typeof details?.['computedHash'] === 'string' ? details['computedHash'] : '',\n          });\n          continue;\n        }\n        if (error.code === 'MIGRATION.PROVIDED_INVARIANTS_MISMATCH') {\n          const rawPkg = await readMigrationPackageRaw(entryPath);\n          if (rawPkg !== null) packages.push(rawPkg);\n          problems.push({ kind: 'providedInvariantsMismatch', dirName });\n          continue;\n        }\n      }\n      // Any other error (missing file, invalid JSON, invalid manifest schema) →\n      // package unloadable; omit from packages.\n      problems.push({\n        kind: 'packageUnloadable',\n        dirName,\n        detail: packageLoadProblemDetailFromError(error),\n      });\n      continue;\n    }\n    packages.push(pkg);\n  }\n\n  return { packages, problems };\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/io-nqFXSSTN.d.mts

@@ -0,0 +1,124 @@
+import { n as OnDiskMigrationPackage, t as MigrationOps } from "./package-DIttKL7X.mjs";
+import { MigrationMetadata, MigrationPackage } from "@prisma-next/framework-components/control";
+
+//#region src/io.d.ts
+declare function writeMigrationPackage(dir: string, metadata: MigrationMetadata, ops: MigrationOps): Promise<void>;
+/**
+ * Materialise an in-memory {@link MigrationPackage} to a per-space
+ * directory on disk.
+ *
+ * Writes two files under `<targetDir>/<pkg.dirName>/`:
+ *
+ * - `migration.json` — the manifest (pretty-printed, matches
+ *   {@link writeMigrationPackage}'s output for byte-for-byte parity with
+ *   app-space migrations).
+ * - `ops.json` — the operation list (pretty-printed).
+ *
+ * Distinct verb from the lower-level {@link writeMigrationPackage}
+ * (which takes constituent `(metadata, ops)`): callers reading
+ * `materialise…` know they are persisting a struct-typed package.
+ *
+ * Overwrite-idempotent: the per-package directory is cleared before
+ * each emit, so re-running against the same `targetDir` produces
+ * byte-identical contents and never leaves stale files behind. The
+ * lower-level {@link writeMigrationPackage} stays strict because the
+ * CLI authoring path (`migration plan` / `migration new`) deliberately
+ * refuses to clobber an existing authored migration; this helper is
+ * the re-emit path that is supposed to converge on a single canonical
+ * on-disk shape.
+ *
+ * The per-space head contract lives at
+ * `<projectMigrationsDir>/<spaceId>/contract.json` (written by
+ * {@link import('./emit-contract-space-artefacts').emitContractSpaceArtefacts}),
+ * not inside the per-package directory. The runner reads only
+ * `migration.json` + `ops.json` from each package.
+ */
+declare function materialiseMigrationPackage(targetDir: string, pkg: MigrationPackage): Promise<void>;
+/**
+ * Idempotent variant of {@link materialiseMigrationPackage}: writes the
+ * package only if `<targetDir>/<pkg.dirName>/` does not already exist on
+ * disk as a directory; returns `{ written: false }` when the package
+ * directory is present (no rewrite, no comparison — by-existence skip).
+ *
+ * Concretely:
+ *   - existing directory → skip silently, return `{ written: false }`.
+ *   - missing path → write three files via {@link materialiseMigrationPackage},
+ *     return `{ written: true }`.
+ *   - path exists but is not a directory (file/symlink) → treated as
+ *     missing; {@link materialiseMigrationPackage} will attempt creation
+ *     and fail with an appropriate OS error.
+ *   - any other I/O error from `stat` → propagated unchanged.
+ *
+ * Used by the CLI's `runContractSpaceExtensionMigrationsPass` to
+ * materialise extension migration packages into a project's
+ * `migrations/<spaceId>/` directory, and by extension-package tests
+ * that mirror the same idempotent-rematerialise property locally
+ * without taking a CLI dependency.
+ */
+declare function materialiseExtensionMigrationPackageIfMissing(targetDir: string, pkg: MigrationPackage): Promise<{
+  readonly written: boolean;
+}>;
+/**
+ * Copy a list of files into `destDir`, optionally renaming each one.
+ *
+ * The destination directory is created (with `recursive: true`) if it
+ * does not already exist. Each source path is copied byte-for-byte into
+ * `destDir/<destName>`; missing sources throw `ENOENT`. The helper is
+ * intentionally generic: callers own the list of files (e.g. a contract
+ * emitter's emitted output) and the naming convention (e.g. renaming
+ * the destination contract to `end-contract.*` and the source contract
+ * to `start-contract.*`).
+ */
+declare function copyFilesWithRename(destDir: string, files: readonly {
+  readonly sourcePath: string;
+  readonly destName: string;
+}[]): Promise<void>;
+declare function writeMigrationMetadata(dir: string, metadata: MigrationMetadata): Promise<void>;
+declare function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void>;
+declare function readMigrationPackage(dir: string): Promise<OnDiskMigrationPackage>;
+/**
+ * A per-package load-time problem returned by {@link readMigrationsDir}.
+ *
+ * Three variants, matching the relocated throws from the load path:
+ *
+ * - `hashMismatch` — stored `migrationHash` differs from the recomputed value.
+ *   The package is **retained** in the returned `packages` array.
+ * - `providedInvariantsMismatch` — `migration.json` declares different
+ *   `providedInvariants` than `ops.json` implies.  The package is **retained**.
+ * - `packageUnloadable` — the manifest is missing, unparseable, or schema-
+ *   invalid.  The package is **omitted** from `packages`.
+ *
+ * Callers that need the `spaceId` context (e.g. the aggregate loader) attach
+ * it when converting to {@link import('./integrity-violation').IntegrityViolation}.
+ */
+type PackageLoadProblem = {
+  readonly kind: 'hashMismatch';
+  readonly dirName: string;
+  readonly stored: string;
+  readonly computed: string;
+} | {
+  readonly kind: 'providedInvariantsMismatch';
+  readonly dirName: string;
+} | {
+  readonly kind: 'packageUnloadable';
+  readonly dirName: string;
+  readonly detail: string;
+};
+/**
+ * Result returned by {@link readMigrationsDir}.
+ *
+ * - `packages` — every package that could be read; hash-mismatched and
+ *   invariants-mismatched packages are included here (the problem is
+ *   represented rather than fatal).
+ * - `problems` — one entry per package that had a load-time issue.
+ *   `packageUnloadable` entries are **not** in `packages`.
+ */
+interface ReadMigrationsDirResult {
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly problems: readonly PackageLoadProblem[];
+}
+declare function readMigrationsDir(migrationsRoot: string): Promise<ReadMigrationsDirResult>;
+declare function formatMigrationDirName(timestamp: Date, slug: string): string;
+//#endregion
+export { materialiseExtensionMigrationPackageIfMissing as a, readMigrationsDir as c, writeMigrationPackage as d, formatMigrationDirName as i, writeMigrationMetadata as l, ReadMigrationsDirResult as n, materialiseMigrationPackage as o, copyFilesWithRename as r, readMigrationPackage as s, PackageLoadProblem as t, writeMigrationOps as u };
+//# sourceMappingURL=io-nqFXSSTN.d.mts.map

package/dist/io-nqFXSSTN.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-nqFXSSTN.d.mts","names":[],"sources":["../src/io.ts"],"mappings":";;;;iBAwCsB,qBAAA,CACpB,GAAA,UACA,QAAA,EAAU,iBAAA,EACV,GAAA,EAAK,YAAA,GACJ,OAAA;AAJH;;;;;;;;;;;;;;;AAIU;AAgDV;;;;;;;;;AAGU;AA2BV;;;;AAlFA,iBAoDsB,2BAAA,CACpB,SAAA,UACA,GAAA,EAAK,gBAAA,GACJ,OAAO;;;;;;AA8BmB;AA6B7B;;;;;;;;;;AAGU;AAUV;;;;iBA7CsB,6CAAA,CACpB,SAAA,UACA,GAAA,EAAK,gBAAA,GACJ,OAAO;EAAA,SAAY,OAAA;AAAA;;;AA6CZ;AAIV;;;;;;;;iBApBsB,mBAAA,CACpB,OAAA,UACA,KAAA;EAAA,SAA2B,UAAA;EAAA,SAA6B,QAAA;AAAA,MACvD,OAAO;AAAA,iBAUY,sBAAA,CACpB,GAAA,UACA,QAAA,EAAU,iBAAA,GACT,OAAO;AAAA,iBAIY,iBAAA,CAAkB,GAAA,UAAa,GAAA,EAAK,YAAA,GAAe,OAAO;AAAA,iBAI1D,oBAAA,CAAqB,GAAA,WAAc,OAAO,CAAC,sBAAA;;;;AAAsB;AAsKvF;;;;;;;;;;;KAAY,kBAAA;EAAA,SAEG,IAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA;EAAA,SACA,QAAA;AAAA;EAAA,SAEA,IAAA;EAAA,SAA6C,OAAA;AAAA;EAAA,SAC7C,IAAA;EAAA,SAAoC,OAAA;EAAA,SAA0B,MAAA;AAAA;AAa7B;AAShD;;;;;;;;AATgD,UAF/B,uBAAA;EAAA,SACN,QAAA,WAAmB,sBAAA;EAAA,SACnB,QAAA,WAAmB,kBAAkB;AAAA;AAAA,iBAS1B,iBAAA,CAAkB,cAAA,WAAyB,OAAO,CAAC,uBAAA;AAAA,iBAkEzD,sBAAA,CAAuB,SAAA,EAAW,IAAI,EAAE,IAAA"}

package/dist/metadata-Bp9X04gM.d.mts

@@ -0,0 +1,2 @@
+import { MigrationMetadata as MigrationMetadata$1 } from "@prisma-next/framework-components/control";
+export { MigrationMetadata$1 as t };

package/dist/{migration-graph-De0dUZoC.d.mts → migration-graph-DtNT-cqc.d.mts}

@@ -1,5 +1,5 @@
-import { n as OnDiskMigrationPackage } from "./package-DZj8YvD0.mjs";
-import { n as MigrationGraph, t as MigrationEdge } from "./graph-BrLXqoUc.mjs";
+import { n as OnDiskMigrationPackage } from "./package-DIttKL7X.mjs";
+import { n as MigrationGraph, t as MigrationEdge } from "./graph-BUZuUeBC.mjs";
 
 //#region src/migration-graph.d.ts
 declare function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): MigrationGraph;
@@ -9,7 +9,7 @@ declare function reconstructGraph(packages: readonly OnDiskMigrationPackage[]):
  * exists. Returns an empty array when `fromHash === toHash` (no-op).
  *
  * Neighbor ordering is deterministic via the tie-break sort key:
- * label priority → createdAt → to → migrationHash.
+ * createdAt → to → migrationHash.
  */
 declare function findPath(graph: MigrationGraph, fromHash: string, toHash: string): readonly MigrationEdge[] | null;
 /**
@@ -27,8 +27,8 @@ declare function findPath(graph: MigrationGraph, fromHash: string, toHash: strin
  * control chars at authoring time).
  *
  * Neighbour ordering when `required ≠ ∅`: edges covering ≥1 still-needed
- * invariant come first, with `labelPriority → createdAt → to → migrationHash`
- * as the secondary key. The heuristic steers BFS toward the satisfying path;
+ * invariant come first, with `createdAt → to → migrationHash` as the
+ * secondary key. The heuristic steers BFS toward the satisfying path;
  * correctness (shortest, deterministic) does not depend on it.
  */
 declare function findPathWithInvariants(graph: MigrationGraph, fromHash: string, toHash: string, required: ReadonlySet<string>): readonly MigrationEdge[] | null;
@@ -121,4 +121,4 @@ declare function detectCycles(graph: MigrationGraph): readonly string[][];
 declare function detectOrphans(graph: MigrationGraph): readonly MigrationEdge[];
 //#endregion
 export { findLeaf as a, findPathWithInvariants as c, findLatestMigration as i, findReachableLeaves as l, detectCycles as n, findPath as o, detectOrphans as r, findPathWithDecision as s, PathDecision as t, reconstructGraph as u };
-//# sourceMappingURL=migration-graph-De0dUZoC.d.mts.map
+//# sourceMappingURL=migration-graph-DtNT-cqc.d.mts.map

package/dist/migration-graph-DtNT-cqc.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-graph-DtNT-cqc.d.mts","names":[],"sources":["../src/migration-graph.ts"],"mappings":";;;;iBAgCgB,gBAAA,CAAiB,QAAA,WAAmB,sBAAA,KAA2B,cAAc;;AAA7F;;;;;;;iBA+DgB,QAAA,CACd,KAAA,EAAO,cAAA,EACP,QAAA,UACA,MAAA,oBACU,aAAa;AAnEoE;AA+D7F;;;;;;;;;;AAIyB;AA4CzB;;;;;;;AA/G6F,iBA+G7E,sBAAA,CACd,KAAA,EAAO,cAAA,EACP,QAAA,UACA,MAAA,UACA,QAAA,EAAU,WAAA,oBACA,aAAA;AAAA,UAsFK,YAAA;EAAA,SACN,YAAA,WAAuB,aAAa;EAAA,SACpC,QAAA;EAAA,SACA,MAAA;EAAA,SACA,gBAAA;EAAA,SACA,eAAA;EAAA,SACA,OAAA;EA5Fc;EAAA,SA8Fd,kBAAA;EARM;;;;;EAAA,SAcN,mBAAA;AAAA;;;;;;;;AAAmB;AAoB9B;;;;;;;;;KAAY,eAAA;EAAA,SACG,IAAA;EAAA,SAAqB,QAAA,EAAU,YAAA;AAAA;EAAA,SAC/B,IAAA;AAAA;EAAA,SAEA,IAAA;EAAA,SACA,cAAA,WAAyB,aAAa;EAAA,SACtC,OAAA;AAAA;;;;AAYkB;AAajC;;;UAfiB,2BAAA;EAAA,SACN,OAAA;EAAA,SACA,QAAA,GAAW,WAAW;AAAA;;;;;;;;;;AAkBf;iBALF,oBAAA,CACd,KAAA,EAAO,cAAA,EACP,QAAA,UACA,MAAA,UACA,OAAA,GAAS,2BAAA,GACR,eAAA;;;;;iBAqLa,mBAAA,CAAoB,KAAA,EAAO,cAAc,EAAE,QAAA;;;AAAgB;AAkB3E;;;;AAA8C;iBAA9B,QAAA,CAAS,KAAqB,EAAd,cAAc;;;;;;iBAwC9B,mBAAA,CAAoB,KAAA,EAAO,cAAA,GAAiB,aAAa;AAAA,iBAQzD,YAAA,CAAa,KAAqB,EAAd,cAAc;AAAA,iBA8DlC,aAAA,CAAc,KAAA,EAAO,cAAA,YAA0B,aAAa"}

package/dist/{migration-graph-nlS4TRpn.mjs → migration-graph-kGBkIZDa.mjs}

@@ -1,4 +1,4 @@
-import { S as errorNoTarget, b as errorNoInitialMigration, n as errorAmbiguousTarget, o as errorDuplicateMigrationHash, w as errorSameSourceAndTarget } from "./errors-DGYwcwXs.mjs";
+import { S as errorNoTarget, b as errorNoInitialMigration, n as errorAmbiguousTarget } from "./errors-4YabujxZ.mjs";
 import { t as EMPTY_CONTRACT_HASH } from "./constants-DWV9_o2Z.mjs";
 import { ifDefined } from "@prisma-next/utils/defined";
 //#region src/queue.ts
@@ -111,9 +111,6 @@ function reconstructGraph(packages) {
 	for (const pkg of packages) {
 		const from = pkg.metadata.from ?? "sha256:empty";
 		const { to } = pkg.metadata;
-		if (from === to) {
-			if (!pkg.ops.some((op) => op.operationClass === "data")) throw errorSameSourceAndTarget(pkg.dirPath, from);
-		}
 		nodes.add(from);
 		nodes.add(to);
 		const migration = {
@@ -122,11 +119,9 @@ function reconstructGraph(packages) {
 			migrationHash: pkg.metadata.migrationHash,
 			dirName: pkg.dirName,
 			createdAt: pkg.metadata.createdAt,
-			labels: pkg.metadata.labels,
 			invariants: pkg.metadata.providedInvariants
 		};
-		if (migrationByHash.has(migration.migrationHash)) throw errorDuplicateMigrationHash(migration.migrationHash);
-		migrationByHash.set(migration.migrationHash, migration);
+		if (!migrationByHash.has(migration.migrationHash)) migrationByHash.set(migration.migrationHash, migration);
 		appendEdge(forwardChain, from, migration);
 		appendEdge(reverseChain, to, migration);
 	}
@@ -137,22 +132,7 @@ function reconstructGraph(packages) {
 		migrationByHash
 	};
 }
-const LABEL_PRIORITY = {
-	main: 0,
-	default: 1,
-	feature: 2
-};
-function labelPriority(labels) {
-	let best = 3;
-	for (const l of labels) {
-		const p = LABEL_PRIORITY[l];
-		if (p !== void 0 && p < best) best = p;
-	}
-	return best;
-}
 function compareTieBreak(a, b) {
-	const lp = labelPriority(a.labels) - labelPriority(b.labels);
-	if (lp !== 0) return lp;
 	const ca = a.createdAt.localeCompare(b.createdAt);
 	if (ca !== 0) return ca;
 	const tc = a.to.localeCompare(b.to);
@@ -168,7 +148,7 @@ function sortedNeighbors(edges) {
 * exists. Returns an empty array when `fromHash === toHash` (no-op).
 *
 * Neighbor ordering is deterministic via the tie-break sort key:
-* label priority → createdAt → to → migrationHash.
+* createdAt → to → migrationHash.
 */
 function findPath(graph, fromHash, toHash) {
 	if (fromHash === toHash) return [];
@@ -208,8 +188,8 @@ function findPath(graph, fromHash, toHash) {
 * control chars at authoring time).
 *
 * Neighbour ordering when `required ≠ ∅`: edges covering ≥1 still-needed
-* invariant come first, with `labelPriority → createdAt → to → migrationHash`
-* as the secondary key. The heuristic steers BFS toward the satisfying path;
+* invariant come first, with `createdAt → to → migrationHash` as the
+* secondary key. The heuristic steers BFS toward the satisfying path;
 * correctness (shortest, deterministic) does not depend on it.
 */
 function findPathWithInvariants(graph, fromHash, toHash, required) {
@@ -520,4 +500,4 @@ function detectOrphans(graph) {
 //#endregion
 export { findPath as a, findReachableLeaves as c, findLeaf as i, reconstructGraph as l, detectOrphans as n, findPathWithDecision as o, findLatestMigration as r, findPathWithInvariants as s, detectCycles as t };
 
-//# sourceMappingURL=migration-graph-nlS4TRpn.mjs.map
+//# sourceMappingURL=migration-graph-kGBkIZDa.mjs.map

package/dist/migration-graph-kGBkIZDa.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-graph-kGBkIZDa.mjs","names":[],"sources":["../src/queue.ts","../src/graph-ops.ts","../src/migration-graph.ts"],"sourcesContent":["/**\n * FIFO queue with amortised O(1) push and shift.\n *\n * Uses a head-index cursor over a backing array rather than\n * `Array.prototype.shift()`, which is O(n) on V8. Intended for BFS-shaped\n * traversals where the queue is drained in a single pass — it does not\n * reclaim memory for already-shifted items, so it is not suitable for\n * long-lived queues with many push/shift cycles.\n */\nexport class Queue<T> {\n  private readonly items: T[];\n  private head = 0;\n\n  constructor(initial: Iterable<T> = []) {\n    this.items = [...initial];\n  }\n\n  push(item: T): void {\n    this.items.push(item);\n  }\n\n  /**\n   * Remove and return the next item. Caller must check `isEmpty` first —\n   * shifting an empty queue throws.\n   */\n  shift(): T {\n    if (this.head >= this.items.length) {\n      throw new Error('Queue.shift called on empty queue');\n    }\n    // biome-ignore lint/style/noNonNullAssertion: bounds-checked on the line above\n    return this.items[this.head++]!;\n  }\n\n  get isEmpty(): boolean {\n    return this.head >= this.items.length;\n  }\n}\n","import { Queue } from './queue';\n\n/**\n * One step of a BFS traversal.\n *\n * `parent` and `incomingEdge` are `null` for start states — they were not\n * reached via any edge. For every other state they record the predecessor\n * state and the edge by which this state was first reached.\n *\n * `state` is the BFS state, most often a string (graph node identifier) but\n * can be a composite object. The string overload keeps the common case\n * ergonomic; the generic overload accepts a caller-supplied `key` function\n * that produces a stable equality key for dedup.\n */\nexport interface BfsStep<S, E> {\n  readonly state: S;\n  readonly parent: S | null;\n  readonly incomingEdge: E | null;\n}\n\n/**\n * Generic breadth-first traversal.\n *\n * Direction (forward/reverse) is expressed by the caller's `neighbours`\n * closure: return `{ next, edge }` pairs where `next` is the state to visit\n * next and `edge` is the edge that connects them. Callers that don't need\n * path reconstruction can ignore the `parent`/`incomingEdge` fields of each\n * yielded step.\n *\n * Ordering — when the result needs to be deterministic (path-finding) the\n * caller is responsible for sorting inside `neighbours`; this generator\n * does not impose an ordering hook of its own. State-dependent orderings\n * have full access to the source state inside the closure.\n *\n * Stops are intrinsic — callers `break` out of the `for..of` loop when\n * they've found what they're looking for.\n */\nexport function bfs<E>(\n  starts: Iterable<string>,\n  neighbours: (state: string) => Iterable<{ next: string; edge: E }>,\n): Generator<BfsStep<string, E>>;\nexport function bfs<S, E>(\n  starts: Iterable<S>,\n  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,\n  key: (state: S) => string,\n): Generator<BfsStep<S, E>>;\nexport function* bfs<S, E>(\n  starts: Iterable<S>,\n  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,\n  // Identity default for the string overload. TypeScript can't express\n  // \"default applies only when S = string\", so this cast bridges the\n  // generic implementation signature to the public overloads — which\n  // guarantee `key` is omitted only when S = string at the call site.\n  key: (state: S) => string = (state) => state as unknown as string,\n): Generator<BfsStep<S, E>> {\n  // Queue entries carry the state alongside its key so we don't recompute\n  // key() twice per visit (once on dedup, once on parent lookup). Composite\n  // keys can be non-trivial to compute; string-overload callers pay nothing\n  // since key() is identity there.\n  interface Entry {\n    readonly state: S;\n    readonly key: string;\n  }\n  const visited = new Set<string>();\n  const parentMap = new Map<string, { parent: S; edge: E }>();\n  const queue = new Queue<Entry>();\n  for (const start of starts) {\n    const k = key(start);\n    if (!visited.has(k)) {\n      visited.add(k);\n      queue.push({ state: start, key: k });\n    }\n  }\n  while (!queue.isEmpty) {\n    const { state: current, key: curKey } = queue.shift();\n    const parentInfo = parentMap.get(curKey);\n    yield {\n      state: current,\n      parent: parentInfo?.parent ?? null,\n      incomingEdge: parentInfo?.edge ?? null,\n    };\n\n    for (const { next, edge } of neighbours(current)) {\n      const k = key(next);\n      if (!visited.has(k)) {\n        visited.add(k);\n        parentMap.set(k, { parent: current, edge });\n        queue.push({ state: next, key: k });\n      }\n    }\n  }\n}\n","import { ifDefined } from '@prisma-next/utils/defined';\nimport { EMPTY_CONTRACT_HASH } from './constants';\nimport { errorAmbiguousTarget, errorNoInitialMigration, errorNoTarget } from './errors';\nimport type { MigrationEdge, MigrationGraph } from './graph';\nimport { bfs } from './graph-ops';\nimport type { OnDiskMigrationPackage } from './package';\n\n/** Forward-edge neighbours: edge `e` from `n` visits `e.to` next. */\nfunction forwardNeighbours(graph: MigrationGraph, node: string) {\n  return (graph.forwardChain.get(node) ?? []).map((edge) => ({ next: edge.to, edge }));\n}\n\n/**\n * Forward-edge neighbours, sorted by the deterministic tie-break.\n * Used by path-finding so the resulting shortest path is stable across runs.\n */\nfunction sortedForwardNeighbours(graph: MigrationGraph, node: string) {\n  const edges = graph.forwardChain.get(node) ?? [];\n  return [...edges].sort(compareTieBreak).map((edge) => ({ next: edge.to, edge }));\n}\n\n/** Reverse-edge neighbours: edge `e` from `n` visits `e.from` next. */\nfunction reverseNeighbours(graph: MigrationGraph, node: string) {\n  return (graph.reverseChain.get(node) ?? []).map((edge) => ({ next: edge.from, edge }));\n}\n\nfunction appendEdge(map: Map<string, MigrationEdge[]>, key: string, entry: MigrationEdge): void {\n  const bucket = map.get(key);\n  if (bucket) bucket.push(entry);\n  else map.set(key, [entry]);\n}\n\nexport function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): MigrationGraph {\n  const nodes = new Set<string>();\n  const forwardChain = new Map<string, MigrationEdge[]>();\n  const reverseChain = new Map<string, MigrationEdge[]>();\n  const migrationByHash = new Map<string, MigrationEdge>();\n\n  for (const pkg of packages) {\n    // Manifest `from` is `string | null` (null = baseline). The graph layer\n    // is the marker/path layer where \"no prior state\" is encoded as the\n    // EMPTY_CONTRACT_HASH sentinel; bridge here so pathfinding stays string-\n    // keyed.\n    const from = pkg.metadata.from ?? EMPTY_CONTRACT_HASH;\n    const { to } = pkg.metadata;\n\n    nodes.add(from);\n    nodes.add(to);\n\n    const migration: MigrationEdge = {\n      from,\n      to,\n      migrationHash: pkg.metadata.migrationHash,\n      dirName: pkg.dirName,\n      createdAt: pkg.metadata.createdAt,\n      invariants: pkg.metadata.providedInvariants,\n    };\n\n    if (!migrationByHash.has(migration.migrationHash)) {\n      migrationByHash.set(migration.migrationHash, migration);\n    }\n\n    appendEdge(forwardChain, from, migration);\n    appendEdge(reverseChain, to, migration);\n  }\n\n  return { nodes, forwardChain, reverseChain, migrationByHash };\n}\n\n// ---------------------------------------------------------------------------\n// Deterministic tie-breaking for BFS neighbour order.\n// Used by path-finders only; not a general-purpose utility.\n// Ordering: createdAt → to → migrationHash.\n// ---------------------------------------------------------------------------\n\nfunction compareTieBreak(a: MigrationEdge, b: MigrationEdge): number {\n  const ca = a.createdAt.localeCompare(b.createdAt);\n  if (ca !== 0) return ca;\n  const tc = a.to.localeCompare(b.to);\n  if (tc !== 0) return tc;\n  return a.migrationHash.localeCompare(b.migrationHash);\n}\n\nfunction sortedNeighbors(edges: readonly MigrationEdge[]): readonly MigrationEdge[] {\n  return [...edges].sort(compareTieBreak);\n}\n\n/**\n * Find the shortest path from `fromHash` to `toHash` using BFS over the\n * contract-hash graph. Returns the ordered list of edges, or null if no path\n * exists. Returns an empty array when `fromHash === toHash` (no-op).\n *\n * Neighbor ordering is deterministic via the tie-break sort key:\n * createdAt → to → migrationHash.\n */\nexport function findPath(\n  graph: MigrationGraph,\n  fromHash: string,\n  toHash: string,\n): readonly MigrationEdge[] | null {\n  if (fromHash === toHash) return [];\n\n  const parents = new Map<string, { parent: string; edge: MigrationEdge }>();\n  for (const step of bfs([fromHash], (n) => sortedForwardNeighbours(graph, n))) {\n    if (step.parent !== null && step.incomingEdge !== null) {\n      parents.set(step.state, { parent: step.parent, edge: step.incomingEdge });\n    }\n    if (step.state === toHash) {\n      const path: MigrationEdge[] = [];\n      let cur = toHash;\n      let p = parents.get(cur);\n      while (p) {\n        path.push(p.edge);\n        cur = p.parent;\n        p = parents.get(cur);\n      }\n      path.reverse();\n      return path;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Find the shortest path from `fromHash` to `toHash` whose edges collectively\n * cover every invariant in `required`. Returns `null` when no such path exists\n * (either `fromHash`→`toHash` is structurally unreachable, or every reachable\n * path leaves at least one required invariant uncovered). When `required` is\n * empty, delegates to `findPath` so the result is byte-identical for that case.\n *\n * Algorithm: BFS over `(node, coveredSubset)` states with state-level dedup.\n * The covered subset is a `Set<string>` of invariant ids; the state's dedup\n * key is `${node}\\0${[...covered].sort().join('\\0')}`. State keys distinguish\n * distinct `(node, covered)` tuples regardless of node-name length because\n * `\\0` cannot appear in any invariant id (validation rejects whitespace and\n * control chars at authoring time).\n *\n * Neighbour ordering when `required ≠ ∅`: edges covering ≥1 still-needed\n * invariant come first, with `createdAt → to → migrationHash` as the\n * secondary key. The heuristic steers BFS toward the satisfying path;\n * correctness (shortest, deterministic) does not depend on it.\n */\nexport function findPathWithInvariants(\n  graph: MigrationGraph,\n  fromHash: string,\n  toHash: string,\n  required: ReadonlySet<string>,\n): readonly MigrationEdge[] | null {\n  if (required.size === 0) {\n    return findPath(graph, fromHash, toHash);\n  }\n\n  interface InvState {\n    readonly node: string;\n    readonly covered: ReadonlySet<string>;\n  }\n  // `\\0` is a safe segment separator: `validateInvariantId` rejects any id\n  // containing whitespace or control characters (NUL is U+0000), and node\n  // hashes are hex strings. Distinct `(node, covered)` tuples therefore\n  // map to distinct strings. If `validateInvariantId` is ever relaxed,\n  // re-confirm dedup correctness here.\n  const stateKey = (s: InvState): string => {\n    if (s.covered.size === 0) return `${s.node}\\0`;\n    return `${s.node}\\0${[...s.covered].sort().join('\\0')}`;\n  };\n\n  const neighbours = (s: InvState): Iterable<{ next: InvState; edge: MigrationEdge }> => {\n    const outgoing = graph.forwardChain.get(s.node) ?? [];\n    if (outgoing.length === 0) return [];\n    return [...outgoing]\n      .map((edge) => {\n        let useful = false;\n        let next: Set<string> | null = null;\n        for (const inv of edge.invariants) {\n          if (required.has(inv) && !s.covered.has(inv)) {\n            if (next === null) next = new Set(s.covered);\n            next.add(inv);\n            useful = true;\n          }\n        }\n        return { edge, useful, nextCovered: next ?? s.covered };\n      })\n      .sort((a, b) => {\n        if (a.useful !== b.useful) return a.useful ? -1 : 1;\n        return compareTieBreak(a.edge, b.edge);\n      })\n      .map(({ edge, nextCovered }) => ({\n        next: { node: edge.to, covered: nextCovered },\n        edge,\n      }));\n  };\n\n  // Path reconstruction is consumer-side, keyed on stateKey, same shape as\n  // findPath's parents map.\n  const parents = new Map<string, { parentKey: string; edge: MigrationEdge }>();\n  for (const step of bfs<InvState, MigrationEdge>(\n    [{ node: fromHash, covered: new Set() }],\n    neighbours,\n    stateKey,\n  )) {\n    const curKey = stateKey(step.state);\n    if (step.parent !== null && step.incomingEdge !== null) {\n      parents.set(curKey, { parentKey: stateKey(step.parent), edge: step.incomingEdge });\n    }\n    if (step.state.node === toHash && step.state.covered.size === required.size) {\n      const path: MigrationEdge[] = [];\n      let cur: string | undefined = curKey;\n      while (cur !== undefined) {\n        const p = parents.get(cur);\n        if (!p) break;\n        path.push(p.edge);\n        cur = p.parentKey;\n      }\n      path.reverse();\n      return path;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Reverse-BFS from `toHash` over `reverseChain` to collect every node from\n * which `toHash` is reachable (inclusive of `toHash` itself).\n */\nfunction collectNodesReachingTarget(graph: MigrationGraph, toHash: string): Set<string> {\n  const reached = new Set<string>();\n  for (const step of bfs([toHash], (n) => reverseNeighbours(graph, n))) {\n    reached.add(step.state);\n  }\n  return reached;\n}\n\nexport interface PathDecision {\n  readonly selectedPath: readonly MigrationEdge[];\n  readonly fromHash: string;\n  readonly toHash: string;\n  readonly alternativeCount: number;\n  readonly tieBreakReasons: readonly string[];\n  readonly refName?: string;\n  /** The caller-supplied required invariant set, sorted ascending. */\n  readonly requiredInvariants: readonly string[];\n  /**\n   * The subset of `requiredInvariants` actually covered by edges on\n   * `selectedPath`. Always a subset of `requiredInvariants` (when the path\n   * is satisfying, equal to it); always derived from `selectedPath`.\n   */\n  readonly satisfiedInvariants: readonly string[];\n}\n\n/**\n * Outcome of {@link findPathWithDecision}. The pathfinder distinguishes\n * three cases up front so callers don't re-derive structural reachability:\n *\n * - `ok` — a path covering `required` exists; `decision` carries the\n *   selection metadata and per-edge invariants.\n * - `unreachable` — `from`→`to` has no structural path. Mapped by callers\n *   to the existing no-path / `NO_TARGET` diagnostic.\n * - `unsatisfiable` — `from`→`to` is structurally reachable but no path\n *   covers every required invariant. `structuralPath` is the\n *   `findPath(graph, from, to)` result, included so callers don't have to\n *   recompute it when raising `MIGRATION.NO_INVARIANT_PATH`. `missing` is\n *   the subset of `required` that the structural path does *not* cover —\n *   correctly accounts for partial coverage when some required invariants\n *   are met by the fallback path. Only emitted when `required` is\n *   non-empty.\n */\nexport type FindPathOutcome =\n  | { readonly kind: 'ok'; readonly decision: PathDecision }\n  | { readonly kind: 'unreachable' }\n  | {\n      readonly kind: 'unsatisfiable';\n      readonly structuralPath: readonly MigrationEdge[];\n      readonly missing: readonly string[];\n    };\n\n/**\n * Routing context for {@link findPathWithDecision}. Both fields are optional;\n * `refName` is only used to decorate the resulting `PathDecision` for the\n * JSON envelope, and `required` defaults to an empty set (purely structural\n * routing). They are passed via a single options object so the call sites\n * cannot silently swap two adjacent string parameters.\n */\nexport interface FindPathWithDecisionOptions {\n  readonly refName?: string;\n  readonly required?: ReadonlySet<string>;\n}\n\n/**\n * Find the shortest path from `fromHash` to `toHash` and return structured\n * path-decision metadata for machine-readable output. When `required` is\n * non-empty, the returned path is the shortest one whose edges collectively\n * cover every required invariant.\n *\n * The discriminated return type tells the caller *why* a path could not be\n * found, so the CLI can pick the right structured error without re-running\n * a structural BFS.\n */\nexport function findPathWithDecision(\n  graph: MigrationGraph,\n  fromHash: string,\n  toHash: string,\n  options: FindPathWithDecisionOptions = {},\n): FindPathOutcome {\n  const { refName, required = new Set<string>() } = options;\n  const requiredInvariants = [...required].sort();\n\n  if (fromHash === toHash && required.size === 0) {\n    return {\n      kind: 'ok',\n      decision: {\n        selectedPath: [],\n        fromHash,\n        toHash,\n        alternativeCount: 0,\n        tieBreakReasons: [],\n        requiredInvariants,\n        satisfiedInvariants: [],\n        ...ifDefined('refName', refName),\n      },\n    };\n  }\n\n  const path = findPathWithInvariants(graph, fromHash, toHash, required);\n  if (!path) {\n    if (required.size === 0) {\n      return { kind: 'unreachable' };\n    }\n    const structural = findPath(graph, fromHash, toHash);\n    if (structural === null) {\n      return { kind: 'unreachable' };\n    }\n    const coveredByStructural = new Set<string>();\n    for (const edge of structural) {\n      for (const inv of edge.invariants) {\n        if (required.has(inv)) coveredByStructural.add(inv);\n      }\n    }\n    const missing = requiredInvariants.filter((id) => !coveredByStructural.has(id));\n    return { kind: 'unsatisfiable', structuralPath: structural, missing };\n  }\n\n  const satisfiedInvariants = computeSatisfiedInvariants(required, path);\n\n  // Single reverse BFS marks every node from which `toHash` is reachable.\n  // Replaces a per-edge `findPath(e.to, toHash)` call inside the loop below,\n  // which made the whole function O(|path| · (V + E)) instead of O(V + E).\n  const reachesTarget = collectNodesReachingTarget(graph, toHash);\n  const coveragePrefixes = requiredCoveragePrefixes(required, path);\n\n  const tieBreakReasons: string[] = [];\n  let alternativeCount = 0;\n\n  for (const [i, edge] of path.entries()) {\n    const outgoing = graph.forwardChain.get(edge.from);\n    if (!outgoing || outgoing.length <= 1) continue;\n    const reachable = outgoing.filter((e) => reachesTarget.has(e.to));\n    if (reachable.length <= 1) continue;\n\n    let comparisonPool: readonly MigrationEdge[] = reachable;\n    if (required.size > 0) {\n      // coveragePrefixes is built one-per-edge from path, so the index is\n      // always in range here; the explicit guard keeps the type narrowed\n      // without a non-null assertion.\n      const prefixSet = coveragePrefixes[i];\n      if (prefixSet === undefined) continue;\n      comparisonPool = invariantViableAlternativesAtStep(required, prefixSet, reachable);\n    }\n\n    alternativeCount += reachable.length - 1;\n    const sorted = sortedNeighbors(reachable);\n    if (sorted[0]?.migrationHash !== edge.migrationHash) continue;\n    if (!reachable.some((e) => e.migrationHash !== edge.migrationHash)) continue;\n\n    const sortedViable = sortedNeighbors(comparisonPool);\n    if (\n      sortedViable.length > 1 &&\n      sortedViable[0]?.migrationHash === edge.migrationHash &&\n      sortedViable.some((e) => e.migrationHash !== edge.migrationHash)\n    ) {\n      tieBreakReasons.push(\n        `at ${edge.from}: ${comparisonPool.length} candidates, selected by tie-break`,\n      );\n    }\n  }\n\n  return {\n    kind: 'ok',\n    decision: {\n      selectedPath: path,\n      fromHash,\n      toHash,\n      alternativeCount,\n      tieBreakReasons,\n      requiredInvariants,\n      satisfiedInvariants,\n      ...ifDefined('refName', refName),\n    },\n  };\n}\n\nfunction computeSatisfiedInvariants(\n  required: ReadonlySet<string>,\n  path: readonly MigrationEdge[],\n): readonly string[] {\n  if (required.size === 0) return [];\n  const covered = new Set<string>();\n  for (const edge of path) {\n    for (const inv of edge.invariants) {\n      if (required.has(inv)) covered.add(inv);\n    }\n  }\n  return [...covered].sort();\n}\n\n/**\n * For each edge on path, invariant coverage accumulated from earlier edges only —\n * `(required ∩ ∪_{j<i} path[j].invariants)` represented as cumulative set along `required`,\n * keyed as \"full set of required ids satisfied before taking path[i]\".\n */\nfunction requiredCoveragePrefixes(\n  required: ReadonlySet<string>,\n  path: readonly MigrationEdge[],\n): readonly ReadonlySet<string>[] {\n  const prefixes: ReadonlySet<string>[] = [];\n  const acc = new Set<string>();\n  for (const edge of path) {\n    prefixes.push(new Set(acc));\n    for (const inv of edge.invariants) {\n      if (required.has(inv)) acc.add(inv);\n    }\n  }\n  return prefixes;\n}\n\nfunction invariantViableAlternativesAtStep(\n  required: ReadonlySet<string>,\n  coverageBeforeTakingEdge: ReadonlySet<string>,\n  outgoing: readonly MigrationEdge[],\n): readonly MigrationEdge[] {\n  if (required.size === 0) return [...outgoing];\n  return outgoing.filter((e) =>\n    [...required].every((id) => coverageBeforeTakingEdge.has(id) || e.invariants.includes(id)),\n  );\n}\n\n/**\n * Walk ancestors of each branch tip back to find the last node\n * that appears on all paths. Returns `fromHash` if no shared ancestor is found.\n */\nfunction findDivergencePoint(\n  graph: MigrationGraph,\n  fromHash: string,\n  leaves: readonly string[],\n): string {\n  const ancestorSets = leaves.map((leaf) => {\n    const ancestors = new Set<string>();\n    for (const step of bfs([leaf], (n) => reverseNeighbours(graph, n))) {\n      ancestors.add(step.state);\n    }\n    return ancestors;\n  });\n\n  const commonAncestors = [...(ancestorSets[0] ?? [])].filter((node) =>\n    ancestorSets.every((s) => s.has(node)),\n  );\n\n  let deepest = fromHash;\n  let deepestDepth = -1;\n  for (const ancestor of commonAncestors) {\n    const path = findPath(graph, fromHash, ancestor);\n    const depth = path ? path.length : 0;\n    if (depth > deepestDepth) {\n      deepestDepth = depth;\n      deepest = ancestor;\n    }\n  }\n  return deepest;\n}\n\n/**\n * Find all branch tips (nodes with no outgoing edges) reachable from\n * `fromHash` via forward edges.\n */\nexport function findReachableLeaves(graph: MigrationGraph, fromHash: string): readonly string[] {\n  const leaves: string[] = [];\n  for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n))) {\n    if (!graph.forwardChain.get(step.state)?.length) {\n      leaves.push(step.state);\n    }\n  }\n  return leaves;\n}\n\n/**\n * Find the target contract hash of the migration graph reachable from\n * EMPTY_CONTRACT_HASH. Returns `null` for a graph that has no target\n * state (either empty, or containing only the root with no outgoing\n * edges). Throws NO_INITIAL_MIGRATION if the graph has nodes but none\n * originate from the empty hash, and AMBIGUOUS_TARGET if multiple\n * branch tips exist.\n */\nexport function findLeaf(graph: MigrationGraph): string | null {\n  if (graph.nodes.size === 0) {\n    return null;\n  }\n\n  if (!graph.nodes.has(EMPTY_CONTRACT_HASH)) {\n    throw errorNoInitialMigration([...graph.nodes]);\n  }\n\n  const leaves = findReachableLeaves(graph, EMPTY_CONTRACT_HASH);\n\n  if (leaves.length === 0) {\n    const reachable = [...graph.nodes].filter((n) => n !== EMPTY_CONTRACT_HASH);\n    if (reachable.length > 0) {\n      throw errorNoTarget(reachable);\n    }\n    return null;\n  }\n\n  if (leaves.length > 1) {\n    const divergencePoint = findDivergencePoint(graph, EMPTY_CONTRACT_HASH, leaves);\n    const branches = leaves.map((tip) => {\n      const path = findPath(graph, divergencePoint, tip);\n      return {\n        tip,\n        edges: (path ?? []).map((e) => ({ dirName: e.dirName, from: e.from, to: e.to })),\n      };\n    });\n    throw errorAmbiguousTarget(leaves, { divergencePoint, branches });\n  }\n\n  // biome-ignore lint/style/noNonNullAssertion: leaves.length is neither 0 nor >1 per the branches above, so exactly one leaf remains\n  return leaves[0]!;\n}\n\n/**\n * Find the latest migration entry by traversing from EMPTY_CONTRACT_HASH\n * to the single target. Returns null for an empty graph.\n * Throws AMBIGUOUS_TARGET if the graph has multiple branch tips.\n */\nexport function findLatestMigration(graph: MigrationGraph): MigrationEdge | null {\n  const leafHash = findLeaf(graph);\n  if (leafHash === null) return null;\n\n  const path = findPath(graph, EMPTY_CONTRACT_HASH, leafHash);\n  return path?.at(-1) ?? null;\n}\n\nexport function detectCycles(graph: MigrationGraph): readonly string[][] {\n  const WHITE = 0;\n  const GRAY = 1;\n  const BLACK = 2;\n\n  const color = new Map<string, number>();\n  const parentMap = new Map<string, string | null>();\n  const cycles: string[][] = [];\n\n  for (const node of graph.nodes) {\n    color.set(node, WHITE);\n  }\n\n  // Iterative three-color DFS. A frame is (node, outgoing edges, next-index).\n  interface Frame {\n    node: string;\n    outgoing: readonly MigrationEdge[];\n    index: number;\n  }\n  const stack: Frame[] = [];\n\n  function pushFrame(u: string): void {\n    color.set(u, GRAY);\n    stack.push({ node: u, outgoing: graph.forwardChain.get(u) ?? [], index: 0 });\n  }\n\n  for (const root of graph.nodes) {\n    if (color.get(root) !== WHITE) continue;\n    parentMap.set(root, null);\n    pushFrame(root);\n\n    while (stack.length > 0) {\n      // biome-ignore lint/style/noNonNullAssertion: stack.length > 0 should guarantee that this cannot be undefined\n      const frame = stack[stack.length - 1]!;\n      if (frame.index >= frame.outgoing.length) {\n        color.set(frame.node, BLACK);\n        stack.pop();\n        continue;\n      }\n      // biome-ignore lint/style/noNonNullAssertion: the early-continue above guarantees frame.index < frame.outgoing.length here, so this is defined\n      const edge = frame.outgoing[frame.index++]!;\n      const v = edge.to;\n      const vColor = color.get(v);\n      if (vColor === GRAY) {\n        const cycle: string[] = [v];\n        let cur = frame.node;\n        while (cur !== v) {\n          cycle.push(cur);\n          cur = parentMap.get(cur) ?? v;\n        }\n        cycle.reverse();\n        cycles.push(cycle);\n      } else if (vColor === WHITE) {\n        parentMap.set(v, frame.node);\n        pushFrame(v);\n      }\n    }\n  }\n\n  return cycles;\n}\n\nexport function detectOrphans(graph: MigrationGraph): readonly MigrationEdge[] {\n  if (graph.nodes.size === 0) return [];\n\n  const reachable = new Set<string>();\n  const startNodes: string[] = [];\n\n  if (graph.forwardChain.has(EMPTY_CONTRACT_HASH)) {\n    startNodes.push(EMPTY_CONTRACT_HASH);\n  } else {\n    const allTargets = new Set<string>();\n    for (const edges of graph.forwardChain.values()) {\n      for (const edge of edges) {\n        allTargets.add(edge.to);\n      }\n    }\n    for (const node of graph.nodes) {\n      if (!allTargets.has(node)) {\n        startNodes.push(node);\n      }\n    }\n  }\n\n  for (const step of bfs(startNodes, (n) => forwardNeighbours(graph, n))) {\n    reachable.add(step.state);\n  }\n\n  const orphans: MigrationEdge[] = [];\n  for (const [from, migrations] of graph.forwardChain) {\n    if (!reachable.has(from)) {\n      orphans.push(...migrations);\n    }\n  }\n\n  return orphans;\n}\n"],"mappings":"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"}

package/dist/migration-list-types-BRTuXR8i.d.mts

@@ -0,0 +1,23 @@
+//#region src/migration-list-types.d.ts
+interface MigrationListEntry {
+  readonly dirName: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+  readonly refs: readonly string[];
+  readonly providedInvariants: readonly string[];
+}
+interface MigrationSpaceListEntry {
+  readonly spaceId: string;
+  readonly migrations: readonly MigrationListEntry[];
+}
+interface MigrationListResult {
+  readonly ok: true;
+  readonly spaces: readonly MigrationSpaceListEntry[];
+  readonly summary: string;
+}
+//#endregion
+export { MigrationListResult as n, MigrationSpaceListEntry as r, MigrationListEntry as t };
+//# sourceMappingURL=migration-list-types-BRTuXR8i.d.mts.map

package/dist/migration-list-types-BRTuXR8i.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-list-types-BRTuXR8i.d.mts","names":[],"sources":["../src/migration-list-types.ts"],"mappings":";UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,IAAA;EAAA,SACA,EAAA;EAAA,SACA,aAAA;EAAA,SACA,cAAA;EAAA,SACA,SAAA;EAAA,SACA,IAAA;EAAA,SACA,kBAAA;AAAA;AAAA,UAGM,uBAAA;EAAA,SACN,OAAA;EAAA,SACA,UAAA,WAAqB,kBAAkB;AAAA;AAAA,UAGjC,mBAAA;EAAA,SACN,EAAA;EAAA,SACA,MAAA,WAAiB,uBAAuB;EAAA,SACxC,OAAA;AAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"op-schema-D5qkXfEf.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"}
+{"version":3,"file":"op-schema-D5qkXfEf.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;AAClB,CAAC;AAGD,MAAa,qBAAqB,kBAAkB,MAAM"}

package/dist/{package-DZj8YvD0.d.mts → package-DIttKL7X.d.mts}

@@ -18,4 +18,4 @@ interface OnDiskMigrationPackage extends MigrationPackage {
 }
 //#endregion
 export { OnDiskMigrationPackage as n, MigrationOps as t };
-//# sourceMappingURL=package-DZj8YvD0.d.mts.map
+//# sourceMappingURL=package-DIttKL7X.d.mts.map

package/dist/package-DIttKL7X.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-DIttKL7X.d.mts","names":[],"sources":["../src/package.ts"],"mappings":";;;KAKY,YAAA,YAAwB,sBAAsB;;AAA1D;;;;AAA0D;AAa1D;;;;AACkB;UADD,sBAAA,SAA+B,gBAAgB;EAAA,SACrD,OAAO;AAAA"}