Architecture Decision Records
A durable record of decisions that are hard to reverse, cost real evidence to reach, or trade one guarantee for another. Not a changelog: git log already has that. Not a place to restate what the code or a doc page already makes obvious. Write one when a decision would otherwise survive only in a commit message or a pull request thread that might itself get lost.
One file per decision, numbered, never edited in place. A changed decision gets a new ADR that supersedes the old one, and the old one's Status line is updated to say so.
Most of these were carried over from the system Truewire was extracted from. The reasoning is kept; the names and the war stories are trimmed to what still applies.
| # | Title | Status |
|---|---|---|
| 0001 | Every documented endpoint resolves to verified, unverified with a reason, or excluded | accepted |
| 0002 | Pagination is declared as an audited discriminated union, not inferred | accepted, amended by 0013 |
| 0003 | Response validation is a tolerant TypedDict base plus a validator[T] wrapper |
accepted |
| 0004 | Envelope extraction is declared per endpoint, and examples store the raw wire body | accepted, amended by 0010 |
| 0005 | spec.kind is rpc or stream; transport is a separate transports list |
accepted, amended by 0006 |
| 0006 | An RPC operation has one identifier field, and request fields declare a role, not wire placement | accepted |
| 0007 | Redaction is declared per endpoint, and example matching is uniqueness-checked | accepted |
| 0008 | A request body serializes through validator(Type).dump(), not per-field conversion |
accepted |
| 0009 | Truewire is a standalone project; truewire.toml replaces the monorepo's per-client convention |
accepted |
| 0010 | The response schema describes the wire body; envelope.payload selects the returned value |
accepted |
| 0011 | The generator reads a declared core contract and never imports the target package | accepted |
| 0012 | Conformance is a nightly replay of the recorded requests, and drift is a change of shape, never of value | accepted |
| 0013 | seek subsumes window, walk direction is derived from a declared truncation anchor, and every _paged method is a PaginatedResponse |
accepted |
| 0014 | A stream declares its subscription reply schema separately from its push payload | accepted |
| 0015 | The Go backend renders one package per endpoint, verbs with distinct names, and meta as a value the core type-asserts |
accepted |
| 0016 | Protobuf WebSocket frames are decoded at run time from spec/proto sources, as ProtoJSON |
accepted |
| 0017 | gRPC endpoints are planned from spec/proto, rendered over each language's standard protobuf stubs, and tested against an in-process fake server |
accepted |
| 0018 | A request field minted per call is ignored by a located path under match.ignore |
accepted |
| 0019 | A list in the query string is written as the endpoint declares under match.query_arrays |
accepted |
New entry: copy 0000-template.md, number it next, add a row above.