Compare commits

...
4 changed files with 712 additions and 16 deletions
+200
View File
@@ -0,0 +1,200 @@
"""Business layer for the completion event log (Feature 08).
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.
Actor policy matches the schema CHECKs (D-008): ``actor_source`` is
``'user'`` or ``'panel'`` only — never ``'service'``. ``'user'``
requires ``actor_user_id`` and forbids ``actor_child_id``; ``'panel'``
requires ``actor_child_id`` (the tapped profile) and forbids
``actor_user_id``. Inverted shapes raise a field-naming ValueError
before any write.
``occurred_at`` is stamped UTC ISO-8601 at second precision with an
explicit ``+00:00`` offset, matching the DAO's one accepted shape so
lexicographic range queries stay exact. ``was_on_time`` is required
(True/False) for completed events; un-completions may pass None. There
is no permission check here (that is Feature 09).
"""
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
#: Timestamp policy for completion_events.occurred_at: strict UTC
#: ISO-8601 with explicit '+00:00' offset (module timestamp policy).
_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
def _now_stamp() -> str:
"""Return the module's strict UTC second-precision stamp."""
return datetime.datetime.now(datetime.timezone.utc).strftime(
_UTC_TIMESTAMP_FORMAT
)
def _stamp_occurred_at(now: datetime.datetime | None) -> str:
"""Return a DAO-accepted UTC stamp for ``now``, or the current time."""
if now is None:
return _now_stamp()
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")
return now.astimezone(datetime.timezone.utc).strftime(
_UTC_TIMESTAMP_FORMAT
)
def _validate_int_id(value: object, field: str) -> int:
"""Reject non-int ids (bools included) before any lookup."""
if isinstance(value, bool) or not isinstance(value, int):
raise ValueError(f"{field} must be an integer, got {value!r}")
return value
def _validate_event_type(value: object) -> str:
"""Return a schema-legal event type, or raise naming the field."""
if value not in (EVENT_COMPLETED, EVENT_UNCOMPLETED):
raise ValueError(
f"event_type must be '{EVENT_COMPLETED}' or "
f"'{EVENT_UNCOMPLETED}', got {value!r}"
)
return value
def _validate_actor(
actor_source: object,
actor_user_id: object,
actor_child_id: object,
) -> tuple[str, str | None, int | None]:
"""Return a schema-legal actor triple, or raise naming the field.
``'user'`` requires a non-empty ``actor_user_id`` string and forbids
``actor_child_id``. ``'panel'`` requires an integer
``actor_child_id`` and forbids ``actor_user_id``. Any other
``actor_source`` (including ``'service'``) is rejected.
"""
if actor_source not in ("user", "panel"):
raise ValueError(
f"actor_source must be 'user' or 'panel', got {actor_source!r}"
)
if actor_source == "user":
if not isinstance(actor_user_id, str) or not actor_user_id.strip():
raise ValueError("actor_source 'user' requires actor_user_id")
if actor_child_id is not None:
raise ValueError(
"actor_source 'user' must not carry actor_child_id"
)
return "user", actor_user_id.strip(), None
if actor_user_id is not None:
raise ValueError("actor_source 'panel' must not carry actor_user_id")
if actor_child_id is None:
raise ValueError(
"actor_source 'panel' requires actor_child_id"
)
return (
"panel",
None,
_validate_int_id(actor_child_id, "actor_child_id"),
)
def _validate_was_on_time(
event_type: str, was_on_time: object
) -> bool | None:
"""Return a real bool or None; completed events require True/False."""
if was_on_time is not None and type(was_on_time) is not bool:
raise ValueError(
f"was_on_time must be True, False or None, got {was_on_time!r}"
)
if event_type == EVENT_COMPLETED and was_on_time is None:
raise ValueError(
"a completed event requires was_on_time (True/False)"
)
return was_on_time
async def append_event(
database: NestQuestDatabase,
instance_id: int,
child_id: int,
event_type: str,
*,
actor_source: str,
actor_user_id: str | None = None,
actor_child_id: int | None = None,
was_on_time: bool | None = None,
now: datetime.datetime | None = None,
) -> CompletionEventRecord:
"""Append one completion or un-completion event and return the row.
Validates actor shapes and the completed-event on-time requirement
before calling :meth:`CompletionEventsDao.append`. ``occurred_at``
is stamped here (UTC ``+00:00``); pass ``now`` to pin the clock.
"""
instance_id = _validate_int_id(instance_id, "instance_id")
child_id = _validate_int_id(child_id, "child_id")
event_type = _validate_event_type(event_type)
actor_source, actor_user_id, actor_child_id = _validate_actor(
actor_source, actor_user_id, actor_child_id
)
was_on_time = _validate_was_on_time(event_type, was_on_time)
occurred_at = _stamp_occurred_at(now)
return await CompletionEventsDao(database).append(
instance_id,
child_id,
event_type,
actor_source,
occurred_at,
was_on_time,
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}"
)
+16 -9
View File
@@ -344,14 +344,20 @@ class QuestInstancesDao:
- the (definition, child) assignment link still exists (a removed
assignment is skipped);
- the window is still declared on the definition (a removed window
is skipped).
is skipped);
- the window's live ``due_time`` still EQUALS the caller-supplied
``due_time`` (NULL-safe: NULL == NULL counts as equal; a window
with no due time matches a snapshot with no due time). A
window-time edit landed after the input snapshot makes the
caller's ``due_time`` stale, and writing it would overwrite the
newer due_time a concurrent regeneration already upserted — so
the tuple is skipped instead of written.
The live checks above ONLY decide whether the tuple is still
valid; they never read the window's ``due_time``. The instance is
written with the caller-supplied ``due_time`` — the value snapshotted
from the coherent input read — so a window-time edit landing
mid-walk cannot leak a newer time into a batch that was already
snapshotted against older rule/presence/assignment decisions.
The due_time check closes the one check-then-insert gap this
method previously left open: it re-validated every OTHER
precondition but then wrote the snapshot's ``due_time``
unconditionally, so a stale materialization could clobber a
newer, concurrently-regenerated due_time.
Returns the stored instance, or ``None`` when a precondition
failed — the tuple no longer materializable, which the walk SKIPS
@@ -384,8 +390,9 @@ class QuestInstancesDao:
"JOIN quest_definition_windows w "
"ON w.definition_id = d.id "
"WHERE d.id = ? AND a.child_id = ? AND w.window = ? "
"AND d.is_active = 1 AND c.is_active = 1 LIMIT 1",
(definition_id, child_id, window),
"AND d.is_active = 1 AND c.is_active = 1 "
"AND w.due_time IS ? LIMIT 1",
(definition_id, child_id, window, due_time),
)
if still_valid is None:
# A config change invalidated the tuple since the
+446
View File
@@ -0,0 +1,446 @@
"""Tests for completion.py: the Feature 08 append-only business layer."""
from __future__ import annotations
import asyncio
import datetime
import inspect
import re
import pytest
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 (
QuestDefinitionsDao,
ScheduleRulesDao,
)
from custom_components.nestquest.db import NestQuestDatabase
from custom_components.nestquest.migrations import apply_migrations
def _run(coro):
return asyncio.new_event_loop().run_until_complete(coro)
def _make_hass_mock():
from unittest.mock import AsyncMock, MagicMock
hass = MagicMock()
hass.async_add_executor_job = AsyncMock(side_effect=(lambda fn, *a: fn(*a)))
return hass
def _today_iso() -> str:
return datetime.date.today().isoformat()
def _now_stamp() -> str:
return f"{_today_iso()}T08:00:00+00:00"
def _future_day(offset: int) -> str:
return (
datetime.date.today() + datetime.timedelta(days=offset)
).isoformat()
D1 = _future_day(1)
async def _prepare(path) -> tuple:
database = NestQuestDatabase(_make_hass_mock())
await database.open(path)
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"
)
return database, child, instance
def _with_db(tmp_path, name):
def _run_test(body):
async def _main():
prepared = await _prepare(tmp_path / name)
try:
return await body(*prepared)
finally:
await prepared[0].close()
return _run(_main())
return _run_test
# ---------------------------------------------------------------------------
# inverted actor shapes: field-naming ValueErrors, no write
# ---------------------------------------------------------------------------
def test_user_without_actor_user_id_rejected() -> None:
async def _body():
with pytest.raises(ValueError, match="actor_user_id"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="user",
was_on_time=True,
)
with pytest.raises(ValueError, match="actor_user_id"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="user",
actor_user_id=None,
was_on_time=True,
)
with pytest.raises(ValueError, match="actor_user_id"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="user",
actor_user_id="",
was_on_time=True,
)
_run(_body())
def test_user_must_not_carry_actor_child_id() -> None:
async def _body():
with pytest.raises(ValueError, match="actor_child_id"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="user",
actor_user_id="user-1",
actor_child_id=1,
was_on_time=True,
)
_run(_body())
def test_panel_must_not_carry_actor_user_id() -> None:
async def _body():
with pytest.raises(ValueError, match="actor_user_id"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="panel",
actor_user_id="user-1",
actor_child_id=1,
was_on_time=True,
)
_run(_body())
def test_panel_requires_actor_child_id() -> None:
async def _body():
with pytest.raises(ValueError, match="actor_child_id"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="panel",
was_on_time=True,
)
_run(_body())
def test_actor_source_service_rejected() -> None:
async def _body():
with pytest.raises(ValueError, match="actor_source"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="service",
actor_user_id="user-1",
was_on_time=True,
)
_run(_body())
def test_completed_requires_was_on_time() -> None:
async def _body():
with pytest.raises(ValueError, match="was_on_time"):
await append_event(
object(),
1,
1,
EVENT_COMPLETED,
actor_source="user",
actor_user_id="user-1",
)
_run(_body())
# ---------------------------------------------------------------------------
# happy paths
# ---------------------------------------------------------------------------
def test_user_append_round_trips(tmp_path) -> None:
async def _body(database, child, instance):
event = await append_event(
database,
instance.id,
child.id,
EVENT_COMPLETED,
actor_source="user",
actor_user_id="user-1",
was_on_time=True,
)
assert isinstance(event, CompletionEventRecord)
assert event.event_type == EVENT_COMPLETED
assert event.actor_source == "user"
assert event.actor_user_id == "user-1"
assert event.actor_child_id is None
assert event.was_on_time is True
assert re.fullmatch(
r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00", event.occurred_at
)
return event
_with_db(tmp_path, "user-append.db")(_body)
def test_panel_append_round_trips(tmp_path) -> None:
async def _body(database, child, instance):
event = await append_event(
database,
instance.id,
child.id,
EVENT_COMPLETED,
actor_source="panel",
actor_child_id=child.id,
was_on_time=False,
)
assert event.actor_source == "panel"
assert event.actor_user_id is None
assert event.actor_child_id == child.id
assert event.was_on_time is False
assert re.fullmatch(
r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00", event.occurred_at
)
return event
_with_db(tmp_path, "panel-append.db")(_body)
def test_uncompleted_allows_null_was_on_time(tmp_path) -> None:
async def _body(database, child, instance):
event = await append_event(
database,
instance.id,
child.id,
EVENT_UNCOMPLETED,
actor_source="user",
actor_user_id="user-1",
was_on_time=None,
)
assert event.event_type == EVENT_UNCOMPLETED
assert event.was_on_time is None
return event
_with_db(tmp_path, "uncompleted-null.db")(_body)
def test_now_pins_occurred_at_utc(tmp_path) -> None:
async def _body(database, child, instance):
pinned = datetime.datetime(
2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc
)
event = await append_event(
database,
instance.id,
child.id,
EVENT_COMPLETED,
actor_source="user",
actor_user_id="user-1",
was_on_time=True,
now=pinned,
)
assert event.occurred_at == "2026-09-18T08:00:00+00:00"
return event
_with_db(tmp_path, "pinned-now.db")(_body)
# ---------------------------------------------------------------------------
# append-only: the module never exposes update/delete
# ---------------------------------------------------------------------------
def test_module_never_exposes_update_or_delete() -> None:
import custom_components.nestquest.completion as completion
public = {
name
for name, _ in inspect.getmembers(completion, inspect.isfunction)
if not name.startswith("_")
}
forbidden = {
name
for name in public
if name.startswith(
(
"update",
"delete",
"set",
"clear",
"remove",
"modify",
"edit",
"upsert",
)
)
}
assert forbidden == set(), (
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)
+50 -7
View File
@@ -545,7 +545,7 @@ def test_materialize_uses_single_presence_snapshot_mid_walk(tmp_path) -> None:
_with_db(tmp_path, "materialize-presence-snapshot.db")(_body)
def test_materialize_stores_snapshot_due_time_not_live(tmp_path) -> None:
def test_materialize_skips_stale_due_time_mid_walk(tmp_path) -> None:
async def _body(database):
children = ChildrenDao(database)
child = await children.create("Ada", NOW)
@@ -566,21 +566,64 @@ def test_materialize_stores_snapshot_due_time_not_live(tmp_path) -> None:
)
# The window's due_time is edited to 10:15 between the input
# snapshot and the insert. The walk must store the SNAPSHOT's
# 09:00, not the live 10:15 — the batch is governed entirely by
# the coherent snapshot it read.
# snapshot and the insert. The walk's snapshotted 09:00 no
# longer matches the live 10:15, so the tuple is SKIPPED rather
# than writing a due_time that has already been superseded.
count = await _materialize_with_change(
database, start_iso, end_iso, _edit_due_time
)
assert count == 3
assert count == 0
assert await QuestInstancesDao(database).list_by_date_range(
child.id, start_iso, end_iso
) == []
return count
_with_db(tmp_path, "materialize-stale-due-time.db")(_body)
def test_materialize_does_not_overwrite_regenerated_due_time(tmp_path) -> None:
async def _body(database):
children = ChildrenDao(database)
child = await children.create("Ada", NOW)
today = datetime.date.today()
start_iso = today.isoformat()
end_iso = (today + datetime.timedelta(days=2)).isoformat()
created = await create_quest_definition(
database,
"Daily chore",
ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
[child.id],
[("morning", "09:00")],
)
async def _edit_and_regenerate():
# A window-time edit + regeneration land after the stale walk
# read its input snapshot: the window moves to 10:15 and the
# regeneration upserts the newer due_time across the horizon.
await QuestDefinitionsDao(database).upsert_window(
created.definition.id, "morning", due_time="10:15"
)
await regenerate_for_definition(database, created.definition.id)
# The stale walk (snapshot due_time 09:00) then resumes. It must
# SKIP these tuples — its snapshotted 09:00 no longer matches the
# live 10:15 — so the regeneration's newer due_time survives and
# is NOT overwritten by the stale value.
count = await _materialize_with_change(
database, start_iso, end_iso, _edit_and_regenerate
)
assert count == 0
records = await QuestInstancesDao(database).list_by_date_range(
child.id, start_iso, end_iso
)
assert len(records) == 3
assert {r.due_time for r in records} == {"09:00"}
assert {r.due_time for r in records} == {"10:15"}
return records
_with_db(tmp_path, "materialize-snapshot-due-time.db")(_body)
_with_db(tmp_path, "materialize-regenerated-due-time.db")(_body)
def test_materialize_honours_overrides(tmp_path) -> None: