fix(core): preserve unmapped ZK error codes

docs/errors.md

@@ -102,6 +102,10 @@ error-code table because they are not errors.
 
 ## ZK
 
+| `CAATINGA_ZK_VK_REQUIRED`          | A zero-knowledge operation requires a verification key.                              | The requested ZK operation was started without a verification key artifact. | Provide the verification key generated for the circuit and retry. | Fail CI and verify the circuit artifacts are complete. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
+| `CAATINGA_ZK_INVOKE_FAILED`        | A zero-knowledge contract invocation failed.                                         | The verifier invocation was rejected or returned an invocation error. | Inspect the contract and invocation arguments, then retry with valid proof inputs. | Fail CI and inspect verifier invocation diagnostics. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
+| `CAATINGA_ZK_DOWNLOAD_FAILED`      | A required zero-knowledge artifact could not be downloaded.                            | The artifact host was unavailable or the download failed. | Check network access and artifact availability, then retry. | Fail CI and verify artifact hosting. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
+| `CAATINGA_ZK_UNSUPPORTED_PLATFORM` | A zero-knowledge operation is unavailable on the current platform.                    | The requested ZK tool or artifact has no supported build for the current operating system or architecture. | Run the operation on a supported platform or provide a compatible tool build. | Fail CI on unsupported release targets. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
 | Code                               | Meaning                                                                                  | Common cause                                                                                                                                                                                                                                                                                                                                           | User action                                                                                                                                                                                                                                                | CI/release action                                                                           | Versioning note                                                                                                                                                                |
 | ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `CAATINGA_ZK_VERIFICATION_FAILED`  | On-chain ZK proof verification returned `false`.                                         | The submitted proof does not match the verification key or public signals.                                                                                                                                                                                                                                                                             | Regenerate the proof with correct inputs (`ctg zk prove`) and retry. Inspect `public.json` to confirm the expected public signals.                                                                                                                         | Fail CI and verify circuit inputs and proof artifacts are consistent.                       | Public code; adding a new code is minor, removal/rename/meaning change is major.                                                                                               |

packages/core/src/errors/CaatingaError.ts

@@ -17,6 +17,10 @@ export class CaatingaError extends Error {
 const ZK_ERROR_CODE_MAP: Record<string, CaatingaErrorCodeValue> = {
   ZK_VERIFY_FAILED: CaatingaErrorCode.ZK_VERIFICATION_FAILED,
   ZK_DEV_CEREMONY_BLOCKED: CaatingaErrorCode.ZK_DEV_CEREMONY_BLOCKED,
+  ZK_VK_REQUIRED: CaatingaErrorCode.ZK_VK_REQUIRED,
+  ZK_INVOKE_FAILED: CaatingaErrorCode.ZK_INVOKE_FAILED,
+  ZK_DOWNLOAD_FAILED: CaatingaErrorCode.ZK_DOWNLOAD_FAILED,
+  ZK_UNSUPPORTED_PLATFORM: CaatingaErrorCode.ZK_UNSUPPORTED_PLATFORM,
 };
 
 export function toCaatingaError(error: unknown): CaatingaError {

packages/core/src/errors/CaatingaErrorCode.ts

@@ -54,6 +54,10 @@ export const CaatingaErrorCode = {
   TEMPLATE_INCOMPATIBLE: "CAATINGA_TEMPLATE_INCOMPATIBLE",
   ZK_VERIFICATION_FAILED: "CAATINGA_ZK_VERIFICATION_FAILED",
   ZK_DEV_CEREMONY_BLOCKED: "CAATINGA_ZK_DEV_CEREMONY_BLOCKED",
+  ZK_VK_REQUIRED: "CAATINGA_ZK_VK_REQUIRED",
+  ZK_INVOKE_FAILED: "CAATINGA_ZK_INVOKE_FAILED",
+  ZK_DOWNLOAD_FAILED: "CAATINGA_ZK_DOWNLOAD_FAILED",
+  ZK_UNSUPPORTED_PLATFORM: "CAATINGA_ZK_UNSUPPORTED_PLATFORM",
   DOCTOR_PARTIAL_DEPLOY: "CAATINGA_DOCTOR_PARTIAL_DEPLOY",
   ROLLBACK_TARGET_NOT_FOUND: "CAATINGA_ROLLBACK_TARGET_NOT_FOUND",
   ESTIMATE_FAILED: "CAATINGA_ESTIMATE_FAILED",

packages/core/src/errors/error-surface.test.ts

@@ -254,6 +254,22 @@ const productionTriggerTests: Record<CaatingaErrorCodeValue, { file: string; tri
     file: "packages/core/src/errors/to-caatinga-error.test.ts",
     trigger: "toCaatingaError(",
   },
+  [CaatingaErrorCode.ZK_VK_REQUIRED]: {
+    file: "packages/core/src/errors/to-caatinga-error.test.ts",
+    trigger: "toCaatingaError(",
+  },
+  [CaatingaErrorCode.ZK_INVOKE_FAILED]: {
+    file: "packages/core/src/errors/to-caatinga-error.test.ts",
+    trigger: "toCaatingaError(",
+  },
+  [CaatingaErrorCode.ZK_DOWNLOAD_FAILED]: {
+    file: "packages/core/src/errors/to-caatinga-error.test.ts",
+    trigger: "toCaatingaError(",
+  },
+  [CaatingaErrorCode.ZK_UNSUPPORTED_PLATFORM]: {
+    file: "packages/core/src/errors/to-caatinga-error.test.ts",
+    trigger: "toCaatingaError(",
+  },
   [CaatingaErrorCode.DOCTOR_PARTIAL_DEPLOY]: {
     file: "packages/core/src/errors/error-codes.test.ts",
     trigger: "CaatingaErrorCode.DOCTOR_PARTIAL_DEPLOY",

packages/core/src/errors/to-caatinga-error.test.ts

@@ -26,4 +26,15 @@ describe("toCaatingaError", () => {
     expect(result.message).toBe("Verifier returned false.");
     expect(result.hint).toBe("Check your proof inputs.");
   });
+
+  it.each([
+    ["ZK_VK_REQUIRED", CaatingaErrorCode.ZK_VK_REQUIRED],
+    ["ZK_INVOKE_FAILED", CaatingaErrorCode.ZK_INVOKE_FAILED],
+    ["ZK_DOWNLOAD_FAILED", CaatingaErrorCode.ZK_DOWNLOAD_FAILED],
+    ["ZK_UNSUPPORTED_PLATFORM", CaatingaErrorCode.ZK_UNSUPPORTED_PLATFORM],
+  ])("should_map_ZkError_%s", (sourceCode, expectedCode) => {
+    const result = toCaatingaError(Object.assign(new Error("zk failure"), { code: sourceCode }));
+
+    expect(result.code).toBe(expectedCode);
+  });
 });