# Recipes — `mgf-hrb` consumer patterns

> **What this is.** A small set of *canonical patterns* a consumer can
> copy when integrating against `mgf-hrb` — the recurring
> claim-then-pass / monitor-with-identity / track-across-mode-change
> shapes that three independent consumers would otherwise each get
> subtly wrong.
>
> **What this is not.** Reference for the API surface (that's in
> [`hrb-design/mgf-hrb-complete-design.md`](../hrb-design/mgf-hrb-complete-design.md)
> §8). Not policy advice — recipes show *mechanism*; consumers own
> *policy* (the same mechanism/meaning split the design draws between
> Zig core and Python policy, drawn again between this layer and the
> consumer).
>
> **Why a recipe rather than a library helper.** A recipe is the right
> surface for patterns that depend on *consumer-side* policy choices
> the library cannot make. The vendor-mode-classification example from
> `mgf-usb` is the precedent: the library cannot enumerate every
> vendor's sub-modes (there are thousands), so it ships the *shape*
> and lets the consumer fill in the values.

---

## Index

| Recipe | When you reach for it |
|---|---|
| [`claim-a-device-for-vfio-passthrough.md`](claim-a-device-for-vfio-passthrough.md) | Hand a PCI function or USB interface to a libvirt VM through the broker, get it back when the VM is done. The vm-vmanager-app pattern. |
| [`usb-event-monitor-with-role-interfaces.md`](usb-event-monitor-with-role-interfaces.md) | Subscribe to `hw:/usb/**` events and drive a UI (or a script) — picking the loop shape (fd / sync / async) that matches your consumer. |
| [`track-a-device-across-a-mode-change.md`](track-a-device-across-a-mode-change.md) | A USB device re-enumerates mid-flow (the iFig DFU case): its PID flips, its serial vanishes, the kernel devnum rotates. How to know it's still the same physical unit. |

---

## Conventions

- Each recipe is a single file, named with kebab-case, with prose +
  one or more concrete code snippets.
- Snippets use the `mgf.hrb` Python SDK (`src/mgf/hrb/`,
  `__version__ = "0.1.0"`) above the socket. Zig snippets appear
  where the recipe targets a Zig-side consumer (e.g., a custom worker).
- Each recipe ends with a **"Testing this pattern"** section. Where
  the surface is shipped (the identity comparator), the tests are
  runnable today. Where the surface is Tier-1 — the broker-side
  subscribe protocol and the `mgf.hrb.testing` fakes module
  (`FakeBackend` / `ScriptedBus` / `install_fake`) designed in
  Part 8.6.1 — the recipes show the intended shape with a clear
  "future / not-yet-shipped" caveat so consumers can architect
  against it. See [`examples/`](../examples/) for the today-API
  runnable counterparts.
- Cross-references back into the design docs cite by Part number
  (`[Part 3.2]`, etc.) so the recipe stays compact and the design
  stays authoritative.

---

## Pairing with `FEEDBACK.md`

If you write a consumer and find yourself reinventing a pattern that
*isn't* covered here, file a `DOC-NN` paper in
[`FEEDBACK.md`](../FEEDBACK.md) — the missing recipe is the surface
the library should grow next.
