# `mgf-fastapi` — scope policy

> This is `mgf-fastapi`'s **scope policy** (federation rule family **SP**). It is
> independent of `mgf-common`'s SCOPE — it governs what belongs in *this* FastAPI
> adapter sibling. A proposed addition is in scope only if it passes the gate in
> §3.

## §1 In scope (SP-01)

`mgf-fastapi` provides **thin, framework-coupled adapters** that wire
`mgf-common` primitives into a FastAPI/Starlette app:

- request-id propagation middleware (`RequestIdMiddleware`)
- exception → HTTP translation (`ExceptionTranslationMiddleware`)
- app lifespan wiring (`setup_lifespan`, `get_app_context`, `get_settings`)
- webhook HMAC verification (Svix-shape; `HmacWebhookVerifier`)
- IP allow-listing + bearer-session auth seams (`IpAllowlist`, `bearer_session`, `AuthVerifier`)
- token-bucket rate limiting (`RateLimitMiddleware`, `TokenBucket`)
- a test-server helper (`run_test_app`)
- optional DB-session (`[sqlalchemy]`) and per-app log-stream (`[livepush]`) bridges

The boundary: **adapter code that needs FastAPI/Starlette types**. Anything
framework-neutral belongs in `mgf-common`.

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

| Not here | Why | Where instead |
|---|---|---|
| Framework-neutral primitives (errors, settings, observability, retries) | belongs in the cornerstone | `mgf-common` |
| ORM / migration logic | a separate concern with its own sibling | `mgf-sqlalchemy` / `mgf-alembic` |
| SSE/broker transport internals | owned by its sibling | `mgf-livepush` |
| A full auth/identity system (user store, token issuance, RBAC) | mgf-fastapi ships **seams** (Protocols), not an implementation | consumer app / a future `mgf-auth` |
| Django/other-framework adapters | framework-specific | `mgf-django` etc. |
| A CLI / standalone service | mgf-fastapi is a *library* | consumer app |

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

A PR adding a new module/middleware/helper MUST answer, in its description:
1. Does it need FastAPI/Starlette types? (If no → it belongs in `mgf-common`.)
2. Is it an adapter (wiring), not a new domain/business capability?
3. Is there a consumer demand signal (a `FEEDBACK.md` paper / recipe), or is it speculative?

If any answer is "no/unclear", it does not land until the scope question is resolved.

## §4 Adjacent scope (SP-04)

Adjacent (plausible but not yet in): GraphQL adapters, gRPC bridges, OpenAPI
codegen helpers, a generic pagination/cursor helper. These move from adjacent →
in scope only on a **consumer demand signal** (a `FEEDBACK.md` paper from a real
consumer), never speculatively.

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

If you need something §2 excludes: framework-neutral → `mgf-common`; DB →
`mgf-sqlalchemy`; SSE → `mgf-livepush`; a full auth system → implement the
`AuthVerifier` Protocol in your app (or adopt a dedicated sibling when one exists).

## §6 Revisiting scope (SP-06)

This policy is revisited at every **MAJOR** boundary (the 0.x → 1.0 line, and
each later major). Pre-1.0, scope may tighten/loosen per the SP-03 gate; a major
bump is the checkpoint to re-justify the whole surface against §1/§2.
