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

package/src/commands/init/errors.ts

@@ -6,7 +6,8 @@ import { CliStructuredError } from '../../utils/cli-errors';
  * the user was never given the choice — `--force` is the contract.
  */
 export function errorInitReinitNeedsForce(): CliStructuredError {
-  return new CliStructuredError('CLI.INIT_REINIT_NEEDS_FORCE', 'Project is already initialized', {
+  return new CliStructuredError('5002', 'Project is already initialized', {
+    domain: 'CLI',
     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',
@@ -41,7 +42,8 @@ export function errorInitMissingFlags(options: {
       }
     })
     .join(' ');
-  return new CliStructuredError('CLI.INIT_MISSING_FLAGS', 'Missing required flags', {
+  return new CliStructuredError('5003', 'Missing required flags', {
+    domain: 'CLI',
     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',
@@ -58,16 +60,13 @@ export function errorInitInvalidFlagValue(options: {
   readonly value: string;
   readonly allowed: readonly string[];
 }): CliStructuredError {
-  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 },
-    },
-  );
+  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 },
+  });
 }
 
 /**
@@ -82,26 +81,23 @@ export function errorInitAuthoringSchemaPathMismatch(options: {
   readonly expectedExtension: string;
 }): CliStructuredError {
   const expectedAuthoring = options.expectedExtension === '.ts' ? 'typescript' : 'psl';
-  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,
-      },
+  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,
     },
-  );
+  });
 }
 
 /**
@@ -112,7 +108,8 @@ export function errorInitAuthoringSchemaPathMismatch(options: {
  * 3 (USER_ABORTED).
  */
 export function errorInitUserAborted(): CliStructuredError {
-  return new CliStructuredError('CLI.INIT_USER_ABORTED', 'Init cancelled', {
+  return new CliStructuredError('5006', 'Init cancelled', {
+    domain: 'CLI',
     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',
@@ -128,15 +125,12 @@ export function errorInitUserAborted(): CliStructuredError {
  * mode is supposed to prevent.
  */
 export function errorInitStrictProbeWithoutProbe(): CliStructuredError {
-  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',
-    },
-  );
+  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',
+  });
 }
 
 /**
@@ -158,7 +152,8 @@ 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('CLI.INIT_INSTALL_FAILED', 'Failed to install dependencies', {
+  return new CliStructuredError('5007', 'Failed to install dependencies', {
+    domain: 'CLI',
     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',
@@ -184,7 +179,8 @@ export function errorInitInvalidManifest(options: {
   readonly path: string;
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('CLI.INIT_INVALID_MANIFEST', `Failed to parse ${options.path}`, {
+  return new CliStructuredError('5010', `Failed to parse ${options.path}`, {
+    domain: 'CLI',
     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',
@@ -210,7 +206,8 @@ export function errorInitInvalidTsconfig(options: {
   readonly path: string;
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('CLI.INIT_INVALID_TSCONFIG', `Failed to parse ${options.path}`, {
+  return new CliStructuredError('5011', `Failed to parse ${options.path}`, {
+    domain: 'CLI',
     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',
@@ -236,7 +233,8 @@ export function errorInitProbeFailed(options: {
   readonly cause: string;
   readonly filesWritten: readonly string[];
 }): CliStructuredError {
-  return new CliStructuredError('CLI.INIT_PROBE_FAILED', 'Database probe failed', {
+  return new CliStructuredError('5012', 'Database probe failed', {
+    domain: 'CLI',
     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',
@@ -258,7 +256,8 @@ export function errorInitEmitFailed(options: {
   readonly filesWritten: readonly string[];
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('CLI.INIT_EMIT_FAILED', 'Failed to emit contract', {
+  return new CliStructuredError('5008', 'Failed to emit contract', {
+    domain: 'CLI',
     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',
@@ -285,21 +284,18 @@ export function errorInitSkillInstallFailed(options: {
   readonly filesWritten: readonly string[];
   readonly cause: string;
 }): CliStructuredError {
-  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,
-      },
+  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,
     },
-  );
+  });
 }

package/src/commands/init/init.ts

@@ -534,21 +534,18 @@ 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
-    // 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.
+    // 5009 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(
-        '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',
-        },
-      ),
+      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',
+      }),
     );
   }
 
@@ -585,10 +582,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.
  *
- * `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.
+ * `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.
  *
  * See [exit-codes.ts](./exit-codes.ts) for the canonical list and
  * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes)
@@ -599,24 +596,24 @@ function emitError(ui: TerminalUI, flags: GlobalFlags, error: CliStructuredError
  */
 export function exitCodeForError(error: { readonly code: string }): number {
   switch (error.code) {
-    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
+    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
       return INIT_EXIT_PRECONDITION;
-    case 'CLI.INIT_USER_ABORTED': // user aborted interactive prompt
+    case '5006': // user aborted interactive prompt
       return INIT_EXIT_USER_ABORTED;
-    case 'CLI.INIT_INSTALL_FAILED': // install failed
+    case '5007': // install failed
       return INIT_EXIT_INSTALL_FAILED;
-    case 'CLI.INIT_EMIT_FAILED': // emit failed
+    case '5008': // emit failed
       return INIT_EXIT_EMIT_FAILED;
-    case 'CLI.INIT_INVALID_OUTPUT_DOCUMENT': // invalid output document — internal bug in prisma-next
+    case '5009': // invalid output document — internal bug in prisma-next
       return INIT_EXIT_INTERNAL_ERROR;
-    case 'CLI.INIT_SKILL_INSTALL_FAILED': // skill install failed
+    case '5013': // 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: 'MIGRATION.CHECK_FILE_MISSING',
+      code: 'PN-MIG-CHECK-002',
       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: 'MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH',
+        code: 'PN-MIG-CHECK-005',
         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: 'MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE',
+      code: 'PN-MIG-CHECK-006',
       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: 'MIGRATION.CHECK_UNREACHABLE_MIGRATION',
+        code: 'PN-MIG-CHECK-003',
         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: 'MIGRATION.CHECK_DANGLING_REF',
+        code: 'PN-MIG-CHECK-004',
         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 (CONTRACT.VERIFY_FAILED) the
+      // parse failure through the shared ref-resolution envelope (PN-RUN-3000) 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: 'MIGRATION.CHECK_HASH_MISMATCH',
+      code: 'PN-MIG-CHECK-001',
       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.code === 'MIGRATION.UNFILLED_PLACEHOLDER') {
+    if (CliStructuredError.is(e) && e.domain === 'MIG' && e.code === '2001') {
       hasPlaceholders = true;
     } else {
       throw e;

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

@@ -286,9 +286,8 @@ 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
- * `MIGRATION.CONTRACT_SPACE_VIOLATION`, `kind: 'orphanMarker'`) for the
- * first orphan it finds, or `null`
+ * Returns a {@link CliStructuredError} envelope (code `5002`,
+ * `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
@@ -314,7 +313,8 @@ 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('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
+  return new CliStructuredError('5002', summary, {
+    domain: 'MIG',
     why: `The database has \`_prisma_marker\` rows for spaces (${orphans
       .map((s) => `"${s}"`)
       .join(

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

@@ -254,15 +254,12 @@ function finaliseVerifyResult(args: {
   if (!verifyResult.ok) {
     emitVerifySpan(onProgress, 'spanEndError');
     return notOk(
-      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',
-        },
-      ),
+      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',
+      }),
     );
   }
   const markerError = skipMarker
@@ -303,8 +300,7 @@ 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
- * `MIGRATION.CONTRACT_SPACE_VIOLATION` (was emitted by
- * `runContractSpaceVerifierMarkerCheck`).
+ * `5002` (was emitted by `runContractSpaceVerifierMarkerCheck`).
  */
 function mapMarkerCheckFailures(
   appSpaceId: string,
@@ -358,7 +354,8 @@ function mapMarkerCheckFailures(
     violations.length === 1
       ? 'Contract-space verifier found a violation'
       : `Contract-space verifier found violations (${violations.length})`;
-  return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
+  return new CliStructuredError('5002', summary, {
+    domain: 'MIG',
     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/types.ts

@@ -402,10 +402,7 @@ export interface DbInitSuccess {
 /**
  * Failure codes for dbInit operation.
  */
-export type DbInitFailureCode =
-  | 'PLANNING_FAILED'
-  | 'MIGRATION.MARKER_ORIGIN_MISMATCH'
-  | 'RUNNER_FAILED';
+export type DbInitFailureCode = 'PLANNING_FAILED' | '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`
- *    (`MIGRATION.TARGET_MISMATCH` on mismatch) before any stack-driven adapter
+ *    (`PN-MIG-2006` 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` (`CLI.CONFIG_ARG_MISSING_PATH`); pre-scanning
+  // `errorMigrationCliInvalidConfigArg` (`PN-CLI-4012`); 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
- *   `CLI.CONFIG_ARG_MISSING_PATH` instead of a less actionable loader error on an
+ *   `PN-CLI-4012` 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 CLI.UNKNOWN_FLAG envelope
+ * returned name is rendered into the user-visible PN-CLI-4013 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 `MIGRATION.TARGET_MISMATCH` before any
+  // target-mismatch guard fail fast with `PN-MIG-2006` 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.

package/src/utils/cli-errors.ts

@@ -360,7 +360,7 @@ export function mapMigrationToolsError(error: MigrationToolsError): CliStructure
  * Shared "needs a live database" precondition for read verbs that consult the
  * marker/ledger (`migration log`, `migration status`). A command needs both a
  * connection string and a control-plane driver; either missing yields the same
- * `CONFIG.DB_CONNECTION_REQUIRED` envelope with `meta.missingFlags` (canonical long-form flags
+ * `PN-CLI-4005` envelope with `meta.missingFlags` (canonical long-form flags
  * per CLI Style Guide §Errors) so callers can react programmatically. Returns
  * `null` when both are present.
  */

package/src/utils/combine-verify-results.ts

@@ -78,7 +78,7 @@ export function combineVerifyResults(
   return {
     result: {
       ok,
-      ...(ok ? {} : { code: appResult.code ?? 'CONTRACT.MARKER_REQUIRED' }),
+      ...(ok ? {} : { code: appResult.code ?? 'PN-RUN-3010' }),
       summary,
       contract: appResult.contract,
       target: appResult.target,

package/src/utils/contract-space-aggregate-loader.ts

@@ -20,7 +20,7 @@ import { toDeclaredExtensionsFromRaw } from './extension-pack-inputs';
 
 const CONTRACT_SPACES_DOCS_URL = 'https://pris.ly/contract-spaces';
 
-function contractSpaceViolationError(
+function contractSpaceError5002(
   summary: string,
   options: {
     readonly why: string;
@@ -28,7 +28,8 @@ function contractSpaceViolationError(
     readonly violations: readonly IntegrityViolation[];
   },
 ): CliStructuredError {
-  return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
+  return new CliStructuredError('5002', summary, {
+    domain: 'MIG',
     why: options.why,
     fix: options.fix,
     docsUrl: CONTRACT_SPACES_DOCS_URL,
@@ -37,7 +38,7 @@ function contractSpaceViolationError(
 }
 
 /**
- * Build the `MIGRATION.CONTRACT_SPACE_VIOLATION` structured-error envelope for a contract-space
+ * Build the `5002` structured-error envelope for a contract-space
  * target mismatch. Shared between the declared-extension precheck (the
  * descriptor's configured target disagrees with the project target) and
  * the on-disk-contract check surfaced by `checkIntegrity`.
@@ -47,7 +48,7 @@ function targetMismatchError(
   expected: string,
   actual: string,
 ): CliStructuredError {
-  return contractSpaceViolationError(`Contract-space target mismatch for "${spaceId}"`, {
+  return contractSpaceError5002(`Contract-space target mismatch for "${spaceId}"`, {
     why: `Space "${spaceId}" targets "${actual}" but the project's adapter targets "${expected}".`,
     fix: 'Update the extension descriptor to target the configured database, or change the project adapter.',
     violations: [{ kind: 'targetMismatch', spaceId, expected, actual }],
@@ -88,10 +89,9 @@ function describeIntegrityViolation(violation: IntegrityViolation): string {
 /**
  * Map the integrity violations `checkIntegrity` reports into a single
  * CLI structured-error envelope, preserving the error codes the prior
- * throw-on-load loader emitted: `MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION`
- * (layout drift, bundled) and `MIGRATION.CONTRACT_SPACE_VIOLATION` (target /
- * disjointness / contract-validation / structural integrity). Returns
- * `null` when there is nothing to refuse on.
+ * throw-on-load loader emitted: `5001` (layout drift, bundled) and
+ * `5002` (target / disjointness / contract-validation / structural
+ * integrity). Returns `null` when there is nothing to refuse on.
  *
  * Precedence reproduces the prior loader's first-failure ordering:
  * layout drift first (every offence bundled into one envelope), then
@@ -113,7 +113,8 @@ export function mapIntegrityViolations(
       layout.length === 1
         ? 'Contract-space layout violation detected'
         : `Contract-space layout violations detected (${layout.length})`;
-    return new CliStructuredError('MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION', summary, {
+    return new CliStructuredError('5001', summary, {
+      domain: 'MIG',
       why: `The on-disk \`migrations/\` directory and your \`extensionPacks\` declaration are not in agreement.\n${lines.join('\n')}`,
       fix: 'Declare the extension in `extensionPacks` and re-emit its contract-space artefacts, or remove the orphan `migrations/<space>` directory.',
       docsUrl: CONTRACT_SPACES_DOCS_URL,
@@ -132,7 +133,7 @@ export function mapIntegrityViolations(
 
   const disjointness = violations.find((v) => v.kind === 'disjointness');
   if (disjointness && disjointness.kind === 'disjointness') {
-    return contractSpaceViolationError(
+    return contractSpaceError5002(
       `Contract-space disjointness violation: storage element "${disjointness.element}" claimed by multiple spaces`,
       {
         why: `Spaces ${disjointness.claimedBy.map((s) => `"${s}"`).join(', ')} all claim the storage element "${disjointness.element}". Each storage element must be owned by exactly one contract space.`,
@@ -144,7 +145,7 @@ export function mapIntegrityViolations(
 
   const contractUnreadable = violations.find((v) => v.kind === 'contractUnreadable');
   if (contractUnreadable && contractUnreadable.kind === 'contractUnreadable') {
-    return contractSpaceViolationError(
+    return contractSpaceError5002(
       `Contract-space contract validation failed for "${contractUnreadable.spaceId}"`,
       {
         why: contractUnreadable.detail,
@@ -159,7 +160,7 @@ export function mapIntegrityViolations(
   // is still computed; the gate just renders one envelope).
   const structural = violations[0]!;
   const spaceId = 'spaceId' in structural ? structural.spaceId : '*';
-  return contractSpaceViolationError(`Contract-space integrity failure for "${spaceId}"`, {
+  return contractSpaceError5002(`Contract-space integrity failure for "${spaceId}"`, {
     why: describeIntegrityViolation(structural),
     fix: 'Re-emit the affected migration package(s) or restore the on-disk `migrations/` directory from version control.',
     violations: [structural],