# Federation alignment — v0.34.0 cycle

> **Audience:** consumers of two or more federation packages
> (`mgf-common` + any of `mgf-fastapi` / `mgf-sqlalchemy` /
> `mgf-alembic` / `mgf-http` / `mgf-apiprobe` / `mgf-django`).
> Read this **instead of** the per-sibling CHANGELOG / cutover
> docs when walking through a federation-alignment minor of
> `mgf-common`.

This is the **single coordinated cutover** for the
`mgf-common 0.34.0` release cycle. mgf-common 0.34.0 was an
internal-only release (perf gates + standards v2.6/v2.7); the
visible consumer-side work is the **sibling pin walk**: each
federation sibling shipped a companion minor whose `mgf-common`
pin moved to `>=0.34,<0.35`.

This doc was written retroactively (2026-05-19) per
[FEEDBACK PAPER-35](../../FEEDBACK.md) — the first federation
cutover to use this aggregate shape, retroactively covering the
v0.34 alignment that PlasmaMapper walked four sibling CHANGELOGs
to triage. Subsequent federation-alignment cycles use this doc
as the template.

---

## §1 At-a-glance pin walks

Update your `pyproject.toml` (or `requirements/*.txt`) to widen
the pin windows in lockstep. None of these are codemod-driven;
they're text edits in the dependency stanza.

| Package | Pin (was) | Pin (now) | Consumer code-change required? |
|---|---|---|---|
| `mgf-common` | `>=0.33,<0.34` | `>=0.34,<0.35` | **No** — internal-only release (perf gates + standards docs) |
| `mgf-fastapi` | `>=0.3,<0.4` | `>=0.4,<0.5` | **No** — docs-only (SECURITY.md + `docs/claude/CLAUDE.md` + `docs/standards/README.md` stub) |
| `mgf-sqlalchemy` | `>=0.1,<0.2` | `>=0.2,<0.3` | **No** — docs-only (same shape as mgf-fastapi 0.4.0) |
| `mgf-alembic` | `>=0.2,<0.3` | `>=0.3,<0.4` | **No** — defaults preserved; opt-in to two new kwargs (see §3) |
| `mgf-http` | (unchanged) | (unchanged) | n/a — no companion minor this cycle |
| `mgf-apiprobe` | (unchanged) | (unchanged) | n/a — no companion minor this cycle |
| `mgf-django` | (unreleased) | (unreleased) | n/a — not yet on PyPI |

After the walk, run `uv sync` (or `pip install -r requirements/base.txt`)
and verify the test suite stays green. The combined update is
risk-equivalent to a no-op MINOR.

---

## §2 What's actually new for consumers

The user-visible delta is narrow. The list below is the *opt-in*
surface — adopting any of it is optional.

### 2.1 New `mgf-alembic` kwargs (opt-in)

`mgf.alembic.configure_env` (re-exported from `mgf-alembic` 0.3.0)
gained two optional kwargs. Defaults preserve the previous
behaviour exactly; the new kwargs are pure additions.

- `is_async: bool | None = None` — async-engine detection. Default
  `None` = auto-detect from the engine URL (`postgresql+asyncpg://`
  → async; `postgresql://` → sync). Pass `True` / `False`
  explicitly when the URL is constructed dynamically and auto-detect
  would mis-fire.
- `transaction_per_migration: bool = False` — wraps each migration
  in its own transaction. Useful for migrations that issue DDL
  Postgres can't run inside a single tx (concurrent index creation,
  partition attach, etc.). The default `False` matches alembic's
  out-of-box behaviour.

A new diagnostic also lands: `mgf-alembic` 0.3.0's `RA-01` raises
when `configure_env` is called from inside a running event loop
(the alembic CLI runs sync; calling from FastAPI's lifespan is the
mis-wiring that this catches). Pre-0.3 consumers who do call from a
running loop will see the raise on upgrade — that's the fix
working.

### 2.2 Standards v2.6 / v2.7 (informational)

`docs/standards/` in `mgf-common` 0.34.0 added two standards
revisions:

- **v2.6** — project-shape taxonomy in `DOCUMENTATION.md`
  (DOC-01 / §2.0). `LICENSE` is now MUST in the universal-four root
  docs.
