test: seed pre-existing instance/history and add concurrency test (NQ-70-001, NQ-70-002)

Deactivate and reactivate a quest definition (Feature 06, task 5)
2026-09-17 09:38:37 -04:00 · 2026-09-17 09:31:45 -04:00
16 changed files with 62 additions and 5663 deletions
@@ -2,32 +2,19 @@
 from __future__ import annotations
 import asyncio
 import datetime
 import inspect
 import sqlite3
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 from zoneinfo import ZoneInfo
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ConfigEntryNotReady
 from homeassistant.helpers.event import async_track_time_change
-from .const import (
+from .const import CONF_ADMIN_USER_IDS, DOMAIN, LOGGER
    CONF_ADMIN_USER_IDS,
    CONF_DAY_ROLLOVER_TIME,
    CONF_HORIZON_DAYS,
    DEFAULT_DAY_ROLLOVER_TIME,
    DEFAULT_HORIZON_DAYS,
    DOMAIN,
    LOGGER,
    SERVICE_REGENERATE,
 )
 from .db import NestQuestDatabase
 from .materialize import materialize as _materialize_run
 from .migrations import apply_migrations
 from .store import async_get_db_path
 from .admin_allowlist import seed_setup_admin
@@ -237,7 +224,6 @@ class NestQuestRuntimeData:
    options: dict[str, Any]
    database: NestQuestDatabase
    remove_update_listener: Callable[[], Any]
    remove_time_change_listener: Callable[[], Any]
 async def _async_owner_user_ids(hass: HomeAssistant) -> list[str]:
@@ -262,138 +248,6 @@ async def _async_owner_user_ids(hass: HomeAssistant) -> list[str]:
    return owners
 def _day_rollover_hour_minute(options: dict[str, Any]) -> tuple[int, int]:
    """Return the (hour, minute) the daily rollover fires at from ``options``.
    The options flow validates ``day_rollover_time`` as a strict ``HH:MM``
    string, so a stored value never needs re-validation here; a missing key
    falls back to :data:`~.const.DEFAULT_DAY_ROLLOVER_TIME`.
    """
    rollover = options.get(CONF_DAY_ROLLOVER_TIME, DEFAULT_DAY_ROLLOVER_TIME)
    hour, _, minute = rollover.partition(":")
    return int(hour), int(minute)
 def _configured_horizon_days(options: dict[str, Any]) -> int:
    """Return the configured generation horizon, validated, else the default.
    The options flow already validates ``horizon_days`` as an integer >= 1,
    but a stored ``entry.options`` dict could still carry a partial or
    hand-edited value.  Re-checking here — and falling back to
    :data:`~.const.DEFAULT_HORIZON_DAYS` on a missing, non-int or sub-1 value
    — keeps a malformed option from shrinking or exploding the materialized
    horizon.
    """
    value = options.get(CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS)
    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
        return DEFAULT_HORIZON_DAYS
    return value
 async def _run_horizon_materialization(
    hass: HomeAssistant,
    database: NestQuestDatabase,
    horizon_days: int = DEFAULT_HORIZON_DAYS,
 ) -> None:
    """Materialize the rolling horizon ``[today, today + horizon_days]``.
    "today" is computed in HA local time (``hass.config.time_zone``) rather
    than the system clock, so the horizon tracks the household's own day.
    The walk itself runs through :func:`~.materialize.materialize`, whose DB
    access is executor-only.
    This is the ONE generation path: the startup backfill, the daily rollover
    listener and the ``regenerate`` service all funnel through it, so there is
    no duplicated materialization logic.  ``horizon_days`` sizes the window
    and defaults to :data:`~.const.DEFAULT_HORIZON_DAYS`; callers thread the
    entry's validated option value through.
    """
    time_zone = ZoneInfo(hass.config.time_zone)
    today = datetime.datetime.now(time_zone).date()
    start_date = today.isoformat()
    end_date = (
        today + datetime.timedelta(days=horizon_days)
    ).isoformat()
    await _materialize_run(database, start_date, end_date, today=today)
 def _register_day_rollover_listener(
    hass: HomeAssistant,
    database: NestQuestDatabase,
    options: dict[str, Any],
 ) -> Callable[[], Any]:
    """Register the daily materialization listener and return its remover.
    Fires once per day at the configured local ``day_rollover_time`` and
    materializes the rolling horizon ``[today, today + horizon_days]``
    through the shared :func:`_run_horizon_materialization` path, using the
    entry's configured (validated) ``horizon_days``.
    """
    hour, minute = _day_rollover_hour_minute(options)
    horizon_days = _configured_horizon_days(options)
    async def _run_materialization(_now: datetime.datetime) -> None:
        await _run_horizon_materialization(hass, database, horizon_days)
    return async_track_time_change(
        hass, _run_materialization, hour=hour, minute=minute
    )
 def _find_live_runtime_data(hass: HomeAssistant) -> NestQuestRuntimeData | None:
    """Return a live runtime record with a connected database, or None.
    The domain-global services (e.g. ``regenerate``) have no database of
    their own; they resolve whichever config entry's runtime data is
    currently live at call time, so none of them can hold a stale handle
    to a closed connection after another entry unloads.  The record also
    carries that entry's options (e.g. the configured horizon).
    """
    for runtime_data in hass.data.get(DOMAIN, {}).values():
        database = getattr(runtime_data, "database", None)
        if database is not None and database.connected:
            return runtime_data
    return None
 def _register_regenerate_service(hass: HomeAssistant) -> None:
    """Register ``nestquest.regenerate`` once at domain scope.
    The service triggers a full on-demand regeneration over the rolling
    horizon, running the SAME idempotent materialize path
    (:func:`_run_horizon_materialization`) as the startup backfill and the
    daily rollover listener.  It is DOMAIN-global — registered exactly once
    (guarded by ``has_service``) and NOT bound to any config entry — so the
    handler resolves the currently-live database at call time and a name
    collision or duplicate setup is impossible.  Removal is handled by the
    unload path only once the LAST entry is removed (see
    :func:`_deregister_regenerate_service`).
    """
    if hass.services.has_service(DOMAIN, SERVICE_REGENERATE):
        return
    async def _regenerate(_call: Any) -> None:
        runtime_data = _find_live_runtime_data(hass)
        if runtime_data is None:
            _LOGGER.warning(
                "NestQuest regenerate requested but no config entry has a "
                "live database; ignoring"
            )
            return
        horizon_days = _configured_horizon_days(runtime_data.options)
        await _run_horizon_materialization(
            hass, runtime_data.database, horizon_days
        )
    hass.services.async_register(DOMAIN, SERVICE_REGENERATE, _regenerate)
 def _deregister_regenerate_service(hass: HomeAssistant) -> None:
    """Remove ``nestquest.regenerate`` when the last entry unloads."""
    if hass.services.has_service(DOMAIN, SERVICE_REGENERATE):
        hass.services.async_remove(DOMAIN, SERVICE_REGENERATE)
 async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
    """Set up the NestQuest integration. YAML configuration is not used, returns True."""
    return True
@@ -451,8 +305,6 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
        await listener_hass.config_entries.async_reload(listener_entry.entry_id)
    database = await _async_open_database(hass, await async_get_db_path(hass))
    remove_update_listener: Callable[[], Any] | None = None
    remove_time_change_listener: Callable[[], Any] | None = None
    try:
        # Seed the admin allowlist on first setup so the owner is never
        # locked out: an empty database takes the persisted admin copy
@@ -478,46 +330,14 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
            owner_ids=owner_ids,
        )
        remove_update_listener = entry.add_update_listener(_async_update_listener)
        remove_time_change_listener = _register_day_rollover_listener(
            hass, database, dict(entry.options)
        )
        # Backfill any days the daily listener missed while the integration
        # was off (or freshly installed): run the one idempotent walk over
        # [today, today + horizon_days] once at setup, using the entry's
        # configured horizon.  This runs through the SAME path as the daily
        # listener and regenerate service.
        await _run_horizon_materialization(
            hass, database, _configured_horizon_days(dict(entry.options))
        )
        _register_regenerate_service(hass)
    except BaseException:
        # A failure anywhere after the database is open must not leak the
        # listeners already registered against that (now-closed) database:
        # unwind EVERY remover we acquired before the failure, keeping the
        # original error as the one raised.  Removal is best-effort — a
        # failing remover must not mask the setup error that triggered it.
        for remove_listener in (
            remove_time_change_listener,
            remove_update_listener,
        ):
            if remove_listener is None:
                continue
            try:
                result = remove_listener()
                if inspect.isawaitable(result):
                    await result
            except BaseException:
                pass
        await database.close()
        raise
    assert remove_update_listener is not None
    assert remove_time_change_listener is not None
    runtime_data = NestQuestRuntimeData(
        entry_id=entry.entry_id,
        options=dict(entry.options),
        database=database,
        remove_update_listener=remove_update_listener,
        remove_time_change_listener=remove_time_change_listener,
    )
    entry.runtime_data = runtime_data
    hass.data[DOMAIN][entry.entry_id] = runtime_data
@@ -528,47 +348,28 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Unload a config entry."""
    domain_data = hass.data.setdefault(DOMAIN, {})
    runtime_data = domain_data.pop(entry.entry_id, None)
-    is_last = not domain_data
+    if not domain_data:
    if is_last:
        hass.data.pop(DOMAIN, None)
    if runtime_data is None:
        runtime_data = getattr(entry, "runtime_data", None)
    unload_error: BaseException | None = None
    if runtime_data is not None:
        remove_update_listener = getattr(runtime_data, "remove_update_listener", None)
-        remove_time_change_listener = getattr(
+        unload_error: BaseException | None = None
            runtime_data, "remove_time_change_listener", None
        )
        try:
-            for remove_listener in (
+            if remove_update_listener is not None:
-                remove_update_listener,
+                result = remove_update_listener()
-                remove_time_change_listener,
+                if inspect.isawaitable(result):
-            ):
+                    await result
-                if remove_listener is None:
+        except BaseException as err:
-                    continue
+            unload_error = err
                try:
                    result = remove_listener()
                    if inspect.isawaitable(result):
                        await result
                except BaseException as err:
                    # Cancel EVERY listener even when an earlier remover
                    # raises: a skipped remover would leave a daily
                    # callback firing against a closed database after
                    # unload.  The first error is retained and re-raised
                    # only after both removers (and the DB close) ran.
                    if unload_error is None:
                        unload_error = err
        finally:
            database = getattr(runtime_data, "database", None)
            if database is not None:
                await database.close()
-    # The ``regenerate`` service is DOMAIN-global: it is torn down only
+        if unload_error is not None:
-    # once the FINAL entry unloads (``hass.data[DOMAIN]`` is now empty),
+            if getattr(entry, "runtime_data", None) is not None:
-    # never when a sibling entry is still loaded.
+                entry.runtime_data = None
-    if is_last:
+            raise unload_error
        _deregister_regenerate_service(hass)
    if getattr(entry, "runtime_data", None) is not None:
        entry.runtime_data = None
    if unload_error is not None:
        raise unload_error
    return True
@@ -1,369 +0,0 @@
 """Business layer for the completion event log (Feature 08).
 Sits between the Feature 09 service gate and the typed
 :class:`~.dao_instances.CompletionEventsDao`: callers get actor-shape
 validation and the UTC occurred-at stamp here, and never talk to the
 DAO or SQL directly.  This module is the only Feature-08 caller of
 :meth:`~.dao_instances.CompletionEventsDao.append`.  Completing an
 instance (no-op if already done) is :func:`complete_instance`;
 un-completing (no-op if already open) is :func:`uncomplete_instance`.
 Instance current state is derived from the latest event via
 :func:`instance_state` (``open`` / ``done``); there is no status
 column.
 Actor policy matches the schema CHECKs (D-008): ``actor_source`` is
 ``'user'`` or ``'panel'`` only — never ``'service'``.  ``'user'``
 requires ``actor_user_id`` and forbids ``actor_child_id``; ``'panel'``
 requires ``actor_child_id`` (the tapped profile) and forbids
 ``actor_user_id``.  Inverted shapes raise a field-naming ValueError
 before any write.
 ``occurred_at`` is stamped UTC ISO-8601 at second precision with an
 explicit ``+00:00`` offset, matching the DAO's one accepted shape so
 lexicographic range queries stay exact.  ``was_on_time`` is required
 (True/False) for completed events; un-completions may pass None.  There
 is no permission check here (that is Feature 09).
 """
 from __future__ import annotations
 import asyncio
 import datetime
 from .dao_children import _CONNECTION_LOCKS, _connection_lock
 from .dao_instances import (
    EVENT_COMPLETED,
    EVENT_UNCOMPLETED,
    CompletionEventRecord,
    CompletionEventsDao,
    QuestInstancesDao,
 )
 from .db import NestQuestDatabase
 #: Timestamp policy for completion_events.occurred_at: strict UTC
 #: ISO-8601 with explicit '+00:00' offset (module timestamp policy).
 _UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
 def _now_stamp() -> str:
    """Return the module's strict UTC second-precision stamp."""
    return datetime.datetime.now(datetime.timezone.utc).strftime(
        _UTC_TIMESTAMP_FORMAT
    )
 def _stamp_occurred_at(now: datetime.datetime | None) -> str:
    """Return a DAO-accepted UTC stamp for ``now``, or the current time."""
    if now is None:
        return _now_stamp()
    if not isinstance(now, datetime.datetime):
        raise ValueError(f"now must be a datetime, got {now!r}")
    if now.tzinfo is None:
        raise ValueError("now must be timezone-aware")
    return now.astimezone(datetime.timezone.utc).strftime(
        _UTC_TIMESTAMP_FORMAT
    )
 class _TaskReentrantLock:
    """Shared connection lock the owning task may re-enter."""
    def __init__(self, inner: asyncio.Lock) -> None:
        self._inner = inner
        self._task: asyncio.Task | None = None
        self._depth = 0
    def locked(self) -> bool:
        return self._inner.locked()
    async def acquire(self) -> bool:
        task = asyncio.current_task()
        if self._task is task:
            self._depth += 1
            return True
        await self._inner.acquire()
        self._task = task
        self._depth = 1
        return True
    def release(self) -> None:
        if self._task is not asyncio.current_task():
            raise RuntimeError("lock released by a non-owner")
        self._depth -= 1
        if self._depth == 0:
            self._task = None
            self._inner.release()
    async def __aenter__(self) -> _TaskReentrantLock:
        await self.acquire()
        return self
    async def __aexit__(self, *exc: object) -> None:
        self.release()
 def _reentrant_connection_lock(database) -> _TaskReentrantLock:
    """Return the shared connection lock, made task-reentrant.
    ``CompletionEventsDao.append`` also acquires this lock, so
    check+append in :func:`complete_instance` and
    :func:`uncomplete_instance` must re-enter on the same task.  The
    wrapper is stored in the shared dict so the DAO sees the same
    object.
    """
    loop = asyncio.get_running_loop()
    key = (id(database), id(loop))
    lock = _CONNECTION_LOCKS.get(key)
    if isinstance(lock, _TaskReentrantLock):
        return lock
    wrapped = _TaskReentrantLock(
        lock if lock is not None else asyncio.Lock()
    )
    _CONNECTION_LOCKS[key] = wrapped
    return wrapped
 def _validate_int_id(value: object, field: str) -> int:
    """Reject non-int ids (bools included) before any lookup."""
    if isinstance(value, bool) or not isinstance(value, int):
        raise ValueError(f"{field} must be an integer, got {value!r}")
    return value
 def _validate_event_type(value: object) -> str:
    """Return a schema-legal event type, or raise naming the field."""
    if value not in (EVENT_COMPLETED, EVENT_UNCOMPLETED):
        raise ValueError(
            f"event_type must be '{EVENT_COMPLETED}' or "
            f"'{EVENT_UNCOMPLETED}', got {value!r}"
        )
    return value
 def _validate_actor(
    actor_source: object,
    actor_user_id: object,
    actor_child_id: object,
 ) -> tuple[str, str | None, int | None]:
    """Return a schema-legal actor triple, or raise naming the field.
    ``'user'`` requires a non-empty ``actor_user_id`` string and forbids
    ``actor_child_id``.  ``'panel'`` requires an integer
    ``actor_child_id`` and forbids ``actor_user_id``.  Any other
    ``actor_source`` (including ``'service'``) is rejected.
    """
    if actor_source not in ("user", "panel"):
        raise ValueError(
            f"actor_source must be 'user' or 'panel', got {actor_source!r}"
        )
    if actor_source == "user":
        if not isinstance(actor_user_id, str) or not actor_user_id.strip():
            raise ValueError("actor_source 'user' requires actor_user_id")
        if actor_child_id is not None:
            raise ValueError(
                "actor_source 'user' must not carry actor_child_id"
            )
        return "user", actor_user_id.strip(), None
    if actor_user_id is not None:
        raise ValueError("actor_source 'panel' must not carry actor_user_id")
    if actor_child_id is None:
        raise ValueError(
            "actor_source 'panel' requires actor_child_id"
        )
    return (
        "panel",
        None,
        _validate_int_id(actor_child_id, "actor_child_id"),
    )
 def _validate_was_on_time(
    event_type: str, was_on_time: object
 ) -> bool | None:
    """Return a real bool or None; completed events require True/False."""
    if was_on_time is not None and type(was_on_time) is not bool:
        raise ValueError(
            f"was_on_time must be True, False or None, got {was_on_time!r}"
        )
    if event_type == EVENT_COMPLETED and was_on_time is None:
        raise ValueError(
            "a completed event requires was_on_time (True/False)"
        )
    return was_on_time
 async def append_event(
    database: NestQuestDatabase,
    instance_id: int,
    child_id: int,
    event_type: str,
    *,
    actor_source: str,
    actor_user_id: str | None = None,
    actor_child_id: int | None = None,
    was_on_time: bool | None = None,
    now: datetime.datetime | None = None,
 ) -> CompletionEventRecord:
    """Append one completion or un-completion event and return the row.
    Validates actor shapes and the completed-event on-time requirement
    before calling :meth:`CompletionEventsDao.append`.  ``occurred_at``
    is stamped here (UTC ``+00:00``); pass ``now`` to pin the clock.
    """
    instance_id = _validate_int_id(instance_id, "instance_id")
    child_id = _validate_int_id(child_id, "child_id")
    event_type = _validate_event_type(event_type)
    actor_source, actor_user_id, actor_child_id = _validate_actor(
        actor_source, actor_user_id, actor_child_id
    )
    was_on_time = _validate_was_on_time(event_type, was_on_time)
    occurred_at = _stamp_occurred_at(now)
    return await CompletionEventsDao(database).append(
        instance_id,
        child_id,
        event_type,
        actor_source,
        occurred_at,
        was_on_time,
        actor_user_id=actor_user_id,
        actor_child_id=actor_child_id,
    )
 async def instance_state(
    database: NestQuestDatabase,
    instance_id: int,
 ) -> str:
    """Return ``open`` or ``done`` from the instance's latest event.
    No events, or a latest event of uncompleted, is ``open``.  A latest
    event of completed is ``done``.  Unknown ``instance_id`` raises
    ValueError naming the field.  Existence and the latest event are
    read inside the connection lock so the answer is one snapshot.
    """
    instance_id = _validate_int_id(instance_id, "instance_id")
    async with _connection_lock(database):
        instance = await QuestInstancesDao(database).get_by_id(instance_id)
        if instance is None:
            raise ValueError(
                f"instance_id: quest instance {instance_id} does not exist"
            )
        latest = await CompletionEventsDao(database).get_latest_for_instance(
            instance_id
        )
    if latest is None or latest.event_type == EVENT_UNCOMPLETED:
        return "open"
    if latest.event_type == EVENT_COMPLETED:
        return "done"
    raise ValueError(
        f"event_type must be '{EVENT_COMPLETED}' or "
        f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
    )
 async def complete_instance(
    database: NestQuestDatabase,
    instance_id: int,
    *,
    actor_source: str,
    actor_user_id: str | None = None,
    actor_child_id: int | None = None,
    now: datetime.datetime | None = None,
    today: datetime.date | None = None,
 ) -> str:
    """Append a completed event unless the instance is already done.
    Returns the derived state ``done``.  An already-done instance is a
    no-op: nothing is appended.  Unknown ``instance_id`` raises
    ValueError naming the field.  Existence, latest-event, and the
    append run under one connection lock so a concurrent complete
    cannot double-append.
    ``was_on_time`` is recorded as True — a placeholder until the
    on-time task computes it from ``now`` / ``today`` against the
    instance due_date and optional due_time.  ``today`` is accepted so
    callers can thread the HA-local date through without a signature
    change; it is unused here.
    """
    instance_id = _validate_int_id(instance_id, "instance_id")
    actor_source, actor_user_id, actor_child_id = _validate_actor(
        actor_source, actor_user_id, actor_child_id
    )
    async with _reentrant_connection_lock(database):
        instance = await QuestInstancesDao(database).get_by_id(instance_id)
        if instance is None:
            raise ValueError(
                f"instance_id: quest instance {instance_id} does not exist"
            )
        latest = await CompletionEventsDao(database).get_latest_for_instance(
            instance_id
        )
        if latest is not None and latest.event_type == EVENT_COMPLETED:
            return "done"
        if latest is not None and latest.event_type != EVENT_UNCOMPLETED:
            raise ValueError(
                f"event_type must be '{EVENT_COMPLETED}' or "
                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
            )
        await append_event(
            database,
            instance.id,
            instance.child_id,
            EVENT_COMPLETED,
            actor_source=actor_source,
            actor_user_id=actor_user_id,
            actor_child_id=actor_child_id,
            was_on_time=True,
            now=now,
        )
    return "done"
 async def uncomplete_instance(
    database: NestQuestDatabase,
    instance_id: int,
    *,
    actor_source: str,
    actor_user_id: str | None = None,
    actor_child_id: int | None = None,
    now: datetime.datetime | None = None,
 ) -> str:
    """Append an uncompleted event unless the instance is already open.
    Returns the derived state ``open``.  An already-open instance is a
    no-op: nothing is appended.  Unknown ``instance_id`` raises
    ValueError naming the field.  Existence, latest-event, and the
    append run under one connection lock so a concurrent uncomplete
    cannot double-append.  The original completed row is not modified.
    """
    instance_id = _validate_int_id(instance_id, "instance_id")
    actor_source, actor_user_id, actor_child_id = _validate_actor(
        actor_source, actor_user_id, actor_child_id
    )
    async with _reentrant_connection_lock(database):
        instance = await QuestInstancesDao(database).get_by_id(instance_id)
        if instance is None:
            raise ValueError(
                f"instance_id: quest instance {instance_id} does not exist"
            )
        latest = await CompletionEventsDao(database).get_latest_for_instance(
            instance_id
        )
        if latest is None or latest.event_type == EVENT_UNCOMPLETED:
            return "open"
        if latest.event_type != EVENT_COMPLETED:
            raise ValueError(
                f"event_type must be '{EVENT_COMPLETED}' or "
                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
            )
        await append_event(
            database,
            instance.id,
            instance.child_id,
            EVENT_UNCOMPLETED,
            actor_source=actor_source,
            actor_user_id=actor_user_id,
            actor_child_id=actor_child_id,
            was_on_time=None,
            now=now,
        )
    return "open"
@@ -9,9 +9,6 @@ LOGGER = logging.getLogger(LOGGER_NAME)
 PLATFORMS: list[str] = []
 #: Service name for the on-demand regeneration service (``nestquest.regenerate``).
 SERVICE_REGENERATE = "regenerate"
 SQLITE_DB_FILENAME = "nestquest.db"
 # Configuration keys and default values
@@ -47,46 +47,6 @@ from .db import NestQuestDatabase
 _UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
 def _today() -> datetime.date:
    """Return the current local calendar date (the single date source).
    Every "today" read in this module goes through this one function so
    the delete clamp and the materialize walk's no-past guard read the
    same clock, and a caller or test can pin/roll that clock
    deterministically (e.g. a queued-across-midnight regression).  Pure
    clock read — no business rule lives here.
    """
    return datetime.date.today()
 def _resolve_today(today: datetime.date | None) -> datetime.date:
    """Return the caller-resolved "today", or the host date when absent.
    The no-past guard and the delete cutoffs must compare due dates
    against the SAME calendar date the materialization horizon was built
    from.  Home Assistant's configured time zone can lag the host clock
    around midnight, so when the caller has already resolved the local
    date (``today``) that anchor is authoritative; ``None`` falls back to
    the host clock (:func:`_today`), which is exactly the previous
    behavior for callers with no HA-local date.
    """
    return _today() if today is None else today
 def _reject_past(due_date: str, today_iso: str) -> None:
    """Raise unless ``due_date`` is on or after ``today_iso``.
    The single no-past rule shared by :meth:`QuestInstancesDao.upsert`
    and :meth:`QuestInstancesDao.upsert_if_valid`: instances are never
    generated in the past, measured against the resolved "today".
    """
    if due_date < today_iso:
        raise ValueError(
            f"instances are never generated in the past: due_date "
            f"{due_date!r} is before today {today_iso!r}"
        )
 def _validate_utc_timestamp(value: str, field: str) -> None:
    """Raise ValueError unless ``value`` is a strict UTC ISO-8601 stamp.
@@ -206,7 +166,6 @@ class QuestInstancesDao:
        *,
        window: str,
        due_time: str | None = None,
        today: datetime.date | None = None,
    ) -> QuestInstanceRecord:
        """Create the dated instance for the widened key idempotently.
@@ -225,10 +184,6 @@ class QuestInstancesDao:
        - ``due_date`` must be TODAY or later: instances are never
          generated in the past (Feature 07).  The caller's
          materialization horizon is future-dated by definition.
          ``today`` optionally pins the resolved HA-local date the
          guard compares against (falling back to the host clock when
          omitted) so a household time zone behind the host around
          midnight is not misread as "past".
        - ``window`` must be one of ``const.QUEST_WINDOWS``.
        - An existing instance WITH a completion event is IMMUTABLE:
          the conflict path must not rewrite its snapshot columns
@@ -248,20 +203,24 @@ class QuestInstancesDao:
        # check runs after the lock is acquired, because a caller can
        # wait on the lock across midnight — a date that was "today"
        # at call time may be "yesterday" by the time the INSERT runs.
-        # A caller-supplied ``today`` (HA-local) is used for BOTH
+        today = datetime.date.today().isoformat()
-        # checks and never re-read, since it is already the anchor the
+        if due_date < today:
-        # batch runs against.
+            raise ValueError(
-        today_date = _resolve_today(today)
+                f"instances are never generated in the past: due_date "
-        _reject_past(due_date, today_date.isoformat())
+                f"{due_date!r} is before today {today!r}"
            )
        async with _connection_lock(self._database):
            async with self._database.transaction():
                # Re-read "today" under the lock: this is the date the
                # insert actually executes on, so the no-past rule
