type: architecture status: accepted last-reviewed: 2026-08-20 relates-to:
- docs/book/src/foundations/fnd-002-documentation-standards.md
Architecture Decision Records
Architecture Decision Records (ADRs) are the durable record of architecture choices that constrain future ZeroClaw work. They are shorter than RFCs: each one records the context, decision, consequences, and the sources that justify the decision.
Accepted ADRs are immutable. If the architecture changes, write a new ADR and mark the old one as superseded rather than rewriting history.
Current ADRs
| ADR | Status | Decision |
|---|---|---|
| ADR-001 | accepted | ZeroClaw’s runtime and first-party crates are implemented in Rust. |
| ADR-002 | accepted | First-party extension surfaces use explicit trait contracts. |
| ADR-003 | superseded by ADR-009 | WASM plugins initially used Extism as the execution bridge. |
| ADR-004 | accepted | Tool-held shared state follows daemon-owned identity, handle ownership, isolation, and reload rules. |
| ADR-005 | accepted | Memory storage uses a backend-neutral contract with SQLite as the default. |
| ADR-006 | proposed | Runtime plugins are the target for optional channels, with explicit capability-based native exceptions during migration. |
| ADR-007 | proposed | The gateway becomes a separate optional process over a supported local IPC contract. |
| ADR-008 | accepted | Goal mode uses the durable task control plane and canonical usage ledger. |
| ADR-009 | accepted | WIT components and direct wasmtime replace the Extism plugin bridge. |
| ADR-010 | proposed | Session history, curated memory, and enrichment have separate authority boundaries. |
| ADR-011 | accepted | Configured agents have explicit runtime boundaries under one daemon. |
| ADR-012 | proposed | Live config application uses canonical generations and target-specific results. |
| ADR-013 | proposed | Master key acquisition uses one configured key-source authority. |
| ADR-014 | proposed | Plugin network access is mediated by one host-owned egress authority. |
| ADR-015 | proposed | The unified capability catalog is a read-only projection over package, capability, implementation, configuration, and runtime owners. |
| ADR-016 | proposed | Extraction is the default for holding-crate subsystems; bounded exceptions are recorded, scoped, and granted by the Core Team. |
| ADR-017 | proposed | Inbound authentication resolves credentials into canonical principals and permission-profile grants before privileged runtime surfaces act. |
| ADR-018 | proposed | Runtime security and provenance use runtime-owned decision boundaries for protected actions, model admission, internal turns, and canonical evidence. |
ADR-006 and ADR-007 are implementation-gated roadmap decisions from FND-002. Their target directions are recorded, but they remain proposed until the acceptance boundaries in each record ship.
ADR-010 remains proposed until the acceptance gates in the record are met.
ADR-012 remains proposed until canonical config publication, generation-scoped results, and the bounded security and channel live-apply consumers meet the acceptance gates in the record.
ADR-013 remains proposed until the canonical key-source boundary, safe file compatibility, configured fail-closed selection, and a supported non-file source meet the acceptance gates in the record.
ADR-014 remains proposed until the enforced plugin transport boundary, the signature-covered manifest declaration, the operator grant ceremony, and the fleet rollout meet the acceptance gates in the record.
ADR-015 remains proposed until unified catalog projections preserve source-of-truth evidence, artifact provenance, compatibility bridges, and the rule that visibility cannot grant invocation authority.
ADR-016 remains proposed until the holding-crate contract states the exception rule and carries an active-exception table, and at least one exception has been granted or refused through the process.
ADR-017 remains proposed until canonical identity and grant resolution, native and peer-credential compatibility, RPC/WSS enforcement, OIDC and gateway integration, principal-owned session and private-memory storage, migration/recovery documentation, and internal-origin ownership rules meet the acceptance gates in the record.
ADR-018 remains proposed until the runtime action pipeline, ingress/provenance envelope, internal-principal conversation binding, peer reply provenance, separated outcomes, durable audit path, and implementation ratchets meet the acceptance gates in the record.