Contact guardrails: who you can reach

What changed, and why

Two guardrails on who a player may message, added for legal, ethical, and safety reasons — the game puts AI-authored words in a real person's mouth, so the living and the not-yet-historical are off limits.

- Deceased only (#72): a figure is contactable only when we can confirm they have died. Living and undatable figures fail closed. - Require grounding (#73): you can only reach a real figure resolved against Wikipedia/Wikidata. The old free-form fallback — type any name, the AI invents a persona — is gone; an unresolved name is guided to a real match instead.

Both rules are enforced at three layers — the client store gate (UX), the authoritative server re-ground (the guarantee), and the suggester — off one predicate. This guide reads the arc end to end.

One predicate: what 'contactable' means

isDeceased is the single source of truth, shared by the server gate and the suggester. It is deliberately strict: a resolved figure with no death year is living (or too undatable to prove otherwise), so it is not deceased — fail closed.

The transient flag (for fail-closed), isDeceased, and the recent-estimated-death guard.

server/utils/figure-grounding.ts · 323 lines

server/utils/figure-grounding.ts323 lines · TypeScript

⋯ 51 lines hidden (lines 1–51)1/**
* Real-world grounding for historical figures — the backbone of the "timeline RPG"
* direction (see docs/ROADMAP.md). Resolves a free-form name to solid facts so the
* game can show who someone was, validate *when* you may contact them, and feed the
* role-play real dates.
*
* Pipeline (the wiki APIs are open + key-less):
*   1. Wikipedia REST summary — the reliable resolver. It follows redirects and
*      picks the notable article, giving a canonical title, a one-line description,
*      a blurb, a portrait, and the Wikidata item id. (Wikidata search alone is NOT
*      reliable: "Cleopatra" resolves to "female given name", "Genghis Khan" to an
*      Iron Maiden song.)
*   2. Wikidata, looked up by that item id (title as fallback) — structured birth
*      (P569) / death (P570), taking the best-ranked claim that actually carries a
*      date, with sub-year precision surfaced honestly as `circa`.
*   3. If the record still has no birth year, a small AI estimator bridges the gap
*      with circa dates (issue #31) — so a real, resolvable figure keeps their
*      "when" slider even when Wikidata can't date them.
*
* Anything unresolved returns `{ resolved: false }` (with `transient` set when the
* lookup couldn't complete). Contact callers now BLOCK an ungrounded name (#73) —
* only a real, documented figure can be reached — while a transient miss is a retry.
*
* Cache honesty: only definitive answers — a real Wikidata reply (dated or not,
* with the estimator genuinely consulted), a genuine no-such-article miss, a
* disambiguation page — keep the full TTL. A transient failure anywhere on the
* path (a rate-limit 429, a timeout, an estimator outage) gets a short TTL, so
* one blip never poisons a figure for a day.
*/
30import { estimateLifespan } from './lifespan-estimator'
31 
32/** A year on the timeline. `signed` is AD-positive / BCE-negative for comparison. */
33export interface FigureYear {
  year: number
  bce: boolean
  signed: number
  display: string
  /** Approximate: sub-year Wikidata precision (decade/century/…) or an AI estimate. */
  circa?: boolean
40}
41 
42export interface GroundedFigure {
  name: string
  resolved: boolean
  description?: string
  extract?: string
  born?: FigureYear
  died?: FigureYear
  living?: boolean
  thumbnail?: string
  wikiUrl?: string
  /** The lookup couldn't be completed (rate-limit / timeout / outage), so an
   *  unresolved result is "we don't know yet", not "no such person". The contact
   *  gate treats this as a retry rather than a definitive miss — and never as a
   *  free-form pass (#72 / #73). */
  transient?: boolean
57}
58 
59/**
* The deceased-only contact floor (#72): a figure may be reached only once we can
* confirm they have died. A resolved figure with no death year is living (or not
* datable enough to prove otherwise) and is never contactable — fail closed. An
* unresolved name is not deceased here either (the free-form path is removed in #73).
* The canonical predicate, shared by the suggester and the send-message gate; the
* client store inlines the same rule (it can't import this server-only module).
*/
67export function isDeceased(figure: GroundedFigure): boolean {
  return figure.resolved && !!figure.died
69}
⋯ 182 lines hidden (lines 70–251)70 
71/**
* The one header for every Wikipedia / Wikidata call the server makes — grounding,
* the name autocomplete, and the suggester's lookups all share it (issue #58).
* Wikimedia's User-Agent policy wants the client identified plus a reachable CONTACT
* so an operator can be reached about problematic traffic; an agent without one gets
* throttled harder, and rate-limit blips are the dominant real-world failure for the
* autocomplete. A mailto is that contact — the deployed site is auth-gated and the
* repo private, so neither would reach a human. Exported so every caller sends the
* identical compliant string instead of drifting per-feature copies.
*/
81export const WIKI_HEADERS = {
  accept: 'application/json',
  'User-Agent': 'Revisionist/1.0 (timeline RPG; mailto:matthew@mseeks.me)'
84}
85 
86const FULL_TTL_MS = 24 * 60 * 60 * 1000
87const TRANSIENT_TTL_MS = 10 * 60 * 1000
88const WIKIDATA_RETRY_DELAY_MS = 400
89const cache = new Map<string, { value: GroundedFigure; expires: number }>()
90 
91/** Builds a `FigureYear`; the display string owns the "c." honesty marker. */
92export function makeFigureYear(year: number, bce: boolean, circa = false): FigureYear {
  const base = bce ? `${year} BC` : `${year}`
  return {
      year,
      bce,
      signed: bce ? -year : year,
      display: circa ? `c. ${base}` : base,
      ...(circa ? { circa: true } : {})
  }
101}
102 
103/**
* Parses a Wikidata time literal (e.g. "+1856-07-10T..", "-0069-01-13T..") to a year.
* Precision 9 means year-level; anything below (8 decade, 7 century, 6 millennium)
* still carries a representative year in the literal, but only approximately —
* those parse as `circa` rather than being dropped or displayed as exact.
*/
109export function parseWikidataYear(time?: string, precision?: number): FigureYear | undefined {
  if (!time) return undefined
  const m = /^([+-])0*(\d+)-/.exec(time)
  if (!m) return undefined
  const year = parseInt(m[2], 10)
  if (!year) return undefined
  const bce = m[1] === '-'
  return makeFigureYear(year, bce, precision != null && precision < 9)
117}
118 
119/** The slice of the Wikipedia REST summary we actually read. */
120interface WikiSummary {
  type?: string
  title?: string
  description?: string
  extract?: string
  thumbnail?: { source?: string }
  content_urls?: { desktop?: { page?: string } }
  wikibase_item?: string
128}
129 
130/** The slice of a Wikidata date claim we actually read. */
131interface WikidataClaim {
  rank?: string
  mainsnak?: {
      snaktype?: string
      datavalue?: { value?: { time?: string; precision?: number } }
  }
137}
138 
139/** The slice of the Wikidata `wbgetentities` response we actually read. */
140interface WikidataEntities {
  entities?: Record<string, { claims?: Record<string, WikidataClaim[]> }>
142}
143 
144/**
* The best date a claim list actually carries. Wikidata routinely stacks several
* birth/death claims (scholarly guesses, deprecated values, "unknown value"
* placeholders) and the community-preferred one is often NOT first — Moses, Jesus
* and Confucius all keep theirs at index 2. So: only claims whose snak carries a
* real time (somevalue/novalue snaks don't), never deprecated, preferred rank first.
*/
151export function pickClaimYear(claims?: WikidataClaim[]): FigureYear | undefined {
  const usable = (claims ?? []).filter(c =>
      c.rank !== 'deprecated' &&
      c.mainsnak?.snaktype === 'value' &&
      c.mainsnak.datavalue?.value?.time
  )
  const best = usable.find(c => c.rank === 'preferred') ?? usable[0]
  const value = best?.mainsnak?.datavalue?.value
  return parseWikidataYear(value?.time, value?.precision)
160}
161 
162/**
* A fetch that tells a definitive miss from a transient one: 404 means the thing
* genuinely isn't there (cacheable at full TTL), anything else — 429, 5xx, timeout,
* network error — is weather to retry soon, not remember for a day.
*/
167interface FetchOutcome<T> {
  data: T | null
  transient: boolean
170}
171 
172async function fetchJson<T>(url: string): Promise<FetchOutcome<T>> {
  try {
      const res = await fetch(url, { headers: WIKI_HEADERS, signal: AbortSignal.timeout(6000) })
      if (!res.ok) return { data: null, transient: res.status !== 404 }
      return { data: (await res.json()) as T, transient: false }
  } catch {
      return { data: null, transient: true }
  }
180}
181 
182interface WikidataDates {
  born?: FigureYear
  died?: FigureYear
  /** True when we never got a real answer (so the result must not cache long). */
  transient: boolean
187}
188 
189/**
* Birth/death from Wikidata — by item id when the summary supplied one (immune to
* title-matching quirks), by sitelink title otherwise. Rate-limit blips are the
* dominant way dates go missing in practice (a 429 body carries no `entities`), so
* a no-entities response gets one spaced retry before being declared transient.
*/
195async function wikidataDates(qid: string | undefined, title: string): Promise<WikidataDates> {
  const subject = qid
      ? `ids=${encodeURIComponent(qid)}`
      : `sites=enwiki&titles=${encodeURIComponent(title)}&normalize=1`
  const url = `https://www.wikidata.org/w/api.php?action=wbgetentities&${subject}&props=claims&languages=en&format=json&origin=*`
  let outcome = await fetchJson<WikidataEntities>(url)
  if (!outcome.data?.entities) {
      await new Promise(resolve => setTimeout(resolve, WIKIDATA_RETRY_DELAY_MS))
      outcome = await fetchJson<WikidataEntities>(url)
  }
  const entities = outcome.data?.entities
  if (!entities) return { transient: true }
  const id = Object.keys(entities)[0]
  const claims = id ? entities[id]?.claims : undefined
  return { born: pickClaimYear(claims?.P569), died: pickClaimYear(claims?.P570), transient: false }
210}
211 
212/**
* Resolves a name to grounded facts (cached). Never throws; returns
* `{ resolved: false }` when the figure can't be confidently identified.
*/
216export async function groundFigure(rawName: string): Promise<GroundedFigure> {
  const name = (rawName || '').trim()
  if (!name) return { name: '', resolved: false }
219 
  const key = name.toLowerCase()
  const hit = cache.get(key)
  if (hit && hit.expires > Date.now()) return hit.value
223 
  const { value, ttlMs } = await resolve(name)
  cache.set(key, { value, expires: Date.now() + ttlMs })
  return value
227}
228 
229/**
* Keep a URL only if it's a plain http(s) link — drop `javascript:` / `data:` /
* relative values. These come from a remote Wikipedia response and end up bound to
* `:href` / `:src` in the figure dossier; Vue escapes the value but NOT the scheme,
* so a spoofed `javascript:` URL would execute on click. (Surfaced by the
* unsafe-render loop.) Exported for the figure-search route, which binds Wikipedia
* thumbnails the same way.
*/
237export function safeUrl(url?: string): string | undefined {
  if (!url) return undefined
  try {
      const { protocol } = new URL(url)
      return protocol === 'https:' || protocol === 'http:' ? url : undefined
  } catch {
      return undefined
  }
245}
246 
247interface Resolution {
  value: GroundedFigure
  ttlMs: number
250}
251 
252/** A purely AI-estimated death is only trusted as "historical" (and the figure
*  contactable, #72) when it predates this year — a recent estimated death is the
*  least trustworthy signal and could mark a living person dead. Documented deaths
*  are exempt (they're facts). */
256const ESTIMATED_DEATH_HISTORICAL_BEFORE = new Date().getFullYear() - 100
⋯ 31 lines hidden (lines 257–287)257 
258async function resolve(name: string): Promise<Resolution> {
  const summary = await fetchJson<WikiSummary>(
      `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(name)}`
  )
262 
  // No article, or an ambiguous disambiguation page → can't pin a person.
  const article = summary.data
  if (!article || article.type === 'disambiguation' || !article.title) {
      return {
          value: { name, resolved: false, transient: summary.transient },
          ttlMs: summary.transient ? TRANSIENT_TTL_MS : FULL_TTL_MS
      }
  }
271 
  const title: string = article.title
273 
  const dates = await wikidataDates(article.wikibase_item, title)
  let born = dates.born
  let died = dates.died
  let bridgeTransient = false
278 
  // The AI bridge (issue #31): the record knows WHO they are but not WHEN — either
  // Wikidata genuinely has no usable birth claim, or the lookup is down right now.
  // Estimated years arrive marked circa, so the dossier and prompts stay honest.
  // A recorded death is law: the estimate only fills what the record lacks, and an
  // estimate that contradicts the record (born after the documented death) is
  // dropped whole rather than shipped as an incoherent lifespan.
  if (!born) {
      const bridge = await estimateLifespan(title, article.description, article.extract, died?.display)
      bridgeTransient = bridge.transient
      if (bridge.estimate) {
          const estBorn = makeFigureYear(bridge.estimate.born.year, bridge.estimate.born.bce, true)
          if (!died || estBorn.signed <= died.signed) {
              born = estBorn
              // A purely AI-ESTIMATED death is trusted as "deceased" (the floor in
              // #72) only when it's clearly historical. An LLM guess of a RECENT
              // death is exactly what could mark a living person contactable, so we
              // don't promote it — the figure stays `living` and is blocked. A
              // DOCUMENTED death (already in `died`) is a fact and is kept as-is.
              const estDied = bridge.estimate.died
                  ? makeFigureYear(bridge.estimate.died.year, bridge.estimate.died.bce, true)
                  : undefined
              died = died ?? (estDied && estDied.signed <= ESTIMATED_DEATH_HISTORICAL_BEFORE ? estDied : undefined)
          }
⋯ 22 lines hidden (lines 302–323)302        }
  }
304 
  return {
      value: {
          name: title,
          resolved: true,
          description: article.description || undefined,
          extract: article.extract || undefined,
          born,
          died,
          living: !!born && !died,
          thumbnail: safeUrl(article.thumbnail?.source),
          wikiUrl: safeUrl(article.content_urls?.desktop?.page),
          transient: dates.transient || bridgeTransient
      },
      // Anything short of a definitive answer keeps the short TTL: a transient
      // Wikidata miss (even when the estimator papered over it — the next lookup
      // should get a shot at the real dates) and an estimator outage alike.
      ttlMs: dates.transient || bridgeTransient ? TRANSIENT_TTL_MS : FULL_TTL_MS
  }
323}

The client gate (UX)

contactLiveness folds both rules into one getter, in order: an ungrounded name is 'unresolved' (#73); a resolved figure with no death is 'living' (#72); a resolved, deceased figure is then gated to its lifetime. canContact admits only the contactable states, so the Send button disables itself.

The whole rule in one place; 'unknown' survives only for the narrow resolved-deceased edge.

stores/game.ts · 1265 lines

stores/game.ts1265 lines · TypeScript

⋯ 335 lines hidden (lines 1–335)1import { defineStore } from 'pinia'
2import type { GameObjective } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { DiceOutcome } from '~/utils/dice'
13import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
14import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
15 
16export type Valence = 'positive' | 'negative' | 'neutral'
17 
18/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
23export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
27}
28 
29/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
36export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
60}
61 
62/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
67export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
91}
92 
93export type GameStatus = 'playing' | 'victory' | 'defeat'
94 
95/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
102type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
147 
148const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
149const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
150 
151// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
152// suspense, then the die lands and the figure's reply writes itself in, then the
153// timeline shift, then the ledger node — so the resolution reads as one conducted
154// moment instead of everything firing in the same tick. Each component already
155// animates when its own slice of state changes; sequencing the WRITES sequences the
156// animations, with no component coordination. Tuned so the swing lands with the
157// reply's own "ripple" line (~0.55s into its staged reveal).
158export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
159const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
160/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
163function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
167}
168 
169function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
173}
174 
175/** Formats a signed timeline year (AD positive, BCE negative) for display. */
176export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
178}
179 
180/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
181function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
185}
186 
187/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
189function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
192}
193 
194/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
196function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
199}
200 
201export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
202 
203/**
* Game Store — core state for a session of freeform timeline editing.
*/
206export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
295 
  getters: {
      /**
       * Can the player send right now? (messages left, still playing, not
       * mid-request, not rate-limited)
       */
      canSendMessage(): boolean {
          return this.remainingMessages > 0 &&
                 this.gameStatus === 'playing' &&
                 !this.isLoading &&
                 !this.isRateLimited
      },
307 
      /**
       * The conversation thread with a single figure (their turns + the
       * player's turns addressed to them). Each figure keeps a coherent,
       * independent thread.
       */
      conversationWith(): (name: string) => Message[] {
          return (name: string) => this.messageHistory.filter(
              m => m.figureName === name && m.sender !== 'system'
          )
      },
318 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
323 
      /**
       * Whether the active figure can be reached at the chosen `when`.
       *
       * Require grounding (#73): an UNRESOLVED name can't be reached at all —
       * 'unresolved' (free-form contact is removed; the picker guides you to a real
       * match). Deceased-only floor (#72): a RESOLVED figure with no confirmed
       * death is living/undatable and never contactable — 'living', fail closed. A
       * resolved, deceased figure is gated to their lifetime (before-birth /
       * after-death). 'unknown' remains only for a resolved, deceased figure we
       * can't fully place (no birth year, or no contact year chosen yet), which
       * stays permissible.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved) return 'unresolved'
          if (!g.died) return 'living'
          if (!g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          if (this.contactWhen > g.died.signed) return 'after-death'
          return 'ok'
      },
345 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
⋯ 917 lines hidden (lines 349–1265)349        },
350 
      /**
       * The last stand is offered ONLY when the final dispatch can no longer win
       * inside the normal per-turn fuse — from any nearer position an unstaked
       * throw can still land it, and offering the (strictly win-probability-
       * increasing) doubling there would be a dominance trap, not a decision.
       */
      canStake(): boolean {
          return this.remainingMessages === 1 &&
                 this.gameStatus === 'playing' &&
                 (MAX_PROGRESS - this.objectiveProgress) > MAX_PROGRESS_SWING
      },
362 
      /**
       * The active figure's age at the chosen `when` — so the player never has to
       * do lifetime math in their head. Null when we lack a birth year or a chosen
       * year (a resolved figure we can't date, or before a year is chosen). Corrects for the missing year zero
       * when a life spans the BC→AD boundary (1 BC → AD 1 is one year, not two).
       */
      contactAge(): number | null {
          const g = this.figureGrounding
          if (!g?.resolved || !g.born || this.contactWhen == null) return null
          const bornSigned = g.born.signed
          const whenSigned = this.contactWhen
          if (whenSigned < bornSigned) return null // before birth — no meaningful age
          const crossedZero = bornSigned < 0 && whenSigned > 0 ? 1 : 0
          return whenSigned - bornSigned - crossedZero
      },
378 
      /**
       * The causal-chain read for the CURRENT contact — the pre-send ⏳ chip's
       * source, mirroring what the Timeline Engine will compute. Footholds are the
       * objective's anchor year plus every dated change already on the ledger; the
       * gap to the nearest one decays the swing. Null (no chip) for ungrounded
       * contacts or an anchorless objective with no dated changes yet.
       */
      causalChainRead(): ChainStatus | null {
          const footholds = [
              this.currentObjective?.anchorYear,
              ...this.timelineEvents.map(e => e.whenSigned)
          ]
          return chainStatus(this.contactWhen, footholds)
      }
  },
394 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
406 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
415 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
437 
      // ---------- figures ----------
      registerFigure(figure: HistoricalFigure) {
          const existing = this.figures.find(f => f.name === figure.name)
          if (existing) {
              if (figure.era) existing.era = figure.era
              if (figure.descriptor) existing.descriptor = figure.descriptor
          } else {
              this.figures.push({ ...figure })
          }
      },
448 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
452 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch is gated as ungrounded (#73)
       * instead of wearing the PREVIOUS figure's facts, year, and liveness gate —
       * and so the wrong year can never be written into the ledger's whenSigned.
       */
      clearGrounding() {
          this.groundingSeq++ // invalidate any lookup still in flight
          this.figureGrounding = null
          this.contactWhen = null
          this.contactMoment = null
          this.groundingLoading = false
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
      },
470 
      /**
       * Resolves the active figure against the grounding service and defaults the
       * "when" to a point inside any known lifetime. Never throws: an unresolved
       * figure simply clears grounding; an ungrounded contact is then blocked (#73).
       */
      async groundActiveFigure(name: string): Promise<void> {
          const target = (name || '').trim()
          // A new contact makes any prior Archive study stale.
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
          if (!target) {
              this.groundingSeq++ // invalidate any lookup still in flight
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
              this.groundingLoading = false
              return
          }
          // Out-of-order guard: only the LATEST lookup may land. Without it, a slow
          // response for the previous name attaches the wrong dossier (and a wrong
          // figureContext on a fast send) to whatever the player typed next.
          const epoch = this.runEpoch
          const seq = ++this.groundingSeq
          this.groundingLoading = true
          try {
              const grounded = await $fetch('/api/figure', { params: { name: target }, headers: await this.aiHeaders() }) as GroundedFigure
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              this.figureGrounding = grounded
              this.contactMoment = null
              if (grounded?.resolved && grounded.born) {
                  const latest = grounded.died ? grounded.died.signed : new Date().getFullYear()
                  this.contactWhen = Math.round((grounded.born.signed + latest) / 2)
              } else {
                  this.contactWhen = null
              }
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              console.error('Figure grounding failed:', error)
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
          } finally {
              if (epoch === this.runEpoch && seq === this.groundingSeq) this.groundingLoading = false
          }
      },
518 
      /** The current run's id, minted server-side via POST /api/run on first
       *  need. The run is a server fact (a persisted, charged row); the id then
       *  tags every AI call so cost telemetry groups per run, and the gameplay
       *  gate verifies it. Fails CLOSED: if begin-run can't return an id this
       *  REJECTS (no local fallback) — a run we can't back server-side must not
       *  start, or the paywall gate would reject it mid-run anyway. */
      async ensureRunId(): Promise<string> {
          if (this.runId) return this.runId
          // Collapse concurrent first-calls onto ONE begin-run (two overlapping
          // calls would otherwise mint two rows). The epoch guards a resetGame
          // mid-flight — a dead run's id must not become the fresh run's.
          if (!this.runIdInflight) {
              const epoch = this.runEpoch
              this.runIdInflight = (async () => {
                  const res = await $fetch('/api/run', { method: 'POST' }) as { runId?: string }
                  if (!res?.runId) throw new Error('begin-run returned no run id')
                  if (epoch === this.runEpoch) {
                      this.runId = res.runId
                      this.runIdInflight = null
                  }
                  return res.runId
              })().catch((err) => {
                  if (epoch === this.runEpoch) this.runIdInflight = null
                  throw err
              })
          }
          return this.runIdInflight
      },
547 
      /** Headers that tag a server call with the current run (the cost
       *  instrument), minting the run id first if needed. */
      async aiHeaders(base: Record<string, string> = {}): Promise<Record<string, string>> {
          return { ...base, 'x-run-id': await this.ensureRunId() }
      },
553 
      setContactWhen(year: number | null) {
          // Scrubbing the year keeps any pinned month/day — the pin refines
          // whichever year is chosen, it doesn't belong to one.
          this.contactWhen = year
      },
559 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
563 
      /**
       * Studies the active (grounded) figure via the Archivist — an objective-blind
       * brief on who they are AT THE CHOSEN MOMENT, so the player can research in the
       * game instead of a browser tab. The brief is moment-specific, so it's cached
       * against the figure AND the year: move the contact slider and the player can
       * re-study them at the new moment. Graceful on failure (leaves the prior brief).
       * Only resolved figures can be studied — an unresolved name has no record.
       */
      async studyActiveFigure(): Promise<void> {
          const g = this.figureGrounding
          if (!g?.resolved) {
              this.figureStudy = null
              return
          }
          // Cache hit only when both the figure AND the studied year still match.
          if (this.studyFor === g.name && this.studyWhen === this.contactWhen && this.figureStudy) return
580 
          // Capture the moment being studied NOW: the brief describes this figure at
          // this year. If the slider moves mid-flight, recording the live value would
          // mislabel the brief and silently suppress the Re-study button.
          const epoch = this.runEpoch
          const studiedName = g.name
          const studiedWhen = this.contactWhen
          this.studyLoading = true
          this.studyNotice = null
          try {
              const res = await $fetch('/api/research', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      figureName: studiedName,
                      when: studiedWhen != null ? formatContactYear(studiedWhen) : undefined,
                      description: g.description,
                      extract: g.extract
                  }
              }) as { success?: boolean; study?: FigureStudy; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              // If the contact changed mid-flight, the stale-study clear in
              // groundActiveFigure already ran — don't resurrect the old brief.
              if (res?.blocked && this.figureGrounding?.name === studiedName) {
                  this.studyNotice = res.error || 'That study was blocked by content moderation.'
              } else if (res?.success && res.study && this.figureGrounding?.name === studiedName) {
                  this.figureStudy = res.study
                  this.studyFor = studiedName
                  this.studyWhen = studiedWhen
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
617 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
651 
      /**
       * Loads era-relevant figure suggestions for the current objective (the
       * educational on-ramp). Cached per objective; on any failure it leaves the
       * list empty so the UI falls back to its generic starters.
       */
      async loadSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) {
              this.figureSuggestions = []
              this.suggestionsFor = ''
              return
          }
          if (this.suggestionsFor === objective.title && this.figureSuggestions.length) return
665 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch) this.suggestionsLoading = false
          }
      },
698 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
722 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
771 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
777 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
784 
      setRateLimit() {
          this.isRateLimited = true
          const remainingTime = this.lastMessageTime
              ? Math.max(0, RATE_LIMIT_MS - (Date.now() - this.lastMessageTime))
              : 0
          setTimeout(() => { this.isRateLimited = false }, remainingTime || RATE_LIMIT_MS)
      },
792 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
797 
      /**
       * Rolls back an unresolved turn: refunds the spent message and drops the
       * dangling user entry, so the counter and history can't drift out of sync.
       * Used for BOTH failure shapes — a thrown request and a graceful HTTP-200
       * `success:false` — an infra hiccup must never burn one of the five
       * dispatches (or, on the last one, convert into an instant unearned defeat).
       */
      refundUnresolvedTurn() {
          if (this.remainingMessages < TOTAL_MESSAGES) this.remainingMessages++
          for (let i = this.messageHistory.length - 1; i >= 0; i--) {
              if (this.messageHistory[i].sender === 'user') {
                  this.messageHistory.splice(i, 1)
                  break
              }
          }
      },
814 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
818 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
834 
      // ---------- the turn ----------
      /**
       * Sends a 160-char message to a chosen figure and folds the result back
       * into the world: the figure replies + acts, the dice decide the swing,
       * and the Timeline Engine records how history bent.
       *
       * Returns `true` only when the turn actually RESOLVED (a ledger entry
       * landed). A blocked or failed send returns `false` so the composer can
       * keep the player's crafted words instead of wiping them.
       *
       * `opts.stake` arms the last stand — honored only when `canStake` holds
       * (final message, win out of normal reach; the server doubles the resolved
       * swing, both ways, past the usual cap).
       */
      async sendMessage(text: string, figureName?: string, opts?: { stake?: boolean }): Promise<boolean> {
          const target = (figureName ?? this.activeFigureName ?? '').trim()
          const stake = opts?.stake === true && this.canStake
852 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
880 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
888 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
901 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
934 
              if (epoch !== this.runEpoch) return false
936 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
939 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
947 
                  // ---- conducted reveal ----
                  // A beat of suspense (the die keeps shaking) before the result
                  // lands, so the resolution has a moment of anticipation.
                  if (animate) {
                      await wait(REVEAL.suspense)
                      if (epoch !== this.runEpoch) return false
                  }
955 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
980 
                  if (timeline) {
                      // Beat 2 — the timeline shift (the % gauge flies its delta),
                      // timed to land with the reply's own "ripple" line.
                      if (animate) {
                          await wait(REVEAL.swing)
                          if (epoch !== this.runEpoch) return false
                      }
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
993 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
1044 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              void this.refreshChronicle()
          }
          return resolved
      },
1054 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.error = null
          return true
      },
1106 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). Returns null rather than throwing if composing
       * fails, so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(): Promise<GameObjective | null> {
          try {
              const res = await $fetch('/api/objective', { method: 'GET', headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1126 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1144 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1150 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1155 
      /** Records the Stripe-return outcome and refreshes the balance on success
       *  (the webhook credits asynchronously; re-read so the gauge reflects it). */
      async notePurchaseReturn(outcome: 'success' | 'cancel'): Promise<void> {
          this.purchaseNotice = outcome
          this.buyModalOpen = false
          if (outcome === 'success') {
              this.outOfRuns = false
              await this.loadBalance()
          }
      },
1166 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1171 
      /** Loads the run-pack catalog for the paywall. Caches only a NON-empty
       *  result: a transient empty/failed read must not poison the cache and
       *  strand the modal with zero packs for the rest of the session. */
      async loadPacks(): Promise<void> {
          if (this.packs.length) return
          try {
              const res = await $fetch('/api/packs') as { packs?: Pack[] }
              const packs = res?.packs ?? []
              if (packs.length) this.packs = packs
          } catch (error) {
              console.error('Failed to load packs:', error)
          }
      },
1185 
      /** Starts checkout for a pack; returns the Stripe Checkout URL to redirect
       *  to (null on failure). The caller does the redirect. */
      async buyPack(packId: string): Promise<string | null> {
          try {
              const res = await $fetch('/api/checkout', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { packId }
              }) as { url?: string }
              return res?.url ?? null
          } catch (error) {
              console.error('Failed to start checkout:', error)
              return null
          }
      },
1201 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1207 
              const efficiencyRating = rateEfficiency(messagesSaved)
1209 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1220 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1265})

The send is stopped before the network, with an honest, specific reason — still living, couldn't be dated, no record found (or, on a network blip, try again).

Each blocked state gets its own message; nothing is sent.

stores/game.ts · 1265 lines

stores/game.ts1265 lines · TypeScript

⋯ 862 lines hidden (lines 1–862)1import { defineStore } from 'pinia'
2import type { GameObjective } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { DiceOutcome } from '~/utils/dice'
13import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
14import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
15 
16export type Valence = 'positive' | 'negative' | 'neutral'
17 
18/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
23export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
27}
28 
29/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
36export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
60}
61 
62/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
67export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
91}
92 
93export type GameStatus = 'playing' | 'victory' | 'defeat'
94 
95/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
102type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
147 
148const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
149const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
150 
151// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
152// suspense, then the die lands and the figure's reply writes itself in, then the
153// timeline shift, then the ledger node — so the resolution reads as one conducted
154// moment instead of everything firing in the same tick. Each component already
155// animates when its own slice of state changes; sequencing the WRITES sequences the
156// animations, with no component coordination. Tuned so the swing lands with the
157// reply's own "ripple" line (~0.55s into its staged reveal).
158export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
159const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
160/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
163function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
167}
168 
169function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
173}
174 
175/** Formats a signed timeline year (AD positive, BCE negative) for display. */
176export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
178}
179 
180/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
181function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
185}
186 
187/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
189function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
192}
193 
194/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
196function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
199}
200 
201export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
202 
203/**
* Game Store — core state for a session of freeform timeline editing.
*/
206export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
295 
  getters: {
      /**
       * Can the player send right now? (messages left, still playing, not
       * mid-request, not rate-limited)
       */
      canSendMessage(): boolean {
          return this.remainingMessages > 0 &&
                 this.gameStatus === 'playing' &&
                 !this.isLoading &&
                 !this.isRateLimited
      },
307 
      /**
       * The conversation thread with a single figure (their turns + the
       * player's turns addressed to them). Each figure keeps a coherent,
       * independent thread.
       */
      conversationWith(): (name: string) => Message[] {
          return (name: string) => this.messageHistory.filter(
              m => m.figureName === name && m.sender !== 'system'
          )
      },
318 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
323 
      /**
       * Whether the active figure can be reached at the chosen `when`.
       *
       * Require grounding (#73): an UNRESOLVED name can't be reached at all —
       * 'unresolved' (free-form contact is removed; the picker guides you to a real
       * match). Deceased-only floor (#72): a RESOLVED figure with no confirmed
       * death is living/undatable and never contactable — 'living', fail closed. A
       * resolved, deceased figure is gated to their lifetime (before-birth /
       * after-death). 'unknown' remains only for a resolved, deceased figure we
       * can't fully place (no birth year, or no contact year chosen yet), which
       * stays permissible.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved) return 'unresolved'
          if (!g.died) return 'living'
          if (!g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          if (this.contactWhen > g.died.signed) return 'after-death'
          return 'ok'
      },
345 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
350 
      /**
       * The last stand is offered ONLY when the final dispatch can no longer win
       * inside the normal per-turn fuse — from any nearer position an unstaked
       * throw can still land it, and offering the (strictly win-probability-
       * increasing) doubling there would be a dominance trap, not a decision.
       */
      canStake(): boolean {
          return this.remainingMessages === 1 &&
                 this.gameStatus === 'playing' &&
                 (MAX_PROGRESS - this.objectiveProgress) > MAX_PROGRESS_SWING
      },
362 
      /**
       * The active figure's age at the chosen `when` — so the player never has to
       * do lifetime math in their head. Null when we lack a birth year or a chosen
       * year (a resolved figure we can't date, or before a year is chosen). Corrects for the missing year zero
       * when a life spans the BC→AD boundary (1 BC → AD 1 is one year, not two).
       */
      contactAge(): number | null {
          const g = this.figureGrounding
          if (!g?.resolved || !g.born || this.contactWhen == null) return null
          const bornSigned = g.born.signed
          const whenSigned = this.contactWhen
          if (whenSigned < bornSigned) return null // before birth — no meaningful age
          const crossedZero = bornSigned < 0 && whenSigned > 0 ? 1 : 0
          return whenSigned - bornSigned - crossedZero
      },
378 
      /**
       * The causal-chain read for the CURRENT contact — the pre-send ⏳ chip's
       * source, mirroring what the Timeline Engine will compute. Footholds are the
       * objective's anchor year plus every dated change already on the ledger; the
       * gap to the nearest one decays the swing. Null (no chip) for ungrounded
       * contacts or an anchorless objective with no dated changes yet.
       */
      causalChainRead(): ChainStatus | null {
          const footholds = [
              this.currentObjective?.anchorYear,
              ...this.timelineEvents.map(e => e.whenSigned)
          ]
          return chainStatus(this.contactWhen, footholds)
      }
  },
