Admin routes: uncomplete and regenerate

The admin plane could reverse nothing and re-materialize nothing: a
mis-tapped completion could only be fixed by hand in the database, and
a config or presence change left the household's rolling horizon
stale until the integration itself regenerated it.

- POST /api/v1/admin/instances/{id}/uncomplete appends the reversal
  through core uncomplete_instance (actor_source 'user' with the
  verified JWT's sub — D-008), so the original completed row is never
  edited or deleted and the derived state returns to open.  An actual
  reversal publishes the quest-uncompleted transition via the existing
  api.transitions helper; an already-open no-op publishes nothing and
  still answers with the honest derived state (open, or missed when
  past due).
- POST /api/v1/admin/regenerate re-materializes the rolling horizon
  through the same core path the integration uses: household (default)
  = materialize over [today, today + const.DEFAULT_HORIZON_DAYS] (the
  API config supplies no horizon knob), definition/child =
  regenerate_for_definition / regenerate_for_child after ONE DAO
  existence read each (unknown id -> 404, which the core's regenerate
  path itself does not check).  The walk is idempotent, so re-running
  never duplicates an instance.

Both handlers are thin adapters: Pydantic models carry the request
shape (scope/id pairing is the model's job), the business rules stay
in core, and the error mapping stays narrow — unknown
instance/definition/child 404, rejected argument 422, anything else
re-raises.

api/nestquest_core.py

@@ -142,13 +142,60 @@ core_quest_definitions = importlib.import_module(
 #: 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")
+
 __all__ = [
     "core",
     "core_children",
     "core_completion",
+    "core_const",
+    "core_dao_children",
+    "core_dao_presence",
+    "core_dao_rules",
     "core_db",
     "core_events",
+    "core_materialize",
     "core_migrations",
+    "core_presence",
+    "core_presence_management",
     "core_quest_definitions",
     "core_recurrence",
     "core_snapshot",

api/routes_admin.py

@@ -35,8 +35,65 @@ through the API: the core's edit path takes no assignees.  The edit
 route forwards only SUPPLIED fields (``exclude_unset``), like the
 children edit.
 
-Error mapping (every children and quest-definition route, deliberately
-narrow):
+The presence routes follow the same pattern over
+:mod:`nestquest_core.presence_management` — the ONE presence write
+layer the HA services share, so the two planes cannot drift:
+
+- ``PUT /children/{child_id}/presence-schedule`` sets (UPSERTS) the
+  child's repeating schedule: the body's ``cycle_length_weeks``,
+  ``anchor_date`` and ``pattern`` go straight into ONE
+  :class:`~nestquest_core.presence.PresenceSchedule` (the model
+  validates cycle length, the strict anchor date and the pattern's
+  week coverage at construction), the core upserts by child (setting
+  again REPLACES the one schedule a child can have) and regenerates
+  the child's future instances; the response is the STORED schedule
+  decoded back through the model.
+- ``POST /presence-overrides`` creates one date-range override: the
+  body becomes ONE :class:`~nestquest_core.presence.PresenceOverride`
+  (the model validates the dates, ``end >= start``, the real bool and
+  the note), the core creates it — rejecting a range that overlaps the
+  same child's existing override — and regenerates; the response is
+  the stored record with its ``id``.
+- ``DELETE /presence-overrides/{override_id}`` deletes one override
+  (children are never hard-deleted; overrides are deletable by
+  design) and regenerates that override's child.  It answers
+  ``{"status": "ok"}``.
+
+The uncomplete and regenerate routes (task da0226b3) follow the same
+pattern over :mod:`nestquest_core.completion` and
+:mod:`nestquest_core.materialize`:
+
+- ``POST /instances/{instance_id}/uncomplete`` reverses ONE completion:
+  the handler takes the actor from the VERIFIED JWT (``actor_source``
+  ``'user'`` with ``actor_user_id`` = the token's ``sub`` — the D-008
+  user-actor shape, so the reversal is attributed to the admin who
+  called it) and calls :func:`nestquest_core.completion.uncomplete_instance`.
+  The append-only discipline lives in the core: a reversal APPENDS an
+  ``uncompleted`` event after the original ``completed`` row — the
+  original is never edited or deleted — and the instance's derived
+  state (recomputed from the latest event) returns to ``open``.  On an
+  ACTUAL reversal (``CompletionResult.appended`` True) the route
+  publishes the ``nestquest_quest_uncompleted`` transition through
+  :func:`api.transitions.publish_quest_uncompleted` (the payload built
+  by the core builder); an already-open no-op publishes nothing.  The
+  response carries the derived ``state`` and whether THIS call
+  ``appended``.
+- ``POST /regenerate`` re-materializes the rolling horizon through the
+  same core path the integration's config/presence changes use.  The
+  body names ONE scope: ``household`` (the default —
+  :func:`nestquest_core.materialize.materialize` over
+  ``[today, today + const.DEFAULT_HORIZON_DAYS]``, the core's default
+  horizon; the API config carries no horizon knob of its own),
+  ``definition`` (:func:`nestquest_core.materialize.regenerate_for_definition`
+  — deletes the definition's open future instances and re-runs the
+  walk), or ``child``
+  (:func:`nestquest_core.materialize.regenerate_for_child`).
+  The upsert is idempotent, so re-running never duplicates an
+  instance.  The response carries the scope, the scoped id (if any)
+  and the core's upsert ``count``.
+
+Error mapping (every children, quest-definition and presence route,
+deliberately narrow):
 
 - Malformed input the body model or the path parser rejects (a missing
   or wrong-typed field, a non-integer child or definition id) is
@@ -55,10 +112,35 @@ narrow):
   ``rule_type``, a shape-missing field such as a weekly rule without
   weekdays, a malformed date, a forbidden field), a bad window name or
   due time, a rejected window or assignee list (empty, duplicate,
-  wrong-typed) — is mapped to 422: the body was well-formed JSON but
+  wrong-typed); a rejected presence schedule or override (bad cycle
+  length, a pattern not covering the cycle's weeks, a malformed or
+  inverted date range, an override overlapping the same child's
+  existing one) — is mapped to 422: the body was well-formed JSON but
   semantically invalid, the same failure class Pydantic reports.  The
   core rejects these BEFORE any write, so a 422 never leaves a
   half-applied change behind.
+- A non-existent CHILD on a presence route (setting a schedule or
+  creating an override for an unknown id) is mapped to 404 through the
+  SAME :func:`_raise_child_error` the children routes use — the
+  message reads ``child N does not exist``.  A non-existent OVERRIDE
+  on the delete route is mapped to 404 through
+  :func:`_raise_presence_override_error`, keyed on the
+  ``override_id:`` prefix the core's unknown-id error carries (the
+  same convention as the quest-definition 404).
+- The UNCOMPLETE route maps the core completion layer's unknown-
+  ``instance_id`` error (prefixed ``instance_id:``, the same
+  convention the panel complete route keys on) to 404; every other
+  core ``ValueError`` — a rejected actor shape, which a verified token
+  without a usable ``sub`` claim produces — is 422: the credential
+  authenticated but the reversal it asks for names no subject to
+  attribute.  Anything ELSE re-raises: no unexpected failure is
+  swallowed into a 4xx.
+- The REGENERATE route's only 404s are the unknown scope ids, decided
+  by ONE existence read (the definitions/children DAO ``get``) BEFORE
+  any core call — the core's regenerate path itself takes no existence
+  stance.  Every core ``ValueError`` (a rejected horizon, a malformed
+  date — unreachable from this body model, but mapped anyway) is 422;
+  anything else re-raises.
 
 PATCH edit semantics: the body model's fields are optional and only
 SUPPLIED fields are forwarded (``model_dump(exclude_unset=True)``), so
