@prisma-next/migration-tools 0.11.0-dev.5 → 0.11.0-dev.50

package/src/integrity-violation.ts

@@ -0,0 +1,114 @@
+/**
+ * Every structural problem the migration model can carry.
+ *
+ * Violations come in three groups:
+ *
+ * - **Recoverable**: the package or space is retained in the model;
+ *   the violation is surfaced for policy (report, refuse, or ignore
+ *   depending on the command).
+ * - **Config/contract-dependent**: produced only when the matching
+ *   `IntegrityQueryOptions` opt is set (declaredExtensions /
+ *   checkContracts). The model is built without them; they surface
+ *   when the caller explicitly asks for the broader integrity view.
+ * - **Unloadable**: the package is omitted from the model entirely
+ *   (its on-disk content cannot be parsed into an `OnDiskMigrationPackage`).
+ *
+ * `checkIntegrity()` on `ContractSpaceAggregate` returns the full set —
+ * all violations across all spaces — never bailing at the first hit.
+ */
+export type IntegrityViolation =
+  // recoverable — package/space retained, surfaced for policy
+  | {
+      readonly kind: 'sameSourceAndTarget';
+      readonly spaceId: string;
+      readonly dirName: string;
+      readonly hash: string;
+    }
+  | {
+      readonly kind: 'hashMismatch';
+      readonly spaceId: string;
+      readonly dirName: string;
+      readonly stored: string;
+      readonly computed: string;
+    }
+  | {
+      readonly kind: 'providedInvariantsMismatch';
+      readonly spaceId: string;
+      readonly dirName: string;
+    }
+  | { readonly kind: 'headRefMissing'; readonly spaceId: string }
+  | { readonly kind: 'headRefNotInGraph'; readonly spaceId: string; readonly hash: string }
+  | {
+      readonly kind: 'duplicateMigrationHash';
+      readonly spaceId: string;
+      readonly migrationHash: string;
+      readonly dirNames: readonly string[];
+    }
+  | {
+      readonly kind: 'refUnreadable';
+      readonly spaceId: string;
+      readonly refName: string;
+      readonly detail: string;
+    }
+  // config/contract-dependent — produced only when the matching opt is set
+  | { readonly kind: 'orphanSpaceDir'; readonly spaceId: string }
+  | { readonly kind: 'declaredButUnmigrated'; readonly spaceId: string }
+  | {
+      readonly kind: 'targetMismatch';
+      readonly spaceId: string;
+      readonly expected: string;
+      readonly actual: string;
+    }
+  | {
+      readonly kind: 'disjointness';
+      readonly element: string;
+      readonly claimedBy: readonly string[];
+    }
+  | { readonly kind: 'contractUnreadable'; readonly spaceId: string; readonly detail: string }
+  // genuinely unloadable — package omitted from member.packages
+  | {
+      readonly kind: 'packageUnloadable';
+      readonly spaceId: string;
+      readonly dirName: string;
+      readonly detail: string;
+    };
+
+/**
+ * One declared extension entry, drawn from `Config.extensionPacks`.
+ *
+ * The integrity layer needs only:
+ *
+ * - `id` — the space id (also the directory name under `migrations/`),
+ *   used for the layout-drift checks (`orphanSpaceDir` /
+ *   `declaredButUnmigrated`).
+ * - `targetId` — the target the declaring extension was configured for.
+ *
+ * Typed structurally so the migration-tools layer stays framework-neutral.
+ */
+export interface DeclaredExtensionEntry {
+  readonly id: string;
+  readonly targetId: string;
+}
+
+/**
+ * Options controlling which config/contract-dependent violation checks
+ * `checkIntegrity()` runs.
+ *
+ * Both opts default to disabled: a caller without the app contract or
+ * declared extensions still gets the structurally-derivable violations
+ * (hashMismatch, providedInvariantsMismatch, headRefMissing,
+ * headRefNotInGraph, refUnreadable, sameSourceAndTarget, packageUnloadable).
+ */
+export interface IntegrityQueryOptions {
+  /**
+   * When provided, enables layout-drift checks: `orphanSpaceDir`
+   * (a directory exists on disk for an extension not in the list) and
+   * `declaredButUnmigrated` (an extension in the list has no on-disk dir).
+   */
+  readonly declaredExtensions?: readonly DeclaredExtensionEntry[];
+  /**
+   * When true, enables contract/disjointness/target checks:
+   * `contractUnreadable`, `targetMismatch`, `disjointness`.
+   */
+  readonly checkContracts?: boolean;
+}