- **v2.7** — new `DEPLOYMENT.md` (DEP-01..DEP-11). Applies to
  stateful web-service consumers (NOT to federation siblings, which
  ship to PyPI).

Consumers running a standards audit should add the new rules to
their audit ledger. No code-change in mgf-common itself triggers
these — the docs ARE the surface.

### 2.3 Perf-gate test additions

`mgf-common` 0.34.0 added regression-protection tests inside its own
suite — PC-02 (sustained throughput), PC-03 (Redactor scaling),
PC-04 (`report_now()` latency), PC-05 (bootstrapped-process memory
baseline), plus P2 perf + security gates PC-07, PC-09, PC-10.

These tests run inside `mgf-common`'s own CI. **Consumers don't
need to do anything** — the gates protect against regressions in
the upstream code. The performance characteristics consumers
already depend on are now pinned.

---

## §3 Federation-cutover doc shape (template)

This section is **for the maintainer**, not for consumers. It
documents the doc shape so subsequent federation-alignment cycles
ship the same aggregate cutover.

### When to write a federation-cutover doc

Write `docs/cutover/federation-v<X.Y>.md` when **two or more
sibling packages need a pin walk** in the same `mgf-common` minor
cycle. The threshold is "would a consumer of N sibling packages
have to read N CHANGELOGs to triage?" — if N ≥ 2, the aggregate
cutover saves N–1 read passes.

Don't write a federation-cutover doc when:

- Only `mgf-common` itself shipped, with no sibling pin walks.
- A single sibling shipped a breaking minor (use the sibling's own
  `docs/cutover/v<X.Y.Z>.md` per DOC-05).
- The mgf-common minor is purely additive AND no sibling pin
  windows close around it. ("Closes around" = an existing sibling
  pins `>=X,<Y`; the new mgf-common is `Y`; the sibling must move
  to a new pin window before consumers can use the new mgf-common
  features.)

### Required sections

The four sections this doc demonstrates:

1. **§1 At-a-glance pin walks** — the table consumers act on in
   30 seconds.
2. **§2 What's actually new for consumers** — only the consumer-
   facing delta. Internal changes (refactors, perf-gate test
   additions, doc-only standards moves) get a one-paragraph
   summary and a pointer to the relevant CHANGELOG / sibling doc
   rather than a full re-narration.
3. **§3 Federation-cutover doc shape (template)** — this section.
   Copy from this v0.34 file when authoring v<X.Y> next time.
4. **§4 Cross-references** — pointers to the individual sibling
   CHANGELOGs / cutovers for consumers who want the full per-
   package detail.

### File naming

`docs/cutover/federation-v<X.Y>.md` (not `v<X.Y.Z>` — the
federation cutover keys off the mgf-common MINOR, not the
specific PATCH within it). When a follow-up patch ships within
the same minor cycle, update the same file in-place with a §5
"Patches in this cycle" note rather than creating a sibling file.

---

## §4 Cross-references

Per-sibling cutover docs (the full per-package detail, if you
want the unaggregated read):

- mgf-common 0.34.0 — no `docs/cutover/v0.34.0.md` exists: the
  release was internal-only, and `docs/cutover/v<X.Y.Z>.md` is
  required only for breaking changes per DOC-05. Read the
  `CHANGELOG.md` 0.34.0 section instead.
- mgf-fastapi 0.4.0 — sibling-local `CHANGELOG.md`.
- mgf-sqlalchemy 0.2.0 — sibling-local `CHANGELOG.md`.
- mgf-alembic 0.3.0 — sibling-local `CHANGELOG.md` (covers the
  `is_async` / `transaction_per_migration` kwargs in detail).

Other relevant context:

- [`FEEDBACK.md`](../../FEEDBACK.md) PAPER-35 — the consumer
  evidence (PlasmaMapper's 2026-05-18 walk through 4 sibling
  CHANGELOGs) that motivated this doc shape.
- [`docs/standards/DOCUMENTATION.md`](../standards/DOCUMENTATION.md)
  DOC-05 — the per-release-cutover MUST. Federation cutover is the
  *aggregate* shape that complements (does not replace) the
  per-release cutover.
- [`README.md`](README.md) — the `docs/cutover/` directory
  conventions. Federation-cutover docs follow the same archival
  rules as regular cutovers (permanent record, not moved to
  `docs/archive/`).
