Reusable Effect functions have drifted back to wrappers around Effect.gen, making operation boundaries and tracing inconsistent. The repository guidance did not clearly preserve the earlier Effect.fn migration.
Document named Effect.fn as the default for reusable operations, reserve Effect.fnUntraced for explained hot paths or existing spans, and retain Effect.gen for inline programs and layer construction. Keep the contributor guidance and review-agent conventions aligned.
Effect.fn("Service.operation") is the default for reusable service and I/O operations, giving each operation a stable span.Effect.fnUntraced is reserved for explained per-event or per-chunk work, tight loops, long-running pollers, or helpers that must retain an existing span. Inline programs and layer construction can still use Effect.gen. This layer documents the choices; it does not change runtime code.Maintainer-requested foundation of the Effect function migration stack, authored by juliusmarminge (maintainer list). This layer only clarifies the established Effect coding convention in contributor and review documentation. It introduces no feature, product default, or runtime behavior change, so the prior product-direction discussion requirement does not apply. No separate approval discussion is required for this documentation-only scope.
Reviewed AGENTS.md, docs/internals/effect-services.md, and .macroscope/check-run-agents/effect-service-conventions.md together for consistent tracing and execution-semantics guidance. All eight required checks passed on this head. No runtime tests or UI screenshots are applicable to this documentation-only layer.
| View | Added lines | Removed lines |
|---|---|---|
| Normal diff | 34 | 0 |
Whitespace ignored (git diff -w) | 34 | 0 |
Review the files with whitespace hidden. These counts and the patch below are a snapshot of 8e658fb, compared with this PR's merge base. Whitespace-only changes are ignored; line wrapping and other textual changes still count.
| 1 | diff --git a/.macroscope/check-run-agents/effect-service-conventions.md b/.macroscope/check-run-agents/effect-service-conventions.md |
| 2 | index 624018f781..f7cef3929a 100644 |
| 3 | --- a/.macroscope/check-run-agents/effect-service-conventions.md |
| 4 | +++ b/.macroscope/check-run-agents/effect-service-conventions.md |
| 5 | @@ -46,0 +47,12 @@ Review changed TypeScript for the conventions below. They apply when a pull requ |
| 6 | +## Effect functions and tracing |
| 7 | + |
| 8 | +- Reusable functions use named `Effect.fn("Service.operation")`, not functions wrapping |
| 9 | + `Effect.gen`. Inline programs, callbacks, and layer construction can keep `Effect.gen`. |
| 10 | +- Named `Effect.fn` creates a span; the unnamed form does not. Default to named spans for service |
| 11 | + operations and I/O. `Effect.fnUntraced` is deliberate for per-chunk/per-event work, tight loops, |
| 12 | + or helpers duplicating an existing tracing boundary; require a nearby reason for new uses. |
| 13 | +- Preserve existing span names/options and avoid adding duplicate spans. Pass combinators after |
| 14 | + the generator body; transforms receive the original function arguments after the effect. |
| 15 | +- Preserve generic signatures, laziness, resource scope, and interruption behavior. An explicit |
| 16 | + generator return type is `Effect.fn.Return<A, E, R>`. |
| 17 | + |
| 18 | diff --git a/AGENTS.md b/AGENTS.md |
| 19 | index 810d26e313..4dc489fafa 100644 |
| 20 | --- a/AGENTS.md |
| 21 | +++ b/AGENTS.md |
| 22 | @@ -155,0 +156,6 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/ |
| 23 | +- Reusable Effect functions use `Effect.fn("Service.operation")` with a stable span name, not a |
| 24 | + function wrapping `Effect.gen`. Keep `Effect.gen` for inline programs and layer construction. |
| 25 | + Use `Effect.fnUntraced` only when spans would be too frequent (stream chunks, per-event |
| 26 | + projection, tight loops) or duplicate an existing tracing boundary; explain that choice nearby. |
| 27 | + Named `Effect.fn` creates a span; the unnamed form does not. Preserve existing span names and |
| 28 | + options, and pass combinators as additional function-builder arguments. |
| 29 | diff --git a/docs/internals/effect-services.md b/docs/internals/effect-services.md |
| 30 | index c29016dbf8..f2d93b9d8e 100644 |
| 31 | --- a/docs/internals/effect-services.md |
| 32 | +++ b/docs/internals/effect-services.md |
| 33 | @@ -92,0 +93,16 @@ export const layer = Layer.effect(Foo, make); |
| 34 | +## Effect functions and tracing |
| 35 | + |
| 36 | +Reusable functions use `Effect.fn("Service.operation")`, not an arrow or declaration returning |
| 37 | +`Effect.gen`. The named form creates a span; `Effect.fn(function* ...)` only captures stack |
| 38 | +frames. Keep `Effect.gen` for inline programs, callbacks, and layer construction. |
| 39 | + |
| 40 | +Default to named spans for service operations and I/O. Use `Effect.fnUntraced` deliberately for |
| 41 | +per-chunk/per-event work, tight loops, or helpers already covered by the same operation's span. |
| 42 | +Explain the reason beside the function or a group of related functions. A loop is not by itself |
| 43 | +an exemption: its outer operation can still have a useful span without tracing each iteration. |
| 44 | +Preserve existing span names and options instead of adding a second span for the same operation. |
| 45 | + |
| 46 | +Pass effect combinators after the generator body. A transform that needs the function's input |
| 47 | +receives it after the effect. Use `Effect.fn.Return<A, E, R>` when the generator needs an explicit |
| 48 | +return type, and preserve generic parameters, laziness, scope, and interruption behavior. |
| 49 | + |
Model: GPT-6.1 Sol. Harness: Codex.
Verdict: Needs Human Approval
Macroscope's review found this PR requires human approval — The PR adds Effect tracing conventions to repository documentation and to a Macroscope check-run agent configuration. The documentation is non-runtime, but the .macroscope change alters automated review behavior and requires human review under the repository criteria.
You can add or adjust custom eligibility rules. Learn more.
No actionable comments were generated in the recent review. 🎉
5c4649fa-4dd9-4b6f-8870-31c9d326f666Reviewing files that changed from the base of the PR and between 673c5e3b3c85a7f2cd2df9ed73d6b712328378c6 and 446028b8cb8002ec504fd310f6a0c34550190792.
.macroscope/check-run-agents/effect-service-conventions.mdAGENTS.mddocs/internals/effect-services.mdLimit details: You’ve used all 10 included reviews currently available.
Added conventions for reusable Effect functions, tracing spans, untraced exceptions, combinator placement, and preservation of type and execution semantics across repository guidance and service documentation.
Changes: Effect service conventions
| Layer / File(s) | Summary |
|---|---|
Document Effect function conventions AGENTS.md, docs/internals/effect-services.md, .macroscope/check-run-agents/effect-service-conventions.md | The guidance describes named spans for reusable Effect functions, documented reasons for untraced functions, combinator placement, and preservation of generics and execution semantics. |
Priority: ⬇️ Low
Estimated code review effort: 1 (Trivial) | ~5 minutes
Change: Other
Suggested reviewers: maria-rcks
44602No merge-blocking risk was identified in these documentation-only changes.
| Check name | Status | Explanation |
|---|---|---|
| Title check | Passed | The title clearly and concisely describes the main documentation change: establishing traced Effect function conventions. |
| Linked Issues check | Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | Passed | Check skipped because no linked issues were found for this pull request. |
| Description check | Passed | The description includes all required sections: Problem, Change, Scope and approval, and Verification. It explains the documentation-only scope, approval basis, affected guidance, verification perform… |
Explanation
The description includes all required sections: Problem, Change, Scope and approval, and Verification. It explains the documentation-only scope, approval basis, affected guidance, verification performed, and why runtime tests and screenshots do not apply. It also includes the model and harness used.
Comment @coderabbitai help to get the list of available commands.
Added 1 commit