@prisma-next/migration-tools 0.11.0 → 0.12.0

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

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

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

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

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

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

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

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

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

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

package/dist/{package-DZj8YvD0.d.mts → package-Ca-J_z_0.d.mts}

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

package/dist/package-Ca-J_z_0.d.mts.map

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

package/dist/{read-contract-space-contract-DRueB4Aa.mjs → read-contract-space-contract-TbeXuJXL.mjs}

@@ -1,5 +1,5 @@
-import { _ as errorInvalidSpaceId, p as errorInvalidRefFile, u as errorInvalidJson, y as errorMissingFile } from "./errors-DGYwcwXs.mjs";
-import { t as MANIFEST_FILE } from "./io-BPLfzvZe.mjs";
+import { f as errorInvalidJson, h as errorInvalidRefFile, x as errorMissingFile, y as errorInvalidSpaceId } from "./errors-vFROOhCR.mjs";
+import { t as MANIFEST_FILE } from "./io-BGlPOt9b.mjs";
 import { join } from "pathe";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { APP_SPACE_ID } from "@prisma-next/framework-components/control";
@@ -32,6 +32,33 @@ function spaceMigrationDirectory(projectMigrationsDir, spaceId) {
 	assertValidSpaceId(spaceId);
 	return join(projectMigrationsDir, spaceId);
 }
