danos/docs/bounds-track-plan.md

# The bounds track: removing the numbers we invented

*Plan, 2026-08-08. Follows [fixed-bounds-audit.md](fixed-bounds-audit.md) (235 ceilings,
139 on quantities we do not choose) and the AMD Ryzen that found the first one.*

---

## Live state — the unattended run

*This table is the progress view. It is updated at the end of every step, before the
next one starts.*

| Step | What | State |
|---|---|---|
| L1 | Reclamation: a dead task's registrations die with its claims | **stopped — the step was wrong; see open question 4** |
| L2 | Bounds build check + allowlist; declare what we have already touched | **done** — `zig build bounds`, 273 allowlisted, 5 declared |
| L3 | xHCI: slot count from `HCSPARAMS1.MaxSlots`, not 8 | **done** — QEMU reports 64; the driver tracked 8 |
| L4 | USB: configuration descriptor sized by `wTotalLength`, not 512 | **done** — QEMU tops out at 211 bytes, so the case catches the class, not the original trigger |
| L5 | USB: interfaces from the descriptor, and the misattributed-endpoint bug | **done** — fix is by construction; no direct test, see open question 5 |
| L6 | xHCI: a failed `allocateDevice` stops leaking an enabled slot | **done** — path forced and verified; no regression test, see open question 5 |

**Run 1 complete.** L1 stopped (the step was wrong), L2–L6 landed. Suite 115 → 116.
Allowlist 278 → 269. Two steps ship without a permanent regression test, both because
QEMU's USB devices are too small to reach the paths — see open question 5, which is the
audit's own lesson recurring: the test rig is smaller than a real machine.

---

## Run 2 — device authority: delete the invented ceilings

*Design: [device-authority.md](os-development/device-authority.md), which is the **how**
for the delegation step [device-manager.md](device-driver-development/device-manager.md)
already settled. Read both before starting; the second is authoritative where they
differ.*

The goal, in the project owner's words: **remove the maximum values we set arbitrarily,
move the responsibility to the device manager, and keep in the kernel only the parts
that cannot safely run in user space.**

| Step | What | State |
|---|---|---|
| D1 | `device_transfer(device_id, task_id)` — the holder gives a device away | **done** — syscall 54; a move, not a copy |
| D2 | Adversarial case: a process handed nothing is refused, on a held device and a free one | **done** — `device-authority-test`; the claim half joins it at D6 |
| D3 | The manager claims the seeded devices at boot, before any driver is spawned | **merged into D4** — see below |
| D4 | The manager claims + delegates on `hello`; `usb-xhci-bus` is the first driver converted | **done** — caught an IOMMU regression I introduced; see below |
| D5 | The other four claimants converted: `pci-bus`, `ps2-bus`, `virtio-gpu`, `acpi` | **partial** — `pci-bus` done; the other three need decisions, see below |
| D6 | `device_claim` refuses a device the caller was not handed; the hole is closed | not started |
| D7 | Zero-resource devices stop being kernel objects — inventory moves to the manager | not started |
| D8 | **`maximum_children_per_parent` deleted** — the authorisation it stood in for exists | not started |
| D9 | The device table becomes dynamic; **`maximum_devices` deleted**; per-holder quota declared | not started |

Ordering is load-bearing. D1–D2 build and prove the mechanism with nothing depending on
it. D4–D5 move each claimant across one at a time, so the suite stays green throughout
and a regression names the driver that caused it. D6 is the flag day. D7 must precede
D9, because zero-resource children are the case that sidesteps containment and so the
reason a shared cap was needed at all.

**D3 merged into D4** (found while implementing, recorded rather than worked around).
The two cannot be separated: the moment the manager claims a device, any driver still
calling `device_claim` on it is refused `AlreadyClaimed`, so D3 on its own turns the
suite red — and D3 applied to *nothing* changes no behaviour and cannot be tested.
They land together, with the manager claiming only for drivers in an explicit
**delegated set** so every unconverted driver keeps claiming exactly as before.
`usb-xhci-bus` is the first member, as it was the first driver to conform to `hello`
(device-manager.md, M18.1). D5 moves the rest in one at a time; the set and the
`device_claim` path both disappear at D6.

### Observations from the run

- **D4 introduced an IOMMU regression, caught by converting one driver at a time.**
  `confineDevice` runs inside `systemDeviceClaim`, so a device arriving by *transfer*
  was never confined for its new owner: the driver's DMA rings went unbound (three
  IOMMU+USB cases failed), and two worse consequences were latent — a manager death
  would have torn down a domain a live driver was using, and a driver death would have
  leaked one. `iommu.reassign` moves the confinement with the device, keeping the
  domain and attachment intact so it never translates through nothing. Converting all
  five drivers at once would have produced the same three failures with five suspects.
