feat: derive missed for past-due open instances

custom_components/nestquest/completion.py

@@ -6,9 +6,12 @@ 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 arrives in a later task.  Instance current state is
+un-completing (no-op if already open) is :func:`uncomplete_instance`.
-derived from the latest event via :func:`instance_state`
+Instance current state is derived from the latest event via
-(``open`` / ``done``); there is no status column.
+: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'``
@@ -34,6 +37,7 @@ from .dao_instances import (
     EVENT_UNCOMPLETED,
     CompletionEventRecord,
     CompletionEventsDao,
+    QuestInstanceRecord,
     QuestInstancesDao,
 )
 from .db import NestQuestDatabase
@@ -63,6 +67,95 @@ 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."""
 
@@ -104,9 +197,10 @@ 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` must re-enter on the
+    check+append in :func:`complete_instance` and
-    same task.  The wrapper is stored in the shared dict so the DAO
+    :func:`uncomplete_instance` must re-enter on the same task.  The
-    sees the same object.
+    wrapper is stored in the shared dict so the DAO sees the same
+    object.
     """
     loop = asyncio.get_running_loop()
     key = (id(database), id(loop))
@@ -230,15 +324,21 @@ async def append_event(
 async def instance_state(
     database: NestQuestDatabase,
     instance_id: int,
+    *,
+    today: datetime.date | None = None,
 ) -> str:
-    """Return ``open`` or ``done`` from the instance's latest event.
+    """Return ``open``, ``done``, or ``missed`` from the latest event.
 
-    No events, or a latest event of uncompleted, is ``open``.  A latest
+    No events, or a latest event of uncompleted, is ``open`` unless
-    event of completed is ``done``.  Unknown ``instance_id`` raises
+    ``due_date`` is before ``today`` (HA-local, threaded), in which
-    ValueError naming the field.  Existence and the latest event are
+    case it is ``missed``.  A latest event of completed is ``done``
-    read inside the connection lock so the answer is one snapshot.
+    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:
@@ -248,14 +348,7 @@ async def instance_state(
         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)
-        return "open"
-    if latest.event_type == EVENT_COMPLETED:
-        return "done"
-    raise ValueError(
-        f"event_type must be '{EVENT_COMPLETED}' or "
-        f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
-    )
 
 
 async def complete_instance(
@@ -276,11 +369,11 @@ async def complete_instance(
     append run under one connection lock so a concurrent complete
     cannot double-append.
 
-    ``was_on_time`` is recorded as True — a placeholder until the
+    ``was_on_time`` is computed from the HA-local completion moment
-    on-time task computes it from ``now`` / ``today`` against the
+    (threaded ``now`` / ``today``) against the instance ``due_date``
-    instance due_date and optional due_time.  ``today`` is accepted so
+    and optional ``due_time``.  ``now`` is the timezone-aware HA-local
-    callers can thread the HA-local date through without a signature
+    datetime; its wall clock is never converted to UTC.  Same-day
-    change; it is unused here.
+    ``due_time`` comparison requires ``now``.
     """
     instance_id = _validate_int_id(instance_id, "instance_id")
     actor_source, actor_user_id, actor_child_id = _validate_actor(
@@ -310,7 +403,93 @@ async def complete_instance(
             actor_source=actor_source,
             actor_user_id=actor_user_id,
             actor_child_id=actor_child_id,
-            was_on_time=True,
+            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

tests/test_completion.py

@@ -12,6 +12,8 @@ from custom_components.nestquest.completion import (
     append_event,
     complete_instance,
     instance_state,
+    list_missed_for_child,
+    uncomplete_instance,
 )
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.dao_instances import (
@@ -338,7 +340,8 @@ def test_module_never_exposes_update_or_delete() -> None:
     assert "append_event" in public
     assert "instance_state" in public
     assert "complete_instance" in public
-    assert "uncomplete_instance" not in public
+    assert "uncomplete_instance" in public
+    assert "list_missed_for_child" in public
     source = inspect.getsource(completion)
     assert "UPDATE" not in source
     assert "DELETE" not in source
@@ -684,3 +687,677 @@ def test_complete_instance_concurrent_second_call_is_noop(tmp_path) -> None:
             await database.close()
 
     _run(_main())
+
+
+_HA_TZ = datetime.timezone(datetime.timedelta(hours=-8))
+
+
+def _ha_local(day: datetime.date, hour: int, minute: int = 0) -> datetime.datetime:
+    return datetime.datetime(
+        day.year, day.month, day.day, hour, minute, 0,
+        tzinfo=_HA_TZ,
+    )
+
+
+def test_complete_instance_on_due_date_before_due_time_is_on_time(
+    tmp_path,
+) -> None:
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        instance = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            instance.due_date,
+            _now_stamp(),
+            window=instance.window,
+            due_time="12:00",
+        )
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=_ha_local(due_date, 11, 0),
+            today=due_date,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].was_on_time is True
+
+    _with_db(tmp_path, "ontime-before-due-time.db")(_body)
+
+
+def test_complete_instance_on_due_date_after_due_time_is_late(
+    tmp_path,
+) -> None:
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        instance = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            instance.due_date,
+            _now_stamp(),
+            window=instance.window,
+            due_time="12:00",
+        )
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=_ha_local(due_date, 12, 1),
+            today=due_date,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].was_on_time is False
+
+    _with_db(tmp_path, "late-after-due-time.db")(_body)
+
+
+def test_complete_instance_microsecond_after_due_time_is_late(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        instance = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            instance.due_date,
+            _now_stamp(),
+            window=instance.window,
+            due_time="12:00",
+        )
+        now = datetime.datetime(
+            due_date.year, due_date.month, due_date.day, 12, 0, 0, 500,
+            tzinfo=_HA_TZ,
+        )
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=now,
+            today=due_date,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].was_on_time is False
+
+    _with_db(tmp_path, "late-microsecond-after-due-time.db")(_body)
+
+
+def test_complete_instance_no_due_time_on_due_date_is_on_time(
+    tmp_path,
+) -> None:
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        assert instance.due_time is None
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=_ha_local(due_date, 23, 59),
+            today=due_date,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].was_on_time is True
+
+    _with_db(tmp_path, "ontime-no-due-time.db")(_body)
+
+
+def test_complete_instance_no_due_time_after_due_date_is_late(
+    tmp_path,
+) -> None:
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        later = due_date + datetime.timedelta(days=1)
+        assert instance.due_time is None
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=_ha_local(later, 8, 0),
+            today=later,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].was_on_time is False
+
+    _with_db(tmp_path, "late-after-due-date.db")(_body)
+
+
+def test_complete_instance_ha_local_wall_clock_not_utc(tmp_path) -> None:
+    """HA-local 11:00 with due_time 12:00 is on time even when UTC is 19:00.
+
+    The helper's zone is UTC-8, so 11:00 local is 19:00 UTC.  Converting
+    to UTC before comparing would mark this late.
+    """
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        instance = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            instance.due_date,
+            _now_stamp(),
+            window=instance.window,
+            due_time="12:00",
+        )
+        now = _ha_local(due_date, 11, 0)
+        assert now.astimezone(datetime.timezone.utc).hour == 19
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=now,
+            today=due_date,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].was_on_time is True
+
+    _with_db(tmp_path, "ontime-ha-local-not-utc.db")(_body)
+
+
+def test_complete_instance_due_time_requires_now_on_due_date(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        instance = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            instance.due_date,
+            _now_stamp(),
+            window=instance.window,
+            due_time="12:00",
+        )
+        with pytest.raises(ValueError, match="now is required to compare due_time"):
+            await complete_instance(
+                database,
+                instance.id,
+                actor_source="user",
+                actor_user_id="user-1",
+                today=due_date,
+            )
+
+    _with_db(tmp_path, "due-time-requires-now.db")(_body)
+
+
+# ---------------------------------------------------------------------------
+# uncomplete_instance: append uncompleted, no-op if already open
+# ---------------------------------------------------------------------------
+
+
+def test_uncomplete_instance_appends_and_leaves_original_untouched(
+    tmp_path,
+) -> None:
+    async def _body(database, child, instance):
+        completed_at = datetime.datetime(
+            2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
+        )
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=completed_at,
+        )
+        events = CompletionEventsDao(database)
+        before = await events.list_by_instance(instance.id)
+        assert len(before) == 1
+        original = before[0]
+        assert original.event_type == EVENT_COMPLETED
+        assert original.occurred_at == "2026-09-18T08:00:00+00:00"
+        assert original.actor_source == "user"
+        assert original.actor_user_id == "user-1"
+        assert original.actor_child_id is None
+        uncompleted_at = completed_at + datetime.timedelta(seconds=1)
+        state = await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="panel",
+            actor_child_id=child.id,
+            now=uncompleted_at,
+        )
+        assert state == "open"
+        assert await instance_state(database, instance.id) == "open"
+        after = await events.list_by_instance(instance.id)
+        assert len(after) == 2
+        assert after[0].id == original.id
+        assert after[0].event_type == EVENT_COMPLETED
+        assert after[0].occurred_at == original.occurred_at
+        assert after[0].actor_source == original.actor_source
+        assert after[0].actor_user_id == original.actor_user_id
+        assert after[0].actor_child_id == original.actor_child_id
+        assert after[1].event_type == EVENT_UNCOMPLETED
+        assert after[1].actor_source == "panel"
+        assert after[1].actor_child_id == child.id
+        assert after[1].was_on_time is None
+
+    _with_db(tmp_path, "uncomplete-append.db")(_body)
+
+
+def test_uncomplete_instance_already_open_is_noop(tmp_path) -> None:
+    async def _body(database, child, instance):
+        events = CompletionEventsDao(database)
+        assert await events.list_by_instance(instance.id) == []
+        first = await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+        )
+        after_first = await events.list_by_instance(instance.id)
+        assert first == "open"
+        assert after_first == []
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+        )
+        await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+        )
+        before = await events.list_by_instance(instance.id)
+        assert len(before) == 2
+        second = await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-2",
+        )
+        after = await events.list_by_instance(instance.id)
+        assert second == "open"
+        assert after == before
+        assert after[0].actor_user_id == "user-1"
+        assert after[1].actor_user_id == "user-1"
+
+    _with_db(tmp_path, "uncomplete-noop.db")(_body)
+
+
+def test_uncomplete_instance_unknown_instance_id_raises(tmp_path) -> None:
+    async def _body(database, child, instance):
+        with pytest.raises(ValueError, match="instance_id"):
+            await uncomplete_instance(
+                database,
+                instance.id + 999,
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+
+    _with_db(tmp_path, "uncomplete-unknown.db")(_body)
+
+
+def test_uncomplete_instance_rejects_non_integer_id() -> None:
+    async def _body():
+        with pytest.raises(ValueError, match="instance_id"):
+            await uncomplete_instance(
+                object(),
+                "1",
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+        with pytest.raises(ValueError, match="instance_id"):
+            await uncomplete_instance(
+                object(),
+                True,
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+
+    _run(_body())
+
+
+def test_uncomplete_instance_now_pins_occurred_at(tmp_path) -> None:
+    async def _body(database, child, instance):
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=datetime.datetime(
+                2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
+            ),
+        )
+        pinned = datetime.datetime(
+            2026, 9, 18, 8, 0, 1, tzinfo=datetime.timezone.utc
+        )
+        await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=pinned,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[1].occurred_at == "2026-09-18T08:00:01+00:00"
+
+    _with_db(tmp_path, "uncomplete-pinned.db")(_body)
+
+
+def test_uncomplete_instance_concurrent_second_call_is_noop(tmp_path) -> None:
+    """Two racing uncompletes cannot both append.
+
+    Deterministic gate: task A is paused at its INSERT (it holds the
+    connection lock); task B is then started and must queue.  A
+    finishes, B sees open and appends nothing.
+    """
+    async def _main():
+        armed = {"active": False, "gated": False}
+        gate_open = asyncio.Event()
+        a_started = asyncio.Event()
+        hass = _gated_hass(armed, gate_open, a_started)
+        database = NestQuestDatabase(hass)
+        await database.open(tmp_path / "uncomplete-race.db")
+        try:
+            await apply_migrations(database)
+            children = ChildrenDao(database)
+            rules = ScheduleRulesDao(database)
+            definitions = QuestDefinitionsDao(database)
+            instances = QuestInstancesDao(database)
+            child = await children.create("Ada", _now_stamp())
+            rule = await rules.create("daily", D1)
+            definition = await definitions.create(
+                "Brush teeth",
+                rule.id,
+                _now_stamp(),
+                assignee_child_ids=[child.id],
+            )
+            instance = await instances.upsert(
+                definition.id,
+                child.id,
+                D1,
+                _now_stamp(),
+                window="morning",
+            )
+            await complete_instance(
+                database,
+                instance.id,
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+
+            armed["active"] = True
+            task_a = asyncio.ensure_future(
+                uncomplete_instance(
+                    database,
+                    instance.id,
+                    actor_source="user",
+                    actor_user_id="user-1",
+                )
+            )
+            await a_started.wait()
+            armed["active"] = False
+            task_b = asyncio.ensure_future(
+                uncomplete_instance(
+                    database,
+                    instance.id,
+                    actor_source="user",
+                    actor_user_id="user-2",
+                )
+            )
+            await asyncio.sleep(0)
+            gate_open.set()
+            state_a, state_b = await asyncio.gather(task_a, task_b)
+            assert state_a == "open"
+            assert state_b == "open"
+            rows = await CompletionEventsDao(database).list_by_instance(
+                instance.id
+            )
+            assert len(rows) == 2
+            assert rows[0].event_type == EVENT_COMPLETED
+            assert rows[1].event_type == EVENT_UNCOMPLETED
+            assert rows[1].actor_user_id == "user-1"
+        finally:
+            await database.close()
+
+    _run(_main())
+
+
+# ---------------------------------------------------------------------------
+# missed: derived for past-due open instances, never stored
+# ---------------------------------------------------------------------------
+
+
+def test_append_event_rejects_missed_event_type() -> None:
+    async def _body():
+        with pytest.raises(ValueError, match="event_type"):
+            await append_event(
+                object(),
+                1,
+                1,
+                "missed",
+                actor_source="user",
+                actor_user_id="user-1",
+                was_on_time=True,
+            )
+
+    _run(_body())
+
+
+def test_instance_state_missed_when_past_due_and_open(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        later = due + datetime.timedelta(days=1)
+        assert await instance_state(database, instance.id, today=later) == "missed"
+        rows = await CompletionEventsDao(database).list_by_instance(instance.id)
+        assert rows == []
+
+    _with_db(tmp_path, "state-missed-open.db")(_body)
+
+
+def test_instance_state_open_when_due_today(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        assert await instance_state(database, instance.id, today=due) == "open"
+
+    _with_db(tmp_path, "state-open-due-today.db")(_body)
+
+
+def test_instance_state_done_when_past_due_and_completed(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            today=due,
+        )
+        later = due + datetime.timedelta(days=1)
+        assert await instance_state(database, instance.id, today=later) == "done"
+
+    _with_db(tmp_path, "state-done-past-due.db")(_body)
+
+
+def test_instance_state_missed_after_uncompleted_when_past_due(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        await append_event(
+            database,
+            instance.id,
+            child.id,
+            EVENT_COMPLETED,
+            actor_source="user",
+            actor_user_id="user-1",
+            was_on_time=True,
+        )
+        await append_event(
+            database,
+            instance.id,
+            child.id,
+            EVENT_UNCOMPLETED,
+            actor_source="user",
+            actor_user_id="user-1",
+        )
+        later = due + datetime.timedelta(days=1)
+        assert await instance_state(database, instance.id, today=later) == "missed"
+
+    _with_db(tmp_path, "state-missed-uncompleted.db")(_body)
+
+
+def test_instance_state_missed_uses_host_today_when_unthreaded(tmp_path) -> None:
+    async def _body(database, child, instance):
+        yesterday = datetime.date.today() - datetime.timedelta(days=1)
+        past = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            yesterday.isoformat(),
+            _now_stamp(),
+            window="afternoon",
+            today=yesterday,
+        )
+        assert await instance_state(database, past.id) == "missed"
+        rows = await CompletionEventsDao(database).list_by_instance(past.id)
+        assert rows == []
+        assert all(row.event_type != "missed" for row in rows)
+
+    _with_db(tmp_path, "state-missed-host-today.db")(_body)
+
+
+def test_uncomplete_past_due_done_returns_missed_not_done(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            today=due,
+        )
+        later = due + datetime.timedelta(days=1)
+        assert await instance_state(database, instance.id, today=later) == "done"
+        state = await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            today=later,
+        )
+        assert state == "missed"
+        assert await instance_state(database, instance.id, today=later) == "missed"
+        rows = await CompletionEventsDao(database).list_by_instance(instance.id)
+        assert [row.event_type for row in rows] == [
+            EVENT_COMPLETED,
+            EVENT_UNCOMPLETED,
+        ]
+        assert all(row.event_type != "missed" for row in rows)
+
+    _with_db(tmp_path, "uncomplete-past-due-missed.db")(_body)
+
+
+def test_uncomplete_past_due_already_open_is_noop_missed(tmp_path) -> None:
+    async def _body(database, child, instance):
+        later = datetime.date.fromisoformat(instance.due_date) + datetime.timedelta(
+            days=1
+        )
+        events = CompletionEventsDao(database)
+        assert await events.list_by_instance(instance.id) == []
+        state = await uncomplete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            today=later,
+        )
+        assert state == "missed"
+        assert await events.list_by_instance(instance.id) == []
+
+    _with_db(tmp_path, "uncomplete-past-due-noop.db")(_body)
+
+
+def test_complete_instance_of_missed_returns_done(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        later = due + datetime.timedelta(days=1)
+        assert await instance_state(database, instance.id, today=later) == "missed"
+        state = await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=_ha_local(later, 8, 0),
+            today=later,
+        )
+        assert state == "done"
+        assert await instance_state(database, instance.id, today=later) == "done"
+        rows = await CompletionEventsDao(database).list_by_instance(instance.id)
+        assert len(rows) == 1
+        assert rows[0].event_type == EVENT_COMPLETED
+        assert rows[0].was_on_time is False
+
+    _with_db(tmp_path, "complete-missed.db")(_body)
+
+
+def test_list_missed_for_child_over_date_range(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        later_due = due + datetime.timedelta(days=1)
+        other = await QuestInstancesDao(database).upsert(
+            instance.definition_id,
+            child.id,
+            later_due.isoformat(),
+            _now_stamp(),
+            window="morning",
+        )
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+            today=due,
+        )
+        today = later_due + datetime.timedelta(days=1)
+        found = await list_missed_for_child(
+            database,
+            child.id,
+            instance.due_date,
+            later_due.isoformat(),
+            today=today,
+        )
+        assert [row.id for row in found] == [other.id]
+        events = CompletionEventsDao(database)
+        assert await events.list_by_instance(other.id) == []
+        done_rows = await events.list_by_instance(instance.id)
+        assert [row.event_type for row in done_rows] == [EVENT_COMPLETED]
+        assert all(row.event_type != "missed" for row in done_rows)
+
+    _with_db(tmp_path, "list-missed-range.db")(_body)
+
+
+def test_list_missed_for_child_empty_when_due_today(tmp_path) -> None:
+    async def _body(database, child, instance):
+        due = datetime.date.fromisoformat(instance.due_date)
+        found = await list_missed_for_child(
+            database,
+            child.id,
+            instance.due_date,
+            instance.due_date,
+            today=due,
+        )
+        assert found == []
+
+    _with_db(tmp_path, "list-missed-due-today.db")(_body)
+
+
+def test_list_missed_for_child_rejects_non_integer_id() -> None:
+    async def _body():
+        with pytest.raises(ValueError, match="child_id"):
+            await list_missed_for_child(object(), "1", D1, D1)
+        with pytest.raises(ValueError, match="child_id"):
+            await list_missed_for_child(object(), True, D1, D1)
+
+    _run(_body())