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

> **Status.** Declared conformance: **L2 — Standard** (per D-H3 in
> [`vm-vmanager-docs/DECISIONS.md`](https://codeberg.org/magogi-admin/vm-vmanager-docs)).
> Same level `mgf-hrb` runs at. (Was filed as the "target" level pre-2026-05-27;
> the per-rule ledger confirmed L2 conformance, so this is now the declared level.)
>
> 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 a few non-trivial rule applications particular to this library.
>
> **Why this file 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 L2 is the right
> level for this kind of library, and how the standards apply to a
> *pure-domain* library (no I/O, no transport, no privileged ops).

## §1 Why L2

L2 — Standard is the right bar for `mgf-vm-core` because:

- **The library is on the federation's critical path.** Every adapter
  implements *for* it; every client depends *on* it. A standards
  weakness here propagates outward to every consumer. L1 — Lite would
  permit drift; L3 — Strict would be over-investment for a library
  whose surface (Protocols + dataclasses + state machine) is already
  small and disciplined.
- **The library is `mgf-common`'s most direct user.** `mgf-vm-core`'s
  `VmManagerError` extends `mgf.common.exceptions.AppError`; its
  Settings stories (where applicable) use `mgf.common.config`; its
  fakes are designed to participate in `mgf-common.testing` fixtures.
  L2 means the integration is tested per the conformance tracker, not
  assumed.
- **L3 is reserved for production daemons.** Where the standards say
  L3 implies CI gates that block on every standard, our use-cases for
  L3 are the privileged daemons (`vm-vmanager-control-plane`,
  `vm-vmanager-agent`) — they will declare L3 when they reach maturity.

## §2 Rules that apply non-trivially here

Most `mgf-common` rules apply uniformly. A few have library-specific
interpretation worth documenting:

- **DP-01 (layering).** Enforced by `import-linter` in CI. The core
  Protocols MUST NOT import any adapter; the adapters MUST NOT import
  each other. Contracts in [`vm-vmanager-docs/DECISIONS.md`](https://codeberg.org/magogi-admin/vm-vmanager-docs) D-H4.
- **DP-02 (ABC + mock).** Satisfied uniquely well — the fakes
  (`FakeHypervisorBackend`, `FakeStorageBackend`, `FakeDeviceBackend`)
  ship as first-class library artifacts (D-F3), not in `tests/`.
  Downstream consumers' unit tests use these directly.
- **DP-03 (frozen domain types).** Every public type is a frozen
  dataclass or pydantic `frozen=True`. IDs are opaque wrapped strings;
  never bare strings cross module boundaries.
- **DP-13 (deterministic cleanup).** N/A at this layer — `mgf-vm-core`
  holds no external resources. The rule applies aggressively in the
  adapter layer (where it caused PAPER-60-adjacent friction recently)
  and in the agent.
- **EH-02 (translate at seam).** N/A inward — `mgf-vm-core` defines
  the seam; adapters translate engine exceptions to *this* library's
  taxonomy at their seam.
- **TS-02 (unit tests no daemons).** Trivially satisfied — the library
  has no daemon path at all. The conformance suite is *adapter*-tier
  (Tier 2 in [`TESTING.md`](https://codeberg.org/magogi-admin/vm-vmanager-docs/src/branch/main/TESTING.md))
  and runs in adapter repos, not here.
- **LG-01 (logger via `getLogger(__name__)`).** Honored uniformly.
  `mgf-vm-core` itself does little logging — the state machine emits
  transitions as `LifecycleObserver` events, not as logs. Observability
  is the consumer's concern.
- **AP-04 (deprecation).** Critical here. A breaking change to a
  Protocol ripples through every consumer. The discipline is: announce
  → still works for ≥1 MINOR → removed, with `DeprecationWarning`.

## §3 What this library does NOT enforce

The federation standards we honestly leave to consumers (because the
library lacks the context):

- **CF-** (config) — `mgf-vm-core` has no application config; functions
  take typed parameters. Consumers carry the Settings story.
- **SC-02/06/07/15** (subprocess / TLS / timeouts / path traversal) —
  N/A here. Apply at the adapter and agent layers.
- **EH-04** (entry-point handler) — applies to *applications*, not
  libraries.

These appear as `N/A` in the conformance tracker with the reason
stated.

## §4 How this file evolves

- On every minor bump of `mgf-common`, re-walk the new/changed rules
  and either map them here or mark N/A in the tracker.
- On any new module added to this library, re-check whether the N/A
  rationale above still holds.
- Conformance level changes (L2 → L3) land here as a §-bump with full
  rationale, and in `vm-vmanager-docs/DECISIONS.md` as a new ADR.
