@prisma-next/cli 0.11.0-dev.55 → 0.11.0-dev.57

package/README.md

@@ -932,25 +932,26 @@ The `contract.output` field specifies the path to `contract.json`. This is the c
 
 ### `prisma-next migration plan`
 
-Plan a migration from contract changes. Compares the emitted contract against the latest on-disk migration state and produces a new migration package with the required operations. No database connection is needed — fully offline.
+Plan a migration from contract changes. Compares a starting contract against a destination contract and produces a new migration package with the required operations. No database connection is needed — fully offline.
 
 ```bash
-prisma-next migration plan [--config <path>] [--name <slug>] [--from <hash>] [--json] [-v] [-q] [--color/--no-color]
+prisma-next migration plan [--config <path>] [--name <slug>] [--from <contract>] [--to <contract>] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 **Options:**
 - `--config <path>`: Path to `prisma-next.config.ts`
 - `--name <slug>`: Name slug for the migration directory (default: `migration`)
-- `--from <hash>`: Explicit starting contract hash (overrides latest migration target detection)
+- `--from <contract>`: Starting contract reference (hash, prefix, ref name, migration directory, `<dir>^`, or filesystem path). Defaults to the `db` ref (greenfield when absent).
+- `--to <contract>`: Destination contract reference (same grammar as `--from`). Defaults to the emitted `contract.json`. Use `--to <migration-dir>^` to plan a rollback toward a predecessor state.
 - `--json`: Output as JSON object
 - `-q, --quiet`: Quiet mode (errors only)
 - `-v, --verbose`: Verbose output (debug info, timings)
 
 **What it does:**
-1. Loads config and reads `contract.json` (the "to" contract)
+1. Loads config and resolves the destination contract: `--to <contract>` if provided, otherwise `contract.json`
 2. Reads existing migrations from `config.migrations.dir` (default: `migrations/`)
-3. Determines the starting point: `--from <hash>` if provided, otherwise the latest migration target
-4. Diffs the starting contract against the new contract using the target's migration planner
+3. Determines the starting point: `--from <contract>` if provided, otherwise the `db` ref (greenfield when absent)
+4. Diffs the starting contract against the destination using the target's migration planner
 5. Scaffolds a new migration package: `migration.ts` (containing `placeholder(...)` lambdas for any data transforms), `migration.json` (with a content-addressed `migrationHash` over the planned ops, or over `[]` when the planner could not lower any calls because of placeholders), `ops.json` (the planned ops, or `[]` in the placeholder-blocked case), and contract bookends. The package is **always** fully attested — there is no draft state on disk.
 6. If the plan has unfilled `placeholder(...)` slots, the command returns a successful `pendingPlaceholders` envelope (a warning, not a failure) asking the developer to fill in the slots before re-emitting. The on-disk `ops.json` is `[]` and `migrationHash` is the hash of `(metadata, [])`, so applying the migration as-written will not advance the storage hash to the intended destination — the runner's destination-hash post-check surfaces this as a state mismatch. After filling in the placeholders, run `node migrations/<dir>/migration.ts` to re-emit `ops.json` and the corresponding `migrationHash`. `PN-MIG-2001` is raised only at self-emit time when a slot is still unfilled.
 
@@ -961,7 +962,7 @@ prisma-next migration plan [--config <path>] [--name <slug>] [--from <hash>] [--
 - `migrations/<dir>/start-contract.{json,d.ts}` — bookend from the "from" side (when applicable)
 - `migrations/<dir>/end-contract.{json,d.ts}` — bookend from the "to" side
 
-**Branching with `--from`:** Use `--from` to create a migration edge from a specific contract hash instead of the latest migration target. This enables branched migration graphs where multiple environments diverge from a common ancestor.
+**Branching with `--from` and `--to`:** Use `--from` to create a migration edge from a specific contract hash instead of the default starting point. Use `--to` to plan toward any resolved contract — including a rollback via `<migration-dir>^` — instead of the emitted contract. This enables branched migration graphs and arbitrary-target (including reverse) edges without editing contract source.
 
 ### `prisma-next migration show`
 
@@ -1027,6 +1028,7 @@ prisma-next migrate [--db <url>] [--to <contract>] [--config <path>] [--json] [-
 
 **Options:**
 - `--db <url>`: Database connection string (optional; defaults to `config.db.connection`)
+- `--to <contract>`: Target contract reference (hash, prefix, ref name, migration directory, `<dir>^`, or filesystem path). When omitted, applies toward the emitted `contract.json`. When `--to` resolves to an on-disk graph node, verification and apply use that bundle's `end-contract.json` — so a planned rollback or other arbitrary-target edge applies without editing contract source.
 - `--ref <name>`: Target a named ref from `migrations/refs.json` instead of the current contract hash
 - `--config <path>`: Path to `prisma-next.config.ts`
 - `--json`: Output as JSON object
@@ -1036,12 +1038,14 @@ prisma-next migrate [--db <url>] [--to <contract>] [--config <path>] [--json] [-
 **What it does:**
 1. Reads migration packages from `config.migrations.dir`. Every package is attested — there is no on-disk draft state. The loader (`readMigrationPackage` in `@prisma-next/migration-tools/io`) rehashes `(metadata, ops)` for each `MigrationPackage` it returns and confirms the result matches the stored `migrationHash`. If a package has been hand-edited or partially written since emit, the load fails with `MIGRATION.HASH_MISMATCH` pointing at the offending directory and asks the developer to re-run `node migrations/<dir>/migration.ts` (or restore from version control).
 2. Reconstructs the migration graph from all loaded packages
-3. Determines the destination hash: from `--ref` (via `refs.json`) or from `contract.json`
+3. Determines the destination hash and apply contract: from `--to` / `--ref`, or from `contract.json` when neither is supplied
 4. Connects to the database and reads the current marker hash
 5. Finds the shortest path from the marker hash to the destination using graph pathfinding
 6. Executes each pending migration in order using the target's `MigrationRunner`
 7. Each migration runs in its own transaction with prechecks, postchecks, and idempotency checks enabled
-8. After each migration, the runner verifies the schema and updates the marker/ledger
+8. After each migration, the runner runs the migration's post-checks and verifies the resulting state matches the target contract's storage hash, then updates the marker/ledger
+
+**Rollback workflow:** When no on-disk edge reaches the target (for example `migrate --to <migration-dir>^`), the command refuses with `MIGRATION.PATH_UNREACHABLE` and suggests planning the missing edge with `migration plan --from <current> --to <target> --name <slug>`, then re-running `migrate --to <target>`. No contract-source edit is required.
 
 **Config requirements:** Requires `driver` and `db.connection` (or `--db`). `migrations.dir` is optional and defaults to `migrations/`.
 

package/dist/{cli-errors-DFF1LlfU.mjs → cli-errors-DQY629C7.mjs}

@@ -123,22 +123,27 @@ function errorMarkerMismatch(markerHash, reachableHashes, graphTip) {
 }
 function errorPathUnreachable(failure) {
 	const meta = failure.meta ?? {};
-	const fromHash = typeof meta["fromHash"] === "string" ? meta["fromHash"] : null;
+	const fromHashMeta = typeof meta["fromHash"] === "string" ? meta["fromHash"] : null;
+	const planFromHash = fromHashMeta === "<empty>" ? null : fromHashMeta;
 	const targetHash = typeof meta["targetHash"] === "string" ? meta["targetHash"] : typeof meta["target"] === "string" ? meta["target"] : null;
 	const deadEnds = meta["deadEnds"];
 	const deadEndsSuffix = Array.isArray(deadEnds) && deadEnds.length > 0 ? ` Dead-ends: ${deadEnds.map(String).join(", ")}.` : "";
-	const planFix = (() => {
-		if (fromHash !== null && targetHash !== null) return `Run \`prisma-next migration plan --from ${fromHash} --to ${targetHash}\` to introduce the missing path.`;
-		if (targetHash !== null) return `Run \`prisma-next migration plan --to ${targetHash}\` to introduce the missing path.`;
-		if (fromHash !== null) return `Run \`prisma-next migration plan --from ${fromHash}\` to introduce the missing path.`;
-		return "Run `prisma-next migration plan` to introduce the missing path.";
+	const planCommand = (() => {
+		if (planFromHash !== null && targetHash !== null) return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
+		if (targetHash !== null) return `prisma-next migration plan --to ${targetHash} --name <slug>`;
+		if (planFromHash !== null) return `prisma-next migration plan --from ${planFromHash} --name <slug>`;
+		return "prisma-next migration plan";
 	})();
