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.

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.
• 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), so it rides along without disturbing structural comparison or JSON output. String-encoded decimal values (value: "1.40") are supported, with digits-after-the-dot as an implicit precision fallback.

Comparison

• resultsEqual now detects interval-shaped operands 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 also fixes the part-based interval representation from Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 ([1.0, 4.0) vs [1.0, 3.99999999]).
• The step is chosen per boundary: declared quantity-precision (10^-p) → declared point type (1 for Integer/Long, 10^-8 for Decimal) → an integrality heuristic for untyped integer intervals → the CQL decimal step (10^-8). Quantity boundaries never use the integer heuristic (Quantity values are Decimals). The comparison is deliberately not over-lenient: an engine that truncates a predecessor at an undeclared precision still fails.
• BigInt Long boundaries compare safely (BigInt arithmetic for integral steps, exact comparison 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).

Docs

• docs/plan-fhir-56226-numeric-interval-checks.md records the full design, the detection decision, and open spec questions (extension URL typo in the ticket, extension placement, string-encoded values).
• README test-flow section documents the mapping and detection rule.

Testing

• 156 unit tests pass (npx vitest run), including ~30 new tests: extractor fixtures for both $cql and $evaluate shapes, the FHIR-56226 ticket example, the Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 cases (DecimalIntervalExcept1to3, IntegerIntervalExcept1to3 shapes), strictness regressions, and negative precision-truncation 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

• 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.