Enforcing the paywall — a code-level reading

What changed, and why

The paywall #48 shipped was advisory: the browser respects the 402, but a direct caller could skip the commit and still hit the AI endpoints with a made-up run id. This makes it binding. The billable endpoints now refuse to spend model tokens unless the run id names a charged run owned by this request's device — so a forged, foreign, or unpaid run id draws no generation.

It's the highest-value of the "address the bypasses directly" fixes. An adversarial review of the first cut also caught a critical hole and two majors, all fixed here — see the notes below.

The check

One helper answers the question. runIsActive ties the run id (from the run-context middleware, i.e. the x-run-id header) to the device (from its cookie). The shape guard on line one is load-bearing: runs.id is a uuid column, so a non-UUID id is refused before the store call — otherwise it would make the query throw, and the fail-open below would hand a 7-character header free generation. Fail-open therefore covers only a genuine store error on a well-formed id (an in-progress run surviving a blip).

Shape-guard first (the bypass fix), then ask the store; fail open only on a real error.

server/utils/run-guard.ts · 33 lines

server/utils/run-guard.ts33 lines · TypeScript

⋯ 17 lines hidden (lines 1–17)1/**
* The paywall enforcement check for the gameplay AI path. send-message and the
* chronicle call this before spending tokens, so a forged or unpaid run id can't
* draw free generation: the run must be charged AND owned by this request's
* device (the run id comes from the run-context middleware, the device from its
* cookie).
*
* Fails OPEN on a store error — a balance-store outage must not block a legit
* in-progress run; the spend cap (a later vertebra) is the floor for that window.
* A missing run id, by contrast, is a hard no: there is nothing to verify.
*/
12import type { H3Event } from 'h3'
13import { deviceId } from '~/server/utils/device'
14import { currentRunId } from '~/server/utils/run-context'
15import { balanceStore } from '~/server/utils/balance-store'
16import { isUuid } from '~/server/utils/uuid'
17 
18export async function runIsActive(event: H3Event): Promise<boolean> {
  const runId = currentRunId()
  // A missing or non-UUID id can never name a real run — a hard no, and (since
  // runs.id is a uuid column) it must NEVER reach the store: a non-UUID would
  // make the Supabase query throw, and the fail-open below would then hand it
  // free generation. Validate the SHAPE before the call, so fail-open covers
  // only a genuine store error on a well-formed id.
  if (!runId || !isUuid(runId)) return false
  try {
      return await balanceStore().runActiveFor(deviceId(event), runId)
  } catch {
      // A well-formed id whose check errored = store unreachable; don't block a
      // legit in-progress run (a valid uuid can't be a cast error here).
      return true
  }
33}

"Active" means charged and device-owned. The in-memory adapter checks who charged the run; Supabase queries the runs row by id, device, and a non-null charged_at.

runActiveFor on both adapters — the charged-and-owned test.

server/utils/balance-store.ts · 136 lines

server/utils/balance-store.ts136 lines · TypeScript

⋯ 65 lines hidden (lines 1–65)1/**
* The run balance — the ledger that makes a run a thing you spend. A brand-new
* device gets FREE_RUNS for free (the doc's "first run free"); chargeRun spends
* one run when the player commits to an objective, once per run. Out of runs →
* the commit is refused (the paywall). Packs (Stripe) credit this balance later.
*
* Same two-adapter shape as the run store: in-memory by default (dev + tests need
* nothing), Supabase when configured. Keyed by an opaque device id (a server-set
* cookie) until accounts arrive, when a user id will supersede it.
*
* The Supabase charge goes through one SQL function (spend_run) so the
* ensure-grant, the idempotency check, and the decrement are atomic in a single
* round-trip — no read-modify-write race. The in-memory adapter mirrors that
* logic exactly.
*/
16import { createClient, type SupabaseClient } from '@supabase/supabase-js'
17import { supabaseConfig } from './supabase'
18 
19/** Runs granted to a brand-new device — the free trial ("first run free").
*  Mirrored by the spend_run SQL function; keep the two in sync. */
21export const FREE_RUNS = 1
22 
23export interface ChargeResult {
  /** False only when the device is out of runs (the paywall). */
  charged: boolean
  runsRemaining: number
27}
28 
29export interface BalanceStore {
  /** Ensure a balance row for the device, granting the free trial on first
   *  sight; returns the current runs remaining. */
  ensureDevice(deviceId: string): Promise<number>
  /** Spend one run for the device, once per runId (idempotent — re-committing
   *  the same run never double-charges). charged=false means out of runs. */
  chargeRun(deviceId: string, runId: string): Promise<ChargeResult>
  /** Runs remaining for the device (0 if unknown). */
  remaining(deviceId: string): Promise<number>
  /** Is this run charged AND owned by this device? The gameplay AI path checks
   *  this before spending tokens, so a forged or unpaid run id can't draw free
   *  generation. */
  runActiveFor(deviceId: string, runId: string): Promise<boolean>
42}
43 
44/** Dev default — process-local balances, durable enough for dev. Mirrors the
*  spend_run SQL function: free grant on first sight, one charge per run. */
46export class InMemoryBalanceStore implements BalanceStore {
  private readonly balances = new Map<string, number>()
  // runId → the device that charged it. Idempotency is per (device, run), so a
  // different device can't ride another's already-charged run for free.
  private readonly chargedRuns = new Map<string, string>()
51 
  async ensureDevice(deviceId: string): Promise<number> {
      if (!this.balances.has(deviceId)) this.balances.set(deviceId, FREE_RUNS)
      return this.balances.get(deviceId) ?? 0
  }
56 
  async chargeRun(deviceId: string, runId: string): Promise<ChargeResult> {
      const remaining = await this.ensureDevice(deviceId)
      if (this.chargedRuns.get(runId) === deviceId) return { charged: true, runsRemaining: remaining }
      if (remaining <= 0) return { charged: false, runsRemaining: 0 }
      this.balances.set(deviceId, remaining - 1)
      this.chargedRuns.set(runId, deviceId)
      return { charged: true, runsRemaining: remaining - 1 }
  }
65 
  async remaining(deviceId: string): Promise<number> {
      return this.balances.get(deviceId) ?? 0
  }
69 
  async runActiveFor(deviceId: string, runId: string): Promise<boolean> {
      return this.chargedRuns.get(runId) === deviceId
  }
73}
⋯ 33 lines hidden (lines 74–106)74 
75/** Service-key (RLS-bypassing) balance access; the table has no public policy. */
76export class SupabaseBalanceStore implements BalanceStore {
  constructor(private readonly client: SupabaseClient) {}
78 
  async ensureDevice(deviceId: string): Promise<number> {
      const { error } = await this.client
          .from('balances')
          .insert({ device_id: deviceId, runs_remaining: FREE_RUNS })
      // 23505 = unique_violation: the row already exists, which is fine.
      if (error && error.code !== '23505') throw new Error(`balance ensure failed: ${error.message}`)
      return this.remaining(deviceId)
  }
87 
  async chargeRun(deviceId: string, runId: string): Promise<ChargeResult> {
      const { data, error } = await this.client.rpc('spend_run', {
          p_device: deviceId,
          p_run: runId
      })
      if (error) throw new Error(`spend_run failed: ${error.message}`)
      const row = (Array.isArray(data) ? data[0] : data) as { charged: boolean; runs_remaining: number }
      return { charged: row.charged, runsRemaining: row.runs_remaining }
  }
97 
  async remaining(deviceId: string): Promise<number> {
      const { data, error } = await this.client
          .from('balances')
          .select('runs_remaining')
          .eq('device_id', deviceId)
          .maybeSingle()
      if (error) throw new Error(`balance read failed: ${error.message}`)
      return (data?.runs_remaining as number | undefined) ?? 0
  }
107 
  async runActiveFor(deviceId: string, runId: string): Promise<boolean> {
      const { data, error } = await this.client
          .from('runs')
          .select('id')
          .eq('id', runId)
          .eq('device_id', deviceId)
          .not('charged_at', 'is', null)
          .maybeSingle()
      if (error) throw new Error(`run check failed: ${error.message}`)
      return !!data
  }
119}
120 
⋯ 16 lines hidden (lines 121–136)121let cached: BalanceStore | null = null
122 
123/** The configured balance store (memoized). */
124export function balanceStore(): BalanceStore {
  if (cached) return cached
  const cfg = supabaseConfig()
  cached = cfg
      ? new SupabaseBalanceStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
      : new InMemoryBalanceStore()
  return cached
131}
132 
133/** Test seam: clear the memoized store so the next balanceStore() re-reads config. */
134export function resetBalanceStore(): void {
  cached = null
136}

The gate on the endpoints that cost money

Every billable endpoint checks first, before any model call. send-message returns a clean refusal — no tokens, and the client refunds the turn as it does for a moderation block. The chronicler (a 2000-token telling) and the two in-run browse endpoints (the Archive lookup and the Archivist study) gate the same way; the pre-commit setup endpoints stay ungated on purpose, since they run before a run is charged.

The gate sits at the top of the work, before the Judge/Character/Timeline calls.

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

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

⋯ 102 lines hidden (lines 1–102)1import { MAX_MESSAGE_CHARS } from '~/utils/game-config'
2import { toContactMoment, formatContactMoment } from '~/utils/contact-moment'
3import {
  cleanArray,
  cleanString,
  clampInt,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_GROUNDING_CHARS,
  MAX_HISTORY_ENTRIES,
  MAX_LEDGER_SWING,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_TIMELINE_ENTRIES
15} from '~/server/utils/validate'
16 
17export default defineEventHandler(async (event) => {
  // Only allow POST requests
  if (getMethod(event) !== 'POST') {
      throw createError({
          statusCode: 405,
          statusMessage: 'Method Not Allowed'
      })
  }
25 
  const body = await readBody(event)
27 
  // The client UI bounds these, but a direct POST is untrusted and every field
  // below feeds a gpt-5.5 prompt — so validate the boundary here, not just in the
  // store. (Surfaced by the input-validation-gap loop.)
  if (!body || typeof body.message !== 'string' || !body.message.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: message parameter is required'
      })
  }
  if (body.message.trim().length > MAX_MESSAGE_CHARS) {
      throw createError({
          statusCode: 400,
          statusMessage: `Bad Request: message exceeds ${MAX_MESSAGE_CHARS} characters`
      })
  }
  if (typeof body.figureName !== 'string' || !body.figureName.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: figureName parameter is required'
      })
  }
49 
  const { when = null, figureContext = null, objective = null } = body
  const message = body.message.trim()
  // A name is interpolated into every prompt (and the Wikipedia lookup upstream),
  // so it gets a hard cap like every other prompt-feeding string.
  const figure = cleanString(body.figureName, MAX_FIGURE_NAME_CHARS)
  // The grounded contact year (signed: AD positive / BC negative) — anchors the
  // causal-distance read and the character's world-brief. Optional + untrusted.
  const figureYear = typeof body.whenSigned === 'number' && Number.isFinite(body.whenSigned)
      ? clampInt(body.whenSigned, 12000)
      : undefined
  // The pinned moment (issue #32) arrives as untrusted integers and is
  // re-validated here; the display string the prompts see is DERIVED, never
  // the client's. Sub-year detail is prompt flavor only — every mechanic
  // below (world-brief, liveness, the wager) still computes on figureYear.
  const figureMoment = figureYear !== undefined ? toContactMoment(body.whenMonth, body.whenDay) : null
  const whenLabel = figureYear !== undefined ? formatContactMoment(figureYear, figureMoment) : undefined
  // The last-stand wager: the client offers it only on the final dispatch; the
  // doubling is applied after amplification, and the response echoes it.
  const staked = body.stake === true