+/**
+* Per-space subdirectory name reserved for the ref store
+* (`migrations/<space>/<SPACE_REFS_DIRNAME>/*.json`). Single source of
+* truth: every helper that composes a per-space refs path imports this
+* constant, and the enumerator uses it (via
+* {@link RESERVED_SPACE_SUBDIR_NAMES}) to exclude reserved names from
+* the contract-space candidate list.
+*/
+const SPACE_REFS_DIRNAME = "refs";
+/**
+* Names reserved as per-space subdirectories of `migrations/<space>/`.
+* Used by the enumerator to filter contract-space candidates so a
+* reserved name (e.g. a top-level `migrations/refs/` left in the wrong
+* place) is never enumerated as a phantom contract space. Currently
+* holds `SPACE_REFS_DIRNAME`; extend if future per-space layouts add
+* more reserved subdirectories.
+*/
+const RESERVED_SPACE_SUBDIR_NAMES = new Set([SPACE_REFS_DIRNAME]);
+/**
+* Resolve the per-space refs directory for `spaceMigrationsDir`
+* (typically the value returned by {@link spaceMigrationDirectory}).
+* Composes the canonical {@link SPACE_REFS_DIRNAME} so callers do not
+* hard-code the literal.
+*/
+function spaceRefsDirectory(spaceMigrationsDir) {
+	return join(spaceMigrationsDir, SPACE_REFS_DIRNAME);
+}
 //#endregion
 //#region src/read-contract-space-head-ref.ts
 function hasErrnoCode$2(error, code) {
@@ -52,7 +79,7 @@ function hasErrnoCode$2(error, code) {
 */
 async function readContractSpaceHeadRef(projectMigrationsDir, spaceId) {
 	assertValidSpaceId(spaceId);
-	const filePath = join(projectMigrationsDir, spaceId, "refs", "head.json");
+	const filePath = join(spaceRefsDirectory(spaceMigrationDirectory(projectMigrationsDir, spaceId)), "head.json");
 	let raw;
 	try {
 		raw = await readFile(filePath, "utf-8");
@@ -254,6 +281,6 @@ async function readContractSpaceContract(projectMigrationsDir, spaceId) {
 	}
 }
 //#endregion
-export { APP_SPACE_ID as a, spaceMigrationDirectory as c, readContractSpaceHeadRef as i, listContractSpaceDirectories as n, assertValidSpaceId as o, verifyContractSpaces as r, isValidSpaceId as s, readContractSpaceContract as t };
+export { APP_SPACE_ID as a, assertValidSpaceId as c, spaceRefsDirectory as d, readContractSpaceHeadRef as i, isValidSpaceId as l, listContractSpaceDirectories as n, RESERVED_SPACE_SUBDIR_NAMES as o, verifyContractSpaces as r, SPACE_REFS_DIRNAME as s, readContractSpaceContract as t, spaceMigrationDirectory as u };
 
-//# sourceMappingURL=read-contract-space-contract-DRueB4Aa.mjs.map
+//# sourceMappingURL=read-contract-space-contract-TbeXuJXL.mjs.map

package/dist/read-contract-space-contract-TbeXuJXL.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-contract-space-contract-TbeXuJXL.mjs","names":["hasErrnoCode","hasErrnoCode"],"sources":["../src/space-layout.ts","../src/read-contract-space-head-ref.ts","../src/verify-contract-spaces.ts","../src/read-contract-space-contract.ts"],"sourcesContent":["import { APP_SPACE_ID } from '@prisma-next/framework-components/control';\nimport { join } from 'pathe';\nimport { errorInvalidSpaceId } from './errors';\n\nexport { APP_SPACE_ID };\n\n/**\n * Branded string carrying a compile-time guarantee that the value has\n * been validated by {@link assertValidSpaceId}. Downstream filesystem\n * helpers (e.g. {@link spaceMigrationDirectory}) accept this type to\n * make \"validated\" tracking visible at the type level rather than\n * relying purely on a runtime check.\n */\nexport type ValidSpaceId = string & { readonly __brand: 'ValidSpaceId' };\n\n/**\n * Pattern a contract-space identifier must match. The constraint is\n * filesystem-friendly: lowercase letters / digits / hyphen / underscore,\n * starts with a letter, max 64 characters.\n */\nconst SPACE_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;\n\nexport function isValidSpaceId(spaceId: string): spaceId is ValidSpaceId {\n  return SPACE_ID_PATTERN.test(spaceId);\n}\n\nexport function assertValidSpaceId(spaceId: string): asserts spaceId is ValidSpaceId {\n  if (!isValidSpaceId(spaceId)) {\n    throw errorInvalidSpaceId(spaceId);\n  }\n}\n\n/**\n * Resolve the migrations subdirectory for a given contract space.\n *\n * Every contract space — including the app space (default `'app'`) —\n * lands under `<projectMigrationsDir>/<spaceId>/`. The space id is\n * validated against {@link SPACE_ID_PATTERN} because it becomes a\n * filesystem directory name verbatim.\n *\n * `projectMigrationsDir` is the project's top-level `migrations/`\n * directory; the helper does not assume anything about its absolute /\n * relative shape and is symmetric with `pathe.join`.\n */\nexport function spaceMigrationDirectory(projectMigrationsDir: string, spaceId: string): string {\n  assertValidSpaceId(spaceId);\n  return join(projectMigrationsDir, spaceId);\n}\n\n/**\n * Per-space subdirectory name reserved for the ref store\n * (`migrations/<space>/<SPACE_REFS_DIRNAME>/*.json`). Single source of\n * truth: every helper that composes a per-space refs path imports this\n * constant, and the enumerator uses it (via\n * {@link RESERVED_SPACE_SUBDIR_NAMES}) to exclude reserved names from\n * the contract-space candidate list.\n */\nexport const SPACE_REFS_DIRNAME = 'refs';\n\n/**\n * Names reserved as per-space subdirectories of `migrations/<space>/`.\n * Used by the enumerator to filter contract-space candidates so a\n * reserved name (e.g. a top-level `migrations/refs/` left in the wrong\n * place) is never enumerated as a phantom contract space. Currently\n * holds `SPACE_REFS_DIRNAME`; extend if future per-space layouts add\n * more reserved subdirectories.\n */\nexport const RESERVED_SPACE_SUBDIR_NAMES: ReadonlySet<string> = new Set([SPACE_REFS_DIRNAME]);\n\n/**\n * Resolve the per-space refs directory for `spaceMigrationsDir`\n * (typically the value returned by {@link spaceMigrationDirectory}).\n * Composes the canonical {@link SPACE_REFS_DIRNAME} so callers do not\n * hard-code the literal.\n */\nexport function spaceRefsDirectory(spaceMigrationsDir: string): string {\n  return join(spaceMigrationsDir, SPACE_REFS_DIRNAME);\n}\n","import { readFile } from 'node:fs/promises';\nimport type { ContractSpaceHeadRef } from '@prisma-next/framework-components/control';\nimport { join } from 'pathe';\nimport { errorInvalidJson, errorInvalidRefFile } from './errors';\nimport { assertValidSpaceId, spaceMigrationDirectory, spaceRefsDirectory } from './space-layout';\n\nexport type { ContractSpaceHeadRef };\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error && (error as { code?: string }).code === code;\n}\n\n/**\n * Read the head ref (`hash` + `invariants`) for a contract space from\n * `<projectMigrationsDir>/<spaceId>/refs/head.json`.\n *\n * Returns `null` when the file does not exist (first emit). Surfaces\n * `MIGRATION.INVALID_JSON` / `MIGRATION.INVALID_REF_FILE` on a corrupt\n * `refs/head.json` so callers can distinguish \"no head ref on disk\"\n * (returns `null`) from \"head ref present but unreadable\" (throws).\n *\n * Validates the space id against `[a-z][a-z0-9_-]{0,63}` for the same\n * filesystem-safety reasons as the rest of the per-space helpers. The\n * helper is uniform across the app and extension spaces.\n */\nexport async function readContractSpaceHeadRef(\n  projectMigrationsDir: string,\n  spaceId: string,\n): Promise<ContractSpaceHeadRef | null> {\n  assertValidSpaceId(spaceId);\n\n  const filePath = join(\n    spaceRefsDirectory(spaceMigrationDirectory(projectMigrationsDir, spaceId)),\n    'head.json',\n  );\n\n  let raw: string;\n  try {\n    raw = await readFile(filePath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      return null;\n    }\n    throw error;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (e) {\n    throw errorInvalidJson(filePath, e instanceof Error ? e.message : String(e));\n  }\n\n  if (typeof parsed !== 'object' || parsed === null) {\n    throw errorInvalidRefFile(filePath, 'expected an object');\n  }\n  const obj = parsed as { hash?: unknown; invariants?: unknown };\n  if (typeof obj.hash !== 'string') {\n    throw errorInvalidRefFile(filePath, 'expected an object with a string `hash` field');\n  }\n  if (!Array.isArray(obj.invariants) || obj.invariants.some((value) => typeof value !== 'string')) {\n    throw errorInvalidRefFile(filePath, 'expected an object with an `invariants` array of strings');\n  }\n\n  return { hash: obj.hash, invariants: obj.invariants as readonly string[] };\n}\n","import { readdir, stat } from 'node:fs/promises';\nimport { join } from 'pathe';\nimport { MANIFEST_FILE } from './io';\nimport { APP_SPACE_ID } from './space-layout';\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error && (error as { code?: string }).code === code;\n}\n\n/**\n * List the per-space subdirectories under\n * `<projectRoot>/migrations/`. Returns space-id directory names (sorted\n * alphabetically) — i.e. any non-dot-prefixed subdirectory whose root\n * does **not** contain a `migration.json` manifest. The manifest is the\n * structural marker of a user-authored migration directory (see\n * `readMigrationsDir` in `./io`); directory names themselves belong to\n * the user and are not part of the contract.\n *\n * Returns `[]` if the migrations directory does not exist (greenfield\n * project).\n *\n * Reads only the user's repo. **No descriptor import.** The caller\n * (verifier) feeds the result into {@link verifyContractSpaces} alongside\n * the loaded-space set and the marker rows.\n */\nexport async function listContractSpaceDirectories(\n  projectMigrationsDir: string,\n): Promise<readonly string[]> {\n  let entries: { readonly name: string; readonly isDirectory: boolean }[];\n  try {\n    const dirents = await readdir(projectMigrationsDir, { withFileTypes: true });\n    entries = dirents.map((d) => ({ name: d.name, isDirectory: d.isDirectory() }));\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      return [];\n    }\n    throw error;\n  }\n\n  const namedCandidates = entries\n    .filter((e) => e.isDirectory)\n    .map((e) => e.name)\n    .filter((name) => !name.startsWith('.'))\n    .sort();\n\n  const manifestChecks = await Promise.all(\n    namedCandidates.map(async (name) => {\n      try {\n        await stat(join(projectMigrationsDir, name, MANIFEST_FILE));\n        return { name, isMigrationDir: true };\n      } catch (error) {\n        if (hasErrnoCode(error, 'ENOENT')) {\n          return { name, isMigrationDir: false };\n        }\n        throw error;\n      }\n    }),\n  );\n\n  return manifestChecks.filter((c) => !c.isMigrationDir).map((c) => c.name);\n}\n\n/**\n * On-disk head value (`(hash, invariants)`) for one contract space.\n * The verifier compares this against the marker row for the same space\n * to detect drift between the user-emitted artefacts and the live DB\n * marker.\n */\nexport interface ContractSpaceHeadRecord {\n  readonly hash: string;\n  readonly invariants: readonly string[];\n}\n\n/**\n * Marker row read from `prisma_contract.marker` (one per `space`).\n * Caller resolves these via the family runtime's marker reader before\n * invoking {@link verifyContractSpaces}.\n */\nexport interface SpaceMarkerRecord {\n  readonly hash: string;\n  readonly invariants: readonly string[];\n}\n\nexport interface VerifyContractSpacesInputs {\n  /**\n   * Set of contract spaces the project declares: `'app'` plus each\n   * extension space in `extensionPacks`. The caller's discovery path\n   * never reads the extension descriptor module — it walks the\n   * `extensionPacks` configuration in `prisma-next.config.ts` for the\n   * space ids.\n   */\n  readonly loadedSpaces: ReadonlySet<string>;\n\n  /**\n   * Per-space subdirectories observed under\n   * `<projectRoot>/migrations/`. Resolved via\n   * {@link listContractSpaceDirectories}.\n   */\n  readonly spaceDirsOnDisk: readonly string[];\n\n  /**\n   * Head ref per space, keyed by space id. Caller reads\n   * `<projectRoot>/migrations/<space-id>/contract.json` and\n   * `<projectRoot>/migrations/<space-id>/refs/head.json` to construct\n   * this map. Spaces with no contract-space dir on disk simply omit a\n   * map entry.\n   */\n  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;\n\n  /**\n   * Marker rows keyed by `space`. Caller reads them from the\n   * `prisma_contract.marker` table.\n   */\n  readonly markerRowsBySpace: ReadonlyMap<string, SpaceMarkerRecord>;\n}\n\nexport type SpaceVerifierViolation =\n  | {\n      readonly kind: 'declaredButUnmigrated';\n      readonly spaceId: string;\n      readonly remediation: string;\n    }\n  | {\n      readonly kind: 'orphanMarker';\n      readonly spaceId: string;\n      readonly remediation: string;\n    }\n  | {\n      readonly kind: 'orphanSpaceDir';\n      readonly spaceId: string;\n      readonly remediation: string;\n    }\n  | {\n      readonly kind: 'hashMismatch';\n      readonly spaceId: string;\n      readonly priorHeadHash: string;\n      readonly markerHash: string;\n      readonly remediation: string;\n    }\n  | {\n      readonly kind: 'invariantsMismatch';\n      readonly spaceId: string;\n      readonly onDiskInvariants: readonly string[];\n      readonly markerInvariants: readonly string[];\n      readonly remediation: string;\n    };\n\nexport type VerifyContractSpacesResult =\n  | { readonly ok: true }\n  | { readonly ok: false; readonly violations: readonly SpaceVerifierViolation[] };\n\n/**\n * Pure structural verifier for the per-space mechanism. Aggregates the\n * three orphan / missing checks plus per-space hash and invariant\n * comparison.\n *\n * Algorithm:\n *\n * - For every extension space declared in `loadedSpaces` (`'app'`\n *   excluded — the per-space verifier is scoped to extension members;\n *   the app is verified through the aggregate path):\n *   - If no contract-space dir on disk → `declaredButUnmigrated`.\n *   - Else if `markerRowsBySpace` lacks an entry → no violation here;\n *     the live-DB compare done outside this helper is where the\n *     absence shows up.\n *   - Else compare marker hash / invariants vs. on-disk head hash /\n *     invariants → `hashMismatch` / `invariantsMismatch` on drift.\n * - For every contract-space dir on disk that is not in `loadedSpaces` →\n *   `orphanSpaceDir`.\n * - For every marker row whose `space` is not in `loadedSpaces` →\n *   `orphanMarker`. The app-space marker is always loaded (`'app'` is\n *   in `loadedSpaces` by definition).\n *\n * Output is deterministic: violations are sorted first by `kind`\n * (`declaredButUnmigrated` → `orphanMarker` → `orphanSpaceDir` →\n * `hashMismatch` → `invariantsMismatch`) then by `spaceId`. Two callers\n * passing equivalent inputs see byte-identical violation lists.\n *\n * Synchronous, pure, no I/O. **Does not import the extension descriptor**\n * (the inputs are pre-resolved by the caller); the verifier reads only\n * the user repo, not `node_modules`.\n */\nexport function verifyContractSpaces(\n  inputs: VerifyContractSpacesInputs,\n): VerifyContractSpacesResult {\n  const violations: SpaceVerifierViolation[] = [];\n\n  for (const spaceId of [...inputs.loadedSpaces].sort()) {\n    if (spaceId === APP_SPACE_ID) continue;\n\n    if (!inputs.spaceDirsOnDisk.includes(spaceId)) {\n      violations.push({\n        kind: 'declaredButUnmigrated',\n        spaceId,\n        remediation: `Extension '${spaceId}' is declared in extensionPacks but has not been emitted; run \\`prisma-next migrate\\`.`,\n      });\n      continue;\n    }\n\n    const head = inputs.headRefsBySpace.get(spaceId);\n    const marker = inputs.markerRowsBySpace.get(spaceId);\n    if (!head || !marker) {\n      continue;\n    }\n\n    if (head.hash !== marker.hash) {\n      violations.push({\n        kind: 'hashMismatch',\n        spaceId,\n        priorHeadHash: head.hash,\n        markerHash: marker.hash,\n        remediation: `Marker row for space '${spaceId}' is keyed at ${marker.hash}, but the on-disk ${join('migrations', spaceId, 'contract.json')} resolves to ${head.hash}. Run \\`prisma-next db update\\` to advance the database, or \\`prisma-next migrate\\` if the descriptor was bumped without re-emitting.`,\n      });\n      continue;\n    }\n\n    const onDiskInvariants = [...head.invariants].sort();\n    const markerInvariants = new Set(marker.invariants);\n    const missing = onDiskInvariants.filter((id) => !markerInvariants.has(id));\n    if (missing.length > 0) {\n      violations.push({\n        kind: 'invariantsMismatch',\n        spaceId,\n        onDiskInvariants,\n        markerInvariants: [...marker.invariants].sort(),\n        remediation: `Marker row for space '${spaceId}' is missing invariants [${missing.map((s) => JSON.stringify(s)).join(', ')}]. Run \\`prisma-next db update\\` to apply the corresponding data-transform migrations.`,\n      });\n    }\n  }\n\n  for (const dir of [...inputs.spaceDirsOnDisk].sort()) {\n    if (!inputs.loadedSpaces.has(dir)) {\n      violations.push({\n        kind: 'orphanSpaceDir',\n        spaceId: dir,\n        remediation: `Orphan contract-space directory \\`${join('migrations', dir)}/\\` for an extension not in extensionPacks; remove the directory or re-add the extension.`,\n      });\n    }\n  }\n\n  for (const space of [...inputs.markerRowsBySpace.keys()].sort()) {\n    if (!inputs.loadedSpaces.has(space)) {\n      violations.push({\n        kind: 'orphanMarker',\n        spaceId: space,\n        remediation: `Orphan marker row for space '${space}' (no longer in extensionPacks); remediation: manually delete the row from \\`prisma_contract.marker\\`.`,\n      });\n    }\n  }\n\n  if (violations.length === 0) {\n    return { ok: true };\n  }\n\n  const kindOrder: Record<SpaceVerifierViolation['kind'], number> = {\n    declaredButUnmigrated: 0,\n    orphanMarker: 1,\n    orphanSpaceDir: 2,\n    hashMismatch: 3,\n    invariantsMismatch: 4,\n  };\n\n  violations.sort((a, b) => {\n    const k = kindOrder[a.kind] - kindOrder[b.kind];\n    if (k !== 0) return k;\n    if (a.spaceId < b.spaceId) return -1;\n    if (a.spaceId > b.spaceId) return 1;\n    return 0;\n  });\n\n  return { ok: false, violations };\n}\n","import { readFile } from 'node:fs/promises';\nimport { join } from 'pathe';\nimport { errorInvalidJson, errorMissingFile } from './errors';\nimport { assertValidSpaceId } from './space-layout';\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error && (error as { code?: string }).code === code;\n}\n\n/**\n * Read the on-disk contract value for a contract space\n * (`<projectMigrationsDir>/<spaceId>/contract.json`). Returns the parsed\n * JSON value as `unknown` — callers that need a typed contract validate\n * via their family's `deserializeContract` to surface schema issues.\n *\n * Companion to {@link import('./read-contract-space-head-ref').readContractSpaceHeadRef}\n * — same ENOENT-throws / corrupt-file-error semantics. Returns the\n * canonical-JSON value the framework wrote during emit, so re-running\n * this helper across machines / runs yields a byte-identical value.\n */\nexport async function readContractSpaceContract(\n  projectMigrationsDir: string,\n  spaceId: string,\n): Promise<unknown> {\n  assertValidSpaceId(spaceId);\n\n  const filePath = join(projectMigrationsDir, spaceId, 'contract.json');\n\n  let raw: string;\n  try {\n    raw = await readFile(filePath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile('contract.json', join(projectMigrationsDir, spaceId));\n    }\n    throw error;\n  }\n\n  try {\n    return JSON.parse(raw);\n  } catch (e) {\n    throw errorInvalidJson(filePath, e instanceof Error ? e.message : String(e));\n  }\n}\n"],"mappings":"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"}

