The layered unsafe ledger
§1Defining the memory-safety TCB
This kernel's memory-safety TCB (trusted computing base) is defined as: the code whose memory safety depends on human review rather than the Rust compiler — i.e. every line inside an unsafe block. Everything else is memory-safe by construction (compiler-enforced). The engineering goal is to give a monolithic kernel microkernel-adjacent safety through language-level isolation: shrink the unsafe TCB into a small privileged Framework layer.
§2The layering rules
| Layer | Contents | unsafe policy |
|---|---|---|
| Framework | the hardware/privilege TCB: trap entry, page tables, context switch, raw MMIO/DMA, uaccess, low-level sync primitives (arch/, mm/, interrupt/, the virtio·intc·timer·pci cores, console/printk/sbi/main etc.) | unsafe permitted; every block carries a // SAFETY: invariant comment, coverage tracked in the ledger |
| service | everything userspace-facing (syscall, fs, ipc, net, process, the sched upper layer, cgroup, procfs...) | #![forbid(unsafe_code)] is the target state (currently 47 files compile-time forbidden + 63 files already unsafe-free) |
| diagnostics | dfx/ forensic instruments, raw-memory tooling | reported separately — diagnostic churn must not hide inside the Framework bucket |
| test | test code | excluded from the headline figure |
- The classifier is longest-prefix match; unmatched paths default to service — new files start in the safest bucket and promotion is an explicit act.
- The capsule boundary (the Tock pattern): the syscall entry validates and translates user pointers uniformly; the rest of the kernel does not touch user memory directly. syscall/io.rs going from 69 unsafe tokens to zero is a worked instance — user copies now go through arch/uaccess_safe.rs's address/slice-typed copy_in/copy_out (a new Framework module).
§3Ledger numbers (script-generated, two accounting bases)
Line basis (scripts/tcb_ledger.py, brace-matched unsafe spans, comments and literals stripped)
| Directory | unsafe lines | unsafe density | Notes |
|---|---|---|---|
| Whole kernel | 25,769 / 361,875 lines (376 files, 4,331 unsafe blocks); dual series 50,630 lines (with unsafe fn/impl bodies) | 7.1% (dual 14.0%) | budget rule: the percentage only goes down, or an increase is justified per release |
| fs | 3,978 | 5.2% | ext4 and the page cache form the bulk of the budget |
| syscall | 1,962 | 4.8% | the capsule boundary layer |
| process / drivers | 1,777 / 1,189 | 9.5% / 4.5% | process completed its typed-handle conversion (round 3b) |
| sched | 4,610 | 22.4% | the GRQ/switch paths |
| mm | 805 | 4.0% | allocator unsafety is cohesive inside the primitives |
| sync | 860 | 4.1% | the shape's living instance: one small unsafe core per primitive, a safe API above it |
Accounting note: the dual series (block bodies plus unsafe fn/impl bodies) is the honest total; the block-only series is kept for trend continuity. Since 2026-11-20 the ledger counts only git-tracked sources, so stale build artifacts no longer dilute the denominator. External reference point: Asterinas (USENIX ATC'25, a same-class Rust kernel) reports a memory-safety TCB of ~14% under the same kind of measurement — this kernel sits below it on the block series (7.1%) and level with it on the dual series (14.0%), for which the reference publishes no figure.
Token basis (scripts/gen_tcb_ledger.py; the rule table mirrors kernel-layers.md)
| Bucket | unsafe tokens | Notes |
|---|---|---|
| service | 3,166 | the shrink target (baseline 10-29: 3,085; forbid files 0 → 47) |
| Framework | 1,484 | SAFETY-comment coverage 3,261/5,210 = 63% |
| diagnostics | 225 | dfx instruments |
| test | 105 | excluded from the headline |
Service-token hotspots: fs 612, syscall 478, sync 450, sched 391, process 342, fs/ext4 310, mm 241, net 147.
§4The forbid campaign and the shrink roadmap
- Session 1 (2026-10-29): 113 files carry
#; Session 2 (2026-10-31): the first named shrink target, syscall/io.rs — 69 tokens → 0. - Targets (recorded in security-design.md): forbid files 47 → 90, unsafe-bearing service files 123 → 60 (a two-quarter window).
- SAFETY-comment coverage 64% → 95% (class 2-3 blocks) is the goal.
- The graded-audit plan: class 1 (checked accessor reads) → class 3 (raw pointers with hand-rolled invariants); the ledger's headline will add "class-3 tokens in service code" — the number that actually predicts field bugs. The audit-coverage gate: scripts/review_coverage.py --check fails the build when the tree gains a file the map does not know about.
§5The layering argument: why this shape deserves trust
- Class elimination (compile time), against C-kernel CVE history: buffer overruns (bounds-checked slices), Arc-owned use-after-free/double-free, data races on typed shared state (Send/Sync), iterator invalidation (borrowck), format-string injection (typed formatting) — the dominant classes are unrepresentable in safe code; the taxonomy's zero pointer-expression defects is the empirical face of the same argument (see taxonomy).
- The density argument: sync at 2.8% unsafe density is the layering's living sample — unsafe area scales with primitive complexity, not API surface.
- The pairing argument: every Framework primitive carries (a) a Kani harness, (b) a proptest, and (c) — as the Framework shrinks — a Verus function spec (the registered next step, page-flag/refcount algebra first); RustBelt is cited as the trust anchor, not a build dependency.
- The budget argument: the monotone-down rule on the 14.0% dual series + every newly added unsafe requiring a commit-body explanation of "why safe code was not possible" — TCB growth is constrained by process, not convention.