package/src/io.ts

@@ -14,6 +14,7 @@ import {
   errorMigrationHashMismatch,
   errorMissingFile,
   errorProvidedInvariantsMismatch,
+  MigrationToolsError,
 } from './errors';
 import { verifyMigrationHash } from './hash';
 import { deriveProvidedInvariants } from './invariants';
@@ -28,19 +29,11 @@ function hasErrnoCode(error: unknown, code: string): boolean {
   return error instanceof Error && (error as { code?: string }).code === code;
 }
 
-const MigrationHintsSchema = type({
-  used: 'string[]',
-  applied: 'string[]',
-  plannerVersion: 'string',
-});
-
 const MigrationMetadataSchema = type({
   '+': 'reject',
   from: 'string > 0 | null',
   to: 'string',
   migrationHash: 'string',
-  hints: MigrationHintsSchema,
-  labels: 'string[]',
   providedInvariants: 'string[]',
   createdAt: 'string',
 });
@@ -255,6 +248,60 @@ export async function readMigrationPackage(dir: string): Promise<OnDiskMigration
   return pkg;
 }
 
+/**
+ * Reads a migration package's manifest and ops without running hash or
+ * invariants verification. Returns `null` when the files cannot be read or
+ * parsed (i.e. when the package is genuinely unloadable).
+ *
+ * Used by {@link readMigrationsDir} to retain a package whose hash or
+ * invariants diverge from what is stored on disk — the raw content is still
+ * useful for display / querying; only integrity is in question.
+ */
+async function readMigrationPackageRaw(dir: string): Promise<OnDiskMigrationPackage | null> {
+  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 {
+    return null;
+  }
+  let opsRaw: string;
+  try {
+    opsRaw = await readFile(opsPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  let metadata: MigrationMetadata;
+  try {
+    metadata = JSON.parse(manifestRaw);
+  } catch {
+    return null;
+  }
+  let ops: MigrationOps;
+  try {
+    ops = JSON.parse(opsRaw);
+  } catch {
+    return null;
+  }
+
+  const result = MigrationMetadataSchema(metadata);
+  if (result instanceof type.errors) return null;
+
+  const opsResult = MigrationOpsSchema(ops);
+  if (opsResult instanceof type.errors) return null;
+
+  return {
+    dirName: basename(absoluteDir),
+    dirPath: absoluteDir,
+    metadata,
+    ops,
+  };
+}
+
 function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) {
@@ -280,20 +327,64 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
   }
 }
 
-export async function readMigrationsDir(
-  migrationsRoot: string,
-): Promise<readonly OnDiskMigrationPackage[]> {
+/**
+ * A per-package load-time problem returned by {@link readMigrationsDir}.
+ *
+ * Three variants, matching the relocated throws from the load path:
+ *
+ * - `hashMismatch` — stored `migrationHash` differs from the recomputed value.
+ *   The package is **retained** in the returned `packages` array.
+ * - `providedInvariantsMismatch` — `migration.json` declares different
+ *   `providedInvariants` than `ops.json` implies.  The package is **retained**.
+ * - `packageUnloadable` — the manifest is missing, unparseable, or schema-
+ *   invalid.  The package is **omitted** from `packages`.
+ *
+ * Callers that need the `spaceId` context (e.g. the aggregate loader) attach
+ * it when converting to {@link import('./integrity-violation').IntegrityViolation}.
+ */
+export type PackageLoadProblem =
+  | {
+      readonly kind: 'hashMismatch';
+      readonly dirName: string;
+      readonly stored: string;
+      readonly computed: string;
+    }
+  | { readonly kind: 'providedInvariantsMismatch'; readonly dirName: string }
+  | { readonly kind: 'packageUnloadable'; readonly dirName: string; readonly detail: string };
+
+/**
+ * Result returned by {@link readMigrationsDir}.
+ *
+ * - `packages` — every package that could be read; hash-mismatched and
+ *   invariants-mismatched packages are included here (the problem is
+ *   represented rather than fatal).
+ * - `problems` — one entry per package that had a load-time issue.
+ *   `packageUnloadable` entries are **not** in `packages`.
+ */
+export interface ReadMigrationsDirResult {
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly problems: readonly PackageLoadProblem[];
+}
+
+function packageLoadProblemDetailFromError(error: unknown): string {
+  if (MigrationToolsError.is(error)) return error.why;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+export async function readMigrationsDir(migrationsRoot: string): Promise<ReadMigrationsDirResult> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
   } catch (error) {
     if (hasErrnoCode(error, 'ENOENT')) {
-      return [];
+      return { packages: [], problems: [] };
     }
     throw error;
   }
 
   const packages: OnDiskMigrationPackage[] = [];
+  const problems: PackageLoadProblem[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);
@@ -307,10 +398,44 @@ export async function readMigrationsDir(
       continue; // skip non-migration directories
     }
 
-    packages.push(await readMigrationPackage(entryPath));
+    let pkg: OnDiskMigrationPackage;
+    try {
+      pkg = await readMigrationPackage(entryPath);
+    } catch (error) {
+      const dirName = entry;
+      if (MigrationToolsError.is(error)) {
+        if (error.code === 'MIGRATION.HASH_MISMATCH') {
+          const details = error.details;
+          const rawPkg = await readMigrationPackageRaw(entryPath);
+          if (rawPkg !== null) packages.push(rawPkg);
+          problems.push({
+            kind: 'hashMismatch',
+            dirName,
+            stored: typeof details?.['storedHash'] === 'string' ? details['storedHash'] : '',
+            computed: typeof details?.['computedHash'] === 'string' ? details['computedHash'] : '',
+          });
+          continue;
+        }
+        if (error.code === 'MIGRATION.PROVIDED_INVARIANTS_MISMATCH') {
+          const rawPkg = await readMigrationPackageRaw(entryPath);
+          if (rawPkg !== null) packages.push(rawPkg);
+          problems.push({ kind: 'providedInvariantsMismatch', dirName });
+          continue;
+        }
+      }
+      // Any other error (missing file, invalid JSON, invalid manifest schema) →
+      // package unloadable; omit from packages.
+      problems.push({
+        kind: 'packageUnloadable',
+        dirName,
+        detail: packageLoadProblemDetailFromError(error),
+      });
+      continue;
+    }
+    packages.push(pkg);
   }
 
