# mgf-fedres

**The federation-resources spine** — the shared core that both **`mgf-fed-web`** (the
federation dashboard) and **`mgf-test-web` / ProofWarden** (the testing & CI authority
console) build on. Part of the Magogi Foundation federation, under the `mgf.*` namespace.

```
mgf-brand-web 0.2        CSS tokens + the operator-instrument layer
        |
mgf-fedres   <-- you are here   the shared spine
        |   schemas (all, incl. test_*) + version-aware reader + validator
        |   manifest + sha256 + canonical-JSON
        |   sync engine: shallow (manifest) + deep (regenerate -> diff, non-mutating)
        |   SourceProvider seam: DiskProvider (now) / PackageProvider (later)
        |   live/ NDJSON reader+writer + run-record writer
        |   the `fedres` CLI: status / check / generate / run --trace / tail + the gate
        |
        |-------------------------> mgf-fed-web   (federation console)
        +--> mgf-test-web           (warden + testctl in base; [web] = ProofWarden console)
```

## What this provides

- **`fed-resources/`** — the per-project directory convention: `generated/` (schema-governed,
  freshness-gated, committed), `feedback/` (authored rounds), `live/` (ephemeral NDJSON).
- **The sync truth model** — "in sync" means regenerating `generated/` yields byte-identical
  output; states are first-class (`IN_SYNC / STALE / TAMPERED / UNKNOWN / UNREADABLE /
  CHECKING / SYNCING / ERROR`), never blank.
- **The schemas** — one versioned, symmetric set (`schema_version 0.1`) shared by both tools.
- **The `fedres` CLI** — the deterministic, JSON-emitting contract surface the webs consume.

## The family-adapter seam (CIR-26)

The Class-P projectors (`architecture`, `federation`) read a *family registry*. A second
family whose registry has the same shape as MGF's just registers a **registry adapter**
(`register_registry_adapter(...)` + `[projectors.*] registry_adapter = "<name>"`). A family
whose projection differs more deeply — different layer semantics, a different graph mode —
needs a whole new projector **body**, and points a slot at it through the supported
override seam:

- **`register_projector(name, fn)` is REPLACE-capable by contract.** Registering a name that
  is already bound — *including* a built-in slot (`architecture` / `federation`) — replaces
  it, last-write-wins. Overriding a built-in is supported behavior, pinned by
  `test_register_projector_replaces_a_builtin_slot`.
- **`MGF_FEDRES_PROJECTORS` is the plugin path.** A colon-separated list of importable
  module paths. The CLI imports them *after* the built-ins register and *before* dispatch,
  so each module's import-time `register_projector(...)` calls win — no wrapper script:

  ```sh
  MGF_FEDRES_PROJECTORS=my_family.fedres_projectors \
    python -m mgf.fedres.cli -C /path/to/project check
  ```

  A named module that cannot be imported is a loud, named failure — never a silent
  fall-back to the built-ins.

The **Sooth family** is the first consumer of this seam: its adapters read
`SOOTH_LIBRARIES.json` (a `repos[]` / `ring` shape) and project a `ring-*`-layered graph,
reaching the stock CLI through `MGF_FEDRES_PROJECTORS` instead of an import-order wrapper.
The end-to-end contract is pinned by
`tests/test_projectors.py::test_sooth_shape_adapter_end_to_end_through_the_cli_env_hook`.

## Status

**Built and tested (pre-alpha).** The spine is implemented: the engine (the
`generate` → `sync` cycle), the `fedres` CLI (`status` / `check` / `generate` /
`run --trace` / `tail` / `session-close`), the reference projectors, and the
schema set + version-aware validator all ship under
[`src/mgf/fedres/`](src/mgf/fedres/), with passing tests under
[`tests/`](tests/). Pre-alpha means the `0.1` contracts may still move — not
that there is nothing to run.

The end-to-end plan and the authoritative specs, briefs, and reference
wireframes for the two consuming webs live in
**[`docs/planning/`](docs/planning/)** — *their* planning status is genuine:

- [`docs/planning/PLAN.md`](docs/planning/PLAN.md) — the approved end-to-end plan (both tools).
- [`docs/planning/mgf-fed-web/`](docs/planning/mgf-fed-web/) — spec + brief + dashboard wireframe.
- [`docs/planning/mgf-test-web/`](docs/planning/mgf-test-web/) — spec + brief + console wireframe.

## License

MIT © The Magogi Foundation
