Sync dev with main (release-merge backport) (#36)

custom_components/nestquest/__init__.py

@@ -1,18 +1,219 @@
 """The NestQuest integration."""
 from __future__ import annotations
 
+import asyncio
 import inspect
+import sqlite3
 from collections.abc import Callable
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryNotReady
 
 from .const import DOMAIN, LOGGER
+from .db import NestQuestDatabase
+from .migrations import apply_migrations
+from .store import async_get_db_path
 
 _LOGGER = LOGGER
 
+#: SQLite reports "file is not a database" for corruption in every
+#: sqlite3 version this integration targets; the version-specific
+#: "encrypted or malformed" spelling (3.41+) maps to the same failure.
+_CORRUPTION_MARKERS = (
+    "file is not a database",
+    "database disk image is malformed",
+    "encrypted or malformed",
+    "is not a database",
+)
+
+#: Primary sqlite error codes that mean "the file is corrupt" (SQLite
+#: result codes, https://www.sqlite.org/c3ref/c_abort.html).  Extended
+#: codes carry the primary code in their low byte, so the match is on
+#: errcode & 0xff.
+_CORRUPT_PRIMARY_CODES = frozenset({11, 26})  # SQLITE_CORRUPT, SQLITE_NOTADB
+
+
+def _is_corruption_error(error: BaseException) -> bool:
+    """Return True when ``error`` indicates a corrupt database file.
+
+    Classification order: sqlite_errorcode (Python 3.11+) is primary
+    and locale-independent — SQLITE_CORRUPT and SQLITE_NOTADB, matched
+    on the primary byte so extended codes (SQLITE_CORRUPT_VTAB etc.)
+    classify correctly too.  Message matching is the fallback for
+    older Pythons: the corruption spellings are the documented English
+    texts; a non-English locale could evade them, but the code check
+    already covers every locale on supported Pythons.
+    """
+    if not isinstance(error, sqlite3.DatabaseError):
+        return False
+    errorcode = getattr(error, "sqlite_errorcode", None)
+    if errorcode is not None and (errorcode & 0xFF) in _CORRUPT_PRIMARY_CODES:
+        return True
+    message = str(error).lower()
+    return any(marker in message for marker in _CORRUPTION_MARKERS)
+
+
+async def _preflight_existing_file(
+    hass: HomeAssistant, db_path: Path
+) -> None:
+    """Detect corruption in an EXISTING file before it is opened read-write.
+
+    Opening read-write persists WAL mode — for a rollback-journal file
+    that rewrites the header byte 18/19 and can create -wal/-shm
+    sidecars — which would modify a corrupt file before detection and
+    break the leave-untouched guarantee.  This preflight therefore
+    validates the WHOLE file with a READ-ONLY connection (mode=ro +
+    immutable=1 URI, PRAGMA integrity_check, run on the executor like
+    every other DB call): corruption anywhere fails there, before
+    anything is written.  ``immutable=1`` is SQLite's documented
+    guarantee that the connection performs NO writes and creates NO
+    sidecars — even a WAL-header file gets its -wal/-shm reads served
+    without creating the shared-memory file.  Missing/empty files skip
+    the preflight (they are created fresh by the real open).  All
+    filesystem stat/URI work runs inside the executor job with the
+    probe so the event loop never touches disk.
+    """
+    def _probe() -> None:
+        # The file-state check and URI construction live inside the
+        # executor job: exists/stat/resolve are disk I/O.
+        if not db_path.exists():
+            return
+        # A zero-byte file is neither missing nor a valid database: it
+        # is a corrupt (truncated-to-nothing) existing file, likely an
+        # interrupted first write.  The leave-untouched contract applies
+        # to it too: refuse rather than silently initialize over it.
+        if db_path.stat().st_size == 0:
+            raise sqlite3.DatabaseError(
+                "existing database file is empty (zero bytes): file is "
+                "not a database"
+            )
+        # Properly escape the path: '#'/'?'/'%' in a directory or file
+        # name would otherwise be parsed as URI fragments/parameters/
+        # escapes.  immutable=1: SQLite guarantees no writes and no
+        # sidecar creation from this connection.
+        uri = db_path.resolve().as_uri() + "?mode=ro&immutable=1"
+        conn = sqlite3.connect(uri, uri=True)
+        try:
+            row = conn.execute("PRAGMA integrity_check").fetchone()
+        finally:
+            conn.close()
+        verdict = row[0] if row else "missing"
+        if verdict != "ok":
+            # A non-ok integrity verdict IS corruption: raise with the
+            # verdict text (which matches the corruption markers) and
+            # the NOTADB code so classification is code-based.
+            raise sqlite3.DatabaseError(
+                f"integrity_check verdict {verdict!r} on read-only "
+                f"probe: file is not a database"
+            )
+
+    try:
+        # Every DB-touching call goes through the executor (the mock
+        # harness's async_add_executor_job is awaitable too).
+        await hass.async_add_executor_job(_probe)
+    except sqlite3.DatabaseError as err:
+        # Non-ok integrity verdicts are corruption, full stop: there is
+        # no benign reading of a failed whole-file integrity check, so
+        # ANY DatabaseError out of the probe that carries a corruption
+        # marker or code propagates as corruption.  Only exotic probe
+        # failures that classify as non-corruption (e.g. a transient
+        # 'database is locked' on the read) are downgraded to a debug
+        # log, letting the real open path surface them.
+        if _is_corruption_error(err):
+            raise
+        raise sqlite3.DatabaseError(
+            f"read-only corruption probe of {db_path} failed: {err}"
+        ) from err
+
+async def _async_open_database(
+    hass: HomeAssistant, db_path: Path
+) -> NestQuestDatabase:
+    """Open the NestQuest database, mapping failure modes for setup.
+
+    Three startup cases (Feature 02 done-condition):
+
+    - file missing: SQLite creates it fresh on open — no special path,
+      migrations stamp version 1 on the next step.
+    - file present and valid: opens normally.
+    - file present but corrupt: log an ERROR with the path, close
+      anything opened, and raise ConfigEntryNotReady so HA retries —
+      the file is left byte-for-byte untouched so the owner can
+      restore a backup.  No code path here deletes or overwrites an
+      existing database file.
+
+    Corruption can surface at EITHER stage: a truncated header fails
+    in the read-only preflight (before the file is ever opened
+    read-write), while damaged later pages fail during migrations —
+    the preflight guarantees no WAL sidecar or header write happens
+    on a corrupt file before it is detected.  Both are classified the
+    same way.
+    """
+    try:
+        await _preflight_existing_file(hass, db_path)
+        database = await NestQuestDatabase(hass).open(db_path)
+    except asyncio.CancelledError:
+        raise
+    except sqlite3.DatabaseError as err:
+        if _is_corruption_error(err):
+            _LOGGER.error(
+                "NestQuest database at %s is corrupt: %s. Refusing to "
+                "start with a corrupt database; the file was left "
+                "untouched so a backup can be restored. Home Assistant "
+                "will retry setup.",
+                db_path,
+                err,
+            )
+            raise ConfigEntryNotReady(
+                f"NestQuest database corrupt: {db_path}"
+            ) from err
+        # open() failed for a non-corruption reason (locked file,
+        # permission problem): retryable, but nothing was opened.
+        _LOGGER.error(
+            "NestQuest database at %s failed to open: %s. Home "
+            "Assistant will retry setup.",
+            db_path,
+            err,
+        )
+        raise ConfigEntryNotReady(
+            f"NestQuest database unavailable: {db_path}"
+        ) from err
+    try:
+        await apply_migrations(database)
+    except (sqlite3.DatabaseError, RuntimeError) as err:
+        await database.close()
+        if _is_corruption_error(err):
+            _LOGGER.error(
+                "NestQuest database at %s is corrupt: %s. Refusing to "
+                "start with a corrupt database; the file was left "
+                "untouched so a backup can be restored. Home Assistant "
+                "will retry setup.",
+                db_path,
+                err,
+            )
+            raise ConfigEntryNotReady(
+                f"NestQuest database corrupt: {db_path}"
+            ) from err
+        # A non-corruption failure (e.g. a locked file, a future schema
+        # version) is also a retryable setup problem, but without the
+        # corruption framing.
+        _LOGGER.error(
+            "NestQuest database at %s failed to open: %s. Home "
+            "Assistant will retry setup.",
+            db_path,
+            err,
+        )
+        raise ConfigEntryNotReady(
+            f"NestQuest database unavailable: {db_path}"
+        ) from err
+    except asyncio.CancelledError:
+        await database.close()
+        raise
+    return database
+
 
 @dataclass
 class NestQuestRuntimeData:
@@ -20,6 +221,7 @@ class NestQuestRuntimeData:
 
     entry_id: str
     options: dict[str, Any]
+    database: NestQuestDatabase
     remove_update_listener: Callable[[], Any]
 
 
@@ -31,6 +233,21 @@ async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up NestQuest from a config entry."""
     hass.data.setdefault(DOMAIN, {})
+    existing = hass.data[DOMAIN].get(entry.entry_id)
+    if existing is not None:
+        db = getattr(existing, "database", None)
+        if db is None or not db.connected:
+            # Reopen through the SAME safety path as first setup: a
+            # record without a live connection (a previous setup's
+            # close-on-failure, or a hand-replaced file) must get the
+            # missing/valid/corrupt classification too, never a raw
+            # sqlite3 error and never skipped migrations.
+            db = await _async_open_database(
+                hass, await async_get_db_path(hass)
+            )
+            existing.database = db
+        entry.runtime_data = existing
+        return True
 
     async def _async_update_listener(
         listener_hass: HomeAssistant, listener_entry: ConfigEntry
@@ -38,10 +255,17 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         """Reload the entry when its options change."""
         await listener_hass.config_entries.async_reload(listener_entry.entry_id)
 
+    database = await _async_open_database(hass, await async_get_db_path(hass))
+    try:
+        remove_update_listener = entry.add_update_listener(_async_update_listener)
+    except BaseException:
+        await database.close()
+        raise
     runtime_data = NestQuestRuntimeData(
         entry_id=entry.entry_id,
         options=dict(entry.options),
-        remove_update_listener=entry.add_update_listener(_async_update_listener),
+        database=database,
+        remove_update_listener=remove_update_listener,
     )
     entry.runtime_data = runtime_data
     hass.data[DOMAIN][entry.entry_id] = runtime_data
@@ -58,10 +282,22 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         runtime_data = getattr(entry, "runtime_data", None)
     if runtime_data is not None:
         remove_update_listener = getattr(runtime_data, "remove_update_listener", None)
-        if remove_update_listener is not None:
-            result = remove_update_listener()
-            if inspect.isawaitable(result):
-                await result
+        unload_error: BaseException | None = None
+        try:
+            if remove_update_listener is not None:
+                result = remove_update_listener()
+                if inspect.isawaitable(result):
+                    await result
+        except BaseException as err:
+            unload_error = err
+        finally:
+            database = getattr(runtime_data, "database", None)
+            if database is not None:
+                await database.close()
+        if unload_error is not None:
+            if getattr(entry, "runtime_data", None) is not None:
+                entry.runtime_data = None
+            raise unload_error
     if getattr(entry, "runtime_data", None) is not None:
         entry.runtime_data = None
     return True

custom_components/nestquest/dao_children.py

@@ -0,0 +1,289 @@
+"""Typed DAO layer for the children and admin_users tables.
+
+All SQL for ``children`` and ``admin_users`` lives in this module per
+the feature guardrail: 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.
+
+Error contract: violations surface as the underlying
+:class:`sqlite3.IntegrityError` (duplicate, foreign-key, or CHECK
+failure) from the execute call; the DAO adds no wrapping exception
+type.  A get that matches nothing returns ``None``; a mutation that
+matches nothing is reported by :class:`~.db.ExecutionResult.rowcount`,
+which each method returns where the caller may need it (reorder, and
+the admin remove/set paths).
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from .db import NestQuestDatabase
+
+
+@dataclass(frozen=True)
+class ChildRecord:
+    """One row of ``children``."""
+
+    id: int
+    display_name: str
+    colour: str | None
+    avatar_ref: str | None
+    sort_order: int
+    is_active: bool
+    created_at: str
+
+
+@dataclass(frozen=True)
+class AdminUserRecord:
+    """One row of ``admin_users``."""
+
+    ha_user_id: str
+    added_at: str
+
+
+def _child_from_row(row: tuple) -> ChildRecord:
+    """Build a :class:`ChildRecord` from a SELECT row."""
+    return ChildRecord(
+        id=row[0],
+        display_name=row[1],
+        colour=row[2],
+        avatar_ref=row[3],
+        sort_order=row[4],
+        is_active=bool(row[5]),
+        created_at=row[6],
+    )
+
+
+_CHILD_COLUMNS = (
+    "id, display_name, colour, avatar_ref, sort_order, is_active, created_at"
+)
+
+
+#: One asyncio.Lock per (connection wrapper, running loop), shared by
+#: every ChildrenDao instance over the same database: the wrapper
+#: rejects a second concurrent transaction with RuntimeError, so ALL
+#: transactional DAO operations on one connection must queue here, not
+#: per-instance.  Keyed like the migration runner's lock; entries are
+#: never evicted (a config entry holds one wrapper per process).
+_CONNECTION_LOCKS: dict[tuple[int, int], asyncio.Lock] = {}
+
+
+def _connection_lock(database) -> asyncio.Lock:
+    """Return the shared transaction-serializing lock for ``database``."""
+    loop = asyncio.get_running_loop()
+    key = (id(database), id(loop))
+    lock = _CONNECTION_LOCKS.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _CONNECTION_LOCKS[key] = lock
+    return lock
+
+
+class ChildrenDao:
+    """Typed async data access for the ``children`` table.
+
+    Deletion is deliberately absent: children are deactivated, never
+    deleted, because completion history references them (feature
+    guardrail).
+    """
+
+    def __init__(self, database) -> None:
+        self._database = database
+
+    async def create(
+        self,
+        display_name: str,
+        created_at: str,
+        *,
+        colour: str | None = None,
+        avatar_ref: str | None = None,
+        sort_order: int = 0,
+        is_active: bool = True,
+    ) -> ChildRecord:
+        """Insert one child and return the record as stored."""
+        result = await self._database.execute(
+            "INSERT INTO children (display_name, colour, avatar_ref, "
+            "sort_order, is_active, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+            (
+                display_name,
+                colour,
+                avatar_ref,
+                sort_order,
+                int(is_active),
+                created_at,
+            ),
+        )
+        child = await self.get(result.lastrowid)
+        assert child is not None
+        return child
+
+    async def get(self, child_id: int) -> ChildRecord | None:
+        """Return the child with ``child_id``, or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_CHILD_COLUMNS} FROM children WHERE id = ?",
+            (child_id,),
+        )
+        return _child_from_row(row) if row is not None else None
+
+    async def list_active(self) -> list[ChildRecord]:
+        """Return active children ordered by sort_order, then id."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_CHILD_COLUMNS} FROM children WHERE is_active = 1 "
+            "ORDER BY sort_order, id"
+        )
+        return [_child_from_row(row) for row in rows]
+
+    async def list_all(self) -> list[ChildRecord]:
+        """Return all children ordered by sort_order, then id."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_CHILD_COLUMNS} FROM children "
+            "ORDER BY sort_order, id"
+        )
+        return [record for record in map(_child_from_row, rows)]
+
+    async def update(
+        self,
+        child_id: int,
+        *,
+        display_name: str | None = None,
+        colour: str | None = None,
+        avatar_ref: str | None = None,
+        sort_order: int | None = None,
+    ) -> int:
+        """Update the given fields; returns rows updated (0 if absent).
+
+        Only non-None arguments are written, so a caller cannot
+        accidentally blank a column by omitting it.
+        """
+        assignments: list[str] = []
+        parameters: list[object] = []
+        if display_name is not None:
+            assignments.append("display_name = ?")
+            parameters.append(display_name)
+        if colour is not None:
+            assignments.append("colour = ?")
+            parameters.append(colour)
+        if avatar_ref is not None:
+            assignments.append("avatar_ref = ?")
+            parameters.append(avatar_ref)
+        if sort_order is not None:
+            assignments.append("sort_order = ?")
+            parameters.append(sort_order)
+        if not assignments:
+            return 0
+        parameters.append(child_id)
+        result = await self._database.execute(
+            f"UPDATE children SET {', '.join(assignments)} WHERE id = ?",
+            tuple(parameters),
+        )
+        return result.rowcount
+
+    async def set_active(self, child_id: int, is_active: bool) -> int:
+        """Set the child's active flag; returns rows updated (0 if absent)."""
+        result = await self._database.execute(
+            "UPDATE children SET is_active = ? WHERE id = ?",
+            (int(is_active), child_id),
+        )
+        return result.rowcount
+
+    async def reorder(self, ordered_ids: list[int]) -> None:
+        """Persist a new sort order: ``ordered_ids[i]`` gets sort_order i.
+
+        Runs inside one transaction; positions are staged at offset
+        -len (all negative, so any permutation of the same ids never
+        collides mid-reorder under the wrapper's single-connection
+        serialization), then finalized 0..n-1.  Duplicate ids are
+        rejected up front: they cannot all hold distinct positions, and
+        silently assigning the last occurrence's index would hide a
+        caller bug.
+
+        Concurrent reorder() calls on one connection are serialized by
+        a connection-scoped asyncio lock (shared across every ChildrenDao
+        over the same wrapper, however many instances): the wrapper's
+        transaction() rejects a second concurrent transaction with
+        RuntimeError, so racing callers would crash instead of
+        queueing.  The lock makes the second call wait, then run
+        against the first call's final state.
+        """
+        if not ordered_ids:
+            return
+        if len(set(ordered_ids)) != len(ordered_ids):
+            raise ValueError(
+                "reorder() received duplicate child ids; every id must "
+                "appear at most once"
+            )
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                offset = len(ordered_ids)
+                await self._database.execute_many(
+                    "UPDATE children SET sort_order = ? WHERE id = ?",
+                    [
+                        (-(offset + index), child_id)
+                        for index, child_id in enumerate(ordered_ids)
+                    ],
+                )
+                await self._database.execute_many(
+                    "UPDATE children SET sort_order = ? WHERE id = ?",
+                    [
+                        (index, child_id)
+                        for index, child_id in enumerate(ordered_ids)
+                    ],
+                )
+
+
+class AdminUsersDao:
+    """Typed async access to the ``admin_users`` allowlist.
+
+    The allowlist stores HA user IDs, never usernames (feature
+    guardrail); an empty allowlist means no admin, enforced by callers
+    resolving through :meth:`exists`.
+    """
+
+    def __init__(self, database) -> None:
+        self._database = database
+
+    async def add(self, ha_user_id: str, added_at: str) -> bool:
+        """Add a user to the allowlist; True if inserted, False if present.
+
+        Idempotent under concurrency: a single INSERT ... ON CONFLICT DO
+        NOTHING decides and inserts in one statement (the wrapper
+        serializes statements, not check-then-insert sequences, so a
+        SELECT/INSERT pair would let two concurrent adds both see no
+        row and the second one raise IntegrityError).  rowcount reports
+        whether the insert actually happened.
+        """
+        result = await self._database.execute(
+            "INSERT INTO admin_users (ha_user_id, added_at) VALUES (?, ?) "
+            "ON CONFLICT (ha_user_id) DO NOTHING",
+            (ha_user_id, added_at),
+        )
+        return result.rowcount > 0
+
+    async def remove(self, ha_user_id: str) -> bool:
+        """Remove a user from the allowlist; True if a row was removed."""
+        result = await self._database.execute(
+            "DELETE FROM admin_users WHERE ha_user_id = ?",
+            (ha_user_id,),
+        )
+        return result.rowcount > 0
+
+    async def list(self) -> list[AdminUserRecord]:
+        """Return every allowlisted user, oldest first."""
+        rows = await self._database.fetch_all(
+            "SELECT ha_user_id, added_at FROM admin_users "
+            "ORDER BY added_at, ha_user_id"
+        )
+        return [
+            AdminUserRecord(ha_user_id=row[0], added_at=row[1])
+            for row in rows
+        ]
+
+    async def exists(self, ha_user_id: str) -> bool:
+        """Return True if ``ha_user_id`` is allowlisted."""
+        row = await self._database.fetch_one(
+            "SELECT 1 FROM admin_users WHERE ha_user_id = ?",
+            (ha_user_id,),
+        )
+        return row is not None

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

