Architecture Decision Records

Short, dated, in-repo records of the load-bearing engineering choices that shape Zion. Each ADR is a one-page capture of the why behind something a future maintainer would otherwise have to reverse-engineer from git log.

Format: MADR (Markdown ADRs), variant defined in 0000-template.md.

Index

#	Title	Status
0001	ArcSwap for config + TLS hot-reload	accepted
0002	Aho-Corasick over regex for the WAF scanner	accepted
0003	Two-level cache with per-snapshot generation counter	accepted
0004	HMAC-SHA256-chained audit log	accepted
0005	Distroless image, SLSA L3 provenance, cosign keyless signatures	accepted
0006	tracing always-on, OTLP gated by --features otel	accepted
0007	Two-tier MSRV — 1.82 core, 1.88 with optional features	accepted
0008	Embed AIMP as the mesh control-plane bus	accepted
0010	Host-based L7 routing (virtual hosting)	accepted
0011	zion import — nginx config migration, honesty over completeness	accepted
0012	zion import traefik — a second front-end on the neutral seam	accepted
0013	zion import caddy — third front-end, own Caddyfile parser	accepted
0014	Native [tls.acme] emission in the importer	accepted
0015	mode = "static" — opt-in disk file serving	accepted
0016	nginx root/try_files/index → mode = "static"	accepted
0017	Audit-log rotation with per-segment chain re-anchoring	accepted
0018	Cache origin-side revalidation (RFC 9111 §4.3)	accepted
0019	Static file conditional GET (ETag / Last-Modified → 304)	accepted
0020	Static file range requests (206 Partial Content)	accepted
0021	Streaming large static files (lift the 64 MiB read cap)	accepted
0022	Precompressed static sidecars (.br/.gz via Accept-Encoding)	accepted

When to write a new ADR

• A choice between two or more reasonable approaches with non-trivial trade-offs (performance, security, ergonomics).
• A change to an external contract (HTTP, file, registry, log format).
• A choice that locks us into a vendor / crate / protocol we'd find costly to replace later.

When in doubt, write one. The cost of a stale ADR is "delete it"; the cost of a missing ADR is a multi-week archaeology trip.

When not to write an ADR

• Pure refactors with no observable contract change.
• Bug fixes.
• Anything captured well by the commit message / PR description.

Lifecycle

ADRs are immutable once accepted. To revisit, write a new ADR that supersedes the old one and update the old one's status:

- **Status**: superseded by ADR-NNNN

Never edit the body of an accepted ADR — write a follow-up.