# Examples — using the `mgf-hrb` SDK

> **Audience.** Engineers writing a consumer (a VM manager, a recovery
> tool, a desktop monitor, a CLI). Each example is short, runnable, and
> grounded in a specific [recipe](../recipes/) that explains *why* the
> pattern is shaped the way it is.
>
> **The bigger picture.** Examples here demonstrate one pattern each.
> [`recipes/`](../recipes/) ships the canonical consumer patterns with
> the full narrative (when to reach for them, failure modes, what the
> broker promises). When the example is too thin to act on alone, the
> example links into a recipe.

---

## Running these

Each example is a standalone Python script. With the package installed
into a venv:

```bash
uv pip install -e '.[dev]'
python examples/01_list_devices.py
```

Or without an install, from the repo root:

```bash
PYTHONPATH=src python examples/01_list_devices.py
```

Examples 01 and 02 expect a running broker on `/tmp/mgf-hrb.sock` (the
skeleton's path). Start one with:

```bash
cd hrb-code && zig build && ./zig-out/bin/mgf-hrb-server &
```

Example 03 is pure SDK — no broker required.

---

## What's here

| # | Example | What it shows | Recipe |
|---|---|---|---|
| 01 | [`01_list_devices.py`](01_list_devices.py) | The Observer surface: connect, list, print. The smallest useful program. | — |
| 02 | [`02_claim_and_use.py`](02_claim_and_use.py) | Claimant + RawAccessor: claim a device under a context-managed `Lease`, get the raw channel, release. Crash-safe by construction (lease bound to liveness — G3). | [`claim-a-device-for-vfio-passthrough.md`](../recipes/claim-a-device-for-vfio-passthrough.md) |
| 03 | [`03_track_identity.py`](03_track_identity.py) | Identity-continuity comparator: capture a `Snapshot`, score against a candidate, get a `Confidence` tier. Pure SDK — no broker needed. | [`track-a-device-across-a-mode-change.md`](../recipes/track-a-device-across-a-mode-change.md) |

---

## What's NOT here yet

The three-layer event API (`monitor()` / `monitor_fd()` / `amonitor()`)
designed in [FEEDBACK `SDK-01`](../FEEDBACK.md) is reserved in the public
API but not yet wired — the broker's event-subscription protocol is a
Tier-1 hardening pass. When it lands, an `04_event_monitor.py` shows the
sync iterator + an `05_qt_monitor.py` shows the `QSocketNotifier` shape
the recipe documents.

---

## Conventions

- Every example starts with `from mgf.hrb import …` — the *public* surface
  only (anything else is private, per AP-14).
- Each example handles `MgfHrbError` (or a typed subclass) explicitly —
  the federation's EH-02 translation-at-the-seam pattern made concrete.
- Every example carries a one-line "what this demonstrates" docstring so
  an AI agent or human reader sees the intent immediately.
