@prisma-next/migration-tools 0.3.0-dev.85 → 0.3.0-dev.87

package/src/dag.ts

@@ -1,18 +1,19 @@
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/core-control-plane/constants';
+import { ifDefined } from '@prisma-next/utils/defined';
 import {
   errorAmbiguousLeaf,
   errorDuplicateMigrationId,
+  errorNoResolvableLeaf,
   errorNoRoot,
   errorSelfLoop,
 } from './errors';
-import type { MigrationChainEntry, MigrationGraph, MigrationPackage } from './types';
+import type { AttestedMigrationBundle, MigrationChainEntry, MigrationGraph } from './types';
 
-export function reconstructGraph(packages: readonly MigrationPackage[]): MigrationGraph {
+export function reconstructGraph(packages: readonly AttestedMigrationBundle[]): 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 childrenByParentId = new Map<string | null, MigrationChainEntry[]>();
 
   for (const pkg of packages) {
     const { from, to } = pkg.manifest;
@@ -28,7 +29,6 @@ export function reconstructGraph(packages: readonly MigrationPackage[]): Migrati
       from,
       to,
       migrationId: pkg.manifest.migrationId,
-      parentMigrationId: pkg.manifest.parentMigrationId,
       dirName: pkg.dirName,
       createdAt: pkg.manifest.createdAt,
       labels: pkg.manifest.labels,
@@ -41,14 +41,6 @@ export function reconstructGraph(packages: readonly MigrationPackage[]): Migrati
       migrationById.set(migration.migrationId, migration);
     }
 
-    const parentId = migration.parentMigrationId;
-    const siblings = childrenByParentId.get(parentId);
-    if (siblings) {
-      siblings.push(migration);
-    } else {
-      childrenByParentId.set(parentId, [migration]);
-    }
-
     const fwd = forwardChain.get(from);
     if (fwd) {
       fwd.push(migration);
@@ -64,128 +56,287 @@ export function reconstructGraph(packages: readonly MigrationPackage[]): Migrati
     }
   }
 
-  return { nodes, forwardChain, reverseChain, migrationById, childrenByParentId };
+  return { nodes, forwardChain, reverseChain, migrationById };
 }
 
