# FEEDBACK — mgf-fedres

> Paper-tracking file for issues, friction, and requests against this sibling.
>
> **Where to file what:**
> - **Spine-specific** (a schema, the sync engine, a sync state, the `fedres`
>   CLI, the `SourceProvider` seam, the live/run-record wire formats) → file HERE.
> - **A consuming web's UI / behaviour** → that tool's repo: the federation
>   dashboard is `mgf-fed-web`; the testing/CI authority console is `mgf-test-web`.
> - **Federation-wide** → [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).
>
> **Discipline:** see DOCUMENTATION.md §FEEDBACK (FB-01..FB-05, DOC-13).

## §1 Process

1. **File freely.** Anyone hitting friction files a PAPER-NN under §2.
2. **Status flips** `OPEN` → `SHIPPED` / `DEFERRED` / `WONTFIX` / `MOVED`.
3. **Renumbering** never happens (FB-01).

## §2 Open feedback (active)

#### `PAPER-01` — Reference projectors hardcode the MGF registry shape (need a `RegistryAdapter` seam); README understates maturity

| Field | Value |
|---|---|
| Status | SHIPPED (2026-07-10) |
| Severity | 🟢 Low |
| Submitter | sooth family — cross-family reuse review |
| Submitted | 2026-07-01 |

- **Resolution (2026-07-10, queue sweep):** SHIPPED on branch
  `feedback/queue-sweep-2026-07-10`, both halves. **(A)** the `RegistryAdapter`
  seam exists: `src/mgf/fedres/projectors.py` now defines `RegistryEntry`
  (`{repo, lang, deps}`), `register_registry_adapter(name, fn)`, and a
  `REGISTRY_ADAPTERS` registry; the projector bodies consume the normalized
  entries, and the MGF-shaped loader (top-level `libraries`,
  `mgf.standard` package-data fallback) became the default-registered `mgf`
  adapter — nothing changes for mgf-standard. A second family registers its
  adapter and selects it via `[projectors.*] registry_adapter = "<name>"`;
  unknown names refuse loudly. Proven by
  `tests/test_projectors.py::test_second_family_registers_its_own_adapter`,
  which projects a sooth-shaped registry (`members`/`language`/`needs` keys)
  through a registered adapter with zero edits to the projector module, and
  `::test_unknown_registry_adapter_refuses_loudly`. **(B)** README Status now
  says "Built and tested (pre-alpha)" and lists what actually ships, keeping
  the genuine planning pointer for the consuming webs. Full suite: 73 passed;
  mypy --strict clean; `PUBLIC_API.json` regenerated for the two new names.

**Concern.** Two small warts, filed together because both sit on the same
"can a second family adopt this by *registering*, not *forking*?" seam.

**(A) The bundled reference projectors hardcode the MGF registry shape.** The
two Class-P projectors in `src/mgf/fedres/projectors.py`
(`architecture_projector`, `federation_projector`) bake in the mgf-standard
registry shape: they read a top-level `libraries` array and index each entry by
`repo` / `deps` / `lang`, and their shared `_load_libraries` fallback loads the
`mgf.standard` package's `_libraries.json` by name. A second family whose
registry has a different top-level shape or package name cannot register these
projectors as-is — it must copy the projector module and edit the keys.

**(B) The README understates maturity.** The Status section says "Planning /
pre-implementation," but the engine (the `generate` → `sync` cycle), the
`fedres` CLI, the reference projectors, and the schema set + validator are all
implemented, with passing tests under `tests/`.

**Why it matters.** `mgf-fedres` is the best-generalized repo in the fleet —
near family-agnostic, and explicitly built with a second family (the sooth /
Zig-language family) in mind. These two warts are the last things between "read
the README, register a loader" and real second-family adoption. (A) forces a
copy-paste fork of the projector — exactly the divergence the projector registry
seam exists to prevent — when a tiny registered adapter would do. (B) actively
deters adopters: a reader who takes the README at face value concludes there is
nothing to run and stops, even though the engine + CLI are built and tested (the
shipped modules under `src/mgf/fedres/` + their `tests/` show the engine + CLI
are real — the README status line trails the code).

**Concrete evidence.**

*(A) hardcoded MGF shape + package fallback —* `src/mgf/fedres/projectors.py`:
- `:43` — fallback hardwires the package:
  `text = (files("mgf.standard") / "_libraries.json").read_text(encoding="utf-8")`,
  and the error at `:45-48` instructs the user to "install mgf-common[standards]".
- `:59-60` — the registry shape is baked in:
  `libs = _load_libraries(provider, cfg).get("libraries", [])` /
  `repos = {lib["repo"] for lib in libs}`.
- `:63` and `:68-74` — nodes/edges index `lib["repo"]`, `lib.get("lang", "python")`,
  `lib.get("deps", {})` — the full MGF registry shape, inline.

*The seam already exists —* `src/mgf/fedres/generate.py`:
- `:72` — `PROJECTORS: dict[...] = {}`
- `:75` — `def register_projector(name, fn) -> None:` — a family *can* register its
  own projector; nothing forces a fork except that the two shipped projectors bundle
  the shape + loader together rather than behind an adapter.

