The Supabase run store — a code-level reading

What changed, and why

Slice A (#46) made cost-per-run measurable by tagging every AI call with a run id. This makes a run a server fact. Until now a run was purely client state: the browser minted the id. Now POST /api/run mints it and records the run, so the id the cost telemetry groups by points at a real, persisted run — and a per-player run balance can later decrement against it. That balance is the monetization keystone; this PR lays the ground for it without building it yet.

The change is small and has a clear seam. A run store with two adapters (one for dev, one for prod), a one-route endpoint that uses it, a client that calls that endpoint instead of minting locally, and a one-table migration. No balance, no identity, no cost columns — those come later. Cost stays a projection of the telemetry, never a stored value.

The run store: one port, two adapters

The store is a port with two implementations. In-memory is the default, so npm run dev and the unit tests need no external service — it just mints and returns a real id, persisting nothing (a dev run needn't outlive the process). Supabase is the durable one; it inserts the run as a row via the service key, and translates a Supabase error envelope into a thrown error — the one branch the begin-run 500 / client-fallback contract leans on.

The port and its two adapters. The id is minted server-side; cost is never a column here.

server/utils/run-store.ts · 88 lines

server/utils/run-store.ts88 lines · TypeScript

⋯ 19 lines hidden (lines 1–19)1/**
2 * The run store — where a game run becomes a server-side fact. POST /api/run
3 * mints a run id and records the run here; the client echoes that id back as
4 * x-run-id, which the cost telemetry groups by. On the happy path the recorded
5 * id and the telemetry id are the same; tying them together so a per-player
6 * balance can spend against the row is the next slice's job, not this one's.
7 *
8 * Two adapters behind one port, chosen by config — the repo's env-degradation
9 * idiom (cf. moderationMode, the REVISIONIST_AI_LANE override):
10 *   - in-memory (default): no external dependency, so `npm run dev` and the unit
11 *     tests need nothing. The run id is real; the "store" is process-local.
12 *   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured;
13 *     inserts the run into the `runs` table (see supabase/migrations).
14 *
15 * Cost is derived, never stored here: cost-per-run stays a projection of the
16 * [ai] telemetry, not a column. This table records a run's existence.
17 */
18import { createClient, type SupabaseClient } from '@supabase/supabase-js'
19 
20export interface RunStore {
21    /** Mint a run id, persist the run, and return the id. */
22    createRun(): Promise<string>
23}
24 
25/** A new run id. crypto.randomUUID is always present server-side (Node 19+). */
26function newRunId(): string {
27    return crypto.randomUUID()
28}
29 
30/** Dev default — mints a real run id but persists nothing (a run needn't outlive
31 *  the process in dev). The Supabase adapter is the durable one. */
32export class InMemoryRunStore implements RunStore {
33    async createRun(): Promise<string> {
34        return newRunId()
35    }
36}
37 
38/** Records each run as a row in the `runs` table via the service (secret) key,
39 *  which bypasses RLS — the table has no public policy, so it is server-only. */
40export class SupabaseRunStore implements RunStore {
41    constructor(private readonly client: SupabaseClient) {}
42    async createRun(): Promise<string> {
43        const id = newRunId()
44        const { error } = await this.client.from('runs').insert({ id })
45        if (error) throw new Error(`runs insert failed: ${error.message}`)
46        return id
47    }
48}
49 
50interface SupabaseConfig {
51    url: string
52    secretKey: string
53}
54 
55/** Supabase creds from runtimeConfig (Nuxt) or raw env (tests/evals in node),
⋯ 33 lines hidden (lines 56–88)56 *  null when either is absent — the signal to stay in-memory. Mirrors
57 *  ai-gateway's configuredKey. */
58function supabaseConfig(): SupabaseConfig | null {
59    let url: string | undefined
60    let secretKey: string | undefined
61    try {
62        const cfg = useRuntimeConfig()
63        url = cfg.supabaseUrl as string | undefined
64        secretKey = cfg.supabaseSecretKey as string | undefined
65    } catch {
66        // not in a Nuxt context
67    }
68    url = url || process.env.SUPABASE_URL
69    secretKey = secretKey || process.env.SUPABASE_SECRET_KEY
70    return url && secretKey ? { url, secretKey } : null
71}
72 
73let cached: RunStore | null = null
74 
75/** The configured run store (memoized — reuses one Supabase client). */
76export function runStore(): RunStore {
77    if (cached) return cached
78    const cfg = supabaseConfig()
79    cached = cfg
80        ? new SupabaseRunStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
81        : new InMemoryRunStore()
82    return cached
83}
84 
85/** Test seam: clear the memoized store so the next runStore() re-reads config. */
86export function resetRunStore(): void {
87    cached = null
88}

Chosen by config — what keeps dev simple

Which adapter runs is decided by config, not a flag: if SUPABASE_URL and SUPABASE_SECRET_KEY are both present it's Supabase, otherwise in-memory. This is the repo's existing env-degradation idiom (the same shape as moderationMode and the AI-lane override), and it's exactly what lets a dev run with nothing wired. The store is memoized so one Supabase client is reused; resetRunStore is the test seam to re-read config.

Creds from runtimeConfig or raw env (null → stay in-memory); memoized factory.

server/utils/run-store.ts · 88 lines

server/utils/run-store.ts88 lines · TypeScript

⋯ 57 lines hidden (lines 1–57)1/**
2 * The run store — where a game run becomes a server-side fact. POST /api/run
3 * mints a run id and records the run here; the client echoes that id back as
4 * x-run-id, which the cost telemetry groups by. On the happy path the recorded
5 * id and the telemetry id are the same; tying them together so a per-player
6 * balance can spend against the row is the next slice's job, not this one's.
7 *
8 * Two adapters behind one port, chosen by config — the repo's env-degradation
9 * idiom (cf. moderationMode, the REVISIONIST_AI_LANE override):
10 *   - in-memory (default): no external dependency, so `npm run dev` and the unit
11 *     tests need nothing. The run id is real; the "store" is process-local.
12 *   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured;
13 *     inserts the run into the `runs` table (see supabase/migrations).
14 *
15 * Cost is derived, never stored here: cost-per-run stays a projection of the
16 * [ai] telemetry, not a column. This table records a run's existence.
17 */
18import { createClient, type SupabaseClient } from '@supabase/supabase-js'
19 
20export interface RunStore {
21    /** Mint a run id, persist the run, and return the id. */
22    createRun(): Promise<string>
23}
24 
25/** A new run id. crypto.randomUUID is always present server-side (Node 19+). */
26function newRunId(): string {
27    return crypto.randomUUID()
28}
29 
30/** Dev default — mints a real run id but persists nothing (a run needn't outlive
31 *  the process in dev). The Supabase adapter is the durable one. */
32export class InMemoryRunStore implements RunStore {
33    async createRun(): Promise<string> {
34        return newRunId()
35    }
36}
37 
38/** Records each run as a row in the `runs` table via the service (secret) key,
39 *  which bypasses RLS — the table has no public policy, so it is server-only. */
40export class SupabaseRunStore implements RunStore {
41    constructor(private readonly client: SupabaseClient) {}
42    async createRun(): Promise<string> {
43        const id = newRunId()
44        const { error } = await this.client.from('runs').insert({ id })
45        if (error) throw new Error(`runs insert failed: ${error.message}`)
46        return id
47    }
48}
49 
50interface SupabaseConfig {
51    url: string
52    secretKey: string
53}
54 
55/** Supabase creds from runtimeConfig (Nuxt) or raw env (tests/evals in node),
56 *  null when either is absent — the signal to stay in-memory. Mirrors
57 *  ai-gateway's configuredKey. */
58function supabaseConfig(): SupabaseConfig | null {
59    let url: string | undefined
60    let secretKey: string | undefined
61    try {
62        const cfg = useRuntimeConfig()
63        url = cfg.supabaseUrl as string | undefined
64        secretKey = cfg.supabaseSecretKey as string | undefined
65    } catch {
66        // not in a Nuxt context
67    }
68    url = url || process.env.SUPABASE_URL
69    secretKey = secretKey || process.env.SUPABASE_SECRET_KEY
70    return url && secretKey ? { url, secretKey } : null
71}
72 
73let cached: RunStore | null = null
74 
75/** The configured run store (memoized — reuses one Supabase client). */
76export function runStore(): RunStore {
77    if (cached) return cached
78    const cfg = supabaseConfig()
79    cached = cfg
80        ? new SupabaseRunStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
81        : new InMemoryRunStore()
82    return cached
83}
84 
85/** Test seam: clear the memoized store so the next runStore() re-reads config. */
86export function resetRunStore(): void {
87    cached = null
88}

The begin-run endpoint

One route mints the run id and records the run. It takes no input, so there's nothing to validate or inject. A failure is a 500 — and the client treats begin-run as best-effort, so a store outage degrades the ledger, never the turn.

Mint + record + return { runId }; failures are non-fatal to play (see the client).

server/api/run.post.ts · 24 lines

server/api/run.post.ts24 lines · TypeScript

⋯ 12 lines hidden (lines 1–12)1/**
* POST /api/run — begins a run server-side: mints a run id, records the run, and
* returns { runId }. The client calls this at the start of a run and sends the id
* as x-run-id on every later AI call (the cost-instrument tag). This is the seam
* where a run becomes a server fact; the run store decides whether that fact is
* durable (Supabase) or process-local (the in-memory dev default).
*
* A failure here is a 500: the client treats begin-run as best-effort and falls
* back to a local id, so a store outage degrades the ledger, never the game.
*/
11import { runStore } from '~/server/utils/run-store'
12 
13export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
  try {
      const runId = await runStore().createRun()
      return { runId }
  } catch (error) {
      console.error('Failed to begin run:', error)
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
24})

The client mints server-side now

In #46 the client minted the run id locally. Now ensureRunId calls /api/run the first time a run needs an id, then reuses it, and every AI call is tagged with x-run-id as before. Three properties matter. The fallback: if begin-run fails, the client mints a local id so the turn still proceeds and telemetry still groups — the server record is best-effort, the game is not. The in-flight memo: concurrent first-calls share one mint, so two overlapping calls at run start don't create two run rows. And the epoch guard: a resetGame mid-mint abandons the stale mint instead of bleeding the dead run's id into the new one.

ensureRunId: one shared in-flight mint, epoch-guarded, with a local fallback; the now-async aiHeaders.

stores/game.ts · 1064 lines

stores/game.ts1064 lines · TypeScript

⋯ 470 lines hidden (lines 1–470)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 
180export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'unknown'
181 
182/**
* Game Store — core state for a session of freeform timeline editing.
*/
185export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // 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,
      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
  }),
