Inject IMetricService into CQL runtime for UCUM unit arithmetic

[ewoutkramer]

Summary

• Adds an IMetricService injection point to FhirCqlContext/FhirCqlContextOptions so callers can supply a custom UCUM implementation instead of the built-in default.
• Introduces DefaultUcumMetricService (internal) — wraps FhirMetricService and fills in TryConvertTo using SystemOfUnits.Convert directly, since FhirMetricService.TryConvertTo throws NotImplementedException.
• Improves several CqlOperators methods that operate on CqlQuantity to route through the injected IMetricService where it was previously ignored:
  • Add and Subtract: cross-unit calendar aliases (day/days) and commensurable UCUM units (kg+g via TryAdd/TrySubtract)
  • Divide: cross-unit UCUM division via TryDivide (e.g. 2 kg / 1 g → 2000)
  • Between: uses Comparer which already routes through the service for cross-unit comparisons
  • CanConvertQuantity: fixed to return false instead of throwing for unconvertible units
• Distinguishes two failure modes in cross-unit arithmetic: false from Try* means genuinely incompatible units; NotImplementedException from Try* means the configured service doesn't implement the operation — each produces a distinct NotSupportedException message.
• Fixes pre-existing copy/paste bugs in Subtract and Modulo (both called Add internally in their mixed-unit branch).
• Adds CqlQuantityTests covering Add, Subtract, Modulo, Divide, Multiply, Between, and CanConvertQuantity with same-unit, calendar-alias, cross-unit, null, and error cases.

Injecting a custom IMetricService

The default service (DefaultUcumMetricService) wraps FhirMetricService from the open-source Fhir.Metrics package. It handles TryConvertTo and TryDivide/TryCompare/TryCanonicalize, but TryAdd and TrySubtract are not implemented — cross-unit addition/subtraction will throw with a clear message.

To enable full cross-unit arithmetic (e.g. 1 kg + 500 g), supply a complete IMetricService implementation via FhirCqlContextOptions:

// Default: uses the built-in FhirMetricService wrapper
var context = FhirCqlContext.ForBundle(bundle);

// Custom: inject an improved custom IMetricService 
var context = FhirCqlContext.ForBundle(bundle, options: new FhirCqlContextOptions
{
    MetricService = new MyFullUcumMetricService()
});

// Same pattern for WithDataSource:
var context = FhirCqlContext.WithDataSource(source, options: new FhirCqlContextOptions
{
    MetricService = new MyFullUcumMetricService()
});

IMetricService is defined in the Fhir.Metrics NuGet package.

Test plan

• CqlQuantityTests — 42 passing, 2 skipped (cross-unit Add/Subtract require a full IMetricService; marked [Ignore] with explanation)
• Existing UcumTests still pass
• No regressions in CqlContextOperatorTests or ExpressionBuilderTests

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds injectable UCUM metric-service support to quantity conversion/comparison/arithmetic paths in the CQL runtime and exposes that injection through the Firely CQL context options.

Changes:

• Adds IMetricService plumbing through runtime comparers, unit conversion, and Firely context options.
• Reworks UCUM conversion helpers around IMetricService, including a default wrapper for FhirMetricService.
• Adds and updates quantity/operator tests for conversion, arithmetic, comparison, and null/error behavior.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Cql/Cql.Runtime/PublicAPI.Shipped.txt	Updates shipped API nullability metadata for Contains<T>.
Cql/Cql.Runtime/Operators/CqlOperators.TypeOperators.cs	Implements CanConvertQuantity using UnitConverter.ChangeUnits.
Cql/Cql.Runtime/Operators/CqlOperators.cs	Adds metric-service support to CqlOperators.Create and stores it for arithmetic.
Cql/Cql.Runtime/Operators/CqlOperators.ComparisonOperators.cs	Routes quantity Between through the configured comparer.
Cql/Cql.Runtime/Operators/CqlOperators.ArithmeticOperators.cs	Uses metric-service UCUM operations for mixed-unit add/subtract/divide paths.
Cql/Cql.Runtime/Cql.Runtime.csproj	Bumps Fhir.Metrics to 1.3.1.
Cql/Cql.Runtime/Conversion/UnitConverter.cs	Allows UCUM fallback conversions to use an injected metric service.
Cql/Cql.Runtime/Conversion/UcumConversionExtensions.cs	Refactors UCUM helpers to accept IMetricService and adds the default wrapper service.
Cql/Cql.Runtime/Comparers/CqlComparers.cs	Passes metric service into the quantity comparer.
Cql/Cql.Runtime/Comparers/CqlComparers.CqlQuantityCqlComparer.cs	Canonicalizes quantities using the configured metric service.
Cql/Cql.Firely/FhirCqlContextOptions.cs	Exposes MetricService as a Firely context option.
Cql/Cql.Firely/FhirCqlContext.cs	Wires the metric service into Firely comparers/unit conversion setup.
Cql/Cql.Firely/Cql.Firely.csproj	Adds a direct Fhir.Metrics dependency.
Cql/CoreTests/UcumTests.cs	Updates UCUM tests for metric-service based conversion APIs.
Cql/CoreTests/CqlQuantityTests.cs	Adds quantity arithmetic/comparison/conversion operator coverage.
Cql/CoreTests/CoreTests.csproj	Adds Fhir.Metrics to the test project dependencies.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[baseTwo]

@alexzautke / @ewoutkramer the assertions in the unit tests do not seem correct. I had a chat with Ewout yesterday, and we determined that more work is needed on this PR.

Specific focus is needed on

• Multiply_ByScalar_ReturnsScalarProduct (previously Multiply_ByScalar_ReturnsProductWithLeftUnit)
  • A scalar product with unit-quantity should also be a unit-quantity
• Divide_ByScalar_ReturnsQuotientWithLeftUnit.
  • When dividing a scalar with a unit-quantity, is it the idea that the si prefix is shifted from mg to g?

There is a possible logic error in CqlOperators.ArithmeticOperators.cs method Multiply(CqlQuantity? left, CqlQuantity? right)

• There is a lot of pre-optimization on cql quantities done here, before it even goes to the ucum binary operator logic. I believe this is the correct logic

        public CqlQuantity? Multiply(CqlQuantity? left, CqlQuantity? right)
        {
            if (left == null || right == null)
                return null;
            else if (left.value == null || right.value == null)
                return null;
            else
                return TryUcumBinaryOp(left.value.Value, left.unit!, right.value.Value, right.unit!, MetricServiceExtensions.TryMultiply, "Multiply");
        }

[baseTwo]

Fix test name - it says result keeps left unit, but assertion checks dimensionless unit on the right

[baseTwo]

Fixed

[baseTwo]

Actually this is still not correct, see #1282 (review)