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