Cost-per-run telemetry — a code-level reading

What changed, and why

The go-to-market plan sells runs — one playthrough is a bounded bundle of roughly 20–26 AI calls — and prices packs at 3–5x the p95 cost per run. That number can't be computed today: the AI gateway already logs one line per call with token counts, but nothing ties a call to a run, and nothing turns tokens into dollars.

This PR adds both, and only those. A run id is minted on the client and rides every AI request as a header; the server binds it per request and the gateway stamps it onto each log line along with the call's computed cost. Group the lines by run id, sum the cost, and you have cost-per-run. No database, no new dependency — the change is telemetry enrichment plus the thread that carries the id from the browser to the log line.

The run id, bound per request

The id has to reach the gateway's emit(), which sits several wrapper calls below each route handler. Threading it through every signature would be noisy, so it travels in request-scoped storage instead. AsyncLocalStorage gives each Nitro request its own context: bind the id once and every awaited call in that request can read it, with no leakage across requests.

Bind with enterWith (the middleware), read with currentRunId (the gateway).

server/utils/run-context.ts · 30 lines

server/utils/run-context.ts30 lines · TypeScript

⋯ 15 lines hidden (lines 1–15)1/**
2 * Request-scoped run context — the thread that ties every AI call in one game
3 * run to a single id, so the cost telemetry (ai-gateway's `[ai]` line) groups
4 * per run and yields cost-per-run, the number dispatch 1 prices packs against.
5 *
6 * Set once per request by the run-context middleware (from the `x-run-id`
7 * header) and read deep inside the gateway's emit() — so the id never has to be
8 * threaded through every wrapper signature between the route and the model call.
9 *
10 * AsyncLocalStorage is the request-local store: each Nitro request runs in its
11 * own async context, so `enterWith` in the middleware propagates to every
12 * awaited model call within that request and never leaks across requests.
13 */
14import { AsyncLocalStorage } from 'node:async_hooks'
15 
16export interface RunContext {
17    runId?: string
18}
19 
20const storage = new AsyncLocalStorage<RunContext>()
21 
22/** Bind the run context to the remainder of the current request (middleware). */
23export function setRunContext(ctx: RunContext): void {
24    storage.enterWith(ctx)
25}
26 
27/** The current request's run id, or undefined outside a run-scoped request. */
28export function currentRunId(): string | undefined {
29    return storage.getStore()?.runId
30}

A middleware binds it once per request, reading the x-run-id header. The id is untrusted client input that lands in a log line, so it is stripped to id-safe characters and length-bounded before use. Requests with no header (static assets, the dashboard) simply leave the context unset.

Header in, sanitized, bound for the rest of the request.

server/middleware/run-context.ts · 17 lines

server/middleware/run-context.ts17 lines · TypeScript

⋯ 12 lines hidden (lines 1–12)1/**
* Stamps each request with its game run id (the `x-run-id` header the client
* sends on every AI call) so the gateway's cost telemetry groups per run.
*
* Header-based on purpose: it works uniformly across the GET and POST AI routes
* without consuming the body, and is harmless on requests that carry no id
* (static assets, the dashboard) — they simply leave the context unset. The id
* is untrusted client input that lands in a log line, so it is bounded and
* stripped to id-safe characters before use.
*/
11import { setRunContext } from '~/server/utils/run-context'
12 
13export default defineEventHandler((event) => {
  const raw = getHeader(event, 'x-run-id')
  const runId = raw?.replace(/[^a-zA-Z0-9-]/g, '').slice(0, 64)
  if (runId) setRunContext({ runId })
17})

The rate card, and per-call cost

Cost needs a price per model. The rate card is one constant — USD per million tokens, per model — and costUsd applies it. An unpriced model returns undefined rather than a guess, so a missing rate shows up as uncounted instead of silently low.

The rate card and the cost function; note the per-lane input handling.

server/utils/cost.ts · 51 lines

server/utils/cost.ts51 lines · TypeScript

⋯ 25 lines hidden (lines 1–25)1/**
2 * The rate card — USD per million tokens, per model — and the per-call cost it
3 * implies. This is the GTM cost instrument's price half: ai-gateway stamps every
4 * `[ai]` line with the dollar cost computed here, so grouping by run id yields
5 * cost-per-run (the p95 that dispatch 1 prices packs at 3-5x against).
6 *
7 * Rates are list prices as of 2026-06 — the ONE number to keep fresh; verify
8 * against current provider pricing before pricing packs. Cache reads bill at
9 * ~0.1x input on Anthropic. The token conventions differ by lane: Anthropic's
10 * input_tokens EXCLUDES cached tokens, OpenAI's prompt_tokens INCLUDES them, so
11 * on the OpenAI lane the cached subset is subtracted out of input to avoid
12 * billing it twice (see ai-gateway's usage mapping).
13 */
14import type { AiLane } from './ai-routing'
15import type { AiUsage } from './ai-gateway'
16 
17/** USD per 1,000,000 tokens. */
18interface Rate {
19    input: number
20    output: number
21    cacheRead: number
22}
23 
24const PER_MILLION = 1_000_000
25 
26const RATES: Record<string, Rate> = {
27    'claude-haiku-4-5': { input: 1, output: 5, cacheRead: 0.1 },
28    'claude-sonnet-4-6': { input: 3, output: 15, cacheRead: 0.3 },
29    'claude-opus-4-8': { input: 15, output: 75, cacheRead: 1.5 },
30    'gpt-5.5': { input: 1.25, output: 10, cacheRead: 0.125 }
31}
32 
33/**
34 * The dollar cost of one call, or undefined for a model with no rate — better an
35 * absent number than a guessed one (a missing line shows up as uncounted rather
36 * than silently low). Rounded to the microdollar; per-call costs are fractions
37 * of a cent and the run total is summed downstream.
38 */
39export function costUsd(model: string, usage: AiUsage, lane: AiLane): number | undefined {
40    const rate = RATES[model]
41    if (!rate) return undefined
42    // OpenAI reports cached tokens inside input; Anthropic reports them apart.
43    const uncachedInput =
44        lane === 'openai' ? Math.max(0, usage.inputTokens - usage.cacheReadTokens) : usage.inputTokens
45    const usd =
46        (uncachedInput * rate.input +
47            usage.cacheReadTokens * rate.cacheRead +
48            usage.outputTokens * rate.output) /
49        PER_MILLION
50    return Math.round(usd * PER_MILLION) / PER_MILLION
⋯ 1 line hidden (lines 51–51)51}

Stamping the telemetry line

The gateway is the single transport for every structured model call, so one edit to its emit() reaches all of them. Enrichment happens in one place: both the success and failure call sites get the run id, and the cost rides only on calls that reported usage. The eval-harness observer sees the same enriched line the log does.

Two new optional telemetry fields; emit() fills them once, centrally.

server/utils/ai-gateway.ts · 239 lines

server/utils/ai-gateway.ts239 lines · TypeScript

⋯ 75 lines hidden (lines 1–75)1/**
* The AI gateway — one transport for every structured model call, dispatched
* per task by the routing table (ai-routing.ts). Callers keep their own prompts,
* schemas, parsing, guards, and never-throw envelopes; the gateway only decides
* WHICH provider runs the request and HOW (model + parameters), and emits the
* cost telemetry the go-to-market plan's dispatch 1 requires.
*
* Telemetry: every call logs one structured line (task, lane, model, tokens
* in/out, latency, ok) — intentional production output, suppressed under vitest.
* The eval harness subscribes via setAiCallObserver to price bake-off lanes.
*/
12import OpenAI from 'openai'
13import Anthropic from '@anthropic-ai/sdk'
14import { routeFor, type AiTask, type AiLane } from './ai-routing'
15import { currentRunId } from './run-context'
16import { costUsd } from './cost'
17 
18let openaiClient: OpenAI | null = null
19let anthropicClient: Anthropic | null = null
20 
21/** Reads a runtime-config key, falling back to raw env outside a Nuxt context
*  (the eval harness exercises these utils directly in node). */
23function configuredKey(name: 'openaiApiKey' | 'anthropicApiKey', envName: string): string | undefined {
  let key: string | undefined
  try {
      key = useRuntimeConfig()[name] as string | undefined
  } catch {
      key = undefined
  }
  return key || process.env[envName]
31}
32 
33export function getOpenAIClient(): OpenAI {
  if (!openaiClient) {
      const apiKey = configuredKey('openaiApiKey', 'OPENAI_API_KEY')
      if (!apiKey) throw new Error('OpenAI API key is not configured')
      openaiClient = new OpenAI({
          apiKey,
          // Fail fast rather than hang on the SDK's 10-minute default if a
          // call stalls (e.g. a bad key or network hiccup).
          timeout: 30_000,
          maxRetries: 1
      })
  }
  return openaiClient
46}
47 
48export function getAnthropicClient(): Anthropic {
  if (!anthropicClient) {
      const apiKey = configuredKey('anthropicApiKey', 'ANTHROPIC_API_KEY')
      if (!apiKey) throw new Error('Anthropic API key is not configured')
      anthropicClient = new Anthropic({
          apiKey,
          // The epilogue's adaptive thinking can run long; everything else is
          // seconds. 60s bounds the worst case without hanging a turn forever.
          timeout: 60_000,
          maxRetries: 1
      })
  }
  return anthropicClient
61}
62 
63export interface AiUsage {
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number
67}
68 
69export interface AiCallTelemetry {
  task: AiTask
  lane: AiLane
  model: string
  ms: number
  ok: boolean
  usage?: AiUsage
  /** The game run this call belongs to (from the request's x-run-id); absent
   *  outside a run-scoped request. The key that groups calls into a run. */
  runId?: string
  /** The call's dollar cost from the rate card; absent when usage is missing
   *  (a failed call) or the model has no listed rate. */
  usd?: number
82}
⋯ 9 lines hidden (lines 83–91)83 
84type AiCallObserver = (t: AiCallTelemetry) => void
85let observer: AiCallObserver | null = null
86 
87/** The eval harness (and future dashboards) subscribe here; null to clear. */
88export function setAiCallObserver(fn: AiCallObserver | null): void {
  observer = fn
90}
91 
92function emit(t: AiCallTelemetry): void {
  // Enrich once, here, so both the success and failure call sites get the run
  // id, and so the observer (the eval harness) sees the same priced line the
  // log does. usd needs usage, so it rides only on calls that reported tokens.
  const enriched: AiCallTelemetry = {
      ...t,
      runId: t.runId ?? currentRunId(),
      usd: t.usd ?? (t.usage ? costUsd(t.model, t.usage, t.lane) : undefined)
  }
  observer?.(enriched)
  // One greppable line per call — the GTM's "structured log line is enough to
  // start". Intentional production telemetry; quiet under the test runner.
  if (!process.env.VITEST) {
      console.info(`[ai] ${JSON.stringify(enriched)}`)
  }
107}
⋯ 132 lines hidden (lines 108–239)108 
109export interface ChatTurn {
  role: 'user' | 'assistant'
  content: string
112}
113 
114/**
* Thrown when Claude's own safety classifiers decline a request mid-flight
* (Claude 4 returns stop_reason "refusal"). It is NOT an infra error and NOT an
* empty answer — it's a model-side block, so callers surface it as a moderation
* block, not a "try again" refund. (See Anthropic's streaming-refusals guide.)
*/
120export class ModelRefusalError extends Error {
  constructor() {
      super('The model declined this request (safety refusal).')
      this.name = 'ModelRefusalError'
  }
125}
126 
127export interface StructuredRequest {
  task: AiTask
  /** The built prompt. Single-shot tasks send it as the whole request; with
   *  `turns` it becomes the system prompt over the conversation. */
  system: string
  turns?: ChatTurn[]
  /** OpenAI requires a schema name; Anthropic ignores it. */
  schemaName: string
  schema: Record<string, unknown>
136}
137 
138/**
* Runs one structured completion on the task's routed lane and returns the raw
* JSON text (trimmed), or null on an empty answer. Throws on transport errors —
* callers own their never-throw envelopes, exactly as before the seam.
*/
143export async function completeStructured(req: StructuredRequest): Promise<string | null> {
  const { lane, route } = routeFor(req.task)
  const model = lane === 'anthropic' ? route.anthropic.model : route.openai.model
  const started = Date.now()
  try {
      const result = lane === 'anthropic' ? await viaAnthropic(req) : await viaOpenAI(req)
      emit({ task: req.task, lane, model, ms: Date.now() - started, ok: true, usage: result.usage })
      return result.content
  } catch (error) {
      emit({ task: req.task, lane, model, ms: Date.now() - started, ok: false })
      throw error
  }
155}
156 
157interface LaneResult {
  content: string | null
  usage?: AiUsage
160}
161 
162async function viaOpenAI(req: StructuredRequest): Promise<LaneResult> {
  const { route } = routeFor(req.task)
  const params = route.openai
  const client = getOpenAIClient()
  const completion = await client.chat.completions.create({
      model: params.model,
      messages: [
          { role: 'system' as const, content: req.system },
          ...(req.turns ?? [])
      ],
      // gpt-5.5 is a reasoning model: omit temperature, keep effort low, leave
      // headroom for hidden reasoning tokens inside the output cap.
      ...(params.reasoningEffort ? { reasoning_effort: params.reasoningEffort } : {}),
      max_completion_tokens: params.maxTokens,
      response_format: {
          type: 'json_schema',
          json_schema: { name: req.schemaName, strict: true, schema: req.schema }
      }
  })
  const usage = completion.usage
      ? {
          inputTokens: completion.usage.prompt_tokens ?? 0,
          outputTokens: completion.usage.completion_tokens ?? 0,
          cacheReadTokens: completion.usage.prompt_tokens_details?.cached_tokens ?? 0
      }
      : undefined
  return { content: completion.choices?.[0]?.message?.content?.trim() || null, usage }
189}
190 
191async function viaAnthropic(req: StructuredRequest): Promise<LaneResult> {
  const { route } = routeFor(req.task)
  const params = route.anthropic
  const client = getAnthropicClient()
195 
  // Anthropic requires the first message to be a user turn. Single-shot tasks
  // send the whole built prompt AS the user message (no system param) — for
  // one-off structured generation the two are equivalent, and it avoids a
  // contentless "Proceed." turn. Conversational tasks keep system + turns.
  const turns = req.turns ?? []
  const system = turns.length ? req.system : undefined
  const messages: Anthropic.MessageParam[] = turns.length
      ? (turns[0].role === 'user' ? turns : [{ role: 'user' as const, content: '(The conversation resumes.)' }, ...turns])
      : [{ role: 'user' as const, content: req.system }]
205 
  const response = await client.messages.create({
      model: params.model,
      max_tokens: params.maxTokens,
      ...(system ? { system } : {}),
      messages,
      // Thinking rejects non-default sampling params — temperature only rides
      // on thinking-off calls (the family rule the routing table can't express).
      ...(params.temperature !== undefined && params.thinking !== 'adaptive' ? { temperature: params.temperature } : {}),
      ...(params.thinking === 'adaptive' ? { thinking: { type: 'adaptive' as const } } : {}),
      output_config: {
          ...(params.effort ? { effort: params.effort } : {}),
          format: { type: 'json_schema' as const, schema: req.schema }
      }
  })
220 
  // Claude's streaming classifiers can decline mid-flight (stop_reason
  // "refusal"); that's a model-side block, surfaced distinctly so callers
  // don't mistake it for an empty/infra response. Cast: the union may predate
  // this SDK's type for the value.
  if ((response.stop_reason as string) === 'refusal') {
      throw new ModelRefusalError()
  }
228 
  // Thinking blocks (epilogue) precede the text block; take the text.
  const text = response.content.find(
      (b): b is Anthropic.TextBlock => b.type === 'text'
  )?.text?.trim()
  const usage: AiUsage = {
      inputTokens: response.usage?.input_tokens ?? 0,
      outputTokens: response.usage?.output_tokens ?? 0,
      cacheReadTokens: response.usage?.cache_read_input_tokens ?? 0
  }
  return { content: text || null, usage }
239}

Carrying the id from the client

The browser owns the run boundary, so it mints the id. aiHeaders lazily creates one on a run's first server call and returns it as x-run-id, preserving any base headers; generateRunId prefers crypto.randomUUID and falls back for the rare insecure context. All seven AI fetches in the store route through aiHeaders, and resetGame clears the id so each run gets a fresh one.

Mint (generateRunId), tag (aiHeaders), and reset (resetGame) — the run's lifecycle.

stores/game.ts · 1025 lines

stores/game.ts1025 lines · TypeScript

⋯ 167 lines hidden (lines 1–167)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 { chainStatus, type ChainStatus } from '~/utils/causal-chain'
10import type { Craft } from '~/utils/craft'
11import type { DiceOutcome } from '~/utils/dice'
12import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
13import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
14 
15export type Valence = 'positive' | 'negative' | 'neutral'
16 
17/**
* 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.
*/
22export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
26}
27 
28/**
* 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.
*/
35export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
59}
60 
61/**
* 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.
*/
66export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
90}
91 
92export type GameStatus = 'playing' | 'victory' | 'defeat'
93 
94/**
* 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.
*/
101type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
146 
147const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
148const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
149 
150function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
154}
155 
156/** Formats a signed timeline year (AD positive, BCE negative) for display. */
157export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
159}
160 
161/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
162function 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
166}
167 
168/** A fresh run id. Used to tag every server call in one run so the gateway's
*  cost telemetry groups per run (the GTM cost instrument). randomUUID needs a
*  secure context (https / localhost — both our cases); the fallback covers the
*  rare insecure one. Not security-sensitive: it only groups log lines. */
172function generateRunId(): string {
  try {
      return crypto.randomUUID()
  } catch {
      return `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
  }
178}
⋯ 284 lines hidden (lines 179–462)179 
180export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'unknown'
181 
182/**
* Game Store — core state for a session of freeform timeline editing.
*/
185export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      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
  }),
246 
  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
      },
258 
      /**
       * 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'
          )
      },
269 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
274 
      /**
       * 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'
      },
288 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
293 
      /**
       * 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
      },
305 
      /**
       * 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
      },
321 
      /**
       * The causal-chain read for the CURRENT contact — the pre-send ⏳ chip's
       * source, mirroring what the Timeline Engine will compute. Footholds are the
       * objective's anchor year plus every dated change already on the ledger; the
       * gap to the nearest one decays the swing. Null (no chip) for ungrounded
       * contacts or an anchorless objective with no dated changes yet.
       */
      causalChainRead(): ChainStatus | null {
          const footholds = [
              this.currentObjective?.anchorYear,
              ...this.timelineEvents.map(e => e.whenSigned)
          ]
          return chainStatus(this.contactWhen, footholds)
      }
  },
337 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
349 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
358 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
380 
      // ---------- 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 })
          }
      },
391 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
395 
      /**
       * 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
      },
413 
      /**
       * 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 }, headers: this.aiHeaders() }) as GroundedFigure
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              this.figureGrounding = grounded
              this.contactMoment = null
              if (grounded?.resolved && grounded.born) {
                  const latest = grounded.died ? grounded.died.signed : new Date().getFullYear()
                  this.contactWhen = Math.round((grounded.born.signed + latest) / 2)
              } else {
                  this.contactWhen = null
              }
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              console.error('Figure grounding failed:', error)
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
          } finally {
              if (epoch === this.runEpoch && seq === this.groundingSeq) this.groundingLoading = false
          }
      },
461 
      /** Headers that tag a server call with the current run, so the gateway's
       *  cost telemetry groups every call in this run together (the GTM cost
       *  instrument). Lazily mints the run id on the run's first server call. */
      aiHeaders(base: Record<string, string> = {}): Record<string, string> {
          if (!this.runId) this.runId = generateRunId()
          return { ...base, 'x-run-id': this.runId }
      },
469 
      setContactWhen(year: number | null) {
⋯ 525 lines hidden (lines 471–995)471            // Scrubbing the year keeps any pinned month/day — the pin refines
          // whichever year is chosen, it doesn't belong to one.
          this.contactWhen = year
      },
475 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
479 
      /**
       * 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
496 
          // 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: this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      figureName: studiedName,
                      when: studiedWhen != null ? formatContactYear(studiedWhen) : undefined,
                      description: g.description,
                      extract: g.extract
                  }
              }) as { success?: boolean; study?: FigureStudy; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              // If the contact changed mid-flight, the stale-study clear in
              // groundActiveFigure already ran — don't resurrect the old brief.
              if (res?.blocked && this.figureGrounding?.name === studiedName) {
                  this.studyNotice = res.error || 'That study was blocked by content moderation.'
              } else if (res?.success && res.study && this.figureGrounding?.name === studiedName) {
                  this.figureStudy = res.study
                  this.studyFor = studiedName
                  this.studyWhen = studiedWhen
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
533 
      /**
       * 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: this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
567 
      /**
       * 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
581 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch) this.suggestionsLoading = false
          }
      },
614 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
638 
      // ---------- 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: this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
687 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
693 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
700 
      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)
      },
708 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
713 
      /**
       * 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
              }
          }
      },
730 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
734 
      /**
       * 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'
          }
      },
750 
      // ---------- 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
768 
          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
          }
788 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
796 
          // 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
807 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
840 
              if (epoch !== this.runEpoch) return false
842 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
845 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
853 
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
873 
                  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,
                          causalChain: timeline.causalChain,
                          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()
              }
          }
925 
          // 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
      },
935 
      /**
       * 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
      },
946 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). Returns null rather than throwing if composing
       * fails, so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(): Promise<GameObjective | null> {
          try {
              const res = await $fetch('/api/objective', { method: 'GET', headers: this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
966 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
972 
              const efficiencyRating = rateEfficiency(messagesSaved)
974 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
985 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call.
          this.runId = null
          this.currentObjective = null
⋯ 26 lines hidden (lines 1000–1025)1000            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
      }
  }
1025})

How it's verified

The pricing math and the lane convention are unit-tested in cost.spec; the request binding in run-context.spec; the client lifecycle in the store spec. The claim that matters most — that a real call actually emits both fields — is proven against the gateway with a mocked SDK, so the full path (bound context → gateway → enriched line) runs without a live key.

The observer sees a priced, run-tagged line for a real completeStructured call.

tests/unit/server/utils/anthropic-pipeline.spec.ts · 276 lines

tests/unit/server/utils/anthropic-pipeline.spec.ts276 lines · TypeScript

⋯ 231 lines hidden (lines 1–231)1import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from 'vitest'
2 
3/**
* The Anthropic lane, driven end to end with a mocked SDK: the same band-clamp →
* amplify → sign-guard pipeline the OpenAI spec pins, PLUS the gateway's lane
* shaping — which parameters each model family receives (Haiku never sees
* `effort`, Opus never sees `temperature`), how single-shot vs conversational
* requests are framed, and that the telemetry observer sees every call.
*/
10const createMock = vi.hoisted(() => vi.fn())
11vi.mock('@anthropic-ai/sdk', () => ({
  // A real `function` (not an arrow): the SUT calls `new Anthropic(...)`, and
  // vitest only allows construction of function/class mock implementations.
  default: vi.fn(function () { return { messages: { create: createMock } } })
15}))
16 
17import { callTimelineAI, callJudgeAI, callCharacterAI, callChroniclerAI } from '../../../../server/utils/openai'
18import { setAiCallObserver, type AiCallTelemetry } from '../../../../server/utils/ai-gateway'
19import { setRunContext } from '../../../../server/utils/run-context'
20import { AI_ROUTES } from '../../../../server/utils/ai-routing'
21import { DiceOutcome } from '../../../../utils/dice'
22 
23function modelReturns(payload: unknown) {
  createMock.mockResolvedValueOnce({
      content: [{ type: 'text', text: JSON.stringify(payload) }],
      usage: { input_tokens: 100, output_tokens: 42, cache_read_input_tokens: 0 },
      stop_reason: 'end_turn'
  })
29}
30 
31const TURN = {
  objective: { title: 'Spare the Library', description: 'The scrolls survive.' },
  figureName: 'Julius Caesar',
  era: 'Alexandria, 48 BC',
  userMessage: 'Guard the scrolls.',
  characterMessage: 'It is done.',
  characterAction: 'Caesar shields the library.',
  diceRoll: 16,
  diceOutcome: DiceOutcome.SUCCESS,
  timeline: []
41}
42 
43const ripple = (over: Record<string, unknown> = {}) => ({
  headline: 'The scrolls survive',
  detail: 'Rome guards wisdom.',
  progressChange: 20,
  valence: 'positive',
  anachronism: 'in-period',
  ...over
50})
51 
52beforeAll(() => {
  process.env.ANTHROPIC_API_KEY = 'test-key'
  process.env.REVISIONIST_AI_LANE = 'anthropic'
55})
56 
57afterAll(() => {
  delete process.env.REVISIONIST_AI_LANE
  setAiCallObserver(null)
60})
61 
62beforeEach(() => {
  createMock.mockReset()
64})
65 
66describe('callTimelineAI on the Anthropic lane — same pipeline, new transport', () => {
  it('clamps a model overshoot into the rolled band', async () => {
      modelReturns(ripple({ progressChange: 80, anachronism: 'in-period' }))
      const res = await callTimelineAI(TURN)
      expect(res.success).toBe(true)
      expect(res.ripple?.baseProgressChange).toBe(30) // Success band ceiling
      expect(res.ripple?.progressChange).toBe(30)
  })
74 
  it('amplifies a far-ahead wager and re-colors a contradictory valence', async () => {
      modelReturns(ripple({ progressChange: -20, anachronism: 'in-period', valence: 'negative' }))
      const res = await callTimelineAI(TURN)
      expect(res.ripple?.baseProgressChange).toBe(15) // Success band floor
      expect(res.ripple?.valence).toBe('positive') // sign-guard re-colors it
  })
81 
  it('sends the single-shot prompt as the user message (no contentless turn)', async () => {
      modelReturns(ripple())
      await callTimelineAI(TURN)
      const req = createMock.mock.calls[0][0]
      expect(req.system).toBeUndefined()
      expect(req.messages).toHaveLength(1)
      expect(req.messages[0].role).toBe('user')
      expect(req.messages[0].content).toContain('Spare the Library')
      expect(req.output_config.format.type).toBe('json_schema')
  })
92 
  it('decays a lone blast far from any foothold (causal chain)', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      // Caesar at 50 BC (-50) aimed at an objective anchored in AD 1960 — a ~2,000yr
      // gap with no stones laid: diffuse, a sliver even on a Success.
      const res = await callTimelineAI({ ...TURN, figureYear: -50, objectiveAnchorYear: 1960 })
      expect(res.ripple?.baseProgressChange).toBe(20) // the rolled band value is untouched
      expect(res.ripple?.causalChain?.tier).toBe('diffuse')
      expect(Math.abs(res.ripple!.progressChange)).toBeLessThan(6)
  })
102 
  it('leaves a swing at the hinge at full force', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const res = await callTimelineAI({ ...TURN, figureYear: 1960, objectiveAnchorYear: 1960 })
      expect(res.ripple?.progressChange).toBe(20) // gap 0 → no decay
      expect(res.ripple?.causalChain?.tier).toBe('at-hinge')
  })
109 
  it('no-ops the chain dial for an ungrounded turn (no contact year)', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const res = await callTimelineAI({ ...TURN, objectiveAnchorYear: 1960 }) // no figureYear
      expect(res.ripple?.progressChange).toBe(20)
      expect(res.ripple?.causalChain).toBeUndefined()
  })
116})
117 
118describe('the gateway shapes parameters per model family', () => {
  it('judge (Haiku): temperature yes, effort never, thinking never', async () => {
      modelReturns({ craft: 'sharp', reason: 'Names the lever.' })
      const res = await callJudgeAI({ objective: TURN.objective, figureName: 'Caesar', userMessage: 'x' })
      expect(res.judge?.craft).toBe('sharp')
123 
      const req = createMock.mock.calls[0][0]
      expect(req.model).toBe(AI_ROUTES.judge.anthropic.model)
      expect(req.temperature).toBe(0)
      expect(req.output_config.effort).toBeUndefined()
      expect(req.thinking).toBeUndefined()
  })
130 
  it('the closed-door cap is code, not vibes: a too-late timing demotes the grade (issue #32)', async () => {
      const burned = 'the Hindenburg disaster at Lakehurst — May 6, 1937'
      modelReturns({ event: burned, timing: 'too-late', craft: 'sharp', reason: 'Brilliant wording; the ship already burned.' })
      const late = await callJudgeAI({ objective: TURN.objective, figureName: 'Pruss', when: 'May 8, 1937', momentRefined: true, userMessage: 'x' })
      expect(late.judge?.craft).toBe('vague') // capped in code, whatever the model graded
136 
      modelReturns({ event: burned, timing: 'too-late', craft: 'reckless', reason: 'Unaware its moment passed.' })
      const reckless = await callJudgeAI({ objective: TURN.objective, figureName: 'Pruss', when: 'May 8, 1937', momentRefined: true, userMessage: 'x' })
      expect(reckless.judge?.craft).toBe('reckless') // below the cap stays as graded
140 
      modelReturns({ event: burned, timing: 'in-time', craft: 'sharp', reason: 'Timed to the hinge.' })
      const onTime = await callJudgeAI({ objective: TURN.objective, figureName: 'Pruss', when: 'May 6, 1937', momentRefined: true, userMessage: 'x' })
      expect(onTime.judge?.craft).toBe('sharp') // in-time grades ride through
144 
      // The schema only demands the event+timing pair when a moment is pinned —
      // event FIRST, so the date is written out before the enum compares it.
      const lateReq = createMock.mock.calls[0][0]
      expect(lateReq.output_config.format.schema.required).toContain('event')
      expect(lateReq.output_config.format.schema.required).toContain('timing')
      expect(Object.keys(lateReq.output_config.format.schema.properties).slice(0, 2)).toEqual(['event', 'timing'])
      modelReturns({ craft: 'sound', reason: 'Plain year.' })
      await callJudgeAI({ objective: TURN.objective, figureName: 'Pruss', when: '1937', userMessage: 'x' })
      const yearReq = createMock.mock.calls[3][0]
      expect(yearReq.output_config.format.schema.required).not.toContain('timing')
      expect(yearReq.output_config.format.schema.required).not.toContain('event')
  })
157 
  it('character (Sonnet): system + conversation turns, effort set explicitly', async () => {
      modelReturns({ message: 'So be it.', action: 'Guards the stacks', era: 'Alexandria, 48 BC', persona: 'Roman consul at war' })
      const res = await callCharacterAI('Julius Caesar', 'Guard the scrolls.', [], DiceOutcome.SUCCESS)
      expect(res.success).toBe(true)
162 
      const req = createMock.mock.calls[0][0]
      expect(req.system).toContain('Julius Caesar')
      expect(req.messages[0]).toEqual({ role: 'user', content: 'Guard the scrolls.' })
      // Sonnet defaults effort to HIGH server-side — the table must always pin it.
      expect(req.output_config.effort).toBe(AI_ROUTES.character.anthropic.effort)
  })
169 
  it('the chronicle speaks the Claude voice on this lane — V1 bar for the epilogue, V2 for mid-run', async () => {
      modelReturns({ title: 'The Library Stands', paragraphs: ['It stands.'] })
      await callChroniclerAI({ objective: TURN.objective, timeline: [], status: 'victory', progress: 100 })
      const epilogueReq = createMock.mock.calls[0][0]
      expect(epilogueReq.model).toBe(AI_ROUTES.epilogue.anthropic.model)
      // The pairwise-winning V1 specificity bar, single-shot as the user turn.
      expect(epilogueReq.messages[0].content).toContain('The bar for every sentence')
      expect(epilogueReq.output_config.effort).toBe(AI_ROUTES.epilogue.anthropic.effort)
178 
      modelReturns({ title: 'The Fire Pauses', paragraphs: ['It waits.'] })
      await callChroniclerAI({ objective: TURN.objective, timeline: [], status: 'playing', progress: 40 })
      const midReq = createMock.mock.calls[1][0]
      expect(midReq.model).toBe(AI_ROUTES.chronicler.anthropic.model)
      // Mid-run carries V2's harder demand (the abstraction ban).
      expect(midReq.messages[0].content).toContain('are banned')
  })
186 
  it('reads the text block even when a thinking block precedes it', async () => {
      createMock.mockResolvedValueOnce({
          content: [
              { type: 'thinking', thinking: '', signature: 'sig' },
              { type: 'text', text: JSON.stringify({ title: 'After the Fire', paragraphs: ['Done.'] }) }
          ],
          usage: { input_tokens: 1, output_tokens: 1 },
          stop_reason: 'end_turn'
      })
      const res = await callChroniclerAI({ objective: TURN.objective, timeline: [], status: 'defeat', progress: 10 })
      expect(res.chronicle?.title).toBe('After the Fire')
  })
199})
200 
201describe('telemetry', () => {
  it('the observer sees task, lane, model, and usage for every call', async () => {
      const seen: AiCallTelemetry[] = []
      setAiCallObserver(t => seen.push(t))
      modelReturns(ripple())
      await callTimelineAI(TURN)
      setAiCallObserver(null)
208 
      expect(seen).toHaveLength(1)
      expect(seen[0]).toMatchObject({
          task: 'timeline',
          lane: 'anthropic',
          model: AI_ROUTES.timeline.anthropic.model,
          ok: true,
          usage: { inputTokens: 100, outputTokens: 42, cacheReadTokens: 0 }
      })
  })
218 
  it('a transport failure still emits (ok: false) and the envelope holds', async () => {
      const seen: AiCallTelemetry[] = []
      setAiCallObserver(t => seen.push(t))
      const quiet = vi.spyOn(console, 'error').mockImplementation(() => {})
      createMock.mockRejectedValueOnce(new Error('lane down'))
      const res = await callTimelineAI(TURN)
      quiet.mockRestore()
      setAiCallObserver(null)
227 
      expect(res.success).toBe(false)
      expect(seen[0]).toMatchObject({ task: 'timeline', ok: false })
  })
231 
  it('prices the line from its usage — the cost instrument (GTM dispatch 1)', async () => {
      const seen: AiCallTelemetry[] = []
      setAiCallObserver(t => seen.push(t))
      modelReturns(ripple()) // usage: 100 in / 42 out / 0 cached, timeline → sonnet-4-6
      await callTimelineAI(TURN)
      setAiCallObserver(null)
      // sonnet-4-6 at $3 / $15 per million in/out: (100*3 + 42*15) / 1e6.
      expect(seen[0].usd).toBe(0.00093)
  })
241 
  it('tags the line with the run id bound for the request', async () => {
      const seen: AiCallTelemetry[] = []
      setAiCallObserver(t => seen.push(t))
      setRunContext({ runId: 'run-telemetry-1' })
      modelReturns(ripple())
      await callTimelineAI(TURN)
      setRunContext({}) // clear so the binding can't leak into later tests
      setAiCallObserver(null)
      expect(seen[0].runId).toBe('run-telemetry-1')
  })
252})
⋯ 24 lines hidden (lines 253–276)253 
254describe('a model-side safety refusal (stop_reason refusal) is a block, not an infra error', () => {
  function modelRefuses() {
      createMock.mockResolvedValueOnce({
          content: [{ type: 'text', text: '' }],
          usage: { input_tokens: 50, output_tokens: 0, cache_read_input_tokens: 0 },
          stop_reason: 'refusal'
      })
  }
262 
  it('callCharacterAI surfaces refused:true', async () => {
      modelRefuses()
      const res = await callCharacterAI('Fritz Haber', 'Synthesize chlorine gas at scale.', [], DiceOutcome.SUCCESS)
      expect(res.success).toBe(false)
      expect(res.refused).toBe(true)
  })
269 
  it('callTimelineAI surfaces refused:true', async () => {
      modelRefuses()
      const res = await callTimelineAI(TURN)
      expect(res.success).toBe(false)
      expect(res.refused).toBe(true)
  })
276})