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

package/src/migration-base.ts

@@ -8,20 +8,27 @@ 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 { errorInvalidOperationEntry, errorStaleContractBookends } from './errors';
+import { computeMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
+import type { MigrationHints, MigrationMetadata } from './metadata';
+import { MigrationOpSchema } from './op-schema';
+import type { MigrationOps } from './package';
 
 export interface MigrationMeta {
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
-  readonly kind?: 'regular' | 'baseline';
   readonly labels?: readonly string[];
 }
 
+// `from` rejects empty strings to mirror `MigrationMetadataSchema` in
+// `./io.ts`. Without this match, an authored migration could `describe()` with
+// `from: ''` and pass `buildMigrationArtifacts`'s validation, only to have
+// `readMigrationPackage` reject the resulting `migration.json` later — the
+// two validators must agree on the legal value space.
 const MigrationMetaSchema = type({
-  from: 'string',
+  from: 'string > 0 | null',
   to: 'string',
-  'kind?': "'regular' | 'baseline'",
   'labels?': type('string').array(),
 });
 
@@ -30,7 +37,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.
  */
@@ -74,11 +81,7 @@ export abstract class Migration<
 
   get origin(): { readonly storageHash: string } | null {
     const from = this.describe().from;
-    // An empty `from` represents a migration with no prior origin (e.g.
-    // initial baseline, or an in-process plan that was never persisted).
-    // Surface that as a null origin so runners treat the plan as
-    // origin-less rather than matching against an empty storage hash.
-    return from === '' ? null : { storageHash: from };
+    return from === null ? null : { storageHash: from };
   }
 
   get destination(): { readonly storageHash: string } {
@@ -104,83 +107,114 @@ export function isDirectEntrypoint(importMetaUrl: string): boolean {
   }
 }
 
-export function printMigrationHelp(): void {
-  printHelp();
-}
-
-function printHelp(): void {
-  process.stdout.write(
-    [
-      'Usage: node <migration-file> [options]',
-      '',
-      'Options:',
-      '  --dry-run  Print operations to stdout without writing files',
-      '  --help     Show this help message',
-      '',
-    ].join('\n'),
-  );
-}
-
 /**
  * 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
+ * `describe()`-derived fields (`from`, `to`) and the operations
+ * change as the author iterates. When no metadata exists yet (a bare
  * `migration.ts` run from scratch), synthesize a minimal but
- * schema-conformant manifest so the resulting package can still be read,
+ * schema-conformant record so the resulting package can still be read,
  * verified, and applied.
  *
- * The `migrationId` is recomputed against the current manifest + ops so
+ * The `migrationHash` is recomputed against the current metadata + ops so
  * the on-disk artifacts are always fully attested.
  */
-function buildAttestedManifest(
+function buildAttestedMetadata(
   meta: MigrationMeta,
   ops: MigrationOps,
-  existing: Partial<MigrationManifest> | null,
-): MigrationManifest {
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  existing: Partial<MigrationMetadata> | null,
+): MigrationMetadata {
+  assertBookendsMatchMeta(meta, existing);
+
+  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 };
+}
+
+/**
+ * Verify each preserved contract bookend in `existing` agrees with the
+ * corresponding side of `describe()`'s output. A mismatch indicates the
+ * migration's `describe()` was edited after `migration plan` scaffolded
+ * the package, leaving a self-inconsistent manifest. Failing fast at
+ * write-time turns a silent foot-gun into an actionable diagnostic.
+ *
+ * Skipped when a side's `existing.<side>Contract` is null/absent (the
+ * synthesis path stays open for origin-less initial migrations and for
+ * bare `migration.ts` runs from scratch). When a bookend is *present*
+ * but its `storage.storageHash` is missing, that's treated as a
+ * mismatch — a malformed bookend is not equivalent to "no bookend".
+ *
+ * This check is paired with TML-2274, which removes `fromContract` /
+ * `toContract` from the manifest entirely; once that lands, this
+ * function and its error code are deleted.
+ */
+function assertBookendsMatchMeta(
+  meta: MigrationMeta,
+  existing: Partial<MigrationMetadata> | null,
+): void {
+  if (existing?.fromContract != null) {
+    const contractHash = existing.fromContract.storage?.storageHash ?? '';
+    if (contractHash !== meta.from) {
+      throw errorStaleContractBookends({
+        side: 'from',
+        metaHash: meta.from,
+        contractHash,
+      });
+    }
+  }
+  if (existing?.toContract != null) {
+    const contractHash = existing.toContract.storage?.storageHash ?? '';
+    if (contractHash !== meta.to) {
+      throw errorStaleContractBookends({
+        side: 'to',
+        metaHash: meta.to,
+        contractHash,
+      });
+    }
+  }
 }
 
 /**
  * Project `existing.hints` down to the known `MigrationHints` shape, dropping
- * any legacy keys that may linger in manifests scaffolded by older CLI
+ * any legacy keys that may linger in metadata scaffolded by older CLI
  * versions (e.g. `planningStrategy`). Picking fields explicitly instead of
  * spreading keeps refreshed `migration.json` files schema-clean regardless
  * of what was on disk before.
@@ -195,33 +229,40 @@ 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)) {
     throw new Error('operations must be an array');
   }
 
+  for (let index = 0; index < ops.length; index++) {
+    const result = MigrationOpSchema(ops[index]);
+    if (result instanceof type.errors) {
+      throw errorInvalidOperationEntry(index, result.summary);
+    }
+  }
+
   const rawMeta: unknown = instance.describe();
   const parsed = MigrationMetaSchema(rawMeta);
   if (parsed instanceof type.errors) {
     throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
   }
 
-  const manifest = buildAttestedManifest(parsed, ops, existing);
+  const metadata = buildAttestedMetadata(parsed, ops, existing);
 
   return {
     opsJson: JSON.stringify(ops, null, 2),
-    manifest,
-    manifestJson: JSON.stringify(manifest, null, 2),
+    metadata,
+    metadataJson: JSON.stringify(metadata, null, 2),
   };
 }

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

@@ -2,75 +2,87 @@ 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. */
+/** Forward-edge neighbours: edge `e` from `n` visits `e.to` next. */
 function forwardNeighbours(graph: MigrationGraph, node: string) {
   return (graph.forwardChain.get(node) ?? []).map((edge) => ({ next: edge.to, edge }));
 }
 
-/** Reverse-edge neighbours for BFS: edge `e` from `n` visits `e.from` next. */
+/**
+ * Forward-edge neighbours, sorted by the deterministic tie-break.
+ * Used by path-finding so the resulting shortest path is stable across runs.
+ */
+function sortedForwardNeighbours(graph: MigrationGraph, node: string) {
+  const edges = graph.forwardChain.get(node) ?? [];
+  return [...edges].sort(compareTieBreak).map((edge) => ({ next: edge.to, edge }));
+}
+
+/** Reverse-edge neighbours: edge `e` from `n` visits `e.from` next. */
 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;
+    // Manifest `from` is `string | null` (null = baseline). The graph layer
+    // is the marker/path layer where "no prior state" is encoded as the
+    // EMPTY_CONTRACT_HASH sentinel; bridge here so pathfinding stays string-
+    // keyed.
+    const from = pkg.metadata.from ?? EMPTY_CONTRACT_HASH;
+    const { 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.
+// Used by path-finders only; not a general-purpose utility.
+// Ordering: label priority → createdAt → to → migrationHash.
 // ---------------------------------------------------------------------------
 
 const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
@@ -84,49 +96,42 @@ 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 }[] {
-  return items.slice().sort((a, b) => compareTieBreak(a.edge, b.edge));
-}
-
 /**
  * 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.
+ * 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 }>();
-  for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n), bfsOrdering)) {
+  const parents = new Map<string, { parent: string; edge: MigrationEdge }>();
+  for (const step of bfs([fromHash], (n) => sortedForwardNeighbours(graph, n))) {
     if (step.parent !== null && step.incomingEdge !== null) {
-      parents.set(step.node, { parent: step.parent, edge: step.incomingEdge });
+      parents.set(step.state, { parent: step.parent, edge: step.incomingEdge });
     }
-    if (step.node === toHash) {
-      const path: MigrationChainEntry[] = [];
+    if (step.state === toHash) {
+      const path: MigrationEdge[] = [];
       let cur = toHash;
       let p = parents.get(cur);
       while (p) {
@@ -142,6 +147,103 @@ export function findPath(
   return null;
 }
 
+/**
+ * Find the shortest path from `fromHash` to `toHash` whose edges collectively
+ * cover every invariant in `required`. Returns `null` when no such path exists
+ * (either `fromHash`→`toHash` is structurally unreachable, or every reachable
+ * path leaves at least one required invariant uncovered). When `required` is
+ * empty, delegates to `findPath` so the result is byte-identical for that case.
+ *
+ * Algorithm: BFS over `(node, coveredSubset)` states with state-level dedup.
+ * The covered subset is a `Set<string>` of invariant ids; the state's dedup
+ * key is `${node}\0${[...covered].sort().join('\0')}`. State keys distinguish
+ * distinct `(node, covered)` tuples regardless of node-name length because
+ * `\0` cannot appear in any invariant id (validation rejects whitespace and
+ * 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;
+ * correctness (shortest, deterministic) does not depend on it.
+ */
+export function findPathWithInvariants(
+  graph: MigrationGraph,
+  fromHash: string,
+  toHash: string,
+  required: ReadonlySet<string>,
+): readonly MigrationEdge[] | null {
+  if (required.size === 0) {
+    return findPath(graph, fromHash, toHash);
+  }
+  if (fromHash === toHash) {
+    // Empty path covers no invariants; required is non-empty ⇒ unsatisfiable.
+    return null;
+  }
+
+  interface InvState {
+    readonly node: string;
+    readonly covered: ReadonlySet<string>;
+  }
+  const stateKey = (s: InvState): string => {
+    if (s.covered.size === 0) return `${s.node}\0`;
+    return `${s.node}\0${[...s.covered].sort().join('\0')}`;
+  };
+
+  const neighbours = (s: InvState): Iterable<{ next: InvState; edge: MigrationEdge }> => {
+    const outgoing = graph.forwardChain.get(s.node) ?? [];
+    if (outgoing.length === 0) return [];
+    return [...outgoing]
+      .map((edge) => {
+        let useful = false;
+        let next: Set<string> | null = null;
+        for (const inv of edge.invariants) {
+          if (required.has(inv) && !s.covered.has(inv)) {
+            if (next === null) next = new Set(s.covered);
+            next.add(inv);
+            useful = true;
+          }
+        }
+        return { edge, useful, nextCovered: next ?? s.covered };
+      })
+      .sort((a, b) => {
+        if (a.useful !== b.useful) return a.useful ? -1 : 1;
+        return compareTieBreak(a.edge, b.edge);
+      })
+      .map(({ edge, nextCovered }) => ({
+        next: { node: edge.to, covered: nextCovered },
+        edge,
+      }));
+  };
+
+  // Path reconstruction is consumer-side, keyed on stateKey, same shape as
+  // findPath's parents map.
+  const parents = new Map<string, { parentKey: string; edge: MigrationEdge }>();
+  for (const step of bfs<InvState, MigrationEdge>(
+    [{ node: fromHash, covered: new Set() }],
+    neighbours,
+    stateKey,
+  )) {
+    const curKey = stateKey(step.state);
+    if (step.parent !== null && step.incomingEdge !== null) {
+      parents.set(curKey, { parentKey: stateKey(step.parent), edge: step.incomingEdge });
+    }
+    if (step.state.node === toHash && step.state.covered.size === required.size) {
+      const path: MigrationEdge[] = [];
+      let cur: string | undefined = curKey;
+      while (cur !== undefined) {
+        const p = parents.get(cur);
+        if (!p) break;
+        path.push(p.edge);
+        cur = p.parentKey;
+      }
+      path.reverse();
+      return path;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Reverse-BFS from `toHash` over `reverseChain` to collect every node from
  * which `toHash` is reachable (inclusive of `toHash` itself).
@@ -149,13 +251,13 @@ export function findPath(
 function collectNodesReachingTarget(graph: MigrationGraph, toHash: string): Set<string> {
   const reached = new Set<string>();
   for (const step of bfs([toHash], (n) => reverseNeighbours(graph, n))) {
-    reached.add(step.node);
+    reached.add(step.state);
   }
   return reached;
 }
 
 export interface PathDecision {
-  readonly selectedPath: readonly MigrationChainEntry[];
+  readonly selectedPath: readonly MigrationEdge[];
   readonly fromHash: string;
   readonly toHash: string;
   readonly alternativeCount: number;
@@ -202,8 +304,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`,
             );
@@ -235,7 +337,7 @@ function findDivergencePoint(
   const ancestorSets = leaves.map((leaf) => {
     const ancestors = new Set<string>();
     for (const step of bfs([leaf], (n) => reverseNeighbours(graph, n))) {
-      ancestors.add(step.node);
+      ancestors.add(step.state);
     }
     return ancestors;
   });
@@ -264,8 +366,8 @@ function findDivergencePoint(
 export function findReachableLeaves(graph: MigrationGraph, fromHash: string): readonly string[] {
   const leaves: string[] = [];
   for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n))) {
-    if (!graph.forwardChain.get(step.node)?.length) {
-      leaves.push(step.node);
+    if (!graph.forwardChain.get(step.state)?.length) {
+      leaves.push(step.state);
     }
   }
   return leaves;
@@ -319,7 +421,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 +445,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 +491,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>();
@@ -412,10 +514,10 @@ export function detectOrphans(graph: MigrationGraph): readonly MigrationChainEnt
   }
 
   for (const step of bfs(startNodes, (n) => forwardNeighbours(graph, n))) {
-    reachable.add(step.node);
+    reachable.add(step.state);
   }
 
-  const orphans: MigrationChainEntry[] = [];
+  const orphans: MigrationEdge[] = [];
   for (const [from, migrations] of graph.forwardChain) {
     if (!reachable.has(from)) {
       orphans.push(...migrations);

package/src/op-schema.ts

@@ -0,0 +1,11 @@
+import { type } from 'arktype';
+
+export const MigrationOpSchema = type({
+  id: 'string',
+  label: 'string',
+  operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
+  'invariantId?': 'string',
+});
+
+// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.
+export const MigrationOpsSchema = MigrationOpSchema.array();

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;
+}