feat: derive instance state from latest completion event

custom_components/nestquest/completion.py

@@ -5,8 +5,10 @@ Sits between the Feature 09 service gate and the typed
 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 and
-un-completing an instance (no-op-if-already-done, derived state) arrive
+un-completing an instance (no-op-if-already-done) arrive in later
-in later tasks; this module is the append wrapper only.
+tasks.  Instance current state is derived from the latest event via
+:func:`instance_state` (``open`` / ``done``); there is no status
+column.
 
 Actor policy matches the schema CHECKs (D-008): ``actor_source`` is
 ``'user'`` or ``'panel'`` only — never ``'service'``.  ``'user'``
@@ -25,11 +27,13 @@ from __future__ import annotations
 
 import datetime
 
+from .dao_children import _connection_lock
 from .dao_instances import (
     EVENT_COMPLETED,
     EVENT_UNCOMPLETED,
     CompletionEventRecord,
     CompletionEventsDao,
+    QuestInstancesDao,
 )
 from .db import NestQuestDatabase
 
@@ -163,3 +167,34 @@ 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,
+) -> str:
+    """Return ``open`` or ``done`` from the instance's latest event.
+
+    No events, or a latest event of uncompleted, is ``open``.  A latest
+    event of completed is ``done``.  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")
+    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
+        )
+    if latest is None or latest.event_type == EVENT_UNCOMPLETED:
+        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}"
+    )

tests/test_completion.py

@@ -8,12 +8,13 @@ import re
 
 import pytest
 
-from custom_components.nestquest.completion import append_event
+from custom_components.nestquest.completion import append_event, instance_state
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.dao_instances import (
     EVENT_COMPLETED,
     EVENT_UNCOMPLETED,
     CompletionEventRecord,
+    CompletionEventsDao,
     QuestInstancesDao,
 )
 from custom_components.nestquest.dao_rules import (
@@ -331,9 +332,115 @@ def test_module_never_exposes_update_or_delete() -> None:
         f"completion.py exposed mutation methods: {forbidden}"
     )
     assert "append_event" in public
+    assert "instance_state" in public
     assert "complete_instance" not in public
     assert "uncomplete_instance" not in public
     source = inspect.getsource(completion)
     assert "UPDATE" not in source
     assert "DELETE" not in source
     assert "INSERT" not in source
+
+
+# ---------------------------------------------------------------------------
+# instance_state: derived from the latest event
+# ---------------------------------------------------------------------------
+
+
+def test_instance_state_open_when_no_events(tmp_path) -> None:
+    async def _body(database, child, instance):
+        assert await instance_state(database, instance.id) == "open"
+
+    _with_db(tmp_path, "state-none.db")(_body)
+
+
+def test_instance_state_open_when_latest_uncompleted(tmp_path) -> None:
+    async def _body(database, child, instance):
+        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",
+        )
+        assert await instance_state(database, instance.id) == "open"
+
+    _with_db(tmp_path, "state-uncompleted.db")(_body)
+
+
+def test_instance_state_unknown_instance_id_raises(tmp_path) -> None:
+    async def _body(database, child, instance):
+        with pytest.raises(ValueError, match="instance_id"):
+            await instance_state(database, instance.id + 999)
+
+    _with_db(tmp_path, "state-unknown.db")(_body)
+
+
+def test_instance_state_rejects_non_integer_id() -> None:
+    async def _body():
+        with pytest.raises(ValueError, match="instance_id"):
+            await instance_state(object(), "1")
+        with pytest.raises(ValueError, match="instance_id"):
+            await instance_state(object(), True)
+
+    _run(_body())
+
+
+def test_instance_state_three_events_returns_done_and_preserves_rows(
+    tmp_path,
+) -> None:
+    async def _body(database, child, instance):
+        base = datetime.datetime(
+            2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
+        )
+        await append_event(
+            database,
+            instance.id,
+            child.id,
+            EVENT_COMPLETED,
+            actor_source="user",
+            actor_user_id="user-1",
+            was_on_time=True,
+            now=base,
+        )
+        await append_event(
+            database,
+            instance.id,
+            child.id,
+            EVENT_UNCOMPLETED,
+            actor_source="user",
+            actor_user_id="user-1",
+            now=base + datetime.timedelta(seconds=1),
+        )
+        await append_event(
+            database,
+            instance.id,
+            child.id,
+            EVENT_COMPLETED,
+            actor_source="user",
+            actor_user_id="user-1",
+            was_on_time=False,
+            now=base + datetime.timedelta(seconds=2),
+        )
+        events = CompletionEventsDao(database)
+        before = await events.list_by_instance(instance.id)
+        assert [e.event_type for e in before] == [
+            EVENT_COMPLETED,
+            EVENT_UNCOMPLETED,
+            EVENT_COMPLETED,
+        ]
+        assert await instance_state(database, instance.id) == "done"
+        after = await events.list_by_instance(instance.id)
+        assert after == before
+        assert len(after) == 3
+
+    _with_db(tmp_path, "state-three.db")(_body)