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

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

@@ -0,0 +1 @@
+{"version":3,"file":"migration-graph.mjs","names":["migration: MigrationEdge","LABEL_PRIORITY: Record<string, number>","path: MigrationEdge[]","next: Set<string> | null","cur: string | undefined","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 states — they were not\n * reached via any edge. For every other state they record the predecessor\n * state and the edge by which this state was first reached.\n *\n * `state` is the BFS state, most often a string (graph node identifier) but\n * can be a composite object. The string overload keeps the common case\n * ergonomic; the generic overload accepts a caller-supplied `key` function\n * that produces a stable equality key for dedup.\n */\nexport interface BfsStep<S, E> {\n  readonly state: S;\n  readonly parent: S | null;\n  readonly incomingEdge: E | null;\n}\n\n/**\n * Generic breadth-first traversal.\n *\n * Direction (forward/reverse) is expressed by the caller's `neighbours`\n * closure: return `{ next, edge }` pairs where `next` is the state to visit\n * next and `edge` is the edge that connects them. Callers that don't need\n * path reconstruction can ignore the `parent`/`incomingEdge` fields of each\n * yielded step.\n *\n * Ordering — when the result needs to be deterministic (path-finding) the\n * caller is responsible for sorting inside `neighbours`; this generator\n * does not impose an ordering hook of its own. State-dependent orderings\n * have full access to the source state inside the closure.\n *\n * Stops are intrinsic — callers `break` out of the `for..of` loop when\n * they've found what they're looking for.\n */\nexport function bfs<E>(\n  starts: Iterable<string>,\n  neighbours: (state: string) => Iterable<{ next: string; edge: E }>,\n): Generator<BfsStep<string, E>>;\nexport function bfs<S, E>(\n  starts: Iterable<S>,\n  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,\n  key: (state: S) => string,\n): Generator<BfsStep<S, E>>;\nexport function* bfs<S, E>(\n  starts: Iterable<S>,\n  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,\n  // Identity default for the string overload. TypeScript can't express\n  // \"default applies only when S = string\", so this cast bridges the\n  // generic implementation signature to the public overloads — which\n  // guarantee `key` is omitted only when S = string at the call site.\n  key: (state: S) => string = (state) => state as unknown as string,\n): Generator<BfsStep<S, E>> {\n  // Queue entries carry the state alongside its key so we don't recompute\n  // key() twice per visit (once on dedup, once on parent lookup). Composite\n  // keys can be non-trivial to compute; string-overload callers pay nothing\n  // since key() is identity there.\n  interface Entry {\n    readonly state: S;\n    readonly key: string;\n  }\n  const visited = new Set<string>();\n  const parentMap = new Map<string, { parent: S; edge: E }>();\n  const queue = new Queue<Entry>();\n  for (const start of starts) {\n    const k = key(start);\n    if (!visited.has(k)) {\n      visited.add(k);\n      queue.push({ state: start, key: k });\n    }\n  }\n  while (!queue.isEmpty) {\n    const { state: current, key: curKey } = queue.shift();\n    const parentInfo = parentMap.get(curKey);\n    yield {\n      state: current,\n      parent: parentInfo?.parent ?? null,\n      incomingEdge: parentInfo?.edge ?? null,\n    };\n\n    for (const { next, edge } of neighbours(current)) {\n      const k = key(next);\n      if (!visited.has(k)) {\n        visited.add(k);\n        parentMap.set(k, { parent: current, edge });\n        queue.push({ state: next, key: k });\n      }\n    }\n  }\n}\n","import { ifDefined } from '@prisma-next/utils/defined';\nimport { EMPTY_CONTRACT_HASH } from './constants';\nimport {\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: edge `e` from `n` visits `e.to` next. */\nfunction forwardNeighbours(graph: MigrationGraph, node: string) {\n  return (graph.forwardChain.get(node) ?? []).map((edge) => ({ next: edge.to, edge }));\n}\n\n/**\n * Forward-edge neighbours, sorted by the deterministic tie-break.\n * Used by path-finding so the resulting shortest path is stable across runs.\n */\nfunction sortedForwardNeighbours(graph: MigrationGraph, node: string) {\n  const edges = graph.forwardChain.get(node) ?? [];\n  return [...edges].sort(compareTieBreak).map((edge) => ({ next: edge.to, edge }));\n}\n\n/** Reverse-edge neighbours: edge `e` from `n` visits `e.from` next. */\nfunction reverseNeighbours(graph: MigrationGraph, node: string) {\n  return (graph.reverseChain.get(node) ?? []).map((edge) => ({ next: edge.from, edge }));\n}\n\nfunction appendEdge(map: Map<string, MigrationEdge[]>, key: string, entry: MigrationEdge): void {\n  const bucket = map.get(key);\n  if (bucket) bucket.push(entry);\n  else map.set(key, [entry]);\n}\n\nexport function reconstructGraph(packages: readonly 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    // Manifest `from` is `string | null` (null = baseline). The graph layer\n    // is the marker/path layer where \"no prior state\" is encoded as the\n    // EMPTY_CONTRACT_HASH sentinel; bridge here so pathfinding stays string-\n    // keyed.\n    const from = pkg.metadata.from ?? EMPTY_CONTRACT_HASH;\n    const { to } = pkg.metadata;\n\n    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 path-finders only; not a general-purpose utility.\n// 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/**\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) => sortedForwardNeighbours(graph, n))) {\n    if (step.parent !== null && step.incomingEdge !== null) {\n      parents.set(step.state, { parent: step.parent, edge: step.incomingEdge });\n    }\n    if (step.state === toHash) {\n      const path: MigrationEdge[] = [];\n      let cur = toHash;\n      let p = parents.get(cur);\n      while (p) {\n        path.push(p.edge);\n        cur = p.parent;\n        p = parents.get(cur);\n      }\n      path.reverse();\n      return path;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Find the shortest path from `fromHash` to `toHash` whose edges collectively\n * cover every invariant in `required`. Returns `null` when no such path exists\n * (either `fromHash`→`toHash` is structurally unreachable, or every reachable\n * path leaves at least one required invariant uncovered). When `required` is\n * empty, delegates to `findPath` so the result is byte-identical for that case.\n *\n * Algorithm: BFS over `(node, coveredSubset)` states with state-level dedup.\n * The covered subset is a `Set<string>` of invariant ids; the state's dedup\n * key is `${node}\\0${[...covered].sort().join('\\0')}`. State keys distinguish\n * distinct `(node, covered)` tuples regardless of node-name length because\n * `\\0` cannot appear in any invariant id (validation rejects whitespace and\n * control chars at authoring time).\n *\n * Neighbour ordering when `required ≠ ∅`: edges covering ≥1 still-needed\n * invariant come first, with `labelPriority → createdAt → to → migrationHash`\n * as the secondary key. The heuristic steers BFS toward the satisfying path;\n * correctness (shortest, deterministic) does not depend on it.\n */\nexport function findPathWithInvariants(\n  graph: MigrationGraph,\n  fromHash: string,\n  toHash: string,\n  required: ReadonlySet<string>,\n): readonly MigrationEdge[] | null {\n  if (required.size === 0) {\n    return findPath(graph, fromHash, toHash);\n  }\n  if (fromHash === toHash) {\n    // Empty path covers no invariants; required is non-empty ⇒ unsatisfiable.\n    return null;\n  }\n\n  interface InvState {\n    readonly node: string;\n    readonly covered: ReadonlySet<string>;\n  }\n  const stateKey = (s: InvState): string => {\n    if (s.covered.size === 0) return `${s.node}\\0`;\n    return `${s.node}\\0${[...s.covered].sort().join('\\0')}`;\n  };\n\n  const neighbours = (s: InvState): Iterable<{ next: InvState; edge: MigrationEdge }> => {\n    const outgoing = graph.forwardChain.get(s.node) ?? [];\n    if (outgoing.length === 0) return [];\n    return [...outgoing]\n      .map((edge) => {\n        let useful = false;\n        let next: Set<string> | null = null;\n        for (const inv of edge.invariants) {\n          if (required.has(inv) && !s.covered.has(inv)) {\n            if (next === null) next = new Set(s.covered);\n            next.add(inv);\n            useful = true;\n          }\n        }\n        return { edge, useful, nextCovered: next ?? s.covered };\n      })\n      .sort((a, b) => {\n        if (a.useful !== b.useful) return a.useful ? -1 : 1;\n        return compareTieBreak(a.edge, b.edge);\n      })\n      .map(({ edge, nextCovered }) => ({\n        next: { node: edge.to, covered: nextCovered },\n        edge,\n      }));\n  };\n\n  // Path reconstruction is consumer-side, keyed on stateKey, same shape as\n  // findPath's parents map.\n  const parents = new Map<string, { parentKey: string; edge: MigrationEdge }>();\n  for (const step of bfs<InvState, MigrationEdge>(\n    [{ node: fromHash, covered: new Set() }],\n    neighbours,\n    stateKey,\n  )) {\n    const curKey = stateKey(step.state);\n    if (step.parent !== null && step.incomingEdge !== null) {\n      parents.set(curKey, { parentKey: stateKey(step.parent), edge: step.incomingEdge });\n    }\n    if (step.state.node === toHash && step.state.covered.size === required.size) {\n      const path: MigrationEdge[] = [];\n      let cur: string | undefined = curKey;\n      while (cur !== undefined) {\n        const p = parents.get(cur);\n        if (!p) break;\n        path.push(p.edge);\n        cur = p.parentKey;\n      }\n      path.reverse();\n      return path;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Reverse-BFS from `toHash` over `reverseChain` to collect every node from\n * which `toHash` is reachable (inclusive of `toHash` itself).\n */\nfunction collectNodesReachingTarget(graph: MigrationGraph, toHash: string): Set<string> {\n  const reached = new Set<string>();\n  for (const step of bfs([toHash], (n) => reverseNeighbours(graph, n))) {\n    reached.add(step.state);\n  }\n  return reached;\n}\n\nexport interface PathDecision {\n  readonly selectedPath: readonly MigrationEdge[];\n  readonly fromHash: string;\n  readonly toHash: string;\n  readonly alternativeCount: number;\n  readonly tieBreakReasons: readonly string[];\n  readonly refName?: string;\n}\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.state);\n    }\n    return ancestors;\n  });\n\n  const commonAncestors = [...(ancestorSets[0] ?? [])].filter((node) =>\n    ancestorSets.every((s) => s.has(node)),\n  );\n\n  let deepest = fromHash;\n  let deepestDepth = -1;\n  for (const ancestor of commonAncestors) {\n    const path = findPath(graph, fromHash, ancestor);\n    const depth = path ? path.length : 0;\n    if (depth > deepestDepth) {\n      deepestDepth = depth;\n      deepest = ancestor;\n    }\n  }\n  return deepest;\n}\n\n/**\n * Find all branch tips (nodes with no outgoing edges) reachable from\n * `fromHash` via forward edges.\n */\nexport function findReachableLeaves(graph: MigrationGraph, fromHash: string): readonly string[] {\n  const leaves: string[] = [];\n  for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n))) {\n    if (!graph.forwardChain.get(step.state)?.length) {\n      leaves.push(step.state);\n    }\n  }\n  return leaves;\n}\n\n/**\n * Find the target contract hash of the migration graph reachable from\n * EMPTY_CONTRACT_HASH. Returns `null` for a graph that has no target\n * state (either empty, or containing only the root with no outgoing\n * edges). Throws NO_INITIAL_MIGRATION if the graph has nodes but none\n * originate from the empty hash, and AMBIGUOUS_TARGET if multiple\n * branch tips exist.\n */\nexport function findLeaf(graph: MigrationGraph): string | null {\n  if (graph.nodes.size === 0) {\n    return null;\n  }\n\n  if (!graph.nodes.has(EMPTY_CONTRACT_HASH)) {\n    throw errorNoInitialMigration([...graph.nodes]);\n  }\n\n  const leaves = findReachableLeaves(graph, EMPTY_CONTRACT_HASH);\n\n  if (leaves.length === 0) {\n    const reachable = [...graph.nodes].filter((n) => n !== EMPTY_CONTRACT_HASH);\n    if (reachable.length > 0) {\n      throw errorNoTarget(reachable);\n    }\n    return null;\n  }\n\n  if (leaves.length > 1) {\n    const divergencePoint = findDivergencePoint(graph, EMPTY_CONTRACT_HASH, leaves);\n    const branches = leaves.map((tip) => {\n      const path = findPath(graph, divergencePoint, tip);\n      return {\n        tip,\n        edges: (path ?? []).map((e) => ({ dirName: e.dirName, from: e.from, to: e.to })),\n      };\n    });\n    throw errorAmbiguousTarget(leaves, { divergencePoint, branches });\n  }\n\n  // biome-ignore lint/style/noNonNullAssertion: leaves.length is neither 0 nor >1 per the branches above, so exactly one leaf remains\n  return leaves[0]!;\n}\n\n/**\n * Find the latest migration entry by traversing from EMPTY_CONTRACT_HASH\n * to the single target. Returns null for an empty graph.\n * Throws AMBIGUOUS_TARGET if the graph has multiple branch tips.\n */\nexport function findLatestMigration(graph: MigrationGraph): MigrationEdge | null {\n  const leafHash = findLeaf(graph);\n  if (leafHash === null) return null;\n\n  const path = findPath(graph, EMPTY_CONTRACT_HASH, leafHash);\n  return path?.at(-1) ?? null;\n}\n\nexport function detectCycles(graph: MigrationGraph): readonly string[][] {\n  const WHITE = 0;\n  const GRAY = 1;\n  const BLACK = 2;\n\n  const color = new Map<string, number>();\n  const parentMap = new Map<string, string | null>();\n  const cycles: string[][] = [];\n\n  for (const node of graph.nodes) {\n    color.set(node, WHITE);\n  }\n\n  // Iterative three-color DFS. A frame is (node, outgoing edges, next-index).\n  interface Frame {\n    node: string;\n    outgoing: readonly MigrationEdge[];\n    index: number;\n  }\n  const stack: Frame[] = [];\n\n  function pushFrame(u: string): void {\n    color.set(u, GRAY);\n    stack.push({ node: u, outgoing: graph.forwardChain.get(u) ?? [], index: 0 });\n  }\n\n  for (const root of graph.nodes) {\n    if (color.get(root) !== WHITE) continue;\n    parentMap.set(root, null);\n    pushFrame(root);\n\n    while (stack.length > 0) {\n      // biome-ignore lint/style/noNonNullAssertion: stack.length > 0 should guarantee that this cannot be undefined\n      const frame = stack[stack.length - 1]!;\n      if (frame.index >= frame.outgoing.length) {\n        color.set(frame.node, BLACK);\n        stack.pop();\n        continue;\n      }\n      // biome-ignore lint/style/noNonNullAssertion: the early-continue above guarantees frame.index < frame.outgoing.length here, so this is defined\n      const edge = frame.outgoing[frame.index++]!;\n      const v = edge.to;\n      const vColor = color.get(v);\n      if (vColor === GRAY) {\n        const cycle: string[] = [v];\n        let cur = frame.node;\n        while (cur !== v) {\n          cycle.push(cur);\n          cur = parentMap.get(cur) ?? v;\n        }\n        cycle.reverse();\n        cycles.push(cycle);\n      } else if (vColor === WHITE) {\n        parentMap.set(v, frame.node);\n        pushFrame(v);\n      }\n    }\n  }\n\n  return cycles;\n}\n\nexport function detectOrphans(graph: MigrationGraph): readonly MigrationEdge[] {\n  if (graph.nodes.size === 0) return [];\n\n  const reachable = new Set<string>();\n  const startNodes: string[] = [];\n\n  if (graph.forwardChain.has(EMPTY_CONTRACT_HASH)) {\n    startNodes.push(EMPTY_CONTRACT_HASH);\n  } else {\n    const allTargets = new Set<string>();\n    for (const edges of graph.forwardChain.values()) {\n      for (const edge of edges) {\n        allTargets.add(edge.to);\n      }\n    }\n    for (const node of graph.nodes) {\n      if (!allTargets.has(node)) {\n        startNodes.push(node);\n      }\n    }\n  }\n\n  for (const step of bfs(startNodes, (n) => forwardNeighbours(graph, n))) {\n    reachable.add(step.state);\n  }\n\n  const orphans: MigrationEdge[] = [];\n  for (const [from, migrations] of graph.forwardChain) {\n    if (!reachable.has(from)) {\n      orphans.push(...migrations);\n    }\n  }\n\n  return orphans;\n}\n"],"mappings":"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"}

package/dist/exports/migration-ts.mjs

@@ -1,5 +1,5 @@
-import { stat, writeFile } from "node:fs/promises";
 import { join } from "pathe";
+import { stat, writeFile } from "node:fs/promises";
 import { format } from "prettier";
 
 //#region src/migration-ts.ts

package/dist/exports/migration.d.mts

@@ -1,11 +1,10 @@
-import { a as MigrationManifest } from "../types-DyGXcWWp.mjs";
+import { n as MigrationMetadata } from "../metadata-BP1cmU7Z.mjs";
 import { ControlStack, MigrationPlan, MigrationPlanOperation } from "@prisma-next/framework-components/control";
 
 //#region src/migration-base.d.ts
 interface MigrationMeta {
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
-  readonly kind?: 'regular' | 'baseline';
   readonly labels?: readonly string[];
 }
 /**
@@ -13,7 +12,7 @@ interface MigrationMeta {
  *
  * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the
  * runner can consume it directly via `targetId`, `operations`, `origin`, and
- * `destination`. The manifest-shaped inputs come from `describe()`, which
+ * `destination`. The metadata-shaped inputs come from `describe()`, which
  * every migration must implement — `migration.json` is required for a
  * migration to be valid.
  */
@@ -58,30 +57,32 @@ declare abstract class Migration<TOperation extends MigrationPlanOperation = Mig
  * than executed directly.
  */
 declare function isDirectEntrypoint(importMetaUrl: string): boolean;
