@prisma-next/migration-tools 0.5.0-dev.9 → 0.5.1

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, OnDiskMigrationPackage } 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: OnDiskMigrationPackage): 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,61 @@
+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 ops in the migration. Ops without an `invariantId` are skipped.
+ *
+ * Both `data`-class ops (data-transforms, e.g. backfills) and
+ * `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle
+ * via `installEqlBundleOp`) may declare invariantIds: the
+ * `operationClass` axis classifies *policy gating* (which kinds of ops
+ * a `db init` / `db update` policy permits), while `invariantId`
+ * classifies *marker bookkeeping* (which named bundles of work a
+ * future regeneration knows to skip). The two concerns are
+ * intentionally orthogonal — an extension can ship additive
+ * non-IR-derivable DDL (the only way the planner can know the bundle
+ * is already applied is via the invariantId on the marker) without
+ * needing to mis-classify it as `data`-class.
+ *
+ * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+ * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+ *
+ * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
+ *   — extension migrations carry `invariantId`s on additive ops; e.g.
+ *   cipherstash's `installEqlBundle` and structural `create-*` ops are
+ *   additive-class but carry `cipherstash:*` invariantIds.
+ */
+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 (!Object.hasOwn(op, 'invariantId')) return undefined;
+  const candidate = (op as { invariantId?: unknown }).invariantId;
+  return typeof candidate === 'string' ? candidate : undefined;
+}

package/src/io.ts

@@ -1,17 +1,27 @@
-import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import type {
+  MigrationMetadata,
+  MigrationPackage,
+} from '@prisma-next/framework-components/control';
 import { type } from 'arktype';
-import { basename, dirname, join } from 'pathe';
+import { basename, dirname, join, resolve } from 'pathe';
+import { canonicalizeJson } from './canonicalize-json';
 import {
   errorDirectoryExists,
   errorInvalidDestName,
   errorInvalidJson,
   errorInvalidManifest,
   errorInvalidSlug,
+  errorMigrationHashMismatch,
   errorMissingFile,
+  errorProvidedInvariantsMismatch,
 } from './errors';
-import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
+import { verifyMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
+import { MigrationOpsSchema } from './op-schema';
+import type { MigrationOps, OnDiskMigrationPackage } from './package';
 
-const MANIFEST_FILE = 'migration.json';
+export const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
 const MAX_SLUG_LENGTH = 64;
 
@@ -25,15 +35,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 +56,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,10 +72,100 @@ 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' });
 }
 
+/**
+ * Materialise an in-memory {@link MigrationPackage} to a per-space
+ * directory on disk.
+ *
+ * Writes three files under `<targetDir>/<pkg.dirName>/`:
+ *
+ * - `migration.json` — the manifest (pretty-printed, matches
+ *   {@link writeMigrationPackage}'s output for byte-for-byte parity with
+ *   app-space migrations).
+ * - `ops.json` — the operation list (pretty-printed).
+ * - `contract.json` — the canonical-JSON serialisation of
+ *   `metadata.toContract`. This is the per-package post-state contract
+ *   snapshot; the canonicalisation pass guarantees byte-determinism so
+ *   re-emitting the same package across machines / runs produces an
+ *   identical file.
+ *
+ * Distinct verb from the lower-level {@link writeMigrationPackage}
+ * (which takes constituent `(metadata, ops)`): callers reading
+ * `materialise…` know they are persisting a struct-typed package
+ * including its contract-snapshot side car.
+ *
+ * Overwrite-idempotent: the per-package directory is cleared before
+ * each emit, so re-running against the same `targetDir` produces
+ * byte-identical contents and never leaves stale files behind. The
+ * spec's "re-emitting the same package across runs / machines produces
+ * byte-identical files" guarantee (§ 3) covers both same-dir and
+ * fresh-dir re-emits. The lower-level {@link writeMigrationPackage}
+ * stays strict because the CLI authoring path (`migration plan` /
+ * `migration new`) deliberately refuses to clobber an existing
+ * authored migration; this helper is the re-emit path that is
+ * supposed to converge on a single canonical on-disk shape.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).
+ */
+export async function materialiseMigrationPackage(
+  targetDir: string,
+  pkg: MigrationPackage,
+): Promise<void> {
+  const dir = join(targetDir, pkg.dirName);
+  await rm(dir, { recursive: true, force: true });
+  await writeMigrationPackage(dir, pkg.metadata, pkg.ops);
+  await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(pkg.metadata.toContract)}\n`, {
+    flag: 'wx',
+  });
+}
+
+/**
+ * Idempotent variant of {@link materialiseMigrationPackage}: writes the
+ * package only if `<targetDir>/<pkg.dirName>/` does not already exist on
+ * disk as a directory; returns `{ written: false }` when the package
+ * directory is present (no rewrite, no comparison — by-existence skip).
+ *
+ * Concretely:
+ *   - existing directory → skip silently, return `{ written: false }`.
+ *   - missing path → write three files via {@link materialiseMigrationPackage},
+ *     return `{ written: true }`.
+ *   - path exists but is not a directory (file/symlink) → treated as
+ *     missing; {@link materialiseMigrationPackage} will attempt creation
+ *     and fail with an appropriate OS error.
+ *   - any other I/O error from `stat` → propagated unchanged.
+ *
+ * Used by the CLI's `runContractSpaceExtensionMigrationsPass` to
+ * materialise extension migration packages into a project's
+ * `migrations/<spaceId>/` directory, and by extension-package tests
+ * that mirror the same idempotent-rematerialise property locally
+ * without taking a CLI dependency.
+ */
+export async function materialiseExtensionMigrationPackageIfMissing(
+  targetDir: string,
+  pkg: MigrationPackage,
+): Promise<{ readonly written: boolean }> {
+  const pkgDir = join(targetDir, pkg.dirName);
+  if (await directoryExists(pkgDir)) {
+    return { written: false };
+  }
+  await materialiseMigrationPackage(targetDir, pkg);
+  return { written: true };
+}
+
+async function directoryExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) return false;
+    throw error;
+  }
+}
+
 /**
  * Copy a list of files into `destDir`, optionally renaming each one.
  *
@@ -98,27 +190,28 @@ 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> {
-  const manifestPath = join(dir, MANIFEST_FILE);
-  const opsPath = join(dir, OPS_FILE);
+export async function readMigrationPackage(dir: string): Promise<OnDiskMigrationPackage> {
+  const absoluteDir = resolve(dir);
+  const manifestPath = join(absoluteDir, MANIFEST_FILE);
+  const opsPath = join(absoluteDir, OPS_FILE);
 
   let manifestRaw: string;
   try {
     manifestRaw = await readFile(manifestPath, 'utf-8');
   } catch (error) {
     if (hasErrnoCode(error, 'ENOENT')) {
-      throw errorMissingFile(MANIFEST_FILE, dir);
+      throw errorMissingFile(MANIFEST_FILE, absoluteDir);
     }
     throw error;
   }
@@ -128,14 +221,14 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     opsRaw = await readFile(opsPath, 'utf-8');
   } catch (error) {
     if (hasErrnoCode(error, 'ENOENT')) {
-      throw errorMissingFile(OPS_FILE, dir);
+      throw errorMissingFile(OPS_FILE, absoluteDir);
     }
     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 +240,52 @@ 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 {
-    dirName: basename(dir),
-    dirPath: dir,
-    manifest,
+  // 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: OnDiskMigrationPackage = {
+    dirName: basename(absoluteDir),
+    dirPath: absoluteDir,
+    metadata,
     ops,
   };
+
+  const verification = verifyMigrationHash(pkg);
+  if (!verification.ok) {
+    throw errorMigrationHashMismatch(
+      absoluteDir,
+      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 +300,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationBundle[]> {
+): Promise<readonly OnDiskMigrationPackage[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -188,7 +311,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationBundle[] = [];
+  const packages: OnDiskMigrationPackage[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);

package/src/metadata.ts

@@ -0,0 +1 @@
+export type { MigrationHints, MigrationMetadata } from '@prisma-next/framework-components/control';