@prisma-next/migration-tools 0.11.0-dev.6 → 0.11.0-dev.61

package/src/aggregate/strategies/graph-walk.ts

@@ -1,7 +1,8 @@
 import type { MigrationPlan } from '@prisma-next/framework-components/control';
 import { EMPTY_CONTRACT_HASH } from '../../constants';
 import { findPathWithDecision } from '../../migration-graph';
-import type { MigrationOps } from '../../package';
+import type { MigrationOps, OnDiskMigrationPackage } from '../../package';
+import { requireHeadRef } from '../aggregate';
 import type { ContractMarkerRecordLike } from '../marker-types';
 import type { AggregatePerSpacePlan } from '../planner-types';
 import type { ContractSpaceMember } from '../types';
@@ -9,7 +10,7 @@ import type { ContractSpaceMember } from '../types';
 /**
  * Outcome variants for the graph-walk strategy. Mirrors
  * {@link import('../../compute-extension-space-apply-path').ExtensionSpaceApplyPathOutcome}
- * but operates against the **already-hydrated** `member.migrations.graph`
+ * but operates against the member's lazily-reconstructed `graph()`
  * instead of re-reading from disk. The aggregate planner converts
  * these into {@link import('../planner-types').AggregatePlannerError}
  * variants.
@@ -49,13 +50,17 @@ export interface GraphWalkStrategyInputs {
  */
 export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutcome {
   const { aggregateTargetId, member, currentMarker, refName } = input;
-  const { graph, packagesByMigrationHash } = member.migrations;
+  const headRef = requireHeadRef(member);
+  const graph = member.graph();
+  const packagesByMigrationHash = new Map<string, OnDiskMigrationPackage>(
+    member.packages.map((pkg) => [pkg.metadata.migrationHash, pkg]),
+  );
 
   const fromHash = currentMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
   const markerInvariants = new Set(currentMarker?.invariants ?? []);
-  const required = new Set(member.headRef.invariants.filter((id) => !markerInvariants.has(id)));
+  const required = new Set(headRef.invariants.filter((id) => !markerInvariants.has(id)));
 
-  const outcome = findPathWithDecision(graph, fromHash, member.headRef.hash, {
+  const outcome = findPathWithDecision(graph, fromHash, headRef.hash, {
     required,
     ...(refName !== undefined ? { refName } : {}),
   });
@@ -98,7 +103,7 @@ export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutc
     targetId: aggregateTargetId,
     spaceId: member.spaceId,
     origin: currentMarker === null ? null : { storageHash: currentMarker.storageHash },
-    destination: { storageHash: member.headRef.hash },
+    destination: { storageHash: headRef.hash },
     operations: pathOps,
     providedInvariants: [...providedInvariantsSet].sort(),
   };
@@ -108,7 +113,7 @@ export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutc
     result: {
       plan,
       displayOps: pathOps,
-      destinationContract: member.contract,
+      destinationContract: member.contract(),
       strategy: 'graph-walk',
       migrationEdges: edgeRefs,
       pathDecision: outcome.decision,

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,108 @@
 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';
+import type { Refs } from '../refs';
+import type { ContractSpaceHeadRecord } from '../verify-contract-spaces';
 
-/**
- * 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>;
+export interface ContractAtOptions {
+  readonly refName?: string;
 }
 
+export type ContractAtResult =
+  | {
+      readonly provenance: 'snapshot';
+      readonly hash: string;
+      readonly contractJson: unknown;
+      readonly contractDts: string;
+      readonly contract: Contract;
+    }
+  | {
+      readonly provenance: 'graph-node';
+      readonly sourceDir: string;
+      readonly hash: string;
+      readonly contractJson: unknown;
+      readonly contractDts: string;
+      readonly contract: Contract;
+    };
+
 /**
  * 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.
+ * - `contractAt(hash, opts?)`: materializes the contract at an arbitrary
+ *   graph node — when `opts.refName` is set, prefer the ref's paired
+ *   snapshot; else find the package whose `metadata.to === hash` and read
+ *   its `end-contract.*`. Lazy per `(hash, refName?)` memoisation; throws
+ *   typed {@link MigrationToolsError} values compatible with CLI mappers.
  */
 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;
+  contractAt(hash: string, opts?: ContractAtOptions): Promise<ContractAtResult>;
 }
 
 /**
- * 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,6 +1,7 @@
+import { elementCoordinates } from '@prisma-next/framework-components/ir';
 import type { Result } from '@prisma-next/utils/result';
 import { notOk, ok } from '@prisma-next/utils/result';
-import { extractStorageElementNames } from './extract-storage-element-names';
+import { requireHeadRef } from './aggregate';
 import type { ContractMarkerRecordLike } from './marker-types';
 import { projectSchemaToSpace } from './project-schema-to-space';
 import type { ContractSpaceAggregate, ContractSpaceMember } from './types';
@@ -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,8 +213,9 @@ function detectOrphanElements(
 
   const claimedTables = new Set<string>();
   for (const member of members) {
-    for (const name of extractStorageElementNames(member.contract)) {
-      claimedTables.add(name);
+    const contract = member.contract();
+    for (const { entityName } of elementCoordinates(contract.storage)) {
+      claimedTables.add(entityName);
     }
   }
 

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/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,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,
@@ -25,9 +29,10 @@ export {
   graphWalkStrategy,
 } from '../aggregate/strategies/graph-walk';
 export type {
+  ContractAtOptions,
+  ContractAtResult,
   ContractSpaceAggregate,
   ContractSpaceMember,
-  HydratedMigrationGraph,
 } from '../aggregate/types';
 export {
   type AggregateVerifierError,
@@ -40,3 +45,8 @@ export {
   type SchemaCheckSection,
   verifyAggregate,
 } 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);