Fix the craft verdict truncating mid-word (#126)

What changed, and why

The craft verdict is the Judge's one-line reason for a grade — the player's main cue for how to write a sharper message next turn. For longer reasons it was cut off mid-word: …lacks specifics on medi for "mediation". The tail is the actionable part, so losing it reads as a glitch.

The cause was a defensive slice(0, 120) on the reason field in callJudgeAI. That field is structured output, asked to stay "under 90 characters" — but the model overruns that soft hint, and the raw slice then severed whatever word it landed in.

The fix keeps a defensive cap and makes it cut cleanly. A small pure helper trims on a word boundary and marks the elision; the seam calls it in place of the slice. Blast radius is one call site plus a new util — the grade, the roll modifier, and the rest of the pipeline are untouched.

The word-safe trim

trimVerdictReason is a pure function. If the text fits the cap it returns unchanged. Otherwise it finds the last space at or before the cap, cuts there, and appends an ellipsis. One detail is worth a second look: it searches slice(0, cap + 1), so a space sitting exactly at the cap still counts as a boundary.

The cap, then the trim: boundary search, runaway fallback, punctuation strip.

utils/verdict.ts · 44 lines

utils/verdict.ts44 lines · TypeScript

⋯ 16 lines hidden (lines 1–16)1/**
* The craft verdict's one-line reason — the Judge's player-facing "why" for a
* grade (issue #126).
*
* The reason is structured output asked to stay "under 90 characters"
* (server/utils/openai.ts), but that's a SOFT hint the model regularly overruns,
* and providers don't enforce string length even in strict structured outputs. So
* we still cap defensively before the reason reaches the turn reveal — but cut on a
* word boundary, never mid-letter. The old hard `slice(0, 120)` severed words
* ("…lacks specifics on medi" for "mediation"), stripping exactly the actionable
* part of the player's main learning signal and reading as a glitch.
*
* Lives in utils/ as a pure transform, beside the rest of the verdict vocabulary
* (craft.ts, continuity.ts) the seam and the UI both read.
*/
16 
17/** Defensive cap on the verdict reason, in characters. Generous over the 90-char
*  prompt target so a typical overrun survives whole; the trim only bites the rare
*  runaway, and cuts it cleanly. */
20export const VERDICT_REASON_CAP = 160
21 
22/**
* Trim a verdict reason to `cap` characters without cutting a word in half. Returns
* the text unchanged when it fits; otherwise cuts at the last word boundary at or
* before the cap and marks the elision with an ellipsis. Falls back to a hard cut
* only for one unbroken token with no boundary to cut on.
*/
28export function trimVerdictReason(reason: string, cap: number = VERDICT_REASON_CAP): string {
  const text = reason.trim()
  if (text.length <= cap) return text
31 
  // Search the window up to and including the cap-th char, so a boundary sitting
  // exactly at the cap still counts.
  const window = text.slice(0, cap + 1)
  const lastSpace = window.lastIndexOf(' ')
36 
  // No word boundary at all — a single runaway token. A hard cut is the only move
  // left, but a marked one still beats a silent severed word.
  if (lastSpace <= 0) return text.slice(0, cap).trimEnd() + '…'
40 
  // Cut before the boundary word's trailing space, drop any dangling clause
  // punctuation, then mark the elision.
  return text.slice(0, lastSpace).replace(/[\s.,;:]+$/, '') + '…'
44}

One line at the judge seam

The only behavioral change at the seam is the reason line (379). The JSON parse, the craft coercion, and the closed-door timing rule just above it are unchanged. The string guard stays too: a non-string reason still falls back to the empty string.

The judge return — line 379 is the only call site changed.

server/utils/openai.ts · 578 lines

server/utils/openai.ts578 lines · TypeScript

⋯ 367 lines hidden (lines 1–367)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 { trimVerdictReason } from '~/utils/verdict'
33import type { DiceOutcome } from '~/utils/dice'
34import { BAND_CEILING, SWING_BANDS, VALENCE_SIGN_GUARD_MIN } from '~/utils/swing-bands'
35import { MAX_PROGRESS_SWING } from '~/utils/game-config'
36import { momentumFactor } from '~/utils/momentum'
37 
38/**
* What a figure returns each turn: an in-character reply and action, plus factual
* metadata (era, persona) the UI uses to label them.
*/
42export interface StructuredCharacterResponse {
  message: string
  action: string
  era: string
  persona: string
47}
48 
49export 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
56}
57 
58/**
* The Timeline Engine's verdict for a turn: how history bent.
*/
61export 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
75}
76 
77export interface TimelineAIResponse {
  success: boolean
  ripple?: TimelineRipple
  error?: string
  /** Model-side safety refusal — surfaced as a block, not an infra refund. */
  refused?: boolean
83}
84 
85/**
* 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.
*/
89export interface ChronicleEntry {
  title: string
  paragraphs: string[]
92}
93 
94export interface ChronicleAIResponse {
  success: boolean
  chronicle?: ChronicleEntry
  error?: string
98}
99 
100interface HistoryItem { text: string; sender: string }
101 
102/**
* 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.
*/
107function 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
      }))
