Architecture Decision Records¶
Each ADR captures one decision: the context, the options weighed, the
choice, and the consequences we accepted. They are immutable once
Accepted — a reversal gets a new ADR that supersedes the old one.
| # | Decision | Status |
|---|---|---|
| 0001 | Requests are content-addressed | Accepted |
| 0002 | DSSE envelopes, Ed25519, detached signing ceremony | Accepted |
| 0003 | Hash-chained ledger + signed Merkle checkpoints | Accepted |
| 0004 | Ship store protocols + a conformance suite, not adapters | Accepted |
| 0005 | Policies are declarative data, evaluated by a pure function | Accepted |
| 0006 | Canonical JSON (RFC 8785 subset) for all hashing and signing | Accepted |
| 0007 | Reserve-then-complete idempotency for mutations | Accepted |
| 0008 | One hash chain per log_id; partition to scale writes |
Accepted |
| 0009 | Projections are rebuildable and never gate a decision | Accepted |
| 0010 | KMS-agnostic KeyProvider; no bundled KMS in core |
Accepted |
| 0011 | KeyResolver + SigningService for org-level signing |
Accepted |
| 0012 | Custodial attribution & the decision_issuer verify rule |
Accepted |
Reference implementations we studied¶
- in-toto — supply-chain layouts: steps, functionaries, key thresholds, expiry. The closest existing analogue to approval policies.
- The Update Framework — threshold signing, key roles, metadata expiry, key validity windows.
- DSSE — the signing envelope format used by in-toto and Sigstore.
- Certificate Transparency / RFC 6962 — Merkle logs, signed tree heads, inclusion and consistency proofs.
- Sigstore — if you want hosted transparency infrastructure rather than a library.
- RFC 8785 JCS — JSON canonicalization.