@prisma-next/cli 0.15.0 → 0.16.0-dev.2

package/src/commands/init/errors.ts

@@ -6,8 +6,7 @@ import { CliStructuredError } from '../../utils/cli-errors';
  * the user was never given the choice — `--force` is the contract.
  */
 export function errorInitReinitNeedsForce(): CliStructuredError {
-  return new CliStructuredError('5002', 'Project is already initialized', {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_REINIT_NEEDS_FORCE', 'Project is already initialized', {
     why: 'A `prisma-next.config.ts` already exists in this directory. Re-running `init` would overwrite the scaffolded files; in non-interactive mode `init` will not do that without `--force`.',
     fix: 'Pass `--force` to overwrite the existing scaffold, or run `init` interactively to confirm.',
     docsUrl: 'https://prisma-next.dev/docs/cli/init',
@@ -42,8 +41,7 @@ export function errorInitMissingFlags(options: {
       }
     })
     .join(' ');
-  return new CliStructuredError('5003', 'Missing required flags', {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_MISSING_FLAGS', 'Missing required flags', {
     why: `${options.why} Missing required flag(s): ${flagList}.`,
     fix: `Re-run with the missing flag(s) supplied, e.g. \`prisma-next init --yes ${fixList}\`. Use \`prisma-next init --help\` to see every flag.`,
     docsUrl: 'https://prisma-next.dev/docs/cli/init',
@@ -60,13 +58,16 @@ export function errorInitInvalidFlagValue(options: {
   readonly value: string;
   readonly allowed: readonly string[];
 }): CliStructuredError {
-  return new CliStructuredError('5004', `Invalid value for --${options.flag}`, {
-    domain: 'CLI',
-    why: `\`--${options.flag} ${options.value}\` is not one of: ${options.allowed.join(', ')}.`,
-    fix: `Use one of: ${options.allowed.map((v) => `--${options.flag} ${v}`).join(', ')}.`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
-    meta: { flag: options.flag, value: options.value, allowed: options.allowed },
-  });
+  return new CliStructuredError(
+    'CLI.INIT_INVALID_FLAG_VALUE',
+    `Invalid value for --${options.flag}`,
+    {
+      why: `\`--${options.flag} ${options.value}\` is not one of: ${options.allowed.join(', ')}.`,
+      fix: `Use one of: ${options.allowed.map((v) => `--${options.flag} ${v}`).join(', ')}.`,
+      docsUrl: 'https://prisma-next.dev/docs/cli/init',
+      meta: { flag: options.flag, value: options.value, allowed: options.allowed },
+    },
+  );
 }
 
 /**
@@ -81,23 +82,26 @@ export function errorInitAuthoringSchemaPathMismatch(options: {
   readonly expectedExtension: string;
 }): CliStructuredError {
   const expectedAuthoring = options.expectedExtension === '.ts' ? 'typescript' : 'psl';
-  return new CliStructuredError('5014', 'Authoring and schema path do not match', {
-    domain: 'CLI',
-    why:
-      `\`--authoring ${options.authoring}\` requires a schema file ending in ${options.expectedExtension}, ` +
-      `but \`--schema-path ${options.schemaPath}\` ends in ${options.actualExtension}.`,
-    fix:
-      `Use a matching pair, for example \`--authoring ${expectedAuthoring} --schema-path <path>${options.expectedExtension}\`, ` +
-      'or change `--authoring` to match the path you supplied. ' +
-      'You can also omit `--schema-path` to use the default for the chosen authoring.',
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
-    meta: {
-      authoring: options.authoring,
-      schemaPath: options.schemaPath,
-      actualExtension: options.actualExtension,
-      expectedExtension: options.expectedExtension,
+  return new CliStructuredError(
+    'CLI.INIT_AUTHORING_SCHEMA_PATH_MISMATCH',
+    'Authoring and schema path do not match',
+    {
+      why:
+        `\`--authoring ${options.authoring}\` requires a schema file ending in ${options.expectedExtension}, ` +
+        `but \`--schema-path ${options.schemaPath}\` ends in ${options.actualExtension}.`,
+      fix:
+        `Use a matching pair, for example \`--authoring ${expectedAuthoring} --schema-path <path>${options.expectedExtension}\`, ` +
+        'or change `--authoring` to match the path you supplied. ' +
+        'You can also omit `--schema-path` to use the default for the chosen authoring.',
+      docsUrl: 'https://prisma-next.dev/docs/cli/init',
+      meta: {
+        authoring: options.authoring,
+        schemaPath: options.schemaPath,
+        actualExtension: options.actualExtension,
+        expectedExtension: options.expectedExtension,
+      },
     },
-  });
+  );
 }
 
 /**
@@ -108,8 +112,7 @@ export function errorInitAuthoringSchemaPathMismatch(options: {
  * 3 (USER_ABORTED).
  */
 export function errorInitUserAborted(): CliStructuredError {
-  return new CliStructuredError('5006', 'Init cancelled', {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_USER_ABORTED', 'Init cancelled', {
     why: 'The interactive prompt was cancelled before all required inputs were supplied. No files were modified.',
     fix: 'Re-run `prisma-next init` and complete the prompts, or pass the required inputs as flags (see `--help`) for a non-interactive run.',
     severity: 'info',
@@ -125,12 +128,15 @@ export function errorInitUserAborted(): CliStructuredError {
  * mode is supposed to prevent.
  */
 export function errorInitStrictProbeWithoutProbe(): CliStructuredError {
-  return new CliStructuredError('5005', '`--strict-probe` requires `--probe-db`', {
-    domain: 'CLI',
-    why: '`--strict-probe` only changes how a *failed* probe is reported; without `--probe-db` no probe is attempted in the first place. (`init` is offline-by-default — it never opens a connection to your database without explicit consent.)',
-    fix: 'Add `--probe-db` to opt in to the probe, or drop `--strict-probe` if you do not need the version check.',
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
-  });
+  return new CliStructuredError(
+    'CLI.INIT_STRICT_PROBE_WITHOUT_PROBE',
+    '`--strict-probe` requires `--probe-db`',
+    {
+      why: '`--strict-probe` only changes how a *failed* probe is reported; without `--probe-db` no probe is attempted in the first place. (`init` is offline-by-default — it never opens a connection to your database without explicit consent.)',
+      fix: 'Add `--probe-db` to opt in to the probe, or drop `--strict-probe` if you do not need the version check.',
+      docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    },
+  );
 }
 
 /**
@@ -152,8 +158,7 @@ export function errorInitInstallFailed(options: {
     trimmed.length === 0
       ? 'The package manager exited with an error and no recoverable fallback applied.'
       : `The package manager exited with: ${trimmed[0]}`;
-  return new CliStructuredError('5007', 'Failed to install dependencies', {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_INSTALL_FAILED', 'Failed to install dependencies', {
     why,
     fix: `Install manually:\n  ${options.addCommand}\n  ${options.addDevCommand}\nThen run \`${options.emitCommand}\` to emit the contract.`,
     docsUrl: 'https://prisma-next.dev/docs/cli/init',
@@ -179,8 +184,7 @@ export function errorInitInvalidManifest(options: {
   readonly path: string;
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('5010', `Failed to parse ${options.path}`, {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_INVALID_MANIFEST', `Failed to parse ${options.path}`, {
     why: `\`${options.path}\` is not valid JSON: ${options.cause}`,
     fix: `Fix the JSON syntax in \`${options.path}\` (a missing comma or unbalanced brace is the most common cause), then re-run \`prisma-next init\`.`,
     docsUrl: 'https://prisma-next.dev/docs/cli/init',
@@ -206,8 +210,7 @@ export function errorInitInvalidTsconfig(options: {
   readonly path: string;
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('5011', `Failed to parse ${options.path}`, {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_INVALID_TSCONFIG', `Failed to parse ${options.path}`, {
     why: `\`${options.path}\` is not valid JSON or JSONC: ${options.cause}`,
     fix: `Fix the syntax in \`${options.path}\` and re-run \`prisma-next init\`. \`init\` accepts JSONC (comments and trailing commas) but cannot recover from unbalanced braces or missing commas.`,
     docsUrl: 'https://prisma-next.dev/docs/cli/init',
@@ -233,8 +236,7 @@ export function errorInitProbeFailed(options: {
   readonly cause: string;
   readonly filesWritten: readonly string[];
 }): CliStructuredError {
-  return new CliStructuredError('5012', 'Database probe failed', {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_PROBE_FAILED', 'Database probe failed', {
     why: `\`--probe-db\` could not complete and \`--strict-probe\` was set: ${options.cause}`,
     fix: 'Confirm `DATABASE_URL` points at a reachable server, or drop `--strict-probe` to treat probe failures as warnings.',
     docsUrl: 'https://prisma-next.dev/docs/cli/init',
@@ -256,8 +258,7 @@ export function errorInitEmitFailed(options: {
   readonly filesWritten: readonly string[];
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('5008', 'Failed to emit contract', {
-    domain: 'CLI',
+  return new CliStructuredError('CLI.INIT_EMIT_FAILED', 'Failed to emit contract', {
     why: `\`prisma-next contract emit\` failed: ${options.cause}`,
     fix: `Inspect your contract file, fix the underlying issue, then re-run \`${options.emitCommand}\`. Pass \`-v\` for the full error envelope.`,
     docsUrl: 'https://prisma-next.dev/docs/cli/contract-emit',
@@ -284,18 +285,21 @@ export function errorInitSkillInstallFailed(options: {
   readonly filesWritten: readonly string[];
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('5013', 'Failed to install Prisma Next skills', {
-    domain: 'CLI',
-    why: `\`${options.skillInstallCommand}\` exited with an error: ${options.cause}`,
-    fix:
-      'Either:\n' +
-      `  - Re-run \`prisma-next init --no-skill${options.filesWritten.length > 0 ? ' --force' : ''}\` to skip the skill install for this run, or\n` +
-      `  - Fix the underlying issue (network, npm registry, \`npx skills\` on PATH) and install manually:\n      ${options.skillInstallCommand}`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init#skills',
-    meta: {
-      filesWritten: options.filesWritten,
-      skillInstallCommand: options.skillInstallCommand,
-      cause: options.cause,
+  return new CliStructuredError(
+    'CLI.INIT_SKILL_INSTALL_FAILED',
+    'Failed to install Prisma Next skills',
+    {
+      why: `\`${options.skillInstallCommand}\` exited with an error: ${options.cause}`,
+      fix:
+        'Either:\n' +
+        `  - Re-run \`prisma-next init --no-skill${options.filesWritten.length > 0 ? ' --force' : ''}\` to skip the skill install for this run, or\n` +
+        `  - Fix the underlying issue (network, npm registry, \`npx skills\` on PATH) and install manually:\n      ${options.skillInstallCommand}`,
+      docsUrl: 'https://prisma-next.dev/docs/cli/init#skills',
+      meta: {
+        filesWritten: options.filesWritten,
+        skillInstallCommand: options.skillInstallCommand,
+        cause: options.cause,
+      },
     },
-  });
+  );
 }

package/src/commands/init/init.ts

@@ -534,18 +534,21 @@ export async function runInit(
   if (validated instanceof Error || (validated as { problems?: unknown }).problems !== undefined) {
     // Route through `emitError` rather than throwing: the bare throw
     // bypassed `--json` envelope formatting and `exitCodeForError`, so a
-    // 5009 regression would surface as an uncaught exception in
-    // commander instead of the documented `INTERNAL_ERROR` envelope on
-    // the right channel.
+    // CLI.INIT_INVALID_OUTPUT_DOCUMENT regression would surface as an
+    // uncaught exception in commander instead of the documented
+    // `INTERNAL_ERROR` envelope on the right channel.
     return emitError(
       ui,
       flags,
-      new CliStructuredError('5009', 'Init produced an invalid output document', {
-        domain: 'CLI',
-        why: `The success document failed schema validation: ${String(validated)}`,
-        fix: 'This is a bug in prisma-next. Please report it with the full `-v` output.',
-        docsUrl: 'https://prisma-next.dev/docs/cli/init',
-      }),
+      new CliStructuredError(
+        'CLI.INIT_INVALID_OUTPUT_DOCUMENT',
+        'Init produced an invalid output document',
+        {
+          why: `The success document failed schema validation: ${String(validated)}`,
+          fix: 'This is a bug in prisma-next. Please report it with the full `-v` output.',
+          docsUrl: 'https://prisma-next.dev/docs/cli/init',
+        },
+      ),
     );
   }
 
@@ -582,10 +585,10 @@ function emitError(ui: TerminalUI, flags: GlobalFlags, error: CliStructuredError
  * Maps a structured init error to its documented exit code. Centralised so
  * the error → exit-code contract lives next to the codes themselves.
  *
- * `5009` (and the unknown-code default branch) routes to
- * `INIT_EXIT_INTERNAL_ERROR` because those represent prisma-next bugs the
- * user did not cause — surfacing them as `PRECONDITION` would mislead
- * automation into thinking the caller mis-invoked the CLI.
+ * `CLI.INIT_INVALID_OUTPUT_DOCUMENT` (and the unknown-code default branch)
+ * routes to `INIT_EXIT_INTERNAL_ERROR` because those represent prisma-next
+ * bugs the user did not cause — surfacing them as `PRECONDITION` would
+ * mislead automation into thinking the caller mis-invoked the CLI.
  *
  * See [exit-codes.ts](./exit-codes.ts) for the canonical list and
  * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes)
@@ -596,24 +599,24 @@ function emitError(ui: TerminalUI, flags: GlobalFlags, error: CliStructuredError
  */
 export function exitCodeForError(error: { readonly code: string }): number {
   switch (error.code) {
-    case '5002': // re-init needs --force — precondition
-    case '5003': // missing flags — precondition
-    case '5004': // invalid flag value — precondition
-    case '5005': // --strict-probe without --probe-db — precondition
-    case '5010': // invalid manifest (malformed package.json) — precondition
-    case '5011': // invalid tsconfig (unparseable JSONC) — precondition
-    case '5012': // probe failed under --strict-probe — precondition
-    case '5014': // --authoring / --schema-path extension mismatch — precondition
+    case 'CLI.INIT_REINIT_NEEDS_FORCE': // re-init needs --force — precondition
+    case 'CLI.INIT_MISSING_FLAGS': // missing flags — precondition
+    case 'CLI.INIT_INVALID_FLAG_VALUE': // invalid flag value — precondition
+    case 'CLI.INIT_STRICT_PROBE_WITHOUT_PROBE': // --strict-probe without --probe-db — precondition
+    case 'CLI.INIT_INVALID_MANIFEST': // invalid manifest (malformed package.json) — precondition
+    case 'CLI.INIT_INVALID_TSCONFIG': // invalid tsconfig (unparseable JSONC) — precondition
+    case 'CLI.INIT_PROBE_FAILED': // probe failed under --strict-probe — precondition
+    case 'CLI.INIT_AUTHORING_SCHEMA_PATH_MISMATCH': // --authoring / --schema-path extension mismatch — precondition
       return INIT_EXIT_PRECONDITION;
-    case '5006': // user aborted interactive prompt
+    case 'CLI.INIT_USER_ABORTED': // user aborted interactive prompt
       return INIT_EXIT_USER_ABORTED;
-    case '5007': // install failed
+    case 'CLI.INIT_INSTALL_FAILED': // install failed
       return INIT_EXIT_INSTALL_FAILED;
-    case '5008': // emit failed
+    case 'CLI.INIT_EMIT_FAILED': // emit failed
       return INIT_EXIT_EMIT_FAILED;
-    case '5009': // invalid output document — internal bug in prisma-next
+    case 'CLI.INIT_INVALID_OUTPUT_DOCUMENT': // invalid output document — internal bug in prisma-next
       return INIT_EXIT_INTERNAL_ERROR;
-    case '5013': // skill install failed
+    case 'CLI.INIT_SKILL_INSTALL_FAILED': // skill install failed
       return INIT_EXIT_SKILL_INSTALL_FAILED;
     default:
       // Any unexpected code is treated as an internal bug rather than

package/src/commands/migration-check.ts

@@ -83,7 +83,7 @@ function checkFileExists(
   if (!existsSync(join(dirPath, fileName))) {
     return {
       space: spaceId,
-      code: 'PN-MIG-CHECK-002',
+      code: 'MIGRATION.CHECK_FILE_MISSING',
       where: migrationFileRelative(dirPath, fileName),
       why: `${fileName} is missing from ${dirName}`,
       fix: 'Re-emit the migration package or restore from version control.',
@@ -105,7 +105,7 @@ function checkSnapshotConsistency(
     if (typeof snapshotHash === 'string' && snapshotHash !== pkg.metadata.to) {
       return {
         space: spaceId,
-        code: 'PN-MIG-CHECK-005',
+        code: 'MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH',
         where: migrationPathRelative(pkg.dirPath),
         why: `Migration "${pkg.dirName}" declares to=${pkg.metadata.to} but end-contract.json has storageHash=${snapshotHash}`,
         fix: 'Re-emit the migration package so migration.json and end-contract.json agree.',
@@ -114,7 +114,7 @@ function checkSnapshotConsistency(
   } catch {
     return {
       space: spaceId,
-      code: 'PN-MIG-CHECK-006',
+      code: 'MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE',
       where: migrationPathRelative(pkg.dirPath),
       why: `Migration "${pkg.dirName}" has an unparseable end-contract.json.`,
       fix: 'Re-emit the migration package to repair the snapshot file.',
@@ -212,7 +212,7 @@ function checkReachability(space: CheckSpace): readonly CheckFailure[] {
     if (!isReachable) {
       failures.push({
         space: space.spaceId,
-        code: 'PN-MIG-CHECK-003',
+        code: 'MIGRATION.CHECK_UNREACHABLE_MIGRATION',
         where: migrationPathRelative(pkg.dirPath),
         why: `Migration "${pkg.dirName}" starts from ${pkg.metadata.from} which no other migration produces`,
         fix: 'This migration is unreachable in the graph. Delete it or re-emit a connecting migration.',
@@ -228,7 +228,7 @@ function checkDanglingRefs(space: CheckSpace): readonly CheckFailure[] {
     if (!space.graph.nodes.has(entry.hash)) {
       failures.push({
         space: space.spaceId,
-        code: 'PN-MIG-CHECK-004',
+        code: 'MIGRATION.CHECK_DANGLING_REF',
         where: relative(process.cwd(), join(space.refsDir, `${name}.json`)),
         why: `Ref "${name}" points at ${entry.hash} which does not exist in the migration graph`,
         fix: `Update the ref with \`prisma-next ref set ${name} <valid-hash>\` or delete it.`,
@@ -522,7 +522,7 @@ async function checkSingleTarget(
       matchedPkg = hits[0]!.pkg;
     } else if (bestParseFailure !== undefined) {
       // The ref didn't resolve in any in-scope space — surface the most informative
-      // parse failure through the shared ref-resolution envelope (PN-RUN-3000) the
+      // parse failure through the shared ref-resolution envelope (CONTRACT.VERIFY_FAILED) the
       // earlier work established, rather than a bespoke string. (Ref-resolved-but-
       // no-package falls through to the "not found on disk" result below.)
       return { error: mapRefResolutionError(bestParseFailure), exitCode: PRECONDITION };
@@ -551,7 +551,7 @@ async function checkSingleTarget(
   if (!verification.ok) {
     failures.push({
       space: matchedSpace.spaceId,
-      code: 'PN-MIG-CHECK-001',
+      code: 'MIGRATION.CHECK_HASH_MISMATCH',
       where: migrationFileRelative(matchedPkg.dirPath, 'migration.json'),
       why: `Stored hash ${verification.storedHash} does not match recomputed hash ${verification.computedHash}`,
       fix: 'Re-emit the migration package or restore from version control.',

package/src/commands/migration-plan.ts

@@ -142,7 +142,7 @@ async function runPlannerLeg(
       );
     }
   } catch (e) {
-    if (CliStructuredError.is(e) && e.domain === 'MIG' && e.code === '2001') {
+    if (CliStructuredError.is(e) && e.code === 'MIGRATION.UNFILLED_PLACEHOLDER') {
       hasPlaceholders = true;
     } else {
       throw e;

package/src/control-api/operations/db-run.ts

@@ -286,8 +286,9 @@ function aggregatePlannerWarnings(
  * an extension that was removed from `extensionPacks` without first
  * cleaning up its on-disk migrations / database tables.
  *
- * Returns a {@link CliStructuredError} envelope (code `5002`,
- * `kind: 'orphanMarker'`) for the first orphan it finds, or `null`
+ * Returns a {@link CliStructuredError} envelope (code
+ * `MIGRATION.CONTRACT_SPACE_VIOLATION`, `kind: 'orphanMarker'`) for the
+ * first orphan it finds, or `null`
  * when every marker row maps to a declared contract space. Mirrors the M2
  * `runContractSpaceVerifierMarkerCheck` envelope so downstream
  * tooling (integration tests, JSON consumers) keeps asserting on the
@@ -313,8 +314,7 @@ function detectOrphanMarkers(
     orphans.length === 1
       ? `Orphan contract-space marker detected for "${orphans[0]}"`
       : `Orphan contract-space markers detected for ${orphans.length} spaces`;
-  return new CliStructuredError('5002', summary, {
-    domain: 'MIG',
+  return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
     why: `The database has \`_prisma_marker\` rows for spaces (${orphans
       .map((s) => `"${s}"`)
       .join(

package/src/control-api/operations/db-verify.ts

@@ -254,12 +254,15 @@ function finaliseVerifyResult(args: {
   if (!verifyResult.ok) {
     emitVerifySpan(onProgress, 'spanEndError');
     return notOk(
-      new CliStructuredError('5002', 'Aggregate verifier introspection failed', {
-        domain: 'MIG',
-        why: verifyResult.failure.detail,
-        fix: 'Check database connectivity and the introspection tooling.',
-        docsUrl: 'https://pris.ly/contract-spaces',
-      }),
+      new CliStructuredError(
+        'MIGRATION.CONTRACT_SPACE_VIOLATION',
+        'Aggregate verifier introspection failed',
+        {
+          why: verifyResult.failure.detail,
+          fix: 'Check database connectivity and the introspection tooling.',
+          docsUrl: 'https://pris.ly/contract-spaces',
+        },
+      ),
     );
   }
   const markerError = skipMarker
@@ -300,7 +303,8 @@ function buildSkippedSchemaResult(space: AggregateContractSpace): VerifyDatabase
 /**
  * Translate per-space marker check failures and orphan markers into a
  * single CLI structured error envelope. Preserves the legacy code
- * `5002` (was emitted by `runContractSpaceVerifierMarkerCheck`).
+ * `MIGRATION.CONTRACT_SPACE_VIOLATION` (was emitted by
+ * `runContractSpaceVerifierMarkerCheck`).
  */
 function mapMarkerCheckFailures(
   appSpaceId: string,
@@ -354,8 +358,7 @@ function mapMarkerCheckFailures(
     violations.length === 1
       ? 'Contract-space verifier found a violation'
       : `Contract-space verifier found violations (${violations.length})`;
-  return new CliStructuredError('5002', summary, {
-    domain: 'MIG',
+  return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
     why: `The on-disk \`migrations/\` directory, the \`extensionPacks\` declaration, and the live database marker rows are not in agreement.\n${lines.join('\n')}`,
     fix: violations[0]?.remediation ?? 'Review and reconcile the violations listed above.',
     docsUrl: 'https://pris.ly/contract-spaces',

package/src/control-api/operations/migrate.ts

@@ -12,6 +12,7 @@ import type {
 } from '@prisma-next/framework-components/control';
 import {
   type AggregateContractSpace,
+  allStorageElementsExternal,
   buildFabricatedMigrationEdge,
   type ContractMarkerRecordLike,
   type ContractSpaceAggregate,
@@ -98,13 +99,17 @@ export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId exten
  * 2. Read live marker rows per space (`familyInstance.readAllMarkers`).
  * 3. Per space: `resolveRecordedPath` plots the path from the live
  *    marker to `space.headRef.hash` (or `refHash` for the app
- *    space when provided). Empty-graph spaces fail loudly — a
- *    "never planned" space is a user-error condition for replay.
+ *    space when provided). An empty-graph space whose elements are ALL
+ *    externally managed resolves declaratively (marker to head, zero
+ *    ops), mirroring the db-init aggregate planner: such a space ships
+ *    no DDL and has nothing to author. Every other empty-graph space
+ *    fails loudly — "never planned" is a user-error condition for
+ *    replay.
  * 4. Hand off to {@link runMigration} (the runner-driving tail
  *    shared with `db init` / `db update`). Marker advancement is
  *    inside the per-space transaction.
  *
- * Encodes the replay-only contract: every contract space must have an
+ * Encodes the replay-only contract: the app contract space must have an
  * authored migration graph on disk before this operation can advance it.
  */
 export async function executeMigrate<TFamilyId extends string, TTargetId extends string>(
@@ -230,8 +235,13 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
   // plans). Surfaces every loaded space — including at-head empty-
   // graph extensions — in `perSpace[]` so the result reflects the
   // full aggregate, not just the spaces the runner would have touched.
-  const totalPlannedOps = sumPlannedOps(applyOrder, perSpacePlans);
-  if (totalPlannedOps === 0) {
+  // A zero-op plan still counts as pending when it advances a marker
+  // (declared-state resolution for an all-external extension space).
+  const hasPendingWork = applyOrder.some((spaceId) => {
+    const entry = perSpacePlans.get(spaceId);
+    return entry !== undefined && planRequiresExecution(entry);
+  });
+  if (!hasPendingWork) {
     const ordered = canonicalOrder
       .filter((spaceId) => perSpacePlans.has(spaceId) || atHeadResolutions.has(spaceId))
       .map((spaceId) => {
@@ -397,6 +407,39 @@ export function planSpacePath({
         }),
       };
     }
+    // Empty-graph extension space not yet at head: the space ships no
+    // migration packages at all. Advancing the marker without migrations
+    // (the db-init aggregate planner's declared-state strategy, mirrored
+    // here) is valid exclusively when every element the space declares is
+    // externally managed — nothing Prisma Next owns exists in such a space
+    // (e.g. Supabase's auth/storage), so its declared state needs no
+    // migration to be true, and there is no command that could author an
+    // edge for it. A space that declares a managed element but ships no
+    // migration graph is an authoring bug: it falls through to the
+    // never-planned failure, like an app space with no authored graph.
+    if (!isAppSpace && allStorageElementsExternal(space.contract())) {
+      if (headRef.invariants.length > 0) {
+        return {
+          kind: 'unsatisfiable',
+          spaceId: space.spaceId,
+          isAppSpace,
+          missing: [...headRef.invariants].sort(),
+          targetInvariants: headRef.invariants,
+          targetSpace: space,
+          liveHash: liveHash ?? EMPTY_CONTRACT_HASH,
+          refName: undefined,
+        };
+      }
+      return {
+        kind: 'ok',
+        plan: buildAtHeadResolution({
+          aggregateTargetId: aggregate.targetId,
+          space,
+          targetHash,
+          liveMarker,
+        }),
+      };
+    }
     return { kind: 'never-planned', spaceId: space.spaceId, targetHash };
   }
 
@@ -434,11 +477,13 @@ export function planSpacePath({
 }
 
 /**
- * Build a zero-op {@link PerSpacePlan} for an empty-graph
- * space whose live marker already matches the target. Lets the apply
- * pipeline thread the space through `perSpacePlans` -> `applyOrder`
- * -> the success envelope's `perSpace[]` block so the result reflects
- * every loaded space, even when there is nothing to execute.
+ * Build a zero-op {@link PerSpacePlan} for an empty-graph space —
+ * either one whose live marker already matches the target (at-head), or
+ * an all-external extension space whose marker must advance to the head
+ * ref with no DDL (declared-state). Lets the apply pipeline thread the
+ * space through `perSpacePlans` -> `applyOrder` -> the success
+ * envelope's `perSpace[]` block so the result reflects every loaded
+ * space, even when there is nothing to execute.
  */
 function buildAtHeadResolution(args: {
   readonly aggregateTargetId: string;
@@ -469,17 +514,14 @@ function buildAtHeadResolution(args: {
   };
 }
 
-function sumPlannedOps(
-  applyOrder: readonly string[],
-  perSpacePlans: ReadonlyMap<string, PerSpacePlan>,
-): number {
-  let total = 0;
-  for (const spaceId of applyOrder) {
-    const entry = perSpacePlans.get(spaceId);
-    if (!entry) continue;
-    total += entry.plan.operations.length;
-  }
-  return total;
+/**
+ * A plan needs the runner when it executes operations or advances the
+ * space's marker (a declared-state resolution has zero operations but a
+ * destination hash the live marker doesn't carry yet).
+ */
+function planRequiresExecution(entry: PerSpacePlan): boolean {
+  if (entry.plan.operations.length > 0) return true;
+  return entry.plan.origin?.storageHash !== entry.plan.destination.storageHash;
 }
 
 interface BuildSuccessArgs {
@@ -552,10 +594,12 @@ function buildSuccess(args: BuildSuccessArgs): MigrateSuccess {
 }
 
 /**
- * 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`.
+ * Build the `neverPlanned` failure raised when a contract space that
+ * declares managed storage elements has no on-disk migration graph but
+ * migrate was asked to reach a target hash. All-external spaces never reach
+ * this: they resolve declaratively (marker advances to the head ref with
+ * zero operations). The `why` states only the condition; the recovery
+ * sequence is composed by `errorPathUnreachable`'s `fix`.
  *
  * @internal Exported for testing only.
  */
@@ -563,7 +607,7 @@ export function buildNeverPlannedFailure(spaceId: string, targetHash: string): M
   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}".`,
+    why: `migrate is replay-only: a contract space that declares managed storage elements 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, kind: 'neverPlanned' },
   };
 }

package/src/control-api/types.ts

@@ -402,7 +402,10 @@ export interface DbInitSuccess {
 /**
  * Failure codes for dbInit operation.
  */
-export type DbInitFailureCode = 'PLANNING_FAILED' | 'MARKER_ORIGIN_MISMATCH' | 'RUNNER_FAILED';
+export type DbInitFailureCode =
+  | 'PLANNING_FAILED'
+  | 'MIGRATION.MARKER_ORIGIN_MISMATCH'
+  | 'RUNNER_FAILED';
 
 /**
  * Failure details for dbInit operation.

package/src/migration-cli.ts

@@ -21,7 +21,7 @@
  *    the CLI commands use, walking up from the migration file's directory.
  * 4. Probe-instantiates the migration class without a stack so it can read
  *    `targetId` and verify it matches `config.target.targetId`
- *    (`PN-MIG-2006` on mismatch) before any stack-driven adapter
+ *    (`MIGRATION.TARGET_MISMATCH` on mismatch) before any stack-driven adapter
  *    construction runs.
  * 5. Assembles a `ControlStack` from the loaded config descriptors and
  *    constructs the migration with that stack.
@@ -269,7 +269,7 @@ async function orchestrate(
 
   // Pre-scan for malformed `--config` (no value, or value-shaped-as-flag)
   // before delegating to clipanion. The legacy parser surfaced both as
-  // `errorMigrationCliInvalidConfigArg` (`PN-CLI-4012`); pre-scanning
+  // `errorMigrationCliInvalidConfigArg` (`CLI.CONFIG_ARG_MISSING_PATH`); pre-scanning
   // here keeps that contract independent of how clipanion classifies
   // the error internally (it variably throws `UnknownSyntaxError` or
   // accepts the flag-shaped token as the value depending on what other
@@ -337,7 +337,7 @@ async function orchestrate(
  * - `--config <empty>` where the value is the empty string. Shells
  *   expand `--config ""` (or `--config "$UNSET_VAR"`) into a real
  *   empty argv token; treating that as a usage error here surfaces
- *   `PN-CLI-4012` instead of a less actionable loader error on an
+ *   `CLI.CONFIG_ARG_MISSING_PATH` instead of a less actionable loader error on an
  *   empty path.
  * - `--config=` (the equals form with an empty value). Same shape as
  *   the empty-string case above; the user expressed intent to override
@@ -425,7 +425,7 @@ function isUnknownSyntaxError(err: unknown): err is Error {
 /**
  * Best-effort: pull the first input token that doesn't match a known
  * flag. Falls back to the first token when we can't pinpoint it. The
- * returned name is rendered into the user-visible PN-CLI-4013 envelope
+ * returned name is rendered into the user-visible CLI.UNKNOWN_FLAG envelope
  * (`Unknown flag \`<name>\``) and round-tripped via `meta.flag` so
  * agent consumers can render their own "did you mean" suggestions.
  */
@@ -556,7 +556,7 @@ async function runMigration(
   // subclasses are required to accept the no-arg form; the abstract
   // `Migration` constructor declares `stack?` and target subclasses
   // (Postgres, Mongo) propagate that optionality. This makes the
-  // target-mismatch guard fail fast with `PN-MIG-2006` before any
+  // target-mismatch guard fail fast with `MIGRATION.TARGET_MISMATCH` before any
   // stack-driven adapter construction begins, even if the wrong-target
   // adapter's `create` would otherwise succeed and silently misshapen
   // the stored adapter cast.