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:
43
docs/rfc/004-architectural-conformance.md
Normal file
43
docs/rfc/004-architectural-conformance.md
Normal 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.
|
||||
Reference in New Issue
Block a user