@prisma-next/errors 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Prisma Data, Inc]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,36 @@
+# @prisma-next/errors
+
+Structured error types and factories for CLI and runtime error reporting.
+
+## Overview
+
+This package provides `CliStructuredError` (the shared error class) and factory functions for creating structured errors with error codes, fix suggestions, and machine-readable metadata. Errors are split across two entry points by domain:
+
+- **`./control`** — CLI errors (`PN-CLI-4xxx`): config validation, file resolution, migration planning
+- **`./execution`** — Runtime errors (`PN-RUN-3xxx`): contract verification, hash mismatch, database signing
+
+## Usage
+
+```ts
+import { CliStructuredError, errorConfigFileNotFound } from '@prisma-next/errors/control';
+import { errorHashMismatch } from '@prisma-next/errors/execution';
+
+// Create a CLI error
+throw errorConfigFileNotFound('/path/to/config.ts');
+
+// Create a runtime error
+throw errorHashMismatch({ expected: 'abc123', actual: 'def456' });
+
+// Type-guard check
+if (CliStructuredError.is(caught)) {
+  const envelope = caught.toEnvelope();
+  // { ok: false, code: 'PN-CLI-4001', domain: 'CLI', summary: '...', ... }
+}
+```
+
+## Entry points
+
+| Entry point | Domain | Code range | Contents |
+|---|---|---|---|
+| `./control` | CLI | `PN-CLI-4xxx` | `CliStructuredError` class, `CliErrorEnvelope`/`CliErrorConflict` types, 14 CLI factory functions, `errorUnexpected` |
+| `./execution` | RUN | `PN-RUN-3xxx` | 8 runtime factory functions, `ERROR_CODE_DESTRUCTIVE_CHANGES` constant |

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@prisma-next/errors",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Structured error types for Prisma Next control and execution planes",
+  "dependencies": {
+    "@prisma-next/framework-components": "0.0.1",
+    "@prisma-next/utils": "0.0.1"
+  },
+  "devDependencies": {
+    "tsdown": "0.18.4",
+    "typescript": "5.9.3",
+    "vitest": "4.0.17",
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/tsconfig": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./control": "./dist/control.mjs",
+    "./execution": "./dist/execution.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/1-core/errors"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  }
+}

package/src/control.ts