package/dist/{refs-BDHo5l_g.mjs → refs-C-_WUrPw.mjs}

@@ -1,8 +1,14 @@
-import { h as errorInvalidRefValue, m as errorInvalidRefName, p as errorInvalidRefFile, t as MigrationToolsError } from "./errors-DGYwcwXs.mjs";
+import { _ as errorInvalidRefValue, g as errorInvalidRefName, h as errorInvalidRefFile, t as MigrationToolsError } from "./errors-vFROOhCR.mjs";
 import { dirname, join, relative } from "pathe";
 import { mkdir, readFile, readdir, rename, rmdir, unlink, writeFile } from "node:fs/promises";
 import { type } from "arktype";
 //#region src/refs.ts
+/**
+* The system head ref lives at `refs/head.json`. It is read (and its
+* corruption judged) through `readContractSpaceHeadRef`, not as a
+* user-authored ref, so {@link readRefsTolerant} excludes it.
+*/
+const HEAD_REF_NAME = "head";
 const REF_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
 const REF_VALUE_PATTERN = /^sha256:(empty|[0-9a-f]{64})$/;
 function validateRefName(name) {
@@ -66,7 +72,7 @@ async function readRefs(refsDir) {
 		if (error instanceof Error && error.code === "ENOENT") return {};
 		throw error;
 	}
-	const jsonFiles = entries.filter((entry) => entry.endsWith(".json"));
+	const jsonFiles = entries.filter((entry) => entry.endsWith(".json") && !entry.endsWith(".contract.json"));
 	const refs = {};
 	for (const jsonFile of jsonFiles) {
 		const filePath = join(refsDir, jsonFile);
@@ -91,6 +97,72 @@ async function readRefs(refsDir) {
 	}
 	return refs;
 }
+/**
+* Read a space's user-authored refs without ever throwing on disk
+* content. A ref whose JSON is unparseable or whose shape fails
+* {@link RefEntrySchema} is omitted from `refs` and reported as a
+* {@link RefLoadProblem}; the remaining well-formed refs are still
+* returned. A missing `refs/` directory yields no refs and no problems.
+*
+* `refs/head.json` is deliberately skipped here: the system head ref is
+* read through `readContractSpaceHeadRef` (which validates head-ref
+* shape, distinct from the strict user-ref hash grammar), so it is judged
+* there and never doubles as a user ref. Genuine I/O faults (EACCES, EIO,
+* …) still propagate — only parse / schema problems are made tolerant.
+*/
+async function readRefsTolerant(refsDir) {
+	let entries;
+	try {
+		entries = await readdir(refsDir, {
+			recursive: true,
+			encoding: "utf-8"
+		});
+	} catch (error) {
+		if (error instanceof Error && error.code === "ENOENT") return {
+			refs: {},
+			problems: []
+		};
+		throw error;
+	}
+	const jsonFiles = entries.filter((entry) => entry.endsWith(".json") && !entry.endsWith(".contract.json") && entry !== `head.json`);
+	const refs = {};
+	const problems = [];
+	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 (e) {
+			problems.push({
+				refName: name,
+				detail: e instanceof Error ? e.message : String(e)
+			});
+			continue;
+		}
+		const result = RefEntrySchema(parsed);
+		if (result instanceof type.errors) {
+			problems.push({
+				refName: name,
+				detail: result.summary
+			});
+			continue;
+		}
+		refs[name] = result;
+	}
+	return {
+		refs,
+		problems
+	};
+}
 async function writeRef(refsDir, name, entry) {
 	if (!validateRefName(name)) throw errorInvalidRefName(name);
 	if (!validateRefValue(entry.hash)) throw errorInvalidRefValue(entry.hash);
@@ -130,6 +202,27 @@ async function deleteRef(refsDir, name) {
 		throw error;
 	}
 }
