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.

Where a projector's inputs come from (and why it matters)

generated/ is byte-pinned and freshness-gated, so every input a projector reads is part of that gate. An input that moves without the project moving turns the project's fedres check RED through no change of its own. Both reference projectors have been walked back off such an input, one at a time:

• architecture (0.3.0) — scoped to the project's own dependency closure instead of emitting a copy of the whole roster, so a member joining the roster that this project does not depend on leaves the file byte-identical.
• federation (0.5.0) — reads pinned_at from the project's own dependency manifest, not from the registry's copy of it. Measured across mgf-standard v0.1.75→v0.1.84 on the 36 carriers: 23 (release, repo) staling events before, 0 after. The registry is still consulted for exactly one thing — which names are federation siblings — because nothing local can answer that.

[projectors.federation] coupling_source selects the manifest reader: auto (default — pyproject.toml, then build.zig.zon), pyproject, zig, or none. A project whose declared source is missing is a loud failure; there is deliberately no fall-back to the registry, because a silent one would re-open this exact coupling for the repos nobody checks. none states "this project declares no coupling" in a committed, reviewable line. register_coupling_reader(name, fn) mirrors register_registry_adapter for a family that declares dependencies in some other manifest.

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

Apache-2.0 © The Magogi Foundation