Add RFCs for the remaining quality-proposal ideas

Eight proposals grouped by category, each with problem statement,
concrete plan, and risks: property-based testing over the
protocol-shaped core (chunk streams, event logs, schema DSL);
mutation testing as the counterweight to the 100%-coverage gate;
deterministic tests + a universal replay-invariant fixture + nightly
race stress; architectural conformance (dependency-cruiser rules and
the LlmAdapter conformance kit); runtime arg validation at the model
boundary with a structured error taxonomy and dev-mode invariants;
doc-sync enforcement (typechecked doc snippets, API reports);
supply-chain checks and nightly vendor-drift verification against the
manifest; and deep-readonly public surfaces (logged-vs-in-flight
mutability boundary). AGENTS.md points at docs/adr and docs/rfc.
This commit is contained in:
Tianyi Cui
2026-06-11 15:27:07 +08:00
parent 9b8fccc6f9
commit 4dafad4db6
10 changed files with 361 additions and 1 deletions

View File

@@ -0,0 +1,43 @@
# RFC 004: Architectural conformance — dependency rules and the adapter kit
Status: proposed
## Problem
Two architectural guarantees currently live only in prose: (1) nothing
depends on the concrete loop package (the microkernel promise, ADR 0002), and
(2) every LlmAdapter speaks the chunk protocol correctly. Both should be
mechanical (ADR 0007).
## Proposal
**dependency-cruiser** with rules:
- `packages/*` (except agent-loop's own tests and examples/) must not import
`@deepseek-ai/dsh-agent-loop`.
- No cross-package deep imports (`@deepseek-ai/dsh-*/src/...` paths) — public
entry points only.
- No import cycles anywhere in packages/.
- `vendor/*` must not import from `packages/*`.
- Layering: dsh-llm imports nothing from other dsh packages; dsh-session only
dsh-llm; etc. (the dependency table in packages/README.md, enforced).
**Adapter conformance kit** in dsh-llm (`@deepseek-ai/dsh-llm/conformance`):
a reusable vitest suite parameterized by an adapter factory, asserting the
chunk-protocol contract — index monotonicity per block, no deltas after
`block-end` for an index, exactly one `finish`, usage at most once, every
`tool-call-delta` carries the call id, abort honored promptly. Run it against
the mocks now; the DeepSeek V4 adapter inherits it on day one. Optionally a
dev-mode `strictAdapter()` wrapper enforcing the same at runtime behind a
debug flag (pairs with RFC 005's invariants).
## Plan
dependency-cruiser config + CI step first (an hour of work, permanent
guarantee); the conformance kit lands with its first consumer test against
MockAdapter, and is a prerequisite for the V4 adapter phase.
## Risks
Dep-cruiser rule maintenance as packages are added — keep rules pattern-based
(`dsh-*`) rather than enumerated.