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

> **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**.

## §1 Why L2

`mgf-vm-sdk` is the **client surface** every CLI, GUI, and external
consumer imports. L2 is the right bar because:

- **The SDK surface is the most-imported surface in the federation.**
  Every breaking change ripples through CLI + GUI + future bindings.
  L2's mechanical enforcement of typing (DP-04), `__all__` discipline
  (AP-01), and deprecation cycle (AP-04) is exactly what a heavily-
  consumed library needs.
- **Two transports must behave identically above the contract.** The
  conformance burden is on us to ensure `InProcessTransport` and
  `GrpcTransport` are observationally equivalent for every method.
  L2 makes the parity tests a CI gate, not a hope.
- **The error rehydration seam is load-bearing.** Across the network,
  a typed `mgf-vm-core` exception travels as `vmanager.api.v1.Error`
  in the gRPC status detail. The SDK rehydrates it to the typed
  Python exception (D-G3). L2 makes this seam tested.

## §2 Rules that apply non-trivially here

- **DP-01 (layering).** The SDK depends only on `mgf-vm-core` +
  `mgf-common`. It MUST NOT import any adapter (`mgf-vm-libvirt`,
  `mgf-vm-firecracker`). The `InProcessTransport` accepts adapter
  *instances* injected by the caller; it does not import them
  directly. Enforced by `import-linter`.
- **DP-04 (typed signatures).** Critical. Every `VmManagerClient`
  method is the surface external consumers code against.
- **DP-09 (cancellation).** Every long-running SDK method takes a
  `CancellationToken`. Across the network, this maps to gRPC
  context cancellation; in-process, the token is honored by the
  underlying adapter call.
- **EH-02 + D-G3 (typed errors across the wire).** The SDK's job at
  the boundary: rehydrate `vmanager.api.v1.Error` protobuf details
  to the corresponding `mgf.vm.core.exceptions` subclass on the
  client side. String-matching is a contract violation.
- **AP-04 (deprecation).** Every removed SDK method requires a
  one-minor `DeprecationWarning` window. The two transports must
  agree on the deprecation: removing a method from `InProcessTransport`
  without also deprecating it on `GrpcTransport` is a contract bug.
- **CF-** — N/A as application config. The SDK takes a transport
  *instance* + optional auth credentials by parameter.

## §3 What this library does NOT enforce

- **SC-02 / SC-15** — N/A (no subprocess, no filesystem ops).
- **EH-04** — N/A (library, not entry point).
- **LG-** — light-touch. The SDK emits logs but the formatter +
  redactor are the consumer's concern.

## §4 How this file evolves

Same discipline as the other federation siblings.
