Skip to content

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.