@@ -0,0 +1,372 @@
+/**
+ * CLI error envelope for output formatting.
+ * This is the serialized form of a CliStructuredError.
+ */
+export interface CliErrorEnvelope {
+  readonly ok: false;
+  readonly code: string;
+  readonly domain: string;
+  readonly severity: 'error' | 'warn' | 'info';
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly fix: string | undefined;
+  readonly where:
+    | {
+        readonly path: string | undefined;
+        readonly line: number | undefined;
+      }
+    | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+  readonly docsUrl: string | undefined;
+}
+
+/**
+ * Minimal conflict data structure expected by CLI output.
+ */
+export interface CliErrorConflict {
+  readonly kind: string;
+  readonly summary: string;
+  readonly why?: string;
+}
+
+/**
+ * Structured CLI error that contains all information needed for error envelopes.
+ * Call sites throw these errors with full context.
+ */
+export class CliStructuredError extends Error {
+  readonly code: string;
+  readonly domain: 'CLI' | 'RUN';
+  readonly severity: 'error' | 'warn' | 'info';
+  readonly why: string | undefined;
+  readonly fix: string | undefined;
+  readonly where:
+    | {
+        readonly path: string | undefined;
+        readonly line: number | undefined;
+      }
+    | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+  readonly docsUrl: string | undefined;
+
+  constructor(
+    code: string,
+    summary: string,
+    options?: {
+      readonly domain?: 'CLI' | 'RUN';
+      readonly severity?: 'error' | 'warn' | 'info';
+      readonly why?: string;
+      readonly fix?: string;
+      readonly where?: { readonly path?: string; readonly line?: number };
+      readonly meta?: Record<string, unknown>;
+      readonly docsUrl?: string;
+    },
+  ) {
+    super(summary);
+    this.name = 'CliStructuredError';
+    this.code = code;
+    this.domain = options?.domain ?? 'CLI';
+    this.severity = options?.severity ?? 'error';
+    this.why = options?.why;
+    this.fix = options?.fix === options?.why ? undefined : options?.fix;
+    this.where = options?.where
+      ? {
+          path: options.where.path,
+          line: options.where.line,
+        }
+      : undefined;
+    this.meta = options?.meta;
+    this.docsUrl = options?.docsUrl;
+  }
+
+  /**
+   * Converts this error to a CLI error envelope for output formatting.
+   */
+  toEnvelope(): CliErrorEnvelope {
+    const codePrefix = this.domain === 'CLI' ? 'PN-CLI-' : 'PN-RUN-';
+    return {
+      ok: false as const,
+      code: `${codePrefix}${this.code}`,
+      domain: this.domain,
+      severity: this.severity,
+      summary: this.message,
+      why: this.why,
+      fix: this.fix,
+      where: this.where,
+      meta: this.meta,
+      docsUrl: this.docsUrl,
+    };
+  }
+
+  /**
+   * Type guard to check if an error is a CliStructuredError.
+   * Uses duck-typing to work across module boundaries where instanceof may fail.
+   */
+  static is(error: unknown): error is CliStructuredError {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const candidate = error as CliStructuredError;
+    return (
+      candidate.name === 'CliStructuredError' &&
+      typeof candidate.code === 'string' &&
+      (candidate.domain === 'CLI' || candidate.domain === 'RUN') &&
+      typeof candidate.toEnvelope === 'function'
+    );
+  }
+}
+
+// ============================================================================
+// Config Errors (PN-CLI-4001-4007)
+// ============================================================================
+
+/**
+ * Config file not found or missing.
+ */
+export function errorConfigFileNotFound(
+  configPath?: string,
+  options?: {
+    readonly why?: string;
+  },
+): CliStructuredError {
+  return new CliStructuredError('4001', 'Config file not found', {
+    domain: 'CLI',
+    ...(options?.why ? { why: options.why } : { why: 'Config file not found' }),
+    fix: "Run 'prisma-next init' to create a config file",
+    docsUrl: 'https://prisma-next.dev/docs/cli/config',
+    ...(configPath ? { where: { path: configPath } } : {}),
+  });
+}
+
+/**
+ * Contract configuration missing from config.
+ */
+export function errorContractConfigMissing(options?: {
+  readonly why?: string;
+}): CliStructuredError {
+  return new CliStructuredError('4002', 'Contract configuration missing', {
+    domain: 'CLI',
+    why: options?.why ?? 'The contract configuration is required for emit',
+    fix: 'Add contract configuration to your prisma-next.config.ts',
+    docsUrl: 'https://prisma-next.dev/docs/cli/contract-emit',
+  });
+}
+
+/**
+ * Contract validation failed.
+ */
+export function errorContractValidationFailed(
+  reason: string,
+  options?: {
+    readonly where?: { readonly path?: string; readonly line?: number };
+  },
+): CliStructuredError {
+  return new CliStructuredError('4003', 'Contract validation failed', {
+    domain: 'CLI',
+    why: reason,
+    fix: 'Re-run `prisma-next contract emit`, or fix the contract file and try again',
+    docsUrl: 'https://prisma-next.dev/docs/contracts',
+    ...(options?.where ? { where: options.where } : {}),
+  });
+}
+
+/**
+ * File not found.
+ */
+export function errorFileNotFound(
+  filePath: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+    readonly docsUrl?: string;
+  },
+): CliStructuredError {
+  return new CliStructuredError('4004', 'File not found', {
+    domain: 'CLI',
+    why: options?.why ?? `File not found: ${filePath}`,
+    fix: options?.fix ?? 'Check that the file path is correct',
+    where: { path: filePath },
+    ...(options?.docsUrl ? { docsUrl: options.docsUrl } : {}),
+  });
+}
+
+/**
+ * Database connection is required but not provided.
+ */
+export function errorDatabaseConnectionRequired(options?: {
+  readonly why?: string;
+  readonly commandName?: string;
+  readonly retryCommand?: string;
+}): CliStructuredError {
+  const runHint = options?.retryCommand
+    ? `Run \`${options.retryCommand}\``
+    : options?.commandName
+      ? `Run \`prisma-next ${options.commandName} --db <url>\``
+      : 'Provide `--db <url>`';
+  return new CliStructuredError('4005', 'Database connection is required', {
+    domain: 'CLI',
+    why: options?.why ?? 'Database connection is required for this command',
+    fix: `${runHint}, or set \`db: { connection: "postgres://…" }\` in prisma-next.config.ts`,
+  });
+}
+
+/**
+ * Query runner factory is required but not provided in config.
+ */
+export function errorQueryRunnerFactoryRequired(options?: {
+  readonly why?: string;
+}): CliStructuredError {
+  return new CliStructuredError('4006', 'Query runner factory is required', {
+    domain: 'CLI',
+    why: options?.why ?? 'Config.db.queryRunnerFactory is required for db verify',
+    fix: 'Add db.queryRunnerFactory to prisma-next.config.ts',
+    docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',
+  });
+}
+
+/**
+ * Family verify.readMarker is required but not provided.
+ */
+export function errorFamilyReadMarkerSqlRequired(options?: {
+  readonly why?: string;
+}): CliStructuredError {
+  return new CliStructuredError('4007', 'Family readMarker() is required', {
+    domain: 'CLI',
+    why: options?.why ?? 'Family verify.readMarker is required for db verify',
+    fix: 'Ensure family.verify.readMarker() is exported by your family package',
+    docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',
+  });
+}
+
+/**
+ * JSON output format not supported.
+ */
+export function errorJsonFormatNotSupported(options: {
+  readonly command: string;
+  readonly format: string;
+  readonly supportedFormats: readonly string[];
+}): CliStructuredError {
+  return new CliStructuredError('4008', 'Unsupported JSON format', {
+    domain: 'CLI',
+    why: `The ${options.command} command does not support --json ${options.format}`,
+    fix: `Use --json ${options.supportedFormats.join(' or ')}, or omit --json for human output`,
+    meta: {
+      command: options.command,
+      format: options.format,
+      supportedFormats: options.supportedFormats,
+    },
+  });
+}
+
+/**
+ * Driver is required for DB-connected commands but not provided.
+ */
+export function errorDriverRequired(options?: { readonly why?: string }): CliStructuredError {
+  return new CliStructuredError('4010', 'Driver is required for DB-connected commands', {
+    domain: 'CLI',
+    why: options?.why ?? 'Config.driver is required for DB-connected commands',
+    fix: 'Add a control-plane driver to prisma-next.config.ts (e.g. import a driver descriptor and set `driver: postgresDriver`)',
+    docsUrl: 'https://prisma-next.dev/docs/cli/config',
+  });
+}
+
+/**
+ * Contract requires extension packs that are not provided by config descriptors.
+ */
+export function errorContractMissingExtensionPacks(options: {
+  readonly missingExtensionPacks: readonly string[];
+  readonly providedComponentIds: readonly string[];
+}): CliStructuredError {
+  const missing = [...options.missingExtensionPacks].sort();
+  return new CliStructuredError('4011', 'Missing extension packs in config', {
+    domain: 'CLI',
+    why:
+      missing.length === 1
+        ? `Contract requires extension pack '${missing[0]}', but CLI config does not provide a matching descriptor.`
+        : `Contract requires extension packs ${missing.map((p) => `'${p}'`).join(', ')}, but CLI config does not provide matching descriptors.`,
+    fix: 'Add the missing extension descriptors to `extensions` in prisma-next.config.ts',
+    docsUrl: 'https://prisma-next.dev/docs/cli/config',
+    meta: {
+      missingExtensionPacks: missing,
+      providedComponentIds: [...options.providedComponentIds].sort(),
+    },
+  });
+}
+
+/**
+ * Migration planning failed due to conflicts.
+ */
+export function errorMigrationPlanningFailed(options: {
+  readonly conflicts: readonly CliErrorConflict[];
+  readonly why?: string;
+}): CliStructuredError {
+  const conflictSummaries = options.conflicts.map((c) => c.summary);
+  const computedWhy = options.why ?? conflictSummaries.join('\n');
+
+  const conflictFixes = options.conflicts
+    .map((c) => c.why)
+    .filter((why): why is string => typeof why === 'string');
+  const computedFix =
+    conflictFixes.length > 0
+      ? conflictFixes.join('\n')
+      : 'Use `db verify --schema-only` to inspect conflicts, or ensure the database is empty';
+
+  return new CliStructuredError('4020', 'Migration planning failed', {
+    domain: 'CLI',
+    why: computedWhy,
+    fix: computedFix,
+    meta: { conflicts: options.conflicts },
+    docsUrl: 'https://prisma-next.dev/docs/cli/db-init',
+  });
+}
+
+/**
+ * Target does not support migrations (missing createPlanner/createRunner).
+ */
+export function errorTargetMigrationNotSupported(options?: {
+  readonly why?: string;
+}): CliStructuredError {
+  return new CliStructuredError('4021', 'Target does not support migrations', {
+    domain: 'CLI',
+    why: options?.why ?? 'The configured target does not provide migration planner/runner',
+    fix: 'Select a target that provides migrations (it must export `target.migrations` for db init)',
+    docsUrl: 'https://prisma-next.dev/docs/cli/db-init',
+  });
+}
+
+/**
+ * Config validation error (missing required fields).
+ */
+export function errorConfigValidation(
+  field: string,
+  options?: {
+    readonly why?: string;
+  },
+): CliStructuredError {
+  return new CliStructuredError('4009', 'Config validation error', {
+    domain: 'CLI',
+    why: options?.why ?? `Config must have a "${field}" field`,
+    fix: 'Check your prisma-next.config.ts and ensure all required fields are provided',
+    docsUrl: 'https://prisma-next.dev/docs/cli/config',
+  });
+}
+
+// ============================================================================
+// Generic Error
+// ============================================================================
+
+/**
+ * Generic unexpected error.
+ */
+export function errorUnexpected(
+  message: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+  },
+): CliStructuredError {
+  return new CliStructuredError('4999', 'Unexpected error', {
+    domain: 'CLI',
+    why: options?.why ?? message,
+    fix: options?.fix ?? 'Check the error message and try again',
+  });
+}

