# mgf-vm-core

> **The pure VM-domain library for the Magogi Foundation distributed
> vm-vmanager-app.** State machine, engine-neutral `VmSpec`, the three
> `Protocol` contracts, the shipped fakes, the conformance suite.
> No engine deps — no libvirt, no Firecracker, no `mgf-hrb`.
>
> The stable core that every adapter implements *for* and every
> client depends *on*.

| Field | Value |
|---|---|
| **Status** | Pre-`0.1.0`. Phase 0 of the vm-vmanager-app roadmap. |
| **Federation sibling.** | Cornerstone: `mgf-common>=0.38,<0.39`. |
| **Conformance level.** | **L2 — Standard.** Per-rule ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md). Design rationale: [`STANDARDS_NOTE.md`](STANDARDS_NOTE.md). |
| **License.** | MIT. |
| **Python.** | 3.11 / 3.12 / 3.13. |

---

## Where the docs live

**Everything load-bearing about this library — what it does, why it
exists, what its contracts mean, how it relates to the rest of the
system — lives in the dedicated vm-vmanager-app docs repo:**

> **`vm-vmanager-docs`** — `~/PycharmProjects/vm-vmanager-docs/` ·
> Codeberg: `vm-vmanager-docs`

Specifically:

| What | Where |
|---|---|
| End-to-end architecture | `vm-vmanager-docs/ARCHITECTURE.md` |
| Component inventory + this library's role | `vm-vmanager-docs/COMPONENTS.md` |
| The decision register (D-B2 = this split) | `vm-vmanager-docs/DECISIONS.md` |
| **The four-Protocol spec — required reading** | `vm-vmanager-docs/component-specs/contracts.md` |
| The roadmap (Phase 0 Stream A = this library) | `vm-vmanager-docs/ROADMAP.md` |
| The test strategy (`mgf.vm.core.conformance` suite) | `vm-vmanager-docs/TESTING.md` |
| The dev loop (`make dev`) | `vm-vmanager-docs/DEV-LOOP.md` |
| Glossary | `vm-vmanager-docs/GLOSSARY.md` |

If you're reading this and you want to *implement* an adapter, the
relevant spec is **`vm-vmanager-docs/component-specs/contracts.md`** —
read it first. It's the contract.

---

## What this library contains

(Phase 0 — see `vm-vmanager-docs/ROADMAP.md`.)

```
src/mgf/vm/core/
├── __init__.py        # public re-exports (AP-01)
├── py.typed
├── domain.py          # VmSpec, VmStatus, VmState, IsolationLevel, ID types
├── state_machine.py   # VmLifecycleStateMachine
├── contracts.py       # HypervisorBackend, StorageBackend, DeviceBackend, LifecycleObserver
├── exceptions.py      # VmManagerError taxonomy (D-G3)
├── fakes/             # FakeHypervisorBackend, FakeStorageBackend, FakeDeviceBackend (D-F3)
├── conformance/       # the cross-adapter test suite (TESTING.md Tier 2)
└── testing/           # shared pytest fixtures + helpers
```

The fakes are **first-class shipping artifacts** (per D-F3) — used
by every downstream library's tests and by the dev loop. They live
in the package proper, not in `tests/`.

The conformance suite is the **contract enforced**. Every adapter
implementation runs it against the real engine on the other side
of the boundary. See [`tests/conformance/`](tests/conformance/) for
the runner skeleton and `vm-vmanager-docs/component-specs/contracts.md`
§10 for the catalogue of named scenarios.

---

## What this library does NOT contain

- **No libvirt** — lives in `mgf-vm-libvirt`.
- **No Firecracker** — lives in `mgf-vm-firecracker` (Phase 1).
- **No mgf-hrb client** — lives in `vm-vmanager-agent`.
- **No CLI / GUI / control plane / agent** — lives in `vm-vmanager-*`.
- **No transport** — lives in `mgf-vm-sdk`.

That is the wrap-don't-marry discipline. See D-B2 in
`vm-vmanager-docs/DECISIONS.md`.

---

## Install (consumer)

```bash
pip install mgf-vm-core
```

Or as an editable install for local development against sibling
checkouts:

```bash
uv pip install -e ~/PycharmProjects/mgf_vm_core
```

## Develop

```bash
cd ~/PycharmProjects/mgf_vm_core
uv venv --python 3.12
uv sync --extra dev
uv run pytest -q             # unit
uv run mypy --strict src/    # types
uv run ruff check src tests  # style
uv run lint-imports          # layering (D-H4)
```

All four gates must be green for any PR (mgf-common standards-default).

For the full system dev loop (this library + adapters + the agent +
CP + clients), see `vm-vmanager-docs/DEV-LOOP.md`.

---

## Federation context

`mgf-vm-core` is a federation sibling (per
[`mgf-common`'s federation strategy](https://codeberg.org/magogi-admin/mgf_common)).
It depends only on `mgf-common`; it is depended on by every other
`mgf-vm-*` library and by every `vm-vmanager-*` application.

Per federation discipline:
- **`USERS.md`** — who depends on this library
- **`STANDARDS_NOTE.md`** — conformance-level argument
- **`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`** — per-rule status
- **No `MGF_ADOPTION.md`** — exempted by ADP-04 (federation siblings
  use the federation roadmap + their own CHANGELOG instead)

## Reporting issues

- **Feedback / design pushback / API friction**: file in this repo's
  `FEEDBACK.md` (or in `mgf-common`'s `FEEDBACK.md` for federation-
  wide concerns, per DOC-13).
- **Security vulnerabilities**: see `SECURITY.md`.
