Save completed runs to the account — a code-level reading (PR #100)

What changed, and why

A run in Revisionist is entirely client-side. The objective, the five dispatches, the timeline ledger, the Chronicle epilogue, and the win/loss verdict all live in the Pinia store and vanish on reload. The only database write today is a billing row that records a run existed so a credit can be charged; it never stores what happened.

This change persists a finished run's end-state to Supabase when the game ends, owns it by the player's account subject, and adds a read-only "your runs" view to revisit any past run. The record is designed for the later (separate) share feature: a stable run id, an immutable versioned snapshot, ownership by subject — so sharing becomes a thin read-only view, not a rebuild.

The pieces, in reading order: the versioned contract that defines the saved shape, the boundary validator that bounds an untrusted save, the migration and the store that hold it, the three routes, the save hook on game end, the read-only view, and the one linking decision the issue left open.

The versioned contract

A snapshot is a flat, fully JSON-native projection of the run's end-state. It is a SNAPSHOT, not a live record: in-progress save/resume is out of scope; a run is short (five messages) and persists at the end. The version field is the load- bearing decision — a reader can branch on it to migrate an older shape rather than mis-read it, so a later change can't silently break runs already saved.

This module is the shared half of the contract: types plus the version constant, and nothing else. It carries only type-only imports, so the client store can import the version and the types without dragging any server-only code into the browser bundle.

The version stamp and the full RunSnapshot shape (composed from the existing game types).

utils/run-snapshot.ts · 108 lines

utils/run-snapshot.ts108 lines · TypeScript

⋯ 29 lines hidden (lines 1–29)1/**
2 * The saved-run contract — the immutable, versioned record of a finished run.
3 *
4 * A run is otherwise client-only: the objective, the dispatches, the timeline
5 * ledger, the Chronicle epilogue, and the verdict all live in the Pinia store and
6 * evaporate on reload. This is the persisted form of that end-state: the store builds
7 * it on game end, the server stores it keyed by the run id, and a read-only "your
8 * runs" view replays it. It is a SNAPSHOT, not a live record — in-progress
9 * save/resume is out of scope; a run is short (five messages) and persists at the end.
10 *
11 * Naming: "run" is overloaded. The header gauge's balance ("runs remaining") is a
12 * purchasable CREDIT (the `balances` table); this is a PLAYED run (the game record,
13 * the `run_snapshots` table). Same noun, two states — kept distinct in the schema.
14 *
15 * The shape is VERSIONED (`version`) so a later change can't silently break runs
16 * saved under an older shape: a reader can branch on `version` and migrate. It is a
17 * flat, fully JSON-native projection of the store state — the `Date` timestamps on
18 * the in-memory ledger/thread are dropped (a snapshot needs none of the duration
19 * math), so the stored blob round-trips through jsonb cleanly.
20 *
21 * This module is the SHARED contract (types + version), client-safe by design: it
22 * carries no runtime imports, only type-only ones, so the client store can import the
23 * version + types without pulling any server-only code. The server-side boundary
24 * validator lives separately in `server/utils/run-snapshot.ts`.
25 */
26import type { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Anachronism } from '~/server/utils/anachronism'
29import type { GameObjective } from '~/server/utils/objectives'
30import type { ChronicleEntry } from '~/server/utils/openai'
31 
32/** The current saved-run shape. Bump when the shape changes incompatibly; a reader
33 *  branches on it to migrate older snapshots rather than mis-reading them. */
34export const RUN_SNAPSHOT_VERSION = 1
35 
36/** Only a finished run is ever saved — the two terminal verdicts. */
37export type RunOutcome = 'victory' | 'defeat'
38 
39/** The valence of a ledger swing (mirrors the store's `Valence`). */
40export type RunValence = 'positive' | 'negative' | 'neutral'
41 
42/** The five efficiency tiers a victory can earn (mirrors the store's rating). */
43export type EfficiencyRating = 'Legendary' | 'Excellent' | 'Great' | 'Good' | 'Standard'
44 
45/** The bit of a roll the read-only view shows: the number and its named outcome. */
46export interface RollMark {
⋯ 37 lines hidden (lines 47–83)47    diceRoll: number
48    diceOutcome: DiceOutcome
49}
50 
51/** A dispatch keepsake — the player's verbatim message and whom/when it reached. */
52export interface RunDispatch {
53    text: string
54    figure: string
55    era: string
56}
57 
58/** The victory efficiency block (null on defeat) — the same data the end screen shows. */
59export interface RunEfficiency {
60    messagesSaved: number
61    messagesUsed: number
62    efficiencyPercentage: number
63    efficiencyRating: EfficiencyRating
64    isEarlyVictory: boolean
65}
66 
67/** One ledger entry, trimmed to the fields a read-only run view renders (the live
68 *  `TimelineEvent` minus its `Date` timestamp and the internals the view ignores). */
69export interface RunLedgerEntry {
70    id: string
71    figureName: string
72    era: string
73    headline: string
74    detail: string
75    diceRoll: number
76    diceOutcome: DiceOutcome
77    progressChange: number
78    valence: RunValence
79    craft?: Craft
80    anachronism?: Anachronism
81}
82 
83/** The full saved run — everything a read-only view needs to replay the end screen. */
84export interface RunSnapshot {
85    version: number
86    runId: string
87    status: RunOutcome
88    objective: GameObjective
89    objectiveProgress: number
90    messagesUsed: number
91    totalMessages: number
92    bestRoll: RollMark | null
93    worstRoll: RollMark | null
94    efficiency: RunEfficiency | null
95    dispatches: RunDispatch[]
96    timeline: RunLedgerEntry[]
97    chronicle: ChronicleEntry | null
98}
99 
100/** The list projection — what the "your runs" list shows per run, without pulling
⋯ 8 lines hidden (lines 101–108)101 *  the full snapshot blob for every row. */
102export interface RunSummary {
103    runId: string
104    status: RunOutcome
105    title: string
106    progress: number
107    createdAt: string
108}

Bounding an untrusted save

The save endpoint is a public POST, so its body is untrusted. sanitizeSnapshot is the gate: it coerces an arbitrary body into a valid snapshot or returns null, using the same cleanString / cleanArray / clampInt helpers every other route uses. It rejects a run that isn't terminal or has no objective / run id (there is nothing meaningful to persist), bounds every string and number, and — critically — stamps the server's own version rather than trusting the client's.

The gate (terminal status, run id, objective) and the assembled result with the server-owned version.

server/utils/run-snapshot.ts · 165 lines

server/utils/run-snapshot.ts165 lines · TypeScript

⋯ 63 lines hidden (lines 1–63)1/**
* Server-side boundary validation for a saved run snapshot.
*
* The shared CONTRACT (types + version) lives in `~/utils/run-snapshot` so both the
* client store and the server can import it without pulling server-only code into the
* client bundle. This module is the server-only half: it coerces an untrusted POST
* body into a valid RunSnapshot (a direct POST can send anything), bounding every
* field with the same cleanString/cleanArray/clampInt helpers the other routes use.
*/
10import { cleanString, cleanArray, clampInt } from './validate'
11import {
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_LEDGER_DETAIL_CHARS,
  MAX_TIMELINE_ENTRIES,
  MAX_HISTORY_ENTRIES,
  MAX_LEDGER_SWING
20} from './validate'
21import { sanitizeRunId } from './run-context'
22import { TOTAL_MESSAGES } from '~/utils/game-config'
23import {
  RUN_SNAPSHOT_VERSION,
  type RunSnapshot,
  type RunOutcome,
  type RunValence,
  type RunEfficiency,
  type RunDispatch,
  type RunLedgerEntry,
  type RollMark,
  type EfficiencyRating
33} from '~/utils/run-snapshot'
34import type { DiceOutcome } from '~/utils/dice'
35import type { Craft } from '~/utils/craft'
36import type { Anachronism } from '~/server/utils/anachronism'
37import type { GameObjective } from '~/server/utils/objectives'
38import type { ChronicleEntry } from '~/server/utils/openai'
39 
40// Caps specific to a snapshot's own fields (the shared input caps live in validate.ts).
41const MAX_DISPATCH_CHARS = 320
42const MAX_HEADLINE_CHARS = 200
43const MAX_ICON_CHARS = 16
44const MAX_OUTCOME_CHARS = 24
45const MAX_RATING_CHARS = 24
46const MAX_HINT_CHARS = 24
47const MAX_ID_CHARS = 64
48const MAX_TOTAL_MESSAGES = 20
49const MAX_DICE = 40
50 
51const VALENCES: RunValence[] = ['positive', 'negative', 'neutral']
52const coerceValence = (v: unknown): RunValence =>
  VALENCES.includes(v as RunValence) ? (v as RunValence) : 'neutral'
54 
55const clampNonNeg = (n: number): number => Math.max(0, n)
56 
57const cleanRoll = (v: unknown): RollMark | null => {
  if (!v || typeof v !== 'object') return null
  const m = v as Record<string, unknown>
  const diceOutcome = cleanString(m.diceOutcome, MAX_OUTCOME_CHARS)
  if (!diceOutcome) return null
  return { diceRoll: clampNonNeg(clampInt(m.diceRoll, MAX_DICE)), diceOutcome: diceOutcome as DiceOutcome }
63}
64 
65/**
* Coerce an untrusted body into a valid RunSnapshot, or null when it isn't a
* completed run we can save. Bounds every field, and stamps the server's own
* `version` rather than trusting the client's. Returns null when the run isn't
* terminal or has no objective / run id — there is nothing meaningful to persist then.
*/
71export function sanitizeSnapshot(raw: unknown): RunSnapshot | null {
  if (!raw || typeof raw !== 'object') return null
  const r = raw as Record<string, unknown>
74 
  const status: RunOutcome | null =
      r.status === 'victory' || r.status === 'defeat' ? r.status : null
  if (!status) return null
78 
  const runId = sanitizeRunId(r.runId)
  if (!runId) return null
81 
  if (!r.objective || typeof r.objective !== 'object') return null
  const o = r.objective as Record<string, unknown>
  const objective: GameObjective = {
      title: cleanString(o.title, MAX_OBJECTIVE_TITLE_CHARS),
      description: cleanString(o.description, MAX_OBJECTIVE_DESC_CHARS),
      era: cleanString(o.era, MAX_ERA_CHARS),
      icon: cleanString(o.icon, MAX_ICON_CHARS)
  }
  if (typeof o.anchorYear === 'number' && Number.isFinite(o.anchorYear)) {
⋯ 58 lines hidden (lines 91–148)91        objective.anchorYear = Math.round(o.anchorYear)
  }
93 
  const totalMessages = clampNonNeg(clampInt(r.totalMessages, MAX_TOTAL_MESSAGES)) || TOTAL_MESSAGES
  const messagesUsed = Math.min(totalMessages, clampNonNeg(clampInt(r.messagesUsed, MAX_TOTAL_MESSAGES)))
96 
  let efficiency: RunEfficiency | null = null
  if (r.efficiency && typeof r.efficiency === 'object') {
      const e = r.efficiency as Record<string, unknown>
      efficiency = {
          messagesSaved: clampNonNeg(clampInt(e.messagesSaved, MAX_TOTAL_MESSAGES)),
          messagesUsed: clampNonNeg(clampInt(e.messagesUsed, MAX_TOTAL_MESSAGES)),
          efficiencyPercentage: clampNonNeg(clampInt(e.efficiencyPercentage, 100)),
          efficiencyRating: (cleanString(e.efficiencyRating, MAX_RATING_CHARS) || 'Standard') as EfficiencyRating,
          isEarlyVictory: e.isEarlyVictory === true
      }
  }
108 
  const dispatches: RunDispatch[] = cleanArray(r.dispatches, MAX_HISTORY_ENTRIES).map((raw) => {
      const d = (raw ?? {}) as Record<string, unknown>
      return {
          text: cleanString(d.text, MAX_DISPATCH_CHARS),
          figure: cleanString(d.figure, MAX_FIGURE_NAME_CHARS),
          era: cleanString(d.era, MAX_ERA_CHARS)
      }
  })
117 
  const timeline: RunLedgerEntry[] = cleanArray(r.timeline, MAX_TIMELINE_ENTRIES).map((raw) => {
      const t = (raw ?? {}) as Record<string, unknown>
      const entry: RunLedgerEntry = {
          id: cleanString(t.id, MAX_ID_CHARS),
          figureName: cleanString(t.figureName, MAX_FIGURE_NAME_CHARS),
          era: cleanString(t.era, MAX_ERA_CHARS),
          headline: cleanString(t.headline, MAX_HEADLINE_CHARS),
          detail: cleanString(t.detail, MAX_LEDGER_DETAIL_CHARS),
          diceRoll: clampNonNeg(clampInt(t.diceRoll, MAX_DICE)),
          diceOutcome: cleanString(t.diceOutcome, MAX_OUTCOME_CHARS) as DiceOutcome,
          progressChange: clampInt(t.progressChange, MAX_LEDGER_SWING),
          valence: coerceValence(t.valence)
      }
      const craft = cleanString(t.craft, MAX_HINT_CHARS)
      if (craft) entry.craft = craft as Craft
      const anachronism = cleanString(t.anachronism, MAX_HINT_CHARS)
      if (anachronism) entry.anachronism = anachronism as Anachronism
      return entry
  })
137 
  let chronicle: ChronicleEntry | null = null
  if (r.chronicle && typeof r.chronicle === 'object') {
      const c = r.chronicle as Record<string, unknown>
      chronicle = {
          title: cleanString(c.title, MAX_HEADLINE_CHARS),
          paragraphs: cleanArray(c.paragraphs, MAX_HISTORY_ENTRIES)
              .map((p) => cleanString(p, MAX_OBJECTIVE_DESC_CHARS))
              .filter(Boolean)
      }
  }
148 
  return {
      // The server owns the version stamp — never trust the client's.
      version: RUN_SNAPSHOT_VERSION,
      runId,
      status,
      objective,
      objectiveProgress: clampNonNeg(clampInt(r.objectiveProgress, 100)),
      messagesUsed,
      totalMessages,
      bestRoll: cleanRoll(r.bestRoll),
      worstRoll: cleanRoll(r.worstRoll),
      efficiency,
      dispatches,
      timeline,
      chronicle
  }
165}

The schema

The migration adds a run_snapshots table keyed one-to-one to the run id, with the full snapshot as versioned jsonb plus a few denormalized columns (status, title, progress) so the list view need not parse every blob. It also adds a user_id owner column to the billing runs row. Like every existing table, RLS is on with no policy: the table is service-key only, unreachable by the public client.

Naming stays careful: the header gauge's "runs remaining" is a purchasable credit (the balances table); this is a played run (the game record). Same noun, two states, kept distinct in the schema.

The table, its owner/list columns, and the (user_id, created_at) index for the list query.

supabase/migrations/0005_run_snapshots.sql · 32 lines

supabase/migrations/0005_run_snapshots.sql32 lines · Transact-SQL

⋯ 10 lines hidden (lines 1–10)1-- run_snapshots: the saved, immutable end-of-run game record — objective, ledger,
2-- dispatches, Chronicle epilogue, and verdict — owned by the player's account
3-- subject. This is the PLAYED run (the game record), distinct from the billing
4-- `runs` row, which records a run's existence + charge. The record is versioned
5-- jsonb so a later shape change can't break old runs; a few columns are
6-- denormalized so the "your runs" list need not parse every blob.
7-- RLS on with no policy: service-key-only, like runs.
8 
9-- Own a run by account subject (the Supabase user id, else the device id) — the
10-- same subject balances/runs already key on. Distinct from device_id/charged_at
11-- (the billing-side charge stamps); set when the completed run is saved. An
12-- anonymous user owns their runs from turn one, and a new-account sign-in keeps the
13-- same id, so those runs carry over for free.
14alter table public.runs add column if not exists user_id text;
15 
16create table if not exists public.run_snapshots (
17    run_id     uuid        primary key references public.runs(id) on delete cascade,
18    user_id    text        not null,
19    version    int         not null,
20    status     text        not null,
21    title      text        not null,
22    progress   int         not null,
23    data       jsonb       not null,
24    created_at timestamptz not null default now()
25);
26 
27alter table public.run_snapshots enable row level security;
28 
29-- The "your runs" list reads a subject's runs newest-first; index that access path
30-- so it doesn't sequentially scan every saved run.
31create index if not exists run_snapshots_user_idx
⋯ 1 line hidden (lines 32–32)32    on public.run_snapshots (user_id, created_at desc);

The store: one port, two adapters

Persistence follows the repo's established idiom (see run-store / balance-store): a port interface, an in-memory adapter as the dependency-free default, a Supabase adapter when configured, and a memoized factory chosen by supabaseConfig(). Every method is keyed by the account subject. The save stamps the owner onto the billing runs row too, then upserts the snapshot on the run-id primary key — so the second (post-epilogue) save overwrites the first instead of erroring.

The port, the Supabase save (owner stamp + idempotent upsert), and the config-driven factory.

server/utils/run-snapshot-store.ts · 151 lines

server/utils/run-snapshot-store.ts151 lines · TypeScript

⋯ 24 lines hidden (lines 1–24)1/**
* The run-snapshot store — where a finished run becomes a durable, owned record.
* POST /api/run-save writes the snapshot here keyed by the run id; the "your runs"
* routes (GET /api/runs, GET /api/runs/:id) read it back, scoped to the account
* subject so a player only ever sees their own runs.
*
* Two adapters behind one port, chosen by config — the repo's env-degradation idiom
* (cf. runStore, balanceStore):
*   - in-memory (default): no external dependency, so `npm run dev` and the unit
*     tests need nothing. History doesn't outlive the process, but the round-trip is
*     real, which is what the save -> list -> load test exercises.
*   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured. Writes
*     the `run_snapshots` row (and stamps the owner onto the billing `runs` row) via
*     the service (secret) key, which bypasses RLS — the table has no public policy,
*     so it is server-only.
*
* Ownership is by SUBJECT (the Supabase user id, falling back to the device id) — the
* same string balances/runs key on. Reads filter by it, so a non-owned run id reads
* as absent (the route turns that into a 404, never leaking another subject's run).
*/
21import { createClient, type SupabaseClient } from '@supabase/supabase-js'
22import { supabaseConfig } from './supabase'
23import type { RunSnapshot, RunSummary } from '~/utils/run-snapshot'
24 
25export interface RunSnapshotStore {
  /** Persist (or overwrite) the finished run's snapshot, owned by `subject`. */
  saveRun(subject: string, snapshot: RunSnapshot): Promise<void>
  /** A subject's saved runs, newest first (the list projection). */
  listRuns(subject: string): Promise<RunSummary[]>
  /** One saved run by id, only if `subject` owns it; null otherwise. */
  getRun(subject: string, runId: string): Promise<RunSnapshot | null>
32}
⋯ 49 lines hidden (lines 33–81)33 
34/** Project a snapshot down to the list row. */
35function toSummary(snapshot: RunSnapshot, createdAt: string): RunSummary {
  return {
      runId: snapshot.runId,
      status: snapshot.status,
      title: snapshot.objective.title,
      progress: snapshot.objectiveProgress,
      createdAt
  }
43}
44 
45/** Dev/test default — keeps the round-trip real (save -> list -> load) without any
*  external dependency. Not durable across process restarts; the Supabase adapter is
*  the one that actually preserves history. */
48export class InMemoryRunSnapshotStore implements RunSnapshotStore {
  private readonly runs: Array<{ subject: string; snapshot: RunSnapshot; createdAt: string }> = []
50 
  async saveRun(subject: string, snapshot: RunSnapshot): Promise<void> {
      const createdAt = new Date().toISOString()
      const existing = this.runs.find((r) => r.snapshot.runId === snapshot.runId)
      if (existing) {
          // Snapshots are immutable, but the save fires again once the epilogue
          // lands — overwrite in place (keep the original position/createdAt).
          existing.subject = subject
          existing.snapshot = snapshot
          return
      }
      this.runs.push({ subject, snapshot, createdAt })
  }
63 
  async listRuns(subject: string): Promise<RunSummary[]> {
      return this.runs
          .filter((r) => r.subject === subject)
          .map((r) => toSummary(r.snapshot, r.createdAt))
          .reverse()
  }
70 
  async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      return found ? found.snapshot : null
  }
75}
76 
77/** Records each saved run as a `run_snapshots` row via the service (secret) key,
*  which bypasses RLS — the table has no public policy, so it is server-only. */
79export class SupabaseRunSnapshotStore implements RunSnapshotStore {
  constructor(private readonly client: SupabaseClient) {}
81 
  async saveRun(subject: string, snapshot: RunSnapshot): Promise<void> {
      // Stamp the owner onto the billing run row too (it carries only device_id
      // today) so a run's ownership is legible from either table.
      const owned = await this.client.from('runs').update({ user_id: subject }).eq('id', snapshot.runId)
      if (owned.error) throw new Error(`runs owner update failed: ${owned.error.message}`)
87 
      // Upsert on the run-id PK so the second (post-epilogue) save overwrites the
      // first rather than erroring — the snapshot is immutable, the write is not.
      const { error } = await this.client.from('run_snapshots').upsert({
          run_id: snapshot.runId,
          user_id: subject,
          version: snapshot.version,
          status: snapshot.status,
          title: snapshot.objective.title,
          progress: snapshot.objectiveProgress,
          data: snapshot
      })
      if (error) throw new Error(`run_snapshots upsert failed: ${error.message}`)
  }
⋯ 37 lines hidden (lines 101–137)101 
  async listRuns(subject: string): Promise<RunSummary[]> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('run_id, status, title, progress, created_at')
          .eq('user_id', subject)
          .order('created_at', { ascending: false })
      if (error) throw new Error(`run_snapshots list failed: ${error.message}`)
      return ((data ?? []) as Array<{
          run_id: string
          status: RunSnapshot['status']
          title: string
          progress: number
          created_at: string
      }>).map((row) => ({
          runId: row.run_id,
          status: row.status,
          title: row.title,
          progress: row.progress,
          createdAt: row.created_at
      }))
  }
123 
  async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('data')
          .eq('run_id', runId)
          .eq('user_id', subject)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots get failed: ${error.message}`)
      return (data?.data ?? null) as RunSnapshot | null
  }
134}
135 
136let cached: RunSnapshotStore | null = null
137 
138/** The configured run-snapshot store (memoized — reuses one Supabase client). */
139export function runSnapshotStore(): RunSnapshotStore {
  if (cached) return cached
  const cfg = supabaseConfig()
  cached = cfg
      ? new SupabaseRunSnapshotStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
      : new InMemoryRunSnapshotStore()
  return cached
146}
147 
148/** Test seam: clear the memoized store so the next call re-reads config. */
149export function resetRunSnapshotStore(): void {
  cached = null
151}

The routes: write once, read scoped

Three thin handlers. POST /api/run-save validates the body, skips a degraded (non-uuid, never-recorded) run as a no-op, resolves the subject, and saves — all best-effort, since the client fires it without blocking the end screen. The two read routes resolve the subject server-side and scope every query to it.

The detail route answers 404 — never 403 — on an id the subject doesn't own. A 403 would confirm the id exists; a 404 leaks nothing. The id is uuid-shape-gated before any query, so a malformed param never reaches the database.

Validate → skip degraded → save, best-effort with a 500 only on a store failure.

server/api/run-save.post.ts · 36 lines

server/api/run-save.post.ts36 lines · TypeScript

1/**
* POST /api/run-save — persist a finished run's snapshot, owned by the account
* subject. The client posts the end-of-run snapshot on victory/defeat; the server
* validates it, then stores it keyed by the run id so it survives reload and seeds
* the read-only "your runs" view.
*
* Best-effort by design: the client fires this without blocking the end screen, so a
* failure here degrades history, never the game. A degraded run (a non-uuid local id,
* never recorded server-side) has nothing to own — it's accepted as a no-op.
*/
11import { sanitizeSnapshot } from '~/server/utils/run-snapshot'
12import { runSnapshotStore } from '~/server/utils/run-snapshot-store'
13import { currentSubject } from '~/server/utils/auth'
14import { isUuid } from '~/server/utils/uuid'
15 
16export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
  const snapshot = sanitizeSnapshot(await readBody(event))
  if (!snapshot) {
      throw createError({ statusCode: 400, statusMessage: 'Bad Request: invalid run snapshot' })
  }
  // A degraded (non-uuid local) run was never recorded server-side — nothing to own.
  if (!isUuid(snapshot.runId)) {
      return { saved: false, degraded: true }
  }
  const subject = await currentSubject(event)
  try {
      await runSnapshotStore().saveRun(subject, snapshot)
  } catch (error) {
      console.error('Failed to save run snapshot:', error)
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
  return { saved: true }
36})

Shape-gate the id, scope to the subject, 404 on a non-owned or unknown run.

server/api/runs/[id].get.ts · 22 lines

server/api/runs/[id].get.ts22 lines · TypeScript

1/**
2 * GET /api/runs/:id — one saved run, read-only, only if the current subject owns it.
3 * The store filters by subject, so a non-owned (or unknown) id reads as absent and we
4 * answer 404 — never 403 — so the endpoint doesn't leak which run ids exist. The id
5 * is uuid-shape-gated before any query so a malformed param never hits the DB.
6 */
7import { currentSubject } from '~/server/utils/auth'
8import { isUuid } from '~/server/utils/uuid'
9import { runSnapshotStore } from '~/server/utils/run-snapshot-store'
10 
11export default defineEventHandler(async (event) => {
12    const id = getRouterParam(event, 'id') ?? ''
13    if (!isUuid(id)) {
14        throw createError({ statusCode: 404, statusMessage: 'Not Found' })
15    }
16    const subject = await currentSubject(event)
17    const run = await runSnapshotStore().getRun(subject, id)
18    if (!run) {
19        throw createError({ statusCode: 404, statusMessage: 'Not Found' })
20    }
21    return { run }
22})

Saving on game end

The store builds the snapshot from exactly what the end screen shows — objective, verdict, ledger, dispatches, rolls, and the Chronicle epilogue — reusing the run id already minted for the run. The ledger is mapped to drop its in-memory Date timestamps (a snapshot needs none of the duration math). It fires only for a completed, server-backed run, and a failure is swallowed: persisting the run is a nicety that must never disturb the end screen.

The hook sits in sendMessage's tail, beside the existing chronicle refresh. The run is saved immediately (so it survives even if the epilogue refresh fails), then again once that refresh lands — the idempotent upsert lets the second write capture the final telling.

The game-end hook, the action's guards, and the snapshot it builds and posts.

stores/game.ts · 1377 lines

stores/game.ts1377 lines · TypeScript

⋯ 1067 lines hidden (lines 1–1067)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, type RunSnapshot } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* 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.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* 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.
*/
38export 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
62}
63 
64/**
* 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.
*/
69export 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
  /** Whether the dispatch built on the run's thread (issue #62) — drives the
   *  momentum meter and the 'builds' badge in the reveal. */
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  /** The PRE-turn momentum that amplified this swing — for the reveal's equation. */
  momentumAtSwing?: 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
98}
99 
100export type GameStatus = 'playing' | 'victory' | 'defeat'
101 
102/**
* 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.
*/
109type 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
          continuity?: Continuity
          momentum?: number
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              momentumAtSwing?: 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
      }
  }
157 
158const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
159 
160// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
161// suspense, then the die lands and the figure's reply writes itself in, then the
162// timeline shift, then the ledger node — so the resolution reads as one conducted
163// moment instead of everything firing in the same tick. Each component already
164// animates when its own slice of state changes; sequencing the WRITES sequences the
165// animations, with no component coordination. Tuned so the swing lands with the
166// reply's own "ripple" line (~0.55s into its staged reveal).
167export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
168const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
169/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
172function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
176}
177 
178function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
182}
183 
184/** Formats a signed timeline year (AD positive, BCE negative) for display. */
185export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
187}
188 
189/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function 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
194}
195 
196/** 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. */
198function 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
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* Game Store — core state for a session of freeform timeline editing.
*/
215export 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 run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 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
  }),
307 
  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
      },
319 
      /**
       * 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'
          )
      },
330 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
335 
      /**
       * Whether the active figure can be reached at the chosen `when`.
       *
       * Require grounding (#73): an UNRESOLVED name can't be reached at all —
       * 'unresolved' (free-form contact is removed; the picker guides you to a real
       * match). Deceased-only floor (#72): a RESOLVED figure with no confirmed
       * death is living/undatable and never contactable — 'living', fail closed. A
       * resolved, deceased figure is gated to their lifetime (before-birth /
       * after-death). 'unknown' remains only for a resolved, deceased figure we
       * can't fully place (no birth year, or no contact year chosen yet), which
       * stays permissible.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved) return 'unresolved'
          if (!g.died) return 'living'
          if (!g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          if (this.contactWhen > g.died.signed) return 'after-death'
          return 'ok'
      },
357 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
362 
      /**
       * 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
      },
374 
      /**
       * 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 (a resolved figure we can't date, or before a year is chosen). 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
      },
390 
      /**
       * 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)
      }
  },
406 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
418 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
427 
      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,
              continuity: messageData.continuity,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              momentumAtSwing: messageData.momentumAtSwing,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
451 
      // ---------- 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 })
          }
      },
462 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
466 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch is gated as ungrounded (#73)
       * 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
      },
484 
      /**
       * 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; an ungrounded contact is then blocked (#73).
       */
      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
          }
      },
532 
      /** The current run's id, minted server-side via POST /api/run on first
       *  need. The run is a server fact (a persisted, charged row); the id then
       *  tags every AI call so cost telemetry groups per run, and the gameplay
       *  gate verifies it. Fails CLOSED: if begin-run can't return an id this
       *  REJECTS (no local fallback) — a run we can't back server-side must not
       *  start, or the paywall gate would reject it mid-run anyway. */
      async ensureRunId(): Promise<string> {
          if (this.runId) return this.runId
          // Collapse concurrent first-calls onto ONE begin-run (two overlapping
          // calls would otherwise mint two rows). The epoch guards a resetGame
          // mid-flight — a dead run's id must not become the fresh run's.
          if (!this.runIdInflight) {
              const epoch = this.runEpoch
              this.runIdInflight = (async () => {
                  const res = await $fetch('/api/run', { method: 'POST' }) as { runId?: string }
                  if (!res?.runId) throw new Error('begin-run returned no run id')
                  if (epoch === this.runEpoch) {
                      this.runId = res.runId
                      this.runIdInflight = null
                  }
                  return res.runId
              })().catch((err) => {
                  if (epoch === this.runEpoch) this.runIdInflight = null
                  throw err
              })
          }
          return this.runIdInflight
      },
561 
      /** 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() }
      },
567 
      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
      },
573 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
577 
      /**
       * 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
594 
          // 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
          }
      },
631 
      /**
       * 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
          }
      },
665 
      /**
       * 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
679 
          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
          }
      },
712 
      // ---------- 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()
          })
      },
736 
      // ---------- 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
          }
      },
785 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
791 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
798 
      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)
      },
806 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
811 
      /**
       * 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
              }
          }
      },
828 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
832 
      /**
       * 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'
          }
      },
848 
      // ---------- 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
866 
          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 === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
894 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
902 
          // 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
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
915 
          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,
                      // The pre-turn momentum the server amplifies the swing by, and
                      // returns advanced (the client stays the system of record).
                      momentum: this.momentum,
                      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)
                  }
              })
951 
              if (epoch !== this.runEpoch) return false
953 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
956 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
964 
                  // ---- conducted reveal ----
                  // A beat of suspense (the die keeps shaking) before the result
                  // lands, so the resolution has a moment of anticipation.
                  if (animate) {
                      await wait(REVEAL.suspense)
                      if (epoch !== this.runEpoch) return false
                  }
972 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  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,
                      continuity: response.data.continuity,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      momentumAtSwing: timeline?.momentumAtSwing,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
999 
                  if (timeline) {
                      // Beat 2 — the timeline shift (the % gauge flies its delta),
                      // timed to land with the reply's own "ripple" line.
                      if (animate) {
                          await wait(REVEAL.swing)
                          if (epoch !== this.runEpoch) return false
                      }
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
                      // The arc meter is server-authoritative for the result; advance
                      // it WITH the swing it amplified — and only past the epoch check
                      // above, so a stale turn never moves the meter (issue #62).
                      this.momentum = response.data.momentum ?? this.momentum
1016 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      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
                      })
                      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()
              }
          }
1067 
          // 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).
          let refresh: Promise<void> | null = null
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              refresh = this.refreshChronicle()
              void refresh
          }
          // The run just ended: persist it (best-effort) so it survives reload, then
          // re-save once the epilogue's telling lands — the immediate save guards
          // against that refresh failing, the second captures the final Chronicle.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
          }
          return resolved
⋯ 183 lines hidden (lines 1085–1267)1085        },
1086 
      /**
       * 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 server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.momentum = 0
          this.error = null
          return true
      },
1139 
      /**
       * 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). An optional steer (era + theme, closed enums) biases
       * the composition; the server re-validates it against the enums, so a bad
       * value is harmless. Returns null rather than throwing if composing fails,
       * so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(steer: ObjectiveSteer = {}): Promise<GameObjective | null> {
          try {
              const query: Record<string, string> = {}
              if (steer.era) query.era = steer.era
              if (steer.theme) query.theme = steer.theme
              const res = await $fetch('/api/objective', { method: 'GET', query, 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
          }
      },
1164 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1182 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1188 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1193 
      /** Records the Stripe-return outcome and refreshes the balance on success
       *  (the webhook credits asynchronously; re-read so the gauge reflects it). */
      async notePurchaseReturn(outcome: 'success' | 'cancel'): Promise<void> {
          this.purchaseNotice = outcome
          this.buyModalOpen = false
          if (outcome === 'success') {
              this.outOfRuns = false
              await this.loadBalance()
          }
      },
1204 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1209 
      /** Loads the run-pack catalog for the paywall. Caches only a NON-empty
       *  result: a transient empty/failed read must not poison the cache and
       *  strand the modal with zero packs for the rest of the session. */
      async loadPacks(): Promise<void> {
          if (this.packs.length) return
          try {
              const res = await $fetch('/api/packs') as { packs?: Pack[] }
              const packs = res?.packs ?? []
              if (packs.length) this.packs = packs
          } catch (error) {
              console.error('Failed to load packs:', error)
          }
      },
1223 
      /** Starts checkout for a pack; returns the Stripe Checkout URL to redirect
       *  to (null on failure). The caller does the redirect. */
      async buyPack(packId: string): Promise<string | null> {
          try {
              const res = await $fetch('/api/checkout', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { packId }
              }) as { url?: string }
              return res?.url ?? null
          } catch (error) {
              console.error('Failed to start checkout:', error)
              return null
          }
      },
1239 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1245 
              const efficiencyRating = rateEfficiency(messagesSaved)
1247 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1258 
      /**
       * Persist the finished run's snapshot to the player's account, best-effort.
       * Captures exactly what the end screen shows — objective, verdict, ledger,
       * dispatches, rolls, and the Chronicle epilogue — keyed by the run id, so the
       * run survives reload and feeds the read-only "your runs" view. Fires and
       * forgets like refreshChronicle: a save failure must never disturb the end
       * screen. Only a completed (victory/defeat), server-backed (uuid run id) run
       * is saved; a degraded local id is dropped server-side.
       */
      async saveRunSnapshot(): Promise<void> {
          const epoch = this.runEpoch
          const status = this.gameStatus
          if (status !== 'victory' && status !== 'defeat') return
          const objective = this.currentObjective
          const runId = this.runId
          if (!objective || !runId) return
⋯ 17 lines hidden (lines 1275–1291)1275 
          const summary = this.gameSummary
          const events = this.timelineEvents
          // The dispatch keepsake — the player's verbatim messages, paired with
          // whom/when they reached (the same zip the end screen renders).
          const dispatches = this.messageHistory
              .filter((m) => m.sender === 'user')
              .map((m, i) => ({
                  text: m.text,
                  figure: m.figureName || events[i]?.figureName || 'the past',
                  era: events[i]?.era || ''
              }))
          const mark = (m: typeof summary.bestRoll) =>
              m && m.diceRoll != null && m.diceOutcome != null
                  ? { diceRoll: m.diceRoll, diceOutcome: m.diceOutcome }
                  : null
1291 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism
              })),
              chronicle: this.chronicle
          }
1319 
          try {
              await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: snapshot
              })
          } catch (error) {
              // Saving the run is a nicety; a failure must not break the end screen.
              if (epoch === this.runEpoch) console.error('Could not save the run:', error)
          }
⋯ 48 lines hidden (lines 1330–1377)1330        },
1331 
      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 / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.momentum = 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
      }
  }
1377})

Replaying a finished run, read-only

RunView renders a saved run from the snapshot alone — no store, no AI, no controls. It deliberately reuses EndGameScreen's verdict strings, glyphs, and design tokens, so a past run reads exactly as it did the moment it ended. The /runs list and /runs/:id pages are thin useFetch wrappers around the read routes; an entry point sits in the account popover. This component is also the seam the later share feature reuses: give it a snapshot, it draws the run.

The verdict masthead bound to the snapshot, and the prop-only script — no store.

components/RunView.vue · 114 lines

components/RunView.vue114 lines · Vue

⋯ 5 lines hidden (lines 1–5)1<template>
<!-- A finished run, read-only — the same verdict / epilogue / ledger the end screen
     shows, but rendered from a saved snapshot rather than the live store, so a past
     run reads identically to the moment it ended. Verdict strings, glyphs, and the
     rv-* tokens are deliberately the same as EndGameScreen's. -->
<div data-testid="run-view" class="run-view" :class="isVictory ? 'run--win' : 'run--loss'">
  <!-- Verdict masthead -->
  <div class="text-center border-b rv-line pb-6">
    <div class="verdict-seal" :class="isVictory ? 'is-win' : 'is-loss'" aria-hidden="true">{{ isVictory ? '✦' : '⊘' }}</div>
    <h2 v-if="isVictory" data-testid="run-verdict" class="rv-serif text-3xl sm:text-4xl font-bold rv-fg mt-3">History Rewritten</h2>
    <h2 v-else data-testid="run-verdict" class="rv-serif text-3xl sm:text-4xl font-bold rv-muted mt-3">The Timeline Held</h2>
    <p class="text-sm mt-2.5 flex items-center justify-center gap-2 flex-wrap">
      <span class="rv-muted inline-flex items-center gap-1.5">
        <span aria-hidden="true">{{ snapshot.objective.icon }}</span>
        <strong data-testid="run-objective-title" class="font-semibold">{{ snapshot.objective.title || 'Historical Mission' }}</strong>
      </span>
      <span class="rv-hair-c" aria-hidden="true">·</span>
      <span class="rv-mono font-bold" :class="isVictory ? 'rv-ok' : 'rv-bad'">
        <span data-testid="run-progress">{{ snapshot.objectiveProgress }}%</span> rewritten
      </span>
    </p>
22 
    <div v-if="snapshot.efficiency" data-testid="run-efficiency" class="mt-3 rv-mono text-sm">
⋯ 72 lines hidden (lines 24–95)24        <span class="rv-ok font-semibold">{{ victoryPhrase }}</span>
      <span class="rv-muted"> · {{ snapshot.efficiency.messagesUsed }}/{{ snapshot.totalMessages }} used<span v-if="snapshot.efficiency.messagesSaved > 0"> · {{ snapshot.efficiency.messagesSaved }} saved</span></span>
      <span v-if="snapshot.efficiency.isEarlyVictory" class="rv-ok"> · 🌟 to spare</span>
    </div>
  </div>
29 
  <!-- The Chronicle's final telling — the epilogue -->
  <div v-if="snapshot.chronicle" data-testid="run-chronicle" class="mt-6">
    <span class="rv-label rv-label--rule"><span aria-hidden="true">📖</span> The Chronicle</span>
    <article class="max-w-[62ch]">
      <h4 data-testid="run-chronicle-title" class="rv-serif text-xl font-semibold rv-fg mb-2.5 leading-tight">{{ snapshot.chronicle.title }}</h4>
      <p v-for="(para, i) in snapshot.chronicle.paragraphs" :key="i" class="rv-serif rv-muted text-[15px] leading-relaxed mb-2.5 last:mb-0">{{ para }}</p>
    </article>
  </div>
38 
  <!-- The words you sent — the keepsake -->
  <div v-if="snapshot.dispatches.length" data-testid="run-dispatches" class="mt-7">
    <span class="rv-label rv-label--rule">The words you sent</span>
    <ul class="space-y-3.5">
      <li v-for="(d, i) in snapshot.dispatches" :key="i">
        <p class="rv-label">to {{ d.figure }}<span v-if="d.era"> · {{ d.era }}</span></p>
        <blockquote class="rv-serif rv-fg text-base leading-relaxed border-l-2 rv-line pl-3 mt-1">"{{ d.text }}"</blockquote>
      </li>
    </ul>
  </div>
49 
  <!-- Stats -->
  <div data-testid="run-summary" class="mt-7">
    <span class="rv-label rv-label--rule">How it played out</span>
    <div class="flex flex-wrap gap-10">
      <div data-testid="run-message-efficiency">
        <div class="rv-mono text-3xl font-extrabold rv-fg leading-none">{{ snapshot.messagesUsed }}</div>
        <div class="rv-label mt-1">{{ snapshot.messagesUsed === 1 ? 'message' : 'messages' }} sent</div>
      </div>
      <div v-if="snapshot.bestRoll" data-testid="run-best-roll">
        <div class="rv-mono text-3xl font-extrabold rv-ok leading-none">{{ snapshot.bestRoll.diceRoll }}</div>
        <div class="rv-label mt-1">{{ snapshot.messagesUsed >= 2 ? 'best roll' : 'the roll that did it' }} · {{ snapshot.bestRoll.diceOutcome }}</div>
      </div>
      <div v-if="snapshot.worstRoll && snapshot.messagesUsed >= 2" data-testid="run-worst-roll">
        <div class="rv-mono text-3xl font-extrabold rv-bad leading-none">{{ snapshot.worstRoll.diceRoll }}</div>
        <div class="rv-label mt-1">worst roll · {{ snapshot.worstRoll.diceOutcome }}</div>
      </div>
    </div>
  </div>
68 
  <!-- The history you wrote -->
  <div v-if="snapshot.timeline.length > 0" data-testid="run-timeline" class="mt-6">
    <span class="rv-label rv-label--rule">The history you wrote</span>
    <ol>
      <li v-for="event in snapshot.timeline" :key="event.id" class="flex items-start justify-between gap-3 py-2 border-b rv-line last:border-b-0">
        <div class="min-w-0">
          <p class="rv-fg text-sm font-medium">{{ event.headline }}</p>
          <p class="rv-faint text-[11px] rv-mono">{{ event.era }} · {{ event.figureName }}</p>
        </div>
        <span class="rv-mono text-sm font-bold shrink-0" :class="deltaClass(event.progressChange)">
          {{ event.progressChange > 0 ? '+' : '' }}{{ event.progressChange }}%
        </span>
      </li>
    </ol>
  </div>
</div>
85</template>
86 
87<script setup lang="ts">
88/**
* RunView — a read-only render of a saved run (a RunSnapshot). It mirrors
* EndGameScreen's verdict / epilogue / ledger, but reads everything from the passed
* snapshot rather than the live store, so it can replay a past run (and later, a
* shared one). Intentionally self-contained: no store coupling, no AI, no controls.
*/
94import { computed } from 'vue'
95import type { RunSnapshot } from '~/utils/run-snapshot'
96 
97const props = defineProps<{ snapshot: RunSnapshot }>()
98 
99const isVictory = computed(() => props.snapshot.status === 'victory')
100 
101// The verdict never deflates: a full-message win reads "Hard-won," not "Standard"
102// (matches EndGameScreen's phrasing exactly).
103const victoryPhrase = computed(() => {
  const rating = props.snapshot.efficiency?.efficiencyRating
  if (!rating) return 'Victory'
  return rating === 'Standard' ? 'Hard-won victory' : `${rating} victory`
107})
108 
109function deltaClass(change: number) {
  if (change > 0) return 'rv-ok'
  if (change < 0) return 'rv-bad'
  return 'rv-muted'
113}
⋯ 1 line hidden (lines 114–114)114</script>

Anonymous → account linking (the one open decision)

A visitor is already an anonymous Supabase user with a durable id, so a run is owned from turn one. Sign-in splits two ways. A new account upgrades that anonymous user in place — same id — so its runs carry over for free, no migration. An existing account is a different id; the anonymous user's runs are left behind.

The issue left this as the one decision: merge the existing-account path now, or ship the new-account path and document the gap. This PR defers the merge and documents it right where the identical balance-merge gap already lives. Re-keying runs without also re-keying the balance would be inconsistent, so the two should move together in a later change.

The module doc, now covering saved runs alongside the balance deferral.

utils/sign-in.ts · 82 lines

utils/sign-in.ts82 lines · TypeScript

1/**
2 * Requesting a sign-in link for the run-store account.
3 *
4 * A visitor is already an anonymous Supabase user, which splits sign-in into two
5 * cases the form can't tell apart up front:
6 *  - NEW player: attach the email to their anonymous user (`updateUser`) so the
7 *    account upgrades in place — same id, runs carried over.
8 *  - RETURNING player: the email already belongs to an account, so that in-place
9 *    upgrade can't apply — Supabase rejects it with `email_exists`. We fall back to
10 *    a magic-link sign-in into that existing account (`signInWithOtp`,
11 *    `shouldCreateUser: false`, so we never mint a duplicate).
12 *
13 * Either path emails a link back to /play, where `utils/auth-return.ts` finalizes
14 * it. The NEW-player path keeps the same user id, so the run balance AND any saved
15 * runs (the `run_snapshots` records, owned by that id) carry over for free. The
16 * RETURNING-player path switches to a different account: that account's balance is
17 * adopted, and the anonymous user's balance and saved runs accrued in this browser
18 * are left behind — re-keying both onto the existing account would be a separate
19 * change (the same deferral applies to balance and saved runs alike).
⋯ 63 lines hidden (lines 20–82)20 */
21 
22/** The slice of a Supabase `AuthError` we branch on. */
23export interface AuthErrorLike {
24    code?: string
25    status?: number
26    message?: string
27}
28 
29/** The slice of the Supabase auth client this needs — kept local so the util
30 *  carries no Nuxt/Supabase runtime imports and unit-tests in the node env. */
31export interface SignInClient {
32    updateUser(
33        attributes: { email: string },
34        options: { emailRedirectTo?: string }
35    ): Promise<{ error: AuthErrorLike | null }>
36    signInWithOtp(
37        credentials: { email: string; options: { emailRedirectTo?: string; shouldCreateUser: boolean } }
38    ): Promise<{ error: AuthErrorLike | null }>
39}
40 
41export type SignInResult =
42    | { status: 'sent' }
43    | { status: 'error'; message: string }
44 
45/** Error codes that all mean "this email already belongs to an account". The set
46 *  spans the variants Supabase has used so a version bump can't silently strand a
47 *  returning player back on the failure path. */
48const EMAIL_TAKEN_CODES = new Set(['email_exists', 'identity_already_exists', 'user_already_exists'])
49 
50export const isEmailTakenError = (e: AuthErrorLike | null | undefined): boolean =>
51    Boolean(e && EMAIL_TAKEN_CODES.has(e.code ?? ''))
52 
53const RATE_LIMITED = 'Too many requests just now — give it a minute, then try again.'
54const SEND_FAILED = 'Could not send the sign-in link. Please try again.'
55 
56const messageFor = (e: AuthErrorLike): string =>
57    e.code === 'over_email_send_rate_limit' ? RATE_LIMITED : SEND_FAILED
58 
59/**
60 * Sends a sign-in link: upgrades the anonymous user in place when the email is new,
61 * and signs into the existing account when the email is already taken. Returns
62 * whether the link went out, or a player-facing error message.
63 */
64export async function requestSignInLink(
65    email: string,
66    emailRedirectTo: string | undefined,
67    client: SignInClient
68): Promise<SignInResult> {
69    const { error: upgradeError } = await client.updateUser({ email }, { emailRedirectTo })
70    if (!upgradeError) return { status: 'sent' }
71 
72    // Returning player: send a magic link to the account that already owns this email.
73    if (isEmailTakenError(upgradeError)) {
74        const { error: signInError } = await client.signInWithOtp({
75            email,
76            options: { emailRedirectTo, shouldCreateUser: false }
77        })
78        return signInError ? { status: 'error', message: messageFor(signInError) } : { status: 'sent' }
79    }
80 
81    return { status: 'error', message: messageFor(upgradeError) }
82}

How it was verified

npx vitest run is green (751 tests) and npx nuxt typecheck is clean. New tests cover the save → list → load round-trip and ownership scoping, the boundary sanitizer (rejects non-terminal runs, clamps and caps fields, stamps the version), the store save action (the exact posted shape, the no-op guards, the swallowed failure), and the read-only view.

Beyond tests, the feature was exercised in a live boot with the in-memory store: POST a snapshot, list it, open it — with a fresh device seeing nothing, a non-owned id returning 404, and the /runs and /runs/:id pages rendering the run end to end.