Count the visits, and say whether anyone got anywhere

A hosted demo raises a question a local app never does: is anyone using it,
and do they reach the part that matters? `/analytics` answers it — visitors,
pages, referrers, countries, devices, which shared scenarios get played, turns
and demo-key spend, API and turn errors, and a funnel from visited to played a
turn to signed up.

Not a third-party script, for reasons specific to this one. The CSP allows
`script-src 'self'`, so a tracker means loosening it; adblockers eat the
popular ones, which silently biases exactly the technical audience this
project gets shown to; and none of them can see the measurement that actually
matters here, which is a turn, not a pageview.

**A visit is a write and never a read.** After the 189x egress fix it would be
perverse to add a feature that reads rows per request, so counts accumulate in
a process-local dict and flush every 60s as UPSERTs. Storage is a generic
`(day, metric, label) -> hits` counter, so measuring something new later costs
a constant rather than a migration, plus one row per visitor per day for the
funnel flags. Every dashboard query is a GROUP BY returning tens of rows
however much traffic sits behind it; a month reads back in a few kilobytes.
The buffer's cost is that a hard restart can lose up to a minute — the flusher
also runs on shutdown, and a tier that sleeps when idle sleeps on an empty
buffer anyway.

**The counters are anonymous; the access log beside them is not, on purpose.**
A visitor is `HMAC(secret, "visitor:<user id>")` truncated to 32 chars —
one-way, so `analytics_daily` and `analytics_visitor_days` cannot be joined
back to `users`, and keyed, so no client can compute one. Story content never
reaches that module, and the only content it ever names is a seeded public
scenario's title; a player's own titles are theirs. `accesslog.py` is the
identifying half and is a separate module writing a separate table so that
separation is a property of the code rather than a convention: `access_events`
records sessions, sign-ins, registrations and failed attempts with address,
email and device, read on a second tab of the same page behind the same gate.

Both halves are gated on `AIDND_ANALYTICS_EMAILS`, not `POWER_USERS`. An
unmetered tester is not automatically someone who should see the traffic. The
route 404s and the nav link is absent for everyone else, the same treatment
AI Chat gets; unset in a hosted deploy means nobody sees it, including me.

Three things came out of building it that a test would not have suggested.

**A failed turn is an HTTP 200 with a bad ending.** The status-code middleware
cannot see one, so a demo whose model had started refusing every request would
look perfectly healthy from outside. All five SSE error paths in
`_generate_turn` now go through a `turn_error()` helper that counts on the way
out. Error buckets elsewhere are labelled by the matched route template rather
than the requested path — one bucket per endpoint instead of one per adventure
id, and, the reason it isn't merely tidier, an unmatched path is entirely
attacker-chosen, so labelling by it would let anyone mint rows.

**The funnel counts people, not clicks.** A player who starts six adventures
is one person who started an adventure. That is the whole reason the
per-visitor-day table exists; its flags only ever turn on, and `is_new` is
settled by the first write of a visitor's first day.

**The tests run on SQLite and production is Neon.** A flush that raises is
caught and logged, so a dialect mistake in the UPSERTs would have stayed
invisible until the dashboard quietly never filled.
`test_the_upserts_compile_for_postgres` compiles both statements against the
Postgres dialect without connecting to one.

Two things this leans on elsewhere. `limits._client_ip` is now public
`client_ip`: the access log needs the same answer, and two functions both
deciding which hop is the caller's is how one of them ends up trusting a
header it shouldn't. And the cleanup sweeper now starts if *either* job has
work — a deployment can keep every guest forever and still want its
visitor-day rows aged out.

No migration. Both tables are new and `bootstrap()` calls `create_all` on
existing databases too, the route `branches` took in Phase 14, so
`LATEST_VERSION` is still 64.

497 tests green, frontend lint and build clean, driven by hand against a
synthetic 90-day fixture at 1568px. The narrow-screen layout follows the
existing 720px block but is unverified: `resize_window` is ignored on a
maximized Chrome and `frame-ancestors 'none'` rules out checking it in a sized
iframe. Also repaired here: a rename in test_ratelimit_hardening.py had run
through the test names themselves, leaving `testclient_ip_*` — still collected
by pytest, which is why it passed unnoticed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DfMCsN1KBLsTqMkj5hSgrY

backend/app/routers/adventures.py

