deepseek-harness/docs/rfc

RFCs

One kind of design doc lives here. An RFC records a decision or proposal that shapes this codebase — the why and what we gave up, the parts code and docs can't carry. (Earlier this split into separate "ADR" and "RFC" trees; they were unified, since most ADRs were simply implemented RFCs.)

Layout and naming

Files are grouped by lifecycle into three folders, and an RFC moves between them as its status changes:

• proposed/ — proposals reviewed before implementation; not yet built (or only partly).
• implemented/ — the decision shipped. The file records what was decided and what was rejected, and is kept current with what actually shipped: when the code later moves a file, renames a package, or changes a key/default, the RFC is updated in the same change to match (facts only — paths, names, structure — not the decision itself). See implemented/AGENTS.md.
• rejected/ — the proposal was considered and declined. Kept for the record so the rejection isn't re-litigated.

Each file is named yyyy-mm-dd-topic-title.md, where the date is when the topic was first proposed (per git history). Cross-references between RFCs use relative markdown links ([topic](../implemented/2026-…-….md)) — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.

When to write one

Write an RFC when a decision is durable (it shapes the codebase beyond a single function or package), contested (there was a real alternative a reasonable engineer might have chosen), and surprising (a future reader would otherwise ask "why on earth is it done this way?"). A proposal for substantial future work starts in proposed/; a decision already made starts in implemented/.

Do NOT write one for a mechanical or local choice (a variable name, a one-file refactor), for anything already enforced and explained by a gate or a convention in AGENTS.md, or for a still-provisional decision tagged TODO(...) in the code — record those as TODOs and promote to an RFC only once they settle. An RFC is never edited into a different decision: supersede it with a new one and cross-link. (Editing an implemented/ RFC to track where its already-made decision now lives — a moved file, a renamed package — is not a different decision and is required, not forbidden; see implemented/AGENTS.md.)

Proposed

Title	First proposed
Mutation testing as the coverage counterweight	2026-06-11
Deterministic tests, the replay invariant fixture, and race stress	2026-06-11
Architectural conformance — dependency rules and the adapter kit	2026-06-11
API extractor reports	2026-06-11
Supply chain checks and vendor drift verification	2026-06-11
Agent Client Protocol (ACP) support for external editors	2026-06-14
Multiplex concurrent ACP sessions over one connection	2026-06-14
Optional Code Mode — model writes TypeScript against an SDK of all tools	2026-06-15
Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)	2026-06-16
Unify the agent id and the session id	2026-06-20
Stop mirroring durable boundaries as agent events	2026-06-20
Keep one public stop primitive	2026-06-20
Drop unconsumed assembled LLM convenience surfaces	2026-06-20
Drop the unconsumed llm/adapter-change event	2026-06-20
Prune dead methods from the persistence and bash seams	2026-06-20
Fold trace-only session facts into load-bearing events	2026-06-20
Extract a generic long-running tool runtime	2026-06-20
Make the shared example base providerless	2026-06-20
Use session.jsonl as the only snapshot session-log artifact	2026-06-20
Reorganize packages into a modular hierarchy	2026-06-20
Discover package inventories instead of maintaining static lists	2026-06-20

Implemented

Title	First proposed
Vendor Cordis as source, not npm dependencies	2026-06-11
Microkernel: extension via Cordis event taxonomy, one concrete loop	2026-06-11
Event-sourced sessions with derived message history	2026-06-11
Provider-neutral content-block vocabulary owned by dsh-llm	2026-06-11
Custom typed tool-schema DSL instead of schemastery	2026-06-11
Tool schemas are part of the system-prompt assembly	2026-06-11
Mechanical quality gates over prose guidelines	2026-06-11
tsdown for JS bundling instead of dumble	2026-06-11
Runtime arg validation at the model boundary	2026-06-11
Dev-mode invariants over compile-time deep-readonly	2026-06-11
Property-based testing for protocol-shaped code	2026-06-11
Doc-sync enforcement	2026-06-11
Markdown cross-link validity linting	2026-06-18
Structured error taxonomy	2026-06-11
Capability seams — interface / implementation / consumer split	2026-06-13
Two LLM adapters as a design-verification twin	2026-06-13
Session persistence as an abstract service over SessionEvent	2026-06-14
Every session event is enclosed in a turn	2026-06-15
pnpm as the package manager instead of Yarn 4	2026-06-16
Rich ACP bash rendering — the terminal card (_meta) and command classification	2026-06-18
ACP snapshot tests — record-once / replay-deterministic	2026-06-19
Real-API e2e in CI against the external DeepSeek API	2026-06-19
Drop the mutable session summary	2026-06-19
Shared persistence write coordinator	2026-06-18
Agent lifecycle and ownership seams	2026-06-18

Rejected

Title	First proposed
Deep-readonly public surfaces	2026-06-11
Persist assembled assistant messages, not stream chunks	2026-06-20
Drop ACP session/load until resume has a product shape	2026-06-20
Drop ACP terminal _meta rendering	2026-06-20
Drop bash full-output spill files	2026-06-20
Drop durable step boundary events	2026-06-20
Drop unused session lineage metadata	2026-06-20
Fold the persistence interface into dsh-session	2026-06-20
Collapse tool-owned UI presentation	2026-06-20
Retire mid-turn steering	2026-06-20
Return the ACP bridge to one live session per connection	2026-06-20
Truncate interrupted final turns on load	2026-06-20