250 
  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
      },
262 
      /**
       * 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'
          )
      },
273 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
278 
      /**
       * 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'
      },
292 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
297 
      /**
       * 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
      },
309 
      /**
       * 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
      },
325 
      /**
       * 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)
      }
  },
341 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
353 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
362 
      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
          })
      },
384 
      // ---------- 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 })
          }
      },
395 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
399 
      /**
       * 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
      },
417 
      /**
       * 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
          }
      },
465 
      /** 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
      },
500 
      /** 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() }
      },
506 
⋯ 558 lines hidden (lines 507–1064)507        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
      },
512 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
516 
      /**
       * 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
533 
          // 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
          }
      },
570 
      /**
       * 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
          }
      },
604 
      /**
       * 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
618 
          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
          }
      },
651 
      // ---------- 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()
          })
      },
675 
      // ---------- 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
          }
      },
724 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
730 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
737 
      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)
      },
745 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
750 
      /**
       * 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
              }
          }
      },
767 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
771 
      /**
       * 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'
          }
      },
787 
      // ---------- 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
805 
          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
          }
825 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
833 
          // 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
844 
          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)
                  }
              })
877 
              if (epoch !== this.runEpoch) return false
879 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
882 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
890 
                  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
                  })
910 
                  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()
              }
          }
962 
          // 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
      },
972 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      chooseObjective(objective: GameObjective) {
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.error = null
      },
983 
      /**
       * 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
          }
      },
1003 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1009 
              const efficiencyRating = rateEfficiency(messagesSaved)
1011 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1022 
      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
          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
      }
  }
1064})

The table, and how it's reached

The migration is one table, kept to id + created_at — nothing speculative. RLS is on with no policy on purpose: the anon key can touch nothing, while the service (secret) key bypasses RLS — so the table is server-only by construction. The secret key reaches the server through private runtimeConfig and never the client.

id / created_at; RLS on, no policy = service-key-only.

supabase/migrations/0001_create_runs.sql · 15 lines

supabase/migrations/0001_create_runs.sql15 lines · Transact-SQL

1-- runs: one row per game run — the server-side fact a run id anchors to.
2--
3-- Cost-per-run stays a projection of the [ai] telemetry, not a column here; this
4-- table records a run's existence (and, later, its lifecycle and the balance it
5-- spends). The server mints the id and inserts via the service (secret) key.
6--
7-- RLS is on with NO policy on purpose: the anon/publishable key can touch
8-- nothing, while the service/secret key bypasses RLS — exactly the server-only
9-- access the run store needs.
10create table if not exists public.runs (
11    id         uuid        primary key,
12    created_at timestamptz not null default now()
13);
14 
15alter table public.runs enable row level security;

Supabase creds as private (server-only) runtimeConfig; absent → in-memory.

nuxt.config.ts · 48 lines

nuxt.config.ts48 lines · TypeScript

⋯ 29 lines hidden (lines 1–29)1/**
* Nuxt 3 Configuration
* https://nuxt.com/docs/api/configuration/nuxt-config
*/
5export default defineNuxtConfig({
// Ensure compatibility with modern Nuxt features
compatibilityDate: '2025-05-15',
8 
// Enable devtools for development
devtools: { enabled: true },
11 
// Register required modules
modules: ['@nuxt/ui', '@pinia/nuxt'],
14 
// Global CSS imports
css: ['~/assets/css/main.css'],
17 
// Color mode (via @nuxtjs/color-mode, bundled with @nuxt/ui). classSuffix '' so the
// class on <html> is exactly `dark` / `light` — what the .dark token block and
// Tailwind's dark: variant key off. Defaulting to `system` respects the OS pref, and
// the module's inline no-flash script + cookie persistence replace the old manual
// classList toggle (which didn't persist and could FOUC).
colorMode: {
  classSuffix: '',
  preference: 'system',
  fallback: 'light'
},
28 
// Runtime configuration
runtimeConfig: {
  // Private keys (only available on server-side)
  openaiApiKey: process.env.OPENAI_API_KEY,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  // Supabase — the run store (server-side only). Absent → in-memory dev store.
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseSecretKey: process.env.SUPABASE_SECRET_KEY,
  // Public keys (exposed to client-side)
  public: {}
},
⋯ 9 lines hidden (lines 40–48)40 
// The standalone agents/ tooling package has its own deps + tsconfig; keep it
// out of the app's type program so `nuxt typecheck` never compiles the loops.
typescript: {
  tsConfig: {
    exclude: ['../agents']
  }
}
48})