Release correction: persist an explicit timezone choice (timezone_configured) (#268)

Co-authored-by: dev_agent <17+dev_agent@code.cubecraftcreations.com>
Co-committed-by: dev_agent <17+dev_agent@code.cubecraftcreations.com>

tests/test_api_admin_settings.py

@@ -13,7 +13,7 @@ proven against the DATABASE the routes wrote, not a parallel copy.
 Proven per the done-condition, everything read back through the API:
 
 - ``GET /api/v1/admin/settings`` returns the current effective settings
-  — the eleven documented fields at their defaults on a fresh database.
+  — the twelve documented fields at their defaults on a fresh database.
 - ``PATCH /api/v1/admin/settings`` PERSISTS the supplied fields and the
   NEXT read reflects them; a later partial update merges onto the
   current effective settings (omitted fields keep their stored value),
@@ -60,7 +60,7 @@ _dao_meta = importlib.import_module("nestquest_core.dao_meta")
 SETTINGS_META_KEY = "settings"
 
 #: The all-defaults effective settings a fresh database reports — the
-#: documented eleven fields, asserted literally so the payload contract is
+#: documented twelve fields, asserted literally so the payload contract is
 #: pinned here, independent of the core constants.
 DEFAULT_SETTINGS = {
     "horizon_days": 14,
@@ -74,6 +74,7 @@ DEFAULT_SETTINGS = {
     "end_of_day_report_enabled": True,
     "celebration_enabled": True,
     "timezone": "",
+    "timezone_configured": False,
 }
 
 
@@ -104,7 +105,7 @@ async def settings_client(temp_db_path: str) -> SimpleNamespace:
 async def test_get_settings_returns_defaults_on_a_fresh_database(
     settings_client: SimpleNamespace,
 ) -> None:
-    """GET returns the eleven documented fields at their defaults."""
+    """GET returns the twelve documented fields at their defaults."""
     response = await settings_client.client.get(
         "/api/v1/admin/settings", headers=_admin_headers()
     )
@@ -140,7 +141,7 @@ async def test_update_persists_and_the_next_read_reflects_it(
     assert reread.status_code == 200
     assert reread.json() == expected
 
-    # ...and the DATABASE holds the merged document: the complete eleven
+    # ...and the DATABASE holds the merged document: the complete twelve
     # fields, keyed by field name, under the well-known meta_state key.
     raw = await _dao_meta.MetaStateDao(settings_client.database).get(
         SETTINGS_META_KEY
@@ -222,6 +223,40 @@ async def test_null_resets_a_field_to_its_default(
     assert reread.json()["horizon_days"] == 14
 
 
+async def test_timezone_configured_round_trips_with_an_explicit_empty_zone(
+    settings_client: SimpleNamespace,
+) -> None:
+    """An explicit empty (host-local) zone persists as configured.
+
+    The admin clearing the zone PATCHes ``timezone: ""`` together with
+    ``timezone_configured: true``; the NEXT read — a reopened settings
+    screen — sees the marker, so the empty value is a persisted choice
+    rather than a fresh install to auto-set.
+    """
+    client = settings_client.client
+    fresh = await client.get("/api/v1/admin/settings", headers=_admin_headers())
+    assert fresh.json()["timezone_configured"] is False
+
+    patched = await client.patch(
+        "/api/v1/admin/settings",
+        json={"timezone": "", "timezone_configured": True},
+        headers=_admin_headers(),
+    )
+    assert patched.status_code == 200
+    expected = {**DEFAULT_SETTINGS, "timezone_configured": True}
+    assert patched.json() == expected
+
+    reread = await client.get(
+        "/api/v1/admin/settings", headers=_admin_headers()
+    )
+    assert reread.json() == expected
+    raw = await _dao_meta.MetaStateDao(settings_client.database).get(
+        SETTINGS_META_KEY
+    )
+    assert raw is not None
+    assert json.loads(raw)["timezone_configured"] is True
+
+
 # --- validation: rejected values never change the stored settings -------
 
 
@@ -238,6 +273,8 @@ async def test_null_resets_a_field_to_its_default(
         ({"morning_summary_enabled": "yes"}, "morning_summary_enabled"),
         ({"celebration_enabled": 1}, "celebration_enabled"),
         ({"notify_target": 5}, "notify_target"),
+        ({"timezone_configured": "true"}, "timezone_configured"),
+        ({"timezone_configured": 1}, "timezone_configured"),
     ],
 )
 async def test_invalid_value_is_rejected_and_stored_settings_unchanged(

tests/test_api_household_clock.py

@@ -236,6 +236,25 @@ def test_from_options_reads_and_resiliently_defaults_timezone() -> None:
     )
 
 
+def test_settings_timezone_configured_defaults_false_and_is_strict() -> None:
+    assert _settings.NestQuestSettings().timezone_configured is False
+    assert _settings.NestQuestSettings.from_options({}).timezone_configured is False
+    assert (
+        _settings.NestQuestSettings.from_options(
+            {"timezone_configured": True}
+        ).timezone_configured
+        is True
+    )
+    for value in ("true", 1, None):
+        with pytest.raises(ValueError, match="timezone_configured"):
+            _settings.NestQuestSettings(timezone_configured=value)
+        if value is not None:
+            with pytest.raises(ValueError):
+                _settings.NestQuestSettings.from_options(
+                    {"timezone_configured": value}
+                )
+
+
 # --- the missed-sweep scheduler ----------------------------------------------