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.
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 |
Sequencing of the next phases
- ADR-0018 (now) — release + package at 0.x. No contract freeze.
- ADR-0019 — authenticate the swarm plane. Extends the COM2/attestation contracts, so it must precede any freeze.
- ADR-0020 — freeze the v1 contracts, after 0019's wire changes settle and the pre-freeze fixes land.
- ADR-0021 — honest memory to 1 GB, standalone; also closes two verified latent defects (the PMM/kheap reservation gap and the Multiboot2-magic trap).
Deferred (panel verdicts, no ADR yet): UEFI boot (revisit at a real CSM-less target), a libagent extraction (needs a second orchestrator consumer + actor-bearing audit records), and a block/log filesystem (no agent-native consumer needs partial writes).
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.