Admin routes: history query and CSV export

The admin History screen (ADMIN-SPEC 1g) had no API: the read
primitives existed (append-only completion-event reads, derived-state
missed logic) but nothing assembled them, so the admin PWA could not
render the event log or export it.  Feature 13's export service was
superseded by the Admin PWA and remains unimplemented by design.

Add a Home-Assistant-free core history layer (core/history.py) that
owns every rule so the two routes cannot drift: one query over the
closed due-date range [start, end] for filter all (every completion
event) / reversals (uncompleted only) / missed (DERIVED past-due open
instances via the existing completion.list_missed_for_child rule --
never stored, never appended); strict ISO date and filter validation
raising ValueError naming filter/start/end; and a csv-module serializer
with a stable documented header (ADMIN-SPEC 5 event-row fields) so the
CSV export is the SAME filtered range as the query, through one
export_history_csv call.  Admin routes GET /api/v1/admin/history and
/history.csv are thin adapters on the existing admin router (the one
require_admin dependency; no new auth check), mapping malformed input
to 422 and never 500.  completion_events stays append-only: history
only reads.

Tests (tests/test_api_admin_history.py) drive the ASGI app as an admin
via the shared JWT harness: seeded completion + reversal + past-due
open instances prove each filter's rows, the CSV header/rows via
csv.reader, due-date range scoping, 403/401 refusals, and 422s for
unknown filter, non-strict dates and inverted ranges.

api/nestquest_core.py

@@ -116,6 +116,11 @@ core_snapshot = importlib.import_module(f"{_CORE_MODULE_NAME}.snapshot")
 #: ``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")
@@ -192,6 +197,7 @@ __all__ = [
     "core_dao_rules",
     "core_db",
     "core_events",
+    "core_history",
     "core_materialize",
     "core_migrations",
     "core_presence",

api/routes_admin.py

@@ -92,6 +92,30 @@ pattern over :mod:`nestquest_core.completion` and
   instance.  The response carries the scope, the scoped id (if any)
   and the core's upsert ``count``.
 
+The history routes (task 2d2dda53) follow the same pattern over
+:mod:`nestquest_core.history` — the ONE read-only history layer, which
+owns every rule so the two routes cannot drift:
+
+- ``GET /history?filter=all|reversals|missed&start=YYYY-MM-DD&end=YYYY-MM-DD``
+  returns the history rows for ONE filter over the CLOSED due-date
+  range ``[start, end]``: ``all`` (every completion event — completed
+  AND uncompleted — whose instance is due in the range), ``reversals``
+  (the uncompleted events only) and ``missed`` (the DERIVED past-due
+  open instances, computed by the core's own derive-state rule —
+  ``missed`` is never a stored event_type and nothing is appended).
+  The range scopes by the instance's ``due_date`` (the Feature 13
+  rule: history asks what happened to the tasks due that day), not the
+  event's wall-clock stamp.  The filter and date-range policies live
+  in the core (strict ``YYYY-MM-DD``, ``end >= start``, a
+  ``ValueError`` naming the offending field); the handler is a thin
+  adapter that threads ONE clock read (:func:`_local_now`, the missed
+  derivation's ``today``) and serializes the core's rows.
+- ``GET /history.csv?...`` exports the SAME filtered range as CSV:
+  ONE :func:`nestquest_core.history.export_history_csv` call — the
+  same query path the JSON route uses — answered as ``text/csv`` with
+  a ``Content-Disposition`` attachment filename and the documented,
+  stable header row (Admin spec §5 event-row fields).
+
 Error mapping (every children, quest-definition and presence route,
 deliberately narrow):
 
@@ -141,6 +165,15 @@ deliberately narrow):
   stance.  Every core ``ValueError`` (a rejected horizon, a malformed
   date — unreachable from this body model, but mapped anyway) is 422;
   anything else re-raises.
