Absent CQL timezone offset is emitted as UTC, not the evaluation-request offset

[baseTwo]

Summary

When converting a CQL System.DateTime that carries no timezone offset to FHIR, the SDK emits UTC (Z). The CQL specification says an absent offset defaults to the timezone offset of the evaluation request, not UTC.

From spec/cql/condensed/02-authorsguide.md:

Only DateTime values may specify a timezone offset, either as UTC ( Z ), or as a timezone offset. If no timezone offset is specified, the timezone offset of the evaluation request timestamp is used.

The only component that is ever defaulted is the timezone offset component. If no timezone offset component is supplied, the timezone offset component is defaulted to the timezone offset of the timestamp associated with the evaluation request.

The same rule is restated in 02-authorsguide.md (extracting a defaulted offset yields the request's offset, not null) and in spec/cql/condensed/04-logicalspecification.md.

Split out of the review of #1458, which introduced the offset emission required by #1506 and documents this deviation in docs/releases/vnext/1458-time-precision-extension.md. #1458 is correct to emit an offset — FHIR requires one once hours and minutes are present — this issue is about which offset.

Impact

Every FHIR dateTime the SDK emits from an offset-less CQL value asserts an instant that is wrong by the evaluation request's offset whenever the request is not UTC — up to ±14 hours. It affects dateTime values and both boundaries of a Period converted from an Interval<DateTime> or Interval<Time>, i.e. the artifacts a receiver validates, stores and may re-evaluate against.

A value sitting near a measurement-period boundary can be shifted across it. Nothing signals the substitution: the output is lexically valid FHIR, so no validator complains.

This is not an edge case. Cql/Cql.Runtime/Operators/CqlOperators.DateTimeOperators.cs leaves the offset components null whenever CQL's DateTime(...) constructor is given no offset, so the SDK never applies the spec's default at construction either — every offset-less CQL literal reaches the converter unset.

Observed Behavior

With an evaluation request at +02:00 and the CQL value @2014-02-01T10:30:00:

• CQL semantics: the value denotes 2014-02-01T10:30:00+02:00, i.e. 08:30Z.
• Emitted FHIR: 2014-02-01T10:30:00Z — two hours later than the value the engine computed with.

Root Cause

Two independent gaps:

1. Construction — CqlOperators.DateTimeOperators.cs (DateTime(int? year, …, decimal? offset)) only populates osHours/osMinutes when offset.HasValue, so an absent offset stays absent instead of being defaulted to the evaluation request's offset as the spec requires.
2. Conversion — Cql/Cql.Firely/FhirTypeConverter.cs has to materialise some offset to satisfy FHIR, and cannot see the evaluation request: FhirCqlContext.CreateOperators builds nowIso8601 from its now argument and hands it to CqlOperators, while the converter is created independently via FhirTypeConverter.Create(modelInspector, cacheSize). UTC is therefore a stand-in chosen for lack of the real value.

Fixing (1) alone would make (2) moot for CQL-authored values, since the offset would already be populated by the time the converter sees it — but it is not a free change, because of a third gap found while reviewing #1458:

3. Populating the offset at construction silently flips an existing comparison branch. Cql/Cql.Abstractions/Primitives/CqlDateTime.cs skips normalization when exactly one side has an offset (if (self.RationalOffset.HasValue ^ other.RationalOffset.HasValue)), under a comment stating that "when one datetime has a timezone specified and the other does not, the timezone should be ignored. Functionally, this means don't normalize" — and it does so at four arms: :340, :369, :401, :440, which are Hour, Minute, Second and Millisecond. Those are exactly the four precisions the spec names in "normalize … but only when the comparison precision is hours, minutes, seconds, or milliseconds", so the branch is the deliberate inverse of the rule at every precision the rule covers, with tests pinning it. Default the offset at construction and the XOR stops firing for CQL-authored values, so those comparisons switch to the normalized path — a change in results, arriving without anyone touching the comparison code. That is also what rules out a partial fix: all four arms get re-derived, or none does.

4. Nothing outside Now()/TimeOfDay()/Today() can currently see the evaluation request, so none of the normalization rules above is implemented today; they need the request timestamp threaded into the comparison, duration and extraction paths, not only into construction.

Expected Behavior

An offset-less CQL DateTime converts to FHIR carrying the evaluation request's timezone offset. When no evaluation timestamp was supplied to the context, the fallback must be a deliberate, documented choice rather than an implicit one.

Acceptance Criteria

• Decide and document where the default is applied: at DateTime/Time construction in CqlOperators (spec-faithful, fixes every downstream consumer at once) or at conversion in FhirTypeConverter (narrower, but leaves CQL-internal semantics still deviating).
• An offset-less CQL DateTime converted with an evaluation request at a non-UTC offset emits that offset, not Z, on the padded path, the second-or-finer path, and both Period boundary paths.
• The behaviour when no evaluation timestamp is supplied is explicit in code and documented in the XML docs.
• timezoneoffset from X on a value whose offset was defaulted returns the evaluation request's offset rather than null, per 02-authorsguide.md.
• Tests cover a non-UTC evaluation request end to end, including a value near a measurement-period boundary that the current UTC substitution would move across it.
• Release-note fragment records the change, and the deviation note added by Pad partial-precision times/dateTimes for FHIR #1458 to docs/releases/vnext/1458-time-precision-extension.md (or its consolidated successor) is removed or updated.
• Comparison, duration between and difference between normalize to the evaluation request's offset at hour-or-finer precision, and the existing "one side has no offset ⇒ do not normalize" branch is re-derived at all four arms against the defaulted-offset world rather than left to flip implicitly.
• time from X on a DateTime normalizes to the evaluation request's offset.
• Existing tests whose names assert the UTC substitution (…_AssumesUtc…, RoundTripCqlDateTime_FhirDateTime_RestoresPrecisionAndAcquiresUtcOffset) are renamed or re-pinned to the new behaviour.

[alexzautke]

The conversion-side portion of this issue landed on PR #1458 in 0b7973c9b: FhirCqlContext.CreateOperators threads the now argument's offset into FhirTypeConverter, overridable via the new FhirCqlContextOptions.OverrideConverterTimezoneOffset or FhirTypeConverter.Create(model, cacheSize, defaultTimezoneOffset). Fallback chain: option → now's offset → UTC — and the UTC fallback matches the UTC evaluation timestamp CqlOperators synthesizes when now is omitted (now ?? DateTimeIso8601.UtcNow), so with no timestamp supplied there is no deviation left on this path.

Status against the acceptance criteria (not ticking boxes on your issue — please tick what you agree with):

• Decide and document where the default is applied — decided: at conversion, for now. The construction-side gap is documented in the code comment, the fragment, and below.
• Offset-less CQL DateTime under a non-UTC request emits that offset — done for the padded path, the second-or-finer path, and both Interval<DateTime> → Period boundaries, with end-to-end tests through FhirCqlContext.WithDataSource(now: …). Two deliberate exceptions keep UTC, found by adversarial review of the first implementation: (1) the 0001-01-01-anchored boundaries of Interval<Time> — a positive default (any host east of Greenwich) would render e.g. @T00:00:00 as 0001-01-01T00:00:00+02:00, whose UTC instant precedes year 1: FhirDateTime.IsValidValue rejects it and the SDK's own FHIR→CQL conversion returns null. Since the CQL default rule is about DateTime values and Time has no offset to default, the synthetic anchor stays Z. (2) Offset-less DateTime values on the first/last representable day whose default-offset rendering would leave the range (@0001-01-01T00:30:00 under +02:00, @9999-12-31T23:30:00 under -05:00) — guarded by component math, edge-tested against IsValidValue on both sides of the boundary.
• Behaviour with no evaluation timestamp is explicit and documented — done (XML docs on the option and overload, fragment note, code comment).
• timezoneoffset from X returns the request's offset — NOT done; construction in CqlOperators.DateTimeOperators still leaves the offset null. This remains the open scope of this issue.
• Tests cover a non-UTC request end to end — done for the conversion paths (+02:00 request, option overrides incl. TimeSpan.Zero beating a non-UTC now); a measurement-period-boundary-crossing scenario as such is not among them, so I left this one to your judgement.
• Fragment records the change / deviation note updated — done (the note now describes the fallback chain and narrows the deviation to the construction side).
• …AssumesUtc… test names renamed/re-pinned — done.

Perf note: converters for the default ModelInspector are now strongly cached per (cacheSize, offset) — without that, every non-UTC host would have lost the rooted converter singleton and rebuilt it (~5–10 ms) after each Gen2 GC in a context-per-request service.

---

Generated by Claude Code

[alexzautke]

Keeping this open, and worth stating plainly before anyone picks it up: what remains here is a change to CQL evaluation semantics, not the addition of a default. The conversion half landed in #1458, which makes the emitted FHIR right; the construction half changes what the engine computes with, and it is easy to leave half-done.

The specification does not only say the request's offset is used when none is given — it says a value whose offset was defaulted behaves as though it carried that offset everywhere. Three consequences, verified against the mirror:

• timezoneoffset from X must return the evaluation request's offset rather than null for such a value (02-authorsguide.md; the logical spec states the construction rule itself at 04-logicalspecification.md:2476, "If timezoneOffset is not specified, it is defaulted to the timezone offset of the evaluation request"). Already an acceptance criterion above.
• Comparisons, duration between and difference between normalize to the request's offset when the precision is hours or finer — which is only meaningful once the offset is actually populated (02-authorsguide.md:1595 and :1779; 04-logicalspecification.md:2512, :2538, and the per-operator restatements at :2589, :2619, :2649, :2805).
• Extracting Time from a DateTime normalizes the same way (02-authorsguide.md:1669, 04-logicalspecification.md:2690).

Two concrete SDK facts that make the "half-done" risk real rather than theoretical:

1. Nothing outside Now()/TimeOfDay()/Today() can see the evaluation request. NowValue has exactly those three readers (CqlOperators.DateTimeOperators.cs:221, :404, :410) — no comparison, duration, difference or time-extraction path consults it. So none of the three normalization rules is implemented today, and implementing them needs the request timestamp threaded into those paths, not just into construction.

2. Populating the offset at construction silently flips an existing comparison branch. CqlDateTime.CompareTo (Cql/Cql.Abstractions/Primitives/CqlDateTime.cs:340, and the sibling arms for the finer precisions) deliberately skips normalization when exactly one side has an offset:

   var left = selfInUtc; var right = otherInUtc;
   if (self.RationalOffset.HasValue ^ other.RationalOffset.HasValue) { left = self; right = other; }

   with the comment "when one datetime has a timezone specified and the other does not, the timezone should be ignored. Functionally, this means don't normalize", and tests pinning it. Default the offset at construction and that XOR stops firing for CQL-authored values, so those comparisons switch to the normalized path — a behavioural change in results, arriving without touching the comparison code. Whoever does this must decide deliberately whether that branch (and the tests behind it) still expresses the intended rule, rather than discovering it as a test failure.

Suggested additions to the acceptance criteria above, if you agree (not editing your body):

• Comparison, duration between and difference between normalize to the evaluation request's offset at hour-or-finer precision, and the existing "one side has no offset ⇒ do not normalize" branch in CqlDateTime.CompareTo is re-derived against the defaulted-offset world rather than left to flip implicitly.
• time from X on a DateTime normalizes to the evaluation request's offset.
• The evaluation request timestamp is reachable from the comparison/duration/extraction paths, not only from Now()/TimeOfDay()/Today().

---

Generated by Claude Code