How Orus is proven
Every change to the kernel is checked by a verifier before it lands. This page explains what the proof says, how it is kept from saying too little, what it rests on, and where AI fits.
What the proof says
Orus’s security claim is about reach. A process’s reach is everything it can get to from the capabilities it holds: the objects they name, the capabilities derived from them, the memory its address spaces map, and, through a control capability to another process, what that process can get to.11 The definition is in reach.rs; why the claim is stated this way is in the design record theorem-over-reach. The theorem has three parts:
- A step taken by a process changes objects only in its reach, and only in the way each object’s kind allows. A send on an endpoint delivers a few words to the matched receiver. A revoke removes capabilities only in the lineage it names. A retype works only on memory the caller’s untyped capability covers.
- Whatever a process does in user mode reads or writes only the memory its own address spaces map.
- Reach grows only when a holder grants a capability, or when a process retypes memory it already holds.
Isolation follows. Two subsystems that share nothing stay that way unless one grants something to the other, and that one-step form is proven.22 lemma_disjoint_step_stays_disjoint. It needs one premise beyond disjoint reach: no thread of one subsystem is waiting on an object of the other. Rights only narrow as well: a capability never gains a right its source did not have.
Most real systems share memory, with a pager or a driver for instance, so a claim that held only for subsystems sharing nothing would say little about them. Stating the theorem per object, over reach, covers the sharing too.
Where it stands. Each kernel operation’s specification states its share of the theorem, and Verus proves the operation meets it. The theorem composed over every step of a running system is not yet proven.
Bounded from above and from below
A proof that code meets its specification is only as strong as the specification. One that says “this operation changes nothing it should not” is met by a kernel that refuses every request. So each verified component in Orus is bounded from both sides.
From above. Whatever an operation does stays inside what its specification allows. A kernel that refused every request would pass this too.
From below. Each way an operation succeeds, here the four of a retype, has a witness that reaches it from any state boot can produce. Each witness has a throwaway that claims false and must fail.
From above is the theorem: each operation changes only what its specification allows.
From below says the operations can actually do their jobs. An operation can succeed in more than one way: a retype of free memory can type it, unlink it, tear down a slice of what was there, or ask to be called again. Each way of each operation has a witness, a verified sequence of operations that starts from any state boot can produce and ends in that outcome. Witnesses are built into no image; they exist to be verified.33 The ways are found by reading the source with witness-inventory.py, so a new operation counts as unwitnessed until someone writes its witness. There are 183 witnesses across the kernel and the verified user crates.
A witness could be hollow: if its premises contradicted each other, anything would follow from them. So each witness has a throwaway, a copy with the same premises that claims something false. If the premises were contradictory, the false claim would verify. The gate requires every throwaway to fail.
A third check pins down what each outcome means. Beside each operation sits a refused claim for each way it succeeds, for instance that it succeeded and changed nothing, and Verus must reject the claim exactly where the postcondition rules it out. That shows the postcondition says what happened, not merely that something did.44 There are 193 refused claims, in the refused/ directory of each verified crate. The design record is refused-claim-per-way.
Ways that no witness reaches yet are listed, one line each, in tools/unwitnessed, and ways with no refused claim in tools/unrefused; each list has eight lines. The gate holds both lists to exactly what the tools find, so a list shrinks when the work is done, and grows only with the maintainer’s sign-off.
What the proof rests on
No proof reaches all the way down to the real machine. Verus proves what code does above a floor of claims it cannot check: what an instruction does, what the language promises. In Orus each such claim is written down along with who vouches for it, so the floor can be read and counted.55 The list is tools/external-body-list, and the rule is the design record who-vouches-for-an-unproven-claim.
- The hardware manual. 22 claims, such as what a TLB flush guarantees once it completes. Each cites the section of the AMD or Arm manual it restates, and the code it covers is the bare instruction or register access, with no logic around it.
- The kernel’s own proof. One claim: the system call as a user program sees it, which restates what the kernel proves of its entry point.
- The language. A rule only Rust’s documentation states is quoted word for word from the pinned toolchain’s source. A toolchain update that changes the passage fails the gate.
- Debt. Anything else, which nothing outside the proof vouches for. There are four items: three spin waits whose termination is not proven, since each ends only while another core keeps running, and one permission that a user library conjures, which this version of Verus cannot check.
Unverified code remains for the glue around hardware and assembly. Every place it hands verified code a value the proof cannot check is listed with who vouches for it.66 tools/boundary-list: 234 sites, of which 54 have nothing vouching for them yet and count as debt. The compiler, Verus and its standard library are trusted, as any compiler is. These checks catch mistakes, not concealment: they assume the committer is not trying to hide anything.
The gate
Every commit passes the gate before it lands on main. The gate requires:
- Verification reports no errors.
- Every list above matches the source exactly. Adding a line to any of them (a new assumption, an unwitnessed way, a site nothing vouches for) needs the maintainer’s approval, which is recorded when the change lands.
- The kernel boots its first process to a clean exit on both targets: x86_64 under KVM, and aarch64 on an Orange Pi 5.
- Every dependency and source file is under a licence on the allowed list.
Where AI fits
AI agents do the day-to-day work. They take an issue, write a failing test, then the change and its proof. Nothing they write is taken on trust: the verifier checks every proof, and the gate checks every commit. Two roles are worth describing.
- The prover searches for a Verus proof of one change. It may add lemmas, assertions and loop invariants. It may not add an assumption or weaken a specification. If the only way through is a weaker claim, it stops and reports that instead.
- The skeptic starts with no context and tries to refute each acceptance criterion of a finished piece of work, using only recorded evidence: commits, verifier output, boot logs. It looks above all for what a proof cannot catch, a specification weaker than what was intended, which verifies cleanly.
Decisions that lower what the proof covers, such as a new assumption, an unwitnessed way or a lowered verification tier, are the maintainer’s alone.77 The agents’ instructions are in the repository, under .claude/agents.
Counts on this page are from kernel commit 31399c5, 17 November 2026.