Introduce MeasureEnvironment: consolidate endpoint params, resolve at construction (#981)

* Introduce MeasureReference sealed interface

Replace Either3<CanonicalType, IdType, Measure> and the three-separate-lists
pattern (List<IdType>, List<String>, List<String>) with a single sealed type:

  sealed interface MeasureReference {
      record ById(IIdType id)
      record ByIdentifier(String identifier)
      record ByCanonicalUrl(String url)
  }

HAPI providers convert at the boundary via fromOperationParams().
R4MeasureServiceUtils.getMeasures() dispatches on the sealed type.
R4CareGapsParameters uses List<MeasureReference> instead of 3 fields.
R4MultiMeasureService, R4CareGapsProcessor accept List<MeasureReference>.
R4CareGapsService.liftMeasureParameters() deleted -- boundary conversion
now happens once in the transport layer.
R4CollectDataService reads Measure directly via repository.read() instead
of wrapping in Either3.

The type is self-documenting: a measure can be referenced by ID,
identifier, or canonical URL. Compiler enforces exhaustive handling.

* Fix benchmark test: replace Either3 with MeasureReference

* spotless

* Introduce MeasureEnvironment: consolidate endpoint params

contentEndpoint, terminologyEndpoint, dataEndpoint, and additionalData
were passed as four separate parameters through every layer of the
measure evaluation stack -- both public interfaces and internal methods.
Replace all four with MeasureEnvironment.

  record MeasureEnvironment(
      IBaseResource contentEndpoint,
      IBaseResource terminologyEndpoint,
      IBaseResource dataEndpoint,
      IBaseBundle additionalData)

Per the pipeline architecture, environment resolution is step 2 --
separate from the operation parameters. HAPI providers (the transport
boundary) now construct MeasureEnvironment from the resolved endpoint
params before calling the service layer. All downstream code receives
a single typed object.

R4MultiMeasureService.evaluateToListOfList() now delegates repository
construction to a private resolveRepository(MeasureEnvironment) helper,
making the step explicit and testable in isolation.

MeasureEnvironment.EMPTY is used by R4CareGapsBundleBuilder (which has
no endpoint configuration) and by test helpers that only set additionalData.

IBaseResource / IBaseBundle carry the endpoints version-agnostically,
consistent with the domain-core invariant (no version-specific types).

* Pull up additionalData federation as explicit pipeline step

federateWithAdditionalData(IRepository, MeasureEnvironment) is now a
named private method alongside resolveRepository(MeasureEnvironment),
making the two-step environment setup explicit in evaluateToListOfList:

  var effectiveRepo = resolveRepository(environment);   // endpoint proxy
  var subjectRepo   = federateWithAdditionalData(effectiveRepo, environment); // bundle overlay

Previously the FederatedRepository construction was buried inside
getSubjectsForEvaluateSingle, which also hardcoded this.repository as
the federation base instead of effectiveRepo. That meant additional-data
subjects were resolved against the base repository even when an endpoint
proxy was active.

getSubjectsForEvaluateSingle now takes the already-prepared subjectRepo
directly — one job, one level of abstraction.

* resolveRepository is the single environment setup step

All environment config is resolved upfront in resolveRepository():
- endpoint proxy (all three endpoints → Repositories.proxy)
- additional data federation (bundle → FederatedRepository overlay)

The CQL engine receives resolvedRepo and null for additionalData —
the bundle is already accessible through the federated repository.
Passing it twice was wrong: the repo is the resolved environment.

* Remove repo branching: resolvedRepo is the only repo

Once resolveRepository() runs, there is one repo. No switching.
The pre-cached standard processor and utils fields were a remnant
of the old conditional — delete them and construct directly from
resolvedRepo every time.

* Environment resolved at construction: MeasureEnvironment gone from eval signatures

The resolved IRepository is now a constructor parameter, not a method
parameter threaded through the call stack.

MeasureEnvironment.resolve(IRepository) composes the final repository:
endpoint proxy (when all three endpoints present) then additional-data
federation. This is the single place that knows how to build the repo.

Operation providers (HAPI transport boundary) resolve environment
before constructing the service via the factory:
  factory.create(requestDetails, environment)
  → environment.resolve(repositoryFactory.create(requestDetails))
  → new R4MultiMeasureService(resolvedRepo, ...)

R4MeasureEvaluatorSingle, R4MeasureEvaluatorMultiple, and
Dstu3MeasureEvaluatorSingle no longer carry MeasureEnvironment.
R4MultiMeasureService.resolveRepository() is deleted. The service
receives a repo that is already fully configured; it just uses it.

* feat: test for measure enviornment

* bug: spotless issues

Author: JPercival

cqf-fhir-benchmark/src/test/java/org/opencds/cqf/fhir/benchmark/measure/r4/Measure.java

@@ -149,10 +149,6 @@ public When evaluate() {
                     null,
                     null,
                     null,
-                    null,
-                    additionalData,
-                    null,
-                    null,
                     null);
             return this;
         }

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/config/dstu3/CrDstu3Config.java

