multi-component stratifiers: Ensure FHIR MeasureReport stratumPopulations contain scores and aggregation extensions, including criteriaReference

[lukedegruchy]

Summary

R4MeasureReportBuilder#copyStratifierScores silently failed to copy stratum scores and per-stratum population aggregation extensions (cqfm-criteriaReference, cqfm-aggregateMethod, cqfm-aggregationMethodResult) for any measure using multi-component stratifiers (2+ components in stratifier.component[]). The root cause was matchesStratumValue only checking the top-level stratum.value field, which multi-component strata never populate -- they store data on stratum.component[] entries instead. This fix adds component-aware matching and closes the test coverage gap that allowed the bug to go undetected.

1. Fix matchesStratumValue to handle multi-component strata: When StratumDef.isComponent() is true, delegate to a new matchesComponentStratumValues method that pairs report components with StratumDef value definitions by code text and value text, with order-independent matching and size validation. The single-value path is unchanged.

2. Close the test coverage gap: All prior multi-component stratifier tests used COHORT scoring (which never scores strata -- scorer returns null), and all RATIO/PROPORTION tests used single-component stratifiers. Added a new RATIO measure fixture with a 2-component stratifier (Gender + Age) and an integration test that asserts stratum scores and per-stratum population counts -- the exact combination that was missing.

Code Review Suggestions

• Verify that matchesComponentStratumValues correctly mirrors the "write" side in R4StratifierBuilder#buildStratum: the builder sets component value via expressionResultToCodableConcept(value) which uses StratumValueWrapper.getValueAsString(), and the matcher reads rc.getValue().getText(). Confirm these are always symmetric for all value types the CQL engine can produce (Codes, integers, strings, booleans, etc.).
• Check whether StratumValueWrapper.getValueAsString() can ever diverge from what expressionResultToCodableConcept stores as CodeableConcept.text. For example, if a CQL expression returns a CodeableConcept (not just a Code), does getValueAsString() return the same thing that gets set as the component value text?
• The matching uses valueDef.value().getValueAsString() on the StratumDef side, but the report side uses rc.getValue().getText(). These come from different code paths (scorer vs builder). Confirm there is no edge case where one normalizes whitespace, casing, or null/empty differently than the other.
• The PRP mentions a secondary bug in getStratumDefText for multi-component strata (returns component code text instead of value text for CodeableConcept values). While the fix bypasses getStratumDefText entirely for component matching, verify no other callers depend on getStratumDefText for multi-component strata.

QA Test Suggestions

Setup

• Deploy a FHIR server with the clinical-reasoning module
• Load a Measure with RATIO or PROPORTION scoring that has a multi-component stratifier (2+ entries in stratifier.component[]), e.g., stratifying by both Gender and Age
• Load test Patient and Encounter resources with varied demographics to produce multiple strata
• Ensure the measurement period covers the encounter dates

Test Cases

• Multi-component RATIO stratum scores are present: Run $evaluate-measure on the RATIO measure with multi-component stratifier. Inspect the resulting MeasureReport's group.stratifier.stratum entries. Each stratum should have a non-null measureScore value matching the expected numerator/denominator ratio for that stratum's subject subset.
• Multi-component RATIO stratum populations are correct: In the same MeasureReport, verify that each stratum's population entries (IP, Denominator, Numerator) have correct counts that partition the group-level populations by the stratifier components.
• Single-component stratifier still works (regression): Run $evaluate-measure on a RATIO measure with a single-component stratifier. Verify stratum scores and population counts are unchanged from prior behavior.
• COHORT multi-component stratifier still works (regression): Run $evaluate-measure on a COHORT measure with a multi-component stratifier. Verify strata are present with correct population counts (scores should remain absent since COHORT doesn't score strata).
• RATIO with MEASUREOBSERVATION populations + multi-component stratifier: If applicable, run $evaluate-measure on a RATIO CV measure with multi-component stratifier. Verify that stratum observation populations have cqfm-criteriaReference, cqfm-aggregateMethod, and cqfm-aggregationMethodResult extensions populated.
• CQIS downstream aggregation (if integrated): After updating the clinical-reasoning dependency in CQIS, run an end-to-end measure evaluation with a multi-component stratifier RCV combo measure. Verify that StratifierReportAggregator no longer encounters null criteriaReference values on stratum observation populations.

[github-actions]

Formatting check succeeded!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
97.2% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud