@prisma-next/migration-tools 0.8.0-dev.1 → 0.8.0-dev.10

package/dist/exports/io.mjs

@@ -1,2 +1,2 @@
-import { a as materialiseMigrationPackage, c as writeMigrationMetadata, i as materialiseExtensionMigrationPackageIfMissing, l as writeMigrationOps, n as copyFilesWithRename, o as readMigrationPackage, r as formatMigrationDirName, s as readMigrationsDir, u as writeMigrationPackage } from "../io-Dw620b51.mjs";
+import { a as materialiseMigrationPackage, c as writeMigrationMetadata, i as materialiseExtensionMigrationPackageIfMissing, l as writeMigrationOps, n as copyFilesWithRename, o as readMigrationPackage, r as formatMigrationDirName, s as readMigrationsDir, u as writeMigrationPackage } from "../io-BPLfzvZe.mjs";
 export { copyFilesWithRename, formatMigrationDirName, materialiseExtensionMigrationPackageIfMissing, materialiseMigrationPackage, readMigrationPackage, readMigrationsDir, writeMigrationMetadata, writeMigrationOps, writeMigrationPackage };

package/dist/exports/metadata.d.mts

@@ -1,2 +1,2 @@
-import { n as MigrationMetadata, t as MigrationHints } from "../metadata-CFvm3ayn.mjs";
+import { n as MigrationMetadata, t as MigrationHints } from "../metadata-BFX0xdz8.mjs";
 export { type MigrationHints, type MigrationMetadata };

package/dist/exports/migration-graph.d.mts

@@ -1,2 +1,2 @@
-import { a as findLeaf, c as findPathWithInvariants, i as findLatestMigration, l as findReachableLeaves, n as detectCycles, o as findPath, r as detectOrphans, s as findPathWithDecision, t as PathDecision, u as reconstructGraph } from "../migration-graph-DulOITvG.mjs";
+import { a as findLeaf, c as findPathWithInvariants, i as findLatestMigration, l as findReachableLeaves, n as detectCycles, o as findPath, r as detectOrphans, s as findPathWithDecision, t as PathDecision, u as reconstructGraph } from "../migration-graph-De0dUZoC.mjs";
 export { type PathDecision, detectCycles, detectOrphans, findLatestMigration, findLeaf, findPath, findPathWithDecision, findPathWithInvariants, findReachableLeaves, reconstructGraph };

package/dist/exports/migration-graph.mjs

@@ -1,2 +1,2 @@
-import { a as findPath, c as findReachableLeaves, i as findLeaf, l as reconstructGraph, n as detectOrphans, o as findPathWithDecision, r as findLatestMigration, s as findPathWithInvariants, t as detectCycles } from "../migration-graph-DGNnKDY5.mjs";
+import { a as findPath, c as findReachableLeaves, i as findLeaf, l as reconstructGraph, n as detectOrphans, o as findPathWithDecision, r as findLatestMigration, s as findPathWithInvariants, t as detectCycles } from "../migration-graph-nlS4TRpn.mjs";
 export { detectCycles, detectOrphans, findLatestMigration, findLeaf, findPath, findPathWithDecision, findPathWithInvariants, findReachableLeaves, reconstructGraph };

package/dist/exports/migration.d.mts

@@ -1,4 +1,4 @@
-import { n as MigrationMetadata$1 } from "../metadata-CFvm3ayn.mjs";
+import { n as MigrationMetadata$1 } from "../metadata-BFX0xdz8.mjs";
 import { ControlStack, MigrationPlan, MigrationPlanOperation } from "@prisma-next/framework-components/control";
 
 //#region src/migration-base.d.ts

package/dist/exports/migration.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"mappings":";;;;UAgBiB,aAAA;EAAA,SACN,IAAA;EAAA,SACA,EAAA;EAAA,SACA,MAAA;AAAA;;;;;;;AAuBX;;;uBAAsB,SAAA,oBACD,sBAAA,GAAyB,sBAAA,mFAGjC,aAAA;EAAA,kBAEO,QAAA;EAWqB;;;;;;;;;EAAA,mBAApB,KAAA,EAAO,YAAA,CAAa,SAAA,EAAW,SAAA;cAEtC,KAAA,GAAQ,YAAA,CAAa,SAAA,EAAW,SAAA;EAlB5C;;;;;;EAAA,aA4Ba,UAAA,CAAA,YAAuB,UAAA;EAZjB;;;;;EAAA,SAmBV,QAAA,CAAA,GAAY,aAAA;EAAA,IAEjB,MAAA,CAAA;IAAA,SAAqB,WAAA;EAAA;EAAA,IAKrB,WAAA,CAAA;IAAA,SAA0B,WAAA;EAAA;AAAA;;;;;;;AAYhC;iBAAgB,kBAAA,CAAmB,aAAA;;;;AAsBnC;;;;;;;;UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,QAAA,EAAU,mBAAA;EAAA,SACV,YAAA;AAAA;;;;;;;;;;iBAkHK,uBAAA,CACd,QAAA,EAAU,SAAA,EACV,QAAA,EAAU,OAAA,CAAQ,mBAAA,WACjB,kBAAA"}
+{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"mappings":";;;;UAeiB,aAAA;EAAA,SACN,IAAA;EAAA,SACA,EAAA;EAAA,SACA,MAAA;AAAA;;;;;;;AAuBX;;;uBAAsB,SAAA,oBACD,sBAAA,GAAyB,sBAAA,mFAGjC,aAAA;EAAA,kBAEO,QAAA;EAWqB;;;;;;;;;EAAA,mBAApB,KAAA,EAAO,YAAA,CAAa,SAAA,EAAW,SAAA;cAEtC,KAAA,GAAQ,YAAA,CAAa,SAAA,EAAW,SAAA;EAlB5C;;;;;;EAAA,aA4Ba,UAAA,CAAA,YAAuB,UAAA;EAZjB;;;;;EAAA,SAmBV,QAAA,CAAA,GAAY,aAAA;EAAA,IAEjB,MAAA,CAAA;IAAA,SAAqB,WAAA;EAAA;EAAA,IAKrB,WAAA,CAAA;IAAA,SAA0B,WAAA;EAAA;AAAA;;;;;;;AAYhC;iBAAgB,kBAAA,CAAmB,aAAA;;;;AAsBnC;;;;;;;;UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,QAAA,EAAU,mBAAA;EAAA,SACV,YAAA;AAAA;;;;;;;;;;iBA8DK,uBAAA,CACd,QAAA,EAAU,SAAA,EACV,QAAA,EAAU,OAAA,CAAQ,mBAAA,WACjB,kBAAA"}

