feat: complete_instance no-op if already done

custom_components/nestquest/completion.py

@@ -4,11 +4,11 @@ Sits between the Feature 09 service gate and the typed
 :class:`~.dao_instances.CompletionEventsDao`: callers get actor-shape
 validation and the UTC occurred-at stamp here, and never talk to the
 DAO or SQL directly.  This module is the only Feature-08 caller of
-:meth:`~.dao_instances.CompletionEventsDao.append`.  Completing and
-un-completing an instance (no-op-if-already-done) arrive in later
-tasks.  Instance current state is derived from the latest event via
-:func:`instance_state` (``open`` / ``done``); there is no status
-column.
+: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
+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'``
@@ -198,3 +198,50 @@ async def instance_state(
         f"event_type must be '{EVENT_COMPLETED}' or "
         f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
     )
+
+
+async def complete_instance(
+    database: NestQuestDatabase,
+    instance_id: int,
+    *,
+    actor_source: str,
+    actor_user_id: str | None = None,
+    actor_child_id: int | None = None,
+    now: datetime.datetime | None = None,
+    today: datetime.date | None = None,
+) -> str:
+    """Append a completed event unless the instance is already done.
+
+    Returns the derived state ``done``.  An already-done instance is a
+    no-op: nothing is appended.  Unknown ``instance_id`` raises
+    ValueError naming the field.
+
+    ``was_on_time`` is recorded as True — a placeholder until the
+    on-time task computes it from ``now`` / ``today`` against the
+    instance due_date and optional due_time.  ``today`` is accepted so
+    callers can thread the HA-local date through without a signature
+    change; it is unused here.
+    """
+    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
+    )
+    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"
+        )
+    if await instance_state(database, instance_id) == "done":
+        return "done"
+    await append_event(
+        database,
+        instance.id,
+        instance.child_id,
+        EVENT_COMPLETED,
+        actor_source=actor_source,
+        actor_user_id=actor_user_id,
+        actor_child_id=actor_child_id,
+        was_on_time=True,
+        now=now,
+    )
+    return "done"

tests/test_completion.py

@@ -8,7 +8,11 @@ import re
 
 import pytest
 
-from custom_components.nestquest.completion import append_event, instance_state
+from custom_components.nestquest.completion import (
+    append_event,
+    complete_instance,
+    instance_state,
+)
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.dao_instances import (
     EVENT_COMPLETED,
@@ -333,7 +337,7 @@ def test_module_never_exposes_update_or_delete() -> None:
     )
     assert "append_event" in public
     assert "instance_state" in public
-    assert "complete_instance" not in public
+    assert "complete_instance" in public
     assert "uncomplete_instance" not in public
     source = inspect.getsource(completion)
     assert "UPDATE" not in source
@@ -444,3 +448,147 @@ def test_instance_state_three_events_returns_done_and_preserves_rows(
         assert len(after) == 3
 
     _with_db(tmp_path, "state-three.db")(_body)
+
+
+# ---------------------------------------------------------------------------
+# complete_instance: append completed, no-op if already done
+# ---------------------------------------------------------------------------
+
+
+def test_complete_instance_appends_and_returns_done(tmp_path) -> None:
+    async def _body(database, child, instance):
+        events = CompletionEventsDao(database)
+        assert await events.list_by_instance(instance.id) == []
+        state = await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+        )
+        assert state == "done"
+        assert await instance_state(database, instance.id) == "done"
+        rows = await events.list_by_instance(instance.id)
+        assert len(rows) == 1
+        assert rows[0].event_type == EVENT_COMPLETED
+        assert rows[0].actor_source == "user"
+        assert rows[0].actor_user_id == "user-1"
+        assert rows[0].was_on_time is True
+
+    _with_db(tmp_path, "complete-open.db")(_body)
+
+
+def test_complete_instance_already_done_is_noop(tmp_path) -> None:
+    async def _body(database, child, instance):
+        first = await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-1",
+        )
+        events = CompletionEventsDao(database)
+        before = await events.list_by_instance(instance.id)
+        assert first == "done"
+        assert len(before) == 1
+        second = await complete_instance(
+            database,
+            instance.id,
+            actor_source="user",
+            actor_user_id="user-2",
+        )
+        after = await events.list_by_instance(instance.id)
+        assert second == "done"
+        assert after == before
+        assert after[0].actor_user_id == "user-1"
+
+    _with_db(tmp_path, "complete-noop.db")(_body)
+
+
+def test_complete_instance_unknown_instance_id_raises(tmp_path) -> None:
+    async def _body(database, child, instance):
+        with pytest.raises(ValueError, match="instance_id"):
+            await complete_instance(
+                database,
+                instance.id + 999,
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+
+    _with_db(tmp_path, "complete-unknown.db")(_body)
+
+
+def test_complete_instance_rejects_non_integer_id() -> None:
+    async def _body():
+        with pytest.raises(ValueError, match="instance_id"):
+            await complete_instance(
+                object(),
+                "1",
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+        with pytest.raises(ValueError, match="instance_id"):
+            await complete_instance(
+                object(),
+                True,
+                actor_source="user",
+                actor_user_id="user-1",
+            )
+
+    _run(_body())
+
+
+def test_complete_instance_after_uncompleted_appends(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",
+        )
+        events = CompletionEventsDao(database)
+        before = await events.list_by_instance(instance.id)
+        assert await instance_state(database, instance.id) == "open"
+        state = await complete_instance(
+            database,
+            instance.id,
+            actor_source="panel",
+            actor_child_id=child.id,
+        )
+        assert state == "done"
+        after = await events.list_by_instance(instance.id)
+        assert len(after) == len(before) + 1
+        assert after[-1].event_type == EVENT_COMPLETED
+        assert after[-1].actor_source == "panel"
+        assert after[-1].was_on_time is True
+
+    _with_db(tmp_path, "complete-reopen.db")(_body)
+
+
+def test_complete_instance_now_pins_occurred_at(tmp_path) -> None:
+    async def _body(database, child, instance):
+        pinned = 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=pinned,
+        )
+        rows = await CompletionEventsDao(database).list_by_instance(
+            instance.id
+        )
+        assert rows[0].occurred_at == "2026-09-18T08:00:00+00:00"
+
+    _with_db(tmp_path, "complete-pinned.db")(_body)