-                # holds across midnight rollovers.  A pinned HA-local
+                # holds across midnight rollovers.
-                # anchor is exempt from the re-read (see above).
+                today = datetime.date.today().isoformat()
-                if today is None:
+                if due_date < today:
-                    today_date = _today()
+                    raise ValueError(
-                _reject_past(due_date, today_date.isoformat())
+                        f"instances are never generated in the past: "
                        f"due_date {due_date!r} is before today "
                        f"{today!r}"
                    )
                definition = await self._database.fetch_one(
                    "SELECT 1 FROM quest_definitions WHERE id = ?",
                    (definition_id,),
@@ -318,123 +277,6 @@ class QuestInstancesDao:
        assert instance is not None
        return instance
    async def upsert_if_valid(
        self,
        definition_id: int,
        child_id: int,
        due_date: str,
        generated_at: str,
        *,
        window: str,
        due_time: str | None = None,
        today: datetime.date | None = None,
    ) -> QuestInstanceRecord | None:
        """Insert one dated instance iff its tuple is still materializable.
        This is the materialization walk's single write path.  Unlike the
        generic :meth:`upsert`, which validates only existence and
        assignment, this method re-validates EVERY materialization
        precondition in the SAME connection-lock-held transaction as the
        INSERT — closing the check-then-insert gap a concurrent config
        write could otherwise slip through:
        - the definition exists AND is active (a definition deactivated
          after the input snapshot is skipped, never written);
        - the child exists AND is active (a deactivated child is skipped);
        - the (definition, child) assignment link still exists (a removed
          assignment is skipped);
        - the window is still declared on the definition (a removed window
          is skipped);
        - the window's live ``due_time`` still EQUALS the caller-supplied
          ``due_time`` (NULL-safe: NULL == NULL counts as equal; a window
          with no due time matches a snapshot with no due time).  A
          window-time edit landed after the input snapshot makes the
          caller's ``due_time`` stale, and writing it would overwrite the
          newer due_time a concurrent regeneration already upserted — so
          the tuple is skipped instead of written.
        The due_time check closes the one check-then-insert gap this
        method previously left open: it re-validated every OTHER
        precondition but then wrote the snapshot's ``due_time``
        unconditionally, so a stale materialization could clobber a
        newer, concurrently-regenerated due_time.
        Returns the stored instance, or ``None`` when a precondition
        failed — the tuple no longer materializable, which the walk SKIPS
        rather than raising, so the rest of the batch is unaffected.  The
        no-past rule (instances are never generated in the past) is
        preserved from :meth:`upsert` and still raises ValueError; ``today``
        optionally pins the HA-local anchor it compares against.  An
        instance that ALREADY has a completion event is also skipped
        (returns ``None``) rather than raised: it is immutable, so the
        walk leaves it untouched instead of failing the batch — the
        generic :meth:`upsert` keeps its hard refusal for the
        delete/regenerate path.
        """
        _validate_date(due_date, "due_date")
        _validate_window(window)
        # Fail fast on obviously-past dates before queuing on the lock;
        # the authoritative check re-runs under the lock (see upsert).
        today_date = _resolve_today(today)
        _reject_past(due_date, today_date.isoformat())
        async with _connection_lock(self._database):
            async with self._database.transaction():
                if today is None:
                    today_date = _today()
                _reject_past(due_date, today_date.isoformat())
                still_valid = await self._database.fetch_one(
                    "SELECT 1 FROM quest_definitions d "
                    "JOIN quest_definition_assignees a "
                    "ON a.definition_id = d.id "
                    "JOIN children c ON c.id = a.child_id "
                    "JOIN quest_definition_windows w "
                    "ON w.definition_id = d.id "
                    "WHERE d.id = ? AND a.child_id = ? AND w.window = ? "
                    "AND d.is_active = 1 AND c.is_active = 1 "
                    "AND w.due_time IS ? LIMIT 1",
                    (definition_id, child_id, window, due_time),
                )
                if still_valid is None:
                    # A config change invalidated the tuple since the
                    # snapshot: skip it rather than abort the batch.
                    return None
                existing = await self._database.fetch_one(
                    "SELECT 1 FROM completion_events "
                    "WHERE instance_id = (SELECT id FROM quest_instances "
                    "WHERE definition_id = ? AND child_id = ? "
                    "AND due_date = ? AND window = ?)",
                    (definition_id, child_id, due_date, window),
                )
                if existing is not None:
                    # The instance is already completed and therefore
                    # immutable: the walk SKIPS it (no-op) rather than
                    # rewriting its snapshot columns or failing the
                    # batch.  This is the materialization walk's skip,
                    # distinct from the generic :meth:`upsert` refusal.
                    return None
                await self._database.execute(
                    "INSERT INTO quest_instances (definition_id, child_id, "
                    "window, due_date, due_time, generated_at) "
                    "VALUES (?, ?, ?, ?, ?, ?) "
                    "ON CONFLICT (definition_id, child_id, due_date, "
                    "window) DO UPDATE SET "
                    "due_time = excluded.due_time, "
                    "generated_at = excluded.generated_at",
                    (
                        definition_id,
                        child_id,
                        window,
                        due_date,
                        due_time,
                        generated_at,
                    ),
                )
                instance = await self.get(
                    definition_id, child_id, due_date, window
                )
        assert instance is not None
        return instance
    async def get(
        self,
        definition_id: int,
@@ -494,7 +336,7 @@ class QuestInstancesDao:
        return [_instance_from_row(row) for row in rows]
    async def delete_future_uncompleted(
-        self, definition_id: int, cutoff_date: str, *, today: datetime.date | None = None
+        self, definition_id: int, cutoff_date: str
    ) -> int:
        """Delete the definition's open instances at/after cutoff.
@@ -506,11 +348,9 @@ class QuestInstancesDao:
        is measured against TODAY (materialization regenerates the
        rolling horizon from now), so a caller cannot use this to
        rewrite past open instances either — the day-rollover missed
-        sweep (Feature 11) handles past-due instances instead.  ``today``
+        sweep (Feature 11) handles past-due instances instead.  Any
-        optionally pins the HA-local anchor the clamp compares against
+        instance with a completion event is never touched, regardless
-        (falling back to the host clock when omitted).  Any instance with
+        of its date.  Returns the number deleted.
        a completion event is never touched, regardless of its date.
        Returns the number deleted.
        """
        _validate_date(cutoff_date, "cutoff_date")
        async with _connection_lock(self._database):
@@ -520,8 +360,8 @@ class QuestInstancesDao:
                # midnight cannot delete instances that became past
                # while it waited (backdating is clamped to the
                # execution date, not the call date).
-                today_date = _resolve_today(today)
+                today = datetime.date.today().isoformat()
-                effective_cutoff = max(cutoff_date, today_date.isoformat())
+                effective_cutoff = max(cutoff_date, today)
                result = await self._database.execute(
                    "DELETE FROM quest_instances WHERE definition_id = ? "
                    "AND due_date >= ? AND NOT EXISTS ("
@@ -532,51 +372,6 @@ class QuestInstancesDao:
                )
        return result.rowcount
    async def delete_future_uncompleted_for_child(
        self, child_id: int, cutoff_date: str, *, today: datetime.date | None = None
    ) -> tuple[int, str]:
        """Delete the child's open instances at/after cutoff, across every
        definition, returning ``(deleted, effective_cutoff)``.
        Child-scoped counterpart to :meth:`delete_future_uncompleted`,
        used when a child's presence changes (Feature 09): only instances
        at or after the cutoff with NO completion event are removed, inside
        one transaction — an instance that gains a completion event
        mid-flight cannot be deleted.  The cutoff cannot be backdated below
        today, for the same reason as the definition-scoped method (see its
        docstring).  ``today`` optionally pins the HA-local anchor the clamp
        compares against (falling back to the host clock when omitted).
        Any instance with a completion event is never touched, regardless
        of its date.
        Returns the number deleted and the effective cutoff that was
        actually applied (``max(cutoff_date, today)``, read under the
        lock).  The caller (:func:`~.materialize.regenerate_for_child`)
        passes that effective cutoff back as its re-materialization anchor,
        so the delete and the rebuild share ONE execution-day even when the
        call is queued across midnight — instead of the caller re-reading a
        stale "today" and materializing a window the delete already
        superseded.
        """
        _validate_date(cutoff_date, "cutoff_date")
        async with _connection_lock(self._database):
            async with self._database.transaction():
                # "today" is read under the lock, matching the
                # definition-scoped method: the DELETE executes on this
                # date, so a caller queued across midnight cannot delete
                # instances that became past while it waited.
                today_date = _resolve_today(today)
                effective_cutoff = max(cutoff_date, today_date.isoformat())
                result = await self._database.execute(
                    "DELETE FROM quest_instances WHERE child_id = ? "
                    "AND due_date >= ? AND NOT EXISTS ("
                    "  SELECT 1 FROM completion_events "
                    "  WHERE instance_id = quest_instances.id"
                    ")",
                    (child_id, effective_cutoff),
                )
        return result.rowcount, effective_cutoff
 class CompletionEventsDao:
    """Typed append-only access to the ``completion_events`` table.
@@ -276,59 +276,4 @@ class PresenceOverridesDao:
            "DELETE FROM presence_overrides WHERE id = ?",
            (override_id,),
        )
-        return result.rowcount > 0
+        return result.rowcount > 0
 async def read_snapshot_unlocked(
    database: NestQuestDatabase,
    child_ids: list[int],
    range_start: str,
    range_end: str,
 ) -> tuple[
    dict[int, PresenceScheduleRecord],
    dict[int, list[PresenceOverrideRecord]],
 ]:
    """Read schedules and overrides for ``child_ids`` WITHOUT locking.
    MUST be called inside the connection lock and an open transaction, so
    the schedules and overrides returned here stay coherent with every
    other table the caller reads inside that same transaction (the
    materialization walk's single input snapshot does exactly that).  The
    date range comes already validated by the caller.
    Returns ``(schedules, overrides)``:
    - ``schedules`` maps ``child_id`` to its :class:`PresenceScheduleRecord`
      for every child that HAS a schedule row.  A child absent from the
      mapping has no schedule, i.e. is present every day (Feature 05).
    - ``overrides`` maps ``child_id`` to that child's overrides overlapping
      ``[range_start, range_end]`` (inclusive boundaries), ordered by start
      date; a child with no matching override is absent from the mapping.
    ``child_ids`` must name existing children (the caller derives them
    from a trusted snapshot, within the same transaction).
    """
    children = sorted(set(child_ids))
    if not children:
        return {}, {}
    placeholders = ",".join("?" for _ in children)
    schedule_rows = await database.fetch_all(
        f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
        f"WHERE child_id IN ({placeholders})",
        tuple(children),
    )
    override_rows = await database.fetch_all(
        f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
        f"WHERE child_id IN ({placeholders}) AND end_date >= ? "
        "AND start_date <= ? ORDER BY start_date",
        tuple(children) + (range_start, range_end),
    )
    schedules = {
        record.child_id: record
        for record in map(_schedule_from_row, schedule_rows)
    }
    overrides: dict[int, list[PresenceOverrideRecord]] = {}
    for row in override_rows:
        record = _override_from_row(row)
        overrides.setdefault(record.child_id, []).append(record)
    return schedules, overrides
@@ -907,81 +907,6 @@ class QuestDefinitionsDao:
        )
        return [_definition_from_row(row) for row in rows]
    async def _snapshots_for(
        self, definitions: list[QuestDefinitionRecord]
    ) -> list[QuestDefinitionSnapshot]:
        """Read each definition's rule, assignees and windows.
        MUST be called inside the connection lock (and ideally a
        transaction) so the definitions handed in and the rows this
        reads back cannot be raced by a concurrent edit between list
        and bundle.  Each rule is read through
        :class:`ScheduleRulesDao` on the same connection, so the
        snapshot's rule record is the one the definition references AT
        the moment of the locked read.
        """
        rules_dao = ScheduleRulesDao(self._database)
        snapshots: list[QuestDefinitionSnapshot] = []
        for definition in definitions:
            rule_record = await rules_dao.get(definition.schedule_rule_id)
            assert rule_record is not None
            snapshots.append(
                QuestDefinitionSnapshot(
                    definition=definition,
                    rule=rule_record,
                    assignees=await self.list_assignees(definition.id),
                    windows=await self.list_windows(definition.id),
                )
            )
        return snapshots
    async def list_snapshots_active(self) -> list[QuestDefinitionSnapshot]:
        """Return every active definition with its rule, assignees and
        windows, all read inside one locked transaction.
        The definitive list and each definition's linked rows are read
        in a single BEGIN..COMMIT span under the connection lock, so a
        concurrent atomic edit cannot interleave between the definition
        list and the bundle read: the caller receives a coherent
        snapshot (each definition's rule, assignees and windows as they
        were at one instant), never a mixed old-rule/new-windows state.
        """
        async with _connection_lock(self._database):
            async with self._database.transaction():
                definitions = await self.list_active()
                return await self._snapshots_for(definitions)
    async def read_snapshots_active(self) -> list[QuestDefinitionSnapshot]:
        """Return every active definition's snapshot WITHOUT locking.
        Mirrors :meth:`list_snapshots_active` minus the lock and
        transaction: the definitions and their rules, assignees and
        windows are read on the caller's connection under whatever
        transaction the caller is already holding, so they stay coherent
        with every OTHER table the caller reads inside that same
        transaction.  MUST be called inside the connection lock and an
        open transaction (the single-transaction input snapshot the
        materialization walk uses is that caller).
        """
        definitions = await self.list_active()
        return await self._snapshots_for(definitions)
    async def list_snapshots_by_child(
        self, child_id: int
    ) -> list[QuestDefinitionSnapshot]:
        """Return each definition assigned to ``child_id`` with its rule,
        assignees and windows, all read inside one locked transaction.
        Mirrors :meth:`list_snapshots_active` but selects by assignment
        (``list_by_child`` order: newest first).  Locks read-and-bundle
        into one transaction so the bundle never mixes one edit's
        definition with another's windows.
        """
        async with _connection_lock(self._database):
            async with self._database.transaction():
                definitions = await self.list_by_child(child_id)
                return await self._snapshots_for(definitions)
    async def update(
        self,
        definition_id: int,
@@ -1204,47 +1129,4 @@ class QuestDefinitionsDao:
        if not child[0]:
            raise ValueError(
                f"child {child_id} is inactive and cannot be assigned"
-            )
+            )
 async def load_materialization_input(
    database: NestQuestDatabase,
    range_start: str,
    range_end: str,
 ):
    """Read every materialization input in ONE locked transaction.
    Returns ``(snapshots, schedules, overrides)``:
    - ``snapshots``: every active definition with its rule, assignees and
      windows (the :class:`QuestDefinitionSnapshot` shape).
    - ``schedules`` / ``overrides``: the presence schedules and
      range-scoped overrides of every assignee child, in
      :mod:`.dao_presence`'s record shapes.
    The whole read — definitions, rules, assignees, windows, and the
    assignees' presence schedules and overrides — runs inside a single
    BEGIN..COMMIT span under the connection lock, so a concurrent edit
    (definition, assignment, window, or presence) cannot interleave
    between the parts and the walk never sees a mixed-time view.  Each
    table's SQL stays in its own DAO module: the presence portion is
    delegated to :mod:`.dao_presence` (a lazy import here, since that
    module imports this one).
    """
    definitions_dao = QuestDefinitionsDao(database)
    async with _connection_lock(database):
        async with database.transaction():
            snapshots = await definitions_dao.read_snapshots_active()
            child_ids = sorted(
                {
                    child.id
                    for snapshot in snapshots
                    for child in snapshot.assignees
                }
            )
            from . import dao_presence  # lazy: dao_presence imports us
            schedules, overrides = await dao_presence.read_snapshot_unlocked(
                database, child_ids, range_start, range_end
            )
    return snapshots, schedules, overrides
@@ -1,377 +0,0 @@
 """The materialization walk (Feature 07 core).
 :func:`materialize` turns the schedule rules + custody presence of the
 active quest definitions into concrete ``quest_instances`` rows over a
 date range.  It is the pure walk over definitions x dates x assignees x
 windows; HA scheduling (day-rollover triggers) is a separate later
 task and lives elsewhere.
 The walk is deterministic and idempotent:
 - All inputs — the active definitions with their rules, assignees and
  windows, AND the assignee children's presence schedules and scoped
  overrides — are read inside ONE locked transaction (see
  :func:`~.dao_rules.load_materialization_input`), so the walk sees a
  single coherent snapshot rather than a definition state from one
  instant and a presence state from another.
 - Presence is snapshotted into an immutable
  :class:`~.presence.PresenceEngine` from that same coherent read.
 - For each date in the range, each definition whose decoded rule
  :func:`~.recurrence.occurs_on` on that date, each assignee who is
  ``is_present`` on that date and each declared window, one instance is
  written through :class:`~.dao_instances.QuestInstancesDao.upsert_if_valid`
  with a ``generated_at`` stamp shared by the whole batch (one coherent
  time per run).
 A config change that lands AFTER the snapshot is read but BEFORE a
 tuple's write (an assignment removed, a definition or child deactivated,
 a window removed) makes that tuple SKIP rather than abort the batch:
 :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` re-validates
 every materialization precondition (active definition, active child,
 live assignment, declared window, and its CURRENT ``due_time``) inside
 the SAME transaction as the INSERT, so the check and the write cannot be
 split by a racing config edit.
 The upsert is idempotent on (definition_id, child_id, due_date,
 window), so re-running the materialization over the same range never
 duplicates a row; a tuple whose instance is already completed is SKIPPED
 (never rewritten, never raised) by
 :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`.
 Regeneration: a config or presence change must rebuild future instances
 so they track the new state.  :func:`regenerate_for_definition` covers
 definition edits / reassignment (Features 06/07); :func:`regenerate_for_child`
 covers a single child's presence change (Feature 09).  Both delete the
 affected open instances at or after today — never a completed instance,
 never the past — and re-run the walk over the rolling horizon
 ``[today, today + horizon_days]`` (``horizon_days`` defaults to
 ``DEFAULT_HORIZON_DAYS``).
 HOOK (Feature 09 presence services): the presence business layer that
 lands in Feature 09 MUST call :func:`regenerate_for_child` after EVERY
 presence-state write so a child's future instances track its presence:
 ``set_presence_pattern`` (including clearing/setting an empty pattern),
 deleting/clearing the presence schedule
 (:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
 ``create_presence_override``, and ``delete_presence_override``.  A
 schedule delete changes presence state too (the child becomes
 always-present), so it must regenerate just like the others.  This hook
 is documented, not yet wired: no presence business layer exists yet, and
 the presence DAO (``dao_presence.py``) must stay free of business rules
 — never call :func:`regenerate_for_child` from inside the DAO layer.
 """
 from __future__ import annotations
 import datetime
 from .const import DEFAULT_HORIZON_DAYS
 from .dao_instances import QuestInstancesDao, _resolve_today
 from .dao_rules import (
    _validate_date,
    load_materialization_input,
    schedule_rule_from_storage,
    schedule_rule_storage_from_record,
 )
 from .db import NestQuestDatabase
 from .presence import PresenceEngine, PresenceOverride, PresenceSchedule
 from .recurrence import ScheduleRule, occurs_on
 def _now_stamp() -> str:
    """Return the batch's shared UTC second-precision generation stamp."""
    return datetime.datetime.now(datetime.timezone.utc).isoformat(
        timespec="seconds"
    )
 def _resolve_horizon_days(horizon_days: int | None) -> int:
    """Validate a regeneration horizon and return the resolved day count.
    ``None`` resolves to :data:`~.const.DEFAULT_HORIZON_DAYS`.  A bool
    (SQLite would happily bind ``True``/``False`` onto an int), a non-int,
    or a value below 1 raises ValueError naming the field — the validation
    runs BEFORE any future-instance delete so a malformed horizon can never
    delete rows it then fails to rebuild.  A negative horizon would
    otherwise delete first and only then be rejected by
    :func:`materialize`'s inverted-range check; ``0``/``False`` would
    silently shrink the window to a single day.
    """
    if horizon_days is None:
        return DEFAULT_HORIZON_DAYS
    if (
        isinstance(horizon_days, bool)
        or not isinstance(horizon_days, int)
        or horizon_days < 1
    ):
        raise ValueError(
            f"horizon_days must be a positive integer, got {horizon_days!r}"
        )
    return horizon_days
 def _decode_rule(snapshot) -> ScheduleRule:
    """Decode a snapshot's rule record back into a ScheduleRule.
    The record carried by the snapshot is the one the definition
    referenced at read time, so decoding it here (rather than re-reading
    through ``ScheduleRulesDao``) preserves the coherence the snapshot
    guarantees.
    """
    return schedule_rule_from_storage(
        schedule_rule_storage_from_record(snapshot.rule)
    )
 def _build_engine(
    schedules_records,
    overrides_records,
 ) -> PresenceEngine:
    """Convert raw presence records into an immutable PresenceEngine."""
    schedules: dict[int, PresenceSchedule] = {}
    for child_id, record in schedules_records.items():
        schedules[child_id] = PresenceSchedule.decode(
            child_id, record.anchor_date, record.pattern
        )
    overrides: dict[int, list[PresenceOverride]] = {}
    for child_id, records in overrides_records.items():
        overrides[child_id] = [
            PresenceOverride(
                record.child_id,
                record.start_date,
                record.end_date,
                record.is_present,
                record.note,
            )
            for record in records
        ]
    return PresenceEngine(schedules, overrides)
 async def materialize(
    database: NestQuestDatabase,
    start_date: str,
    end_date: str,
    *,
    child_ids: list[int] | None = None,
    today: datetime.date | None = None,
 ) -> int:
    """Generate quest instances for the closed range [start_date, end_date].
    ``start_date`` and ``end_date`` must be strict ISO calendar dates
    (YYYY-MM-DD) with ``end_date`` on or after ``start_date``; anything
    else raises ValueError naming the offending field.  Returns the number
    of instances upserted for the range (idempotent — a re-run refreshes
    the same rows, never duplicates them).
    ``child_ids`` optionally scopes the walk to exactly those children:
    assignees outside the list are never written, so a caller that only
    wants one child's instances rebuilt (e.g. :func:`regenerate_for_child`
    after a presence change) cannot touch any unrelated child's rows.
    When omitted (or None) the walk covers every assignee as before.
    ``today`` optionally pins the resolved HA-local date the walk's
    no-past guard compares against; it is threaded into every
    :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` write.  When
    omitted the host clock (``datetime.date.today``) is used, which is the
    historical default.  A caller that computed the horizon in Home
    Assistant's configured time zone MUST pass that same date here so a
    time zone behind the host around midnight is not rejected as "past".
    ``start_date`` is clamped up to the resolved "today" (the same
    ``today`` anchor threaded into the no-past guard), so a caller that
    passes a ``start_date`` already in the past never yields a
    past-dated instance: the walk simply begins on today and skips every
    earlier date.  A range entirely in the past therefore produces zero
    instances rather than an error, and the DAO's no-past guard remains
    the authoritative backstop under the lock.
    All inputs are read in ONE locked transaction; each tuple's write then
    goes through the atomic :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`,
    which re-validates the tuple and its current ``due_time`` in the same
    transaction as the INSERT, so a config change that arrives mid-batch
    skips the affected tuples rather than aborting the batch or leaving a
    partial result.
    """
    _validate_date(start_date, "start_date")
    _validate_date(end_date, "end_date")
    if end_date < start_date:
        raise ValueError(
            f"end_date must be on or after start_date, got "
            f"{end_date!r} < {start_date!r}"
        )
    snapshots, schedules_records, overrides_records = await (
        load_materialization_input(database, start_date, end_date)
    )
    engine = _build_engine(schedules_records, overrides_records)
    child_filter = None if child_ids is None else set(child_ids)
    definitions = [
        (snapshot.definition.id, _decode_rule(snapshot),
         snapshot.assignees, snapshot.windows)
        for snapshot in snapshots
    ]
    generated_at = _now_stamp()
    instances = QuestInstancesDao(database)
    start = datetime.datetime.strptime(start_date, "%Y-%m-%d").date()
    end = datetime.datetime.strptime(end_date, "%Y-%m-%d").date()
    # Clamp a past start up to today (the HA-local anchor when the caller
    # pinned one, else the host clock) so the walk can never emit a
    # past-dated instance; the DAO's no-past guard remains the backstop.
    # A range entirely in the past therefore yields zero instances.
    today_date = _resolve_today(today)
    start = max(start, today_date)
    count = 0
    cursor = start
    while cursor <= end:
        iso = cursor.isoformat()
        for definition_id, rule, assignees, windows in definitions:
            if not occurs_on(rule, cursor):
                continue
            for child in assignees:
                if child_filter is not None and child.id not in child_filter:
                    continue
                if not engine.is_present(child.id, cursor):
                    continue
                for window in windows:
                    written = await instances.upsert_if_valid(
                        definition_id,
                        child.id,
                        iso,
                        generated_at,
                        window=window.window,
                        due_time=window.due_time,
                        today=today,
                    )
                    if written is not None:
                        count += 1
        cursor += datetime.timedelta(days=1)
    return count
 async def regenerate_for_definition(
    database: NestQuestDatabase,
    definition_id: int,
    *,
    today: datetime.date | None = None,
    horizon_days: int | None = None,
 ) -> int:
    """Regenerate a definition's future instances after a config change.
    The Feature 06 edit/assignment/activation paths call this after a
    successful write so future instances track the new state: the
    definition's open instances at or after today are deleted (never a
    completed instance, never the past) via
    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted`,
    then the materialization walk re-runs over the rolling horizon
    ``[today, today + horizon_days]`` so the (changed) rule,
    assignee set and windows re-materialize against today's state.
    "today" is computed the same way the walk computes it —
    :func:`~.dao_instances._today` — so the delete cutoff and the
    re-materialization range share one anchor, and the walk's
    ``upsert_if_valid`` no-past guard never rejects the regenerated
    range.  ``today`` optionally pins a caller-resolved HA-local date
    (threaded into both the delete cutoff and the re-materialization)
    so a household time zone behind the host around midnight stays
    consistent.  ``horizon_days`` sizes the re-materialization window;
    when omitted it falls back to :data:`~.const.DEFAULT_HORIZON_DAYS`.
    A bool, non-int, or sub-1 value raises ValueError BEFORE any delete.
    Returns the number of instances the re-materialization
    upserted across the whole snapshot (idempotent — other active
    definitions' tuples refresh in place, never duplicate).
    """
    horizon = _resolve_horizon_days(horizon_days)
    today_date = _resolve_today(today)
    start_date = today_date.isoformat()
    end_date = (
        today_date + datetime.timedelta(days=horizon)
    ).isoformat()
    instances = QuestInstancesDao(database)
    await instances.delete_future_uncompleted(
        definition_id, start_date, today=today
    )
    return await materialize(database, start_date, end_date, today=today)
 # HOOK (Feature 09 presence services): ``regenerate_for_child`` is the
 # child-presence counterpart to ``regenerate_for_definition``.  The
 # presence business layer that lands in Feature 09 MUST call
 # ``regenerate_for_child`` after EVERY presence-state write, so future
 # instances track a child's changed presence: set_presence_pattern
 # (including clearing/setting an empty pattern), deleting/clearing the
 # presence schedule (PresenceSchedulesDao.delete),
 # create_presence_override, and delete_presence_override.  A schedule
 # delete changes presence state too (the child becomes always-present),
 # so it must regenerate just like the others.  It is deliberately NOT
 # wired into ``dao_presence.py``: the DAO layer stays pure storage (no
 # business rules), and no presence business layer exists yet to host the
 # call — see the module docstring note above.
 async def regenerate_for_child(
    database: NestQuestDatabase,
    child_id: int,
    *,
    today: datetime.date | None = None,
    horizon_days: int | None = None,
 ) -> int:
    """Regenerate a child's future instances after a presence change.
    The Feature 09 presence services call this after every
    presence-state write — set_presence_pattern (including clearing or
    setting an empty pattern), deleting/clearing the presence schedule
    (:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
    create_presence_override, and delete_presence_override — so a
    child's future instances track its new presence: the child's open
    instances at or after today are deleted across ALL its definitions
    (never a completed instance, never the past) via
    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`,
    then the materialization walk re-runs over the rolling horizon
    ``[today, today + horizon_days]`` scoped to that child only,
    so the child's now-absent/present dates re-materialize against
    today's presence WITHOUT touching any other child's rows.
    ``child_id`` must be a plain int — bool and float are rejected
    (SQLite binds a bool as 0/1 and a float would round, so a malformed
    id must never mutate the wrong profile).
    "today" is computed the same way the walk computes it —
    :func:`~.dao_instances._today` — and the re-materialization range uses the
    delete's returned effective cutoff (see
    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`),
    so the delete cutoff and the re-materialization window share ONE
    execution-day anchor even when the call is queued across midnight.
    ``today`` optionally pins a caller-resolved HA-local date, threaded
    into the delete cutoff and the re-materialization for the same
    host-vs-HA time-zone consistency.  ``horizon_days`` sizes the
    re-materialization window; when omitted it falls back to
    :data:`~.const.DEFAULT_HORIZON_DAYS`.  A bool, non-int, or sub-1 value
    raises ValueError BEFORE any delete.  Returns the number of instances
    the re-materialization upserted for the child across the whole
    snapshot.
    """
    if isinstance(child_id, bool) or not isinstance(child_id, int):
        raise ValueError(f"child_id must be an integer, got {child_id!r}")
    horizon = _resolve_horizon_days(horizon_days)
    today_date = _resolve_today(today)
    instances = QuestInstancesDao(database)
    # Use the delete's returned effective cutoff as the materialize anchor,
    # NOT the independently-computed "today" above.  If the call is queued
    # across midnight the delete clamps its cutoff to the execution-day;
    # materializing from the stale "today" (now yesterday) would trip the
    # walk's no-past guard and leave the child's future instances deleted
    # but not rebuilt.  One anchor for both keeps them consistent.
    _, effective_cutoff = await instances.delete_future_uncompleted_for_child(
        child_id, today_date.isoformat(), today=today
    )
    start = datetime.date.fromisoformat(effective_cutoff)
    end_date = (start + datetime.timedelta(days=horizon)).isoformat()
    return await materialize(
        database, start.isoformat(), end_date, child_ids=[child_id], today=today
    )
@@ -44,13 +44,11 @@ from dataclasses import dataclass
 from .dao_children import ChildRecord, _connection_lock
 from .dao_rules import (
    QuestDefinitionRecord,
    QuestDefinitionSnapshot,
    QuestDefinitionWindowRecord,
    QuestDefinitionsDao,
    ScheduleRuleStorage,
    ScheduleRulesDao,
    _UNSET,
    _validate_date,
    _validate_time,
    _validate_window,
    schedule_rule_from_storage,
@@ -58,8 +56,7 @@ from .dao_rules import (
    schedule_rule_to_storage,
 )
 from .db import NestQuestDatabase
-from .materialize import regenerate_for_definition
+from .recurrence import ScheduleRule
 from .recurrence import ScheduleRule, occurs_on
@dataclass(frozen=True)
@@ -271,8 +268,6 @@ async def edit_quest_definition(
    icon: str | None | object = _UNSET,
    rule: ScheduleRule | object = _UNSET,
    windows: list[str | tuple[str, str | None]] | object = _UNSET,
    today: datetime.date | None = None,
    horizon_days: int | None = None,
 ) -> CreatedQuestDefinition:
    """Edit a quest definition's metadata, rule and windows atomically.
@@ -294,16 +289,6 @@ async def edit_quest_definition(
    so the returned bundle is a consistent edit snapshot.  Edits change
    future instances only; no ``quest_instances`` or
    ``completion_events`` row is touched.
    ``today`` optionally pins the caller-resolved HA-local date the
    regeneration's no-past guard and horizon are anchored to (threaded
    into :func:`~.materialize.regenerate_for_definition`); it is a plain
    ``datetime.date`` with no HA import here — the Feature 09 service
    supplies the hass-derived value.  When omitted, regeneration falls
    back to the host clock, same as before.  ``horizon_days`` sizes the
    regeneration's re-materialization window the same way (threaded into
    :func:`~.materialize.regenerate_for_definition`); it defaults to
    :data:`~.const.DEFAULT_HORIZON_DAYS` when omitted.
    """
    _validate_definition_id(definition_id)
@@ -332,32 +317,19 @@ async def edit_quest_definition(
        window_specs = _normalize_windows(windows)
    dao = QuestDefinitionsDao(database)
-    try:
+    snapshot = await dao.edit_definition(
-        snapshot = await dao.edit_definition(
+        definition_id,
-            definition_id,
+        title=title_value,
-            title=title_value,
+        description=description_value,
-            description=description_value,
+        icon=icon_value,
-            icon=icon_value,
+        rule=rule_storage,
-            rule=rule_storage,
+        windows=window_specs,
-            windows=window_specs,
+    )
        )
    except ValueError as error:
        # The DAO's missing-definition error names only the id; re-raise
        # so the public contract names the field the caller passed (matching
        # assign/unassign/deactivate).
        message = str(error)
        if message.startswith("quest definition "):
            raise ValueError(f"definition_id: {message}") from error
        raise
    decoded_rule = schedule_rule_from_storage(
        schedule_rule_storage_from_record(snapshot.rule)
    )
    await regenerate_for_definition(
        database, definition_id, today=today, horizon_days=horizon_days
    )
    return CreatedQuestDefinition(
        definition=snapshot.definition,
        rule=decoded_rule,
@@ -370,9 +342,6 @@ async def assign_child(
    database: NestQuestDatabase,
    definition_id: int,
    child_id: int,
    *,
    today: datetime.date | None = None,
    horizon_days: int | None = None,
 ) -> list[ChildRecord]:
    """Assign ``child_id`` to the definition (idempotent).
@@ -386,17 +355,12 @@ async def assign_child(
    write).  Raises ValueError on any rejected argument.  Only the
    ``quest_definition_assignees`` link is written; existing instances
    and completion history are never touched.
    ``today`` optionally pins the caller-resolved HA-local date threaded
    into the assignment's regeneration (see :func:`edit_quest_definition`).
    ``horizon_days`` optionally sizes the regeneration's re-materialization
    window the same way.
    """
    _validate_definition_id(definition_id)
    _validate_child_id(child_id)
    dao = QuestDefinitionsDao(database)
    try:
-        assignees = await dao.add_assignee(definition_id, child_id)
+        return await dao.add_assignee(definition_id, child_id)
    except ValueError as error:
        # The DAO names only the child/definition; re-raise so the
        # public contract names the field the caller actually passed.
@@ -406,19 +370,12 @@ async def assign_child(
        if message.startswith("quest definition "):
            raise ValueError(f"definition_id: {message}") from error
        raise
    await regenerate_for_definition(
        database, definition_id, today=today, horizon_days=horizon_days
    )
    return assignees
 async def unassign_child(
    database: NestQuestDatabase,
    definition_id: int,
    child_id: int,
    *,
    today: datetime.date | None = None,
    horizon_days: int | None = None,
 ) -> bool:
    """Unassign ``child_id`` from the definition; True when removed.
@@ -428,11 +385,6 @@ async def unassign_child(
    was not currently assigned.  Raises ValueError on a rejected
    argument.  Only the ``quest_definition_assignees`` link is written;
    existing instances and completion history are never touched.
    ``today`` optionally pins the caller-resolved HA-local date threaded
    into the unassignment's regeneration (see :func:`edit_quest_definition`).
    ``horizon_days`` optionally sizes the regeneration's re-materialization
    window the same way.
    """
    _validate_definition_id(definition_id)
    _validate_child_id(child_id)
@@ -442,20 +394,13 @@ async def unassign_child(
        raise ValueError(
            f"definition_id: quest definition {definition_id} does not exist"
        )
-    removed = await dao.remove_assignee(definition_id, child_id)
+    return await dao.remove_assignee(definition_id, child_id)
    await regenerate_for_definition(
        database, definition_id, today=today, horizon_days=horizon_days
    )
    return removed
 async def set_quest_definition_active(
    database: NestQuestDatabase,
    definition_id: int,
    is_active: bool,
    *,
    today: datetime.date | None = None,
    horizon_days: int | None = None,
 ) -> CreatedQuestDefinition:
    """Deactivate or reactivate a definition; returns the updated view.
@@ -478,11 +423,6 @@ async def set_quest_definition_active(
    definition, its rule, assignees and windows all run inside the
    connection-scoped lock, so the returned bundle is a consistent
    snapshot that a concurrent mutation cannot race.
    ``today`` optionally pins the caller-resolved HA-local date threaded
    into the activation change's regeneration (see
    :func:`edit_quest_definition`).  ``horizon_days`` optionally sizes the
    regeneration's re-materialization window the same way.
    """
    _validate_definition_id(definition_id)
    if not isinstance(is_active, bool):
@@ -506,98 +446,9 @@ async def set_quest_definition_active(
    rule = schedule_rule_from_storage(
        schedule_rule_storage_from_record(rule_record)
    )
    await regenerate_for_definition(
        database, definition_id, today=today, horizon_days=horizon_days
    )
    return CreatedQuestDefinition(
        definition=updated,
        rule=rule,
        assignees=assignees,
        windows=windows,
    )
 def _bundle_snapshot(
    snapshot: QuestDefinitionSnapshot,
 ) -> CreatedQuestDefinition:
    """Decode a DAO snapshot into the layer's rich view.
    The rule record carried by the snapshot is the one the definition
    referenced at read time, so decoding it here (rather than re-reading
    through :class:`~.dao_rules.ScheduleRulesDao`) preserves the
    coherence the DAO's locked snapshot guarantees: the rule, assignees
    and windows all come from one atomic read, never three separate ones.
    """
    rule = schedule_rule_from_storage(
        schedule_rule_storage_from_record(snapshot.rule)
    )
    return CreatedQuestDefinition(
        definition=snapshot.definition,
        rule=rule,
        assignees=snapshot.assignees,
        windows=snapshot.windows,
    )
 async def list_active_definitions(
    database: NestQuestDatabase,
 ) -> list[CreatedQuestDefinition]:
    """Return every ACTIVE definition with its decoded rule and links.
    Ordered by rising definition id, matching the DAO's ``list_active``
    order, so callers get a stable, repeatable sequence.  Each entry is
    the same rich :class:`CreatedQuestDefinition` snapshot as the rest of
    the layer: the stored row plus its decoded
    :class:`~.recurrence.ScheduleRule`, assignees and windows.  The
    definitions and their links are read by the DAO inside one locked
    transaction, so each bundle is a coherent snapshot that a concurrent
    edit cannot interleave.
    """
    dao = QuestDefinitionsDao(database)
    snapshots = await dao.list_snapshots_active()
    return [_bundle_snapshot(snapshot) for snapshot in snapshots]
 async def list_definitions_for_child(
    database: NestQuestDatabase,
    child_id: int,
 ) -> list[CreatedQuestDefinition]:
    """Return the definitions assigned to ``child_id`` (rich view).
    ``child_id`` must be a plain int (bools and floats rejected, since
    SQLite would bind ``True`` onto child 1).  Results are ordered by
    rising definition id, matching ``list_active_definitions`` and
    ``list_definitions_firing_on``.  Each entry is a
    :class:`CreatedQuestDefinition` snapshot bundling the definition with
    its decoded rule, assignees and windows, read atomically by the DAO.
    """
    _validate_child_id(child_id)
    dao = QuestDefinitionsDao(database)
    snapshots = await dao.list_snapshots_by_child(child_id)
    bundles = [_bundle_snapshot(snapshot) for snapshot in snapshots]
    return sorted(bundles, key=lambda bundle: bundle.definition.id)
 async def list_definitions_firing_on(
    database: NestQuestDatabase,
    date: str,
 ) -> list[CreatedQuestDefinition]:
    """Return the ACTIVE definitions whose rule fires on ``date``.
    ``date`` must be a strict ISO calendar date (YYYY-MM-DD); a malformed
    value raises ValueError naming the field.  Each active definition's
    stored rule is decoded through the task-1 storage mapping and handed
    to the recurrence engine's :func:`~.recurrence.occurs_on`; only the
    definitions whose decoded rule fires on the date are returned, in
    rising definition-id order, each as the same rich
    :class:`CreatedQuestDefinition` snapshot as the rest of the layer.
    The definitions and their rules are read inside one locked
    transaction, so a bundle can never filter on one rule while
    presenting another state's windows.
    """
    _validate_date(date, "date")
    target = datetime.datetime.strptime(date, "%Y-%m-%d").date()
    dao = QuestDefinitionsDao(database)
    snapshots = await dao.list_snapshots_active()
    bundles = [_bundle_snapshot(snapshot) for snapshot in snapshots]
    return [bundle for bundle in bundles if occurs_on(bundle.rule, target)]
@@ -1,12 +0,0 @@
 # Service declarations for the NestQuest integration (Home Assistant
 # services.yaml metadata). Services are domain-scoped: nested under the
 # "nestquest" domain, not repeated per config entry.
 regenerate:
  name: Regenerate quest instances
  description: >-
    Regenerate every future quest instance for the household over the rolling
    horizon, using the same idempotent materialization as the daily rollover
    and the startup backfill. Safe to call at any time: a re-run refreshes the
    same rows instead of duplicating them, and completed instances are never
    touched.
@@ -44,7 +44,6 @@ _HA_MODULES = (
    "homeassistant.exceptions",
    "homeassistant.helpers",
    "homeassistant.helpers.config_validation",
    "homeassistant.helpers.event",
 )
 def _find_spec(name: str):
@@ -84,7 +83,6 @@ for _parent, _child in (
    ("homeassistant", "exceptions"),
    ("homeassistant", "helpers"),
    ("homeassistant.helpers", "config_validation"),
    ("homeassistant.helpers", "event"),
 ):
    setattr(sys.modules[_parent], _child, sys.modules[f"{_parent}.{_child}"])
@@ -244,113 +242,6 @@ class ListenerRegistry:
        return sum(len(listeners) for listeners in self._listeners.values())
 class TimeChangeRegistry:
    """Models HA's time-change listener bookkeeping.
    ``track`` mirrors ``homeassistant.helpers.event.async_track_time_change``:
    each call appends a record (action + hour/minute/second) and returns
    a remove callable that reverses the registration.  Tests inspect
    ``registrations`` and exercise the newest action through :meth:`fire`.
    """
    def __init__(self, hass=None):
        self._hass = hass
        self._registrations: list[dict] = []
    def track(self, action, hour=None, minute=None, second=None):
        record = {
            "action": action,
            "hour": hour,
            "minute": minute,
            "second": second,
        }
        def _remove():
            self._registrations.remove(record)
        record["remove"] = _remove
        self._registrations.append(record)
        return _remove
    @property
    def registrations(self):
        """Return a copy of the live registrations."""
        return list(self._registrations)
    @property
    def size(self) -> int:
        """Number of live registrations."""
        return len(self._registrations)
    async def fire(self, now=None, index: int = -1):
        """Run a registered action as HA's scheduler would, awaiting coroutines."""
        result = self._registrations[index]["action"](now)
        if inspect.isawaitable(result):
            await result
 def _async_track_time_change(hass, action, hour=None, minute=None, second=None):
    """Mirror homeassistant.helpers.event.async_track_time_change.
    Exact HA 2024.6 signature — no ``local`` keyword: the local-time
    wrapper is already this function.  Routes to the registry attached to
    ``hass`` (created on demand), so tests reach the registrations via
    ``hass.time_change``.
    """
    registry = getattr(hass, "time_change", None)
    if registry is None:
        registry = TimeChangeRegistry(hass)
        hass.time_change = registry
    return registry.track(action, hour=hour, minute=minute, second=second)
 _ha_mock("homeassistant.helpers.event").async_track_time_change = _async_track_time_change
 class ServiceRegistry:
    """Models HA's ``hass.services`` service registry.
    ``async_register`` stores a handler under its (domain, service) key,
    ``has_service`` reports registration, and ``async_remove`` removes it
    — exactly the surface Home Assistant's ``ServiceRegistry`` exposes
    (there is deliberately NO ``async_unregister`` alias here, so a caller
    that uses the wrong method name fails instead of being silently
    papered over).  ``call`` invokes a stored handler the way HA's service
    bus would — awaiting a coroutine result — so tests can exercise a
    registered service end-to-end.
    """
    def __init__(self, hass=None):
        self._hass = hass
        self._services: dict[tuple[str, str], object] = {}
    def async_register(self, domain, service, func, schema=None, supports_response=None):
        self._services[(domain, service)] = func
        return None
    def has_service(self, domain, service):
        return (domain, service) in self._services
    def async_remove(self, domain, service):
        self._services.pop((domain, service), None)
        return None
    async def call(self, domain, service, data=None):
        func = self._services.get((domain, service))
        if func is None:
            raise KeyError(f"service {domain}.{service} not registered")
        call = SimpleNamespace(domain=domain, service=service, data=data or {})
        result = func(call)
        if inspect.isawaitable(result):
            await result
        return result
    @property
    def registered_services(self):
        """The registered (domain, service) pairs."""
        return list(self._services)
 def make_config_entry(
    entry_id: str = "test_entry",
    options: dict | None = None,
@@ -412,11 +303,6 @@ def make_hass() -> tuple:
    hass.async_add_executor_job = _run_executor_job
    registry = ListenerRegistry(hass)
    hass.time_change = TimeChangeRegistry(hass)
    hass.services = ServiceRegistry(hass)
    # A valid IANA time zone (the day-rollover listener reads it to
    # compute "today" in HA local time).
    hass.config.time_zone = "UTC"
    async def _async_reload(entry_id: str) -> None:
        registry.reloaded.append(entry_id)
@@ -1,924 +0,0 @@
 """Tests for completion.py: the Feature 08 append-only business layer."""
 from __future__ import annotations
 import asyncio
 import datetime
 import inspect
 import re
 import pytest
 from custom_components.nestquest.completion import (
    append_event,
    complete_instance,
    instance_state,
    uncomplete_instance,
 )
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.dao_instances import (
    EVENT_COMPLETED,
    EVENT_UNCOMPLETED,
    CompletionEventRecord,
    CompletionEventsDao,
    QuestInstancesDao,
 )
 from custom_components.nestquest.dao_rules import (
    QuestDefinitionsDao,
    ScheduleRulesDao,
 )
 from custom_components.nestquest.db import NestQuestDatabase
 from custom_components.nestquest.migrations import apply_migrations
 def _run(coro):
    return asyncio.new_event_loop().run_until_complete(coro)
 def _make_hass_mock():
    from unittest.mock import AsyncMock, MagicMock
    hass = MagicMock()
    hass.async_add_executor_job = AsyncMock(side_effect=(lambda fn, *a: fn(*a)))
    return hass
 def _today_iso() -> str:
    return datetime.date.today().isoformat()
 def _now_stamp() -> str:
    return f"{_today_iso()}T08:00:00+00:00"
 def _future_day(offset: int) -> str:
    return (
        datetime.date.today() + datetime.timedelta(days=offset)
    ).isoformat()
 D1 = _future_day(1)
 async def _prepare(path) -> tuple:
    database = NestQuestDatabase(_make_hass_mock())
    await database.open(path)
    await apply_migrations(database)
    children = ChildrenDao(database)
    rules = ScheduleRulesDao(database)
    definitions = QuestDefinitionsDao(database)
    instances = QuestInstancesDao(database)
    child = await children.create("Ada", _now_stamp())
    rule = await rules.create("daily", D1)
    definition = await definitions.create(
        "Brush teeth", rule.id, _now_stamp(), assignee_child_ids=[child.id]
    )
    instance = await instances.upsert(
        definition.id, child.id, D1, _now_stamp(), window="morning"
    )
    return database, child, instance
 def _with_db(tmp_path, name):
    def _run_test(body):
        async def _main():
            prepared = await _prepare(tmp_path / name)
            try:
                return await body(*prepared)
            finally:
                await prepared[0].close()
        return _run(_main())
    return _run_test
 # ---------------------------------------------------------------------------
 # inverted actor shapes: field-naming ValueErrors, no write
 # ---------------------------------------------------------------------------
 def test_user_without_actor_user_id_rejected() -> None:
    async def _body():
        with pytest.raises(ValueError, match="actor_user_id"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="user",
                was_on_time=True,
            )
        with pytest.raises(ValueError, match="actor_user_id"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="user",
                actor_user_id=None,
                was_on_time=True,
            )
        with pytest.raises(ValueError, match="actor_user_id"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="user",
                actor_user_id="",
                was_on_time=True,
            )
    _run(_body())
 def test_user_must_not_carry_actor_child_id() -> None:
    async def _body():
        with pytest.raises(ValueError, match="actor_child_id"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="user",
                actor_user_id="user-1",
                actor_child_id=1,
                was_on_time=True,
            )
    _run(_body())
 def test_panel_must_not_carry_actor_user_id() -> None:
    async def _body():
        with pytest.raises(ValueError, match="actor_user_id"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="panel",
                actor_user_id="user-1",
                actor_child_id=1,
                was_on_time=True,
            )
    _run(_body())
 def test_panel_requires_actor_child_id() -> None:
    async def _body():
        with pytest.raises(ValueError, match="actor_child_id"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="panel",
                was_on_time=True,
            )
    _run(_body())
 def test_actor_source_service_rejected() -> None:
    async def _body():
        with pytest.raises(ValueError, match="actor_source"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="service",
                actor_user_id="user-1",
                was_on_time=True,
            )
    _run(_body())
 def test_completed_requires_was_on_time() -> None:
    async def _body():
        with pytest.raises(ValueError, match="was_on_time"):
            await append_event(
                object(),
                1,
                1,
                EVENT_COMPLETED,
                actor_source="user",
                actor_user_id="user-1",
            )
    _run(_body())
 # ---------------------------------------------------------------------------
 # happy paths
 # ---------------------------------------------------------------------------
 def test_user_append_round_trips(tmp_path) -> None:
    async def _body(database, child, instance):
        event = await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=True,
        )
        assert isinstance(event, CompletionEventRecord)
        assert event.event_type == EVENT_COMPLETED
        assert event.actor_source == "user"
        assert event.actor_user_id == "user-1"
        assert event.actor_child_id is None
        assert event.was_on_time is True
        assert re.fullmatch(
            r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00", event.occurred_at
        )
        return event
    _with_db(tmp_path, "user-append.db")(_body)
 def test_panel_append_round_trips(tmp_path) -> None:
    async def _body(database, child, instance):
        event = await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="panel",
            actor_child_id=child.id,
            was_on_time=False,
        )
        assert event.actor_source == "panel"
        assert event.actor_user_id is None
        assert event.actor_child_id == child.id
        assert event.was_on_time is False
        assert re.fullmatch(
            r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00", event.occurred_at
        )
        return event
    _with_db(tmp_path, "panel-append.db")(_body)
 def test_uncompleted_allows_null_was_on_time(tmp_path) -> None:
    async def _body(database, child, instance):
        event = await append_event(
            database,
            instance.id,
            child.id,
            EVENT_UNCOMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=None,
        )
        assert event.event_type == EVENT_UNCOMPLETED
        assert event.was_on_time is None
        return event
    _with_db(tmp_path, "uncompleted-null.db")(_body)
 def test_now_pins_occurred_at_utc(tmp_path) -> None:
    async def _body(database, child, instance):
        pinned = datetime.datetime(
            2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
        )
        event = await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=True,
            now=pinned,
        )
        assert event.occurred_at == "2026-09-18T08:00:00+00:00"
        return event
    _with_db(tmp_path, "pinned-now.db")(_body)
 # ---------------------------------------------------------------------------
 # append-only: the module never exposes update/delete
 # ---------------------------------------------------------------------------
 def test_module_never_exposes_update_or_delete() -> None:
    import custom_components.nestquest.completion as completion
    public = {
        name
        for name, _ in inspect.getmembers(completion, inspect.isfunction)
        if not name.startswith("_")
    }
    forbidden = {
        name
        for name in public
        if name.startswith(
            (
                "update",
                "delete",
                "set",
                "clear",
                "remove",
                "modify",
                "edit",
                "upsert",
            )
        )
    }
    assert forbidden == set(), (
        f"completion.py exposed mutation methods: {forbidden}"
    )
    assert "append_event" in public
    assert "instance_state" in public
    assert "complete_instance" in public
    assert "uncomplete_instance" in public
    source = inspect.getsource(completion)
    assert "UPDATE" not in source
    assert "DELETE" not in source
    assert "INSERT" not in source
 # ---------------------------------------------------------------------------
 # instance_state: derived from the latest event
 # ---------------------------------------------------------------------------
 def test_instance_state_open_when_no_events(tmp_path) -> None:
    async def _body(database, child, instance):
        assert await instance_state(database, instance.id) == "open"
    _with_db(tmp_path, "state-none.db")(_body)
 def test_instance_state_open_when_latest_uncompleted(tmp_path) -> None:
    async def _body(database, child, instance):
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=True,
        )
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_UNCOMPLETED,
            actor_source="user",
            actor_user_id="user-1",
        )
        assert await instance_state(database, instance.id) == "open"
    _with_db(tmp_path, "state-uncompleted.db")(_body)
 def test_instance_state_unknown_instance_id_raises(tmp_path) -> None:
    async def _body(database, child, instance):
        with pytest.raises(ValueError, match="instance_id"):
            await instance_state(database, instance.id + 999)
    _with_db(tmp_path, "state-unknown.db")(_body)
 def test_instance_state_rejects_non_integer_id() -> None:
    async def _body():
        with pytest.raises(ValueError, match="instance_id"):
            await instance_state(object(), "1")
        with pytest.raises(ValueError, match="instance_id"):
            await instance_state(object(), True)
    _run(_body())
 def test_instance_state_three_events_returns_done_and_preserves_rows(
    tmp_path,
 ) -> None:
    async def _body(database, child, instance):
        base = datetime.datetime(
            2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
        )
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=True,
            now=base,
        )
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_UNCOMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            now=base + datetime.timedelta(seconds=1),
        )
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=False,
            now=base + datetime.timedelta(seconds=2),
        )
        events = CompletionEventsDao(database)
        before = await events.list_by_instance(instance.id)
        assert [e.event_type for e in before] == [
            EVENT_COMPLETED,
            EVENT_UNCOMPLETED,
            EVENT_COMPLETED,
        ]
        assert await instance_state(database, instance.id) == "done"
        after = await events.list_by_instance(instance.id)
        assert after == before
        assert len(after) == 3
    _with_db(tmp_path, "state-three.db")(_body)
 # ---------------------------------------------------------------------------
 # complete_instance: append completed, no-op if already done
 # ---------------------------------------------------------------------------
 def test_complete_instance_appends_and_returns_done(tmp_path) -> None:
    async def _body(database, child, instance):
        events = CompletionEventsDao(database)
        assert await events.list_by_instance(instance.id) == []
        state = await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
        )
        assert state == "done"
        assert await instance_state(database, instance.id) == "done"
        rows = await events.list_by_instance(instance.id)
        assert len(rows) == 1
        assert rows[0].event_type == EVENT_COMPLETED
        assert rows[0].actor_source == "user"
        assert rows[0].actor_user_id == "user-1"
        assert rows[0].was_on_time is True
    _with_db(tmp_path, "complete-open.db")(_body)
 def test_complete_instance_already_done_is_noop(tmp_path) -> None:
    async def _body(database, child, instance):
        first = await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
        )
        events = CompletionEventsDao(database)
        before = await events.list_by_instance(instance.id)
        assert first == "done"
        assert len(before) == 1
        second = await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-2",
        )
        after = await events.list_by_instance(instance.id)
        assert second == "done"
        assert after == before
        assert after[0].actor_user_id == "user-1"
    _with_db(tmp_path, "complete-noop.db")(_body)
 def test_complete_instance_unknown_instance_id_raises(tmp_path) -> None:
    async def _body(database, child, instance):
        with pytest.raises(ValueError, match="instance_id"):
            await complete_instance(
                database,
                instance.id + 999,
                actor_source="user",
                actor_user_id="user-1",
            )
    _with_db(tmp_path, "complete-unknown.db")(_body)
 def test_complete_instance_rejects_non_integer_id() -> None:
    async def _body():
        with pytest.raises(ValueError, match="instance_id"):
            await complete_instance(
                object(),
                "1",
                actor_source="user",
                actor_user_id="user-1",
            )
        with pytest.raises(ValueError, match="instance_id"):
            await complete_instance(
                object(),
                True,
                actor_source="user",
                actor_user_id="user-1",
            )
    _run(_body())
 def test_complete_instance_after_uncompleted_appends(tmp_path) -> None:
    async def _body(database, child, instance):
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_COMPLETED,
            actor_source="user",
            actor_user_id="user-1",
            was_on_time=True,
        )
        await append_event(
            database,
            instance.id,
            child.id,
            EVENT_UNCOMPLETED,
            actor_source="user",
            actor_user_id="user-1",
        )
        events = CompletionEventsDao(database)
        before = await events.list_by_instance(instance.id)
        assert await instance_state(database, instance.id) == "open"
        state = await complete_instance(
            database,
            instance.id,
            actor_source="panel",
            actor_child_id=child.id,
        )
        assert state == "done"
        after = await events.list_by_instance(instance.id)
        assert len(after) == len(before) + 1
        assert after[-1].event_type == EVENT_COMPLETED
        assert after[-1].actor_source == "panel"
        assert after[-1].was_on_time is True
    _with_db(tmp_path, "complete-reopen.db")(_body)
 def test_complete_instance_now_pins_occurred_at(tmp_path) -> None:
    async def _body(database, child, instance):
        pinned = datetime.datetime(
            2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
        )
        await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
            now=pinned,
        )
        rows = await CompletionEventsDao(database).list_by_instance(
            instance.id
        )
        assert rows[0].occurred_at == "2026-09-18T08:00:00+00:00"
    _with_db(tmp_path, "complete-pinned.db")(_body)
 def _gated_hass(armed: dict, gate_open: asyncio.Event, a_started: asyncio.Event):
    """A hass mock whose executor gates the FIRST ``_execute`` job after
    arming — the INSERT of whichever ``complete_instance`` starts first
    — proving that caller holds the connection lock and the second
    caller must queue behind it."""
    from unittest.mock import MagicMock
    hass = MagicMock()
    async def _gated_executor(fn, *args):
        if armed["active"]:
            if getattr(fn, "__name__", "") == "_execute" and not armed["gated"]:
                armed["gated"] = True
                a_started.set()
                await gate_open.wait()
        return fn(*args)
    hass.async_add_executor_job = _gated_executor
    return hass
 def test_complete_instance_concurrent_second_call_is_noop(tmp_path) -> None:
    """Two racing completes cannot both append.
    Deterministic gate: task A is paused at its INSERT (it holds the
    connection lock); task B is then started and must queue.  A
    finishes, B sees done and appends nothing.
    """
    async def _main():
        armed = {"active": False, "gated": False}
        gate_open = asyncio.Event()
        a_started = asyncio.Event()
        hass = _gated_hass(armed, gate_open, a_started)
        database = NestQuestDatabase(hass)
        await database.open(tmp_path / "complete-race.db")
        try:
            await apply_migrations(database)
            children = ChildrenDao(database)
            rules = ScheduleRulesDao(database)
            definitions = QuestDefinitionsDao(database)
            instances = QuestInstancesDao(database)
            child = await children.create("Ada", _now_stamp())
            rule = await rules.create("daily", D1)
            definition = await definitions.create(
                "Brush teeth",
                rule.id,
                _now_stamp(),
                assignee_child_ids=[child.id],
            )
            instance = await instances.upsert(
                definition.id,
                child.id,
                D1,
                _now_stamp(),
                window="morning",
            )
            armed["active"] = True
            task_a = asyncio.ensure_future(
                complete_instance(
                    database,
                    instance.id,
                    actor_source="user",
                    actor_user_id="user-1",
                )
            )
            await a_started.wait()
            armed["active"] = False
            task_b = asyncio.ensure_future(
                complete_instance(
                    database,
                    instance.id,
                    actor_source="user",
                    actor_user_id="user-2",
                )
            )
            await asyncio.sleep(0)
            gate_open.set()
            state_a, state_b = await asyncio.gather(task_a, task_b)
            assert state_a == "done"
            assert state_b == "done"
            rows = await CompletionEventsDao(database).list_by_instance(
                instance.id
            )
            assert len(rows) == 1
            assert rows[0].actor_user_id == "user-1"
        finally:
            await database.close()
    _run(_main())
 # ---------------------------------------------------------------------------
 # uncomplete_instance: append uncompleted, no-op if already open
 # ---------------------------------------------------------------------------
 def test_uncomplete_instance_appends_and_leaves_original_untouched(
    tmp_path,
 ) -> None:
    async def _body(database, child, instance):
        completed_at = datetime.datetime(
            2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
        )
        await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
            now=completed_at,
        )
        events = CompletionEventsDao(database)
        before = await events.list_by_instance(instance.id)
        assert len(before) == 1
        original = before[0]
        assert original.event_type == EVENT_COMPLETED
        assert original.occurred_at == "2026-09-18T08:00:00+00:00"
        assert original.actor_source == "user"
        assert original.actor_user_id == "user-1"
        assert original.actor_child_id is None
        uncompleted_at = completed_at + datetime.timedelta(seconds=1)
        state = await uncomplete_instance(
            database,
            instance.id,
            actor_source="panel",
            actor_child_id=child.id,
            now=uncompleted_at,
        )
        assert state == "open"
        assert await instance_state(database, instance.id) == "open"
        after = await events.list_by_instance(instance.id)
        assert len(after) == 2
        assert after[0].id == original.id
        assert after[0].event_type == EVENT_COMPLETED
        assert after[0].occurred_at == original.occurred_at
        assert after[0].actor_source == original.actor_source
        assert after[0].actor_user_id == original.actor_user_id
        assert after[0].actor_child_id == original.actor_child_id
        assert after[1].event_type == EVENT_UNCOMPLETED
        assert after[1].actor_source == "panel"
        assert after[1].actor_child_id == child.id
        assert after[1].was_on_time is None
    _with_db(tmp_path, "uncomplete-append.db")(_body)
 def test_uncomplete_instance_already_open_is_noop(tmp_path) -> None:
    async def _body(database, child, instance):
        events = CompletionEventsDao(database)
        assert await events.list_by_instance(instance.id) == []
        first = await uncomplete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
        )
        after_first = await events.list_by_instance(instance.id)
        assert first == "open"
        assert after_first == []
        await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
        )
        await uncomplete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
        )
        before = await events.list_by_instance(instance.id)
        assert len(before) == 2
        second = await uncomplete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-2",
        )
        after = await events.list_by_instance(instance.id)
        assert second == "open"
        assert after == before
        assert after[0].actor_user_id == "user-1"
        assert after[1].actor_user_id == "user-1"
    _with_db(tmp_path, "uncomplete-noop.db")(_body)
 def test_uncomplete_instance_unknown_instance_id_raises(tmp_path) -> None:
    async def _body(database, child, instance):
        with pytest.raises(ValueError, match="instance_id"):
            await uncomplete_instance(
                database,
                instance.id + 999,
                actor_source="user",
                actor_user_id="user-1",
            )
    _with_db(tmp_path, "uncomplete-unknown.db")(_body)
 def test_uncomplete_instance_rejects_non_integer_id() -> None:
    async def _body():
        with pytest.raises(ValueError, match="instance_id"):
            await uncomplete_instance(
                object(),
                "1",
                actor_source="user",
                actor_user_id="user-1",
            )
        with pytest.raises(ValueError, match="instance_id"):
            await uncomplete_instance(
                object(),
                True,
                actor_source="user",
                actor_user_id="user-1",
            )
    _run(_body())
 def test_uncomplete_instance_now_pins_occurred_at(tmp_path) -> None:
    async def _body(database, child, instance):
        await complete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
            now=datetime.datetime(
                2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
            ),
        )
        pinned = datetime.datetime(
            2026, 9, 18, 8, 0, 1, tzinfo=datetime.timezone.utc
        )
        await uncomplete_instance(
            database,
            instance.id,
            actor_source="user",
            actor_user_id="user-1",
            now=pinned,
        )
        rows = await CompletionEventsDao(database).list_by_instance(
            instance.id
        )
        assert rows[1].occurred_at == "2026-09-18T08:00:01+00:00"
    _with_db(tmp_path, "uncomplete-pinned.db")(_body)
 def test_uncomplete_instance_concurrent_second_call_is_noop(tmp_path) -> None:
    """Two racing uncompletes cannot both append.
    Deterministic gate: task A is paused at its INSERT (it holds the
    connection lock); task B is then started and must queue.  A
    finishes, B sees open and appends nothing.
    """
    async def _main():
        armed = {"active": False, "gated": False}
        gate_open = asyncio.Event()
        a_started = asyncio.Event()
        hass = _gated_hass(armed, gate_open, a_started)
        database = NestQuestDatabase(hass)
        await database.open(tmp_path / "uncomplete-race.db")
        try:
            await apply_migrations(database)
            children = ChildrenDao(database)
            rules = ScheduleRulesDao(database)
            definitions = QuestDefinitionsDao(database)
            instances = QuestInstancesDao(database)
            child = await children.create("Ada", _now_stamp())
            rule = await rules.create("daily", D1)
            definition = await definitions.create(
                "Brush teeth",
                rule.id,
                _now_stamp(),
                assignee_child_ids=[child.id],
            )
            instance = await instances.upsert(
                definition.id,
                child.id,
                D1,
                _now_stamp(),
                window="morning",
            )
            await complete_instance(
                database,
                instance.id,
                actor_source="user",
                actor_user_id="user-1",
            )
            armed["active"] = True
            task_a = asyncio.ensure_future(
                uncomplete_instance(
                    database,
                    instance.id,
                    actor_source="user",
                    actor_user_id="user-1",
                )
            )
            await a_started.wait()
            armed["active"] = False
            task_b = asyncio.ensure_future(
                uncomplete_instance(
                    database,
                    instance.id,
                    actor_source="user",
                    actor_user_id="user-2",
                )
            )
            await asyncio.sleep(0)
            gate_open.set()
            state_a, state_b = await asyncio.gather(task_a, task_b)
            assert state_a == "open"
            assert state_b == "open"
            rows = await CompletionEventsDao(database).list_by_instance(
                instance.id
            )
            assert len(rows) == 2
            assert rows[0].event_type == EVENT_COMPLETED
            assert rows[1].event_type == EVENT_UNCOMPLETED
            assert rows[1].actor_user_id == "user-1"
        finally:
            await database.close()
    _run(_main())
