# 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](/docs/adr/0001-endpoint-outcome-taxonomy) | Every documented endpoint resolves to verified, unverified with a reason, or excluded | accepted |
| [0002](/docs/adr/0002-declared-pagination) | Pagination is declared as an audited discriminated union, not inferred | accepted |
| [0003](/docs/adr/0003-tolerant-validation-wrapper) | Response validation is a tolerant `TypedDict` base plus a `validator[T]` wrapper | accepted |
| [0004](/docs/adr/0004-declared-envelope-extraction) | Envelope extraction is declared per endpoint, and examples store the raw wire body | accepted, amended by 0010 |
| [0005](/docs/adr/0005-rpc-stream-kind-and-transports) | `spec.kind` is `rpc` or `stream`; transport is a separate `transports` list | accepted, amended by 0006 |
| [0006](/docs/adr/0006-rpc-identifier-and-parameter-authoring) | An RPC operation has one identifier field, and request fields declare a role, not wire placement | accepted |
| [0007](/docs/adr/0007-declared-redaction) | Redaction is declared per endpoint, and example matching is uniqueness-checked | accepted |
| [0008](/docs/adr/0008-whole-body-dump) | A request body serializes through `validator(Type).dump()`, not per-field conversion | accepted |
| [0009](/docs/adr/0009-standalone-project-and-truewire-toml) | Truewire is a standalone project; `truewire.toml` replaces the monorepo's per-client convention | accepted |
| [0010](/docs/adr/0010-response-schema-describes-the-wire-body) | The response schema describes the wire body; `envelope.payload` selects the returned value | accepted |

New entry: copy `0000-template.md`, number it next, add a row above.