Implement core materialization walk (Feature 07)

custom_components/nestquest/dao_presence.py

@@ -276,4 +276,75 @@ class PresenceOverridesDao:
             "DELETE FROM presence_overrides WHERE id = ?",
             (override_id,),
         )
-        return result.rowcount > 0
+        return result.rowcount > 0
+
+
+async def load_snapshot(
+    database: NestQuestDatabase,
+    child_ids: list[int],
+    range_start: str,
+    range_end: str,
+) -> tuple[
+    dict[int, PresenceScheduleRecord],
+    dict[int, list[PresenceOverrideRecord]],
+]:
+    """Read schedules and overrides for ``child_ids`` in ONE transaction.
+
+    Returns ``(schedules, overrides)``:
+
+    - ``schedules`` maps ``child_id`` to its :class:`PresenceScheduleRecord`
+      for every child that HAS a schedule row.  A child absent from the
+      mapping has no schedule, i.e. is present every day (Feature 05).
+    - ``overrides`` maps ``child_id`` to that child's overrides overlapping
+      ``[range_start, range_end]`` (inclusive boundaries), ordered by start
+      date; a child with no matching override is absent from the mapping.
+
+    Both tables are read inside one BEGIN..COMMIT span under the
+    connection-scoped lock, so the returned pairing is a coherent snapshot
+    — a concurrent schedule upsert or override create cannot interleave
+    between the two reads.  Children are validated as existing up front so
+    an unknown ``child_id`` raises ValueError rather than being silently
+    read as "present every day", mirroring
+    :meth:`PresenceSchedulesDao.get_by_child`.
+    """
+    _validate_date(range_start, "range_start")
+    _validate_date(range_end, "range_end")
+    if range_end < range_start:
+        raise ValueError(
+            "range_end must be on or after range_start, got "
+            f"{range_end!r} < {range_start!r}"
+        )
+    children = sorted(set(child_ids))
+    if not children:
+        return {}, {}
+    placeholders = ",".join("?" for _ in children)
+    async with _connection_lock(database):
+        async with database.transaction():
+            existing_rows = await database.fetch_all(
+                f"SELECT id FROM children WHERE id IN ({placeholders})",
+                tuple(children),
+            )
+            existing = {row[0] for row in existing_rows}
+            unknown = sorted(set(children) - existing)
+            if unknown:
+                raise ValueError(f"child {unknown[0]} does not exist")
+            schedule_rows = await database.fetch_all(
+                f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
+                f"WHERE child_id IN ({placeholders})",
+                tuple(children),
+            )
+            override_rows = await database.fetch_all(
+                f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+                f"WHERE child_id IN ({placeholders}) AND end_date >= ? "
+                "AND start_date <= ? ORDER BY start_date",
+                tuple(children) + (range_start, range_end),
+            )
+    schedules = {
+        record.child_id: record
+        for record in map(_schedule_from_row, schedule_rows)
+    }
+    overrides: dict[int, list[PresenceOverrideRecord]] = {}
+    for row in override_rows:
+        record = _override_from_row(row)
+        overrides.setdefault(record.child_id, []).append(record)
+    return schedules, overrides

custom_components/nestquest/materialize.py

@@ -0,0 +1,164 @@
+"""The materialization walk (Feature 07 core).
+
+:func:`materialize` turns the schedule rules + custody presence of the
+active quest definitions into concrete ``quest_instances`` rows over a
+date range.  It is the pure walk over definitions x dates x assignees x
+windows; HA scheduling (day-rollover triggers) and skip-completed
+generation are separate later tasks and live elsewhere.
+
+The walk is deterministic and idempotent:
+
+- Every active definition is read with its decoded
+  :class:`~.recurrence.ScheduleRule`, assignees and windows through the
+  Feature 06 snapshot helpers, so each bundle is a coherent read.
+- Presence is snapshotted into an immutable
+  :class:`~.presence.PresenceEngine` from the schedules and overrides of
+  every assignee child, read in one locked transaction (see
+  :func:`~.dao_presence.load_snapshot`).
+- For each date in the range, each definition whose decoded rule
+  :func:`~.recurrence.occurs_on` on that date, each assignee who is
+  ``is_present`` on that date and each declared window, one instance is
+  upserted through :class:`~.dao_instances.QuestInstancesDao.upsert` with
+  the window's ``due_time`` snapshotted and a ``generated_at`` stamp
+  shared by the whole batch (one coherent time per run).
+
+The upsert is idempotent on (definition_id, child_id, due_date, window),
+so re-running the materialization over the same range never duplicates a
+row; skipped-completed handling is deliberately NOT done here.
+"""
+from __future__ import annotations
+
+import datetime
+
+from .dao_instances import QuestInstancesDao
+from .dao_presence import load_snapshot
+from .dao_rules import (
+    QuestDefinitionsDao,
+    _validate_date,
+    schedule_rule_from_storage,
+    schedule_rule_storage_from_record,
+)
+from .db import NestQuestDatabase
+from .presence import PresenceEngine, PresenceOverride, PresenceSchedule
+from .recurrence import ScheduleRule, occurs_on
+
+
+def _now_stamp() -> str:
+    """Return the batch's shared UTC second-precision generation stamp."""
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(
+        timespec="seconds"
+    )
+
+
+def _decode_rule(snapshot) -> ScheduleRule:
+    """Decode a snapshot's rule record back into a ScheduleRule.
+
+    The record carried by the snapshot is the one the definition
+    referenced at read time, so decoding it here (rather than re-reading
+    through ``ScheduleRulesDao``) preserves the coherence the snapshot
+    guarantees.
+    """
+    return schedule_rule_from_storage(
+        schedule_rule_storage_from_record(snapshot.rule)
+    )
+
+
+def _build_engine(
+    schedules_records,
+    overrides_records,
+) -> PresenceEngine:
+    """Convert raw presence records into an immutable PresenceEngine."""
+    schedules: dict[int, PresenceSchedule] = {}
+    for child_id, record in schedules_records.items():
+        schedules[child_id] = PresenceSchedule.decode(
+            child_id, record.anchor_date, record.pattern
+        )
+    overrides: dict[int, list[PresenceOverride]] = {}
+    for child_id, records in overrides_records.items():
+        overrides[child_id] = [
+            PresenceOverride(
+                record.child_id,
+                record.start_date,
+                record.end_date,
+                record.is_present,
+                record.note,
+            )
+            for record in records
+        ]
+    return PresenceEngine(schedules, overrides)
+
+
+async def materialize(
+    database: NestQuestDatabase,
+    start_date: str,
+    end_date: str,
+) -> int:
+    """Generate quest instances for the closed range [start_date, end_date].
+
+    ``start_date`` and ``end_date`` must be strict ISO calendar dates
+    (YYYY-MM-DD) with ``end_date`` on or after ``start_date``; anything
+    else raises ValueError naming the offending field.  Returns the number
+    of instances upserted (idempotent — a re-run for the same batch
+    refreshes the same rows, never duplicates them).
+
+    The active definitions and the presence inputs are each read as a
+    coherent snapshot, and the presence schedule/overrides are read under
+    one locked transaction so the walk sees a single stable view of who
+    is where on each date.
+    """
+    _validate_date(start_date, "start_date")
+    _validate_date(end_date, "end_date")
+    if end_date < start_date:
+        raise ValueError(
+            f"end_date must be on or after start_date, got "
+            f"{end_date!r} < {start_date!r}"
+        )
+
+    snapshots = await QuestDefinitionsDao(database).list_snapshots_active()
+    assignee_child_ids = sorted(
+        {
+            child.id
+            for snapshot in snapshots
+            for child in snapshot.assignees
+        }
+    )
+
+    schedules_records, overrides_records = await load_snapshot(
+        database, assignee_child_ids, start_date, end_date
+    )
+    engine = _build_engine(schedules_records, overrides_records)
+
+    definitions = [
+        (snapshot.definition.id, _decode_rule(snapshot),
+         snapshot.assignees, snapshot.windows)
+        for snapshot in snapshots
+    ]
+
+    generated_at = _now_stamp()
+    instances = QuestInstancesDao(database)
+
+    start = datetime.datetime.strptime(start_date, "%Y-%m-%d").date()
+    end = datetime.datetime.strptime(end_date, "%Y-%m-%d").date()
+
+    count = 0
+    cursor = start
+    while cursor <= end:
+        iso = cursor.isoformat()
+        for definition_id, rule, assignees, windows in definitions:
+            if not occurs_on(rule, cursor):
+                continue
+            for child in assignees:
+                if not engine.is_present(child.id, cursor):
+                    continue
+                for window in windows:
+                    await instances.upsert(
+                        definition_id,
+                        child.id,
+                        iso,
+                        generated_at,
+                        window=window.window,
+                        due_time=window.due_time,
+                    )
+                    count += 1
+        cursor += datetime.timedelta(days=1)
+    return count

