Run balance + the paywall gate — a code-level reading

What changed, and why

This is the spine that turns a run into a currency. #46 measured cost-per-run; #47 made a run a server row. This makes a run a thing you spend: a new device gets one free run, the balance is charged when the player commits to an objective, and out of runs raises a paywall. It's the heart of "sell runs" — Stripe packs and a global spend cap are the next two vertebrae.

Five small pieces: a balance store (the ledger), an httpOnly device cookie (the trial identity), a commit endpoint (the gate), a gated chooseObjective on the client, and a one-function migration. No accounts, no payment yet.

The ledger — one port, two adapters

The balance store mirrors the run store: in-memory by default (dev + tests need nothing), Supabase when configured. A brand-new device is granted FREE_RUNS; chargeRun spends one run, and charged:false is the paywall. Idempotency is keyed to (device, run), not the run alone — so a second device can't ride another's already-charged run for free (chargedRuns maps a run id to the device that paid).

The port, the free grant, and the in-memory adapter (mirrors the SQL function).

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

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

⋯ 18 lines hidden (lines 1–18)1/**
2 * The run balance — the ledger that makes a run a thing you spend. A brand-new
3 * device gets FREE_RUNS for free (the doc's "first run free"); chargeRun spends
4 * one run when the player commits to an objective, once per run. Out of runs →
5 * the commit is refused (the paywall). Packs (Stripe) credit this balance later.
6 *
7 * Same two-adapter shape as the run store: in-memory by default (dev + tests need
8 * nothing), Supabase when configured. Keyed by an opaque device id (a server-set
9 * cookie) until accounts arrive, when a user id will supersede it.
10 *
11 * The Supabase charge goes through one SQL function (spend_run) so the
12 * ensure-grant, the idempotency check, and the decrement are atomic in a single
13 * round-trip — no read-modify-write race. The in-memory adapter mirrors that
14 * logic exactly.
15 */
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").
20 *  Mirrored by the spend_run SQL function; keep the two in sync. */
21export const FREE_RUNS = 1
22 
23export interface ChargeResult {
24    /** False only when the device is out of runs (the paywall). */
25    charged: boolean
26    runsRemaining: number
27}
28 
29export interface BalanceStore {
30    /** Ensure a balance row for the device, granting the free trial on first
31     *  sight; returns the current runs remaining. */
32    ensureDevice(deviceId: string): Promise<number>
33    /** Spend one run for the device, once per runId (idempotent — re-committing
34     *  the same run never double-charges). charged=false means out of runs. */
35    chargeRun(deviceId: string, runId: string): Promise<ChargeResult>
36    /** Runs remaining for the device (0 if unknown). */
37    remaining(deviceId: string): Promise<number>
38}
39 
40/** Dev default — process-local balances, durable enough for dev. Mirrors the
41 *  spend_run SQL function: free grant on first sight, one charge per run. */
42export class InMemoryBalanceStore implements BalanceStore {
43    private readonly balances = new Map<string, number>()
44    // runId → the device that charged it. Idempotency is per (device, run), so a
45    // different device can't ride another's already-charged run for free.
46    private readonly chargedRuns = new Map<string, string>()
47 
48    async ensureDevice(deviceId: string): Promise<number> {
49        if (!this.balances.has(deviceId)) this.balances.set(deviceId, FREE_RUNS)
50        return this.balances.get(deviceId) ?? 0
51    }
52 
53    async chargeRun(deviceId: string, runId: string): Promise<ChargeResult> {
54        const remaining = await this.ensureDevice(deviceId)
55        if (this.chargedRuns.get(runId) === deviceId) return { charged: true, runsRemaining: remaining }
56        if (remaining <= 0) return { charged: false, runsRemaining: 0 }
57        this.balances.set(deviceId, remaining - 1)
58        this.chargedRuns.set(runId, deviceId)
59        return { charged: true, runsRemaining: remaining - 1 }
60    }
61 
62    async remaining(deviceId: string): Promise<number> {
63        return this.balances.get(deviceId) ?? 0
64    }
65}
66 
⋯ 50 lines hidden (lines 67–116)67/** Service-key (RLS-bypassing) balance access; the table has no public policy. */
68export class SupabaseBalanceStore implements BalanceStore {
69    constructor(private readonly client: SupabaseClient) {}
70 
71    async ensureDevice(deviceId: string): Promise<number> {
72        const { error } = await this.client
73            .from('balances')
74            .insert({ device_id: deviceId, runs_remaining: FREE_RUNS })
75        // 23505 = unique_violation: the row already exists, which is fine.
76        if (error && error.code !== '23505') throw new Error(`balance ensure failed: ${error.message}`)
77        return this.remaining(deviceId)
78    }
79 
80    async chargeRun(deviceId: string, runId: string): Promise<ChargeResult> {
81        const { data, error } = await this.client.rpc('spend_run', {
82            p_device: deviceId,
83            p_run: runId
84        })
85        if (error) throw new Error(`spend_run failed: ${error.message}`)
86        const row = (Array.isArray(data) ? data[0] : data) as { charged: boolean; runs_remaining: number }
87        return { charged: row.charged, runsRemaining: row.runs_remaining }
88    }
89 
90    async remaining(deviceId: string): Promise<number> {
91        const { data, error } = await this.client
92            .from('balances')
93            .select('runs_remaining')
94            .eq('device_id', deviceId)
95            .maybeSingle()
96        if (error) throw new Error(`balance read failed: ${error.message}`)
97        return (data?.runs_remaining as number | undefined) ?? 0
98    }
99}
100 
101let cached: BalanceStore | null = null
102 
103/** The configured balance store (memoized). */
104export function balanceStore(): BalanceStore {
105    if (cached) return cached
106    const cfg = supabaseConfig()
107    cached = cfg
108        ? new SupabaseBalanceStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
109        : new InMemoryBalanceStore()
110    return cached
111}
112 
113/** Test seam: clear the memoized store so the next balanceStore() re-reads config. */
114export function resetBalanceStore(): void {
115    cached = null
116}

The Supabase charge does not read-modify-write. It calls one SQL function, spend_run, so the free grant, the idempotency check, and the conditional decrement happen atomically in a single round-trip.

The Supabase adapter: chargeRun is one rpc('spend_run'); ensureDevice tolerates the unique-violation.

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

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

⋯ 67 lines hidden (lines 1–67)1/**
2 * The run balance — the ledger that makes a run a thing you spend. A brand-new
3 * device gets FREE_RUNS for free (the doc's "first run free"); chargeRun spends
4 * one run when the player commits to an objective, once per run. Out of runs →
5 * the commit is refused (the paywall). Packs (Stripe) credit this balance later.
6 *
7 * Same two-adapter shape as the run store: in-memory by default (dev + tests need
8 * nothing), Supabase when configured. Keyed by an opaque device id (a server-set
9 * cookie) until accounts arrive, when a user id will supersede it.
10 *
11 * The Supabase charge goes through one SQL function (spend_run) so the
12 * ensure-grant, the idempotency check, and the decrement are atomic in a single
13 * round-trip — no read-modify-write race. The in-memory adapter mirrors that
14 * logic exactly.
15 */
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").
20 *  Mirrored by the spend_run SQL function; keep the two in sync. */
21export const FREE_RUNS = 1
22 
23export interface ChargeResult {
24    /** False only when the device is out of runs (the paywall). */
25    charged: boolean
26    runsRemaining: number
27}
28 
29export interface BalanceStore {
30    /** Ensure a balance row for the device, granting the free trial on first
31     *  sight; returns the current runs remaining. */
32    ensureDevice(deviceId: string): Promise<number>
33    /** Spend one run for the device, once per runId (idempotent — re-committing
34     *  the same run never double-charges). charged=false means out of runs. */
35    chargeRun(deviceId: string, runId: string): Promise<ChargeResult>
36    /** Runs remaining for the device (0 if unknown). */
37    remaining(deviceId: string): Promise<number>
38}
39 
40/** Dev default — process-local balances, durable enough for dev. Mirrors the
41 *  spend_run SQL function: free grant on first sight, one charge per run. */
42export class InMemoryBalanceStore implements BalanceStore {
43    private readonly balances = new Map<string, number>()
44    // runId → the device that charged it. Idempotency is per (device, run), so a
45    // different device can't ride another's already-charged run for free.
46    private readonly chargedRuns = new Map<string, string>()
47 
48    async ensureDevice(deviceId: string): Promise<number> {
49        if (!this.balances.has(deviceId)) this.balances.set(deviceId, FREE_RUNS)
50        return this.balances.get(deviceId) ?? 0
51    }
52 
53    async chargeRun(deviceId: string, runId: string): Promise<ChargeResult> {
54        const remaining = await this.ensureDevice(deviceId)
55        if (this.chargedRuns.get(runId) === deviceId) return { charged: true, runsRemaining: remaining }
56        if (remaining <= 0) return { charged: false, runsRemaining: 0 }
57        this.balances.set(deviceId, remaining - 1)
58        this.chargedRuns.set(runId, deviceId)
59        return { charged: true, runsRemaining: remaining - 1 }
60    }
61 
62    async remaining(deviceId: string): Promise<number> {
63        return this.balances.get(deviceId) ?? 0
64    }
65}
66 
67/** Service-key (RLS-bypassing) balance access; the table has no public policy. */
68export class SupabaseBalanceStore implements BalanceStore {
69    constructor(private readonly client: SupabaseClient) {}
70 
71    async ensureDevice(deviceId: string): Promise<number> {
72        const { error } = await this.client
73            .from('balances')
74            .insert({ device_id: deviceId, runs_remaining: FREE_RUNS })
75        // 23505 = unique_violation: the row already exists, which is fine.
76        if (error && error.code !== '23505') throw new Error(`balance ensure failed: ${error.message}`)
77        return this.remaining(deviceId)
78    }
79 
80    async chargeRun(deviceId: string, runId: string): Promise<ChargeResult> {
81        const { data, error } = await this.client.rpc('spend_run', {
82            p_device: deviceId,
83            p_run: runId
84        })
85        if (error) throw new Error(`spend_run failed: ${error.message}`)
86        const row = (Array.isArray(data) ? data[0] : data) as { charged: boolean; runs_remaining: number }
87        return { charged: row.charged, runsRemaining: row.runs_remaining }
88    }
89 
90    async remaining(deviceId: string): Promise<number> {
91        const { data, error } = await this.client
92            .from('balances')
93            .select('runs_remaining')
94            .eq('device_id', deviceId)
95            .maybeSingle()
96        if (error) throw new Error(`balance read failed: ${error.message}`)
97        return (data?.runs_remaining as number | undefined) ?? 0
98    }
99}
100 
101let cached: BalanceStore | null = null
⋯ 15 lines hidden (lines 102–116)102 
103/** The configured balance store (memoized). */
104export function balanceStore(): BalanceStore {
105    if (cached) return cached
106    const cfg = supabaseConfig()
107    cached = cfg
108        ? new SupabaseBalanceStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
109        : new InMemoryBalanceStore()
110    return cached
111}
112 
113/** Test seam: clear the memoized store so the next balanceStore() re-reads config. */
114export function resetBalanceStore(): void {
115    cached = null
116}

