Architecture Decision Records¶
Durable decisions that outlive any one change. They are created by the adr step of the
spec-driven-adr OpenSpec workflow (see openspec/schemas/spec-driven-adr/schema.yaml) when a
change makes a long-term architectural commitment: a pattern, technology, boundary or contract.
Tactical choices stay in the change's design.md.
Accepted ADRs are immutable. To change a decision, add a new ADR with
Status: accepted, supersedes ADR-NNNN and a Supersedes: line; never edit the old file. What is
in force is found by following Supersedes: links. Files are named NNNN-kebab-title.md,
numbers are monotonic and never reused. Start from template.md.
Index¶
| ADR | Decision |
|---|---|
| 0001 | Embed Switchyard in-process |
| 0002 | Dispatch on Switchyard's client; providers speak OpenAI Chat |
| 0003 | Config-first virtual keys behind a KeyStore trait |
| 0004 | No plaintext secrets in config, logs or the ledger |
| 0005 | SQLite usage ledger with an asynchronous writer |
| 0006 | Money is integer micro-USD |
| 0007 | One-shot modelrelay migration, not a runtime importer |
| 0008 | A routing policy seam in front of Switchyard's algorithms |
| 0009 | Endpoint health lives in the pool and fails open |
| 0010 | Releases are tag-only and built on native runners |
| 0011 | Selectors choose the route from request facts; clients narrow, never widen |
| 0012 | The configuration is an atomically swapped snapshot, reloaded on SIGHUP |
| 0013 | Routing decisions are recorded per request in the ledger database |
| 0014 | Prices are proposed by a CLI and never fetched at runtime (proposed) |
| 0015 | Provider quota is polled at runtime, advisory, and fails open |
| 0016 | Metrics are one registry with bounded labels |
| 0017 | Strict routes exclude disallowed classes before routing |
| 0018 | Cold targets are skipped only when an alternative remains |
| 0019 | Declared capabilities remove targets that cannot serve a request |
| 0020 | Latency-ordered routes rank only what eligibility leaves |
| 0021 | Strengths build pools at load time and never remove a target |
| 0022 | Free-pool membership may be updated on a schedule without review |
| 0023 | Answers that describe the endpoint make it unavailable |
| 0024 | A pool route can end in a guarded tail |
| 0025 | The UI has no state of its own |
How decisions relate to enforcement: invariants that must hold mechanically are listed in ../invariants.md and checked by tests and CI.