@prisma-next/migration-tools 0.8.0 → 0.9.0-dev.2

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

@@ -1,4 +1,3 @@
-import type { Contract } from '@prisma-next/contract/types';
 import type { MigrationPlan } from '@prisma-next/framework-components/control';
 import { EMPTY_CONTRACT_HASH } from '../../constants';
 import { findPathWithDecision } from '../../migration-graph';
@@ -26,7 +25,7 @@ export interface GraphWalkStrategyInputs {
   readonly currentMarker: ContractMarkerRecordLike | null;
   /**
    * Optional ref name to decorate the resulting `PathDecision`. Used by
-   * `migration apply` to surface the user-supplied `--ref <name>` in
+   * `migrate` to surface the user-supplied `--to <name>` in
    * structured-progress events and invariant-path error envelopes. The
    * strategy itself does not interpret it.
    */
@@ -109,7 +108,7 @@ export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutc
     result: {
       plan,
       displayOps: pathOps,
-      destinationContract: member.contract as Contract,
+      destinationContract: member.contract,
       strategy: 'graph-walk',
       migrationEdges: edgeRefs,
       pathDecision: outcome.decision,

package/src/aggregate/strategies/synth.ts

@@ -1,4 +1,3 @@
-import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
   ControlFamilyInstance,
@@ -115,7 +114,7 @@ export async function synthStrategy<TFamilyId extends string, TTargetId extends
     result: {
       plan,
       displayOps: synthedPlan.operations,
-      destinationContract: input.member.contract as Contract,
+      destinationContract: input.member.contract,
       strategy: 'synth',
     },
   };

package/src/aggregate/types.ts

@@ -30,7 +30,7 @@ export interface HydratedMigrationGraph {
  * - `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 `validateContract` at the loader boundary.
+ *   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`.

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

@@ -101,7 +101,7 @@ export async function computeExtensionSpaceApplyPath(
   const graph = reconstructGraph(packages);
 
   // Live-marker layer encodes "no prior state" as EMPTY_CONTRACT_HASH;
-  // mirror the `migration apply` flow so a fresh-marker initial walk
+  // mirror the `migrate` flow so a fresh-marker initial walk
   // hits the baseline migration whose `from` is EMPTY_CONTRACT_HASH.
   const fromHash = currentMarkerHash ?? EMPTY_CONTRACT_HASH;
   const required = new Set(

package/src/contract-space-from-json.ts

@@ -29,9 +29,9 @@ import type { MigrationMetadata } from './metadata';
  * canonical emit pipeline".
  *
  * The helper does not introspect or schema-validate the inputs; runtime
- * validation is the responsibility of `validateContract` (codec-aware,
- * called by `family.validateContract` at control-stack construction)
- * and the per-migration `readMigrationPackage` reader used when loading
+ * validation is the responsibility of `family.deserializeContract`
+ * (codec-aware, invoked at control-stack construction) and the
+ * per-migration `readMigrationPackage` reader used when loading
  * from disk. JSON-imported packages flow through the descriptor without
  * a disk read, so the equivalent runtime guarantee comes from the emit
  * pipeline that produced the JSON in the first place.

package/src/errors.ts

@@ -111,27 +111,6 @@ export function errorInvalidOperationEntry(index: number, reason: string): Migra
   );
 }
 
-export function errorStaleContractBookends(args: {
-  readonly side: 'from' | 'to';
-  readonly metaHash: string | null;
-  readonly contractHash: string;
-}): MigrationToolsError {
-  const { side, metaHash, contractHash } = args;
-  // `meta.from` is `string | null` (null = baseline). Render `null` as a
-  // human-readable token in the diagnostic so the message stays clear when
-  // the mismatch is a baseline-vs-non-baseline disagreement.
-  const renderedMetaHash = metaHash === null ? 'null (baseline)' : `"${metaHash}"`;
-  return new MigrationToolsError(
-    'MIGRATION.STALE_CONTRACT_BOOKENDS',
-    'Migration manifest contract bookends disagree with describe()',
-    {
-      why: `migration.json stores ${side}Contract.storage.storageHash "${contractHash}", but describe() returned meta.${side} = ${renderedMetaHash}. The bookend is stale — most likely the migration's describe() was edited after the package was scaffolded by \`migration plan\`.`,
-      fix: 'Re-run `migration plan` to regenerate the package with fresh contract bookends, or restore the directory from version control.',
-      details: { side, metaHash, contractHash },
-    },
-  );
-}
-
 export function errorInvalidSlug(slug: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {
     why: `The slug "${slug}" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,
@@ -220,7 +199,7 @@ export function errorAmbiguousTarget(
     : '';
   return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {
     why: `The migration history has diverged into multiple branches: ${branchTips.join(', ')}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,
-    fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',
+    fix: 'Use `ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',
     details: {
       branchTips,
       ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),

package/src/exports/ref-resolution.ts

@@ -0,0 +1,15 @@
+export { parseContractRef } from '../refs/contract-ref';
+export { parseMigrationRef } from '../refs/migration-ref';
+export type {
+  ContractRef,
+  ContractRefProvenance,
+  MigrationRef,
+  MigrationRefProvenance,
+  RefResolutionAmbiguous,
+  RefResolutionContext,
+  RefResolutionError,
+  RefResolutionInvalidFormat,
+  RefResolutionNotFound,
+  RefResolutionWrongGrammar,
+} from '../refs/types';
+export { findEdgeByDirName } from '../refs/types';

package/src/hash.ts

@@ -15,11 +15,13 @@ function sha256Hex(input: string): string {
 }
 
 /**
- * Content-addressed migration hash over (metadata envelope sans
- * contracts/hints, ops). See ADR 199 — Storage-only migration identity
- * for the rationale: contracts are anchored separately by the
- * storage-hash bookends inside the envelope; planner hints are advisory
- * and must not affect identity.
+ * 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.
  *
  * The integrity check is purely structural, not semantic. The function
  * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
@@ -44,13 +46,7 @@ export function computeMigrationHash(
   metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },
   ops: MigrationOps,
 ): string {
-  const {
-    migrationHash: _migrationHash,
-    fromContract: _fromContract,
-    toContract: _toContract,
-    hints: _hints,
-    ...strippedMeta
-  } = metadata;
+  const { migrationHash: _migrationHash, hints: _hints, ...strippedMeta } = metadata;
 
   const canonicalMetadata = canonicalizeJson(strippedMeta);
   const canonicalOps = canonicalizeJson(ops);

package/src/io.ts

@@ -3,7 +3,6 @@ import type {
   MigrationMetadata,
   MigrationPackage,
 } from '@prisma-next/framework-components/control';
-import { canonicalizeJson } from '@prisma-next/framework-components/utils';
 import { type } from 'arktype';
 import { basename, dirname, join, resolve } from 'pathe';
 import {
@@ -40,8 +39,6 @@ const MigrationMetadataSchema = type({
   from: 'string > 0 | null',
   to: 'string',
   migrationHash: 'string',
-  fromContract: 'object | null',
-  toContract: 'object',
   hints: MigrationHintsSchema,
   labels: 'string[]',
   providedInvariants: 'string[]',
@@ -74,35 +71,31 @@ export async function writeMigrationPackage(
  * Materialise an in-memory {@link MigrationPackage} to a per-space
  * directory on disk.
  *
- * Writes three files under `<targetDir>/<pkg.dirName>/`:
+ * Writes two files under `<targetDir>/<pkg.dirName>/`:
  *
  * - `migration.json` — the manifest (pretty-printed, matches
  *   {@link writeMigrationPackage}'s output for byte-for-byte parity with
  *   app-space migrations).
  * - `ops.json` — the operation list (pretty-printed).
- * - `contract.json` — the canonical-JSON serialisation of
- *   `metadata.toContract`. This is the per-package post-state contract
- *   snapshot; the canonicalisation pass guarantees byte-determinism so
- *   re-emitting the same package across machines / runs produces an
- *   identical file.
  *
  * Distinct verb from the lower-level {@link writeMigrationPackage}
  * (which takes constituent `(metadata, ops)`): callers reading
- * `materialise…` know they are persisting a struct-typed package
- * including its contract-snapshot side car.
+ * `materialise…` know they are persisting a struct-typed package.
  *
  * Overwrite-idempotent: the per-package directory is cleared before
  * each emit, so re-running against the same `targetDir` produces
  * byte-identical contents and never leaves stale files behind. The
- * spec's "re-emitting the same package across runs / machines produces
- * byte-identical files" guarantee (§ 3) covers both same-dir and
- * fresh-dir re-emits. The lower-level {@link writeMigrationPackage}
- * stays strict because the CLI authoring path (`migration plan` /
- * `migration new`) deliberately refuses to clobber an existing
- * authored migration; this helper is the re-emit path that is
- * supposed to converge on a single canonical on-disk shape.
+ * lower-level {@link writeMigrationPackage} stays strict because the
+ * CLI authoring path (`migration plan` / `migration new`) deliberately
+ * refuses to clobber an existing authored migration; this helper is
+ * the re-emit path that is supposed to converge on a single canonical
+ * on-disk shape.
  *
- * @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).
+ * The per-space head contract lives at
+ * `<projectMigrationsDir>/<spaceId>/contract.json` (written by
+ * {@link import('./emit-contract-space-artefacts').emitContractSpaceArtefacts}),
+ * not inside the per-package directory. The runner reads only
+ * `migration.json` + `ops.json` from each package.
  */
 export async function materialiseMigrationPackage(
   targetDir: string,
@@ -111,9 +104,6 @@ export async function materialiseMigrationPackage(
   const dir = join(targetDir, pkg.dirName);
   await rm(dir, { recursive: true, force: true });
   await writeMigrationPackage(dir, pkg.metadata, pkg.ops);
-  await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(pkg.metadata.toContract)}\n`, {
-    flag: 'wx',
-  });
 }
 
 /**

package/src/migration-base.ts

@@ -1,13 +1,12 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import type { Contract } from '@prisma-next/contract/types';
 import type {
   ControlStack,
   MigrationPlan,
   MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
 import { type } from 'arktype';
-import { errorInvalidOperationEntry, errorStaleContractBookends } from './errors';
+import { errorInvalidOperationEntry } from './errors';
 import { computeMigrationHash } from './hash';
 import { deriveProvidedInvariants } from './invariants';
 import type { MigrationHints, MigrationMetadata } from './metadata';
@@ -145,21 +144,12 @@ function buildAttestedMetadata(
   ops: MigrationOps,
   existing: Partial<MigrationMetadata> | null,
 ): MigrationMetadata {
-  assertBookendsMatchMeta(meta, existing);
-
   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(),
-    fromContract: existing?.fromContract ?? null,
-    // When no scaffolded metadata exists we synthesize a minimal contract
-    // stub so the package is still readable end-to-end. The cast is
-    // intentional: only the storage bookend matters for hash computation
-    // (everything else is stripped by `computeMigrationHash`), and a real
-    // contract bookend would only be available after `migration plan`.
-    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),
     hints: normalizeHints(existing?.hints),
   };
 
@@ -167,49 +157,6 @@ function buildAttestedMetadata(
   return { ...baseMetadata, migrationHash };
 }
 
-/**
- * Verify each preserved contract bookend in `existing` agrees with the
- * corresponding side of `describe()`'s output. A mismatch indicates the
- * migration's `describe()` was edited after `migration plan` scaffolded
- * the package, leaving a self-inconsistent manifest. Failing fast at
- * write-time turns a silent foot-gun into an actionable diagnostic.
- *
- * Skipped when a side's `existing.<side>Contract` is null/absent (the
- * synthesis path stays open for origin-less initial migrations and for
- * bare `migration.ts` runs from scratch). When a bookend is *present*
- * but its `storage.storageHash` is missing, that's treated as a
- * mismatch — a malformed bookend is not equivalent to "no bookend".
- *
- * This check is paired with TML-2274, which removes `fromContract` /
- * `toContract` from the manifest entirely; once that lands, this
- * function and its error code are deleted.
- */
-function assertBookendsMatchMeta(
-  meta: MigrationMeta,
-  existing: Partial<MigrationMetadata> | null,
-): void {
-  if (existing?.fromContract != null) {
-    const contractHash = existing.fromContract.storage?.storageHash ?? '';
-    if (contractHash !== meta.from) {
-      throw errorStaleContractBookends({
-        side: 'from',
-        metaHash: meta.from,
-        contractHash,
-      });
-    }
-  }
-  if (existing?.toContract != null) {
-    const contractHash = existing.toContract.storage?.storageHash ?? '';
-    if (contractHash !== meta.to) {
-      throw errorStaleContractBookends({
-        side: 'to',
-        metaHash: meta.to,
-        contractHash,
-      });
-    }
-  }
-}
-
 /**
  * Project `existing.hints` down to the known `MigrationHints` shape, dropping
  * any legacy keys that may linger in metadata scaffolded by older CLI

package/src/read-contract-space-contract.ts

@@ -11,7 +11,7 @@ function hasErrnoCode(error: unknown, code: string): boolean {
  * Read the on-disk contract value for a contract space
  * (`<projectMigrationsDir>/<spaceId>/contract.json`). Returns the parsed
  * JSON value as `unknown` — callers that need a typed contract validate
- * via their family's `validateContract` to surface schema issues.
+ * via their family's `deserializeContract` to surface schema issues.
  *
  * Companion to {@link import('./read-contract-space-head-ref').readContractSpaceHeadRef}
  * — same ENOENT-throws / corrupt-file-error semantics. Returns the

package/src/refs/contract-ref.ts

@@ -0,0 +1,103 @@
+import type { Result } from '@prisma-next/utils/result';
+import { notOk, ok } from '@prisma-next/utils/result';
+import { validateRefName } from '../refs';
+import type {
+  ContractRef,
+  ContractRefProvenance,
+  RefResolutionContext,
+  RefResolutionError,
+} from './types';
+import { findEdgeByDirName, isFullHash, isHexPrefix, normalizeHashPrefix } from './types';
+
+/**
+ * Resolve a user-supplied string to a contract hash using the unified
+ * contract-reference grammar.
+ *
+ * Accepted forms:
+ * - Full storage hash (`sha256:<64 hex>` or `sha256:empty`)
+ * - Hex prefix (6+ hex chars, must uniquely identify one contract)
+ * - Ref name (looked up in the refs index)
+ * - Migration directory name (resolves to the migration's `to`-contract)
+ * - `<dir>^` (resolves to the migration's `from`-contract)
+ */
+export function parseContractRef(
+  input: string,
+  ctx: RefResolutionContext,
+): Result<ContractRef, RefResolutionError> {
+  if (!input) {
+    return notOk({ kind: 'invalid-format', input, reason: 'Reference cannot be empty' });
+  }
+
+  if (isFullHash(input)) {
+    if (ctx.graph.nodes.has(input)) {
+      return ok({ hash: input, provenance: { kind: 'hash', input } });
+    }
+    return notOk({ kind: 'not-found', input, grammar: 'contract' });
+  }
+
+  if (input.endsWith('^')) {
+    const dirName = input.slice(0, -1);
+    if (!dirName) {
+      return notOk({ kind: 'invalid-format', input, reason: 'Missing directory name before ^' });
+    }
+    const edge = findEdgeByDirName(ctx.graph, dirName);
+    if (edge) {
+      return ok({ hash: edge.from, provenance: { kind: 'migration-from', dirName } });
+    }
+    return notOk({ kind: 'not-found', input, grammar: 'contract' });
+  }
+
+  type Candidate = { hash: string; provenance: ContractRefProvenance; label: string };
+  const candidates: Candidate[] = [];
+
+  if (validateRefName(input) && Object.hasOwn(ctx.refs, input)) {
+    const ref = ctx.refs[input];
+    if (ref) {
+      candidates.push({
+        hash: ref.hash,
+        provenance: { kind: 'ref', refName: input },
+        label: `ref "${input}"`,
+      });
+    }
+  }
+
+  const edge = findEdgeByDirName(ctx.graph, input);
+  if (edge) {
+    candidates.push({
+      hash: edge.to,
+      provenance: { kind: 'migration-to', dirName: input },
+      label: `migration directory "${input}"`,
+    });
+  }
+
+  if (isHexPrefix(input)) {
+    const prefix = normalizeHashPrefix(input);
+    const matches = [...ctx.graph.nodes].filter((n) => n.startsWith(prefix));
+    const [firstMatch] = matches;
+    if (matches.length === 1 && firstMatch !== undefined) {
+      candidates.push({
+        hash: firstMatch,
+        provenance: { kind: 'hash', input },
+        label: `hash prefix "${input}"`,
+      });
+    } else if (matches.length > 1) {
+      return notOk({ kind: 'ambiguous', input, candidates: matches, grammar: 'contract' });
+    }
+  }
+
+  const [firstCandidate] = candidates;
+  if (candidates.length === 1 && firstCandidate !== undefined) {
+    return ok({ hash: firstCandidate.hash, provenance: firstCandidate.provenance });
+  }
+
+  if (candidates.length > 1) {
+    return notOk({
+      kind: 'ambiguous',
+      input,
+      candidates: candidates.map((c) => c.label),
+      grammar: 'contract',
+    });
+  }
+
+  return notOk({ kind: 'not-found', input, grammar: 'contract' });
+}

package/src/refs/migration-ref.ts

@@ -0,0 +1,121 @@
+import type { Result } from '@prisma-next/utils/result';
+import { notOk, ok } from '@prisma-next/utils/result';
+import { validateRefName } from '../refs';
+import type { MigrationRef, RefResolutionContext, RefResolutionError } from './types';
+import { findEdgeByDirName, isFullHash, isHexPrefix, normalizeHashPrefix } from './types';
+
+/**
+ * Resolve a user-supplied string to a migration using the migration-reference
+ * grammar.
+ *
+ * Accepted forms:
+ * - Migration directory name (e.g. `20260101-add-users`)
+ * - Migration hash (full or 6+ hex prefix)
+ *
+ * Wrong-grammar diagnostics are produced when the input matches a
+ * contract-grammar form (ref name, `<dir>^`, contract-only hash) so the
+ * user gets a targeted hint rather than a generic "not found".
+ */
+export function parseMigrationRef(
+  input: string,
+  ctx: RefResolutionContext,
+): Result<MigrationRef, RefResolutionError> {
+  if (!input) {
+    return notOk({ kind: 'invalid-format', input, reason: 'Reference cannot be empty' });
+  }
+
+  if (input.endsWith('^')) {
+    return notOk({
+      kind: 'wrong-grammar',
+      input,
+      expectedGrammar: 'migration',
+      message: '`^` syntax addresses contracts, not migrations',
+      fix: 'Pass the migration directory name without `^`, or use a contract-accepting flag like `--to` or `--from`.',
+    });
+  }
+
+  if (validateRefName(input) && Object.hasOwn(ctx.refs, input)) {
+    return notOk({
+      kind: 'wrong-grammar',
+      input,
+      expectedGrammar: 'migration',
+      message: `"${input}" is a ref name, not a migration`,
+      fix: 'Refs point at contracts, not migrations. Use a migration directory name or migration hash.',
+    });
+  }
+
+  const edge = findEdgeByDirName(ctx.graph, input);
+  if (edge) {
+    return ok({
+      dirName: edge.dirName,
+      migrationHash: edge.migrationHash,
+      from: edge.from,
+      to: edge.to,
+      provenance: { kind: 'dir-name', dirName: input },
+    });
+  }
+
+  if (isFullHash(input)) {
+    const migEdge = ctx.graph.migrationByHash.get(input);
+    if (migEdge) {
+      return ok({
+        dirName: migEdge.dirName,
+        migrationHash: migEdge.migrationHash,
+        from: migEdge.from,
+        to: migEdge.to,
+        provenance: { kind: 'hash', input },
+      });
+    }
+    if (ctx.graph.nodes.has(input)) {
+      return notOk({
+        kind: 'wrong-grammar',
+        input,
+        expectedGrammar: 'migration',
+        message: 'Hash matched a contract but not a migration',
+        fix: 'Use a contract-accepting flag like `--to` or `--from` to reference contracts by hash. Pass `migration show <dir>` for a specific migration.',
+      });
+    }
+    return notOk({ kind: 'not-found', input, grammar: 'migration' });
+  }
+
+  if (isHexPrefix(input)) {
+    const prefix = normalizeHashPrefix(input);
+    const migMatches = [...ctx.graph.migrationByHash.entries()].filter(([hash]) =>
+      hash.startsWith(prefix),
+    );
+
+    const [firstMigMatch] = migMatches;
+    if (migMatches.length === 1 && firstMigMatch !== undefined) {
+      const [, matchedEdge] = firstMigMatch;
+      return ok({
+        dirName: matchedEdge.dirName,
+        migrationHash: matchedEdge.migrationHash,
+        from: matchedEdge.from,
+        to: matchedEdge.to,
+        provenance: { kind: 'hash', input },
+      });
+    }
+
+    if (migMatches.length > 1) {
+      return notOk({
+        kind: 'ambiguous',
+        input,
+        candidates: migMatches.map(([hash]) => hash),
+        grammar: 'migration',
+      });
+    }
+
+    const contractMatches = [...ctx.graph.nodes].filter((n) => n.startsWith(prefix));
+    if (contractMatches.length > 0) {
+      return notOk({
+        kind: 'wrong-grammar',
+        input,
+        expectedGrammar: 'migration',
+        message: 'Hash matched a contract but not a migration',
+        fix: 'Use a contract-accepting flag like `--to` or `--from` to reference contracts by hash. Pass `migration show <dir>` for a specific migration.',
+      });
+    }
+  }
+
+  return notOk({ kind: 'not-found', input, grammar: 'migration' });
+}

package/src/refs/types.ts

@@ -0,0 +1,93 @@
+import type { MigrationEdge, MigrationGraph } from '../graph';
+import type { Refs } from '../refs';
+
+/** Context required to resolve a contract or migration reference. */
+export interface RefResolutionContext {
+  readonly graph: MigrationGraph;
+  readonly refs: Refs;
+}
+
+export type ContractRefProvenance =
+  | { readonly kind: 'hash'; readonly input: string }
+  | { readonly kind: 'ref'; readonly refName: string }
+  | { readonly kind: 'migration-to'; readonly dirName: string }
+  | { readonly kind: 'migration-from'; readonly dirName: string };
+
+/** A resolved contract reference: the target hash and how it was derived. */
+export interface ContractRef {
+  readonly hash: string;
+  readonly provenance: ContractRefProvenance;
+}
+
+export type MigrationRefProvenance =
+  | { readonly kind: 'dir-name'; readonly dirName: string }
+  | { readonly kind: 'hash'; readonly input: string };
+
+/** A resolved migration reference. */
+export interface MigrationRef {
+  readonly dirName: string;
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly provenance: MigrationRefProvenance;
+}
+
+export interface RefResolutionNotFound {
+  readonly kind: 'not-found';
+  readonly input: string;
+  readonly grammar: 'contract' | 'migration';
+}
+
+export interface RefResolutionAmbiguous {
+  readonly kind: 'ambiguous';
+  readonly input: string;
+  readonly candidates: readonly string[];
+  readonly grammar: 'contract' | 'migration';
+}
+
+export interface RefResolutionWrongGrammar {
+  readonly kind: 'wrong-grammar';
+  readonly input: string;
+  readonly expectedGrammar: 'contract' | 'migration';
+  readonly message: string;
+  readonly fix: string;
+}
+
+export interface RefResolutionInvalidFormat {
+  readonly kind: 'invalid-format';
+  readonly input: string;
+  readonly reason: string;
+}
+
+export type RefResolutionError =
+  | RefResolutionNotFound
+  | RefResolutionAmbiguous
+  | RefResolutionWrongGrammar
+  | RefResolutionInvalidFormat;
+
+const FULL_HASH_PATTERN = /^sha256:([0-9a-f]{64}|empty)$/;
+const HEX_PREFIX_PATTERN = /^(sha256:)?[0-9a-f]{6,}$/;
+
+export function isFullHash(input: string): boolean {
+  return FULL_HASH_PATTERN.test(input);
+}
+
+export function isHexPrefix(input: string): boolean {
+  return HEX_PREFIX_PATTERN.test(input);
+}
+
+export function normalizeHashPrefix(input: string): string {
+  return input.startsWith('sha256:') ? input : `sha256:${input}`;
+}
+
+export function findEdgeByDirName(
+  graph: MigrationGraph,
+  dirName: string,
+): MigrationEdge | undefined {
+  for (const edges of graph.forwardChain.values()) {
+    for (const edge of edges) {
+      if (edge.dirName === dirName) return edge;
+    }
+  }
+  return undefined;
+}