@@ -26,7 +26,8 @@ public class CrDstu3Config {
     @Bean
     IMeasureServiceFactory dstu3MeasureServiceFactory(
             IRepositoryFactory repositoryFactory, MeasureEvaluationOptions evaluationOptions) {
-        return rd -> new Dstu3MeasureService(repositoryFactory.create(rd), evaluationOptions);
+        return (requestDetails, environment) -> new Dstu3MeasureService(
+                environment.resolve(repositoryFactory.create(requestDetails)), evaluationOptions);
     }
 
     @Bean

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/config/r4/CrR4Config.java

@@ -75,8 +75,8 @@ R4MeasureEvaluatorSingleFactory r4MeasureServiceFactory(
             MeasureEvaluationOptions evaluationOptions,
             MeasurePeriodValidator measurePeriodValidator) {
         // We are effectively returning an R4MeasureEvaluatorSingle her
-        return requestDetails -> new R4MultiMeasureService(
-                repositoryFactory.create(requestDetails),
+        return (requestDetails, environment) -> new R4MultiMeasureService(
+                environment.resolve(repositoryFactory.create(requestDetails)),
                 evaluationOptions,
                 requestDetails.getFhirServerBase(),
                 measurePeriodValidator);
@@ -87,8 +87,11 @@ R4MeasureEvaluatorMultipleFactory r4MeasureEvaluatorMultipleFactory(
             IRepositoryFactory repositoryFactory,
             MeasureEvaluationOptions evaluationOptions,
             MeasurePeriodValidator measurePeriodValidator) {
-        return rd -> new R4MultiMeasureService(
-                repositoryFactory.create(rd), evaluationOptions, rd.getFhirServerBase(), measurePeriodValidator);
+        return (requestDetails, environment) -> new R4MultiMeasureService(
+                environment.resolve(repositoryFactory.create(requestDetails)),
+                evaluationOptions,
+                requestDetails.getFhirServerBase(),
+                measurePeriodValidator);
     }
 
     @Bean

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/dstu3/IMeasureServiceFactory.java

@@ -1,9 +1,10 @@
 package org.opencds.cqf.fhir.cr.hapi.dstu3;
 
 import ca.uhn.fhir.rest.api.server.RequestDetails;
+import org.opencds.cqf.fhir.cr.measure.common.MeasureEnvironment;
 import org.opencds.cqf.fhir.cr.measure.dstu3.Dstu3MeasureService;
 
 @FunctionalInterface
 public interface IMeasureServiceFactory {
-    Dstu3MeasureService create(RequestDetails requestDetails);
+    Dstu3MeasureService create(RequestDetails requestDetails, MeasureEnvironment environment);
 }

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/dstu3/measure/MeasureOperationsProvider.java

@@ -18,6 +18,7 @@
 import org.hl7.fhir.dstu3.model.Parameters.ParametersParameterComponent;
 import org.hl7.fhir.exceptions.FHIRException;
 import org.opencds.cqf.fhir.cr.hapi.dstu3.IMeasureServiceFactory;
+import org.opencds.cqf.fhir.cr.measure.common.MeasureEnvironment;
 import org.springframework.stereotype.Component;
 
 @Component
@@ -72,8 +73,9 @@ public MeasureReport evaluateMeasure(
             RequestDetails requestDetails)
             throws InternalErrorException, FHIRException {
         var terminologyEndpointParam = (Endpoint) getEndpoint(fhirVersion, terminologyEndpoint);
+        var environment = new MeasureEnvironment(null, terminologyEndpointParam, null, additionalData);
         return dstu3MeasureProcessorFactory
-                .create(requestDetails)
+                .create(requestDetails, environment)
                 .evaluateMeasure(
                         id,
                         periodStart,
@@ -83,8 +85,6 @@ public MeasureReport evaluateMeasure(
                         practitioner,
                         lastReceivedOn,
                         productLine,
-                        additionalData,
-                        parameters,
-                        terminologyEndpointParam);
+                        parameters);
     }
 }

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/r4/R4MeasureEvaluatorMultipleFactory.java

@@ -1,9 +1,10 @@
 package org.opencds.cqf.fhir.cr.hapi.r4;
 
 import ca.uhn.fhir.rest.api.server.RequestDetails;
+import org.opencds.cqf.fhir.cr.measure.common.MeasureEnvironment;
 import org.opencds.cqf.fhir.cr.measure.r4.R4MeasureEvaluatorMultiple;
 
 @FunctionalInterface
 public interface R4MeasureEvaluatorMultipleFactory {
-    R4MeasureEvaluatorMultiple create(RequestDetails requestDetails);
+    R4MeasureEvaluatorMultiple create(RequestDetails requestDetails, MeasureEnvironment environment);
 }

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/r4/R4MeasureEvaluatorSingleFactory.java

@@ -1,9 +1,10 @@
 package org.opencds.cqf.fhir.cr.hapi.r4;
 
 import ca.uhn.fhir.rest.api.server.RequestDetails;
+import org.opencds.cqf.fhir.cr.measure.common.MeasureEnvironment;
 import org.opencds.cqf.fhir.cr.measure.r4.R4MeasureEvaluatorSingle;
 
 @FunctionalInterface
 public interface R4MeasureEvaluatorSingleFactory {
-    R4MeasureEvaluatorSingle create(RequestDetails requestDetails);
+    R4MeasureEvaluatorSingle create(RequestDetails requestDetails, MeasureEnvironment environment);
 }

cqf-fhir-cr-hapi/src/main/java/org/opencds/cqf/fhir/cr/hapi/r4/measure/MeasureOperationsProvider.java

@@ -20,6 +20,7 @@
 import org.opencds.cqf.fhir.cr.hapi.common.StringTimePeriodHandler;
 import org.opencds.cqf.fhir.cr.hapi.r4.R4MeasureEvaluatorMultipleFactory;
 import org.opencds.cqf.fhir.cr.hapi.r4.R4MeasureEvaluatorSingleFactory;
+import org.opencds.cqf.fhir.cr.measure.common.MeasureEnvironment;
 import org.opencds.cqf.fhir.cr.measure.common.MeasureReference;
 
 @SuppressWarnings("java:S107")
@@ -87,19 +88,17 @@ public MeasureReport evaluateMeasure(
         var contentEndpointParam = (Endpoint) getEndpoint(fhirVersion, contentEndpoint);
         var terminologyEndpointParam = (Endpoint) getEndpoint(fhirVersion, terminologyEndpoint);
         var dataEndpointParam = (Endpoint) getEndpoint(fhirVersion, dataEndpoint);
+        var environment = new MeasureEnvironment(
+                contentEndpointParam, terminologyEndpointParam, dataEndpointParam, additionalData);
         return r4MeasureServiceFactory
-                .create(requestDetails)
+                .create(requestDetails, environment)
                 .evaluate(
                         new MeasureReference.ById(id),
                         stringTimePeriodHandler.getStartZonedDateTime(periodStart, requestDetails),
                         stringTimePeriodHandler.getEndZonedDateTime(periodEnd, requestDetails),
                         reportType,
                         subject,
                         lastReceivedOn,
-                        contentEndpointParam,
-                        terminologyEndpointParam,
-                        dataEndpointParam,
-                        additionalData,
                         parameters,
                         productLine,
                         practitioner);
@@ -157,18 +156,16 @@ public Parameters evaluate(
         var terminologyEndpointParam = (Endpoint) getEndpoint(fhirVersion, terminologyEndpoint);
         var dataEndpointParam = (Endpoint) getEndpoint(fhirVersion, dataEndpoint);
         var measureRefs = MeasureReference.fromOperationParams(measureId, measureIdentifier, measureUrl);
+        var environment = new MeasureEnvironment(
+                contentEndpointParam, terminologyEndpointParam, dataEndpointParam, additionalData);
         return r4MultiMeasureServiceFactory
-                .create(requestDetails)
+                .create(requestDetails, environment)
                 .evaluate(
                         measureRefs,
                         stringTimePeriodHandler.getStartZonedDateTime(periodStart, requestDetails),
                         stringTimePeriodHandler.getEndZonedDateTime(periodEnd, requestDetails),
                         reportType,
                         subject,
-                        contentEndpointParam,
-                        terminologyEndpointParam,
-                        dataEndpointParam,
-                        additionalData,
                         parameters,
                         productLine,
                         reporter);

cqf-fhir-cr/src/main/java/org/opencds/cqf/fhir/cr/measure/common/MeasureEnvironment.java

@@ -0,0 +1,58 @@
+package org.opencds.cqf.fhir.cr.measure.common;
+
+import ca.uhn.fhir.repository.IRepository;
+import jakarta.annotation.Nullable;
+import org.hl7.fhir.instance.model.api.IBaseBundle;
+import org.hl7.fhir.instance.model.api.IBaseResource;
+import org.opencds.cqf.fhir.utility.repository.FederatedRepository;
+import org.opencds.cqf.fhir.utility.repository.InMemoryFhirRepository;
+import org.opencds.cqf.fhir.utility.repository.Repositories;
+
+/**
+ * Version-agnostic environment configuration for measure evaluation.
+ *
+ * <p>Separates the <em>infrastructure inputs</em> (where data, content, and terminology come from)
+ * from the <em>operation parameters</em> (what to evaluate). Per the pipeline architecture,
+ * environment resolution happens before domain logic: the service layer composes a
+ * {@code ProxyRepository} from these endpoints and passes it to the evaluator.
+ *
+ * <p>Endpoint resources are typed as {@link IBaseResource} so both R4 and DSTU3
+ * {@code Endpoint} instances can be carried without version coupling.
+ * {@code Repositories.proxy()} already accepts {@code IBaseResource} endpoints directly.
+ *
+ * @param contentEndpoint     endpoint for library/content resolution (nullable)
+ * @param terminologyEndpoint endpoint for terminology resolution (nullable)
+ * @param dataEndpoint        endpoint for clinical data retrieval (nullable)
+ * @param additionalData      supplemental data bundle for repository federation and CQL engine
+ *                            configuration (nullable)
+ */
+public record MeasureEnvironment(
+        @Nullable IBaseResource contentEndpoint,
+        @Nullable IBaseResource terminologyEndpoint,
+        @Nullable IBaseResource dataEndpoint,
+        @Nullable IBaseBundle additionalData) {
+
+    /** Empty environment — no endpoints, no additional data. */
+    public static final MeasureEnvironment EMPTY = new MeasureEnvironment(null, null, null, null);
+
+    /**
+     * Resolves this environment against a base repository.
+     *
+     * <p>If any endpoint is present, wraps {@code base} in a {@code ProxyRepository}; null
+     * endpoints fall back to {@code base}. If {@code additionalData} is present, federates
+     * the result with an in-memory repository seeded from that bundle.
+     *
+     * @param base the base repository to build on top of
+     * @return the resolved repository, possibly wrapped
+     */
+    public IRepository resolve(IRepository base) {
+        IRepository repo = base;
+        if (dataEndpoint() != null || contentEndpoint() != null || terminologyEndpoint() != null) {
+            repo = Repositories.proxy(repo, true, dataEndpoint(), contentEndpoint(), terminologyEndpoint());
+        }
+        if (additionalData() != null) {
+            repo = new FederatedRepository(repo, new InMemoryFhirRepository(repo.fhirContext(), additionalData()));
+        }
+        return repo;
+    }
+}

cqf-fhir-cr/src/main/java/org/opencds/cqf/fhir/cr/measure/dstu3/Dstu3MeasureEvaluatorSingle.java

@@ -1,7 +1,5 @@
 package org.opencds.cqf.fhir.cr.measure.dstu3;
 
-import org.hl7.fhir.dstu3.model.Bundle;
-import org.hl7.fhir.dstu3.model.Endpoint;
 import org.hl7.fhir.dstu3.model.IdType;
 import org.hl7.fhir.dstu3.model.MeasureReport;
 import org.hl7.fhir.dstu3.model.Parameters;
@@ -21,7 +19,5 @@ MeasureReport evaluateMeasure(
             String practitioner,
             String lastReceivedOn,
             String productLine,
-            Bundle additionalData,
-            Parameters parameters,
-            Endpoint terminologyEndpoint);
+            Parameters parameters);
 }