authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-06-19 22:53:48-07:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-06-20 05:53:48+00:00
log6d2dae0627897e84e79bc7d2f164a564357fe9b0
tree309a7cc6747380c6046dd4cf2bf6b19d01116969
parent10a8d3fbd9c44fef2e23a213c61e8b517067e38b
signature Signed by PGP key B5690EEEBB952194

Preserve full cause chains in Effect error checks (#3215)

Co-authored-by: codex <codex@users.noreply.github.com>

1 files changed, 3 insertions(+), 2 deletions(-)

.macroscope/check-run-agents/effect-service-conventions.md+3-2
......@@ -47,8 +47,9 @@ Review changed TypeScript and directly affected call sites for the conventions b
4747
4848- Define service failures with `Schema.TaggedErrorClass` and structured attributes. Derive `message` from those attributes rather than storing an unstructured message as the only data.
4949- `Schema.Defect()` is not a substitute for modeling an error. Flag error classes whose only meaningful field is `cause`, or whose `message` merely stringifies an opaque cause.
50- Capture stable, serializable domain context such as the operation or stage, resource/path or entity identifier, normalized category/status, and a useful detail. Map failures where that context is known instead of wrapping an entire multi-step pipeline in one generic error.
51- Preserve a real underlying `cause` only when it adds diagnostic value, and make it optional supplemental data alongside the structural fields. Never manufacture an `Error` or opaque defect merely to populate `cause`, and do not erase structured upstream errors into `Schema.Defect()`.
50- Capture stable, serializable domain context such as the operation or stage, resource/path or entity identifier, and normalized category/status. Map failures where that context is known instead of wrapping an entire multi-step pipeline in one generic error. Do not add a `detail` field that merely copies `cause.message` and then use it to construct the wrapper message.
51- When translating or wrapping a real failure, preserve the immediate underlying error itself as `cause` alongside the structural fields so the complete error chain and stack remain available. If every construction wraps a failure, `cause` should be required; make it optional only when the same error can legitimately originate without an underlying failure.
52- Derive the wrapper's `message` exclusively from its stable structural attributes, never from `cause`, `cause.message`, or a stringified defect. Do not replace the immediate error with only `error.cause`, erase a structured upstream error into a string, or manufacture an `Error` merely to populate `cause`. Pure validation/domain errors created without an underlying failure do not need a cause.
5253- Split semantically distinct failures into separate error classes when a `reason`, `kind`, `phase`, or similar discriminator is used to choose the user-facing message or drive caller control flow. A discriminator used only for internal diagnostics may remain a field.
5354- Use `Schema.Union` of error classes when a shared schema, predicate, or helper type is useful.
5455- Export direct schema predicates such as `export const isFoo = Schema.is(Foo)`. Flag a private `Schema.is` constant wrapped by a redundant function with the same signature.