# FEEDBACK — mgf-alembic

> Paper-tracking file for issues, friction, and requests against
> this sibling. Consumer projects (PlasmaMapper, inthewords,
> vm-vmanager-app, figrecovery, and any future adopter) file PAPER-NN
> entries here.
>
> **Where to file what:**
>
> - **mgf-alembic-specific** → file HERE.
> - **Federation-wide** (cross-sibling patterns, standards
>   proposals) → file in
>   [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).
>
> **Numbering convention:** paper numbers (`PAPER-NN`) are
> local to this repo. When a paper cross-references a
> federation-wide paper, the federation number appears in the
> metadata table as a cross-reference row.
>
> **Discipline:** see
> [mgf-standard/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md)
> §FEEDBACK (rules FB-01..FB-04, DOC-13).

---

## §1 Process

1. **File freely.** Any consumer hitting friction MUST file
   a PAPER-NN under §2. Don't wait for permission; the
   maintainer triages.
2. **Status flips** through `OPEN` → `SHIPPED` / `DEFERRED` /
   `WONTFIX` / `MOVED` as the paper resolves. A `SHIPPED` row
   carries a commit-SHA reference + release-version reference.
3. **Renumbering** never happens within this repo — papers
   keep their PAPER-NN forever (per FB-01).

---

## §2 Open feedback (active)

*No papers filed against this sibling yet. When a consumer hits
friction with mgf-alembic's public surface, file a PAPER-01
entry here using the shape from
[mgf-common/docs/recipes/feedback-md-template.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/recipes/feedback-md-template.md).*

---

## §3 Reviewer's meta-feedback

### From vm-vmanager-app (CLI/desktop consumer of mgf-common) — 2026-05-18

Cross-cutting observation derived from vm-vmanager-app's `0.34 → 0.38`
catch-up to mgf-common ([commit `212808f`](https://codeberg.org/magogi-admin/vm-vmanager-app/commit/212808f),
2026-05-18). I am NOT an mgf-alembic consumer — vm-vmanager-app has no
SQL migrations stack.

**The observation: potential scope-overlap with `mgf-common.versioned`.**
vm-vmanager-app uses `mgf.common.versioned.VersionedFileStore[T]` for
satellite-store versioning at 6 sites (CF-07 / LIFT-06 in
[`docs/STANDARDS_COMPLIANCE.md`](https://codeberg.org/magogi-admin/vm-vmanager-app/src/branch/main/docs/STANDARDS_COMPLIANCE.md)).
The shape `VersionedFileStore[T]` solves: a typed YAML/JSON file,
a `version:` field at the document root, an atomic write, a
versioned migration hook between versions. Conceptually adjacent
to what alembic does for DB schemas. A consumer who has "I have
a schema with a version field, please migrate me from N to N+1"
might land on either surface depending on which README they read
first.

**Implication for mgf-alembic.** Publish a clear scope
delineation up front:

- **mgf-alembic = DB-schema migrations only.** (Not for typed
  file-store versioning. Not for YAML config migrations.)
- **For typed file-store versioning, see
  `mgf-common.versioned.VersionedFileStore[T]`.**

This single statement at the top of the mgf-alembic README (and
mirrored in mgf-common.versioned's docstring) would prevent the
class of consumer confusion where both surfaces look applicable
for "I have a schema, I have a version, please migrate me." The
federation contract's `_check_federation_contract` audit step
might also want to grow a "are you using the right primitive
for your use case?" hint — but that's a much larger ask; the
README statement is the cheap immediate fix.

- **Resolution:** 2026-07-10 queue sweep — the cheap immediate fix
  is SHIPPED (this commit, branch `feedback/queue-sweep-2026-07-10`):
  `README.md` now carries a "Scope — DB-schema migrations only"
  blockquote directly above "What this provides", stating the
  delineation verbatim (DB-schema migrations only; typed file-store /
  YAML-config versioning → `mgf.common.versioned.VersionedFileStore[T]`)
  and cross-referencing this §3 entry. Verified the README previously
  had no scope statement (`grep -in "versioned\|scope\|not for"
  README.md` → no hits before the change). The two follow-on asks
  live outside this repo and are NOT shipped here: mirroring the
  statement in `mgf-common.versioned`'s docstring (drafted to
  mgf-common via `pending-feedback/mgf-common.md` in this commit)
  and the `_check_federation_contract` "right primitive" hint
  (explicitly called "a much larger ask" by the submitter — deferred
  with the same relay).
- **Status:** SHIPPED (README statement — the paper's named cheap
  fix); mgf-common mirror relayed via pending-feedback

---

## §4 How consumers submit feedback

1. **Open a Codeberg issue** at
   <https://codeberg.org/magogi-admin/mgf-alembic/issues> if
   you have a quick question. Maintainer triages.
2. **For a structured pain point**: file a PAPER-NN here as a PR
   that adds the entry to §2.
3. **For AI-agent-driven consumer sessions**: see your project's
   `docs/CLAUDE.md` auto-block (managed by `mgf-common catch-up`)
   — the `feedback-discipline` section spells out where to file
   what.

---

## §5 Cross-references

- [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
  — federation-wide PAPERs.
- [mgf-standard/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md)
  — FEEDBACK discipline rules.