@@ -8,13 +8,7 @@ import pytest
 from conftest import make_config_entry, make_hass, wire_entry_to_registry
 from custom_components.nestquest import DOMAIN, async_setup_entry, async_unload_entry
-from custom_components.nestquest.const import (
+from custom_components.nestquest.const import DOMAIN as DOMAIN_CONST
    CONF_DAY_ROLLOVER_TIME,
    CONF_HORIZON_DAYS,
    DEFAULT_HORIZON_DAYS,
    SERVICE_REGENERATE,
    DOMAIN as DOMAIN_CONST,
 )
 def _wire(entry, registry):
@@ -243,163 +237,6 @@ async def test_unload_closes_database_even_when_listener_removal_raises() -> Non
    assert database.connected is False, "database leaked despite remover error"
    assert entry.runtime_data is None
    assert DOMAIN not in hass.data
    assert hass.time_change.size == 0, "time-change listener leaked"
 async def test_unload_cancels_time_listener_even_when_update_remover_raises() -> None:
    """A raising update-listener remover must not skip the time-change cancel.
    Both removers are independent: the update-listener remover raising must
    still cancel the daily time-change callback, whose action would otherwise
    fire after unload against a closed database.
    """
    class _RemoveBoom(Exception):
        pass
    def _remover():
        raise _RemoveBoom()
    entry = make_config_entry(entry_id="update-boom-time-cancel")
    entry.add_update_listener = lambda listener: _remover
    hass, _registry = make_hass()
    await async_setup_entry(hass, entry)
    assert hass.time_change.size == 1
    with pytest.raises(_RemoveBoom):
        await async_unload_entry(hass, entry)
    assert hass.time_change.size == 0, "time-change listener not cancelled"
    assert entry.runtime_data is None
    assert DOMAIN not in hass.data
 async def test_setup_registers_day_rollover_listener(hass, make_entry) -> None:
    """Setup registers a daily rollover listener and stores its cancel fn."""
    entry = _wire(make_entry(), hass.registry)
    assert await async_setup_entry(hass, entry) is True
    assert hass.time_change.size == 1
    registration = hass.time_change.registrations[0]
    assert registration["hour"] == 0
    assert registration["minute"] == 0
    assert callable(entry.runtime_data.remove_time_change_listener)
 async def test_setup_registers_day_rollover_at_configured_time(hass, make_entry) -> None:
    """The listener fires at the entry option's rollover time, not the default."""
    entry = _wire(make_entry(options={CONF_DAY_ROLLOVER_TIME: "06:30"}), hass.registry)
    await async_setup_entry(hass, entry)
    registration = hass.time_change.registrations[0]
    assert registration["hour"] == 6
    assert registration["minute"] == 30
 async def test_unload_cancels_day_rollover_listener(hass, make_entry) -> None:
    """Unload removes the time-change listener alongside the update listener."""
    entry = _wire(make_entry(), hass.registry)
    await async_setup_entry(hass, entry)
    assert hass.time_change.size == 1
    assert await async_unload_entry(hass, entry) is True
    assert hass.time_change.size == 0
 async def test_rollover_time_change_reregisters_listener_at_new_time(
    hass, make_entry
 ) -> None:
    """A rollover-time options change re-registers the listener at the new time."""
    entry = _wire(
        make_entry(options={CONF_DAY_ROLLOVER_TIME: "00:00"}), hass.registry
    )
    await async_setup_entry(hass, entry)
    assert (hass.time_change.registrations[0]["hour"], hass.time_change.registrations[0]["minute"]) == (0, 0)
    # The options flow writes the new rollover time, then HA reloads the
    # entry: unload tears down the old listener, setup re-registers it.
    entry.options = {CONF_DAY_ROLLOVER_TIME: "06:30"}
    await async_unload_entry(hass, entry)
    assert hass.time_change.size == 0
    assert await async_setup_entry(hass, entry) is True
    assert hass.time_change.size == 1
    registration = hass.time_change.registrations[0]
    assert (registration["hour"], registration["minute"]) == (6, 30)
 async def test_day_rollover_listener_materializes_ha_local_horizon(
    hass, make_entry, monkeypatch
 ) -> None:
    """Firing the listener materializes today..today+horizon in HA local time."""
    import datetime
    from unittest.mock import AsyncMock
    from zoneinfo import ZoneInfo
    import custom_components.nestquest as nestquest
    entry = _wire(make_entry(), hass.registry)
    await async_setup_entry(hass, entry)
    database = entry.runtime_data.database
    fake = AsyncMock()
    monkeypatch.setattr(nestquest, "_materialize_run", fake)
    time_zone = ZoneInfo(hass.config.time_zone)
    today = datetime.datetime.now(time_zone).date()
    expected_start = today.isoformat()
    expected_end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
    await hass.time_change.fire()
    fake.assert_awaited_once_with(
        database, expected_start, expected_end, today=today
    )
 async def test_day_rollover_uses_configured_horizon_days(hass, make_entry) -> None:
    """The daily run materializes only the configured horizon window."""
    import datetime
    from custom_components.nestquest.dao_instances import QuestInstancesDao
    entry = _wire(make_entry(options={CONF_HORIZON_DAYS: 5}), hass.registry)
    assert await async_setup_entry(hass, entry) is True
    database = entry.runtime_data.database
    # A definition created AFTER setup has no instances yet (create does not
    # materialize); firing the daily listener must generate only the horizon.
    child_id = await _seed_daily_child_and_definition(
        database, _local_today(hass)
    )
    await hass.time_change.fire()
    today = _local_today(hass)
    end = (today + datetime.timedelta(days=5)).isoformat()
    records = await QuestInstancesDao(database).list_by_date_range(
        child_id, today.isoformat(), end
    )
    assert len(records) == 6
    beyond = (today + datetime.timedelta(days=6)).isoformat()
    beyond_end = (
        today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
    ).isoformat()
    assert await QuestInstancesDao(database).list_by_date_range(
        child_id, beyond, beyond_end
    ) == []
 def test_day_rollover_time_change_tracker_rejects_local_kwarg() -> None:
    """The fake async_track_time_change mirrors HA 2024.6 (no ``local`` kwarg).
    Setup drives the local-time wrapper directly, so passing ``local=`` must
    raise TypeError — otherwise a regression in the production call would be
    silently masked by the fake.
    """
    import inspect as _inspect
    from homeassistant.helpers.event import async_track_time_change
    params = _inspect.signature(async_track_time_change).parameters
    assert list(params) == ["hass", "action", "hour", "minute", "second"]
    with pytest.raises(TypeError):
        async_track_time_change(None, lambda _now: None, hour=0, minute=0, local=True)
 async def test_setup_applies_all_v1_tables(hass, make_entry) -> None:
