Skip to content

Commit 446028b

Browse files
docs: establish traced Effect function conventions
1 parent ff9f41b commit 446028b

3 files changed

Lines changed: 34 additions & 0 deletions

File tree

‎.macroscope/check-run-agents/effect-service-conventions.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,18 @@ Review changed TypeScript for the conventions below. They apply when a pull requ
4444
- Use plain `make` and `layer` in a module named for its implementation (`BunPtyAdapter.ts`). Keep implementation-specific names when one abstract port module holds several implementations (`makeCloudflaredRelayClient`, `layerCloudflared` in `RelayClient.ts`). `infra/relay/src/db.ts` may keep its inline `Layer.succeed(RelayDb, db)`.
4545
- When a service moves, delete the old files and update every consumer, including orchestration, MCP, tests, and integration harnesses. Do not leave compatibility re-export shims.
4646

47+
## Effect functions and tracing
48+
49+
- Reusable functions use named `Effect.fn("Service.operation")`, not functions wrapping
50+
`Effect.gen`. Inline programs, callbacks, and layer construction can keep `Effect.gen`.
51+
- Named `Effect.fn` creates a span; the unnamed form does not. Default to named spans for service
52+
operations and I/O. `Effect.fnUntraced` is deliberate for per-chunk/per-event work, tight loops,
53+
or helpers duplicating an existing tracing boundary; require a nearby reason for new uses.
54+
- Preserve existing span names/options and avoid adding duplicate spans. Pass combinators after
55+
the generator body; transforms receive the original function arguments after the effect.
56+
- Preserve generic signatures, laziness, resource scope, and interruption behavior. An explicit
57+
generator return type is `Effect.fn.Return<A, E, R>`.
58+
4759
## Dependency acquisition and runtime boundaries
4860

4961
- Production service construction acquires its Effect dependencies from the environment with `yield* Foo.Foo`, and `make`/`layer` types expose those requirements. Flag a factory that takes `Foo["Service"]` (or an object of Effect-returning methods) as a parameter when that value is a service dependency. Passing service instances explicitly in tests is fine; passing pure configuration, immutable domain values, or deliberate callback strategies is not service injection.

‎AGENTS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,12 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
153153
- Client mutations use `createEnvironmentRpcCommand`. Add protected methods to `CLIENT_GUARDED_RPC_SCOPES` in contracts and use the command's `permissionAtom` for UI availability. Grants are checked at execution against the destination environment; the server remains authoritative. Keep raw RPC clients inside `rpc/`, and extend the permission behavior tests when adding a protected method.
154154
- Server features are services; transports stay thin. A `ws.ts` RPC handler, HTTP route, or MCP tool decodes input, calls one service method, and maps errors. See [Effect services](docs/internals/effect-services.md).
155155
- `apps/web/src/components/ui` exports own their look. Pick a `variant` or `size`; do not restyle one with `className`. If none fits and the look is a generic concept, add a variant to the component; a look that belongs to one feature stays in that feature's own component, not in `components/ui`. Layout classes (width, flex, margin, position) belong on the parent. `shadcn/no-restyle` fails lint on violations. See [Web UI](docs/internals/web-ui.md).
156+
- Reusable Effect functions use `Effect.fn("Service.operation")` with a stable span name, not a
157+
function wrapping `Effect.gen`. Keep `Effect.gen` for inline programs and layer construction.
158+
Use `Effect.fnUntraced` only when spans would be too frequent (stream chunks, per-event
159+
projection, tight loops) or duplicate an existing tracing boundary; explain that choice nearby.
160+
Named `Effect.fn` creates a span; the unnamed form does not. Preserve existing span names and
161+
options, and pass combinators as additional function-builder arguments.
156162
- Inferred types over annotations. `any` is the enemy.
157163
- Comments say why: a constraint, an external quirk, or an invariant the code can't show. Don't restate names or signatures, narrate steps, or record history. `t3code/no-low-value-comments` catches the mechanical cases.
158164
- Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.

‎docs/internals/effect-services.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,22 @@ export const layer = Layer.effect(Foo, make);
9090
- **Tests** exercise behavior through the service, with test layers only for external dependencies.
9191
Don't mock the logic under test.
9292

93+
## Effect functions and tracing
94+
95+
Reusable functions use `Effect.fn("Service.operation")`, not an arrow or declaration returning
96+
`Effect.gen`. The named form creates a span; `Effect.fn(function* ...)` only captures stack
97+
frames. Keep `Effect.gen` for inline programs, callbacks, and layer construction.
98+
99+
Default to named spans for service operations and I/O. Use `Effect.fnUntraced` deliberately for
100+
per-chunk/per-event work, tight loops, or helpers already covered by the same operation's span.
101+
Explain the reason beside the function or a group of related functions. A loop is not by itself
102+
an exemption: its outer operation can still have a useful span without tracing each iteration.
103+
Preserve existing span names and options instead of adding a second span for the same operation.
104+
105+
Pass effect combinators after the generator body. A transform that needs the function's input
106+
receives it after the effect. Use `Effect.fn.Return<A, E, R>` when the generator needs an explicit
107+
return type, and preserve generic parameters, laziness, scope, and interruption behavior.
108+
93109
## Runtime boundaries
94110

95111
`ManagedRuntime.make`, `runPromise`, and `runPromiseExit` belong at application and framework

0 commit comments

Comments
 (0)