114 
  const last = mapped[mapped.length - 1]
  if (!last || last.role !== 'user' || last.content !== currentUserMessage) {
      mapped.push({ role: 'user', content: currentUserMessage })
  }
  return mapped
120}
121 
122/**
* Layer 1 — role-plays the chosen figure (any name, any era), objective-blind,
* returning a structured reply + action + factual era/persona metadata.
*/
126export 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
136): 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
          }
      })
155 
      if (!content) {
          return { success: false, error: 'Character AI generated an empty response' }
      }
159 
      const parsed = JSON.parse(content) as StructuredCharacterResponse
      if (!parsed.message || !parsed.action) {
          return { success: false, error: 'Character AI response missing required fields' }
      }
164 
      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' }
  }
173}
174 
175/**
* Layer 2 — judges how the figure's action ripples through the already-altered
* world toward the live objective, returning a structured timeline ripple.
*/
179export 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
199}): 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
          }
      })
218 
      if (!content) {
          return { success: false, error: 'Timeline AI generated an empty response' }
      }
222 
      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' }
      }
227 
      // 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)))
      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
264 
      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' }
  }
276}
277 
278/**
* 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.
*/
285export 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
291}
292 
293export interface JudgeAIResponse {
  success: boolean
  judge?: JudgeVerdict
  error?: string
297}
298 
299export 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[]
311}): 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
          }
      })
363 
      if (!content) {
          return { success: false, error: 'Judge generated an empty response' }
      }
367 
      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' ? trimVerdictReason(parsed.reason) : ''
          }
      }
⋯ 197 lines hidden (lines 382–578)382    } catch (error) {
      console.error('Judge AI error:', error)
      return { success: false, error: 'Judge could not assess the dispatch' }
  }
386}
387 
388/**
* 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.
*/
394export 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
401}
402 
403export async function callArchivistAI(args: {
  figureName: string
  when?: string
  description?: string
  extract?: string
408}): 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
          }
      })
426 
      if (!content) {
          return { success: false, error: 'Archivist generated an empty response' }
      }
430 
      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' }
      }
439 
      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' }
  }
456}
457 
458/**
* 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.
*/
463export 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
470}
471 
472export 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
          }
      })
490 
      if (!content) {
          return { success: false, error: 'Archive generated an empty response' }
      }
494 
      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)
          : []
502 
      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' }
  }
519}
520 
521/**
* 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.
*/
529export async function callChroniclerAI(args: {
  objective: ObjectiveContext
  timeline: TimelineContextEntry[]
  status: ChronicleStatus
  progress: number
534}): 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
          }
      })
560 
      if (!content) {
          return { success: false, error: 'Chronicle AI generated an empty response' }
      }
564 
      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' }
      }
572 
      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' }
  }
578}

Tests pin the behavior

The util's behavior is fixed with small, readable cases: the exact-cap edge, a boundary landing on the cap, the punctuation strip, and the runaway-token fallback. Two cases speak to the bug directly.

Boundary + fallback cases, then the two that mirror the bug.

tests/unit/utils/verdict.spec.ts · 58 lines

tests/unit/utils/verdict.spec.ts58 lines · TypeScript

