Object Model vs Federated Model¶

The object-model layer (src/fcc/objectmodel/base.py:18, src/fcc/objectmodel/facade.py:14) provides a protocol-based abstraction for any domain entity a project wants to expose through FCC — a ModelFacade offers statistics, search, and full-record retrieval over one or more generic RepositoryProtocol[T] instances. The federation layer (src/fcc/federation/entities.py:12, src/fcc/federation/entities.py:64) lifts that abstraction up to the cross-project plane: a FederatedEntity carries a canonical id resolved across namespaces, and a CrossProjectAssessment rolls up readiness scores across multiple participating facades. The diagram below shows how the local object model feeds federated resolution without collapsing the two layers into one.

The diagram below details the object-model protocols alongside the federation entities that consume them.

classDiagram
    class DomainEntity {
        <<interface>>
        +id : str
        +to_dict() dict
    }

    class RepositoryProtocol~T~ {
        <<interface>>
        +add(entity : T)
        +get_by_id(id : str) T
        +get_all() list
        +count() int
        +__iter__()
        +__len__()
        +__contains__(id : str) bool
    }

    class ModelFacade {
        <<abstract>>
        +name : str
        +version : str
        +stats()*
        +search(query, limit)*
        +get_full(entity_id)*
        +to_dict()*
    }

    class VocabularyMapping {
        <<frozen dataclass>>
        +source_term : str
        +target_term : str
        +namespace : str
    }

    class FederatedEntity {
        <<frozen dataclass>>
        +local_id : str
        +namespace : str
        +canonical_id : str
        +resolved : bool
        +confidence : float
        +source_vocabulary : str
        +properties : dict
    }

    class EntityResolver {
        +__init__(mappings)
        +add_mapping(mapping)
        +resolve(local_id, source_namespace, target_namespace) FederatedEntity
    }

    class CrossProjectAssessment {
        <<frozen dataclass>>
        +project_assessments : dict
        +cross_project_score : float
        +federation_readiness : str
        +vocabulary_coverage : float
        +recommendations : list
    }

    ModelFacade "1" o-- "1..*" RepositoryProtocol~T~ : exposes
    RepositoryProtocol~T~ ..> DomainEntity : parameterised by
    EntityResolver "1" o-- "1..*" VocabularyMapping : indexes
    EntityResolver "1" ..> "0..*" FederatedEntity : produces
    FederatedEntity "1" --> "1" VocabularyMapping : resolved via
    CrossProjectAssessment "1" --> "1..*" ModelFacade : assesses

Reach for the object-model protocols when a project wants to expose its own entities through FCC without adopting any particular ORM or storage layer; the Protocol-typed repository makes any iterable-with-lookup structure a valid backing store. Reach for the federation layer only when cross-project identity becomes a concern — for example, when two ecosystem projects need to agree that mnemosyne:Workflow#42 and athenium:Process#17 are the same canonical entity. The CTOFacadeAdapter (in cto_bridge.py) is the recommended extension point for wrapping an external CTO-backed model.

Because FederatedEntity is frozen and carries a confidence score, federation consumers can choose to treat resolution as probabilistic: a recommended threshold lives in the CrossProjectAssessment.recommendations list rather than baked into the resolver itself.

Key contracts¶

DomainEntity — minimal Protocol requiring only an id property and a to_dict() method; the universal type parameter for repositories.
RepositoryProtocol[T] — generic Protocol for add, get-by-id, iterate, count, and membership; does not mandate any persistence model.
ModelFacade — abstract base class offering stats, search, get_full, and to_dict over one or more repositories.
VocabularyMapping — frozen record mapping a source term to a target term inside a named namespace.
FederatedEntity — frozen record carrying both the local id and the resolved canonical id with a confidence score.
EntityResolver — holds a set of VocabularyMapping instances and produces FederatedEntity instances via resolve().
CrossProjectAssessment — frozen roll-up across multiple facades with an aggregate score, readiness label, vocabulary-coverage percentage, and recommendations.

Object Model vs Federated Model¶

Key contracts¶

See also¶