Skip to content

Adopting the Universal Services Superset

The universal services document is FCC's canonical list of ecosystem-wide plumbing — RC-vendored registries, cross-repo handoffs, FCC public APIs, absorbed authorities (POLARIS + ice_ext patterns), FCC infrastructure, and sibling-project optionals. This tutorial walks downstream consumers (PAOM, ice_ext, the 10 constellation vocabularies, ATHENIUM, MNEMOSYNE, and future consumers) through adopting the superset without rewiring everything at once.

You will end this tutorial with:

  • A consumer-side inventory of every universal-service entry you call or could call.
  • An "own / adopt / optional" classification per entry.
  • A sequenced migration plan that starts with FCC public APIs and ends with cross-cut governance.
  • Optional adoption of LaneRouter + OpenTelemetry orchestration.
  • Familiarity with the pattern-absorption-proposal workflow so you can propose future additions to the superset yourself.

What the superset is

The universal services superset lives at docs/ecosystem/universal-services.md and is organised into four tiers:

  • Tier 1 — Authoritative Registries (3 services). RC-vendored ecosystem_projects.yaml, port_allocation.yaml, and namespace registry.
  • Tier 2 — Telemetry + Traffic Plumbing (3 services). OpenTelemetry collector, UX REST gateway (port 8200), PAOM decode endpoint.
  • Tier 3 — Domain Subsystems (5 services). Distiller cross-vertical harvest, PHOENIX patent coordination, LYRA graph-of-thought, POLARIS long-term archive, ice_ext Model primitives.
  • Tier 4 — Cross-Cut Governance (5 services). Zachman cross-cut, SAFe reconciliation, Open-Science references, Federation namespace registry, ecosystem-integration-tests offline suite.

That is 16 explicitly numbered services. The "superset" framing means the list is deliberately larger than any single consumer strictly needs — RC rationalises duplicates over time, and every service entry documents a fallback so your consumer is never blocked when a service is absent.

A useful mental grouping across categories:

Category Count Example entries
RC-vendored registries 3 Tier 1 entries #1–#3
Cross-repo handoffs 3 PHOENIX patent coord, ice_ext Models, SAFe
FCC public APIs 3 UX REST, PAOM decode, integration-tests
Absorbed authorities 3 POLARIS archive, LYRA graph-of-thought, Distiller
FCC infrastructure 2 OpenTelemetry collector, Zachman cross-cut
Sibling optionals 2 Federation namespace, Open-Science refs

Why it matters

Before the superset, every consumer hand-wired integrations with each ecosystem partner through bespoke code paths. Three symptoms:

  1. Integration complexity. A constellation vertical needed to understand ice_ext, POLARIS, PHOENIX, RC, and PAOM individually.
  2. Drift. When RC renamed a port, every consumer learned separately.
  3. Governance gaps. No single place documented the consumer's obligations + fallbacks.

The superset turns every service entry into a contract with:

  • A Definition — what FCC calls and why.
  • An SLA — availability + latency + schema stability.
  • A Drift policy — how changes propagate (SemVer, SHA-256 sentinel, preview window).
  • A Fallback behavior — what happens when the service is absent or has drifted.

The superset-first principle then governs contributions: FCC consumers add entries additively; RC rationalises duplicates in its own roadmap. This is ADR-009 Universal services coordination in practice.

Step 1 — Inventory current integrations

Run through the 16 numbered services and classify each against your consumer:

## My-Consumer universal-services inventory

| # | Service | Used today? | Plan for v1.5? |
|---|---|---|---|
| 1 | RC ecosystem_projects.yaml | no | adopt |
| 2 | RC port_allocation.yaml | yes (bespoke) | adopt |
| 3 | RC namespace registry | no | optional |
| 4 | OpenTelemetry collector | yes | keep |
| 5 | UX REST gateway | no | optional |
| 6 | PAOM decode | no | optional |
| 7 | Distiller harvest | yes (via plugin) | keep |
| 8 | PHOENIX patent coord | no | optional |
| 9 | LYRA graph-of-thought | yes (preview imports) | migrate to stable |
| 10 | POLARIS long-term archive | yes (preview imports) | migrate to stable |
| 11 | ice_ext Model primitives | yes | keep |
| 12 | Zachman cross-cut | yes | keep |
| 13 | SAFe reconciliation | no | optional |
| 14 | Open-Science references | no | optional |
| 15 | Federation namespace | yes | keep |
| 16 | ecosystem-integration-tests | no | adopt |

Do this honestly. "Used today via bespoke code path" counts as "yes" — the migration is what replaces it with the superset-compliant call.

Step 2 — Classify every entry

For each row, pick one of four dispositions:

  • Own — your consumer produces the service (rare; usually only RC does this, but constellation verticals may own Tier 3 entries occasionally).
  • Adopt — your consumer calls the service + will follow the superset-compliant path.
  • Optional — your consumer does not call it today + may choose to later. Declare the intention so RC can plan for it.
  • Exempt — the service does not apply to your consumer (e.g. SAFe for a single-team library). Document why.

