Open Science -- v1.3.5.2 Addendum¶

This addendum extends the Open Science Demo, the Phase 14 Addendum, and the Phase 15 Addendum with the v1.3.5.2 cross-project FAIR audit scenario. Where Phase 15 introduced FAIR compliance backed by the unified knowledge graph for a single project, v1.3.5.2 scales the audit across three projects -- FCC, PAOM, and AOME -- and aggregates the result into a single cross-project assessment.

Scenario Overview¶

The scenario runs a FAIR audit across three project facades and produces a unified report that can be shared with reviewers, funding agencies, or partner institutions.

Project	Role in the Audit	Facade Class
FCC	Reference framework; owns FAIR rubric	`fcc_facade`
PAOM	Persona / agent / object model consumer	`paom_facade`
AOME	Ontology-heavy sister project	`aome_facade`

The `ModelFacade` Contract¶

Each project exposes a concrete ModelFacade that the audit uses as its single integration point. The facade surfaces three categories of information: model statistics, search, and full entity retrieval.

from fcc.objectmodel.facade import ModelFacade

class ProjectFacade(ModelFacade):
    def stats(self) -> dict: ...
    def search(self, query: str) -> list: ...
    def get_full(self, entity_id: str) -> dict: ...

The audit never imports a sister project's runtime classes directly. Facades are loaded through the registered VocabularyProviderPlugin pathway documented in the Distiller Bridge v1.3.5.2 Addendum.

Running the Cross-Project Assessment¶

Minimal Invocation¶

assess_cross_project accepts a list of facades and returns a single CrossProjectAssessment dataclass. The function computes three headline scores and a short list of recommendations.

from fcc.objectmodel.federation import assess_cross_project

assessment = assess_cross_project([fcc_facade, paom_facade, aome_facade])

print("Cross-project score:    ", assessment.cross_project_score)
print("Federation readiness:   ", assessment.federation_readiness)
print("Vocabulary coverage:    ", assessment.vocabulary_coverage)
print("Recommendations:        ", assessment.recommendations)

Score Semantics¶

Field	Range	Meaning
`cross_project_score`	0.0 -- 1.0	Overall federation quality
`federation_readiness`	0.0 -- 1.0	Readiness to deploy as a federated ecosystem
`vocabulary_coverage`	0.0 -- 1.0	Fraction of vocabulary overlap across projects

The headline score is a weighted combination that favours completeness (0.4), vocabulary coverage (0.3), and resolution score (0.3). See src/fcc/objectmodel/federation.py for the exact formulation, which also varies with the number of projects passed in.

FAIR Principle Mapping¶

v1.3.5.2 retains the Phase 15 FAIR rubric but evaluates each principle against all three facades simultaneously and records the best- available evidence source per project.

Principle	Evidence Source	FCC	PAOM	AOME
F1 -- Globally unique ID	Namespace registry	YES	YES	YES
F2 -- Rich metadata	Persona dimensions / object model	YES	YES	PARTIAL
F3 -- Searchable resource	`SearchIndex`	YES	YES	YES
F4 -- Metadata with ID	KG node attributes	YES	PARTIAL	YES
A1 -- Retrievable by ID	`ModelFacade.get_full()`	YES	YES	YES
A2 -- Metadata accessible	Facade protocol	YES	YES	YES
I1 -- Formal representation	OWL/RDF/SKOS serializers	YES	PARTIAL	YES
I2 -- FAIR vocabularies	`VocabularyMapping` coverage	YES	YES	PARTIAL
I3 -- Qualified references	Cross-namespace edges	YES	YES	YES
R1 -- Rich attributes	Model card completeness	YES	PARTIAL	PARTIAL

The "YES / PARTIAL / NO" grading is a readable projection of the underlying 0.0 -- 1.0 evidence score; thresholds are >= 0.85 for YES, 0.6 -- 0.85 for PARTIAL, and < 0.6 for NO.

Evidence Aggregation¶

Per-Project Evidence Packs¶

Each project contributes an evidence pack that is attached to the final report. A pack is a dict keyed by FAIR principle ID.

pack = {
    "F1": {"score": 0.98, "source": "namespace", "items": 11},
    "F2": {"score": 0.91, "source": "dimensions", "items": 56},
    # ...
}

Cross-Project Reconciliation¶

Where two projects disagree on the same entity, the report records both views and flags the discrepancy as a reconciliation candidate. A typical disagreement is a persona defined by FCC and consumed by PAOM but with a slightly different dimension profile.

Scenario	Reconciliation Action
Exact match on ID and content	No action
Match on ID, different content	Flag as `reconciliation.diff` event
Different ID, cross-namespace resolution succeeds	Record as alias; contributes to `vocabulary_coverage`
Different ID, no resolution	Flag as `federation.orphan` event