@@ -9,8 +9,8 @@ from sqlalchemy.orm import Session, load_only, undefer
 from sqlalchemy.orm.attributes import set_committed_value
 
 from .. import (
-    attempts, auth, bundle, images, limits, memorybank, models, schemas, tree,
-    worldstate,
+    analytics, attempts, auth, bundle, images, limits, memorybank, models, schemas,
+    tree, worldstate,
 )
 from ..context import build_context, cursors
 from ..context import history as context_history
@@ -411,6 +411,12 @@ def create_adventure(
 
     db.commit()
     db.refresh(adventure)
+    analytics.record_event(analytics.EV_ADVENTURE, user)
+    # Which of the shared scenarios people actually pick — the one piece of
+    # content this module ever names, and only ever a seeded/public one. A
+    # player's own scenario titles are theirs.
+    if scenario is not None and scenario.is_public:
+        analytics.record(analytics.M_SCENARIO, scenario.title)
     return adventure
 
 
@@ -589,6 +595,15 @@ def sse(obj: dict) -> str:
     return f"data: {json.dumps(obj)}\n\n"
 
 
+def turn_error(detail: str, **extra) -> str:
+    """An SSE error for a turn that could not be produced, counted on the way
+    out. Worth its own event: a failed turn is an HTTP 200 with a bad ending,
+    so the middleware's status-code tally cannot see it — a demo whose model
+    has started refusing every request looks perfectly healthy from outside."""
+    analytics.record(analytics.M_EVENT, analytics.EV_TURN_ERROR)
+    return sse({"type": "error", "detail": detail, **extra})
+
+
 # no-cache defeats any intermediary caching; X-Accel-Buffering makes
 # nginx-style reverse proxies (hosted deploys) flush each event immediately
 # instead of buffering the stream.
@@ -745,7 +760,7 @@ async def _generate_turn(
                 chunks.append(chunk)
                 yield sse({"type": "chunk", "text": chunk})
     except ProviderError as exc:
-        yield sse({"type": "error", "detail": str(exc)})
+        yield turn_error(str(exc))
         return
 
     text = "".join(chunks).strip()
@@ -763,13 +778,13 @@ async def _generate_turn(
             )
         else:
             detail = "The AI returned an empty response."
-        yield sse({"type": "error", "detail": detail})
+        yield turn_error(detail)
         return
 
     # onOutput
     text, _ = pipeline.run("output", text)
     if not text.strip():
-        yield sse({"type": "error", "detail": "A script's output modifier returned empty text."})
+        yield turn_error("A script's output modifier returned empty text.")
         return
     snapshot["script"] = snapshot["script"] | pipeline.report()
 
@@ -785,7 +800,7 @@ async def _generate_turn(
     if worldstate.has_schema(stat_schema):
         text, delta = worldstate.extract_delta(text)
         if not text.strip():
-            yield sse({"type": "error", "detail": "The AI returned only a state update and no story text."})
+            yield turn_error("The AI returned only a state update and no story text.")
             return
         new_world_state, ws_report = worldstate.apply_delta(
             adventure.world_state, stat_schema, delta, ai_depth
@@ -832,6 +847,12 @@ async def _generate_turn(
         # in the endpoint); failed provider calls above don't reach here.
         auth.count_demo_turn(user)
     db.commit()
+    # Counted here, past every way the turn could still have failed, so the
+    # number means "stories advanced" rather than "requests attempted". The
+    # demo tally is those same turns seen as spend on the server-funded key.
+    analytics.record_event(analytics.EV_TURN, user)
+    if cfg.using_demo:
+        analytics.record(analytics.M_EVENT, analytics.EV_DEMO_TURN)
     db.refresh(ai_action)
     yield _SAVED
     yield sse({"type": "done", "action": action_json(ai_action, db), "script": pipeline.report()})
@@ -876,8 +897,8 @@ async def run_player_turn(
         )
         modified, stop = pipeline.run("input", formatted)
         if not modified.strip():
-            yield sse({"type": "error", "detail": "A script's input modifier returned empty text.",
-                       "script": pipeline.report()})
+            yield turn_error("A script's input modifier returned empty text.",
+                             script=pipeline.report())
             return
         player_action = models.Action(
             adventure_id=adventure.id,
@@ -1800,6 +1821,10 @@ def import_adventure(
 
     db.commit()
     db.refresh(adventure)
+    # Not a funnel step: importing a bundle is something a returning player
+    # does, not a sign a first-time visitor got anywhere. Counted anyway,
+    # because it is the clearest evidence anyone is using the export format.
+    analytics.record_event(analytics.EV_IMPORT, user)
     return adventure
 
 

backend/app/routers/analytics.py

@@ -0,0 +1,137 @@
+"""Visit analytics: one endpoint the browser writes to, one the owner reads.
+
+The split matters. `/collect` is public and takes exactly one fact — which
+page was viewed — because anything a stranger can POST is a number a stranger
+can invent. Everything the dashboard actually relies on (turns, adventures,
+sign-ups, demo spend, errors) is recorded server-side by the code performing
+it, so those counts are as trustworthy as the app itself.
+
+The two reading endpoints are owner-only and 404 for everyone else, the same
+way the AI Chat router does: a feature nobody else can use is better off not
+appearing to exist. `/summary` serves the anonymous counters (analytics.py,
+which stores nothing that points at a person) and `/access` serves the access
+log (accesslog.py, which identifies people on purpose).
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from .. import accesslog, analytics, auth, limits, models
+from ..database import get_db
+
+router = APIRouter(prefix="/api/analytics", tags=["analytics"])
+
+
+def owner(
+    db: Session = Depends(get_db),
+    user: models.User = Depends(auth.get_current_user),
+) -> models.User:
+    """Gate for the reading half. 404, not 403 — see the module docstring."""
+    if not auth.is_owner(user):
+        raise HTTPException(404, "Not found")
+    return user
+
+
+Owner = Depends(owner)
+
+
+class Pageview(BaseModel):
+    """What the SPA reports on a page load or a route change.
+
+    `first` marks a real page load rather than a client-side navigation: the
+    things that describe a *visit* rather than a *view* — where it came from,
+    on what kind of device, from which country — are recorded only then, so a
+    visitor who clicks around five pages is still one referral.
+    """
+
+    path: str = Field("", max_length=300)
+    referrer: str = Field("", max_length=500)
+    first: bool = False
+
+
+@router.post("/collect", status_code=204)
+def collect(
+    payload: Pageview,
+    request: Request,
+    db: Session = Depends(get_db),
+) -> Response:
+    """Record one pageview. Always 204, even when nothing was counted: the
+    browser has no business knowing whether it was."""
+    limits.rate_limit("analytics", request)
+    # Resolved by hand rather than through get_current_user: a pageview that
+    # arrives before /auth/me has minted a session should still be counted as a
+    # view, not turned into a 401 the SPA has to handle.
+    user = (
+        auth.resolve_session_user(request, db)
+        if auth.MULTI_USER
+        else auth.local_user(db)
+    )
+    # The operator's own clicking is not traffic. Only in multi-user mode —
+    # locally everyone is the owner, and excluding them would leave the
+    # dashboard permanently empty on the machine it is developed on.
+    if auth.MULTI_USER and user is not None and auth.is_owner(user):
+        return Response(status_code=204)
+
+    analytics.record(analytics.M_PAGE, analytics.normalize_route(payload.path))
+    analytics.record_visit(user)
+    if payload.first:
+        referrer = analytics.normalize_referrer(
+            payload.referrer, request.url.hostname or ""
+        )
+        if referrer:  # "" means same-origin, which is not a referral
+            analytics.record(analytics.M_REFERRER, referrer)
+        analytics.record(
+            analytics.M_DEVICE,
+            analytics.device_of(request.headers.get("user-agent", "")),
+        )
+        analytics.record(analytics.M_COUNTRY, analytics.country_of(request.headers))
+    return Response(status_code=204)
+
+
+@router.get("/summary")
+def summary(
+    days: int = Query(30, ge=1, le=365),
+    db: Session = Depends(get_db),
+    _user: models.User = Owner,
+) -> dict:
+    """The whole dashboard in one aggregate response — a few kilobytes however
+    much traffic sits behind it."""
+    return analytics.summary(db, days)
+
+
+@router.get("/access")
+def access_log(
+    limit: int = Query(50, ge=1, le=200),
+    before_id: int | None = Query(None),
+    kind: str | None = Query(None),
+    q: str | None = Query(None, max_length=120),
+    db: Session = Depends(get_db),
+    _user: models.User = Owner,
+) -> dict:
+    """A page of the access log, newest first.
+
+    Unlike /summary this returns rows about people, which is the whole point of
+    it — so it is behind the same owner gate, paged rather than dumped, and has
+    no counterpart the people it describes can reach.
+    """
+    page = accesslog.recent(
+        db, limit=limit, before_id=before_id, kind=kind, query=q
+    )
+    return {
+        "events": [
+            {
+                "id": event.id,
+                "at": event.at.isoformat(),
+                "kind": event.kind,
+                "who": event.who,
+                "is_guest": event.is_guest,
+                "ip": event.ip,
+                "country": event.country,
+                "device": event.device,
+                "user_agent": event.user_agent,
+            }
+            for event in page["events"]
+        ],
+        "has_more": page["has_more"],
+    }

backend/app/routers/auth.py

@@ -3,7 +3,7 @@ import re
 from fastapi import APIRouter, Depends, HTTPException, Request, Response
 from sqlalchemy.orm import Session
 
-from .. import auth, cleanup, limits, models, schemas, security
+from .. import accesslog, analytics, auth, cleanup, limits, models, schemas, security
 from ..database import get_db
 from .settings import get_settings
 
@@ -34,6 +34,8 @@ def me_payload(user: models.User, db: Session) -> dict:
         "is_guest": user.is_guest,
         # Trusted testers: unmetered demo turns, plus the AI Chat scratchpad.
         "power_user": auth.is_power_user(user),
+        # Separate allowlist: shows the visit-analytics page and its nav link.
+        "analytics": auth.is_owner(user),
         # How long an idle guest is kept before cleanup deletes it (None when
         # the policy is off). Served rather than hardcoded in the UI so the
         # number a guest is shown is the number actually enforced.
@@ -65,6 +67,9 @@ def me(request: Request, response: Response, db: Session = Depends(get_db)):
             db.add(user)
             db.commit()
             _set_session_cookie(response, user.id)
+    # This endpoint is the SPA's bootstrap call, so it is where a session first
+    # shows itself; accesslog thins the rows down to one per day per address.
+    accesslog.note_session(db, user, request)
     return me_payload(user, db)
 
 
@@ -93,6 +98,8 @@ def register(
     user.password_hash = security.hash_password(payload.password)
     user.is_guest = False
     db.commit()
+    analytics.record_event(analytics.EV_SIGNUP, user)
+    accesslog.record(db, accesslog.REGISTER, request, user=user)
     return me_payload(user, db)
 
 
@@ -119,9 +126,15 @@ def login(
         or not security.verify_password(payload.password, user.password_hash)
     ):
         limits.note_login_failure(email)
+        # Logged with the address that was tried, not the account that owns it:
+        # a guessing run against an address that has no account is exactly the
+        # thing worth being able to see.
+        accesslog.record(db, accesslog.LOGIN_FAILED, request, who=email)
         raise HTTPException(401, "Incorrect email or password.")
     limits.note_login_success(email)
     _set_session_cookie(response, user.id)
+    analytics.record_event(analytics.EV_LOGIN, user)
+    accesslog.record(db, accesslog.LOGIN, request, user=user)
     return me_payload(user, db)
 
 

backend/app/routers/scenarios.py

@@ -3,7 +3,7 @@ from fastapi.responses import Response
 from sqlalchemy import or_
 from sqlalchemy.orm import Session
 
-from .. import auth, images, limits, models, schemas
+from .. import analytics, auth, images, limits, models, schemas
 from ..database import get_db
 
 router = APIRouter(prefix="/api/scenarios", tags=["scenarios"])
@@ -53,7 +53,13 @@ def get_scenario(
     db: Session = Depends(get_db),
     user: models.User = Depends(auth.get_current_user),
 ):
-    return get_scenario_or_404(scenario_id, db, user)
+    scenario = get_scenario_or_404(scenario_id, db, user)
+    # Funnel step. Only for shared scenarios: opening one is the first sign a
+    # visitor is interested, whereas someone editing their own is already past
+    # this point — and their titles are theirs, not a statistic.
+    if scenario.is_public:
+        analytics.record_event(analytics.EV_SCENARIO_OPEN, user)
+    return scenario
 
 
 @router.get("/{scenario_id}/image")