A useful outcome at this step is a shared spreadsheet with every consumer's disposition per row — this becomes the RC rationalisation input.

Step 3 — Migration order

The dependency order across tiers is:

  1. FCC public APIs first (Tier 2 UX REST, Tier 3 LYRA + POLARIS, Tier 3 ice_ext Models). Most SemVer-stable + lowest risk.
  2. Infrastructure second (Tier 2 OpenTelemetry, Tier 4 integration-tests). Wires in parallel to your existing observability
  3. CI.
  4. Coordination last (Tier 1 registries, Tier 4 Zachman + SAFe + Open-Science + Federation + PHOENIX). These require agreement with RC + sibling consumers.

3a — FCC public APIs

Start with POLARIS + LYRA if you used preview imports — see upgrading-consumers-to-v1_5_stable.md for the full migration.

Typical new-consumer adoption pattern for the bridges:

from fcc.api import get_polaris_bridge, get_lyra_bridge

polaris = get_polaris_bridge()  # live if ice_ext installed; mock otherwise
lyra = get_lyra_bridge()        # mock by default; live when lyra ships

# Full protocol works on both live + mock
archive_id = polaris.push_archive("/path/to/manifest.yaml")
thoughts = lyra.graph_of_thought_query("persona", depth=2)

The availability-sentinel pattern means your consumer does not branch on which backend is active — the mock satisfies the full protocol.

3b — Infrastructure

Install the OpenTelemetry extra + point your consumer's OTel configuration at the collector RC specifies:

pip install "fcc-agent-team-ext[otel]>=1.5.0,<2.0.0"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-collector:4317"

Wire tracing into your consumer's entry points using FCC's instrument_* helpers. See Step 6 of integrating-fcc-into-mature-codebase.md for details.

Register for the ecosystem-integration-tests offline suite:

git clone https://github.com/rollingthunderfourtytwo-afk/ecosystem-integration-tests /opt/ecosystem-integration-tests
cd /opt/ecosystem-integration-tests
pytest -q  # 49 offline contract tests; should pass with no network

Add make ecosystem-check (or equivalent) to your consumer's Makefile so CI runs it when the sibling repo is available + skips gracefully otherwise.

3c — Coordination

Vendor the RC registries into your consumer with the SHA-256 drift sentinel pattern:

# scripts/check_registry_drift.py
import hashlib
from pathlib import Path

FCC_VENDORED = Path("src/my_consumer/data/ecosystem/ecosystem_projects.yaml")
RC_MASTER = Path("/opt/research_center_ext/ecosystem_projects.yaml")

if not RC_MASTER.exists():
    print("RC not checked out locally — skipping drift check")
    raise SystemExit(0)

vendored_hash = hashlib.sha256(FCC_VENDORED.read_bytes()).hexdigest()
master_hash = hashlib.sha256(RC_MASTER.read_bytes()).hexdigest()

if vendored_hash != master_hash:
    print(f"DRIFT DETECTED: vendored {vendored_hash} != master {master_hash}")
    raise SystemExit(1)

When RC is not checked out, your drift check skips gracefully — this is how FCC itself handles it in tests/test_ecosystem_registry_drift.py.

For Zachman cross-cut, declare your custom personas with a zachman_cell: attribute. For Open-Science references (OPEN-SCI-NNN), declare open_science_refs: in any persona that produces or consumes FAIR artifacts.

Step 4 — Pattern-absorption-proposal workflow

When your consumer discovers a capability that should be in the superset but is not, propose it. The v1.4.1 absorption-proposal issue template in .github/ISSUE_TEMPLATE/ (refreshed in v1.5.1) is the entry point.