-  return packages;
+  return { packages, problems };
 }
 
 export function formatMigrationDirName(timestamp: Date, slug: string): string {

package/src/metadata.ts

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

package/src/migration-base.ts

@@ -9,14 +9,13 @@ import { type } from 'arktype';
 import { errorInvalidOperationEntry } from './errors';
 import { computeMigrationHash } from './hash';
 import { deriveProvidedInvariants } from './invariants';
-import type { MigrationHints, MigrationMetadata } from './metadata';
+import type { MigrationMetadata } from './metadata';
 import { MigrationOpSchema } from './op-schema';
 import type { MigrationOps } from './package';
 
 export interface MigrationMeta {
   readonly from: string | null;
   readonly to: string;
-  readonly labels?: readonly string[];
 }
 
 // `from` rejects empty strings to mirror `MigrationMetadataSchema` in
@@ -27,7 +26,6 @@ export interface MigrationMeta {
 const MigrationMetaSchema = type({
   from: 'string > 0 | null',
   to: 'string',
-  'labels?': type('string').array(),
 });
 
 /**
@@ -127,12 +125,11 @@ export interface MigrationArtifacts {
  * 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`) and the operations
- * change as the author iterates. When no metadata exists yet (a bare
- * `migration.ts` run from scratch), synthesize a minimal but
+ * case: it was scaffolded by `migration plan`), preserve `createdAt`
+ * set there — that field is owned by the CLI scaffolder, not the authored
+ * class. Only the `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 record so the resulting package can still be read,
  * verified, and applied.
  *
@@ -147,39 +144,22 @@ function buildAttestedMetadata(
   const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: meta.from,
     to: meta.to,
-    labels: meta.labels ?? existing?.labels ?? [],
     providedInvariants: deriveProvidedInvariants(ops),
     createdAt: existing?.createdAt ?? new Date().toISOString(),
-    hints: normalizeHints(existing?.hints),
   };
 
   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 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.
- */
-function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
-  return {
-    used: existing?.used ?? [],
-    applied: existing?.applied ?? [],
-    plannerVersion: existing?.plannerVersion ?? '2.0.0',
-  };
-}
-
 /**
  * Pure conversion from a `Migration` instance (plus the previously
  * scaffolded metadata, when one exists on disk) to the in-memory
  * artifacts that downstream tooling persists. Owns metadata validation,
- * 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` / `metadataJson`).
+ * metadata synthesis/preservation, and the content-addressed
+ * `migrationHash` computation, but performs no file I/O — callers handle
+ * reads (to source `existing`) and writes (to persist `opsJson` /
+ * `metadataJson`).
  */
 export function buildMigrationArtifacts(
   instance: Migration,

package/src/migration-graph.ts

@@ -1,12 +1,6 @@
 import { ifDefined } from '@prisma-next/utils/defined';
 import { EMPTY_CONTRACT_HASH } from './constants';
-import {
-  errorAmbiguousTarget,
-  errorDuplicateMigrationHash,
-  errorNoInitialMigration,
-  errorNoTarget,
-  errorSameSourceAndTarget,
-} from './errors';
+import { errorAmbiguousTarget, errorNoInitialMigration, errorNoTarget } from './errors';
 import type { MigrationEdge, MigrationGraph } from './graph';
 import { bfs } from './graph-ops';
 import type { OnDiskMigrationPackage } from './package';
@@ -50,13 +44,6 @@ export function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): M
     const from = pkg.metadata.from ?? EMPTY_CONTRACT_HASH;
     const { to } = pkg.metadata;
 
-    if (from === to) {
-      const hasDataOp = pkg.ops.some((op) => op.operationClass === 'data');
-      if (!hasDataOp) {
-        throw errorSameSourceAndTarget(pkg.dirPath, from);
-      }
-    }
-
     nodes.add(from);
     nodes.add(to);
 
@@ -66,14 +53,12 @@ export function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): M
       migrationHash: pkg.metadata.migrationHash,
       dirName: pkg.dirName,
       createdAt: pkg.metadata.createdAt,