⋯ 16 lines hidden (lines 1–16)1import { describe, it, expect } from 'vitest'
2import { VERDICT_REASON_CAP, trimVerdictReason } from '../../../utils/verdict'
3 
4describe('verdict reason trim (issue #126)', () => {
  it('returns a reason that already fits, unchanged', () => {
      expect(trimVerdictReason('Names the lever and the moment.')).toBe('Names the lever and the moment.')
  })
8 
  it('trims surrounding whitespace', () => {
      expect(trimVerdictReason('  A clear, honest ask.  ')).toBe('A clear, honest ask.')
  })
12 
  it('keeps a reason exactly at the cap', () => {
      expect(trimVerdictReason('exactly10!', 10)).toBe('exactly10!')
  })
16 
  it('cuts on a word boundary and marks the elision — never mid-word', () => {
      expect(trimVerdictReason('hello world foo', 11)).toBe('hello world…')
  })
20 
  it('counts a boundary sitting exactly at the cap', () => {
      // The space lands at index 10 (== cap); the window reaches cap+1 so it counts.
      expect(trimVerdictReason('exactlyten yes', 10)).toBe('exactlyten…')
  })
25 
  it('drops dangling clause punctuation before the ellipsis', () => {
      expect(trimVerdictReason('alpha beta, gamma delta', 14)).toBe('alpha beta…')
  })
29 
  it('hard-cuts a single runaway token with no boundary, but still marks it', () => {
      expect(trimVerdictReason('supercalifragilistic', 10)).toBe('supercalif…')
  })
⋯ 10 lines hidden (lines 33–42)33 
  it('lets a typical overrun past the OLD 120-char cap survive whole (the bug)', () => {
      // 124 chars: the old slice(0, 120) severed this mid-word; the roomier cap
      // returns it intact, so the actionable tail is never lost.
      const reason = 'Names the lever and the moment, but it leans on Wilhelm restraint outweighing his alliance with Austria over the July plans.'
      expect(reason.length).toBeGreaterThan(120)
      expect(reason.length).toBeLessThanOrEqual(VERDICT_REASON_CAP)
      expect(trimVerdictReason(reason)).toBe(reason)
  })
42 
  it('cuts a genuinely overlong reason on a word boundary, keeping whole words', () => {
      const reason = 'Names the lever and the moment, but it leans hard on Wilhelm restraint outweighing his alliance with Austria-Hungary over the July mobilization timetables already locked in by the staff.'
      const out = trimVerdictReason(reason)
      expect(reason.length).toBeGreaterThan(VERDICT_REASON_CAP)
      expect(out.length).toBeLessThanOrEqual(VERDICT_REASON_CAP + 1) // + the ellipsis char
      expect(out.endsWith('…')).toBe(true)
      const body = out.slice(0, -1)
      expect(reason.startsWith(body)).toBe(true) // a clean prefix, nothing inserted
      expect(out).toContain('alliance') // the actionable word survives whole, not "…allia"
      expect(reason[body.length]).toMatch(/[\s.,;:]/) // cut fell on a boundary, not mid-word
  })
⋯ 5 lines hidden (lines 54–58)54 
  it('caps generously over the 90-char prompt target', () => {
      expect(VERDICT_REASON_CAP).toBe(160)
  })
58})

The 124-char case is the bug's exact shape: longer than the old 120 cap, within the new one, returned whole. The overlong case asserts the real invariant — the cut falls on a boundary in the original string, so no word is severed — and that the actionable word ("alliance") survives.

The same guarantee, driven end to end through callJudgeAI.

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

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

