Skip to content

Commit 50858d7

Browse files
Add ADR 0008: session-bound runtime + gRPC protocol; supersede ADR 0007
ADR 0008 records the architectural pivot from automatic server-side prefix matching (ADR 0007) to an explicit session-bound runtime, driven by: * Empirical failure of ADR 0007's primitive against Qwen3's enable_thinking=False chat template (continuation_rate = 0.0 in local-only smoke #2 evidence). * User-stated 2026-06-01 strategic frame: standalone runtime for local agent applications, no framework coupling, no deadline, no sunk-cost reasoning, extreme KV efficiency, zero intelligence regression. * The need to make 'long-session usability' falsifiable on Mac M4 without depending on any one tokenizer template's round-trip stability. Key decisions captured: * gRPC bidirectional streaming as the primary wire protocol; HTTP+SSE preserved as a deprecated single-shot shim. * Server-issued session_id, raw-token-history, append-only contract. No chat template at the runtime ever. * Per-session sink+window KV slab, byte-exact bound to (session_id, history_token_ids). INV-1 / INV-2 / INV-3 refined for sessions. * Python and TypeScript SDKs as first-class v0.3 deliverables (TS targets Node/Electron/Bun, not browser). * Mac M4 integration test report as a binding pre-merge gate (\u00a79). ADR 0007 is marked Superseded by 0008; none of its implementation reaches main (recorded as decision C3=b on 2026-06-01). Index README updated. This PR ships only the markdown; implementation will land in PR sequence A1..F1 documented in \u00a76. No code changes here. Co-authored-by: FluffyAIcode <FluffyAIcode@users.noreply.github.com>
1 parent 0fecf20 commit 50858d7

3 files changed

Lines changed: 910 additions & 2 deletions

File tree

docs/adr/0007-cross-request-kv-reuse.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR 0007 — Cross-request KV cache reuse for long sessions
22

3-
- **Status**: Accepted (2026-05-31, blocking v0.3.0 GA)
3+
- **Status**: Superseded by [ADR 0008](0008-session-bound-runtime-and-grpc-protocol.md) (2026-06-01). Originally Accepted 2026-05-31; superseded after empirical falsification of §2.4 by Qwen3 chat-template re-rendering. None of this ADR's implementation reached `main`. See ADR 0008 §1.2.
44
- **Date**: 2026-05-31
55
- **Decision drivers**: ADR 0006 §2.3.b empirical evidence (4-hour Mac M4
66
run); the gap between the "local agent infrastructure" framing and the

0 commit comments

Comments
 (0)