[bryantaustin13]

The comparison side of #138, stacked on #142 (the request side). Closes #83 and #84. Supersedes #132.

Base branch: this PR targets evaluation-timestamp-and-offset (#142), so its diff is only this change. Once #142 merges, GitHub retargets it to main.

Problem

A DateTime always has an offset during evaluation. In the CQL Author's Guide: "If no timezone offset is specified, the timezone offset of the evaluation request timestamp is used." Expected outputs are almost always written without one, but an engine must return one, because FHIR requires an offset on a dateTime with a time. The runner compared DateTimes as text, so:

expected: @2005-05-10T10:20:30
actual  : @2005-05-10T10:20:30-06:00     -> fail, although it is the same value at the evaluation offset (#84)

expected: @2014-01-01T12:05:05.955+00:00
actual  : @2014-01-01T12:05:05.955Z      -> fail, although Z and +00:00 are the same offset (#83)

#142 sends the evaluation timestamp and offset, defaulting to UTC. On its own that fixes no test, because the comparison is still textual. This PR changes the comparison.

Change

DateTime equality (src/shared/datetime-comparison.ts):

• Two DateTimes with at least an hour are equal when, at the same precision, they denote the same instant. So Z = +00:00, and @…T16:20:30Z = @…T10:20:30-06:00.
• A side written without an offset is read at the evaluation offset.
• Different precisions stay unequal. Dates, date-precision DateTimes and Times keep plain comparison.
• With no evaluation offset known, an offset-less value only equals another offset-less value, as before.

Which offset the evaluation ran at:

• If the server honours the timestamp parameter or the Timezone header (see Send an evaluation request timestamp, defaulting to UTC, with every test #142), it is the test's requested offset: UTC by default, or the test's evaluationTimezoneOffset / evaluationDateTime.
• If it honours neither, it is the server's own offset. The start-of-run probe evaluates an offset-less DateTime and records the offset it comes back with as evaluationRequest.serverTimezoneOffset, and comparison uses it. This judges each result against the evaluation that actually produced it, rather than against an offset the server never used. The run log states it, e.g. results are compared at the server's own offset -06:00.

time-hasOffset: a result whose _valueDateTime, or Period _start / _end, carries time-hasOffset: false (Using CQL With FHIR) is read as having no offset. This is @brynrhodes's request from #77 / #119.

The evaluation offset is threaded through resultsEqual into lists, tuples and interval boundaries. The README section added in #142 now explains the comparison, and the results schema gains serverTimezoneOffset.

Verification

Against HAPI FHIR 8.10.0 / CQL engine 5.3.0 (clinical-reasoning 4.12.0). This server ignores both mechanisms, and the probe reports serverTimezoneOffset: -06:00. Full cql-tests suite:

	pass	fail	skip	error
main	1639	170	14	0
this branch	1665	144	14	0

Exactly 26 tests move from fail to pass, and no other record changes status or actual value across all 1823:

• 22 where the expected value has no offset and the actual has the server's -06:00, for example DateTimeAdd5Seconds, DateTimeMillisecond, HighBoundaryDateTimeMillisecond, ToDateTime3, DateTimeMin, DateTimeMax;
• 1 Z vs +00:00 (ToDateTime6);
• 3 intervals with DateTime boundaries (TestPeriod1, TestPeriod2, DateTimeIntervalTest).

All 22 offset cases carry the same -06:00, including January values when the host's zone is at -07:00. So the engine uses one request-level offset, as CQL specifies, not a zone, which is what makes a single observed server offset sound.

270 unit tests pass (252 before, 18 new). They cover:

• equality of offsets and instants, and that different instants and precisions stay unequal;
• the old behaviour when no offset is known;
• non-DateTime strings left alone;
• nesting in lists, tuples and intervals;
• time-hasOffset on values and Period boundaries;
• the effective-offset rule, and runTest passing or failing against a server that ignores the request.

One bug was caught while testing: instants are built with setUTCFullYear rather than Date.UTC, which reads years 0–99 as 1900–1999 and would have made @0001 equal @1901.

Carried over from #132

#132 is closed in favour of this PR, so its review discussion is reproduced here:

@cmoesel (2026-09-01): Thanks. You can resolve #83 when this gets merged.

This PR covers #83's case (ToDateTime6, Z vs +00:00), so it carries Closes #83, along with #84. Because it is stacked on #142, GitHub closes those issues automatically only if it merges into main. If it merges into evaluation-timestamp-and-offset first, #83 and #84 need closing by hand once the change reaches main.

Notes

• Equate the Z and +00:00 spellings of UTC when comparing temporal lite… #132 made Z equal +00:00 with a narrow string check at the same place in results-utils.ts. This PR covers that case as part of instant equality, so Equate the Z and +00:00 spellings of UTC when comparing temporal lite… #132 is closed in its favour.
• The remaining DateTime failures on this engine are not comparison problems:
  • 11 lose hour or minute precision in FHIR's dateTime (@2005-05-10T10 arrives as @2005-05-10T) — the engine could send time-precision, which the runner already honours (Honour the time-precision extension on dateTime, time and Period boundaries #135);
  • the others are engine defects, e.g. expand returning DateTimes for Dates (expand Interval of Dates is returning intervals of DateTime clinical_quality_language#1770).
• tsc --noEmit still reports the two pre-existing rest-routes.ts errors on main, which Declare the /jobs/:id route parameter type so the server type-checks #139 fixes.

🤖 Generated with Claude Code

[bryantaustin13]

I ran this PR against a second engine, the JavaScript cql-execution test-server, to check that the comparison change holds beyond the Java engine.

Setup

• Engine: cql-execution 4.0.0-beta.1 (b1a4c3e) with @cqframework/cql 5.2.0.
• Tests: cql-tests f591d9e, the commit main pins.
• Config: conf/cql-execution-local.json, minus its 47 skips that cite runner issues (Test Runner Not Detecting Equal DateTimes (+00:00 vs Z) #83, Test Runner Not Detecting Equal DateTimes (Offset vs No Offset) #84, Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85, Test Runner Not Detecting Equal Lists on Interval<Time> #94, Honour the time-precision extension on dateTime, time and Period boundaries #135). The other 34 skips were kept.

Code	Pass	Fail	Skip	Error
main, original config	1692	64	86	0
main, runner-issue skips removed	1696	107	39	0
#142	1696	107	39	0
this PR (#145, includes #142)	1736	67	39	0

So this PR fixes 40 tests on cql-execution, with no regressions:

• Test Runner Not Detecting Equal DateTimes (+00:00 vs Z) #83 (+00:00 vs Z): all 4 previously skipped tests pass.
• Test Runner Not Detecting Equal DateTimes (Offset vs No Offset) #84 (DateTime with vs without an offset): 34 of the 37 previously skipped tests pass.
• Two tests that weren't skipped also go from fail to pass: HighBoundaryDateTimeMillisecond and LowBoundaryDateTimeMillisecond.

The probe reports that this server ignores both the timestamp parameter and the Timezone header, and evaluates at Z. So these results come from comparing at the server's effective offset, which is the case this PR was designed for.

The 3 #84-skipped tests that still fail aren't comparison problems:

• ToDateTime2 and ToDateTime3: ToDateTime('2014-01-01T12:05') comes back as @2014-01-01T12:05-06:00, the host offset, while literals get the request offset +00:00. Inside the engine, ToDateTime('2014-01-01T12:05') = @2014-01-01T12:05 is false. CQL 1.5.3, ToDateTime: "If no timezone offset is supplied, the timezone offset of the evaluation request timestamp is assumed." This looks like a cql-execution issue; I can open one there.
• DateTimeToString2: the result is a string with an offset, and the test expects none. That's Wrong Expected Outcome for ToString of DateTime with No Offset Specified cql-tests#73.

Other findings from this run, not related to this PR:

• The 2 tests skipped for Honour the time-precision extension on dateTime, time and Period boundaries #135 and the 2 skipped for Test Runner Not Detecting Equal Lists on Interval<Time> #94 already pass on main, so those 4 skips in conf/cql-execution-local.json could go now.
• The 2 tests skipped for Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 (ExceptTime2, ExceptTimeInterval) still fail. The runner treats open and closed numeric boundaries as equivalent, but not Time boundaries; for example, [@T05:59:59.999, @T08:59:59.999) against [@T05:59:59.999, @T08:59:59.998]. I'll follow up on Test Runner Not Detecting Equal Intervals (Open vs Closed Boundaries) #85 separately.

On the Java engine (HAPI FHIR 8.12.0 / clinical-reasoning 4.13.0 / CQL engine 5.4.0, cql-tests 9e92193), the result is unchanged: #141 + #142 + #145 together fix the same 67 tests as before, with no regressions. The absolute totals in the description came from an older local copy of the tests; the fixes are the same.

Once this merges, the #83/#84 skips can come out of conf/cql-execution-local.json. I'm happy to do that as a follow-up.

[bryantaustin13]

Follow-up on ToDateTime2 / ToDateTime3 from my comment above: I've opened cqframework/cql-execution#385 for the engine side. With the fix proposed there applied locally, both tests pass with this PR's comparison, and no other test changes (1736 → 1738 pass on cql-execution).