⋯ 237 lines hidden (lines 1–237)1import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from 'vitest'
2 
3/**
* The riskiest seam in the codebase, driven end to end with a mocked OpenAI SDK:
* model JSON → parse → base clamp → anachronism amplify (asymmetric + soft knee)
* → valence sign-guard. This is where roadmap slice 3 will bolt on its second
* multiplier — a silent break here only ever surfaced as "the game feels off".
*/
9const createMock = vi.hoisted(() => vi.fn())
10vi.mock('openai', () => ({
  // A real `function` (not an arrow): the SUT calls `new OpenAI(...)`, and
  // vitest only allows construction of function/class mock implementations.
  default: vi.fn(function () { return { chat: { completions: { create: createMock } } } })
14}))
15 
16import { callTimelineAI, callJudgeAI } from '../../../../server/utils/openai'
17import { DiceOutcome } from '../../../../utils/dice'
18 
19function modelReturns(payload: unknown) {
  createMock.mockResolvedValueOnce({ choices: [{ message: { content: JSON.stringify(payload) } }] })
21}
22 
23const TURN = {
  objective: { title: 'Spare the Library', description: 'The scrolls survive.' },
  figureName: 'Julius Caesar',
  era: 'Alexandria, 48 BC',
  userMessage: 'Guard the scrolls.',
  characterMessage: 'It is done.',
  characterAction: 'Caesar shields the library.',
  diceRoll: 16,
  diceOutcome: DiceOutcome.SUCCESS,
  timeline: []
33}
34 
35const ripple = (over: Record<string, unknown> = {}) => ({
  headline: 'The scrolls survive',
  detail: 'Rome guards wisdom.',
  progressChange: 20,
  valence: 'positive',
  anachronism: 'in-period',
  ...over
42})
43 
44beforeAll(() => {
  process.env.OPENAI_API_KEY = 'test-key'
  // This spec drives the LEGACY lane end to end — routing now defaults these
  // tasks to Anthropic, so pin the override (and prove the lever works).
  process.env.REVISIONIST_AI_LANE = 'openai'
49})
50 
51afterAll(() => {
  delete process.env.REVISIONIST_AI_LANE
53})
54 
55beforeEach(() => {
  createMock.mockReset()
57})
58 
59describe('callTimelineAI — band-clamp → amplify → valence pipeline', () => {
  it('passes an in-period swing through untouched, reporting base = final', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const res = await callTimelineAI(TURN)
      expect(res.success).toBe(true)
      expect(res.ripple?.progressChange).toBe(20)
      expect(res.ripple?.baseProgressChange).toBe(20)
  })
67 
  it('the band table is law: a model overshoot is clamped into the ROLLED band', async () => {
      // A Success (band +15..+30) cannot pay like a crit, whatever the model says.
      modelReturns(ripple({ progressChange: 80, anachronism: 'in-period' }))
      const res = await callTimelineAI(TURN)
      expect(res.ripple?.baseProgressChange).toBe(30)
      expect(res.ripple?.progressChange).toBe(30)
  })
75 
  it('…and clamps a wrong-signed swing back into the band too', async () => {
      // The roll said Success; the engine may not turn it into a setback.
      modelReturns(ripple({ progressChange: -20, anachronism: 'in-period', valence: 'negative' }))
      const res = await callTimelineAI(TURN)
      expect(res.ripple?.baseProgressChange).toBe(15) // Success band floor
      expect(res.ripple?.valence).toBe('positive') // sign-guard re-colors it
  })
83 
  it('amplifies gains gently and reports the pre-amplifier base', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'far-ahead' }))
      const res = await callTimelineAI(TURN)
      expect(res.ripple?.baseProgressChange).toBe(20)
      expect(res.ripple?.progressChange).toBe(27) // 20 × 1.35
  })
90 
  it('cuts losses harder than gains at the same tier', async () => {
      modelReturns(ripple({ progressChange: -12, anachronism: 'far-ahead', valence: 'negative' }))
      const res = await callTimelineAI({ ...TURN, diceRoll: 5, diceOutcome: DiceOutcome.FAILURE })
      expect(res.ripple?.baseProgressChange).toBe(-12)
      expect(res.ripple?.progressChange).toBe(-19) // 12 × 1.6 = 19.2 → -19
  })
97 
  it('soft-knees a big amplified swing into the cap instead of pinning past it', async () => {
      modelReturns(ripple({ progressChange: 40, anachronism: 'impossible' }))
      const res = await callTimelineAI({ ...TURN, diceRoll: 20, diceOutcome: DiceOutcome.CRITICAL_SUCCESS })
      // 40 × 1.6 = 64 → knee 40 + 12 = 52 → clamp 50
      expect(res.ripple?.progressChange).toBe(50)
      expect(res.ripple?.baseProgressChange).toBe(40)
  })
105 
  it('overrides a contradictory valence once the swing is beyond the neutral window', async () => {
      modelReturns(ripple({ progressChange: -12, anachronism: 'far-ahead', valence: 'positive' }))
      const res = await callTimelineAI({ ...TURN, diceRoll: 5, diceOutcome: DiceOutcome.FAILURE })
      expect(res.ripple?.progressChange).toBe(-19)
      expect(res.ripple?.valence).toBe('negative')
  })
112 
  it('keeps the model’s shading for small swings inside the ±3 window', async () => {
      modelReturns(ripple({ progressChange: 2, anachronism: 'in-period', valence: 'neutral' }))
      const res = await callTimelineAI({ ...TURN, diceRoll: 10, diceOutcome: DiceOutcome.NEUTRAL })
      expect(res.ripple?.valence).toBe('neutral')
  })
118 
  it('coerces a garbage anachronism level to the safe in-period', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'bananas' }))
      const res = await callTimelineAI(TURN)
      expect(res.ripple?.anachronism).toBe('in-period')
      expect(res.ripple?.progressChange).toBe(20)
  })
125 
  it('fails closed when required fields are missing', async () => {
      modelReturns({ detail: 'no headline', progressChange: 10 })
      const res = await callTimelineAI(TURN)
      expect(res.success).toBe(false)
  })
131})
132 
133describe('callTimelineAI — gains-only craft amplifier (issue #62)', () => {
  it('collapses a junk gain and amplifies a masterful one — same roll, same band', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const reckless = await callTimelineAI({ ...TURN, craft: 'reckless' })
      expect(reckless.ripple?.progressChange).toBe(3) // 20 × 0.15
138 
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const masterful = await callTimelineAI({ ...TURN, craft: 'masterful' })
      expect(masterful.ripple?.progressChange).toBe(29) // 20 × 1.45
142 
      // The pre-amplifier base swing is the band figure — craft never moves it.
      expect(reckless.ripple?.baseProgressChange).toBe(20)
      expect(masterful.ripple?.baseProgressChange).toBe(20)
  })
147 
  it('never scales the downside — a loss is identical across every craft grade', async () => {
      const losses: number[] = []
      for (const craft of ['masterful', 'sharp', 'sound', 'vague', 'reckless'] as const) {
          modelReturns(ripple({ progressChange: -10, anachronism: 'in-period', valence: 'negative' }))
          const res = await callTimelineAI({ ...TURN, diceRoll: 5, diceOutcome: DiceOutcome.FAILURE, craft })
          losses.push(res.ripple!.progressChange)
      }
      expect(new Set(losses)).toEqual(new Set([-10])) // craft buys reach, never immunity
  })
157 
  it('re-clamps the amplified gain to the per-turn fuse (±MAX_PROGRESS_SWING)', async () => {
      modelReturns(ripple({ progressChange: 45, anachronism: 'in-period' }))
      const res = await callTimelineAI({ ...TURN, diceRoll: 20, diceOutcome: DiceOutcome.CRITICAL_SUCCESS, craft: 'masterful' })
      // 45 × 1.45 = 65 → pinned to the 50 fuse, never past it.
      expect(res.ripple?.progressChange).toBe(50)
      expect(Math.abs(res.ripple!.progressChange)).toBeLessThanOrEqual(50)
  })
165 
  it('the craft EV ladder is monotonic on a fixed roll: masterful ≥ sharp ≥ sound ≥ vague ≥ reckless', async () => {
      const gains: number[] = []
      for (const craft of ['masterful', 'sharp', 'sound', 'vague', 'reckless'] as const) {
          modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
          const res = await callTimelineAI({ ...TURN, craft })
          gains.push(res.ripple!.progressChange)
      }
      expect(gains).toEqual([29, 24, 20, 8, 3])
      for (let i = 1; i < gains.length; i++) expect(gains[i]).toBeLessThanOrEqual(gains[i - 1])
  })
176 
  it('leaves the swing untouched when no craft is supplied (back-compat)', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const res = await callTimelineAI(TURN)
      expect(res.ripple?.progressChange).toBe(20)
  })
182 
  it('momentum amplifies the gain alongside craft, re-clamped to the fuse', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      const m4 = await callTimelineAI({ ...TURN, craft: 'sound', momentum: 4 })
      expect(m4.ripple?.progressChange).toBe(28) // 20 × 1.0 × 1.4
187 
      modelReturns(ripple({ progressChange: 45, anachronism: 'in-period' }))
      const big = await callTimelineAI({ ...TURN, diceRoll: 20, diceOutcome: DiceOutcome.CRITICAL_SUCCESS, craft: 'masterful', momentum: 4 })
      expect(big.ripple?.progressChange).toBe(50) // 45 × 1.45 × 1.4 = 91 → pinned to 50
  })
192 
  it('momentum never scales the downside (gains-only)', async () => {
      modelReturns(ripple({ progressChange: -10, anachronism: 'in-period', valence: 'negative' }))
      const res = await callTimelineAI({ ...TURN, diceRoll: 5, diceOutcome: DiceOutcome.FAILURE, momentum: 4 })
      expect(res.ripple?.progressChange).toBe(-10)
  })
