Task ded75ab8: Persisted skip_on_away on quest definitions (#194)

Co-authored-by: dev_agent <17+dev_agent@code.cubecraftcreations.com>
Co-committed-by: dev_agent <17+dev_agent@code.cubecraftcreations.com>

.gitignore

@@ -4,3 +4,4 @@ __pycache__/
 .venv/
 .pytest_cache/
 *.metadata.json
+frontend/node_modules/

.opencode/agents/approver.md

@@ -0,0 +1,32 @@
+---
+description: Independently verify NestQuest merge gates and merge approved heads
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  edit: deny
+  write: deny
+  task: deny
+  bash:
+    "*": deny
+    "/home/overseer/.local/share/nestquest-controller/scripts/nq-approve-merge *": allow
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/nestquest-controller/*": allow
+---
+
+You are the NestQuest feature-to-dev approver, separate from the controller and
+developer sessions. Verify the current PR head equals the independently
+reviewed and approved commit,
+required checks pass, blocking findings are resolved, branch protection is
+satisfied, and Maestro has accurate links. Use only the approver Gitea identity
+for the merge. Do not change code or approve a stale head. Use only the
+installed nq-approve-merge launcher for Gitea inspection and merging. Merge
+only into dev; never merge into main. If any gate is
+missing, refuse the merge and give the exact missing evidence. Report the PR,
+reviewed head, resulting merge commit, and target branch.
+
+Broker syntax: `nq-approve-merge inspect PR_NUMBER` or
+`nq-approve-merge merge PR_NUMBER REVIEWED_HEAD REVIEW_FILE`. Run one broker
+command per Bash call. The broker validates the current PR and review again
+before merging; do not substitute an ad hoc Gitea command.

.opencode/agents/developer.md

@@ -0,0 +1,21 @@
+---
+description: Implement one assigned NestQuest task in an isolated worktree
+mode: primary
+model: openrouter/z-ai/glm-5.3-flash
+permission:
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+---
+
+You are the NestQuest development agent. Implement only the assigned Maestro
+task in the supplied worktree. Follow the task's acceptance criteria and the
+repository's instructions. Run relevant tests, commit on the task branch, and
+report the commit and test results. Keep changes inside the assigned worktree.
+Do not approve your own pull request. You may merge your task PR into the
+feature branch only after the independent reviewer approved its exact current
+head and the controller verified every task merge gate. Never merge a feature
+into dev or a release into main. Do not start another task, change role, or
+use another model. Do not read or print credential files except when the
+approved task merge requires the existing Gitea development credential.

.opencode/agents/orchestrator.md

@@ -0,0 +1,60 @@
+---
+description: Reconcile NestQuest work and dispatch the next verified action
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  doom_loop: deny
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/opencode/tool-output/*": allow
+---
+
+You are the NestQuest controller. Work in the NestQuest repository. Maestro is
+the source of truth for feature and task state; CTXD is the source of truth for
+project instructions. At the start of every invocation, read the current
+NestQuest context in CTXD, including OPENCODE-ORCHESTRATOR-PROMPT.MD, then
+reconcile it with Maestro, Git, pull requests, and checks before dispatching.
+Follow the review, identity, and branch rules in that prompt.
+If the CTXD project or prompt is unavailable, do not dispatch or merge work;
+report the missing source and end with ORCHESTRATOR_STATE: BLOCKED.
+
+One invocation is a controller tick, not an entire feature lifetime. Prefer a
+state-changing action over another identical status query. Never repeat an
+unchanged tool call three times. If work is asynchronous, wait or inspect a
+specific changed result. Do not claim that you are continuing while ending
+the turn without naming the next action.
+
+The NESTQUEST_CONTROL_HOME environment variable names the installed launchers
+(normally /home/overseer/.local/share/nestquest-controller).
+For implementation, run "$NESTQUEST_CONTROL_HOME/scripts/nq-agent" with role
+developer, a task worktree, title, and task prompt file. For independent
+review, run "$NESTQUEST_CONTROL_HOME/scripts/nq-review" with the worktree,
+feature base ref, exact head ref, review prompt file, PR number, and an output
+file under /tmp/opencode. It publishes an exact-head Gitea approval only after
+Claude approves. The developer may merge
+a task PR into its feature branch only after independent approval of the exact
+head and verification of every task gate. For feature-to-dev approval and
+merge, run "$NESTQUEST_CONTROL_HOME/scripts/nq-agent" with role approver in
+a separate session after the independent review. Save the Claude review output
+in a file under /tmp/opencode and give that file and its reviewed head to the
+approver. Never substitute a different model or reviewer silently.
+
+When a feature is integrated into dev, reconcile Maestro, then immediately
+select and dispatch the next eligible feature. Feature completion is a
+transition, not the end of the controller's job. A release awaiting Joshua's
+main merge does not prevent work on independent eligible features.
+
+End each invocation with exactly one final line using one of these values:
+
+ORCHESTRATOR_STATE: CONTINUE
+ORCHESTRATOR_STATE: QUIESCENT
+ORCHESTRATOR_STATE: BLOCKED
+
+Use CONTINUE when there is any eligible or in-flight work; include the feature,
+task, and next concrete action immediately above the final line. Use QUIESCENT
+only after verifying no eligible or in-flight work remains in Maestro and the
+repository. Use BLOCKED only when a specific decision or access is required;
+include evidence and the needed human action. If you cannot establish the
+state, use BLOCKED. Never emit a success claim based only on a child's summary.

.opencode/agents/terminal-orchestrator.md

@@ -0,0 +1,31 @@
+---
+description: Run the NestQuest orchestration loop in this foreground terminal
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  doom_loop: deny
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/opencode/tool-output/*": allow
+---
+
+You are the foreground NestQuest orchestrator. The user explicitly launched
+this session to run the development queue now. Read the supplied terminal
+orchestrator prompt and current CTXD project context, but follow the
+FOREGROUND TERMINAL RUNTIME for this session instead of CTXD's service runtime
+section.
+
+Continuously reconcile Maestro, CTXD, Git, pull requests, checks, and child
+agent results. Execute the next useful transition in this same session. Do
+not finish after dispatch, review, remediation, or merge while eligible work
+remains. Use the installed role launchers for developer, reviewer, and
+approver isolation. Never start or wait for the systemd controller service.
+Never repeat an identical unchanged tool call three times; wait on the
+specific child or inspect newly changed evidence.
+
+End only at a global terminal condition, an explicit user stop, a genuine
+global access/decision block with no other eligible work, or a host-forced
+yield. On a forced yield, return a continuation checkpoint that can be
+resumed in the same OpenCode session.

.opencode/commands/start-development.md

@@ -0,0 +1,11 @@
+---
+description: Run the NestQuest orchestrator now in this OpenCode terminal
+agent: terminal-orchestrator
+---
+
+Run the NestQuest project queue now in this foreground OpenCode session.
+Read the current CTXD prompt and Maestro state, but use the FOREGROUND
+TERMINAL RUNTIME instead of the service runtime. Reconcile repository and
+pull-request state, then execute CONTROLLER_TICK repeatedly until a global
+terminal condition, explicit user stop, genuine global block, or host-forced
+yield. Do not start or wait for the systemd controller.

ORCHESTRATION.md

@@ -0,0 +1,77 @@
+# NestQuest foreground orchestrator
+
+OpenCode 1.18.32 loads the named agents from `.opencode/agents/`. Their
+models match the current NestQuest CTXD prompt: DeepSeek V4.1 Flash for the
+foreground orchestrator and approver, and GLM 5.3 Flash for development.
+Run orchestration directly from a shell:
+
+```bash
+nq-orchestrate
+nq-orchestrate mission.md
+cat mission.md | nq-orchestrate -
+nq-orchestrate --print-prompt > nestquest-orchestrator.md
+```
+
+The launcher renders the project prompt with the foreground terminal runtime,
+stops the dormant legacy service, refuses immediately when another NestQuest
+TUI is open, and then replaces itself with OpenCode using
+`terminal-orchestrator`. There is no background polling process and no wait
+for a controller tick. Exit or interrupt the TUI to stop the foreground run;
+resume that OpenCode session when a host-forced yield needs continuation.
+
+`scripts/nq-agent` launches developer and approver sessions with fixed agent
+definitions and no `--auto` flag. Headless OpenCode runs use `--pure` so the
+global idle-notification plugin does not notify on every controller tick.
+The approver's shell permission permits only the installed
+`nq-approve-merge` broker for Gitea. That broker requires exact-head
+Claude approval evidence, an exact-head Gitea approval by `review_agent`,
+the `dev` target, a mergeable PR, and passing configured checks before it
+requests a squash merge with Gitea's atomic `head_commit_id` guard.
+`scripts/nq-review` launches the independent
+Claude review in a noninteractive read-only session in the task worktree,
+checks the head again afterward, saves
+the output under `/tmp/opencode`, and posts the Gitea approval.
+The approver verifies the reviewed head again before a merge.
+
+The terminal launcher uses a stable copy of this configuration and scripts
+at `/home/overseer/.local/share/nestquest-controller`; it does not depend on
+which task branch is checked out in the primary NestQuest directory. Install
+that copy, run `scripts/nq-controller --check`, and verify the OpenCode
+agents (terminal-orchestrator, developer, and approver)
+with `opencode debug agent <name>` while `OPENCODE_CONFIG_DIR` points at the
+installed `.opencode` directory. Install `scripts/nq-orchestrate` in
+`~/.local/bin/`. For the global slash command, also install
+`.opencode/agents/terminal-orchestrator.md` under
+`~/.config/opencode/agents/` and
+`deploy/opencode-global-commands/start-nestquest-development.md` under
+`~/.config/opencode/commands/`. The old `nestquest-controller.service` remains static and
+inactive only for migration safety; foreground launch stops it.
+
+Inside an already-open OpenCode TUI, `/start-development` (or the global
+`/start-nestquest-development`) switches to the same foreground
+`terminal-orchestrator` behavior immediately. The shell launcher is the
+preferred entry point when supplying a mission prompt file.
+
+`templates/ORCHESTRATOR-PROMPT.template.md` and
+`templates/nestquest.profile.json` make the current CTXD cycle prompt
+adaptable to another project. See `templates/README.md` before publishing a
+rendered prompt for a new project.
+
+The CTXD preflight reads the configured HTTP/MCP server's NestQuest prompt.
+It deliberately does not inspect `/home/overseer/.ctx/ctxd.db`, which belongs
+to a different local store and lacks this project.
+
+All four agent credentials are currently readable by the same Unix account.
+The Gitea review and merge gates enforce normal workflow sequencing, but
+they are not a hard isolation boundary against a process running as that
+account. Strong isolation requires separate OS identities and protected
+credentials for the controller, reviewer, and approver.
+
+The terminal runtime repeatedly executes CONTROLLER_TICK within the foreground
+session. Neither a feature merge nor a progress report ends the run while
+eligible work remains. A host-forced yield returns a continuation checkpoint
+that can be resumed in the same OpenCode session.
+
+Do not put tokens in this repository or in unit files. Existing OpenCode MCP
+connections supply CTXD and Maestro. Rotate those MCP tokens as a coordinated
+operation across every consumer before revoking the old values.

README.md

@@ -4,7 +4,7 @@ Home Assistant custom integration for managing chores, custody schedules, and ho
 
 ## Overview
 
-NestQuest helps households coordinate daily life, chore tracking, custody schedules, and shared tasks directly within Home Assistant. It provides sensors, calendar events, and service calls designed for busy households and modern co-parenting setups.
+NestQuest helps households coordinate daily life, chore tracking, custody schedules, and shared tasks directly within Home Assistant. Version 0.2.0 ships the integration foundation (a configuration scaffold providing the package and manifest, shared constants, a single-instance config flow, setup/unload lifecycle handling with an options-reload listener, an options flow for horizon days / day rollover time / panel idle timeout, and HACS metadata) plus its persistence layer: an integration-owned SQLite database (`nestquest.db`) with WAL mode and foreign keys, a versioned migration runner stamping schema version 1 across eight tables (children, admin_users, schedule_rules, task_definitions, presence_schedules, presence_overrides, task_instances, completion_events), typed DAO layers so no other feature writes raw SQL, an append-only completion-event log, and startup handling that creates a missing database, opens a valid one, and refuses — without touching a single byte — to start on a corrupt one. Sensors, calendar events, and service calls are forthcoming in later releases and are not yet part of the integration.
 
 ## Installation
 
@@ -13,14 +13,14 @@ NestQuest helps households coordinate daily life, chore tracking, custody schedu
 1. Ensure [HACS (Home Assistant Community Store)](https://hacs.xyz/) is installed.
 2. In Home Assistant, open **HACS** > **Integrations**.
 3. Select the three-dots menu in the top right and click **Custom repositories**.
-4. Enter the repository URL: `https://github.com/talon2king/NestQuest`
+4. Enter the repository URL: `https://github.com/Maniacs-Mansion/NestQuest`
 5. Select category **Integration** and click **Add**.
 6. Search for **NestQuest** and click **Download**.
 7. Restart Home Assistant.
 
 > **Note:** Development happens in the private Gitea repository
 > (`https://code.cubecraftlabs.com/Maniacs_Mansion/NestQuest`). The GitHub
-> repository is a public mirror maintained for HACS distribution.
+> repository is a private mirror maintained for HACS distribution.
 
 ### Manual Installation
 
@@ -38,6 +38,278 @@ After installation and restart:
 2. Click **Add Integration** and search for **NestQuest**.
 3. Follow the on-screen configuration flow.
 
+## Events
+
+NestQuest fires Home Assistant bus events so automations can react to a
+child's progress. Each payload carries `child_id`, `child_name`,
+`instance_id`, `quest_title`, the instance's `window`, `due_date`,
+`due_time`, and `occurred_at` (a strict UTC ISO-8601 timestamp).
+
+| Event | Fires when | Extra payload fields |
+|---|---|---|
+| `nestquest_quest_completed` | a quest is completed (an actual completion, never a re-complete no-op) | `was_on_time` (bool) |
+| `nestquest_quest_uncompleted` | an admin reverses a completion | — |
+| `nestquest_child_day_complete` | a completion clears the child's whole day (quests were owed and none remain; a zero-quest day never fires it) | `quests_due`, `quests_completed` |
+| `nestquest_quest_missed` | the nightly sweep marks a still-open past-due quest missed (integrated in a later release) | — |
+
+Example automation trigger:
+
+```yaml
+triggers:
+  - trigger: event
+    event_type: nestquest_child_day_complete
+conditions:
+  - condition: template
+    value_template: "{{ trigger.event.data.child_name == 'Declan' }}"
+actions:
+  - action: notify.mobile_app_declans_phone
+    data:
+      message: "Every quest cleared — legendary!"
+```
+
+## Automation Blueprints
+
+NestQuest ships four automation blueprints in
+`custom_components/nestquest/blueprints/automation/`. Import them in
+Home Assistant under **Settings → Automations & Scenes → Blueprints**
+(or place the files in your `config/blueprints/automation/` folder),
+then create one automation per blueprint, filling the inputs with your
+household's choices.
+
+### Wiring to the integration's notification settings
+
+The integration's options flow records your notification choices —
+notify target, morning/afternoon/end-of-day times, and a toggle per
+automation. The blueprints take their own inputs at import time;
+fill them from the same values you stored in the options flow (the
+integration does not push its settings into imported automations):
+
+| Blueprint input | Options-flow counterpart |
+|---|---|
+| `morning_time` (default 08:00) | `morning_summary_time` |
+| `afternoon_time` (default 15:00) | `afternoon_reminder_time` |
+| `report_time` (default 20:00) | `end_of_day_report_time` |
+| `send_summary` / `send_reminder` / `send_report` / `celebrate` | the four `*_enabled` toggles |
+| `notify_target` | `notify_target` (your notify service, e.g. `notify.mobile_app_your_phone`) |
+
+The end-of-day report deliberately runs BEFORE the midnight missed
+sweep and reads the same day's data — do not schedule it at the
+day-rollover time.
+
+### The four blueprints
+
+1. **Morning summary** (`morning_summary.yaml`) — at the configured
+   time, lists every child whose `binary_sensor.nestquest_<child>_present_today`
+   is on and what they owe from `sensor.nestquest_<child>_quests_remaining_today`.
+   Children not present today are omitted entirely.
+
+2. **Afternoon reminder** (`afternoon_reminder.yaml`) — at the
+   configured time, notifies only about present children who still
+   have open quests. Sends nothing at all when every present child is
+   clear.
+
+3. **End-of-day report** (`end_of_day_report.yaml`) — one message per
+   evening: each present child's completion count and the quests they
+   still owe (the ones the midnight sweep will mark
+   `nestquest_quest_missed`). Absent children are omitted. Sends
+   nothing on an all-clear day unless `send_even_when_clear` is on.
+
+4. **Day-complete celebration** (`day_complete_celebration.yaml`) —
+   triggers on the `nestquest_child_day_complete` event (which only
+   fires when quests were owed and all are complete, so a zero-quest
+   day never celebrates). Create one `input_text` helper
+   (`nestquest_last_celebrated`) for the dedupe: the automation
+   records each celebrated child as `<child_id>:<today>` and
+   celebrates each child at most once per day — a re-cleared day does
+   not re-fire, but a second child clearing the same day still
+   celebrates.
+
+### Example package
+
+```yaml
+# One automation per blueprint — Settings → Automations & Scenes →
+# Create → Blueprint, then pick each NestQuest blueprint.
+#
+# morning_summary:   morning_time 08:00, notify_target notify.mobile_app_your_phone
+# afternoon_reminder: afternoon_time 15:00, same notify target
+# end_of_day_report:  report_time 20:00, send_even_when_clear false, same target
+# day_complete_celebration: input_text.nestquest_last_celebrated,
+#                            celebration_message "Legendary! {{ trigger.event.data.child_name }} cleared every quest today!"
+#
+# Every blueprint has its own send/celebrate toggle input; turn an
+# automation off entirely from HA's automation menu.
+```
+
+### Events the automations rely on
+
+| Event | Payload |
+|---|---|
+| `nestquest_quest_completed` | child_id, child_name, instance_id, quest_title, window, due_date, due_time, occurred_at (UTC ISO-8601), was_on_time |
+| `nestquest_quest_uncompleted` | child_id, child_name, instance_id, quest_title, window, due_date, due_time, occurred_at |
+| `nestquest_child_day_complete` | child_id, child_name, quests_due, quests_completed, occurred_at |
+| `nestquest_quest_missed` | child_id, child_name, instance_id, quest_title, window, due_date, due_time, occurred_at (fired by the nightly sweep) |
+
+Sensors the automations read: `sensor.nestquest_<child>_quests_due_today`
+(attributes: `child_id`, `child_name`, `present`, `instances`,
+`admin_instances`), `..._quests_remaining_today`,
+`..._quests_completed_today`, and
+`binary_sensor.nestquest_<child>_present_today`.
+
+## TouchHub setup
+
+Run these steps in order to display the NestQuest panel on a TouchHub
+wall device. The panel is an HA Lovelace dashboard, so the kiosk browser
+is simply a Home Assistant client. The path below is zero-config: the
+integration registers its panel dashboard itself on setup, so no YAML
+and no hand-built views are involved.
+
+1. **Install the integration and add the config entry.** Install
+   NestQuest via HACS or manually (see Installation above) and restart
+   Home Assistant. Then, in *Settings → Devices & Services*, click
+   **Add Integration**, search for **NestQuest**, and submit the flow —
+   it has no fields; it just creates the single config entry. Then open
+   the entry, click **Configure**, and fill the panel-plane API
+   connection in the options flow:
+
+   - **NestQuest API base URL** — the full `http://host:port` URL of
+     your NestQuest API service (default `http://127.0.0.1:8000`).
+   - **Panel service token** — the token the panel presents to the API
+     service as its Bearer credential. It may stay empty until you have
+     one; a pasted token must be unpadded.
+
+   The form's remaining fields (panel idle timeout, coordinator update
+   interval, last-good snapshot staleness) have defaults that serve the
+   panel and need no change here.
+
+2. **The panel dashboard appears automatically.** On setup the
+   integration registers one storage-mode Lovelace dashboard: a sidebar
+   entry titled **NestQuest** at the URL path `/nestquest`, whose stored
+   config is nothing but the **`custom:nestquest-party` strategy**
+   (`strategy: { type: custom:nestquest-party }`). The strategy
+   generates the views at render time from the household roster:
+
+   - **The Party** — the party-board view at `/nestquest/party`; the
+     dashboard root `/nestquest` shows it as the first view.
+   - one quest-log view per child at `/nestquest/<child-slug>`
+     ("Ada's Quest Log", …), in roster order.
+
+   Nothing is hand-configured: no YAML, no manual views, no
+   `child_order`, no `quest_log_path`/`board_path` — the board and the
+   quest logs compute their navigation paths from the dashboard's own
+   URL — and every generated view is already in **Panel** layout (see
+   the two constraints below). If the Lovelace surfaces are unavailable
+   (for example when Lovelace runs in YAML mode), setup logs a warning
+   and skips the registration; create the dashboard manually with the
+   same strategy as described in the manual alternative below.
+
+3. **Create a dedicated kiosk user.** In *Settings → People → Users*, add
+   a new user for the wall device. Make it **non-admin**, and ensure it is
+   not in the NestQuest admin allowlist. The allowlist blocks the NestQuest
+   **admin** operations — `uncomplete_quest`, `create_quest_definition`,
+   `update_quest_definition`, `set_quest_definition_active`,
+   `set_presence_pattern`, `create_presence_override`,
+   `delete_presence_override`, `export_history_csv`, and `manage_child`
+   (plus `regenerate` flows) — it does not make the account view-only. The
+   kiosk user *can* call `nestquest.complete_quest`, the one open NestQuest
+   service, to complete quests from the panel, and as a non-admin Home
+   Assistant user it may also reach other permitted Home Assistant entities
+   and services.
+
+4. **Open the dashboard and point TouchHub at it.** Open
+   `http://<home-assistant>/nestquest` in a browser first and check the
+   party board renders with your children's crests. Then, in the
+   TouchHub launcher, add the **Home Assistant Lovelace** app to the
+   dock and paste the dashboard URL from step 2 — the dashboard root,
+   `/nestquest` (TouchHub loads that URL directly as the kiosk landing
+   page). Set TouchHub **Auto-Return** to a value GREATER than the
+   quest log's `idle_return_seconds` (default 40s) — recommend **60s or
+   higher**. If Auto-Return is at or below 40s, TouchHub returns to its
+   launcher before the quest log's idle return can navigate back to the
+   party board.
+
+5. **Log the kiosk session in.** Sign in on the device as the dedicated
+   kiosk user from step 3, and leave that session logged in.
+
+TouchHub loads the dashboard URL directly. The NestQuest cards are normal
+Lovelace cards, not an iframe, so no Home Assistant framing setting is
+needed.
+
+### The two constraints
+
+- **Panel layout.** Every view must be in **Panel** (single-card)
+  layout: Home Assistant's default Masonry layout constrains the
+  1080px-tall NestQuest card to a narrow column, while Panel renders the
+  card full-screen at 1920×1080. The zero-config path already satisfies
+  the requirement — the strategy generates every view as
+  `type: panel` — while the manual alternative below requires setting
+  the layout by hand on each view (Edit Dashboard → pencil on the view
+  → View type: Panel).
+
+- **TouchHub Auto-Return.** TouchHub's **Auto-Return** must be greater
+  than the quest log's `idle_return_seconds` (default 40s) — recommend
+  **60s or higher** — so the launcher does not reclaim the wall device
+  before the quest log's own idle return navigates back to the party
+  board.
+
+### Manual alternative: build the dashboard by hand
+
+If you prefer not to use the zero-config dashboard above — or its
+registration was skipped — configure a Lovelace dashboard whose **URL
+slug is `nestquest`** (Settings → Dashboards → Edit → URL slug)
+yourself. Two options, in decreasing order of convenience:
+
+- **Use the strategy.** Give the dashboard
+
+  ```yaml
+  strategy:
+    type: custom:nestquest-party
+  ```
+
+  and no views of your own — the strategy generates the party-board and
+  quest-log views (each already in Panel layout) from the household
+  roster at render time. Optional `url_path` and `weather_entity` keys
+  may sit beside `strategy:`.
+
+- **Build the two views by hand.** A functional panel needs **two**
+  views in that dashboard, each with its own card config from
+  `design/ENTITIES-AND-SERVICES.md` §4. Give the views these exact URL
+  paths (the path segment after the dashboard slug):
+
+  - **View 1 path `board`** (URL `/nestquest/board`) — party board
+    (`type: custom:nestquest-party-board-card`): the household quest
+    board. Set `weather_entity` (optional; the dock falls back to
+    date/time), `quest_log_path: /nestquest/log` (the view the crest tap
+    navigates to), and `child_order: [slug1, slug2, slug3]` listing each
+    child's slug in display order.
+
+  - **View 2 path `log`** (URL `/nestquest/log`) — quest log
+    (`type: custom:nestquest-quest-log-card`): the per-child quest screen
+    the party board hops to. Set `board_path: /nestquest/board` (the
+    party-board view to return to), `weather_entity`,
+    `idle_return_seconds` (must be shorter than TouchHub Auto-Return —
+    see the two constraints above), `confirm_timeout_seconds`, and
+    `complete_screen_seconds`. The quest log reads the selected child's
+    slug from the view's URL path, so the board → log hop is a plain
+    Lovelace navigation.
+
+  The dashboard contains only the NestQuest panel card for each view —
+  no other cards, no admin controls. Each view's layout MUST be set to
+  **Panel** — see the two constraints above for why; the strategy
+  generates it for you, hand-built views do not get it for free.
+
+  The `quest_log_path` and `board_path` values must match the dashboard
+  slug and view paths above: `/<slug>/<view>`. If you chose `nestquest`
+  as the dashboard slug with view paths `board` and `log`, the card
+  configs are already correct. If you pick different names, substitute
+  your actual paths in **both** card configs — e.g. a dashboard slug
+  `chores` with view paths `main` and `history` needs
+  `quest_log_path: /chores/history` and `board_path: /chores/main`.
+  Navigation between the two views fails (the crest tap or back button
+  lands on a 404) if the card config paths do not match the dashboard
+  slug and view paths exactly.
+
+  See `design/ENTITIES-AND-SERVICES.md` §4 for the full card YAML.
+
 ## Developer Setup and Testing
 
 This project uses [`uv`](https://github.com/astral-sh/uv) for fast Python package and dependency management.
@@ -55,6 +327,28 @@ To set up the development environment and install dependencies:
 uv sync
 ```
 
+### Frontend cards
+
+The Lovelace cards live in `frontend/` (TypeScript + Lit) and build to a
+single bundle at `custom_components/nestquest/www/nestquest-cards.js`. The
+integration registers that bundle as a Lovelace resource automatically on
+setup — do not add it by hand. Card YAML is documented in
+`design/ENTITIES-AND-SERVICES.md` §4.
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+### Kids panel layout
+
+The Lovelace panel cards are designed for the wall display's confirmed
+resolution, 1920×1080 landscape, with no page scroll. TouchHub's bottom
+dock overlays the NestQuest weather dock strip until it auto-hides, so
+no tappable NestQuest control sits in that strip (the dock carries
+`pointer-events: none`). Keep it that way when editing the cards.
+
 ### Running Tests
 
 Run the test suite with `pytest`:

RELEASE_NOTES.md

@@ -0,0 +1,342 @@
+# NestQuest Release Notes
+
+## Version 0.6.0 — 2026-09-23
+
+### Scope
+
+Sixth release of NestQuest, promoting the re-imagined architecture
+(Features 15, 16, 18 and 20) and the foreground development-orchestration
+tooling from `dev` onto 0.5.0. This is a major architectural change: the
+Home Assistant integration becomes a thin client of a standalone NestQuest
+API service that owns the database.
+
+- **Feature 15 — Domain Core Extraction:** all domain code (schema,
+  migrations, database access, the DAOs, the pure recurrence/presence
+  engines, materialization, completion, the SSE-free event payload
+  builders, the panel snapshot builder, the children/definitions/allowlist
+  business layers, and an explicit settings object) now lives in a
+  Home-Assistant-free package bundled inside the integration at
+  `custom_components/nestquest/core/`. The SQLite schema and migration
+  versions are unchanged, so an existing `nestquest.db` opens without
+  migration. Covered by a no-Home-Assistant end-to-end smoke test.
+  (Tasks d0b691d8, 510c1f78, 4dd8f870, 628473ad.)
+- **Feature 16 — NestQuest API Service:** a standalone FastAPI service
+  (`api/`) that imports `core/` and is the only writer of the database.
+  Panel plane (`/api/v1/panel/*`) is authenticated by a static service
+  token: household snapshot and an idempotent complete route. Admin plane
+  (`/api/v1/admin/*`): children, quest definitions, presence
+  schedule/override, uncomplete, regenerate, history query + CSV export,
+  and settings — authenticated by an Authentik OIDC JWT (issuer, audience,
+  JWKS signature and expiry) plus membership in `nestquest-admins`, with
+  the panel service token rejected outright. A server-sent-events stream
+  publishes the quest-completed, quest-uncompleted, quest-missed and
+  child-day-complete transitions; the missed sweep runs in the API with a
+  cross-process-safe watermark. `/health` and the OpenAPI document are
+  served. (Tasks 042dfc5c, ae7e90ae, 1860ef76, 4d7bae00, 44c93cfd,
+  e70e6bfb, 0f2afb29, e4845baa, b586a2f1, e4a9d31b, da0226b3, 2d2dda53,
+  2b3de7e5, 9047a97b, 9a118da9, 058c7b69, a232c4f5.)
+- **Feature 18 — HA Integration as API Client:** the integration no longer
+  owns a database. It polls `GET /api/v1/panel/snapshot` and builds the
+  existing sensors (entity ids and per-child instance payload shape
+  unchanged), subscribes to the SSE stream and re-fires the four HA bus
+  events, proxies `nestquest.complete_quest` to the panel complete route,
+  and caches the last-good snapshot so a brief API outage does not blank
+  the panel. The HA admin services and the service permission gate are
+  removed; only the panel completion path remains. (Tasks 37d5e806,
+  6e70d166, b1ed9c45, 47c7c90e, d25b875f, d04f5bf3, ad67fc44.)
+- **Feature 20 — Zero-Config Panel Dashboard:** the panel installs with no
+  hand-written card YAML and no manual dashboard creation. The cards
+  auto-discover children from a household entity attribute (ordered by the
+  API's `sort_order`), a Lovelace dashboard strategy generates the
+  party-board view and one quest-log view per child at render time with
+  computed navigation paths, and the integration registers the dashboard
+  on first setup. Navigation and the panel transitions match the design
+  mockups. (Tasks 1b6d91d2, c859af23, c2d4dd8e, 107b8fbe, 50067c1f,
+  fc69c940, 67775be9.)
+- **Development orchestration tooling:** durable OpenCode controller and
+  role launchers, the foreground terminal orchestrator, the independent
+  review/approval gates, and the automatic release-preparation policy.
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+- A running NestQuest API service, reachable at the base URL and panel
+  service token configured in the integration options. The API service
+  source ships in `api/`; there is no container image, compose file or
+  deployment runbook in this release, and Feature 17 — the deployment
+  (TLS reverse proxy, Authentik, network separation, backups) — is **not**
+  part of this release and must be completed before the integration is
+  functional. See `docs/ARCHITECTURE.md` for the target design.
+
+### Breaking changes
+
+- **The HA integration no longer owns a database.** It reads exclusively
+  from the NestQuest API. The local `nestquest.db` is no longer opened,
+  migrated or written by the integration (the file is left untouched on
+  disk). Without a reachable API the entities become unavailable after the
+  configured staleness threshold; the panel serves the last-good snapshot
+  in the meantime.
+- **HA admin services are removed** (`uncomplete`, quest-definition
+  create/update/set-active, presence pattern/override, CSV export,
+  `manage_child`, `regenerate`) and the HA-side permission gate is gone.
+  Admin operations move to the API, and — once Feature 19 lands — the
+  admin PWA. Any automation that called an admin service must be
+  repointed at the API.
+- **Logger namespaces moved** under `custom_components.nestquest.core.*`:
+  the migrations runner now logs under
+  `custom_components.nestquest.core.migrations` (previously
+  `custom_components.nestquest.migrations`), and the children registry and
+  admin allowlist log under `custom_components.nestquest.core.children` and
+  `custom_components.nestquest.core.admin_allowlist`. The parent
+  `custom_components.nestquest` logger still catches all three; only users
+  who pinned a leaf logger name by its old spelling must update.
+- **The panel installs with no configuration.** `child_order`,
+  `quest_log_path` and `board_path` are no longer required (an explicit
+  value still wins). The integration registers a `custom:nestquest-party`
+  dashboard on setup; point TouchHub at it.
+- **Schema is unchanged at version 7** — no migration runs on upgrade.
+
+### Known Limitations
+
+- **Feature 17 (API deployment and identity) is not in this release.** The
+  API service source ships in `api/`, but no container image, compose
+  file, TLS reverse proxy, Authentik application/provider/`nestquest-admins`
+  group, proven network separation of the panel routes, or backup/restore
+  is included. Feature 17's containerization groundwork was completed on
+  its own feature branch, which is **not** merged into `dev` and therefore
+  is not part of this release. Until that deployment is completed the
+  integration has nothing to talk to.
+- **Feature 19 (admin PWA) is not in this release.** There is no admin UI
+  in 0.6.0; admin operations are reachable only through the API directly.
+- Moving the household database from Home Assistant to the API box is a
+  manual file copy (the schema is unchanged).
+- Single household; single API service.
+
+### Rollback
+
+Schema version is unchanged (7), so no migration is involved in either
+direction. Nevertheless **back up `nestquest.db` (plus `-wal`/`-shm`)
+before upgrading**: 0.6.0 never touches it, and a downgrade to 0.5.0
+resumes using exactly that file.
+
+**HACS installs:**
+
+1. Downgrade via HACS (HACS > Integrations > NestQuest > Redownload > 0.5.0).
+2. Restart Home Assistant.
+
+**Manual installs:**
+
+1. Replace `custom_components/nestquest/` with the 0.5.0 tree.
+2. Restart Home Assistant.
+
+**Repository operators:** git-revert the 0.6.0 release merge on `main`.
+
+## Version 0.5.0 — 2026-09-18
+
+### Scope
+
+Fifth release of NestQuest, promoting Features 06, 07, and 08 from `dev` onto 0.4.0 (quest model, children registry, presence engine):
+
+- **Feature 06 — quest definitions and assignment:** business layer `quest_definitions.py` over the multi-assignee / multi-window model (D-008). Create/edit/deactivate definitions; assign/unassign children; query helpers for materialization. `ScheduleRule` ⇄ `schedule_rules` storage mapping in the DAO layer.
+- **Feature 07 — instance materialization:** `materialize.py` fans out one instance per (definition, child, window, firing date) when the recurrence rule fires and the child is present. Idempotent on `(definition_id, child_id, due_date, window)`; skips completed instances; never generates past dates. HA-local `today` and configured `horizon_days` threaded end-to-end. Regeneration on definition/assignee/presence changes; daily rollover listener; startup backfill; `nestquest.regenerate` service.
+- **Feature 08 — completion and event log:** business layer `completion.py` wrapping the existing append-only `CompletionEventsDao`. `complete_instance` / `uncomplete_instance` (reversal event, original row untouched); state derived from the latest event; HA-local `was_on_time`; derived `missed` (never stored). Actor shapes `'user'` / `'panel'` with `actor_child_id` (D-008). Permission gating of un-complete is Feature 09.
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+
+### Breaking changes
+
+- None at the schema layer. Schema remains **version 6** (advanced in 0.4.0). This release adds application code only.
+
+### Known Limitations
+
+- No permission decorator yet (Feature 09): `complete_instance` / `uncomplete_instance` are Python APIs, not gated HA services. The only HA service in this release is `nestquest.regenerate`.
+- No entity or event surface (Feature 10): no sensors, no `nestquest_quest_completed` bus events.
+- No panel or admin Lovelace cards (Features 12/13).
+- Un-complete is implemented but not admin-gated until Feature 09.
+- Single-instance only.
+
+### Rollback
+
+Schema version is unchanged from 0.4.0 (still 6). A code downgrade to 0.4.0 does not require a database restore for schema compatibility, but **back up `nestquest.db` (plus `-wal`/`-shm`) before upgrading** — generated instances and completion events written by 0.5.0 remain in the file after downgrade; 0.4.0 will not generate or complete them.
+
+**HACS installs:**
+
+1. Downgrade via HACS (HACS > Integrations > NestQuest > Redownload > 0.4.0).
+2. Restart Home Assistant.
+
+**Manual installs:**
+
+1. Replace `custom_components/nestquest/` with the 0.4.0 tree.
+2. Restart Home Assistant.
+
+**Repository operators:** git-revert the 0.5.0 release merge on `main`.
+
+## Version 0.4.0 — 2026-09-15
+
+### Scope
+
+Fourth release of NestQuest, shipping three completed features on top of the data layer and recurrence engine:
+
+- **Feature 14 — quest domain model (BREAKING rename, D-007/D-008):** `task_definitions`/`task_instances` are now `quest_definitions`/`quest_instances` everywhere; definitions are multi-assignee (`quest_definition_assignees`, no single child column) and multi-window (`quest_definition_windows` — morning/afternoon/evening, clock ranges in `const.py`); the instance key widens to `(definition_id, child_id, due_date, window)` so twice-daily and shared quests materialise one instance per child per window per day; `completion_events` gains `actor_child_id` (the tapped panel profile; admin events stay NULL) with a second actor-pair CHECK. Schema version advances to **6**.
+- **Feature 03 — children registry & admin allowlist:** typed business layer for child profiles (create/edit with trimmed required names and duplicate-name warnings, whole-table reorder, deactivation as the only removal path — history is never touched); the admin allowlist with a fail-closed `is_admin` resolver (empty allowlist denies everyone; the last admin cannot be removed); automatic seeding on first setup (the config-flow user is persisted in entry data, with the options-flow list and HA owner accounts as fallbacks) so the owner is never locked out; the options flow gains a multi-select picker of existing Home Assistant users.
+- **Feature 05 — presence & custody engine:** a pure `PresenceSchedule`/`PresenceOverride` model with total validation and lossless round-trips; anchor-date cycle arithmetic (D-004 — never ISO week numbers or parity); `PresenceEngine.is_present` with the always-present default for schedule-free children; date overrides beat the repeating pattern; a `next_present_dates` preview for the admin schedule UI; a full-year regression guard walking 2020 (366 days, ISO week 53) and 2015 (365 days, ISO week 53) proving the rotation never inverts at a year boundary.
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+
+### Breaking changes
+
+- The database schema advances from version 1 to version 6. Upgrades are automatic and data-preserving (legacy `task_*` tables are renamed; the definitions table is rebuilt for multi-assignee; legacy instances pin to the morning window; panel events backfill `actor_child_id`). **Back up `nestquest.db` before upgrading** — see Rollback.
+- Dev installs from before 2026-09-15 migrate automatically on first start.
+
+### Known Limitations
+
+- Still no entities, services, calendar platforms, or panel cards: nothing is user-visible in Home Assistant yet (Features 06-10 land the business layer, materialisation, permission gate, and entity surface).
+- No materialisation yet: instances are not generated from definitions + presence yet (Feature 07).
+- Single-instance only.
+
+### Rollback
+
+**Back up `nestquest.db` (plus `-wal`/`-shm` sidecars) BEFORE upgrading.** This release migrates the database to schema version 6 with renamed tables; an older NestQuest build refuses a version-6 database ("newer than this integration understands") and cannot read renamed tables at all — a plain downgrade is NOT possible once the database has been migrated.
+
+**Rollback procedure (after a migrated database):**
+
+1. Stop Home Assistant.
+2. Restore the pre-upgrade `nestquest.db` backup (and sidecars) you made before upgrading.
+3. Downgrade the integration (HACS > Integrations > NestQuest > Redownload > 0.3.0) or replace `custom_components/nestquest/` manually.
+4. Restart Home Assistant.
+
+Without a backup, the only path is staying on 0.4.0 (recommended) or deleting the integration and its database to start fresh (Settings > Devices & Services > NestQuest > Delete, then remove `nestquest.db`).
+
+**Repository operators:** instead of uninstalling, git-revert the release merge on `main` and restore the pre-upgrade database.
+
+## Version 0.3.0 — 2026-09-14
+
+### Scope
+
+Third release of NestQuest, shipping Feature 04 — the recurrence rule engine:
+
+- `ScheduleRule`: an immutable, validated rule model (frozen dataclass) covering six recurrence shapes — daily, weekly (weekday sets), monthly by day-of-month, monthly by nth-weekday, yearly, and custom day-sets — with interval multipliers (every N days/weeks/months) and optional start/end dates.
+- `occurs_on(rule, date)`: pure calendar evaluation answering "does this rule fire on this date?"
+- `occurrences_between(rule, start, end)`: ordered, duplicate-free date lists, inclusive bounds, clamped to the rule's window.
+- Documented month-end policy: a rule for a day absent from a month (the 31st in April, the 30th/29th in February) fires on that month's LAST day — one firing per eligible month, interval anchored on nominal months elapsed.
+- Documented leap-day policy: a YEARLY February 29th rule fires February 28th in non-leap years (clamp, never skip).
+- Week offsets anchored at `start_date` by whole weeks elapsed — never ISO week numbers or parity (53-week years cannot silently invert schedules).
+- The engine is pure: no Home Assistant imports, no database access, no timezone logic.
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+
+### Known Limitations
+
+- No entities, services, or calendar platforms yet — the integration does not expose sensors, calendar events, or service calls in this release (data layer + recurrence engine only).
+- No business logic yet: nothing materializes task instances (Feature 07 combines this engine with presence schedules) — storage and scheduling math only.
+- Single-instance only — one NestQuest config entry is permitted per Home Assistant instance.
+
+### Rollback
+
+Downgrading from 0.3.0 to 0.2.0 removes the recurrence engine's code but leaves the `nestquest.db` file in place (untouched by both releases; no code path deletes an existing database). The file's schema version stamp is unaffected — this release ships no schema migration.
+
+**HACS installs:**
+
+1. Downgrade via HACS (HACS > Integrations > NestQuest > Redownload > 0.2.0) or Remove entirely.
+2. Restart Home Assistant.
+3. If removing: delete the integration in Home Assistant (Settings > Devices & Services > NestQuest > Delete), then restart Home Assistant again.
+
+**Manual installs:**
+
+1. Replace or delete the `custom_components/nestquest/` directory in your Home Assistant configuration directory.
+2. Restart Home Assistant.
+
+**Data:** the `nestquest.db` file (plus any `-wal`/`-shm` sidecars) is intentionally left untouched by both upgrade and rollback — back it up before upgrading.
+
+**Repository operators:** instead of uninstalling, git-revert the release merge on `main`.
+
+## Version 0.2.0 — 2026-09-14
+
+### Scope
+
+Second release of NestQuest, shipping Feature 02 — the persistence layer the integration owns outright:
+
+- Integration-owned SQLite database (`nestquest.db`) in the Home Assistant config directory: WAL journal mode, foreign-key enforcement, executor-backed access so the event loop never blocks.
+- Schema v1 for all eight tables: `children`, `admin_users`, `schedule_rules`, `task_definitions`, `presence_schedules`, `presence_overrides`, `task_instances`, `completion_events` — validated by declarative CHECK constraints (no triggers).
+- Versioned migration runner: on first start the database is created at schema version 1; later starts are a verified no-op; a failed migration rolls back to its prior version. A database stamped with a future version refuses to start.
+- Typed DAO layers for every table so no other feature writes raw SQL. Assignment validation is atomic; `completion_events` is strictly append-only — the DAO exposes no update or delete method, and a package-wide guard keeps mutation SQL out of every module.
+- Startup handling for missing (created fresh), valid (opened), and corrupt (logged, retried, left byte-identical for backup restore) database files via a read-only `integrity_check` preflight that cannot write or create sidecars. An existing zero-byte file is treated as corrupt and left untouched, not silently initialized.
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+
+### Known Limitations
+
+- No entities, services, or calendar platforms yet — the integration does not expose sensors, calendar events, or service calls in this release (data layer only).
+- No business logic yet: nothing materializes task instances and nothing can be completed — storage and schema only.
+- Single-instance only — one NestQuest config entry is permitted per Home Assistant instance.
+
+### Rollback
+
+Downgrading from 0.2.0 to 0.1.0 removes the data layer's code but leaves the `nestquest.db` file in place (0.1.0 never touches it, and no code path deletes an existing database). The file is compatible with this release's schema version stamp; a later reinstall of 0.2.0 or newer resumes from the stored version without re-migrating.
+
+**HACS installs:**
+
+1. Downgrade via HACS (HACS > Integrations > NestQuest > Redownload > 0.1.0) or Remove entirely.
+2. Restart Home Assistant.
+3. If removing: delete the integration in Home Assistant (Settings > Devices & Services > NestQuest > Delete), then restart Home Assistant again.
+
+**Manual installs:**
+
+1. Replace or delete the `custom_components/nestquest/` directory in your Home Assistant configuration directory.
+2. Restart Home Assistant.
+
+**Data:** the `nestquest.db` file (plus any `-wal`/`-shm` sidecars) is intentionally left untouched by both upgrade and rollback — back it up before upgrading. Removing the integration via Home Assistant deletes the config entry but not the database file.
+
+**Repository operators:** instead of uninstalling, git-revert the release merge on `main`. The database file is independent of the code and is never deleted by code.
+
+## Version 0.1.0 — 2026-09-13
+
+### Scope
+
+First release of NestQuest, a Home Assistant custom integration for managing chores, custody schedules, and house coordination. This release ships the integration foundation/configuration scaffold only (Feature 01):
+
+- Integration package and manifest, plus HACS metadata (`hacs.json`).
+- Shared constants module.
+- Single-instance config flow for initial setup.
+- Setup/unload lifecycle handling with an options-reload listener.
+- Options flow for configuring `horizon_days`, `day_rollover_time`, and `panel_idle_timeout`.
+- SQLite storage path resolver — path resolution only; the database itself is not created in this release.
+- Test harness (`pytest` via `uv`).
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+
+### Known Limitations
+
+- No entities, services, or calendar platforms yet — the integration does not expose sensors, calendar events, or service calls in this release.
+- Single-instance only — one NestQuest config entry is permitted per Home Assistant instance.
+- The integration does not yet create its database file; storage is limited to resolved configuration paths.
+
+### Rollback
+
+v0.1.0 is the first release — there is no previous NestQuest version to downgrade to, so rollback means complete removal. This release performs no data or schema migrations.
+
+**HACS installs:**
+
+1. Remove the NestQuest integration via HACS (HACS > Integrations > NestQuest > Remove).
+2. Restart Home Assistant.
+3. Remove the integration in Home Assistant (Settings > Devices & Services > NestQuest > Delete), then restart Home Assistant again.
+
+**Manual installs:**
+
+1. Delete the `custom_components/nestquest/` directory from your Home Assistant configuration directory.
+2. Restart Home Assistant.
+3. Remove the integration in Home Assistant (Settings > Devices & Services > NestQuest > Delete), then restart Home Assistant again.
+
+**Data:** the integration does not yet create its own database file, so there is no application data. However, Home Assistant persists the config entry and its selected options — removing the integration deletes that configuration, and the option values (`horizon_days`, `day_rollover_time`, `panel_idle_timeout`) will be lost on removal.
+
+**Repository operators:** instead of uninstalling, you may git-revert the release merge on `main`, which removes the integration files entirely. End users should use the uninstall path above.

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,139 @@
+"""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 /api/v1/admin/ping`` — the admin plane's auth probe, protected
+  by the Authentik OIDC JWT check (see :mod:`api.routes_admin`, whose
+  router carries the shared :func:`api.auth.require_admin_jwt`
+  dependency; the JWKS document it verifies against is cached on
+  ``app.state.jwks_cache``).
+- ``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.auth import JwksCache
+from api.config import ApiConfig
+from api.database import DatabaseState, make_database
+from api.events import TransitionPublisher
+from api.routes_admin import router as admin_router
+from api.routes_panel import router as panel_router
+from api.scheduler import MissedSweepScheduler
+
+
+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, and
+    starts the daily missed-sweep scheduler
+    (:class:`api.scheduler.MissedSweepScheduler`) against the same
+    database and publisher — cancelled before the connection closes on
+    shutdown.
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        state = make_database(db_path)
+        app.state.db = state
+        app.state.publisher = TransitionPublisher()
+        scheduler = MissedSweepScheduler(
+            state.database, publisher=app.state.publisher
+        )
+        app.state.sweep_scheduler = scheduler
+        try:
+            await state.open_and_migrate()
+            scheduler.start()
+            yield
+        finally:
+            await scheduler.stop()
+            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, the admin JWT check)
+    # read the configured values from the app rather than module state.
+    app.state.config = cfg
+    # The admin plane's ONE per-app JWKS cache: fetched from the
+    # configured provider on first use, then reused until its TTL
+    # lapses (see api.auth.JwksCache).  Tests replace it with a
+    # stub-backed cache so no request ever leaves the process.
+    app.state.jwks_cache = JwksCache(cfg.oidc_jwks_url)
+    app.include_router(panel_router)
+    app.include_router(admin_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/auth.py

@@ -0,0 +1,490 @@
+"""Admin-plane authentication for the NestQuest API service.
+
+The admin plane (``/api/v1/admin/*``, D-012) is authenticated by
+Authentik-issued OIDC access tokens: the admin PWA presents its JWT as
+a Bearer credential and :func:`require_admin_jwt` — the ONE
+implementation of that check — verifies it before any admin route runs.
+Verification enforces, without exception:
+
+- the signature, against the RSA signing key published in the
+  provider's JWKS document (fetched from the configured
+  ``NESTQUEST_OIDC_JWKS_URL`` and cached per app — never per request);
+- the issuer (``iss`` must equal the configured
+  ``NESTQUEST_OIDC_ISSUER``);
+- the audience (``aud`` must carry the configured
+  ``NESTQUEST_OIDC_AUDIENCE``);
+- expiry (``exp`` is required and enforced, and ``nbf`` is enforced
+  when the token carries it).
+
+Every rejection raises the SAME :class:`~fastapi.HTTPException` with
+the same detail — nothing in the response distinguishes which check
+failed.  The check FAILS CLOSED: a missing app config, a malformed or
+missing ``Authorization`` header, a non-RS256 algorithm, an unknown
+``kid``, and any PyJWT verification error all yield the one 401.
+
+The token's header (``alg``, ``kid``) is parsed and checked BEFORE the
+JWKS cache is consulted, so structurally invalid tokens can never
+amplify load on the provider.  An unknown ``kid`` forces ONE
+TTL-bypassing refetch (throttled, see :class:`JwksCache`) so a rotated
+key is picked up without waiting out the TTL, and a JWKS entry that
+matches the ``kid`` but carries corrupt key material maps to the same
+401.  A JWKS FETCH failure is deliberately NOT mapped to 401: the
+provider being unreachable is a server-side fault (an HTTP 500
+surfaces) and never poisons the cache, so the plane stays closed while
+the real cause is visible in the server log instead of disguised as a
+bad credential; a short backoff window after a failed fetch fails fast
+(re-raising the recorded fault) rather than fetching once per request.
+
+Beyond authentication, :func:`require_admin` is the ONE dependency
+every admin route uses: it REJECTS the panel service token outright —
+that credential authenticates the panel plane only, so treating it as
+a JWT candidate would blur two credential types into one check — and
+then requires the verified JWT's ``groups`` claim to name the
+``nestquest-admins`` group (authorization, 403, distinct from the
+uniform authentication 401 so the two failure classes stay apart).
+"""
+from __future__ import annotations
+
+import asyncio
+import binascii
+import json
+import secrets
+import time
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+import httpx
+import jwt
+from fastapi import Header, HTTPException, Request
+
+#: The authorization scheme the admin plane expects.  Matched
+#: case-insensitively, as RFC 9110 requires for scheme names.
+_BEARER_SCHEME = "bearer"
+
+#: The ONLY JWT signing algorithm accepted.  Pinned to one asymmetric
+#: algorithm (Authentik's RS256 default) so neither the header's ``alg``
+#: nor any JWKS key can talk the verifier into a weaker or symmetric
+#: scheme; PyJWT re-enforces it at decode time.
+_ALLOWED_ALGORITHM = "RS256"
+
+#: 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 admin credentials"
+
+#: Challenge header returned with a 401, per the Bearer auth scheme.
+_WWW_AUTHENTICATE = {"WWW-Authenticate": "Bearer"}
+
+#: The authorization group a verified admin JWT must name in its
+#: ``groups`` claim.  A module constant (the value Authentik's
+#: nestquest-admins group maps to) so it is clearly named in one place.
+ADMIN_GROUP = "nestquest-admins"
+
+#: Seconds a fetched JWKS document stays trusted before the next
+#: fetch.  Five minutes bounds how long a rotated-away key keeps
+#: verifying while staying far above a per-request fetch.
+_JWKS_TTL_SECONDS = 300.0
+
+#: Seconds a FAILED JWKS fetch blocks further fetch attempts.  Within
+#: this window after a failure the cache fails fast — it re-raises the
+#: recorded fault instead of touching the provider — so an outage is
+#: never amplified into one fetch per request.
+_JWKS_BACKOFF_SECONDS = 5.0
+
+#: Seconds that must pass before ANOTHER forced (TTL-bypassing) refetch
+#: may run.  An unmatched ``kid`` forces one refetch to pick up rotated
+#: keys; this interval bounds it, so a flood of unknown-``kid`` tokens
+#: cannot turn each request into a provider fetch either.
+_JWKS_KID_REFETCH_SECONDS = 5.0
+
+#: Seconds before the real JWKS fetch gives up on the provider.
+_JWKS_TIMEOUT_SECONDS = 5.0
+
+#: An async callable that fetches the JWKS document from a URL.  The
+#: real one (:func:`_fetch_jwks`) uses httpx; tests inject a stub so
+#: the suite stays hermetic (no network access).
+JwksFetcher = Callable[[str], Awaitable[dict[str, object]]]
+
+
+async def _fetch_jwks(url: str) -> dict[str, object]:
+    """Fetch the provider's JWKS document over HTTP (the real fetch).
+
+    Uses httpx with a short timeout; a non-2xx response or a body that
+    is not a ``{"keys": [...]}`` object raises — the cache never stores
+    a failed or malformed fetch.
+    """
+    async with httpx.AsyncClient(timeout=_JWKS_TIMEOUT_SECONDS) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        document = response.json()
+    if not isinstance(document, dict) or not isinstance(
+        document.get("keys"), list
+    ):
+        raise ValueError("JWKS document must be an object with a keys list")
+    return document
+
+
+class JwksCache:
+    """One app's cache of the OIDC provider's JWKS document.
+
+    The document is fetched through ``fetcher`` (the real one uses
+    httpx against the configured JWKS URL) and held for ``ttl_seconds``
+    — the dependency NEVER fetches per request.  A single fetch is
+    shared between concurrent requests via an :class:`asyncio.Lock`
+    (double-checked around it), and a failed fetch is never cached, so
+    the next request retries once the backoff window lapses rather than
+    being locked out until the TTL does.
+
+    Two bounds keep the provider out of an amplification loop:
+
+    - ``backoff_seconds``: after a FAILED fetch, :meth:`get` fails fast
+      for this long — re-raising the recorded fault WITHOUT touching
+      the fetcher or even the lock — instead of retrying per request.
+    - ``kid_refetch_seconds``: forced (TTL-bypassing) refetches — the
+      unmatched-``kid`` path — may run at most this often; a forced
+      refetch that is bounded out (or one inside the backoff window)
+      is served from the cached document as-is.
+
+    A successful fetch always clears the backoff; the document itself
+    is still trusted only for ``ttl_seconds`` — nothing is cached
+    indefinitely.
+
+    One instance lives on ``app.state.jwks_cache`` (installed by
+    :func:`api.app.create_app`); tests replace it with one built around
+    a stub fetcher, keeping the suite hermetic.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        ttl_seconds: float = _JWKS_TTL_SECONDS,
+        backoff_seconds: float = _JWKS_BACKOFF_SECONDS,
+        kid_refetch_seconds: float = _JWKS_KID_REFETCH_SECONDS,
+        fetcher: JwksFetcher | None = None,
+    ) -> None:
+        self._url = url
+        self._ttl_seconds = ttl_seconds
+        self._backoff_seconds = backoff_seconds
+        self._kid_refetch_seconds = kid_refetch_seconds
+        self._fetcher: JwksFetcher = (
+            fetcher if fetcher is not None else _fetch_jwks
+        )
+        self._document: dict[str, object] | None = None
+        self._fetched_at: float | None = None
+        self._failed_until: float | None = None
+        self._last_error: BaseException | None = None
+        self._forced_at: float | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self, *, force: bool = False) -> dict[str, object]:
+        """Return the JWKS document, refetching it if the TTL lapsed.
+
+        With ``force=True`` the TTL is bypassed so an unmatched ``kid``
+        can pick up a rotated key without waiting it out; the forced
+        refetch is itself bounded (see the class docstring): inside the
+        backoff window or the ``kid_refetch_seconds`` interval the
+        cached document is served as-is instead.  A failed fetch is
+        re-raised to the caller (a provider outage is a server fault,
+        never a 401) and starts the backoff window, during which every
+        caller — including forced ones with nothing cached — fails fast
+        on the recorded fault.
+        """
+        if not force:
+            fresh = self._fresh_document()
+            if fresh is not None:
+                return fresh
+        error = self._backoff_error()
+        if error is not None:
+            # Fail fast OUTSIDE the lock: a request inside the backoff
+            # window must not queue behind an in-flight fetch.
+            if force:
+                document = self._document
+                if document is not None:
+                    return document
+            raise error
+        async with self._lock:
+            if not force:
+                fresh = self._fresh_document()
+                if fresh is not None:
+                    return fresh
+            error = self._backoff_error()
+            if error is not None:
+                if force:
+                    document = self._document
+                    if document is not None:
+                        return document
+                raise error
+            if force and self._refetch_throttled():
+                document = self._document
+                if document is not None:
+                    return document
+            return await self._fetch_locked(force=force)
+
+    def _fresh_document(self) -> dict[str, object] | None:
+        """The cached document if one exists and is inside its TTL."""
+        document = self._document
+        fetched_at = self._fetched_at
+        if (
+            document is not None
+            and fetched_at is not None
+            and (time.monotonic() - fetched_at) < self._ttl_seconds
+        ):
+            return document
+        return None
+
+    def _backoff_error(self) -> BaseException | None:
+        """The recorded fetch fault while the backoff window is open."""
+        failed_until = self._failed_until
+        last_error = self._last_error
+        if (
+            failed_until is not None
+            and last_error is not None
+            and time.monotonic() < failed_until
+        ):
+            return last_error
+        return None
+
+    def _refetch_throttled(self) -> bool:
+        """Whether a forced refetch ran too recently to run another."""
+        forced_at = self._forced_at
+        return forced_at is not None and (
+            time.monotonic() - forced_at
+        ) < self._kid_refetch_seconds
+
+    async def _fetch_locked(self, *, force: bool) -> dict[str, object]:
+        """Run ONE fetch attempt (caller holds the lock) and record it.
+
+        A failed fetch starts the ``backoff_seconds`` window and is
+        re-raised; a successful one stores the document, restarts the
+        TTL and clears the backoff.  A forced attempt stamps
+        ``_forced_at`` so the ``kid_refetch_seconds`` interval bounds
+        how often forced refetches may run back-to-back.
+        """
+        if force:
+            self._forced_at = time.monotonic()
+        try:
+            document = await self._fetcher(self._url)
+        except Exception as error:
+            self._failed_until = time.monotonic() + self._backoff_seconds
+            self._last_error = error
+            raise
+        self._document = document
+        self._fetched_at = time.monotonic()
+        self._failed_until = None
+        self._last_error = None
+        return document
+
+
+#: 403 detail for the panel service token on an admin route.  Deliberately
+#: non-leaking: it names the credential TYPE, not its value or where it came
+#: from.  403 (not 401) because this is a REFUSED credential type, not an
+#: absent/invalid one — challenging re-authentication would suggest the same
+#: credential could work with a retry, which it never can here.
+_PANEL_TOKEN_REJECTION_DETAIL = "This credential type is not accepted for admin access"
+
+#: 403 detail for a valid JWT that is not a member of the admin group.
+#: Distinct from the uniform 401 on purpose: the token AUTHENTICATED, but
+#: the caller is not AUTHORIZED, so the response may say so.
+_FORBIDDEN_DETAIL = "Admin access requires membership in the nestquest-admins group"
+
+
+def _reject() -> HTTPException:
+    """Build the single 401 the dependency raises for every failure."""
+    return HTTPException(
+        status_code=401,
+        detail=_REJECTION_DETAIL,
+        headers=_WWW_AUTHENTICATE,
+    )
+
+
+def _matching_key(jwks: dict[str, object], kid: str) -> object | None:
+    """Return the RSA signing key named ``kid`` from the JWKS.
+
+    Only ``kty: RSA`` entries are considered (the pinned RS256 scheme
+    is asymmetric RSA); anything else — a missing ``keys`` list, no
+    entry with that ``kid`` — returns ``None`` rather than falling back
+    to "some" key.  The key is built through PyJWT's JWKS decoder, and
+    an entry that MATCHES the ``kid`` but carries corrupt key material
+    (a malformed ``n``/``e`` raises ``ValueError`` — ``binascii.Error``
+    is its subclass — or ``TypeError`` instead of a ``PyJWTError``) is
+    mapped to the one 401 like every other rejection: the caller must
+    never see a half-built key.
+    """
+    keys = jwks.get("keys")
+    if not isinstance(keys, list):
+        raise _reject()
+    for entry in keys:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("kid") != kid or entry.get("kty") != "RSA":
+            continue
+        try:
+            return jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(entry))
+        except (
+            jwt.PyJWTError,
+            binascii.Error,
+            ValueError,
+            TypeError,
+            KeyError,
+        ):
+            raise _reject() from None
+    return None
+
+
+async def verify_admin_token(
+    request: Request, token: str
+) -> dict[str, object]:
+    """Verify ONE admin bearer token and return its verified claims.
+
+    Reads the OIDC settings off ``app.state.config`` and the JWKS cache
+    off ``app.state.jwks_cache`` (both installed by
+    :func:`api.app.create_app`) so the check carries no module state.
+    A missing config or cache, an EMPTY configured issuer/audience/JWKS
+    URL, a non-RS256 ``alg`` header, an absent ``kid``, an unknown
+    ``kid``, and any PyJWT verification failure (bad signature,
+    expired, wrong issuer, wrong audience, not-yet-valid, missing
+    ``exp``) raise the SAME 401 — the failure mode is never leaked.
+    ``exp`` is REQUIRED (a token that never expires is never accepted)
+    and PyJWT enforces ``nbf`` when the token carries it.
+
+    The token's HEADER (``alg``, ``kid``) is parsed and enforced BEFORE
+    the JWKS cache is consulted, so a structurally invalid token costs
+    no fetch, no lock, no provider load.  When the cached document has
+    no entry for the ``kid``, ONE forced (TTL-bypassing, throttled)
+    refetch is made and the match retried once — a rotated key is
+    picked up without waiting out the TTL — before the 401.
+
+    A JWKS fetch failure propagates (see the module docstring): the
+    provider being down is a server fault, not a bad credential.
+    """
+    config = getattr(request.app.state, "config", None)
+    if (
+        config is None
+        or not config.oidc_issuer
+        or not config.oidc_audience
+        or not config.oidc_jwks_url
+    ):
+        raise _reject()
+    cache = getattr(request.app.state, "jwks_cache", None)
+    if cache is None:
+        raise _reject()
+    try:
+        header = jwt.get_unverified_header(token)
+    except jwt.PyJWTError:
+        raise _reject() from None
+    if header.get("alg") != _ALLOWED_ALGORITHM:
+        raise _reject()
+    kid = header.get("kid")
+    if not isinstance(kid, str) or not kid:
+        raise _reject()
+    jwks = await cache.get()
+    try:
+        key = _matching_key(jwks, kid)
+        if key is None:
+            # The kid is not in the cached document: force ONE
+            # TTL-bypassing refetch (bounded by the cache) and retry
+            # the match once before rejecting.
+            jwks = await cache.get(force=True)
+            key = _matching_key(jwks, kid)
+            if key is None:
+                raise _reject()
+        claims = jwt.decode(
+            token,
+            key=key,
+            algorithms=[_ALLOWED_ALGORITHM],
+            issuer=config.oidc_issuer,
+            audience=config.oidc_audience,
+            options={"require": ["exp"]},
+        )
+    except jwt.PyJWTError:
+        raise _reject() from None
+    return claims
+
+
+async def require_admin_jwt(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, object]:
+    """Reject the request with 401 unless it carries a valid admin JWT.
+
+    Extracts the Bearer credential — a missing or malformed
+    ``Authorization`` header (wrong scheme, empty credential) raises
+    the one 401 — and delegates the verification to
+    :func:`verify_admin_token`, returning the verified claims for the
+    route to use (the probe route surfaces the token's ``sub``).
+
+    The nestquest-admins GROUP check lives in :func:`require_admin`,
+    which wraps this dependency; ``require_admin_jwt`` remains the plain
+    JWT-validation contract — the 401 path stays exactly this uniform.
+    """
+    if authorization is None:
+        raise _reject()
+    scheme, _, credential = authorization.partition(" ")
+    if scheme.lower() != _BEARER_SCHEME or not credential.strip():
+        raise _reject()
+    return await verify_admin_token(request, credential.strip())
+
+
+async def require_admin(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, object]:
+    """The ONE admin-plane dependency: service-token refusal + group gate.
+
+    Order matters.  FIRST the Bearer credential is compared against the
+    configured panel service token (``app.state.config.panel_token``):
+    a match is refused OUTRIGHT with 403 — BEFORE any JWT parsing — so
+    the panel credential is never even treated as a JWT candidate, let
+    alone a non-admin JWT.  (403 rather than 401 because this is a
+    refused credential TYPE, not an invalid one: challenging
+    re-authentication would imply retrying could ever succeed; the
+    detail names the type only, never the value.)  A config with an
+    EMPTY panel token never matches anything, so it cannot lock every
+    Bearer request out.
+
+    Otherwise the credential goes through the existing JWT path
+    (:func:`require_admin_jwt` → :func:`verify_admin_token`): a missing
+    or malformed header and any invalid JWT still yield the SAME
+    uniform 401 as before.  A VALID JWT is then checked for
+    authorization: its ``groups`` claim must be a list containing
+    :data:`ADMIN_GROUP` — a missing, empty, or non-list ``groups`` or
+    one without the group raises 403 (distinct from the 401 on
+    purpose: the token authenticated, the caller did not authorize).
+
+    Returns the verified claims for the route.
+    """
+    if authorization is not None:
+        scheme, _, credential = authorization.partition(" ")
+        if scheme.lower() == _BEARER_SCHEME and credential.strip():
+            config = getattr(request.app.state, "config", None)
+            if (
+                config is not None
+                and config.panel_token
+                # compare_digest on bytes (as require_panel_token does)
+                # so the refusal does not short-circuit on the first
+                # mismatching byte — a constant-time comparison keeps a
+                # timing side channel on the credential off the table.
+                and secrets.compare_digest(
+                    credential.strip().encode("utf-8"),
+                    config.panel_token.encode("utf-8"),
+                )
+            ):
+                raise HTTPException(
+                    status_code=403,
+                    detail=_PANEL_TOKEN_REJECTION_DETAIL,
+                )
+    claims = await require_admin_jwt(request, authorization)
+    groups = claims.get("groups")
+    if not isinstance(groups, list) or ADMIN_GROUP not in groups:
+        raise HTTPException(status_code=403, detail=_FORBIDDEN_DETAIL)
+    return claims
+
+
+__all__ = [
+    "ADMIN_GROUP",
+    "JwksCache",
+    "JwksFetcher",
+    "require_admin",
+    "require_admin_jwt",
+    "verify_admin_token",
+]

api/config.py

@@ -0,0 +1,174 @@
+"""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.
+- ``NESTQUEST_OIDC_ISSUER`` — the Authentik OIDC issuer URL whose
+  ``iss`` claim admin tokens must carry (D-012 admin plane).
+- ``NESTQUEST_OIDC_AUDIENCE`` — the OIDC client id the admin tokens
+  must carry as their ``aud`` claim (the API service's client id).
+- ``NESTQUEST_OIDC_JWKS_URL`` — the Authentik endpoint serving the
+  signing keys (the JWKS document) the admin tokens' signatures are
+  verified against.  Cached per app (see :class:`api.auth.JwksCache`).
+
+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, a default (or empty) service token
+would either authenticate everyone or lock the panel plane out for
+good, and a default (or empty) OIDC setting would silently leave the
+admin plane trusting an issuer that was never configured.  All five
+variables are therefore REQUIRED — ``ApiConfig.from_env`` RAISES when
+any of them 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"
+
+#: Environment variable holding the Authentik OIDC issuer URL (D-012
+#: admin plane): every admin JWT's ``iss`` claim must equal it.  Checked
+#: by :func:`api.auth.require_admin_jwt`.  REQUIRED — unset or empty
+#: raises :class:`ConfigError` from :meth:`ApiConfig.from_env`; a default
+#: issuer would silently make the admin plane trust tokens from an
+#: issuer nobody configured.
+OIDC_ISSUER_ENV = "NESTQUEST_OIDC_ISSUER"
+
+#: Environment variable holding the OIDC audience (the API service's
+#: client id at Authentik): every admin JWT's ``aud`` claim must carry
+#: it.  Checked by :func:`api.auth.require_admin_jwt`.  REQUIRED — unset
+#: or empty raises :class:`ConfigError` from :meth:`ApiConfig.from_env`.
+OIDC_AUDIENCE_ENV = "NESTQUEST_OIDC_AUDIENCE"
+
+#: Environment variable holding the Authentik JWKS URL: the endpoint
+#: serving the signing keys admin JWT signatures are verified against.
+#: Fetched and cached by :class:`api.auth.JwksCache`.  REQUIRED — unset
+#: or empty raises :class:`ConfigError` from :meth:`ApiConfig.from_env`;
+#: without the provider's keys no token can be verified, so a silent
+#: default would only move the failure to request time.
+OIDC_JWKS_URL_ENV = "NESTQUEST_OIDC_JWKS_URL"
+
+
+class ConfigError(RuntimeError):
+    """Raised when required API configuration is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class ApiConfig:
+    """Resolved API configuration.
+
+    Every field is required (no defaults): ``from_env`` rejects an
+    unset or empty value for each, and a caller building the dataclass
+    directly must pass explicit values — the token check and the JWT
+    checks themselves fail closed on empty configured values, but
+    expecting a caller to discover that at request time is a wiring
+    mistake, so every field is mandatory.  Kept as a dataclass so later
+    tasks (SSE, settings persistence) can extend it without touching
+    the call sites that read ``db_path``.
+    """
+
+    db_path: str
+    panel_token: str
+    #: The Authentik OIDC issuer URL admin tokens' ``iss`` must equal.
+    oidc_issuer: str
+    #: The OIDC audience (the API service's client id) admin tokens'
+    #: ``aud`` must carry.
+    oidc_audience: str
+    #: The Authentik JWKS URL the signing keys are fetched from.
+    oidc_jwks_url: 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 ANY of the five variables is
+        unset or empty/whitespace-only — there is no silent default:
+
+        - ``NESTQUEST_DB_PATH``: a default in the temp directory would
+          silently lose data at reboot;
+        - ``NESTQUEST_PANEL_TOKEN``: a default token is never invented —
+          the panel plane is closed until a real one is configured;
+        - the three OIDC variables: an unconfigured issuer/audience/JWKS
+          URL must not silently leave the admin plane open (a default
+          JWKS URL or issuer would point at a provider nobody set up).
+        """
+        source = env if env is not None else os.environ
+
+        def require(env_var: str, reason: str) -> str:
+            """Return the stripped env value or raise ConfigError."""
+            value = source.get(env_var, "").strip()
+            if not value:
+                raise ConfigError(f"{env_var} {reason}")
+            return value
+
+        return cls(
+            db_path=require(
+                DB_PATH_ENV,
+                "must be set to a writable SQLite file path (it is unset "
+                "or empty — the API will not fall back to a temp directory "
+                "and silently lose data)",
+            ),
+            panel_token=require(
+                PANEL_TOKEN_ENV,
+                "must be set to the panel service token (it is unset or "
+                "empty — the API will not start without one, and no "
+                "default token is invented)",
+            ),
+            oidc_issuer=require(
+                OIDC_ISSUER_ENV,
+                "must be set to the Authentik OIDC issuer URL (it is "
+                "unset or empty — the admin plane will not trust tokens "
+                "from an issuer nobody configured)",
+            ),
+            oidc_audience=require(
+                OIDC_AUDIENCE_ENV,
+                "must be set to the OIDC audience the admin tokens carry "
+                "(it is unset or empty — the admin plane will not accept "
+                "tokens without a configured audience)",
+            ),
+            oidc_jwks_url=require(
+                OIDC_JWKS_URL_ENV,
+                "must be set to the Authentik JWKS URL (it is unset or "
+                "empty — admin token signatures cannot be verified "
+                "without the provider's signing keys)",
+            ),
+        )
+
+
+__all__ = [
+    "ApiConfig",
+    "ConfigError",
+    "DB_PATH_ENV",
+    "OIDC_AUDIENCE_ENV",
+    "OIDC_ISSUER_ENV",
+    "OIDC_JWKS_URL_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,228 @@
+"""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 read-only history layer (``core.history.query_history``,
+#: ``export_history_csv``, ``rows_to_csv``) the admin plane's history
+#: query and CSV export routes call.
+core_history = importlib.import_module(f"{_CORE_MODULE_NAME}.history")
+
+#: 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")
+
+#: The durable settings store (``core.settings_store.load_settings`` /
+#: ``update_settings``) the admin plane's settings routes read and
+#: write — the API's OWN settings source: a validated JSON document in
+#: the existing ``nestquest_meta_state`` table, resolved through the
+#: same core settings validators (the integration's HA config-entry
+#: options remain a temporary separate source until Feature 18 wires
+#: the client to the API).
+core_settings_store = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.settings_store"
+)
+
+#: The children business layer (``core.children.create_child`` et al.)
+#: the admin plane's children routes call.
+core_children = importlib.import_module(f"{_CORE_MODULE_NAME}.children")
+
+#: The quest-definition business layer (``core.quest_definitions`` —
+#: ``create_quest_definition``, ``edit_quest_definition``,
+#: ``set_quest_definition_active``) the admin plane's quest-definition
+#: routes call.
+core_quest_definitions = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.quest_definitions"
+)
+
+#: The recurrence model (``core.recurrence.ScheduleRule`` and
+#: ``RuleValidationError``) the quest-definition routes build request
+#: rules with — the model validates at construction, the routes never
+#: re-implement rule validation.
+core_recurrence = importlib.import_module(f"{_CORE_MODULE_NAME}.recurrence")
+
+#: The presence model (``core.presence.PresenceEngine``,
+#: ``PresenceSchedule``, ``PresenceOverride``) the admin plane's
+#: presence routes serialize and the tests resolve presence with.
+core_presence = importlib.import_module(f"{_CORE_MODULE_NAME}.presence")
+
+#: The presence-write business layer
+#: (``core.presence_management.set_presence_schedule`` et al.) the
+#: admin plane's presence routes call — the ONE implementation the HA
+#: services share.
+core_presence_management = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.presence_management"
+)
+
+#: The typed presence DAOs (``core.dao_presence``) the admin-plane tests
+#: read stored schedules and overrides back through.
+core_dao_presence = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.dao_presence"
+)
+
+#: The materialization walk (``core.materialize.materialize``,
+#: ``regenerate_for_definition``, ``regenerate_for_child``) the admin
+#: plane's regenerate route calls — the same walk the integration's
+#: config/presence changes trigger.
+core_materialize = importlib.import_module(f"{_CORE_MODULE_NAME}.materialize")
+
+#: The core constants module (``core.const.DEFAULT_HORIZON_DAYS``) the
+#: regenerate route sizes the household rolling horizon with.
+core_const = importlib.import_module(f"{_CORE_MODULE_NAME}.const")
+
+#: The typed child DAO (``core.dao_children.ChildrenDao.get``) the
+#: regenerate route reads a child's existence with before delegating.
+core_dao_children = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.dao_children"
+)
+
+#: The typed definition DAO (``core.dao_rules.QuestDefinitionsDao.get``)
+#: the regenerate route reads a definition's existence with before
+#: delegating.
+core_dao_rules = importlib.import_module(f"{_CORE_MODULE_NAME}.dao_rules")
+
+#: The HA-free missed sweep (``core.sweep.run_missed_sweep`` +
+#: ``SWEEP_WATERMARK_KEY``) the admin plane's trigger route calls and
+#: the daily scheduler runs — the ONE sweep policy the integration's
+#: bus shim shares.
+core_sweep = importlib.import_module(f"{_CORE_MODULE_NAME}.sweep")
+
+__all__ = [
+    "core",
+    "core_children",
+    "core_completion",
+    "core_const",
+    "core_dao_children",
+    "core_dao_presence",
+    "core_dao_rules",
+    "core_db",
+    "core_events",
+    "core_history",
+    "core_materialize",
+    "core_migrations",
+    "core_presence",
+    "core_presence_management",
+    "core_quest_definitions",
+    "core_recurrence",
+    "core_snapshot",
+    "core_settings",
+    "core_settings_store",
+    "core_sweep",
+]

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/scheduler.py

@@ -0,0 +1,173 @@
+"""Daily missed-sweep background scheduler for the API service.
+
+The API service has no Home Assistant, so nobody re-fires the
+integration's day-rollover listener for it: this module owns the API
+plane's own background job.  One :class:`MissedSweepScheduler` per app
+(installed on ``app.state`` by the lifespan) sleeps until the
+configured ``day_rollover_time`` — read fresh from the settings store
+at the top of EVERY cycle, so an admin's settings change applies on
+the next scheduling decision without a restart — then runs the
+HA-free core's :func:`nestquest_core.sweep.run_missed_sweep` for the
+API host's local date and publishes each returned
+``nestquest_quest_missed`` event on the app's ONE transition publisher
+(the same SSE stream every route publishes through).
+
+All sweep policy lives in the core (the watermark, the
+``[watermark, today)`` window, the no-completion-event rule): this
+scheduler only decides WHEN.  A same-night rerun — e.g. two workers,
+or a settings change moving the rollover past itself — fires nothing:
+the core's watermark makes the run an empty no-op.
+
+Testability: ``clock`` (an aware-now callable) and ``sleep`` (an
+awaitable delay) are injectable, so tests pin the time, fast-forward
+through the wait, and observe the computed delays without waiting a
+real day.  Cancellation: :meth:`stop` cancels the loop task and waits
+for it, so the lifespan's shutdown is clean and a mid-run sweep is
+interrupted before the connection closes.  A failed iteration (a
+database hiccup, a rejected setting) is logged and retried after a
+fixed backoff rather than silently killing the job.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import logging
+
+from api.nestquest_core import core_settings_store, core_sweep
+
+LOGGER = logging.getLogger(__name__)
+
+#: Backoff after a failed scheduling cycle (settings read or sweep
+#: error), so a persistent failure retries every minute instead of
+#: spinning or dying.
+_RETRY_BACKOFF_SECONDS = 60.0
+
+
+def _delay_seconds(target: datetime.time, now: datetime.datetime) -> float:
+    """Seconds from ``now`` until the next occurrence of ``target``.
+
+    ``target`` is a plain ``HH:MM`` time of day: the next wall-clock
+    occurrence strictly AFTER ``now`` (an equal time schedules for
+    tomorrow, so the just-run sweep is never instantly re-run).
+    """
+    scheduled = now.replace(
+        hour=target.hour, minute=target.minute, second=0, microsecond=0
+    )
+    if scheduled <= now:
+        scheduled += datetime.timedelta(days=1)
+    return (scheduled - now).total_seconds()
+
+
+class MissedSweepScheduler:
+    """Run the missed sweep once per day at ``day_rollover_time``."""
+
+    def __init__(
+        self,
+        database: object,
+        *,
+        publisher: object | None = None,
+        clock: object | None = None,
+        sleep: object | None = None,
+    ) -> None:
+        """Create the scheduler (not yet running).
+
+        ``database`` is the app's live :class:`~api.database.NestQuestDatabase`.
+        ``publisher`` is the app's ONE
+        :class:`~api.events.TransitionPublisher` (publishing is skipped
+        when ``None``).  ``clock`` defaults to the API host's local
+        aware now (``datetime.datetime.now().astimezone()``) — the same
+        single-clock discipline the routes' ``_local_now`` uses;
+        ``sleep`` defaults to :func:`asyncio.sleep`.
+        """
+        self._database = database
+        self._publisher = publisher
+        self._clock = clock if clock is not None else (
+            lambda: datetime.datetime.now().astimezone()
+        )
+        self._sleep = sleep if sleep is not None else asyncio.sleep
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        """Start the background loop (idempotent: a running one stays)."""
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(
+                self._run_forever(), name="nestquest-missed-sweep"
+            )
+
+    async def stop(self) -> None:
+        """Cancel the loop and wait for it to finish (safe if never started)."""
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+
+    @property
+    def running(self) -> bool:
+        """Whether the background loop task is alive."""
+        return self._task is not None and not self._task.done()
+
+    async def _run_forever(self) -> None:
+        """Schedule → sweep → repeat, forever (until cancelled)."""
+        while True:
+            try:
+                settings = await core_settings_store.load_settings(
+                    self._database
+                )
+                rollover = datetime.time.fromisoformat(
+                    settings.day_rollover_time
+                )
+            except Exception:
+                # Not silent: the failure is logged and retried after
+                # the backoff, so one bad settings document or a
+                # transient database error never kills the scheduler.
+                LOGGER.exception(
+                    "NestQuest missed-sweep scheduler failed to resolve "
+                    "the day rollover time; retrying in %gs",
+                    _RETRY_BACKOFF_SECONDS,
+                )
+                await self._sleep(_RETRY_BACKOFF_SECONDS)
+                continue
+            delay = _delay_seconds(rollover, self._clock())
+            LOGGER.info(
+                "NestQuest missed sweep scheduled for %s (%.0fs from now)",
+                settings.day_rollover_time,
+                delay,
+            )
+            await self._sleep(delay)
+            try:
+                await self._run_once(self._clock().date())
+            except Exception:
+                # Not silent either: the sweep error is logged and the
+                # loop backs off before the next cycle, whose watermark
+                # re-read makes an already-swept day a no-op.
+                LOGGER.exception(
+                    "NestQuest scheduled missed sweep failed; retrying in "
+                    "%gs",
+                    _RETRY_BACKOFF_SECONDS,
+                )
+                await self._sleep(_RETRY_BACKOFF_SECONDS)
+
+    async def _run_once(self, today: datetime.date) -> None:
+        """Run ONE sweep for ``today`` and publish what it built.
+
+        A failure propagates to :meth:`_run_forever`, which logs it and
+        backs off before the next cycle; the watermark makes a re-run
+        of an already-swept day announce nothing twice.
+        """
+        events = await core_sweep.run_missed_sweep(
+            self._database, today=today
+        )
+        for event_type, payload in events:
+            if self._publisher is not None:
+                self._publisher.publish(event_type, payload)
+        LOGGER.info(
+            "NestQuest scheduled missed sweep for %s published %d event(s)",
+            today.isoformat(),
+            len(events),
+        )
+
+
+__all__ = ["MissedSweepScheduler"]

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

@@ -1,4 +1,14 @@
-"""The NestQuest integration."""
+"""The NestQuest integration (Feature 18: a thin client of the NestQuest API service).
+
+The integration owns NO database: the API service (Feature 16) owns the
+SQLite file, the migrations, and every business rule.  Setup builds the
+entry's ONE shared API client, the coordinator that polls the panel
+snapshot through it, and the SSE subscription that re-fires the API's
+transition frames on the HA bus, registers the single
+``nestquest.complete_quest`` proxy service, registers the zero-config
+panel dashboard (Feature 20), and forwards the sensor and
+binary_sensor platforms.
+"""
 from __future__ import annotations
 
 import inspect
@@ -8,8 +18,22 @@ from typing import Any
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryNotReady
 
-from .const import DOMAIN, LOGGER
+from .const import (
+    CONF_SNAPSHOT_STALENESS,
+    CONF_UPDATE_INTERVAL,
+    DEFAULT_SNAPSHOT_STALENESS,
+    DEFAULT_UPDATE_INTERVAL,
+    DOMAIN,
+    LOGGER,
+    PLATFORMS,
+)
+from .coordinator import NestQuestCoordinator, coordinator_client_from_entry
+from .dashboard import async_register_dashboard
+from .frontend import async_register_frontend
+from .services import async_deregister_services, async_register_services
+from .sse import NestQuestEventStream
 
 _LOGGER = LOGGER
 
@@ -19,17 +43,59 @@ class NestQuestRuntimeData:
     """Runtime data stored on a NestQuest config entry."""
 
     entry_id: str
-    options: dict[str, Any]
     remove_update_listener: Callable[[], Any]
+    coordinator: Any = None
+    event_stream: NestQuestEventStream | None = None
+
+
+def _find_live_runtime_data(hass: HomeAssistant) -> NestQuestRuntimeData | None:
+    """Return a live runtime record with a coordinator, or None.
+
+    The domain-global service (the panel completion proxy) has no
+    database of its own; it resolves whichever config entry's runtime
+    data is currently live at call time, so it cannot hold a stale
+    handle to an unloaded entry's coordinator.
+    """
+    for runtime_data in hass.data.get(DOMAIN, {}).values():
+        if getattr(runtime_data, "coordinator", None) is not None:
+            return runtime_data
+    return None
+
+
+def _register_services(hass: HomeAssistant) -> None:
+    """Register the domain-global NestQuest service once.
+
+    The service is DOMAIN-global — registered exactly once (guarded by
+    ``has_service``) and NOT bound to any config entry — so the panel
+    completion proxy resolves the currently-live runtime at call time
+    and a name collision or duplicate setup is impossible.  Removal is
+    handled by the unload path only once the LAST entry is removed
+    (see :func:`_deregister_services`).
+    """
+    async_register_services(hass, find_runtime=_find_live_runtime_data)
+
+
+def _deregister_services(hass: HomeAssistant) -> None:
+    """Remove domain-global NestQuest services when the last entry unloads."""
+    async_deregister_services(hass)
 
 
 async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
     """Set up the NestQuest integration. YAML configuration is not used, returns True."""
+    await async_register_frontend(hass)
     return True
 
 
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up NestQuest from a config entry."""
+    await async_register_frontend(hass)
+    # The zero-config panel dashboard (Feature 20): register the
+    # storage-mode strategy dashboard if no dashboard under the stable
+    # url_path exists yet.  Unavailability of the Lovelace dashboards
+    # collection (YAML mode, lovelace not loaded) logs a warning and
+    # NEVER fails setup; an existing dashboard — ours or the user's —
+    # is left untouched, so a reload cannot duplicate it.
+    await async_register_dashboard(hass)
     hass.data.setdefault(DOMAIN, {})
 
     async def _async_update_listener(
@@ -38,12 +104,115 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         """Reload the entry when its options change."""
         await listener_hass.config_entries.async_reload(listener_entry.entry_id)
 
-    runtime_data = NestQuestRuntimeData(
-        entry_id=entry.entry_id,
-        options=dict(entry.options),
-        remove_update_listener=entry.add_update_listener(_async_update_listener),
-    )
-    entry.runtime_data = runtime_data
+    remove_update_listener: Callable[[], Any] | None = None
+    coordinator: Any = None
+    event_stream: NestQuestEventStream | None = None
+    try:
+        remove_update_listener = entry.add_update_listener(_async_update_listener)
+        _register_services(hass)
+        # ONE API client for the entry, shared by the coordinator's
+        # snapshot polling, the SSE subscription, and the completion
+        # proxy (the client is stateless — one session, one connection
+        # pool).  An entry with no panel token yet gets the
+        # typed-error stub (unavailable entities, never a setup crash).
+        api_client = coordinator_client_from_entry(hass, entry)
+        # The shared coordinator: one refresh cycle every entity reads
+        # from (CONF_UPDATE_INTERVAL seconds, default five minutes).
+        # It polls the API service's panel snapshot; a failed poll
+        # keeps the entities rendering the last-good snapshot within
+        # CONF_SNAPSHOT_STALENESS, unavailable past it.
+        coordinator = NestQuestCoordinator(
+            hass,
+            entry_id=entry.entry_id,
+            api_client=api_client,
+            update_interval_seconds=entry.options.get(
+                CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL
+            ),
+            staleness_seconds=entry.options.get(
+                CONF_SNAPSHOT_STALENESS, DEFAULT_SNAPSHOT_STALENESS
+            ),
+        )
+        # The panel event subscription (the SSE task): a background
+        # task consumes the API service's transition-event stream and
+        # re-fires the four documented HA bus events.  It reuses the
+        # coordinator's client, so it only starts when that client
+        # actually offers a stream — an unconfigured-token stub (or a
+        # test snapshot client without ``stream_events``) leaves it
+        # unstarted, and the typed-error path already covers
+        # availability for those entries.
+        if callable(getattr(api_client, "stream_events", None)):
+            event_stream = NestQuestEventStream(hass, api_client)
+            event_stream.start()
+        runtime_data = NestQuestRuntimeData(
+            entry_id=entry.entry_id,
+            remove_update_listener=remove_update_listener,
+            coordinator=coordinator,
+            event_stream=event_stream,
+        )
+        # The runtime record is registered BEFORE the first refresh:
+        # the service proxy resolves the entry's runtime state through
+        # hass.data, and it must find the live coordinator there —
+        # never a half-set-up entry.  The platforms forward below reads
+        # the coordinator off the entry (the HA runtime-data contract);
+        # a forward failure below unwinds it through the except path.
+        hass.data[DOMAIN][entry.entry_id] = runtime_data
+        entry.runtime_data = runtime_data
+        # The first refresh polls the API snapshot; an API failure
+        # (unconfigured token, API service down) does NOT crash setup:
+        # the coordinator reports last_update_success=False, entities
+        # come up unavailable, and HA's standard retry cycle applies
+        # once the API is reachable.  HA's real
+        # ``async_config_entry_first_refresh`` wraps ANY failed update
+        # pass in ConfigEntryNotReady — the original error survives
+        # only as ``__cause__``, never as the raised exception — so the
+        # catch keys on ConfigEntryNotReady, NOT on the typed API
+        # error.  Everything else (a platform-forward failure,
+        # cancellation) still unwinds through the except block below.
+        try:
+            await coordinator.async_config_entry_first_refresh()
+        except ConfigEntryNotReady:
+            pass
+        await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+    except BaseException:
+        # A failure anywhere after the listener was registered must not
+        # leak it (or the SSE task): unwind EVERYTHING acquired before
+        # the failure, keeping the original error as the one raised.
+        # Removal is best-effort — a failing step must not mask the
+        # setup error that triggered it.
+        if event_stream is not None:
+            try:
+                await event_stream.stop()
+            except BaseException:
+                pass
+        if remove_update_listener is not None:
+            try:
+                remove_update_listener()
+            except BaseException:
+                pass
+        # A coordinator created before the failure holds entity
+        # listeners pointed at the never-registered runtime — shut it
+        # down so no scheduled refresh outlives the failed setup.
+        if coordinator is not None:
+            try:
+                await coordinator.async_shutdown()
+            except BaseException:
+                pass
+        # A platform-forward failure reached this unwind AFTER
+        # runtime_data was assigned: clear it so no later unload path
+        # re-invokes the already-consumed update-listener remover
+        # through the stale record.
+        if getattr(entry, "runtime_data", None) is not None:
+            entry.runtime_data = None
+        # The runtime record was ALSO registered in hass.data before
+        # the first refresh: remove it here on ANY failure, or a later
+        # unload picks up the stale, already-torn-down record
+        # (hass.data wins over entry.runtime_data there) and
+        # re-invokes the already-consumed update-listener remover.
+        hass.data.get(DOMAIN, {}).pop(entry.entry_id, None)
+        raise
+    # The runtime record was already registered before the first
+    # refresh; re-assert the (unchanged) record so the return path
+    # stays readable as one registration site.
     hass.data[DOMAIN][entry.entry_id] = runtime_data
     return True
 
@@ -52,16 +221,63 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Unload a config entry."""
     domain_data = hass.data.setdefault(DOMAIN, {})
     runtime_data = domain_data.pop(entry.entry_id, None)
-    if not domain_data:
+    is_last = not domain_data
+    if is_last:
         hass.data.pop(DOMAIN, None)
     if runtime_data is None:
         runtime_data = getattr(entry, "runtime_data", None)
+    # Platforms unload FIRST (mirroring HA conventions): entity
+    # listeners must not outlive the coordinator the teardown below
+    # shuts down.
+    platforms_unloaded = await hass.config_entries.async_unload_platforms(
+        entry, PLATFORMS
+    )
+    if platforms_unloaded is False and runtime_data is not None:
+        # Home Assistant KEPT one or more platforms loaded — their
+        # entities still live and must keep their coordinator.  Restore
+        # the runtime record popped above and report failure so HA
+        # retries the unload later instead of leaving live entities
+        # backed by a torn-down coordinator.
+        hass.data.setdefault(DOMAIN, {})[entry.entry_id] = runtime_data
+        return False
+    unload_error: BaseException | None = None
     if runtime_data is not None:
-        remove_update_listener = getattr(runtime_data, "remove_update_listener", None)
-        if remove_update_listener is not None:
-            result = remove_update_listener()
-            if inspect.isawaitable(result):
-                await result
+        # The SSE subscription is stopped FIRST: its task must be gone
+        # (no frame can fire) before anything else is torn down.
+        event_stream = getattr(runtime_data, "event_stream", None)
+        if event_stream is not None:
+            stop_stream = getattr(event_stream, "stop", None)
+            if stop_stream is not None:
+                await stop_stream()
+        remove_update_listener = getattr(
+            runtime_data, "remove_update_listener", None
+        )
+        try:
+            if remove_update_listener is not None:
+                result = remove_update_listener()
+                if inspect.isawaitable(result):
+                    await result
+        except BaseException as err:
+            # A failing remover must not skip the coordinator shutdown
+            # below; the first error is retained and re-raised only
+            # after the teardown ran.
+            if unload_error is None:
+                unload_error = err
+        finally:
+            # The coordinator's entity listeners must stop here: a
+            # scheduled refresh must never outlive the unload.
+            coordinator = getattr(runtime_data, "coordinator", None)
+            if coordinator is not None:
+                shutdown = getattr(coordinator, "async_shutdown", None)
+                if shutdown is not None:
+                    await shutdown()
+    # Domain-global services are torn down only once the FINAL entry
+    # unloads (``hass.data[DOMAIN]`` is now empty), never when a sibling
+    # entry is still loaded.
+    if is_last:
+        _deregister_services(hass)
     if getattr(entry, "runtime_data", None) is not None:
         entry.runtime_data = None
+    if unload_error is not None:
+        raise unload_error
     return True

custom_components/nestquest/api_client.py

@@ -0,0 +1,414 @@
+"""Panel-plane API client for the NestQuest integration (Feature 18).
+
+The integration talks to the NestQuest API service (Feature 16) over
+HTTP instead of reading the database: this module is the ONE place that
+speaks the API's panel plane — ``GET /api/v1/panel/snapshot`` (today's
+household snapshot) and ``POST /api/v1/panel/instances/{id}/complete``
+(completion as the tapped child profile) — authenticated with the
+static panel service token as a Bearer credential on every request.
+
+Transport-injected by construction: the constructor takes the base URL,
+the panel token, and the HTTP session to use.  The session speaks the
+aiohttp ``ClientSession`` surface (``request(method, url, headers=...,
+json=...)`` returning an async context manager whose response carries
+``status`` and ``await text()``), so tests stub the transport with NO
+network and NO aiohttp installed; production builds the client through
+:func:`client_from_entry`, which hands in Home Assistant's shared
+aiohttp session (``homeassistant.helpers.aiohttp_client
+.async_get_clientsession``).  The module itself imports NEITHER
+homeassistant NOR aiohttp at runtime (aiohttp appears only behind
+``TYPE_CHECKING`` for annotations), so the client is usable anywhere —
+the HA coupling lives in the one production factory.
+
+Every failure is typed: a transport failure (connection refused, DNS
+failure, timeout — the exchange never produced a response) and every
+non-2xx HTTP response raise :class:`NestQuestApiError`.  The error
+carries the HTTP status where there is one (so 401 and 404 are
+distinguishable at the call site) and ``None`` when there is not; the
+original transport error is chained as ``__cause__`` — nothing is
+swallowed.  There are NO retries and the client logs nothing: refresh
+cadence is the coordinator's concern (the next task), and the panel
+token is a secret that must never reach a log line or an error
+message — the error texts name the method, path, and status only.
+
+The panel plane's SSE event stream (``GET /api/v1/panel/events``) is
+exposed by :meth:`NestQuestApiClient.stream_events` — an async
+generator yielding ``(event_type, payload)`` per Server-Sent Events
+frame (``event: <type>`` / ``data: <json>`` lines separated by a blank
+line).  Opening the stream gets the same one-timeout, typed-error
+contract as every other call; reading it has NO body-wide timeout (a
+healthy stream is long-lived — the subscription manager owns
+reconnection and backoff).
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+from .const import (
+    CONF_API_BASE_URL,
+    CONF_PANEL_TOKEN,
+    DEFAULT_API_BASE_URL,
+    DEFAULT_PANEL_TOKEN,
+)
+
+if TYPE_CHECKING:
+    import aiohttp
+
+__all__ = [
+    "COMPLETE_INSTANCE_PATH",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "EVENTS_PATH",
+    "NestQuestApiError",
+    "NestQuestApiClient",
+    "SNAPSHOT_PATH",
+    "client_from_entry",
+    "is_valid_base_url",
+    "resolve_api_config",
+]
+
+#: The panel plane's snapshot route (Feature 16).
+SNAPSHOT_PATH = "/api/v1/panel/snapshot"
+
+#: The panel plane's SSE event-stream route (Feature 16): each
+#: transition arrives as an ``event: <type>`` / ``data: <json>`` frame.
+EVENTS_PATH = "/api/v1/panel/events"
+
+#: The panel plane's completion route template (Feature 16); the
+#: ``{instance_id}`` placeholder is filled per call.
+COMPLETE_INSTANCE_PATH = "/api/v1/panel/instances/{instance_id}/complete"
+
+#: Request timeout, in seconds.  One attempt, one timeout: a hung API
+#: call surfaces as a typed error for the coordinator to report, never
+#: a retry loop.
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+class NestQuestApiError(Exception):
+    """A failed NestQuest API exchange, raised for every failure mode.
+
+    ``status`` carries the HTTP status when a response arrived (a
+    non-2xx response — 401 for a bad token, 404 for an unknown
+    instance) and is ``None`` when the exchange failed at the transport
+    level (connection refused, DNS failure, timeout) — so callers
+    distinguish the two with ``is_transport_error``.  The original
+    transport error, where there is one, is chained as ``__cause__``.
+    Messages carry the method, path, and status — never the request
+    headers, so the panel token can never leak through an error.
+    """
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+    @property
+    def is_transport_error(self) -> bool:
+        """True when the exchange failed before any response arrived."""
+        return self.status is None
+
+
+def is_valid_base_url(value: object) -> bool:
+    """Return True when ``value`` is a usable API base URL.
+
+    A full ``http://`` or ``https://`` URL with a host — the exact
+    shape the options flow validates (form ergonomics) and the client
+    constructor enforces (fail fast, never build requests against a
+    scheme-less or host-less string).
+    """
+    if not isinstance(value, str):
+        return False
+    candidate = value.strip()
+    if not candidate:
+        return False
+    parsed = urlparse(candidate)
+    return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+
+
+def resolve_api_config(entry: Any) -> tuple[str, str]:
+    """Resolve ``(base_url, panel_token)`` off a config entry.
+
+    Precedence mirrors the options flow's stored-values resolution:
+    ``entry.options`` first (the live options-flow copy), then
+    ``entry.data`` (the config-flow-era copy), then the const defaults.
+    The token is a secret: callers must never log the returned pair.
+    """
+    options = getattr(entry, "options", None) or {}
+    data = getattr(entry, "data", None) or {}
+
+    def _pick(key: str, default: str) -> str:
+        if key in options:
+            return options[key]
+        if key in data:
+            return data[key]
+        return default
+
+    return (
+        _pick(CONF_API_BASE_URL, DEFAULT_API_BASE_URL),
+        _pick(CONF_PANEL_TOKEN, DEFAULT_PANEL_TOKEN),
+    )
+
+
+def client_from_entry(hass: Any, entry: Any) -> NestQuestApiClient:
+    """Build the production client for a config entry.
+
+    Reads the configured base URL and panel token off the entry
+    (:func:`resolve_api_config`) and hands the client Home Assistant's
+    SHARED aiohttp session (``homeassistant.helpers.aiohttp_client
+    .async_get_clientsession``) so panel calls ride HA's one connection
+    pool.  The helper import is deferred into this function on purpose:
+    the test harness is mock-only and the module must import (and the
+    client must be stub-transport testable) without homeassistant or
+    aiohttp installed.
+    """
+    from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+    base_url, panel_token = resolve_api_config(entry)
+    return NestQuestApiClient(
+        base_url, panel_token, async_get_clientsession(hass)
+    )
+
+
+class NestQuestApiClient:
+    """Async client for the NestQuest API service's panel plane.
+
+    ONE instance per config entry (the coordinator task wires it into
+    the refresh cycle).  The client is deliberately thin: it adds the
+    Bearer credential and the base URL, enforces one timeout per
+    request, and turns every failure into :class:`NestQuestApiError` —
+    no business logic, no retries, no caching.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        panel_token: str,
+        session: aiohttp.ClientSession,
+        *,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        """Store the connection settings; the session is injected.
+
+        ``session`` is an aiohttp ``ClientSession`` in production and a
+        stub transport in tests.  ``base_url`` must be a full http(s)
+        URL and ``panel_token`` must be non-empty — a client built
+        without either can only fail later at request time with a
+        less-explicable error, so construction fails fast instead.
+        """
+        if not is_valid_base_url(base_url):
+            raise ValueError(
+                f"base_url must be a full http(s) URL, got {base_url!r}"
+            )
+        if not isinstance(panel_token, str) or not panel_token.strip():
+            raise ValueError("panel_token must be a non-empty string")
+        if (
+            not isinstance(timeout_seconds, (int, float))
+            or isinstance(timeout_seconds, bool)
+            or timeout_seconds <= 0
+        ):
+            raise ValueError(
+                f"timeout_seconds must be a positive number, got {timeout_seconds!r}"
+            )
+        self._base_url = base_url.strip().rstrip("/")
+        self._panel_token = panel_token
+        self._session = session
+        self._timeout_seconds = float(timeout_seconds)
+
+    async def get_snapshot(self) -> dict[str, Any]:
+        """Fetch and parse today's household snapshot.
+
+        Returns the JSON the snapshot route returns (``today_iso``,
+        ``cycle_day``, and the per-child list — see
+        ``api/routes_panel.py`` for the documented shape).  Raises
+        :class:`NestQuestApiError` on transport failure, timeout, or a
+        non-2xx response.
+        """
+        return await self._request_json("GET", SNAPSHOT_PATH)
+
+    async def complete_instance(
+        self, instance_id: int, actor_child_id: int
+    ) -> dict[str, Any]:
+        """Complete one quest instance as the tapped child profile.
+
+        POSTs ``{"actor_child_id": actor_child_id}`` to the complete
+        route and returns the parsed response body (the route answers
+        ``{"status": ...}`` both for a first completion and for an
+        idempotent repeat, so a retried panel tap succeeds).  Raises
+        :class:`NestQuestApiError` on transport failure, timeout, or a
+        non-2xx response — 401 for a wrong token, 404 for an unknown
+        instance.
+        """
+        path = COMPLETE_INSTANCE_PATH.format(instance_id=instance_id)
+        return await self._request_json(
+            "POST", path, json_body={"actor_child_id": actor_child_id}
+        )
+
+    async def stream_events(
+        self,
+    ) -> AsyncIterator[tuple[str, dict[str, Any]]]:
+        """Yield ``(event_type, payload)`` for every panel SSE frame.
+
+        Opens ``GET /api/v1/panel/events`` with the Bearer credential
+        and parses the Server-Sent Events framing the API service
+        emits: ``event: <type>`` and ``data: <json>`` lines closed by a
+        blank line (one frame per transition event; a frame's ``data``
+        may span several ``data:`` lines, joined with newlines — the
+        standard SSE rule).  Line splits across chunk boundaries are
+        buffered, so frames are parsed correctly whatever chunking the
+        transport produces.
+
+        Opening the stream carries the SAME one-timeout, typed-error
+        contract as every other call: a non-2xx response raises
+        :class:`NestQuestApiError` with its status and a transport
+        failure (connection refused, DNS, the open timing out) raises
+        one with ``status=None`` and the original error chained.  The
+        reading loop itself has NO timeout — a healthy stream is
+        long-lived — but any failure raised from the transport
+        mid-stream raises typed as well, so the consumer can reconnect.
+        A frame whose ``data`` is not valid JSON is a protocol failure
+        and raises typed, carrying the response status it arrived
+        with.  Cancellation is never converted: closing the generator
+        (``aclose``, i.e. the consumer's task being cancelled) stops
+        cleanly and closes the underlying response in every path.
+        """
+        url = f"{self._base_url}{EVENTS_PATH}"
+        headers = {"Authorization": f"Bearer {self._panel_token}"}
+        # Opening the response gets ONE request timeout, exactly like
+        # ``_request_json``; the read loop below runs WITHOUT one — a
+        # body-wide timeout would kill a healthy long-lived stream.
+        # The response context manager is entered manually (not via
+        # ``async with``) because the block must span the yields below;
+        # the ``finally`` closes it on EVERY exit path.
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                stream_cm = self._session.request(
+                    "GET", url, headers=headers, json=None
+                )
+                response = await stream_cm.__aenter__()
+        except asyncio.CancelledError:
+            # Cancellation is never converted (see ``_request_json``).
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API GET {EVENTS_PATH} transport failure: {err}",
+                status=None,
+            ) from err
+
+        status = response.status
+        if not 200 <= status < 300:
+            await self._close_stream(stream_cm)
+            raise NestQuestApiError(
+                f"NestQuest API GET {EVENTS_PATH} failed with HTTP {status}",
+                status=status,
+            )
+
+        try:
+            event_type: str | None = None
+            data_lines: list[str] = []
+            buffer = ""
+            async for chunk in response:
+                if isinstance(chunk, (bytes, bytearray)):
+                    chunk = chunk.decode("utf-8")
+                buffer += chunk
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    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:
+                        # A blank line ends the frame.  A trailing
+                        # incomplete frame (stream ends without its
+                        # closing blank line) is discarded, per the
+                        # SSE spec's treatment of incomplete events.
+                        try:
+                            payload = json.loads("\n".join(data_lines))
+                        except ValueError as err:
+                            raise NestQuestApiError(
+                                f"NestQuest API GET {EVENTS_PATH} "
+                                f"delivered a malformed SSE frame: {err}",
+                                status=status,
+                            ) from err
+                        yield event_type, payload
+                        event_type = None
+                        data_lines = []
+        except asyncio.CancelledError:
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API GET {EVENTS_PATH} transport failure: {err}",
+                status=None,
+            ) from err
+        finally:
+            await self._close_stream(stream_cm)
+
+    @staticmethod
+    async def _close_stream(stream_cm: Any) -> None:
+        """Close an opened streaming response context manager.
+
+        Works for aiohttp's response context manager (whose
+        ``__aexit__`` is a coroutine) and for test stubs that return
+        either a coroutine or a plain value.
+        """
+        result = stream_cm.__aexit__(None, None, None)
+        if inspect.isawaitable(result):
+            await result
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        """Run ONE request and return the parsed JSON body.
+
+        The Bearer token rides the Authorization header only.  A
+        non-2xx response raises :class:`NestQuestApiError` with its
+        status; anything the transport raises (connection, timeout) is
+        wrapped as a transport-level :class:`NestQuestApiError` with
+        the original error chained — never swallowed, never retried.
+        A 2xx body that is not valid JSON is a protocol failure and
+        raises typed too, carrying the status it arrived with.
+        """
+        url = f"{self._base_url}{path}"
+        headers = {"Authorization": f"Bearer {self._panel_token}"}
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                async with self._session.request(
+                    method, url, headers=headers, json=json_body
+                ) as response:
+                    status = response.status
+                    if not 200 <= status < 300:
+                        raise NestQuestApiError(
+                            f"NestQuest API {method} {path} failed with "
+                            f"HTTP {status}",
+                            status=status,
+                        )
+                    body_text = await response.text()
+        except asyncio.CancelledError:
+            # Cancellation is never converted: a shutting-down event
+            # loop must stop, not read a synthesized API error.
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API {method} {path} transport failure: {err}",
+                status=None,
+            ) from err
+        try:
+            return json.loads(body_text)
+        except ValueError as err:
+            raise NestQuestApiError(
+                f"NestQuest API {method} {path} returned malformed "
+                f"JSON: {err}",
+                status=status,
+            ) from err

custom_components/nestquest/binary_sensor.py

@@ -0,0 +1,202 @@
+"""Per-child binary sensors (Feature 10, task 4).
+
+Two binary sensors per active child, both reading only the coordinator
+snapshot (the same ChildDaySnapshot the day sensors read):
+
+- ``binary_sensor.nestquest_<child>_all_done`` — ON exactly when the
+  child owes quests today (due today > 0) AND owes none of them any
+  more (remaining today == 0).  A zero-quest day is OFF: the
+  celebration automation must never fire on an empty day (the
+  day-complete event carries the same rule, Feature 10 task 7).
+- ``binary_sensor.nestquest_<child>_present_today`` — ON when the
+  presence engine resolves the child present on the HA-local date
+  (schedules and overrides, D-004 anchor-date arithmetic).
+
+Naming and registry identity follow the day sensors' contract: names
+slug to the documented entity_id shape; unique_ids are built from the
+child's database id, never the display name, so a rename never
+orphans an entity's history.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from homeassistant.components.binary_sensor import BinarySensorEntity
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity import DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+
+from .const import DOMAIN
+from .coordinator import ChildDaySnapshot, NestQuestCoordinator
+
+
+class _NestQuestChildBinarySensor(CoordinatorEntity, BinarySensorEntity):
+    """Base for the per-child binary sensors.
+
+    Registry identity is built from the child's database id and never
+    changes; the displayed name and device label re-derive from the
+    child's CURRENT snapshot on every read, so a rename propagates on
+    the next refresh without orphaning history.  A child absent from
+    the latest snapshot (a deactivation; removal is a later task's
+    scope) yields ``None`` states rather than stale values.
+    """
+
+    _name_suffix: str = ""
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator)
+        self._child_id = child.child_id
+        self._fallback_name = child.child_name
+
+    @property
+    def _child(self) -> ChildDaySnapshot | None:
+        """Return the child's current day snapshot, or None."""
+        data = self.coordinator.data
+        if data is None:
+            return None
+        for child in data.children:
+            if child.child_id == self._child_id:
+                return child
+        return None
+
+    def _displayed_child_name(self) -> str:
+        child = self._child
+        return child.child_name if child is not None else self._fallback_name
+
+    @property
+    def name(self) -> str | None:
+        return f"NestQuest {self._displayed_child_name()} {self._name_suffix}"
+
+    @property
+    def device_info(self) -> DeviceInfo:
+        return DeviceInfo(
+            identifiers={(DOMAIN, f"child_{self._child_id}")},
+            name=f"NestQuest {self._displayed_child_name()}",
+            manufacturer="NestQuest",
+        )
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        child = self._child
+        if child is None:
+            return None
+        return {
+            "child_id": child.child_id,
+            "child_name": child.child_name,
+        }
+
+
+class NestQuestAllDoneSensor(_NestQuestChildBinarySensor):
+    """ON when the child had quests today and owes none of them."""
+
+    _name_suffix = "all done"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = f"{DOMAIN}_child_{child.child_id}_all_done"
+
+    @property
+    def is_on(self) -> bool | None:
+        child = self._child
+        if child is None:
+            return None
+        # Zero-quest days are OFF, not ON: an empty day must never fire
+        # the celebration automation.
+        return child.due_today > 0 and child.remaining_today == 0
+
+
+class NestQuestPresentTodaySensor(_NestQuestChildBinarySensor):
+    """ON when the child is at this house today (presence engine)."""
+
+    _name_suffix = "present today"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = f"{DOMAIN}_child_{child.child_id}_present_today"
+
+    @property
+    def is_on(self) -> bool | None:
+        child = self._child
+        if child is None:
+            return None
+        return child.present
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        """Base attributes plus, 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)."""
+        base = super().extra_state_attributes
+        if base is None:
+            return None
+        child = self._child
+        return {**base, "next_present": child.next_present if child else None}
+
+
+def _child_binary_sensors(
+    coordinator: NestQuestCoordinator, child: ChildDaySnapshot
+) -> tuple[_NestQuestChildBinarySensor, ...]:
+    """Build the two documented binary sensors for one active child."""
+    return (
+        NestQuestAllDoneSensor(coordinator, child),
+        NestQuestPresentTodaySensor(coordinator, child),
+    )
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: ConfigEntry,
+    async_add_entities: Callable[..., None],
+) -> None:
+    """Create the two binary sensors per active child.
+
+    Entities are created for the snapshot's children at platform
+    setup; a coordinator listener adds sensors for children that first
+    appear on a later refresh (the day sensors' same pattern, so a new
+    child's whole entity set lands together).  Deactivated children
+    are NOT removed here — removal is a later task's scope.
+    """
+    coordinator = entry.runtime_data.coordinator
+    known_child_ids: set[int] = set()
+
+    def _add_new_children(children: Iterable[ChildDaySnapshot]) -> None:
+        new_children = [
+            child
+            for child in children
+            if child.child_id not in known_child_ids
+        ]
+        if not new_children:
+            return
+        known_child_ids.update(child.child_id for child in new_children)
+        async_add_entities(
+            [
+                sensor
+                for child in new_children
+                for sensor in _child_binary_sensors(coordinator, child)
+            ]
+        )
+
+    data = coordinator.data
+    if data is not None:
+        _add_new_children(data.children)
+
+    def _handle_coordinator_update() -> None:
+        data = coordinator.data
+        if data is not None:
+            _add_new_children(data.children)
+
+    coordinator.async_add_listener(_handle_coordinator_update)

custom_components/nestquest/blueprints/automation/afternoon_reminder.yaml

@@ -0,0 +1,90 @@
+blueprint:
+  name: NestQuest afternoon reminder
+  description: >-
+    Sends an afternoon nudge listing ONLY the children who still have
+    open quests today. Children who are present and all clear are
+    omitted (the nudge is for stragglers, not a roll call), children
+    who are not present today are omitted entirely, and the household
+    rollup sensors are excluded by the same present guard. When every
+    present child is already done the automation sends NOTHING at all:
+    a template condition stops the run before the notification. The
+    notify service is chosen by the household when importing this
+    blueprint — NestQuest never hard-codes a personal notify target.
+  domain: automation
+  input:
+    afternoon_time:
+      name: Afternoon time
+      description: Local time of day the reminder is sent.
+      default: "15:00"
+      selector:
+        time: {}
+    notify_target:
+      name: Notify service
+      description: >-
+        The Home Assistant notify service to call for the reminder,
+        for example notify.mobile_app_your_phone — a placeholder;
+        pick the notify service for your own device.
+      selector:
+        text: {}
+    send_reminder:
+      name: Send the reminder
+      description: >-
+        Turn off to keep the automation installed but skip the
+        notification entirely.
+      default: true
+      selector:
+        boolean: {}
+
+mode: single
+
+variables:
+  send_reminder: !input send_reminder
+
+triggers:
+  - trigger: time
+    at: !input afternoon_time
+
+conditions:
+  - condition: template
+    value_template: "{{ send_reminder | bool }}"
+  # Send nothing when every present child is already done: the guard is
+  # false unless at least one present child has remaining quests today.
+  - condition: template
+    value_template: |
+      {%- set ns = namespace(any_open=false) -%}
+      {%- for due in states.sensor
+            | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_due_today(_\\d+)?$') -%}
+        {%- if due.attributes.get('present') -%}
+          {%- set remaining_values = states.sensor
+                | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_remaining_today(_\\d+)?$')
+                | selectattr('attributes.child_id', 'eq', due.attributes.child_id)
+                | map(attribute='state')
+                | list -%}
+          {%- if remaining_values and (remaining_values | first | int) > 0 -%}
+            {%- set ns.any_open = true -%}
+          {%- endif -%}
+        {%- endif -%}
+      {%- endfor -%}
+      {{- ns.any_open -}}
+
+actions:
+  - action: !input notify_target
+    data:
+      title: NestQuest afternoon reminder
+      message: |
+        {%- set ns = namespace(lines=[]) -%}
+        {%- for due in states.sensor
+              | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_due_today(_\\d+)?$') -%}
+          {%- if due.attributes.get('present') -%}
+            {%- set remaining_values = states.sensor
+                  | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_remaining_today(_\\d+)?$')
+                  | selectattr('attributes.child_id', 'eq', due.attributes.child_id)
+                  | map(attribute='state')
+                  | list -%}
+            {%- if remaining_values and (remaining_values | first | int) > 0 -%}
+              {%- set line = due.attributes.child_name ~ ' still has ' ~ (remaining_values | first | int) ~ ' quest(s) open.' -%}
+              {%- set ns.lines = ns.lines + [line] -%}
+            {%- endif -%}
+          {%- endif -%}
+        {%- endfor -%}
+        {{- ns.lines | join('\n') -}}

custom_components/nestquest/blueprints/automation/day_complete_celebration.yaml

@@ -0,0 +1,109 @@
+blueprint:
+  name: NestQuest day complete celebration
+  description: >-
+    Celebrates the moment a child clears every quest for the day: the
+    automation is driven by the nestquest_child_day_complete event,
+    which NestQuest only fires when quests were owed and all of them
+    are complete — a zero-quest day can never trigger this
+    celebration. Once-per-child-per-day dedupe: point
+    last_celebrated_helper at ONE input_text helper (create it under
+    Settings, Devices and Services, Helpers — plain text). The
+    automation records each celebrated child as
+    "<child_id>:<today>" inside that helper, and a child who
+    un-completes a quest and completes it again the same day is
+    celebrated once, not twice — while a SECOND child clearing their
+    day the same date is still celebrated in full. The helper is
+    pruned to today's entries on every celebration, so it never
+    grows past one entry per child per day. A helper that does not
+    exist yet, or has never been set, lets the first celebration
+    through. The notification message may use the event payload's
+    child_name, quests_due and quests_completed. The notify service
+    is chosen by the household when importing this blueprint —
+    NestQuest never hard-codes a personal notify target.
+  domain: automation
+  input:
+    notify_target:
+      name: Notify service
+      description: >-
+        The Home Assistant notify service to call for the celebration,
+        for example notify.mobile_app_your_phone — a placeholder;
+        pick the notify service for your own device.
+      selector:
+        text: {}
+    celebration_message:
+      name: Celebration message
+      description: >-
+        The message sent when a child clears every quest today. May
+        use the event payload: trigger.event.data.child_name,
+        trigger.event.data.quests_due and trigger.event.data.quests_completed.
+      default: "Legendary! {{ trigger.event.data.child_name }} cleared every quest today!"
+      selector:
+        text: {}
+    celebrate:
+      name: Send the celebration
+      description: >-
+        Turn off to keep the automation installed but skip the
+        notification entirely.
+      default: true
+      selector:
+        boolean: {}
+    last_celebrated_helper:
+      name: Last-celebrated helper
+      description: >-
+        A single input_text helper remembering which children were
+        already celebrated today, as "<child_id>:<date>" entries
+        separated by commas. The automation skips a child whose entry
+        for today is already stored, and rewrites the helper with only
+        today's entries plus the new one after each celebration.
+      selector:
+        entity:
+          filter:
+            - domain: input_text
+
+mode: queued
+
+variables:
+  celebrate: !input celebrate
+  last_celebrated_helper: !input last_celebrated_helper
+
+triggers:
+  - trigger: event
+    event_type: nestquest_child_day_complete
+
+conditions:
+  - condition: template
+    value_template: "{{ celebrate | bool }}"
+  # Once-per-child-per-day dedupe: celebrate only when THIS child has
+  # no equal entry for today in the helper. Entries compare as whole
+  # comma-separated tokens — a substring check would wrongly suppress
+  # child 1 after child 11 was celebrated. An unset or missing helper
+  # reads as '' and celebrates.
+  - condition: template
+    value_template: >-
+      {{ (trigger.event.data.child_id ~ ':' ~ now().strftime('%Y-%m-%d'))
+         not in ((states(last_celebrated_helper) or '')
+                  .split(',')
+                  | select('ne', '')
+                  | list) }}
+
+actions:
+  - action: !input notify_target
+    data:
+      title: NestQuest day complete
+      message: !input celebration_message
+  # Record this child's celebration, keeping only today's entries so the
+  # helper never outgrows its text limit and stale entries cannot block
+  # next week's celebrations.
+  - action: input_text.set_value
+    target:
+      entity_id: !input last_celebrated_helper
+    data:
+      value: >-
+        {%- set today = now().strftime('%Y-%m-%d') -%}
+        {%- set ns = namespace(entries=[]) -%}
+        {%- for entry in (states(last_celebrated_helper) or '').split(',') -%}
+          {%- if entry and entry.endswith(':' ~ today) -%}
+            {%- set ns.entries = ns.entries + [entry] -%}
+          {%- endif -%}
+        {%- endfor -%}
+        {{ (ns.entries + [trigger.event.data.child_id ~ ':' ~ today]) | join(',') }}

custom_components/nestquest/blueprints/automation/end_of_day_report.yaml

@@ -0,0 +1,121 @@
+blueprint:
+  name: NestQuest end-of-day report
+  description: >-
+    Sends the parent an end-of-day report on how the day went. It runs
+    deliberately BEFORE NestQuest's midnight missed-quest sweep, so it
+    reads the same day's data (what is still open at report time, and
+    how much of the day was completed) rather than tomorrow-morning's
+    hindsight. Every PRESENT child gets a completion line, so the
+    parent always receives the day's summary; children who still owe
+    quests get their open count called out on that line, and children
+    who are not present today are omitted entirely. A child whose
+    remaining-count sensor is unavailable is reported with the
+    completion line only. By default the report is skipped when every
+    present child is already done — turn on send-even-when-clear to
+    always get the day's completion summary. The notify service is
+    chosen by the household when importing this blueprint — NestQuest
+    never hard-codes a personal notify target.
+  domain: automation
+  input:
+    report_time:
+      name: Report time
+      description: >-
+        Local time of day the report is sent — deliberately before the
+        midnight missed-quest sweep, so the report reads the same
+        day's data.
+      default: "20:00"
+      selector:
+        time: {}
+    notify_target:
+      name: Notify service
+      description: >-
+        The Home Assistant notify service to call for the report,
+        for example notify.mobile_app_your_phone — a placeholder;
+        pick the notify service for your own device.
+      selector:
+        text: {}
+    send_report:
+      name: Send the report
+      description: >-
+        Turn off to keep the automation installed but skip the
+        notification entirely.
+      default: true
+      selector:
+        boolean: {}
+    send_even_when_clear:
+      name: Send even when clear
+      description: >-
+        Send the report even when every present child has already
+        finished their quests today. When off (the default), an
+        all-clear day sends nothing.
+      default: false
+      selector:
+        boolean: {}
+
+mode: single
+
+variables:
+  send_report: !input send_report
+  send_even_when_clear: !input send_even_when_clear
+
+triggers:
+  - trigger: time
+    at: !input report_time
+
+conditions:
+  - condition: template
+    value_template: "{{ send_report | bool }}"
+  # Skip an all-clear day unless the household opted into
+  # send-even-when-clear: the guard is false only when every present
+  # child has a usable remaining count of zero. A MISSING or
+  # non-numeric remaining sensor reads as -1 and counts as open —
+  # a degraded state must reach the parent, not look like all-clear.
+  - condition: template
+    value_template: |
+      {%- set ns = namespace(any_open=false) -%}
+      {%- for due in states.sensor
+            | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_due_today(_\\d+)?$') -%}
+        {%- if due.attributes.get('present') -%}
+          {%- set remaining_values = states.sensor
+                | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_remaining_today(_\\d+)?$')
+                | selectattr('attributes.child_id', 'eq', due.attributes.child_id)
+                | map(attribute='state')
+                | list -%}
+          {%- if not remaining_values or (remaining_values | first | int(-1)) != 0 -%}
+            {%- set ns.any_open = true -%}
+          {%- endif -%}
+        {%- endif -%}
+      {%- endfor -%}
+      {{- send_even_when_clear | bool or ns.any_open -}}
+
+actions:
+  - action: !input notify_target
+    data:
+      title: NestQuest end-of-day report
+      message: |
+            {%- set ns = namespace(lines=[]) -%}
+            {%- for due in states.sensor
+                  | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_due_today(_\\d+)?$') -%}
+              {%- if due.attributes.get('present') -%}
+                {%- set due_count = due.state | int -%}
+                {%- set completed_values = states.sensor
+                      | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_completed_today(_\\d+)?$')
+                      | selectattr('attributes.child_id', 'eq', due.attributes.child_id)
+                      | map(attribute='state')
+                      | list -%}
+                {%- set remaining_values = states.sensor
+                      | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_remaining_today(_\\d+)?$')
+                      | selectattr('attributes.child_id', 'eq', due.attributes.child_id)
+                      | map(attribute='state')
+                      | list -%}
+                {%- set completed_count = (completed_values | first | int) if completed_values else 0 -%}
+                {%- set remaining_count = (remaining_values | first | int) if remaining_values else none -%}
+                {%- if remaining_count is not none and remaining_count > 0 -%}
+                  {%- set line = due.attributes.child_name ~ ': ' ~ remaining_count ~ ' still open (' ~ completed_count ~ '/' ~ due_count ~ ' done).' -%}
+                {%- else -%}
+                  {%- set line = due.attributes.child_name ~ ': ' ~ completed_count ~ '/' ~ due_count ~ ' done.' -%}
+                {%- endif -%}
+                {%- set ns.lines = ns.lines + [line] -%}
+              {%- endif -%}
+            {%- endfor -%}
+            {{- ns.lines | join('\n') -}}

custom_components/nestquest/blueprints/automation/morning_summary.yaml

@@ -0,0 +1,78 @@
+blueprint:
+  name: NestQuest morning summary
+  description: >-
+    Sends a morning notification listing what each child still owes
+    today. Only children whose NestQuest presence sensor is on are
+    included; children who are not present today are omitted entirely.
+    The notify service is chosen by the household when importing this
+    blueprint — NestQuest never hard-codes a personal notify target.
+  domain: automation
+  input:
+    morning_time:
+      name: Morning time
+      description: Local time of day the summary is sent.
+      default: "08:00"
+      selector:
+        time: {}
+    notify_target:
+      name: Notify service
+      description: >-
+        The Home Assistant notify service to call for the summary,
+        for example notify.mobile_app_your_phone — a placeholder;
+        pick the notify service for your own device.
+      selector:
+        text: {}
+    send_summary:
+      name: Send the summary
+      description: >-
+        Turn off to keep the automation installed but skip the
+        notification entirely.
+      default: true
+      selector:
+        boolean: {}
+
+mode: single
+
+variables:
+  send_summary: !input send_summary
+
+triggers:
+  - trigger: time
+    at: !input morning_time
+
+conditions:
+  - condition: template
+    value_template: "{{ send_summary | bool }}"
+
+actions:
+  - action: !input notify_target
+    data:
+      title: NestQuest morning summary
+      message: |
+        {%- set ns = namespace(lines=[]) -%}
+        {%- for due in states.sensor
+              | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_due_today(_\\d+)?$') -%}
+          {%- if due.attributes.get('present') -%}
+            {%- set remaining_values = states.sensor
+                  | selectattr('entity_id', 'search', '^sensor\\.nestquest_.*_quests_remaining_today(_\\d+)?$')
+                  | selectattr('attributes.child_id', 'eq', due.attributes.child_id)
+                  | map(attribute='state')
+                  | list -%}
+            {%- if remaining_values -%}
+              {%- set remaining = remaining_values | first | int -%}
+              {%- if remaining > 0 -%}
+                {%- set line = due.attributes.child_name ~ ' owes ' ~ remaining ~ ' quest(s) today.' -%}
+              {%- else -%}
+                {%- set line = due.attributes.child_name ~ ' is all clear today (0 quests remaining).' -%}
+              {%- endif -%}
+            {%- else -%}
+              {%- set line = due.attributes.child_name ~ "'s quest count is unavailable today." -%}
+            {%- endif -%}
+            {%- set ns.lines = ns.lines + [line] -%}
+          {%- endif -%}
+        {%- endfor -%}
+        {%- if ns.lines -%}
+          {{- ns.lines | join('\n') -}}
+        {%- else -%}
+          No children present today.
+        {%- endif -%}

custom_components/nestquest/config_flow.py

@@ -28,7 +28,14 @@ class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
     async def async_step_user(
         self, user_input: dict[str, Any] | None = None
     ) -> FlowResult:
-        """Handle the user step of the config flow."""
+        """Handle the user step of the config flow.
+
+        The integration needs no configuration to start (the API
+        connection is set in the options flow), so the user input is
+        stored as-is.  The former admin-allowlist copy is gone: with
+        the database removed the allowlist lives in the API service's
+        own store, not on the entry.
+        """
         await self.async_set_unique_id(DOMAIN, raise_on_progress=False)
         if self._async_in_progress() or self._async_current_entries():
             return self.async_abort(reason="single_instance_allowed")
@@ -36,4 +43,4 @@ class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
         if user_input is None:
             return self.async_show_form(step_id="user")
 
-        return self.async_create_entry(title="NestQuest", data=user_input)
+        return self.async_create_entry(title="NestQuest", data=dict(user_input))

custom_components/nestquest/const.py

@@ -1,22 +1,10 @@
-"""Constants for the NestQuest integration."""
+"""Re-export of :mod:`custom_components.nestquest.core.const` for the integration package.
+
+The canonical constants live in :mod:`custom_components.nestquest.core.const` (the storage layer
+extracted in task d0b691d8); this module re-exports them so existing
+``from .const import ...`` references inside the integration keep
+working without touching every import line.
+"""
 from __future__ import annotations
 
-import logging
-
-DOMAIN = "nestquest"
-LOGGER_NAME = "custom_components.nestquest"
-LOGGER = logging.getLogger(LOGGER_NAME)
-
-PLATFORMS: list[str] = []
-
-SQLITE_DB_FILENAME = "nestquest.db"
-
-# Configuration keys and default values
-CONF_HORIZON_DAYS = "horizon_days"
-DEFAULT_HORIZON_DAYS = 14
-
-CONF_DAY_ROLLOVER_TIME = "day_rollover_time"
-DEFAULT_DAY_ROLLOVER_TIME = "00:00"
-
-CONF_PANEL_IDLE_TIMEOUT = "panel_idle_timeout"
-DEFAULT_PANEL_IDLE_TIMEOUT = 300
+from .core.const import *  # noqa: F401,F403

custom_components/nestquest/coordinator.py

@@ -0,0 +1,386 @@
+"""The shared NestQuest DataUpdateCoordinator (Feature 10, Feature 18).
+
+ONE refresh pass builds the whole entity snapshot: active children,
+today's instances with their derived states (open / done / missed via
+:func:`~.completion.derive_state`), each child's presence today, and
+per-child rollup counts.  Every Feature 10 entity reads
+``coordinator.data`` — no entity queries the database itself, so one
+refresh updates the whole board coherently.
+
+Since Feature 18 the snapshot no longer comes from the local database:
+the coordinator polls the NestQuest API service's panel plane —
+``GET /api/v1/panel/snapshot`` through
+:class:`~.api_client.NestQuestApiClient` on its update interval — and
+RECONSTRUCTS the same core dataclasses the local builder produced
+(:class:`~.core.snapshot.NestQuestSnapshot`,
+:class:`~.core.snapshot.ChildDaySnapshot`,
+:class:`~.core.snapshot.QuestInstanceView`).  ``sensor.py`` and
+``binary_sensor.py`` read ``coordinator.data`` and
+:func:`~.core.snapshot.instance_payload` exactly as before, so every
+entity_id and attribute payload shape is unchanged: the panel cards and
+the four blueprints keep working untouched.
+
+One loss is deliberate and documented (D-009 revisited): the panel
+payload OMITS missed instances, so a snapshot rebuilt from the API can
+no longer carry them — ``admin_instances`` (``include_missed=True``)
+now equals ``instances`` (they can hold only open and completed rows).
+The admin surface for missed quests is the PWA, which reads the API
+service directly; the integration's entities never needed missed rows
+for their states or counts (the counts arrive precomputed).
+
+Failure handling: constructing the client fails fast (ValueError) when
+the entry has no panel token configured, and a fetch failure raises the
+typed :class:`~.api_client.NestQuestApiError`.  Neither crashes
+integration setup: the constructor logs a clear message and hands back
+a client-shaped stub whose refresh raises the same typed error, and
+``_async_update_data`` converts every typed error into
+:class:`~homeassistant.helpers.update_coordinator.UpdateFailed` — the
+exception a HA ``DataUpdateCoordinator`` records as a failed pass
+(``last_update_success = False``, ``data = None``), so the entities
+come up unavailable.  The typed error is never swallowed silently: it
+is logged with its message and chained into the UpdateFailed.  (The
+conversion matters at setup: HA's real
+``async_config_entry_first_refresh`` wraps any failed pass in
+``ConfigEntryNotReady``, so a setup that keys on the original
+exception type would never match it.)
+
+Last-good cache and staleness: every successful pass refreshes a cache
+of the rebuilt snapshot stamped with the :func:`time.monotonic`
+instant of the success.  A typed failure is checked against that stamp
+BEFORE the pass is declared failed: within the configured staleness
+threshold (``CONF_SNAPSHOT_STALENESS``, seconds, default three update
+intervals) the pass SUCCEEDS with the cached snapshot — the panel
+keeps rendering last-good data and the entities stay available — and
+the outage is logged as a warning.  Entities go unavailable only once
+the cache is older than the threshold (or before the first success);
+a later successful fetch refreshes the cache and the entities recover
+on their own, without a config-entry reload.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import time
+from typing import Any
+
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.update_coordinator import (
+    DataUpdateCoordinator,
+    UpdateFailed,
+)
+
+from .api_client import NestQuestApiClient, NestQuestApiError, resolve_api_config
+from .const import (
+    CONF_UPDATE_INTERVAL,
+    DEFAULT_SNAPSHOT_STALENESS,
+    DEFAULT_UPDATE_INTERVAL,
+    DOMAIN,
+    LOGGER,
+    MIN_UPDATE_INTERVAL,
+)
+from .core.snapshot import (
+    ChildDaySnapshot,
+    NestQuestSnapshot,
+    QuestInstanceView,
+)
+
+__all__ = [
+    "ChildDaySnapshot",
+    "NestQuestCoordinator",
+    "NestQuestSnapshot",
+    "QuestInstanceView",
+]
+
+
+def snapshot_from_api_payload(payload: dict[str, Any]) -> NestQuestSnapshot:
+    """Reconstruct the core snapshot dataclasses from the API's JSON.
+
+    The panel snapshot route (``api/routes_panel.py``) returns today's
+    household as plain JSON — ``today_iso``, ``cycle_day``, and the
+    per-child list with precomputed counts and the instances in the
+    documented payload shape.  This function maps that shape BACK onto
+    the dataclasses ``sensor.py`` / ``binary_sensor.py`` read, field by
+    field:
+
+    - the API's ``state`` ``"completed"`` maps back to the core view's
+      ``"done"`` (so :func:`~.core.snapshot.instance_payload` renders
+      ``"completed"`` again — the round-trip is identity for open and
+      completed rows);
+    - ``overdue``, ``on_time`` (→ ``was_on_time``), ``completed_at``,
+      ``window``, ``due_time``, ``icon`` and the per-child counts pass
+      through verbatim;
+    - ``present`` and ``next_present`` pass through verbatim (the API
+      resolved them through the same presence engine server-side);
+    - the instance list is rebuilt IN ORDER, so the panel payload the
+      sensors emit matches the route's order byte for byte.
+
+    Because the route omits missed instances (D-009), a snapshot built
+    here cannot contain any ``missed`` view — see the module docstring.
+    """
+    children: list[ChildDaySnapshot] = []
+    for child in payload.get("children", []):
+        views = tuple(
+            QuestInstanceView(
+                instance_id=instance["id"],
+                definition_id=instance["definition_id"],
+                child_id=instance["child_id"],
+                title=instance["title"],
+                icon=instance.get("icon"),
+                window=instance["window"],
+                # The API payload does not carry due_date: every row
+                # is TODAY's instance (the route queries
+                # [today, today]), so the view's due_date is the
+                # snapshot's today_iso — the same value the local
+                # builder stamped on every today row.
+                due_date=payload["today_iso"],
+                due_time=instance.get("due_time"),
+                state=(
+                    "done" if instance["state"] == "completed" else
+                    instance["state"]
+                ),
+                overdue=instance["overdue"],
+                completed_at=instance.get("completed_at"),
+                was_on_time=instance.get("on_time"),
+            )
+            for instance in child.get("instances", [])
+        )
+        children.append(
+            ChildDaySnapshot(
+                child_id=child["child_id"],
+                child_name=child["child_name"],
+                instances=views,
+                present=child["present"],
+                due_today=child["due_today"],
+                completed_today=child["completed_today"],
+                remaining_today=child["remaining_today"],
+                completion_pct=child["completion_pct"],
+                next_present=child.get("next_present"),
+            )
+        )
+    return NestQuestSnapshot(
+        today_iso=payload["today_iso"],
+        children=tuple(children),
+        cycle_day=payload["cycle_day"],
+    )
+
+
+class _UnconfiguredApiClient:
+    """Client-shaped stand-in used when the entry has no panel token.
+
+    Constructing a real :class:`~.api_client.NestQuestApiClient` with an
+    empty token raises ValueError by design (fail fast on a client that
+    could only ever 401).  An entry that simply has not been configured
+    yet must not crash integration setup, so the coordinator swaps in
+    this stub: every refresh raises the SAME typed
+    :class:`~.api_client.NestQuestApiError` a transport failure would,
+    carrying a clear "API not configured" message;
+    :meth:`NestQuestCoordinator._async_update_data` converts it to
+    :class:`~homeassistant.helpers.update_coordinator.UpdateFailed`, so
+    the coordinator marks the entities unavailable and the HA standard
+    retry cycle applies.  The error is logged, never silent.
+    """
+
+    __slots__ = ()
+
+    async def get_snapshot(self) -> dict[str, Any]:
+        """Always raise: there is no configured API to fetch from."""
+        raise NestQuestApiError(
+            "NestQuest API not configured: set the panel token in the "
+            "integration options"
+        )
+
+
+def _monotonic() -> float:
+    """The monotonic clock the staleness math reads.
+
+    A one-line indirection over :func:`time.monotonic` so the staleness
+    tests can drive the clock deterministically (patch THIS function,
+    never the stdlib clock).  Monotonic is deliberate: wall-clock jumps
+    (NTP corrections, suspends) must not shorten or extend the window.
+    """
+    return time.monotonic()
+
+
+class NestQuestCoordinator(DataUpdateCoordinator):
+    """Shared refresh cycle for every NestQuest entity.
+
+    One refresh pass = one ``GET /api/v1/panel/snapshot`` through the
+    API client, reconstructed into the core snapshot dataclasses every
+    entity reads.  A failed pass (unconfigured API, transport failure,
+    non-2xx response) raises the typed error out of the client;
+    ``_async_update_data`` converts it to
+    :class:`~homeassistant.helpers.update_coordinator.UpdateFailed`, the
+    exception HA's coordinator machinery records as a failed pass: the
+    coordinator's ``data`` keeps its last good value while
+    ``last_update_success`` goes False — HA marks the entities
+    unavailable until a later pass succeeds.  An unexpected
+    non-typed error still propagates out of ``_async_update_data``
+    and is logged (with its traceback) by HA's machinery, the same way.
+
+    Forced refreshes (the service paths pushing an immediate update
+    after a completion) are SERIALIZED per entry: overlapping
+    complete/uncomplete calls must not interleave their snapshot
+    passes, or an older pass could publish a stale snapshot AFTER a
+    newer one and leave entities wrong until the next poll.  Real
+    HA's coordinator already serializes internally; the lock keeps
+    the same guarantee on the stand-in and costs nothing upstream.
+
+    Last-good cache: a successful pass stamps the rebuilt snapshot
+    with the :func:`~.coordinator._monotonic` instant of the success;
+    a typed failure within the configured staleness threshold
+    (``staleness_seconds``, from ``CONF_SNAPSHOT_STALENESS``) serves
+    that cached snapshot instead of failing the pass, so a short API
+    outage keeps the board up.  Past the threshold — or before the
+    first success — the pass fails as above, and a later successful
+    pass refreshes the cache and recovers the entities on its own.
+    """
+
+    def __init__(
+        self,
+        hass: HomeAssistant,
+        *,
+        entry_id: str,
+        api_client: NestQuestApiClient,
+        update_interval_seconds: int | None = None,
+        staleness_seconds: int | None = None,
+    ) -> None:
+        interval = update_interval_seconds
+        if (
+            not isinstance(interval, int)
+            or isinstance(interval, bool)
+            or interval < MIN_UPDATE_INTERVAL
+        ):
+            interval = DEFAULT_UPDATE_INTERVAL
+        staleness = staleness_seconds
+        if (
+            not isinstance(staleness, int)
+            or isinstance(staleness, bool)
+            or staleness < interval
+        ):
+            # A missing or nonsensical threshold falls back to the
+            # shipped default; a configured-but-too-short one (below
+            # even one poll interval) falls back to whichever of
+            # default/interval spans at least one failed poll, so the
+            # cache is never dead on arrival.  (The options flow
+            # validates the same rule at the form.)
+            staleness = max(DEFAULT_SNAPSHOT_STALENESS, interval)
+        super().__init__(
+            hass,
+            LOGGER,
+            name=DOMAIN,
+            update_interval=datetime.timedelta(seconds=interval),
+        )
+        self.entry_id = entry_id
+        self.api_client = api_client
+        self._refresh_lock = asyncio.Lock()
+        #: The configured last-good window, in SECONDS (const.py:
+        #: CONF_SNAPSHOT_STALENESS / DEFAULT_SNAPSHOT_STALENESS).
+        self._staleness_seconds = staleness
+        #: The last-good cache: the snapshot from the most recent
+        #: SUCCESSFUL fetch and the :func:`time.monotonic` instant it
+        #: landed.  Both stay None until the first success.
+        self._last_good_snapshot: NestQuestSnapshot | None = None
+        self._last_good_monotonic: float | None = None
+
+    async def async_refresh(self) -> None:
+        """One refresh at a time; a queued refresh runs AFTER the
+        in-flight one publishes, so the last snapshot always reflects
+        the latest mutation."""
+        async with self._refresh_lock:
+            await super().async_refresh()
+
+    async def _async_update_data(self) -> NestQuestSnapshot:
+        """One refresh pass: fetch the panel snapshot and rebuild it.
+
+        A successful pass rebuilds the snapshot and refreshes the
+        last-good cache (the snapshot plus the
+        :func:`time.monotonic` instant of the success).
+
+        A typed API failure (unconfigured token stub, transport
+        failure, non-2xx response) is first checked against that
+        stamp: WITHIN the configured staleness threshold (elapsed time
+        since the last successful fetch, inclusive of the threshold
+        itself) the pass SUCCEEDS with the cached snapshot — the panel
+        keeps rendering last-good data, the entities stay available —
+        and the outage is logged as a clear warning (never silent).
+        With no cache yet, or past the threshold, the typed error is
+        converted to
+        :class:`~homeassistant.helpers.update_coordinator.UpdateFailed`
+        — the exception HA's coordinator machinery records as a failed
+        pass (``last_update_success = False``, ``data`` unchanged) so
+        entities go unavailable and the setup-time first refresh
+        arrives as ``ConfigEntryNotReady`` — with the typed error
+        logged and chained.  Anything else still propagates.
+        """
+        try:
+            payload = await self.api_client.get_snapshot()
+        except NestQuestApiError as err:
+            now = _monotonic()
+            cached = self._last_good_snapshot
+            fetched_at = self._last_good_monotonic
+            if (
+                cached is not None
+                and fetched_at is not None
+                and now - fetched_at <= self._staleness_seconds
+            ):
+                LOGGER.warning(
+                    "NestQuest API refresh failed (%s); serving the "
+                    "last-good snapshot fetched %.0f s ago, within the "
+                    "%d s staleness threshold",
+                    err,
+                    now - fetched_at,
+                    self._staleness_seconds,
+                )
+                return cached
+            LOGGER.error(
+                "NestQuest coordinator refresh failed: %s", err
+            )
+            raise UpdateFailed(str(err)) from err
+        snapshot = snapshot_from_api_payload(payload)
+        self._last_good_snapshot = snapshot
+        self._last_good_monotonic = _monotonic()
+        return snapshot
+
+
+def coordinator_client_from_entry(
+    hass: HomeAssistant, entry: Any, *, session_factory: Any = None
+) -> Any:
+    """Build the refresh client for a config entry, tolerating no token.
+
+    Reads ``(base_url, panel_token)`` off the entry and constructs the
+    real client.  An entry with no panel token configured (the shipped
+    default is the empty string) makes the constructor raise ValueError
+    by design; integration setup must not crash on an unconfigured
+    entry, so this factory swaps in the typed-error stub instead and
+    logs ONE clear message.  The ValueError itself is never re-raised
+    past this point — it is converted, with the reason logged.
+
+    ``session_factory`` overrides where the HTTP session comes from
+    (production: HA's shared aiohttp session via
+    :func:`~.api_client.client_from_entry`); it exists so tests can
+    inject a stub transport without importing aiohttp — the mock-only
+    test harness has no ``homeassistant.helpers.aiohttp_client``.
+    """
+    base_url, panel_token = resolve_api_config(entry)
+    if not isinstance(panel_token, str) or not panel_token.strip():
+        LOGGER.warning(
+            "NestQuest API panel token is not configured for entry %s: "
+            "entities will stay unavailable until a token is set in the "
+            "integration options",
+            entry.entry_id,
+        )
+        return _UnconfiguredApiClient()
+    if session_factory is not None:
+        return NestQuestApiClient(
+            base_url, panel_token, session_factory(hass)
+        )
+    from custom_components.nestquest.api_client import client_from_entry
+
+    return client_from_entry(hass, entry)
+
+
+#: Test seam: entry_id → client, consulted by the conftest's client
+#: factory BEFORE the production path.  Always empty in production
+#: (nothing in the integration writes to it); tests register scripted
+#: clients through it and clear it between tests.
+_COORDINATOR_CLIENT_OVERRIDES: dict[str, Any] = {}

custom_components/nestquest/core/__init__.py

@@ -0,0 +1,11 @@
+"""NestQuest storage layer.
+
+A self-contained, Home-Assistant-free package holding the NestQuest
+SQLite storage layer: schema DDL, the versioned migration runner, the
+async connection wrapper, the path resolver, the domain constants and
+recurrence model, and the typed DAOs.  Nothing in this package imports
+``homeassistant``; the integration wires it into HA at its own layer
+(constructing :class:`custom_components.nestquest.core.db.NestQuestDatabase`
+with an executor adapter backed by ``hass.async_add_executor_job``).
+"""
+from __future__ import annotations

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

@@ -0,0 +1,165 @@
+"""Constants for the NestQuest integration."""
+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"]
+
+# Home Assistant bus events (design/ENTITIES-AND-SERVICES.md §3).  The
+# panel and admin cards listen for these; since Feature 18 the
+# completed/uncompleted/day-complete transitions are published by the
+# API service on its SSE stream and re-fired on the bus by the
+# integration's subscription, and Feature 11's nightly sweep fires
+# quest_missed.
+EVENT_QUEST_COMPLETED = "nestquest_quest_completed"
+EVENT_QUEST_UNCOMPLETED = "nestquest_quest_uncompleted"
+EVENT_QUEST_MISSED = "nestquest_quest_missed"
+EVENT_CHILD_DAY_COMPLETE = "nestquest_child_day_complete"
+
+#: Canonical domain-global service name (design/ENTITIES-AND-SERVICES.md §2).
+#: Since Feature 18 only the panel completion service remains: the admin
+#: surface is the PWA and the API service's admin routes, so the former
+#: HA admin services (uncomplete, quest-definition and presence
+#: management, CSV export, child management, regenerate) are gone.
+SERVICE_COMPLETE_QUEST = "complete_quest"
+
+DOMAIN_SERVICES: tuple[str, ...] = (
+    SERVICE_COMPLETE_QUEST,
+)
+
+SQLITE_DB_FILENAME = "nestquest.db"
+
+# Zero-config panel dashboard (Feature 20): ONE storage-mode Lovelace
+# dashboard registered on setup whose config carries the bundle's
+# ``custom:nestquest-party`` strategy (frontend/src/strategy.ts) — the
+# views are generated at render time from the household roster.  The
+# url_path IS the domain: the stable key idempotency is keyed on (a
+# reload or a second entry never duplicates it, and a dashboard already
+# registered under it — ours or the user's — is left untouched).
+DASHBOARD_URL_PATH = DOMAIN
+DASHBOARD_TITLE = "NestQuest"
+DASHBOARD_ICON = "mdi:party-popper"
+DASHBOARD_STRATEGY_TYPE = "custom:nestquest-party"
+
+# Configuration keys and default values
+CONF_HORIZON_DAYS = "horizon_days"
+DEFAULT_HORIZON_DAYS = 14
+
+CONF_DAY_ROLLOVER_TIME = "day_rollover_time"
+DEFAULT_DAY_ROLLOVER_TIME = "00:00"
+
+CONF_PANEL_IDLE_TIMEOUT = "panel_idle_timeout"
+DEFAULT_PANEL_IDLE_TIMEOUT = 300
+
+# Admin allowlist (Feature 03): HA user IDs permitted to call admin-only
+# services.  Stored as IDs, never usernames (feature guardrail).  The
+# database allowlist is authoritative; the config entry carries the same
+# list as a disaster-recovery copy so a lost database can be re-seeded.
+CONF_ADMIN_USER_IDS = "admin_user_ids"
+
+# Shared coordinator refresh interval (Feature 10), in SECONDS.  Every
+# entity reads one snapshot per refresh; completions push an immediate
+# refresh so this poll is only the fallback cadence.
+CONF_UPDATE_INTERVAL = "update_interval"
+DEFAULT_UPDATE_INTERVAL = 300
+MIN_UPDATE_INTERVAL = 30
+
+# Last-good snapshot staleness (Feature 18), in SECONDS: how long the
+# coordinator keeps SERVING the last good snapshot after the API stops
+# answering.  A failed poll whose elapsed time since the last successful
+# fetch is within the threshold returns the cached snapshot (the panel
+# keeps rendering last-good data, entities stay available); past it the
+# poll fails the HA way and the entities go unavailable.  The default is
+# 3x the default update interval (900 s = 15 minutes): three consecutive
+# failed five-minute polls before the board is declared stale — enough
+# to ride out an API service restart, short enough not to render a
+# days-old board all day.  Validation floor: the threshold must be at
+# least the configured update interval, or the cache could never span
+# even one failed poll.
+CONF_SNAPSHOT_STALENESS = "snapshot_staleness"
+DEFAULT_SNAPSHOT_STALENESS = 3 * DEFAULT_UPDATE_INTERVAL
+
+# Notification automations (Feature 11).  The notify target is a free-text
+# Home Assistant service name (e.g. "notify.mobile_app_dads_phone") the
+# household fills in — never a hard-coded personal target; the times are
+# strict HH:MM local; each of the four automations has an independent
+# enable toggle.  Per the owner-settled resolution the end-of-day report
+# defaults to 20:00 — deliberately BEFORE the midnight missed sweep —
+# and never defaults to the rollover time.
+CONF_NOTIFY_TARGET = "notify_target"
+CONF_MORNING_SUMMARY_TIME = "morning_summary_time"
+DEFAULT_MORNING_SUMMARY_TIME = "08:00"
+CONF_AFTERNOON_REMINDER_TIME = "afternoon_reminder_time"
+DEFAULT_AFTERNOON_REMINDER_TIME = "15:00"
+CONF_END_OF_DAY_REPORT_TIME = "end_of_day_report_time"
+DEFAULT_END_OF_DAY_REPORT_TIME = "20:00"
+CONF_MORNING_SUMMARY_ENABLED = "morning_summary_enabled"
+CONF_AFTERNOON_REMINDER_ENABLED = "afternoon_reminder_enabled"
+CONF_END_OF_DAY_REPORT_ENABLED = "end_of_day_report_enabled"
+CONF_CELEBRATION_ENABLED = "celebration_enabled"
+DEFAULT_AUTOMATION_ENABLED = True
+
+# Panel-plane API client (Feature 18): the integration reaches the
+# NestQuest API service (Feature 16) over HTTP instead of the database.
+# The base URL points at the API service host serving ``/api/v1/panel/*``
+# (uvicorn's default host/port is the sensible starting point); the panel
+# service token is the static Bearer credential the panel plane requires
+# (``NESTQUEST_PANEL_TOKEN`` on the API side).  Both are stored on the
+# entry like every other setting — options first, then the entry-data
+# copy, then defaults.  The TOKEN IS A SECRET: it is never logged, never
+# echoed into error messages, and never committed.  The shipped default
+# token IS the empty string (DEFAULT_PANEL_TOKEN) — an entry with no
+# configured token is therefore NOT a working client: the options flow
+# accepts an empty token as "not configured yet" and only rejects
+# malformed (padded/whitespace-only/non-string) values — the actual
+# non-emptiness guard is enforced at client construction, where
+# NestQuestApiClient fails fast on an empty/whitespace token
+# (api_client.py).  So a caller building the client from a bare
+# entry must either ensure a token is configured first or handle the
+# construction ValueError and surface an "API not configured" state —
+# an unconfigured entry never yields a client that can only 401.
+# This mirrors the API service's fail-closed stance (api/config.py: no
+# default token exists).
+CONF_API_BASE_URL = "api_base_url"
+DEFAULT_API_BASE_URL = "http://127.0.0.1:8000"
+CONF_PANEL_TOKEN = "panel_token"
+DEFAULT_PANEL_TOKEN = ""
+
+# Quest windows (D-008): a definition may declare several day windows;
+# each produces its own instance per day and groups the panel's Quest
+# Log into three columns.  The clock ranges are stored here so they stay
+# configurable later.  Boundaries: a window's end equals the next
+# window's start; classification (Feature 07 materialisation) treats a
+# due time exactly on the boundary as belonging to the LATER window, so
+# 12:00 is afternoon (not morning) and 17:00 is evening (not
+# afternoon).  Times after 21:00 belong to no window.
+WINDOW_MORNING = "morning"
+WINDOW_AFTERNOON = "afternoon"
+WINDOW_EVENING = "evening"
+
+QUEST_WINDOWS: tuple[str, ...] = (
+    WINDOW_MORNING,
+    WINDOW_AFTERNOON,
+    WINDOW_EVENING,
+)
+
+#: Inclusive "HH:MM" bounds per window, in 24-hour local time.
+WINDOW_CLOCK_RANGES: dict[str, tuple[str, str]] = {
+    WINDOW_MORNING: ("00:00", "11:59"),
+    WINDOW_AFTERNOON: ("12:00", "17:00"),
+    WINDOW_EVENING: ("17:00", "21:00"),
+}

custom_components/nestquest/core/dao_children.py

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

custom_components/nestquest/core/dao_instances.py

@@ -0,0 +1,832 @@
+"""Typed DAO layer for quest_instances and the append-only completion_events.
+
+All SQL for these tables lives in this module per the feature
+guardrails: callers get typed dataclasses back and never see raw rows
+or SQL.  Every method is async and runs through
+:class:`~.db.NestQuestDatabase`, so each statement executes on the HA
+executor and the event loop never blocks.
+
+Append-only policy (Feature 08, D-005): ``completion_events`` is
+strictly append-only.  This module is where that property is enforced
+mechanically — the completion-events DAO below exposes NO update or
+delete method at all; completions append, un-completions append a
+separate reversal event, and instance state derives from the latest
+event.  A package-wide guard test (bottom of the test module) keeps
+mutation SQL for this table out of every other module.
+
+Upsert semantics: ``QuestInstancesDao.upsert`` is idempotent on
+(definition_id, child_id, due_date, window) — re-running
+materialization for a tuple whose instance already exists refreshes
+only the generation-time snapshot columns and never duplicates a row.
+The schema's UNIQUE(definition_id, child_id, due_date, window) is the
+last line of defense.  The upsert refuses a child that is not an
+assignee of the definition and a window outside ``const.QUEST_WINDOWS``
+(D-008 multi-assignee, multi-window model).
+
+``delete_future_uncompleted`` implements the Feature 06/07 rule that
+reassignment and schedule edits regenerate future instances: it
+removes only instances at or after the cutoff that have NO completion
+event, inside one transaction, so an instance completed mid-call can
+never be deleted.  Instances in the past are never touched (Feature 07
+guardrail: never delete history), and no method here deletes a single
+instance that has a completion event.
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+from .dao_children import _connection_lock
+from .dao_rules import _validate_date, _validate_window
+from .db import NestQuestDatabase
+
+#: Timestamp policy for completion_events.occurred_at: strict UTC
+#: ISO-8601 with explicit '+00:00' offset (module timestamp policy).
+#: One accepted shape bounds lexicographic range queries correctly, so
+#: the occurred-at scope does not guess at timestamp spellings.
+_UTC_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S+00:00"
+
+
+def _today() -> datetime.date:
+    """Return the current local calendar date (the single date source).
+
+    Every "today" read in this module goes through this one function so
+    the delete clamp and the materialize walk's no-past guard read the
+    same clock, and a caller or test can pin/roll that clock
+    deterministically (e.g. a queued-across-midnight regression).  Pure
+    clock read — no business rule lives here.
+    """
+    return datetime.date.today()
+
+
+def _resolve_today(today: datetime.date | None) -> datetime.date:
+    """Return the caller-resolved "today", or the host date when absent.
+
+    The no-past guard and the delete cutoffs must compare due dates
+    against the SAME calendar date the materialization horizon was built
+    from.  Home Assistant's configured time zone can lag the host clock
+    around midnight, so when the caller has already resolved the local
+    date (``today``) that anchor is authoritative; ``None`` falls back to
+    the host clock (:func:`_today`), which is exactly the previous
+    behavior for callers with no HA-local date.
+    """
+    return _today() if today is None else today
+
+
+def _reject_past(due_date: str, today_iso: str) -> None:
+    """Raise unless ``due_date`` is on or after ``today_iso``.
+
+    The single no-past rule shared by :meth:`QuestInstancesDao.upsert`
+    and :meth:`QuestInstancesDao.upsert_if_valid`: instances are never
+    generated in the past, measured against the resolved "today".
+    """
+    if due_date < today_iso:
+        raise ValueError(
+            f"instances are never generated in the past: due_date "
+            f"{due_date!r} is before today {today_iso!r}"
+        )
+
+
+def _validate_utc_timestamp(value: str, field: str) -> None:
+    """Raise ValueError unless ``value`` is a strict UTC ISO-8601 stamp.
+
+    Same strictness policy as _validate_date: parse with the exact
+    format, then round-trip the parsed value against the input so
+    non-padded or re-ordered shapes are rejected.  The round-trip
+    strips the UTC offset (isoformat() omits it when the offset is
+    zero), so the suffix is appended before comparing.
+    """
+    try:
+        parsed = datetime.datetime.strptime(
+            value, _UTC_TIMESTAMP_FORMAT
+        )
+    except (TypeError, ValueError):
+        raise ValueError(
+            f"{field} must be a UTC ISO-8601 timestamp "
+            f"(YYYY-MM-DDTHH:MM:SS+00:00), got {value!r}"
+        ) from None
+    if parsed.isoformat() + "+00:00" != value:
+        raise ValueError(
+            f"{field} must be a strict UTC timestamp "
+            f"(YYYY-MM-DDTHH:MM:SS+00:00), got {value!r}"
+        )
+
+
+def _next_day_start(date_str: str) -> str:
+    """Return the UTC timestamp one second past ``date_str``'s last second.
+
+    Gives range queries an exact half-open upper bound without
+    fractional-second guessing.
+    """
+    day = datetime.date.fromisoformat(date_str)
+    next_day = day + datetime.timedelta(days=1)
+    return f"{next_day.isoformat()}T00:00:00+00:00"
+
+
+@dataclass(frozen=True)
+class QuestInstanceRecord:
+    """One row of ``quest_instances``."""
+
+    id: int
+    definition_id: int
+    child_id: int
+    window: str
+    due_date: str
+    due_time: str | None
+    generated_at: str
+
+
+@dataclass(frozen=True)
+class CompletionEventRecord:
+    """One row of ``completion_events`` (append-only table)."""
+
+    id: int
+    instance_id: int
+    child_id: int
+    event_type: str
+    actor_source: str
+    actor_user_id: str | None
+    actor_child_id: int | None
+    occurred_at: str
+    was_on_time: bool | None
+
+
+_INSTANCE_COLUMNS = (
+    "id, definition_id, child_id, window, due_date, due_time, generated_at"
+)
+_EVENT_COLUMNS = (
+    "id, instance_id, child_id, event_type, actor_source, actor_user_id, "
+    "actor_child_id, occurred_at, was_on_time"
+)
+
+#: The only event types the append path accepts; the schema CHECK is
+#: the backstop, this is the DAO's typed front door.
+EVENT_COMPLETED = "completed"
+EVENT_UNCOMPLETED = "uncompleted"
+
+
+def _instance_from_row(row: tuple) -> QuestInstanceRecord:
+    return QuestInstanceRecord(
+        id=row[0],
+        definition_id=row[1],
+        child_id=row[2],
+        window=row[3],
+        due_date=row[4],
+        due_time=row[5],
+        generated_at=row[6],
+    )
+
+
+def _event_from_row(row: tuple) -> CompletionEventRecord:
+    return CompletionEventRecord(
+        id=row[0],
+        instance_id=row[1],
+        child_id=row[2],
+        event_type=row[3],
+        actor_source=row[4],
+        actor_user_id=row[5],
+        actor_child_id=row[6],
+        occurred_at=row[7],
+        was_on_time=None if row[8] is None else bool(row[8]),
+    )
+
+
+class QuestInstancesDao:
+    """Typed async access to the ``quest_instances`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def upsert(
+        self,
+        definition_id: int,
+        child_id: int,
+        due_date: str,
+        generated_at: str,
+        *,
+        window: str,
+        due_time: str | None = None,
+        today: datetime.date | None = None,
+    ) -> QuestInstanceRecord:
+        """Create the dated instance for the widened key idempotently.
+
+        The instance key is (definition_id, child_id, due_date, window)
+        (D-008): running materialization twice for the same tuple
+        yields ONE row — the ON CONFLICT path refreshes the
+        generation-time snapshot columns (due_time) and regenerates the
+        stamp, but can never create a duplicate.  The schema's
+        UNIQUE(definition_id, child_id, due_date, window) backs this
+        up, so the twice-daily case (two windows, one child, one date)
+        yields two rows and the shared case (three assignees, one
+        window) yields three.
+
+        Guardrails enforced here:
+
+        - ``due_date`` must be TODAY or later: instances are never
+          generated in the past (Feature 07).  The caller's
+          materialization horizon is future-dated by definition.
+          ``today`` optionally pins the resolved HA-local date the
+          guard compares against (falling back to the host clock when
+          omitted) so a household time zone behind the host around
+          midnight is not misread as "past".
+        - ``window`` must be one of ``const.QUEST_WINDOWS``.
+        - An existing instance WITH a completion event is IMMUTABLE:
+          the conflict path must not rewrite its snapshot columns
+          (Feature 07/08).  The upsert refuses with ValueError in that
+          case — silently no-oping would mask a materialization bug.
+        - The child must be an assignee of the definition (D-008
+          multi-assignee model).
+
+        The definition must exist (validated atomically under the
+        connection lock so a concurrent definition deactivation or
+        child deletion cannot slip between check and insert).
+        """
+        _validate_date(due_date, "due_date")
+        _validate_window(window)
+        # Fail fast on obviously-past dates BEFORE queuing on the
+        # connection lock (a nice early error); the AUTHORITATIVE
+        # check runs after the lock is acquired, because a caller can
+        # wait on the lock across midnight — a date that was "today"
+        # at call time may be "yesterday" by the time the INSERT runs.
+        # A caller-supplied ``today`` (HA-local) is used for BOTH
+        # checks and never re-read, since it is already the anchor the
+        # batch runs against.
+        today_date = _resolve_today(today)
+        _reject_past(due_date, today_date.isoformat())
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                # Re-read "today" under the lock: this is the date the
+                # insert actually executes on, so the no-past rule
+                # holds across midnight rollovers.  A pinned HA-local
+                # anchor is exempt from the re-read (see above).
+                if today is None:
+                    today_date = _today()
+                _reject_past(due_date, today_date.isoformat())
+                definition = await self._database.fetch_one(
+                    "SELECT 1 FROM quest_definitions WHERE id = ?",
+                    (definition_id,),
+                )
+                if definition is None:
+                    raise ValueError(
+                        f"quest definition {definition_id} does not exist"
+                    )
+                assignee = await self._database.fetch_one(
+                    "SELECT 1 FROM quest_definition_assignees "
+                    "WHERE definition_id = ? AND child_id = ?",
+                    (definition_id, child_id),
+                )
+                if assignee is None:
+                    raise ValueError(
+                        f"quest definition {definition_id} is not "
+                        f"assigned to child {child_id}; instance must "
+                        "carry an assigned child"
+                    )
+                existing = await self._database.fetch_one(
+                    "SELECT 1 FROM completion_events "
+                    "WHERE instance_id = (SELECT id FROM quest_instances "
+                    "WHERE definition_id = ? AND child_id = ? "
+                    "AND due_date = ? AND window = ?)",
+                    (definition_id, child_id, due_date, window),
+                )
+                if existing is not None:
+                    raise ValueError(
+                        f"instance for (definition {definition_id}, "
+                        f"child {child_id}, due_date {due_date!r}, "
+                        f"window {window!r}) already has a completion "
+                        "event and is immutable; it cannot be regenerated"
+                    )
+                await self._database.execute(
+                    "INSERT INTO quest_instances (definition_id, child_id, "
+                    "window, due_date, due_time, generated_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?) "
+                    "ON CONFLICT (definition_id, child_id, due_date, "
+                    "window) DO UPDATE SET "
+                    "due_time = excluded.due_time, "
+                    "generated_at = excluded.generated_at",
+                    (
+                        definition_id,
+                        child_id,
+                        window,
+                        due_date,
+                        due_time,
+                        generated_at,
+                    ),
+                )
+                instance = await self.get(
+                    definition_id, child_id, due_date, window
+                )
+        assert instance is not None
+        return instance
+
+    async def upsert_if_valid(
+        self,
+        definition_id: int,
+        child_id: int,
+        due_date: str,
+        generated_at: str,
+        *,
+        window: str,
+        due_time: str | None = None,
+        today: datetime.date | None = None,
+    ) -> QuestInstanceRecord | None:
+        """Insert one dated instance iff its tuple is still materializable.
+
+        This is the materialization walk's single write path.  Unlike the
+        generic :meth:`upsert`, which validates only existence and
+        assignment, this method re-validates EVERY materialization
+        precondition in the SAME connection-lock-held transaction as the
+        INSERT — closing the check-then-insert gap a concurrent config
+        write could otherwise slip through:
+
+        - the definition exists AND is active (a definition deactivated
+          after the input snapshot is skipped, never written);
+        - the child exists AND is active (a deactivated child is skipped);
+        - the (definition, child) assignment link still exists (a removed
+          assignment is skipped);
+        - the window is still declared on the definition (a removed window
+          is skipped);
+        - the window's live ``due_time`` still EQUALS the caller-supplied
+          ``due_time`` (NULL-safe: NULL == NULL counts as equal; a window
+          with no due time matches a snapshot with no due time).  A
+          window-time edit landed after the input snapshot makes the
+          caller's ``due_time`` stale, and writing it would overwrite the
+          newer due_time a concurrent regeneration already upserted — so
+          the tuple is skipped instead of written.
+
+        The due_time check closes the one check-then-insert gap this
+        method previously left open: it re-validated every OTHER
+        precondition but then wrote the snapshot's ``due_time``
+        unconditionally, so a stale materialization could clobber a
+        newer, concurrently-regenerated due_time.
+
+        Returns the stored instance, or ``None`` when a precondition
+        failed — the tuple no longer materializable, which the walk SKIPS
+        rather than raising, so the rest of the batch is unaffected.  The
+        no-past rule (instances are never generated in the past) is
+        preserved from :meth:`upsert` and still raises ValueError; ``today``
+        optionally pins the HA-local anchor it compares against.  An
+        instance that ALREADY has a completion event is also skipped
+        (returns ``None``) rather than raised: it is immutable, so the
+        walk leaves it untouched instead of failing the batch — the
+        generic :meth:`upsert` keeps its hard refusal for the
+        delete/regenerate path.
+        """
+        _validate_date(due_date, "due_date")
+        _validate_window(window)
+        # Fail fast on obviously-past dates before queuing on the lock;
+        # the authoritative check re-runs under the lock (see upsert).
+        today_date = _resolve_today(today)
+        _reject_past(due_date, today_date.isoformat())
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                if today is None:
+                    today_date = _today()
+                _reject_past(due_date, today_date.isoformat())
+                still_valid = await self._database.fetch_one(
+                    "SELECT 1 FROM quest_definitions d "
+                    "JOIN quest_definition_assignees a "
+                    "ON a.definition_id = d.id "
+                    "JOIN children c ON c.id = a.child_id "
+                    "JOIN quest_definition_windows w "
+                    "ON w.definition_id = d.id "
+                    "WHERE d.id = ? AND a.child_id = ? AND w.window = ? "
+                    "AND d.is_active = 1 AND c.is_active = 1 "
+                    "AND w.due_time IS ? LIMIT 1",
+                    (definition_id, child_id, window, due_time),
+                )
+                if still_valid is None:
+                    # A config change invalidated the tuple since the
+                    # snapshot: skip it rather than abort the batch.
+                    return None
+                existing = await self._database.fetch_one(
+                    "SELECT 1 FROM completion_events "
+                    "WHERE instance_id = (SELECT id FROM quest_instances "
+                    "WHERE definition_id = ? AND child_id = ? "
+                    "AND due_date = ? AND window = ?)",
+                    (definition_id, child_id, due_date, window),
+                )
+                if existing is not None:
+                    # The instance is already completed and therefore
+                    # immutable: the walk SKIPS it (no-op) rather than
+                    # rewriting its snapshot columns or failing the
+                    # batch.  This is the materialization walk's skip,
+                    # distinct from the generic :meth:`upsert` refusal.
+                    return None
+                await self._database.execute(
+                    "INSERT INTO quest_instances (definition_id, child_id, "
+                    "window, due_date, due_time, generated_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?) "
+                    "ON CONFLICT (definition_id, child_id, due_date, "
+                    "window) DO UPDATE SET "
+                    "due_time = excluded.due_time, "
+                    "generated_at = excluded.generated_at",
+                    (
+                        definition_id,
+                        child_id,
+                        window,
+                        due_date,
+                        due_time,
+                        generated_at,
+                    ),
+                )
+                instance = await self.get(
+                    definition_id, child_id, due_date, window
+                )
+        assert instance is not None
+        return instance
+
+    async def get(
+        self,
+        definition_id: int,
+        child_id: int,
+        due_date: str,
+        window: str,
+    ) -> QuestInstanceRecord | None:
+        """Return the instance for the widened key tuple, or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_INSTANCE_COLUMNS} FROM quest_instances "
+            "WHERE definition_id = ? AND child_id = ? AND due_date = ? "
+            "AND window = ?",
+            (definition_id, child_id, due_date, window),
+        )
+        return _instance_from_row(row) if row is not None else None
+
+    async def get_by_id(self, instance_id: int) -> QuestInstanceRecord | None:
+        """Return the instance with ``instance_id``, or None."""
+        row = await self._database.fetch_one(
+            f"SELECT {_INSTANCE_COLUMNS} FROM quest_instances WHERE id = ?",
+            (instance_id,),
+        )
+        return _instance_from_row(row) if row is not None else None
+
+    async def list_by_child_and_date(
+        self, child_id: int, due_date: str
+    ) -> list[QuestInstanceRecord]:
+        """Return the child's instances due exactly on ``due_date``."""
+        _validate_date(due_date, "due_date")
+        rows = await self._database.fetch_all(
+            f"SELECT {_INSTANCE_COLUMNS} FROM quest_instances "
+            "WHERE child_id = ? AND due_date = ? ORDER BY id",
+            (child_id, due_date),
+        )
+        return [_instance_from_row(row) for row in rows]
+
+    async def list_by_date_range(
+        self,
+        child_id: int,
+        range_start: str,
+        range_end: str,
+    ) -> list[QuestInstanceRecord]:
+        """Return the child's instances with due_date in the closed range."""
+        _validate_date(range_start, "range_start")
+        _validate_date(range_end, "range_end")
+        if range_end < range_start:
+            raise ValueError(
+                "range_end must be on or after range_start, got "
+                f"{range_end!r} < {range_start!r}"
+            )
+        rows = await self._database.fetch_all(
+            f"SELECT {_INSTANCE_COLUMNS} FROM quest_instances "
+            "WHERE child_id = ? AND due_date >= ? AND due_date <= ? "
+            "ORDER BY due_date, id",
+            (child_id, range_start, range_end),
+        )
+        return [_instance_from_row(row) for row in rows]
+
+    async def list_missed_unswept(
+        self, today_iso: str, watermark: str | None
+    ) -> list[QuestInstanceRecord]:
+        """Return past-due open instances the sweep has not announced.
+
+        Feature 11's missed-sweep query: ``due_date`` strictly before
+        ``today_iso`` (past due), at or after ``watermark`` when one is
+        recorded, and with NO completion event ever (the Feature 08
+        append-only contract: an instance that was ever completed is
+        never reported missed, even when later reversed — history keeps
+        both rows and the sweep never mutates any).  The watermark is
+        the HA-local date the sweep last ran, and the window is
+        ``[watermark, today)``: the nightly run entering day D+1 sweeps
+        exactly day D's instances, so every day's quests are announced
+        once — at the midnight after their due date — and a same-night
+        rerun (watermark == today) sees an empty window.  Read-only;
+        ordered deterministically by (due_date, id).
+        """
+        _validate_date(today_iso, "today_iso")
+        if watermark is not None:
+            _validate_date(watermark, "watermark")
+        sql = (
+            f"SELECT {_INSTANCE_COLUMNS} FROM quest_instances "
+            "WHERE due_date < ? "
+            "AND NOT EXISTS ("
+            "  SELECT 1 FROM completion_events "
+            "  WHERE instance_id = quest_instances.id"
+            ")"
+        )
+        parameters: tuple = (today_iso,)
+        if watermark is not None:
+            sql += " AND due_date >= ?"
+            parameters += (watermark,)
+        sql += " ORDER BY due_date, id"
+        rows = await self._database.fetch_all(sql, parameters)
+        return [_instance_from_row(row) for row in rows]
+
+    async def delete_future_uncompleted(
+        self, definition_id: int, cutoff_date: str, *, today: datetime.date | None = None
+    ) -> int:
+        """Delete the definition's open instances at/after cutoff.
+
+        Implements regeneration after a definition edit or reassignment
+        (Features 06/07): only instances at or after the cutoff with NO
+        completion event are removed, inside one transaction — an
+        instance that gains a completion event mid-flight cannot be
+        deleted.  The cutoff cannot be backdated below today: "future"
+        is measured against TODAY (materialization regenerates the
+        rolling horizon from now), so a caller cannot use this to
+        rewrite past open instances either — the day-rollover missed
+        sweep (Feature 11) handles past-due instances instead.  ``today``
+        optionally pins the HA-local anchor the clamp compares against
+        (falling back to the host clock when omitted).  Any instance with
+        a completion event is never touched, regardless of its date.
+        Returns the number deleted.
+        """
+        _validate_date(cutoff_date, "cutoff_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                # "today" is read under the lock: the DELETE actually
+                # executes on this date, so a caller queued across
+                # midnight cannot delete instances that became past
+                # while it waited (backdating is clamped to the
+                # execution date, not the call date).
+                today_date = _resolve_today(today)
+                effective_cutoff = max(cutoff_date, today_date.isoformat())
+                result = await self._database.execute(
+                    "DELETE FROM quest_instances WHERE definition_id = ? "
+                    "AND due_date >= ? AND NOT EXISTS ("
+                    "  SELECT 1 FROM completion_events "
+                    "  WHERE instance_id = quest_instances.id"
+                    ")",
+                    (definition_id, effective_cutoff),
+                )
+        return result.rowcount
+
+    async def delete_future_uncompleted_for_child(
+        self, child_id: int, cutoff_date: str, *, today: datetime.date | None = None
+    ) -> tuple[int, str]:
+        """Delete the child's open instances at/after cutoff, across every
+        definition, returning ``(deleted, effective_cutoff)``.
+
+        Child-scoped counterpart to :meth:`delete_future_uncompleted`,
+        used when a child's presence changes (Feature 09): only instances
+        at or after the cutoff with NO completion event are removed, inside
+        one transaction — an instance that gains a completion event
+        mid-flight cannot be deleted.  The cutoff cannot be backdated below
+        today, for the same reason as the definition-scoped method (see its
+        docstring).  ``today`` optionally pins the HA-local anchor the clamp
+        compares against (falling back to the host clock when omitted).
+        Any instance with a completion event is never touched, regardless
+        of its date.
+
+        Returns the number deleted and the effective cutoff that was
+        actually applied (``max(cutoff_date, today)``, read under the
+        lock).  The caller (:func:`~.materialize.regenerate_for_child`)
+        passes that effective cutoff back as its re-materialization anchor,
+        so the delete and the rebuild share ONE execution-day even when the
+        call is queued across midnight — instead of the caller re-reading a
+        stale "today" and materializing a window the delete already
+        superseded.
+        """
+        _validate_date(cutoff_date, "cutoff_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                # "today" is read under the lock, matching the
+                # definition-scoped method: the DELETE executes on this
+                # date, so a caller queued across midnight cannot delete
+                # instances that became past while it waited.
+                today_date = _resolve_today(today)
+                effective_cutoff = max(cutoff_date, today_date.isoformat())
+                result = await self._database.execute(
+                    "DELETE FROM quest_instances WHERE child_id = ? "
+                    "AND due_date >= ? AND NOT EXISTS ("
+                    "  SELECT 1 FROM completion_events "
+                    "  WHERE instance_id = quest_instances.id"
+                    ")",
+                    (child_id, effective_cutoff),
+                )
+        return result.rowcount, effective_cutoff
+
+
+class CompletionEventsDao:
+    """Typed append-only access to the ``completion_events`` table.
+
+    APPEND-ONLY BY CONSTRUCTION: this class exposes ``append`` and the
+    three read methods below, and NOTHING else.  There is no update,
+    no delete, no upsert — completions and un-completions both arrive
+    through :meth:`append` as new rows, and history is immutable
+    (Feature 08 done-condition: no code path updates or deletes an
+    event).  The package-wide leak-guard test additionally fails if
+    mutation SQL for this table ever appears in any module.
+    """
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def append(
+        self,
+        instance_id: int,
+        child_id: int,
+        event_type: str,
+        actor_source: str,
+        occurred_at: str,
+        was_on_time: bool | None,
+        *,
+        actor_user_id: str | None = None,
+        actor_child_id: int | None = None,
+    ) -> CompletionEventRecord:
+        """Append one completion or un-completion event.
+
+        ``actor_source`` is 'user' (an admin action: ``actor_user_id``
+        set, ``actor_child_id`` NULL) or 'panel' (a panel tap: no user
+        id, and ``actor_child_id`` carrying the tapped child profile,
+        D-008); the actor-pair CHECKs enforce this shape at the schema
+        level.  ``occurred_at`` must be the module's one strict UTC
+        shape (YYYY-MM-DDTHH:MM:SS+00:00) so lexicographic range
+        queries stay exact.  ``was_on_time`` is required (True/False)
+        for completions; for un-completions it may be None or the
+        reversed completion's flag (Feature 08 still deciding).  The
+        instance, child and — for panel events — the tapped child must
+        exist — validated atomically under the connection lock.
+        """
+        if event_type not in (EVENT_COMPLETED, EVENT_UNCOMPLETED):
+            raise ValueError(
+                f"event_type must be '{EVENT_COMPLETED}' or "
+                f"'{EVENT_UNCOMPLETED}', got {event_type!r}"
+            )
+        if actor_source not in ("user", "panel"):
+            raise ValueError(
+                f"actor_source must be 'user' or 'panel', got "
+                f"{actor_source!r}"
+            )
+        if actor_source == "user" and not actor_user_id:
+            raise ValueError(
+                "actor_source 'user' requires actor_user_id"
+            )
+        if actor_source == "panel" and actor_user_id is not None:
+            raise ValueError(
+                "actor_source 'panel' must not carry actor_user_id"
+            )
+        if actor_source == "panel" and actor_child_id is None:
+            raise ValueError(
+                "actor_source 'panel' requires actor_child_id "
+                "(the tapped child profile)"
+            )
+        if actor_source == "user" and actor_child_id is not None:
+            raise ValueError(
+                "actor_source 'user' must not carry actor_child_id"
+            )
+        if was_on_time is not None and type(was_on_time) is not bool:
+            raise ValueError(
+                f"was_on_time must be True, False or None, got "
+                f"{was_on_time!r}"
+            )
+        if event_type == EVENT_COMPLETED and was_on_time is None:
+            raise ValueError(
+                "a completed event requires was_on_time (True/False)"
+            )
+        _validate_utc_timestamp(occurred_at, "occurred_at")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                instance = await self._database.fetch_one(
+                    "SELECT child_id FROM quest_instances WHERE id = ?",
+                    (instance_id,),
+                )
+                if instance is None:
+                    raise ValueError(
+                        f"quest instance {instance_id} does not exist"
+                    )
+                if instance[0] != child_id:
+                    raise ValueError(
+                        f"quest instance {instance_id} belongs to child "
+                        f"{instance[0]}, not {child_id}"
+                    )
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                if actor_child_id is not None:
+                    tapped = await self._database.fetch_one(
+                        "SELECT 1 FROM children WHERE id = ?",
+                        (actor_child_id,),
+                    )
+                    if tapped is None:
+                        raise ValueError(
+                            f"actor_child_id {actor_child_id} does not "
+                            "reference an existing child"
+                        )
+                result = await self._database.execute(
+                    "INSERT INTO completion_events (instance_id, child_id, "
+                    "event_type, actor_source, actor_user_id, "
+                    "actor_child_id, occurred_at, was_on_time) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        instance_id,
+                        child_id,
+                        event_type,
+                        actor_source,
+                        actor_user_id,
+                        actor_child_id,
+                        occurred_at,
+                        None if was_on_time is None else int(was_on_time),
+                    ),
+                )
+                event = await self._database.fetch_one(
+                    f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+                    "WHERE id = ?",
+                    (result.lastrowid,),
+                )
+        assert event is not None
+        return _event_from_row(event)
+
+    async def list_by_instance(
+        self, instance_id: int
+    ) -> list[CompletionEventRecord]:
+        """Return every event for the instance, in append order."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+            "WHERE instance_id = ? ORDER BY id",
+            (instance_id,),
+        )
+        return [_event_from_row(row) for row in rows]
+
+    async def list_by_child_and_date_range(
+        self,
+        child_id: int,
+        range_start: str,
+        range_end: str,
+        *,
+        due_date_scope: bool = True,
+    ) -> list[CompletionEventRecord]:
+        """Return the child's events for instances due in the closed range.
+
+        Scopes by the INSTANCE's due date (the day the task was owed),
+        not the event's wall-clock timestamp: history reporting asks
+        "what happened to the tasks due that day" (Feature 13).  Set
+        ``due_date_scope=False`` to filter by ``occurred_at`` date
+        instead.  Ordered by instance, then event id.
+        """
+        _validate_date(range_start, "range_start")
+        _validate_date(range_end, "range_end")
+        if range_end < range_start:
+            raise ValueError(
+                "range_end must be on or after range_start, got "
+                f"{range_end!r} < {range_start!r}"
+            )
+        if due_date_scope:
+            predicate = (
+                "SELECT id FROM quest_instances WHERE child_id = ? "
+                "AND due_date >= ? AND due_date <= ?"
+            )
+            parameters: list[object] = [child_id, range_start, range_end]
+        else:
+            # Occurred-at scope: occurred_at is validated to the one
+            # accepted UTC shape at append time, so half-open day
+            # bounds in that same shape are exact (no spelling drift).
+            occurred_start = f"{range_start}T00:00:00+00:00"
+            occurred_end = f"{range_end}T23:59:59+00:00"
+            query = (
+                f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+                "WHERE child_id = ? AND occurred_at >= ? "
+                "AND occurred_at < ? ORDER BY instance_id, id"
+            )
+            rows = await self._database.fetch_all(
+                query,
+                [
+                    child_id,
+                    occurred_start,
+                    _next_day_start(range_end),
+                ],
+            )
+            return [_event_from_row(row) for row in rows]
+        rows = await self._database.fetch_all(
+            f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+            f"WHERE instance_id IN ({predicate}) "
+            "ORDER BY instance_id, id",
+            tuple(parameters),
+        )
+        return [_event_from_row(row) for row in rows]
+
+    async def get_latest_for_instance(
+        self, instance_id: int
+    ) -> CompletionEventRecord | None:
+        """Return the instance's most recent event, or None if untouched.
+
+        Instance current state derives from this event (Feature 08):
+        'completed' means done, 'uncompleted' as the latest means open
+        again, None means never completed.
+        """
+        row = await self._database.fetch_one(
+            f"SELECT {_EVENT_COLUMNS} FROM completion_events "
+            "WHERE instance_id = ? ORDER BY id DESC LIMIT 1",
+            (instance_id,),
+        )
+        return _event_from_row(row) if row is not None else None

custom_components/nestquest/core/dao_meta.py

@@ -0,0 +1,78 @@
+"""Typed DAO for the integration-owned ``nestquest_meta_state`` table.
+
+Generic persistent key/value bookkeeping that belongs to the
+integration itself rather than any domain table — currently the
+Feature 11 missed-sweep watermark.  Values are plain strings; callers
+interpret them.  All SQL for this table lives here per the feature
+guardrails, and every method runs through
+:class:`~.db.NestQuestDatabase` so nothing blocks the event loop.
+"""
+from __future__ import annotations
+
+from .dao_children import _connection_lock
+from .db import NestQuestDatabase
+
+_TABLE = "nestquest_meta_state"
+
+
+class MetaStateDao:
+    """Typed async access to the ``nestquest_meta_state`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def get(self, key: str) -> str | None:
+        """Return the stored value for ``key``, or None when absent."""
+        row = await self._database.fetch_one(
+            f"SELECT value FROM {_TABLE} WHERE key = ?", (key,)
+        )
+        return row[0] if row is not None else None
+
+    async def set(self, key: str, value: str) -> None:
+        """Upsert one key/value row atomically.
+
+        The write runs inside one transaction under the shared
+        connection lock, so a racing reader either sees the old value
+        or the fully-written new one, never a half-applied state.
+        """
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                await self._database.execute(
+                    f"INSERT INTO {_TABLE} (key, value) VALUES (?, ?) "
+                    "ON CONFLICT (key) DO UPDATE SET value = excluded.value",
+                    (key, value),
+                )
+
+    async def claim(self, key: str, value: str) -> bool:
+        """Atomically set ``key`` to ``value`` unless it already is.
+
+        The single upsert statement carries a ``WHERE`` guard on the
+        conflict path (``t.value IS NOT excluded.value``), so the
+        read-compare-write is ONE SQLite statement — atomic at the
+        DATABASE level, not just within one process: two connections
+        (two processes sharing one SQLite file) cannot both observe
+        "not yet set" and both write, because the second writer's
+        statement re-evaluates the guard against the first writer's
+        committed value and matches zero rows.
+
+        Returns True only when THIS call changed the row: the first
+        claimant wins and every later claimant of the same value
+        returns False.  A DIFFERENT value always wins (an advance, e.g.
+        the sweep watermark moving to a new date) and re-arms the
+        same-value loser check for the new value.
+
+        Runs under the shared connection lock and inside one
+        transaction, like :meth:`set`; ``cursor.rowcount`` (1 for a
+        matched write, 0 for a guarded no-op) is captured by the
+        wrapper on the executor thread, so no sqlite3 object crosses
+        back to the event loop.
+        """
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                result = await self._database.execute(
+                    f"INSERT INTO {_TABLE} (key, value) VALUES (?, ?) "
+                    "ON CONFLICT (key) DO UPDATE SET value = excluded.value "
+                    f"WHERE {_TABLE}.value IS NOT excluded.value",
+                    (key, value),
+                )
+        return result.rowcount == 1

custom_components/nestquest/core/dao_presence.py

@@ -0,0 +1,343 @@
+"""Typed DAO layer for the presence_schedules and presence_overrides tables.
+
+All SQL for these tables lives in this module per the feature
+guardrails: callers get typed dataclasses back and never see raw rows
+or SQL.  Every method is async and runs through
+:class:`~.db.NestQuestDatabase`, so each statement executes on the HA
+executor and the event loop never blocks.
+
+Semantics per the done-condition and Feature 05:
+
+- A child has AT MOST ONE presence schedule (schema UNIQUE); upserting
+  by child updates the existing row rather than raising.
+- A child with NO schedule row is present every day — the absence of a
+  row is meaningful state, expressed by :meth:`PresenceSchedulesDao.get_by_child`
+  returning None, never by an empty pattern row.
+- Overrides beat the pattern for their date range (that resolution is
+  the presence engine's job, Feature 05); the DAO only stores and
+  lists them.  A single-day override stores the same date as both
+  start and end (schema CHECK requires end >= start).
+
+Date arguments are validated as strict YYYY-MM-DD per the same policy
+the rules DAO applies: the schema's lexical CHECKs cannot prove
+calendar validity.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .dao_children import _connection_lock
+from .dao_rules import _UNSET, _validate_date
+from .db import NestQuestDatabase
+
+
+@dataclass(frozen=True)
+class PresenceScheduleRecord:
+    """One row of ``presence_schedules``."""
+
+    id: int
+    child_id: int
+    cycle_length_weeks: int
+    anchor_date: str
+    pattern: str
+
+
+@dataclass(frozen=True)
+class PresenceOverrideRecord:
+    """One row of ``presence_overrides``."""
+
+    id: int
+    child_id: int
+    start_date: str
+    end_date: str
+    is_present: bool
+    note: str | None
+
+
+_SCHEDULE_COLUMNS = (
+    "id, child_id, cycle_length_weeks, anchor_date, pattern"
+)
+_OVERRIDE_COLUMNS = (
+    "id, child_id, start_date, end_date, is_present, note"
+)
+
+
+def _schedule_from_row(row: tuple) -> PresenceScheduleRecord:
+    return PresenceScheduleRecord(
+        id=row[0],
+        child_id=row[1],
+        cycle_length_weeks=row[2],
+        anchor_date=row[3],
+        pattern=row[4],
+    )
+
+
+def _override_from_row(row: tuple) -> PresenceOverrideRecord:
+    return PresenceOverrideRecord(
+        id=row[0],
+        child_id=row[1],
+        start_date=row[2],
+        end_date=row[3],
+        is_present=bool(row[4]),
+        note=row[5],
+    )
+
+
+class PresenceSchedulesDao:
+    """Typed async access to the ``presence_schedules`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def upsert_by_child(
+        self,
+        child_id: int,
+        cycle_length_weeks: int,
+        anchor_date: str,
+        pattern: str,
+    ) -> PresenceScheduleRecord:
+        """Set the child's presence schedule, replacing any existing one.
+
+        Upsert semantics are the done-condition: a second schedule for
+        the same child updates the existing row rather than raising.
+        Runs under the connection lock so a concurrent upsert/delete
+        for the same child serializes instead of colliding on the
+        schema's UNIQUE(child_id).  Pattern validity (segment shape,
+        segment count = cycle_length_weeks) is enforced by the schema
+        CHECKs; the child must exist (FK) — validated atomically here
+        so a deleted child cannot pass a stale check.
+        """
+        _validate_date(anchor_date, "anchor_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                await self._database.execute(
+                    "INSERT INTO presence_schedules (child_id, "
+                    "cycle_length_weeks, anchor_date, pattern) "
+                    "VALUES (?, ?, ?, ?) "
+                    "ON CONFLICT (child_id) DO UPDATE SET "
+                    "cycle_length_weeks = excluded.cycle_length_weeks, "
+                    "anchor_date = excluded.anchor_date, "
+                    "pattern = excluded.pattern",
+                    (child_id, cycle_length_weeks, anchor_date, pattern),
+                )
+                schedule = await self.get_by_child(child_id)
+        assert schedule is not None
+        return schedule
+
+    async def get_by_child(
+        self, child_id: int
+    ) -> PresenceScheduleRecord | None:
+        """Return the child's schedule, or None when the child has none.
+
+        None is meaningful and UNAMBIGUOUS here: the child exists and
+        has no schedule row, i.e. the child is present every day
+        (Feature 05 guardrail).  An unknown child id raises ValueError
+        instead of returning None, because "nonexistent child" must
+        never be silently read as "present every day".
+        """
+        child = await self._database.fetch_one(
+            "SELECT 1 FROM children WHERE id = ?", (child_id,)
+        )
+        if child is None:
+            raise ValueError(f"child {child_id} does not exist")
+        row = await self._database.fetch_one(
+            f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
+            "WHERE child_id = ?",
+            (child_id,),
+        )
+        return _schedule_from_row(row) if row is not None else None
+
+    async def delete(self, child_id: int) -> bool:
+        """Remove the child's schedule; True if a row was removed.
+
+        After deletion the child is present every day (no row means
+        no restriction).  Deleting a schedule the child never had
+        returns False.
+        """
+        result = await self._database.execute(
+            "DELETE FROM presence_schedules WHERE child_id = ?",
+            (child_id,),
+        )
+        return result.rowcount > 0
+
+
+class PresenceOverridesDao:
+    """Typed async access to the ``presence_overrides`` table."""
+
+    def __init__(self, database: NestQuestDatabase) -> None:
+        self._database = database
+
+    async def create(
+        self,
+        child_id: int,
+        start_date: str,
+        end_date: str,
+        is_present: bool,
+        *,
+        note: str | None = None,
+    ) -> PresenceOverrideRecord:
+        """Insert one override and return the record as stored.
+
+        The child must exist (validated atomically under the
+        connection lock).  Date shape is validated strictly, and the
+        schema CHECK rejects end < start.
+
+        Overlap policy (Feature 05): an override for a child may not
+        overlap another override of the SAME child — two different
+        present/absent answers for one date are unresolvable.  The
+        overlap check (inclusive boundaries) runs inside the same
+        transaction as the INSERT, so a racing create cannot slip a
+        conflicting override between the check and the write; a
+        conflict raises ValueError naming the conflicting override's
+        id and range.
+        """
+        _validate_date(start_date, "start_date")
+        _validate_date(end_date, "end_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                child = await self._database.fetch_one(
+                    "SELECT 1 FROM children WHERE id = ?", (child_id,)
+                )
+                if child is None:
+                    raise ValueError(f"child {child_id} does not exist")
+                # Only a well-ordered range has overlap semantics:
+                # inverted ranges fall through to the INSERT and hit
+                # the schema's end>=start CHECK, preserving the
+                # IntegrityError contract the matrix tests rely on.
+                if end_date >= start_date:
+                    conflicting = await self._database.fetch_one(
+                        f"SELECT {_OVERRIDE_COLUMNS} "
+                        "FROM presence_overrides "
+                        "WHERE child_id = ? AND end_date >= ? "
+                        "AND start_date <= ? ORDER BY id LIMIT 1",
+                        (child_id, start_date, end_date),
+                    )
+                else:
+                    conflicting = None
+                if conflicting is not None:
+                    conflict = _override_from_row(conflicting)
+                    raise ValueError(
+                        f"override for child {child_id} "
+                        f"[{start_date}, {end_date}] overlaps existing "
+                        f"override {conflict.id} "
+                        f"[{conflict.start_date}, {conflict.end_date}] "
+                        f"(is_present={conflict.is_present})"
+                    )
+                result = await self._database.execute(
+                    "INSERT INTO presence_overrides (child_id, "
+                    "start_date, end_date, is_present, note) "
+                    "VALUES (?, ?, ?, ?, ?)",
+                    (child_id, start_date, end_date, int(is_present), note),
+                )
+                override = await self._database.fetch_one(
+                    f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+                    "WHERE id = ?",
+                    (result.lastrowid,),
+                )
+        assert override is not None
+        return _override_from_row(override)
+
+    async def list_by_child_and_range(
+        self,
+        child_id: int,
+        range_start: str,
+        range_end: str,
+    ) -> list[PresenceOverrideRecord]:
+        """Return the child's overrides overlapping [range_start, range_end].
+
+        An override overlaps the range when it ends on or after the
+        range starts and starts on or before the range ends (inclusive
+        boundary dates, matching the storage model where overrides are
+        closed date ranges).  Ordered by start date.
+        """
+        _validate_date(range_start, "range_start")
+        _validate_date(range_end, "range_end")
+        if range_end < range_start:
+            raise ValueError(
+                "range_end must be on or after range_start, got "
+                f"{range_end!r} < {range_start!r}"
+            )
+        rows = await self._database.fetch_all(
+            f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+            "WHERE child_id = ? AND end_date >= ? AND start_date <= ? "
+            "ORDER BY start_date",
+            (child_id, range_start, range_end),
+        )
+        return [_override_from_row(row) for row in rows]
+
+    async def get(self, override_id: int) -> PresenceOverrideRecord | None:
+        """Return one override by id, or None when it does not exist."""
+        row = await self._database.fetch_one(
+            f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+            "WHERE id = ?",
+            (override_id,),
+        )
+        return _override_from_row(row) if row is not None else None
+
+    async def delete(self, override_id: int) -> bool:
+        """Remove one override by id; True if a row was removed."""
+        result = await self._database.execute(
+            "DELETE FROM presence_overrides WHERE id = ?",
+            (override_id,),
+        )
+        return result.rowcount > 0
+
+
+async def read_snapshot_unlocked(
+    database: NestQuestDatabase,
+    child_ids: list[int],
+    range_start: str,
+    range_end: str,
+) -> tuple[
+    dict[int, PresenceScheduleRecord],
+    dict[int, list[PresenceOverrideRecord]],
+]:
+    """Read schedules and overrides for ``child_ids`` WITHOUT locking.
+
+    MUST be called inside the connection lock and an open transaction, so
+    the schedules and overrides returned here stay coherent with every
+    other table the caller reads inside that same transaction (the
+    materialization walk's single input snapshot does exactly that).  The
+    date range comes already validated by the caller.
+
+    Returns ``(schedules, overrides)``:
+
+    - ``schedules`` maps ``child_id`` to its :class:`PresenceScheduleRecord`
+      for every child that HAS a schedule row.  A child absent from the
+      mapping has no schedule, i.e. is present every day (Feature 05).
+    - ``overrides`` maps ``child_id`` to that child's overrides overlapping
+      ``[range_start, range_end]`` (inclusive boundaries), ordered by start
+      date; a child with no matching override is absent from the mapping.
+
+    ``child_ids`` must name existing children (the caller derives them
+    from a trusted snapshot, within the same transaction).
+    """
+    children = sorted(set(child_ids))
+    if not children:
+        return {}, {}
+    placeholders = ",".join("?" for _ in children)
+    schedule_rows = await database.fetch_all(
+        f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
+        f"WHERE child_id IN ({placeholders})",
+        tuple(children),
+    )
+    override_rows = await database.fetch_all(
+        f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides "
+        f"WHERE child_id IN ({placeholders}) AND end_date >= ? "
+        "AND start_date <= ? ORDER BY start_date",
+        tuple(children) + (range_start, range_end),
+    )
+    schedules = {
+        record.child_id: record
+        for record in map(_schedule_from_row, schedule_rows)
+    }
+    overrides: dict[int, list[PresenceOverrideRecord]] = {}
+    for row in override_rows:
+        record = _override_from_row(row)
+        overrides.setdefault(record.child_id, []).append(record)
+    return schedules, overrides

custom_components/nestquest/core/db.py

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

custom_components/nestquest/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/history.py

@@ -0,0 +1,405 @@
+"""Read-only history layer for the admin plane (Admin spec §5, task 2d2dda53).
+
+Assembles the History screen's event rows over the append-only
+completion log: a query over a CLOSED date range ``[start_date,
+end_date]`` for one of three filters —
+
+- ``all`` — every completion event (completed AND uncompleted) whose
+  instance is due in the range;
+- ``reversals`` — the uncompleted events only;
+- ``missed`` — the DERIVED missed instances in the range.
+
+Range semantics (Feature 13's rule, kept): the range scopes by the
+INSTANCE's ``due_date`` — the day the task was owed — not the event's
+wall-clock ``occurred_at``, because history reporting asks "what
+happened to the tasks due that day".  ``missed`` is derived, never
+stored: rows come from :func:`~.completion.list_missed_for_child`
+(past-due open instances, the same ``_derived_state`` rule the
+coordinator uses), and nothing is ever appended for them.
+
+Row shape: the Admin spec §5 event-row fields, fixed and documented in
+:data:`CSV_COLUMNS` — ``occurred_at``, ``event_type``,
+``child_name``, ``child_id``, ``quest_title``, ``instance_id``,
+``window``, ``due_date``, ``due_time``, ``actor``, ``was_on_time``.
+Derived missed rows carry ``event_type`` ``'missed'`` (never a stored
+event_type), no ``occurred_at`` (there is no event), ``was_on_time``
+``None`` and the spec's ``nightly sweep`` actor.  A stored event's
+``actor`` follows the spec's meta shape: the ``actor_user_id`` string
+for a user event (``joshua``), ``panel (Child)`` naming the tapped
+profile for a panel event.
+
+Validation policy (module-level, shared by both the JSON query and the
+CSV export): the filter must be one of :data:`FILTERS` and the range
+must be two strict ``YYYY-MM-DD`` dates with ``end >= start``;
+violations raise ``ValueError`` naming the offending field
+(``filter`` / ``start`` / ``end``) BEFORE any read.  The whole
+household read runs under the task-reentrant connection lock so every
+row of one answer is one snapshot — the same discipline
+:mod:`.completion` gives its read-decide-write paths.
+
+:func:`rows_to_csv` serializes rows with the :mod:`csv` module (proper
+quoting, one stable header row) and :func:`export_history_csv` runs
+query + serialization as ONE call, so the CSV export can never drift
+from the JSON query's filtered range.  No permission check lives here
+(that is the admin router's single ``require_admin`` dependency).
+"""
+from __future__ import annotations
+
+import csv
+import datetime
+import io
+from dataclasses import dataclass
+
+from .completion import _reentrant_connection_lock, list_missed_for_child
+from .dao_children import ChildRecord, ChildrenDao
+from .dao_instances import (
+    EVENT_UNCOMPLETED,
+    CompletionEventRecord,
+    CompletionEventsDao,
+    QuestInstanceRecord,
+    QuestInstancesDao,
+)
+from .dao_rules import QuestDefinitionsDao, _validate_date
+from .db import NestQuestDatabase
+
+#: The ``all`` filter: every completion event in the range.
+FILTER_ALL = "all"
+
+#: The ``reversals`` filter: uncompleted events only.
+FILTER_REVERSALS = "reversals"
+
+#: The ``missed`` filter: derived missed instances in the range.
+FILTER_MISSED = "missed"
+
+#: The filters the query accepts, in the Admin spec's chip order.
+FILTERS = (FILTER_ALL, FILTER_REVERSALS, FILTER_MISSED)
+
+#: The ``event_type`` a derived missed row reports.  ``missed`` is a
+#: DERIVED state, never a stored event_type (Feature 08).
+EVENT_MISSED = "missed"
+
+#: The actor a derived missed row reports (Admin spec §5 meta:
+#: ``missed · nightly sweep``).
+ACTOR_NIGHTLY_SWEEP = "nightly sweep"
+
+#: The CSV column set, in header order — the Admin spec §5 event-row
+#: fields.  The header row is exactly this tuple, always, so a consumer
+#: can key on column names.
+CSV_COLUMNS = (
+    "occurred_at",
+    "event_type",
+    "child_name",
+    "child_id",
+    "quest_title",
+    "instance_id",
+    "window",
+    "due_date",
+    "due_time",
+    "actor",
+    "was_on_time",
+)
+
+
+@dataclass(frozen=True)
+class HistoryRow:
+    """One history row: a stored event or a derived missed instance.
+
+    The fields are :data:`CSV_COLUMNS` in order.  For a derived missed
+    row ``occurred_at`` is ``None`` (no event exists) and ``was_on_time``
+    is ``None``; for a stored event ``event_type`` is
+    ``'completed'``/``'uncompleted'`` and the fields come from the event
+    joined with its instance, child and definition.
+    """
+
+    occurred_at: str | None
+    event_type: str
+    child_name: str
+    child_id: int
+    quest_title: str
+    instance_id: int
+    window: str
+    due_date: str
+    due_time: str | None
+    actor: str
+    was_on_time: bool | None
+
+
+def _validate_filter(filter_name: str) -> str:
+    """Return the filter, or raise ValueError naming the field."""
+    if filter_name not in FILTERS:
+        raise ValueError(
+            f"filter must be one of {', '.join(repr(f) for f in FILTERS)}, "
+            f"got {filter_name!r}"
+        )
+    return filter_name
+
+
+def _validate_range(start_date: str, end_date: str) -> tuple[str, str]:
+    """Validate the closed range and return it, else raise naming the field.
+
+    Both bounds must be strict ``YYYY-MM-DD`` dates (the shared
+    :func:`~.dao_rules._validate_date`, so non-padded or re-ordered
+    shapes are rejected and a non-string raises naming the field) and
+    ``end`` must be on or after ``start``.
+    """
+    _validate_date(start_date, "start")
+    _validate_date(end_date, "end")
+    if end_date < start_date:
+        raise ValueError(
+            f"end must be on or after start, got {end_date!r} < "
+            f"{start_date!r}"
+        )
+    return start_date, end_date
+
+
+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 _event_actor(
+    event: CompletionEventRecord, actor_child: ChildRecord | None
+) -> str:
+    """Return the spec-meta actor string for one stored event.
+
+    A user event reports the ``actor_user_id`` string (the spec's
+    ``uncompleted · joshua (admin)`` shape); a panel event reports
+    ``panel (Child)`` naming the tapped profile.  The tapped child is
+    never hard-deleted, so the lookup below is a belt-and-braces
+    fallback to the stored id, never a silent rewrite of policy.
+    """
+    if event.actor_source == "user":
+        return event.actor_user_id or ""
+    if actor_child is not None:
+        return f"panel ({actor_child.display_name})"
+    return f"panel ({event.actor_child_id})"
+
+
+def _event_row(
+    event: CompletionEventRecord,
+    instance: QuestInstanceRecord,
+    child: ChildRecord,
+    quest_title: str,
+    actor_child: ChildRecord | None,
+) -> HistoryRow:
+    """Join one stored event with its instance, child and definition."""
+    return HistoryRow(
+        occurred_at=event.occurred_at,
+        event_type=event.event_type,
+        child_name=child.display_name,
+        child_id=event.child_id,
+        quest_title=quest_title,
+        instance_id=event.instance_id,
+        window=instance.window,
+        due_date=instance.due_date,
+        due_time=instance.due_time,
+        actor=_event_actor(event, actor_child),
+        was_on_time=event.was_on_time,
+    )
+
+
+def _missed_row(
+    instance: QuestInstanceRecord,
+    child: ChildRecord,
+    quest_title: str,
+) -> HistoryRow:
+    """Build the derived row for one past-due open instance."""
+    return HistoryRow(
+        occurred_at=None,
+        event_type=EVENT_MISSED,
+        child_name=child.display_name,
+        child_id=instance.child_id,
+        quest_title=quest_title,
+        instance_id=instance.id,
+        window=instance.window,
+        due_date=instance.due_date,
+        due_time=instance.due_time,
+        actor=ACTOR_NIGHTLY_SWEEP,
+        was_on_time=None,
+    )
+
+
+def _csv_values(row: HistoryRow) -> list[str]:
+    """Return one CSV row's cell values in :data:`CSV_COLUMNS` order.
+
+    ``None`` cells serialize as empty (a missed row has no
+    ``occurred_at``); ``was_on_time`` serializes as ``true``/``false``
+    when the event carries the flag and empty when it does not.
+    """
+    return [
+        row.occurred_at or "",
+        row.event_type,
+        row.child_name,
+        str(row.child_id),
+        row.quest_title,
+        str(row.instance_id),
+        row.window,
+        row.due_date,
+        row.due_time or "",
+        row.actor,
+        "" if row.was_on_time is None else str(row.was_on_time).lower(),
+    ]
+
+
+def rows_to_csv(rows: list[HistoryRow]) -> str:
+    """Serialize history rows to CSV text with the documented header.
+
+    The FIRST row is always :data:`CSV_COLUMNS`, so the header is
+    stable and deterministic; the :mod:`csv` module handles quoting
+    (titles or names containing commas or quotes are quoted per RFC
+    4180) and CRLF line endings.
+    """
+    buffer = io.StringIO()
+    writer = csv.writer(buffer)
+    writer.writerow(CSV_COLUMNS)
+    for row in rows:
+        writer.writerow(_csv_values(row))
+    return buffer.getvalue()
+
+
+async def query_history(
+    database: NestQuestDatabase,
+    filter_name: str,
+    start_date: str,
+    end_date: str,
+    *,
+    today: datetime.date | None = None,
+) -> list[HistoryRow]:
+    """Return the history rows for ``filter_name`` over the closed range.
+
+    Validates the filter and the strict ``YYYY-MM-DD`` range (raising
+    ``ValueError`` naming ``filter`` / ``start`` / ``end``) BEFORE any
+    read, then builds the rows:
+
+    - ``all`` / ``reversals``: every child's events whose instances are
+      due in the range (:meth:`~.dao_instances.CompletionEventsDao.list_by_child_and_date_range`,
+      the Feature 13 due-date scope), ``reversals`` keeping only the
+      ``uncompleted`` rows.
+    - ``missed``: :func:`~.completion.list_missed_for_child` per child —
+      the SAME derived-state rule the coordinator uses, never a new one,
+      and never a stored event.
+
+    Rows are ordered deterministically by ``due_date``, then instance,
+    then event id (the per-instance append order, so a completion and
+    its reversal keep their order).  ``today`` pins the HA-local date
+    the missed derivation compares due dates against (the host calendar
+    date when omitted).  The whole read runs under the task-reentrant
+    connection lock — :func:`list_missed_for_child` re-enters it — so
+    one answer is one snapshot.
+    """
+    filter_name = _validate_filter(filter_name)
+    start_date, end_date = _validate_range(start_date, end_date)
+    today_date = _resolve_today(today)
+
+    keyed: list[tuple[tuple[str, int, int], HistoryRow]] = []
+    async with _reentrant_connection_lock(database):
+        children = await ChildrenDao(database).list_all()
+        children_by_id = {child.id: child for child in children}
+        instances = QuestInstancesDao(database)
+        definitions = QuestDefinitionsDao(database)
+        events = CompletionEventsDao(database)
+        titles: dict[int, str] = {}
+
+        if filter_name == FILTER_MISSED:
+            for child in children:
+                for instance in await list_missed_for_child(
+                    database, child.id, start_date, end_date, today=today_date
+                ):
+                    if instance.definition_id not in titles:
+                        definition = await definitions.get(
+                            instance.definition_id
+                        )
+                        assert definition is not None, (
+                            "a materialized instance's definition exists"
+                        )
+                        titles[instance.definition_id] = definition.title
+                    keyed.append(
+                        (
+                            (instance.due_date, instance.id, 0),
+                            _missed_row(
+                                instance,
+                                child,
+                                titles[instance.definition_id],
+                            ),
+                        )
+                    )
+            keyed.sort(key=lambda pair: pair[0])
+            return [row for _, row in keyed]
+
+        for child in children:
+            for event in await events.list_by_child_and_date_range(
+                child.id, start_date, end_date
+            ):
+                if filter_name == FILTER_REVERSALS and (
+                    event.event_type != EVENT_UNCOMPLETED
+                ):
+                    continue
+                instance = await instances.get_by_id(event.instance_id)
+                assert instance is not None, (
+                    "an event's instance is never deleted (append-only "
+                    "history keeps its references)"
+                )
+                actor_child = (
+                    children_by_id.get(event.actor_child_id)
+                    if event.actor_child_id is not None
+                    else None
+                )
+                if instance.definition_id not in titles:
+                    definition = await definitions.get(instance.definition_id)
+                    assert definition is not None, (
+                        "a materialized instance's definition exists"
+                    )
+                    titles[instance.definition_id] = definition.title
+                keyed.append(
+                    (
+                        (instance.due_date, instance.id, event.id),
+                        _event_row(
+                            event,
+                            instance,
+                            child,
+                            titles[instance.definition_id],
+                            actor_child,
+                        ),
+                    )
+                )
+        keyed.sort(key=lambda pair: pair[0])
+        return [row for _, row in keyed]
+
+
+async def export_history_csv(
+    database: NestQuestDatabase,
+    filter_name: str,
+    start_date: str,
+    end_date: str,
+    *,
+    today: datetime.date | None = None,
+) -> str:
+    """Return the filtered history as CSV text, header row included.
+
+    ONE query + serialization call so the CSV export carries exactly
+    the JSON query's filtered range and order — the same
+    :func:`query_history` validation, rows and :func:`rows_to_csv`
+    serializer, never a second implementation.
+    """
+    rows = await query_history(
+        database, filter_name, start_date, end_date, today=today
+    )
+    return rows_to_csv(rows)
+
+
+__all__ = [
+    "ACTOR_NIGHTLY_SWEEP",
+    "CSV_COLUMNS",
+    "EVENT_MISSED",
+    "EVENT_UNCOMPLETED",
+    "FILTERS",
+    "FILTER_ALL",
+    "FILTER_MISSED",
+    "FILTER_REVERSALS",
+    "HistoryRow",
+    "export_history_csv",
+    "query_history",
+    "rows_to_csv",
+]

custom_components/nestquest/core/materialize.py

@@ -0,0 +1,381 @@
+"""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 (or every assignee, when the definition's
+  ``skip_on_away`` is off) 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,
+         snapshot.definition.skip_on_away)
+        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, skip_on_away
+        ) 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 skip_on_away and 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/migrations.py

@@ -0,0 +1,620 @@
+"""Versioned schema migration runner for the NestQuest SQLite database.
+
+The runner owns one metadata table, ``nestquest_schema_version``, holding
+a single row with the schema version the database file currently
+reflects.  Migrations are declared as an ordered list: entry ``n``
+upgrades version ``n-1`` to version ``n``.  Applying a migration means
+running its DDL inside one transaction and stamping the new version in
+that same transaction, so a database never persists a half-applied
+migration: any failure rolls the statements and the version stamp back
+together, leaving the file at its prior version.
+
+Version 0 means "the file exists but carries no NestQuest schema yet"
+— a fresh file, or a file this integration has never written.  Starting
+the runner against version 0 applies migration 1, which applies the
+full v1 DDL from :mod:`.schema` and stamps version 1.
+
+Migration 1 was rewritten pre-release (D-007): nothing was ever
+shipped, so the v1 DDL now creates the ``quest_*`` tables directly
+instead of the legacy ``task_*`` spellings, and no compatibility shim
+exists.  Dev machines that already hold a version-1 database with
+``task_*`` tables are handled by migration 2, which detects the legacy
+table names and ``ALTER TABLE ... RENAME TO``s them to their current
+names before anything else assumes the new model.  Migration 3 brings
+pre-D-008 databases to the multi-assignee model: it creates
+``quest_definition_assignees`` and, when ``quest_definitions`` still
+carries a single ``child_id`` column, rebuilds the table without it,
+copying each definition's assignee across.  Migration 4 adds the
+windows table, migration 5 rebuilds ``quest_instances`` onto the
+widened (definition_id, child_id, due_date, window) key, and migration
+6 rebuilds ``completion_events`` with the D-008 ``actor_child_id``
+column.  Migration 7 adds the generic ``nestquest_meta_state``
+key/value table for integration-owned bookkeeping (Feature 11's
+missed-sweep watermark).  Migration 8 adds the ``skip_on_away``
+column to ``quest_definitions`` (Feature 22), defaulting to 1.  Each
+callable migration runs inside its own transaction
+together with its version stamp, so a crash mid-step rolls the
+statements and the stamp back together.
+
+Migration entries are either an ordered sequence of SQL statements or
+an async callable taking ``(database, target_version)``.  Callables
+exist for steps whose SQL depends on the database's current state (a
+legacy rename only fires when a legacy table is present; a rebuild only
+when the old column shape is present) and own their transaction so they
+can bracket it with connection pragmas the runner's uniform transaction
+cannot express.
+
+Each migration's statements and its version stamp run inside ONE
+transaction, and the stamp is written as DELETE + INSERT rather than
+UPDATE because a version-0 database has no version row to update yet.
+An UPDATE form would silently match zero rows there and leave the
+database migrated but unstamped — reporting version 0 forever, and
+re-applying migration 1 on every startup.  The DELETE+INSERT shape is
+also what makes the stamp a replace, so the row never duplicates.
+
+Idempotence across restarts: a database already at the latest version
+has no pending migrations, so the runner opens a read-only check, finds
+nothing to do, and leaves the file byte-untouched (no write transaction
+is opened, so no WAL churn).
+
+Migration list policy: entries are append-only.  Once shipped, a
+migration's SQL must never be edited — an old database applying it for
+the first time and a fresh database would then diverge.  Fix-forward
+with a new migration instead.  The version stamp lives in the same
+SQLite file as the data it describes, so restoring a backup restores
+its matching schema version with it.
+
+Corrupt or missing files are not this module's concern: startup
+handling of those cases is task d5bca74b, which decides whether to
+open fresh or raise ConfigEntryNotReady.  This runner assumes it is
+handed an open, working connection.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Union
+
+from .db import NestQuestDatabase
+from .schema import (
+    COMPLETION_EVENTS_TABLE_SQL,
+    QUEST_DEFINITIONS_TABLE_SQL,
+    QUEST_INSTANCES_TABLE_SQL,
+    SCHEMA_V1_STATEMENTS,
+    SCHEMA_V1_QUEST_DEFINITION_ASSIGNEES_DDL,
+    SCHEMA_V1_QUEST_DEFINITION_WINDOWS_DDL,
+    SCHEMA_V7_META_STATE_DDL,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+#: One migration entry: either an ordered sequence of SQL statements or
+#: an async callable taking ``(database, target_version)`` that manages
+#: its own transaction and stamps via :func:`stamp_schema_version`.
+MigrationStep = Union[
+    Sequence[str],
+    Callable[[NestQuestDatabase, int], Awaitable[None]],
+]
+
+#: Metadata table holding the applied schema version.  Prefixed with the
+#: integration domain so a config directory shared with other tools can
+#: never collide with a foreign ``schema_version`` table.
+VERSION_TABLE = "nestquest_schema_version"
+
+#: DDL for the version metadata table.  The singleton-row invariant is
+#: enforced by the schema itself: ``id`` is fixed at 1 by CHECK, keyed
+#: PRIMARY KEY, so the table can never hold a second row, and the
+#: stamp write is an UPDATE (no DELETE+INSERT needed).  ``version`` is
+#: a positive integer: version 0 means "no row" and is never stored,
+#: so a negative or zero stored value is corruption, not a state the
+#: runner can act on.
+VERSION_TABLE_DDL = f"""
+    CREATE TABLE IF NOT EXISTS {VERSION_TABLE} (
+        id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
+        version INTEGER NOT NULL CHECK (version >= 1)
+    )
+"""
+
+#: One-based index into :data:`MIGRATIONS`: entry ``n`` upgrades
+#: version ``n-1`` to version ``n``.
+MIGRATION_1_V1_DDL: list[str] = list(SCHEMA_V1_STATEMENTS)
+
+#: The assignees table DDL, shared with migration 1 via the schema
+#: module so a rebuilt and a freshly created table cannot drift.
+_ASSIGNEES_TABLE_DDL: str = SCHEMA_V1_QUEST_DEFINITION_ASSIGNEES_DDL[0]
+
+#: Legacy (pre-D-007) table name -> current table name.  Order matters:
+#: the parent table renames first so the child's foreign key reference
+#: is rewritten while its parent's new name is already in place.
+LEGACY_TASK_TABLE_RENAMES: tuple[tuple[str, str], ...] = (
+    ("task_definitions", "quest_definitions"),
+    ("task_instances", "quest_instances"),
+)
+
+
+async def stamp_schema_version(
+    database: NestQuestDatabase, version: int
+) -> None:
+    """Write the schema version stamp (inside the caller's transaction).
+
+    INSERT keyed on the singleton row (id = 1) with an upsert: a fresh
+    file has no row yet, so UPDATE alone would silently match zero rows
+    there and leave a migrated-but-unstamped database.
+    """
+    await database.execute(
+        f"INSERT INTO {VERSION_TABLE} (id, version) "
+        "VALUES (1, ?) "
+        "ON CONFLICT (id) DO UPDATE SET version = excluded.version",
+        (version,),
+    )
+
+
+async def _table_has_column(
+    database: NestQuestDatabase, table: str, column: str
+) -> bool:
+    """Return True when ``table`` currently carries ``column``."""
+    rows = await database.fetch_all(f"PRAGMA table_info({table})")
+    return any(row[1] == column for row in rows)
+
+
+#: Window assigned to instances migrated from the pre-window instance
+#: shape (D-008).  Pre-window rows were generated for whole-day
+#: obligations; the morning window is the documented default landing
+#: spot, and future dates are regenerated with real window declarations
+#: by materialization (delete_future_uncompleted + re-run).
+LEGACY_MIGRATED_WINDOW = "morning"
+
+
+async def _rename_legacy_task_tables(
+    database: NestQuestDatabase, target_version: int
+) -> None:
+    """Rename any surviving ``task_*`` tables to their ``quest_*`` names.
+
+    Dev-machines-only path (D-007): a database stamped version 1 by the
+    pre-rename runner holds ``task_definitions``/``task_instances``.
+    Each legacy name still present is renamed; fresh databases find
+    nothing and this step is a no-op.  Modern SQLite rewrites foreign
+    key clauses in other tables to follow the rename, so the renamed
+    schema is indistinguishable from a freshly created one apart from
+    internal autoindex names.  Runs in its own transaction together
+    with the version stamp, so a crash rolls both back.
+    """
+    async with database.transaction():
+        for legacy_name, current_name in LEGACY_TASK_TABLE_RENAMES:
+            row = await database.fetch_one(
+                "SELECT 1 FROM sqlite_master WHERE type = 'table' "
+                "AND name = ?",
+                (legacy_name,),
+            )
+            if row is not None:
+                await database.execute(
+                    f'ALTER TABLE "{legacy_name}" RENAME TO "{current_name}"'
+                )
+                LOGGER.info(
+                    "Renamed legacy table %s to %s",
+                    legacy_name,
+                    current_name,
+                )
+        await stamp_schema_version(database, target_version)
+
+
+async def _add_definition_assignees(
+    database: NestQuestDatabase, target_version: int
+) -> None:
+    """Bring definitions to the multi-assignee model (D-008).
+
+    Two shapes arrive here:
+
+    - Fresh or renamed databases whose ``quest_definitions`` already
+      matches the current canonical DDL (no ``child_id`` column): only
+      the assignees table needs creating (``IF NOT EXISTS`` is a no-op
+      when migration 1 already made it).
+    - Databases stamped at version 2 whose ``quest_definitions`` still
+      carries the single ``child_id`` column: the table is rebuilt via
+      SQLite's canonical procedure — create the new table, copy rows,
+      move each definition's assignee into
+      ``quest_definition_assignees``, drop the old table, rename — so
+      ``DROP COLUMN``'s foreign-key restriction never applies and no
+      definition or instance row is lost.
+
+    The copy runs with ``foreign_keys = OFF`` because dropping the old
+    table under enforcement would fire the implicit DELETE and violate
+    the ``quest_instances`` foreign key; ``PRAGMA foreign_key_check``
+    runs inside the same transaction before the stamp, so a corrupt
+    copy aborts the whole migration instead of persisting.  The pragma
+    is a connection-level no-op inside a transaction, hence the
+    off/transaction/on bracket.
+    """
+    legacy_child_id = await _table_has_column(
+        database, "quest_definitions", "child_id"
+    )
+    await database.execute("PRAGMA foreign_keys = OFF")
+    try:
+        async with database.transaction():
+            await database.execute(_ASSIGNEES_TABLE_DDL)
+            if legacy_child_id:
+                await database.execute(
+                    "CREATE TABLE quest_definitions_rebuilt "
+                    f"{QUEST_DEFINITIONS_TABLE_SQL}"
+                )
+                await database.execute(
+                    "INSERT INTO quest_definitions_rebuilt "
+                    "(id, title, description, icon, schedule_rule_id, "
+                    "due_time, is_active, created_at) "
+                    "SELECT id, title, description, icon, "
+                    "schedule_rule_id, due_time, is_active, created_at "
+                    "FROM quest_definitions ORDER BY id"
+                )
+                await database.execute(
+                    "INSERT OR IGNORE INTO quest_definition_assignees "
+                    "(definition_id, child_id) "
+                    "SELECT id, child_id FROM quest_definitions"
+                )
+                await database.execute("DROP TABLE quest_definitions")
+                await database.execute(
+                    "ALTER TABLE quest_definitions_rebuilt "
+                    "RENAME TO quest_definitions"
+                )
+                violations = await database.fetch_all(
+                    "PRAGMA foreign_key_check"
+                )
+                if violations:
+                    raise RuntimeError(
+                        "definition rebuild produced foreign-key "
+                        f"violations: {violations!r}"
+                    )
+            await stamp_schema_version(database, target_version)
+    finally:
+        await database.execute("PRAGMA foreign_keys = ON")
+
+
+async def _widen_instance_key(
+    database: NestQuestDatabase, target_version: int
+) -> None:
+    """Bring ``quest_instances`` to the D-008 instance key.
+
+    Databases whose instance table still carries the pre-window shape
+    (no ``window`` column, UNIQUE on (definition_id, due_date)) are
+    rebuilt via SQLite's canonical procedure into the widened shape —
+    UNIQUE (definition_id, child_id, due_date, window) — with every
+    migrated row landing in :data:`LEGACY_MIGRATED_WINDOW` so existing
+    ids (and the completion events referencing them) survive intact.
+    The old rows were unique per (definition, due_date), so pinning one
+    window cannot collide with the widened key.  Fresh databases whose
+    table already matches the canonical shape only stamp.
+
+    The rebuild runs with ``foreign_keys = OFF`` (dropping the old
+    table under enforcement would fire the implicit DELETE and violate
+    the ``completion_events`` foreign key) and verifies
+    ``PRAGMA foreign_key_check`` inside the transaction before the
+    stamp, so a corrupt copy aborts the whole migration.
+    """
+    legacy_shape = not await _table_has_column(
+        database, "quest_instances", "window"
+    )
+    await database.execute("PRAGMA foreign_keys = OFF")
+    try:
+        async with database.transaction():
+            if legacy_shape:
+                await database.execute(
+                    "CREATE TABLE quest_instances_rebuilt "
+                    f"{QUEST_INSTANCES_TABLE_SQL}"
+                )
+                await database.execute(
+                    "INSERT INTO quest_instances_rebuilt "
+                    "(id, definition_id, child_id, window, due_date, "
+                    "due_time, generated_at) "
+                    "SELECT id, definition_id, child_id, ?, due_date, "
+                    "due_time, generated_at "
+                    "FROM quest_instances ORDER BY id",
+                    (LEGACY_MIGRATED_WINDOW,),
+                )
+                await database.execute("DROP TABLE quest_instances")
+                await database.execute(
+                    "ALTER TABLE quest_instances_rebuilt "
+                    "RENAME TO quest_instances"
+                )
+                violations = await database.fetch_all(
+                    "PRAGMA foreign_key_check"
+                )
+                if violations:
+                    raise RuntimeError(
+                        "instance rebuild produced foreign-key "
+                        f"violations: {violations!r}"
+                    )
+                LOGGER.info(
+                    "Widened quest_instances key; migrated rows pinned "
+                    "to the %r window",
+                    LEGACY_MIGRATED_WINDOW,
+                )
+            await stamp_schema_version(database, target_version)
+    finally:
+        await database.execute("PRAGMA foreign_keys = ON")
+
+
+async def _add_actor_child_id(
+    database: NestQuestDatabase, target_version: int
+) -> None:
+    """Bring ``completion_events`` to the D-008 actor-child shape.
+
+    The ``actor_child_id`` column records which panel profile was
+    tapped; it cannot be added with ``ALTER TABLE ADD COLUMN`` alone
+    because the canonical shape also carries an actor-pair coherence
+    CHECK (panel events require it, user events forbid it), and CHECK
+    constraints cannot be added to an existing table.  Databases with
+    the legacy shape are therefore rebuilt via SQLite's canonical
+    procedure, backfilling each legacy panel row's ``actor_child_id``
+    to ``child_id`` — pre-D-008 panel completions were always recorded
+    against the tapped child themselves — while admin rows stay NULL.
+    Row ids are preserved so ``quest_instances`` references and the
+    append-only history stay intact.  Fresh databases already match
+    the canonical shape and only stamp.
+
+    The rebuild runs with ``foreign_keys = OFF`` and verifies
+    ``PRAGMA foreign_key_check`` inside the transaction before the
+    stamp.  The copy is an INSERT..SELECT, not an UPDATE: the
+    completion_events table keeps its append-only guarantee.
+    """
+    legacy_shape = not await _table_has_column(
+        database, "completion_events", "actor_child_id"
+    )
+    await database.execute("PRAGMA foreign_keys = OFF")
+    try:
+        async with database.transaction():
+            if legacy_shape:
+                await database.execute(
+                    "CREATE TABLE completion_events_rebuilt "
+                    f"{COMPLETION_EVENTS_TABLE_SQL}"
+                )
+                await database.execute(
+                    "INSERT INTO completion_events_rebuilt "
+                    "(id, instance_id, child_id, event_type, actor_source, "
+                    "actor_user_id, actor_child_id, occurred_at, "
+                    "was_on_time) "
+                    "SELECT id, instance_id, child_id, event_type, "
+                    "actor_source, actor_user_id, "
+                    "CASE WHEN actor_source = 'panel' THEN child_id "
+                    "ELSE NULL END, "
+                    "occurred_at, was_on_time "
+                    "FROM completion_events ORDER BY id"
+                )
+                await database.execute("DROP TABLE completion_events")
+                await database.execute(
+                    "ALTER TABLE completion_events_rebuilt "
+                    "RENAME TO completion_events"
+                )
+                violations = await database.fetch_all(
+                    "PRAGMA foreign_key_check"
+                )
+                if violations:
+                    raise RuntimeError(
+                        "completion_events rebuild produced foreign-key "
+                        f"violations: {violations!r}"
+                    )
+                LOGGER.info(
+                    "Added actor_child_id to completion_events; legacy "
+                    "panel rows backfilled to their own child_id"
+                )
+            await stamp_schema_version(database, target_version)
+    finally:
+        await database.execute("PRAGMA foreign_keys = ON")
+
+
+async def _add_skip_on_away(
+    database: NestQuestDatabase, target_version: int
+) -> None:
+    """Add the ``skip_on_away`` column to ``quest_definitions``.
+
+    Strictly additive: ``ALTER TABLE ... ADD COLUMN`` with a NOT NULL
+    DEFAULT 1, so existing rows read as 1 (skip absent dates — the
+    behaviour before the flag existed).  Fresh databases already carry
+    the column from the canonical DDL, so the ALTER is guarded and the
+    step only stamps there.
+    """
+    async with database.transaction():
+        if not await _table_has_column(
+            database, "quest_definitions", "skip_on_away"
+        ):
+            await database.execute(
+                "ALTER TABLE quest_definitions ADD COLUMN "
+                "skip_on_away INTEGER NOT NULL DEFAULT 1"
+            )
+        await stamp_schema_version(database, target_version)
+
+
+#: The ordered migration list.  Append-only: never edit an applied
+#: entry, add the next one instead.  (Migration 1's content was
+#: rewritten pre-release per D-007 — no version 1 database shipped.)
+MIGRATIONS: Sequence[MigrationStep] = [
+    MIGRATION_1_V1_DDL,
+    _rename_legacy_task_tables,
+    _add_definition_assignees,
+    # Migration 4 (D-008): the windows table is a plain new table — a
+    # CREATE IF NOT EXISTS suffices for both fresh databases (which
+    # already made it in migration 1) and pre-window databases.
+    list(SCHEMA_V1_QUEST_DEFINITION_WINDOWS_DDL),
+    # Migration 5 (D-008): rebuild quest_instances onto the widened
+    # (definition_id, child_id, due_date, window) key.
+    _widen_instance_key,
+    # Migration 6 (D-008): rebuild completion_events with the
+    # actor_child_id column and its actor-pair coherence CHECK,
+    # backfilling legacy panel rows to their own child_id.
+    _add_actor_child_id,
+    # Migration 7 (Feature 11): the generic meta_state key/value table
+    # — a plain new table, so CREATE IF NOT EXISTS suffices for both
+    # fresh databases (which already made it in migration 1) and
+    # pre-v7 databases.  Strictly additive; no existing table changes.
+    list(SCHEMA_V7_META_STATE_DDL),
+    # Migration 8 (Feature 22): the skip_on_away flag on
+    # quest_definitions — an additive column defaulting to 1, so every
+    # pre-existing definition keeps today's skip-when-absent behaviour.
+    _add_skip_on_away,
+]
+
+
+async def _create_version_table(database: NestQuestDatabase) -> None:
+    """Create the version metadata table if it does not exist.
+
+    The table is created before any version check: it is the runner's
+    own bookkeeping, and creating it is idempotent.  The DDL enforces
+    the singleton-row invariant (``id`` fixed at 1) and a positive
+    integer version at the database level.
+    """
+    await database.execute(VERSION_TABLE_DDL)
+
+
+async def read_schema_version(database: NestQuestDatabase) -> int:
+    """Return the schema version recorded in the database.
+
+    Returns 0 when the version table or its row is missing — the
+    "fresh file" case.  A stored version higher than the runner knows
+    is surfaced as-is; the caller decides how to treat a future version.
+
+    Reading is deliberately passive: a missing table raises, it is not
+    swallowed into 0, because :func:`apply_migrations` always creates
+    the table before reading and a direct reader hitting "no such
+    table" is a caller bug worth surfacing, not a fresh file.
+    """
+    row = await database.fetch_one(
+        f"SELECT version FROM {VERSION_TABLE} LIMIT 1"
+    )
+    if row is None:
+        return 0
+    version = row[0]
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise RuntimeError(
+            f"Schema version metadata is not an integer: {version!r}"
+        )
+    if version < 1:
+        raise RuntimeError(
+            f"Schema version metadata is invalid (must be >= 1): {version!r}"
+        )
+    return version
+
+
+#: One asyncio.Lock per connection wrapper, created lazily and bound to
+#: the running loop, serializing whole apply_migrations runs so two
+#: concurrent callers on one connection queue instead of colliding on
+#: the wrapper's single-transaction rule.
+_MIGRATION_LOCKS: dict[int, asyncio.Lock] = {}
+
+
+def _migration_lock(database: NestQuestDatabase) -> asyncio.Lock:
+    """Return the migration lock bound to ``database``'s running loop."""
+    loop = asyncio.get_running_loop()
+    key = (id(database), id(loop))
+    lock = _MIGRATION_LOCKS.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _MIGRATION_LOCKS[key] = lock
+    return lock
+
+
+async def apply_migrations(
+    database: NestQuestDatabase,
+    migrations: Sequence[MigrationStep] = MIGRATIONS,
+) -> int:
+    """Bring the database schema up to the latest version.
+
+    Reads the current version, applies every pending migration in order
+    — each inside one transaction that also stamps the new version —
+    and returns the resulting version.  Applying zero pending
+    migrations (database already current) is a no-op that logs at debug
+    level and opens no write transaction.
+
+    The version is re-read inside each migration transaction before
+    deciding to apply it: the outer read is advisory only (loop bounds,
+    no-op fast path), and on one shared connection two interleaved
+    runners would otherwise both read the same version and both apply
+    a non-idempotent migration.  Under the transaction's lock the
+    second runner sees the first runner's stamp and skips.
+
+    Runners on one connection are serialized by an asyncio lock held
+    for the whole decide-and-apply span: NestQuestDatabase rejects a
+    second transaction while one is active (RuntimeError), so
+    concurrent callers must queue, and the lock makes that queueing
+    explicit.  The loser of the race re-reads the version once it
+    acquires the lock, sees the winner's stamp, and applies nothing.
+
+    Raises whatever the failing migration raised, with the database
+    rolled back to its prior version and prior rows untouched.
+    """
+    async with _migration_lock(database):
+        await _create_version_table(database)
+        current = await read_schema_version(database)
+        latest = len(migrations)
+
+        if current > latest:
+            raise RuntimeError(
+                f"Database schema version {current} is newer than this "
+                f"integration understands (latest known: {latest}); "
+                "downgrades are not supported"
+            )
+
+        if current == latest:
+            LOGGER.debug(
+                "NestQuest schema already at version %d; "
+                "no migrations to apply",
+                current,
+            )
+            return current
+
+        for target in range(current + 1, latest + 1):
+            applied = False
+            step = migrations[target - 1]
+            if callable(step):
+                # Callable migrations own their transaction: some steps
+                # (table rebuilds) must run connection pragmas such as
+                # ``foreign_keys = OFF`` BEFORE opening one, which the
+                # runner's uniform transaction cannot express, and they
+                # stamp inside their own transaction so a failure rolls
+                # the statements and the version stamp back together.
+                # The version is re-read here under the migration lock:
+                # runners on one connection are serialized by it, so
+                # the version cannot change between this read and the
+                # callable's commit.
+                in_tx_version = await read_schema_version(database)
+                if in_tx_version > latest:
+                    raise RuntimeError(
+                        f"Database schema version {in_tx_version} is newer "
+                        f"than this integration understands (latest known: "
+                        f"{latest}); downgrades are not supported"
+                    )
+                if in_tx_version < target:
+                    await step(database, target)
+                    applied = True
+            else:
+                async with database.transaction():
+                    # Re-read the version INSIDE the write transaction:
+                    # the outer read was advisory, and the wrapper
+                    # serializes individual statements, not the
+                    # read-decide-apply decision.  Under the
+                    # transaction's lock the version cannot change
+                    # between the read and the stamp, and the loser of
+                    # an interleaved race (a queued second caller
+                    # re-running apply_migrations after the winner
+                    # already migrated) re-reads here, sees the
+                    # winner's stamp, and skips instead of re-applying
+                    # a non-idempotent migration with a stale version.
+                    in_tx_version = await read_schema_version(database)
+                    if in_tx_version > latest:
+                        raise RuntimeError(
+                            f"Database schema version {in_tx_version} is "
+                            f"newer than this integration understands "
+                            f"(latest known: {latest}); downgrades are "
+                            f"not supported"
+                        )
+                    if in_tx_version < target:
+                        for sql in step:
+                            await database.execute(sql)
+                        await stamp_schema_version(database, target)
+                        applied = True
+                        applied_statements = len(step)
+            if applied:
+                LOGGER.info(
+                    "NestQuest schema migrated to version %d",
+                    target,
+                )
+
+        return latest

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/presence_management.py

@@ -0,0 +1,161 @@
+"""Business layer for presence writes (Feature 09, API admin plane).
+
+Sits between the write callers (the Feature 09 HA service handlers and
+the API admin plane's presence routes) and the typed presence DAOs plus
+the pure presence model: callers get the model validation, the upsert /
+create / delete operations and the regeneration side effect here, and
+never touch the DAO or SQL directly.  This is the ONE implementation of
+these business rules — every caller constructs the same
+:class:`~.presence.PresenceSchedule` / :class:`~.presence.PresenceOverride`
+models (whose constructors are total, so no re-validation happens in a
+handler) and gets the same post-write
+:func:`~.materialize.regenerate_for_child`, so a child's future quest
+instances track its changed presence no matter which plane issued the
+write.  Like the model it is Home-Assistant-free: ``today`` is a plain
+calendar date threaded through to the regeneration, defaulting to the
+host clock there.
+
+Upsert policy (Feature 05, unchanged): a child has AT MOST ONE presence
+schedule — setting again REPLACES the existing row rather than
+duplicating it.  Overrides are deletable by design (children are not —
+the children layer owns that guardrail).  Deleting a nonexistent
+override raises ValueError prefixed ``override_id:`` so a caller can
+distinguish "unknown id" from a rejected argument the same way the
+quest-definitions layer prefixes ``definition_id:``.
+"""
+from __future__ import annotations
+
+import datetime
+
+from .dao_presence import (
+    PresenceOverrideRecord,
+    PresenceOverridesDao,
+    PresenceSchedulesDao,
+)
+from .db import NestQuestDatabase
+from .materialize import regenerate_for_child
+from .presence import PresenceOverride, PresenceSchedule
+
+
+def _validate_override_id(value: object) -> int:
+    """Reject non-int override ids (bools would silently address id 1)."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"override_id must be an integer, got {value!r}")
+    return value
+
+
+async def set_presence_schedule(
+    database: NestQuestDatabase,
+    child_id: int,
+    cycle_length_weeks: int,
+    anchor_date: object,
+    pattern: dict[int, object],
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> PresenceSchedule:
+    """Set (upsert) a child's repeating presence schedule.
+
+    The :class:`~.presence.PresenceSchedule` model validates at
+    construction — cycle length 1..4, a strict calendar anchor date,
+    and a pattern covering week indices 0..n-1 with weekday sets — so
+    no invalid schedule reaches the DAO.  The encoded pattern is
+    UPSERTed by child (a second set REPLACES the child's existing
+    schedule; the schema's UNIQUE(child_id) makes duplication
+    unrepresentable), then :func:`~.materialize.regenerate_for_child`
+    re-materializes the child's future instances against the new
+    presence.  ``today``/``horizon_days`` thread through to that
+    regeneration; raising ValueError names what to fix (an unknown
+    child reads ``child N does not exist``).
+
+    Returns the STORED schedule decoded back through the model — the
+    round-trip proves the encoded pattern the database now holds is
+    exactly the one the caller asked for.
+    """
+    schedule = PresenceSchedule(
+        child_id, cycle_length_weeks, anchor_date, pattern
+    )
+    record = await PresenceSchedulesDao(database).upsert_by_child(
+        schedule.child_id,
+        schedule.cycle_length_weeks,
+        schedule.anchor_date.isoformat(),
+        schedule.encode(),
+    )
+    await regenerate_for_child(
+        database, schedule.child_id, today=today, horizon_days=horizon_days
+    )
+    return PresenceSchedule.decode(
+        record.child_id, record.anchor_date, record.pattern
+    )
+
+
+async def create_presence_override(
+    database: NestQuestDatabase,
+    child_id: int,
+    start_date: object,
+    end_date: object,
+    is_present: bool,
+    note: str | None = None,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> PresenceOverrideRecord:
+    """Create one date-range presence override and return it as stored.
+
+    The :class:`~.presence.PresenceOverride` model validates at
+    construction — strict calendar dates, ``end_date`` on or after
+    ``start_date``, a real ``is_present`` bool, a string-or-None note —
+    then the DAO insert applies the same-child no-overlap policy (a
+    conflicting range raises ValueError naming the existing override)
+    and :func:`~.materialize.regenerate_for_child` re-materializes the
+    child's future instances against the override's presence answer.
+    An unknown child reads ``child N does not exist``.
+
+    Returns the stored record WITH its ``id`` — the handle a later
+    :func:`delete_presence_override` takes.
+    """
+    override = PresenceOverride(
+        child_id, start_date, end_date, is_present, note=note
+    )
+    record = await PresenceOverridesDao(database).create(
+        override.child_id,
+        override.start_date.isoformat(),
+        override.end_date.isoformat(),
+        override.is_present,
+        note=override.note,
+    )
+    await regenerate_for_child(
+        database, override.child_id, today=today, horizon_days=horizon_days
+    )
+    return record
+
+
+async def delete_presence_override(
+    database: NestQuestDatabase,
+    override_id: int,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> PresenceOverrideRecord:
+    """Delete one presence override by id and return it as it was stored.
+
+    The override is looked up FIRST and an unknown id raises ValueError
+    prefixed ``override_id:`` (naming the id) BEFORE any delete, so a
+    mistyped id can never be silently swallowed by a no-op.  The
+    deletion is followed by :func:`~.materialize.regenerate_for_child`
+    for the override's own child — the id decides the child, never a
+    caller-supplied one.  ``today``/``horizon_days`` thread through to
+    that regeneration.
+    """
+    _validate_override_id(override_id)
+    dao = PresenceOverridesDao(database)
+    override = await dao.get(override_id)
+    if override is None:
+        raise ValueError(
+            f"override_id: presence override {override_id} does not exist"
+        )
+    await dao.delete(override_id)
+    await regenerate_for_child(
+        database, override.child_id, today=today, horizon_days=horizon_days
+    )
+    return override

custom_components/nestquest/core/quest_definitions.py

@@ -0,0 +1,640 @@
+"""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_skip_on_away(value: object) -> bool:
+    """Reject a non-bool ``skip_on_away`` before any write.
+
+    The DAO's ``int()`` would otherwise silently coerce strings and
+    numerics ("0", 1) into a state the caller never asked for.
+    """
+    if not isinstance(value, bool):
+        raise ValueError(f"skip_on_away must be a real bool, 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,
+    skip_on_away: bool = True,
+) -> 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")
+    skip_on_away_value = _validate_skip_on_away(skip_on_away)
+
+    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,
+            skip_on_away=skip_on_away_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,
+    skip_on_away: bool | None = None,
+    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.  A provided
+    ``skip_on_away`` (a real bool) replaces the stored flag; ``None``
+    leaves it unchanged.  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)
+
+    skip_on_away_value: bool | object = _UNSET
+    if skip_on_away is not None:
+        skip_on_away_value = _validate_skip_on_away(skip_on_away)
+
+    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,
+            skip_on_away=skip_on_away_value,
+        )
+    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_all_definitions(
+    database: NestQuestDatabase,
+) -> list[CreatedQuestDefinition]:
+    """Return EVERY definition, active AND inactive (rich view).
+
+    Mirrors :func:`list_active_definitions` without the activity
+    filter: ordered by rising definition id, each entry the same
+    :class:`CreatedQuestDefinition` snapshot, read by the DAO inside one
+    locked transaction.
+    """
+    dao = QuestDefinitionsDao(database)
+    snapshots = await dao.list_snapshots_all()
+    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/recurrence.py

@@ -39,11 +39,16 @@ reach storage):
 - ``start_date`` is a strict ISO date; ``end_date`` is optional and,
   when present, on or after ``start_date``.
 
-Month-end policy (documented for Feature 04): a MONTHLY_DAY rule for
-the 31st does NOT fire in a 30-day month, and a YEARLY rule for
-February 29th does NOT fire in a non-leap year — the engine skips
-instead of clamping to month end, because clamping silently moves
-"the 31st" to "the 30th" and double-fires tasks.
+Month-end policy (implemented in :func:`_occurs_monthly_day` and
+documented for Feature 04): in each interval-eligible month, a
+MONTHLY_DAY rule for a day that does not exist in that month — the
+31st in April, the 30th or 29th in February, February 29th in a
+non-leap year — fires on the LAST day of the month instead of being
+skipped.  A monthly chore still happens in every eligible month,
+pinned to the month's end when its nominal date is absent; exactly one
+day per eligible month matches the rule (nominal day when it exists,
+month end when it does not).  The interval anchors on nominal months
+elapsed from start_date's month, so clamping never shifts the cadence.
 """
 from __future__ import annotations
 
@@ -265,10 +270,9 @@ class ScheduleRule:
                                 "nth_weekday_weekday", "month")
         elif shape is RuleType.MONTHLY_WEEKDAY:
             forbidden_fields = ("weekday_set", "day_of_month", "month")
-        else:  # YEARLY
+        elif shape is RuleType.YEARLY:
             forbidden_fields = (
                 "weekday_set",
-                "day_of_month",
                 "nth_weekday",
                 "nth_weekday_weekday",
             )
@@ -311,6 +315,14 @@ class ScheduleRule:
                 raise RuleValidationError(
                     f"month must be 1..12, got {self.month!r}"
                 )
+            if self.day_of_month is not None and not (
+                _is_plain_int(self.day_of_month)
+                and 1 <= self.day_of_month <= 31
+            ):
+                raise RuleValidationError(
+                    f"day_of_month must be 1..31 for yearly rules, got "
+                    f"{self.day_of_month!r}"
+                )
 
     def to_dict(self) -> dict:
         """Return the lossless dict form (model-side storage shape).
@@ -418,6 +430,112 @@ def _within_window(rule: ScheduleRule, target: datetime.date) -> bool:
     return True
 
 
+def _month_end(year: int, month: int) -> int:
+    """The last calendar day of the given month (leap-aware)."""
+    if month == 12:
+        return 31
+    return (datetime.date(year, month + 1, 1)
+            - datetime.timedelta(days=1)).day
+
+
+def _occurs_monthly_day(rule: ScheduleRule, target: datetime.date) -> bool:
+    """MONTHLY_DAY evaluation with the documented month-end policy.
+
+    Policy: in each interval-eligible month, a rule for a day-of-month
+    that does not exist in that month (the 31st in April, the 30th in
+    February, the 29th of February in a non-leap year) fires on the
+    LAST day of that month instead of being skipped — the chore still
+    happens that month, pinned to the month's end when its nominal date
+    is absent.
+
+    The interval anchors on months ELAPSED from start_date's month: the
+    rule fires when the months between the anchor month and the target's
+    month form a multiple of the interval, keeping "every 2 months on
+    the 15th" aligned to the anchor month even when the firing lands on
+    a clamped month-end day.
+    """
+    anchor = _parse_date(rule.start_date)
+    months_elapsed = (
+        (target.year - anchor.year) * 12 + (target.month - anchor.month)
+    )
+    if months_elapsed % rule.interval != 0:
+        return False
+    month_end = _month_end(target.year, target.month)
+    return target.day == min(rule.day_of_month, month_end)
+
+
+def _nth_weekday_of_month(
+    year: int, month: int, weekday: int, nth: int
+) -> int | None:
+    """The day-of-month of the ``nth`` ``weekday``, or None when the
+    month has no such occurrence (``nth`` 5 beyond four occurrences).
+
+    Positive ``nth`` counts forward (1 = first); ``-1`` counts from the
+    end (last occurrence, whatever the total).  Pure calendar math.
+    """
+    if nth == -1:
+        last = datetime.date(year, month, _month_end(year, month))
+        back = (last.weekday() - weekday) % 7
+        return last.day - back
+    first = datetime.date(year, month, 1)
+    first_offset = (weekday - first.weekday()) % 7
+    day = 1 + first_offset + (nth - 1) * 7
+    if day > _month_end(year, month):
+        return None
+    return day
+
+
+def _occurs_monthly_weekday(
+    rule: ScheduleRule, target: datetime.date
+) -> bool:
+    """MONTHLY_WEEKDAY evaluation.
+
+    Fires when the target is the ``nth`` occurrence of
+    ``nth_weekday_weekday`` in its month (1..4 forward, -1 last).  A
+    month with fewer occurrences than ``nth`` (5 on a four-occurrence
+    month) does not fire — n 5 is accepted by the model but skips such
+    months, matching the done-condition.  The interval anchors on
+    nominal months elapsed from start_date's month.
+    """
+    anchor = _parse_date(rule.start_date)
+    months_elapsed = (
+        (target.year - anchor.year) * 12 + (target.month - anchor.month)
+    )
+    if months_elapsed % rule.interval != 0:
+        return False
+    if target.weekday() != rule.nth_weekday_weekday:
+        return False
+    nth_day = _nth_weekday_of_month(
+        target.year, target.month, rule.nth_weekday_weekday, rule.nth_weekday
+    )
+    return nth_day is not None and target.day == nth_day
+
+
+def _occurs_yearly(rule: ScheduleRule, target: datetime.date) -> bool:
+    """YEARLY evaluation with the documented leap-day clamp policy.
+
+    Policy: in each interval-eligible year, the rule fires on
+    ``day_of_month`` of ``month`` when that day exists.  A YEARLY rule
+    for February 29th fires on FEBRUARY 28TH in a non-leap year (the
+    same clamp-as-month-end policy as MONTHLY_DAY: the annual chore
+    still happens every year, pinned to February's end when its
+    nominal date is absent) rather than silently vanishing.  A YEARLY
+    rule with NO day_of_month fires on the first day of ``month``.
+    The interval anchors on years elapsed from start_date's year.
+    """
+    anchor = _parse_date(rule.start_date)
+    years_elapsed = target.year - anchor.year
+    if years_elapsed % rule.interval != 0:
+        return False
+    if target.month != rule.month:
+        return False
+    if rule.day_of_month is None:
+        # Day-less yearly rules fire on the first of the month.
+        return target.day == 1
+    month_end = _month_end(target.year, target.month)
+    return target.day == min(rule.day_of_month, month_end)
+
+
 def occurs_on(rule: ScheduleRule, target: datetime.date) -> bool:
     """Return True when ``rule`` fires on ``target``.
 
@@ -428,15 +546,37 @@ def occurs_on(rule: ScheduleRule, target: datetime.date) -> bool:
     # Dispatch FIRST: an unimplemented shape must raise loudly even for
     # dates outside the window, never silently evaluate to False.
     shape = rule.rule_type
-    if shape is not RuleType.DAILY:
+    if shape not in (
+        RuleType.DAILY, RuleType.WEEKLY, RuleType.CUSTOM_DAYS,
+        RuleType.MONTHLY_DAY, RuleType.MONTHLY_WEEKDAY, RuleType.YEARLY,
+    ):
         raise NotImplementedError(
             f"occurs_on for {shape} lands with its own engine task "
             "(Features 04 task sequence)"
         )
     if not _within_window(rule, target):
         return False
-    offset = (target - _parse_date(rule.start_date)).days
-    return offset % rule.interval == 0
+    if shape is RuleType.DAILY:
+        offset = (target - _parse_date(rule.start_date)).days
+        return offset % rule.interval == 0
+    if shape is RuleType.MONTHLY_DAY:
+        return _occurs_monthly_day(rule, target)
+    if shape is RuleType.MONTHLY_WEEKDAY:
+        return _occurs_monthly_weekday(rule, target)
+    if shape is RuleType.YEARLY:
+        return _occurs_yearly(rule, target)
+    # WEEKLY / CUSTOM_DAYS: whole-week anchoring from start_date, never
+    # ISO week numbers (Feature 04/05 guardrail: 53-week years flip ISO
+    # parity on January 1st; anchor arithmetic does not).
+    anchor = _parse_date(rule.start_date)
+    if shape is RuleType.CUSTOM_DAYS:
+        interval = 1
+    else:
+        interval = rule.interval
+    week_offset = (target - anchor).days // 7
+    if week_offset % interval != 0:
+        return False
+    return target.weekday() in rule.weekday_set
 
 
 def occurrences_between(
@@ -448,7 +588,10 @@ def occurrences_between(
     inverted bounds; a window entirely outside [rule.start_date,
     rule.end_date] yields an empty list.
     """
-    if rule.rule_type is not RuleType.DAILY:
+    if rule.rule_type not in (
+        RuleType.DAILY, RuleType.WEEKLY, RuleType.CUSTOM_DAYS,
+        RuleType.MONTHLY_DAY, RuleType.MONTHLY_WEEKDAY, RuleType.YEARLY,
+    ):
         raise NotImplementedError(
             f"occurrences_between for {rule.rule_type} lands with its own "
             "engine task (Features 04 task sequence)"

custom_components/nestquest/core/schema.py

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

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/settings_store.py

@@ -0,0 +1,210 @@
+"""Durable settings store for the NestQuest API service.
+
+The API service has NO Home Assistant config entry, so it cannot build
+:class:`~.settings.NestQuestSettings` from ``entry.options`` the way the
+integration does.  This module gives the API its own durable settings
+source: a JSON document kept in the EXISTING ``nestquest_meta_state``
+key/value table (:class:`~.dao_meta.MetaStateDao`) under the well-known
+key :data:`SETTINGS_META_KEY` — no schema change, no new table —
+validated through the SAME field table the settings object is built
+from (:data:`~.settings._FIELDS`, the table driving
+``from_options``/``from_options_resilient``).  No validation rule is
+re-implemented here.
+
+OWNERSHIP: the API now owns settings in the database.  The
+integration's Home-Assistant config-entry options remain a temporary,
+SEPARATE source until Feature 18 converts the integration into a thin
+API client; the two are deliberately NOT unified here, and neither
+side reads the other's values.
+
+STORED SERIALIZATION — the document at ``SETTINGS_META_KEY`` is a JSON
+object holding exactly the TEN settings fields, keyed by field name
+(which equals the ``CONF_*`` option key for every field), complete
+after the first update:
+
+- ``horizon_days`` — int >= 1,
+- ``day_rollover_time``, ``morning_summary_time``,
+  ``afternoon_reminder_time``, ``end_of_day_report_time`` — strict
+  24-hour ``HH:MM`` strings,
+- ``notify_target`` — a string (a padded value is stripped by the
+  core's normalizer),
+- ``morning_summary_enabled``, ``afternoon_reminder_enabled``,
+  ``end_of_day_report_enabled``, ``celebration_enabled`` — real
+  booleans.
+
+Only values whose core validators ACCEPTED are ever written, so a
+stored document always round-trips through the core's option builders.
+An absent key (a fresh database) resolves to the all-defaults
+settings, and a corrupt document degrades to defaults or per-field
+defaults rather than crashing the service (see :func:`load_settings`).
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .const import LOGGER
+from .dao_meta import MetaStateDao
+from .db import NestQuestDatabase
+from .settings import NestQuestSettings, _FIELDS
+
+#: The well-known ``nestquest_meta_state`` key holding the settings
+#: document.  One key, one JSON object — the same table the missed
+#: sweep's watermark already uses, so no migration is needed.
+SETTINGS_META_KEY = "settings"
+
+#: The per-field resolution table keyed by field name: each row is the
+#: ``(default, validator)`` pair the settings module's ``_FIELDS`` table
+#: carries for that field.  ``update_settings`` resolves each PROVIDED
+#: field through its row's validator — the SAME core validators
+#: ``from_options`` applies — and never re-implements one here.
+#: (Field names equal the ``CONF_*`` option keys, so one dict serves
+#: both the API's field names and the stored document's keys.)
+_RESOLUTIONS: dict[str, tuple[Any, Any]] = {
+    key: (default, validator) for _field, key, default, validator in _FIELDS
+}
+
+#: The known field names, in the settings module's field order — the
+#: allowed keys of an update body and the stored document's key set.
+_FIELD_NAMES: tuple[str, ...] = tuple(
+    key for _field, key, _default, _validator in _FIELDS
+)
+
+#: One asyncio.Lock per (connection wrapper, running loop), the missed
+#: sweep's pattern: the whole stored-document read → merge → write span
+#: is one critical section, so two concurrent updates queue instead of
+#: one losing the other's change — the loser re-reads the document
+#: INSIDE the lock and merges onto the winner's settings.
+_SETTINGS_LOCKS: dict[tuple[int, int], asyncio.Lock] = {}
+
+
+def _settings_lock(database: NestQuestDatabase) -> asyncio.Lock:
+    """Return the settings lock bound to ``database``'s running loop."""
+    loop = asyncio.get_running_loop()
+    key = (id(database), id(loop))
+    lock = _SETTINGS_LOCKS.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _SETTINGS_LOCKS[key] = lock
+    return lock
+
+
+async def _load_document(database: NestQuestDatabase) -> dict[str, Any]:
+    """Read and decode the stored settings document (empty when unusable).
+
+    An absent key — a fresh database that never updated settings — and
+    an unparseable value (invalid JSON, or JSON that is not an object)
+    return an empty mapping, which the option builders resolve to the
+    all-defaults settings; the corrupt cases log a warning first.  A
+    parseable object is returned as stored (its per-field validity is
+    the builder's concern, not this reader's).
+    """
+    raw = await MetaStateDao(database).get(SETTINGS_META_KEY)
+    if raw is None:
+        return {}
+    try:
+        document = json.loads(raw)
+    except ValueError:
+        LOGGER.warning(
+            "NestQuest stored settings (meta_state key %r) are not valid "
+            "JSON; falling back to the default settings",
+            SETTINGS_META_KEY,
+        )
+        return {}
+    if not isinstance(document, dict):
+        LOGGER.warning(
+            "NestQuest stored settings (meta_state key %r) are not a JSON "
+            "object; falling back to the default settings",
+            SETTINGS_META_KEY,
+        )
+        return {}
+    return document
+
+
+def _named(field: str, error: ValueError) -> str:
+    """Return a field-named message for a rejected validator value.
+
+    The horizon, time and notify-target validators already name their
+    field in the message; the boolean validator's message is generic
+    (``expected a boolean, got ...``), so it gets the field prefixed.
+    Every rejected update's error therefore names its field either way.
+    """
+    message = str(error)
+    if message.startswith(f"{field} "):
+        return message
+    return f"{field}: {message}"
+
+
+async def load_settings(database: NestQuestDatabase) -> NestQuestSettings:
+    """Return the current effective settings stored for ``database``.
+
+    Reads :data:`SETTINGS_META_KEY` and resolves the stored document
+    through the core settings validators, with each absent field
+    falling back to its default.  An absent key and an unparseable
+    document fall back to the all-defaults settings (via
+    :func:`_load_document`), and a parseable document with a single
+    invalid FIELD falls back PER FIELD — through
+    :meth:`NestQuestSettings.from_options_resilient`, the core's own
+    resilient builder — so a corrupt sibling never resets the stored
+    values around it.  This never raises: the service must keep
+    serving reads even over a corrupt store.
+    """
+    document = await _load_document(database)
+    return NestQuestSettings.from_options_resilient(document)
+
+
+async def update_settings(
+    database: NestQuestDatabase, changes: Mapping[str, Any]
+) -> NestQuestSettings:
+    """Validate ``changes`` and persist them as the effective settings.
+
+    ``changes`` maps settings field names to new values.  EVERY name is
+    checked against the known field table BEFORE anything is validated
+    or written: an unknown name raises a ``ValueError`` naming it (and
+    the known names), leaving the stored settings untouched.  Each
+    PROVIDED field is then resolved from_options-style — its
+    :data:`~.settings._FIELDS` validator applied, with a JSON ``null``
+    mapping to the field's default (the settings module's uniform
+    None-as-absent rule) — and an invalid value raises a ``ValueError``
+    naming the field, also BEFORE anything is written, so a rejected
+    update can never leave a half-applied document behind.
+
+    The validated changes are merged onto the current effective
+    settings and the merged (complete, ten-field) document is persisted
+    in one atomic upsert; the updated settings are returned.  The whole
+    read → merge → write span runs inside the per-database settings
+    lock, so concurrent updates queue instead of interleaving.
+    """
+    if not isinstance(changes, Mapping):
+        raise ValueError(
+            "settings changes must be a JSON object mapping field names "
+            "to values"
+        )
+    unknown = sorted(
+        str(name) for name in changes if name not in _RESOLUTIONS
+    )
+    if unknown:
+        listed = ", ".join(repr(name) for name in unknown)
+        known = ", ".join(_FIELD_NAMES)
+        raise ValueError(
+            f"unknown settings field(s): {listed}; known fields: {known}"
+        )
+    async with _settings_lock(database):
+        current = await load_settings(database)
+        document: dict[str, Any] = {
+            field: getattr(current, field) for field in _FIELD_NAMES
+        }
+        for name, raw_value in changes.items():
+            default, validator = _RESOLUTIONS[name]
+            try:
+                document[name] = validator(
+                    default if raw_value is None else raw_value
+                )
+            except ValueError as error:
+                raise ValueError(_named(name, error)) from error
+        await MetaStateDao(database).set(
+            SETTINGS_META_KEY, json.dumps(document, sort_keys=True)
+        )
+    return NestQuestSettings(**document)

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/core/store.py

@@ -0,0 +1,30 @@
+"""SQLite storage path resolution for the NestQuest storage layer.
+
+Home-Assistant-free: callers resolve the database file location from
+their own config (HA resolves it from ``hass.config.path``) and pass
+the full path here; this module ensures the parent directory exists
+off-thread via :func:`asyncio.to_thread` and returns the absolute path.
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+
+def _ensure_dir(path: Path) -> None:
+    """Create the given directory and any missing parents."""
+    path.mkdir(parents=True, exist_ok=True)
+
+
+async def async_get_db_path(db_path: Path | str) -> Path:
+    """Return the absolute path to the NestQuest SQLite database file.
+
+    ``db_path`` is the full path to the database file (the integration
+    resolves it from ``hass.config.path(SQLITE_DB_FILENAME)``); the
+    parent directory is created off the event loop via
+    :func:`asyncio.to_thread` so this module never blocks and never
+    imports Home Assistant.
+    """
+    path = Path(db_path).absolute()
+    await asyncio.to_thread(_ensure_dir, path.parent)
+    return path

custom_components/nestquest/core/sweep.py

@@ -0,0 +1,170 @@
+"""The nightly missed-quest sweep, Home-Assistant-free (Feature 11).
+
+This is the HA-free heart of the missed sweep, shared by the two
+planes: the Home Assistant integration's :mod:`~..sweep` shim (which
+fires the returned events on ``hass.bus``) and the API service (which
+publishes them on the SSE stream and can also trigger the run on
+demand).  It owns the ONE sweep policy:
+
+At the configured day-rollover time (or on an explicit trigger) this
+job finds every instance whose ``due_date`` is before the
+household-local date, that has NO completion event, and that falls
+after the persisted sweep watermark — and RETURNS one
+``nestquest_quest_missed`` event per instance with the documented
+payload.  Like every core module, it never touches the Home Assistant
+event bus and never mutates an instance: ``missed`` is derived state,
+never an event_type (Feature 08's contract), so the sweep is read-only
+over the domain tables.
+
+Idempotency is the watermark: after a run, ``nestquest_meta_state``
+records the household-local date the sweep ran, and the next run only
+sweeps instances due in ``[watermark, today)``.  A second run the same
+night therefore fires nothing new, and a run after days of downtime
+sweeps exactly the accumulated window once — no per-instance journal,
+no re-announcing old misses.  An instance swept as missed that is
+later completed simply gains its completion event; history keeps both
+rows (append-only), and the sweep's later runs skip it via the
+no-completion-event rule.
+
+The whole watermark read → query → build span runs inside the
+per-database sweep lock (one lock per connection wrapper and running
+loop, the settings store's pattern): an overlapping startup sweep and
+a rollover sweep of the SAME process queue instead of interleaving.
+The announce decision itself is the DATABASE-level claim
+(:meth:`MetaStateDao.claim`), so two PROCESSES sharing one SQLite file
+(the integration's rollover sweep and the API service's scheduler)
+cannot both announce the same missed batch either: both may read the
+old watermark and build the events, but the single conditional upsert
+lets exactly one of them win the claim — the loser returns [] and
+announces nothing.
+
+The caller supplies ``today`` as a plain :class:`datetime.date`: the
+household-local calendar date, read from ``hass.config.time_zone`` by
+the integration or from the API host's local clock by the API.  This
+module never reads a timezone database or config of its own.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import logging
+
+from .const import EVENT_QUEST_MISSED
+from .dao_meta import MetaStateDao
+from .dao_instances import QuestInstancesDao
+from .db import NestQuestDatabase
+# Intentional intra-package reuse of the shared payload builder: the
+# missed event's payload is the documented §3 instance payload, and
+# building it through the ONE builder keeps this sweep's payloads from
+# drifting from the completion/uncompleted builders' shape.
+from .events import _instance_payload
+
+LOGGER = logging.getLogger(__name__)
+
+#: meta_state key holding the household-local date the sweep last ran.
+SWEEP_WATERMARK_KEY = "missed_sweep_last_run_date"
+
+#: One asyncio.Lock per (connection wrapper, running loop), mirroring
+#: the settings store's pattern: the watermark read → query → build
+#: span is one critical section, so an overlapping startup sweep and
+#: rollover sweep of the SAME process queue instead of interleaving.
+#: Same-process callers are fully serialised by it; the cross-process
+#: case is closed by the database-level claim, not by this lock.
+_SWEEP_LOCKS: dict[tuple[int, int], asyncio.Lock] = {}
+
+
+def _sweep_lock(database: NestQuestDatabase) -> asyncio.Lock:
+    """Return the sweep lock bound to ``database``'s running loop."""
+    loop = asyncio.get_running_loop()
+    key = (id(database), id(loop))
+    lock = _SWEEP_LOCKS.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _SWEEP_LOCKS[key] = lock
+    return lock
+
+
+#: 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"
+
+
+async def run_missed_sweep(
+    database: NestQuestDatabase,
+    *,
+    today: datetime.date,
+) -> list[tuple[str, dict]]:
+    """Build one missed event per unswept past-due open instance.
+
+    ``today`` is the household-local calendar date the sweep runs for
+    (the caller owns the clock: the integration reads it from
+    ``hass.config.time_zone``, the API from its host's local time).
+    Returns the ``(event_type, payload)`` tuples to announce, EMPTY
+    when the watermark already covers ``today`` (a same-night rerun) —
+    the caller decides how to publish them and announces nothing on
+    its own.
+
+    The watermark read → query → build span runs inside the
+    per-database sweep lock, so overlapping callers of ONE process
+    queue instead of interleaving.  The announce decision is the
+    DATABASE-level claim (:meth:`MetaStateDao.claim` — a single
+    conditional upsert on the watermark, atomic across processes):
+    every caller builds the events optimistically, then only the
+    caller whose claim actually advanced the watermark returns them;
+    a loser (another process already announced for ``today``) returns
+    [] and announces nothing twice.  Every event in one run shares one
+    ``occurred_at`` stamp (one run, one announcement moment), and the
+    payload comes from the shared
+    :func:`~.events._instance_payload` builder so the shape can never
+    drift from the documented §3 contract.
+
+    Failure ordering: the watermark is advanced ONLY by the claim,
+    AFTER the events are fully built — a failure before the claim
+    leaves the watermark unadvanced, so a later run re-sweeps the same
+    window and nothing is lost.
+    """
+    today_iso = today.isoformat()
+    dao = MetaStateDao(database)
+    async with _sweep_lock(database):
+        watermark = await dao.get(SWEEP_WATERMARK_KEY)
+        if watermark == today_iso:
+            LOGGER.debug(
+                "NestQuest missed sweep already ran for %s", today_iso
+            )
+            return []
+
+        instances_dao = QuestInstancesDao(database)
+        rows = await instances_dao.list_missed_unswept(today_iso, watermark)
+        now_stamp = datetime.datetime.now(datetime.timezone.utc).strftime(
+            _UTC_TIMESTAMP_FORMAT
+        )
+        events: list[tuple[str, dict]] = []
+        for instance in rows:
+            events.append(
+                (
+                    EVENT_QUEST_MISSED,
+                    await _instance_payload(
+                        database, instance.id, now_stamp
+                    ),
+                )
+            )
+        # The database-level claim gates the announcement: only the
+        # caller that actually advanced the watermark may publish the
+        # built events, so two processes racing one SQLite file cannot
+        # both announce the same missed batch.  A same-value loser's
+        # claim matches zero rows and this run announces nothing.
+        claimed = await dao.claim(SWEEP_WATERMARK_KEY, today_iso)
+        if not claimed:
+            LOGGER.info(
+                "NestQuest missed sweep for %s lost the watermark claim; "
+                "announcing nothing",
+                today_iso,
+            )
+            return []
+    LOGGER.info(
+        "NestQuest missed sweep for %s built %d event(s)",
+        today_iso,
+        len(events),
+    )
+    return events
+

custom_components/nestquest/dashboard.py

@@ -0,0 +1,215 @@
+"""Zero-config panel dashboard registration for NestQuest (Feature 20).
+
+On setup the integration registers ONE storage-mode Lovelace dashboard
+whose CONFIG uses the bundle's ``custom:nestquest-party`` strategy (see
+``frontend/src/strategy.ts``): the views themselves are GENERATED at
+render time from the household roster, so the stored dashboard config
+carries nothing but the strategy reference.
+
+Registration mirrors the REAL two-step sequence the lovelace
+integration itself uses when it creates the onboarding map dashboard
+(``homeassistant/components/lovelace/__init__.py``,
+``_create_map_dashboard``):
+
+1. create the dashboard METADATA through the ``DashboardsCollection``
+   (``hass.data["lovelace"]["dashboards_collection"]``) — url_path,
+   title, icon, sidebar visibility.  The strategy reference is NOT part
+   of the create payload: the collection's create schema allows only
+   the metadata fields, so a ``strategy`` key there fails the whole
+   create (this was the silent no-op the first implementation shipped).
+2. save the dashboard CONFIG — ``{"strategy": ...}`` — through the
+   per-url_path CONTENT manager that the collection's change listener
+   registers under ``hass.data["lovelace"]["dashboards"][url_path]``
+   (a ``LovelaceStorage``), exactly the second step HA performs.
+
+Registration is IDEMPOTENT — a dashboard already under the stable
+``url_path`` (ours or a user's) skips BOTH steps and its stored config
+is never overwritten — and the Lovelace surfaces being unavailable
+(YAML mode, lovelace not loaded) is a logged warning, never a setup
+failure.
+"""
+from __future__ import annotations
+
+import asyncio
+
+from homeassistant.core import HomeAssistant
+
+from .const import (
+    DASHBOARD_ICON,
+    DASHBOARD_STRATEGY_TYPE,
+    DASHBOARD_TITLE,
+    DASHBOARD_URL_PATH,
+    LOGGER,
+)
+
+_LOGGER = LOGGER
+
+# Single-flight guard for the check-then-create below: HA can set up
+# several config entries CONCURRENTLY, and two overlapping setups would
+# both pass the exists-check and race on the url_path create.  The lock
+# is per hass instance (kept as an attribute on the hass object, since
+# hass.data is the integrations' shared registry the unload path
+# empties) rather than one module-level asyncio.Lock — a bare
+# module-level lock binds to whichever event loop first awaits it and
+# raises RuntimeError on any other loop, while the race it must prevent
+# only exists between setups running on the SAME hass anyway.
+_REGISTRATION_LOCK_ATTR = "_nestquest_dashboard_registration_lock"
+
+
+def _registration_lock(hass: HomeAssistant) -> asyncio.Lock:
+    """Return the per-hass registration lock, creating it on first use."""
+    lock = getattr(hass, _REGISTRATION_LOCK_ATTR, None)
+    if lock is None:
+        lock = asyncio.Lock()
+        setattr(hass, _REGISTRATION_LOCK_ATTR, lock)
+    return lock
+
+
+def _lovelace_data(hass: HomeAssistant) -> dict | None:
+    """Return ``hass.data["lovelace"]`` when it is the real dict shape.
+
+    The lovelace integration stores a plain DICT of surfaces (``mode``,
+    ``dashboards``, ``dashboards_collection``, ``resources``,
+    ``yaml_dashboards``) under the ``lovelace`` key; anything else
+    (missing key, unexpected object) means the surfaces below cannot be
+    reached and registration must warn and continue.
+    """
+    lovelace_data = hass.data.get("lovelace")
+    if not isinstance(lovelace_data, dict):
+        return None
+    return lovelace_data
+
+
+def _dashboards_collection(hass: HomeAssistant):
+    """Return the Lovelace dashboards METADATA collection, or None.
+
+    The collection lives at ``hass.data["lovelace"]
+    ["dashboards_collection"]`` — NOT under ``["dashboards"]``, which
+    maps url_path to the per-dashboard CONTENT managers
+    (``LovelaceStorage``/``LovelaceYAML``).  A missing key (lovelace
+    not loaded) and a missing/None entry (YAML mode never sets the
+    collection) both mean "cannot create storage dashboards here" —
+    callers log and continue.  The presence of the surface is verified
+    by capability (``async_create_item`` callable), not by type, so no
+    lovelace import is needed.
+    """
+    lovelace_data = _lovelace_data(hass)
+    if lovelace_data is None:
+        return None
+    collection = lovelace_data.get("dashboards_collection")
+    if collection is None or not callable(
+        getattr(collection, "async_create_item", None)
+    ):
+        return None
+    return collection
+
+
+def _dashboard_store(hass: HomeAssistant, url_path: str):
+    """Return a url_path's dashboard CONTENT manager, or None.
+
+    After a metadata create, the collection's change listener registers
+    a ``LovelaceStorage`` for the new dashboard under
+    ``hass.data["lovelace"]["dashboards"][url_path]``; the dashboard
+    CONFIG (the strategy reference) is saved through THAT manager —
+    the second step of HA's own dashboard creation.
+    """
+    lovelace_data = _lovelace_data(hass)
+    if lovelace_data is None:
+        return None
+    dashboards = lovelace_data.get("dashboards")
+    if not isinstance(dashboards, dict):
+        return None
+    store = dashboards.get(url_path)
+    if store is None or not callable(getattr(store, "async_save", None)):
+        return None
+    return store
+
+
+def _item_url_path(item) -> str | None:
+    """Read a dashboard item's ``url_path`` through either access shape.
+
+    The collection hands back storage items as dicts while builtin
+    dashboards come back as config objects; the url_path is reachable
+    through ``item["url_path"]`` or ``item.url_path`` respectively.
+    """
+    url_path = getattr(item, "url_path", None)
+    if isinstance(url_path, str):
+        return url_path
+    get_url_path = getattr(item, "get", None)
+    if callable(get_url_path):
+        value = get_url_path("url_path")
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def _existing_dashboard(items) -> bool:
+    """Whether a dashboard under the stable url_path already exists."""
+    return any(_item_url_path(item) == DASHBOARD_URL_PATH for item in items)
+
+
+async def async_register_dashboard(hass: HomeAssistant) -> bool:
+    """Register the NestQuest panel dashboard exactly once.
+
+    Returns True when a dashboard under the stable ``url_path`` exists
+    after the call (pre-existing or created here), False when the
+    Lovelace surfaces were unavailable or refused.  A dashboard already
+    registered under the stable ``url_path`` — whether ours from a
+    previous setup or a user's own — skips BOTH steps and is left
+    COMPLETELY alone: its stored config is never overwritten, it is
+    never deleted, never a duplicate.  The strategy config is saved
+    ONLY for the dashboard created in THIS call, whose fresh content
+    store is empty, so the save cannot clobber anything.
+    """
+    collection = _dashboards_collection(hass)
+    if collection is None:
+        _LOGGER.warning(
+            "Lovelace dashboards collection unavailable; the NestQuest "
+            "panel dashboard was not registered. Enable the Lovelace "
+            "integration in storage mode or create a dashboard with "
+            "strategy %s manually.",
+            DASHBOARD_STRATEGY_TYPE,
+        )
+        return False
+    try:
+        # Single-flight: two concurrent entry setups must not both pass
+        # the exists-check and race on the url_path create.
+        async with _registration_lock(hass):
+            # async_items() is a SYNC @callback on the real collection
+            # (helpers/collection.py ObservableCollection) — not awaited.
+            if _existing_dashboard(collection.async_items()):
+                return True
+            await collection.async_create_item(
+                {
+                    "url_path": DASHBOARD_URL_PATH,
+                    "title": DASHBOARD_TITLE,
+                    "icon": DASHBOARD_ICON,
+                    "show_in_sidebar": True,
+                    "allow_single_word": True,
+                }
+            )
+            # Step two (mirroring HA's _create_map_dashboard): the
+            # strategy CONFIG goes through the fresh dashboard's
+            # content manager, not through the metadata collection.
+            store = _dashboard_store(hass, DASHBOARD_URL_PATH)
+            if store is None:
+                _LOGGER.warning(
+                    "The NestQuest panel dashboard was registered but its "
+                    "Lovelace content manager never appeared; add the "
+                    "strategy %s to the dashboard manually.",
+                    DASHBOARD_STRATEGY_TYPE,
+                )
+                return False
+            await store.async_save(
+                {"strategy": {"type": DASHBOARD_STRATEGY_TYPE}}
+            )
+    except Exception:
+        _LOGGER.warning(
+            "Registering the NestQuest panel dashboard in the Lovelace "
+            "dashboards collection failed; set it up manually with "
+            "strategy %s.",
+            DASHBOARD_STRATEGY_TYPE,
+            exc_info=True,
+        )
+        return False
+    return True

custom_components/nestquest/frontend.py

@@ -0,0 +1,35 @@
+"""Lovelace card bundle registration for NestQuest."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from homeassistant.components.frontend import add_extra_js_url
+from homeassistant.components.http import StaticPathConfig
+from homeassistant.core import HomeAssistant
+
+WWW_DIR = Path(__file__).parent / "www"
+FRONTEND_URL_BASE = "/nestquest-static"
+BUNDLE_FILENAME = "nestquest-cards.js"
+BUNDLE_URL = f"{FRONTEND_URL_BASE}/{BUNDLE_FILENAME}"
+_REGISTERED_ATTR = "_nestquest_frontend_registered"
+
+
+async def async_register_frontend(hass: HomeAssistant) -> None:
+    """Serve the card bundle and inject it into every Lovelace page.
+
+    Idempotent across config entries: static paths and extra JS URLs are
+    process-global, so a second entry must not register them again.
+    """
+    if getattr(hass, _REGISTERED_ATTR, False):
+        return
+    await hass.http.async_register_static_paths(
+        [
+            StaticPathConfig(
+                FRONTEND_URL_BASE,
+                str(WWW_DIR),
+                cache_headers=False,
+            )
+        ]
+    )
+    add_extra_js_url(hass, BUNDLE_URL)
+    setattr(hass, _REGISTERED_ATTR, True)

custom_components/nestquest/manifest.json

@@ -1,12 +1,19 @@
 {
   "domain": "nestquest",
   "name": "NestQuest",
-  "codeowners": ["@overseer"],
+  "codeowners": [
+    "@overseer"
+  ],
   "config_flow": true,
-  "documentation": "https://code.cubecraftlabs.com/Maniacs_Mansion/NestQuest",
+  "dependencies": [
+    "frontend",
+    "http",
+    "lovelace"
+  ],
+  "documentation": "https://github.com/Maniacs-Mansion/NestQuest",
   "integration_type": "hub",
   "iot_class": "local_polling",
-  "issue_tracker": "https://code.cubecraftlabs.com/Maniacs_Mansion/NestQuest/issues",
+  "issue_tracker": "https://github.com/Maniacs-Mansion/NestQuest/issues",
   "requirements": [],
-  "version": "0.1.0"
+  "version": "0.6.0"
 }

custom_components/nestquest/options_flow.py

@@ -1,7 +1,17 @@
-"""Options flow for NestQuest post-setup settings."""
+"""Options flow for NestQuest post-setup settings.
+
+Since the DB removal (Feature 18) the integration is a thin client of
+the NestQuest API service: the settings that only served the local
+database (the generation horizon, the day rollover, the notification
+defaults, the admin allowlist) are gone — the API service owns those in
+its own settings store, and the automations take their behaviour from
+blueprint inputs.  What remains is what the CLIENT itself consumes: the
+panel-plane API connection (base URL + token), the shared coordinator's
+refresh interval, the last-good staleness threshold, and the
+panel-facing idle timeout.
+"""
 from __future__ import annotations
 
-import re
 from typing import Any
 
 import voluptuous as vol
@@ -9,41 +19,37 @@ from homeassistant import config_entries
 from homeassistant.data_entry_flow import FlowResult
 
 from .const import (
-    CONF_DAY_ROLLOVER_TIME,
-    CONF_HORIZON_DAYS,
+    CONF_API_BASE_URL,
     CONF_PANEL_IDLE_TIMEOUT,
-    DEFAULT_DAY_ROLLOVER_TIME,
-    DEFAULT_HORIZON_DAYS,
+    CONF_PANEL_TOKEN,
+    CONF_SNAPSHOT_STALENESS,
+    CONF_UPDATE_INTERVAL,
+    DEFAULT_API_BASE_URL,
     DEFAULT_PANEL_IDLE_TIMEOUT,
+    DEFAULT_PANEL_TOKEN,
+    DEFAULT_SNAPSHOT_STALENESS,
+    DEFAULT_UPDATE_INTERVAL,
+    MIN_UPDATE_INTERVAL,
 )
+from .api_client import is_valid_base_url
 
-MIN_HORIZON_DAYS = 1
 MIN_PANEL_IDLE_TIMEOUT = 30
 
-_TIME_PATTERN = re.compile(r"(?:[01]\d|2[0-3]):[0-5]\d")
 
+def _async_validate(
+    user_input: dict[str, Any],
+    current: dict[str, Any] | None = None,
+) -> dict[str, str]:
+    """Validate user input and return field-level errors instead of raising.
 
-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
-
-
-def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:
-    """Validate user input and return field-level errors instead of raising."""
+    ``current`` carries the stored values (entry options → entry data →
+    defaults) so a raw submit that sets one field but omits a sibling it
+    is validated against (the staleness threshold vs. the update
+    interval) can still check the effective pair; raw submits omitting
+    BOTH keys keep their stored values untouched.
+    """
     errors: dict[str, str] = {}
 
-    horizon_days = user_input.get(CONF_HORIZON_DAYS)
-    if (
-        isinstance(horizon_days, bool)
-        or not isinstance(horizon_days, int)
-        or horizon_days < MIN_HORIZON_DAYS
-    ):
-        errors[CONF_HORIZON_DAYS] = "invalid"
-
-    day_rollover_time = user_input.get(CONF_DAY_ROLLOVER_TIME)
-    if not isinstance(day_rollover_time, str) or not _parse_time(day_rollover_time):
-        errors[CONF_DAY_ROLLOVER_TIME] = "invalid_time"
-
     panel_idle_timeout = user_input.get(CONF_PANEL_IDLE_TIMEOUT)
     if (
         isinstance(panel_idle_timeout, bool)
@@ -52,22 +58,101 @@ def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:
     ):
         errors[CONF_PANEL_IDLE_TIMEOUT] = "invalid"
 
+    # The coordinator refresh interval (Feature 10) is OPTIONAL in raw
+    # submits: a missing key keeps the current value, so pre-Feature-10
+    # form payloads (and API callers) are unaffected.  Schema-validated
+    # submits always carry it.
+    update_interval = user_input.get(CONF_UPDATE_INTERVAL)
+    if update_interval is not None and (
+        isinstance(update_interval, bool)
+        or not isinstance(update_interval, int)
+        or update_interval < MIN_UPDATE_INTERVAL
+    ):
+        errors[CONF_UPDATE_INTERVAL] = "invalid"
+
+    # The last-good staleness threshold (Feature 18) is OPTIONAL in raw
+    # submits the same way: a missing key keeps the current value.  It
+    # must be a positive int, and at least the EFFECTIVE update interval
+    # (the one this submit carries, else the stored or default one) — a
+    # threshold shorter than the poll cadence could never serve even one
+    # cached snapshot.
+    staleness = user_input.get(CONF_SNAPSHOT_STALENESS)
+    if staleness is not None and (
+        isinstance(staleness, bool)
+        or not isinstance(staleness, int)
+        or staleness < 1
+    ):
+        errors[CONF_SNAPSHOT_STALENESS] = "invalid"
+    elif staleness is not None and not errors.get(CONF_UPDATE_INTERVAL):
+        stored_interval = (current or {}).get(CONF_UPDATE_INTERVAL)
+        effective_interval = update_interval
+        if effective_interval is None and (
+            isinstance(stored_interval, int)
+            and not isinstance(stored_interval, bool)
+            and stored_interval >= MIN_UPDATE_INTERVAL
+        ):
+            effective_interval = stored_interval
+        if effective_interval is None:
+            effective_interval = DEFAULT_UPDATE_INTERVAL
+        if staleness < effective_interval:
+            errors[CONF_SNAPSHOT_STALENESS] = "invalid_staleness"
+
+    # The panel-plane API connection (Feature 18) is OPTIONAL in raw
+    # submits the same way: a missing key keeps the current value.  The
+    # base URL must be a full http(s) URL with a host — the same check
+    # the client's constructor enforces, so a malformed URL fails at
+    # the form, not at the first request.  The token may be EMPTY (the
+    # API connection is simply not configured yet) but a non-empty one
+    # must be pasted unpadded: a padded or whitespace-only value is a
+    # clipboard mistake that would fail the token check at request
+    # time.
+    api_base_url = user_input.get(CONF_API_BASE_URL)
+    if api_base_url is not None and not is_valid_base_url(api_base_url):
+        errors[CONF_API_BASE_URL] = "invalid_url"
+    panel_token = user_input.get(CONF_PANEL_TOKEN)
+    if panel_token is not None and (
+        not isinstance(panel_token, str)
+        or panel_token != panel_token.strip()
+    ):
+        errors[CONF_PANEL_TOKEN] = "invalid"
+
     return errors
 
 
 def _build_schema(current: dict[str, Any]) -> vol.Schema:
-    """Build the form schema, pre-filled with the current values."""
+    """Build the form schema, pre-filled with the current values.
+
+    The API connection (Feature 18) carries the base URL the API client
+    talks to and the panel service token it presents as the Bearer
+    credential.  Schema-validated submits always carry every field (the
+    defaults pre-fill from the stored values); raw callers omitting one
+    keep its stored value (see _async_validate).
+    """
     return vol.Schema(
         {
             vol.Required(
-                CONF_HORIZON_DAYS, default=current[CONF_HORIZON_DAYS]
+                CONF_PANEL_IDLE_TIMEOUT,
+                default=current[CONF_PANEL_IDLE_TIMEOUT],
             ): int,
             vol.Required(
-                CONF_DAY_ROLLOVER_TIME, default=current[CONF_DAY_ROLLOVER_TIME]
+                CONF_UPDATE_INTERVAL, default=current[CONF_UPDATE_INTERVAL]
+            ): int,
+            # The last-good staleness threshold (Feature 18): how long
+            # the coordinator keeps serving the cached snapshot after
+            # the API stops answering.
+            vol.Required(
+                CONF_SNAPSHOT_STALENESS,
+                default=current[CONF_SNAPSHOT_STALENESS],
+            ): int,
+            # Panel-plane API connection (Feature 18): the base URL the
+            # API client talks to and the panel service token it
+            # presents as the Bearer credential.
+            vol.Required(
+                CONF_API_BASE_URL, default=current[CONF_API_BASE_URL]
             ): str,
             vol.Required(
-                CONF_PANEL_IDLE_TIMEOUT, default=current[CONF_PANEL_IDLE_TIMEOUT]
-            ): int,
+                CONF_PANEL_TOKEN, default=current[CONF_PANEL_TOKEN]
+            ): str,
         }
     )
 
@@ -81,10 +166,11 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
         """Manage the NestQuest options."""
         if user_input is None:
             return self.async_show_form(
-                step_id="init", data_schema=_build_schema(self._current_values())
+                step_id="init",
+                data_schema=_build_schema(self._current_values()),
             )
 
-        errors = _async_validate(user_input)
+        errors = _async_validate(user_input, self._current_values())
         if errors:
             return self.async_show_form(
                 step_id="init",
@@ -92,14 +178,20 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
                 errors=errors,
             )
 
-        return self.async_create_entry(
-            title="NestQuest",
-            data={
-                CONF_HORIZON_DAYS: user_input[CONF_HORIZON_DAYS],
-                CONF_DAY_ROLLOVER_TIME: user_input[CONF_DAY_ROLLOVER_TIME],
-                CONF_PANEL_IDLE_TIMEOUT: user_input[CONF_PANEL_IDLE_TIMEOUT],
-            },
-        )
+        # Every remaining key is stored the fall-back-to-current way, so
+        # raw submits that predate a section keep that section's stored
+        # values.
+        current = self._current_values()
+        data: dict[str, Any] = {}
+        for key in (
+            CONF_PANEL_IDLE_TIMEOUT,
+            CONF_UPDATE_INTERVAL,
+            CONF_SNAPSHOT_STALENESS,
+            CONF_API_BASE_URL,
+            CONF_PANEL_TOKEN,
+        ):
+            data[key] = user_input.get(key, current[key])
+        return self.async_create_entry(title="NestQuest", data=data)
 
     def _current_values(self) -> dict[str, Any]:
         """Resolve current values from entry options, then entry data, then defaults."""
@@ -107,9 +199,11 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
         entry_data = getattr(self.config_entry, "data", None) or {}
         values: dict[str, Any] = {}
         for key, default in (
-            (CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS),
-            (CONF_DAY_ROLLOVER_TIME, DEFAULT_DAY_ROLLOVER_TIME),
             (CONF_PANEL_IDLE_TIMEOUT, DEFAULT_PANEL_IDLE_TIMEOUT),
+            (CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL),
+            (CONF_SNAPSHOT_STALENESS, DEFAULT_SNAPSHOT_STALENESS),
+            (CONF_API_BASE_URL, DEFAULT_API_BASE_URL),
+            (CONF_PANEL_TOKEN, DEFAULT_PANEL_TOKEN),
         ):
             if key in options:
                 values[key] = options[key]
@@ -117,4 +211,4 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
                 values[key] = entry_data[key]
             else:
                 values[key] = default
-        return values
+        return values

custom_components/nestquest/sensor.py

@@ -0,0 +1,560 @@
+"""Per-child daily count and percentage sensors (Feature 10, task 2).
+
+Naming contract (design/ENTITIES-AND-SERVICES.md §1): the design table
+documents the entity_id shape ``sensor.nestquest_<child>_quests_due_today``.
+Home Assistant derives entity_id from the entity NAME and exact
+entity_id strings are not directly controllable, so names are spelled
+to slug into the documented shape — ``NestQuest Ada quests due today``
+slugs to ``sensor.nestquest_ada_quests_due_today`` — while the
+registry identity (``unique_id``) IS exact: built from the child's
+database id, never the display name, so a rename never orphans an
+entity's history.  The design table is the visual contract; this
+module spells names so HA's default slugging produces it.
+
+Every sensor reads ONLY ``coordinator.data`` (one
+:class:`~.coordinator.ChildDaySnapshot` per active child); no entity
+queries the database, so one refresh updates the whole board
+coherently.  The due-today sensor additionally carries the child's
+day payload as attributes: ``instances`` is the panel shape of
+ENTITIES-AND-SERVICES.md §1 (state ``open``/``completed``) OMITTING
+missed instances, and ``admin_instances`` includes them (D-009).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from homeassistant.components.sensor import (
+    SensorEntity,
+    SensorStateClass,
+)
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity import DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+from homeassistant.util import slugify
+
+from .const import DOMAIN
+from .coordinator import (
+    ChildDaySnapshot,
+    NestQuestCoordinator,
+    QuestInstanceView,
+)
+from .core.snapshot import instance_payload
+
+#: HA's state machine refuses states longer than 255
+#: characters (its hard recorder/state limit).  These sensors' states
+#: are numeric, but the guard is applied uniformly: a payload-bearing
+#: sensor can never crash the state write, and later string-state
+#: sensors reuse the same helper.
+MAX_STATE_LENGTH = 255
+
+#: Entity-id length cap the roster applies to HA's slugify: HA's
+#: slugifier itself does NOT truncate, but the entity registry derives
+#: entity ids as ``<domain>.<slug>`` and truncates the full entity_id at
+#: MAX_LENGTH_STATE_ENTITY_ID (64), so for this module's ``sensor.``
+#: entities the slugged object id alone may not exceed
+#: 64 - len("sensor.").
+_MAX_SLUG_LENGTH = 64 - len("sensor.")
+
+
+def _state_within_limit(state: Any) -> Any:
+    """Return ``state`` unchanged, refusing strings over HA's limit.
+
+    Numeric states pass through untouched; a string state longer than
+    :data:`MAX_STATE_LENGTH` fails fast with ValueError at the property
+    read — before HA's state machine rejects the write.
+    """
+    if isinstance(state, str) and len(state) > MAX_STATE_LENGTH:
+        raise ValueError(
+            f"state exceeds Home Assistant's {MAX_STATE_LENGTH}-character "
+            f"limit ({len(state)} characters)"
+        )
+    return state
+
+
+#: 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).
+NEXT_QUEST_NONE_STATE = "none"
+
+
+def _next_open_quest(
+    child: ChildDaySnapshot,
+) -> QuestInstanceView | None:
+    """Return the child's earliest open quest from today's snapshot.
+
+    The snapshot carries TODAY's instances, so "next" is the earliest
+    open instance by (due_date, due_time), with ``due_time`` ordering
+    ahead of ``None`` (a window with no due time comes first only
+    within the same date — the materializer snapshots each window's
+    due_time, so a missing one means the window is unscheduled).
+    Missed and completed instances never qualify.
+    """
+    open_views = [
+        view
+        for view in child.instances
+        if view.state == "open"
+    ]
+    if not open_views:
+        return None
+    return min(
+        open_views,
+        key=lambda view: (
+            view.due_date,
+            view.due_time if view.due_time is not None else "",
+        ),
+    )
+
+
+def _slugify(text: str) -> str:
+    """Slugify a display name the way Home Assistant derives entity ids.
+
+    Runs ``homeassistant.util.slugify`` — the real slugifier HA runs
+    entity names through, which transliterates every script to ASCII
+    through unidecode (so non-Latin names survive: ``京子`` slugs to
+    ``jing_zi``) before folding to lowercase and turning every run of
+    non-alphanumerics into one underscore, answering HA's ``unknown``
+    sentinel when a name slugs to nothing — then caps the result at
+    the object-id length the entity registry enforces (the registry
+    truncates the full ``sensor.`` + slug entity_id at 64 characters,
+    so the slug alone is capped like this; HA's slugify does not
+    truncate by itself).
+    """
+    return slugify(text)[:_MAX_SLUG_LENGTH]
+
+
+def _child_roster(children: Iterable[ChildDaySnapshot]) -> list[dict[str, Any]]:
+    """The ordered child roster the panel cards discover children from.
+
+    One entry per ACTIVE child in the snapshot's order (the API's
+    sort_order, then id): ``child_id``, ``name``, and the ``slug`` the
+    entity-id derivation produces for the child's name — the piece the
+    cards need to build ``sensor.nestquest_<slug>_...`` ids.  Duplicate
+    display names get the registry's ``_2``/``_3`` suffix in snapshot
+    order, matching how HA resolves the collision at registration.  The
+    rollups' ``children`` attribute (per-child counts) is unchanged and
+    carries a different shape on purpose.
+    """
+    slugs: dict[str, int] = {}
+    roster: list[dict[str, Any]] = []
+    for child in children:
+        base = _slugify(child.child_name)
+        taken = slugs.get(base, 0) + 1
+        slugs[base] = taken
+        roster.append(
+            {
+                "child_id": child.child_id,
+                "name": child.child_name,
+                "slug": base if taken == 1 else f"{base}_{taken}",
+            }
+        )
+    return roster
+
+
+class _NestQuestChildDaySensor(CoordinatorEntity, SensorEntity):
+    """Base for the per-child day sensors.
+
+    Registry identity is built from the child's database id and never
+    changes; the DISPLAYED name and device label are derived from the
+    child's CURRENT snapshot on every read, so a rename through
+    ``manage_child`` propagates on the next refresh without orphaning
+    the entity's history.  A child absent from the latest snapshot (a
+    deactivation; removal is a later task's scope) yields ``None``
+    states rather than stale counts.
+    """
+
+    #: Per-subclass label appended to the name (e.g. ``quests due
+    #: today``), set as a class attribute so ``name`` composes from the
+    #: current snapshot.
+    _name_suffix: str = ""
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator)
+        self._child_id = child.child_id
+        self._fallback_name = child.child_name
+        self._attr_unique_id = None  # set by the subclass
+
+    @property
+    def _child(self) -> ChildDaySnapshot | None:
+        """Return the child's current day snapshot, or None."""
+        data = self.coordinator.data
+        if data is None:
+            return None
+        for child in data.children:
+            if child.child_id == self._child_id:
+                return child
+        return None
+
+    def _displayed_child_name(self) -> str:
+        child = self._child
+        return child.child_name if child is not None else self._fallback_name
+
+    @property
+    def name(self) -> str | None:
+        return f"NestQuest {self._displayed_child_name()} {self._name_suffix}"
+
+    @property
+    def device_info(self) -> DeviceInfo:
+        return DeviceInfo(
+            identifiers={(DOMAIN, f"child_{self._child_id}")},
+            name=f"NestQuest {self._displayed_child_name()}",
+            manufacturer="NestQuest",
+        )
+
+
+class NestQuestQuestsDueTodaySensor(_NestQuestChildDaySensor):
+    """How many quests the child has due today, with the day payload."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _name_suffix = "quests due today"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = (
+            f"{DOMAIN}_child_{child.child_id}_quests_due_today"
+        )
+
+    @property
+    def native_value(self) -> int | None:
+        child = self._child
+        if child is None:
+            return None
+        return _state_within_limit(child.due_today)
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        child = self._child
+        if child is None:
+            return None
+        return {
+            "instances": instance_payload(
+                child.instances, include_missed=False
+            ),
+            "admin_instances": instance_payload(
+                child.instances, include_missed=True
+            ),
+            "child_id": child.child_id,
+            "child_name": child.child_name,
+            "present": child.present,
+        }
+
+
+class NestQuestQuestsCompletedTodaySensor(_NestQuestChildDaySensor):
+    """How many of the child's quests were completed today."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _name_suffix = "quests completed today"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = (
+            f"{DOMAIN}_child_{child.child_id}_quests_completed_today"
+        )
+
+    @property
+    def native_value(self) -> int | None:
+        child = self._child
+        if child is None:
+            return None
+        return _state_within_limit(child.completed_today)
+
+
+class NestQuestQuestsRemainingTodaySensor(_NestQuestChildDaySensor):
+    """How many of the child's quests are still owed today."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _name_suffix = "quests remaining today"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = (
+            f"{DOMAIN}_child_{child.child_id}_quests_remaining_today"
+        )
+
+    @property
+    def native_value(self) -> int | None:
+        child = self._child
+        if child is None:
+            return None
+        return _state_within_limit(child.remaining_today)
+
+
+class NestQuestCompletionPctTodaySensor(_NestQuestChildDaySensor):
+    """The child's completion percentage for today (100 on a zero-quest day)."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_native_unit_of_measurement = "%"
+    _name_suffix = "completion pct today"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = (
+            f"{DOMAIN}_child_{child.child_id}_completion_pct_today"
+        )
+
+    @property
+    def native_value(self) -> int | None:
+        child = self._child
+        if child is None:
+            return None
+        return _state_within_limit(child.completion_pct)
+
+
+class NestQuestNextQuestSensor(_NestQuestChildDaySensor):
+    """The child's next open quest today (title in the state).
+
+    State is the quest TITLE, truncated to HA's 255-character state
+    limit (attributes always carry the full title); when the child
+    owes nothing else today the state is the documented sentinel
+    ``none`` (NEXT_QUEST_NONE_STATE), never an empty string.
+    """
+
+    _attr_state_class = None  # a label, not a measurement
+    _name_suffix = "next quest"
+
+    def __init__(
+        self,
+        coordinator: NestQuestCoordinator,
+        child: ChildDaySnapshot,
+    ) -> None:
+        super().__init__(coordinator, child)
+        self._attr_unique_id = (
+            f"{DOMAIN}_child_{child.child_id}_next_quest"
+        )
+
+    @property
+    def native_value(self) -> str | None:
+        child = self._child
+        if child is None:
+            return None
+        quest = _next_open_quest(child)
+        if quest is None:
+            return NEXT_QUEST_NONE_STATE
+        return quest.title[:MAX_STATE_LENGTH]
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        child = self._child
+        if child is None:
+            return None
+        quest = _next_open_quest(child)
+        if quest is None:
+            return {"child_id": child.child_id, "child_name": child.child_name}
+        return {
+            "instance_id": quest.instance_id,
+            "definition_id": quest.definition_id,
+            "child_id": quest.child_id,
+            "child_name": child.child_name,
+            "title": quest.title,
+            "icon": quest.icon,
+            "window": quest.window,
+            "due_date": quest.due_date,
+            "due_time": quest.due_time,
+            "overdue": quest.overdue,
+        }
+
+
+def _child_day_sensors(
+    coordinator: NestQuestCoordinator, child: ChildDaySnapshot
+) -> tuple[_NestQuestChildDaySensor, ...]:
+    """Build the per-child day sensors for one active child."""
+    return (
+        NestQuestQuestsDueTodaySensor(coordinator, child),
+        NestQuestQuestsCompletedTodaySensor(coordinator, child),
+        NestQuestQuestsRemainingTodaySensor(coordinator, child),
+        NestQuestCompletionPctTodaySensor(coordinator, child),
+        NestQuestNextQuestSensor(coordinator, child),
+    )
+
+
+class _NestQuestHouseholdSensor(CoordinatorEntity, SensorEntity):
+    """Base for the household-level rollup sensors.
+
+    Aggregates the ACTIVE children's snapshots only (the snapshot
+    already excludes inactive children), matching the per-child
+    sensors exactly — a household number is always the sum of the
+    per-child numbers.  Grouped under one household device so the
+    three household sensors render together.
+    """
+
+    _attr_name: str
+
+    def __init__(self, coordinator: NestQuestCoordinator) -> None:
+        super().__init__(coordinator)
+        self._attr_device_info = DeviceInfo(
+            identifiers={(DOMAIN, "household")},
+            name="NestQuest Household",
+            manufacturer="NestQuest",
+        )
+
+
+class NestQuestHouseholdDueTodaySensor(_NestQuestHouseholdSensor):
+    """Total quests due today across active children.
+
+    Also publishes ``child_roster`` (see :func:`_child_roster`): the
+    ordered child identity list the panel cards read to discover the
+    board's children when the card config carries no ``child_order``.
+    """
+
+    _attr_name = "NestQuest household quests due today"
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_unique_id = f"{DOMAIN}_household_quests_due_today"
+
+    @property
+    def native_value(self) -> int | None:
+        data = self.coordinator.data
+        if data is None:
+            return None
+        return _state_within_limit(
+            sum(child.due_today for child in data.children)
+        )
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        data = self.coordinator.data
+        if data is None:
+            return None
+        return {
+            "children": {
+                str(child.child_id): child.due_today
+                for child in data.children
+            },
+            "child_roster": _child_roster(data.children),
+        }
+
+
+class NestQuestHouseholdCompletedTodaySensor(_NestQuestHouseholdSensor):
+    """Total quests completed today across active children."""
+
+    _attr_name = "NestQuest household quests completed today"
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_unique_id = f"{DOMAIN}_household_quests_completed_today"
+
+    @property
+    def native_value(self) -> int | None:
+        data = self.coordinator.data
+        if data is None:
+            return None
+        return _state_within_limit(
+            sum(child.completed_today for child in data.children)
+        )
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        data = self.coordinator.data
+        if data is None:
+            return None
+        return {
+            "children": {
+                str(child.child_id): child.completed_today
+                for child in data.children
+            }
+        }
+
+
+class NestQuestCycleDaySensor(_NestQuestHouseholdSensor):
+    """Cycle day N of the custody cycle (0 when nobody is scheduled).
+
+    Computed by the coordinator from the first active child with a
+    presence schedule, anchor-date arithmetic only (D-004 — never ISO
+    week parity), so a 53-week year cannot silently invert it.
+    """
+
+    _attr_name = "NestQuest cycle day"
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_unique_id = f"{DOMAIN}_cycle_day"
+
+    @property
+    def native_value(self) -> int | None:
+        data = self.coordinator.data
+        if data is None:
+            return None
+        return _state_within_limit(data.cycle_day)
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any] | None:
+        data = self.coordinator.data
+        if data is None:
+            return None
+        return {"cycle_day": data.cycle_day, "today": data.today_iso}
+
+
+def _household_sensors(
+    coordinator: NestQuestCoordinator,
+) -> tuple[_NestQuestHouseholdSensor, ...]:
+    """Build the three household-level sensors (one set per entry)."""
+    return (
+        NestQuestHouseholdDueTodaySensor(coordinator),
+        NestQuestHouseholdCompletedTodaySensor(coordinator),
+        NestQuestCycleDaySensor(coordinator),
+    )
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: ConfigEntry,
+    async_add_entities: Callable[..., None],
+) -> None:
+    """Create the five day sensors per active child.
+
+    Entities are created for the snapshot's children at platform
+    setup; a coordinator listener adds sensors for children that
+    first appear on a later refresh.  Deactivated children are NOT
+    removed here — their sensors hold ``None`` states until the
+    entity-removal task lands.
+    """
+    coordinator = entry.runtime_data.coordinator
+    known_child_ids: set[int] = set()
+
+    def _add_new_children(children: Iterable[ChildDaySnapshot]) -> None:
+        new_children = [
+            child
+            for child in children
+            if child.child_id not in known_child_ids
+        ]
+        if not new_children:
+            return
+        known_child_ids.update(child.child_id for child in new_children)
+        async_add_entities(
+            [
+                sensor
+                for child in new_children
+                for sensor in _child_day_sensors(coordinator, child)
+            ]
+        )
+
+    data = coordinator.data
+    if data is not None:
+        _add_new_children(data.children)
+        # The household rollups are child-independent: created exactly
+        # once at platform setup, they aggregate whatever the snapshot
+        # carries (empty included — an empty household is a valid 0).
+        async_add_entities(_household_sensors(coordinator))
+
+    def _handle_coordinator_update() -> None:
+        data = coordinator.data
+        if data is not None:
+            _add_new_children(data.children)
+
+    coordinator.async_add_listener(_handle_coordinator_update)

custom_components/nestquest/services.py

@@ -0,0 +1,190 @@
+"""The domain-global ``nestquest.complete_quest`` service (Feature 18).
+
+Registration is domain-scoped and happens once (see
+:func:`async_register_services`).  Since Feature 18 the integration is
+a client of the NestQuest API service, so ``complete_quest`` proxies
+to the API's panel complete route through the entry's shared API
+client instead of writing any database.  The former HA admin services
+(uncomplete, quest-definition and presence management, CSV export,
+child management, regenerate) are removed: the admin surface is the
+PWA and the API service's admin routes, so the only HA service left is
+the panel completion path.
+"""
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import voluptuous as vol
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import HomeAssistantError
+
+from .api_client import NestQuestApiError
+from .const import (
+    DOMAIN,
+    DOMAIN_SERVICES,
+    SERVICE_COMPLETE_QUEST,
+)
+
+FindRuntime = Callable[[HomeAssistant], Any]
+ServiceHandler = Callable[[Any], Awaitable[None]]
+
+ACTOR_PANEL = "panel"
+ACTOR_USER = "user"
+
+
+def _strict_int(value: object) -> int:
+    """Reject bools and non-ints; voluptuous ``int`` would accept True."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise vol.Invalid(f"expected int, got {value!r}")
+    return value
+
+
+SCHEMA_COMPLETE_QUEST = vol.Schema(
+    {
+        vol.Required("instance_id"): _strict_int,
+        vol.Required("actor"): vol.In([ACTOR_PANEL, ACTOR_USER]),
+        vol.Optional("actor_child_id"): _strict_int,
+        vol.Optional("actor_user_id"): str,
+    }
+)
+
+
+def _require_runtime(hass: HomeAssistant, find_runtime: FindRuntime):
+    runtime = find_runtime(hass)
+    if runtime is None:
+        raise HomeAssistantError(
+            "NestQuest is not loaded; cannot run this service"
+        )
+    return runtime
+
+
+async def _refresh_entities(runtime: Any) -> None:
+    """Force an immediate coordinator refresh after the service call.
+
+    Only the SERVICE path calls this — the scheduled materialize and
+    rollover internals are direct function calls and never widen this
+    gate — so the entities reflect a completion the moment the service
+    call returns instead of waiting for the poll interval.
+    """
+    coordinator = getattr(runtime, "coordinator", None)
+    if coordinator is not None:
+        await coordinator.async_refresh()
+
+
+def _actor_kwargs(call: Any) -> dict[str, Any]:
+    actor = call.data["actor"]
+    if actor == ACTOR_PANEL:
+        actor_child_id = call.data.get("actor_child_id")
+        if actor_child_id is None:
+            raise HomeAssistantError(
+                "actor_child_id is required when actor is panel"
+            )
+        return {
+            "actor_source": ACTOR_PANEL,
+            "actor_child_id": actor_child_id,
+            "actor_user_id": None,
+        }
+    context = getattr(call, "context", None)
+    user_id = getattr(context, "user_id", None) if context is not None else None
+    if not user_id:
+        user_id = call.data.get("actor_user_id")
+    return {
+        "actor_source": ACTOR_USER,
+        "actor_user_id": user_id,
+        "actor_child_id": None,
+    }
+
+
+def _with_errors(handler: ServiceHandler) -> ServiceHandler:
+    async def _wrapped(call: Any) -> None:
+        try:
+            await handler(call)
+        except HomeAssistantError:
+            raise
+        except ValueError as err:
+            raise HomeAssistantError(str(err)) from err
+
+    return _wrapped
+
+
+def _complete_quest(
+    hass: HomeAssistant, find_runtime: FindRuntime
+) -> ServiceHandler:
+    async def _handler(call: Any) -> None:
+        runtime = _require_runtime(hass, find_runtime)
+        instance_id = call.data["instance_id"]
+        # The panel contract (decision 9): a tap completes as the
+        # tapped child profile, the only actor shape the API's panel
+        # route accepts.  The payload schema is unchanged — the panel
+        # cards call it with instance_id, actor=panel, actor_child_id.
+        actor = _actor_kwargs(call)
+        if actor["actor_source"] != ACTOR_PANEL:
+            raise HomeAssistantError(
+                "nestquest.complete_quest completes through the API's "
+                "panel route as the tapped child profile; actor must "
+                "be 'panel' with actor_child_id"
+            )
+        # The entry's ONE shared API client (built at setup): the
+        # coordinator's snapshot poll, the SSE subscription, and this
+        # proxy all ride the same instance.  An entry with no panel
+        # token runs the unconfigured stub, which has no completion
+        # surface — fail fast with a clear, token-free message.
+        complete_instance = getattr(
+            getattr(runtime.coordinator, "api_client", None),
+            "complete_instance",
+            None,
+        )
+        if complete_instance is None:
+            raise HomeAssistantError(
+                "NestQuest API is not configured; cannot complete a "
+                "quest"
+            )
+        try:
+            await complete_instance(instance_id, actor["actor_child_id"])
+        except NestQuestApiError as err:
+            # The typed API failure surfaces as a service error the
+            # caller sees — never swallowed, never retried here.  The
+            # typed message names method, path, and status only; the
+            # panel token never appears in it.
+            raise HomeAssistantError(
+                f"NestQuest quest completion failed: {err}"
+            ) from err
+        # NO local completion write and NO local event: the API service
+        # emits the transition on its SSE stream and the integration's
+        # subscription re-fires it on the bus — firing it here too
+        # would double-fire.  The immediate refresh keeps the old
+        # behaviour where the sensors reflect the completion the
+        # moment the service call returns instead of waiting for the
+        # poll interval.
+        await _refresh_entities(runtime)
+
+    return _with_errors(_handler)
+
+
+def async_register_services(
+    hass: HomeAssistant,
+    *,
+    find_runtime: FindRuntime,
+) -> None:
+    """Register the panel completion service once at domain scope.
+
+    The one remaining HA service is the panel completion path; every
+    admin operation moved to the API service's admin routes, so there
+    is no permission gate to apply here.
+    """
+    if hass.services.has_service(DOMAIN, SERVICE_COMPLETE_QUEST):
+        return
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        _complete_quest(hass, find_runtime),
+        schema=SCHEMA_COMPLETE_QUEST,
+    )
+
+
+def async_deregister_services(hass: HomeAssistant) -> None:
+    """Remove every canonical service when the last entry unloads."""
+    for service in DOMAIN_SERVICES:
+        if hass.services.has_service(DOMAIN, service):
+            hass.services.async_remove(DOMAIN, service)

custom_components/nestquest/services.yaml

@@ -0,0 +1,39 @@
+# Service declarations for the NestQuest integration (Home Assistant
+# services.yaml metadata). Services are domain-scoped: nested under the
+# "nestquest" domain, not repeated per config entry.  Since Feature 18
+# only the panel completion service remains — every admin operation
+# moved to the PWA and the API service's admin routes.
+
+complete_quest:
+  name: Complete quest
+  description: Mark a quest instance as completed.
+  fields:
+    instance_id:
+      name: Instance ID
+      description: The quest instance to complete.
+      required: true
+      selector:
+        number:
+          mode: box
+    actor:
+      name: Actor
+      description: Who completed the quest (panel or user).
+      required: true
+      selector:
+        select:
+          options:
+            - panel
+            - user
+    actor_child_id:
+      name: Actor child ID
+      description: The tapped child profile. Required when actor is panel.
+      required: false
+      selector:
+        number:
+          mode: box
+    actor_user_id:
+      name: Actor user ID
+      description: Home Assistant user id when actor is user and no call context is present.
+      required: false
+      selector:
+        text:

custom_components/nestquest/sse.py

@@ -0,0 +1,172 @@
+"""HA-bus subscription over the API service's panel SSE stream.
+
+The NestQuest API service (Feature 16) publishes every quest
+transition on ``GET /api/v1/panel/events`` as Server-Sent Events
+frames.  This module is the integration-side subscriber: ONE
+background task consumes :meth:`~.api_client.NestQuestApiClient
+.stream_events` and re-fires each frame on ``hass.bus`` with the SAME
+event type and payload fields the local transition path
+(:mod:`~.events`) emits — ``nestquest_quest_completed``,
+``nestquest_quest_uncompleted``, ``nestquest_quest_missed`` and
+``nestquest_child_day_complete`` — so the four blueprints fire
+identically whether a completion happens through the integration's own
+service or through the API service's panel route.
+
+Failure handling: a failed stream (API down, network blip, non-2xx, a
+dropped connection) is retried FOREVER with a bounded exponential
+backoff — :data:`RECONNECT_MIN_SECONDS` after the first failure,
+doubling up to :data:`RECONNECT_MAX_SECONDS` — so a long API outage
+neither pins the event loop nor spams the log, and a frame received on
+a healthy stream resets the backoff.  Nothing escapes the task: every
+failure is logged with its reason and the loop reconnects; a
+:class:`asyncio.CancelledError` (from :meth:`stop` or integration
+unload) is the only thing that ends it, and it stops cleanly — no
+frame fires after :meth:`stop` returns and the response is closed.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .const import LOGGER
+
+__all__ = [
+    "NestQuestEventStream",
+    "RECONNECT_MAX_SECONDS",
+    "RECONNECT_MIN_SECONDS",
+]
+
+#: Delay before the FIRST reconnect attempt after a stream failure.
+#: One failed frame must not turn into a hot reconnect loop.
+RECONNECT_MIN_SECONDS = 5.0
+
+#: Ceiling for the exponential reconnect backoff: a long API outage
+#: retries at a calm fixed cadence instead of growing without bound.
+RECONNECT_MAX_SECONDS = 60.0
+
+
+class NestQuestEventStream:
+    """Consume the panel SSE stream in the background, fire the HA bus.
+
+    ONE instance per config entry, built in integration setup with the
+    SAME API client the coordinator polls (the client is stateless —
+    one shared session, one connection pool).  ``start()`` schedules
+    the background task; ``stop()`` cancels and awaits it, so unload
+    never leaks the task and no frame fires after teardown.  The task
+    itself is failure-proof: any exception from the stream (typed
+    :class:`~.api_client.NestQuestApiError` or anything else) is
+    logged and retried after the current backoff, never allowed to
+    escape the task.
+    """
+
+    def __init__(
+        self,
+        hass: Any,
+        client: Any,
+        *,
+        reconnect_min_seconds: float = RECONNECT_MIN_SECONDS,
+        reconnect_max_seconds: float = RECONNECT_MAX_SECONDS,
+    ) -> None:
+        """Store the hass bus target, the API client, and the backoff.
+
+        The client is anything exposing ``stream_events()`` (the real
+        :class:`~.api_client.NestQuestApiClient` in production, a stub
+        in tests).  The backoff bounds must be positive and the minimum
+        must not exceed the maximum — a misconfiguration should fail
+        loudly at construction, not quietly reconnect at delay 0.
+        """
+        if (
+            not isinstance(reconnect_min_seconds, (int, float))
+            or isinstance(reconnect_min_seconds, bool)
+            or reconnect_min_seconds <= 0
+            or reconnect_min_seconds > reconnect_max_seconds
+        ):
+            raise ValueError(
+                "reconnect_min_seconds must be a positive number no "
+                f"greater than reconnect_max_seconds, got "
+                f"{reconnect_min_seconds!r}"
+            )
+        if (
+            not isinstance(reconnect_max_seconds, (int, float))
+            or isinstance(reconnect_max_seconds, bool)
+            or reconnect_max_seconds <= 0
+        ):
+            raise ValueError(
+                f"reconnect_max_seconds must be a positive number, got "
+                f"{reconnect_max_seconds!r}"
+            )
+        self._hass = hass
+        self._client = client
+        self._min_backoff = float(reconnect_min_seconds)
+        self._max_backoff = float(reconnect_max_seconds)
+        self._backoff = float(reconnect_min_seconds)
+        self._task: asyncio.Task | None = None
+
+    @property
+    def task(self) -> asyncio.Task | None:
+        """The background task, or ``None`` when never started/stopped."""
+        return self._task
+
+    def start(self) -> None:
+        """Schedule the subscription task (idempotent while it runs)."""
+        if self._task is not None and not self._task.done():
+            return
+        self._backoff = self._min_backoff
+        self._task = asyncio.create_task(
+            self._run(), name="nestquest-sse-subscription"
+        )
+
+    async def stop(self) -> None:
+        """Cancel and await the subscription task.
+
+        Returns only after the task has actually finished, so unload
+        can rely on: no further frame is fired after ``stop()``, and
+        the underlying stream response has been closed.  Safe to call
+        when the task was never started or already stopped.
+        """
+        task, self._task = self._task, None
+        if task is None:
+            return
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            # The task's own cancellation surfaces here — expected and
+            # swallowed; a cancelling the CALLER would re-raise out of
+            # the surrounding await on its own.
+            pass
+
+    async def _run(self) -> None:
+        """Consume stream frames forever, reconnecting on failure."""
+        while True:
+            try:
+                async for event_type, payload in self._client.stream_events():
+                    # A frame arrived on a healthy stream: the next
+                    # failure reconnects quickly again.
+                    self._backoff = self._min_backoff
+                    try:
+                        self._hass.bus.async_fire(event_type, dict(payload))
+                    except Exception as err:
+                        # Firing one frame must never tear down a
+                        # healthy connection: log and keep consuming.
+                        LOGGER.error(
+                            "NestQuest panel event %s could not be fired "
+                            "on the Home Assistant event bus: %s",
+                            event_type,
+                            err,
+                        )
+            except asyncio.CancelledError:
+                # Unload / shutdown: stop cleanly, never converted.
+                raise
+            except Exception as err:
+                delay = self._backoff
+                self._backoff = min(
+                    self._backoff * 2, self._max_backoff
+                )
+                LOGGER.warning(
+                    "NestQuest panel event stream failed (%s); "
+                    "reconnecting in %.1f s",
+                    err,
+                    delay,
+                )
+                await asyncio.sleep(delay)

custom_components/nestquest/store.py

@@ -1,20 +0,0 @@
-"""SQLite storage path resolution for the NestQuest integration."""
-from __future__ import annotations
-
-from pathlib import Path
-
-from homeassistant.core import HomeAssistant
-
-from .const import SQLITE_DB_FILENAME
-
-
-def _ensure_dir(path: Path) -> None:
-    """Create the given directory and any missing parents."""
-    path.mkdir(parents=True, exist_ok=True)
-
-
-async def async_get_db_path(hass: HomeAssistant) -> Path:
-    """Return the absolute path to the NestQuest SQLite database file."""
-    db_path = Path(hass.config.path(SQLITE_DB_FILENAME)).absolute()
-    await hass.async_add_executor_job(_ensure_dir, db_path.parent)
-    return db_path

custom_components/nestquest/strings.json

@@ -18,17 +18,19 @@
     "step": {
       "init": {
         "title": "NestQuest Settings",
-        "description": "Adjust how NestQuest plans, rolls over days, and idles its panel.",
+        "description": "Adjust how the NestQuest API client polls and reaches the NestQuest API service.",
         "data": {
-          "horizon_days": "Generation horizon (days)",
-          "day_rollover_time": "Day rollover time (HH:MM)",
-          "panel_idle_timeout": "Panel idle timeout (seconds)"
+          "panel_idle_timeout": "Panel idle timeout (seconds)",
+          "snapshot_staleness": "Last-good snapshot staleness (seconds)",
+          "api_base_url": "NestQuest API base URL (http://host:port)",
+          "panel_token": "Panel service token"
         }
       }
     },
     "errors": {
       "invalid": "Invalid value.",
-      "invalid_time": "Time must use 24-hour HH:MM format."
+      "invalid_url": "Enter the API base URL as a full http:// or https:// URL with a host.",
+      "invalid_staleness": "Last-good snapshot staleness must be at least the update interval."
     }
   }
-}
+}

custom_components/nestquest/translations/en.json

@@ -18,17 +18,19 @@
     "step": {
       "init": {
         "title": "NestQuest Settings",
-        "description": "Adjust how NestQuest plans, rolls over days, and idles its panel.",
+        "description": "Adjust how the NestQuest API client polls and reaches the NestQuest API service.",
         "data": {
-          "horizon_days": "Generation horizon (days)",
-          "day_rollover_time": "Day rollover time (HH:MM)",
-          "panel_idle_timeout": "Panel idle timeout (seconds)"
+          "panel_idle_timeout": "Panel idle timeout (seconds)",
+          "snapshot_staleness": "Last-good snapshot staleness (seconds)",
+          "api_base_url": "NestQuest API base URL (http://host:port)",
+          "panel_token": "Panel service token"
         }
       }
     },
     "errors": {
       "invalid": "Invalid value.",
-      "invalid_time": "Time must use 24-hour HH:MM format."
+      "invalid_url": "Enter the API base URL as a full http:// or https:// URL with a host.",
+      "invalid_staleness": "Last-good snapshot staleness must be at least the update interval."
     }
   }
-}
+}

custom_components/nestquest/www/nestquest-admin-tokens.css

@@ -0,0 +1,76 @@
+/* ============================================================
+   NestQuest — Parent admin card tokens
+   Surface: phone, 390x844 reference. Plain CubeCraft styling,
+   no tabletop treatment, plain domain words in the UI.
+   Scope on the card host: nestquest-admin-card.
+   Derived from the approved mockups (admin screens 1d-1i).
+   Two densities were built; COMPACT is the default. Flip
+   --nq-a-density-* to the roomy values for the alternative.
+   ============================================================ */
+
+:host {
+  /* ── Brand + neutrals (CubeCraft tokens, verbatim) ─────── */
+  --nq-brand-blue:        #3B3AB8;
+  --nq-brand-purple:      #A035CC;
+  --nq-brand-gradient:    linear-gradient(135deg, var(--nq-brand-blue), var(--nq-brand-purple));
+  --nq-brand-gradient-h:  linear-gradient(90deg,  var(--nq-brand-blue), var(--nq-brand-purple));
+
+  --nq-a-page:            #F4F4F6;
+  --nq-a-surface:         #FFFFFF;
+  --nq-a-surface-subtle:  #FAFAFA;
+  --nq-a-selected:        #EBEBF8;   /* row being edited */
+  --nq-a-border:          #E4E4EA;
+  --nq-a-divider:         #EDEDF1;
+
+  --nq-a-ink:             #18181D;
+  --nq-a-ink-secondary:   #52525E;
+  --nq-a-ink-tertiary:    #70707E;   /* inactive rows, unselected nav icons */
+
+  --nq-a-success:         #15803D;
+  --nq-a-danger:          #DC2626;
+  --nq-a-danger-strong:   #B91C1C;
+  --nq-a-danger-bg:       #FEE2E2;
+  --nq-a-warning-ink:     #92400E;
+  --nq-a-warning-ink-2:   #78350F;
+  --nq-a-warning-bg:      #FEF3C7;
+  --nq-a-warning-border:  rgba(217,119,6,.35);
+  --nq-a-info-bg:         #DBEAFE;
+  --nq-a-info-ink:        #1E3A8A;
+  --nq-a-info-icon:       #1D4ED8;
+  --nq-a-reversal:        #7D28A0;   /* un-complete events in history */
+
+  /* ── Type ─────────────────────────────────────────────── */
+  --nq-a-font:            Nunito, system-ui, sans-serif;
+  --nq-a-size-screen:     24px;  /* 800, screen title */
+  --nq-a-size-hero:       32px;  /* 800, roomy "8 of 12 done" */
+  --nq-a-size-card-title: 19px;  /* 800, roomy child card */
+  --nq-a-size-stat:       22px;  /* 800, compact stat number */
+  --nq-a-size-row:        13.5px;/* 700, list row title */
+  --nq-a-size-meta:       11px;  /* 600, row meta */
+  --nq-a-size-label:      10px;  /* 700, uppercase field label */
+  --nq-a-track-label:     .10em;
+
+  /* ── Density: COMPACT (default) ───────────────────────── */
+  --nq-a-density-page-pad:   14px 16px 92px;  /* bottom clears the 70px tab bar */
+  --nq-a-density-gap:        10px;
+  --nq-a-density-card-pad:   13px;
+  --nq-a-density-row-pad:    11px 13px;
+  --nq-a-density-radius:     8px;
+  --nq-a-density-shadow:     none;
+  /* Density: ROOMY — page-pad 18px 20px 92px; gap 16px;
+     card-pad 18px; radius 12px; shadow 0 4px 12px rgba(0,0,0,.06) */
+
+  /* ── Metrics ──────────────────────────────────────────── */
+  --nq-a-tabbar-height:   70px;   /* + 12px safe-area padding */
+  --nq-a-tap-min:         44px;   /* every row/control clears this */
+  --nq-a-radius-pill:     9999px;
+  --nq-a-radius-sheet:    20px 20px 0 0;
+  --nq-a-sheet-shadow:    0 -8px 28px rgba(9,9,11,.18);
+  --nq-a-progress-height: 6px;    /* 8px roomy, 10px hero */
+
+  /* ── Motion ───────────────────────────────────────────── */
+  --nq-ease-out:          cubic-bezier(0, 0, .2, 1);
+  --nq-dur-micro:         120ms;
+  --nq-dur-base:          200ms;
+  --nq-dur-modal:         350ms;
+}

custom_components/nestquest/www/nestquest-fonts.css

@@ -0,0 +1,71 @@
+@font-face {
+  font-family: "Nunito";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("./fonts/nunito-latin-400-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Nunito";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url("./fonts/nunito-latin-600-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Nunito";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("./fonts/nunito-latin-700-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Nunito";
+  font-style: normal;
+  font-weight: 800;
+  font-display: swap;
+  src: url("./fonts/nunito-latin-800-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Cinzel";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url("./fonts/cinzel-latin-600-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Cinzel";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("./fonts/cinzel-latin-700-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Cinzel";
+  font-style: normal;
+  font-weight: 900;
+  font-display: swap;
+  src: url("./fonts/cinzel-latin-900-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Cinzel Decorative";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("./fonts/cinzel-decorative-latin-700-normal.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Cinzel Decorative";
+  font-style: normal;
+  font-weight: 900;
+  font-display: swap;
+  src: url("./fonts/cinzel-decorative-latin-900-normal.woff2") format("woff2");
+}

custom_components/nestquest/www/nestquest-panel-tokens.css

@@ -0,0 +1,96 @@
+/* ============================================================
+   NestQuest — Kids' panel card tokens
+   Surface: DAKboard DAKOS wall panel, 1920x1080 landscape,
+   viewed from ~3 ft, no login, read/complete only.
+   Scope these on the card host: nestquest-quest-log-card,
+   nestquest-party-board-card.
+   Derived from the approved mockups (panel screens 1a, 1b, 1c, 1j).
+   ============================================================ */
+
+:host {
+  /* ── Parchment ground ─────────────────────────────────── */
+  --nq-p-parchment-top:      #f0e4c7;
+  --nq-p-parchment-bottom:   #ddcca3;
+  --nq-p-parchment: radial-gradient(ellipse at 25% 10%, rgba(255,255,255,.5), transparent 55%),
+                    radial-gradient(ellipse at 85% 90%, rgba(120,86,44,.28), transparent 60%),
+                    repeating-linear-gradient(93deg, rgba(150,115,70,.05) 0 2px, transparent 2px 6px),
+                    repeating-linear-gradient(2deg, rgba(150,115,70,.04) 0 3px, transparent 3px 7px),
+                    linear-gradient(var(--nq-p-parchment-top), var(--nq-p-parchment-bottom));
+  --nq-p-vignette:           inset 0 0 200px rgba(80,52,20,.35);
+
+  /* Card surfaces sitting on parchment */
+  --nq-p-card-open:          linear-gradient(#fdf7e6, #f2e7c9);   /* incomplete quest */
+  --nq-p-card-done:          linear-gradient(#f0e8d3, #e6dcc2);   /* sealed quest */
+  --nq-p-card-panel:         linear-gradient(#fcf6e6, #f1e6ca);   /* adventurer plate, stat block */
+  --nq-p-card-border:        rgba(120,88,48,.38);
+  --nq-p-panel-border:       rgba(92,62,26,.40);
+  --nq-p-card-shadow:        0 3px 0 rgba(120,88,48,.20), inset 0 1px 0 rgba(255,255,255,.70);
+  --nq-p-panel-shadow:       0 6px 0 rgba(92,62,26,.18), inset 0 2px 0 rgba(255,255,255,.70);
+  --nq-p-frame-outer:        2px solid rgba(92,62,26,.45);
+  --nq-p-frame-inner:        1px solid rgba(92,62,26,.28);
+  --nq-p-rule:               2px solid rgba(92,62,26,.35);
+
+  /* ── Ink (all values >= 4.5:1 on parchment) ───────────── */
+  --nq-p-ink:                #2b1f14;   /* titles, quest names */
+  --nq-p-ink-secondary:      #5c452a;   /* meta, window labels, counts */
+  --nq-p-ink-muted:          #6f6455;   /* sealed quest titles only */
+  --nq-p-ink-away:           #4d4433;   /* away adventurer name */
+  --nq-p-ink-late:           #8f1526;   /* overdue line */
+
+  /* ── Brand (CubeCraft, toned down: accents only) ──────── */
+  --nq-brand-blue:           #3B3AB8;
+  --nq-brand-purple:         #A035CC;
+  --nq-brand-gradient:       linear-gradient(135deg, var(--nq-brand-blue), var(--nq-brand-purple));
+  --nq-p-icon-tile:          var(--nq-brand-gradient);            /* open quest icon tile */
+  --nq-p-icon-tile-done:     rgba(92,62,26,.16);
+  --nq-p-crest:              var(--nq-brand-gradient);
+  --nq-p-crest-away:         linear-gradient(135deg, #6b6b7a, #7a7286);
+
+  /* ── Wax seal (completed marker) ──────────────────────── */
+  --nq-p-seal:               radial-gradient(circle at 35% 30%, #a8283a, #6d1322);
+  --nq-p-seal-shadow:        0 4px 10px rgba(60,10,20,.40), inset 0 0 0 4px rgba(255,255,255,.14);
+  --nq-p-seal-size:          78px;   /* 168px on the quest-complete screen */
+
+  /* ── Dock (bottom strip, non-interactive) ─────────────── */
+  --nq-p-dock-bg:            rgba(43,31,20,.90);
+  --nq-p-dock-ink:           #f7efdb;
+  --nq-p-dock-ink-secondary: #d8c9a6;
+  --nq-p-dock-divider:       rgba(233,220,189,.30);
+  --nq-p-dock-height:        84px;
+
+  /* ── Type ─────────────────────────────────────────────── */
+  --nq-p-font-display:       'Cinzel Decorative', Cinzel, serif;  /* NestQuest, names, Quest complete */
+  --nq-p-font-heading:       Cinzel, serif;                       /* section heads, quest titles, numerals */
+  --nq-p-font-body:          Nunito, system-ui, sans-serif;       /* meta lines, dock */
+
+  --nq-p-size-hero:          86px;   /* 900 weight, "Quest complete" */
+  --nq-p-size-wordmark:      66px;   /* 900 weight */
+  --nq-p-size-title:         56px;   /* 700, "Declan's Quest Log" */
+  --nq-p-size-name:          48px;   /* 700, adventurer name */
+  --nq-p-size-section:       32px;   /* 700, Morning / Afternoon / Evening */
+  --nq-p-size-quest:         30px;   /* 700, quest title */
+  --nq-p-size-body:          22px;   /* 600 Nunito, meta — PANEL MINIMUM */
+  --nq-p-size-label:         21px;   /* 600 Cinzel, uppercase, tracked */
+  --nq-p-track-label:        .14em;
+  --nq-p-track-kicker:       .30em;
+
+  /* ── Metrics: touch ───────────────────────────────────── */
+  --nq-p-quest-min-height:   116px;  /* whole card is the tap target */
+  --nq-p-quest-gap:          24px;   /* separation between tap targets */
+  --nq-p-quest-pad:          22px;   /* padding inside a quest card */
+  --nq-p-tile-size:          64px;   /* quest icon tile */
+  --nq-p-button-height:      72px;   /* "Complete" button on a quest card */
+  --nq-p-button-min-width:   150px;
+  --nq-p-confirm-button:     108px;  /* confirm dialog buttons */
+  --nq-p-radius-card:        12px;
+  --nq-p-radius-panel:       20px;
+  --nq-p-radius-pill:        9999px;
+  --nq-p-page-inset:         62px;
+  --nq-p-frame-inset:        26px;
+
+  /* ── Motion (CubeCraft easing) ────────────────────────── */
+  --nq-ease-out:             cubic-bezier(0, 0, .2, 1);
+  --nq-dur-micro:            120ms;
+  --nq-dur-base:             200ms;
+  --nq-dur-modal:            350ms;
+}

deploy/nestquest-controller.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=NestQuest OpenCode controller
+
+[Service]
+Type=simple
+WorkingDirectory=/mnt/ai-storage/projects/NestQuest
+ExecStartPre=/home/overseer/.local/share/nestquest-controller/scripts/nq-controller --check
+ExecStart=/home/overseer/.local/share/nestquest-controller/scripts/nq-controller
+Restart=on-failure
+RestartSec=60s
+RestartPreventExitStatus=77
+TimeoutStartSec=0
+KillMode=control-group
+Environment=PYTHONUNBUFFERED=1

deploy/opencode-global-commands/start-nestquest-development.md

@@ -0,0 +1,11 @@
+---
+description: Run the NestQuest orchestrator now in this OpenCode terminal
+agent: terminal-orchestrator
+---
+
+Run the NestQuest project queue now in this foreground OpenCode session.
+Read the current CTXD prompt and Maestro state, but use the FOREGROUND
+TERMINAL RUNTIME instead of the service runtime. Reconcile repository and
+pull-request state, then execute CONTROLLER_TICK repeatedly until a global
+terminal condition, explicit user stop, genuine global block, or host-forced
+yield. Do not start or wait for the systemd controller.

design/ADMIN-SPEC.md

@@ -0,0 +1,136 @@
+# Admin spec — parent phone card
+
+Screens `1d`–`1i`. One card, `nestquest-admin-card`, four tabs. Reference viewport
+390×844. Plain CubeCraft styling and plain domain words — no parchment, no Cinzel, no
+quest vocabulary in this surface.
+
+## 1. Shell
+
+- Page `--nq-a-page`; cards `--nq-a-surface` with 1px `--nq-a-border`.
+- **Header** white, 1px bottom border: screen title 24px/800, tracking −.02em, plus a
+  12px/600 `--nq-a-ink-secondary` sub-line. Optional trailing action (icon square 36px,
+  or a gradient `New` button).
+- **Tab bar** absolute bottom, `--nq-a-tabbar-height` 70px + 12px bottom padding, white,
+  1px top border, 4 items: `house` Today · `list-checks` Tasks · `calendar-days` Schedule ·
+  `history` History. Active icon and label `--nq-brand-blue` at 700; inactive icon
+  `--nq-a-ink-tertiary`, label `--nq-a-ink-secondary` 600.
+- **Every scroll column ends with 92px bottom padding** so content clears the tab bar.
+  This was a real defect in review — do not omit it.
+- Two densities exist. Ship **compact**; `--nq-a-density-*` carries the roomy values.
+- Everything this card mutates goes through a NestQuest service, which enforces the admin
+  allowlist server-side. The card must assume it can be rendered by a non-admin and still
+  be safe — hiding controls is not the boundary (D-003).
+
+## 2. Today (1d compact, 1h roomy)
+
+### 2.1 Header
+Title `Today`; sub `<weekday>, <Month D> · cycle day N of 14`; trailing `settings` square.
+
+### 2.2 Stat row
+Three equal cards, 8px gap, padding 12px: numeral 22px/800 (done in `--nq-brand-blue`,
+remaining in `--nq-a-ink`, overdue in `--nq-a-danger`), label 10px/600 uppercase tracking
+.08em `--nq-a-ink-secondary` — `Done`, `Remaining`, `Overdue`.
+
+### 2.3 Child rows
+One card, rows divided by `--nq-a-divider`, row padding 11px 13px:
+30px gradient avatar square (radius 7px, initial 13px/800 white) · name 14px/700 ·
+meta 11px/600 (`3 of 7 · 1 overdue`; all-done in `--nq-a-success`; away reads
+`Away · returns <Mon D>`) · 82×6px progress track with gradient fill. An away child's
+avatar is flat `#9898A8` and the row carries a lowercase `override` pill when the absence
+comes from a presence override rather than the pattern.
+
+### 2.4 Roomy variant (1h)
+Header becomes a hero: kicker 11px/700 uppercase, `8 of 12 done` 32px/800, 10px gradient
+progress bar, 13px/600 sub-line. Each child gets its own 12px-radius card with
+`0 4px 12px rgba(0,0,0,.06)`, 48px avatar, 19px/800 name, right-aligned `3/7` +
+status line, and its overdue item inlined as a `--nq-a-danger-bg` row with a
+`Mark done` action.
+
+### 2.5 Needs attention
+Section label 11px/700 uppercase, then one card of event rows: Lucide glyph 18px ·
+title `<Quest> · <Child>` 13px/700 · meta 11px/600 (`Overdue since 9:00 AM` in
+`--nq-a-danger`; `Completed 7:04 AM from panel` in `--nq-a-ink-secondary`) · trailing
+text action `Mark done` (`--nq-brand-blue`) or `Undo` (`--nq-brand-purple`).
+
+### 2.6 Permission note
+An info strip (`--nq-a-info-bg`, `info` glyph, 11.5px/600 `--nq-a-info-ink`):
+"Undo is admin-only. A panel tap can never reverse a completion." Keep this copy — it is
+the one place the security model is explained to the user.
+
+## 3. Definitions (1e)
+
+### 3.1 List
+Header `Tasks` / `7 definitions · 3 children` + gradient `New` button. Filter chips row
+(All / one per child): active `#18181D` fill white text, inactive white with border.
+Rows: glyph 17px · title 13.5px/700 · meta 11px/600 `<assignees> · <recurrence> · <windows>`
+· `chevron-right`. An inactive definition renders the whole row at
+`--nq-a-ink-tertiary` with `· inactive` in the meta — never hard-deleted (glossary).
+The row being edited takes `--nq-a-selected` with brand-blue glyph, `Editing` meta and
+`chevron-down`.
+
+### 3.2 Edit sheet
+Bottom sheet, `--nq-a-radius-sheet`, `--nq-a-sheet-shadow`, 38×4px grabber, padding
+14px 18px 24px. Title 19px/800. Fields, 11px gap, each with a 10px/700 uppercase label:
+
+| Field | Control |
+|---|---|
+| Assigned children | multi-select row → sheet; shows `Declan` or `All three` |
+| Repeats | select (Daily / Weekly / Monthly / Yearly / Custom + interval) |
+| Due time | time field per window |
+| Window | 3-up segmented, **multi-select** — a definition may own several |
+| Skip on away days | toggle, gradient when on, sub "No instance when the child is absent" |
+
+Footer: `Cancel` (flex 1, bordered) + `Save changes` (flex 2, gradient), both 13px vertical
+padding. Sheet enters over the dimmed list in `--nq-dur-modal`.
+
+### 3.3 Icon picker
+Each definition carries a Lucide glyph, shown on both surfaces. **The allowed subset is not
+yet defined** — pick 24–40 household-relevant glyphs and ship them as a grid picker.
+
+## 4. Schedule (1f)
+
+- Header `Schedule` / `2-week cycle · anchor <weekday>, <Mon D>`.
+- **Month grid** card: month label 11px/700 uppercase + chevron pair; weekday initials
+  10px/700 `--nq-a-ink-tertiary`; day cells `aspect-ratio: 1`, radius 6px —
+  rotation-home days `--nq-a-selected` with `#201F7A` numerals, away days
+  `--nq-a-page` with `--nq-a-ink-secondary`, override days `--nq-a-warning-bg` with
+  `--nq-a-warning-ink` and a 1px warning border, today filled with the brand gradient in
+  white 800. Legend row beneath, 10.5px/600, one swatch per state.
+- **Presence pattern** card: one row per child, name 13px/700 + rule 12px/600
+  (`Weeks 1 & 3 of cycle`, `Every day`).
+- **Overrides** card: `Add` text action; rows with `calendar-x` / `calendar-check`,
+  title `<Child> away · <Mon D – D>`, meta reason, trailing `trash-2`.
+- Cycle position is always computed from the anchor date. **Never** from ISO week numbers
+  or week parity (D-004).
+
+## 5. History (1g)
+
+- Header `History` / `Append-only event log · last 14 days` + bordered `CSV` button
+  (`download` glyph) that exports the filtered range.
+- Stat row: `91%` On time · `128` Completed · `7` Missed, numerals 20px/800.
+- Filter chips: `All events` / `Reversals` / `Missed`.
+- Day-grouped sections (label 11px/700 uppercase) of event rows: 7px status dot
+  (green completed, `--nq-a-reversal` un-completed, `--nq-a-danger` missed) ·
+  title `<Quest> · <Child>` 12.5px/700 · meta 10.5px/600 giving event type, actor and
+  on-time flag (`completed · panel (Declan) · on time`, `uncompleted · joshua (admin)`,
+  `missed · nightly sweep`, `completed · panel (Declan) · late 22 min`) · time 11px/600.
+- Footer strip (`--nq-a-page`, `lock` glyph): "Events are never edited or deleted. A
+  reversal is its own row." Rows are never editable in the UI (D-005).
+
+## 6. Presence override editor (1i)
+
+Pushed screen with a back chevron; title `Presence override` / sub "Beats the custody
+pattern for these dates".
+
+- Form card (roomy density, 18px padding, 16px gaps):
+  **Child** 3-up segmented, selected = gradient;
+  **Status for these dates** 2-up segmented (`Away` / `Home`), selected = `#18181D`;
+  **From** / **Through** date fields side by side, 13px padding, 14px/700 values;
+  **Reason (optional)** text field.
+- **Consequence warning** — `--nq-a-warning-bg` card with `alert-circle`:
+  headline `This removes N upcoming tasks` 13.5px/700 `--nq-a-warning-ink`, body 12px/600
+  `--nq-a-warning-ink-2` naming the child, the date range, and stating "Completed days are
+  untouched." The count must be computed live from the materialiser before saving.
+- Footer: `Cancel` (flex 1, white, bordered) + `Save override` (flex 2, gradient), 15px
+  vertical padding.
+- Saving must never delete an instance that already has a completion event.

design/DESIGN-HANDOFF.md

@@ -0,0 +1,82 @@
+# NestQuest — design handoff
+
+Approved UI design for the NestQuest Home Assistant integration, ready to implement.
+Source of truth for visuals: the mockup file `NestQuest Mockups.dc.html` (9 screens,
+option ids `1a`–`1j`). This folder is the written form of those screens.
+
+## What is in here
+
+| File | Contents |
+|---|---|
+| `PANEL-SPEC.md` | Kids' DAKOS wall panel: party board, quest log, confirm, quest complete |
+| `ADMIN-SPEC.md` | Parent phone admin: today, definitions, schedule, history, overrides |
+| `ENTITIES-AND-SERVICES.md` | Every screen mapped to the HA entities, services and events it needs |
+| `IMPLEMENTATION-ORDER.md` | Build order, with the decisions that change existing code first |
+| `tokens/nestquest-panel-tokens.css` | Panel card custom properties |
+| `tokens/nestquest-admin-tokens.css` | Admin card custom properties |
+
+## Screen index
+
+| id | Screen | Surface | Spec |
+|---|---|---|---|
+| 1a | The Party (attract) | panel 1920×1080 | PANEL §2 |
+| 1b | Quest Log | panel 1920×1080 | PANEL §3 |
+| 1j | Complete confirm | panel 1920×1080 | PANEL §4 |
+| 1c | Quest complete | panel 1920×1080 | PANEL §5 |
+| 1d | Today (compact) | phone 390×844 | ADMIN §2 |
+| 1e | Definitions + edit sheet | phone 390×844 | ADMIN §3 |
+| 1f | Schedule + custody | phone 390×844 | ADMIN §4 |
+| 1g | History + CSV | phone 390×844 | ADMIN §5 |
+| 1h | Today (roomy) | phone 390×844 | ADMIN §2.4 |
+| 1i | Presence override | phone 390×844 | ADMIN §6 |
+
+## Design decisions taken during this handoff
+
+These were open in CTXD and are now settled. Several contradict the current repo and
+docs — read `IMPLEMENTATION-ORDER.md` §1 before writing code.
+
+1. **`quest_*` naming throughout.** The domain model is renamed from `task_*` to
+   `quest_*` in DB, services, entities and UI. Migration note in IMPLEMENTATION-ORDER §1.1.
+2. **Instance key becomes `(definition_id, child_id, due_date, window)`.** Required by
+   multi-assignee definitions and by twice-daily quests. Supersedes the documented
+   `(definition_id, due_date)`.
+3. **A definition may have multiple assignees**, and materialises one instance per
+   assigned child per date per window. Each child completes their own.
+4. **A definition may declare more than one window** (morning / afternoon / evening),
+   producing one instance per window per day.
+5. **Missed quests vanish from the panel at rollover.** Kids never see a wall of failure;
+   the missed event is in the parent's history only.
+6. **Three Lovelace cards**: `nestquest-party-board-card`, `nestquest-quest-log-card`,
+   `nestquest-admin-card`. Board and log live in separate Lovelace views; a crest tap
+   navigates.
+7. **Completion needs a confirm step** (screen 1j) because children cannot undo.
+8. **The quest log owns idle return**: 40 s of no touch navigates back to the board.
+   TouchHub Auto-Return must be configured longer than 40 s so the two do not fight.
+9. **Actor on a panel completion** is `panel` plus the tapped child profile, per glossary.
+10. **Weather is a configured entity** on the party board card (`weather_entity`), not
+    NestQuest data.
+11. **Fonts are bundled** as local woff2 in the card's `www/` folder — the panel may be
+    offline. Nunito (400/600/700/800) and Cinzel + Cinzel Decorative.
+
+## Vocabulary
+
+The panel speaks tabletop; the admin speaks plainly. Both sit on the same `quest_*` model.
+
+| Model / admin | Panel display string |
+|---|---|
+| quest instance | quest |
+| child | adventurer |
+| child's task list | Quest Log |
+| household | The Party |
+| all complete | Quest complete |
+| absent | On travels |
+
+## Open questions
+
+- Empty and error states are unspecified by request (child with no quests, everyone away,
+  integration unconfigured, DB unreachable). Panel must not render a blank parchment —
+  decide before shipping the card.
+- No gamification is in scope. XP, levels, streaks and rarity were explicitly deferred,
+  but the append-only event log already supports computing them later.
+- Icon per quest definition is chosen by the parent from a Lucide subset; the subset is
+  not yet defined (`ADMIN-SPEC.md` §3.3).

design/ENTITIES-AND-SERVICES.md

@@ -0,0 +1,118 @@
+# Screens → HA entities, services and events
+
+Planned surface from CTXD CONTEXT.MD, adjusted for the design decisions in
+`DESIGN-HANDOFF.md`. Names use the `quest_*` model.
+
+## 1. Entities the cards read
+
+| Entity | Type | Used by |
+|---|---|---|
+| `sensor.nestquest_<child>_quests_due_today` | int | 1a plate progress, 1b counts, 1d stats |
+| `sensor.nestquest_<child>_quests_completed_today` | int | 1a, 1b, 1c, 1d, 1h |
+| `sensor.nestquest_<child>_quests_remaining_today` | int | 1b remaining block, 1d |
+| `sensor.nestquest_<child>_completion_pct_today` | float | progress bars |
+| `sensor.nestquest_<child>_next_quest` | str + attrs | optional panel hint |
+| `binary_sensor.nestquest_<child>_all_done` | bool | 1c trigger, 1d "all done" |
+| `binary_sensor.nestquest_<child>_present_today` | bool | 1a away plate, 1d away row |
+| `sensor.nestquest_household_quests_due_today` | int | 1b party line, 1c party stat |
+| `sensor.nestquest_household_quests_completed_today` | int | same |
+| `sensor.nestquest_cycle_day` | int | 1d sub-line, 1f header |
+| *configured* `weather.<entity>` | HA core | panel dock |
+
+Per-instance data is too granular for entity state. The cards read the day's instance list
+from an attribute payload on the per-child sensor (or a websocket command —
+implementer's call), shaped:
+
+```json
+{
+  "instances": [
+    { "id": 4821, "definition_id": 12, "child_id": 3, "title": "Fill bird feeder",
+      "icon": "bird", "window": "afternoon", "due_time": "17:00",
+      "state": "open", "overdue": true, "completed_at": null, "on_time": null }
+  ]
+}
+```
+
+`state` ∈ `open` | `completed`. Missed instances are **omitted** from panel payloads
+(decision 5) and included in admin payloads.
+
+## 2. Services the cards call
+
+| Service | Admin only | Called from |
+|---|---|---|
+| `nestquest.complete_quest` | no (panel allowed) | 1j confirm |
+| `nestquest.uncomplete_quest` | **yes** | 1d `Undo` |
+| `nestquest.create_quest_definition` | **yes** | 1e `New` |
+| `nestquest.update_quest_definition` | **yes** | 1e sheet `Save changes` |
+| `nestquest.set_quest_definition_active` | **yes** | 1e row action |
+| `nestquest.set_presence_pattern` | **yes** | 1f presence card |
+| `nestquest.create_presence_override` | **yes** | 1i `Save override` |
+| `nestquest.delete_presence_override` | **yes** | 1f override row `trash-2` |
+| `nestquest.export_history_csv` | **yes** | 1g `CSV` |
+| `nestquest.manage_child` | **yes** | settings |
+
+`complete_quest` payload from the panel:
+
+```yaml
+service: nestquest.complete_quest
+data:
+  instance_id: 4821
+  actor: panel            # kiosk user context
+  actor_child_id: 3       # the tapped profile (decision 9)
+```
+
+Every service resolves `call.context.user_id` against the admin allowlist and **fails
+closed** with no user context (D-003). The panel's kiosk user is never allowlisted, so
+`uncomplete_quest` is unreachable from the wall even though the card never renders the
+control.
+
+## 3. Events the cards listen for
+
+| Event | Effect |
+|---|---|
+| `nestquest_quest_completed` | stamp the seal, re-sort the column, refresh counts |
+| `nestquest_quest_uncompleted` | un-seal, restore the card (admin action, panel must reflect it) |
+| `nestquest_quest_missed` | remove the instance from the panel; add a history row |
+| `nestquest_child_day_complete` | show screen 1c |
+
+All four come off the `DataUpdateCoordinator`; cards should also refresh on
+`state_changed` for their sensors so they recover if an event is dropped.
+
+## 4. Card configuration
+
+```yaml
+# kids' panel, view 1
+type: custom:nestquest-party-board-card
+weather_entity: weather.home          # optional; dock falls back to date/time
+quest_log_path: /nestquest/log        # view the crest tap navigates to
+child_order: [declan, jordyn, chloe]
+
+# kids' panel, view 2
+type: custom:nestquest-quest-log-card
+board_path: /nestquest/board
+weather_entity: weather.home          # optional; dock falls back to date/time
+idle_return_seconds: 40               # must be shorter than TouchHub Auto-Return
+confirm_timeout_seconds: 15
+complete_screen_seconds: 12
+
+# parent phone
+type: custom:nestquest-admin-card
+density: compact                      # compact | roomy
+default_tab: today
+```
+
+The quest log reads the selected child from the view's URL/`hass` path parameter so the
+board → log hop is a plain Lovelace navigation (decision 6).
+
+## 5. Data-shape consequences of the design
+
+1. Instance key is `(definition_id, child_id, due_date, window)` — the schema's
+   `task_instances` unique index must widen.
+2. `quest_definitions` needs an **assignees** join table, replacing the single
+   `child_id` column.
+3. `quest_definitions` needs a **windows** set (morning/afternoon/evening) plus an
+   optional due time per window.
+4. The materialiser emits one instance per (assignee × window × firing date), still
+   idempotent on the widened key, still only when the child is present.
+5. `completion_events` gains `actor_child_id` so a panel completion records which
+   profile was tapped, while `actor` stays `panel`.

design/IMPLEMENTATION-ORDER.md

@@ -0,0 +1,80 @@
+# Implementation order
+
+Written for an agent working in `code.cubecraftlabs.com/Maniacs_Mansion/NestQuest`.
+Steps 1.x change existing code and must land first; the frontend is step 4 onward.
+
+## 1. Model changes (breaking, pre-release)
+
+### 1.1 Rename `task_*` → `quest_*`
+Nothing is released (main/dev are at "first commit", version 0.1.0), so rename in place
+rather than aliasing.
+
+- `schema.py`: `task_definitions` → `quest_definitions`, `task_instances` →
+  `quest_instances`. Keep `completion_events`, `children`, `admin_users`,
+  `schedule_rules`, `presence_schedules`, `presence_overrides`.
+- `db.py` / `store.py`: rename DAO methods and any SQL literals.
+- `const.py`: no table names live there today; keep it that way.
+- `tests/test_schema.py`, `tests/test_store.py`, `tests/test_db.py`: update expectations.
+- **Migration note:** the versioned migration runner has no released version to upgrade
+  from. Bump the schema version, and make migration 1 create the `quest_*` tables
+  directly. If any dev machine already holds a `nestquest.db` with `task_*` tables, the
+  runner should detect the legacy names and `ALTER TABLE ... RENAME TO` before applying
+  the widened index — a dev-only path, worth ~20 lines and a test.
+
+### 1.2 Widen the instance key
+Unique index becomes `(definition_id, child_id, due_date, window)`. Materialisation stays
+idempotent on that tuple. Add a test for the twice-daily case (one definition, two windows,
+one child, one date → two rows) and the shared case (one definition, three assignees, one
+window → three rows).
+
+### 1.3 Multi-assignee definitions
+Add `quest_definition_assignees(definition_id, child_id)`. Drop the single `child_id`
+column on the definition. The "exactly one assigned child" rule in GLOSSARY.MD no longer
+holds — CTXD has been updated.
+
+### 1.4 Windows
+Add `quest_definition_windows(definition_id, window, due_time)` with
+`window ∈ ('morning','afternoon','evening')`. Window clock ranges are fixed for now:
+morning ≤ 11:59, afternoon 12:00–17:00, evening 17:00–21:00. Store the ranges in
+`const.py` so they are configurable later.
+
+### 1.5 `actor_child_id` on completion events
+Nullable int. Set for panel completions, null for admin ones. Still append-only.
+
+## 2. Engines and materialisation
+Unchanged in intent: pure recurrence engine, pure presence engine with anchor-date
+arithmetic, daily materialiser over `horizon_days` at `day_rollover_time`. Only the
+instance fan-out changes (assignees × windows).
+
+## 3. Services, permissions, entities
+Implement the service table in `ENTITIES-AND-SERVICES.md` §2 behind the permission
+decorator, then the sensors and binary sensors in §1, then the four events in §3.
+`complete_quest` is the only service a non-admin context may call.
+
+## 4. Frontend groundwork
+1. Create `custom_components/nestquest/www/`.
+2. Bundle fonts as woff2: Nunito 400/600/700/800; Cinzel 600/700/900; Cinzel Decorative
+   700/900. Declare `@font-face` with `font-display: swap` in a shared
+   `nestquest-fonts.css`. No CDN — the panel may be offline.
+3. Copy `design/tokens/nestquest-panel-tokens.css` and
+   `design/tokens/nestquest-admin-tokens.css` in as the cards' `:host` blocks.
+4. Register the three cards with `customCards` and ship editors later; hand-written YAML
+   is fine for v1.
+
+## 5. Cards, in this order
+1. `nestquest-party-board-card` (screen 1a) — read-only, proves the entity payload.
+2. `nestquest-quest-log-card` (1b) — read-only first, no completion.
+3. Confirm dialog + `complete_quest` (1j) with optimistic seal and revert-on-failure.
+4. Quest complete screen (1c) driven by `nestquest_child_day_complete`.
+5. Idle return (40 s) and the documented TouchHub Auto-Return constraint.
+6. `nestquest-admin-card`: Today (1d) → Definitions + sheet (1e) → Schedule (1f) →
+   History + CSV (1g) → Presence override (1i).
+
+## 6. Before shipping
+- `use_x_frame_options: false` is required for TouchHub embedding — document the
+  clickjacking trade-off next to the setting, per D-006.
+- Verify no NestQuest control in the dock strip is tappable.
+- Verify the kiosk HA user is absent from the admin allowlist, and that
+  `uncomplete_quest` denies it with a logged denial.
+- Empty and error states are still unspecified (see DESIGN-HANDOFF "Open questions").
+  Do not ship a card that renders a blank parchment.

design/PANEL-EMPTY-STATES.md

@@ -0,0 +1,104 @@
+# Panel empty & error states — design addendum
+
+Closes the gap DESIGN-HANDOFF.md lists under "Open questions": *"Empty and error
+states are unspecified by request (child with no quests, everyone away, integration
+unconfigured, DB unreachable). Panel must not render a blank parchment — decide
+before shipping the card."*
+
+All decisions below reuse PANEL-SPEC.md's approved aesthetic — parchment ground,
+double frame, dock, panel tokens, no text below 22px, no alpha-muted ink — and add
+one shared component per card: a **notice panel** (radius 20px, `--nq-p-card-panel`,
+2px `--nq-p-panel-border`, `--nq-p-panel-shadow`, centred icon + headline + body).
+The frame, wordmark row, kicker and dock always render; only the content area
+changes. **No state renders a blank parchment.**
+
+## 1. What the data can say
+
+The cards read `sensor.nestquest_<child>_quests_due_today` (plus siblings). One of
+four things comes back, and the card must tell them apart:
+
+| Backend condition | What the card sees | Card's interpretation |
+|---|---|---|
+| Resolving (DB fine) | numeric state + attributes (`child_name`, `present`, `instances`) | normal, all states below |
+| Integration not configured | entity does not exist at all | **not set up** |
+| Backend unreachable (DB locked, refresh failed) | state `unavailable` | **records unreachable** |
+| Child deactivated / absent from snapshot | state `unknown` | **records unreachable** (same panel voice: the records do not answer) |
+
+An away child (presence `present: false`, from the due-sensor attributes with the
+presence binary sensor as fallback) is *not* an error: it is a first-class panel
+state ("On travels"). Away children get no instances (materialiser skips them), so
+away is detected from the presence flag, never from a zero quest count.
+
+## 2. Quest log — state priority
+
+`nestquest-quest-log-card` resolves exactly one state, in this order:
+
+1. **No adventurer in the path** (direct navigation to a URL with no child slug —
+   misconfigured `board_path`/`quest_log_path`) → notice *"No adventurer chosen"*,
+   body *"Open The Party and tap your crest to open your quest log."*
+2. **Not set up** (entity missing) → notice *"NestQuest is not set up yet"*, body
+   *"A parent needs to finish setting up NestQuest."*
+3. **Records unreachable** (`unavailable`/`unknown`) → notice *"The records cannot
+   be reached"*, body *"The party's records are quiet right now. NestQuest will
+   return shortly."*
+4. **Away** (present flag false) → away notice: dashed muted panel (the away-plate
+   gradient), tent icon, *"<Name> is on travels"*, *"The quest log unlocks when
+   they return."* and, when `next_present` is known, *"Returns <weekday>, <Mon D>"*.
+   Direct navigation is the one path that can reach this state (the board's away
+   plate is not tappable); the log answers it honestly instead of showing an empty
+   column set. Header renders with the crest in away colours and the sub line
+   `… · On travels`; the remaining-count block is hidden (it is meaningless while
+   away).
+5. **No quests today** (present, due = 0) → all-clear notice, sun icon, *"No quests
+   today"*, body *"Nothing was posted for today, <Name>. Enjoy the day's rest!"* —
+   never three bare empty columns. The header and remaining block stay (0 quests
+   left, party progress), so the log still reads like the log.
+6. **All quests done** (due > 0, remaining = 0) → the fallback celebration that
+   shows until the 1c quest-complete screen takes over: centred wax-seal mark (the
+   `--nq-p-seal` tokens at 78px, check glyph, −6°) with headline *"Quest complete"*
+   — the same phrase screen 1c uses — and body *"Every quest is claimed, <Name>.
+   The seal is set for today. Returning to The Party shortly."* The idle return
+   (§3.5) is what actually navigates back; 1c remains the designed takeover.
+7. **Normal** → the three-window column layout of PANEL-SPEC §3.1 unchanged. A
+   window with no quests still renders its head alone, exactly as the spec says.
+
+Notices sit in the columns' content area, vertically centred. Error notices (states
+1–3) replace the header entirely — there is no honest name to headline when the
+records do not answer — while states 4–6 keep the full header.
+
+## 3. Party board — state priority
+
+`nestquest-party-board-card` resolves per configured child, then at board level:
+
+1. **No children configured** (`child_order` empty) → board notice *"NestQuest is
+   not set up yet"*, body *"A parent needs to finish setting up NestQuest before
+   the party can gather."*
+2. **Every configured child unresolvable** → one board notice instead of a grid of
+   broken plates: *"NestQuest is not set up yet"* when the entities are missing,
+   *"The records cannot be reached"* when they answer `unavailable`/`unknown`.
+3. **Partial** (some children resolve, some do not) → the board still renders the
+   resolving plates; an unresolvable child renders a muted, dashed plate in the
+   away geometry with a compass icon and the pill label **"Unknown"**, progress
+   line `—`, empty bar, **not tappable**. It must not claim "Home today" (0 of 0)
+   and must not lie "On travels": the records simply do not say.
+4. **Normal** → the plates grid of PANEL-SPEC §2 unchanged (present + away plates).
+
+The hint line ("Tap your crest…") is hidden in board-level notice states — there
+is nothing to tap.
+
+## 4. Shared rules
+
+- **Never a blank parchment.** Every render path emits the frames, wordmark,
+  kicker, dock, and either content or a notice panel. The dock already degrades to
+  date + time when weather is unset (PANEL-SPEC §2.3); that behaviour is unchanged.
+- **Notice panel type scale:** icon 46px, headline 40px/700 Cinzel
+  (`--nq-p-font-heading`, `--nq-p-ink`), body 24px/600 Nunito
+  (`--nq-p-ink-secondary`), `role="status"` so assistive tech announces it.
+- **Tone.** The panel speaks tabletop (PANEL-SPEC vocabulary) but never lies: an
+  error says the records cannot be reached, not that everything is fine. Error
+  copy names the actor who can fix it (a parent) or promises the return of the
+  data — no stack traces, no entity IDs.
+- **No interaction in error/away states.** No confirm dialog, no idle return
+  changes, no navigation attempts. Notices are static.
+- Both cards implement the same resolution rules, so the board and the log never
+  disagree about whether the integration is up.

design/PANEL-SPEC.md

@@ -0,0 +1,170 @@
+# Panel spec — kids' DAKOS wall panel
+
+Screens `1a`, `1b`, `1j`, `1c` of the mockups. Two cards:
+`nestquest-party-board-card` (§2) and `nestquest-quest-log-card` (§3–5).
+
+## 1. Frame and constraints
+
+- **Canvas** 1920×1080, landscape, fixed. No scrolling — content must fit. Every screen in
+  the mockups measures exactly 1920×1080 with no overflow; keep it that way.
+- **Viewing distance** ~3 ft. **No text below 22px.** Meta lines are 22px/600 Nunito;
+  quest titles 30px/700 Cinzel; section heads 32px.
+- **Contrast** every ink token is ≥4.5:1 on parchment. Do not introduce alpha-muted text.
+- **Ground** `--nq-p-parchment` + `--nq-p-vignette`, CSS only, no image assets.
+- **Double frame** inset 26px (`--nq-p-frame-outer`, radius 14px) and inset 36px
+  (`--nq-p-frame-inner`, radius 8px), both `pointer-events: none`.
+- **Dock** bottom strip, 84px, inset 46px, radius 14px, `--nq-p-dock-bg`. Weather only.
+  **Nothing in the dock is tappable** (D-006).
+- **No login.** Every action comes from the kiosk HA user; the kiosk user is never in the
+  admin allowlist.
+
+## 2. The Party — attract state (1a)
+
+Default view on the wall. Layout top to bottom:
+
+1. **Wordmark row** at y=64. Rule · d20 hexagon · `NestQuest` (66px/900 display, brand
+   gradient via `background-clip: text`) · d20 · rule. d20 marks are 34px hexagons
+   (`clip-path: polygon(50% 0, 93% 25%, 93% 75%, 50% 100%, 7% 75%, 7% 25%)`) filled with
+   the brand gradient, numeral 15px/700 Cinzel.
+2. **Kicker** `The Party · <weekday>, <Month D>` — 21px/600 Cinzel, tracking .30em, uppercase.
+3. **Adventurer plates**, 3-up grid, 56px gap, page inset 110px, top y=262. One plate per
+   child returned by the party sensor, in configured order.
+4. **Hint line** `Tap your crest to open your Quest Log`, 27px/600 Nunito, y≈930.
+5. **Dock.**
+
+### 2.1 Adventurer plate (present)
+
+Radius 20px, `--nq-p-card-panel`, 2px `--nq-p-panel-border`, `--nq-p-panel-shadow`,
+padding 44px 28px 40px, contents centred, 26px gap. **The whole plate is the tap target**
+(≥188px wide, ≥600px tall — far above minimum).
+
+- **Crest** 188×214, shield via `clip-path: polygon(0 0, 100% 0, 100% 62%, 50% 100%, 0 62%)`,
+  `--nq-p-crest`, inset ring `inset 0 0 0 4px rgba(255,255,255,.22)`, child's initial
+  82px/700 display in white.
+- **Name** 48px/700 Cinzel, `--nq-p-ink`, tracking .02em.
+- **Presence pill** radius 9999px, `#e8f4ea` on `rgba(22,120,60,.35)`, `check-circle` 22px
+  `#157a3c`, label `Home today` 19px/600 Cinzel uppercase `#146b36`.
+- **Progress line** `N of M quests claimed` 26px/700 Cinzel `--nq-p-ink-secondary`.
+- **Progress bar** full width, 16px, radius 9999px, track `rgba(92,62,26,.18)` with 1px
+  border, fill `--nq-brand-gradient-h`.
+
+### 2.2 Adventurer plate (away)
+
+Same geometry, muted: `linear-gradient(#f2ecdd, #e6dcc6)`, **2px dashed** border, no lift
+shadow. Crest uses `--nq-p-crest-away`; initial stays **full-opacity white** (never alpha).
+Name in `--nq-p-ink-away`. Pill: `tent` icon, label `On travels`, neutral fill. Progress
+line reads `Returns <weekday>, <Mon D>`; empty progress track, no fill. **Not tappable** —
+the plate must not navigate, since the child has no instances.
+
+### 2.3 Dock
+
+`cloud-sun` 40px · temperature 38px/800 Nunito `--nq-p-dock-ink` · 1px divider ·
+condition + high/low 26px/600 `--nq-p-dock-ink-secondary` · divider · one short forecast
+phrase. All read from the configured `weather_entity`; if unset, render the dock with date
+and time only rather than removing it (the strip is part of the frame).
+
+## 3. Quest Log (1b)
+
+Reached by tapping a present crest. Header at y=56, page inset 62px:
+
+- Small crest 96×110 (initial 44px/700 display).
+- Title `<Name>'s Quest Log` 56px/700 display.
+- Sub `<weekday>, <Month D> · N of M claimed` 20px/600 Cinzel, tracking .24em, uppercase.
+- **Remaining block** right-aligned: radius 14px panel, d20 mark 44px with the remaining
+  count, `N quests left` 28px/700 Cinzel, and a party line
+  `Party progress · X of Y today` 22px/600 Nunito.
+
+### 3.1 Window columns
+
+Three equal columns, 34px gap, top y=236, one per window — **Morning** (until 11:59 AM),
+**Afternoon** (12:00–5:00 PM), **Evening** (5:00–9:00 PM). Column head: icon
+(`sunrise` / `sun` / `moon`) 34px, name 32px/700 Cinzel, sub-label 21px/600 Cinzel
+uppercase with the window's clock range, right-aligned `done/total` 26px/700 Cinzel,
+14px bottom padding, `--nq-p-rule` underline.
+
+Cards stack at `--nq-p-quest-gap` (24px). Order within a column: **incomplete first,
+sealed below**. A window with no quests renders its head and nothing else — do not
+collapse the column, the three-column rhythm is the layout.
+
+### 3.2 Quest card — open
+
+`--nq-p-quest-min-height` 116px, radius 12px, `--nq-p-card-open`, 1px
+`--nq-p-card-border`, `--nq-p-card-shadow`, padding 22px, 22px gap, row layout:
+
+1. **Icon tile** 64×64, radius 10px, `--nq-p-icon-tile`, Lucide glyph 34px white.
+2. **Text** title 30px/700 Cinzel `--nq-p-ink`; meta 22px/600 Nunito
+   `--nq-p-ink-secondary` reading `Due by <h:mm A>`. If past due:
+   `Overdue · due <h:mm A>` in 22px/700 Cinzel uppercase, tracking .10em,
+   `--nq-p-ink-late`.
+3. **Complete button** `--nq-p-button-height` 72px × min 150px, radius 10px,
+   `--nq-brand-gradient`, `check` 30px + `Complete` 24px/700 Cinzel white,
+   `box-shadow: 0 3px 0 rgba(40,20,60,.35)`.
+
+Both the card body and the button open the confirm dialog (§4). Press feedback:
+`scale(.98)`, `--nq-dur-micro`.
+
+### 3.3 Quest card — sealed
+
+`--nq-p-card-done`, `opacity: .82`, no shadow, **not tappable**. Icon tile
+`--nq-p-icon-tile-done` with the glyph in `--nq-p-ink-secondary`. Title 30px/700 Cinzel
+`--nq-p-ink-muted` with `text-decoration: line-through`. Meta reads
+`Claimed <h:mm A>` 22px/600 Nunito `--nq-p-ink-secondary`.
+
+**Wax seal** `--nq-p-seal-size` 78px circle, `--nq-p-seal`, `--nq-p-seal-shadow`,
+`check` 38px in `rgba(255,235,235,.95)`, absolutely positioned `right: 16px; top: -12px`,
+rotated a few degrees — **vary the rotation per card** (−9°, +6°, −4° in the mockup) so the
+board looks stamped by hand, not templated. Entrance: fade + `scale(1.15 → 1)`,
+`--nq-dur-base`, `--nq-ease-out`.
+
+### 3.4 Party roll-up
+
+An optional dashed panel in the afternoon column: label `Party roll-up` 18px/600 Cinzel
+uppercase, body 23px/600 Nunito `--nq-p-ink-secondary` — one or two sentences on the other
+children ("Jordyn has finished her log. Chloe is on travels until Sunday."). Read-only.
+
+### 3.5 Idle return
+
+40 s with no touch → navigate back to the party board view. Reset on any pointer or touch
+event. The card owns this; TouchHub Auto-Return must be set longer than 40 s.
+
+## 4. Complete confirm (1j)
+
+Modal over the dimmed log — scrim `rgba(30,20,10,.62)` over the live board.
+
+Dialog 1000px wide at `top: 196px; left: 460px`, radius 20px, parchment panel with 3px
+`rgba(92,62,26,.5)`, `box-shadow: 0 26px 60px rgba(20,10,0,.5)`, padding 64px 68px 56px.
+
+- Header row: 104px icon tile (radius 12px, brand gradient, glyph 56px) · window kicker
+  21px/600 Cinzel uppercase tracking .24em · quest title 58px/700 display.
+- Body 32px/600 Nunito `#3f2f1c`: `Mark this quest complete? Once the seal is set, only a
+  parent can undo it.`
+- Buttons, 24px gap, both `--nq-p-confirm-button` 108px tall:
+  **Not yet** flex 1, `rgba(92,62,26,.1)` with 2px border, `x` 34px + 30px/700 Cinzel;
+  **Complete** flex 2, brand gradient, `check` 38px + 32px/700 Cinzel white.
+- Dialog enters with fade + `scale(.96 → 1)`, `--nq-dur-modal`, `--nq-ease-out`.
+- Dismiss: **Not yet**, scrim tap, or 15 s of no input.
+
+On confirm, call the completion service optimistically, stamp the seal, and re-sort the
+column. On service failure, revert the card and surface a single-line parchment toast.
+
+## 5. Quest complete (1c)
+
+Shown when the last instance for a child's day is completed; auto-returns to the board
+after 12 s (countdown line `Returning to The Party in N seconds`, 25px/600 Nunito).
+
+- Large seal 168px at y=96 (`check` 86px), rotated −6°, `0 10px 24px rgba(60,10,20,.42)`.
+- `Quest complete` 86px/900 display, brand-gradient text fill.
+- Sub 34px/600 Nunito `--nq-p-ink-secondary`, max-width 1000px, centred, `text-wrap: pretty`:
+  names the child, the date, and how the day went.
+- **Stat blocks** 4-up at y=540, inset 200px, 26px gap: radius 16px parchment panels,
+  numeral 58px/900 Cinzel, label 17px/600 Cinzel uppercase tracking .14em —
+  `Quests claimed`, `On time`, `Late`, `The Party` (household X/Y).
+- Dock switches to the evening variant (`cloud-moon`).
+
+## 6. Accessibility and input
+
+- Minimum tap target on this surface is the quest card itself (116px) and the 72px button;
+  nothing interactive is smaller than 72px.
+- 24px between adjacent tap targets so a stray finger cannot claim the wrong quest.
+- No hover states — this is a touch-only surface. Provide `:active` feedback only.
+- No animation loops. Entrances only, per the CubeCraft motion rules.

design/tokens/nestquest-admin-tokens.css

@@ -0,0 +1,76 @@
+/* ============================================================
+   NestQuest — Parent admin card tokens
+   Surface: phone, 390x844 reference. Plain CubeCraft styling,
+   no tabletop treatment, plain domain words in the UI.
+   Scope on the card host: nestquest-admin-card.
+   Derived from the approved mockups (admin screens 1d-1i).
+   Two densities were built; COMPACT is the default. Flip
+   --nq-a-density-* to the roomy values for the alternative.
+   ============================================================ */
+
+:host {
+  /* ── Brand + neutrals (CubeCraft tokens, verbatim) ─────── */
+  --nq-brand-blue:        #3B3AB8;
+  --nq-brand-purple:      #A035CC;
+  --nq-brand-gradient:    linear-gradient(135deg, var(--nq-brand-blue), var(--nq-brand-purple));
+  --nq-brand-gradient-h:  linear-gradient(90deg,  var(--nq-brand-blue), var(--nq-brand-purple));
+
+  --nq-a-page:            #F4F4F6;
+  --nq-a-surface:         #FFFFFF;
+  --nq-a-surface-subtle:  #FAFAFA;
+  --nq-a-selected:        #EBEBF8;   /* row being edited */
+  --nq-a-border:          #E4E4EA;
+  --nq-a-divider:         #EDEDF1;
+
+  --nq-a-ink:             #18181D;
+  --nq-a-ink-secondary:   #52525E;
+  --nq-a-ink-tertiary:    #70707E;   /* inactive rows, unselected nav icons */
+
+  --nq-a-success:         #15803D;
+  --nq-a-danger:          #DC2626;
+  --nq-a-danger-strong:   #B91C1C;
+  --nq-a-danger-bg:       #FEE2E2;
+  --nq-a-warning-ink:     #92400E;
+  --nq-a-warning-ink-2:   #78350F;
+  --nq-a-warning-bg:      #FEF3C7;
+  --nq-a-warning-border:  rgba(217,119,6,.35);
+  --nq-a-info-bg:         #DBEAFE;
+  --nq-a-info-ink:        #1E3A8A;
+  --nq-a-info-icon:       #1D4ED8;
+  --nq-a-reversal:        #7D28A0;   /* un-complete events in history */
+
+  /* ── Type ─────────────────────────────────────────────── */
+  --nq-a-font:            Nunito, system-ui, sans-serif;
+  --nq-a-size-screen:     24px;  /* 800, screen title */
+  --nq-a-size-hero:       32px;  /* 800, roomy "8 of 12 done" */
+  --nq-a-size-card-title: 19px;  /* 800, roomy child card */
+  --nq-a-size-stat:       22px;  /* 800, compact stat number */
+  --nq-a-size-row:        13.5px;/* 700, list row title */
+  --nq-a-size-meta:       11px;  /* 600, row meta */
+  --nq-a-size-label:      10px;  /* 700, uppercase field label */
+  --nq-a-track-label:     .10em;
+
+  /* ── Density: COMPACT (default) ───────────────────────── */
+  --nq-a-density-page-pad:   14px 16px 92px;  /* bottom clears the 70px tab bar */
+  --nq-a-density-gap:        10px;
+  --nq-a-density-card-pad:   13px;
+  --nq-a-density-row-pad:    11px 13px;
+  --nq-a-density-radius:     8px;
+  --nq-a-density-shadow:     none;
+  /* Density: ROOMY — page-pad 18px 20px 92px; gap 16px;
+     card-pad 18px; radius 12px; shadow 0 4px 12px rgba(0,0,0,.06) */
+
+  /* ── Metrics ──────────────────────────────────────────── */
+  --nq-a-tabbar-height:   70px;   /* + 12px safe-area padding */
+  --nq-a-tap-min:         44px;   /* every row/control clears this */
+  --nq-a-radius-pill:     9999px;
+  --nq-a-radius-sheet:    20px 20px 0 0;
+  --nq-a-sheet-shadow:    0 -8px 28px rgba(9,9,11,.18);
+  --nq-a-progress-height: 6px;    /* 8px roomy, 10px hero */
+
+  /* ── Motion ───────────────────────────────────────────── */
+  --nq-ease-out:          cubic-bezier(0, 0, .2, 1);
+  --nq-dur-micro:         120ms;
+  --nq-dur-base:          200ms;
+  --nq-dur-modal:         350ms;
+}

design/tokens/nestquest-panel-tokens.css

@@ -0,0 +1,96 @@
+/* ============================================================
+   NestQuest — Kids' panel card tokens
+   Surface: DAKboard DAKOS wall panel, 1920x1080 landscape,
+   viewed from ~3 ft, no login, read/complete only.
+   Scope these on the card host: nestquest-quest-log-card,
+   nestquest-party-board-card.
+   Derived from the approved mockups (panel screens 1a, 1b, 1c, 1j).
+   ============================================================ */
+
+:host {
+  /* ── Parchment ground ─────────────────────────────────── */
+  --nq-p-parchment-top:      #f0e4c7;
+  --nq-p-parchment-bottom:   #ddcca3;
+  --nq-p-parchment: radial-gradient(ellipse at 25% 10%, rgba(255,255,255,.5), transparent 55%),
+                    radial-gradient(ellipse at 85% 90%, rgba(120,86,44,.28), transparent 60%),
+                    repeating-linear-gradient(93deg, rgba(150,115,70,.05) 0 2px, transparent 2px 6px),
+                    repeating-linear-gradient(2deg, rgba(150,115,70,.04) 0 3px, transparent 3px 7px),
+                    linear-gradient(var(--nq-p-parchment-top), var(--nq-p-parchment-bottom));
+  --nq-p-vignette:           inset 0 0 200px rgba(80,52,20,.35);
+
+  /* Card surfaces sitting on parchment */
+  --nq-p-card-open:          linear-gradient(#fdf7e6, #f2e7c9);   /* incomplete quest */
+  --nq-p-card-done:          linear-gradient(#f0e8d3, #e6dcc2);   /* sealed quest */
+  --nq-p-card-panel:         linear-gradient(#fcf6e6, #f1e6ca);   /* adventurer plate, stat block */
+  --nq-p-card-border:        rgba(120,88,48,.38);
+  --nq-p-panel-border:       rgba(92,62,26,.40);
+  --nq-p-card-shadow:        0 3px 0 rgba(120,88,48,.20), inset 0 1px 0 rgba(255,255,255,.70);
+  --nq-p-panel-shadow:       0 6px 0 rgba(92,62,26,.18), inset 0 2px 0 rgba(255,255,255,.70);
+  --nq-p-frame-outer:        2px solid rgba(92,62,26,.45);
+  --nq-p-frame-inner:        1px solid rgba(92,62,26,.28);
+  --nq-p-rule:               2px solid rgba(92,62,26,.35);
+
+  /* ── Ink (all values >= 4.5:1 on parchment) ───────────── */
+  --nq-p-ink:                #2b1f14;   /* titles, quest names */
+  --nq-p-ink-secondary:      #5c452a;   /* meta, window labels, counts */
+  --nq-p-ink-muted:          #6f6455;   /* sealed quest titles only */
+  --nq-p-ink-away:           #4d4433;   /* away adventurer name */
+  --nq-p-ink-late:           #8f1526;   /* overdue line */
+
+  /* ── Brand (CubeCraft, toned down: accents only) ──────── */
+  --nq-brand-blue:           #3B3AB8;
+  --nq-brand-purple:         #A035CC;
+  --nq-brand-gradient:       linear-gradient(135deg, var(--nq-brand-blue), var(--nq-brand-purple));
+  --nq-p-icon-tile:          var(--nq-brand-gradient);            /* open quest icon tile */
+  --nq-p-icon-tile-done:     rgba(92,62,26,.16);
+  --nq-p-crest:              var(--nq-brand-gradient);
+  --nq-p-crest-away:         linear-gradient(135deg, #6b6b7a, #7a7286);
+
+  /* ── Wax seal (completed marker) ──────────────────────── */
+  --nq-p-seal:               radial-gradient(circle at 35% 30%, #a8283a, #6d1322);
+  --nq-p-seal-shadow:        0 4px 10px rgba(60,10,20,.40), inset 0 0 0 4px rgba(255,255,255,.14);
+  --nq-p-seal-size:          78px;   /* 168px on the quest-complete screen */
+
+  /* ── Dock (bottom strip, non-interactive) ─────────────── */
+  --nq-p-dock-bg:            rgba(43,31,20,.90);
+  --nq-p-dock-ink:           #f7efdb;
+  --nq-p-dock-ink-secondary: #d8c9a6;
+  --nq-p-dock-divider:       rgba(233,220,189,.30);
+  --nq-p-dock-height:        84px;
+
+  /* ── Type ─────────────────────────────────────────────── */
+  --nq-p-font-display:       'Cinzel Decorative', Cinzel, serif;  /* NestQuest, names, Quest complete */
+  --nq-p-font-heading:       Cinzel, serif;                       /* section heads, quest titles, numerals */
+  --nq-p-font-body:          Nunito, system-ui, sans-serif;       /* meta lines, dock */
+
+  --nq-p-size-hero:          86px;   /* 900 weight, "Quest complete" */
+  --nq-p-size-wordmark:      66px;   /* 900 weight */
+  --nq-p-size-title:         56px;   /* 700, "Declan's Quest Log" */
+  --nq-p-size-name:          48px;   /* 700, adventurer name */
+  --nq-p-size-section:       32px;   /* 700, Morning / Afternoon / Evening */
+  --nq-p-size-quest:         30px;   /* 700, quest title */
+  --nq-p-size-body:          22px;   /* 600 Nunito, meta — PANEL MINIMUM */
+  --nq-p-size-label:         21px;   /* 600 Cinzel, uppercase, tracked */
+  --nq-p-track-label:        .14em;
+  --nq-p-track-kicker:       .30em;
+
+  /* ── Metrics: touch ───────────────────────────────────── */
+  --nq-p-quest-min-height:   116px;  /* whole card is the tap target */
+  --nq-p-quest-gap:          24px;   /* separation between tap targets */
+  --nq-p-quest-pad:          22px;   /* padding inside a quest card */
+  --nq-p-tile-size:          64px;   /* quest icon tile */
+  --nq-p-button-height:      72px;   /* "Complete" button on a quest card */
+  --nq-p-button-min-width:   150px;
+  --nq-p-confirm-button:     108px;  /* confirm dialog buttons */
+  --nq-p-radius-card:        12px;
+  --nq-p-radius-panel:       20px;
+  --nq-p-radius-pill:        9999px;
+  --nq-p-page-inset:         62px;
+  --nq-p-frame-inset:        26px;
+
+  /* ── Motion (CubeCraft easing) ────────────────────────── */
+  --nq-ease-out:             cubic-bezier(0, 0, .2, 1);
+  --nq-dur-micro:            120ms;
+  --nq-dur-base:             200ms;
+  --nq-dur-modal:            350ms;
+}

docs/ARCHITECTURE.md

@@ -0,0 +1,203 @@
+# NestQuest Architecture
+
+Status: approved direction (2026-09-21). This document supersedes the
+single-process design implied by Features 01–14, in which the Home Assistant
+integration owned the database and the parent admin surface was planned as a
+Lovelace card inside Home Assistant.
+
+## 1. Why this changed
+
+The original design put everything inside the Home Assistant integration: the
+SQLite database, the business logic, the kid panel cards, and (planned) the
+parent admin card. Three problems surfaced:
+
+1. **The panel needed hand configuration.** Standing up the kid panel required
+   hand-writing card YAML (`child_order`, `quest_log_path`, `board_path`) and
+   hand-creating a Lovelace dashboard. A fresh install rendered nothing.
+2. **The admin surface fought Home Assistant.** The admin design
+   (`design/ADMIN-SPEC.md`) is drawn at 390×844 — it is a phone app. Trapping it
+   inside a Lovelace card meant fighting HA's UI constraints for a mobile-first
+   experience.
+3. **Data was locked to one process.** A standalone admin web app cannot reach a
+   SQLite file inside Home Assistant's config directory.
+
+The re-imagined design keeps the panel in Home Assistant (TouchHub loads an HA
+dashboard), moves data ownership to a standalone API service, and promotes the
+admin surface to a standalone mobile-first PWA.
+
+## 2. Target architecture
+
+```
+ DAKboard TouchHub
+       │  (loads an HA dashboard URL)
+       ▼
+ HA box                                        API box
+ ┌───────────────────────────────┐            ┌───────────────────────────────────┐
+ │ Lovelace panel dashboard      │            │ reverse proxy (TLS)               │
+ │  ├ nestquest-party-board-card │  service   │  ├ /api/v1/panel/*   LAN-only     │
+ │  └ nestquest-quest-log-card   │  token     │  └ /api/v1/admin/*   public       │
+ │                               │ ─────────▶ │ FastAPI (imports core/)           │
+ │ NestQuest integration         │            │  └ SQLite (owned here)            │
+ │  (thin client, no database)   │ ◀───────── │ Authentik (OIDC)                  │
+ │  sensors + HA bus events      │  SSE       └───────────────────────────────────┘
+ └───────────────────────────────┘                          ▲
+                                            PWA ───────────┘
+                                  https://nestquest.cubecraftlabs.com
+```
+
+One owner of the data (the API). Two clients (the HA integration, the PWA).
+
+## 3. Data ownership
+
+**The API service is the only writer.** The HA integration never opens the
+database; it reads a snapshot and posts completions. This removes the
+two-writer problem entirely.
+
+- **Storage:** SQLite on the API box. Single household, trivial concurrency,
+  and the existing schema, migrations, and DAO tests are already SQLite. Postgres
+  buys nothing at this scale.
+- **Schema:** unchanged. The cutover from the current HA-hosted database is a
+  file copy — same schema, same migration version.
+- **Backups:** continuous replication (e.g. Litestream) plus a proven restore.
+  A configured-but-untested backup is not a backup.
+
+## 4. Authentication: two planes
+
+The kid panel and the admin PWA have opposite trust levels, so they use
+separate credentials and separate network exposure.
+
+### Panel plane (machine)
+
+- **Credential:** a static service token.
+- **Exposure:** `/api/v1/panel/*` is reachable **only from the LAN**.
+- **Grants:** read the snapshot, and the single open write — complete a quest as
+  `actor: panel` with the tapped `actor_child_id`.
+- **Refused:** admin routes reject the service token outright, not merely as a
+  non-admin. The internet cannot reach these routes at all.
+
+This preserves the original fail-closed boundary: the kiosk can complete a
+quest and nothing else.
+
+### Admin plane (human)
+
+- **Credential:** an Authentik OIDC JWT (authorization code + PKCE).
+- **Exposure:** `/api/v1/admin/*` is internet-facing behind Authentik.
+- **Grants:** everything a parent can do — definitions, assignment, presence,
+  children, un-complete, history, export, settings, regenerate.
+- **Gate:** the API validates the JWT (issuer, audience, JWKS signature, expiry)
+  and requires membership in the `nestquest-admins` group. The Authentik group
+  is the single source of truth for "who is a parent", replacing the
+  integration-side admin allowlist.
+
+## 5. Components
+
+### `core/` — domain library
+
+The extracted domain layer: schema, migrations, database access, DAOs, the pure
+recurrence and presence engines, materialization, completion, event payload
+construction, and the children/definitions/allowlist business layers. **No
+Home Assistant imports.** Consumed by both the API and (during transition) the
+integration. This is where the ~1500 existing tests live after extraction.
+
+### `api/` — NestQuest API
+
+A FastAPI service importing `core/`. Owns the database. Serves the panel and
+admin planes, validates Authentik tokens, and publishes a transition event
+stream (SSE) that the integration consumes. No business logic in route handlers.
+
+### `custom_components/nestquest/` — HA integration (client)
+
+A thin client. Polls the snapshot and builds the existing sensors; subscribes to
+the SSE stream and re-fires the four HA bus events; proxies the panel completion.
+Holds a last-good snapshot cache so a brief API outage does not blank the panel.
+Owns no database and no business logic.
+
+### `panel/` — Lovelace cards and dashboard strategy
+
+The two kid-facing Lit cards plus a dashboard strategy that generates the panel
+views at render time. Cards auto-discover children, so no `child_order` is
+required; the strategy computes navigation paths, so `quest_log_path` and
+`board_path` are not required.
+
+### `admin/` — Admin PWA
+
+A React progressive web app implementing `design/ADMIN-SPEC.md`, authenticated
+via Authentik OIDC, installable on a phone. The only admin surface.
+
+## 6. Zero-configuration panel
+
+A fresh install should show the panel with no YAML:
+
+1. **Auto-discovery.** The party-board card reads an ordered child list from a
+   household entity attribute instead of a configured `child_order`.
+2. **Dashboard strategy.** A Lovelace strategy generates a party-board view and
+   one quest-log view per child, wiring navigation between them, so paths are
+   computed rather than configured. Explicit configuration still wins if a user
+   supplies it.
+3. **Auto-registration.** The integration registers the dashboard on first
+   setup, so there is no manual dashboard step.
+
+## 7. Home Assistant surface preserved
+
+The re-imagining must not break what already works:
+
+- **Sensors:** the per-child and household sensor entity_ids and the per-child
+  instance attribute payload shape are unchanged. The panel cards and the four
+  blueprints depend on them.
+- **Events:** the four HA bus events (`nestquest_quest_completed`,
+  `nestquest_quest_uncompleted`, `nestquest_quest_missed`,
+  `nestquest_child_day_complete`) keep firing with their documented payloads.
+  They are now driven by the API's transition stream rather than by local
+  service handlers.
+- **Blueprints:** the morning summary, afternoon reminder, end-of-day report, and
+  day-complete celebration continue to work with no change.
+
+## 8. Events without an HA token on the API box
+
+The API publishes transitions on an SSE stream; the integration subscribes and
+re-fires the HA bus events locally. This deliberately avoids storing a Home
+Assistant long-lived token on the API box, which would grant full HA access.
+
+## 9. Migration phases
+
+Mapped to the Maestro features:
+
+| Phase | Feature | Outcome |
+|---|---|---|
+| 1 | 15 — Domain Core Extraction | `core/` runs with no HA imports; one implementation of the rules |
+| 2 | 16 — NestQuest API Service | Panel and admin planes served with two-plane auth |
+| 3 | 17 — API Deployment and Identity | TLS, Authentik, backups, network separation |
+| 4 | 18 — HA Integration as API Client | Integration becomes a client; entity/event surface preserved |
+| 5 | 19 — Admin PWA | Mobile-first React PWA replaces the admin card |
+| 6 | 20 — Zero-Config Panel Dashboard | Panel installs itself; navigation and animations match the mockups |
+
+Cutover: copy the existing SQLite file to the API box (same schema).
+
+## 10. Locked decisions
+
+- **API on its own box** — separate from Home Assistant.
+- **Authentik** (`https://auth.cubecraftlabs.com`) for admin identity; a
+  `nestquest-admins` group is the admin source of truth.
+- **Single household** — no tenant column, no multi-household auth.
+- **React** for the admin PWA.
+- **Drop the HA admin services** — the PWA is the only admin surface. The panel
+  completion path stays.
+- **SQLite on the API box** initially; Postgres only if multi-household ever
+  becomes real.
+
+## 11. Preserved vs. changed
+
+**Preserved:** the tested Python domain layer, the panel card designs and
+tokens, the sensor and event contract, the completion model, the append-only
+event log, the panel's fail-closed "complete only" boundary.
+
+**Changed:** data ownership moves to the API; the integration becomes a client;
+the admin card becomes a PWA; panel cards become config-free with a
+strategy-generated dashboard.
+
+**New:** the API service, Authentik-gated admin auth, the PWA, and a
+last-good-snapshot cache in the integration.
+
+**Cost:** two new deployables (the API and the PWA) and one new box. Accepted
+knowingly in exchange for a self-installing panel, an admin surface that is not
+fighting HA's UI, and a data layer with real auth in front of it.

frontend/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "nestquest-cards",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build"
+  },
+  "dependencies": {
+    "lit": "^3.3.0"
+  },
+  "devDependencies": {
+    "jsdom": "^30.1.1",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.5"
+  }
+}

frontend/src/cards/admin.ts

@@ -0,0 +1,38 @@
+import { LitElement, html, unsafeCSS } from "lit";
+import adminTokens from "../../../custom_components/nestquest/www/nestquest-admin-tokens.css?inline";
+
+import { registerCustomCard, type CardConfig, type HassLike } from "../types";
+
+export class NestQuestAdminCard extends LitElement {
+  static properties = {
+    hass: { attribute: false },
+    _config: { state: true },
+  };
+
+  static styles = [unsafeCSS(adminTokens)];
+
+  hass?: HassLike;
+  _config?: CardConfig;
+
+  setConfig(config: CardConfig): void {
+    if (!config || typeof config !== "object") {
+      throw new Error("Invalid configuration");
+    }
+    this._config = config;
+  }
+
+  getCardSize(): number {
+    return 8;
+  }
+
+  render() {
+    return html`<div>NestQuest Admin</div>`;
+  }
+}
+
+customElements.define("nestquest-admin-card", NestQuestAdminCard);
+registerCustomCard({
+  type: "nestquest-admin-card",
+  name: "NestQuest Admin",
+  description: "Parent phone view for today, tasks, schedule, and history.",
+});

frontend/src/nestquest-cards.ts

@@ -0,0 +1,13 @@
+import "./cards/party-board";
+import "./cards/quest-log";
+import "./cards/admin";
+import "./strategy";
+
+const FONTS_HREF = "/nestquest-static/nestquest-fonts.css";
+if (!document.querySelector('link[data-nq-fonts=""]')) {
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = FONTS_HREF;
+  link.dataset.nqFonts = "";
+  document.head.appendChild(link);
+}

frontend/src/strategy.ts

@@ -0,0 +1,161 @@
+import type { HassLike } from "./types";
+
+type StateObject = {
+  state: unknown;
+  attributes?: Record<string, unknown> | null;
+};
+
+type RosterEntry = {
+  name: string;
+  slug: string;
+};
+
+type View = {
+  path?: string;
+  title?: string;
+  type: string;
+  cards: Record<string, unknown>[];
+};
+
+type LovelaceConfig = {
+  views: View[];
+};
+
+type StrategyConfig = Record<string, unknown>;
+
+type StrategyClass = {
+  generate: (
+    config: StrategyConfig,
+    hass: HassLike | undefined
+  ) => Promise<LovelaceConfig>;
+};
+
+declare global {
+  interface Window {
+    customStrategies?: Record<string, StrategyClass>;
+  }
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/** The slug a discovered roster entry carries, or "" when the entry is
+ *  not an object with a non-empty slug string — the same shape check
+ *  the party board applies to the same attribute. */
+function asRosterSlug(entry: unknown): string {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return "";
+  }
+  const slug = (entry as Record<string, unknown>).slug;
+  return typeof slug === "string" ? slug.trim() : "";
+}
+
+/** The dashboard's URL path segment, used to COMPUTE the card paths the
+ *  navigation needs.  A dashboard lives at a single top-level segment
+ *  (/<url_path>), so the first pathname segment is the dashboard root —
+ *  this is where the strategy renders, and navigating back to it shows
+ *  the first view (the party board).  An explicit ``url_path`` in the
+ *  strategy configuration wins for setups that need to pin it. */
+function dashboardUrlPath(config: StrategyConfig): string {
+  const configured = asString(config.url_path).replace(/^\/+|\/+$/g, "");
+  if (configured) {
+    return configured;
+  }
+  const segment = window.location.pathname.split("/").filter(Boolean)[0];
+  return segment ?? "";
+}
+
+/** The display name a roster entry carries, or "" when it is not a
+ *  non-empty string — the roster's ``name`` field (sensor.py
+ *  ``_child_roster``), used for the quest-log view titles. */
+function asRosterName(entry: unknown): string {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return "";
+  }
+  const name = (entry as Record<string, unknown>).name;
+  return typeof name === "string" ? name.trim() : "";
+}
+
+/** The ordered child roster the integration publishes on the household
+ *  rollup (custom_components/nestquest/sensor.py — ``child_roster``,
+ *  the snapshot's sort_order, then id).  The same source the party
+ *  board's plate discovery reads, consumed here at render time so the
+ *  quest-log views exist for exactly the active children. */
+function rosterEntries(hass: HassLike | undefined): RosterEntry[] {
+  const states = hass?.states as Record<string, StateObject> | undefined;
+  const household = states?.["sensor.nestquest_household_quests_due_today"];
+  const roster = household?.attributes?.child_roster;
+  if (!Array.isArray(roster)) {
+    return [];
+  }
+  return roster
+    .map((entry) => ({ slug: asRosterSlug(entry), name: asRosterName(entry) }))
+    .filter((entry) => entry.slug.length > 0);
+}
+
+/**
+ * Zero-config NestQuest dashboard strategy (Feature 20).
+ *
+ * A dashboard configured with ``strategy: { type: custom:nestquest-party }``
+ * gets its views GENERATED at render time from the household roster: one
+ * party-board view (the dashboard root) and one quest-log view per child,
+ * ordered by the roster's sort_order.  The paths the cards navigate by are
+ * COMPUTED, not configured:
+ *
+ * - the board's ``quest_log_path`` is the dashboard root; tapping a crest
+ *   pushes ``<root>/<slug>`` (party-board.ts ``_openQuestLog``);
+ * - each log view's ``path`` IS the child's slug, so the log resolves its
+ *   child from the last pathname segment (quest-log.ts
+ *   ``childSlugFromPath``) and its ``board_path`` back to the dashboard
+ *   root (quest-log.ts ``_returnToBoard``).
+ *
+ * With zero children the board view still renders — the board card shows
+ * its own "not set up yet" notice for an empty roster, so no log views are
+ * needed.  ``url_path`` and ``weather_entity`` may still be set explicitly
+ * in the strategy configuration; everything else is derived.
+ */
+export class NestQuestPartyStrategy {
+  static async generate(
+    config: StrategyConfig,
+    hass: HassLike | undefined
+  ): Promise<LovelaceConfig> {
+    const root = `/${dashboardUrlPath(config)}`;
+    const weatherEntity = asString(config.weather_entity);
+    const boardCard: Record<string, unknown> = {
+      type: "custom:nestquest-party-board-card",
+      quest_log_path: root,
+    };
+    if (weatherEntity) {
+      boardCard.weather_entity = weatherEntity;
+    }
+    const logCard: Record<string, unknown> = {
+      type: "custom:nestquest-quest-log-card",
+      board_path: root,
+    };
+    if (weatherEntity) {
+      logCard.weather_entity = weatherEntity;
+    }
+    return {
+      views: [
+        {
+          path: "party",
+          title: "The Party",
+          type: "panel",
+          cards: [boardCard],
+        },
+        ...rosterEntries(hass).map<View>((entry) => ({
+          path: entry.slug,
+          title: entry.name
+            ? `${entry.name}'s Quest Log`
+            : `${entry.slug}'s Quest Log`,
+          type: "panel",
+          cards: [{ ...logCard }],
+        })),
+      ],
+    };
+  }
+}
+
+window.customStrategies = window.customStrategies ?? {};
+window.customStrategies["nestquest-party"] = NestQuestPartyStrategy;