# Kernel Design Brief — A Capability-Based Device Subsystem
### Derived from the friction of abstracting Linux in the mgf-hrb hardware broker

This document is extracted and expanded from the mgf-hrb design (`mgf-hrb-complete-design.md`, Part 9.6). It exists for one purpose: **to inform the from-scratch OS kernel by treating every place Linux made the hardware broker awkward as a place the new kernel can be clean by design.**

The method is unusual and worth stating, because it's what makes this brief trustworthy: these features were not brainstormed in the abstract. Each one is a *real friction point* encountered while designing a working userspace layer (`mgf-hrb-linux`) against Linux's actual interfaces. Where the broker had to wrestle Linux, the wrestling is evidence of a missing or mis-shaped kernel primitive. **This is a feature list validated by the pain of a real consumer, not a wishlist.**

---

## 1. The thesis — what the friction is telling you

When you collect the friction points (§3) and ask "what underlying kernel decision would make *all* of these dissolve at once," they converge on a single answer:

> **The broker is hard on Linux primarily because Linux's models of *authority* and *lifetime* are ambient and scattered. A kernel where authority is an explicit, attenuable capability and lifetime is a kernel-tracked property of processes would make most of the broker's hardest parts native.**

Concretely: capability enforcement, lease reclamation on death, privilege isolation of the dangerous core, and capability transfer over IPC are *four separate hard problems on Linux* (features 1, 2, 7, 4 below) — and they are *one problem* on a capability-based kernel. They are all the same thing wearing different clothes: "who is allowed to do what, and what happens when the holder dies." Solve that once, at the kernel's foundation, and the four hardest parts of the broker become kernel-native.

**The single biggest signal: design the kernel capability-first.** Make hardware access, IPC, and process lifetime all expressions of one capability model. Everything below is downstream of that decision.

---

## 2. The architectural shape this implies

```
   A capability-based microkernel-ish device model:

   ┌─────────────────────────────────────────────────────────┐
   │  KERNEL                                                    │
   │   • capability space per process (unforgeable, attenuable) │
   │   • hardware access = a capability you hold or don't       │
   │   • IPC = message-passing that transfers capabilities      │
   │   • lifetime = kernel reclaims caps/leases on process death │
   │   • one authoritative resource registry                    │
   │   • native event channel with backpressure                 │
   └───────────────────────────┬───────────────────────────────┘
                               │  (mgf-hrb-youros backend implements
                               │   the same 9-op contract — Part 6)
   ┌───────────────────────────┴───────────────────────────────┐
   │  USERSPACE: mgf-hrb runs unchanged                          │
   │   the broker, workers, SDK, tools — all lift over verbatim  │
   └─────────────────────────────────────────────────────────┘
```

The broker already speaks to an *abstract* kernel (the `mgf-hrb-kabi` seam, 9 operations). Your kernel's job is to implement that seam natively — and because the seam was designed kernel-agnostic, **the entire userspace broker lifts over unchanged the day your backend passes the conformance suite.**

---

## 3. The features, prioritized by leverage

Each feature: what it is, the Linux friction it removes, and a design note for the kernel.

### Feature 1 — Capabilities as a native kernel primitive  ⭐ highest leverage
**What:** every process has a capability space; a capability is an unforgeable, specific, attenuable grant of authority over a resource. Hardware access, IPC endpoints, and resources are all named by capabilities. Attenuation (minting a strictly-weaker capability to delegate) is a kernel operation.
**Linux friction removed:** the broker must enforce capabilities *in userspace* (`mgf-hrb-cap`), because Linux can't. The seam's `enforce_cap` hook is `null` on Linux. A sufficiently privileged local actor can therefore bypass the broker's authority model — the threat model only contains this via privilege-separation gymnastics.
**Kernel design note:** make `enforce_cap` real. When the kernel enforces capabilities, a process *cannot* act beyond its caps even if compromised — the broker's authority model becomes kernel-guaranteed rather than userspace-advisory. This is the foundation; features 2, 4, 7 are corollaries of it.
**Maps to broker:** Part 4 (entire), Part 6.2 (`enforce_cap`).

### Feature 2 — Lease/ownership as a kernel-tracked process property  ⭐ highest leverage
**What:** when a process holds a resource (a device lease), the kernel tracks that ownership and **reclaims it automatically on process death** — crash, kill, or exit — returning the resource to a safe state.
**Linux friction removed:** the broker needs a *heartbeat backstop* (Part 5.5) because Linux only ties reclamation to fd/socket lifetime, which catches crashes but not all hangs. The whole lease-expiry-on-liveness machinery (Part 3.2) exists to compensate for the kernel not owning this fact.
**Kernel design note:** tie resource leases to process lifetime as a kernel invariant. On process death the kernel runs the resource's safe-reset and frees the lease — no heartbeat, no userspace liveness detection, no ghost ownership *possible*. This makes the broker's hardest reliability guarantee (G3) a kernel fact rather than a userspace achievement.
**Maps to broker:** Part 3.2, 3.6, 3.7; Part 5.5.