-      labels: pkg.metadata.labels,
       invariants: pkg.metadata.providedInvariants,
     };
 
-    if (migrationByHash.has(migration.migrationHash)) {
-      throw errorDuplicateMigrationHash(migration.migrationHash);
+    if (!migrationByHash.has(migration.migrationHash)) {
+      migrationByHash.set(migration.migrationHash, migration);
     }
-    migrationByHash.set(migration.migrationHash, migration);
 
     appendEdge(forwardChain, from, migration);
     appendEdge(reverseChain, to, migration);
@@ -85,23 +70,10 @@ export function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): M
 // ---------------------------------------------------------------------------
 // Deterministic tie-breaking for BFS neighbour order.
 // Used by path-finders only; not a general-purpose utility.
-// Ordering: label priority → createdAt → to → migrationHash.
+// Ordering: createdAt → to → migrationHash.
 // ---------------------------------------------------------------------------
 
-const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
-
-function labelPriority(labels: readonly string[]): number {
-  let best = 3;
-  for (const l of labels) {
-    const p = LABEL_PRIORITY[l];
-    if (p !== undefined && p < best) best = p;
-  }
-  return best;
-}
-
 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);
@@ -119,7 +91,7 @@ function sortedNeighbors(edges: readonly MigrationEdge[]): readonly MigrationEdg
  * exists. Returns an empty array when `fromHash === toHash` (no-op).
  *
  * Neighbor ordering is deterministic via the tie-break sort key:
