Support numeric interval results mapped as Range per FHIR-56226

[alexzautke]

Summary

Implements runner support for the proposed FHIR-56226 mapping of Interval<Integer>, Interval<Long>, and Interval<Decimal> results, and fixes the open-vs-closed boundary comparison mismatch for numeric intervals reported in #85.

Under FHIR-56226, a numeric interval is returned as a FHIR Range whose boundaries are unity quantities (code: "1", system: http://unitsofmeasure.org), each optionally carrying a quantity-precision extension. Since Range cannot express open boundaries, an open boundary is sent as its closed equivalent at the stated precision — e.g. Interval[1.0, 1.4) arrives as [1.0, 1.3] with precision 1. The runner previously extracted such ranges as quantity intervals and compared boundary flags literally, so these results could never match the expected values.

Note: the comparison change is not gated on FHIR-56226 adoption. resultsEqual delegates every interval-shaped operand to intervalsEqual, so open/closed boundary normalization applies to interval comparison today — including the existing part-based interval representation — independent of whether an engine uses the proposed Range mapping.

Changes

Extraction

• New NumericIntervalExtractor (registered ahead of QuantityIntervalExtractor) extracts a declared numeric valueRange into the same plain-number {lowClosed, low, highClosed, high} shape the CVL parser produces for expected values. Interval<Long> boundaries extract as BigInt (exact beyond 2^53 when the engine sends the value as a JSON string; a bare JSON number is rounded by the JSON parser before extraction).
• Detection is strictly declaration-driven: the parameter must carry a cqf-cqlType extension naming Interval<Integer|Long|Decimal> (optional System. prefix). A unity-coded fallback without the extension was implemented and then removed in review — FHIR-56226 only defines the forward mapping, not an inverse detection rule, and unity coding alone is ambiguous with a dimensionless Interval<Quantity>. Ranges without the extension keep their existing quantity-interval behavior.
• The quantity-precision extension is read from both plausible placements (low.extension as shown in the Jira example, and low._value.extension per FHIR primitive-extension rules) and recorded — together with the point type — as non-enumerable Symbol-keyed metadata (src/shared/interval-utils.ts). This metadata exists only on the live extracted object: any serialization round-trip drops it, so comparison must run before serialization (documented in interval-utils.ts; relevant to the runner-core refactor in Dedupe runners for cli and server paths #108). Non-numeric boundary values are treated as absent.
• Intervals in the part-based representation (Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85) get their point type derived from the wire: the parameter's cqf-cqlType extension when it names a numeric interval type, otherwise the FHIR element types of the boundary parts (valueInteger → Integer, valueDecimal → Decimal; valueString and mixed types derive nothing).

Comparison

• resultsEqual detects interval-shaped operands (strictly: exactly the four interval keys with boolean closed flags — near-miss tuples keep comparing by plain value) and delegates to intervalsEqual, which normalizes open boundaries on both sides to their closed equivalent one step inwards before comparing values, so open and closed forms of the same interval are equal. This fixes the part-based cases from Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 ([1.0, 4.0) vs [1.0, 3.99999999], [1, 4) vs [1, 3]).
• The step is chosen per boundary from recorded metadata: 1 for a declared/wire-derived Integer or Long point type (a precision extension cannot override it); otherwise a validated non-negative-integer quantity-precision (10^-p; precision 0 legitimately yields step 1 for Decimals); otherwise the CQL decimal step (10^-8). Step 1 requires a declared or wire-derived point type — a heuristic that inferred it from integral-looking values was implemented and then dropped in review, because it accepted both the integer-step and the decimal-step answer for the same untyped expected. Untyped intervals always compare at the decimal step.
• Boundary values compare with a tolerance of half the step (not the fixed 1e-8): with tolerance equal to the step, values a full step apart sit exactly on the comparison boundary and the verdict depends on float rounding. When the step underflows the float's resolution at extreme magnitudes (1e9 - 1e-8 === 1e9), an open and a closed boundary at the same value are unequal by rule — the one-point difference is real even when the value can no longer express it. The comparison stays deliberately not over-lenient: an engine that truncates a predecessor at an undeclared precision still fails.
• BigInt Long boundaries compare exactly beyond Number.MAX_SAFE_INTEGER; Date/DateTime/Time intervals keep the pre-existing structural semantics byte-for-byte (Test Runner Not Detecting Equal Lists of Interval<DateTime>/Period #80/Test Runner Not Detecting Equal DateTimes (Offset vs No Offset) #84 remain out of scope).
• The four-key interval-shape predicate lives in one place (interval-utils.ts) and is shared by comparison, part-form extraction, and the results-file rendering that Extract Date/Time intervals from Periods via cqf-cqlType and render interval/quantity actuals in CQL syntax #109 introduced in cql-test-results.ts.

Docs

• docs/plan-fhir-56226-numeric-interval-checks.md records the full design and the decisions made during review (strict detection, heuristic removal, tolerance and underflow rules, precision-0 semantics, extension URL typo in the ticket, extension placement, string-encoded values).
• README test-flow section documents the mapping and detection rule.

Testing

• 184 unit tests pass (npx vitest run), including ~50 new tests: extractor fixtures for both $cql and $evaluate shapes (Range and part-form), the FHIR-56226 ticket example, the Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 cases, BigInt Long round-trips, strictness and near-miss-tuple regressions, and negative precision/truncation/underflow cases. tsc --noEmit clean.
• The five skip-list entries in conf/cql-execution-local.json citing Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 are intentionally left in place; removing them should follow a verified run against a live engine.

Notes for reviewers

• Because intervalsEqual is ungated (see note above), this PR changes interval comparison behavior for all engines as of merge — most visibly, open/closed boundary forms of the same interval now compare equal, and untyped integer-looking intervals now compare at the decimal step rather than being heuristically matched.
• Trade-off accepted with strict detection: an engine that follows the FHIR-56226 JSON example verbatim but omits cqf-cqlType will have numeric-interval results extracted as quantity intervals and fail those tests. It may be worth feeding back on FHIR-56226 that the mapping should require the cqlType extension to be invertible.
• FHIR-56226 is still in Submitted state; if the ballot resolution changes the representation, the extractor is the single place to adjust.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WUJ7RDTBnqwBwFFwGwrR1b

[Copilot]

Pull request overview

Adds support in the runner for the proposed FHIR-56226 representation of numeric CQL intervals (Integer/Long/Decimal) as FHIR Range, including precision metadata, and updates result comparison so open/closed boundary forms can match (fixing the numeric open-vs-closed mismatch reported in #85).

Changes:

• Introduces NumericIntervalExtractor to extract declared numeric valueRange results into plain {lowClosed, low, highClosed, high} intervals and attach non-enumerable metadata (point type + precision).
• Updates resultsEqual to detect interval-shaped operands and delegate to interval-aware comparison that normalizes open boundaries inward by an appropriate step.
• Adds comprehensive unit tests and documents the mapping/detection/normalization behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/results-utils.test.ts	Adds interval comparison unit tests (FHIR-56226 and #85 scenarios, including metadata-based precision handling).
test/extractResults-library_evaluate_operations.test.ts	Adds $evaluate extraction fixtures for numeric Range intervals and metadata assertions.
test/extractResults-cql_operations.test.ts	Adds $cql extraction fixtures for numeric Range intervals and metadata assertions.
src/shared/results-utils.ts	Implements interval-aware equality with boundary normalization and precision/type-based step selection.
src/shared/interval-utils.ts	Adds shared Symbol-keyed interval metadata utilities and interval-shape detection.
src/server/extractor-builder.ts	Registers NumericIntervalExtractor ahead of QuantityIntervalExtractor.
src/extractors/value-type-extractors/numeric-interval-extractor.ts	New extractor for strictly-declared numeric interval Range results, including precision extraction.
README.md	Documents FHIR-56226 numeric interval mapping and the strict detection rule via cqf-cqlType.
docs/plan-fhir-56226-numeric-interval-checks.md	Design/decision record for numeric interval extraction and comparison.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bryantaustin13]

1. boundaryValue must return BigInt for Long boundaries. Right now Interval is advertised, typed, and unusable above 2^53 — and it leaves the BigInt paths in closeBoundary/scalarsEqual unreachable from extraction. Branch on pointType === 'Long', or on the value being an integer-literal string.
2. Decouple the equality tolerance from the predecessor step. With both at 1e-8, one step inward is one tolerance wide, so decimal open-vs-closed resolves by float magnitude rather than by rule. Either drop the tolerance well below the smallest step (step / 2, or a fixed 1e-12) or compare at the declared precision using scaled integers.

[alexzautke]

Follow-up: review-driven changes since the initial implementation

Summary of what changed on this branch in response to the review rounds, most recent last:

• 354b5ff — Boundary and precision guards. A Range boundary whose quantity value is missing or non-numeric ("abc" → NaN, booleans) is treated as an absent boundary instead of a closed boundary with an unusable value. Step selection ignores negative or fractional quantity-precision values, and an Integer/Long point type always steps by 1 regardless of any declared precision.
• 34cfd41 — Exact Longs and decoupled tolerance. Interval<Long> boundaries extract as BigInt (exact beyond 2^53 when the engine sends the value as a JSON string; a bare JSON number is rounded by the JSON parser before extraction), so they compare exactly against the BigInt expecteds the CVL parser produces. Boundary comparison uses a tolerance of half the step instead of the fixed 1e-8: with tolerance equal to the step, values a full step apart sat exactly on the comparison boundary and the verdict depended on float rounding of the subtraction.
• d66f748 — Integrality heuristic removed. The heuristic accepted both the integer-step and the decimal-step answer for the same untyped expected, so it added leniency without a check. Step-1 comparison now requires a declared or wire-derived point type: the cqf-cqlType extension for a Range, or — for the part-based representation from Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85, which carries no Range metadata — the FHIR element types of the boundary parts (valueInteger → Integer, valueDecimal → Decimal; valueString and mixed types derive nothing). Untyped intervals always compare at the decimal step; [1.0, 4.0) no longer matches [1.0, 3.0].
• 625e793 — Interval-shape predicate tightened and consolidated (after merging main to pick up Extract Date/Time intervals from Periods via cqf-cqlType and render interval/quantity actuals in CQL syntax #109). isIntervalShaped requires exactly the four interval keys with boolean closed flags, so tuples that merely share the field names keep main's plain value comparison (and render as JSON, not Interval(...)). The duplicate four-key predicate Extract Date/Time intervals from Periods via cqf-cqlType and render interval/quantity actuals in CQL syntax #109 added in cql-test-results.ts is replaced by the single shared one in interval-utils.ts. Also documented: the Symbol-keyed interval metadata exists only on the live extracted object — serialization drops it, so comparison must precede any round-trip (relevant to the runner-core refactor in Dedupe runners for cli and server paths #108) — and a declared precision of 0 legitimately yields step 1 for Decimals.
• 52f7fed — Underflow rule. At extreme magnitudes the step underflows the double's resolution (1e9 - 1e-8 === 1e9), so normalization couldn't move an open boundary and [1.5, 1e9) compared equal to [1.5, 1e9]. When exactly one side is open and closing it cannot move the value, the intervals differ by one point the float can no longer express — now unequal by rule.

The PR description reflects all of the above, including the note that intervalsEqual is ungated and changes interval comparison behavior today, independent of FHIR-56226 adoption. Suite: 184 tests passing, tsc --noEmit clean.

---

Generated by Claude Code