394 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
406 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
415 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
437 
      // ---------- figures ----------
      registerFigure(figure: HistoricalFigure) {
          const existing = this.figures.find(f => f.name === figure.name)
          if (existing) {
              if (figure.era) existing.era = figure.era
              if (figure.descriptor) existing.descriptor = figure.descriptor
          } else {
              this.figures.push({ ...figure })
          }
      },
448 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
452 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch is gated as ungrounded (#73)
       * instead of wearing the PREVIOUS figure's facts, year, and liveness gate —
       * and so the wrong year can never be written into the ledger's whenSigned.
       */
      clearGrounding() {
          this.groundingSeq++ // invalidate any lookup still in flight
          this.figureGrounding = null
          this.contactWhen = null
          this.contactMoment = null
          this.groundingLoading = false
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
      },
470 
      /**
       * Resolves the active figure against the grounding service and defaults the
       * "when" to a point inside any known lifetime. Never throws: an unresolved
       * figure simply clears grounding; an ungrounded contact is then blocked (#73).
       */
      async groundActiveFigure(name: string): Promise<void> {
          const target = (name || '').trim()
          // A new contact makes any prior Archive study stale.
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
          if (!target) {
              this.groundingSeq++ // invalidate any lookup still in flight
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
              this.groundingLoading = false
              return
          }
          // Out-of-order guard: only the LATEST lookup may land. Without it, a slow
          // response for the previous name attaches the wrong dossier (and a wrong
          // figureContext on a fast send) to whatever the player typed next.
          const epoch = this.runEpoch
          const seq = ++this.groundingSeq
          this.groundingLoading = true
          try {
              const grounded = await $fetch('/api/figure', { params: { name: target }, headers: await this.aiHeaders() }) as GroundedFigure
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              this.figureGrounding = grounded
              this.contactMoment = null
              if (grounded?.resolved && grounded.born) {
                  const latest = grounded.died ? grounded.died.signed : new Date().getFullYear()
                  this.contactWhen = Math.round((grounded.born.signed + latest) / 2)
              } else {
                  this.contactWhen = null
              }
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              console.error('Figure grounding failed:', error)
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
          } finally {
              if (epoch === this.runEpoch && seq === this.groundingSeq) this.groundingLoading = false
          }
      },
518 
      /** The current run's id, minted server-side via POST /api/run on first
       *  need. The run is a server fact (a persisted, charged row); the id then
       *  tags every AI call so cost telemetry groups per run, and the gameplay
       *  gate verifies it. Fails CLOSED: if begin-run can't return an id this
       *  REJECTS (no local fallback) — a run we can't back server-side must not
       *  start, or the paywall gate would reject it mid-run anyway. */
      async ensureRunId(): Promise<string> {
          if (this.runId) return this.runId
          // Collapse concurrent first-calls onto ONE begin-run (two overlapping
          // calls would otherwise mint two rows). The epoch guards a resetGame
          // mid-flight — a dead run's id must not become the fresh run's.
          if (!this.runIdInflight) {
              const epoch = this.runEpoch
              this.runIdInflight = (async () => {
                  const res = await $fetch('/api/run', { method: 'POST' }) as { runId?: string }
                  if (!res?.runId) throw new Error('begin-run returned no run id')
                  if (epoch === this.runEpoch) {
                      this.runId = res.runId
                      this.runIdInflight = null
                  }
                  return res.runId
              })().catch((err) => {
                  if (epoch === this.runEpoch) this.runIdInflight = null
                  throw err
              })
          }
          return this.runIdInflight
      },
547 
      /** Headers that tag a server call with the current run (the cost
       *  instrument), minting the run id first if needed. */
      async aiHeaders(base: Record<string, string> = {}): Promise<Record<string, string>> {
          return { ...base, 'x-run-id': await this.ensureRunId() }
      },
553 
      setContactWhen(year: number | null) {
          // Scrubbing the year keeps any pinned month/day — the pin refines
          // whichever year is chosen, it doesn't belong to one.
          this.contactWhen = year
      },
559 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
563 
      /**
       * Studies the active (grounded) figure via the Archivist — an objective-blind
       * brief on who they are AT THE CHOSEN MOMENT, so the player can research in the
       * game instead of a browser tab. The brief is moment-specific, so it's cached
       * against the figure AND the year: move the contact slider and the player can
       * re-study them at the new moment. Graceful on failure (leaves the prior brief).
       * Only resolved figures can be studied — an unresolved name has no record.
       */
      async studyActiveFigure(): Promise<void> {
          const g = this.figureGrounding
          if (!g?.resolved) {
              this.figureStudy = null
              return
          }
          // Cache hit only when both the figure AND the studied year still match.
          if (this.studyFor === g.name && this.studyWhen === this.contactWhen && this.figureStudy) return
580 
          // Capture the moment being studied NOW: the brief describes this figure at
          // this year. If the slider moves mid-flight, recording the live value would
          // mislabel the brief and silently suppress the Re-study button.
          const epoch = this.runEpoch
          const studiedName = g.name
          const studiedWhen = this.contactWhen
          this.studyLoading = true
          this.studyNotice = null
          try {
              const res = await $fetch('/api/research', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      figureName: studiedName,
                      when: studiedWhen != null ? formatContactYear(studiedWhen) : undefined,
                      description: g.description,
                      extract: g.extract
                  }
              }) as { success?: boolean; study?: FigureStudy; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              // If the contact changed mid-flight, the stale-study clear in
              // groundActiveFigure already ran — don't resurrect the old brief.
              if (res?.blocked && this.figureGrounding?.name === studiedName) {
                  this.studyNotice = res.error || 'That study was blocked by content moderation.'
              } else if (res?.success && res.study && this.figureGrounding?.name === studiedName) {
                  this.figureStudy = res.study
                  this.studyFor = studiedName
                  this.studyWhen = studiedWhen
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
617 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
651 
      /**
       * Loads era-relevant figure suggestions for the current objective (the
       * educational on-ramp). Cached per objective; on any failure it leaves the
       * list empty so the UI falls back to its generic starters.
       */
      async loadSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) {
              this.figureSuggestions = []
              this.suggestionsFor = ''
              return
          }
          if (this.suggestionsFor === objective.title && this.figureSuggestions.length) return
665 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch) this.suggestionsLoading = false
          }
      },
698 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
722 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
771 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
777 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
784 
      setRateLimit() {
          this.isRateLimited = true
          const remainingTime = this.lastMessageTime
              ? Math.max(0, RATE_LIMIT_MS - (Date.now() - this.lastMessageTime))
              : 0
          setTimeout(() => { this.isRateLimited = false }, remainingTime || RATE_LIMIT_MS)
      },
792 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
797 
      /**
       * Rolls back an unresolved turn: refunds the spent message and drops the
       * dangling user entry, so the counter and history can't drift out of sync.
       * Used for BOTH failure shapes — a thrown request and a graceful HTTP-200
       * `success:false` — an infra hiccup must never burn one of the five
       * dispatches (or, on the last one, convert into an instant unearned defeat).
       */
      refundUnresolvedTurn() {
          if (this.remainingMessages < TOTAL_MESSAGES) this.remainingMessages++
          for (let i = this.messageHistory.length - 1; i >= 0; i--) {
              if (this.messageHistory[i].sender === 'user') {
                  this.messageHistory.splice(i, 1)
                  break
              }
          }
      },
814 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
818 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
834 
      // ---------- the turn ----------
      /**
       * Sends a 160-char message to a chosen figure and folds the result back
       * into the world: the figure replies + acts, the dice decide the swing,
       * and the Timeline Engine records how history bent.
       *
       * Returns `true` only when the turn actually RESOLVED (a ledger entry
       * landed). A blocked or failed send returns `false` so the composer can
       * keep the player's crafted words instead of wiping them.
       *
       * `opts.stake` arms the last stand — honored only when `canStake` holds
       * (final message, win out of normal reach; the server doubles the resolved
       * swing, both ways, past the usual cap).
       */
      async sendMessage(text: string, figureName?: string, opts?: { stake?: boolean }): Promise<boolean> {
          const target = (figureName ?? this.activeFigureName ?? '').trim()
          const stake = opts?.stake === true && this.canStake
852 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
⋯ 387 lines hidden (lines 879–1265)879            }
880 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
888 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
901 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
934 
              if (epoch !== this.runEpoch) return false
936 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
939 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
947 
                  // ---- conducted reveal ----
                  // A beat of suspense (the die keeps shaking) before the result
                  // lands, so the resolution has a moment of anticipation.
                  if (animate) {
                      await wait(REVEAL.suspense)
                      if (epoch !== this.runEpoch) return false
                  }
955 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
980 
                  if (timeline) {
                      // Beat 2 — the timeline shift (the % gauge flies its delta),
                      // timed to land with the reply's own "ripple" line.
                      if (animate) {
                          await wait(REVEAL.swing)
                          if (epoch !== this.runEpoch) return false
                      }
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
993 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
1044 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              void this.refreshChronicle()
          }
          return resolved
      },
1054 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.error = null
          return true
      },
1106 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). Returns null rather than throwing if composing
       * fails, so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(): Promise<GameObjective | null> {
          try {
              const res = await $fetch('/api/objective', { method: 'GET', headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1126 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1144 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1150 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1155 
      /** Records the Stripe-return outcome and refreshes the balance on success
       *  (the webhook credits asynchronously; re-read so the gauge reflects it). */
      async notePurchaseReturn(outcome: 'success' | 'cancel'): Promise<void> {
          this.purchaseNotice = outcome
          this.buyModalOpen = false
          if (outcome === 'success') {
              this.outOfRuns = false
              await this.loadBalance()
          }
      },
1166 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1171 
      /** Loads the run-pack catalog for the paywall. Caches only a NON-empty
       *  result: a transient empty/failed read must not poison the cache and
       *  strand the modal with zero packs for the rest of the session. */
      async loadPacks(): Promise<void> {
          if (this.packs.length) return
          try {
              const res = await $fetch('/api/packs') as { packs?: Pack[] }
              const packs = res?.packs ?? []
              if (packs.length) this.packs = packs
          } catch (error) {
              console.error('Failed to load packs:', error)
          }
      },
1185 
      /** Starts checkout for a pack; returns the Stripe Checkout URL to redirect
       *  to (null on failure). The caller does the redirect. */
      async buyPack(packId: string): Promise<string | null> {
          try {
              const res = await $fetch('/api/checkout', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { packId }
              }) as { url?: string }
              return res?.url ?? null
          } catch (error) {
              console.error('Failed to start checkout:', error)
              return null
          }
      },
1201 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1207 
              const efficiencyRating = rateEfficiency(messagesSaved)
1209 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1220 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1265})

The authoritative server gate (the guarantee)

The client gate is convenience; a direct POST or a send racing the grounding debounce would skip it. So the turn endpoint re-grounds the name itself — the client payload is untrusted — and blocks. It is cache-backed in the warm path (the same lookup the dossier just did), one bounded call on a cold cache.

resolved-not-deceased → block; unresolved-definitive → block (#73); transient → retry.

server/api/send-message.post.ts · 330 lines

server/api/send-message.post.ts330 lines · TypeScript

⋯ 136 lines hidden (lines 1–136)1import { MAX_MESSAGE_CHARS } from '~/utils/game-config'
2import { toContactMoment, formatContactMoment } from '~/utils/contact-moment'
3import {
  cleanArray,
  cleanString,
  clampInt,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_GROUNDING_CHARS,
  MAX_HISTORY_ENTRIES,
  MAX_LEDGER_SWING,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_TIMELINE_ENTRIES
15} from '~/server/utils/validate'
16 
17export default defineEventHandler(async (event) => {
  // Only allow POST requests
  if (getMethod(event) !== 'POST') {
      throw createError({
          statusCode: 405,
          statusMessage: 'Method Not Allowed'
      })
  }
25 
  const body = await readBody(event)
27 
  // The client UI bounds these, but a direct POST is untrusted and every field
  // below feeds a gpt-5.5 prompt — so validate the boundary here, not just in the
  // store. (Surfaced by the input-validation-gap loop.)
  if (!body || typeof body.message !== 'string' || !body.message.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: message parameter is required'
      })
  }
  if (body.message.trim().length > MAX_MESSAGE_CHARS) {
      throw createError({
          statusCode: 400,
          statusMessage: `Bad Request: message exceeds ${MAX_MESSAGE_CHARS} characters`
      })
  }
  if (typeof body.figureName !== 'string' || !body.figureName.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: figureName parameter is required'
      })
  }