+	const applyCommand = targetHash !== null ? `prisma-next migrate --to ${targetHash}` : "prisma-next migrate";
 	return errorRuntime(failure.summary, {
-		why: failure.why ?? `Cannot reach target "${targetHash ?? "<unknown>"}" from current marker "${fromHash ?? "<unknown>"}".${deadEndsSuffix}`,
+		why: failure.why ?? `Cannot reach target "${targetHash ?? "<unknown>"}" from current marker "${fromHashMeta ?? "<unknown>"}".${deadEndsSuffix}`,
 		fix: [
-			"Run `prisma-next migration list` to see the on-disk graph.",
-			planFix,
-			"Run `prisma-next migration show <bundle>` for any bundle in the path you expected."
+			"Plan the missing edge, then apply it:",
+			`  1. ${planCommand}`,
+			`  2. ${applyCommand}`,
+			"A rollback (reverse) plan is expected to contain destructive (DROP) operations — review them before applying.",
+			"Narrower cases (rename inference, re-adding a NOT NULL column without a safe default, or a type change that needs data) may additionally need a hint in the planned migration.",
+			"Inspect the on-disk graph with `prisma-next migration list`, or `prisma-next migration show <bundle>` for any bundle in the path you expected."
 		].join("\n"),
 		meta: {
 			...meta,
@@ -212,4 +217,4 @@ function mapRefResolutionError(error) {
 //#endregion
 export { mapRefResolutionError as A, errorRuntime$1 as C, errorTargetMismatch as D, errorTargetMigrationNotSupported as E, errorUnexpected$1 as O, errorRunnerFailed as S, errorSpaceNotFound as T, errorPathUnreachable as _, errorContractValidationFailed as a, errorRefSetEmptySentinel as b, errorDriverRequired as c, errorInvalidOutputFormat as d, errorInvalidSpaceId as f, errorOutputFormatMutex as g, errorMigrationPlanningFailed as h, errorContractConfigMissing$1 as i, mapMigrationToolsError as k, errorFileNotFound as l, errorMarkerMissing as m, ERROR_CODE_DESTRUCTIVE_CHANGES as n, errorDatabaseConnectionRequired as o, errorMarkerMismatch as p, errorConfigValidation$1 as r, errorDestructiveChanges as s, CliStructuredError$1 as t, errorHashMismatch as u, errorPlanForgotTheFlag as v, errorSnapshotMissing as w, errorRefSetHashNotInGraph as x, errorRefSetBundleNotFound as y };
 
-//# sourceMappingURL=cli-errors-DFF1LlfU.mjs.map
+//# sourceMappingURL=cli-errors-DQY629C7.mjs.map

package/dist/{cli-errors-DFF1LlfU.mjs.map → cli-errors-DQY629C7.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"cli-errors-DFF1LlfU.mjs","names":[],"sources":["../src/utils/cli-errors.ts"],"sourcesContent":["/**\n * Re-export all domain error factories from @prisma-next/errors for convenience.\n * CLI-specific errors (e.g., Commander argument validation in the main CLI, or\n * clipanion parse errors in the migration-file CLI) can be added here if needed.\n */\nexport type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';\n\nimport {\n  CliStructuredError,\n  errorConfigFileNotFound,\n  errorConfigValidation,\n  errorContractConfigMissing,\n  errorContractMissingExtensionPacks,\n  errorContractValidationFailed,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorFamilyReadMarkerSqlRequired,\n  errorFileNotFound,\n  errorInvalidOutputFormat,\n  errorMigrationCliInvalidConfigArg,\n  errorMigrationCliUnknownFlag,\n  errorMigrationPlanningFailed,\n  errorOutputFormatMutex,\n  errorQueryRunnerFactoryRequired,\n  errorTargetMigrationNotSupported,\n  errorUnexpected,\n} from '@prisma-next/errors/control';\nimport { errorRuntime } from '@prisma-next/errors/execution';\nimport type { MigrationToolsError } from '@prisma-next/migration-tools/errors';\nimport type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';\nimport type { MigrationApplyFailure } from '../control-api/types';\n\nexport {\n  ERROR_CODE_DESTRUCTIVE_CHANGES,\n  errorDestructiveChanges,\n  errorHashMismatch,\n  errorMarkerMissing,\n  errorMarkerRequired,\n  errorRunnerFailed,\n  errorRuntime,\n  errorSchemaVerificationFailed,\n  errorTargetMismatch,\n} from '@prisma-next/errors/execution';\nexport {\n  errorMigrationFileMissing,\n  errorMigrationInvalidDefaultExport,\n  errorMigrationPlanNotArray,\n  errorUnfilledPlaceholder,\n  placeholder,\n} from '@prisma-next/errors/migration';\nexport {\n  CliStructuredError,\n  errorConfigFileNotFound,\n  errorConfigValidation,\n  errorContractConfigMissing,\n  errorContractMissingExtensionPacks,\n  errorContractValidationFailed,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorFamilyReadMarkerSqlRequired,\n  errorFileNotFound,\n  errorInvalidOutputFormat,\n  errorMigrationCliInvalidConfigArg,\n  errorMigrationCliUnknownFlag,\n  errorMigrationPlanningFailed,\n  errorOutputFormatMutex,\n  errorQueryRunnerFactoryRequired,\n  errorTargetMigrationNotSupported,\n  errorUnexpected,\n};\n\nexport function errorRefSetHashNotInGraph(\n  resolvedHash: string,\n  reachableHashes: readonly string[],\n  graphTipHash: string | null,\n): CliStructuredError {\n  const reachableList =\n    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';\n  const fix =\n    reachableHashes.length > 0\n      ? graphTipHash !== null\n        ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \\`prisma-next migration plan\\` to extend the graph.`\n        : 'Set the ref to a hash that appears in the migration graph.'\n      : 'Run `prisma-next migration plan` first.';\n  return errorRuntime(`Resolved contract hash is not in the migration graph: ${resolvedHash}`, {\n    why:\n      reachableHashes.length > 0\n        ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`\n        : 'The migration graph is empty — no hashes reachable.',\n    fix,\n    meta: {\n      code: 'MIGRATION.HASH_NOT_IN_GRAPH',\n      resolvedHash,\n      reachableHashes: [...reachableHashes],\n      ...(graphTipHash !== null ? { graphTipHash } : {}),\n    },\n  });\n}\n\nexport function errorRefSetEmptySentinel(hash: string): CliStructuredError {\n  return errorRuntime(`Cannot set ref to the empty-database sentinel: ${hash}`, {\n    why: 'The empty-database sentinel is a planner internal; it is not a valid ref target.',\n    fix: 'Set the ref to a contract hash from the migration graph, or use another ref name.',\n    meta: {\n      code: 'MIGRATION.REF_SET_EMPTY_SENTINEL',\n      hash,\n    },\n  });\n}\n\n/**\n * `--space <id>` was given a value that doesn't satisfy the contract-space\n * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before\n * any fs work — the input is syntactically rejected the same way an on-disk\n * directory with that name would be skipped by the enumerator.\n */\nexport function errorInvalidSpaceId(spaceId: string): CliStructuredError {\n  return errorRuntime(`Invalid contract space id: ${spaceId}`, {\n    why: 'Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).',\n    fix: 'Pass a space id that matches the directory naming rule, or omit --space to list every space.',\n    meta: {\n      code: 'MIGRATION.INVALID_SPACE_ID',\n      spaceId,\n    },\n  });\n}\n\n/**\n * `migration list --space <id>` was given a contract-space id that has no\n * directory under `migrations/`. Distinct from \"the space exists but is\n * empty\" — that path renders the empty-state line and exits 0 per the\n * slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`\n * does not exist on disk.\n *\n * `availableSpaces` lists the contract-space directory names actually\n * present, sorted lex-asc, so the diagnostic can suggest a near match\n * without making the user reach for `ls`.\n */\nexport function errorSpaceNotFound(\n  spaceId: string,\n  availableSpaces: readonly string[],\n): CliStructuredError {\n  const availableList =\n    availableSpaces.length > 0\n      ? availableSpaces.join(', ')\n      : '(none — no contract spaces on disk yet)';\n  const fix =\n    availableSpaces.length > 0\n      ? `Pick one of: ${availableList}. Run \\`prisma-next migration list\\` (no --space) to see every space's migrations.`\n      : 'Author a migration with `prisma-next migration new` to create the first contract-space directory.';\n  return errorRuntime(`Unknown contract space: ${spaceId}`, {\n    why: `No directory named \"${spaceId}\" exists under the migrations root.`,\n    fix,\n    meta: {\n      code: 'MIGRATION.SPACE_NOT_FOUND',\n      spaceId,\n      availableSpaces: [...availableSpaces],\n    },\n  });\n}\n\nexport function errorRefSetBundleNotFound(hash: string): CliStructuredError {\n  return errorRuntime(`No migration bundle matches graph-node hash ${hash}`, {\n    why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,\n    fix: 'Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.',\n    meta: {\n      code: 'MIGRATION.REF_SET_BUNDLE_NOT_FOUND',\n      hash,\n    },\n  });\n}\n\nexport function errorPlanForgotTheFlag(\n  resolvedHash: string,\n  reachableRefs: ReadonlyArray<{ readonly name: string; readonly hash: string }>,\n  graphTipHash: string | null,\n): CliStructuredError {\n  const reachableList =\n    reachableRefs.length > 0\n      ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(', ')\n      : '(none)';\n  const refFix =\n    reachableRefs.length > 0\n      ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(' or ')}.`\n      : graphTipHash !== null\n        ? `Run migration plan --from ${graphTipHash}.`\n        : 'Commit pending migrations first, then run migration plan.';\n  return errorRuntime(`Resolved from-hash is not in the migration graph: ${resolvedHash}`, {\n    why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,\n    fix: refFix,\n    meta: {\n      code: 'MIGRATION.HASH_NOT_IN_GRAPH',\n      resolvedHash,\n      reachableRefs: reachableRefs.map((r) => r.name),\n      ...(graphTipHash !== null ? { graphTipHash } : {}),\n    },\n  });\n}\n\nexport function errorSnapshotMissing(\n  identifier: string,\n  options?: { readonly viaRef?: boolean },\n): CliStructuredError {\n  const viaRef = options?.viaRef !== false;\n  const fix = viaRef\n    ? `Run \"prisma-next db update --advance-ref ${identifier}\" to repopulate the snapshot, or \"prisma-next ref delete ${identifier}\" to clear the orphan pointer.`\n    : `No contract source exists for hash \"${identifier}\" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;\n  return errorRuntime(\n    viaRef\n      ? `Ref \"${identifier}\" has no paired contract snapshot`\n      : `No contract source for from-hash \"${identifier}\"`,\n    {\n      why: viaRef\n        ? `Ref \"${identifier}\" exists but its paired snapshot files are missing.`\n        : `Hash \"${identifier}\" is not a graph node and no paired ref snapshot supplies a contract.`,\n      fix,\n      meta: {\n        code: 'MIGRATION.SNAPSHOT_MISSING',\n        identifier,\n        viaRef,\n      },\n    },\n  );\n}\n\nexport function errorMarkerMismatch(\n  markerHash: string,\n  reachableHashes: readonly string[],\n  graphTip: string | null,\n): CliStructuredError {\n  const reachableList =\n    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';\n  const planFromFix =\n    graphTip !== null\n      ? `Run \\`prisma-next migration plan --from ${graphTip}\\` if the live marker is canonical and the on-disk graph needs catching up.`\n      : 'Run `prisma-next migration plan` if the live marker is canonical and the on-disk graph needs catching up.';\n  return errorRuntime('Database marker is not reachable in the on-disk migration graph', {\n    why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,\n    fix: [\n      planFromFix,\n      `Run \\`prisma-next ref set db ${markerHash}\\` if the on-disk graph is canonical and the local \\`db\\` ref drifted.`,\n      'Investigate whether the database was migrated by an out-of-band process.',\n    ].join('\\n'),\n    meta: {\n      code: 'MIGRATION.MARKER_MISMATCH',\n      markerHash,\n      reachableHashes: [...reachableHashes],\n      ...(graphTip !== null ? { graphTip } : {}),\n    },\n  });\n}\n\nexport function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {\n  const meta = failure.meta ?? {};\n  const fromHash = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;\n  const targetHash =\n    typeof meta['targetHash'] === 'string'\n      ? meta['targetHash']\n      : typeof meta['target'] === 'string'\n        ? meta['target']\n        : null;\n  const deadEnds = meta['deadEnds'];\n  const deadEndsSuffix =\n    Array.isArray(deadEnds) && deadEnds.length > 0\n      ? ` Dead-ends: ${deadEnds.map(String).join(', ')}.`\n      : '';\n  const planFix = (() => {\n    if (fromHash !== null && targetHash !== null) {\n      return `Run \\`prisma-next migration plan --from ${fromHash} --to ${targetHash}\\` to introduce the missing path.`;\n    }\n    if (targetHash !== null) {\n      return `Run \\`prisma-next migration plan --to ${targetHash}\\` to introduce the missing path.`;\n    }\n    if (fromHash !== null) {\n      return `Run \\`prisma-next migration plan --from ${fromHash}\\` to introduce the missing path.`;\n    }\n    return 'Run `prisma-next migration plan` to introduce the missing path.';\n  })();\n  return errorRuntime(failure.summary, {\n    why:\n      failure.why ??\n      `Cannot reach target \"${targetHash ?? '<unknown>'}\" from current marker \"${fromHash ?? '<unknown>'}\".${deadEndsSuffix}`,\n    fix: [\n      'Run `prisma-next migration list` to see the on-disk graph.',\n      planFix,\n      'Run `prisma-next migration show <bundle>` for any bundle in the path you expected.',\n    ].join('\\n'),\n    meta: {\n      ...meta,\n      code: 'MIGRATION.PATH_UNREACHABLE',\n    },\n  });\n}\n\n/**\n * Maps a `MigrationToolsError` raised by the migration-tools loader/graph\n * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,\n * `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.\n *\n * The full `error.details` payload is forwarded into `meta` so machine\n * consumers (`--json`) see structural fields like `dir`, `storedHash`,\n * `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable\n * `code`. The user-visible `summary`/`why`/`fix` text is unchanged.\n *\n * Callers are expected to gate on `MigrationToolsError.is(error)` first\n * (mirroring the original inline pattern); non-`MigrationToolsError`\n * values are caller-classified (rethrow, wrap with command-specific\n * `errorUnexpected`, etc.).\n */\nexport function mapMigrationToolsError(error: MigrationToolsError): CliStructuredError {\n  return errorRuntime(error.message, {\n    why: error.why,\n    fix: error.fix,\n    meta: { code: error.code, ...(error.details ?? {}) },\n  });\n}\n\n/**\n * Maps a `RefResolutionError` from the contract/migration reference\n * resolver into a CLI structured error envelope.\n */\nexport function mapRefResolutionError(error: RefResolutionError): CliStructuredError {\n  switch (error.kind) {\n    case 'not-found':\n      return errorRuntime(`Not a known ${error.grammar} reference: \"${error.input}\"`, {\n        why: `No ${error.grammar} matching \"${error.input}\" exists in the migration graph or refs index.`,\n        fix:\n          error.grammar === 'contract'\n            ? 'Provide a valid contract hash, ref name, or migration directory name.'\n            : 'Provide a valid migration directory name or migration hash.',\n        meta: { input: error.input, grammar: error.grammar },\n      });\n    case 'ambiguous':\n      return errorRuntime(`Ambiguous ${error.grammar} reference: \"${error.input}\"`, {\n        why: `\"${error.input}\" matches multiple ${error.grammar}s: ${error.candidates.join(', ')}`,\n        fix: 'Provide a longer prefix or use the full hash to disambiguate.',\n        meta: { input: error.input, candidates: error.candidates, grammar: error.grammar },\n      });\n    case 'wrong-grammar':\n      return errorRuntime(error.message, {\n        why: error.message,\n        fix: error.fix,\n        meta: { input: error.input, expectedGrammar: error.expectedGrammar },\n      });\n    case 'invalid-format':\n      return errorRuntime(`Invalid reference format: \"${error.input}\"`, {\n        why: error.reason,\n        fix: 'Provide a valid contract hash, ref name, or migration directory name.',\n        meta: { input: error.input },\n      });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"cli-errors-DQY629C7.mjs","names":[],"sources":["../src/utils/cli-errors.ts"],"sourcesContent":["/**\n * Re-export all domain error factories from @prisma-next/errors for convenience.\n * CLI-specific errors (e.g., Commander argument validation in the main CLI, or\n * clipanion parse errors in the migration-file CLI) can be added here if needed.\n */\nexport type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';\n\nimport {\n  CliStructuredError,\n  errorConfigFileNotFound,\n  errorConfigValidation,\n  errorContractConfigMissing,\n  errorContractMissingExtensionPacks,\n  errorContractValidationFailed,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorFamilyReadMarkerSqlRequired,\n  errorFileNotFound,\n  errorInvalidOutputFormat,\n  errorMigrationCliInvalidConfigArg,\n  errorMigrationCliUnknownFlag,\n  errorMigrationPlanningFailed,\n  errorOutputFormatMutex,\n  errorQueryRunnerFactoryRequired,\n  errorTargetMigrationNotSupported,\n  errorUnexpected,\n} from '@prisma-next/errors/control';\nimport { errorRuntime } from '@prisma-next/errors/execution';\nimport type { MigrationToolsError } from '@prisma-next/migration-tools/errors';\nimport type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';\nimport type { MigrationApplyFailure } from '../control-api/types';\n\nexport {\n  ERROR_CODE_DESTRUCTIVE_CHANGES,\n  errorDestructiveChanges,\n  errorHashMismatch,\n  errorMarkerMissing,\n  errorMarkerRequired,\n  errorRunnerFailed,\n  errorRuntime,\n  errorSchemaVerificationFailed,\n  errorTargetMismatch,\n} from '@prisma-next/errors/execution';\nexport {\n  errorMigrationFileMissing,\n  errorMigrationInvalidDefaultExport,\n  errorMigrationPlanNotArray,\n  errorUnfilledPlaceholder,\n  placeholder,\n} from '@prisma-next/errors/migration';\nexport {\n  CliStructuredError,\n  errorConfigFileNotFound,\n  errorConfigValidation,\n  errorContractConfigMissing,\n  errorContractMissingExtensionPacks,\n  errorContractValidationFailed,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorFamilyReadMarkerSqlRequired,\n  errorFileNotFound,\n  errorInvalidOutputFormat,\n  errorMigrationCliInvalidConfigArg,\n  errorMigrationCliUnknownFlag,\n  errorMigrationPlanningFailed,\n  errorOutputFormatMutex,\n  errorQueryRunnerFactoryRequired,\n  errorTargetMigrationNotSupported,\n  errorUnexpected,\n};\n\nexport function errorRefSetHashNotInGraph(\n  resolvedHash: string,\n  reachableHashes: readonly string[],\n  graphTipHash: string | null,\n): CliStructuredError {\n  const reachableList =\n    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';\n  const fix =\n    reachableHashes.length > 0\n      ? graphTipHash !== null\n        ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \\`prisma-next migration plan\\` to extend the graph.`\n        : 'Set the ref to a hash that appears in the migration graph.'\n      : 'Run `prisma-next migration plan` first.';\n  return errorRuntime(`Resolved contract hash is not in the migration graph: ${resolvedHash}`, {\n    why:\n      reachableHashes.length > 0\n        ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`\n        : 'The migration graph is empty — no hashes reachable.',\n    fix,\n    meta: {\n      code: 'MIGRATION.HASH_NOT_IN_GRAPH',\n      resolvedHash,\n      reachableHashes: [...reachableHashes],\n      ...(graphTipHash !== null ? { graphTipHash } : {}),\n    },\n  });\n}\n\nexport function errorRefSetEmptySentinel(hash: string): CliStructuredError {\n  return errorRuntime(`Cannot set ref to the empty-database sentinel: ${hash}`, {\n    why: 'The empty-database sentinel is a planner internal; it is not a valid ref target.',\n    fix: 'Set the ref to a contract hash from the migration graph, or use another ref name.',\n    meta: {\n      code: 'MIGRATION.REF_SET_EMPTY_SENTINEL',\n      hash,\n    },\n  });\n}\n\n/**\n * `--space <id>` was given a value that doesn't satisfy the contract-space\n * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before\n * any fs work — the input is syntactically rejected the same way an on-disk\n * directory with that name would be skipped by the enumerator.\n */\nexport function errorInvalidSpaceId(spaceId: string): CliStructuredError {\n  return errorRuntime(`Invalid contract space id: ${spaceId}`, {\n    why: 'Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).',\n    fix: 'Pass a space id that matches the directory naming rule, or omit --space to list every space.',\n    meta: {\n      code: 'MIGRATION.INVALID_SPACE_ID',\n      spaceId,\n    },\n  });\n}\n\n/**\n * `migration list --space <id>` was given a contract-space id that has no\n * directory under `migrations/`. Distinct from \"the space exists but is\n * empty\" — that path renders the empty-state line and exits 0 per the\n * slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`\n * does not exist on disk.\n *\n * `availableSpaces` lists the contract-space directory names actually\n * present, sorted lex-asc, so the diagnostic can suggest a near match\n * without making the user reach for `ls`.\n */\nexport function errorSpaceNotFound(\n  spaceId: string,\n  availableSpaces: readonly string[],\n): CliStructuredError {\n  const availableList =\n    availableSpaces.length > 0\n      ? availableSpaces.join(', ')\n      : '(none — no contract spaces on disk yet)';\n  const fix =\n    availableSpaces.length > 0\n      ? `Pick one of: ${availableList}. Run \\`prisma-next migration list\\` (no --space) to see every space's migrations.`\n      : 'Author a migration with `prisma-next migration new` to create the first contract-space directory.';\n  return errorRuntime(`Unknown contract space: ${spaceId}`, {\n    why: `No directory named \"${spaceId}\" exists under the migrations root.`,\n    fix,\n    meta: {\n      code: 'MIGRATION.SPACE_NOT_FOUND',\n      spaceId,\n      availableSpaces: [...availableSpaces],\n    },\n  });\n}\n\nexport function errorRefSetBundleNotFound(hash: string): CliStructuredError {\n  return errorRuntime(`No migration bundle matches graph-node hash ${hash}`, {\n    why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,\n    fix: 'Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.',\n    meta: {\n      code: 'MIGRATION.REF_SET_BUNDLE_NOT_FOUND',\n      hash,\n    },\n  });\n}\n\nexport function errorPlanForgotTheFlag(\n  resolvedHash: string,\n  reachableRefs: ReadonlyArray<{ readonly name: string; readonly hash: string }>,\n  graphTipHash: string | null,\n): CliStructuredError {\n  const reachableList =\n    reachableRefs.length > 0\n      ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(', ')\n      : '(none)';\n  const refFix =\n    reachableRefs.length > 0\n      ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(' or ')}.`\n      : graphTipHash !== null\n        ? `Run migration plan --from ${graphTipHash}.`\n        : 'Commit pending migrations first, then run migration plan.';\n  return errorRuntime(`Resolved from-hash is not in the migration graph: ${resolvedHash}`, {\n    why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,\n    fix: refFix,\n    meta: {\n      code: 'MIGRATION.HASH_NOT_IN_GRAPH',\n      resolvedHash,\n      reachableRefs: reachableRefs.map((r) => r.name),\n      ...(graphTipHash !== null ? { graphTipHash } : {}),\n    },\n  });\n}\n\nexport function errorSnapshotMissing(\n  identifier: string,\n  options?: { readonly viaRef?: boolean },\n): CliStructuredError {\n  const viaRef = options?.viaRef !== false;\n  const fix = viaRef\n    ? `Run \"prisma-next db update --advance-ref ${identifier}\" to repopulate the snapshot, or \"prisma-next ref delete ${identifier}\" to clear the orphan pointer.`\n    : `No contract source exists for hash \"${identifier}\" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;\n  return errorRuntime(\n    viaRef\n      ? `Ref \"${identifier}\" has no paired contract snapshot`\n      : `No contract source for from-hash \"${identifier}\"`,\n    {\n      why: viaRef\n        ? `Ref \"${identifier}\" exists but its paired snapshot files are missing.`\n        : `Hash \"${identifier}\" is not a graph node and no paired ref snapshot supplies a contract.`,\n      fix,\n      meta: {\n        code: 'MIGRATION.SNAPSHOT_MISSING',\n        identifier,\n        viaRef,\n      },\n    },\n  );\n}\n\nexport function errorMarkerMismatch(\n  markerHash: string,\n  reachableHashes: readonly string[],\n  graphTip: string | null,\n): CliStructuredError {\n  const reachableList =\n    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';\n  const planFromFix =\n    graphTip !== null\n      ? `Run \\`prisma-next migration plan --from ${graphTip}\\` if the live marker is canonical and the on-disk graph needs catching up.`\n      : 'Run `prisma-next migration plan` if the live marker is canonical and the on-disk graph needs catching up.';\n  return errorRuntime('Database marker is not reachable in the on-disk migration graph', {\n    why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,\n    fix: [\n      planFromFix,\n      `Run \\`prisma-next ref set db ${markerHash}\\` if the on-disk graph is canonical and the local \\`db\\` ref drifted.`,\n      'Investigate whether the database was migrated by an out-of-band process.',\n    ].join('\\n'),\n    meta: {\n      code: 'MIGRATION.MARKER_MISMATCH',\n      markerHash,\n      reachableHashes: [...reachableHashes],\n      ...(graphTip !== null ? { graphTip } : {}),\n    },\n  });\n}\n\nexport function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {\n  const meta = failure.meta ?? {};\n  const fromHashMeta = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;\n  // `buildPathNotFoundFailure` uses this sentinel in meta when the live marker is null.\n  const planFromHash = fromHashMeta === '<empty>' ? null : fromHashMeta;\n  const targetHash =\n    typeof meta['targetHash'] === 'string'\n      ? meta['targetHash']\n      : typeof meta['target'] === 'string'\n        ? meta['target']\n        : null;\n  const deadEnds = meta['deadEnds'];\n  const deadEndsSuffix =\n    Array.isArray(deadEnds) && deadEnds.length > 0\n      ? ` Dead-ends: ${deadEnds.map(String).join(', ')}.`\n      : '';\n  // Plan-then-apply recovery. The planner destination is the missing edge's\n  // target; `migration plan --to` (built for arbitrary targets) makes this a\n  // real command, so the diagnostic that sends you here is now honest.\n  const planCommand = (() => {\n    if (planFromHash !== null && targetHash !== null) {\n      return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;\n    }\n    if (targetHash !== null) {\n      return `prisma-next migration plan --to ${targetHash} --name <slug>`;\n    }\n    if (planFromHash !== null) {\n      return `prisma-next migration plan --from ${planFromHash} --name <slug>`;\n    }\n    return 'prisma-next migration plan';\n  })();\n  const applyCommand =\n    targetHash !== null ? `prisma-next migrate --to ${targetHash}` : 'prisma-next migrate';\n  return errorRuntime(failure.summary, {\n    why:\n      failure.why ??\n      `Cannot reach target \"${targetHash ?? '<unknown>'}\" from current marker \"${fromHashMeta ?? '<unknown>'}\".${deadEndsSuffix}`,\n    fix: [\n      'Plan the missing edge, then apply it:',\n      `  1. ${planCommand}`,\n      `  2. ${applyCommand}`,\n      'A rollback (reverse) plan is expected to contain destructive (DROP) operations — review them before applying.',\n      'Narrower cases (rename inference, re-adding a NOT NULL column without a safe default, or a type change that needs data) may additionally need a hint in the planned migration.',\n      'Inspect the on-disk graph with `prisma-next migration list`, or `prisma-next migration show <bundle>` for any bundle in the path you expected.',\n    ].join('\\n'),\n    meta: {\n      ...meta,\n      code: 'MIGRATION.PATH_UNREACHABLE',\n    },\n  });\n}\n\n/**\n * Maps a `MigrationToolsError` raised by the migration-tools loader/graph\n * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,\n * `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.\n *\n * The full `error.details` payload is forwarded into `meta` so machine\n * consumers (`--json`) see structural fields like `dir`, `storedHash`,\n * `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable\n * `code`. The user-visible `summary`/`why`/`fix` text is unchanged.\n *\n * Callers are expected to gate on `MigrationToolsError.is(error)` first\n * (mirroring the original inline pattern); non-`MigrationToolsError`\n * values are caller-classified (rethrow, wrap with command-specific\n * `errorUnexpected`, etc.).\n */\nexport function mapMigrationToolsError(error: MigrationToolsError): CliStructuredError {\n  return errorRuntime(error.message, {\n    why: error.why,\n    fix: error.fix,\n    meta: { code: error.code, ...(error.details ?? {}) },\n  });\n}\n\n/**\n * Maps a `RefResolutionError` from the contract/migration reference\n * resolver into a CLI structured error envelope.\n */\nexport function mapRefResolutionError(error: RefResolutionError): CliStructuredError {\n  switch (error.kind) {\n    case 'not-found':\n      return errorRuntime(`Not a known ${error.grammar} reference: \"${error.input}\"`, {\n        why: `No ${error.grammar} matching \"${error.input}\" exists in the migration graph or refs index.`,\n        fix:\n          error.grammar === 'contract'\n            ? 'Provide a valid contract hash, ref name, or migration directory name.'\n            : 'Provide a valid migration directory name or migration hash.',\n        meta: { input: error.input, grammar: error.grammar },\n      });\n    case 'ambiguous':\n      return errorRuntime(`Ambiguous ${error.grammar} reference: \"${error.input}\"`, {\n        why: `\"${error.input}\" matches multiple ${error.grammar}s: ${error.candidates.join(', ')}`,\n        fix: 'Provide a longer prefix or use the full hash to disambiguate.',\n        meta: { input: error.input, candidates: error.candidates, grammar: error.grammar },\n      });\n    case 'wrong-grammar':\n      return errorRuntime(error.message, {\n        why: error.message,\n        fix: error.fix,\n        meta: { input: error.input, expectedGrammar: error.expectedGrammar },\n      });\n    case 'invalid-format':\n      return errorRuntime(`Invalid reference format: \"${error.input}\"`, {\n        why: error.reason,\n        fix: 'Provide a valid contract hash, ref name, or migration directory name.',\n        meta: { input: error.input },\n      });\n  }\n}\n"],"mappings":"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"}

package/dist/cli.mjs

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
-import { E as formatRootHelp, T as formatCommandHelp, _ as parseGlobalFlags, b as installShutdownHandlers, d as setCommandDescriptions, f as setCommandExamples, t as addGlobalOptions, v as parseGlobalFlagsOrExit, w as isCI } from "./command-helpers-4UNsRRc4.mjs";
-import { t as createContractEmitCommand } from "./contract-emit-CuUzzM46.mjs";
-import { t as createContractInferCommand } from "./contract-infer-C98ZaRhp.mjs";
+import { E as formatRootHelp, T as formatCommandHelp, _ as parseGlobalFlags, b as installShutdownHandlers, d as setCommandDescriptions, f as setCommandExamples, t as addGlobalOptions, v as parseGlobalFlagsOrExit, w as isCI } from "./command-helpers-DTpEJCgI.mjs";
+import { t as createContractEmitCommand } from "./contract-emit-CS3vF-w9.mjs";
+import { t as createContractInferCommand } from "./contract-infer-BtefFYF-.mjs";
 import { createDbInitCommand } from "./commands/db-init.mjs";
 import { createDbSchemaCommand } from "./commands/db-schema.mjs";
 import { createDbSignCommand } from "./commands/db-sign.mjs";
 import { createDbUpdateCommand } from "./commands/db-update.mjs";
-import { t as createDbVerifyCommand } from "./db-verify-BWl1Yxi-.mjs";
+import { t as createDbVerifyCommand } from "./db-verify-aHw2nzH2.mjs";
 import { createMigrateCommand } from "./commands/migrate.mjs";
-import { t as createMigrationCheckCommand } from "./migration-check-DoskM1nB.mjs";
+import { t as createMigrationCheckCommand } from "./migration-check-BFdael8w.mjs";
 import { createMigrationGraphCommand } from "./commands/migration-graph.mjs";
-import { t as createMigrationListCommand } from "./migration-list-B2-iQ5Jd.mjs";
+import { t as createMigrationListCommand } from "./migration-list-hj86sCtZ.mjs";
 import { createMigrationLogCommand } from "./commands/migration-log.mjs";
 import { createMigrationNewCommand } from "./commands/migration-new.mjs";
-import { t as createMigrationPlanCommand } from "./migration-plan-BqmIKQpZ.mjs";
+import { t as createMigrationPlanCommand } from "./migration-plan-Bt6wxUIv.mjs";
 import { createMigrationShowCommand } from "./commands/migration-show.mjs";
 import { createMigrationStatusCommand } from "./commands/migration-status.mjs";
 import { createRefCommand } from "./commands/ref.mjs";
@@ -24,7 +24,7 @@ import { fileURLToPath } from "node:url";
 import { readUserConfig, resolveGating, runTelemetry } from "@prisma-next/cli-telemetry";
 import { distance } from "closest-match";
 //#region package.json
-var version = "0.11.0-dev.55";
+var version = "0.11.0-dev.57";
 //#endregion
 //#region src/utils/telemetry.ts
 /**
@@ -412,7 +412,7 @@ Exit codes (see CLI Style Guide § Exit Codes):
 		"prisma-next init --no-skill                                         # skip the skills install (air-gapped / restricted env)"
 	]);
 	return addGlobalOptions(command).option("--target <db>", "Database target: postgres or mongodb").option("--authoring <style>", "Schema authoring style: psl or typescript").option("--schema-path <path>", `Where to write the starter schema (default: ${defaultSchemaPath("psl")})`).option("--force", "Overwrite an existing scaffold without prompting").option("--write-env", "Write a .env file from .env.example (gitignored; default: only .env.example)").option("--probe-db", "Connect to DATABASE_URL once and check the server version against the target minimum (opt-in; off by default)").option("--strict-probe", "Treat a failed --probe-db as fatal (no-op without --probe-db; init is offline-by-default)").option("--no-install", "Skip dependency installation and contract emission").option("--no-skill", "Skip Prisma Next skills install (air-gapped CI, restricted registries, etc.)").action(async (options, actionCommand) => {
-		const { runInit } = await import("./init-C7PvN163.mjs");
+		const { runInit } = await import("./init-DOE4Q9YK.mjs");
 		const flags = parseGlobalFlagsOrExit(options);
 		const canPrompt = deriveCanPrompt({
 			flagsInteractive: flags.interactive,

package/dist/{client-5uvDppD8.mjs → client-Ls2SAhrZ.mjs}

@@ -1,7 +1,7 @@
-import { S as errorRunnerFailed, t as CliStructuredError } from "./cli-errors-DFF1LlfU.mjs";
-import { t as assertFrameworkComponentsCompatible } from "./framework-components-DTcjouhS.mjs";
+import { S as errorRunnerFailed, t as CliStructuredError } from "./cli-errors-DQY629C7.mjs";
+import { t as assertFrameworkComponentsCompatible } from "./framework-components-BwuEBcyk.mjs";
 import { t as enrichContract } from "./contract-enrichment-XmUPhmsS.mjs";
-import { t as buildContractSpaceAggregate } from "./contract-space-aggregate-loader-CVHGuA35.mjs";
+import { t as buildContractSpaceAggregate } from "./contract-space-aggregate-loader-DX_1n2SA.mjs";
 import { emit } from "@prisma-next/emitter";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { notOk, ok } from "@prisma-next/utils/result";
@@ -965,11 +965,19 @@ function buildSuccess(args) {
 		...pathDecision !== void 0 ? { pathDecision } : {}
 	};
 }
+/**
+* Build the `neverPlanned` failure raised when a contract space has no on-disk
+* migration graph but migrate was asked to reach a target hash. The `why`
+* states only the condition; the recovery sequence is composed by
+* `errorPathUnreachable`'s `fix`.
+*
+* @internal Exported for testing only.
+*/
 function buildNeverPlannedFailure(spaceId, targetHash) {
 	return {
 		code: "MIGRATION_PATH_NOT_FOUND",
 		summary: `No on-disk migrations for contract space "${spaceId}"`,
-		why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}". Run \`prisma-next migration plan\` first to materialise the path.`,
+		why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}".`,
 		meta: {
 			spaceId,
 			target: targetHash,
@@ -977,12 +985,22 @@ function buildNeverPlannedFailure(spaceId, targetHash) {
 		}
 	};
 }
+/**
+* Build the `pathUnreachable` failure raised when an emitted contract has no
+* on-disk migration edge from the current marker to the target. The `why`
+* states only the condition (no edge between the two named states, and migrate
+* replays edges rather than inventing them); the recovery sequence — plan the
+* edge, then re-apply — is composed by `errorPathUnreachable`'s `fix`, so the
+* two read as one non-redundant plan-then-apply story.
+*
+* @internal Exported for testing only.
+*/
 function buildPathNotFoundFailure(spaceId, marker, targetHash) {
 	const fromHash = marker?.storageHash ?? "<empty>";
 	return {
 		code: "MIGRATION_PATH_NOT_FOUND",
 		summary: spaceId === "app" ? "Current contract has no planned migration path" : `Current contract has no planned migration path for contract space "${spaceId}"`,
-		why: `Cannot reach target "${targetHash}" from current marker "${fromHash}" in space "${spaceId}". The on-disk migration graph for this space does not connect the two states. Run \`prisma-next migration plan\` to materialise the path.`,
+		why: `No migration edge connects the current state "${fromHash}" to the target "${targetHash}" in contract space "${spaceId}". The on-disk migration graph does not join the two, and migrate replays existing edges — it never invents one.`,
 		meta: {
 			spaceId,
 			fromHash,
@@ -1483,4 +1501,4 @@ var ControlClientImpl = class {
 //#endregion
 export { ContractValidationError as a, executeDbInit as i, executeDbVerify as n, executeDbUpdate as r, createControlClient as t };
 
-//# sourceMappingURL=client-5uvDppD8.mjs.map
+//# sourceMappingURL=client-Ls2SAhrZ.mjs.map