package/dist/exports/migration.mjs

@@ -1,6 +1,6 @@
-import { T as errorStaleContractBookends, f as errorInvalidOperationEntry } from "../errors-EPL_9p9f.mjs";
-import { t as computeMigrationHash } from "../hash-C6bpZczT.mjs";
-import { t as deriveProvidedInvariants } from "../invariants-qgQGlsrV.mjs";
+import { f as errorInvalidOperationEntry } from "../errors-DGYwcwXs.mjs";
+import { t as computeMigrationHash } from "../hash-Cr4WIr4Z.mjs";
+import { t as deriveProvidedInvariants } from "../invariants-0daYEzyo.mjs";
 import { t as MigrationOpSchema } from "../op-schema-D5qkXfEf.mjs";
 import { type } from "arktype";
 import { realpathSync } from "node:fs";
@@ -77,15 +77,12 @@ function isDirectEntrypoint(importMetaUrl) {
 * the on-disk artifacts are always fully attested.
 */
 function buildAttestedMetadata(meta, ops, existing) {
-	assertBookendsMatchMeta(meta, existing);
 	const baseMetadata = {
 		from: meta.from,
 		to: meta.to,
 		labels: meta.labels ?? existing?.labels ?? [],
 		providedInvariants: deriveProvidedInvariants(ops),
 		createdAt: existing?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-		fromContract: existing?.fromContract ?? null,
-		toContract: existing?.toContract ?? { storage: { storageHash: meta.to } },
 		hints: normalizeHints(existing?.hints)
 	};
 	const migrationHash = computeMigrationHash(baseMetadata, ops);
@@ -95,41 +92,6 @@ function buildAttestedMetadata(meta, ops, existing) {
 	};
 }
 /**
-* 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, existing) {
-	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
 * versions (e.g. `planningStrategy`). Picking fields explicitly instead of

package/dist/exports/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { realpathSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type {\n  ControlStack,\n  MigrationPlan,\n  MigrationPlanOperation,\n} from '@prisma-next/framework-components/control';\nimport { type } from 'arktype';\nimport { errorInvalidOperationEntry, errorStaleContractBookends } from './errors';\nimport { computeMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport type { MigrationHints, MigrationMetadata } from './metadata';\nimport { MigrationOpSchema } from './op-schema';\nimport type { MigrationOps } from './package';\n\nexport interface MigrationMeta {\n  readonly from: string | null;\n  readonly to: string;\n  readonly labels?: readonly string[];\n}\n\n// `from` rejects empty strings to mirror `MigrationMetadataSchema` in\n// `./io.ts`. Without this match, an authored migration could `describe()` with\n// `from: ''` and pass `buildMigrationArtifacts`'s validation, only to have\n// `readMigrationPackage` reject the resulting `migration.json` later — the\n// two validators must agree on the legal value space.\nconst MigrationMetaSchema = type({\n  from: 'string > 0 | null',\n  to: 'string',\n  'labels?': type('string').array(),\n});\n\n/**\n * Base class for migrations.\n *\n * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the\n * runner can consume it directly via `targetId`, `operations`, `origin`, and\n * `destination`. The metadata-shaped inputs come from `describe()`, which\n * every migration must implement — `migration.json` is required for a\n * migration to be valid.\n */\nexport abstract class Migration<\n  TOperation extends MigrationPlanOperation = MigrationPlanOperation,\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> implements MigrationPlan\n{\n  abstract readonly targetId: string;\n\n  /**\n   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).\n   *\n   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their\n   * adapter once per instance. Optional at the abstract level so unit tests can\n   * construct `Migration` instances purely for `operations` / `describe`\n   * assertions without needing a real stack; concrete subclasses that need the\n   * stack at runtime should narrow the parameter to required.\n   */\n  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;\n\n  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {\n    this.stack = stack;\n  }\n\n  /**\n   * Ordered list of operations this migration performs.\n   *\n   * Implemented as a getter so that subclasses can either precompute the list\n   * in their constructor or build it lazily per access.\n   */\n  abstract get operations(): readonly TOperation[];\n\n  /**\n   * Metadata inputs used to build `migration.json` and to derive the plan's\n   * origin/destination identities. Every migration must provide this —\n   * omitting it would produce an invalid on-disk migration package.\n   */\n  abstract describe(): MigrationMeta;\n\n  get origin(): { readonly storageHash: string } | null {\n    const from = this.describe().from;\n    return from === null ? null : { storageHash: from };\n  }\n\n  get destination(): { readonly storageHash: string } {\n    return { storageHash: this.describe().to };\n  }\n}\n\n/**\n * Returns true when `import.meta.url` resolves to the same file that was\n * invoked as the node entrypoint (`process.argv[1]`). Used by\n * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when\n * the migration module is being imported (e.g. by another script) rather\n * than executed directly.\n */\nexport function isDirectEntrypoint(importMetaUrl: string): boolean {\n  const metaFilename = fileURLToPath(importMetaUrl);\n  const argv1 = process.argv[1];\n  if (!argv1) return false;\n  try {\n    return realpathSync(metaFilename) === realpathSync(argv1);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * In-memory artifacts produced from a `Migration` instance: the\n * serialized `ops.json` body, the `migration.json` metadata object, and\n * its serialized form. Returned by `buildMigrationArtifacts` so callers\n * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can\n * decide how to persist them — write to disk, print in dry-run, ship\n * over the wire — without coupling artifact construction to file I/O.\n *\n * `metadataJson` is `JSON.stringify(metadata, null, 2)` — the canonical\n * on-disk shape that the arktype loader-schema in `./io` validates.\n */\nexport interface MigrationArtifacts {\n  readonly opsJson: string;\n  readonly metadata: MigrationMetadata;\n  readonly metadataJson: string;\n}\n\n/**\n * Build the attested metadata from `describe()`-derived metadata, the\n * operations list, and the previously-scaffolded metadata (if any).\n *\n * When a `migration.json` already exists for this package (the common\n * case: it was scaffolded by `migration plan`), preserve the contract\n * bookends, hints, labels, and `createdAt` set there — those fields are\n * owned by the CLI scaffolder, not the authored class. Only the\n * `describe()`-derived fields (`from`, `to`) and the operations\n * change as the author iterates. When no metadata exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant record so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationHash` is recomputed against the current metadata + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedMetadata(\n  meta: MigrationMeta,\n  ops: MigrationOps,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationMetadata {\n  assertBookendsMatchMeta(meta, existing);\n\n  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {\n    from: meta.from,\n    to: meta.to,\n    labels: meta.labels ?? existing?.labels ?? [],\n    providedInvariants: deriveProvidedInvariants(ops),\n    createdAt: existing?.createdAt ?? new Date().toISOString(),\n    fromContract: existing?.fromContract ?? null,\n    // When no scaffolded metadata exists we synthesize a minimal contract\n    // stub so the package is still readable end-to-end. The cast is\n    // intentional: only the storage bookend matters for hash computation\n    // (everything else is stripped by `computeMigrationHash`), and a real\n    // contract bookend would only be available after `migration plan`.\n    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),\n    hints: normalizeHints(existing?.hints),\n  };\n\n  const migrationHash = computeMigrationHash(baseMetadata, ops);\n  return { ...baseMetadata, migrationHash };\n}\n\n/**\n * Verify each preserved contract bookend in `existing` agrees with the\n * corresponding side of `describe()`'s output. A mismatch indicates the\n * migration's `describe()` was edited after `migration plan` scaffolded\n * the package, leaving a self-inconsistent manifest. Failing fast at\n * write-time turns a silent foot-gun into an actionable diagnostic.\n *\n * Skipped when a side's `existing.<side>Contract` is null/absent (the\n * synthesis path stays open for origin-less initial migrations and for\n * bare `migration.ts` runs from scratch). When a bookend is *present*\n * but its `storage.storageHash` is missing, that's treated as a\n * mismatch — a malformed bookend is not equivalent to \"no bookend\".\n *\n * This check is paired with TML-2274, which removes `fromContract` /\n * `toContract` from the manifest entirely; once that lands, this\n * function and its error code are deleted.\n */\nfunction assertBookendsMatchMeta(\n  meta: MigrationMeta,\n  existing: Partial<MigrationMetadata> | null,\n): void {\n  if (existing?.fromContract != null) {\n    const contractHash = existing.fromContract.storage?.storageHash ?? '';\n    if (contractHash !== meta.from) {\n      throw errorStaleContractBookends({\n        side: 'from',\n        metaHash: meta.from,\n        contractHash,\n      });\n    }\n  }\n  if (existing?.toContract != null) {\n    const contractHash = existing.toContract.storage?.storageHash ?? '';\n    if (contractHash !== meta.to) {\n      throw errorStaleContractBookends({\n        side: 'to',\n        metaHash: meta.to,\n        contractHash,\n      });\n    }\n  }\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in metadata scaffolded by older CLI\n * versions (e.g. `planningStrategy`). Picking fields explicitly instead of\n * spreading keeps refreshed `migration.json` files schema-clean regardless\n * of what was on disk before.\n */\nfunction normalizeHints(existing: MigrationHints | undefined): MigrationHints {\n  return {\n    used: existing?.used ?? [],\n    applied: existing?.applied ?? [],\n    plannerVersion: existing?.plannerVersion ?? '2.0.0',\n  };\n}\n\n/**\n * Pure conversion from a `Migration` instance (plus the previously\n * scaffolded metadata, when one exists on disk) to the in-memory\n * artifacts that downstream tooling persists. Owns metadata validation,\n * metadata synthesis/preservation, hint normalization, and the\n * content-addressed `migrationHash` computation, but performs no file I/O\n * — callers handle reads (to source `existing`) and writes (to persist\n * `opsJson` / `metadataJson`).\n */\nexport function buildMigrationArtifacts(\n  instance: Migration,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationArtifacts {\n  const ops = instance.operations;\n  if (!Array.isArray(ops)) {\n    throw new Error('operations must be an array');\n  }\n\n  for (let index = 0; index < ops.length; index++) {\n    const result = MigrationOpSchema(ops[index]);\n    if (result instanceof type.errors) {\n      throw errorInvalidOperationEntry(index, result.summary);\n    }\n  }\n\n  const rawMeta: unknown = instance.describe();\n  const parsed = MigrationMetaSchema(rawMeta);\n  if (parsed instanceof type.errors) {\n    throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n  }\n\n  const metadata = buildAttestedMetadata(parsed, ops, existing);\n\n  return {\n    opsJson: JSON.stringify(ops, null, 2),\n    metadata,\n    metadataJson: JSON.stringify(metadata, null, 2),\n  };\n}\n"],"mappings":";;;;;;;;AA2BA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,WAAW,KAAK,SAAS,CAAC,OAAO;CAClC,CAAC;;;;;;;;;;AAWF,IAAsB,YAAtB,MAKA;;;;;;;;;;CAYE;CAEA,YAAY,OAA4C;EACtD,KAAK,QAAQ;;CAkBf,IAAI,SAAkD;EACpD,MAAM,OAAO,KAAK,UAAU,CAAC;EAC7B,OAAO,SAAS,OAAO,OAAO,EAAE,aAAa,MAAM;;CAGrD,IAAI,cAAgD;EAClD,OAAO,EAAE,aAAa,KAAK,UAAU,CAAC,IAAI;;;;;;;;;;AAW9C,SAAgB,mBAAmB,eAAgC;CACjE,MAAM,eAAe,cAAc,cAAc;CACjD,MAAM,QAAQ,QAAQ,KAAK;CAC3B,IAAI,CAAC,OAAO,OAAO;CACnB,IAAI;EACF,OAAO,aAAa,aAAa,KAAK,aAAa,MAAM;SACnD;EACN,OAAO;;;;;;;;;;;;;;;;;;;;AAsCX,SAAS,sBACP,MACA,KACA,UACmB;CACnB,wBAAwB,MAAM,SAAS;CAEvC,MAAM,eAAyD;EAC7D,MAAM,KAAK;EACX,IAAI,KAAK;EACT,QAAQ,KAAK,UAAU,UAAU,UAAU,EAAE;EAC7C,oBAAoB,yBAAyB,IAAI;EACjD,WAAW,UAAU,8BAAa,IAAI,MAAM,EAAC,aAAa;EAC1D,cAAc,UAAU,gBAAgB;EAMxC,YAAY,UAAU,cAAe,EAAE,SAAS,EAAE,aAAa,KAAK,IAAI,EAAE;EAC1E,OAAO,eAAe,UAAU,MAAM;EACvC;CAED,MAAM,gBAAgB,qBAAqB,cAAc,IAAI;CAC7D,OAAO;EAAE,GAAG;EAAc;EAAe;;;;;;;;;;;;;;;;;;;AAoB3C,SAAS,wBACP,MACA,UACM;CACN,IAAI,UAAU,gBAAgB,MAAM;EAClC,MAAM,eAAe,SAAS,aAAa,SAAS,eAAe;EACnE,IAAI,iBAAiB,KAAK,MACxB,MAAM,2BAA2B;GAC/B,MAAM;GACN,UAAU,KAAK;GACf;GACD,CAAC;;CAGN,IAAI,UAAU,cAAc,MAAM;EAChC,MAAM,eAAe,SAAS,WAAW,SAAS,eAAe;EACjE,IAAI,iBAAiB,KAAK,IACxB,MAAM,2BAA2B;GAC/B,MAAM;GACN,UAAU,KAAK;GACf;GACD,CAAC;;;;;;;;;;AAYR,SAAS,eAAe,UAAsD;CAC5E,OAAO;EACL,MAAM,UAAU,QAAQ,EAAE;EAC1B,SAAS,UAAU,WAAW,EAAE;EAChC,gBAAgB,UAAU,kBAAkB;EAC7C;;;;;;;;;;;AAYH,SAAgB,wBACd,UACA,UACoB;CACpB,MAAM,MAAM,SAAS;CACrB,IAAI,CAAC,MAAM,QAAQ,IAAI,EACrB,MAAM,IAAI,MAAM,8BAA8B;CAGhD,KAAK,IAAI,QAAQ,GAAG,QAAQ,IAAI,QAAQ,SAAS;EAC/C,MAAM,SAAS,kBAAkB,IAAI,OAAO;EAC5C,IAAI,kBAAkB,KAAK,QACzB,MAAM,2BAA2B,OAAO,OAAO,QAAQ;;CAK3D,MAAM,SAAS,oBADU,SAAS,UACQ,CAAC;CAC3C,IAAI,kBAAkB,KAAK,QACzB,MAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;CAG5E,MAAM,WAAW,sBAAsB,QAAQ,KAAK,SAAS;CAE7D,OAAO;EACL,SAAS,KAAK,UAAU,KAAK,MAAM,EAAE;EACrC;EACA,cAAc,KAAK,UAAU,UAAU,MAAM,EAAE;EAChD"}
+{"version":3,"file":"migration.mjs","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { realpathSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport type {\n  ControlStack,\n  MigrationPlan,\n  MigrationPlanOperation,\n} from '@prisma-next/framework-components/control';\nimport { type } from 'arktype';\nimport { errorInvalidOperationEntry } from './errors';\nimport { computeMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport type { MigrationHints, MigrationMetadata } from './metadata';\nimport { MigrationOpSchema } from './op-schema';\nimport type { MigrationOps } from './package';\n\nexport interface MigrationMeta {\n  readonly from: string | null;\n  readonly to: string;\n  readonly labels?: readonly string[];\n}\n\n// `from` rejects empty strings to mirror `MigrationMetadataSchema` in\n// `./io.ts`. Without this match, an authored migration could `describe()` with\n// `from: ''` and pass `buildMigrationArtifacts`'s validation, only to have\n// `readMigrationPackage` reject the resulting `migration.json` later — the\n// two validators must agree on the legal value space.\nconst MigrationMetaSchema = type({\n  from: 'string > 0 | null',\n  to: 'string',\n  'labels?': type('string').array(),\n});\n\n/**\n * Base class for migrations.\n *\n * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the\n * runner can consume it directly via `targetId`, `operations`, `origin`, and\n * `destination`. The metadata-shaped inputs come from `describe()`, which\n * every migration must implement — `migration.json` is required for a\n * migration to be valid.\n */\nexport abstract class Migration<\n  TOperation extends MigrationPlanOperation = MigrationPlanOperation,\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> implements MigrationPlan\n{\n  abstract readonly targetId: string;\n\n  /**\n   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).\n   *\n   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their\n   * adapter once per instance. Optional at the abstract level so unit tests can\n   * construct `Migration` instances purely for `operations` / `describe`\n   * assertions without needing a real stack; concrete subclasses that need the\n   * stack at runtime should narrow the parameter to required.\n   */\n  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;\n\n  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {\n    this.stack = stack;\n  }\n\n  /**\n   * Ordered list of operations this migration performs.\n   *\n   * Implemented as a getter so that subclasses can either precompute the list\n   * in their constructor or build it lazily per access.\n   */\n  abstract get operations(): readonly TOperation[];\n\n  /**\n   * Metadata inputs used to build `migration.json` and to derive the plan's\n   * origin/destination identities. Every migration must provide this —\n   * omitting it would produce an invalid on-disk migration package.\n   */\n  abstract describe(): MigrationMeta;\n\n  get origin(): { readonly storageHash: string } | null {\n    const from = this.describe().from;\n    return from === null ? null : { storageHash: from };\n  }\n\n  get destination(): { readonly storageHash: string } {\n    return { storageHash: this.describe().to };\n  }\n}\n\n/**\n * Returns true when `import.meta.url` resolves to the same file that was\n * invoked as the node entrypoint (`process.argv[1]`). Used by\n * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when\n * the migration module is being imported (e.g. by another script) rather\n * than executed directly.\n */\nexport function isDirectEntrypoint(importMetaUrl: string): boolean {\n  const metaFilename = fileURLToPath(importMetaUrl);\n  const argv1 = process.argv[1];\n  if (!argv1) return false;\n  try {\n    return realpathSync(metaFilename) === realpathSync(argv1);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * In-memory artifacts produced from a `Migration` instance: the\n * serialized `ops.json` body, the `migration.json` metadata object, and\n * its serialized form. Returned by `buildMigrationArtifacts` so callers\n * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can\n * decide how to persist them — write to disk, print in dry-run, ship\n * over the wire — without coupling artifact construction to file I/O.\n *\n * `metadataJson` is `JSON.stringify(metadata, null, 2)` — the canonical\n * on-disk shape that the arktype loader-schema in `./io` validates.\n */\nexport interface MigrationArtifacts {\n  readonly opsJson: string;\n  readonly metadata: MigrationMetadata;\n  readonly metadataJson: string;\n}\n\n/**\n * Build the attested metadata from `describe()`-derived metadata, the\n * operations list, and the previously-scaffolded metadata (if any).\n *\n * When a `migration.json` already exists for this package (the common\n * case: it was scaffolded by `migration plan`), preserve the contract\n * bookends, hints, labels, and `createdAt` set there — those fields are\n * owned by the CLI scaffolder, not the authored class. Only the\n * `describe()`-derived fields (`from`, `to`) and the operations\n * change as the author iterates. When no metadata exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant record so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationHash` is recomputed against the current metadata + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedMetadata(\n  meta: MigrationMeta,\n  ops: MigrationOps,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationMetadata {\n  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {\n    from: meta.from,\n    to: meta.to,\n    labels: meta.labels ?? existing?.labels ?? [],\n    providedInvariants: deriveProvidedInvariants(ops),\n    createdAt: existing?.createdAt ?? new Date().toISOString(),\n    hints: normalizeHints(existing?.hints),\n  };\n\n  const migrationHash = computeMigrationHash(baseMetadata, ops);\n  return { ...baseMetadata, migrationHash };\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in metadata scaffolded by older CLI\n * versions (e.g. `planningStrategy`). Picking fields explicitly instead of\n * spreading keeps refreshed `migration.json` files schema-clean regardless\n * of what was on disk before.\n */\nfunction normalizeHints(existing: MigrationHints | undefined): MigrationHints {\n  return {\n    used: existing?.used ?? [],\n    applied: existing?.applied ?? [],\n    plannerVersion: existing?.plannerVersion ?? '2.0.0',\n  };\n}\n\n/**\n * Pure conversion from a `Migration` instance (plus the previously\n * scaffolded metadata, when one exists on disk) to the in-memory\n * artifacts that downstream tooling persists. Owns metadata validation,\n * metadata synthesis/preservation, hint normalization, and the\n * content-addressed `migrationHash` computation, but performs no file I/O\n * — callers handle reads (to source `existing`) and writes (to persist\n * `opsJson` / `metadataJson`).\n */\nexport function buildMigrationArtifacts(\n  instance: Migration,\n  existing: Partial<MigrationMetadata> | null,\n): MigrationArtifacts {\n  const ops = instance.operations;\n  if (!Array.isArray(ops)) {\n    throw new Error('operations must be an array');\n  }\n\n  for (let index = 0; index < ops.length; index++) {\n    const result = MigrationOpSchema(ops[index]);\n    if (result instanceof type.errors) {\n      throw errorInvalidOperationEntry(index, result.summary);\n    }\n  }\n\n  const rawMeta: unknown = instance.describe();\n  const parsed = MigrationMetaSchema(rawMeta);\n  if (parsed instanceof type.errors) {\n    throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n  }\n\n  const metadata = buildAttestedMetadata(parsed, ops, existing);\n\n  return {\n    opsJson: JSON.stringify(ops, null, 2),\n    metadata,\n    metadataJson: JSON.stringify(metadata, null, 2),\n  };\n}\n"],"mappings":";;;;;;;;AA0BA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,WAAW,KAAK,SAAS,CAAC,OAAO;CAClC,CAAC;;;;;;;;;;AAWF,IAAsB,YAAtB,MAKA;;;;;;;;;;CAYE;CAEA,YAAY,OAA4C;EACtD,KAAK,QAAQ;;CAkBf,IAAI,SAAkD;EACpD,MAAM,OAAO,KAAK,UAAU,CAAC;EAC7B,OAAO,SAAS,OAAO,OAAO,EAAE,aAAa,MAAM;;CAGrD,IAAI,cAAgD;EAClD,OAAO,EAAE,aAAa,KAAK,UAAU,CAAC,IAAI;;;;;;;;;;AAW9C,SAAgB,mBAAmB,eAAgC;CACjE,MAAM,eAAe,cAAc,cAAc;CACjD,MAAM,QAAQ,QAAQ,KAAK;CAC3B,IAAI,CAAC,OAAO,OAAO;CACnB,IAAI;EACF,OAAO,aAAa,aAAa,KAAK,aAAa,MAAM;SACnD;EACN,OAAO;;;;;;;;;;;;;;;;;;;;AAsCX,SAAS,sBACP,MACA,KACA,UACmB;CACnB,MAAM,eAAyD;EAC7D,MAAM,KAAK;EACX,IAAI,KAAK;EACT,QAAQ,KAAK,UAAU,UAAU,UAAU,EAAE;EAC7C,oBAAoB,yBAAyB,IAAI;EACjD,WAAW,UAAU,8BAAa,IAAI,MAAM,EAAC,aAAa;EAC1D,OAAO,eAAe,UAAU,MAAM;EACvC;CAED,MAAM,gBAAgB,qBAAqB,cAAc,IAAI;CAC7D,OAAO;EAAE,GAAG;EAAc;EAAe;;;;;;;;;AAU3C,SAAS,eAAe,UAAsD;CAC5E,OAAO;EACL,MAAM,UAAU,QAAQ,EAAE;EAC1B,SAAS,UAAU,WAAW,EAAE;EAChC,gBAAgB,UAAU,kBAAkB;EAC7C;;;;;;;;;;;AAYH,SAAgB,wBACd,UACA,UACoB;CACpB,MAAM,MAAM,SAAS;CACrB,IAAI,CAAC,MAAM,QAAQ,IAAI,EACrB,MAAM,IAAI,MAAM,8BAA8B;CAGhD,KAAK,IAAI,QAAQ,GAAG,QAAQ,IAAI,QAAQ,SAAS;EAC/C,MAAM,SAAS,kBAAkB,IAAI,OAAO;EAC5C,IAAI,kBAAkB,KAAK,QACzB,MAAM,2BAA2B,OAAO,OAAO,QAAQ;;CAK3D,MAAM,SAAS,oBADU,SAAS,UACQ,CAAC;CAC3C,IAAI,kBAAkB,KAAK,QACzB,MAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;CAG5E,MAAM,WAAW,sBAAsB,QAAQ,KAAK,SAAS;CAE7D,OAAO;EACL,SAAS,KAAK,UAAU,KAAK,MAAM,EAAE;EACrC;EACA,cAAc,KAAK,UAAU,UAAU,MAAM,EAAE;EAChD"}

package/dist/exports/package.d.mts

@@ -1,3 +1,3 @@
-import { n as OnDiskMigrationPackage, t as MigrationOps } from "../package-BjiZ7KDy.mjs";
+import { n as OnDiskMigrationPackage, t as MigrationOps } from "../package-DZj8YvD0.mjs";
 import { MigrationPackage } from "@prisma-next/framework-components/control";
 export { type MigrationOps, type MigrationPackage, type OnDiskMigrationPackage };

package/dist/exports/ref-resolution.d.mts

@@ -0,0 +1,100 @@
+import { n as MigrationGraph, t as MigrationEdge } from "../graph-BrLXqoUc.mjs";
+import { n as Refs } from "../refs-CDaNerhT.mjs";
+import { Result } from "@prisma-next/utils/result";
+
+//#region src/refs/types.d.ts
+/** Context required to resolve a contract or migration reference. */
+interface RefResolutionContext {
+  readonly graph: MigrationGraph;
+  readonly refs: Refs;
+}
+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. */
+interface ContractRef {
+  readonly hash: string;
+  readonly provenance: ContractRefProvenance;
+}
+type MigrationRefProvenance = {
+  readonly kind: 'dir-name';
+  readonly dirName: string;
+} | {
+  readonly kind: 'hash';
+  readonly input: string;
+};
+/** A resolved migration reference. */
+interface MigrationRef {
+  readonly dirName: string;
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly provenance: MigrationRefProvenance;
+}
+interface RefResolutionNotFound {
+  readonly kind: 'not-found';
+  readonly input: string;
+  readonly grammar: 'contract' | 'migration';
+}
+interface RefResolutionAmbiguous {
+  readonly kind: 'ambiguous';
+  readonly input: string;
+  readonly candidates: readonly string[];
+  readonly grammar: 'contract' | 'migration';
+}
+interface RefResolutionWrongGrammar {
+  readonly kind: 'wrong-grammar';
+  readonly input: string;
+  readonly expectedGrammar: 'contract' | 'migration';
+  readonly message: string;
+  readonly fix: string;
+}
+interface RefResolutionInvalidFormat {
+  readonly kind: 'invalid-format';
+  readonly input: string;
+  readonly reason: string;
+}
+type RefResolutionError = RefResolutionNotFound | RefResolutionAmbiguous | RefResolutionWrongGrammar | RefResolutionInvalidFormat;
+declare function findEdgeByDirName(graph: MigrationGraph, dirName: string): MigrationEdge | undefined;
+//#endregion
+//#region src/refs/contract-ref.d.ts
+/**
+ * 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)
+ */
+declare function parseContractRef(input: string, ctx: RefResolutionContext): Result<ContractRef, RefResolutionError>;
+//#endregion
+//#region src/refs/migration-ref.d.ts
+/**
+ * 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".
+ */
+declare function parseMigrationRef(input: string, ctx: RefResolutionContext): Result<MigrationRef, RefResolutionError>;
+//#endregion
+export { type ContractRef, type ContractRefProvenance, type MigrationRef, type MigrationRefProvenance, type RefResolutionAmbiguous, type RefResolutionContext, type RefResolutionError, type RefResolutionInvalidFormat, type RefResolutionNotFound, type RefResolutionWrongGrammar, findEdgeByDirName, parseContractRef, parseMigrationRef };
+//# sourceMappingURL=ref-resolution.d.mts.map

package/dist/exports/ref-resolution.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-resolution.d.mts","names":[],"sources":["../../src/refs/types.ts","../../src/refs/contract-ref.ts","../../src/refs/migration-ref.ts"],"mappings":";;;;;;UAIiB,oBAAA;EAAA,SACN,KAAA,EAAO,cAAA;EAAA,SACP,IAAA,EAAM,IAAA;AAAA;AAAA,KAGL,qBAAA;EAAA,SACG,IAAA;EAAA,SAAuB,KAAA;AAAA;EAAA,SACvB,IAAA;EAAA,SAAsB,OAAA;AAAA;EAAA,SACtB,IAAA;EAAA,SAA+B,OAAA;AAAA;EAAA,SAC/B,IAAA;EAAA,SAAiC,OAAA;AAAA;;UAG/B,WAAA;EAAA,SACN,IAAA;EAAA,SACA,UAAA,EAAY,qBAAA;AAAA;AAAA,KAGX,sBAAA;EAAA,SACG,IAAA;EAAA,SAA2B,OAAA;AAAA;EAAA,SAC3B,IAAA;EAAA,SAAuB,KAAA;AAAA;;UAGrB,YAAA;EAAA,SACN,OAAA;EAAA,SACA,aAAA;EAAA,SACA,IAAA;EAAA,SACA,EAAA;EAAA,SACA,UAAA,EAAY,sBAAA;AAAA;AAAA,UAGN,qBAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,OAAA;AAAA;AAAA,UAGM,sBAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,UAAA;EAAA,SACA,OAAA;AAAA;AAAA,UAGM,yBAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,eAAA;EAAA,SACA,OAAA;EAAA,SACA,GAAA;AAAA;AAAA,UAGM,0BAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA;AAAA;AAAA,KAGC,kBAAA,GACR,qBAAA,GACA,sBAAA,GACA,yBAAA,GACA,0BAAA;AAAA,iBAiBY,iBAAA,CACd,KAAA,EAAO,cAAA,EACP,OAAA,WACC,aAAA;;;;;;AAjFH;;;;;;;;iBCkBgB,gBAAA,CACd,KAAA,UACA,GAAA,EAAK,oBAAA,GACJ,MAAA,CAAO,WAAA,EAAa,kBAAA;;;;;;ADrBvB;;;;;;;;;iBEcgB,iBAAA,CACd,KAAA,UACA,GAAA,EAAK,oBAAA,GACJ,MAAA,CAAO,YAAA,EAAc,kBAAA"}

package/dist/exports/ref-resolution.mjs

@@ -0,0 +1,239 @@
+import { a as validateRefName } from "../refs-BDHo5l_g.mjs";
+import { notOk, ok } from "@prisma-next/utils/result";
+//#region src/refs/types.ts
+const FULL_HASH_PATTERN = /^sha256:([0-9a-f]{64}|empty)$/;
+const HEX_PREFIX_PATTERN = /^(sha256:)?[0-9a-f]{6,}$/;
+function isFullHash(input) {
+	return FULL_HASH_PATTERN.test(input);
+}
+function isHexPrefix(input) {
+	return HEX_PREFIX_PATTERN.test(input);
+}
+function normalizeHashPrefix(input) {
+	return input.startsWith("sha256:") ? input : `sha256:${input}`;
+}
+function findEdgeByDirName(graph, dirName) {
+	for (const edges of graph.forwardChain.values()) for (const edge of edges) if (edge.dirName === dirName) return edge;
+}
+//#endregion
+//#region src/refs/contract-ref.ts
+/**
+* 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)
+*/
+function parseContractRef(input, ctx) {
+	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"
+		});
+	}
+	const candidates = [];
+	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 !== void 0) 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 !== void 0) 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"
+	});
+}
+//#endregion
+//#region src/refs/migration-ref.ts
+/**
+* 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".
+*/
+function parseMigrationRef(input, ctx) {
+	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 !== void 0) {
+			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"
+		});
+		if ([...ctx.graph.nodes].filter((n) => n.startsWith(prefix)).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"
+	});
+}
+//#endregion
+export { findEdgeByDirName, parseContractRef, parseMigrationRef };
+
+//# sourceMappingURL=ref-resolution.mjs.map