### Feature 3 — Per-function device isolation from the start
**What:** the IOMMU/isolation model lets you claim and contain a *single* device function independently, not just a whole isolation group.
**Linux friction removed:** VFIO forces whole-IOMMU-group claims — you often cannot claim one function without detaching every device in its group from host drivers. The broker's `acquire` hides this, but the backend wrestles it.
**Kernel design note:** design device isolation at function granularity, so `acquire(one_function)` is genuinely per-function. This simplifies the backend's atomic-acquire (Feature 8) and removes a class of "can't claim X without disturbing Y" surprises.
**Maps to broker:** Part 6.3, 6.5.

### Feature 4 — Message-IPC with native capability transfer and guaranteed ordering
**What:** the IPC primitive is ordered, reliable, message-oriented, *and* transfers capabilities natively (the recipient receives the capability, attenuated if requested, installed in its capability space by the kernel).
**Linux friction removed:** the broker approximates this with `SOCK_SEQPACKET` (for ordering + message boundaries) plus `SCM_RIGHTS` (to smuggle fds as ancillary data). Capability transfer is "pass a file descriptor in a control message" — an awkward hack for what should be a primitive.
**Kernel design note:** make capability-transferring message-passing *the* IPC primitive. The broker's entire control plane (Part 5.2) becomes native, and capability delegation (Part 4.4 attenuation) happens *in the IPC operation itself* rather than as a separate userspace step.
**Maps to broker:** Part 5.2, 5.4.

### Feature 5 — A single authoritative resource registry
**What:** one kernel-owned registry of all hardware resources, with uniform freshness semantics — a single source of truth for "what hardware exists and what state is it in."
**Linux friction removed:** enumeration facts are scattered across sysfs, procfs, and ioctls with inconsistent freshness, forcing the broker into careful per-field `FieldFidelity` tagging (Part 2.8) just to be honest about what it knows.
**Kernel design note:** a unified registry with uniform freshness means `enumerate`/`query_topology` return facts of known, consistent trustworthiness. The broker's fidelity tagging gets simpler (fewer `unknown`/`inferred` cases) and more accurate. The registry is also the natural home for Feature 6's events.
**Maps to broker:** Part 2.7, 2.8; Part 6.5.

### Feature 6 — A native event channel with explicit backpressure, no silent loss
**What:** a kernel event channel for hardware changes (hotplug, state, ownership) with defined backpressure semantics — it blocks or signals an explicit gap, but never silently drops.
**Linux friction removed:** netlink can drop events under flood; the broker must reconstruct gap-honesty (Part 5.3.3) and reconcile against re-enumeration to stay accurate.
**Kernel design note:** an event channel that guarantees either delivery or an explicit gap marker lets the broker's event stream (and the shm rings above it) be honest by construction rather than by careful compensation.
**Maps to broker:** Part 2.9; Part 5.3.3; Part 6.5.

### Feature 7 — Privilege as a thread-held capability, not a process-topology problem
**What:** the authority to touch hardware is a capability a thread holds; isolating "the dangerous code" means scoping which thread holds the hardware capability — not splitting processes.
**Linux friction removed:** isolating the broker's tiny privileged core (Part 7.5) requires seccomp filters, namespaces, or a separate helper process — process-topology acrobatics to approximate "only this code may touch hardware."
**Kernel design note:** with thread-level capabilities, the "tiny privileged core" is simply *the only thread holding the hardware capability*. Privilege separation becomes a capability-scoping question (clean, declarative) instead of a process-splitting one (gymnastic). A direct corollary of Feature 1.
**Maps to broker:** Part 4.9; Part 7.5.

### Feature 8 — `acquire` as a single all-or-nothing kernel operation with native safe-reset
**What:** claiming a device is one atomic kernel operation that either fully succeeds (device exclusively held, isolated, ready) or fully fails (nothing changed); release and safe-reset are native, total operations.
**Linux friction removed:** the broker must compose the VFIO bind / driver-detach / IOMMU dance into atomicity itself (Part 3.4, 6.3), using `errdefer` to unwind partial acquisition. `release` must be made total over operations that can individually fail.
**Kernel design note:** provide atomic acquire and total release/reset as kernel primitives. The broker's atomic-grant sequence (Part 3.4) collapses to a single kernel call, and the "never leave a device half-acquired" guarantee becomes the kernel's responsibility. Pairs with Feature 3 (per-function granularity makes atomicity simpler).
**Maps to broker:** Part 3.4; Part 6.3, 6.5.

---

## 4. Dependency among the features

