Architecture Decision Records¶
Issue: #1197
Status: ADR-0001 through ADR-0005 are Accepted. ADR-0006 through ADR-0011 are Proposed and permit only unwired prototypes until accepted (ADR-0010 landed design-first; its unwired prototype follows in the same review). A changed decision requires a new ADR and a supersedes link; do not silently rewrite historical rationale.
Why ADRs Exist¶
Records of significant architectural decisions and the reasoning behind them
— not a design spec (see Technical design
for that) but the why, so a later reader doesn't have to re-derive a
decision from scratch or accidentally re-litigate one that was already made
deliberately. New ADRs are required for future architectural changes — see
blueprint.md for when a change needs a
blueprint/plan before code, which is a related but distinct requirement.
Use template.md for new entries. Number sequentially; never
edit a published ADR's decision after the fact — if a decision changes, write
a new ADR and mark the old one "Superseded by ADR-NNNN."
| ADR | Decision |
|---|---|
| 0001 | Cedar as the policy engine |
| 0002 | SQLite as the default storage backend (Postgres at scale) |
| 0003 | aegis-jcs-1 canonicalization scheme for action_hash |
| 0004 | Ed25519 for optional receipt signing |
| 0005 | Fail-closed defaults for unknown/ambiguous state |
| 0006 | Cache-padded SPSC descriptor fabric (Proposed) |
| 0007 | Sealed generation-tagged slab-page ownership oracle (Proposed) |
| 0008 | Append-only published-prefix slab pages (Proposed) |
| 0009 | Failure-atomic single-page slab/ring admission (Proposed) |
| 0010 | Bounded page rotation with generation-tagged reuse (Proposed) |
| 0011 | v2 wire contracts and logical-event conversion (Proposed) |
Security and Review¶
An ADR affecting identity, tenant isolation, canonicalization, approvals, receipts, policy authority, cryptography, runtime isolation, storage consistency, or fail-closed behavior requires security review and negative acceptance tests. Record residual risk and operational consequences, not only architectural elegance.
Creating an ADR¶
Replace every placeholder, link the issue/design, compare alternatives, name verification, and add the new record here and to MkDocs navigation.
References¶
Architecture Patterns · Technical Design · Threat Model · Documentation Standard