@prisma-next/migration-tools 0.5.0-dev.15 → 0.5.0-dev.17

package/dist/{constants-WVGVMOdu.mjs → constants-DOzBI2EP.mjs}

@@ -7,4 +7,4 @@ const EMPTY_CONTRACT_HASH = "sha256:empty";
 
 //#endregion
 export { EMPTY_CONTRACT_HASH as t };
-//# sourceMappingURL=constants-WVGVMOdu.mjs.map
+//# sourceMappingURL=constants-DOzBI2EP.mjs.map

package/dist/{constants-WVGVMOdu.mjs.map → constants-DOzBI2EP.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"constants-WVGVMOdu.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Sentinel value representing the absence of a contract (empty/new project).\n * This is a human-readable marker, not a real SHA-256 hash.\n */\nexport const EMPTY_CONTRACT_HASH = 'sha256:empty' as const;\n"],"mappings":";;;;;AAIA,MAAa,sBAAsB"}
+{"version":3,"file":"constants-DOzBI2EP.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Sentinel value representing the absence of a contract (empty/new project).\n * This is a human-readable marker, not a real SHA-256 hash.\n */\nexport const EMPTY_CONTRACT_HASH = 'sha256:empty' as const;\n"],"mappings":";;;;;AAIA,MAAa,sBAAsB"}

package/dist/{errors-CZ9JD4sd.mjs → errors-BS_Kq8GF.mjs}

@@ -172,6 +172,39 @@ function errorDuplicateMigrationHash(migrationHash) {
 		details: { migrationHash }
 	});
 }
