Distillation

Date: Sep 15, 2026

• 🔴 (21:47) User directed that type checking must use bun typecheck from package directories such as packages/opencode, never tsc directly.
• 🔴 (21:47) User stated runtime dependencies must flow from Schema to Core and Protocol, then from Core and Protocol to Server; Client runtime code may depend on Schema and Protocol but never Core or Server; sdk-next composes Client, Core, and Server.
• 🔴 (21:47) User directed never to alias imports, including forms such as import { foo as bar } from "..." and resolve as pathResolve.
• 🔴 (21:47) User directed never to use star imports, including import * as Foo from "..." and import type * as Foo from "..."; namespace-style values should use a module’s named exported namespace, such as import { Project } from "@opencode-ai/core/project" and Project.ID.
• 🔴 (21:47) User stated tests cannot run from the repository root because of the do-not-run-tests-from-root guard; tests must run from package directories such as packages/opencode.
• 🔴 (21:47) User stated the repository default branch is dev; local main may not exist, so diffs should use dev or origin/dev.
• 🔴 (21:47) User stated branch names must contain at most three hyphen-separated words and must not use slashes or type prefixes such as feat/ or fix/.
• 🔴 (21:47) User stated commit messages and PR titles use type(scope): summary; valid types are feat, fix, docs, chore, refactor, and test, with optional scopes such as core, opencode, tui, app, desktop, sdk, or plugin.
• 🔴 (21:47) User stated legacy JavaScript SDK regeneration uses ./packages/sdk/js/script/build.ts; after public Protocol or Server HttpApi changes, generation uses bun run generate from packages/client, and src/generated plus src/generated-effect must not be edited directly.
• 🔴 (21:47) User stated V2 Session Core semantics: SessionV2.prompt(...) durably admits one session_input row before advisory SessionExecution.wake(sessionID), except resume: false requests admit-only behavior; the serialized runner promotes admitted inputs at safe boundaries.
• 🔴 (21:47) User stated exact retry semantics: reusing a Session ID adopts the existing Session; reusing a prompt message ID reconciles only when Session, prompt, and delivery mode match; conflicting reuse fails; historical projected prompts lazily synthesize promoted inbox records during exact retry.
• 🔴 (21:47) User stated SessionExecution must remain process-global and Session-ID based; its local implementation owns the process-local Session coordinator and discovers placement through SessionStore and LocationServiceMap.get(session.location) only when a drain starts; no layer should take a Session ID.
• 🔴 (21:47) User stated local Session drains remain process-local until clustering exists; SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakeups, and permits different Sessions to run concurrently; advisory wakes drain eligible durable inbox rows only, while post-crash provider-work recovery requires a separate explicit design.
• 🔴 (21:47) User stated EventV2 replay owner claims must remain separate from clustered Session execution ownership.
• 🔴 (21:47) User stated @opencode-ai/schema owns browser-safe wire and storage contracts; runtime behavior, service layers, side effects, and host-local implementation details belong in the owning domain package.
• 🔴 (21:47) User stated Schema optional object properties, including nested structs and event payloads, must use the package optional(...) helper so encoded objects omit undefined; raw Schema.optional(...) is reserved for intentionally and explicitly preserving an encoded undefined.
• 🔴 (21:47) User stated focused tests for contract/generated-surface changes must cover optional properties omitting undefined, absence of accidental current-contract Schema.Any, stable and unique public identifiers, exact facade/schema identity, and exclusion of V1-only events from current Protocol manifests.
• 🟡 (21:48) Inspection of /home/byk/Code/opencode/packages/schema/src/session-event.ts:38-43 found ordinary session durable events use aggregate sessionID and durable version 1; /home/byk/Code/opencode/packages/schema/src/session-event.ts:44-49 separately defines stepSettlementOptions with aggregate sessionID and durable version 2.
• 🟡 (21:48) Inspection confirmed /home/byk/Code/opencode/packages/schema/src/session-event.ts:94-112 defines PromptAdmitted as session.next.prompt.admitted with requestExecution: Schema.Boolean.pipe(optional), and PromptExecutionRequested as session.next.prompt.execution_requested carrying sessionID, messageID, and timestamp.
• 🟡 (21:48) Inspection confirmed both events are public in both inventories: PromptAdmitted and PromptExecutionRequested appear in DurableDefinitions at /home/byk/Code/opencode/packages/schema/src/session-event.ts:489-490 and in Definitions at lines 523-524; Durable is a one-of tagged union annotated SessionDurableEvent at lines 556-559, while All is the full tagged union at lines 561-562.
• 🟡 (21:48) In /home/byk/Code/opencode/packages/core/src/session/input.ts:54-59, exact retry first loads the existing row by message ID; non-equivalent input dies with SessionInput.LifecycleConflict, while equivalent input returns the existing admission and calls requestExecution(...) only when the retry has requestExecution: true.
• 🟡 (21:48) In /home/byk/Code/opencode/packages/core/src/session/input.ts:60-98, a new admission publishes SessionEvent.PromptAdmitted with the explicit boolean requestExecution; a missing durable aggregate sequence is fatal. On publication defect, it rereads storage: absent data rethrows the defect, conflicting data dies with SessionInput.LifecycleConflict, and an equivalent stored row is returned after requesting execution when needed.
• 🟡 (21:48) In /home/byk/Code/opencode/packages/core/src/session/input.ts:101-141, requestExecution(...) validates the stored row’s Session ID, no-ops if already promoted or wake_pending, and otherwise publishes SessionEvent.PromptExecutionRequested with deterministic ID EventV2.ID.make(\evt_prompt_execution_${input.id}`). If publication defects, it rereads wake_pending` and treats an already-applied projection as success; otherwise it rethrows the defect.
• 🟡 (21:48) In /home/byk/Code/opencode/packages/core/src/session/input.ts:143-178, projectAdmitted(...) rejects a message ID already present in SessionMessageTable, inserts a SessionInputTable row with wake_pending: input.requestExecution, uses .onConflictDoNothing(), and treats a failed insert as SessionInput.LifecycleConflict.
• 🟡 (21:48) In /home/byk/Code/opencode/packages/core/src/session/input.ts:180-201, projectExecutionRequested(...) sets wake_pending: true only for the matching message ID and Session ID whose promoted_seq is null; if no row updates, it accepts an already-promoted matching row as idempotent and otherwise dies with SessionInput.LifecycleConflict.
• 🟡 (21:48) In /home/byk/Code/opencode/packages/core/src/session/input.ts:203-239, prompt promotion atomically sets promoted_seq and clears wake_pending; both the newly updated and already-projected matching paths invoke settleRecoveryWake(...), while projection mismatches produce SessionInput.LifecycleConflict.
• 🟡 (21:47) /home/byk/Code/opencode/package.json pins package manager bun@1.3.14; its root test script is echo 'do not run tests from root' && exit 1, and root typecheck is bun turbo typecheck.