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.

A project the registry does not know is refused (L9)

Both reference projectors refuse to project a [project] id that is absent from the registry they read. fedres generate and fedres check exit nonzero, and the message names the id and the registry it was checked against, down to its content (for the fleet's CI path, e.g. mgf-standard 0.1.84 package data (mgf/standard/_libraries.json, sha256 32eb738b4fc8), generated 2026-09-03, 55 repos; one version number can ship many different registries, so the hash is the identity). Before this change the answer was an architecture.json with no nodes and no edges, with exit 0. The D25 pilot (flotilla-firecracker, renamed from mgf-vm-firecracker) sat in exactly that state, and its gate reported IN_SYNC.

The engine enforces it for every projector body, including family overrides. A graph-mode architecture projection that does not contain [project] id as a node is refused by generate itself, whichever function produced it, so a projector registered through register_projector / $MGF_FEDRES_PROJECTORS cannot bring the silence back. A federation override's own body is still responsible for the federation slot.

A project that is genuinely new, or renamed ahead of the registry release that will know it, states that choice in its source:

[projectors.architecture]
allow_unregistered = true   # not in the registry yet; remove once it is

[projectors.federation]
allow_unregistered = true

The declaration is recorded in generated/manifest.json as "allow_unregistered": ["architecture", "federation"]. fedres check holds the manifest to the declaration and says NOTE: projected under allow_unregistered on every run. The opt-in is refused once the project is registered, because a stale opt-in would silence the next rename. The release that registers the project changes its architecture projection anyway, so removing the line costs no extra regeneration. Only a TOML boolean counts. A manifest that records the opt-in needs fedres 0.5.1 or later to be read: fedres 0.5.0's closed manifest schema rejects the new property, so opt in only once 0.5.1 is on the index (see the CHANGELOG's [0.5.1] Compatibility note). A registry adapter can name its version by returning a RegistrySnapshot(entries, version) instead of a bare sequence.

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