49 
  const { when = null, figureContext = null, objective = null } = body
  const message = body.message.trim()
  // A name is interpolated into every prompt (and the Wikipedia lookup upstream),
  // so it gets a hard cap like every other prompt-feeding string.
  const figure = cleanString(body.figureName, MAX_FIGURE_NAME_CHARS)
  // The grounded contact year (signed: AD positive / BC negative) — anchors the
  // causal-distance read and the character's world-brief. Optional + untrusted.
  const figureYear = typeof body.whenSigned === 'number' && Number.isFinite(body.whenSigned)
      ? clampInt(body.whenSigned, 12000)
      : undefined
  // The pinned moment (issue #32) arrives as untrusted integers and is
  // re-validated here; the display string the prompts see is DERIVED, never
  // the client's. Sub-year detail is prompt flavor only — every mechanic
  // below (world-brief, liveness, the wager) still computes on figureYear.
  const figureMoment = figureYear !== undefined ? toContactMoment(body.whenMonth, body.whenDay) : null
  const whenLabel = figureYear !== undefined ? formatContactMoment(figureYear, figureMoment) : undefined
  // The last-stand wager: the client offers it only on the final dispatch; the
  // doubling is applied after amplification, and the response echoes it.
  const staked = body.stake === true
69 
  // Normalize the objective into the context the Timeline Engine needs (coerced +
  // bounded — a non-string or megabyte field would otherwise reach the prompt raw).
  const objectiveContext = {
      title: cleanString(objective?.title, MAX_OBJECTIVE_TITLE_CHARS) || 'Alter the course of history',
      description: cleanString(objective?.description, MAX_OBJECTIVE_DESC_CHARS) || 'Bend the chain of events toward a better world.',
      era: cleanString(objective?.era, MAX_ERA_CHARS)
  }
  // The objective's far anchor year (signed: AD+/BC−) — the foothold the
  // causal-chain dial decays toward. Optional + untrusted; absent → no-op.
  const objectiveAnchorYear = typeof objective?.anchorYear === 'number' && Number.isFinite(objective.anchorYear)
      ? clampInt(objective.anchorYear, 12000)
      : undefined
82 
  // Sanitize the client-supplied ledger + thread: cap the counts and coerce each
  // field, so a crafted body can't crash a `.map`, forge an unbounded prior
  // history, or amplify token cost.
  const timeline = cleanArray(body.timeline, MAX_TIMELINE_ENTRIES).map((raw) => {
      const e = (raw ?? {}) as Record<string, unknown>
      return {
          era: cleanString(e.era, MAX_ERA_CHARS),
          headline: cleanString(e.headline, MAX_OBJECTIVE_TITLE_CHARS),
          detail: cleanString(e.detail, MAX_OBJECTIVE_DESC_CHARS),
          progressChange: clampInt(e.progressChange, MAX_LEDGER_SWING),
          whenSigned: typeof e.whenSigned === 'number' && Number.isFinite(e.whenSigned)
              ? clampInt(e.whenSigned, 12000)
              : undefined
      }
  })
  const conversationHistory = cleanArray(body.conversationHistory, MAX_HISTORY_ENTRIES)
      .map((raw) => (raw ?? {}) as Record<string, unknown>)
      .filter((m) => (m.sender === 'user' || m.sender === 'ai') && typeof m.text === 'string')
      .map((m) => ({ sender: m.sender as 'user' | 'ai', text: cleanString(m.text, MAX_MESSAGE_CHARS) }))
102 
  try {
      // Paywall enforcement: the run must be charged and owned by this device,
      // or a forged / unpaid run id could draw free generation. Fails open if
      // the balance store is unreachable (see run-guard) so an outage never
      // blocks a legit in-progress run.
      const { runIsActive } = await import('~/server/utils/run-guard')
      if (!(await runIsActive(event))) {
          return {
              success: false as const,
              message: 'Run not active',
              data: { userMessage: message, error: 'This run is no longer active. Start a new run to continue.' }
          }
      }
116 
      const { callCharacterAI, callTimelineAI, callJudgeAI } = await import('~/server/utils/openai')
      const { rollD20, applyCraftModifier } = await import('~/utils/dice')
      const { CRAFT_MODIFIER } = await import('~/utils/craft')
      const { hardBlockCheck, moderateAction } = await import('~/server/utils/moderation')
121 
      // A blocked turn never burns a message: success:false + data.blocked lets
      // the store show a distinct, honest "blocked" banner (not an infra retry).
      const blockedResponse = (reason: string) => ({
          success: false as const,
          message: 'Blocked by moderation',
          data: { userMessage: message, blocked: true as const, moderationReason: reason, error: reason }
      })
129 
      // Moderation, stage 1 — a deterministic hard block on the raw dispatch
      // BEFORE we spend a generation token. The unforgivable categories (sexual
      // content, anything involving minors, self-harm facilitation) need no
      // context; the contextual Sentinel runs post-generation over the exchange.
      const inputBlock = await hardBlockCheck(message, 'turn', 'input')
      if (inputBlock.blocked) return blockedResponse(inputBlock.block.reason)
136 
      // Contact gating, enforced authoritatively here (#72 deceased-only + #73
      // require-grounding): the client payload is untrusted, and a direct POST (or
      // a send racing the grounding debounce) could otherwise reach a living or
      // ungrounded figure. Re-ground the name ourselves — cache-backed in the warm
      // path (the same in-process cache /api/figure just filled), one bounded
      // external lookup on a cold cache — and:
      //   • resolved + not deceased → block (living, or undatable: fail closed)
      //   • unresolved + transient  → retry (a lookup we couldn't complete)
      //   • unresolved + definitive → block (#73: no free-form; reach a real figure)
      // This gate enforces existence + liveness (the safety floor); a deceased
      // figure's lifetime window is a client-side UX nicety (anachronism is
      // mechanically allowed via the wager), so it is deliberately not re-checked here.
      const { groundFigure, isDeceased } = await import('~/server/utils/figure-grounding')
      const grounded = await groundFigure(figure)
      if (grounded.resolved && !isDeceased(grounded)) {
          return blockedResponse('This figure is still living and cannot be contacted — Revisionist only reaches figures from history.')
      }
      if (!grounded.resolved) {
          return grounded.transient
              ? {
                  success: false as const,
                  message: 'Could not verify the figure',
                  data: { userMessage: message, error: "Couldn't reach the record to verify who this is — please try again in a moment." }
              }
              : blockedResponse('No historical record found for this name — reach for a real, documented figure.')
      }
163 
      // The client supplies figureContext (it grounded the figure via /api/figure),
      // so treat it as untrusted: coerce + bound each field before it becomes a
⋯ 165 lines hidden (lines 166–330)166        // "fact" in the character system prompt.
      const grounding = {
          when: whenLabel ?? (cleanString(when, MAX_ERA_CHARS) || undefined),
          // The figure should take a pinned moment with period-appropriate
          // granularity rather than false precision (the prompt line is
          // conditional so year-only turns stay byte-identical).
          momentRefined: figureMoment !== null,
          description: cleanString(figureContext?.description, MAX_GROUNDING_CHARS) || undefined,
          lifespan: cleanString(figureContext?.lifespan, MAX_ERA_CHARS) || undefined
      }
176 
      // Step 1: The Judge grades the dispatch's craft — the one place player skill
      // directly tilts fate. A Judge outage grades 'sound' (modifier 0): an infra
      // hiccup must never tilt the die either way.
      const judged = await callJudgeAI({
          objective: objectiveContext,
          figureName: figure,
          when: grounding.when,
          momentRefined: figureMoment !== null,
          userMessage: message
      })
      const craft = judged.success && judged.judge ? judged.judge.craft : 'sound'
      const craftReason = judged.success && judged.judge ? judged.judge.reason : ''
      const rollModifier = CRAFT_MODIFIER[craft]
190 
      // Step 2: Roll the dice of fate, tilted by craft (clamped to the die's faces).
      const natural = rollD20()
      const diceResult = applyCraftModifier(natural.roll, rollModifier)
194 
      // Step 3: The chosen figure replies and acts, in character, blind to the goal.
      // Grounding (when + real facts) anchors the role-play; the world-brief hands
      // them the altered history their own moment would already know (changes at or
      // before their year), so a turn-4 figure doesn't role-play the unaltered world.
      // Headlines only — `detail` narrates downstream ripples (often stamped with
      // later eras) and would hand the figure the future outright.
      const worldBrief = figureYear === undefined
          ? []
          : timeline
              .filter(e => typeof e.whenSigned === 'number' && e.whenSigned <= figureYear && e.headline)
              .slice(-5)
              .map(e => `${e.era ? `[${e.era}] ` : ''}${e.headline}`)
      const character = await callCharacterAI(figure, message, conversationHistory, diceResult.outcome, grounding, worldBrief)
      if (!character.success || !character.characterResponse) {
          // A model-side safety refusal is a block, not an infra hiccup.
          if (character.refused) return blockedResponse(character.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate character response',
              data: {
                  userMessage: message,
                  error: character.error || 'Character AI failed'
              }
          }
      }
220 
      const reply = character.characterResponse
222 
      // Enforce the message-length constraint on the figure's reply.
      if (reply.message && reply.message.length > MAX_MESSAGE_CHARS) {
          console.warn(`Figure reply exceeded ${MAX_MESSAGE_CHARS} characters (${reply.message.length}); truncating.`)
          reply.message = reply.message.substring(0, MAX_MESSAGE_CHARS - 3) + '...'
      }
228 
      // Step 4: The Timeline Engine judges how the action ripples toward the objective.
      const timelineResult = await callTimelineAI({
          objective: objectiveContext,
          figureName: figure,
          era: reply.era || objectiveContext.era,
          userMessage: message,
          characterMessage: reply.message,
          characterAction: reply.action,
          diceRoll: diceResult.roll,
          diceOutcome: diceResult.outcome,
          timeline,
          figureYear,
          figureMoment: figureMoment ? whenLabel : undefined,
          objectiveAnchorYear
      })
244 
      if (!timelineResult.success || !timelineResult.ripple) {
          if (timelineResult.refused) return blockedResponse(timelineResult.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate timeline analysis',
              data: {
                  userMessage: message,
                  diceRoll: diceResult.roll,
                  diceOutcome: diceResult.outcome,
                  characterResponse: { message: reply.message, action: reply.action },
                  error: timelineResult.error || 'Timeline AI failed'
              }
          }
      }
259 
      const ripple = timelineResult.ripple
261 
      // Moderation, stage 2 — the contextual Sentinel reviews the WHOLE exchange
      // (full thread + this dispatch + the figure's reply and the timeline's
      // narration) against the verbatim Usage Policy, and the detector hard-blocks
      // the outputs. A block here suppresses the reveal: the generated text never
      // ships, and the turn is refunded with an honest banner.
      const moderation = await moderateAction({
          surface: 'turn',
          objective: { title: objectiveContext.title, description: objectiveContext.description },
          figureName: figure,
          era: reply.era || objectiveContext.era,
          conversation: conversationHistory.map(m => ({ role: m.sender === 'user' ? 'user' : 'assistant', text: m.text })),
          userText: message,
          outputs: [reply.message, reply.action, ripple.headline, ripple.detail].filter((t): t is string => !!t)
      })
      if (moderation.blocked) return blockedResponse(moderation.block.reason)
277 
      // The last stand: a staked dispatch doubles its resolved swing, both ways,
      // and may escape the per-turn fuse up to the full meter. The valence badge
      // is re-asserted AFTER the doubling — the sign-guard inside callTimelineAI
      // ran on the pre-stake value, and a doubled swing must wear its own color.
      const { applyStake } = await import('~/utils/swing-bands')
      const finalProgressChange = staked ? applyStake(ripple.progressChange) : ripple.progressChange
      const finalValence = staked && Math.abs(finalProgressChange) > 3
          ? (finalProgressChange > 0 ? 'positive' as const : 'negative' as const)
          : ripple.valence
287 
      return {
          success: true,
          message: 'Timeline updated',
          data: {
              userMessage: message,
              figure: {
                  name: figure,
                  era: reply.era,
                  descriptor: reply.persona
              },
              // The effective (craft-tilted) roll drives the bands and the UI; the
              // natural roll + modifier ride along so the reveal can show the tilt.
              diceRoll: diceResult.roll,
              diceOutcome: diceResult.outcome,
              naturalRoll: natural.roll,
              rollModifier,
              craft,
              craftReason,
              staked,
              characterResponse: { message: reply.message, action: reply.action },
              timeline: {
                  headline: ripple.headline,
                  detail: ripple.detail,
                  era: reply.era || objectiveContext.era,
                  progressChange: finalProgressChange,
                  baseProgressChange: ripple.baseProgressChange,
                  valence: finalValence,
                  anachronism: ripple.anachronism,
                  causalChain: ripple.causalChain
              },
              error: null
          }
      }
  } catch (error) {
      // Log the detail server-side; the wire gets a clean line (internal error
      // text — stack hints, key issues, SDK messages — is not for the client).
      console.error('API endpoint error:', error)
      throw createError({
          statusCode: 500,
          statusMessage: 'Internal Server Error'
      })
  }
