A skills / modifiers layer — a code-level reading

What this PR is

This PR adds one file: a design exploration for issue #94, docs/design/skills-modifiers-layer.md. It is a recommendation, not an implementation — no skill schema, no UI, no economy retune. It mirrors the sibling settings-layer note (#90).

The recommendation is "The Editor's Hand": a small per-run draft of diegetic annotations that amplify the craft channel the game already has. Every annotation is craft-gated — its payout is a function of the Message Judge's grade, so a vague or reckless dispatch gets almost nothing back even after spending a charge. Writing stays king by construction: a skill multiplies or floors what a graded dispatch already earned; it never adds a flat number.

The note's credibility rests on two claims about the existing engine. This guide walks the source behind each so a reviewer can vouch for them. Every line range below was read against the tree at HEAD.

The pipeline — exactly the order the note claims

A turn's swing resolves server-side in callTimelineAI, in a fixed order: the model's number is clamped into the rolled band, then the anachronism amplifier widens it, then causal-chain decay diffuses it, then the gains-only craft and momentum multipliers bank the upside, then it is clamped to the per-turn fuse. The note's "resolution pipeline, in order" list is this block.

Band clamp (230-231) → anachronism (233) → chain decay (241) → gains-only craft × momentum (249-251) → ±50 clamp (252).

server/utils/openai.ts · 577 lines

server/utils/openai.ts577 lines · TypeScript

⋯ 226 lines hidden (lines 1–226)1/**
* The game's AI layers. Historically OpenAI-only (hence the filename, kept to
* avoid churning every reference); today each layer is routed per task through
* the AI gateway (ai-gateway.ts) to its bake-off-chosen lane — Anthropic tiers
* by default, the OpenAI lane alive behind REVISIONIST_AI_LANE.
*
* Every layer keeps the same contract it always had: build prompt → structured
* call → parse → guard → never-throw envelope. The catch-block console.errors
* are intentional (ops signal, not debug cruft).
*/
11import {
  buildCharacterPrompt,
  buildTimelinePrompt,
  buildChroniclePrompt,
  buildChroniclePromptClaude,
  buildResearchPrompt,
  buildLookupPrompt,
  buildJudgePrompt,
  type ObjectiveContext,
  type TimelineContextEntry,
  type CharacterGrounding,
  type ChronicleStatus,
  type FigureStudy,
  type ArchiveLookup
25} from './prompt-builder'
26import { completeStructured, ModelRefusalError, type ChatTurn } from './ai-gateway'
27import { routeFor } from './ai-routing'
28import { amplifyForAnachronism, toAnachronism, type Anachronism } from './anachronism'
29import { chainStatus, decayForChain, type ChainStatus } from '~/utils/causal-chain'
30import { toCraft, CRAFT_LEVELS, CRAFT_MODIFIER, CRAFT_GAIN_FACTOR, type Craft } from '~/utils/craft'
31import { toContinuity, CONTINUITY_LEVELS, type Continuity } from '~/utils/continuity'
32import type { DiceOutcome } from '~/utils/dice'
33import { BAND_CEILING, SWING_BANDS, VALENCE_SIGN_GUARD_MIN } from '~/utils/swing-bands'
34import { MAX_PROGRESS_SWING } from '~/utils/game-config'
35import { momentumFactor } from '~/utils/momentum'
36 
37/**
* What a figure returns each turn: an in-character reply and action, plus factual
* metadata (era, persona) the UI uses to label them.
*/
41export interface StructuredCharacterResponse {
  message: string
  action: string
  era: string
  persona: string
46}
47 
48export interface CharacterAIResponse {
  success: boolean
  characterResponse?: StructuredCharacterResponse
  error?: string
  /** Claude's own safety classifier declined this turn (stop_reason refusal) —
   *  the caller surfaces it as a moderation block, not an infra refund. */
  refused?: boolean
55}
56 
57/**
* The Timeline Engine's verdict for a turn: how history bent.
*/
60export interface TimelineRipple {
  headline: string
  detail: string
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — kept so the UI can
   *  show the wager's work ("+8 ⚡ far-ahead → +11%") instead of an opaque total. */
  baseProgressChange: number
  valence: 'positive' | 'negative' | 'neutral'
  /** How far beyond the figure's era the player reached — widens the swing. */
  anachronism: Anachronism
  /** How far this moment lands from the nearest foothold (objective anchor or a
   *  prior change) — DECAYS the swing toward zero. Absent for ungrounded turns
   *  or anchorless objectives (the dial no-ops). The opposite of anachronism. */
  causalChain?: ChainStatus
74}
75 
76export interface TimelineAIResponse {
  success: boolean
  ripple?: TimelineRipple
  error?: string
  /** Model-side safety refusal — surfaced as a block, not an infra refund. */
  refused?: boolean
82}
83 
84/**
* The Chronicler's telling: a titled, multi-paragraph prose account of the altered
* timeline as it currently stands. Rewritten each turn; the final one is the epilogue.
*/
88export interface ChronicleEntry {
  title: string
  paragraphs: string[]
91}
92 
93export interface ChronicleAIResponse {
  success: boolean
  chronicle?: ChronicleEntry
  error?: string
97}
98 
99interface HistoryItem { text: string; sender: string }
100 
101/**
* Maps the stored conversation thread into chat turns. The thread is expected to
* end with the current user message; if it doesn't (e.g. a direct call with no
* history), the current message is appended so the figure has it.
*/
106function toChatMessages(conversationHistory: HistoryItem[], currentUserMessage: string): ChatTurn[] {
  const mapped: ChatTurn[] = (conversationHistory || [])
      .filter(m => m && typeof m.text === 'string' && m.sender !== 'system')
      .map(m => ({
          role: (m.sender === 'user' ? 'user' : 'assistant') as 'user' | 'assistant',
          content: m.text
      }))
113 
  const last = mapped[mapped.length - 1]
  if (!last || last.role !== 'user' || last.content !== currentUserMessage) {
      mapped.push({ role: 'user', content: currentUserMessage })
  }
  return mapped
119}
120 
121/**
* Layer 1 — role-plays the chosen figure (any name, any era), objective-blind,
* returning a structured reply + action + factual era/persona metadata.
*/
125export async function callCharacterAI(
  figureName: string,
  userMessage: string,
  conversationHistory: HistoryItem[] = [],
  diceOutcome: DiceOutcome,
  grounding?: CharacterGrounding,
  worldBrief?: string[],
  /** True when the dispatch carries no actionable substance — keeps the figure
   *  honest so a favorable roll on noise yields confusion, not a fabricated deed. */
  contentless?: boolean
135): Promise<CharacterAIResponse> {
  try {
      const content = await completeStructured({
          task: 'character',
          system: buildCharacterPrompt(figureName, diceOutcome, grounding, worldBrief, contentless),
          turns: toChatMessages(conversationHistory, userMessage),
          schemaName: 'character_response',
          schema: {
              type: 'object',
              properties: {
                  message: { type: 'string', description: `${figureName}'s in-character reply, 160 chars max` },
                  action: { type: 'string', description: `The concrete thing ${figureName} decides to do` },
                  era: { type: 'string', description: 'Short factual when/where tag, e.g. "Vienna, 1914"' },
                  persona: { type: 'string', description: 'A 3-6 word factual descriptor of the figure' }
              },
              required: ['message', 'action', 'era', 'persona'],
              additionalProperties: false
          }
      })
154 
      if (!content) {
          return { success: false, error: 'Character AI generated an empty response' }
      }
158 
      const parsed = JSON.parse(content) as StructuredCharacterResponse
      if (!parsed.message || !parsed.action) {
          return { success: false, error: 'Character AI response missing required fields' }
      }
163 
      return { success: true, characterResponse: parsed }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This dispatch was declined by content moderation and cannot be sent.' }
      }
      console.error('Character AI error:', error)
      return { success: false, error: 'Character AI could not process the request' }
  }
