Skip to content

Integration Risk and Mitigation

This page catalogues the architectural risks that most commonly show up in FCC integration reviews and pairs each one with the built-in mitigation FCC offers. Each risk is stated at the altitude an architect cares about — what could break, what the cost of breakage is, and what control FCC gives you.

Risk 1 — Version drift across the ecosystem

What could break. Your application pins FCC v1.3.5.3; an upstream consumer (AOME, say) ships against FCC v1.4.0. A schema change between the two releases breaks cross-project entity resolution silently — the plugin loads, but emits empty mapping results.

Cost of breakage. Silent correctness failure is the worst kind; errors surface downstream as mysterious missing data rather than as stack traces.

Mitigations FCC offers.

  • Trust tier model. Tier 1 consumers commit to contract tests that break CI on drift; Tier 2 consumers are version-pinned and track releases. See System Context.
  • Vendored SHA-pinned YAML. The upstream NEXUS registries are vendored under src/fcc/data/ecosystem/ and SHA-pinned in a CI contract test. Drift is detected at PR time.
  • Semantic-version discipline. Adding a plugin type is MINOR; removing or renaming one is MAJOR. The 4-part PEP 440 scheme signals breakage intent at release time.

Risk 2 — Plugin discovery failures in production

What could break. An entry point is declared in pyproject.toml but the sister package is not in the production wheel. The PluginRegistry silently skips the plugin; features that depend on it disappear.

Cost of breakage. Medium. Usually surfaces in staging once integration tests run, but occasionally slips to production if integration coverage is thin.

Mitigations FCC offers.

  • Graceful-degradation contract. VocabularyProviderPlugin authors are required to return an empty get_class_map() when the source package is absent rather than raising ImportError. Testing for this path is covered in For Developers — Testing Guide.
  • Admin health reader. fcc.admin.readers.PluginReader.health() returns a per-plugin status map. Wire it into your deployment's readiness probe and you will catch missing plugins before they serve traffic.
  • Plugin dependency manifest. src/fcc/data/ecosystem/plugin_dependencies.yaml declares which plugins depend on which sister packages; CI asserts the manifest matches reality.

Risk 3 — Compliance drift under regulatory change

What could break. The EU AI Act enters a new enforcement phase (e.g. high-risk operator obligations in 2026–2027). Your organisation needs to demonstrate documented compliance for all AI-assisted workflows. An FCC-backed workflow whose persona classifications are out of date fails the audit.

Cost of breakage. Very high. Regulatory non-compliance is a board-level risk.

Mitigations FCC offers.

  • Compliance pipeline. CompliancePipeline walks every persona against the 256+ EU AI Act requirements and the 29 NIST AI RMF subcategories on every release; the ComplianceReport is a structured artifact you can archive per release.
  • Evidence graphs. build_compliance_evidence_graph() emits a JSON-LD graph linking requirements to personas to artifacts — the defensible paper trail for audit.
  • Pluggable regulation. Adding a new regulation (DORA, NIS2, ISO 42001) means shipping a new RequirementRegistry file; the auditor code does not change. See the Logical View's compliance and governance diagram.

Risk 4 — Governance gate bypass

What could break. A developer adds a new persona or workflow that bypasses one of the 58 quality gates (e.g. the hard-stop gate on PII handling). The artifact ships, and an audit surfaces the gap months later.

Cost of breakage. High when the gate is constitutional (hard-stop tier); medium when mandatory; low when preferred.

Mitigations FCC offers.

  • 3-tier constitution registry. src/fcc/governance/constitution_registry.py enforces hard-stop, mandatory, and preferred tiers at persona-lookup time — a hard-stop bypass is a runtime error.
  • Quality gate registry. QualityGateRegistry runs gates per deliverable; the CI scaffold hooks this into PR checks. See For Professionals — Governance and Compliance.
  • Event-driven audit trail. Every gate evaluation emits an event on the FCC bus; the AURORA visualiser and the compliance subscriber both consume this stream.

Risk 5 — Observability gaps

What could break. A production incident in an FCC-backed workflow requires tracing back through the persona sequence. Your observability stack captures HTTP requests but not in-process persona handoffs, so the incident is opaque.

Cost of breakage. Medium. Incidents are not common, but opaque ones are expensive.

Mitigations FCC offers.

  • 81-event structured bus. Every persona step, plugin load, compliance check, and gate evaluation emits a typed event on the FCC bus. Subscribe once; replay forever. See For Professionals — Integration Guide.
  • OpenTelemetry-optional tracing. FccTracer works standalone and upgrades to OTel when the optional dependency is installed.
  • Session recording. The collaboration engine records every session as JSON under src/fcc/collaboration/recording.py; the recordings are replayable through the event bus.

Risk 6 — Federation entity collision

What could break. Two sister projects register vocabulary providers with overlapping source_id keys. The VocabularyMappingLoader resolves non-deterministically and downstream RAG results become unreliable.

Cost of breakage. Medium-high for RAG-dependent applications.

Mitigations FCC offers.

  • Namespace registry. NamespaceRegistry under src/fcc/federation/namespace.py claims one namespace per ecosystem (11 registered today) and rejects collisions at load time.
  • Change tracker. ChangeTracker logs every mapping change with before/after state; reviews catch the collision before it ships.
  • Entry-point name uniqueness. The setuptools entry-point group enforces unique keys per installation; pip will refuse a second provider with the same key.

Summary — who owns which risk

Risk Primary owner FCC's role
Version drift Your tier commitment Contract tests, SHA-pinning
Plugin discovery Your CI Health reader, dependency manifest
Compliance drift Your compliance officer Pipeline, evidence graphs
Gate bypass Your developer Constitution registry, audit trail
Observability gaps Your SRE Event bus, OTel, session recording
Federation collision Your architect Namespace registry, change tracker

FCC cannot eliminate any of the risks above — no framework can. What it offers is an instrumented, auditable substrate on which your team can reason about them.