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:

  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/, with passing tests under 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/ — their planning status is genuine:

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

License

MIT © The Magogi Foundation