@prisma-next/migration-tools 0.11.0 → 0.12.0

package/src/errors.ts

@@ -1,5 +1,6 @@
 import { ifDefined } from '@prisma-next/utils/defined';
 import { basename, dirname, relative } from 'pathe';
+import type { MigrationGraph } from './graph';
 
 /**
  * Build the canonical "re-emit this package" remediation hint.
@@ -319,8 +320,8 @@ export function errorProvidedInvariantsMismatch(
 /**
  * Wire-shape edge surfaced through the JSON envelope's
  * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —
- * authoring metadata (`createdAt`, `labels`) lives on `MigrationEdge` but
- * is intentionally dropped here so the envelope stays stable across
+ * authoring metadata (`createdAt`) lives on `MigrationEdge` but is
+ * intentionally dropped here so the envelope stays stable across
  * graph-internal refactors.
  *
  * Stability: any field added here is part of the public CLI JSON contract.
@@ -399,3 +400,58 @@ export function errorMigrationHashMismatch(
     details: { dir, storedHash, computedHash },
   });
 }
+
+export function errorSnapshotMissing(refName: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.SNAPSHOT_MISSING',
+    `Ref "${refName}" has no paired contract snapshot`,
+    {
+      why: `Ref "${refName}" exists but its paired snapshot files are missing.`,
+      fix: `Run "prisma-next db update --advance-ref ${refName}" to repopulate the snapshot, or "prisma-next ref delete ${refName}" to clear the orphan pointer.`,
+      details: { refName, identifier: refName, viaRef: true },
+    },
+  );
+}
+
+export function errorBundleNotFoundForGraphNode(
+  hash: string,
+  explicitLabel?: string,
+): MigrationToolsError {
+  const summary = explicitLabel
+    ? `No migration bundle found for reference "${explicitLabel}" (resolved hash: ${hash})`
+    : `No migration bundle found for graph node ${hash}`;
+  return new MigrationToolsError('MIGRATION.BUNDLE_NOT_FOUND_FOR_GRAPH_NODE', summary, {
+    why: `The hash ${hash} is a graph node but no on-disk migration package has an end-contract hash matching it.`,
+    fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+    details: { hash, ...(explicitLabel ? { explicitLabel } : {}) },
+  });
+}
+
+export function errorContractDeserializationFailed(
+  filePath: string,
+  message: string,
+): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.CONTRACT_DESERIALIZATION_FAILED',
+    'Contract failed to deserialize',
+    {
+      why: `Contract at "${filePath}" failed to deserialize: ${message}`,
+      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
+      details: { filePath, message },
+    },
+  );
+}
+
+export function errorHashNotInGraph(hash: string, graph: MigrationGraph): MigrationToolsError {
+  const reachableHashes = [...graph.nodes].sort();
+  const reachableList = reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none)';
+  return new MigrationToolsError(
+    'MIGRATION.HASH_NOT_IN_GRAPH',
+    `Hash "${hash}" is not a node in the migration graph`,
+    {
+      why: `The migration graph contains nodes ${reachableList}; "${hash}" isn't one of them.`,
+      fix: `Pass a hash that's the from-or-to of an on-disk migration bundle, use --from with a graph-node hash, or run "prisma-next migration plan" to introduce it.`,
+      details: { hash, reachableHashes },
+    },
+  );
+}

package/src/exports/aggregate.ts

@@ -1,22 +1,26 @@
 export {
-  type DeclaredExtensionEntry,
-  type LayoutViolation,
-  type LoadAggregateError,
-  type LoadAggregateInput,
-  type LoadAggregateOutput,
-  loadContractSpaceAggregate,
-} from '../aggregate/loader';
+  createContractSpaceAggregate,
+  createContractSpaceMember,
+  requireHeadRef,
+} from '../aggregate/aggregate';
+export {
+  computeIntegrityViolations,
+  type IntegrityComputationInput,
+  type IntegritySpaceState,
+  loadProblemToViolation,
+} from '../aggregate/check-integrity';
+export { type LoadAggregateInput, loadContractSpaceAggregate } from '../aggregate/loader';
 export type { ContractMarkerRecordLike } from '../aggregate/marker-types';
 export {
   type AggregateCurrentDBState,
   type AggregateMigrationEdgeRef,
-  type AggregatePerSpacePlan,
-  type AggregatePlannerError,
-  type AggregatePlannerInput,
-  type AggregatePlannerOutput,
-  type AggregatePlannerSuccess,
   type CallerPolicy,
-  planAggregate,
+  type PerSpacePlan,
+  type PlannerError,
+  type PlannerInput,
+  type PlannerOutput,
+  type PlannerSuccess,
+  planMigration,
 } from '../aggregate/planner';
 export { projectSchemaToSpace } from '../aggregate/project-schema-to-space';
 export {
@@ -25,18 +29,24 @@ export {
   graphWalkStrategy,
 } from '../aggregate/strategies/graph-walk';
 export type {
+  ContractAtOptions,
+  ContractAtResult,
   ContractSpaceAggregate,
   ContractSpaceMember,
-  HydratedMigrationGraph,
 } from '../aggregate/types';
 export {
-  type AggregateVerifierError,
-  type AggregateVerifierInput,
-  type AggregateVerifierOutput,
-  type AggregateVerifierSuccess,
   type MarkerCheckResult,
   type MarkerCheckSection,
   type OrphanElement,
   type SchemaCheckSection,
-  verifyAggregate,
+  type VerifierError,
+  type VerifierInput,
+  type VerifierOutput,
+  type VerifierSuccess,
+  verifyMigration,
 } from '../aggregate/verifier';
+export type {
+  DeclaredExtensionEntry,
+  IntegrityQueryOptions,
+  IntegrityViolation,
+} from '../integrity-violation';

package/src/exports/io.ts

@@ -3,6 +3,8 @@ export {
   formatMigrationDirName,
   materialiseExtensionMigrationPackageIfMissing,
   materialiseMigrationPackage,
+  type PackageLoadProblem,
+  type ReadMigrationsDirResult,
   readMigrationPackage,
   readMigrationsDir,
   writeMigrationMetadata,

package/src/exports/metadata.ts

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

package/src/exports/migration-graph.ts

@@ -1,3 +1,4 @@
+export { assertHashIsGraphNode, isGraphNode } from '../graph-membership';
 export type { PathDecision } from '../migration-graph';
 export {
   detectCycles,

package/src/exports/refs.ts

@@ -1,10 +1,21 @@
 export type { RefEntry, Refs } from '../refs';
 export {
   deleteRef,
+  HEAD_REF_NAME,
   readRef,
   readRefs,
+  refsByContractHash,
   resolveRef,
+  resolveRefsByContractHash,
   validateRefName,
   validateRefValue,
   writeRef,
 } from '../refs';
+export type { ContractIR } from '../refs/snapshot';
+export {
+  deleteRefPaired,
+  deleteRefSnapshot,
+  readRefSnapshot,
+  writeRefPaired,
+  writeRefSnapshot,
+} from '../refs/snapshot';

package/src/exports/spaces.ts

@@ -31,7 +31,10 @@ export {
   APP_SPACE_ID,
   assertValidSpaceId,
   isValidSpaceId,
+  RESERVED_SPACE_SUBDIR_NAMES,
+  SPACE_REFS_DIRNAME,
   spaceMigrationDirectory,
+  spaceRefsDirectory,
   type ValidSpaceId,
 } from '../space-layout';
 export {

package/src/graph-membership.ts

@@ -0,0 +1,17 @@
+import { EMPTY_CONTRACT_HASH } from './constants';
+import { errorHashNotInGraph } from './errors';
+import type { MigrationGraph } from './graph';
+
+export function isGraphNode(hash: string, graph: MigrationGraph): boolean {
+  if (hash === EMPTY_CONTRACT_HASH) {
+    return true;
+  }
+  return graph.nodes.has(hash);
+}
+
+export function assertHashIsGraphNode(hash: string, graph: MigrationGraph): asserts hash is string {
+  if (isGraphNode(hash, graph)) {
+    return;
+  }
+  throw errorHashNotInGraph(hash, graph);
+}

package/src/graph.ts

@@ -8,7 +8,6 @@ export interface MigrationEdge {
   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

package/src/hash.ts

@@ -15,13 +15,12 @@ function sha256Hex(input: string): string {
 }
 
 /**
- * Content-addressed migration hash over (metadata envelope sans hints,
- * ops). See ADR 199 — Storage-only migration identity for the
- * rationale: the storage-hash bookends (`from`, `to`) inside the
- * envelope anchor the contract identity by hash, and planner hints are
- * advisory and must not affect identity. The full contract IRs are not
- * part of the manifest — they live in sibling `*-contract.json` files
- * authored alongside the migration, never inlined here.
+ * Content-addressed migration hash over (metadata envelope, ops). See
+ * ADR 199 — Storage-only migration identity for the rationale: the
+ * storage-hash bookends (`from`, `to`) inside the envelope anchor the
+ * contract identity by hash. The full contract IRs are not part of the
+ * manifest — they live in sibling `*-contract.json` files authored
+ * alongside the migration, never inlined here.
  *
  * The integrity check is purely structural, not semantic. The function
  * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
@@ -46,7 +45,7 @@ export function computeMigrationHash(
   metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },
   ops: MigrationOps,
 ): string {
-  const { migrationHash: _migrationHash, hints: _hints, ...strippedMeta } = metadata;
+  const { migrationHash: _migrationHash, ...strippedMeta } = metadata;
 
   const canonicalMetadata = canonicalizeJson(strippedMeta);
   const canonicalOps = canonicalizeJson(ops);

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,