@prisma-next/migration-tools 0.11.0-dev.56 → 0.11.0-dev.58

package/dist/{errors-4YabujxZ.mjs → errors-vFROOhCR.mjs}

@@ -261,6 +261,37 @@ function errorMigrationHashMismatch(dir, storedHash, computedHash) {
 		}
 	});
 }
+function errorSnapshotMissing(refName) {
+	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
+		}
+	});
+}
+function errorBundleNotFoundForGraphNode(hash, explicitLabel) {
+	return new MigrationToolsError("MIGRATION.BUNDLE_NOT_FOUND_FOR_GRAPH_NODE", explicitLabel ? `No migration bundle found for reference "${explicitLabel}" (resolved hash: ${hash})` : `No migration bundle found for graph node ${hash}`, {
+		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 } : {}
+		}
+	});
+}
+function errorContractDeserializationFailed(filePath, message) {
+	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
+		}
+	});
+}
 function errorHashNotInGraph(hash, graph) {
 	const reachableHashes = [...graph.nodes].sort();
 	const reachableList = reachableHashes.length > 0 ? reachableHashes.join(", ") : "(none)";
@@ -274,6 +305,6 @@ function errorHashNotInGraph(hash, graph) {
 	});
 }
 //#endregion
-export { errorProvidedInvariantsMismatch as C, errorNoTarget as S, errorInvalidSpaceId as _, errorDuplicateInvariantInEdge as a, errorNoInitialMigration as b, errorInvalidDestName as c, errorInvalidManifest as d, errorInvalidOperationEntry as f, errorInvalidSlug as g, errorInvalidRefValue as h, errorDirectoryExists as i, errorInvalidInvariantId as l, errorInvalidRefName as m, errorAmbiguousTarget as n, errorDuplicateSpaceId as o, errorInvalidRefFile as p, errorDescriptorHeadHashMismatch as r, errorHashNotInGraph as s, MigrationToolsError as t, errorInvalidJson as u, errorMigrationHashMismatch as v, errorUnknownInvariant as w, errorNoInvariantPath as x, errorMissingFile as y };
+export { errorNoInvariantPath as C, errorUnknownInvariant as D, errorSnapshotMissing as E, errorNoInitialMigration as S, errorProvidedInvariantsMismatch as T, errorInvalidRefValue as _, errorDescriptorHeadHashMismatch as a, errorMigrationHashMismatch as b, errorDuplicateSpaceId as c, errorInvalidInvariantId as d, errorInvalidJson as f, errorInvalidRefName as g, errorInvalidRefFile as h, errorContractDeserializationFailed as i, errorHashNotInGraph as l, errorInvalidOperationEntry as m, errorAmbiguousTarget as n, errorDirectoryExists as o, errorInvalidManifest as p, errorBundleNotFoundForGraphNode as r, errorDuplicateInvariantInEdge as s, MigrationToolsError as t, errorInvalidDestName as u, errorInvalidSlug as v, errorNoTarget as w, errorMissingFile as x, errorInvalidSpaceId as y };
 
-//# sourceMappingURL=errors-4YabujxZ.mjs.map
+//# sourceMappingURL=errors-vFROOhCR.mjs.map

