fix: validate horizon_days before delete + wrapper forwarding tests (NQ-86-001, NQ-86-002)

test: prove configured horizon bounds generation (TEST-001)
feat: thread configured horizon_days through materialization + regeneration
2026-09-17 17:05:50 -04:00 · 2026-09-17 16:56:36 -04:00 · 2026-09-17 16:51:03 -04:00
8 changed files with 20 additions and 2097 deletions
@@ -1,87 +1,5 @@
 # NestQuest Release Notes
 ## Version 0.5.0 — 2026-09-18
 ### Scope
 Fifth release of NestQuest, promoting Features 06, 07, and 08 from `dev` onto 0.4.0 (quest model, children registry, presence engine):
 - **Feature 06 — quest definitions and assignment:** business layer `quest_definitions.py` over the multi-assignee / multi-window model (D-008). Create/edit/deactivate definitions; assign/unassign children; query helpers for materialization. `ScheduleRule` ⇄ `schedule_rules` storage mapping in the DAO layer.
 - **Feature 07 — instance materialization:** `materialize.py` fans out one instance per (definition, child, window, firing date) when the recurrence rule fires and the child is present. Idempotent on `(definition_id, child_id, due_date, window)`; skips completed instances; never generates past dates. HA-local `today` and configured `horizon_days` threaded end-to-end. Regeneration on definition/assignee/presence changes; daily rollover listener; startup backfill; `nestquest.regenerate` service.
 - **Feature 08 — completion and event log:** business layer `completion.py` wrapping the existing append-only `CompletionEventsDao`. `complete_instance` / `uncomplete_instance` (reversal event, original row untouched); state derived from the latest event; HA-local `was_on_time`; derived `missed` (never stored). Actor shapes `'user'` / `'panel'` with `actor_child_id` (D-008). Permission gating of un-complete is Feature 09.
 ### Requirements
 - Minimum Home Assistant version: **2024.6.0**.
 ### Breaking changes
 - None at the schema layer. Schema remains **version 6** (advanced in 0.4.0). This release adds application code only.
 ### Known Limitations
 - No permission decorator yet (Feature 09): `complete_instance` / `uncomplete_instance` are Python APIs, not gated HA services. The only HA service in this release is `nestquest.regenerate`.
 - No entity or event surface (Feature 10): no sensors, no `nestquest_quest_completed` bus events.
 - No panel or admin Lovelace cards (Features 12/13).
 - Un-complete is implemented but not admin-gated until Feature 09.
 - Single-instance only.
 ### Rollback
 Schema version is unchanged from 0.4.0 (still 6). A code downgrade to 0.4.0 does not require a database restore for schema compatibility, but **back up `nestquest.db` (plus `-wal`/`-shm`) before upgrading** — generated instances and completion events written by 0.5.0 remain in the file after downgrade; 0.4.0 will not generate or complete them.
 **HACS installs:**
 1. Downgrade via HACS (HACS > Integrations > NestQuest > Redownload > 0.4.0).
 2. Restart Home Assistant.
 **Manual installs:**
 1. Replace `custom_components/nestquest/` with the 0.4.0 tree.
 2. Restart Home Assistant.
 **Repository operators:** git-revert the 0.5.0 release merge on `main`.
 ## Version 0.4.0 — 2026-09-15
 ### Scope
 Fourth release of NestQuest, shipping three completed features on top of the data layer and recurrence engine:
 - **Feature 14 — quest domain model (BREAKING rename, D-007/D-008):** `task_definitions`/`task_instances` are now `quest_definitions`/`quest_instances` everywhere; definitions are multi-assignee (`quest_definition_assignees`, no single child column) and multi-window (`quest_definition_windows` — morning/afternoon/evening, clock ranges in `const.py`); the instance key widens to `(definition_id, child_id, due_date, window)` so twice-daily and shared quests materialise one instance per child per window per day; `completion_events` gains `actor_child_id` (the tapped panel profile; admin events stay NULL) with a second actor-pair CHECK. Schema version advances to **6**.
 - **Feature 03 — children registry & admin allowlist:** typed business layer for child profiles (create/edit with trimmed required names and duplicate-name warnings, whole-table reorder, deactivation as the only removal path — history is never touched); the admin allowlist with a fail-closed `is_admin` resolver (empty allowlist denies everyone; the last admin cannot be removed); automatic seeding on first setup (the config-flow user is persisted in entry data, with the options-flow list and HA owner accounts as fallbacks) so the owner is never locked out; the options flow gains a multi-select picker of existing Home Assistant users.
 - **Feature 05 — presence & custody engine:** a pure `PresenceSchedule`/`PresenceOverride` model with total validation and lossless round-trips; anchor-date cycle arithmetic (D-004 — never ISO week numbers or parity); `PresenceEngine.is_present` with the always-present default for schedule-free children; date overrides beat the repeating pattern; a `next_present_dates` preview for the admin schedule UI; a full-year regression guard walking 2020 (366 days, ISO week 53) and 2015 (365 days, ISO week 53) proving the rotation never inverts at a year boundary.
 ### Requirements
 - Minimum Home Assistant version: **2024.6.0**.
 ### Breaking changes
 - The database schema advances from version 1 to version 6. Upgrades are automatic and data-preserving (legacy `task_*` tables are renamed; the definitions table is rebuilt for multi-assignee; legacy instances pin to the morning window; panel events backfill `actor_child_id`). **Back up `nestquest.db` before upgrading** — see Rollback.
 - Dev installs from before 2026-09-15 migrate automatically on first start.
 ### Known Limitations
 - Still no entities, services, calendar platforms, or panel cards: nothing is user-visible in Home Assistant yet (Features 06-10 land the business layer, materialisation, permission gate, and entity surface).
 - No materialisation yet: instances are not generated from definitions + presence yet (Feature 07).
 - Single-instance only.
 ### Rollback
 **Back up `nestquest.db` (plus `-wal`/`-shm` sidecars) BEFORE upgrading.** This release migrates the database to schema version 6 with renamed tables; an older NestQuest build refuses a version-6 database ("newer than this integration understands") and cannot read renamed tables at all — a plain downgrade is NOT possible once the database has been migrated.
 **Rollback procedure (after a migrated database):**
 1. Stop Home Assistant.
 2. Restore the pre-upgrade `nestquest.db` backup (and sidecars) you made before upgrading.
 3. Downgrade the integration (HACS > Integrations > NestQuest > Redownload > 0.3.0) or replace `custom_components/nestquest/` manually.
 4. Restart Home Assistant.
 Without a backup, the only path is staying on 0.4.0 (recommended) or deleting the integration and its database to start fresh (Settings > Devices & Services > NestQuest > Delete, then remove `nestquest.db`).
 **Repository operators:** instead of uninstalling, git-revert the release merge on `main` and restore the pre-upgrade database.
 ## Version 0.3.0 — 2026-09-14
 ### Scope