-/**
- * Walk the parent-migration chain to find the latest migration.
- * Returns the migration with no children, or null for an empty graph.
- * Throws AMBIGUOUS_LEAF if the chain branches.
- */
-export function findLatestMigration(graph: MigrationGraph): MigrationChainEntry | null {
-  if (graph.nodes.size === 0) {
-    return null;
-  }
+const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
 
-  const roots = graph.childrenByParentId.get(null);
-  if (!roots || roots.length === 0) {
-    throw errorNoRoot([...graph.nodes].sort());
+function labelPriority(labels: readonly string[]): number {
+  let best = 3;
+  for (const l of labels) {
+    const p = LABEL_PRIORITY[l];
+    if (p !== undefined && p < best) best = p;
   }
+  return best;
+}
 
-  if (roots.length > 1) {
-    throw errorAmbiguousLeaf(roots.map((e) => e.to));
-  }
+function sortedNeighbors(edges: readonly MigrationChainEntry[]): readonly MigrationChainEntry[] {
+  return [...edges].sort((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);
+    if (tc !== 0) return tc;
+    return (a.migrationId ?? '').localeCompare(b.migrationId ?? '');
+  });
+}
 
-  let current = roots[0];
-  if (!current) {
-    throw errorNoRoot([...graph.nodes].sort());
-  }
+/**
+ * Find the shortest path from `fromHash` to `toHash` using BFS over the
+ * contract-hash graph. Returns the ordered list of edges, or null if no path
+ * 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.
+ */
+export function findPath(
+  graph: MigrationGraph,
+  fromHash: string,
+  toHash: string,
+): readonly MigrationChainEntry[] | null {
+  if (fromHash === toHash) return [];
 
-  for (let depth = 0; depth < graph.migrationById.size + 1 && current; depth++) {
-    const children: readonly MigrationChainEntry[] | undefined =
-      current.migrationId !== null ? graph.childrenByParentId.get(current.migrationId) : undefined;
+  const visited = new Set<string>();
+  const parent = new Map<string, { node: string; edge: MigrationChainEntry }>();
+  const queue: string[] = [fromHash];
+  visited.add(fromHash);
 
-    if (!children || children.length === 0) {
-      return current;
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) break;
+
+    if (current === toHash) {
+      const path: MigrationChainEntry[] = [];
+      let node = toHash;
+      let entry = parent.get(node);
+      while (entry) {
+        const { node: prev, edge } = entry;
+        path.push(edge);
+        node = prev;
+        entry = parent.get(node);
+      }
+      path.reverse();
+      return path;
     }
 
-    if (children.length > 1) {
-      throw errorAmbiguousLeaf(children.map((e) => e.to));
-    }
+    const outgoing = graph.forwardChain.get(current);
+    if (!outgoing) continue;
 
-    current = children[0];
+    for (const edge of sortedNeighbors(outgoing)) {
+      if (!visited.has(edge.to)) {
+        visited.add(edge.to);
+        parent.set(edge.to, { node: current, edge });
+        queue.push(edge.to);
+      }
+    }
   }
 
-  throw errorNoRoot([...graph.nodes].sort());
+  return null;
+}
+
+export interface PathDecision {
+  readonly selectedPath: readonly MigrationChainEntry[];
+  readonly fromHash: string;
+  readonly toHash: string;
+  readonly alternativeCount: number;
+  readonly tieBreakReasons: readonly string[];
+  readonly refName?: string;
 }
 
 /**
- * Find the leaf contract hash of the migration chain.
- * Convenience wrapper around findLatestMigration.
+ * Find the shortest path from `fromHash` to `toHash` and return structured
+ * path-decision metadata for machine-readable output.
  */
-export function findLeaf(graph: MigrationGraph): string {
-  const migration = findLatestMigration(graph);
-  return migration ? migration.to : EMPTY_CONTRACT_HASH;
+export function findPathWithDecision(
+  graph: MigrationGraph,
+  fromHash: string,
+  toHash: string,
+  refName?: string,
+): PathDecision | null {
+  if (fromHash === toHash) {
+    return {
+      selectedPath: [],
+      fromHash,
+      toHash,
+      alternativeCount: 0,
+      tieBreakReasons: [],
+      ...ifDefined('refName', refName),
+    };
+  }
+
+  const path = findPath(graph, fromHash, toHash);
+  if (!path) return null;
+
+  const tieBreakReasons: string[] = [];
+  let alternativeCount = 0;
+
+  for (const edge of path) {
+    const outgoing = graph.forwardChain.get(edge.from);
+    if (outgoing && outgoing.length > 1) {
+      const reachable = outgoing.filter((e) => {
+        const pathFromE = findPath(graph, e.to, toHash);
+        return pathFromE !== null || e.to === toHash;
+      });
+      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)) {
+            tieBreakReasons.push(
+              `at ${edge.from}: ${reachable.length} candidates, selected by tie-break`,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    selectedPath: path,
+    fromHash,
+    toHash,
+    alternativeCount,
+    tieBreakReasons,
+    ...ifDefined('refName', refName),
+  };
 }
 
 /**
- * Find the ordered chain of migrations from `fromHash` to `toHash` by walking the
- * parent-migration chain. Returns the sub-sequence of migrations whose cumulative path
- * goes from `fromHash` to `toHash`.
- *
- * This reconstructs the full chain from root to leaf via parent pointers, then
- * extracts the segment between the two hashes. This correctly handles revisited
- * contract hashes (e.g. A→B→A) because it operates on migrations, not nodes.
+ * Walk ancestors of each leaf back from the leaves to find the last node
+ * that appears on all paths. Returns `fromHash` if no shared ancestor is found.
  */
-export function findPath(
+function findDivergencePoint(
   graph: MigrationGraph,
   fromHash: string,
-  toHash: string,
-): readonly MigrationChainEntry[] | null {
-  if (fromHash === toHash) return [];
+  leaves: readonly string[],
+): string {
+  const ancestorSets = leaves.map((leaf) => {
+    const ancestors = new Set<string>();
+    const queue = [leaf];
+    while (queue.length > 0) {
+      const current = queue.shift() as string;
+      if (ancestors.has(current)) continue;
+      ancestors.add(current);
+      const incoming = graph.reverseChain.get(current);
+      if (incoming) {
+        for (const edge of incoming) {
+          queue.push(edge.from);
+        }
+      }
+    }
+    return ancestors;
+  });
 
-  const chain = buildChain(graph);
-  if (!chain) return null;
+  const commonAncestors = [...(ancestorSets[0] ?? [])].filter((node) =>
+    ancestorSets.every((s) => s.has(node)),
+  );
 
-  let startIdx = -1;
-  if (chain.length > 0 && chain[0]?.from === fromHash) {
-    startIdx = 0;
-  } else {
-    for (let i = chain.length - 1; i >= 0; i--) {
-      if (chain[i]?.to === fromHash) {
-        startIdx = i + 1;
-        break;
+  let deepest = fromHash;
+  let deepestDepth = -1;
+  for (const ancestor of commonAncestors) {
+    const path = findPath(graph, fromHash, ancestor);
+    const depth = path ? path.length : 0;
+    if (depth > deepestDepth) {
+      deepestDepth = depth;
+      deepest = ancestor;
+    }
+  }
+  return deepest;
+}
+
+/**
+ * Find all leaf nodes reachable from `fromHash` via forward edges.
+ * A leaf is a node with no outgoing edges in the graph.
+ */
+export function findReachableLeaves(graph: MigrationGraph, fromHash: string): readonly string[] {
+  const visited = new Set<string>();
+  const queue: string[] = [fromHash];
+  visited.add(fromHash);
+  const leaves: string[] = [];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) break;
+    const outgoing = graph.forwardChain.get(current);
+
+    if (!outgoing || outgoing.length === 0) {
+      leaves.push(current);
+    } else {
+      for (const edge of outgoing) {
+        if (!visited.has(edge.to)) {
+          visited.add(edge.to);
+          queue.push(edge.to);
+        }
       }
     }
   }
 
-  if (startIdx === -1) return null;
+  return leaves;
+}
+
+/**
+ * Find the leaf contract hash of the migration graph reachable from
+ * EMPTY_CONTRACT_HASH. Throws NO_ROOT if the graph has nodes but none
+ * originate from the empty hash (e.g. root migration was deleted).
+ * Throws AMBIGUOUS_LEAF if multiple leaves exist.
+ */
+export function findLeaf(graph: MigrationGraph): string {
+  if (graph.nodes.size === 0) {
+    return EMPTY_CONTRACT_HASH;
+  }
+
+  if (!graph.nodes.has(EMPTY_CONTRACT_HASH)) {
+    throw errorNoRoot([...graph.nodes]);
+  }
+
+  const leaves = findReachableLeaves(graph, EMPTY_CONTRACT_HASH);
 
-  let endIdx = -1;
-  for (let i = chain.length - 1; i >= startIdx; i--) {
-    if (chain[i]?.to === toHash) {
-      endIdx = i + 1;
-      break;
+  if (leaves.length === 0) {
+    const reachable = [...graph.nodes].filter((n) => n !== EMPTY_CONTRACT_HASH);
+    if (reachable.length > 0) {
+      throw errorNoResolvableLeaf(reachable);
     }
+    return EMPTY_CONTRACT_HASH;
   }
 
-  if (endIdx === -1) return null;
+  if (leaves.length > 1) {
+    const divergencePoint = findDivergencePoint(graph, EMPTY_CONTRACT_HASH, leaves);
+    const branches = leaves.map((leaf) => {
+      const path = findPath(graph, divergencePoint, leaf);
+      return {
+        leaf,
+        edges: (path ?? []).map((e) => ({ dirName: e.dirName, from: e.from, to: e.to })),
+      };
+    });
+    throw errorAmbiguousLeaf(leaves, { divergencePoint, branches });
+  }
 
-  return chain.slice(startIdx, endIdx);
+  const leaf = leaves[0];
+  return leaf !== undefined ? leaf : EMPTY_CONTRACT_HASH;
 }
 
 /**
- * Build the full ordered chain of migrations from root to leaf by following
- * parent pointers. Returns null if the chain cannot be reconstructed
- * (e.g. missing root, branches).
+ * Find the latest migration entry by traversing from EMPTY_CONTRACT_HASH
+ * to the single leaf. Returns null for an empty graph.
+ * Throws AMBIGUOUS_LEAF if the graph has multiple leaves.
  */
-function buildChain(graph: MigrationGraph): readonly MigrationChainEntry[] | null {
-  const roots = graph.childrenByParentId.get(null);
-  if (!roots || roots.length !== 1) return null;
-
-  const chain: MigrationChainEntry[] = [];
-  let current: MigrationChainEntry | undefined = roots[0];
-
-  for (let depth = 0; depth < graph.migrationById.size + 1 && current; depth++) {
-    chain.push(current);
-    const children =
-      current.migrationId !== null ? graph.childrenByParentId.get(current.migrationId) : undefined;
-    if (!children || children.length === 0) break;
-    if (children.length > 1) return null;
-    current = children[0];
+export function findLatestMigration(graph: MigrationGraph): MigrationChainEntry | null {
+  if (graph.nodes.size === 0) {
+    return null;
+  }
+
+  const leafHash = findLeaf(graph);
+  if (leafHash === EMPTY_CONTRACT_HASH) {
+    return null;
   }
 
-  return chain;
+  const path = findPath(graph, EMPTY_CONTRACT_HASH, leafHash);
+  if (!path || path.length === 0) {
+    return null;
+  }
+
+  return path[path.length - 1] ?? null;
 }
 
 export function detectCycles(graph: MigrationGraph): readonly string[][] {
@@ -194,7 +345,7 @@ export function detectCycles(graph: MigrationGraph): readonly string[][] {
   const BLACK = 2;
 
   const color = new Map<string, number>();
-  const parent = new Map<string, string | null>();
+  const parentMap = new Map<string, string | null>();
   const cycles: string[][] = [];
 
   for (const node of graph.nodes) {
@@ -209,17 +360,16 @@ export function detectCycles(graph: MigrationGraph): readonly string[][] {
       for (const edge of outgoing) {
         const v = edge.to;
         if (color.get(v) === GRAY) {
-          // Back edge found — reconstruct cycle
           const cycle: string[] = [v];
           let cur = u;
           while (cur !== v) {
             cycle.push(cur);
-            cur = parent.get(cur) ?? v;
+            cur = parentMap.get(cur) ?? v;
           }
           cycle.reverse();
           cycles.push(cycle);
         } else if (color.get(v) === WHITE) {
-          parent.set(v, u);
+          parentMap.set(v, u);
           dfs(v);
         }
       }
@@ -230,7 +380,7 @@ export function detectCycles(graph: MigrationGraph): readonly string[][] {
 
   for (const node of graph.nodes) {
     if (color.get(node) === WHITE) {
-      parent.set(node, null);
+      parentMap.set(node, null);
       dfs(node);
     }
   }
@@ -242,15 +392,25 @@ export function detectOrphans(graph: MigrationGraph): readonly MigrationChainEnt
   if (graph.nodes.size === 0) return [];
 
   const reachable = new Set<string>();
-  const rootMigrations = graph.childrenByParentId.get(null) ?? [];
-  const emptyRootExists = rootMigrations.some(
-    (migration) => migration.from === EMPTY_CONTRACT_HASH,
-  );
-  const rootHashes = emptyRootExists
-    ? [EMPTY_CONTRACT_HASH]
-    : [...new Set(rootMigrations.map((migration) => migration.from))];
-  const queue: string[] = rootHashes.length > 0 ? rootHashes : [EMPTY_CONTRACT_HASH];
+  const startNodes: string[] = [];
+
+  if (graph.forwardChain.has(EMPTY_CONTRACT_HASH)) {
+    startNodes.push(EMPTY_CONTRACT_HASH);
+  } else {
+    const allTargets = new Set<string>();
+    for (const edges of graph.forwardChain.values()) {
+      for (const edge of edges) {
+        allTargets.add(edge.to);
+      }
+    }
+    for (const node of graph.nodes) {
+      if (!allTargets.has(node)) {
+        startNodes.push(node);
+      }
+    }
+  }
 
+  const queue = [...startNodes];
   for (const hash of queue) {
     reachable.add(hash);
   }

package/src/errors.ts

@@ -92,28 +92,79 @@ export function errorSelfLoop(dirName: string, hash: string): MigrationToolsErro
   });
 }
 
-export function errorAmbiguousLeaf(leaves: readonly string[]): MigrationToolsError {
+export function errorAmbiguousLeaf(
+  leaves: readonly string[],
+  context?: {
+    divergencePoint: string;
+    branches: readonly {
+      leaf: string;
+      edges: readonly { dirName: string; from: string; to: string }[];
+    }[];
+  },
+): MigrationToolsError {
+  const divergenceInfo = context
+    ? `\nDivergence point: ${context.divergencePoint}\nBranches:\n${context.branches.map((b) => `  → ${b.leaf} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\n')}`
+    : '';
   return new MigrationToolsError('MIGRATION.AMBIGUOUS_LEAF', 'Ambiguous migration graph', {
-    why: `Multiple leaf nodes found: ${leaves.join(', ')}. The migration graph has diverged — this typically happens when two developers plan migrations from the same starting point.`,
-    fix: 'Delete one of the conflicting migration directories, then re-run `migration plan` to re-plan it from the remaining branch. Or use --from <hash> to explicitly select a starting point.',
-    details: { leaves },
+    why: `Multiple leaf nodes found: ${leaves.join(', ')}. The migration graph has diverged — this typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,
+    fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',
+    details: {
+      leaves,
+      ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),
+    },
   });
 }
 
 export function errorNoRoot(nodes: readonly string[]): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.NO_ROOT', 'Migration graph has no root', {
-    why: `No root migration found in the migration graph (nodes: ${nodes.join(', ')}). Every migration references a parentMigrationId that does not exist, or the graph contains a cycle in parent pointers.`,
-    fix: 'Inspect the migrations directory for corrupted migration.json files. Exactly one migration must have parentMigrationId set to null (the first migration).',
+    why: `No root migration found in the migration graph (nodes: ${nodes.join(', ')}). No migration starts from the empty contract hash, or all edges form a disconnected subgraph.`,
+    fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',
     details: { nodes },
   });
 }
 
+export function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {
+    why: `refs.json at "${refsPath}" is invalid: ${reason}`,
+    fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',
+    details: { path: refsPath, reason },
+  });
+}
+
+export function errorInvalidRefName(refName: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {
+    why: `Ref name "${refName}" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no "." or ".." segments).`,
+    fix: `Use a valid ref name (e.g., "staging", "envs/production").`,
+    details: { refName },
+  });
+}
+
+export function errorNoResolvableLeaf(reachableNodes: readonly string[]): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.NO_RESOLVABLE_LEAF',
+    'Migration graph has no resolvable leaf',
+    {
+      why: `The migration graph contains cycles and no node has zero outgoing edges (reachable nodes: ${reachableNodes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,
+      fix: 'Use --from <hash> to specify the planning origin explicitly.',
+      details: { reachableNodes },
+    },
+  );
+}
+
+export function errorInvalidRefValue(value: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {
+    why: `Ref value "${value}" is not a valid contract hash. Values must be in the format "sha256:<64 hex chars>" or "sha256:empty".`,
+    fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',
+    details: { value },
+  });
+}
+
 export function errorDuplicateMigrationId(migrationId: string): MigrationToolsError {
   return new MigrationToolsError(
     'MIGRATION.DUPLICATE_MIGRATION_ID',
     'Duplicate migrationId in migration graph',
     {
-      why: `Multiple migrations share migrationId "${migrationId}". This makes parent-chain reconstruction ambiguous and unsafe.`,
+      why: `Multiple migrations share migrationId "${migrationId}". Each migration must have a unique content-addressed identity.`,
       fix: 'Regenerate one of the conflicting migrations so each migrationId is unique, then re-run migration commands.',
       details: { migrationId },
     },

package/src/exports/dag.ts

@@ -1,8 +1,11 @@
+export type { PathDecision } from '../dag';
 export {
   detectCycles,
   detectOrphans,
   findLatestMigration,
   findLeaf,
   findPath,
+  findPathWithDecision,
+  findReachableLeaves,
   reconstructGraph,
 } from '../dag';

package/src/exports/refs.ts

@@ -0,0 +1,2 @@
+export type { Refs } from '../refs';
+export { readRefs, resolveRef, validateRefName, validateRefValue, writeRefs } from '../refs';

package/src/exports/types.ts

@@ -1,9 +1,14 @@
 export { MigrationToolsError } from '../errors';
 export type {
+  AttestedMigrationBundle,
+  AttestedMigrationManifest,
+  DraftMigrationManifest,
+  MigrationBundle,
+  MigrationBundle as MigrationPackage,
   MigrationChainEntry,
   MigrationGraph,
   MigrationHints,
   MigrationManifest,
   MigrationOps,
-  MigrationPackage,
 } from '../types';
+export { isAttested } from '../types';

package/src/io.ts

@@ -8,7 +8,7 @@ import {
   errorInvalidSlug,
   errorMissingFile,
 } from './errors';
-import type { MigrationManifest, MigrationOps, MigrationPackage } from './types';
+import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -29,7 +29,6 @@ const MigrationManifestSchema = type({
   from: 'string',
   to: 'string',
   migrationId: 'string | null',
-  parentMigrationId: 'string | null',
   kind: "'regular' | 'baseline'",
   fromContract: 'object | null',
   toContract: 'object',
@@ -75,7 +74,7 @@ export async function writeMigrationPackage(
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
-export async function readMigrationPackage(dir: string): Promise<MigrationPackage> {
+export async function readMigrationPackage(dir: string): Promise<MigrationBundle> {
   const manifestPath = join(dir, MANIFEST_FILE);
   const opsPath = join(dir, OPS_FILE);
 
@@ -143,7 +142,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationPackage[]> {
+): Promise<readonly MigrationBundle[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -154,7 +153,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationPackage[] = [];
+  const packages: MigrationBundle[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);