diff --git a/custom_components/nestquest/completion.py b/custom_components/nestquest/completion.py index 4b512b4..94bbb46 100644 --- a/custom_components/nestquest/completion.py +++ b/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 -in later tasks; this module is the append wrapper only. +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. 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}" + ) diff --git a/tests/test_completion.py b/tests/test_completion.py index 5b4dc19..5412db5 100644 --- a/tests/test_completion.py +++ b/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)