openAgent

1# Effect Migration Patterns
2 
3This is the compact reference for moving code toward the current Effect
4shape. The high-level roadmap is [`todo.md`](./todo.md); examples and
5rules are in [`guide.md`](./guide.md).
6 
7## Default Shape
8 
9- Service methods return `Effect`.
10- Service methods are named with `Effect.fn("Domain.method")`.
11- Expected failures are typed errors on the error channel.
12- Dependencies are yielded once at layer construction and closed over by
13  methods.
14- `defaultLayer` wires production dependencies; tests can use open layers
15  when replacing dependencies.
16 
17## Instance State
18 
19Use `InstanceState` for per-directory state, subscriptions, scoped
20background work, and per-instance cleanup.
21 
22Do not add ad hoc `started` flags on top of `InstanceState`; the scoped
23cache handles run-once and concurrent deduplication.
24 
25## Runtime Boundaries
26 
27Prefer `AppRuntime` for crossing from non-Effect code into the shared app
28layer.
29 
30`makeRuntime(...)` exists for intentional service-local boundaries and
31legacy facades. Do not add new service-local runtimes unless the service is
32genuinely outside `AppLayer`.
33 
34## Platform Edges
35 
36- Use `FSUtil.Service` instead of raw filesystem APIs in
37  effectified services.
38- Use `AppProcess.Service` instead of raw process wrappers.
39- Use `HttpClient.HttpClient` instead of raw `fetch` in Effect code.
40- Use `Effect.cached` for shared in-flight work.
41- Use `Effect.callback` for callback APIs.
42 
43## Tests During Migration
44 
45When migrating code, migrate touched tests toward
46[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md):
47 
48- `testEffect(...)`
49- `it.effect`, `it.live`, or `it.instance`
50- explicit layers for behavior changes
51- deterministic waits instead of sleeps
52- no mutable env/global flags after layers are built
53 
54## Migration Checklist
55 
56- [ ] The code has a single Effect body instead of Promise wrappers around
57      service calls.
58- [ ] Expected failures are typed errors, not thrown exceptions or defects.
59- [ ] Layer requirements are explicit.
60- [ ] Tests use Effect-aware fixtures and focused layers.
61- [ ] Public behavior and wire shapes are preserved unless intentionally
62      changed.
63