SSE endpoint publishing quest-completed transitions (task 4d7bae00)

The panel needs live transitions, so add ONE in-process publisher
(api/events.py, installed on app.state.publisher in the lifespan) and
a GET /api/v1/panel/events SSE route on the panel router — it inherits
the single require_panel_token check. The complete route now builds
the event through the core builder and publishes it only when the
core's .appended flag says an actual transition happened; a no-op
re-complete publishes nothing. Tests stream from a real uvicorn
instance on an ephemeral port because httpx's ASGITransport buffers
endless SSE bodies.

api/app.py

@@ -39,6 +39,7 @@ from fastapi import FastAPI
 
 from api.config import ApiConfig
 from api.database import DatabaseState, make_database
+from api.events import TransitionPublisher
 from api.routes_panel import router as panel_router
 
 
@@ -47,12 +48,16 @@ def _build_lifespan(db_path: str):
 
     Captured as a closure so the app factory can hand the configured
     path in without threading it through FastAPI's lifespan signature.
+    The lifespan also installs the app's ONE in-process transition
+    publisher on ``app.state.publisher`` (see :mod:`api.events`) so
+    every route and SSE subscriber shares that single instance.
     """
 
     @asynccontextmanager
     async def lifespan(app: FastAPI) -> AsyncIterator[None]:
         state = make_database(db_path)
         app.state.db = state
+        app.state.publisher = TransitionPublisher()
         try:
             await state.open_and_migrate()
             yield

api/events.py

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

api/nestquest_core.py

@@ -116,6 +116,10 @@ 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 transition-event builders (``core.events.build_quest_completed_event``
+#: et al.) the panel's write routes build their SSE events with.
+core_events = importlib.import_module(f"{_CORE_MODULE_NAME}.events")
+
 #: The explicit settings object (``core.settings.NestQuestSettings``)
 #: the snapshot builder's ``settings`` parameter takes.
 core_settings = importlib.import_module(f"{_CORE_MODULE_NAME}.settings")
@@ -124,6 +128,7 @@ __all__ = [
     "core",
     "core_completion",
     "core_db",
+    "core_events",
     "core_migrations",
     "core_snapshot",
     "core_settings",

api/routes_panel.py

@@ -53,14 +53,19 @@ from __future__ import annotations
 
 import datetime
 import importlib
+import json
+
+from collections.abc import AsyncIterator
 
 from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import StreamingResponse
 from pydantic import BaseModel, field_validator
 
 from api.database import DatabaseState
 from api.dependencies import require_panel_token
 from api.nestquest_core import (
     core_completion,
+    core_events,
     core_settings,
     core_snapshot,
 )
@@ -299,7 +304,57 @@ async def panel_complete_instance(
     # The derived state is "done" in both the appended and no-op cases;
     # ``result.appended`` distinguishes them for callers that care —
     # the panel route returns the same success either way.
+    if result.appended:
+        # An ACTUAL transition: publish the SSE transition event.  The
+        # payload is built by the core builder (never hand-built here)
+        # and fan-out is fire-and-forget (see api/events.py).
+        event_type, payload = await core_events.build_quest_completed_event(
+            database, instance_id, was_on_time=result.was_on_time
+        )
+        request.app.state.publisher.publish(event_type, payload)
     return {"status": str(result)}
 
 
+async def _sse_stream(request: Request) -> AsyncIterator[str]:
+    """Yield the SSE frames for every published transition event.
+
+    One subscriber of the app's single publisher (resolved off
+    ``app.state.publisher``); each event becomes one
+    ``event: <type>\\ndata: <json>\\n\\n`` frame.  Breaking out of the
+    publisher's subscription (on client disconnect) tears the
+    subscription down cleanly — no queue is leaked.
+    """
+    publisher = request.app.state.publisher
+    async for event_type, payload in publisher.subscribe():
+        yield (
+            f"event: {event_type}\n"
+            f"data: {json.dumps(payload)}\n\n"
+        )
+
+
+@router.get(
+    "/events",
+    summary="Stream panel transition events (SSE)",
+)
+async def panel_events(request: Request) -> StreamingResponse:
+    """Stream the app's transition events to the panel (Server-Sent
+    Events).
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency — the ONE
+    token check; this handler performs NO auth of its own).
+
+    Returns a ``text/event-stream`` response whose body is produced by
+    :func:`_sse_stream` off the app's single in-process publisher
+    (``app.state.publisher``, installed in the lifespan).  The stream
+    ends when the client disconnects, at which point the subscription
+    is torn down (its queue removed) with nothing leaked.
+    """
+    return StreamingResponse(
+        _sse_stream(request),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache"},
+    )
+
+
 __all__ = ["router"]