172}
173 
174/**
* Layer 2 — judges how the figure's action ripples through the already-altered
* world toward the live objective, returning a structured timeline ripple.
*/
178export async function callTimelineAI(args: {
  objective: ObjectiveContext
  figureName: string
  era: string
  userMessage: string
  characterMessage: string
  characterAction: string
  diceRoll: number
  diceOutcome: DiceOutcome
  timeline?: TimelineContextEntry[]
  figureYear?: number
  figureMoment?: string
  /** The objective's far anchor year — a foothold for the causal-chain dial. */
  objectiveAnchorYear?: number
  /** The Judge's craft grade for this dispatch — drives the gains-only craft
   *  amplifier (issue #62). Absent → no amplification (factor 1). */
  craft?: Craft
  /** The run's PRE-turn momentum (0..4) — the run-level gains amplifier that rides
   *  alongside craft. Absent → no amplification (factor 1). */
  momentum?: number
198}): Promise<TimelineAIResponse> {
  try {
      const content = await completeStructured({
          task: 'timeline',
          system: buildTimelinePrompt({ ...args, timeline: args.timeline ?? [] }),
          schemaName: 'timeline_ripple',
          schema: {
              type: 'object',
              properties: {
                  headline: { type: 'string', description: 'Punchy headline, ~9 words max' },
                  detail: { type: 'string', description: '1-2 sentences describing the ripple through history' },
                  progressChange: { type: 'integer', description: `Integer from -${BAND_CEILING} to ${BAND_CEILING}, within the rolled band` },
                  valence: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
                  anachronism: { type: 'string', enum: ['in-period', 'ahead', 'far-ahead', 'impossible'], description: 'How far beyond the figure’s era the message reached' }
              },
              required: ['headline', 'detail', 'progressChange', 'valence', 'anachronism'],
              additionalProperties: false
          }
      })
217 
      if (!content) {
          return { success: false, error: 'Timeline AI generated an empty response' }
      }
221 
      const parsed = JSON.parse(content)
      if (typeof parsed.headline !== 'string' || typeof parsed.detail !== 'string' || typeof parsed.progressChange !== 'number') {
          return { success: false, error: 'Timeline AI response missing required fields' }
      }
226 
      // The band table is law — in code, not just prompt: the model's base swing
      // is clamped into the ROLLED band before the amplifier touches it, so the
      // disclosed legend and the engine can never disagree about a roll's range.
      const band = SWING_BANDS[args.diceOutcome]
      const baseProgress = Math.max(band.min, Math.min(band.max, Math.round(parsed.progressChange)))
      const anachronism = toAnachronism(parsed.anachronism)
      const amplified = amplifyForAnachronism(baseProgress, anachronism)
      // Causal-chain decay (the opposite dial): a reach far from any foothold is
      // diffused toward zero. Footholds are the objective's anchor year plus every
      // dated change already on the ledger — so landing a change plants a new
      // foothold and chaining forward overcomes the distance. No-ops (factor 1)
      // for ungrounded turns or anchorless objectives.
      const footholds = [args.objectiveAnchorYear, ...(args.timeline ?? []).map(e => e.whenSigned)]
      const causalChain = chainStatus(args.figureYear, footholds) ?? undefined
      const decayed = causalChain ? decayForChain(amplified, causalChain.factor) : amplified
      // Gains-only amplifiers (issue #62): a sharper dispatch (craft) and a more
      // coherent arc (momentum) each bank more of the band the roll earned — but ONLY
      // on the upside. Losses keep the rolled band's verdict untouched (mirrors
      // amplifyForAnachronism's sign branch), so skill buys reach, never immunity.
      // After this the value can exceed the per-turn fuse, and nothing downstream
      // re-clamps an UPWARD push before the (post-stake) ±100 cap — so re-clamp to
      // ±MAX_PROGRESS_SWING here.
      const craftFactor = args.craft ? CRAFT_GAIN_FACTOR[args.craft] : 1
      const momoFactor = momentumFactor(args.momentum ?? 0)
      const gained = decayed > 0 ? decayed * craftFactor * momoFactor : decayed
      const progressChange = Math.max(-MAX_PROGRESS_SWING, Math.min(MAX_PROGRESS_SWING, Math.round(gained)))
⋯ 325 lines hidden (lines 253–577)253        const modelValence: TimelineRipple['valence'] =
          parsed.valence === 'positive' || parsed.valence === 'negative' || parsed.valence === 'neutral'
              ? parsed.valence
              : (progressChange > 0 ? 'positive' : progressChange < 0 ? 'negative' : 'neutral')
      // Sign guard: a swing beyond the neutral window (±3, the eval's own line)
      // must wear the color of its sign — a "positive" badge on a -12 turn is a
      // straight "this game is arbitrary" signal. Small swings keep the model's
      // shading, where "neutral" or a soft contradiction is fair judgment.
      const signValence: TimelineRipple['valence'] = progressChange > 0 ? 'positive' : 'negative'
      const valence = Math.abs(progressChange) > VALENCE_SIGN_GUARD_MIN ? signValence : modelValence
263 
      return {
          success: true,
          ripple: { headline: parsed.headline, detail: parsed.detail, progressChange, baseProgressChange: baseProgress, valence, anachronism, causalChain }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This dispatch was declined by content moderation and cannot be sent.' }
      }
      console.error('Timeline AI error:', error)
      return { success: false, error: 'Timeline AI could not process the request' }
  }
275}
276 
277/**
* The Message Judge (roadmap slice 5) — grades the craft of the player's dispatch
* BEFORE the dice are thrown; the grade becomes a small roll modifier. Objective-
* aware (it judges leverage toward the goal) but outcome-blind: it never sees the
* roll. A failure here must never punish the player — callers fall back to the
* neutral 'sound' (modifier 0), so a Judge outage just means an untilted die.
*/
284export interface JudgeVerdict {
  craft: Craft
  /** Whether the dispatch builds on the run's thread — feeds the momentum meter
   *  (issue #62). 'neutral' on turn 1 or a Judge outage (never moves momentum). */
  continuity: Continuity
  reason: string
290}
291 
292export interface JudgeAIResponse {
  success: boolean
  judge?: JudgeVerdict
  error?: string
296}
297 
298export async function callJudgeAI(args: {
  objective: ObjectiveContext
  figureName: string
  when?: string
  momentRefined?: boolean
  userMessage: string
  /** The figure's reply on the PRIOR turn — their last revealed condition/price.
   *  Empty on turn 1. The Judge reads it to see if THIS dispatch meets it. */
  lastFigureReply?: string
  /** A short digest of recent ledger headlines so the Judge can spot a dispatch
   *  that deliberately exploits a change already on the record. */
  ledgerDigest?: string[]
310}): Promise<JudgeAIResponse> {
  try {
      // With a pinned moment the schema gains two leading fields: "event"
      // makes the model WRITE OUT the real event and its real-world date, so
      // the "timing" enum right after it compares two dates sitting on the
      // page instead of inferring silently inside one token. Probed 24/24 on
      // Haiku and Sonnet where a bare timing enum failed 0/12 — date retrieval
      // must be a generation step, not an implication. The CAP is still
      // enforced in code below (legend-is-law, like the band clamp).
      const timingFields = args.momentRefined
          ? {
              event: {
                  type: 'string',
                  description: 'The real recorded historical event this dispatch is trying to influence, and the exact real-world date it occurred (e.g. "the Hindenburg disaster at Lakehurst — May 6, 1937")'
              },
              timing: {
                  type: 'string',
                  enum: ['in-time', 'too-late'],
                  description: '"too-late" if the event\'s real date above is earlier than the stated moment the dispatch arrives — its chance already spent; otherwise "in-time"'
              }
          }
          : {}
      // Continuity is read only when there's a thread to build on. On turn 1 (no
      // prior reply, empty ledger) the prompt + schema stay byte-identical to the
      // pre-feature build and continuity defaults to 'neutral' — momentum can't
      // build out of nothing anyway.
      const hasThread = !!(args.lastFigureReply || args.ledgerDigest?.length)
      const continuityField = hasThread
          ? {
              continuity: {
                  type: 'string',
                  enum: [...CONTINUITY_LEVELS],
                  description: '"builds" if this dispatch meets a condition/price the figure just revealed, deliberately exploits a change already on the record, or coheres with and escalates the run\'s strategy; "resets" if it abandons that thread and starts cold; "neutral" otherwise'
              }
          }
          : {}
      const content = await completeStructured({
          task: 'judge',
          system: buildJudgePrompt(args),
          schemaName: 'craft_verdict',
          schema: {
              type: 'object',
              properties: {
                  ...timingFields,
                  craft: { type: 'string', enum: [...CRAFT_LEVELS], description: 'The dispatch’s craft grade' },
                  ...continuityField,
                  reason: { type: 'string', description: 'One terse player-facing sentence, under 90 characters' }
              },
              required: [...(args.momentRefined ? ['event', 'timing'] : []), 'craft', ...(hasThread ? ['continuity'] : []), 'reason'],
              additionalProperties: false
          }
      })
362 
      if (!content) {
          return { success: false, error: 'Judge generated an empty response' }
      }
366 
      const parsed = JSON.parse(content) as { timing?: unknown; craft?: unknown; continuity?: unknown; reason?: unknown }
      let craft = toCraft(parsed.craft)
      // The closed-door cap, in code: a too-late pin grades vague at best.
      if (args.momentRefined && parsed.timing === 'too-late' && CRAFT_MODIFIER[craft] > CRAFT_MODIFIER.vague) {
          craft = 'vague'
      }
      return {
          success: true,
          judge: {
              craft,
              continuity: toContinuity(parsed.continuity),
              reason: typeof parsed.reason === 'string' ? parsed.reason.trim().slice(0, 120) : ''
          }
      }
  } catch (error) {
      console.error('Judge AI error:', error)
      return { success: false, error: 'Judge could not assess the dispatch' }
  }
385}
386 
387/**
* The Archivist (prototype) — a grounded, OBJECTIVE-BLIND brief on a real figure at
* a chosen point in their life: who they are, what they grasp, what they're reaching
* for, and what lies beyond their era. In-game research so the player needn't break
* out to a search engine — it enriches the world, never makes their move.
*/
393export interface ArchivistAIResponse {
  success: boolean
  study?: FigureStudy
  error?: string
  /** Claude's own safety classifier declined the study — surfaced as a moderation
   *  block (the study-blocked banner), not an infra failure. */
  refused?: boolean
400}
401 
402export async function callArchivistAI(args: {
  figureName: string
  when?: string
  description?: string
  extract?: string
407}): Promise<ArchivistAIResponse> {
  try {
      const content = await completeStructured({
          task: 'archivist-study',
          system: buildResearchPrompt(args),
          schemaName: 'figure_study',
          schema: {
              type: 'object',
              properties: {
                  atThisMoment: { type: 'string', description: 'Where the figure stands in life and work at the chosen moment' },
                  grasp: { type: 'array', items: { type: 'string' }, description: '2-4 things they genuinely understand' },
                  reaching: { type: 'array', items: { type: 'string' }, description: '2-4 things they pursue or are stuck on' },
                  cannotYetKnow: { type: 'string', description: 'One sentence on what lies beyond their era' }
              },
              required: ['atThisMoment', 'grasp', 'reaching', 'cannotYetKnow'],
              additionalProperties: false
          }
      })
425 
      if (!content) {
          return { success: false, error: 'Archivist generated an empty response' }
      }
429 
      const parsed = JSON.parse(content) as { atThisMoment?: unknown; grasp?: unknown; reaching?: unknown; cannotYetKnow?: unknown }
      const asStrings = (v: unknown): string[] =>
          Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string' && s.trim().length > 0) : []
      const grasp = asStrings(parsed.grasp)
      const reaching = asStrings(parsed.reaching)
      if (typeof parsed.atThisMoment !== 'string' || !parsed.atThisMoment.trim() || (!grasp.length && !reaching.length)) {
          return { success: false, error: 'Archivist response missing required fields' }
      }
438 
      return {
          success: true,
          study: {
              atThisMoment: parsed.atThisMoment.trim(),
              grasp,
              reaching,
              cannotYetKnow: typeof parsed.cannotYetKnow === 'string' ? parsed.cannotYetKnow.trim() : ''
          }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This study was declined by content moderation.' }
      }
      console.error('Archivist AI error:', error)
      return { success: false, error: 'Archivist could not process the request' }
  }
455}
456 
457/**
* The Archive lookup (prototype, "yellow") — a concise, factual answer to a freeform
* topic query, stamped with when the knowledge first emerged so the player can read
* its anachronism. Pure domain facts (what/ingredients/when), never strategy.
*/
462export interface ArchiveLookupResponse {
  success: boolean
  lookup?: ArchiveLookup
  error?: string
  /** Claude's own safety classifier declined the lookup — surfaced as a moderation
   *  block (the lookup-blocked banner), not an infra failure. */
  refused?: boolean
469}
470 
471export async function callArchiveLookupAI(query: string): Promise<ArchiveLookupResponse> {
  try {
      const content = await completeStructured({
          task: 'archive-lookup',
          system: buildLookupPrompt(query),
          schemaName: 'archive_lookup',
          schema: {
              type: 'object',
              properties: {
                  topic: { type: 'string', description: 'Short title for what was asked' },
                  summary: { type: 'string', description: 'One or two plain sentences — the essential fact' },
                  requires: { type: 'array', items: { type: 'string' }, description: 'Concrete ingredients / prerequisites, or empty' },
                  knownSince: { type: 'string', description: 'When/where this knowledge first emerged' }
              },
              required: ['topic', 'summary', 'requires', 'knownSince'],
              additionalProperties: false
          }
      })
489 
      if (!content) {
          return { success: false, error: 'Archive generated an empty response' }
      }
493 
      const parsed = JSON.parse(content) as { topic?: unknown; summary?: unknown; requires?: unknown; knownSince?: unknown }
      if (typeof parsed.topic !== 'string' || typeof parsed.summary !== 'string' || !parsed.summary.trim()) {
          return { success: false, error: 'Archive response missing required fields' }
      }
      const requires = Array.isArray(parsed.requires)
          ? parsed.requires.filter((s): s is string => typeof s === 'string' && s.trim().length > 0)
          : []
501 
      return {
          success: true,
          lookup: {
              topic: parsed.topic.trim() || query,
              summary: parsed.summary.trim(),
              requires,
              knownSince: typeof parsed.knownSince === 'string' ? parsed.knownSince.trim() : ''
          }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'That lookup was declined by content moderation.' }
      }
      console.error('Archive lookup error:', error)
      return { success: false, error: 'Archive could not process the request' }
  }
518}
519 
520/**
* Layer 3 — the Chronicler. Narrates the whole altered timeline as it now stands,
* rewritten each turn from the running ledger. It judges nothing, so a failure is
* non-fatal: the caller simply keeps the prior telling rather than blanking the panel.
*
* The FINAL telling (victory/defeat) is the run's epilogue — the share artifact —
* and routes as its own task so the flagship model can carry that one moment.
*/
528export async function callChroniclerAI(args: {
  objective: ObjectiveContext
  timeline: TimelineContextEntry[]
  status: ChronicleStatus
  progress: number
533}): Promise<ChronicleAIResponse> {
  try {
      const task = args.status === 'playing' ? 'chronicler' : 'epilogue'
      // Prompts are per-model artifacts: the Claude voice won its lane in
      // blind pairwise (see buildChroniclePromptClaude); the incumbent voice
      // stays exactly as-is for the OpenAI lane, so the fallback lever keeps
      // its tuned prompt too.
      const { lane } = routeFor(task)
      const content = await completeStructured({
          task,
          system: lane === 'anthropic' ? buildChroniclePromptClaude(args) : buildChroniclePrompt(args),
          schemaName: 'chronicle',
          schema: {
              type: 'object',
              properties: {
                  title: { type: 'string', description: 'Short, evocative title for this version of history (3-6 words)' },
                  paragraphs: {
                      type: 'array',
                      items: { type: 'string' },
                      description: '2-4 short paragraphs of prose, in reading order'
                  }
              },
              required: ['title', 'paragraphs'],
              additionalProperties: false
          }
      })
559 
      if (!content) {
          return { success: false, error: 'Chronicle AI generated an empty response' }
      }
563 
      const parsed = JSON.parse(content) as { title?: unknown; paragraphs?: unknown }
      const paragraphs = Array.isArray(parsed.paragraphs)
          ? parsed.paragraphs.filter((p): p is string => typeof p === 'string' && p.trim().length > 0)
          : []
      if (typeof parsed.title !== 'string' || !parsed.title.trim() || paragraphs.length === 0) {
          return { success: false, error: 'Chronicle AI response missing required fields' }
      }
571 
      return { success: true, chronicle: { title: parsed.title.trim(), paragraphs } }
  } catch (error) {
      console.error('Chronicle AI error:', error)
      return { success: false, error: 'Chronicle AI could not process the request' }
  }
577}

Why "swing-neutral" is a myth here

The obvious lean skill is a reroll or a band-floor that adds no expected value and so (the claim goes) needs no retune. The note argues this is wrong, and the reason is in two places. First, craft already has two compounding channels: a ±2 die-tilt and a ×0.15–1.45 gains multiplier.

CRAFT_MODIFIER (±2 on the die) and CRAFT_GAIN_FACTOR (×0.15–1.45 on the gain) — the two channels a skill would amplify.

utils/craft.ts · 64 lines

utils/craft.ts64 lines · TypeScript

⋯ 13 lines hidden (lines 1–13)1/**
2 * Message craft — the Judge's grade of the player's words (roadmap slice 5).
3 *
4 * The Judge reads the dispatch BEFORE the dice are thrown and converts its craft
5 * into a small roll modifier: writing a sharper message visibly tilts fate. The
6 * dice still dominate any single turn (±2 at most); craft decides the campaign.
7 * Lives in utils/ because both sides read it: the server maps grade → modifier,
8 * the UI labels the grade in the turn reveal.
9 */
10export type Craft = 'masterful' | 'sharp' | 'sound' | 'vague' | 'reckless'
11 
12export const CRAFT_LEVELS: Craft[] = ['masterful', 'sharp', 'sound', 'vague', 'reckless']
13 
14/** Roll modifier per grade — combined with the 1–20 clamp in `applyCraftModifier`,
15 *  a masterful dispatch cannot critically backfire, a reckless one cannot
16 *  critically cascade. Both edges are deliberate, legible rewards. */
17export const CRAFT_MODIFIER: Record<Craft, number> = {
18    masterful: 2,
19    sharp: 1,
20    sound: 0,
21    vague: -1,
22    reckless: -2
23}
24 
25/** Multiplicative swing factor per grade — a GAINS-ONLY amplifier applied to a
26 *  turn's POSITIVE progress inside the Timeline Engine (after causal decay, before
27 *  the per-turn clamp). Losses are never scaled: the downside stays governed by the
28 *  rolled band, so a sharp dispatch buys upside without buying immunity. Floor 0.15,
29 *  never 0 — a graded dispatch always counts for something (rails, not walls). This
30 *  is the craft channel's SECOND, multiplicative half: the ±2 CRAFT_MODIFIER above
31 *  tilts the die toward a better band; this scales the gain that band pays out. The
32 *  two compound on purpose — that compounding is how craft decides the campaign. */
33export const CRAFT_GAIN_FACTOR: Record<Craft, number> = {
34    masterful: 1.45,
35    sharp: 1.20,
36    sound: 1.00,
37    vague: 0.40,
38    reckless: 0.15
39}
⋯ 25 lines hidden (lines 40–64)40 
41/** Short player-facing label per grade (for the turn reveal / ledger). */
42export const CRAFT_LABEL: Record<Craft, string> = {
43    masterful: 'Masterful',
44    sharp: 'Sharp',
45    sound: 'Sound',
46    vague: 'Vague',
47    reckless: 'Reckless'
48}
49 
50/** One-line hover hint per grade — what it means and how it tilts the roll.
51 *  Lives beside the modifier so the copy and the number can never drift apart. */
52export const CRAFT_HINT: Record<Craft, string> = {
53    masterful: 'precise and period-fluent — adds 2 to the roll; cannot critically backfire',
54    sharp: 'a cut above competent — adds 1 to the roll',
55    sound: 'a clear, honest ask — leaves the roll unchanged',
56    vague: 'wishing more than working — subtracts 1 from the roll',
57    reckless: 'incoherent for the era — subtracts 2 from the roll; cannot critically land'
58}
59 
60/** Coerce an untrusted value to a known grade. Defaults to the neutral 'sound':
61 *  a Judge outage must never tilt the roll either way. */
62export function toCraft(value: unknown): Craft {
63    return CRAFT_LEVELS.includes(value as Craft) ? (value as Craft) : 'sound'
64}

Second, the gains multipliers apply only to a positive swing; losses pass through untouched. So the band → progress map is convex on the upside.

gained = decayed > 0 ? decayed * craftFactor * momoFactor : decayed — gains-only. Losses keep the rolled band's verdict.

server/utils/openai.ts · 577 lines

server/utils/openai.ts577 lines · TypeScript

⋯ 241 lines hidden (lines 1–241)1/**
* The game's AI layers. Historically OpenAI-only (hence the filename, kept to
* avoid churning every reference); today each layer is routed per task through
* the AI gateway (ai-gateway.ts) to its bake-off-chosen lane — Anthropic tiers
* by default, the OpenAI lane alive behind REVISIONIST_AI_LANE.
*
* Every layer keeps the same contract it always had: build prompt → structured
* call → parse → guard → never-throw envelope. The catch-block console.errors
* are intentional (ops signal, not debug cruft).
*/
11import {
  buildCharacterPrompt,
  buildTimelinePrompt,
  buildChroniclePrompt,
  buildChroniclePromptClaude,
  buildResearchPrompt,
  buildLookupPrompt,
  buildJudgePrompt,
  type ObjectiveContext,
  type TimelineContextEntry,
  type CharacterGrounding,
  type ChronicleStatus,
  type FigureStudy,
  type ArchiveLookup
25} from './prompt-builder'
26import { completeStructured, ModelRefusalError, type ChatTurn } from './ai-gateway'
27import { routeFor } from './ai-routing'
28import { amplifyForAnachronism, toAnachronism, type Anachronism } from './anachronism'
29import { chainStatus, decayForChain, type ChainStatus } from '~/utils/causal-chain'
30import { toCraft, CRAFT_LEVELS, CRAFT_MODIFIER, CRAFT_GAIN_FACTOR, type Craft } from '~/utils/craft'
31import { toContinuity, CONTINUITY_LEVELS, type Continuity } from '~/utils/continuity'
32import type { DiceOutcome } from '~/utils/dice'
33import { BAND_CEILING, SWING_BANDS, VALENCE_SIGN_GUARD_MIN } from '~/utils/swing-bands'
34import { MAX_PROGRESS_SWING } from '~/utils/game-config'
35import { momentumFactor } from '~/utils/momentum'
36 
37/**
* What a figure returns each turn: an in-character reply and action, plus factual
* metadata (era, persona) the UI uses to label them.
*/
41export interface StructuredCharacterResponse {
  message: string
  action: string
  era: string
  persona: string
46}
47 
48export interface CharacterAIResponse {
  success: boolean
  characterResponse?: StructuredCharacterResponse
  error?: string
  /** Claude's own safety classifier declined this turn (stop_reason refusal) —
   *  the caller surfaces it as a moderation block, not an infra refund. */
  refused?: boolean
55}
56 
57/**
* The Timeline Engine's verdict for a turn: how history bent.
*/
60export interface TimelineRipple {
  headline: string
  detail: string
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — kept so the UI can
   *  show the wager's work ("+8 ⚡ far-ahead → +11%") instead of an opaque total. */
  baseProgressChange: number
  valence: 'positive' | 'negative' | 'neutral'
  /** How far beyond the figure's era the player reached — widens the swing. */
  anachronism: Anachronism
  /** How far this moment lands from the nearest foothold (objective anchor or a
   *  prior change) — DECAYS the swing toward zero. Absent for ungrounded turns
   *  or anchorless objectives (the dial no-ops). The opposite of anachronism. */
  causalChain?: ChainStatus
74}
75 
76export interface TimelineAIResponse {
  success: boolean
  ripple?: TimelineRipple
  error?: string
  /** Model-side safety refusal — surfaced as a block, not an infra refund. */
  refused?: boolean
82}
83 
84/**
* The Chronicler's telling: a titled, multi-paragraph prose account of the altered
* timeline as it currently stands. Rewritten each turn; the final one is the epilogue.
*/
88export interface ChronicleEntry {
  title: string
  paragraphs: string[]
91}
92 
93export interface ChronicleAIResponse {
  success: boolean
  chronicle?: ChronicleEntry
  error?: string
97}
98 
99interface HistoryItem { text: string; sender: string }
100 
101/**
* Maps the stored conversation thread into chat turns. The thread is expected to
* end with the current user message; if it doesn't (e.g. a direct call with no
* history), the current message is appended so the figure has it.
*/
106function toChatMessages(conversationHistory: HistoryItem[], currentUserMessage: string): ChatTurn[] {
  const mapped: ChatTurn[] = (conversationHistory || [])
      .filter(m => m && typeof m.text === 'string' && m.sender !== 'system')
      .map(m => ({
          role: (m.sender === 'user' ? 'user' : 'assistant') as 'user' | 'assistant',
          content: m.text
      }))
113 
  const last = mapped[mapped.length - 1]
  if (!last || last.role !== 'user' || last.content !== currentUserMessage) {
      mapped.push({ role: 'user', content: currentUserMessage })
  }
  return mapped
119}
120 
121/**
* Layer 1 — role-plays the chosen figure (any name, any era), objective-blind,
* returning a structured reply + action + factual era/persona metadata.
*/
125export async function callCharacterAI(
  figureName: string,
  userMessage: string,
  conversationHistory: HistoryItem[] = [],
  diceOutcome: DiceOutcome,
  grounding?: CharacterGrounding,
  worldBrief?: string[],
  /** True when the dispatch carries no actionable substance — keeps the figure
   *  honest so a favorable roll on noise yields confusion, not a fabricated deed. */
  contentless?: boolean
135): Promise<CharacterAIResponse> {
  try {
      const content = await completeStructured({
          task: 'character',
          system: buildCharacterPrompt(figureName, diceOutcome, grounding, worldBrief, contentless),
          turns: toChatMessages(conversationHistory, userMessage),
          schemaName: 'character_response',
          schema: {
              type: 'object',
              properties: {
                  message: { type: 'string', description: `${figureName}'s in-character reply, 160 chars max` },
                  action: { type: 'string', description: `The concrete thing ${figureName} decides to do` },
                  era: { type: 'string', description: 'Short factual when/where tag, e.g. "Vienna, 1914"' },
                  persona: { type: 'string', description: 'A 3-6 word factual descriptor of the figure' }
              },
              required: ['message', 'action', 'era', 'persona'],
              additionalProperties: false
          }
      })
154 
      if (!content) {
          return { success: false, error: 'Character AI generated an empty response' }
      }
158 
      const parsed = JSON.parse(content) as StructuredCharacterResponse
      if (!parsed.message || !parsed.action) {
          return { success: false, error: 'Character AI response missing required fields' }
      }
163 
      return { success: true, characterResponse: parsed }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This dispatch was declined by content moderation and cannot be sent.' }
      }
      console.error('Character AI error:', error)
      return { success: false, error: 'Character AI could not process the request' }
  }
172}
173 
174/**
* Layer 2 — judges how the figure's action ripples through the already-altered
* world toward the live objective, returning a structured timeline ripple.
*/
178export async function callTimelineAI(args: {
  objective: ObjectiveContext
  figureName: string
  era: string
  userMessage: string
  characterMessage: string
  characterAction: string
  diceRoll: number
  diceOutcome: DiceOutcome
  timeline?: TimelineContextEntry[]
  figureYear?: number
  figureMoment?: string
  /** The objective's far anchor year — a foothold for the causal-chain dial. */
  objectiveAnchorYear?: number
  /** The Judge's craft grade for this dispatch — drives the gains-only craft
   *  amplifier (issue #62). Absent → no amplification (factor 1). */
  craft?: Craft
  /** The run's PRE-turn momentum (0..4) — the run-level gains amplifier that rides
   *  alongside craft. Absent → no amplification (factor 1). */
  momentum?: number
198}): Promise<TimelineAIResponse> {
  try {
      const content = await completeStructured({
          task: 'timeline',
          system: buildTimelinePrompt({ ...args, timeline: args.timeline ?? [] }),
          schemaName: 'timeline_ripple',
          schema: {
              type: 'object',
              properties: {
                  headline: { type: 'string', description: 'Punchy headline, ~9 words max' },
                  detail: { type: 'string', description: '1-2 sentences describing the ripple through history' },
                  progressChange: { type: 'integer', description: `Integer from -${BAND_CEILING} to ${BAND_CEILING}, within the rolled band` },
                  valence: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
                  anachronism: { type: 'string', enum: ['in-period', 'ahead', 'far-ahead', 'impossible'], description: 'How far beyond the figure’s era the message reached' }
              },
              required: ['headline', 'detail', 'progressChange', 'valence', 'anachronism'],
              additionalProperties: false
          }
      })
217 
      if (!content) {
          return { success: false, error: 'Timeline AI generated an empty response' }
      }
221 
      const parsed = JSON.parse(content)
      if (typeof parsed.headline !== 'string' || typeof parsed.detail !== 'string' || typeof parsed.progressChange !== 'number') {
          return { success: false, error: 'Timeline AI response missing required fields' }
      }
226 
      // The band table is law — in code, not just prompt: the model's base swing
      // is clamped into the ROLLED band before the amplifier touches it, so the
      // disclosed legend and the engine can never disagree about a roll's range.
      const band = SWING_BANDS[args.diceOutcome]
      const baseProgress = Math.max(band.min, Math.min(band.max, Math.round(parsed.progressChange)))
      const anachronism = toAnachronism(parsed.anachronism)
      const amplified = amplifyForAnachronism(baseProgress, anachronism)
      // Causal-chain decay (the opposite dial): a reach far from any foothold is
      // diffused toward zero. Footholds are the objective's anchor year plus every
      // dated change already on the ledger — so landing a change plants a new
      // foothold and chaining forward overcomes the distance. No-ops (factor 1)
      // for ungrounded turns or anchorless objectives.
      const footholds = [args.objectiveAnchorYear, ...(args.timeline ?? []).map(e => e.whenSigned)]
      const causalChain = chainStatus(args.figureYear, footholds) ?? undefined
      const decayed = causalChain ? decayForChain(amplified, causalChain.factor) : amplified
      // Gains-only amplifiers (issue #62): a sharper dispatch (craft) and a more
      // coherent arc (momentum) each bank more of the band the roll earned — but ONLY
      // on the upside. Losses keep the rolled band's verdict untouched (mirrors
      // amplifyForAnachronism's sign branch), so skill buys reach, never immunity.
      // After this the value can exceed the per-turn fuse, and nothing downstream
      // re-clamps an UPWARD push before the (post-stake) ±100 cap — so re-clamp to
      // ±MAX_PROGRESS_SWING here.
      const craftFactor = args.craft ? CRAFT_GAIN_FACTOR[args.craft] : 1
      const momoFactor = momentumFactor(args.momentum ?? 0)
      const gained = decayed > 0 ? decayed * craftFactor * momoFactor : decayed
      const progressChange = Math.max(-MAX_PROGRESS_SWING, Math.min(MAX_PROGRESS_SWING, Math.round(gained)))
⋯ 325 lines hidden (lines 253–577)253        const modelValence: TimelineRipple['valence'] =
          parsed.valence === 'positive' || parsed.valence === 'negative' || parsed.valence === 'neutral'
              ? parsed.valence
              : (progressChange > 0 ? 'positive' : progressChange < 0 ? 'negative' : 'neutral')
      // Sign guard: a swing beyond the neutral window (±3, the eval's own line)
      // must wear the color of its sign — a "positive" badge on a -12 turn is a
      // straight "this game is arbitrary" signal. Small swings keep the model's
      // shading, where "neutral" or a soft contradiction is fair judgment.
      const signValence: TimelineRipple['valence'] = progressChange > 0 ? 'positive' : 'negative'
      const valence = Math.abs(progressChange) > VALENCE_SIGN_GUARD_MIN ? signValence : modelValence
263 
      return {
          success: true,
          ripple: { headline: parsed.headline, detail: parsed.detail, progressChange, baseProgressChange: baseProgress, valence, anachronism, causalChain }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This dispatch was declined by content moderation and cannot be sent.' }
      }
      console.error('Timeline AI error:', error)
      return { success: false, error: 'Timeline AI could not process the request' }
  }
275}
276 
277/**
* The Message Judge (roadmap slice 5) — grades the craft of the player's dispatch
* BEFORE the dice are thrown; the grade becomes a small roll modifier. Objective-
* aware (it judges leverage toward the goal) but outcome-blind: it never sees the
* roll. A failure here must never punish the player — callers fall back to the
* neutral 'sound' (modifier 0), so a Judge outage just means an untilted die.
*/
284export interface JudgeVerdict {
  craft: Craft
  /** Whether the dispatch builds on the run's thread — feeds the momentum meter
   *  (issue #62). 'neutral' on turn 1 or a Judge outage (never moves momentum). */
  continuity: Continuity
  reason: string
290}
291 
292export interface JudgeAIResponse {
  success: boolean
  judge?: JudgeVerdict
  error?: string
296}
297 
298export async function callJudgeAI(args: {
  objective: ObjectiveContext
  figureName: string
  when?: string
  momentRefined?: boolean
  userMessage: string
  /** The figure's reply on the PRIOR turn — their last revealed condition/price.
   *  Empty on turn 1. The Judge reads it to see if THIS dispatch meets it. */
  lastFigureReply?: string
  /** A short digest of recent ledger headlines so the Judge can spot a dispatch
   *  that deliberately exploits a change already on the record. */
  ledgerDigest?: string[]
310}): Promise<JudgeAIResponse> {
  try {
      // With a pinned moment the schema gains two leading fields: "event"
      // makes the model WRITE OUT the real event and its real-world date, so
      // the "timing" enum right after it compares two dates sitting on the
      // page instead of inferring silently inside one token. Probed 24/24 on
      // Haiku and Sonnet where a bare timing enum failed 0/12 — date retrieval
      // must be a generation step, not an implication. The CAP is still
      // enforced in code below (legend-is-law, like the band clamp).
      const timingFields = args.momentRefined
          ? {
              event: {
                  type: 'string',
                  description: 'The real recorded historical event this dispatch is trying to influence, and the exact real-world date it occurred (e.g. "the Hindenburg disaster at Lakehurst — May 6, 1937")'
              },
              timing: {
                  type: 'string',
                  enum: ['in-time', 'too-late'],
                  description: '"too-late" if the event\'s real date above is earlier than the stated moment the dispatch arrives — its chance already spent; otherwise "in-time"'
              }
          }
          : {}
      // Continuity is read only when there's a thread to build on. On turn 1 (no
      // prior reply, empty ledger) the prompt + schema stay byte-identical to the
      // pre-feature build and continuity defaults to 'neutral' — momentum can't
      // build out of nothing anyway.
      const hasThread = !!(args.lastFigureReply || args.ledgerDigest?.length)
      const continuityField = hasThread
          ? {
              continuity: {
                  type: 'string',
                  enum: [...CONTINUITY_LEVELS],
                  description: '"builds" if this dispatch meets a condition/price the figure just revealed, deliberately exploits a change already on the record, or coheres with and escalates the run\'s strategy; "resets" if it abandons that thread and starts cold; "neutral" otherwise'
              }
          }
          : {}
      const content = await completeStructured({
          task: 'judge',
          system: buildJudgePrompt(args),
          schemaName: 'craft_verdict',
          schema: {
              type: 'object',
              properties: {
                  ...timingFields,
                  craft: { type: 'string', enum: [...CRAFT_LEVELS], description: 'The dispatch’s craft grade' },
                  ...continuityField,
                  reason: { type: 'string', description: 'One terse player-facing sentence, under 90 characters' }
              },
              required: [...(args.momentRefined ? ['event', 'timing'] : []), 'craft', ...(hasThread ? ['continuity'] : []), 'reason'],
              additionalProperties: false
          }
      })
362 
      if (!content) {
          return { success: false, error: 'Judge generated an empty response' }
      }
366 
      const parsed = JSON.parse(content) as { timing?: unknown; craft?: unknown; continuity?: unknown; reason?: unknown }
      let craft = toCraft(parsed.craft)
      // The closed-door cap, in code: a too-late pin grades vague at best.
      if (args.momentRefined && parsed.timing === 'too-late' && CRAFT_MODIFIER[craft] > CRAFT_MODIFIER.vague) {
          craft = 'vague'
      }
      return {
          success: true,
          judge: {
              craft,
              continuity: toContinuity(parsed.continuity),
              reason: typeof parsed.reason === 'string' ? parsed.reason.trim().slice(0, 120) : ''
          }
      }
  } catch (error) {
      console.error('Judge AI error:', error)
      return { success: false, error: 'Judge could not assess the dispatch' }
  }
385}
386 
387/**
* The Archivist (prototype) — a grounded, OBJECTIVE-BLIND brief on a real figure at
* a chosen point in their life: who they are, what they grasp, what they're reaching
* for, and what lies beyond their era. In-game research so the player needn't break
* out to a search engine — it enriches the world, never makes their move.
*/
393export interface ArchivistAIResponse {
  success: boolean
  study?: FigureStudy
  error?: string
  /** Claude's own safety classifier declined the study — surfaced as a moderation
   *  block (the study-blocked banner), not an infra failure. */
  refused?: boolean
400}
401 
402export async function callArchivistAI(args: {
  figureName: string
  when?: string
  description?: string
  extract?: string
407}): Promise<ArchivistAIResponse> {
  try {
      const content = await completeStructured({
          task: 'archivist-study',
          system: buildResearchPrompt(args),
          schemaName: 'figure_study',
          schema: {
              type: 'object',
              properties: {
                  atThisMoment: { type: 'string', description: 'Where the figure stands in life and work at the chosen moment' },
                  grasp: { type: 'array', items: { type: 'string' }, description: '2-4 things they genuinely understand' },
                  reaching: { type: 'array', items: { type: 'string' }, description: '2-4 things they pursue or are stuck on' },
                  cannotYetKnow: { type: 'string', description: 'One sentence on what lies beyond their era' }
              },
              required: ['atThisMoment', 'grasp', 'reaching', 'cannotYetKnow'],
              additionalProperties: false
          }
      })
425 
      if (!content) {
          return { success: false, error: 'Archivist generated an empty response' }
      }
429 
      const parsed = JSON.parse(content) as { atThisMoment?: unknown; grasp?: unknown; reaching?: unknown; cannotYetKnow?: unknown }
      const asStrings = (v: unknown): string[] =>
          Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string' && s.trim().length > 0) : []
      const grasp = asStrings(parsed.grasp)
      const reaching = asStrings(parsed.reaching)
      if (typeof parsed.atThisMoment !== 'string' || !parsed.atThisMoment.trim() || (!grasp.length && !reaching.length)) {
          return { success: false, error: 'Archivist response missing required fields' }
      }
438 
      return {
          success: true,
          study: {
              atThisMoment: parsed.atThisMoment.trim(),
              grasp,
              reaching,
              cannotYetKnow: typeof parsed.cannotYetKnow === 'string' ? parsed.cannotYetKnow.trim() : ''
          }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This study was declined by content moderation.' }
      }
      console.error('Archivist AI error:', error)
      return { success: false, error: 'Archivist could not process the request' }
  }
455}
456 
457/**
* The Archive lookup (prototype, "yellow") — a concise, factual answer to a freeform
* topic query, stamped with when the knowledge first emerged so the player can read
* its anachronism. Pure domain facts (what/ingredients/when), never strategy.
*/
462export interface ArchiveLookupResponse {
  success: boolean
  lookup?: ArchiveLookup
  error?: string
  /** Claude's own safety classifier declined the lookup — surfaced as a moderation
   *  block (the lookup-blocked banner), not an infra failure. */
  refused?: boolean
469}
470 
471export async function callArchiveLookupAI(query: string): Promise<ArchiveLookupResponse> {
  try {
      const content = await completeStructured({
          task: 'archive-lookup',
          system: buildLookupPrompt(query),
          schemaName: 'archive_lookup',
          schema: {
              type: 'object',
              properties: {
                  topic: { type: 'string', description: 'Short title for what was asked' },
                  summary: { type: 'string', description: 'One or two plain sentences — the essential fact' },
                  requires: { type: 'array', items: { type: 'string' }, description: 'Concrete ingredients / prerequisites, or empty' },
                  knownSince: { type: 'string', description: 'When/where this knowledge first emerged' }
              },
              required: ['topic', 'summary', 'requires', 'knownSince'],
              additionalProperties: false
          }
      })
489 
      if (!content) {
          return { success: false, error: 'Archive generated an empty response' }
      }
493 
      const parsed = JSON.parse(content) as { topic?: unknown; summary?: unknown; requires?: unknown; knownSince?: unknown }
      if (typeof parsed.topic !== 'string' || typeof parsed.summary !== 'string' || !parsed.summary.trim()) {
          return { success: false, error: 'Archive response missing required fields' }
      }
      const requires = Array.isArray(parsed.requires)
          ? parsed.requires.filter((s): s is string => typeof s === 'string' && s.trim().length > 0)
          : []
501 
      return {
          success: true,
          lookup: {
              topic: parsed.topic.trim() || query,
              summary: parsed.summary.trim(),
              requires,
              knownSince: typeof parsed.knownSince === 'string' ? parsed.knownSince.trim() : ''
          }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'That lookup was declined by content moderation.' }
      }
      console.error('Archive lookup error:', error)
      return { success: false, error: 'Archive could not process the request' }
  }
518}
519 
520/**
* Layer 3 — the Chronicler. Narrates the whole altered timeline as it now stands,
* rewritten each turn from the running ledger. It judges nothing, so a failure is
* non-fatal: the caller simply keeps the prior telling rather than blanking the panel.
*
* The FINAL telling (victory/defeat) is the run's epilogue — the share artifact —
* and routes as its own task so the flagship model can carry that one moment.
*/
528export async function callChroniclerAI(args: {
  objective: ObjectiveContext
  timeline: TimelineContextEntry[]
  status: ChronicleStatus
  progress: number
533}): Promise<ChronicleAIResponse> {
  try {
      const task = args.status === 'playing' ? 'chronicler' : 'epilogue'
      // Prompts are per-model artifacts: the Claude voice won its lane in
      // blind pairwise (see buildChroniclePromptClaude); the incumbent voice
      // stays exactly as-is for the OpenAI lane, so the fallback lever keeps
      // its tuned prompt too.
      const { lane } = routeFor(task)
      const content = await completeStructured({
          task,
          system: lane === 'anthropic' ? buildChroniclePromptClaude(args) : buildChroniclePrompt(args),
          schemaName: 'chronicle',
          schema: {
              type: 'object',
              properties: {
                  title: { type: 'string', description: 'Short, evocative title for this version of history (3-6 words)' },
                  paragraphs: {
                      type: 'array',
                      items: { type: 'string' },
                      description: '2-4 short paragraphs of prose, in reading order'
                  }
              },
              required: ['title', 'paragraphs'],
              additionalProperties: false
          }
      })
559 
      if (!content) {
          return { success: false, error: 'Chronicle AI generated an empty response' }
      }
563 
      const parsed = JSON.parse(content) as { title?: unknown; paragraphs?: unknown }
      const paragraphs = Array.isArray(parsed.paragraphs)
          ? parsed.paragraphs.filter((p): p is string => typeof p === 'string' && p.trim().length > 0)
          : []
      if (typeof parsed.title !== 'string' || !parsed.title.trim() || paragraphs.length === 0) {
          return { success: false, error: 'Chronicle AI response missing required fields' }
      }
571 
      return { success: true, chronicle: { title: parsed.title.trim(), paragraphs } }
  } catch (error) {
      console.error('Chronicle AI error:', error)
      return { success: false, error: 'Chronicle AI could not process the request' }
  }
577}

The trust boundary — the charge-economy blocker

The note's resource model is earned-in-play, server-minted charges with a hard cap of 2. That assumes the server can verify "this run earned a charge" and refuse a forged spend. It cannot today, because there is no server-authoritative per-turn run state. The handler reads momentum and the stake flag straight off the client body and only range-clamps them — the code says so itself.

staked = body.stake === true (no server-side canStake recheck); momentum from body.momentum, comment: "no server run-state today".

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

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

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

The corridor the retune must not break

The run economy is tuned to a neutral-band mean the bakeoff eval pins to [4, 9]. It measures baseProgressChange — the swing before the four multipliers — on a fixture that sets no craft grade (the neutral ×1.0 factor).

bandMeans use r.baseProgressChange (110); the NEUTRAL anchor (index 2) must stay in [4, 9] (122-123).

evals/bakeoff.eval.ts · 372 lines

evals/bakeoff.eval.ts372 lines · TypeScript

⋯ 105 lines hidden (lines 1–105)1/**
* The provider bake-off (GTM dispatch 1) — the same fixtures driven down BOTH
* lanes of the per-task routing seam, scored per layer:
*
*   Timeline  — band→swing ordering, the NEUTRAL-band EV corridor the run
*               economy is tuned around, valence↔sign, anachronism accuracy.
*   Judge     — calibration against the labeled craft ladders (ordinal
*               agreement + hard fairness violations), the Haiku gate.
*   Character — dice-band differential, 160-char discipline, era-blindness.
*   Chronicler— blind pairwise prose (position-debiased, dual-graded), plus a
*               ledger-consistency gate; the epilogue judged separately.
*   Cost      — real usage per lane from the gateway's telemetry observer.
*
* Run with: `npm run eval:bakeoff` (needs OPENAI_API_KEY + ANTHROPIC_API_KEY).
* Results land in evals/results/ as JSON alongside the printed scorecard.
* Lane passes are sequential; REVISIONIST_AI_LANE flips the whole seam per pass.
*/
18import { describe, it, afterAll } from 'vitest'
19import { mkdirSync, writeFileSync } from 'node:fs'
20import { resolve } from 'node:path'
21import { DiceOutcome } from '~/utils/dice'
22import { callCharacterAI, callTimelineAI, callChroniclerAI, callJudgeAI } from '~/server/utils/openai'
23import { setAiCallObserver, type AiCallTelemetry } from '~/server/utils/ai-gateway'
24import { CRAFT_MODIFIER } from '~/utils/craft'
25import { RUN, record, recordedRows, sample, gradeAll, prefer, mean, printScorecard } from './harness'
26import {
  ROLL_BY_BAND,
  TIMELINE_FIXED,
  ANACHRONISM_INPERIOD,
  ANACHRONISM_FUTURE,
  CHARACTER,
  OBJECTIVE
33} from './fixtures'
34import { JUDGE_LADDERS, EPILOGUE_LEDGER, CHRONICLE_CRITERIA } from './bakeoff-fixtures'
35 
36const LANES = ['anthropic', 'openai'] as const
37type Lane = (typeof LANES)[number]
38 
39/** Samples per cell — sized for a decision, not a census; paired across lanes. */
40const N_TIMELINE = 10
41const N_ANACHRONISM = 8
42const N_JUDGE = 2
43const N_CHARACTER = 8
44const K_CHRONICLE = 5
45 
46/** Anthropic list prices per MTok (verified 2026-06); OpenAI reported as tokens. */
47const ANTHROPIC_PRICES: Record<string, { input: number; output: number }> = {
  'claude-haiku-4-5': { input: 1, output: 5 },
  'claude-sonnet-4-6': { input: 3, output: 15 },
  'claude-opus-4-8': { input: 5, output: 25 }
51}
52 
53interface UsageCell { calls: number; input: number; output: number }
54const usageByLane: Record<Lane, Record<string, UsageCell>> = { anthropic: {}, openai: {} }
55let currentLane: Lane = 'anthropic'
56 
57function collect(t: AiCallTelemetry): void {
  if (!t.usage) return
  const key = `${t.task}:${t.model}`
  const cell = (usageByLane[currentLane][key] ??= { calls: 0, input: 0, output: 0 })
  cell.calls++
  cell.input += t.usage.inputTokens
  cell.output += t.usage.outputTokens
64}
65 
66function enterLane(lane: Lane): void {
  currentLane = lane
  process.env.REVISIONIST_AI_LANE = lane
  setAiCallObserver(collect)
70}
71 
72/** Everything the JSON snapshot carries, accumulated across the it-blocks. */
73const results: Record<string, unknown> = { lanes: {} }
74function laneResults(lane: Lane): Record<string, unknown> {
  const lanes = results.lanes as Record<string, Record<string, unknown>>
  return (lanes[lane] ??= {})
77}
78 
79const chronicles: Record<Lane, { mid: string[]; epilogue: string[] }> = {
  anthropic: { mid: [], epilogue: [] },
  openai: { mid: [], epilogue: [] }
82}
83 
84afterAll(() => {
  setAiCallObserver(null)
  delete process.env.REVISIONIST_AI_LANE
  printScorecard()
88})
89 
90function skip(layer: string, invariant: string): void {
  record({ layer, invariant, result: 'skipped (needs both keys)', status: 'skipped' })
92}
93 
94for (const lane of LANES) {
  describe(`${lane} lane`, () => {
      it('timeline: bands, corridor, anachronism', async () => {
          if (!RUN) {
              skip(`TL·${lane}`, 'band ordering / corridor / anachronism')
              return
          }
          enterLane(lane)
102 
          const bandMeans: number[] = []
          let vOK = 0
          let vTotal = 0
          for (const band of ROLL_BY_BAND) {
              const res = await sample(N_TIMELINE, () =>
                  callTimelineAI({ ...TIMELINE_FIXED, diceRoll: band.roll, diceOutcome: band.outcome }))
              const ripples = res.flatMap(r => (r.success && r.ripple ? [r.ripple] : []))
              bandMeans.push(Math.round(mean(ripples.map(r => r.baseProgressChange)) * 10) / 10)
              for (const r of ripples) {
                  vTotal++
                  const s = r.progressChange
                  if ((r.valence === 'positive' && s > 0) || (r.valence === 'negative' && s < 0) || (r.valence === 'neutral' && Math.abs(s) <= 3)) vOK++
              }
          }
          let ordered = 0
          for (let i = 1; i < bandMeans.length; i++) if (bandMeans[i] >= bandMeans[i - 1]) ordered++
          // The run economy is tuned around ~+6/turn for sound unaided play —
          // the NEUTRAL band (0..+12) is the anchor; a lane whose neutral mean
          // drifts out of [4, 9] silently rebalances the whole game.
          const neutralMean = bandMeans[2]
          const corridorOK = neutralMean >= 4 && neutralMean <= 9
⋯ 249 lines hidden (lines 124–372)124 
          const inP = await sample(N_ANACHRONISM, () =>
              callTimelineAI({ ...ANACHRONISM_INPERIOD, diceRoll: 12, diceOutcome: DiceOutcome.NEUTRAL }))
          const fut = await sample(N_ANACHRONISM, () =>
              callTimelineAI({ ...ANACHRONISM_FUTURE, diceRoll: 12, diceOutcome: DiceOutcome.NEUTRAL }))
          const inLevels = inP.flatMap(r => (r.success && r.ripple ? [r.ripple.anachronism] : []))
          const futLevels = fut.flatMap(r => (r.success && r.ripple ? [r.ripple.anachronism] : []))
          const inOK = inLevels.filter(a => a === 'in-period' || a === 'ahead').length
          const futOK = futLevels.filter(a => a === 'far-ahead' || a === 'impossible').length
133 
          laneResults(lane).timeline = {
              bandMeans, ordered, neutralMean, corridorOK,
              valence: { ok: vOK, total: vTotal },
              anachronism: { inOK, inTotal: inLevels.length, futOK, futTotal: futLevels.length }
          }
          record({
              layer: `TL·${lane}`,
              invariant: 'band means + ordering',
              result: vTotal === 0 ? 'no samples' : `[${bandMeans.join(', ')}] · ${ordered}/4 ordered`,
              status: vTotal === 0 ? 'error' : ordered >= 4 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `TL·${lane}`,
              invariant: 'neutral EV corridor [4..9]',
              result: `mean ${neutralMean}`,
              status: vTotal === 0 ? 'error' : corridorOK ? 'ok' : 'soft-miss'
          })
          record({
              layer: `TL·${lane}`,
              invariant: 'valence↔sign',
              result: `${vOK}/${vTotal}`,
              status: vTotal > 0 && vOK / vTotal >= 0.9 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `TL·${lane}`,
              invariant: 'anachronism accuracy',
              result: `in-period ${inOK}/${inLevels.length} · future ${futOK}/${futLevels.length}`,
              status: inLevels.length + futLevels.length > 0 && (inOK + futOK) / (inLevels.length + futLevels.length) >= 0.75 ? 'ok' : 'soft-miss'
          })
      })
164 
      it('judge: calibration ladders', async () => {
          if (!RUN) {
              skip(`JD·${lane}`, 'ladder calibration')
              return
          }
          enterLane(lane)
171 
          let orderedPairs = 0
          let totalPairs = 0
          let hardViolations = 0
          const ladderMeans: number[][] = []
          for (const ladder of JUDGE_LADDERS) {
              const rungMeans: number[] = []
              for (const dispatch of ladder.rungs) {
                  const res = await sample(N_JUDGE, () =>
                      callJudgeAI({ objective: ladder.objective, figureName: ladder.figureName, when: ladder.when, userMessage: dispatch }))
                  const mods = res.flatMap(r => (r.success && r.judge ? [CRAFT_MODIFIER[r.judge.craft]] : []))
                  rungMeans.push(mean(mods))
                  // Fairness floor: the bottom two rungs must never read masterful
                  // (+2), the top rung must never read reckless (-2).
                  const rungIndex = ladder.rungs.indexOf(dispatch)
                  if (rungIndex >= 2 && mods.some(m => m >= 2)) hardViolations++
                  if (rungIndex === 0 && mods.some(m => m <= -2)) hardViolations++
              }
              ladderMeans.push(rungMeans)
              for (let i = 0; i < rungMeans.length; i++) {
                  for (let j = i + 1; j < rungMeans.length; j++) {
                      totalPairs++
                      if (rungMeans[i] >= rungMeans[j]) orderedPairs++
                  }
              }
          }
197 
          laneResults(lane).judge = { ladderMeans, orderedPairs, totalPairs, hardViolations }
          record({
              layer: `JD·${lane}`,
              invariant: 'ladder ordinal agreement',
              result: `${orderedPairs}/${totalPairs} pairs ordered`,
              status: totalPairs > 0 && orderedPairs / totalPairs >= 0.9 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `JD·${lane}`,
              invariant: 'hard violations',
              result: `${hardViolations}`,
              status: hardViolations === 0 ? 'ok' : 'soft-miss'
          })
      })
212 
      it('character: differential, discipline, era-blindness', async () => {
          if (!RUN) {
              skip(`CH·${lane}`, 'differential / 160 / era')
              return
          }
          enterLane(lane)
219 
          const succ = await sample(N_CHARACTER, () =>
              callCharacterAI(CHARACTER.figureName, CHARACTER.nudgeMessage, [], DiceOutcome.CRITICAL_SUCCESS, CHARACTER.grounding))
          const fail = await sample(N_CHARACTER, () =>
              callCharacterAI(CHARACTER.figureName, CHARACTER.nudgeMessage, [], DiceOutcome.CRITICAL_FAILURE, CHARACTER.grounding))
          const succR = succ.flatMap(r => (r.success && r.characterResponse ? [r.characterResponse] : []))
          const failR = fail.flatMap(r => (r.success && r.characterResponse ? [r.characterResponse] : []))
226 
          const q = `Does the figure decisively and favorably act toward this goal — "${CHARACTER.nudgeGoal}"? Answer yes only if they clearly move to do it.`
          const sG = await gradeAll(q, succR.map(a => a.action))
          const fG = await gradeAll(q, failR.map(a => a.action))
          const sRate = sG.graded ? sG.yes / sG.graded : 0
          const fRate = fG.graded ? fG.yes / fG.graded : 0
232 
          const all = [...succR, ...failR]
          const within = all.filter(a => a.message.length <= 160).length
235 
          const future = await sample(N_CHARACTER, () =>
              callCharacterAI(CHARACTER.figureName, CHARACTER.futureMessage, [], DiceOutcome.NEUTRAL, CHARACTER.grounding))
          const futureReplies = future.flatMap(r => (r.success && r.characterResponse ? [r.characterResponse.message] : []))
          const eraQ = 'Does this reply treat events beyond the speaker’s own lifetime as established fact, or acknowledge knowing the future / being in a game? Answer yes if it breaks the historical illusion.'
          const eraG = await gradeAll(eraQ, futureReplies)
241 
          laneResults(lane).character = {
              actToward: { success: sG, fail: fG },
              len160: { within, total: all.length },
              eraBreaks: eraG
          }
          record({
              layer: `CH·${lane}`,
              invariant: 'band→reaction differential',
              result: `crit-succ ${sG.yes}/${sG.graded} · crit-fail ${fG.yes}/${fG.graded} (${sG.contested + fG.contested} contested)`,
              status: sG.graded && fG.graded ? (sRate > fRate ? 'ok' : 'soft-miss') : 'error'
          })
          record({
              layer: `CH·${lane}`,
              invariant: 'reply ≤160 chars',
              result: `${within}/${all.length}`,
              status: all.length > 0 && within / all.length >= 0.8 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `CH·${lane}`,
              invariant: 'no future-as-fact',
              result: `${eraG.graded - eraG.yes}/${eraG.graded} stay in-era (${eraG.contested} contested)`,
              status: eraG.graded > 0 && eraG.yes / eraG.graded <= 0.25 ? 'ok' : 'soft-miss'
          })
      })
266 
      it('chronicler: generate tellings (judged cross-lane later)', async () => {
          if (!RUN) {
              skip(`CR·${lane}`, 'tellings generated')
              return
          }
          enterLane(lane)
273 
          const mid = await sample(K_CHRONICLE, () =>
              callChroniclerAI({ objective: OBJECTIVE, timeline: EPILOGUE_LEDGER.slice(0, 3), status: 'playing', progress: 55 }))
          const epi = await sample(K_CHRONICLE, () =>
              callChroniclerAI({ objective: OBJECTIVE, timeline: EPILOGUE_LEDGER, status: 'victory', progress: 100 }))
          chronicles[lane].mid = mid.flatMap(r => (r.success && r.chronicle ? [`${r.chronicle.title}\n${r.chronicle.paragraphs.join('\n')}`] : []))
          chronicles[lane].epilogue = epi.flatMap(r => (r.success && r.chronicle ? [`${r.chronicle.title}\n${r.chronicle.paragraphs.join('\n')}`] : []))
280 
          const facts = 'These facts are TRUE: (1) Caesar spared the library from fire; (2) Cleopatra endowed it; (3) Octavian later spared Alexandria and endowed the Museion. Does the narrative CONTRADICT any of these (e.g. the library burns or is lost)? Answer yes if it contradicts.'
          const g = await gradeAll(facts, [...chronicles[lane].mid, ...chronicles[lane].epilogue])
283 
          laneResults(lane).chronicler = { consistency: g, midCount: chronicles[lane].mid.length, epilogueCount: chronicles[lane].epilogue.length }
          record({
              layer: `CR·${lane}`,
              invariant: 'ledger consistency',
              result: `${g.graded - g.yes}/${g.graded} consistent (${g.contested} contested)`,
              status: g.graded > 0 && g.yes / g.graded <= 0.25 ? 'ok' : 'soft-miss'
          })
      })
  })
293}
294 
295describe('cross-lane', () => {
  it('chronicle pairwise + cost + snapshot', async () => {
      if (!RUN) {
          skip('XL', 'pairwise / cost / snapshot')
          return
      }
      setAiCallObserver(null)
302 
      // Blind pairwise: pair lane outputs by index, both kinds. Votes are
      // position-debiased and dual-graded inside prefer().
      async function pairwise(kind: 'mid' | 'epilogue'): Promise<{ anthropic: number; openai: number }> {
          const a = chronicles.anthropic[kind]
          const o = chronicles.openai[kind]
          const pairs = Math.min(a.length, o.length)
          let aVotes = 0
          let oVotes = 0
          for (let i = 0; i < pairs; i++) {
              const v = await prefer(CHRONICLE_CRITERIA, a[i], o[i])
              aVotes += v.a
              oVotes += v.b
          }
          return { anthropic: aVotes, openai: oVotes }
      }
318 
      const midVotes = await pairwise('mid')
      const epiVotes = await pairwise('epilogue')
      results.pairwise = { mid: midVotes, epilogue: epiVotes }
      record({
          layer: 'XL',
          invariant: 'chronicle pairwise (mid-run)',
          result: `anthropic ${midVotes.anthropic} · openai ${midVotes.openai}`,
          status: 'ok'
      })
      record({
          layer: 'XL',
          invariant: 'epilogue pairwise',
          result: `anthropic ${epiVotes.anthropic} · openai ${epiVotes.openai}`,
          status: 'ok'
      })
334 
      // Cost from real usage. Anthropic priced from the verified list; the
      // OpenAI lane is reported in raw tokens (its prices live outside the repo).
      for (const lane of LANES) {
          const cells = usageByLane[lane]
          let dollars = 0
          let input = 0
          let output = 0
          let calls = 0
          for (const [key, cell] of Object.entries(cells)) {
              input += cell.input
              output += cell.output
              calls += cell.calls
              const model = key.split(':')[1]
              const price = ANTHROPIC_PRICES[model]
              if (price) dollars += (cell.input * price.input + cell.output * price.output) / 1_000_000
          }
          laneResults(lane).usage = { calls, input, output, dollars: lane === 'anthropic' ? Math.round(dollars * 10000) / 10000 : null, byTask: cells }
          record({
              layer: 'COST',
              invariant: `${lane} battery usage`,
              result: `${calls} calls · ${input} in · ${output} out${lane === 'anthropic' ? ` · $${dollars.toFixed(4)}` : ''}`,
              status: 'ok'
          })
      }
359 
      results.rows = recordedRows()
      results.meta = {
          date: new Date().toISOString(),
          samples: { N_TIMELINE, N_ANACHRONISM, N_JUDGE, N_CHARACTER, K_CHRONICLE },
          graders: 'dual (gpt-5.4 + claude-sonnet-4-6), agreement-gated, position-debiased pairwise'
      }
      const dir = resolve(process.cwd(), 'evals/results')
      mkdirSync(dir, { recursive: true })
      const file = resolve(dir, `bakeoff-${new Date().toISOString().slice(0, 10)}.json`)
      writeFileSync(file, JSON.stringify(results, null, 2))
      process.stdout.write(`\nbake-off snapshot → ${file}\n`)
  })
372})

Because the corridor measures the pre-multiplier base at craft-neutral, an annotation that fires only at sharp/masterful or only on the gains side is a literal no-op there — the anchor cannot move. That is also why the corridor alone proves nothing about the armed regime, so the note makes an armed-masterful re-test (run the bakeoff at masterful with each annotation armed) a required CI gate. It is the same realized-EV eval the settings note (#90) already calls for; build it once.

Where a ⟐ badge would live

The game discloses its math, so a skill has to as well. The resolved-equation token list already renders ✒ craft, ⚡ anachronism, ⏳ chain, ✦ momentum, and ⚑ stake from server-echoed values, each with a hover hint from a shared constant so the copy and the number can't drift. A new ⟐ annotation token slots in here.

equationTokens(): the badge glyphs ✒ ⚡ ⏳ ✦ ⚑ a ⟐ annotation badge would join, plus the disclosed pre-send chip pattern.

components/MessageHistory.vue · 213 lines

components/MessageHistory.vue213 lines · Vue

⋯ 153 lines hidden (lines 1–153)1<template>
2  <!-- Conversation with the currently-selected figure (the THREAD rail). -->
3  <div data-testid="message-history"
4    class="message-history-container overflow-y-auto rv-bg max-h-[340px] md:max-h-none md:overflow-visible"
5    aria-label="Conversation history" aria-live="polite" role="log">
6    <!-- Empty state -->
7    <div v-if="thread.length === 0 && !gameStore.isLoading" data-testid="empty-state"
8      class="flex flex-col items-center justify-center p-8 text-center">
9      <div class="text-3xl mb-2 opacity-50" aria-hidden="true">💬</div>
10      <p class="rv-muted text-sm">
11        {{ activeFigure ? `No words exchanged with ${activeFigure} yet` : 'No one contacted yet' }}
12      </p>
13      <p class="rv-faint text-xs mt-0.5">
14        {{ activeFigure ? 'Send a message to begin.' : 'Choose a figure and send your first message.' }}
15      </p>
16    </div>
17 
18    <!-- Conversation -->
19    <ol v-else>
20      <li v-for="(message, index) in thread" :key="index" data-testid="message-item" :data-sender="message.sender"
21        class="message-item py-3 border-b rv-line last:border-b-0">
22        <!-- Player message -->
23        <div v-if="message.sender === 'user'" data-testid="user-message">
24          <p class="text-[11px] rv-faint uppercase tracking-wide mb-0.5">You → {{ message.figureName || activeFigure }}</p>
25          <p class="rv-fg text-sm">{{ message.text }}</p>
26          <p class="text-[11px] rv-faint mt-1 rv-mono" data-testid="message-timestamp">{{ formatTimestamp(message.timestamp) }}</p>
27        </div>
28 
29        <!-- Figure reply -->
30        <div v-else-if="message.sender === 'ai'" data-testid="ai-message">
31          <div class="flex items-center justify-between gap-2 mb-1">
32            <p class="text-sm font-semibold rv-fg flex items-center gap-1.5 min-w-0">
33              <span class="rv-dot" :class="outcomeDot(message.diceOutcome)" aria-hidden="true" />
34              <span class="truncate">{{ message.figureName || activeFigure || 'The past' }}</span>
35            </p>
36            <div v-if="message.diceRoll !== undefined" class="flex items-center gap-1.5 rv-mono text-xs shrink-0">
37              <span data-testid="dice-icon" aria-hidden="true">🎲</span>
38              <!-- Craft tilts fate visibly: natural roll ✒mod = effective. -->
39              <span v-if="message.rollModifier" data-testid="craft-roll" class="rv-faint">
40                {{ message.naturalRoll }} <span :class="message.rollModifier > 0 ? 'rv-ok' : 'rv-bad'">✒{{ message.rollModifier > 0 ? '+' : '' }}{{ message.rollModifier }}</span> =
41              </span>
42              <span data-testid="dice-result" class="font-bold rv-fg">{{ message.diceRoll }}</span>
43              <span data-testid="dice-outcome" class="font-semibold" :class="outcomeText(message.diceOutcome)">{{ message.diceOutcome }}</span>
44            </div>
45          </div>
46 
47          <!-- The Judge's verdict on the dispatch that caused all this: the craft
48               grade (with a hover hint), a 'builds' mark when it picked up the run's
49               thread (the momentum signal), and the terse reason. -->
50          <div v-if="message.craft && (message.craft !== 'sound' || message.craftReason || message.continuity === 'builds')" data-testid="craft-verdict" class="text-[11px] mb-1.5">
51            <span class="rv-faint">✒ your dispatch · </span><SymbolHint :text="CRAFT_HINT[message.craft]"><span class="font-semibold" :class="craftClass(message.craft)">{{ CRAFT_LABEL[message.craft] }}</span></SymbolHint><span v-if="message.continuity === 'builds'" data-testid="continuity-builds" class="rv-ok font-semibold"> · ✦ builds</span><span v-if="message.craftReason" class="rv-faint"> — {{ message.craftReason }}</span>
52          </div>
53 
54          <p data-testid="character-message" class="rv-fg text-sm mb-2">{{ message.text }}</p>
55 
56          <div v-if="message.characterAction" data-testid="character-action" class="text-xs rv-muted border-l rv-line pl-2 mb-2">
57            <span class="rv-faint">acts · </span><span class="italic">{{ message.characterAction }}</span>
58          </div>
59 
60          <div v-if="message.timelineImpact" data-testid="timeline-impact" class="text-xs rv-muted border-l rv-line pl-2 mb-1">
61            <span class="rv-faint">ripple · </span>{{ message.timelineImpact }}
62            <span v-if="message.progressChange !== undefined" data-testid="progress-change"
63              class="rv-mono font-bold ml-1" :class="deltaText(message.progressChange)">
64              {{ message.progressChange > 0 ? '+' : '' }}{{ message.progressChange }}%
65            </span>
66            <!-- The wager's work, shown as an equation: base ⚡tier (⚑ staked) → final.
67                 Each amplifier token carries its own hover hint for what it did. -->
68            <span v-if="showEquation(message)" data-testid="swing-equation" class="rv-mono rv-faint ml-1 whitespace-nowrap">({{ signed(message.baseProgressChange!) }}<template v-for="tok in equationTokens(message)" :key="tok.kind">{{ ' ' }}<SymbolHint :text="tok.hint"><span :data-testid="`equation-${tok.kind}`">{{ tok.label }}</span></SymbolHint></template>{{ ' → ' + signed(message.progressChange!) + '%' }})</span>
69          </div>
70 
71          <p class="text-[11px] rv-faint rv-mono" data-testid="message-timestamp">{{ formatTimestamp(message.timestamp) }}</p>
72        </div>
73      </li>
74 
75      <!-- Loading indicator -->
76      <li v-if="gameStore.isLoading" data-testid="loading-indicator" class="py-3 flex items-center gap-2 rv-muted text-sm">
77        <span class="rv-spinner" aria-hidden="true" />
78        {{ activeFigure || 'The past' }} is weighing your words…
79      </li>
80    </ol>
81  </div>
82</template>
83 
84<script setup lang="ts">
85/**
86 * MessageHistory — the conversation thread with the active figure, as hairline rows
87 * led by an outcome dot. Figure-aware labels; each figure keeps an independent thread.
88 */
89import { computed } from 'vue'
90import { useGameStore, type Message } from '~/stores/game'
91import { ANACHRONISM_HINT, ANACHRONISM_LABEL } from '~/server/utils/anachronism'
92import { CHAIN_HINT, CHAIN_LABEL } from '~/utils/causal-chain'
93import { CRAFT_HINT, CRAFT_LABEL, type Craft } from '~/utils/craft'
94import { STAKE_HINT } from '~/utils/swing-bands'
95 
96const gameStore = useGameStore()
97 
98const activeFigure = computed(() => gameStore.activeFigureName)
99const thread = computed(() => gameStore.conversationWith(gameStore.activeFigureName))
100 
101const formatTimestamp = (timestamp: Date): string => {
102    return new Intl.DateTimeFormat('en-US', { hour: '2-digit', minute: '2-digit', second: '2-digit' }).format(timestamp)
103}
104 
105function outcomeDot(outcome?: string): string {
106    switch (outcome) {
107        case 'Critical Success':
108        case 'Success': return 'rv-dot--ok'
109        case 'Failure':
110        case 'Critical Failure': return 'rv-dot--bad'
111        default: return 'rv-dot--mut'
112    }
113}
114function outcomeText(outcome?: string): string {
115    switch (outcome) {
116        case 'Critical Success':
117        case 'Success': return 'rv-ok'
118        case 'Failure':
119        case 'Critical Failure': return 'rv-bad'
120        default: return 'rv-muted'
121    }
122}
123function deltaText(change?: number): string {
124    if (change === undefined || change === 0) return 'rv-muted'
125    return change > 0 ? 'rv-ok' : 'rv-bad'
126}
127 
128function craftClass(craft?: Craft): string {
129    switch (craft) {
130        case 'masterful':
131        case 'sharp': return 'rv-ok'
132        case 'vague':
133        case 'reckless': return 'rv-warn'
134        default: return 'rv-muted'
135    }
136}
137 
138// The swing equation appears only when something actually transformed the base
139// swing (wager amplification and/or the stake) — an in-period unstaked turn
140// keeps its single clean number.
141function showEquation(m: Message): boolean {
142    return m.baseProgressChange !== undefined
143        && m.progressChange !== undefined
144        && m.baseProgressChange !== m.progressChange
145}
146function signed(n: number): string {
147    return `${n > 0 ? '+' : ''}${n}`
148}
149 
150// The amplifier tokens between the base and final swing — anachronism, causal
151// chain, the stake — each rendered as a labeled glyph carrying its own hover
152// hint (what the token is and how it bent the swing). Mirrors the order the
153// server applies them; absent tokens drop out, matching the old flat string.
154interface EquationToken {
155    kind: 'anachronism' | 'chain' | 'craft' | 'momentum' | 'staked'
156    label: string
157    hint: string
158}
159function equationTokens(m: Message): EquationToken[] {
160    const tokens: EquationToken[] = []
161    if (m.anachronism && m.anachronism !== 'in-period') {
162        const pips = m.anachronism === 'impossible' ? '⚡⚡⚡' : m.anachronism === 'far-ahead' ? '⚡⚡' : '⚡'
163        tokens.push({ kind: 'anachronism', label: `${pips} ${ANACHRONISM_LABEL[m.anachronism].toLowerCase()}`, hint: ANACHRONISM_HINT[m.anachronism] })
164    }
165    if (m.causalChain && m.causalChain.tier !== 'at-hinge') {
166        tokens.push({ kind: 'chain', label: `⏳ ${CHAIN_LABEL[m.causalChain.tier].toLowerCase()}`, hint: CHAIN_HINT[m.causalChain.tier] })
167    }
168    // Craft scales the UPSIDE only, and only when it isn't the neutral 'sound' — so a
169    // sharp gain shows its lift and a vague one its drag, right in the math. This is
170    // where the player SEES craft drive the magnitude, not just tilt the die (#62).
171    if (m.progressChange !== undefined && m.progressChange > 0 && m.craft && m.craft !== 'sound') {
172        tokens.push({ kind: 'craft', label: `✒ ${CRAFT_LABEL[m.craft].toLowerCase()}`, hint: `a ${CRAFT_LABEL[m.craft].toLowerCase()} dispatch scales the gain it earned — craft, gains-only` })
173    }
174    // Momentum is the OTHER gains-only amplifier (the arc meter): show it whenever it
175    // lifted this turn, so the printed equation reconciles to the result (issue #62).
176    if (m.progressChange !== undefined && m.progressChange > 0 && m.momentumAtSwing && m.momentumAtSwing >= 1) {
177        tokens.push({ kind: 'momentum', label: `✦ momentum ${m.momentumAtSwing}`, hint: `momentum ${m.momentumAtSwing} of 4 — a coherent arc amplifies every gain` })
178    }
179    if (m.staked) tokens.push({ kind: 'staked', label: '⚑ staked', hint: STAKE_HINT })
180    return tokens
⋯ 33 lines hidden (lines 181–213)181}
182</script>
183 
184<style scoped>
185/* Phone keeps a fixed scroll box (the Story tab is one panel); the 340px cap and
186   md+ release live as utilities on the element (a scoped rule would out-specify the
187   Tailwind md: override). From md up the thread grows into the panel's own scroll. */
188.message-history-container {
189    min-height: 120px;
190}
191 
192/* Staged reveal: a resolved turn writes itself in — the figure speaks, then acts,
193   then the ripple through history lands. Elements stay in the DOM (opacity only). */
194[data-testid="character-message"],
195[data-testid="character-action"],
196[data-testid="timeline-impact"] {
197    animation: reveal-up 0.45s var(--rv-ease) both;
198}
199[data-testid="character-message"] { animation-delay: 0.08s; }
200[data-testid="character-action"] { animation-delay: 0.30s; }
201[data-testid="timeline-impact"] { animation-delay: 0.55s; }
202 
203@keyframes reveal-up {
204    from { opacity: 0; transform: translateY(8px); }
205    to { opacity: 1; transform: none; }
206}
207 
208@media (prefers-reduced-motion: reduce) {
209    [data-testid="character-message"],
210    [data-testid="character-action"],
211    [data-testid="timeline-impact"] { animation: none; }
212}
213</style>

What the note spawns

The exploration enumerates two implementation issues, ready to file, in dependency order — and the adversarial balance break-test cut one proposed skill before it could ship.

Outcome	Detail
Issue 1 (foundation)	Server-authoritative per-turn run state + close the stake/momentum trust gaps.
Issue 2 (depends on 1)	“The Editor's Hand”: the per-run annotation draft, the earned-in-play charge ledger, server resolution at the verified hooks, ANNOTATION_CAP, the ⟐ badge, and the armed-masterful corridor re-test.
Cut by the break-test	Press Correction (a chain-decay floor lift) — the only non-craft-gated skill; it rewarded the least-grounded play and inverted the causal-chain dial's intent.

No code beyond the doc. Classes, trees, inventory, reroll skills, and loss-softeners are all deferred.