Preserve trace file read causes

[juliusmarminge]

Summary

• represent non-NotFound trace reads as structured TraceFileReadError values with the failed path and exact platform cause
• use catchTags at the platform-error boundary, then recover with Effect.result only at the best-effort diagnostics aggregation boundary
• log the structured failure before recovery and keep the public message path-derived instead of cause-derived

Validation

• vp test apps/server/src/diagnostics/TraceDiagnostics.test.ts (5 passed)
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

---

Note

Low Risk
Scoped to local trace diagnostics reads; behavior for callers is unchanged at the public API except clearer errors and logs, with partial aggregation preserved.

Overview
Trace diagnostics now treat non–not-found filesystem errors as TraceFileReadError effect failures (path, causeTag, and the original PlatformError cause) instead of a 'Failed' success variant from readTraceFile.

At the aggregation boundary, each rotated file read is recovered with Effect.result so partial loads still work: failures emit a warning log annotated with traceFilePath, errorTag, and causeTag, while the public diagnostics.error keeps a path-derived message from TraceFileReadError.message. Tests assert that shape and the logged annotations when one rotated file fails.

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

Note

Preserve trace file read causes as structured errors in TraceDiagnostics

• Introduces TraceFileReadError, a tagged error class with traceFilePath, causeTag, and cause fields, replacing the previous Failed result payload for non-NotFound read errors.
• readTraceFile now fails with TraceFileReadError (instead of returning a Failed result) when a trace file exists but cannot be read, while NotFound still yields a Missing result.
• TraceDiagnostics.read logs a structured warning with traceFilePath, errorTag, and causeTag annotations on failure, and sets diagnostics.error to a standardized message with kind: 'trace-file-read-failed'.
• Behavioral Change: callers relying on the Failed result shape will no longer receive it; failures now propagate as Effect failures and are surfaced in the error summary.

^{Macroscope summarized 626ccfe.}

[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: 50fc60b6-86db-4cc7-a2bb-af92abc2fe9a

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-trace-read-causes

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Self-contained error handling improvement that adds a typed error class and structured logging for trace file read failures. The changes are well-tested and don't alter successful code paths, only improving failure observability.

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

Dismissing prior approval to re-evaluate fdcd091

Dismissing prior approval to re-evaluate 626ccfe