- **`usb-hub` failed once in a full run, then passed six times** (four isolated, two
  full). Suspected instance of the known intermittent AP ring-3 fault rather than
  anything in D4 — recorded rather than dismissed, because D4 moved the `hello` earlier
  and so did shift boot timing. Watch it across the remaining steps.

### Open questions raised by D5 — three of the four claimants cannot be converted yet

Delegation is delivered in `onHello`. That works for a driver that says hello, and
**two of the four do not**.

6. **`ps2-bus` and the `acpi` service never hello at all**, and that is deliberate:
   device-manager.md records "Legacy drivers (e.g. ps2-bus) are supervised and
   restarted but **not yet required to hello**", and the `Driver.speaks_protocol` flag
   exists to say so. Delegating to them means either making them speak the protocol —
   promoting them out of "legacy", which is a change to their documented status — or
   giving the grant a second delivery point that is not `hello`. Neither is written
   down. A second delivery point would also need its own answer to "when", since the
   whole value of `hello` here is that it is the moment the driver is known to be alive
   and is a synchronous point to hand something over.

7. **`virtio-gpu` hellos, but best-effort by design.** Its call is
   `_ = device_manager.hello(.device, device_id);` with the comment "Best-effort:
   standalone bring-up has no manager." Delegation would make the hello *mandatory* and
   move it to the front, so the driver could no longer come up without a manager. No
   test exercises standalone today (the `virtio-gpu` case boots the manager stack, and
   devices.csv matches it), so this is a documented intent rather than a live path —
   but discarding a documented intent is a decision, not a mechanical step.

Until these are answered, `device_claim` cannot be closed off at D6 for those three, so
**D6 is blocked on question 6 and 7**. D7–D9 are not: they concern what the kernel
stores and how the table is sized, and are independent of which drivers have converted.

### Settled, so the run does not re-litigate them

- **The manager claims, it is not granted.** No binary names in the kernel; the rule is
  "you may give away what you hold". The residual — it rests on the manager claiming
  first — is stated in the design and is closed later by the spawn capability
  [drivers.md](device-driver-development/drivers.md) already names as missing.
- **The framebuffer is not a device.** It is where pixels go, handed over by the loader,
  and the compositor uses it as the boot floor until a real display driver announces
  itself. Nothing in this run touches the display service or its GOP path.
- **`maximum_endpoints_per_interface` and the wire structs stay.** Widening them is a
  protocol change, out of scope.
- **A per-holder quota is not a retreat.** Dynamic storage with no bound moves the
  ceiling to the kernel heap, which is shared and fatal rather than partial. A bound
  charged to the task that caused it is isolation, and it is declared through
  [bounds.md](os-development/bounds.md) like anything else.

### Working rules

As Run 1, unchanged: work in `/Users/danielsamson/Gitea/daniel/danos` on
`claude/bounds-track`; every step lands with a test that fails before the fix, verified
by restoring the old behaviour; full suite green before each commit; never two suites at
once (`pgrep -f qemu_test.py`); 60 GiB free; `git commit -F` with no `Co-Authored-By`;
update this table before starting the next step. **If a step needs a decision that is
not written down, stop it, add the question below, and move on** — Run 1's first step
was wrong and stopping was the right call.

**Suite:** 115/115 at the start of the run.
**Branch:** `claude/bounds-track`.

### What this run deliberately does not touch

Phases 2 and 3 below — the authorisation gate and moving the inventory to the device
manager — are **out of scope for unattended work**. They decide whether the OS is
secure, and they are currently a direction rather than a specification: what a device
capability *is*, which syscalls change, what replaces `device_claim` for its seven
callers, how a driver spawned bare behaves. Those want a design session, the way
`/protocol` had one.

Also out of scope: anything touching `maximum_device_resources` (a wire struct, so a
trust-boundary change, not a resize), and the non-device bounds the audit found in FAT,
the VFS, logger, init, display and boot.

### Open questions this run must not answer on its own

Recorded here rather than guessed. If a step runs into one, it stops and writes the
question down instead of inventing an answer.

