# Project Index — `mgf-hrb`

A userspace **hardware resource broker** that arbitrates read/write access
to all hardware (PCIe, USB, GPU, CPU/memory) for any client — reliable,
fast, complete, impossible to need to bypass — designed kernel-agnostic
so it lifts onto a from-scratch capability-based OS by writing one backend.

**Priority order:** Reliability · Performance · Fidelity · Flexibility · Simplicity.
**Languages:** Zig below the socket (enforcement, hardware, hot path) ·
Python above it (ergonomics, policy, tooling).

```
mgf-hrb-project/
├── README.md             federation-standard project landing page (DOC-01)
├── STARTHERE.md          procedural how-to (DOC-01 sibling shape)
├── INDEX.md              this file — the deep architectural entry point
├── LICENSE               MIT
├── CHANGELOG.md          Keep-a-Changelog (DOC-04)
├── SECURITY.md           vuln-report channel; points to Part 12 for the threat model (DOC-01 / SC-12)
├── USERS.md              the user roll — who depends on mgf-hrb (DOC-16)
├── AGENTS.md             AI-agent entry point (run `mgf-common agents`)
├── PUBLIC_API.{md,json}  the public Python surface (DOC-08 / AP-10)
├── pyproject.toml        Python library packaging (hatchling, src/ layout)
├── src/mgf/hrb/          the Python SDK + embedded CLI (federation sibling shape)
│   ├── __init__.py       public surface re-exports
│   ├── _client.py        Client + Lease (line-JSON over Unix socket)
│   ├── domain.py         frozen dataclasses (ClaimMode, Resource, …)
│   ├── identity.py       Snapshot + same_likely (Python mirror of identity.zig)
│   ├── exceptions.py     typed hierarchy extending AppError (EH-01/-02)
│   └── cli/              the `mgf-hrb` console script: scan / info / doctor / explain
├── tests/
│   ├── unit/mgf/hrb/     pytest tree mirroring src/ (TS-01)
│   └── e2e/test_e2e.py   Python ↔ Zig over a real Unix socket
├── examples/             runnable consumer snippets
├── docs/
│   ├── claude/CLAUDE.md  project-specific Claude reference (DOC-07)
│   ├── inprogress/
│   │   └── MGF_STANDARDS_CONFORMANCE.md   conformance tracker (L2 — Standard; DOC-15)
│   ├── standards/README.md   pointer-only → mgf-common (DOC-02 §2.0.4)
│   └── cutover/          (empty until first breaking change)
├── hrb-design/           the design — 5 docs, the spine + 3 deepenings + the survivability review
├── hrb-code/             the Zig broker (kernel side); `src/`, `build.zig`
├── DECISIONS.md          the ADR catalog (load-bearing decisions, extracted from the design)
├── FEEDBACK.md           the design-conversation log (mgf-family pattern)
├── STANDARDS_NOTE.md     the *argument* behind the conformance tracker's posture
└── recipes/              consumer-pattern recipes (claim for VFIO, USB monitor, mode-change tracking)
```

---

## hrb-design/ — the design

| File | What it is | When to read |
|---|---|---|
| [`mgf-hrb-complete-design.md`](hrb-design/mgf-hrb-complete-design.md) | The full design. Priorities, SOLID-where-valuable, the fidelity guarantee (G1–G4), the survivability guarantees (S1–S5) and threat model, the lease engine, capabilities, transport, the kernel seam, the process model, the client surface, assembly. **Start here.** | Always |
| [`kernel-design-brief.md`](hrb-design/kernel-design-brief.md) | Extracted for your from-scratch OS: **10 kernel features** (8 from abstracting Linux + 2 from the survivability review: native deadlines, native handle revocation). The thesis: design the kernel capability-first. | When you turn to the kernel work |
| [`mgf-hrb-survivability-review.md`](hrb-design/mgf-hrb-survivability-review.md) | **The adversarial-resistance review (Part 12), standalone.** Six stages: threat model, the downward (hardware) boundary, the upward (client) boundary, broker self-integrity, concurrency/fairness, and synthesis. ~30 findings converging onto four primitives (deadlines, quarantine, revocation-below-the-fd, the trust gate). The hardening roadmap. | Before hardening; or when reviewing reliability under attack |
| [`mgf-hrb-family-b-deepening.md`](hrb-design/mgf-hrb-family-b-deepening.md) | Part 10 — the apportionable-resource model (CPU/memory); decision: report-only first, reservation-complete by design. | Before any CPU/memory work |
| [`mgf-hrb-privileged-core-hardening.md`](hrb-design/mgf-hrb-privileged-core-hardening.md) | Part 11 — decision: separate privileged helper process per worker. | Before implementing the helper |
| [`mgf-hrb-usb-worker.md`](hrb-design/mgf-hrb-usb-worker.md) | The first concrete bus worker: URN translation, the substrate matrix (sysfs/usbfs/netlink), composite-device handling per-interface, identity continuity across re-enumeration, the seam-ops mapped to USB, deadlines/quarantine specialised for USB. Encodes lessons from the working `mgf-usb` Python library. | Before implementing `mgf-hrb-usb` |

Reading order for a first-time visitor: `complete-design.md` → pick the deepening matching the area you'll touch.

---

## hrb-code/ — the live implementation

Working, tested Zig + Python. Built in 7 phases; every load-bearing claim of the
design is a passing test against real conditions.

**308 Zig tests (broker) + ~44 more in the carved leaf repos + 466 Python tests (default suite), all green; marker-gated stress/perf/e2e add ~94 more.**