198 
  it('is monotonic in momentum on a fixed roll', async () => {
      const gains: number[] = []
      for (const momentum of [0, 1, 2, 3, 4]) {
          modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
          const res = await callTimelineAI({ ...TURN, craft: 'sound', momentum })
          gains.push(res.ripple!.progressChange)
      }
      expect(gains).toEqual([20, 22, 24, 26, 28])
      for (let i = 1; i < gains.length; i++) expect(gains[i]).toBeGreaterThanOrEqual(gains[i - 1])
  })
209 
  it('composes causal decay with the craft amplifier — a far reach keeps only a sliver', async () => {
      modelReturns(ripple({ progressChange: 20, anachronism: 'in-period' }))
      // Figure in AD 1500, objective anchored at 48 BC → a ~1548-year unbridged gap,
      // so the swing is decayed toward the floor BEFORE the craft factor. Even
      // masterful craft can't undo the distance (rails, not walls).
      const res = await callTimelineAI({ ...TURN, craft: 'masterful', figureYear: 1500, objectiveAnchorYear: -48 })
      expect(res.ripple?.baseProgressChange).toBe(20)        // pre-amplifier, unchanged
      expect(res.ripple!.progressChange).toBeGreaterThan(0)  // a sliver survives the floor
      expect(res.ripple!.progressChange).toBeLessThan(8)     // far below the no-decay masterful 29
  })
220})
221 
222describe('callJudgeAI — the craft verdict seam', () => {
  const DISPATCH = {
      objective: { title: 'Spare the Library', description: 'The scrolls survive.' },
      figureName: 'Julius Caesar',
      when: '48 BC',
      userMessage: 'Guard the scrolls when the docks burn.'
  }
229 
  it('returns the parsed verdict', async () => {
      modelReturns({ craft: 'sharp', reason: 'Names the lever and the moment.' })
      const res = await callJudgeAI(DISPATCH)
      expect(res.success).toBe(true)
      expect(res.judge?.craft).toBe('sharp')
      expect(res.judge?.reason).toBe('Names the lever and the moment.')
  })
237 
  it('word-trims an overlong reason at the seam — never mid-word (issue #126)', async () => {
      // The "under 90 chars" prompt hint is soft and the model overruns it. The seam
      // caps defensively, but on a word boundary so the verdict never reads as a glitch.
      const reason = 'Names the lever and the moment, but it leans hard on Wilhelm restraint outweighing his alliance with Austria-Hungary over the July mobilization timetables already locked in by the staff.'
      modelReturns({ craft: 'sound', reason })
      const res = await callJudgeAI(DISPATCH)
      expect(res.judge!.reason.length).toBeLessThan(reason.length)
      expect(res.judge!.reason.endsWith('…')).toBe(true)
      expect(res.judge!.reason).toContain('alliance') // the actionable word kept whole
  })
⋯ 29 lines hidden (lines 248–276)248 
  it('coerces an off-menu grade to the neutral sound', async () => {
      modelReturns({ craft: 'legendary', reason: 'x' })
      const res = await callJudgeAI(DISPATCH)
      expect(res.judge?.craft).toBe('sound')
  })
254 
  it('fails closed (so the caller falls back to modifier 0) on an empty response', async () => {
      createMock.mockResolvedValueOnce({ choices: [{ message: { content: '' } }] })
      const res = await callJudgeAI(DISPATCH)
      expect(res.success).toBe(false)
  })
260 
  it('parses the continuity verdict when the run has a thread (issue #62)', async () => {
      modelReturns({ craft: 'sharp', continuity: 'builds', reason: 'Meets the price he named.' })
      const res = await callJudgeAI({ ...DISPATCH, lastFigureReply: 'Bring me grain and I will act.' })
      expect(res.judge?.continuity).toBe('builds')
  })
266 
  it('defaults continuity to neutral on turn 1 (no thread) and coerces garbage', async () => {
      modelReturns({ craft: 'sound', reason: 'A clear ask.' }) // threadless → continuity not asked
      const turn1 = await callJudgeAI(DISPATCH)
      expect(turn1.judge?.continuity).toBe('neutral')
271 
      modelReturns({ craft: 'sound', continuity: 'combo', reason: 'x' })
      const garbage = await callJudgeAI({ ...DISPATCH, ledgerDigest: ['[Rome] A change'] })
      expect(garbage.judge?.continuity).toBe('neutral')
  })
276})