Architecture Decision Records
Numbered, immutable records of significant decisions and why they were made. An ADR is never edited after acceptance; it is superseded by a later ADR that references it. Format follows the lightweight Nygard template (see ADR-0001).
Index
| # | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Spec-first for the on-disk format only | Accepted |
| 0003 | Licensing, and dependency-selection criteria | Accepted |
| 0004 | Rust as the implementation language | Accepted |
| 0005 | Single-provider, closed federation | Proposed |
| 0006 | etcd for coordination; openraft reserved | Accepted |
| 0007 | Reserve append / CAS / watch primitives | Accepted |
| 0008 | TiKV metadata store and pluggable backends | Superseded by 0042 |
| 0009 | Testing strategy | Accepted |
| 0010 | Pluggable deployment substrate; Kubernetes optional | Accepted |
| 0011 | Durability telemetry and declarative management | Accepted |
| 0012 | OpenTelemetry instrumentation; storage/viz agnostic | Accepted |
| 0013 | API-first management surface | Proposed |
| 0014 | Single-binary profile is dev/eval only | Accepted |
| 0015 | Consistency contract: home-zone authority, version-fence reserved | Accepted |
| 0016 | Monorepo and evolving crate structure | Accepted |
| 0017 | Project name (Wyrd) and the Norn component scheme | Proposed |
| 0018 | Reserve hooks for a hyperscale identity consumer | Proposed |
| 0019 | Chunk/fragment on-disk format layout | Accepted |
| 0020 | Global namespace store (L2) and the NamespaceStore trait | Proposed |
| 0021 | Encryption at rest and key management | Proposed |
| 0022 | Multi-tenancy model | Proposed |
| 0023 | Adopt the Act beat: a process-improvement loop | Proposed |
| 0024 | Clock and time-source trust | Proposed |
| 0025 | Internal service-to-service trust | Proposed |
| 0026 | Key management: the KeyService contract and KMS backend selection | Proposed |
| 0027 | Cross-zone replication transport: the ReplicationQueue trait and NATS JetStream default | Proposed |
| 0028 | Erasure-versus-retention precedence | Proposed |
| 0029 | Key-compromise emergency response | Proposed |
| 0030 | Build and release integrity | Proposed |
| 0031 | Watch / change-feed contract | Proposed |
| 0032 | D-server on-disk fragment layout (FsChunkStore) | Proposed |
| 0033 | Fragment durability: redundancy + crash-atomic rename, not per-write fsync | Proposed |
| 0034 | D server disk model: one-per-disk now, multi-disk reserved | Proposed |
| 0035 | No DST-reachable shared mutable global state (seed-determinism discipline) | Proposed |
| 0036 | Internal CA and identity fabric: step-ca now, SPIRE reserved | Proposed |
| 0037 | Proposal and specification process, lifecycle, and immutability | Accepted (supersession-marker clause refined by 0038) |
| 0038 | Supersession is recorded in the index, not on the frozen file | Proposed |
| 0039 | Tier-1 consistency-over-repair as an in-repo Rust scenario; literal Jepsen deferred (refines proposal 0005 §13.2) | Accepted |
| 0040 | Mixed-era placement expansion: one identity-fallback rule, liberal read / strict maintenance (refines proposal 0005 §placement) | Accepted |
| 0041 | Consistency-checker foundation: model the mutable metadata register, not the immutable data path (refines the ADR-0039 deferral; unblocks #329) | Accepted |
| 0042 | Production metadata backend: adopt FoundationDB for the distributed slot (two-slot design + redb embedded + durability-scheme decision carried forward), two named liabilities each mitigated, TiKV then YugabyteDB as ranked fallback; the #257 battery gates deployment (supersedes ADR-0008) |
Accepted |
| 0043 | Testing fixture profiles: one minimal container topology per test class; root compose removed | Accepted |
| 0044 | Provisional pins in the shared conformance suite: mark, don't gate (governs the multi-backend MetadataStore contract; refines ADR-0006) |
Proposed |
| 0045 | Metadata validation boundaries: parse-don't-validate at decode, liberal read / strict maintenance (generalizes ADR-0040's posture across all metadata) | Proposed |
| 0046 | Bucket model: real bucket records in the MetadataStore behind a protocol-neutral container seam; synthesized prefixes rejected (decides #502; shapes #507, #511) |
Accepted |
| 0047 | Object metadata model: ETag (opaque SHA-256 change-token), Content-Type, and Last-Modified as flat optional fields on InodeRecord, committed atomically with the chunk map and preserved across repair (decides #503; foundation for #504, #506, multipart) |
Accepted |
Why not ... ?
ADR-0002 and the architecture overview's section 11 cover the major "why not" questions (why not fork SeaweedFS, why not Ceph, why not MinIO). A dedicated comparison ADR can be added when the project's public positioning needs it.