authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-06-19 22:39:21-07:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-06-20 05:39:21+00:00
log10a8d3fbd9c44fef2e23a213c61e8b517067e38b
tree664db09efe62e8450e22922939e2437e55c020bd
parent0ad1e9d9e4bf691ad1dcfb5af69de11b0b48047f
signature Signed by PGP key B5690EEEBB952194

Tighten structural Effect error checks (#3213)

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

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

.macroscope/check-run-agents/effect-service-conventions.md+3
......@@ -46,6 +46,9 @@ Review changed TypeScript and directly affected call sites for the conventions b
4646## Errors and predicates
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.
49- `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()`.
4952- 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.
5053- Use `Schema.Union` of error classes when a shared schema, predicate, or helper type is useful.
5154- 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.