Universal Services Superset¶

The Universal Services superset is FCC's canonical consumer-side list of every cross-ecosystem service FCC calls, with drift policy and fallback behaviour recorded for each. The authoritative document is docs/ecosystem/universal-services.md (shipped in v1.5.0); this diagram is a structural view of the same 22 entries organized as 5 functional tiers. ADR-009 captures the decision to adopt a superset-first principle: FCC contributes additively; the Research Center (RC) rationalizes duplicates and owns deprecation debates in its own ADR repo.

Each entry carries four contract fields — Definition, SLA, Drift policy, Fallback — so every consumer change is audit-ready. The diagram below groups the 22 entries by tier, with each group showing the services in it and the governing contract style.

classDiagram
    class UniversalServicesDoc {
        <<docs/ecosystem/universal-services.md>>
        +22 entries
        +5 tiers
        +superset-first principle
        +contributed by FCC
        +rationalized by RC
    }

    class ServiceEntry {
        <<record shape>>
        +definition : str
        +sla : str
        +drift_policy : str
        +fallback : str
    }

    class Tier1_RCVendoredConfig {
        <<Tier 1 — Authoritative Registries>>
        1. ecosystem_projects.yaml
        2. port_allocation.yaml
        3. namespace registry (11 ecosystems)
        drift: SHA-256 sentinel
        fallback: vendored copy
    }
    class Tier2_TelemetryTraffic {
        <<Tier 2 — Telemetry + Traffic Plumbing>>
        4. OpenTelemetry collector config
        5. UX REST gateway :8200
        6. PAOM decode endpoint
        drift: SemVer minor on schema
        fallback: in-process default
    }
    class Tier3_DomainSubsystems {
        <<Tier 3 — Domain Subsystems>>
        7. Distiller cross-vertical harvest
        8. PHOENIX patent coordination
        9. LYRA graph-of-thought (v1.5.0)
        10. POLARIS long-term archive (v1.5.0)
        11. ice_ext Model primitives
        drift: mock-first bridge
        fallback: functional mock bridge
    }
    class Tier4_CrossCutGovernance {
        <<Tier 4 — Cross-Cut Governance>>
        12. Zachman cross-cut (6x6)
        13. SAFe reconciliation
        14. Open-Science reference (OPEN-SCI-NNN)
        15. Federation namespace registry
        16. Ecosystem-integration-tests suite
        drift: ADR on breaking change
        fallback: degraded-mode
    }
    class Tier5_FccInfraAndSiblings {
        <<Tier 5 — FCC infrastructure + sibling optionals>>
        17. fcc.api.archive (POLARIS surface)
        18. fcc.api.knowledge (LYRA surface)
        19. fcc.api.rag (GraphRAG surface)
        20. fcc.api.collaboration (CRDT surface)
        21. fcc.api.federation (bidirectional)
        22. sibling plugin ecosystem (Athenium, Mnemosyne)
        drift: SemVer 1.x guarantee
        fallback: plugin absent = no capability
    }

    class RCRegistry {
        <<upstream authority>>
        +Research Center
        +rationalizes duplicates
        +owns deprecation ADRs
    }

    class FCCFramework {
        <<consumer>>
        +contributes additively
        +wires consumers
        +documents fallbacks
    }

    UniversalServicesDoc "1" *-- "5" Tier1_RCVendoredConfig : tier 1
    UniversalServicesDoc "1" *-- "5" Tier2_TelemetryTraffic : tier 2
    UniversalServicesDoc "1" *-- "5" Tier3_DomainSubsystems : tier 3
    UniversalServicesDoc "1" *-- "5" Tier4_CrossCutGovernance : tier 4
    UniversalServicesDoc "1" *-- "5" Tier5_FccInfraAndSiblings : tier 5
    Tier1_RCVendoredConfig ..> ServiceEntry : each is
    Tier2_TelemetryTraffic ..> ServiceEntry : each is
    Tier3_DomainSubsystems ..> ServiceEntry : each is
    Tier4_CrossCutGovernance ..> ServiceEntry : each is
    Tier5_FccInfraAndSiblings ..> ServiceEntry : each is
    RCRegistry --> UniversalServicesDoc : rationalizes
    FCCFramework --> UniversalServicesDoc : contributes

Four drift-policy patterns show up in the table. SHA-256 sentinel (Tier 1) pins a vendored copy byte-exactly against the upstream master — CI fails on drift when RC is checked out locally, skips gracefully when it isn't. SemVer minor (Tier 2, Tier 5) guarantees backward compatibility within a major and windows any breaking change across at least one release. Mock-first bridge (Tier 3) wires the sentinel (polaris_available(), lyra_available(), etc.) up front so the live adapter slots in without any consumer-side churn — this is the pattern that made the v1.5.0 POLARIS + LYRA promotion zero-churn. ADR on breaking change (Tier 4) treats cross-cut governance artifacts as non-versioned but ADR-gated.

The 22 entries divide cleanly into a consumption surface (Tiers 1-3), a governance surface (Tier 4), and a contribution surface (Tier 5). The consumption surface is where FCC pulls; the governance surface is where FCC coordinates with peers; the contribution surface is what FCC publishes back for siblings to consume. Keeping the three surfaces in a single doc is what enables the cross-ecosystem alignment audits the Research Center runs each release.

Key contracts¶

Superset-first principle — consumers add rows; the maintainer (RC) rationalizes.
ServiceEntry shape — every row carries Definition / SLA / Drift policy / Fallback.
Tier 1 (4 entries) — RC-vendored authoritative config, SHA-256-pinned drift.
Tier 2 (3 entries) — telemetry + traffic plumbing (OTel collector, UX REST gateway :8200, PAOM decode).
Tier 3 (5 entries) — domain subsystems (Distiller, PHOENIX, LYRA, POLARIS, ice_ext); mock-first bridges.
Tier 4 (5 entries) — cross-cut governance (Zachman, SAFe, Open-Science refs, federation namespace registry, ecosystem-integration-tests).
Tier 5 (5 entries) — FCC's own contribution surface (fcc.api.archive, fcc.api.knowledge, fcc.api.rag, fcc.api.collaboration, fcc.api.federation) plus sibling plugin optionals.

Universal Services Superset¶

Key contracts¶

See also¶