1. **`device_enumerate` probably narrows rather than retires.** The device manager
   calls it to find `pci_host_bridge` nodes — it cannot ask itself. The likely shape is
   that the kernel keeps the *firmware-discovered roots* (which by principle 5 it holds
   for real reasons, since they come from ACPI rather than a driver's say-so) and
   everything a driver registered lives in the manager. Not decided.
2. **A device-manager restart has no re-enumerate handshake.** If only the manager
   dies, the buses are alive and never re-send `child_added`, so a restarted manager
   comes back blind. The manager is restartable by design; nothing implements this.
3. **Which adversarial tests I1–I3 need.** The audit's six real defects were all found
   by asking what an attacker would do, and the suite had never asked. "Add adversarial
   cases" is not executable until the attacks are named.
4. **Reclamation is not a death-sweep problem, and L1 as written would have broken the
   restart path.** Found on the first attempt at it. The audit is right that `count`
   never decreases, but *death is the wrong trigger*:
   - The broker keeps entries deliberately: "The devices stay in the table — they
     describe hardware, which did not go away — only their ownership clears." A driver
     dying does not unplug anything.
   - Device ids must stay **stable across a bus restart**, because
     `device-manager.driverForDevice` dedupes by `device_id` so that "a re-report after
     a bus restart must not spawn a second instance". Stability comes from the
     idempotency scan returning the existing id — removing entries on death would give
     a restarted bus fresh ids and spawn duplicate driver instances.
   - Everything else a task holds *is* already reclaimed on every path out:
     `irq.releaseOwner`, `iommu.releaseAllOwnedBy`, `dmaRegistryReleaseOwner`, then the
     broker's claims (`process.releaseTaskResourcesLocked`).

   So the real leak has two sources, and neither is death: a device that genuinely
   **goes away** (hot-unplug) has no retirement path, and a bus that enumerates
   *differently* on restart leaves its stale entries behind forever. Both are the device
   manager's inventory problem — phase 3 — and both need the id-stability question
   answered first (tombstone-and-reuse aliases stale ids held by another process;
   generation-tagged ids change the id encoding, which is ABI). Not an unattended
   decision.
5. **Driver descriptor parsing cannot be host-tested, so L5's correctness fix ships
   without a direct test.** The endpoint-misattribution bug lives in
   `parseConfiguration`, a pure function over a byte blob — exactly the shape a host
   unit test wants, and `usb-storage/scsi.zig` and `usb-hid/hid-report.zig` already do
   this. But `usb-xhci-library.zig` imports `memory`, `mmio` and `time`, so it cannot
   be a standalone host-test root, and QEMU offers no device that would exercise the
   path anyway: the largest available is `usb-audio,multi=on` at 2 interfaces and 211
   bytes, against a cap of 4.

   Three ways out, and picking one is a judgement about house style rather than a
   mechanical step: extract the parser to its own file and wire `usb-abi` into a test
   module (build-support currently resolves module names only for `userBinary`);
   extract it and import `usb-abi` by relative path (against the import-by-name
   convention); or accept QEMU-only coverage and say so.

   Mitigating, and the reason this is recorded rather than blocking: after the fix the
   bug is unreachable **by construction**, not by the added `else`. Interfaces are now
   allocated to exactly the count the descriptor declares, so `interface_count` can
   never reach `interfaces.len` mid-parse. The `else` is belt-and-braces for the
   255-interface clamp. The alternate-setting path that shares it *is* exercised —
   `usb-audio` has alternate settings, and the `usb-large-descriptor` case walks them.

### Working rules for the run

- Work in `/Users/danielsamson/Gitea/daniel/danos` (not a worktree), on
  `claude/bounds-track`.
- **Every step lands with a test that fails before the fix**, verified by temporarily
  restoring the old behaviour and watching exactly the intended assertion flip. A test
  that passes both ways is not a test.
- Full QEMU suite green before each commit. Never run two suites at once — check
  `pgrep -f qemu_test.py` first; a second concurrent run produces false triple faults
  because both share `zig-out`.
- Check at least 60 GiB free before starting a suite.
- Commit with `git commit -F <file>`, never `-m` (a backtick in a message is executed
  by the shell and silently eats a word). No `Co-Authored-By` trailers.
- Update the Live state table **before** starting the next step.
- If a step needs a decision that is not written down here, stop, add it to the open
  questions above, and move to the next step.

---

## The principles this is derived from

1. **danOS is a microkernel.** Minimise what the kernel is responsible for; move
   responsibility to user space so it can be restarted, or fixed live during
   development, without taking the system down.
2. **Implement the specifications correctly**, with the limits those specifications
   define — not limits we decide.
3. **Move as much responsibility as possible to user space** (the device manager).
4. **What remains in the kernel is minimal.**
5. **What remains in the kernel is there for security or for a hardware limitation.**
   Nothing else earns a place.

Principle 5 is the test every bound is put to. For each one: *is this here because of
security, or because of a hardware limitation?* If neither, the storage does not belong
in the kernel and the bound is not a number to be resized — it is a thing to be moved or
deleted.

Applying it to the case that started this:

- `maximum_devices = 64` bounds an inventory of hardware. An inventory is neither a
  security control nor a hardware limitation. **The table is in the wrong place**; the
  number is a symptom.
- `maximum_children_per_parent = 16` exists because `device_claim` is unauthenticated —
  any process can claim any unclaimed device ([devices-broker.zig:164](../system/kernel/devices-broker.zig:164)
  checks only that the device exists and is free). The cap is a crude proxy for an
  authorisation the kernel does not perform. **Fix the authorisation and the cap has
  nothing to defend.**
- `maximum_domains = 64` bounds IOMMU translation domains. Security — stays in the
  kernel. But VT-d and AMD-Vi both *report* how many domains they support in a
  capability register. Principle 2: read it. We chose 64 without asking.

## The security invariants

Every phase must leave all five standing. This is the "without punching a hole" half of
the brief, and each phase below states how it is checked.

- **I1 Containment.** A process may map only physical memory inside a resource it was
  granted. A bus may subdivide only what it already holds.
- **I2 Confinement.** A DMA-capable device is under IOMMU translation before its driver
  can program it, or it is not driven at all.
- **I3 No self-granted authority.** A process holds what it was handed. It cannot name
  its way into holding more.
- **I4 Death releases everything.** Every resource a task held is reclaimed when it
  dies, on every path out.
- **I5 Refusal is attributable.** Every refusal names the rule that refused it.

## Phase 0 — Done

- **Errno attribution.** One errno space in `system/abi.zig`; `device_register`'s six
  refusals and `device_claim`'s three are distinct codes; call sites name the reason;
  `pci-bus` reconciles found against registered. (I5)
- **Idempotency ordering.** A re-registration consumes no slot, so a full parent
  re-admits an identical child. A restarted bus is no longer billed for what it
  rediscovers.

Suite 114/114.

## Phase 1 — Reclamation

**Nothing may become dynamic before this.** Today `count` only ever increases and
`releaseAllOwnedBy` clears a dead driver's *claims* but not its *registrations*. With a
fixed table that is a slow march to the cap; with dynamic storage it is an unbounded
leak, and every supervisor restart makes it worse.

- Extend the existing death sweep so a task's registrations go with its claims.
- A registration whose owner is gone is removed; its children are re-parented or removed
  with it (they cannot outlive the authority that published them).
- Test: register under a claimed parent, kill the owner, assert the entries are gone and
  the ids are not reused while any handle to them lives.

Invariant: **I4**.

## Phase 2 — Close the authorisation hole

The device manager already decides which driver gets which device — it matches against
`devices.csv` and spawns the driver with the device id as `argv[1]`. Nothing binds that
decision to the kernel's `claim`. A driver passes an integer; the kernel checks only
that the device is free.

Per principles 3 and 5: **the decision stays in user space; the kernel enforces only
possession.** The manager hands the driver the device it matched; the kernel's job is
that a driver holds what it was handed and nothing else.

- The manager passes a device to the driver it spawned, over the existing cap-passing
  path. Possession is the authority.
- `device_claim` stops being a way to *acquire* a device by naming it.
- Exclusivity stops being a broker refusing a second claimant and becomes the ordinary
  property of a thing only one process was given.

**`maximum_children_per_parent` is deleted here**, because after this a bus driver's
children are the devices it actually enumerated under a bus it was actually given, and
the rogue-driver-fills-the-table threat the cap was written for no longer exists.

Invariants: **I3** (the point of the phase), **I1** (containment is unchanged and still
checked on every subdivision), **I5**.

Acceptance: a driver that names a device it was not given is refused, with its own
errno. The QEMU suite gains an adversarial case for it — the audit's lesson was that
"the suite contains no attacker".

## Phase 3 — The inventory moves to user space

The kernel reads only three things out of a device descriptor: **physical ranges** (to
check a mapping falls inside one), **interrupt numbers**, and **one PCI BDF** (to key an
IOMMU domain). Vendor and device ids, class triples, subsystem ids, human-readable
names, bus numbers and parent links are stored solely so `device_enumerate` can hand
them back. That is the kernel acting as a distribution mechanism for data it does not
use — principle 5 excludes it.

- **Zero-resource devices leave the kernel entirely.** A USB device addressed through
  its controller conveys no mapping authority; there is nothing for the kernel to
  enforce. It is pure inventory and belongs to the device manager. (This is also the
  case that sidesteps containment, which is why the cap existed.)
- Identity and topology move to the manager, which already receives them as
  `child_added` reports and already holds the authoritative picture.
- `device_enumerate` retires; callers ask the manager, whose protocol already reserves
  an `enumerate` verb. Public-ABI change — `docs/os-development/vdso.md` documents it.
- What the kernel keeps: for each device that carries resources, the ranges, the GSIs,
  the BDF, and the owner.

After this, the kernel's table holds only resource-bearing devices, and the remaining
count is bounded by what the machine physically has rather than by us.

Invariants: **I1**, **I2** unchanged — both operate on resources, which do not move.
**I4** must be re-checked: the manager's table now needs its own reclamation, and it is
restartable, so it must be able to rebuild from the buses.

## Phase 4 — Ask the hardware and the specification

Principle 2, applied to every remaining bound. Each of these is a number the machine or
the standard already states, which we replaced with a guess. Independent of each other;
can proceed in any order.

| Today | Ask instead |
|---|---|
| `maximum_domains = 64` (IOMMU) | the VT-d / AMD-Vi capability register reports the domains supported |
| `max_devices = 8` (xHCI slots) | `HCSPARAMS1.MaxSlots` — the controller says (1–255) |
| `max_interfaces = 4`, `max_endpoints` | the configuration descriptor says |
| `blob: [512]u8` (USB config) | the device's `wTotalLength` |
| `below: [64]Range` (memory map) | UEFI reports the descriptor count |
| AML blobs capped at 6 | the XSDT's length field gives the entry count |
| `maximum_cpus = 128` | the MADT entry count |
| `maximum_gsi = 24` | the I/O APIC's redirection-entry count; and more than one I/O APIC exists |
| MSI-X vectors | the capability's table-size field (up to 2048) |

Several of these are in user space already (xHCI, USB descriptors) and are ordinary
allocations — principle 1 means those are also the safest to do first, since a mistake
restarts a driver rather than the machine.

Two in this table are **also** correctness fixes the audit found, and should carry their
regression tests: the xHCI `max_interfaces` path misattributes a fifth interface's
endpoints to interface 3, and `below: [64]Range` silently turns occupied RAM into a PCI
aperture — which is an **I1 violation reachable on real hardware**, not merely a lost
device. That one is the highest-priority item in this phase.

## Phase 5 — What legitimately remains

After phases 1–4 the survivors should be only:

- **Pre-allocator storage**: the PMM's own frame bitmap, the memory map the loader hands
  over, the bootstrap page tables. You cannot allocate the allocator. (Hardware/boot
  limitation — principle 5 admits these.)
- **Interrupt-context storage**: the IST stack and anything an exception path touches
  without allocating.
- **Wire structures** whose layout the other side of a trust boundary parses.
- **Facts that are not ceilings**: a page is 4096 bytes; an ACPI name segment is 4.

Each is declared per [bounds.md](os-development/bounds.md) — what it counts, who decides
its size, what it protects, what happens at the limit, how you find out. And two numbers
that must agree agree in code, not in a comment:

```zig
comptime {
    if (maximum_domains != devices_broker.maximum_devices)
        @compileError("iommu.confined is indexed by device id; an id past its end is " ++
            "left unconfined while confineDevice still reports success");
}
```

## The one that must not wait

[`iommu.zig:107`](../system/kernel/iommu.zig:107) — `if (device_id >= confined.len) return
true;` — returns *success* without confining. It is unreachable today only because
device ids stop at 64. **Phases 3 and 4 both change the device count, and either makes
it live.** Fix it before them: out of range must refuse, never allow. (I2)

This is also the standing rule the audit argues for: at a bound, the safe direction is
refusal. A ceiling that fails open is not a limit, it is a switch that turns the
protection off.

## How this is verified

- The QEMU suite is the arbiter at every step; it is 114 cases and must stay green.
- Each fix lands with a test that **fails before it** — as the idempotency reorder did,
  where exactly one assertion flipped.
- Adversarial cases for I1–I3 specifically: the audit's six real defects were all found
  by asking "what would an attacker do", and the suite had never asked.
- The Ryzen is the acceptance test. It is the machine that found this, and the one that
  proves it fixed.

## Sequencing

Phase 1 gates everything. Phase 2 gates phase 3 — the inventory cannot move until
authority is sound, or moving it is the hole. Phase 4 is independent and its user-space
items are the safest work in the track. Phase 5 is the record of what survived.

The IOMMU fail-open is fixed before phase 3 or 4 touches the device count.