@prisma-next/migration-tools 0.5.0-dev.2 → 0.5.0-dev.21

package/src/migration-base.ts

@@ -8,8 +8,10 @@ import type {
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type } from 'arktype';
-import { computeMigrationId } from './attestation';
-import type { MigrationHints, MigrationManifest, MigrationOps } from './types';
+import { computeMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
+import type { MigrationHints, MigrationMetadata } from './metadata';
+import type { MigrationOps } from './package';
 
 export interface MigrationMeta {
   readonly from: string;
@@ -30,7 +32,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.
  */
@@ -123,64 +125,68 @@ function printHelp(): 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.
  */
 export interface MigrationArtifacts {
   readonly opsJson: string;
-  readonly manifest: MigrationManifest;
-  readonly manifestJson: string;
+  readonly metadata: MigrationMetadata;
+  readonly metadataJson: string;
 }
 
 /**
- * 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
+ * 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(
+function buildAttestedMetadata(
   meta: MigrationMeta,
   ops: MigrationOps,
-  existing: Partial<MigrationManifest> | null,
-): MigrationManifest {
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  existing: Partial<MigrationMetadata> | null,
+): MigrationMetadata {
+  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: meta.from,
     to: meta.to,
     kind: meta.kind ?? 'regular',
     labels: meta.labels ?? existing?.labels ?? [],
+    providedInvariants: deriveProvidedInvariants(ops),
     createdAt: existing?.createdAt ?? new Date().toISOString(),
     fromContract: existing?.fromContract ?? null,
-    // When no scaffolded manifest exists we synthesize a minimal contract
+    // When no scaffolded metadata exists we synthesize a minimal contract
     // stub so the package is still readable end-to-end. The cast is
     // intentional: only the storage bookend matters for hash computation
-    // (everything else is stripped by `computeMigrationId`), and a real
+    // (everything else is stripped by `computeMigrationHash`), and a real
     // contract bookend would only be available after `migration plan`.
     toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),
     hints: normalizeHints(existing?.hints),
     ...ifDefined('authorship', existing?.authorship),
   };
 
-  const migrationId = computeMigrationId(baseManifest, ops);
-  return { ...baseManifest, migrationId };
+  const migrationHash = computeMigrationHash(baseMetadata, ops);
+  return { ...baseMetadata, migrationHash };
 }
 
 /**
  * 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.
@@ -195,16 +201,16 @@ function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
 
 /**
  * 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`).
  */
 export function buildMigrationArtifacts(
   instance: Migration,
-  existing: Partial<MigrationManifest> | null,
+  existing: Partial<MigrationMetadata> | null,
 ): MigrationArtifacts {
   const ops = instance.operations;
   if (!Array.isArray(ops)) {
@@ -217,11 +223,11 @@ export function buildMigrationArtifacts(
     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),
   };
 }

package/src/{dag.ts → migration-graph.ts}

@@ -2,13 +2,14 @@ import { ifDefined } from '@prisma-next/utils/defined';
 import { EMPTY_CONTRACT_HASH } from './constants';
 import {
   errorAmbiguousTarget,
-  errorDuplicateMigrationId,
+  errorDuplicateMigrationHash,
   errorNoInitialMigration,
   errorNoTarget,
   errorSameSourceAndTarget,
 } from './errors';
+import type { MigrationEdge, MigrationGraph } from './graph';
 import { bfs } from './graph-ops';
-import type { MigrationBundle, MigrationChainEntry, MigrationGraph } from './types';
+import type { MigrationPackage } from './package';
 
 /** Forward-edge neighbours for BFS: edge `e` from `n` visits `e.to` next. */
 function forwardNeighbours(graph: MigrationGraph, node: string) {
@@ -20,57 +21,54 @@ function reverseNeighbours(graph: MigrationGraph, node: string) {
   return (graph.reverseChain.get(node) ?? []).map((edge) => ({ next: edge.from, edge }));
 }
 
-function appendEdge(
-  map: Map<string, MigrationChainEntry[]>,
-  key: string,
-  entry: MigrationChainEntry,
-): void {
+function appendEdge(map: Map<string, MigrationEdge[]>, key: string, entry: MigrationEdge): void {
   const bucket = map.get(key);
   if (bucket) bucket.push(entry);
   else map.set(key, [entry]);
 }
 
-export function reconstructGraph(packages: readonly MigrationBundle[]): MigrationGraph {
+export function reconstructGraph(packages: readonly MigrationPackage[]): MigrationGraph {
   const nodes = new Set<string>();
-  const forwardChain = new Map<string, MigrationChainEntry[]>();
-  const reverseChain = new Map<string, MigrationChainEntry[]>();
-  const migrationById = new Map<string, MigrationChainEntry>();
+  const forwardChain = new Map<string, MigrationEdge[]>();
+  const reverseChain = new Map<string, MigrationEdge[]>();
+  const migrationByHash = new Map<string, MigrationEdge>();
 
   for (const pkg of packages) {
-    const { from, to } = pkg.manifest;
+    const { from, to } = pkg.metadata;
 
     if (from === to) {
-      throw errorSameSourceAndTarget(pkg.dirName, from);
+      throw errorSameSourceAndTarget(pkg.dirPath, from);
     }
 
     nodes.add(from);
     nodes.add(to);
 
-    const migration: MigrationChainEntry = {
+    const migration: MigrationEdge = {
       from,
       to,
-      migrationId: pkg.manifest.migrationId,
+      migrationHash: pkg.metadata.migrationHash,
       dirName: pkg.dirName,
-      createdAt: pkg.manifest.createdAt,
-      labels: pkg.manifest.labels,
+      createdAt: pkg.metadata.createdAt,
+      labels: pkg.metadata.labels,
+      invariants: pkg.metadata.providedInvariants,
     };
 
-    if (migrationById.has(migration.migrationId)) {
-      throw errorDuplicateMigrationId(migration.migrationId);
+    if (migrationByHash.has(migration.migrationHash)) {
+      throw errorDuplicateMigrationHash(migration.migrationHash);
     }
-    migrationById.set(migration.migrationId, migration);
+    migrationByHash.set(migration.migrationHash, migration);
 
     appendEdge(forwardChain, from, migration);
     appendEdge(reverseChain, to, migration);
   }
 
-  return { nodes, forwardChain, reverseChain, migrationById };
+  return { nodes, forwardChain, reverseChain, migrationByHash };
 }
 
 // ---------------------------------------------------------------------------
 // Deterministic tie-breaking for BFS neighbour order.
 // Used by `findPath` and `findPathWithDecision` only; not a general-purpose
-// utility. Ordering: label priority → createdAt → to → migrationId.
+// utility. Ordering: label priority → createdAt → to → migrationHash.
 // ---------------------------------------------------------------------------
 
 const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
@@ -84,24 +82,24 @@ function labelPriority(labels: readonly string[]): number {
   return best;
 }
 
-function compareTieBreak(a: MigrationChainEntry, b: MigrationChainEntry): number {
+function compareTieBreak(a: MigrationEdge, b: MigrationEdge): number {
   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);
   if (tc !== 0) return tc;
-  return a.migrationId.localeCompare(b.migrationId);
+  return a.migrationHash.localeCompare(b.migrationHash);
 }
 
-function sortedNeighbors(edges: readonly MigrationChainEntry[]): readonly MigrationChainEntry[] {
+function sortedNeighbors(edges: readonly MigrationEdge[]): readonly MigrationEdge[] {
   return [...edges].sort(compareTieBreak);
 }
 
 /** Ordering adapter for `bfs` — sorts `{next, edge}` pairs by tie-break. */
 function bfsOrdering(
-  items: readonly { next: string; edge: MigrationChainEntry }[],
-): readonly { next: string; edge: MigrationChainEntry }[] {
+  items: readonly { next: string; edge: MigrationEdge }[],
+): readonly { next: string; edge: MigrationEdge }[] {
   return items.slice().sort((a, b) => compareTieBreak(a.edge, b.edge));
 }
 
@@ -111,22 +109,22 @@ function bfsOrdering(
  * exists. Returns an empty array when `fromHash === toHash` (no-op).
  *
  * Neighbor ordering is deterministic via the tie-break sort key:
- * label priority → createdAt → to → migrationId.
+ * label priority → createdAt → to → migrationHash.
  */
 export function findPath(
   graph: MigrationGraph,
   fromHash: string,
   toHash: string,
-): readonly MigrationChainEntry[] | null {
+): readonly MigrationEdge[] | null {
   if (fromHash === toHash) return [];
 
-  const parents = new Map<string, { parent: string; edge: MigrationChainEntry }>();
+  const parents = new Map<string, { parent: string; edge: MigrationEdge }>();
   for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n), bfsOrdering)) {
     if (step.parent !== null && step.incomingEdge !== null) {
       parents.set(step.node, { parent: step.parent, edge: step.incomingEdge });
     }
     if (step.node === toHash) {
-      const path: MigrationChainEntry[] = [];
+      const path: MigrationEdge[] = [];
       let cur = toHash;
       let p = parents.get(cur);
       while (p) {
@@ -155,7 +153,7 @@ function collectNodesReachingTarget(graph: MigrationGraph, toHash: string): Set<
 }
 
 export interface PathDecision {
-  readonly selectedPath: readonly MigrationChainEntry[];
+  readonly selectedPath: readonly MigrationEdge[];
   readonly fromHash: string;
   readonly toHash: string;
   readonly alternativeCount: number;
@@ -202,8 +200,8 @@ export function findPathWithDecision(
       if (reachable.length > 1) {
         alternativeCount += reachable.length - 1;
         const sorted = sortedNeighbors(reachable);
-        if (sorted[0] && sorted[0].migrationId === edge.migrationId) {
-          if (reachable.some((e) => e.migrationId !== edge.migrationId)) {
+        if (sorted[0] && sorted[0].migrationHash === edge.migrationHash) {
+          if (reachable.some((e) => e.migrationHash !== edge.migrationHash)) {
             tieBreakReasons.push(
               `at ${edge.from}: ${reachable.length} candidates, selected by tie-break`,
             );
@@ -319,7 +317,7 @@ export function findLeaf(graph: MigrationGraph): string | null {
  * to the single target. Returns null for an empty graph.
  * Throws AMBIGUOUS_TARGET if the graph has multiple branch tips.
  */
-export function findLatestMigration(graph: MigrationGraph): MigrationChainEntry | null {
+export function findLatestMigration(graph: MigrationGraph): MigrationEdge | null {
   const leafHash = findLeaf(graph);
   if (leafHash === null) return null;
 
@@ -343,7 +341,7 @@ export function detectCycles(graph: MigrationGraph): readonly string[][] {
   // Iterative three-color DFS. A frame is (node, outgoing edges, next-index).
   interface Frame {
     node: string;
-    outgoing: readonly MigrationChainEntry[];
+    outgoing: readonly MigrationEdge[];
     index: number;
   }
   const stack: Frame[] = [];
@@ -389,7 +387,7 @@ export function detectCycles(graph: MigrationGraph): readonly string[][] {
   return cycles;
 }
 
-export function detectOrphans(graph: MigrationGraph): readonly MigrationChainEntry[] {
+export function detectOrphans(graph: MigrationGraph): readonly MigrationEdge[] {
   if (graph.nodes.size === 0) return [];
 
   const reachable = new Set<string>();
@@ -415,7 +413,7 @@ export function detectOrphans(graph: MigrationGraph): readonly MigrationChainEnt
     reachable.add(step.node);
   }
 
-  const orphans: MigrationChainEntry[] = [];
+  const orphans: MigrationEdge[] = [];
   for (const [from, migrations] of graph.forwardChain) {
     if (!reachable.has(from)) {
       orphans.push(...migrations);

package/src/package.ts

@@ -0,0 +1,18 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import type { MigrationMetadata } from './metadata';
+
+export type MigrationOps = readonly MigrationPlanOperation[];
+
+/**
+ * An on-disk migration directory (a "package") with its parsed metadata and
+ * operations. Returned from `readMigrationPackage` / `readMigrationsDir` only
+ * after the loader has verified the package's integrity (hash recomputation
+ * against the stored `migrationHash`); holding a `MigrationPackage` value
+ * therefore implies the package is internally consistent.
+ */
+export interface MigrationPackage {
+  readonly dirName: string;
+  readonly dirPath: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: MigrationOps;
+}

package/src/refs.ts

@@ -1,14 +1,19 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';
 import { type } from 'arktype';
-import { dirname, join } from 'pathe';
+import { dirname, join, relative } from 'pathe';
 import {
+  errorInvalidRefFile,
   errorInvalidRefName,
-  errorInvalidRefs,
   errorInvalidRefValue,
   MigrationToolsError,
 } from './errors';
 
-export type Refs = Readonly<Record<string, string>>;
+export interface RefEntry {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+
+export type Refs = Readonly<Record<string, RefEntry>>;
 
 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})$/;
@@ -25,22 +30,40 @@ export function validateRefValue(value: string): boolean {
   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;
 });
 
-export async function readRefs(refsPath: string): Promise<Refs> {
+function refFilePath(refsDir: string, name: string): string {
+  return join(refsDir, `${name}.json`);
+}
+
+function refNameFromPath(refsDir: string, filePath: string): string {
+  const rel = relative(refsDir, filePath);
+  return rel.replace(/\.json$/, '');
+}
+
+export async function readRef(refsDir: string, name: string): Promise<RefEntry> {
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+
+  const filePath = refFilePath(refsDir, name);
   let raw: string;
   try {
-    raw = await readFile(refsPath, 'utf-8');
+    raw = await readFile(filePath, 'utf-8');
   } catch (error) {
     if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-      return {};
+      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;
   }
@@ -49,54 +72,142 @@ export async function readRefs(refsPath: string): Promise<Refs> {
   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);
+  const result = RefEntrySchema(parsed);
   if (result instanceof type.errors) {
-    throw errorInvalidRefs(refsPath, result.summary);
+    throw errorInvalidRefFile(filePath, result.summary);
   }
 
   return result;
 }
 
-export async function writeRefs(refsPath: string, refs: Refs): Promise<void> {
-  for (const [key, value] of Object.entries(refs)) {
-    if (!validateRefName(key)) {
-      throw errorInvalidRefName(key);
+export async function readRefs(refsDir: string): Promise<Refs> {
+  let entries: string[];
+  try {
+    entries = await readdir(refsDir, { recursive: true, encoding: 'utf-8' });
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+
+  const jsonFiles = entries.filter((entry) => entry.endsWith('.json'));
+  const refs: Record<string, RefEntry> = {};
+
+  for (const jsonFile of jsonFiles) {
+    const filePath = join(refsDir, jsonFile);
+    const name = refNameFromPath(refsDir, filePath);
+
+    let raw: string;
+    try {
+      raw = await readFile(filePath, 'utf-8');
+    } catch (error) {
+      // Tolerate the TOCTOU race between `readdir` and `readFile` (ENOENT) and
+      // benign EISDIR if a directory happens to end in `.json`. Anything else
+      // (EACCES, EIO, EMFILE, …) is a real failure and propagates so the CLI
+      // surfaces it rather than silently dropping the ref.
+      const code = error instanceof Error ? (error as { code?: string }).code : undefined;
+      if (code === 'ENOENT' || code === 'EISDIR') {
+        continue;
+      }
+      throw error;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');
     }
-    if (!validateRefValue(value)) {
-      throw errorInvalidRefValue(value);
+
+    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)));
+  return refs;
+}
+
+export async function writeRef(refsDir: string, name: string, entry: RefEntry): Promise<void> {
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+  if (!validateRefValue(entry.hash)) {
+    throw errorInvalidRefValue(entry.hash);
+  }
 
-  const dir = dirname(refsPath);
+  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);
 }
 
-export function resolveRef(refs: Refs, name: string): string {
+export async function deleteRef(refsDir: string, name: string): Promise<void> {
   if (!validateRefName(name)) {
     throw errorInvalidRefName(name);
   }
 
-  const hash = refs[name];
-  if (hash === undefined) {
+  const filePath = refFilePath(refsDir, name);
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).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;
+  }
+
+  // Clean empty parent directories up to refsDir. Stop walking on the expected
+  // "directory has siblings" signal (ENOTEMPTY on Linux, EEXIST on some BSDs)
+  // and on ENOENT (concurrent removal). Anything else (EACCES, EIO, …) is a
+  // real failure and propagates.
+  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 as { code?: string }).code : undefined;
+      if (code === 'ENOTEMPTY' || code === 'EEXIST' || code === 'ENOENT') {
+        break;
+      }
+      throw error;
+    }
+  }
+}
+
+export function resolveRef(refs: Refs, name: string): RefEntry {
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+
+  // Object.hasOwn gate: plain-object `refs` would otherwise let
+  // `refs['constructor']` return Object.prototype.constructor and bypass the
+  // UNKNOWN_REF throw. validateRefName accepts `"constructor"` as a name shape.
+  if (!Object.hasOwn(refs, name)) {
     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.`,
+      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;
+  // biome-ignore lint/style/noNonNullAssertion: Object.hasOwn gate above guarantees this is defined
+  return refs[name]!;
 }

package/dist/attestation-DtF8tEOM.mjs

@@ -1,65 +0,0 @@
-import { r as readMigrationPackage } from "./io-CCnYsUHU.mjs";
-import { createHash } from "node:crypto";
-
-//#region src/canonicalize-json.ts
-function sortKeys(value) {
-	if (value === null || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map(sortKeys);
-	const sorted = {};
-	for (const key of Object.keys(value).sort()) sorted[key] = sortKeys(value[key]);
-	return sorted;
-}
-function canonicalizeJson(value) {
-	return JSON.stringify(sortKeys(value));
-}
-
-//#endregion
-//#region src/attestation.ts
-function sha256Hex(input) {
-	return createHash("sha256").update(input).digest("hex");
-}
-/**
-* Content-addressed migration identity over (manifest envelope sans
-* contracts/hints, ops). See ADR 199 "Storage-only migration identity"
-* for the rationale: contracts are anchored separately by the
-* storage-hash bookends inside the envelope; planner hints are advisory
-* and must not affect identity.
-*
-* The `migrationId` field on the manifest is stripped before hashing so
-* the function can be used both at write time (when no id exists yet)
-* and at verify time (rehashing an already-attested manifest).
-*/
-function computeMigrationId(manifest, ops) {
-	const { migrationId: _migrationId, signature: _signature, fromContract: _fromContract, toContract: _toContract, hints: _hints, ...strippedMeta } = manifest;
-	return `sha256:${sha256Hex(canonicalizeJson([canonicalizeJson(strippedMeta), canonicalizeJson(ops)].map(sha256Hex)))}`;
-}
-/**
-* Re-hash an on-disk migration bundle and compare against the stored
-* `migrationId`. Returns `{ ok: true }` when the package is internally
-* consistent (manifest + ops still produce the recorded id), or
-* `{ ok: false, reason: 'mismatch', stored, computed }` when they do
-* not — typically a sign of FS corruption, partial writes, or a
-* post-emit hand edit.
-*/
-function verifyMigrationBundle(bundle) {
-	const computed = computeMigrationId(bundle.manifest, bundle.ops);
-	if (bundle.manifest.migrationId === computed) return {
-		ok: true,
-		storedMigrationId: bundle.manifest.migrationId,
-		computedMigrationId: computed
-	};
-	return {
-		ok: false,
-		reason: "mismatch",
-		storedMigrationId: bundle.manifest.migrationId,
-		computedMigrationId: computed
-	};
-}
-/** Convenience wrapper: read the package from disk then verify it. */
-async function verifyMigration(dir) {
-	return verifyMigrationBundle(await readMigrationPackage(dir));
-}
-
-//#endregion
-export { verifyMigration as n, verifyMigrationBundle as r, computeMigrationId as t };
-//# sourceMappingURL=attestation-DtF8tEOM.mjs.map