package/dist/{errors-4YabujxZ.mjs.map → errors-vFROOhCR.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-4YabujxZ.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { ifDefined } from '@prisma-next/utils/defined';\nimport { basename, dirname, relative } from 'pathe';\nimport type { MigrationGraph } from './graph';\n\n/**\n * Build the canonical \"re-emit this package\" remediation hint.\n *\n * Every on-disk migration package ships its own `migration.ts` author-time\n * file. Running it regenerates `migration.json` and `ops.json` with the\n * correct hash + metadata, so it is the right primitive whenever a single\n * package's on-disk artifacts are missing, malformed, or otherwise corrupt.\n * Pointing users at `migration plan` would emit a *new* package rather than\n * heal the broken one.\n */\nfunction reemitHint(dir: string, fallback?: string): string {\n  const relativeDir = relative(process.cwd(), dir);\n  const reemit = `Re-emit the package by running \\`node \"${relativeDir}/migration.ts\"\\``;\n  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;\n}\n\n/**\n * Structured error for migration tooling operations.\n *\n * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under\n * the MIGRATION namespace. These are tooling-time errors (file I/O, hash\n * verification, migration history reconstruction), distinct from the runtime\n * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,\n * etc.).\n *\n * Fields:\n * - code:     Stable machine-readable code (MIGRATION.SUBCODE)\n * - category: Always 'MIGRATION'\n * - why:      Explains the cause in plain language\n * - fix:      Actionable remediation step\n * - details:  Machine-readable structured data for agents\n */\nexport class MigrationToolsError extends Error {\n  readonly code: string;\n  readonly category = 'MIGRATION' as const;\n  readonly why: string;\n  readonly fix: string;\n  readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    code: string,\n    summary: string,\n    options: {\n      readonly why: string;\n      readonly fix: string;\n      readonly details?: Record<string, unknown>;\n    },\n  ) {\n    super(summary);\n    this.name = 'MigrationToolsError';\n    this.code = code;\n    this.why = options.why;\n    this.fix = options.fix;\n    this.details = options.details;\n  }\n\n  static is(error: unknown): error is MigrationToolsError {\n    if (!(error instanceof Error)) return false;\n    const candidate = error as MigrationToolsError;\n    return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';\n  }\n}\n\nexport function errorDirectoryExists(dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {\n    why: `The directory \"${dir}\" already exists. Each migration must have a unique directory.`,\n    fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',\n    details: { dir },\n  });\n}\n\nexport function errorMissingFile(file: string, dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {\n    why: `Expected \"${file}\" in \"${dir}\" but the file does not exist.`,\n    fix: reemitHint(\n      dir,\n      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n    ),\n    details: { file, dir },\n  });\n}\n\nexport function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {\n    why: `Failed to parse \"${filePath}\": ${parseError}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, parseError },\n  });\n}\n\nexport function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {\n    why: `Migration manifest at \"${filePath}\" is invalid: ${reason}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, reason },\n  });\n}\n\nexport function errorInvalidOperationEntry(index: number, reason: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.INVALID_OPERATION_ENTRY',\n    'Migration operation entry is malformed',\n    {\n      why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,\n      fix: \"Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').\",\n      details: { index, reason },\n    },\n  );\n}\n\nexport function errorInvalidSlug(slug: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {\n    why: `The slug \"${slug}\" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,\n    fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',\n    details: { slug },\n  });\n}\n\nexport function errorInvalidDestName(destName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {\n    why: `The destination name \"${destName}\" must be a single path segment (no \"..\" or directory separators).`,\n    fix: 'Use a simple file name such as \"contract.json\" for each destination in the copy list.',\n    details: { destName },\n  });\n}\n\nexport function errorInvalidSpaceId(spaceId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.INVALID_SPACE_ID',\n    'Invalid contract space identifier',\n    {\n      why: `The space id \"${spaceId}\" does not match the required pattern /^[a-z][a-z0-9_-]{0,63}$/. Space ids are used as filesystem directory names under \\`migrations/\\`, so the pattern is conservative on purpose.`,\n      fix: 'Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.',\n      details: { spaceId },\n    },\n  );\n}\n\nexport function errorDescriptorHeadHashMismatch(args: {\n  readonly extensionId: string;\n  readonly recomputedHash: string;\n  readonly headRefHash: string;\n}): MigrationToolsError {\n  const { extensionId, recomputedHash, headRefHash } = args;\n  return new MigrationToolsError(\n    'MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH',\n    \"Extension descriptor's headRef.hash does not match its contractJson\",\n    {\n      why: `Extension \"${extensionId}\" publishes a \\`contractSpace\\` whose \\`headRef.hash\\` (${headRefHash}) does not match the canonical hash recomputed from \\`contractSpace.contractJson\\` (${recomputedHash}). This means the extension descriptor was published with stale \\`headRef.hash\\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,\n      fix: 'Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).',\n      details: { extensionId, recomputedHash, headRefHash },\n    },\n  );\n}\n\nexport function errorDuplicateSpaceId(spaceId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_SPACE_ID',\n    'Duplicate contract space identifier',\n    {\n      why: `The space id \"${spaceId}\" appears more than once in the per-space planner input. Each space id must be unique across the inputs (the per-space planner emits one output entry per id).`,\n      fix: 'Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.',\n      details: { spaceId },\n    },\n  );\n}\n\nexport function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {\n  const dirName = basename(dir);\n  return new MigrationToolsError(\n    'MIGRATION.SAME_SOURCE_AND_TARGET',\n    'Migration without data-transform operations has same source and target',\n    {\n      why: `Migration \"${dirName}\" has from === to === \"${hash}\" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,\n      fix: reemitHint(\n        dir,\n        'and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted.',\n      ),\n      details: { dirName, hash },\n    },\n  );\n}\n\nexport function errorAmbiguousTarget(\n  branchTips: readonly string[],\n  context?: {\n    divergencePoint: string;\n    branches: readonly {\n      tip: string;\n      edges: readonly { dirName: string; from: string; to: string }[];\n    }[];\n  },\n): MigrationToolsError {\n  const divergenceInfo = context\n    ? `\\nDivergence point: ${context.divergencePoint}\\nBranches:\\n${context.branches.map((b) => `  → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\\n')}`\n    : '';\n  return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {\n    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}`,\n    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.',\n    details: {\n      branchTips,\n      ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),\n    },\n  });\n}\n\nexport function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {\n    why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,\n    fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',\n    details: { nodes },\n  });\n}\n\nexport function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {\n    why: `refs.json at \"${refsPath}\" is invalid: ${reason}`,\n    fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',\n    details: { path: refsPath, reason },\n  });\n}\n\nexport function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {\n    why: `Ref file at \"${filePath}\" is invalid: ${reason}`,\n    fix: 'Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.',\n    details: { path: filePath, reason },\n  });\n}\n\nexport function errorInvalidRefName(refName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {\n    why: `Ref name \"${refName}\" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no \".\" or \"..\" segments).`,\n    fix: `Use a valid ref name (e.g., \"staging\", \"envs/production\").`,\n    details: { refName },\n  });\n}\n\nexport function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {\n    why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,\n    fix: 'Use --from <hash> to specify the planning origin explicitly.',\n    details: { reachableHashes },\n  });\n}\n\nexport function errorInvalidRefValue(value: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {\n    why: `Ref value \"${value}\" is not a valid contract hash. Values must be in the format \"sha256:<64 hex chars>\" or \"sha256:empty\".`,\n    fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',\n    details: { value },\n  });\n}\n\nexport function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_MIGRATION_HASH',\n    'Duplicate migrationHash in migration graph',\n    {\n      why: `Multiple migrations share migrationHash \"${migrationHash}\". Each migration must have a unique content-addressed identity.`,\n      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',\n      details: { migrationHash },\n    },\n  );\n}\n\nexport function errorInvalidInvariantId(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {\n    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,\n    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".',\n    details: { invariantId },\n  });\n}\n\nexport function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',\n    'Duplicate invariantId on a single migration',\n    {\n      why: `invariantId \"${invariantId}\" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,\n      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',\n      details: { invariantId },\n    },\n  );\n}\n\nexport function errorProvidedInvariantsMismatch(\n  filePath: string,\n  stored: readonly string[],\n  derived: readonly string[],\n): MigrationToolsError {\n  const storedSet = new Set(stored);\n  const derivedSet = new Set(derived);\n  const missing = [...derivedSet].filter((id) => !storedSet.has(id));\n  const extra = [...storedSet].filter((id) => !derivedSet.has(id));\n  // When sets agree but arrays don't, the only difference is ordering — call\n  // it out so the reader doesn't stare at two visually-identical arrays.\n  // Canonical providedInvariants is sorted ascending; a manifest with the\n  // same ids in a different order is still a mismatch (the hash check would\n  // also fail), but the human-readable diagnostic is otherwise unhelpful.\n  const orderingOnly = missing.length === 0 && extra.length === 0;\n  const why = orderingOnly\n    ? `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`\n    : `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;\n  return new MigrationToolsError(\n    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',\n    'providedInvariants on migration.json disagrees with ops.json',\n    {\n      why,\n      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n      details: { filePath, stored, derived, difference: { missing, extra } },\n    },\n  );\n}\n\n/**\n * Wire-shape edge surfaced through the JSON envelope's\n * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —\n * authoring metadata (`createdAt`) lives on `MigrationEdge` but is\n * intentionally dropped here so the envelope stays stable across\n * graph-internal refactors.\n *\n * Stability: any field added here is part of the public CLI JSON contract.\n * Callers (CLI consumers, agents) must be able to treat\n * `(dirName, migrationHash, from, to, invariants)` as the canonical shape.\n */\nexport interface NoInvariantPathStructuralEdge {\n  readonly dirName: string;\n  readonly migrationHash: string;\n  readonly from: string;\n  readonly to: string;\n  readonly invariants: readonly string[];\n}\n\nexport function errorNoInvariantPath(args: {\n  readonly refName?: string;\n  readonly required: readonly string[];\n  readonly missing: readonly string[];\n  readonly structuralPath: readonly NoInvariantPathStructuralEdge[];\n}): MigrationToolsError {\n  const { refName, required, missing, structuralPath } = args;\n  const refClause = refName ? `Ref \"${refName}\"` : 'Target';\n  const missingList = missing.map((id) => JSON.stringify(id)).join(', ');\n  const requiredList = required.map((id) => JSON.stringify(id)).join(', ');\n  return new MigrationToolsError(\n    'MIGRATION.NO_INVARIANT_PATH',\n    'No path covers the required invariants',\n    {\n      why: `${refClause} requires invariants the reachable path doesn't cover. required=[${requiredList}], missing=[${missingList}].`,\n      fix: 'Add a migration on the path that runs `dataTransform({ invariantId: \"<id>\", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.',\n      details: {\n        required,\n        missing,\n        structuralPath,\n        ...ifDefined('refName', refName),\n      },\n    },\n  );\n}\n\nexport function errorUnknownInvariant(args: {\n  readonly refName?: string;\n  readonly unknown: readonly string[];\n  readonly declared: readonly string[];\n}): MigrationToolsError {\n  const { refName, unknown, declared } = args;\n  const refClause = refName ? `Ref \"${refName}\" declares` : 'Declares';\n  const unknownList = unknown.map((id) => JSON.stringify(id)).join(', ');\n  return new MigrationToolsError(\n    'MIGRATION.UNKNOWN_INVARIANT',\n    'Ref declares invariants no migration in the graph provides',\n    {\n      why: `${refClause} invariants no migration in the graph provides. unknown=[${unknownList}].`,\n      fix: 'Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.',\n      details: {\n        unknown,\n        declared,\n        ...ifDefined('refName', refName),\n      },\n    },\n  );\n}\n\nexport function errorMigrationHashMismatch(\n  dir: string,\n  storedHash: string,\n  computedHash: string,\n): MigrationToolsError {\n  // Render a cwd-relative path in the human-readable diagnostic so users\n  // running CLI commands from the project root see a familiar short path.\n  // Keep the absolute path in `details.dir` for machine consumers.\n  const relativeDir = relative(process.cwd(), dir);\n  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {\n    why: `Stored migrationHash \"${storedHash}\" does not match the recomputed hash \"${computedHash}\" for \"${relativeDir}\". The migration.json or ops.json has been edited or partially written since emit.`,\n    fix: reemitHint(dir, 'or restore the directory from version control.'),\n    details: { dir, storedHash, computedHash },\n  });\n}\n\nexport function errorHashNotInGraph(hash: string, graph: MigrationGraph): MigrationToolsError {\n  const reachableHashes = [...graph.nodes].sort();\n  const reachableList = reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none)';\n  return new MigrationToolsError(\n    'MIGRATION.HASH_NOT_IN_GRAPH',\n    `Hash \"${hash}\" is not a node in the migration graph`,\n    {\n      why: `The migration graph contains nodes ${reachableList}; \"${hash}\" isn't one of them.`,\n      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.`,\n      details: { hash, reachableHashes },\n    },\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"errors-vFROOhCR.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { ifDefined } from '@prisma-next/utils/defined';\nimport { basename, dirname, relative } from 'pathe';\nimport type { MigrationGraph } from './graph';\n\n/**\n * Build the canonical \"re-emit this package\" remediation hint.\n *\n * Every on-disk migration package ships its own `migration.ts` author-time\n * file. Running it regenerates `migration.json` and `ops.json` with the\n * correct hash + metadata, so it is the right primitive whenever a single\n * package's on-disk artifacts are missing, malformed, or otherwise corrupt.\n * Pointing users at `migration plan` would emit a *new* package rather than\n * heal the broken one.\n */\nfunction reemitHint(dir: string, fallback?: string): string {\n  const relativeDir = relative(process.cwd(), dir);\n  const reemit = `Re-emit the package by running \\`node \"${relativeDir}/migration.ts\"\\``;\n  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;\n}\n\n/**\n * Structured error for migration tooling operations.\n *\n * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under\n * the MIGRATION namespace. These are tooling-time errors (file I/O, hash\n * verification, migration history reconstruction), distinct from the runtime\n * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,\n * etc.).\n *\n * Fields:\n * - code:     Stable machine-readable code (MIGRATION.SUBCODE)\n * - category: Always 'MIGRATION'\n * - why:      Explains the cause in plain language\n * - fix:      Actionable remediation step\n * - details:  Machine-readable structured data for agents\n */\nexport class MigrationToolsError extends Error {\n  readonly code: string;\n  readonly category = 'MIGRATION' as const;\n  readonly why: string;\n  readonly fix: string;\n  readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    code: string,\n    summary: string,\n    options: {\n      readonly why: string;\n      readonly fix: string;\n      readonly details?: Record<string, unknown>;\n    },\n  ) {\n    super(summary);\n    this.name = 'MigrationToolsError';\n    this.code = code;\n    this.why = options.why;\n    this.fix = options.fix;\n    this.details = options.details;\n  }\n\n  static is(error: unknown): error is MigrationToolsError {\n    if (!(error instanceof Error)) return false;\n    const candidate = error as MigrationToolsError;\n    return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';\n  }\n}\n\nexport function errorDirectoryExists(dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {\n    why: `The directory \"${dir}\" already exists. Each migration must have a unique directory.`,\n    fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',\n    details: { dir },\n  });\n}\n\nexport function errorMissingFile(file: string, dir: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {\n    why: `Expected \"${file}\" in \"${dir}\" but the file does not exist.`,\n    fix: reemitHint(\n      dir,\n      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n    ),\n    details: { file, dir },\n  });\n}\n\nexport function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {\n    why: `Failed to parse \"${filePath}\": ${parseError}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, parseError },\n  });\n}\n\nexport function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {\n    why: `Migration manifest at \"${filePath}\" is invalid: ${reason}`,\n    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n    details: { filePath, reason },\n  });\n}\n\nexport function errorInvalidOperationEntry(index: number, reason: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.INVALID_OPERATION_ENTRY',\n    'Migration operation entry is malformed',\n    {\n      why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,\n      fix: \"Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').\",\n      details: { index, reason },\n    },\n  );\n}\n\nexport function errorInvalidSlug(slug: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {\n    why: `The slug \"${slug}\" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,\n    fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',\n    details: { slug },\n  });\n}\n\nexport function errorInvalidDestName(destName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {\n    why: `The destination name \"${destName}\" must be a single path segment (no \"..\" or directory separators).`,\n    fix: 'Use a simple file name such as \"contract.json\" for each destination in the copy list.',\n    details: { destName },\n  });\n}\n\nexport function errorInvalidSpaceId(spaceId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.INVALID_SPACE_ID',\n    'Invalid contract space identifier',\n    {\n      why: `The space id \"${spaceId}\" does not match the required pattern /^[a-z][a-z0-9_-]{0,63}$/. Space ids are used as filesystem directory names under \\`migrations/\\`, so the pattern is conservative on purpose.`,\n      fix: 'Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.',\n      details: { spaceId },\n    },\n  );\n}\n\nexport function errorDescriptorHeadHashMismatch(args: {\n  readonly extensionId: string;\n  readonly recomputedHash: string;\n  readonly headRefHash: string;\n}): MigrationToolsError {\n  const { extensionId, recomputedHash, headRefHash } = args;\n  return new MigrationToolsError(\n    'MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH',\n    \"Extension descriptor's headRef.hash does not match its contractJson\",\n    {\n      why: `Extension \"${extensionId}\" publishes a \\`contractSpace\\` whose \\`headRef.hash\\` (${headRefHash}) does not match the canonical hash recomputed from \\`contractSpace.contractJson\\` (${recomputedHash}). This means the extension descriptor was published with stale \\`headRef.hash\\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,\n      fix: 'Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).',\n      details: { extensionId, recomputedHash, headRefHash },\n    },\n  );\n}\n\nexport function errorDuplicateSpaceId(spaceId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_SPACE_ID',\n    'Duplicate contract space identifier',\n    {\n      why: `The space id \"${spaceId}\" appears more than once in the per-space planner input. Each space id must be unique across the inputs (the per-space planner emits one output entry per id).`,\n      fix: 'Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.',\n      details: { spaceId },\n    },\n  );\n}\n\nexport function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {\n  const dirName = basename(dir);\n  return new MigrationToolsError(\n    'MIGRATION.SAME_SOURCE_AND_TARGET',\n    'Migration without data-transform operations has same source and target',\n    {\n      why: `Migration \"${dirName}\" has from === to === \"${hash}\" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,\n      fix: reemitHint(\n        dir,\n        'and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted.',\n      ),\n      details: { dirName, hash },\n    },\n  );\n}\n\nexport function errorAmbiguousTarget(\n  branchTips: readonly string[],\n  context?: {\n    divergencePoint: string;\n    branches: readonly {\n      tip: string;\n      edges: readonly { dirName: string; from: string; to: string }[];\n    }[];\n  },\n): MigrationToolsError {\n  const divergenceInfo = context\n    ? `\\nDivergence point: ${context.divergencePoint}\\nBranches:\\n${context.branches.map((b) => `  → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\\n')}`\n    : '';\n  return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {\n    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}`,\n    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.',\n    details: {\n      branchTips,\n      ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),\n    },\n  });\n}\n\nexport function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {\n    why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,\n    fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',\n    details: { nodes },\n  });\n}\n\nexport function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {\n    why: `refs.json at \"${refsPath}\" is invalid: ${reason}`,\n    fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',\n    details: { path: refsPath, reason },\n  });\n}\n\nexport function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {\n    why: `Ref file at \"${filePath}\" is invalid: ${reason}`,\n    fix: 'Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.',\n    details: { path: filePath, reason },\n  });\n}\n\nexport function errorInvalidRefName(refName: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {\n    why: `Ref name \"${refName}\" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no \".\" or \"..\" segments).`,\n    fix: `Use a valid ref name (e.g., \"staging\", \"envs/production\").`,\n    details: { refName },\n  });\n}\n\nexport function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {\n    why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,\n    fix: 'Use --from <hash> to specify the planning origin explicitly.',\n    details: { reachableHashes },\n  });\n}\n\nexport function errorInvalidRefValue(value: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {\n    why: `Ref value \"${value}\" is not a valid contract hash. Values must be in the format \"sha256:<64 hex chars>\" or \"sha256:empty\".`,\n    fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',\n    details: { value },\n  });\n}\n\nexport function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_MIGRATION_HASH',\n    'Duplicate migrationHash in migration graph',\n    {\n      why: `Multiple migrations share migrationHash \"${migrationHash}\". Each migration must have a unique content-addressed identity.`,\n      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',\n      details: { migrationHash },\n    },\n  );\n}\n\nexport function errorInvalidInvariantId(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {\n    why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,\n    fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".',\n    details: { invariantId },\n  });\n}\n\nexport function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',\n    'Duplicate invariantId on a single migration',\n    {\n      why: `invariantId \"${invariantId}\" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,\n      fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',\n      details: { invariantId },\n    },\n  );\n}\n\nexport function errorProvidedInvariantsMismatch(\n  filePath: string,\n  stored: readonly string[],\n  derived: readonly string[],\n): MigrationToolsError {\n  const storedSet = new Set(stored);\n  const derivedSet = new Set(derived);\n  const missing = [...derivedSet].filter((id) => !storedSet.has(id));\n  const extra = [...storedSet].filter((id) => !derivedSet.has(id));\n  // When sets agree but arrays don't, the only difference is ordering — call\n  // it out so the reader doesn't stare at two visually-identical arrays.\n  // Canonical providedInvariants is sorted ascending; a manifest with the\n  // same ids in a different order is still a mismatch (the hash check would\n  // also fail), but the human-readable diagnostic is otherwise unhelpful.\n  const orderingOnly = missing.length === 0 && extra.length === 0;\n  const why = orderingOnly\n    ? `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`\n    : `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;\n  return new MigrationToolsError(\n    'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',\n    'providedInvariants on migration.json disagrees with ops.json',\n    {\n      why,\n      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n      details: { filePath, stored, derived, difference: { missing, extra } },\n    },\n  );\n}\n\n/**\n * Wire-shape edge surfaced through the JSON envelope's\n * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —\n * authoring metadata (`createdAt`) lives on `MigrationEdge` but is\n * intentionally dropped here so the envelope stays stable across\n * graph-internal refactors.\n *\n * Stability: any field added here is part of the public CLI JSON contract.\n * Callers (CLI consumers, agents) must be able to treat\n * `(dirName, migrationHash, from, to, invariants)` as the canonical shape.\n */\nexport interface NoInvariantPathStructuralEdge {\n  readonly dirName: string;\n  readonly migrationHash: string;\n  readonly from: string;\n  readonly to: string;\n  readonly invariants: readonly string[];\n}\n\nexport function errorNoInvariantPath(args: {\n  readonly refName?: string;\n  readonly required: readonly string[];\n  readonly missing: readonly string[];\n  readonly structuralPath: readonly NoInvariantPathStructuralEdge[];\n}): MigrationToolsError {\n  const { refName, required, missing, structuralPath } = args;\n  const refClause = refName ? `Ref \"${refName}\"` : 'Target';\n  const missingList = missing.map((id) => JSON.stringify(id)).join(', ');\n  const requiredList = required.map((id) => JSON.stringify(id)).join(', ');\n  return new MigrationToolsError(\n    'MIGRATION.NO_INVARIANT_PATH',\n    'No path covers the required invariants',\n    {\n      why: `${refClause} requires invariants the reachable path doesn't cover. required=[${requiredList}], missing=[${missingList}].`,\n      fix: 'Add a migration on the path that runs `dataTransform({ invariantId: \"<id>\", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.',\n      details: {\n        required,\n        missing,\n        structuralPath,\n        ...ifDefined('refName', refName),\n      },\n    },\n  );\n}\n\nexport function errorUnknownInvariant(args: {\n  readonly refName?: string;\n  readonly unknown: readonly string[];\n  readonly declared: readonly string[];\n}): MigrationToolsError {\n  const { refName, unknown, declared } = args;\n  const refClause = refName ? `Ref \"${refName}\" declares` : 'Declares';\n  const unknownList = unknown.map((id) => JSON.stringify(id)).join(', ');\n  return new MigrationToolsError(\n    'MIGRATION.UNKNOWN_INVARIANT',\n    'Ref declares invariants no migration in the graph provides',\n    {\n      why: `${refClause} invariants no migration in the graph provides. unknown=[${unknownList}].`,\n      fix: 'Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.',\n      details: {\n        unknown,\n        declared,\n        ...ifDefined('refName', refName),\n      },\n    },\n  );\n}\n\nexport function errorMigrationHashMismatch(\n  dir: string,\n  storedHash: string,\n  computedHash: string,\n): MigrationToolsError {\n  // Render a cwd-relative path in the human-readable diagnostic so users\n  // running CLI commands from the project root see a familiar short path.\n  // Keep the absolute path in `details.dir` for machine consumers.\n  const relativeDir = relative(process.cwd(), dir);\n  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {\n    why: `Stored migrationHash \"${storedHash}\" does not match the recomputed hash \"${computedHash}\" for \"${relativeDir}\". The migration.json or ops.json has been edited or partially written since emit.`,\n    fix: reemitHint(dir, 'or restore the directory from version control.'),\n    details: { dir, storedHash, computedHash },\n  });\n}\n\nexport function errorSnapshotMissing(refName: string): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.SNAPSHOT_MISSING',\n    `Ref \"${refName}\" has no paired contract snapshot`,\n    {\n      why: `Ref \"${refName}\" exists but its paired snapshot files are missing.`,\n      fix: `Run \"prisma-next db update --advance-ref ${refName}\" to repopulate the snapshot, or \"prisma-next ref delete ${refName}\" to clear the orphan pointer.`,\n      details: { refName, identifier: refName, viaRef: true },\n    },\n  );\n}\n\nexport function errorBundleNotFoundForGraphNode(\n  hash: string,\n  explicitLabel?: string,\n): MigrationToolsError {\n  const summary = explicitLabel\n    ? `No migration bundle found for reference \"${explicitLabel}\" (resolved hash: ${hash})`\n    : `No migration bundle found for graph node ${hash}`;\n  return new MigrationToolsError('MIGRATION.BUNDLE_NOT_FOUND_FOR_GRAPH_NODE', summary, {\n    why: `The hash ${hash} is a graph node but no on-disk migration package has an end-contract hash matching it.`,\n    fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',\n    details: { hash, ...(explicitLabel ? { explicitLabel } : {}) },\n  });\n}\n\nexport function errorContractDeserializationFailed(\n  filePath: string,\n  message: string,\n): MigrationToolsError {\n  return new MigrationToolsError(\n    'MIGRATION.CONTRACT_DESERIALIZATION_FAILED',\n    'Contract failed to deserialize',\n    {\n      why: `Contract at \"${filePath}\" failed to deserialize: ${message}`,\n      fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n      details: { filePath, message },\n    },\n  );\n}\n\nexport function errorHashNotInGraph(hash: string, graph: MigrationGraph): MigrationToolsError {\n  const reachableHashes = [...graph.nodes].sort();\n  const reachableList = reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none)';\n  return new MigrationToolsError(\n    'MIGRATION.HASH_NOT_IN_GRAPH',\n    `Hash \"${hash}\" is not a node in the migration graph`,\n    {\n      why: `The migration graph contains nodes ${reachableList}; \"${hash}\" isn't one of them.`,\n      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.`,\n      details: { hash, reachableHashes },\n    },\n  );\n}\n"],"mappings":"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"}

package/dist/exports/aggregate.d.mts

@@ -1,9 +1,9 @@
-import { n as OnDiskMigrationPackage } from "../package-DIttKL7X.mjs";
-import { n as RefLoadProblem, r as Refs } from "../refs-C8f2IGM8.mjs";
-import { t as ContractSpaceHeadRecord } from "../verify-contract-spaces-T0aiJlBS.mjs";
-import { n as MigrationGraph } from "../graph-BUZuUeBC.mjs";
-import { t as PackageLoadProblem } from "../io-nqFXSSTN.mjs";
-import { t as PathDecision } from "../migration-graph-DtNT-cqc.mjs";
+import { n as OnDiskMigrationPackage } from "../package-C31VGBCK.mjs";
+import { n as RefLoadProblem, r as Refs } from "../refs-BPYU-r14.mjs";
+import { t as ContractSpaceHeadRecord } from "../verify-contract-spaces-C7EZktZP.mjs";
+import { n as MigrationGraph } from "../graph-BwjwIZmb.mjs";
+import { t as PackageLoadProblem } from "../io-g7fQCYNJ.mjs";
+import { t as PathDecision } from "../migration-graph-CC7PSXw0.mjs";
 import { ControlFamilyInstance, MigrationOperationPolicy, MigrationPlan, MigrationPlanOperation, MigrationPlannerConflict, TargetMigrationsCapability } from "@prisma-next/framework-components/control";
 import { Result } from "@prisma-next/utils/result";
 import { Contract } from "@prisma-next/contract/types";
@@ -125,6 +125,23 @@ interface IntegrityQueryOptions {
 }
 //#endregion
 //#region src/aggregate/types.d.ts
+interface ContractAtOptions {
+  readonly refName?: string;
+}
+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.
@@ -155,6 +172,11 @@ interface IntegrityQueryOptions {
  *   `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.
  */
 interface ContractSpaceMember {
   readonly spaceId: string;
@@ -163,6 +185,7 @@ interface ContractSpaceMember {
   readonly headRef: ContractSpaceHeadRecord | null;
   graph(): MigrationGraph;
   contract(): Contract;
+  contractAt(hash: string, opts?: ContractAtOptions): Promise<ContractAtResult>;
 }
 /**
  * Tolerant, queryable snapshot of a project's on-disk migration state:
@@ -210,21 +233,26 @@ interface ContractSpaceAggregate {
  */
 declare function requireHeadRef(member: ContractSpaceMember): ContractSpaceHeadRecord;
 /**
- * Build a {@link ContractSpaceMember} with lazily-memoised `graph()` and
- * `contract()` facets.
+ * Build a {@link ContractSpaceMember} with lazily-memoised `graph()`,
+ * `contract()`, and `contractAt()` facets.
  *
  * `graph()` reconstructs the migration graph from `packages` on first
  * call and caches it. `contract()` calls `resolveContract` on first call
  * and caches the result; a throwing `resolveContract` (e.g. a missing or
  * undeserializable on-disk contract) re-throws on each call rather than
  * caching a value — `checkIntegrity` surfaces that as `contractUnreadable`.
+ * `contractAt()` materializes the contract at an arbitrary graph node with
+ * the same resolution order as plan-time ref resolution: ref snapshot first
+ * (when `opts.refName` is set), else the matching package's `end-contract.*`.
  */
 declare function createContractSpaceMember(args: {
   readonly spaceId: string;
   readonly packages: readonly OnDiskMigrationPackage[];
   readonly refs: Refs;
   readonly headRef: ContractSpaceHeadRecord | null;
+  readonly refsDir: string;
   readonly resolveContract: () => Contract;
+  readonly deserializeContract: (raw: unknown) => Contract;
 }): ContractSpaceMember;
 /**
  * Assemble a {@link ContractSpaceAggregate} value from its members and a
@@ -716,5 +744,5 @@ type AggregateVerifierOutput<TSchemaResult> = Result<AggregateVerifierSuccess<TS
  */
 declare function verifyAggregate<TSchemaResult>(input: AggregateVerifierInput<TSchemaResult>): AggregateVerifierOutput<TSchemaResult>;
 //#endregion
-export { type AggregateCurrentDBState, type AggregateMigrationEdgeRef, type AggregatePerSpacePlan, type AggregatePlannerError, type AggregatePlannerInput, type AggregatePlannerOutput, type AggregatePlannerSuccess, type AggregateVerifierError, type AggregateVerifierInput, type AggregateVerifierOutput, type AggregateVerifierSuccess, type CallerPolicy, type ContractMarkerRecordLike, type ContractSpaceAggregate, type ContractSpaceMember, type DeclaredExtensionEntry, type GraphWalkOutcome, type GraphWalkStrategyInputs, type IntegrityComputationInput, type IntegrityQueryOptions, type IntegritySpaceState, type IntegrityViolation, type LoadAggregateInput, type MarkerCheckResult, type MarkerCheckSection, type OrphanElement, type SchemaCheckSection, computeIntegrityViolations, createContractSpaceAggregate, createContractSpaceMember, graphWalkStrategy, loadContractSpaceAggregate, loadProblemToViolation, planAggregate, projectSchemaToSpace, requireHeadRef, verifyAggregate };
+export { type AggregateCurrentDBState, type AggregateMigrationEdgeRef, type AggregatePerSpacePlan, type AggregatePlannerError, type AggregatePlannerInput, type AggregatePlannerOutput, type AggregatePlannerSuccess, type AggregateVerifierError, type AggregateVerifierInput, type AggregateVerifierOutput, type AggregateVerifierSuccess, type CallerPolicy, type ContractAtOptions, type ContractAtResult, type ContractMarkerRecordLike, type ContractSpaceAggregate, type ContractSpaceMember, type DeclaredExtensionEntry, type GraphWalkOutcome, type GraphWalkStrategyInputs, type IntegrityComputationInput, type IntegrityQueryOptions, type IntegritySpaceState, type IntegrityViolation, type LoadAggregateInput, type MarkerCheckResult, type MarkerCheckSection, type OrphanElement, type SchemaCheckSection, computeIntegrityViolations, createContractSpaceAggregate, createContractSpaceMember, graphWalkStrategy, loadContractSpaceAggregate, loadProblemToViolation, planAggregate, projectSchemaToSpace, requireHeadRef, verifyAggregate };
 //# sourceMappingURL=aggregate.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"aggregate.d.mts","names":[],"sources":["../../src/integrity-violation.ts","../../src/aggregate/types.ts","../../src/aggregate/aggregate.ts","../../src/aggregate/check-integrity.ts","../../src/aggregate/loader.ts","../../src/aggregate/marker-types.ts","../../src/aggregate/planner-types.ts","../../src/aggregate/planner.ts","../../src/aggregate/project-schema-to-space.ts","../../src/aggregate/strategies/graph-walk.ts","../../src/aggregate/verifier.ts"],"mappings":"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"}
+{"version":3,"file":"aggregate.d.mts","names":[],"sources":["../../src/integrity-violation.ts","../../src/aggregate/types.ts","../../src/aggregate/aggregate.ts","../../src/aggregate/check-integrity.ts","../../src/aggregate/loader.ts","../../src/aggregate/marker-types.ts","../../src/aggregate/planner-types.ts","../../src/aggregate/planner.ts","../../src/aggregate/project-schema-to-space.ts","../../src/aggregate/strategies/graph-walk.ts","../../src/aggregate/verifier.ts"],"mappings":"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"}

package/dist/exports/aggregate.mjs

@@ -1,13 +1,105 @@
-import { t as MigrationToolsError } from "../errors-4YabujxZ.mjs";
-import { s as readMigrationsDir } from "../io-BHl0amF0.mjs";
+import { E as errorSnapshotMissing, f as errorInvalidJson, i as errorContractDeserializationFailed, l as errorHashNotInGraph, r as errorBundleNotFoundForGraphNode, t as MigrationToolsError, x as errorMissingFile } from "../errors-vFROOhCR.mjs";
+import { s as readMigrationsDir } from "../io-BGlPOt9b.mjs";
 import { t as EMPTY_CONTRACT_HASH } from "../constants-DWV9_o2Z.mjs";
-import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-kGBkIZDa.mjs";
-import { a as readRefsTolerant, t as HEAD_REF_NAME } from "../refs-BBKNL45K.mjs";
-import { c as spaceMigrationDirectory, i as RESERVED_SPACE_SUBDIR_NAMES, l as spaceRefsDirectory, r as APP_SPACE_ID, s as isValidSpaceId, t as listContractSpaceDirectories } from "../verify-contract-spaces-BJX5gqtD.mjs";
-import { n as readContractSpaceHeadRef, t as readContractSpaceContract } from "../read-contract-space-contract-BS5Oxbgw.mjs";
+import { n as isGraphNode } from "../graph-membership-BV23F1IV.mjs";
+import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-BMAqSfv9.mjs";
+import { a as readRefsTolerant, t as HEAD_REF_NAME } from "../refs-Ditzcs06.mjs";
+import { c as spaceMigrationDirectory, i as RESERVED_SPACE_SUBDIR_NAMES, l as spaceRefsDirectory, r as APP_SPACE_ID, s as isValidSpaceId, t as listContractSpaceDirectories } from "../verify-contract-spaces-3u7gzhqT.mjs";
+import { r as readRefSnapshot } from "../snapshot-CVg78oBp.mjs";
+import { n as readContractSpaceHeadRef, t as readContractSpaceContract } from "../read-contract-space-contract-BbcST3Lm.mjs";
+import { join } from "pathe";
+import { readFile } from "node:fs/promises";
 import { notOk, ok } from "@prisma-next/utils/result";
 import { elementCoordinates } from "@prisma-next/framework-components/ir";
 //#region src/aggregate/aggregate.ts
+function hasErrnoCode(error, code) {
+	return error instanceof Error && error.code === code;
+}
+function contractAtMemoKey(hash, refName) {
+	return `${hash}\0${refName ?? ""}`;
+}
+function deserializeContractAtPath(filePath, contractJson, deserializeContract) {
+	try {
+		return deserializeContract(contractJson);
+	} catch (error) {
+		if (MigrationToolsError.is(error)) throw error;
+		throw errorContractDeserializationFailed(filePath, error instanceof Error ? error.message : String(error));
+	}
+}
+async function readGraphNodeEndContract(packageDir, deserializeContract) {
+	const jsonPath = join(packageDir, "end-contract.json");
+	const dtsPath = join(packageDir, "end-contract.d.ts");
+	let rawJson;
+	try {
+		rawJson = await readFile(jsonPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile("end-contract.json", packageDir);
+		throw error;
+	}
+	let contractJson;
+	try {
+		contractJson = JSON.parse(rawJson);
+	} catch (error) {
+		throw errorInvalidJson(jsonPath, error instanceof Error ? error.message : String(error));
+	}
+	let contractDts;
+	try {
+		contractDts = await readFile(dtsPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile("end-contract.d.ts", packageDir);
+		throw error;
+	}
+	const contract = deserializeContractAtPath(jsonPath, contractJson, deserializeContract);
+	return {
+		contractJson,
+		contractDts,
+		contract
+	};
+}
+async function resolveContractAt(args) {
+	const { hash, opts, refsDir, packages, graph, deserializeContract } = args;
+	const refName = opts?.refName;
+	if (refName !== void 0) {
+		const snapshot = await readRefSnapshot(refsDir, refName);
+		if (snapshot) {
+			const jsonPath = join(refsDir, `${refName}.contract.json`);
+			return {
+				hash,
+				contractJson: snapshot.contract,
+				contractDts: snapshot.contractDts,
+				contract: deserializeContractAtPath(jsonPath, snapshot.contract, deserializeContract),
+				provenance: "snapshot"
+			};
+		}
+		if (isGraphNode(hash, graph)) return resolveGraphNodeContractAt({
+			hash,
+			packages,
+			deserializeContract,
+			explicitLabel: refName
+		});
+		throw errorSnapshotMissing(refName);
+	}
+	if (isGraphNode(hash, graph)) return resolveGraphNodeContractAt({
+		hash,
+		packages,
+		deserializeContract
+	});
+	throw errorHashNotInGraph(hash, graph);
+}
+async function resolveGraphNodeContractAt(args) {
+	const { hash, packages, deserializeContract, explicitLabel } = args;
+	const matchingBundle = packages.find((pkg) => pkg.metadata.to === hash);
+	if (!matchingBundle) throw errorBundleNotFoundForGraphNode(hash, explicitLabel);
+	const { contractJson, contractDts, contract } = await readGraphNodeEndContract(matchingBundle.dirPath, deserializeContract);
+	return {
+		hash,
+		contractJson,
+		contractDts,
+		contract,
+		provenance: "graph-node",
+		sourceDir: matchingBundle.dirPath
+	};
+}
 /**
 * Resolve a member's head ref, asserting it is present. The apply/verify
 * engine only runs after `checkIntegrity` has refused on `headRefMissing`,
@@ -21,31 +113,51 @@ function requireHeadRef(member) {
 	return member.headRef;
 }
 /**
-* Build a {@link ContractSpaceMember} with lazily-memoised `graph()` and
-* `contract()` facets.
+* Build a {@link ContractSpaceMember} with lazily-memoised `graph()`,
+* `contract()`, and `contractAt()` facets.
 *
 * `graph()` reconstructs the migration graph from `packages` on first
 * call and caches it. `contract()` calls `resolveContract` on first call
 * and caches the result; a throwing `resolveContract` (e.g. a missing or
 * undeserializable on-disk contract) re-throws on each call rather than
 * caching a value — `checkIntegrity` surfaces that as `contractUnreadable`.
+* `contractAt()` materializes the contract at an arbitrary graph node with
+* the same resolution order as plan-time ref resolution: ref snapshot first
+* (when `opts.refName` is set), else the matching package's `end-contract.*`.
 */
 function createContractSpaceMember(args) {
-	const { spaceId, packages, refs, headRef, resolveContract } = args;
+	const { spaceId, packages, refs, headRef, refsDir, resolveContract, deserializeContract } = args;
 	let graphMemo;
 	let contractMemo;
+	const contractAtMemo = /* @__PURE__ */ new Map();
+	function memberGraph() {
+		graphMemo ??= reconstructGraph(packages);
+		return graphMemo;
+	}
 	return {
 		spaceId,
 		packages,
 		refs,
 		headRef,
-		graph() {
-			graphMemo ??= reconstructGraph(packages);
-			return graphMemo;
-		},
+		graph: memberGraph,
 		contract() {
 			contractMemo ??= resolveContract();
 			return contractMemo;
+		},
+		async contractAt(hash, opts) {
+			const key = contractAtMemoKey(hash, opts?.refName);
+			const cached = contractAtMemo.get(key);
+			if (cached) return cached;
+			const result = await resolveContractAt({
+				hash,
+				opts,
+				refsDir,
+				packages,
+				graph: memberGraph(),
+				deserializeContract
+			});
+			contractAtMemo.set(key, result);
+			return result;
 		}
 	};
 }
@@ -253,7 +365,7 @@ function detailOf$1(error) {
 async function loadContractSpaceAggregate(input) {
 	const { migrationsDir, deserializeContract, appContract } = input;
 	const targetId = appContract.target;
-	const appState = await loadAppSpace(migrationsDir, appContract);
+	const appState = await loadAppSpace(migrationsDir, appContract, deserializeContract);
 	const extensionStates = await loadExtensionSpaces(migrationsDir, deserializeContract);
 	const spaces = [appState, ...extensionStates];
 	return createContractSpaceAggregate({
@@ -266,7 +378,7 @@ async function loadContractSpaceAggregate(input) {
 		}, opts)
 	});
 }
-async function loadAppSpace(migrationsDir, appContract) {
+async function loadAppSpace(migrationsDir, appContract, deserializeContract) {
 	const spaceDir = spaceMigrationDirectory(migrationsDir, APP_SPACE_ID);
 	const { packages, problems } = await readMigrationsDir(spaceDir);
 	const { refs, problems: refProblems } = await readRefsTolerant(spaceRefsDirectory(spaceDir));
@@ -279,7 +391,9 @@ async function loadAppSpace(migrationsDir, appContract) {
 				hash: appContract.storage.storageHash,
 				invariants: []
 			},
-			resolveContract: () => appContract
+			refsDir: spaceRefsDirectory(spaceDir),
+			resolveContract: () => appContract,
+			deserializeContract
 		}),
 		problems,
 		refProblems,
@@ -305,7 +419,9 @@ async function loadExtensionSpace(migrationsDir, spaceId, deserializeContract) {
 			packages,
 			refs,
 			headRef,
-			resolveContract: () => deserializeContract(rawContract())
+			refsDir: spaceRefsDirectory(spaceDir),
+			resolveContract: () => deserializeContract(rawContract()),
+			deserializeContract
 		}),
 		problems,
 		refProblems,