69 
  // Normalize the objective into the context the Timeline Engine needs (coerced +
  // bounded — a non-string or megabyte field would otherwise reach the prompt raw).
  const objectiveContext = {
      title: cleanString(objective?.title, MAX_OBJECTIVE_TITLE_CHARS) || 'Alter the course of history',
      description: cleanString(objective?.description, MAX_OBJECTIVE_DESC_CHARS) || 'Bend the chain of events toward a better world.',
      era: cleanString(objective?.era, MAX_ERA_CHARS)
  }
  // The objective's far anchor year (signed: AD+/BC−) — the foothold the
  // causal-chain dial decays toward. Optional + untrusted; absent → no-op.
  const objectiveAnchorYear = typeof objective?.anchorYear === 'number' && Number.isFinite(objective.anchorYear)
      ? clampInt(objective.anchorYear, 12000)
      : undefined
82 
  // Sanitize the client-supplied ledger + thread: cap the counts and coerce each
  // field, so a crafted body can't crash a `.map`, forge an unbounded prior
  // history, or amplify token cost.
  const timeline = cleanArray(body.timeline, MAX_TIMELINE_ENTRIES).map((raw) => {
      const e = (raw ?? {}) as Record<string, unknown>
      return {
          era: cleanString(e.era, MAX_ERA_CHARS),
          headline: cleanString(e.headline, MAX_OBJECTIVE_TITLE_CHARS),
          detail: cleanString(e.detail, MAX_OBJECTIVE_DESC_CHARS),
          progressChange: clampInt(e.progressChange, MAX_LEDGER_SWING),
          whenSigned: typeof e.whenSigned === 'number' && Number.isFinite(e.whenSigned)
              ? clampInt(e.whenSigned, 12000)
              : undefined
      }
  })
  const conversationHistory = cleanArray(body.conversationHistory, MAX_HISTORY_ENTRIES)
      .map((raw) => (raw ?? {}) as Record<string, unknown>)
      .filter((m) => (m.sender === 'user' || m.sender === 'ai') && typeof m.text === 'string')
      .map((m) => ({ sender: m.sender as 'user' | 'ai', text: cleanString(m.text, MAX_MESSAGE_CHARS) }))
102 
  try {
      // Paywall enforcement: the run must be charged and owned by this device,
      // or a forged / unpaid run id could draw free generation. Fails open if
      // the balance store is unreachable (see run-guard) so an outage never
      // blocks a legit in-progress run.
      const { runIsActive } = await import('~/server/utils/run-guard')
      if (!(await runIsActive(event))) {
          return {
              success: false as const,
              message: 'Run not active',
              data: { userMessage: message, error: 'This run is no longer active. Start a new run to continue.' }
          }
      }
116 
⋯ 187 lines hidden (lines 117–303)117        const { callCharacterAI, callTimelineAI, callJudgeAI } = await import('~/server/utils/openai')
      const { rollD20, applyCraftModifier } = await import('~/utils/dice')
      const { CRAFT_MODIFIER } = await import('~/utils/craft')
      const { hardBlockCheck, moderateAction } = await import('~/server/utils/moderation')
121 
      // A blocked turn never burns a message: success:false + data.blocked lets
      // the store show a distinct, honest "blocked" banner (not an infra retry).
      const blockedResponse = (reason: string) => ({
          success: false as const,
          message: 'Blocked by moderation',
          data: { userMessage: message, blocked: true as const, moderationReason: reason, error: reason }
      })
129 
      // Moderation, stage 1 — a deterministic hard block on the raw dispatch
      // BEFORE we spend a generation token. The unforgivable categories (sexual
      // content, anything involving minors, self-harm facilitation) need no
      // context; the contextual Sentinel runs post-generation over the exchange.
      const inputBlock = await hardBlockCheck(message, 'turn', 'input')
      if (inputBlock.blocked) return blockedResponse(inputBlock.block.reason)
136 
      // 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
      }