The gate

The client calls this when the player commits to an objective. It spends one run for the run id and returns the new balance, or 402 when out. A run id that isn't a server-minted UUID means begin-run degraded to a local id (a store outage) — that run was never recorded, so it isn't gated; the client is allowed to play. The honest caveat: this, and a forged id, are uncharged until the AI endpoints verify the run id server-side (a tracked follow-up).

Validate (strict UUID), resolve the device, charge — 402 on out-of-runs, degrade on a non-UUID id.

server/api/run-commit.post.ts · 48 lines

server/api/run-commit.post.ts48 lines · TypeScript

⋯ 23 lines hidden (lines 1–23)1/**
* POST /api/run-commit — the paywall gate. The client calls this when the player
* commits to an objective. It spends one run from the device's balance for this
* runId (once, idempotently), granting the free trial on the device's first
* sight. Returns { runsRemaining } when charged, or 402 when out of runs.
*
* A run id that isn't a server-minted UUID means begin-run degraded to a local id
* (a store outage) — that run was never recorded, so it isn't gated here; the
* client is allowed to play (best-effort, uncharged). NOTE: there is no
* server-enforced spend backstop yet — this gap (and a forged id) means uncharged
* play and uncharged AI spend until the AI endpoints verify the run id and the
* spend-cap vertebra lands. Both are tracked follow-ups, acceptable only while the
* alpha sits behind basic auth.
*/
15import { deviceId } from '~/server/utils/device'
16import { balanceStore } from '~/server/utils/balance-store'
17import { isUuid } from '~/server/utils/uuid'
18 
19export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
  const body = await readBody(event)
  const runId = typeof body?.runId === 'string' ? body.runId.replace(/[^a-zA-Z0-9-]/g, '').slice(0, 64) : ''
  if (!runId) {
      throw createError({ statusCode: 400, statusMessage: 'Bad Request: runId is required' })
  }
28 
  const device = deviceId(event)
  // A degraded (non-UUID) run was never recorded server-side — don't gate it.
  if (!isUuid(runId)) return { runsRemaining: -1, degraded: true }
32 
  let result
  try {
      result = await balanceStore().chargeRun(device, runId)
  } catch (error) {
      console.error('Run commit failed:', error)
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
  if (!result.charged) {
      throw createError({
          statusCode: 402,
          statusMessage: 'Out of runs',
          data: { runsRemaining: result.runsRemaining }
      })
  }
  return { runsRemaining: result.runsRemaining }
48})

The client — gated commit, paywall on refusal

chooseObjective is now async and gated. It charges the run; if the device is out (402, in any of ofetch's error shapes) it raises the paywall and the run does not start. Any other failure degrades to allowing the run — a store outage must never block play. MissionSelect shows the paywall notice.

Charge at commit; 402 → paywall + don't start; other errors → degrade and start.

stores/game.ts · 1097 lines

stores/game.ts1097 lines · TypeScript

⋯ 988 lines hidden (lines 1–988)1import { defineStore } from 'pinia'
2import type { GameObjective } from '~/server/utils/objective-generator'
3import type { GroundedFigure } from '~/server/utils/figure-grounding'
4import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
5import type { FigureSuggestion } from '~/server/utils/figure-suggester'
6import type { ChronicleEntry } from '~/server/utils/openai'
7import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
8import type { Anachronism } from '~/server/utils/anachronism'
9import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
10import type { Craft } from '~/utils/craft'
11import type { DiceOutcome } from '~/utils/dice'
12import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
13import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
14 
15export type Valence = 'positive' | 'negative' | 'neutral'
16 
17/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
22export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
26}
27 
28/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
35export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
59}
60 
61/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
66export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
90}
91 
92export type GameStatus = 'playing' | 'victory' | 'defeat'
93 
94/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
101type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
146 
147const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
148const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
149 
150function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
154}
155 
156/** Formats a signed timeline year (AD positive, BCE negative) for display. */
157export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
159}
160 
161/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
162function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
166}
167 
168/** A fresh run id. Used to tag every server call in one run so the gateway's
*  cost telemetry groups per run (the GTM cost instrument). randomUUID needs a
*  secure context (https / localhost — both our cases); the fallback covers the
*  rare insecure one. Not security-sensitive: it only groups log lines. */
172function generateRunId(): string {
  try {
      return crypto.randomUUID()
  } catch {
      return `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
  }
178}
179 
180/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
182function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
185}
186 
187export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'unknown'
188 
189/**
* Game Store — core state for a session of freeform timeline editing.
*/
192export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The remaining-balance readout returns with the Stripe
      // slice, when there's somewhere to show it.
      outOfRuns: false,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
261 
  getters: {
      /**
       * Can the player send right now? (messages left, still playing, not
       * mid-request, not rate-limited)
       */
      canSendMessage(): boolean {
          return this.remainingMessages > 0 &&
                 this.gameStatus === 'playing' &&
                 !this.isLoading &&
                 !this.isRateLimited
      },
273 
      /**
       * The conversation thread with a single figure (their turns + the
       * player's turns addressed to them). Each figure keeps a coherent,
       * independent thread.
       */
      conversationWith(): (name: string) => Message[] {
          return (name: string) => this.messageHistory.filter(
              m => m.figureName === name && m.sender !== 'system'
          )
      },
284 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
289 
      /**
       * Whether the chosen `when` falls within the active figure's lifetime.
       * 'unknown' (permissive) whenever we lack solid dates — we never block a
       * figure we couldn't ground, only one we know you can't reach yet/anymore.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved || !g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          const latest = g.died ? g.died.signed : new Date().getFullYear()
          if (this.contactWhen > latest) return 'after-death'
          return 'ok'
      },
303 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
308 
      /**
       * The last stand is offered ONLY when the final dispatch can no longer win
       * inside the normal per-turn fuse — from any nearer position an unstaked
       * throw can still land it, and offering the (strictly win-probability-
       * increasing) doubling there would be a dominance trap, not a decision.
       */
      canStake(): boolean {
          return this.remainingMessages === 1 &&
                 this.gameStatus === 'playing' &&
                 (MAX_PROGRESS - this.objectiveProgress) > MAX_PROGRESS_SWING
      },
320 
      /**
       * The active figure's age at the chosen `when` — so the player never has to
       * do lifetime math in their head. Null when we lack a birth year or a chosen
       * year (unresolved / free-form contact). Corrects for the missing year zero
       * when a life spans the BC→AD boundary (1 BC → AD 1 is one year, not two).
       */
      contactAge(): number | null {
          const g = this.figureGrounding
          if (!g?.resolved || !g.born || this.contactWhen == null) return null
          const bornSigned = g.born.signed
          const whenSigned = this.contactWhen
          if (whenSigned < bornSigned) return null // before birth — no meaningful age
          const crossedZero = bornSigned < 0 && whenSigned > 0 ? 1 : 0
          return whenSigned - bornSigned - crossedZero
      },
336 
      /**
       * The causal-chain read for the CURRENT contact — the pre-send ⏳ chip's
       * source, mirroring what the Timeline Engine will compute. Footholds are the
       * objective's anchor year plus every dated change already on the ledger; the
       * gap to the nearest one decays the swing. Null (no chip) for ungrounded
       * contacts or an anchorless objective with no dated changes yet.
       */
      causalChainRead(): ChainStatus | null {
          const footholds = [
              this.currentObjective?.anchorYear,
              ...this.timelineEvents.map(e => e.whenSigned)
          ]
          return chainStatus(this.contactWhen, footholds)
      }
  },
352 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
364 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
373 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
395 
      // ---------- figures ----------
      registerFigure(figure: HistoricalFigure) {
          const existing = this.figures.find(f => f.name === figure.name)
          if (existing) {
              if (figure.era) existing.era = figure.era
              if (figure.descriptor) existing.descriptor = figure.descriptor
          } else {
              this.figures.push({ ...figure })
          }
      },
406 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
410 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch goes out clean (free-form)
       * instead of wearing the PREVIOUS figure's facts, year, and liveness gate —
       * and so the wrong year can never be written into the ledger's whenSigned.
       */
      clearGrounding() {
          this.groundingSeq++ // invalidate any lookup still in flight
          this.figureGrounding = null
          this.contactWhen = null
          this.contactMoment = null
          this.groundingLoading = false
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
      },
428 
      /**
       * Resolves the active figure against the grounding service and defaults the
       * "when" to a point inside any known lifetime. Never throws: an unresolved
       * figure simply clears grounding, leaving the contact free-form.
       */
      async groundActiveFigure(name: string): Promise<void> {
          const target = (name || '').trim()
          // A new contact makes any prior Archive study stale.
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
          if (!target) {
              this.groundingSeq++ // invalidate any lookup still in flight
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
              this.groundingLoading = false
              return
          }
          // Out-of-order guard: only the LATEST lookup may land. Without it, a slow
          // response for the previous name attaches the wrong dossier (and a wrong
          // figureContext on a fast send) to whatever the player typed next.
          const epoch = this.runEpoch
          const seq = ++this.groundingSeq
          this.groundingLoading = true
          try {
              const grounded = await $fetch('/api/figure', { params: { name: target }, headers: await this.aiHeaders() }) as GroundedFigure
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              this.figureGrounding = grounded
              this.contactMoment = null
              if (grounded?.resolved && grounded.born) {
                  const latest = grounded.died ? grounded.died.signed : new Date().getFullYear()
                  this.contactWhen = Math.round((grounded.born.signed + latest) / 2)
              } else {
                  this.contactWhen = null
              }
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              console.error('Figure grounding failed:', error)
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
          } finally {
              if (epoch === this.runEpoch && seq === this.groundingSeq) this.groundingLoading = false
          }
      },
476 
      /** The current run's id, minted server-side on first need. POST /api/run
       *  makes the run a server fact (a persisted row); the id then tags every
       *  AI call so the cost telemetry groups per run. Best-effort: if begin-run
       *  fails, fall back to a local id so a store outage degrades the ledger,
       *  never the turn — the [ai] lines still group, just without a server row. */
      async ensureRunId(): Promise<string> {
          if (this.runId) return this.runId
          // Collapse concurrent first-calls onto ONE begin-run: without this,
          // two AI calls overlapping at run start each POST /api/run, minting
          // two server rows and splitting the run's telemetry across two ids.
          // The epoch captured here guards a resetGame mid-flight — the dead
          // run's id must not become the fresh run's (the guard every other
          // async action in this store carries).
          if (!this.runIdInflight) {
              const epoch = this.runEpoch
              this.runIdInflight = (async () => {
                  let id: string
                  try {
                      const res = await $fetch('/api/run', { method: 'POST' }) as { runId?: string }
                      id = res?.runId || generateRunId()
                  } catch {
                      id = generateRunId()
                  }
                  // Only land the mint if its run still exists; if reset bumped
                  // the epoch, leave this.runId/runIdInflight for the new run.
                  if (epoch === this.runEpoch) {
                      this.runId = id
                      this.runIdInflight = null
                  }
                  return id
              })()
          }
          return this.runIdInflight
      },
511 
      /** Headers that tag a server call with the current run (the cost
       *  instrument), minting the run id first if needed. */
      async aiHeaders(base: Record<string, string> = {}): Promise<Record<string, string>> {
          return { ...base, 'x-run-id': await this.ensureRunId() }
      },
517 
      setContactWhen(year: number | null) {
          // Scrubbing the year keeps any pinned month/day — the pin refines
          // whichever year is chosen, it doesn't belong to one.
          this.contactWhen = year
      },
523 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
527 
      /**
       * Studies the active (grounded) figure via the Archivist — an objective-blind
       * brief on who they are AT THE CHOSEN MOMENT, so the player can research in the
       * game instead of a browser tab. The brief is moment-specific, so it's cached
       * against the figure AND the year: move the contact slider and the player can
       * re-study them at the new moment. Graceful on failure (leaves the prior brief).
       * Only resolved figures can be studied — an unresolved name has no record.
       */
      async studyActiveFigure(): Promise<void> {
          const g = this.figureGrounding
          if (!g?.resolved) {
              this.figureStudy = null
              return
          }
          // Cache hit only when both the figure AND the studied year still match.
          if (this.studyFor === g.name && this.studyWhen === this.contactWhen && this.figureStudy) return
544 
          // Capture the moment being studied NOW: the brief describes this figure at
          // this year. If the slider moves mid-flight, recording the live value would
          // mislabel the brief and silently suppress the Re-study button.
          const epoch = this.runEpoch
          const studiedName = g.name
          const studiedWhen = this.contactWhen
          this.studyLoading = true
          this.studyNotice = null
          try {
              const res = await $fetch('/api/research', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      figureName: studiedName,
                      when: studiedWhen != null ? formatContactYear(studiedWhen) : undefined,
                      description: g.description,
                      extract: g.extract
                  }
              }) as { success?: boolean; study?: FigureStudy; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              // If the contact changed mid-flight, the stale-study clear in
              // groundActiveFigure already ran — don't resurrect the old brief.
              if (res?.blocked && this.figureGrounding?.name === studiedName) {
                  this.studyNotice = res.error || 'That study was blocked by content moderation.'
              } else if (res?.success && res.study && this.figureGrounding?.name === studiedName) {
                  this.figureStudy = res.study
                  this.studyFor = studiedName
                  this.studyWhen = studiedWhen
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
581 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
615 
      /**
       * Loads era-relevant figure suggestions for the current objective (the
       * educational on-ramp). Cached per objective; on any failure it leaves the
       * list empty so the UI falls back to its generic starters.
       */
      async loadSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) {
              this.figureSuggestions = []
              this.suggestionsFor = ''
              return
          }
          if (this.suggestionsFor === objective.title && this.figureSuggestions.length) return
629 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch) this.suggestionsLoading = false
          }
      },
662 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
686 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
735 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
741 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
748 
      setRateLimit() {
          this.isRateLimited = true
          const remainingTime = this.lastMessageTime
              ? Math.max(0, RATE_LIMIT_MS - (Date.now() - this.lastMessageTime))
              : 0
          setTimeout(() => { this.isRateLimited = false }, remainingTime || RATE_LIMIT_MS)
      },
756 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
761 
      /**
       * Rolls back an unresolved turn: refunds the spent message and drops the
       * dangling user entry, so the counter and history can't drift out of sync.
       * Used for BOTH failure shapes — a thrown request and a graceful HTTP-200
       * `success:false` — an infra hiccup must never burn one of the five
       * dispatches (or, on the last one, convert into an instant unearned defeat).
       */
      refundUnresolvedTurn() {
          if (this.remainingMessages < TOTAL_MESSAGES) this.remainingMessages++
          for (let i = this.messageHistory.length - 1; i >= 0; i--) {
              if (this.messageHistory[i].sender === 'user') {
                  this.messageHistory.splice(i, 1)
                  break
              }
          }
      },
778 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
782 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
798 
      // ---------- the turn ----------
      /**
       * Sends a 160-char message to a chosen figure and folds the result back
       * into the world: the figure replies + acts, the dice decide the swing,
       * and the Timeline Engine records how history bent.
       *
       * Returns `true` only when the turn actually RESOLVED (a ledger entry
       * landed). A blocked or failed send returns `false` so the composer can
       * keep the player's crafted words instead of wiping them.
       *
       * `opts.stake` arms the last stand — honored only when `canStake` holds
       * (final message, win out of normal reach; the server doubles the resolved
       * swing, both ways, past the usual cap).
       */
      async sendMessage(text: string, figureName?: string, opts?: { stake?: boolean }): Promise<boolean> {
          const target = (figureName ?? this.activeFigureName ?? '').trim()
          const stake = opts?.stake === true && this.canStake
816 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'before-birth'
                      ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                      : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
836 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
844 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
855 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
888 
              if (epoch !== this.runEpoch) return false
890 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
893 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
901 
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
921 
                  if (timeline) {
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
973 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              void this.refreshChronicle()
          }
          return resolved
      },
983 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id, then spend one run
          // from the device's balance. Out of runs → don't start; raise the
          // paywall. Any other failure degrades to allowing the run — a store
          // outage must never block play; the budget cap is the real backstop.
          const runId = await this.ensureRunId()
          try {
              await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              })
              this.outOfRuns = false
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  return false
              }
              console.error('Run commit failed; allowing the run:', error)
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.error = null
          return true
      },
1014 
      /**
⋯ 82 lines hidden (lines 1016–1097)1016         * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). Returns null rather than throwing if composing
       * fails, so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(): Promise<GameObjective | null> {
          try {
              const res = await $fetch('/api/objective', { method: 'GET', headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1034 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1040 
              const efficiencyRating = rateEfficiency(messagesSaved)
1042 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1053 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          // The paywall re-checks on the next commit; the balance stays as-is.
          this.outOfRuns = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1097})

The table, and the atomic charge

One migration: the balances table (RLS on, no policy → service-key-only, like runs), two nullable columns on runs to record who spent a run and when, and the spend_run function. The function is where correctness lives: it locks the run row (for update) so two commits of the same run serialize — without that, one caller hit a spurious 402 after the other's decrement — and the conditional update ... where runs_remaining > 0 can't lose a race the way a read-then-write would. The idempotent no-op is gated on the owning device.

balances (server-only) and the two run columns.

supabase/migrations/0002_balances.sql · 63 lines

supabase/migrations/0002_balances.sql63 lines · Transact-SQL

1-- balances: the run ledger, keyed by the trial device id (a server-set cookie).
2-- A new device is granted the free trial; spend_run decrements it at commit.
3-- RLS on with no policy: service-key-only, like runs.
4create table if not exists public.balances (
5    device_id      text        primary key,
6    runs_remaining int         not null default 0,
7    updated_at     timestamptz not null default now()
8);
9 
10alter table public.balances enable row level security;
11 
12-- Tie a run to who spent it and when (set at commit). Both nullable: an
13-- uncommitted run has neither.
14alter table public.runs add column if not exists device_id  text;
15alter table public.runs add column if not exists charged_at timestamptz;
⋯ 48 lines hidden (lines 16–63)16 
17-- spend_run: grant the device's free trial on first sight, then charge ONE run
18-- for p_run — idempotently (a re-commit of the same run doesn't double-charge)
19-- and atomically (the conditional decrement can't race a read-modify-write).
20-- Returns whether it charged and the resulting balance. The free-grant constant
21-- mirrors FREE_RUNS in server/utils/balance-store.ts — keep the two in sync.
22create or replace function public.spend_run(p_device text, p_run uuid)
23returns table(charged boolean, runs_remaining int)
24language plpgsql as $$
25declare
26    v_remaining  int;
27    v_charged_at timestamptz;
28    v_owner      text;
29begin
30    insert into public.balances(device_id, runs_remaining)
31        values (p_device, 1)
32        on conflict (device_id) do nothing;
33 
34    -- Lock the run row so concurrent commits of the SAME run serialize here;
35    -- without the lock both pass the not-yet-charged guard and one gets a
36    -- spurious 402 after the other's decrement. Read the owner too: idempotency
37    -- is per (device, run), so only the device that charged this run gets the
38    -- no-op return — a different device falls through to its own decrement (or a
39    -- 402), never a free pass on someone else's already-charged run.
40    select r.charged_at, r.device_id into v_charged_at, v_owner
41        from public.runs r where r.id = p_run
42        for update;
43    if v_charged_at is not null and v_owner = p_device then
44        select b.runs_remaining into v_remaining from public.balances b where b.device_id = p_device;
45        return query select true, coalesce(v_remaining, 0);
46        return;
47    end if;
48 
49    -- Atomic conditional decrement: charges only if a run is available.
50    update public.balances b
51        set runs_remaining = b.runs_remaining - 1, updated_at = now()
52        where b.device_id = p_device and b.runs_remaining > 0
53        returning b.runs_remaining into v_remaining;
54    if not found then
55        select b.runs_remaining into v_remaining from public.balances b where b.device_id = p_device;
56        return query select false, coalesce(v_remaining, 0);
57        return;
58    end if;
59 
60    update public.runs set charged_at = now(), device_id = p_device where id = p_run;
61    return query select true, v_remaining;
62end;
63$$;

spend_run: free grant, FOR UPDATE serialization, per-(device,run) idempotency, atomic decrement.