fix: async_remove service, HA-local today for no-past guard, setup cleanup (NQ-81-001..003)

2026-09-17 15:34:39 -04:00
parent 0127362ebf
commit 386f9dc8b6
6 changed files with 205 additions and 67 deletions
@@ -59,6 +59,34 @@ def _today() -> datetime.date:
    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.

@@ -178,6 +206,7 @@ class QuestInstancesDao:
        *,
        window: str,
        due_time: str | None = None,
+        today: datetime.date | None = None,
    ) -> QuestInstanceRecord:
        """Create the dated instance for the widened key idempotently.

@@ -196,6 +225,10 @@ 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
@@ -215,24 +248,20 @@ 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.
-        today = _today().isoformat()
-        if due_date < today:
-            raise ValueError(
-                f"instances are never generated in the past: due_date "
-                f"{due_date!r} is before today {today!r}"
-            )
+        # A caller-supplied ``today`` (HA-local) is used for BOTH
+        # checks and never re-read, since it is already the anchor the
+        # batch runs against.
+        today_date = _resolve_today(today)
+        _reject_past(due_date, today_date.isoformat())
        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.
-                today = _today().isoformat()
-                if due_date < today:
-                    raise ValueError(
-                        f"instances are never generated in the past: "
-                        f"due_date {due_date!r} is before today "
-                        f"{today!r}"
-                    )
+                # holds across midnight rollovers.  A pinned HA-local
+                # anchor is exempt from the re-read (see above).
+                if today is None:
+                    today_date = _today()
+                _reject_past(due_date, today_date.isoformat())
                definition = await self._database.fetch_one(
                    "SELECT 1 FROM quest_definitions WHERE id = ?",
                    (definition_id,),
@@ -298,6 +327,7 @@ class QuestInstancesDao:
        *,
        window: str,
        due_time: str | None = None,
+        today: datetime.date | None = None,
    ) -> QuestInstanceRecord | None:
        """Insert one dated instance iff its tuple is still materializable.

@@ -327,7 +357,8 @@ class QuestInstancesDao:
        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.  An
+        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
@@ -338,20 +369,13 @@ class QuestInstancesDao:
        _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 = _today().isoformat()
-        if due_date < today:
-            raise ValueError(
-                f"instances are never generated in the past: due_date "
-                f"{due_date!r} is before today {today!r}"
-            )
+        today_date = _resolve_today(today)
+        _reject_past(due_date, today_date.isoformat())
        async with _connection_lock(self._database):
            async with self._database.transaction():
-                today = _today().isoformat()
-                if due_date < today:
-                    raise ValueError(
-                        f"instances are never generated in the past: "
-                        f"due_date {due_date!r} is before today {today!r}"
-                    )
+                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 "
@@ -463,7 +487,7 @@ class QuestInstancesDao:
        return [_instance_from_row(row) for row in rows]

    async def delete_future_uncompleted(
-        self, definition_id: int, cutoff_date: str
+        self, definition_id: int, cutoff_date: str, *, today: datetime.date | None = None
    ) -> int:
        """Delete the definition's open instances at/after cutoff.

@@ -475,9 +499,11 @@ 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.  Any
-        instance with a completion event is never touched, regardless
-        of its date.  Returns the number deleted.
+        sweep (Feature 11) handles past-due instances instead.  ``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.
        """
        _validate_date(cutoff_date, "cutoff_date")
        async with _connection_lock(self._database):
@@ -487,8 +513,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 = _today().isoformat()
-                effective_cutoff = max(cutoff_date, today)
+                today_date = _resolve_today(today)
+                effective_cutoff = max(cutoff_date, today_date.isoformat())
                result = await self._database.execute(
                    "DELETE FROM quest_instances WHERE definition_id = ? "
                    "AND due_date >= ? AND NOT EXISTS ("
@@ -500,7 +526,7 @@ class QuestInstancesDao:
        return result.rowcount

    async def delete_future_uncompleted_for_child(
-        self, child_id: int, cutoff_date: str
+        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)``.
@@ -511,8 +537,10 @@ class QuestInstancesDao:
        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).  Any instance with a completion event is never touched,
-        regardless of its date.
+        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
@@ -530,8 +558,8 @@ class QuestInstancesDao:
                # 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 = _today().isoformat()
-                effective_cutoff = max(cutoff_date, today)
+                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 ("