-declare function printMigrationHelp(): void;
 /**
  * In-memory artifacts produced from a `Migration` instance: the
- * serialized `ops.json` body, the `migration.json` manifest object, and
+ * serialized `ops.json` body, the `migration.json` metadata object, and
  * its serialized form. Returned by `buildMigrationArtifacts` so callers
  * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can
  * decide how to persist them — write to disk, print in dry-run, ship
  * over the wire — without coupling artifact construction to file I/O.
+ *
+ * `metadataJson` is `JSON.stringify(metadata, null, 2)` — the canonical
+ * on-disk shape that the arktype loader-schema in `./io` validates.
  */
 interface MigrationArtifacts {
   readonly opsJson: string;
-  readonly manifest: MigrationManifest;
-  readonly manifestJson: string;
+  readonly metadata: MigrationMetadata;
+  readonly metadataJson: string;
 }
 /**
  * Pure conversion from a `Migration` instance (plus the previously
- * scaffolded manifest, when one exists on disk) to the in-memory
+ * scaffolded metadata, when one exists on disk) to the in-memory
  * artifacts that downstream tooling persists. Owns metadata validation,
- * manifest synthesis/preservation, hint normalization, and the
- * content-addressed `migrationId` computation, but performs no file I/O
+ * metadata synthesis/preservation, hint normalization, and the
+ * content-addressed `migrationHash` computation, but performs no file I/O
  * — callers handle reads (to source `existing`) and writes (to persist
- * `opsJson` / `manifestJson`).
+ * `opsJson` / `metadataJson`).
  */