```
   Feature 1 (capabilities native) ──┬──▶ Feature 4 (cap-transfer IPC)
                                      ├──▶ Feature 7 (privilege = thread cap)
                                      └──▶ Feature 2 (lease = process property)
                                                      │
   Feature 5 (resource registry) ─────────┐          │
                                           ├──▶ Feature 6 (event channel)
   Feature 3 (per-function isolation) ─────┴──▶ Feature 8 (atomic acquire)
```

- **Feature 1 is the keystone.** Build it first; 2, 4, 7 are largely corollaries.
- **Features 3, 5, 8 are the device-mechanics cluster** — the hardware-facing primitives, somewhat independent of the capability core.
- **Feature 6 sits between** — it needs the registry (5) and benefits from the event semantics the capability/lifetime model enables.

A sensible kernel build order mirrors the broker's phasing: capability core (1 → 2, 4, 7) first, then the device-mechanics cluster (3, 5, 8), then the event channel (6) — and at each stage, the corresponding part of `mgf-hrb-youros` becomes implementable.

---

## 5. The acceptance test you already have

The mgf-hrb design ships a **backend conformance suite** (Part 6.4): behavioral tests written against the abstract 9-operation kernel seam, runnable against any backend. It already runs against `mgf-hrb-linux` and an in-memory fake.

**It is, unmodified, the acceptance test for your kernel's device subsystem.** When you write `mgf-hrb-youros` against your kernel and the conformance suite goes green, three things are simultaneously true:
1. Your kernel's device primitives satisfy a contract a real system relies on.
2. The entire mgf-hrb userspace (broker, workers, SDK, tools) runs on your kernel unchanged.
3. You have an objective, mechanical definition of "done" for the device subsystem.

> Build the kernel until the suite is green. That is a rare luxury in kernel work: an external, behavioral, pass/fail definition of correctness for a subsystem, written before the kernel exists, validated by a real consumer.

---

## 5b. Two more features the survivability review surfaced

The adversarial-resistance review (design Part 12) found that the two hardest *survivability* hardenings on Linux are precisely things a capability-native kernel makes easy. They join the feature list:

### Feature 9 — Native time-bounded operations (deadlines)
On Linux, "no hardware call may hang the broker" requires bolting deadlines onto blocking ioctls and running them in killable worker processes guarded by a watchdog — because a frozen device makes a syscall never return. **A kernel that makes every hardware-touching operation natively deadline-bounded** — where the kernel itself guarantees an operation completes, errors, or is cancelled within a caller-supplied bound — removes the entire watchdog/kill/respawn dance. The broker's S2 guarantee (downward fault-containment) becomes a kernel primitive instead of a userspace scaffold. Design implication: hardware operations are *cancellable by construction*, with a deadline as a first-class argument, not a hopeful timeout layered on top.

### Feature 10 — Native handle revocation (revocation below the handle)
On Linux, the broker's performance model (delegate a usable fd, step out of the use path — G4) conflicts with instant revocation: a client keeps a working fd after losing its lease. The Linux fix is to tear down the IOMMU/VFIO mapping *under* the fd so the fd goes inert — a workaround for the kernel's lack of revocable handles. **A kernel where a delegated capability/handle is natively revocable** — where revoking the grant invalidates every outstanding handle to it atomically, no mapping-teardown dance — makes the broker's revocation principle a single kernel call. This also makes multi-tenant *preemption* (Part 5 fairness) trivial: preemption is just revocation. Design implication: handles are kernel-tracked references to a grant, and revoking the grant is O(1) and total — the holder's next access faults, by construction.

> Both features share a theme with Features 1–2: **Linux forces the broker to *approximate* a guarantee the kernel should provide natively.** Capabilities, lifetime-bound ownership, deadlines, and revocable handles are all things a from-scratch capability kernel can make primitive — collapsing large amounts of careful userspace scaffolding into kernel-guaranteed facts.

---

## 6. What this brief deliberately does not cover

Honesty about scope (the same fidelity discipline as the broker design):
- This is the **device-subsystem** brief only. Scheduling, memory management, filesystems, and the rest of the kernel are out of scope — though Feature 1 (capabilities) and Feature 2 (lifetime) will ripple into all of them, and that ripple is probably desirable (a capability-based kernel is capability-based *everywhere*, not just for devices).
- It prescribes *primitives and their semantics*, not *implementation* — whether your capability space is a table, a tree, or a guard-page scheme is yours to choose; the brief only says what the primitive must guarantee.
- The friction list is *what Linux made hard*, which is a strong signal but not a complete kernel design. New hardware classes (Family B: CPU/memory apportionment, Part 2.1) and future buses (GPU) will surface further primitives as `mgf-hrb-cpu` and `mgf-hrb-gpu` are built — treat this brief as living, growing with each new backend friction.

---

## 7. One-line summary

**Design the kernel capability-first — authority, lifetime, time-bounds, and revocation as explicit, kernel-tracked facts — and the hardest parts of the hardware broker, including its survivability under attack and failure, stop being hard. The conformance suite (functional + adversarial) tells you when you've succeeded.**