custom_components/nestquest/dao_rules.py

@@ -0,0 +1,465 @@
+"""Typed DAO layer for the schedule_rules and task_definitions tables.
+
+All SQL for ``schedule_rules`` and ``task_definitions`` 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.
+
+Guardrail mapping:
+
+- ``schedule_rules`` deletion is delete-if-unreferenced: a rule still
+  referenced by any task definition is rejected (the done-condition),
+  not cascaded.
+- ``task_definitions`` has no delete path at all: definitions are
+  deactivated, never hard-deleted, and history must survive.
+- ``set_assignee`` changes future instances only — the DAO writes the
+  definition row and nothing else; reassignment never rewrites
+  existing instances or completion history (Feature 06 guardrail).
+- Validation of rule well-formedness and child activeness lives partly
+  in the schema CHECKs (rule-type coherence) and partly in
+  :meth:`TaskDefinitionsDao.create` (active child, rule existence);
+  no permission checks here, that is the Feature 09 gate's job.
+
+Concurrency: ``delete_rule_if_unreferenced`` performs its reference
+check and DELETE inside one transaction under the connection-scoped
+lock shared with :mod:`.dao_children`, so a definition referencing the
+rule cannot appear between check and delete on this connection.
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+from .dao_children import _connection_lock
+from .db import NestQuestDatabase
+
+#: Sentinel distinguishing "argument omitted" from "explicit SQL NULL"
+#: in update methods: passing ``None`` must mean clearing a nullable
+#: column, not skipping it.
+_UNSET = object()
+
+#: Date-shape policy: schedule-rule dates are ISO YYYY-MM-DD.  The
+#: schema's lexical end>=start CHECK cannot prove a value is a real
+#: calendar date, so the DAO validates the shape it accepts.
+_DATE_FORMAT = "%Y-%m-%d"
+
+
+def _validate_date(value: str, field: str) -> None:
+    """Raise ValueError unless ``value`` is a YYYY-MM-DD calendar date.
+
+    ``datetime.date.fromisoformat`` accepts ISO dates but is lenient on
+    some builds (e.g. '2026-9-4'); strptime with an exact format is
+    strict, and strptime round-trips the parsed value to reject zero
+    padding ('2026-9-4' parses but its isoformat differs).
+    """
+    try:
+        parsed = datetime.datetime.strptime(value, _DATE_FORMAT).date()
+    except (TypeError, ValueError):
+        raise ValueError(
+            f"{field} must be an ISO date (YYYY-MM-DD), got {value!r}"
+        ) from None
+    if parsed.isoformat() != value:
+        raise ValueError(
+            f"{field} must be a strict YYYY-MM-DD date, got {value!r}"
+        )
+
+
+@dataclass(frozen=True)
+class ScheduleRuleRecord:
+    """One row of ``schedule_rules``."""
+
+    id: int
+    rule_type: str
+    interval: int
+    weekday_set: str | None
+    day_of_month: int | None
+    nth_weekday: int | None
+    month: int | None
+    start_date: str
+    end_date: str | None
+
+
+@dataclass(frozen=True)
+class TaskDefinitionRecord:
+    """One row of ``task_definitions``."""
+
+    id: int
+    title: str
+    description: str | None
+    icon: str | None
+    child_id: int
+    schedule_rule_id: int
+    due_time: str | None
+    is_active: bool
+    created_at: str
+
+
+_RULE_COLUMNS = (
+    "id, rule_type, interval, weekday_set, day_of_month, nth_weekday, "
+    "month, start_date, end_date"
+)
+_DEFINITION_COLUMNS = (
+    "id, title, description, icon, child_id, schedule_rule_id, due_time, "
+    "is_active, created_at"
+)
+
+
+def _rule_from_row(row: tuple) -> ScheduleRuleRecord:
+    return ScheduleRuleRecord(
+        id=row[0],
+        rule_type=row[1],
+        interval=row[2],
+        weekday_set=row[3],
+        day_of_month=row[4],
+        nth_weekday=row[5],
+        month=row[6],
+        start_date=row[7],
+        end_date=row[8],
+    )
+
+
+def _definition_from_row(row: tuple) -> TaskDefinitionRecord:
+    return TaskDefinitionRecord(
+        id=row[0],
+        title=row[1],
+        description=row[2],
+        icon=row[3],
+        child_id=row[4],
+        schedule_rule_id=row[5],
+        due_time=row[6],
+        is_active=bool(row[7]),
+        created_at=row[8],
+    )
+
+
+class ScheduleRulesDao:
+    """Typed async access to the ``schedule_rules`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def create(
+        self,
+        rule_type: str,
+        start_date: str,
+        *,
+        interval: int = 1,
+        weekday_set: str | None = None,
+        day_of_month: int | None = None,
+        nth_weekday: int | None = None,
+        month: int | None = None,
+        end_date: str | None = None,
+    ) -> ScheduleRuleRecord:
+        """Insert one rule and return the record as stored.
+
+        Rule-type coherence (a weekly rule needs ``weekday_set``, a
+        yearly rule needs ``month``, etc.) is enforced by the schema
+        CHECKs and surfaces as :class:`sqlite3.IntegrityError`.  Date
+        shape (strict YYYY-MM-DD) is validated here because the
+        schema's lexical end>=start CHECK cannot prove a real calendar
+        date.
+        """
+        _validate_date(start_date, "start_date")
+        if end_date is not None:
+            _validate_date(end_date, "end_date")
+        result = await self._database.execute(
+            "INSERT INTO schedule_rules (rule_type, interval, weekday_set, "
+            "day_of_month, nth_weekday, month, start_date, end_date) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                rule_type,
+                interval,
+                weekday_set,
+                day_of_month,
+                nth_weekday,
+                month,
+                start_date,
+                end_date,
+            ),
+        )
+        rule = await self.get(result.lastrowid)
+        assert rule is not None
+        return rule
+
+    async def get(self, rule_id: int) -> ScheduleRuleRecord | None:
+        """Return the rule with ``rule_id``, or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_RULE_COLUMNS} FROM schedule_rules WHERE id = ?",
+            (rule_id,),
+        )
+        return _rule_from_row(row) if row is not None else None
+
+    async def update(
+        self,
+        rule_id: int,
+        *,
+        rule_type: str | None | object = _UNSET,
+        interval: int | None | object = _UNSET,
+        weekday_set: str | None | object = _UNSET,
+        day_of_month: int | None | object = _UNSET,
+        nth_weekday: int | None | object = _UNSET,
+        month: int | None | object = _UNSET,
+        start_date: str | None | object = _UNSET,
+        end_date: str | None | object = _UNSET,
+    ) -> int:
+        """Update the given fields; returns rows updated (0 if absent).
+
+        Arguments default to the module sentinel ``_UNSET`` meaning
+        "leave this column alone"; passing ``None`` explicitly writes
+        SQL NULL, so callers can reopen an ended rule (``end_date``
+        back to NULL) or clear nullable shape fields.  Passing
+        ``None``/a new value for a date field validates its shape.
+        Editing a rule that a definition references changes future
+        materializations only — this method touches no instances
+        (Feature 06/07 separation).
+        """
+        date_args = (
+            ("start_date", start_date),
+            ("end_date", end_date),
+        )
+        for field, value in date_args:
+            if value is not _UNSET and value is not None:
+                _validate_date(value, field)
+        assignments: list[str] = []
+        parameters: list[object] = []
+        for column, value in (
+            ("rule_type", rule_type),
+            ("interval", interval),
+            ("weekday_set", weekday_set),
+            ("day_of_month", day_of_month),
+            ("nth_weekday", nth_weekday),
+            ("month", month),
+            ("start_date", start_date),
+            ("end_date", end_date),
+        ):
+            if value is not _UNSET:
+                assignments.append(f"{column} = ?")
+                parameters.append(value)
+        if not assignments:
+            return 0
+        parameters.append(rule_id)
+        result = await self._database.execute(
+            f"UPDATE schedule_rules SET {', '.join(assignments)} "
+            "WHERE id = ?",
+            tuple(parameters),
+        )
+        return result.rowcount
+
+    async def delete_if_unreferenced(self, rule_id: int) -> bool:
+        """Delete the rule only if no definition references it.
+
+        Returns True if the rule was deleted, False if it is still
+        referenced (or does not exist — distinguish via :meth:`get`).
+        The reference check and the DELETE run inside one transaction
+        under the connection lock, so a definition cannot start
+        referencing the rule between the check and the delete.
+        """
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                row = await self._database.fetch_one(
+                    "SELECT 1 FROM task_definitions "
+                    "WHERE schedule_rule_id = ? LIMIT 1",
+                    (rule_id,),
+                )
+                if row is not None:
+                    return False
+                result = await self._database.execute(
+                    "DELETE FROM schedule_rules WHERE id = ?",
+                    (rule_id,),
+                )
+                return result.rowcount > 0
+
+
+class TaskDefinitionsDao:
+    """Typed async access to the ``task_definitions`` table.
+
+    No delete method exists: definitions are deactivated via
+    :meth:`set_active`, never hard-deleted, so completion history keeps
+    its references (feature guardrail).
+    """
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def create(
+        self,
+        title: str,
+        child_id: int,
+        schedule_rule_id: int,
+        created_at: str,
+        *,
+        description: str | None = None,
+        icon: str | None = None,
+        due_time: str | None = None,
+        is_active: bool = True,
+    ) -> TaskDefinitionRecord:
+        """Insert one definition and return the record as stored.
+
+        Validates the assignment target as part of the same serialized
+        transaction as the insert: the child must exist and be active,
+        and the rule must exist, AT INSERT TIME — a child deactivated
+        or a rule deleted concurrently cannot slip between the checks
+        and the INSERT, which would otherwise create an invalid
+        assignment or surface as a raw FK IntegrityError instead of
+        the documented ValueError.  An INACTIVE child would pass the
+        schema foreign keys, which is why the activeness check lives
+        here.
+        """
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                await self._validate_assignable(
+                    child_id, schedule_rule_id
+                )
+                result = await self._database.execute(
+                    "INSERT INTO task_definitions (title, description, "
+                    "icon, child_id, schedule_rule_id, due_time, "
+                    "is_active, created_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        title,
+                        description,
+                        icon,
+                        child_id,
+                        schedule_rule_id,
+                        due_time,
+                        int(is_active),
+                        created_at,
+                    ),
+                )
+                definition = await self.get(result.lastrowid)
+        assert definition is not None
+        return definition
+
+    async def _validate_assignable(
+        self, child_id: int, schedule_rule_id: int
+    ) -> None:
+        """Raise ValueError unless child (active) and rule both exist.
+
+        MUST be called inside the connection lock so the verdict cannot
+        go stale before the caller's INSERT commits.
+        """
+        await self._validate_assignable_child(child_id)
+        rule = await self._database.fetch_one(
+            "SELECT 1 FROM schedule_rules WHERE id = ?",
+            (schedule_rule_id,),
+        )
+        if rule is None:
+            raise ValueError(
+                f"schedule rule {schedule_rule_id} does not exist"
+            )
+
+    async def get(self, definition_id: int) -> TaskDefinitionRecord | None:
+        """Return the definition with ``definition_id``, or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_DEFINITION_COLUMNS} FROM task_definitions "
+            "WHERE id = ?",
+            (definition_id,),
+        )
+        return _definition_from_row(row) if row is not None else None
+
+    async def list_by_child(self, child_id: int) -> list[TaskDefinitionRecord]:
+        """Return all definitions assigned to ``child_id``, newest first."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_DEFINITION_COLUMNS} FROM task_definitions "
+            "WHERE child_id = ? ORDER BY id DESC",
+            (child_id,),
+        )
+        return [_definition_from_row(row) for row in rows]
+
+    async def list_active(self) -> list[TaskDefinitionRecord]:
+        """Return all active definitions, oldest first (stable order)."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_DEFINITION_COLUMNS} FROM task_definitions "
+            "WHERE is_active = 1 ORDER BY id"
+        )
+        return [_definition_from_row(row) for row in rows]
+
+    async def update(
+        self,
+        definition_id: int,
+        *,
+        title: str | None | object = _UNSET,
+        description: str | None | object = _UNSET,
+        icon: str | None | object = _UNSET,
+        due_time: str | None | object = _UNSET,
+    ) -> int:
+        """Update the given fields; returns rows updated (0 if absent).
+
+        Arguments default to the module sentinel ``_UNSET`` meaning
+        "leave this column alone"; passing ``None`` explicitly writes
+        SQL NULL, so callers can remove optional metadata
+        (description, icon, due_time).  Assignment and activation are
+        deliberately NOT settable here: they have their own explicit
+        operations (:meth:`set_assignee`, :meth:`set_active`) so they
+        stay separately loggable and permission-gateable.
+        """
+        assignments: list[str] = []
+        parameters: list[object] = []
+        for column, value in (
+            ("title", title),
+            ("description", description),
+            ("icon", icon),
+            ("due_time", due_time),
+        ):
+            if value is not _UNSET:
+                assignments.append(f"{column} = ?")
+                parameters.append(value)
+        if not assignments:
+            return 0
+        parameters.append(definition_id)
+        result = await self._database.execute(
+            f"UPDATE task_definitions SET {', '.join(assignments)} "
+            "WHERE id = ?",
+            tuple(parameters),
+        )
+        return result.rowcount
+
+    async def set_active(self, definition_id: int, is_active: bool) -> int:
+        """Deactivate/reactivate; returns rows updated (0 if absent).
+
+        Deactivating stops future instance generation but leaves
+        existing instances and completion history untouched.
+        """
+        result = await self._database.execute(
+            "UPDATE task_definitions SET is_active = ? WHERE id = ?",
+            (int(is_active), definition_id),
+        )
+        return result.rowcount
+
+    async def set_assignee(
+        self, definition_id: int, child_id: int
+    ) -> int:
+        """Reassign the definition to ``child_id``; rows updated (0 if absent).
+
+        Validates the new assignee inside the same serialized
+        transaction as the UPDATE (existing and active AT ASSIGNMENT
+        TIME), so a child deactivated concurrently cannot become the
+        assignee.  Changes future instances only: already-generated
+        instances and completion history are never rewritten here.
+        """
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                await self._validate_assignable_child(child_id)
+                result = await self._database.execute(
+                    "UPDATE task_definitions SET child_id = ? "
+                    "WHERE id = ?",
+                    (child_id, definition_id),
+                )
+        return result.rowcount
+
+    async def _validate_assignable_child(self, child_id: int) -> None:
+        """Raise ValueError unless the child exists and is active.
+
+        MUST be called inside the connection lock so the verdict cannot
+        go stale before the caller's UPDATE commits.
+        """
+        child = await self._database.fetch_one(
+            "SELECT is_active FROM children WHERE id = ?", (child_id,)
+        )
+        if child is None:
+            raise ValueError(f"child {child_id} does not exist")
+        if not child[0]:
+            raise ValueError(
+                f"child {child_id} is inactive and cannot be assigned"
+            )

custom_components/nestquest/db.py

@@ -0,0 +1,422 @@
+"""Async SQLite connection wrapper for the NestQuest integration."""
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from collections.abc import AsyncIterator, Awaitable, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from homeassistant.core import HomeAssistant
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    """Plain-data outcome of one statement.
+
+    ``rowcount`` and ``lastrowid`` mirror the corresponding
+    :class:`sqlite3.Cursor` attributes; both are captured on the executor
+    thread so no sqlite3 object ever crosses back to the event loop.
+    """
+
+    rowcount: int
+    lastrowid: int | None
+
+
+class NestQuestDatabase:
+    """Async wrapper around a single SQLite connection.
+
+    Every sqlite3 call is delegated to the Home Assistant executor through
+    ``hass.async_add_executor_job`` so the event loop is never blocked, and
+    only plain Python data (row tuples and :class:`ExecutionResult`) is
+    returned to the event loop.
+
+    Every operation is serialized through one asyncio.Lock per wrapper.  A
+    ``transaction()`` holds that lock for its whole BEGIN..COMMIT span, so
+    interleaved coroutines cannot corrupt the transaction and concurrent
+    BEGINs are impossible; statements issued while a transaction is open
+    queue until it completes.  Concurrent transactions on one wrapper are
+    not supported: a second ``transaction()`` entered while one is active
+    raises :class:`RuntimeError`.  ``close()`` serializes on the same lock
+    and is idempotent.
+
+    Every connection-affecting executor job (connect, pragmas, statements,
+    transaction lifecycle and close) is awaited through the settlement
+    helper :meth:`_await_settled`: if the awaiting task is cancelled while
+    a job is in flight, the job still settles on the worker thread before
+    the cancellation propagates, so the wrapper lock is never released
+    while the executor thread is mid-job.
+    """
+
+    def __init__(self, hass: HomeAssistant) -> None:
+        """Initialize the wrapper around a Home Assistant instance."""
+        self._hass = hass
+        self._conn: sqlite3.Connection | None = None
+        self._rowcount: int = -1
+        self._lastrowid: int | None = None
+        self._lock: asyncio.Lock | None = None
+        self._lock_loop: asyncio.AbstractEventLoop | None = None
+        self._in_transaction = False
+        self._tx_task: asyncio.Task | None = None
+
+    def _get_lock(self) -> asyncio.Lock:
+        """Return the per-wrapper lock, (re)bound to the running loop.
+
+        HA drives every wrapper call from one event loop, so the lock is
+        created once and reused; re-binding only when the running loop
+        differs keeps the wrapper usable from plain synchronous drivers
+        that run each call on a fresh loop.
+        """
+        loop = asyncio.get_running_loop()
+        if self._lock is None or self._lock_loop is not loop:
+            self._lock = asyncio.Lock()
+            self._lock_loop = loop
+        return self._lock
+
+    @property
+    def connected(self) -> bool:
+        """Return True while the underlying connection is open."""
+        return self._conn is not None
+
+    @property
+    def rowcount(self) -> int:
+        """Row count of the most recent statement, or -1 when unset."""
+        return self._rowcount
+
+    @property
+    def lastrowid(self) -> int | None:
+        """Row id of the most recent insert, or None when unset."""
+        return self._lastrowid
+
+    @asynccontextmanager
+    async def _serialized(self) -> AsyncIterator[None]:
+        """Hold the wrapper lock unless the caller owns the active transaction.
+
+        A transaction holds the lock for its whole BEGIN..COMMIT span;
+        statements issued by the transaction's own task are already
+        serialized by it and must not re-acquire the non-reentrant lock.
+        Any other task queues on the lock until the transaction ends.
+        """
+        if (
+            self._in_transaction
+            and self._tx_task is not None
+            and asyncio.current_task() is self._tx_task
+        ):
+            yield
+            return
+        async with self._get_lock():
+            yield
+
+    async def open(self, path: Path | str) -> NestQuestDatabase:
+        """Open the SQLite file with WAL journal mode and foreign keys on.
+
+        Cancellation-safe: if this call is cancelled while the connect job
+        is in flight, the job still settles (see :meth:`_await_settled`).
+        A connection the settled job created is never adopted by the
+        cancelled call; it is closed through a settled executor job instead
+        of being abandoned to garbage collection, and the cancellation
+        propagates afterwards, so a follow-up ``open()`` starts from a
+        clean state.
+        """
+        if self._conn is not None:
+            return self
+        async with self._get_lock():
+            if self._conn is not None:
+                return self
+
+            def _open() -> sqlite3.Connection:
+                conn = sqlite3.connect(
+                    path, check_same_thread=False, isolation_level=None
+                )
+                try:
+                    conn.execute("PRAGMA journal_mode=WAL")
+                    conn.execute("PRAGMA foreign_keys=ON")
+                except BaseException:
+                    conn.close()
+                    raise
+                return conn
+
+            settled, cancelled = await self._await_settled_state(
+                self._hass.async_add_executor_job(_open)
+            )
+            if cancelled:
+                if isinstance(settled, sqlite3.Connection):
+
+                    def _close_abandoned() -> None:
+                        settled.close()
+
+                    await self._await_settled(
+                        self._hass.async_add_executor_job(_close_abandoned)
+                    )
+                raise asyncio.CancelledError()
+            self._conn = settled
+        return self
+
+    async def execute(
+        self, sql: str, parameters: Sequence[Any] = ()
+    ) -> ExecutionResult:
+        """Run one statement in the executor and return its plain result."""
+        async with self._serialized():
+            conn = self._require_conn()
+
+            def _execute() -> ExecutionResult:
+                cursor = conn.execute(sql, parameters)
+                return ExecutionResult(cursor.rowcount, cursor.lastrowid)
+
+            result = await self._await_settled(
+                self._hass.async_add_executor_job(_execute)
+            )
+            self._rowcount = result.rowcount
+            self._lastrowid = result.lastrowid
+            return result
+
+    async def execute_many(
+        self, sql: str, parameters: Sequence[Sequence[Any]]
+    ) -> ExecutionResult:
+        """Run executemany in the executor and return its plain result."""
+        async with self._serialized():
+            conn = self._require_conn()
+
+            def _execute_many() -> ExecutionResult:
+                cursor = conn.executemany(sql, parameters)
+                return ExecutionResult(cursor.rowcount, cursor.lastrowid)
+
+            result = await self._await_settled(
+                self._hass.async_add_executor_job(_execute_many)
+            )
+            self._rowcount = result.rowcount
+            self._lastrowid = result.lastrowid
+            return result
+
+    async def fetch_one(
+        self, sql: str, parameters: Sequence[Any] = ()
+    ) -> tuple | None:
+        """Run a query in the executor and return its first row, or None."""
+        async with self._serialized():
+            conn = self._require_conn()
+
+            def _fetch_one() -> tuple[tuple | None, int, int | None]:
+                cursor = conn.execute(sql, parameters)
+                return cursor.fetchone(), cursor.rowcount, cursor.lastrowid
+
+            row, rowcount, lastrowid = await self._await_settled(
+                self._hass.async_add_executor_job(_fetch_one)
+            )
+            self._rowcount = rowcount
+            self._lastrowid = lastrowid
+            return row
+
+    async def fetch_all(
+        self, sql: str, parameters: Sequence[Any] = ()
+    ) -> list[tuple]:
+        """Run a query in the executor and return all of its rows."""
+        async with self._serialized():
+            conn = self._require_conn()
+
+            def _fetch_all() -> tuple[list[tuple], int, int | None]:
+                cursor = conn.execute(sql, parameters)
+                return cursor.fetchall(), cursor.rowcount, cursor.lastrowid
+
+            rows, rowcount, lastrowid = await self._await_settled(
+                self._hass.async_add_executor_job(_fetch_all)
+            )
+            self._rowcount = rowcount
+            self._lastrowid = lastrowid
+            return rows
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[None]:
+        """Run a block inside BEGIN/COMMIT, rolling back on any exception.
+
+        The wrapper lock is held for the entire BEGIN..COMMIT span, so no
+        other statement can interleave inside the transaction.  Entering a
+        second transaction while one is active raises RuntimeError.  A
+        failing COMMIT (e.g. a deferred foreign-key violation) also triggers
+        a ROLLBACK before the commit error propagates, so the real
+        connection is never left inside a stray transaction.
+
+        The lifecycle is cancellation-safe.  Transaction ownership and the
+        wrapper lock are only released after the executor work has fully
+        settled, even when the owning task is cancelled mid-flight: if a
+        cancelled BEGIN or COMMIT still completes on the worker thread,
+        the corresponding ROLLBACK is shielded and awaited before any state
+        is cleared.  A lifecycle statement that fails plus a failing
+        follow-up cleanup surface both errors in an ExceptionGroup.
+        """
+        if self._in_transaction:
+            raise RuntimeError(
+                "A NestQuest transaction is already active on this "
+                "connection; concurrent transactions are not supported"
+            )
+        async with self._get_lock():
+            conn = self._require_conn()
+            self._in_transaction = True
+            self._tx_task = asyncio.current_task()
+            try:
+
+                def _begin() -> None:
+                    conn.execute("BEGIN")
+
+                await self._settle_lifecycle(
+                    conn,
+                    self._hass.async_add_executor_job(_begin),
+                    "BEGIN did not settle cleanly and the follow-up "
+                    "cleanup also raised; the transaction may need manual "
+                    "cleanup",
+                )
+                try:
+                    yield
+                except BaseException:
+
+                    def _rollback() -> None:
+                        conn.execute("ROLLBACK")
+
+                    await self._settle_lifecycle(
+                        conn,
+                        self._hass.async_add_executor_job(_rollback),
+                        "ROLLBACK failed and the follow-up cleanup also "
+                        "raised; the transaction may need manual cleanup",
+                    )
+                    raise
+
+                def _commit() -> None:
+                    conn.execute("COMMIT")
+
+                await self._settle_lifecycle(
+                    conn,
+                    self._hass.async_add_executor_job(_commit),
+                    "COMMIT failed and the follow-up cleanup also raised; "
+                    "the transaction may need manual cleanup",
+                )
+            finally:
+                self._in_transaction = False
+                self._tx_task = None
+
+    async def _settle_lifecycle(
+        self, conn: sqlite3.Connection, job: Awaitable[Any], message: str
+    ) -> None:
+        """Run one BEGIN/ROLLBACK/COMMIT job, then force the connection clean.
+
+        The job always settles first (see :meth:`_await_settled`), so a
+        cancelled statement that the worker thread completed anyway is
+        never abandoned mid-flight.  If the job raised, a follow-up
+        ROLLBACK — itself settled — guarantees the connection ends outside
+        any SQLite transaction before the error propagates.  When both the
+        job and the cleanup raise, both errors are preserved in an
+        ExceptionGroup instead of the original being lost.
+        """
+        try:
+            await self._await_settled(job)
+        except BaseException as settle_error:
+            errors: list[BaseException] = [settle_error]
+            try:
+                await self._ensure_no_stray_transaction(conn)
+            except BaseException as cleanup_error:
+                errors.append(cleanup_error)
+            if len(errors) == 2:
+                raise BaseExceptionGroup(message, errors) from settle_error
+            raise
+
+    async def _ensure_no_stray_transaction(
+        self, conn: sqlite3.Connection
+    ) -> None:
+        """Force the connection out of any transaction via ROLLBACK.
+
+        Runs after a failed or cancelled lifecycle statement.  The worker
+        thread may still be finishing (or may already have completed) the
+        very statement whose await was cancelled, so both the check and
+        the ROLLBACK settle in the executor before the caller releases
+        transaction ownership.
+        """
+
+        def _cleanup() -> bool:
+            if conn.in_transaction:
+                conn.execute("ROLLBACK")
+            return conn.in_transaction
+
+        stray = await self._await_settled(
+            self._hass.async_add_executor_job(_cleanup)
+        )
+        if stray:
+            raise RuntimeError(
+                "The SQLite connection is still inside a transaction after "
+                "cleanup; the transaction may need manual cleanup"
+            )
+
+    async def _await_settled(self, job: Awaitable[Any]) -> Any:
+        """Await ``job``, letting it settle even if this task is cancelled.
+
+        Cancellation is observed, not swallowed: it is re-raised only once
+        the job has fully settled, so the caller can finalize against a
+        known connection state instead of abandoning in-flight work.  The
+        job is wrapped in a task because a bare coroutine dies un-awaited
+        once its await is cancelled.  A second cancellation during
+        settlement is absorbed the same way; if the job itself fails after
+        a cancellation, both errors surface in an ExceptionGroup.
+        """
+        result, cancelled = await self._await_settled_state(job)
+        if cancelled:
+            raise asyncio.CancelledError()
+        return result
+
+    async def _await_settled_state(self, job: Awaitable[Any]) -> tuple[Any, bool]:
+        """Await ``job`` to settlement and report ``(result, cancelled)``.
+
+        Same settlement guarantees as :meth:`_await_settled`, but returns
+        the settled outcome together with whether the awaiting task was
+        cancelled, so callers that must act on a settled result before
+        re-raising cancellation (e.g. closing an abandoned connection)
+        can do so without losing the result.
+        """
+        cancelled = False
+        inner = asyncio.ensure_future(job)
+        while not inner.done():
+            try:
+                await asyncio.shield(inner)
+            except asyncio.CancelledError:
+                cancelled = True
+        try:
+            result = inner.result()
+        except BaseException as job_error:
+            if cancelled:
+                raise BaseExceptionGroup(
+                    "executor job failed while settling after cancellation",
+                    [asyncio.CancelledError(), job_error],
+                ) from job_error
+            raise
+        return result, cancelled
+
+    async def close(self) -> None:
+        """Close the connection in the executor; safe to call repeatedly.
+
+        Serialized on the wrapper lock, so an in-flight operation or open
+        transaction always completes before the connection is closed.
+        """
+        if (
+            self._in_transaction
+            and self._tx_task is not None
+            and asyncio.current_task() is self._tx_task
+        ):
+            raise RuntimeError(
+                "Cannot close the NestQuest database from inside its own "
+                "transaction; exit the transaction first"
+            )
+        async with self._get_lock():
+            conn, self._conn = self._conn, None
+            self._rowcount, self._lastrowid = -1, None
+            if conn is None:
+                return
+
+            def _close() -> None:
+                conn.close()
+
+            await self._await_settled(self._hass.async_add_executor_job(_close))
+
+    def _require_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            raise RuntimeError(
+                "The NestQuest database connection is closed; call open() first"
+            )
+        return self._conn

custom_components/nestquest/manifest.json

@@ -1,12 +1,14 @@
 {
   "domain": "nestquest",
   "name": "NestQuest",
-  "codeowners": ["@overseer"],
+  "codeowners": [
+    "@overseer"
+  ],
   "config_flow": true,
-  "documentation": "https://code.cubecraftlabs.com/Maniacs_Mansion/NestQuest",
+  "documentation": "https://github.com/talon2king/NestQuest",
   "integration_type": "hub",
   "iot_class": "local_polling",
-  "issue_tracker": "https://code.cubecraftlabs.com/Maniacs_Mansion/NestQuest/issues",
+  "issue_tracker": "https://github.com/talon2king/NestQuest/issues",
   "requirements": [],
-  "version": "0.1.0"
+  "version": "0.3.0"
 }

custom_components/nestquest/migrations.py

@@ -0,0 +1,236 @@
+"""Versioned schema migration runner for the NestQuest SQLite database.
+
+The runner owns one metadata table, ``nestquest_schema_version``, holding
+a single row with the schema version the database file currently
+reflects.  Migrations are declared as an ordered list: entry ``n``
+upgrades version ``n-1`` to version ``n``.  Applying a migration means
+running its DDL inside one transaction and stamping the new version in
+that same transaction, so a database never persists a half-applied
+migration: any failure rolls the statements and the version stamp back
+together, leaving the file at its prior version.
+
+Version 0 means "the file exists but carries no NestQuest schema yet"
+— a fresh file, or a file this integration has never written.  Starting
+the runner against version 0 applies migration 1, which applies the
+full v1 DDL from :mod:`.schema` and stamps version 1.
+
+Each migration's statements and its version stamp run inside ONE
+transaction, and the stamp is written as DELETE + INSERT rather than
+UPDATE because a version-0 database has no version row to update yet.
+An UPDATE form would silently match zero rows there and leave the
+database migrated but unstamped — reporting version 0 forever, and
+re-applying migration 1 on every startup.  The DELETE+INSERT shape is
+also what makes the stamp a replace, so the row never duplicates.
+
+Idempotence across restarts: a database already at the latest version
+has no pending migrations, so the runner opens a read-only check, finds
+nothing to do, and leaves the file byte-untouched (no write transaction
+is opened, so no WAL churn).
+
+Migration list policy: entries are append-only.  Once shipped, a
+migration's SQL must never be edited — an old database applying it for
+the first time and a fresh database would then diverge.  Fix-forward
+with a new migration instead.  The version stamp lives in the same
+SQLite file as the data it describes, so restoring a backup restores
+its matching schema version with it.
+
+Corrupt or missing files are not this module's concern: startup
+handling of those cases is task d5bca74b, which decides whether to
+open fresh or raise ConfigEntryNotReady.  This runner assumes it is
+handed an open, working connection.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Sequence
+
+from .db import NestQuestDatabase
+from .schema import SCHEMA_V1_STATEMENTS
+
+LOGGER = logging.getLogger(__name__)
+
+#: Metadata table holding the applied schema version.  Prefixed with the
+#: integration domain so a config directory shared with other tools can
+#: never collide with a foreign ``schema_version`` table.
+VERSION_TABLE = "nestquest_schema_version"
+
+#: DDL for the version metadata table.  The singleton-row invariant is
+#: enforced by the schema itself: ``id`` is fixed at 1 by CHECK, keyed
+#: PRIMARY KEY, so the table can never hold a second row, and the
+#: stamp write is an UPDATE (no DELETE+INSERT needed).  ``version`` is
+#: a positive integer: version 0 means "no row" and is never stored,
+#: so a negative or zero stored value is corruption, not a state the
+#: runner can act on.
+VERSION_TABLE_DDL = f"""
+    CREATE TABLE IF NOT EXISTS {VERSION_TABLE} (
+        id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
+        version INTEGER NOT NULL CHECK (version >= 1)
+    )
+"""
+
+#: One-based index into :data:`MIGRATIONS`: entry ``n`` upgrades
+#: version ``n-1`` to version ``n``.
+MIGRATION_1_V1_DDL: list[str] = list(SCHEMA_V1_STATEMENTS)
+
+#: The ordered migration list.  Append-only: never edit an applied
+#: entry, add the next one instead.
+MIGRATIONS: Sequence[Sequence[str]] = [
+    MIGRATION_1_V1_DDL,
+]
+
+
+async def _create_version_table(database: NestQuestDatabase) -> None:
+    """Create the version metadata table if it does not exist.
+
+    The table is created before any version check: it is the runner's
+    own bookkeeping, and creating it is idempotent.  The DDL enforces
+    the singleton-row invariant (``id`` fixed at 1) and a positive
+    integer version at the database level.
+    """
+    await database.execute(VERSION_TABLE_DDL)
+
+
+async def read_schema_version(database: NestQuestDatabase) -> int:
+    """Return the schema version recorded in the database.
+
+    Returns 0 when the version table or its row is missing — the
+    "fresh file" case.  A stored version higher than the runner knows
+    is surfaced as-is; the caller decides how to treat a future version.
+
+    Reading is deliberately passive: a missing table raises, it is not
+    swallowed into 0, because :func:`apply_migrations` always creates
+    the table before reading and a direct reader hitting "no such
+    table" is a caller bug worth surfacing, not a fresh file.
+    """
+    row = await database.fetch_one(
+        f"SELECT version FROM {VERSION_TABLE} LIMIT 1"
+    )
+    if row is None:
+        return 0
+    version = row[0]
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise RuntimeError(
+            f"Schema version metadata is not an integer: {version!r}"
+        )
+    if version < 1:
+        raise RuntimeError(
+            f"Schema version metadata is invalid (must be >= 1): {version!r}"
+        )
+    return version
+
+
+#: One asyncio.Lock per connection wrapper, created lazily and bound to
+#: the running loop, serializing whole apply_migrations runs so two
+#: concurrent callers on one connection queue instead of colliding on
+#: the wrapper's single-transaction rule.
+_MIGRATION_LOCKS: dict[int, asyncio.Lock] = {}
+
+
+def _migration_lock(database: NestQuestDatabase) -> asyncio.Lock:
+    """Return the migration lock bound to ``database``'s running loop."""
+    loop = asyncio.get_running_loop()
+    key = (id(database), id(loop))
+    lock = _MIGRATION_LOCKS.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _MIGRATION_LOCKS[key] = lock
+    return lock
+
+
+async def apply_migrations(
+    database: NestQuestDatabase,
+    migrations: Sequence[Sequence[str]] = MIGRATIONS,
+) -> int:
+    """Bring the database schema up to the latest version.
+
+    Reads the current version, applies every pending migration in order
+    — each inside one transaction that also stamps the new version —
+    and returns the resulting version.  Applying zero pending
+    migrations (database already current) is a no-op that logs at debug
+    level and opens no write transaction.
+
+    The version is re-read inside each migration transaction before
+    deciding to apply it: the outer read is advisory only (loop bounds,
+    no-op fast path), and on one shared connection two interleaved
+    runners would otherwise both read the same version and both apply
+    a non-idempotent migration.  Under the transaction's lock the
+    second runner sees the first runner's stamp and skips.
+
+    Runners on one connection are serialized by an asyncio lock held
+    for the whole decide-and-apply span: NestQuestDatabase rejects a
+    second transaction while one is active (RuntimeError), so
+    concurrent callers must queue, and the lock makes that queueing
+    explicit.  The loser of the race re-reads the version once it
+    acquires the lock, sees the winner's stamp, and applies nothing.
+
+    Raises whatever the failing migration raised, with the database
+    rolled back to its prior version and prior rows untouched.
+    """
+    async with _migration_lock(database):
+        await _create_version_table(database)
+        current = await read_schema_version(database)
+        latest = len(migrations)
+
+        if current > latest:
+            raise RuntimeError(
+                f"Database schema version {current} is newer than this "
+                f"integration understands (latest known: {latest}); "
+                "downgrades are not supported"
+            )
+
+        if current == latest:
+            LOGGER.debug(
+                "NestQuest schema already at version %d; "
+                "no migrations to apply",
+                current,
+            )
+            return current
+
+        for target in range(current + 1, latest + 1):
+            applied = False
+            async with database.transaction():
+                # Re-read the version INSIDE the write transaction: the
+                # outer read was advisory, and the wrapper serializes
+                # individual statements, not the read-decide-apply
+                # decision.  Under the transaction's lock the version
+                # cannot change between the read and the stamp, and the
+                # loser of an interleaved race (a queued second caller
+                # re-running apply_migrations after the winner already
+                # migrated) re-reads here, sees the winner's stamp, and
+                # skips instead of re-applying a non-idempotent
+                # migration with a stale version.
+                in_tx_version = await read_schema_version(database)
+                if in_tx_version > latest:
+                    raise RuntimeError(
+                        f"Database schema version {in_tx_version} is newer "
+                        f"than this integration understands (latest known: "
+                        f"{latest}); downgrades are not supported"
+                    )
+                if in_tx_version < target:
+                    for sql in migrations[target - 1]:
+                        await database.execute(sql)
+                    # INSERT keyed on the singleton row (id = 1): a
+                    # fresh file has no row yet, and migration 1 is the
+                    # only migration a version-0 database can run, so
+                    # the row is seeded by the same statement batch
+                    # when needed.  UPDATE alone would silently match
+                    # zero rows there.
+                    await database.execute(
+                        f"INSERT INTO {VERSION_TABLE} (id, version) "
+                        "VALUES (1, ?) "
+                        "ON CONFLICT (id) DO UPDATE SET version = "
+                        "excluded.version",
+                        (target,),
+                    )
+                    applied = True
+            if applied:
+                LOGGER.info(
+                    "NestQuest schema migrated to version %d "
+                    "(%d statement%s)",
+                    target,
+                    len(migrations[target - 1]),
+                    "s" if len(migrations[target - 1]) != 1 else "",
+                )
+
+        return latest

custom_components/nestquest/schema.py

@@ -0,0 +1,336 @@
+"""Declarative schema DDL for the NestQuest SQLite database.
+
+Every v1 table is declared here as plain SQL statements so later schema
+tasks can append their own DDL to :data:`SCHEMA_V1_STATEMENTS` without
+touching this module's tables.  All statements use
+``CREATE TABLE IF NOT EXISTS`` so application is idempotent; the versioned
+migration runner is a separate later concern.
+
+Timestamp policy: all timestamps are UTC ISO-8601 strings, set by the
+caller/DAO rather than a DB default, per the feature guardrails.  No
+``length(created_at) = 25`` CHECK is added: the exact string shape
+produced by callers is not fixed yet (``datetime.isoformat()`` may
+include microseconds, changing the length), so enforcing a fixed length
+here would reject valid values.  Only non-null is enforced for now.
+
+Date policy: ``start_date``/``end_date`` are ISO date strings (YYYY-MM-DD,
+no time component) compared lexically by the ``end_date >= start_date``
+CHECK; due_date/due_time string shapes are caller-validated by the rule
+engine and DAO layers, not by DDL.
+
+``weekday_set`` format: comma-separated weekday integers (CSV), 0 =
+Monday .. 6 = Sunday, e.g. ``'0,2,4'`` for Mon/Wed/Fri.  Chosen over JSON
+because it sorts, compares and parses trivially in SQL.  The format is
+enforced at the DB level: a CHECK matches ``weekday_set`` against GLOB
+patterns for element counts 1..7 of single digits 0-6 (GLOB has no
+repetition quantifier, so the element count is enumerated; more than 7
+elements is impossible for a weekday set).  ``''``, ``'x'``, ``'7'`` and
+``'0,x'`` are all rejected; NULL stays allowed for non-weekly rules.
+This keeps the schema layer storage-only — the DAO layer (tasks
+8c72300c+) does not need its own validator, it can rely on the CHECK.
+
+Type affinity: SQLite applies column affinity on insert, but CHECKs
+still observe text and fractional values ('abc' stays text, '1.5'
+becomes REAL), so every INTEGER column carrying rule semantics carries
+a ``typeof(...) = 'integer'`` guard in its CHECK.
+
+Rule-type coherence: two CHECKs enforce that ``weekly`` carries a
+non-null ``weekday_set``, ``monthly`` carries a ``day_of_month`` or an
+``nth_weekday``, ``yearly`` carries a ``month``, and ``daily``/``custom``
+carry none of the month-specific fields.  Relaxed deliberately: the DDL
+does NOT forbid ``month`` on weekly/monthly rules (an "every 2 weeks"
+rule or a monthly rule could later be pinned to a month) nor extra
+fields on weekly/monthly/yearly rules generally, so the CHECKs only
+reject what the rule engine definitively cannot express now.
+
+Presence pattern format: ``presence_schedules.pattern`` encodes the
+whole N-week repeating cycle in one TEXT column as pipe-separated
+segments, one per week of the cycle: segment ``i`` is a ``weekday_set``
+CSV (same single-digit 0-6 convention as ``schedule_rules.weekday_set``)
+for week ``i``, e.g. ``'0,2,4|1,3'`` = Mon/Wed/Fri in week 0, Tue/Thu in
+week 1.  An empty segment means the child is absent every day of that
+week; a wholly empty pattern with ``cycle_length_weeks = 1`` means
+absent every day of every week, which is distinct from having no
+schedule row at all (a child with no schedule is present every day, per
+the feature guardrails).  Chosen over JSON or per-week rows to stay
+consistent with the CSV ``weekday_set`` convention and fully checkable
+by plain CHECKs.  DB-level validation is pure CHECK, no triggers or
+custom functions: char-class GLOBs reject every character outside
+digits 0-6, comma and pipe; adjacency GLOBs reject empty elements
+(double comma, comma next to a pipe, leading/trailing comma) and
+two-digit runs; a further GLOB rejects contiguous runs of 8+ comma
+separated digits, which caps a segment at 7 elements — the GLOB cannot
+match across a ``|``, so cross-segment boundaries stay safe; and the
+segment count is pinned to ``cycle_length_weeks`` by
+``LENGTH(pattern) - LENGTH(REPLACE(pattern, '|', '')) + 1``.  Per
+weekday_set this is not full CSV-set normalisation (duplicates like
+``'0,0'`` or unsorted sets stay storable, as with ``schedule_rules``);
+the engine treats the segment as a set.  A
+one-row-per-``week_index`` normalization was considered and rejected:
+the flat single-column encoding keeps the done-condition's table shape
+and proved fully checkable with plain CHECKs.
+
+``cycle_length_weeks`` is capped at 4: 2 (alternating weeks) is the
+common case, and a small cap keeps anchor arithmetic and the encoded
+pattern human-readable.  Revisit the cap — and re-run the pattern
+validation matrix in tests — if a longer cycle is ever needed.
+``anchor_date`` is an ISO date string pinning the cycle: the week index
+of a date is (days since anchor) // 7 mod ``cycle_length_weeks``,
+computed by the presence engine (Feature 05) from anchor-date
+arithmetic, never ISO week parity.  Like other date columns it carries
+no shape CHECK, matching the established date policy.
+
+Presence overrides: ``presence_overrides.end_date`` is NOT NULL,
+unlike ``schedule_rules.end_date`` — an override is always a concrete
+date range; a single-day override stores the same date in both columns.
+``is_present`` 0/1 marks the child absent/present for the whole range;
+``note`` is optional free text.
+
+Task instances: ``task_instances`` deliberately carries NO completion
+status column.  An instance's current state derives from the latest row
+in ``completion_events`` (Feature 08), so materialization (Feature 07)
+can insert instances without knowing anything about completion and the
+append-only log stays the single source of truth.  ``definition_id``,
+``due_date`` and ``child_id`` snapshot the materialization-time facts
+("why this instance exists"): reassignment and rule edits change future
+instances only and never rewrite these rows.  ``due_time`` snapshots
+the definition's optional due time at generation for the same reason —
+the instance keeps its generation-time value even if the definition is
+edited later.  ``generated_at`` is a caller-set UTC ISO-8601 timestamp
+per the module timestamp policy (no DB default, so a generation batch
+stamps one coherent time).
+
+Uniqueness: the (definition_id, due_date) pair is declared as a
+table-level ``UNIQUE`` constraint rather than a separate ``CREATE
+UNIQUE INDEX`` statement.  SQLite materializes it as an implicit unique
+index (``sqlite_autoindex_task_instances_1``) — the required "unique
+index prevents duplicate instances" — and the constraint form cannot be
+silently dropped the way a standalone index can, so the duplicate door
+stays shut.  Idempotent materialization keys on exactly this pair.  No
+secondary indexes beyond it are declared yet: history and board queries
+(Features 08/10/13) should justify their indexes as a later migration
+once their query shapes exist.
+
+No ``ON DELETE`` clauses are declared on any foreign key in this
+module: children and definitions are deactivated, never deleted, so a
+deletion that would orphan instances or events is a bug and must fail
+loudly rather than cascade.
+
+Completion events: ``completion_events`` is strictly append-only.  That
+property is enforced at the DAO layer — the completion-events DAO
+exposes no UPDATE or DELETE path (task a9ea75fc) — and deliberately NOT
+by database triggers, matching the module's no-trigger policy: a RAISE
+trigger would be the one exception to "pure CHECK, no triggers",
+complicate the later migration runner, and still prove nothing (any
+writer can run raw SQL).  ``event_type`` is constrained to
+``completed``/``uncompleted``; a ``missed`` row is intentionally not
+representable — missed is a derived state announced on the HA event bus
+(Feature 10), never an appended event.
+
+``child_id`` is deliberately denormalized (it is also derivable via
+``task_instances``): history reporting (Feature 13) filters and rates
+per child directly against the log, and the log should stay
+self-describing without joins.
+
+Actor policy: ``actor_source`` distinguishes an authenticated HA user
+(``'user'``, with ``actor_user_id`` holding the HA user id) from a
+panel tap with no user context (``'panel'``, with ``actor_user_id``
+NULL — the tapped child profile is already ``child_id``).  A coherence
+CHECK makes the pair shape non-negotiable: ``'user'`` requires
+``actor_user_id``, ``'panel'`` forbids it.  Other actor sources are
+rejected; if an unattended system actor is ever needed, that is a
+schema migration, not a silent widening.
+
+On-time policy: ``was_on_time`` is required (integer 0 or 1) for
+``completed`` events — at completion time the due date is known and the
+flag is decidable.  For ``uncompleted`` events the flag is optional:
+Feature 08 decides whether a reversal carries the reversed completion's
+on-time flag or NULL, and the DDL deliberately accepts both rather than
+guessing.
+"""
+from __future__ import annotations
+
+from .db import NestQuestDatabase
+
+#: GLOB patterns matching a valid ``weekday_set`` CSV: one GLOB per
+#: possible element count 1..7 (a weekday set cannot exceed 7 elements).
+#: Each element is a single digit 0-6, separated by a literal comma.
+#: GLOB has no repetition quantifier, so the element count is enumerated.
+#: ``''`` and NULL are deliberately NOT matched: NULL is allowed for
+#: non-weekly rules via a separate ``IS NULL`` arm, and '' is invalid
+#: because weekly rules need at least one weekday.
+WEEKDAY_SET_GLOB_PATTERNS: list[str] = [
+    "[0-6]",
+    "[0-6],[0-6]",
+    "[0-6],[0-6],[0-6]",
+    "[0-6],[0-6],[0-6],[0-6]",
+    "[0-6],[0-6],[0-6],[0-6],[0-6]",
+    "[0-6],[0-6],[0-6],[0-6],[0-6],[0-6]",
+    "[0-6],[0-6],[0-6],[0-6],[0-6],[0-6],[0-6]",
+]
+
+SCHEMA_V1_CHILDREN_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS children (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        display_name TEXT NOT NULL,
+        colour TEXT,
+        avatar_ref TEXT,
+        sort_order INTEGER NOT NULL DEFAULT 0 CHECK (typeof(sort_order) = 'integer'),
+        is_active INTEGER NOT NULL DEFAULT 1 CHECK (typeof(is_active) = 'integer' AND is_active IN (0, 1)),
+        created_at TEXT NOT NULL
+    )
+    """,
+]
+
+SCHEMA_V1_ADMIN_USERS_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS admin_users (
+        ha_user_id TEXT PRIMARY KEY NOT NULL,
+        added_at TEXT NOT NULL
+    )
+    """,
+]
+
+_WEEKDAY_SET_CHECK = " OR ".join(
+    f"weekday_set GLOB '{pattern}'" for pattern in WEEKDAY_SET_GLOB_PATTERNS
+)
+
+SCHEMA_V1_SCHEDULE_RULES_DDL: list[str] = [
+    f"""
+    CREATE TABLE IF NOT EXISTS schedule_rules (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        rule_type TEXT NOT NULL CHECK (rule_type IN ('daily', 'weekly', 'monthly', 'yearly', 'custom')),
+        interval INTEGER NOT NULL DEFAULT 1 CHECK (typeof(interval) = 'integer' AND interval >= 1),
+        weekday_set TEXT CHECK (weekday_set IS NULL OR ({_WEEKDAY_SET_CHECK})),
+        day_of_month INTEGER CHECK (day_of_month IS NULL OR (typeof(day_of_month) = 'integer' AND day_of_month >= 1 AND day_of_month <= 31)),
+        nth_weekday INTEGER CHECK (nth_weekday IS NULL OR (typeof(nth_weekday) = 'integer' AND nth_weekday IN (-1, 1, 2, 3, 4, 5))),
+        month INTEGER CHECK (month IS NULL OR (typeof(month) = 'integer' AND month >= 1 AND month <= 12)),
+        start_date TEXT NOT NULL,
+        end_date TEXT,
+        CHECK (end_date IS NULL OR end_date >= start_date),
+        CHECK (
+            (rule_type = 'weekly' AND weekday_set IS NOT NULL)
+            OR (rule_type = 'monthly' AND (day_of_month IS NOT NULL OR nth_weekday IS NOT NULL))
+            OR (rule_type = 'yearly' AND month IS NOT NULL)
+            OR (rule_type IN ('daily', 'custom') AND day_of_month IS NULL AND nth_weekday IS NULL AND month IS NULL)
+        )
+    )
+    """,
+]
+
+SCHEMA_V1_TASK_DEFINITIONS_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS task_definitions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        title TEXT NOT NULL,
+        description TEXT,
+        icon TEXT,
+        child_id INTEGER NOT NULL REFERENCES children(id),
+        schedule_rule_id INTEGER NOT NULL REFERENCES schedule_rules(id),
+        due_time TEXT,
+        is_active INTEGER NOT NULL DEFAULT 1 CHECK (typeof(is_active) = 'integer' AND is_active IN (0, 1)),
+        created_at TEXT NOT NULL
+    )
+    """,
+]
+
+SCHEMA_V1_PRESENCE_SCHEDULES_DDL: list[str] = [
+    f"""
+    CREATE TABLE IF NOT EXISTS presence_schedules (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        child_id INTEGER NOT NULL UNIQUE REFERENCES children(id),
+        cycle_length_weeks INTEGER NOT NULL CHECK (typeof(cycle_length_weeks) = 'integer' AND cycle_length_weeks >= 1 AND cycle_length_weeks <= 4),
+        anchor_date TEXT NOT NULL,
+        pattern TEXT NOT NULL CHECK (
+            NOT pattern GLOB '*[^0-6,|]*'
+            AND NOT pattern GLOB '*[0-6][0-6]*'
+            AND NOT pattern GLOB '*,,*'
+            AND NOT pattern GLOB '*,|*'
+            AND NOT pattern GLOB '*|,*'
+            AND NOT pattern GLOB ',*'
+            AND NOT pattern GLOB '*,'
+            AND NOT pattern GLOB '*[0-6],[0-6],[0-6],[0-6],[0-6],[0-6],[0-6],[0-6]*'
+            AND (LENGTH(pattern) - LENGTH(REPLACE(pattern, '|', '')) + 1) = cycle_length_weeks
+        )
+    )
+    """,
+]
+
+SCHEMA_V1_PRESENCE_OVERRIDES_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS presence_overrides (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        child_id INTEGER NOT NULL REFERENCES children(id),
+        start_date TEXT NOT NULL,
+        end_date TEXT NOT NULL,
+        is_present INTEGER NOT NULL CHECK (typeof(is_present) = 'integer' AND is_present IN (0, 1)),
+        note TEXT,
+        CHECK (end_date >= start_date)
+    )
+    """,
+]
+
+SCHEMA_V1_TASK_INSTANCES_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS task_instances (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        definition_id INTEGER NOT NULL REFERENCES task_definitions(id),
+        child_id INTEGER NOT NULL REFERENCES children(id),
+        due_date TEXT NOT NULL,
+        due_time TEXT,
+        generated_at TEXT NOT NULL,
+        UNIQUE (definition_id, due_date)
+    )
+    """,
+]
+
+SCHEMA_V1_COMPLETION_EVENTS_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS completion_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        instance_id INTEGER NOT NULL REFERENCES task_instances(id),
+        child_id INTEGER NOT NULL REFERENCES children(id),
+        event_type TEXT NOT NULL CHECK (event_type IN ('completed', 'uncompleted')),
+        actor_source TEXT NOT NULL CHECK (actor_source IN ('user', 'panel')),
+        actor_user_id TEXT,
+        occurred_at TEXT NOT NULL,
+        was_on_time INTEGER CHECK (
+            was_on_time IS NULL
+            OR (typeof(was_on_time) = 'integer' AND was_on_time IN (0, 1))
+        ),
+        CHECK (
+            (actor_source = 'user' AND actor_user_id IS NOT NULL)
+            OR (actor_source = 'panel' AND actor_user_id IS NULL)
+        ),
+        CHECK (
+            (event_type = 'completed' AND was_on_time IS NOT NULL)
+            OR (event_type = 'uncompleted')
+        )
+    )
+    """,
+]
+
+SCHEMA_V1_STATEMENTS: list[str] = [
+    *SCHEMA_V1_CHILDREN_DDL,
+    *SCHEMA_V1_ADMIN_USERS_DDL,
+    *SCHEMA_V1_SCHEDULE_RULES_DDL,
+    *SCHEMA_V1_TASK_DEFINITIONS_DDL,
+    *SCHEMA_V1_PRESENCE_SCHEDULES_DDL,
+    *SCHEMA_V1_PRESENCE_OVERRIDES_DDL,
+    *SCHEMA_V1_TASK_INSTANCES_DDL,
+    *SCHEMA_V1_COMPLETION_EVENTS_DDL,
+]
+
+
+async def async_apply_ddl(
+    database: NestQuestDatabase, statements: list[str]
+) -> None:
+    """Apply each DDL statement inside one transaction on ``database``.
+
+    Idempotent: every statement is ``CREATE TABLE IF NOT EXISTS``, so
+    applying the same list twice leaves the schema and its rows intact.
+    """
+    async with database.transaction():
+        for sql in statements:
+            await database.execute(sql)