From b5333d756cab900911c1b635e3835d282dbf6019 Mon Sep 17 00:00:00 2001 From: Sakariyah Abdulhazeem <150973162+zeemscript@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:09:33 +0100 Subject: [PATCH 1/3] fix(core): bound transient HTTP status matching --- .../core/src/shell/is-transient-command-failure.test.ts | 6 ++++++ packages/core/src/shell/is-transient-command-failure.ts | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/core/src/shell/is-transient-command-failure.test.ts b/packages/core/src/shell/is-transient-command-failure.test.ts index e22ec0f2..a9820238 100644 --- a/packages/core/src/shell/is-transient-command-failure.test.ts +++ b/packages/core/src/shell/is-transient-command-failure.test.ts @@ -15,6 +15,12 @@ describe("isTransientCommandFailure", () => { expect(isTransientCommandFailure("503 Service Unavailable")).toBe(true); }); + it("should_return_false_when_status_code_is_part_of_a_larger_number", () => { + expect(isTransientCommandFailure("port 4290 is already in use")).toBe(false); + expect(isTransientCommandFailure("test 5030 failed")).toBe(false); + expect(isTransientCommandFailure("build 5023 failed")).toBe(false); + }); + it("should_return_true_when_log_contains_connection_reset", () => { expect(isTransientCommandFailure("ECONNRESET")).toBe(true); }); diff --git a/packages/core/src/shell/is-transient-command-failure.ts b/packages/core/src/shell/is-transient-command-failure.ts index 3ba34de9..9d537a9e 100644 --- a/packages/core/src/shell/is-transient-command-failure.ts +++ b/packages/core/src/shell/is-transient-command-failure.ts @@ -16,7 +16,7 @@ export const NO_RETRY_ERROR_CODES: ReadonlySet = new Set ]); const TRANSIENT_COMMAND_FAILURE_PATTERN = - /timeout|i\/o timeout|econnreset|connection reset|503|502|429|rate limit|temporar|bad gateway|fetch failed|network error|unavailable|tx_?bad_?seq|bad sequence|bad seq/i; + /timeout|i\/o timeout|econnreset|connection reset|\b503\b|\b502\b|\b429\b|rate limit|temporar|bad gateway|fetch failed|network error|unavailable|tx_?bad_?seq|bad sequence|bad seq/i; /** * Decides retryability from raw log text — captured CLI output, as passed by the From 24368a55329a1fe45e3c35894764f1863c127042 Mon Sep 17 00:00:00 2001 From: Sakariyah Abdulhazeem <150973162+zeemscript@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:09:33 +0100 Subject: [PATCH 2/3] fix(core): preserve unmapped ZK error codes --- docs/errors.md | 4 ++++ packages/core/src/errors/CaatingaError.ts | 4 ++++ packages/core/src/errors/CaatingaErrorCode.ts | 4 ++++ packages/core/src/errors/error-surface.test.ts | 16 ++++++++++++++++ .../core/src/errors/to-caatinga-error.test.ts | 11 +++++++++++ 5 files changed, 39 insertions(+) diff --git a/docs/errors.md b/docs/errors.md index 8c274934..2deffdc7 100644 --- a/docs/errors.md +++ b/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. | diff --git a/packages/core/src/errors/CaatingaError.ts b/packages/core/src/errors/CaatingaError.ts index bbb24e2e..0a119f9f 100644 --- a/packages/core/src/errors/CaatingaError.ts +++ b/packages/core/src/errors/CaatingaError.ts @@ -17,6 +17,10 @@ export class CaatingaError extends Error { const ZK_ERROR_CODE_MAP: Record = { 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 { diff --git a/packages/core/src/errors/CaatingaErrorCode.ts b/packages/core/src/errors/CaatingaErrorCode.ts index 5bdb5184..6ae15142 100644 --- a/packages/core/src/errors/CaatingaErrorCode.ts +++ b/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", diff --git a/packages/core/src/errors/error-surface.test.ts b/packages/core/src/errors/error-surface.test.ts index 34efce1f..ab9f2fa8 100644 --- a/packages/core/src/errors/error-surface.test.ts +++ b/packages/core/src/errors/error-surface.test.ts @@ -254,6 +254,22 @@ const productionTriggerTests: Record { 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); + }); }); From bccd689e4fd13c292004ea844cdc21e820e5b20b Mon Sep 17 00:00:00 2001 From: Sakariyah Abdulhazeem <150973162+zeemscript@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:11:26 +0100 Subject: [PATCH 3/3] Revert "fix(core): bound transient HTTP status matching" This reverts commit b5333d756cab900911c1b635e3835d282dbf6019. --- .../core/src/shell/is-transient-command-failure.test.ts | 6 ------ packages/core/src/shell/is-transient-command-failure.ts | 2 +- 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/packages/core/src/shell/is-transient-command-failure.test.ts b/packages/core/src/shell/is-transient-command-failure.test.ts index a9820238..e22ec0f2 100644 --- a/packages/core/src/shell/is-transient-command-failure.test.ts +++ b/packages/core/src/shell/is-transient-command-failure.test.ts @@ -15,12 +15,6 @@ describe("isTransientCommandFailure", () => { expect(isTransientCommandFailure("503 Service Unavailable")).toBe(true); }); - it("should_return_false_when_status_code_is_part_of_a_larger_number", () => { - expect(isTransientCommandFailure("port 4290 is already in use")).toBe(false); - expect(isTransientCommandFailure("test 5030 failed")).toBe(false); - expect(isTransientCommandFailure("build 5023 failed")).toBe(false); - }); - it("should_return_true_when_log_contains_connection_reset", () => { expect(isTransientCommandFailure("ECONNRESET")).toBe(true); }); diff --git a/packages/core/src/shell/is-transient-command-failure.ts b/packages/core/src/shell/is-transient-command-failure.ts index 9d537a9e..3ba34de9 100644 --- a/packages/core/src/shell/is-transient-command-failure.ts +++ b/packages/core/src/shell/is-transient-command-failure.ts @@ -16,7 +16,7 @@ export const NO_RETRY_ERROR_CODES: ReadonlySet = new Set ]); const TRANSIENT_COMMAND_FAILURE_PATTERN = - /timeout|i\/o timeout|econnreset|connection reset|\b503\b|\b502\b|\b429\b|rate limit|temporar|bad gateway|fetch failed|network error|unavailable|tx_?bad_?seq|bad sequence|bad seq/i; + /timeout|i\/o timeout|econnreset|connection reset|503|502|429|rate limit|temporar|bad gateway|fetch failed|network error|unavailable|tx_?bad_?seq|bad sequence|bad seq/i; /** * Decides retryability from raw log text — captured CLI output, as passed by the