Architecture Decision Records
Every system is shaped by the decisions made early — and the ones nobody questioned later. This section documents the why behind Nexus OS: what was chosen, what was rejected, and what the consequences are.
These are not post-hoc rationalizations. Each decision has trade-offs, and we list them honestly.
Decision Log
| ID | Domain | Decision | Key Trade-off |
|---|---|---|---|
| K1 | Kernel | Unikernel over monolithic kernel | POSIX compat needs Membrane translation |
| K2 | Kernel | Zig HAL + Nim kernel logic | Two runtime ecosystems to maintain |
| K3 | Kernel | 12 frozen syscalls over full POSIX — Superseded by K7 | No dynamic extensions possible |
| K4 | Kernel | ION Rings over pipes/sockets | Requires pre-allocated ring capacity |
| K5 | Kernel | Tickless event-driven scheduler | Software timeouts need explicit registration |
| K6 | Kernel | Fibers over processes/threads | No true parallelism on single core |
| K7 | Kernel | Kernel Protocol Boundary — Supersedes K3, amends A2 | Trap ABI becomes implementation detail |
| K8 | Kernel | Cells Own Application State | Application truth is not system truth; no state daemon |
| A1 | Kernel | Single address space | Requires static VA partitioning |
| A2 | Kernel | SysTable frozen ABI — Amended by K7 | Fixed address; layout evolves per SPEC-022 |
| A3 | Kernel | DragonflyBSD LWKT scheduler model | Not perfectly fair for batch workloads |
| A4 | Kernel | No microkernel message-passing | Apps implement own protocols |
| S1 | Security | Capability algebra (7 verbs) | Requires app rewrite for POSIX compat |
| S2 | Security | Pledge/Unveil over Seccomp | No runtime policy changes |
| S3 | Security | Kinetic economy (energy-budget DoS) | Applications see rate limiting as latency |
| S4 | Security | TOFU+ over PKI | Vulnerable to MITM on first contact |
| ST1 | Storage | Graph-native filesystem (NexFS) | Hash computation on every write |
| ST2 | Storage | No /dev, /proc, /sys | Legacy tools need Membrane translation |
| ST3 | Storage | CBOR on-disk format — Amended 2026-07-02 | Narrowed from wire to NexFS DAG + debug; SBI/BKDL supersede for wire/descriptors |
| N1 | Network | TCP/IP in userland (LwIP) | 50-100 KB memory per application |
| N2 | Network | UTCP over QUIC | Limited to Nexus ecosystem |
| N3 | Network | L2 switching only in kernel | ARP less efficient on large segments |
| H1 | Hypervisor | Type-1 hypervisor (RumKV) | Must support each hardware platform directly |
| H2 | Hypervisor | Dual-Pledge enforcement | Hypervisor debugging harder |
| H3 | Hypervisor | Spatial-only partitioning | Unused cores wasted on idle cells |
| P1 | Packaging | Six package types | Higher learning curve for developers |
| P2 | Packaging | Graft → Evolve → Sovereignize | Mixed code quality in intermediate versions |
| P3 | Packaging | GoboLinux hierarchy | Breaks FHS-dependent tools |
| P4 | Packaging | KDL over YAML/TOML | New language, immature tooling |
| D1 | Drivers | Vendor-signed driver accountability | Adoption leverage needed early |
| D2 | Drivers | RISC-V as stable ISA | Secondary targets get weaker model |
| D3 | Drivers | Driver abandonment — use it or lose it | Legal framework and adjudication needed |
| D4 | Drivers | Pledge containment for vendor drivers | Pledge granularity critical for containment |
Format
Each record follows a consistent structure:
- Context — What problem prompted the decision
- Decision — What was chosen
- Alternatives — What was rejected and why
- Consequences — What this means (good and bad)
Decisions marked Accepted are in effect. Decisions marked Superseded have been replaced by a later ADR. We don't delete superseded records — they document the evolution.