Orus

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:

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.

The specification as a region inside every change a step could make, with what the code does inside it, and a kernel that refuses everything also inside it every change a step could make what the specification allows what the code does refuse everything

From above. Whatever an operation does stays inside what its specification allows. A kernel that refused every request would pass this too.

From boot, a witness path reaches each way retype succeeds: freed, unlinked, slice and again; a dashed throwaway path claims false and ends in a cross throwaway: must fail boot Freed Unlinked Slice Again

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.

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:

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.

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.