@@ -208,4 +126,4 @@ v0.1.0 is the first release — there is no previous NestQuest version to downgr
 **Data:** the integration does not yet create its own database file, so there is no application data. However, Home Assistant persists the config entry and its selected options — removing the integration deletes that configuration, and the option values (`horizon_days`, `day_rollover_time`, `panel_idle_timeout`) will be lost on removal.
-**Repository operators:** instead of uninstalling, you may git-revert the release merge on `main`, which removes the integration files entirely. End users should use the uninstall path above.
+**Repository operators:** instead of uninstalling, you may git-revert the release merge on `main`, which removes the integration files entirely. End users should use the uninstall path above.
@@ -1,495 +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`` / ``missed``); there is
 no status column.  ``missed`` is derived for past-due open instances
 (``due_date`` before HA-local ``today``) and is never stored as an
 event_type.
 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,
    QuestInstanceRecord,
    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
    )
 def _completion_moment(
    now: datetime.datetime | None,
    today: datetime.date | None,
 ) -> tuple[datetime.date, datetime.time | None]:
    """Return the HA-local completion date and optional wall-clock time.
    ``today`` is the HA-local calendar date when threaded (Feature 07
    style).  ``now`` is a timezone-aware HA-local datetime; its wall
    clock is used as-is and is never converted to UTC.  When ``today``
    is omitted the date comes from ``now``.  When both are omitted the
    host calendar date is the Feature 07 fallback — never the UTC
    clock.  Time-of-day is None unless ``now`` is supplied; comparing
    against ``due_time`` requires ``now``.
    """
    if now is not None:
        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")
    if today is not None:
        completion_date = today
    elif now is not None:
        completion_date = now.date()
    else:
        completion_date = datetime.date.today()
    if now is None:
        return completion_date, None
    return completion_date, now.time()
 def _resolve_today(today: datetime.date | None) -> datetime.date:
    """Return the threaded HA-local date, or the host calendar date."""
    if today is None:
        return datetime.date.today()
    return today
 def _derived_state(
    instance: QuestInstanceRecord,
    latest: CompletionEventRecord | None,
    today: datetime.date,
 ) -> str:
    """Return ``open``, ``done``, or ``missed`` from event plus due date.
    A latest completed event is ``done`` even when past due.  No events
    or a latest uncompleted event is ``open``, or ``missed`` when
    ``due_date`` is before ``today``.  ``missed`` is never an event_type.
    """
    if latest is None or latest.event_type == EVENT_UNCOMPLETED:
        due_date = datetime.date.fromisoformat(instance.due_date)
        if due_date < today:
            return "missed"
        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}"
    )
 def _was_on_time(
    instance: QuestInstanceRecord,
    now: datetime.datetime | None,
    today: datetime.date | None,
 ) -> bool:
    """Return whether the completion moment is on time for ``instance``.
    On ``due_date`` before ``due_time`` is on time; on ``due_date``
    after ``due_time``, or any later date, is late.  With no
    ``due_time``, on time if the completion date equals ``due_date``
    (or is earlier); late if after ``due_date``.  Same-day
    ``due_time`` comparison requires ``now``; UTC time-of-day is never
    substituted.
    """
    completion_date, completion_time = _completion_moment(now, today)
    due_date = datetime.date.fromisoformat(instance.due_date)
    if completion_date < due_date:
        return True
    if completion_date > due_date:
        return False
    if instance.due_time is None:
        return True
    if completion_time is None:
        raise ValueError("now is required to compare due_time")
    due_time = datetime.datetime.strptime(instance.due_time, "%H:%M").time()
    return completion_time <= due_time
 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,
    *,
    today: datetime.date | None = None,
 ) -> str:
    """Return ``open``, ``done``, or ``missed`` from the latest event.
    No events, or a latest event of uncompleted, is ``open`` unless
    ``due_date`` is before ``today`` (HA-local, threaded), in which
    case it is ``missed``.  A latest event of completed is ``done``
    even when past due.  ``missed`` is never stored as an event_type.
    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")
    today_date = _resolve_today(today)
    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
        )
    return _derived_state(instance, latest, today_date)
 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 computed from the HA-local completion moment
    (threaded ``now`` / ``today``) against the instance ``due_date``
    and optional ``due_time``.  ``now`` is the timezone-aware HA-local
    datetime; its wall clock is never converted to UTC.  Same-day
    ``due_time`` comparison requires ``now``.
    """
    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=_was_on_time(instance, now, today),
            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,
    today: datetime.date | None = None,
 ) -> str:
    """Append an uncompleted event unless the instance is already open.
    Returns the derived state ``open``, or ``missed`` when the instance
    is past due (``due_date`` before HA-local ``today``).  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
    )
    today_date = _resolve_today(today)
    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 _derived_state(instance, latest, today_date)
        if latest.event_type != EVENT_COMPLETED:
            raise ValueError(
                f"event_type must be '{EVENT_COMPLETED}' or "
                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
            )
        latest = 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 _derived_state(instance, latest, today_date)
 async def list_missed_for_child(
    database: NestQuestDatabase,
    child_id: int,
    range_start: str,
    range_end: str,
    *,
    today: datetime.date | None = None,
 ) -> list[QuestInstanceRecord]:
    """Return the child's missed instances due in the closed date range.
    Missed means the latest event state is open and ``due_date`` is
    before ``today`` (HA-local, threaded).  Uses
    :meth:`QuestInstancesDao.list_by_date_range` plus derived state.
    Never appends a missed event.  Instances and latest events are
    read inside the connection lock so the list is one snapshot.
    """
    child_id = _validate_int_id(child_id, "child_id")
    today_date = _resolve_today(today)
    async with _connection_lock(database):
        instances = await QuestInstancesDao(database).list_by_date_range(
            child_id, range_start, range_end
        )
        events = CompletionEventsDao(database)
        missed: list[QuestInstanceRecord] = []
        for instance in instances:
            latest = await events.get_latest_for_instance(instance.id)
            if _derived_state(instance, latest, today_date) == "missed":
                missed.append(instance)
    return missed
@@ -344,20 +344,14 @@ class QuestInstancesDao:
        - 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);
+          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
+        The live checks above ONLY decide whether the tuple is still
-        method previously left open: it re-validated every OTHER
+        valid; they never read the window's ``due_time``.  The instance is
-        precondition but then wrote the snapshot's ``due_time``
+        written with the caller-supplied ``due_time`` — the value snapshotted
-        unconditionally, so a stale materialization could clobber a
+        from the coherent input read — so a window-time edit landing
-        newer, concurrently-regenerated due_time.
+        mid-walk cannot leak a newer time into a batch that was already
        snapshotted against older rule/presence/assignment decisions.
        Returns the stored instance, or ``None`` when a precondition
        failed — the tuple no longer materializable, which the walk SKIPS
@@ -390,9 +384,8 @@ class QuestInstancesDao:
                    "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 d.is_active = 1 AND c.is_active = 1 LIMIT 1",
-                    "AND w.due_time IS ? LIMIT 1",
+                    (definition_id, child_id, window),
                    (definition_id, child_id, window, due_time),
                )
                if still_valid is None:
                    # A config change invalidated the tuple since the
@@ -10,5 +10,5 @@
  "iot_class": "local_polling",
  "issue_tracker": "https://github.com/talon2king/NestQuest/issues",
  "requirements": [],
-  "version": "0.5.0"
+  "version": "0.3.0"
 }
@@ -1,6 +1,6 @@
 [project]
 name = "nestquest"
-version = "0.5.0"
+version = "0.3.0"
 description = "NestQuest Home Assistant Integration"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -545,7 +545,7 @@ def test_materialize_uses_single_presence_snapshot_mid_walk(tmp_path) -> None:
    _with_db(tmp_path, "materialize-presence-snapshot.db")(_body)
-def test_materialize_skips_stale_due_time_mid_walk(tmp_path) -> None:
+def test_materialize_stores_snapshot_due_time_not_live(tmp_path) -> None:
    async def _body(database):
        children = ChildrenDao(database)
        child = await children.create("Ada", NOW)
@@ -566,64 +566,21 @@ def test_materialize_skips_stale_due_time_mid_walk(tmp_path) -> None:
            )
        # The window's due_time is edited to 10:15 between the input
-        # snapshot and the insert.  The walk's snapshotted 09:00 no
+        # snapshot and the insert.  The walk must store the SNAPSHOT's
-        # longer matches the live 10:15, so the tuple is SKIPPED rather
+        # 09:00, not the live 10:15 — the batch is governed entirely by
-        # than writing a due_time that has already been superseded.
+        # the coherent snapshot it read.
        count = await _materialize_with_change(
            database, start_iso, end_iso, _edit_due_time
        )
-        assert count == 0
+        assert count == 3
        assert await QuestInstancesDao(database).list_by_date_range(
            child.id, start_iso, end_iso
        ) == []
        return count
    _with_db(tmp_path, "materialize-stale-due-time.db")(_body)
 def test_materialize_does_not_overwrite_regenerated_due_time(tmp_path) -> None:
    async def _body(database):
        children = ChildrenDao(database)
        child = await children.create("Ada", NOW)
        today = datetime.date.today()
        start_iso = today.isoformat()
        end_iso = (today + datetime.timedelta(days=2)).isoformat()
        created = await create_quest_definition(
            database,
            "Daily chore",
            ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
            [child.id],
            [("morning", "09:00")],
        )
        async def _edit_and_regenerate():
            # A window-time edit + regeneration land after the stale walk
            # read its input snapshot: the window moves to 10:15 and the
            # regeneration upserts the newer due_time across the horizon.
            await QuestDefinitionsDao(database).upsert_window(
                created.definition.id, "morning", due_time="10:15"
            )
            await regenerate_for_definition(database, created.definition.id)
        # The stale walk (snapshot due_time 09:00) then resumes.  It must
        # SKIP these tuples — its snapshotted 09:00 no longer matches the
        # live 10:15 — so the regeneration's newer due_time survives and
        # is NOT overwritten by the stale value.
        count = await _materialize_with_change(
            database, start_iso, end_iso, _edit_and_regenerate
        )
        assert count == 0
        records = await QuestInstancesDao(database).list_by_date_range(
            child.id, start_iso, end_iso
        )
        assert len(records) == 3
-        assert {r.due_time for r in records} == {"10:15"}
+        assert {r.due_time for r in records} == {"09:00"}
        return records
-    _with_db(tmp_path, "materialize-regenerated-due-time.db")(_body)
+    _with_db(tmp_path, "materialize-snapshot-due-time.db")(_body)
 def test_materialize_honours_overrides(tmp_path) -> None:
@@ -22,7 +22,7 @@ wheels = [
 [[package]]
 name = "nestquest"
-version = "0.5.0"
+version = "0.3.0"
 source = { virtual = "." }
 [package.dev-dependencies]
Author	SHA1	Message	Date
overseer	b274741b0c	fix: validate horizon_days before delete + wrapper forwarding tests (NQ-86-001, NQ-86-002)	2026-09-17 17:05:50 -04:00
overseer	8ab8260b33	test: prove configured horizon bounds generation (TEST-001)	2026-09-17 16:56:36 -04:00
overseer	0900a29220	feat: thread configured horizon_days through materialization + regeneration	2026-09-17 16:51:03 -04:00