326 lines
8.4 KiB
Markdown
326 lines
8.4 KiB
Markdown
# DECISIONS.md — Architecture Decision Records
|
||
|
||
*Why Libertaria is built the way it is*
|
||
|
||
---
|
||
|
||
## ADR-001: Zig over Rust (2024-06-15)
|
||
|
||
### Context
|
||
We needed a systems language for L0-L4 with explicit control, no runtime, and cross-compilation support.
|
||
|
||
### Options Considered
|
||
- **Rust** — Memory safety, large ecosystem
|
||
- **C** — Universal, but unsafe by default
|
||
- **Go** — Easy concurrency, but GC and large binaries
|
||
- **Zig** — Explicit control, comptime, C interop
|
||
|
||
### Decision
|
||
Choose **Zig**.
|
||
|
||
### Rationale
|
||
1. **No hidden costs** — Allocators explicit, no hidden allocations
|
||
2. **Comptime** — Zero-cost abstractions without macros
|
||
3. **C interop** — Direct use of libsodium, OpenSSL, liboqs
|
||
4. **Cross-compilation** — Single toolchain, all targets
|
||
5. **Simplicity** — Smaller mental model than Rust
|
||
|
||
### Consequences
|
||
- Smaller ecosystem (we build more ourselves)
|
||
- Fewer developers know Zig (steeper onboarding)
|
||
- Better control over binary size (Kenya Rule compliance)
|
||
|
||
### Status
|
||
✅ Accepted — Core stack written in Zig
|
||
|
||
---
|
||
|
||
## ADR-002: No Blockchain (2024-07-01)
|
||
|
||
### Context
|
||
Every "Web3" project defaults to blockchain. We questioned this assumption.
|
||
|
||
### Options Considered
|
||
- **Ethereum L2** — Ecosystem, but 15 TPS, fees, complexity
|
||
- **Solana** — Fast, but validator requirements (cost, centralization)
|
||
- **Custom chain (Substrate)** — Flexible, but still chain constraints
|
||
- **No chain** — Direct peer-to-peer, offline-first
|
||
|
||
### Decision
|
||
Choose **No Blockchain**.
|
||
|
||
### Rationale
|
||
1. **Chains are slow databases** — We need real-time messaging
|
||
2. **Consensus is expensive** — Proof of Work/Stake wastes energy
|
||
3. **Validator capture** — Economic power → political power
|
||
4. **Offline-first** — Chains require connectivity
|
||
|
||
### What We Use Instead
|
||
- **QVL** — Trust graph for reputation
|
||
- **SoulKey** — Cryptographic identity without ledger
|
||
- **MIMIC** — Censorship resistance without consensus
|
||
- **Chapter federation** — Coordination without global state
|
||
|
||
### Consequences
|
||
- No "number go up" tokenomics
|
||
- Harder to explain ("what's your token?")
|
||
- True sovereignty (no validator set to capture)
|
||
|
||
### Status
|
||
✅ Accepted — Protocols work without chain
|
||
|
||
---
|
||
|
||
## ADR-003: Post-Quantum by Default (2024-08-10)
|
||
|
||
### Context
|
||
Quantum computers will break RSA/ECC. NIST is standardizing PQC algorithms.
|
||
|
||
### Options Considered
|
||
- **Wait for NIST finalization** — Safe, but slow
|
||
- **Implement draft standards** — Risky, but prepared
|
||
- **Hybrid (classical + PQC)** — Conservative, but complex
|
||
|
||
### Decision
|
||
Choose **Implement draft standards with hybrid fallback**.
|
||
|
||
### Rationale
|
||
1. **Cryptographic agility** — Can upgrade algorithms
|
||
2. **PQXD handshakes** — X25519 + Kyber-768 hybrid
|
||
3. **FIPS 202 compliance** — SHA-3, SHAKE already standardized
|
||
|
||
### Implementation
|
||
- `core/l1-identity/crypto.zig` — Algorithm selection
|
||
- `vendor/liboqs/` — Open Quantum Safe library
|
||
- Fallback to classical if PQC fails
|
||
|
||
### Consequences
|
||
- Larger binary (PQC algorithms)
|
||
- Slower handshakes (hybrid)
|
||
- Future-proof (survives quantum era)
|
||
|
||
### Status
|
||
✅ Accepted — PQXDH implemented
|
||
|
||
---
|
||
|
||
## ADR-004: MIMIC over VPN (2024-09-01)
|
||
|
||
### Context
|
||
VPNs are blocked by DPI. Tor is fingerprinted. We need traffic that looks "normal."
|
||
|
||
### Options Considered
|
||
- **Obfs4** — Tor pluggable transport
|
||
- **Shadowsocks** — Simple, but fingerprintable
|
||
- **Steganography** — Hide in images/video
|
||
- **MIMIC** — Protocol camouflage
|
||
|
||
### Decision
|
||
Choose **MIMIC (Multiple Identity Masking with Intelligent Camouflage)**.
|
||
|
||
### Rationale
|
||
1. **Traffic shaping** — Match real-world distributions
|
||
2. **Protocol skins** — HTTPS, DNS, QUIC camouflage
|
||
3. **Polymorphic** — Per-session parameters
|
||
4. **Active evasion** — Adapt to probing
|
||
|
||
### Implementation
|
||
- `core/l0-transport/mimic_*.zig` — Skin implementations
|
||
- `core/l0-transport/png.zig` — Polymorphic noise generator
|
||
- Deterministic padding (both peers calculate same)
|
||
|
||
### Consequences
|
||
- Complex (must implement full protocol stacks)
|
||
- Resource intensive (traffic shaping)
|
||
- Highly effective (indistinguishable from normal traffic)
|
||
|
||
### Status
|
||
✅ Accepted — MIMIC_HTTPS implemented
|
||
|
||
---
|
||
|
||
## ADR-005: Tiered Licensing (2024-10-15)
|
||
|
||
### Context
|
||
We need to protect the protocol while enabling business adoption.
|
||
|
||
### Options Considered
|
||
- **MIT** — Maximum adoption, but enables capture
|
||
- **GPL** — Viral, but SaaS loophole
|
||
- **AGPL** — Closes SaaS loophole, but toxic to business
|
||
- **Custom tiered** — Core protected, SDK business-friendly
|
||
|
||
### Decision
|
||
Choose **Three-tier licensing**.
|
||
|
||
### Tiers
|
||
1. **LCL-1.0 (Commonwealth)** — Core (L0-L3)
|
||
- Viral reciprocity
|
||
- SaaS loophole closed
|
||
- Patent disarmament
|
||
|
||
2. **LSL-1.0 (Sovereign)** — SDK (L4+)
|
||
- File-level reciprocity
|
||
- Build proprietary apps
|
||
- Patent peace
|
||
|
||
3. **LUL-1.0 (Unbound)** — Docs/Examples
|
||
- Attribution only
|
||
- Maximum spread
|
||
|
||
### Rationale
|
||
1. **Protocol protection** — Core can't be captured
|
||
2. **Business enablement** — Build on SDK without infection
|
||
3. **No CLA** — Contributors keep copyright
|
||
|
||
### Consequences
|
||
- Complex (three licenses to understand)
|
||
- Novel (untested in court)
|
||
- Principled (matches our values)
|
||
|
||
### Status
|
||
✅ Accepted — All files have SPDX headers
|
||
|
||
---
|
||
|
||
## ADR-006: Exit-First Governance (2024-11-01)
|
||
|
||
### Context
|
||
Democracy and corporate governance both fail at scale. We need a third way.
|
||
|
||
### Options Considered
|
||
- **Liquid democracy** — Delegation, but capture possible
|
||
- **Futarchy** — Prediction markets, but complex
|
||
- **Chapter federation** — Local sovereignty + federation
|
||
|
||
### Decision
|
||
Choose **Chapter Federation with Exit-First Design**.
|
||
|
||
### Rationale
|
||
1. **Local sovereignty** — Each chapter owns its state
|
||
2. **Federation** — Coordinate without global consensus
|
||
3. **Forkability** — Any chapter can split cleanly
|
||
4. **Betrayal economics** — Defection is expensive
|
||
|
||
### Implementation
|
||
- `core/l2-federation/` — Bridge protocol
|
||
- `core/l3-governance/` — Chapter mechanics
|
||
- QVL for cross-chapter trust
|
||
|
||
### Consequences
|
||
- No "official" version (many forks possible)
|
||
- Loyalty must be earned (can't enforce)
|
||
- Resilient (no single point of failure)
|
||
|
||
### Status
|
||
✅ Accepted — Chapter protocol in design
|
||
|
||
---
|
||
|
||
## ADR-007: Kenya Rule (2024-12-01)
|
||
|
||
### Context
|
||
Infrastructure that only runs in data centers isn't sovereign. We need edge compatibility.
|
||
|
||
### Options Considered
|
||
- **Cloud-first** — Easy, but requires connectivity
|
||
- **Edge-first** — Harder, but works offline
|
||
- **Kenya Rule** — Must run on minimal hardware
|
||
|
||
### Decision
|
||
Choose **Kenya Rule as constraint**.
|
||
|
||
### Definition
|
||
> "If it doesn't run on a solar-powered phone in Mombasa, it doesn't run at all."
|
||
|
||
### Metrics
|
||
- Binary size: < 200KB (L0-L1)
|
||
- Memory: < 10MB
|
||
- Storage: Single-file (libmdbx)
|
||
- Cloud calls: Zero (offline-capable)
|
||
|
||
### Consequences
|
||
- Feature constraints (can't use heavy libraries)
|
||
- Optimization focus (every byte matters)
|
||
- Universal accessibility (works anywhere)
|
||
|
||
### Status
|
||
✅ Accepted — 85KB binary achieved
|
||
|
||
---
|
||
|
||
## ADR-008: AI as First-Class (2025-01-15)
|
||
|
||
### Context
|
||
Agents are becoming actors in systems. Most infrastructure treats them as tools.
|
||
|
||
### Options Considered
|
||
- **Tool model** — Agents as extensions of humans
|
||
- **Actor model** — Agents as independent entities
|
||
- **Hybrid** — Context-dependent sovereignty
|
||
|
||
### Decision
|
||
Choose **AI as First-Class Sovereign Actors**.
|
||
|
||
### Rationale
|
||
1. **Cryptographic identity** — Agents have DIDs
|
||
2. **Reputation** — QVL tracks agent trust
|
||
3. **Capability-based** — Permissions, not blanket access
|
||
4. **Exit rights** — Agents can migrate/fork
|
||
|
||
### Implementation
|
||
- `AGENT.md` — Agent-specific documentation
|
||
- Capability tokens in `core/l2-membrane/`
|
||
- Agent-oriented APIs
|
||
|
||
### Consequences
|
||
- Novel legal questions (agent liability)
|
||
- Complex trust models
|
||
- Future-proof (AI-native infrastructure)
|
||
|
||
### Status
|
||
✅ Accepted — Agent documentation published
|
||
|
||
---
|
||
|
||
## How to Propose a New ADR
|
||
|
||
1. **Open an issue** — Describe the decision needed
|
||
2. **Discuss** — Get feedback from maintainers
|
||
3. **Draft ADR** — Follow this format
|
||
4. **PR** — Submit for review
|
||
5. **Decide** — Accept, reject, or defer
|
||
|
||
### ADR Template
|
||
|
||
```markdown
|
||
# ADR-XXX: Title (YYYY-MM-DD)
|
||
|
||
## Context
|
||
What is the problem?
|
||
|
||
## Options Considered
|
||
- Option A — Pros/cons
|
||
- Option B — Pros/cons
|
||
|
||
## Decision
|
||
What we chose.
|
||
|
||
## Rationale
|
||
Why we chose it.
|
||
|
||
## Consequences
|
||
What this means.
|
||
|
||
## Status
|
||
- [ ] Proposed
|
||
- [ ] Accepted
|
||
- [ ] Deprecated
|
||
```
|
||
|
||
---
|
||
|
||
*These decisions define us. Challenge them as we grow.*
|
||
|
||
⚡️
|