refactor(effect): unify service namespaces and align naming (#18093)

packages/opencode/AGENTS.md

@@ -9,71 +9,55 @@
 - **Output**: creates `migration/<timestamp>_<slug>/migration.sql` and `snapshot.json`.
 - **Tests**: migration tests should read the per-folder layout (no `_journal.json`).
 
-# opencode Effect guide
+# opencode Effect rules
 
-Instructions to follow when writing Effect.
+Use these rules when writing or migrating Effect code.
 
-## Schemas
+See `specs/effect-migration.md` for the compact pattern reference and examples.
 
-- Use `Schema.Class` for data types with multiple fields.
-- Use branded schemas (`Schema.brand`) for single-value types.
-
-## Services
-
-- Services use `ServiceMap.Service<ServiceName, ServiceName.Service>()("@console/<Name>")`.
-- In `Layer.effect`, always return service implementations with `ServiceName.of({ ... })`, never a plain object.
-
-## Errors
-
-- Use `Schema.TaggedErrorClass` for typed errors.
-- For defect-like causes, use `Schema.Defect` instead of `unknown`.
-- In `Effect.gen`, prefer `yield* new MyError(...)` over `yield* Effect.fail(new MyError(...))` for direct early-failure branches.
-
-## Effects
+## Core
 
 - Use `Effect.gen(function* () { ... })` for composition.
-- Use `Effect.fn("ServiceName.method")` for named/traced effects and `Effect.fnUntraced` for internal helpers.
-- `Effect.fn` / `Effect.fnUntraced` accept pipeable operators as extra arguments, so avoid unnecessary `flow` or outer `.pipe()` wrappers.
-- **`Effect.callback`** (not `Effect.async`) for callback-based APIs. The classic `Effect.async` was renamed to `Effect.callback` in effect-smol/v4.
-
-## Time
-
+- Use `Effect.fn("Domain.method")` for named/traced effects and `Effect.fnUntraced` for internal helpers.
+- `Effect.fn` / `Effect.fnUntraced` accept pipeable operators as extra arguments, so avoid unnecessary outer `.pipe()` wrappers.
+- Use `Effect.callback` for callback-based APIs.
 - Prefer `DateTime.nowAsDate` over `new Date(yield* Clock.currentTimeMillis)` when you need a `Date`.
 
-## Errors
+## Schemas and errors
 
-- In `Effect.gen/fn`, prefer `yield* new MyError(...)` over `yield* Effect.fail(new MyError(...))` for direct early-failure branches.
+- Use `Schema.Class` for multi-field data.
+- Use branded schemas (`Schema.brand`) for single-value types.
+- Use `Schema.TaggedErrorClass` for typed errors.
+- Use `Schema.Defect` instead of `unknown` for defect-like causes.
+- In `Effect.gen` / `Effect.fn`, prefer `yield* new MyError(...)` over `yield* Effect.fail(new MyError(...))` for direct early-failure branches.
 
-## Instance-scoped Effect services
+## Runtime vs Instances
 
-Services that need per-directory lifecycle (created/destroyed per instance) go through the `Instances` LayerMap:
+- Use the shared runtime for process-wide services with one lifecycle for the whole app.
+- Use `src/effect/instances.ts` for per-directory or per-project services that need `InstanceContext`, per-instance state, or per-instance cleanup.
+- If two open directories should not share one copy of the service, it belongs in `Instances`.
+- Instance-scoped services should read context from `InstanceContext`, not `Instance.*` globals.
 
-1. Define a `ServiceMap.Service` with a `static readonly layer` (see `FileWatcherService`, `QuestionService`, `PermissionService`, `ProviderAuthService`).
-2. Add it to `InstanceServices` union and `Layer.mergeAll(...)` in `src/effect/instances.ts`.
-3. Use `InstanceContext` inside the layer to read `directory` and `project` instead of `Instance.*` globals.
-4. Call from legacy code via `runPromiseInstance(MyService.use((s) => s.method()))`.
+## Preferred Effect services
 
-### Instance.bind — ALS context for native callbacks
+- In effectified services, prefer yielding existing Effect services over dropping down to ad hoc platform APIs.
+- Prefer `FileSystem.FileSystem` instead of raw `fs/promises` for effectful file I/O.
+- Prefer `ChildProcessSpawner.ChildProcessSpawner` with `ChildProcess.make(...)` instead of custom process wrappers.
+- Prefer `HttpClient.HttpClient` instead of raw `fetch`.
+- Prefer `Path.Path`, `Config`, `Clock`, and `DateTime` when those concerns are already inside Effect code.
+- For background loops or scheduled tasks, use `Effect.repeat` or `Effect.schedule` with `Effect.forkScoped` in the layer definition.
 
-`Instance.bind(fn)` captures the current Instance AsyncLocalStorage context and returns a wrapper that restores it synchronously when called.
+## Instance.bind — ALS for native callbacks
 
-**Use it** when passing callbacks to native C/C++ addons (`@parcel/watcher`, `node-pty`, native `fs.watch`, etc.) that need to call `Bus.publish`, `Instance.state()`, or anything that reads `Instance.directory`.
+`Instance.bind(fn)` captures the current Instance AsyncLocalStorage context and restores it synchronously when called.
 
-**Don't need it** for `setTimeout`, `Promise.then`, `EventEmitter.on`, or Effect fibers — Node.js ALS propagates through those automatically.
+Use it for native addon callbacks (`@parcel/watcher`, `node-pty`, native `fs.watch`, etc.) that need to call `Bus.publish`, `Instance.state()`, or anything that reads `Instance.directory`.
+
+You do not need it for `setTimeout`, `Promise.then`, `EventEmitter.on`, or Effect fibers.
 
 ```typescript
-// Native addon callback — needs Instance.bind
 const cb = Instance.bind((err, evts) => {
   Bus.publish(MyEvent, { ... })
 })
 nativeAddon.subscribe(dir, cb)
 ```
-
-## Flag → Effect.Config migration
-
-Flags in `src/flag/flag.ts` are being migrated from static `truthy(...)` reads to `Config.boolean(...).pipe(Config.withDefault(false))` as their consumers get effectified.
-
-- Effectful flags return `Config<boolean>` and are read with `yield*` inside `Effect.gen`.
-- The default `ConfigProvider` reads from `process.env`, so env vars keep working.
-- Tests can override via `ConfigProvider.layer(ConfigProvider.fromUnknown({ ... }))`.
-- Keep all flags in `flag.ts` as the single registry — just change the implementation from `truthy()` to `Config.boolean()` when the consumer moves to Effect.