@@ -418,264 +255,4 @@ async def test_setup_applies_all_v1_tables(hass, make_entry) -> None:
        "quest_definitions",
        "schedule_rules",
    ]
-    await async_unload_entry(hass, entry)
+    await async_unload_entry(hass, entry)
 async def _seed_daily_child_and_definition(database, today) -> int:
    """Create one always-present child + a daily definition starting today.
    Returns the child's id.  No presence schedule means the child is present
    every day, so the daily rule yields exactly one instance per horizon day.
    """
    from custom_components.nestquest.dao_children import ChildrenDao
    from custom_components.nestquest.quest_definitions import (
        create_quest_definition,
    )
    from custom_components.nestquest.recurrence import RuleType, ScheduleRule
    NOW = "2026-09-14T12:00:00+00:00"
    child = await ChildrenDao(database).create("Ada", NOW)
    await create_quest_definition(
        database,
        "Daily chore",
        ScheduleRule(rule_type=RuleType.DAILY, start_date=today.isoformat()),
        [child.id],
        ["morning"],
    )
    return child.id
 def _local_today(hass) -> "datetime.date":
    import datetime
    from zoneinfo import ZoneInfo
    return datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
 async def test_setup_backfills_instances_over_horizon(hass, make_entry) -> None:
    """Setup materializes once so a restart backfills any missed days."""
    import datetime
    from custom_components.nestquest.dao_instances import QuestInstancesDao
    from custom_components.nestquest.db import NestQuestDatabase
    from custom_components.nestquest.migrations import apply_migrations
    from custom_components.nestquest.store import async_get_db_path
    # Seed the database BEFORE setup: a restart reopens an existing file that
    # already holds definitions.  The startup backfill must pick them up.
    db_path = await async_get_db_path(hass)
    pre = NestQuestDatabase(hass)
    await pre.open(db_path)
    await apply_migrations(pre)
    child_id = await _seed_daily_child_and_definition(pre, _local_today(hass))
    await pre.close()
    entry = _wire(make_entry(), hass.registry)
    assert await async_setup_entry(hass, entry) is True
    today = _local_today(hass)
    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
    records = await QuestInstancesDao(entry.runtime_data.database).list_by_date_range(
        child_id, today.isoformat(), end
    )
    assert len(records) == DEFAULT_HORIZON_DAYS + 1
 async def test_setup_backfills_configured_horizon_days(hass, make_entry) -> None:
    """Setup backfills only the configured (non-default) horizon window."""
    import datetime
    from custom_components.nestquest.dao_instances import QuestInstancesDao
    from custom_components.nestquest.db import NestQuestDatabase
    from custom_components.nestquest.migrations import apply_migrations
    from custom_components.nestquest.store import async_get_db_path
    db_path = await async_get_db_path(hass)
    pre = NestQuestDatabase(hass)
    await pre.open(db_path)
    await apply_migrations(pre)
    child_id = await _seed_daily_child_and_definition(pre, _local_today(hass))
    await pre.close()
    entry = _wire(
        make_entry(options={CONF_HORIZON_DAYS: 5}), hass.registry
    )
    assert await async_setup_entry(hass, entry) is True
    today = _local_today(hass)
    end = (today + datetime.timedelta(days=5)).isoformat()
    records = await QuestInstancesDao(
        entry.runtime_data.database
    ).list_by_date_range(child_id, today.isoformat(), end)
    assert len(records) == 6
    beyond = (today + datetime.timedelta(days=6)).isoformat()
    beyond_end = (
        today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
    ).isoformat()
    assert await QuestInstancesDao(
        entry.runtime_data.database
    ).list_by_date_range(child_id, beyond, beyond_end) == []
 def test_configured_horizon_days_validates_and_falls_back() -> None:
    """The configured horizon is validated; a malformed value uses the default."""
    import custom_components.nestquest as nestquest
    assert nestquest._configured_horizon_days({CONF_HORIZON_DAYS: 5}) == 5
    assert nestquest._configured_horizon_days({}) == DEFAULT_HORIZON_DAYS
    assert (
        nestquest._configured_horizon_days({CONF_HORIZON_DAYS: True})
        == DEFAULT_HORIZON_DAYS
    )
    assert (
        nestquest._configured_horizon_days({CONF_HORIZON_DAYS: "5"})
        == DEFAULT_HORIZON_DAYS
    )
    assert (
        nestquest._configured_horizon_days({CONF_HORIZON_DAYS: 0})
        == DEFAULT_HORIZON_DAYS
    )
 async def test_regenerate_service_registered_and_materializes(
    hass, make_entry
 ) -> None:
    """``nestquest.regenerate`` is registered and calling it regenerates."""
    import datetime
    from custom_components.nestquest.dao_instances import QuestInstancesDao
    entry = _wire(make_entry(), hass.registry)
    assert await async_setup_entry(hass, entry) is True
    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
    # A definition created AFTER setup has no instances yet (create does not
    # materialize); the service must generate them on demand.
    database = entry.runtime_data.database
    child_id = await _seed_daily_child_and_definition(database, _local_today(hass))
    await hass.services.call(DOMAIN, SERVICE_REGENERATE)
    today = _local_today(hass)
    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
    records = await QuestInstancesDao(database).list_by_date_range(
        child_id, today.isoformat(), end
    )
    assert len(records) == DEFAULT_HORIZON_DAYS + 1
 async def test_regenerate_service_uses_configured_horizon_days(
    hass, make_entry
 ) -> None:
    """``nestquest.regenerate`` regenerates only the configured horizon."""
    import datetime
    from custom_components.nestquest.dao_instances import QuestInstancesDao
    entry = _wire(
        make_entry(options={CONF_HORIZON_DAYS: 5}), hass.registry
    )
    assert await async_setup_entry(hass, entry) is True
    database = entry.runtime_data.database
    child_id = await _seed_daily_child_and_definition(database, _local_today(hass))
    await hass.services.call(DOMAIN, SERVICE_REGENERATE)
    today = _local_today(hass)
    end = (today + datetime.timedelta(days=5)).isoformat()
    records = await QuestInstancesDao(database).list_by_date_range(
        child_id, today.isoformat(), end
    )
    assert len(records) == 6
    beyond = (today + datetime.timedelta(days=6)).isoformat()
    beyond_end = (
        today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
    ).isoformat()
    assert await QuestInstancesDao(database).list_by_date_range(
        child_id, beyond, beyond_end
    ) == []
 async def test_unload_deregisters_regenerate_service(hass, make_entry) -> None:
    """Unload removes the ``regenerate`` service so no stale entry leaks."""
    entry = _wire(make_entry(), hass.registry)
    assert await async_setup_entry(hass, entry) is True
    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
    assert await async_unload_entry(hass, entry) is True
    assert not hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
 async def test_regenerate_service_is_domain_scoped_across_entries(
    hass, make_entry
 ) -> None:
    """The ``regenerate`` service is domain-global, not per-entry.
    With two loaded entries the service must be registered and functional;
    unloading one entry must keep it registered and functional for the
    remaining entry; unloading the final entry must remove it.
    """
    import datetime
    from custom_components.nestquest.dao_instances import QuestInstancesDao
    entry_a = _wire(make_entry(entry_id="entry_a"), hass.registry)
    entry_b = _wire(make_entry(entry_id="entry_b"), hass.registry)
    assert await async_setup_entry(hass, entry_a) is True
    assert await async_setup_entry(hass, entry_b) is True
    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
    # The domain-global handler resolves a live database from any entry.
    database_b = entry_b.runtime_data.database
    child_id = await _seed_daily_child_and_definition(
        database_b, _local_today(hass)
    )
    await hass.services.call(DOMAIN, SERVICE_REGENERATE)
    today = _local_today(hass)
    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
    records = await QuestInstancesDao(database_b).list_by_date_range(
        child_id, today.isoformat(), end
    )
    assert len(records) == DEFAULT_HORIZON_DAYS + 1
    # Unloading one entry must not tear down the shared service.
    assert await async_unload_entry(hass, entry_a) is True
    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
    # It still works for the remaining entry.
    await hass.services.call(DOMAIN, SERVICE_REGENERATE)
    # Unloading the final entry removes the domain-global service.
    assert await async_unload_entry(hass, entry_b) is True
    assert not hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
 async def test_setup_cleans_listeners_when_materialization_raises(
    hass, make_entry, monkeypatch
 ) -> None:
    """A startup-materialization failure rolls back every registered listener.
    The daily and update listeners are installed before the startup
    materialization runs; when that walk raises, the database is closed but
    the remover callables must also be invoked so no listener survives
    firing against a closed database.
    """
    import custom_components.nestquest as nestquest
    async def _boom(*_args, **_kwargs):
        raise RuntimeError("materialization failed")
    monkeypatch.setattr(nestquest, "_materialize_run", _boom)
    entry = _wire(make_entry(), hass.registry)
    with pytest.raises(RuntimeError, match="materialization failed"):
        await async_setup_entry(hass, entry)
    assert hass.time_change.size == 0
    assert hass.registry.size == 0
    assert not hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
    assert not hasattr(entry, "runtime_data")