@@ -69,15 +151,24 @@ silently ignored.
 """
 from __future__ import annotations
 
-from typing import Annotated, NoReturn
+import datetime
+from typing import Annotated, Literal, NoReturn
 
 from fastapi import APIRouter, Depends, HTTPException, Request
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator, model_validator
 
+from api import transitions as api_transitions
 from api.auth import require_admin
 from api.database import DatabaseState
 from api.nestquest_core import (
     core_children,
+    core_completion,
+    core_const,
+    core_dao_children,
+    core_dao_rules,
+    core_materialize,
+    core_presence,
+    core_presence_management,
     core_quest_definitions,
     core_recurrence,
 )
@@ -294,6 +385,147 @@ class AdminQuestDefinitionActiveRequest(BaseModel):
     is_active: bool
 
 
+class AdminPresenceScheduleRequest(BaseModel):
+    """The body of ``PUT /api/v1/admin/children/{child_id}/presence-schedule``.
+
+    The shape of :class:`~nestquest_core.presence.PresenceSchedule` —
+    nothing more.  ``pattern`` maps each cycle week index (JSON object
+    keys, coerced to ints by the model) to that week's present weekdays
+    (Monday=0); every week of the cycle must be covered, which the
+    PRESENCE MODEL enforces at construction, not this shape.  A week
+    with an empty list means absent every day of that week.
+    """
+
+    cycle_length_weeks: int
+    anchor_date: str
+    pattern: dict[int, list[int]]
+
+
+class AdminPresenceScheduleResponse(BaseModel):
+    """A child's repeating presence schedule as the admin plane serializes it.
+
+    The stored schedule decoded back through
+    :meth:`nestquest_core.presence.PresenceSchedule.decode`: each
+    pattern week is the sorted list of present weekdays, and the child
+    has exactly ONE schedule (setting again replaces it).
+    """
+
+    child_id: int
+    cycle_length_weeks: int
+    anchor_date: str
+    pattern: dict[int, list[int]]
+
+
+class AdminPresenceOverrideCreateRequest(BaseModel):
+    """The body of ``POST /api/v1/admin/presence-overrides``.
+
+    The shape of :class:`~nestquest_core.presence.PresenceOverride` —
+    the strict ISO dates, the ``end_date >= start_date`` order, the
+    real ``is_present`` bool and the optional note are ALL enforced by
+    the model's constructor, which the route builds directly from this
+    body; this model only guards the SHAPE.
+    """
+
+    child_id: int
+    start_date: str
+    end_date: str
+    is_present: bool
+    note: str | None = None
+
+
+class AdminPresenceOverrideResponse(BaseModel):
+    """One presence override as the admin plane serializes it.
+
+    Mirrors
+    :class:`~nestquest_core.dao_presence.PresenceOverrideRecord` — the
+    ``id`` is the handle the DELETE route takes.
+    """
+
+    id: int
+    child_id: int
+    start_date: str
+    end_date: str
+    is_present: bool
+    note: str | None
+
+
+class AdminUncompleteResponse(BaseModel):
+    """The result of ``POST /api/v1/admin/instances/{id}/uncomplete``.
+
+    ``state`` is the instance's derived state AFTER the reversal —
+    ``open``, or ``missed`` when it is past due — and ``appended``
+    reports whether THIS call appended the reversal event (``False``
+    for an already-open no-op).
+    """
+
+    instance_id: int
+    state: str
+    appended: bool
+
+
+class AdminRegenerateRequest(BaseModel):
+    """The body of ``POST /api/v1/admin/regenerate``.
+
+    ONE scope per request: ``household`` (the default) re-materializes
+    every active definition over the rolling horizon; ``definition``
+    and ``child`` scope the rebuild to one id.  The model enforces the
+    scope/id pairing so the handler never has to guess: an id without
+    its scope, a scope without its id, or a zero/negative id is a
+    validation error (422) before any handler code runs.
+    """
+
+    scope: Literal["household", "definition", "child"] = "household"
+    definition_id: int | None = None
+    child_id: int | None = None
+
+    @field_validator("definition_id", "child_id")
+    @classmethod
+    def _positive(cls, value: int | None) -> int | None:
+        """Reject zero and negative ids with a validation error."""
+        if value is not None and value < 1:
+            raise ValueError(
+                "definition_id and child_id must be positive integers"
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _scope_matches_ids(self) -> "AdminRegenerateRequest":
+        """Reject an id that does not belong to the requested scope."""
+        if self.scope == "household":
+            if self.definition_id is not None or self.child_id is not None:
+                raise ValueError(
+                    "scope 'household' takes no definition_id or child_id"
+                )
+        elif self.scope == "definition":
+            if self.definition_id is None:
+                raise ValueError("scope 'definition' requires definition_id")
+            if self.child_id is not None:
+                raise ValueError("scope 'definition' must not carry child_id")
+        else:
+            if self.child_id is None:
+                raise ValueError("scope 'child' requires child_id")
+            if self.definition_id is not None:
+                raise ValueError(
+                    "scope 'child' must not carry definition_id"
+                )
+        return self
+
+
+class AdminRegenerateResponse(BaseModel):
+    """What a regenerate request rebuilt.
+
+    ``scope`` echoes the request; ``definition_id``/``child_id`` carry
+    the scoped id (both ``None`` for the household); ``count`` is the
+    number of instances the core walk upserted — the core's idempotent
+    count, so a re-run refreshes rows in place and never duplicates.
+    """
+
+    scope: str
+    definition_id: int | None
+    child_id: int | None
+    count: int
+
+
 #: 404 detail for a child id the core layer reports as non-existent.
 _CHILD_NOT_FOUND_DETAIL = "Child not found"
 
@@ -355,6 +587,78 @@ def _raise_quest_definition_error(error: ValueError) -> NoReturn:
     raise HTTPException(status_code=422, detail=str(error)) from error
 
 
+#: 404 detail for an override id the core layer reports as non-existent.
+_PRESENCE_OVERRIDE_NOT_FOUND_DETAIL = "Presence override not found"
+
+
+def _raise_presence_override_error(error: ValueError) -> NoReturn:
+    """Map a core presence ``ValueError`` from the DELETE route onto 404/422.
+
+    The mapping mirrors :func:`_raise_quest_definition_error`: the core
+    names a missing override by prefixing its error with
+    ``override_id:`` (an unknown id), and that one case is this route's
+    404.  Every other ``ValueError`` — a non-integer id the path
+    parser's ``int`` already makes unreachable — becomes 422.  The
+    schedule and override-CREATE routes do NOT use this mapper: their
+    only 404 is an unknown CHILD, mapped by :func:`_raise_child_error`.
+    """
+    if str(error).startswith("override_id:"):
+        raise HTTPException(
+            status_code=404, detail=_PRESENCE_OVERRIDE_NOT_FOUND_DETAIL
+        ) from error
+    raise HTTPException(status_code=422, detail=str(error)) from error
+
+
+#: 404 detail for an instance id the core layer reports as non-existent.
+_QUEST_INSTANCE_NOT_FOUND_DETAIL = "Quest instance not found"
+
+
+def _raise_instance_error(error: ValueError) -> NoReturn:
+    """Map a core completion ``ValueError`` onto 404 or 422 and raise it.
+
+    The uncomplete route's mapping, keyed the same way the panel
+    complete route keys its 404: the core names a missing instance by
+    prefixing its error with ``instance_id:``
+    (:func:`nestquest_core.completion.uncomplete_instance` on an
+    unknown id), and that one case is this route's 404.  Every other
+    ``ValueError`` — a rejected actor shape, which a verified token
+    without a usable ``sub`` claim produces — is 422 with the core's
+    message as the detail.  The route catches ONLY ``ValueError``, so
+    an unexpected failure propagates untouched.
+    """
+    if str(error).startswith("instance_id:"):
+        raise HTTPException(
+            status_code=404, detail=_QUEST_INSTANCE_NOT_FOUND_DETAIL
+        ) from error
+    raise HTTPException(status_code=422, detail=str(error)) from error
+
+
+def _raise_regenerate_error(error: ValueError) -> NoReturn:
+    """Map a core materialization ``ValueError`` onto 422 and raise it.
+
+    The regenerate route's 404s are decided BEFORE the core call (the
+    handler's own existence reads of the scoped id), so every
+    ``ValueError`` that survives to here is a rejected argument — a
+    malformed horizon or date the core refuses before any write — and
+    is 422 with the core's message as the detail.  Nothing else is
+    caught: an unexpected failure re-raises rather than becoming a 4xx.
+    """
+    raise HTTPException(status_code=422, detail=str(error)) from error
+
+
+def _local_now() -> datetime.datetime:
+    """Return the API host's local time as ONE timezone-aware clock read.
+
+    Same discipline as the panel route's clock read: a single
+    ``now().astimezone()`` read anchors the household-local date the
+    regenerate horizon and the uncomplete stamp derive from, so the
+    calendar date can never disagree inside one request.  Kept as a
+    module function so tests pin the instant the same way the panel
+    route's ``_local_now`` is pinned.
+    """
+    return datetime.datetime.now().astimezone()
+
+
 def _rule_from_request(rule: AdminRuleRequest) -> core_recurrence.ScheduleRule:
     """Build the core ScheduleRule from the request's ``rule`` object.
 
@@ -398,6 +702,34 @@ def _quest_definition_response(
     )
 
 