Reporting¶

Output Artefacts¶

The audit produces four artefacts suitable for sharing outside the engineering team.

Artefact	Format	Size (reference run)	Audience
Summary report	Markdown	~12 KB	Reviewers
Detailed evidence bundle	JSON	~240 KB	Auditors
FAIR radar chart	SVG	~18 KB	Publication-ready
Compliance evidence graph	JSON-LD	~90 KB	Tooling integration

Sample Summary¶

Cross-Project FAIR Assessment  --  2026-04-13

Projects:          fcc, paom, aome
Overall score:     0.89  (Strong)
Federation ready:  0.86
Vocab coverage:    0.74

Strengths:
  F1, A1, A2, I3  -- uniformly strong across all three projects
  F3, F4          -- strong in fcc and aome, partial in paom

Gaps:
  R1              -- PAOM model cards incomplete (sections missing)
  I2              -- AOME vocabulary mapping at 0.68, needs review
  F2              -- AOME dimension coverage at 0.71

Next actions:
  1. PAOM: generate remaining 12 model cards
  2. AOME: review vocabulary mappings for concept classes
  3. AOME: expand dimension profile definitions

Publication Pipeline Integration¶

The summary report and the radar chart are automatically picked up by the v1.3.2 publication pipeline when placed under publications/audits/. Running make pub-all produces a PDF rendering alongside the existing books and reference cards.

Event Integration¶

The audit emits events throughout its run. Downstream subscribers can act on these events in real time.

Event Type	Payload	Typical Handler
`fair.check.started`	`project_count`, `principle_count`	UI progress bar
`fair.principle.evaluated`	`principle_id`, `score`, `project`	Radar chart update
`fair.check.completed`	`overall_score`, `gaps`	Report generator
`cross_project.assessment.completed`	full `CrossProjectAssessment` dict	Dashboard refresh
`reconciliation.diff`	`entity_id`, `projects`, `fields`	Reconciliation queue

Running the Scenario Step-by-Step¶

Setup¶

from fcc.objectmodel.facade import ModelFacade
from fcc.objectmodel.federation import assess_cross_project
from fcc.objectmodel.examples import create_sample_model

# In a real run, these are loaded via VocabularyProviderPlugin.
# For the reference demo run, use the bundled sample facades.
fcc_facade  = create_sample_model("fcc")
paom_facade = create_sample_model("paom")
aome_facade = create_sample_model("aome")

Assessment¶

assessment = assess_cross_project([fcc_facade, paom_facade, aome_facade])

assert 0.0 <= assessment.cross_project_score <= 1.0
assert 0.0 <= assessment.federation_readiness <= 1.0
assert 0.0 <= assessment.vocabulary_coverage <= 1.0

Evidence Graph¶

from fcc.compliance.evidence_graph import build_compliance_evidence_graph

# Add the cross-project evidence on top of the per-project graphs.
graph = build_compliance_evidence_graph(
    projects=[fcc_facade, paom_facade, aome_facade],
    cross_project_assessment=assessment,
)
graph.serialize("./publications/audits/fair-xproj-2026-04-13.jsonld")

Interpreting the Numbers¶

What "Strong" Looks Like¶

A cross_project_score above 0.85 indicates that the three projects share enough vocabulary, metadata, and resolvable references to function as a single federation for user-facing queries. A score between 0.70 and 0.85 indicates usable federation with known gaps, and below 0.70 indicates that the federation should not be relied upon for compliance or regulatory use cases until gaps are closed.

What "Vocabulary Coverage" Measures¶

vocabulary_coverage is the Jaccard overlap between the declared vocabularies of the participating projects. It is a pure overlap measure and does not weight importance. Two projects with perfectly overlapping but very small vocabularies can achieve a coverage of 1.0 without being useful for broad federated queries -- always read the coverage number alongside the per-project vocabulary size.

Typical Improvement Loop¶

The recommended cycle for raising the cross-project score is:

Pick the lowest-scoring FAIR principle.
Identify the project that pulls it down.
Apply the project-local remedy (model card, vocabulary mapping, or dimension profile fill-in).
Re-run the audit.
Stop when all three projects are at PARTIAL or above for every principle.

Tips¶

Always run the audit against a clean KG. A stale KG can mask real gaps and produce an optimistic score.
The cross-project audit is safe to run in CI. The reference run completes in under 30 seconds against the bundled sample facades.
When evaluating against real sister projects, pin the sister- project version in the audit config -- a moving target makes it very hard to compare runs across dates.