# STANDARDS_NOTE — `mgf-common` federation standards and `mgf-vm-libvirt`

> **Status.** Target conformance: **L2 — Standard** (per D-H3 in
> [`vm-vmanager-docs/DECISIONS.md`](https://codeberg.org/magogi-admin/vm-vmanager-docs)).
>
> The per-rule ledger lives in
> [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md).
> This file records the **deeper rationale** behind the level choice
> and how the standards apply to an *I/O-heavy adapter library*.

## §1 Why L2

`mgf-vm-libvirt` is an **adapter library** — pure Python on top of
the `libvirt-python` binding. L2 is the right bar because:

- **Adapter correctness is contract correctness.** The library's
  purpose is to faithfully implement two Protocols from `mgf-vm-core`
  (`HypervisorBackend` + `StorageBackend`). The conformance suite
  enforces the contract; L2 makes its supporting rules (typing,
  error translation, cancellation, layering) mechanically enforced.
- **The library holds a real resource.** The libvirt connection is
  owned external state — DP-13 applies aggressively. L2 makes
  context-manager cleanup mandatory rather than aspirational.
- **The error translation seam is load-bearing.** Every libvirt
  exception MUST translate at the boundary to `mgf-vm-core`'s typed
  hierarchy (EH-02). Above L2, this becomes a mechanically checked
  rule rather than convention.
- **L3 is reserved for the daemons.** `vm-vmanager-agent` (which
  composes this library) will run at L3 in its own surface.

## §2 Rules that apply non-trivially here

- **DP-01 (layering).** Hard rule. `mgf.vm.libvirt` MUST NOT import
  any other adapter (no Firecracker, no `mgf-hrb`). It depends *up*
  on `mgf-vm-core` and `mgf-common`. Enforced by `import-linter`.
- **DP-02 (ABC + mock).** Satisfied by *being* the production
  implementation of `mgf-vm-core`'s ABCs. The mock counterpart is
  `mgf-vm-core`'s `FakeHypervisorBackend` (D-F3).
- **DP-09 (cancellation).** Every long-running method (`start`,
  `stop` graceful, `snapshot`, `revert_snapshot`, `migrate`,
  `convert_format`) takes a `CancellationToken` per the contract.
- **DP-13 (deterministic cleanup).** The libvirt connection MUST be
  closed via context manager or explicit `close()`. The conformance
  suite includes a leak-detection test under Python 3.13's strict
  unraisable handling.
- **EH-02 (translate at seam).** Every `libvirt.libvirtError` raised
  by the binding MUST be caught at the adapter method boundary,
  classified, and re-raised as the corresponding `mgf-vm-core`
  exception with `raise ... from libvirt_exception`. The translation
  table lives in `src/mgf/vm/libvirt/errors.py`.
- **SC-15 (path traversal).** Applies to any code that reads a VM
  disk path supplied by the spec. Use `Path.resolve()` +
  `is_relative_to()` per the rule.
- **LG-04 (log redaction).** Applies. Domain names, network MACs,
  device serial numbers in libvirt error messages — passed through
  `mgf.common.observability.Redactor` before any sink.

## §3 What this library does NOT enforce

- **CF-** (config) — N/A. Adapter takes a connection URI + token;
  no Settings.
- **SC-02 (subprocess argv)** — N/A. Adapter does no subprocess
  calls (the binding does; not our seam).
- **SC-06 (TLS)** — N/A. libvirt-native transport.
- **EH-04 (top-level handler)** — N/A. Library, not entry point.

## §4 How this file evolves

Same discipline as `mgf-vm-core`'s STANDARDS_NOTE.md §4.
