Tighten structural Effect error checks

[juliusmarminge]

Summary

• teach the Effect service check to flag cause-only Schema.Defect() errors
• require stable, serializable domain context and failure-site mapping
• preserve genuine underlying causes only as supplemental diagnostics

Why

PR #3188 exposed a mechanical refactor pattern that replaced typed failures with opaque defects. The check now enforces structural error modeling instead of accepting an artificial cause field.

Validation

• vp check
• vp run typecheck
• git diff --check

---

Note

Low Risk
Documentation-only change to a check-run agent; no runtime or application code is modified.

Overview
Extends the Effect service conventions check agent (.macroscope/check-run-agents/effect-service-conventions.md) so reviewers flag weak error modeling, not just missing TaggedErrorClass usage.

New Errors and predicates rules require flagging Schema.Defect()-style errors that only carry an opaque cause, insist on stable serializable domain context (operation, resource, category, detail) mapped at the failure site, and clarify that real cause values are optional diagnostics—not manufactured defects and not a replacement for structured upstream errors.

^{Reviewed by Cursor Bugbot for commit c46afb5. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Tighten error modeling guidance in Effect service conventions

Adds three bullet points to the 'Errors and predicates' section of effect-service-conventions.md to clarify correct error modeling:

• Clarifies that Schema.Defect is not a substitute for structured error classes
• Instructs capturing stable, serializable domain context and mapping failures where context is known
• Advises preserving an underlying cause only when diagnostically useful, and avoiding erasing structured upstream errors into Schema.Defect

^{Macroscope summarized c46afb5.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 57e066f1-4633-4489-91df-bed6900f2552

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/effect-service-structural-error-check

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Changes to .macroscope/ configuration files require human review to verify the intended Macroscope review behavior, regardless of how straightforward the additions appear.

^{You can customize Macroscope's approvability policy. Learn more.}