Problem
The SDK, services, web application, and repository scripts convert caught values with different combinations of instanceof Error, String(...), handwritten fallbacks, and unstructured response bodies. This loses error codes and causes, produces inconsistent user messages, and makes redaction and retry decisions unreliable.
Goal
Introduce one safe unknown-error normalization model and use it at every first-party error boundary.
Requirements
- Define a stable normalized error shape containing name, message, optional code, cause, stack, retryability, and structured context.
- Correctly normalize native errors, thrown strings, plain objects, RPC failures, HTTP failures, and values that cannot be serialized normally.
- Preserve nested causes without infinite recursion.
- Separate operator diagnostics from safe public or UI-facing messages.
- Recursively redact secrets, credentials, authorization data, cookies, private keys, and tokens.
- Preserve existing domain-specific error classes and codes rather than flattening them.
- Replace ad hoc caught-value conversion across first-party runtime modules, UI boundaries, CLIs, and operational scripts.
- Make normalized errors easy to assert without snapshotting unstable stack paths.
- Add a repository guard that catches newly introduced ad hoc caught-value stringification in the migrated scope.
- Add focused tests for every supported thrown-value shape, cause chains, redaction, cycles, retryability, and public-message safety.
Acceptance criteria
- Every migrated catch boundary uses the shared normalization model.
- Domain codes and causes survive normalization.
- Public responses and UI messages contain no stacks or sensitive context.
- Operator diagnostics remain actionable.
- A repository-wide search finds no remaining ad hoc caught-value conversion in scope.
- New tests, affected workspace tests and typechecks, and the regression guard pass.
- The PR avoids unrelated error-message rewrites.
Suggested implementation prompt
Implement this issue end to end from the current main branch. Inventory all first-party catch boundaries and ad hoc unknown-error conversions. Design a small normalized error model that preserves domain errors, codes, causes, stacks, retryability, and structured context while producing a separately safe public message. Add cycle-safe serialization and recursive redaction, migrate every inventoried boundary, add comprehensive tests and a regression guard, verify affected workspaces, and keep behavior changes limited to consistent and safer error handling.
Problem
The SDK, services, web application, and repository scripts convert caught values with different combinations of
instanceof Error,String(...), handwritten fallbacks, and unstructured response bodies. This loses error codes and causes, produces inconsistent user messages, and makes redaction and retry decisions unreliable.Goal
Introduce one safe unknown-error normalization model and use it at every first-party error boundary.
Requirements
Acceptance criteria
Suggested implementation prompt