- * label priority → createdAt → to → migrationHash.
+ * createdAt → to → migrationHash.
  */
 export function findPath(
   graph: MigrationGraph,
@@ -165,8 +137,8 @@ export function findPath(
  * 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;
+ * invariant come first, with `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(

package/src/migration-list-graph-topology.ts

@@ -0,0 +1,158 @@
+import { EMPTY_CONTRACT_HASH } from './constants';
+import type { MigrationListEntry } from './migration-list-types';
+
+export type MigrationEdgeKind = 'forward' | 'rollback' | 'self';
+
+export interface MigrationListGraphTopology {
+  readonly kindByMigrationHash: ReadonlyMap<string, MigrationEdgeKind>;
+  readonly forwardInDegree: ReadonlyMap<string, number>;
+  readonly forwardOutDegree: ReadonlyMap<string, number>;
+}
+
+interface NonSelfEdge {
+  readonly entry: MigrationListEntry;
+  readonly from: string;
+  readonly to: string;
+}
+
+function canonicalFrom(from: string | null): string {
+  return from ?? EMPTY_CONTRACT_HASH;
+}
+
+function compareDirNameDesc(a: MigrationListEntry, b: MigrationListEntry): number {
+  return b.dirName.localeCompare(a.dirName);
+}
+
+function bumpDegree(map: Map<string, number>, key: string): void {
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+
+export function classifyMigrationListGraphTopology(
+  entries: readonly MigrationListEntry[],
+): MigrationListGraphTopology {
+  const nodes = new Set<string>();
+  const kindByMigrationHash = new Map<string, MigrationEdgeKind>();
+  const outgoingByFrom = new Map<string, NonSelfEdge[]>();
+
+  for (const entry of entries) {
+    const from = canonicalFrom(entry.from);
+    const to = entry.to;
+    nodes.add(from);
+    nodes.add(to);
+
+    if (from === to) {
+      kindByMigrationHash.set(entry.migrationHash, 'self');
+      continue;
+    }
+
+    const bucket = outgoingByFrom.get(from);
+    const edge: NonSelfEdge = { entry, from, to };
+    if (bucket) bucket.push(edge);
+    else outgoingByFrom.set(from, [edge]);
+  }
+
+  for (const bucket of outgoingByFrom.values()) {
+    bucket.sort((a, b) => compareDirNameDesc(a.entry, b.entry));
+  }
+
+  const nonSelfInDegree = new Map<string, number>();
+  for (const node of nodes) {
+    nonSelfInDegree.set(node, 0);
+  }
+  for (const bucket of outgoingByFrom.values()) {
+    for (const edge of bucket) {
+      bumpDegree(nonSelfInDegree, edge.to);
+    }
+  }
+
+  const dfsRoots: string[] = [];
+  for (const node of nodes) {
+    if ((nonSelfInDegree.get(node) ?? 0) === 0) {
+      dfsRoots.push(node);
+    }
+  }
+  dfsRoots.sort((a, b) => {
+    if (a === EMPTY_CONTRACT_HASH) return -1;
+    if (b === EMPTY_CONTRACT_HASH) return 1;
+    return a.localeCompare(b);
+  });
+  if (dfsRoots.length === 0) {
+    dfsRoots.push(...[...nodes].sort((a, b) => a.localeCompare(b)));
+  }
+
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>();
+  for (const node of nodes) {
+    color.set(node, WHITE);
+  }
+
+  interface Frame {
+    node: string;
+    outgoing: readonly NonSelfEdge[];
+    index: number;
+  }
+  const stack: Frame[] = [];
+
+  function pushFrame(node: string): void {
+    color.set(node, GRAY);
+    stack.push({ node, outgoing: outgoingByFrom.get(node) ?? [], index: 0 });
+  }
+
+  function runDfsFrom(root: string): void {
+    if (color.get(root) !== WHITE) return;
+    pushFrame(root);
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame === undefined) break;
+      if (frame.index >= frame.outgoing.length) {
+        color.set(frame.node, BLACK);
+        stack.pop();
+        continue;
+      }
+
+      const edge = frame.outgoing[frame.index];
+      frame.index += 1;
+      if (edge === undefined) continue;
+
+      const v = edge.to;
+      const vColor = color.get(v);
+      if (vColor === GRAY) {
+        kindByMigrationHash.set(edge.entry.migrationHash, 'rollback');
+      } else {
+        kindByMigrationHash.set(edge.entry.migrationHash, 'forward');
+        if (vColor === WHITE) {
+          pushFrame(v);
+        }
+      }
+    }
+  }
+
+  for (const root of dfsRoots) {
+    runDfsFrom(root);
+  }
+  const remainingWhite = [...nodes].filter((node) => color.get(node) === WHITE);
+  remainingWhite.sort((a, b) => a.localeCompare(b));
+  for (const root of remainingWhite) {
+    runDfsFrom(root);
+  }
+
+  const forwardInDegree = new Map<string, number>();
+  const forwardOutDegree = new Map<string, number>();
+
+  for (const entry of entries) {
+    if (kindByMigrationHash.get(entry.migrationHash) !== 'forward') continue;
+    const from = canonicalFrom(entry.from);
+    const to = entry.to;
+    bumpDegree(forwardOutDegree, from);
+    bumpDegree(forwardInDegree, to);
+  }
+
+  return {
+    kindByMigrationHash,
+    forwardInDegree,
+    forwardOutDegree,
+  };
+}

package/src/migration-list-types.ts

@@ -0,0 +1,21 @@
+export interface MigrationListEntry {
+  readonly dirName: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+  readonly refs: readonly string[];
+  readonly providedInvariants: readonly string[];
+}
+
+export interface MigrationSpaceListEntry {
+  readonly spaceId: string;
+  readonly migrations: readonly MigrationListEntry[];
+}
+
+export interface MigrationListResult {
+  readonly ok: true;
+  readonly spaces: readonly MigrationSpaceListEntry[];
+  readonly summary: string;
+}