MAINT-10: maintenance start hour in local time, default 19:00

The start hour was compared with the UTC hour, so the shipped 10 started at 12:00 in a Belgian summer. It is now read in Home Assistant's time zone (fallback: the container's TZ, then UTC, one log line says which), and the default moves to 19. DST: a missing hour starts at the first hour after the jump; a repeated hour starts only in its first pass. Stored options are not rewritten: a saved 10 now means 10:00 local (DOCS, CHANGELOG). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 22:52:05 +02:00
parent 35cdffe766
commit 02c0a3dd7b
13 changed files with 678 additions and 27 deletions
@@ -0,0 +1,51 @@
+# MAINT-10 — the maintenance start hour is local time, default 19:00
+
+Owner decision 2026-09-29 (option A). `maintenance_start_hour` was compared
+with the UTC hour, so the shipped 10 started at 12:00 in a Belgian summer and
+11:00 in winter. It is now read on the site's local clock, and the default moves
+to 19 so the drain runs into the evening and night rather than the solar day.
+
+Merges only after SAFETY-83 (peak guard outranks the drain at N=1): evening
+drains meet higher house loads.
+
+## 1. Which zone
+
+Home Assistant's `time_zone` (`GET /core/api/config`, 3 s budget) at startup,
+else the container's `TZ`, else UTC. One log line says which (WARNING only for
+UTC). Resolved once per start: a zone change in HA takes effect on the next
+add-on restart. The add-on image has tzdata (checked in `amd64-base:3.20`); the
+CI image does not, so the tests grade DST on `tariff._EUTimezone` too.
+
+## 2. DST
+
+`maintenance.in_start_slot()` works from UTC instants only, so it does not
+depend on how a tzinfo resolves a missing or doubled wall time:
+
+- normally the slot is the local hour `start_hour`;
+- clocks forward and the hour does not exist: the first hour after the jump;
+- clocks back and the hour happens twice: the first pass only. Without this an
+  aborted start (90 min cooldown) would start again in the 120 min repeated hour.
+
+Every day has exactly one 60 min slot for every hour 0-23: checked against
+zoneinfo for Europe/Brussels, America/New_York, America/Santiago (midnight
+transitions), Asia/Kathmandu (+05:45) and Australia/Lord_Howe (30 min DST)
+over all of 2026.
+
+## 3. Existing installs
+
+The Supervisor merges the shipped defaults under the STORED options, and saving
+the settings stores every key (the reference install's blob has all 76). So
+almost every existing install keeps its stored 10, which now means 10:00 local
+instead of 12:00 (summer) or 11:00 (winter). Only a blob without the key gets 19.
+The add-on does not rewrite a stored option: a silent migration would override
+an operator's choice with no way to tell it apart from the old default. DOCS
+and the CHANGELOG tell the owner to set 19 if they want the evening start.
+`tools/supervisor_shape_probe.py` §I measures this on Supervisor 2026.08.0.
+
+## 4. What does not change
+
+Only the start decision (`Maintenance.wants_start`) and the Home screen's shown
+start time read the zone. `test_maint10.py` part 9 runs the real Controller
+with start hour 11 UTC against 13 Europe/Brussels (the same instant) and with
+12 UTC against 14 local (not the start hour): every command, claim, reason and
+log line is identical. A `Maintenance` built without a zone reads UTC, as before.