-declare function buildMigrationArtifacts(instance: Migration, existing: Partial<MigrationManifest> | null): MigrationArtifacts;
+declare function buildMigrationArtifacts(instance: Migration, existing: Partial<MigrationMetadata> | null): MigrationArtifacts;
 //#endregion
-export { Migration, type MigrationArtifacts, type MigrationMeta, buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp };
+export { Migration, type MigrationArtifacts, type MigrationMeta, buildMigrationArtifacts, isDirectEntrypoint };
 //# sourceMappingURL=migration.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":[],"mappings":";;;;UAaiB,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;AAyBhB;AAyEA;;;;;;;4BAvJ4B,aAAa,WAAW;sBAE9B,aAAa,WAAW;;;;;;;sCAUR;;;;;;uBAOf;;;;;;;;;;;;;;;iBAuBP,kBAAA;iBAWA,kBAAA,CAAA;;;;;;;;;UAyBC,kBAAA;;qBAEI;;;;;;;;;;;;iBAuEL,uBAAA,WACJ,qBACA,QAAQ,4BACjB"}
+{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":[],"mappings":";;;;UAiBiB,aAAA;;EAAA,SAAA,EAAA,EAAA,MAAa;EA0BR,SAAA,MAAS,CAAA,EAAA,SAAA,MAAA,EAAA;;;;;;;;;;;AAIlB,uBAJS,SAIT,CAAA,mBAHQ,sBAGR,GAHiC,sBAGjC,EAAA,kBAAA,MAAA,GAAA,MAAA,EAAA,kBAAA,MAAA,GAAA,MAAA,CAAA,YAAA,aAAA,CAAA;EAAa,kBAAA,QAAA,EAAA,MAAA;EAmDV;AAsBhB;AAsHA;;;;;;;4BAlL4B,aAAa,WAAW;sBAE9B,aAAa,WAAW;;;;;;;sCAUR;;;;;;uBAOf;;;;;;;;;;;;;;;iBAmBP,kBAAA;;;;;;;;;;;;UAsBC,kBAAA;;qBAEI;;;;;;;;;;;;iBAoHL,uBAAA,WACJ,qBACA,QAAQ,4BACjB"}

package/dist/exports/migration.mjs

@@ -1,5 +1,7 @@
-import "../io-CCnYsUHU.mjs";
-import { t as computeMigrationId } from "../attestation-DtF8tEOM.mjs";
+import { u as errorInvalidOperationEntry, x as errorStaleContractBookends } from "../errors-Bl3cKiM8.mjs";
+import { t as computeMigrationHash } from "../hash-BARZdVgW.mjs";
+import { t as deriveProvidedInvariants } from "../invariants-BmrTBQ0A.mjs";
+import { t as MigrationOpSchema } from "../op-schema-DZKFua46.mjs";
 import { type } from "arktype";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { realpathSync } from "node:fs";
@@ -7,9 +9,8 @@ import { fileURLToPath } from "node:url";
 
 //#region src/migration-base.ts
 const MigrationMetaSchema = type({
-	from: "string",
+	from: "string > 0 | null",
 	to: "string",
-	"kind?": "'regular' | 'baseline'",
 	"labels?": type("string").array()
 });
 /**
@@ -17,7 +18,7 @@ const MigrationMetaSchema = type({
 *
 * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the
 * runner can consume it directly via `targetId`, `operations`, `origin`, and
-* `destination`. The manifest-shaped inputs come from `describe()`, which
+* `destination`. The metadata-shaped inputs come from `describe()`, which
 * every migration must implement — `migration.json` is required for a
 * migration to be valid.
 */
@@ -37,7 +38,7 @@ var Migration = class {
 	}
 	get origin() {
 		const from = this.describe().from;
-		return from === "" ? null : { storageHash: from };
+		return from === null ? null : { storageHash: from };
 	}
 	get destination() {
 		return { storageHash: this.describe().to };
@@ -60,57 +61,80 @@ function isDirectEntrypoint(importMetaUrl) {
 		return false;
 	}
 }
-function printMigrationHelp() {
-	printHelp();
-}
-function printHelp() {
-	process.stdout.write([
-		"Usage: node <migration-file> [options]",
-		"",
-		"Options:",
-		"  --dry-run  Print operations to stdout without writing files",
-		"  --help     Show this help message",
-		""
-	].join("\n"));
-}
 /**
-* Build the attested manifest from `describe()`-derived metadata, the
-* operations list, and the previously-scaffolded manifest (if any).
+* Build the attested metadata from `describe()`-derived metadata, the
+* operations list, and the previously-scaffolded metadata (if any).
 *
 * When a `migration.json` already exists for this package (the common
 * case: it was scaffolded by `migration plan`), preserve the contract
 * bookends, hints, labels, and `createdAt` set there — those fields are
 * owned by the CLI scaffolder, not the authored class. Only the
-* `describe()`-derived fields (`from`, `to`, `kind`) and the operations
-* change as the author iterates. When no manifest exists yet (a bare
+* `describe()`-derived fields (`from`, `to`) and the operations
+* change as the author iterates. When no metadata exists yet (a bare
 * `migration.ts` run from scratch), synthesize a minimal but
-* schema-conformant manifest so the resulting package can still be read,
+* schema-conformant record so the resulting package can still be read,
 * verified, and applied.
 *
-* The `migrationId` is recomputed against the current manifest + ops so
+* The `migrationHash` is recomputed against the current metadata + ops so
 * the on-disk artifacts are always fully attested.
 */
-function buildAttestedManifest(meta, ops, existing) {
-	const baseManifest = {
+function buildAttestedMetadata(meta, ops, existing) {
+	assertBookendsMatchMeta(meta, existing);
+	const baseMetadata = {
 		from: meta.from,
 		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 } },
 		hints: normalizeHints(existing?.hints),
 		...ifDefined("authorship", existing?.authorship)
 	};
-	const migrationId = computeMigrationId(baseManifest, ops);
+	const migrationHash = computeMigrationHash(baseMetadata, ops);
 	return {
-		...baseManifest,
-		migrationId
+		...baseMetadata,
+		migrationHash
 	};
 }
 /**
+* Verify each preserved contract bookend in `existing` agrees with the
+* corresponding side of `describe()`'s output. A mismatch indicates the
+* migration's `describe()` was edited after `migration plan` scaffolded
+* the package, leaving a self-inconsistent manifest. Failing fast at
+* write-time turns a silent foot-gun into an actionable diagnostic.
+*
+* Skipped when a side's `existing.<side>Contract` is null/absent (the
+* synthesis path stays open for origin-less initial migrations and for
+* bare `migration.ts` runs from scratch). When a bookend is *present*
+* but its `storage.storageHash` is missing, that's treated as a
+* mismatch — a malformed bookend is not equivalent to "no bookend".
+*
+* This check is paired with TML-2274, which removes `fromContract` /
+* `toContract` from the manifest entirely; once that lands, this
+* function and its error code are deleted.
+*/
+function assertBookendsMatchMeta(meta, existing) {
+	if (existing?.fromContract != null) {
+		const contractHash = existing.fromContract.storage?.storageHash ?? "";
+		if (contractHash !== meta.from) throw errorStaleContractBookends({
+			side: "from",
+			metaHash: meta.from,
+			contractHash
+		});
+	}
+	if (existing?.toContract != null) {
+		const contractHash = existing.toContract.storage?.storageHash ?? "";
+		if (contractHash !== meta.to) throw errorStaleContractBookends({
+			side: "to",
+			metaHash: meta.to,
+			contractHash
+		});
+	}
+}
+/**
 * Project `existing.hints` down to the known `MigrationHints` shape, dropping
-* any legacy keys that may linger in manifests scaffolded by older CLI
+* any legacy keys that may linger in metadata scaffolded by older CLI
 * versions (e.g. `planningStrategy`). Picking fields explicitly instead of
 * spreading keeps refreshed `migration.json` files schema-clean regardless
 * of what was on disk before.
@@ -124,26 +148,30 @@ function normalizeHints(existing) {
 }
 /**
 * Pure conversion from a `Migration` instance (plus the previously
-* scaffolded manifest, when one exists on disk) to the in-memory
+* scaffolded metadata, when one exists on disk) to the in-memory
 * artifacts that downstream tooling persists. Owns metadata validation,
-* manifest synthesis/preservation, hint normalization, and the
-* content-addressed `migrationId` computation, but performs no file I/O
+* metadata synthesis/preservation, hint normalization, and the
+* content-addressed `migrationHash` computation, but performs no file I/O
 * — callers handle reads (to source `existing`) and writes (to persist
-* `opsJson` / `manifestJson`).
+* `opsJson` / `metadataJson`).
 */
 function buildMigrationArtifacts(instance, existing) {
 	const ops = instance.operations;
 	if (!Array.isArray(ops)) throw new Error("operations must be an array");
+	for (let index = 0; index < ops.length; index++) {
+		const result = MigrationOpSchema(ops[index]);
+		if (result instanceof type.errors) throw errorInvalidOperationEntry(index, result.summary);
+	}
 	const parsed = MigrationMetaSchema(instance.describe());
 	if (parsed instanceof type.errors) throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
-	const manifest = buildAttestedManifest(parsed, ops, existing);
+	const metadata = buildAttestedMetadata(parsed, ops, existing);
 	return {
 		opsJson: JSON.stringify(ops, null, 2),
-		manifest,
-		manifestJson: JSON.stringify(manifest, null, 2)
+		metadata,
+		metadataJson: JSON.stringify(metadata, null, 2)
 	};
 }
 
 //#endregion
-export { Migration, buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp };
+export { Migration, buildMigrationArtifacts, isDirectEntrypoint };
 //# sourceMappingURL=migration.mjs.map

package/dist/exports/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":["baseManifest: Omit<MigrationManifest, 'migrationId'>"],"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 { computeMigrationId } from './attestation';\nimport type { MigrationHints, MigrationManifest, MigrationOps } from './types';\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 manifest-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` manifest 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 */\nexport interface MigrationArtifacts {\n  readonly opsJson: string;\n  readonly manifest: MigrationManifest;\n  readonly manifestJson: string;\n}\n\n/**\n * Build the attested manifest from `describe()`-derived metadata, the\n * operations list, and the previously-scaffolded manifest (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 manifest exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant manifest so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationId` is recomputed against the current manifest + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedManifest(\n  meta: MigrationMeta,\n  ops: MigrationOps,\n  existing: Partial<MigrationManifest> | null,\n): MigrationManifest {\n  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {\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 manifest 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 `computeMigrationId`), 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 migrationId = computeMigrationId(baseManifest, ops);\n  return { ...baseManifest, migrationId };\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in manifests 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 manifest, when one exists on disk) to the in-memory\n * artifacts that downstream tooling persists. Owns metadata validation,\n * manifest synthesis/preservation, hint normalization, and the\n * content-addressed `migrationId` computation, but performs no file I/O\n * — callers handle reads (to source `existing`) and writes (to persist\n * `opsJson` / `manifestJson`).\n */\nexport function buildMigrationArtifacts(\n  instance: Migration,\n  existing: Partial<MigrationManifest> | 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 manifest = buildAttestedManifest(parsed, ops, existing);\n\n  return {\n    opsJson: JSON.stringify(ops, null, 2),\n    manifest,\n    manifestJson: JSON.stringify(manifest, null, 2),\n  };\n}\n"],"mappings":";;;;;;;;AAoBA,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;;;;;;;;;;;;;;;;;;;AAkCH,SAAS,sBACP,MACA,KACA,UACmB;CACnB,MAAMA,eAAuD;EAC3D,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,cAAc,mBAAmB,cAAc,IAAI;AACzD,QAAO;EAAE,GAAG;EAAc;EAAa;;;;;;;;;AAUzC,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 { errorInvalidOperationEntry, errorStaleContractBookends } from './errors';\nimport { computeMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport type { MigrationHints, MigrationMetadata } from './metadata';\nimport { MigrationOpSchema } from './op-schema';\nimport type { MigrationOps } from './package';\n\nexport interface MigrationMeta {\n  readonly from: string | null;\n  readonly to: string;\n  readonly labels?: readonly string[];\n}\n\n// `from` rejects empty strings to mirror `MigrationMetadataSchema` in\n// `./io.ts`. Without this match, an authored migration could `describe()` with\n// `from: ''` and pass `buildMigrationArtifacts`'s validation, only to have\n// `readMigrationPackage` reject the resulting `migration.json` later — the\n// two validators must agree on the legal value space.\nconst MigrationMetaSchema = type({\n  from: 'string > 0 | null',\n  to: 'string',\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    return from === null ? 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\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`) 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  assertBookendsMatchMeta(meta, existing);\n\n  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {\n    from: meta.from,\n    to: meta.to,\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 * Verify each preserved contract bookend in `existing` agrees with the\n * corresponding side of `describe()`'s output. A mismatch indicates the\n * migration's `describe()` was edited after `migration plan` scaffolded\n * the package, leaving a self-inconsistent manifest. Failing fast at\n * write-time turns a silent foot-gun into an actionable diagnostic.\n *\n * Skipped when a side's `existing.<side>Contract` is null/absent (the\n * synthesis path stays open for origin-less initial migrations and for\n * bare `migration.ts` runs from scratch). When a bookend is *present*\n * but its `storage.storageHash` is missing, that's treated as a\n * mismatch — a malformed bookend is not equivalent to \"no bookend\".\n *\n * This check is paired with TML-2274, which removes `fromContract` /\n * `toContract` from the manifest entirely; once that lands, this\n * function and its error code are deleted.\n */\nfunction assertBookendsMatchMeta(\n  meta: MigrationMeta,\n  existing: Partial<MigrationMetadata> | null,\n): void {\n  if (existing?.fromContract != null) {\n    const contractHash = existing.fromContract.storage?.storageHash ?? '';\n    if (contractHash !== meta.from) {\n      throw errorStaleContractBookends({\n        side: 'from',\n        metaHash: meta.from,\n        contractHash,\n      });\n    }\n  }\n  if (existing?.toContract != null) {\n    const contractHash = existing.toContract.storage?.storageHash ?? '';\n    if (contractHash !== meta.to) {\n      throw errorStaleContractBookends({\n        side: 'to',\n        metaHash: meta.to,\n        contractHash,\n      });\n    }\n  }\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  for (let index = 0; index < ops.length; index++) {\n    const result = MigrationOpSchema(ops[index]);\n    if (result instanceof type.errors) {\n      throw errorInvalidOperationEntry(index, result.summary);\n    }\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":";;;;;;;;;;AA4BA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,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;AAC7B,SAAO,SAAS,OAAO,OAAO,EAAE,aAAa,MAAM;;CAGrD,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;;;;;;;;;;;;;;;;;;;;AAsCX,SAAS,sBACP,MACA,KACA,UACmB;AACnB,yBAAwB,MAAM,SAAS;CAEvC,MAAMA,eAAyD;EAC7D,MAAM,KAAK;EACX,IAAI,KAAK;EACT,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;;;;;;;;;;;;;;;;;;;AAoB3C,SAAS,wBACP,MACA,UACM;AACN,KAAI,UAAU,gBAAgB,MAAM;EAClC,MAAM,eAAe,SAAS,aAAa,SAAS,eAAe;AACnE,MAAI,iBAAiB,KAAK,KACxB,OAAM,2BAA2B;GAC/B,MAAM;GACN,UAAU,KAAK;GACf;GACD,CAAC;;AAGN,KAAI,UAAU,cAAc,MAAM;EAChC,MAAM,eAAe,SAAS,WAAW,SAAS,eAAe;AACjE,MAAI,iBAAiB,KAAK,GACxB,OAAM,2BAA2B;GAC/B,MAAM;GACN,UAAU,KAAK;GACf;GACD,CAAC;;;;;;;;;;AAYR,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;AAGhD,MAAK,IAAI,QAAQ,GAAG,QAAQ,IAAI,QAAQ,SAAS;EAC/C,MAAM,SAAS,kBAAkB,IAAI,OAAO;AAC5C,MAAI,kBAAkB,KAAK,OACzB,OAAM,2BAA2B,OAAO,OAAO,QAAQ;;CAK3D,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

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

package/dist/exports/package.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/exports/refs.d.mts

@@ -1,10 +1,16 @@
 //#region src/refs.d.ts
-type Refs = Readonly<Record<string, string>>;
+interface RefEntry {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+type Refs = Readonly<Record<string, RefEntry>>;
 declare function validateRefName(name: string): boolean;
 declare function validateRefValue(value: string): boolean;
-declare function readRefs(refsPath: string): Promise<Refs>;
-declare function writeRefs(refsPath: string, refs: Refs): Promise<void>;
-declare function resolveRef(refs: Refs, name: string): string;
+declare function readRef(refsDir: string, name: string): Promise<RefEntry>;
+declare function readRefs(refsDir: string): Promise<Refs>;
+declare function writeRef(refsDir: string, name: string, entry: RefEntry): Promise<void>;
+declare function deleteRef(refsDir: string, name: string): Promise<void>;
+declare function resolveRef(refs: Refs, name: string): RefEntry;
 //#endregion
-export { type Refs, readRefs, resolveRef, validateRefName, validateRefValue, writeRefs };
+export { type RefEntry, type Refs, deleteRef, readRef, readRefs, resolveRef, validateRefName, validateRefValue, writeRef };
 //# sourceMappingURL=refs.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"refs.d.mts","names":[],"sources":["../../src/refs.ts"],"sourcesContent":[],"mappings":";KAUY,IAAA,GAAO,SAAS;AAAhB,iBAKI,eAAA,CALW,IAAA,EAAA,MAAA,CAAA,EAAA,OAAA;AAKX,iBAQA,gBAAA,CARe,KAAA,EAAA,MAAA,CAAA,EAAA,OAAA;AAQf,iBAaM,QAAA,CAbU,QAAA,EAAA,MAAA,CAAA,EAakB,OAblB,CAa0B,IAb1B,CAAA;AAaV,iBA0BA,SAAA,CA1B4B,QAAO,EAAA,MAAA,EAAA,IAAA,EA0BD,IA1BC,CAAA,EA0BM,OA1BN,CAAA,IAAA,CAAA;AA0BnC,iBAoBN,UAAA,CApB+C,IAAA,EAoB9B,IApBqC,EAAA,IAAA,EAAA,MAAA,CAAA,EAAA,MAAA"}
+{"version":3,"file":"refs.d.mts","names":[],"sources":["../../src/refs.ts"],"sourcesContent":[],"mappings":";UAUiB,QAAA;EAAA,SAAA,IAAQ,EAAA,MAAA;EAKb,SAAI,UAAA,EAAA,SAAA,MAAA,EAAA;;AAAY,KAAhB,IAAA,GAAO,QAAS,CAAA,MAAA,CAAA,MAAA,EAAe,QAAf,CAAA,CAAA;AAAT,iBAKH,eAAA,CALG,IAAA,EAAA,MAAA,CAAA,EAAA,OAAA;AAAQ,iBAaX,gBAAA,CAbW,KAAA,EAAA,MAAA,CAAA,EAAA,OAAA;AAKX,iBA8BM,OAAA,CA9BS,OAAA,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,CAAA,EA8B+B,OA9B/B,CA8BuC,QA9BvC,CAAA;AAQf,iBAyDM,QAAA,CAzDU,OAAA,EAAA,MAAA,CAAA,EAyDiB,OAzDjB,CAyDyB,IAzDzB,CAAA;AAsBV,iBAsFA,QAAA,CAtFgD,OAAR,EAAA,MAAO,EAAA,IAAA,EAAA,MAAA,EAAA,KAAA,EAsFA,QAtFA,CAAA,EAsFW,OAtFX,CAAA,IAAA,CAAA;AAmC/C,iBAuEA,SAAA,CAvE2B,OAAO,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,CAAA,EAuEQ,OAvER,CAAA,IAAA,CAAA;AAmDlC,iBA0DN,UAAA,CA1DqD,IAAW,EA0D/C,IA1DsD,EAAA,IAAA,EAAA,MAAA,CAAA,EA0DjC,QA1DiC"}

package/dist/exports/refs.mjs

@@ -1,7 +1,7 @@
-import { c as errorInvalidRefName, l as errorInvalidRefValue, t as MigrationToolsError, u as errorInvalidRefs } from "../errors-BKbRGCJM.mjs";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { d as errorInvalidRefFile, f as errorInvalidRefName, p as errorInvalidRefValue, t as MigrationToolsError } from "../errors-Bl3cKiM8.mjs";
+import { dirname, join, relative } from "pathe";
+import { mkdir, readFile, readdir, rename, rmdir, unlink, writeFile } from "node:fs/promises";
 import { type } from "arktype";
-import { dirname, join } from "pathe";
 
 //#region src/refs.ts
 const REF_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
@@ -16,58 +16,134 @@ function validateRefName(name) {
 function validateRefValue(value) {
 	return REF_VALUE_PATTERN.test(value);
 }
-const RefsSchema = type("Record<string, string>").narrow((refs, ctx) => {
-	for (const [key, value] of Object.entries(refs)) {
-		if (!validateRefName(key)) return ctx.mustBe(`valid ref names (invalid: "${key}")`);
-		if (!validateRefValue(value)) return ctx.mustBe(`valid contract hashes (invalid value for "${key}": "${value}")`);
-	}
+const RefEntrySchema = type({
+	hash: "string",
+	invariants: "string[]"
+}).narrow((entry, ctx) => {
+	if (!validateRefValue(entry.hash)) return ctx.mustBe(`a valid contract hash (got "${entry.hash}")`);
 	return true;
 });
-async function readRefs(refsPath) {
+function refFilePath(refsDir, name) {
+	return join(refsDir, `${name}.json`);
+}
+function refNameFromPath(refsDir, filePath) {
+	return relative(refsDir, filePath).replace(/\.json$/, "");
+}
+async function readRef(refsDir, name) {
+	if (!validateRefName(name)) throw errorInvalidRefName(name);
+	const filePath = refFilePath(refsDir, name);
 	let raw;
 	try {
-		raw = await readFile(refsPath, "utf-8");
+		raw = await readFile(filePath, "utf-8");
 	} catch (error) {
-		if (error instanceof Error && error.code === "ENOENT") return {};
+		if (error instanceof Error && error.code === "ENOENT") throw new MigrationToolsError("MIGRATION.UNKNOWN_REF", `Unknown ref "${name}"`, {
+			why: `No ref file found at "${filePath}".`,
+			fix: `Create the ref with: prisma-next migration ref set ${name} <hash>`,
+			details: {
+				refName: name,
+				filePath
+			}
+		});
 		throw error;
 	}
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch {
-		throw errorInvalidRefs(refsPath, "Failed to parse as JSON");
+		throw errorInvalidRefFile(filePath, "Failed to parse as JSON");
 	}
-	const result = RefsSchema(parsed);
-	if (result instanceof type.errors) throw errorInvalidRefs(refsPath, result.summary);
+	const result = RefEntrySchema(parsed);
+	if (result instanceof type.errors) throw errorInvalidRefFile(filePath, result.summary);
 	return result;
 }
-async function writeRefs(refsPath, refs) {
-	for (const [key, value] of Object.entries(refs)) {
-		if (!validateRefName(key)) throw errorInvalidRefName(key);
-		if (!validateRefValue(value)) throw errorInvalidRefValue(value);
+async function readRefs(refsDir) {
+	let entries;
+	try {
+		entries = await readdir(refsDir, {
+			recursive: true,
+			encoding: "utf-8"
+		});
+	} catch (error) {
+		if (error instanceof Error && error.code === "ENOENT") return {};
+		throw error;
+	}
+	const jsonFiles = entries.filter((entry) => entry.endsWith(".json"));
+	const refs = {};
+	for (const jsonFile of jsonFiles) {
+		const filePath = join(refsDir, jsonFile);
+		const name = refNameFromPath(refsDir, filePath);
+		let raw;
+		try {
+			raw = await readFile(filePath, "utf-8");
+		} catch (error) {
+			const code = error instanceof Error ? error.code : void 0;
+			if (code === "ENOENT" || code === "EISDIR") continue;
+			throw error;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			throw errorInvalidRefFile(filePath, "Failed to parse as JSON");
+		}
+		const result = RefEntrySchema(parsed);
+		if (result instanceof type.errors) throw errorInvalidRefFile(filePath, result.summary);
+		refs[name] = result;
 	}
-	const sorted = Object.fromEntries(Object.entries(refs).sort(([a], [b]) => a.localeCompare(b)));
-	const dir = dirname(refsPath);
+	return refs;
+}
+async function writeRef(refsDir, name, entry) {
+	if (!validateRefName(name)) throw errorInvalidRefName(name);
+	if (!validateRefValue(entry.hash)) throw errorInvalidRefValue(entry.hash);
+	const filePath = refFilePath(refsDir, name);
+	const dir = dirname(filePath);
 	await mkdir(dir, { recursive: true });
-	const tmpPath = join(dir, `.refs.json.${Date.now()}.tmp`);
-	await writeFile(tmpPath, `${JSON.stringify(sorted, null, 2)}\n`);
-	await rename(tmpPath, refsPath);
+	const tmpPath = join(dir, `.${name.split("/").pop()}.json.${Date.now()}.tmp`);
+	await writeFile(tmpPath, `${JSON.stringify({
+		hash: entry.hash,
+		invariants: [...entry.invariants]
+	}, null, 2)}\n`);
+	await rename(tmpPath, filePath);
+}
+async function deleteRef(refsDir, name) {
+	if (!validateRefName(name)) throw errorInvalidRefName(name);
+	const filePath = refFilePath(refsDir, name);
+	try {
+		await unlink(filePath);
+	} catch (error) {
+		if (error instanceof Error && error.code === "ENOENT") throw new MigrationToolsError("MIGRATION.UNKNOWN_REF", `Unknown ref "${name}"`, {
+			why: `No ref file found at "${filePath}".`,
+			fix: "Run `prisma-next migration ref list` to see available refs.",
+			details: {
+				refName: name,
+				filePath
+			}
+		});
+		throw error;
+	}
+	let dir = dirname(filePath);
+	while (dir !== refsDir && dir.startsWith(refsDir)) try {
+		await rmdir(dir);
+		dir = dirname(dir);
+	} catch (error) {
+		const code = error instanceof Error ? error.code : void 0;
+		if (code === "ENOTEMPTY" || code === "EEXIST" || code === "ENOENT") break;
+		throw error;
+	}
 }
 function resolveRef(refs, name) {
 	if (!validateRefName(name)) throw errorInvalidRefName(name);
-	const hash = refs[name];
-	if (hash === void 0) throw new MigrationToolsError("MIGRATION.UNKNOWN_REF", `Unknown ref "${name}"`, {
-		why: `No ref named "${name}" exists in refs.json.`,
-		fix: `Available refs: ${Object.keys(refs).join(", ") || "(none)"}. Create a ref with: set the "${name}" key in migrations/refs.json.`,
+	if (!Object.hasOwn(refs, name)) throw new MigrationToolsError("MIGRATION.UNKNOWN_REF", `Unknown ref "${name}"`, {
+		why: `No ref named "${name}" exists.`,
+		fix: `Available refs: ${Object.keys(refs).join(", ") || "(none)"}. Create a ref with: prisma-next migration ref set ${name} <hash>`,
 		details: {
 			refName: name,
 			availableRefs: Object.keys(refs)
 		}
 	});
-	if (!validateRefValue(hash)) throw errorInvalidRefValue(hash);
-	return hash;
+	return refs[name];
 }
 
 //#endregion
-export { readRefs, resolveRef, validateRefName, validateRefValue, writeRefs };
+export { deleteRef, readRef, readRefs, resolveRef, validateRefName, validateRefValue, writeRef };
 //# sourceMappingURL=refs.mjs.map