mgf-vm-core 0.1.0

Magogi Foundation VM-core — pure VM-domain library: state machine, VmSpec, contracts, fakes. The stable core of the distributed vm-vmanager-app.

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. Design rationale: 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/ 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)

pip install mgf-vm-core

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

uv pip install -e ~/PycharmProjects/mgf_vm_core

Develop

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