+- The HISTORY routes have no path ids, so they have no 404 case: a
+  missing query parameter (the request's shape) is FastAPI's 422
+  before any handler code runs, and every core ``ValueError`` — an
+  unknown filter, a non-strict or inverted date range, each naming the
+  offending field (``filter`` / ``start`` / ``end``) — is 422
+  (:func:`_raise_history_error`): well-formed but semantically
+  invalid, the same failure class Pydantic reports.  Only
+  ``ValueError`` is caught, so an unexpected failure re-raises rather
+  than becoming a 4xx.
 
 PATCH edit semantics: the body model's fields are optional and only
 SUPPLIED fields are forwarded (``model_dump(exclude_unset=True)``), so
@@ -154,7 +187,7 @@ from __future__ import annotations
 import datetime
 from typing import Annotated, Literal, NoReturn
 
-from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
 from pydantic import BaseModel, field_validator, model_validator
 
 from api import transitions as api_transitions
@@ -166,6 +199,7 @@ from api.nestquest_core import (
     core_const,
     core_dao_children,
     core_dao_rules,
+    core_history,
     core_materialize,
     core_presence,
     core_presence_management,
@@ -526,6 +560,47 @@ class AdminRegenerateResponse(BaseModel):
     count: int
 
 
+class AdminHistoryRow(BaseModel):
+    """One history row as the admin plane serializes it.
+
+    Mirrors :class:`nestquest_core.history.HistoryRow` — the Admin spec
+    §5 event-row fields, the same set the CSV export's header carries.
+    A stored event carries its UTC ``occurred_at`` stamp and the
+    ``completed``/``uncompleted`` ``event_type``; a derived missed row
+    (``missed`` is NEVER a stored event_type) carries ``event_type``
+    ``'missed'``, ``occurred_at`` ``None`` (there is no event) and the
+    ``nightly sweep`` actor.
+    """
+
+    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
+
+
+class AdminHistoryResponse(BaseModel):
+    """The history query's answer.
+
+    ``filter``/``start``/``end`` echo the request, ``count`` is the row
+    count, and ``rows`` are the core's rows in its deterministic order
+    (``due_date``, then instance, then event id — the per-instance
+    append order, so a completion and its reversal keep their order).
+    """
+
+    filter: str
+    start: str
+    end: str
+    count: int
+    rows: list[AdminHistoryRow]
+
+
 #: 404 detail for a child id the core layer reports as non-existent.
 _CHILD_NOT_FOUND_DETAIL = "Child not found"
 
@@ -646,6 +721,21 @@ def _raise_regenerate_error(error: ValueError) -> NoReturn:
     raise HTTPException(status_code=422, detail=str(error)) from error
 
 
+def _raise_history_error(error: ValueError) -> NoReturn:
+    """Map a core history ``ValueError`` onto 422 and raise it.
+
+    The history routes have no path ids, so they have no 404 case:
+    every ``ValueError`` that survives to here is a rejected argument —
+    an unknown filter, a non-strict date, or an inverted range, each
+    raised by the core naming the offending field (``filter`` /
+    ``start`` / ``end``) BEFORE any read — and is 422 with the core's
+    message as the detail.  Only ``ValueError`` is caught by the
+    handlers, so 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.
 
@@ -1294,4 +1384,109 @@ async def admin_regenerate(
     )
 
 
+def _history_row_response(row: core_history.HistoryRow) -> AdminHistoryRow:
+    """Serialize one core HistoryRow into the documented payload."""
+    return AdminHistoryRow(
+        occurred_at=row.occurred_at,
+        event_type=row.event_type,
+        child_name=row.child_name,
+        child_id=row.child_id,
+        quest_title=row.quest_title,
+        instance_id=row.instance_id,
+        window=row.window,
+        due_date=row.due_date,
+        due_time=row.due_time,
+        actor=row.actor,
+        was_on_time=row.was_on_time,
+    )
+
+
+@router.get(
+    "/history",
+    summary="Query the completion history for one filter and range",
+    response_model=AdminHistoryResponse,
+)
+async def admin_history_query(
+    request: Request,
+    start: str,
+    end: str,
+    filter: str = "all",
+) -> AdminHistoryResponse:
+    """Return the history rows for one filter over the closed range.
+
+    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: ``filter``
+    (default ``all``), ``start`` and ``end`` go straight to
+    :func:`nestquest_core.history.query_history` as STRINGS — the
+    filter policy (``all`` / ``reversals`` / ``missed``) and the
+    date-range policy (strict ``YYYY-MM-DD``, ``end >= start``) live in
+    the core, which raises a ``ValueError`` naming the offending field;
+    the handler only threads ONE clock read (:func:`_local_now`) as the
+    missed derivation's ``today`` and serializes the returned rows.
+    ``start``/``end`` are required query parameters (missing is
+    FastAPI's 422 before any handler code runs); every core
+    ``ValueError`` is 422 (:func:`_raise_history_error`).
+    """
+    state: DatabaseState = request.app.state.db
+    today = _local_now().date()
+    try:
+        rows = await core_history.query_history(
+            state.database, filter, start, end, today=today
+        )
+    except ValueError as error:
+        _raise_history_error(error)
+    return AdminHistoryResponse(
+        filter=filter,
+        start=start,
+        end=end,
+        count=len(rows),
+        rows=[_history_row_response(row) for row in rows],
+    )
+
+
+@router.get(
+    "/history.csv",
+    summary="Export the completion history as CSV",
+    response_class=Response,
+)
+async def admin_history_csv(
+    request: Request,
+    start: str,
+    end: str,
+    filter: str = "all",
+) -> Response:
+    """Export the SAME filtered history range as a CSV attachment.
+
+    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 ONE
+    :func:`nestquest_core.history.export_history_csv` call — the same
+    query path the JSON route uses, so the CSV can never drift from the
+    query's filtered range — with the core's validation policy and the
+    :mod:`csv`-based serialization (stable documented header row, RFC
+    4180 quoting) living in the core.  The answer is ``text/csv`` with
+    a ``Content-Disposition`` attachment filename naming the range;
+    the range is core-validated strict ``YYYY-MM-DD`` by the time the
+    filename is built, so it is injection-safe.  Error mapping is the
+    JSON route's (:func:`_raise_history_error`).
+    """
+    state: DatabaseState = request.app.state.db
+    today = _local_now().date()
+    try:
+        csv_text = await core_history.export_history_csv(
+            state.database, filter, start, end, today=today
+        )
+    except ValueError as error:
+        _raise_history_error(error)
+    filename = f"nestquest-history-{start}-to-{end}.csv"
+    return Response(
+        content=csv_text,
+        media_type="text/csv",
+        headers={
+            "Content-Disposition": f'attachment; filename="{filename}"'
+        },
+    )
+
+
 __all__ = ["router"]