The chain runs through three personas:

  1. PHV (Privacy Handoff Validator) — validates the proposal does not leak data across boundary trust zones.
  2. RHL (Release Handoff Liaison) — confirms the proposal fits a future FCC release window + the SemVer envelope.
  3. TLDR (Too-Long-Didn't-Read summarizer) — produces the final decision-grade summary that RC uses in its roadmap meeting.

A typical proposal lifecycle:

  1. Consumer opens an issue using the pattern-absorption-proposal.yml template describing the consumer-side pattern, the cross-ecosystem value, and the proposed contract shape.
  2. PHV reviews within a release cycle (typically a week or two).
  3. RHL assigns a target FCC release if accepted — usually the next minor release.
  4. The new entry lands in docs/ecosystem/universal-services.md as an additive contribution (per superset-first principle).
  5. RC picks it up in the next roadmap meeting for rationalization.
  6. TLDR publishes a one-paragraph summary in the FCC CHANGELOG for the release that lands the entry.

This is how the universal services document grew from 15 numbered services at v1.5.0 to the current 16+ entries, and how new entries will land in v1.6.0+.

Example — adopting LaneRouter + OpenTelemetry orchestration

A medium consumer (a constellation vertical shipped at v0.2.0) went through this adoption in 2026-Q2. Their target was to push both their consumer-side simulation traces and their decision-workflow decode traces through the same FCC-provided OTel pipeline, lane-routed by the LaneRouter shipped in v1.4.2 (ADR-006).

Their work:

  1. Tier 2 #4 — OpenTelemetry collector. Installed [otel] extra, set OTEL_EXPORTER_OTLP_ENDPOINT.
  2. Tier 2 #6 — PAOM decode. Plugged PAOM at fcc>=1.5.0 pin; verified decode latency under 2s.
  3. Tier 4 #15 — Federation namespace. Registered the constellation namespace with the registry.
  4. LaneRouter wiring. Subscribed to PAOMBus + UXBus separately; each lane got its own tracer provider with distinct service name so the APM could slice per-lane.

Timeline: 3 days, of which half was APM-side config (not FCC's fault). Outcome: per-lane trace visibility in their existing APM with no new moving parts inside their simulation code.

Sample LaneRouter consumer wiring:

from fcc.messaging.bus import EventBus, LaneRouter
from fcc.observability.tracing import FccTracer

paom_bus = EventBus(name="paom")
ux_bus = EventBus(name="ux")
router = LaneRouter(paom=paom_bus, ux=ux_bus)

# Per-lane tracer — each lane gets a distinct service name in APM
paom_tracer = FccTracer(service_name="my-consumer-paom-lane")
ux_tracer = FccTracer(service_name="my-consumer-ux-lane")

paom_bus.subscribe_tracer(paom_tracer)
ux_bus.subscribe_tracer(ux_tracer)

Governance — superset-first principle

Two rules govern this whole surface:

  1. FCC contributes. FCC consumers add entries to docs/ecosystem/universal-services.md additively.
  2. RC governs. The Research Center rationalises duplicates + conflicts in its own roadmap.

That split is load-bearing. FCC cannot reconcile entries on its own because it is one consumer among many; RC is the only party with the cross-ecosystem vantage point. When you see duplication in the superset (two entries that seem to serve the same purpose), that is intentional — RC is the body that decides how to resolve it, not any individual consumer.

In practice this means:

  • Your consumer never deletes a superset entry unilaterally.
  • Your consumer always documents its disposition (own / adopt / optional / exempt) against every numbered entry.
  • Your consumer proposes additions through the pattern-absorption-proposal workflow, not by editing the universal services doc directly.
  • RC ratifies the final shape in its quarterly roadmap review.

Consumer role reference matrix

A quick lookup of which personas you will interact with at each step:

Superset area Key persona What they own on your side
RC registry adoption LAR (Lane Router Architect) Wiring the registry-backed port + namespace lookup into your runtime
OTel wiring OTO (OpenTelemetry Orchestrator) Per-lane tracer provider configuration
POLARIS bridge migration LTAS (Long-Term Archive Steward) Manifest discipline on the consumer side
LYRA mock + future live KGSE (Knowledge-Graph Serializer Elevator) Tracking when LYRA graduates to live backend
PHOENIX coordination IHL (Innovation Handoff Liaison), PCT (Patent Claim Tracer) Coordinating any IP-bearing contributions
SAFe reconciliation SFBI (SAFe-FCC Bridge Interpreter), SMC (SAFe Metrics Crafter) PI planning + portfolio reports
Open-Science refs OSC (Open-Science Curator) OPEN-SCI-NNN reference discipline
Governance absorption PHV (Privacy Handoff Validator), RHL (Release Handoff Liaison), TLDR (Too-Long-Didn't-Read summarizer), DAR (Decision Archaeologist) Proposal review + final summaries + historical decisions

Every one of these personas ships with a full R.I.S.C.E.A.R. spec + model card + EU AI Act classification. Read the persona pages before you open a proposal — knowing who will review your request is half the battle.

Coordination meeting cadence

Ecosystem consumers that adopt the universal services typically meet on a quarterly rhythm with RC. A working cadence:

  • Month 1 of the quarter. Consumer reviews the superset + updates its inventory + disposition table. Any new proposals are drafted.
  • Month 2 of the quarter. Proposals are submitted through the pattern-absorption-proposal.yml issue template. PHV + RHL + TLDR chain runs.
  • Month 3 of the quarter. RC roadmap meeting. Accepted proposals are assigned to the next FCC minor release; deferred proposals get an explanation + a target quarter.
  • End of quarter. Consumer consumes the resulting RC roadmap update + plans the next quarter's adoption work.

Consumers that keep this cadence find integration work predictable; consumers that skip it find themselves scrambling when FCC ships a change they did not plan for.

Checklist for "done"

  • Inventory spreadsheet filled out for every numbered entry.
  • Disposition classified for every entry (own / adopt / optional / exempt).
  • FCC public API adoption complete (POLARIS + LYRA stable imports, PAOM pinned, UX REST exercised in integration tests).
  • OpenTelemetry traces flowing from your consumer to the ecosystem collector.
  • ecosystem-integration-tests offline suite either installed locally or deferred with a tracking issue.
  • RC registries vendored (if Tier 1 adopted) with a SHA-256 drift check.
  • Zachman cells declared on every custom persona.
  • At least one pattern-absorption proposal drafted (even if not yet submitted) — this proves your team knows the workflow.
  • CHANGELOG entry for your consumer calling out the adoption.

Next steps