@@ -8,7 +8,6 @@ import re
 import pytest
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.const import DEFAULT_HORIZON_DAYS
 from custom_components.nestquest.dao_instances import (
    CompletionEventsDao,
    QuestInstancesDao,
@@ -25,9 +24,6 @@ from custom_components.nestquest.quest_definitions import (
    assign_child,
    create_quest_definition,
    edit_quest_definition,
    list_active_definitions,
    list_definitions_firing_on,
    list_definitions_for_child,
    set_quest_definition_active,
    unassign_child,
 )
@@ -787,24 +783,6 @@ def test_edit_rejects_nonexistent_definition(tmp_path) -> None:
    _with_db(tmp_path, "edit-missing-definition.db")(_body)
 def test_edit_nonexistent_definition_names_field(tmp_path) -> None:
    """A missing definition's error names the ``definition_id`` field.
    The DAO raises a bare "quest definition <id> does not exist"; the
    business layer must re-raise it prefixed with the field the caller
    passed, matching assign/unassign/deactivate.
    """
    async def _body(database, children, rules, definitions, child):
        with pytest.raises(
            ValueError,
            match="definition_id: quest definition 999 does not exist",
        ):
            await edit_quest_definition(database, 999, title="X")
        return None
    _with_db(tmp_path, "edit-missing-definition-field.db")(_body)
@pytest.mark.parametrize("bad", [True, 1.5, "1", None])
 def test_edit_rejects_non_int_definition_id(tmp_path, bad) -> None:
    async def _body(database, children, rules, definitions, child):
@@ -1280,19 +1258,11 @@ def test_set_quest_definition_active_nonexistent_definition_names_field(
    _with_db(tmp_path, "set-active-missing-definition.db")(_body)
-def test_set_quest_definition_active_preserves_completed_and_history(
+def test_set_quest_definition_active_never_deletes_or_touches_instances(
    tmp_path,
 ) -> None:
-    """Deactivation stops future generation; reactivation resumes it.
+    """Deactivation hides the definition but deletes nothing, and
-
+    pre-existing instances and completion history survive unchanged."""
    The Feature 07 wiring makes both transitions regenerate the
    definition's rolling horizon: future OPEN instances are removed on
    deactivation and re-materialized on reactivation.  A pre-existing
    COMPLETED instance and its completion events always survive both
    transitions unchanged (regeneration never touches completed rows or
    the past), and the append-only completion-events table is never
    rewritten.
    """
    async def _body(database, children, rules, definitions, child):
        created = await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
@@ -1319,6 +1289,9 @@ def test_set_quest_definition_active_preserves_completed_and_history(
            actor_user_id="admin-1",
        )
        instance_count = await database.fetch_one(
            "SELECT COUNT(*) FROM quest_instances"
        )
        event_count = await database.fetch_one(
            "SELECT COUNT(*) FROM completion_events"
        )
@@ -1338,25 +1311,29 @@ def test_set_quest_definition_active_preserves_completed_and_history(
            definition_id
        )] == ["morning"]
        # The pre-existing instance and completion event survive with
-        # unchanged ids and contents, and no new event rows appeared.
+        # unchanged ids and contents, and no new rows appeared.
        assert await instances.get_by_id(instance.id) == instance
        assert await events.list_by_instance(instance.id) == [event]
        assert await database.fetch_one(
            "SELECT COUNT(*) FROM quest_instances"
        ) == instance_count
        assert await database.fetch_one(
            "SELECT COUNT(*) FROM completion_events"
        ) == event_count
        await set_quest_definition_active(database, definition_id, True)
        assert (await definitions.get(definition_id)).is_active is True
        # Reactivation regenerates future OPEN instances, but the
        # completed instance and its history survive the sweep unchanged.
        assert await instances.get_by_id(instance.id) == instance
        assert await events.list_by_instance(instance.id) == [event]
        assert await database.fetch_one(
            "SELECT COUNT(*) FROM quest_instances"
        ) == instance_count
        assert await database.fetch_one(
            "SELECT COUNT(*) FROM completion_events"
        ) == event_count
        return None
-    _with_db(tmp_path, "set-active-preserves-completed.db")(_body)
+    _with_db(tmp_path, "set-active-never-deletes.db")(_body)
 def _gated_hass(
@@ -1443,567 +1420,3 @@ def test_set_quest_definition_active_concurrent_opposite_transitions_return_own(
            await database.close()
    _run(_main())
 # ---------------------------------------------------------------------------
 # list query helpers: list_active_definitions / list_definitions_for_child /
 # list_definitions_firing_on
 # ---------------------------------------------------------------------------
 def test_list_active_definitions_returns_only_active_in_id_order(tmp_path) -> None:
    """Only active definitions come back, in rising id order, each rich.
    Two definitions are created (ids 1 and 2), then definition 1 is
    deactivated.  ``list_active_definitions`` must return only definition
    2, and every bundle must carry the decoded rule, assignees and
    windows of its own definition.
    """
    async def _body(database, children, rules, definitions, child):
        bo = await children.create("Bo", NOW)
        first = await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
        )
        weekly = ScheduleRule(
            rule_type=RuleType.WEEKLY,
            weekday_set={0, 2},
            start_date="2026-09-14",
        )
        second = await create_quest_definition(
            database,
            "Tidy room",
            weekly,
            [child.id, bo.id],
            [("morning", "08:00"), ("evening", "19:00")],
        )
        assert [d.id for d in await definitions.list_active()] == [
            first.definition.id,
            second.definition.id,
        ]
        await set_quest_definition_active(database, first.definition.id, False)
        result = await list_active_definitions(database)
        assert [bundle.definition.id for bundle in result] == [second.definition.id]
        assert isinstance(result[0], CreatedQuestDefinition)
        assert result[0].rule == weekly
        assert sorted(c.id for c in result[0].assignees) == sorted(
            [child.id, bo.id]
        )
        by_name = {w.window: w.due_time for w in result[0].windows}
        assert by_name == {"morning": "08:00", "evening": "19:00"}
        return result
    _with_db(tmp_path, "list-active.db")(_body)
 def test_list_definitions_for_child_returns_only_that_child(tmp_path) -> None:
    """Only the given child's definitions come back, deterministically.
    Definitions are created assigned to Ada (child), Bo, or both; the
    helper must return exactly the definitions assigned to Ada, excluding
    a Bo-only definition.  Inactive definitions are still assigned, so
    they too come back (the helper filters by child, not by activity).
    """
    async def _body(database, children, rules, definitions, child):
        bo = await children.create("Bo", NOW)
        ada_only = await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
        )
        both = await create_quest_definition(
            database,
            "Tidy room",
            ScheduleRule(
                rule_type=RuleType.WEEKLY,
                weekday_set={1},
                start_date="2026-09-14",
            ),
            [child.id, bo.id],
            ["evening"],
        )
        bo_only = await create_quest_definition(
            database, "Walk dog", _daily_rule(), [bo.id], ["afternoon"]
        )
        # The helper returns the given child's definitions in ascending
        # id order, consistent with list_active_definitions.
        result = await list_definitions_for_child(database, child.id)
        assert [bundle.definition.id for bundle in result] == [
            ada_only.definition.id,
            both.definition.id,
        ]
        assert result[0].rule == _daily_rule()
        assert [c.id for c in result[0].assignees] == [child.id]
        assert [w.window for w in result[0].windows] == ["morning"]
        bo_result = await list_definitions_for_child(database, bo.id)
        assert [bundle.definition.id for bundle in bo_result] == [
            both.definition.id,
            bo_only.definition.id,
        ]
        return result
    _with_db(tmp_path, "list-for-child.db")(_body)
@pytest.mark.parametrize("bad", [True, False, 1.5, "1", None])
 def test_list_definitions_for_child_rejects_non_int_child_id(tmp_path, bad) -> None:
    async def _body(database, children, rules, definitions, child):
        with pytest.raises(ValueError, match="child_id must be an integer"):
            await list_definitions_for_child(database, bad)
        return None
    _with_db(tmp_path, "list-for-child-bad-id.db")(_body)
 def test_list_definitions_firing_on_mixed_rules(tmp_path) -> None:
    """A mixed daily + weekly + monthly set fires on the right dates.
    Daily fires every day from its start; weekly fires on its weekdays;
    monthly fires on its day-of-month.  Deactivated definitions never
    fire, and the returned bundles carry the decoded rule.
    """
    async def _body(database, children, rules, definitions, child):
        daily = await create_quest_definition(
            database,
            "Daily chore",
            ScheduleRule(rule_type=RuleType.DAILY, start_date="2026-09-14"),
            [child.id],
            ["morning"],
        )
        weekly = await create_quest_definition(
            database,
            "Weekly chore",
            ScheduleRule(
                rule_type=RuleType.WEEKLY,
                weekday_set={0, 2},  # Monday, Wednesday
                start_date="2026-09-14",
            ),
            [child.id],
            ["evening"],
        )
        monthly = await create_quest_definition(
            database,
            "Monthly chore",
            ScheduleRule(
                rule_type=RuleType.MONTHLY_DAY,
                day_of_month=15,
                start_date="2026-09-14",
            ),
            [child.id],
            ["afternoon"],
        )
        # 2026-09-14 is a Monday (weekday 0): daily + weekly fire;
        # monthly (the 15th) does not.
        hits = await list_definitions_firing_on(database, "2026-09-14")
        assert [b.definition.id for b in hits] == [
            daily.definition.id,
            weekly.definition.id,
        ]
        # 2026-09-15 is a Tuesday (weekday 1, day 15): daily + monthly.
        hits = await list_definitions_firing_on(database, "2026-09-15")
        assert [b.definition.id for b in hits] == [
            daily.definition.id,
            monthly.definition.id,
        ]
        # 2026-09-16 is a Wednesday (weekday 2, day 16): daily + weekly.
        hits = await list_definitions_firing_on(database, "2026-09-16")
        assert [b.definition.id for b in hits] == [
            daily.definition.id,
            weekly.definition.id,
        ]
        # Deactivating a definition removes it from every future result.
        await set_quest_definition_active(database, weekly.definition.id, False)
        hits = await list_definitions_firing_on(database, "2026-09-14")
        assert [b.definition.id for b in hits] == [daily.definition.id]
        # The returned bundle carries the decoded rule, not the raw row.
        assert hits[0].rule == ScheduleRule(
            rule_type=RuleType.DAILY, start_date="2026-09-14"
        )
        return hits
    _with_db(tmp_path, "list-firing-on.db")(_body)
@pytest.mark.parametrize(
    "bad",
    ["2026-9-4", "2026-13-01", "2026-02-30", "not-a-date", None, 20260914],
 )
 def test_list_definitions_firing_on_rejects_malformed_date(tmp_path, bad) -> None:
    async def _body(database, children, rules, definitions, child):
        await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
        )
        with pytest.raises(ValueError, match="date must be"):
            await list_definitions_firing_on(database, bad)
        return None
    _with_db(tmp_path, "list-firing-on-bad-date.db")(_body)
 def test_list_query_snapshot_coherent_under_racing_edit(tmp_path) -> None:
    """A racing edit cannot mix states into a query helper's snapshot.
    The query helper pauses mid-snapshot (inside its locked transaction)
    while an edit that changes BOTH the rule and the windows is queued
    behind the connection lock.  Because the helper reads definitions,
    rules and windows in one locked transaction, its returned bundle is
    either the whole old state or the whole new state — never the old
    rule paired with the new windows (the exact interleaving the unlocked
    reads used to allow).  The pause hook holds
    ``list_windows`` mid-flight so the edit is deterministically queued
    against the helper's lock.
    """
    async def _body(database, children, rules, definitions, child):
        created = await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
        )
        weekly = ScheduleRule(
            rule_type=RuleType.WEEKLY,
            weekday_set={2},
            start_date="2026-09-14",
        )
        import custom_components.nestquest.dao_rules as dao_rules
        original_list = dao_rules.QuestDefinitionsDao.list_windows
        started = asyncio.Event()
        release = asyncio.Event()
        async def _pausing_list(self, definition_id):
            if not started.is_set():
                started.set()
                await release.wait()
            return await original_list(self, definition_id)
        dao_rules.QuestDefinitionsDao.list_windows = _pausing_list
        try:
            read_task = asyncio.ensure_future(
                list_definitions_firing_on(database, "2026-09-16")
            )
            await started.wait()
            edit_task = asyncio.ensure_future(
                edit_quest_definition(
                    database,
                    created.definition.id,
                    rule=weekly,
                    windows=["evening"],
                )
            )
            await asyncio.sleep(0)
            release.set()
            result, edited = await asyncio.gather(read_task, edit_task)
        finally:
            dao_rules.QuestDefinitionsDao.list_windows = original_list
        # The helper finished before the queued edit, so its snapshot is
        # the whole OLD state: the daily rule with its morning window.
        assert [b.definition.id for b in result] == [created.definition.id]
        assert result[0].rule == _daily_rule()
        assert [w.window for w in result[0].windows] == ["morning"]
        # The edit then reported the whole NEW state, not a mix either.
        assert edited.rule == weekly
        assert [w.window for w in edited.windows] == ["evening"]
        return result
    _with_db(tmp_path, "list-snapshot-concurrent.db")(_body)
 def test_list_definitions_for_child_snapshot_coherent_under_racing_unassign(
    tmp_path,
 ) -> None:
    """A racing unassign cannot strip the child from the child-scoped
    snapshot that ``list_definitions_for_child`` returns.
    The helper pauses mid-snapshot (inside its locked transaction) while
    an unassign of the very child it is listing is queued behind the
    connection lock.  Because the definition set and its assignees are
    read in one locked transaction, the returned bundle still shows the
    child assigned — the coherent pre-unassign snapshot — rather than the
    mixed state (definition returned "for child" but with the child
    already gone from its roster) that the unlocked reads used to allow.
    The pause hook holds ``list_assignees`` mid-flight so the unassign is
    deterministically queued against the helper's lock.
    """
    async def _body(database, children, rules, definitions, child):
        created = await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
        )
        import custom_components.nestquest.dao_rules as dao_rules
        original_list = dao_rules.QuestDefinitionsDao.list_assignees
        started = asyncio.Event()
        release = asyncio.Event()
        async def _pausing_list(self, definition_id):
            if not started.is_set():
                started.set()
                await release.wait()
            return await original_list(self, definition_id)
        dao_rules.QuestDefinitionsDao.list_assignees = _pausing_list
        try:
            read_task = asyncio.ensure_future(
                list_definitions_for_child(database, child.id)
            )
            await started.wait()
            unassign_task = asyncio.ensure_future(
                unassign_child(database, created.definition.id, child.id)
            )
            for _ in range(5):
                await asyncio.sleep(0)
            release.set()
            result, removed = await asyncio.gather(read_task, unassign_task)
        finally:
            dao_rules.QuestDefinitionsDao.list_assignees = original_list
        # The helper finished before the queued unassign, so its snapshot
        # is the whole OLD state: the child still assigned to the
        # definition it returned for that child.
        assert [b.definition.id for b in result] == [created.definition.id]
        assert [c.id for c in result[0].assignees] == [child.id]
        assert removed is True
        return result
    _with_db(tmp_path, "list-for-child-snapshot-concurrent.db")(_body)
 def test_list_active_definitions_snapshot_coherent_under_racing_edit(
    tmp_path,
 ) -> None:
    """A racing edit cannot mix states into ``list_active_definitions``.
    The helper pauses mid-snapshot (inside its locked transaction) while
    an edit that changes BOTH the rule and the windows is queued behind
    the connection lock.  Because definitions, rules and windows are read
    in one locked transaction, the returned bundle is the whole old state
    — the daily rule with its morning window — never the old rule paired
    with the new windows.  The pause hook holds ``list_windows``
    mid-flight so the edit is deterministically queued against the
    helper's lock.
    """
    async def _body(database, children, rules, definitions, child):
        created = await create_quest_definition(
            database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
        )
        weekly = ScheduleRule(
            rule_type=RuleType.WEEKLY,
            weekday_set={2},
            start_date="2026-09-14",
        )
        import custom_components.nestquest.dao_rules as dao_rules
        original_list = dao_rules.QuestDefinitionsDao.list_windows
        started = asyncio.Event()
        release = asyncio.Event()
        async def _pausing_list(self, definition_id):
            if not started.is_set():
                started.set()
                await release.wait()
            return await original_list(self, definition_id)
        dao_rules.QuestDefinitionsDao.list_windows = _pausing_list
        try:
            read_task = asyncio.ensure_future(list_active_definitions(database))
            await started.wait()
            edit_task = asyncio.ensure_future(
                edit_quest_definition(
                    database,
                    created.definition.id,
                    rule=weekly,
                    windows=["evening"],
                )
            )
            await asyncio.sleep(0)
            release.set()
            result, edited = await asyncio.gather(read_task, edit_task)
        finally:
            dao_rules.QuestDefinitionsDao.list_windows = original_list
        # The helper finished before the queued edit, so its snapshot is
        # the whole OLD state: the daily rule with its morning window.
        assert [b.definition.id for b in result] == [created.definition.id]
        assert result[0].rule == _daily_rule()
        assert [w.window for w in result[0].windows] == ["morning"]
        # The edit then reported the whole NEW state, not a mix either.
        assert edited.rule == weekly
        assert [w.window for w in edited.windows] == ["evening"]
        return result
    _with_db(tmp_path, "list-active-snapshot-concurrent.db")(_body)
 # ---------------------------------------------------------------------------
 # full-lifecycle integration: one definition through every operation
 # ---------------------------------------------------------------------------
 def test_full_lifecycle_preserves_completed_and_history(tmp_path) -> None:
    """End-to-end lifecycle preserves completed rows and append-only history.
    Each stage (create -> edit rule/windows -> assign a second child ->
    unassign the original child -> deactivate -> reactivate) now
    regenerates the definition's future OPEN instances (Feature 07
    wiring), but a pre-existing COMPLETED instance and its completion
    events survive every stage unchanged — the completed row keeps its
    id and snapshot columns, the completion-events table stays append-only.
    """
    async def _body(database, children, rules, definitions, child):
        created = await create_quest_definition(
            database,
            "Brush teeth",
            _daily_rule(),
            [child.id],
            [("morning", "07:00")],
        )
        definition_id = created.definition.id
        instances = QuestInstancesDao(database)
        events = CompletionEventsDao(database)
        instance = await instances.upsert(
            definition_id, child.id, _today_iso(), NOW, window="morning"
        )
        event = await events.append(
            instance.id,
            child.id,
            "completed",
            "user",
            NOW,
            True,
            actor_user_id="admin-1",
        )
        event_count = await database.fetch_one(
            "SELECT COUNT(*) FROM completion_events"
        )
        async def _assert_history_preserved():
            assert await instances.get_by_id(instance.id) == instance
            assert await events.list_by_instance(instance.id) == [event]
            assert await database.fetch_one(
                "SELECT COUNT(*) FROM completion_events"
            ) == event_count
        await _assert_history_preserved()
        # Edit rule and windows together; the definition's rule row is
        # rewritten in place and its window set replaced.
        edited = await edit_quest_definition(
            database,
            definition_id,
            rule=ScheduleRule(
                rule_type=RuleType.WEEKLY,
                weekday_set={1, 3},
                start_date="2026-09-14",
            ),
            windows=[("morning", "08:00"), ("evening", "19:30")],
        )
        assert edited.rule == ScheduleRule(
            rule_type=RuleType.WEEKLY,
            weekday_set={1, 3},
            start_date="2026-09-14",
        )
        by_name = {w.window: w.due_time for w in edited.windows}
        assert by_name == {"morning": "08:00", "evening": "19:30"}
        await _assert_history_preserved()
        # Assign a second child: multi-assignee, both present.
        bo = await children.create("Bo", NOW)
        roster = await assign_child(database, definition_id, bo.id)
        assert sorted(c.id for c in roster) == sorted([child.id, bo.id])
        await _assert_history_preserved()
        # Unassign the original child: only the link drops.
        assert await unassign_child(database, definition_id, child.id) is True
        assert [
            c.id for c in await definitions.list_assignees(definition_id)
        ] == [bo.id]
        await _assert_history_preserved()
        # Deactivate, then reactivate: the definition survives both.
        deactivated = await set_quest_definition_active(
            database, definition_id, False
        )
        assert deactivated.definition.is_active is False
        await _assert_history_preserved()
        reactivated = await set_quest_definition_active(
            database, definition_id, True
        )
        assert reactivated.definition.is_active is True
        await _assert_history_preserved()
        return reactivated
    _with_db(tmp_path, "full-lifecycle.db")(_body)
