# DEPS — mgf-vm-core's bidirectional dependency manifest

> **§1** — what mgf-vm-core depends on. **§2** — who depends on
> mgf-vm-core. Knowing both directions makes deprecation,
> breaking-change blast-radius, and feature-prioritisation tractable.
>
> **Per standard DOC-16** (v2.12): every project ships a `DEPS.md`.
> Replaces the former `USERS.md`.

Last verified: 2026-06-09.

---

## §1 What mgf-vm-core depends on

`mgf-vm-core` is a **pure domain library** — no third-party engine
deps (no libvirt, no Firecracker, no `mgf-hrb`). That is the
wrap-don't-marry discipline (D-B2). Its dependencies are deliberately
tight:

| Dependency | Window | Why | Tier |
|---|---|---|---|
| `mgf-common` | `>=0.41,<0.47` | cornerstone — typed exceptions / bootstrap / observability | runtime (federation sibling) |
| `pydantic` | `>=2.6,<3` | the typed, frozen `VmSpec` + domain value types | runtime |

*Federation siblings depended on: `mgf-common` — the cornerstone.
This is the only `mgf-*` sibling mgf-vm-core depends on; it sits one
layer above the cornerstone and below every `mgf-vm-*` adapter.*

Dev-only tooling (`pytest`, `hypothesis`, `ruff`, `mypy`,
`import-linter`, `types-paramiko`) lives in the `[dev]` extra and
never ships to consumers.

---

## §2 Who depends on mgf-vm-core

Federation siblings + applications that build on the core. Every
consumer's load-bearing dependency is the four `Protocol` contracts
(`HypervisorBackend`, `StorageBackend`, `DeviceBackend`,
`LifecycleObserver`) plus the `VmSpec` domain types and the typed
exception taxonomy.

> **Status (2026-05-28).** mgf-vm-core is pre-`0.1.0` (Phase 0). The
> siblings below carry **hard pyproject pins** on `mgf-vm-core>=0.1,<0.2`
> (resolved via local editable `[tool.uv.sources]` until PyPI publish),
> but no runtime `import mgf.vm.core` sites exist yet — they are
> **designed-for / pre-code scaffolds**. Counts are the live import
> survey, not the intended surface.

| Project / sibling | Location | Import sites | Status | Surfaces used |
|---|---|---:|---|---|
| **mgf-vm-libvirt** | `/home/bassam/PycharmProjects/mgf-vm-libvirt` | 0 | designed-for (pin: `>=0.1,<0.2`) | `HypervisorBackend`, `StorageBackend`, `VmSpec`, `exceptions.*`, conformance suite |
| **mgf-vm-firecracker** | `/home/bassam/PycharmProjects/mgf-vm-firecracker` | 0 | designed-for, Phase 1 (pin: `>=0.1,<0.2`) | `HypervisorBackend`, `StorageBackend`, conformance suite |
| **mgf-vm-sdk** | `/home/bassam/PycharmProjects/mgf-vm-sdk` | 0 | designed-for (pin: `>=0.1,<0.2`) | `VmSpec`, `VmStatus`, ID types, `exceptions.VmManagerError` taxonomy |
| **mgf-vm-forensics** | `/home/bassam/PycharmProjects/mgf-vm-forensics` | ✓ | active (pin `>=0.1,<0.2`) — ✅ flipped off the umbrella 2026-06-05 (v0.1.4) | `common.{shell,atomic_io}`, `security.isolation`, exceptions |
| **mgf-vm-interchange** | `/home/bassam/PycharmProjects/mgf-vm-interchange` | ✓ | active (pin `>=0.1,<0.2`) — ✅ flipped off the umbrella 2026-06-05 (v0.2.0) | `domain`, `exceptions`, `common.{safe_tar,progress}` |
| **vm-vmanager-app** | `/home/bassam/PycharmProjects/vm-vmanager-app` | 0 | designed-for — transitive via `mgf-vm-sdk` only (D-H4) | none directly |

Phase-1 applications also designed-for (no repo / pin yet):
`vm-vmanager-control-plane` (`VmSpec` + state-machine semantics),
`vm-vmanager-agent` (composes the adapter Protocols + `mgf-hrb`).

A breaking change to any of the four Protocols affects every row
above. Per AP-04, breaking changes carry a one-minor deprecation
window with a `DeprecationWarning`.

*Note: `mgf-vm` is the legacy source the core is being extracted
**from** — it does NOT depend on mgf-vm-core.*

---

## §3 Maintenance

Updated every MINOR release + when a dependency or consumer changes.
Import-survey methodology (scoped to `src/` + `tests/` per repo to
avoid `.venv` noise):

```sh
grep -rE "(from|import) +mgf\.vm\.core" \
  /home/bassam/PycharmProjects/<consumer>/src \
  /home/bassam/PycharmProjects/<consumer>/tests \
  --include='*.py' | wc -l
```

As of 2026-05-28 every `mgf.vm.core` reference across the siblings
is in a docstring/comment, not a runtime import — hence the 0 counts.
Re-run this when the core ships `0.1.0` and the adapters start
implementing the contracts.