+function errorInvalidInvariantId(invariantId) {
+	return new MigrationToolsError("MIGRATION.INVALID_INVARIANT_ID", "Invalid invariantId", {
+		why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,
+		fix: "Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".",
+		details: { invariantId }
+	});
+}
+function errorDuplicateInvariantInEdge(invariantId) {
+	return new MigrationToolsError("MIGRATION.DUPLICATE_INVARIANT_IN_EDGE", "Duplicate invariantId on a single migration", {
+		why: `invariantId "${invariantId}" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,
+		fix: "Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.",
+		details: { invariantId }
+	});
+}
+function errorProvidedInvariantsMismatch(filePath, stored, derived) {
+	const storedSet = new Set(stored);
+	const derivedSet = new Set(derived);
+	const missing = [...derivedSet].filter((id) => !storedSet.has(id));
+	const extra = [...storedSet].filter((id) => !derivedSet.has(id));
+	return new MigrationToolsError("MIGRATION.PROVIDED_INVARIANTS_MISMATCH", "providedInvariants on migration.json disagrees with ops.json", {
+		why: missing.length === 0 && extra.length === 0 ? `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.` : `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`,
+		fix: reemitHint(dirname(filePath), "or restore the directory from version control."),
+		details: {
+			filePath,
+			stored,
+			derived,
+			difference: {
+				missing,
+				extra
+			}
+		}
+	});
+}
 function errorMigrationHashMismatch(dir, storedHash, computedHash) {
 	return new MigrationToolsError("MIGRATION.HASH_MISMATCH", "Migration package is corrupt", {
 		why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relative(process.cwd(), dir)}". The migration.json or ops.json has been edited or partially written since emit.`,
@@ -185,5 +218,5 @@ function errorMigrationHashMismatch(dir, storedHash, computedHash) {
 }
 
 //#endregion
-export { errorInvalidDestName as a, errorInvalidRefFile as c, errorInvalidSlug as d, errorMigrationHashMismatch as f, errorSameSourceAndTarget as g, errorNoTarget as h, errorDuplicateMigrationHash as i, errorInvalidRefName as l, errorNoInitialMigration as m, errorAmbiguousTarget as n, errorInvalidJson as o, errorMissingFile as p, errorDirectoryExists as r, errorInvalidManifest as s, MigrationToolsError as t, errorInvalidRefValue as u };
-//# sourceMappingURL=errors-CZ9JD4sd.mjs.map
+export { errorNoTarget as _, errorDuplicateMigrationHash as a, errorInvalidJson as c, errorInvalidRefName as d, errorInvalidRefValue as f, errorNoInitialMigration as g, errorMissingFile as h, errorDuplicateInvariantInEdge as i, errorInvalidManifest as l, errorMigrationHashMismatch as m, errorAmbiguousTarget as n, errorInvalidDestName as o, errorInvalidSlug as p, errorDirectoryExists as r, errorInvalidInvariantId as s, MigrationToolsError as t, errorInvalidRefFile as u, errorProvidedInvariantsMismatch as v, errorSameSourceAndTarget as y };
+//# sourceMappingURL=errors-BS_Kq8GF.mjs.map

package/dist/{errors-CZ9JD4sd.mjs.map → errors-BS_Kq8GF.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-CZ9JD4sd.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { basename, dirname, relative } from 'pathe';\n\n/**\n * Build the canonical \"re-emit this package\" remediation hint.\n *\n * Every on-disk migration package ships its own `migration.ts` author-time\n * file. Running it regenerates `migration.json` and `ops.json` with the\n * correct hash + metadata, so it is the right primitive whenever a single\n * package's on-disk artifacts are missing, malformed, or otherwise corrupt.\n * Pointing users at `migration plan` would emit a *new* package rather than\n * heal the broken one.\n */\nfunction reemitHint(dir: string, fallback?: string): string {\n  const relativeDir = relative(process.cwd(), dir);\n  const reemit = `Re-emit the package by running \\`node \"${relativeDir}/migration.ts\"\\``;\n  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;\n}\n\n/**\n * Structured error for migration tooling operations.\n *\n * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under\n * the MIGRATION namespace. These are tooling-time errors (file I/O, hash\n * verification, migration history reconstruction), distinct from the runtime\n * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,\n * etc.).\n *\n * Fields:\n * - code:     Stable machine-readable code (MIGRATION.SUBCODE)\n * - category: Always 'MIGRATION'\n * - why:      Explains the cause in plain language\n * - fix:      Actionable remediation step\n * - details:  Machine-readable structured data for agents\n */\nexport class MigrationToolsError extends Error {\n  readonly code: string;\n  readonly category = 'MIGRATION' as const;\n  readonly why: string;\n  readonly fix: string;\n  readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    code: string,\n    summary: string,\n    options: {\n      readonly why: string;\n      readonly fix: string;\n      readonly details?: Record<string, unknown>;\n    },\n  ) {\n    super(summary);\n    this.name = 'MigrationToolsError';\n    this.code = code;\n    this.why = options.why;\n    this.fix = options.fix;\n    this.details = options.details;\n  }\n\n  static is(error: unknown): error is MigrationToolsError {\n    if (!(error instanceof Error)) return false;\n    const candidate = error as MigrationToolsError;\n    return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';\n  }\n}\n\nexport function errorDirectoryExists(dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {\n    why: `The directory \"${dir}\" already exists. Each migration must have a unique directory.`,\n    fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',\n    details: { dir },\n  });\n}\n\nexport function errorMissingFile(file: string, dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {\n    why: `Expected \"${file}\" in \"${dir}\" but the file does not exist.`,\n    fix: reemitHint(\n      dir,\n      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n    ),\n    details: { file, dir },\n  });\n}\n\nexport function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {\n    why: `Failed to parse \"${filePath}\": ${parseError}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, parseError },\n  });\n}\n\nexport function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {\n    why: `Migration manifest at \"${filePath}\" is invalid: ${reason}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, reason },\n  });\n}\n\nexport function errorInvalidSlug(slug: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {\n    why: `The slug \"${slug}\" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,\n    fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',\n    details: { slug },\n  });\n}\n\nexport function errorInvalidDestName(destName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {\n    why: `The destination name \"${destName}\" must be a single path segment (no \"..\" or directory separators).`,\n    fix: 'Use a simple file name such as \"contract.json\" for each destination in the copy list.',\n    details: { destName },\n  });\n}\n\nexport function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {\n  const dirName = basename(dir);\n  return new MigrationToolsError(\n    'MIGRATION.SAME_SOURCE_AND_TARGET',\n    'Migration has same source and target',\n    {\n      why: `Migration \"${dirName}\" has from === to === \"${hash}\". A migration must transition between two different contract states.`,\n      fix: reemitHint(\n        dir,\n        'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n      ),\n      details: { dirName, hash },\n    },\n  );\n}\n\nexport function errorAmbiguousTarget(\n  branchTips: readonly string[],\n  context?: {\n    divergencePoint: string;\n    branches: readonly {\n      tip: string;\n      edges: readonly { dirName: string; from: string; to: string }[];\n    }[];\n  },\n): MigrationToolsError {\n  const divergenceInfo = context\n    ? `\\nDivergence point: ${context.divergencePoint}\\nBranches:\\n${context.branches.map((b) => `  → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\\n')}`\n    : '';\n  return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {\n    why: `The migration history has diverged into multiple branches: ${branchTips.join(', ')}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,\n    fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',\n    details: {\n      branchTips,\n      ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),\n    },\n  });\n}\n\nexport function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {\n    why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,\n    fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',\n    details: { nodes },\n  });\n}\n\nexport function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {\n    why: `refs.json at \"${refsPath}\" is invalid: ${reason}`,\n    fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',\n    details: { path: refsPath, reason },\n  });\n}\n\nexport function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {\n    why: `Ref file at \"${filePath}\" is invalid: ${reason}`,\n    fix: 'Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.',\n    details: { path: filePath, reason },\n  });\n}\n\nexport function errorInvalidRefName(refName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {\n    why: `Ref name \"${refName}\" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no \".\" or \"..\" segments).`,\n    fix: `Use a valid ref name (e.g., \"staging\", \"envs/production\").`,\n    details: { refName },\n  });\n}\n\nexport function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {\n    why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,\n    fix: 'Use --from <hash> to specify the planning origin explicitly.',\n    details: { reachableHashes },\n  });\n}\n\nexport function errorInvalidRefValue(value: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {\n    why: `Ref value \"${value}\" is not a valid contract hash. Values must be in the format \"sha256:<64 hex chars>\" or \"sha256:empty\".`,\n    fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',\n    details: { value },\n  });\n}\n\nexport function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_MIGRATION_HASH',\n    'Duplicate migrationHash in migration graph',\n    {\n      why: `Multiple migrations share migrationHash \"${migrationHash}\". Each migration must have a unique content-addressed identity.`,\n      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',\n      details: { migrationHash },\n    },\n  );\n}\n\nexport function errorMigrationHashMismatch(\n  dir: string,\n  storedHash: string,\n  computedHash: string,\n): MigrationToolsError {\n  // Render a cwd-relative path in the human-readable diagnostic so users\n  // running CLI commands from the project root see a familiar short path.\n  // Keep the absolute path in `details.dir` for machine consumers.\n  const relativeDir = relative(process.cwd(), dir);\n  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {\n    why: `Stored migrationHash \"${storedHash}\" does not match the recomputed hash \"${computedHash}\" for \"${relativeDir}\". The migration.json or ops.json has been edited or partially written since emit.`,\n    fix: reemitHint(dir, 'or restore the directory from version control.'),\n    details: { dir, storedHash, computedHash },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"errors-BS_Kq8GF.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { basename, dirname, relative } from 'pathe';\n\n/**\n * Build the canonical \"re-emit this package\" remediation hint.\n *\n * Every on-disk migration package ships its own `migration.ts` author-time\n * file. Running it regenerates `migration.json` and `ops.json` with the\n * correct hash + metadata, so it is the right primitive whenever a single\n * package's on-disk artifacts are missing, malformed, or otherwise corrupt.\n * Pointing users at `migration plan` would emit a *new* package rather than\n * heal the broken one.\n */\nfunction reemitHint(dir: string, fallback?: string): string {\n  const relativeDir = relative(process.cwd(), dir);\n  const reemit = `Re-emit the package by running \\`node \"${relativeDir}/migration.ts\"\\``;\n  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;\n}\n\n/**\n * Structured error for migration tooling operations.\n *\n * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under\n * the MIGRATION namespace. These are tooling-time errors (file I/O, hash\n * verification, migration history reconstruction), distinct from the runtime\n * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,\n * etc.).\n *\n * Fields:\n * - code:     Stable machine-readable code (MIGRATION.SUBCODE)\n * - category: Always 'MIGRATION'\n * - why:      Explains the cause in plain language\n * - fix:      Actionable remediation step\n * - details:  Machine-readable structured data for agents\n */\nexport class MigrationToolsError extends Error {\n  readonly code: string;\n  readonly category = 'MIGRATION' as const;\n  readonly why: string;\n  readonly fix: string;\n  readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    code: string,\n    summary: string,\n    options: {\n      readonly why: string;\n      readonly fix: string;\n      readonly details?: Record<string, unknown>;\n    },\n  ) {\n    super(summary);\n    this.name = 'MigrationToolsError';\n    this.code = code;\n    this.why = options.why;\n    this.fix = options.fix;\n    this.details = options.details;\n  }\n\n  static is(error: unknown): error is MigrationToolsError {\n    if (!(error instanceof Error)) return false;\n    const candidate = error as MigrationToolsError;\n    return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';\n  }\n}\n\nexport function errorDirectoryExists(dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {\n    why: `The directory \"${dir}\" already exists. Each migration must have a unique directory.`,\n    fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',\n    details: { dir },\n  });\n}\n\nexport function errorMissingFile(file: string, dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {\n    why: `Expected \"${file}\" in \"${dir}\" but the file does not exist.`,\n    fix: reemitHint(\n      dir,\n      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n    ),\n    details: { file, dir },\n  });\n}\n\nexport function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {\n    why: `Failed to parse \"${filePath}\": ${parseError}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, parseError },\n  });\n}\n\nexport function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {\n    why: `Migration manifest at \"${filePath}\" is invalid: ${reason}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, reason },\n  });\n}\n\nexport function errorInvalidSlug(slug: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {\n    why: `The slug \"${slug}\" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,\n    fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',\n    details: { slug },\n  });\n}\n\nexport function errorInvalidDestName(destName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {\n    why: `The destination name \"${destName}\" must be a single path segment (no \"..\" or directory separators).`,\n    fix: 'Use a simple file name such as \"contract.json\" for each destination in the copy list.',\n    details: { destName },\n  });\n}\n\nexport function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {\n  const dirName = basename(dir);\n  return new MigrationToolsError(\n    'MIGRATION.SAME_SOURCE_AND_TARGET',\n    'Migration has same source and target',\n    {\n      why: `Migration \"${dirName}\" has from === to === \"${hash}\". A migration must transition between two different contract states.`,\n      fix: reemitHint(\n        dir,\n        'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n      ),\n      details: { dirName, hash },\n    },\n  );\n}\n\nexport function errorAmbiguousTarget(\n  branchTips: readonly string[],\n  context?: {\n    divergencePoint: string;\n    branches: readonly {\n      tip: string;\n      edges: readonly { dirName: string; from: string; to: string }[];\n    }[];\n  },\n): MigrationToolsError {\n  const divergenceInfo = context\n    ? `\\nDivergence point: ${context.divergencePoint}\\nBranches:\\n${context.branches.map((b) => `  → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\\n')}`\n    : '';\n  return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {\n    why: `The migration history has diverged into multiple branches: ${branchTips.join(', ')}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,\n    fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',\n    details: {\n      branchTips,\n      ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),\n    },\n  });\n}\n\nexport function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {\n    why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,\n    fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',\n    details: { nodes },\n  });\n}\n\nexport function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {\n    why: `refs.json at \"${refsPath}\" is invalid: ${reason}`,\n    fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',\n    details: { path: refsPath, reason },\n  });\n}\n\nexport function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {\n    why: `Ref file at \"${filePath}\" is invalid: ${reason}`,\n    fix: 'Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.',\n    details: { path: filePath, reason },\n  });\n}\n\nexport function errorInvalidRefName(refName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {\n    why: `Ref name \"${refName}\" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no \".\" or \"..\" segments).`,\n    fix: `Use a valid ref name (e.g., \"staging\", \"envs/production\").`,\n    details: { refName },\n  });\n}\n\nexport function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {\n    why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,\n    fix: 'Use --from <hash> to specify the planning origin explicitly.',\n    details: { reachableHashes },\n  });\n}\n\nexport function errorInvalidRefValue(value: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {\n    why: `Ref value \"${value}\" is not a valid contract hash. Values must be in the format \"sha256:<64 hex chars>\" or \"sha256:empty\".`,\n    fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',\n    details: { value },\n  });\n}\n\nexport function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_MIGRATION_HASH',\n    'Duplicate migrationHash in migration graph',\n    {\n      why: `Multiple migrations share migrationHash \"${migrationHash}\". Each migration must have a unique content-addressed identity.`,\n      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',\n      details: { migrationHash },\n    },\n  );\n}\n\nexport function errorInvalidInvariantId(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {\n    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,\n    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".',\n    details: { invariantId },\n  });\n}\n\nexport function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',\n    'Duplicate invariantId on a single migration',\n    {\n      why: `invariantId \"${invariantId}\" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,\n      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',\n      details: { invariantId },\n    },\n  );\n}\n\nexport function errorProvidedInvariantsMismatch(\n  filePath: string,\n  stored: readonly string[],\n  derived: readonly string[],\n): MigrationToolsError {\n  const storedSet = new Set(stored);\n  const derivedSet = new Set(derived);\n  const missing = [...derivedSet].filter((id) => !storedSet.has(id));\n  const extra = [...storedSet].filter((id) => !derivedSet.has(id));\n  // When sets agree but arrays don't, the only difference is ordering — call\n  // it out so the reader doesn't stare at two visually-identical arrays.\n  // Canonical providedInvariants is sorted ascending; a manifest with the\n  // same ids in a different order is still a mismatch (the hash check would\n  // also fail), but the human-readable diagnostic is otherwise unhelpful.\n  const orderingOnly = missing.length === 0 && extra.length === 0;\n  const why = orderingOnly\n    ? `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`\n    : `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;\n  return new MigrationToolsError(\n    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',\n    'providedInvariants on migration.json disagrees with ops.json',\n    {\n      why,\n      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n      details: { filePath, stored, derived, difference: { missing, extra } },\n    },\n  );\n}\n\nexport function errorMigrationHashMismatch(\n  dir: string,\n  storedHash: string,\n  computedHash: string,\n): MigrationToolsError {\n  // Render a cwd-relative path in the human-readable diagnostic so users\n  // running CLI commands from the project root see a familiar short path.\n  // Keep the absolute path in `details.dir` for machine consumers.\n  const relativeDir = relative(process.cwd(), dir);\n  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {\n    why: `Stored migrationHash \"${storedHash}\" does not match the recomputed hash \"${computedHash}\" for \"${relativeDir}\". The migration.json or ops.json has been edited or partially written since emit.`,\n    fix: reemitHint(dir, 'or restore the directory from version control.'),\n    details: { dir, storedHash, computedHash },\n  });\n}\n"],"mappings":"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"}

package/dist/exports/constants.mjs

@@ -1,3 +1,3 @@
-import { t as EMPTY_CONTRACT_HASH } from "../constants-WVGVMOdu.mjs";
+import { t as EMPTY_CONTRACT_HASH } from "../constants-DOzBI2EP.mjs";
 
 export { EMPTY_CONTRACT_HASH };

package/dist/exports/errors.mjs

@@ -1,3 +1,3 @@
-import { t as MigrationToolsError } from "../errors-CZ9JD4sd.mjs";
+import { t as MigrationToolsError } from "../errors-BS_Kq8GF.mjs";
 
 export { MigrationToolsError };

package/dist/exports/graph.d.mts

@@ -1,2 +1,2 @@
-import { n as MigrationGraph, t as MigrationEdge } from "../graph-B5wbCSna.mjs";
+import { n as MigrationGraph, t as MigrationEdge } from "../graph-coc0V7k2.mjs";
 export { type MigrationEdge, type MigrationGraph };

package/dist/exports/hash.d.mts

@@ -1,5 +1,5 @@
-import { n as MigrationMetadata } from "../metadata-DDa5L-uD.mjs";
-import { n as MigrationPackage, t as MigrationOps } from "../package-BJ5KAEcD.mjs";
+import { n as MigrationMetadata } from "../metadata-CdSwaQ2k.mjs";
+import { n as MigrationPackage, t as MigrationOps } from "../package-DFjGigEm.mjs";
 
 //#region src/hash.d.ts
 interface VerifyResult {

package/dist/exports/hash.mjs

@@ -1,3 +1,3 @@
-import { n as verifyMigrationHash, t as computeMigrationHash } from "../hash-BNWumjn7.mjs";
+import { n as verifyMigrationHash, t as computeMigrationHash } from "../hash-BARZdVgW.mjs";
 
 export { computeMigrationHash, verifyMigrationHash };

package/dist/exports/invariants.d.mts

@@ -0,0 +1,24 @@
+import { t as MigrationOps } from "../package-DFjGigEm.mjs";
+
+//#region src/invariants.d.ts
+
+/**
+ * Hygiene check for `invariantId`. Rejects empty values plus any
+ * whitespace or control character (including Unicode whitespace like
+ * NBSP and em space, which are visually identical to ASCII space and
+ * routinely sneak in via paste).
+ */
+declare function validateInvariantId(invariantId: string): boolean;
+/**
+ * Walk a migration's operations and produce its `providedInvariants`
+ * aggregate: the sorted, deduplicated list of `invariantId`s declared
+ * by data-transform ops. Ops without `operationClass === 'data'` are
+ * skipped; data ops without an `invariantId` are skipped.
+ *
+ * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+ * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+ */
+declare function deriveProvidedInvariants(ops: MigrationOps): readonly string[];
+//#endregion
+export { deriveProvidedInvariants, validateInvariantId };
+//# sourceMappingURL=invariants.d.mts.map

package/dist/exports/invariants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.d.mts","names":[],"sources":["../../src/invariants.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AAcA;;;iBAdgB,mBAAA;;;;;;;;;;iBAcA,wBAAA,MAA8B"}

package/dist/exports/invariants.mjs

@@ -0,0 +1,4 @@
+import "../errors-BS_Kq8GF.mjs";
+import { n as validateInvariantId, t as deriveProvidedInvariants } from "../invariants-jlMTqh_Q.mjs";
+
+export { deriveProvidedInvariants, validateInvariantId };

package/dist/exports/io.d.mts

@@ -1,5 +1,5 @@
-import { n as MigrationMetadata } from "../metadata-DDa5L-uD.mjs";
-import { n as MigrationPackage, t as MigrationOps } from "../package-BJ5KAEcD.mjs";
+import { n as MigrationMetadata } from "../metadata-CdSwaQ2k.mjs";
+import { n as MigrationPackage, t as MigrationOps } from "../package-DFjGigEm.mjs";
 
 //#region src/io.d.ts
 declare function writeMigrationPackage(dir: string, metadata: MigrationMetadata, ops: MigrationOps): Promise<void>;

package/dist/exports/io.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.mts","names":[],"sources":["../../src/io.ts"],"sourcesContent":[],"mappings":";;;;iBA2DsB,qBAAA,wBAEV,wBACL,eACJ;;AAJH;;;;;AAiCA;AAaA;AAOA;AAIA;AAyEA;AAiCgB,iBAlIM,mBAAA,CAkI4B,OAAI,EAAA,MAAA,EAAA,KAAA,EAAA,SAAA;;;MA/HnD;iBAUmB,sBAAA,wBAEV,oBACT;iBAImB,iBAAA,mBAAoC,eAAe;iBAInD,oBAAA,eAAmC,QAAQ;iBAyE3C,iBAAA,0BAEnB,iBAAiB;iBA+BJ,sBAAA,YAAkC"}
+{"version":3,"file":"io.d.mts","names":[],"sources":["../../src/io.ts"],"sourcesContent":[],"mappings":";;;;iBA+DsB,qBAAA,wBAEV,wBACL,eACJ;;AAJH;;;;;AAiCA;AAaA;AAOA;AAIA;AA4FA;AAiCgB,iBArJM,mBAAA,CAqJ4B,OAAI,EAAA,MAAA,EAAA,KAAA,EAAA,SAAA;;;MAlJnD;iBAUmB,sBAAA,wBAEV,oBACT;iBAImB,iBAAA,mBAAoC,eAAe;iBAInD,oBAAA,eAAmC,QAAQ;iBA4F3C,iBAAA,0BAEnB,iBAAiB;iBA+BJ,sBAAA,YAAkC"}

package/dist/exports/io.mjs

@@ -1,5 +1,6 @@
-import { a as errorInvalidDestName, d as errorInvalidSlug, f as errorMigrationHashMismatch, o as errorInvalidJson, p as errorMissingFile, r as errorDirectoryExists, s as errorInvalidManifest } from "../errors-CZ9JD4sd.mjs";
-import { n as verifyMigrationHash } from "../hash-BNWumjn7.mjs";
+import { c as errorInvalidJson, h as errorMissingFile, l as errorInvalidManifest, m as errorMigrationHashMismatch, o as errorInvalidDestName, p as errorInvalidSlug, r as errorDirectoryExists, v as errorProvidedInvariantsMismatch } from "../errors-BS_Kq8GF.mjs";
+import { n as verifyMigrationHash } from "../hash-BARZdVgW.mjs";
+import { t as deriveProvidedInvariants } from "../invariants-jlMTqh_Q.mjs";
 import { basename, dirname, join } from "pathe";
 import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { type } from "arktype";
@@ -24,6 +25,7 @@ const MigrationMetadataSchema = type({
 		plannerVersion: "string"
 	}),
 	labels: "string[]",
+	providedInvariants: "string[]",
 	"authorship?": type({
 		"author?": "string",
 		"email?": "string"
@@ -37,7 +39,8 @@ const MigrationMetadataSchema = type({
 const MigrationOpsSchema = type({
 	id: "string",
 	label: "string",
-	operationClass: "'additive' | 'widening' | 'destructive' | 'data'"
+	operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
+	"invariantId?": "string"
 }).array();
 async function writeMigrationPackage(dir, metadata, ops) {
 	await mkdir(dirname(dir), { recursive: true });
@@ -105,6 +108,8 @@ async function readMigrationPackage(dir) {
 	}
 	validateMetadata(metadata, manifestPath);
 	validateOps(ops, opsPath);
+	const derivedInvariants = deriveProvidedInvariants(ops);
+	if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) throw errorProvidedInvariantsMismatch(manifestPath, metadata.providedInvariants, derivedInvariants);
 	const pkg = {
 		dirName: basename(dir),
 		dirPath: dir,
@@ -115,6 +120,11 @@ async function readMigrationPackage(dir) {
 	if (!verification.ok) throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);
 	return pkg;
 }
+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;
+	return true;
+}
 function validateMetadata(metadata, filePath) {
 	const result = MigrationMetadataSchema(metadata);
 	if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);

package/dist/exports/io.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"io.mjs","names":["manifestRaw: string","opsRaw: string","metadata: MigrationMetadata","ops: MigrationOps","pkg: MigrationPackage","entries: string[]","packages: MigrationPackage[]"],"sources":["../../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { basename, dirname, join } from 'pathe';\nimport {\n  errorDirectoryExists,\n  errorInvalidDestName,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMigrationHashMismatch,\n  errorMissingFile,\n} from './errors';\nimport { verifyMigrationHash } from './hash';\nimport type { MigrationMetadata } from './metadata';\nimport type { MigrationOps, MigrationPackage } from './package';\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});\n\nconst MigrationMetadataSchema = type({\n  from: 'string',\n  to: 'string',\n  migrationHash: 'string',\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' | 'data'\",\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  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 * 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<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 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  const pkg: MigrationPackage = {\n    dirName: basename(dir),\n    dirPath: dir,\n    metadata,\n    ops,\n  };\n\n  const verification = verifyMigrationHash(pkg);\n  if (!verification.ok) {\n    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);\n  }\n\n  return pkg;\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\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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"}
+{"version":3,"file":"io.mjs","names":["manifestRaw: string","opsRaw: string","metadata: MigrationMetadata","ops: MigrationOps","pkg: MigrationPackage","entries: string[]","packages: MigrationPackage[]"],"sources":["../../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { basename, dirname, join } from 'pathe';\nimport {\n  errorDirectoryExists,\n  errorInvalidDestName,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMigrationHashMismatch,\n  errorMissingFile,\n  errorProvidedInvariantsMismatch,\n} from './errors';\nimport { verifyMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport type { MigrationMetadata } from './metadata';\nimport type { MigrationOps, MigrationPackage } from './package';\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});\n\nconst MigrationMetadataSchema = type({\n  from: 'string',\n  to: 'string',\n  migrationHash: 'string',\n  kind: \"'regular' | 'baseline'\",\n  fromContract: 'object | null',\n  toContract: 'object',\n  hints: MigrationHintsSchema,\n  labels: 'string[]',\n  providedInvariants: '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' | 'data'\",\n  'invariantId?': 'string',\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  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 * 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<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 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: MigrationPackage = {\n    dirName: basename(dir),\n    dirPath: dir,\n    metadata,\n    ops,\n  };\n\n  const verification = verifyMigrationHash(pkg);\n  if (!verification.ok) {\n    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);\n  }\n\n  return pkg;\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\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/exports/metadata.d.mts

@@ -1,2 +1,2 @@
-import { n as MigrationMetadata, t as MigrationHints } from "../metadata-DDa5L-uD.mjs";
+import { n as MigrationMetadata, t as MigrationHints } from "../metadata-CdSwaQ2k.mjs";
 export { type MigrationHints, type MigrationMetadata };

package/dist/exports/migration-graph.d.mts

@@ -1,5 +1,5 @@
-import { n as MigrationGraph, t as MigrationEdge } from "../graph-B5wbCSna.mjs";
-import { n as MigrationPackage } from "../package-BJ5KAEcD.mjs";
+import { n as MigrationGraph, t as MigrationEdge } from "../graph-coc0V7k2.mjs";
+import { n as MigrationPackage } from "../package-DFjGigEm.mjs";
 
 //#region src/migration-graph.d.ts
 declare function reconstructGraph(packages: readonly MigrationPackage[]): MigrationGraph;

package/dist/exports/migration-graph.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-graph.d.mts","names":[],"sources":["../../src/migration-graph.ts"],"sourcesContent":[],"mappings":";;;;iBA6BgB,gBAAA,oBAAoC,qBAAqB;;AAAzE;AAmFA;AAyCA;AAaA;AA8FA;AAkBA;AAwCA;AAQgB,iBAtNA,QAAA,CAsNoB,KAAA,EArN3B,cAqNyC,EAAA,QAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,SAlNtC,aAkNsC,EAAA,GAAA,IAAA;AA8DlC,UA3OC,YAAA,CA2OY;kCA1OK;;;;;;;;;;;iBAYlB,oBAAA,QACP,qEAIN;;;;;iBAyFa,mBAAA,QAA2B;;;;;;;;;iBAkB3B,QAAA,QAAgB;;;;;;iBAwChB,mBAAA,QAA2B,iBAAiB;iBAQ5C,YAAA,QAAoB;iBA8DpB,aAAA,QAAqB,0BAA0B"}
+{"version":3,"file":"migration-graph.d.mts","names":[],"sources":["../../src/migration-graph.ts"],"sourcesContent":[],"mappings":";;;;iBA6BgB,gBAAA,oBAAoC,qBAAqB;;AAAzE;AAoFA;AAyCA;AAaA;AA8FA;AAkBA;AAwCA;AAQgB,iBAtNA,QAAA,CAsNoB,KAAA,EArN3B,cAqNyC,EAAA,QAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,SAlNtC,aAkNsC,EAAA,GAAA,IAAA;AA8DlC,UA3OC,YAAA,CA2OY;kCA1OK;;;;;;;;;;;iBAYlB,oBAAA,QACP,qEAIN;;;;;iBAyFa,mBAAA,QAA2B;;;;;;;;;iBAkB3B,QAAA,QAAgB;;;;;;iBAwChB,mBAAA,QAA2B,iBAAiB;iBAQ5C,YAAA,QAAoB;iBA8DpB,aAAA,QAAqB,0BAA0B"}

package/dist/exports/migration-graph.mjs

@@ -1,5 +1,5 @@
-import { g as errorSameSourceAndTarget, h as errorNoTarget, i as errorDuplicateMigrationHash, m as errorNoInitialMigration, n as errorAmbiguousTarget } from "../errors-CZ9JD4sd.mjs";
-import { t as EMPTY_CONTRACT_HASH } from "../constants-WVGVMOdu.mjs";
+import { _ as errorNoTarget, a as errorDuplicateMigrationHash, g as errorNoInitialMigration, n as errorAmbiguousTarget, y as errorSameSourceAndTarget } from "../errors-BS_Kq8GF.mjs";
+import { t as EMPTY_CONTRACT_HASH } from "../constants-DOzBI2EP.mjs";
 import { ifDefined } from "@prisma-next/utils/defined";
 
 //#region src/queue.ts
@@ -118,7 +118,8 @@ function reconstructGraph(packages) {
 			migrationHash: pkg.metadata.migrationHash,
 			dirName: pkg.dirName,
 			createdAt: pkg.metadata.createdAt,
-			labels: pkg.metadata.labels
+			labels: pkg.metadata.labels,
+			invariants: pkg.metadata.providedInvariants
 		};
 		if (migrationByHash.has(migration.migrationHash)) throw errorDuplicateMigrationHash(migration.migrationHash);
 		migrationByHash.set(migration.migrationHash, migration);

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

@@ -1 +1 @@
-{"version":3,"file":"migration-graph.mjs","names":["migration: MigrationEdge","LABEL_PRIORITY: Record<string, number>","path: MigrationEdge[]","tieBreakReasons: string[]","leaves: string[]","cycles: string[][]","stack: Frame[]","cycle: string[]","startNodes: string[]","orphans: MigrationEdge[]"],"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 nodes — they were not\n * reached via any edge. For every other node they record the node and edge\n * by which this node was first reached.\n */\nexport interface BfsStep<E> {\n  readonly node: string;\n  readonly parent: string | 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 node 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 * Stops are intrinsic — callers `break` out of the `for..of` loop when\n * they've found what they're looking for.\n *\n * `ordering`, if provided, controls the order in which neighbours of each\n * node are enqueued. Only matters for path-finding: a deterministic ordering\n * makes BFS return a deterministic shortest path when multiple exist.\n */\nexport function* bfs<E>(\n  starts: Iterable<string>,\n  neighbours: (node: string) => Iterable<{ next: string; edge: E }>,\n  ordering?: (items: readonly { next: string; edge: E }[]) => readonly { next: string; edge: E }[],\n): Generator<BfsStep<E>> {\n  const visited = new Set<string>();\n  const parentMap = new Map<string, { parent: string; edge: E }>();\n  const queue = new Queue<string>();\n  for (const start of starts) {\n    if (!visited.has(start)) {\n      visited.add(start);\n      queue.push(start);\n    }\n  }\n  while (!queue.isEmpty) {\n    const current = queue.shift();\n    const parentInfo = parentMap.get(current);\n    yield {\n      node: current,\n      parent: parentInfo?.parent ?? null,\n      incomingEdge: parentInfo?.edge ?? null,\n    };\n\n    const items = neighbours(current);\n    const toVisit = ordering ? ordering([...items]) : items;\n    for (const { next, edge } of toVisit) {\n      if (!visited.has(next)) {\n        visited.add(next);\n        parentMap.set(next, { parent: current, edge });\n        queue.push(next);\n      }\n    }\n  }\n}\n","import { ifDefined } from '@prisma-next/utils/defined';\nimport { EMPTY_CONTRACT_HASH } from './constants';\nimport {\n  errorAmbiguousTarget,\n  errorDuplicateMigrationHash,\n  errorNoInitialMigration,\n  errorNoTarget,\n  errorSameSourceAndTarget,\n} from './errors';\nimport type { MigrationEdge, MigrationGraph } from './graph';\nimport { bfs } from './graph-ops';\nimport type { MigrationPackage } from './package';\n\n/** Forward-edge neighbours for BFS: 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/** Reverse-edge neighbours for BFS: 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 MigrationPackage[]): 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    const { from, to } = pkg.metadata;\n\n    if (from === to) {\n      throw errorSameSourceAndTarget(pkg.dirPath, from);\n    }\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      labels: pkg.metadata.labels,\n    };\n\n    if (migrationByHash.has(migration.migrationHash)) {\n      throw errorDuplicateMigrationHash(migration.migrationHash);\n    }\n    migrationByHash.set(migration.migrationHash, migration);\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 `findPath` and `findPathWithDecision` only; not a general-purpose\n// utility. Ordering: label priority → createdAt → to → migrationHash.\n// ---------------------------------------------------------------------------\n\nconst LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };\n\nfunction labelPriority(labels: readonly string[]): number {\n  let best = 3;\n  for (const l of labels) {\n    const p = LABEL_PRIORITY[l];\n    if (p !== undefined && p < best) best = p;\n  }\n  return best;\n}\n\nfunction compareTieBreak(a: MigrationEdge, b: MigrationEdge): number {\n  const lp = labelPriority(a.labels) - labelPriority(b.labels);\n  if (lp !== 0) return lp;\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/** Ordering adapter for `bfs` — sorts `{next, edge}` pairs by tie-break. */\nfunction bfsOrdering(\n  items: readonly { next: string; edge: MigrationEdge }[],\n): readonly { next: string; edge: MigrationEdge }[] {\n  return items.slice().sort((a, b) => compareTieBreak(a.edge, b.edge));\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 * label priority → 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) => forwardNeighbours(graph, n), bfsOrdering)) {\n    if (step.parent !== null && step.incomingEdge !== null) {\n      parents.set(step.node, { parent: step.parent, edge: step.incomingEdge });\n    }\n    if (step.node === 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 * 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.node);\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}\n\n/**\n * Find the shortest path from `fromHash` to `toHash` and return structured\n * path-decision metadata for machine-readable output.\n */\nexport function findPathWithDecision(\n  graph: MigrationGraph,\n  fromHash: string,\n  toHash: string,\n  refName?: string,\n): PathDecision | null {\n  if (fromHash === toHash) {\n    return {\n      selectedPath: [],\n      fromHash,\n      toHash,\n      alternativeCount: 0,\n      tieBreakReasons: [],\n      ...ifDefined('refName', refName),\n    };\n  }\n\n  const path = findPath(graph, fromHash, toHash);\n  if (!path) return null;\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\n  const tieBreakReasons: string[] = [];\n  let alternativeCount = 0;\n\n  for (const edge of path) {\n    const outgoing = graph.forwardChain.get(edge.from);\n    if (outgoing && outgoing.length > 1) {\n      const reachable = outgoing.filter((e) => reachesTarget.has(e.to));\n      if (reachable.length > 1) {\n        alternativeCount += reachable.length - 1;\n        const sorted = sortedNeighbors(reachable);\n        if (sorted[0] && sorted[0].migrationHash === edge.migrationHash) {\n          if (reachable.some((e) => e.migrationHash !== edge.migrationHash)) {\n            tieBreakReasons.push(\n              `at ${edge.from}: ${reachable.length} candidates, selected by tie-break`,\n            );\n          }\n        }\n      }\n    }\n  }\n\n  return {\n    selectedPath: path,\n    fromHash,\n    toHash,\n    alternativeCount,\n    tieBreakReasons,\n    ...ifDefined('refName', refName),\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.node);\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.node)?.length) {\n      leaves.push(step.node);\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.node);\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":";;;;;;;;;;;;;;AASA,IAAa,QAAb,MAAsB;CACpB,AAAiB;CACjB,AAAQ,OAAO;CAEf,YAAY,UAAuB,EAAE,EAAE;AACrC,OAAK,QAAQ,CAAC,GAAG,QAAQ;;CAG3B,KAAK,MAAe;AAClB,OAAK,MAAM,KAAK,KAAK;;;;;;CAOvB,QAAW;AACT,MAAI,KAAK,QAAQ,KAAK,MAAM,OAC1B,OAAM,IAAI,MAAM,oCAAoC;AAGtD,SAAO,KAAK,MAAM,KAAK;;CAGzB,IAAI,UAAmB;AACrB,SAAO,KAAK,QAAQ,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;ACHnC,UAAiB,IACf,QACA,YACA,UACuB;CACvB,MAAM,0BAAU,IAAI,KAAa;CACjC,MAAM,4BAAY,IAAI,KAA0C;CAChE,MAAM,QAAQ,IAAI,OAAe;AACjC,MAAK,MAAM,SAAS,OAClB,KAAI,CAAC,QAAQ,IAAI,MAAM,EAAE;AACvB,UAAQ,IAAI,MAAM;AAClB,QAAM,KAAK,MAAM;;AAGrB,QAAO,CAAC,MAAM,SAAS;EACrB,MAAM,UAAU,MAAM,OAAO;EAC7B,MAAM,aAAa,UAAU,IAAI,QAAQ;AACzC,QAAM;GACJ,MAAM;GACN,QAAQ,YAAY,UAAU;GAC9B,cAAc,YAAY,QAAQ;GACnC;EAED,MAAM,QAAQ,WAAW,QAAQ;EACjC,MAAM,UAAU,WAAW,SAAS,CAAC,GAAG,MAAM,CAAC,GAAG;AAClD,OAAK,MAAM,EAAE,MAAM,UAAU,QAC3B,KAAI,CAAC,QAAQ,IAAI,KAAK,EAAE;AACtB,WAAQ,IAAI,KAAK;AACjB,aAAU,IAAI,MAAM;IAAE,QAAQ;IAAS;IAAM,CAAC;AAC9C,SAAM,KAAK,KAAK;;;;;;;;AC9CxB,SAAS,kBAAkB,OAAuB,MAAc;AAC9D,SAAQ,MAAM,aAAa,IAAI,KAAK,IAAI,EAAE,EAAE,KAAK,UAAU;EAAE,MAAM,KAAK;EAAI;EAAM,EAAE;;;AAItF,SAAS,kBAAkB,OAAuB,MAAc;AAC9D,SAAQ,MAAM,aAAa,IAAI,KAAK,IAAI,EAAE,EAAE,KAAK,UAAU;EAAE,MAAM,KAAK;EAAM;EAAM,EAAE;;AAGxF,SAAS,WAAW,KAAmC,KAAa,OAA4B;CAC9F,MAAM,SAAS,IAAI,IAAI,IAAI;AAC3B,KAAI,OAAQ,QAAO,KAAK,MAAM;KACzB,KAAI,IAAI,KAAK,CAAC,MAAM,CAAC;;AAG5B,SAAgB,iBAAiB,UAAuD;CACtF,MAAM,wBAAQ,IAAI,KAAa;CAC/B,MAAM,+BAAe,IAAI,KAA8B;CACvD,MAAM,+BAAe,IAAI,KAA8B;CACvD,MAAM,kCAAkB,IAAI,KAA4B;AAExD,MAAK,MAAM,OAAO,UAAU;EAC1B,MAAM,EAAE,MAAM,OAAO,IAAI;AAEzB,MAAI,SAAS,GACX,OAAM,yBAAyB,IAAI,SAAS,KAAK;AAGnD,QAAM,IAAI,KAAK;AACf,QAAM,IAAI,GAAG;EAEb,MAAMA,YAA2B;GAC/B;GACA;GACA,eAAe,IAAI,SAAS;GAC5B,SAAS,IAAI;GACb,WAAW,IAAI,SAAS;GACxB,QAAQ,IAAI,SAAS;GACtB;AAED,MAAI,gBAAgB,IAAI,UAAU,cAAc,CAC9C,OAAM,4BAA4B,UAAU,cAAc;AAE5D,kBAAgB,IAAI,UAAU,eAAe,UAAU;AAEvD,aAAW,cAAc,MAAM,UAAU;AACzC,aAAW,cAAc,IAAI,UAAU;;AAGzC,QAAO;EAAE;EAAO;EAAc;EAAc;EAAiB;;AAS/D,MAAMC,iBAAyC;CAAE,MAAM;CAAG,SAAS;CAAG,SAAS;CAAG;AAElF,SAAS,cAAc,QAAmC;CACxD,IAAI,OAAO;AACX,MAAK,MAAM,KAAK,QAAQ;EACtB,MAAM,IAAI,eAAe;AACzB,MAAI,MAAM,UAAa,IAAI,KAAM,QAAO;;AAE1C,QAAO;;AAGT,SAAS,gBAAgB,GAAkB,GAA0B;CACnE,MAAM,KAAK,cAAc,EAAE,OAAO,GAAG,cAAc,EAAE,OAAO;AAC5D,KAAI,OAAO,EAAG,QAAO;CACrB,MAAM,KAAK,EAAE,UAAU,cAAc,EAAE,UAAU;AACjD,KAAI,OAAO,EAAG,QAAO;CACrB,MAAM,KAAK,EAAE,GAAG,cAAc,EAAE,GAAG;AACnC,KAAI,OAAO,EAAG,QAAO;AACrB,QAAO,EAAE,cAAc,cAAc,EAAE,cAAc;;AAGvD,SAAS,gBAAgB,OAA2D;AAClF,QAAO,CAAC,GAAG,MAAM,CAAC,KAAK,gBAAgB;;;AAIzC,SAAS,YACP,OACkD;AAClD,QAAO,MAAM,OAAO,CAAC,MAAM,GAAG,MAAM,gBAAgB,EAAE,MAAM,EAAE,KAAK,CAAC;;;;;;;;;;AAWtE,SAAgB,SACd,OACA,UACA,QACiC;AACjC,KAAI,aAAa,OAAQ,QAAO,EAAE;CAElC,MAAM,0BAAU,IAAI,KAAsD;AAC1E,MAAK,MAAM,QAAQ,IAAI,CAAC,SAAS,GAAG,MAAM,kBAAkB,OAAO,EAAE,EAAE,YAAY,EAAE;AACnF,MAAI,KAAK,WAAW,QAAQ,KAAK,iBAAiB,KAChD,SAAQ,IAAI,KAAK,MAAM;GAAE,QAAQ,KAAK;GAAQ,MAAM,KAAK;GAAc,CAAC;AAE1E,MAAI,KAAK,SAAS,QAAQ;GACxB,MAAMC,OAAwB,EAAE;GAChC,IAAI,MAAM;GACV,IAAI,IAAI,QAAQ,IAAI,IAAI;AACxB,UAAO,GAAG;AACR,SAAK,KAAK,EAAE,KAAK;AACjB,UAAM,EAAE;AACR,QAAI,QAAQ,IAAI,IAAI;;AAEtB,QAAK,SAAS;AACd,UAAO;;;AAIX,QAAO;;;;;;AAOT,SAAS,2BAA2B,OAAuB,QAA6B;CACtF,MAAM,0BAAU,IAAI,KAAa;AACjC,MAAK,MAAM,QAAQ,IAAI,CAAC,OAAO,GAAG,MAAM,kBAAkB,OAAO,EAAE,CAAC,CAClE,SAAQ,IAAI,KAAK,KAAK;AAExB,QAAO;;;;;;AAgBT,SAAgB,qBACd,OACA,UACA,QACA,SACqB;AACrB,KAAI,aAAa,OACf,QAAO;EACL,cAAc,EAAE;EAChB;EACA;EACA,kBAAkB;EAClB,iBAAiB,EAAE;EACnB,GAAG,UAAU,WAAW,QAAQ;EACjC;CAGH,MAAM,OAAO,SAAS,OAAO,UAAU,OAAO;AAC9C,KAAI,CAAC,KAAM,QAAO;CAKlB,MAAM,gBAAgB,2BAA2B,OAAO,OAAO;CAE/D,MAAMC,kBAA4B,EAAE;CACpC,IAAI,mBAAmB;AAEvB,MAAK,MAAM,QAAQ,MAAM;EACvB,MAAM,WAAW,MAAM,aAAa,IAAI,KAAK,KAAK;AAClD,MAAI,YAAY,SAAS,SAAS,GAAG;GACnC,MAAM,YAAY,SAAS,QAAQ,MAAM,cAAc,IAAI,EAAE,GAAG,CAAC;AACjE,OAAI,UAAU,SAAS,GAAG;AACxB,wBAAoB,UAAU,SAAS;IACvC,MAAM,SAAS,gBAAgB,UAAU;AACzC,QAAI,OAAO,MAAM,OAAO,GAAG,kBAAkB,KAAK,eAChD;SAAI,UAAU,MAAM,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAC/D,iBAAgB,KACd,MAAM,KAAK,KAAK,IAAI,UAAU,OAAO,oCACtC;;;;;AAOX,QAAO;EACL,cAAc;EACd;EACA;EACA;EACA;EACA,GAAG,UAAU,WAAW,QAAQ;EACjC;;;;;;AAOH,SAAS,oBACP,OACA,UACA,QACQ;CACR,MAAM,eAAe,OAAO,KAAK,SAAS;EACxC,MAAM,4BAAY,IAAI,KAAa;AACnC,OAAK,MAAM,QAAQ,IAAI,CAAC,KAAK,GAAG,MAAM,kBAAkB,OAAO,EAAE,CAAC,CAChE,WAAU,IAAI,KAAK,KAAK;AAE1B,SAAO;GACP;CAEF,MAAM,kBAAkB,CAAC,GAAI,aAAa,MAAM,EAAE,CAAE,CAAC,QAAQ,SAC3D,aAAa,OAAO,MAAM,EAAE,IAAI,KAAK,CAAC,CACvC;CAED,IAAI,UAAU;CACd,IAAI,eAAe;AACnB,MAAK,MAAM,YAAY,iBAAiB;EACtC,MAAM,OAAO,SAAS,OAAO,UAAU,SAAS;EAChD,MAAM,QAAQ,OAAO,KAAK,SAAS;AACnC,MAAI,QAAQ,cAAc;AACxB,kBAAe;AACf,aAAU;;;AAGd,QAAO;;;;;;AAOT,SAAgB,oBAAoB,OAAuB,UAAqC;CAC9F,MAAMC,SAAmB,EAAE;AAC3B,MAAK,MAAM,QAAQ,IAAI,CAAC,SAAS,GAAG,MAAM,kBAAkB,OAAO,EAAE,CAAC,CACpE,KAAI,CAAC,MAAM,aAAa,IAAI,KAAK,KAAK,EAAE,OACtC,QAAO,KAAK,KAAK,KAAK;AAG1B,QAAO;;;;;;;;;;AAWT,SAAgB,SAAS,OAAsC;AAC7D,KAAI,MAAM,MAAM,SAAS,EACvB,QAAO;AAGT,KAAI,CAAC,MAAM,MAAM,IAAI,oBAAoB,CACvC,OAAM,wBAAwB,CAAC,GAAG,MAAM,MAAM,CAAC;CAGjD,MAAM,SAAS,oBAAoB,OAAO,oBAAoB;AAE9D,KAAI,OAAO,WAAW,GAAG;EACvB,MAAM,YAAY,CAAC,GAAG,MAAM,MAAM,CAAC,QAAQ,MAAM,MAAM,oBAAoB;AAC3E,MAAI,UAAU,SAAS,EACrB,OAAM,cAAc,UAAU;AAEhC,SAAO;;AAGT,KAAI,OAAO,SAAS,GAAG;EACrB,MAAM,kBAAkB,oBAAoB,OAAO,qBAAqB,OAAO;AAQ/E,QAAM,qBAAqB,QAAQ;GAAE;GAAiB,UAPrC,OAAO,KAAK,QAAQ;AAEnC,WAAO;KACL;KACA,QAHW,SAAS,OAAO,iBAAiB,IAAI,IAGhC,EAAE,EAAE,KAAK,OAAO;MAAE,SAAS,EAAE;MAAS,MAAM,EAAE;MAAM,IAAI,EAAE;MAAI,EAAE;KACjF;KACD;GAC8D,CAAC;;AAInE,QAAO,OAAO;;;;;;;AAQhB,SAAgB,oBAAoB,OAA6C;CAC/E,MAAM,WAAW,SAAS,MAAM;AAChC,KAAI,aAAa,KAAM,QAAO;AAG9B,QADa,SAAS,OAAO,qBAAqB,SAAS,EAC9C,GAAG,GAAG,IAAI;;AAGzB,SAAgB,aAAa,OAA4C;CACvE,MAAM,QAAQ;CACd,MAAM,OAAO;CACb,MAAM,QAAQ;CAEd,MAAM,wBAAQ,IAAI,KAAqB;CACvC,MAAM,4BAAY,IAAI,KAA4B;CAClD,MAAMC,SAAqB,EAAE;AAE7B,MAAK,MAAM,QAAQ,MAAM,MACvB,OAAM,IAAI,MAAM,MAAM;CASxB,MAAMC,QAAiB,EAAE;CAEzB,SAAS,UAAU,GAAiB;AAClC,QAAM,IAAI,GAAG,KAAK;AAClB,QAAM,KAAK;GAAE,MAAM;GAAG,UAAU,MAAM,aAAa,IAAI,EAAE,IAAI,EAAE;GAAE,OAAO;GAAG,CAAC;;AAG9E,MAAK,MAAM,QAAQ,MAAM,OAAO;AAC9B,MAAI,MAAM,IAAI,KAAK,KAAK,MAAO;AAC/B,YAAU,IAAI,MAAM,KAAK;AACzB,YAAU,KAAK;AAEf,SAAO,MAAM,SAAS,GAAG;GAEvB,MAAM,QAAQ,MAAM,MAAM,SAAS;AACnC,OAAI,MAAM,SAAS,MAAM,SAAS,QAAQ;AACxC,UAAM,IAAI,MAAM,MAAM,MAAM;AAC5B,UAAM,KAAK;AACX;;GAIF,MAAM,IADO,MAAM,SAAS,MAAM,SACnB;GACf,MAAM,SAAS,MAAM,IAAI,EAAE;AAC3B,OAAI,WAAW,MAAM;IACnB,MAAMC,QAAkB,CAAC,EAAE;IAC3B,IAAI,MAAM,MAAM;AAChB,WAAO,QAAQ,GAAG;AAChB,WAAM,KAAK,IAAI;AACf,WAAM,UAAU,IAAI,IAAI,IAAI;;AAE9B,UAAM,SAAS;AACf,WAAO,KAAK,MAAM;cACT,WAAW,OAAO;AAC3B,cAAU,IAAI,GAAG,MAAM,KAAK;AAC5B,cAAU,EAAE;;;;AAKlB,QAAO;;AAGT,SAAgB,cAAc,OAAiD;AAC7E,KAAI,MAAM,MAAM,SAAS,EAAG,QAAO,EAAE;CAErC,MAAM,4BAAY,IAAI,KAAa;CACnC,MAAMC,aAAuB,EAAE;AAE/B,KAAI,MAAM,aAAa,IAAI,oBAAoB,CAC7C,YAAW,KAAK,oBAAoB;MAC/B;EACL,MAAM,6BAAa,IAAI,KAAa;AACpC,OAAK,MAAM,SAAS,MAAM,aAAa,QAAQ,CAC7C,MAAK,MAAM,QAAQ,MACjB,YAAW,IAAI,KAAK,GAAG;AAG3B,OAAK,MAAM,QAAQ,MAAM,MACvB,KAAI,CAAC,WAAW,IAAI,KAAK,CACvB,YAAW,KAAK,KAAK;;AAK3B,MAAK,MAAM,QAAQ,IAAI,aAAa,MAAM,kBAAkB,OAAO,EAAE,CAAC,CACpE,WAAU,IAAI,KAAK,KAAK;CAG1B,MAAMC,UAA2B,EAAE;AACnC,MAAK,MAAM,CAAC,MAAM,eAAe,MAAM,aACrC,KAAI,CAAC,UAAU,IAAI,KAAK,CACtB,SAAQ,KAAK,GAAG,WAAW;AAI/B,QAAO"}
+{"version":3,"file":"migration-graph.mjs","names":["migration: MigrationEdge","LABEL_PRIORITY: Record<string, number>","path: MigrationEdge[]","tieBreakReasons: string[]","leaves: string[]","cycles: string[][]","stack: Frame[]","cycle: string[]","startNodes: string[]","orphans: MigrationEdge[]"],"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 nodes — they were not\n * reached via any edge. For every other node they record the node and edge\n * by which this node was first reached.\n */\nexport interface BfsStep<E> {\n  readonly node: string;\n  readonly parent: string | 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 node 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 * Stops are intrinsic — callers `break` out of the `for..of` loop when\n * they've found what they're looking for.\n *\n * `ordering`, if provided, controls the order in which neighbours of each\n * node are enqueued. Only matters for path-finding: a deterministic ordering\n * makes BFS return a deterministic shortest path when multiple exist.\n */\nexport function* bfs<E>(\n  starts: Iterable<string>,\n  neighbours: (node: string) => Iterable<{ next: string; edge: E }>,\n  ordering?: (items: readonly { next: string; edge: E }[]) => readonly { next: string; edge: E }[],\n): Generator<BfsStep<E>> {\n  const visited = new Set<string>();\n  const parentMap = new Map<string, { parent: string; edge: E }>();\n  const queue = new Queue<string>();\n  for (const start of starts) {\n    if (!visited.has(start)) {\n      visited.add(start);\n      queue.push(start);\n    }\n  }\n  while (!queue.isEmpty) {\n    const current = queue.shift();\n    const parentInfo = parentMap.get(current);\n    yield {\n      node: current,\n      parent: parentInfo?.parent ?? null,\n      incomingEdge: parentInfo?.edge ?? null,\n    };\n\n    const items = neighbours(current);\n    const toVisit = ordering ? ordering([...items]) : items;\n    for (const { next, edge } of toVisit) {\n      if (!visited.has(next)) {\n        visited.add(next);\n        parentMap.set(next, { parent: current, edge });\n        queue.push(next);\n      }\n    }\n  }\n}\n","import { ifDefined } from '@prisma-next/utils/defined';\nimport { EMPTY_CONTRACT_HASH } from './constants';\nimport {\n  errorAmbiguousTarget,\n  errorDuplicateMigrationHash,\n  errorNoInitialMigration,\n  errorNoTarget,\n  errorSameSourceAndTarget,\n} from './errors';\nimport type { MigrationEdge, MigrationGraph } from './graph';\nimport { bfs } from './graph-ops';\nimport type { MigrationPackage } from './package';\n\n/** Forward-edge neighbours for BFS: 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/** Reverse-edge neighbours for BFS: 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 MigrationPackage[]): 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    const { from, to } = pkg.metadata;\n\n    if (from === to) {\n      throw errorSameSourceAndTarget(pkg.dirPath, from);\n    }\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      labels: pkg.metadata.labels,\n      invariants: pkg.metadata.providedInvariants,\n    };\n\n    if (migrationByHash.has(migration.migrationHash)) {\n      throw errorDuplicateMigrationHash(migration.migrationHash);\n    }\n    migrationByHash.set(migration.migrationHash, migration);\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 `findPath` and `findPathWithDecision` only; not a general-purpose\n// utility. Ordering: label priority → createdAt → to → migrationHash.\n// ---------------------------------------------------------------------------\n\nconst LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };\n\nfunction labelPriority(labels: readonly string[]): number {\n  let best = 3;\n  for (const l of labels) {\n    const p = LABEL_PRIORITY[l];\n    if (p !== undefined && p < best) best = p;\n  }\n  return best;\n}\n\nfunction compareTieBreak(a: MigrationEdge, b: MigrationEdge): number {\n  const lp = labelPriority(a.labels) - labelPriority(b.labels);\n  if (lp !== 0) return lp;\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/** Ordering adapter for `bfs` — sorts `{next, edge}` pairs by tie-break. */\nfunction bfsOrdering(\n  items: readonly { next: string; edge: MigrationEdge }[],\n): readonly { next: string; edge: MigrationEdge }[] {\n  return items.slice().sort((a, b) => compareTieBreak(a.edge, b.edge));\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 * label priority → 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) => forwardNeighbours(graph, n), bfsOrdering)) {\n    if (step.parent !== null && step.incomingEdge !== null) {\n      parents.set(step.node, { parent: step.parent, edge: step.incomingEdge });\n    }\n    if (step.node === 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 * 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.node);\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}\n\n/**\n * Find the shortest path from `fromHash` to `toHash` and return structured\n * path-decision metadata for machine-readable output.\n */\nexport function findPathWithDecision(\n  graph: MigrationGraph,\n  fromHash: string,\n  toHash: string,\n  refName?: string,\n): PathDecision | null {\n  if (fromHash === toHash) {\n    return {\n      selectedPath: [],\n      fromHash,\n      toHash,\n      alternativeCount: 0,\n      tieBreakReasons: [],\n      ...ifDefined('refName', refName),\n    };\n  }\n\n  const path = findPath(graph, fromHash, toHash);\n  if (!path) return null;\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\n  const tieBreakReasons: string[] = [];\n  let alternativeCount = 0;\n\n  for (const edge of path) {\n    const outgoing = graph.forwardChain.get(edge.from);\n    if (outgoing && outgoing.length > 1) {\n      const reachable = outgoing.filter((e) => reachesTarget.has(e.to));\n      if (reachable.length > 1) {\n        alternativeCount += reachable.length - 1;\n        const sorted = sortedNeighbors(reachable);\n        if (sorted[0] && sorted[0].migrationHash === edge.migrationHash) {\n          if (reachable.some((e) => e.migrationHash !== edge.migrationHash)) {\n            tieBreakReasons.push(\n              `at ${edge.from}: ${reachable.length} candidates, selected by tie-break`,\n            );\n          }\n        }\n      }\n    }\n  }\n\n  return {\n    selectedPath: path,\n    fromHash,\n    toHash,\n    alternativeCount,\n    tieBreakReasons,\n    ...ifDefined('refName', refName),\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.node);\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.node)?.length) {\n      leaves.push(step.node);\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.node);\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/exports/migration.d.mts

@@ -1,4 +1,4 @@
-import { n as MigrationMetadata } from "../metadata-DDa5L-uD.mjs";
+import { n as MigrationMetadata } from "../metadata-CdSwaQ2k.mjs";
 import { ControlStack, MigrationPlan, MigrationPlanOperation } from "@prisma-next/framework-components/control";
 
 //#region src/migration-base.d.ts

package/dist/exports/migration.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":[],"mappings":";;;;UAciB,aAAA;;EAAA,SAAA,EAAA,EAAA,MAAa;EAuBR,SAAA,IAAS,CAAA,EAAA,SAAA,GAAA,UAAA;EACV,SAAA,MAAA,CAAA,EAAA,SAAA,MAAA,EAAA;;;;;;;;;;;AAGK,uBAJJ,SAII,CAAA,mBAHL,sBAGK,GAHoB,sBAGpB,EAAA,kBAAA,MAAA,GAAA,MAAA,EAAA,kBAAA,MAAA,GAAA,MAAA,CAAA,YAAb,aAAa,CAAA;EAuDV,kBAAA,QAAkB,EAAA,MAAA;EAWlB;AA4BhB;AAyEA;;;;;;;4BA1J4B,aAAa,WAAW;sBAE9B,aAAa,WAAW;;;;;;;sCAUR;;;;;;uBAOf;;;;;;;;;;;;;;;iBAuBP,kBAAA;iBAWA,kBAAA,CAAA;;;;;;;;;;;;UA4BC,kBAAA;;qBAEI;;;;;;;;;;;;iBAuEL,uBAAA,WACJ,qBACA,QAAQ,4BACjB"}
+{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":[],"mappings":";;;;UAeiB,aAAA;;EAAA,SAAA,EAAA,EAAA,MAAa;EAuBR,SAAA,IAAS,CAAA,EAAA,SAAA,GAAA,UAAA;EACV,SAAA,MAAA,CAAA,EAAA,SAAA,MAAA,EAAA;;;;;;;;;;;AAGK,uBAJJ,SAII,CAAA,mBAHL,sBAGK,GAHoB,sBAGpB,EAAA,kBAAA,MAAA,GAAA,MAAA,EAAA,kBAAA,MAAA,GAAA,MAAA,CAAA,YAAb,aAAa,CAAA;EAuDV,kBAAA,QAAkB,EAAA,MAAA;EAWlB;AA4BhB;AA0EA;;;;;;;4BA3J4B,aAAa,WAAW;sBAE9B,aAAa,WAAW;;;;;;;sCAUR;;;;;;uBAOf;;;;;;;;;;;;;;;iBAuBP,kBAAA;iBAWA,kBAAA,CAAA;;;;;;;;;;;;UA4BC,kBAAA;;qBAEI;;;;;;;;;;;;iBAwEL,uBAAA,WACJ,qBACA,QAAQ,4BACjB"}

package/dist/exports/migration.mjs

@@ -1,4 +1,6 @@
-import { t as computeMigrationHash } from "../hash-BNWumjn7.mjs";
+import "../errors-BS_Kq8GF.mjs";
+import { t as computeMigrationHash } from "../hash-BARZdVgW.mjs";
+import { t as deriveProvidedInvariants } from "../invariants-jlMTqh_Q.mjs";
 import { type } from "arktype";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { realpathSync } from "node:fs";
@@ -95,6 +97,7 @@ function buildAttestedMetadata(meta, ops, existing) {
 		to: meta.to,
 		kind: meta.kind ?? "regular",
 		labels: meta.labels ?? existing?.labels ?? [],
+		providedInvariants: deriveProvidedInvariants(ops),
 		createdAt: existing?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
 		fromContract: existing?.fromContract ?? null,
 		toContract: existing?.toContract ?? { storage: { storageHash: meta.to } },

package/dist/exports/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":["baseMetadata: Omit<MigrationMetadata, 'migrationHash'>"],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { realpathSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type {\n  ControlStack,\n  MigrationPlan,\n  MigrationPlanOperation,\n} from '@prisma-next/framework-components/control';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { type } from 'arktype';\nimport { computeMigrationHash } from './hash';\nimport type { MigrationHints, MigrationMetadata } from './metadata';\nimport type { MigrationOps } from './package';\n\nexport interface MigrationMeta {\n  readonly from: string;\n  readonly to: string;\n  readonly kind?: 'regular' | 'baseline';\n  readonly labels?: readonly string[];\n}\n\nconst MigrationMetaSchema = type({\n  from: 'string',\n  to: 'string',\n  'kind?': \"'regular' | 'baseline'\",\n  'labels?': type('string').array(),\n});\n\n/**\n * Base class for migrations.\n *\n * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the\n * runner can consume it directly via `targetId`, `operations`, `origin`, and\n * `destination`. The metadata-shaped inputs come from `describe()`, which\n * every migration must implement — `migration.json` is required for a\n * migration to be valid.\n */\nexport abstract class Migration<\n  TOperation extends MigrationPlanOperation = MigrationPlanOperation,\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> implements MigrationPlan\n{\n  abstract readonly targetId: string;\n\n  /**\n   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).\n   *\n   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their\n   * adapter once per instance. Optional at the abstract level so unit tests can\n   * construct `Migration` instances purely for `operations` / `describe`\n   * assertions without needing a real stack; concrete subclasses that need the\n   * stack at runtime should narrow the parameter to required.\n   */\n  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;\n\n  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {\n    this.stack = stack;\n  }\n\n  /**\n   * Ordered list of operations this migration performs.\n   *\n   * Implemented as a getter so that subclasses can either precompute the list\n   * in their constructor or build it lazily per access.\n   */\n  abstract get operations(): readonly TOperation[];\n\n  /**\n   * Metadata inputs used to build `migration.json` and to derive the plan's\n   * origin/destination identities. Every migration must provide this —\n   * omitting it would produce an invalid on-disk migration package.\n   */\n  abstract describe(): MigrationMeta;\n\n  get origin(): { readonly storageHash: string } | null {\n    const from = this.describe().from;\n    // An empty `from` represents a migration with no prior origin (e.g.\n    // initial baseline, or an in-process plan that was never persisted).\n    // Surface that as a null origin so runners treat the plan as\n    // origin-less rather than matching against an empty storage hash.\n    return from === '' ? null : { storageHash: from };\n  }\n\n  get destination(): { readonly storageHash: string } {\n    return { storageHash: this.describe().to };\n  }\n}\n\n/**\n * Returns true when `import.meta.url` resolves to the same file that was\n * invoked as the node entrypoint (`process.argv[1]`). Used by\n * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when\n * the migration module is being imported (e.g. by another script) rather\n * than executed directly.\n */\nexport function isDirectEntrypoint(importMetaUrl: string): boolean {\n  const metaFilename = fileURLToPath(importMetaUrl);\n  const argv1 = process.argv[1];\n  if (!argv1) return false;\n  try {\n    return realpathSync(metaFilename) === realpathSync(argv1);\n  } catch {\n    return false;\n  }\n}\n\nexport function printMigrationHelp(): void {\n  printHelp();\n}\n\nfunction printHelp(): void {\n  process.stdout.write(\n    [\n      'Usage: node <migration-file> [options]',\n      '',\n      'Options:',\n      '  --dry-run  Print operations to stdout without writing files',\n      '  --help     Show this help message',\n      '',\n    ].join('\\n'),\n  );\n}\n\n/**\n * In-memory artifacts produced from a `Migration` instance: the\n * serialized `ops.json` body, the `migration.json` metadata object, and\n * its serialized form. Returned by `buildMigrationArtifacts` so callers\n * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can\n * decide how to persist them — write to disk, print in dry-run, ship\n * over the wire — without coupling artifact construction to file I/O.\n *\n * `metadataJson` is `JSON.stringify(metadata, null, 2)` — the canonical\n * on-disk shape that the arktype loader-schema in `./io` validates.\n */\nexport interface MigrationArtifacts {\n  readonly opsJson: string;\n  readonly metadata: MigrationMetadata;\n  readonly metadataJson: string;\n}\n\n/**\n * Build the attested metadata from `describe()`-derived metadata, the\n * operations list, and the previously-scaffolded metadata (if any).\n *\n * When a `migration.json` already exists for this package (the common\n * case: it was scaffolded by `migration plan`), preserve the contract\n * bookends, hints, labels, and `createdAt` set there — those fields are\n * owned by the CLI scaffolder, not the authored class. Only the\n * `describe()`-derived fields (`from`, `to`, `kind`) and the operations\n * change as the author iterates. When no metadata exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant record so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationHash` is recomputed against the current metadata + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedMetadata(\n  meta: MigrationMeta,\n  ops: MigrationOps,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationMetadata {\n  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {\n    from: meta.from,\n    to: meta.to,\n    kind: meta.kind ?? 'regular',\n    labels: meta.labels ?? existing?.labels ?? [],\n    createdAt: existing?.createdAt ?? new Date().toISOString(),\n    fromContract: existing?.fromContract ?? null,\n    // When no scaffolded metadata exists we synthesize a minimal contract\n    // stub so the package is still readable end-to-end. The cast is\n    // intentional: only the storage bookend matters for hash computation\n    // (everything else is stripped by `computeMigrationHash`), and a real\n    // contract bookend would only be available after `migration plan`.\n    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),\n    hints: normalizeHints(existing?.hints),\n    ...ifDefined('authorship', existing?.authorship),\n  };\n\n  const migrationHash = computeMigrationHash(baseMetadata, ops);\n  return { ...baseMetadata, migrationHash };\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in metadata scaffolded by older CLI\n * versions (e.g. `planningStrategy`). Picking fields explicitly instead of\n * spreading keeps refreshed `migration.json` files schema-clean regardless\n * of what was on disk before.\n */\nfunction normalizeHints(existing: MigrationHints | undefined): MigrationHints {\n  return {\n    used: existing?.used ?? [],\n    applied: existing?.applied ?? [],\n    plannerVersion: existing?.plannerVersion ?? '2.0.0',\n  };\n}\n\n/**\n * Pure conversion from a `Migration` instance (plus the previously\n * scaffolded metadata, when one exists on disk) to the in-memory\n * artifacts that downstream tooling persists. Owns metadata validation,\n * metadata synthesis/preservation, hint normalization, and the\n * content-addressed `migrationHash` computation, but performs no file I/O\n * — callers handle reads (to source `existing`) and writes (to persist\n * `opsJson` / `metadataJson`).\n */\nexport function buildMigrationArtifacts(\n  instance: Migration,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationArtifacts {\n  const ops = instance.operations;\n  if (!Array.isArray(ops)) {\n    throw new Error('operations must be an array');\n  }\n\n  const rawMeta: unknown = instance.describe();\n  const parsed = MigrationMetaSchema(rawMeta);\n  if (parsed instanceof type.errors) {\n    throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n  }\n\n  const metadata = buildAttestedMetadata(parsed, ops, existing);\n\n  return {\n    opsJson: JSON.stringify(ops, null, 2),\n    metadata,\n    metadataJson: JSON.stringify(metadata, null, 2),\n  };\n}\n"],"mappings":";;;;;;;AAqBA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,SAAS;CACT,WAAW,KAAK,SAAS,CAAC,OAAO;CAClC,CAAC;;;;;;;;;;AAWF,IAAsB,YAAtB,MAKA;;;;;;;;;;CAYE,AAAmB;CAEnB,YAAY,OAA4C;AACtD,OAAK,QAAQ;;CAkBf,IAAI,SAAkD;EACpD,MAAM,OAAO,KAAK,UAAU,CAAC;AAK7B,SAAO,SAAS,KAAK,OAAO,EAAE,aAAa,MAAM;;CAGnD,IAAI,cAAgD;AAClD,SAAO,EAAE,aAAa,KAAK,UAAU,CAAC,IAAI;;;;;;;;;;AAW9C,SAAgB,mBAAmB,eAAgC;CACjE,MAAM,eAAe,cAAc,cAAc;CACjD,MAAM,QAAQ,QAAQ,KAAK;AAC3B,KAAI,CAAC,MAAO,QAAO;AACnB,KAAI;AACF,SAAO,aAAa,aAAa,KAAK,aAAa,MAAM;SACnD;AACN,SAAO;;;AAIX,SAAgB,qBAA2B;AACzC,YAAW;;AAGb,SAAS,YAAkB;AACzB,SAAQ,OAAO,MACb;EACE;EACA;EACA;EACA;EACA;EACA;EACD,CAAC,KAAK,KAAK,CACb;;;;;;;;;;;;;;;;;;;AAqCH,SAAS,sBACP,MACA,KACA,UACmB;CACnB,MAAMA,eAAyD;EAC7D,MAAM,KAAK;EACX,IAAI,KAAK;EACT,MAAM,KAAK,QAAQ;EACnB,QAAQ,KAAK,UAAU,UAAU,UAAU,EAAE;EAC7C,WAAW,UAAU,8BAAa,IAAI,MAAM,EAAC,aAAa;EAC1D,cAAc,UAAU,gBAAgB;EAMxC,YAAY,UAAU,cAAe,EAAE,SAAS,EAAE,aAAa,KAAK,IAAI,EAAE;EAC1E,OAAO,eAAe,UAAU,MAAM;EACtC,GAAG,UAAU,cAAc,UAAU,WAAW;EACjD;CAED,MAAM,gBAAgB,qBAAqB,cAAc,IAAI;AAC7D,QAAO;EAAE,GAAG;EAAc;EAAe;;;;;;;;;AAU3C,SAAS,eAAe,UAAsD;AAC5E,QAAO;EACL,MAAM,UAAU,QAAQ,EAAE;EAC1B,SAAS,UAAU,WAAW,EAAE;EAChC,gBAAgB,UAAU,kBAAkB;EAC7C;;;;;;;;;;;AAYH,SAAgB,wBACd,UACA,UACoB;CACpB,MAAM,MAAM,SAAS;AACrB,KAAI,CAAC,MAAM,QAAQ,IAAI,CACrB,OAAM,IAAI,MAAM,8BAA8B;CAIhD,MAAM,SAAS,oBADU,SAAS,UAAU,CACD;AAC3C,KAAI,kBAAkB,KAAK,OACzB,OAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;CAG5E,MAAM,WAAW,sBAAsB,QAAQ,KAAK,SAAS;AAE7D,QAAO;EACL,SAAS,KAAK,UAAU,KAAK,MAAM,EAAE;EACrC;EACA,cAAc,KAAK,UAAU,UAAU,MAAM,EAAE;EAChD"}
+{"version":3,"file":"migration.mjs","names":["baseMetadata: Omit<MigrationMetadata, 'migrationHash'>"],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { realpathSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type {\n  ControlStack,\n  MigrationPlan,\n  MigrationPlanOperation,\n} from '@prisma-next/framework-components/control';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { type } from 'arktype';\nimport { computeMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport type { MigrationHints, MigrationMetadata } from './metadata';\nimport type { MigrationOps } from './package';\n\nexport interface MigrationMeta {\n  readonly from: string;\n  readonly to: string;\n  readonly kind?: 'regular' | 'baseline';\n  readonly labels?: readonly string[];\n}\n\nconst MigrationMetaSchema = type({\n  from: 'string',\n  to: 'string',\n  'kind?': \"'regular' | 'baseline'\",\n  'labels?': type('string').array(),\n});\n\n/**\n * Base class for migrations.\n *\n * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the\n * runner can consume it directly via `targetId`, `operations`, `origin`, and\n * `destination`. The metadata-shaped inputs come from `describe()`, which\n * every migration must implement — `migration.json` is required for a\n * migration to be valid.\n */\nexport abstract class Migration<\n  TOperation extends MigrationPlanOperation = MigrationPlanOperation,\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> implements MigrationPlan\n{\n  abstract readonly targetId: string;\n\n  /**\n   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).\n   *\n   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their\n   * adapter once per instance. Optional at the abstract level so unit tests can\n   * construct `Migration` instances purely for `operations` / `describe`\n   * assertions without needing a real stack; concrete subclasses that need the\n   * stack at runtime should narrow the parameter to required.\n   */\n  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;\n\n  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {\n    this.stack = stack;\n  }\n\n  /**\n   * Ordered list of operations this migration performs.\n   *\n   * Implemented as a getter so that subclasses can either precompute the list\n   * in their constructor or build it lazily per access.\n   */\n  abstract get operations(): readonly TOperation[];\n\n  /**\n   * Metadata inputs used to build `migration.json` and to derive the plan's\n   * origin/destination identities. Every migration must provide this —\n   * omitting it would produce an invalid on-disk migration package.\n   */\n  abstract describe(): MigrationMeta;\n\n  get origin(): { readonly storageHash: string } | null {\n    const from = this.describe().from;\n    // An empty `from` represents a migration with no prior origin (e.g.\n    // initial baseline, or an in-process plan that was never persisted).\n    // Surface that as a null origin so runners treat the plan as\n    // origin-less rather than matching against an empty storage hash.\n    return from === '' ? null : { storageHash: from };\n  }\n\n  get destination(): { readonly storageHash: string } {\n    return { storageHash: this.describe().to };\n  }\n}\n\n/**\n * Returns true when `import.meta.url` resolves to the same file that was\n * invoked as the node entrypoint (`process.argv[1]`). Used by\n * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when\n * the migration module is being imported (e.g. by another script) rather\n * than executed directly.\n */\nexport function isDirectEntrypoint(importMetaUrl: string): boolean {\n  const metaFilename = fileURLToPath(importMetaUrl);\n  const argv1 = process.argv[1];\n  if (!argv1) return false;\n  try {\n    return realpathSync(metaFilename) === realpathSync(argv1);\n  } catch {\n    return false;\n  }\n}\n\nexport function printMigrationHelp(): void {\n  printHelp();\n}\n\nfunction printHelp(): void {\n  process.stdout.write(\n    [\n      'Usage: node <migration-file> [options]',\n      '',\n      'Options:',\n      '  --dry-run  Print operations to stdout without writing files',\n      '  --help     Show this help message',\n      '',\n    ].join('\\n'),\n  );\n}\n\n/**\n * In-memory artifacts produced from a `Migration` instance: the\n * serialized `ops.json` body, the `migration.json` metadata object, and\n * its serialized form. Returned by `buildMigrationArtifacts` so callers\n * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can\n * decide how to persist them — write to disk, print in dry-run, ship\n * over the wire — without coupling artifact construction to file I/O.\n *\n * `metadataJson` is `JSON.stringify(metadata, null, 2)` — the canonical\n * on-disk shape that the arktype loader-schema in `./io` validates.\n */\nexport interface MigrationArtifacts {\n  readonly opsJson: string;\n  readonly metadata: MigrationMetadata;\n  readonly metadataJson: string;\n}\n\n/**\n * Build the attested metadata from `describe()`-derived metadata, the\n * operations list, and the previously-scaffolded metadata (if any).\n *\n * When a `migration.json` already exists for this package (the common\n * case: it was scaffolded by `migration plan`), preserve the contract\n * bookends, hints, labels, and `createdAt` set there — those fields are\n * owned by the CLI scaffolder, not the authored class. Only the\n * `describe()`-derived fields (`from`, `to`, `kind`) and the operations\n * change as the author iterates. When no metadata exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant record so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationHash` is recomputed against the current metadata + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedMetadata(\n  meta: MigrationMeta,\n  ops: MigrationOps,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationMetadata {\n  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {\n    from: meta.from,\n    to: meta.to,\n    kind: meta.kind ?? 'regular',\n    labels: meta.labels ?? existing?.labels ?? [],\n    providedInvariants: deriveProvidedInvariants(ops),\n    createdAt: existing?.createdAt ?? new Date().toISOString(),\n    fromContract: existing?.fromContract ?? null,\n    // When no scaffolded metadata exists we synthesize a minimal contract\n    // stub so the package is still readable end-to-end. The cast is\n    // intentional: only the storage bookend matters for hash computation\n    // (everything else is stripped by `computeMigrationHash`), and a real\n    // contract bookend would only be available after `migration plan`.\n    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),\n    hints: normalizeHints(existing?.hints),\n    ...ifDefined('authorship', existing?.authorship),\n  };\n\n  const migrationHash = computeMigrationHash(baseMetadata, ops);\n  return { ...baseMetadata, migrationHash };\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in metadata scaffolded by older CLI\n * versions (e.g. `planningStrategy`). Picking fields explicitly instead of\n * spreading keeps refreshed `migration.json` files schema-clean regardless\n * of what was on disk before.\n */\nfunction normalizeHints(existing: MigrationHints | undefined): MigrationHints {\n  return {\n    used: existing?.used ?? [],\n    applied: existing?.applied ?? [],\n    plannerVersion: existing?.plannerVersion ?? '2.0.0',\n  };\n}\n\n/**\n * Pure conversion from a `Migration` instance (plus the previously\n * scaffolded metadata, when one exists on disk) to the in-memory\n * artifacts that downstream tooling persists. Owns metadata validation,\n * metadata synthesis/preservation, hint normalization, and the\n * content-addressed `migrationHash` computation, but performs no file I/O\n * — callers handle reads (to source `existing`) and writes (to persist\n * `opsJson` / `metadataJson`).\n */\nexport function buildMigrationArtifacts(\n  instance: Migration,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationArtifacts {\n  const ops = instance.operations;\n  if (!Array.isArray(ops)) {\n    throw new Error('operations must be an array');\n  }\n\n  const rawMeta: unknown = instance.describe();\n  const parsed = MigrationMetaSchema(rawMeta);\n  if (parsed instanceof type.errors) {\n    throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n  }\n\n  const metadata = buildAttestedMetadata(parsed, ops, existing);\n\n  return {\n    opsJson: JSON.stringify(ops, null, 2),\n    metadata,\n    metadataJson: JSON.stringify(metadata, null, 2),\n  };\n}\n"],"mappings":";;;;;;;;;AAsBA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,SAAS;CACT,WAAW,KAAK,SAAS,CAAC,OAAO;CAClC,CAAC;;;;;;;;;;AAWF,IAAsB,YAAtB,MAKA;;;;;;;;;;CAYE,AAAmB;CAEnB,YAAY,OAA4C;AACtD,OAAK,QAAQ;;CAkBf,IAAI,SAAkD;EACpD,MAAM,OAAO,KAAK,UAAU,CAAC;AAK7B,SAAO,SAAS,KAAK,OAAO,EAAE,aAAa,MAAM;;CAGnD,IAAI,cAAgD;AAClD,SAAO,EAAE,aAAa,KAAK,UAAU,CAAC,IAAI;;;;;;;;;;AAW9C,SAAgB,mBAAmB,eAAgC;CACjE,MAAM,eAAe,cAAc,cAAc;CACjD,MAAM,QAAQ,QAAQ,KAAK;AAC3B,KAAI,CAAC,MAAO,QAAO;AACnB,KAAI;AACF,SAAO,aAAa,aAAa,KAAK,aAAa,MAAM;SACnD;AACN,SAAO;;;AAIX,SAAgB,qBAA2B;AACzC,YAAW;;AAGb,SAAS,YAAkB;AACzB,SAAQ,OAAO,MACb;EACE;EACA;EACA;EACA;EACA;EACA;EACD,CAAC,KAAK,KAAK,CACb;;;;;;;;;;;;;;;;;;;AAqCH,SAAS,sBACP,MACA,KACA,UACmB;CACnB,MAAMA,eAAyD;EAC7D,MAAM,KAAK;EACX,IAAI,KAAK;EACT,MAAM,KAAK,QAAQ;EACnB,QAAQ,KAAK,UAAU,UAAU,UAAU,EAAE;EAC7C,oBAAoB,yBAAyB,IAAI;EACjD,WAAW,UAAU,8BAAa,IAAI,MAAM,EAAC,aAAa;EAC1D,cAAc,UAAU,gBAAgB;EAMxC,YAAY,UAAU,cAAe,EAAE,SAAS,EAAE,aAAa,KAAK,IAAI,EAAE;EAC1E,OAAO,eAAe,UAAU,MAAM;EACtC,GAAG,UAAU,cAAc,UAAU,WAAW;EACjD;CAED,MAAM,gBAAgB,qBAAqB,cAAc,IAAI;AAC7D,QAAO;EAAE,GAAG;EAAc;EAAe;;;;;;;;;AAU3C,SAAS,eAAe,UAAsD;AAC5E,QAAO;EACL,MAAM,UAAU,QAAQ,EAAE;EAC1B,SAAS,UAAU,WAAW,EAAE;EAChC,gBAAgB,UAAU,kBAAkB;EAC7C;;;;;;;;;;;AAYH,SAAgB,wBACd,UACA,UACoB;CACpB,MAAM,MAAM,SAAS;AACrB,KAAI,CAAC,MAAM,QAAQ,IAAI,CACrB,OAAM,IAAI,MAAM,8BAA8B;CAIhD,MAAM,SAAS,oBADU,SAAS,UAAU,CACD;AAC3C,KAAI,kBAAkB,KAAK,OACzB,OAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;CAG5E,MAAM,WAAW,sBAAsB,QAAQ,KAAK,SAAS;AAE7D,QAAO;EACL,SAAS,KAAK,UAAU,KAAK,MAAM,EAAE;EACrC;EACA,cAAc,KAAK,UAAU,UAAU,MAAM,EAAE;EAChD"}

package/dist/exports/package.d.mts

@@ -1,2 +1,2 @@
-import { n as MigrationPackage, t as MigrationOps } from "../package-BJ5KAEcD.mjs";
+import { n as MigrationPackage, t as MigrationOps } from "../package-DFjGigEm.mjs";
 export { type MigrationOps, type MigrationPackage };

package/dist/exports/refs.mjs

@@ -1,4 +1,4 @@
-import { c as errorInvalidRefFile, l as errorInvalidRefName, t as MigrationToolsError, u as errorInvalidRefValue } from "../errors-CZ9JD4sd.mjs";
+import { d as errorInvalidRefName, f as errorInvalidRefValue, t as MigrationToolsError, u as errorInvalidRefFile } from "../errors-BS_Kq8GF.mjs";
 import { dirname, join, relative } from "pathe";
 import { mkdir, readFile, readdir, rename, rmdir, unlink, writeFile } from "node:fs/promises";
 import { type } from "arktype";

package/dist/{graph-B5wbCSna.d.mts → graph-coc0V7k2.d.mts}

@@ -10,6 +10,12 @@ interface MigrationEdge {
   readonly dirName: string;
   readonly createdAt: string;
   readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s this edge provides.
+   * An empty array means the migration declares no routing-visible
+   * data transforms.
+   */
+  readonly invariants: readonly string[];
 }
 interface MigrationGraph {
   readonly nodes: ReadonlySet<string>;
@@ -19,4 +25,4 @@ interface MigrationGraph {
 }
 //#endregion
 export { MigrationGraph as n, MigrationEdge as t };
-//# sourceMappingURL=graph-B5wbCSna.d.mts.map
+//# sourceMappingURL=graph-coc0V7k2.d.mts.map

package/dist/graph-coc0V7k2.d.mts.map

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

package/dist/{hash-BNWumjn7.mjs → hash-BARZdVgW.mjs}

@@ -73,4 +73,4 @@ function verifyMigrationHash(pkg) {
 
 //#endregion
 export { verifyMigrationHash as n, computeMigrationHash as t };
-//# sourceMappingURL=hash-BNWumjn7.mjs.map
+//# sourceMappingURL=hash-BARZdVgW.mjs.map

package/dist/{hash-BNWumjn7.mjs.map → hash-BARZdVgW.mjs.map}

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

package/dist/invariants-jlMTqh_Q.mjs

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

package/dist/invariants-jlMTqh_Q.mjs.map

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

package/dist/{metadata-DDa5L-uD.d.mts → metadata-CdSwaQ2k.d.mts}

@@ -30,6 +30,12 @@ interface MigrationMetadata {
   readonly toContract: Contract;
   readonly hints: MigrationHints;
   readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
   readonly authorship?: {
     readonly author?: string;
     readonly email?: string;
@@ -42,4 +48,4 @@ interface MigrationMetadata {
 }
 //#endregion
 export { MigrationMetadata as n, MigrationHints as t };
-//# sourceMappingURL=metadata-DDa5L-uD.d.mts.map
+//# sourceMappingURL=metadata-CdSwaQ2k.d.mts.map

package/dist/{metadata-DDa5L-uD.d.mts.map → metadata-CdSwaQ2k.d.mts.map}

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

package/dist/{package-BJ5KAEcD.d.mts → package-DFjGigEm.d.mts}

@@ -1,4 +1,4 @@
-import { n as MigrationMetadata } from "./metadata-DDa5L-uD.mjs";
+import { n as MigrationMetadata } from "./metadata-CdSwaQ2k.mjs";
 import { MigrationPlanOperation } from "@prisma-next/framework-components/control";
 
 //#region src/package.d.ts
@@ -18,4 +18,4 @@ interface MigrationPackage {
 }
 //#endregion
 export { MigrationPackage as n, MigrationOps as t };
-//# sourceMappingURL=package-BJ5KAEcD.d.mts.map
+//# sourceMappingURL=package-DFjGigEm.d.mts.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.5.0-dev.15",
+  "version": "0.5.0-dev.17",
   "type": "module",
   "sideEffects": false,
   "description": "On-disk migration persistence, hash verification, and chain reconstruction for Prisma Next",
@@ -8,9 +8,9 @@
     "arktype": "^2.1.29",
     "pathe": "^2.0.3",
     "prettier": "^3.6.2",
-    "@prisma-next/contract": "0.5.0-dev.15",
-    "@prisma-next/framework-components": "0.5.0-dev.15",
-    "@prisma-next/utils": "0.5.0-dev.15"
+    "@prisma-next/contract": "0.5.0-dev.17",
+    "@prisma-next/framework-components": "0.5.0-dev.17",
+    "@prisma-next/utils": "0.5.0-dev.17"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
@@ -51,6 +51,10 @@
       "types": "./dist/exports/hash.d.mts",
       "import": "./dist/exports/hash.mjs"
     },
+    "./invariants": {
+      "types": "./dist/exports/invariants.d.mts",
+      "import": "./dist/exports/invariants.mjs"
+    },
     "./migration-graph": {
       "types": "./dist/exports/migration-graph.d.mts",
       "import": "./dist/exports/migration-graph.mjs"

package/src/errors.ts

@@ -213,6 +213,55 @@ export function errorDuplicateMigrationHash(migrationHash: string): MigrationToo
   );
 }
 
+export function errorInvalidInvariantId(invariantId: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {
+    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,
+    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. "backfill-user-phone", "users/backfill-phone", or "BackfillUserPhone".',
+    details: { invariantId },
+  });
+}
+
+export function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',
+    'Duplicate invariantId on a single migration',
+    {
+      why: `invariantId "${invariantId}" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,
+      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',
+      details: { invariantId },
+    },
+  );
+}
+
+export function errorProvidedInvariantsMismatch(
+  filePath: string,
+  stored: readonly string[],
+  derived: readonly string[],
+): MigrationToolsError {
+  const storedSet = new Set(stored);
+  const derivedSet = new Set(derived);
+  const missing = [...derivedSet].filter((id) => !storedSet.has(id));
+  const extra = [...storedSet].filter((id) => !derivedSet.has(id));
+  // When sets agree but arrays don't, the only difference is ordering — call
+  // it out so the reader doesn't stare at two visually-identical arrays.
+  // Canonical providedInvariants is sorted ascending; a manifest with the
+  // same ids in a different order is still a mismatch (the hash check would
+  // also fail), but the human-readable diagnostic is otherwise unhelpful.
+  const orderingOnly = missing.length === 0 && extra.length === 0;
+  const why = orderingOnly
+    ? `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`
+    : `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;
+  return new MigrationToolsError(
+    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',
+    'providedInvariants on migration.json disagrees with ops.json',
+    {
+      why,
+      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
+      details: { filePath, stored, derived, difference: { missing, extra } },
+    },
+  );
+}
+
 export function errorMigrationHashMismatch(
   dir: string,
   storedHash: string,

package/src/exports/invariants.ts

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

package/src/graph.ts

@@ -9,6 +9,12 @@ export interface MigrationEdge {
   readonly dirName: string;
   readonly createdAt: string;
   readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s this edge provides.
+   * An empty array means the migration declares no routing-visible
+   * data transforms.
+   */
+  readonly invariants: readonly string[];
 }
 
 export interface MigrationGraph {

package/src/invariants.ts

@@ -0,0 +1,45 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import { errorDuplicateInvariantInEdge, errorInvalidInvariantId } from './errors';
+import type { MigrationOps } from './package';
+
+/**
+ * Hygiene check for `invariantId`. Rejects empty values plus any
+ * whitespace or control character (including Unicode whitespace like
+ * NBSP and em space, which are visually identical to ASCII space and
+ * routinely sneak in via paste).
+ */
+export function validateInvariantId(invariantId: string): boolean {
+  if (invariantId.length === 0) return false;
+  return !/[\p{Cc}\p{White_Space}]/u.test(invariantId);
+}
+
+/**
+ * Walk a migration's operations and produce its `providedInvariants`
+ * aggregate: the sorted, deduplicated list of `invariantId`s declared
+ * by data-transform ops. Ops without `operationClass === 'data'` are
+ * skipped; data ops without an `invariantId` are skipped.
+ *
+ * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+ * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+ */
+export function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {
+  const seen = new Set<string>();
+  for (const op of ops) {
+    const invariantId = readInvariantId(op);
+    if (invariantId === undefined) continue;
+    if (!validateInvariantId(invariantId)) {
+      throw errorInvalidInvariantId(invariantId);
+    }
+    if (seen.has(invariantId)) {
+      throw errorDuplicateInvariantInEdge(invariantId);
+    }
+    seen.add(invariantId);
+  }
+  return [...seen].sort();
+}
+
+function readInvariantId(op: MigrationPlanOperation): string | undefined {
+  if (op.operationClass !== 'data') return undefined;
+  const candidate = (op as { invariantId?: unknown }).invariantId;
+  return typeof candidate === 'string' ? candidate : undefined;
+}

package/src/io.ts

@@ -9,8 +9,10 @@ import {
   errorInvalidSlug,
   errorMigrationHashMismatch,
   errorMissingFile,
+  errorProvidedInvariantsMismatch,
 } from './errors';
 import { verifyMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
 import type { MigrationMetadata } from './metadata';
 import type { MigrationOps, MigrationPackage } from './package';
 
@@ -37,6 +39,7 @@ const MigrationMetadataSchema = type({
   toContract: 'object',
   hints: MigrationHintsSchema,
   labels: 'string[]',
+  providedInvariants: 'string[]',
   'authorship?': type({
     'author?': 'string',
     'email?': 'string',
@@ -52,6 +55,7 @@ const MigrationOpSchema = type({
   id: 'string',
   label: 'string',
   operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
+  'invariantId?': 'string',
 });
 
 // Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.
@@ -155,6 +159,17 @@ export async function readMigrationPackage(dir: string): Promise<MigrationPackag
   validateMetadata(metadata, manifestPath);
   validateOps(ops, opsPath);
 
+  // Re-derive before the hash check so format/duplicate diagnostics
+  // fire with their dedicated codes rather than as a generic hash mismatch.
+  const derivedInvariants = deriveProvidedInvariants(ops);
+  if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) {
+    throw errorProvidedInvariantsMismatch(
+      manifestPath,
+      metadata.providedInvariants,
+      derivedInvariants,
+    );
+  }
+
   const pkg: MigrationPackage = {
     dirName: basename(dir),
     dirPath: dir,
@@ -170,6 +185,14 @@ export async function readMigrationPackage(dir: string): Promise<MigrationPackag
   return pkg;
 }
 
+function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
 function validateMetadata(
   metadata: unknown,
   filePath: string,

package/src/metadata.ts

@@ -30,6 +30,12 @@ export interface MigrationMetadata {
   readonly toContract: Contract;
   readonly hints: MigrationHints;
   readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
   readonly authorship?: { readonly author?: string; readonly email?: string };
   readonly signature?: { readonly keyId: string; readonly value: string } | null;
   readonly createdAt: string;

package/src/migration-base.ts

@@ -9,6 +9,7 @@ import type {
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type } from 'arktype';
 import { computeMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
 import type { MigrationHints, MigrationMetadata } from './metadata';
 import type { MigrationOps } from './package';
 
@@ -166,6 +167,7 @@ function buildAttestedMetadata(
     to: meta.to,
     kind: meta.kind ?? 'regular',
     labels: meta.labels ?? existing?.labels ?? [],
+    providedInvariants: deriveProvidedInvariants(ops),
     createdAt: existing?.createdAt ?? new Date().toISOString(),
     fromContract: existing?.fromContract ?? null,
     // When no scaffolded metadata exists we synthesize a minimal contract

package/src/migration-graph.ts

@@ -50,6 +50,7 @@ export function reconstructGraph(packages: readonly MigrationPackage[]): Migrati
       dirName: pkg.dirName,
       createdAt: pkg.metadata.createdAt,
       labels: pkg.metadata.labels,
+      invariants: pkg.metadata.providedInvariants,
     };
 
     if (migrationByHash.has(migration.migrationHash)) {

package/dist/graph-B5wbCSna.d.mts.map

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

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

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