# `mgf-alembic` — scope policy

> `mgf-alembic`'s **scope policy** (family **SP**) — what belongs in this
> async-aware alembic env.py helper. A proposed addition is in scope only if it
> passes the §3 gate.

## §1 In scope (SP-01)

A thin helper that removes alembic env.py boilerplate for mgf-common consumers:

- `configure_env()` — one call replaces ~40 lines of alembic env.py (sync + async,
  online + offline), with safe defaults (NullPool, password redaction, RA guards)
- schema-drift detection (`detect_drift` / `DriftReport`)

The boundary: **wiring alembic + (async) SQLAlchemy into a consumer's env.py with
safe defaults.** Consumers own their migrations, models, and DB driver.

## §2 Out of scope (SP-02) — with reasons

| Not here | Why | Where instead |
|---|---|---|
| Authoring migrations | that's alembic's revision workflow | `alembic revision` |
| The migration CLI | alembic already provides it | `alembic` |
| ORM model / `Base` definitions | consumer's domain | the consumer app |
| The DB driver | consumer picks | `asyncpg` / `psycopg` / `aiosqlite` |
| Engine/session helpers | a separate sibling | `mgf-sqlalchemy` |
| A schema-versioning policy / data backfills | consumer/migration concern | the consumer's migrations |

## §3 Scope-creep gate (SP-03)

A PR adding a module/helper MUST answer: (1) does it need alembic/SQLAlchemy
env-wiring types (else → `mgf-common`/`mgf-sqlalchemy`)? (2) is it env.py wiring +
safe defaults, not migration authoring or a consumer domain concern? (3) consumer
demand signal, or speculative? Any "no/unclear" blocks it.

## §4 Adjacent scope (SP-04)

Adjacent (not yet in): a multi-DB env.py variant, a CI drift-gate runner, a
post-migrate hook framework. Move adjacent → in only on a documented consumer
demand signal, never speculatively.

## §5 Alternatives for out-of-scope needs (SP-05)

Migration authoring → `alembic`; engine/session → `mgf-sqlalchemy`; a driver →
`asyncpg`/`psycopg`/`aiosqlite`; ORM models → SQLAlchemy declarative in your app.

## §6 Revisiting scope (SP-06)

Revisited at every **MAJOR** boundary; a major bump re-justifies the surface
against §1/§2 and re-affirms the env-helper-not-migration-tool invariant.