*(B) README vs. reality —*
- `README.md:34` — "**Planning / pre-implementation.** The end-to-end plan and the
  authoritative specs,".
- Real engine modules under `src/mgf/fedres/`: `generate.py`, `sync.py`,
  `manifest.py`, `provider.py`, `cli.py`, `live.py`, `reader.py`, `validate.py`,
  `canonical.py`, `states.py`, `_schemas.py` (plus `schemas/` and `examples/`).
- Tests under `tests/`: `test_engine.py` (10 tests — the generate→sync cycle),
  `test_cli.py` (10), `test_projectors.py` (4), `test_schemas.py` (18) — 42 test
  functions.

**Suggested shape.** Two small, independent fixes.

**(A) Extract a tiny `RegistryAdapter`.** Add a one-callable seam that maps an
arbitrary registry JSON → a normalized view (`{repos, deps, lang}`, or directly
`{nodes, edges}`). The projector bodies consume the normalized view instead of
reaching into `lib["libraries"]` / `lib["repo"]` directly, and
`_load_libraries`'s `mgf.standard` fallback becomes the *default adapter's*
fallback. Ship the current mgf-shaped `architecture` + `federation` projectors as
the default-registered pair over the default MGF adapter — so nothing changes for
mgf-standard — while a second family REGISTERS its own adapter (or its own
loader) instead of copying the projector module.

**(B) Fix the README Status line.** State reality: the engine (generate→sync) +
the `fedres` CLI + the reference projectors + schemas/validator are built and
tested, not "Planning / pre-implementation." Keep the pointer to `docs/planning/`
for the consuming webs (`mgf-fed-web`, `mgf-test-web`), whose planning status is
genuine.

*Filed by the sooth family during a cross-family reuse review — mgf-fedres is the
spine sooth would adopt (add `fed-resources/` + register one sooth registry
adapter); these two warts are the only things between the README and that.*

#### `PAPER-04` — `test_status_value` enum too narrow for the supervisor's outcome vocabulary

| Field | Value |
|---|---|
| Status | SHIPPED (2026-07-10) |
| Severity | 🟡 Medium |
| Submitter | the Court — M2 Wave-2 P1 §1.6 (mgf-test-web outcome-fidelity work) |
| Submitted | 2026-07-04 |

- **Resolution (2026-07-10, queue sweep):** SHIPPED on branch
  `feedback/queue-sweep-2026-07-10`. `test_status_value`
  (`src/mgf/fedres/schemas/_common.schema.json`) and `TEST_STATUS_VALUES`
  (`src/mgf/fedres/states.py`) widened additively with `crashed`, `hung`,
  `quarantined` — verified against the supervisor's closed set
  (`mgf-test-supervisor/src/mgf/test_supervisor/records.py` `OUTCOMES`:
  passed/failed/error/skipped/hung/crashed/quarantined; the exact three values
  missing here). `unknown` stays the loud fallback and unknown values still
  fail closed. Additive enum ⇒ MINOR; `schema_version` stays `0.1` (every
  previously-valid payload remains valid). Proven by
  `tests/test_schemas.py::test_supervisor_outcomes_validate_natively`
  (crashed/hung/quarantined each validate as `test_run_record.result`) and
  `::test_unknown_outcome_still_fails_closed`; lock-step test
  `test_sync_states_match_schema` keeps Python and wire enums equal. Full
  suite: 73 passed; mypy --strict clean. mgf-test-web can now drop its
  `warden/outcomes.py` projection (heads-up drafted in
  `pending-feedback/mgf-test-web.md`).

**Pain:** the `test_run_record` schema clamps `result` to `pass|fail|error|skipped|unknown`
(`additionalProperties: false`), but the supervisor's real outcome vocabulary is
`passed/failed/error/crashed/hung/skipped/quarantined`. Consumers (mgf-test-web) must
project `crashed/hung→error` and `quarantined→skipped` for durable records, preserving the
verbatim outcome only in an `{"event":"outcome","note":…}` audit row — fidelity survives,
but only by convention, and any reader of the record's `result` field alone sees the
flattened value.

**Ask:** widen `test_status_value` with `crashed`, `hung`, `quarantined` (additive enum,
schema MINOR per the versioning rules) so run-records carry the supervisor vocabulary
natively; keep `unknown` as the loud fallback. mgf-test-web's mapping table
(`src/mgf/test_web/warden/outcomes.py`) is structured to drop its projection the moment
the schema widens.

## §3 Reviewer's meta-feedback

_None yet._

## §4 How to submit feedback

1. **Open a Codeberg issue** at <https://codeberg.org/magogi-admin/mgf-fedres/issues>.
2. **For a structured pain point**: file a PAPER-NN here as a PR that adds the entry to §2.

## §5 Cross-references

- [mgf-fed-web](https://codeberg.org/magogi-admin/mgf-fed-web) — the federation dashboard (consumer).
- [mgf-test-web](https://codeberg.org/magogi-admin/mgf-test-web) — ProofWarden, the testing/CI authority console (consumer).
- [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md) — federation-wide PAPERs.
