danos/docs/establishment-planes-plan.md

# Establishment planes: the plan

*2026-08-09. The design is settled in
[communication.md](os-development/communication.md) ("Establishment: two planes, one
namespace"): driver-layer channels stop being registry names and are routed at
establishment by the device manager, which owns the topology. This converts both live
seams — `usb-transfer` and `block` — in one flag-day, and fixes the restart hole the
scoping audit found on the way. Found by a real machine: three xHCI controllers, one
name, a mouse nobody could reach.*

**Non-goals, stated up front.** fat stays single-volume (multi-volume mounting, volume
identity/content-probing, and fat's own reconnection after a storage restart are the
M21 remount track). The input service's last-writer-wins button mask across two mice
is a known quirk, not part of this change. Nothing here touches the app-facing names —
`input`, `display`, `ufs` keep their exclusive registry binds.

## What the scoping reads established

- **Capabilities already travel both directions of a synchronous call, and only
  there.** Request-direction via `ipc.callCap` (r9 → `shareCapability` at server
  dequeue, a refcounted copy); reply-direction via `ipc_reply_wait`'s `send_cap`
  (surfaces as the client's `Reply.cap`) — init's registry is the working in-tree
  precedent (`pending_capability`). Pushes structurally cannot carry one. **No kernel
  change is needed.**
- **The one mechanism gap is the service harness**: `service.run` hardcodes the reply
  capability to null and `Answer` has no capability slot; the device manager runs on
  that harness. It needs a reply-cap out-slot following init's pattern, with null
  staying the untouched default for every other service.
- **The manager already stores the routing fact**: `Child{parent, bus_address,
  device_id, reporter}` — consumer's device id → `children[].reporter` →
  `driverByProcess(reporter)` → the (new) stored endpoint. `Hello.role` (.bus vs
  .device) already exists on the wire to distinguish provider hellos (cap up) from
  consumer hellos (cap down); the manager currently never reads it.
- **The restart hole (new finding):** today, when a bus instance dies, its class
  drivers are zombies — HID drivers block forever on interrupt reports that will
  never come, usb-storage answers fat with errors forever; the manager respawns
  neither, and the matcher's dedupe actively prevents a respawn on re-report. The
  user's core goal is restart-a-driver-live; this plan closes the hole.
- **Blast radius:** every QEMU case boots from USB storage, so this seam failing
  fails the whole suite, and the load-bearing serial markers (`fat: mounted
  /volumes/usb`, `usb-storage: ready`, `fat-test: ok`) must not change.

## P0 — mechanics (library + manager, no behavior change yet)

1. **Harness reply-capability out-slot.** A handler nominates a capability for its
   reply (init's `pending_capability` idiom moved into `service.run`'s loop); default
   null; the existing Arrival take/release ownership discipline is unchanged. Every
   other service compiles and behaves identically.
2. **`driver.hello` grows both directions.** Provider form: carry the caller's
   serving endpoint up (`ipc.callCap`). Consumer form: return `Reply.cap`. One call
   can do both (a storage driver hands its block endpoint up and receives its bus
   channel down in the same hello).
3. **Manager stores and routes.** `Driver` gains an endpoint field; the cap is
   claimed at `onMessage` level (the `capability_claimed` pattern usb-xhci-bus
   already uses — the harness's private claim flag composes, verified). `onDriverExit`
   **must** `ipc.close` the stored handle (a dead owner's endpoint survives as a
   refcounted slot; repeated restarts would exhaust the manager's 32-slot table —
   boot-fatal). Consumer hello with an unknown device id (bus died, not yet
   re-reported) gets a *retryable* refusal, never a permanent one.

## P1 — the usb-transfer seam

- Bus: delete the `bindPatiently("usb-transfer")` block and its serve-unnamed
  fallback; hello carries the endpoint up.
- `usb.open(device_id)` takes the channel from the class driver's hello instead of
  the name lookup; retry patience stays ≥ today's window (the provider's hello
  precedes the consumer's spawn in the normal order — the retry covers respawn races).
- usb-storage's *consumer* side uses the same lineage (its own device id).
- `protocol.csv`: delete the bind row (67) and the three open rows (119/120/122) in
  the same commit as the code — grants and code move together or the old path dies
  silently first.
- Fixtures: conformance table row, the usb-report kernel-side registry spawn.

## P2 — the block seam

- usb-storage: drop `.service = "block"` (the field is optional; the harness serves
  nameless — pci-bus and logger already do); its `initialise` keeps the endpoint it
  currently discards and hellos it up. Exit-code contract preserved: device absent =
  clean exit (no restart), device-present failure = exit(1) (restart with backoff) —
  establishment failure is the latter, never a silent pre-hello death like today's
  second-stick `-EBUSY`.
- fat: `block.tryOpen`'s name lookup becomes manager-routed — enumerate, find the
  block-class provider, hello for its channel. One volume: unambiguous. Two volumes:
  fat takes the first by device-id order — deterministic within a boot, and no worse
  than today's bind race; choosing *the boot volume* by content is deferred to M21
  (risk noted: `/system/configuration` and `/system/logs` mounts ride this choice).
- fat gets a `protocol.csv` open grant for `device-manager`; rows 68/99 die.
- Delete `block.open` (zero callers, dead code).

## P3 — restart integrity (the zombie fix)

- **A reporter's death reaps its subtree.** When a bus/storage instance dies, the
  manager already prunes its children; now it also kills the class drivers spawned
  for those children and clears their entries, so the matcher's dedupe stops blocking
  the respawn. On re-report (ids are stable — the `P<port>I<iface>` registration
  identity), the matcher spawns fresh class drivers, which hello and receive the
  successor's channel. Restart a bus driver live: the subtree rebuilds itself.
- usb-storage on `-EPEER` from its bus: exit(1) → supervisor restart with backoff →
  fresh hello. (fat's own reconnection: M21.)
- Extend the existing bus-restart drill (`test-usb-restart`, the usb-report case) to
  assert the subtree *works* after the restart — a post-restart keyboard event, not
  just a re-report. **Discrimination: today that assertion fails (zombie).**

## P4 — the multi-instance proof

- New QEMU case: **two xHCI controllers**, keyboard on one, storage on the other;
  assert both class drivers come up and function. **Discrimination: without the
  conversion this case fails exactly like the Ryzen mouse** (second controller's
  child unreachable). This is the machine's bug, pinned in the suite forever.
- Full suite green; the four existing second-controller cases (usb-hub and friends)
  re-checked against their expectations.
- Docs updated with the code: device-manager.md, drivers.md (hello), the usb-transfer
  and block protocol docblocks, device-authority.md as-built appendix.

## Order and verification discipline

P0 → P1 → P2 → P3 → P4, one commit per coherent step, suite green at every phase
boundary (P0 and P1 may share a verification run — P0 alone changes no behavior).
Every new test must be shown to fail against the old behavior before it counts
(the discrimination rule). One QEMU suite at a time. The Ryzen re-test at the end is
the acceptance run: mouse moves, and killing one bus instance from a shell one day
only blinks the devices on that controller.