@pytest.mark.parametrize(
    "mode",
    ["edit", "assign", "unassign", "set_active"],
 )
 def test_wrappers_forward_horizon_days(tmp_path, mode) -> None:
    """The four change wrappers forward a non-default horizon_days.
    Each wrapper threads ``horizon_days`` into the regeneration it triggers;
    passing 5 here must bound the regenerated window to today..today+5 —
    proving the forwarding argument is actually honored, not dropped.
    """
    async def _body(database, children, rules, definitions, child):
        created = await create_quest_definition(
            database,
            "Chore",
            ScheduleRule(rule_type=RuleType.DAILY, start_date=_today_iso()),
            [child.id],
            ["morning"],
        )
        definition_id = created.definition.id
        instances = QuestInstancesDao(database)
        if mode == "edit":
            await edit_quest_definition(
                database,
                definition_id,
                windows=[("morning", "10:30")],
                horizon_days=5,
            )
            tracked = child
        elif mode == "assign":
            bo = await children.create("Bo", NOW)
            await assign_child(database, definition_id, bo.id, horizon_days=5)
            tracked = bo
        elif mode == "unassign":
            # The remaining assignee (``child``) must be regenerated over
            # the 5-day window after ``bo`` is removed.
            bo = await children.create("Bo", NOW)
            await assign_child(database, definition_id, bo.id)
            await unassign_child(
                database, definition_id, bo.id, horizon_days=5
            )
            tracked = child
        else:  # set_active
            await set_quest_definition_active(
                database, definition_id, True, horizon_days=5
            )
            tracked = child
        today = datetime.date.today()
        end = (today + datetime.timedelta(days=5)).isoformat()
        records = await instances.list_by_date_range(
            tracked.id, today.isoformat(), end
        )
        assert len(records) == 6
        beyond = (today + datetime.timedelta(days=6)).isoformat()
        beyond_end = (
            today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
        ).isoformat()
        assert await instances.list_by_date_range(
            tracked.id, beyond, beyond_end
        ) == []
        return None
    _with_db(tmp_path, f"wrapper-horizon-{mode}.db")(_body)
