Settle the analysis-summary contract, and fix what sub actually means

[adamjohnwright]

Settles every open item in the analysis-summary contract with the website session, and fixes a wrong description of deployed behaviour that the exchange turned up.

The contract is closed

• Presence rides as human, human_iat, human_sub on the caller token, minted only when their Turnstile-backed identity cookie validated. human is absent rather than false, so a missing claim and a failed check are indistinguishable here.
• Freshness is 30 minutes, inclusive — 1800.000s accepted, 1800.001s refused — enforced at both ends so neither side is a single point of failure. They have a test pinned at exactly that edge; we will mirror it.
• The analysis token passes straight through. We already distinguish 404, 410 and the undocumented 500 from a malformed token; a second validator disagrees with the first eventually.
• Refusals carry a reason: no_caller, no_human, stale_human. "Failed" is not something an interface can say to a person, and stale_human is the only refusal a reader can act on. Advisory — an unrecognised value must read as a plain refusal.

The more useful half: sub was documented wrong

I asked for human_sub rather than sub because sub was already taken by an opaque per-visit id. They corrected me: their callerSubject() prefers the identity cookie's subject whenever the reader has passed a challenge, falling back to the per-visit value only when they have not.

So sub has been browser-scoped for every gated reader since the gate shipped, and identity_of has been keying the answer endpoint's backstop limiter on an identifier that lasts as long as that cookie — counting a person across visits, not within one.

That is the stronger throttle and it is kept. No behaviour changes here. What was wrong was caller_token.py's docstring and rate_limit.py's comment, both of which named the fallback case as though it were the only case. Anyone reasoning about a burst on that endpoint had the wrong model, and the analysis-summary limiter would later have looked inexplicably similar to one they believed was scoped differently.

Also written down: while that preference holds, sub and human_sub carry the same value whenever both are present. They stay separate because they mean different things, would diverge the moment the preference changed, and because agreement between them is not a signal anything should test.

Documentation and comments only, no behaviour change. 501 passed, 1 skipped; mypy over all 137 files, ruff and ruff format clean.

🤖 Generated with Claude Code