orynacode-ai 1.16.2

package/specs/effect/todo.md

@@ -0,0 +1,241 @@
+# Effect TODO
+
+Short roadmap for Effect cleanup in `packages/opencode`.
+
+Current patterns and examples live in [`guide.md`](./guide.md). Error
+boundary migration details live in
+[`error-boundaries-plan.md`](./error-boundaries-plan.md). Test migration rules live in
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md).
+Older deep-dive notes in this directory may still be useful, but treat
+this roadmap and the guide as the current entry points.
+
+This is a planning map, not a verified inventory. Before starting a task,
+re-run a targeted `git grep` from current `dev` and update this file if
+the inventory changed.
+
+## Priorities
+
+```text
+P0  ERR + RENDER + HTTP
+    Make expected failures typed, render them well, and stop relying on
+    generic HTTP error guesswork.
+
+P1  TEST
+    Convert touched tests to the ideal Effect test patterns from the guide.
+
+P2  RF
+    Move mutable runtime flags into typed runtime/config services.
+
+P3  GLOBAL
+    Make global paths explicit and remove import-time side effects.
+
+P4  INST + BRIDGE
+    Remove ambient Instance coupling while keeping Promise/callback interop.
+
+P5  PROC + FS
+    Replace raw process/filesystem edges with typed Effect services.
+
+P6  OA
+    Shrink OpenAPI compatibility shims as source schemas improve.
+```
+
+## Work Paths
+
+- `ERR` Typed errors — replace legacy `NamedError.create(...)` and
+  `Effect.die(...)` for expected service failures with
+  `Schema.TaggedErrorClass` errors on the Effect error channel.
+  Shrinks: [`NamedError`](../../../core/src/util/error.ts) usage.
+- `RENDER` User-visible error rendering — preserve structured typed-error
+  details at CLI, HTTP, and tool boundaries.
+  Shrinks: opaque `Error: Name` rendering.
+- `HTTP` HTTP route cleanup — make route errors explicit instead of
+  relying on generic middleware to guess status/body from error names.
+  Shrinks: [`middleware/error.ts`](../../src/server/routes/instance/httpapi/middleware/error.ts)
+  and route-level compatibility shims.
+- `TEST` Effect test migration — use `testEffect`, `it.live`, and
+  `it.instance` with explicit layers.
+  Shrinks: Promise-style tests, sleeps, mutable global test flags.
+- `RF` RuntimeFlags / Flag deletion — move mutable
+  [`Flag`](../../../core/src/flag/flag.ts) reads into typed runtime/config
+  services.
+  Shrinks: [`flag.ts`](../../../core/src/flag/flag.ts),
+  [`test/fixture/flag.ts`](../../test/fixture/flag.ts).
+- `GLOBAL` Global paths / import side effects — make global path state
+  explicit and testable instead of mutable module state.
+  Shrinks: [`global.ts`](../../../core/src/global.ts) import-time side
+  effects, mutable `Global.Path` overrides, and its `Flag` dependency.
+- `INST` Instance context — keep project context explicit through Effect refs
+  and bridge boundaries.
+- `BRIDGE` Promise/callback interop — keep bridge helpers, but reduce
+  legacy ALS coupling.
+  Shrinks: ad hoc Promise/callback re-entry code.
+- `PROC` AppProcess migration — prefer `AppProcess.Service` over raw
+  process wrappers.
+  Shrinks: direct spawn callsites and legacy process helpers.
+- `FS` FSUtil migration — prefer `FSUtil.Service` over raw
+  filesystem APIs.
+  Shrinks: direct `fs` / `Bun.file` service callsites where inappropriate.
+- `RT` Runtime/facade cleanup — remove service-local `makeRuntime`
+  facades when not intentional.
+  Shrinks: async facade exports around services and
+  [`run-service.ts`](../../src/effect/run-service.ts) usage.
+- `OA` OpenAPI compatibility — tighten source schemas instead of
+  post-processing generated OpenAPI.
+  Shrinks: schema workaround blocks in
+  [`public.ts`](../../src/server/routes/instance/httpapi/public.ts).
+
+## P0: Errors, Rendering, And HTTP
+
+This should be the next big cleanup theme. The codebase is moving toward
+typed Effect failures, but the user-facing boundaries still leak old
+shapes and sometimes collapse rich errors into opaque strings.
+
+### Problems
+
+- Some expected service failures still use `NamedError.create(...)` or
+  collapse to `Effect.die(...)`. The storage/worktree/provider-auth
+  conversions are done; an inventory sweep is needed for the rest.
+- HTTP error middleware still guesses status codes from error names —
+  some entries (e.g. storage `NotFound`, provider auth) can now be
+  removed, but the middleware overall has not shrunk.
+- Route handlers and route groups do not consistently declare the public
+  error body they intend to expose.
+- Repeated route error translations do not yet have a clear home: some
+  should stay inline, some deserve tiny shared mapper helpers.
+
+### Target Shape
+
+- Services define expected failures with `Schema.TaggedErrorClass`.
+- Services export an `Error` union and include it in method return types.
+- Expected failures stay on the Effect error channel.
+- `Effect.die(...)` is reserved for defects: bugs, impossible states,
+  violated invariants, or final unknown-boundary fallbacks.
+- Inside `Effect.gen` / `Effect.fn`, use `yield* new MyError(...)` for
+  direct expected failures.
+- Domain services do not import HTTP status codes, `HttpApiError`, or
+  route-specific error schemas.
+- HTTP route groups make their public error contracts obvious.
+- Handlers map service errors to declared HTTP errors at the boundary.
+- Shared mapper helpers are only for repeated translations, not a giant
+  central registry of every domain error.
+- Generic HTTP middleware should shrink; it should not accumulate more
+  name-based domain knowledge.
+
+### Recently completed
+
+- [x] `RENDER-1` CLI tagged config error rendering (#27256, tests #27257).
+- [x] `ERR-1` [`storage/storage.ts`](../../src/storage/storage.ts) typed
+      `NotFoundError` (#27265) and removal of the server defect fallback
+      (#27287).
+- [x] `ERR-2` [`worktree/index.ts`](../../src/worktree/index.ts) typed
+      errors (#27296).
+- [x] `ERR-3` [`provider/auth.ts`](../../src/provider/auth.ts) typed
+      validation/oauth errors (#27301).
+- [x] `HTTP-1` Unknown-500 details no longer leaked (#27251); follow-up
+      to stop exposing named defects (#27471).
+- [x] Session message reads typed and made effectful (#27269, #27275,
+      #27280, #27291).
+- [x] Session HTTP error contracts tightened (#27308); busy-session
+      mapping centralized (#27375, #27473).
+- [x] Provider init (#27484) and LSP init (#27494) errors typed.
+
+### First PR Candidates
+
+- [ ] `HTTP-2` Audit one route group for explicit error contracts and
+      decide which mappings stay inline vs. shared helper.
+- [ ] `ERR-4` Sweep remaining `NamedError.create(...)` and
+      `Effect.die(...)` callsites for expected failures — re-run `git
+grep` to build a current inventory.
+- [ ] `RENDER-2` Audit CLI and TUI surfaces for any remaining opaque
+      `Error: Name` rendering of typed errors.
+
+## P1: Tests
+
+When touching tests, migrate them toward the ideal patterns in
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md):
+
+- Use `testEffect(...)` with explicit layers.
+- Prefer `it.instance(...)` for service tests that need an instance.
+- Prefer `it.live(...)` for real timers, filesystem mtimes, child
+  processes, git, locks, or other live integration behavior.
+- Avoid sleeps; wait on real events or deterministic state transitions.
+- Do not mutate `process.env` or mutable globals after layers are built.
+- Use explicit layer variants, such as `RuntimeFlags.layer(...)`, for
+  behavior changes.
+
+## P2: RuntimeFlags / Flag Deletion
+
+Recently completed:
+
+- [x] Plugin/pure-mode flags moved to RuntimeFlags.
+- [x] Tool visibility flags moved to RuntimeFlags.
+- [x] Built-in websearch provider selection uses the same runtime flags as
+      tool visibility.
+- [x] Removed global default-plugin disabling from test preload.
+- [x] `RF-1` Reference reads routed through runtime flags (#27318).
+- [x] `RF-2` Plan-mode prompt read routed through runtime flags (#27320).
+- [x] `RF-3` Event-system reads routed through runtime flags (#27323).
+- [x] `RF-4` Workspaces reads routed through runtime flags for session
+      (#27335), sync (#27336), and control-plane (#27337).
+- [x] LLM client (#27368) and installation client (#27369) routed
+      through runtime flags.
+- [x] TUI plugin runtime flags simplified (#27506).
+- [x] Background-subagents flag moved to RuntimeFlags, then removed
+      (`refactor(task): use runtime flag for background subagents`,
+      `refactor(flags): remove background subagents flag`).
+
+Remaining cleanup:
+
+- [ ] Sweep lingering `Flag.*` reads — many CLI/TUI/config/observability
+      callsites still import [`flag.ts`](../../../core/src/flag/flag.ts).
+      Decide per-callsite whether to route through RuntimeFlags, accept
+      as legitimate env/config boundary, or migrate to typed `Config`.
+- [ ] Delete [`test/fixture/flag.ts`](../../test/fixture/flag.ts) once
+      tests no longer mutate `Flag`.
+- [ ] Delete [`flag.ts`](../../../core/src/flag/flag.ts) once no packages
+      import it.
+
+## P3: Global Paths
+
+[`global.ts`](../../../core/src/global.ts) is real connective tissue, not
+just cosmetic ugliness. It currently mixes path calculation, import-time
+directory creation, `Flock` setup, mutable exported `Path` state, and a
+`Flag` dependency.
+
+Problems to reduce:
+
+- Importing the module creates directories.
+- Tests override `Global.Path` by mutating exported module state.
+- Most callers use `Global.Path` directly instead of the Effect service.
+- `Global.make()` still reads mutable `Flag.OPENCODE_CONFIG_DIR`.
+
+Next PR candidates:
+
+- [ ] Replace mutable `Global.Path` test overrides with explicit test
+      layers or scoped helpers.
+- [ ] Move directory creation and `Flock` setup behind an explicit init
+      boundary where possible.
+- [ ] Remove the `Flag` dependency from global path resolution.
+
+## P4: Instance And Bridge
+
+Instance context migration is complete for the legacy sync shim. Promise and callback interop continues through [`effect/bridge.ts`](../../src/effect/bridge.ts).
+
+Current rules:
+
+- Effect services read instance data from `InstanceRef`, `WorkspaceRef`, `InstanceState`, or explicit arguments.
+- Plain JavaScript callback boundaries use `EffectBridge` or explicit context arguments.
+- Runtime entrypoints must provide refs explicitly when they are instance-scoped.
+
+## Lower Priority Tracks
+
+- `PROC` / `FS` — continue AppProcess and FSUtil migrations as
+  focused PRs when touching relevant files.
+- `RT` — remove service-local runtime facades only when they are not an
+  intentional boundary.
+- `OA` — shrink [`public.ts`](../../src/server/routes/instance/httpapi/public.ts)
+  by tightening source schemas one workaround at a time.
+- `fetch` → `HttpClient` — migrate raw fetch callsites when the caller is
+  already effectful or being effectified.
+- `Tools` — remaining tool cleanup is narrow: `webfetch` HTML extraction
+  and `shell` raw stream/promise edges.

package/specs/effect/tools.md

@@ -0,0 +1,88 @@
+# Tool migration
+
+Practical reference for the current tool-migration state in `packages/opencode`.
+
+## Status
+
+`Tool.Def.execute` and `Tool.Info.init` already return `Effect` on this branch, and the built-in tool surface is now largely on the target shape.
+
+The current exported tools in `src/tool` all use `Tool.define(...)` with Effect-based initialization, and nearly all of them already build their tool body with `Effect.gen(...)` and `Effect.fn(...)`.
+
+So the remaining work is no longer "convert tools to Effect at all". The remaining work is mostly:
+
+1. remove Promise and raw platform bridges inside individual tool bodies
+2. swap tool internals to Effect-native services like `FSUtil`, `HttpClient`, and `ChildProcessSpawner`
+3. keep tests and callers aligned with `yield* info.init()` and real service graphs
+
+## Current shape
+
+`Tool.define(...)` is already the Effect-native helper here.
+
+- `init` is an `Effect`
+- `info.init()` returns an `Effect`
+- `execute(...)` returns an `Effect`
+
+That means a tool does not need a separate `Tool.defineEffect(...)` helper to count as migrated. A tool is effectively migrated when its init and execute path stay Effect-native, even if some internals still bridge to Promise-based or raw APIs.
+
+## Tests
+
+Tool tests should use the existing Effect helpers in `packages/opencode/test/lib/effect.ts`:
+
+- Use `testEffect(...)` / `it.live(...)` instead of creating fake local wrappers around effectful tools.
+- Yield the real tool export, then initialize it: `const info = yield* ReadTool`, `const tool = yield* info.init()`.
+- Run tests inside a real instance with `provideTmpdirInstance(...)` or `provideInstance(tmpdirScoped(...))` so instance-scoped services resolve exactly as they do in production.
+
+This keeps tool tests aligned with the production service graph and makes follow-up cleanup mostly mechanical.
+
+## Exported tools
+
+These exported tool definitions currently use `Tool.define(...)` in `src/tool`:
+
+- [x] `apply_patch.ts`
+- [x] `bash.ts`
+- [x] `edit.ts`
+- [x] `glob.ts`
+- [x] `grep.ts`
+- [x] `invalid.ts`
+- [x] `lsp.ts`
+- [x] `plan.ts`
+- [x] `question.ts`
+- [x] `read.ts`
+- [x] `skill.ts`
+- [x] `task.ts`
+- [x] `todo.ts`
+- [x] `webfetch.ts`
+- [x] `websearch.ts`
+- [x] `write.ts`
+
+Notes:
+
+- There is no current `ls.ts` tool file on this branch.
+- `truncate.ts` is an Effect service used by tools, not a tool definition itself.
+- `mcp-exa.ts`, `external-directory.ts`, and `schema.ts` are support modules, not standalone tool definitions.
+
+## Follow-up cleanup
+
+Most exported tools are already on the intended Effect-native shape. The remaining cleanup is narrower than the old checklist implied.
+
+Current spot cleanups worth tracking:
+
+- [x] `read.ts` — streams through `FSUtil.Service.stream` with `Stream.splitLines`; the legacy Node stream / `readline` helper is gone
+- [ ] `bash.ts` — already uses Effect child-process primitives; only keep tracking shell-specific platform bridges and parser/loading details as they come up
+- [ ] `webfetch.ts` — already uses `HttpClient`; remaining work is limited to smaller boundary helpers like HTML text extraction
+- [ ] `file/ripgrep.ts` — adjacent to tool migration; still has raw fs/process usage that affects `grep.ts` and file-search routes
+- [x] `patch/index.ts` — apply path now returns `Effect` over `FSUtil.Service`; the parser and chunk replacer stay pure
+
+Notable items that are already effectively on the target path and do not need separate migration bullets right now:
+
+- `apply_patch.ts`
+- `grep.ts`
+- `write.ts`
+- `websearch.ts`
+- `edit.ts`
+
+## Filesystem notes
+
+Current raw fs users that still appear relevant here:
+
+- `file/ripgrep.ts` — `fs/promises`

package/specs/openapi-translation-cleanup.md

@@ -0,0 +1,204 @@
+# OpenAPI Translation Cleanup Plan
+
+## Goal
+
+Trim `packages/opencode/src/server/routes/instance/httpapi/public.ts` until OpenAPI generation is mostly a direct projection of the `HttpApi` route declarations, without breaking the generated SDK surface.
+
+The main failure mode to eliminate is spec-only behavior: anything that appears in `/doc` or the SDK but is not accepted by runtime `HttpApi` validation.
+
+## Current Culprit
+
+`public.ts` exports `PublicApi` with a large `OpenApi.annotations({ transform })` hook. That hook rewrites the generated spec for legacy SDK compatibility.
+
+The highest-risk rewrite is `InstanceQueryParameters`, which injected `directory` and `workspace` into every instance route in OpenAPI even when the runtime query schema did not accept them. This caused the SDK and `/doc` to advertise calls that could fail with `400` at runtime.
+
+## Non-Negotiables
+
+- Do not break the generated JavaScript SDK without an explicit versioned migration plan.
+- Runtime route schemas are the source of truth for accepted params, payloads, and responses.
+- `/doc`, generated SDK types, and runtime validation must agree for every endpoint.
+- Prefer endpoint or schema annotations over post-generation spec surgery.
+- Remove one category of rewrite at a time, with focused compatibility checks.
+
+## PR Checklist
+
+Status legend: `[x]` done locally, `[~]` in progress locally, `[ ]` not started.
+
+Current combined PR scope:
+
+- `[x]` PR 1 drift tests: added OpenAPI/runtime query assertions and a negative fixture in `test/server/httpapi-query-schema-drift.test.ts`.
+- `[x]` PR 2 injection removal: removed broad `directory` / `workspace` post-generation injection from `public.ts` and replaced it with explicit runtime query schemas on affected routes.
+- `[ ]` PR 3+ cleanup: leave query override, path pattern, error shape, auth, and component-shape rewrites for later PRs.
+
+### PR 1: Add OpenAPI/Runtime Query Drift Tests
+
+- `[x]` Add or extend `packages/opencode/test/server/httpapi-query-schema-drift.test.ts`.
+- `[x]` Import `OpenApi.fromApi` and `PublicApi`.
+- `[x]` Generate the public spec in-process with `OpenApi.fromApi(PublicApi)`.
+- `[x]` Add a route inventory for the existing runtime reproducers: `session`, `file`, `experimental`, and `instance` routes.
+- `[x]` For each inventory entry, assert every OpenAPI query parameter is declared by the runtime query schema.
+- `[x]` Add a negative regression fixture that fails on spec-only `directory` / `workspace` params.
+- `[x]` Keep this part test-only.
+
+Verification:
+
+- `[x]` `bun test --timeout 5000 test/server/httpapi-query-schema-drift.test.ts` from `packages/opencode`.
+- `[x]` `bun typecheck` from `packages/opencode`.
+
+### PR 2: Delete Spec-Only Workspace Query Injection
+
+- `[x]` Edit `packages/opencode/src/server/routes/instance/httpapi/public.ts`.
+- `[x]` Delete `InstanceQueryParameters`.
+- `[x]` Delete the `isInstanceRoute` constant.
+- `[x]` Delete the branch that prepends `directory` and `workspace` to every instance operation.
+- `[x]` Keep `normalizeParameter(param, route)` for parameters that are actually produced by `HttpApi`.
+- `[x]` Add `WorkspaceRoutingQuery` / `WorkspaceRoutingQueryFields` to runtime query schemas for affected routes.
+- `[x]` Regenerate SDK and inspect diff. Result: no `directory` / `workspace` request-param removals; generated SDK diff is declaration ordering only.
+
+Notes:
+
+- Added `WorkspaceRoutingQuery` in `middleware/workspace-routing.ts` as the canonical runtime schema for middleware-consumed query params.
+- Replaced v2 union-query schemas with plain struct query schemas so `OpenApi.fromApi` emits their query params directly. This intentionally exposes the beta `/api/session` pagination/filter params in the SDK; cursor mutual-exclusion rules now live in the handlers, while `directory` / `workspace` remain allowed with cursors for routing.
+
+Expected code shape:
+
+```ts
+for (const param of operation.parameters ?? []) normalizeParameter(param, `${method.toUpperCase()} ${path}`)
+```
+
+Verification:
+
+- `[x]` `bun test --timeout 5000 test/server/httpapi-query-schema-drift.test.ts` from `packages/opencode`.
+- `[x]` `bun dev generate > /tmp/opencode-openapi.json` from `packages/opencode`.
+- `[x]` `./packages/sdk/js/script/build.ts` from repo root.
+- `[x]` Inspect SDK diff for removed `directory` / `workspace` params. Result: none after explicit runtime schemas; v2 list/message now also expose their existing beta pagination/filter query params in the SDK.
+- `[x]` `bun typecheck` from `packages/opencode`.
+
+### PR 3: Replace Broad Query Type Override Sets With Route-Level Helpers
+
+- Edit `packages/opencode/src/server/routes/instance/httpapi/public.ts`.
+- Remove broad name-based assumptions from `QueryNumberParameters` and `QueryBooleanParameters` one field at a time.
+- Add shared query schema helpers near route group code if needed, for example in `groups/metadata.ts` or a new `groups/query.ts`.
+- Prefer route declarations like `Schema.NumberFromString.check(...)` and boolean string decoders like the existing `QueryBoolean` in `groups/session.ts`.
+- Keep only route-specific `QueryParameterSchemas` entries when SDK compatibility requires a public encoded type that Effect OpenAPI cannot emit yet.
+
+Concrete first targets:
+
+- `[x]` Consolidate `roots` / `archived` onto an explicit shared route schema helper. Keep `QueryBooleanParameters` until route-level schema metadata can preserve the SDK's `boolean | "true" | "false"` call shape without a global transform.
+- `[x]` Replace broad `QueryNumberParameters` reliance for `start` / `cursor` / `limit` with route-specific SDK compatibility schemas. Keep improving route-level constraints where behavior is intentionally stricter.
+- Keep `GET /find/file limit`, `GET /session/{sessionID}/diff messageID`, and `GET /session/{sessionID}/message limit` overrides until their route schemas generate identical SDK types directly.
+
+Verification:
+
+- Focused HTTP tests for changed query fields.
+- `bun dev generate > /tmp/opencode-openapi.json` from `packages/opencode`.
+- `./packages/sdk/js/script/build.ts` from repo root.
+- Inspect generated SDK request param types before deleting each override.
+- `bun typecheck` from `packages/opencode`.
+
+### PR 4: Move Path Parameter Patterns Into ID Schemas
+
+- Audit `PathParameterSchemas` and `pathParameterSchema()` in `public.ts`.
+- Check source schemas in files like `packages/opencode/src/session/schema.ts`, `packages/opencode/src/permission/schema.ts`, and pty schema definitions.
+- Add or fix OpenAPI-compatible annotations on branded ID schemas so generated path params include the same patterns without `public.ts` overrides.
+- Delete one path override only after generated OpenAPI is unchanged for that param.
+
+Concrete first targets:
+
+- `[x]` `sessionID`
+- `[x]` `messageID`
+- `[x]` `partID`
+- `[x]` `permissionID`
+- `[x]` `ptyID`
+
+- `[x]` Remove ambiguous workspace `id` path overrides once the endpoint source schema emits the `wrk` pattern.
+
+Verification:
+
+- `bun dev generate > /tmp/opencode-openapi.json` from `packages/opencode`.
+- `./packages/sdk/js/script/build.ts` from repo root.
+- Inspect generated path param types and patterns.
+- `bun typecheck` from `packages/opencode`.
+
+### PR 5: Replace Built-In Error Rewrites With Declared API Errors
+
+- Edit route group files under `packages/opencode/src/server/routes/instance/httpapi/groups/`.
+- Replace SDK-visible `HttpApiError.BadRequest` / `HttpApiError.NotFound` with explicit error schemas from `packages/opencode/src/server/routes/instance/httpapi/errors.ts` or add new ones there.
+- Update handlers to fail with the declared API errors at the boundary.
+- Remove matching cases from `normalizeLegacyErrorResponses()` only after generated OpenAPI remains SDK-compatible.
+- Do this group by group, starting with one small route group.
+
+Concrete first targets:
+
+- `groups/config.ts` `PATCH /config` bad request.
+- `groups/session.ts` endpoints that already translate domain not-found errors.
+- `groups/file.ts` if any handler currently relies on built-in error shape.
+
+Verification:
+
+- Focused HTTP tests asserting response body shape for changed error paths.
+- `bun dev generate > /tmp/opencode-openapi.json` from `packages/opencode`.
+- `./packages/sdk/js/script/build.ts` from repo root.
+- Inspect SDK error union diff.
+- `bun typecheck` from `packages/opencode`.
+
+### PR 6: Remove Auth/Security Spec Rewrites If SDK Can Tolerate It
+
+- Audit `delete operation.security`, `delete operation.responses?.["401"]`, and `delete spec.components?.securitySchemes` in `public.ts`.
+- Decide whether SDK should expose auth in generated operation metadata.
+- If preserving no-auth SDK surface is required, leave this rewrite and document it as intentional compatibility code.
+- If removing it, update SDK generation expectations and docs in the same PR.
+
+Verification:
+
+- `./packages/sdk/js/script/build.ts` from repo root.
+- Inspect generated client call signatures and error unions.
+- Do not merge if auth churn changes normal SDK call ergonomics unintentionally.
+
+### PR 7: Tackle Component Shape Rewrites One At A Time
+
+- Audit these in `public.ts`: `normalizeComponentNames`, `collapseDuplicateComponents`, `applyLegacySchemaOverrides`, `normalizeComponentDescriptions`, `stripOptionalNull`, `fixSelfReferencingComponents`.
+- For each rewrite, make a tiny PR that removes or narrows only that rewrite.
+- If generated SDK type names churn broadly, stop and either keep the rewrite or fix `effect-smol` generation first.
+
+Concrete first targets:
+
+- Delete cosmetic `normalizeComponentDescriptions` if SDK output does not change materially.
+- Narrow `applyLegacySchemaOverrides` entries that correspond to schemas already fixed at the source.
+- Keep `stripOptionalNull` until there is an explicit SDK migration plan, because it likely affects many optional fields.
+
+Verification:
+
+- `bun dev generate > /tmp/opencode-openapi.json` from `packages/opencode`.
+- `./packages/sdk/js/script/build.ts` from repo root.
+- Inspect generated SDK type-name and optionality diffs.
+
+## Upstream Middleware Query Support
+
+Long-term, `WorkspaceRoutingMiddleware` should declare the query fields it reads once, and `HttpApi` should use that declaration for both runtime validation and OpenAPI generation.
+
+Target in `effect-smol`:
+
+- Extend `HttpApiMiddleware.Service` config with optional query schema support, or add a dedicated middleware query annotation.
+- Make runtime request decoding include middleware query schemas.
+- Make `OpenApi.fromApi` emit middleware query params for endpoints using that middleware.
+
+Once available, remove `WorkspaceRoutingQueryFields` spreads from route groups and declare `directory` / `workspace` only on `WorkspaceRoutingMiddleware`.
+
+## Suggested PR Order
+
+1. Add drift detection tests only.
+2. Remove `InstanceQueryParameters` spec injection; rely on `WorkspaceRoutingQueryFields` already present in runtime schemas.
+3. Convert query type overrides into route/schema-level helpers where possible.
+4. Convert path parameter overrides into schema annotations or upstream fixes.
+5. Replace built-in error response rewrites with explicit declared API errors by route group.
+6. Tackle component naming/nullability rewrites only after SDK compatibility snapshots are stable.
+
+## Verification Checklist Per PR
+
+- Focused HTTP tests for changed routes.
+- OpenAPI drift tests.
+- `bun dev generate > /tmp/opencode-openapi.json` from `packages/opencode`.
+- `./packages/sdk/js/script/build.ts` from repo root.
+- Inspect generated SDK diff for public API churn.
+- `bun typecheck` from `packages/opencode`.