Carry completion timing under the lock; shut down before close

The completed event's was_on_time travels on the CompletionResult
(decided with the write) instead of re-reading latest state a racing
reversal could replace; unload clears coordinator listeners before
the database close.

README.md

@@ -38,6 +38,35 @@ After installation and restart:
 2. Click **Add Integration** and search for **NestQuest**.
 3. Follow the on-screen configuration flow.
 
+## Events
+
+NestQuest fires Home Assistant bus events so automations can react to a
+child's progress. Each payload carries `child_id`, `child_name`,
+`instance_id`, `quest_title`, the instance's `window`, `due_date`,
+`due_time`, and `occurred_at` (a strict UTC ISO-8601 timestamp).
+
+| Event | Fires when | Extra payload fields |
+|---|---|---|
+| `nestquest_quest_completed` | a quest is completed (an actual completion, never a re-complete no-op) | `was_on_time` (bool) |
+| `nestquest_quest_uncompleted` | an admin reverses a completion | — |
+| `nestquest_child_day_complete` | a completion clears the child's whole day (quests were owed and none remain; a zero-quest day never fires it) | `quests_due`, `quests_completed` |
+| `nestquest_quest_missed` | the nightly sweep marks a still-open past-due quest missed (integrated in a later release) | — |
+
+Example automation trigger:
+
+```yaml
+triggers:
+  - trigger: event
+    event_type: nestquest_child_day_complete
+conditions:
+  - condition: template
+    value_template: "{{ trigger.payload.child_name == 'Declan' }}"
+actions:
+  - action: notify.mobile_app_declans_phone
+    data:
+      message: "Every quest cleared — legendary!"
+```
+
 ## Developer Setup and Testing
 
 This project uses [`uv`](https://github.com/astral-sh/uv) for fast Python package and dependency management.

custom_components/nestquest/__init__.py

@@ -615,16 +615,19 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
                     if unload_error is None:
                         unload_error = err
         finally:
-            database = getattr(runtime_data, "database", None)
-            if database is not None:
-                await database.close()
-            # Tear the shared coordinator down after the DB close: no
-            # listener may outlive the connection it reads.
+            # The coordinator's entity listeners must stop BEFORE the
+            # database closes: a scheduled refresh starting during the
+            # close await would touch a cleared connection.  (The
+            # platform unload above already removed the entities; this
+            # clears the coordinator's own remaining listeners.)
             coordinator = getattr(runtime_data, "coordinator", None)
             if coordinator is not None:
                 shutdown = getattr(coordinator, "async_shutdown", None)
                 if shutdown is not None:
                     await shutdown()
+            database = getattr(runtime_data, "database", None)
+            if database is not None:
+                await database.close()
     # Domain-global services are torn down only once the FINAL entry
     # unloads (``hass.data[DOMAIN]`` is now empty), never when a sibling
     # entry is still loaded.

custom_components/nestquest/completion.py

@@ -366,6 +366,36 @@ async def instance_state(
     return _derived_state(instance, latest, today_date)
 
 
+class CompletionResult(str):
+    """The derived instance state, carrying the append verdict.
+
+    A ``str`` subclass so every existing ``result == "done"`` contract
+    keeps working; ``appended`` reports whether THIS call actually
+    appended an event (decided under the same lock as the append), so
+    a caller — the Feature 09 service path firing bus events —
+    announces a transition exactly once even under a concurrent
+    duplicate call where the loser's write is a no-op.  A completion
+    also carries the ``was_on_time`` verdict computed under that same
+    lock, so the event payload never re-reads mutable latest state a
+    racing reversal could have replaced.
+    """
+
+    appended: bool
+    was_on_time: bool | None
+
+    def __new__(
+        cls,
+        state: str,
+        *,
+        appended: bool,
+        was_on_time: bool | None = None,
+    ) -> "CompletionResult":
+        obj = super().__new__(cls, state)
+        obj.appended = appended
+        obj.was_on_time = was_on_time
+        return obj
+
+
 async def complete_instance(
     database: NestQuestDatabase,
     instance_id: int,
@@ -375,14 +405,14 @@ async def complete_instance(
     actor_child_id: int | None = None,
     now: datetime.datetime | None = None,
     today: datetime.date | None = None,
-) -> str:
+) -> CompletionResult:
     """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.
+    Returns the derived state ``done``; ``appended`` reports whether
+    THIS call appended (False on an already-done no-op).  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``
@@ -404,12 +434,16 @@ async def complete_instance(
             instance_id
         )
         if latest is not None and latest.event_type == EVENT_COMPLETED:
-            return "done"
+            return CompletionResult("done", appended=False)
         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}"
             )
+        # Computed under the completion lock and carried on the result:
+        # the bus event must report THIS completion's timing, never a
+        # re-read of the latest event a racing reversal could replace.
+        on_time = _was_on_time(instance, now, today)
         await append_event(
             database,
             instance.id,
@@ -418,10 +452,10 @@ async def complete_instance(
             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),
+            was_on_time=on_time,
             now=now,
         )
-    return "done"
+    return CompletionResult("done", appended=True, was_on_time=on_time)
 
 
 async def uncomplete_instance(
@@ -433,16 +467,16 @@ async def uncomplete_instance(
     actor_child_id: int | None = None,
     now: datetime.datetime | None = None,
     today: datetime.date | None = None,
-) -> str:
+) -> CompletionResult:
     """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.
+    is past due (``due_date`` before HA-local ``today``); ``appended``
+    reports whether THIS call appended (False on an already-open
+    no-op).  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(
@@ -459,7 +493,10 @@ async def uncomplete_instance(
             instance_id
         )
         if latest is None or latest.event_type == EVENT_UNCOMPLETED:
-            return _derived_state(instance, latest, today_date)
+            return CompletionResult(
+                _derived_state(instance, latest, today_date),
+                appended=False,
+            )
         if latest.event_type != EVENT_COMPLETED:
             raise ValueError(
                 f"event_type must be '{EVENT_COMPLETED}' or "
@@ -476,7 +513,9 @@ async def uncomplete_instance(
             was_on_time=None,
             now=now,
         )
-    return _derived_state(instance, latest, today_date)
+    return CompletionResult(
+        _derived_state(instance, latest, today_date), appended=True
+    )
 
 
 async def list_missed_for_child(

custom_components/nestquest/const.py

@@ -11,6 +11,15 @@ LOGGER = logging.getLogger(LOGGER_NAME)
 # sensors and binary sensors.
 PLATFORMS: list[str] = ["sensor", "binary_sensor"]
 
+# Home Assistant bus events (design/ENTITIES-AND-SERVICES.md §3).  The
+# panel and admin cards listen for these; Feature 10 fires completed,
+# uncompleted, and child_day_complete from the service paths, and
+# Feature 11's nightly sweep fires quest_missed.
+EVENT_QUEST_COMPLETED = "nestquest_quest_completed"
+EVENT_QUEST_UNCOMPLETED = "nestquest_quest_uncompleted"
+EVENT_QUEST_MISSED = "nestquest_quest_missed"
+EVENT_CHILD_DAY_COMPLETE = "nestquest_child_day_complete"
+
 #: Canonical domain-global service names (design/ENTITIES-AND-SERVICES.md §2
 #: plus the existing Feature 07 regenerate service).
 SERVICE_COMPLETE_QUEST = "complete_quest"

custom_components/nestquest/coordinator.py

@@ -25,6 +25,7 @@ the admin header degrades to a harmless zero instead of guessing.
 """
 from __future__ import annotations
 
+import asyncio
 import datetime
 from dataclasses import dataclass
 from zoneinfo import ZoneInfo
@@ -97,7 +98,16 @@ class NestQuestSnapshot:
 
 
 class NestQuestCoordinator(DataUpdateCoordinator):
-    """Shared refresh cycle for every NestQuest entity."""
+    """Shared refresh cycle for every NestQuest entity.
+
+    Forced refreshes (the service paths pushing an immediate update
+    after a completion) are SERIALIZED per entry: overlapping
+    complete/uncomplete calls must not interleave their snapshot
+    passes, or an older pass could publish a stale snapshot AFTER a
+    newer one and leave entities wrong until the next poll.  Real
+    HA's coordinator already serializes internally; the lock keeps
+    the same guarantee on the stand-in and costs nothing upstream.
+    """
 
     def __init__(
         self,
@@ -122,6 +132,14 @@ class NestQuestCoordinator(DataUpdateCoordinator):
         )
         self.entry_id = entry_id
         self.database = database
+        self._refresh_lock = asyncio.Lock()
+
+    async def async_refresh(self) -> None:
+        """One refresh at a time; a queued refresh runs AFTER the
+        in-flight one publishes, so the last snapshot always reflects
+        the latest mutation."""
+        async with self._refresh_lock:
+            await super().async_refresh()
 
     def _local_now(self) -> datetime.datetime:
         time_zone = ZoneInfo(self.hass.config.time_zone)

custom_components/nestquest/events.py

@@ -0,0 +1,130 @@
+"""HA bus events fired by the NestQuest service paths (Feature 10).
+
+The four documented events (design/ENTITIES-AND-SERVICES.md §3, names
+in :mod:`~.const`): ``nestquest_quest_completed`` and
+``nestquest_quest_uncompleted`` fire from the completion service
+handlers on an actual transition (a no-op re-complete or re-uncomplete
+fires nothing), and ``nestquest_child_day_complete`` fires when a
+completion clears the child's whole day (quests were owed and none
+remain — a zero-quest day can never fire it, matching the all-done
+binary sensor's rule).  ``nestquest_quest_missed`` is the documented
+contract Feature 11's nightly sweep fires; nothing here fires it.
+
+Payload policy: one dict carrying ``child_id``, ``child_name``,
+``instance_id``, ``quest_title``, the instance's ``window``/
+``due_date``/``due_time`` so automation authors can filter without a
+database lookup, and ``occurred_at`` — the event's own strict UTC
+ISO-8601 timestamp.  Completion payloads additionally carry
+``was_on_time``.  No other personal data: names and titles are the
+household's own records, and nothing beyond them leaks.
+"""
+from __future__ import annotations
+
+import datetime
+from zoneinfo import ZoneInfo
+
+from .completion import derive_state
+from .const import (
+    EVENT_CHILD_DAY_COMPLETE,
+    EVENT_QUEST_COMPLETED,
+    EVENT_QUEST_UNCOMPLETED,
+)
+from .dao_children import ChildrenDao
+from .dao_instances import CompletionEventsDao, QuestInstancesDao
+from .dao_rules import QuestDefinitionsDao
+from .db import NestQuestDatabase
+
+#: Strict UTC ISO-8601 timestamp (the DAO layers' policy): one shape,
+#: explicit offset, second precision.
+_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
+
+
+def _now_stamp() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime(
+        _UTC_TIMESTAMP_FORMAT
+    )
+
+
+async def _instance_payload(
+    database: NestQuestDatabase, instance_id: int, now_stamp: str
+) -> dict:
+    """Build the shared event payload for one quest instance."""
+    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"
+        )
+    child = await ChildrenDao(database).get(instance.child_id)
+    definition = await QuestDefinitionsDao(database).get(
+        instance.definition_id
+    )
+    return {
+        "child_id": instance.child_id,
+        "child_name": child.display_name if child else None,
+        "instance_id": instance.id,
+        "quest_title": definition.title if definition else None,
+        "window": instance.window,
+        "due_date": instance.due_date,
+        "due_time": instance.due_time,
+        "occurred_at": now_stamp,
+    }
+
+
+async def fire_quest_completed(
+    hass,
+    database: NestQuestDatabase,
+    instance_id: int,
+    *,
+    was_on_time: bool | None,
+) -> None:
+    """Fire ``nestquest_quest_completed`` and, when the completion
+    cleared the child's whole day, ``nestquest_child_day_complete``.
+
+    Called by the complete_quest service handler AFTER an actual
+    completion transition, with the completion's ``was_on_time`` —
+    computed under the completion lock and carried on the result — so
+    the payload never re-reads mutable latest state a racing reversal
+    could have replaced.  A no-op re-complete never reaches here.
+    """
+    now_stamp = _now_stamp()
+    payload = await _instance_payload(database, instance_id, now_stamp)
+    payload["was_on_time"] = was_on_time
+    hass.bus.async_fire(EVENT_QUEST_COMPLETED, payload)
+
+    # Day-complete: quests were owed today and none remain (the same
+    # rule as the all-done binary sensor; a zero-quest day never fires).
+    # Only a completion of TODAY'S instance evaluates it: completing a
+    # back-dated or future instance must not announce a cleared day.
+    today = datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
+    if payload["due_date"] != today.isoformat():
+        return
+    instances = await QuestInstancesDao(database).list_by_date_range(
+        payload["child_id"], today.isoformat(), today.isoformat()
+    )
+    events = CompletionEventsDao(database)
+    remaining = 0
+    for instance in instances:
+        latest_for_instance = await events.get_latest_for_instance(
+            instance.id
+        )
+        if derive_state(instance, latest_for_instance, today) != "done":
+            remaining += 1
+    if instances and remaining == 0:
+        hass.bus.async_fire(
+            EVENT_CHILD_DAY_COMPLETE,
+            {
+                "child_id": payload["child_id"],
+                "child_name": payload["child_name"],
+                "quests_due": len(instances),
+                "quests_completed": len(instances),
+                "occurred_at": now_stamp,
+            },
+        )
+
+
+async def fire_quest_uncompleted(
+    hass, database: NestQuestDatabase, instance_id: int
+) -> None:
+    """Fire ``nestquest_quest_uncompleted`` for an actual reversal."""
+    payload = await _instance_payload(database, instance_id, _now_stamp())
+    hass.bus.async_fire(EVENT_QUEST_UNCOMPLETED, payload)

custom_components/nestquest/services.py

@@ -42,6 +42,7 @@ from .const import (
     SERVICE_UPDATE_QUEST_DEFINITION,
 )
 from .dao_presence import PresenceOverridesDao, PresenceSchedulesDao
+from .events import fire_quest_completed, fire_quest_uncompleted
 from .materialize import regenerate_for_child
 from .permissions import permission_gate
 from .presence import PresenceSchedule
@@ -241,6 +242,19 @@ def _require_runtime(hass: HomeAssistant, find_runtime: FindRuntime):
     return runtime
 
 
+async def _refresh_entities(runtime: Any) -> None:
+    """Force an immediate coordinator refresh after a service mutation.
+
+    Only the SERVICE paths call this — the scheduled materialize and
+    rollover internals are direct function calls and never widen this
+    gate — so entities reflect a completion the moment the service
+    call returns instead of waiting for the poll interval.
+    """
+    coordinator = getattr(runtime, "coordinator", None)
+    if coordinator is not None:
+        await coordinator.async_refresh()
+
+
 def _generation_kwargs(hass: HomeAssistant, runtime: Any) -> dict[str, Any]:
     time_zone = ZoneInfo(hass.config.time_zone)
     today = datetime.datetime.now(time_zone).date()
@@ -292,12 +306,24 @@ def _complete_quest(
     hass: HomeAssistant, find_runtime: FindRuntime
 ) -> ServiceHandler:
     async def _handler(call: Any) -> None:
-        database = _require_runtime(hass, find_runtime).database
-        await completion_layer.complete_instance(
-            database,
-            call.data["instance_id"],
+        runtime = _require_runtime(hass, find_runtime)
+        instance_id = call.data["instance_id"]
+        # ``appended`` is decided under the same lock as the write, so
+        # a concurrent duplicate call (a double tap) can not produce a
+        # second transition event: the loser appends nothing.
+        result = await completion_layer.complete_instance(
+            runtime.database,
+            instance_id,
             **_actor_kwargs(call),
         )
+        if result.appended:
+            await fire_quest_completed(
+                hass,
+                runtime.database,
+                instance_id,
+                was_on_time=result.was_on_time,
+            )
+            await _refresh_entities(runtime)
 
     return _with_errors(_handler)
 
@@ -306,12 +332,18 @@ def _uncomplete_quest(
     hass: HomeAssistant, find_runtime: FindRuntime
 ) -> ServiceHandler:
     async def _handler(call: Any) -> None:
-        database = _require_runtime(hass, find_runtime).database
-        await completion_layer.uncomplete_instance(
-            database,
-            call.data["instance_id"],
+        runtime = _require_runtime(hass, find_runtime)
+        instance_id = call.data["instance_id"]
+        result = await completion_layer.uncomplete_instance(
+            runtime.database,
+            instance_id,
             **_actor_kwargs(call),
         )
+        if result.appended:
+            await fire_quest_uncompleted(
+                hass, runtime.database, instance_id
+            )
+            await _refresh_entities(runtime)
 
     return _with_errors(_handler)
 

tests/conftest.py

@@ -549,6 +549,31 @@ def _async_track_time_change(hass, action, hour=None, minute=None, second=None):
 _ha_mock("homeassistant.helpers.event").async_track_time_change = _async_track_time_change
 
 
+class EventBus:
+    """Models HA's ``hass.bus`` event bus.
+
+    ``async_fire`` is SYNCHRONOUS (matching real HA) and records
+    ``(event_type, payload)`` pairs in order so tests can assert
+    exactly which events fired with which payloads; there is no
+    listener dispatch (entities poll the coordinator, and the cards
+    are not part of this harness).
+    """
+
+    def __init__(self):
+        self.events: list[tuple[str, dict]] = []
+
+    def async_fire(self, event_type: str, payload=None):
+        self.events.append((event_type, dict(payload or {})))
+
+    def fired(self, event_type: str) -> list[dict]:
+        """Return every payload fired for ``event_type``, in order."""
+        return [
+            payload
+            for fired_type, payload in self.events
+            if fired_type == event_type
+        ]
+
+
 class ServiceRegistry:
     """Models HA's ``hass.services`` service registry.
 
@@ -671,6 +696,7 @@ def make_hass() -> tuple:
     registry = ListenerRegistry(hass)
     hass.time_change = TimeChangeRegistry(hass)
     hass.services = ServiceRegistry(hass)
+    hass.bus = EventBus()
     # A valid IANA time zone (the day-rollover listener reads it to
     # compute "today" in HA local time).
     hass.config.time_zone = "UTC"
@@ -678,28 +704,40 @@ def make_hass() -> tuple:
     # The minimal entity registry: entities self-register through
     # Entity.async_write_ha_state keyed by unique_id, storing the live
     # object; tests enumerate created entities and read their state
-    # directly.
+    # directly.  entities_by_entry mirrors HA's per-entry platform
+    # scoping: unloading an entry's platforms removes exactly that
+    # entry's entities.
     hass.entities: dict[str, Entity] = {}
+    hass.entities_by_entry: dict[str, dict[str, Entity]] = {}
 
-    def _async_add_entities(new_entities, update_before_add=False):
-        """Mirror HA's AddEntitiesCallback: bind hass and register entities.
+    def _make_add_entities(entry):
+        entry_entities = hass.entities_by_entry.setdefault(entry.entry_id, {})
 
-        Accepts a single entity or an iterable, mirroring HA's
-        permissive call shape; registration goes through each entity's
-        async_write_ha_state (the mock state write).
-        """
-        if isinstance(new_entities, Entity):
-            new_entities = [new_entities]
-        for entity in new_entities:
-            entity.hass = hass
-            entity.async_write_ha_state()
+        def _async_add_entities(new_entities, update_before_add=False):
+            """Mirror HA's AddEntitiesCallback: bind hass and register.
+
+            Accepts a single entity or an iterable, mirroring HA's
+            permissive call shape; registration goes through each
+            entity's async_write_ha_state (the mock state write) and
+            is recorded per entry so an unload removes exactly this
+            entry's entities.
+            """
+            if isinstance(new_entities, Entity):
+                new_entities = [new_entities]
+            for entity in new_entities:
+                entity.hass = hass
+                entity.async_write_ha_state()
+                if entity.unique_id is not None:
+                    entry_entities[entity.unique_id] = entity
+
+        return _async_add_entities
 
     async def _async_forward_entry_setups(entry, platforms):
         """Mirror hass.config_entries.async_forward_entry_setups.
 
         HA's contract, loosely: import each platform module of the
-        entry's integration and drive its ``async_setup_entry`` with
-        the AddEntitiesCallback above.  A stub entry without a domain
+        entry's integration and drive its ``async_setup_entry`` with a
+        per-entry AddEntitiesCallback.  A stub entry without a domain
         defaults to this harness's single integration (NestQuest).
         """
         for platform in list(platforms):
@@ -707,14 +745,18 @@ def make_hass() -> tuple:
             module = importlib.import_module(
                 f"custom_components.{domain}.{platform}"
             )
-            await module.async_setup_entry(hass, entry, _async_add_entities)
+            await module.async_setup_entry(
+                hass, entry, _make_add_entities(entry)
+            )
             hass.config_entries.forwarded_platforms.append(platform)
 
     async def _async_unload_platforms(entry, platforms):
         """Mirror hass.config_entries.async_unload_platforms.
 
         Runs each platform module's ``async_unload_entry`` when it
-        defines one (per-platform unload is optional, like HA's).
+        defines one (per-platform unload is optional, like HA's), then
+        removes the entry's entities — unloading an entry's platforms
+        removes exactly that entry's entities, never another entry's.
         """
         for platform in list(platforms):
             domain = getattr(entry, "domain", "nestquest")
@@ -725,6 +767,8 @@ def make_hass() -> tuple:
             if unload is not None:
                 await unload(hass, entry)
             hass.config_entries.unloaded_platforms.append(platform)
+        for unique_id in hass.entities_by_entry.pop(entry.entry_id, {}):
+            hass.entities.pop(unique_id, None)
 
     hass.config_entries.forwarded_platforms: list[str] = []
     hass.config_entries.unloaded_platforms: list[str] = []

tests/test_entity_lifecycle.py

@@ -0,0 +1,187 @@
+"""Entity lifecycle across child add/deactivate/reactivate (Feature 10, task 8)."""
+from __future__ import annotations
+
+import datetime
+
+from conftest import wire_entry_to_registry
+
+from custom_components.nestquest import async_setup_entry, async_unload_entry
+from custom_components.nestquest.children import (
+    create_child,
+    list_children,
+    set_child_active,
+)
+from custom_components.nestquest.const import DOMAIN
+from custom_components.nestquest.materialize import materialize
+from custom_components.nestquest.quest_definitions import (
+    create_quest_definition,
+)
+from custom_components.nestquest.recurrence import ScheduleRule
+
+SEED_HORIZON_DAYS = 3
+PER_CHILD_KINDS = (
+    "quests_due_today",
+    "quests_completed_today",
+    "quests_remaining_today",
+    "completion_pct_today",
+    "next_quest",
+    "all_done",
+    "present_today",
+)
+HOUSEHOLD_UNIQUE_IDS = (
+    "nestquest_household_quests_due_today",
+    "nestquest_household_quests_completed_today",
+    "nestquest_cycle_day",
+)
+
+
+async def _reload(hass, entry) -> None:
+    """Unload then set up: the harness's restart/reload equivalent."""
+    assert await async_unload_entry(hass, entry) is True
+    assert await async_setup_entry(hass, entry) is True
+
+
+def _child_unique_ids(child_id: int) -> set[str]:
+    return {f"nestquest_child_{child_id}_{kind}" for kind in PER_CHILD_KINDS}
+
+
+async def _setup_and_seed(hass, make_entry):
+    entry = wire_entry_to_registry(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    database = entry.runtime_data.database
+    ada = await create_child(database, "Ada")
+    bo = await create_child(database, "Bo")
+    today = datetime.date.today()
+    await create_quest_definition(
+        database,
+        "Brush teeth",
+        ScheduleRule.from_dict(
+            {"rule_type": "daily", "start_date": today.isoformat()}
+        ),
+        [ada.id, bo.id],
+        ["morning"],
+    )
+    end = (today + datetime.timedelta(days=SEED_HORIZON_DAYS)).isoformat()
+    await materialize(database, today.isoformat(), end, today=today)
+    await entry.runtime_data.coordinator.async_refresh()
+    return entry, ada, bo
+
+
+async def test_deactivated_child_entities_removed_on_reload(
+    hass, make_entry
+) -> None:
+    entry, ada, bo = await _setup_and_seed(hass, make_entry)
+    assert _child_unique_ids(ada.id) <= set(hass.entities)
+    assert _child_unique_ids(bo.id) <= set(hass.entities)
+
+    await set_child_active(entry.runtime_data.database, bo.id, False)
+    await _reload(hass, entry)
+
+    assert _child_unique_ids(ada.id) <= set(hass.entities), (
+        "the surviving child's entities must be untouched"
+    )
+    assert not (_child_unique_ids(bo.id) & set(hass.entities)), (
+        "the deactivated child's entities must be gone after reload"
+    )
+
+
+async def test_reactivation_restores_entities_with_original_unique_ids(
+    hass, make_entry
+) -> None:
+    entry, ada, bo = await _setup_and_seed(hass, make_entry)
+    original = _child_unique_ids(bo.id)
+    await set_child_active(entry.runtime_data.database, bo.id, False)
+    await _reload(hass, entry)
+    assert not (original & set(hass.entities))
+
+    await set_child_active(entry.runtime_data.database, bo.id, True)
+    await _reload(hass, entry)
+
+    assert original <= set(hass.entities), (
+        "reactivation must restore the exact original unique_ids"
+    )
+    bo_due = hass.entities[f"nestquest_child_{bo.id}_quests_due_today"]
+    assert bo_due.native_value == 1, "restored entities carry live state"
+
+
+async def test_new_child_gets_entities_without_disturbing_existing(
+    hass, make_entry
+) -> None:
+    entry, ada, bo = await _setup_and_seed(hass, make_entry)
+    before_ada = set(hass.entities) & _child_unique_ids(ada.id)
+
+    cory = await create_child(entry.runtime_data.database, "Cory")
+    await _reload(hass, entry)
+
+    assert before_ada <= set(hass.entities), "existing entities untouched"
+    assert _child_unique_ids(cory.id) <= set(hass.entities), (
+        "the new child's entities appear after reload"
+    )
+    assert hass.entities[f"nestquest_child_{cory.id}_quests_due_today"].native_value == 0
+
+
+async def test_restart_equivalent_restores_all_entity_states(
+    hass, make_entry
+) -> None:
+    """Unload + setup (the restart equivalent) restores every active
+    child's entities with correct states and the household rollups."""
+    from custom_components.nestquest.completion import complete_instance
+
+    entry, ada, bo = await _setup_and_seed(hass, make_entry)
+    coordinator = entry.runtime_data.coordinator
+    snapshot_ada = next(
+        child
+        for child in coordinator.data.children
+        if child.child_id == ada.id
+    )
+    await complete_instance(
+        entry.runtime_data.database,
+        snapshot_ada.instances[0].instance_id,
+        actor_source="panel",
+        actor_child_id=ada.id,
+    )
+    await coordinator.async_refresh()
+    assert hass.entities[
+        f"nestquest_child_{ada.id}_quests_completed_today"
+    ].native_value == 1
+
+    await _reload(hass, entry)
+
+    assert hass.entities[
+        f"nestquest_child_{ada.id}_quests_completed_today"
+    ].native_value == 1, "completed count survives the restart"
+    assert hass.entities[
+        f"nestquest_child_{bo.id}_quests_completed_today"
+    ].native_value == 0
+    assert set(HOUSEHOLD_UNIQUE_IDS) <= set(hass.entities)
+    assert hass.entities[
+        "nestquest_household_quests_completed_today"
+    ].native_value == 1
+
+
+async def test_unload_shuts_coordinator_before_closing_database(
+    hass, make_entry
+) -> None:
+    """The coordinator's listeners are cleared while the database is
+    still connected: a scheduled refresh must never race the close."""
+    entry = wire_entry_to_registry(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    coordinator = entry.runtime_data.coordinator
+    database = entry.runtime_data.database
+    seen_connected = []
+
+    async def _probe_shutdown():
+        seen_connected.append(database.connected)
+
+    original_close = database.close
+
+    async def _recording_close():
+        seen_connected.append("closing")
+        await original_close()
+
+    coordinator.async_shutdown = _probe_shutdown
+    database.close = _recording_close
+    assert await async_unload_entry(hass, entry) is True
+    assert seen_connected == [True, "closing"], (
+        "coordinator shutdown must precede the database close"
+    )

tests/test_entity_matrix.py

@@ -0,0 +1,247 @@
+"""The Feature 10 entity-and-event matrix (task 9).
+
+One fixture drives every assertion the done-condition names: correct
+values for every sensor and binary sensor (including the zero-quest
+child and the 255-character state limit), the three events firing
+exactly once with schema-valid payloads, the instances payload
+omitting missed instances while admin_instances includes them, and no
+entities for an inactive child.  The per-task test files cover each
+behavior in depth; this file is the single pass that proves them all
+against ONE fixture, so a regression in any contract fails here too.
+"""
+from __future__ import annotations
+
+import datetime
+import re
+
+from conftest import wire_entry_to_registry
+
+from custom_components.nestquest import async_setup_entry
+from custom_components.nestquest.children import (
+    create_child,
+    list_children,
+    set_child_active,
+)
+from custom_components.nestquest.completion import derive_state
+from custom_components.nestquest.const import (
+    CONF_ADMIN_USER_IDS,
+    DOMAIN,
+    EVENT_CHILD_DAY_COMPLETE,
+    EVENT_QUEST_COMPLETED,
+    EVENT_QUEST_UNCOMPLETED,
+    SERVICE_COMPLETE_QUEST,
+    SERVICE_UNCOMPLETE_QUEST,
+)
+from custom_components.nestquest.dao_instances import QuestInstancesDao
+from custom_components.nestquest.materialize import materialize
+from custom_components.nestquest.quest_definitions import (
+    create_quest_definition,
+)
+from custom_components.nestquest.recurrence import ScheduleRule
+
+_TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$")
+
+
+async def _fixture(hass, make_entry):
+    """Two quest children, one zero-quest child, one inactive child."""
+    entry = wire_entry_to_registry(
+        make_entry(data={CONF_ADMIN_USER_IDS: ["admin-1"]}), hass.registry
+    )
+    assert await async_setup_entry(hass, entry) is True
+    database = entry.runtime_data.database
+    ada = await create_child(database, "Ada")
+    bo = await create_child(database, "Bo")
+    cory = await create_child(database, "Cory")
+    ghost = await create_child(database, "Ghost")
+    await set_child_active(database, ghost.id, False)
+    today = datetime.date.today()
+    await create_quest_definition(
+        database,
+        "Brush teeth",
+        ScheduleRule.from_dict(
+            {"rule_type": "daily", "start_date": today.isoformat()}
+        ),
+        [ada.id, bo.id],
+        ["morning", "evening"],
+    )
+    end = (today + datetime.timedelta(days=3)).isoformat()
+    await materialize(database, today.isoformat(), end, today=today)
+    await entry.runtime_data.coordinator.async_refresh()
+    return entry, (ada, bo, cory, ghost)
+
+
+def _sensor(hass, child_id, kind):
+    return hass.entities[f"{DOMAIN}_child_{child_id}_{kind}"]
+
+
+async def test_entity_and_event_matrix(hass, make_entry) -> None:
+    entry, (ada, bo, cory, ghost) = await _fixture(hass, make_entry)
+    coordinator = entry.runtime_data.coordinator
+
+    # --- Every active child has the full entity set; the inactive
+    # child has none.
+    kinds = (
+        "quests_due_today",
+        "quests_completed_today",
+        "quests_remaining_today",
+        "completion_pct_today",
+        "next_quest",
+        "all_done",
+        "present_today",
+    )
+    for child in (ada, bo, cory):
+        for kind in kinds:
+            assert f"{DOMAIN}_child_{child.id}_{kind}" in hass.entities, kind
+    for kind in kinds:
+        assert f"{DOMAIN}_child_{ghost.id}_{kind}" not in hass.entities, (
+            "inactive children must have no entities"
+        )
+
+    # --- Correct values against the fixture: Ada and Bo owe two
+    # quests (morning + evening), Cory owes none and is still 100%.
+    for child in (ada, bo):
+        assert _sensor(hass, child.id, "quests_due_today").native_value == 2
+        assert (
+            _sensor(hass, child.id, "quests_completed_today").native_value == 0
+        )
+        assert (
+            _sensor(hass, child.id, "quests_remaining_today").native_value == 2
+        )
+        assert (
+            _sensor(hass, child.id, "completion_pct_today").native_value == 0
+        )
+        assert _sensor(hass, child.id, "next_quest").native_value == (
+            "Brush teeth"
+        )
+        assert _sensor(hass, child.id, "all_done").is_on is False
+        assert _sensor(hass, child.id, "present_today").is_on is True
+    assert _sensor(hass, cory.id, "quests_due_today").native_value == 0
+    assert _sensor(hass, cory.id, "completion_pct_today").native_value == 100
+    assert _sensor(hass, cory.id, "all_done").is_on is False
+    assert _sensor(hass, cory.id, "next_quest").native_value == "none"
+
+    # --- Household rollups equal the per-child sums.
+    assert hass.entities[
+        "nestquest_household_quests_due_today"
+    ].native_value == 4
+    assert hass.entities[
+        "nestquest_household_quests_completed_today"
+    ].native_value == 0
+
+    # --- The 255-character limit holds for every registered entity.
+    for unique_id, entity in hass.entities.items():
+        state = getattr(entity, "native_value", None)
+        if state is None:
+            state = getattr(entity, "is_on", None)
+        assert state is None or not (
+            isinstance(state, str) and len(state) > 255
+        ), unique_id
+
+    # --- Completing both of Ada's quests fires the events exactly
+    # once each and flips her entities immediately.
+    instances = await QuestInstancesDao(
+        entry.runtime_data.database
+    ).list_by_date_range(
+        ada.id, datetime.date.today().isoformat(), datetime.date.today().isoformat()
+    )
+    for instance in instances:
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": instance.id,
+                "actor": "panel",
+                "actor_child_id": ada.id,
+            },
+        )
+    assert len(hass.bus.fired(EVENT_QUEST_COMPLETED)) == 2
+    for payload in hass.bus.fired(EVENT_QUEST_COMPLETED):
+        assert _TIMESTAMP.match(payload["occurred_at"])
+        assert isinstance(payload["was_on_time"], bool)
+        assert payload["child_name"] in ("Ada",)
+        assert payload["quest_title"] == "Brush teeth"
+        assert isinstance(payload["instance_id"], int)
+    assert len(hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)) == 1
+    assert _sensor(hass, ada.id, "all_done").is_on is True
+    assert _sensor(hass, ada.id, "quests_remaining_today").native_value == 0
+    assert (
+        _sensor(hass, ada.id, "completion_pct_today").native_value == 100
+    )
+
+    # --- Reversing one quest fires the uncompleted event exactly once
+    # and restores the owed counts.
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_UNCOMPLETE_QUEST,
+        {"instance_id": instances[0].id, "actor": "user"},
+        context={"user_id": "admin-1"},
+    )
+    assert len(hass.bus.fired(EVENT_QUEST_UNCOMPLETED)) == 1
+    assert _sensor(hass, ada.id, "all_done").is_on is False
+    assert _sensor(hass, ada.id, "quests_remaining_today").native_value == 1
+
+    # --- The instances payload omits missed instances while
+    # admin_instances includes them (D-009): pin the derive clock
+    # forward in the TEST ONLY so today's open instances read missed.
+    original_refresh = coordinator._async_update_data
+
+    async def _future_dated_refresh():
+        import custom_components.nestquest.coordinator as coordinator_module
+
+        real_derive = coordinator_module.derive_state
+
+        def _derive(instance, latest, today):
+            return real_derive(instance, latest, today + datetime.timedelta(days=1))
+
+        coordinator_module.derive_state = _derive
+        try:
+            return await original_refresh()
+        finally:
+            coordinator_module.derive_state = real_derive
+
+    coordinator._async_update_data = _future_dated_refresh
+    await coordinator.async_refresh()
+    attributes = _sensor(hass, bo.id, "quests_due_today").extra_state_attributes
+    assert attributes["instances"] == [], "panel payload omits missed"
+    assert len(attributes["admin_instances"]) == 2
+    assert all(
+        entry["state"] == "missed" for entry in attributes["admin_instances"]
+    )
+    coordinator._async_update_data = original_refresh
+    await coordinator.async_refresh()
+
+
+async def test_payload_schema_matches_the_documented_contract(
+    hass, make_entry
+) -> None:
+    """Every fired payload carries the documented fields with the
+    documented types."""
+    entry, (ada, _bo, _cory, _ghost) = await _fixture(hass, make_entry)
+    instances = await QuestInstancesDao(
+        entry.runtime_data.database
+    ).list_by_date_range(
+        ada.id, datetime.date.today().isoformat(), datetime.date.today().isoformat()
+    )
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": instances[0].id,
+            "actor": "panel",
+            "actor_child_id": ada.id,
+        },
+    )
+    payload = hass.bus.fired(EVENT_QUEST_COMPLETED)[0]
+    for key, check in (
+        ("child_id", lambda v: isinstance(v, int)),
+        ("child_name", lambda v: isinstance(v, str)),
+        ("instance_id", lambda v: isinstance(v, int)),
+        ("quest_title", lambda v: isinstance(v, str)),
+        ("window", lambda v: v in ("morning", "evening")),
+        ("due_date", lambda v: isinstance(v, str)),
+        ("due_time", lambda v: v is None or isinstance(v, str)),
+        ("occurred_at", lambda v: bool(_TIMESTAMP.match(v))),
+        ("was_on_time", lambda v: isinstance(v, bool)),
+    ):
+        assert key in payload, key
+        assert check(payload[key]), key

tests/test_events.py

@@ -0,0 +1,379 @@
+"""Tests for the NestQuest bus events (Feature 10, task 6)."""
+from __future__ import annotations
+
+import re
+
+from conftest import wire_entry_to_registry
+
+from custom_components.nestquest import async_setup_entry
+from custom_components.nestquest.children import create_child
+from custom_components.nestquest.const import (
+    CONF_ADMIN_USER_IDS,
+    DOMAIN,
+    EVENT_CHILD_DAY_COMPLETE,
+    EVENT_QUEST_COMPLETED,
+    EVENT_QUEST_MISSED,
+    EVENT_QUEST_UNCOMPLETED,
+    SERVICE_COMPLETE_QUEST,
+    SERVICE_CREATE_QUEST_DEFINITION,
+    SERVICE_MANAGE_CHILD,
+    SERVICE_REGENERATE,
+    SERVICE_UNCOMPLETE_QUEST,
+)
+from custom_components.nestquest.dao_instances import QuestInstancesDao
+from custom_components.nestquest.materialize import materialize
+from custom_components.nestquest.quest_definitions import (
+    create_quest_definition,
+)
+from custom_components.nestquest.recurrence import ScheduleRule
+
+ADMIN_CTX = {"user_id": "admin-1"}
+_TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$")
+
+
+async def _setup_and_seed(hass, make_entry, *, windows=("morning",)):
+    entry = wire_entry_to_registry(
+        make_entry(data={CONF_ADMIN_USER_IDS: ["admin-1"]}), hass.registry
+    )
+    assert await async_setup_entry(hass, entry) is True
+    database = entry.runtime_data.database
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_MANAGE_CHILD,
+        {"action": "create", "display_name": "Ada"},
+        context=ADMIN_CTX,
+    )
+    child = None
+    from custom_components.nestquest.children import list_children
+
+    child = (await list_children(database))[0]
+    await create_quest_definition(
+        database,
+        "Brush teeth",
+        ScheduleRule.from_dict(
+            {"rule_type": "daily", "start_date": __import__("datetime").date.today().isoformat()}
+        ),
+        [child.id],
+        list(windows),
+    )
+    import datetime
+
+    today = datetime.date.today().isoformat()
+    end = (datetime.date.today() + datetime.timedelta(days=3)).isoformat()
+    await materialize(database, today, end, today=datetime.date.today())
+    instances = await QuestInstancesDao(database).list_by_date_range(
+        child.id, today, today
+    )
+    return entry, child, instances
+
+
+async def test_quest_completed_fires_with_documented_payload(
+    hass, make_entry
+) -> None:
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    instance_id = instances[0].id
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {"instance_id": instance_id, "actor": "panel", "actor_child_id": child.id},
+    )
+    fired = hass.bus.fired(EVENT_QUEST_COMPLETED)
+    assert len(fired) == 1
+    payload = fired[0]
+    assert payload["child_id"] == child.id
+    assert payload["child_name"] == "Ada"
+    assert payload["instance_id"] == instance_id
+    assert payload["quest_title"] == "Brush teeth"
+    assert payload["window"] == "morning"
+    assert payload["was_on_time"] is not None
+    assert _TIMESTAMP.match(payload["occurred_at"]), payload["occurred_at"]
+
+
+async def test_recomplete_no_op_fires_nothing(hass, make_entry) -> None:
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    instance_id = instances[0].id
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {"instance_id": instance_id, "actor": "panel", "actor_child_id": child.id},
+    )
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {"instance_id": instance_id, "actor": "panel", "actor_child_id": child.id},
+    )
+    assert len(hass.bus.fired(EVENT_QUEST_COMPLETED)) == 1
+
+
+async def test_child_day_complete_fires_when_day_clears(
+    hass, make_entry
+) -> None:
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    for instance in instances:
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": instance.id,
+                "actor": "panel",
+                "actor_child_id": child.id,
+            },
+        )
+    day_complete = hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)
+    assert len(day_complete) == 1, "exactly one day-complete per cleared day"
+    payload = day_complete[0]
+    assert payload["child_id"] == child.id
+    assert payload["child_name"] == "Ada"
+    assert payload["quests_due"] == len(instances)
+    assert _TIMESTAMP.match(payload["occurred_at"])
+
+
+async def test_child_day_complete_does_not_fire_partway(
+    hass, make_entry
+) -> None:
+    entry, child, instances = await _setup_and_seed(
+        hass, make_entry, windows=("morning", "evening")
+    )
+    assert len(instances) == 2
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": instances[0].id,
+            "actor": "panel",
+            "actor_child_id": child.id,
+        },
+    )
+    assert hass.bus.fired(EVENT_CHILD_DAY_COMPLETE) == []
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": instances[1].id,
+            "actor": "panel",
+            "actor_child_id": child.id,
+        },
+    )
+    assert len(hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)) == 1
+
+
+async def test_uncompleted_fires_on_reversal_only(hass, make_entry) -> None:
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    instance_id = instances[0].id
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {"instance_id": instance_id, "actor": "panel", "actor_child_id": child.id},
+    )
+    # Un-completing an open instance is a no-op and fires nothing.
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_UNCOMPLETE_QUEST,
+        {"instance_id": instance_id, "actor": "user"},
+        context=ADMIN_CTX,
+    )
+    fired = hass.bus.fired(EVENT_QUEST_UNCOMPLETED)
+    assert len(fired) == 1
+    payload = fired[0]
+    assert payload["instance_id"] == instance_id
+    assert payload["quest_title"] == "Brush teeth"
+    assert _TIMESTAMP.match(payload["occurred_at"])
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_UNCOMPLETE_QUEST,
+        {"instance_id": instance_id, "actor": "user"},
+        context=ADMIN_CTX,
+    )
+    assert len(hass.bus.fired(EVENT_QUEST_UNCOMPLETED)) == 1
+
+
+def test_missed_event_name_is_documented_contract() -> None:
+    """Feature 10 defines the missed event Feature 11's sweep fires."""
+    assert EVENT_QUEST_MISSED == "nestquest_quest_missed"
+
+
+async def test_appended_verdict_is_atomic_under_duplicate_calls(
+    hass, make_entry
+) -> None:
+    """Concurrent duplicate completes decide appended under the same
+    lock as the write: exactly one fires the transition event."""
+    import asyncio
+
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    instance_id = instances[0].id
+    calls = [
+        hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": instance_id,
+                "actor": "panel",
+                "actor_child_id": child.id,
+            },
+        )
+        for _ in range(2)
+    ]
+    await asyncio.gather(*calls)
+    assert len(hass.bus.fired(EVENT_QUEST_COMPLETED)) == 1
+
+
+async def test_day_complete_ignored_for_backdated_completion(
+    hass, make_entry
+) -> None:
+    """Completing an instance NOT due today never evaluates the
+    child's day-complete, so a cleared day is announced at most once
+    per day and only by that day's completions."""
+    import datetime
+
+    from custom_components.nestquest.completion import (
+        complete_instance as _complete,
+    )
+
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    # A future instance (tomorrow) completed after today's day is
+    # already clear.
+    today = datetime.date.today()
+    end = (today + datetime.timedelta(days=3)).isoformat()
+    all_instances = await QuestInstancesDao(database).list_by_date_range(
+        child.id, today.isoformat(), end
+    )
+    today_ids = {instance.id for instance in instances}
+    tomorrow_instance = next(
+        instance
+        for instance in all_instances
+        if instance.id not in today_ids
+    )
+    for instance in instances:
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": instance.id,
+                "actor": "panel",
+                "actor_child_id": child.id,
+            },
+        )
+    assert len(hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)) == 1
+
+    await _complete(
+        database,
+        tomorrow_instance.id,
+        actor_source="user",
+        actor_user_id="admin-1",
+    )
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": tomorrow_instance.id,
+            "actor": "panel",
+            "actor_child_id": child.id,
+        },
+    )
+    assert len(hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)) == 1, (
+        "a back-dated/future completion must not re-announce today"
+    )
+    # The direct business-layer call fired nothing (only the service
+    # path fires), and the follow-up service call on the now-done
+    # future instance was a no-op: today's single completion stands.
+    assert len(hass.bus.fired(EVENT_QUEST_COMPLETED)) == len(instances)
+
+
+async def test_completion_updates_entities_immediately(
+    hass, make_entry
+) -> None:
+    """The remaining-today sensor reflects the completion the moment
+    the service call returns — no manual refresh — and the day-complete
+    event fired exactly once when the day became clear."""
+    from custom_components.nestquest.const import EVENT_CHILD_DAY_COMPLETE
+
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    from conftest import wire_entry_to_registry  # noqa: F401
+
+    coordinator = entry.runtime_data.coordinator
+    # Entities only exist after one refresh since they were seeded
+    # after setup; create them, then prove the service path refreshes.
+    await coordinator.async_refresh()
+    remaining_before = hass.entities[
+        f"nestquest_child_{child.id}_quests_remaining_today"
+    ].native_value
+    assert remaining_before == len(instances)
+
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": instances[0].id,
+            "actor": "panel",
+            "actor_child_id": child.id,
+        },
+    )
+    remaining_after = hass.entities[
+        f"nestquest_child_{child.id}_quests_remaining_today"
+    ].native_value
+    assert remaining_after == len(instances) - 1, (
+        "sensor must reflect the completion without a manual refresh"
+    )
+    assert len(hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)) == (
+        1 if len(instances) == 1 else 0
+    )
+
+
+async def test_uncompletion_updates_entities_immediately(
+    hass, make_entry
+) -> None:
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    coordinator = entry.runtime_data.coordinator
+    await coordinator.async_refresh()
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": instances[0].id,
+            "actor": "panel",
+            "actor_child_id": child.id,
+        },
+    )
+    completed_after_complete = hass.entities[
+        f"nestquest_child_{child.id}_quests_completed_today"
+    ].native_value
+    assert completed_after_complete == 1
+
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_UNCOMPLETE_QUEST,
+        {"instance_id": instances[0].id, "actor": "user"},
+        context=ADMIN_CTX,
+    )
+    completed_after_uncomplete = hass.entities[
+        f"nestquest_child_{child.id}_quests_completed_today"
+    ].native_value
+    assert completed_after_uncomplete == 0, (
+        "sensor must reflect the reversal without a manual refresh"
+    )
+
+
+async def test_forced_refreshes_serialize_no_stale_publish(
+    hass, make_entry
+) -> None:
+    """Overlapping forced refreshes never interleave: a slow pass
+    pauses mid-snapshot, and the queued pass still publishes AFTER
+    it, so the last published snapshot reflects the latest mutation."""
+    import asyncio
+
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    coordinator = entry.runtime_data.coordinator
+    order: list[str] = []
+
+    async def _slow_update():
+        order.append("start")
+        await asyncio.sleep(0.01)
+        order.append("end")
+        return coordinator.data
+
+    coordinator._async_update_data = _slow_update
+    await asyncio.gather(coordinator.async_refresh(), coordinator.async_refresh())
+    assert order == ["start", "end", "start", "end"], (
+        "overlapping refreshes must serialize: " + str(order)
+    )