# STANDARDS_NOTE — `mgf-common` federation standards and `mgf-hrb`

> **Status.** *Light-touch inheritance, formal audit at L1 — Lite.*
> `mgf-hrb` is now a registered federation sibling (`mgf-common>=0.38,<0.39`
> in [`pyproject.toml`](pyproject.toml)) with a per-rule conformance
> tracker at [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md).
> This file records the *deeper rationale* behind that tracker's posture
> — why most rule-rows are honestly N/A (Python rule × Zig code) or ⏳
> (Python SDK pre-maturity), and what we'd map to *when* the Python
> siblings mature.
>
> **Why this file still exists alongside the conformance tracker.** The
> tracker is the *ledger* (per-rule ✅ / 🚫 / ⏳ / N/A). This file is the
> *argument* — the design-level case for why the federation standards
> apply unevenly to a dual-language project, and what that means for
> integrators who expect a uniform mgf-* surface.
>
> **The companion working library.** `mgf-usb` at the repo root inherits
> `mgf-common` wholesale (DP-* / EH-* / LG-* / CF-* / SC-* / TS-* / AP-*).
> When `mgf-hrb`'s Python siblings (the SDK, policy, tools) grow to a
> shippable surface, every consumer of those siblings will have the
> same conformance expectations a sibling `mgf-*` library currently
> implies. Mapping early *without overclaiming* lets us land conformance
> additively (L1 → L2) rather than retrofitting.

---

## §1. The shape of the question

`mgf-hrb` is a **dual-language** project:

- **Below the socket — Zig** (`mgf-hrb-model`, `mgf-hrb-core`,
  `mgf-hrb-cap`, `mgf-hrb-rt`, `mgf-hrb-kabi`, `mgf-hrb-linux`, the
  workers, the facade, the privileged helper). The `mgf-common`
  standards are Python-flavoured and **do not apply** here. The design
  doc's priority order, SOLID-where-it-earns-its-place, and the
  fidelity guarantees are the conformance contract for the Zig side.
- **Above the socket — Python** (`mgf-hrb-sdk-py`, `mgf-hrb-policy`,
  `mgf-hrb-tools`). These are where `mgf-common`'s rules naturally
  apply — they're Python libraries in the same federation
  (`mgf.hrb.*`) as `mgf.usb`, `mgf.common`, etc.

So this note covers only the Python siblings. The Zig siblings have
their own conformance — the **kabi conformance suite** (Part 6.4) and
the **survivability conformance suite** (Part 12 §6.3 / S1–S5).

---

## §2. What we expect to inherit when the Python SDK matures

The mapping below names which rule families would apply, where each
sibling would slot in, and what *won't* apply (and why). Each row
links to the canonical mgf-common doc.

| Rule family | Where it applies in `mgf-hrb` | Notes |
|---|---|---|
| **DP-* (design principles)** | All three Python siblings | DP-01 (layering), DP-02 (third-party IO behind an ABC) — natural fit; `mgf-hrb-sdk-py` already speaks the broker via a transport interface. DP-12 (UTC everywhere) — Snapshot's `captured_at` is monotonic, but human-facing fields render UTC. |
| **EH-* (error handling)** | SDK + tools | `MgfHrbError` extends `mgf.common.exceptions.AppError` (EH-01). Translation at the SDK transport seam — every Zig-side `Err` becomes a typed Python exception (EH-02 / EH-03). The structured `Fix` enum (design §6.3) renders via `mgf-hrb-tools doctor`. |
| **LG-* (logging)** | SDK + tools + policy | Module-loggers (LG-01), `extra={}` structured fields (LG-09), redaction of capability tokens by default (LG-04). The hot-path concern (LG-12, ≤100 µs per record) is irrelevant for the Python siblings — they're cold-path. |
| **CF-* (configuration)** | tools + a possible `policy-loader` | `mgf-common.config.BaseAppSettings`-derived `HrbSettings` for the SDK's debounce / queue knobs. Policy itself is *data* (Part 8.4), consumed from a declarative file rather than from env vars. |
| **SC-* (security)** | SDK + tools | SC-02 (no shell injection) — relevant where `mgf-hrb-tools doctor` invokes external commands (`udevadm`, `lsmod`). SC-07 (timeouts on every external request) — the SDK applies this naturally because every long-lived call already takes a timeout (Part 6). |
| **TS-* (testing)** | All three | TS-01 (mirrored test tree), TS-02 (no real broker in unit tests — uses the public `FakeClient` from §8.6.1). |
| **AP-* (API design)** | SDK only | AP-01 (`__all__` at every module boundary), AP-08 (`from __future__ import annotations`), AP-11 (`experimental` until v1.0). |

---

## §3. What will *not* be mapped

Honesty about scope (the same fidelity discipline as the design):

- **Zig-side standards.** The Zig siblings are governed by the design
  doc's priority order and the kabi behavioral contract, not by
  `mgf-common`. Inventing a "Zig conformance tracker" mirroring the
  Python one would be ceremony without payoff.
- **Federation observability (`mgf-common.observability`).** OTel
  spans + redaction are useful in the Python SDK; **not** in the Zig
  hot path (the ring's per-event budget is far below OTel emit cost).
  The Zig side surfaces its own telemetry via the typed event stream.
- **Federation bootstrap (`mgf.common.bootstrap()`).** Applies only
  if/when `mgf-hrb-tools` ships a CLI with the federation conventions.
  Not until then.

---

## §4. Decision: L1 — Lite now, tighten to L2 when the SDK matures

**`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` now exists** and
declares **L1 — Lite**. The per-rule audit honestly marks most Python
rules ⏳ (in-progress, pre-SDK-maturity) and 🚫 N/A where the rule's
premise doesn't hold for Zig code or for a use-path-absent broker
(LG-12 hot-path budget, SC-06 TLS, EH-11 retries on the SPSC ring).
The audit is re-run on every `mgf-common` standards bump (per CFM-03)
and before the SDK approaches `v0.1.0`.

**The path to L2.** When `mgf-hrb-sdk-py` approaches `v0.1.0`:

1. Re-audit the Python rule families that were ⏳; promote to ✅ as the
   surfaces stabilise.
2. File a `DOC-NN` paper in [`FEEDBACK.md`](FEEDBACK.md) declaring the
   L1 → L2 transition, with the audit deltas as evidence.
3. Where a rule still doesn't fit, keep the 🚫 with the rationale per
   [`mgf-common`'s principles/non-adoption-is-valid.md](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/principles/non-adoption-is-valid.md).
   The principle covers exactly this case (rule × shape mismatch),
   so the L2 declaration doesn't have to mean "every rule ✅".

---

## §5. Cross-references

- [`docs/claude/CLAUDE.md`](docs/claude/CLAUDE.md) — this project's
  auto-managed copy of the mgf-common rule list + federation-
  discipline reminders.
- [`FEEDBACK.md`](FEEDBACK.md) — the place to file friction or
  re-raise the conformance question.
- [`hrb-design/mgf-hrb-complete-design.md`](hrb-design/mgf-hrb-complete-design.md)
  Part 8 (the Python SDK surface this note's mapping applies to).
