fix(sensor): read report timestamps in each unit's own timezone

[andrew-blake]

Summary

Stacks on docs/pr-body-skill (#277) and needs nothing from it beyond a base: that branch is a docs-only change queued to merge first.

The /report/v1/ endpoints keep each unit's datapoints in that unit's own local timezone, and /context names the zone per unit as an IANA string on the unit node. Requests now declare their window as UTC so the server converts it, and returned stamps are interpreted in the unit's zone before becoming a last_reading. Two faults compounded to hide each other: a window sent without an offset is taken as already-local, so it stops short of the present by the unit's offset, and a local stamp parsed as UTC yields an age that much too young. The combination presents a reading at least offset-hours old as current, which is the condition last_reading exists to expose (#200). Measurements, the to-shift test that identifies the behaviour on any unit, and the superseded evidence they replace are in ADR-022 and docs/api/atw-api-reference.md.

Key changes

• parse_api_timestamp accepts a source timezone, defaulting to UTC so a caller without one is unaffected.
• AirToAirUnit and AirToWaterUnit carry time_zone, read from the unit node's timeZone key.
• _report_params marks from and to as UTC, which makes the server convert the window instead of reading it as local time.
• The three report client methods accept a timezone and pass it to the point parsers.
• resolve_unit_timezone resolves a unit's zone through Home Assistant's async resolver, falling back to UTC with a debug line for a missing or unrecognised name.
• The coordinator and the telemetry tracker resolve each unit's zone per poll and pass it down.
• The mock server serves timeZone on every unit node and stamps report points in that unit's zone, so a mock-backed run exercises the conversion.
• ADR-022 and both API references now describe the timezone behaviour and the test that establishes it.

What changes for users

• Outdoor temperature and heat pump water temperature sensors reach more recent readings, so they update sooner on any unit outside UTC.
• last_reading on those sensors shows the instant the unit recorded the value. On a unit that has not produced a newer reading, the displayed value moves back by that unit's UTC offset, because the age it showed understated the truth by exactly that much. Nothing to do: the sensor value is unchanged and no history is rewritten.
• Installations on GMT see no change while their offset is zero.

Risks accepted

• Devices west of UTC are unexercised. Converting a UTC window into a zone behind UTC moves from earlier, which can widen the span by a calendar day, and internaltemperatures returns 500 for windows spanning three. Every device reachable for testing sits at +1 or +2, so this is reasoned rather than measured. It would surface as water temperatures missing for users in the Americas, and the fix reverts to sending an offset-less window.
• The vendor's own client sends a different request form. Its app sends unit-local wall-clock times carrying no offset, so the server's handling of an explicit offset rests on measurement alone, and a server-side change could break it while the vendor's path keeps working. Detection is a reading age that stops advancing, checked with the to-shift probe. The fallback is to send unit-local wall-clock, which requires the unit's zone on the request path and so makes a unit with no reported zone worse off.
• One hour twice a year is ambiguous. A naive local stamp inside a daylight-saving autumn fold resolves to the earlier offset, so a reading age can be an hour out during that hour. Disambiguating needs the neighbouring points' ordering, which is not worth it for an age. Marked in parse_api_timestamp.
• Zone 2 remains unverified against real hardware, unchanged by this work: no two-zone device is available.

AI Disclosure

• No AI/agent tooling was used
• AI/agent tooling assisted; I reviewed and ran the change myself before submitting

Testing

• make test: 395 api, 256 integration, 16 e2e. make test-integration-floor: 256 on the hacs.json Home Assistant floor.
• make type-check and make pre-commit clean.
• The three report cassettes re-recorded against the real API, since the request genuinely changes. Recorded windows carry the UTC marker, gitleaks clean, credentials and device identifiers scrubbed. Superseded cassettes archived outside the diff.
• Real API, one Europe/Stockholm unit, two requests one after the other differing only in whether the window declares UTC: the declared one reaches 89 minutes of data the other cannot, and both echo an identical from, so the window gains no calendar days.
• Devserver against the mock: two units in different building zones stamp an hour apart and resolve to the same instant, and their sensor ages equal the true poll age. No blocking-call or zoneinfo warning in the Home Assistant log, which is the only tier that can check that, since tests/api runs without Home Assistant.
• Prod deploy. Two units that produced no newer reading show last_reading move back by exactly their offsets, 60 minutes for a Europe/London unit and 120 for a Europe/Stockholm one, on identical naive stamps. A restart re-polls, so a freshness improvement proves nothing here and the backward shift is the signal. No new integration error class, and the only blocking-call warnings name an unrelated third-party integration. Prod is running this from this branch on top of the unmerged stack below it.
• The reading age column moves in both directions and that is expected: it changes by the unit's offset minus whatever fresher data the wider window reached, so it fell on nine sensors and rose on two. It is not a pass or fail signal on its own.
• The mock stamp guard mutation-tested in both failure directions, confirming it fails when either is reintroduced and that no other test in the suite does.
• Prod soak across a full telemetry cycle: deployed and left running, observed so far for minutes only.
• Zone 2 datasets on a real two-zone device.
• A device at a negative UTC offset.

[codecov]

Codecov Report

❌ Patch coverage is 96.87500% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.22%. Comparing base (2269acd) to head (77683f2).

Files with missing lines	Patch %	Lines
custom_components/melcloudhome/helpers.py	91.66%	1 Missing ⚠️

Additional details and impacted files

@@                 Coverage Diff                 @@
##           docs/pr-body-skill     #283   +/-   ##
===================================================
  Coverage               93.21%   93.22%           
===================================================
  Files                      44       44           
  Lines                    2904     2922   +18     
===================================================
+ Hits                     2707     2724   +17     
- Misses                    197      198    +1     

Flag	Coverage Δ
unittests	93.22% <96.87%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
custom_components/melcloudhome/api/client.py	91.13% <100.00%> (ø)
custom_components/melcloudhome/api/models_ata.py	98.98% <100.00%> (+0.01%)	⬆️
custom_components/melcloudhome/api/models_atw.py	100.00% <100.00%> (ø)
custom_components/melcloudhome/api/parsing.py	100.00% <100.00%> (ø)
custom_components/melcloudhome/coordinator.py	96.46% <100.00%> (+0.02%)	⬆️
...ustom_components/melcloudhome/telemetry_tracker.py	94.59% <100.00%> (+0.15%)	⬆️
custom_components/melcloudhome/helpers.py	97.95% <91.66%> (-2.05%)	⬇️

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2269acd...77683f2. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.