149 
      // Step 1: The Judge grades the dispatch's craft — the one place player skill
      // directly tilts fate. A Judge outage grades 'sound' (modifier 0): an infra
      // hiccup must never tilt the die either way.
      const judged = await callJudgeAI({
          objective: objectiveContext,
          figureName: figure,
          when: grounding.when,
          momentRefined: figureMoment !== null,
          userMessage: message
      })
      const craft = judged.success && judged.judge ? judged.judge.craft : 'sound'
      const craftReason = judged.success && judged.judge ? judged.judge.reason : ''
      const rollModifier = CRAFT_MODIFIER[craft]
163 
      // 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)
167 
      // Step 3: The chosen figure replies and acts, in character, blind to the goal.
      // Grounding (when + real facts) anchors the role-play; the world-brief hands
      // them the altered history their own moment would already know (changes at or
      // before their year), so a turn-4 figure doesn't role-play the unaltered world.
      // Headlines only — `detail` narrates downstream ripples (often stamped with
      // later eras) and would hand the figure the future outright.
      const worldBrief = figureYear === undefined
          ? []
          : timeline
              .filter(e => typeof e.whenSigned === 'number' && e.whenSigned <= figureYear && e.headline)
              .slice(-5)
              .map(e => `${e.era ? `[${e.era}] ` : ''}${e.headline}`)
      const character = await callCharacterAI(figure, message, conversationHistory, diceResult.outcome, grounding, worldBrief)
      if (!character.success || !character.characterResponse) {
          // A model-side safety refusal is a block, not an infra hiccup.
          if (character.refused) return blockedResponse(character.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate character response',
              data: {
                  userMessage: message,
                  error: character.error || 'Character AI failed'
              }
          }
      }
193 
      const reply = character.characterResponse
195 
      // 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) + '...'
      }
201 
      // 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
      })
217 
      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'
              }
          }
      }
232 
      const ripple = timelineResult.ripple
234 
      // 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)
250 
      // The last stand: a staked dispatch doubles its resolved swing, both ways,
      // and may escape the per-turn fuse up to the full meter. The valence badge
      // is re-asserted AFTER the doubling — the sign-guard inside callTimelineAI
      // ran on the pre-stake value, and a doubled swing must wear its own color.
      const { applyStake } = await import('~/utils/swing-bands')
      const finalProgressChange = staked ? applyStake(ripple.progressChange) : ripple.progressChange
      const finalValence = staked && Math.abs(finalProgressChange) > 3
          ? (finalProgressChange > 0 ? 'positive' as const : 'negative' as const)
          : ripple.valence
260 
      return {
          success: true,
          message: 'Timeline updated',
          data: {
              userMessage: message,
              figure: {
                  name: figure,
                  era: reply.era,
                  descriptor: reply.persona
              },
              // The effective (craft-tilted) roll drives the bands and the UI; the
              // natural roll + modifier ride along so the reveal can show the tilt.
              diceRoll: diceResult.roll,
              diceOutcome: diceResult.outcome,
              naturalRoll: natural.roll,
              rollModifier,
              craft,
              craftReason,
              staked,
              characterResponse: { message: reply.message, action: reply.action },
              timeline: {
                  headline: ripple.headline,
                  detail: ripple.detail,
                  era: reply.era || objectiveContext.era,
                  progressChange: finalProgressChange,
                  baseProgressChange: ripple.baseProgressChange,
                  valence: finalValence,
                  anachronism: ripple.anachronism,
                  causalChain: ripple.causalChain
              },
              error: null
          }
      }
  } catch (error) {
      // Log the detail server-side; the wire gets a clean line (internal error
      // text — stack hints, key issues, SDK messages — is not for the client).
      console.error('API endpoint error:', error)
      throw createError({
          statusCode: 500,
          statusMessage: 'Internal Server Error'
      })
  }
