Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions CONSTITUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,9 @@ The kernel is hand-written and minimal. It provides mechanism, never policy.
*(Fuchsia/Zircon)*
- **Known graves to avoid:** multi-copy IPC (Mach), policy in the kernel
(early microkernels), baroque capability hierarchies (KeyKOS), bolted-on
multicore support.
multicore support, drivers pulled into the kernel for the fast path
(vhost-net), compiled-in but unused device paths (VENOM), and the catch-all
right that decays into root (CAP_SYS_ADMIN).

## 4. The Borrow Ledger

Expand Down Expand Up @@ -282,9 +284,12 @@ replacing Linux, supporting every board on earth.
IPC fast path, capability tables, MMU, UART console. Then the same kernel
on QEMU x86_64 `q35`, proving the HAL boundary.
- **Phase 2 — Voice.** Scheme registry, first userspace driver (virtio),
minimal runtime; port first Redox drivers.
- **Phase 3 — Soul.** The pillars: broker, signed content-addressed app
format, updater. First real app runs confined.
minimal runtime; port first Redox drivers. Scheme mediation begins here — the
registry is the first broker-shaped component — so the confused-deputy and
scheme-escape obligations bind from this phase, ahead of the full broker.
- **Phase 3 — Soul.** The pillars: the full broker (grant policy, prompt
surface, revocation), signed content-addressed app format, updater. First
real app runs confined.
- **Phase 4 — Company.** Publish, write the show-don't-tell posts, open to
contributors.

Expand Down
17 changes: 17 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,23 @@ recorded is indistinguishable from law that was never agreed.

### Changed

- **Constitution §3 amended, on the maintainer's authorisation (2026-08-01): three graves added from
the second prior-art review.** The "known graves to avoid" list gains *drivers pulled into the
kernel for the fast path* (vhost-net's CVE-2019-14835 guest-to-host-kernel escape, the userspace-
driver doctrine argued by counterexample), *compiled-in but unused device paths* (VENOM,
CVE-2015-3456 — a floppy controller exploitable with no floppy configured; "absent beats disabled"),
and *the catch-all right that decays into root* (CAP_SYS_ADMIN — a standing review rule on `Rights`
growth). All three are documented production disasters the review mapped to Setonix decisions;
taking them as graves makes the doctrine list say so.
- **Constitution §10 clarified, and the threat model's §8 reconciled with it (2026-08-01): where the
broker binds.** The roadmap's Phase 2 — Voice now states that scheme mediation begins there (the
scheme registry is the first broker-shaped component), and Phase 3 — Soul names the *full* broker
(grant policy, prompt surface, revocation). This removes a disagreement the second prior-art
review's follow-through exposed: the threat model's §8 binds O-10 (confused deputy) and O-11 (scheme
escape) in Phase 2, which is correct because mediation exists from the scheme registry — but §10 had
grouped the whole broker under Phase 3, so §8 appeared to contradict the roadmap it maps against.
Both documents now agree: *mediation* (the O-10 surface) starts in Phase 2; the *broker pillar* and
its own obligations O-21..O-23 land in Phase 3. §8 gains a paragraph stating the split explicitly.
- **Threat model amended (2026-08-01): seven obligations from the second prior-art review, and a
fast-forward clause on O-15.** The [virtualisation and containment review](research/0002-virtualisation-and-containment-prior-art.md)
surfaced gaps that no existing obligation covered; per §11's "new surface, new obligation" rule they
Expand Down
7 changes: 7 additions & 0 deletions docs/threat-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,13 @@ hidden.
| **Phase 2 — Voice** | scheme registry, first userspace driver | O-9, O-10, O-11, O-17 bind; O-26 binds with the first multiplexing server; O-18 becomes relevant as soon as a driver can DMA |
| **Phase 3 — Soul** | broker, signing, store, updater | O-12, O-14, O-15, O-16 bind; O-21, O-22, O-23 bind with the broker; O-24, O-25 bind with the store and updater; O-13's W^X becomes load-path-enforced |

The broker's obligations bind across two phases on purpose, and the constitution's §10 was clarified
to match: O-10 and O-11 bind in **Phase 2** because the scheme registry that lands then is itself the
first broker-shaped mediator, so the confused-deputy and scheme-escape disciplines apply the moment
mediation exists — while the full-broker obligations O-21..O-23 bind in **Phase 3** with the broker
pillar (grant policy, prompt surface, revocation). "Broker" is therefore a Phase-3 deliverable, but
*mediation* — the surface O-10 guards — is not deferred to it.

Today, three of twenty-seven obligations are Built. That ratio is the honest status of a Phase-1
kernel, and stating it is the point: this document is the specification the ratio is meant to climb
against, not a description of a system that already holds the line. The seven obligations the second
Expand Down