```
scripts/zig-fetch-deps                    # cache the carved Zig deps (one-time)
cd hrb-code
zig build test --summary all              # 308 Zig tests (S1 fuzz + S2 deadlines + Part 13 + Tier-0)
cd .. && pytest                            # 466 Python tests
scripts/mtest --tier 0-3                   # budget-aware supervisor (4-tier model)
```
(Built with Zig 0.16. No `zig`? `pip install ziglang`, alias `zig` to `python3 -m ziglang`.)

**E2 status.** The reuse-proven leaves are now their **own Codeberg
repos** (consumed by the broker as Zig package deps, pinned by hash in
`hrb-code/build.zig.zon`); broker-internal modules stay in `hrb-code/src/`.

| Sibling | Where | Proven |
|---|---|---|
| `mgf-hrb-model` | **carved repo** | the vocabulary (two families, fidelity tags, errors) |
| `mgf-hrb-kabi` | **carved repo** (`kabi`+`conformance`+`fake_backend`) | the 9-op substitutable seam — your kernel's spec + acceptance test |
| `mgf-hrb-core` | `src/core.zig`, `src/core_test.zig` (in broker) | lease engine; atomic grant; **G3 ghost-free reclamation** |
| `mgf-hrb-cap` | **carved repo** (`cap_test` stays in broker) | **monotone attenuation**; `raw` as its own right |
| `mgf-hrb-rt` | **carved repo** (ring/fdpass/liveness; `liveness_test` stays in broker) | lock-free SPSC **822M/sec**; SCM_RIGHTS fd-pass (G4); real-socket death → reclamation |
| `mgf-hrb-linux` | `src/linux_backend.zig`, `src/linux_test.zig` (in broker) | **real PCI hardware** enumeration; honest-Unsupported acquire |
| `mgf-hrb-facade` | `src/facade.zig`, `src/facade_test.zig` (in broker) | **the live constellation** (2 workers + caps + liveness) |
| broker server | `src/server.zig` (in broker) | the running broker behind the E2E test |
| broker trust gate | `src/request.zig`, `src/request_test.zig` (in broker) | **S1 hardened decode** (Part 12 §3.2): bytes → typed `Request`; fuzz-verified |
| `mgf-common-identity` | **carved repo** (federation-level; module `mgf_hrb_identity`) | **MODEL-01**: `Snapshot` + `sameLikely()`; iFig DFU validated |
| `mgf-hrb-sdk-py` | **published from this monorepo** (`scripts/publish-wheel`; lockstep) | **zero-FFI Python↔Zig** over a socket; federation-sibling library layout |

### What's proven vs. what remains

Proven against real conditions: substitutable seam (real PCI hardware), ghost-free
ownership (real socket death), authority-only-shrinks (refused widenings), blazing
data plane (822M/sec across real threads), the constellation composes end-to-end,
zero-FFI language boundary (two real processes), use survives the broker (fd works
after sender closes its copy).

Remaining (hardware-gated or integration, not unproven design):

- real VFIO `acquire` — needs a host with `/dev/vfio` + IOMMU. The VFIO branch of `revoke` plugs into the same wire surface USB uses today.
- **`mgf-hrb-usb` worker Phase U4 follow-ons** — reset-escalation ladder partially done; interrupt-rate watchdog + Quarantined-state transitions vs. stub-firmware fake still open.
- **Privileged-helper subprocess** — `UsbBackendViaIpc` ships and is opt-in via `MGF_HRB_USB_USE_HELPER=1`; default mode is still in-process. Promoting to default needs a soak under real USB load.
- **Tier-0 #5** — asymmetric shared-memory trust + per-tenant private regions (§3.5). The only remaining Tier-0 item; #1–#4 all shipped.
- `mgf-hrb-cpu` / `gpu` / `sdk-zig` — designed, contracts fixed, deferred
- `mgf-hrb-youros` — your future kernel's backend; passes the same conformance suite

---

## Cross-references

- [`DECISIONS.md`](DECISIONS.md) — the load-bearing decisions, each with rationale, status, and source citation back into `hrb-design/`.
- [`FEEDBACK.md`](FEEDBACK.md) — the design-conversation log; the place to file friction so the design itself can improve.
- [`STANDARDS_NOTE.md`](STANDARDS_NOTE.md) — the argument behind the federation-conformance posture (why most Python rules don't apply line-for-line to a dual-language project).
- [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md) — the per-rule ledger (L2 — Standard, declared honestly; flipped 2026-05-24).
- [`USERS.md`](USERS.md) — the user roll: vm-vmanager-app, figrecovery, planned reference tools.
- [`SECURITY.md`](SECURITY.md) — vuln-report channel; points to the survivability review (Part 12) for the threat model.
- [`recipes/`](recipes/) — consumer-pattern recipes (canonical claim-for-VFIO; USB event monitoring; tracking a device across a re-enumeration).
- The **conformance suite** in `hrb-code/src/conformance.zig` is the acceptance test for any backend — including a future `mgf-hrb-youros`.

---

## The design in one breath

A capability-secured hardware **broker**, not a passive layer: it tracks **ownership as continuously-renewed leases** so ghosts are impossible (reliability); it **mediates the claim and delegates the usage** via passed fds so owned access is as fast as raw (performance); it represents hardware **completely and honestly** with per-field fidelity and a raw escape hatch so nobody needs to bypass it (fidelity); it is built from **siblings behind a narrow kernel seam** with a verified behavioral contract so it lifts onto a new kernel by writing one backend (flexibility); and it keeps the **dangerous code tiny and the exposed code powerless** (security throughout). Zig owns everything below the socket where reliability and speed are non-negotiable; Python owns everything above where ergonomics and policy change often. The socket is the one boundary where language, privilege, meaning, and temperature all change at once — and that coincidence is the sign the boundary is right.

And, as a byproduct: a **specification and conformance test for the device subsystem of the capability-based kernel you're about to build.**
