Move service state into InstanceState, flatten service facades (#18483)

packages/opencode/specs/effect-migration.md

@@ -4,18 +4,18 @@ Practical reference for new and migrated Effect code in `packages/opencode`.
 
 ## Choose scope
 
-Use the shared runtime for process-wide services with one lifecycle for the whole app.
+Use `InstanceState` (from `src/effect/instance-state.ts`) for services that need per-directory state, per-instance cleanup, or project-bound background work. InstanceState uses a `ScopedCache` keyed by directory, so each open project gets its own copy of the state that is automatically cleaned up on disposal.
 
-Use `src/effect/instances.ts` for services that are created per directory or need `InstanceContext`, per-project state, or per-instance cleanup.
+Use `makeRunPromise` (from `src/effect/run-service.ts`) to create a per-service `ManagedRuntime` that lazily initializes and shares layers via a global `memoMap`.
 
-- Shared runtime: config readers, stateless helpers, global clients
-- Instance-scoped: watchers, per-project caches, session state, project-bound background work
+- Global services (no per-directory state): Account, Auth, Installation, Truncate
+- Instance-scoped (per-directory state via InstanceState): File, FileTime, FileWatcher, Format, Permission, Question, Skill, Snapshot, Vcs, ProviderAuth
 
-Rule of thumb: if two open directories should not share one copy of the service, it belongs in `Instances`.
+Rule of thumb: if two open directories should not share one copy of the service, it needs `InstanceState`.
 
 ## Service shape
 
-For a fully migrated module, use the public namespace directly:
+Every service follows the same pattern — a single namespace with the service definition, layer, `runPromise`, and async facade functions:
 
 ```ts
 export namespace Foo {
@@ -28,53 +28,52 @@ export namespace Foo {
   export const layer = Layer.effect(
     Service,
     Effect.gen(function* () {
-      return Service.of({
-        get: Effect.fn("Foo.get")(function* (id) {
-          return yield* ...
-        }),
+      // For instance-scoped services:
+      const state = yield* InstanceState.make<State>(
+        Effect.fn("Foo.state")(() => Effect.succeed({ ... })),
+      )
+
+      const get = Effect.fn("Foo.get")(function* (id: FooID) {
+        const s = yield* InstanceState.get(state)
+        // ...
       })
+
+      return Service.of({ get })
     }),
   )
 
-  export const defaultLayer = layer.pipe(Layer.provide(FooRepo.defaultLayer))
+  // Optional: wire dependencies
+  export const defaultLayer = layer.pipe(Layer.provide(FooDep.layer))
+
+  // Per-service runtime (inside the namespace)
+  const runPromise = makeRunPromise(Service, defaultLayer)
+
+  // Async facade functions
+  export async function get(id: FooID) {
+    return runPromise((svc) => svc.get(id))
+  }
 }
 ```
 
 Rules:
 
-- Keep `Interface`, `Service`, `layer`, and `defaultLayer` on the owning namespace
-- Export `defaultLayer` only when wiring dependencies is useful
-- Use the direct namespace form once the module is fully migrated
+- Keep everything in one namespace, one file — no separate `service.ts` / `index.ts` split
+- `runPromise` goes inside the namespace (not exported unless tests need it)
+- Facade functions are plain `async function` — no `fn()` wrappers
+- Use `Effect.fn("Namespace.method")` for all Effect functions (for tracing)
+- No `Layer.fresh` — InstanceState handles per-directory isolation
 
-## Temporary mixed-mode pattern
+## Schema → Zod interop
 
-Prefer a single namespace whenever possible.
-
-Use a `*Effect` namespace only when there is a real mixed-mode split, usually because a legacy boundary facade still exists or because merging everything immediately would create awkward cycles.
+When a service uses Effect Schema internally but needs Zod schemas for the HTTP layer, derive Zod from Schema using the `zod()` helper from `@/util/effect-zod`:
 
 ```ts
-export namespace FooEffect {
-  export interface Interface {
-    readonly get: (id: FooID) => Effect.Effect<Foo, FooError>
-  }
+import { zod } from "@/util/effect-zod"
 
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/Foo") {}
-
-  export const layer = Layer.effect(...)
-}
+export const ZodInfo = zod(Info) // derives z.ZodType from Schema.Union
 ```
 
-Then keep the old boundary thin:
-
-```ts
-export namespace Foo {
-  export function get(id: FooID) {
-    return runtime.runPromise(FooEffect.Service.use((svc) => svc.get(id)))
-  }
-}
-```
-
-Remove the `Effect` suffix when the boundary split is gone.
+See `Auth.ZodInfo` for the canonical example.
 
 ## Scheduled Tasks
 
@@ -107,22 +106,23 @@ That is fine for leaf files like `schema.ts`. Keep the service surface in the ow
 
 ## Migration checklist
 
-Done now:
+Fully migrated (single namespace, InstanceState where needed, flattened facade):
 
-- [x] `AccountEffect` (mixed-mode)
-- [x] `AuthEffect` (mixed-mode)
-- [x] `TruncateEffect` (mixed-mode)
-- [x] `Question`
-- [x] `PermissionNext`
-- [x] `ProviderAuth`
-- [x] `FileWatcher`
-- [x] `FileTime`
-- [x] `Format`
-- [x] `Vcs`
-- [x] `Skill`
-- [x] `Discovery`
-- [x] `File`
-- [x] `Snapshot`
+- [x] `Account` — `account/index.ts`
+- [x] `Auth` — `auth/index.ts` (uses `zod()` helper for Schema→Zod interop)
+- [x] `File` — `file/index.ts`
+- [x] `FileTime` — `file/time.ts`
+- [x] `FileWatcher` — `file/watcher.ts`
+- [x] `Format` — `format/index.ts`
+- [x] `Installation` — `installation/index.ts`
+- [x] `Permission` — `permission/index.ts`
+- [x] `ProviderAuth` — `provider/auth.ts`
+- [x] `Question` — `question/index.ts`
+- [x] `Skill` — `skill/index.ts`
+- [x] `Snapshot` — `snapshot/index.ts`
+- [x] `Truncate` — `tool/truncate.ts`
+- [x] `Vcs` — `project/vcs.ts`
+- [x] `Discovery` — `skill/discovery.ts`
 
 Still open and likely worth migrating:
 
@@ -130,7 +130,6 @@ Still open and likely worth migrating:
 - [ ] `ToolRegistry`
 - [ ] `Pty`
 - [ ] `Worktree`
-- [ ] `Installation`
 - [ ] `Bus`
 - [ ] `Command`
 - [ ] `Config`