Federation Patterns¶

Federation in FCC is the mechanism that lets entities from different ecosystem projects refer to each other unambiguously and be resolved transitively through shared semantics. This chapter covers the namespace model, the entity resolver, and the change- tracking mechanism that makes federated lineage auditable.

Namespaces¶

The namespace registry at src/fcc/data/federation/namespace_registry.yaml lists 21 packaged namespaces (11 ecosystem + 10 vertical project scaffolds added in v1.3.0). The registry is canonical — if a namespace is not here, it cannot appear in a federated reference.

Namespace	Prefix	Domain
`fcc`	`fcc`	FCC Agent Team Framework
`paom`	`paom`	Portfolio & Artifact Object Model
`aome`	`aome`	Agentic Object Model Engine
`constel`	`constel`	Constellation metadata framework
`cto`	`cto`	CTO Object Model
`skyparlour`	`sp`	Sky-Parlour visualization
`distiller`	`dist`	Distiller NanoCube
`sentinel`	`sent`	Sentinel governance
`athenium`	`ath`	Athenium learning
`mnemosyne`	`mne`	Mnemosyne memory
`crucible`	`cruc`	Crucible test framework
`ophiuchus`	`oph`	Medical (HL7 FHIR, DICOM, IEC 62304)
`serpens`	`ser`	Medical (ICH E2B, EudraVigilance)
`libra`	`lib`	Finance (FIBO, EDM Council)
`crater`	`cra`	Finance (ISO 20022, BCBS 239, SR 11-7)
`scutum`	`scu`	Insurance (ACORD)
`norma`	`nor`	Insurance (Solvency II, IFRS 17)
`pyxis`	`pyx`	Energy (IEC 61970 CIM)
`vela`	`vel`	Energy (IEC 62325, CGMES, IEEE 1547)
`columba`	`col`	Government (DCAT-US 3.0)
`caelum`	`cae`	Government (NIEM 6.0, eIDAS 2.0)

Each namespace carries a canonical base_uri, a short prefix for QName-style references (paom:PORT-001), a semantic version, and a description. Namespaces without a registered facade are "scaffold" entries — reserved but not yet queryable.

Qualified names¶

A federated entity reference always has the form <prefix>:<id> — for example fcc:BC (Blueprint Crafter), paom:PORT-001 (PAOM Portfolio), cto:CONCEPT-1234 (CTO Concept). The parser at src/fcc/federation/entities.py normalises these into FederatedEntity frozen dataclasses that carry the prefix, local id, display name, and resolution metadata.

The `EntityResolver`¶

src/fcc/federation/resolver.py implements the resolver. Its public contract is small:

class EntityResolver:
    def register(self, entity: FederatedEntity) -> None: ...
    def resolve(self, qname: str) -> FederatedEntity | None: ...
    def resolve_through_mapping(
        self, qname: str, target_namespace: str
    ) -> FederatedEntity | None: ...
    def all_equivalents(
        self, qname: str
    ) -> list[FederatedEntity]: ...

resolve performs a direct lookup. resolve_through_mapping walks the vocabulary mappings from Vocabulary Mappings to find the equivalent entity in another namespace. all_equivalents returns the transitive closure of mapped entities.

The resolver filters by the 0.75 confidence threshold — mappings below that tier are ignored during resolution.

Resolution topology¶

The diagram below shows a typical three-hop resolution. A query for paom:PORT-001 is first resolved directly in the PAOM namespace, then its mapped equivalents are discovered in FCC (as a persona set) and then in CTO (as a concept). The resolver always returns the union, not the first match, so downstream consumers can choose their target namespace.

sequenceDiagram
    participant Q as Caller
    participant R as EntityResolver
    participant N1 as paom namespace
    participant M as MappingStore
    participant N2 as fcc namespace
    participant N3 as cto namespace

    Q->>R: resolve_through_mapping("paom:PORT-001", "fcc")
    R->>N1: lookup PORT-001
    N1-->>R: FederatedEntity(paom:PORT-001)
    R->>M: get_by_source("PORT-001")
    M-->>R: [mapping → fcc:BC (0.88)]
    R->>N2: lookup BC
    N2-->>R: FederatedEntity(fcc:BC)
    R-->>Q: FederatedEntity(fcc:BC)

    Q->>R: all_equivalents("paom:PORT-001")
    R->>M: transitive closure
    M-->>R: [fcc:BC, cto:CONCEPT-7, ...]
    R-->>Q: list[FederatedEntity]

The `FederationRegistry`¶

src/fcc/federation/registry.py is the central coordinator. It holds:

the NamespaceRegistry (loaded from YAML)
the MappingStore (loaded from the 20 vocabulary YAMLs)
the EntityResolver
a ChangeTracker for auditability

The registry is built once at startup and is the object the CLI, dashboards, and plugin hooks all share. Plugin authors should never construct their own registry — fetch the process-wide instance via federation.registry.get_default_registry().

Change tracking¶

src/fcc/federation/change_tracking.py records every registration, mapping addition, and resolution failure to an append-only log. The log is the source of truth for data-lineage audits — it is what the compliance pipeline consumes to answer "how did PAOM's PORT-001 come to be linked to FCC's BC?"

Each log entry carries:

Timestamp (UTC, ISO 8601)
Actor (plugin, user, or system)
Before state (if any)
After state
Mapping confidence (where applicable)

The log is written to .fcc/federation/changes.jsonl by default and can be pointed at a durable store (S3, GCS) via the fcc.federation.change_tracking.store config key.

Federation topology patterns¶

Three topology patterns are supported out of the box:

Star — one central FCC instance with N satellite ecosystem projects. All resolution flows through the centre. This is the default for v1.3.x.

Mesh — peer-to-peer resolution between ecosystem projects. Supported via the UnifiedFacade but requires every peer to publish a facade. This is the v1.4.0 ecosystem pivot target.

Hierarchical — a two-tier arrangement where vertical packs (Ophiuchus, Libra, Pyxis, etc.) resolve through their horizontal parent (FCC or PAOM) rather than directly.

The diagram below shows all three topologies with the same six-node example.

flowchart LR
    subgraph "Star (v1.3.x default)"
      S_FCC[fcc] --- S_P[paom]
      S_FCC --- S_A[aome]
      S_FCC --- S_C[constel]
      S_FCC --- S_O[ophiuchus]
      S_FCC --- S_L[libra]
    end
    subgraph "Mesh (v1.4.0 target)"
      M_FCC[fcc] --- M_P[paom]
      M_P --- M_A[aome]
      M_A --- M_C[constel]
      M_C --- M_O[ophiuchus]
      M_O --- M_L[libra]
      M_L --- M_FCC
    end
    subgraph "Hierarchical (vertical)"
      H_FCC[fcc] --- H_P[paom]
      H_P --- H_O[ophiuchus]
      H_P --- H_L[libra]
      H_FCC --- H_A[aome]
      H_A --- H_C[constel]
    end