package/src/execution.ts

@@ -0,0 +1,159 @@
+import type {
+  SchemaIssue,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/framework-components/control';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { CliStructuredError } from './control';
+
+// ============================================================================
+// Runtime Errors (PN-RUN-3000-3030)
+// ============================================================================
+
+/**
+ * Contract marker not found in database.
+ */
+export function errorMarkerMissing(options?: { readonly why?: string }): CliStructuredError {
+  return new CliStructuredError('3001', 'Database not signed', {
+    domain: 'RUN',
+    why: options?.why ?? 'No database signature (marker) found',
+    fix: 'Run `prisma-next db sign --db <url>` to sign the database',
+  });
+}
+
+/**
+ * Contract hash does not match database marker.
+ */
+export function errorHashMismatch(options?: {
+  readonly why?: string;
+  readonly expected?: string;
+  readonly actual?: string;
+}): CliStructuredError {
+  return new CliStructuredError('3002', 'Hash mismatch', {
+    domain: 'RUN',
+    why: options?.why ?? 'Contract hash does not match database marker',
+    fix: 'Migrate database or re-sign if intentional',
+    ...(options?.expected !== undefined || options?.actual !== undefined
+      ? {
+          meta: {
+            ...ifDefined('expected', options?.expected),
+            ...ifDefined('actual', options?.actual),
+          },
+        }
+      : {}),
+  });
+}
+
+/**
+ * Contract target does not match config target.
+ */
+export function errorTargetMismatch(
+  expected: string,
+  actual: string,
+  options?: {
+    readonly why?: string;
+  },
+): CliStructuredError {
+  return new CliStructuredError('3003', 'Target mismatch', {
+    domain: 'RUN',
+    why:
+      options?.why ??
+      `Contract target does not match config target (expected: ${expected}, actual: ${actual})`,
+    fix: 'Align contract target and config target',
+    meta: { expected, actual },
+  });
+}
+
+/**
+ * Database marker is required but not found.
+ * Used by commands that require a pre-existing marker as a precondition.
+ */
+export function errorMarkerRequired(options?: {
+  readonly why?: string;
+  readonly fix?: string;
+}): CliStructuredError {
+  return new CliStructuredError('3010', 'Database must be signed first', {
+    domain: 'RUN',
+    why: options?.why ?? 'No database signature (marker) found',
+    fix: options?.fix ?? 'Run `prisma-next db init` first to sign the database',
+  });
+}
+
+/**
+ * Schema verification found mismatches between the database and the contract.
+ * The full verification tree is preserved in `meta.verificationResult`.
+ */
+export function errorSchemaVerificationFailed(options: {
+  readonly summary: string;
+  readonly verificationResult: VerifyDatabaseSchemaResult;
+  readonly issues?: readonly SchemaIssue[];
+}): CliStructuredError {
+  return new CliStructuredError('3004', options.summary, {
+    domain: 'RUN',
+    why: 'Database schema does not satisfy the contract',
+    fix: 'Run `prisma-next db update` to reconcile, or adjust your contract to match the database',
+    meta: {
+      verificationResult: options.verificationResult,
+      ...ifDefined('issues', options.issues),
+    },
+  });
+}
+
+/**
+ * Migration runner failed during execution.
+ */
+export function errorRunnerFailed(
+  summary: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+    readonly meta?: Record<string, unknown>;
+  },
+): CliStructuredError {
+  return new CliStructuredError('3020', summary, {
+    domain: 'RUN',
+    why: options?.why ?? 'Migration runner failed',
+    fix: options?.fix ?? 'Inspect the reported conflict and reconcile schema drift',
+    ...(options?.meta ? { meta: options.meta } : {}),
+  });
+}
+
+/** Error code for destructive changes that require explicit confirmation. */
+export const ERROR_CODE_DESTRUCTIVE_CHANGES = '3030';
+
+/**
+ * Destructive operations require explicit confirmation via -y/--yes.
+ */
+export function errorDestructiveChanges(
+  summary: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+    readonly meta?: Record<string, unknown>;
+  },
+): CliStructuredError {
+  return new CliStructuredError(ERROR_CODE_DESTRUCTIVE_CHANGES, summary, {
+    domain: 'RUN',
+    why: options?.why ?? 'Planned operations include destructive changes that require confirmation',
+    fix: options?.fix ?? 'Re-run with `-y` to apply, or use `--dry-run` to preview first',
+    ...(options?.meta ? { meta: options.meta } : {}),
+  });
+}
+
+/**
+ * Generic runtime error.
+ */
+export function errorRuntime(
+  summary: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+    readonly meta?: Record<string, unknown>;
+  },
+): CliStructuredError {
+  return new CliStructuredError('3000', summary, {
+    domain: 'RUN',
+    ...(options?.why ? { why: options.why } : { why: 'Verification failed' }),
+    ...(options?.fix ? { fix: options.fix } : { fix: 'Check contract and database state' }),
+    ...(options?.meta ? { meta: options.meta } : {}),
+  });
+}

package/src/exports/control.ts

@@ -0,0 +1,18 @@
+export type { CliErrorConflict, CliErrorEnvelope } from '../control';
+export {
+  CliStructuredError,
+  errorConfigFileNotFound,
+  errorConfigValidation,
+  errorContractConfigMissing,
+  errorContractMissingExtensionPacks,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFamilyReadMarkerSqlRequired,
+  errorFileNotFound,
+  errorJsonFormatNotSupported,
+  errorMigrationPlanningFailed,
+  errorQueryRunnerFactoryRequired,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+} from '../control';

package/src/exports/execution.ts

@@ -0,0 +1,11 @@
+export {
+  ERROR_CODE_DESTRUCTIVE_CHANGES,
+  errorDestructiveChanges,
+  errorHashMismatch,
+  errorMarkerMissing,
+  errorMarkerRequired,
+  errorRunnerFailed,
+  errorRuntime,
+  errorSchemaVerificationFailed,
+  errorTargetMismatch,
+} from '../execution';