330})

The same re-ground gate on the research surface.

server/api/research.post.ts · 89 lines

server/api/research.post.ts89 lines · TypeScript

⋯ 50 lines hidden (lines 1–50)1import { cleanString, MAX_ERA_CHARS, MAX_GROUNDING_CHARS } from '~/server/utils/validate'
2 
3// The Wikipedia extract is longer than the other grounded fields; give it room.
4const MAX_EXTRACT_CHARS = 1500
5 
6/**
* POST /api/research — the Archivist (prototype). Given a figure (and the year the
* player means to reach them, plus the grounded facts the client already holds), it
* returns a green-level, OBJECTIVE-BLIND brief: who they are at that moment, what
* they grasp, what they're reaching for, what they cannot yet know. In-game research
* so the player needn't break out to a search engine.
*
* Like the other AI routes, the untrusted body is coerced + bounded before it feeds
* the prompt. A model failure self-heals to { success: false } — the caller simply
* shows nothing.
*/
17export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
21 
  const body = await readBody(event)
  if (!body || typeof body.figureName !== 'string' || !body.figureName.trim()) {
      throw createError({ statusCode: 400, statusMessage: 'Bad Request: figureName is required' })
  }
26 
  const figureName = body.figureName.trim().slice(0, MAX_ERA_CHARS)
  const when = cleanString(body.when, MAX_ERA_CHARS) || undefined
  const description = cleanString(body.description, MAX_GROUNDING_CHARS) || undefined
  const extract = cleanString(body.extract, MAX_EXTRACT_CHARS) || undefined
31 
  try {
      // Paywall enforcement: the Archivist study runs during a charged run, so a
      // forged/unpaid run id must not draw free generation here either.
      const { runIsActive } = await import('~/server/utils/run-guard')
      if (!(await runIsActive(event))) {
          return { success: false, error: 'Run not active' }
      }
39 
      const { callArchivistAI } = await import('~/server/utils/openai')
      const { hardBlockCheck, moderateAction } = await import('~/server/utils/moderation')
42 
      // The Archivist takes untrusted figure text and returns a model brief to the
      // player — the same untrusted-input → model → player path the turn and the
      // Archive lookup gate, so it gets the same two stages: hard-block the input
      // up front, then the Sentinel reviews the generated brief before it ships.
      const subject = [figureName, description, extract].filter(Boolean).join(' — ')
      const inputBlock = await hardBlockCheck(subject, 'research', 'input')
      if (inputBlock.blocked) return { success: false, blocked: true, error: inputBlock.block.reason }
50 
      // Contact gating (#72 deceased-only + #73 require-grounding): the Archivist
      // generates a model brief ABOUT a real person, so it gets the same target
      // gate as a contact. Re-ground and refuse a living/undatable figure; block an
      // ungrounded name (#73: no free-form), retrying only a transient lookup.
      // Single-sourced via isDeceased.
      const { groundFigure, isDeceased } = await import('~/server/utils/figure-grounding')
      const grounded = await groundFigure(figureName)
      if (grounded.resolved && !isDeceased(grounded)) {
          return { success: false, blocked: true, error: 'This figure is still living and cannot be studied — Revisionist only reaches figures from history.' }
      }
      if (!grounded.resolved) {
          return grounded.transient
              ? { success: false, error: "Couldn't reach the record to verify who this is — please try again in a moment." }
              : { success: false, blocked: true, error: 'No historical record found for this name — Revisionist only studies real, documented figures.' }
      }
66 
⋯ 23 lines hidden (lines 67–89)67        const result = await callArchivistAI({ figureName, when, description, extract })
68 
      if (!result.success || !result.study) {
          return { success: false, error: result.error || 'Archivist failed' }
      }
72 
      const s = result.study
      const moderation = await moderateAction({
          surface: 'research',
          figureName,
          era: when,
          userText: subject,
          outputs: [s.atThisMoment, ...(s.grasp ?? []), ...(s.reaching ?? []), s.cannotYetKnow].filter((t): t is string => !!t)
      })
      if (moderation.blocked) return { success: false, blocked: true, error: moderation.block.reason }
82 
      return { success: true, study: result.study }
  } catch (error) {
      console.error('Research endpoint error:', error)
      // Log the detail server-side; the wire gets a clean line.
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
89})

The suggester never offers someone you can't reach

Suggestions are one-tap contacts, so they get the rule too: a deceased-only instruction in the prompt, and — defense in depth against a model that ignores it — a re-ground filter that drops anyone not confirmed deceased before they reach the player. The curated fallback is all-deceased (pinned by a test).

Prompt rule, the keepDeceased filter, and where suggestFigures applies it.

server/utils/figure-suggester.ts · 284 lines

server/utils/figure-suggester.ts284 lines · TypeScript

