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

@@ -2,7 +2,7 @@ from datetime import datetime, timezone
 
 from sqlalchemy import (
     JSON, Boolean, Column, DateTime, Float, ForeignKey, Index, Integer, LargeBinary,
-    String, Table, Text, event,
+    String, Table, Text, UniqueConstraint, event,
 )
 from sqlalchemy.orm import Mapped, Session, mapped_column, relationship
 
@@ -575,6 +575,93 @@ class Settings(Base):
         return security.decrypt_secret(self.api_key)
 
 
+# ---------- Visit analytics (see analytics.py) ----------
+# Two deliberately dumb tables. Neither can hold anything a player wrote, and
+# neither can be joined back to a `users` row: the visitor column is an HMAC,
+# with no foreign key, so guest cleanup deleting an account leaves the history
+# it contributed to intact and anonymous.
+
+
+class AnalyticsDaily(Base):
+    """One counter: how many times `label` happened within `metric` on `day`.
+
+    A generic (metric, label, hits) triple rather than a column per statistic,
+    so measuring something new later costs a constant instead of a migration.
+    Written only by UPSERT, from a buffer — see analytics.flush.
+    """
+
+    __tablename__ = "analytics_daily"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    day: Mapped[str] = mapped_column(String(10), index=True)  # YYYY-MM-DD, UTC
+    metric: Mapped[str] = mapped_column(String(32))
+    label: Mapped[str] = mapped_column(String(80), default="")
+    hits: Mapped[int] = mapped_column(Integer, default=0)
+
+    # The upsert target: one row per bucket per day, created or incremented.
+    __table_args__ = (
+        UniqueConstraint("day", "metric", "label", name="uq_analytics_daily_bucket"),
+    )
+
+
+class AnalyticsVisitorDay(Base):
+    """One visitor, one day, and which funnel steps they reached on it.
+
+    Exists so the funnel counts people rather than clicks — a player who starts
+    six adventures is one person who started an adventure. `is_new` is set when
+    the visitor has no earlier row, which is also why the visitor column is
+    indexed on its own.
+    """
+
+    __tablename__ = "analytics_visitor_days"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    day: Mapped[str] = mapped_column(String(10))
+    # HMAC of the user id under the app secret; not reversible, not a key.
+    visitor: Mapped[str] = mapped_column(String(32))
+    is_new: Mapped[bool] = mapped_column(Boolean, default=False)
+    opened: Mapped[bool] = mapped_column(Boolean, default=False)
+    created: Mapped[bool] = mapped_column(Boolean, default=False)
+    played: Mapped[bool] = mapped_column(Boolean, default=False)
+    signed_up: Mapped[bool] = mapped_column(Boolean, default=False)
+
+    __table_args__ = (
+        UniqueConstraint("day", "visitor", name="uq_analytics_visitor_day"),
+        Index("ix_analytics_visitor", "visitor"),
+    )
+
+
+class AccessEvent(Base):
+    """One sign-in, registration, failed attempt, or session first-seen.
+
+    The counterpart to the two tables above, and deliberately not mixed in with
+    them: this one identifies people on purpose — address, email, device — so
+    keeping it in its own table (and its own module) means the anonymity of the
+    counters stays a property of the code rather than of a convention.
+
+    `user_id` is a plain integer with no foreign key. An access log that
+    disappeared when the account did would not be an access log, and guest
+    cleanup deletes accounts on a schedule; `who` and `is_guest` are snapshots
+    for the same reason, so a row still reads correctly afterwards.
+    """
+
+    __tablename__ = "access_events"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    at: Mapped[datetime] = mapped_column(DateTime, default=utcnow, index=True)
+    # session | login | register | login_failed
+    kind: Mapped[str] = mapped_column(String(16))
+    user_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # Email for a registered account, "Guest #12" otherwise; for a failed
+    # sign-in, the address that was tried — which is the point of the row.
+    who: Mapped[str] = mapped_column(String(320), default="")
+    is_guest: Mapped[bool] = mapped_column(Boolean, default=False)
+    ip: Mapped[str] = mapped_column(String(45), default="")   # 45 = max IPv6
+    country: Mapped[str] = mapped_column(String(16), default="")
+    device: Mapped[str] = mapped_column(String(16), default="")
+    user_agent: Mapped[str] = mapped_column(String(200), default="")
+
+
 # Phase 14 — the floor under `tree.place_action`.
 #
 # From SP2 a read selects on (branch_id, depth): a node written without them is