# DEPS — mgf-sqlalchemy's bidirectional dependency manifest

> **§1** — what mgf-sqlalchemy depends on. **§2** — who depends on
> mgf-sqlalchemy. 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` (its roster is now §2 below).

Last verified: 2026-06-07.

---

## §1 What mgf-sqlalchemy depends on

| Dependency | Window | Why | Tier |
|---|---|---|---|
| `mgf-common` | `>=0.41,<0.47` | AppError + observability + settings + identity | runtime *(federation sibling)* |
| `sqlalchemy[asyncio]` | `>=2.0` | the async ORM/engine layer these helpers wrap | runtime |
| `aiosqlite` | `>=0.20` | async sqlite driver for the test suite / in-memory dev DB | `[test]` (lazy) |

*Federation siblings depended on: `mgf-common` — supplies the typed
`AppError` hierarchy, observability, settings, and identity surfaces
this sibling builds atop.*

Runtime core is deliberately tight. Production consumers pick their own
real-DB async driver (asyncpg, aiomysql, asyncmy) — mgf-sqlalchemy
does not pin one.

---

## §2 Who depends on mgf-sqlalchemy

Consumer projects + federation siblings that import `mgf.sqlalchemy.*`.
(Inverse of each consumer's `MGF_ADOPTION.md`.)

### Consumer projects (external users)

| Project | Location | Import sites | Status | Surfaces used |
|---|---|---:|---|---|
| **PlasmaMapper** | `/home/bassam/PycharmProjects/PlasmaMapper` | 2 | Active — multi-tenant FastAPI SaaS | Session helpers + (planned) `AuditTrailMixin` |

**Single-consumer reality.** Only PlasmaMapper imports `mgf.sqlalchemy`
directly today, and only at two call sites. The v0.4.0 audit-trail mixin
+ UUID v7 surface shipped ahead of broad adoption — PlasmaMapper will
pick them up in its next mgf-* refresh.

### Federation siblings (`mgf-*` libraries)

| Sibling | Import sites | Surfaces used |
|---|---:|---|
| **mgf-fastapi** | 1 *(via the `[sqlalchemy]` extra)* | Audit-trail integration glue |

mgf-fastapi declares `mgf-sqlalchemy>=0.4,<0.5` under the `[sqlalchemy]`
extra so FastAPI + SQLAlchemy + audit-trail compose without consumers
having to manage three pins manually.

**Blast-radius note.** The `AuditTrailMixin` adds **four columns** to any
table that mixes it in (`created_at`, `created_by`, `updated_at`,
`updated_by`). Renaming or retyping those post-v1.0 would force
PlasmaMapper to write a migration — treat any change to the mixin column
shape as a major-version-bump candidate even before v1.0.

---

## §3 Maintenance

Updated every MINOR release + when a dependency or consumer changes.
Import-survey methodology:

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