feat: completion business layer wrapping append-only DAO

RELEASE_NOTES.md

@@ -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.

custom_components/nestquest/completion.py

@@ -4,14 +4,9 @@ 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.
+:meth:`~.dao_instances.CompletionEventsDao.append`.  Completing and
+un-completing an instance (no-op-if-already-done, derived state) arrive
+in later tasks; this module is the append wrapper only.
 
 Actor policy matches the schema CHECKs (D-008): ``actor_source`` is
 ``'user'`` or ``'panel'`` only — never ``'service'``.  ``'user'``
@@ -28,17 +23,13 @@ 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
 
@@ -67,153 +58,6 @@ def _stamp_occurred_at(now: datetime.datetime | None) -> str:
     )
 
 
-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):
@@ -319,177 +163,3 @@ async def append_event(
         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

custom_components/nestquest/manifest.json

@@ -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"
 }

pyproject.toml

@@ -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"

uv.lock

@@ -22,7 +22,7 @@ wheels = [
 
 [[package]]
 name = "nestquest"
-version = "0.5.0"
+version = "0.3.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]