Architecture Decision Records¶
These are the decisions that constrain implementation. They exist as separate files, rather than as TIP §66, so they can be cited in a code review by name instead of by a section number inside a 93-section document.
Eight of the ten are mandatory. A pull request that violates a mandatory ADR is rejected or must amend the ADR — those are the only two options.
| ADR | Decision | Status | Enforced by |
|---|---|---|---|
| 0001 | Portable configuration is the source of truth | Recommended | Determinism test, artifact manifest |
| 0002 | Generated runtime is data-driven, not per-operation bespoke code | Strongly recommended | Review rule, generated-e2e |
| 0003 | OpenAPI parser types never escape the adapter package | Mandatory | boundaries script (CI, blocking) |
| 0004 | MCP protocol revisions isolated behind an adapter | Mandatory | boundaries script, protocol E2E |
| 0005 | Upstream auth and MCP auth are separate planes | Mandatory | Token-passthrough regression test |
| 0006 | Secrets are references only | Mandatory | Type-level absence + secret-leakage suite |
| 0007 | Readiness deterministic first, AI second | Mandatory | AI-disabled CI run, determinism test |
| 0008 | Destructive retry disabled by default | Mandatory | Unit tests on retry policy |
| 0009 | Use MCP SDK v2 scoped packages via the modern-era factory path | Mandatory | Wire assertion on server/discover, lint ban on connect() |
| 0010 | User-delegated upstream access is token exchange, never passthrough | Mandatory | Token-passthrough regression test |
Superseded open questions¶
OQ-01 — MCP protocol revision and SDK strategy. Dissolved rather than resolved: the premise (that the official SDK could not serve 2026-07-28) rested on inspecting the legacy @modelcontextprotocol/sdk package. The v2 scoped packages serve the target revision. Recorded in ADR-0009, with evidence in research/sdk-v2-api-notes.md.
Format¶
Context → Decision → Consequences (positive and negative) → Enforcement.
The Enforcement section is not decoration. A decision with no mechanism behind it is a comment, and comments do not survive contact with a deadline. If a new ADR cannot name a test, a lint rule, or a script that upholds it, that is a signal the decision is not yet concrete enough to accept.