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

> **Status.** Target conformance: **L2 — Standard** (per D-H3).
> Per-rule ledger:
> [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md).

## §1 Why L2

`mgf-vm-firecracker` is an **adapter library** — Python over the
Firecracker REST API + the jailer subprocess. Same shape as
`mgf-vm-libvirt`; same L2 bar for the same reasons:

- Adapter correctness *is* contract correctness; the conformance
  suite proves it.
- The library holds external resources (the Firecracker REST
  socket; jailer subprocesses), so DP-13 applies aggressively.
- Error translation at the seam (EH-02) is critical — Firecracker
  reports errors via HTTP status codes + JSON bodies that must
  translate to typed `mgf.vm.core.exceptions`.

## §2 Rules that apply non-trivially here

- **DP-01 (layering).** `mgf.vm.firecracker` MUST NOT import any
  other adapter. Depends *up* on `mgf-vm-core` + `mgf-common`.
- **DP-02 (ABC + mock).** Production implementation of
  `mgf-vm-core`'s ABCs; mock counterpart is the
  `FakeHypervisorBackend` from `mgf-vm-core`.
- **DP-09 (cancellation).** Every long-running adapter method
  takes a `CancellationToken`. Firecracker doesn't have
  long-running operations the way libvirt does (no live migration,
  no graceful shutdown polling — instances start in milliseconds,
  stop is fast), but the contract still requires the token plumb-
  through.
- **DP-13 (deterministic cleanup).** Two resources to release per
  instance: the Firecracker REST socket connection AND the jailer
  subprocess. Both via context managers; `close()` is idempotent.
- **EH-02 (translate at seam).** Every HTTP error from Firecracker
  AND every subprocess error from jailer translates to a typed
  `mgf-vm-core` exception. Translation table in `errors.py`.
- **SC-02 (subprocess argv).** Jailer is invoked via `subprocess`
  with **argv lists, never shell strings**. This is non-negotiable
  — the jailer arguments include paths controlled by the
  `VmSpec`, and shell-string construction would be a classic
  command-injection surface.
- **SC-15 (path traversal).** Disk paths from `VmSpec` validate via
  `Path.resolve()` + `is_relative_to()` against allowed roots.

## §3 What this library does NOT enforce

- **CF-** — N/A. Adapter takes a config object on construction; no
  Settings.
- **SC-06 (TLS)** — N/A. Local-only Unix socket; no network
  transport.
- **EH-04** — N/A (library, not entry point).

## §4 Phasing

Skeleton landed 2026-05-24. Real implementation is a Phase 1
deliverable per `vm-vmanager-docs/ROADMAP.md`. Conformance suite
must be green against real Firecracker (in CI, containerized) before
the 0.1.0 release.