tests/test_materialize.py

@@ -0,0 +1,288 @@
+"""Tests for materialize.py: the Feature 07 materialization walk."""
+from __future__ import annotations
+
+import asyncio
+import datetime
+
+import pytest
+
+from custom_components.nestquest.dao_children import ChildrenDao
+from custom_components.nestquest.dao_instances import QuestInstancesDao
+from custom_components.nestquest.dao_presence import PresenceSchedulesDao
+from custom_components.nestquest.db import NestQuestDatabase
+from custom_components.nestquest.materialize import materialize
+from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.quest_definitions import (
+    create_quest_definition,
+)
+from custom_components.nestquest.recurrence import RuleType, ScheduleRule
+
+
+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
+
+
+NOW = "2026-09-14T12:00:00+00:00"
+
+
+async def _prepare(path):
+    database = NestQuestDatabase(_make_hass_mock())
+    await database.open(path)
+    await apply_migrations(database)
+    return database
+
+
+def _with_db(tmp_path, name):
+    def _run_test(body):
+        async def _main():
+            database = await _prepare(tmp_path / name)
+            try:
+                return await body(database)
+            finally:
+                await database.close()
+
+        return _run(_main())
+
+    return _run_test
+
+
+def _future_monday() -> datetime.date:
+    """The Monday of next week (strictly future, all 28 days eligible)."""
+    today = datetime.date.today()
+    this_monday = today - datetime.timedelta(days=today.weekday())
+    return this_monday + datetime.timedelta(days=7)
+
+
+def _build_expected(start, def1_id, def2_id, a_id, b_id, c_id) -> set:
+    """Hand-derived expected (definition_id, child_id, window, due_date,
+    due_time) tuples over the four-week window.
+
+    Custody: A is present week 0 and 2 of the two-week cycle, absent
+    1 and 3; B is the mirror; C has no schedule (present every day).
+    """
+    expected: set = set()
+    start_dt = datetime.date.fromisoformat(start)
+    for offset in range(28):
+        day = start_dt + datetime.timedelta(days=offset)
+        iso = day.isoformat()
+        week = offset // 7
+        monday = day.weekday() == 0
+
+        # Def1: DAILY, assignees A + C, window morning due 09:00.
+        if week % 2 == 0:
+            expected.add((def1_id, a_id, "morning", iso, "09:00"))
+        expected.add((def1_id, c_id, "morning", iso, "09:00"))
+
+        # Def2: WEEKLY Monday, assignees B + C, morning 07:00 + evening 19:00.
+        if monday:
+            if week % 2 == 1:
+                expected.add((def2_id, b_id, "morning", iso, "07:00"))
+                expected.add((def2_id, b_id, "evening", iso, "19:00"))
+            expected.add((def2_id, c_id, "morning", iso, "07:00"))
+            expected.add((def2_id, c_id, "evening", iso, "19:00"))
+    return expected
+
+
+async def _collect_instances(database, child_ids, start, end) -> set:
+    dao = QuestInstancesDao(database)
+    collected = set()
+    for child_id in child_ids:
+        for record in await dao.list_by_date_range(child_id, start, end):
+            collected.add(
+                (
+                    record.definition_id,
+                    record.child_id,
+                    record.window,
+                    record.due_date,
+                    record.due_time,
+                )
+            )
+    return collected
+
+
+def test_materialize_two_custody_one_always_present(tmp_path) -> None:
+    async def _body(database):
+        children = ChildrenDao(database)
+        schedules = PresenceSchedulesDao(database)
+
+        a = await children.create("Ada", NOW)      # present weeks 0, 2
+        b = await children.create("Bo", NOW)       # present weeks 1, 3
+        c = await children.create("Cleo", NOW)     # no schedule: always present
+
+        start = _future_monday()
+        start_iso = start.isoformat()
+        end_iso = (start + datetime.timedelta(days=27)).isoformat()
+
+        await schedules.upsert_by_child(
+            a.id, 2, start_iso, "0,1,2,3,4,5,6|"
+        )
+        await schedules.upsert_by_child(
+            b.id, 2, start_iso, "|0,1,2,3,4,5,6"
+        )
+
+        def1 = await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
+            [a.id, c.id],
+            [("morning", "09:00")],
+        )
+        def2 = await create_quest_definition(
+            database,
+            "Weekly chore",
+            ScheduleRule(
+                rule_type=RuleType.WEEKLY,
+                weekday_set={0},
+                start_date=start_iso,
+            ),
+            [b.id, c.id],
+            [("morning", "07:00"), ("evening", "19:00")],
+        )
+
+        expected = _build_expected(
+            start_iso, def1.definition.id, def2.definition.id,
+            a.id, b.id, c.id,
+        )
+
+        count = await materialize(database, start_iso, end_iso)
+        assert count == len(expected)
+
+        actual = await _collect_instances(
+            database, (a.id, b.id, c.id), start_iso, end_iso
+        )
+        assert actual == expected
+        return count
+
+    _with_db(tmp_path, "materialize.db")(_body)
+
+
+def test_materialize_shares_one_generated_at_per_run(tmp_path) -> None:
+    async def _body(database):
+        children = ChildrenDao(database)
+        child = await children.create("Ada", NOW)
+        start = _future_monday()
+        start_iso = start.isoformat()
+        end_iso = (start + datetime.timedelta(days=6)).isoformat()
+        await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
+            [child.id],
+            ["morning"],
+        )
+        await materialize(database, start_iso, end_iso)
+        dao = QuestInstancesDao(database)
+        stamps = {
+            record.generated_at
+            for record in await dao.list_by_date_range(
+                child.id, start_iso, end_iso
+            )
+        }
+        assert len(stamps) == 1
+        return stamps
+
+    _with_db(tmp_path, "materialize-stamp.db")(_body)
+
+
+def test_materialize_is_idempotent(tmp_path) -> None:
+    async def _body(database):
+        children = ChildrenDao(database)
+        child = await children.create("Ada", NOW)
+        start = _future_monday()
+        start_iso = start.isoformat()
+        end_iso = (start + datetime.timedelta(days=6)).isoformat()
+        await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
+            [child.id],
+            ["morning"],
+        )
+        first = await materialize(database, start_iso, end_iso)
+        second = await materialize(database, start_iso, end_iso)
+        assert first == second == 7
+        return first
+
+    _with_db(tmp_path, "materialize-idempotent.db")(_body)
+
+
+def test_materialize_honours_overrides(tmp_path) -> None:
+    async def _body(database):
+        from custom_components.nestquest.dao_presence import (
+            PresenceOverridesDao,
+        )
+
+        children = ChildrenDao(database)
+        overrides = PresenceOverridesDao(database)
+        child = await children.create("Ada", NOW)
+        start = _future_monday()
+        start_iso = start.isoformat()
+        end_iso = (start + datetime.timedelta(days=6)).isoformat()
+        # No schedule means the child is present every day; a blocking
+        # override covering the whole week must still suppress every day.
+        await overrides.create(
+            child.id, start_iso, end_iso, False, note="away all week"
+        )
+        await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
+            [child.id],
+            ["morning"],
+        )
+        count = await materialize(database, start_iso, end_iso)
+        assert count == 0
+        return count
+
+    _with_db(tmp_path, "materialize-override.db")(_body)
+
+
+def test_materialize_rejects_malformed_or_inverted_bounds(tmp_path) -> None:
+    async def _body(database):
+        start = (_future_monday()).isoformat()
+        end = (datetime.date.fromisoformat(start)
+               + datetime.timedelta(days=1)).isoformat()
+        for bad in ("not-a-date", "2026-9-7", ""):
+            with pytest.raises(ValueError, match="start_date"):
+                await materialize(database, bad, end)
+            with pytest.raises(ValueError, match="end_date"):
+                await materialize(database, start, bad)
+        with pytest.raises(ValueError, match="end_date must be on or after"):
+            await materialize(database, end, start)
+        return None
+
+    _with_db(tmp_path, "materialize-bounds.db")(_body)
+
+
+def test_materialize_skips_inactive_definitions(tmp_path) -> None:
+    async def _body(database):
+        from custom_components.nestquest.quest_definitions import (
+            set_quest_definition_active,
+        )
+
+        children = ChildrenDao(database)
+        child = await children.create("Ada", NOW)
+        start = _future_monday()
+        start_iso = start.isoformat()
+        end_iso = (start + datetime.timedelta(days=6)).isoformat()
+        created = await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(rule_type=RuleType.DAILY, start_date=start_iso),
+            [child.id],
+            ["morning"],
+        )
+        await set_quest_definition_active(database, created.definition.id, False)
+        count = await materialize(database, start_iso, end_iso)
+        assert count == 0
+        return count
+
+    _with_db(tmp_path, "materialize-inactive.db")(_body)