package/dist/exports/ref-resolution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-resolution.mjs","names":[],"sources":["../../src/refs/types.ts","../../src/refs/contract-ref.ts","../../src/refs/migration-ref.ts"],"sourcesContent":["import type { MigrationEdge, MigrationGraph } from '../graph';\nimport type { Refs } from '../refs';\n\n/** Context required to resolve a contract or migration reference. */\nexport interface RefResolutionContext {\n  readonly graph: MigrationGraph;\n  readonly refs: Refs;\n}\n\nexport type ContractRefProvenance =\n  | { readonly kind: 'hash'; readonly input: string }\n  | { readonly kind: 'ref'; readonly refName: string }\n  | { readonly kind: 'migration-to'; readonly dirName: string }\n  | { readonly kind: 'migration-from'; readonly dirName: string };\n\n/** A resolved contract reference: the target hash and how it was derived. */\nexport interface ContractRef {\n  readonly hash: string;\n  readonly provenance: ContractRefProvenance;\n}\n\nexport type MigrationRefProvenance =\n  | { readonly kind: 'dir-name'; readonly dirName: string }\n  | { readonly kind: 'hash'; readonly input: string };\n\n/** A resolved migration reference. */\nexport interface MigrationRef {\n  readonly dirName: string;\n  readonly migrationHash: string;\n  readonly from: string;\n  readonly to: string;\n  readonly provenance: MigrationRefProvenance;\n}\n\nexport interface RefResolutionNotFound {\n  readonly kind: 'not-found';\n  readonly input: string;\n  readonly grammar: 'contract' | 'migration';\n}\n\nexport interface RefResolutionAmbiguous {\n  readonly kind: 'ambiguous';\n  readonly input: string;\n  readonly candidates: readonly string[];\n  readonly grammar: 'contract' | 'migration';\n}\n\nexport interface RefResolutionWrongGrammar {\n  readonly kind: 'wrong-grammar';\n  readonly input: string;\n  readonly expectedGrammar: 'contract' | 'migration';\n  readonly message: string;\n  readonly fix: string;\n}\n\nexport interface RefResolutionInvalidFormat {\n  readonly kind: 'invalid-format';\n  readonly input: string;\n  readonly reason: string;\n}\n\nexport type RefResolutionError =\n  | RefResolutionNotFound\n  | RefResolutionAmbiguous\n  | RefResolutionWrongGrammar\n  | RefResolutionInvalidFormat;\n\nconst FULL_HASH_PATTERN = /^sha256:([0-9a-f]{64}|empty)$/;\nconst HEX_PREFIX_PATTERN = /^(sha256:)?[0-9a-f]{6,}$/;\n\nexport function isFullHash(input: string): boolean {\n  return FULL_HASH_PATTERN.test(input);\n}\n\nexport function isHexPrefix(input: string): boolean {\n  return HEX_PREFIX_PATTERN.test(input);\n}\n\nexport function normalizeHashPrefix(input: string): string {\n  return input.startsWith('sha256:') ? input : `sha256:${input}`;\n}\n\nexport function findEdgeByDirName(\n  graph: MigrationGraph,\n  dirName: string,\n): MigrationEdge | undefined {\n  for (const edges of graph.forwardChain.values()) {\n    for (const edge of edges) {\n      if (edge.dirName === dirName) return edge;\n    }\n  }\n  return undefined;\n}\n","import type { Result } from '@prisma-next/utils/result';\nimport { notOk, ok } from '@prisma-next/utils/result';\nimport { validateRefName } from '../refs';\nimport type {\n  ContractRef,\n  ContractRefProvenance,\n  RefResolutionContext,\n  RefResolutionError,\n} from './types';\nimport { findEdgeByDirName, isFullHash, isHexPrefix, normalizeHashPrefix } from './types';\n\n/**\n * Resolve a user-supplied string to a contract hash using the unified\n * contract-reference grammar.\n *\n * Accepted forms:\n * - Full storage hash (`sha256:<64 hex>` or `sha256:empty`)\n * - Hex prefix (6+ hex chars, must uniquely identify one contract)\n * - Ref name (looked up in the refs index)\n * - Migration directory name (resolves to the migration's `to`-contract)\n * - `<dir>^` (resolves to the migration's `from`-contract)\n */\nexport function parseContractRef(\n  input: string,\n  ctx: RefResolutionContext,\n): Result<ContractRef, RefResolutionError> {\n  if (!input) {\n    return notOk({ kind: 'invalid-format', input, reason: 'Reference cannot be empty' });\n  }\n\n  if (isFullHash(input)) {\n    if (ctx.graph.nodes.has(input)) {\n      return ok({ hash: input, provenance: { kind: 'hash', input } });\n    }\n    return notOk({ kind: 'not-found', input, grammar: 'contract' });\n  }\n\n  if (input.endsWith('^')) {\n    const dirName = input.slice(0, -1);\n    if (!dirName) {\n      return notOk({ kind: 'invalid-format', input, reason: 'Missing directory name before ^' });\n    }\n    const edge = findEdgeByDirName(ctx.graph, dirName);\n    if (edge) {\n      return ok({ hash: edge.from, provenance: { kind: 'migration-from', dirName } });\n    }\n    return notOk({ kind: 'not-found', input, grammar: 'contract' });\n  }\n\n  type Candidate = { hash: string; provenance: ContractRefProvenance; label: string };\n  const candidates: Candidate[] = [];\n\n  if (validateRefName(input) && Object.hasOwn(ctx.refs, input)) {\n    const ref = ctx.refs[input];\n    if (ref) {\n      candidates.push({\n        hash: ref.hash,\n        provenance: { kind: 'ref', refName: input },\n        label: `ref \"${input}\"`,\n      });\n    }\n  }\n\n  const edge = findEdgeByDirName(ctx.graph, input);\n  if (edge) {\n    candidates.push({\n      hash: edge.to,\n      provenance: { kind: 'migration-to', dirName: input },\n      label: `migration directory \"${input}\"`,\n    });\n  }\n\n  if (isHexPrefix(input)) {\n    const prefix = normalizeHashPrefix(input);\n    const matches = [...ctx.graph.nodes].filter((n) => n.startsWith(prefix));\n    const [firstMatch] = matches;\n    if (matches.length === 1 && firstMatch !== undefined) {\n      candidates.push({\n        hash: firstMatch,\n        provenance: { kind: 'hash', input },\n        label: `hash prefix \"${input}\"`,\n      });\n    } else if (matches.length > 1) {\n      return notOk({ kind: 'ambiguous', input, candidates: matches, grammar: 'contract' });\n    }\n  }\n\n  const [firstCandidate] = candidates;\n  if (candidates.length === 1 && firstCandidate !== undefined) {\n    return ok({ hash: firstCandidate.hash, provenance: firstCandidate.provenance });\n  }\n\n  if (candidates.length > 1) {\n    return notOk({\n      kind: 'ambiguous',\n      input,\n      candidates: candidates.map((c) => c.label),\n      grammar: 'contract',\n    });\n  }\n\n  return notOk({ kind: 'not-found', input, grammar: 'contract' });\n}\n","import type { Result } from '@prisma-next/utils/result';\nimport { notOk, ok } from '@prisma-next/utils/result';\nimport { validateRefName } from '../refs';\nimport type { MigrationRef, RefResolutionContext, RefResolutionError } from './types';\nimport { findEdgeByDirName, isFullHash, isHexPrefix, normalizeHashPrefix } from './types';\n\n/**\n * Resolve a user-supplied string to a migration using the migration-reference\n * grammar.\n *\n * Accepted forms:\n * - Migration directory name (e.g. `20260101-add-users`)\n * - Migration hash (full or 6+ hex prefix)\n *\n * Wrong-grammar diagnostics are produced when the input matches a\n * contract-grammar form (ref name, `<dir>^`, contract-only hash) so the\n * user gets a targeted hint rather than a generic \"not found\".\n */\nexport function parseMigrationRef(\n  input: string,\n  ctx: RefResolutionContext,\n): Result<MigrationRef, RefResolutionError> {\n  if (!input) {\n    return notOk({ kind: 'invalid-format', input, reason: 'Reference cannot be empty' });\n  }\n\n  if (input.endsWith('^')) {\n    return notOk({\n      kind: 'wrong-grammar',\n      input,\n      expectedGrammar: 'migration',\n      message: '`^` syntax addresses contracts, not migrations',\n      fix: 'Pass the migration directory name without `^`, or use a contract-accepting flag like `--to` or `--from`.',\n    });\n  }\n\n  if (validateRefName(input) && Object.hasOwn(ctx.refs, input)) {\n    return notOk({\n      kind: 'wrong-grammar',\n      input,\n      expectedGrammar: 'migration',\n      message: `\"${input}\" is a ref name, not a migration`,\n      fix: 'Refs point at contracts, not migrations. Use a migration directory name or migration hash.',\n    });\n  }\n\n  const edge = findEdgeByDirName(ctx.graph, input);\n  if (edge) {\n    return ok({\n      dirName: edge.dirName,\n      migrationHash: edge.migrationHash,\n      from: edge.from,\n      to: edge.to,\n      provenance: { kind: 'dir-name', dirName: input },\n    });\n  }\n\n  if (isFullHash(input)) {\n    const migEdge = ctx.graph.migrationByHash.get(input);\n    if (migEdge) {\n      return ok({\n        dirName: migEdge.dirName,\n        migrationHash: migEdge.migrationHash,\n        from: migEdge.from,\n        to: migEdge.to,\n        provenance: { kind: 'hash', input },\n      });\n    }\n    if (ctx.graph.nodes.has(input)) {\n      return notOk({\n        kind: 'wrong-grammar',\n        input,\n        expectedGrammar: 'migration',\n        message: 'Hash matched a contract but not a migration',\n        fix: 'Use a contract-accepting flag like `--to` or `--from` to reference contracts by hash. Pass `migration show <dir>` for a specific migration.',\n      });\n    }\n    return notOk({ kind: 'not-found', input, grammar: 'migration' });\n  }\n\n  if (isHexPrefix(input)) {\n    const prefix = normalizeHashPrefix(input);\n    const migMatches = [...ctx.graph.migrationByHash.entries()].filter(([hash]) =>\n      hash.startsWith(prefix),\n    );\n\n    const [firstMigMatch] = migMatches;\n    if (migMatches.length === 1 && firstMigMatch !== undefined) {\n      const [, matchedEdge] = firstMigMatch;\n      return ok({\n        dirName: matchedEdge.dirName,\n        migrationHash: matchedEdge.migrationHash,\n        from: matchedEdge.from,\n        to: matchedEdge.to,\n        provenance: { kind: 'hash', input },\n      });\n    }\n\n    if (migMatches.length > 1) {\n      return notOk({\n        kind: 'ambiguous',\n        input,\n        candidates: migMatches.map(([hash]) => hash),\n        grammar: 'migration',\n      });\n    }\n\n    const contractMatches = [...ctx.graph.nodes].filter((n) => n.startsWith(prefix));\n    if (contractMatches.length > 0) {\n      return notOk({\n        kind: 'wrong-grammar',\n        input,\n        expectedGrammar: 'migration',\n        message: 'Hash matched a contract but not a migration',\n        fix: 'Use a contract-accepting flag like `--to` or `--from` to reference contracts by hash. Pass `migration show <dir>` for a specific migration.',\n      });\n    }\n  }\n\n  return notOk({ kind: 'not-found', input, grammar: 'migration' });\n}\n"],"mappings":"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"}

package/dist/exports/refs.d.mts

@@ -1,16 +1,2 @@
-//#region src/refs.d.ts
-interface RefEntry {
-  readonly hash: string;
-  readonly invariants: readonly string[];
-}
-type Refs = Readonly<Record<string, RefEntry>>;
-declare function validateRefName(name: string): boolean;
-declare function validateRefValue(value: string): boolean;
-declare function readRef(refsDir: string, name: string): Promise<RefEntry>;
-declare function readRefs(refsDir: string): Promise<Refs>;
-declare function writeRef(refsDir: string, name: string, entry: RefEntry): Promise<void>;
-declare function deleteRef(refsDir: string, name: string): Promise<void>;
-declare function resolveRef(refs: Refs, name: string): RefEntry;
-//#endregion
-export { type RefEntry, type Refs, deleteRef, readRef, readRefs, resolveRef, validateRefName, validateRefValue, writeRef };
-//# sourceMappingURL=refs.d.mts.map
+import { a as readRefs, c as validateRefValue, i as readRef, l as writeRef, n as Refs, o as resolveRef, r as deleteRef, s as validateRefName, t as RefEntry } from "../refs-CDaNerhT.mjs";
+export { type RefEntry, type Refs, deleteRef, readRef, readRefs, resolveRef, validateRefName, validateRefValue, writeRef };