release: qualify the 0.9.6 notes for the explicit-choice fix and legacy stored zones

Co-authored-by: Joshua <joshua@cnjmail.com>
Co-committed-by: Joshua <joshua@cnjmail.com>

RELEASE_NOTES.md

@@ -5,7 +5,8 @@
 ### Scope
 
 Patch release carrying the household time-zone fix onto `main` (PR #275, task
-6351b36d "Time zone errors").
+6351b36d "Time zone errors"), plus its release-review correction (PR #277, task
+45243478).
 
 ### Behaviour
 
@@ -20,8 +21,10 @@ Patch release carrying the household time-zone fix onto `main` (PR #275, task
   while it is sleeping, and re-reads the stored zone before sweeping, so it no
   longer fires at the old (UTC) rollover.
 - An admin-chosen zone — including an explicit choice of empty (API-host local)
-  — still wins over the reported zone. An invalid reported zone is logged and
-  ignored; the panel keeps serving on the stored settings.
+  — still wins over the reported zone: any admin update that supplies
+  `timezone` is recorded as an explicit choice (`timezone_configured` true). An
+  invalid reported zone is logged and ignored; the panel keeps serving on the
+  stored settings.
 
 ### Requirements
 
@@ -33,11 +36,18 @@ Patch release carrying the household time-zone fix onto `main` (PR #275, task
   database backup is required for this release.
 - Deployment note: this fix needs BOTH the API service and the HA integration
   upgraded. The integration supplies the zone and the API adopts it; upgrading
-  only one side leaves the previous behaviour. An install whose `timezone` was
-  previously set — or explicitly cleared to host-local — keeps that choice.
+  only one side leaves the previous behaviour. An install that sets or clears
+  its zone on 0.9.6 or later keeps that choice; see Known limitations for a zone
+  stored by an older release.
 
 ### Known limitations
 
+- A zone stored by a release before 0.9.6 without the explicit-choice marker
+  (for example through the previously documented
+  `PATCH /api/v1/admin/settings {"timezone": ...}`) is not distinguishable from
+  an automatically adopted value, so 0.9.6 adopts Home Assistant's reported zone
+  over it once. If a zone different from Home Assistant's is intended, re-save
+  it in the admin Preferences, which now records the explicit choice.
 - If `timezone` is empty and `timezone_configured` is true (an explicit
   "host local" choice), that choice is respected and the API host's zone (UTC
   on the standard deployment) still applies until an admin selects a zone in

custom_components/nestquest/core/settings_store.py

@@ -184,6 +184,11 @@ async def update_settings(
     in one atomic upsert; the updated settings are returned.  The whole
     read → merge → write span runs inside the per-database settings
     lock, so concurrent updates queue instead of interleaving.
+
+    Supplying ``timezone`` without ``timezone_configured`` records the
+    zone as the admin's explicit choice (``timezone_configured`` is
+    persisted ``True`` in the same write); an explicitly supplied
+    ``timezone_configured`` is kept exactly as given.
     """
     if not isinstance(changes, Mapping):
         raise ValueError(
@@ -199,6 +204,10 @@ async def update_settings(
         raise ValueError(
             f"unknown settings field(s): {listed}; known fields: {known}"
         )
+    if "timezone" in changes and "timezone_configured" not in changes:
+        # An admin-supplied zone is an explicit choice, so Home
+        # Assistant's reported zone must no longer replace it.
+        changes = {**changes, "timezone_configured": True}
     async with _settings_lock(database):
         current = await load_settings(database)
         return await _write_merged(database, current, changes)

tests/test_api_household_clock.py

@@ -445,6 +445,44 @@ async def test_admin_chosen_zone_wins_over_reported_zone(
     assert stored["timezone_configured"] is True
 
 
+# --- a timezone-only admin update is an explicit choice (task 45243478) ------
+
+
+@pytest.mark.parametrize("chosen", ["America/Los_Angeles", ""])
+async def test_timezone_only_admin_update_is_an_explicit_choice(
+    household: SimpleNamespace, chosen: str
+) -> None:
+    """``PATCH {"timezone": ...}`` alone marks the zone admin-chosen."""
+    await _adopt_new_york(household)
+    response = await household.client.patch(
+        "/api/v1/admin/settings",
+        json={"timezone": chosen},
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 200
+    assert response.json()["timezone_configured"] is True
+    # A conflicting report is no longer adopted.
+    await _panel_pack_bag(household, "America/Chicago")
+    stored = await _stored_settings(household)
+    assert stored["timezone"] == chosen
+    assert stored["timezone_configured"] is True
+
+
+async def test_explicit_timezone_configured_false_is_respected(
+    household: SimpleNamespace,
+) -> None:
+    """A supplied ``timezone_configured`` is persisted exactly as given."""
+    response = await household.client.patch(
+        "/api/v1/admin/settings",
+        json={"timezone": "America/Chicago", "timezone_configured": False},
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 200
+    assert response.json()["timezone_configured"] is False
+    await _panel_pack_bag(household, HOUSEHOLD_ZONE)
+    assert (await _stored_settings(household))["timezone"] == HOUSEHOLD_ZONE
+
+
 async def test_invalid_reported_zone_is_ignored(
     household: SimpleNamespace,
 ) -> None: