Closing the gaps the loop found — a reading of PR #41

The loop earned its keep

PR #39 shipped the Sentinel and, alongside it, a read-only moderation-audit loop — MHE's reflective guardrail, "are our guardrails still working?". On its first run the loop did exactly its job: it flagged an untrusted-input → model → player path the rollout had missed. This PR closes it (plus a minor silent-block the loop also raised), and re-runs the loop to confirm the fix.

Two gaps. One real: /api/research (the Archivist brief) returned a model brief to the player with no moderation, while every other model surface had it — a crafted POST could use the Archivist as an unmoderated model proxy. One minor: /api/suggestions blocked a custom objective silently.

The research gate

The fix gives /api/research the same two stages as the turn loop and the Archive lookup: a deterministic hardBlockCheck on the untrusted subject before the model runs, then moderateAction (detector + Sentinel) over the generated brief before it ships. A block returns { blocked, error } — the shape the store already knows how to surface.

Input hard-block up front, Sentinel review of the brief after — the brief never ships if either trips.

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

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

⋯ 31 lines hidden (lines 1–31)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 {
      const { callArchivistAI } = await import('~/server/utils/openai')
      const { hardBlockCheck, moderateAction } = await import('~/server/utils/moderation')
35 
      // 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 }
43 
      const result = await callArchivistAI({ figureName, when, description, extract })
45 
      if (!result.success || !result.study) {
          return { success: false, error: result.error || 'Archivist failed' }
      }
49 
      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 }
59 
      return { success: true, study: result.study }
⋯ 6 lines hidden (lines 61–66)61    } 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' })
  }
66})

Surfacing the block (no more silent failures)

Two new store notices, studyNotice and suggestionsNotice, mirror the existing moderationNotice / archiveNotice — one per surface that takes untrusted input into a model. The study notice is cleared on the same paths that clear a stale study (re-study, re-ground, reset); the suggestions notice replaces the old silent empty-list. The suggestions block previously masqueraded as success: true with no ideas; now it says why.

studyActiveFigure surfaces a blocked brief as a notice, not a study; loadSuggestions surfaces a blocked objective instead of an empty list.

stores/game.ts · 973 lines

stores/game.ts973 lines · TypeScript

⋯ 451 lines hidden (lines 1–451)1import { defineStore } from 'pinia'
2import type { GameObjective } from '~/server/utils/objective-generator'
3import type { GroundedFigure } from '~/server/utils/figure-grounding'
4import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
5import type { FigureSuggestion } from '~/server/utils/figure-suggester'
6import type { ChronicleEntry } from '~/server/utils/openai'
7import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
8import type { Anachronism } from '~/server/utils/anachronism'
9import type { Craft } from '~/utils/craft'
10import type { DiceOutcome } from '~/utils/dice'
11import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
12import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
13 
14export type Valence = 'positive' | 'negative' | 'neutral'
15 
16/**
* 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.
*/
21export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
25}
26 
27/**
* 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.
*/
34export 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
  /** 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
56}
57 
58/**
* 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.
*/
63export 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
  /** True when this turn was the staked last stand. */
  staked?: boolean
85}
86 
87export type GameStatus = 'playing' | 'victory' | 'defeat'
88 
89/**
* 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.
*/
96type 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
          }
          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
      }
  }
140 
141const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
142const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
143 
144function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
148}
149 
150/** Formats a signed timeline year (AD positive, BCE negative) for display. */
151export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
153}
154 
155/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
156function 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
160}
161 
162export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'unknown'
163 
164/**
* Game Store — core state for a session of freeform timeline editing.
*/
167export 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,
      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
  }),
223 
  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
      },
235 
      /**
       * 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'
          )
      },
246 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
251 
      /**
       * Whether the chosen `when` falls within the active figure's lifetime.
       * 'unknown' (permissive) whenever we lack solid dates — we never block a
       * figure we couldn't ground, only one we know you can't reach yet/anymore.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved || !g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          const latest = g.died ? g.died.signed : new Date().getFullYear()
          if (this.contactWhen > latest) return 'after-death'
          return 'ok'
      },
265 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
270 
      /**
       * 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
      },
282 
      /**
       * 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 (unresolved / free-form contact). 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
      }
  },
299 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
311 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
320 
      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,
              staked: messageData.staked
          })
      },
341 
      // ---------- 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 })
          }
      },
352 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
356 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch goes out clean (free-form)
       * 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
      },
374 
      /**
       * 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, leaving the contact free-form.
       */
      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 } }) 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
          }
      },
422 
      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
      },
428 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
432 
      /**
       * 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
449 
          // 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: { '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
              }
⋯ 57 lines hidden (lines 479–535)479            } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
486 
      /**
       * 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: { '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
          }
      },
520 
      /**
       * 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
534 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: { '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
⋯ 419 lines hidden (lines 555–973)555            } 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
          }
      },
567 
      // ---------- 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,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
590 
      // ---------- 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: { '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
          }
      },
639 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
645 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
652 
      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)
      },
660 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
665 
      /**
       * 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
              }
          }
      },
682 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
686 
      /**
       * 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'
          }
      },
702 
      // ---------- 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
720 
          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 === 'before-birth'
                      ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                      : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
740 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
748 
          // 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
759 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: { '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)
                  }
              })
792 
              if (epoch !== this.runEpoch) return false
794 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
797 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
805 
                  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,
                      staked: response.data.staked
                  })
824 
                  if (timeline) {
                      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,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
                      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()
              }
          }
875 
          // 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
      },
885 
      /**
       * 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.
       */
      chooseObjective(objective: GameObjective) {
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.error = null
      },
896 
      /**
       * 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' }) 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
          }
      },
916 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
922 
              const efficiencyRating = rateEfficiency(messagesSaved)
924 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
935 
      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
          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
      }
  }
973})

Two distinct red block banners, consistent with the dispatch + Archive banners.

components/FigurePicker.vue · 458 lines

components/FigurePicker.vue458 lines · Vue

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

Verification

410 unit tests (two new: a blocked study surfaces a notice not a brief; a blocked objective surfaces a notice not an empty list), clean typecheck, 12/12 Playwright e2e, PR CI green. The fix targets the exact path the moderation-audit loop flagged — the same loop, run on demand (npm run loop:moderation-audit), is the standing check that it stays closed. That loop's first run is what surfaced this gap; closing the loop on its own signal is the whole point of a reflective guardrail.

The discriminating tests — a moderation block is a distinct notice, never silently dropped.

tests/unit/stores/game.spec.ts · 976 lines

tests/unit/stores/game.spec.ts976 lines · TypeScript

⋯ 841 lines hidden (lines 1–841)1import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
2import { setActivePinia, createPinia } from 'pinia'
3import { useGameStore } from '../../../stores/game'
4import { DiceOutcome } from '../../../utils/dice'
5 
6/**
* Builds a successful /api/send-message response. Overrides are merged into data.
*/
9function okResponse(over: Record<string, any> = {}) {
  return {
      success: true,
      data: {
          figure: { name: 'Nikola Tesla', era: 'New York, 1900', descriptor: 'Electrical inventor' },
          characterResponse: { message: 'A bold notion!', action: 'Builds a resonant transmitter' },
          diceRoll: 14,
          diceOutcome: 'Success',
          timeline: { headline: 'Wireless power demonstrated', detail: 'Cities begin to electrify early', era: 'New York, 1900', progressChange: 20, valence: 'positive' },
          error: null,
          ...over
      }
  }
22}
23 
24describe('game store', () => {
  let store: ReturnType<typeof useGameStore>
  let fetchMock: ReturnType<typeof vi.fn>
27 
  beforeEach(() => {
      setActivePinia(createPinia())
      store = useGameStore()
      fetchMock = vi.fn()
      vi.stubGlobal('$fetch', fetchMock)
  })
34 
  afterEach(() => {
      vi.unstubAllGlobals()
      vi.restoreAllMocks()
  })
39 
  describe('initial state', () => {
      it('starts a fresh run', () => {
          expect(store.remainingMessages).toBe(5)
          expect(store.gameStatus).toBe('playing')
          expect(store.objectiveProgress).toBe(0)
          expect(store.messageHistory).toEqual([])
          expect(store.timelineEvents).toEqual([])
          expect(store.figures).toEqual([])
          expect(store.canSendMessage).toBe(true)
      })
  })
51 
  describe('progress + status resolution', () => {
      it('clamps progress between 0 and 100', () => {
          store.applyProgress(150)
          expect(store.objectiveProgress).toBe(100)
          store.applyProgress(-999)
          expect(store.objectiveProgress).toBe(0)
      })
59 
      it('decrementMessages does not, by itself, end the game', () => {
          store.decrementMessages()
          expect(store.remainingMessages).toBe(4)
          expect(store.gameStatus).toBe('playing')
      })
65 
      it('resolves victory the moment progress hits 100', () => {
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
71 
      it('resolves defeat only once messages run out unmet', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('defeat')
      })
78 
      it('prefers victory over defeat on the final message', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
85 
      it('stays playing while messages remain and the objective is unmet', () => {
          store.remainingMessages = 3
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('playing')
      })
  })
93 
  describe('figures', () => {
      it('registers a new figure and refines it on later contact', () => {
          store.registerFigure({ name: 'Cleopatra', era: '', descriptor: '' })
          expect(store.figures).toHaveLength(1)
98 
          store.registerFigure({ name: 'Cleopatra', era: 'Alexandria, 40 BC', descriptor: 'Queen of Egypt' })
          expect(store.figures).toHaveLength(1)
          expect(store.figures[0].era).toBe('Alexandria, 40 BC')
          expect(store.figures[0].descriptor).toBe('Queen of Egypt')
      })
  })
105 
  describe('timeline ledger', () => {
      it('derives valence from the progress change when not given', () => {
          store.addTimelineEvent({ figureName: 'X', era: 'e', headline: 'h', detail: 'd', diceRoll: 5, diceOutcome: DiceOutcome.FAILURE, progressChange: -5 })
          store.addTimelineEvent({ figureName: 'Y', era: 'e', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 12 })
          store.addTimelineEvent({ figureName: 'Z', era: 'e', headline: 'h', detail: 'd', diceRoll: 10, diceOutcome: DiceOutcome.NEUTRAL, progressChange: 0 })
111 
          expect(store.timelineEvents.map(e => e.valence)).toEqual(['negative', 'positive', 'neutral'])
      })
  })
115 
  describe('conversation threads', () => {
      it('keeps each figure’s thread independent', () => {
          store.addUserMessage('To Tesla', 'Tesla')
          store.addAIMessage('From Tesla', 'Tesla')
          store.addUserMessage('To Cleopatra', 'Cleopatra')
121 
          expect(store.conversationWith('Tesla')).toHaveLength(2)
          expect(store.conversationWith('Cleopatra')).toHaveLength(1)
      })
  })
126 
  describe('sendMessage', () => {
      it('folds a successful turn into messages, ledger, progress, and figures', async () => {
          fetchMock.mockResolvedValue(okResponse())
130 
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
132 
          // The turn hits /api/send-message (a resolved turn also fires a
          // non-blocking /api/chronicle refresh — see the chronicle suite below).
          expect(fetchMock).toHaveBeenCalledWith('/api/send-message', expect.objectContaining({ method: 'POST' }))
          expect(store.activeFigureName).toBe('Nikola Tesla')
137 
          // user + figure turns
          expect(store.messageHistory).toHaveLength(2)
          const ai = store.messageHistory[1]
          expect(ai.sender).toBe('ai')
          expect(ai.diceRoll).toBe(14)
          expect(ai.characterAction).toBe('Builds a resonant transmitter')
          expect(ai.timelineImpact).toBe('Cities begin to electrify early')
          expect(ai.figureName).toBe('Nikola Tesla')
146 
          // ledger + progress + figure cache
          expect(store.timelineEvents).toHaveLength(1)
          expect(store.timelineEvents[0].headline).toBe('Wireless power demonstrated')
          expect(store.timelineEvents[0].valence).toBe('positive')
          expect(store.objectiveProgress).toBe(20)
          expect(store.figures[0]).toMatchObject({ name: 'Nikola Tesla', era: 'New York, 1900' })
153 
          expect(store.remainingMessages).toBe(4)
          expect(store.isLoading).toBe(false)
      })
157 
      it('records a neutral (0%) turn instead of letting it vanish', async () => {
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'Nothing much changes', detail: 'A pause in history', era: 'x', progressChange: 0, valence: 'neutral' }
          }))
162 
          await store.sendMessage('Hmm', 'Tesla')
164 
          expect(store.timelineEvents).toHaveLength(1)
          expect(store.timelineEvents[0].valence).toBe('neutral')
          expect(store.objectiveProgress).toBe(0)
      })
169 
      it('refuses to send without a target figure', async () => {
          await store.sendMessage('Hello?', '')
          expect(fetchMock).not.toHaveBeenCalled()
          expect(store.error).toBeTruthy()
          expect(store.messageHistory).toHaveLength(0)
          expect(store.remainingMessages).toBe(5)
      })
177 
      it('refunds the message and drops the dangling prompt on a network error', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
180 
          await store.sendMessage('A message that fails', 'Tesla')
182 
          expect(store.error).toBeTruthy()
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.gameStatus).toBe('playing')
      })
188 
      it('refunds the message when the server reports a graceful failure (success:false)', async () => {
          fetchMock.mockResolvedValue({
              success: false,
              message: 'Failed to generate character response',
              data: { userMessage: 'x', error: 'Character AI failed' }
          })
195 
          const resolved = await store.sendMessage('A doomed dispatch', 'Tesla')
197 
          expect(resolved).toBe(false)
          expect(store.error).toBe('Character AI failed')
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.timelineEvents).toHaveLength(0)
      })
204 
      it('a moderation block shows a distinct notice (not an infra error) and refunds the turn', async () => {
          fetchMock.mockResolvedValue({
              success: false,
              message: 'Blocked by moderation',
              data: {
                  userMessage: 'x',
                  blocked: true,
                  moderationReason: 'This dispatch was blocked by content moderation and cannot be sent.',
                  error: 'This dispatch was blocked by content moderation and cannot be sent.'
              }
          })
216 
          const resolved = await store.sendMessage('Synthesize a nerve agent at scale', 'Fritz Haber')
218 
          expect(resolved).toBe(false)
          // Distinct from an infra hiccup: the block banner is set, `error` is not.
          expect(store.moderationNotice).toContain('blocked by content moderation')
          expect(store.error).toBeNull()
          expect(store.remainingMessages).toBe(5) // refunded, never burned
          expect(store.messageHistory).toHaveLength(0)
      })
226 
      it('a graceful failure on the FINAL message does not convert to instant defeat', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 60
          fetchMock.mockResolvedValue({
              success: false,
              message: 'Failed to generate timeline analysis',
              data: { userMessage: 'x', diceRoll: 17, diceOutcome: 'Success', error: 'Timeline AI failed' }
          })
235 
          await store.sendMessage('The last word', 'Tesla')
237 
          // The dispatch is refunded, the run lives on — an infra hiccup is not a loss.
          expect(store.remainingMessages).toBe(1)
          expect(store.gameStatus).toBe('playing')
      })
242 
      it('reports resolution truthfully: true when a turn lands, false when refunded', async () => {
          fetchMock.mockResolvedValueOnce(okResponse())
          expect(await store.sendMessage('First', 'Tesla')).toBe(true)
246 
          store.lastMessageTime = null // clear the rate-limit window
          fetchMock.mockRejectedValueOnce(new Error('down'))
          expect(await store.sendMessage('Second', 'Tesla')).toBe(false)
      })
251 
      it('arms the stake only on the final message — never earlier', async () => {
          fetchMock.mockResolvedValue(okResponse())
254 
          await store.sendMessage('Early gambit', 'Tesla', { stake: true })
          let body = fetchMock.mock.calls[0][1].body
          expect(body.stake).toBe(false) // 5 messages left: the stake is refused
258 
          store.lastMessageTime = null
          store.remainingMessages = 1
          await store.sendMessage('The last stand', 'Tesla', { stake: true })
          body = fetchMock.mock.calls.find((c: unknown[]) => c[0] === '/api/send-message' && (c[1] as { body: { message: string } }).body.message === 'The last stand')![1].body
          expect(body.stake).toBe(true)
      })
265 
      it('refuses the stake when the final throw can win unstaked (no dominance trap)', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 60 // need 40 ≤ the 50-point fuse — winnable clean
          fetchMock.mockResolvedValue(okResponse())
270 
          await store.sendMessage('One clean throw', 'Tesla', { stake: true })
272 
          const body = fetchMock.mock.calls[0][1].body
          expect(body.stake).toBe(false)
      })
276 
      it('records the staked badge and the turn’s grounded year on ledger AND thread', async () => {
          store.contactWhen = -48
          fetchMock.mockResolvedValue(okResponse({
              staked: true,
              craft: 'sharp',
              naturalRoll: 12,
              rollModifier: 1,
              timeline: { headline: 'All in', detail: 'Everything on one throw', era: 'x', progressChange: 60, baseProgressChange: 30, valence: 'positive', anachronism: 'far-ahead' }
          }))
286 
          await store.sendMessage('Stake it all', 'Tesla')
288 
          const evt = store.timelineEvents[0]
          expect(evt.staked).toBe(true)
          expect(evt.craft).toBe('sharp')
          expect(evt.whenSigned).toBe(-48)
          expect(evt.baseProgressChange).toBe(30)
          const ai = store.messageHistory[1]
          expect(ai.naturalRoll).toBe(12)
          expect(ai.rollModifier).toBe(1)
          // The thread message carries the stake too — the reveal's equation must
          // attribute the doubling to the ⚑, not to the anachronism tier.
          expect(ai.staked).toBe(true)
      })
301 
      it('does NOT prematurely defeat: a winning final message is a victory', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 90
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'The last push', detail: 'It is done', era: 'x', progressChange: 20, valence: 'positive' }
          }))
308 
          await store.sendMessage('The decisive word', 'Tesla')
310 
          expect(store.objectiveProgress).toBe(100)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('victory')
      })
315 
      it('declares defeat when the final message falls short', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 10
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'Not enough', detail: 'History resists', era: 'x', progressChange: 5, valence: 'positive' }
          }))
322 
          await store.sendMessage('A last try', 'Tesla')
324 
          expect(store.objectiveProgress).toBe(15)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('defeat')
      })
  })
330 
  describe('living chronicle (refreshChronicle)', () => {
      const telling = { title: 'The Peace That Held', paragraphs: ['In 1878, Bismarck chose trade.', 'By 1914, no war came.'] }
333 
      function seedOneChange() {
          store.addTimelineEvent({
              figureName: 'Bismarck', era: '1878', headline: 'Bismarck chooses trade',
              detail: 'Alliances soften into commerce.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20
          })
      }
340 
      it('re-narrates the timeline and stores the telling', async () => {
          seedOneChange()
          fetchMock.mockResolvedValue({ success: true, chronicle: telling })
344 
          await store.refreshChronicle()
346 
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
351 
      it('skips (and clears) when no changes exist to chronicle', async () => {
          store.chronicle = telling
          await store.refreshChronicle()
          expect(fetchMock).not.toHaveBeenCalled()
          expect(store.chronicle).toBeNull()
      })
358 
      it('keeps the prior telling when a refresh fails (never blanks)', async () => {
          seedOneChange()
          store.chronicle = telling
          fetchMock.mockRejectedValue(new Error('chronicler offline'))
363 
          await store.refreshChronicle()
365 
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
369 
      it('fires a non-blocking refresh after a turn actually changes the world', async () => {
          fetchMock.mockResolvedValue(okResponse())
372 
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
374 
          // The refresh is fired (not awaited) once the turn added a ledger entry.
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
      })
378 
      it('does NOT refresh when a turn fails to change the world', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
381 
          await store.sendMessage('A message that fails', 'Tesla')
383 
          expect(fetchMock).not.toHaveBeenCalledWith('/api/chronicle', expect.anything())
      })
  })
387 
  describe('staleness guards (epoch + sequencing)', () => {
      function deferred<T>() {
          let resolve!: (v: T) => void
          let reject!: (e: unknown) => void
          const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
          return { promise, resolve, reject }
      }
395 
      it('a reset mid-send drops the stale response instead of haunting the new run', async () => {
          const slow = deferred<ReturnType<typeof okResponse>>()
          fetchMock.mockReturnValue(slow.promise)
399 
          const inFlight = store.sendMessage('From the old world', 'Tesla')
          store.resetGame()
          slow.resolve(okResponse())
          const resolved = await inFlight
404 
          // The dead run's turn finds no purchase in the fresh one.
          expect(resolved).toBe(false)
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.timelineEvents).toHaveLength(0)
          expect(store.objectiveProgress).toBe(0)
      })
412 
      it('a reset mid-send must not "refund" the new run on failure either', async () => {
          const slow = deferred<never>()
          fetchMock.mockReturnValue(slow.promise)
416 
          const inFlight = store.sendMessage('Doomed', 'Tesla')
          store.resetGame()
          store.remainingMessages = 3 // the new run has its own spent counter
          slow.reject(new Error('old run network error'))
          await inFlight
422 
          expect(store.remainingMessages).toBe(3) // untouched by the stale refund
      })
425 
      it('an earlier chronicle rewrite cannot overwrite a later one', async () => {
          store.addTimelineEvent({ figureName: 'X', era: 'e', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20 })
428 
          const first = deferred<{ success: boolean; chronicle: { title: string; paragraphs: string[] } }>()
          const second = deferred<{ success: boolean; chronicle: { title: string; paragraphs: string[] } }>()
          fetchMock.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise)
432 
          const a = store.refreshChronicle()
          const b = store.refreshChronicle()
          // The LATER telling lands first; the earlier one limps in afterwards.
          second.resolve({ success: true, chronicle: { title: 'The Later Telling', paragraphs: ['b'] } })
          await b
          first.resolve({ success: true, chronicle: { title: 'The Earlier Telling', paragraphs: ['a'] } })
          await a
440 
          expect(store.chronicle?.title).toBe('The Later Telling')
          expect(store.chronicleLoading).toBe(false)
      })
444 
      it('a reset mid-chronicle keeps the old run’s telling out of the new run', async () => {
          store.addTimelineEvent({ figureName: 'X', era: 'e', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20 })
          const slow = deferred<{ success: boolean; chronicle: { title: string; paragraphs: string[] } }>()
          fetchMock.mockReturnValue(slow.promise)
449 
          const inFlight = store.refreshChronicle()
          store.resetGame()
          slow.resolve({ success: true, chronicle: { title: 'A Ghost Epilogue', paragraphs: ['boo'] } })
          await inFlight
454 
          expect(store.chronicle).toBeNull()
      })
457 
      it('out-of-order grounding keeps the latest figure’s dossier', async () => {
          const slowA = deferred<Record<string, unknown>>()
          const fastB = deferred<Record<string, unknown>>()
          fetchMock.mockReturnValueOnce(slowA.promise).mockReturnValueOnce(fastB.promise)
462 
          const a = store.groundActiveFigure('Aristotle')
          const b = store.groundActiveFigure('Bismarck')
          fastB.resolve({ name: 'Otto von Bismarck', resolved: true, born: { year: 1815, bce: false, signed: 1815, display: '1815' }, died: { year: 1898, bce: false, signed: 1898, display: '1898' }, living: false })
          await b
          slowA.resolve({ name: 'Aristotle', resolved: true, born: { year: 384, bce: true, signed: -384, display: '384 BC' }, died: { year: 322, bce: true, signed: -322, display: '322 BC' }, living: false })
          await a
469 
          expect(store.figureGrounding?.name).toBe('Otto von Bismarck')
          expect(store.groundingLoading).toBe(false)
      })
473 
      it('clearGrounding drops the dossier instantly and a lookup still in flight finds no purchase', async () => {
          const slow = deferred<Record<string, unknown>>()
          fetchMock.mockReturnValue(slow.promise)
477 
          const inFlight = store.groundActiveFigure('Napoleon')
          store.clearGrounding() // the player typed a new name — the old dossier dies NOW
          slow.resolve({ name: 'Napoleon', resolved: true, born: { year: 1769, bce: false, signed: 1769, display: '1769' }, died: { year: 1821, bce: false, signed: 1821, display: '1821' }, living: false })
          await inFlight
482 
          expect(store.figureGrounding).toBeNull()
          expect(store.contactWhen).toBeNull()
          expect(store.groundingLoading).toBe(false)
      })
487 
      it('study records the moment it was asked for, not where the slider moved mid-flight', async () => {
          store.figureGrounding = {
              name: 'Cleopatra', resolved: true,
              born: { year: 69, bce: true, signed: -69, display: '69 BC' },
              died: { year: 30, bce: true, signed: -30, display: '30 BC' }, living: false
          } as never
          store.setContactWhen(-40)
          const slow = deferred<{ success: boolean; study: Record<string, unknown> }>()
          fetchMock.mockReturnValue(slow.promise)
497 
          const inFlight = store.studyActiveFigure()
          store.setContactWhen(-35) // the player keeps exploring while the Archivist works
          slow.resolve({ success: true, study: { atThisMoment: 'x', grasp: ['a'], reaching: ['b'], cannotYetKnow: 'c' } })
          await inFlight
502 
          // The brief is FOR -40; recording -35 would mislabel it and hide Re-study.
          expect(store.studyWhen).toBe(-40)
          expect(store.studyFor).toBe('Cleopatra')
      })
  })
508 
  describe('victory efficiency', () => {
      it('rates an early win and reports messages saved', () => {
          store.gameStatus = 'victory'
          store.remainingMessages = 4
          const eff = store.getVictoryEfficiency()
          expect(eff?.efficiencyRating).toBe('Legendary')
          expect(eff?.messagesUsed).toBe(1)
          expect(eff?.isEarlyVictory).toBe(true)
      })
518 
      it('returns null when not a victory', () => {
          store.gameStatus = 'playing'
          expect(store.getVictoryEfficiency()).toBeNull()
      })
  })
524 
  describe('resetGame', () => {
      it('returns everything to a fresh run', () => {
          store.remainingMessages = 1
          store.objectiveProgress = 80
          store.gameStatus = 'defeat'
          store.messageHistory.push({ text: 'x', sender: 'user', timestamp: new Date() })
          store.timelineEvents.push({ id: '1', figureName: 'x', era: 'e', headline: 'h', detail: 'd', diceRoll: 1, diceOutcome: DiceOutcome.FAILURE, progressChange: -1, valence: 'negative', timestamp: new Date() })
          store.figures.push({ name: 'x', era: 'e', descriptor: 'd' })
          store.activeFigureName = 'x'
          store.chronicle = { title: 'A History', paragraphs: ['It happened.'] }
          store.figureStudy = { atThisMoment: 'x', grasp: [], reaching: [], cannotYetKnow: '' }
          store.studyFor = 'x'
          store.studyWhen = 1500
          store.archiveResult = { topic: 't', summary: 's', requires: [], knownSince: '' }
539 
          store.resetGame()
541 
          expect(store.remainingMessages).toBe(5)
          expect(store.objectiveProgress).toBe(0)
          expect(store.gameStatus).toBe('playing')
          expect(store.messageHistory).toEqual([])
          expect(store.timelineEvents).toEqual([])
          expect(store.figures).toEqual([])
          expect(store.activeFigureName).toBe('')
          expect(store.chronicle).toBeNull()
          expect(store.figureStudy).toBeNull()
          expect(store.studyFor).toBe('')
          expect(store.studyWhen).toBeNull()
          expect(store.archiveResult).toBeNull()
      })
  })
556 
  describe('objective selection', () => {
      const objective = {
          title: 'Save the Library of Alexandria',
          description: 'Keep the ancient world’s knowledge intact into the modern age.',
          era: 'Alexandria, antiquity',
          icon: '📜'
      }
564 
      it('chooseObjective commits the objective and resets progress', () => {
          store.objectiveProgress = 40
          store.setError('a stale error')
568 
          store.chooseObjective(objective)
570 
          expect(store.currentObjective).toEqual(objective)
          expect(store.objectiveProgress).toBe(0)
          expect(store.error).toBeNull()
      })
575 
      it('fetchAIObjective returns a composed objective WITHOUT committing it', async () => {
          fetchMock.mockResolvedValue({ success: true, objective })
578 
          const result = await store.fetchAIObjective()
580 
          expect(fetchMock).toHaveBeenCalledWith('/api/objective', { method: 'GET' })
          expect(result).toEqual(objective)
          // The caller previews it, then commits via chooseObjective — not here.
          expect(store.currentObjective).toBeNull()
      })
586 
      it('fetchAIObjective returns null (never throws) when composing fails', async () => {
          fetchMock.mockRejectedValue(new Error('archives offline'))
          expect(await store.fetchAIObjective()).toBeNull()
          expect(store.currentObjective).toBeNull()
      })
592 
      it('fetchAIObjective returns null when the server reports failure', async () => {
          fetchMock.mockResolvedValue({ success: false })
          expect(await store.fetchAIObjective()).toBeNull()
      })
  })
598 
  describe('grounded contacts (who · when · liveness)', () => {
      const cleopatra = {
          name: 'Cleopatra',
          resolved: true,
          description: 'Pharaoh of Egypt from 51 to 30 BC',
          born: { year: 69, bce: true, signed: -69, display: '69 BC' },
          died: { year: 30, bce: true, signed: -30, display: '30 BC' },
          living: false
      }
608 
      it('grounds the active figure and defaults the when inside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
611 
          await store.groundActiveFigure('Cleopatra')
613 
          expect(fetchMock).toHaveBeenCalledWith('/api/figure', { params: { name: 'Cleopatra' } })
          expect(store.figureGrounding?.resolved).toBe(true)
          expect(store.contactWhen).toBeGreaterThanOrEqual(-69)
          expect(store.contactWhen).toBeLessThanOrEqual(-30)
          expect(store.contactLiveness).toBe('ok')
          expect(store.canContact).toBe(true)
      })
621 
      it('flags a when before birth or after death', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
625 
          store.setContactWhen(-200) // 200 BC — long before she was born
          expect(store.contactLiveness).toBe('before-birth')
          expect(store.canContact).toBe(false)
629 
          store.setContactWhen(1990) // long after she died
          expect(store.contactLiveness).toBe('after-death')
          expect(store.canContact).toBe(false)
633 
          store.setContactWhen(-50) // 50 BC — within her life
          expect(store.contactLiveness).toBe('ok')
      })
637 
      it('stays permissive when a figure cannot be grounded', async () => {
          fetchMock.mockResolvedValue({ name: 'Nobody', resolved: false })
          await store.groundActiveFigure('Nobody Atall')
641 
          expect(store.figureGrounding?.resolved).toBe(false)
          expect(store.contactWhen).toBeNull()
          expect(store.contactLiveness).toBe('unknown')
          expect(store.canContact).toBe(true)
      })
647 
      it('treats a living figure as reachable up to the present', async () => {
          fetchMock.mockResolvedValue({
              name: 'Paul McCartney', resolved: true,
              born: { year: 1942, bce: false, signed: 1942, display: '1942' },
              living: true
          })
          await store.groundActiveFigure('Paul McCartney')
655 
          store.setContactWhen(1965)
          expect(store.contactLiveness).toBe('ok')
          store.setContactWhen(1900) // before birth
          expect(store.contactLiveness).toBe('before-birth')
      })
661 
      it('pins, rescrubs, and clears the contact moment (issue #32)', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
665 
          store.setContactMoment({ month: 6, day: 28 })
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
668 
          // Scrubbing the year keeps the pin — it refines whichever year is chosen.
          store.setContactWhen(-44)
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
672 
          // A name change clears it with the rest of the dossier.
          store.clearGrounding()
          expect(store.contactMoment).toBeNull()
      })
677 
      it('sends the refined when string + raw moment integers (issue #32)', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          store.setContactWhen(-48)
          store.setContactMoment({ month: 3, day: 15 })
          fetchMock.mockClear()
          fetchMock.mockResolvedValue({ success: false, message: 'x', data: { userMessage: 'm', error: 'x' } })
685 
          await store.sendMessage('Hold court away from the palace today.', 'Cleopatra')
687 
          const body = (fetchMock.mock.calls[0][1] as { body: Record<string, unknown> }).body
          expect(body.when).toBe('March 15, 48 BC')
          expect(body.whenSigned).toBe(-48)
          expect(body.whenMonth).toBe(3)
          expect(body.whenDay).toBe(15)
      })
694 
      it('clears grounding when the figure is cleared', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          await store.groundActiveFigure('')
          expect(store.figureGrounding).toBeNull()
          expect(store.contactWhen).toBeNull()
      })
702 
      it('refuses to send to someone outside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          store.setContactWhen(-300) // before birth
          fetchMock.mockClear()
708 
          await store.sendMessage('Beware the Ides', 'Cleopatra')
710 
          expect(fetchMock).not.toHaveBeenCalled() // never reached /api/send-message
          expect(store.error).toMatch(/born yet/i)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.remainingMessages).toBe(5)
      })
  })
717 
  describe('contactAge (so the player skips the lifetime math)', () => {
      const cleopatra = {
          name: 'Cleopatra', resolved: true,
          born: { year: 69, bce: true, signed: -69, display: '69 BC' },
          died: { year: 30, bce: true, signed: -30, display: '30 BC' },
          living: false
      }
725 
      it('reports the age at the chosen year for a grounded figure', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-50) // 50 BC
          expect(store.contactAge).toBe(19) // -50 - (-69)
      })
731 
      it('is 0 in the birth year', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-69)
          expect(store.contactAge).toBe(0)
      })
737 
      it('corrects for the missing year zero across the BC→AD boundary', () => {
          store.figureGrounding = {
              name: 'Augustus', resolved: true,
              born: { year: 63, bce: true, signed: -63, display: '63 BC' },
              died: { year: 14, bce: false, signed: 14, display: '14' },
              living: false
          } as never
          store.setContactWhen(14) // AD 14
          expect(store.contactAge).toBe(76) // 14 - (-63) - 1 (no year zero)
      })
748 
      it('handles a modern living figure', () => {
          store.figureGrounding = {
              name: 'Paul McCartney', resolved: true,
              born: { year: 1942, bce: false, signed: 1942, display: '1942' }, living: true
          } as never
          store.setContactWhen(1965)
          expect(store.contactAge).toBe(23)
      })
757 
      it('is null when the figure is unresolved or has no birth year', () => {
          store.figureGrounding = { name: 'Nobody', resolved: false } as never
          store.setContactWhen(1500)
          expect(store.contactAge).toBeNull()
762 
          store.figureGrounding = null
          expect(store.contactAge).toBeNull()
      })
766 
      it('is null before birth rather than a negative age', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-200) // long before she was born
          expect(store.contactAge).toBeNull()
      })
  })
773 
  describe('the Archive — studyActiveFigure (prototype)', () => {
      const cleopatra = {
          name: 'Cleopatra', resolved: true,
          description: 'Pharaoh of Egypt', extract: 'Cleopatra was the last active ruler of Ptolemaic Egypt.',
          born: { year: 69, bce: true, signed: -69, display: '69 BC' },
          died: { year: 30, bce: true, signed: -30, display: '30 BC' }, living: false
      }
      const study = {
          atThisMoment: 'Queen at the height of her power.',
          grasp: ['statecraft', 'Hellenistic science'],
          reaching: ['securing Egypt against Rome'],
          cannotYetKnow: 'the fall of the Roman Republic'
      }
787 
      it('studies a grounded figure and stores the brief', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
792 
          await store.studyActiveFigure()
794 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.figureStudy).toEqual(study)
          expect(store.studyFor).toBe('Cleopatra')
          expect(store.studyLoading).toBe(false)
      })
800 
      it('caches per figure + year (no refetch on a second study at the same moment)', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
          await store.studyActiveFigure()
          fetchMock.mockClear()
807 
          await store.studyActiveFigure()
          expect(fetchMock).not.toHaveBeenCalled()
      })
811 
      it('re-studies the figure when the contact year changes', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
          await store.studyActiveFigure()
          expect(store.studyWhen).toBe(-40)
          fetchMock.mockClear()
819 
          store.setContactWhen(-35) // move the slider
          await store.studyActiveFigure()
822 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.studyWhen).toBe(-35)
      })
826 
      it('does nothing for an unresolved figure (no record to consult)', async () => {
          store.figureGrounding = { name: 'Nobody', resolved: false } as never
          await store.studyActiveFigure()
          expect(fetchMock).not.toHaveBeenCalled()
          expect(store.figureStudy).toBeNull()
      })
833 
      it('leaves the study empty (no throw) when research fails', async () => {
          store.figureGrounding = cleopatra as never
          fetchMock.mockRejectedValue(new Error('archive offline'))
          await store.studyActiveFigure()
          expect(store.figureStudy).toBeNull()
          expect(store.studyLoading).toBe(false)
      })
841 
      it('surfaces a moderation block as a distinct notice, not a study', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: false, blocked: true, error: 'That study was blocked by content moderation.' })
846 
          await store.studyActiveFigure()
848 
          expect(store.studyNotice).toContain('blocked by content moderation')
          expect(store.figureStudy).toBeNull()
          expect(store.studyLoading).toBe(false)
      })
853 
⋯ 123 lines hidden (lines 854–976)854        it('drops a stale study when the contact changes', async () => {
          store.figureStudy = study as never
          store.studyFor = 'Cleopatra'
          fetchMock.mockResolvedValue({ name: 'Tesla', resolved: false })
858 
          await store.groundActiveFigure('Nikola Tesla')
860 
          expect(store.figureStudy).toBeNull()
          expect(store.studyFor).toBe('')
      })
  })
865 
  describe('the Archive — askArchive lookup (prototype, yellow)', () => {
      const lookup = {
          topic: 'Gunpowder',
          summary: 'An explosive mix of saltpeter, charcoal, and sulfur.',
          requires: ['saltpeter', 'charcoal', 'sulfur'],
          knownSince: 'China, ~9th century'
      }
873 
      it('looks up a topic and stores the result', async () => {
          fetchMock.mockResolvedValue({ success: true, lookup })
876 
          await store.askArchive('gunpowder')
878 
          expect(fetchMock).toHaveBeenCalledWith('/api/lookup', expect.objectContaining({ method: 'POST' }))
          expect(store.archiveResult).toEqual(lookup)
          expect(store.lookupLoading).toBe(false)
      })
883 
      it('ignores an empty query', async () => {
          await store.askArchive('   ')
          expect(fetchMock).not.toHaveBeenCalled()
      })
888 
      it('leaves the result empty (no throw) when the lookup fails', async () => {
          fetchMock.mockRejectedValue(new Error('archive offline'))
          await store.askArchive('gunpowder')
          expect(store.archiveResult).toBeNull()
          expect(store.lookupLoading).toBe(false)
      })
  })
896 
  describe('anachronism risk-coupling (prototype)', () => {
      it('records the anachronism level on the resolved ledger entry', async () => {
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'A leap', detail: 'Generations early', era: 'x', progressChange: 40, valence: 'positive', anachronism: 'far-ahead' }
          }))
902 
          await store.sendMessage('Build a flying machine and aim higher', 'Leonardo da Vinci')
904 
          expect(store.timelineEvents[0].anachronism).toBe('far-ahead')
      })
907 
      it('leaves the ledger entry anachronism undefined when the server omits it', async () => {
          fetchMock.mockResolvedValue(okResponse())
          await store.sendMessage('A modest note', 'Tesla')
          expect(store.timelineEvents[0].anachronism).toBeUndefined()
      })
  })
914 
  describe('figure suggestions (era-aware on-ramp)', () => {
      const objective = {
          title: 'Prevent the Great War',
          description: 'Keep 1914 from collapsing into world war.',
          era: 'Europe, 1914',
          icon: '🕊️'
      }
922 
      it('loads era-relevant suggestions for the current objective', async () => {
          store.currentObjective = objective
          fetchMock.mockResolvedValue({
              success: true,
              suggestions: [{ name: 'Wilhelm II', reason: 'Could restrain Vienna.', lifespan: '1859 – 1941' }],
              fallback: false
          })
930 
          await store.loadSuggestions()
932 
          expect(fetchMock).toHaveBeenCalledWith('/api/suggestions', expect.objectContaining({ method: 'POST' }))
          expect(store.figureSuggestions).toHaveLength(1)
          expect(store.figureSuggestions[0].name).toBe('Wilhelm II')
          expect(store.suggestionsFor).toBe('Prevent the Great War')
      })
938 
      it('caches per objective (no refetch on a second call)', async () => {
          store.currentObjective = objective
          fetchMock.mockResolvedValue({ success: true, suggestions: [{ name: 'X', reason: 'y' }] })
          await store.loadSuggestions()
          fetchMock.mockClear()
944 
          await store.loadSuggestions()
          expect(fetchMock).not.toHaveBeenCalled()
      })
948 
      it('clears suggestions when there is no objective', async () => {
          store.currentObjective = null
          await store.loadSuggestions()
          expect(store.figureSuggestions).toEqual([])
          expect(fetchMock).not.toHaveBeenCalled()
      })
955 
      it('surfaces a blocked objective instead of a silent empty list', async () => {
          store.currentObjective = objective
          fetchMock.mockResolvedValue({ success: true, suggestions: [], blocked: true, reason: 'That objective was blocked by content moderation.' })
959 
          await store.loadSuggestions()
961 
          expect(store.suggestionsNotice).toContain('blocked by content moderation')
          expect(store.figureSuggestions).toEqual([])
      })
965 
      it('leaves suggestions empty (no throw) when the request fails — but records the ask', async () => {
          store.currentObjective = objective
          fetchMock.mockRejectedValue(new Error('suggester down'))
          await store.loadSuggestions()
          expect(store.figureSuggestions).toEqual([])
          // "Asked and failed" must be distinguishable from "not yet asked": the
          // picker shows skeletons for the latter, the honest fallback for this.
          expect(store.suggestionsFor).toBe('Prevent the Great War')
      })
  })
976})