# DEPS — mgf-common's bidirectional dependency manifest

> **Purpose:** both sides of mgf-common's dependency graph in one place.
> **§1** — what mgf-common depends on. **§2/§3** — who depends on
> mgf-common (consumers + federation siblings). Knowing both directions
> makes deprecation, breaking-change blast-radius, and
> feature-prioritisation decisions tractable.
>
> **Maintained by:** the mgf-common owner (Bassam).
> **Pairs with:** [`FEEDBACK.md`](FEEDBACK.md) (what users tell us),
> [`PUBLIC_API.md`](PUBLIC_API.md) (what we tell users).
> **Per standard DOC-16** (v2.12): every project MUST maintain a
> `DEPS.md` at repo root. `DEPS.md` replaces the former `USERS.md`
> (its roster is now §2/§3 below).

Last verified: 2026-05-28.

---

## §1 What mgf-common depends on

mgf-common is the **cornerstone** + reference implementation. It
depends on exactly **one** `mgf-*` sibling —
[`mgf-standard`](https://codeberg.org/magogi-admin/mgf-standard),
the standards/contract data package that sits *below* it in the graph
(the federation leaf-of-leaves) — plus its third-party runtime deps:

| Dependency           | Window        | Why                                          | Tier |
|----------------------|---------------|----------------------------------------------|------|
| `mgf-standard`   | `>=0.1,<0.2`  | engineering-standards corpus + federation contract (surfaced via `mgf-fed standards`/`agents`) | runtime |
| `pydantic`           | `>=2.6,<3`    | `BaseAppSettings` + typed config schemas     | runtime |
| `pydantic-settings`  | `>=2.2,<3`    | layered settings loader                      | runtime |
| `pyyaml`             | `>=6.0,<8`    | YAML config layer                            | runtime |
| `opentelemetry-*` / `sentry-sdk` | see pyproject | tracing/error export | `[observability]` extra (lazy) |
| `keyring` / `cryptography` | see pyproject | vault backends             | `[vault]` extra (lazy) |

Runtime core is kept deliberately tight — every runtime dep ships
transitively into every consumer. Optional capabilities live behind
extras with lazy imports (DP-02).

---

## §2 Who depends on mgf-common — consumer projects (external users)

End-applications that depend on mgf-common.

| Project           | Location                                     | Import sites | Status                         | Primary surfaces used                                              |
|-------------------|----------------------------------------------|-------------:|--------------------------------|--------------------------------------------------------------------|
| **vm-vmanager-app**      | `/home/bassam/PycharmProjects/vm-vmanager-app`      | 38           | Active — mature, Qt6 desktop   | `bootstrap` / `setup_logging` / `process` / `vault` / `progress`   |
| **PlasmaMapper**  | `/home/bassam/PycharmProjects/PlasmaMapper`  | 25           | Active — multi-tenant FastAPI SaaS, heaviest adopter | `bootstrap` / `BaseAppSettings` / `db` / `observability` / `registry` |
| **iosRecovery**   | `/home/bassam/PycharmProjects/iosRecovery`   | 16           | Greenfield — CLI canary, pre-1.0 | `bootstrap` / `cli` / `process` / `progress`                       |
| **inthewords**    | `/home/bassam/PycharmProjects/inthewords`    | 12           | Behind — pinned to 0.31 (catch-up needed) | `bootstrap` / `observability` / `settings`                         |

**Reading the table.** Status labels reflect adoption depth (number of
mgf-common surfaces in use), not project size. "Import sites" is a
coupling proxy — a change to a low-coupling consumer is cheaper.

**Consumer-side trackers** (per DOC-14 / DOC-15):

- vm-vmanager-app: `docs/MGF_COMMON_ADOPTION.md` (status TBC — verify next session).
- PlasmaMapper: `docs/inprogress/MGF_ADOPTION.md` + `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`.
- inthewords: `docs/MGF_COMMON_ADOPTION.md`.
- iosRecovery: pre-code, no tracker yet — lands with the first commit.

---

## §3 Who depends on mgf-common — federation siblings (`mgf-*`)

Siblings that import `mgf.common.*` directly from their `src/`:

| Sibling          | Import sites | Surfaces used                                          | Codeberg                                          |
|------------------|-------------:|--------------------------------------------------------|---------------------------------------------------|
| **mgf-fastapi**  | 14           | `bootstrap` / `observability` / `exceptions` / `settings` | https://codeberg.org/magogi-admin/mgf-fastapi |
| **mgf-django**   | 7            | `bootstrap` / `observability` / `exceptions`            | https://codeberg.org/magogi-admin/mgf-django   |
| **mgf-apiprobe** | 6            | `bootstrap` / `exceptions` / `observability`            | https://codeberg.org/magogi-admin/mgf-apiprobe |
| **mgf-http**     | 4            | `bootstrap` / `exceptions`                              | https://codeberg.org/magogi-admin/mgf-http     |
| **mgf-livepush** | 1            | `exceptions` (SSE/broker errors subclass `AppError`)    | https://codeberg.org/magogi-admin/mgf-livepush   |
| **mgf-tele-core**| 1            | `exceptions` (telematics error hierarchy on `AppError`) | https://codeberg.org/magogi-admin/mgf-tele-core  |
| **mgf-auth**     | 1            | `exceptions` (typed 401 on `HttpUnauthorizedError`)     | https://codeberg.org/magogi-admin/mgf-auth       |

**Not importing `mgf.common.*` at runtime** (still depend via pyproject
pins for tests + bootstrap): **mgf-alembic**, **mgf-sqlalchemy** (wrap
their libs; consumers bootstrap before invoking), **mgf-tele-teltonika**
(imports transitively via `mgf-tele-core`), **mgf-test-supervisor**
(dev-dep only — `mgf.common.testing` schema contract), **mgf-website-template**
(cookiecutter, not a runtime lib), **mgf-usb** (pre-implementation
scaffold). Still federation members; just no direct `mgf.common.*`
import sites.

---

## §4 What a dependency-graph change MUST trigger

When a user is added, removed, or changes adoption depth (§2/§3):

1. Update the relevant table.
2. Confirm the user's tracker (`MGF_COMMON_ADOPTION.md` / `MGF_ADOPTION.md`) exists and is current.
3. If the user is on a stale mgf-common minor, open a FEEDBACK paper proposing the catch-up.

When mgf-common adds/changes a §1 dependency: confirm the window is
pinned at the next MAJOR (RA-05) and the cost is justified (every
runtime dep ships into every consumer).

---

## §5 How this list is maintained

Updated on every MINOR release + whenever a consumer/sibling is
added/removed. The §2/§3 import-survey methodology:

```sh
for proj in vm-vmanager-app inthewords PlasmaMapper iosRecovery; do
  grep -rE "(from|import) +mgf\.common" "/home/bassam/PycharmProjects/$proj" \
    --include='*.py' | wc -l
done
```
