@prisma-next/migration-tools 0.5.0-dev.1 → 0.5.0-dev.10

package/src/errors.ts

@@ -1,10 +1,29 @@
+import { basename, dirname, relative } from 'pathe';
+
+/**
+ * Build the canonical "re-emit this package" remediation hint.
+ *
+ * Every on-disk migration package ships its own `migration.ts` author-time
+ * file. Running it regenerates `migration.json` and `ops.json` with the
+ * correct hash + metadata, so it is the right primitive whenever a single
+ * package's on-disk artifacts are missing, malformed, or otherwise corrupt.
+ * Pointing users at `migration plan` would emit a *new* package rather than
+ * heal the broken one.
+ */
+function reemitHint(dir: string, fallback?: string): string {
+  const relativeDir = relative(process.cwd(), dir);
+  const reemit = `Re-emit the package by running \`node "${relativeDir}/migration.ts"\``;
+  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;
+}
+
 /**
  * Structured error for migration tooling operations.
  *
  * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
- * the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
- * migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
- * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+ * the MIGRATION namespace. These are tooling-time errors (file I/O, hash
+ * verification, migration history reconstruction), distinct from the runtime
+ * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
+ * etc.).
  *
  * Fields:
  * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
@@ -55,7 +74,10 @@ export function errorDirectoryExists(dir: string): MigrationToolsError {
 export function errorMissingFile(file: string, dir: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {
     why: `Expected "${file}" in "${dir}" but the file does not exist.`,
-    fix: 'Ensure the migration directory contains both migration.json and ops.json. If the directory is corrupt, delete it and re-run migration plan.',
+    fix: reemitHint(
+      dir,
+      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+    ),
     details: { file, dir },
   });
 }
@@ -63,15 +85,15 @@ export function errorMissingFile(file: string, dir: string): MigrationToolsError
 export function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {
     why: `Failed to parse "${filePath}": ${parseError}`,
-    fix: 'Fix the JSON syntax error, or delete the migration directory and re-run migration plan.',
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, parseError },
   });
 }
 
 export function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {
-    why: `Manifest at "${filePath}" is invalid: ${reason}`,
-    fix: 'Ensure the manifest has all required fields (from, to, kind, toContract). If corrupt, delete and re-plan.',
+    why: `Migration manifest at "${filePath}" is invalid: ${reason}`,
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, reason },
   });
 }
@@ -92,13 +114,17 @@ export function errorInvalidDestName(destName: string): MigrationToolsError {
   });
 }
 
-export function errorSameSourceAndTarget(dirName: string, hash: string): MigrationToolsError {
+export function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {
+  const dirName = basename(dir);
   return new MigrationToolsError(
     'MIGRATION.SAME_SOURCE_AND_TARGET',
     'Migration has same source and target',
     {
       why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
-      fix: 'Delete the invalid migration directory and re-run migration plan.',
+      fix: reemitHint(
+        dir,
+        'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+      ),
       details: { dirName, hash },
     },
   );
@@ -175,14 +201,30 @@ export function errorInvalidRefValue(value: string): MigrationToolsError {
   });
 }
 
-export function errorDuplicateMigrationId(migrationId: string): MigrationToolsError {
+export function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {
   return new MigrationToolsError(
-    'MIGRATION.DUPLICATE_MIGRATION_ID',
-    'Duplicate migrationId in migration graph',
+    'MIGRATION.DUPLICATE_MIGRATION_HASH',
+    'Duplicate migrationHash in migration graph',
     {
-      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 },
+      why: `Multiple migrations share migrationHash "${migrationHash}". Each migration must have a unique content-addressed identity.`,
+      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',
+      details: { migrationHash },
     },
   );
 }
+
+export function errorMigrationHashMismatch(
+  dir: string,
+  storedHash: string,
+  computedHash: string,
+): MigrationToolsError {
+  // Render a cwd-relative path in the human-readable diagnostic so users
+  // running CLI commands from the project root see a familiar short path.
+  // Keep the absolute path in `details.dir` for machine consumers.
+  const relativeDir = relative(process.cwd(), dir);
+  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {
+    why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relativeDir}". The migration.json or ops.json has been edited or partially written since emit.`,
+    fix: reemitHint(dir, 'or restore the directory from version control.'),
+    details: { dir, storedHash, computedHash },
+  });
+}

package/src/exports/errors.ts

@@ -0,0 +1 @@
+export { MigrationToolsError } from '../errors';

package/src/exports/graph.ts

@@ -0,0 +1 @@
+export type { MigrationChainEntry, MigrationGraph } from '../graph';

package/src/exports/hash.ts

@@ -0,0 +1,2 @@
+export type { VerifyResult } from '../hash';
+export { computeMigrationHash, verifyMigrationHash } from '../hash';

package/src/exports/io.ts

@@ -3,7 +3,7 @@ export {
   formatMigrationDirName,
   readMigrationPackage,
   readMigrationsDir,
-  writeMigrationManifest,
+  writeMigrationMetadata,
   writeMigrationOps,
   writeMigrationPackage,
 } from '../io';

package/src/exports/metadata.ts

@@ -0,0 +1 @@
+export type { MigrationHints, MigrationMetadata } from '../metadata';

package/src/exports/package.ts

@@ -0,0 +1 @@
+export type { MigrationOps, MigrationPackage } from '../package';

package/src/exports/refs.ts

@@ -1,2 +1,10 @@
-export type { Refs } from '../refs';
-export { readRefs, resolveRef, validateRefName, validateRefValue, writeRefs } from '../refs';
+export type { RefEntry, Refs } from '../refs';
+export {
+  deleteRef,
+  readRef,
+  readRefs,
+  resolveRef,
+  validateRefName,
+  validateRefValue,
+  writeRef,
+} from '../refs';

package/src/graph.ts

@@ -0,0 +1,19 @@
+/**
+ * An entry in the migration graph. All on-disk migrations are attested,
+ * so `migrationHash` is always a string.
+ */
+export interface MigrationChainEntry {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+}
+
+export interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly migrationByHash: ReadonlyMap<string, MigrationChainEntry>;
+}

