TECH_DEBT: Wire federated terminology into Measure evaluation with bundle-first semantics

[c-schuler]

🛠️ Description of Changes

Adds optional federated terminology support to measure evaluation. When a remote FHIR terminology service URL is configured via link.fhirTerminologyServiceUrl, CQL evaluation federates ValueSet and CodeSystem lookups between the measure bundle and the remote server; when unset, behavior is unchanged (plain in-memory bundle repository, exactly as before).

Federation semantics: bundle-first, fall-through-on-empty. The measure bundle is always consulted first for terminology resources; the remote is called only when the bundle doesn't have what CQL is asking for. Remote failures degrade gracefully. The local (empty) result is returned instead of propagating an exception. This preserves measure reproducibility: bundle-embedded ValueSet expansions the measure author validated with take precedence over whatever the remote TS currently holds.

Scope of federation. Only ValueSet and CodeSystem reads/searches consult the remote. Patient data, Measure, Library, and everything else stay strictly local - no patient data is ever fetched from a terminology server.

🧪 Testing Performed

Automated tests run and verified in IntelliJ (four scenarios):

1. No federation baseline - no remote client, bundle carries its own ValueSet. MeasureReport computes correctly with initial-population = 1.
2. Federation on, bundle self-sufficient - remote client configured, bundle has the VS. MeasureReport identical to (1). WireMock recorded zero requests - confirming bundle-first semantics work end-to-end and the remote is not consulted when unnecessary. This is the load-bearing regression test.
3. Federation on, bundle missing the VS - bundle stripped of ValueSets, mock TS serves them. MeasureReport still initial-population = 1; WireMock records the expected fetch. Confirms fall-through works and produces the same result as bundle-embedded.
4. Federation on, remote unreachable - bundle stripped, WireMock returns 503 on every request. MeasureReport comes back with initial-population = 0 rather than throwing. Confirms graceful degradation.

Manual verifier (FederatedTerminologyVerifier) built for running against real NHSN measure bundles per the procedure documented in FEDERATION-VERIFICATION.md - not yet exercised against production-shape input, recommended before merge but not required.

🧑‍🔬 Unit Testing

• I have written or updated unit tests to cover my changes
• Coverage: 70.0%

📓 Documentation Updated

• Java/measureeval/FEDERATION-VERIFICATION.md (new) - Manual verification procedure for exercising the wire-up against real IG bundles. Includes prerequisites, invocation, expected output format, and cross-referencing with shipped example MeasureReport counts. Serves as the compliance-verification runbook for future changes to buildRepository().
• MeasureEvaluator.buildRepository() Javadoc - Extended block explaining why we compose our own IRepository instead of using CQF's endpoint parameters or Repositories.proxy + FederatedRepository. Documents the bytecode-verified limitations in both mechanisms (all-or-nothing endpoint guard; parallel-merge semantics in FederatedRepository.search) so future maintainers understand the decision.
• FederatedFhirRepository class Javadoc - Documents behavior (bundle-first, fall-through-on-empty, VS/CS-only), rationale for the custom implementation, and interaction with CQF's RestRepository for the underlying client bridge.
• MeasureEvaluatorFederationTests class Javadoc - Documents which invariants each scenario tests and calls out scenario 2 as the load-bearing regression check.

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e5ae3584-29d7-4b37-a5bb-672574d5bdab

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}