+/**
+* Index user-authored refs by the contract hash each ref points at.
+* Each bucket is sorted lex-asc for deterministic output.
+*/
+function refsByContractHash(refs) {
+	const byHash = /* @__PURE__ */ new Map();
+	for (const [name, entry] of Object.entries(refs)) {
+		const bucket = byHash.get(entry.hash);
+		if (bucket) bucket.push(name);
+		else byHash.set(entry.hash, [name]);
+	}
+	for (const bucket of byHash.values()) bucket.sort();
+	return byHash;
+}
+/**
+* Read `migrations/<space>/refs/*.json` and index by destination hash.
+* Returns an empty map when the refs directory does not exist.
+*/
+async function resolveRefsByContractHash(refsDir) {
+	return refsByContractHash(await readRefs(refsDir));
+}
 function resolveRef(refs, name) {
 	if (!validateRefName(name)) throw errorInvalidRefName(name);
 	if (!Object.hasOwn(refs, name)) throw new MigrationToolsError("MIGRATION.UNKNOWN_REF", `Unknown ref "${name}"`, {
@@ -143,6 +236,6 @@ function resolveRef(refs, name) {
 	return refs[name];
 }
 //#endregion
-export { validateRefName as a, resolveRef as i, readRef as n, validateRefValue as o, readRefs as r, writeRef as s, deleteRef as t };
+export { readRefsTolerant as a, resolveRefsByContractHash as c, writeRef as d, readRefs as i, validateRefName as l, deleteRef as n, refsByContractHash as o, readRef as r, resolveRef as s, HEAD_REF_NAME as t, validateRefValue as u };
 
-//# sourceMappingURL=refs-BDHo5l_g.mjs.map
+//# sourceMappingURL=refs-C-_WUrPw.mjs.map

package/dist/refs-C-_WUrPw.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs-C-_WUrPw.mjs","names":[],"sources":["../src/refs.ts"],"sourcesContent":["import { mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { dirname, join, relative } from 'pathe';\nimport {\n  errorInvalidRefFile,\n  errorInvalidRefName,\n  errorInvalidRefValue,\n  MigrationToolsError,\n} from './errors';\n\nexport interface RefEntry {\n  readonly hash: string;\n  readonly invariants: readonly string[];\n}\n\nexport type Refs = Readonly<Record<string, RefEntry>>;\n\n/**\n * The system head ref lives at `refs/head.json`. It is read (and its\n * corruption judged) through `readContractSpaceHeadRef`, not as a\n * user-authored ref, so {@link readRefsTolerant} excludes it.\n */\nexport const HEAD_REF_NAME = 'head';\n\n/**\n * A single ref file that exists on disk but cannot be turned into a\n * {@link RefEntry} (unparseable JSON or schema-invalid content). The ref\n * is omitted from the result; the problem is surfaced for the integrity\n * layer to report as `refUnreadable` rather than aborting the load.\n */\nexport interface RefLoadProblem {\n  readonly refName: string;\n  readonly detail: string;\n}\n\nexport interface TolerantRefsResult {\n  readonly refs: Refs;\n  readonly problems: readonly RefLoadProblem[];\n}\n\nconst REF_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;\nconst REF_VALUE_PATTERN = /^sha256:(empty|[0-9a-f]{64})$/;\n\nexport function validateRefName(name: string): boolean {\n  if (name.length === 0) return false;\n  if (name.includes('..')) return false;\n  if (name.includes('//')) return false;\n  if (name.startsWith('.')) return false;\n  return REF_NAME_PATTERN.test(name);\n}\n\nexport function validateRefValue(value: string): boolean {\n  return REF_VALUE_PATTERN.test(value);\n}\n\nconst RefEntrySchema = type({\n  hash: 'string',\n  invariants: 'string[]',\n}).narrow((entry, ctx) => {\n  if (!validateRefValue(entry.hash))\n    return ctx.mustBe(`a valid contract hash (got \"${entry.hash}\")`);\n  return true;\n});\n\nfunction refFilePath(refsDir: string, name: string): string {\n  return join(refsDir, `${name}.json`);\n}\n\nfunction refNameFromPath(refsDir: string, filePath: string): string {\n  const rel = relative(refsDir, filePath);\n  return rel.replace(/\\.json$/, '');\n}\n\nexport async function readRef(refsDir: string, name: string): Promise<RefEntry> {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  const filePath = refFilePath(refsDir, name);\n  let raw: string;\n  try {\n    raw = await readFile(filePath, 'utf-8');\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n        why: `No ref file found at \"${filePath}\".`,\n        fix: `Create the ref with: prisma-next ref set ${name} <hash>`,\n        details: { refName: name, filePath },\n      });\n    }\n    throw error;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');\n  }\n\n  const result = RefEntrySchema(parsed);\n  if (result instanceof type.errors) {\n    throw errorInvalidRefFile(filePath, result.summary);\n  }\n\n  return result;\n}\n\nexport async function readRefs(refsDir: string): Promise<Refs> {\n  let entries: string[];\n  try {\n    entries = await readdir(refsDir, { recursive: true, encoding: 'utf-8' });\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      return {};\n    }\n    throw error;\n  }\n\n  const jsonFiles = entries.filter(\n    (entry) => entry.endsWith('.json') && !entry.endsWith('.contract.json'),\n  );\n  const refs: Record<string, RefEntry> = {};\n\n  for (const jsonFile of jsonFiles) {\n    const filePath = join(refsDir, jsonFile);\n    const name = refNameFromPath(refsDir, filePath);\n\n    let raw: string;\n    try {\n      raw = await readFile(filePath, 'utf-8');\n    } catch (error) {\n      // Tolerate the TOCTOU race between `readdir` and `readFile` (ENOENT) and\n      // benign EISDIR if a directory happens to end in `.json`. Anything else\n      // (EACCES, EIO, EMFILE, …) is a real failure and propagates so the CLI\n      // surfaces it rather than silently dropping the ref.\n      const code = error instanceof Error ? (error as { code?: string }).code : undefined;\n      if (code === 'ENOENT' || code === 'EISDIR') {\n        continue;\n      }\n      throw error;\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');\n    }\n\n    const result = RefEntrySchema(parsed);\n    if (result instanceof type.errors) {\n      throw errorInvalidRefFile(filePath, result.summary);\n    }\n\n    refs[name] = result;\n  }\n\n  return refs;\n}\n\n/**\n * Read a space's user-authored refs without ever throwing on disk\n * content. A ref whose JSON is unparseable or whose shape fails\n * {@link RefEntrySchema} is omitted from `refs` and reported as a\n * {@link RefLoadProblem}; the remaining well-formed refs are still\n * returned. A missing `refs/` directory yields no refs and no problems.\n *\n * `refs/head.json` is deliberately skipped here: the system head ref is\n * read through `readContractSpaceHeadRef` (which validates head-ref\n * shape, distinct from the strict user-ref hash grammar), so it is judged\n * there and never doubles as a user ref. Genuine I/O faults (EACCES, EIO,\n * …) still propagate — only parse / schema problems are made tolerant.\n */\nexport async function readRefsTolerant(refsDir: string): Promise<TolerantRefsResult> {\n  let entries: string[];\n  try {\n    entries = await readdir(refsDir, { recursive: true, encoding: 'utf-8' });\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      return { refs: {}, problems: [] };\n    }\n    throw error;\n  }\n\n  const jsonFiles = entries.filter(\n    (entry) =>\n      entry.endsWith('.json') &&\n      !entry.endsWith('.contract.json') &&\n      entry !== `${HEAD_REF_NAME}.json`,\n  );\n  const refs: Record<string, RefEntry> = {};\n  const problems: RefLoadProblem[] = [];\n\n  for (const jsonFile of jsonFiles) {\n    const filePath = join(refsDir, jsonFile);\n    const name = refNameFromPath(refsDir, filePath);\n\n    let raw: string;\n    try {\n      raw = await readFile(filePath, 'utf-8');\n    } catch (error) {\n      // Tolerate the TOCTOU race between `readdir` and `readFile` (ENOENT)\n      // and benign EISDIR if a directory happens to end in `.json`.\n      // Anything else (EACCES, EIO, …) is a real failure and propagates.\n      const code = error instanceof Error ? (error as { code?: string }).code : undefined;\n      if (code === 'ENOENT' || code === 'EISDIR') {\n        continue;\n      }\n      throw error;\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch (e) {\n      problems.push({ refName: name, detail: e instanceof Error ? e.message : String(e) });\n      continue;\n    }\n\n    const result = RefEntrySchema(parsed);\n    if (result instanceof type.errors) {\n      problems.push({ refName: name, detail: result.summary });\n      continue;\n    }\n\n    refs[name] = result;\n  }\n\n  return { refs, problems };\n}\n\nexport async function writeRef(refsDir: string, name: string, entry: RefEntry): Promise<void> {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n  if (!validateRefValue(entry.hash)) {\n    throw errorInvalidRefValue(entry.hash);\n  }\n\n  const filePath = refFilePath(refsDir, name);\n  const dir = dirname(filePath);\n  await mkdir(dir, { recursive: true });\n\n  const tmpPath = join(dir, `.${name.split('/').pop()}.json.${Date.now()}.tmp`);\n  await writeFile(\n    tmpPath,\n    `${JSON.stringify({ hash: entry.hash, invariants: [...entry.invariants] }, null, 2)}\\n`,\n  );\n  await rename(tmpPath, filePath);\n}\n\nexport async function deleteRef(refsDir: string, name: string): Promise<void> {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  const filePath = refFilePath(refsDir, name);\n  try {\n    await unlink(filePath);\n  } catch (error) {\n    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {\n      throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n        why: `No ref file found at \"${filePath}\".`,\n        fix: 'Run `prisma-next ref list` to see available refs.',\n        details: { refName: name, filePath },\n      });\n    }\n    throw error;\n  }\n\n  // Clean empty parent directories up to refsDir. Stop walking on the expected\n  // \"directory has siblings\" signal (ENOTEMPTY on Linux, EEXIST on some BSDs)\n  // and on ENOENT (concurrent removal). Anything else (EACCES, EIO, …) is a\n  // real failure and propagates.\n  let dir = dirname(filePath);\n  while (dir !== refsDir && dir.startsWith(refsDir)) {\n    try {\n      await rmdir(dir);\n      dir = dirname(dir);\n    } catch (error) {\n      const code = error instanceof Error ? (error as { code?: string }).code : undefined;\n      if (code === 'ENOTEMPTY' || code === 'EEXIST' || code === 'ENOENT') {\n        break;\n      }\n      throw error;\n    }\n  }\n}\n\n/**\n * Index user-authored refs by the contract hash each ref points at.\n * Each bucket is sorted lex-asc for deterministic output.\n */\nexport function refsByContractHash(refs: Refs): ReadonlyMap<string, readonly string[]> {\n  const byHash = new Map<string, string[]>();\n  for (const [name, entry] of Object.entries(refs)) {\n    const bucket = byHash.get(entry.hash);\n    if (bucket) bucket.push(name);\n    else byHash.set(entry.hash, [name]);\n  }\n  for (const bucket of byHash.values()) {\n    bucket.sort();\n  }\n  return byHash;\n}\n\n/**\n * Read `migrations/<space>/refs/*.json` and index by destination hash.\n * Returns an empty map when the refs directory does not exist.\n */\nexport async function resolveRefsByContractHash(\n  refsDir: string,\n): Promise<ReadonlyMap<string, readonly string[]>> {\n  return refsByContractHash(await readRefs(refsDir));\n}\n\nexport function resolveRef(refs: Refs, name: string): RefEntry {\n  if (!validateRefName(name)) {\n    throw errorInvalidRefName(name);\n  }\n\n  // Object.hasOwn gate: plain-object `refs` would otherwise let\n  // `refs['constructor']` return Object.prototype.constructor and bypass the\n  // UNKNOWN_REF throw. validateRefName accepts `\"constructor\"` as a name shape.\n  if (!Object.hasOwn(refs, name)) {\n    throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref \"${name}\"`, {\n      why: `No ref named \"${name}\" exists.`,\n      fix: `Available refs: ${Object.keys(refs).join(', ') || '(none)'}. Create a ref with: prisma-next ref set ${name} <hash>`,\n      details: { refName: name, availableRefs: Object.keys(refs) },\n    });\n  }\n\n  // biome-ignore lint/style/noNonNullAssertion: Object.hasOwn gate above guarantees this is defined\n  return refs[name]!;\n}\n"],"mappings":"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"}

package/dist/refs-C7wuYFqZ.d.mts

@@ -0,0 +1,42 @@
+//#region src/refs.d.ts
+interface RefEntry {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+type Refs = Readonly<Record<string, RefEntry>>;
+/**
+ * The system head ref lives at `refs/head.json`. It is read (and its
+ * corruption judged) through `readContractSpaceHeadRef`, not as a
+ * user-authored ref, so {@link readRefsTolerant} excludes it.
+ */
+declare const HEAD_REF_NAME = "head";
+/**
+ * A single ref file that exists on disk but cannot be turned into a
+ * {@link RefEntry} (unparseable JSON or schema-invalid content). The ref
+ * is omitted from the result; the problem is surfaced for the integrity
+ * layer to report as `refUnreadable` rather than aborting the load.
+ */
+interface RefLoadProblem {
+  readonly refName: string;
+  readonly detail: string;
+}
+declare function validateRefName(name: string): boolean;
+declare function validateRefValue(value: string): boolean;
+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>;
+/**
+ * Index user-authored refs by the contract hash each ref points at.
+ * Each bucket is sorted lex-asc for deterministic output.
+ */
+declare function refsByContractHash(refs: Refs): ReadonlyMap<string, readonly string[]>;
+/**
+ * Read `migrations/<space>/refs/*.json` and index by destination hash.
+ * Returns an empty map when the refs directory does not exist.
+ */
+declare function resolveRefsByContractHash(refsDir: string): Promise<ReadonlyMap<string, readonly string[]>>;
+declare function resolveRef(refs: Refs, name: string): RefEntry;
+//#endregion
+export { deleteRef as a, refsByContractHash as c, validateRefName as d, validateRefValue as f, Refs as i, resolveRef as l, RefEntry as n, readRef as o, writeRef as p, RefLoadProblem as r, readRefs as s, HEAD_REF_NAME as t, resolveRefsByContractHash as u };
+//# sourceMappingURL=refs-C7wuYFqZ.d.mts.map

package/dist/refs-C7wuYFqZ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs-C7wuYFqZ.d.mts","names":[],"sources":["../src/refs.ts"],"mappings":";UAUiB,QAAA;EAAA,SACN,IAAA;EAAA,SACA,UAAU;AAAA;AAAA,KAGT,IAAA,GAAO,QAAA,CAAS,MAAA,SAAe,QAAA;AAHtB;AAGrB;;;;AAHqB,cAUR,aAAA;;;;;;;UAQI,cAAA;EAAA,SACN,OAAA;EAAA,SACA,MAAM;AAAA;AAAA,iBAWD,eAAA,CAAgB,IAAY;AAAA,iBAQ5B,gBAAA,CAAiB,KAAa;AAAA,iBAsBxB,OAAA,CAAQ,OAAA,UAAiB,IAAA,WAAe,OAAO,CAAC,QAAA;AAAA,iBAmChD,QAAA,CAAS,OAAA,WAAkB,OAAO,CAAC,IAAA;AAAA,iBA4HnC,QAAA,CAAS,OAAA,UAAiB,IAAA,UAAc,KAAA,EAAO,QAAA,GAAW,OAAO;AAAA,iBAoBjE,SAAA,CAAU,OAAA,UAAiB,IAAA,WAAe,OAAO;;;;AAnLO;iBA6N9D,kBAAA,CAAmB,IAAA,EAAM,IAAA,GAAO,WAAW;;;;;iBAiBrC,yBAAA,CACpB,OAAA,WACC,OAAO,CAAC,WAAA;AAAA,iBAIK,UAAA,CAAW,IAAA,EAAM,IAAA,EAAM,IAAA,WAAe,QAAQ"}