Architecture Decision Records
This directory records the architectural decisions behind QuantumOS — both as-built (decisions already shipped and gated in CI, status Accepted) and next-phase (decisions being adopted, status Accepted for work in flight or Proposed for planned work). Each ADR carries file:line and PR evidence you can check against the tree.
The as-built ADRs were reconciled from a full ground-truth inventory of the 126 merged PRs (#7–#183) at main. The next-phase ADRs were produced by an adversarial design panel (2026-07-11) that attacked eight candidate directions against the real code; its verdicts — adopt the authenticated swarm plane, the v1 freeze, and honest memory; reject SMP; defer UEFI, a libagent extraction, and a block filesystem — are recorded here. Since then UEFI shipped (ADR-0031, v0.6.2) and SMP was revisited against a measured inventory and kept closed (ADR-0033, accepted 2026-10-30); the later ADRs record the shipped arcs PR by PR.
As-built (Accepted)
| ADR | Title |
|---|---|
| 0001 | Capability-based security as the sole kernel authority model |
| 0002 | Declarative citizen grants resolved at spawn |
| 0003 | Universal user-pointer copy guard at the syscall boundary |
| 0004 | Integer-only math (no kernel FPU) |
| 0005 | Single-core by design (the SMP rejection) |
| 0006 | Holographic field — associative memory as a kernel syscall |
| 0007 | QDSK persistence — fixed homes, superblock-last commit, cold-start |
| 0008 | Explicit intent manifests + enforced quotas above capabilities |
| 0009 | The authority audit ledger |
| 0010 | Cross-ring one-hop capability delegation (SYS_CAP_DERIVE) |
| 0011 | Spawn channels — societies self-assemble |
| 0012 | Quantum stack — front real backends, don't port them |
| 0013 | The QPU broker brokers opaque payloads |
| 0014 | Distributed field societies over N VMs |
| 0015 | The agent-native host surface (MCP + attested bridge) |
| 0016 | Anti-vacuous CI gate discipline |
| 0017 | Honest-slice engineering |
Next-phase
| ADR | Status | Title |
|---|---|---|
| 0018 | Accepted | Versioned releases and a published host package |
| 0019 | Accepted | Authenticate the swarm plane (FSYN + COM2 reply-auth shipped) |
| 0020 | Accepted | Freeze the v1 agent-surface contracts |
| 0021 | Accepted | Honest memory to the 1 GB identity window |
| 0022 | Accepted | COM2 round-trip latency is scheduler-cadence-bound |
| 0023 | Accepted | IPC peer re-wiring on watchdog rebirth + dead-target IPC unlink |
| 0024 | Accepted | virtio-net: one device driver over virtio-pci and virtio-mmio |
| 0025 | Accepted | Reseed each console session after a snapshot restore |
| 0026 | Accepted | QuantumOS as the agent's provider broker (quote, lease, teardown under budgets) |
| 0027 | Accepted | One policy-gated MCP endpoint for the ecosystem (allow / ask / deny per tool) |
| 0028 | Accepted | Sashiko review as a service the person pays for with their own model key |
| 0029 | Accepted | A virtio-vsock channel for the shell, with COM1 kept as the log and the fallback |
| 0030 | Accepted | Networking is an egress grant (default off, allowlist, budgets, receipt), not a side effect of a NIC |
| 0031 | Accepted | UEFI boot: Multiboot1 kept, hybrid ISO, the screen console rendered on the GOP framebuffer; the boot-stack overflow that zeroed page tables on every boot |
| 0032 | Accepted | Rust no_std citizens are the path for running the Kannaka tools inside QuantumOS: a cargo workspace + the C link line, same ABI and capability gate; /bin/rhello (no heap, no authority) and the rkannaka service (libq-arena allocator, a field grant, kannaka's verbs replayed from /etc/kannaka.session) as the CI proofs |
| 0033 | Accepted | SMP revisited for #261: a measured inventory (39 interrupt-off brackets in 14 files, every service an IF=1 kernel thread, LAPIC used only for MSI-X, no ACPI reader), what a big-kernel-lock SMP would and would not keep true, the hardware floor and a cost estimate; single-core stays, with the staged path and the triggers that would reopen it |
Sequencing of the phases
The July panel's four next phases shipped in order, and the arcs since are recorded one ADR each:
- ADR-0018 — release + package at 0.x (v0.4.0 was the first tag;
quantumos-host-toolson PyPI). - ADR-0019 — authenticate the swarm plane (FSYN + COM2 reply-auth).
- ADR-0020 — freeze the v1 contracts (syscall ABI, MCP tool surface, society wire), gated.
- ADR-0021 — honest memory to 1 GB; closed the PMM/kheap reservation gap and the Multiboot2-magic trap.
- ADR-0022, 0023 — what the latency and rebirth work found: COM2 round trips are bound by the scheduler cadence; IPC peers are re-wired on watchdog rebirth.
- ADR-0024, 0025, 0029 — the Firecracker path: one virtio-net driver over pci and mmio, a reseed per console session after a snapshot restore, the shell over vsock.
- ADR-0026, 0027, 0028 — the host tools: the provider broker, the ecosystem hub, and Sashiko review with the person's own model key.
- ADR-0030 — networking is an egress grant (v0.6.2).
- ADR-0031 — UEFI boot and the framebuffer console (v0.6.2); the panel's "defer UEFI" held until a real-machine report needed it.
- ADR-0032 — Rust
no_stdcitizens, the path for the Kannaka tools inside the guest. - ADR-0033 — SMP revisited against a measured inventory and kept closed, with the staged path and the triggers that would reopen it (accepted 2026-10-30).
Still deferred (panel verdicts, no ADR): a libagent extraction (needs a second orchestrator consumer + actor-bearing audit records, ADR-0009's reserved field), and a block/log filesystem (no agent-native consumer needs partial writes; the save disk is a ustar overlay).
Format
Each ADR follows: a number and title; a date and status; Context (the forces), Decision (what was chosen), Consequences (positive, negative, and residual risks — honest negatives are mandatory), and Evidence (shipping PRs, file:line anchors, and the CI gates that prove it). New ADRs take the next free number and never renumber existing ones.