Architecture Decision Records
All architectural decisions are recorded as ADRs in
specs/architecture/adr/.
ADR index
| ADR | Title | Status |
|---|---|---|
| ADR-001 | Pure Rust, No Mochi Dependency | Accepted |
| ADR-002 | Two-Layer Encryption Model (C) | Accepted |
| ADR-003 | System DEK Derivation (Not Storage) | Accepted |
| ADR-004 | Schema Versioning and Rolling Upgrades | Accepted |
| ADR-005 | Erasure Coding and Chunk Durability | Accepted |
| ADR-006 | Inline Data Threshold | Accepted |
| ADR-007 | System Key Manager HA via Raft | Accepted |
| ADR-008 | Native Client Fabric Discovery | Accepted |
| ADR-009 | Audit Log Sharding and GC | Accepted |
| ADR-010 | Retention Hold Enforcement Before Crypto-Shred | Accepted |
| ADR-011 | Crypto-Shred Cache Invalidation and TTL | Accepted |
| ADR-012 | Stream Processor Tenant Isolation | Accepted |
| ADR-013 | POSIX Semantics Scope | Accepted |
| ADR-014 | S3 API Compatibility Scope | Accepted |
| ADR-015 | Observability Contract | Accepted |
| ADR-016 | Backup and Disaster Recovery | Accepted |
| ADR-017 | Dedup Refcount Metadata Access Control | Accepted |
| ADR-018 | Runtime Integrity Monitor | Accepted |
| ADR-019 | Gateway Deployment Model | Accepted |
| ADR-020 | Workflow Advisory & Client Telemetry | Accepted |
| ADR-021 | Workflow Advisory Architecture | Accepted |
| ADR-022 | Storage Backend – redb (Pure Rust) | Accepted |
| ADR-023 | Protocol RFC Compliance Scope | Accepted |
| ADR-024 | Device Management, Storage Tiers, and Capacity Thresholds | Accepted |
| ADR-025 | Storage Administration API | Accepted |
| ADR-026 | Raft Topology – Per-Shard on Fabric (Strategy A) | Accepted |
| ADR-027 | Single-Language Implementation – Rust Only | Accepted |
| ADR-028 | External Tenant KMS Providers | Accepted |
| ADR-029 | Raw Block Device Allocator | Accepted |
| ADR-030 | Dynamic Small-File Placement and Metadata Capacity Management | Accepted |
| ADR-031 | Client-Side Cache | Accepted |
ADR template
New ADRs follow this structure:
# ADR-NNN: Title
**Status**: Proposed | Accepted | Superseded by ADR-XXX
**Date**: YYYY-MM-DD
**Context**: Why this decision is needed.
## Decision
What was decided and why.
## Consequences
What changes as a result. Trade-offs accepted.
## Alternatives considered
What else was evaluated and why it was rejected.
Key decisions by topic
Language and architecture
- ADR-001: Pure Rust (no Mochi dependency)
- ADR-027: Single-language Rust (Go control plane replaced)
- ADR-022: redb as storage backend (pure Rust, no RocksDB)
Encryption
- ADR-002: Two-layer encryption model (system DEK + tenant KEK)
- ADR-003: HKDF-based DEK derivation (not per-chunk storage)
- ADR-011: Crypto-shred cache invalidation TTL
- ADR-028: External tenant KMS providers (Vault, KMIP, AWS KMS, PKCS#11)
Consensus and replication
- ADR-007: System key manager HA via Raft
- ADR-026: Per-shard Raft groups on fabric (Strategy A)
- ADR-009: Audit log sharding and GC
Storage
- ADR-005: Erasure coding and chunk durability
- ADR-006: Inline data threshold
- ADR-029: Raw block device allocator
- ADR-030: Dynamic small-file placement
Protocols and access
- ADR-008: Native client fabric discovery
- ADR-013: POSIX semantics scope
- ADR-014: S3 API compatibility scope
- ADR-019: Gateway deployment model
- ADR-023: Protocol RFC compliance scope
Operations
- ADR-015: Observability contract
- ADR-016: Backup and disaster recovery
- ADR-024: Device management and capacity thresholds
- ADR-025: Storage administration API
Advisory
- ADR-020: Workflow advisory and client telemetry
- ADR-021: Workflow advisory architecture
Client
- ADR-031: Client-side cache