@@ -1,41 +0,0 @@
 """Tests for the NestQuest services.yaml declaration file."""
 from __future__ import annotations
 import re
 from pathlib import Path
 SERVICES_PATH = (
    Path(__file__).parent.parent
    / "custom_components"
    / "nestquest"
    / "services.yaml"
 )
 def test_services_yaml_exists() -> None:
    assert SERVICES_PATH.exists(), f"services.yaml missing at {SERVICES_PATH}"
 def test_services_yaml_declares_regenerate() -> None:
    text = SERVICES_PATH.read_text(encoding="utf-8")
    assert re.search(r"^regenerate:\s*$", text, re.MULTILINE), (
        "services.yaml must declare the 'regenerate' service"
    )
 def test_services_yaml_regenerate_has_description_and_no_fields() -> None:
    """The regenerate service is documented with a clear description and no
    required fields (there is no ``fields`` block under it)."""
    text = SERVICES_PATH.read_text(encoding="utf-8")
    match = re.search(r"^regenerate:\s*$", text, re.MULTILINE)
    assert match is not None
    section = text[match.end():]
    next_service = re.search(r"^(?![#\s])\w+:\s*$", section, re.MULTILINE)
    if next_service is not None:
        section = section[: next_service.start()]
    assert re.search(r"description:", section), (
        "regenerate must carry a description"
    )
    assert "fields:" not in section, (
        "regenerate declares no required fields"
    )
@@ -1,370 +0,0 @@
 """Timezone tests for the single HA-local date source in the generation path.
 These pin the done-condition that every "today" read in the generation path
 derives from ``hass.config.time_zone`` — not the host clock and not UTC —
 and that the rolling horizon ``[today, today + DEFAULT_HORIZON_DAYS]`` and the
 no-past guard resolve the correct local dates around midnight and across the
 daylight-saving transitions.
 """
 from __future__ import annotations
 import asyncio
 import datetime
 from types import SimpleNamespace
 from zoneinfo import ZoneInfo
 from custom_components.nestquest.const import DEFAULT_HORIZON_DAYS
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.dao_instances import QuestInstancesDao
 from custom_components.nestquest.db import NestQuestDatabase
 from custom_components.nestquest.migrations import apply_migrations
 from custom_components.nestquest.quest_definitions import (
    assign_child,
    create_quest_definition,
    edit_quest_definition,
 )
 from custom_components.nestquest.recurrence import RuleType, ScheduleRule
 NOW = "2026-09-14T12:00:00+00:00"
 NEW_YORK = "America/New_York"
 def _make_hass_mock():
    from unittest.mock import AsyncMock, MagicMock
    hass = MagicMock()
    hass.async_add_executor_job = AsyncMock(side_effect=(lambda fn, *a: fn(*a)))
    return hass
 async def _prepare(path):
    database = NestQuestDatabase(_make_hass_mock())
    await database.open(path)
    await apply_migrations(database)
    return database
 def _run(coro):
    return asyncio.new_event_loop().run_until_complete(coro)
 def _freeze_clock(
    monkeypatch, instant: datetime.datetime
 ) -> tuple[datetime.datetime, list]:
    """Freeze the integration's ``datetime`` clock to a fixed aware instant.
    Only ``custom_components.nestquest``'s ``datetime`` binding is patched, so
    the generation path's "today" reads this instant (localized to whatever
    time zone it asks for) while every other module and the test harness keep
    the real clock.  Returns ``(frozen, requested)`` where ``frozen`` is the
    instant normalized to UTC and ``requested`` is the list of ``tzinfo``
    objects the code under test passed to ``now`` — so a test can prove the
    generation path actually requested the configured HA time zone rather
    than silently reading UTC.
    """
    import custom_components.nestquest as nestquest
    frozen = instant.astimezone(datetime.timezone.utc)
    requested: list = []
    class _FrozenDatetime(datetime.datetime):
        @classmethod
        def now(cls, tz=None):
            requested.append(tz)
            if tz is None:
                return frozen.replace(tzinfo=None)
            return frozen.astimezone(tz)
    fake_module = SimpleNamespace(
        datetime=_FrozenDatetime,
        timedelta=datetime.timedelta,
        date=datetime.date,
    )
    monkeypatch.setattr(nestquest, "datetime", fake_module)
    return frozen, requested
 def _assert_requested_ha_timezone(requested, time_zone: str) -> None:
    """Assert ``now`` was called with (only) the configured HA time zone.
    This is what turns the DST tests into a real proof of the HA-local date
    source: if the generation path regressed to ``now(timezone.utc)``, its
    requested tz would be UTC and this fails.
    """
    assert requested, "the generation path never called now(tz)"
    assert all(tz == ZoneInfo(time_zone) for tz in requested)
 def _tz_hass(time_zone: str):
    """A minimal hass exposing only the ``config.time_zone`` the walk reads."""
    return SimpleNamespace(config=SimpleNamespace(time_zone=time_zone))
 async def _seed_daily(database, start_iso: str) -> int:
    """One always-present child + a daily definition starting ``start_iso``."""
    child = await ChildrenDao(database).create("Ada", NOW)
    await create_quest_definition(
        database,
        "Daily chore",
        ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
        [child.id],
        ["morning"],
    )
    return child.id
 def _local_date(instant_utc: datetime.datetime, time_zone: str) -> datetime.date:
    return instant_utc.astimezone(ZoneInfo(time_zone)).date()
 def _assert_contiguous_horizon(records, local_today: datetime.date) -> None:
    """The horizon is exactly today..today+horizon, no off-by-one, no gap."""
    expected = {
        (local_today + datetime.timedelta(days=offset)).isoformat()
        for offset in range(DEFAULT_HORIZON_DAYS + 1)
    }
    assert {r.due_date for r in records} == expected
    assert len(records) == DEFAULT_HORIZON_DAYS + 1
 def test_horizon_uses_newyork_local_date_after_local_midnight(
    tmp_path, monkeypatch
 ) -> None:
    """A run just after New York local midnight uses the local date.
    The frozen instant is 00:05 New York local time on 2026-03-10 (EDT, so
    04:05 UTC).  The horizon must start on 2026-03-10 — the local calendar
    date — not any host/UTC-derived value.
    """
    instant = datetime.datetime(
        2026, 3, 10, 0, 5, tzinfo=ZoneInfo(NEW_YORK)
    )
    local_today = instant.date()
    async def _body(database):
        hass = _tz_hass(NEW_YORK)
        _frozen, requested = _freeze_clock(monkeypatch, instant)
        import custom_components.nestquest as nestquest
        child_id = await _seed_daily(database, local_today.isoformat())
        await nestquest._run_horizon_materialization(hass, database)
        records = await QuestInstancesDao(database).list_by_date_range(
            child_id,
            local_today.isoformat(),
            (local_today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat(),
        )
        _assert_contiguous_horizon(records, local_today)
        _assert_requested_ha_timezone(requested, NEW_YORK)
        return len(records)
    async def _main():
        database = await _prepare(tmp_path / "tz-midnight.db")
        try:
            return await _body(database)
        finally:
            await database.close()
    assert _run(_main()) == DEFAULT_HORIZON_DAYS + 1
 def test_horizon_uses_local_date_not_utc_when_host_ahead(
    tmp_path, monkeypatch
 ) -> None:
    """The walk's "today" is HA-local, never the UTC/system calendar date.
    FROZEN at 2026-01-15 03:00 UTC: the UTC calendar date is 2026-01-15, but
    New York local is still 2026-01-14 22:00 EST.  The horizon must start on
    2026-01-14 (local), proving the UTC date did not win.
    """
    instant = datetime.datetime(2026, 1, 15, 3, 0, tzinfo=datetime.timezone.utc)
    local_today = _local_date(instant, NEW_YORK)
    assert local_today == datetime.date(2026, 1, 14)
    assert instant.date() == datetime.date(2026, 1, 15)
    async def _body(database):
        hass = _tz_hass(NEW_YORK)
        _frozen, requested = _freeze_clock(monkeypatch, instant)
        import custom_components.nestquest as nestquest
        child_id = await _seed_daily(database, local_today.isoformat())
        await nestquest._run_horizon_materialization(hass, database)
        records = await QuestInstancesDao(database).list_by_date_range(
            child_id,
            local_today.isoformat(),
            (local_today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat(),
        )
        _assert_contiguous_horizon(records, local_today)
        _assert_requested_ha_timezone(requested, NEW_YORK)
        return len(records)
    async def _main():
        database = await _prepare(tmp_path / "tz-host-ahead.db")
        try:
            return await _body(database)
        finally:
            await database.close()
    assert _run(_main()) == DEFAULT_HORIZON_DAYS + 1
 def test_horizon_resolves_spring_forward_day_without_off_by_one(
    tmp_path, monkeypatch
 ) -> None:
    """Across the 2026-03-08 spring-forward, today and the horizon stay local.
    Before the jump ("01:30 EST") and after it ("03:30 EDT") both resolve to
    2026-03-08 local — the lost hour must not skip or repeat a calendar day —
    and the full horizon remains 15 contiguous days.
    """
    zone = ZoneInfo(NEW_YORK)
    before = datetime.datetime(2026, 3, 8, 1, 30, tzinfo=zone)  # EST
    after = datetime.datetime(2026, 3, 8, 3, 30, tzinfo=zone)   # EDT
    assert before.date() == after.date() == datetime.date(2026, 3, 8)
    async def _body(database):
        hass = _tz_hass(NEW_YORK)
        import custom_components.nestquest as nestquest
        requested_batches: list[list] = []
        for instant in (before, after):
            _frozen, requested = _freeze_clock(monkeypatch, instant)
            requested_batches.append(requested)
            local_today = instant.date()
            child_id = await _seed_daily(database, local_today.isoformat())
            await nestquest._run_horizon_materialization(hass, database)
            records = await QuestInstancesDao(database).list_by_date_range(
                child_id,
                local_today.isoformat(),
                (local_today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat(),
            )
            _assert_contiguous_horizon(records, local_today)
        requested_all = [tz for batch in requested_batches for tz in batch]
        _assert_requested_ha_timezone(requested_all, NEW_YORK)
        return local_today
    async def _main():
        database = await _prepare(tmp_path / "tz-spring-forward.db")
        try:
            return await _body(database)
        finally:
            await database.close()
    assert _run(_main()) == datetime.date(2026, 3, 8)
 def test_horizon_resolves_fall_back_day_without_off_by_one(
    tmp_path, monkeypatch
 ) -> None:
    """Across the 2026-11-01 fall-back, today and the horizon stay local.
    The repeated 01:00-02:00 hour must not resolve to the wrong calendar
    day: the first 01:30 (``fold=0``, EDT) and the repeated 01:30
    (``fold=1``, EST) are distinct instants yet both resolve to 2026-11-01
    — and both, along with 03:30 EST after the jump, materialize the same
    15 contiguous-day horizon with no off-by-one.
    """
    zone = ZoneInfo(NEW_YORK)
    first = datetime.datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=0)  # EDT
    second = datetime.datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=1)  # EST
    after = datetime.datetime(2026, 11, 1, 3, 30, tzinfo=zone)  # EST
    assert first.date() == second.date() == after.date() == datetime.date(2026, 11, 1)
    assert first.utcoffset() != second.utcoffset()  # the two repeated-hour folds
    async def _body(database):
        hass = _tz_hass(NEW_YORK)
        import custom_components.nestquest as nestquest
        requested_batches: list[list] = []
        for instant in (first, second, after):
            _frozen, requested = _freeze_clock(monkeypatch, instant)
            requested_batches.append(requested)
            local_today = instant.date()
            child_id = await _seed_daily(database, local_today.isoformat())
            await nestquest._run_horizon_materialization(hass, database)
            records = await QuestInstancesDao(database).list_by_date_range(
                child_id,
                local_today.isoformat(),
                (local_today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat(),
            )
            _assert_contiguous_horizon(records, local_today)
        requested_all = [tz for batch in requested_batches for tz in batch]
        _assert_requested_ha_timezone(requested_all, NEW_YORK)
        return local_today
    async def _main():
        database = await _prepare(tmp_path / "tz-fall-back.db")
        try:
            return await _body(database)
        finally:
            await database.close()
    assert _run(_main()) == datetime.date(2026, 11, 1)
 def test_definition_business_regeneration_uses_pinned_today_not_host(
    tmp_path, monkeypatch
 ) -> None:
    """``edit_quest_definition``/``assign_child`` anchor regeneration on
    the caller-pinned HA-local ``today``, not the host clock.
    The host clock (the ``_today`` fallback) is pinned one day AHEAD of the
    HA-local ``today``; the guard would reject the local "today" as past
    (and the horizon would skip it) if it consulted the host clock.  Both
    business operations must regenerate against the pinned date and keep
    that first local day, proving the threaded ``today`` wins.
    """
    import custom_components.nestquest.dao_instances as dao_instances_module
    pinned = datetime.date(2026, 1, 14)
    host_today = datetime.date(2026, 1, 15)
    monkeypatch.setattr(dao_instances_module, "_today", lambda: host_today)
    async def _body(database):
        children = ChildrenDao(database)
        dao = QuestInstancesDao(database)
        horizon_end = pinned + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
        a = await children.create("Ada", NOW)
        created = await create_quest_definition(
            database,
            "Daily chore",
            ScheduleRule(rule_type=RuleType.DAILY, start_date=pinned.isoformat()),
            [a.id],
            [("morning", "09:00")],
        )
        definition_id = created.definition.id
        # edit anchors on pinned: the horizon starts at the local day the
        # host clock calls "past", so its presence proves pinned won.
        await edit_quest_definition(
            database,
            definition_id,
            windows=[("morning", "10:15")],
            today=pinned,
        )
        a_records = await dao.list_by_date_range(
            a.id, pinned.isoformat(), horizon_end.isoformat()
        )
        assert [r.due_date for r in a_records][0] == pinned.isoformat()
        assert {r.due_time for r in a_records} == {"10:15"}
        assert len(a_records) == DEFAULT_HORIZON_DAYS + 1
        # assign anchors on pinned too: the new child's regeneration keeps
        # the same pinned-local first day rather than skipping to the host day.
        b = await children.create("Bo", NOW)
        await assign_child(database, definition_id, b.id, today=pinned)
        b_records = await dao.list_by_date_range(
            b.id, pinned.isoformat(), horizon_end.isoformat()
        )
        assert [r.due_date for r in b_records][0] == pinned.isoformat()
        assert len(b_records) == DEFAULT_HORIZON_DAYS + 1
        return definition_id
    async def _main():
        database = await _prepare(tmp_path / "tz-definition-regen.db")
        try:
            return await _body(database)
        finally:
            await database.close()
    assert _run(_main()) is not None
Author	SHA1	Message	Date
overseer	dbbe044bef	test: seed pre-existing instance/history and add concurrency test (NQ-70-001, NQ-70-002)	2026-09-17 09:38:37 -04:00
overseer	6b17fb160f	Deactivate and reactivate a quest definition (Feature 06, task 5)	2026-09-17 09:31:45 -04:00