⋯ 67 lines hidden (lines 1–67)1/**
* Figure suggester — a small tool-using agent (grounding slice 2, see docs/ROADMAP.md).
*
* Given the run's objective, it proposes real historical figures the player could
* message, each with a one-line reason. It's built as a mini-agent: the model may
* call `lookup_figure` (which reuses the Wikidata/Wikipedia grounding) to verify a
* candidate exists and learn their era/role, so suggestions stay accurate rather
* than hallucinated. If the model is unavailable or misbehaves, a curated fallback
* guarantees the player is never left without ideas.
*
* Runs on the lane the routing table picks (ai-routing.ts): the agent loop is
* implemented per provider — the tool-call wire shapes differ — but both share
* the same system prompt, tool contract, and final structured-list schema.
*/
15import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions'
16import type AnthropicSdk from '@anthropic-ai/sdk'
17import { getOpenAIClient, getAnthropicClient } from './ai-gateway'
18import { routeFor } from './ai-routing'
19import { groundFigure, isDeceased, type GroundedFigure } from './figure-grounding'
20 
21export interface FigureSuggestion {
  name: string
  reason: string
  lifespan?: string
25}
26 
27/**
* What the model returns on the wire under the strict schema: `lifespan` is ALWAYS
* present (an empty string when unknown). We type the raw parse against this — not
* the public `FigureSuggestion` — so the schema's contract is honest at the boundary;
* the mapping below turns the empty-string sentinel into the optional public field.
* (Surfaced by the ai-contract-drift loop: schema-required vs type-optional.)
*/
34interface FigureSuggestionWire {
  name: string
  reason: string
  lifespan: string
38}
39 
40export interface SuggestionResult {
  suggestions: FigureSuggestion[]
  fallback: boolean
43}
44 
45interface ObjectiveInput {
  title?: string
  description?: string
  era?: string
49}
50 
51/** Era-agnostic safety net so the player always has somewhere to start. Every name
*  here MUST be a historically deceased figure (the deceased-only floor, #72) — the
*  fallback bypasses the live grounding filter, so a test pins this invariant. */
54const GENERIC_FALLBACK: FigureSuggestion[] = [
  { name: 'Cleopatra', reason: 'A ruler whose alliances reshaped the ancient Mediterranean.' },
  { name: 'Leonardo da Vinci', reason: 'A mind a century ahead — art, war machines, and invention.' },
  { name: 'Genghis Khan', reason: 'Forged the largest contiguous empire in history.' },
  { name: 'Marie Curie', reason: 'A pioneer whose science bent the modern age.' },
  { name: 'Abraham Lincoln', reason: 'Held a fracturing nation together at its hinge point.' }
60]
61 
62function lifespanOf(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
66}
67 
68const SYSTEM = `You are a historian helping a player of a timeline game decide whom to contact. Given their grand objective, propose real historical figures whose decisions could plausibly bend events toward it — spanning the relevant era(s) and the dynamics actually at play. Favor figures with real leverage over the situation, and include a few the player might not think of.
69 
70Only suggest figures who have already died — never anyone still living. Call lookup_figure to confirm a person is real, learn their lifespan and role, and check they are deceased; use it to keep every suggestion accurate and era-appropriate. Don't suggest anyone you can't ground, and drop anyone the lookup shows is still living.`
⋯ 60 lines hidden (lines 71–130)71 
72const LOOKUP_TOOL = {
  name: 'lookup_figure',
  description: 'Verify a real historical figure exists and fetch their lifespan and role.',
  parameters: {
      type: 'object' as const,
      properties: { name: { type: 'string', description: 'The figure’s name to look up' } },
      required: ['name'],
      additionalProperties: false
  }
81}
82 
83const SUGGESTIONS_SCHEMA = {
  type: 'object',
  properties: {
      suggestions: {
          type: 'array',
          items: {
              type: 'object',
              properties: {
                  name: { type: 'string', description: 'The figure’s name' },
                  reason: { type: 'string', description: 'One sentence: why this figure matters for the objective' },
                  lifespan: { type: 'string', description: 'e.g. "69 BC – 30 BC"; empty string if unknown' }
              },
              required: ['name', 'reason', 'lifespan'],
              additionalProperties: false
          }
      }
  },
  required: ['suggestions'],
  additionalProperties: false
102}
103 
104function userBrief(objective: ObjectiveInput): string {
  return `Objective: "${objective.title ?? 'Alter the course of history'}".
106What winning looks like: ${objective.description ?? '—'}
107${objective.era ? `Anchoring era: ${objective.era}` : ''}
108 
109Propose 5 figures the player could message to influence this. Verify each with lookup_figure before finalizing.`
110}
111 
112const FINAL_NUDGE = 'Now give your final answer: the 5 figures, each with a one-sentence reason it matters for this objective.'
113 
114/** Runs one lookup_figure call and shapes the evidence the agent reads. */
115async function runLookup(name: string): Promise<object> {
  const g = name ? await groundFigure(name) : ({ name: '', resolved: false } as GroundedFigure)
  return g.resolved
      ? { resolved: true, name: g.name, role: g.description, lifespan: lifespanOf(g), deceased: isDeceased(g) }
      : { resolved: false }
120}
121 
122function mapWire(raw: unknown): FigureSuggestion[] {
  const parsed = raw as { suggestions?: FigureSuggestionWire[] }
  return (parsed.suggestions ?? [])
      .filter(s => s && s.name && s.reason)
      .map(s => ({ name: s.name, reason: s.reason, lifespan: s.lifespan || undefined }))
      .slice(0, 6)
128}
129 
130/**
* Defense in depth for the deceased-only floor (#72): re-ground every proposed
* figure and keep only the confirmed-deceased ones, so a model that ignores the
* instruction can never surface a living person as a one-tap contact. Grounding is
* usually cached (the agent typically looked these up), so usually near-free — a
* final name that differs from a looked-up one costs a fresh bounded lookup, and a
* transient outage drops that pick (fail closed; the list can fall to the curated
* fallback). We also normalize each lifespan to the grounded record. Exported for
* the unit test.
*/
140export async function keepDeceased(suggestions: FigureSuggestion[]): Promise<FigureSuggestion[]> {
  const checked = await Promise.all(suggestions.map(async (s): Promise<FigureSuggestion | null> => {
      const g = await groundFigure(s.name)
      return isDeceased(g) ? { ...s, lifespan: lifespanOf(g) ?? s.lifespan } : null
  }))
  return checked.filter((s): s is FigureSuggestion => s !== null)
146}
⋯ 123 lines hidden (lines 147–269)147 
148async function runAgentOpenAI(objective: ObjectiveInput): Promise<FigureSuggestion[]> {
  const params = routeFor('suggester').route.openai
  const client = getOpenAIClient()
  const tools: ChatCompletionTool[] = [{
      type: 'function',
      function: {
          name: LOOKUP_TOOL.name,
          description: LOOKUP_TOOL.description,
          parameters: LOOKUP_TOOL.parameters
      }
  }]
  const messages: ChatCompletionMessageParam[] = [
      { role: 'system', content: SYSTEM },
      { role: 'user', content: userBrief(objective) }
  ]
163 
  // Phase 1: let the agent research candidates with the grounding tool.
  for (let round = 0; round < 3; round++) {
      const completion = await client.chat.completions.create({
          model: params.model,
          messages,
          tools,
          tool_choice: 'auto',
          // gpt-5.5 rejects `reasoning_effort` alongside function tools on Chat
          // Completions, so we omit it here (the no-tool phase 2 keeps it).
          max_completion_tokens: params.maxTokens
      })
      const msg = completion.choices?.[0]?.message
      if (!msg) break
      messages.push(msg)
      if (!msg.tool_calls?.length) break
179 
      for (const call of msg.tool_calls) {
          let name = ''
          try { name = JSON.parse(call.function.arguments || '{}').name } catch { /* bad args */ }
          const result = await runLookup(name)
          messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) })
      }
  }
187 
  // Phase 2: force a clean structured list out of the research.
  const final = await client.chat.completions.create({
      model: params.model,
      messages: [...messages, { role: 'user', content: FINAL_NUDGE }],
      reasoning_effort: 'low',
      max_completion_tokens: 1500,
      response_format: {
          type: 'json_schema',
          json_schema: { name: 'figure_suggestions', strict: true, schema: SUGGESTIONS_SCHEMA }
      }
  })
199 
  const content = final.choices?.[0]?.message?.content
  if (!content) return []
  return mapWire(JSON.parse(content))
203}
204 
205async function runAgentAnthropic(objective: ObjectiveInput): Promise<FigureSuggestion[]> {
  const params = routeFor('suggester').route.anthropic
  const client = getAnthropicClient()
  const tools: AnthropicSdk.ToolUnion[] = [{
      name: LOOKUP_TOOL.name,
      description: LOOKUP_TOOL.description,
      input_schema: LOOKUP_TOOL.parameters,
      // Strict tools: the API guarantees the input matches the schema.
      strict: true
  }]
  const messages: AnthropicSdk.MessageParam[] = [
      { role: 'user', content: userBrief(objective) }
  ]
  const common = {
      model: params.model,
      max_tokens: params.maxTokens,
      system: SYSTEM,
      ...(params.temperature !== undefined ? { temperature: params.temperature } : {})
  }
224 
  // Phase 1: the research loop — run tools until the model stops asking.
  for (let round = 0; round < 3; round++) {
      const response = await client.messages.create({ ...common, messages, tools })
      messages.push({ role: 'assistant', content: response.content })
      const toolUses = response.content.filter(
          (b): b is AnthropicSdk.ToolUseBlock => b.type === 'tool_use'
      )
      if (response.stop_reason !== 'tool_use' || !toolUses.length) break
233 
      const results: AnthropicSdk.ToolResultBlockParam[] = []
      for (const use of toolUses) {
          const name = typeof (use.input as { name?: unknown })?.name === 'string'
              ? (use.input as { name: string }).name
              : ''
          results.push({
              type: 'tool_result',
              tool_use_id: use.id,
              content: JSON.stringify(await runLookup(name))
          })
      }
      messages.push({ role: 'user', content: results })
  }
247 
  // Phase 2: force a clean structured list out of the research.
  const final = await client.messages.create({
      ...common,
      max_tokens: 1500,
      messages: [...messages, { role: 'user', content: FINAL_NUDGE }],
      output_config: { format: { type: 'json_schema', schema: SUGGESTIONS_SCHEMA } }
  })
255 
  const text = final.content.find(
      (b): b is AnthropicSdk.TextBlock => b.type === 'text'
  )?.text
  if (!text) return []
  return mapWire(JSON.parse(text))
261}
262 
263/** Suggests era-relevant figures for an objective, with a curated fallback. */
264export async function suggestFigures(objective: ObjectiveInput): Promise<SuggestionResult> {
  try {
      const { lane } = routeFor('suggester')
      const suggestions = lane === 'anthropic'
          ? await runAgentAnthropic(objective)
          : await runAgentOpenAI(objective)
      // Deceased-only floor (#72): re-ground and drop anyone still living before
      // they reach the player. If that empties the list (a fully misbehaving
      // model), fall through to the curated, all-deceased fallback below.
      const deceased = await keepDeceased(suggestions)
      if (deceased.length) return { suggestions: deceased, fallback: false }
  } catch (error) {
⋯ 9 lines hidden (lines 276–284)276        console.error('Figure suggester agent failed; using fallback:', error)
  }
  return { suggestions: GENERIC_FALLBACK, fallback: true }
279}
280 
281/** Exposed for the fallback path + tests. */
282export function fallbackSuggestions(): FigureSuggestion[] {
  return [...GENERIC_FALLBACK]
284}

The dossier tells the truth

The picker stops offering what it can't deliver. A resolved-but-living (or undatable) figure shows an honest block in place of the when-slider; an unresolved name shows a guide to a real match, not a "send into the unknown".

The contactBlocked computed + reason, the block notice, and the unresolved guide.

components/FigurePicker.vue · 536 lines

components/FigurePicker.vue536 lines · Vue

