# DEPS — mgf-hrb's bidirectional dependency manifest

> **§1** — what mgf-hrb depends on. **§2** — who depends on mgf-hrb.
> Knowing both directions makes deprecation, breaking-change
> blast-radius, and feature-prioritisation tractable.
>
> **Maintained by:** the mgf-common owner (Bassam — mgf-common owns the
> federation per the one-big-library mindset).
> **Per standard DOC-16** (v2.12): every project ships a `DEPS.md`.
> Replaces the former `USERS.md` (its roster is now §2 below).

Last verified: 2026-05-28.

---

## §1 What mgf-hrb depends on

`mgf-hrb` is a **dual-language** repo: a Python SDK (`src/mgf/hrb/`)
plus the Zig **broker** that ships alongside it in `hrb-code/`. The Zig
broker is an in-repo **build component**, not a packaged dependency — it
is built from this same tree (`cd hrb-code && zig build`) so the two
sides of the no-FFI Unix-socket protocol never skew. The Python
dependency window is below.

| Dependency | Window | Why | Tier |
|---|---|---|---|
| `mgf-common` | `>=0.40.0,<0.41` | cornerstone — typed exceptions / `BaseAppSettings` / standards + `mgf-common standards <topic>` CLI | runtime |
| `pytest` (+ `pytest-cov`, `pytest-timeout`, `pytest-xdist`) | `>=8.0` / `>=5.0` / `>=2.3` / `>=3.5` | test harness — per-test deadline + per-worker broker sockets | `[dev]` extra |
| `hypothesis` | `>=6.100` | property tests (TS-13) — fmt invariants | `[dev]` extra |
| `ruff` / `mypy` | `>=0.4` / `>=1.10` | lint + strict type gates | `[dev]` extra |
| `import-linter` | `>=2.0,<3.0` | PR-01 / PR-06 layering contracts (SDK forbids UI frameworks) | `[dev]` extra |
| `ziglang` | `>=0.16` | broker build + test toolchain, vendored via PyPI | `[dev]` extra |
| `mgf-test-supervisor` | `@ git+ssh …@v0.1.1` | federation test supervisor (replaces in-tree `scripts/_mtest/`) | `[dev]` extra |

*Federation siblings depended on: `mgf-common` — the cornerstone; the
only `mgf-*` sibling mgf-hrb imports at runtime (typed exceptions +
config). `mgf-test-supervisor` is a `[dev]`-only sibling (git source
until its PyPI publish lands; flip to a PyPI pin at the next federation
sync).*

**Build component (not a packaged dep):** the Zig broker in
`hrb-code/` — kernel side; 308 Zig tests; carved Zig deps cached via
`scripts/zig-fetch-deps`.

Runtime core is kept deliberately tight — the only runtime dependency
is `mgf-common`. Everything else lives behind the `[dev]` extra.

---

## §2 Who depends on mgf-hrb

Consumer projects + federation siblings that import `mgf.hrb.*`.
(Inverse of each consumer's `MGF_ADOPTION.md`.)

### Consumer projects (external users)

| Project | Location | Import sites | Status | Surfaces used |
|---|---|---:|---|---|
| **hrb-app** | `/home/bassam/PycharmProjects/hrb-app` | 55 | Active — GUI front-end, pre-`0.1.0`; runs against a real broker | `Client` / `ClaimMode` / `ControlVerb` / `Lease` / `LeaseRecord` / domain types / `diagnostics` (Doctor) / `fmt` / `MgfHrbError` hierarchy |
| **vm-vmanager-app** | external (host-side VM manager) | — | Designed-for — not yet integrated | Claimant + RawAccessor + `mgf.hrb.libvirt` extra (drives `recipes/claim-a-device-for-vfio-passthrough.md`) |
| **figrecovery** | external (iFig restore tool) | — | Designed-for — not yet integrated | Observer + Claimant + RawAccessor + `snapshot` / `same_likely` identity comparator (drives `recipes/track-a-device-across-a-mode-change.md`) |

**Reference tools (this repo / future `mgf-hrb-tools`).** Planned
Phase-4 in-repo consumers, each proving one end-to-end slice: a **PCIe
GUI mapper** (Observer + `monitor_fd` — event stream + ring +
reconnection), a **USB recovery tool** (RawAccessor — full ownership +
safe-reset-on-crash), and a **bus-layout reporter** (Observer only —
discovery + fidelity). The embedded **`mgf-hrb` CLI**
(`src/mgf/hrb/cli/`) is the first in-repo consumer of `mgf.hrb` today
(`Client` / `ClaimMode` / `MgfHrbError` / identity comparator);
`cli/_doctor.py` carries the operator-diagnostic shape (FEEDBACK
`TOOLS-01`; substrate-report rows pending the USB worker).

### Federation siblings (`mgf-*` libraries)

No `mgf-*` sibling imports `mgf.hrb` today. mgf-hrb sits above the
cornerstone and is consumed by applications, not by other siblings.

**On a §2 change.** When vm-vmanager-app / figrecovery finish their
integration (today "designed-for", not yet importing `mgf.hrb`), flip
their rows from designed-for to a verified import-site count in the same
PR that bumps their pyproject pins; the migration also feeds back into
each consumer's `MGF_ADOPTION.md`.

### Surfaces NOT yet user-facing (recorded so growth is intentional)

Intentionally not exposed yet — listed so integrators know what to
expect: `mgf-hrb-policy` (the declarative meaning layer; designed),
`mgf-hrb-sdk-zig` (native Zig client; contracts fixed, deferred until a
Zig consumer materialises), `mgf-hrb-cpu` / `mgf-hrb-gpu` (Family-B /
future-bus workers; report-only first), and `mgf-hrb-youros` (the
future-OS backend satisfying the same kabi conformance suite as
`mgf-hrb-linux`).

---

## §3 Maintenance

Updated every MINOR release + when a dependency or consumer changes.
Import-survey methodology for `mgf.hrb`:

```sh
for proj in hrb-app vm-vmanager-app figrecovery; do
  grep -rE "(from|import) +mgf\.hrb" "/home/bassam/PycharmProjects/$proj" \
    --include='*.py' | wc -l
done
```

When the SDK is published, this file flips the two external designed-for
rows (vm-vmanager-app + figrecovery) from "designed-for" to "imports `mgf.hrb`"
with verified import-site counts before each MINOR release.
