SSE: publish uncompleted, child-day-complete and missed transitions

The panel stream so far carried only quest-completed. This adds the
three remaining documented transitions (§3) so the panel UI can react
to reversals, full days, and nightly misses through the same ONE
publisher:

- core/events.py gains build_quest_missed_event, mirroring the
  sweep's hand-built payload exactly (shared _instance_payload shape),
  so the API plane publishes the same shape the integration sweep fires.
- api/transitions.py adds the reusable publish helpers the later
  uncomplete route (da0226b3) and the API-side missed sweep will call;
  payloads are always built by the core builders, never hand-built.
- The panel complete route now evaluates the day-complete rule on an
  actual transition, off the completed event's payload and the route's
  single clock read; the core builder still decides, so a zero-quest
  day and a non-today instance never fire it and a no-op re-complete
  publishes nothing.
- Tests drive all three transitions through the real SSE stream
  (server-loop scheduling for the not-yet-routed helpers) and assert
  every documented payload field.

RELEASE_NOTES.md

@@ -13,6 +13,15 @@
   logger name (e.g. in `logger.yaml` or `configuration.yaml`) must
   update the entry to keep that level, as the old name no longer
   receives migration log output.
+- **Additional logger namespace moves:** the children registry and the
+  admin allowlist business layers now log under
+  `custom_components.nestquest.core.children` and
+  `custom_components.nestquest.core.admin_allowlist` respectively
+  (moved with the engines/business-layer extraction, task 510c1f78).
+  The parent `custom_components.nestquest` logger still catches both,
+  so users who tune the parent rather than the leaf names are
+  unaffected; only users who pinned a leaf logger name by its old
+  spelling need to update.
 
 ## Version 0.5.0 — 2026-09-18
 

api/__init__.py

@@ -0,0 +1,19 @@
+"""NestQuest API service.
+
+A standalone FastAPI deployable that owns the NestQuest database and
+exposes it over HTTP to the Home Assistant integration (panel plane) and
+the admin PWA (admin plane).  See Feature 16 (task cd03735b) in the
+project tracker for the full contract.
+
+This package imports the NestQuest domain ``core`` WITHOUT executing
+``custom_components/nestquest/__init__.py`` — that parent package's
+``__init__.py`` imports ``homeassistant``, which is absent from the
+API's runtime.  The coupling is encapsulated in
+:mod:`api.nestquest_core`, which loads ``core`` by file location with
+:mod:`importlib.util` and registers it under the distinct top-level name
+``nestquest_core`` (no ``sys.path`` mutation, no generic top-level
+names published).  It is a TRANSITIONAL coupling that Feature 18 will
+revisit: once the integration becomes a thin API client and ``core``
+moves out of the integration bundle, this helper goes away.
+"""
+from __future__ import annotations

api/app.py

@@ -0,0 +1,115 @@
+"""The NestQuest FastAPI application.
+
+This module builds the ASGI app for the NestQuest API service (Feature
+16).  The skeleton here wires the bundled ``core`` (Feature 15) and
+exposes the two endpoints every later task depends on:
+
+- ``GET /health`` — returns ``200`` with a JSON status body once the
+  app has imported core, opened the database, and applied migrations;
+  a cheap ``SELECT 1`` confirms the connection is live without leaking
+  the filesystem path on an unauthenticated route.
+- ``GET /api/v1/panel/snapshot`` — the panel plane's today snapshot
+  (service-token protected; see :mod:`api.routes_panel`, whose router
+  carries the shared :func:`api.dependencies.require_panel_token`
+  check).
+- ``GET /docs`` — FastAPI's auto-served OpenAPI document (Swagger UI);
+  ``/openapi.json`` is the raw schema.  No extra wiring is needed;
+  FastAPI serves both by default.
+
+The database is opened and migrated in a FastAPI lifespan context so a
+startup failure (e.g. an unwritable path) surfaces as a startup error
+rather than the first request.  The connection is closed on shutdown.
+
+This module exports ONLY the :func:`create_app` factory — there is no
+module-level app instance, because building one at import time would
+read ``NESTQUEST_DB_PATH`` at import (and fail-fast on a missing value)
+before any worker is ready to report it.  Serve with::
+
+    uvicorn --factory api.app:create_app
+
+so the factory runs on each worker startup and reads the environment
+then.
+"""
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+
+from api.config import ApiConfig
+from api.database import DatabaseState, make_database
+from api.events import TransitionPublisher
+from api.routes_panel import router as panel_router
+
+
+def _build_lifespan(db_path: str):
+    """Return a lifespan that opens+migrates then closes one database.
+
+    Captured as a closure so the app factory can hand the configured
+    path in without threading it through FastAPI's lifespan signature.
+    The lifespan also installs the app's ONE in-process transition
+    publisher on ``app.state.publisher`` (see :mod:`api.events`) so
+    every route and SSE subscriber shares that single instance.
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        state = make_database(db_path)
+        app.state.db = state
+        app.state.publisher = TransitionPublisher()
+        try:
+            await state.open_and_migrate()
+            yield
+        finally:
+            await state.close()
+
+    return lifespan
+
+
+def create_app(config: ApiConfig | None = None) -> FastAPI:
+    """Build the NestQuest API FastAPI app.
+
+    ``config`` defaults to one built from the process environment, so
+    ``uvicorn --factory api.app:create_app`` picks up
+    ``NESTQUEST_DB_PATH`` (and fails fast on startup if it is missing).
+    Tests pass an explicit config so each test gets a hermetic temp
+    SQLite file.
+    """
+    cfg = config if config is not None else ApiConfig.from_env()
+
+    app = FastAPI(
+        title="NestQuest API",
+        description=(
+            "Standalone HTTP service that owns the NestQuest database and "
+            "exposes it to the Home Assistant integration (panel plane) and "
+            "the admin PWA (admin plane)."
+        ),
+        version="0.1.0",
+        lifespan=_build_lifespan(cfg.db_path),
+    )
+
+    # The resolved config rides on app.state so the reusable route
+    # dependencies (the panel service-token check) read the configured
+    # values from the app rather than module state.
+    app.state.config = cfg
+    app.include_router(panel_router)
+
+    @app.get("/health", summary="Service health")
+    async def health() -> dict[str, str]:
+        """Return service health.
+
+        Returns ``200`` with ``{"status": "ok"}`` once the lifespan has
+        opened and migrated the database.  A cheap ``SELECT 1`` against
+        the live connection confirms the database is reachable WITHOUT
+        leaking the filesystem path on an unauthenticated route; if the
+        connection is dead the query raises and the probe fails.
+        """
+        state: DatabaseState = app.state.db
+        await state.database.fetch_one("SELECT 1")
+        return {"status": "ok"}
+
+    return app
+
+
+__all__ = ["create_app"]

api/config.py

@@ -0,0 +1,98 @@
+"""Configuration for the NestQuest API service.
+
+The API reads its configuration knobs from environment variables:
+
+- ``NESTQUEST_DB_PATH`` — the SQLite database file.  The API opens this
+  file on startup (creating it if absent) and applies migrations.
+- ``NESTQUEST_PANEL_TOKEN`` — the static panel-plane service token
+  (D-012): the credential ``/api/v1/panel/*`` routes require via
+  :func:`api.dependencies.require_panel_token`.  It is stored outside
+  the repo and handed to the service through the environment.
+
+Unlike a dev convenience default, a missing or empty value is a
+configuration ERROR, not a silent fallback: a default database path
+would silently drop data at reboot, and a default (or empty) service
+token would either authenticate everyone or lock the panel plane out
+for good.  ``ApiConfig.from_env`` therefore RAISES when either variable
+is unset or empty.  This mirrors the integration's "explicit settings
+object" discipline (Feature 15's ``core.settings``): the API never
+reads HA config; callers pass the resolved values into the wiring.
+
+Serving: the app is built with the factory ``api.app:create_app`` — run
+it with ``uvicorn --factory api.app:create_app`` so the factory reads
+the environment on each worker startup rather than at import time.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+#: Environment variable holding the SQLite file path.  The API opens
+#: this file on startup (creating it if absent) and applies migrations.
+#: REQUIRED — unset or empty raises :class:`ConfigError` from
+#: :meth:`ApiConfig.from_env`.
+DB_PATH_ENV = "NESTQUEST_DB_PATH"
+
+#: Environment variable holding the static panel-plane service token
+#: (D-012), checked by :func:`api.dependencies.require_panel_token`.
+#: REQUIRED — unset or empty raises :class:`ConfigError` from
+#: :meth:`ApiConfig.from_env`; there is no silent default, because an
+#: empty configured token would either authenticate every caller or
+#: lock the panel plane out permanently.
+PANEL_TOKEN_ENV = "NESTQUEST_PANEL_TOKEN"
+
+
+class ConfigError(RuntimeError):
+    """Raised when required API configuration is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class ApiConfig:
+    """Resolved API configuration.
+
+    Both fields are required (no defaults): ``from_env`` rejects an
+    unset or empty value for either, and a caller building the dataclass
+    directly must pass an explicit token — the token check itself fails
+    closed on an empty configured token, but expecting a caller to
+    discover that at request time is a wiring mistake, so the field is
+    mandatory.  Kept as a dataclass so later tasks (admin plane, SSE,
+    settings persistence) can extend it without touching the call sites
+    that read ``db_path``.
+    """
+
+    db_path: str
+    panel_token: str
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "ApiConfig":
+        """Build configuration from the process environment.
+
+        ``env`` defaults to ``os.environ``; tests pass an explicit dict
+        so they are hermetic (no monkeypatch of the global environ).
+
+        Raises :class:`ConfigError` when ``NESTQUEST_DB_PATH`` is unset
+        or empty/whitespace-only — there is no silent default, because a
+        default in the temp directory would silently lose data at reboot
+        — and likewise when ``NESTQUEST_PANEL_TOKEN`` is unset or empty
+        (a default token is never invented: the panel plane is closed
+        until a real one is configured).
+        """
+        source = env if env is not None else os.environ
+        raw_db_path = source.get(DB_PATH_ENV, "").strip()
+        if not raw_db_path:
+            raise ConfigError(
+                f"{DB_PATH_ENV} must be set to a writable SQLite file path "
+                f"(it is unset or empty — the API will not fall back to a "
+                f"temp directory and silently lose data)"
+            )
+        raw_panel_token = source.get(PANEL_TOKEN_ENV, "").strip()
+        if not raw_panel_token:
+            raise ConfigError(
+                f"{PANEL_TOKEN_ENV} must be set to the panel service token "
+                f"(it is unset or empty — the API will not start without "
+                f"one, and no default token is invented)"
+            )
+        return cls(db_path=raw_db_path, panel_token=raw_panel_token)
+
+
+__all__ = ["ApiConfig", "ConfigError", "DB_PATH_ENV", "PANEL_TOKEN_ENV"]

api/database.py

@@ -0,0 +1,82 @@
+"""Database wiring for the NestQuest API service.
+
+The API owns the database (it is the writer of record per Feature 16's
+contract).  This module owns one application-lifetime
+:class:`core.db.NestQuestDatabase`: it opens the SQLite file at the
+configured path on startup, applies migrations (creating the schema on
+a fresh file), and closes the connection on shutdown.
+
+The executor callable passed into ``NestQuestDatabase`` mirrors the
+contract of ``hass.async_add_executor_job``: schedule a synchronous
+callable on a worker and await its result.  HA's own version lives on
+the event loop; the API is not HA, so it uses
+:func:`asyncio.to_thread` for the same effect — sqlite3 calls run on a
+worker thread and only plain data returns to the event loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from api.nestquest_core import core_db, core_migrations
+
+LOGGER = logging.getLogger(__name__)
+
+#: The async SQLite wrapper.  Re-exported so route handlers and later
+#: tasks reach it through the API package, not the bundled core.
+NestQuestDatabase = core_db.NestQuestDatabase
+
+#: The migration runner.  Re-exported for the same reason.
+apply_migrations = core_migrations.apply_migrations
+
+
+async def _executor(fn: Any, *args: Any, **kwargs: Any) -> Any:
+    """Run a synchronous callable on a worker thread and await its result.
+
+    Mirrors the contract of ``hass.async_add_executor_job`` so the
+    bundled ``NestQuestDatabase`` (written against that contract) works
+    unchanged in the API process: sqlite3 calls never block the event
+    loop, and only plain Python data (row tuples,
+    :class:`core.db.ExecutionResult`) crosses back.
+    """
+    return await asyncio.to_thread(fn, *args, **kwargs)
+
+
+class DatabaseState:
+    """Holds the live database wrapper and its resolved path.
+
+    A small container so the lifespan and the route handlers share one
+    authoritative reference; FastAPI's lifespan stores one of these on
+    ``app.state.db`` and the health route reads it back.
+    """
+
+    __slots__ = ("database", "db_path")
+
+    def __init__(self, database: NestQuestDatabase, db_path: str) -> None:
+        self.database = database
+        self.db_path = db_path
+
+    async def open_and_migrate(self) -> None:
+        """Open the connection and apply migrations to the latest version."""
+        LOGGER.info("Opening NestQuest database at %s", self.db_path)
+        await self.database.open(self.db_path)
+        version = await apply_migrations(self.database)
+        LOGGER.info("NestQuest schema at version %d", version)
+
+    async def close(self) -> None:
+        """Close the connection; safe to call even if open failed."""
+        await self.database.close()
+
+
+def make_database(db_path: str) -> DatabaseState:
+    """Construct a :class:`DatabaseState` for the given path (not yet open)."""
+    return DatabaseState(NestQuestDatabase(_executor), db_path)
+
+
+__all__ = [
+    "DatabaseState",
+    "NestQuestDatabase",
+    "apply_migrations",
+    "make_database",
+]

api/dependencies.py

@@ -0,0 +1,81 @@
+"""Reusable FastAPI dependencies for the NestQuest API routes.
+
+The panel plane (``/api/v1/panel/*``) is authenticated by the static
+service token configured through ``NESTQUEST_PANEL_TOKEN`` (D-012): the
+HA integration presents it as a Bearer credential on every panel
+request.  :func:`require_panel_token` is the ONE implementation of that
+check — every panel route (this task's snapshot route and each later
+panel route) declares it as a dependency rather than re-implementing
+token handling, so the credential, the failure behaviour, and the
+401 contract stay in exactly one place.
+
+The dependency FAILS CLOSED: a missing ``Authorization`` header, a
+malformed one (wrong scheme or empty credential), a token that does not
+match the configured value, and an empty configured token all yield
+HTTP 401.  The comparison is constant-time (:func:`secrets.compare_digest`)
+so the wall-clock difference between "wrong length" and "wrong value"
+cannot be used to probe the token byte by byte, and every rejection
+carries the same detail — nothing in the response distinguishes which
+part of the check failed.
+"""
+from __future__ import annotations
+
+import secrets
+from typing import Annotated
+
+from fastapi import Header, HTTPException, Request
+
+#: The authorization scheme the panel plane expects.  Matched
+#: case-insensitively, as RFC 9110 requires for scheme names.
+_BEARER_SCHEME = "bearer"
+
+#: The 401 detail shared by every rejection — deliberately uniform so
+#: the response never reveals which part of the check failed.
+_REJECTION_DETAIL = "Missing or invalid panel service token"
+
+#: Challenge header returned with a 401, per the Bearer auth scheme.
+_WWW_AUTHENTICATE = {"WWW-Authenticate": "Bearer"}
+
+
+def _reject() -> HTTPException:
+    """Build the single 401 the dependency raises for every failure."""
+    return HTTPException(
+        status_code=401,
+        detail=_REJECTION_DETAIL,
+        headers=_WWW_AUTHENTICATE,
+    )
+
+
+async def require_panel_token(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+) -> None:
+    """Reject the request with 401 unless it carries the panel token.
+
+    Reads the configured token off ``app.state.config`` (set by
+    :func:`api.app.create_app`) so the dependency stays reusable across
+    routes and carries no module state of its own.  A missing or
+    malformed ``Authorization`` header, a non-matching credential, and
+    an EMPTY configured token (a wiring mistake) all raise the same
+    ``HTTPException(401)`` — the check is closed even when the service
+    is misconfigured.
+
+    Returns ``None`` on success; FastAPI discards a ``None`` return,
+    the route handler simply proceeds.
+    """
+    config = getattr(request.app.state, "config", None)
+    expected = config.panel_token if config is not None else ""
+    if not expected or authorization is None:
+        raise _reject()
+    scheme, _, credential = authorization.partition(" ")
+    if scheme.lower() != _BEARER_SCHEME or not credential.strip():
+        raise _reject()
+    # compare_digest on bytes so a non-ASCII token raises nothing and a
+    # timing side channel on the str path is not available.
+    if not secrets.compare_digest(
+        credential.strip().encode("utf-8"), expected.encode("utf-8")
+    ):
+        raise _reject()
+
+
+__all__ = ["require_panel_token"]

api/events.py

@@ -0,0 +1,78 @@
+"""The ONE in-process transition-event publisher for the API service.
+
+Route handlers call :meth:`TransitionPublisher.publish` synchronously
+(no ``await``, callable from any async handler); SSE subscribers stream
+those transitions through an async generator.  The scope of "ONE" is
+deliberate: a single :class:`TransitionPublisher` instance is created
+in the app lifespan and stored on ``app.state.publisher`` — per-app,
+so tests build their own hermetic app without module-level state, and
+both the panel complete route and the SSE endpoint resolve the SAME
+instance off ``request.app.state`` (exactly one publisher exists per
+running app; nothing else may create one).
+
+Design (small and dependency-free, asyncio only):
+
+- Each subscriber gets its own ``asyncio.Queue(maxsize=64)``.
+- ``publish`` is synchronous and non-blocking: it puts the event on
+  every live queue with ``put_nowait``.  A slow subscriber that lets
+  its queue fill gets the event DROPPED (oldest overflow) — never a
+  blocked publisher, never unbounded growth.
+- A disconnected subscriber's queue is removed in the generator's
+  ``finally`` block, so teardown is clean and a closed consumer cannot
+  leak its queue.
+
+Fan-out is fire-and-forget by design: the SSE plane mirrors transition
+events for the panel UI; a dropped event costs the panel one UI
+refresh, and the documented recovery path is the next snapshot poll.
+"""
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+#: Per-subscriber queue capacity.  Bounded so a stalled consumer can
+#: never make the publisher or another subscriber wait; beyond this
+#: the slow subscriber drops the event (see module docstring).
+_QUEUE_MAXSIZE = 64
+
+__all__ = ["TransitionPublisher"]
+
+
+class TransitionPublisher:
+    """A single in-process fan-out point for transition events."""
+
+    def __init__(self) -> None:
+        """Create the publisher with no subscribers."""
+        self._subscribers: set[asyncio.Queue] = set()
+
+    def publish(self, event_type: str, payload: dict) -> None:
+        """Fan one transition event out to every current subscriber.
+
+        Synchronous and non-blocking: each subscriber's bounded queue
+        is filled with ``put_nowait``, and a FULL queue silently drops
+        the event for that (slow) subscriber rather than blocking the
+        route handler or growing without bound.
+        """
+        for queue in tuple(self._subscribers):
+            try:
+                queue.put_nowait((event_type, payload))
+            except asyncio.QueueFull:
+                # The subscriber is not keeping up; drop the event for
+                # it and move on (the panel recovers by polling).
+                pass
+
+    async def subscribe(self) -> AsyncIterator[tuple[str, dict]]:
+        """Yield ``(event_type, payload)`` tuples until the consumer breaks.
+
+        Registers ONE bounded queue for the duration of the iteration
+        and removes it in the ``finally`` block, so a client disconnect
+        (or any break out of the loop) tears the subscription down
+        cleanly with no leaked queue.
+        """
+        queue: asyncio.Queue = asyncio.Queue(maxsize=_QUEUE_MAXSIZE)
+        self._subscribers.add(queue)
+        try:
+            while True:
+                yield await queue.get()
+        finally:
+            self._subscribers.discard(queue)

api/nestquest_core.py

@@ -0,0 +1,135 @@
+"""Transitional coupling: import ``core`` without importing Home Assistant.
+
+The NestQuest domain ``core`` package (Feature 15) is bundled INSIDE the
+Home Assistant integration at ``custom_components/nestquest/core/``.
+Importing it the obvious way — ``import custom_components.nestquest.core``
+— would execute ``custom_components/nestquest/__init__.py``, which
+imports ``homeassistant``.  Home Assistant is NOT installed in the API
+service's runtime, so that import raises ``ModuleNotFoundError`` and the
+API cannot start.
+
+``core`` itself is a clean, Home-Assistant-free package: its
+``__init__.py`` is a bare docstring and every internal import is
+relative (``from .db import ...``).  It can therefore be imported by
+file location as a standalone package.
+
+This module loads ``core`` with :func:`importlib.util.spec_from_file_location`
+— registering it under the distinct top-level name ``nestquest_core``
+with ``submodule_search_locations`` set to the bundled ``core``
+directory — so its relative imports resolve against that directory
+without touching ``sys.path``.  No generic top-level name (``db``,
+``const``, ``schema``, ...) is published, so nothing here can silently
+shadow a future dependency, and the integration's HA-coupled
+``__init__.py`` is never executed: ``custom_components.nestquest`` is
+never imported.
+
+Usage::
+
+    from api.nestquest_core import core_db, core_migrations
+    # core_db.NestQuestDatabase, core_migrations.apply_migrations, ...
+
+This is a TRANSITIONAL coupling.  Feature 18 (task 430f7f98) converts
+the integration into a thin API client and moves ``core`` out of the
+integration bundle; once that lands, this bootstrap helper goes away and
+the API imports ``core`` as an ordinary installed dependency.
+
+NOTE on the pytest process: the suite's ``conftest.py`` stubs the
+parent integration package and imports ``custom_components.nestquest.core.*``
+BEFORE any API test runs, so two copies of the core package coexist in
+the pytest process — the one registered here as ``nestquest_core.*``
+(loaded by file location) and the conftest-stubbed
+``custom_components.nestquest.core.*``.  Later tasks must NOT compare
+class or exception identity across these two copies: a
+``nestquest_core.db.NestQuestDatabase`` is a DIFFERENT class object from
+``custom_components.nestquest.core.db.NestQuestDatabase`` even though
+they share source.  Operate on a single copy within any one code path.
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+#: The repository root (this file is ``<root>/api/nestquest_core.py``).
+_REPO_ROOT: Path = Path(__file__).resolve().parent.parent
+
+#: The bundled ``core`` package directory, inside the HA integration.
+_CORE_DIR: Path = _REPO_ROOT / "custom_components" / "nestquest" / "core"
+
+#: The ``core`` package's ``__init__.py`` — a bare docstring, so loading
+#: it by file location executes no imports of its own.
+_CORE_INIT: Path = _CORE_DIR / "__init__.py"
+
+#: The distinct top-level name under which the bundled ``core`` package
+#: is registered in ``sys.modules``.  A distinctive name (rather than the
+#: generic ``core``) avoids publishing shadow-able top-level names and
+#: keeps the bundled copy separate from the conftest-stubbed
+#: ``custom_components.nestquest.core`` present in the pytest process.
+_CORE_MODULE_NAME = "nestquest_core"
+
+
+def _load_core() -> ModuleType:
+    """Load the bundled ``core`` package by file location and return it.
+
+    Registers the package under :data:`_CORE_MODULE_NAME` in
+    ``sys.modules`` with ``submodule_search_locations`` pointing at the
+    bundled directory, so its relative imports (``from .db import ...``)
+    resolve to ``nestquest_core.<submodule>`` against that directory
+    without mutating ``sys.path``.  Idempotent: a second call returns
+    the already-registered module.
+    """
+    existing = sys.modules.get(_CORE_MODULE_NAME)
+    if existing is not None:
+        return existing
+    spec = importlib.util.spec_from_file_location(
+        _CORE_MODULE_NAME,
+        _CORE_INIT,
+        submodule_search_locations=[str(_CORE_DIR)],
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError(f"could not load core from {_CORE_INIT}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[_CORE_MODULE_NAME] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+#: The bundled core package, loaded by file location and registered as
+#: ``nestquest_core`` in ``sys.modules``.  Held here so callers import the
+#: submodules through it (``nestquest_core.db``, ``nestquest_core.migrations``)
+#: the same relative way the integration does.
+core: ModuleType = _load_core()
+
+#: Re-exported for convenience; route handlers import these names from
+#: here rather than reaching into the core package directly.
+core_db = importlib.import_module(f"{_CORE_MODULE_NAME}.db")
+core_migrations = importlib.import_module(f"{_CORE_MODULE_NAME}.migrations")
+
+#: The panel snapshot builder and its payload shaper
+#: (``core.snapshot.build_snapshot`` / ``instance_payload``) — the pure
+#: assembly the panel routes call.
+core_snapshot = importlib.import_module(f"{_CORE_MODULE_NAME}.snapshot")
+
+#: The completion service (``core.completion.complete_instance`` /
+#: ``uncomplete_instance``) the panel's write routes call.
+core_completion = importlib.import_module(f"{_CORE_MODULE_NAME}.completion")
+
+#: The transition-event builders (``core.events.build_quest_completed_event``
+#: et al.) the panel's write routes build their SSE events with.
+core_events = importlib.import_module(f"{_CORE_MODULE_NAME}.events")
+
+#: The explicit settings object (``core.settings.NestQuestSettings``)
+#: the snapshot builder's ``settings`` parameter takes.
+core_settings = importlib.import_module(f"{_CORE_MODULE_NAME}.settings")
+
+__all__ = [
+    "core",
+    "core_completion",
+    "core_db",
+    "core_events",
+    "core_migrations",
+    "core_snapshot",
+    "core_settings",
+]

api/routes_panel.py

@@ -0,0 +1,373 @@
+"""Panel-plane routes for the NestQuest API service.
+
+The panel plane (``/api/v1/panel/*``, D-012) serves the wall panel's
+reads.  Every route on :data:`router` requires the panel service token
+through the ONE reusable dependency :func:`api.dependencies.require_panel_token`
+(declared once at the router level, so each later panel route added to
+this router inherits the check).
+
+The snapshot route is a thin adapter over the bundled core: it performs
+NO business logic.  It reads the live database off ``app.state.db``,
+resolves ONE timezone-aware ``now`` (the API host's local time — the
+API is the household's "local" host now that the domain no longer lives
+inside Home Assistant), calls the pure
+:func:`nestquest_core.snapshot.build_snapshot`, shapes each child's
+instances through :func:`nestquest_core.snapshot.instance_payload` with
+``include_missed=False`` (D-009: missed instances are OMITTED from the
+panel payload), and returns the documented JSON shape:
+
+.. code-block:: json
+
+    {
+      "today_iso": "2026-09-22",
+      "cycle_day": 2,
+      "children": [
+        {
+          "child_id": 1,
+          "child_name": "Ada",
+          "present": false,
+          "next_present": "2026-09-24",
+          "due_today": 1,
+          "completed_today": 0,
+          "remaining_today": 1,
+          "completion_pct": 0,
+          "instances": [
+            {"id": 7, "definition_id": 3, "child_id": 1,
+             "title": "Pack bag", "icon": null, "window": "morning",
+             "due_time": "10:00", "state": "open", "overdue": true,
+             "completed_at": null, "on_time": null}
+          ]
+        }
+      ]
+    }
+
+``children`` follows the household's sort order (the core builder lists
+active children ``ORDER BY sort_order, id``); ``state`` is the
+documented panel spelling ``open`` | ``completed`` (§1 of
+design/ENTITIES-AND-SERVICES.md); ``cycle_day`` is today's 1-based day
+in the first scheduled child's custody cycle (0 when no child has one).
+The same :class:`PanelSnapshotResponse` Pydantic model is the route's
+``response_model``, so the OpenAPI document carries the shape too.
+"""
+from __future__ import annotations
+
+import datetime
+import importlib
+import json
+
+from collections.abc import AsyncIterator
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, field_validator
+
+from api.database import DatabaseState
+from api.dependencies import require_panel_token
+from api.nestquest_core import (
+    core_completion,
+    core_events,
+    core_settings,
+    core_snapshot,
+)
+from api import transitions as api_transitions
+
+#: The instance DAO, imported on the app's core copy for the
+#: child-mismatch guard on the complete route.
+_dao_instances = importlib.import_module("nestquest_core.dao_instances")
+
+#: All panel-plane routes share this router; the service-token check is
+#: attached HERE so every panel route (current and later) requires it.
+router = APIRouter(
+    prefix="/api/v1/panel",
+    dependencies=[Depends(require_panel_token)],
+)
+
+
+class PanelInstancePayload(BaseModel):
+    """One instance in the documented panel payload shape (§1).
+
+    Mirrors :func:`nestquest_core.snapshot.instance_payload`:
+    ``state`` is ``open`` | ``completed`` (missed instances never reach
+    the panel payload), ``on_time`` passes the completion event's flag
+    through verbatim (``None`` for an open instance), and
+    ``completed_at`` is the event's UTC timestamp when completed.
+    """
+
+    id: int
+    definition_id: int
+    child_id: int
+    title: str
+    icon: str | None
+    window: str
+    due_time: str | None
+    state: str
+    overdue: bool
+    completed_at: str | None
+    on_time: bool | None
+
+
+class PanelChildPayload(BaseModel):
+    """One child's day: presence, rollup counts, and today's instances."""
+
+    child_id: int
+    child_name: str
+    present: bool
+    #: ISO date of the child's next present day while they are away
+    #: (the away plate renders ``Returns <weekday>, <Mon D>`` from it);
+    #: ``None`` when the child is present today.
+    next_present: str | None
+    due_today: int
+    completed_today: int
+    remaining_today: int
+    completion_pct: int
+    instances: list[PanelInstancePayload]
+
+
+class PanelSnapshotResponse(BaseModel):
+    """The whole household snapshot the panel renders from.
+
+    ``today_iso`` anchors the payload's day; ``cycle_day`` is today's
+    1-based day in the first scheduled child's custody cycle (0 when no
+    child has a schedule); ``children`` is in the household's sort
+    order.
+    """
+
+    today_iso: str
+    cycle_day: int
+    children: list[PanelChildPayload]
+
+
+class PanelCompleteRequest(BaseModel):
+    """The body of ``POST /api/v1/panel/instances/{id}/complete``.
+
+    Matches the panel's ``nestquest.complete_quest`` payload (§2 of
+    design/ENTITIES-AND-SERVICES.md): ``actor_child_id`` is the tapped
+    profile.  A positive integer is required — the core completion
+    layer rejects non-int (and bool) ids anyway, but rejecting them
+    here with 422 keeps the contract visible in the OpenAPI document
+    and fails before any database work.
+    """
+
+    actor_child_id: int
+
+    model_config = {
+        "json_schema_extra": {
+            "description": (
+                "The tapped child profile the completion is "
+                "attributed to (decision 9)."
+            )
+        }
+    }
+
+    @field_validator("actor_child_id")
+    @classmethod
+    def _positive(cls, value: int) -> int:
+        """Reject zero and negative ids with a validation error."""
+        if value < 1:
+            raise ValueError("actor_child_id must be a positive integer")
+        return value
+
+
+def _local_now() -> datetime.datetime:
+    """Return the API host's local time as ONE timezone-aware clock read.
+
+    ``now().astimezone()`` attaches the host's local timezone to a
+    single clock read, so the calendar date and wall-clock time the
+    builder derives can never disagree.  Kept as a module function (not
+    inlined) so tests pin the instant the same way the coordinator's
+    ``_local_now`` is pinned.
+    """
+    return datetime.datetime.now().astimezone()
+
+
+@router.get(
+    "/snapshot",
+    summary="Today's household snapshot",
+    response_model=PanelSnapshotResponse,
+)
+async def panel_snapshot(request: Request) -> PanelSnapshotResponse:
+    """Return today's full household snapshot for the panel.
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency).  Builds
+    the snapshot through the pure core builder against the live
+    database and shapes each child's instances with
+    ``instance_payload(include_missed=False)`` — missed instances are
+    OMITTED from the panel payload (D-009) — then returns the shape
+    documented in this module's docstring and
+    :class:`PanelSnapshotResponse`.
+    """
+    state: DatabaseState = request.app.state.db
+    snapshot = await core_snapshot.build_snapshot(
+        state.database, core_settings.NestQuestSettings(), _local_now()
+    )
+    return PanelSnapshotResponse(
+        today_iso=snapshot.today_iso,
+        cycle_day=snapshot.cycle_day,
+        children=[
+            PanelChildPayload(
+                child_id=child.child_id,
+                child_name=child.child_name,
+                present=child.present,
+                next_present=child.next_present,
+                due_today=child.due_today,
+                completed_today=child.completed_today,
+                remaining_today=child.remaining_today,
+                completion_pct=child.completion_pct,
+                instances=[
+                    PanelInstancePayload.model_validate(instance)
+                    for instance in core_snapshot.instance_payload(
+                        child.instances, include_missed=False
+                    )
+                ],
+            )
+            for child in snapshot.children
+        ],
+    )
+
+
+@router.post(
+    "/instances/{instance_id}/complete",
+    summary="Complete one quest instance",
+    status_code=200,
+)
+async def panel_complete_instance(
+    instance_id: int, body: PanelCompleteRequest, request: Request
+) -> dict[str, str]:
+    """Complete one quest instance as the tapped child profile.
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency — the ONE
+    token check; this handler performs NO auth of its own).
+
+    Thin adapter only: resolves the live database off ``app.state.db``,
+    reads ONE timezone-aware clock (:func:`_local_now`), and delegates
+    to :func:`nestquest_core.completion.complete_instance` with
+    ``actor_source="panel"`` and the tapped ``actor_child_id`` — the
+    append/idempotence logic, the lock, and the actor-shape validation
+    all live in the core layer, never here.
+
+    Response and idempotence: ``complete_instance`` returns a
+    :class:`~nestquest_core.completion.CompletionResult` whose
+    ``appended`` flag reports whether THIS call wrote an event; a
+    repeat call for an already-completed instance is a no-op inside
+    the core layer (no duplicate event) and this route still answers
+    ``{"status": "done"}`` either way, so a retried panel tap succeeds.
+
+    Error mapping (deliberately narrow): the ONLY ``ValueError`` mapped
+    to 404 is the unknown-``instance_id`` one, identified by the
+    ``instance_id:`` prefix ``complete_instance`` names the failing
+    field with.  Every other ``ValueError`` (an invalid actor shape,
+    which the body model and the panel actor contract already make
+    unreachable) re-raises to the framework's 500 — nothing else is
+    turned into a 404 or a 500 of our own making.
+
+    Child mismatch: ``complete_instance`` verifies the tapped
+    ``actor_child_id`` exists but does NOT check it is the child the
+    instance belongs to.  The route performs that check here (one
+    ``QuestInstancesDao.get_by_id`` read) and answers 404 when the
+    instance's ``child_id`` differs — completing another child's quest
+    from the wrong profile must not succeed, and 404 (not 403) keeps
+    the instance's existence from leaking to a wrong-profile tap.
+    """
+    state: DatabaseState = request.app.state.db
+    database = state.database
+
+    # Child-mismatch guard (see docstring): the instance must belong to
+    # the tapped profile before the completion layer is entered.
+    instance = await _dao_instances.QuestInstancesDao(database).get_by_id(
+        instance_id
+    )
+    if instance is not None and instance.child_id != body.actor_child_id:
+        raise HTTPException(
+            status_code=404,
+            detail="Quest instance not found for this child",
+        )
+
+    now = _local_now()
+    try:
+        result = await core_completion.complete_instance(
+            database,
+            instance_id,
+            actor_source="panel",
+            actor_child_id=body.actor_child_id,
+            now=now,
+        )
+    except ValueError as error:
+        message = str(error)
+        if message.startswith("instance_id:"):
+            # complete_instance names the field in its ValueError:
+            # "instance_id: quest instance N does not exist".
+            raise HTTPException(
+                status_code=404,
+                detail="Quest instance not found",
+            ) from error
+        raise
+    # The derived state is "done" in both the appended and no-op cases;
+    # ``result.appended`` distinguishes them for callers that care —
+    # the panel route returns the same success either way.
+    if result.appended:
+        # An ACTUAL transition: publish the SSE transition event.  The
+        # payload is built by the core builder (never hand-built here)
+        # and fan-out is fire-and-forget (see api/events.py).
+        event_type, payload = await core_events.build_quest_completed_event(
+            database, instance_id, was_on_time=result.was_on_time
+        )
+        request.app.state.publisher.publish(event_type, payload)
+        # THEN evaluate the day-complete rule off the completed event's
+        # payload (the core builder decides when the child's whole day
+        # is cleared — a zero-quest day and a non-today instance never
+        # fire it).  ``today`` comes from the route's single clock read
+        # so the calendar date can never disagree with the completion's.
+        await api_transitions.publish_child_day_complete(
+            database,
+            payload,
+            now.date(),
+            request.app.state.publisher,
+        )
+    return {"status": str(result)}
+
+
+async def _sse_stream(request: Request) -> AsyncIterator[str]:
+    """Yield the SSE frames for every published transition event.
+
+    One subscriber of the app's single publisher (resolved off
+    ``app.state.publisher``); each event becomes one
+    ``event: <type>\\ndata: <json>\\n\\n`` frame.  Breaking out of the
+    publisher's subscription (on client disconnect) tears the
+    subscription down cleanly — no queue is leaked.
+    """
+    publisher = request.app.state.publisher
+    async for event_type, payload in publisher.subscribe():
+        yield (
+            f"event: {event_type}\n"
+            f"data: {json.dumps(payload)}\n\n"
+        )
+
+
+@router.get(
+    "/events",
+    summary="Stream panel transition events (SSE)",
+)
+async def panel_events(request: Request) -> StreamingResponse:
+    """Stream the app's transition events to the panel (Server-Sent
+    Events).
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency — the ONE
+    token check; this handler performs NO auth of its own).
+
+    Returns a ``text/event-stream`` response whose body is produced by
+    :func:`_sse_stream` off the app's single in-process publisher
+    (``app.state.publisher``, installed in the lifespan).  The stream
+    ends when the client disconnects, at which point the subscription
+    is torn down (its queue removed) with nothing leaked.
+    """
+    return StreamingResponse(
+        _sse_stream(request),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache"},
+    )
+
+
+__all__ = ["router"]

api/transitions.py

@@ -0,0 +1,83 @@
+"""Reusable SSE transition publishers for the API service (task 44c93cfd).
+
+Each helper wraps the ONE publisher on ``app.state.publisher`` with a
+single documented transition: it builds the payload through the core
+event builders (``nestquest_core.events``) — never hand-built here —
+and fans it out with :meth:`~api.events.TransitionPublisher.publish`.
+
+The uncomplete route (follow-up task da0226b3) and the API-side missed
+sweep do not exist yet; these helpers are the functions they will call,
+and the SSE tests exercise them directly.  Fan-out stays fire-and-forget
+(see api/events.py): a slow subscriber drops the event and recovers by
+polling the snapshot.
+"""
+from __future__ import annotations
+
+import datetime
+
+from api.nestquest_core import core_events
+
+
+async def publish_quest_uncompleted(
+    database: object, instance_id: int, publisher: object
+) -> None:
+    """Publish ONE ``nestquest_quest_uncompleted`` event for an actual
+    reversal of ``instance_id``.
+
+    The payload is built by the core builder
+    (:func:`nestquest_core.events.build_quest_uncompleted_events`);
+    this helper only picks the single event out of the builder's list
+    and publishes it.
+    """
+    events = await core_events.build_quest_uncompleted_events(
+        database, instance_id
+    )
+    for event_type, payload in events:
+        publisher.publish(event_type, payload)
+
+
+async def publish_quest_missed(
+    database: object, instance_id: int, publisher: object
+) -> None:
+    """Publish ONE ``nestquest_quest_missed`` event for ``instance_id``.
+
+    The payload is built by the core builder
+    (:func:`nestquest_core.events.build_quest_missed_event`), which
+    mirrors the documented sweep payload exactly (§3 of
+    design/ENTITIES-AND-SERVICES.md).
+    """
+    event_type, payload = await core_events.build_quest_missed_event(
+        database, instance_id
+    )
+    publisher.publish(event_type, payload)
+
+
+async def publish_child_day_complete(
+    database: object,
+    completed_payload: dict,
+    today: datetime.date,
+    publisher: object,
+) -> bool:
+    """Publish ``nestquest_child_day_complete`` when a completion
+    cleared the child's whole day; return whether one was published.
+
+    The day-complete rule lives entirely in the core builder
+    (:func:`nestquest_core.events.build_child_day_complete_event`):
+    it returns ``None`` when the day did not clear (a zero-quest day
+    or a non-today instance) and this helper publishes nothing then.
+    """
+    event = await core_events.build_child_day_complete_event(
+        database, completed_payload, today=today
+    )
+    if event is None:
+        return False
+    event_type, payload = event
+    publisher.publish(event_type, payload)
+    return True
+
+
+__all__ = [
+    "publish_child_day_complete",
+    "publish_quest_missed",
+    "publish_quest_uncompleted",
+]

custom_components/nestquest/__init__.py

@@ -18,16 +18,13 @@ from homeassistant.helpers.event import async_track_time_change
 
 from .const import (
     CONF_ADMIN_USER_IDS,
-    CONF_DAY_ROLLOVER_TIME,
-    CONF_HORIZON_DAYS,
     CONF_UPDATE_INTERVAL,
-    DEFAULT_DAY_ROLLOVER_TIME,
-    DEFAULT_HORIZON_DAYS,
     DEFAULT_UPDATE_INTERVAL,
     DOMAIN,
     LOGGER,
     PLATFORMS,
 )
+from .core.settings import NestQuestSettings
 from .frontend import async_register_frontend
 from .coordinator import NestQuestCoordinator
 from .db import NestQuestDatabase, make_database
@@ -240,7 +237,7 @@ class NestQuestRuntimeData:
     """Runtime data stored on a NestQuest config entry."""
 
     entry_id: str
-    options: dict[str, Any]
+    settings: NestQuestSettings
     database: NestQuestDatabase
     remove_update_listener: Callable[[], Any]
     remove_time_change_listener: Callable[[], Any]
@@ -269,38 +266,10 @@ async def _async_owner_user_ids(hass: HomeAssistant) -> list[str]:
     return owners
 
 
-def _day_rollover_hour_minute(options: dict[str, Any]) -> tuple[int, int]:
-    """Return the (hour, minute) the daily rollover fires at from ``options``.
-
-    The options flow validates ``day_rollover_time`` as a strict ``HH:MM``
-    string, so a stored value never needs re-validation here; a missing key
-    falls back to :data:`~.const.DEFAULT_DAY_ROLLOVER_TIME`.
-    """
-    rollover = options.get(CONF_DAY_ROLLOVER_TIME, DEFAULT_DAY_ROLLOVER_TIME)
-    hour, _, minute = rollover.partition(":")
-    return int(hour), int(minute)
-
-
-def _configured_horizon_days(options: dict[str, Any]) -> int:
-    """Return the configured generation horizon, validated, else the default.
-
-    The options flow already validates ``horizon_days`` as an integer >= 1,
-    but a stored ``entry.options`` dict could still carry a partial or
-    hand-edited value.  Re-checking here — and falling back to
-    :data:`~.const.DEFAULT_HORIZON_DAYS` on a missing, non-int or sub-1 value
-    — keeps a malformed option from shrinking or exploding the materialized
-    horizon.
-    """
-    value = options.get(CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS)
-    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
-        return DEFAULT_HORIZON_DAYS
-    return value
-
-
 async def _run_horizon_materialization(
     hass: HomeAssistant,
     database: NestQuestDatabase,
-    horizon_days: int = DEFAULT_HORIZON_DAYS,
+    settings: NestQuestSettings,
 ) -> None:
     """Materialize the rolling horizon ``[today, today + horizon_days]``.
 
@@ -311,23 +280,22 @@ async def _run_horizon_materialization(
 
     This is the ONE generation path: the startup backfill, the daily rollover
     listener and the ``regenerate`` service all funnel through it, so there is
-    no duplicated materialization logic.  ``horizon_days`` sizes the window
-    and defaults to :data:`~.const.DEFAULT_HORIZON_DAYS`; callers thread the
-    entry's validated option value through.
+    no duplicated materialization logic.  ``settings`` (REQUIRED — there is no
+    silent default; every caller already passes the entry's validated
+    :class:`NestQuestSettings`) carries the configured ``horizon_days``.  The
+    window itself comes from :meth:`settings.horizon_window` so the helper is
+    real and shared (not recomputed inline here).
     """
     time_zone = ZoneInfo(hass.config.time_zone)
     today = datetime.datetime.now(time_zone).date()
-    start_date = today.isoformat()
-    end_date = (
-        today + datetime.timedelta(days=horizon_days)
-    ).isoformat()
-    await _materialize_run(database, start_date, end_date, today=today)
+    start, end = settings.horizon_window(today)
+    await _materialize_run(database, start.isoformat(), end.isoformat(), today=today)
 
 
 def _register_day_rollover_listener(
     hass: HomeAssistant,
     database: NestQuestDatabase,
-    options: dict[str, Any],
+    settings: NestQuestSettings,
 ) -> Callable[[], Any]:
     """Register the daily rollover listener and return its remover.
 
@@ -335,16 +303,15 @@ def _register_day_rollover_listener(
     first re-materializes the rolling horizon
     ``[today, today + horizon_days]`` through the shared
     :func:`_run_horizon_materialization` path (the entry's configured,
-    validated ``horizon_days``), then runs the Feature 11 missed sweep
-    — announcing yesterday's still-open quests as missed AFTER today's
-    instances exist, watermark-guarded so a re-fire of the listener the
-    same night announces nothing twice.
+    validated ``horizon_days`` carried on ``settings``), then runs the
+    Feature 11 missed sweep — announcing yesterday's still-open quests
+    as missed AFTER today's instances exist, watermark-guarded so a
+    re-fire of the listener the same night announces nothing twice.
     """
-    hour, minute = _day_rollover_hour_minute(options)
-    horizon_days = _configured_horizon_days(options)
+    hour, minute = settings.day_rollover_hour_minute
 
     async def _run_materialization(_now: datetime.datetime) -> None:
-        await _run_horizon_materialization(hass, database, horizon_days)
+        await _run_horizon_materialization(hass, database, settings)
         await run_missed_sweep(hass, database)
 
     return async_track_time_change(
@@ -359,7 +326,9 @@ def _find_live_runtime_data(hass: HomeAssistant) -> NestQuestRuntimeData | None:
     their own; they resolve whichever config entry's runtime data is
     currently live at call time, so none of them can hold a stale handle
     to a closed connection after another entry unloads.  The record also
-    carries that entry's options (e.g. the configured horizon).
+    carries that entry's validated ``settings`` (e.g. the configured
+    horizon) so service handlers read horizon days off it rather than
+    re-reading HA config.
     """
     for runtime_data in hass.data.get(DOMAIN, {}).values():
         database = getattr(runtime_data, "database", None)
@@ -379,9 +348,8 @@ def _make_regenerate_handler(hass: HomeAssistant):
                 "live database; ignoring"
             )
             return
-        horizon_days = _configured_horizon_days(runtime_data.options)
         await _run_horizon_materialization(
-            hass, runtime_data.database, horizon_days
+            hass, runtime_data.database, runtime_data.settings
         )
 
     return _regenerate
@@ -495,18 +463,24 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             context_user_id=context_user_id,
             owner_ids=owner_ids,
         )
+        # Build the explicit settings object from entry.options ONCE: the
+        # horizon materialization and the daily-rollover listener both
+        # consume it, so core never reads HA config itself.  A malformed
+        # stored option falls back PER FIELD (via from_options_resilient)
+        # so a single bad sibling option cannot reset the user's
+        # horizon_days or day_rollover_time — the two fields core
+        # consumes — to their defaults.
+        settings = NestQuestSettings.from_options_resilient(entry.options)
         remove_update_listener = entry.add_update_listener(_async_update_listener)
         remove_time_change_listener = _register_day_rollover_listener(
-            hass, database, dict(entry.options)
+            hass, database, settings
         )
         # Backfill any days the daily listener missed while the integration
         # was off (or freshly installed): run the one idempotent walk over
         # [today, today + horizon_days] once at setup, using the entry's
         # configured horizon.  This runs through the SAME path as the daily
         # listener and regenerate service.
-        await _run_horizon_materialization(
-            hass, database, _configured_horizon_days(dict(entry.options))
-        )
+        await _run_horizon_materialization(hass, database, settings)
         # The missed sweep runs at startup too (Feature 11): if HA was
         # down at the rollover time, the previous night's still-open
         # quests are announced as missed now instead of waiting for
@@ -522,6 +496,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             hass,
             entry_id=entry.entry_id,
             database=database,
+            settings=settings,
             update_interval_seconds=entry.options.get(
                 CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL
             ),
@@ -529,7 +504,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         await coordinator.async_config_entry_first_refresh()
         runtime_data = NestQuestRuntimeData(
             entry_id=entry.entry_id,
-            options=dict(entry.options),
+            settings=settings,
             database=database,
             remove_update_listener=remove_update_listener,
             remove_time_change_listener=remove_time_change_listener,

custom_components/nestquest/admin_allowlist.py

@@ -1,153 +1,11 @@
-"""Business layer for the admin allowlist (Feature 03).
+"""Re-export of :mod:`custom_components.nestquest.core.admin_allowlist` for the integration package.
 
-Sits between the options flow / Feature 09 service gate and the typed
-:class:`~.dao_children.AdminUsersDao`.  The allowlist stores Home
-Assistant user IDs — never usernames or display names (feature
-guardrail) — and an empty allowlist must fail closed: every function
-here refuses to write an empty allowlist, so the owner can never be
-accidentally locked out of admin operations by a bad save.
-
-Shape policy: a user id is a non-empty trimmed string.  Duplicate ids
-in one write are rejected up front — they would silently map to one
-row and hide a caller bug.  Writes replace the allowlist atomically:
-the diff (additions and removals) is computed and applied inside one
-transaction under the connection-scoped lock shared with the DAOs, so
-a concurrent reader never observes a half-applied sync.
-
-Seed policy (:func:`seed_setup_admin`): the allowlist is seeded only
-when it is EMPTY, so re-running setup never resurrects a deliberately
-narrowed list.  The setup user (the HA user who completed the config
-flow, via the entry context) is added automatically so the owner is
-never locked out on first setup; a stored entry-data copy of the list
-re-seeds a lost database.
+The admin allowlist business layer lives in
+:mod:`custom_components.nestquest.core.admin_allowlist` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .admin_allowlist import ...`` references inside the integration
+keep working.
 """
 from __future__ import annotations
 
-import datetime
-import logging
-
-from .dao_children import AdminUsersDao, _connection_lock
-from .db import NestQuestDatabase
-
-LOGGER = logging.getLogger(__name__)
-
-
-def _now_stamp() -> str:
-    """UTC second-precision stamp, matching the registry's policy."""
-    return datetime.datetime.now(datetime.timezone.utc).isoformat(
-        timespec="seconds"
-    )
-
-
-def _validate_user_id(value: object) -> str:
-    """Return ``value`` trimmed; raise unless a non-empty string."""
-    if not isinstance(value, str):
-        raise ValueError(
-            f"admin user id must be a string, got {value!r}"
-        )
-    trimmed = value.strip()
-    if not trimmed:
-        raise ValueError("admin user id must not be empty")
-    return trimmed
-
-
-async def list_admin_ids(database: NestQuestDatabase) -> list[str]:
-    """Return the allowlisted HA user IDs in storage order."""
-    return [row.ha_user_id for row in await AdminUsersDao(database).list()]
-
-
-async def set_admin_ids(
-    database: NestQuestDatabase, user_ids: list[str]
-) -> None:
-    """Replace the allowlist with exactly ``user_ids`` (atomic sync).
-
-    Refuses an empty list — an empty allowlist must fail closed, and
-    the only way to reach one through this API would be removing the
-    last admin, so that removal is refused here with a clear error.
-    Refuses non-string, empty, or duplicate ids up front.  The diff
-    against the current allowlist (additions and removals) applies
-    inside one transaction under the connection lock.
-    """
-    if not isinstance(user_ids, list):
-        raise ValueError("user_ids must be a list of HA user id strings")
-    normalized: list[str] = []
-    for value in user_ids:
-        normalized.append(_validate_user_id(value))
-    if len(set(normalized)) != len(normalized):
-        raise ValueError("user_ids must not contain duplicates")
-    if not normalized:
-        raise ValueError(
-            "refusing to empty the admin allowlist: at least one admin "
-            "must remain (an empty allowlist fails closed)"
-        )
-    dao = AdminUsersDao(database)
-    async with _connection_lock(database):
-        async with database.transaction():
-            current = {row.ha_user_id for row in await dao.list()}
-            target = set(normalized)
-            for user_id in sorted(current - target):
-                await dao.remove(user_id)
-            for user_id in normalized:
-                await dao.add(user_id, _now_stamp())
-
-
-async def is_admin(
-    database: NestQuestDatabase, user_id: object
-) -> bool:
-    """Resolve an HA user ID against the allowlist — FAILS CLOSED.
-
-    True only for an allowlisted user id.  Everything else is False:
-    a non-allowlisted id, an unknown id, a None or non-string value
-    (a service call with no user context), and an empty allowlist
-    (nobody is admin rather than everybody).  The Feature 09 gate
-    wraps every admin-only service with this verdict; it never raises
-    for malformed input — malformed means not admin.
-    """
-    if not isinstance(user_id, str) or not user_id:
-        return False
-    return await AdminUsersDao(database).exists(user_id)
-
-
-async def seed_setup_admin(
-    database: NestQuestDatabase,
-    *,
-    stored_admin_ids: list[str] | None = None,
-    context_user_id: str | None = None,
-    owner_ids: list[str] | None = None,
-) -> list[str]:
-    """Seed an empty allowlist so the owner is never locked out.
-
-    Only acts when the allowlist is EMPTY.  Preference order: the
-    stored persisted copy of the list (the options flow's current
-    selection, then the config flow's original — disaster recovery for
-    a lost database), then the HA user who completed the config flow
-    (``context_user_id``), then — when no caller identity survived at
-    all — every Home Assistant OWNER account (``owner_ids``), so a
-    first setup whose flow context lost the user id still seeds a
-    working admin.  Returns the allowlist after seeding.  Non-empty
-    allowlists are returned untouched — re-running setup must never
-    resurrect a deliberately narrowed list.
-    """
-    dao = AdminUsersDao(database)
-    async with _connection_lock(database):
-        current = [row.ha_user_id for row in await dao.list()]
-        if current:
-            return current
-        candidates: list[str] = []
-        if stored_admin_ids is not None:
-            if not isinstance(stored_admin_ids, list):
-                raise ValueError(
-                    "stored_admin_ids must be a list of HA user id strings"
-                )
-            candidates = [_validate_user_id(value) for value in stored_admin_ids]
-        elif context_user_id is not None:
-            candidates = [_validate_user_id(context_user_id)]
-        elif owner_ids:
-            if not isinstance(owner_ids, list):
-                raise ValueError(
-                    "owner_ids must be a list of HA user id strings"
-                )
-            candidates = [_validate_user_id(value) for value in owner_ids]
-        for user_id in candidates:
-            await dao.add(user_id, _now_stamp())
-        return [row.ha_user_id for row in await dao.list()]
+from .core.admin_allowlist import *  # noqa: F401,F403

custom_components/nestquest/children.py

@@ -1,280 +1,11 @@
-"""Business layer for the children registry (Feature 03).
+"""Re-export of :mod:`custom_components.nestquest.core.children` for the integration package.
 
-Sits between the Feature 09 service gate and the typed
-:class:`~.dao_children.ChildrenDao`: callers get validation, name
-policies and the duplicate-name warning here, and never talk to the
-DAO or SQL directly.  Children are never hard-deleted — deactivation
-is a separate explicit operation (:func:`set_child_active`), so
-completion history keeps its references (feature guardrail).
-
-Name policy: the display name is required and trimmed; an empty or
-whitespace-only name is rejected with ValueError.  A duplicate display
-name is ALLOWED (two children may legitimately share a nickname) but
-logged as a warning so an accidental double-add is visible in the HA
-log.  The duplicate check is case-insensitive and whitespace-normalised
-on both sides, because "ada" and "Ada " are the same name to a parent.
-
-Colour and avatar are optional free-form strings, trimmed when present;
-``sort_order`` is an int with the DAO/schema default of 0.  Clearing an
-optional field back to NULL is deliberately rejected: the DAO's update
-writes only provided fields (it cannot express NULL), so the business
-layer refuses an explicit ``None`` instead of silently ignoring it.
-Timestamps follow the module timestamp policy: the business layer
-stamps UTC ISO-8601 at second precision so every row it creates is
-uniform.
+The children registry business layer lives in
+:mod:`custom_components.nestquest.core.children` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .children import ...`` references inside the integration keep
+working.
 """
 from __future__ import annotations
 
-import datetime
-import logging
-
-from .dao_children import ChildRecord, ChildrenDao, _connection_lock
-from .db import NestQuestDatabase
-
-LOGGER = logging.getLogger(__name__)
-
-#: Sentinel distinguishing "argument omitted" from "explicit SQL NULL"
-#: in :func:`edit_child`.
-_UNSET = object()
-
-
-def _now_stamp() -> str:
-    """Return the module's strict UTC second-precision stamp."""
-    return datetime.datetime.now(datetime.timezone.utc).isoformat(
-        timespec="seconds"
-    )
-
-
-def _validate_text(
-    value: object, field: str, *, required: bool = False
-) -> str | None:
-    """Validate a free-text field and return it trimmed.
-
-    ``None`` raises when ``required`` and otherwise returns None.  A
-    non-string value is rejected; an empty result is rejected for
-    required fields (whitespace-only names are empty to a parent).
-    """
-    if value is None:
-        if required:
-            raise ValueError(f"{field} is required")
-        return None
-    if not isinstance(value, str):
-        raise ValueError(f"{field} must be a string, got {value!r}")
-    trimmed = value.strip()
-    if required and not trimmed:
-        raise ValueError(f"{field} is required")
-    return trimmed
-
-
-def _validate_sort_order(value: object) -> int:
-    """Reject non-int sort orders (bools included) before the DAO."""
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(f"sort_order must be an integer, got {value!r}")
-    return value
-
-
-def _validate_child_id(value: object) -> int:
-    """Reject non-int child ids (bools included) before any lookup.
-
-    SQLite binds Python bools as integers, so ``True`` would silently
-    address child 1 and a float would round — malformed service input
-    must never mutate the wrong profile.
-    """
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(f"child_id must be an integer, got {value!r}")
-    return value
-
-
-async def _warn_on_duplicate_name(
-    database: NestQuestDatabase,
-    display_name: str,
-    *,
-    exclude_child_id: int | None = None,
-) -> None:
-    """Log a warning when ``display_name`` duplicates an existing child.
-
-    Case-insensitive and whitespace-normalised on both sides.  The
-    duplicate is still allowed — this only makes it visible; the log
-    line names both rows so an accidental double-add can be found.
-    ``exclude_child_id`` removes the child being edited from the scan,
-    so an edit only warns when the result collides with a DIFFERENT
-    child's name — including case-only edits, where the self-comparison
-    would otherwise hide a real duplicate.
-    """
-    lowered = display_name.casefold()
-    for child in await ChildrenDao(database).list_all():
-        if exclude_child_id is not None and child.id == exclude_child_id:
-            continue
-        if child.display_name.strip().casefold() == lowered:
-            LOGGER.warning(
-                "Child display name %r duplicates existing child %d "
-                "(%r); allowed, but check this was intentional",
-                display_name,
-                child.id,
-                child.display_name,
-            )
-            return
-
-
-async def create_child(
-    database: NestQuestDatabase,
-    display_name: str,
-    *,
-    colour: str | None = None,
-    avatar_ref: str | None = None,
-    sort_order: int = 0,
-) -> ChildRecord:
-    """Create a child profile and return the stored record.
-
-    The display name is required, trimmed, and rejected when empty.
-    A duplicate display name (case-insensitive) is allowed but logged
-    as a warning.  The scan and the INSERT run inside the
-    connection-scoped lock shared with the DAOs, so a concurrent
-    create of the same normalised name queues behind the first insert
-    and sees it — the duplicate still warns; it can never slip through
-    unlogged.
-    """
-    name = _validate_text(display_name, "display_name", required=True)
-    assert name is not None
-    colour_value = _validate_text(colour, "colour")
-    avatar_value = _validate_text(avatar_ref, "avatar_ref")
-    order = _validate_sort_order(sort_order)
-    async with _connection_lock(database):
-        await _warn_on_duplicate_name(database, name)
-        created = await ChildrenDao(database).create(
-            name,
-            _now_stamp(),
-            colour=colour_value,
-            avatar_ref=avatar_value,
-            sort_order=order,
-        )
-    return created
-
-
-async def edit_child(
-    database: NestQuestDatabase,
-    child_id: int,
-    *,
-    display_name: str | object = _UNSET,
-    colour: str | None | object = _UNSET,
-    avatar_ref: str | None | object = _UNSET,
-    sort_order: int | object = _UNSET,
-) -> ChildRecord:
-    """Edit a child profile and return the updated record.
-
-    Arguments default to the module sentinel ``_UNSET`` meaning "leave
-    this field alone".  An explicitly passed ``None`` for an optional
-    field raises: the DAO's update writes only provided fields and
-    cannot express NULL, so a silent no-op would mask the caller's
-    intent (see the module docstring).  A provided display name is
-    validated like create's; the duplicate scan excludes only the child
-    being edited, so a case-only edit colliding with another child's
-    normalised name still warns.  Raises ValueError when the child does
-    not exist.
-
-    Atomicity: the existence check, the duplicate scan, the UPDATE and
-    the readback all run inside the connection-scoped lock shared with
-    the DAOs, so another edit cannot slip between this call's UPDATE
-    and its readback — the returned record is exactly the one this
-    edit produced, not a later writer's.
-    """
-    _validate_child_id(child_id)
-    async with _connection_lock(database):
-        dao = ChildrenDao(database)
-        existing = await dao.get(child_id)
-        if existing is None:
-            raise ValueError(f"child {child_id} does not exist")
-        updates: dict[str, object] = {}
-        if display_name is not _UNSET:
-            name = _validate_text(
-                display_name, "display_name", required=True
-            )
-            assert name is not None
-            await _warn_on_duplicate_name(
-                database, name, exclude_child_id=child_id
-            )
-            updates["display_name"] = name
-        if colour is not _UNSET:
-            value = _validate_text(colour, "colour")
-            if value is None:
-                raise ValueError(
-                    "clearing colour is not supported; pass a replacement "
-                    "value or omit the field"
-                )
-            updates["colour"] = value
-        if avatar_ref is not _UNSET:
-            value = _validate_text(avatar_ref, "avatar_ref")
-            if value is None:
-                raise ValueError(
-                    "clearing avatar_ref is not supported; pass a "
-                    "replacement value or omit the field"
-                )
-            updates["avatar_ref"] = value
-        if sort_order is not _UNSET:
-            updates["sort_order"] = _validate_sort_order(sort_order)
-        if updates:
-            await dao.update(child_id, **updates)
-        edited = await dao.get(child_id)
-    assert edited is not None
-    return edited
-
-
-async def set_child_active(
-    database: NestQuestDatabase, child_id: int, is_active: bool
-) -> ChildRecord:
-    """Deactivate or reactivate a child; returns the updated record.
-
-    Deactivation hides the child from the panel without deleting their
-    history (feature guardrail); this is the only removal path.
-    ``is_active`` must be a real bool: the DAO's ``int()`` would
-    otherwise silently coerce strings and numerics ("1", 0) into a
-    state the caller never asked for.  Raises ValueError when the
-    child does not exist.
-
-    Atomicity: existence check, UPDATE and readback run inside the
-    connection-scoped lock, so a concurrent opposite transition cannot
-    make this call report the other caller's value.
-    """
-    _validate_child_id(child_id)
-    async with _connection_lock(database):
-        dao = ChildrenDao(database)
-        if await dao.get(child_id) is None:
-            raise ValueError(f"child {child_id} does not exist")
-        if not isinstance(is_active, bool):
-            raise ValueError(
-                f"is_active must be a real bool, got {is_active!r}"
-            )
-        await dao.set_active(child_id, is_active)
-        updated = await dao.get(child_id)
-    assert updated is not None
-    return updated
-
-
-async def reorder_children(
-    database: NestQuestDatabase, ordered_ids: list[int]
-) -> None:
-    """Rewrite the children's panel display order in one transaction.
-
-    ``ordered_ids`` must be a complete permutation of the children
-    table — every child id exactly once.  A partial list (missing an
-    existing child), an unknown id, or a duplicate is rejected with
-    ValueError before any write, so the current order survives a
-    rejected call.  The DAO enforces this inside its own transaction
-    (check and write are     atomic under the connection lock); this
-    wrapper additionally rejects non-integer ids up front, since
-    ``bool`` and floats would silently compare against stored integer
-    ids at the SQL layer.
-    """
-    for child_id in ordered_ids:
-        _validate_child_id(child_id)
-    await ChildrenDao(database).reorder(ordered_ids)
-
-
-async def list_children(
-    database: NestQuestDatabase, *, active_only: bool = False
-) -> list[ChildRecord]:
-    """Return children in display order (sort_order, then id)."""
-    dao = ChildrenDao(database)
-    if active_only:
-        return await dao.list_active()
-    return await dao.list_all()
+from .core.children import *  # noqa: F401,F403

custom_components/nestquest/completion.py

@@ -1,549 +1,11 @@
-"""Business layer for the completion event log (Feature 08).
+"""Re-export of :mod:`custom_components.nestquest.core.completion` for the integration package.
 
-Sits between the Feature 09 service gate and the typed
-:class:`~.dao_instances.CompletionEventsDao`: callers get actor-shape
-validation and the UTC occurred-at stamp here, and never talk to the
-DAO or SQL directly.  This module is the only Feature-08 caller of
-:meth:`~.dao_instances.CompletionEventsDao.append`.  Completing an
-instance (no-op if already done) is :func:`complete_instance`;
-un-completing (no-op if already open) is :func:`uncomplete_instance`.
-Instance current state is derived from the latest event via
-:func:`instance_state` (``open`` / ``done`` / ``missed``); there is
-no status column.  ``missed`` is derived for past-due open instances
-(``due_date`` before HA-local ``today``) and is never stored as an
-event_type.
-
-Actor policy matches the schema CHECKs (D-008): ``actor_source`` is
-``'user'`` or ``'panel'`` only — never ``'service'``.  ``'user'``
-requires ``actor_user_id`` and forbids ``actor_child_id``; ``'panel'``
-requires ``actor_child_id`` (the tapped profile) and forbids
-``actor_user_id``.  Inverted shapes raise a field-naming ValueError
-before any write.
-
-``occurred_at`` is stamped UTC ISO-8601 at second precision with an
-explicit ``+00:00`` offset, matching the DAO's one accepted shape so
-lexicographic range queries stay exact.  ``was_on_time`` is required
-(True/False) for completed events; un-completions may pass None.  There
-is no permission check here (that is Feature 09).
+The completion business layer lives in
+:mod:`custom_components.nestquest.core.completion` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .completion import ...`` references inside the integration keep
+working.
 """
 from __future__ import annotations
 
-import asyncio
-import datetime
-
-from .dao_children import _CONNECTION_LOCKS, _connection_lock
-from .dao_instances import (
-    EVENT_COMPLETED,
-    EVENT_UNCOMPLETED,
-    CompletionEventRecord,
-    CompletionEventsDao,
-    QuestInstanceRecord,
-    QuestInstancesDao,
-)
-from .db import NestQuestDatabase
-
-#: Timestamp policy for completion_events.occurred_at: strict UTC
-#: ISO-8601 with explicit '+00:00' offset (module timestamp policy).
-_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
-
-
-def _now_stamp() -> str:
-    """Return the module's strict UTC second-precision stamp."""
-    return datetime.datetime.now(datetime.timezone.utc).strftime(
-        _UTC_TIMESTAMP_FORMAT
-    )
-
-
-def _stamp_occurred_at(now: datetime.datetime | None) -> str:
-    """Return a DAO-accepted UTC stamp for ``now``, or the current time."""
-    if now is None:
-        return _now_stamp()
-    if not isinstance(now, datetime.datetime):
-        raise ValueError(f"now must be a datetime, got {now!r}")
-    if now.tzinfo is None:
-        raise ValueError("now must be timezone-aware")
-    return now.astimezone(datetime.timezone.utc).strftime(
-        _UTC_TIMESTAMP_FORMAT
-    )
-
-
-def _completion_moment(
-    now: datetime.datetime | None,
-    today: datetime.date | None,
-) -> tuple[datetime.date, datetime.time | None]:
-    """Return the HA-local completion date and optional wall-clock time.
-
-    ``today`` is the HA-local calendar date when threaded (Feature 07
-    style).  ``now`` is a timezone-aware HA-local datetime; its wall
-    clock is used as-is and is never converted to UTC.  When ``today``
-    is omitted the date comes from ``now``.  When both are omitted the
-    host calendar date is the Feature 07 fallback — never the UTC
-    clock.  Time-of-day is None unless ``now`` is supplied; comparing
-    against ``due_time`` requires ``now``.
-    """
-    if now is not None:
-        if not isinstance(now, datetime.datetime):
-            raise ValueError(f"now must be a datetime, got {now!r}")
-        if now.tzinfo is None:
-            raise ValueError("now must be timezone-aware")
-    if today is not None:
-        completion_date = today
-    elif now is not None:
-        completion_date = now.date()
-    else:
-        completion_date = datetime.date.today()
-    if now is None:
-        return completion_date, None
-    return completion_date, now.time()
-
-
-def _resolve_today(today: datetime.date | None) -> datetime.date:
-    """Return the threaded HA-local date, or the host calendar date."""
-    if today is None:
-        return datetime.date.today()
-    return today
-
-
-def _derived_state(
-    instance: QuestInstanceRecord,
-    latest: CompletionEventRecord | None,
-    today: datetime.date,
-) -> str:
-    """Return ``open``, ``done``, or ``missed`` from event plus due date.
-
-    A latest completed event is ``done`` even when past due.  No events
-    or a latest uncompleted event is ``open``, or ``missed`` when
-    ``due_date`` is before ``today``.  ``missed`` is never an event_type.
-    """
-    if latest is None or latest.event_type == EVENT_UNCOMPLETED:
-        due_date = datetime.date.fromisoformat(instance.due_date)
-        if due_date < today:
-            return "missed"
-        return "open"
-    if latest.event_type == EVENT_COMPLETED:
-        return "done"
-    raise ValueError(
-        f"event_type must be '{EVENT_COMPLETED}' or "
-        f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
-    )
-
-
-def derive_state(
-    instance: QuestInstanceRecord,
-    latest: CompletionEventRecord | None,
-    today: datetime.date,
-) -> str:
-    """Public state derivation for the Feature 10 coordinator.
-
-    Thin wrapper over :func:`_derived_state`: ``open``, ``done``, or
-    ``missed`` from the latest event plus the due date (``missed`` is
-    derived, never an event_type).  ``today`` is the caller-resolved
-    HA-local date.
-    """
-    return _derived_state(instance, latest, today)
-
-
-def _was_on_time(
-    instance: QuestInstanceRecord,
-    now: datetime.datetime | None,
-    today: datetime.date | None,
-) -> bool:
-    """Return whether the completion moment is on time for ``instance``.
-
-    On ``due_date`` before ``due_time`` is on time; on ``due_date``
-    after ``due_time``, or any later date, is late.  With no
-    ``due_time``, on time if the completion date equals ``due_date``
-    (or is earlier); late if after ``due_date``.  Same-day
-    ``due_time`` comparison requires ``now``; UTC time-of-day is never
-    substituted.
-    """
-    completion_date, completion_time = _completion_moment(now, today)
-    due_date = datetime.date.fromisoformat(instance.due_date)
-    if completion_date < due_date:
-        return True
-    if completion_date > due_date:
-        return False
-    if instance.due_time is None:
-        return True
-    if completion_time is None:
-        raise ValueError("now is required to compare due_time")
-    due_time = datetime.datetime.strptime(instance.due_time, "%H:%M").time()
-    return completion_time <= due_time
-
-
-class _TaskReentrantLock:
-    """Shared connection lock the owning task may re-enter."""
-
-    def __init__(self, inner: asyncio.Lock) -> None:
-        self._inner = inner
-        self._task: asyncio.Task | None = None
-        self._depth = 0
-
-    def locked(self) -> bool:
-        return self._inner.locked()
-
-    async def acquire(self) -> bool:
-        task = asyncio.current_task()
-        if self._task is task:
-            self._depth += 1
-            return True
-        await self._inner.acquire()
-        self._task = task
-        self._depth = 1
-        return True
-
-    def release(self) -> None:
-        if self._task is not asyncio.current_task():
-            raise RuntimeError("lock released by a non-owner")
-        self._depth -= 1
-        if self._depth == 0:
-            self._task = None
-            self._inner.release()
-
-    async def __aenter__(self) -> _TaskReentrantLock:
-        await self.acquire()
-        return self
-
-    async def __aexit__(self, *exc: object) -> None:
-        self.release()
-
-
-def _reentrant_connection_lock(database) -> _TaskReentrantLock:
-    """Return the shared connection lock, made task-reentrant.
-
-    ``CompletionEventsDao.append`` also acquires this lock, so
-    check+append in :func:`complete_instance` and
-    :func:`uncomplete_instance` must re-enter on the same task.  The
-    wrapper is stored in the shared dict so the DAO sees the same
-    object.
-    """
-    loop = asyncio.get_running_loop()
-    key = (id(database), id(loop))
-    lock = _CONNECTION_LOCKS.get(key)
-    if isinstance(lock, _TaskReentrantLock):
-        return lock
-    wrapped = _TaskReentrantLock(
-        lock if lock is not None else asyncio.Lock()
-    )
-    _CONNECTION_LOCKS[key] = wrapped
-    return wrapped
-
-
-def _validate_int_id(value: object, field: str) -> int:
-    """Reject non-int ids (bools included) before any lookup."""
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(f"{field} must be an integer, got {value!r}")
-    return value
-
-
-def _validate_event_type(value: object) -> str:
-    """Return a schema-legal event type, or raise naming the field."""
-    if value not in (EVENT_COMPLETED, EVENT_UNCOMPLETED):
-        raise ValueError(
-            f"event_type must be '{EVENT_COMPLETED}' or "
-            f"'{EVENT_UNCOMPLETED}', got {value!r}"
-        )
-    return value
-
-
-def _validate_actor(
-    actor_source: object,
-    actor_user_id: object,
-    actor_child_id: object,
-) -> tuple[str, str | None, int | None]:
-    """Return a schema-legal actor triple, or raise naming the field.
-
-    ``'user'`` requires a non-empty ``actor_user_id`` string and forbids
-    ``actor_child_id``.  ``'panel'`` requires an integer
-    ``actor_child_id`` and forbids ``actor_user_id``.  Any other
-    ``actor_source`` (including ``'service'``) is rejected.
-    """
-    if actor_source not in ("user", "panel"):
-        raise ValueError(
-            f"actor_source must be 'user' or 'panel', got {actor_source!r}"
-        )
-    if actor_source == "user":
-        if not isinstance(actor_user_id, str) or not actor_user_id.strip():
-            raise ValueError("actor_source 'user' requires actor_user_id")
-        if actor_child_id is not None:
-            raise ValueError(
-                "actor_source 'user' must not carry actor_child_id"
-            )
-        return "user", actor_user_id.strip(), None
-    if actor_user_id is not None:
-        raise ValueError("actor_source 'panel' must not carry actor_user_id")
-    if actor_child_id is None:
-        raise ValueError(
-            "actor_source 'panel' requires actor_child_id"
-        )
-    return (
-        "panel",
-        None,
-        _validate_int_id(actor_child_id, "actor_child_id"),
-    )
-
-
-def _validate_was_on_time(
-    event_type: str, was_on_time: object
-) -> bool | None:
-    """Return a real bool or None; completed events require True/False."""
-    if was_on_time is not None and type(was_on_time) is not bool:
-        raise ValueError(
-            f"was_on_time must be True, False or None, got {was_on_time!r}"
-        )
-    if event_type == EVENT_COMPLETED and was_on_time is None:
-        raise ValueError(
-            "a completed event requires was_on_time (True/False)"
-        )
-    return was_on_time
-
-
-async def append_event(
-    database: NestQuestDatabase,
-    instance_id: int,
-    child_id: int,
-    event_type: str,
-    *,
-    actor_source: str,
-    actor_user_id: str | None = None,
-    actor_child_id: int | None = None,
-    was_on_time: bool | None = None,
-    now: datetime.datetime | None = None,
-) -> CompletionEventRecord:
-    """Append one completion or un-completion event and return the row.
-
-    Validates actor shapes and the completed-event on-time requirement
-    before calling :meth:`CompletionEventsDao.append`.  ``occurred_at``
-    is stamped here (UTC ``+00:00``); pass ``now`` to pin the clock.
-    """
-    instance_id = _validate_int_id(instance_id, "instance_id")
-    child_id = _validate_int_id(child_id, "child_id")
-    event_type = _validate_event_type(event_type)
-    actor_source, actor_user_id, actor_child_id = _validate_actor(
-        actor_source, actor_user_id, actor_child_id
-    )
-    was_on_time = _validate_was_on_time(event_type, was_on_time)
-    occurred_at = _stamp_occurred_at(now)
-    return await CompletionEventsDao(database).append(
-        instance_id,
-        child_id,
-        event_type,
-        actor_source,
-        occurred_at,
-        was_on_time,
-        actor_user_id=actor_user_id,
-        actor_child_id=actor_child_id,
-    )
-
-
-async def instance_state(
-    database: NestQuestDatabase,
-    instance_id: int,
-    *,
-    today: datetime.date | None = None,
-) -> str:
-    """Return ``open``, ``done``, or ``missed`` from the latest event.
-
-    No events, or a latest event of uncompleted, is ``open`` unless
-    ``due_date`` is before ``today`` (HA-local, threaded), in which
-    case it is ``missed``.  A latest event of completed is ``done``
-    even when past due.  ``missed`` is never stored as an event_type.
-    Unknown ``instance_id`` raises ValueError naming the field.
-    Existence and the latest event are read inside the connection lock
-    so the answer is one snapshot.
-    """
-    instance_id = _validate_int_id(instance_id, "instance_id")
-    today_date = _resolve_today(today)
-    async with _connection_lock(database):
-        instance = await QuestInstancesDao(database).get_by_id(instance_id)
-        if instance is None:
-            raise ValueError(
-                f"instance_id: quest instance {instance_id} does not exist"
-            )
-        latest = await CompletionEventsDao(database).get_latest_for_instance(
-            instance_id
-        )
-    return _derived_state(instance, latest, today_date)
-
-
-class CompletionResult(str):
-    """The derived instance state, carrying the append verdict.
-
-    A ``str`` subclass so every existing ``result == "done"`` contract
-    keeps working; ``appended`` reports whether THIS call actually
-    appended an event (decided under the same lock as the append), so
-    a caller — the Feature 09 service path firing bus events —
-    announces a transition exactly once even under a concurrent
-    duplicate call where the loser's write is a no-op.  A completion
-    also carries the ``was_on_time`` verdict computed under that same
-    lock, so the event payload never re-reads mutable latest state a
-    racing reversal could have replaced.
-    """
-
-    appended: bool
-    was_on_time: bool | None
-
-    def __new__(
-        cls,
-        state: str,
-        *,
-        appended: bool,
-        was_on_time: bool | None = None,
-    ) -> "CompletionResult":
-        obj = super().__new__(cls, state)
-        obj.appended = appended
-        obj.was_on_time = was_on_time
-        return obj
-
-
-async def complete_instance(
-    database: NestQuestDatabase,
-    instance_id: int,
-    *,
-    actor_source: str,
-    actor_user_id: str | None = None,
-    actor_child_id: int | None = None,
-    now: datetime.datetime | None = None,
-    today: datetime.date | None = None,
-) -> CompletionResult:
-    """Append a completed event unless the instance is already done.
-
-    Returns the derived state ``done``; ``appended`` reports whether
-    THIS call appended (False on an already-done no-op).  Unknown
-    ``instance_id`` raises ValueError naming the field.  Existence,
-    latest-event, and the append run under one connection lock so a
-    concurrent complete cannot double-append.
-
-    ``was_on_time`` is computed from the HA-local completion moment
-    (threaded ``now`` / ``today``) against the instance ``due_date``
-    and optional ``due_time``.  ``now`` is the timezone-aware HA-local
-    datetime; its wall clock is never converted to UTC.  Same-day
-    ``due_time`` comparison requires ``now``.
-    """
-    instance_id = _validate_int_id(instance_id, "instance_id")
-    actor_source, actor_user_id, actor_child_id = _validate_actor(
-        actor_source, actor_user_id, actor_child_id
-    )
-    async with _reentrant_connection_lock(database):
-        instance = await QuestInstancesDao(database).get_by_id(instance_id)
-        if instance is None:
-            raise ValueError(
-                f"instance_id: quest instance {instance_id} does not exist"
-            )
-        latest = await CompletionEventsDao(database).get_latest_for_instance(
-            instance_id
-        )
-        if latest is not None and latest.event_type == EVENT_COMPLETED:
-            return CompletionResult("done", appended=False)
-        if latest is not None and latest.event_type != EVENT_UNCOMPLETED:
-            raise ValueError(
-                f"event_type must be '{EVENT_COMPLETED}' or "
-                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
-            )
-        # Computed under the completion lock and carried on the result:
-        # the bus event must report THIS completion's timing, never a
-        # re-read of the latest event a racing reversal could replace.
-        on_time = _was_on_time(instance, now, today)
-        await append_event(
-            database,
-            instance.id,
-            instance.child_id,
-            EVENT_COMPLETED,
-            actor_source=actor_source,
-            actor_user_id=actor_user_id,
-            actor_child_id=actor_child_id,
-            was_on_time=on_time,
-            now=now,
-        )
-    return CompletionResult("done", appended=True, was_on_time=on_time)
-
-
-async def uncomplete_instance(
-    database: NestQuestDatabase,
-    instance_id: int,
-    *,
-    actor_source: str,
-    actor_user_id: str | None = None,
-    actor_child_id: int | None = None,
-    now: datetime.datetime | None = None,
-    today: datetime.date | None = None,
-) -> CompletionResult:
-    """Append an uncompleted event unless the instance is already open.
-
-    Returns the derived state ``open``, or ``missed`` when the instance
-    is past due (``due_date`` before HA-local ``today``); ``appended``
-    reports whether THIS call appended (False on an already-open
-    no-op).  Unknown ``instance_id`` raises ValueError naming the
-    field.  Existence, latest-event, and the append run under one
-    connection lock so a concurrent uncomplete cannot double-append.
-    The original completed row is not modified.
-    """
-    instance_id = _validate_int_id(instance_id, "instance_id")
-    actor_source, actor_user_id, actor_child_id = _validate_actor(
-        actor_source, actor_user_id, actor_child_id
-    )
-    today_date = _resolve_today(today)
-    async with _reentrant_connection_lock(database):
-        instance = await QuestInstancesDao(database).get_by_id(instance_id)
-        if instance is None:
-            raise ValueError(
-                f"instance_id: quest instance {instance_id} does not exist"
-            )
-        latest = await CompletionEventsDao(database).get_latest_for_instance(
-            instance_id
-        )
-        if latest is None or latest.event_type == EVENT_UNCOMPLETED:
-            return CompletionResult(
-                _derived_state(instance, latest, today_date),
-                appended=False,
-            )
-        if latest.event_type != EVENT_COMPLETED:
-            raise ValueError(
-                f"event_type must be '{EVENT_COMPLETED}' or "
-                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
-            )
-        latest = await append_event(
-            database,
-            instance.id,
-            instance.child_id,
-            EVENT_UNCOMPLETED,
-            actor_source=actor_source,
-            actor_user_id=actor_user_id,
-            actor_child_id=actor_child_id,
-            was_on_time=None,
-            now=now,
-        )
-    return CompletionResult(
-        _derived_state(instance, latest, today_date), appended=True
-    )
-
-
-async def list_missed_for_child(
-    database: NestQuestDatabase,
-    child_id: int,
-    range_start: str,
-    range_end: str,
-    *,
-    today: datetime.date | None = None,
-) -> list[QuestInstanceRecord]:
-    """Return the child's missed instances due in the closed date range.
-
-    Missed means the latest event state is open and ``due_date`` is
-    before ``today`` (HA-local, threaded).  Uses
-    :meth:`QuestInstancesDao.list_by_date_range` plus derived state.
-    Never appends a missed event.  Instances and latest events are
-    read inside the connection lock so the list is one snapshot.
-    """
-    child_id = _validate_int_id(child_id, "child_id")
-    today_date = _resolve_today(today)
-    async with _connection_lock(database):
-        instances = await QuestInstancesDao(database).list_by_date_range(
-            child_id, range_start, range_end
-        )
-        events = CompletionEventsDao(database)
-        missed: list[QuestInstanceRecord] = []
-        for instance in instances:
-            latest = await events.get_latest_for_instance(instance.id)
-            if _derived_state(instance, latest, today_date) == "missed":
-                missed.append(instance)
-    return missed
+from .core.completion import *  # noqa: F401,F403

custom_components/nestquest/coordinator.py

@@ -11,6 +11,15 @@ refresh updates the whole board coherently.
 host clock and never UTC, matching the materialization and completion
 layers.
 
+The snapshot assembly itself lives in the Home-Assistant-free
+:mod:`custom_components.nestquest.core.snapshot` module
+(:func:`~core.snapshot.build_snapshot`); this coordinator is now a thin
+HA wrapper that resolves the local timezone and reads the settings handed
+into its constructor, then delegates to that builder, passing the SAME
+HA-local ``now`` it resolved in one clock read.  The API service's panel
+snapshot route shares the same builder, so both consumers render ONE
+snapshot shape.
+
 Presence is resolved through the SAME engine the materializer uses
 (:class:`~.presence.PresenceEngine`): schedules and overrides are read
 with the public DAO methods and the engine's anchor-date arithmetic
@@ -27,13 +36,11 @@ from __future__ import annotations
 
 import asyncio
 import datetime
-from dataclasses import dataclass
 from zoneinfo import ZoneInfo
 
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator
 
-from .completion import derive_state
 from .const import (
     CONF_UPDATE_INTERVAL,
     DEFAULT_UPDATE_INTERVAL,
@@ -41,66 +48,21 @@ from .const import (
     LOGGER,
     MIN_UPDATE_INTERVAL,
 )
-from .dao_children import ChildrenDao
-from .dao_instances import (
-    CompletionEventsDao,
-    QuestInstancesDao,
-)
-from .dao_rules import QuestDefinitionsDao
-from .dao_presence import PresenceOverridesDao, PresenceSchedulesDao
-from .db import NestQuestDatabase
-from .presence import (
-    MAX_PREVIEW_SCAN_DAYS,
-    PresenceEngine,
-    PresenceOverride,
-    PresenceSchedule,
+from .core.db import NestQuestDatabase
+from .core.settings import NestQuestSettings
+from .core.snapshot import (
+    ChildDaySnapshot,
+    NestQuestSnapshot,
+    QuestInstanceView,
+    build_snapshot,
 )
 
-
-@dataclass(frozen=True)
-class QuestInstanceView:
-    """One instance plus everything the entities render from it."""
-
-    instance_id: int
-    definition_id: int
-    child_id: int
-    title: str
-    icon: str | None
-    window: str
-    due_date: str
-    due_time: str | None
-    state: str  # open | done | missed
-    overdue: bool
-    completed_at: str | None
-    was_on_time: bool | None
-
-
-@dataclass(frozen=True)
-class ChildDaySnapshot:
-    """One active child's day: instances, presence, and rollup counts."""
-
-    child_id: int
-    child_name: str
-    instances: tuple[QuestInstanceView, ...]
-    present: bool
-    due_today: int
-    completed_today: int
-    remaining_today: int
-    completion_pct: int
-    #: For a child away today: the ISO date of their next present day
-    #: (the panel's away plate renders ``Returns <weekday>, <Mon D>``
-    #: from it).  ``None`` when the child is present today or no
-    #: present day exists within the presence engine's scan cap.
-    next_present: str | None = None
-
-
-@dataclass(frozen=True)
-class NestQuestSnapshot:
-    """The coordinator's whole-entity data payload."""
-
-    today_iso: str
-    children: tuple[ChildDaySnapshot, ...]
-    cycle_day: int
+__all__ = [
+    "ChildDaySnapshot",
+    "NestQuestCoordinator",
+    "NestQuestSnapshot",
+    "QuestInstanceView",
+]
 
 
 class NestQuestCoordinator(DataUpdateCoordinator):
@@ -121,6 +83,7 @@ class NestQuestCoordinator(DataUpdateCoordinator):
         *,
         entry_id: str,
         database: NestQuestDatabase,
+        settings: NestQuestSettings,
         update_interval_seconds: int | None = None,
     ) -> None:
         interval = update_interval_seconds
@@ -138,6 +101,7 @@ class NestQuestCoordinator(DataUpdateCoordinator):
         )
         self.entry_id = entry_id
         self.database = database
+        self.settings = settings
         self._refresh_lock = asyncio.Lock()
 
     async def async_refresh(self) -> None:
@@ -153,140 +117,6 @@ class NestQuestCoordinator(DataUpdateCoordinator):
 
     async def _async_update_data(self) -> NestQuestSnapshot:
         now = self._local_now()
-        today = now.date()
-        today_iso = today.isoformat()
-
-        children = await ChildrenDao(self.database).list_active()
-
-        schedules: dict[int, PresenceSchedule] = {}
-        overrides: dict[int, list[PresenceOverride]] = {}
-        for child in children:
-            schedule = await PresenceSchedulesDao(self.database).get_by_child(
-                child.id
-            )
-            if schedule is not None:
-                schedules[child.id] = PresenceSchedule.decode(
-                    child.id, schedule.anchor_date, schedule.pattern
-                )
-            window_end = today + datetime.timedelta(
-                days=MAX_PREVIEW_SCAN_DAYS
-            )
-            window_end_iso = window_end.isoformat()
-            ranged = await PresenceOverridesDao(
-                self.database
-            ).list_by_child_and_range(child.id, today_iso, window_end_iso)
-            if ranged:
-                # The engine validates MODEL objects, not DAO records;
-                # each record converts losslessly (the schema guarantees
-                # end >= start and a real is_present).
-                overrides[child.id] = [
-                    PresenceOverride(
-                        record.child_id,
-                        record.start_date,
-                        record.end_date,
-                        record.is_present,
-                        record.note,
-                    )
-                    for record in ranged
-                ]
-        engine = PresenceEngine(schedules, overrides)
-
-        instances_dao = QuestInstancesDao(self.database)
-        events_dao = CompletionEventsDao(self.database)
-        definitions_dao = QuestDefinitionsDao(self.database)
-
-        snapshots: list[ChildDaySnapshot] = []
-        for child in children:
-            instances = await instances_dao.list_by_date_range(
-                child.id, today_iso, today_iso
-            )
-            views: list[QuestInstanceView] = []
-            for instance in instances:
-                latest = await events_dao.get_latest_for_instance(instance.id)
-                definition = await definitions_dao.get(instance.definition_id)
-                state = derive_state(instance, latest, today)
-                overdue = False
-                if state == "open" and instance.due_date == today_iso:
-                    if instance.due_time is not None:
-                        due_moment = datetime.datetime.strptime(
-                            instance.due_time, "%H:%M"
-                        ).time()
-                        overdue = now.time() > due_moment
-                views.append(
-                    QuestInstanceView(
-                        instance_id=instance.id,
-                        definition_id=instance.definition_id,
-                        child_id=instance.child_id,
-                        title=definition.title if definition else "Quest",
-                        icon=definition.icon if definition else None,
-                        window=instance.window,
-                        due_date=instance.due_date,
-                        due_time=instance.due_time,
-                        state=state,
-                        overdue=overdue,
-                        completed_at=(
-                            latest.occurred_at
-                            if latest is not None
-                            and latest.event_type == "completed"
-                            else None
-                        ),
-                        was_on_time=(
-                            latest.was_on_time
-                            if latest is not None
-                            and latest.event_type == "completed"
-                            else None
-                        ),
-                    )
-                )
-            due = len(views)
-            completed = sum(1 for view in views if view.state == "done")
-            remaining = due - completed
-            child_present = engine.is_present(child.id, today)
-            next_present: str | None = None
-            if not child_present:
-                try:
-                    next_present = engine.next_present_dates(
-                        child.id, today, 1
-                    )[0].isoformat()
-                except ValueError:
-                    next_present = None
-            snapshots.append(
-                ChildDaySnapshot(
-                    child_id=child.id,
-                    child_name=child.display_name,
-                    instances=tuple(views),
-                    present=child_present,
-                    due_today=due,
-                    completed_today=completed,
-                    remaining_today=remaining,
-                    completion_pct=(
-                        round(completed * 100 / due) if due else 100
-                    ),
-                    next_present=next_present,
-                )
-            )
-
-        return NestQuestSnapshot(
-            today_iso=today_iso,
-            children=tuple(snapshots),
-            cycle_day=_cycle_day(schedules, children, today),
+        return await build_snapshot(
+            self.database, self.settings, now
         )
-
-
-def _cycle_day(
-    schedules: dict[int, PresenceSchedule], children, today: datetime.date
-) -> int:
-    """Return today's 1-based day in the first scheduled child's cycle.
-
-    Anchor-date arithmetic ONLY (D-004): the day offset is computed from
-    the schedule's own anchor, never ISO week numbers or parity, so a
-    53-week year cannot silently invert the cycle.
-    """
-    for child in children:
-        schedule = schedules.get(child.id)
-        if schedule is None:
-            continue
-        days = (today - schedule.anchor_date).days
-        cycle_length = schedule.cycle_length_weeks * 7
-        return (days % cycle_length) + 1
-    return 0

custom_components/nestquest/core/admin_allowlist.py

@@ -0,0 +1,153 @@
+"""Business layer for the admin allowlist (Feature 03).
+
+Sits between the options flow / Feature 09 service gate and the typed
+:class:`~.dao_children.AdminUsersDao`.  The allowlist stores Home
+Assistant user IDs — never usernames or display names (feature
+guardrail) — and an empty allowlist must fail closed: every function
+here refuses to write an empty allowlist, so the owner can never be
+accidentally locked out of admin operations by a bad save.
+
+Shape policy: a user id is a non-empty trimmed string.  Duplicate ids
+in one write are rejected up front — they would silently map to one
+row and hide a caller bug.  Writes replace the allowlist atomically:
+the diff (additions and removals) is computed and applied inside one
+transaction under the connection-scoped lock shared with the DAOs, so
+a concurrent reader never observes a half-applied sync.
+
+Seed policy (:func:`seed_setup_admin`): the allowlist is seeded only
+when it is EMPTY, so re-running setup never resurrects a deliberately
+narrowed list.  The setup user (the HA user who completed the config
+flow, via the entry context) is added automatically so the owner is
+never locked out on first setup; a stored entry-data copy of the list
+re-seeds a lost database.
+"""
+from __future__ import annotations
+
+import datetime
+import logging
+
+from .dao_children import AdminUsersDao, _connection_lock
+from .db import NestQuestDatabase
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _now_stamp() -> str:
+    """UTC second-precision stamp, matching the registry's policy."""
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(
+        timespec="seconds"
+    )
+
+
+def _validate_user_id(value: object) -> str:
+    """Return ``value`` trimmed; raise unless a non-empty string."""
+    if not isinstance(value, str):
+        raise ValueError(
+            f"admin user id must be a string, got {value!r}"
+        )
+    trimmed = value.strip()
+    if not trimmed:
+        raise ValueError("admin user id must not be empty")
+    return trimmed
+
+
+async def list_admin_ids(database: NestQuestDatabase) -> list[str]:
+    """Return the allowlisted HA user IDs in storage order."""
+    return [row.ha_user_id for row in await AdminUsersDao(database).list()]
+
+
+async def set_admin_ids(
+    database: NestQuestDatabase, user_ids: list[str]
+) -> None:
+    """Replace the allowlist with exactly ``user_ids`` (atomic sync).
+
+    Refuses an empty list — an empty allowlist must fail closed, and
+    the only way to reach one through this API would be removing the
+    last admin, so that removal is refused here with a clear error.
+    Refuses non-string, empty, or duplicate ids up front.  The diff
+    against the current allowlist (additions and removals) applies
+    inside one transaction under the connection lock.
+    """
+    if not isinstance(user_ids, list):
+        raise ValueError("user_ids must be a list of HA user id strings")
+    normalized: list[str] = []
+    for value in user_ids:
+        normalized.append(_validate_user_id(value))
+    if len(set(normalized)) != len(normalized):
+        raise ValueError("user_ids must not contain duplicates")
+    if not normalized:
+        raise ValueError(
+            "refusing to empty the admin allowlist: at least one admin "
+            "must remain (an empty allowlist fails closed)"
+        )
+    dao = AdminUsersDao(database)
+    async with _connection_lock(database):
+        async with database.transaction():
+            current = {row.ha_user_id for row in await dao.list()}
+            target = set(normalized)
+            for user_id in sorted(current - target):
+                await dao.remove(user_id)
+            for user_id in normalized:
+                await dao.add(user_id, _now_stamp())
+
+
+async def is_admin(
+    database: NestQuestDatabase, user_id: object
+) -> bool:
+    """Resolve an HA user ID against the allowlist — FAILS CLOSED.
+
+    True only for an allowlisted user id.  Everything else is False:
+    a non-allowlisted id, an unknown id, a None or non-string value
+    (a service call with no user context), and an empty allowlist
+    (nobody is admin rather than everybody).  The Feature 09 gate
+    wraps every admin-only service with this verdict; it never raises
+    for malformed input — malformed means not admin.
+    """
+    if not isinstance(user_id, str) or not user_id:
+        return False
+    return await AdminUsersDao(database).exists(user_id)
+
+
+async def seed_setup_admin(
+    database: NestQuestDatabase,
+    *,
+    stored_admin_ids: list[str] | None = None,
+    context_user_id: str | None = None,
+    owner_ids: list[str] | None = None,
+) -> list[str]:
+    """Seed an empty allowlist so the owner is never locked out.
+
+    Only acts when the allowlist is EMPTY.  Preference order: the
+    stored persisted copy of the list (the options flow's current
+    selection, then the config flow's original — disaster recovery for
+    a lost database), then the HA user who completed the config flow
+    (``context_user_id``), then — when no caller identity survived at
+    all — every Home Assistant OWNER account (``owner_ids``), so a
+    first setup whose flow context lost the user id still seeds a
+    working admin.  Returns the allowlist after seeding.  Non-empty
+    allowlists are returned untouched — re-running setup must never
+    resurrect a deliberately narrowed list.
+    """
+    dao = AdminUsersDao(database)
+    async with _connection_lock(database):
+        current = [row.ha_user_id for row in await dao.list()]
+        if current:
+            return current
+        candidates: list[str] = []
+        if stored_admin_ids is not None:
+            if not isinstance(stored_admin_ids, list):
+                raise ValueError(
+                    "stored_admin_ids must be a list of HA user id strings"
+                )
+            candidates = [_validate_user_id(value) for value in stored_admin_ids]
+        elif context_user_id is not None:
+            candidates = [_validate_user_id(context_user_id)]
+        elif owner_ids:
+            if not isinstance(owner_ids, list):
+                raise ValueError(
+                    "owner_ids must be a list of HA user id strings"
+                )
+            candidates = [_validate_user_id(value) for value in owner_ids]
+        for user_id in candidates:
+            await dao.add(user_id, _now_stamp())
+        return [row.ha_user_id for row in await dao.list()]

custom_components/nestquest/core/children.py

@@ -0,0 +1,280 @@
+"""Business layer for the children registry (Feature 03).
+
+Sits between the Feature 09 service gate and the typed
+:class:`~.dao_children.ChildrenDao`: callers get validation, name
+policies and the duplicate-name warning here, and never talk to the
+DAO or SQL directly.  Children are never hard-deleted — deactivation
+is a separate explicit operation (:func:`set_child_active`), so
+completion history keeps its references (feature guardrail).
+
+Name policy: the display name is required and trimmed; an empty or
+whitespace-only name is rejected with ValueError.  A duplicate display
+name is ALLOWED (two children may legitimately share a nickname) but
+logged as a warning so an accidental double-add is visible in the HA
+log.  The duplicate check is case-insensitive and whitespace-normalised
+on both sides, because "ada" and "Ada " are the same name to a parent.
+
+Colour and avatar are optional free-form strings, trimmed when present;
+``sort_order`` is an int with the DAO/schema default of 0.  Clearing an
+optional field back to NULL is deliberately rejected: the DAO's update
+writes only provided fields (it cannot express NULL), so the business
+layer refuses an explicit ``None`` instead of silently ignoring it.
+Timestamps follow the module timestamp policy: the business layer
+stamps UTC ISO-8601 at second precision so every row it creates is
+uniform.
+"""
+from __future__ import annotations
+
+import datetime
+import logging
+
+from .dao_children import ChildRecord, ChildrenDao, _connection_lock
+from .db import NestQuestDatabase
+
+LOGGER = logging.getLogger(__name__)
+
+#: Sentinel distinguishing "argument omitted" from "explicit SQL NULL"
+#: in :func:`edit_child`.
+_UNSET = object()
+
+
+def _now_stamp() -> str:
+    """Return the module's strict UTC second-precision stamp."""
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(
+        timespec="seconds"
+    )
+
+
+def _validate_text(
+    value: object, field: str, *, required: bool = False
+) -> str | None:
+    """Validate a free-text field and return it trimmed.
+
+    ``None`` raises when ``required`` and otherwise returns None.  A
+    non-string value is rejected; an empty result is rejected for
+    required fields (whitespace-only names are empty to a parent).
+    """
+    if value is None:
+        if required:
+            raise ValueError(f"{field} is required")
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a string, got {value!r}")
+    trimmed = value.strip()
+    if required and not trimmed:
+        raise ValueError(f"{field} is required")
+    return trimmed
+
+
+def _validate_sort_order(value: object) -> int:
+    """Reject non-int sort orders (bools included) before the DAO."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"sort_order must be an integer, got {value!r}")
+    return value
+
+
+def _validate_child_id(value: object) -> int:
+    """Reject non-int child ids (bools included) before any lookup.
+
+    SQLite binds Python bools as integers, so ``True`` would silently
+    address child 1 and a float would round — malformed service input
+    must never mutate the wrong profile.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"child_id must be an integer, got {value!r}")
+    return value
+
+
+async def _warn_on_duplicate_name(
+    database: NestQuestDatabase,
+    display_name: str,
+    *,
+    exclude_child_id: int | None = None,
+) -> None:
+    """Log a warning when ``display_name`` duplicates an existing child.
+
+    Case-insensitive and whitespace-normalised on both sides.  The
+    duplicate is still allowed — this only makes it visible; the log
+    line names both rows so an accidental double-add can be found.
+    ``exclude_child_id`` removes the child being edited from the scan,
+    so an edit only warns when the result collides with a DIFFERENT
+    child's name — including case-only edits, where the self-comparison
+    would otherwise hide a real duplicate.
+    """
+    lowered = display_name.casefold()
+    for child in await ChildrenDao(database).list_all():
+        if exclude_child_id is not None and child.id == exclude_child_id:
+            continue
+        if child.display_name.strip().casefold() == lowered:
+            LOGGER.warning(
+                "Child display name %r duplicates existing child %d "
+                "(%r); allowed, but check this was intentional",
+                display_name,
+                child.id,
+                child.display_name,
+            )
+            return
+
+
+async def create_child(
+    database: NestQuestDatabase,
+    display_name: str,
+    *,
+    colour: str | None = None,
+    avatar_ref: str | None = None,
+    sort_order: int = 0,
+) -> ChildRecord:
+    """Create a child profile and return the stored record.
+
+    The display name is required, trimmed, and rejected when empty.
+    A duplicate display name (case-insensitive) is allowed but logged
+    as a warning.  The scan and the INSERT run inside the
+    connection-scoped lock shared with the DAOs, so a concurrent
+    create of the same normalised name queues behind the first insert
+    and sees it — the duplicate still warns; it can never slip through
+    unlogged.
+    """
+    name = _validate_text(display_name, "display_name", required=True)
+    assert name is not None
+    colour_value = _validate_text(colour, "colour")
+    avatar_value = _validate_text(avatar_ref, "avatar_ref")
+    order = _validate_sort_order(sort_order)
+    async with _connection_lock(database):
+        await _warn_on_duplicate_name(database, name)
+        created = await ChildrenDao(database).create(
+            name,
+            _now_stamp(),
+            colour=colour_value,
+            avatar_ref=avatar_value,
+            sort_order=order,
+        )
+    return created
+
+
+async def edit_child(
+    database: NestQuestDatabase,
+    child_id: int,
+    *,
+    display_name: str | object = _UNSET,
+    colour: str | None | object = _UNSET,
+    avatar_ref: str | None | object = _UNSET,
+    sort_order: int | object = _UNSET,
+) -> ChildRecord:
+    """Edit a child profile and return the updated record.
+
+    Arguments default to the module sentinel ``_UNSET`` meaning "leave
+    this field alone".  An explicitly passed ``None`` for an optional
+    field raises: the DAO's update writes only provided fields and
+    cannot express NULL, so a silent no-op would mask the caller's
+    intent (see the module docstring).  A provided display name is
+    validated like create's; the duplicate scan excludes only the child
+    being edited, so a case-only edit colliding with another child's
+    normalised name still warns.  Raises ValueError when the child does
+    not exist.
+
+    Atomicity: the existence check, the duplicate scan, the UPDATE and
+    the readback all run inside the connection-scoped lock shared with
+    the DAOs, so another edit cannot slip between this call's UPDATE
+    and its readback — the returned record is exactly the one this
+    edit produced, not a later writer's.
+    """
+    _validate_child_id(child_id)
+    async with _connection_lock(database):
+        dao = ChildrenDao(database)
+        existing = await dao.get(child_id)
+        if existing is None:
+            raise ValueError(f"child {child_id} does not exist")
+        updates: dict[str, object] = {}
+        if display_name is not _UNSET:
+            name = _validate_text(
+                display_name, "display_name", required=True
+            )
+            assert name is not None
+            await _warn_on_duplicate_name(
+                database, name, exclude_child_id=child_id
+            )
+            updates["display_name"] = name
+        if colour is not _UNSET:
+            value = _validate_text(colour, "colour")
+            if value is None:
+                raise ValueError(
+                    "clearing colour is not supported; pass a replacement "
+                    "value or omit the field"
+                )
+            updates["colour"] = value
+        if avatar_ref is not _UNSET:
+            value = _validate_text(avatar_ref, "avatar_ref")
+            if value is None:
+                raise ValueError(
+                    "clearing avatar_ref is not supported; pass a "
+                    "replacement value or omit the field"
+                )
+            updates["avatar_ref"] = value
+        if sort_order is not _UNSET:
+            updates["sort_order"] = _validate_sort_order(sort_order)
+        if updates:
+            await dao.update(child_id, **updates)
+        edited = await dao.get(child_id)
+    assert edited is not None
+    return edited
+
+
+async def set_child_active(
+    database: NestQuestDatabase, child_id: int, is_active: bool
+) -> ChildRecord:
+    """Deactivate or reactivate a child; returns the updated record.
+
+    Deactivation hides the child from the panel without deleting their
+    history (feature guardrail); this is the only removal path.
+    ``is_active`` must be a real bool: the DAO's ``int()`` would
+    otherwise silently coerce strings and numerics ("1", 0) into a
+    state the caller never asked for.  Raises ValueError when the
+    child does not exist.
+
+    Atomicity: existence check, UPDATE and readback run inside the
+    connection-scoped lock, so a concurrent opposite transition cannot
+    make this call report the other caller's value.
+    """
+    _validate_child_id(child_id)
+    async with _connection_lock(database):
+        dao = ChildrenDao(database)
+        if await dao.get(child_id) is None:
+            raise ValueError(f"child {child_id} does not exist")
+        if not isinstance(is_active, bool):
+            raise ValueError(
+                f"is_active must be a real bool, got {is_active!r}"
+            )
+        await dao.set_active(child_id, is_active)
+        updated = await dao.get(child_id)
+    assert updated is not None
+    return updated
+
+
+async def reorder_children(
+    database: NestQuestDatabase, ordered_ids: list[int]
+) -> None:
+    """Rewrite the children's panel display order in one transaction.
+
+    ``ordered_ids`` must be a complete permutation of the children
+    table — every child id exactly once.  A partial list (missing an
+    existing child), an unknown id, or a duplicate is rejected with
+    ValueError before any write, so the current order survives a
+    rejected call.  The DAO enforces this inside its own transaction
+    (check and write are     atomic under the connection lock); this
+    wrapper additionally rejects non-integer ids up front, since
+    ``bool`` and floats would silently compare against stored integer
+    ids at the SQL layer.
+    """
+    for child_id in ordered_ids:
+        _validate_child_id(child_id)
+    await ChildrenDao(database).reorder(ordered_ids)
+
+
+async def list_children(
+    database: NestQuestDatabase, *, active_only: bool = False
+) -> list[ChildRecord]:
+    """Return children in display order (sort_order, then id)."""
+    dao = ChildrenDao(database)
+    if active_only:
+        return await dao.list_active()
+    return await dao.list_all()

custom_components/nestquest/core/completion.py

@@ -0,0 +1,549 @@
+"""Business layer for the completion event log (Feature 08).
+
+Sits between the Feature 09 service gate and the typed
+:class:`~.dao_instances.CompletionEventsDao`: callers get actor-shape
+validation and the UTC occurred-at stamp here, and never talk to the
+DAO or SQL directly.  This module is the only Feature-08 caller of
+:meth:`~.dao_instances.CompletionEventsDao.append`.  Completing an
+instance (no-op if already done) is :func:`complete_instance`;
+un-completing (no-op if already open) is :func:`uncomplete_instance`.
+Instance current state is derived from the latest event via
+:func:`instance_state` (``open`` / ``done`` / ``missed``); there is
+no status column.  ``missed`` is derived for past-due open instances
+(``due_date`` before HA-local ``today``) and is never stored as an
+event_type.
+
+Actor policy matches the schema CHECKs (D-008): ``actor_source`` is
+``'user'`` or ``'panel'`` only — never ``'service'``.  ``'user'``
+requires ``actor_user_id`` and forbids ``actor_child_id``; ``'panel'``
+requires ``actor_child_id`` (the tapped profile) and forbids
+``actor_user_id``.  Inverted shapes raise a field-naming ValueError
+before any write.
+
+``occurred_at`` is stamped UTC ISO-8601 at second precision with an
+explicit ``+00:00`` offset, matching the DAO's one accepted shape so
+lexicographic range queries stay exact.  ``was_on_time`` is required
+(True/False) for completed events; un-completions may pass None.  There
+is no permission check here (that is Feature 09).
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+
+from .dao_children import _CONNECTION_LOCKS, _connection_lock
+from .dao_instances import (
+    EVENT_COMPLETED,
+    EVENT_UNCOMPLETED,
+    CompletionEventRecord,
+    CompletionEventsDao,
+    QuestInstanceRecord,
+    QuestInstancesDao,
+)
+from .db import NestQuestDatabase
+
+#: Timestamp policy for completion_events.occurred_at: strict UTC
+#: ISO-8601 with explicit '+00:00' offset (module timestamp policy).
+_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
+
+
+def _now_stamp() -> str:
+    """Return the module's strict UTC second-precision stamp."""
+    return datetime.datetime.now(datetime.timezone.utc).strftime(
+        _UTC_TIMESTAMP_FORMAT
+    )
+
+
+def _stamp_occurred_at(now: datetime.datetime | None) -> str:
+    """Return a DAO-accepted UTC stamp for ``now``, or the current time."""
+    if now is None:
+        return _now_stamp()
+    if not isinstance(now, datetime.datetime):
+        raise ValueError(f"now must be a datetime, got {now!r}")
+    if now.tzinfo is None:
+        raise ValueError("now must be timezone-aware")
+    return now.astimezone(datetime.timezone.utc).strftime(
+        _UTC_TIMESTAMP_FORMAT
+    )
+
+
+def _completion_moment(
+    now: datetime.datetime | None,
+    today: datetime.date | None,
+) -> tuple[datetime.date, datetime.time | None]:
+    """Return the HA-local completion date and optional wall-clock time.
+
+    ``today`` is the HA-local calendar date when threaded (Feature 07
+    style).  ``now`` is a timezone-aware HA-local datetime; its wall
+    clock is used as-is and is never converted to UTC.  When ``today``
+    is omitted the date comes from ``now``.  When both are omitted the
+    host calendar date is the Feature 07 fallback — never the UTC
+    clock.  Time-of-day is None unless ``now`` is supplied; comparing
+    against ``due_time`` requires ``now``.
+    """
+    if now is not None:
+        if not isinstance(now, datetime.datetime):
+            raise ValueError(f"now must be a datetime, got {now!r}")
+        if now.tzinfo is None:
+            raise ValueError("now must be timezone-aware")
+    if today is not None:
+        completion_date = today
+    elif now is not None:
+        completion_date = now.date()
+    else:
+        completion_date = datetime.date.today()
+    if now is None:
+        return completion_date, None
+    return completion_date, now.time()
+
+
+def _resolve_today(today: datetime.date | None) -> datetime.date:
+    """Return the threaded HA-local date, or the host calendar date."""
+    if today is None:
+        return datetime.date.today()
+    return today
+
+
+def _derived_state(
+    instance: QuestInstanceRecord,
+    latest: CompletionEventRecord | None,
+    today: datetime.date,
+) -> str:
+    """Return ``open``, ``done``, or ``missed`` from event plus due date.
+
+    A latest completed event is ``done`` even when past due.  No events
+    or a latest uncompleted event is ``open``, or ``missed`` when
+    ``due_date`` is before ``today``.  ``missed`` is never an event_type.
+    """
+    if latest is None or latest.event_type == EVENT_UNCOMPLETED:
+        due_date = datetime.date.fromisoformat(instance.due_date)
+        if due_date < today:
+            return "missed"
+        return "open"
+    if latest.event_type == EVENT_COMPLETED:
+        return "done"
+    raise ValueError(
+        f"event_type must be '{EVENT_COMPLETED}' or "
+        f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
+    )
+
+
+def derive_state(
+    instance: QuestInstanceRecord,
+    latest: CompletionEventRecord | None,
+    today: datetime.date,
+) -> str:
+    """Public state derivation for the Feature 10 coordinator.
+
+    Thin wrapper over :func:`_derived_state`: ``open``, ``done``, or
+    ``missed`` from the latest event plus the due date (``missed`` is
+    derived, never an event_type).  ``today`` is the caller-resolved
+    HA-local date.
+    """
+    return _derived_state(instance, latest, today)
+
+
+def _was_on_time(
+    instance: QuestInstanceRecord,
+    now: datetime.datetime | None,
+    today: datetime.date | None,
+) -> bool:
+    """Return whether the completion moment is on time for ``instance``.
+
+    On ``due_date`` before ``due_time`` is on time; on ``due_date``
+    after ``due_time``, or any later date, is late.  With no
+    ``due_time``, on time if the completion date equals ``due_date``
+    (or is earlier); late if after ``due_date``.  Same-day
+    ``due_time`` comparison requires ``now``; UTC time-of-day is never
+    substituted.
+    """
+    completion_date, completion_time = _completion_moment(now, today)
+    due_date = datetime.date.fromisoformat(instance.due_date)
+    if completion_date < due_date:
+        return True
+    if completion_date > due_date:
+        return False
+    if instance.due_time is None:
+        return True
+    if completion_time is None:
+        raise ValueError("now is required to compare due_time")
+    due_time = datetime.datetime.strptime(instance.due_time, "%H:%M").time()
+    return completion_time <= due_time
+
+
+class _TaskReentrantLock:
+    """Shared connection lock the owning task may re-enter."""
+
+    def __init__(self, inner: asyncio.Lock) -> None:
+        self._inner = inner
+        self._task: asyncio.Task | None = None
+        self._depth = 0
+
+    def locked(self) -> bool:
+        return self._inner.locked()
+
+    async def acquire(self) -> bool:
+        task = asyncio.current_task()
+        if self._task is task:
+            self._depth += 1
+            return True
+        await self._inner.acquire()
+        self._task = task
+        self._depth = 1
+        return True
+
+    def release(self) -> None:
+        if self._task is not asyncio.current_task():
+            raise RuntimeError("lock released by a non-owner")
+        self._depth -= 1
+        if self._depth == 0:
+            self._task = None
+            self._inner.release()
+
+    async def __aenter__(self) -> _TaskReentrantLock:
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        self.release()
+
+
+def _reentrant_connection_lock(database) -> _TaskReentrantLock:
+    """Return the shared connection lock, made task-reentrant.
+
+    ``CompletionEventsDao.append`` also acquires this lock, so
+    check+append in :func:`complete_instance` and
+    :func:`uncomplete_instance` must re-enter on the same task.  The
+    wrapper is stored in the shared dict so the DAO sees the same
+    object.
+    """
+    loop = asyncio.get_running_loop()
+    key = (id(database), id(loop))
+    lock = _CONNECTION_LOCKS.get(key)
+    if isinstance(lock, _TaskReentrantLock):
+        return lock
+    wrapped = _TaskReentrantLock(
+        lock if lock is not None else asyncio.Lock()
+    )
+    _CONNECTION_LOCKS[key] = wrapped
+    return wrapped
+
+
+def _validate_int_id(value: object, field: str) -> int:
+    """Reject non-int ids (bools included) before any lookup."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{field} must be an integer, got {value!r}")
+    return value
+
+
+def _validate_event_type(value: object) -> str:
+    """Return a schema-legal event type, or raise naming the field."""
+    if value not in (EVENT_COMPLETED, EVENT_UNCOMPLETED):
+        raise ValueError(
+            f"event_type must be '{EVENT_COMPLETED}' or "
+            f"'{EVENT_UNCOMPLETED}', got {value!r}"
+        )
+    return value
+
+
+def _validate_actor(
+    actor_source: object,
+    actor_user_id: object,
+    actor_child_id: object,
+) -> tuple[str, str | None, int | None]:
+    """Return a schema-legal actor triple, or raise naming the field.
+
+    ``'user'`` requires a non-empty ``actor_user_id`` string and forbids
+    ``actor_child_id``.  ``'panel'`` requires an integer
+    ``actor_child_id`` and forbids ``actor_user_id``.  Any other
+    ``actor_source`` (including ``'service'``) is rejected.
+    """
+    if actor_source not in ("user", "panel"):
+        raise ValueError(
+            f"actor_source must be 'user' or 'panel', got {actor_source!r}"
+        )
+    if actor_source == "user":
+        if not isinstance(actor_user_id, str) or not actor_user_id.strip():
+            raise ValueError("actor_source 'user' requires actor_user_id")
+        if actor_child_id is not None:
+            raise ValueError(
+                "actor_source 'user' must not carry actor_child_id"
+            )
+        return "user", actor_user_id.strip(), None
+    if actor_user_id is not None:
+        raise ValueError("actor_source 'panel' must not carry actor_user_id")
+    if actor_child_id is None:
+        raise ValueError(
+            "actor_source 'panel' requires actor_child_id"
+        )
+    return (
+        "panel",
+        None,
+        _validate_int_id(actor_child_id, "actor_child_id"),
+    )
+
+
+def _validate_was_on_time(
+    event_type: str, was_on_time: object
+) -> bool | None:
+    """Return a real bool or None; completed events require True/False."""
+    if was_on_time is not None and type(was_on_time) is not bool:
+        raise ValueError(
+            f"was_on_time must be True, False or None, got {was_on_time!r}"
+        )
+    if event_type == EVENT_COMPLETED and was_on_time is None:
+        raise ValueError(
+            "a completed event requires was_on_time (True/False)"
+        )
+    return was_on_time
+
+
+async def append_event(
+    database: NestQuestDatabase,
+    instance_id: int,
+    child_id: int,
+    event_type: str,
+    *,
+    actor_source: str,
+    actor_user_id: str | None = None,
+    actor_child_id: int | None = None,
+    was_on_time: bool | None = None,
+    now: datetime.datetime | None = None,
+) -> CompletionEventRecord:
+    """Append one completion or un-completion event and return the row.
+
+    Validates actor shapes and the completed-event on-time requirement
+    before calling :meth:`CompletionEventsDao.append`.  ``occurred_at``
+    is stamped here (UTC ``+00:00``); pass ``now`` to pin the clock.
+    """
+    instance_id = _validate_int_id(instance_id, "instance_id")
+    child_id = _validate_int_id(child_id, "child_id")
+    event_type = _validate_event_type(event_type)
+    actor_source, actor_user_id, actor_child_id = _validate_actor(
+        actor_source, actor_user_id, actor_child_id
+    )
+    was_on_time = _validate_was_on_time(event_type, was_on_time)
+    occurred_at = _stamp_occurred_at(now)
+    return await CompletionEventsDao(database).append(
+        instance_id,
+        child_id,
+        event_type,
+        actor_source,
+        occurred_at,
+        was_on_time,
+        actor_user_id=actor_user_id,
+        actor_child_id=actor_child_id,
+    )
+
+
+async def instance_state(
+    database: NestQuestDatabase,
+    instance_id: int,
+    *,
+    today: datetime.date | None = None,
+) -> str:
+    """Return ``open``, ``done``, or ``missed`` from the latest event.
+
+    No events, or a latest event of uncompleted, is ``open`` unless
+    ``due_date`` is before ``today`` (HA-local, threaded), in which
+    case it is ``missed``.  A latest event of completed is ``done``
+    even when past due.  ``missed`` is never stored as an event_type.
+    Unknown ``instance_id`` raises ValueError naming the field.
+    Existence and the latest event are read inside the connection lock
+    so the answer is one snapshot.
+    """
+    instance_id = _validate_int_id(instance_id, "instance_id")
+    today_date = _resolve_today(today)
+    async with _connection_lock(database):
+        instance = await QuestInstancesDao(database).get_by_id(instance_id)
+        if instance is None:
+            raise ValueError(
+                f"instance_id: quest instance {instance_id} does not exist"
+            )
+        latest = await CompletionEventsDao(database).get_latest_for_instance(
+            instance_id
+        )
+    return _derived_state(instance, latest, today_date)
+
+
+class CompletionResult(str):
+    """The derived instance state, carrying the append verdict.
+
+    A ``str`` subclass so every existing ``result == "done"`` contract
+    keeps working; ``appended`` reports whether THIS call actually
+    appended an event (decided under the same lock as the append), so
+    a caller — the Feature 09 service path firing bus events —
+    announces a transition exactly once even under a concurrent
+    duplicate call where the loser's write is a no-op.  A completion
+    also carries the ``was_on_time`` verdict computed under that same
+    lock, so the event payload never re-reads mutable latest state a
+    racing reversal could have replaced.
+    """
+
+    appended: bool
+    was_on_time: bool | None
+
+    def __new__(
+        cls,
+        state: str,
+        *,
+        appended: bool,
+        was_on_time: bool | None = None,
+    ) -> "CompletionResult":
+        obj = super().__new__(cls, state)
+        obj.appended = appended
+        obj.was_on_time = was_on_time
+        return obj
+
+
+async def complete_instance(
+    database: NestQuestDatabase,
+    instance_id: int,
+    *,
+    actor_source: str,
+    actor_user_id: str | None = None,
+    actor_child_id: int | None = None,
+    now: datetime.datetime | None = None,
+    today: datetime.date | None = None,
+) -> CompletionResult:
+    """Append a completed event unless the instance is already done.
+
+    Returns the derived state ``done``; ``appended`` reports whether
+    THIS call appended (False on an already-done no-op).  Unknown
+    ``instance_id`` raises ValueError naming the field.  Existence,
+    latest-event, and the append run under one connection lock so a
+    concurrent complete cannot double-append.
+
+    ``was_on_time`` is computed from the HA-local completion moment
+    (threaded ``now`` / ``today``) against the instance ``due_date``
+    and optional ``due_time``.  ``now`` is the timezone-aware HA-local
+    datetime; its wall clock is never converted to UTC.  Same-day
+    ``due_time`` comparison requires ``now``.
+    """
+    instance_id = _validate_int_id(instance_id, "instance_id")
+    actor_source, actor_user_id, actor_child_id = _validate_actor(
+        actor_source, actor_user_id, actor_child_id
+    )
+    async with _reentrant_connection_lock(database):
+        instance = await QuestInstancesDao(database).get_by_id(instance_id)
+        if instance is None:
+            raise ValueError(
+                f"instance_id: quest instance {instance_id} does not exist"
+            )
+        latest = await CompletionEventsDao(database).get_latest_for_instance(
+            instance_id
+        )
+        if latest is not None and latest.event_type == EVENT_COMPLETED:
+            return CompletionResult("done", appended=False)
+        if latest is not None and latest.event_type != EVENT_UNCOMPLETED:
+            raise ValueError(
+                f"event_type must be '{EVENT_COMPLETED}' or "
+                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
+            )
+        # Computed under the completion lock and carried on the result:
+        # the bus event must report THIS completion's timing, never a
+        # re-read of the latest event a racing reversal could replace.
+        on_time = _was_on_time(instance, now, today)
+        await append_event(
+            database,
+            instance.id,
+            instance.child_id,
+            EVENT_COMPLETED,
+            actor_source=actor_source,
+            actor_user_id=actor_user_id,
+            actor_child_id=actor_child_id,
+            was_on_time=on_time,
+            now=now,
+        )
+    return CompletionResult("done", appended=True, was_on_time=on_time)
+
+
+async def uncomplete_instance(
+    database: NestQuestDatabase,
+    instance_id: int,
+    *,
+    actor_source: str,
+    actor_user_id: str | None = None,
+    actor_child_id: int | None = None,
+    now: datetime.datetime | None = None,
+    today: datetime.date | None = None,
+) -> CompletionResult:
+    """Append an uncompleted event unless the instance is already open.
+
+    Returns the derived state ``open``, or ``missed`` when the instance
+    is past due (``due_date`` before HA-local ``today``); ``appended``
+    reports whether THIS call appended (False on an already-open
+    no-op).  Unknown ``instance_id`` raises ValueError naming the
+    field.  Existence, latest-event, and the append run under one
+    connection lock so a concurrent uncomplete cannot double-append.
+    The original completed row is not modified.
+    """
+    instance_id = _validate_int_id(instance_id, "instance_id")
+    actor_source, actor_user_id, actor_child_id = _validate_actor(
+        actor_source, actor_user_id, actor_child_id
+    )
+    today_date = _resolve_today(today)
+    async with _reentrant_connection_lock(database):
+        instance = await QuestInstancesDao(database).get_by_id(instance_id)
+        if instance is None:
+            raise ValueError(
+                f"instance_id: quest instance {instance_id} does not exist"
+            )
+        latest = await CompletionEventsDao(database).get_latest_for_instance(
+            instance_id
+        )
+        if latest is None or latest.event_type == EVENT_UNCOMPLETED:
+            return CompletionResult(
+                _derived_state(instance, latest, today_date),
+                appended=False,
+            )
+        if latest.event_type != EVENT_COMPLETED:
+            raise ValueError(
+                f"event_type must be '{EVENT_COMPLETED}' or "
+                f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}"
+            )
+        latest = await append_event(
+            database,
+            instance.id,
+            instance.child_id,
+            EVENT_UNCOMPLETED,
+            actor_source=actor_source,
+            actor_user_id=actor_user_id,
+            actor_child_id=actor_child_id,
+            was_on_time=None,
+            now=now,
+        )
+    return CompletionResult(
+        _derived_state(instance, latest, today_date), appended=True
+    )
+
+
+async def list_missed_for_child(
+    database: NestQuestDatabase,
+    child_id: int,
+    range_start: str,
+    range_end: str,
+    *,
+    today: datetime.date | None = None,
+) -> list[QuestInstanceRecord]:
+    """Return the child's missed instances due in the closed date range.
+
+    Missed means the latest event state is open and ``due_date`` is
+    before ``today`` (HA-local, threaded).  Uses
+    :meth:`QuestInstancesDao.list_by_date_range` plus derived state.
+    Never appends a missed event.  Instances and latest events are
+    read inside the connection lock so the list is one snapshot.
+    """
+    child_id = _validate_int_id(child_id, "child_id")
+    today_date = _resolve_today(today)
+    async with _connection_lock(database):
+        instances = await QuestInstancesDao(database).list_by_date_range(
+            child_id, range_start, range_end
+        )
+        events = CompletionEventsDao(database)
+        missed: list[QuestInstanceRecord] = []
+        for instance in instances:
+            latest = await events.get_latest_for_instance(instance.id)
+            if _derived_state(instance, latest, today_date) == "missed":
+                missed.append(instance)
+    return missed

custom_components/nestquest/core/const.py

@@ -2,11 +2,19 @@
 from __future__ import annotations
 
 import logging
+import re
 
 DOMAIN = "nestquest"
 LOGGER_NAME = "custom_components.nestquest"
 LOGGER = logging.getLogger(LOGGER_NAME)
 
+#: Strict 24-hour ``HH:MM`` pattern shared by the options flow and the
+#: settings object's time validation, so a stored option and a freshly
+#: validated form submit parse the same way.  Defined here (HA-free) so
+#: both the integration's options flow and the core settings module
+#: import ONE pattern instead of re-copying it.
+TIME_PATTERN = re.compile(r"(?:[01]\d|2[0-3]):[0-5]\d")
+
 # Platforms set up per config entry (Feature 10): the per-child day
 # sensors and binary sensors.
 PLATFORMS: list[str] = ["sensor", "binary_sensor"]

custom_components/nestquest/core/events.py

@@ -0,0 +1,210 @@
+"""Transition-event payload construction for the NestQuest service paths (Feature 10).
+
+This module is PAYLOAD CONSTRUCTION ONLY: it builds and RETURNS the
+transition events (event type + payload dict) and never touches the
+Home Assistant event bus or config.  The caller decides how to fire
+them (the integration's re-export shim wires the returned events to
+``hass.bus.async_fire``).
+
+The four documented events (design/ENTITIES-AND-SERVICES.md §3, names
+in :mod:`~.const`): ``nestquest_quest_completed`` and
+``nestquest_quest_uncompleted`` fire from the completion service
+handlers on an actual transition (a no-op re-complete or re-uncomplete
+fires nothing), and ``nestquest_child_day_complete`` fires when a
+completion clears the child's whole day (quests were owed and none
+remain — a zero-quest day can never fire it, matching the all-done
+binary sensor's rule).  ``nestquest_quest_missed`` is the documented
+contract Feature 11's nightly sweep fires; :func:`build_quest_missed_event`
+builds it with exactly the payload the sweep hand-builds (§3), so the
+API plane can publish the same shape without re-deriving it.
+
+The completed-event and day-complete-event builders are split so the
+shim can fire ``nestquest_quest_completed`` BEFORE it evaluates the
+day-complete rule (the pre-extraction implementation fired the
+completed event on the bus first, then ran the day-complete DB reads;
+a failure in those reads or the ZoneInfo lookup must not suppress the
+completed event).  :func:`build_quest_completed_event` builds the
+completed event from the instance and its child/definition only;
+:func:`build_child_day_complete_event` runs the day-complete DB reads
+and returns the day-complete event (or ``None``).  The shim fires the
+completed event, then calls the day-complete builder and fires its
+result.  :func:`build_quest_uncompleted_events` builds the single
+uncompleted event.
+
+Payload policy: one dict carrying ``child_id``, ``child_name``,
+``instance_id``, ``quest_title``, the instance's ``window``/
+``due_date``/``due_time`` so automation authors can filter without a
+database lookup, and ``occurred_at`` — the event's own strict UTC
+ISO-8601 timestamp.  Completion payloads additionally carry
+``was_on_time``.  No other personal data: names and titles are the
+household's own records, and nothing beyond them leaks.
+
+Timezone policy: the day-complete check needs the HA-local "today",
+which the caller passes in as a plain :class:`datetime.date`.  Nothing
+here reads ``hass.config.time_zone`` — the integration owns HA
+timezone, the core owns the calendar arithmetic.
+"""
+from __future__ import annotations
+
+import datetime
+
+from .completion import derive_state
+from .const import (
+    EVENT_CHILD_DAY_COMPLETE,
+    EVENT_QUEST_COMPLETED,
+    EVENT_QUEST_MISSED,
+    EVENT_QUEST_UNCOMPLETED,
+)
+from .dao_children import ChildrenDao
+from .dao_instances import CompletionEventsDao, QuestInstancesDao
+from .dao_rules import QuestDefinitionsDao
+from .db import NestQuestDatabase
+
+#: Strict UTC ISO-8601 timestamp (the DAO layers' policy): one shape,
+#: explicit offset, second precision.
+_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
+
+
+def _now_stamp() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime(
+        _UTC_TIMESTAMP_FORMAT
+    )
+
+
+async def _instance_payload(
+    database: NestQuestDatabase, instance_id: int, now_stamp: str
+) -> dict:
+    """Build the shared event payload for one quest instance."""
+    instance = await QuestInstancesDao(database).get_by_id(instance_id)
+    if instance is None:
+        raise ValueError(
+            f"instance_id: quest instance {instance_id} does not exist"
+        )
+    child = await ChildrenDao(database).get(instance.child_id)
+    definition = await QuestDefinitionsDao(database).get(
+        instance.definition_id
+    )
+    return {
+        "child_id": instance.child_id,
+        "child_name": child.display_name if child else None,
+        "instance_id": instance.id,
+        "quest_title": definition.title if definition else None,
+        "window": instance.window,
+        "due_date": instance.due_date,
+        "due_time": instance.due_time,
+        "occurred_at": now_stamp,
+    }
+
+
+async def build_quest_completed_event(
+    database: NestQuestDatabase,
+    instance_id: int,
+    *,
+    was_on_time: bool | None,
+) -> tuple[str, dict]:
+    """Build the ``nestquest_quest_completed`` event for an actual
+    completion.
+
+    Called by the complete_quest service handler AFTER an actual
+    completion transition, with the completion's ``was_on_time`` —
+    computed under the completion lock and carried on the result — so
+    the payload never re-reads mutable latest state a racing reversal
+    could have replaced.  A no-op re-complete never reaches here.
+
+    Returns the ``(event_type, payload)`` tuple to fire.  This builder
+    touches NO day-complete state: it only reads the instance, its
+    child, and its definition, so a failure in the day-complete
+    evaluation (DB reads, timezone lookup in the shim) cannot suppress
+    the completed event.  The caller fires this BEFORE asking
+    :func:`build_child_day_complete_event` for the day-complete event.
+    """
+    now_stamp = _now_stamp()
+    payload = await _instance_payload(database, instance_id, now_stamp)
+    payload["was_on_time"] = was_on_time
+    return (EVENT_QUEST_COMPLETED, payload)
+
+
+async def build_child_day_complete_event(
+    database: NestQuestDatabase,
+    completed_payload: dict,
+    *,
+    today: datetime.date,
+) -> tuple[str, dict] | None:
+    """Build the ``nestquest_child_day_complete`` event for a
+    completion that cleared the child's whole day, or ``None`` when no
+    day-complete event should fire.
+
+    Called by the complete_quest service handler AFTER the
+    ``nestquest_quest_completed`` event has already been fired, with
+    that event's payload (so this builder reuses the same
+    ``occurred_at`` stamp and the same ``child_id`` / ``child_name``
+    the completed event carried — one transition, one shared
+    timestamp, matching the pre-extraction implementation).
+
+    Day-complete rule (identical to the pre-extraction implementation
+    and to the all-done binary sensor): quests were owed today and
+    none remain — a zero-quest day can never fire it.  Only a
+    completion of TODAY'S instance evaluates it: completing a
+    back-dated or future instance must not announce a cleared day.
+
+    ``today`` is the HA-local calendar date the day-complete rule is
+    evaluated against; the integration reads it from
+    ``hass.config.time_zone`` and passes it in, so this module never
+    touches HA config.
+    """
+    # Only a completion of TODAY'S instance evaluates the day-complete
+    # rule: completing a back-dated or future instance must not
+    # announce a cleared day.
+    if completed_payload["due_date"] != today.isoformat():
+        return None
+    instances = await QuestInstancesDao(database).list_by_date_range(
+        completed_payload["child_id"], today.isoformat(), today.isoformat()
+    )
+    completion_events = CompletionEventsDao(database)
+    remaining = 0
+    for instance in instances:
+        latest_for_instance = await completion_events.get_latest_for_instance(
+            instance.id
+        )
+        if derive_state(instance, latest_for_instance, today) != "done":
+            remaining += 1
+    if not instances or remaining:
+        return None
+    return (
+        EVENT_CHILD_DAY_COMPLETE,
+        {
+            "child_id": completed_payload["child_id"],
+            "child_name": completed_payload["child_name"],
+            "quests_due": len(instances),
+            "quests_completed": len(instances),
+            "occurred_at": completed_payload["occurred_at"],
+        },
+    )
+
+
+async def build_quest_uncompleted_events(
+    database: NestQuestDatabase, instance_id: int
+) -> list[tuple[str, dict]]:
+    """Build the ``nestquest_quest_uncompleted`` event for an actual reversal.
+
+    Returns a one-element list of ``(event_type, payload)`` to fire.
+    """
+    payload = await _instance_payload(database, instance_id, _now_stamp())
+    return [(EVENT_QUEST_UNCOMPLETED, payload)]
+
+
+async def build_quest_missed_event(
+    database: NestQuestDatabase, instance_id: int
+) -> tuple[str, dict]:
+    """Build the ``nestquest_quest_missed`` event for one instance.
+
+    The payload mirrors the nightly sweep's hand-built payload exactly
+    (the shared :func:`_instance_payload` shape: ``child_id``,
+    ``child_name``, ``instance_id``, ``quest_title``, ``window``,
+    ``due_date``, ``due_time``, ``occurred_at``), so the API plane's
+    missed path publishes the same event shape the integration's sweep
+    fires.  Like the sweep, this builder never mutates the instance or
+    writes a completion event — it reads only.
+    """
+    payload = await _instance_payload(database, instance_id, _now_stamp())
+    return (EVENT_QUEST_MISSED, payload)

custom_components/nestquest/core/materialize.py

@@ -0,0 +1,377 @@
+"""The materialization walk (Feature 07 core).
+
+:func:`materialize` turns the schedule rules + custody presence of the
+active quest definitions into concrete ``quest_instances`` rows over a
+date range.  It is the pure walk over definitions x dates x assignees x
+windows; HA scheduling (day-rollover triggers) is a separate later
+task and lives elsewhere.
+
+The walk is deterministic and idempotent:
+
+- All inputs — the active definitions with their rules, assignees and
+  windows, AND the assignee children's presence schedules and scoped
+  overrides — are read inside ONE locked transaction (see
+  :func:`~.dao_rules.load_materialization_input`), so the walk sees a
+  single coherent snapshot rather than a definition state from one
+  instant and a presence state from another.
+- Presence is snapshotted into an immutable
+  :class:`~.presence.PresenceEngine` from that same coherent read.
+- For each date in the range, each definition whose decoded rule
+  :func:`~.recurrence.occurs_on` on that date, each assignee who is
+  ``is_present`` on that date and each declared window, one instance is
+  written through :class:`~.dao_instances.QuestInstancesDao.upsert_if_valid`
+  with a ``generated_at`` stamp shared by the whole batch (one coherent
+  time per run).
+
+A config change that lands AFTER the snapshot is read but BEFORE a
+tuple's write (an assignment removed, a definition or child deactivated,
+a window removed) makes that tuple SKIP rather than abort the batch:
+:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` re-validates
+every materialization precondition (active definition, active child,
+live assignment, declared window, and its CURRENT ``due_time``) inside
+the SAME transaction as the INSERT, so the check and the write cannot be
+split by a racing config edit.
+
+The upsert is idempotent on (definition_id, child_id, due_date,
+window), so re-running the materialization over the same range never
+duplicates a row; a tuple whose instance is already completed is SKIPPED
+(never rewritten, never raised) by
+:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`.
+
+Regeneration: a config or presence change must rebuild future instances
+so they track the new state.  :func:`regenerate_for_definition` covers
+definition edits / reassignment (Features 06/07); :func:`regenerate_for_child`
+covers a single child's presence change (Feature 09).  Both delete the
+affected open instances at or after today — never a completed instance,
+never the past — and re-run the walk over the rolling horizon
+``[today, today + horizon_days]`` (``horizon_days`` defaults to
+``DEFAULT_HORIZON_DAYS``).
+
+HOOK (Feature 09 presence services): the presence business layer that
+lands in Feature 09 MUST call :func:`regenerate_for_child` after EVERY
+presence-state write so a child's future instances track its presence:
+``set_presence_pattern`` (including clearing/setting an empty pattern),
+deleting/clearing the presence schedule
+(:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
+``create_presence_override``, and ``delete_presence_override``.  A
+schedule delete changes presence state too (the child becomes
+always-present), so it must regenerate just like the others.  This hook
+is documented, not yet wired: no presence business layer exists yet, and
+the presence DAO (``dao_presence.py``) must stay free of business rules
+— never call :func:`regenerate_for_child` from inside the DAO layer.
+"""
+from __future__ import annotations
+
+import datetime
+
+from .const import DEFAULT_HORIZON_DAYS
+from .dao_instances import QuestInstancesDao, _resolve_today
+from .dao_rules import (
+    _validate_date,
+    load_materialization_input,
+    schedule_rule_from_storage,
+    schedule_rule_storage_from_record,
+)
+from .db import NestQuestDatabase
+from .presence import PresenceEngine, PresenceOverride, PresenceSchedule
+from .recurrence import ScheduleRule, occurs_on
+
+
+def _now_stamp() -> str:
+    """Return the batch's shared UTC second-precision generation stamp."""
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(
+        timespec="seconds"
+    )
+
+
+def _resolve_horizon_days(horizon_days: int | None) -> int:
+    """Validate a regeneration horizon and return the resolved day count.
+
+    ``None`` resolves to :data:`~.const.DEFAULT_HORIZON_DAYS`.  A bool
+    (SQLite would happily bind ``True``/``False`` onto an int), a non-int,
+    or a value below 1 raises ValueError naming the field — the validation
+    runs BEFORE any future-instance delete so a malformed horizon can never
+    delete rows it then fails to rebuild.  A negative horizon would
+    otherwise delete first and only then be rejected by
+    :func:`materialize`'s inverted-range check; ``0``/``False`` would
+    silently shrink the window to a single day.
+    """
+    if horizon_days is None:
+        return DEFAULT_HORIZON_DAYS
+    if (
+        isinstance(horizon_days, bool)
+        or not isinstance(horizon_days, int)
+        or horizon_days < 1
+    ):
+        raise ValueError(
+            f"horizon_days must be a positive integer, got {horizon_days!r}"
+        )
+    return horizon_days
+
+
+def _decode_rule(snapshot) -> ScheduleRule:
+    """Decode a snapshot's rule record back into a ScheduleRule.
+
+    The record carried by the snapshot is the one the definition
+    referenced at read time, so decoding it here (rather than re-reading
+    through ``ScheduleRulesDao``) preserves the coherence the snapshot
+    guarantees.
+    """
+    return schedule_rule_from_storage(
+        schedule_rule_storage_from_record(snapshot.rule)
+    )
+
+
+def _build_engine(
+    schedules_records,
+    overrides_records,
+) -> PresenceEngine:
+    """Convert raw presence records into an immutable PresenceEngine."""
+    schedules: dict[int, PresenceSchedule] = {}
+    for child_id, record in schedules_records.items():
+        schedules[child_id] = PresenceSchedule.decode(
+            child_id, record.anchor_date, record.pattern
+        )
+    overrides: dict[int, list[PresenceOverride]] = {}
+    for child_id, records in overrides_records.items():
+        overrides[child_id] = [
+            PresenceOverride(
+                record.child_id,
+                record.start_date,
+                record.end_date,
+                record.is_present,
+                record.note,
+            )
+            for record in records
+        ]
+    return PresenceEngine(schedules, overrides)
+
+
+async def materialize(
+    database: NestQuestDatabase,
+    start_date: str,
+    end_date: str,
+    *,
+    child_ids: list[int] | None = None,
+    today: datetime.date | None = None,
+) -> int:
+    """Generate quest instances for the closed range [start_date, end_date].
+
+    ``start_date`` and ``end_date`` must be strict ISO calendar dates
+    (YYYY-MM-DD) with ``end_date`` on or after ``start_date``; anything
+    else raises ValueError naming the offending field.  Returns the number
+    of instances upserted for the range (idempotent — a re-run refreshes
+    the same rows, never duplicates them).
+
+    ``child_ids`` optionally scopes the walk to exactly those children:
+    assignees outside the list are never written, so a caller that only
+    wants one child's instances rebuilt (e.g. :func:`regenerate_for_child`
+    after a presence change) cannot touch any unrelated child's rows.
+    When omitted (or None) the walk covers every assignee as before.
+
+    ``today`` optionally pins the resolved HA-local date the walk's
+    no-past guard compares against; it is threaded into every
+    :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` write.  When
+    omitted the host clock (``datetime.date.today``) is used, which is the
+    historical default.  A caller that computed the horizon in Home
+    Assistant's configured time zone MUST pass that same date here so a
+    time zone behind the host around midnight is not rejected as "past".
+
+    ``start_date`` is clamped up to the resolved "today" (the same
+    ``today`` anchor threaded into the no-past guard), so a caller that
+    passes a ``start_date`` already in the past never yields a
+    past-dated instance: the walk simply begins on today and skips every
+    earlier date.  A range entirely in the past therefore produces zero
+    instances rather than an error, and the DAO's no-past guard remains
+    the authoritative backstop under the lock.
+
+    All inputs are read in ONE locked transaction; each tuple's write then
+    goes through the atomic :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`,
+    which re-validates the tuple and its current ``due_time`` in the same
+    transaction as the INSERT, so a config change that arrives mid-batch
+    skips the affected tuples rather than aborting the batch or leaving a
+    partial result.
+    """
+    _validate_date(start_date, "start_date")
+    _validate_date(end_date, "end_date")
+    if end_date < start_date:
+        raise ValueError(
+            f"end_date must be on or after start_date, got "
+            f"{end_date!r} < {start_date!r}"
+        )
+
+    snapshots, schedules_records, overrides_records = await (
+        load_materialization_input(database, start_date, end_date)
+    )
+    engine = _build_engine(schedules_records, overrides_records)
+    child_filter = None if child_ids is None else set(child_ids)
+
+    definitions = [
+        (snapshot.definition.id, _decode_rule(snapshot),
+         snapshot.assignees, snapshot.windows)
+        for snapshot in snapshots
+    ]
+
+    generated_at = _now_stamp()
+    instances = QuestInstancesDao(database)
+
+    start = datetime.datetime.strptime(start_date, "%Y-%m-%d").date()
+    end = datetime.datetime.strptime(end_date, "%Y-%m-%d").date()
+
+    # Clamp a past start up to today (the HA-local anchor when the caller
+    # pinned one, else the host clock) so the walk can never emit a
+    # past-dated instance; the DAO's no-past guard remains the backstop.
+    # A range entirely in the past therefore yields zero instances.
+    today_date = _resolve_today(today)
+    start = max(start, today_date)
+
+    count = 0
+    cursor = start
+    while cursor <= end:
+        iso = cursor.isoformat()
+        for definition_id, rule, assignees, windows in definitions:
+            if not occurs_on(rule, cursor):
+                continue
+            for child in assignees:
+                if child_filter is not None and child.id not in child_filter:
+                    continue
+                if not engine.is_present(child.id, cursor):
+                    continue
+                for window in windows:
+                    written = await instances.upsert_if_valid(
+                        definition_id,
+                        child.id,
+                        iso,
+                        generated_at,
+                        window=window.window,
+                        due_time=window.due_time,
+                        today=today,
+                    )
+                    if written is not None:
+                        count += 1
+        cursor += datetime.timedelta(days=1)
+    return count
+
+
+async def regenerate_for_definition(
+    database: NestQuestDatabase,
+    definition_id: int,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> int:
+    """Regenerate a definition's future instances after a config change.
+
+    The Feature 06 edit/assignment/activation paths call this after a
+    successful write so future instances track the new state: the
+    definition's open instances at or after today are deleted (never a
+    completed instance, never the past) via
+    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted`,
+    then the materialization walk re-runs over the rolling horizon
+    ``[today, today + horizon_days]`` so the (changed) rule,
+    assignee set and windows re-materialize against today's state.
+
+    "today" is computed the same way the walk computes it —
+    :func:`~.dao_instances._today` — so the delete cutoff and the
+    re-materialization range share one anchor, and the walk's
+    ``upsert_if_valid`` no-past guard never rejects the regenerated
+    range.  ``today`` optionally pins a caller-resolved HA-local date
+    (threaded into both the delete cutoff and the re-materialization)
+    so a household time zone behind the host around midnight stays
+    consistent.  ``horizon_days`` sizes the re-materialization window;
+    when omitted it falls back to :data:`~.const.DEFAULT_HORIZON_DAYS`.
+    A bool, non-int, or sub-1 value raises ValueError BEFORE any delete.
+    Returns the number of instances the re-materialization
+    upserted across the whole snapshot (idempotent — other active
+    definitions' tuples refresh in place, never duplicate).
+    """
+    horizon = _resolve_horizon_days(horizon_days)
+    today_date = _resolve_today(today)
+    start_date = today_date.isoformat()
+    end_date = (
+        today_date + datetime.timedelta(days=horizon)
+    ).isoformat()
+
+    instances = QuestInstancesDao(database)
+    await instances.delete_future_uncompleted(
+        definition_id, start_date, today=today
+    )
+    return await materialize(database, start_date, end_date, today=today)
+
+
+# HOOK (Feature 09 presence services): ``regenerate_for_child`` is the
+# child-presence counterpart to ``regenerate_for_definition``.  The
+# presence business layer that lands in Feature 09 MUST call
+# ``regenerate_for_child`` after EVERY presence-state write, so future
+# instances track a child's changed presence: set_presence_pattern
+# (including clearing/setting an empty pattern), deleting/clearing the
+# presence schedule (PresenceSchedulesDao.delete),
+# create_presence_override, and delete_presence_override.  A schedule
+# delete changes presence state too (the child becomes always-present),
+# so it must regenerate just like the others.  It is deliberately NOT
+# wired into ``dao_presence.py``: the DAO layer stays pure storage (no
+# business rules), and no presence business layer exists yet to host the
+# call — see the module docstring note above.
+async def regenerate_for_child(
+    database: NestQuestDatabase,
+    child_id: int,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> int:
+    """Regenerate a child's future instances after a presence change.
+
+    The Feature 09 presence services call this after every
+    presence-state write — set_presence_pattern (including clearing or
+    setting an empty pattern), deleting/clearing the presence schedule
+    (:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
+    create_presence_override, and delete_presence_override — so a
+    child's future instances track its new presence: the child's open
+    instances at or after today are deleted across ALL its definitions
+    (never a completed instance, never the past) via
+    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`,
+    then the materialization walk re-runs over the rolling horizon
+    ``[today, today + horizon_days]`` scoped to that child only,
+    so the child's now-absent/present dates re-materialize against
+    today's presence WITHOUT touching any other child's rows.
+
+    ``child_id`` must be a plain int — bool and float are rejected
+    (SQLite binds a bool as 0/1 and a float would round, so a malformed
+    id must never mutate the wrong profile).
+
+    "today" is computed the same way the walk computes it —
+    :func:`~.dao_instances._today` — and the re-materialization range uses the
+    delete's returned effective cutoff (see
+    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`),
+    so the delete cutoff and the re-materialization window share ONE
+    execution-day anchor even when the call is queued across midnight.
+    ``today`` optionally pins a caller-resolved HA-local date, threaded
+    into the delete cutoff and the re-materialization for the same
+    host-vs-HA time-zone consistency.  ``horizon_days`` sizes the
+    re-materialization window; when omitted it falls back to
+    :data:`~.const.DEFAULT_HORIZON_DAYS`.  A bool, non-int, or sub-1 value
+    raises ValueError BEFORE any delete.  Returns the number of instances
+    the re-materialization upserted for the child across the whole
+    snapshot.
+    """
+    if isinstance(child_id, bool) or not isinstance(child_id, int):
+        raise ValueError(f"child_id must be an integer, got {child_id!r}")
+
+    horizon = _resolve_horizon_days(horizon_days)
+    today_date = _resolve_today(today)
+
+    instances = QuestInstancesDao(database)
+    # Use the delete's returned effective cutoff as the materialize anchor,
+    # NOT the independently-computed "today" above.  If the call is queued
+    # across midnight the delete clamps its cutoff to the execution-day;
+    # materializing from the stale "today" (now yesterday) would trip the
+    # walk's no-past guard and leave the child's future instances deleted
+    # but not rebuilt.  One anchor for both keeps them consistent.
+    _, effective_cutoff = await instances.delete_future_uncompleted_for_child(
+        child_id, today_date.isoformat(), today=today
+    )
+    start = datetime.date.fromisoformat(effective_cutoff)
+    end_date = (start + datetime.timedelta(days=horizon)).isoformat()
+    return await materialize(
+        database, start.isoformat(), end_date, child_ids=[child_id], today=today
+    )

custom_components/nestquest/core/presence.py

@@ -0,0 +1,477 @@
+"""The presence and custody model (Feature 05).
+
+PURE module: no Home Assistant imports, no database access, no
+timezone logic — it operates on plain calendar dates only (feature
+guardrail).  The later engine (cycle position, ``is_present``,
+overrides, previews) builds directly on this model.
+
+A :class:`PresenceSchedule` answers "on which weekdays of which cycle
+week is this child at this house?" for an N-week repeating custody
+pattern.  Two of the household's three children follow a two-week
+rotation; a child with NO schedule row is present every day (that
+default lives in the engine, not here).
+
+Pattern encoding: the model's canonical serialization is the SAME
+pipe-separated CSV the database stores (see schema.py's
+``presence_schedules.pattern``): segment ``i`` (week index ``i``) is a
+comma-separated list of present weekdays, 0 = Monday .. 6 = Sunday,
+e.g. ``'0,2,4|1,3'`` = Mon/Wed/Fri in week 0, Tue/Thu in week 1.  An
+empty segment means absent every day of that week.  Encoding sorts
+each segment's weekdays and uses the exact segment order, so
+``decode(encode(schedule))`` round-trips losslessly and two schedules
+with equal patterns produce equal strings.
+
+Anchor-date policy: ``anchor_date`` pins the cycle.  Cycle position is
+computed from anchor-date arithmetic ONLY — never ISO week numbers or
+week parity (D-004): 53-week years silently invert parity on January
+1st.  The arithmetic lives in the engine task; this module validates
+that the anchor is a strict calendar date.
+
+Validation policy: construction is total — every reject happens in
+``__init__`` so no invalid schedule can ever exist:
+- ``cycle_length_weeks`` must be an integer 1..4.  The 4 cap matches
+  the database CHECK (schema.py) and keeps anchor arithmetic and the
+  encoded pattern human-readable; revisit both together if a longer
+  cycle is ever needed.
+- ``pattern`` must cover week indices 0..cycle_length_weeks-1 exactly
+  (no gaps, no extra weeks) with sets of integers 0..6 (bools
+  rejected: True would silently mean Monday).
+- ``anchor_date`` must be a strict ISO YYYY-MM-DD calendar date (or a
+  ``datetime.date``).
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+from types import MappingProxyType
+
+#: The schema's documented cap for cycle_length_weeks (schema.py keeps
+#: the pattern human-readable and the anchor arithmetic small).
+MAX_CYCLE_LENGTH_WEEKS = 4
+
+_DATE_FORMAT = "%Y-%m-%d"
+
+
+def _parse_date(value: object, field_name: str) -> datetime.date:
+    """Accept a datetime.date or a strict YYYY-MM-DD string.
+
+    ``datetime.datetime`` is rejected explicitly: it SUBCLASSES
+    datetime.date, so a bare isinstance check would store a value with
+    a time component and every later calendar-date comparison (e.g.
+    ``PresenceOverride.covers``) would raise TypeError.
+    """
+    if isinstance(value, datetime.datetime):
+        raise ValueError(
+            f"{field_name} must be a plain calendar date, not a "
+            f"datetime with a time component: {value!r}"
+        )
+    if isinstance(value, datetime.date):
+        return value
+    if not isinstance(value, str):
+        raise ValueError(
+            f"{field_name} must be a datetime.date or an ISO date string, "
+            f"got {value!r}"
+        )
+    try:
+        parsed = datetime.datetime.strptime(value, _DATE_FORMAT).date()
+    except (TypeError, ValueError):
+        raise ValueError(
+            f"{field_name} must be an ISO date (YYYY-MM-DD), got {value!r}"
+        ) from None
+    if parsed.isoformat() != value:
+        raise ValueError(
+            f"{field_name} must be a strict YYYY-MM-DD date, got {value!r}"
+        )
+    return parsed
+
+
+def _validate_week_index(week: object, cycle_length_weeks: int) -> int:
+    """Reject non-int week indices (bools included) and out-of-cycle."""
+    if isinstance(week, bool) or not isinstance(week, int):
+        raise ValueError(
+            f"pattern week index must be an integer, got {week!r}"
+        )
+    if not 0 <= week < cycle_length_weeks:
+        raise ValueError(
+            f"pattern week index must be in 0..{cycle_length_weeks - 1}, "
+            f"got {week}"
+        )
+    return week
+
+
+def _validate_weekday_set(week: int, weekdays: object) -> frozenset[int]:
+    """Validate one week's present-weekday set."""
+    if isinstance(weekdays, (str, bytes)) or weekdays is None:
+        raise ValueError(
+            f"pattern[{week}] must be an iterable of weekday ints 0..6, "
+            f"got {weekdays!r}"
+        )
+    try:
+        members = list(weekdays)
+    except TypeError:
+        raise ValueError(
+            f"pattern[{week}] must be an iterable of weekday ints 0..6, "
+            f"got {weekdays!r}"
+        ) from None
+    for member in members:
+        if isinstance(member, bool) or not isinstance(member, int):
+            raise ValueError(
+                f"pattern[{week}] weekday must be an int 0..6, got {member!r}"
+            )
+        if not 0 <= member <= 6:
+            raise ValueError(
+                f"pattern[{week}] weekday must be in 0..6 (Monday=0), "
+                f"got {member}"
+            )
+    return frozenset(members)
+
+
+def _validate_cycle_length(value: object) -> int:
+    """Reject non-int and out-of-range cycle lengths (bools included)."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(
+            f"cycle_length_weeks must be an integer, got {value!r}"
+        )
+    if not 1 <= value <= MAX_CYCLE_LENGTH_WEEKS:
+        raise ValueError(
+            f"cycle_length_weeks must be between 1 and "
+            f"{MAX_CYCLE_LENGTH_WEEKS}, got {value}"
+        )
+    return value
+
+
+def _validate_child_id(value: object) -> int:
+    """Reject non-int child ids (bools would silently address child 1)."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"child_id must be an integer, got {value!r}")
+    return value
+
+
+@dataclass(frozen=True, init=False)
+class PresenceSchedule:
+    """One child's N-week repeating presence pattern.
+
+    ``pattern`` maps each week index of the cycle (``0`` .. ``n-1``)
+    to the set of present weekdays (ints, Monday=0).  A week with an
+    empty set means the child is absent every day of that week — which
+    is distinct from having no schedule at all (the engine treats a
+    missing schedule as present every day).
+    """
+
+    child_id: int
+    cycle_length_weeks: int
+    anchor_date: datetime.date
+    pattern: MappingProxyType  # week index -> frozenset of weekdays
+
+    def __init__(
+        self,
+        child_id: int,
+        cycle_length_weeks: int,
+        anchor_date: object,
+        pattern: dict[int, object],
+    ) -> None:
+        object.__setattr__(self, "child_id", _validate_child_id(child_id))
+        cycle = _validate_cycle_length(cycle_length_weeks)
+        object.__setattr__(self, "cycle_length_weeks", cycle)
+        object.__setattr__(
+            self, "anchor_date", _parse_date(anchor_date, "anchor_date")
+        )
+        if not isinstance(pattern, dict):
+            raise ValueError(
+                "pattern must map week index to a set of present "
+                f"weekdays, got {pattern!r}"
+            )
+        normalised: dict[int, frozenset[int]] = {}
+        for week, weekdays in pattern.items():
+            index = _validate_week_index(week, cycle)
+            normalised[index] = _validate_weekday_set(index, weekdays)
+        missing = [
+            week for week in range(cycle) if week not in normalised
+        ]
+        if missing:
+            raise ValueError(
+                f"pattern must cover week indices 0..{cycle - 1}; "
+                f"missing {missing}"
+            )
+        # Frozen must mean frozen: a bare dict would let callers inject
+        # unvalidated weekdays (or drop required weeks) AFTER
+        # construction, bypassing total validation.  The mapping
+        # proxy exposes the validated contents read-only; the
+        # per-week sets are already frozensets.
+        object.__setattr__(self, "pattern", MappingProxyType(normalised))
+
+    def encode(self) -> str:
+        """Serialize to the database's pipe-separated CSV shape.
+
+        Segments appear in week order; each segment is the week's
+        present weekdays as a sorted comma-separated list (an empty set
+        encodes as an empty segment).  Two schedules with equal
+        patterns encode identically.
+        """
+        segments = [
+            ",".join(str(day) for day in sorted(self.pattern[week]))
+            for week in range(self.cycle_length_weeks)
+        ]
+        return "|".join(segments)
+
+    @classmethod
+    def decode(
+        cls,
+        child_id: int,
+        anchor_date: object,
+        encoded: str,
+    ) -> "PresenceSchedule":
+        """Build a schedule from its encoded pattern.
+
+        The cycle length is derived from the segment count, mirroring
+        the database's segment-count CHECK.  Decoding is strict: wrong
+        shapes, non-numeric or out-of-range weekdays are rejected —
+        the database CHECKs make such rows unrepresentable, and this
+        is the same contract on the model side.  A segment count above
+        the documented cycle cap is rejected by the ordinary
+        construction validation.
+        """
+        if not isinstance(encoded, str):
+            raise ValueError(
+                f"encoded pattern must be a string, got {encoded!r}"
+            )
+        segments = encoded.split("|")
+        pattern: dict[int, set[int]] = {}
+        for week, segment in enumerate(segments):
+            weekdays: set[int] = set()
+            if segment:
+                for part in segment.split(","):
+                    if len(part) != 1 or part not in "0123456":
+                        raise ValueError(
+                            f"encoded segment {week} carries an invalid "
+                            f"weekday {part!r} (single digits 0-6 only)"
+                        )
+                    weekdays.add(int(part))
+            pattern[week] = weekdays
+        return cls(child_id, len(segments), anchor_date, pattern)
+
+
+@dataclass(frozen=True, init=False)
+class PresenceOverride:
+    """A date-specific present/absent flag beating any pattern.
+
+    Covers a single date (``end_date == start_date``) or an inclusive
+    range.  A concrete range is the storage shape
+    (``presence_overrides.end_date`` is NOT NULL), so the model
+    requires both bounds and validates start <= end.  Construction and
+    validation live here so the engine can trust every instance.
+    """
+
+    child_id: int
+    start_date: datetime.date
+    end_date: datetime.date
+    is_present: bool
+    note: str | None
+
+    def __init__(
+        self,
+        child_id: int,
+        start_date: object,
+        end_date: object,
+        is_present: bool,
+        note: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "child_id", _validate_child_id(child_id))
+        start = _parse_date(start_date, "start_date")
+        end = _parse_date(end_date, "end_date")
+        if end < start:
+            raise ValueError(
+                f"end_date must be on or after start_date, got "
+                f"{end.isoformat()} < {start.isoformat()}"
+            )
+        object.__setattr__(self, "start_date", start)
+        object.__setattr__(self, "end_date", end)
+        if not isinstance(is_present, bool):
+            raise ValueError(
+                f"is_present must be a real bool, got {is_present!r}"
+            )
+        object.__setattr__(self, "is_present", is_present)
+        if note is not None and not isinstance(note, str):
+            raise ValueError(f"note must be a string or None, got {note!r}")
+        object.__setattr__(self, "note", note)
+
+    def covers(self, date: datetime.date) -> bool:
+        """Return True when the override applies to ``date``."""
+        return self.start_date <= date <= self.end_date
+
+
+def cycle_week_index(
+    schedule: PresenceSchedule, target_date: object
+) -> int:
+    """Return the cycle week index ``target_date`` falls in.
+
+    Anchor-date arithmetic ONLY (D-004): ``((target_date -
+    anchor_date).days // 7) % cycle_length_weeks``.  Python's floor
+    division makes dates BEFORE the anchor behave correctly — they
+    walk the cycle backwards (day -1 is the last week of the cycle,
+    day -8 wraps one further) instead of inverting, which is exactly
+    what ISO week parity does wrong in 53-week years.  The modulo of
+    a negative in Python is non-negative, so the index is always a
+    valid week index.
+    """
+    target = _parse_date(target_date, "target_date")
+    days = (target - schedule.anchor_date).days
+    return (days // 7) % schedule.cycle_length_weeks
+
+
+#: Search cap for :meth:`PresenceEngine.next_present_dates`: two full
+#: years of daily checks.  A child absent every day (an all-absent
+#: pattern with a blocking override) would otherwise loop forever; the
+#: cap bounds the scan and surfaces the situation as an error instead.
+MAX_PREVIEW_SCAN_DAYS = 366 * 2
+
+
+class PresenceEngine:
+    """Answers "is this child at this house on this date?".
+
+    Pure and side-effect-free: built from an immutable snapshot of the
+    children's schedules (``child_id -> PresenceSchedule``), it never
+    touches the database — callers build a snapshot from the DAO layer
+    and pass it in.  A child with NO schedule entry is present every
+    day (the third household child's case); a child WITH a schedule is
+    present exactly when the date's weekday is in that schedule's
+    pattern for the date's cycle week index (anchor-date arithmetic —
+    :func:`cycle_week_index`, never ISO week parity).
+    """
+
+    def __init__(
+        self,
+        schedules: dict[int, PresenceSchedule],
+        overrides: dict[int, list[PresenceOverride]] | None = None,
+    ) -> None:
+        if not isinstance(schedules, dict):
+            raise ValueError(
+                f"schedules must map child_id to PresenceSchedule, got "
+                f"{schedules!r}"
+            )
+        for child_id, schedule in schedules.items():
+            # Validate the KEY as a model child id too: True and 1.0
+            # compare equal to 1, so {True: schedule(1)} would be
+            # accepted and then behave differently on lookup.
+            _validate_child_id(child_id)
+            if not isinstance(schedule, PresenceSchedule):
+                raise ValueError(
+                    f"schedules[{child_id!r}] must be a PresenceSchedule, "
+                    f"got {schedule!r}"
+                )
+            if schedule.child_id != child_id:
+                raise ValueError(
+                    f"schedules is keyed {child_id!r} but holds the "
+                    f"schedule of child {schedule.child_id}"
+                )
+        if overrides is None:
+            overrides = {}
+        if not isinstance(overrides, dict):
+            raise ValueError(
+                "overrides must map child_id to a list of "
+                f"PresenceOverride, got {overrides!r}"
+            )
+        for child_id, entries in overrides.items():
+            _validate_child_id(child_id)
+            if not isinstance(entries, list):
+                raise ValueError(
+                    f"overrides[{child_id!r}] must be a list of "
+                    f"PresenceOverride, got {entries!r}"
+                )
+            for entry in entries:
+                if not isinstance(entry, PresenceOverride):
+                    raise ValueError(
+                        f"overrides[{child_id!r}] entries must be "
+                        f"PresenceOverride, got {entry!r}"
+                    )
+                if entry.child_id != child_id:
+                    raise ValueError(
+                        f"overrides is keyed {child_id!r} but holds an "
+                        f"override of child {entry.child_id}"
+                    )
+        # Read-only snapshot: reassignment is refused and no mutator
+        # exists, so a built engine answers consistently for its
+        # lifetime.  The overrides lists are copied to immutable
+        # tuples — a shallow mapping copy alone would leave caller-
+        # owned lists reachable through _overrides, and mutating one
+        # later would change is_present results.
+        object.__setattr__(self, "_schedules", MappingProxyType(dict(schedules)))
+        object.__setattr__(
+            self,
+            "_overrides",
+            MappingProxyType(
+                {child_id: tuple(entries) for child_id, entries in overrides.items()}
+            ),
+        )
+
+    def is_present(self, child_id: object, date: object) -> bool:
+        """Return whether ``child_id`` is present on ``date``.
+
+        Overrides take precedence over the repeating pattern: when an
+        override covers the date, its flag IS the answer — including
+        for a child with no schedule at all.  The DAO layer guarantees
+        a child's overrides never overlap; if a snapshot still carries
+        two covering the same date, the one with the LATEST start date
+        wins (deterministic, and matches "the most specific swap wins").
+        """
+        if isinstance(child_id, bool) or not isinstance(child_id, int):
+            raise ValueError(f"child_id must be an integer, got {child_id!r}")
+        target = _parse_date(date, "date")
+        entries = self._overrides.get(child_id) or []
+        covering = [
+            entry for entry in entries if entry.covers(target)
+        ]
+        if covering:
+            winner = max(covering, key=lambda entry: entry.start_date)
+            return winner.is_present
+        schedule = self._schedules.get(child_id)
+        if schedule is None:
+            # No schedule at all: present every day (household default).
+            return True
+        week = cycle_week_index(schedule, target)
+        return target.weekday() in schedule.pattern[week]
+
+    def next_present_dates(
+        self,
+        child_id: object,
+        start_date: object,
+        count: int,
+    ) -> list[datetime.date]:
+        """Return the next ``count`` dates the child is present.
+
+        Walks forward from ``start_date`` (INCLUSIVE — a parent
+        previewing "starting Monday" expects Monday itself when the
+        child is present) checking :meth:`is_present` for every day,
+        so overrides and the pattern are honoured identically.  The
+        admin Schedule tab renders this preview so a parent can confirm
+        a custody pattern is right before saving it.
+
+        A child absent every scanned day raises ValueError after the
+        two-year search cap — an always-absent child would otherwise
+        loop forever.  ``count`` must be a positive integer.
+        """
+        _validate_child_id(child_id)
+        start = _parse_date(start_date, "start_date")
+        if isinstance(count, bool) or not isinstance(count, int):
+            raise ValueError(f"count must be an integer, got {count!r}")
+        if count < 1:
+            raise ValueError(f"count must be at least 1, got {count}")
+        found: list[datetime.date] = []
+        day = start
+        for _ in range(MAX_PREVIEW_SCAN_DAYS):
+            if self.is_present(child_id, day):
+                found.append(day)
+                if len(found) == count:
+                    return found
+            day += datetime.timedelta(days=1)
+        raise ValueError(
+            f"child {child_id} is not present on any of the "
+            f"{MAX_PREVIEW_SCAN_DAYS} days from {start.isoformat()}; "
+            f"{count} present day(s) cannot be previewed"
+        )
+
+    def __setattr__(self, name: object, value: object) -> None:
+        raise AttributeError(
+            "PresenceEngine is an immutable snapshot; build a new engine "
+            "instead of mutating this one"
+        )

custom_components/nestquest/core/quest_definitions.py

@@ -0,0 +1,603 @@
+"""Business layer for creating and editing quest definitions (Feature 06).
+
+Sits between the Feature 09 service gate and the typed
+:class:`~.dao_rules.QuestDefinitionsDao`: callers get validation and the
+all-or-nothing create/edit here, and never touch the DAO SQL directly.
+:func:`create_quest_definition` is the create path,
+:func:`edit_quest_definition` the edit path, :func:`assign_child` and
+:func:`unassign_child` the assignment paths, and
+:func:`set_quest_definition_active` the deactivate/reactivate path.
+There is no permission check here (that is Feature 09).
+
+Validation policy mirrors :mod:`.children`:
+
+- ``title`` is required and trimmed; empty or whitespace-only raises
+  ValueError.
+- ``rule`` must be an already-validated :class:`~.recurrence.ScheduleRule`
+  (its constructor is total — rule validation is NOT re-implemented
+  here).
+- ``assignee_child_ids`` must be a non-empty list (strictly a ``list``);
+  every id is a plain int (bools and floats rejected, since SQLite would
+  bind them onto a real child) and must reference an existing ACTIVE
+  child (the DAO enforces the active/exists check inside the same
+  transaction).  Duplicate ids are rejected here, before the composite
+  primary key could surface them as an :class:`sqlite3.IntegrityError`.
+- ``windows`` must be a non-empty list (strictly a ``list``); each entry
+  is a window name from :data:`~.const.QUEST_WINDOWS` — either a bare
+  name (no due time) or a ``(name, due_time)`` pair whose due time is a
+  strict 24-hour HH:MM string.  Duplicate window names are rejected
+  here, before the composite primary key could surface them as an
+  :class:`sqlite3.IntegrityError`.
+
+The rule, definition, assignees and windows are persisted in ONE
+transaction (the DAO's :meth:`~.dao_rules.QuestDefinitionsDao.create_with_rule_and_windows`),
+so a rejected or failed create persists nothing.  The definition-level
+``due_time`` column is superseded by per-window due times (D-008) and is
+never set here.  ``created_at`` is stamped UTC ISO-8601 at second
+precision, matching :mod:`.children`.
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+from .dao_children import ChildRecord, _connection_lock
+from .dao_rules import (
+    QuestDefinitionRecord,
+    QuestDefinitionSnapshot,
+    QuestDefinitionWindowRecord,
+    QuestDefinitionsDao,
+    ScheduleRuleStorage,
+    ScheduleRulesDao,
+    _UNSET,
+    _validate_date,
+    _validate_time,
+    _validate_window,
+    schedule_rule_from_storage,
+    schedule_rule_storage_from_record,
+    schedule_rule_to_storage,
+)
+from .db import NestQuestDatabase
+from .materialize import regenerate_for_definition
+from .recurrence import ScheduleRule, occurs_on
+
+
+@dataclass(frozen=True)
+class CreatedQuestDefinition:
+    """The persisted result of a create, edit or activation change.
+
+    ``definition`` is the stored row; ``rule`` is the schedule rule
+    decoded back through the storage mapping; ``assignees`` and
+    ``windows`` are the definition's linked child records and window
+    declarations, read through the DAO.
+    """
+
+    definition: QuestDefinitionRecord
+    rule: ScheduleRule
+    assignees: list[ChildRecord]
+    windows: list[QuestDefinitionWindowRecord]
+
+
+def _now_stamp() -> str:
+    """Return the module's strict UTC second-precision stamp."""
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(
+        timespec="seconds"
+    )
+
+
+def _validate_text(
+    value: object, field: str, *, required: bool = False
+) -> str | None:
+    """Validate a free-text field and return it trimmed.
+
+    ``None`` raises when ``required`` and otherwise returns None.  A
+    non-string value is rejected; an empty result is rejected for
+    required fields.
+    """
+    if value is None:
+        if required:
+            raise ValueError(f"{field} is required")
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a string, got {value!r}")
+    trimmed = value.strip()
+    if required and not trimmed:
+        raise ValueError(f"{field} is required")
+    return trimmed
+
+
+def _validate_assignee_ids(value: object) -> list[int]:
+    """Return the assignee ids as plain ints, or raise naming the field.
+
+    The argument must be a non-empty list — strictly a ``list``: tuples
+    and other sequences are rejected.  Each entry must be a real int
+    (bools and floats rejected) so SQLite cannot bind ``True`` onto
+    child 1 or a float onto a neighbouring profile.
+    """
+    if type(value) is not list:
+        raise ValueError(
+            f"assignee_child_ids must be a list, got {type(value).__name__}"
+        )
+    if not value:
+        raise ValueError("assignee_child_ids must not be empty")
+    ids: list[int] = []
+    for entry in value:
+        if isinstance(entry, bool) or not isinstance(entry, int):
+            raise ValueError(
+                "assignee_child_ids must contain integer child ids, "
+                f"got {entry!r}"
+            )
+        ids.append(entry)
+    if len(set(ids)) != len(ids):
+        raise ValueError(
+            "assignee_child_ids must not contain duplicate child ids"
+        )
+    return ids
+
+
+def _normalize_windows(
+    value: object,
+) -> list[tuple[str, str | None]]:
+    """Normalize the windows argument to ``(name, due_time)`` pairs.
+
+    The outer argument must be a non-empty list — strictly a ``list``:
+    tuples and other sequences are rejected, while each individual entry
+    may still be a ``(window, due_time)`` tuple.  A bare window name
+    (due time None) is also accepted.  The name must be a
+    :data:`~.const.QUEST_WINDOWS` spelling and a present due time must be
+    a strict 24-hour HH:MM, both validated up front so a malformed
+    window is rejected before any write.
+    """
+    if type(value) is not list:
+        raise ValueError(
+            f"windows must be a list, got {type(value).__name__}"
+        )
+    if not value:
+        raise ValueError("windows must not be empty")
+    normalized: list[tuple[str, str | None]] = []
+    seen: set[str] = set()
+    for index, entry in enumerate(value):
+        if isinstance(entry, str):
+            name: object = entry
+            due_time: object = None
+        elif isinstance(entry, (tuple, list)) and len(entry) == 2:
+            name, due_time = entry[0], entry[1]
+        else:
+            raise ValueError(
+                f"windows[{index}] must be a window name or a "
+                f"(name, due_time) pair, got {entry!r}"
+            )
+        _validate_window(name)
+        if due_time is not None:
+            _validate_time(due_time, "due_time")
+        if name in seen:
+            raise ValueError(
+                f"windows must not contain duplicate window {name!r}"
+            )
+        seen.add(name)
+        normalized.append((name, due_time))
+    return normalized
+
+
+def _validate_definition_id(value: object) -> int:
+    """Reject non-int definition ids (bools included) before any lookup.
+
+    SQLite binds Python bools as integers, so ``True`` would silently
+    address definition 1 and a float would round — malformed service
+    input must never mutate the wrong definition.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"definition_id must be an integer, got {value!r}")
+    return value
+
+
+def _validate_child_id(value: object) -> int:
+    """Reject non-int child ids (bools included) before any lookup.
+
+    SQLite binds Python bools as integers, so ``True`` would silently
+    address child 1 and a float would round — malformed service input
+    must never mutate the wrong profile.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"child_id must be an integer, got {value!r}")
+    return value
+
+
+async def create_quest_definition(
+    database: NestQuestDatabase,
+    title: str,
+    rule: ScheduleRule,
+    assignee_child_ids: list[int],
+    windows: list[str | tuple[str, str | None]],
+    *,
+    description: str | None = None,
+    icon: str | None = None,
+) -> CreatedQuestDefinition:
+    """Create a quest definition (rule + assignees + windows) atomically.
+
+    Validates the arguments up front, then persists the schedule rule,
+    the definition, its assignees and its windows in one transaction via
+    the DAO.  Returns the stored definition together with its decoded
+    rule, assignees and windows — all read back inside that same
+    transaction, so the returned bundle is a consistent creation
+    snapshot.  Raises ValueError on any rejected argument; a rejected or
+    failed create persists nothing.
+    """
+    name = _validate_text(title, "title", required=True)
+    assert name is not None
+    if not isinstance(rule, ScheduleRule):
+        raise ValueError(f"rule must be a ScheduleRule, got {rule!r}")
+    assignee_ids = _validate_assignee_ids(assignee_child_ids)
+    window_specs = _normalize_windows(windows)
+    description_value = _validate_text(description, "description")
+    icon_value = _validate_text(icon, "icon")
+
+    storage = schedule_rule_to_storage(rule)
+    dao = QuestDefinitionsDao(database)
+    try:
+        snapshot = await dao.create_with_rule_and_windows(
+            name,
+            storage,
+            _now_stamp(),
+            assignee_ids,
+            window_specs,
+            description=description_value,
+            icon=icon_value,
+        )
+    except ValueError as error:
+        # The DAO's assignee check names only the child; re-raise so the
+        # public contract names the field the caller actually passed.
+        message = str(error)
+        if message.startswith("child "):
+            raise ValueError(
+                f"assignee_child_ids: {message}"
+            ) from error
+        raise
+    decoded_rule = schedule_rule_from_storage(storage)
+    return CreatedQuestDefinition(
+        definition=snapshot.definition,
+        rule=decoded_rule,
+        assignees=snapshot.assignees,
+        windows=snapshot.windows,
+    )
+
+
+async def edit_quest_definition(
+    database: NestQuestDatabase,
+    definition_id: int,
+    *,
+    title: str | object = _UNSET,
+    description: str | None | object = _UNSET,
+    icon: str | None | object = _UNSET,
+    rule: ScheduleRule | object = _UNSET,
+    windows: list[str | tuple[str, str | None]] | object = _UNSET,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> CreatedQuestDefinition:
+    """Edit a quest definition's metadata, rule and windows atomically.
+
+    Arguments default to the sentinel ``_UNSET`` meaning "leave this
+    field alone".  A provided ``title`` is validated like create's
+    (required and trimmed); ``description`` and ``icon`` are optional
+    and may be cleared by passing ``None`` explicitly.  A provided
+    ``rule`` must be an already-validated :class:`~.recurrence.ScheduleRule`
+    and REPLACES the definition's schedule rule IN PLACE — the existing
+    ``schedule_rules`` row is updated, never orphaned or duplicated.  A
+    provided ``windows`` list REPLACES the whole window set (each entry
+    a ``const.QUEST_WINDOWS`` name, optionally with a strict HH:MM due
+    time), matching create's non-empty contract.  Assignment is NOT
+    settable here.  Raises ValueError when the definition does not
+    exist or any argument is rejected.
+
+    Returns the updated definition together with its decoded rule,
+    assignees and windows — all read back inside the DAO's transaction,
+    so the returned bundle is a consistent edit snapshot.  Edits change
+    future instances only; no ``quest_instances`` or
+    ``completion_events`` row is touched.
+
+    ``today`` optionally pins the caller-resolved HA-local date the
+    regeneration's no-past guard and horizon are anchored to (threaded
+    into :func:`~.materialize.regenerate_for_definition`); it is a plain
+    ``datetime.date`` with no HA import here — the Feature 09 service
+    supplies the hass-derived value.  When omitted, regeneration falls
+    back to the host clock, same as before.  ``horizon_days`` sizes the
+    regeneration's re-materialization window the same way (threaded into
+    :func:`~.materialize.regenerate_for_definition`); it defaults to
+    :data:`~.const.DEFAULT_HORIZON_DAYS` when omitted.
+    """
+    _validate_definition_id(definition_id)
+
+    title_value: str | None | object = _UNSET
+    if title is not _UNSET:
+        name = _validate_text(title, "title", required=True)
+        assert name is not None
+        title_value = name
+
+    description_value: str | None | object = _UNSET
+    if description is not _UNSET:
+        description_value = _validate_text(description, "description")
+
+    icon_value: str | None | object = _UNSET
+    if icon is not _UNSET:
+        icon_value = _validate_text(icon, "icon")
+
+    rule_storage: ScheduleRuleStorage | object = _UNSET
+    if rule is not _UNSET:
+        if not isinstance(rule, ScheduleRule):
+            raise ValueError(f"rule must be a ScheduleRule, got {rule!r}")
+        rule_storage = schedule_rule_to_storage(rule)
+
+    window_specs: list[tuple[str, str | None]] | object = _UNSET
+    if windows is not _UNSET:
+        window_specs = _normalize_windows(windows)
+
+    dao = QuestDefinitionsDao(database)
+    try:
+        snapshot = await dao.edit_definition(
+            definition_id,
+            title=title_value,
+            description=description_value,
+            icon=icon_value,
+            rule=rule_storage,
+            windows=window_specs,
+        )
+    except ValueError as error:
+        # The DAO's missing-definition error names only the id; re-raise
+        # so the public contract names the field the caller passed (matching
+        # assign/unassign/deactivate).
+        message = str(error)
+        if message.startswith("quest definition "):
+            raise ValueError(f"definition_id: {message}") from error
+        raise
+
+    decoded_rule = schedule_rule_from_storage(
+        schedule_rule_storage_from_record(snapshot.rule)
+    )
+
+    await regenerate_for_definition(
+        database, definition_id, today=today, horizon_days=horizon_days
+    )
+
+    return CreatedQuestDefinition(
+        definition=snapshot.definition,
+        rule=decoded_rule,
+        assignees=snapshot.assignees,
+        windows=snapshot.windows,
+    )
+
+
+async def assign_child(
+    database: NestQuestDatabase,
+    definition_id: int,
+    child_id: int,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> list[ChildRecord]:
+    """Assign ``child_id`` to the definition (idempotent).
+
+    Validates that both ids are plain ints (bools and floats rejected)
+    and that the child exists and is active — the DAO enforces the
+    active/exists check inside its transaction, and also confirms the
+    definition exists.  Assigning an already-assigned child is a no-op
+    (no duplicate row).  Returns the definition's assignees read back
+    inside the DAO's same transaction, a consistent post-assignment
+    roster (a concurrent assign/unassign cannot race it after the
+    write).  Raises ValueError on any rejected argument.  Only the
+    ``quest_definition_assignees`` link is written; existing instances
+    and completion history are never touched.
+
+    ``today`` optionally pins the caller-resolved HA-local date threaded
+    into the assignment's regeneration (see :func:`edit_quest_definition`).
+    ``horizon_days`` optionally sizes the regeneration's re-materialization
+    window the same way.
+    """
+    _validate_definition_id(definition_id)
+    _validate_child_id(child_id)
+    dao = QuestDefinitionsDao(database)
+    try:
+        assignees = await dao.add_assignee(definition_id, child_id)
+    except ValueError as error:
+        # The DAO names only the child/definition; re-raise so the
+        # public contract names the field the caller actually passed.
+        message = str(error)
+        if message.startswith("child "):
+            raise ValueError(f"child_id: {message}") from error
+        if message.startswith("quest definition "):
+            raise ValueError(f"definition_id: {message}") from error
+        raise
+    await regenerate_for_definition(
+        database, definition_id, today=today, horizon_days=horizon_days
+    )
+    return assignees
+
+
+async def unassign_child(
+    database: NestQuestDatabase,
+    definition_id: int,
+    child_id: int,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> bool:
+    """Unassign ``child_id`` from the definition; True when removed.
+
+    Validates both ids are plain ints (bools and floats rejected) and
+    that the definition exists, then removes the (definition, child)
+    link.  Returns True when a row was removed and False when the child
+    was not currently assigned.  Raises ValueError on a rejected
+    argument.  Only the ``quest_definition_assignees`` link is written;
+    existing instances and completion history are never touched.
+
+    ``today`` optionally pins the caller-resolved HA-local date threaded
+    into the unassignment's regeneration (see :func:`edit_quest_definition`).
+    ``horizon_days`` optionally sizes the regeneration's re-materialization
+    window the same way.
+    """
+    _validate_definition_id(definition_id)
+    _validate_child_id(child_id)
+    dao = QuestDefinitionsDao(database)
+    definition = await dao.get(definition_id)
+    if definition is None:
+        raise ValueError(
+            f"definition_id: quest definition {definition_id} does not exist"
+        )
+    removed = await dao.remove_assignee(definition_id, child_id)
+    await regenerate_for_definition(
+        database, definition_id, today=today, horizon_days=horizon_days
+    )
+    return removed
+
+
+async def set_quest_definition_active(
+    database: NestQuestDatabase,
+    definition_id: int,
+    is_active: bool,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> CreatedQuestDefinition:
+    """Deactivate or reactivate a definition; returns the updated view.
+
+    Flipping the flag is the only removal path (Feature 06 guardrail):
+    a deactivated definition stops future instance generation but its
+    row, schedule rule, assignees and windows all survive, and existing
+    instances plus completion history are never touched.  Reactivation
+    re-enables future generation; generating or removing instances is
+    Feature 07 and does not happen here.
+
+    ``definition_id`` must be a plain int (bools and floats rejected,
+    since SQLite would bind ``True`` onto definition 1) and
+    ``is_active`` must be a real bool — the DAO's ``int()`` would
+    otherwise silently coerce strings and numerics ("1", 0) into a
+    state the caller never asked for.  Raises ValueError naming the
+    offending field when the id is malformed, ``is_active`` is not a
+    bool, or the definition does not exist.
+
+    Atomicity: the existence check, the UPDATE and the readback of the
+    definition, its rule, assignees and windows all run inside the
+    connection-scoped lock, so the returned bundle is a consistent
+    snapshot that a concurrent mutation cannot race.
+
+    ``today`` optionally pins the caller-resolved HA-local date threaded
+    into the activation change's regeneration (see
+    :func:`edit_quest_definition`).  ``horizon_days`` optionally sizes the
+    regeneration's re-materialization window the same way.
+    """
+    _validate_definition_id(definition_id)
+    if not isinstance(is_active, bool):
+        raise ValueError(f"is_active must be a real bool, got {is_active!r}")
+    async with _connection_lock(database):
+        dao = QuestDefinitionsDao(database)
+        if await dao.get(definition_id) is None:
+            raise ValueError(
+                f"definition_id: quest definition {definition_id} "
+                "does not exist"
+            )
+        await dao.set_active(definition_id, is_active)
+        updated = await dao.get(definition_id)
+        assert updated is not None
+        rule_record = await ScheduleRulesDao(database).get(
+            updated.schedule_rule_id
+        )
+        assert rule_record is not None
+        assignees = await dao.list_assignees(definition_id)
+        windows = await dao.list_windows(definition_id)
+    rule = schedule_rule_from_storage(
+        schedule_rule_storage_from_record(rule_record)
+    )
+    await regenerate_for_definition(
+        database, definition_id, today=today, horizon_days=horizon_days
+    )
+    return CreatedQuestDefinition(
+        definition=updated,
+        rule=rule,
+        assignees=assignees,
+        windows=windows,
+    )
+
+
+def _bundle_snapshot(
+    snapshot: QuestDefinitionSnapshot,
+) -> CreatedQuestDefinition:
+    """Decode a DAO snapshot into the layer's rich view.
+
+    The rule record carried by the snapshot is the one the definition
+    referenced at read time, so decoding it here (rather than re-reading
+    through :class:`~.dao_rules.ScheduleRulesDao`) preserves the
+    coherence the DAO's locked snapshot guarantees: the rule, assignees
+    and windows all come from one atomic read, never three separate ones.
+    """
+    rule = schedule_rule_from_storage(
+        schedule_rule_storage_from_record(snapshot.rule)
+    )
+    return CreatedQuestDefinition(
+        definition=snapshot.definition,
+        rule=rule,
+        assignees=snapshot.assignees,
+        windows=snapshot.windows,
+    )
+
+
+async def list_active_definitions(
+    database: NestQuestDatabase,
+) -> list[CreatedQuestDefinition]:
+    """Return every ACTIVE definition with its decoded rule and links.
+
+    Ordered by rising definition id, matching the DAO's ``list_active``
+    order, so callers get a stable, repeatable sequence.  Each entry is
+    the same rich :class:`CreatedQuestDefinition` snapshot as the rest of
+    the layer: the stored row plus its decoded
+    :class:`~.recurrence.ScheduleRule`, assignees and windows.  The
+    definitions and their links are read by the DAO inside one locked
+    transaction, so each bundle is a coherent snapshot that a concurrent
+    edit cannot interleave.
+    """
+    dao = QuestDefinitionsDao(database)
+    snapshots = await dao.list_snapshots_active()
+    return [_bundle_snapshot(snapshot) for snapshot in snapshots]
+
+
+async def list_definitions_for_child(
+    database: NestQuestDatabase,
+    child_id: int,
+) -> list[CreatedQuestDefinition]:
+    """Return the definitions assigned to ``child_id`` (rich view).
+
+    ``child_id`` must be a plain int (bools and floats rejected, since
+    SQLite would bind ``True`` onto child 1).  Results are ordered by
+    rising definition id, matching ``list_active_definitions`` and
+    ``list_definitions_firing_on``.  Each entry is a
+    :class:`CreatedQuestDefinition` snapshot bundling the definition with
+    its decoded rule, assignees and windows, read atomically by the DAO.
+    """
+    _validate_child_id(child_id)
+    dao = QuestDefinitionsDao(database)
+    snapshots = await dao.list_snapshots_by_child(child_id)
+    bundles = [_bundle_snapshot(snapshot) for snapshot in snapshots]
+    return sorted(bundles, key=lambda bundle: bundle.definition.id)
+
+
+async def list_definitions_firing_on(
+    database: NestQuestDatabase,
+    date: str,
+) -> list[CreatedQuestDefinition]:
+    """Return the ACTIVE definitions whose rule fires on ``date``.
+
+    ``date`` must be a strict ISO calendar date (YYYY-MM-DD); a malformed
+    value raises ValueError naming the field.  Each active definition's
+    stored rule is decoded through the task-1 storage mapping and handed
+    to the recurrence engine's :func:`~.recurrence.occurs_on`; only the
+    definitions whose decoded rule fires on the date are returned, in
+    rising definition-id order, each as the same rich
+    :class:`CreatedQuestDefinition` snapshot as the rest of the layer.
+    The definitions and their rules are read inside one locked
+    transaction, so a bundle can never filter on one rule while
+    presenting another state's windows.
+    """
+    _validate_date(date, "date")
+    target = datetime.datetime.strptime(date, "%Y-%m-%d").date()
+    dao = QuestDefinitionsDao(database)
+    snapshots = await dao.list_snapshots_active()
+    bundles = [_bundle_snapshot(snapshot) for snapshot in snapshots]
+    return [bundle for bundle in bundles if occurs_on(bundle.rule, target)]

custom_components/nestquest/core/service_policy.py

@@ -0,0 +1,46 @@
+"""Explicit admin-only versus open service registry (Feature 09).
+
+One mapping, one file: every registered ``nestquest`` service name is
+either ``open`` or ``admin_only``.  The permission decorator (later
+Feature 09 tasks) reads this table; it does not take per-handler
+policy arguments.
+"""
+from __future__ import annotations
+
+from .const import (
+    DOMAIN_SERVICES,
+    SERVICE_COMPLETE_QUEST,
+    SERVICE_CREATE_PRESENCE_OVERRIDE,
+    SERVICE_CREATE_QUEST_DEFINITION,
+    SERVICE_DELETE_PRESENCE_OVERRIDE,
+    SERVICE_EXPORT_HISTORY_CSV,
+    SERVICE_MANAGE_CHILD,
+    SERVICE_REGENERATE,
+    SERVICE_SET_PRESENCE_PATTERN,
+    SERVICE_SET_QUEST_DEFINITION_ACTIVE,
+    SERVICE_UNCOMPLETE_QUEST,
+    SERVICE_UPDATE_QUEST_DEFINITION,
+)
+
+OPEN = "open"
+ADMIN_ONLY = "admin_only"
+
+SERVICE_POLICY: dict[str, str] = {
+    SERVICE_COMPLETE_QUEST: OPEN,
+    SERVICE_UNCOMPLETE_QUEST: ADMIN_ONLY,
+    SERVICE_CREATE_QUEST_DEFINITION: ADMIN_ONLY,
+    SERVICE_UPDATE_QUEST_DEFINITION: ADMIN_ONLY,
+    SERVICE_SET_QUEST_DEFINITION_ACTIVE: ADMIN_ONLY,
+    SERVICE_SET_PRESENCE_PATTERN: ADMIN_ONLY,
+    SERVICE_CREATE_PRESENCE_OVERRIDE: ADMIN_ONLY,
+    SERVICE_DELETE_PRESENCE_OVERRIDE: ADMIN_ONLY,
+    SERVICE_EXPORT_HISTORY_CSV: ADMIN_ONLY,
+    SERVICE_MANAGE_CHILD: ADMIN_ONLY,
+    SERVICE_REGENERATE: ADMIN_ONLY,
+}
+
+if frozenset(SERVICE_POLICY) != frozenset(DOMAIN_SERVICES):
+    raise RuntimeError(
+        "SERVICE_POLICY must name exactly the registered nestquest services, "
+        f"got {sorted(SERVICE_POLICY)} vs {list(DOMAIN_SERVICES)}"
+    )

custom_components/nestquest/core/settings.py

@@ -0,0 +1,379 @@
+"""Explicit, Home-Assistant-free settings object for NestQuest core.
+
+The integration reads its configuration off a Home Assistant config
+entry (``entry.options``); the core package must not.  This module
+bridges that split: it defines a frozen, validation-carrying
+:class:`NestQuestSettings` dataclass that the integration constructs
+from ``entry.options`` (via :meth:`NestQuestSettings.from_options`, or
+:meth:`NestQuestSettings.from_options_resilient` for the per-field
+fallback used at setup) and then passes into the core paths that
+previously read HA config themselves — the rolling horizon
+(``horizon_days``) and the daily rollover time (``day_rollover_time``),
+plus the Feature 11 notification settings (notify target, the three
+summary/reminder/report times, and the four independent enable toggles).
+
+Nothing in this module imports ``homeassistant`` or touches a config
+entry; ``from_options`` accepts any plain mapping keyed by the
+:data:`~.const.CONF_*` names.  The validation semantics match the
+options flow's: ``horizon_days`` must be a real integer >= 1 (bool
+rejected), and ``day_rollover_time`` plus the three notification times
+must be strict ``HH:MM`` 24-hour strings.  Construction therefore can
+never yield a settings object whose horizon could shrink or explode the
+materialized window, or whose rollover fires at an unparsable time.
+
+The strict resolvers (:func:`_resolve_horizon_days`, :func:`_validate_hhmm`,
+:func:`_resolve_bool`, :func:`_resolve_optional_str`) reject ``None``; the
+``None``-as-absent mapping lives ONLY in :meth:`from_options` /
+:meth:`from_options_resilient` (via :func:`_option_value`), so a hand-built
+:class:`NestQuestSettings` cannot smuggle a ``None`` past
+:meth:`__post_init__`.
+"""
+from __future__ import annotations
+
+import datetime
+from collections.abc import Callable
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from .const import (
+    CONF_AFTERNOON_REMINDER_ENABLED,
+    CONF_AFTERNOON_REMINDER_TIME,
+    CONF_CELEBRATION_ENABLED,
+    CONF_DAY_ROLLOVER_TIME,
+    CONF_END_OF_DAY_REPORT_ENABLED,
+    CONF_END_OF_DAY_REPORT_TIME,
+    CONF_HORIZON_DAYS,
+    CONF_MORNING_SUMMARY_ENABLED,
+    CONF_MORNING_SUMMARY_TIME,
+    CONF_NOTIFY_TARGET,
+    DEFAULT_AFTERNOON_REMINDER_TIME,
+    DEFAULT_AUTOMATION_ENABLED,
+    DEFAULT_DAY_ROLLOVER_TIME,
+    DEFAULT_END_OF_DAY_REPORT_TIME,
+    DEFAULT_HORIZON_DAYS,
+    DEFAULT_MORNING_SUMMARY_TIME,
+    LOGGER,
+    TIME_PATTERN,
+)
+
+
+def _option_value(
+    opts: Mapping[str, Any], key: str, default: Any
+) -> Any:
+    """Return ``opts[key]`` when present and non-None, else ``default``.
+
+    This is the SOLE place the ``None``-as-absent mapping lives: a stored
+    ``None`` is treated the same as an absent key — the historical
+    ``horizon_days`` path mapped a missing-or-None value to the default,
+    and this keeps that forgiving semantics uniform across every field.
+    The per-field resolvers (:func:`_resolve_horizon_days`,
+    :func:`_validate_hhmm`, :func:`_resolve_bool`,
+    :func:`_resolve_optional_str`) are STRICT — they reject ``None`` —
+    so a partially-populated ``entry.options`` dict (or one migrated
+    across versions) never raises just because a key carries ``None``,
+    and a hand-built :class:`NestQuestSettings` cannot smuggle a
+    ``None`` past :meth:`NestQuestSettings.__post_init__`.
+    """
+    if key not in opts:
+        return default
+    value = opts[key]
+    return default if value is None else value
+
+
+def _validate_hhmm(value: Any, *, field: str) -> str:
+    """Validate a strict ``HH:MM`` string and return it; raise naming ``field``.
+
+    Uses the shared :data:`~.const.TIME_PATTERN` (the same compiled
+    regex the options flow applies), so a stored option and a freshly
+    validated form submit parse the same way.  ``None`` (and any
+    non-string) is rejected; the ``None``-as-absent mapping lives ONLY
+    in :meth:`NestQuestSettings.from_options` (via :func:`_option_value`).
+    """
+    if not isinstance(value, str) or TIME_PATTERN.fullmatch(value) is None:
+        raise ValueError(
+            f"{field} must be a strict HH:MM string, got {value!r}"
+        )
+    return value
+
+
+def _resolve_horizon_days(value: Any) -> int:
+    """Validate a horizon value and return the resolved day count.
+
+    A bool is rejected (SQLite binds ``True``/``False`` onto an int), a
+    non-int is rejected, and a sub-1 value is rejected — so a malformed
+    option can never shrink or explode the materialized horizon.
+    ``None`` is rejected here too; the ``None``-as-absent mapping lives
+    ONLY in :meth:`NestQuestSettings.from_options` (via
+    :func:`_option_value`), so a hand-built
+    :class:`NestQuestSettings(horizon_days=None)` raises in
+    :meth:`NestQuestSettings.__post_init__` rather than silently
+    constructing an object whose :meth:`NestQuestSettings.horizon_window`
+    would later raise ``TypeError`` on ``timedelta(days=None)``.
+    """
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(
+            f"horizon_days must be a positive integer, got {value!r}"
+        )
+    return value
+
+
+def _resolve_bool(value: Any) -> bool:
+    """Return a real bool; a non-bool (including ``None``) is rejected.
+
+    voluptuous ``bool`` would coerce strings, so the options flow uses a
+    strict-bool validator and this mirrors it.  The ``None``-as-absent
+    mapping lives ONLY in :meth:`NestQuestSettings.from_options` (via
+    :func:`_option_value`).
+    """
+    if not isinstance(value, bool):
+        raise ValueError(f"expected a boolean, got {value!r}")
+    return value
+
+
+def _resolve_optional_str(value: Any) -> str:
+    """Return a stripped notify target string; a non-str is rejected.
+
+    A padded or whitespace-only value is STRIPPED to its trim — the
+    shipped default is the empty string, meaning "no notifications are
+    configured yet".  This is intentionally MORE LENIENT than the options
+    flow, which REJECTS a target that differs from its own trim (so a
+    padded value never persists): the integration tolerates a stored
+    padded value (e.g. one migrated from an older schema) by normalizing
+    it rather than crashing setup.  The ``None``-as-absent mapping lives
+    ONLY in :meth:`NestQuestSettings.from_options` (via
+    :func:`_option_value`).  :meth:`NestQuestSettings.__post_init__`
+    applies this SAME normalizer so a hand-built
+    ``NestQuestSettings(notify_target=' x ')`` is stripped to ``'x'``
+    exactly like the options-flow path (no padded value can slip through
+    direct construction either).
+    """
+    if not isinstance(value, str):
+        raise ValueError(f"notify_target must be a string, got {value!r}")
+    return value.strip()
+
+
+#: The single field table the two builders share.  Each row is
+#: ``(field_name, CONF_* key, default, validator)``.  ``from_options``
+#: applies every validator (raising on the first invalid value) while
+#: ``from_options_resilient`` wraps each in its own try/except so a single
+#: bad sibling falls back to its default alone.  Driving both builders
+#: from this table avoids three-way drift between ``__post_init__``'s
+#: inline checks and the two option builders' field lists: the only
+#: places that enumerate the fields are this table and
+#: ``__post_init__`` (which validates a hand-built instance without the
+#: None->default mapping, so it stays inline).
+_FIELDS: tuple[tuple[str, str, Any, Callable[[Any], Any]], ...] = (
+    ("horizon_days", CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS, _resolve_horizon_days),
+    (
+        "day_rollover_time",
+        CONF_DAY_ROLLOVER_TIME,
+        DEFAULT_DAY_ROLLOVER_TIME,
+        lambda v: _validate_hhmm(v, field="day_rollover_time"),
+    ),
+    ("notify_target", CONF_NOTIFY_TARGET, "", _resolve_optional_str),
+    (
+        "morning_summary_time",
+        CONF_MORNING_SUMMARY_TIME,
+        DEFAULT_MORNING_SUMMARY_TIME,
+        lambda v: _validate_hhmm(v, field="morning_summary_time"),
+    ),
+    (
+        "afternoon_reminder_time",
+        CONF_AFTERNOON_REMINDER_TIME,
+        DEFAULT_AFTERNOON_REMINDER_TIME,
+        lambda v: _validate_hhmm(v, field="afternoon_reminder_time"),
+    ),
+    (
+        "end_of_day_report_time",
+        CONF_END_OF_DAY_REPORT_TIME,
+        DEFAULT_END_OF_DAY_REPORT_TIME,
+        lambda v: _validate_hhmm(v, field="end_of_day_report_time"),
+    ),
+    (
+        "morning_summary_enabled",
+        CONF_MORNING_SUMMARY_ENABLED,
+        DEFAULT_AUTOMATION_ENABLED,
+        _resolve_bool,
+    ),
+    (
+        "afternoon_reminder_enabled",
+        CONF_AFTERNOON_REMINDER_ENABLED,
+        DEFAULT_AUTOMATION_ENABLED,
+        _resolve_bool,
+    ),
+    (
+        "end_of_day_report_enabled",
+        CONF_END_OF_DAY_REPORT_ENABLED,
+        DEFAULT_AUTOMATION_ENABLED,
+        _resolve_bool,
+    ),
+    (
+        "celebration_enabled",
+        CONF_CELEBRATION_ENABLED,
+        DEFAULT_AUTOMATION_ENABLED,
+        _resolve_bool,
+    ),
+)
+
+
+@dataclass(frozen=True)
+class NestQuestSettings:
+    """Explicit, HA-free configuration carried into core paths.
+
+    The integration builds this once from ``entry.options`` (via
+    :meth:`from_options`, or :meth:`from_options_resilient` for the
+    per-field fallback used at setup) and threads it into the horizon
+    materialization and the daily-rollover scheduling.  Core never
+    reads HA config itself; callers pass the resolved horizon and
+    rollover time in.
+
+    All fields are validated at construction; the dataclass is frozen so
+    a stale settings object cannot be mutated in place after the
+    integration hands it off.
+    """
+
+    horizon_days: int = DEFAULT_HORIZON_DAYS
+    day_rollover_time: str = DEFAULT_DAY_ROLLOVER_TIME
+    notify_target: str = ""
+    morning_summary_time: str = DEFAULT_MORNING_SUMMARY_TIME
+    afternoon_reminder_time: str = DEFAULT_AFTERNOON_REMINDER_TIME
+    end_of_day_report_time: str = DEFAULT_END_OF_DAY_REPORT_TIME
+    morning_summary_enabled: bool = DEFAULT_AUTOMATION_ENABLED
+    afternoon_reminder_enabled: bool = DEFAULT_AUTOMATION_ENABLED
+    end_of_day_report_enabled: bool = DEFAULT_AUTOMATION_ENABLED
+    celebration_enabled: bool = DEFAULT_AUTOMATION_ENABLED
+
+    def __post_init__(self) -> None:
+        # Validate STRICTLY at construction so a hand-built instance
+        # cannot carry an invalid value: the same rules from_options
+        # applies, but WITHOUT the None->default mapping (that lives
+        # only in from_options via _option_value).  A None horizon, time,
+        # or toggle raises here rather than later blowing up
+        # horizon_window or the rollover listener.
+        _resolve_horizon_days(self.horizon_days)
+        _validate_hhmm(self.day_rollover_time, field="day_rollover_time")
+        # ``notify_target`` is normalised the SAME way as from_options
+        # (via _resolve_optional_str): a non-str is rejected and a
+        # padded/whitespace-only value is STRIPPED to its trim.  This
+        # keeps a hand-built ``NestQuestSettings(notify_target=' x ')``
+        # behaving like the options flow (which strips on persist) so a
+        # padded value cannot slip through direct construction either.
+        # The dataclass is frozen, so the stripped value is written via
+        # object.__setattr__.
+        stripped_notify_target = _resolve_optional_str(self.notify_target)
+        object.__setattr__(self, "notify_target", stripped_notify_target)
+        _validate_hhmm(self.morning_summary_time, field="morning_summary_time")
+        _validate_hhmm(
+            self.afternoon_reminder_time, field="afternoon_reminder_time"
+        )
+        _validate_hhmm(
+            self.end_of_day_report_time, field="end_of_day_report_time"
+        )
+        for name in (
+            "morning_summary_enabled",
+            "afternoon_reminder_enabled",
+            "end_of_day_report_enabled",
+            "celebration_enabled",
+        ):
+            value = getattr(self, name)
+            if not isinstance(value, bool):
+                raise ValueError(
+                    f"{name} must be a boolean, got {value!r}"
+                )
+
+    @property
+    def day_rollover_hour_minute(self) -> tuple[int, int]:
+        """The (hour, minute) the daily rollover fires at."""
+        # The string is validated at construction, so a plain partition
+        # is safe and avoids re-running the regex on every access.
+        hour_str, _, minute_str = self.day_rollover_time.partition(":")
+        return int(hour_str), int(minute_str)
+
+    def horizon_window(
+        self, today: datetime.date
+    ) -> tuple[datetime.date, datetime.date]:
+        """Return the rolling horizon window ``[today, today + horizon_days]``.
+
+        ``today`` is REQUIRED (there is no host-clock default): the
+        integration passes the HA-local ``hass.config.time_zone`` date so
+        the horizon tracks the household's own day, and a silent
+        host-clock fallback would be a wrong-day footgun (a test or a
+        caller that forgets to pass ``today`` would otherwise materialize
+        against the machine's calendar, not the household's).  The
+        returned window is closed/inclusive — the same shape
+        :func:`~.materialize.materialize` walks.
+        """
+        end = today + datetime.timedelta(days=self.horizon_days)
+        return today, end
+
+    @classmethod
+    def from_options(
+        cls, options: Mapping[str, Any] | None = None
+    ) -> "NestQuestSettings":
+        """Build settings from a CONF_*-keyed mapping (e.g. ``entry.options``).
+
+        Reads the same keys the options flow persists, applying the
+        matching defaults when a key is absent OR ``None`` (via
+        :func:`_option_value`, the SOLE place the ``None``-as-absent
+        mapping lives) and validating STRICTLY: ``horizon_days`` is a
+        positive int (bool rejected), the four times are strict
+        ``HH:MM``, the four toggles are real booleans, and
+        ``notify_target`` is a string (stripped).  A malformed value
+        RAISES — the integration uses :meth:`from_options_resilient` at
+        setup to fall back per field instead of crashing.  A ``None``
+        mapping yields the all-defaults settings — useful for tests and
+        for a fresh install whose options dict is empty.
+
+        ``options`` is consumed read-only via
+        :class:`types.MappingProxyType`, so this method never mutates
+        the caller's mapping.
+        """
+        opts: Mapping[str, Any] = (
+            MappingProxyType({}) if options is None else MappingProxyType(options)
+        )
+        return cls(
+            **{
+                field: validator(_option_value(opts, key, default))
+                for field, key, default, validator in _FIELDS
+            }
+        )
+
+    @classmethod
+    def from_options_resilient(
+        cls, options: Mapping[str, Any] | None = None
+    ) -> "NestQuestSettings":
+        """Build settings, falling back PER FIELD on a malformed value.
+
+        Unlike :meth:`from_options` (which raises on the first invalid
+        field), this resolves EACH field in its own try/except: a
+        malformed value logs a :data:`~.const.LOGGER` warning naming the
+        field and falls back to that field's default.  The integration
+        uses this at setup so a single bad sibling option (e.g. a
+        migrated ``morning_summary_time`` of ``'25:00'``) cannot
+        silently reset the user's ``horizon_days`` or
+        ``day_rollover_time`` — the two fields core actually consumes.
+
+        An absent or ``None`` key maps to the default via
+        :func:`_option_value` WITHOUT a warning (that is the normal
+        missing-key path); only a present, non-``None``, invalid value
+        triggers a warning and a per-field fallback.
+        """
+        opts: Mapping[str, Any] = (
+            MappingProxyType({}) if options is None else MappingProxyType(options)
+        )
+        resolved: dict[str, Any] = {}
+        for field, key, default, validator in _FIELDS:
+            raw = _option_value(opts, key, default)
+            try:
+                resolved[field] = validator(raw)
+            except ValueError as err:
+                LOGGER.warning(
+                    "NestQuest option %s is invalid (%s); falling back "
+                    "to the default %r",
+                    field,
+                    err,
+                    default,
+                )
+                resolved[field] = default
+        return cls(**resolved)

custom_components/nestquest/core/snapshot.py

@@ -0,0 +1,306 @@
+"""Pure, Home-Assistant-free panel snapshot builder.
+
+The household snapshot the NestQuest panel renders — active children in
+sort order, each child's today-instances in the documented payload shape
+(missed instances OMITTED from the entity-facing attribute payload, but
+retained on the snapshot for the count rollups), per-child counts and
+presence, and the custody cycle day — used to be assembled inline inside
+:mod:`custom_components.nestquest.coordinator`'s
+``_async_update_data``.  That assembly is HA-coupled only because its
+host is a :class:`~homeassistant.helpers.update_coordinator.DataUpdateCoordinator`;
+the assembly itself touches no HA surface.
+
+This module holds the pure pieces — the snapshot dataclasses
+(:class:`QuestInstanceView`, :class:`ChildDaySnapshot`,
+:class:`NestQuestSnapshot`), the cycle-day helper (:func:`_cycle_day`),
+the panel payload shaper (:func:`instance_payload`), and the async
+:func:`build_snapshot` builder — so the HA coordinator and the API
+service's panel snapshot route share ONE implementation of both the
+snapshot assembly and the entity-facing attribute payload shape.
+Nothing here imports :mod:`homeassistant`; the builder takes the
+database, the settings object, and the HA-local ``now`` (a single
+clock read the caller already resolved, from which it derives
+``today``) and returns the snapshot, mirroring exactly what the
+coordinator used to do inline.
+
+``settings`` is accepted because the API route hands in the entry's
+:class:`~.settings.NestQuestSettings`; it is CURRENTLY UNUSED — the
+assembly reads nothing from it — and is retained so the builder's
+contract stays stable if a future panel feature derives scan caps or
+rollup behaviour from configuration.  No speculative read is wired in.
+"""
+from __future__ import annotations
+
+import datetime
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from .completion import derive_state
+from .dao_children import ChildrenDao
+from .dao_instances import CompletionEventsDao, QuestInstancesDao
+from .dao_presence import PresenceOverridesDao, PresenceSchedulesDao
+from .dao_rules import QuestDefinitionsDao
+from .db import NestQuestDatabase
+from .presence import (
+    MAX_PREVIEW_SCAN_DAYS,
+    PresenceEngine,
+    PresenceOverride,
+    PresenceSchedule,
+)
+from .settings import NestQuestSettings
+
+
+@dataclass(frozen=True)
+class QuestInstanceView:
+    """One instance plus everything the entities render from it."""
+
+    instance_id: int
+    definition_id: int
+    child_id: int
+    title: str
+    icon: str | None
+    window: str
+    due_date: str
+    due_time: str | None
+    state: str  # open | done | missed
+    overdue: bool
+    completed_at: str | None
+    was_on_time: bool | None
+
+
+@dataclass(frozen=True)
+class ChildDaySnapshot:
+    """One active child's day: instances, presence, and rollup counts."""
+
+    child_id: int
+    child_name: str
+    instances: tuple[QuestInstanceView, ...]
+    present: bool
+    due_today: int
+    completed_today: int
+    remaining_today: int
+    completion_pct: int
+    #: For a child away today: the ISO date of their next present day
+    #: (the panel's away plate renders ``Returns <weekday>, <Mon D>``
+    #: from it).  ``None`` when the child is present today or no
+    #: present day exists within the presence engine's scan cap.
+    next_present: str | None = None
+
+
+@dataclass(frozen=True)
+class NestQuestSnapshot:
+    """The coordinator's whole-entity data payload."""
+
+    today_iso: str
+    children: tuple[ChildDaySnapshot, ...]
+    cycle_day: int
+
+
+def _cycle_day(
+    schedules: dict[int, PresenceSchedule], children, today: datetime.date
+) -> int:
+    """Return today's 1-based day in the first scheduled child's cycle.
+
+    Anchor-date arithmetic ONLY (D-004): the day offset is computed from
+    the schedule's own anchor, never ISO week numbers or parity, so a
+    53-week year cannot silently invert the cycle.
+    """
+    for child in children:
+        schedule = schedules.get(child.id)
+        if schedule is None:
+            continue
+        days = (today - schedule.anchor_date).days
+        cycle_length = schedule.cycle_length_weeks * 7
+        return (days % cycle_length) + 1
+    return 0
+
+
+def instance_payload(
+    instances: Iterable[QuestInstanceView], *, include_missed: bool
+) -> list[dict[str, Any]]:
+    """Shape instance dicts per ENTITIES-AND-SERVICES.md §1.
+
+    The panel payload ``state`` is the documented ``open`` | ``completed``
+    spelling, so the builder's derived ``done`` maps to ``completed`` here;
+    ``open`` passes through.  ``missed`` instances are OMITTED from the
+    entity-facing attribute payload (decision 5) unless ``include_missed``
+    is set — the admin payload (D-009) keeps them with their ``missed``
+    state.  ``on_time`` passes the builder's ``was_on_time`` through
+    verbatim (``True`` / ``False`` for a completed instance, ``None`` for
+    an open one).  This is the SINGLE shared implementation both the HA
+    sensor layer and the API panel route read; it touches no Home
+    Assistant surface.
+    """
+    payload: list[dict[str, Any]] = []
+    for view in instances:
+        if view.state == "missed" and not include_missed:
+            continue
+        payload.append(
+            {
+                "id": view.instance_id,
+                "definition_id": view.definition_id,
+                "child_id": view.child_id,
+                "title": view.title,
+                "icon": view.icon,
+                "window": view.window,
+                "due_time": view.due_time,
+                "state": (
+                    "completed" if view.state == "done" else view.state
+                ),
+                "overdue": view.overdue,
+                "completed_at": view.completed_at,
+                "on_time": view.was_on_time,
+            }
+        )
+    return payload
+
+
+async def build_snapshot(
+    database: NestQuestDatabase,
+    settings: NestQuestSettings,
+    now: datetime.datetime,
+) -> NestQuestSnapshot:
+    """Build the household panel snapshot for ``today`` at the ``now`` instant.
+
+    Mirrors the assembly that lived in the coordinator's
+    ``_async_update_data``: active children in sort order, each child's
+    today-instances with derived state (open / done / missed via
+    :func:`~.completion.derive_state`) and the overdue flag, per-child
+    presence (resolved through :class:`~.presence.PresenceEngine`), the
+    per-child rollup counts, and the custody cycle day of the first
+    scheduled active child.  Missed instances are retained on the
+    snapshot (the rollup counts and the panel's missed plate need them)
+    but the entity-facing attribute payload omits them at the
+    :func:`instance_payload` layer — this builder produces the shared
+    shape both consumers read.
+
+    ``now`` is the HA-local timezone-aware datetime the caller already
+    resolved (a SINGLE clock read); the overdue check compares
+    ``now.time()`` against the instance's ``due_time`` for today's open
+    instances.  The builder performs NO internal clock read — it never
+    calls :func:`datetime.datetime.now` — so the instant is pinned in
+    tests.  ``today`` is derived INSIDE the builder as ``now.date()``,
+    so the calendar date that anchors the due-date and cycle-day
+    arithmetic is always the SAME clock read as the wall-clock time;
+    the two can never disagree.  ``settings`` is accepted but currently
+    unused (see the module docstring).
+    """
+    today = now.date()
+    today_iso = today.isoformat()
+
+    children = await ChildrenDao(database).list_active()
+
+    schedules: dict[int, PresenceSchedule] = {}
+    overrides: dict[int, list[PresenceOverride]] = {}
+    for child in children:
+        schedule = await PresenceSchedulesDao(database).get_by_child(
+            child.id
+        )
+        if schedule is not None:
+            schedules[child.id] = PresenceSchedule.decode(
+                child.id, schedule.anchor_date, schedule.pattern
+            )
+        window_end = today + datetime.timedelta(
+            days=MAX_PREVIEW_SCAN_DAYS
+        )
+        window_end_iso = window_end.isoformat()
+        ranged = await PresenceOverridesDao(
+            database
+        ).list_by_child_and_range(child.id, today_iso, window_end_iso)
+        if ranged:
+            # The engine validates MODEL objects, not DAO records;
+            # each record converts losslessly (the schema guarantees
+            # end >= start and a real is_present).
+            overrides[child.id] = [
+                PresenceOverride(
+                    record.child_id,
+                    record.start_date,
+                    record.end_date,
+                    record.is_present,
+                    record.note,
+                )
+                for record in ranged
+            ]
+    engine = PresenceEngine(schedules, overrides)
+
+    instances_dao = QuestInstancesDao(database)
+    events_dao = CompletionEventsDao(database)
+    definitions_dao = QuestDefinitionsDao(database)
+
+    snapshots: list[ChildDaySnapshot] = []
+    for child in children:
+        instances = await instances_dao.list_by_date_range(
+            child.id, today_iso, today_iso
+        )
+        views: list[QuestInstanceView] = []
+        for instance in instances:
+            latest = await events_dao.get_latest_for_instance(instance.id)
+            definition = await definitions_dao.get(instance.definition_id)
+            state = derive_state(instance, latest, today)
+            overdue = False
+            if state == "open" and instance.due_date == today_iso:
+                if instance.due_time is not None:
+                    due_moment = datetime.datetime.strptime(
+                        instance.due_time, "%H:%M"
+                    ).time()
+                    overdue = now.time() > due_moment
+            views.append(
+                QuestInstanceView(
+                    instance_id=instance.id,
+                    definition_id=instance.definition_id,
+                    child_id=instance.child_id,
+                    title=definition.title if definition else "Quest",
+                    icon=definition.icon if definition else None,
+                    window=instance.window,
+                    due_date=instance.due_date,
+                    due_time=instance.due_time,
+                    state=state,
+                    overdue=overdue,
+                    completed_at=(
+                        latest.occurred_at
+                        if latest is not None
+                        and latest.event_type == "completed"
+                        else None
+                    ),
+                    was_on_time=(
+                        latest.was_on_time
+                        if latest is not None
+                        and latest.event_type == "completed"
+                        else None
+                    ),
+                )
+            )
+        due = len(views)
+        completed = sum(1 for view in views if view.state == "done")
+        remaining = due - completed
+        child_present = engine.is_present(child.id, today)
+        next_present: str | None = None
+        if not child_present:
+            try:
+                next_present = engine.next_present_dates(
+                    child.id, today, 1
+                )[0].isoformat()
+            except ValueError:
+                next_present = None
+        snapshots.append(
+            ChildDaySnapshot(
+                child_id=child.id,
+                child_name=child.display_name,
+                instances=tuple(views),
+                present=child_present,
+                due_today=due,
+                completed_today=completed,
+                remaining_today=remaining,
+                completion_pct=(
+                    round(completed * 100 / due) if due else 100
+                ),
+                next_present=next_present,
+            )
+        )
+
+    return NestQuestSnapshot(
+        today_iso=today_iso,
+        children=tuple(snapshots),
+        cycle_day=_cycle_day(schedules, children, today),
+    )

custom_components/nestquest/events.py

@@ -1,73 +1,37 @@
-"""HA bus events fired by the NestQuest service paths (Feature 10).
+"""Re-export / HA wiring of :mod:`custom_components.nestquest.core.events` for the integration package.
 
-The four documented events (design/ENTITIES-AND-SERVICES.md §3, names
-in :mod:`~.const`): ``nestquest_quest_completed`` and
-``nestquest_quest_uncompleted`` fire from the completion service
-handlers on an actual transition (a no-op re-complete or re-uncomplete
-fires nothing), and ``nestquest_child_day_complete`` fires when a
-completion clears the child's whole day (quests were owed and none
-remain — a zero-quest day can never fire it, matching the all-done
-binary sensor's rule).  ``nestquest_quest_missed`` is the documented
-contract Feature 11's nightly sweep fires; nothing here fires it.
+The transition-event payload construction lives in
+:mod:`custom_components.nestquest.core.events` (extracted in
+task 510c1f78) and is HA-free: it builds and RETURNS the events.  This
+shim keeps the integration's old ``fire_quest_completed`` /
+``fire_quest_uncompleted`` API (the complete/uncomplete service
+handlers call them with ``hass``), reads the HA-local timezone from
+``hass.config.time_zone`` to derive ``today``, asks the core builder
+for the events, and fires each on ``hass.bus`` with the documented
+payloads.  The four blueprints keep working with identical payloads.
 
-Payload policy: one dict carrying ``child_id``, ``child_name``,
-``instance_id``, ``quest_title``, the instance's ``window``/
-``due_date``/``due_time`` so automation authors can filter without a
-database lookup, and ``occurred_at`` — the event's own strict UTC
-ISO-8601 timestamp.  Completion payloads additionally carry
-``was_on_time``.  No other personal data: names and titles are the
-household's own records, and nothing beyond them leaks.
+The completed event is fired BEFORE the day-complete rule evaluates:
+``fire_quest_completed`` asks
+:func:`build_quest_completed_event` for the completed event and fires
+it immediately, THEN reads the HA-local ``today``, asks
+:func:`build_child_day_complete_event` for the day-complete event, and
+fires it (if any) afterwards.  This restores the pre-extraction
+ordering — a failure in the day-complete DB reads or the ZoneInfo
+lookup cannot suppress the completed event.
 """
 from __future__ import annotations
 
 import datetime
 from zoneinfo import ZoneInfo
 
-from .completion import derive_state
-from .const import (
-    EVENT_CHILD_DAY_COMPLETE,
-    EVENT_QUEST_COMPLETED,
-    EVENT_QUEST_UNCOMPLETED,
+from .core.db import NestQuestDatabase
+from .core.events import (
+    build_child_day_complete_event,
+    build_quest_completed_event,
+    build_quest_uncompleted_events,
 )
-from .dao_children import ChildrenDao
-from .dao_instances import CompletionEventsDao, QuestInstancesDao
-from .dao_rules import QuestDefinitionsDao
-from .db import NestQuestDatabase
 
-#: Strict UTC ISO-8601 timestamp (the DAO layers' policy): one shape,
-#: explicit offset, second precision.
-_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
-
-
-def _now_stamp() -> str:
-    return datetime.datetime.now(datetime.timezone.utc).strftime(
-        _UTC_TIMESTAMP_FORMAT
-    )
-
-
-async def _instance_payload(
-    database: NestQuestDatabase, instance_id: int, now_stamp: str
-) -> dict:
-    """Build the shared event payload for one quest instance."""
-    instance = await QuestInstancesDao(database).get_by_id(instance_id)
-    if instance is None:
-        raise ValueError(
-            f"instance_id: quest instance {instance_id} does not exist"
-        )
-    child = await ChildrenDao(database).get(instance.child_id)
-    definition = await QuestDefinitionsDao(database).get(
-        instance.definition_id
-    )
-    return {
-        "child_id": instance.child_id,
-        "child_name": child.display_name if child else None,
-        "instance_id": instance.id,
-        "quest_title": definition.title if definition else None,
-        "window": instance.window,
-        "due_date": instance.due_date,
-        "due_time": instance.due_time,
-        "occurred_at": now_stamp,
-    }
+__all__ = ["fire_quest_completed", "fire_quest_uncompleted"]
 
 
 async def fire_quest_completed(
@@ -80,51 +44,36 @@ async def fire_quest_completed(
     """Fire ``nestquest_quest_completed`` and, when the completion
     cleared the child's whole day, ``nestquest_child_day_complete``.
 
-    Called by the complete_quest service handler AFTER an actual
-    completion transition, with the completion's ``was_on_time`` —
-    computed under the completion lock and carried on the result — so
-    the payload never re-reads mutable latest state a racing reversal
-    could have replaced.  A no-op re-complete never reaches here.
+    Thin HA wiring over the HA-free
+    :func:`custom_components.nestquest.core.events.build_quest_completed_event`
+    and
+    :func:`build_child_day_complete_event`: the completed event is
+    built and fired FIRST (so a failure in the day-complete DB reads
+    or the HA-local ``today`` lookup cannot suppress it), then the
+    HA-local ``today`` (the day-complete rule's input) is read from
+    ``hass.config.time_zone`` and the day-complete builder is asked
+    whether the child's whole day cleared.  Identical payloads and
+    day-complete rule to the pre-extraction implementation.
     """
-    now_stamp = _now_stamp()
-    payload = await _instance_payload(database, instance_id, now_stamp)
-    payload["was_on_time"] = was_on_time
-    hass.bus.async_fire(EVENT_QUEST_COMPLETED, payload)
-
-    # Day-complete: quests were owed today and none remain (the same
-    # rule as the all-done binary sensor; a zero-quest day never fires).
-    # Only a completion of TODAY'S instance evaluates it: completing a
-    # back-dated or future instance must not announce a cleared day.
-    today = datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
-    if payload["due_date"] != today.isoformat():
-        return
-    instances = await QuestInstancesDao(database).list_by_date_range(
-        payload["child_id"], today.isoformat(), today.isoformat()
+    completed = await build_quest_completed_event(
+        database,
+        instance_id,
+        was_on_time=was_on_time,
     )
-    events = CompletionEventsDao(database)
-    remaining = 0
-    for instance in instances:
-        latest_for_instance = await events.get_latest_for_instance(
-            instance.id
-        )
-        if derive_state(instance, latest_for_instance, today) != "done":
-            remaining += 1
-    if instances and remaining == 0:
-        hass.bus.async_fire(
-            EVENT_CHILD_DAY_COMPLETE,
-            {
-                "child_id": payload["child_id"],
-                "child_name": payload["child_name"],
-                "quests_due": len(instances),
-                "quests_completed": len(instances),
-                "occurred_at": now_stamp,
-            },
-        )
+    hass.bus.async_fire(*completed)
+
+    today = datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
+    day_complete = await build_child_day_complete_event(
+        database, completed[1], today=today
+    )
+    if day_complete is not None:
+        hass.bus.async_fire(*day_complete)
 
 
 async def fire_quest_uncompleted(
     hass, database: NestQuestDatabase, instance_id: int
 ) -> None:
     """Fire ``nestquest_quest_uncompleted`` for an actual reversal."""
-    payload = await _instance_payload(database, instance_id, _now_stamp())
-    hass.bus.async_fire(EVENT_QUEST_UNCOMPLETED, payload)
+    events = await build_quest_uncompleted_events(database, instance_id)
+    for event_type, payload in events:
+        hass.bus.async_fire(event_type, payload)

custom_components/nestquest/materialize.py

@@ -1,377 +1,11 @@
-"""The materialization walk (Feature 07 core).
+"""Re-export of :mod:`custom_components.nestquest.core.materialize` for the integration package.
 
-:func:`materialize` turns the schedule rules + custody presence of the
-active quest definitions into concrete ``quest_instances`` rows over a
-date range.  It is the pure walk over definitions x dates x assignees x
-windows; HA scheduling (day-rollover triggers) is a separate later
-task and lives elsewhere.
-
-The walk is deterministic and idempotent:
-
-- All inputs — the active definitions with their rules, assignees and
-  windows, AND the assignee children's presence schedules and scoped
-  overrides — are read inside ONE locked transaction (see
-  :func:`~.dao_rules.load_materialization_input`), so the walk sees a
-  single coherent snapshot rather than a definition state from one
-  instant and a presence state from another.
-- Presence is snapshotted into an immutable
-  :class:`~.presence.PresenceEngine` from that same coherent read.
-- For each date in the range, each definition whose decoded rule
-  :func:`~.recurrence.occurs_on` on that date, each assignee who is
-  ``is_present`` on that date and each declared window, one instance is
-  written through :class:`~.dao_instances.QuestInstancesDao.upsert_if_valid`
-  with a ``generated_at`` stamp shared by the whole batch (one coherent
-  time per run).
-
-A config change that lands AFTER the snapshot is read but BEFORE a
-tuple's write (an assignment removed, a definition or child deactivated,
-a window removed) makes that tuple SKIP rather than abort the batch:
-:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` re-validates
-every materialization precondition (active definition, active child,
-live assignment, declared window, and its CURRENT ``due_time``) inside
-the SAME transaction as the INSERT, so the check and the write cannot be
-split by a racing config edit.
-
-The upsert is idempotent on (definition_id, child_id, due_date,
-window), so re-running the materialization over the same range never
-duplicates a row; a tuple whose instance is already completed is SKIPPED
-(never rewritten, never raised) by
-:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`.
-
-Regeneration: a config or presence change must rebuild future instances
-so they track the new state.  :func:`regenerate_for_definition` covers
-definition edits / reassignment (Features 06/07); :func:`regenerate_for_child`
-covers a single child's presence change (Feature 09).  Both delete the
-affected open instances at or after today — never a completed instance,
-never the past — and re-run the walk over the rolling horizon
-``[today, today + horizon_days]`` (``horizon_days`` defaults to
-``DEFAULT_HORIZON_DAYS``).
-
-HOOK (Feature 09 presence services): the presence business layer that
-lands in Feature 09 MUST call :func:`regenerate_for_child` after EVERY
-presence-state write so a child's future instances track its presence:
-``set_presence_pattern`` (including clearing/setting an empty pattern),
-deleting/clearing the presence schedule
-(:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
-``create_presence_override``, and ``delete_presence_override``.  A
-schedule delete changes presence state too (the child becomes
-always-present), so it must regenerate just like the others.  This hook
-is documented, not yet wired: no presence business layer exists yet, and
-the presence DAO (``dao_presence.py``) must stay free of business rules
-— never call :func:`regenerate_for_child` from inside the DAO layer.
+The materialization walk lives in
+:mod:`custom_components.nestquest.core.materialize` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .materialize import ...`` references inside the integration keep
+working.
 """
 from __future__ import annotations
 
-import datetime
-
-from .const import DEFAULT_HORIZON_DAYS
-from .dao_instances import QuestInstancesDao, _resolve_today
-from .dao_rules import (
-    _validate_date,
-    load_materialization_input,
-    schedule_rule_from_storage,
-    schedule_rule_storage_from_record,
-)
-from .db import NestQuestDatabase
-from .presence import PresenceEngine, PresenceOverride, PresenceSchedule
-from .recurrence import ScheduleRule, occurs_on
-
-
-def _now_stamp() -> str:
-    """Return the batch's shared UTC second-precision generation stamp."""
-    return datetime.datetime.now(datetime.timezone.utc).isoformat(
-        timespec="seconds"
-    )
-
-
-def _resolve_horizon_days(horizon_days: int | None) -> int:
-    """Validate a regeneration horizon and return the resolved day count.
-
-    ``None`` resolves to :data:`~.const.DEFAULT_HORIZON_DAYS`.  A bool
-    (SQLite would happily bind ``True``/``False`` onto an int), a non-int,
-    or a value below 1 raises ValueError naming the field — the validation
-    runs BEFORE any future-instance delete so a malformed horizon can never
-    delete rows it then fails to rebuild.  A negative horizon would
-    otherwise delete first and only then be rejected by
-    :func:`materialize`'s inverted-range check; ``0``/``False`` would
-    silently shrink the window to a single day.
-    """
-    if horizon_days is None:
-        return DEFAULT_HORIZON_DAYS
-    if (
-        isinstance(horizon_days, bool)
-        or not isinstance(horizon_days, int)
-        or horizon_days < 1
-    ):
-        raise ValueError(
-            f"horizon_days must be a positive integer, got {horizon_days!r}"
-        )
-    return horizon_days
-
-
-def _decode_rule(snapshot) -> ScheduleRule:
-    """Decode a snapshot's rule record back into a ScheduleRule.
-
-    The record carried by the snapshot is the one the definition
-    referenced at read time, so decoding it here (rather than re-reading
-    through ``ScheduleRulesDao``) preserves the coherence the snapshot
-    guarantees.
-    """
-    return schedule_rule_from_storage(
-        schedule_rule_storage_from_record(snapshot.rule)
-    )
-
-
-def _build_engine(
-    schedules_records,
-    overrides_records,
-) -> PresenceEngine:
-    """Convert raw presence records into an immutable PresenceEngine."""
-    schedules: dict[int, PresenceSchedule] = {}
-    for child_id, record in schedules_records.items():
-        schedules[child_id] = PresenceSchedule.decode(
-            child_id, record.anchor_date, record.pattern
-        )
-    overrides: dict[int, list[PresenceOverride]] = {}
-    for child_id, records in overrides_records.items():
-        overrides[child_id] = [
-            PresenceOverride(
-                record.child_id,
-                record.start_date,
-                record.end_date,
-                record.is_present,
-                record.note,
-            )
-            for record in records
-        ]
-    return PresenceEngine(schedules, overrides)
-
-
-async def materialize(
-    database: NestQuestDatabase,
-    start_date: str,
-    end_date: str,
-    *,
-    child_ids: list[int] | None = None,
-    today: datetime.date | None = None,
-) -> int:
-    """Generate quest instances for the closed range [start_date, end_date].
-
-    ``start_date`` and ``end_date`` must be strict ISO calendar dates
-    (YYYY-MM-DD) with ``end_date`` on or after ``start_date``; anything
-    else raises ValueError naming the offending field.  Returns the number
-    of instances upserted for the range (idempotent — a re-run refreshes
-    the same rows, never duplicates them).
-
-    ``child_ids`` optionally scopes the walk to exactly those children:
-    assignees outside the list are never written, so a caller that only
-    wants one child's instances rebuilt (e.g. :func:`regenerate_for_child`
-    after a presence change) cannot touch any unrelated child's rows.
-    When omitted (or None) the walk covers every assignee as before.
-
-    ``today`` optionally pins the resolved HA-local date the walk's
-    no-past guard compares against; it is threaded into every
-    :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` write.  When
-    omitted the host clock (``datetime.date.today``) is used, which is the
-    historical default.  A caller that computed the horizon in Home
-    Assistant's configured time zone MUST pass that same date here so a
-    time zone behind the host around midnight is not rejected as "past".
-
-    ``start_date`` is clamped up to the resolved "today" (the same
-    ``today`` anchor threaded into the no-past guard), so a caller that
-    passes a ``start_date`` already in the past never yields a
-    past-dated instance: the walk simply begins on today and skips every
-    earlier date.  A range entirely in the past therefore produces zero
-    instances rather than an error, and the DAO's no-past guard remains
-    the authoritative backstop under the lock.
-
-    All inputs are read in ONE locked transaction; each tuple's write then
-    goes through the atomic :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`,
-    which re-validates the tuple and its current ``due_time`` in the same
-    transaction as the INSERT, so a config change that arrives mid-batch
-    skips the affected tuples rather than aborting the batch or leaving a
-    partial result.
-    """
-    _validate_date(start_date, "start_date")
-    _validate_date(end_date, "end_date")
-    if end_date < start_date:
-        raise ValueError(
-            f"end_date must be on or after start_date, got "
-            f"{end_date!r} < {start_date!r}"
-        )
-
-    snapshots, schedules_records, overrides_records = await (
-        load_materialization_input(database, start_date, end_date)
-    )
-    engine = _build_engine(schedules_records, overrides_records)
-    child_filter = None if child_ids is None else set(child_ids)
-
-    definitions = [
-        (snapshot.definition.id, _decode_rule(snapshot),
-         snapshot.assignees, snapshot.windows)
-        for snapshot in snapshots
-    ]
-
-    generated_at = _now_stamp()
-    instances = QuestInstancesDao(database)
-
-    start = datetime.datetime.strptime(start_date, "%Y-%m-%d").date()
-    end = datetime.datetime.strptime(end_date, "%Y-%m-%d").date()
-
-    # Clamp a past start up to today (the HA-local anchor when the caller
-    # pinned one, else the host clock) so the walk can never emit a
-    # past-dated instance; the DAO's no-past guard remains the backstop.
-    # A range entirely in the past therefore yields zero instances.
-    today_date = _resolve_today(today)
-    start = max(start, today_date)
-
-    count = 0
-    cursor = start
-    while cursor <= end:
-        iso = cursor.isoformat()
-        for definition_id, rule, assignees, windows in definitions:
-            if not occurs_on(rule, cursor):
-                continue
-            for child in assignees:
-                if child_filter is not None and child.id not in child_filter:
-                    continue
-                if not engine.is_present(child.id, cursor):
-                    continue
-                for window in windows:
-                    written = await instances.upsert_if_valid(
-                        definition_id,
-                        child.id,
-                        iso,
-                        generated_at,
-                        window=window.window,
-                        due_time=window.due_time,
-                        today=today,
-                    )
-                    if written is not None:
-                        count += 1
-        cursor += datetime.timedelta(days=1)
-    return count
-
-
-async def regenerate_for_definition(
-    database: NestQuestDatabase,
-    definition_id: int,
-    *,
-    today: datetime.date | None = None,
-    horizon_days: int | None = None,
-) -> int:
-    """Regenerate a definition's future instances after a config change.
-
-    The Feature 06 edit/assignment/activation paths call this after a
-    successful write so future instances track the new state: the
-    definition's open instances at or after today are deleted (never a
-    completed instance, never the past) via
-    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted`,
-    then the materialization walk re-runs over the rolling horizon
-    ``[today, today + horizon_days]`` so the (changed) rule,
-    assignee set and windows re-materialize against today's state.
-
-    "today" is computed the same way the walk computes it —
-    :func:`~.dao_instances._today` — so the delete cutoff and the
-    re-materialization range share one anchor, and the walk's
-    ``upsert_if_valid`` no-past guard never rejects the regenerated
-    range.  ``today`` optionally pins a caller-resolved HA-local date
-    (threaded into both the delete cutoff and the re-materialization)
-    so a household time zone behind the host around midnight stays
-    consistent.  ``horizon_days`` sizes the re-materialization window;
-    when omitted it falls back to :data:`~.const.DEFAULT_HORIZON_DAYS`.
-    A bool, non-int, or sub-1 value raises ValueError BEFORE any delete.
-    Returns the number of instances the re-materialization
-    upserted across the whole snapshot (idempotent — other active
-    definitions' tuples refresh in place, never duplicate).
-    """
-    horizon = _resolve_horizon_days(horizon_days)
-    today_date = _resolve_today(today)
-    start_date = today_date.isoformat()
-    end_date = (
-        today_date + datetime.timedelta(days=horizon)
-    ).isoformat()
-
-    instances = QuestInstancesDao(database)
-    await instances.delete_future_uncompleted(
-        definition_id, start_date, today=today
-    )
-    return await materialize(database, start_date, end_date, today=today)
-
-
-# HOOK (Feature 09 presence services): ``regenerate_for_child`` is the
-# child-presence counterpart to ``regenerate_for_definition``.  The
-# presence business layer that lands in Feature 09 MUST call
-# ``regenerate_for_child`` after EVERY presence-state write, so future
-# instances track a child's changed presence: set_presence_pattern
-# (including clearing/setting an empty pattern), deleting/clearing the
-# presence schedule (PresenceSchedulesDao.delete),
-# create_presence_override, and delete_presence_override.  A schedule
-# delete changes presence state too (the child becomes always-present),
-# so it must regenerate just like the others.  It is deliberately NOT
-# wired into ``dao_presence.py``: the DAO layer stays pure storage (no
-# business rules), and no presence business layer exists yet to host the
-# call — see the module docstring note above.
-async def regenerate_for_child(
-    database: NestQuestDatabase,
-    child_id: int,
-    *,
-    today: datetime.date | None = None,
-    horizon_days: int | None = None,
-) -> int:
-    """Regenerate a child's future instances after a presence change.
-
-    The Feature 09 presence services call this after every
-    presence-state write — set_presence_pattern (including clearing or
-    setting an empty pattern), deleting/clearing the presence schedule
-    (:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
-    create_presence_override, and delete_presence_override — so a
-    child's future instances track its new presence: the child's open
-    instances at or after today are deleted across ALL its definitions
-    (never a completed instance, never the past) via
-    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`,
-    then the materialization walk re-runs over the rolling horizon
-    ``[today, today + horizon_days]`` scoped to that child only,
-    so the child's now-absent/present dates re-materialize against
-    today's presence WITHOUT touching any other child's rows.
-
-    ``child_id`` must be a plain int — bool and float are rejected
-    (SQLite binds a bool as 0/1 and a float would round, so a malformed
-    id must never mutate the wrong profile).
-
-    "today" is computed the same way the walk computes it —
-    :func:`~.dao_instances._today` — and the re-materialization range uses the
-    delete's returned effective cutoff (see
-    :meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`),
-    so the delete cutoff and the re-materialization window share ONE
-    execution-day anchor even when the call is queued across midnight.
-    ``today`` optionally pins a caller-resolved HA-local date, threaded
-    into the delete cutoff and the re-materialization for the same
-    host-vs-HA time-zone consistency.  ``horizon_days`` sizes the
-    re-materialization window; when omitted it falls back to
-    :data:`~.const.DEFAULT_HORIZON_DAYS`.  A bool, non-int, or sub-1 value
-    raises ValueError BEFORE any delete.  Returns the number of instances
-    the re-materialization upserted for the child across the whole
-    snapshot.
-    """
-    if isinstance(child_id, bool) or not isinstance(child_id, int):
-        raise ValueError(f"child_id must be an integer, got {child_id!r}")
-
-    horizon = _resolve_horizon_days(horizon_days)
-    today_date = _resolve_today(today)
-
-    instances = QuestInstancesDao(database)
-    # Use the delete's returned effective cutoff as the materialize anchor,
-    # NOT the independently-computed "today" above.  If the call is queued
-    # across midnight the delete clamps its cutoff to the execution-day;
-    # materializing from the stale "today" (now yesterday) would trip the
-    # walk's no-past guard and leave the child's future instances deleted
-    # but not rebuilt.  One anchor for both keeps them consistent.
-    _, effective_cutoff = await instances.delete_future_uncompleted_for_child(
-        child_id, today_date.isoformat(), today=today
-    )
-    start = datetime.date.fromisoformat(effective_cutoff)
-    end_date = (start + datetime.timedelta(days=horizon)).isoformat()
-    return await materialize(
-        database, start.isoformat(), end_date, child_ids=[child_id], today=today
-    )
+from .core.materialize import *  # noqa: F401,F403

custom_components/nestquest/options_flow.py

@@ -1,7 +1,6 @@
 """Options flow for NestQuest post-setup settings."""
 from __future__ import annotations
 
-import re
 from typing import Any
 
 import voluptuous as vol
@@ -33,18 +32,17 @@ from .const import (
     DEFAULT_UPDATE_INTERVAL,
     DOMAIN,
     MIN_UPDATE_INTERVAL,
+    TIME_PATTERN,
 )
 from .admin_allowlist import list_admin_ids, set_admin_ids
 
 MIN_HORIZON_DAYS = 1
 MIN_PANEL_IDLE_TIMEOUT = 30
 
-_TIME_PATTERN = re.compile(r"(?:[01]\d|2[0-3]):[0-5]\d")
-
 
 def _parse_time(value: str) -> bool:
     """Return True when value is a valid 24-hour HH:MM string."""
-    return _TIME_PATTERN.fullmatch(value) is not None
+    return TIME_PATTERN.fullmatch(value) is not None
 
 
 def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:

custom_components/nestquest/presence.py

@@ -1,477 +1,11 @@
-"""The presence and custody model (Feature 05).
+"""Re-export of :mod:`custom_components.nestquest.core.presence` for the integration package.
 
-PURE module: no Home Assistant imports, no database access, no
-timezone logic — it operates on plain calendar dates only (feature
-guardrail).  The later engine (cycle position, ``is_present``,
-overrides, previews) builds directly on this model.
-
-A :class:`PresenceSchedule` answers "on which weekdays of which cycle
-week is this child at this house?" for an N-week repeating custody
-pattern.  Two of the household's three children follow a two-week
-rotation; a child with NO schedule row is present every day (that
-default lives in the engine, not here).
-
-Pattern encoding: the model's canonical serialization is the SAME
-pipe-separated CSV the database stores (see schema.py's
-``presence_schedules.pattern``): segment ``i`` (week index ``i``) is a
-comma-separated list of present weekdays, 0 = Monday .. 6 = Sunday,
-e.g. ``'0,2,4|1,3'`` = Mon/Wed/Fri in week 0, Tue/Thu in week 1.  An
-empty segment means absent every day of that week.  Encoding sorts
-each segment's weekdays and uses the exact segment order, so
-``decode(encode(schedule))`` round-trips losslessly and two schedules
-with equal patterns produce equal strings.
-
-Anchor-date policy: ``anchor_date`` pins the cycle.  Cycle position is
-computed from anchor-date arithmetic ONLY — never ISO week numbers or
-week parity (D-004): 53-week years silently invert parity on January
-1st.  The arithmetic lives in the engine task; this module validates
-that the anchor is a strict calendar date.
-
-Validation policy: construction is total — every reject happens in
-``__init__`` so no invalid schedule can ever exist:
-- ``cycle_length_weeks`` must be an integer 1..4.  The 4 cap matches
-  the database CHECK (schema.py) and keeps anchor arithmetic and the
-  encoded pattern human-readable; revisit both together if a longer
-  cycle is ever needed.
-- ``pattern`` must cover week indices 0..cycle_length_weeks-1 exactly
-  (no gaps, no extra weeks) with sets of integers 0..6 (bools
-  rejected: True would silently mean Monday).
-- ``anchor_date`` must be a strict ISO YYYY-MM-DD calendar date (or a
-  ``datetime.date``).
+The presence and custody model lives in
+:mod:`custom_components.nestquest.core.presence` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .presence import ...`` references inside the integration keep
+working.
 """
 from __future__ import annotations
 
-import datetime
-from dataclasses import dataclass
-from types import MappingProxyType
-
-#: The schema's documented cap for cycle_length_weeks (schema.py keeps
-#: the pattern human-readable and the anchor arithmetic small).
-MAX_CYCLE_LENGTH_WEEKS = 4
-
-_DATE_FORMAT = "%Y-%m-%d"
-
-
-def _parse_date(value: object, field_name: str) -> datetime.date:
-    """Accept a datetime.date or a strict YYYY-MM-DD string.
-
-    ``datetime.datetime`` is rejected explicitly: it SUBCLASSES
-    datetime.date, so a bare isinstance check would store a value with
-    a time component and every later calendar-date comparison (e.g.
-    ``PresenceOverride.covers``) would raise TypeError.
-    """
-    if isinstance(value, datetime.datetime):
-        raise ValueError(
-            f"{field_name} must be a plain calendar date, not a "
-            f"datetime with a time component: {value!r}"
-        )
-    if isinstance(value, datetime.date):
-        return value
-    if not isinstance(value, str):
-        raise ValueError(
-            f"{field_name} must be a datetime.date or an ISO date string, "
-            f"got {value!r}"
-        )
-    try:
-        parsed = datetime.datetime.strptime(value, _DATE_FORMAT).date()
-    except (TypeError, ValueError):
-        raise ValueError(
-            f"{field_name} must be an ISO date (YYYY-MM-DD), got {value!r}"
-        ) from None
-    if parsed.isoformat() != value:
-        raise ValueError(
-            f"{field_name} must be a strict YYYY-MM-DD date, got {value!r}"
-        )
-    return parsed
-
-
-def _validate_week_index(week: object, cycle_length_weeks: int) -> int:
-    """Reject non-int week indices (bools included) and out-of-cycle."""
-    if isinstance(week, bool) or not isinstance(week, int):
-        raise ValueError(
-            f"pattern week index must be an integer, got {week!r}"
-        )
-    if not 0 <= week < cycle_length_weeks:
-        raise ValueError(
-            f"pattern week index must be in 0..{cycle_length_weeks - 1}, "
-            f"got {week}"
-        )
-    return week
-
-
-def _validate_weekday_set(week: int, weekdays: object) -> frozenset[int]:
-    """Validate one week's present-weekday set."""
-    if isinstance(weekdays, (str, bytes)) or weekdays is None:
-        raise ValueError(
-            f"pattern[{week}] must be an iterable of weekday ints 0..6, "
-            f"got {weekdays!r}"
-        )
-    try:
-        members = list(weekdays)
-    except TypeError:
-        raise ValueError(
-            f"pattern[{week}] must be an iterable of weekday ints 0..6, "
-            f"got {weekdays!r}"
-        ) from None
-    for member in members:
-        if isinstance(member, bool) or not isinstance(member, int):
-            raise ValueError(
-                f"pattern[{week}] weekday must be an int 0..6, got {member!r}"
-            )
-        if not 0 <= member <= 6:
-            raise ValueError(
-                f"pattern[{week}] weekday must be in 0..6 (Monday=0), "
-                f"got {member}"
-            )
-    return frozenset(members)
-
-
-def _validate_cycle_length(value: object) -> int:
-    """Reject non-int and out-of-range cycle lengths (bools included)."""
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(
-            f"cycle_length_weeks must be an integer, got {value!r}"
-        )
-    if not 1 <= value <= MAX_CYCLE_LENGTH_WEEKS:
-        raise ValueError(
-            f"cycle_length_weeks must be between 1 and "
-            f"{MAX_CYCLE_LENGTH_WEEKS}, got {value}"
-        )
-    return value
-
-
-def _validate_child_id(value: object) -> int:
-    """Reject non-int child ids (bools would silently address child 1)."""
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(f"child_id must be an integer, got {value!r}")
-    return value
-
-
-@dataclass(frozen=True, init=False)
-class PresenceSchedule:
-    """One child's N-week repeating presence pattern.
-
-    ``pattern`` maps each week index of the cycle (``0`` .. ``n-1``)
-    to the set of present weekdays (ints, Monday=0).  A week with an
-    empty set means the child is absent every day of that week — which
-    is distinct from having no schedule at all (the engine treats a
-    missing schedule as present every day).
-    """
-
-    child_id: int
-    cycle_length_weeks: int
-    anchor_date: datetime.date
-    pattern: MappingProxyType  # week index -> frozenset of weekdays
-
-    def __init__(
-        self,
-        child_id: int,
-        cycle_length_weeks: int,
-        anchor_date: object,
-        pattern: dict[int, object],
-    ) -> None:
-        object.__setattr__(self, "child_id", _validate_child_id(child_id))
-        cycle = _validate_cycle_length(cycle_length_weeks)
-        object.__setattr__(self, "cycle_length_weeks", cycle)
-        object.__setattr__(
-            self, "anchor_date", _parse_date(anchor_date, "anchor_date")
-        )
-        if not isinstance(pattern, dict):
-            raise ValueError(
-                "pattern must map week index to a set of present "
-                f"weekdays, got {pattern!r}"
-            )
-        normalised: dict[int, frozenset[int]] = {}
-        for week, weekdays in pattern.items():
-            index = _validate_week_index(week, cycle)
-            normalised[index] = _validate_weekday_set(index, weekdays)
-        missing = [
-            week for week in range(cycle) if week not in normalised
-        ]
-        if missing:
-            raise ValueError(
-                f"pattern must cover week indices 0..{cycle - 1}; "
-                f"missing {missing}"
-            )
-        # Frozen must mean frozen: a bare dict would let callers inject
-        # unvalidated weekdays (or drop required weeks) AFTER
-        # construction, bypassing total validation.  The mapping
-        # proxy exposes the validated contents read-only; the
-        # per-week sets are already frozensets.
-        object.__setattr__(self, "pattern", MappingProxyType(normalised))
-
-    def encode(self) -> str:
-        """Serialize to the database's pipe-separated CSV shape.
-
-        Segments appear in week order; each segment is the week's
-        present weekdays as a sorted comma-separated list (an empty set
-        encodes as an empty segment).  Two schedules with equal
-        patterns encode identically.
-        """
-        segments = [
-            ",".join(str(day) for day in sorted(self.pattern[week]))
-            for week in range(self.cycle_length_weeks)
-        ]
-        return "|".join(segments)
-
-    @classmethod
-    def decode(
-        cls,
-        child_id: int,
-        anchor_date: object,
-        encoded: str,
-    ) -> "PresenceSchedule":
-        """Build a schedule from its encoded pattern.
-
-        The cycle length is derived from the segment count, mirroring
-        the database's segment-count CHECK.  Decoding is strict: wrong
-        shapes, non-numeric or out-of-range weekdays are rejected —
-        the database CHECKs make such rows unrepresentable, and this
-        is the same contract on the model side.  A segment count above
-        the documented cycle cap is rejected by the ordinary
-        construction validation.
-        """
-        if not isinstance(encoded, str):
-            raise ValueError(
-                f"encoded pattern must be a string, got {encoded!r}"
-            )
-        segments = encoded.split("|")
-        pattern: dict[int, set[int]] = {}
-        for week, segment in enumerate(segments):
-            weekdays: set[int] = set()
-            if segment:
-                for part in segment.split(","):
-                    if len(part) != 1 or part not in "0123456":
-                        raise ValueError(
-                            f"encoded segment {week} carries an invalid "
-                            f"weekday {part!r} (single digits 0-6 only)"
-                        )
-                    weekdays.add(int(part))
-            pattern[week] = weekdays
-        return cls(child_id, len(segments), anchor_date, pattern)
-
-
-@dataclass(frozen=True, init=False)
-class PresenceOverride:
-    """A date-specific present/absent flag beating any pattern.
-
-    Covers a single date (``end_date == start_date``) or an inclusive
-    range.  A concrete range is the storage shape
-    (``presence_overrides.end_date`` is NOT NULL), so the model
-    requires both bounds and validates start <= end.  Construction and
-    validation live here so the engine can trust every instance.
-    """
-
-    child_id: int
-    start_date: datetime.date
-    end_date: datetime.date
-    is_present: bool
-    note: str | None
-
-    def __init__(
-        self,
-        child_id: int,
-        start_date: object,
-        end_date: object,
-        is_present: bool,
-        note: str | None = None,
-    ) -> None:
-        object.__setattr__(self, "child_id", _validate_child_id(child_id))
-        start = _parse_date(start_date, "start_date")
-        end = _parse_date(end_date, "end_date")
-        if end < start:
-            raise ValueError(
-                f"end_date must be on or after start_date, got "
-                f"{end.isoformat()} < {start.isoformat()}"
-            )
-        object.__setattr__(self, "start_date", start)
-        object.__setattr__(self, "end_date", end)
-        if not isinstance(is_present, bool):
-            raise ValueError(
-                f"is_present must be a real bool, got {is_present!r}"
-            )
-        object.__setattr__(self, "is_present", is_present)
-        if note is not None and not isinstance(note, str):
-            raise ValueError(f"note must be a string or None, got {note!r}")
-        object.__setattr__(self, "note", note)
-
-    def covers(self, date: datetime.date) -> bool:
-        """Return True when the override applies to ``date``."""
-        return self.start_date <= date <= self.end_date
-
-
-def cycle_week_index(
-    schedule: PresenceSchedule, target_date: object
-) -> int:
-    """Return the cycle week index ``target_date`` falls in.
-
-    Anchor-date arithmetic ONLY (D-004): ``((target_date -
-    anchor_date).days // 7) % cycle_length_weeks``.  Python's floor
-    division makes dates BEFORE the anchor behave correctly — they
-    walk the cycle backwards (day -1 is the last week of the cycle,
-    day -8 wraps one further) instead of inverting, which is exactly
-    what ISO week parity does wrong in 53-week years.  The modulo of
-    a negative in Python is non-negative, so the index is always a
-    valid week index.
-    """
-    target = _parse_date(target_date, "target_date")
-    days = (target - schedule.anchor_date).days
-    return (days // 7) % schedule.cycle_length_weeks
-
-
-#: Search cap for :meth:`PresenceEngine.next_present_dates`: two full
-#: years of daily checks.  A child absent every day (an all-absent
-#: pattern with a blocking override) would otherwise loop forever; the
-#: cap bounds the scan and surfaces the situation as an error instead.
-MAX_PREVIEW_SCAN_DAYS = 366 * 2
-
-
-class PresenceEngine:
-    """Answers "is this child at this house on this date?".
-
-    Pure and side-effect-free: built from an immutable snapshot of the
-    children's schedules (``child_id -> PresenceSchedule``), it never
-    touches the database — callers build a snapshot from the DAO layer
-    and pass it in.  A child with NO schedule entry is present every
-    day (the third household child's case); a child WITH a schedule is
-    present exactly when the date's weekday is in that schedule's
-    pattern for the date's cycle week index (anchor-date arithmetic —
-    :func:`cycle_week_index`, never ISO week parity).
-    """
-
-    def __init__(
-        self,
-        schedules: dict[int, PresenceSchedule],
-        overrides: dict[int, list[PresenceOverride]] | None = None,
-    ) -> None:
-        if not isinstance(schedules, dict):
-            raise ValueError(
-                f"schedules must map child_id to PresenceSchedule, got "
-                f"{schedules!r}"
-            )
-        for child_id, schedule in schedules.items():
-            # Validate the KEY as a model child id too: True and 1.0
-            # compare equal to 1, so {True: schedule(1)} would be
-            # accepted and then behave differently on lookup.
-            _validate_child_id(child_id)
-            if not isinstance(schedule, PresenceSchedule):
-                raise ValueError(
-                    f"schedules[{child_id!r}] must be a PresenceSchedule, "
-                    f"got {schedule!r}"
-                )
-            if schedule.child_id != child_id:
-                raise ValueError(
-                    f"schedules is keyed {child_id!r} but holds the "
-                    f"schedule of child {schedule.child_id}"
-                )
-        if overrides is None:
-            overrides = {}
-        if not isinstance(overrides, dict):
-            raise ValueError(
-                "overrides must map child_id to a list of "
-                f"PresenceOverride, got {overrides!r}"
-            )
-        for child_id, entries in overrides.items():
-            _validate_child_id(child_id)
-            if not isinstance(entries, list):
-                raise ValueError(
-                    f"overrides[{child_id!r}] must be a list of "
-                    f"PresenceOverride, got {entries!r}"
-                )
-            for entry in entries:
-                if not isinstance(entry, PresenceOverride):
-                    raise ValueError(
-                        f"overrides[{child_id!r}] entries must be "
-                        f"PresenceOverride, got {entry!r}"
-                    )
-                if entry.child_id != child_id:
-                    raise ValueError(
-                        f"overrides is keyed {child_id!r} but holds an "
-                        f"override of child {entry.child_id}"
-                    )
-        # Read-only snapshot: reassignment is refused and no mutator
-        # exists, so a built engine answers consistently for its
-        # lifetime.  The overrides lists are copied to immutable
-        # tuples — a shallow mapping copy alone would leave caller-
-        # owned lists reachable through _overrides, and mutating one
-        # later would change is_present results.
-        object.__setattr__(self, "_schedules", MappingProxyType(dict(schedules)))
-        object.__setattr__(
-            self,
-            "_overrides",
-            MappingProxyType(
-                {child_id: tuple(entries) for child_id, entries in overrides.items()}
-            ),
-        )
-
-    def is_present(self, child_id: object, date: object) -> bool:
-        """Return whether ``child_id`` is present on ``date``.
-
-        Overrides take precedence over the repeating pattern: when an
-        override covers the date, its flag IS the answer — including
-        for a child with no schedule at all.  The DAO layer guarantees
-        a child's overrides never overlap; if a snapshot still carries
-        two covering the same date, the one with the LATEST start date
-        wins (deterministic, and matches "the most specific swap wins").
-        """
-        if isinstance(child_id, bool) or not isinstance(child_id, int):
-            raise ValueError(f"child_id must be an integer, got {child_id!r}")
-        target = _parse_date(date, "date")
-        entries = self._overrides.get(child_id) or []
-        covering = [
-            entry for entry in entries if entry.covers(target)
-        ]
-        if covering:
-            winner = max(covering, key=lambda entry: entry.start_date)
-            return winner.is_present
-        schedule = self._schedules.get(child_id)
-        if schedule is None:
-            # No schedule at all: present every day (household default).
-            return True
-        week = cycle_week_index(schedule, target)
-        return target.weekday() in schedule.pattern[week]
-
-    def next_present_dates(
-        self,
-        child_id: object,
-        start_date: object,
-        count: int,
-    ) -> list[datetime.date]:
-        """Return the next ``count`` dates the child is present.
-
-        Walks forward from ``start_date`` (INCLUSIVE — a parent
-        previewing "starting Monday" expects Monday itself when the
-        child is present) checking :meth:`is_present` for every day,
-        so overrides and the pattern are honoured identically.  The
-        admin Schedule tab renders this preview so a parent can confirm
-        a custody pattern is right before saving it.
-
-        A child absent every scanned day raises ValueError after the
-        two-year search cap — an always-absent child would otherwise
-        loop forever.  ``count`` must be a positive integer.
-        """
-        _validate_child_id(child_id)
-        start = _parse_date(start_date, "start_date")
-        if isinstance(count, bool) or not isinstance(count, int):
-            raise ValueError(f"count must be an integer, got {count!r}")
-        if count < 1:
-            raise ValueError(f"count must be at least 1, got {count}")
-        found: list[datetime.date] = []
-        day = start
-        for _ in range(MAX_PREVIEW_SCAN_DAYS):
-            if self.is_present(child_id, day):
-                found.append(day)
-                if len(found) == count:
-                    return found
-            day += datetime.timedelta(days=1)
-        raise ValueError(
-            f"child {child_id} is not present on any of the "
-            f"{MAX_PREVIEW_SCAN_DAYS} days from {start.isoformat()}; "
-            f"{count} present day(s) cannot be previewed"
-        )
-
-    def __setattr__(self, name: object, value: object) -> None:
-        raise AttributeError(
-            "PresenceEngine is an immutable snapshot; build a new engine "
-            "instead of mutating this one"
-        )
+from .core.presence import *  # noqa: F401,F403

custom_components/nestquest/quest_definitions.py

@@ -1,603 +1,11 @@
-"""Business layer for creating and editing quest definitions (Feature 06).
+"""Re-export of :mod:`custom_components.nestquest.core.quest_definitions` for the integration package.
 
-Sits between the Feature 09 service gate and the typed
-:class:`~.dao_rules.QuestDefinitionsDao`: callers get validation and the
-all-or-nothing create/edit here, and never touch the DAO SQL directly.
-:func:`create_quest_definition` is the create path,
-:func:`edit_quest_definition` the edit path, :func:`assign_child` and
-:func:`unassign_child` the assignment paths, and
-:func:`set_quest_definition_active` the deactivate/reactivate path.
-There is no permission check here (that is Feature 09).
-
-Validation policy mirrors :mod:`.children`:
-
-- ``title`` is required and trimmed; empty or whitespace-only raises
-  ValueError.
-- ``rule`` must be an already-validated :class:`~.recurrence.ScheduleRule`
-  (its constructor is total — rule validation is NOT re-implemented
-  here).
-- ``assignee_child_ids`` must be a non-empty list (strictly a ``list``);
-  every id is a plain int (bools and floats rejected, since SQLite would
-  bind them onto a real child) and must reference an existing ACTIVE
-  child (the DAO enforces the active/exists check inside the same
-  transaction).  Duplicate ids are rejected here, before the composite
-  primary key could surface them as an :class:`sqlite3.IntegrityError`.
-- ``windows`` must be a non-empty list (strictly a ``list``); each entry
-  is a window name from :data:`~.const.QUEST_WINDOWS` — either a bare
-  name (no due time) or a ``(name, due_time)`` pair whose due time is a
-  strict 24-hour HH:MM string.  Duplicate window names are rejected
-  here, before the composite primary key could surface them as an
-  :class:`sqlite3.IntegrityError`.
-
-The rule, definition, assignees and windows are persisted in ONE
-transaction (the DAO's :meth:`~.dao_rules.QuestDefinitionsDao.create_with_rule_and_windows`),
-so a rejected or failed create persists nothing.  The definition-level
-``due_time`` column is superseded by per-window due times (D-008) and is
-never set here.  ``created_at`` is stamped UTC ISO-8601 at second
-precision, matching :mod:`.children`.
+The quest definitions business layer lives in
+:mod:`custom_components.nestquest.core.quest_definitions` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .quest_definitions import ...`` references inside the integration
+keep working.
 """
 from __future__ import annotations
 
-import datetime
-from dataclasses import dataclass
-
-from .dao_children import ChildRecord, _connection_lock
-from .dao_rules import (
-    QuestDefinitionRecord,
-    QuestDefinitionSnapshot,
-    QuestDefinitionWindowRecord,
-    QuestDefinitionsDao,
-    ScheduleRuleStorage,
-    ScheduleRulesDao,
-    _UNSET,
-    _validate_date,
-    _validate_time,
-    _validate_window,
-    schedule_rule_from_storage,
-    schedule_rule_storage_from_record,
-    schedule_rule_to_storage,
-)
-from .db import NestQuestDatabase
-from .materialize import regenerate_for_definition
-from .recurrence import ScheduleRule, occurs_on
-
-
-@dataclass(frozen=True)
-class CreatedQuestDefinition:
-    """The persisted result of a create, edit or activation change.
-
-    ``definition`` is the stored row; ``rule`` is the schedule rule
-    decoded back through the storage mapping; ``assignees`` and
-    ``windows`` are the definition's linked child records and window
-    declarations, read through the DAO.
-    """
-
-    definition: QuestDefinitionRecord
-    rule: ScheduleRule
-    assignees: list[ChildRecord]
-    windows: list[QuestDefinitionWindowRecord]
-
-
-def _now_stamp() -> str:
-    """Return the module's strict UTC second-precision stamp."""
-    return datetime.datetime.now(datetime.timezone.utc).isoformat(
-        timespec="seconds"
-    )
-
-
-def _validate_text(
-    value: object, field: str, *, required: bool = False
-) -> str | None:
-    """Validate a free-text field and return it trimmed.
-
-    ``None`` raises when ``required`` and otherwise returns None.  A
-    non-string value is rejected; an empty result is rejected for
-    required fields.
-    """
-    if value is None:
-        if required:
-            raise ValueError(f"{field} is required")
-        return None
-    if not isinstance(value, str):
-        raise ValueError(f"{field} must be a string, got {value!r}")
-    trimmed = value.strip()
-    if required and not trimmed:
-        raise ValueError(f"{field} is required")
-    return trimmed
-
-
-def _validate_assignee_ids(value: object) -> list[int]:
-    """Return the assignee ids as plain ints, or raise naming the field.
-
-    The argument must be a non-empty list — strictly a ``list``: tuples
-    and other sequences are rejected.  Each entry must be a real int
-    (bools and floats rejected) so SQLite cannot bind ``True`` onto
-    child 1 or a float onto a neighbouring profile.
-    """
-    if type(value) is not list:
-        raise ValueError(
-            f"assignee_child_ids must be a list, got {type(value).__name__}"
-        )
-    if not value:
-        raise ValueError("assignee_child_ids must not be empty")
-    ids: list[int] = []
-    for entry in value:
-        if isinstance(entry, bool) or not isinstance(entry, int):
-            raise ValueError(
-                "assignee_child_ids must contain integer child ids, "
-                f"got {entry!r}"
-            )
-        ids.append(entry)
-    if len(set(ids)) != len(ids):
-        raise ValueError(
-            "assignee_child_ids must not contain duplicate child ids"
-        )
-    return ids
-
-
-def _normalize_windows(
-    value: object,
-) -> list[tuple[str, str | None]]:
-    """Normalize the windows argument to ``(name, due_time)`` pairs.
-
-    The outer argument must be a non-empty list — strictly a ``list``:
-    tuples and other sequences are rejected, while each individual entry
-    may still be a ``(window, due_time)`` tuple.  A bare window name
-    (due time None) is also accepted.  The name must be a
-    :data:`~.const.QUEST_WINDOWS` spelling and a present due time must be
-    a strict 24-hour HH:MM, both validated up front so a malformed
-    window is rejected before any write.
-    """
-    if type(value) is not list:
-        raise ValueError(
-            f"windows must be a list, got {type(value).__name__}"
-        )
-    if not value:
-        raise ValueError("windows must not be empty")
-    normalized: list[tuple[str, str | None]] = []
-    seen: set[str] = set()
-    for index, entry in enumerate(value):
-        if isinstance(entry, str):
-            name: object = entry
-            due_time: object = None
-        elif isinstance(entry, (tuple, list)) and len(entry) == 2:
-            name, due_time = entry[0], entry[1]
-        else:
-            raise ValueError(
-                f"windows[{index}] must be a window name or a "
-                f"(name, due_time) pair, got {entry!r}"
-            )
-        _validate_window(name)
-        if due_time is not None:
-            _validate_time(due_time, "due_time")
-        if name in seen:
-            raise ValueError(
-                f"windows must not contain duplicate window {name!r}"
-            )
-        seen.add(name)
-        normalized.append((name, due_time))
-    return normalized
-
-
-def _validate_definition_id(value: object) -> int:
-    """Reject non-int definition ids (bools included) before any lookup.
-
-    SQLite binds Python bools as integers, so ``True`` would silently
-    address definition 1 and a float would round — malformed service
-    input must never mutate the wrong definition.
-    """
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(f"definition_id must be an integer, got {value!r}")
-    return value
-
-
-def _validate_child_id(value: object) -> int:
-    """Reject non-int child ids (bools included) before any lookup.
-
-    SQLite binds Python bools as integers, so ``True`` would silently
-    address child 1 and a float would round — malformed service input
-    must never mutate the wrong profile.
-    """
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise ValueError(f"child_id must be an integer, got {value!r}")
-    return value
-
-
-async def create_quest_definition(
-    database: NestQuestDatabase,
-    title: str,
-    rule: ScheduleRule,
-    assignee_child_ids: list[int],
-    windows: list[str | tuple[str, str | None]],
-    *,
-    description: str | None = None,
-    icon: str | None = None,
-) -> CreatedQuestDefinition:
-    """Create a quest definition (rule + assignees + windows) atomically.
-
-    Validates the arguments up front, then persists the schedule rule,
-    the definition, its assignees and its windows in one transaction via
-    the DAO.  Returns the stored definition together with its decoded
-    rule, assignees and windows — all read back inside that same
-    transaction, so the returned bundle is a consistent creation
-    snapshot.  Raises ValueError on any rejected argument; a rejected or
-    failed create persists nothing.
-    """
-    name = _validate_text(title, "title", required=True)
-    assert name is not None
-    if not isinstance(rule, ScheduleRule):
-        raise ValueError(f"rule must be a ScheduleRule, got {rule!r}")
-    assignee_ids = _validate_assignee_ids(assignee_child_ids)
-    window_specs = _normalize_windows(windows)
-    description_value = _validate_text(description, "description")
-    icon_value = _validate_text(icon, "icon")
-
-    storage = schedule_rule_to_storage(rule)
-    dao = QuestDefinitionsDao(database)
-    try:
-        snapshot = await dao.create_with_rule_and_windows(
-            name,
-            storage,
-            _now_stamp(),
-            assignee_ids,
-            window_specs,
-            description=description_value,
-            icon=icon_value,
-        )
-    except ValueError as error:
-        # The DAO's assignee check names only the child; re-raise so the
-        # public contract names the field the caller actually passed.
-        message = str(error)
-        if message.startswith("child "):
-            raise ValueError(
-                f"assignee_child_ids: {message}"
-            ) from error
-        raise
-    decoded_rule = schedule_rule_from_storage(storage)
-    return CreatedQuestDefinition(
-        definition=snapshot.definition,
-        rule=decoded_rule,
-        assignees=snapshot.assignees,
-        windows=snapshot.windows,
-    )
-
-
-async def edit_quest_definition(
-    database: NestQuestDatabase,
-    definition_id: int,
-    *,
-    title: str | object = _UNSET,
-    description: str | None | object = _UNSET,
-    icon: str | None | object = _UNSET,
-    rule: ScheduleRule | object = _UNSET,
-    windows: list[str | tuple[str, str | None]] | object = _UNSET,
-    today: datetime.date | None = None,
-    horizon_days: int | None = None,
-) -> CreatedQuestDefinition:
-    """Edit a quest definition's metadata, rule and windows atomically.
-
-    Arguments default to the sentinel ``_UNSET`` meaning "leave this
-    field alone".  A provided ``title`` is validated like create's
-    (required and trimmed); ``description`` and ``icon`` are optional
-    and may be cleared by passing ``None`` explicitly.  A provided
-    ``rule`` must be an already-validated :class:`~.recurrence.ScheduleRule`
-    and REPLACES the definition's schedule rule IN PLACE — the existing
-    ``schedule_rules`` row is updated, never orphaned or duplicated.  A
-    provided ``windows`` list REPLACES the whole window set (each entry
-    a ``const.QUEST_WINDOWS`` name, optionally with a strict HH:MM due
-    time), matching create's non-empty contract.  Assignment is NOT
-    settable here.  Raises ValueError when the definition does not
-    exist or any argument is rejected.
-
-    Returns the updated definition together with its decoded rule,
-    assignees and windows — all read back inside the DAO's transaction,
-    so the returned bundle is a consistent edit snapshot.  Edits change
-    future instances only; no ``quest_instances`` or
-    ``completion_events`` row is touched.
-
-    ``today`` optionally pins the caller-resolved HA-local date the
-    regeneration's no-past guard and horizon are anchored to (threaded
-    into :func:`~.materialize.regenerate_for_definition`); it is a plain
-    ``datetime.date`` with no HA import here — the Feature 09 service
-    supplies the hass-derived value.  When omitted, regeneration falls
-    back to the host clock, same as before.  ``horizon_days`` sizes the
-    regeneration's re-materialization window the same way (threaded into
-    :func:`~.materialize.regenerate_for_definition`); it defaults to
-    :data:`~.const.DEFAULT_HORIZON_DAYS` when omitted.
-    """
-    _validate_definition_id(definition_id)
-
-    title_value: str | None | object = _UNSET
-    if title is not _UNSET:
-        name = _validate_text(title, "title", required=True)
-        assert name is not None
-        title_value = name
-
-    description_value: str | None | object = _UNSET
-    if description is not _UNSET:
-        description_value = _validate_text(description, "description")
-
-    icon_value: str | None | object = _UNSET
-    if icon is not _UNSET:
-        icon_value = _validate_text(icon, "icon")
-
-    rule_storage: ScheduleRuleStorage | object = _UNSET
-    if rule is not _UNSET:
-        if not isinstance(rule, ScheduleRule):
-            raise ValueError(f"rule must be a ScheduleRule, got {rule!r}")
-        rule_storage = schedule_rule_to_storage(rule)
-
-    window_specs: list[tuple[str, str | None]] | object = _UNSET
-    if windows is not _UNSET:
-        window_specs = _normalize_windows(windows)
-
-    dao = QuestDefinitionsDao(database)
-    try:
-        snapshot = await dao.edit_definition(
-            definition_id,
-            title=title_value,
-            description=description_value,
-            icon=icon_value,
-            rule=rule_storage,
-            windows=window_specs,
-        )
-    except ValueError as error:
-        # The DAO's missing-definition error names only the id; re-raise
-        # so the public contract names the field the caller passed (matching
-        # assign/unassign/deactivate).
-        message = str(error)
-        if message.startswith("quest definition "):
-            raise ValueError(f"definition_id: {message}") from error
-        raise
-
-    decoded_rule = schedule_rule_from_storage(
-        schedule_rule_storage_from_record(snapshot.rule)
-    )
-
-    await regenerate_for_definition(
-        database, definition_id, today=today, horizon_days=horizon_days
-    )
-
-    return CreatedQuestDefinition(
-        definition=snapshot.definition,
-        rule=decoded_rule,
-        assignees=snapshot.assignees,
-        windows=snapshot.windows,
-    )
-
-
-async def assign_child(
-    database: NestQuestDatabase,
-    definition_id: int,
-    child_id: int,
-    *,
-    today: datetime.date | None = None,
-    horizon_days: int | None = None,
-) -> list[ChildRecord]:
-    """Assign ``child_id`` to the definition (idempotent).
-
-    Validates that both ids are plain ints (bools and floats rejected)
-    and that the child exists and is active — the DAO enforces the
-    active/exists check inside its transaction, and also confirms the
-    definition exists.  Assigning an already-assigned child is a no-op
-    (no duplicate row).  Returns the definition's assignees read back
-    inside the DAO's same transaction, a consistent post-assignment
-    roster (a concurrent assign/unassign cannot race it after the
-    write).  Raises ValueError on any rejected argument.  Only the
-    ``quest_definition_assignees`` link is written; existing instances
-    and completion history are never touched.
-
-    ``today`` optionally pins the caller-resolved HA-local date threaded
-    into the assignment's regeneration (see :func:`edit_quest_definition`).
-    ``horizon_days`` optionally sizes the regeneration's re-materialization
-    window the same way.
-    """
-    _validate_definition_id(definition_id)
-    _validate_child_id(child_id)
-    dao = QuestDefinitionsDao(database)
-    try:
-        assignees = await dao.add_assignee(definition_id, child_id)
-    except ValueError as error:
-        # The DAO names only the child/definition; re-raise so the
-        # public contract names the field the caller actually passed.
-        message = str(error)
-        if message.startswith("child "):
-            raise ValueError(f"child_id: {message}") from error
-        if message.startswith("quest definition "):
-            raise ValueError(f"definition_id: {message}") from error
-        raise
-    await regenerate_for_definition(
-        database, definition_id, today=today, horizon_days=horizon_days
-    )
-    return assignees
-
-
-async def unassign_child(
-    database: NestQuestDatabase,
-    definition_id: int,
-    child_id: int,
-    *,
-    today: datetime.date | None = None,
-    horizon_days: int | None = None,
-) -> bool:
-    """Unassign ``child_id`` from the definition; True when removed.
-
-    Validates both ids are plain ints (bools and floats rejected) and
-    that the definition exists, then removes the (definition, child)
-    link.  Returns True when a row was removed and False when the child
-    was not currently assigned.  Raises ValueError on a rejected
-    argument.  Only the ``quest_definition_assignees`` link is written;
-    existing instances and completion history are never touched.
-
-    ``today`` optionally pins the caller-resolved HA-local date threaded
-    into the unassignment's regeneration (see :func:`edit_quest_definition`).
-    ``horizon_days`` optionally sizes the regeneration's re-materialization
-    window the same way.
-    """
-    _validate_definition_id(definition_id)
-    _validate_child_id(child_id)
-    dao = QuestDefinitionsDao(database)
-    definition = await dao.get(definition_id)
-    if definition is None:
-        raise ValueError(
-            f"definition_id: quest definition {definition_id} does not exist"
-        )
-    removed = await dao.remove_assignee(definition_id, child_id)
-    await regenerate_for_definition(
-        database, definition_id, today=today, horizon_days=horizon_days
-    )
-    return removed
-
-
-async def set_quest_definition_active(
-    database: NestQuestDatabase,
-    definition_id: int,
-    is_active: bool,
-    *,
-    today: datetime.date | None = None,
-    horizon_days: int | None = None,
-) -> CreatedQuestDefinition:
-    """Deactivate or reactivate a definition; returns the updated view.
-
-    Flipping the flag is the only removal path (Feature 06 guardrail):
-    a deactivated definition stops future instance generation but its
-    row, schedule rule, assignees and windows all survive, and existing
-    instances plus completion history are never touched.  Reactivation
-    re-enables future generation; generating or removing instances is
-    Feature 07 and does not happen here.
-
-    ``definition_id`` must be a plain int (bools and floats rejected,
-    since SQLite would bind ``True`` onto definition 1) and
-    ``is_active`` must be a real bool — the DAO's ``int()`` would
-    otherwise silently coerce strings and numerics ("1", 0) into a
-    state the caller never asked for.  Raises ValueError naming the
-    offending field when the id is malformed, ``is_active`` is not a
-    bool, or the definition does not exist.
-
-    Atomicity: the existence check, the UPDATE and the readback of the
-    definition, its rule, assignees and windows all run inside the
-    connection-scoped lock, so the returned bundle is a consistent
-    snapshot that a concurrent mutation cannot race.
-
-    ``today`` optionally pins the caller-resolved HA-local date threaded
-    into the activation change's regeneration (see
-    :func:`edit_quest_definition`).  ``horizon_days`` optionally sizes the
-    regeneration's re-materialization window the same way.
-    """
-    _validate_definition_id(definition_id)
-    if not isinstance(is_active, bool):
-        raise ValueError(f"is_active must be a real bool, got {is_active!r}")
-    async with _connection_lock(database):
-        dao = QuestDefinitionsDao(database)
-        if await dao.get(definition_id) is None:
-            raise ValueError(
-                f"definition_id: quest definition {definition_id} "
-                "does not exist"
-            )
-        await dao.set_active(definition_id, is_active)
-        updated = await dao.get(definition_id)
-        assert updated is not None
-        rule_record = await ScheduleRulesDao(database).get(
-            updated.schedule_rule_id
-        )
-        assert rule_record is not None
-        assignees = await dao.list_assignees(definition_id)
-        windows = await dao.list_windows(definition_id)
-    rule = schedule_rule_from_storage(
-        schedule_rule_storage_from_record(rule_record)
-    )
-    await regenerate_for_definition(
-        database, definition_id, today=today, horizon_days=horizon_days
-    )
-    return CreatedQuestDefinition(
-        definition=updated,
-        rule=rule,
-        assignees=assignees,
-        windows=windows,
-    )
-
-
-def _bundle_snapshot(
-    snapshot: QuestDefinitionSnapshot,
-) -> CreatedQuestDefinition:
-    """Decode a DAO snapshot into the layer's rich view.
-
-    The rule record carried by the snapshot is the one the definition
-    referenced at read time, so decoding it here (rather than re-reading
-    through :class:`~.dao_rules.ScheduleRulesDao`) preserves the
-    coherence the DAO's locked snapshot guarantees: the rule, assignees
-    and windows all come from one atomic read, never three separate ones.
-    """
-    rule = schedule_rule_from_storage(
-        schedule_rule_storage_from_record(snapshot.rule)
-    )
-    return CreatedQuestDefinition(
-        definition=snapshot.definition,
-        rule=rule,
-        assignees=snapshot.assignees,
-        windows=snapshot.windows,
-    )
-
-
-async def list_active_definitions(
-    database: NestQuestDatabase,
-) -> list[CreatedQuestDefinition]:
-    """Return every ACTIVE definition with its decoded rule and links.
-
-    Ordered by rising definition id, matching the DAO's ``list_active``
-    order, so callers get a stable, repeatable sequence.  Each entry is
-    the same rich :class:`CreatedQuestDefinition` snapshot as the rest of
-    the layer: the stored row plus its decoded
-    :class:`~.recurrence.ScheduleRule`, assignees and windows.  The
-    definitions and their links are read by the DAO inside one locked
-    transaction, so each bundle is a coherent snapshot that a concurrent
-    edit cannot interleave.
-    """
-    dao = QuestDefinitionsDao(database)
-    snapshots = await dao.list_snapshots_active()
-    return [_bundle_snapshot(snapshot) for snapshot in snapshots]
-
-
-async def list_definitions_for_child(
-    database: NestQuestDatabase,
-    child_id: int,
-) -> list[CreatedQuestDefinition]:
-    """Return the definitions assigned to ``child_id`` (rich view).
-
-    ``child_id`` must be a plain int (bools and floats rejected, since
-    SQLite would bind ``True`` onto child 1).  Results are ordered by
-    rising definition id, matching ``list_active_definitions`` and
-    ``list_definitions_firing_on``.  Each entry is a
-    :class:`CreatedQuestDefinition` snapshot bundling the definition with
-    its decoded rule, assignees and windows, read atomically by the DAO.
-    """
-    _validate_child_id(child_id)
-    dao = QuestDefinitionsDao(database)
-    snapshots = await dao.list_snapshots_by_child(child_id)
-    bundles = [_bundle_snapshot(snapshot) for snapshot in snapshots]
-    return sorted(bundles, key=lambda bundle: bundle.definition.id)
-
-
-async def list_definitions_firing_on(
-    database: NestQuestDatabase,
-    date: str,
-) -> list[CreatedQuestDefinition]:
-    """Return the ACTIVE definitions whose rule fires on ``date``.
-
-    ``date`` must be a strict ISO calendar date (YYYY-MM-DD); a malformed
-    value raises ValueError naming the field.  Each active definition's
-    stored rule is decoded through the task-1 storage mapping and handed
-    to the recurrence engine's :func:`~.recurrence.occurs_on`; only the
-    definitions whose decoded rule fires on the date are returned, in
-    rising definition-id order, each as the same rich
-    :class:`CreatedQuestDefinition` snapshot as the rest of the layer.
-    The definitions and their rules are read inside one locked
-    transaction, so a bundle can never filter on one rule while
-    presenting another state's windows.
-    """
-    _validate_date(date, "date")
-    target = datetime.datetime.strptime(date, "%Y-%m-%d").date()
-    dao = QuestDefinitionsDao(database)
-    snapshots = await dao.list_snapshots_active()
-    bundles = [_bundle_snapshot(snapshot) for snapshot in snapshots]
-    return [bundle for bundle in bundles if occurs_on(bundle.rule, target)]
+from .core.quest_definitions import *  # noqa: F401,F403

custom_components/nestquest/sensor.py

@@ -39,6 +39,7 @@ from .coordinator import (
     NestQuestCoordinator,
     QuestInstanceView,
 )
+from .core.snapshot import instance_payload
 
 #: Home Assistant's state machine refuses states longer than 255
 #: characters (its hard recorder/state limit).  These sensors' states
@@ -63,40 +64,6 @@ def _state_within_limit(state: Any) -> Any:
     return state
 
 
-def _instance_payload(
-    instances: Iterable[QuestInstanceView], *, include_missed: bool
-) -> list[dict[str, Any]]:
-    """Shape instance dicts per ENTITIES-AND-SERVICES.md §1.
-
-    ``state`` maps the coordinator's derived ``done`` to the panel's
-    ``completed`` spelling; ``missed`` instances are omitted unless
-    ``include_missed`` (the admin payload, D-009, keeps them with
-    their ``missed`` state).
-    """
-    payload: list[dict[str, Any]] = []
-    for view in instances:
-        if view.state == "missed" and not include_missed:
-            continue
-        payload.append(
-            {
-                "id": view.instance_id,
-                "definition_id": view.definition_id,
-                "child_id": view.child_id,
-                "title": view.title,
-                "icon": view.icon,
-                "window": view.window,
-                "due_time": view.due_time,
-                "state": (
-                    "completed" if view.state == "done" else view.state
-                ),
-                "overdue": view.overdue,
-                "completed_at": view.completed_at,
-                "on_time": view.was_on_time,
-            }
-        )
-    return payload
-
-
 #: State reported by the next-quest sensor when the child owes nothing
 #: else today.  A documented sentinel, never an empty string (an empty
 #: state reads as "sensor went unavailable" in HA).
@@ -215,10 +182,10 @@ class NestQuestQuestsDueTodaySensor(_NestQuestChildDaySensor):
         if child is None:
             return None
         return {
-            "instances": _instance_payload(
+            "instances": instance_payload(
                 child.instances, include_missed=False
             ),
-            "admin_instances": _instance_payload(
+            "admin_instances": instance_payload(
                 child.instances, include_missed=True
             ),
             "child_id": child.child_id,

custom_components/nestquest/service_policy.py

@@ -1,46 +1,11 @@
-"""Explicit admin-only versus open service registry (Feature 09).
+"""Re-export of :mod:`custom_components.nestquest.core.service_policy` for the integration package.
 
-One mapping, one file: every registered ``nestquest`` service name is
-either ``open`` or ``admin_only``.  The permission decorator (later
-Feature 09 tasks) reads this table; it does not take per-handler
-policy arguments.
+The service policy registry lives in
+:mod:`custom_components.nestquest.core.service_policy` (extracted in
+task 510c1f78); this module re-exports it so existing
+``from .service_policy import ...`` references inside the integration
+keep working.
 """
 from __future__ import annotations
 
-from .const import (
-    DOMAIN_SERVICES,
-    SERVICE_COMPLETE_QUEST,
-    SERVICE_CREATE_PRESENCE_OVERRIDE,
-    SERVICE_CREATE_QUEST_DEFINITION,
-    SERVICE_DELETE_PRESENCE_OVERRIDE,
-    SERVICE_EXPORT_HISTORY_CSV,
-    SERVICE_MANAGE_CHILD,
-    SERVICE_REGENERATE,
-    SERVICE_SET_PRESENCE_PATTERN,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE,
-    SERVICE_UNCOMPLETE_QUEST,
-    SERVICE_UPDATE_QUEST_DEFINITION,
-)
-
-OPEN = "open"
-ADMIN_ONLY = "admin_only"
-
-SERVICE_POLICY: dict[str, str] = {
-    SERVICE_COMPLETE_QUEST: OPEN,
-    SERVICE_UNCOMPLETE_QUEST: ADMIN_ONLY,
-    SERVICE_CREATE_QUEST_DEFINITION: ADMIN_ONLY,
-    SERVICE_UPDATE_QUEST_DEFINITION: ADMIN_ONLY,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE: ADMIN_ONLY,
-    SERVICE_SET_PRESENCE_PATTERN: ADMIN_ONLY,
-    SERVICE_CREATE_PRESENCE_OVERRIDE: ADMIN_ONLY,
-    SERVICE_DELETE_PRESENCE_OVERRIDE: ADMIN_ONLY,
-    SERVICE_EXPORT_HISTORY_CSV: ADMIN_ONLY,
-    SERVICE_MANAGE_CHILD: ADMIN_ONLY,
-    SERVICE_REGENERATE: ADMIN_ONLY,
-}
-
-if frozenset(SERVICE_POLICY) != frozenset(DOMAIN_SERVICES):
-    raise RuntimeError(
-        "SERVICE_POLICY must name exactly the registered nestquest services, "
-        f"got {sorted(SERVICE_POLICY)} vs {list(DOMAIN_SERVICES)}"
-    )
+from .core.service_policy import *  # noqa: F401,F403

custom_components/nestquest/services.py

@@ -24,8 +24,6 @@ from . import children as children_layer
 from . import completion as completion_layer
 from . import quest_definitions as quest_definitions_layer
 from .const import (
-    CONF_HORIZON_DAYS,
-    DEFAULT_HORIZON_DAYS,
     DOMAIN,
     DOMAIN_SERVICES,
     QUEST_WINDOWS,
@@ -258,12 +256,7 @@ async def _refresh_entities(runtime: Any) -> None:
 def _generation_kwargs(hass: HomeAssistant, runtime: Any) -> dict[str, Any]:
     time_zone = ZoneInfo(hass.config.time_zone)
     today = datetime.datetime.now(time_zone).date()
-    value = runtime.options.get(CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS)
-    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
-        horizon_days = DEFAULT_HORIZON_DAYS
-    else:
-        horizon_days = value
-    return {"today": today, "horizon_days": horizon_days}
+    return {"today": today, "horizon_days": runtime.settings.horizon_days}
 
 
 def _actor_kwargs(call: Any) -> dict[str, Any]:

pyproject.toml

@@ -7,11 +7,20 @@ requires-python = ">=3.11"
 dependencies = []
 
 [dependency-groups]
+# fastapi and uvicorn live in the DEV group only so the monorepo's test
+# venv can exercise the API app (tests under tests/test_api_health.py).
+# They are NOT runtime dependencies of the NestQuest HA integration.
+# When the API deployable is packaged (Feature 17), its runtime
+# dependencies — fastapi, uvicorn, and any others — MUST be declared in
+# that deployable's own dependency manifest, not here.
 dev = [
+    "fastapi>=0.115",
+    "httpx>=0.28",
     "jinja2>=3",
     "pytest>=8.0.0",
     "pytest-asyncio>=0.24",
     "pyyaml>=6",
+    "uvicorn>=0.30",
     "voluptuous>=0.14",
 ]
 

tests/conftest.py

@@ -22,6 +22,7 @@ pytest -q``); it is never meant to run against a real HA install.
 from __future__ import annotations
 
 import asyncio
+import datetime
 import importlib.util
 import inspect
 import sys
@@ -916,4 +917,40 @@ def make_config_flow_entry():
     def _factory(domain: str, entry_id: str = "existing"):
         return SimpleNamespace(domain=domain, entry_id=entry_id)
 
-    return _factory
+    return _factory
+
+
+def freeze_nestquest_clock(
+    monkeypatch, instant: datetime.datetime
+) -> tuple[datetime.datetime, list]:
+    """Freeze the integration's ``datetime`` clock to a fixed aware instant.
+
+    Only ``custom_components.nestquest``'s ``datetime`` binding is patched,
+    so the generation path's ``datetime.datetime.now`` reads this instant
+    (localized to whatever time zone it asks for) while every other module
+    and the test harness keep the real clock.  Returns ``(frozen, requested)``
+    where ``frozen`` is the instant normalized to UTC and ``requested`` is
+    the list of ``tzinfo`` objects the code under test passed to ``now`` —
+    so a caller can prove the generation path actually requested the
+    configured HA time zone rather than silently reading UTC.
+    """
+    import custom_components.nestquest as nestquest
+
+    frozen = instant.astimezone(datetime.timezone.utc)
+    requested: list = []
+
+    class _FrozenDatetime(datetime.datetime):
+        @classmethod
+        def now(cls, tz=None):
+            requested.append(tz)
+            if tz is None:
+                return frozen.replace(tzinfo=None)
+            return frozen.astimezone(tz)
+
+    fake_module = SimpleNamespace(
+        datetime=_FrozenDatetime,
+        timedelta=datetime.timedelta,
+        date=datetime.date,
+    )
+    monkeypatch.setattr(nestquest, "datetime", fake_module)
+    return frozen, requested

tests/test_api_health.py

@@ -0,0 +1,336 @@
+"""FastAPI skeleton tests: health, OpenAPI, core wiring (task 042dfc5c).
+
+These tests start the NestQuest API app with httpx against the ASGI
+app and assert the skeleton contract of Feature 16's first task:
+
+- ``GET /health`` returns 200 with a JSON status body (``status: ok``)
+  and does NOT leak the filesystem path;
+- ``GET /docs`` (Swagger UI) is served, and ``GET /openapi.json``
+  returns the OpenAPI document;
+- the app wires core (opens the configured SQLite file and applies
+  migrations on startup via the lifespan) and closes the connection on
+  shutdown (``connected is False`` afterwards);
+- ``ApiConfig.from_env`` raises when ``NESTQUEST_DB_PATH`` is missing or
+  empty, and returns the value when set;
+- a startup failure (unwritable path / non-SQLite file) surfaces from
+  the lifespan rather than the first request;
+- each test is hermetic — it points ``NESTQUEST_DB_PATH`` at a fresh
+  temp file.
+
+A SEPARATE subprocess test asserts the stronger invariant the task
+calls out: the app imports the bundled ``core`` WITHOUT importing
+``homeassistant``.  That cannot run inside the pytest process because
+``tests/conftest.py`` installs mock ``homeassistant`` modules globally
+before any test imports the integration; a subprocess with a clean
+``sys.modules`` is the only honest proof (the same approach
+``tests/test_core_no_ha_smoke.py`` takes for the core bundle).
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+import httpx
+import pytest
+
+from api.app import create_app
+from api.config import ApiConfig, ConfigError
+from api.database import DatabaseState, _executor, make_database
+
+#: The repo root, so the no-HA subprocess can import the API package.
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+
+#: The marker the no-HA subprocess prints on success.
+_SUCCESS_MARKER = "API NO-HA IMPORT OK"
+
+
+@pytest.fixture
+def temp_db_path(tmp_path: Path) -> str:
+    """A fresh per-test SQLite path under pytest's tmp_path."""
+    return str(tmp_path / "nestquest.db")
+
+
+class _AppRunner:
+    """Run the app's lifespan around an httpx AsyncClient.
+
+    httpx's :class:`ASGITransport` does NOT run the ASGI lifespan on its
+    own, so the database would never open.  Starlette exposes the app's
+    lifespan as ``app.router.lifespan_context``; wrapping the client
+    session in it drives the same startup/shutdown path uvicorn would,
+    so ``open_and_migrate`` runs before the first request and ``close``
+    runs after the last.
+
+    ``__aexit__`` uses try/finally so a client-side error still shuts
+    the lifespan down — otherwise a failure mid-test would leak the
+    database connection open.
+    """
+
+    def __init__(self, db_path: str) -> None:
+        # The token value is irrelevant to these tests (the health
+        # route is unauthenticated); it just satisfies the required
+        # field — the panel token's own tests live in test_api_panel.py.
+        self.app = create_app(
+            ApiConfig(db_path=db_path, panel_token="health-runner-token")
+        )
+
+    async def __aenter__(self) -> httpx.AsyncClient:
+        self._lifespan = self.app.router.lifespan_context(self.app)
+        await self._lifespan.__aenter__()
+        self._client = httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=self.app),
+            base_url="http://testserver",
+        )
+        return await self._client.__aenter__()
+
+    async def __aexit__(self, *exc) -> None:
+        try:
+            await self._client.__aexit__(*exc)
+        finally:
+            await self._lifespan.__aexit__(*exc)
+
+
+@pytest.fixture
+async def app_client(temp_db_path: str) -> httpx.AsyncClient:
+    async with _AppRunner(temp_db_path) as client:
+        yield client
+
+
+# --- ApiConfig.from_env -------------------------------------------------
+
+
+def test_from_env_returns_set_value() -> None:
+    """Set, non-empty env values are returned verbatim."""
+    cfg = ApiConfig.from_env(
+        {
+            "NESTQUEST_DB_PATH": "/data/nq.db",
+            "NESTQUEST_PANEL_TOKEN": "panel-token",
+        }
+    )
+    assert cfg.db_path == "/data/nq.db"
+    assert cfg.panel_token == "panel-token"
+
+
+def test_from_env_raises_on_empty_value() -> None:
+    """An empty/whitespace-only value raises ConfigError (no silent default)."""
+    with pytest.raises(ConfigError):
+        ApiConfig.from_env({"NESTQUEST_DB_PATH": "   "})
+
+
+def test_from_env_raises_on_missing_value() -> None:
+    """A missing NESTQUEST_DB_PATH raises ConfigError (no silent default)."""
+    with pytest.raises(ConfigError):
+        ApiConfig.from_env({})
+
+
+# --- health / openapi / docs -------------------------------------------
+
+
+async def test_health_returns_200_with_status_body(
+    app_client: httpx.AsyncClient,
+) -> None:
+    """GET /health returns 200 with status ok and no filesystem path."""
+    response = await app_client.get("/health")
+    assert response.status_code == 200
+    body = response.json()
+    assert body == {"status": "ok"}
+    assert "db_path" not in body
+
+
+async def test_openapi_document_is_served(
+    app_client: httpx.AsyncClient,
+) -> None:
+    """GET /openapi.json returns the OpenAPI document."""
+    response = await app_client.get("/openapi.json")
+    assert response.status_code == 200
+    schema = response.json()
+    assert schema["openapi"].startswith("3.")
+    assert "/health" in schema["paths"]
+
+
+async def test_docs_swagger_ui_is_served(app_client: httpx.AsyncClient) -> None:
+    """GET /docs serves the Swagger UI HTML (OpenAPI at /docs)."""
+    response = await app_client.get("/docs")
+    assert response.status_code == 200
+    assert "swagger" in response.text.lower()
+
+
+# --- core wiring & shutdown --------------------------------------------
+
+
+async def test_app_wires_core_and_applies_migrations(
+    temp_db_path: str,
+) -> None:
+    """The lifespan opens the SQLite file and applies migrations.
+
+    After startup, the file exists and carries the NestQuest schema
+    version stamp — proving the app imported core, opened the database
+    at the configured path, and ran the migration runner.
+    """
+    async with _AppRunner(temp_db_path):
+        assert Path(temp_db_path).exists()
+    # Re-open the file with a fresh core database to read the version
+    # stamp independent of the app's connection.  Reuse the API's own
+    # executor so the test exercises the same wiring the app does.
+    from api.nestquest_core import core_db, core_migrations
+
+    database = core_db.NestQuestDatabase(_executor)
+    await database.open(temp_db_path)
+    try:
+        version = await core_migrations.read_schema_version(database)
+    finally:
+        await database.close()
+    assert version >= 1
+
+
+async def test_shutdown_closes_the_connection(temp_db_path: str) -> None:
+    """The lifespan closes the database connection on shutdown.
+
+    After the runner exits, ``DatabaseState.database.connected`` is
+    False — proving ``close()`` ran (the lifespan's finally block) even
+    on a clean exit.
+    """
+    runner = _AppRunner(temp_db_path)
+    async with runner as _client:
+        state: DatabaseState = runner.app.state.db
+        assert state.database.connected
+    assert not state.database.connected
+
+
+# --- startup failure ----------------------------------------------------
+
+
+async def test_startup_fails_on_unwritable_path(tmp_path: Path) -> None:
+    """A database path whose parent directory does not exist fails fast.
+
+    ``sqlite3.connect`` raises ``OperationalError`` for a path under a
+    non-existent directory; the lifespan surfaces that as a startup
+    error rather than the first request.  The connection is closed
+    through the lifespan's finally block (``close`` is a no-op on a
+    never-opened wrapper).
+    """
+    bad_path = str(tmp_path / "does_not_exist" / "nestquest.db")
+    runner = _AppRunner(bad_path)
+    with pytest.raises(Exception):
+        async with runner:
+            pass
+
+
+async def test_startup_fails_on_non_sqlite_file(tmp_path: Path) -> None:
+    """A path pointing at a non-SQLite file fails fast on startup.
+
+    Opening an existing file that is not a SQLite database makes the
+    ``PRAGMA journal_mode=WAL`` run during :meth:`open` raise
+    ``DatabaseError: file is not a database``; the lifespan surfaces it.
+    """
+    bad_file = tmp_path / "not_a_db.bin"
+    bad_file.write_bytes(b"this is not a sqlite database")
+    runner = _AppRunner(str(bad_file))
+    with pytest.raises(Exception):
+        async with runner:
+            pass
+
+
+# --- no-HA subprocess ---------------------------------------------------
+
+#: The no-HA subprocess script.  Runs with ``sys.executable -c`` so it
+#: starts with a clean ``sys.modules`` and no ``homeassistant`` installed
+#: (the suite's conftest stubs are not present in a subprocess).  It
+#: builds the app — which triggers the core bootstrap — and asserts
+#: neither ``homeassistant`` nor ``custom_components`` entered
+#: ``sys.modules``, and that the loaded core package's ``__file__``
+#: points at the bundled directory.
+_NO_HA_SCRIPT = textwrap.dedent(
+    """\
+    import sys
+    import tempfile
+    from pathlib import Path
+
+    sys.path.insert(0, sys.argv[1])
+    REPO_ROOT = Path(sys.argv[1])
+
+    # homeassistant must not be present before we touch the API.
+    assert "homeassistant" not in sys.modules, (
+        "homeassistant already in sys.modules before app import — the "
+        "subprocess is not a clean no-HA process"
+    )
+
+    from api.app import create_app
+    from api.config import ApiConfig
+    from api.nestquest_core import core
+
+    # The app build imports core via api.nestquest_core.  core is a
+    # Home-Assistant-free package; if it (or its loader) ever drags HA
+    # in, this fails.
+    assert "homeassistant" not in sys.modules, (
+        "homeassistant imported while building the NestQuest API app — "
+        "the core wiring is no longer Home-Assistant-free"
+    )
+    # The loader registers core under the distinct name "nestquest_core"
+    # WITHOUT executing custom_components.nestquest.__init__, so the
+    # parent integration package must never be registered, and no
+    # sys.path mutation places the integration directory on sys.path.
+    assert "custom_components" not in sys.modules, (
+        "custom_components registered in sys.modules — the core loader "
+        "executed the integration's HA-coupled __init__ instead of loading "
+        "core by file location"
+    )
+    assert "nestquest_core" in sys.modules, "core was not imported"
+
+    # core.__file__ must point at the bundled directory inside the
+    # integration, proving the file-location loader resolved against the
+    # bundled package rather than some other "core" on sys.path.
+    expected_core_dir = (
+        REPO_ROOT / "custom_components" / "nestquest" / "core"
+    )
+    assert Path(core.__file__).resolve() == (
+        expected_core_dir / "__init__.py"
+    ).resolve(), (
+        f"core.__file__={core.__file__} does not point at the bundled "
+        f"directory {expected_core_dir}"
+    )
+
+    # Build the app (the lifespan is NOT run here, so the path is never
+    # opened — it just needs to be a non-empty string to satisfy the
+    # fail-fast config check).  Use a temp path so nothing is created;
+    # the panel token value is irrelevant to this import-only check.
+    app = create_app(ApiConfig(db_path=str(
+        Path(tempfile.gettempdir()) / "nq-noha-buildonly.db"
+    ), panel_token="noha-import-token"))
+    assert app is not None
+
+    print("API NO-HA IMPORT OK")
+    """
+)
+
+
+def test_app_imports_core_without_importing_homeassistant() -> None:
+    """The app imports core without importing homeassistant (subprocess).
+
+    Runs in a subprocess because ``tests/conftest.py`` installs mock
+    ``homeassistant`` modules into the pytest process's ``sys.modules``
+    before any test runs, so an in-process check could never
+    distinguish "core never touched HA" from "conftest already stubbed
+    HA for us".  The subprocess is a genuine no-HA process; if the
+    core loader (or core itself) ever grows a ``homeassistant``
+    import, the subprocess exits non-zero with ``ModuleNotFoundError``.
+    """
+    result = subprocess.run(
+        [sys.executable, "-c", _NO_HA_SCRIPT, str(_REPO_ROOT)],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    if result.returncode != 0:
+        raise AssertionError(
+            f"no-HA app-import subprocess exited {result.returncode}.\n"
+            f"--- stdout ---\n{result.stdout}\n"
+            f"--- stderr ---\n{result.stderr}"
+        )
+    assert _SUCCESS_MARKER in result.stdout, (
+        f"success marker {_SUCCESS_MARKER!r} not printed.\n"
+        f"--- stdout ---\n{result.stdout}\n"
+        f"--- stderr ---\n{result.stderr}"
+    )

tests/test_api_panel.py

@@ -0,0 +1,688 @@
+"""Panel-plane route tests: service token + snapshot (task ae7e90ae).
+
+These tests exercise the NestQuest API's panel plane against the ASGI
+app with httpx:
+
+- ``GET /api/v1/panel/snapshot`` requires the panel service token
+  (D-012): a request with NO ``Authorization`` header, a MALFORMED
+  header, and a WRONG token all return 401; the correct Bearer token
+  returns 200.
+- The 200 body is the documented snapshot shape: ``today_iso``,
+  ``cycle_day``, and ``children`` in the household's sort order, each
+  carrying ``child_id``/``child_name``/``present``/``next_present``,
+  the per-day rollup counts, and its instances in the documented panel
+  payload shape (ENTITIES-AND-SERVICES.md §1) with missed instances
+  OMITTED (D-009).
+- ``ApiConfig.from_env`` requires ``NESTQUEST_PANEL_TOKEN`` with the
+  same fail-fast discipline as ``NESTQUEST_DB_PATH``.
+
+The household is seeded through the SAME core copy the app uses — the
+``nestquest_core.*`` package registered by ``api/nestquest_core.py`` —
+NOT the conftest-stubbed ``custom_components.nestquest.core`` copy (see
+the two-copy caveat in api/nestquest_core.py's docstring: never compare
+class or exception identity across the two copies).  The seed opens and
+migrates its own connection on the app's SQLite path and closes BEFORE
+the app's lifespan opens the file, so the two connections never
+overlap.
+
+The route's single clock read (:func:`api.routes_panel._local_now`) is
+pinned with monkeypatch the same way the coordinator's ``_local_now``
+is pinned in test_core_snapshot.py, so the seeded rows and the
+snapshot's ``today`` can never straddle midnight.
+"""
+from __future__ import annotations
+
+import datetime
+import importlib
+from pathlib import Path
+from types import SimpleNamespace
+from zoneinfo import ZoneInfo
+
+import httpx
+import pytest
+
+from api import routes_panel
+from api.app import create_app
+from api.config import ApiConfig, ConfigError
+from api.database import _executor
+from api.nestquest_core import (
+    core_db,
+    core_migrations,
+    core_snapshot,
+)
+
+#: The panel service token the test apps are configured with.
+PANEL_TOKEN = "panel-service-token-test"
+
+# The bundled core submodules, through the SAME copy the app uses
+# (nestquest_core.*, NOT the conftest-stubbed custom_components copy).
+_children = importlib.import_module("nestquest_core.children")
+_quest_definitions = importlib.import_module(
+    "nestquest_core.quest_definitions"
+)
+_materialize = importlib.import_module("nestquest_core.materialize")
+_recurrence = importlib.import_module("nestquest_core.recurrence")
+_dao_presence = importlib.import_module("nestquest_core.dao_presence")
+_dao_instances = importlib.import_module("nestquest_core.dao_instances")
+_completion = importlib.import_module("nestquest_core.completion")
+
+
+async def _events_for_instance(database: object, instance_id: int) -> list:
+    """The instance's completion events, on the app's core copy.
+
+    Uses the SAME ``nestquest_core.*`` copy the app uses (the two-copy
+    caveat: never mix copies) against the app's live connection.
+    """
+    dao = _dao_instances.CompletionEventsDao(database)
+    return await dao.list_by_instance(instance_id)
+
+
+async def _derived_state(
+    database: object, instance: object, today: datetime.date
+) -> str:
+    """The instance's derived state on the app's core copy.
+
+    ``derive_state(instance, latest, today)`` from the app's core copy;
+    the latest event is fetched through the same copy's DAO against the
+    app's live connection.
+    """
+    dao = _dao_instances.CompletionEventsDao(database)
+    latest = await dao.get_latest_for_instance(instance.id)
+    return _completion.derive_state(instance, latest, today)
+
+
+async def _seed_household(
+    db_path: str,
+    today: datetime.date,
+    pinned_now: datetime.datetime,
+) -> SimpleNamespace:
+    """Seed a two-child household on ``db_path`` and return its records.
+
+    Mirrors the test_core_snapshot.py household: an AWAY child (2-week
+    custody cycle anchored yesterday, empty week 0, an override returns
+    her today+2) with an open quest due 10:00 — overdue at the pinned
+    12:00 — and a present child whose 17:00 quest is completed at
+    12:00 (on time).  A third quest's instance is materialized due
+    YESTERDAY (via ``materialize`` with ``today`` pinned to yesterday,
+    since the no-past guard refuses past-dated writes): a past-due OPEN
+    instance, i.e. the "missed" view the panel payload must omit.
+
+    Opens, migrates, seeds, and CLOSES its own connection so the app's
+    lifespan connection never overlaps it.
+    """
+    database = core_db.NestQuestDatabase(_executor)
+    await database.open(db_path)
+    try:
+        await core_migrations.apply_migrations(database)
+        today_iso = today.isoformat()
+        yesterday = today - datetime.timedelta(days=1)
+        yesterday_iso = yesterday.isoformat()
+
+        ada = await _children.create_child(database, "Ada", sort_order=0)
+        bo = await _children.create_child(database, "Bo", sort_order=1)
+
+        # Every rule starts YESTERDAY so the yesterday materialization
+        # below (which pins ``today`` to yesterday) fires them.
+        await _quest_definitions.create_quest_definition(
+            database,
+            "Pack bag",
+            _recurrence.ScheduleRule.from_dict(
+                {"rule_type": "daily", "start_date": yesterday_iso}
+            ),
+            [ada.id],
+            [("morning", "10:00")],
+        )
+        await _quest_definitions.create_quest_definition(
+            database,
+            "Brush teeth",
+            _recurrence.ScheduleRule.from_dict(
+                {"rule_type": "daily", "start_date": yesterday_iso}
+            ),
+            [bo.id],
+            [("morning", "17:00")],
+        )
+        # Today's instances first, while Ada has no presence schedule
+        # (she is present every day, so her instance IS generated).
+        await _materialize.materialize(
+            database,
+            today_iso,
+            (today + datetime.timedelta(days=3)).isoformat(),
+            today=today,
+        )
+        # The stale quest is created AFTER the today walk, so its only
+        # instance is the yesterday one written below.
+        await _quest_definitions.create_quest_definition(
+            database,
+            "Stale chore",
+            _recurrence.ScheduleRule.from_dict(
+                {"rule_type": "daily", "start_date": yesterday_iso}
+            ),
+            [ada.id],
+            [("morning", "09:00")],
+        )
+        # Materialize yesterday with ``today`` pinned to yesterday: the
+        # no-past guard accepts the rows, and they land past-due (no
+        # completion events) — the missed view.
+        await _materialize.materialize(
+            database, yesterday_iso, yesterday_iso, today=yesterday
+        )
+        instances = _dao_instances.QuestInstancesDao(database)
+
+        ada_today = await instances.list_by_child_and_date(ada.id, today_iso)
+        assert len(ada_today) == 1
+        pack_bag_instance = ada_today[0]
+        bo_today = await instances.list_by_child_and_date(bo.id, today_iso)
+        assert len(bo_today) == 1
+        brush_teeth_instance = bo_today[0]
+        ada_yesterday = await instances.list_by_child_and_date(
+            ada.id, yesterday_iso
+        )
+        stale_instance = next(
+            record
+            for record in ada_yesterday
+            if record.due_time == "09:00"
+        )
+
+        # Ada's custody schedule, added AFTER materialization (the
+        # same order test_core_snapshot.py seeds): 2-week cycle
+        # anchored yesterday, empty week 0 covers today => absent
+        # today; an override returns her on today+2.
+        await _dao_presence.PresenceSchedulesDao(database).upsert_by_child(
+            ada.id,
+            cycle_length_weeks=2,
+            anchor_date=yesterday_iso,
+            pattern="|0,1,2,3,4,5,6",
+        )
+        returns_date = today + datetime.timedelta(days=2)
+        await _dao_presence.PresenceOverridesDao(database).create(
+            ada.id,
+            returns_date.isoformat(),
+            returns_date.isoformat(),
+            is_present=True,
+            note="visit",
+        )
+
+        # Complete Bo's today instance at the pinned 12:00 (17:00 due
+        # => on time).
+        await _completion.complete_instance(
+            database,
+            brush_teeth_instance.id,
+            actor_source="panel",
+            actor_child_id=bo.id,
+            now=pinned_now,
+            today=today,
+        )
+        return SimpleNamespace(
+            ada=ada,
+            bo=bo,
+            pack_bag_instance=pack_bag_instance,
+            brush_teeth_instance=brush_teeth_instance,
+            stale_instance=stale_instance,
+            returns_date=returns_date,
+        )
+    finally:
+        await database.close()
+
+
+class _PanelRunner:
+    """Run the app's lifespan around an httpx AsyncClient.
+
+    Same pattern as test_api_health.py's ``_AppRunner``: httpx's ASGI
+    transport does not run the lifespan, so it is driven explicitly and
+    shut down in ``__aexit__``'s finally block even on failure.
+    """
+
+    def __init__(
+        self, db_path: str, panel_token: str = PANEL_TOKEN
+    ) -> None:
+        self.app = create_app(
+            ApiConfig(db_path=db_path, panel_token=panel_token)
+        )
+
+    async def __aenter__(self) -> tuple["_PanelRunner", httpx.AsyncClient]:
+        self._lifespan = self.app.router.lifespan_context(self.app)
+        await self._lifespan.__aenter__()
+        self._client = httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=self.app),
+            base_url="http://testserver",
+        )
+        await self._client.__aenter__()
+        return self, self._client
+
+    async def __aexit__(self, *exc) -> None:
+        try:
+            await self._client.__aexit__(*exc)
+        finally:
+            await self._lifespan.__aexit__(*exc)
+
+
+@pytest.fixture
+def temp_db_path(tmp_path: Path) -> str:
+    """A fresh per-test SQLite path under pytest's tmp_path."""
+    return str(tmp_path / "nestquest.db")
+
+
+@pytest.fixture
+async def panel_client(temp_db_path: str) -> httpx.AsyncClient:
+    """An app client with an empty (migrated) household database."""
+    async with _PanelRunner(temp_db_path) as runner_and_client:
+        _, client = runner_and_client
+        yield client
+
+
+@pytest.fixture
+async def seeded_panel(temp_db_path: str, monkeypatch) -> SimpleNamespace:
+    """A seeded household served by the app, with the clock pinned.
+
+    One host clock read anchors ``today``; the pinned instant is
+    12:00 UTC that day (past Ada's 10:00 due, before Bo's 17:00).  The
+    route's ``_local_now`` is patched to return the pinned instant.
+
+    Yields the runner too so tests reach the app's live database (the
+    SAME ``nestquest_core`` connection) for assertions.
+    """
+    today = datetime.datetime.now().astimezone().date()
+    time_zone = ZoneInfo("UTC")
+    pinned_now = datetime.datetime(
+        today.year, today.month, today.day, 12, 0, 0, tzinfo=time_zone
+    )
+    seed = await _seed_household(temp_db_path, today, pinned_now)
+    monkeypatch.setattr(routes_panel, "_local_now", lambda: pinned_now)
+    async with _PanelRunner(temp_db_path) as runner_and_client:
+        runner, client = runner_and_client
+        yield SimpleNamespace(
+            client=client,
+            database=runner.app.state.db.database,
+            seed=seed,
+            today=today,
+            pinned_now=pinned_now,
+            pinned_utc_iso=pinned_now.astimezone(
+                datetime.timezone.utc
+            ).isoformat(),
+        )
+
+
+# --- ApiConfig.from_env: the panel token --------------------------------
+
+
+def test_from_env_reads_panel_token() -> None:
+    """A set, non-empty NESTQUEST_PANEL_TOKEN is returned verbatim."""
+    cfg = ApiConfig.from_env(
+        {
+            "NESTQUEST_DB_PATH": "/data/nq.db",
+            "NESTQUEST_PANEL_TOKEN": "panel-token",
+        }
+    )
+    assert cfg.panel_token == "panel-token"
+
+
+def test_from_env_requires_panel_token_when_missing() -> None:
+    """A missing panel token raises ConfigError (no silent default)."""
+    with pytest.raises(ConfigError):
+        ApiConfig.from_env({"NESTQUEST_DB_PATH": "/data/nq.db"})
+
+
+def test_from_env_requires_panel_token_when_empty() -> None:
+    """An empty/whitespace panel token raises ConfigError."""
+    with pytest.raises(ConfigError):
+        ApiConfig.from_env(
+            {
+                "NESTQUEST_DB_PATH": "/data/nq.db",
+                "NESTQUEST_PANEL_TOKEN": "   ",
+            }
+        )
+
+
+# --- service-token auth --------------------------------------------------
+
+
+async def test_missing_token_is_unauthorized(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """A request with no Authorization header returns 401."""
+    response = await panel_client.get("/api/v1/panel/snapshot")
+    assert response.status_code == 401
+    assert "www-authenticate" in {
+        key.lower() for key in response.headers
+    }
+
+
+async def test_wrong_token_is_unauthorized(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """A wrong Bearer token returns 401."""
+    response = await panel_client.get(
+        "/api/v1/panel/snapshot",
+        headers={"Authorization": "Bearer not-the-panel-token"},
+    )
+    assert response.status_code == 401
+
+
+async def test_malformed_authorization_header_is_unauthorized(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """A malformed Authorization header returns 401.
+
+    Wrong scheme, empty credential, and an empty header all fail the
+    same way — the response never reveals which part failed.
+    """
+    for header in (
+        "Basic dXNlcjpwYXNz",
+        "Bearer",
+        "Bearer   ",
+        "Token not-the-panel-token",
+        "",
+    ):
+        response = await panel_client.get(
+            "/api/v1/panel/snapshot",
+            headers={"Authorization": header},
+        )
+        assert response.status_code == 401, f"header {header!r} passed"
+
+
+# --- snapshot payload ----------------------------------------------------
+
+
+async def test_valid_token_returns_full_snapshot(
+    seeded_panel: SimpleNamespace,
+) -> None:
+    """The correct token returns 200 with the documented snapshot shape.
+
+    Children in sort order (Ada sort_order 0, Bo 1); per-child counts,
+    presence, next_present, and cycle day all asserted as explicit
+    literals; each child's instances are in the documented panel
+    payload shape (done -> completed spelling, on_time passthrough).
+    """
+    seed = seeded_panel.seed
+    response = await seeded_panel.client.get(
+        "/api/v1/panel/snapshot",
+        headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+    )
+    assert response.status_code == 200
+    body = response.json()
+
+    assert body["today_iso"] == seeded_panel.today.isoformat()
+    # Ada's 2-week cycle anchored yesterday => today is cycle day 2.
+    assert body["cycle_day"] == 2
+
+    children = body["children"]
+    assert [child["child_id"] for child in children] == [
+        seed.ada.id,
+        seed.bo.id,
+    ], "children appear in sort_order"
+
+    ada, bo = children
+
+    # Ada: away today, returns on the override date; her 10:00 quest
+    # is open and overdue at the pinned 12:00.
+    assert ada["child_name"] == "Ada"
+    assert ada["present"] is False
+    assert ada["next_present"] == seed.returns_date.isoformat()
+    assert ada["due_today"] == 1
+    assert ada["completed_today"] == 0
+    assert ada["remaining_today"] == 1
+    assert ada["completion_pct"] == 0
+    assert ada["instances"] == [
+        {
+            "id": seed.pack_bag_instance.id,
+            "definition_id": seed.pack_bag_instance.definition_id,
+            "child_id": seed.ada.id,
+            "title": "Pack bag",
+            "icon": None,
+            "window": "morning",
+            "due_time": "10:00",
+            "state": "open",
+            "overdue": True,
+            "completed_at": None,
+            "on_time": None,
+        }
+    ]
+
+    # Bo: present, completed his 17:00 quest at the pinned 12:00
+    # (on time), so the panel spelling is "completed".
+    assert bo["child_name"] == "Bo"
+    assert bo["present"] is True
+    assert bo["next_present"] is None
+    assert bo["due_today"] == 1
+    assert bo["completed_today"] == 1
+    assert bo["remaining_today"] == 0
+    assert bo["completion_pct"] == 100
+    assert bo["instances"] == [
+        {
+            "id": seed.brush_teeth_instance.id,
+            "definition_id": seed.brush_teeth_instance.definition_id,
+            "child_id": seed.bo.id,
+            "title": "Brush teeth",
+            "icon": None,
+            "window": "morning",
+            "due_time": "17:00",
+            "state": "completed",
+            "overdue": False,
+            "completed_at": seeded_panel.pinned_utc_iso,
+            "on_time": True,
+        }
+    ]
+
+
+async def test_missed_instances_are_omitted_from_panel_payload(
+    seeded_panel: SimpleNamespace,
+) -> None:
+    """A missed instance never reaches the panel payload (D-009).
+
+    The household carries a past-due OPEN instance due yesterday (the
+    state the panel reads as "missed"); it must not appear anywhere in
+    the response, and Ada's payload carries exactly her ONE today
+    instance — the past-due rows (the stale chore AND her pack bag due
+    yesterday) are both omitted rather than rendered.
+    """
+    seed = seeded_panel.seed
+    response = await seeded_panel.client.get(
+        "/api/v1/panel/snapshot",
+        headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+    )
+    assert response.status_code == 200
+    body = response.json()
+
+    payload_instances = [
+        instance
+        for child in body["children"]
+        for instance in child["instances"]
+    ]
+    assert "missed" not in [
+        instance["state"] for instance in payload_instances
+    ]
+    past_due_ids = {seed.stale_instance.id}
+    assert past_due_ids.isdisjoint(
+        instance["id"] for instance in payload_instances
+    ), "the past-due open instance leaked into the panel payload"
+
+    ada = next(
+        child
+        for child in body["children"]
+        if child["child_id"] == seed.ada.id
+    )
+    assert [instance["id"] for instance in ada["instances"]] == [
+        seed.pack_bag_instance.id
+    ]
+
+
+def test_panel_shaper_drops_missed_views() -> None:
+    """The route's shaper omits a missed view (D-009), on the app's copy.
+
+    ``instance_payload(include_missed=False)`` is what the snapshot
+    route shapes every child's instances with; exercised here on the
+    SAME core copy the app uses (the two-copy caveat makes this a
+    distinct object from the conftest-stubbed copy's identical source).
+    """
+    missed_view = core_snapshot.QuestInstanceView(
+        instance_id=999,
+        definition_id=1,
+        child_id=1,
+        title="Stale chore",
+        icon=None,
+        window="morning",
+        due_date="2026-09-21",
+        due_time="09:00",
+        state="missed",
+        overdue=False,
+        completed_at=None,
+        was_on_time=None,
+    )
+    assert core_snapshot.instance_payload(
+        [missed_view], include_missed=False
+    ) == []
+
+
+# --- route documentation -------------------------------------------------
+
+
+async def test_snapshot_route_is_documented(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """The snapshot route and its response shape are in the OpenAPI doc."""
+    response = await panel_client.get("/openapi.json")
+    assert response.status_code == 200
+    schema = response.json()
+    assert "/api/v1/panel/snapshot" in schema["paths"]
+    assert "get" in schema["paths"]["/api/v1/panel/snapshot"]
+    documented = {
+        model["title"]
+        for model in schema["components"]["schemas"].values()
+    }
+    assert "PanelSnapshotResponse" in documented
+    assert "PanelChildPayload" in documented
+    assert "PanelInstancePayload" in documented
+
+
+# --- complete route -------------------------------------------------------
+
+
+async def test_complete_writes_panel_completion(
+    seeded_panel: SimpleNamespace,
+) -> None:
+    """The first POST completes the instance as the tapped profile.
+
+    Returns success; the completion event recorded is
+    ``actor_source='panel'`` with the tapped ``actor_child_id`` and NO
+    ``actor_user_id`` (the panel actor contract), and the instance's
+    derived state becomes ``done``.
+    """
+    seed = seeded_panel.seed
+    response = await seeded_panel.client.post(
+        f"/api/v1/panel/instances/{seed.pack_bag_instance.id}/complete",
+        headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+        json={"actor_child_id": seed.ada.id},
+    )
+    assert response.status_code == 200
+    assert response.json() == {"status": "done"}
+
+    # Assert the recorded event and derived state through the SAME core
+    # copy the app uses (two-copy caveat: never mix copies), against the
+    # app's live connection.
+    events = await _events_for_instance(
+        seeded_panel.database, seed.pack_bag_instance.id
+    )
+    assert len(events) == 1
+    event = events[0]
+    assert event.event_type == "completed"
+    assert event.actor_source == "panel"
+    assert event.actor_child_id == seed.ada.id
+    assert event.actor_user_id is None
+
+    instance = await _dao_instances.QuestInstancesDao(
+        seeded_panel.database
+    ).get_by_id(seed.pack_bag_instance.id)
+    assert await _derived_state(
+        seeded_panel.database, instance, seeded_panel.today
+    ) == "done"
+
+
+async def test_complete_is_idempotent(
+    seeded_panel: SimpleNamespace,
+) -> None:
+    """A second call is a no-op that still returns success.
+
+    The core completion layer's ``appended`` flag decides: the repeat
+    call appends nothing, so exactly ONE completion event row exists
+    after two calls.
+    """
+    seed = seeded_panel.seed
+    headers = {"Authorization": f"Bearer {PANEL_TOKEN}"}
+    url = f"/api/v1/panel/instances/{seed.pack_bag_instance.id}/complete"
+    body = {"actor_child_id": seed.ada.id}
+    first = await seeded_panel.client.post(url, headers=headers, json=body)
+    assert first.status_code == 200
+    second = await seeded_panel.client.post(url, headers=headers, json=body)
+    assert second.status_code == 200
+    assert second.json() == {"status": "done"}
+
+    events = await _events_for_instance(
+        seeded_panel.database, seed.pack_bag_instance.id
+    )
+    assert len(events) == 1, (
+        "the idempotent call must not append a second event"
+    )
+
+
+async def test_complete_unknown_instance_is_not_found(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """Completing a non-existent instance returns 404."""
+    response = await panel_client.post(
+        "/api/v1/panel/instances/999999/complete",
+        headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+        json={"actor_child_id": 1},
+    )
+    assert response.status_code == 404
+
+
+async def test_complete_without_token_is_unauthorized(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """A complete request with no Authorization header returns 401."""
+    response = await panel_client.post(
+        "/api/v1/panel/instances/1/complete",
+        json={"actor_child_id": 1},
+    )
+    assert response.status_code == 401
+
+
+async def test_complete_wrong_child_is_not_found(
+    seeded_panel: SimpleNamespace,
+) -> None:
+    """Tapping the wrong child's profile answers 404, not success.
+
+    ``complete_instance`` does not itself check that the tapped
+    ``actor_child_id`` is the child the instance belongs to; the route
+    guards it so a wrong-profile tap can never complete another
+    child's quest.
+    """
+    seed = seeded_panel.seed
+    response = await seeded_panel.client.post(
+        f"/api/v1/panel/instances/{seed.pack_bag_instance.id}/complete",
+        headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+        json={"actor_child_id": seed.bo.id},
+    )
+    assert response.status_code == 404
+    # And nothing was completed.
+    events = await _events_for_instance(
+        seeded_panel.database, seed.pack_bag_instance.id
+    )
+    assert events == []
+
+
+async def test_complete_route_is_documented(
+    panel_client: httpx.AsyncClient,
+) -> None:
+    """The complete route and its request shape are in the OpenAPI doc."""
+    response = await panel_client.get("/openapi.json")
+    assert response.status_code == 200
+    schema = response.json()
+    path = "/api/v1/panel/instances/{instance_id}/complete"
+    assert path in schema["paths"]
+    assert "post" in schema["paths"][path]
+    documented = {
+        model["title"]
+        for model in schema["components"]["schemas"].values()
+    }
+    assert "PanelCompleteRequest" in documented

tests/test_api_sse.py

@@ -0,0 +1,456 @@
+"""SSE endpoint tests: the panel event stream (task 4d7bae00).
+
+These tests exercise ``GET /api/v1/panel/events`` — the panel plane's
+Server-Sent Events stream — against a REAL server:
+
+- The stream requires the panel service token (D-012): no/wrong token
+  returns 401 (the router-level shared dependency, no second check).
+- The response is ``text/event-stream`` and each transition arrives as
+  an ``event: <type>`` / ``data: <json>`` frame.
+- Completing an instance through the panel complete route publishes
+  the ``nestquest_quest_completed`` transition carrying the documented
+  payload fields (design/ENTITIES-AND-SERVICES.md §3).
+- A no-op re-complete publishes nothing (no second completed event).
+
+Streaming approach (documented): httpx's ASGITransport BUFFERS the
+whole response body before returning, so an endless SSE stream hangs
+it — exactly the awkward case this task anticipated.  These tests
+therefore run the app with uvicorn on an ephemeral port (port 0, so
+the OS picks a free one) in a daemon thread, and httpx streams from
+``http://127.0.0.1:<port>``.  Every read is bounded by a timeout so a
+wedged stream fails an assertion instead of hanging the suite; the
+server is shut down in the fixture's finally block.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import importlib
+import json
+import socket
+import threading
+import time
+from pathlib import Path
+from types import SimpleNamespace
+from zoneinfo import ZoneInfo
+
+import httpx
+import pytest
+import uvicorn
+
+from api import routes_panel
+from api.app import create_app
+from api.config import ApiConfig
+from tests.test_api_panel import PANEL_TOKEN, _seed_household
+
+#: The documented quest-completed event name (core const, §3).
+_core_const = importlib.import_module("nestquest_core.const")
+EVENT_QUEST_COMPLETED = _core_const.EVENT_QUEST_COMPLETED
+EVENT_QUEST_UNCOMPLETED = _core_const.EVENT_QUEST_UNCOMPLETED
+EVENT_QUEST_MISSED = _core_const.EVENT_QUEST_MISSED
+EVENT_CHILD_DAY_COMPLETE = _core_const.EVENT_CHILD_DAY_COMPLETE
+
+#: Upper bound for any single stream read; bounds the whole test so a
+#: wedged stream fails the assertion instead of hanging the suite.
+READ_TIMEOUT = 5.0
+
+
+def _free_port() -> int:
+    """Ask the OS for one free TCP port (bound then released)."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+class _Server:
+    """Run the app with uvicorn on an ephemeral port, in a thread.
+
+    ``create_app`` runs INSIDE the server thread (uvicorn's factory
+    mode), so the lifespan — including ``app.state.publisher`` — is
+    set up per test on the server's own event loop.  Daemon thread +
+    explicit ``should_exit`` shutdown in the fixture's finally block.
+    """
+
+    def __init__(self, db_path: str) -> None:
+        self.port = _free_port()
+        self._server_loop: asyncio.AbstractEventLoop | None = None
+        self._server = uvicorn.Server(
+            uvicorn.Config(
+                # A closure factory that captures the app's event loop
+                # as it is created INSIDE the server thread: the
+                # lifespan's database and publisher belong to that
+                # thread's loop, so tests driving an API-side
+                # transition helper directly schedule it there.
+                self._make_app_factory(db_path),
+                host="127.0.0.1",
+                port=self.port,
+                log_level="warning",
+            )
+        )
+        self._thread = threading.Thread(
+            target=self._server.run, daemon=True
+        )
+
+    def _make_app_factory(self, db_path: str):
+        """The uvicorn app factory, closing over ``db_path``.
+
+        Records the running loop the first time uvicorn calls it (in
+        the server thread) so :meth:`run_on_loop` can target it.
+        """
+
+        def factory():
+            app = create_app(
+                ApiConfig(db_path=db_path, panel_token=PANEL_TOKEN)
+            )
+            self._server_loop = asyncio.get_running_loop()
+            self.app = app
+            return app
+
+        return factory
+
+    def __enter__(self) -> "_Server":
+        self._thread.start()
+        deadline = time.monotonic() + READ_TIMEOUT
+        while not self._server.started:
+            if time.monotonic() > deadline or not self._thread.is_alive():
+                raise RuntimeError("uvicorn did not start")
+            time.sleep(0.01)
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self._server.should_exit = True
+        self._thread.join(timeout=READ_TIMEOUT)
+
+    def url(self, path: str) -> str:
+        """The full URL for ``path`` on this server."""
+        return f"http://127.0.0.1:{self.port}{path}"
+
+    def run_on_loop(self, coro) -> None:
+        """Run ``coro`` on the SERVER's event loop and wait for it.
+
+        The app (its database and publisher) lives on the uvicorn
+        thread's loop, so a test that drives an API-side transition
+        helper directly must schedule it there: the helper awaits core
+        DAO calls and calls ``publisher.publish`` synchronously, and
+        both must run on the loop that owns them.  Bounded by
+        READ_TIMEOUT so a wedged schedule fails instead of hanging.
+        """
+        return asyncio.run_coroutine_threadsafe(
+            coro, self._server_loop
+        ).result(timeout=READ_TIMEOUT)
+
+
+class _EventStream:
+    """A subscribed SSE reader over a live httpx connection.
+
+    Parses frames (``event:``/``data:`` pairs) into
+    ``(event_type, payload)`` tuples; ``next_event`` awaits the next
+    parsed frame with a timeout.
+    """
+
+    def __init__(self) -> None:
+        self.queue: asyncio.Queue = asyncio.Queue()
+        self._task: asyncio.Task | None = None
+        self._client: httpx.AsyncClient | None = None
+        self._stream_cm = None
+        self._response: httpx.Response | None = None
+
+    async def __aenter__(self) -> "_EventStream":
+        self._client = httpx.AsyncClient(timeout=READ_TIMEOUT)
+        self._stream_cm = self._client.stream(
+            "GET",
+            self.url,
+            headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+        )
+        self._response = await self._stream_cm.__aenter__()
+        assert self._response.status_code == 200
+        assert self._response.headers["content-type"].startswith(
+            "text/event-stream"
+        )
+        self._task = asyncio.create_task(self._pump())
+        return self
+
+    def _set_url(self, url: str) -> "_EventStream":
+        """Record the stream URL (called before ``__aenter__``)."""
+        self.url = url
+        return self
+
+    async def _pump(self) -> None:
+        """Read the stream and push parsed frames onto the queue."""
+        event_type: str | None = None
+        data_lines: list[str] = []
+        try:
+            async for chunk in self._response.aiter_text():
+                for line in chunk.splitlines():
+                    if line.startswith("event:"):
+                        event_type = line[len("event:"):].strip()
+                    elif line.startswith("data:"):
+                        data_lines.append(line[len("data:"):].strip())
+                    elif not line and event_type is not None:
+                        payload = json.loads("\n".join(data_lines))
+                        await self.queue.put((event_type, payload))
+                        event_type = None
+                        data_lines = []
+        except Exception as error:  # pragma: no cover - teardown path
+            await self.queue.put(error)
+
+    async def next_event(self) -> tuple[str, dict]:
+        """The next parsed ``(event_type, payload)``, with a timeout."""
+        item = await asyncio.wait_for(
+            self.queue.get(), timeout=READ_TIMEOUT
+        )
+        if isinstance(item, Exception):
+            raise item
+        return item
+
+    async def __aexit__(self, *exc) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        await self._stream_cm.__aexit__(*exc)
+        await self._client.__aexit__(*exc)
+
+
+@pytest.fixture
+def temp_db_path(tmp_path: Path) -> str:
+    """A fresh per-test SQLite path under pytest's tmp_path."""
+    return str(tmp_path / "nestquest.db")
+
+
+@pytest.fixture
+async def seeded_panel(temp_db_path: str) -> SimpleNamespace:
+    """A seeded household served by a live uvicorn app, clock pinned.
+
+    Same pinning discipline as the panel tests (12:00 UTC, past Ada's
+    10:00 due, before Bo's 17:00): the route's ``_local_now`` is
+    patched so the completion's ``was_on_time`` is deterministic.  The
+    app is created inside uvicorn's factory, so the patch must happen
+    BEFORE the server starts.
+    """
+    today = datetime.datetime.now().astimezone().date()
+    pinned_now = datetime.datetime(
+        today.year, today.month, today.day, 12, 0, 0, tzinfo=ZoneInfo("UTC")
+    )
+    seed = await _seed_household(temp_db_path, today, pinned_now)
+    # The app is created inside uvicorn's factory (in the server
+    # thread), so the patch must be applied BEFORE the server starts.
+    original = routes_panel._local_now
+    routes_panel._local_now = lambda: pinned_now
+    try:
+        with _Server(temp_db_path) as server:
+            client = httpx.AsyncClient(base_url=server.url(""))
+            async with client:
+                yield SimpleNamespace(
+                    client=client,
+                    seed=seed,
+                    server=server,
+                    url=server.url,
+                )
+    finally:
+        routes_panel._local_now = original
+
+
+def _stream(url: str) -> _EventStream:
+    """A subscribed SSE reader for ``url``."""
+    return _EventStream()._set_url(url)
+
+
+# --- auth and content type ----------------------------------------------
+
+
+async def test_events_requires_panel_token(seeded_panel) -> None:
+    """The SSE route inherits the router's token check (no second one)."""
+    response = await seeded_panel.client.get("/api/v1/panel/events")
+    assert response.status_code == 401
+
+
+# --- the quest-completed transition --------------------------------------
+
+
+async def test_complete_publishes_quest_completed_event(
+    seeded_panel,
+) -> None:
+    """A panel completion emits the documented completed transition.
+
+    The stream is subscribed FIRST, the instance is completed through
+    the panel route, and the emitted frame's type and every documented
+    payload field (child_id, child_name, instance_id, quest_title,
+    window, due_date, due_time, occurred_at, was_on_time) are asserted.
+    """
+    seed = seeded_panel.seed
+    pack_bag = seed.pack_bag_instance
+    stream = _stream(seeded_panel.url("/api/v1/panel/events"))
+    async with stream:
+        response = await seeded_panel.client.post(
+            f"/api/v1/panel/instances/{pack_bag.id}/complete",
+            headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+            json={"actor_child_id": seed.ada.id},
+        )
+        assert response.status_code == 200
+
+        event_type, payload = await stream.next_event()
+        assert event_type == EVENT_QUEST_COMPLETED
+        assert event_type == "nestquest_quest_completed"
+        assert payload["child_id"] == seed.ada.id
+        assert payload["child_name"] == "Ada"
+        assert payload["instance_id"] == pack_bag.id
+        assert payload["quest_title"] == "Pack bag"
+        assert payload["window"] == "morning"
+        assert payload["due_date"] == pack_bag.due_date
+        assert payload["due_time"] == "10:00"
+        assert payload["occurred_at"]  # strict UTC ISO-8601 stamp
+        assert payload["was_on_time"] is False  # 10:00 due, 12:00 now
+
+
+async def test_no_op_recomplete_publishes_nothing(seeded_panel) -> None:
+    """A second complete call emits NO second completed event.
+
+    After the first (real) transition, a re-complete is a no-op in the
+    core layer; the stream must stay silent.
+    """
+    seed = seeded_panel.seed
+    url = f"/api/v1/panel/instances/{seed.pack_bag_instance.id}/complete"
+    body = {"actor_child_id": seed.ada.id}
+    headers = {"Authorization": f"Bearer {PANEL_TOKEN}"}
+    stream = _stream(seeded_panel.url("/api/v1/panel/events"))
+    async with stream:
+        first = await seeded_panel.client.post(url, headers=headers, json=body)
+        assert first.status_code == 200
+        event_type, _ = await stream.next_event()
+        assert event_type == EVENT_QUEST_COMPLETED
+        # Ada's only quest today: the completion also clears her whole
+        # day, so the day-complete event follows (task 44c93cfd).
+        event_type, _ = await stream.next_event()
+        assert event_type == EVENT_CHILD_DAY_COMPLETE
+
+        second = await seeded_panel.client.post(
+            url, headers=headers, json=body
+        )
+        assert second.status_code == 200
+        with pytest.raises(asyncio.TimeoutError):
+            # Nothing arrives within the window: the no-op re-complete
+            # must publish nothing.
+            await asyncio.wait_for(stream.queue.get(), timeout=0.3)
+
+
+# --- the remaining documented transitions (task 44c93cfd) -----------------
+
+
+async def test_publish_quest_uncompleted_streams_event(seeded_panel) -> None:
+    """The reusable uncompleted publisher streams the documented
+    uncompleted transition with its documented payload fields.
+
+    The admin uncomplete route does not exist yet (deferred to task
+    da0226b3); the test drives the API-side helper the route will call.
+    The helper runs on the SERVER's event loop (``run_coroutine_threadsafe``
+    on the uvicorn thread's loop) against the app's own live database,
+    exactly the way the later route handler will call it.
+    """
+    from api import transitions
+
+    seed = seeded_panel.seed
+    pack_bag = seed.pack_bag_instance
+    app = seeded_panel.server.app
+    database = app.state.db.database
+    stream = _stream(seeded_panel.url("/api/v1/panel/events"))
+    async with stream:
+        seeded_panel.server.run_on_loop(
+            transitions.publish_quest_uncompleted(
+                database, pack_bag.id, app.state.publisher
+            )
+        )
+        event_type, payload = await stream.next_event()
+    assert event_type == EVENT_QUEST_UNCOMPLETED
+    assert event_type == "nestquest_quest_uncompleted"
+    assert payload["child_id"] == seed.ada.id
+    assert payload["child_name"] == "Ada"
+    assert payload["instance_id"] == pack_bag.id
+    assert payload["quest_title"] == "Pack bag"
+    assert payload["window"] == "morning"
+    assert payload["due_date"] == pack_bag.due_date
+    assert payload["due_time"] == "10:00"
+    assert payload["occurred_at"]
+    assert "was_on_time" not in payload
+
+
+async def test_last_quest_of_day_publishes_day_complete(seeded_panel) -> None:
+    """Completing the child's LAST open quest of the day emits the
+    completed event AND the child-day-complete event carrying
+    ``quests_due`` and ``quests_completed``.
+
+    Ada has exactly one instance today (Pack bag), so completing it
+    clears her whole day; a no-op re-complete afterwards publishes
+    nothing.
+    """
+    seed = seeded_panel.seed
+    pack_bag = seed.pack_bag_instance
+    stream = _stream(seeded_panel.url("/api/v1/panel/events"))
+    async with stream:
+        response = await seeded_panel.client.post(
+            f"/api/v1/panel/instances/{pack_bag.id}/complete",
+            headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+            json={"actor_child_id": seed.ada.id},
+        )
+        assert response.status_code == 200
+
+        event_type, payload = await stream.next_event()
+        assert event_type == EVENT_QUEST_COMPLETED
+        completed_occurred_at = payload["occurred_at"]
+        event_type, payload = await stream.next_event()
+        assert event_type == EVENT_CHILD_DAY_COMPLETE
+        assert event_type == "nestquest_child_day_complete"
+        assert payload["child_id"] == seed.ada.id
+        assert payload["child_name"] == "Ada"
+        assert payload["quests_due"] == 1
+        assert payload["quests_completed"] == 1
+        # One transition, one shared timestamp (the core builder
+        # reuses the completed event's stamp).
+        assert payload["occurred_at"] == completed_occurred_at
+
+        # No-op re-complete: nothing further on the stream.
+        second = await seeded_panel.client.post(
+            f"/api/v1/panel/instances/{pack_bag.id}/complete",
+            headers={"Authorization": f"Bearer {PANEL_TOKEN}"},
+            json={"actor_child_id": seed.ada.id},
+        )
+        assert second.status_code == 200
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(stream.queue.get(), timeout=0.3)
+
+
+async def test_publish_quest_missed_streams_event(seeded_panel) -> None:
+    """The reusable missed publisher streams the documented missed
+    transition with its documented payload fields (the sweep payload).
+
+    The API-side missed sweep does not exist yet at this queue
+    position; the test drives the API-side helper the sweep will call
+    against the seeded past-due open instance, on the server's own
+    event loop and database.
+    """
+    from api import transitions
+
+    seed = seeded_panel.seed
+    stale = seed.stale_instance
+    app = seeded_panel.server.app
+    database = app.state.db.database
+    stream = _stream(seeded_panel.url("/api/v1/panel/events"))
+    async with stream:
+        seeded_panel.server.run_on_loop(
+            transitions.publish_quest_missed(
+                database, stale.id, app.state.publisher
+            )
+        )
+        event_type, payload = await stream.next_event()
+    assert event_type == EVENT_QUEST_MISSED
+    assert event_type == "nestquest_quest_missed"
+    assert payload["child_id"] == seed.ada.id
+    assert payload["child_name"] == "Ada"
+    assert payload["instance_id"] == stale.id
+    assert payload["quest_title"] == "Stale chore"
+    assert payload["window"] == "morning"
+    assert payload["due_date"] == stale.due_date
+    assert payload["due_time"] == "09:00"
+    assert payload["occurred_at"]

tests/test_children_registry.py

@@ -141,7 +141,7 @@ def test_create_child_duplicate_name_allowed_and_warned(
     async def _body(database):
         first = await create_child(database, "Ada")
         with caplog.at_level(
-            logging.WARNING, logger="custom_components.nestquest.children"
+            logging.WARNING, logger="custom_components.nestquest.core.children"
         ):
             second = await create_child(database, "  ADA ")
         # Whitespace/case-normalised duplicate: allowed, both rows exist.
@@ -365,7 +365,7 @@ def test_create_child_concurrent_same_name_still_warns(tmp_path) -> None:
         try:
             await apply_migrations(database)
             logger = logging.getLogger(
-                "custom_components.nestquest.children"
+                "custom_components.nestquest.core.children"
             )
             seen: list[logging.LogRecord] = []
 

tests/test_core_isolation.py

@@ -4,9 +4,10 @@ Every module under ``custom_components/nestquest/core/`` must be free of
 Home Assistant and must not climb out of the core package: no
 ``homeassistant`` import, no relative import with level > 1, no absolute
 import of ``custom_components.nestquest.<something other than core>``,
-and no bare ``import core`` / ``from core``.  This guards the
-storage-layer extraction (task d0b691d8) from regressing into a
-HA-coupled or integration-coupled bundle.
+and no bare ``import core`` / ``from core``.  This guards the whole
+core package — the storage-layer extraction (task d0b691d8) and the
+engines/business-layer extraction (task 510c1f78) — from regressing
+into a HA-coupled or integration-coupled bundle.
 """
 from __future__ import annotations
 

tests/test_core_no_ha_smoke.py

@@ -0,0 +1,230 @@
+"""No-HA end-to-end smoke test (task 628473ad).
+
+The bundled core package (``custom_components.nestquest.core``) is
+self-contained and Home-Assistant-free, but the parent integration
+package ``custom_components.nestquest`` is NOT: its ``__init__.py``
+imports ``homeassistant``.  A genuine "core runs with no Home
+Assistant installed" proof therefore cannot live inside the suite
+process — the suite's ``conftest.py`` installs mock ``homeassistant``
+modules globally before any test imports the integration, so an
+in-process exercise can never distinguish "core never touched HA"
+from "conftest already stubbed HA for us".
+
+This module runs the smoke test in a SUBPROCESS (``sys.executable -c
+<script>``) that starts with a clean ``sys.modules`` and no
+``homeassistant`` installed.  The subprocess script:
+
+- asserts ``homeassistant`` is NOT in ``sys.modules`` before importing
+  core;
+- installs a STUB parent package ``custom_components.nestquest`` (a
+  bare :class:`types.ModuleType` whose ``__path__`` points at the real
+  ``custom_components/nestquest`` directory) into ``sys.modules``
+  WITHOUT executing its ``__init__.py`` — so importing
+  ``custom_components.nestquest.core.<x>`` resolves the real core
+  subpackage without dragging the integration's HA imports along;
+- installs a ``custom_components`` namespace entry too, so the
+  subpackage resolves;
+- imports the core modules (db, migrations, children,
+  quest_definitions, materialize, completion, recurrence);
+- asserts ``homeassistant`` is STILL not in ``sys.modules`` after
+  those imports;
+- opens a FRESH SQLite file, applies migrations, creates two children
+  and one quest definition (a daily recurrence rule with a start date
+  and one ``morning`` window), runs :func:`materialize` over a 28-day
+  window, completes one instance via :func:`complete_instance`
+  (``actor_source='panel'``), and derives the instance state via
+  :func:`instance_state`, asserting it is ``done``;
+- prints a clear success marker.
+
+The pytest test asserts the subprocess exit code is 0 and the marker
+is printed, and fails with the subprocess stderr otherwise.  This
+guards the storage/engines/business extraction (tasks d0b691d8 /
+510c1f78 / 4dd8f870) from regressing into a HA-coupled bundle: the
+moment a core module grows a ``homeassistant`` import (direct or via
+the parent package's ``__init__``), this test fails in a process
+where HA is genuinely absent.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+#: The marker the subprocess prints on success.  Kept short and unique
+#: so the parent test can assert it survived intact in stdout.
+SUCCESS_MARKER = "NO-HA SMOKE TEST OK"
+
+#: The repo root, so the subprocess can locate the real
+#: ``custom_components/nestquest`` directory regardless of its own
+#: working directory.
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+
+#: The smoke-test script, run with ``sys.executable -c``.  It is a
+#: real no-HA process: the suite's conftest stubs do not exist here,
+#: and ``homeassistant`` is not installed in this venv, so any core
+#: import of HA (direct or via the parent package ``__init__``) raises
+#: ``ModuleNotFoundError`` and the subprocess exits non-zero.
+_SCRIPT = textwrap.dedent(
+    """\
+    import asyncio
+    import datetime
+    import sys
+    import tempfile
+    import types
+    from pathlib import Path
+
+    REPO_ROOT = Path(sys.argv[1])
+    CC_PATH = REPO_ROOT / "custom_components"
+    NQ_PATH = CC_PATH / "nestquest"
+
+    # 1. homeassistant must not be imported before we touch core.
+    assert "homeassistant" not in sys.modules, (
+        "homeassistant already in sys.modules before core import — "
+        "the subprocess is not a clean no-HA process"
+    )
+
+    # 2. Stub the parent packages WITHOUT running their __init__.py.
+    #    custom_components is a namespace package; nestquest's __init__
+    #    imports homeassistant, so we install a bare ModuleType whose
+    #    __path__ points at the real directory instead of executing it.
+    cc = types.ModuleType("custom_components")
+    cc.__path__ = [str(CC_PATH)]
+    sys.modules["custom_components"] = cc
+
+    nq = types.ModuleType("custom_components.nestquest")
+    nq.__path__ = [str(NQ_PATH)]
+    nq.__package__ = "custom_components.nestquest"
+    sys.modules["custom_components.nestquest"] = nq
+    cc.nestquest = nq
+
+    # 3. Import the core modules directly from the bundle.
+    from custom_components.nestquest.core.db import NestQuestDatabase
+    from custom_components.nestquest.core.migrations import apply_migrations
+    from custom_components.nestquest.core.children import create_child
+    from custom_components.nestquest.core.quest_definitions import (
+        create_quest_definition,
+    )
+    from custom_components.nestquest.core.materialize import materialize
+    from custom_components.nestquest.core.completion import (
+        complete_instance,
+        instance_state,
+    )
+    from custom_components.nestquest.core.recurrence import (
+        RuleType,
+        ScheduleRule,
+    )
+    from custom_components.nestquest.core.dao_instances import (
+        QuestInstancesDao,
+    )
+
+    # 4. core must not have pulled in homeassistant.
+    assert "homeassistant" not in sys.modules, (
+        "homeassistant imported by core — the core bundle is no longer "
+        "Home-Assistant-free"
+    )
+
+
+    async def _executor(fn, *args, **kwargs):
+        return await asyncio.to_thread(fn, *args, **kwargs)
+
+
+    async def main() -> None:
+        db_path = Path(tempfile.mkdtemp(prefix="nq-noha-smoke-")) / "nestquest.db"
+        database = NestQuestDatabase(_executor)
+        await database.open(str(db_path))
+        try:
+            await apply_migrations(database)
+
+            # Two children.
+            child_a = await create_child(database, "Ada")
+            child_b = await create_child(database, "Bee")
+
+            # One quest definition: daily recurrence, one morning window.
+            today = datetime.date.today()
+            start_iso = today.isoformat()
+            rule = ScheduleRule(
+                rule_type=RuleType.DAILY, interval=1, start_date=start_iso
+            )
+            created = await create_quest_definition(
+                database,
+                "Brush teeth",
+                rule,
+                [child_a.id, child_b.id],
+                ["morning"],
+            )
+            assert created.definition.id is not None
+
+            # Materialize over a 28-day window (inclusive of both ends).
+            end_iso = (today + datetime.timedelta(days=27)).isoformat()
+            count = await materialize(database, start_iso, end_iso, today=today)
+            assert count > 0, (
+                f"materialize produced no instances over the 28-day "
+                f"window (count={count})"
+            )
+
+            # Complete one instance for child_a on the start date.
+            instances = QuestInstancesDao(database)
+            rows = await instances.list_by_child_and_date(
+                child_a.id, start_iso
+            )
+            assert rows, (
+                "no materialized instance for child_a on the start date"
+            )
+            instance = rows[0]
+
+            result = await complete_instance(
+                database,
+                instance.id,
+                actor_source="panel",
+                actor_child_id=child_a.id,
+                today=today,
+            )
+            assert result == "done", (
+                f"complete_instance returned {result!r}, expected 'done'"
+            )
+
+            state = await instance_state(database, instance.id, today=today)
+            assert state == "done", (
+                f"instance_state returned {state!r}, expected 'done'"
+            )
+        finally:
+            await database.close()
+
+        print("NO-HA SMOKE TEST OK")
+
+
+    asyncio.run(main())
+    """
+)
+
+
+def test_core_runs_end_to_end_without_homeassistant() -> None:
+    """Run the no-HA smoke test in a subprocess and assert its marker.
+
+    The subprocess is a genuine no-HA process: the suite's conftest
+    stubs are not present there, and ``homeassistant`` is not installed
+    in this venv.  If any core module ever grows a ``homeassistant``
+    import (directly or via the parent package ``__init__``), the
+    subprocess exits non-zero with a ``ModuleNotFoundError`` and this
+    test fails with the subprocess's stderr.
+    """
+    result = subprocess.run(
+        [sys.executable, "-c", _SCRIPT, str(_REPO_ROOT)],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    if result.returncode != 0:
+        raise AssertionError(
+            f"no-HA smoke subprocess exited {result.returncode}.\n"
+            f"--- stdout ---\n{result.stdout}\n"
+            f"--- stderr ---\n{result.stderr}"
+        )
+    assert SUCCESS_MARKER in result.stdout, (
+        f"success marker {SUCCESS_MARKER!r} not printed by subprocess.\n"
+        f"--- stdout ---\n{result.stdout}\n"
+        f"--- stderr ---\n{result.stderr}"
+    )

tests/test_core_settings.py

@@ -0,0 +1,912 @@
+"""Tests for core/settings.py: the explicit, HA-free settings object.
+
+Covers the contracts from task 4dd8f870 plus the review fixes:
+
+- ``NestQuestSettings.from_options`` applies defaults when keys are
+  absent and rejects invalid horizon/rollover values; ``from_options``
+  is strict (raises), while ``from_options_resilient`` falls back PER
+  FIELD so a malformed sibling cannot reset horizon_days/rollover.
+- An AST scan asserts no module under
+  ``custom_components/nestquest/core/`` imports ``homeassistant``,
+  names ``hass``/``config_entry``, reads a ``.config``/``.options``/
+  ``.data`` attribute, or dynamically reads them via ``getattr``/
+  ``hasattr``.  (Docstring mentions are allowed.)  A negative-control
+  test feeds the scanner each bypass shape and asserts it flags them.
+- A settings object constructed with NON-default ``horizon_days`` and
+  ``day_rollover_time`` drives a materialization whose resulting window
+  matches the non-default horizon — via BOTH the core ``materialize``
+  path and the INTEGRATION path (``_run_horizon_materialization`` +
+  ``_register_day_rollover_listener``).
+"""
+from __future__ import annotations
+
+import ast
+import datetime
+from dataclasses import FrozenInstanceError
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+import custom_components.nestquest.core as _core_mod
+from conftest import freeze_nestquest_clock
+
+from custom_components.nestquest.const import (
+    CONF_AFTERNOON_REMINDER_ENABLED,
+    CONF_AFTERNOON_REMINDER_TIME,
+    CONF_CELEBRATION_ENABLED,
+    CONF_DAY_ROLLOVER_TIME,
+    CONF_END_OF_DAY_REPORT_ENABLED,
+    CONF_END_OF_DAY_REPORT_TIME,
+    CONF_HORIZON_DAYS,
+    CONF_MORNING_SUMMARY_ENABLED,
+    CONF_MORNING_SUMMARY_TIME,
+    CONF_NOTIFY_TARGET,
+    DEFAULT_AFTERNOON_REMINDER_TIME,
+    DEFAULT_AUTOMATION_ENABLED,
+    DEFAULT_DAY_ROLLOVER_TIME,
+    DEFAULT_END_OF_DAY_REPORT_TIME,
+    DEFAULT_HORIZON_DAYS,
+    DEFAULT_MORNING_SUMMARY_TIME,
+)
+from custom_components.nestquest.core.settings import NestQuestSettings
+
+
+# ---------------------------------------------------------------------------
+# from_options: defaults + validation.
+# ---------------------------------------------------------------------------
+
+
+def test_from_options_none_yields_all_defaults() -> None:
+    """A None mapping yields a settings object with every default applied."""
+    s = NestQuestSettings.from_options(None)
+    assert s.horizon_days == DEFAULT_HORIZON_DAYS
+    assert s.day_rollover_time == DEFAULT_DAY_ROLLOVER_TIME
+    assert s.notify_target == ""
+    assert s.morning_summary_time == DEFAULT_MORNING_SUMMARY_TIME
+    assert s.afternoon_reminder_time == DEFAULT_AFTERNOON_REMINDER_TIME
+    assert s.end_of_day_report_time == DEFAULT_END_OF_DAY_REPORT_TIME
+    assert s.morning_summary_enabled is DEFAULT_AUTOMATION_ENABLED
+    assert s.afternoon_reminder_enabled is DEFAULT_AUTOMATION_ENABLED
+    assert s.end_of_day_report_enabled is DEFAULT_AUTOMATION_ENABLED
+    assert s.celebration_enabled is DEFAULT_AUTOMATION_ENABLED
+
+
+def test_from_options_empty_mapping_yields_all_defaults() -> None:
+    """An empty mapping also yields every default (the fresh-install case)."""
+    s = NestQuestSettings.from_options({})
+    assert s.horizon_days == DEFAULT_HORIZON_DAYS
+    assert s.day_rollover_time == DEFAULT_DAY_ROLLOVER_TIME
+
+
+def test_from_options_reads_keys() -> None:
+    """Each CONF_* key is read into the matching field."""
+    opts = {
+        CONF_HORIZON_DAYS: 21,
+        CONF_DAY_ROLLOVER_TIME: "03:30",
+        CONF_NOTIFY_TARGET: "notify.mobile_app_x",
+        CONF_MORNING_SUMMARY_TIME: "07:15",
+        CONF_AFTERNOON_REMINDER_TIME: "14:45",
+        CONF_END_OF_DAY_REPORT_TIME: "21:30",
+        CONF_MORNING_SUMMARY_ENABLED: False,
+        CONF_AFTERNOON_REMINDER_ENABLED: False,
+        CONF_END_OF_DAY_REPORT_ENABLED: False,
+        CONF_CELEBRATION_ENABLED: False,
+    }
+    s = NestQuestSettings.from_options(opts)
+    assert s.horizon_days == 21
+    assert s.day_rollover_time == "03:30"
+    assert s.notify_target == "notify.mobile_app_x"
+    assert s.morning_summary_time == "07:15"
+    assert s.afternoon_reminder_time == "14:45"
+    assert s.end_of_day_report_time == "21:30"
+    assert s.morning_summary_enabled is False
+    assert s.afternoon_reminder_enabled is False
+    assert s.end_of_day_report_enabled is False
+    assert s.celebration_enabled is False
+
+
+def test_from_options_does_not_mutate_caller_mapping() -> None:
+    """from_options consumes the mapping read-only."""
+    opts: dict[str, Any] = {CONF_HORIZON_DAYS: 9}
+    snapshot = dict(opts)
+    _ = NestQuestSettings.from_options(opts)
+    assert opts == snapshot
+
+
+@pytest.mark.parametrize(
+    "value",
+    [True, False, "5", 0, -3, 1.5],
+)
+def test_from_options_rejects_invalid_horizon(value: Any) -> None:
+    """A malformed horizon_days is rejected.
+
+    A key that is ABSENT (or present-but-None) falls back to the
+    default — see :func:`test_from_options_horizon_absent_falls_back_to_default`
+    and the None case below; any other invalid value raises, matching
+    the options flow's strict validation.
+    """
+    with pytest.raises(ValueError, match="horizon_days"):
+        NestQuestSettings.from_options({CONF_HORIZON_DAYS: value})
+
+
+def test_from_options_horizon_absent_falls_back_to_default() -> None:
+    """An absent (or None) horizon_days key falls back to the default."""
+    assert NestQuestSettings.from_options({}).horizon_days == DEFAULT_HORIZON_DAYS
+    assert (
+        NestQuestSettings.from_options(
+            {CONF_HORIZON_DAYS: None}
+        ).horizon_days
+        == DEFAULT_HORIZON_DAYS
+    )
+
+
+def test_from_options_horizon_validates_and_defaults() -> None:
+    """from_options returns the configured horizon, defaulting when absent/None.
+
+    A valid horizon is read; an absent or None key falls back to the
+    default; and a malformed value RAISES (the integration's
+    ``from_options_resilient`` handles the per-field fall-back at setup,
+    not this strict path).
+    """
+    assert NestQuestSettings.from_options({CONF_HORIZON_DAYS: 5}).horizon_days == 5
+    assert (
+        NestQuestSettings.from_options({}).horizon_days == DEFAULT_HORIZON_DAYS
+    )
+    assert (
+        NestQuestSettings.from_options(
+            {CONF_HORIZON_DAYS: None}
+        ).horizon_days
+        == DEFAULT_HORIZON_DAYS
+    )
+    for bad in (True, "5", 0):
+        with pytest.raises(ValueError):
+            NestQuestSettings.from_options({CONF_HORIZON_DAYS: bad})
+
+
+@pytest.mark.parametrize(
+    "value",
+    ["25:00", "00:60", "24:00", "9:5", "abc", "07:00:00", 700, ""],
+)
+def test_from_options_rejects_invalid_rollover(value: Any) -> None:
+    """A malformed day_rollover_time is rejected.
+
+    A key that is ABSENT (or present-but-None) falls back to the
+    default — a present-but-empty-string or non-HH:MM value raises,
+    matching the options flow's strict validation.
+    """
+    with pytest.raises(ValueError):
+        NestQuestSettings.from_options({CONF_DAY_ROLLOVER_TIME: value})
+
+
+def test_from_options_rollover_absent_falls_back_to_default() -> None:
+    """An absent (or None) day_rollover_time key falls back to the default."""
+    assert (
+        NestQuestSettings.from_options({}).day_rollover_time
+        == DEFAULT_DAY_ROLLOVER_TIME
+    )
+    assert (
+        NestQuestSettings.from_options(
+            {CONF_DAY_ROLLOVER_TIME: None}
+        ).day_rollover_time
+        == DEFAULT_DAY_ROLLOVER_TIME
+    )
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        CONF_MORNING_SUMMARY_TIME,
+        CONF_AFTERNOON_REMINDER_TIME,
+        CONF_END_OF_DAY_REPORT_TIME,
+    ],
+)
+def test_from_options_rejects_invalid_notification_time(key: str) -> None:
+    """The three notification times are validated as strict HH:MM."""
+    with pytest.raises(ValueError):
+        NestQuestSettings.from_options({key: "25:99"})
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        CONF_MORNING_SUMMARY_ENABLED,
+        CONF_AFTERNOON_REMINDER_ENABLED,
+        CONF_END_OF_DAY_REPORT_ENABLED,
+        CONF_CELEBRATION_ENABLED,
+    ],
+)
+def test_from_options_rejects_non_bool_toggle(key: str) -> None:
+    """Each toggle must be a real bool (no string coercion)."""
+    with pytest.raises(ValueError):
+        NestQuestSettings.from_options({key: "yes"})
+
+
+def test_from_options_rejects_non_string_notify_target() -> None:
+    """notify_target must be a string (or absent)."""
+    with pytest.raises(ValueError):
+        NestQuestSettings.from_options({CONF_NOTIFY_TARGET: 123})
+
+
+def test_from_options_strips_notify_target() -> None:
+    """A padded notify target is stripped; empty stays empty."""
+    s = NestQuestSettings.from_options({CONF_NOTIFY_TARGET: "  notify.x  "})
+    assert s.notify_target == "notify.x"
+    s_empty = NestQuestSettings.from_options({CONF_NOTIFY_TARGET: "   "})
+    assert s_empty.notify_target == ""
+
+
+# ---------------------------------------------------------------------------
+# from_options_resilient: per-field fallback.
+# ---------------------------------------------------------------------------
+
+
+def test_from_options_resilient_none_yields_all_defaults() -> None:
+    """A None mapping yields the all-defaults settings (no warnings)."""
+    s = NestQuestSettings.from_options_resilient(None)
+    assert s.horizon_days == DEFAULT_HORIZON_DAYS
+    assert s.day_rollover_time == DEFAULT_DAY_ROLLOVER_TIME
+
+
+def test_from_options_resilient_reads_valid_keys() -> None:
+    """Valid keys are read exactly as from_options would read them."""
+    s = NestQuestSettings.from_options_resilient(
+        {CONF_HORIZON_DAYS: 3, CONF_DAY_ROLLOVER_TIME: "03:30"}
+    )
+    assert s.horizon_days == 3
+    assert s.day_rollover_time == "03:30"
+
+
+def test_from_options_resilient_keeps_horizon_when_sibling_is_bad(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A malformed SIBLING field cannot reset horizon_days or day_rollover_time.
+
+    The old all-or-nothing fallback reset EVERY field when from_options
+    raised for ANY field: ``{horizon_days: 3, morning_summary_time:
+    '25:00'}`` yielded horizon 14 (was 3).  The resilient builder falls
+    back PER FIELD, so horizon_days=3 and day_rollover_time='03:30'
+    survive a malformed morning_summary_time, and the bad field alone
+    falls back to its default with a warning naming it.
+    """
+    s = NestQuestSettings.from_options_resilient(
+        {
+            CONF_HORIZON_DAYS: 3,
+            CONF_DAY_ROLLOVER_TIME: "03:30",
+            CONF_MORNING_SUMMARY_TIME: "25:00",
+        }
+    )
+    assert s.horizon_days == 3
+    assert s.day_rollover_time == "03:30"
+    # The malformed sibling fell back to its default.
+    assert s.morning_summary_time == DEFAULT_MORNING_SUMMARY_TIME
+    # A warning was logged naming the bad field.
+    assert any(
+        "morning_summary_time" in record.getMessage()
+        and record.levelname == "WARNING"
+        for record in caplog.records
+    )
+
+
+def test_from_options_resilient_bad_horizon_falls_back_with_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A malformed horizon_days itself falls back to the default + warning."""
+    s = NestQuestSettings.from_options_resilient({CONF_HORIZON_DAYS: True})
+    assert s.horizon_days == DEFAULT_HORIZON_DAYS
+    assert any(
+        "horizon_days" in record.getMessage() and record.levelname == "WARNING"
+        for record in caplog.records
+    )
+
+
+def test_from_options_resilient_bad_rollover_falls_back_with_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A malformed day_rollover_time falls back to the default + warning."""
+    s = NestQuestSettings.from_options_resilient(
+        {CONF_DAY_ROLLOVER_TIME: "99:99"}
+    )
+    assert s.day_rollover_time == DEFAULT_DAY_ROLLOVER_TIME
+    assert any(
+        "day_rollover_time" in record.getMessage()
+        and record.levelname == "WARNING"
+        for record in caplog.records
+    )
+
+
+def test_from_options_resilient_none_value_is_not_a_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A None value maps to the default silently (it is absent, not malformed)."""
+    s = NestQuestSettings.from_options_resilient(
+        {CONF_HORIZON_DAYS: None, CONF_MORNING_SUMMARY_TIME: None}
+    )
+    assert s.horizon_days == DEFAULT_HORIZON_DAYS
+    assert s.morning_summary_time == DEFAULT_MORNING_SUMMARY_TIME
+    assert not [r for r in caplog.records if r.levelname == "WARNING"]
+
+
+# ---------------------------------------------------------------------------
+# Construction + frozenness.
+# ---------------------------------------------------------------------------
+
+
+def test_direct_construction_validates() -> None:
+    """Hand-built instances validate the same way from_options does."""
+    with pytest.raises(ValueError):
+        NestQuestSettings(horizon_days=0)
+    with pytest.raises(ValueError):
+        NestQuestSettings(day_rollover_time="bad")
+    with pytest.raises(ValueError):
+        NestQuestSettings(morning_summary_enabled="yes")
+
+
+@pytest.mark.parametrize(
+    "field,kwargs",
+    [
+        ("horizon_days", {"horizon_days": None}),
+        ("day_rollover_time", {"day_rollover_time": None}),
+        ("notify_target", {"notify_target": None}),
+        ("morning_summary_time", {"morning_summary_time": None}),
+        ("afternoon_reminder_time", {"afternoon_reminder_time": None}),
+        ("end_of_day_report_time", {"end_of_day_report_time": None}),
+        ("morning_summary_enabled", {"morning_summary_enabled": None}),
+        ("afternoon_reminder_enabled", {"afternoon_reminder_enabled": None}),
+        ("end_of_day_report_enabled", {"end_of_day_report_enabled": None}),
+        ("celebration_enabled", {"celebration_enabled": None}),
+    ],
+)
+def test_direct_construction_rejects_none(field: str, kwargs: dict[str, Any]) -> None:
+    """__post_init__ is STRICT: None is rejected for every field.
+
+    The None->default mapping lives ONLY in from_options (via
+    _option_value).  A hand-built NestQuestSettings(field=None) must raise
+    in __post_init__ rather than constructing and later blowing up
+    horizon_window (timedelta(days=None) -> TypeError) or the rollover
+    listener.
+    """
+    with pytest.raises(ValueError):
+        NestQuestSettings(**kwargs)
+
+
+@pytest.mark.parametrize("value", [True, False, "5", 1.5])
+def test_direct_construction_rejects_non_int_horizon(value: Any) -> None:
+    """A bool or non-int horizon is rejected at construction (not bool-as-int)."""
+    with pytest.raises(ValueError, match="horizon_days"):
+        NestQuestSettings(horizon_days=value)
+
+
+
+def test_direct_construction_strips_notify_target() -> None:
+    """__post_init__ normalises notify_target the SAME way from_options does.
+
+    P3: a hand-built ``NestQuestSettings(notify_target=' x ')`` is
+    stripped to ``'x'`` (and a whitespace-only value to ``''``) so direct
+    construction behaves like the options flow; a padded value cannot
+    slip through __post_init__ either.
+    """
+    assert NestQuestSettings(notify_target="  notify.x  ").notify_target == "notify.x"
+    assert NestQuestSettings(notify_target="   ").notify_target == ""
+    assert NestQuestSettings(notify_target="notify.x").notify_target == "notify.x"
+
+
+def test_settings_is_frozen() -> None:
+    """The dataclass is frozen so a stale settings object cannot be mutated."""
+    s = NestQuestSettings()
+    with pytest.raises(FrozenInstanceError):
+        s.horizon_days = 99  # type: ignore[misc]
+
+
+def test_day_rollover_hour_minute() -> None:
+    """day_rollover_hour_minute returns the parsed (hour, minute)."""
+    s = NestQuestSettings(day_rollover_time="03:30")
+    assert s.day_rollover_hour_minute == (3, 30)
+    assert NestQuestSettings().day_rollover_hour_minute == (0, 0)
+
+
+# ---------------------------------------------------------------------------
+# horizon_window.
+# ---------------------------------------------------------------------------
+
+
+def test_horizon_window_pinned_today() -> None:
+    """A pinned today is honored so the window is deterministic.
+
+    ``today`` is REQUIRED (no host-clock default) — see
+    :meth:`NestQuestSettings.horizon_window`.
+    """
+    s = NestQuestSettings(horizon_days=5)
+    pinned = datetime.date(2026, 3, 1)
+    start, end = s.horizon_window(pinned)
+    assert start == pinned
+    assert end == pinned + datetime.timedelta(days=5)
+
+
+def test_horizon_window_requires_today() -> None:
+    """horizon_window has no default today: omitting it raises TypeError."""
+    s = NestQuestSettings(horizon_days=5)
+    with pytest.raises(TypeError):
+        s.horizon_window()  # type: ignore[call-arg]
+
+
+def test_horizon_window_non_default_horizon() -> None:
+    """A non-default horizon_days widens the window accordingly."""
+    pinned = datetime.date(2026, 3, 1)
+    short = NestQuestSettings(horizon_days=3).horizon_window(pinned)
+    long_ = NestQuestSettings(horizon_days=30).horizon_window(pinned)
+    assert short[1] == pinned + datetime.timedelta(days=3)
+    assert long_[1] == pinned + datetime.timedelta(days=30)
+    assert (long_[1] - short[1]).days == 27
+
+
+# ---------------------------------------------------------------------------
+# AST: no HA config reads under core/.
+# ---------------------------------------------------------------------------
+
+CORE_PKG = Path(_core_mod.__file__).parent
+
+
+def _is_homeassistant(module: str) -> bool:
+    return module == "homeassistant" or module.startswith("homeassistant.")
+
+
+#: HA-specific identifiers with no legitimate core use.  ``entry`` is
+#: deliberately NOT in this set: core uses ``entry`` as a domain loop
+#: variable (iterating weekday_set entries in recurrence/presence/
+#: quest_definitions), so forbidding the bare name would false-positive.
+#: The config-entry attribute reads the bare-name check misses are
+#: caught by _CONFIG_ATTRS and _FORBIDDEN_ATTRS below.
+_FORBIDDEN_NAMES = frozenset({"hass", "config_entry"})
+
+#: Attribute names that signal a HA object reference (self.hass,
+#: self.entry, obj.config_entry).  No core module currently uses any of
+#: these as an attribute, so flagging them is false-positive-free.
+_FORBIDDEN_ATTRS = frozenset({"hass", "entry", "config_entry"})
+
+#: Config-entry attribute reads — the shapes ``hass.config``,
+#: ``config_entry.options``, ``self.entry.options``, ``runtime.options``,
+#: ``entry.data``.  Flagging the attribute ANYWHERE (regardless of root)
+#: catches ``runtime.options``, whose root name is not a forbidden
+#: identifier.  No core module currently reads any of these attributes.
+_CONFIG_ATTRS = frozenset({"config", "options", "data"})
+
+#: Dynamic config-entry reads via getattr/hasattr with a string argument.
+_GETATTR_FUNCS = frozenset({"getattr", "hasattr"})
+
+#: The dynamic-import function the string-based import bypass uses.
+#: ``importlib.import_module("homeassistant...")`` reaches the HA package
+#: without an ``import homeassistant`` statement the static import check
+#: sees, so the scanner must recognise the call shape too.
+_IMPORT_MODULE_FUNCS = frozenset({"import_module"})
+
+
+def _is_import_module_call(node: ast.Call) -> bool:
+    """True for ``importlib.import_module(...)`` or a bare ``import_module(...)``."""
+    func = node.func
+    if isinstance(func, ast.Attribute):
+        return func.attr in _IMPORT_MODULE_FUNCS
+    if isinstance(func, ast.Name):
+        return func.id in _IMPORT_MODULE_FUNCS
+    return False
+
+
+def _scan_source_for_ha_config(
+    source: str, *, name: str = "<snippet>"
+) -> list[str]:
+    """Return offender strings for HA-coupling in ``source``.
+
+    Flags (each closes a bypass a root-only ``hass``/``entry`` chain
+    check would not catch):
+
+    - any ``import homeassistant`` / ``from homeassistant ...``;
+    - any ``importlib.import_module('homeassistant...')`` (a string-based
+      import that reaches HA without an ``import homeassistant`` statement
+      the static import check can see);
+    - any ``Name``/``arg`` whose id is ``hass`` or ``config_entry``
+      (HA-specific identifiers with no legitimate core use);
+    - any call keyword whose name is ``hass`` or ``config_entry``
+      (catches ``foo(hass=...)`` / ``handler(config_entry=...)`` — the
+      bare-Name check misses keyword arguments);
+    - any attribute access whose ``attr`` is ``hass``/``entry``/
+      ``config_entry`` (catches ``self.hass``, ``self.entry``,
+      ``obj.config_entry`` — root names a root-only check could not see);
+    - any attribute access whose ``attr`` is ``config``/``options``/
+      ``data`` — these are Home Assistant config-entry attributes with no
+      legitimate core use (``.config`` reads ``hass.config``, ``.options``
+      reads ``config_entry.options``, ``.data`` reads ``config_entry.data``);
+      flagging the attribute ANYWHERE (regardless of root) is what catches
+      ``runtime.options``, whose root name is not a forbidden identifier.
+      No core module currently reads any of these attributes;
+    - any ``getattr``/``hasattr`` call whose string argument is
+      ``'config'``/``'options'``/``'data'`` (catches the dynamic read
+      ``getattr(hass, 'config')`` the static attribute check cannot see).
+
+    Docstring mentions are structurally exempt: AST only sees code, and
+    none of these node shapes appear inside a string literal.  The
+    existing docstring references to ``hass.config`` in ``core/events.py``
+    and ``core/store.py`` therefore pass.
+    """
+    tree = ast.parse(source, filename=name)
+    offenders: list[str] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if _is_homeassistant(alias.name):
+                    offenders.append(
+                        f"{name}:{node.lineno} homeassistant import: "
+                        f"import {alias.name}"
+                    )
+        elif isinstance(node, ast.ImportFrom):
+            base = node.module or ""
+            if _is_homeassistant(base):
+                offenders.append(
+                    f"{name}:{node.lineno} homeassistant import: from {base}"
+                )
+            for alias in node.names:
+                combined = f"{base}.{alias.name}" if base else alias.name
+                if _is_homeassistant(combined):
+                    offenders.append(
+                        f"{name}:{node.lineno} homeassistant import: "
+                        f"from {base} import {alias.name}"
+                    )
+        elif isinstance(node, ast.Name):
+            if node.id in _FORBIDDEN_NAMES:
+                offenders.append(
+                    f"{name}:{node.lineno} forbidden identifier: {node.id!r}"
+                )
+        elif isinstance(node, ast.arg):
+            if node.arg in _FORBIDDEN_NAMES:
+                offenders.append(
+                    f"{name}:{node.lineno} forbidden parameter: {node.arg!r}"
+                )
+        elif isinstance(node, ast.keyword):
+            # A call keyword like ``foo(hass=...)``: the bare-Name check
+            # sees the value, not the keyword's own name, so a HA object
+            # could be passed by keyword without tripping it.  ``arg`` is
+            # ``None`` for ``**kwargs`` unpacking, which is not a name.
+            if node.arg is not None and node.arg in _FORBIDDEN_NAMES:
+                offenders.append(
+                    f"{name}:{node.lineno} forbidden keyword argument: "
+                    f"{node.arg!r}"
+                )
+        elif isinstance(node, ast.Attribute):
+            if node.attr in _FORBIDDEN_ATTRS:
+                offenders.append(
+                    f"{name}:{node.lineno} forbidden attribute: .{node.attr}"
+                )
+            if node.attr in _CONFIG_ATTRS:
+                offenders.append(
+                    f"{name}:{node.lineno} config-entry attribute read: "
+                    f".{node.attr}"
+                )
+        elif isinstance(node, ast.Call):
+            if _is_import_module_call(node):
+                # The first positional argument is the module string; a
+                # constant ``'homeassistant...'`` is the bypass shape.
+                for arg in node.args:
+                    if (
+                        isinstance(arg, ast.Constant)
+                        and isinstance(arg.value, str)
+                        and _is_homeassistant(arg.value)
+                    ):
+                        offenders.append(
+                            f"{name}:{node.lineno} dynamic homeassistant "
+                            f"import: import_module({arg.value!r})"
+                        )
+            func = node.func
+            if isinstance(func, ast.Name) and func.id in _GETATTR_FUNCS:
+                for arg in node.args:
+                    if (
+                        isinstance(arg, ast.Constant)
+                        and isinstance(arg.value, str)
+                        and arg.value in _CONFIG_ATTRS
+                    ):
+                        offenders.append(
+                            f"{name}:{node.lineno} {func.id}() dynamic "
+                            f"config-entry read: {arg.value!r}"
+                        )
+
+    return offenders
+
+
+def _scan_module_for_ha_config(path: Path) -> list[str]:
+    """Scan a core module file for HA-coupling (file-backed scan)."""
+    return _scan_source_for_ha_config(
+        path.read_text(encoding="utf-8"), name=path.name
+    )
+
+
+def test_core_modules_have_no_ha_config_reads() -> None:
+    """No core module imports homeassistant or reads HA config / entry options.
+
+    The scan forbids the HA-specific identifiers ``hass``/``config_entry``,
+    the HA-object attributes ``.hass``/``.entry``/``.config_entry``, the
+    config-entry attribute reads ``.config``/``.options``/``.data``, and
+    dynamic ``getattr``/``hasattr`` reads of them — so a chain rooted at
+    ``self`` or ``runtime`` (whose root name is not a forbidden
+    identifier) is caught.  ``.config``/``.options``/``.data`` are banned
+    because they are Home Assistant config-entry attributes with no
+    legitimate core use: core receives the resolved values via the
+    explicit :class:`NestQuestSettings` object the integration builds
+    from ``entry.options``, so any read of those attributes in ``core/``
+    is a config-entry coupling the settings object exists to remove.
+    Docstring mentions pass: AST only sees code.
+    """
+    py_files = sorted(CORE_PKG.rglob("*.py"))
+    assert py_files, "core package not found"
+    all_offenders: list[str] = []
+    for py_file in py_files:
+        all_offenders.extend(_scan_module_for_ha_config(py_file))
+    assert all_offenders == [], (
+        "core package reads HA config / entry options:\n"
+        + "\n".join(all_offenders)
+    )
+
+
+def test_ast_scan_flags_each_bypass_shape() -> None:
+    """Negative control: the scanner flags each bypass a root-only check misses.
+
+    A root-only scan flags chains rooted at a literal name ``hass``/
+    ``entry``.  Each snippet below is a shape such a scan would miss;
+    this scanner must flag every one.
+    """
+    snippets: dict[str, str] = {
+        "self.hass.config": "x = self.hass.config\n",
+        "config_entry.options": "x = config_entry.options\n",
+        "self.entry.options": "x = self.entry.options\n",
+        "getattr(hass,'config')": "x = getattr(hass, 'config')\n",
+        "runtime.options": "x = runtime.options\n",
+        "hasattr(obj,'data')": "x = hasattr(obj, 'data')\n",
+        "importlib.import_module('homeassistant')": (
+            "import importlib\nimportlib.import_module('homeassistant')\n"
+        ),
+        "import_module('homeassistant.helpers')": (
+            "from importlib import import_module\n"
+            "import_module('homeassistant.helpers')\n"
+        ),
+        "handler(hass=...)": "handler(hass=obj)\n",
+        "handler(config_entry=...)": "handler(config_entry=obj)\n",
+    }
+    for label, src in snippets.items():
+        offenders = _scan_source_for_ha_config(src, name=label)
+        assert offenders, f"scanner missed {label!r}: {src!r}"
+
+
+def test_ast_scan_allows_non_homeassistant_import_module() -> None:
+    """A dynamic import of a NON-homeassistant module is not flagged.
+
+    ``importlib.import_module`` is a legitimate way to load a non-HA
+    module lazily; only a ``homeassistant...`` target is the bypass shape.
+    """
+    src = (
+        "import importlib\n"
+        "m = importlib.import_module('custom_components.nestquest.core')\n"
+    )
+    assert _scan_source_for_ha_config(src, name="non-ha-import") == []
+
+
+def test_ast_scan_allows_non_forbidden_keyword_arguments() -> None:
+    """A call with non-forbidden keyword arguments is not flagged.
+
+    Only ``hass=``/``config_entry=`` are forbidden as keyword names; an
+    unrelated keyword like ``hass_data=`` or ``entry_id=`` must not
+    false-positive (and ``**kwargs`` unpacking has ``arg=None``).
+    """
+    src = (
+        "foo(entry_id=1, name='x')\n"
+        "bar(**kwargs)\n"
+    )
+    assert _scan_source_for_ha_config(src, name="non-forbidden-kwargs") == []
+
+
+def test_ast_scan_allows_legitimate_entry_loop_var() -> None:
+    """A bare ``entry`` loop variable (a domain concept) is NOT flagged.
+
+    ``entry`` is used in core as a loop variable over weekday_set entries
+    (recurrence.py, presence.py, quest_definitions.py) — not a HA config
+    entry.  Forbidding the bare name would false-positive on those, so
+    only ``hass``/``config_entry`` are forbidden as bare names; the
+    config-entry reads via ``entry.options``/``entry.data`` are caught by
+    the ``_CONFIG_ATTRS`` attribute check instead.
+    """
+    offenders = _scan_source_for_ha_config(
+        "for entry in items:\n    pass\n", name="loop"
+    )
+    assert offenders == [], offenders
+
+
+def test_ast_scan_allows_clean_core_shape() -> None:
+    """A clean snippet with no HA coupling is not flagged (no false positives)."""
+    src = "opts = {'a': 1}\nx = opts.get('a')\nfor entry in items:\n    pass\n"
+    offenders = _scan_source_for_ha_config(src, name="clean")
+    assert offenders == [], offenders
+
+
+def test_settings_module_lives_under_core() -> None:
+    """settings.py is part of the core package (not the integration root)."""
+    assert (CORE_PKG / "settings.py").is_file()
+    # And it is importable as a core submodule.
+    import custom_components.nestquest.core.settings as mod
+
+    assert hasattr(mod, "NestQuestSettings")
+    assert isinstance(mod.NestQuestSettings, type)
+
+
+def test_settings_module_has_no_ha_imports() -> None:
+    """settings.py specifically carries no homeassistant import or config read."""
+    offenders = _scan_module_for_ha_config(CORE_PKG / "settings.py")
+    assert offenders == [], offenders
+
+
+# ---------------------------------------------------------------------------
+# Materialization over a non-default horizon: core path + integration path.
+# ---------------------------------------------------------------------------
+
+
+async def _prepare(path, executor):
+    """Open and migrate a database backed by ``executor`` (executor-only DB access)."""
+    from custom_components.nestquest.core.db import NestQuestDatabase
+    from custom_components.nestquest.core.migrations import apply_migrations
+
+    database = NestQuestDatabase(executor)
+    await database.open(path)
+    await apply_migrations(database)
+    return database
+
+
+async def test_materialize_over_non_default_horizon(hass, tmp_path) -> None:
+    """A settings object with a non-default horizon drives the matching window.
+
+    Constructs NestQuestSettings with horizon_days=3 and day_rollover_time
+    '03:30' (both non-default), builds the window via horizon_window, and
+    drives the CORE ``materialize`` over it; asserts the resulting instance
+    rows land exactly on the [today, today+3] window and NOT beyond it.
+    """
+    from custom_components.nestquest.core.dao_children import ChildrenDao
+    from custom_components.nestquest.core.dao_instances import (
+        QuestInstancesDao,
+    )
+    from custom_components.nestquest.core.materialize import materialize
+    from custom_components.nestquest.core.quest_definitions import (
+        create_quest_definition,
+    )
+    from custom_components.nestquest.core.recurrence import (
+        RuleType,
+        ScheduleRule,
+    )
+
+    database = await _prepare(tmp_path / "nq.db", hass.async_add_executor_job)
+    try:
+        settings = NestQuestSettings(
+            horizon_days=3, day_rollover_time="03:30"
+        )
+        assert settings.horizon_days == 3
+        assert settings.day_rollover_time == "03:30"
+
+        today = datetime.date(2026, 3, 1)
+        start, end = settings.horizon_window(today)
+        assert start == today
+        assert end == today + datetime.timedelta(days=3)
+
+        NOW = "2026-03-01T12:00:00+00:00"
+        child = await ChildrenDao(database).create("Ada", NOW)
+        await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(
+                rule_type=RuleType.DAILY, start_date=today.isoformat()
+            ),
+            [child.id],
+            ["morning"],
+        )
+
+        count = await materialize(
+            database,
+            start.isoformat(),
+            end.isoformat(),
+            today=today,
+        )
+        # 4 days (today..today+3 inclusive), one instance per day.
+        assert count == 4
+
+        records = await QuestInstancesDao(database).list_by_date_range(
+            child.id, start.isoformat(), end.isoformat()
+        )
+        dates = sorted({r.due_date for r in records})
+        assert dates == [
+            (today + datetime.timedelta(days=i)).isoformat()
+            for i in range(4)
+        ]
+
+        # Beyond the configured horizon: no instances.
+        beyond = (end + datetime.timedelta(days=1)).isoformat()
+        far = (end + datetime.timedelta(days=10)).isoformat()
+        assert await QuestInstancesDao(database).list_by_date_range(
+            child.id, beyond, far
+        ) == []
+    finally:
+        await database.close()
+
+
+async def test_integration_path_threads_settings(
+    hass, tmp_path, monkeypatch
+) -> None:
+    """The integration path threads ``settings`` through horizon_window + rollover.
+
+    ``_run_horizon_materialization`` calls
+    ``settings.horizon_window(today)`` (so the helper is real and shared,
+    not recomputed inline), and ``_register_day_rollover_listener``
+    registers at ``settings.day_rollover_hour_minute``.  This runs the
+    INTEGRATION path with ``horizon_days=3`` and
+    ``day_rollover_time='03:30'`` and asserts the resulting instance
+    window matches [today, today+3] AND the registered hour/minute are 3/30.
+    """
+    import custom_components.nestquest as nestquest
+    from custom_components.nestquest.core.dao_children import ChildrenDao
+    from custom_components.nestquest.core.dao_instances import (
+        QuestInstancesDao,
+    )
+    from custom_components.nestquest.core.quest_definitions import (
+        create_quest_definition,
+    )
+    from custom_components.nestquest.core.recurrence import (
+        RuleType,
+        ScheduleRule,
+    )
+
+    # Freeze the integration clock so "today" is deterministic (the
+    # hass fixture's config.time_zone is UTC, so 2026-03-01 12:00 UTC
+    # localizes to 2026-03-01).
+    freeze_nestquest_clock(
+        monkeypatch, datetime.datetime(2026, 3, 1, 12, 0, tzinfo=datetime.timezone.utc)
+    )
+
+    database = await _prepare(tmp_path / "nq.db", hass.async_add_executor_job)
+    try:
+        settings = NestQuestSettings(horizon_days=3, day_rollover_time="03:30")
+        today = datetime.date(2026, 3, 1)
+
+        NOW = "2026-03-01T12:00:00+00:00"
+        child = await ChildrenDao(database).create("Ada", NOW)
+        await create_quest_definition(
+            database,
+            "Daily chore",
+            ScheduleRule(
+                rule_type=RuleType.DAILY, start_date=today.isoformat()
+            ),
+            [child.id],
+            ["morning"],
+        )
+
+        # Integration path: the window comes from settings.horizon_window.
+        await nestquest._run_horizon_materialization(hass, database, settings)
+
+        end = today + datetime.timedelta(days=3)
+        records = await QuestInstancesDao(database).list_by_date_range(
+            child.id, today.isoformat(), end.isoformat()
+        )
+        dates = sorted({r.due_date for r in records})
+        assert dates == [
+            (today + datetime.timedelta(days=i)).isoformat()
+            for i in range(4)
+        ]
+        beyond = (end + datetime.timedelta(days=1)).isoformat()
+        far = (end + datetime.timedelta(days=10)).isoformat()
+        assert await QuestInstancesDao(database).list_by_date_range(
+            child.id, beyond, far
+        ) == []
+
+        # The rollover listener registers at the configured hour/minute.
+        remove = nestquest._register_day_rollover_listener(
+            hass, database, settings
+        )
+        try:
+            reg = hass.time_change.registrations[-1]
+            assert reg["hour"] == 3
+            assert reg["minute"] == 30
+        finally:
+            remove()
+    finally:
+        await database.close()

tests/test_core_snapshot.py

@@ -0,0 +1,306 @@
+"""Test the pure panel snapshot builder (task 9047a97b).
+
+The snapshot assembly that lived inline in the coordinator's
+``_async_update_data`` was extracted into the Home-Assistant-free
+:func:`custom_components.nestquest.core.snapshot.build_snapshot`, and
+the panel payload shaper (:func:`instance_payload`) with it.  These
+tests seed a household and assert the pure builder's output against
+EXPLICIT literal expected values — not self-equality — so the AWAY
+child's ``next_present``, a due-timed quest's ``overdue`` under a
+pinned ``now``, the custody ``cycle_day`` (> 1), and the panel payload
+dict shape (``done`` -> ``completed``, ``on_time`` passthrough, and
+``missed`` omission) are all exercised as literals.
+"""
+from __future__ import annotations
+
+import datetime
+from zoneinfo import ZoneInfo
+
+from conftest import wire_entry_to_registry
+
+from custom_components.nestquest import async_setup_entry
+from custom_components.nestquest.children import create_child
+from custom_components.nestquest.completion import complete_instance
+from custom_components.nestquest.core.snapshot import (
+    ChildDaySnapshot,
+    NestQuestSnapshot,
+    QuestInstanceView,
+    build_snapshot,
+    instance_payload,
+)
+from custom_components.nestquest.dao_instances import QuestInstancesDao
+from custom_components.nestquest.dao_presence import (
+    PresenceOverridesDao,
+    PresenceSchedulesDao,
+)
+from custom_components.nestquest.materialize import materialize
+from custom_components.nestquest.quest_definitions import create_quest_definition
+from custom_components.nestquest.recurrence import ScheduleRule
+
+
+async def test_instance_payload_shape_and_missed_omission() -> None:
+    """``instance_payload`` is the documented panel shape (§1).
+
+    ``done`` maps to ``completed``; ``open`` passes through; ``on_time``
+    is the builder's ``was_on_time`` verbatim; ``missed`` instances are
+    omitted unless ``include_missed`` (the admin payload, D-009).
+    """
+    def view(state: str, *, overdue: bool = False, on_time: bool | None = None,
+             completed_at: str | None = None, instance_id: int = 1) -> QuestInstanceView:
+        return QuestInstanceView(
+            instance_id=instance_id,
+            definition_id=10,
+            child_id=3,
+            title="Fill bird feeder",
+            icon="bird",
+            window="afternoon",
+            due_date="2026-09-21",
+            due_time="17:00",
+            state=state,
+            overdue=overdue,
+            completed_at=completed_at,
+            was_on_time=on_time,
+        )
+
+    open_view = view("open", overdue=True)
+    done_view = view("done", on_time=True, completed_at="2026-09-21T12:00:00+00:00")
+    missed_view = view("missed", instance_id=2)
+
+    panel = instance_payload([open_view, done_view, missed_view], include_missed=False)
+    assert panel == [
+        {
+            "id": 1,
+            "definition_id": 10,
+            "child_id": 3,
+            "title": "Fill bird feeder",
+            "icon": "bird",
+            "window": "afternoon",
+            "due_time": "17:00",
+            "state": "open",
+            "overdue": True,
+            "completed_at": None,
+            "on_time": None,
+        },
+        {
+            "id": 1,
+            "definition_id": 10,
+            "child_id": 3,
+            "title": "Fill bird feeder",
+            "icon": "bird",
+            "window": "afternoon",
+            "due_time": "17:00",
+            "state": "completed",
+            "overdue": False,
+            "completed_at": "2026-09-21T12:00:00+00:00",
+            "on_time": True,
+        },
+    ], "panel payload omits missed and spells done as completed"
+
+    admin = instance_payload(
+        [open_view, done_view, missed_view], include_missed=True
+    )
+    assert len(admin) == 3
+    assert admin[2]["state"] == "missed", (
+        "admin payload keeps missed instances with their missed state"
+    )
+
+
+async def test_build_snapshot_explicit_values(hass, make_entry, monkeypatch) -> None:
+    """The builder produces the documented shape as literals, pinned in time.
+
+    Ada is AWAY today (a 2-week schedule whose absent week 0 covers today,
+    plus a presence override marking her present on today+2) so
+    ``present`` is False and ``next_present`` is the override date.  Her
+    open quest due at 10:00 is OVERDUE under the pinned 12:00 ``now``.
+    Bo's quest due at 17:00 is completed at 12:00 (on time) so its
+    payload ``state`` is ``completed`` and ``on_time`` is True.  The first
+    scheduled active child is Ada, whose 2-week cycle anchored one day
+    before today puts ``cycle_day`` at 2.
+    """
+    entry = wire_entry_to_registry(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    coordinator = entry.runtime_data.coordinator
+    database = entry.runtime_data.database
+    settings = entry.runtime_data.settings
+
+    # Single clock read for the seed/snapshot anchor (no midnight skew).
+    today = coordinator._local_now().date()
+    time_zone = ZoneInfo(hass.config.time_zone)
+    # Pin the build instant at 12:00 local: past Ada's 10:00 due time
+    # (overdue) and before Bo's 17:00, and the completion moment for Bo.
+    pinned_now = datetime.datetime(
+        today.year, today.month, today.day, 12, 0, 0, tzinfo=time_zone
+    )
+    today_iso = today.isoformat()
+
+    ada = await create_child(database, "Ada")
+    bo = await create_child(database, "Bo")
+
+    await create_quest_definition(
+        database,
+        "Pack bag",
+        ScheduleRule.from_dict(
+            {"rule_type": "daily", "start_date": today_iso}
+        ),
+        [ada.id],
+        [("morning", "10:00")],
+    )
+    await create_quest_definition(
+        database,
+        "Brush teeth",
+        ScheduleRule.from_dict(
+            {"rule_type": "daily", "start_date": today_iso}
+        ),
+        [bo.id],
+        [("morning", "17:00")],
+    )
+    end = (today + datetime.timedelta(days=3)).isoformat()
+    await materialize(database, today_iso, end, today=today)
+
+    # Ada: 2-week cycle anchored yesterday. Week 0 (the empty segment)
+    # covers today, so she is absent today; an override marks her present
+    # on today+2, so next_present resolves to that date and cycle_day is
+    # ((today - (today-1)) % 14) + 1 == 2.
+    await PresenceSchedulesDao(database).upsert_by_child(
+        ada.id,
+        cycle_length_weeks=2,
+        anchor_date=(today - datetime.timedelta(days=1)).isoformat(),
+        pattern="|0,1,2,3,4,5,6",
+    )
+    returns_date = today + datetime.timedelta(days=2)
+    await PresenceOverridesDao(database).create(
+        ada.id,
+        returns_date.isoformat(),
+        returns_date.isoformat(),
+        is_present=True,
+        note="visit",
+    )
+
+    # Complete Bo's instance at the pinned 12:00 (17:00 due => on time).
+    bo_instances = await QuestInstancesDao(database).list_by_child_and_date(
+        bo.id, today_iso
+    )
+    await complete_instance(
+        database,
+        bo_instances[0].id,
+        actor_source="panel",
+        actor_child_id=bo.id,
+        now=pinned_now,
+        today=today,
+    )
+
+    built = await build_snapshot(database, settings, pinned_now)
+
+    assert isinstance(built, NestQuestSnapshot)
+    assert built.today_iso == today_iso
+    assert built.cycle_day == 2, (
+        "Ada's 2-week cycle anchored yesterday => day 2 today"
+    )
+
+    by_id = {child.child_id: child for child in built.children}
+    assert list(by_id) == [ada.id, bo.id], (
+        "active children appear in sort_order, id order"
+    )
+    ada_child = by_id[ada.id]
+    bo_child = by_id[bo.id]
+
+    # Ada: away today, returns on the override date, one open+overdue quest.
+    assert isinstance(ada_child, ChildDaySnapshot)
+    assert ada_child.present is False
+    assert ada_child.next_present == returns_date.isoformat()
+    assert ada_child.due_today == 1
+    assert ada_child.completed_today == 0
+    assert ada_child.remaining_today == 1
+    assert ada_child.completion_pct == 0
+    ada_view = ada_child.instances[0]
+    assert isinstance(ada_view, QuestInstanceView)
+    assert ada_view.state == "open"
+    assert ada_view.due_time == "10:00"
+    assert ada_view.overdue is True, "12:00 now is past the 10:00 due time"
+    assert ada_view.completed_at is None
+    assert ada_view.was_on_time is None
+
+    # Bo: present, one completed instance, on time, not overdue.
+    assert bo_child.present is True
+    assert bo_child.next_present is None
+    assert bo_child.due_today == 1
+    assert bo_child.completed_today == 1
+    assert bo_child.remaining_today == 0
+    assert bo_child.completion_pct == 100
+    bo_view = bo_child.instances[0]
+    assert bo_view.state == "done"
+    assert bo_view.due_time == "17:00"
+    assert bo_view.overdue is False, "overdue is only computed for open state"
+    assert bo_view.completed_at == pinned_now.astimezone(
+        datetime.timezone.utc
+    ).isoformat()
+    assert bo_view.was_on_time is True
+
+    # Panel payload shape: Ada open+overdue stays open; Bo done -> completed.
+    ada_payload = instance_payload(ada_child.instances, include_missed=False)
+    assert ada_payload == [
+        {
+            "id": ada_view.instance_id,
+            "definition_id": ada_view.definition_id,
+            "child_id": ada.id,
+            "title": "Pack bag",
+            "icon": None,
+            "window": "morning",
+            "due_time": "10:00",
+            "state": "open",
+            "overdue": True,
+            "completed_at": None,
+            "on_time": None,
+        }
+    ]
+    bo_payload = instance_payload(bo_child.instances, include_missed=False)
+    assert bo_payload == [
+        {
+            "id": bo_view.instance_id,
+            "definition_id": bo_view.definition_id,
+            "child_id": bo.id,
+            "title": "Brush teeth",
+            "icon": None,
+            "window": "morning",
+            "due_time": "17:00",
+            "state": "completed",
+            "overdue": False,
+            "completed_at": pinned_now.astimezone(
+                datetime.timezone.utc
+            ).isoformat(),
+            "on_time": True,
+        }
+    ]
+
+    # Missed omission is real: a missed view is dropped from the panel
+    # payload and kept in the admin payload with its missed state.
+    missed_view = QuestInstanceView(
+        instance_id=999,
+        definition_id=10,
+        child_id=ada.id,
+        title="Stale quest",
+        icon=None,
+        window="morning",
+        due_date=(today - datetime.timedelta(days=1)).isoformat(),
+        due_time="09:00",
+        state="missed",
+        overdue=False,
+        completed_at=None,
+        was_on_time=None,
+    )
+    assert instance_payload([missed_view], include_missed=False) == []
+    assert (
+        instance_payload([missed_view], include_missed=True)[0]["state"]
+        == "missed"
+    )
+
+    # REQUIRED wrapper tie-in: the coordinator's _async_update_data is a
+    # thin WRAPPER over build_snapshot, so pinning its clock to the SAME
+    # pinned_now the builder was called with must reproduce the builder's
+    # snapshot byte-for-byte.  The dataclasses are frozen, so == is a full
+    # deep compare — a wrapper that mis-passed today vs now, or stopped
+    # calling the builder, would diverge here even though the literal
+    # assertions above still pass.
+    monkeypatch.setattr(coordinator, "_local_now", lambda: pinned_now)
+    await coordinator.async_refresh()
+    assert coordinator.data == built

tests/test_entity_matrix.py

@@ -186,18 +186,18 @@ async def test_entity_and_event_matrix(hass, make_entry) -> None:
     original_refresh = coordinator._async_update_data
 
     async def _future_dated_refresh():
-        import custom_components.nestquest.coordinator as coordinator_module
+        import custom_components.nestquest.core.snapshot as snapshot_module
 
-        real_derive = coordinator_module.derive_state
+        real_derive = snapshot_module.derive_state
 
         def _derive(instance, latest, today):
             return real_derive(instance, latest, today + datetime.timedelta(days=1))
 
-        coordinator_module.derive_state = _derive
+        snapshot_module.derive_state = _derive
         try:
             return await original_refresh()
         finally:
-            coordinator_module.derive_state = real_derive
+            snapshot_module.derive_state = real_derive
 
     coordinator._async_update_data = _future_dated_refresh
     await coordinator.async_refresh()

tests/test_events.py

@@ -31,7 +31,19 @@ ADMIN_CTX = {"user_id": "admin-1"}
 _TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$")
 
 
-async def _setup_and_seed(hass, make_entry, *, windows=("morning",)):
+async def _setup_and_seed(hass, make_entry, *, windows=("morning",), seed_date=None):
+    """Seed a household and materialize today's instances.
+
+    ``seed_date`` pins the date instances are materialized for (and the
+    daily rule's ``start_date``); it defaults to the host's
+    ``datetime.date.today()``.  Callers that need to test the day-complete
+    rule against a non-UTC HA-local timezone pass the local zone's
+    ``today`` here so the seeded instance's ``due_date`` matches it.
+    """
+    import datetime
+
+    if seed_date is None:
+        seed_date = datetime.date.today()
     entry = wire_entry_to_registry(
         make_entry(data={CONF_ADMIN_USER_IDS: ["admin-1"]}), hass.registry
     )
@@ -43,7 +55,6 @@ async def _setup_and_seed(hass, make_entry, *, windows=("morning",)):
         {"action": "create", "display_name": "Ada"},
         context=ADMIN_CTX,
     )
-    child = None
     from custom_components.nestquest.children import list_children
 
     child = (await list_children(database))[0]
@@ -51,18 +62,16 @@ async def _setup_and_seed(hass, make_entry, *, windows=("morning",)):
         database,
         "Brush teeth",
         ScheduleRule.from_dict(
-            {"rule_type": "daily", "start_date": __import__("datetime").date.today().isoformat()}
+            {"rule_type": "daily", "start_date": seed_date.isoformat()}
         ),
         [child.id],
         list(windows),
     )
-    import datetime
-
-    today = datetime.date.today().isoformat()
-    end = (datetime.date.today() + datetime.timedelta(days=3)).isoformat()
-    await materialize(database, today, end, today=datetime.date.today())
+    today_iso = seed_date.isoformat()
+    end_iso = (seed_date + datetime.timedelta(days=3)).isoformat()
+    await materialize(database, today_iso, end_iso, today=seed_date)
     instances = await QuestInstancesDao(database).list_by_date_range(
-        child.id, today, today
+        child.id, today_iso, today_iso
     )
     return entry, child, instances
 
@@ -377,3 +386,436 @@ async def test_forced_refreshes_serialize_no_stale_publish(
     assert order == ["start", "end", "start", "end"], (
         "overlapping refreshes must serialize: " + str(order)
     )
+
+
+# ---------------------------------------------------------------------------
+# Direct core-builder unit tests (P2.2a): exact payload key sets, event
+# order, and was_on_time threading.  These target
+# custom_components.nestquest.core.events directly, bypassing the shim,
+# so a payload-shape regression is caught even if the shim masks it.
+# ---------------------------------------------------------------------------
+
+_COMPLETED_KEYS = {
+    "child_id",
+    "child_name",
+    "instance_id",
+    "quest_title",
+    "window",
+    "due_date",
+    "due_time",
+    "occurred_at",
+    "was_on_time",
+}
+_UNCOMPLETED_KEYS = {
+    "child_id",
+    "child_name",
+    "instance_id",
+    "quest_title",
+    "window",
+    "due_date",
+    "due_time",
+    "occurred_at",
+}
+_DAY_COMPLETE_KEYS = {
+    "child_id",
+    "child_name",
+    "quests_due",
+    "quests_completed",
+    "occurred_at",
+}
+
+
+async def test_build_quest_completed_event_payload_key_set(hass, make_entry) -> None:
+    """The completed-event payload carries exactly the documented keys
+    (no extra fields, no missing field) and threads ``was_on_time``."""
+    from custom_components.nestquest.core.events import build_quest_completed_event
+
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    event_type, payload = await build_quest_completed_event(
+        database, instances[0].id, was_on_time=True
+    )
+    assert event_type == EVENT_QUEST_COMPLETED
+    assert set(payload) == _COMPLETED_KEYS, (
+        f"completed payload keys drift: got {set(payload)} expected {_COMPLETED_KEYS}"
+    )
+    assert payload["was_on_time"] is True
+    assert payload["child_id"] == child.id
+    assert payload["child_name"] == "Ada"
+    assert payload["instance_id"] == instances[0].id
+    assert payload["quest_title"] == "Brush teeth"
+    assert _TIMESTAMP.match(payload["occurred_at"]), payload["occurred_at"]
+
+
+async def test_build_quest_completed_event_was_on_time_threads_all_shapes(
+    hass, make_entry
+) -> None:
+    """``was_on_time`` is carried verbatim — True, False, and None
+    (the unknown-timing shape) all round-trip into the payload."""
+    from custom_components.nestquest.core.events import build_quest_completed_event
+
+    entry, _child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    for wanted in (True, False, None):
+        _etype, payload = await build_quest_completed_event(
+            database, instances[0].id, was_on_time=wanted
+        )
+        assert payload["was_on_time"] is wanted, (
+            f"was_on_time={wanted!r} did not thread through"
+        )
+
+
+async def test_build_quest_uncompleted_events_payload_key_set(
+    hass, make_entry
+) -> None:
+    """The uncompleted-event payload carries exactly the documented keys
+    (no ``was_on_time`` — that field is completion-only)."""
+    from custom_components.nestquest.core.events import (
+        build_quest_uncompleted_events,
+    )
+
+    entry, _child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    events = await build_quest_uncompleted_events(database, instances[0].id)
+    assert len(events) == 1
+    event_type, payload = events[0]
+    assert event_type == EVENT_QUEST_UNCOMPLETED
+    assert set(payload) == _UNCOMPLETED_KEYS, (
+        f"uncompleted payload keys drift: got {set(payload)} "
+        f"expected {_UNCOMPLETED_KEYS}"
+    )
+    assert _TIMESTAMP.match(payload["occurred_at"]), payload["occurred_at"]
+
+
+async def test_build_child_day_complete_event_payload_key_set(
+    hass, make_entry
+) -> None:
+    """The day-complete payload carries exactly the documented keys
+    when the child's whole day clears, and reuses the completed
+    event's ``occurred_at`` stamp (one transition, one timestamp)."""
+    import datetime
+
+    from custom_components.nestquest.core.events import (
+        build_child_day_complete_event,
+        build_quest_completed_event,
+    )
+
+    entry, _child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    today = datetime.date.today()
+    completed_type, completed_payload = await build_quest_completed_event(
+        database, instances[0].id, was_on_time=True
+    )
+    # Mark every today-instance done so the day clears.
+    from custom_components.nestquest.completion import complete_instance
+
+    for instance in instances:
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="panel",
+            actor_child_id=_child.id,
+            today=today,
+        )
+    day_event = await build_child_day_complete_event(
+        database, completed_payload, today=today
+    )
+    assert day_event is not None
+    event_type, day_payload = day_event
+    assert event_type == EVENT_CHILD_DAY_COMPLETE
+    assert set(day_payload) == _DAY_COMPLETE_KEYS, (
+        f"day-complete payload keys drift: got {set(day_payload)} "
+        f"expected {_DAY_COMPLETE_KEYS}"
+    )
+    assert day_payload["occurred_at"] == completed_payload["occurred_at"], (
+        "day-complete must reuse the completed event's occurred_at stamp"
+    )
+    assert day_payload["quests_due"] == len(instances)
+    assert day_payload["quests_completed"] == len(instances)
+
+
+async def test_shim_fires_completed_before_day_complete(hass, make_entry) -> None:
+    """The shim fires ``nestquest_quest_completed`` BEFORE
+    ``nestquest_child_day_complete`` (the pre-extraction ordering), so
+    a failure in the day-complete DB reads cannot suppress the
+    completed event.  Asserted by bus event ORDER, not just counts."""
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    for instance in instances:
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": instance.id,
+                "actor": "panel",
+                "actor_child_id": child.id,
+            },
+        )
+    ordered = [
+        etype for etype, _payload in hass.bus.events
+        if etype in (EVENT_QUEST_COMPLETED, EVENT_CHILD_DAY_COMPLETE)
+    ]
+    # The completed event must precede the day-complete event.
+    first_completed = ordered.index(EVENT_QUEST_COMPLETED)
+    first_day = ordered.index(EVENT_CHILD_DAY_COMPLETE)
+    assert first_completed < first_day, (
+        f"completed must fire before day-complete; order was {ordered}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Day-complete rule coverage (P2.2b): an explicit ``today`` proves the
+# four outcomes — zero-quest day, non-today instance, partial day, and
+# fully-cleared today.
+# ---------------------------------------------------------------------------
+
+
+async def test_day_complete_zero_quest_day_yields_no_event(
+    hass, make_entry
+) -> None:
+    """A zero-quest day never fires day-complete: when the completed
+    payload's ``due_date`` matches ``today`` but the child has NO
+    instances due that date, the builder returns ``None`` (the
+    all-done binary sensor's rule — a day with zero quests owed can
+    never be "cleared")."""
+    import datetime
+
+    from custom_components.nestquest.core.events import (
+        build_child_day_complete_event,
+        build_quest_completed_event,
+    )
+
+    entry, _child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    # A date the daily rule does NOT cover (well past the materialized
+    # horizon) — zero instances due this date.
+    zero_quest_day = datetime.date.today() + datetime.timedelta(days=365)
+    _etype, completed_payload = await build_quest_completed_event(
+        database, instances[0].id, was_on_time=True
+    )
+    # Override due_date to the zero-quest day so the builder evaluates
+    # it (otherwise the due_date != today short-circuit fires first).
+    crafted = dict(completed_payload, due_date=zero_quest_day.isoformat())
+    result = await build_child_day_complete_event(
+        database, crafted, today=zero_quest_day
+    )
+    assert result is None, (
+        "a zero-quest day must not yield a day-complete event"
+    )
+
+
+async def test_day_complete_non_today_instance_yields_no_event(
+    hass, make_entry
+) -> None:
+    """Completing an instance NOT due today never evaluates the
+    child's day-complete for today: only the completed event fires."""
+    import datetime
+
+    from custom_components.nestquest.core.events import (
+        build_child_day_complete_event,
+        build_quest_completed_event,
+    )
+
+    entry, _child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    # Complete a FUTURE instance (tomorrow), pass today = today.
+    from custom_components.nestquest.dao_instances import QuestInstancesDao
+
+    today = datetime.date.today()
+    end = (today + datetime.timedelta(days=3)).isoformat()
+    all_instances = await QuestInstancesDao(database).list_by_date_range(
+        _child.id, today.isoformat(), end
+    )
+    today_ids = {i.id for i in instances}
+    tomorrow_instance = next(i for i in all_instances if i.id not in today_ids)
+    _etype, completed_payload = await build_quest_completed_event(
+        database, tomorrow_instance.id, was_on_time=True
+    )
+    assert completed_payload["due_date"] != today.isoformat()
+    result = await build_child_day_complete_event(
+        database, completed_payload, today=today
+    )
+    assert result is None, (
+        "a non-today instance must not yield a day-complete event for today"
+    )
+
+
+async def test_day_complete_partial_day_yields_no_event(
+    hass, make_entry
+) -> None:
+    """A partial day (some quests still open) yields only the
+    completed event — day-complete does not fire until the WHOLE day
+    clears."""
+    import datetime
+
+    from custom_components.nestquest.core.events import (
+        build_child_day_complete_event,
+        build_quest_completed_event,
+    )
+    from custom_components.nestquest.completion import complete_instance
+
+    entry, child, instances = await _setup_and_seed(
+        hass, make_entry, windows=("morning", "evening")
+    )
+    assert len(instances) == 2
+    database = entry.runtime_data.database
+    today = datetime.date.today()
+    # Complete ONLY the morning instance — the evening one stays open.
+    await complete_instance(
+        database,
+        instances[0].id,
+        actor_source="panel",
+        actor_child_id=child.id,
+        today=today,
+    )
+    _etype, completed_payload = await build_quest_completed_event(
+        database, instances[0].id, was_on_time=True
+    )
+    result = await build_child_day_complete_event(
+        database, completed_payload, today=today
+    )
+    assert result is None, (
+        "a partial day (evening quest still open) must not fire day-complete"
+    )
+
+
+async def test_day_complete_fully_cleared_today_yields_event(
+    hass, make_entry
+) -> None:
+    """A fully-cleared today (all owed quests done) yields the
+    completed event AND the child_day_complete event."""
+    import datetime
+
+    from custom_components.nestquest.core.events import (
+        build_child_day_complete_event,
+        build_quest_completed_event,
+    )
+    from custom_components.nestquest.completion import complete_instance
+
+    entry, child, instances = await _setup_and_seed(
+        hass, make_entry, windows=("morning", "evening")
+    )
+    assert len(instances) == 2
+    database = entry.runtime_data.database
+    today = datetime.date.today()
+    for instance in instances:
+        await complete_instance(
+            database,
+            instance.id,
+            actor_source="panel",
+            actor_child_id=child.id,
+            today=today,
+        )
+    # The last completion's payload drives the day-complete evaluation.
+    _etype, completed_payload = await build_quest_completed_event(
+        database, instances[-1].id, was_on_time=True
+    )
+    result = await build_child_day_complete_event(
+        database, completed_payload, today=today
+    )
+    assert result is not None, (
+        "a fully-cleared today must yield the day-complete event"
+    )
+    assert result[0] == EVENT_CHILD_DAY_COMPLETE
+    assert result[1]["quests_due"] == len(instances)
+    assert result[1]["quests_completed"] == len(instances)
+
+
+# ---------------------------------------------------------------------------
+# Shim timezone wiring (P2.2c): the conftest fake hass defaults
+# hass.config.time_zone to UTC, so the day-complete rule's HA-local
+# ``today`` wiring is otherwise untested.  This test sets the zone to
+# one whose current local date differs from UTC and asserts the
+# day-complete rule uses THAT local date, not UTC.
+# ---------------------------------------------------------------------------
+
+
+async def test_shim_day_complete_uses_ha_local_timezone(
+    hass, make_entry
+) -> None:
+    """The day-complete rule reads ``hass.config.time_zone`` and
+    derives ``today`` in HA-local time, not UTC.
+
+    Picks a zone whose current local date differs from UTC, seeds an
+    instance for THAT zone's today (not UTC's today), completes it
+    through the service path, and asserts
+    ``nestquest_child_day_complete`` fires — proving the local date
+    reached the day-complete rule.  If no candidate zone has a
+    different date right now (only possible inside the ~1h window
+    around 12:00 UTC when all zones share one date), the test skips
+    rather than run vacuously.
+    """
+    import datetime as _dt
+    from zoneinfo import ZoneInfo
+
+    utc_today = _dt.datetime.now(_dt.timezone.utc).date()
+    far_zone = None
+    far_today = None
+    for tz_name in (
+        "Pacific/Kiritimati",   # +14 (UTC+14)
+        "Pacific/Auckland",     # +12/+13
+        "Pacific/Chatham",      # +12:45/+13:45
+        "Pacific/Honolulu",     # -10
+        "America/Los_Angeles",  # -8/-7
+        "Etc/GMT+12",           # -12
+        "Etc/GMT-13",           # +13
+    ):
+        local_today = _dt.datetime.now(ZoneInfo(tz_name)).date()
+        if local_today != utc_today:
+            far_zone = tz_name
+            far_today = local_today
+            break
+    if far_zone is None:
+        import pytest
+
+        pytest.skip(
+            "no candidate zone has a date different from UTC right now"
+        )
+
+    hass.config.time_zone = far_zone
+    entry, child, instances = await _setup_and_seed(
+        hass, make_entry, seed_date=far_today
+    )
+    for instance in instances:
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": instance.id,
+                "actor": "panel",
+                "actor_child_id": child.id,
+            },
+        )
+    day_complete = hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)
+    assert len(day_complete) == 1, (
+        f"day-complete must fire under {far_zone} (local today "
+        f"{far_today.isoformat()}, UTC today {utc_today.isoformat()}); "
+        f"got {len(day_complete)} events"
+    )
+
+
+async def test_build_quest_missed_event_payload_key_set(
+    hass, make_entry
+) -> None:
+    """The missed-event payload carries exactly the documented keys —
+    the same shape the nightly sweep hand-builds (§3), with no
+    ``was_on_time`` (completion-only)."""
+    from custom_components.nestquest.core.events import (
+        build_quest_missed_event,
+    )
+
+    entry, child, instances = await _setup_and_seed(hass, make_entry)
+    database = entry.runtime_data.database
+    event_type, payload = await build_quest_missed_event(
+        database, instances[0].id
+    )
+    assert event_type == EVENT_QUEST_MISSED
+    assert event_type == "nestquest_quest_missed"
+    assert set(payload) == _UNCOMPLETED_KEYS, (
+        f"missed payload keys drift: got {set(payload)} "
+        f"expected {_UNCOMPLETED_KEYS}"
+    )
+    assert payload["child_id"] == child.id
+    assert payload["child_name"] == "Ada"
+    assert payload["instance_id"] == instances[0].id
+    assert payload["quest_title"] == "Brush teeth"
+    assert _TIMESTAMP.match(payload["occurred_at"]), payload["occurred_at"]

tests/test_lifecycle.py

@@ -12,6 +12,7 @@ from custom_components.nestquest.const import (
     CONF_ADMIN_USER_IDS,
     CONF_DAY_ROLLOVER_TIME,
     CONF_HORIZON_DAYS,
+    CONF_MORNING_SUMMARY_TIME,
     DEFAULT_HORIZON_DAYS,
     SERVICE_REGENERATE,
     DOMAIN as DOMAIN_CONST,
@@ -36,12 +37,12 @@ async def test_setup_stores_runtime_data_in_hass_data(hass, make_entry) -> None:
     assert hass.data[DOMAIN][entry.entry_id] is entry.runtime_data
 
 
-async def test_setup_runtime_data_has_entry_id_and_options(hass, make_entry) -> None:
+async def test_setup_runtime_data_has_entry_id_and_settings(hass, make_entry) -> None:
     entry = _wire(make_entry(options={"horizon_days": 7}), hass.registry)
     await async_setup_entry(hass, entry)
     runtime = entry.runtime_data
     assert runtime.entry_id == entry.entry_id
-    assert runtime.options == {"horizon_days": 7}
+    assert runtime.settings.horizon_days == 7
     assert callable(runtime.remove_update_listener)
 
 
@@ -526,24 +527,78 @@ async def test_setup_backfills_configured_horizon_days(hass, make_entry) -> None
     ).list_by_date_range(child_id, beyond, beyond_end) == []
 
 
-def test_configured_horizon_days_validates_and_falls_back() -> None:
-    """The configured horizon is validated; a malformed value uses the default."""
-    import custom_components.nestquest as nestquest
+async def test_setup_succeeds_with_fully_malformed_options(
+    hass, make_entry
+) -> None:
+    """A fully malformed options dict falls back per field and setup succeeds.
 
-    assert nestquest._configured_horizon_days({CONF_HORIZON_DAYS: 5}) == 5
-    assert nestquest._configured_horizon_days({}) == DEFAULT_HORIZON_DAYS
-    assert (
-        nestquest._configured_horizon_days({CONF_HORIZON_DAYS: True})
-        == DEFAULT_HORIZON_DAYS
+    ``horizon_days=True``, ``day_rollover_time='99:99'`` and
+    ``morning_summary_time='25:00'`` are all invalid; the integration's
+    ``from_options_resilient`` falls each back to its default, so setup
+    SUCCEEDS, the day-rollover listener registers at the default hour 0
+    minute 0, and the startup backfill materializes the default horizon
+    window.
+    """
+    import datetime
+
+    from custom_components.nestquest.dao_instances import QuestInstancesDao
+    from custom_components.nestquest.db import NestQuestDatabase
+    from custom_components.nestquest.migrations import apply_migrations
+    from custom_components.nestquest.store import async_get_db_path
+
+    db_path = await async_get_db_path(hass)
+    pre = NestQuestDatabase(hass.async_add_executor_job)
+    await pre.open(db_path)
+    await apply_migrations(pre)
+    child_id = await _seed_daily_child_and_definition(pre, _local_today(hass))
+    await pre.close()
+
+    entry = _wire(
+        make_entry(
+            options={
+                CONF_HORIZON_DAYS: True,
+                CONF_DAY_ROLLOVER_TIME: "99:99",
+                CONF_MORNING_SUMMARY_TIME: "25:00",
+            }
+        ),
+        hass.registry,
     )
-    assert (
-        nestquest._configured_horizon_days({CONF_HORIZON_DAYS: "5"})
-        == DEFAULT_HORIZON_DAYS
-    )
-    assert (
-        nestquest._configured_horizon_days({CONF_HORIZON_DAYS: 0})
-        == DEFAULT_HORIZON_DAYS
+    assert await async_setup_entry(hass, entry) is True
+
+    # The day-rollover listener fell back to the default 00:00.
+    registration = hass.time_change.registrations[0]
+    assert registration["hour"] == 0
+    assert registration["minute"] == 0
+
+    # The startup backfill used the default horizon window.
+    today = _local_today(hass)
+    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
+    records = await QuestInstancesDao(
+        entry.runtime_data.database
+    ).list_by_date_range(child_id, today.isoformat(), end)
+    assert len(records) == DEFAULT_HORIZON_DAYS + 1
+
+
+async def test_setup_keeps_horizon_when_sibling_option_is_bad(
+    hass, make_entry
+) -> None:
+    """A malformed sibling option does not reset the configured horizon.
+
+    ``horizon_days=5`` is valid while ``morning_summary_time='25:00'`` is
+    invalid; ``from_options_resilient`` falls back ONLY the bad sibling,
+    so the entry's resolved settings keep ``horizon_days == 5``.
+    """
+    entry = _wire(
+        make_entry(
+            options={
+                CONF_HORIZON_DAYS: 5,
+                CONF_MORNING_SUMMARY_TIME: "25:00",
+            }
+        ),
+        hass.registry,
     )
+    assert await async_setup_entry(hass, entry) is True
+    assert entry.runtime_data.settings.horizon_days == 5
 
 
 async def test_regenerate_service_registered_and_materializes(

tests/test_materialize.py

@@ -1475,7 +1475,7 @@ async def _collect_records(database, child_ids, start, end) -> set:
 
 
 def test_materialize_end_to_end_six_rule_types(tmp_path, monkeypatch) -> None:
-    import custom_components.nestquest.materialize as materialize_module
+    import custom_components.nestquest.core.materialize as materialize_module
 
     # Give each materialize run a DISTINCT batch stamp: production upserts
     # rewrite generated_at on every re-run, so a shared pinned stamp would
@@ -1487,6 +1487,9 @@ def test_materialize_end_to_end_six_rule_types(tmp_path, monkeypatch) -> None:
         stamps["n"] += 1
         return f"2026-06-01T00:00:{stamps['n']:02d}+00:00"
 
+    # The materialize() walk reads ``_now_stamp`` from its OWN module
+    # globals (now the HA-free core package), so the patch must target
+    # the core module, not the re-export shim the integration imports.
     monkeypatch.setattr(materialize_module, "_now_stamp", _distinct_stamp)
 
     async def _body(database):

tests/test_presence.py

@@ -364,11 +364,19 @@ def test_cycle_week_index_stable_across_three_year_boundaries() -> None:
 
 
 def test_module_uses_no_iso_week_functions() -> None:
-    """D-004 guardrail: cycle math never reads ISO week numbers."""
+    """D-004 guardrail: cycle math never reads ISO week numbers.
+
+    Scanned against ``custom_components.nestquest.core.presence`` (the
+    real presence model since task 510c1f78); the integration's
+    ``presence.py`` is now a re-export shim, so scanning the shim is
+    vacuous.  Mirrors ``test_recurrence_model.py``'s scan of
+    ``core.recurrence``.
+    """
     from pathlib import Path
 
     source = Path(
-        __import__("custom_components.nestquest.presence", fromlist=["__file__"]).__file__
+        __import__("custom_components.nestquest.core.presence",
+                   fromlist=["__file__"]).__file__
     ).read_text()
     assert "isocalendar" not in source
     assert "isoweek" not in source

tests/test_sensors.py

@@ -238,16 +238,16 @@ async def test_due_today_payload_omits_missed_for_panel_includes_for_admin(
     entry, coordinator, (ada, bo, cory) = await _setup_seeded_entry(
         hass, make_entry
     )
-    import custom_components.nestquest.coordinator as coordinator_module
+    import custom_components.nestquest.core.snapshot as snapshot_module
 
     tomorrow = _today() + datetime.timedelta(days=1)
-    real_derive_state = coordinator_module.derive_state
+    real_derive_state = snapshot_module.derive_state
 
     def _derive_against_pinned_future(instance, latest, today):
         return real_derive_state(instance, latest, tomorrow)
 
     monkeypatch.setattr(
-        coordinator_module, "derive_state", _derive_against_pinned_future
+        snapshot_module, "derive_state", _derive_against_pinned_future
     )
     await coordinator.async_refresh()
 

tests/test_startup_db.py

@@ -442,6 +442,11 @@ def test_package_never_unlinks_or_truncates_db_files() -> None:
     """Guardrail: no code path may delete or overwrite an existing
     database file.  Scans the package for unlink/rmtree/write on the
     DB filename constant or *.db patterns.
+
+    Recursive (``rglob``) so the bundled ``core/`` package (extracted
+    in task d0b691d8 / 510c1f78) is scanned alongside the integration's
+    own modules — a non-recursive ``glob`` skips ``core/`` and leaves
+    the guardrail vacuous against it.
     """
     import re
     from pathlib import Path
@@ -459,7 +464,7 @@ def test_package_never_unlinks_or_truncates_db_files() -> None:
         re.IGNORECASE,
     )
     offenders: list[str] = []
-    for py in sorted(package.glob("*.py")):
+    for py in sorted(package.rglob("*.py")):
         if pattern.search(py.read_text()):
             offenders.append(py.name)
     assert offenders == [], (

tests/test_timezones.py

@@ -13,7 +13,9 @@ import datetime
 from types import SimpleNamespace
 from zoneinfo import ZoneInfo
 
+from conftest import freeze_nestquest_clock
 from custom_components.nestquest.const import DEFAULT_HORIZON_DAYS
+from custom_components.nestquest.core.settings import NestQuestSettings
 from custom_components.nestquest.dao_children import ChildrenDao
 from custom_components.nestquest.dao_instances import QuestInstancesDao
 from custom_components.nestquest.db import NestQuestDatabase
@@ -53,35 +55,10 @@ def _freeze_clock(
 ) -> tuple[datetime.datetime, list]:
     """Freeze the integration's ``datetime`` clock to a fixed aware instant.
 
-    Only ``custom_components.nestquest``'s ``datetime`` binding is patched, so
-    the generation path's "today" reads this instant (localized to whatever
-    time zone it asks for) while every other module and the test harness keep
-    the real clock.  Returns ``(frozen, requested)`` where ``frozen`` is the
-    instant normalized to UTC and ``requested`` is the list of ``tzinfo``
-    objects the code under test passed to ``now`` — so a test can prove the
-    generation path actually requested the configured HA time zone rather
-    than silently reading UTC.
+    Thin wrapper over :func:`conftest.freeze_nestquest_clock` kept for the
+    ``(frozen, requested)`` return shape the timezone assertions read.
     """
-    import custom_components.nestquest as nestquest
-
-    frozen = instant.astimezone(datetime.timezone.utc)
-    requested: list = []
-
-    class _FrozenDatetime(datetime.datetime):
-        @classmethod
-        def now(cls, tz=None):
-            requested.append(tz)
-            if tz is None:
-                return frozen.replace(tzinfo=None)
-            return frozen.astimezone(tz)
-
-    fake_module = SimpleNamespace(
-        datetime=_FrozenDatetime,
-        timedelta=datetime.timedelta,
-        date=datetime.date,
-    )
-    monkeypatch.setattr(nestquest, "datetime", fake_module)
-    return frozen, requested
+    return freeze_nestquest_clock(monkeypatch, instant)
 
 
 def _assert_requested_ha_timezone(requested, time_zone: str) -> None:
@@ -147,7 +124,9 @@ def test_horizon_uses_newyork_local_date_after_local_midnight(
         import custom_components.nestquest as nestquest
 
         child_id = await _seed_daily(database, local_today.isoformat())
-        await nestquest._run_horizon_materialization(hass, database)
+        await nestquest._run_horizon_materialization(
+            hass, database, NestQuestSettings()
+        )
         records = await QuestInstancesDao(database).list_by_date_range(
             child_id,
             local_today.isoformat(),
@@ -187,7 +166,9 @@ def test_horizon_uses_local_date_not_utc_when_host_ahead(
         import custom_components.nestquest as nestquest
 
         child_id = await _seed_daily(database, local_today.isoformat())
-        await nestquest._run_horizon_materialization(hass, database)
+        await nestquest._run_horizon_materialization(
+            hass, database, NestQuestSettings()
+        )
         records = await QuestInstancesDao(database).list_by_date_range(
             child_id,
             local_today.isoformat(),
@@ -231,7 +212,9 @@ def test_horizon_resolves_spring_forward_day_without_off_by_one(
             requested_batches.append(requested)
             local_today = instant.date()
             child_id = await _seed_daily(database, local_today.isoformat())
-            await nestquest._run_horizon_materialization(hass, database)
+            await nestquest._run_horizon_materialization(
+                hass, database, NestQuestSettings()
+            )
             records = await QuestInstancesDao(database).list_by_date_range(
                 child_id,
                 local_today.isoformat(),
@@ -280,7 +263,9 @@ def test_horizon_resolves_fall_back_day_without_off_by_one(
             requested_batches.append(requested)
             local_today = instant.date()
             child_id = await _seed_daily(database, local_today.isoformat())
-            await nestquest._run_horizon_materialization(hass, database)
+            await nestquest._run_horizon_materialization(
+                hass, database, NestQuestSettings()
+            )
             records = await QuestInstancesDao(database).list_by_date_range(
                 child_id,
                 local_today.isoformat(),

uv.lock

@@ -2,6 +2,55 @@ version = 1
 revision = 3
 requires-python = ">=3.11"
 
+[[package]]
+name = "annotated-doc"
+version = "0.0.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5a/8e/38aa427ed5402449e226975b649c5dc73ccadfefeb95e6aecb8f8ea4b6b6/annotated_doc-0.0.5.tar.gz", hash = "sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb", size = 10758, upload-time = "2026-07-28T13:50:58.129Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3e/30/e900b21425a860e195f32e37657aa1f7c7f2b1bfb26f03ca209b90933c06/annotated_doc-0.0.5-py3-none-any.whl", hash = "sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101", size = 5302, upload-time = "2026-07-28T13:50:57.239Z" },
+]
+
+[[package]]
+name = "annotated-types"
+version = "0.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5f/56/a8120250d128bed162cd73c76d45f6ef9991f3e068f62a8ee060afa3104a/annotated_types-0.8.0.tar.gz", hash = "sha256:13b2beaad985e05e2d6407ee4c4f35590b11f8d693a258a561055cac8f64cab7", size = 15893, upload-time = "2026-07-23T20:16:13.995Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/99/91/8acff4f5e50511b911bbccb72b8628a49c68ce14148cd9f6431094859a90/annotated_types-0.8.0-py3-none-any.whl", hash = "sha256:f072f4d804ea359e4eaf198b1af7a8b0943881a87f31bb764f8bf219bb9419e0", size = 13427, upload-time = "2026-07-23T20:16:12.938Z" },
+]
+
+[[package]]
+name = "anyio"
+version = "4.15.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "idna" },
+    { name = "typing-extensions", marker = "python_full_version < '3.15'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a9/d2/f4d173e22df740bc37b1db102b386ba719b66e95b0f0d751f556b387e6d2/anyio-4.15.1.tar.gz", hash = "sha256:9f28306018cbd6d329e64a36d58256edff76dd996fe423bc957326e578b82a94", size = 276966, upload-time = "2026-09-05T10:42:39.44Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.7.22"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a3/c2/24167ea9858356b47a87a50d39908bfdb72ceeefe0041586e704e5376b3a/certifi-2026.7.22.tar.gz", hash = "sha256:741e2c3b351ddf169a738da9f2c048608ff7f2c5cc02f1ebc6b118bb090d5d55", size = 138112, upload-time = "2026-07-22T03:35:12.644Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/a7/71ac2cff56fec219ed242bb11b8efb69fcc4bec75db06fb7bfe35de520e6/certifi-2026.7.22-py3-none-any.whl", hash = "sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775", size = 136983, upload-time = "2026-07-22T03:35:11.276Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/0e/7fa0ef50764b67090eca4114772a2abf8b6148198475e54c660b97caeee6/click-8.5.0.tar.gz", hash = "sha256:ba0d2089de75ea0310e2dde03160e6ca10009947fb95a182f9b54021bb272e34", size = 382235, upload-time = "2026-08-26T13:33:14.56Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/50/6c0d534c5f134586a8e1ba4e330569e32f057e33372ae556463212fb4cd3/click-8.5.0-py3-none-any.whl", hash = "sha256:255bc9599cf7748b4b1a446ccc735421bd08a2ae529a8b88597d3de5664ee360", size = 125251, upload-time = "2026-08-26T13:33:12.928Z" },
+]
+
 [[package]]
 name = "colorama"
 version = "0.4.6"
@@ -11,6 +60,68 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "fastapi"
+version = "0.141.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/02/91e3416a8fdd715abb903a952a6bec7cdd8d14eed55d415fc8595524c319/fastapi-0.141.1.tar.gz", hash = "sha256:e8822fc40db1e1858054d7a949a888695bc9bdce70139178e33bd2871a453ca1", size = 425799, upload-time = "2026-07-29T17:18:05.568Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/03/10388a42375ee7e4ac9b94eb2c5c569c8b5795e377e701c9ac3ad63de890/fastapi-0.141.1-py3-none-any.whl", hash = "sha256:bfb91aa2d334c61cb35ba9a116fc123b3d3df31640b801cf57a7a78ec3f603b3", size = 131954, upload-time = "2026-07-29T17:18:04.364Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "certifi" },
+    { name = "httpcore" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.20"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/08/8eea9d4b8302028f3abb2c0813953f7aec26d33b7a8960ed760e65ff29fa/idna-3.20.tar.gz", hash = "sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44", size = 216463, upload-time = "2026-09-17T14:11:04.752Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/a2/bb081bab032533a855d44de1d56f8e8426114ff1ba5d1f07a438a0a654f8/idna-3.20-py3-none-any.whl", hash = "sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c", size = 69583, upload-time = "2026-09-17T14:11:03.168Z" },
+]
+
 [[package]]
 name = "iniconfig"
 version = "2.3.0"
@@ -113,10 +224,13 @@ source = { virtual = "." }
 
 [package.dev-dependencies]
 dev = [
+    { name = "fastapi" },
+    { name = "httpx" },
     { name = "jinja2" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
     { name = "pyyaml" },
+    { name = "uvicorn" },
     { name = "voluptuous" },
 ]
 
@@ -124,10 +238,13 @@ dev = [
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "fastapi", specifier = ">=0.115" },
+    { name = "httpx", specifier = ">=0.28" },
     { name = "jinja2", specifier = ">=3" },
     { name = "pytest", specifier = ">=8.0.0" },
     { name = "pytest-asyncio", specifier = ">=0.24" },
     { name = "pyyaml", specifier = ">=6" },
+    { name = "uvicorn", specifier = ">=0.30" },
     { name = "voluptuous", specifier = ">=0.14" },
 ]
 
@@ -149,6 +266,123 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
 ]
 
+[[package]]
+name = "pydantic"
+version = "2.13.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-types" },
+    { name = "pydantic-core" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/53/ef/fc4f868f4e2cee79f863883abffceff107875f569b848507319842d2a681/pydantic-2.13.5.tar.gz", hash = "sha256:51a9c5f7b2f8e636f04c6cada605d9b6a3bf1348fdf945a3d8869b19bba0ee08", size = 845750, upload-time = "2026-08-28T14:04:00.916Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/eb/47/c95ffc2009878c7aac0c5e08528022dcb885933252a88b5f170058014464/pydantic-2.13.5-py3-none-any.whl", hash = "sha256:346a034f080da3755d8e9cb5e00e8b07de1d39e4f6e2c87d8ab7cafa0b269a73", size = 472589, upload-time = "2026-08-28T14:03:59.136Z" },
+]
+
+[[package]]
+name = "pydantic-core"
+version = "2.46.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/af/f9/8a06bea35ef8daf588f707784c973a7046e0034c8d8cfb08828eeffb8b75/pydantic_core-2.46.5.tar.gz", hash = "sha256:10416c15b8839ecc4ef4d0885da76da6fd0f67333a0eb8aff6d93c4b8f2910fc", size = 472262, upload-time = "2026-08-28T10:01:31.677Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a2/b6/81d2d19ea0be2c03664381b59f65fa72fc7969decedae00bc2c4ad835708/pydantic_core-2.46.5-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:a1dee1b804ff4d11c663636cf15d2ea47e9f79cd56c033fb1cbf08924842a48f", size = 2074737, upload-time = "2026-08-28T09:57:57.711Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/18/b70da8300e292df4099684ea11b1958043580d2f50d2dc8bf7e542bdd84a/pydantic_core-2.46.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:d625a186a65201c23a9e3b8ed9c47e90a026e03256608cc91851c6709096844f", size = 1921751, upload-time = "2026-08-28T09:57:59.265Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/1a/0d590341b6ffa4b4aca83508e6b8db4761aaeacfc15a25ca3815876d4797/pydantic_core-2.46.5-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4f8507560a9284e1370bb048ed4282012fbef4e8d109875b95e884d228552061", size = 1948231, upload-time = "2026-08-28T09:58:00.678Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/1d/02eb35761c51f2f7b1b042d6ab4cda6600f0c8c88a2243b3f734376201e5/pydantic_core-2.46.5-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5f93c5fe914d75fbec9a49209b00da5f08e9e467d69da2b1510c81940cfd10be", size = 2020708, upload-time = "2026-08-28T09:58:02.267Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/ea/f86073830e35d508cc8ddf9c3d9e6e6840fcb88d34bf726b0b4710186f27/pydantic_core-2.46.5-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:aca6c767f552b21b10f774aeac128e828eafb796adfa1b666a18bf6321453c3a", size = 2194914, upload-time = "2026-08-28T09:58:03.934Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/d7/fc36240d7791ce90939e51608568c33bfdae26202016f9770c229a487d86/pydantic_core-2.46.5-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:701b2e04b560eeb4bddf7a25ab8ca476176e34fdbd9a0e18196f0d12d4685f0b", size = 2235622, upload-time = "2026-08-28T09:58:05.516Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/bc/3fa2d76b83162820a17da7f645b28d1cba99fc8e1e5fc6517067ec450fa1/pydantic_core-2.46.5-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:49776eab08766a08dfff7012f8b422dcd7e25e43b316eedf0477c24fcfa84b7c", size = 2062091, upload-time = "2026-08-28T09:58:07.135Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/9a/095d557bb492c90cd8a70a6dd048bf793d433d03d86c81c11e912e4cd049/pydantic_core-2.46.5-cp311-cp311-manylinux_2_31_riscv64.whl", hash = "sha256:a2468d93d181667a7abd66e1b64bb9f76f361b0fef8faddf687456453576f5ee", size = 2089904, upload-time = "2026-08-28T09:58:08.814Z" },
+    { url = "https://files.pythonhosted.org/packages/24/98/7b76b1ad10a19a617a52aaa1d80e159115af939b095e86f8e756fd52e0df/pydantic_core-2.46.5-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:53feb344243bb9510a9dec7bf3cf1b64d88a98af5dc7872a5160465f8b198c8e", size = 2132244, upload-time = "2026-08-28T09:58:10.435Z" },
+    { url = "https://files.pythonhosted.org/packages/20/32/7d6ca365fadba186a0c8f85de1a701663bce81efd309d9479be58687622f/pydantic_core-2.46.5-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:cd5214352ae68f3b5e9af7768bdc5253695ee069675db3480518420b3be881f2", size = 2143901, upload-time = "2026-08-28T09:58:12.033Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/09/eb9a6aa57f22fd1541a9c0aa2a1f3aeef3ec65347d33e10a6da2f43e0ee9/pydantic_core-2.46.5-cp311-cp311-musllinux_1_1_armv7l.whl", hash = "sha256:9432f3598db432cb51c5b37fdbf29a60fcccc79e30d37a05022776a6bc4ab689", size = 2299425, upload-time = "2026-08-28T09:58:13.614Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/f9/548a5bb9d4ba8cd26e26daf48052236f6b38bb61e7b7241fbc3c995719eb/pydantic_core-2.46.5-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:8feeac04b5794e513e710af2f9c87d49f31a6dc47967bb264a1fed61a8989bec", size = 2318566, upload-time = "2026-08-28T09:58:15.199Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/20/06454d18834c02c406c9133f1a3b485305fd9ee984f9636c2f730bef6a9d/pydantic_core-2.46.5-cp311-cp311-win32.whl", hash = "sha256:892a881d5f68c2b9ea304b7a6c2c60d9343df578a311b0f86b94bc8f1ffe8129", size = 1954258, upload-time = "2026-08-28T09:58:16.813Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/c2/718b9deb4b72453b5d8c7447a3b14cb77bef36917ef5f514e0948a4096a0/pydantic_core-2.46.5-cp311-cp311-win_amd64.whl", hash = "sha256:40375c2d05acec10323e45dfe2077ac44bc74659008614af5069034e2cfc781c", size = 2041030, upload-time = "2026-08-28T09:58:18.288Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ea/c1d1a5b72d6e1ff7f377a4d9199f6591f095beb5b409a8a5d89f7238d939/pydantic_core-2.46.5-cp311-cp311-win_arm64.whl", hash = "sha256:28a6a556cd3b6066bea827857f9d9cce027c96f776e512f544a581f9e42161f8", size = 2009234, upload-time = "2026-08-28T09:58:19.929Z" },
+    { url = "https://files.pythonhosted.org/packages/82/3f/76358795aa7a8c6d4f36e2cb828ad1c90ee118e1393a9281664f5aade9d4/pydantic_core-2.46.5-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:b9fe6fb92520e3fd61f2e49000b6911b188824f089b75973ea06d6267f0b476d", size = 2076516, upload-time = "2026-08-28T09:58:21.576Z" },
+    { url = "https://files.pythonhosted.org/packages/db/50/26b091836076ce4cb2fac264186936acc069e0595772cfd02a563bc4761a/pydantic_core-2.46.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a39ac25a9a2fa4072efdb429833c4a4c8009a51ff9eea3eeae131713cd27991e", size = 1922874, upload-time = "2026-08-28T09:58:23.766Z" },
+    { url = "https://files.pythonhosted.org/packages/09/f0/2a8ce3849e299d44e2d2c196b6082643a3235565a735cb51db7a6261f614/pydantic_core-2.46.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4fdc8b93a41521988916eeaa271173fcca7fa0803d62f87675aac8dcec1c8e29", size = 1951772, upload-time = "2026-08-28T09:58:25.435Z" },
+    { url = "https://files.pythonhosted.org/packages/87/46/ac0dc8bdd9e6048183a14eb127764e7ad9240021c17513074a4711b0e31e/pydantic_core-2.46.5-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:b98134087d9de723658d17a42c7d0da8d6e2ef08015dee7dc93889047315f5e4", size = 2031832, upload-time = "2026-08-28T09:58:27.102Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/c2/339de5bef7be36301a2231eaa52e62163742c2281f11b5f4892bc79785cd/pydantic_core-2.46.5-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e652ab17569c94bff5475520f907b7148b8c24036a8ebbe5cf7cf7493d28579a", size = 2208645, upload-time = "2026-08-28T09:58:28.948Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/a0/9ff22b797724262da14427abaed4dd1d864a139693fc5e7809114376a716/pydantic_core-2.46.5-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d925f3d9afd05a8c0fb3a1031463a8d59ebe5e2afad297e29c78be19e13b4e62", size = 2265935, upload-time = "2026-08-28T09:58:30.625Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/a4/eb9409ec0736e50aa70a412f16c204ed149516846912f7e6724d4c73ee53/pydantic_core-2.46.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0fc5be0abd4a407e200d844b404e33639a554e7bd0d448e7b9ae181be4789ac2", size = 2066284, upload-time = "2026-08-28T09:58:32.289Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/02/7f6156ffc926857f1c37c07d9a388682865a81830ab6a1b637082c25e399/pydantic_core-2.46.5-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:816ff0a6550ffc06c098ccd2e0698600f9aa7da192a79eaa6f9af504a35db869", size = 2105889, upload-time = "2026-08-28T09:58:33.986Z" },
+    { url = "https://files.pythonhosted.org/packages/92/b1/e781d357ebe09fc929f995700f1b3503e8897f1cece183ecb1300d4d67e9/pydantic_core-2.46.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c7ea57fc63aa7da93a1bd2d644e6577befae10c52c4e36377635eea1056a74f5", size = 2158006, upload-time = "2026-08-28T09:58:35.647Z" },
+    { url = "https://files.pythonhosted.org/packages/70/0a/644597d84ab400e50609c192120b85c9681c22d3a20461b9060a79be0a7a/pydantic_core-2.46.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:efd62a42486f1bda5d24cb4f63d15a3c7768375fe83d36f9417b4ad7a2fb20b3", size = 2158408, upload-time = "2026-08-28T09:58:37.38Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/ee/ca3b7b3a4b3769ffe9ce9432a7c9be755de9593a46d3b0d54d0409323e44/pydantic_core-2.46.5-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:2bc9419666990c06d7397831f2126a1ecc3594aaa3ff7de5bf2d066802f4e07b", size = 2309609, upload-time = "2026-08-28T09:58:39.22Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/52/39fa1f451486019524ca685020390e7ca351832fd874530ba30c8628e6dc/pydantic_core-2.46.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:18a09e1e1011b462f2e32774f25859ef1223d5c2b0546a633cf56654710721e0", size = 2342618, upload-time = "2026-08-28T09:58:40.89Z" },
+    { url = "https://files.pythonhosted.org/packages/81/5e/468fc630568c61dcef3cd47ad32ffbeed9af643f49208d1ea86ab4f890c4/pydantic_core-2.46.5-cp312-cp312-win32.whl", hash = "sha256:5cb482e9e84c851f4e623fe4acc1ced89168cf1fe18f7089db4548c8f5bbb65b", size = 1939475, upload-time = "2026-08-28T09:58:42.591Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/c9/4c19f41b84cf6b622a72fbeed7665b25d47a187d68d47d0d430c07f23268/pydantic_core-2.46.5-cp312-cp312-win_amd64.whl", hash = "sha256:5e81740c09e310f5aa5cbd3e434a01c154d4bef93241c7877b39f211d2b78ba8", size = 2043140, upload-time = "2026-08-28T09:58:44.272Z" },
+    { url = "https://files.pythonhosted.org/packages/af/dd/0c1a050299147c746e5256db16d645ab5efd4f78c59937d581a0524e74a2/pydantic_core-2.46.5-cp312-cp312-win_arm64.whl", hash = "sha256:f7b0ec93a2893de856652154d73b7ba622f26fa97726487dcac373de5f4c6084", size = 1997729, upload-time = "2026-08-28T09:58:46.13Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/37/5abe39a8372a61d3dc3c1338fc504281c01b32fdb3169cd7187153b56d3e/pydantic_core-2.46.5-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:b7ca9034437b6022f941f4857459562ee00a560b97e7cce8a0ec5a74fc6766e0", size = 2075885, upload-time = "2026-08-28T09:58:47.856Z" },
+    { url = "https://files.pythonhosted.org/packages/21/43/6323b1f8b217780454c61304bcd2b38ae4762f50754414124603ccc90bb2/pydantic_core-2.46.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f332f0e72a5a0400141f830744e141bf9f97917878dbe968669e8a7fefea78ff", size = 1922768, upload-time = "2026-08-28T09:58:49.58Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/a3/c05ca796e1197618a774b01e596aeedfefc2f7d8c01ae3054e910b120e8a/pydantic_core-2.46.5-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:193375f3548919d3f0b60936ca113ada3e38f264f91b9b8e0508efaad57be931", size = 1951241, upload-time = "2026-08-28T09:58:51.511Z" },
+    { url = "https://files.pythonhosted.org/packages/68/32/33bc39ac705c52cffc908e8389f9754fdb208aea5c69cceddf4eb3ce99af/pydantic_core-2.46.5-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:79bdfa52f843137045b2d081cc05c120ba6665d29b7559c2c47690906f39279f", size = 2031975, upload-time = "2026-08-28T09:58:53.166Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/70/2333e885c0f6a67bc105c5916965dac9b57f2718ee20d81d1a06a4ebdc13/pydantic_core-2.46.5-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:24922243639cbdac66c75fcb6fd6495a9cb52b213d62f9a0d16f0310b1ff8038", size = 2208542, upload-time = "2026-08-28T09:58:55.017Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/ea/296debfb4264207bbda5936133892e027c0a58875ad53ebd512fba8ec3a2/pydantic_core-2.46.5-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c76fe65e607be28c7fd4d56fc3c42b1583aa058ce3408b7ad0fd540171d31f9f", size = 2264692, upload-time = "2026-08-28T09:58:56.767Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/f2/9e4de77a6271e07a76d2d58b11c091a979c191ed2939bf80067568b369d2/pydantic_core-2.46.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6f7b393a8b3da82f5c1fc0751e6d01ac6c55b93c18226a60bdfba4a724efafd1", size = 2066633, upload-time = "2026-08-28T09:58:58.531Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/db/f9e9d0c97445987b2084823d5c240de88087338f04fc2cfaa2df186b8049/pydantic_core-2.46.5-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:7ac031912d54f3d83ef3b3eb98dfabc1608802e2202263d25957eeed40b94761", size = 2105235, upload-time = "2026-08-28T09:59:00.421Z" },
+    { url = "https://files.pythonhosted.org/packages/07/c5/79169b047b3b2c3e99e04bc76372af9637e0bf6db638274fa927df96369e/pydantic_core-2.46.5-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:837b396ca3d7b74091ca623f6cbd8351bd42d670a79c2683e79fb089f06a2de5", size = 2157367, upload-time = "2026-08-28T09:59:02.442Z" },
+    { url = "https://files.pythonhosted.org/packages/26/b5/ba6057afb7c291bd449f51b867f95aef2072941c4ce4e5c31d6ffd132d3b/pydantic_core-2.46.5-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:5ee239d575f80b08eca11f6e20f90c4c695de7825c67eefe6091fbf20dda648e", size = 2158420, upload-time = "2026-08-28T09:59:04.2Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/28/2057abecaafdc22912afa819603a51f0a62d40643b7c4871c51721fea9be/pydantic_core-2.46.5-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:e80675d75ae2cd14372cb65cad5400d9347a3d3f6c13000183f22dfd027283ed", size = 2309588, upload-time = "2026-08-28T09:59:06.048Z" },
+    { url = "https://files.pythonhosted.org/packages/71/9d/881156dc404e27479c4246128d73538464cab4a239bec61995e227644c30/pydantic_core-2.46.5-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:9c4b71f10dd532fb7a5cbc8f58707779e64f03a258c2bf8bfbaecfcd9970b519", size = 2341866, upload-time = "2026-08-28T09:59:08.539Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/38/d66f443a259f84d13babdceae568e572b0ed26da17ca5d0a649ebb110a67/pydantic_core-2.46.5-cp313-cp313-win32.whl", hash = "sha256:97bf8de4d541598c94a59344eeb988a94c08ff76b5723c41f6567ec18c7892ea", size = 1938580, upload-time = "2026-08-28T09:59:10.402Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/1e/1d5371213f4cc9a7ed70c0bfcc7911de22311ee99a662a56077d7292d2ac/pydantic_core-2.46.5-cp313-cp313-win_amd64.whl", hash = "sha256:15f4a94963c95accac15b7b657bb177d3ad82bb90b0d0526d9a9b85079925db5", size = 2041980, upload-time = "2026-08-28T09:59:12.396Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/48/4222d90b1c67568bace4dec6dca6271449c66de3595d72b6d098f5fde597/pydantic_core-2.46.5-cp313-cp313-win_arm64.whl", hash = "sha256:d22a945598fb91236b4dd793a6e42e4f3dd7740bb5aace5ebd7d4c08d13bb575", size = 1997213, upload-time = "2026-08-28T09:59:14.245Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/8a/14596f2a8367da50cf7cbac48169ee5d9c8e11d486a3b527082384630c72/pydantic_core-2.46.5-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:c1c43ad4339643d70ebb8124e1305a7dab423001eff58bb41a0f731adbc98355", size = 2074081, upload-time = "2026-08-28T09:59:16.141Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/d5/d8a4eb6d6c7f66b91dd37c576d76e9e60fba900caf5372c17bcf949febc2/pydantic_core-2.46.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1a353f84de772f423b5ffb11d7ae352fbbef0f446f3c0b0af0f8236d7233606e", size = 1920497, upload-time = "2026-08-28T09:59:18.065Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/26/092079428f86e927e030b2c0ced87df69dbb1c875cdeaa67bf42ea2be746/pydantic_core-2.46.5-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5086029a57366b8cf81b130a43908738095c270c21a8d7f0e8bdfdb89718e2f3", size = 1952130, upload-time = "2026-08-28T09:59:20.476Z" },
+    { url = "https://files.pythonhosted.org/packages/08/c3/8ec0e290a9ebaebd64047bf5fda94be835c6b1551b02437e4b76778fbcd7/pydantic_core-2.46.5-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:46c25dda9d092a06c08db76ffe0a197107904d0dfac653f7d5306bbcd6d6119c", size = 2026371, upload-time = "2026-08-28T09:59:22.227Z" },
+    { url = "https://files.pythonhosted.org/packages/01/72/4fd20ad520fb8da0157f95b27a7eb05a72790ef08138e7701ac972c342ea/pydantic_core-2.46.5-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:37ea7b83c935e5b0d68c9449b82651accf78a10828b2c02b2f2d9e9496446c21", size = 2202822, upload-time = "2026-08-28T09:59:24.277Z" },
+    { url = "https://files.pythonhosted.org/packages/31/b0/d16e0771206b29314f0d52198b720be21e8a99ab2bf11e3bc0d7c9cebdff/pydantic_core-2.46.5-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e64e88d5585bea9ce95861079de72006c7fa6d3df4e3a3b65ba31eb979c15c9f", size = 2262756, upload-time = "2026-08-28T09:59:26.608Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/9b/59634b7ac631c63b2a37760eb6943af3e29573d6b59a4abc5e7f019d4cee/pydantic_core-2.46.5-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:54d510bac3ee52247af28ed4bb18a1e799f040ac60fd2bf5ccd4c92f1fbe786f", size = 2068352, upload-time = "2026-08-28T09:59:29.044Z" },
+    { url = "https://files.pythonhosted.org/packages/08/7c/570abb1ad2155348dc754ea91be22e5aaa18eb6d69a6068f7c6f2679a6ed/pydantic_core-2.46.5-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:a2a5e1d0ff29adddc9f6d6821a66302e4493f8ca898b715b6b1182c2c201ea0a", size = 2104777, upload-time = "2026-08-28T09:59:30.95Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/25/5bf74adc65a1ac5b7be3f6cb0bcb5433615c1598a801c19d830d84c98ded/pydantic_core-2.46.5-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:03b9666e41e35d8909852ba191a0607520f81b74eaf12ccf8737005dbb313821", size = 2156312, upload-time = "2026-08-28T09:59:32.604Z" },
+    { url = "https://files.pythonhosted.org/packages/90/6a/2ef38830675e050121040618135564ed56b860b45433b02d9b4ebece46f3/pydantic_core-2.46.5-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:a91c17edf6eea2402cb5457b4c89e99bc5ed1004aa34c4adf1d4258c1a5c22c2", size = 2150067, upload-time = "2026-08-28T09:59:34.453Z" },
+    { url = "https://files.pythonhosted.org/packages/90/ef/a7dbb03a14a64c2a4621f989c615ed9a892535a6cad938fc27079f919d80/pydantic_core-2.46.5-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:b49924c73a235e969511bf2aabdff3beebf9820931f646c80274d5d780010c47", size = 2304516, upload-time = "2026-08-28T09:59:36.194Z" },
+    { url = "https://files.pythonhosted.org/packages/68/f8/6bb4c4b80e8a6fde1904c64a51c62a1d04fcdfa3ea521a66b2ddefa1d885/pydantic_core-2.46.5-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:2cbd9a5eff05e51c447c34dfa4632145b26b09120cf04bd0c871e44c1a5e1c9a", size = 2335223, upload-time = "2026-08-28T09:59:37.931Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/80/f46b8c681195190b2c1f1c7c0a81abce60663e987613e09ef64d433dd96b/pydantic_core-2.46.5-cp314-cp314-win32.whl", hash = "sha256:2d5d76654becf5efd62c9e51c3756c67b49498b0c9a40884934c40807adbd074", size = 1934827, upload-time = "2026-08-28T09:59:39.836Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/3c/60674207246bc0a4009d2391b7c7251c7159f279c8d2ab8aae8ef46f3dee/pydantic_core-2.46.5-cp314-cp314-win_amd64.whl", hash = "sha256:fa10ef4112775900e7a0661068635eb67b2ab824fbde764de6e0e21982a93db0", size = 2042648, upload-time = "2026-08-28T09:59:41.792Z" },
+    { url = "https://files.pythonhosted.org/packages/69/0c/117c562c7c1babdf44576b72a5e496906506c93690387ecfbca7c729ae2e/pydantic_core-2.46.5-cp314-cp314-win_arm64.whl", hash = "sha256:045ab3b6d308439e32b81cc173bba5b9018bc6ed896afd0c65b3b009b1699af5", size = 1989652, upload-time = "2026-08-28T09:59:43.702Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/66/9336ae58f9eb68c41d121894e52c4c89eccb07eb8f602a04ee9c3f37736a/pydantic_core-2.46.5-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8816f3d218beb4b787de5c9759c259b8fa61f9dec42dc7811f320a33771778b7", size = 2065829, upload-time = "2026-08-28T09:59:45.364Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/02/bc19b47a96c2d3109760711acf22369e56bd7e405ca52f7ade164d2ead57/pydantic_core-2.46.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:bce57638e08ac148e5778cce7feb968307a727d66f8e2274a543d0cf0c9ad6a3", size = 1905716, upload-time = "2026-08-28T09:59:47.18Z" },
+    { url = "https://files.pythonhosted.org/packages/52/a4/70b47c0509923dd98ccfed04fb3e32ea3849c82a0ff2205bb41009b43c00/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:976e1128455aa595ea04c79ccfedff1aaeab96ee013fcc916bed120c4f0ad94f", size = 1934216, upload-time = "2026-08-28T09:59:49.241Z" },
+    { url = "https://files.pythonhosted.org/packages/52/ab/aa03b65f7bb198585edf806b906c3223ecf1795543e39e23aec4cce27ad2/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e7b891faeedeafba41b2983e5001a81b6a915b69544c7e7570d1989ce1c36ac7", size = 2010635, upload-time = "2026-08-28T09:59:51.692Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/8b/0da06343f30b84ec549aafd309c6456223d5dc8bd36af504c573faad561d/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f194189415698233dd1114a093a9b56e61e2c57e11b469be3b0506f46f0771c", size = 2209369, upload-time = "2026-08-28T09:59:53.582Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/5b/844c4defaa34a3df66eb9257087d121d70c201298b96abdf9f492fc2f1bf/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:82a36973cf8a2ef5406f4fe2edbf8ed0c99629535d959e0b100c76a32535a111", size = 2253238, upload-time = "2026-08-28T09:59:55.484Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/64/a4e536cb16d7f61a7fd3120b46c577fc7fa7325992f69c4f52bc786d77d8/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:cdbb78909f52b981d3b2d56b97328d71eb0b974c36bd77c920123a7ebb192829", size = 2065740, upload-time = "2026-08-28T09:59:58.038Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/75/aaa38c6bc2d085f6605b34eabdc6a8a4e0b2e61fc9c8e6e52b28e97b3125/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:52e24eacdb536cade636aa90fb851835222becff8484b7001fdc78cb0290f2aa", size = 2087425, upload-time = "2026-08-28T09:59:59.898Z" },
+    { url = "https://files.pythonhosted.org/packages/55/ae/fcab4cfc39aba3689e1d20c8b5250ad280957022c09af2ed9cd585602a5e/pydantic_core-2.46.5-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:37ae34309d7bd8c0d61ab839668058f2a7962ea1fc51d105d2db228fe0618034", size = 2139306, upload-time = "2026-08-28T10:00:03.057Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/f4/f1d03a4bc9d9acbc62f4d742b8a319af52f71885079868b2ff8e48a651ee/pydantic_core-2.46.5-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:0cdbada856a1c69a7624a64d3d9aefe79300bd6ef827b43a4f265010b9b55184", size = 2144589, upload-time = "2026-08-28T10:00:05.645Z" },
+    { url = "https://files.pythonhosted.org/packages/83/f3/7a53bb1356de514a4cd295f25b6ac39237895620c0462d2592b76c16e114/pydantic_core-2.46.5-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:545f26c504b27c3758439a5e6d9349931f0a04f855668d5fe323c89e82300a38", size = 2288882, upload-time = "2026-08-28T10:00:07.931Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/94/5a81583660c175c59d49ffb09f4b3a44debeaf86a19fca664ae1cdd9ee32/pydantic_core-2.46.5-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:ff218293c9c806138dca139765e3b067621be52bcd93cdc14c7711be7ddc90a9", size = 2335210, upload-time = "2026-08-28T10:00:10.177Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/9f/5d685c2693b972d1a59c998586e8823712b66603aeff47ee60a4bdaafd37/pydantic_core-2.46.5-cp314-cp314t-win32.whl", hash = "sha256:97cf3eb53a8cccacf9d46686a0926186c9bfb5574f2ed66d3639d5fe117cd3a9", size = 1921180, upload-time = "2026-08-28T10:00:12.35Z" },
+    { url = "https://files.pythonhosted.org/packages/70/12/5c94ee16d65a37a15f9e869f5e6256df111154491173801a4c5e800ab548/pydantic_core-2.46.5-cp314-cp314t-win_amd64.whl", hash = "sha256:d2f9fc07a8042a8f95925b35c4f04f469707c981fc33245b6ca187cf5d2dd290", size = 2020515, upload-time = "2026-08-28T10:00:14.774Z" },
+    { url = "https://files.pythonhosted.org/packages/63/19/67830dda664e6bdf9285ee2e40f355d0d7d6b92aa0c42e8d217bb8d33d36/pydantic_core-2.46.5-cp314-cp314t-win_arm64.whl", hash = "sha256:acf8a67ba51f4ca9ddbd0e6b3000a65ac51ab734661778b3e7ba64d99a710f2f", size = 1989276, upload-time = "2026-08-28T10:00:16.984Z" },
+    { url = "https://files.pythonhosted.org/packages/af/1e/ecca01fce348f7e8afa9572441ff6f7d1cc70d21e4859f33944d10877e1e/pydantic_core-2.46.5-graalpy311-graalpy242_311_native-macosx_10_12_x86_64.whl", hash = "sha256:c14ad3bdc85ee7f318742c457ca3968a92126d144b15721c759033bfb06296c2", size = 2075342, upload-time = "2026-08-28T10:00:51.353Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/4c/af80c7a8032dfc897040ad5cb772bebde529a381186499e6e29987f23f8c/pydantic_core-2.46.5-graalpy311-graalpy242_311_native-macosx_11_0_arm64.whl", hash = "sha256:0bddb4020d8f04175865ccd17eff3040874fc11fb593f424edb452653b4b947c", size = 1907219, upload-time = "2026-08-28T10:00:53.438Z" },
+    { url = "https://files.pythonhosted.org/packages/be/3e/54d89e2b092e778716bf6153634ef479e955f48c261090be23aa1e0fb0b5/pydantic_core-2.46.5-graalpy311-graalpy242_311_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2471fd51c61c610e1dcf7de44d7299283661654d11264ab4802b303368d69c47", size = 1953393, upload-time = "2026-08-28T10:00:55.58Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/89/828ee90cda28ce17bdefaa3a6eaf74fe430e113295a10e6126beca559d6c/pydantic_core-2.46.5-graalpy311-graalpy242_311_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b10ec717381bdbfafef34607824db4c91de69ff085e4fca3b2af91b4fa17e68a", size = 2099024, upload-time = "2026-08-28T10:00:57.794Z" },
+    { url = "https://files.pythonhosted.org/packages/df/dd/053c2e4303f791f3b8f8a14ab0b22008e8eb21d868c0c90b4f9be705b76a/pydantic_core-2.46.5-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:013d6f3483d81e02e7c328831808f336c8596ee33b4bd4026b9ffb1e960b8942", size = 2062540, upload-time = "2026-08-28T10:01:00.318Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/dd/a18df751a5e37dd51bfad7f68e766999125bebe68c9e1d10a493ad01bd63/pydantic_core-2.46.5-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:e9c134bb666dd54b778b9fc0d2b50cbb7f979b9e3716f26a88c9ab3b6fc1dd0f", size = 1902040, upload-time = "2026-08-28T10:01:02.529Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/13/01d40f9d07ce8a779fd6e0bd8ad4fba91309500dd67b869e2e219d261a6d/pydantic_core-2.46.5-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:347ec774390c87326a2e4929d58d3f7e8763a104d5d35f4cd595a4c952366433", size = 1967479, upload-time = "2026-08-28T10:01:05.004Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/04/c81d4841331c2178b6fb09ae225425e110ed72d990c9fe556c4ec03d1013/pydantic_core-2.46.5-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8e24d8f05fa2d28513d94e877e9c75ad66175376209b3977f916e240e623193c", size = 2111034, upload-time = "2026-08-28T10:01:07.345Z" },
+    { url = "https://files.pythonhosted.org/packages/20/21/22102e9950b3049526d20e811b95396508377d87651edd2b80d2b3d28659/pydantic_core-2.46.5-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:ab4b66edffb32d9e951efb3814bd104b8367a7501b81b955cacb5726d897389f", size = 2071333, upload-time = "2026-08-28T10:01:09.636Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/18/87aefa427d191e6d3ab1447f1efc1cdcac86af1069239b133e8a0fd7f7c9/pydantic_core-2.46.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:337639ba62a11acde6ef3aeb08c8ea755f8ef1fe5e513356c0f36a2b0d7568b0", size = 1912713, upload-time = "2026-08-28T10:01:12.285Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/93/fd89e9ad49b1805ca94d24ce1088b7d305f05c35ffafcedb9819d03588a0/pydantic_core-2.46.5-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:413a717a410d0c817ef5b786a059415550b3794e1d0c2abffd9efb93a3d9f7b4", size = 2090926, upload-time = "2026-08-28T10:01:15.19Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/45/8e59dab6acf8d35f02f0a958980074f31038968bdb2c983fcae9d1efee03/pydantic_core-2.46.5-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1e449def1945a462c464331254e5a44fca7c3b4f9aedf59ec2f50f8066dd8e25", size = 2131303, upload-time = "2026-08-28T10:01:17.937Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/a5/e1d4dc5180dd887a9522efc1f8716b8692b7606b1d3273d7862eaf66be44/pydantic_core-2.46.5-pp311-pypy311_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:a445486499897b88a7d6c310c88ed64dd37b1b59bfd7ae9107490bbb362f47d6", size = 2145128, upload-time = "2026-08-28T10:01:20.694Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/d7/ad493864a7fb21c0c4df98f965e2db430cb25a9d7369b5778d5016c09fd9/pydantic_core-2.46.5-pp311-pypy311_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:2d330aaba8621b1edcec8ae2c4050f63b84ccf6d98723a8f212e9684713abf0e", size = 2294560, upload-time = "2026-08-28T10:01:23.495Z" },
+    { url = "https://files.pythonhosted.org/packages/02/8e/b41c84c913f29973a268e6c2b5bbf13c95adb9956c126d10da11ba3b2bef/pydantic_core-2.46.5-pp311-pypy311_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:b6acfb46a814762367fb7ba0828b0a17d441b92ce249a0e007474c9072662dda", size = 2317531, upload-time = "2026-08-28T10:01:26.334Z" },
+    { url = "https://files.pythonhosted.org/packages/db/1d/068464f23075f66a8f1b806935e9cd9363ee446636ea70d2c22ee8659dbf/pydantic_core-2.46.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:d0a24b40877af2de4950252be9d21eaf7fb07660f3c2cae1f56c6b599ada5266", size = 2140686, upload-time = "2026-08-28T10:01:28.947Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.21.0"
@@ -242,6 +476,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
 ]
 
+[[package]]
+name = "starlette"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b5/b4/205b0d5241d934e8add0c38aa924c4f9fb7330834ff11e5444db964ec3f9/starlette-1.6.0.tar.gz", hash = "sha256:d4e3ac5e546444960c710297a3c9fc3f7ebae1b7e963f3d36173b49da535be9b", size = 2716969, upload-time = "2026-08-08T18:27:57.512Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c8/cb/6a6a47d5b464bd08695d254f3da6e7986cc70c9fa5d778eda57538edfe56/starlette-1.6.0-py3-none-any.whl", hash = "sha256:a86dd39d14bb45f85a3d18525215a9ef0cfd1f192ac793220e72598c90335f0c", size = 75969, upload-time = "2026-08-08T18:27:56.196Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.16.0"
@@ -251,6 +498,31 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
 ]
 
+[[package]]
+name = "typing-inspection"
+version = "0.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a3/26/b09b8010994eccc3c09092e6b34058f36a460eea2d4c3e8b910c695975a0/typing_inspection-0.4.4.tar.gz", hash = "sha256:547274fa6b0a561ccf549cc9524b999a578e737d015d8709d021f9d0d13bea47", size = 76928, upload-time = "2026-08-12T12:37:25.997Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/67/81/4add07e5172b7ac40d8ed5ff580409a7801a4fe26d529bdd915401dabfbe/typing_inspection-0.4.4-py3-none-any.whl", hash = "sha256:65b8397ba37ccbce054456aaccddfc91e6e3083c92824df348d96ca832f3f147", size = 14750, upload-time = "2026-08-12T12:37:24.648Z" },
+]
+
+[[package]]
+name = "uvicorn"
+version = "0.53.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5d/ad/04bbb797c84fc1f26cb171f7394716f4865ffb8d8c5e1eef42565c2dfa6b/uvicorn-0.53.0.tar.gz", hash = "sha256:a9356f0cb89b3b8621529c5d5eebd69bfe154f4c3f68b4cf2de47e45fa855c2e", size = 110881, upload-time = "2026-09-14T07:44:23.815Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/76/18/0eea75741ee812e9f598b687619ce2454f6c3a1c5cd21ea990ec6bd26f45/uvicorn-0.53.0-py3-none-any.whl", hash = "sha256:e8dca71ec86dce5f04e333f0d56cdedf942446e6643b9cea1af0d6d3a02cb03e", size = 87081, upload-time = "2026-09-14T07:44:22.179Z" },
+]
+
 [[package]]
 name = "voluptuous"
 version = "0.16.0"