⋯ 63 lines hidden (lines 1–63)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- Deceased-only floor (#72): a living (or undatable) figure can't be
65               reached. Show an honest block in place of the when-control; the send is
66               gated by canContact, and the server re-checks authoritatively. -->
67          <p v-if="contactBlocked" data-testid="contact-blocked" role="alert"
68            class="mt-2.5 border-t rv-line pt-2.5 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
69            <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ contactBlockReason }}
70          </p>
71 
72          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
73               chosen year + live age lead, big and in the accent, so the moment you're
74               writing into is the loudest thing in the dossier (not a buried micro-row). -->
75          <div v-else-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
⋯ 84 lines hidden (lines 76–159)76            <div class="flex items-baseline justify-between gap-2">
77              <span id="when-label" class="rv-label">Reach them in</span>
78              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
79                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
80              </span>
81            </div>
82            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
83              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
84              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
85            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
86              <span>{{ grounding.born?.display }} · born</span>
87              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
88            </div>
89 
90            <!-- Pin the moment (issue #32): an optional month/day refinement of the
91                 chosen year. Display + prompt flavor only — the year stays the value
92                 every mechanic computes with, so the wager, world-brief, and liveness
93                 gates are untouched by whatever is pinned here. -->
94            <div class="mt-1.5">
95              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
96                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
97                :disabled="disabled" @click="momentOpen = true">
98                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
99              </button>
100              <div v-else data-testid="moment-picker">
101                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
102                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
103                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
104                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
105                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
106                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
107                </div>
108                <div class="flex items-center gap-1.5 mt-1">
109                  <template v-if="contactMoment">
110                    <label for="moment-day" class="rv-label">day</label>
111                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
112                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
113                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
114                      @input="onDayInput" />
115                  </template>
116                  <button type="button" data-testid="unpin-moment"
117                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
118                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
119                </div>
120              </div>
121            </div>
122          </div>
123 
124          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
125               mysteriously absent control. The copy claims only the lookup outcome
126               (it may be a transient outage, not a dateless record). No manual year
127               here — the contact year prices the anachronism wager, so it stays
128               grounded or unset. -->
129          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
130            No birth year could be found for them — your message will find them in their own time.
131          </p>
132 
133          <!-- The Archive: study who you're reaching, at the chosen moment -->
134          <div v-if="!contactBlocked" data-testid="archive" class="mt-2 border-t rv-line pt-2">
135            <button v-if="!studyShown" type="button" data-testid="study-button"
136              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
137              :disabled="studyLoading || disabled" @click="studyThem">
138              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
139            </button>
140 
141            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
142              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
143              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
144              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
145              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
146              <button v-if="yearMoved" type="button" data-testid="restudy-button"
147                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
148                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
149              </button>
150            </div>
151 
152            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
153              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
154              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
155            </p>
156          </div>
157        </div>
158      </div>
159    </div>
160 
161    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
162      <template v-if="grounding.transient">Couldn't reach the record for "{{ activeName }}" — try again in a moment.</template>
163      <template v-else>No record found for "{{ activeName }}" — reach for a real historical figure (pick a match as you type, or refine the name).</template>
164    </div>
⋯ 66 lines hidden (lines 165–230)165 
166    <!-- Figures already contacted this run -->
167    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
168      <span class="rv-label">contacts</span>
169      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
170        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
171        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
172      </button>
173    </div>
174 
175    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
176    <div class="space-y-1.5">
177      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
178      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
179        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
180        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
181      </p>
182      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
183           generic defaults masquerading as objective-relevant picks. The famous-
184           names fallback appears only AFTER the agent has genuinely come up empty,
185           labeled honestly as what it is. -->
186      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
187        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
188          <span class="skeleton-line w-32" />
189          <span class="skeleton-line w-48 mt-1.5" />
190        </div>
191      </div>
192      <div v-else class="flex flex-col gap-1">
193        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
194          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
195          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
196          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
197          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
198        </button>
199      </div>
200    </div>
201  </div>
202</template>
203 
204<script setup lang="ts">
205/**
206 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
207 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
208 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
209 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
210 */
211import { computed, watch, onMounted, onUnmounted } from 'vue'
212import { useGameStore } from '~/stores/game'
213import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
214import type { FigureSuggestion } from '~/server/utils/figure-suggester'
215 
216const figure = defineModel<string>({ default: '' })
217defineProps<{ disabled?: boolean }>()
218 
219const gameStore = useGameStore()
220const contacted = computed(() => gameStore.figures)
221const figureSuggestions = computed(() => gameStore.figureSuggestions)
222const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
223const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
224const grounding = computed(() => gameStore.figureGrounding)
225const groundingLoading = computed(() => gameStore.groundingLoading)
226const contactWhen = computed(() => gameStore.contactWhen)
227const contactAge = computed(() => gameStore.contactAge)
228const activeName = computed(() => figure.value.trim())
229 
230const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
231// Deceased-only floor (#72): a resolved figure with no confirmed death is living
232// (or undatable) and can't be reached — show a block instead of the when-control.
233const contactBlocked = computed(() => !!(grounding.value?.resolved && !grounding.value.died))
234const contactBlockReason = computed(() => {
235    const g = grounding.value
236    if (!contactBlocked.value || !g) return ''
237    return g.born
238        ? `${g.name} is still living — Revisionist only reaches figures from history.`
239        : `${g.name} couldn't be dated — Revisionist can only reach figures it can place in history.`
240})
241const lifespan = computed(() => {
⋯ 295 lines hidden (lines 242–536)242    const g = grounding.value
243    if (!g?.born) return ''
244    if (g.died) return `${g.born.display} – ${g.died.display}`
245    return g.living ? `${g.born.display} – present` : g.born.display
246})
247const range = computed(() => ({
248    min: grounding.value?.born?.signed ?? 0,
249    max: grounding.value?.died?.signed ?? new Date().getFullYear()
250}))
251const contactMoment = computed(() => gameStore.contactMoment)
252const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
253// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
254// not the raw signed integer the value attribute carries.
255const whenValueText = computed(() =>
256    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
257)
258 
259function onWhenInput(e: Event) {
260    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
261}
262 
263// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
264const momentOpen = ref(false)
265const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
266function pickMonth(month: number) {
267    const current = gameStore.contactMoment
268    if (current?.month === month) return
269    // Switching months keeps the day where it stays valid, clamps where it doesn't.
270    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
271    gameStore.setContactMoment(day ? { month, day } : { month })
272}
273function onDayInput(e: Event) {
274    const current = gameStore.contactMoment
275    if (!current) return
276    const raw = Number((e.target as HTMLInputElement).value)
277    if (!Number.isInteger(raw) || raw < 1) {
278        gameStore.setContactMoment({ month: current.month })
279        return
280    }
281    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
282}
283function unpinMoment() {
284    gameStore.setContactMoment(null)
285    momentOpen.value = false
286}
287 
288// The Archive: study the grounded figure in-game, at the chosen moment.
289const figureStudy = computed(() => gameStore.figureStudy)
290const studyLoading = computed(() => gameStore.studyLoading)
291const studyNotice = computed(() => gameStore.studyNotice)
292const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
293const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
294const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
295const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
296function studyThem() { gameStore.studyActiveFigure() }
297 
298const LOCAL_DEFAULT: FigureSuggestion[] = [
299    { name: 'Cleopatra', reason: '' },
300    { name: 'Nikola Tesla', reason: '' },
301    { name: 'Genghis Khan', reason: '' },
302    { name: 'Marie Curie', reason: '' },
303    { name: 'Leonardo da Vinci', reason: '' }
304]
305const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
306// Pending = in flight, OR simply not yet asked for this objective — the latter
307// covers the first painted frame (loadSuggestions fires onMounted, after render),
308// which would otherwise flash the clickable famous-names fallback for one frame.
309// The store records suggestionsFor even on failure, so a genuine miss still
310// settles into the honest fallback rather than skeletons forever.
311const suggestionsPending = computed(() =>
312    !figureSuggestions.value.length && (
313        suggestionsLoading.value ||
314        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
315    )
316)
317const suggestionsLabel = computed(() =>
318    suggestionsPending.value
319        ? 'finding figures who matter here…'
320        : figureSuggestions.value.length
321            ? 'figures who might matter here'
322            : 'some famous names to start with'
323)
324 
325function select(name: string) {
326    choose(name)
327}
328 
329// --- Name autocomplete (a combobox over Wikipedia title search) ---
330interface SearchResult { name: string; description?: string; thumbnail?: string }
331const searchBoxRef = ref<HTMLElement | null>(null)
332const searchInputRef = ref<HTMLInputElement | null>(null)
333const searchResults = ref<SearchResult[]>([])
334const searchOpen = ref(false)
335// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
336// visible, retryable hint takes the popup so an outage degrades honestly instead
337// of an empty box that reads as "no matches" (issue #58).
338const searchUnavailable = ref(false)
339const activeIndex = ref(-1)
340// The listbox is the result popup; the unavailable hint is a separate, non-listbox
341// surface. aria-expanded / aria-controls track only this.
342const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
343let searchDebounce: ReturnType<typeof setTimeout> | null = null
344let searchSeq = 0
345// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
346// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
347const SEARCH_RETRY_DELAYS_MS = [800, 1600]
348// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
349// the model change it causes must not reopen the dropdown over the fresh dossier.
350let lastChosen = ''
351 
352/** Closing also INVALIDATES any response still in flight: bumping the seq is what
353 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
354 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
355 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
356 *  pop the dropdown (or the unavailable hint) back up unprompted. */
357function closeSearch() {
358    if (searchDebounce) clearTimeout(searchDebounce)
359    searchDebounce = null
360    searchSeq++
361    searchResults.value = []
362    searchOpen.value = false
363    searchUnavailable.value = false
364    activeIndex.value = -1
365}
366 
367/** Deliberate selection from any surface: fill the input and stand down. */
368function choose(name: string) {
369    lastChosen = name
370    figure.value = name
371    closeSearch()
372}
373 
374/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
375async function runSearch(q: string, seq: number, attempt = 0) {
376    try {
377        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
378        if (seq !== searchSeq) return // closed, or a newer keystroke took over
379        const results = res?.results ?? []
380        // Weather, not absence: an empty answer the server marks transient must not
381        // read as "no matches" — keep whatever is showing and retry with backoff.
382        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
383        if (!results.length && res?.transient) {
384            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
385            if (delay != null) {
386                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
387            } else if (!searchResults.value.length) {
388                // Out of retries with nothing to fall back on: say so plainly and
389                // offer a retry, rather than an empty box that looks like "no matches".
390                searchUnavailable.value = true
391                searchOpen.value = true
392                activeIndex.value = -1
393            }
394            return
395        }
396        searchUnavailable.value = false
397        searchResults.value = results
398        searchOpen.value = results.length > 0
399        activeIndex.value = -1
400    } catch {
401        if (seq === searchSeq) closeSearch()
402    }
403}
404 
405/** Manual retry from the "unavailable" hint — refire the search for the current text.
406 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
407 *  a keyboard user activating it would otherwise have focus fall to <body>. */
408function retrySearch() {
409    const q = (figure.value || '').trim()
410    if (q.length < 2) return
411    searchInputRef.value?.focus()
412    searchUnavailable.value = false
413    void runSearch(q, ++searchSeq)
414}
415 
416watch(figure, (name) => {
417    if (searchDebounce) clearTimeout(searchDebounce)
418    const q = (name || '').trim()
419    if (q.length < 2 || q === lastChosen) {
420        closeSearch()
421        // One-shot suppression: it exists to swallow the single model echo a
422        // choice causes. A later deliberate retype of the same name searches again.
423        if (q === lastChosen) lastChosen = ''
424        return
425    }
426    lastChosen = ''
427    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
428    const seq = ++searchSeq
429    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
430})
431 
432function onSearchKeydown(e: KeyboardEvent) {
433    if (e.isComposing) return // IME candidate navigation owns these keys
434    // Escape always dismisses: it must clear a populated listbox OR the unavailable
435    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
436    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
437    // seq). Handled before the guard below, which only covers a populated listbox.
438    if (e.key === 'Escape') {
439        closeSearch()
440        return
441    }
442    if (!searchOpen.value || !searchResults.value.length) {
443        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
444        // (the only recovery after Escape that doesn't require editing the text).
445        if (e.key === 'ArrowDown') {
446            const q = (figure.value || '').trim()
447            if (q.length >= 2) {
448                e.preventDefault()
449                void runSearch(q, ++searchSeq)
450            }
451        }
452        return
453    }
454    if (e.key === 'ArrowDown') {
455        e.preventDefault()
456        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
457    } else if (e.key === 'ArrowUp') {
458        e.preventDefault()
459        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
460    } else if (e.key === 'Enter') {
461        if (activeIndex.value >= 0) {
462            e.preventDefault()
463            choose(searchResults.value[activeIndex.value].name)
464        }
465    }
466    // Escape is handled up top (it must also dismiss the unavailable hint, where
467    // searchResults is empty and this block is skipped).
468}
469 
470/** Close when focus genuinely leaves the combobox (not when it moves within it). */
471function onSearchFocusOut(e: FocusEvent) {
472    const next = e.relatedTarget as Node | null
473    if (next && searchBoxRef.value?.contains(next)) return
474    closeSearch()
475}
476 
477/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
478const searchStatus = computed(() =>
479    searchUnavailable.value
480        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
481        : listboxOpen.value
482            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
483            : ''
484)
485 
486function chipClass(name: string) {
487    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
488}
489function suggestionClass(name: string) {
490    return name === figure.value ? 'rv-tint' : 'rv-hover'
491}
492 
493// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
494// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
495// fired during the debounce/fetch window must go out clean (free-form), never
496// wearing the old figure's facts, year, or liveness gate.
497let debounce: ReturnType<typeof setTimeout> | null = null
498watch(figure, (name) => {
499    if (debounce) clearTimeout(debounce)
500    gameStore.clearGrounding()
501    const trimmed = (name || '').trim()
502    if (!trimmed) return
503    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
504})
505onUnmounted(() => {
506    if (debounce) clearTimeout(debounce)
507    if (searchDebounce) clearTimeout(searchDebounce)
508})
509 
510// Load era-relevant suggestions for the current objective when the board appears.
511onMounted(() => gameStore.loadSuggestions())
512</script>
513 
514<style scoped>
515/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
516   pulse, stilled under reduced motion. Never a clickable fake. */
517.skeleton-line {
518    display: block;
519    height: 10px;
520    border-radius: 2px;
521    background: var(--rv-tint);
522    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
523}
524@keyframes skeleton-pulse {
525    0%, 100% { opacity: .55; }
526    50% { opacity: 1; }
527}
528@media (prefers-reduced-motion: reduce) {
529    .skeleton-line { animation: none; }
530}
531 
532/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
533.search-pop {
534    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
535}
536</style>