+def _presence_schedule_response(
+    schedule: core_presence.PresenceSchedule,
+) -> AdminPresenceScheduleResponse:
+    """Serialize one decoded core PresenceSchedule into the payload."""
+    return AdminPresenceScheduleResponse(
+        child_id=schedule.child_id,
+        cycle_length_weeks=schedule.cycle_length_weeks,
+        anchor_date=schedule.anchor_date.isoformat(),
+        pattern={
+            week: sorted(days) for week, days in schedule.pattern.items()
+        },
+    )
+
+
+def _presence_override_response(
+    record: core_presence_management.PresenceOverrideRecord,
+) -> AdminPresenceOverrideResponse:
+    """Serialize one core PresenceOverrideRecord into the payload."""
+    return AdminPresenceOverrideResponse(
+        id=record.id,
+        child_id=record.child_id,
+        start_date=record.start_date,
+        end_date=record.end_date,
+        is_present=record.is_present,
+        note=record.note,
+    )
+
+
 @router.get("/ping", summary="Admin plane probe")
 async def admin_ping(
     claims: Annotated[dict[str, object], Depends(require_admin)],
@@ -681,4 +1013,285 @@ async def admin_set_quest_definition_active(
     return _quest_definition_response(bundle)
 
 
+@router.put(
+    "/children/{child_id}/presence-schedule",
+    summary="Set a child's repeating presence schedule",
+    response_model=AdminPresenceScheduleResponse,
+)
+async def admin_set_presence_schedule(
+    child_id: int, body: AdminPresenceScheduleRequest, request: Request
+) -> AdminPresenceScheduleResponse:
+    """Set (upsert) a child's repeating presence schedule.
+
+    Requires a valid admin JWT (the router's shared
+    :func:`~api.auth.require_admin` dependency — the ONE check; this
+    handler performs NO auth of its own).  Thin adapter: the body model
+    carries the shape, and the cycle-length, anchor-date and
+    pattern-coverage policies all live in the
+    :class:`~nestquest_core.presence.PresenceSchedule` constructor the
+    core builds the schedule with — setting again REPLACES the child's
+    one schedule, and the core regenerates the child's future instances
+    so they track the new presence.  Errors are mapped by
+    :func:`_raise_child_error`: an unknown child is 404, a rejected
+    schedule 422.
+    """
+    state: DatabaseState = request.app.state.db
+    try:
+        schedule = await core_presence_management.set_presence_schedule(
+            state.database,
+            child_id,
+            body.cycle_length_weeks,
+            body.anchor_date,
+            body.pattern,
+        )
+    except ValueError as error:
+        _raise_child_error(error)
+    return _presence_schedule_response(schedule)
+
+
+@router.post(
+    "/presence-overrides",
+    summary="Create a date-range presence override",
+    status_code=201,
+    response_model=AdminPresenceOverrideResponse,
+)
+async def admin_create_presence_override(
+    body: AdminPresenceOverrideCreateRequest, request: Request
+) -> AdminPresenceOverrideResponse:
+    """Create one date-range presence override and return it with its id.
+
+    Requires a valid admin JWT (the router's shared
+    :func:`~api.auth.require_admin` dependency — the ONE check; this
+    handler performs NO auth of its own).  Thin adapter: the body model
+    carries the shape, and the date/order/bool/note policies live in
+    the :class:`~nestquest_core.presence.PresenceOverride` constructor
+    while the same-child no-overlap policy lives in the core's create
+    path — which then regenerates the child's future instances so an
+    absent range removes them and a present range restores them.  The
+    response carries the stored ``id``, the handle
+    ``DELETE /presence-overrides/{id}`` takes.
+
+    Errors are mapped by :func:`_raise_child_error`: an unknown child
+    is 404; a rejected override (malformed or inverted dates, an
+    overlapping range) is 422.
+    """
+    state: DatabaseState = request.app.state.db
+    try:
+        record = await core_presence_management.create_presence_override(
+            state.database,
+            body.child_id,
+            body.start_date,
+            body.end_date,
+            body.is_present,
+            note=body.note,
+        )
+    except ValueError as error:
+        _raise_child_error(error)
+    return _presence_override_response(record)
+
+
+@router.delete(
+    "/presence-overrides/{override_id}",
+    summary="Delete a presence override",
+)
+async def admin_delete_presence_override(
+    override_id: int, request: Request
+) -> dict[str, str]:
+    """Delete one presence override; children are never hard-deleted.
+
+    Requires a valid admin JWT (the router's shared
+    :func:`~api.auth.require_admin` dependency — the ONE check; this
+    handler performs NO auth of its own).  Thin adapter: the id goes
+    straight to
+    :func:`nestquest_core.presence_management.delete_presence_override`,
+    which looks the override up first (an unknown id is refused BEFORE
+    any delete), removes it and regenerates ITS child's future
+    instances — the id, never a caller-supplied child, decides which
+    child's presence is rebuilt.  On success the route answers
+    ``{"status": "ok"}``.
+
+    Error mapping (:func:`_raise_presence_override_error`): an unknown
+    override id is 404; every other core ``ValueError`` is 422.
+    """
+    state: DatabaseState = request.app.state.db
+    try:
+        await core_presence_management.delete_presence_override(
+            state.database, override_id
+        )
+    except ValueError as error:
+        _raise_presence_override_error(error)
+    return {"status": "ok"}
+
+
+@router.post(
+    "/instances/{instance_id}/uncomplete",
+    summary="Reverse one completion (append a reversal event)",
+    response_model=AdminUncompleteResponse,
+)
+async def admin_uncomplete_instance(
+    instance_id: int,
+    request: Request,
+    claims: Annotated[dict[str, object], Depends(require_admin)],
+) -> AdminUncompleteResponse:
+    """Reverse one completion; the original event is never touched.
+
+    Requires a valid admin JWT (the router's shared
+    :func:`~api.auth.require_admin` dependency — the ONE check; this
+    handler performs NO auth of its own).  ``claims`` is the SAME
+    verified-claims dict that dependency produced (FastAPI's
+    per-request dependency cache), and the reversal is attributed to
+    it: ``actor_source="user"`` with ``actor_user_id`` = the token's
+    ``sub`` — the D-008 user-actor shape, ``actor_child_id`` never
+    sent — so the completion log records WHICH admin reversed it.
+
+    Thin adapter: ONE timezone-aware clock read (:func:`_local_now`)
+    and ONE :func:`nestquest_core.completion.uncomplete_instance` call
+    — the append-only discipline (a reversal APPENDS an ``uncompleted``
+    event after the original ``completed`` row, which is never edited
+    or deleted), the already-open no-op and the derived-state
+    recomputation all live in the core layer.
+
+    On an ACTUAL reversal (``CompletionResult.appended`` True) the
+    route publishes the ``nestquest_quest_uncompleted`` transition on
+    the SSE stream through
+    :func:`api.transitions.publish_quest_uncompleted` (the payload is
+    built by the core builder, never hand-built here; fan-out is
+    fire-and-forget, see api/events.py).  An already-open no-op
+    (``appended`` False) publishes nothing.
+
+    Response: the derived ``state`` after the reversal — ``open``, or
+    ``missed`` when the instance is past due — and whether THIS call
+    ``appended``.  Error mapping (:func:`_raise_instance_error`): an
+    unknown instance is 404; every other core ``ValueError`` is 422.
+    """
+    state: DatabaseState = request.app.state.db
+    database = state.database
+    now = _local_now()
+    sub = claims.get("sub")
+    try:
+        result = await core_completion.uncomplete_instance(
+            database,
+            instance_id,
+            actor_source="user",
+            actor_user_id=sub if isinstance(sub, str) else None,
+            now=now,
+        )
+    except ValueError as error:
+        _raise_instance_error(error)
+    if result.appended:
+        # An ACTUAL reversal: announce the transition once.  A no-op
+        # (already open) publishes nothing.
+        await api_transitions.publish_quest_uncompleted(
+            database, instance_id, request.app.state.publisher
+        )
+    return AdminUncompleteResponse(
+        instance_id=instance_id,
+        state=str(result),
+        appended=result.appended,
+    )
+
+
+@router.post(
+    "/regenerate",
+    summary="Re-materialize the rolling horizon for one scope",
+    response_model=AdminRegenerateResponse,
+)
+async def admin_regenerate(
+    body: AdminRegenerateRequest, request: Request
+) -> AdminRegenerateResponse:
+    """Re-materialize the rolling horizon for the requested scope.
+
+    Requires a valid admin JWT (the router's shared
+    :func:`~api.auth.require_admin` dependency — the ONE check; this
+    handler performs NO auth of its own).  Thin adapter over the SAME
+    materialization path the integration's config/presence changes
+    trigger, one scope per request:
+
+    - ``household`` (the default): ONE
+      :func:`nestquest_core.materialize.materialize` call over
+      ``[today, today + const.DEFAULT_HORIZON_DAYS]`` — the core's
+      default horizon, which sizes the window here because the API
+      config carries no horizon knob of its own.  The walk is an
+      idempotent upsert: re-running refreshes rows in place and never
+      duplicates an instance.
+    - ``definition``: ONE existence read
+      (:class:`~nestquest_core.dao_rules.QuestDefinitionsDao.get` — an
+      unknown id is 404 BEFORE any core call, which the core's
+      regenerate path itself takes no stance on), then
+      :func:`nestquest_core.materialize.regenerate_for_definition`.
+    - ``child``: the same shape through
+      :class:`~nestquest_core.dao_children.ChildrenDao.get` and
+      :func:`nestquest_core.materialize.regenerate_for_child`.
+
+    The ONE clock read (:func:`_local_now`) threads the household-local
+    ``today`` into every core call so the walk's no-past guard and the
+    delete cutoff share one anchor.  Every core call returns the
+    upsert ``count``, which the response passes through.  Error
+    mapping (:func:`_raise_regenerate_error`): every core
+    ``ValueError`` is 422; the scope-id 404s are decided above.
+    """
+    state: DatabaseState = request.app.state.db
+    database = state.database
+    today = _local_now().date()
+
+    if body.scope == "household":
+        end_date = today + datetime.timedelta(
+            days=core_const.DEFAULT_HORIZON_DAYS
+        )
+        try:
+            count = await core_materialize.materialize(
+                database,
+                today.isoformat(),
+                end_date.isoformat(),
+                today=today,
+            )
+        except ValueError as error:
+            _raise_regenerate_error(error)
+        return AdminRegenerateResponse(
+            scope="household", definition_id=None, child_id=None,
+            count=count,
+        )
+
+    if body.scope == "definition":
+        definition_id = body.definition_id
+        # The request model's scope/id consistency validator already
+        # guarantees the id for this scope; this only narrows the type.
+        assert definition_id is not None
+        definition = await core_dao_rules.QuestDefinitionsDao(
+            database
+        ).get(definition_id)
+        if definition is None:
+            raise HTTPException(
+                status_code=404, detail=_QUEST_DEFINITION_NOT_FOUND_DETAIL
+            )
+        try:
+            count = await core_materialize.regenerate_for_definition(
+                database, definition_id, today=today
+            )
+        except ValueError as error:
+            _raise_regenerate_error(error)
+        return AdminRegenerateResponse(
+            scope="definition",
+            definition_id=definition_id,
+            child_id=None,
+            count=count,
+        )
+
+    child_id = body.child_id
+    # Same model guarantee as the definition scope above.
+    assert child_id is not None
+    child = await core_dao_children.ChildrenDao(database).get(child_id)
+    if child is None:
+        raise HTTPException(status_code=404, detail=_CHILD_NOT_FOUND_DETAIL)
+    try:
+        count = await core_materialize.regenerate_for_child(
+            database, child_id, today=today
+        )
+    except ValueError as error:
+        _raise_regenerate_error(error)
+    return AdminRegenerateResponse(
+        scope="child", definition_id=None, child_id=child_id, count=count
+    )
+
+
 __all__ = ["router"]

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

@@ -0,0 +1,10 @@
+"""Re-export of :mod:`custom_components.nestquest.core.presence_management` for the integration package.
+
+The presence-write business layer lives in
+:mod:`custom_components.nestquest.core.presence_management` (added for
+task e4a9d31b); this module re-exports it so the integration's service
+handlers call the ONE implementation the API admin plane shares.
+"""
+from __future__ import annotations
+
+from .core.presence_management import *  # noqa: F401,F403

custom_components/nestquest/services.py

@@ -4,9 +4,11 @@ Registration is domain-scoped and happens once (see
 :func:`async_register_services`); handlers resolve a live database at
 call time through the injected ``find_runtime`` callable.  Permission
 checks are Feature 09 later tasks — this module only validates payload
-shape and forwards to the Feature 03/06/08 business layers (and the
-presence DAOs).  ``export_history_csv`` is registered with a schema but
-raises until Feature 13.  ``regenerate`` is supplied by the caller so
+shape and forwards to the Feature 03/06/08 business layers (the
+presence writes included, through :mod:`.presence_management` — the
+ONE implementation the API admin plane shares).
+``export_history_csv`` is registered with a schema but raises until
+Feature 13.  ``regenerate`` is supplied by the caller so
 the Feature 07 handler stays the one in ``__init__``.
 """
 from __future__ import annotations
@@ -22,6 +24,7 @@ from homeassistant.exceptions import HomeAssistantError
 
 from . import children as children_layer
 from . import completion as completion_layer
+from . import presence_management as presence_management_layer
 from . import quest_definitions as quest_definitions_layer
 from .const import (
     DOMAIN,
@@ -39,11 +42,8 @@ from .const import (
     SERVICE_UNCOMPLETE_QUEST,
     SERVICE_UPDATE_QUEST_DEFINITION,
 )
-from .dao_presence import PresenceOverridesDao, PresenceSchedulesDao
 from .events import fire_quest_completed, fire_quest_uncompleted
-from .materialize import regenerate_for_child
 from .permissions import permission_gate
-from .presence import PresenceSchedule
 from .recurrence import ScheduleRule
 from .service_policy import SERVICE_POLICY
 
@@ -405,21 +405,12 @@ def _set_presence_pattern(
     async def _handler(call: Any) -> None:
         runtime = _require_runtime(hass, find_runtime)
         data = call.data
-        schedule = PresenceSchedule(
+        await presence_management_layer.set_presence_schedule(
+            runtime.database,
             data["child_id"],
             data["cycle_length_weeks"],
             data["anchor_date"],
             data["pattern"],
-        )
-        await PresenceSchedulesDao(runtime.database).upsert_by_child(
-            schedule.child_id,
-            schedule.cycle_length_weeks,
-            schedule.anchor_date.isoformat(),
-            schedule.encode(),
-        )
-        await regenerate_for_child(
-            runtime.database,
-            schedule.child_id,
             **_generation_kwargs(hass, runtime),
         )
 
@@ -432,16 +423,13 @@ def _create_presence_override(
     async def _handler(call: Any) -> None:
         runtime = _require_runtime(hass, find_runtime)
         data = call.data
-        await PresenceOverridesDao(runtime.database).create(
+        await presence_management_layer.create_presence_override(
+            runtime.database,
             data["child_id"],
             data["start_date"],
             data["end_date"],
             data["is_present"],
             note=data.get("note"),
-        )
-        await regenerate_for_child(
-            runtime.database,
-            data["child_id"],
             **_generation_kwargs(hass, runtime),
         )
 
@@ -453,17 +441,9 @@ def _delete_presence_override(
 ) -> ServiceHandler:
     async def _handler(call: Any) -> None:
         runtime = _require_runtime(hass, find_runtime)
-        dao = PresenceOverridesDao(runtime.database)
-        override_id = call.data["override_id"]
-        override = await dao.get(override_id)
-        if override is None:
-            raise HomeAssistantError(
-                f"override_id: presence override {override_id} does not exist"
-            )
-        await dao.delete(override_id)
-        await regenerate_for_child(
+        await presence_management_layer.delete_presence_override(
             runtime.database,
-            override.child_id,
+            call.data["override_id"],
             **_generation_kwargs(hass, runtime),
         )
 

tests/test_api_admin_presence.py

@@ -0,0 +1,571 @@
+"""Admin-plane presence route tests (task e4a9d31b).
+
+These tests exercise the admin plane's presence routes against the ASGI
+app with httpx, reusing the shared local-RSA-key/stubbed-JWKS harness
+(:mod:`tests.admin_jwt_harness`) so an admin JWT genuinely
+authenticates — signature, issuer, audience, expiry and the
+nestquest-admins group — with NO network access.
+
+Every done-condition case is proven against the DATABASE and the DOMAIN,
+read through the SAME core copy the app uses (``nestquest_core.*``; see
+the two-copy caveat in api/nestquest_core.py):
+
+- Authentication runs through the router's ONE ``require_admin``
+  dependency: an admin JWT passes, a JWT without the group is 403, an
+  absent credential is 401 — and nothing is written.
+- ``PUT /api/v1/admin/children/{id}/presence-schedule`` UPSERTS: the
+  first set persists the schedule, setting again REPLACES it — one
+  schedule row per child, never a duplicate.
+- ``POST /api/v1/admin/presence-overrides`` creates the override (its
+  ``id`` comes back) and ``DELETE /api/v1/admin/presence-overrides/{id}``
+  removes it again.
+- The child's RESOLVED presence changes accordingly: the pure
+  :class:`~nestquest_core.presence.PresenceEngine` built from the
+  stored rows answers differently before/after each write — a schedule
+  restricts the child's present weekdays, an override beats the pattern
+  for its range, and deleting the override restores the pattern's
+  answer.
+- The regeneration side effect lives in the core layer the route
+  calls: setting an all-absent schedule through the route deletes the
+  child's future open quest instances and they are NOT rebuilt while
+  the child is absent every day — the same proof the HA service test
+  makes, through the API instead.
+
+Error mapping (documented in api/routes_admin.py): a core ValueError
+for a non-existent child (schedule or override create) or override
+(delete) is 404; every other core ValueError — a rejected schedule
+(cycle length, pattern coverage, anchor date) or override (malformed or
+inverted dates, an overlapping range) — is 422, the same failure class
+FastAPI reports for malformed bodies.
+"""
+from __future__ import annotations
+
+import datetime
+import importlib
+from types import SimpleNamespace
+
+import pytest
+
+from tests.admin_jwt_harness import (
+    ADMIN_KEY,
+    KID,
+    AdminRunner,
+    jwks_for,
+    make_token,
+)
+
+# The presence model, DAOs, business layer and materializer through the
+# SAME core copy the app uses (nestquest_core.*, NOT the conftest-stubbed
+# custom_components copy) — used for the tests' database and resolved-
+# presence assertions only; the routes reach them through api.nestquest_core.
+_children = importlib.import_module("nestquest_core.children")
+_dao_presence = importlib.import_module("nestquest_core.dao_presence")
+_dao_instances = importlib.import_module("nestquest_core.dao_instances")
+_materialize = importlib.import_module("nestquest_core.materialize")
+_presence = importlib.import_module("nestquest_core.presence")
+
+#: A Monday anchoring every schedule: cycle week 0 starts here.
+ANCHOR_MONDAY = "2026-01-05"
+#: The Tuesday of that week — absent under the test schedule.
+TUESDAY = "2026-01-06"
+
+
+def _admin_headers() -> dict[str, str]:
+    """The Authorization header of a valid nestquest-admins JWT."""
+    return {"Authorization": f"Bearer {make_token()}"}
+
+
+def _schedule_body(
+    cycle_length_weeks: int = 1, pattern: dict[int, list[int]] | None = None
+) -> dict[str, object]:
+    """A valid schedule body anchored to the test Monday."""
+    return {
+        "cycle_length_weeks": cycle_length_weeks,
+        "anchor_date": ANCHOR_MONDAY,
+        "pattern": {"0": [0, 2, 4]} if pattern is None else pattern,
+    }
+
+
+def _override_body(
+    child_id: int,
+    *,
+    start_date: str = TUESDAY,
+    end_date: str = TUESDAY,
+    is_present: bool = True,
+) -> dict[str, object]:
+    """A valid single-day override body for the test child."""
+    return {
+        "child_id": child_id,
+        "start_date": start_date,
+        "end_date": end_date,
+        "is_present": is_present,
+        "note": "grandmother's week",
+    }
+
+
+async def _create_child(client: object, name: str = "Ada") -> int:
+    """Create one child through the admin children route; return the id."""
+    created = await client.post(
+        "/api/v1/admin/children",
+        json={"display_name": name},
+        headers=_admin_headers(),
+    )
+    assert created.status_code == 201
+    return created.json()["id"]
+
+
+def _engine(
+    database: object,
+    child_id: int,
+    schedule_record: object | None,
+    override_records: list[object],
+) -> object:
+    """Build the pure PresenceEngine from stored rows (the snapshot shape).
+
+    Mirrors what the core snapshot builder assembles: the child's
+    decoded schedule (absent → present every day) plus its overrides,
+    so :meth:`PresenceEngine.is_present` answers from the SAME rows the
+    routes produced.
+    """
+    schedules: dict[int, object] = {}
+    if schedule_record is not None:
+        schedules[child_id] = _presence.PresenceSchedule.decode(
+            schedule_record.child_id,
+            schedule_record.anchor_date,
+            schedule_record.pattern,
+        )
+    overrides = {
+        child_id: [
+            _presence.PresenceOverride(
+                record.child_id,
+                record.start_date,
+                record.end_date,
+                record.is_present,
+                note=record.note,
+            )
+            for record in override_records
+        ]
+    }
+    return _presence.PresenceEngine(schedules, overrides)
+
+
+async def _child_state(
+    database: object, child_id: int
+) -> tuple[object | None, list[object], object]:
+    """The child's stored schedule record, overrides and PresenceEngine."""
+    schedule_record = await _dao_presence.PresenceSchedulesDao(
+        database
+    ).get_by_child(child_id)
+    override_records = await _dao_presence.PresenceOverridesDao(
+        database
+    ).list_by_child_and_range(child_id, "2020-01-01", "2030-01-01")
+    engine = _engine(database, child_id, schedule_record, override_records)
+    return schedule_record, override_records, engine
+
+
+@pytest.fixture
+async def admin_presence(temp_db_path: str) -> SimpleNamespace:
+    """An admin-plane app client plus its live database.
+
+    The same runner the auth, children and quest-definition tests use
+    (stubbed JWKS, no network); the fixture also exposes the app's ONE
+    database connection so tests assert the routes' effects on the
+    stored rows and the resolved presence built from them.
+    """
+    runner = AdminRunner(temp_db_path, jwks_for(ADMIN_KEY, KID))
+    async with runner as client:
+        yield SimpleNamespace(
+            client=client,
+            database=runner.app.state.db.database,
+        )
+
+
+# --- authentication: the ONE require_admin dependency guards every route ---
+
+
+async def test_presence_routes_refuse_non_admin_and_absent_credentials(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """A non-admin JWT is 403, an absent credential is 401: nothing written."""
+    client = admin_presence.client
+    child_id = await _create_child(client)
+    non_admin = make_token(groups=("some-other-group",))
+    non_admin_headers = {"Authorization": f"Bearer {non_admin}"}
+
+    forbidden_schedule = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(),
+        headers=non_admin_headers,
+    )
+    assert forbidden_schedule.status_code == 403
+    assert forbidden_schedule.json()["detail"] == (
+        "Admin access requires membership in the nestquest-admins group"
+    )
+
+    forbidden_override = await client.post(
+        "/api/v1/admin/presence-overrides",
+        json=_override_body(child_id),
+        headers=non_admin_headers,
+    )
+    assert forbidden_override.status_code == 403
+
+    forbidden_delete = await client.delete(
+        "/api/v1/admin/presence-overrides/1", headers=non_admin_headers
+    )
+    assert forbidden_delete.status_code == 403
+
+    unauthenticated_schedule = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(),
+    )
+    assert unauthenticated_schedule.status_code == 401
+
+    unauthenticated_override = await client.post(
+        "/api/v1/admin/presence-overrides", json=_override_body(child_id)
+    )
+    assert unauthenticated_override.status_code == 401
+
+    unauthenticated_delete = await client.delete(
+        "/api/v1/admin/presence-overrides/1"
+    )
+    assert unauthenticated_delete.status_code == 401
+
+    # No route ran its handler: the child still has no schedule and no
+    # overrides (and is present every day, the no-schedule default).
+    _schedule, _overrides, engine = await _child_state(
+        admin_presence.database, child_id
+    )
+    assert _schedule is None
+    assert _overrides == []
+    assert engine.is_present(child_id, ANCHOR_MONDAY) is True
+
+
+# --- schedule upsert --------------------------------------------------------
+
+
+async def test_schedule_upserts_and_replaces_one_row_per_child(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """PUT /presence-schedule persists, and setting again REPLACES it."""
+    client = admin_presence.client
+    child_id = await _create_child(client)
+
+    first = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(),
+        headers=_admin_headers(),
+    )
+    assert first.status_code == 200
+    assert first.json() == {
+        "child_id": child_id,
+        "cycle_length_weeks": 1,
+        "anchor_date": ANCHOR_MONDAY,
+        "pattern": {"0": [0, 2, 4]},
+    }
+    # Database proof: exactly ONE schedule row (the schema's
+    # UNIQUE(child_id) makes a second row unrepresentable), stored as
+    # encoded CSV.
+    schedule, _overrides, _engine = await _child_state(
+        admin_presence.database, child_id
+    )
+    assert schedule is not None
+    row_id = schedule.id
+    assert schedule.cycle_length_weeks == 1
+    assert schedule.anchor_date == ANCHOR_MONDAY
+    assert schedule.pattern == "0,2,4"
+
+    # Setting again UPSERTS: the SAME row is updated in place — new
+    # values, unchanged id — never a duplicate or a stale first set.
+    second = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(
+            cycle_length_weeks=2, pattern={"0": [], "1": [1, 3]}
+        ),
+        headers=_admin_headers(),
+    )
+    assert second.status_code == 200
+    assert second.json() == {
+        "child_id": child_id,
+        "cycle_length_weeks": 2,
+        "anchor_date": ANCHOR_MONDAY,
+        "pattern": {"0": [], "1": [1, 3]},
+    }
+    schedule, _overrides, _engine = await _child_state(
+        admin_presence.database, child_id
+    )
+    assert schedule is not None
+    assert schedule.id == row_id
+    assert schedule.cycle_length_weeks == 2
+    assert schedule.pattern == "|1,3"
+
+
+async def test_schedule_changes_the_childs_resolved_presence(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """The resolved presence (PresenceEngine) follows the stored schedule."""
+    client = admin_presence.client
+    child_id = await _create_child(client)
+
+    # Before any schedule the child is present every day.
+    _schedule, _overrides, engine = await _child_state(
+        admin_presence.database, child_id
+    )
+    assert engine.is_present(child_id, ANCHOR_MONDAY) is True
+    assert engine.is_present(child_id, TUESDAY) is True
+
+    # Mon/Wed/Fri only, week 0 of a one-week cycle.
+    response = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(),
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 200
+    _schedule, _overrides, engine = await _child_state(
+        admin_presence.database, child_id
+    )
+    assert engine.is_present(child_id, ANCHOR_MONDAY) is True
+    assert engine.is_present(child_id, TUESDAY) is False
+
+
+async def test_schedule_upsert_regenerates_future_instances(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """Setting an all-absent schedule deletes the child's future instances.
+
+    The regeneration side effect lives in the core layer the route
+    calls: the child's open instances at or after today are deleted
+    across ALL its definitions and NOT rebuilt while the child is
+    absent every day — the same proof the HA service test makes,
+    exercised here through the API route instead.
+    """
+    client = admin_presence.client
+    database = admin_presence.database
+    child_id = await _create_child(client)
+    created = await client.post(
+        "/api/v1/admin/quest-definitions",
+        json={
+            "title": "Brush teeth",
+            "rule": {"rule_type": "daily"},
+            "assignee_child_ids": [child_id],
+            "windows": ["morning"],
+        },
+        headers=_admin_headers(),
+    )
+    assert created.status_code == 201
+
+    today = datetime.date.today()
+    start = today.isoformat()
+    end = (today + datetime.timedelta(days=14)).isoformat()
+    await _materialize.materialize(database, start, end, today=today)
+    instances = _dao_instances.QuestInstancesDao(database)
+    assert await instances.list_by_date_range(child_id, start, end)
+
+    # The route's write must regenerate: absent every day removes every
+    # open future instance.
+    response = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(pattern={"0": []}),
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 200
+    assert await instances.list_by_date_range(child_id, start, end) == []
+
+
+# --- override create + delete -----------------------------------------------
+
+
+async def test_override_is_created_then_deleted_and_presence_resolves(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """POST creates the override, DELETE removes it; presence follows."""
+    client = admin_presence.client
+    database = admin_presence.database
+    child_id = await _create_child(client)
+    schedule_response = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=_schedule_body(),
+        headers=_admin_headers(),
+    )
+    assert schedule_response.status_code == 200
+
+    # Create: the override comes back with its id and the posted shape.
+    created = await client.post(
+        "/api/v1/admin/presence-overrides",
+        json=_override_body(child_id),
+        headers=_admin_headers(),
+    )
+    assert created.status_code == 201
+    payload = created.json()
+    assert set(payload) == {
+        "id",
+        "child_id",
+        "start_date",
+        "end_date",
+        "is_present",
+        "note",
+    }
+    assert payload["child_id"] == child_id
+    assert payload["start_date"] == TUESDAY
+    assert payload["end_date"] == TUESDAY
+    assert payload["is_present"] is True
+    assert payload["note"] == "grandmother's week"
+
+    # Database proof: the row exists — and the RESOLVED presence for the
+    # affected date flips: the override beats the Tuesday-absent pattern.
+    _schedule, overrides, engine = await _child_state(database, child_id)
+    assert [record.id for record in overrides] == [payload["id"]]
+    assert engine.is_present(child_id, TUESDAY) is True
+    # A date the override does not cover keeps the pattern's answer.
+    assert engine.is_present(child_id, ANCHOR_MONDAY) is True
+
+    # Delete: the row is gone and the resolved presence follows the
+    # pattern again.
+    deleted = await client.delete(
+        f"/api/v1/admin/presence-overrides/{payload['id']}",
+        headers=_admin_headers(),
+    )
+    assert deleted.status_code == 200
+    assert deleted.json() == {"status": "ok"}
+    assert (
+        await _dao_presence.PresenceOverridesDao(database).get(payload["id"])
+        is None
+    )
+    _schedule, overrides, engine = await _child_state(database, child_id)
+    assert overrides == []
+    assert engine.is_present(child_id, TUESDAY) is False
+
+
+# --- error mapping: 404 vs 422 ----------------------------------------------
+
+
+async def test_schedule_and_override_for_unknown_child_are_404(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """A presence write naming a child that does not exist is 404."""
+    client = admin_presence.client
+
+    schedule = await client.put(
+        "/api/v1/admin/children/999/presence-schedule",
+        json=_schedule_body(),
+        headers=_admin_headers(),
+    )
+    assert schedule.status_code == 404
+    assert schedule.json()["detail"] == "Child not found"
+
+    override = await client.post(
+        "/api/v1/admin/presence-overrides",
+        json=_override_body(999),
+        headers=_admin_headers(),
+    )
+    assert override.status_code == 404
+    assert override.json()["detail"] == "Child not found"
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        _schedule_body(cycle_length_weeks=0),  # below the 1..4 range
+        _schedule_body(cycle_length_weeks=5),  # above the documented cap
+        # week 1 of the cycle missing:
+        _schedule_body(cycle_length_weeks=2, pattern={"0": [0]}),
+        {
+            "cycle_length_weeks": 1,
+            "anchor_date": "2026-13-40",
+            "pattern": {"0": [0]},
+        },
+        _schedule_body(pattern={"0": [7]}),  # weekday out of 0..6
+        _schedule_body(pattern={"nope": [0]}),  # week index not an integer
+        _schedule_body(pattern={"0": "0,2,4"}),  # weekdays not a list
+    ],
+)
+async def test_rejected_schedule_is_422(
+    admin_presence: SimpleNamespace, body: dict[str, object]
+) -> None:
+    """A rejected schedule is 422 and stores nothing."""
+    client = admin_presence.client
+    child_id = await _create_child(client)
+    response = await client.put(
+        f"/api/v1/admin/children/{child_id}/presence-schedule",
+        json=body,
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 422
+    assert (
+        await _dao_presence.PresenceSchedulesDao(
+            admin_presence.database
+        ).get_by_child(child_id)
+        is None
+    )
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        _override_body(1, start_date="2026-01-07", end_date="2026-01-06"),
+        _override_body(1, start_date="2026-02-30", end_date="2026-02-30"),
+        dict(_override_body(1), note=5),
+        dict(_override_body(1), child_id="one"),
+    ],
+)
+async def test_rejected_override_is_422(
+    admin_presence: SimpleNamespace, body: dict[str, object]
+) -> None:
+    """A rejected override (inverted/malformed dates, bad note/id) is 422.
+
+    The shape failures (a non-string note, a non-integer child id) are
+    the body model's; the date failures are the PresenceOverride
+    model's.  A string ``is_present`` like ``"yes"`` is deliberately
+    absent: Pydantic's lax bool COERCES it to ``True`` (the same design
+    as the children active route), so it never reaches the model's
+    real-bool check.
+    """
+    response = await admin_presence.client.post(
+        "/api/v1/admin/presence-overrides", json=body, headers=_admin_headers()
+    )
+    assert response.status_code == 422
+
+
+async def test_overlapping_override_is_422_and_first_survives(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """An override overlapping the child's existing one is 422.
+
+    The conflicting write persists nothing: the child's original
+    override survives unchanged.
+    """
+    client = admin_presence.client
+    child_id = await _create_child(client)
+    created = await client.post(
+        "/api/v1/admin/presence-overrides",
+        json=_override_body(child_id),
+        headers=_admin_headers(),
+    )
+    assert created.status_code == 201
+
+    response = await client.post(
+        "/api/v1/admin/presence-overrides",
+        json=_override_body(child_id, is_present=False),
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 422
+    _schedule, overrides, _engine = await _child_state(
+        admin_presence.database, child_id
+    )
+    assert [record.id for record in overrides] == [created.json()["id"]]
+
+
+async def test_delete_unknown_override_is_404(
+    admin_presence: SimpleNamespace,
+) -> None:
+    """Deleting an override id that does not exist is 404."""
+    response = await admin_presence.client.delete(
+        "/api/v1/admin/presence-overrides/999", headers=_admin_headers()
+    )
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Presence override not found"
+
+    malformed = await admin_presence.client.delete(
+        "/api/v1/admin/presence-overrides/not-an-id",
+        headers=_admin_headers(),
+    )
+    assert malformed.status_code == 422

tests/test_api_admin_uncomplete.py

@@ -0,0 +1,694 @@
+"""Admin-plane uncomplete and regenerate route tests (task da0226b3).
+
+These tests exercise the admin plane's completion-reversal and
+re-materialization routes against the ASGI app with httpx, reusing the
+shared local-RSA-key/stubbed-JWKS harness
+(:mod:`tests.admin_jwt_harness`) so an admin JWT genuinely
+authenticates — signature, issuer, audience, expiry and the
+nestquest-admins group — with NO network access.  The household is
+seeded with :func:`tests.test_api_panel._seed_household` through the
+SAME core copy the app uses (``nestquest_core.*``; the two-copy caveat
+in api/nestquest_core.py), and the route's ONE clock read
+(:func:`api.routes_admin._local_now`) is pinned the same way the panel
+route's is, so seeded rows and route stamps cannot straddle midnight.
+
+Every done-condition case is proven against the DATABASE, read through
+that same core copy:
+
+- Authentication runs through the router's ONE ``require_admin``
+  dependency: an admin JWT passes, a JWT without the group is 403, an
+  absent credential is 401 — and nothing is written.
+- ``POST /api/v1/admin/instances/{id}/uncomplete``: the completion
+  events log for the instance holds the ORIGINAL ``completed`` row
+  UNTOUCHED plus ONE appended ``uncompleted`` row attributed to the
+  verified token's ``sub`` (actor_source ``user``), and the instance's
+  DERIVED state is ``open`` again; a second uncomplete is a no-op that
+  appends nothing.
+- On an ACTUAL reversal the ``nestquest_quest_uncompleted`` transition
+  arrives on the SSE stream exactly once (subscribed live as
+  :mod:`tests.test_api_sse` does); a no-op uncomplete publishes
+  nothing.
+- ``POST /api/v1/admin/regenerate`` re-materializes without
+  duplicating: running it twice (household, definition and child
+  scopes) leaves the instance count stable, and the scoped variants
+  rebuild only their own scope's rows.
+
+Error mapping (documented in api/routes_admin.py): an unknown
+instance is 404 (the core's ``instance_id:`` prefix, the same key the
+panel complete route uses); unknown definition/child scope ids are 404
+from the route's own existence reads; malformed input — a bad scope,
+a scope/id mismatch, a zero id, a non-integer path id — is 422 before
+any handler code runs.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import importlib
+from types import SimpleNamespace
+from zoneinfo import ZoneInfo
+
+import httpx
+import pytest
+
+from api import routes_admin
+from api.app import create_app
+from api.auth import JwksCache
+from api.config import ApiConfig
+from tests.admin_jwt_harness import (
+    ADMIN_KEY,
+    AUDIENCE,
+    ISSUER,
+    JWKS_URL,
+    KID,
+    AdminRunner,
+    StubbedFetch,
+    SUBJECT,
+    jwks_for,
+    make_token,
+)
+from tests.test_api_panel import PANEL_TOKEN, _seed_household
+from tests.test_api_sse import _EventStream, _Server, _stream
+
+# The completion and instance-DAO layers through the SAME core copy the
+# app uses (nestquest_core.*, NOT the conftest-stubbed
+# custom_components copy) — used for the tests' database assertions
+# only; the routes reach them through api.nestquest_core.
+_completion = importlib.import_module("nestquest_core.completion")
+_dao_instances = importlib.import_module("nestquest_core.dao_instances")
+
+#: The documented quest-uncompleted event name (core const, §3).
+EVENT_QUEST_UNCOMPLETED = importlib.import_module(
+    "nestquest_core.const"
+).EVENT_QUEST_UNCOMPLETED
+
+
+def _admin_headers() -> dict[str, str]:
+    """The Authorization header of a valid nestquest-admins JWT."""
+    return {"Authorization": f"Bearer {make_token()}"}
+
+
+def _pinned_noon() -> tuple[datetime.date, datetime.datetime]:
+    """One host clock read pinned to 12:00 UTC that day.
+
+    The seed's completion and the route's clock both anchor to this
+    instant, so nothing can straddle midnight mid-test.
+    """
+    today = datetime.datetime.now().astimezone().date()
+    return today, datetime.datetime(
+        today.year, today.month, today.day, 12, 0, 0, tzinfo=ZoneInfo("UTC")
+    )
+
+
+async def _instance_count(database: object) -> int:
+    """The whole ``quest_instances`` row count (the sanctioned probe)."""
+    row = await database.fetch_one("SELECT COUNT(*) FROM quest_instances")
+    return row[0]
+
+
+async def _events_for_instance(
+    database: object, instance_id: int
+) -> list:
+    """The instance's completion events, in append order."""
+    dao = _dao_instances.CompletionEventsDao(database)
+    return await dao.list_by_instance(instance_id)
+
+
+async def _derived_state(
+    database: object, instance_id: int, today: datetime.date
+) -> str:
+    """The instance's derived state through the app's core copy."""
+    dao = _dao_instances.QuestInstancesDao(database)
+    instance = await dao.get_by_id(instance_id)
+    assert instance is not None
+    latest = await _dao_instances.CompletionEventsDao(
+        database
+    ).get_latest_for_instance(instance_id)
+    return _completion.derive_state(instance, latest, today)
+
+
+@pytest.fixture
+async def admin_api(temp_db_path: str) -> SimpleNamespace:
+    """An admin-plane app client plus its live database.
+
+    The same runner the auth and children tests use (stubbed JWKS, no
+    network); the fixture exposes the app's ONE database connection so
+    tests assert the routes' effects on the stored rows themselves.
+    """
+    runner = AdminRunner(temp_db_path, jwks_for(ADMIN_KEY, KID))
+    async with runner as client:
+        yield SimpleNamespace(
+            client=client,
+            database=runner.app.state.db.database,
+        )
+
+
+@pytest.fixture
+async def admin_household(temp_db_path: str, monkeypatch) -> SimpleNamespace:
+    """A seeded household served by the admin-plane app, clock pinned.
+
+    ``_seed_household`` completes Bo's today instance (17:00 due, 12:00
+    pinned — on time), which is the completion the uncomplete tests
+    reverse.  The route's ``_local_now`` is pinned to the same instant.
+    """
+    today, pinned_now = _pinned_noon()
+    seed = await _seed_household(temp_db_path, today, pinned_now)
+    monkeypatch.setattr(routes_admin, "_local_now", lambda: pinned_now)
+    runner = AdminRunner(temp_db_path, jwks_for(ADMIN_KEY, KID))
+    async with runner as client:
+        yield SimpleNamespace(
+            client=client,
+            seed=seed,
+            database=runner.app.state.db.database,
+            today=today,
+        )
+
+
+class _AdminServer(_Server):
+    """:mod:`tests.test_api_sse`'s live-uvicorn server, admin-enabled.
+
+    Same ephemeral-port uvicorn thread (httpx's ASGI transport buffers
+    SSE bodies, so a live server is the only way to stream), but the
+    app factory swaps the JWKS cache for one built around the harness's
+    stub fetcher, so a real admin JWT verifies with NO network access.
+    """
+
+    def _make_app_factory(self, db_path: str):
+        """The uvicorn app factory with the stubbed JWKS cache."""
+
+        def factory():
+            app = create_app(
+                ApiConfig(
+                    db_path=db_path,
+                    panel_token=PANEL_TOKEN,
+                    oidc_issuer=ISSUER,
+                    oidc_audience=AUDIENCE,
+                    oidc_jwks_url=JWKS_URL,
+                )
+            )
+            app.state.jwks_cache = JwksCache(
+                JWKS_URL, fetcher=StubbedFetch(jwks_for(ADMIN_KEY, KID))
+            )
+            self._server_loop = asyncio.get_running_loop()
+            self.app = app
+            return app
+
+        return factory
+
+
+@pytest.fixture
+async def admin_sse(temp_db_path: str) -> SimpleNamespace:
+    """A seeded household served by a live uvicorn app, clock pinned.
+
+    Same pinning discipline as the panel tests, applied to
+    :func:`api.routes_admin._local_now` BEFORE the server starts (the
+    app is created inside uvicorn's factory thread).
+    """
+    today, pinned_now = _pinned_noon()
+    seed = await _seed_household(temp_db_path, today, pinned_now)
+    original = routes_admin._local_now
+    routes_admin._local_now = lambda: pinned_now
+    try:
+        with _AdminServer(temp_db_path) as server:
+            client = httpx.AsyncClient(base_url=server.url(""))
+            async with client:
+                yield SimpleNamespace(
+                    client=client,
+                    seed=seed,
+                    server=server,
+                    database=server.app.state.db.database,
+                    today=today,
+                )
+    finally:
+        routes_admin._local_now = original
+
+
+# --- authentication: the ONE require_admin dependency guards every route ---
+
+
+async def test_uncomplete_and_regenerate_refuse_non_admin_and_absent(
+    admin_household: SimpleNamespace,
+) -> None:
+    """A non-admin JWT is 403, an absent credential is 401: nothing written."""
+    client = admin_household.client
+    database = admin_household.database
+    brush = admin_household.seed.brush_teeth_instance
+    non_admin = make_token(groups=("some-other-group",))
+    events_before = await _events_for_instance(database, brush.id)
+    instances_before = await _instance_count(database)
+
+    uncomplete_url = f"/api/v1/admin/instances/{brush.id}/uncomplete"
+    forbidden = await client.post(
+        uncomplete_url,
+        headers={"Authorization": f"Bearer {non_admin}"},
+    )
+    assert forbidden.status_code == 403
+    assert forbidden.json()["detail"] == (
+        "Admin access requires membership in the nestquest-admins group"
+    )
+    unauthenticated = await client.post(uncomplete_url)
+    assert unauthenticated.status_code == 401
+
+    regenerate_bodies = (
+        {},
+        {"scope": "household"},
+        {"scope": "child", "child_id": 1},
+    )
+    for body in regenerate_bodies:
+        forbidden = await client.post(
+            "/api/v1/admin/regenerate",
+            json=body,
+            headers={"Authorization": f"Bearer {non_admin}"},
+        )
+        assert forbidden.status_code == 403, body
+        unauthenticated = await client.post(
+            "/api/v1/admin/regenerate", json=body
+        )
+        assert unauthenticated.status_code == 401, body
+
+    # No handler ran: the seeded completion is still the ONLY event for
+    # the instance and the instance table is untouched.
+    assert (
+        await _events_for_instance(database, brush.id) == events_before
+    )
+    assert await _instance_count(database) == instances_before
+
+
+# --- uncomplete: the append-only reversal -----------------------------------
+
+
+async def test_uncomplete_appends_reversal_and_derived_state_is_open(
+    admin_household: SimpleNamespace,
+) -> None:
+    """A reversal APPENDS an uncompleted event; the instance is open again.
+
+    The original completed row is proven byte-identical after the call
+    (frozen-dataclass equality), the new row carries the verified
+    token's ``sub`` as the user actor, and the DERIVED state —
+    recomputed from the latest event — is ``open`` again.
+    """
+    client = admin_household.client
+    database = admin_household.database
+    brush = admin_household.seed.brush_teeth_instance
+    today = admin_household.today
+
+    before = await _events_for_instance(database, brush.id)
+    assert [event.event_type for event in before] == ["completed"]
+    assert await _derived_state(database, brush.id, today) == "done"
+
+    response = await client.post(
+        f"/api/v1/admin/instances/{brush.id}/uncomplete",
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body == {
+        "instance_id": brush.id,
+        "state": "open",
+        "appended": True,
+    }
+
+    events = await _events_for_instance(database, brush.id)
+    assert len(events) == 2
+    # The original completed row is UNTOUCHED — never edited, never
+    # deleted (append-only completion_events).
+    assert events[0] == before[0]
+    assert events[0].event_type == "completed"
+    assert events[0].actor_source == "panel"
+    # The reversal is the NEW row, attributed to the verified token.
+    reversal = events[1]
+    assert reversal.event_type == "uncompleted"
+    assert reversal.instance_id == brush.id
+    assert reversal.child_id == brush.child_id
+    assert reversal.actor_source == "user"
+    assert reversal.actor_user_id == SUBJECT
+    assert reversal.actor_child_id is None
+    assert reversal.was_on_time is None
+    # The derived state is recomputed from the latest event: open again.
+    assert await _derived_state(database, brush.id, today) == "open"
+
+
+async def test_second_uncomplete_is_a_noop_that_appends_nothing(
+    admin_household: SimpleNamespace,
+) -> None:
+    """A repeat uncomplete appends NOTHING and still succeeds."""
+    client = admin_household.client
+    database = admin_household.database
+    brush = admin_household.seed.brush_teeth_instance
+    today = admin_household.today
+
+    first = await client.post(
+        f"/api/v1/admin/instances/{brush.id}/uncomplete",
+        headers=_admin_headers(),
+    )
+    assert first.status_code == 200
+    assert first.json()["appended"] is True
+
+    second = await client.post(
+        f"/api/v1/admin/instances/{brush.id}/uncomplete",
+        headers=_admin_headers(),
+    )
+    assert second.status_code == 200
+    body = second.json()
+    assert body["appended"] is False
+    assert body["state"] == "open"
+
+    events = await _events_for_instance(database, brush.id)
+    assert len(events) == 2
+    assert [event.event_type for event in events] == [
+        "completed",
+        "uncompleted",
+    ]
+    assert await _derived_state(database, brush.id, today) == "open"
+
+
+async def test_uncomplete_unknown_instance_is_404_and_malformed_is_422(
+    admin_household: SimpleNamespace,
+) -> None:
+    """An unknown instance is 404; a non-integer path id is 422."""
+    client = admin_household.client
+    brush = admin_household.seed.brush_teeth_instance
+    before = await _events_for_instance(
+        admin_household.database, brush.id
+    )
+
+    unknown = await client.post(
+        "/api/v1/admin/instances/999/uncomplete",
+        headers=_admin_headers(),
+    )
+    assert unknown.status_code == 404
+    assert unknown.json()["detail"] == "Quest instance not found"
+
+    malformed = await client.post(
+        "/api/v1/admin/instances/not-an-int/uncomplete",
+        headers=_admin_headers(),
+    )
+    assert malformed.status_code == 422
+
+    # Neither rejection wrote anything.
+    assert (
+        await _events_for_instance(admin_household.database, brush.id)
+        == before
+    )
+
+
+async def test_uncomplete_already_open_past_due_reports_missed(
+    admin_household: SimpleNamespace,
+) -> None:
+    """A no-op uncomplete still reports the honest DERIVED state.
+
+    The seeded stale instance is open and past due: uncompleting it is
+    a no-op (nothing appended) and the derived state is ``missed`` —
+    open-but-past-due, never an event type.
+    """
+    client = admin_household.client
+    database = admin_household.database
+    stale = admin_household.seed.stale_instance
+    today = admin_household.today
+    assert await _derived_state(database, stale.id, today) == "missed"
+
+    response = await client.post(
+        f"/api/v1/admin/instances/{stale.id}/uncomplete",
+        headers=_admin_headers(),
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["appended"] is False
+    assert body["state"] == "missed"
+
+    # The no-op appended nothing: the instance still has NO events.
+    assert await _events_for_instance(database, stale.id) == []
+
+
+# --- the SSE transition on an actual reversal --------------------------------
+
+
+async def test_uncomplete_publishes_exactly_one_uncompleted_transition(
+    admin_sse: SimpleNamespace,
+) -> None:
+    """An actual reversal streams ONE quest-uncompleted event; a no-op none.
+
+    The stream is subscribed FIRST (test_api_sse's live-server reader),
+    the completed instance is reversed through the admin route, and the
+    documented payload fields are asserted; the no-op second call adds
+    no frame.
+    """
+    seed = admin_sse.seed
+    brush = seed.brush_teeth_instance
+    stream = _stream(admin_sse.server.url("/api/v1/panel/events"))
+    async with stream:
+        first = await admin_sse.client.post(
+            f"/api/v1/admin/instances/{brush.id}/uncomplete",
+            headers=_admin_headers(),
+        )
+        assert first.status_code == 200
+        assert first.json()["appended"] is True
+
+        event_type, payload = await stream.next_event()
+        assert event_type == EVENT_QUEST_UNCOMPLETED
+        assert event_type == "nestquest_quest_uncompleted"
+        assert payload["child_id"] == seed.bo.id
+        assert payload["child_name"] == "Bo"
+        assert payload["instance_id"] == brush.id
+        assert payload["quest_title"] == "Brush teeth"
+        assert payload["window"] == "morning"
+        assert payload["due_date"] == brush.due_date
+        assert payload["due_time"] == "17:00"
+        assert payload["occurred_at"]  # strict UTC ISO-8601 stamp
+        assert "was_on_time" not in payload
+
+        # The no-op second call publishes nothing: the stream stays
+        # silent past the window.
+        second = await admin_sse.client.post(
+            f"/api/v1/admin/instances/{brush.id}/uncomplete",
+            headers=_admin_headers(),
+        )
+        assert second.status_code == 200
+        assert second.json()["appended"] is False
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(stream.queue.get(), timeout=0.3)
+
+
+# --- regenerate: re-materialize without duplicating --------------------------
+
+
+async def _create_child(client: object, name: str) -> int:
+    """Create one child through the admin children route."""
+    created = await client.post(
+        "/api/v1/admin/children",
+        json={"display_name": name},
+        headers=_admin_headers(),
+    )
+    assert created.status_code == 201
+    return created.json()["id"]
+
+
+async def _create_daily_definition(
+    client: object, assignee_ids: list[int]
+) -> int:
+    """Create one daily one-window definition for the given assignees."""
+    created = await client.post(
+        "/api/v1/admin/quest-definitions",
+        json={
+            "title": "Tidy the den",
+            "rule": {"rule_type": "daily", "start_date": "2026-03-02"},
+            "assignee_child_ids": assignee_ids,
+            "windows": ["morning"],
+        },
+        headers=_admin_headers(),
+    )
+    assert created.status_code == 201
+    return created.json()["id"]
+
+
+async def test_regenerate_household_never_duplicates(
+    admin_household: SimpleNamespace,
+) -> None:
+    """Two household regenerations leave the instance count stable.
+
+    The first call re-materializes the rolling horizon
+    ``[today, today + DEFAULT_HORIZON_DAYS]``; the second walks the
+    SAME tuples and upserts them in place — the row count never grows
+    and the core reports the same upsert count both times.
+    """
+    client = admin_household.client
+    database = admin_household.database
+
+    before = await _instance_count(database)
+    assert before > 0  # the seed already materialized a few days
+
+    first = await client.post(
+        "/api/v1/admin/regenerate", json={}, headers=_admin_headers()
+    )
+    assert first.status_code == 200
+    body = first.json()
+    assert body["scope"] == "household"
+    assert body["definition_id"] is None
+    assert body["child_id"] is None
+    assert body["count"] >= before
+    after_first = await _instance_count(database)
+    assert after_first >= before
+
+    second = await client.post(
+        "/api/v1/admin/regenerate", json={}, headers=_admin_headers()
+    )
+    assert second.status_code == 200
+    assert second.json()["count"] == body["count"]
+    # The idempotent walk: the second run's row count is EXACTLY the
+    # first's — no duplicated instances.
+    assert await _instance_count(database) == after_first
+
+
+async def test_regenerate_definition_scope_rematerializes(
+    admin_api: SimpleNamespace,
+) -> None:
+    """The definition scope rebuilds that definition's horizon, twice, stably.
+
+    Creating a definition through the admin route materializes NOTHING
+    (the core's create path does not regenerate); the scoped regenerate
+    call is what materializes its instances, and re-running it leaves
+    the row count exactly where the first run left it.
+    """
+    client = admin_api.client
+    database = admin_api.database
+    ada = await _create_child(client, "Ada")
+    definition_id = await _create_daily_definition(client, [ada])
+
+    assert await _instance_count(database) == 0
+
+    first = await client.post(
+        "/api/v1/admin/regenerate",
+        json={"scope": "definition", "definition_id": definition_id},
+        headers=_admin_headers(),
+    )
+    assert first.status_code == 200
+    body = first.json()
+    assert body["scope"] == "definition"
+    assert body["definition_id"] == definition_id
+    assert body["child_id"] is None
+    assert body["count"] > 0
+    after_first = await _instance_count(database)
+    assert after_first == body["count"]
+
+    second = await client.post(
+        "/api/v1/admin/regenerate",
+        json={"scope": "definition", "definition_id": definition_id},
+        headers=_admin_headers(),
+    )
+    assert second.status_code == 200
+    assert second.json()["count"] == body["count"]
+    assert await _instance_count(database) == after_first
+
+
+async def test_regenerate_child_scope_touches_only_that_child(
+    admin_api: SimpleNamespace,
+) -> None:
+    """The child scope rebuilds that child's rows and no others'.
+
+    Two children share one daily definition; the household walk
+    materializes both.  A child-scoped regenerate for Ada re-runs her
+    side of the walk (same count) while Bo's rows keep their identity,
+    and re-running it never grows the table.
+    """
+    client = admin_api.client
+    database = admin_api.database
+    instances = _dao_instances.QuestInstancesDao(database)
+    ada = await _create_child(client, "Ada")
+    bo = await _create_child(client, "Bo")
+    # One daily definition assigned to BOTH children: the household walk
+    # gives each child its own rows.
+    await _create_daily_definition(client, [ada, bo])
+
+    # Materialize the household first so BOTH children have rows.
+    seeded = await client.post(
+        "/api/v1/admin/regenerate", json={}, headers=_admin_headers()
+    )
+    assert seeded.status_code == 200
+    assert seeded.json()["scope"] == "household"
+
+    ada_rows = await instances.list_by_date_range(
+        ada, "2026-03-02", "2100-01-01"
+    )
+    bo_rows = await instances.list_by_date_range(
+        bo, "2026-03-02", "2100-01-01"
+    )
+    assert ada_rows and bo_rows
+    total = await _instance_count(database)
+    assert total == len(ada_rows) + len(bo_rows)
+
+    for expected_count in (len(ada_rows), len(ada_rows)):
+        response = await client.post(
+            "/api/v1/admin/regenerate",
+            json={"scope": "child", "child_id": ada},
+            headers=_admin_headers(),
+        )
+        assert response.status_code == 200
+        body = response.json()
+        assert body == {
+            "scope": "child",
+            "definition_id": None,
+            "child_id": ada,
+            "count": expected_count,
+        }
+        # Ada's side re-materialized the same number of rows and Bo's
+        # rows kept their identity; the table never grew.
+        assert await instances.list_by_date_range(
+            ada, "2026-03-02", "2100-01-01"
+        )
+        assert await instances.list_by_date_range(
+            bo, "2026-03-02", "2100-01-01"
+        ) == bo_rows
+        assert await _instance_count(database) == total
+
+
+async def test_regenerate_unknown_scope_ids_are_404(
+    admin_api: SimpleNamespace,
+) -> None:
+    """An unknown definition or child scope id is 404, nothing written."""
+    client = admin_api.client
+
+    unknown_definition = await client.post(
+        "/api/v1/admin/regenerate",
+        json={"scope": "definition", "definition_id": 999},
+        headers=_admin_headers(),
+    )
+    assert unknown_definition.status_code == 404
+    assert unknown_definition.json()["detail"] == "Quest definition not found"
+
+    unknown_child = await client.post(
+        "/api/v1/admin/regenerate",
+        json={"scope": "child", "child_id": 999},
+        headers=_admin_headers(),
+    )
+    assert unknown_child.status_code == 404
+    assert unknown_child.json()["detail"] == "Child not found"
+
+    assert await _instance_count(admin_api.database) == 0
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        {"scope": "galaxy"},  # unknown scope
+        {"scope": "definition"},  # scope without its id
+        {"scope": "child"},  # scope without its id
+        {"scope": "household", "child_id": 1},  # id without its scope
+        {"scope": "household", "definition_id": 1},  # id without its scope
+        {
+            "scope": "definition",
+            "definition_id": 1,
+            "child_id": 2,
+        },  # scope mismatch
+        {"scope": "child", "child_id": 0},  # zero id
+        {"scope": "child", "child_id": "seven"},  # wrong type
+    ],
+)
+async def test_regenerate_malformed_bodies_are_422(
+    admin_api: SimpleNamespace, body: dict[str, object]
+) -> None:
+    """Malformed scope/id combinations are 422 before any core call."""
+    response = await admin_api.client.post(
+        "/api/v1/admin/regenerate", json=body, headers=_admin_headers()
+    )
+    assert response.status_code == 422, body
+    assert await _instance_count(admin_api.database) == 0