Distillation

Date: Sep 17, 2026

• 🟡 (01:36) Patch inspection reported /tmp/opencode/session-recovery-final-v19.patch is 11,174 lines and contains exactly 34 diff --git sections.
• 🟡 (01:36) Patch numstat for the 34 changed paths was: packages/client/src/generated/types.ts +72/-0; packages/core/schema.json +567/-48; packages/core/src/database/migration.gen.ts +1/-0; packages/core/src/database/migration/20260914170650_session-recovery.ts +62/-0; packages/core/src/database/schema.gen.ts +52/-1; packages/core/src/session.ts +6/-4; packages/core/src/session/compaction.ts +31/-16; packages/core/src/session/context-epoch.ts +54/-34; packages/core/src/session/execution/local.ts +200/-19; packages/core/src/session/input.ts +391/-31; packages/core/src/session/message-updater.ts +69/-0; packages/core/src/session/projector.ts +88/-1; packages/core/src/session/recovery.ts +504/-0; packages/core/src/session/run-coordinator.ts +30/-5; packages/core/src/session/runner/index.ts +4/-0; packages/core/src/session/runner/llm.ts +358/-104; packages/core/src/session/runner/publish-llm-event.ts +111/-48; packages/core/src/session/sql.ts +88/-1; packages/core/test/database-migration.test.ts +66/-1; packages/core/test/session-execution-local.test.ts +352/-0; packages/core/test/session-projector.test.ts +2771/-3; packages/core/test/session-prompt.test.ts +247/-25; packages/core/test/session-run-coordinator.test.ts +45/-0; packages/core/test/session-runner-recorded.test.ts +5/-10; packages/core/test/session-runner-tool-events.test.ts +46/-7; packages/core/test/session-runner.test.ts +1184/-58; packages/opencode/src/server/routes/instance/httpapi/server.ts +2/-1; packages/schema/src/session-event.ts +43/-1; packages/schema/test/event-manifest.test.ts +8/-5; packages/sdk/js/src/v2/gen/types.gen.ts +190/-0; packages/sdk/openapi.json +657/-44; packages/server/src/routes.ts +2/-0; packages/core/src/session/execution/claim.ts +112/-0; packages/core/src/session/recovery-id.ts +6/-0.
• 🟡 (01:36) One patch applicability probe against the existing review-tree state reported failures in numerous already-present files, including packages/core/src/database/schema.gen.ts, packages/core/src/session.ts, packages/core/src/session/execution/local.ts, packages/core/src/session/input.ts, packages/core/src/session/run-coordinator.ts, runner files, tests, generated SDK files, and server routes; a separate complete probe printed checks for all 34 paths in forward and reverse order without an error in that output.
• 🔴 (01:36) User’s repository guidance requires generated artifacts to be regenerated rather than edited directly: run ./packages/sdk/js/script/build.ts for the legacy JavaScript SDK; after public Protocol or Server HttpApi changes, run bun run generate from packages/client; do not directly edit src/generated or src/generated-effect.
• 🔴 (01:36) User requires runtime dependencies to flow Schema → Core and Protocol, then Core and Protocol → Server. Client runtime code may depend on Schema and Protocol, but never Core or Server; sdk-next composes Client, Core, and Server.
• 🔴 (01:36) User stated the repository default branch is dev; local main may not exist, so diffs should use dev or origin/dev.
• 🔴 (01:36) User requires branch names of at most 3 hyphen-separated words, without slashes or prefixes such as feat/ or fix/; examples are session-recovery, fix-scroll-state, and regenerate-sdk.
• 🔴 (01:36) User requires conventional commit and PR titles in type(scope): summary form, with valid types feat, fix, docs, chore, refactor, and test; scopes are optional and may include core, opencode, tui, app, desktop, sdk, or plugin.
• 🔴 (01:36) User’s code-style guidance: keep code in one function unless composable/reusable; do not preemptively extract single-use helpers; avoid try/catch and any; prefer Bun APIs such as Bun.file(); rely on inference; prefer flatMap, filter, and map over loops; bind Effect services to named variables before method calls; inline one-use values; avoid unnecessary destructuring; prefer const, ternaries, and early returns over reassignment and else.
• 🔴 (01:36) User requires complex functions to expose the happy path and place genuinely meaningful supporting helpers below the main export; helpers should remain close to their caller, synchronous parsing/validation should not return Effect, untrusted JSON should use helpers such as Schema.UnknownFromJsonString and Schema.decodeUnknownOption, and comments should explain only non-obvious constraints or surprising behavior.
• 🔴 (01:36) User requires Drizzle fields to use snake_case directly so column names do not need explicit string remapping.
• 🔴 (01:36) User stated: never alias imports; do not use forms such as import { foo as bar } or resolve as pathResolve.
• 🔴 (01:36) User stated: never use star imports, including import * as Foo and import type * as Foo; import a module’s own exported namespace by name instead, such as import { Project } from "@opencode-ai/core/project", then use Project.ID.
• 🔴 (01:36) User prefers dynamic imports for heavy modules used only in selected paths, especially startup-sensitive entrypoints; destructure bindings near the top of the narrowest scope, keep branch-specific imports inside their branch, and avoid inline import chains such as await import("./module").then(...) or (await import("./module")).value().
• 🔴 (01:36) User requires tests to run from package directories rather than repository root because of the do-not-run-tests-from-root guard; tests should minimize mocks, avoid globalThis.* unless unavoidable, exercise actual implementations, and not duplicate implementation logic.
• 🔴 (01:36) User stated: always run bun typecheck from package directories such as packages/opencode; never run tsc directly.
• 🔴 (01:36) User’s V2 Session Core rules require SessionV2.prompt(...) to durably admit one session_input before advisory SessionExecution.wake(sessionID), except resume: false is admit-only; the serialized runner promotes admitted inputs at safe boundaries.
• 🔴 (01:36) User’s V2 Session Core identity/retry rules: reused Session IDs adopt the existing Session; reused prompt message IDs reconcile only exact retries matching Session, prompt, and delivery mode; conflicts fail; historical projected prompts lazily synthesize promoted inbox records for exact retry.
• 🔴 (01:36) User requires SessionExecution to remain process-global and Session-ID based; its local implementation owns the process-local coordinator and discovers placement via SessionStore plus LocationServiceMap.get(session.location) only when draining; no layer takes a Session ID; V2 interruption targets the active process-local ownership chain, while idle or missing interruption is a no-op.
• 🔴 (01:36) User requires SessionRunner, model resolution, tool registry, permissions, and filesystem to remain Location-scoped; omitted Location.workspaceID means implicit-local placement, while explicit workspace identity is reserved for future semantics.
• 🔴 (01:36) User requires exactly one explicit llm.stream(request) per provider turn and projected-history reload before durable continuation; orchestration must not bridge through legacy SessionPrompt.loop(...) or an in-memory tool loop.
• 🔴 (01:36) User’s drain semantics: keep local drains process-local until clustering exists; SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakes, and permits different Sessions concurrently; advisory wakes drain only eligible durable inbox rows; post-crash provider retry requires a separate explicit design; a drain has no durable identity or transcript boundary.
• 🔴 (01:36) User’s delivery semantics: steer is default and promotes at the next safe provider-turn boundary while continuation is needed; queue remains pending until the Session would otherwise idle, then exactly one queued input is promoted before continuation is reevaluated; any new user input resets the selected agent’s provider-turn allowance, with a steer batch resetting it once.
• 🔴 (01:36) User requires EventV2 replay-owner claims to remain separate from clustered Session execution ownership.
• 🔴 (01:36) User requires the System Context algebra, registry, and built-ins to remain in src/system-context; Context Source producers stay with their observed domains; Session History selection and Context Epoch persistence remain Session-owned.
• 🔴 (01:37) User’s Schema package boundary requires @opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server; Schema contains serializable contracts, not services, runtime registries, side effects, or host-local implementations.
• 🔴 (01:37) User requires current contracts to be unversioned and legacy contracts explicitly named V1; permanent replacement architecture must not retain V2 names. New/current code must not depend on the eventual src/v1/ subtree, and @opencode-ai/protocol plus @opencode-ai/sdk-next are the current /api/... surfaces.
• 🔴 (01:37) User requires public events to be classified as current, shared transitional, or V1-only; V1 emission alone does not justify Protocol/SDK Next exposure. Events such as message.updated and message.part.* must stay out of the current surface absent a documented current-client need, and each event must have one canonical definition.
• 🔴 (01:37) User’s Schema module rules: one canonical exported value per contract; avoid bridge aliases such as PluginID, PluginEvent, PtyInfo, PtyEvent, and SessionTodoInfo; use canonical members such as Plugin.ID; Core facades must re-export the exact Schema value; use flat exports plus namespace projections such as export * as SessionMessage from "./session-message".
• 🔴 (01:37) User’s Schema contract rules: exported values/namespaces use PascalCase, builders/combinators use camelCase, the static combinator is statics(...); optional object properties use the package optional(...) helper; decode-only convenience defaults use Schema.withDecodingDefault(...); public Schema.Struct records use same-name interfaces; public contracts are readonly and must not use Schema.mutable(...).
• 🔴 (01:37) User requires current public contracts to avoid Schema.Any; use Schema.Json for JSON-serializable values and Schema.Unknown for opaque values requiring narrowing; Schema.Any is allowed only at an explicitly unsafe, documented compatibility boundary.
• 🔴 (01:37) User’s ID rules: current constructors expose create(); directional constructors remain only for public ordering semantics or compatibility; generated ID schemas must validate the exact emitted prefix including _; legacy loose validators must not be tightened without explicit compatibility and migration decisions; public identifiers and brands must be stable and unique.
• 🔴 [requested-tests] (01:37) User requires focused tests for contract/generated-surface changes, covering omission of optional undefined properties, absence of accidental current-contract Schema.Any, stable unique public identifiers, exact facade/Schema identity, and exclusion of V1-only events from current Protocol manifests.
• 🔴 (01:37) User’s opencode module-shape rule prohibits export namespace Foo; modules use flat top-level exports plus a self-reexport such as export * as Foo from "./foo", or export * as Foo from "." in a single-namespace index.ts. Multi-sibling directories such as src/session/ and src/config/ must not add barrel index.ts files.
• 🔴 (01:37) User’s Effect rules: compose with Effect.gen(function* () { ... }); use Effect.fn("Domain.method") for traced effects and Effect.fnUntraced for internal helpers; use Effect.callback for callback APIs; use Effect.void; prefer DateTime.nowAsDate; use Schema.Class, Schema.brand, Schema.TaggedErrorClass, and Schema.Defect; directly yield* new MyError(...) for early typed failure branches.
• 🔴 (01:37) User requires makeRuntime from src/effect/run-service.ts for services and InstanceState from src/effect/instance-state.ts for per-directory/project state. Work belongs directly in InstanceState.make; cleanup uses Effect.addFinalizer or Effect.acquireRelease; background consumers use Effect.forkScoped; non-blocking initialization forks InstanceState.get(state) at the call site rather than inside the closure.
• 🔴 (01:37) User stated Effect v4 beta has no Effect.fork or Effect.forkDaemon; use Effect.forkIn(scope).
• 🔴 (01:37) User prefers Effect services over ad hoc platform APIs: FileSystem.FileSystem over raw fs/promises, ChildProcessSpawner.ChildProcessSpawner with ChildProcess.make(...), HttpClient.HttpClient over raw fetch, and Path.Path, Config, Clock, and DateTime within Effect code; scheduled/background work should use Effect.repeat or Effect.schedule with Effect.forkScoped.
• 🔴 (01:37) User requires Effect.cached for sharing in-flight computations instead of manually storing Fiber | undefined or Promise | undefined, and EffectBridge for native/external callbacks that must re-enter Effect services with instance/workspace context.
• 🔴 (01:37) User’s HTTP route rules: normal and SSE endpoints use HttpApiBuilder.group(...); SSE returns HttpServerResponse.stream(...) and declares HttpApiSchema.asText({ contentType: "text/event-stream" }); declared raw/WebSocket endpoints use handleRaw(...); raw HttpRouter.use(...) is reserved for routes outside the declared API such as UI fallback.
• 🔴 (01:37) User prohibits providing stable layers inside request handlers. Effect.provideService(...) middleware is only for request-derived context such as WorkspaceRouteContext, InstanceRef, or WorkspaceRef; stable services should be yielded once while constructing the handler layer.
• 🔴 (01:37) User requires explicit Schema.ErrorClass contracts for public JSON errors; built-in HttpApiError.* is allowed only when its empty/tagged body is intended. SDK-visible message-bearing errors need exact declared API schemas, domain/storage layers must remain free of HttpApi types, and expected domain errors are translated at the handler boundary.