test: derive occurred-at query date from the event stamp; capture generated_at at creation

Both comparisons now use the recorded value, never a fresh clock read,
so a midnight boundary mid-test cannot flake them.

custom_components/nestquest/dao_instances.py

@@ -0,0 +1,542 @@
+"""Typed DAO layer for task_instances and the append-only completion_events.
+
+All SQL for these tables lives in this module per the feature
+guardrails: callers get typed dataclasses back and never see raw rows
+or SQL.  Every method is async and runs through
+:class:`~.db.NestQuestDatabase`, so each statement executes on the HA
+executor and the event loop never blocks.
+
+Append-only policy (Feature 08, D-005): ``completion_events`` is
+strictly append-only.  This module is where that property is enforced
+mechanically — the completion-events DAO below exposes NO update or
+delete method at all; completions append, un-completions append a
+separate reversal event, and instance state derives from the latest
+event.  A package-wide guard test (bottom of the test module) keeps
+mutation SQL for this table out of every other module.
+
+Upsert semantics: ``TaskInstancesDao.upsert`` is idempotent on
+(definition_id, due_date) — re-running materialization for a date
+whose instance already exists updates nothing that matters
+(child_id/due_time are refreshed only in the degenerate re-generation
+case where they changed) and never duplicates a row.  The schema's
+UNIQUE(definition_id, due_date) is the last line of defense.
+
+``delete_future_uncompleted`` implements the Feature 06/07 rule that
+reassignment and schedule edits regenerate future instances: it
+removes only instances at or after the cutoff that have NO completion
+event, inside one transaction, so an instance completed mid-call can
+never be deleted.  Instances in the past are never touched (Feature 07
+guardrail: never delete history), and no method here deletes a single
+instance that has a completion event.
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+from .dao_children import _connection_lock
+from .dao_rules import _validate_date
+from .db import NestQuestDatabase
+
+#: Timestamp policy for completion_events.occurred_at: strict UTC
+#: ISO-8601 with explicit '+00:00' offset (module timestamp policy).
+#: One accepted shape bounds lexicographic range queries correctly, so
+#: the occurred-at scope does not guess at timestamp spellings.
+_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
+
+
+def _validate_utc_timestamp(value: str, field: str) -> None:
+    """Raise ValueError unless ``value`` is a strict UTC ISO-8601 stamp.
+
+    Same strictness policy as _validate_date: parse with the exact
+    format, then round-trip the parsed value against the input so
+    non-padded or re-ordered shapes are rejected.  The round-trip
+    strips the UTC offset (isoformat() omits it when the offset is
+    zero), so the suffix is appended before comparing.
+    """
+    try:
+        parsed = datetime.datetime.strptime(
+            value, _UTC_TIMESTAMP_FORMAT
+        )
+    except (TypeError, ValueError):
+        raise ValueError(
+            f"{field} must be a UTC ISO-8601 timestamp "
+            f"(YYYY-MM-DDTHH:MM:SS+00:00), got {value!r}"
+        ) from None
+    if parsed.isoformat() + "+00:00" != value:
+        raise ValueError(
+            f"{field} must be a strict UTC timestamp "
+            f"(YYYY-MM-DDTHH:MM:SS+00:00), got {value!r}"
+        )
+
+
+def _next_day_start(date_str: str) -> str:
+    """Return the UTC timestamp one second past ``date_str``'s last second.
+
+    Gives range queries an exact half-open upper bound without
+    fractional-second guessing.
+    """
+    day = datetime.date.fromisoformat(date_str)
+    next_day = day + datetime.timedelta(days=1)
+    return f"{next_day.isoformat()}T00:00:00+00:00"
+
+
+@dataclass(frozen=True)
+class TaskInstanceRecord:
+    """One row of ``task_instances``."""
+
+    id: int
+    definition_id: int
+    child_id: int
+    due_date: str
+    due_time: str | None
+    generated_at: str
+
+
+@dataclass(frozen=True)
+class CompletionEventRecord:
+    """One row of ``completion_events`` (append-only table)."""
+
+    id: int
+    instance_id: int
+    child_id: int
+    event_type: str
+    actor_source: str
+    actor_user_id: str | None
+    occurred_at: str
+    was_on_time: bool | None
+
+
+_INSTANCE_COLUMNS = (
+    "id, definition_id, child_id, due_date, due_time, generated_at"
+)
+_EVENT_COLUMNS = (
+    "id, instance_id, child_id, event_type, actor_source, actor_user_id, "
+    "occurred_at, was_on_time"
+)
+
+#: The only event types the append path accepts; the schema CHECK is
+#: the backstop, this is the DAO's typed front door.
+EVENT_COMPLETED = "completed"
+EVENT_UNCOMPLETED = "uncompleted"
+
+
+def _instance_from_row(row: tuple) -> TaskInstanceRecord:
+    return TaskInstanceRecord(
+        id=row[0],
+        definition_id=row[1],
+        child_id=row[2],
+        due_date=row[3],
+        due_time=row[4],
+        generated_at=row[5],
+    )
+
+
+def _event_from_row(row: tuple) -> CompletionEventRecord:
+    return CompletionEventRecord(
+        id=row[0],
+        instance_id=row[1],
+        child_id=row[2],
+        event_type=row[3],
+        actor_source=row[4],
+        actor_user_id=row[5],
+        occurred_at=row[6],
+        was_on_time=None if row[7] is None else bool(row[7]),
+    )
+
+
+class TaskInstancesDao:
+    """Typed async access to the ``task_instances`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def upsert(
+        self,
+        definition_id: int,
+        child_id: int,
+        due_date: str,
+        generated_at: str,
+        *,
+        due_time: str | None = None,
+    ) -> TaskInstanceRecord:
+        """Create the dated instance for (definition_id, due_date) idempotently.
+
+        Running materialization twice for the same definition/date
+        yields ONE row: the ON CONFLICT path refreshes the
+        generation-time snapshot columns (child_id, due_time) and
+        regenerates the stamp, but can never create a duplicate — the
+        schema UNIQUE(definition_id, due_date) backs this up.
+
+        Guardrails enforced here:
+
+        - ``due_date`` must be TODAY or later: instances are never
+          generated in the past (Feature 07).  The caller's
+          materialization horizon is future-dated by definition.
+        - An existing instance WITH a completion event is IMMUTABLE:
+          the conflict path must not rewrite its snapshot columns
+          (Feature 07/08).  The upsert refuses with ValueError in that
+          case — silently no-oping would mask a materialization bug.
+
+        The definition must exist (validated atomically under the
+        connection lock so a concurrent definition deactivation or
+        child deletion cannot slip between check and insert).
+        """
+        _validate_date(due_date, "due_date")
+        # Fail fast on obviously-past dates BEFORE queuing on the
+        # connection lock (a nice early error); the AUTHORITATIVE
+        # check runs after the lock is acquired, because a caller can
+        # wait on the lock across midnight — a date that was "today"
+        # at call time may be "yesterday" by the time the INSERT runs.
+        today = datetime.date.today().isoformat()
+        if due_date < today:
+            raise ValueError(
+                f"instances are never generated in the past: due_date "
+                f"{due_date!r} is before today {today!r}"
+            )
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                # Re-read "today" under the lock: this is the date the
+                # insert actually executes on, so the no-past rule
+                # holds across midnight rollovers.
+                today = datetime.date.today().isoformat()
+                if due_date < today:
+                    raise ValueError(
+                        f"instances are never generated in the past: "
+                        f"due_date {due_date!r} is before today "
+                        f"{today!r}"
+                    )
+                definition = await self._database.fetch_one(
+                    "SELECT child_id FROM task_definitions WHERE id = ?",
+                    (definition_id,),
+                )
+                if definition is None:
+                    raise ValueError(
+                        f"task definition {definition_id} does not exist"
+                    )
+                if definition[0] != child_id:
+                    raise ValueError(
+                        f"task definition {definition_id} is assigned to "
+                        f"child {definition[0]}, not {child_id}; instance "
+                        "must carry the definition's assignee"
+                    )
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                existing = await self._database.fetch_one(
+                    "SELECT 1 FROM completion_events "
+                    "WHERE instance_id = (SELECT id FROM task_instances "
+                    "WHERE definition_id = ? AND due_date = ?)",
+                    (definition_id, due_date),
+                )
+                if existing is not None:
+                    raise ValueError(
+                        f"instance for (definition {definition_id}, "
+                        f"due_date {due_date!r}) already has a completion "
+                        "event and is immutable; it cannot be regenerated"
+                    )
+                await self._database.execute(
+                    "INSERT INTO task_instances (definition_id, child_id, "
+                    "due_date, due_time, generated_at) "
+                    "VALUES (?, ?, ?, ?, ?) "
+                    "ON CONFLICT (definition_id, due_date) DO UPDATE SET "
+                    "child_id = excluded.child_id, "
+                    "due_time = excluded.due_time, "
+                    "generated_at = excluded.generated_at",
+                    (
+                        definition_id,
+                        child_id,
+                        due_date,
+                        due_time,
+                        generated_at,
+                    ),
+                )
+                instance = await self.get(definition_id, due_date)
+        assert instance is not None
+        return instance
+
+    async def get(
+        self, definition_id: int, due_date: str
+    ) -> TaskInstanceRecord | None:
+        """Return the instance for (definition_id, due_date), or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_INSTANCE_COLUMNS} FROM task_instances "
+            "WHERE definition_id = ? AND due_date = ?",
+            (definition_id, due_date),
+        )
+        return _instance_from_row(row) if row is not None else None
+
+    async def get_by_id(self, instance_id: int) -> TaskInstanceRecord | None:
+        """Return the instance with ``instance_id``, or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_INSTANCE_COLUMNS} FROM task_instances WHERE id = ?",
+            (instance_id,),
+        )
+        return _instance_from_row(row) if row is not None else None
+
+    async def list_by_child_and_date(
+        self, child_id: int, due_date: str
+    ) -> list[TaskInstanceRecord]:
+        """Return the child's instances due exactly on ``due_date``."""
+        _validate_date(due_date, "due_date")
+        rows = await self._database.fetch_all(
+            f"SELECT {_INSTANCE_COLUMNS} FROM task_instances "
+            "WHERE child_id = ? AND due_date = ? ORDER BY id",
+            (child_id, due_date),
+        )
+        return [_instance_from_row(row) for row in rows]
+
+    async def list_by_date_range(
+        self,
+        child_id: int,
+        range_start: str,
+        range_end: str,
+    ) -> list[TaskInstanceRecord]:
+        """Return the child's instances with due_date in the closed range."""
+        _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}"
+            )
+        rows = await self._database.fetch_all(
+            f"SELECT {_INSTANCE_COLUMNS} FROM task_instances "
+            "WHERE child_id = ? AND due_date >= ? AND due_date <= ? "
+            "ORDER BY due_date, id",
+            (child_id, range_start, range_end),
+        )
+        return [_instance_from_row(row) for row in rows]
+
+    async def delete_future_uncompleted(
+        self, definition_id: int, cutoff_date: str
+    ) -> int:
+        """Delete the definition's open instances at/after cutoff.
+
+        Implements regeneration after a definition edit or reassignment
+        (Features 06/07): only instances at or after the cutoff with NO
+        completion event are removed, inside one transaction — an
+        instance that gains a completion event mid-flight cannot be
+        deleted.  The cutoff cannot be backdated below today: "future"
+        is measured against TODAY (materialization regenerates the
+        rolling horizon from now), so a caller cannot use this to
+        rewrite past open instances either — the day-rollover missed
+        sweep (Feature 11) handles past-due instances instead.  Any
+        instance with a completion event is never touched, regardless
+        of its date.  Returns the number deleted.
+        """
+        _validate_date(cutoff_date, "cutoff_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                # "today" is read under the lock: the DELETE actually
+                # executes on this date, so a caller queued across
+                # midnight cannot delete instances that became past
+                # while it waited (backdating is clamped to the
+                # execution date, not the call date).
+                today = datetime.date.today().isoformat()
+                effective_cutoff = max(cutoff_date, today)
+                result = await self._database.execute(
+                    "DELETE FROM task_instances WHERE definition_id = ? "
+                    "AND due_date >= ? AND NOT EXISTS ("
+                    "  SELECT 1 FROM completion_events "
+                    "  WHERE instance_id = task_instances.id"
+                    ")",
+                    (definition_id, effective_cutoff),
+                )
+        return result.rowcount
+
+
+class CompletionEventsDao:
+    """Typed append-only access to the ``completion_events`` table.
+
+    APPEND-ONLY BY CONSTRUCTION: this class exposes ``append`` and the
+    three read methods below, and NOTHING else.  There is no update,
+    no delete, no upsert — completions and un-completions both arrive
+    through :meth:`append` as new rows, and history is immutable
+    (Feature 08 done-condition: no code path updates or deletes an
+    event).  The package-wide leak-guard test additionally fails if
+    mutation SQL for this table ever appears in any module.
+    """
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def append(
+        self,
+        instance_id: int,
+        child_id: int,
+        event_type: str,
+        actor_source: str,
+        occurred_at: str,
+        was_on_time: bool | None,
+        *,
+        actor_user_id: str | None = None,
+    ) -> CompletionEventRecord:
+        """Append one completion or un-completion event.
+
+        ``actor_source`` is 'user' (with ``actor_user_id`` set) or
+        'panel' (no user id — the tapped child is ``child_id``); the
+        actor-pair CHECK enforces this shape at the schema level.
+        ``occurred_at`` must be the module's one strict UTC shape
+        (YYYY-MM-DDTHH:MM:SS+00:00) so lexicographic range queries
+        stay exact.  ``was_on_time`` is required (True/False) for
+        completions; for un-completions it may be None or the reversed
+        completion's flag (Feature 08 still deciding).  The instance
+        and child must exist — validated atomically under the
+        connection lock.
+        """
+        if event_type not in (EVENT_COMPLETED, EVENT_UNCOMPLETED):
+            raise ValueError(
+                f"event_type must be '{EVENT_COMPLETED}' or "
+                f"'{EVENT_UNCOMPLETED}', got {event_type!r}"
+            )
+        if actor_source not in ("user", "panel"):
+            raise ValueError(
+                f"actor_source must be 'user' or 'panel', got "
+                f"{actor_source!r}"
+            )
+        if actor_source == "user" and not actor_user_id:
+            raise ValueError(
+                "actor_source 'user' requires actor_user_id"
+            )
+        if actor_source == "panel" and actor_user_id is not None:
+            raise ValueError(
+                "actor_source 'panel' must not carry actor_user_id"
+            )
+        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 "
+                f"{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)"
+            )
+        _validate_utc_timestamp(occurred_at, "occurred_at")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                instance = await self._database.fetch_one(
+                    "SELECT child_id FROM task_instances WHERE id = ?",
+                    (instance_id,),
+                )
+                if instance is None:
+                    raise ValueError(
+                        f"task instance {instance_id} does not exist"
+                    )
+                if instance[0] != child_id:
+                    raise ValueError(
+                        f"task instance {instance_id} belongs to child "
+                        f"{instance[0]}, not {child_id}"
+                    )
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                result = await self._database.execute(
+                    "INSERT INTO completion_events (instance_id, child_id, "
+                    "event_type, actor_source, actor_user_id, occurred_at, "
+                    "was_on_time) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        instance_id,
+                        child_id,
+                        event_type,
+                        actor_source,
+                        actor_user_id,
+                        occurred_at,
+                        None if was_on_time is None else int(was_on_time),
+                    ),
+                )
+                event = await self._database.fetch_one(
+                    f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+                    "WHERE id = ?",
+                    (result.lastrowid,),
+                )
+        assert event is not None
+        return _event_from_row(event)
+
+    async def list_by_instance(
+        self, instance_id: int
+    ) -> list[CompletionEventRecord]:
+        """Return every event for the instance, in append order."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+            "WHERE instance_id = ? ORDER BY id",
+            (instance_id,),
+        )
+        return [_event_from_row(row) for row in rows]
+
+    async def list_by_child_and_date_range(
+        self,
+        child_id: int,
+        range_start: str,
+        range_end: str,
+        *,
+        due_date_scope: bool = True,
+    ) -> list[CompletionEventRecord]:
+        """Return the child's events for instances due in the closed range.
+
+        Scopes by the INSTANCE's due date (the day the task was owed),
+        not the event's wall-clock timestamp: history reporting asks
+        "what happened to the tasks due that day" (Feature 13).  Set
+        ``due_date_scope=False`` to filter by ``occurred_at`` date
+        instead.  Ordered by instance, then event id.
+        """
+        _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}"
+            )
+        if due_date_scope:
+            predicate = (
+                "SELECT id FROM task_instances WHERE child_id = ? "
+                "AND due_date >= ? AND due_date <= ?"
+            )
+            parameters: list[object] = [child_id, range_start, range_end]
+        else:
+            # Occurred-at scope: occurred_at is validated to the one
+            # accepted UTC shape at append time, so half-open day
+            # bounds in that same shape are exact (no spelling drift).
+            occurred_start = f"{range_start}T00:00:00+00:00"
+            occurred_end = f"{range_end}T23:59:59+00:00"
+            query = (
+                f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+                "WHERE child_id = ? AND occurred_at >= ? "
+                "AND occurred_at < ? ORDER BY instance_id, id"
+            )
+            rows = await self._database.fetch_all(
+                query,
+                [
+                    child_id,
+                    occurred_start,
+                    _next_day_start(range_end),
+                ],
+            )
+            return [_event_from_row(row) for row in rows]
+        rows = await self._database.fetch_all(
+            f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+            f"WHERE instance_id IN ({predicate}) "
+            "ORDER BY instance_id, id",
+            tuple(parameters),
+        )
+        return [_event_from_row(row) for row in rows]
+
+    async def get_latest_for_instance(
+        self, instance_id: int
+    ) -> CompletionEventRecord | None:
+        """Return the instance's most recent event, or None if untouched.
+
+        Instance current state derives from this event (Feature 08):
+        'completed' means done, 'uncompleted' as the latest means open
+        again, None means never completed.
+        """
+        row = await self._database.fetch_one(
+            f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+            "WHERE instance_id = ? ORDER BY id DESC LIMIT 1",
+            (instance_id,),
+        )
+        return _event_from_row(row) if row is not None else None

custom_components/nestquest/dao_presence.py

@@ -0,0 +1,247 @@
+"""Typed DAO layer for the presence_schedules and presence_overrides tables.
+
+All SQL for these tables lives in this module per the feature
+guardrails: callers get typed dataclasses back and never see raw rows
+or SQL.  Every method is async and runs through
+:class:`~.db.NestQuestDatabase`, so each statement executes on the HA
+executor and the event loop never blocks.
+
+Semantics per the done-condition and Feature 05:
+
+- A child has AT MOST ONE presence schedule (schema UNIQUE); upserting
+  by child updates the existing row rather than raising.
+- A child with NO schedule row is present every day — the absence of a
+  row is meaningful state, expressed by :meth:`PresenceSchedulesDao.get_by_child`
+  returning None, never by an empty pattern row.
+- Overrides beat the pattern for their date range (that resolution is
+  the presence engine's job, Feature 05); the DAO only stores and
+  lists them.  A single-day override stores the same date as both
+  start and end (schema CHECK requires end >= start).
+
+Date arguments are validated as strict YYYY-MM-DD per the same policy
+the rules DAO applies: the schema's lexical CHECKs cannot prove
+calendar validity.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .dao_children import _connection_lock
+from .dao_rules import _UNSET, _validate_date
+from .db import NestQuestDatabase
+
+
+@dataclass(frozen=True)
+class PresenceScheduleRecord:
+    """One row of ``presence_schedules``."""
+
+    id: int
+    child_id: int
+    cycle_length_weeks: int
+    anchor_date: str
+    pattern: str
+
+
+@dataclass(frozen=True)
+class PresenceOverrideRecord:
+    """One row of ``presence_overrides``."""
+
+    id: int
+    child_id: int
+    start_date: str
+    end_date: str
+    is_present: bool
+    note: str | None
+
+
+_SCHEDULE_COLUMNS = (
+    "id, child_id, cycle_length_weeks, anchor_date, pattern"
+)
+_OVERRIDE_COLUMNS = (
+    "id, child_id, start_date, end_date, is_present, note"
+)
+
+
+def _schedule_from_row(row: tuple) -> PresenceScheduleRecord:
+    return PresenceScheduleRecord(
+        id=row[0],
+        child_id=row[1],
+        cycle_length_weeks=row[2],
+        anchor_date=row[3],
+        pattern=row[4],
+    )
+
+
+def _override_from_row(row: tuple) -> PresenceOverrideRecord:
+    return PresenceOverrideRecord(
+        id=row[0],
+        child_id=row[1],
+        start_date=row[2],
+        end_date=row[3],
+        is_present=bool(row[4]),
+        note=row[5],
+    )
+
+
+class PresenceSchedulesDao:
+    """Typed async access to the ``presence_schedules`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def upsert_by_child(
+        self,
+        child_id: int,
+        cycle_length_weeks: int,
+        anchor_date: str,
+        pattern: str,
+    ) -> PresenceScheduleRecord:
+        """Set the child's presence schedule, replacing any existing one.
+
+        Upsert semantics are the done-condition: a second schedule for
+        the same child updates the existing row rather than raising.
+        Runs under the connection lock so a concurrent upsert/delete
+        for the same child serializes instead of colliding on the
+        schema's UNIQUE(child_id).  Pattern validity (segment shape,
+        segment count = cycle_length_weeks) is enforced by the schema
+        CHECKs; the child must exist (FK) — validated atomically here
+        so a deleted child cannot pass a stale check.
+        """
+        _validate_date(anchor_date, "anchor_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                await self._database.execute(
+                    "INSERT INTO presence_schedules (child_id, "
+                    "cycle_length_weeks, anchor_date, pattern) "
+                    "VALUES (?, ?, ?, ?) "
+                    "ON CONFLICT (child_id) DO UPDATE SET "
+                    "cycle_length_weeks = excluded.cycle_length_weeks, "
+                    "anchor_date = excluded.anchor_date, "
+                    "pattern = excluded.pattern",
+                    (child_id, cycle_length_weeks, anchor_date, pattern),
+                )
+                schedule = await self.get_by_child(child_id)
+        assert schedule is not None
+        return schedule
+
+    async def get_by_child(
+        self, child_id: int
+    ) -> PresenceScheduleRecord | None:
+        """Return the child's schedule, or None when the child has none.
+
+        None is meaningful and UNAMBIGUOUS here: the child exists and
+        has no schedule row, i.e. the child is present every day
+        (Feature 05 guardrail).  An unknown child id raises ValueError
+        instead of returning None, because "nonexistent child" must
+        never be silently read as "present every day".
+        """
+        child = await self._database.fetch_one(
+            "SELECT 1 FROM children WHERE id = ?", (child_id,)
+        )
+        if child is None:
+            raise ValueError(f"child {child_id} does not exist")
+        row = await self._database.fetch_one(
+            f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
+            "WHERE child_id = ?",
+            (child_id,),
+        )
+        return _schedule_from_row(row) if row is not None else None
+
+    async def delete(self, child_id: int) -> bool:
+        """Remove the child's schedule; True if a row was removed.
+
+        After deletion the child is present every day (no row means
+        no restriction).  Deleting a schedule the child never had
+        returns False.
+        """
+        result = await self._database.execute(
+            "DELETE FROM presence_schedules WHERE child_id = ?",
+            (child_id,),
+        )
+        return result.rowcount > 0
+
+
+class PresenceOverridesDao:
+    """Typed async access to the ``presence_overrides`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def create(
+        self,
+        child_id: int,
+        start_date: str,
+        end_date: str,
+        is_present: bool,
+        *,
+        note: str | None = None,
+    ) -> PresenceOverrideRecord:
+        """Insert one override and return the record as stored.
+
+        The child must exist (validated atomically under the
+        connection lock).  Date shape is validated strictly, and the
+        schema CHECK rejects end < start.
+        """
+        _validate_date(start_date, "start_date")
+        _validate_date(end_date, "end_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                result = await self._database.execute(
+                    "INSERT INTO presence_overrides (child_id, "
+                    "start_date, end_date, is_present, note) "
+                    "VALUES (?, ?, ?, ?, ?)",
+                    (child_id, start_date, end_date, int(is_present), note),
+                )
+                override = await self._database.fetch_one(
+                    f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+                    "WHERE id = ?",
+                    (result.lastrowid,),
+                )
+        assert override is not None
+        return _override_from_row(override)
+
+    async def list_by_child_and_range(
+        self,
+        child_id: int,
+        range_start: str,
+        range_end: str,
+    ) -> list[PresenceOverrideRecord]:
+        """Return the child's overrides overlapping [range_start, range_end].
+
+        An override overlaps the range when it ends on or after the
+        range starts and starts on or before the range ends (inclusive
+        boundary dates, matching the storage model where overrides are
+        closed date ranges).  Ordered by start date.
+        """
+        _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}"
+            )
+        rows = await self._database.fetch_all(
+            f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+            "WHERE child_id = ? AND end_date >= ? AND start_date <= ? "
+            "ORDER BY start_date",
+            (child_id, range_start, range_end),
+        )
+        return [_override_from_row(row) for row in rows]
+
+    async def delete(self, override_id: int) -> bool:
+        """Remove one override by id; True if a row was removed."""
+        result = await self._database.execute(
+            "DELETE FROM presence_overrides WHERE id = ?",
+            (override_id,),
+        )
+        return result.rowcount > 0

tests/test_dao_children.py

@@ -481,12 +481,18 @@ def test_children_and_admin_sql_lives_only_in_dao_module() -> None:
         "custom_components/nestquest/dao_rules.py",  # validates child
         # activeness on assignment (FK to children, done-condition
         # 'validates that the assigned child is active')
+        "custom_components/nestquest/dao_presence.py",  # validates the
+        # schedule/override child exists before writing (same FK shape
+        # as dao_rules: one existence SELECT per write)
+        "custom_components/nestquest/dao_instances.py",  # validates the
+        # instance/event child exists before writing (same FK shape)
         "custom_components/nestquest/schema.py",  # declares the DDL
         "custom_components/nestquest/migrations.py",  # applies the DDL
         "tests/test_schema.py",  # tests the DDL
         "tests/test_migrations.py",  # tests migration application
         "tests/test_dao_children.py",  # this file, scanned separately
         "tests/test_dao_rules.py",  # rules/definitions guard, own scope
+        "tests/test_dao_presence.py",  # presence guard, own scope
     }
     sql_pattern = re.compile(
         r"(FROM|INTO|UPDATE|DELETE\s+FROM|JOIN)\s+"

tests/test_dao_presence.py

@@ -0,0 +1,622 @@
+"""Tests for dao_presence.py: presence schedules and overrides DAO."""
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+
+import pytest
+
+from custom_components.nestquest.dao_children import ChildrenDao
+from custom_components.nestquest.dao_presence import (
+    PresenceOverrideRecord,
+    PresenceOverridesDao,
+    PresenceScheduleRecord,
+    PresenceSchedulesDao,
+)
+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
+
+
+NOW = "2026-09-14T12:00:00+00:00"
+
+
+async def _prepare(path) -> tuple:
+    database = NestQuestDatabase(_make_hass_mock())
+    await database.open(path)
+    await apply_migrations(database)
+    schedules = PresenceSchedulesDao(database)
+    overrides = PresenceOverridesDao(database)
+    children = ChildrenDao(database)
+    child = await children.create("Ada", NOW)
+    return database, schedules, overrides, children, child
+
+
+def _with_db(tmp_path, name):
+    def _run_test(body):
+        async def _main():
+            database, schedules, overrides, children, child = await _prepare(
+                tmp_path / name
+            )
+            try:
+                return await body(
+                    database, schedules, overrides, children, child
+                )
+            finally:
+                await database.close()
+
+        return _run(_main())
+
+    return _run_test
+
+
+# ---------------------------------------------------------------------------
+# presence_schedules: upsert by child
+# ---------------------------------------------------------------------------
+
+
+def test_upsert_creates_then_updates_same_row(tmp_path) -> None:
+    """Second upsert for the same child UPDATES, not raises."""
+    async def _body(database, schedules, overrides, children, child):
+        first = await schedules.upsert_by_child(
+            child.id, 2, "2026-09-07", "0,2,4|1,3"
+        )
+        assert isinstance(first, PresenceScheduleRecord)
+        assert first.child_id == child.id
+        second = await schedules.upsert_by_child(
+            child.id, 2, "2026-09-14", "1,3|0,2,4"
+        )
+        assert second.id == first.id, "upsert must reuse the existing row"
+        fetched = await schedules.get_by_child(child.id)
+        assert fetched.anchor_date == "2026-09-14"
+        assert fetched.pattern == "1,3|0,2,4"
+        rows = await database.fetch_one(
+            "SELECT COUNT(*) FROM presence_schedules"
+        )
+        assert rows == (1,)
+        return second
+
+    _with_db(tmp_path, "upsert.db")(_body)
+
+
+def test_upsert_typed_record_fields(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        record = await schedules.upsert_by_child(
+            child.id, 4, "2026-09-07", "0|1|2|3"
+        )
+        assert record.id == 1
+        assert record.child_id == child.id
+        assert record.cycle_length_weeks == 4
+        assert record.anchor_date == "2026-09-07"
+        assert record.pattern == "0|1|2|3"
+        return record
+
+    _with_db(tmp_path, "upsert-fields.db")(_body)
+
+
+def test_upsert_unknown_child_raises_value_error(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        with pytest.raises(ValueError, match="does not exist"):
+            await schedules.upsert_by_child(
+                999, 2, "2026-09-07", "0,2|1,3"
+            )
+        return None
+
+    _with_db(tmp_path, "upsert-bad-child.db")(_body)
+
+
+def test_upsert_malformed_anchor_date_raises(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        for bad in ("not-a-date", "2026-9-7", "2026-13-01", ""):
+            with pytest.raises(ValueError, match="YYYY-MM-DD"):
+                await schedules.upsert_by_child(child.id, 2, bad, "0|1")
+        return None
+
+    _with_db(tmp_path, "upsert-bad-date.db")(_body)
+
+
+def test_upsert_malformed_pattern_rejected_by_schema(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        with pytest.raises(sqlite3.IntegrityError, match="CHECK"):
+            await schedules.upsert_by_child(
+                child.id, 2, "2026-09-07", "0,2"
+            )
+        return None
+
+    _with_db(tmp_path, "upsert-bad-pattern.db")(_body)
+
+
+def test_upsert_two_children_have_distinct_rows(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        other = await children.create("Bo", NOW)
+        await schedules.upsert_by_child(child.id, 2, "2026-09-07", "0,2|1,3")
+        await schedules.upsert_by_child(other.id, 2, "2026-09-07", "1,3|0,2")
+        mine = await schedules.get_by_child(child.id)
+        theirs = await schedules.get_by_child(other.id)
+        assert mine.id != theirs.id
+        assert mine.pattern == "0,2|1,3"
+        assert theirs.pattern == "1,3|0,2"
+        return mine
+
+    _with_db(tmp_path, "upsert-two-children.db")(_body)
+
+
+def test_upsert_concurrent_same_child_serializes(tmp_path) -> None:
+    """Racing upserts for one child both succeed; exactly one row.
+
+    Deterministic interleaving: a controllable executor gates task A's
+    job AFTER it has acquired the connection lock and begun its
+    transaction, so task B is created while A provably owns the
+    transaction and must queue on the lock.  Both upserts land, and
+    the table holds exactly one row (the ON CONFLICT upsert, not two
+    plain INSERTs, is what avoids a UNIQUE violation).
+    """
+    async def _main():
+        from unittest.mock import MagicMock
+
+        hass = MagicMock()
+        # Gate exactly ONE job: the first _fetch_one issued after
+        # arming, which is task A's child-existence SELECT inside its
+        # transaction.  The transaction's BEGIN runs first and is NOT
+        # gated, so when the gated fetch signals, BEGIN has executed
+        # and SQLite is inside the open transaction (A holds the
+        # connection lock from BEGIN until commit).  Everything before
+        # arming (open, migrations, child create)
+        # and everything after (B's jobs, A's remaining jobs, reads)
+        # pass straight through.
+        armed = {"active": False, "gated": False}
+        gate_open = asyncio.Event()
+        a_started = asyncio.Event()
+
+        async def _gated_executor(fn, *args):
+            # Gate the SECOND gated-window job: the first is the
+            # transaction's BEGIN (submitted and awaited by
+            # transaction() before upsert_by_child's child-SELECT
+            # runs).  Pausing the child-existence SELECT proves the
+            # BEGIN has EXECUTED — SQLite is actually inside the open
+            # transaction, with A holding the connection lock — when
+            # task B gets scheduled and must queue.
+            if armed["active"]:
+                name = getattr(fn, "__name__", "")
+                if name == "_fetch_one" and not armed["gated"]:
+                    armed["gated"] = True
+                    a_started.set()
+                    await gate_open.wait()
+            return fn(*args)
+
+        hass.async_add_executor_job = _gated_executor
+        database = NestQuestDatabase(hass)
+        await database.open(tmp_path / "upsert-race.db")
+        try:
+            await apply_migrations(database)
+            children = ChildrenDao(database)
+            schedules = PresenceSchedulesDao(database)
+            child = await children.create("Ada", NOW)
+
+            armed["active"] = True
+            task_a = asyncio.ensure_future(
+                schedules.upsert_by_child(
+                    child.id, 2, "2026-09-07", "0,2|1,3"
+                )
+            )
+            # Wait until task A's child-existence SELECT (inside its
+            # open transaction, BEGIN already executed) is paused, then
+            # schedule task B so it must queue behind the open
+            # transaction.
+            await a_started.wait()
+            armed["active"] = False
+            task_b = asyncio.ensure_future(
+                schedules.upsert_by_child(
+                    child.id, 2, "2026-09-14", "1,3|0,2"
+                )
+            )
+            await asyncio.sleep(0)
+            # Release A; B's upsert must wait for A's commit and then
+            # land as the ON CONFLICT update path.
+            gate_open.set()
+            record_a, record_b = await asyncio.gather(task_a, task_b)
+            assert record_a.id == record_b.id
+            fetched = await schedules.get_by_child(child.id)
+            assert fetched is not None
+            rows = await database.fetch_one(
+                "SELECT COUNT(*) FROM presence_schedules"
+            )
+            assert rows == (1,)
+            return fetched
+        finally:
+            await database.close()
+
+    fetched = _run(_main())
+    assert fetched.pattern in {"0,2|1,3", "1,3|0,2"}
+
+
+# ---------------------------------------------------------------------------
+# presence_schedules: get / delete
+# ---------------------------------------------------------------------------
+
+
+def test_get_by_child_missing_schedule_returns_none(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        return await schedules.get_by_child(child.id)
+
+    assert _with_db(tmp_path, "get-none.db")(_body) is None
+
+
+def test_get_by_child_unknown_child_raises(tmp_path) -> None:
+    """None must mean ONLY 'no schedule row': an unknown child id is a
+    caller bug, and silently reading a nonexistent child as 'present
+    every day' would be wrong — so get raises instead.
+    """
+    async def _body(database, schedules, overrides, children, child):
+        with pytest.raises(ValueError, match="does not exist"):
+            await schedules.get_by_child(999)
+        return None
+
+    _with_db(tmp_path, "get-unknown.db")(_body)
+
+
+def test_delete_removes_and_returns_true_then_false(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        await schedules.upsert_by_child(child.id, 2, "2026-09-07", "0,2|1,3")
+        assert await schedules.delete(child.id) is True
+        assert await schedules.get_by_child(child.id) is None
+        assert await schedules.delete(child.id) is False
+        return None
+
+    _with_db(tmp_path, "delete.db")(_body)
+
+
+def test_delete_child_without_schedule_returns_false(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        return await schedules.delete(child.id)
+
+    assert _with_db(tmp_path, "delete-none.db")(_body) is False
+
+
+def test_delete_then_upsert_creates_fresh_row(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        first = await schedules.upsert_by_child(
+            child.id, 2, "2026-09-07", "0,2|1,3"
+        )
+        await schedules.delete(child.id)
+        second = await schedules.upsert_by_child(
+            child.id, 2, "2026-09-07", "0,2|1,3"
+        )
+        assert second.id != first.id
+        return second
+
+    _with_db(tmp_path, "delete-recreate.db")(_body)
+
+
+# ---------------------------------------------------------------------------
+# presence_overrides: create / list / delete
+# ---------------------------------------------------------------------------
+
+
+def test_override_create_returns_typed_record(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        record = await overrides.create(
+            child.id, "2026-12-21", "2027-01-04", False,
+            note="Holiday abroad",
+        )
+        assert isinstance(record, PresenceOverrideRecord)
+        assert record.child_id == child.id
+        assert record.start_date == "2026-12-21"
+        assert record.end_date == "2027-01-04"
+        assert record.is_present is False
+        assert record.note == "Holiday abroad"
+        return record
+
+    _with_db(tmp_path, "override-create.db")(_body)
+
+
+def test_override_create_single_day_same_start_and_end(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        record = await overrides.create(
+            child.id, "2026-09-14", "2026-09-14", True
+        )
+        assert record.start_date == record.end_date
+        assert record.is_present is True
+        assert record.note is None
+        return record
+
+    _with_db(tmp_path, "override-single-day.db")(_body)
+
+
+def test_override_create_unknown_child_raises(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        with pytest.raises(ValueError, match="does not exist"):
+            await overrides.create(
+                999, "2026-09-14", "2026-09-14", True
+            )
+        return None
+
+    _with_db(tmp_path, "override-bad-child.db")(_body)
+
+
+def test_override_create_malformed_dates_raise(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        for bad in ("not-a-date", "2026-9-14", ""):
+            with pytest.raises(ValueError, match="YYYY-MM-DD"):
+                await overrides.create(child.id, bad, "2026-09-14", True)
+            with pytest.raises(ValueError, match="YYYY-MM-DD"):
+                await overrides.create(child.id, "2026-09-14", bad, True)
+        return None
+
+    _with_db(tmp_path, "override-bad-dates.db")(_body)
+
+
+def test_override_end_before_start_rejected_by_schema(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        with pytest.raises(sqlite3.IntegrityError, match="CHECK"):
+            await overrides.create(
+                child.id, "2026-09-14", "2026-09-13", True
+            )
+        return None
+
+    _with_db(tmp_path, "override-end-before-start.db")(_body)
+
+
+def test_override_list_by_child_and_range_filters_correctly(
+    tmp_path,
+) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        await overrides.create(
+            child.id, "2026-09-01", "2026-09-05", False, note="before"
+        )
+        inside = await overrides.create(
+            child.id, "2026-09-10", "2026-09-12", False, note="inside"
+        )
+        overlapping = await overrides.create(
+            child.id, "2026-09-20", "2026-09-25", True, note="overlap"
+        )
+        after = await overrides.create(
+            child.id, "2026-10-01", "2026-10-02", False, note="after"
+        )
+        found = await overrides.list_by_child_and_range(
+            child.id, "2026-09-09", "2026-09-22"
+        )
+        assert [r.id for r in found] == [inside.id, overlapping.id]
+        # Inclusive boundaries: a range touching the override's edges
+        # still matches.
+        edge = await overrides.list_by_child_and_range(
+            child.id, "2026-09-20", "2026-09-20"
+        )
+        assert [r.id for r in edge] == [overlapping.id]
+        return found
+
+    _with_db(tmp_path, "override-list-range.db")(_body)
+
+
+def test_override_list_orders_by_start_date(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        late = await overrides.create(
+            child.id, "2026-09-20", "2026-09-21", True
+        )
+        early = await overrides.create(
+            child.id, "2026-09-10", "2026-09-11", False
+        )
+        found = await overrides.list_by_child_and_range(
+            child.id, "2026-09-01", "2026-09-30"
+        )
+        assert [r.id for r in found] == [early.id, late.id]
+        return found
+
+    _with_db(tmp_path, "override-list-order.db")(_body)
+
+
+def test_override_list_per_child_isolation(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        other = await children.create("Bo", NOW)
+        await overrides.create(child.id, "2026-09-10", "2026-09-11", True)
+        await overrides.create(other.id, "2026-09-10", "2026-09-11", False)
+        mine = await overrides.list_by_child_and_range(
+            child.id, "2026-09-01", "2026-09-30"
+        )
+        assert len(mine) == 1
+        assert mine[0].is_present is True
+        return mine
+
+    _with_db(tmp_path, "override-isolation.db")(_body)
+
+
+def test_override_list_malformed_range_raises(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        with pytest.raises(ValueError, match="YYYY-MM-DD"):
+            await overrides.list_by_child_and_range(
+                child.id, "oops", "2026-09-30"
+            )
+        with pytest.raises(ValueError, match="on or after"):
+            await overrides.list_by_child_and_range(
+                child.id, "2026-09-30", "2026-09-01"
+            )
+        return None
+
+    _with_db(tmp_path, "override-list-bad-range.db")(_body)
+
+
+def test_override_list_unknown_child_returns_empty(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        return await overrides.list_by_child_and_range(
+            999, "2026-09-01", "2026-09-30"
+        )
+
+    assert _with_db(tmp_path, "override-list-unknown.db")(_body) == []
+
+
+def test_override_delete_round_trip(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        record = await overrides.create(
+            child.id, "2026-09-10", "2026-09-11", True
+        )
+        assert await overrides.delete(record.id) is True
+        found = await overrides.list_by_child_and_range(
+            child.id, "2026-09-01", "2026-09-30"
+        )
+        assert found == []
+        assert await overrides.delete(record.id) is False
+        return None
+
+    _with_db(tmp_path, "override-delete.db")(_body)
+
+
+def test_override_delete_missing_returns_false(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        return await overrides.delete(999)
+
+    assert _with_db(tmp_path, "override-delete-missing.db")(_body) is False
+
+
+def test_override_delete_leaves_other_overrides(tmp_path) -> None:
+    async def _body(database, schedules, overrides, children, child):
+        first = await overrides.create(
+            child.id, "2026-09-10", "2026-09-11", True
+        )
+        second = await overrides.create(
+            child.id, "2026-09-20", "2026-09-21", False
+        )
+        assert await overrides.delete(first.id) is True
+        found = await overrides.list_by_child_and_range(
+            child.id, "2026-09-01", "2026-09-30"
+        )
+        assert [r.id for r in found] == [second.id]
+        return found
+
+    _with_db(tmp_path, "override-delete-others.db")(_body)
+
+
+def test_schedule_and_override_independent_for_same_child(tmp_path) -> None:
+    """Deleting the schedule does not touch overrides and vice versa."""
+    async def _body(database, schedules, overrides, children, child):
+        await schedules.upsert_by_child(child.id, 2, "2026-09-07", "0,2|1,3")
+        override = await overrides.create(
+            child.id, "2026-09-10", "2026-09-11", True
+        )
+        assert await schedules.delete(child.id) is True
+        found = await overrides.list_by_child_and_range(
+            child.id, "2026-09-01", "2026-09-30"
+        )
+        assert [r.id for r in found] == [override.id]
+        return found
+
+    _with_db(tmp_path, "independent.db")(_body)
+
+
+# ---------------------------------------------------------------------------
+# No SQL for these tables outside the DAO module
+# ---------------------------------------------------------------------------
+
+
+def test_presence_sql_lives_only_in_dao_module() -> None:
+    """Guardrail: presence_schedules/presence_overrides SQL may appear
+    only in the DAO module (and the schema DDL declarations).
+    RECURSIVE scan of package and tests, FROM/INTO/UPDATE/DELETE FROM/
+    JOIN pattern, with exact repo-relative exclusions justified by
+    role: schema.py declares the DDL, migrations.py applies it, and
+    the test files for exactly those layers verify DDL, not data
+    paths.
+    """
+    import re
+    from pathlib import Path
+
+    package = Path(
+        __import__(
+            "custom_components.nestquest", fromlist=["__file__"]
+        ).__file__
+    ).parent
+    repo_root = package.parent.parent
+    scan_roots = [package, repo_root / "tests"]
+
+    allowed = {
+        "custom_components/nestquest/dao_presence.py",  # this DAO
+        "custom_components/nestquest/schema.py",  # declares the DDL
+        "custom_components/nestquest/migrations.py",  # applies the DDL
+        "tests/test_schema.py",  # tests the DDL
+        "tests/test_migrations.py",  # tests migration application
+        "tests/test_dao_presence.py",  # this file, scanned separately
+    }
+    sql_pattern = re.compile(
+        r"(FROM|INTO|UPDATE|DELETE\s+FROM|JOIN)\s+[`'\"]*(\[)?"
+        r"(presence_schedules|presence_overrides)\b",
+        re.IGNORECASE,
+    )
+    offenders: list[str] = []
+    for root in scan_roots:
+        for py in sorted(root.rglob("*.py")):
+            relative = py.relative_to(repo_root).as_posix()
+            if relative in allowed:
+                continue
+            if sql_pattern.search(py.read_text()):
+                offenders.append(relative)
+    assert offenders == [], (
+        f"SQL touching presence_schedules/presence_overrides leaked "
+        f"into: {offenders}"
+    )
+
+
+def test_dao_presence_test_file_uses_dao_not_raw_table_sql() -> None:
+    """This test module must exercise the DAO, not raw SQL, for these
+    tables.  Exemptions are EXACT lines, not whole-function spans: the
+    two single-statement COUNT(*) row probes (the only honest way to
+    prove 'exactly one row exists' without a listing method) and the
+    guard functions' own regex spans.  Any other raw SQL added anywhere
+    in this file fails the guard.
+    """
+    import ast
+    import re
+    from pathlib import Path
+
+    path = Path(__file__)
+    text = path.read_text()
+    lines = text.splitlines(keepends=True)
+    tree = ast.parse(text)
+    guard_names = {
+        "test_presence_sql_lives_only_in_dao_module",
+        "test_dao_presence_test_file_uses_dao_not_raw_table_sql",
+    }
+    excluded: set[int] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.name in guard_names:
+            excluded.update(
+                range(node.lineno, (node.end_lineno or node.lineno) + 1)
+            )
+            continue
+        # Narrow probe exemption: only the string-literal line holding
+        # the sanctioned COUNT(*) query, not the enclosing function.
+        for sub in ast.walk(node):
+            if (
+                isinstance(sub, ast.Constant)
+                and isinstance(sub.value, str)
+                and sub.value.strip()
+                == "SELECT COUNT(*) FROM presence_schedules"
+                and sub.lineno is not None
+            ):
+                excluded.add(sub.lineno)
+
+    remaining = "".join(
+        line
+        for number, line in enumerate(lines, start=1)
+        if number not in excluded
+    )
+    sql_pattern = re.compile(
+        r"(SELECT\s[^\"']*?FROM|INSERT\s+INTO|UPDATE|DELETE\s+FROM|"
+        r"FROM|JOIN)\s+[`'\"]*(\[)?(presence_schedules|presence_overrides)"
+        r"\b",
+        re.IGNORECASE,
+    )
+    assert sql_pattern.search(remaining) is None, (
+        "tests must go through the DAO, not raw SQL, for these tables"
+    )

tests/test_dao_rules.py

@@ -789,15 +789,15 @@ def test_rules_and_definitions_sql_lives_only_in_dao_module() -> None:
 
     allowed = {
         "custom_components/nestquest/dao_rules.py",  # this DAO
+        "custom_components/nestquest/dao_instances.py",  # validates the
+        # definition exists + fetches its assignee before generating an
+        # instance (the instance must snapshot the definition's child)
         "custom_components/nestquest/schema.py",  # declares the DDL
         "custom_components/nestquest/migrations.py",  # applies the DDL
         "tests/test_schema.py",  # tests the DDL
         "tests/test_migrations.py",  # tests migration application
         "tests/test_dao_rules.py",  # this file, scanned separately
-        # dao_children.py is NOT exempt: it holds no SQL for these
-        # tables (its FK reference check names task_definitions only
-        # inside delete_if_unreferenced's comment-free SQL? No — that
-        # lives HERE in dao_rules).  Any future leak there must fail.
+        "tests/test_dao_instances.py",  # instances guard, own scope
     }
     sql_pattern = re.compile(
         r"(FROM|INTO|UPDATE|DELETE\s+FROM|JOIN)\s+[`'\"]*(\[)?"
@@ -818,6 +818,50 @@ def test_rules_and_definitions_sql_lives_only_in_dao_module() -> None:
     )
 
 
+def test_dao_instances_test_file_uses_dao_not_raw_rules_sql() -> None:
+    """Compensating self-scan for the test_dao_instances.py exemption:
+    that file may query task_instances/completion_events raw (its own
+    guard's scope) but must go through the DAO for schedule_rules and
+    task_definitions, except its single sanctioned definition-create
+    helper usage and guard spans.
+    """
+    import ast
+    import re
+    from pathlib import Path
+
+    instances_test = Path(__file__).parent / "test_dao_instances.py"
+    text = instances_test.read_text()
+    lines = text.splitlines(keepends=True)
+    tree = ast.parse(text)
+    guard_names = {
+        "test_rules_and_definitions_sql_lives_only_in_dao_module",
+        "test_no_mutation_sql_for_completion_events_anywhere",
+    }
+    excluded: set[int] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.name in guard_names:
+            excluded.update(
+                range(node.lineno, (node.end_lineno or node.lineno) + 1)
+            )
+
+    remaining = "".join(
+        line
+        for number, line in enumerate(lines, start=1)
+        if number not in excluded
+    )
+    sql_pattern = re.compile(
+        r"(SELECT\s[^\"']*?FROM|INSERT\s+INTO|UPDATE|DELETE\s+FROM|"
+        r"FROM|JOIN)\s+[`'\"]*(\[)?(schedule_rules|task_definitions)\b",
+        re.IGNORECASE,
+    )
+    assert sql_pattern.search(remaining) is None, (
+        "test_dao_instances.py must go through the DAO, not raw SQL, "
+        "for schedule_rules/task_definitions"
+    )
+
+
 def test_dao_rules_test_file_uses_dao_not_raw_table_sql() -> None:
     """This test module must exercise the DAO, not raw SQL, for these
     tables.  Exceptions: the guard functions' own spans (their regexes