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

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-ops.ts

@@ -3,13 +3,18 @@ import { Queue } from './queue';
 /**
  * One step of a BFS traversal.
  *
- * `parent` and `incomingEdge` are `null` for start nodes — they were not
- * reached via any edge. For every other node they record the node and edge
- * by which this node was first reached.
+ * `parent` and `incomingEdge` are `null` for start states — they were not
+ * reached via any edge. For every other state they record the predecessor
+ * state and the edge by which this state was first reached.
+ *
+ * `state` is the BFS state, most often a string (graph node identifier) but
+ * can be a composite object. The string overload keeps the common case
+ * ergonomic; the generic overload accepts a caller-supplied `key` function
+ * that produces a stable equality key for dedup.
  */
-export interface BfsStep<E> {
-  readonly node: string;
-  readonly parent: string | null;
+export interface BfsStep<S, E> {
+  readonly state: S;
+  readonly parent: S | null;
   readonly incomingEdge: E | null;
 }
 
@@ -17,48 +22,70 @@ export interface BfsStep<E> {
  * Generic breadth-first traversal.
  *
  * Direction (forward/reverse) is expressed by the caller's `neighbours`
- * closure: return `{ next, edge }` pairs where `next` is the node to visit
+ * closure: return `{ next, edge }` pairs where `next` is the state to visit
  * next and `edge` is the edge that connects them. Callers that don't need
  * path reconstruction can ignore the `parent`/`incomingEdge` fields of each
  * yielded step.
  *
+ * Ordering — when the result needs to be deterministic (path-finding) the
+ * caller is responsible for sorting inside `neighbours`; this generator
+ * does not impose an ordering hook of its own. State-dependent orderings
+ * have full access to the source state inside the closure.
+ *
  * Stops are intrinsic — callers `break` out of the `for..of` loop when
  * they've found what they're looking for.
- *
- * `ordering`, if provided, controls the order in which neighbours of each
- * node are enqueued. Only matters for path-finding: a deterministic ordering
- * makes BFS return a deterministic shortest path when multiple exist.
  */
-export function* bfs<E>(
+export function bfs<E>(
   starts: Iterable<string>,
-  neighbours: (node: string) => Iterable<{ next: string; edge: E }>,
-  ordering?: (items: readonly { next: string; edge: E }[]) => readonly { next: string; edge: E }[],
-): Generator<BfsStep<E>> {
+  neighbours: (state: string) => Iterable<{ next: string; edge: E }>,
+): Generator<BfsStep<string, E>>;
+export function bfs<S, E>(
+  starts: Iterable<S>,
+  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,
+  key: (state: S) => string,
+): Generator<BfsStep<S, E>>;
+export function* bfs<S, E>(
+  starts: Iterable<S>,
+  neighbours: (state: S) => Iterable<{ next: S; edge: E }>,
+  // Identity default for the string overload. TypeScript can't express
+  // "default applies only when S = string", so this cast bridges the
+  // generic implementation signature to the public overloads — which
+  // guarantee `key` is omitted only when S = string at the call site.
+  key: (state: S) => string = (state) => state as unknown as string,
+): Generator<BfsStep<S, E>> {
+  // Queue entries carry the state alongside its key so we don't recompute
+  // key() twice per visit (once on dedup, once on parent lookup). Composite
+  // keys can be non-trivial to compute; string-overload callers pay nothing
+  // since key() is identity there.
+  interface Entry {
+    readonly state: S;
+    readonly key: string;
+  }
   const visited = new Set<string>();
-  const parentMap = new Map<string, { parent: string; edge: E }>();
-  const queue = new Queue<string>();
+  const parentMap = new Map<string, { parent: S; edge: E }>();
+  const queue = new Queue<Entry>();
   for (const start of starts) {
-    if (!visited.has(start)) {
-      visited.add(start);
-      queue.push(start);
+    const k = key(start);
+    if (!visited.has(k)) {
+      visited.add(k);
+      queue.push({ state: start, key: k });
     }
   }
   while (!queue.isEmpty) {
-    const current = queue.shift();
-    const parentInfo = parentMap.get(current);
+    const { state: current, key: curKey } = queue.shift();
+    const parentInfo = parentMap.get(curKey);
     yield {
-      node: current,
+      state: current,
       parent: parentInfo?.parent ?? null,
       incomingEdge: parentInfo?.edge ?? null,
     };
 
-    const items = neighbours(current);
-    const toVisit = ordering ? ordering([...items]) : items;
-    for (const { next, edge } of toVisit) {
-      if (!visited.has(next)) {
-        visited.add(next);
-        parentMap.set(next, { parent: current, edge });
-        queue.push(next);
+    for (const { next, edge } of neighbours(current)) {
+      const k = key(next);
+      if (!visited.has(k)) {
+        visited.add(k);
+        parentMap.set(k, { parent: current, edge });
+        queue.push({ state: next, key: k });
       }
     }
   }

package/src/graph.ts

@@ -0,0 +1,25 @@
+/**
+ * An entry in the migration graph. All on-disk migrations are attested,
+ * so `migrationHash` is always a string.
+ */
+export interface MigrationEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s this edge provides.
+   * An empty array means the migration declares no routing-visible
+   * data transforms.
+   */
+  readonly invariants: readonly string[];
+}
+
+export interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationEdge[]>;
+  readonly migrationByHash: ReadonlyMap<string, MigrationEdge>;
+}

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/invariants.ts

@@ -0,0 +1,45 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import { errorDuplicateInvariantInEdge, errorInvalidInvariantId } from './errors';
+import type { MigrationOps } from './package';
+
+/**
+ * Hygiene check for `invariantId`. Rejects empty values plus any
+ * whitespace or control character (including Unicode whitespace like
+ * NBSP and em space, which are visually identical to ASCII space and
+ * routinely sneak in via paste).
+ */
+export function validateInvariantId(invariantId: string): boolean {
+  if (invariantId.length === 0) return false;
+  return !/[\p{Cc}\p{White_Space}]/u.test(invariantId);
+}
+
+/**
+ * Walk a migration's operations and produce its `providedInvariants`
+ * aggregate: the sorted, deduplicated list of `invariantId`s declared
+ * by data-transform ops. Ops without `operationClass === 'data'` are
+ * skipped; data ops without an `invariantId` are skipped.
+ *
+ * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+ * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+ */
+export function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {
+  const seen = new Set<string>();
+  for (const op of ops) {
+    const invariantId = readInvariantId(op);
+    if (invariantId === undefined) continue;
+    if (!validateInvariantId(invariantId)) {
+      throw errorInvalidInvariantId(invariantId);
+    }
+    if (seen.has(invariantId)) {
+      throw errorDuplicateInvariantInEdge(invariantId);
+    }
+    seen.add(invariantId);
+  }
+  return [...seen].sort();
+}
+
+function readInvariantId(op: MigrationPlanOperation): string | undefined {
+  if (op.operationClass !== 'data') return undefined;
+  const candidate = (op as { invariantId?: unknown }).invariantId;
+  return typeof candidate === 'string' ? candidate : undefined;
+}

package/src/io.ts

@@ -7,9 +7,15 @@ import {
   errorInvalidJson,
   errorInvalidManifest,
   errorInvalidSlug,
+  errorMigrationHashMismatch,
   errorMissingFile,
+  errorProvidedInvariantsMismatch,
 } from './errors';
-import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
+import { verifyMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
+import type { MigrationMetadata } from './metadata';
+import { MigrationOpsSchema } from './op-schema';
+import type { MigrationOps, MigrationPackage } from './package';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -25,15 +31,16 @@ const MigrationHintsSchema = type({
   plannerVersion: 'string',
 });
 
-const MigrationManifestSchema = type({
-  from: 'string',
+const MigrationMetadataSchema = type({
+  '+': 'reject',
+  from: 'string > 0 | null',
   to: 'string',
-  migrationId: 'string',
-  kind: "'regular' | 'baseline'",
+  migrationHash: 'string',
   fromContract: 'object | null',
   toContract: 'object',
   hints: MigrationHintsSchema,
   labels: 'string[]',
+  providedInvariants: 'string[]',
   'authorship?': type({
     'author?': 'string',
     'email?': 'string',
@@ -45,18 +52,9 @@ const MigrationManifestSchema = type({
   createdAt: 'string',
 });
 
-const MigrationOpSchema = type({
-  id: 'string',
-  label: 'string',
-  operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
-});
-
-// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.
-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 +68,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 +98,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 +133,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 +147,48 @@ 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 {
+  // Re-derive before the hash check so format/duplicate diagnostics
+  // fire with their dedicated codes rather than as a generic hash mismatch.
+  const derivedInvariants = deriveProvidedInvariants(ops);
+  if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) {
+    throw errorProvidedInvariantsMismatch(
+      manifestPath,
+      metadata.providedInvariants,
+      derivedInvariants,
+    );
+  }
+
+  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 arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
 }
 
-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 +203,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 +214,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,41 @@
+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 | null;
+  readonly to: string;
+  readonly fromContract: Contract | null;
+  readonly toContract: Contract;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
+  readonly authorship?: { readonly author?: string; readonly email?: string };
+  readonly signature?: { readonly keyId: string; readonly value: string } | null;
+  readonly createdAt: string;
+}