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

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/{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,53 @@ 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,
     };
 
-    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 +81,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 +108,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 +152,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 +199,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 +316,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 +340,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 +386,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 +412,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;
+}