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

package/src/aggregate/strategies/synth.ts

@@ -73,7 +73,7 @@ export async function synthStrategy<TFamilyId extends string, TTargetId extends
 
   const planner = input.migrations.createPlanner(input.familyInstance);
   const plannerResult: MigrationPlannerResult = await (planner.plan({
-    contract: input.member.contract,
+    contract: input.member.contract(),
     schema: projectedSchema,
     policy: input.operationPolicy,
     fromContract: null,
@@ -114,7 +114,7 @@ export async function synthStrategy<TFamilyId extends string, TTargetId extends
     result: {
       plan,
       displayOps: synthedPlan.operations,
-      destinationContract: input.member.contract,
+      destinationContract: input.member.contract(),
       strategy: 'synth',
     },
   };

package/src/aggregate/types.ts

@@ -1,89 +1,81 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { MigrationGraph } from '../graph';
+import type { IntegrityQueryOptions, IntegrityViolation } from '../integrity-violation';
 import type { OnDiskMigrationPackage } from '../package';
-
-/**
- * Hydrated migration graph for a single contract space.
- *
- * `graph` is the structural shortest-path graph (forward / reverse chain,
- * deterministic tie-break order) reconstructed from a set of on-disk
- * migration packages. `packagesByMigrationHash` is the lookup table the
- * graph-walk strategy uses to resolve a path's edge sequence back to the
- * concrete `OnDiskMigrationPackage` (and therefore the operation list) for
- * apply.
- *
- * Eagerly hydrated by the loader. Once a `ContractSpaceAggregate` exists,
- * downstream consumers do **not** touch the filesystem to walk graphs or
- * resolve packages — the aggregate is the boundary.
- */
-export interface HydratedMigrationGraph {
-  readonly graph: MigrationGraph;
-  readonly packagesByMigrationHash: ReadonlyMap<string, OnDiskMigrationPackage>;
-}
+import type { Refs } from '../refs';
+import type { ContractSpaceHeadRecord } from '../verify-contract-spaces';
 
 /**
  * One contract space — app or extension — as a member of a
  * {@link ContractSpaceAggregate}. Every member has the same shape.
  *
+ * A member is a tolerant snapshot of one space's on-disk state, not a
+ * validated value: `packages` is the raw migration-package list as read
+ * from disk (a hash- or invariants-mismatched package is retained here;
+ * a genuinely unparseable one is omitted), and integrity is judged
+ * separately by {@link ContractSpaceAggregate.checkIntegrity}.
+ *
  * - `spaceId`: `'app'` for the application, otherwise the extension's
  *   id (validated against `[a-z][a-z0-9_-]{0,63}`).
- * - `contract`: the validated contract value for this member. For the
- *   app, the user's authored contract; for an extension, the on-disk
- *   `migrations/<spaceId>/contract.json`. Both have already passed the
- *   family's `deserializeContract` at the loader boundary.
- * - `headRef.hash`: the storage hash this member is targeting. For the
- *   app, equals `contract.storage.storageHash`. For extensions, the
- *   on-disk `refs/head.json.hash`.
- * - `headRef.invariants`: alphabetically sorted, deduplicated invariant
- *   ids declared on the head ref. Empty for the app member (the app's
- *   plan is synthesised from the contract IR, no invariants required).
- * - `migrations`: the hydrated migration graph for this space. Possibly
- *   empty (an extension whose on-disk head ref points at the
- *   empty-contract sentinel and ships no migrations yet, or the app
- *   when the user hasn't authored any).
+ * - `packages`: raw on-disk migration packages, as read; never
+ *   integrity-validated at load.
+ * - `refs`: the user-authored refs under `migrations/<spaceId>/refs/*.json`.
+ * - `headRef`: the system head ref read from
+ *   `migrations/<spaceId>/refs/head.json`, or `null` when absent
+ *   (represented as a `headRefMissing` violation, never fatal). The app
+ *   member's head ref is always synthesised from its live contract's
+ *   storage hash, so it is never `null`.
+ * - `graph()`: the migration graph this space's packages induce —
+ *   lazily reconstructed on first call and memoised. Pure structure: a
+ *   `from === to` self-edge is represented, not rejected.
+ * - `contract()`: the deserialized contract for this member — lazily
+ *   produced on first call and memoised. For the app it is the live
+ *   contract the caller supplied; for an extension it is the on-disk
+ *   `migrations/<spaceId>/contract.json` run through the family's
+ *   `deserializeContract`. Throws if the on-disk contract is missing or
+ *   undeserializable (surfaced as `contractUnreadable` by `checkIntegrity`
+ *   under `checkContracts`); callers gate before querying it.
  */
 export interface ContractSpaceMember {
   readonly spaceId: string;
-  readonly contract: Contract;
-  readonly headRef: {
-    readonly hash: string;
-    readonly invariants: readonly string[];
-  };
-  readonly migrations: HydratedMigrationGraph;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly refs: Refs;
+  readonly headRef: ContractSpaceHeadRecord | null;
+  graph(): MigrationGraph;
+  contract(): Contract;
 }
 
 /**
- * Typed value carrying the user's app contract plus every loaded
- * extension contract space, fully hydrated and internally consistent.
+ * Tolerant, queryable snapshot of a project's on-disk migration state:
+ * the app contract space plus every extension contract space, each a
+ * {@link ContractSpaceMember}.
  *
  * Produced once per CLI invocation by `loadContractSpaceAggregate`.
- * Every downstream component (planner, verifier, runner adapter)
- * consumes this value rather than rebuilding state from disk.
- *
- * Invariants the loader enforces at construction:
- *
- * 1. `targetId` is consistent across every member (`contract.target`
- *    matches `aggregate.targetId`). The aggregate's `targetId` is the
- *    `Config.adapter.targetId` value the loader was told to use.
- * 2. `aggregate.extensions` is sorted alphabetically by `spaceId`.
- *    Mirrors {@link import('../concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
- *    extension ordering convention so downstream apply order matches
- *    today's behaviour byte-for-byte.
- * 3. No two members claim the same storage element (table / type / etc.).
- * 4. For each extension member: `member.headRef.hash` is reachable from
- *    the empty-contract sentinel in `member.migrations.graph` (or the
- *    graph is empty and `member.headRef.hash === EMPTY_CONTRACT_HASH`).
- * 5. For the app member: `member.headRef.hash` equals
- *    `member.contract.storage.storageHash`. The app's `migrations`
- *    is hydrated from the user's authored `migrations/` (or empty if
- *    none).
+ * Building the aggregate never throws on disk content; every consumer
+ * obtains spaces / packages / refs / graphs from this one value rather
+ * than re-deriving them from disk.
  *
- * The aggregate is **type-uniform** post-construction: app/extension
- * distinguishability survives only at the caller-policy layer
- * (`ignoreGraphFor: new Set([appSpaceId])`), not on member shape.
+ * - `targetId`: the app contract's target; every member is expected to
+ *   share it (a mismatch surfaces as a `targetMismatch` violation under
+ *   `checkContracts`).
+ * - `app` / `extensions`: retained as fields for the existing planner /
+ *   verifier / runner consumers. `extensions` is sorted alphabetically
+ *   by `spaceId` (the apply-ordering convention).
+ * - `listSpaces()` / `hasSpace()` / `space()` / `spaces()`: the query
+ *   surface the read commands consume — `app` first, then extension ids
+ *   lex-ascending.
+ * - `checkIntegrity()`: judges the loaded model and returns every
+ *   violation (never bailing at the first). Config/contract-dependent
+ *   checks run only when the matching {@link IntegrityQueryOptions} opt
+ *   is set.
  */
 export interface ContractSpaceAggregate {
   readonly targetId: string;
   readonly app: ContractSpaceMember;
   readonly extensions: readonly ContractSpaceMember[];
+  listSpaces(): readonly string[];
+  hasSpace(id: string): boolean;
+  space(id: string): ContractSpaceMember | undefined;
+  spaces(): readonly ContractSpaceMember[];
+  checkIntegrity(opts?: IntegrityQueryOptions): readonly IntegrityViolation[];
 }

package/src/aggregate/verifier.ts

@@ -1,5 +1,6 @@
 import type { Result } from '@prisma-next/utils/result';
 import { notOk, ok } from '@prisma-next/utils/result';
+import { requireHeadRef } from './aggregate';
 import { extractStorageElementNames } from './extract-storage-element-names';
 import type { ContractMarkerRecordLike } from './marker-types';
 import { projectSchemaToSpace } from './project-schema-to-space';
@@ -145,16 +146,17 @@ function runVerifyAggregate<TSchemaResult>(
       markerPerSpace.set(member.spaceId, { kind: 'absent' });
       continue;
     }
-    if (marker.storageHash !== member.headRef.hash) {
+    const headRef = requireHeadRef(member);
+    if (marker.storageHash !== headRef.hash) {
       markerPerSpace.set(member.spaceId, {
         kind: 'hashMismatch',
         markerHash: marker.storageHash,
-        expected: member.headRef.hash,
+        expected: headRef.hash,
       });
       continue;
     }
     const markerInvariants = new Set(marker.invariants);
-    const missing = member.headRef.invariants.filter((id) => !markerInvariants.has(id));
+    const missing = headRef.invariants.filter((id) => !markerInvariants.has(id));
     if (missing.length > 0) {
       markerPerSpace.set(member.spaceId, {
         kind: 'missingInvariants',
@@ -211,7 +213,7 @@ function detectOrphanElements(
 
   const claimedTables = new Set<string>();
   for (const member of members) {
-    for (const name of extractStorageElementNames(member.contract)) {
+    for (const name of extractStorageElementNames(member.contract())) {
       claimedTables.add(name);
     }
   }

package/src/assert-descriptor-self-consistency.ts

@@ -1,4 +1,6 @@
+import type { PreserveEmptyPredicate, StorageSort } from '@prisma-next/contract/hashing';
 import { computeStorageHash } from '@prisma-next/contract/hashing';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { errorDescriptorHeadHashMismatch } from './errors';
 
 function stripNamespaceKinds(storage: Record<string, unknown>): Record<string, unknown> {
@@ -35,6 +37,8 @@ export interface DescriptorSelfConsistencyInputs {
    */
   readonly storage: unknown;
   readonly headRefHash: string;
+  readonly shouldPreserveEmpty?: PreserveEmptyPredicate;
+  readonly sortStorage?: StorageSort;
 }
 
 /**
@@ -82,6 +86,8 @@ export function assertDescriptorSelfConsistency(inputs: DescriptorSelfConsistenc
     target: inputs.target,
     targetFamily: inputs.targetFamily,
     storage: normalizedStorage,
+    ...ifDefined('shouldPreserveEmpty', inputs.shouldPreserveEmpty),
+    ...ifDefined('sortStorage', inputs.sortStorage),
   });
   if (recomputed !== inputs.headRefHash) {
     throw errorDescriptorHeadHashMismatch({

package/src/compute-extension-space-apply-path.ts

@@ -97,7 +97,7 @@ export async function computeExtensionSpaceApplyPath(
   }
 
   const spaceDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);
-  const packages = await readMigrationsDir(spaceDir);
+  const { packages } = await readMigrationsDir(spaceDir);
   const graph = reconstructGraph(packages);
 
   // Live-marker layer encodes "no prior state" as EMPTY_CONTRACT_HASH;

package/src/emit-contract-space-artefacts.ts

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { canonicalizeJson } from '@prisma-next/framework-components/utils';
 import { join } from 'pathe';
 import type { ContractSpaceHeadRef } from './read-contract-space-head-ref';
-import { assertValidSpaceId } from './space-layout';
+import { assertValidSpaceId, spaceRefsDirectory } from './space-layout';
 
 /**
  * Inputs for {@link emitContractSpaceArtefacts}.
@@ -56,7 +56,8 @@ export async function emitContractSpaceArtefacts(
   assertValidSpaceId(spaceId);
 
   const dir = join(projectMigrationsDir, spaceId);
-  await mkdir(join(dir, 'refs'), { recursive: true });
+  const refsDir = spaceRefsDirectory(dir);
+  await mkdir(refsDir, { recursive: true });
 
   await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(inputs.contract)}\n`);
   await writeFile(join(dir, 'contract.d.ts'), inputs.contractDts);
@@ -66,5 +67,5 @@ export async function emitContractSpaceArtefacts(
     hash: inputs.headRef.hash,
     invariants: sortedInvariants,
   });
-  await writeFile(join(dir, 'refs', 'head.json'), `${headJson}\n`);
+  await writeFile(join(refsDir, 'head.json'), `${headJson}\n`);
 }

package/src/enumerate-migration-spaces.ts

@@ -0,0 +1,127 @@
+import { readMigrationsDir } from './io';
+import type { MigrationListEntry, MigrationSpaceListEntry } from './migration-list-types';
+import { readRefs } from './refs';
+import {
+  APP_SPACE_ID,
+  isValidSpaceId,
+  RESERVED_SPACE_SUBDIR_NAMES,
+  spaceMigrationDirectory,
+  spaceRefsDirectory,
+} from './space-layout';
+import { listContractSpaceDirectories } from './verify-contract-spaces';
+
+/**
+ * Index `migrations/<space>/refs/*.json` by the contract hash each ref
+ * points at, so callers can attach `(ref names)` decorations to every
+ * row whose destination contract hash matches.
+ *
+ * Each bucket is sorted lex-asc to keep rendered output deterministic
+ * (adjacent rows pointing at the same hash render their ref decorations
+ * in the same order).
+ *
+ * Refs whose hash matches no migration on disk are still indexed; the
+ * caller decides whether to surface them. Migration rows only carry
+ * `(refs)` decorations when a matching destination contract hash exists
+ * on disk — orphan refs are not rendered on any row.
+ *
+ * Returns an empty map when the refs directory does not exist
+ * ({@link readRefs} treats `ENOENT` as "no refs").
+ */
+export async function resolveRefsByContractHash(
+  refsDir: string,
+): Promise<ReadonlyMap<string, readonly string[]>> {
+  const refs = await readRefs(refsDir);
+  const byHash = new Map<string, string[]>();
+  for (const [name, entry] of Object.entries(refs)) {
+    const bucket = byHash.get(entry.hash);
+    if (bucket) bucket.push(name);
+    else byHash.set(entry.hash, [name]);
+  }
+  for (const bucket of byHash.values()) {
+    bucket.sort();
+  }
+  return byHash;
+}
+
+/**
+ * Compare two contract-space IDs for the inter-space ordering rule:
+ * {@link APP_SPACE_ID} first if present, then lex-asc on the rest.
+ */
+function compareSpaceIds(a: string, b: string): number {
+  if (a === APP_SPACE_ID) return b === APP_SPACE_ID ? 0 : -1;
+  if (b === APP_SPACE_ID) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Sort `dirName` descending so the rendered output reads latest-first,
+ * matching the `git log` latest-first convention.
+ */
+function compareDirNamesDescending(a: MigrationListEntry, b: MigrationListEntry): number {
+  if (a.dirName < b.dirName) return 1;
+  if (a.dirName > b.dirName) return -1;
+  return 0;
+}
+
+/**
+ * Enumerate every contract space's on-disk migrations under
+ * `<projectMigrationsDir>/`. For each valid space directory:
+ *
+ * - Loads on-disk packages via {@link readMigrationsDir}.
+ * - Attaches ref decorations: each migration's `refs[]` lists every ref
+ *   name from `migrations/<spaceId>/refs/*.json` whose hash equals the
+ *   migration's destination contract hash.
+ * - Sorts migrations within the space by `dirName` descending
+ *   (reverse-filename, latest first).
+ *
+ * Contract spaces are returned with {@link APP_SPACE_ID} first when
+ * present, then the remaining ids lex-asc. A contract-space directory
+ * that contains no migrations becomes `{ spaceId, migrations: [] }` so
+ * the renderer's empty-state path can surface it.
+ *
+ * Directory entries that are not valid {@link isValidSpaceId} names are
+ * skipped (a stray non-space directory under `migrations/` does not
+ * spawn a phantom space entry). Entries whose name appears in
+ * {@link RESERVED_SPACE_SUBDIR_NAMES} are also skipped — the per-space
+ * `refs/` subdirectory name shape would otherwise satisfy
+ * {@link isValidSpaceId} and surface as a phantom contract space.
+ *
+ * Returns `[]` when `<projectMigrationsDir>` does not exist — a fresh
+ * project that has not authored any migration yet.
+ */
+export async function enumerateMigrationSpaces(args: {
+  readonly projectMigrationsDir: string;
+}): Promise<readonly MigrationSpaceListEntry[]> {
+  const { projectMigrationsDir } = args;
+  const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
+  const spaceIds = candidateDirs
+    .filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name))
+    .filter(isValidSpaceId)
+    .sort(compareSpaceIds);
+
+  const spaces: MigrationSpaceListEntry[] = [];
+  for (const spaceId of spaceIds) {
+    const spaceDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);
+    const { packages } = await readMigrationsDir(spaceDir);
+    const refsByHash = await resolveRefsByContractHash(spaceRefsDirectory(spaceDir));
+
+    const migrations: MigrationListEntry[] = packages
+      .map((pkg) => ({
+        dirName: pkg.dirName,
+        from: pkg.metadata.from,
+        to: pkg.metadata.to,
+        migrationHash: pkg.metadata.migrationHash,
+        operationCount: pkg.ops.length,
+        createdAt: pkg.metadata.createdAt,
+        refs: refsByHash.get(pkg.metadata.to) ?? [],
+        providedInvariants: pkg.metadata.providedInvariants,
+      }))
+      .sort(compareDirNamesDescending);
+
+    spaces.push({ spaceId, migrations });
+  }
+
+  return spaces;
+}

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,17 @@ export function errorMigrationHashMismatch(
     details: { dir, storedHash, computedHash },
   });
 }
+
+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,11 +1,15 @@
 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,
@@ -24,11 +28,7 @@ export {
   type GraphWalkStrategyInputs,
   graphWalkStrategy,
 } from '../aggregate/strategies/graph-walk';
-export type {
-  ContractSpaceAggregate,
-  ContractSpaceMember,
-  HydratedMigrationGraph,
-} from '../aggregate/types';
+export type { ContractSpaceAggregate, ContractSpaceMember } from '../aggregate/types';
 export {
   type AggregateVerifierError,
   type AggregateVerifierInput,
@@ -40,3 +40,8 @@ export {
   type SchemaCheckSection,
   verifyAggregate,
 } from '../aggregate/verifier';
+export type {
+  DeclaredExtensionEntry,
+  IntegrityQueryOptions,
+  IntegrityViolation,
+} from '../integrity-violation';

package/src/exports/enumerate-migration-spaces.ts

@@ -0,0 +1,4 @@
+export {
+  enumerateMigrationSpaces,
+  resolveRefsByContractHash,
+} from '../enumerate-migration-spaces';

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/migration-list-graph-topology.ts

@@ -0,0 +1,5 @@
+export type {
+  MigrationEdgeKind,
+  MigrationListGraphTopology,
+} from '../migration-list-graph-topology';
+export { classifyMigrationListGraphTopology } from '../migration-list-graph-topology';

package/src/exports/migration-list-types.ts

@@ -0,0 +1,5 @@
+export type {
+  MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '../migration-list-types';

package/src/exports/refs.ts

@@ -8,3 +8,11 @@ export {
   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);