package/src/hash.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeJson } from './canonicalize-json';
+import type { MigrationMetadata } from './metadata';
+import type { MigrationOps, MigrationPackage } from './package';
+
+export interface VerifyResult {
+  readonly ok: boolean;
+  readonly reason?: 'mismatch';
+  readonly storedHash: string;
+  readonly computedHash: string;
+}
+
+function sha256Hex(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+/**
+ * Content-addressed migration hash over (metadata envelope sans
+ * contracts/hints/signature, 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 integrity check is purely structural, not semantic. The function
+ * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
+ * and hashes the result. Target-specific operation payloads (`step.sql`,
+ * Mongo's pipeline AST, …) are hashed verbatim — no per-target
+ * normalization is required, because what's being verified is "do the
+ * on-disk bytes still produce their recorded hash", not "do two
+ * semantically-equivalent migrations hash the same". The latter is an
+ * emit-drift concern (ADR 192 step 2).
+ *
+ * The symmetry across write and read holds because `JSON.parse(
+ * JSON.stringify(x))` round-trips JSON-safe values losslessly and
+ * `sortKeys` is idempotent and deterministic — write-time and read-time
+ * canonicalization produce the same canonical bytes regardless of
+ * source-side key ordering or whitespace.
+ *
+ * The `migrationHash` field on the metadata is stripped before hashing
+ * so the function can be used both at write time (when no hash exists
+ * yet) and at verify time (rehashing an already-attested record).
+ */
+export function computeMigrationHash(
+  metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },
+  ops: MigrationOps,
+): string {
+  const {
+    migrationHash: _migrationHash,
+    signature: _signature,
+    fromContract: _fromContract,
+    toContract: _toContract,
+    hints: _hints,
+    ...strippedMeta
+  } = metadata;
+
+  const canonicalMetadata = canonicalizeJson(strippedMeta);
+  const canonicalOps = canonicalizeJson(ops);
+
+  const partHashes = [canonicalMetadata, canonicalOps].map(sha256Hex);
+  const hash = sha256Hex(canonicalizeJson(partHashes));
+
+  return `sha256:${hash}`;
+}
+
+/**
+ * Re-hash an in-memory migration package and compare against the stored
+ * `migrationHash`. See `computeMigrationHash` for the canonicalization rules.
+ *
+ * Returns `{ ok: true }` when the package is internally consistent, or
+ * `{ ok: false, reason: 'mismatch', storedHash, computedHash }` when it is
+ * not — typically a sign of FS corruption, partial writes, or a post-emit
+ * hand edit.
+ */
+export function verifyMigrationHash(pkg: MigrationPackage): VerifyResult {
+  const computed = computeMigrationHash(pkg.metadata, pkg.ops);
+
+  if (pkg.metadata.migrationHash === computed) {
+    return {
+      ok: true,
+      storedHash: pkg.metadata.migrationHash,
+      computedHash: computed,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: 'mismatch',
+    storedHash: pkg.metadata.migrationHash,
+    computedHash: computed,
+  };
+}

package/src/io.ts

@@ -7,9 +7,12 @@ import {
   errorInvalidJson,
   errorInvalidManifest,
   errorInvalidSlug,
+  errorMigrationHashMismatch,
   errorMissingFile,
 } from './errors';
-import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
+import { verifyMigrationHash } from './hash';
+import type { MigrationMetadata } from './metadata';
+import type { MigrationOps, MigrationPackage } from './package';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -25,10 +28,10 @@ const MigrationHintsSchema = type({
   plannerVersion: 'string',
 });
 
-const MigrationManifestSchema = type({
+const MigrationMetadataSchema = type({
   from: 'string',
   to: 'string',
-  migrationId: 'string',
+  migrationHash: 'string',
   kind: "'regular' | 'baseline'",
   fromContract: 'object | null',
   toContract: 'object',
@@ -56,7 +59,7 @@ const MigrationOpsSchema = MigrationOpSchema.array();
 
 export async function writeMigrationPackage(
   dir: string,
-  manifest: MigrationManifest,
+  metadata: MigrationMetadata,
   ops: MigrationOps,
 ): Promise<void> {
   await mkdir(dirname(dir), { recursive: true });
@@ -70,7 +73,9 @@ export async function writeMigrationPackage(
     throw error;
   }
 
-  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: 'wx' });
+  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), {
+    flag: 'wx',
+  });
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
@@ -98,18 +103,18 @@ export async function copyFilesWithRename(
   }
 }
 
-export async function writeMigrationManifest(
+export async function writeMigrationMetadata(
   dir: string,
-  manifest: MigrationManifest,
+  metadata: MigrationMetadata,
 ): Promise<void> {
-  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\n`);
 }
 
 export async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {
   await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
 }
 
-export async function readMigrationPackage(dir: string): Promise<MigrationBundle> {
+export async function readMigrationPackage(dir: string): Promise<MigrationPackage> {
   const manifestPath = join(dir, MANIFEST_FILE);
   const opsPath = join(dir, OPS_FILE);
 
@@ -133,9 +138,9 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     throw error;
   }
 
-  let manifest: MigrationManifest;
+  let metadata: MigrationMetadata;
   try {
-    manifest = JSON.parse(manifestRaw);
+    metadata = JSON.parse(manifestRaw);
   } catch (e) {
     throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
   }
@@ -147,22 +152,29 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
   }
 
-  validateManifest(manifest, manifestPath);
+  validateMetadata(metadata, manifestPath);
   validateOps(ops, opsPath);
 
-  return {
+  const pkg: MigrationPackage = {
     dirName: basename(dir),
     dirPath: dir,
-    manifest,
+    metadata,
     ops,
   };
+
+  const verification = verifyMigrationHash(pkg);
+  if (!verification.ok) {
+    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);
+  }
+
+  return pkg;
 }
 
-function validateManifest(
-  manifest: unknown,
+function validateMetadata(
+  metadata: unknown,
   filePath: string,
-): asserts manifest is MigrationManifest {
-  const result = MigrationManifestSchema(manifest);
+): asserts metadata is MigrationMetadata {
+  const result = MigrationMetadataSchema(metadata);
   if (result instanceof type.errors) {
     throw errorInvalidManifest(filePath, result.summary);
   }
@@ -177,7 +189,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationBundle[]> {
+): Promise<readonly MigrationPackage[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -188,7 +200,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationBundle[] = [];
+  const packages: MigrationPackage[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);

package/src/metadata.ts

@@ -0,0 +1,36 @@
+import type { Contract } from '@prisma-next/contract/types';
+
+export interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+}
+
+/**
+ * In-memory migration metadata envelope. Every migration is content-addressed:
+ * the `migrationHash` is a hash over the metadata envelope plus the operations
+ * list, computed at write time. There is no draft state — a migration
+ * directory either exists with fully attested metadata or it does not.
+ *
+ * When the planner cannot lower an operation because of an unfilled
+ * `placeholder(...)` slot, the migration is still written with `migrationHash`
+ * hashed over `ops: []`. Re-running self-emit after the user fills the
+ * placeholder produces a *different* `migrationHash` (committed to the real
+ * ops); this is intentional.
+ *
+ * The on-disk JSON shape in `migration.json` matches this type field-for-field
+ * — `JSON.stringify(metadata, null, 2)` is the canonical writer output.
+ */
+export interface MigrationMetadata {
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly kind: 'regular' | 'baseline';
+  readonly fromContract: Contract | null;
+  readonly toContract: Contract;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  readonly authorship?: { readonly author?: string; readonly email?: string };
+  readonly signature?: { readonly keyId: string; readonly value: string } | null;
+  readonly createdAt: string;
+}

package/src/migration-base.ts

@@ -8,8 +8,9 @@ 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 type { MigrationHints, MigrationMetadata } from './metadata';
+import type { MigrationOps } from './package';
 
 export interface MigrationMeta {
   readonly from: string;
@@ -30,7 +31,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 +124,67 @@ 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 ?? [],
     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 +199,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 +221,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/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;
+}