303})

Same gate before the chronicler's large generation (lookup/research mirror it).

server/api/chronicle.post.ts · 76 lines

server/api/chronicle.post.ts76 lines · TypeScript

⋯ 55 lines hidden (lines 1–55)1import {
  cleanArray,
  cleanString,
  clampInt,
  MAX_ERA_CHARS,
  MAX_LEDGER_SWING,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_TIMELINE_ENTRIES
10} from '~/server/utils/validate'
11import type { ChronicleStatus } from '~/server/utils/prompt-builder'
12 
13const STATUSES: ChronicleStatus[] = ['playing', 'victory', 'defeat']
14 
15/**
* POST /api/chronicle — the Chronicler (Layer 3). Given the live objective, the
* running ledger, and the run's status, it narrates the altered timeline as it now
* stands. The client fires this non-blocking after every resolved turn, so the
* dice/progress reveal never waits on prose; the final telling is the epilogue.
*
* Like /api/send-message, every field below feeds a gpt-5.5 prompt, so the untrusted
* body is coerced + bounded here (the client caps live only in the store, which a raw
* POST bypasses). A model failure self-heals to `{ success: false }` — the caller
* keeps the prior chronicle rather than blanking the panel.
*/
26export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
30 
  const body = await readBody(event)
32 
  const objectiveContext = {
      title: cleanString(body?.objective?.title, MAX_OBJECTIVE_TITLE_CHARS) || 'Alter the course of history',
      description: cleanString(body?.objective?.description, MAX_OBJECTIVE_DESC_CHARS) || 'Bend the chain of events toward a better world.',
      era: cleanString(body?.objective?.era, MAX_ERA_CHARS)
  }
38 
  // Sanitize the client-supplied ledger: cap the count and coerce each field, so a
  // crafted body can't crash a `.map`, forge an unbounded prior history, or amplify
  // token cost. (Mirrors send-message.post.ts.)
  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),
          figureName: cleanString(e.figureName, MAX_ERA_CHARS),
          headline: cleanString(e.headline, MAX_OBJECTIVE_TITLE_CHARS),
          detail: cleanString(e.detail, MAX_OBJECTIVE_DESC_CHARS),
          progressChange: clampInt(e.progressChange, MAX_LEDGER_SWING)
      }
  })
52 
  const status: ChronicleStatus = STATUSES.includes(body?.status) ? body.status : 'playing'
  const progress = Math.max(0, Math.min(100, clampInt(body?.progress, 100)))
55 
  try {
      // Paywall enforcement: don't spend the chronicler's large generation on a
      // forged / unpaid run. Graceful — the caller keeps the prior telling.
      const { runIsActive } = await import('~/server/utils/run-guard')
      if (!(await runIsActive(event))) {
          return { success: false, error: 'Run not active' }
      }
63 
⋯ 13 lines hidden (lines 64–76)64        const { callChroniclerAI } = await import('~/server/utils/openai')
      const result = await callChroniclerAI({ objective: objectiveContext, timeline, status, progress })
66 
      if (!result.success || !result.chronicle) {
          return { success: false, error: result.error || 'Chronicle AI failed' }
      }
      return { success: true, chronicle: result.chronicle }
  } catch (error) {
      console.error('Chronicle endpoint error:', error)
      // Log the detail server-side; the wire gets a clean line.
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
76})

The review's fixes, and what stays open

Three things the review surfaced, fixed here:

- Critical — the non-UUID fail-open bypass above (a malformed header threw, then fail-open allowed it). Now refused before the store. - Major — spend_run now ensures the run row before charging, so "charged" always implies a row the gate can find; a paid run can't get locked out. - Major — the client now fails closed: if begin-run or the commit can't establish a charged, server-backed run, it surfaces an error and does not start (no fabricated local id that the gate would later reject).