Preserve observable Effect error semantics

[juliusmarminge]

Summary

• allow precise error tags to carry real causes without invented singleton fields
• require structural refactors to preserve caller-visible error messages
• prefer distinct tags when existing messages encode distinct behavior

Validation

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

---

Note

Low Risk
Documentation-only change to review-agent conventions; no runtime, API, or application code is modified.

Overview
Updates the Effect service conventions doc used by Macroscope check-run agents so reviews enforce observable error behavior, not just structural shape.

Schema.Defect() guidance is expanded: defects must still identify failures structurally; precise error tags may keep a real cause without inventing redundant singleton fields when there is no extra variable context, while still capturing path, resource, or entity context at the wrap site.

A new rule treats caller-visible error messages (HTTP/RPC, persisted state, UI) as behavior that must survive structural refactors. Existing distinct messages are treated as evidence that failures should stay separate error tags rather than being folded into a generic operation error with redundant discriminators.

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

Note

Preserve caller-visible error message semantics during structural refactors

Updates effect-service-conventions.md with two new guidelines for Effect error handling:

• Clarifies that a precise error tag may wrap a real cause directly without adding a redundant single-field context object when no extra variable data exists.
• Adds a rule to treat caller-visible error messages (HTTP/RPC responses, persisted state, UI) as observable behavior: preserve distinct messages during structural refactors and use existing distinct messages as evidence to keep separate error tags rather than collapsing them into a generic error.

^{Macroscope summarized 53629c0.}

[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: 451603ef-780e-40fd-bdcf-0a51ff77afd4

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/preserve-observable-effect-error-messages

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR modifies Macroscope configuration files (.macroscope/check-run-agents/effect-service-conventions.md), which control how automated code review behaves in this repository. Changes to these files require human review to verify the intended review behavior.

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