Skip to content

ADR-009: Universal Services Coordination Pattern (Superset-First)

Date: 2026-04-22 Status: Accepted Decision-makers: FCC core maintainers · PHV (Pattern Harvester) persona Consulted: Research Center (NEXUS) — rationalization authority · OSC (Open-Science Curator) persona Informed: All ecosystem partners (AURORA, AOME, CONSTEL, PAOM, PHOENIX, Distiller, ice_ext)

Context and Problem Statement

By v1.5.0 the FCC ecosystem had accreted a long list of services it consumed — some from the Research Center (authoritative registries), some from visualization partners (AURORA/Sky Parlour), some from JV partners (Athenium, Mnemosyne), some from incubating projects (POLARIS, LYRA), and some from upstream standards (OpenTelemetry, Zachman, SAFe, Open-Science references).

Each service had its own SLA, drift policy, and fallback behaviour buried in release notes or coordination notes but not cross-referenced in any single document. When a consumer hit a service outage, the answer to "what does FCC expect from this service, and what is the degraded-mode fallback?" required reading 10+ files.

Worse, there was no principled answer to the question of duplication. If two services overlapped (e.g., namespace resolution via fcc.federation.namespace vs. the RC namespace registry), who decided whether to consolidate? The Research Center could only make that call if it had a clear picture of what FCC was actually consuming.

The problem was how to coordinate cross-ecosystem service evolution without either (a) centralising authority in one project or (b) letting drift accumulate silently.

Decision Drivers

  • Single source of truth for FCC consumer side. One document must answer "what does FCC call, and what's the fallback?" for every service.
  • Additivity. FCC entries must not require RC approval to land; the list grows as FCC evolves.
  • Governance boundary. RC must own rationalisation decisions — FCC lists what it consumes; RC decides whether to consolidate.
  • Uniform drift story. Every entry should have the same four fields: definition, SLA, drift policy, fallback.
  • KGSE promotion coordination. The document should drive promotion candidates for private FCC symbols into fcc.api.*.

Considered Options

  1. No central document. Continue with scattered coordination notes. Unmanageable at ecosystem scale.
  2. RC-owned catalog. Move all consumer-side documentation into RC. Centralises authority but requires cross-repo PRs for every FCC-side addition, slowing iteration.
  3. FCC-owned superset, RC-owned rationalization roadmap. FCC maintains the consumer superset as an additive document; RC decides which entries can be consolidated or deprecated. This is the "superset-first principle."
  4. Per-service ADRs only. Each service gets its own ADR; no central catalog. Loses the uniform drift story.

Decision

We adopt option 3: a superset-first universal services catalog at docs/ecosystem/universal-services.md, delivered in v1.5.0.

The catalog has four tiers:

  • Tier 1 — Authoritative Registries (Research Center): RC ecosystem registry, RC port allocation registry, RC namespace registry.
  • Tier 2 — Telemetry + Traffic Plumbing: OpenTelemetry collector, UX REST gateway, PAOM decode endpoint.
  • Tier 3 — Domain Subsystems: Distiller cross-vertical harvest, PHOENIX patent coordination, LYRA graph-of-thought, POLARIS long-term archive, ice_ext Model primitives.
  • Tier 4 — Cross-Cut Governance: Zachman cross-cut, SAFe reconciliation, Open-Science reference (OPEN-SCI-NNN), Federation namespace registry, ecosystem-integration-tests offline suite.

Every entry carries the same four fields:

  • Definition — what FCC calls and why.
  • SLA — what FCC treats as the contractual promise (availability, latency, schema stability).
  • Drift policy — how changes propagate (SemVer major / minor / patch; SHA-256 drift sentinel; preview-namespace window).
  • Fallback behavior — what FCC does when the service is unavailable or has drifted out of contract.

Three governance principles make the pattern work:

  1. Superset-first. FCC contributions are purely additive. When FCC adds a new consumer seam, the entry lands here first. No RC approval is required for an FCC-side addition.
  2. RC owns rationalization. If two services duplicate a capability, or if a service should be deprecated, that debate lives in RC's ADR repo — not in FCC's docs.
  3. Pattern-absorption-proposal workflow. When a pattern in a sibling repo looks upstream-worthy, PHV (Pattern Harvester, v1.4.4) files a GitHub issue using the pattern-absorption-proposal template (v1.4.1). RHL (Research Handoff Liaison) routes it to the right consuming persona chain; TLDR (Three-Layer Doc Reconciler) ensures the absorbed pattern lands in the right layer.

Every entry in the catalog lists its fallback behaviour uniformly (NoOp bridge, Mock bridge, vendored YAML with drift sentinel, or graceful degrade). This uniformity is the other half of the pattern — every service can fail without breaking FCC.

Consequences

Positive

  • Single source of truth. Any consumer can answer "what does FCC expect from this service?" by reading one document.
  • Uniform fallback. Every service has a graceful-degradation path; FCC continues to work when any subset of services is unavailable.
  • RC rationalization target. RC has a concrete catalog to rationalize over time. Duplicates can be flagged and consolidated on RC's own roadmap.
  • Additive contribution flow. FCC contributors don't wait on cross-repo coordination to add a consumer seam.
  • KGSE promotion signal. When an entry becomes stable, KGSE proposes promoting the corresponding private symbol into fcc.api.*.
  • Pattern-absorption channel. PHV + pattern-absorption-proposal issue template give siblings a well-defined way to propose upstream-worthy patterns.

Negative

  • Superset drift risk. The catalog must be maintained; stale entries erode trust. Mitigated by making the catalog part of the PR-review checklist when any fallback behaviour changes.
  • Governance boundary discipline. FCC must resist the temptation to rationalize on its own side; that authority stays with RC.
  • 22 entries and counting. As of v1.5.0 the superset has 22 entries across four tiers; consumers may find it long. The four-tier split + quick-field table mitigates.

Confirmation

  • docs/ecosystem/universal-services.md landed in v1.5.0 with 22 entries across 4 tiers (4 RC-vendored, 2 cross-repo handoffs, 5 FCC-provided APIs, 3 ecosystem-absorbed authorities, 6 FCC infrastructure, 2 sibling optional consumers).
  • .github/ISSUE_TEMPLATE/pattern-absorption-proposal.yml (v1.4.1) exercises the PHV + RHL + TLDR persona chain.
  • tests/test_ecosystem_registry_drift.py (v1.3.5.4) + ecosystem- integration-tests sibling offline suite together enforce the drift policies for Tier 1.
  • PHV persona (v1.4.4) + RHL + TLDR (v1.4.3) catalog named in universal-services.md §Superset-first principle.

References

  • docs/ecosystem/universal-services.md — the catalog itself
  • docs/ecosystem/alignment-status.md — living status dashboard
  • .github/ISSUE_TEMPLATE/pattern-absorption-proposal.yml — absorption workflow
  • tests/test_ecosystem_registry_drift.py — Tier 1 drift sentinel
  • CHANGELOG [1.5.0] §Universal Services coordination doc
  • CHANGELOG [1.4.4] §PHV persona (absorption channel owner)
  • New personas: PHV (Pattern Harvester), RHL (Research Handoff Liaison), TLDR (Three-Layer Doc Reconciler)
  • ADR-008 — POLARIS absorption (pattern-absorption in action)