Distillation

Date: Sep 16, 2026

• 🔴 (10:13) User requires recovery to treat a newer turn as superseding stale incomplete rows and to “never resume an older assistant projection.”
• 🔴 (10:13) User requires OpenApi.fromApi(PublicApi) to be deferred for processes that never serve /doc, specifically CLI processes and scripts, so they do not pay the cost at module load.
• 🟡 (10:12) packages/core/src/session/context-epoch.ts defines Prepared as { baseline: string, baselineSeq: number }; exported initialize(...) can return Prepared | undefined, while exported prepare(...) always returns Prepared and can fail with SystemContext.InitializationBlocked | ContextSnapshotDecodeError.
• 🟡 (10:12) SessionContextEpoch.prepareOnce concurrently loads the current SystemContext.SystemContext, the stored SessionContextEpochTable row, and SessionHistory.latestCompaction(db, sessionID) using Effect.all(..., { concurrency: "unbounded" }).
• 🟡 (10:12) When no context epoch is stored, SessionContextEpoch.prepareOnce runs SystemContext.initialize(value), inserts the generation under the SessionExecutionClaim.Claim, and returns its generation.baseline with the inserted baselineSeq.
• 🟡 (10:12) Stored context snapshots are decoded with Schema.decodeUnknownEffect(SystemContext.Snapshot); decode failures become ContextSnapshotDecodeError({ sessionID, details: String(error) }).
• 🟡 (10:12) Context replacement is selected only when the latest compaction sequence is strictly greater than stored.baseline_seq; it calls SystemContext.replace(value, snapshot). Otherwise context preparation calls SystemContext.reconcile(value, snapshot).
• 🟡 (10:12) SessionContextEpoch.prepareOnce preserves the stored baseline for Unchanged and ReplacementBlocked. For ReplacementReady, it uses the compaction sequence when available or EventV2.latestSequence(db, sessionID), calls replace(...), and returns the replacement generation’s baseline. A reconciliation update publishes SessionEvent.ContextUpdated and atomically advances the snapshot through its local commit hook.
• 🟡 (10:12) SessionContextEpoch.initializeOnce checks exists(db, sessionID) and does nothing when an epoch already exists; otherwise it initializes context, inserts the generation, and returns { baseline, baselineSeq }.
• 🟡 (10:12) Context epoch mutation helpers in packages/core/src/session/context-epoch.ts are claim-fenced through SessionExecutionClaim.transaction: insert(...) stores session_id, baseline, snapshot, and baseline_seq; replace(...) updates all three generation fields; advance(...) updates only snapshot. replace(...) and advance(...) die with Context Epoch not found if no row is returned.
• 🟡 (10:12) SessionContextEpoch.reset(db, sessionID) deletes the matching SessionContextEpochTable row without taking a SessionExecutionClaim.Claim.
• 🟡 (10:13) packages/core/src/session/message-updater.ts scopes event-driven assistant mutation through updateOwnedAssistant(event.data.assistantMessageID, ...), consistent with refusing to mutate an older assistant projection after a newer turn supersedes it.
• 🟡 (10:13) In packages/core/src/session/message-updater.ts, "session.next.tool.input.delta" is ignored; "session.next.tool.input.ended" replaces the input text only for the latest matching pending tool; "session.next.tool.called" records provider and run timestamp and changes the tool to running with parsed input, empty structured, and empty content.
• 🟡 (10:13) Tool progress updates only a matching running tool’s structured and content. Tool success merges the provider’s executed flag with any prior executed === true, preserves prior provider metadata as metadata, stores completion metadata as resultMetadata, sets time.completed, and changes state to completed with input, structured data, content, outputPaths defaulting to [], and result.
• 🟡 (10:13) Tool failure can settle a matching pending or running tool. It preserves prior execution truth and provider metadata, adds result metadata and completion time, and creates an error state containing event.data.error, {} when the prior input is still a string, prior structured/content only when previously running, and event.data.result.
• 🟡 (10:13) Reasoning projection in packages/core/src/session/message-updater.ts appends an empty AssistantReasoning on "session.next.reasoning.started", concatenates deltas into the latest matching reasoning block, and on "session.next.reasoning.ended" replaces text with the final text, preserves the original creation timestamp when present, records completion time, and replaces provider metadata only when the ending event supplies it.
• 🟡 (10:13) "session.next.compaction.started" and "session.next.compaction.delta" are ignored by the message updater. "session.next.compaction.ended" appends a SessionMessage.Compaction containing messageID, event metadata, reason, summary text, recent context, and creation timestamp. All three revert events—staged, cleared, and committed—are ignored.
• 🟡 (10:13) packages/core/src/event.ts defines durable event commit as a local operational projection committed atomically with the new durable event; it is not replayed or serialized. Supplying a local commit hook for a non-durable event is rejected with Local commit hooks require a durable event.
• 🟡 (10:13) packages/opencode/src/server/routes/instance/httpapi/server.ts divides routing into rootApiRoutes, eventApiRoutes, ptyConnectApiRoutes, instanceApiRoutes, serverRoutes, docRoute, and uiRoute, with distinct authorization layers for normal HTTP APIs, PTY connection, server APIs, and raw router middleware.
• 🟡 (10:13) The legacy instance server’s /doc response is created as lazy(() => HttpServerResponse.jsonUnsafe(OpenApi.fromApi(PublicApi))); this both defers non-trivial OpenAPI generation until /doc is requested and caches the eagerly serialized Uint8Array so later /doc requests do not re-stringify the specification.
• 🟡 (10:14) packages/opencode/src/server/routes/instance/httpapi/server.ts currently builds LayerNode.group([SessionV2.node, SessionRecovery.node]) with [SessionExecution.node, SessionExecutionLocal.node], meaning this route graph still wires local session execution ownership.
• 🟡 (10:14) In the legacy instance server, Observability.layer must remain the final provider because later-provided layers build beneath earlier ones; otherwise eagerly forked fibers such as the ModelsDev background refresh capture Effect’s default stdout logger and corrupt the TUI (#34730).
• 🟡 (10:14) packages/server/src/routes.ts groups Database.node, EventV2.node, httpClient, ToolOutputStore.cleanupNode, SessionV2.node, SessionRecovery.node, PermissionSaved.node, PtyTicket.node, Credential.node, PtyEnvironment.node, and LocationServiceMap.node as applicationServices.
• 🟡 (10:14) packages/server/src/routes.ts also currently wires [SessionExecution.node, SessionExecutionLocal.node] through AppNodeBuilder.build(applicationServices, ...), so the newer server route graph likewise uses local execution ownership.
• 🟡 (10:14) The newer server exposes OpenAPI at /openapi.json; createRoutes(password?) configures username "opencode" with the supplied password when present, while createEmbeddedRoutes() configures username "opencode" with Option.none() for the password.