A game-settings layer — a design note you can vouch for

What this PR is

One file: docs/design/game-settings-layer.md. Issue #90 is a design exploration, not an implementation — the deliverable is a recommendation, not code, a schema, or UI. This guide exists so a reviewer can do the one thing that matters for a design note: check that it's grounded in the real code. Each claim the note makes about the run economy is shown here beside the source it rests on.

The recommendation, in one breath: a lean v1 of three difficulty presets (Story · Standard · Iron), two run-shape dials (messages per run, distinct-figures cap), and a deterministic seed plumbed in. Everything else deferred. The note's spine is below.

The v1 cut, lead-with-the-answer.

The note's TL;DR · 353 lines

The note's TL;DR353 lines · Markdown

⋯ 8 lines hidden (lines 1–8)1# Game Settings Layer — difficulty, run shape, constraints
2 
3> **Design exploration for [#90](https://github.com/mseeks/revisionist/issues/90).** This is a
4> recommendation, not an implementation. No `RunSettings` schema, no settings UI, no
5> retuning of the live curve — just the design space, a recommended v1, and the
6> implementation issues this note should spawn. For what is true in the code today,
7> read [`../../CLAUDE.md`](../../CLAUDE.md); for forward intent, [`../ROADMAP.md`](../ROADMAP.md).
8 
9## TL;DR — the recommendation
10 
11Ship a **lean v1**: three difficulty **presets** as the primary surface, **two run-shape
12dials** exposed directly, and a **deterministic seed** plumbed in (no UI yet). Defer
13everything else.
14 
15| v1 (ship) | v2 (next) | Deferred / never |
16|---|---|---|
17| **Difficulty presets:** Story · Standard · Iron | Per-dial **Custom** overrides | Daily challenge, score normalization |
18| **Messages per run** (run length) | Timeline-window constraints (era clamp, chronological-only) | Message length (it's core identity — leave fixed) |
19| **Distinct-figures cap** (incl. single-figure) | Sandbox / "anywhen" stance (its own slice) | Paid-gating (note the question; don't decide) |
20| **Seed** (plumbing only — basis for sharing/replay) | Repeat-contact + grounded-only policies | — |
⋯ 333 lines hidden (lines 21–353)21 
22Four load-bearing decisions, each argued below:
23 
241. **Presets bundle the dials; they are not independent sliders.** The run economy is a
25   tuned system. A preset must move the band economy *with* message count and win
26   threshold, or the win rate breaks.
272. **`RunSettings` is a small serializable bundle, chosen at mission-select**, stored in
28   the run, validated server-side. Design it serializable from day one so a shared run
29   (`#88`/`#89`) can carry its rules + seed.
303. **Safety never moves.** Difficulty can make the *game* harder or easier; it can never
31   relax the server-authoritative safety floor (`#72` deceased-only, `#71` objective
32   bounds, the swing clamp, moderation). Those stay closed-enum and server-enforced.
334. **Every preset needs eval coverage** so a retune can't silently regress the EV
34   corridor the economy rests on.
35 
36## Today: one fixed configuration
37 
38The game ships as a single, well-tuned configuration. Every rule is a named constant —
39already centralized, just not player-facing. The cross-module ones live in
40[`utils/game-config.ts`](../../utils/game-config.ts); the rest sit per-module by design.
41 
42| Constant | Value | File | Controls |
43|---|---|---|---|
44| `TOTAL_MESSAGES` | `5` | `utils/game-config.ts` | dispatches allotted per run |
45| `MAX_PROGRESS` | `100` | `utils/game-config.ts` | win threshold (progress is clamped 0..100) |
46| `MAX_PROGRESS_SWING` | `50` | `utils/game-config.ts` | the per-turn fuse (hard clamp on a resolved swing) |
47| `MAX_MESSAGE_CHARS` | `160` | `utils/game-config.ts` | chars per dispatch |
48| `SWING_BANDS` | CF −35..−15 · F −15..−5 · N 0..+12 · S +15..+30 · CS +30..+45 | `utils/swing-bands.ts` | the D20 band → progress table (the run economy) |
49| dice faces | CF 1–2 · F 3–8 · N 9–12 · S 13–18 · CS 19–20 (2/6/4/6/2) | `utils/dice.ts` | the natural-roll distribution |
50| `STAKE_MULTIPLIER` / `STAKED_SWING_CAP` | `2` / `100` | `utils/swing-bands.ts` | the last-stand wager on a final dispatch |
51| `CRAFT_MODIFIER` / `CRAFT_GAIN_FACTOR` | ±2 roll / ×0.15–1.45 gain | `utils/craft.ts` | the Message Judge's two channels |
52| `MOMENTUM_MAX` / `MOMENTUM_STEP` | `4` / `0.1` (cap ×1.4) | `utils/momentum.ts` | the run-level gains amplifier |
53| `BRIDGE_FREE` / `SCALE` / `CHAIN_FLOOR` | `75` / `550` / `0.12` | `utils/causal-chain.ts` | causal-chain decay |
54| `GAIN_FACTOR` / `LOSS_FACTOR` / `KNEE` | ×1–1.6 / ×1–2 / `40` | `server/utils/anachronism.ts` | the future-knowledge wager |
55| `SAFELY_HISTORICAL_BEFORE_YEAR` | (the floor) | `server/utils/historical-floor.ts` | the safely-dead / safely-historical line (`#71`/`#72`) |
56 
57`utils/game-config.ts` is the natural seam for a settings layer — but its own header says
58only *cross-module* rules belong there; many dials are intentionally local. Part of the
59work is deciding **which constants get promoted into a player-facing `RunSettings`** and
60which stay internal.
61 
62## The core risk: the economy is a tuned system, not free dials
63 
64This is the whole reason these aren't already settings, and the reason a difficulty
65"level" must be a **bundle** rather than a row of independent sliders.
66 
67**The EV corridor.** With the documented face distribution (2/6/4/6/2 over 20) and the
68band midpoints, the expected swing for *sound, unaided* play (craft modifier 0, no wager,
69no chain, no momentum) is:
70 
71```
72P(CF)=0.10  P(F)=0.30  P(N)=0.20  P(S)=0.30  P(CS)=0.10
73mid:  −25       −10       +6        +22.5       +37.5
74EV = .10(−25) + .30(−10) + .20(6) + .30(22.5) + .10(37.5) ≈ +6.2 / turn
75```
76 
77That matches the tuning intent stated in `utils/swing-bands.ts` ("roughly +6/turn" for
78sound play). Over `TOTAL_MESSAGES = 5` turns that is ≈ **+31 of 100** — an *honorable
79loss*. The gap to 100 is what craft, a calibrated anachronism wager, and momentum are
80meant to close, so victory is earned rather than drawn from a lottery.
81 
82**The pipeline that produces a turn's swing** (`callTimelineAI`,
83`server/utils/openai.ts`), in order:
84 
851. Roll a D20; **craft modifier (±2)** shifts the roll (clamped 1–20) → this picks the band.
862. Model proposes a swing; it is **clamped into the rolled band** (`SWING_BANDS`).
873. **Anachronism amplifier** (`amplifyForAnachronism`) widens both signs, asymmetric
88   (gains ×1.15/1.35/1.6, losses ×1.25/1.6/2), soft knee above ±40, re-clamped to ±50.
894. **Causal-chain decay** (`decayForChain`) diffuses both signs toward zero by distance
90   from the nearest foothold (floor 0.12).
915. **Gains-only** multipliers: positive swing × `CRAFT_GAIN_FACTOR` × `momentumFactor`.
92   Losses are never scaled — skill buys reach, never immunity.
936. **Clamp to ±`MAX_PROGRESS_SWING`** (the per-turn fuse).
947. On a final *staked* dispatch only: `applyStake` doubles, clamp ±100.
95 
96**Why the coupling bites.** The corridor is calibrated against `TOTAL_MESSAGES` *and*
97`MAX_PROGRESS` together:
98 
99- Cut messages 5 → 3 and unaided play yields ≈ +18, while the per-turn band ceiling is
100  +45 (`BAND_CEILING`). The win now demands ≈ +33/turn average — near-impossible inside
101  the bands. The run is "harder" by accident, not design.
102- Raise the win threshold 100 → 150 and the same thing happens from the other side.
103- Widen the per-turn fuse and the stake's drama collapses (every turn can already swing
104  the meter).
105 
106So a difficulty preset cannot change message count or win threshold *and leave the bands
107alone*. The bands, the message count, and the threshold move **together**, as one tuned
108bundle, validated by eval. This single fact drives the entire design: **presets, not
109sliders.**
110 
111The honest framing for a preset: it sets a *target* unaided-finish ratio (today ≈ 0.31 of
112the win bar) and a target aided EV, then derives the dials to hit them. There is one
113genuinely clean exception, and it points at the simplest KISS move: **message count
114re-prices the run while leaving every per-turn artifact byte-identical** (bands, dice,
115legend, prompt calibration all unchanged). The pragmatic call is to let message count *be*
116a difficulty axis — Story = more messages, Iron = fewer — and accept that the corridor
117ratio moves with it, rather than re-scaling the bands to hold the ratio constant. Document
118the shift as the intended knob.
119 
120### Gotchas the implementation must handle
121 
122Making these constants settings exposes seams that are invisible today because the values
123happen to line up:
124 
125- **Coincidentally-equal literals must become derived.** `STAKED_SWING_CAP` is a hardcoded
126  `100` (`utils/swing-bands.ts`), *not* a reference to `MAX_PROGRESS`. They are equal by
127  intent (a staked throw sweeps the whole meter) but would silently diverge the moment the
128  win threshold becomes a setting. Same risk anywhere a tuning value re-derives a
129  game-config number by hand.
130- **Re-typed eval constants would desync.** The ±3 valence window and the 160-char cap are
131  re-typed inside the eval fixtures, not imported. A preset touching them desyncs the evals
132  from the game silently. Promote them to imports first.
133- **`BAND_CEILING ≤ MAX_PROGRESS_SWING` is a pinned invariant** (`swing-bands.spec.ts`). Any
134  preset that reshapes the bands has to re-check it, or the amplifier loses its headroom.
135 
136## What gets promoted vs stays internal
137 
138A clean split keeps the settings surface small and the safety/tuning invariants intact.
139 
140**Promote into `RunSettings` (player-facing, per run):**
141 
142- `messagesPerRun` (← `TOTAL_MESSAGES`) — the cleanest standalone run-shape knob.
143- `winThreshold` (← `MAX_PROGRESS`) — only via presets (it re-tunes the corridor).
144- `distinctFiguresCap` — a *new* constraint (none today); 1 = single-thread challenge.
145- `difficulty` — a preset id that *bundles* the tuning dials below.
146- `seed` — deterministic dice; plumbing now, surfaced later for sharing/replay.
147 
148**Keep internal, scaled only *through* a preset (never a raw slider):** the band table,
149the dice reshaping, `CRAFT_*`, `MOMENTUM_*`, the anachronism factors, the chain decay,
150the stake. These are the tuning dials; exposing them raw is how a player breaks the
151curve. A v2 "Custom" mode can open a curated subset behind an advanced panel.
152 
153**Keep internal and immovable (safety):** `isDeceased` / `SAFELY_HISTORICAL_BEFORE_YEAR`
154(`#72`), the objective bounds (`#71`), the in-code band clamp, and moderation
155(`REVISIONIST_MODERATION`). Difficulty does not get a vote here.
156 
157**Leave fixed:** `MAX_MESSAGE_CHARS = 160`. The 160-char discipline is core identity and
158an eval'd Character-layer invariant; making it a dial dilutes the game's signature
159constraint for little variety.
160 
161## The candidate catalog, triaged
162 
163The issue's brainstorm (groups A–G), cut to a v1 verdict. The full rationale for the
164"economy" rows is the section above.
165 
166| Candidate | Maps to | Verdict | Why |
167|---|---|---|---|
168| Messages per run | `TOTAL_MESSAGES` | **v1 dial** | cleanest run-shape lever; couples to the corridor, so its retune rides the preset |
169| Distinct-figures cap | new constraint | **v1 dial** | adds real variety (single-figure run), no economy coupling, server-checkable |
170| Difficulty preset | bundles the tuning dials | **v1 (primary)** | the only safe way to move the coupled economy |
171| Win threshold | `MAX_PROGRESS` | **v1, preset-only** | moves the corridor — must ride a preset, never a free slider |
172| Per-turn fuse | `MAX_PROGRESS_SWING` | **internal** | a safety clamp + the stake's basis; not a player knob |
173| Roll variance / band reshape | dice + bands | **internal (preset-scaled)** | the corridor itself |
174| Craft weight / anachronism / decay / momentum / stake | the tuning dials | **internal (preset-scaled)** | exposing raw breaks tuning |
175| Timeline-window constraints (era clamp, chronological-only) | new, atop the when-slider | **v2** | strong variety, but needs its own UX + eval; lifetime bound already exists |
176| Sandbox / "anywhen" | drop lifetime + safely-dead bounds | **deferred (own slice)** | collides with the safety floor; a deliberate separate stance, not a difficulty knob |
177| Repeat-contact / grounded-only | figure policy | **v2** | grounded-only is already the floor (`#73`); repeat-contact is a light add |
178| Safely-dead cutoff relax | `#72` floor | **never (as difficulty)** | safety, server-authoritative — cannot be a difficulty lever |
179| Objective source / steering / anchor visibility / reroll cap | `#71`, objective compose | **v2** | ties to objective work, not the core economy |
180| Assist (tutorial, scaffolding, archive access) | `#60`, UI | **folds into presets** | Story shows scaffolding; Iron hides it + caps research |
181| Seed | new | **v1 (plumbing)** | the basis for fair sharing/replay; cheap to land early |
182| Daily challenge / speedrun / score normalization | meta modes | **deferred** | depend on seed + sharing; design after the bundle exists |
183 
184## The v1 proposal: three presets
185 
186Three is the right number: an on-ramp, the tuned default, and a brutal mode — from one
187engine. The dial values below are **illustrative targets to be validated by eval**, not
188final tuning (the issue forbids re-tuning the live curve here; this just shows *where*
189each preset would re-tune it).
190 
191| Dimension | **Story** (on-ramp) | **Standard** (today) | **Iron** (veteran) |
192|---|---|---|---|
193| Target unaided EV/turn | higher (~+9) | ~+6 (today) | lower (~+4) |
194| Messages per run | 6–7 | **5** | 4 |
195| Win threshold | 100 | **100** | 100 (decisive feel via tighter economy, not a higher bar) |
196| Band economy | gentler losses, fatter Success | **today** | harsher losses, leaner gains |
197| Anachronism penalty | softened | **today** | harsher losses |
198| Causal-chain decay | gentler | **today** | steeper (chaining matters more) |
199| Last stand (stake) | on | **on** | **off** (no safety net) |
200| Scaffolding (band table, pace hint, ⚡/⏳ chips) | all shown | **shown** | hidden |
201| Archive (research) | unlimited | **unlimited** | capped or disabled |
202| Guided first-run (`#60`) | on | default | off |
203 
204Standard *is* the current configuration — shipping presets must not change today's game.
205Story and Iron are symmetric moves outward from it, each a coherent bundle rather than a
206pile of toggles. Note that "harder" on Iron comes mostly from a leaner economy and a
207removed safety net, **not** from raising the win bar — keeping the meter legible.
208 
209## Surface, persistence, and travel
210 
211**Presets over a wall of sliders.** The mission-select briefing
212([`components/MissionSelect.vue`](../../components/MissionSelect.vue)) gains one row: a
213three-way difficulty chip plus the two run-shape dials (messages, figure cap). That is
214the entire v1 surface. A "Custom" disclosure (per-dial overrides) is explicitly v2.
215 
216**Where settings live.** A run starts when the player commits an objective
217(`chooseObjective` in `stores/game.ts`; a null `currentObjective` is what surfaces the
218briefing). `RunSettings` is authored in the same briefing — a sibling fieldset to the
219existing era/theme steer dials, closed enums, committed only on Begin — threaded through
220`chooseObjective` into **one new `runSettings` state field cleared by `resetGame`**, and
221read by `sendMessage` and the pure dials. Because it carries only pre-run choices (no
222dates, no server `runId`, none of the staleness/account plumbing), it round-trips through
223JSON or a URL param cleanly — which is exactly what makes it the right unit to travel with
224a run. It must work for **anonymous** players (the default path today). A saved profile
225default is a later tie to accounts (`#83`), layered on top — the per-run choice is the
226primitive.
227 
228**Settings travel with a run.** There is **no run snapshot, share, or seed concept in the
229code today** — a run is entirely live and ephemeral. That makes this greenfield, and it
230argues for designing `RunSettings` as a **small serializable bundle from the start**, next
231to a `seed`. For shared-run "beat this" (`#88`) and replay (`#89`) to be *fair*, the
232snapshot has to carry both the rules and the seed; otherwise two players aren't playing
233the same game. The seed is the one piece worth plumbing in v1 even before daily/seeded
234modes ship, because retrofitting determinism later is far more invasive than reserving the
235field now (the dice live behind `rollD20` in `utils/dice.ts` — a single, swappable source).
236 
237## Safety stays server-authoritative
238 
239Several knobs are server-enforced and closed-enum on purpose: the deceased-only contact
240floor (`isDeceased`, `server/utils/figure-grounding.ts`, fail-closed — a figure with no
241confirmed death is never contactable), the objective bounds (`#71`), the in-code clamp of
242the engine's swing into the rolled band, and moderation. A settings layer **must not
243become a client bypass.** Concretely:
244 
245- `RunSettings` is **validated and clamped server-side**, to an allowed range per field —
246  the client's chosen values are untrusted input, like every other field. This is the
247  pattern already in place: `send-message.post.ts` and `research.post.ts` **re-ground the
248  figure name** against the untrusted payload rather than trusting a client claim of "this
249  person is contactable."
250- Difficulty scales the *game* (harder/easier), never the *safety floor*. There is no
251  difficulty that lets you message a living person or dodge moderation. A Sandbox / "anywhen"
252  stance that *did* relax the lifetime + deceased-only bounds (its own deferred slice, not a
253  difficulty knob) would flip a **server-read** flag, never a client toggle the POST handler
254  honors — and moderation (`REVISIONIST_MODERATION`) is never surfaced to players at all;
255  `off` is an operator/calibration lever only.
256- The closed enums stay closed. A preset id is one of a fixed set; an out-of-range message
257  count or figure cap is rejected, not honored.
258 
259## Evals: a preset can't silently break the curve
260 
261The tuning expectations already live as evals, and a new difficulty knob has to extend
262them or it can regress the curve invisibly:
263 
264- [`evals/bakeoff.eval.ts`](../../evals/bakeoff.eval.ts) scores **the NEUTRAL-band EV
265  corridor the run economy is tuned around** — the exact invariant a preset's retune
266  threatens.
267- [`evals/behavior.eval.ts`](../../evals/behavior.eval.ts) checks the model-behavior
268  invariants the mechanics rest on (band steering, `sharp ≥ vague` craft ordering,
269  anachronism accuracy).
270- [`evals/causal-chain.eval.ts`](../../evals/causal-chain.eval.ts) confirms stepping
271  stones beat blasts end-to-end; [`evals/judge-tune.eval.ts`](../../evals/judge-tune.eval.ts)
272  pins craft-grade anchoring (which feeds the economy).
273 
274But the existing coverage has two gaps a preset would fall straight through, and naming
275them is half the value of this exploration:
276 
2771. **The corridor eval guards the wrong number.** It scores `baseProgressChange` — the swing
278   *before* the anachronism / causal-chain / craft-gain / momentum multipliers. So the four
279   downstream multipliers are an **unguarded realized-EV surface**: a "hard" preset that
280   halved `CRAFT_GAIN_FACTOR` would change the EV the player actually experiences while the
281   corridor eval stayed green. The `[4,9]` corridor is a real invariant, but it is *not* the
282   EV the run is won or lost on.
2832. **The corridor bounds are hardcoded literals, not a function of the preset.** If Story
284   legitimately targets a higher neutral EV and Iron a lower one, today's absolute `[4,9]`
285   assertion would flag the *intended* presets as misses. The corridor eval has to become
286   **preset-parameterized** — fed each preset's target band.
287 
288**Requirement for the implementation:** each shipped preset needs (a) a parameterized
289pre-multiplier corridor assertion fed its own target, and (b) a **realized-EV** assertion
290that composes the full pipeline (so a multiplier change can't move the curve unseen) and a
291plausible win rate at sound + calibrated play. The pure dials (bands, decay, momentum,
292craft) are already unit-tested in isolation; the new surface to cover is *the composition
293under each preset*.
294 
295## Scope & monetization
296 
297v1 is deliberately small: presets + two dials + seed plumbing. The open question worth
298**noting, not deciding here**: whether any setting (e.g. seeded/daily competitive modes,
299or an Iron leaderboard) is paid-gated. The accounts/paywall seam already exists (`#83`,
300the runs economy); this note flags the question and leaves the call to the monetization
301track.
302 
303## Recommended v1, restated
304 
305- **Surface:** three difficulty presets (Story · Standard · Iron) + two run-shape dials
306  (messages per run, distinct-figures cap), chosen at mission-select. Custom per-dial
307  overrides deferred to v2.
308- **Model:** a small serializable `RunSettings` bundle (`difficulty`, `messagesPerRun`,
309  `distinctFiguresCap`, `seed`), validated + clamped server-side, stored in the run,
310  anonymous-friendly, profile-default later (`#83`).
311- **Economy:** each preset re-tunes the bundle (message count + band economy + the wager /
312  decay / momentum / stake) **together**, with Standard == today's game unchanged.
313- **Travel:** plumb a deterministic `seed` now; carry `RunSettings` + `seed` in the run
314  snapshot when sharing/replay (`#88`/`#89`) lands.
315- **Guardrails:** safety floor untouched and server-authoritative; an EV-corridor eval per
316  preset.
317 
318## Implementation issues this note spawns
319 
320Ready-to-file, in dependency order:
321 
3221. **`RunSettings` bundle + server validation + seed plumbing.** Define the serializable
323   type (`difficulty`, `messagesPerRun`, `distinctFiguresCap`, `seed`), thread it through
324   the store run-state and `sendMessage`, validate + clamp server-side, and route the dice
325   through a seeded source behind `rollD20`. No UI beyond a default. *Foundation for the
326   rest.*
3272. **Difficulty presets + economy retune + eval coverage.** Implement Story/Standard/Iron
328   as preset bundles that scale the internal tuning dials together; Standard reproduces
329   today's curve exactly. Make the corridor eval **preset-parameterized** and add a
330   **realized-EV** assertion (full pipeline, not just `baseProgressChange`) per preset.
331   First promote the re-typed eval constants (±3 valence, 160-char) to imports and derive
332   `STAKED_SWING_CAP` from the win threshold so nothing diverges silently. *Depends on 1.*
3333. **Run-shape dials at mission-select.** Surface `messagesPerRun` and
334   `distinctFiguresCap` (incl. the single-figure challenge) in `MissionSelect.vue`, with
335   the figure cap enforced server-side. *Depends on 1; pairs with 2 for the message-count
336   retune.*
3374. **Settings + seed travel with a shared run.** Carry `RunSettings` + `seed` in the run
338   snapshot so a shared/replayed run is the same game. *Depends on 1 and on `#88`/`#89`.*
339 
340## Explicitly out of scope (per #90)
341 
342No implementation, no final `RunSettings` schema, no settings UI here. No commitment to the
343final set — this is divergent brainstorming plus a recommendation. Not a re-tuning of the
344existing curve; this only identifies *where* each difficulty would re-tune it.
345 
346---
347 
348*Related:* [#83](https://github.com/mseeks/revisionist/issues/83) (accounts — saved
349defaults) · [#88](https://github.com/mseeks/revisionist/issues/88) /
350[#89](https://github.com/mseeks/revisionist/issues/89) (sharing & replay — why a run
351should carry its settings + seed) · [#71](https://github.com/mseeks/revisionist/issues/71)
352(objective steering) · [#72](https://github.com/mseeks/revisionist/issues/72) (safely-dead
353floor) · [#60](https://github.com/mseeks/revisionist/issues/60) (guided first-run).

The run economy is a tuned system, not free dials

This is the load-bearing claim of the whole note, and the reason a difficulty 'level' has to be a bundle rather than a row of independent sliders. The cross-module constants are small and already centralized — they're just not player-facing yet.

TOTAL_MESSAGES, MAX_PROGRESS (win bar), MAX_PROGRESS_SWING (the per-turn fuse).

The config seam · 31 lines

The config seam31 lines · TypeScript

⋯ 8 lines hidden (lines 1–8)1/**
2 * Shared game-rule constants — named once so the store, the server validation,
3 * the post-game summary, and the input UI can't silently drift apart. Each was
4 * surfaced as a re-typed literal by the duplicated-constant loop. (Per-module
5 * rules that live in a single file — the rate-limit window, the dice bands —
6 * stay where they are used; only the genuinely cross-module ones live here.)
7 */
8 
9/** Messages allotted per run. */
10export const TOTAL_MESSAGES = 5
11 
12/** Hard cap on a single message's length, in characters. */
13export const MAX_MESSAGE_CHARS = 160
14 
15/**
16 * Hard safety cap on a single resolved turn's progress swing, in percentage
17 * points (±). The Timeline Engine's base swing is clamped to this and the
18 * anachronism amplifier re-clamps to it. Deliberately a touch WIDER than the
19 * instructed band ceiling (`BAND_CEILING` in `utils/swing-bands.ts`, the range
20 * the prompt + schema state to the model), so the amplifier has real headroom
21 * above the bands; the band table is the tuning surface, this is the fuse.
22 */
23export const MAX_PROGRESS_SWING = 50
24 
25/**
26 * The objective-progress ceiling, in percentage points: a run's progress is clamped
27 * to 0..MAX_PROGRESS and victory is reaching it. Cross-module — the store gates and
28 * clamps against it, and /api/chronicle sanitizes the client-supplied progress to it
29 * before the Chronicler narrates — so it lives here rather than being re-typed.
30 */
31export const MAX_PROGRESS = 100

The D20 outcome → progress-swing table, single-sourced; BAND_CEILING derives from it (= 45).

The band table — the run economy · 70 lines

The band table — the run economy70 lines · TypeScript

⋯ 23 lines hidden (lines 1–23)1import { DiceOutcome } from '~/utils/dice'
2 
3/**
4 * The D20 band → progress-swing table, named once. The Timeline Engine's prompt
5 * renders its calibration lines FROM this table, the response schema states the
6 * same ceiling, and the UI's roll legend reads it too — so the numbers the model
7 * is told, the numbers the code enforces, and the numbers the player is shown
8 * can't silently drift apart. A rebalance is one edit, here.
9 *
10 * Tuning intent (the run economy): five messages must reach 100. With sound play
11 * the expected swing is roughly +6/turn — losing, but honorably; craft (the
12 * Message Judge's roll modifier) and a well-calibrated anachronism wager push a
13 * thoughtful run to roughly +12..16/turn, where victory is earned rather than
14 * drawn from a lottery. Dice still dominate any single turn; judgment decides
15 * the campaign.
16 */
17export interface SwingBand {
18    /** Most negative end of the band's instructed range, in progress points. */
19    min: number
20    /** Most positive end of the band's instructed range, in progress points. */
21    max: number
22}
23 
24export const SWING_BANDS: Record<DiceOutcome, SwingBand> = {
25    [DiceOutcome.CRITICAL_SUCCESS]: { min: 30, max: 45 },
26    [DiceOutcome.SUCCESS]: { min: 15, max: 30 },
27    [DiceOutcome.NEUTRAL]: { min: 0, max: 12 },
28    [DiceOutcome.FAILURE]: { min: -15, max: -5 },
29    [DiceOutcome.CRITICAL_FAILURE]: { min: -35, max: -15 }
30}
⋯ 7 lines hidden (lines 31–37)31 
32/**
33 * The largest base magnitude any band allows — the integer range stated to the
34 * model (±45). Derived, not re-typed; the hard safety clamp in game-config
35 * (±MAX_PROGRESS_SWING) stays slightly wider so the anachronism amplifier has
36 * headroom above the bands.
37 */
38export const BAND_CEILING = Math.max(
39    ...Object.values(SWING_BANDS).flatMap(b => [Math.abs(b.min), Math.abs(b.max)])
40)
⋯ 30 lines hidden (lines 41–70)41 
42/**
43 * The neutral window for the Timeline Engine's valence sign-guard: a resolved swing
44 * whose magnitude exceeds this must wear the color of its sign (a "positive" badge on
45 * a clear loss reads as arbitrary), while a smaller swing keeps the model's shading.
46 * Applied once in callTimelineAI on the pre-stake swing and re-asserted in
47 * send-message.post.ts on a doubled (staked) swing — named once so the two can't drift.
48 */
49export const VALENCE_SIGN_GUARD_MIN = 3
50 
51/**
52 * The last stand: when the FINAL dispatch of a run can no longer win inside the
53 * normal fuse (the gap exceeds MAX_PROGRESS_SWING — the store's `canStake`),
54 * the player may STAKE THE TIMELINE — the resolved swing doubles, both ways,
55 * and escapes the per-turn cap up to the full meter. Structurally this means no
56 * run is ever mathematically dead while a message remains. Deliberately NOT
57 * offered from winnable positions: doubling never lowers win odds on a final
58 * throw, so an unrestricted stake would be a dominance trap, not a decision.
59 * The doubling itself is applied server-side after amplification.
60 */
61export const STAKE_MULTIPLIER = 2
62export const STAKED_SWING_CAP = 100
63 
64/** One-line hover hint for the ⚑ stake badge — the last-stand wager. */
65export const STAKE_HINT = 'the last stand, only on your final dispatch — doubles the swing, both ways'
66 
67export function applyStake(progressChange: number): number {
68    const staked = Math.round(progressChange * STAKE_MULTIPLIER)
69    return Math.max(-STAKED_SWING_CAP, Math.min(STAKED_SWING_CAP, staked))
70}

STAKED_SWING_CAP is a hardcoded 100, not a reference to MAX_PROGRESS — a seam the note flags.

The last stand (context) · 70 lines

The last stand (context)70 lines · TypeScript

⋯ 50 lines hidden (lines 1–50)1import { DiceOutcome } from '~/utils/dice'
2 
3/**
4 * The D20 band → progress-swing table, named once. The Timeline Engine's prompt
5 * renders its calibration lines FROM this table, the response schema states the
6 * same ceiling, and the UI's roll legend reads it too — so the numbers the model
7 * is told, the numbers the code enforces, and the numbers the player is shown
8 * can't silently drift apart. A rebalance is one edit, here.
9 *
10 * Tuning intent (the run economy): five messages must reach 100. With sound play
11 * the expected swing is roughly +6/turn — losing, but honorably; craft (the
12 * Message Judge's roll modifier) and a well-calibrated anachronism wager push a
13 * thoughtful run to roughly +12..16/turn, where victory is earned rather than
14 * drawn from a lottery. Dice still dominate any single turn; judgment decides
15 * the campaign.
16 */
17export interface SwingBand {
18    /** Most negative end of the band's instructed range, in progress points. */
19    min: number
20    /** Most positive end of the band's instructed range, in progress points. */
21    max: number
22}
23 
24export const SWING_BANDS: Record<DiceOutcome, SwingBand> = {
25    [DiceOutcome.CRITICAL_SUCCESS]: { min: 30, max: 45 },
26    [DiceOutcome.SUCCESS]: { min: 15, max: 30 },
27    [DiceOutcome.NEUTRAL]: { min: 0, max: 12 },
28    [DiceOutcome.FAILURE]: { min: -15, max: -5 },
29    [DiceOutcome.CRITICAL_FAILURE]: { min: -35, max: -15 }
30}
31 
32/**
33 * The largest base magnitude any band allows — the integer range stated to the
34 * model (±45). Derived, not re-typed; the hard safety clamp in game-config
35 * (±MAX_PROGRESS_SWING) stays slightly wider so the anachronism amplifier has
36 * headroom above the bands.
37 */
38export const BAND_CEILING = Math.max(
39    ...Object.values(SWING_BANDS).flatMap(b => [Math.abs(b.min), Math.abs(b.max)])
40)
41 
42/**
43 * The neutral window for the Timeline Engine's valence sign-guard: a resolved swing
44 * whose magnitude exceeds this must wear the color of its sign (a "positive" badge on
45 * a clear loss reads as arbitrary), while a smaller swing keeps the model's shading.
46 * Applied once in callTimelineAI on the pre-stake swing and re-asserted in
47 * send-message.post.ts on a doubled (staked) swing — named once so the two can't drift.
48 */
49export const VALENCE_SIGN_GUARD_MIN = 3
50 
51/**
52 * The last stand: when the FINAL dispatch of a run can no longer win inside the
53 * normal fuse (the gap exceeds MAX_PROGRESS_SWING — the store's `canStake`),
54 * the player may STAKE THE TIMELINE — the resolved swing doubles, both ways,
55 * and escapes the per-turn cap up to the full meter. Structurally this means no
56 * run is ever mathematically dead while a message remains. Deliberately NOT
57 * offered from winnable positions: doubling never lowers win odds on a final
58 * throw, so an unrestricted stake would be a dominance trap, not a decision.
59 * The doubling itself is applied server-side after amplification.
60 */
61export const STAKE_MULTIPLIER = 2
62export const STAKED_SWING_CAP = 100
63 
64/** One-line hover hint for the ⚑ stake badge — the last-stand wager. */
65export const STAKE_HINT = 'the last stand, only on your final dispatch — doubles the swing, both ways'
66 
67export function applyStake(progressChange: number): number {
68    const staked = Math.round(progressChange * STAKE_MULTIPLIER)
69    return Math.max(-STAKED_SWING_CAP, Math.min(STAKED_SWING_CAP, staked))
70}

The swing pipeline — exactly the order the note claims

The note describes how one turn's swing is built. Here is that pipeline in callTimelineAI, verbatim. Read it top to bottom: rolled band → anachronism amplify → causal decay → gains-only craft × momentum → clamp to the ±50 fuse. (The stake doubling, on a final staked dispatch only, is applied later, server-side.)

The single place the economy resolves; the note's pipeline section maps 1:1 to this.

callTimelineAI — the swing composition · 577 lines

callTimelineAI — the swing composition577 lines · TypeScript

⋯ 229 lines hidden (lines 1–229)1/**
* The game's AI layers. Historically OpenAI-only (hence the filename, kept to
* avoid churning every reference); today each layer is routed per task through
* the AI gateway (ai-gateway.ts) to its bake-off-chosen lane — Anthropic tiers
* by default, the OpenAI lane alive behind REVISIONIST_AI_LANE.
*
* Every layer keeps the same contract it always had: build prompt → structured
* call → parse → guard → never-throw envelope. The catch-block console.errors
* are intentional (ops signal, not debug cruft).
*/
11import {
  buildCharacterPrompt,
  buildTimelinePrompt,
  buildChroniclePrompt,
  buildChroniclePromptClaude,
  buildResearchPrompt,
  buildLookupPrompt,
  buildJudgePrompt,
  type ObjectiveContext,
  type TimelineContextEntry,
  type CharacterGrounding,
  type ChronicleStatus,
  type FigureStudy,
  type ArchiveLookup
25} from './prompt-builder'
26import { completeStructured, ModelRefusalError, type ChatTurn } from './ai-gateway'
27import { routeFor } from './ai-routing'
28import { amplifyForAnachronism, toAnachronism, type Anachronism } from './anachronism'
29import { chainStatus, decayForChain, type ChainStatus } from '~/utils/causal-chain'
30import { toCraft, CRAFT_LEVELS, CRAFT_MODIFIER, CRAFT_GAIN_FACTOR, type Craft } from '~/utils/craft'
31import { toContinuity, CONTINUITY_LEVELS, type Continuity } from '~/utils/continuity'
32import type { DiceOutcome } from '~/utils/dice'
33import { BAND_CEILING, SWING_BANDS, VALENCE_SIGN_GUARD_MIN } from '~/utils/swing-bands'
34import { MAX_PROGRESS_SWING } from '~/utils/game-config'
35import { momentumFactor } from '~/utils/momentum'
36 
37/**
* What a figure returns each turn: an in-character reply and action, plus factual
* metadata (era, persona) the UI uses to label them.
*/
41export interface StructuredCharacterResponse {
  message: string
  action: string
  era: string
  persona: string
46}
47 
48export interface CharacterAIResponse {
  success: boolean
  characterResponse?: StructuredCharacterResponse
  error?: string
  /** Claude's own safety classifier declined this turn (stop_reason refusal) —
   *  the caller surfaces it as a moderation block, not an infra refund. */
  refused?: boolean
55}
56 
57/**
* The Timeline Engine's verdict for a turn: how history bent.
*/
60export interface TimelineRipple {
  headline: string
  detail: string
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — kept so the UI can
   *  show the wager's work ("+8 ⚡ far-ahead → +11%") instead of an opaque total. */
  baseProgressChange: number
  valence: 'positive' | 'negative' | 'neutral'
  /** How far beyond the figure's era the player reached — widens the swing. */
  anachronism: Anachronism
  /** How far this moment lands from the nearest foothold (objective anchor or a
   *  prior change) — DECAYS the swing toward zero. Absent for ungrounded turns
   *  or anchorless objectives (the dial no-ops). The opposite of anachronism. */
  causalChain?: ChainStatus
74}
75 
76export interface TimelineAIResponse {
  success: boolean
  ripple?: TimelineRipple
  error?: string
  /** Model-side safety refusal — surfaced as a block, not an infra refund. */
  refused?: boolean
82}
83 
84/**
* The Chronicler's telling: a titled, multi-paragraph prose account of the altered
* timeline as it currently stands. Rewritten each turn; the final one is the epilogue.
*/
88export interface ChronicleEntry {
  title: string
  paragraphs: string[]
91}
92 
93export interface ChronicleAIResponse {
  success: boolean
  chronicle?: ChronicleEntry
  error?: string
97}
98 
99interface HistoryItem { text: string; sender: string }
100 
101/**
* Maps the stored conversation thread into chat turns. The thread is expected to
* end with the current user message; if it doesn't (e.g. a direct call with no
* history), the current message is appended so the figure has it.
*/
106function toChatMessages(conversationHistory: HistoryItem[], currentUserMessage: string): ChatTurn[] {
  const mapped: ChatTurn[] = (conversationHistory || [])
      .filter(m => m && typeof m.text === 'string' && m.sender !== 'system')
      .map(m => ({
          role: (m.sender === 'user' ? 'user' : 'assistant') as 'user' | 'assistant',
          content: m.text
      }))
113 
  const last = mapped[mapped.length - 1]
  if (!last || last.role !== 'user' || last.content !== currentUserMessage) {
      mapped.push({ role: 'user', content: currentUserMessage })
  }
  return mapped
119}
120 
121/**
* Layer 1 — role-plays the chosen figure (any name, any era), objective-blind,
* returning a structured reply + action + factual era/persona metadata.
*/
125export async function callCharacterAI(
  figureName: string,
  userMessage: string,
  conversationHistory: HistoryItem[] = [],
  diceOutcome: DiceOutcome,
  grounding?: CharacterGrounding,
  worldBrief?: string[],
  /** True when the dispatch carries no actionable substance — keeps the figure
   *  honest so a favorable roll on noise yields confusion, not a fabricated deed. */
  contentless?: boolean
135): Promise<CharacterAIResponse> {
  try {
      const content = await completeStructured({
          task: 'character',
          system: buildCharacterPrompt(figureName, diceOutcome, grounding, worldBrief, contentless),
          turns: toChatMessages(conversationHistory, userMessage),
          schemaName: 'character_response',
          schema: {
              type: 'object',
              properties: {
                  message: { type: 'string', description: `${figureName}'s in-character reply, 160 chars max` },
                  action: { type: 'string', description: `The concrete thing ${figureName} decides to do` },
                  era: { type: 'string', description: 'Short factual when/where tag, e.g. "Vienna, 1914"' },
                  persona: { type: 'string', description: 'A 3-6 word factual descriptor of the figure' }
              },
              required: ['message', 'action', 'era', 'persona'],
              additionalProperties: false
          }
      })
154 
      if (!content) {
          return { success: false, error: 'Character AI generated an empty response' }
      }
158 
      const parsed = JSON.parse(content) as StructuredCharacterResponse
      if (!parsed.message || !parsed.action) {
          return { success: false, error: 'Character AI response missing required fields' }
      }
163 
      return { success: true, characterResponse: parsed }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This dispatch was declined by content moderation and cannot be sent.' }
      }
      console.error('Character AI error:', error)
      return { success: false, error: 'Character AI could not process the request' }
  }
172}
173 
174/**
* Layer 2 — judges how the figure's action ripples through the already-altered
* world toward the live objective, returning a structured timeline ripple.
*/
178export async function callTimelineAI(args: {
  objective: ObjectiveContext
  figureName: string
  era: string
  userMessage: string
  characterMessage: string
  characterAction: string
  diceRoll: number
  diceOutcome: DiceOutcome
  timeline?: TimelineContextEntry[]
  figureYear?: number
  figureMoment?: string
  /** The objective's far anchor year — a foothold for the causal-chain dial. */
  objectiveAnchorYear?: number
  /** The Judge's craft grade for this dispatch — drives the gains-only craft
   *  amplifier (issue #62). Absent → no amplification (factor 1). */
  craft?: Craft
  /** The run's PRE-turn momentum (0..4) — the run-level gains amplifier that rides
   *  alongside craft. Absent → no amplification (factor 1). */
  momentum?: number
198}): Promise<TimelineAIResponse> {
  try {
      const content = await completeStructured({
          task: 'timeline',
          system: buildTimelinePrompt({ ...args, timeline: args.timeline ?? [] }),
          schemaName: 'timeline_ripple',
          schema: {
              type: 'object',
              properties: {
                  headline: { type: 'string', description: 'Punchy headline, ~9 words max' },
                  detail: { type: 'string', description: '1-2 sentences describing the ripple through history' },
                  progressChange: { type: 'integer', description: `Integer from -${BAND_CEILING} to ${BAND_CEILING}, within the rolled band` },
                  valence: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
                  anachronism: { type: 'string', enum: ['in-period', 'ahead', 'far-ahead', 'impossible'], description: 'How far beyond the figure’s era the message reached' }
              },
              required: ['headline', 'detail', 'progressChange', 'valence', 'anachronism'],
              additionalProperties: false
          }
      })
217 
      if (!content) {
          return { success: false, error: 'Timeline AI generated an empty response' }
      }
221 
      const parsed = JSON.parse(content)
      if (typeof parsed.headline !== 'string' || typeof parsed.detail !== 'string' || typeof parsed.progressChange !== 'number') {
          return { success: false, error: 'Timeline AI response missing required fields' }
      }
226 
      // The band table is law — in code, not just prompt: the model's base swing
      // is clamped into the ROLLED band before the amplifier touches it, so the
      // disclosed legend and the engine can never disagree about a roll's range.
      const band = SWING_BANDS[args.diceOutcome]
      const baseProgress = Math.max(band.min, Math.min(band.max, Math.round(parsed.progressChange)))
      const anachronism = toAnachronism(parsed.anachronism)
      const amplified = amplifyForAnachronism(baseProgress, anachronism)
      // Causal-chain decay (the opposite dial): a reach far from any foothold is
      // diffused toward zero. Footholds are the objective's anchor year plus every
      // dated change already on the ledger — so landing a change plants a new
      // foothold and chaining forward overcomes the distance. No-ops (factor 1)
      // for ungrounded turns or anchorless objectives.
      const footholds = [args.objectiveAnchorYear, ...(args.timeline ?? []).map(e => e.whenSigned)]
      const causalChain = chainStatus(args.figureYear, footholds) ?? undefined
      const decayed = causalChain ? decayForChain(amplified, causalChain.factor) : amplified
      // Gains-only amplifiers (issue #62): a sharper dispatch (craft) and a more
      // coherent arc (momentum) each bank more of the band the roll earned — but ONLY
      // on the upside. Losses keep the rolled band's verdict untouched (mirrors
      // amplifyForAnachronism's sign branch), so skill buys reach, never immunity.
      // After this the value can exceed the per-turn fuse, and nothing downstream
      // re-clamps an UPWARD push before the (post-stake) ±100 cap — so re-clamp to
      // ±MAX_PROGRESS_SWING here.
      const craftFactor = args.craft ? CRAFT_GAIN_FACTOR[args.craft] : 1
      const momoFactor = momentumFactor(args.momentum ?? 0)
      const gained = decayed > 0 ? decayed * craftFactor * momoFactor : decayed
      const progressChange = Math.max(-MAX_PROGRESS_SWING, Math.min(MAX_PROGRESS_SWING, Math.round(gained)))
⋯ 325 lines hidden (lines 253–577)253        const modelValence: TimelineRipple['valence'] =
          parsed.valence === 'positive' || parsed.valence === 'negative' || parsed.valence === 'neutral'
              ? parsed.valence
              : (progressChange > 0 ? 'positive' : progressChange < 0 ? 'negative' : 'neutral')
      // Sign guard: a swing beyond the neutral window (±3, the eval's own line)
      // must wear the color of its sign — a "positive" badge on a -12 turn is a
      // straight "this game is arbitrary" signal. Small swings keep the model's
      // shading, where "neutral" or a soft contradiction is fair judgment.
      const signValence: TimelineRipple['valence'] = progressChange > 0 ? 'positive' : 'negative'
      const valence = Math.abs(progressChange) > VALENCE_SIGN_GUARD_MIN ? signValence : modelValence
263 
      return {
          success: true,
          ripple: { headline: parsed.headline, detail: parsed.detail, progressChange, baseProgressChange: baseProgress, valence, anachronism, causalChain }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This dispatch was declined by content moderation and cannot be sent.' }
      }
      console.error('Timeline AI error:', error)
      return { success: false, error: 'Timeline AI could not process the request' }
  }
275}
276 
277/**
* The Message Judge (roadmap slice 5) — grades the craft of the player's dispatch
* BEFORE the dice are thrown; the grade becomes a small roll modifier. Objective-
* aware (it judges leverage toward the goal) but outcome-blind: it never sees the
* roll. A failure here must never punish the player — callers fall back to the
* neutral 'sound' (modifier 0), so a Judge outage just means an untilted die.
*/
284export interface JudgeVerdict {
  craft: Craft
  /** Whether the dispatch builds on the run's thread — feeds the momentum meter
   *  (issue #62). 'neutral' on turn 1 or a Judge outage (never moves momentum). */
  continuity: Continuity
  reason: string
290}
291 
292export interface JudgeAIResponse {
  success: boolean
  judge?: JudgeVerdict
  error?: string
296}
297 
298export async function callJudgeAI(args: {
  objective: ObjectiveContext
  figureName: string
  when?: string
  momentRefined?: boolean
  userMessage: string
  /** The figure's reply on the PRIOR turn — their last revealed condition/price.
   *  Empty on turn 1. The Judge reads it to see if THIS dispatch meets it. */
  lastFigureReply?: string
  /** A short digest of recent ledger headlines so the Judge can spot a dispatch
   *  that deliberately exploits a change already on the record. */
  ledgerDigest?: string[]
310}): Promise<JudgeAIResponse> {
  try {
      // With a pinned moment the schema gains two leading fields: "event"
      // makes the model WRITE OUT the real event and its real-world date, so
      // the "timing" enum right after it compares two dates sitting on the
      // page instead of inferring silently inside one token. Probed 24/24 on
      // Haiku and Sonnet where a bare timing enum failed 0/12 — date retrieval
      // must be a generation step, not an implication. The CAP is still
      // enforced in code below (legend-is-law, like the band clamp).
      const timingFields = args.momentRefined
          ? {
              event: {
                  type: 'string',
                  description: 'The real recorded historical event this dispatch is trying to influence, and the exact real-world date it occurred (e.g. "the Hindenburg disaster at Lakehurst — May 6, 1937")'
              },
              timing: {
                  type: 'string',
                  enum: ['in-time', 'too-late'],
                  description: '"too-late" if the event\'s real date above is earlier than the stated moment the dispatch arrives — its chance already spent; otherwise "in-time"'
              }
          }
          : {}
      // Continuity is read only when there's a thread to build on. On turn 1 (no
      // prior reply, empty ledger) the prompt + schema stay byte-identical to the
      // pre-feature build and continuity defaults to 'neutral' — momentum can't
      // build out of nothing anyway.
      const hasThread = !!(args.lastFigureReply || args.ledgerDigest?.length)
      const continuityField = hasThread
          ? {
              continuity: {
                  type: 'string',
                  enum: [...CONTINUITY_LEVELS],
                  description: '"builds" if this dispatch meets a condition/price the figure just revealed, deliberately exploits a change already on the record, or coheres with and escalates the run\'s strategy; "resets" if it abandons that thread and starts cold; "neutral" otherwise'
              }
          }
          : {}
      const content = await completeStructured({
          task: 'judge',
          system: buildJudgePrompt(args),
          schemaName: 'craft_verdict',
          schema: {
              type: 'object',
              properties: {
                  ...timingFields,
                  craft: { type: 'string', enum: [...CRAFT_LEVELS], description: 'The dispatch’s craft grade' },
                  ...continuityField,
                  reason: { type: 'string', description: 'One terse player-facing sentence, under 90 characters' }
              },
              required: [...(args.momentRefined ? ['event', 'timing'] : []), 'craft', ...(hasThread ? ['continuity'] : []), 'reason'],
              additionalProperties: false
          }
      })
362 
      if (!content) {
          return { success: false, error: 'Judge generated an empty response' }
      }
366 
      const parsed = JSON.parse(content) as { timing?: unknown; craft?: unknown; continuity?: unknown; reason?: unknown }
      let craft = toCraft(parsed.craft)
      // The closed-door cap, in code: a too-late pin grades vague at best.
      if (args.momentRefined && parsed.timing === 'too-late' && CRAFT_MODIFIER[craft] > CRAFT_MODIFIER.vague) {
          craft = 'vague'
      }
      return {
          success: true,
          judge: {
              craft,
              continuity: toContinuity(parsed.continuity),
              reason: typeof parsed.reason === 'string' ? parsed.reason.trim().slice(0, 120) : ''
          }
      }
  } catch (error) {
      console.error('Judge AI error:', error)
      return { success: false, error: 'Judge could not assess the dispatch' }
  }
385}
386 
387/**
* The Archivist (prototype) — a grounded, OBJECTIVE-BLIND brief on a real figure at
* a chosen point in their life: who they are, what they grasp, what they're reaching
* for, and what lies beyond their era. In-game research so the player needn't break
* out to a search engine — it enriches the world, never makes their move.
*/
393export interface ArchivistAIResponse {
  success: boolean
  study?: FigureStudy
  error?: string
  /** Claude's own safety classifier declined the study — surfaced as a moderation
   *  block (the study-blocked banner), not an infra failure. */
  refused?: boolean
400}
401 
402export async function callArchivistAI(args: {
  figureName: string
  when?: string
  description?: string
  extract?: string
407}): Promise<ArchivistAIResponse> {
  try {
      const content = await completeStructured({
          task: 'archivist-study',
          system: buildResearchPrompt(args),
          schemaName: 'figure_study',
          schema: {
              type: 'object',
              properties: {
                  atThisMoment: { type: 'string', description: 'Where the figure stands in life and work at the chosen moment' },
                  grasp: { type: 'array', items: { type: 'string' }, description: '2-4 things they genuinely understand' },
                  reaching: { type: 'array', items: { type: 'string' }, description: '2-4 things they pursue or are stuck on' },
                  cannotYetKnow: { type: 'string', description: 'One sentence on what lies beyond their era' }
              },
              required: ['atThisMoment', 'grasp', 'reaching', 'cannotYetKnow'],
              additionalProperties: false
          }
      })
425 
      if (!content) {
          return { success: false, error: 'Archivist generated an empty response' }
      }
429 
      const parsed = JSON.parse(content) as { atThisMoment?: unknown; grasp?: unknown; reaching?: unknown; cannotYetKnow?: unknown }
      const asStrings = (v: unknown): string[] =>
          Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string' && s.trim().length > 0) : []
      const grasp = asStrings(parsed.grasp)
      const reaching = asStrings(parsed.reaching)
      if (typeof parsed.atThisMoment !== 'string' || !parsed.atThisMoment.trim() || (!grasp.length && !reaching.length)) {
          return { success: false, error: 'Archivist response missing required fields' }
      }
438 
      return {
          success: true,
          study: {
              atThisMoment: parsed.atThisMoment.trim(),
              grasp,
              reaching,
              cannotYetKnow: typeof parsed.cannotYetKnow === 'string' ? parsed.cannotYetKnow.trim() : ''
          }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'This study was declined by content moderation.' }
      }
      console.error('Archivist AI error:', error)
      return { success: false, error: 'Archivist could not process the request' }
  }
455}
456 
457/**
* The Archive lookup (prototype, "yellow") — a concise, factual answer to a freeform
* topic query, stamped with when the knowledge first emerged so the player can read
* its anachronism. Pure domain facts (what/ingredients/when), never strategy.
*/
462export interface ArchiveLookupResponse {
  success: boolean
  lookup?: ArchiveLookup
  error?: string
  /** Claude's own safety classifier declined the lookup — surfaced as a moderation
   *  block (the lookup-blocked banner), not an infra failure. */
  refused?: boolean
469}
470 
471export async function callArchiveLookupAI(query: string): Promise<ArchiveLookupResponse> {
  try {
      const content = await completeStructured({
          task: 'archive-lookup',
          system: buildLookupPrompt(query),
          schemaName: 'archive_lookup',
          schema: {
              type: 'object',
              properties: {
                  topic: { type: 'string', description: 'Short title for what was asked' },
                  summary: { type: 'string', description: 'One or two plain sentences — the essential fact' },
                  requires: { type: 'array', items: { type: 'string' }, description: 'Concrete ingredients / prerequisites, or empty' },
                  knownSince: { type: 'string', description: 'When/where this knowledge first emerged' }
              },
              required: ['topic', 'summary', 'requires', 'knownSince'],
              additionalProperties: false
          }
      })
489 
      if (!content) {
          return { success: false, error: 'Archive generated an empty response' }
      }
493 
      const parsed = JSON.parse(content) as { topic?: unknown; summary?: unknown; requires?: unknown; knownSince?: unknown }
      if (typeof parsed.topic !== 'string' || typeof parsed.summary !== 'string' || !parsed.summary.trim()) {
          return { success: false, error: 'Archive response missing required fields' }
      }
      const requires = Array.isArray(parsed.requires)
          ? parsed.requires.filter((s): s is string => typeof s === 'string' && s.trim().length > 0)
          : []
501 
      return {
          success: true,
          lookup: {
              topic: parsed.topic.trim() || query,
              summary: parsed.summary.trim(),
              requires,
              knownSince: typeof parsed.knownSince === 'string' ? parsed.knownSince.trim() : ''
          }
      }
  } catch (error) {
      if (error instanceof ModelRefusalError) {
          return { success: false, refused: true, error: 'That lookup was declined by content moderation.' }
      }
      console.error('Archive lookup error:', error)
      return { success: false, error: 'Archive could not process the request' }
  }
518}
519 
520/**
* Layer 3 — the Chronicler. Narrates the whole altered timeline as it now stands,
* rewritten each turn from the running ledger. It judges nothing, so a failure is
* non-fatal: the caller simply keeps the prior telling rather than blanking the panel.
*
* The FINAL telling (victory/defeat) is the run's epilogue — the share artifact —
* and routes as its own task so the flagship model can carry that one moment.
*/
528export async function callChroniclerAI(args: {
  objective: ObjectiveContext
  timeline: TimelineContextEntry[]
  status: ChronicleStatus
  progress: number
533}): Promise<ChronicleAIResponse> {
  try {
      const task = args.status === 'playing' ? 'chronicler' : 'epilogue'
      // Prompts are per-model artifacts: the Claude voice won its lane in
      // blind pairwise (see buildChroniclePromptClaude); the incumbent voice
      // stays exactly as-is for the OpenAI lane, so the fallback lever keeps
      // its tuned prompt too.
      const { lane } = routeFor(task)
      const content = await completeStructured({
          task,
          system: lane === 'anthropic' ? buildChroniclePromptClaude(args) : buildChroniclePrompt(args),
          schemaName: 'chronicle',
          schema: {
              type: 'object',
              properties: {
                  title: { type: 'string', description: 'Short, evocative title for this version of history (3-6 words)' },
                  paragraphs: {
                      type: 'array',
                      items: { type: 'string' },
                      description: '2-4 short paragraphs of prose, in reading order'
                  }
              },
              required: ['title', 'paragraphs'],
              additionalProperties: false
          }
      })
559 
      if (!content) {
          return { success: false, error: 'Chronicle AI generated an empty response' }
      }
563 
      const parsed = JSON.parse(content) as { title?: unknown; paragraphs?: unknown }
      const paragraphs = Array.isArray(parsed.paragraphs)
          ? parsed.paragraphs.filter((p): p is string => typeof p === 'string' && p.trim().length > 0)
          : []
      if (typeof parsed.title !== 'string' || !parsed.title.trim() || paragraphs.length === 0) {
          return { success: false, error: 'Chronicle AI response missing required fields' }
      }
571 
      return { success: true, chronicle: { title: parsed.title.trim(), paragraphs } }
  } catch (error) {
      console.error('Chronicle AI error:', error)
      return { success: false, error: 'Chronicle AI could not process the request' }
  }
577}

Why presets, not sliders

The corridor is tuned against TOTAL_MESSAGES and MAX_PROGRESS together. Cut messages 5 → 3 and unaided play yields ≈ +18 while the per-turn band ceiling is +45 — the win now demands ≈ +33/turn, near-impossible inside the bands. So a preset cannot move message count or the win bar and leave the bands alone; they move as one bundle. That single fact drives the entire design.

The note's coupling argument · 353 lines

The note's coupling argument353 lines · Markdown

⋯ 95 lines hidden (lines 1–95)1# Game Settings Layer — difficulty, run shape, constraints
2 
3> **Design exploration for [#90](https://github.com/mseeks/revisionist/issues/90).** This is a
4> recommendation, not an implementation. No `RunSettings` schema, no settings UI, no
5> retuning of the live curve — just the design space, a recommended v1, and the
6> implementation issues this note should spawn. For what is true in the code today,
7> read [`../../CLAUDE.md`](../../CLAUDE.md); for forward intent, [`../ROADMAP.md`](../ROADMAP.md).
8 
9## TL;DR — the recommendation
10 
11Ship a **lean v1**: three difficulty **presets** as the primary surface, **two run-shape
12dials** exposed directly, and a **deterministic seed** plumbed in (no UI yet). Defer
13everything else.
14 
15| v1 (ship) | v2 (next) | Deferred / never |
16|---|---|---|
17| **Difficulty presets:** Story · Standard · Iron | Per-dial **Custom** overrides | Daily challenge, score normalization |
18| **Messages per run** (run length) | Timeline-window constraints (era clamp, chronological-only) | Message length (it's core identity — leave fixed) |
19| **Distinct-figures cap** (incl. single-figure) | Sandbox / "anywhen" stance (its own slice) | Paid-gating (note the question; don't decide) |
20| **Seed** (plumbing only — basis for sharing/replay) | Repeat-contact + grounded-only policies | — |
21 
22Four load-bearing decisions, each argued below:
23 
241. **Presets bundle the dials; they are not independent sliders.** The run economy is a
25   tuned system. A preset must move the band economy *with* message count and win
26   threshold, or the win rate breaks.
272. **`RunSettings` is a small serializable bundle, chosen at mission-select**, stored in
28   the run, validated server-side. Design it serializable from day one so a shared run
29   (`#88`/`#89`) can carry its rules + seed.
303. **Safety never moves.** Difficulty can make the *game* harder or easier; it can never
31   relax the server-authoritative safety floor (`#72` deceased-only, `#71` objective
32   bounds, the swing clamp, moderation). Those stay closed-enum and server-enforced.
334. **Every preset needs eval coverage** so a retune can't silently regress the EV
34   corridor the economy rests on.
35 
36## Today: one fixed configuration
37 
38The game ships as a single, well-tuned configuration. Every rule is a named constant —
39already centralized, just not player-facing. The cross-module ones live in
40[`utils/game-config.ts`](../../utils/game-config.ts); the rest sit per-module by design.
41 
42| Constant | Value | File | Controls |
43|---|---|---|---|
44| `TOTAL_MESSAGES` | `5` | `utils/game-config.ts` | dispatches allotted per run |
45| `MAX_PROGRESS` | `100` | `utils/game-config.ts` | win threshold (progress is clamped 0..100) |
46| `MAX_PROGRESS_SWING` | `50` | `utils/game-config.ts` | the per-turn fuse (hard clamp on a resolved swing) |
47| `MAX_MESSAGE_CHARS` | `160` | `utils/game-config.ts` | chars per dispatch |
48| `SWING_BANDS` | CF −35..−15 · F −15..−5 · N 0..+12 · S +15..+30 · CS +30..+45 | `utils/swing-bands.ts` | the D20 band → progress table (the run economy) |
49| dice faces | CF 1–2 · F 3–8 · N 9–12 · S 13–18 · CS 19–20 (2/6/4/6/2) | `utils/dice.ts` | the natural-roll distribution |
50| `STAKE_MULTIPLIER` / `STAKED_SWING_CAP` | `2` / `100` | `utils/swing-bands.ts` | the last-stand wager on a final dispatch |
51| `CRAFT_MODIFIER` / `CRAFT_GAIN_FACTOR` | ±2 roll / ×0.15–1.45 gain | `utils/craft.ts` | the Message Judge's two channels |
52| `MOMENTUM_MAX` / `MOMENTUM_STEP` | `4` / `0.1` (cap ×1.4) | `utils/momentum.ts` | the run-level gains amplifier |
53| `BRIDGE_FREE` / `SCALE` / `CHAIN_FLOOR` | `75` / `550` / `0.12` | `utils/causal-chain.ts` | causal-chain decay |
54| `GAIN_FACTOR` / `LOSS_FACTOR` / `KNEE` | ×1–1.6 / ×1–2 / `40` | `server/utils/anachronism.ts` | the future-knowledge wager |
55| `SAFELY_HISTORICAL_BEFORE_YEAR` | (the floor) | `server/utils/historical-floor.ts` | the safely-dead / safely-historical line (`#71`/`#72`) |
56 
57`utils/game-config.ts` is the natural seam for a settings layer — but its own header says
58only *cross-module* rules belong there; many dials are intentionally local. Part of the
59work is deciding **which constants get promoted into a player-facing `RunSettings`** and
60which stay internal.
61 
62## The core risk: the economy is a tuned system, not free dials
63 
64This is the whole reason these aren't already settings, and the reason a difficulty
65"level" must be a **bundle** rather than a row of independent sliders.
66 
67**The EV corridor.** With the documented face distribution (2/6/4/6/2 over 20) and the
68band midpoints, the expected swing for *sound, unaided* play (craft modifier 0, no wager,
69no chain, no momentum) is:
70 
71```
72P(CF)=0.10  P(F)=0.30  P(N)=0.20  P(S)=0.30  P(CS)=0.10
73mid:  −25       −10       +6        +22.5       +37.5
74EV = .10(−25) + .30(−10) + .20(6) + .30(22.5) + .10(37.5) ≈ +6.2 / turn
75```
76 
77That matches the tuning intent stated in `utils/swing-bands.ts` ("roughly +6/turn" for
78sound play). Over `TOTAL_MESSAGES = 5` turns that is ≈ **+31 of 100** — an *honorable
79loss*. The gap to 100 is what craft, a calibrated anachronism wager, and momentum are
80meant to close, so victory is earned rather than drawn from a lottery.
81 
82**The pipeline that produces a turn's swing** (`callTimelineAI`,
83`server/utils/openai.ts`), in order:
84 
851. Roll a D20; **craft modifier (±2)** shifts the roll (clamped 1–20) → this picks the band.
862. Model proposes a swing; it is **clamped into the rolled band** (`SWING_BANDS`).
873. **Anachronism amplifier** (`amplifyForAnachronism`) widens both signs, asymmetric
88   (gains ×1.15/1.35/1.6, losses ×1.25/1.6/2), soft knee above ±40, re-clamped to ±50.
894. **Causal-chain decay** (`decayForChain`) diffuses both signs toward zero by distance
90   from the nearest foothold (floor 0.12).
915. **Gains-only** multipliers: positive swing × `CRAFT_GAIN_FACTOR` × `momentumFactor`.
92   Losses are never scaled — skill buys reach, never immunity.
936. **Clamp to ±`MAX_PROGRESS_SWING`** (the per-turn fuse).
947. On a final *staked* dispatch only: `applyStake` doubles, clamp ±100.
95 
96**Why the coupling bites.** The corridor is calibrated against `TOTAL_MESSAGES` *and*
97`MAX_PROGRESS` together:
98 
99- Cut messages 5 → 3 and unaided play yields ≈ +18, while the per-turn band ceiling is
100  +45 (`BAND_CEILING`). The win now demands ≈ +33/turn average — near-impossible inside
101  the bands. The run is "harder" by accident, not design.
102- Raise the win threshold 100 → 150 and the same thing happens from the other side.
103- Widen the per-turn fuse and the stake's drama collapses (every turn can already swing
104  the meter).
105 
106So a difficulty preset cannot change message count or win threshold *and leave the bands
107alone*. The bands, the message count, and the threshold move **together**, as one tuned
108bundle, validated by eval. This single fact drives the entire design: **presets, not
109sliders.**
110 
111The honest framing for a preset: it sets a *target* unaided-finish ratio (today ≈ 0.31 of
112the win bar) and a target aided EV, then derives the dials to hit them. There is one
113genuinely clean exception, and it points at the simplest KISS move: **message count
114re-prices the run while leaving every per-turn artifact byte-identical** (bands, dice,
115legend, prompt calibration all unchanged). The pragmatic call is to let message count *be*
116a difficulty axis — Story = more messages, Iron = fewer — and accept that the corridor
117ratio moves with it, rather than re-scaling the bands to hold the ratio constant. Document
118the shift as the intended knob.
⋯ 235 lines hidden (lines 119–353)119 
120### Gotchas the implementation must handle
121 
122Making these constants settings exposes seams that are invisible today because the values
123happen to line up:
124 
125- **Coincidentally-equal literals must become derived.** `STAKED_SWING_CAP` is a hardcoded
126  `100` (`utils/swing-bands.ts`), *not* a reference to `MAX_PROGRESS`. They are equal by
127  intent (a staked throw sweeps the whole meter) but would silently diverge the moment the
128  win threshold becomes a setting. Same risk anywhere a tuning value re-derives a
129  game-config number by hand.
130- **Re-typed eval constants would desync.** The ±3 valence window and the 160-char cap are
131  re-typed inside the eval fixtures, not imported. A preset touching them desyncs the evals
132  from the game silently. Promote them to imports first.
133- **`BAND_CEILING ≤ MAX_PROGRESS_SWING` is a pinned invariant** (`swing-bands.spec.ts`). Any
134  preset that reshapes the bands has to re-check it, or the amplifier loses its headroom.
135 
136## What gets promoted vs stays internal
137 
138A clean split keeps the settings surface small and the safety/tuning invariants intact.
139 
140**Promote into `RunSettings` (player-facing, per run):**
141 
142- `messagesPerRun` (← `TOTAL_MESSAGES`) — the cleanest standalone run-shape knob.
143- `winThreshold` (← `MAX_PROGRESS`) — only via presets (it re-tunes the corridor).
144- `distinctFiguresCap` — a *new* constraint (none today); 1 = single-thread challenge.
145- `difficulty` — a preset id that *bundles* the tuning dials below.
146- `seed` — deterministic dice; plumbing now, surfaced later for sharing/replay.
147 
148**Keep internal, scaled only *through* a preset (never a raw slider):** the band table,
149the dice reshaping, `CRAFT_*`, `MOMENTUM_*`, the anachronism factors, the chain decay,
150the stake. These are the tuning dials; exposing them raw is how a player breaks the
151curve. A v2 "Custom" mode can open a curated subset behind an advanced panel.
152 
153**Keep internal and immovable (safety):** `isDeceased` / `SAFELY_HISTORICAL_BEFORE_YEAR`
154(`#72`), the objective bounds (`#71`), the in-code band clamp, and moderation
155(`REVISIONIST_MODERATION`). Difficulty does not get a vote here.
156 
157**Leave fixed:** `MAX_MESSAGE_CHARS = 160`. The 160-char discipline is core identity and
158an eval'd Character-layer invariant; making it a dial dilutes the game's signature
159constraint for little variety.
160 
161## The candidate catalog, triaged
162 
163The issue's brainstorm (groups A–G), cut to a v1 verdict. The full rationale for the
164"economy" rows is the section above.
165 
166| Candidate | Maps to | Verdict | Why |
167|---|---|---|---|
168| Messages per run | `TOTAL_MESSAGES` | **v1 dial** | cleanest run-shape lever; couples to the corridor, so its retune rides the preset |
169| Distinct-figures cap | new constraint | **v1 dial** | adds real variety (single-figure run), no economy coupling, server-checkable |
170| Difficulty preset | bundles the tuning dials | **v1 (primary)** | the only safe way to move the coupled economy |
171| Win threshold | `MAX_PROGRESS` | **v1, preset-only** | moves the corridor — must ride a preset, never a free slider |
172| Per-turn fuse | `MAX_PROGRESS_SWING` | **internal** | a safety clamp + the stake's basis; not a player knob |
173| Roll variance / band reshape | dice + bands | **internal (preset-scaled)** | the corridor itself |
174| Craft weight / anachronism / decay / momentum / stake | the tuning dials | **internal (preset-scaled)** | exposing raw breaks tuning |
175| Timeline-window constraints (era clamp, chronological-only) | new, atop the when-slider | **v2** | strong variety, but needs its own UX + eval; lifetime bound already exists |
176| Sandbox / "anywhen" | drop lifetime + safely-dead bounds | **deferred (own slice)** | collides with the safety floor; a deliberate separate stance, not a difficulty knob |
177| Repeat-contact / grounded-only | figure policy | **v2** | grounded-only is already the floor (`#73`); repeat-contact is a light add |
178| Safely-dead cutoff relax | `#72` floor | **never (as difficulty)** | safety, server-authoritative — cannot be a difficulty lever |
179| Objective source / steering / anchor visibility / reroll cap | `#71`, objective compose | **v2** | ties to objective work, not the core economy |
180| Assist (tutorial, scaffolding, archive access) | `#60`, UI | **folds into presets** | Story shows scaffolding; Iron hides it + caps research |
181| Seed | new | **v1 (plumbing)** | the basis for fair sharing/replay; cheap to land early |
182| Daily challenge / speedrun / score normalization | meta modes | **deferred** | depend on seed + sharing; design after the bundle exists |
183 
184## The v1 proposal: three presets
185 
186Three is the right number: an on-ramp, the tuned default, and a brutal mode — from one
187engine. The dial values below are **illustrative targets to be validated by eval**, not
188final tuning (the issue forbids re-tuning the live curve here; this just shows *where*
189each preset would re-tune it).
190 
191| Dimension | **Story** (on-ramp) | **Standard** (today) | **Iron** (veteran) |
192|---|---|---|---|
193| Target unaided EV/turn | higher (~+9) | ~+6 (today) | lower (~+4) |
194| Messages per run | 6–7 | **5** | 4 |
195| Win threshold | 100 | **100** | 100 (decisive feel via tighter economy, not a higher bar) |
196| Band economy | gentler losses, fatter Success | **today** | harsher losses, leaner gains |
197| Anachronism penalty | softened | **today** | harsher losses |
198| Causal-chain decay | gentler | **today** | steeper (chaining matters more) |
199| Last stand (stake) | on | **on** | **off** (no safety net) |
200| Scaffolding (band table, pace hint, ⚡/⏳ chips) | all shown | **shown** | hidden |
201| Archive (research) | unlimited | **unlimited** | capped or disabled |
202| Guided first-run (`#60`) | on | default | off |
203 
204Standard *is* the current configuration — shipping presets must not change today's game.
205Story and Iron are symmetric moves outward from it, each a coherent bundle rather than a
206pile of toggles. Note that "harder" on Iron comes mostly from a leaner economy and a
207removed safety net, **not** from raising the win bar — keeping the meter legible.
208 
209## Surface, persistence, and travel
210 
211**Presets over a wall of sliders.** The mission-select briefing
212([`components/MissionSelect.vue`](../../components/MissionSelect.vue)) gains one row: a
213three-way difficulty chip plus the two run-shape dials (messages, figure cap). That is
214the entire v1 surface. A "Custom" disclosure (per-dial overrides) is explicitly v2.
215 
216**Where settings live.** A run starts when the player commits an objective
217(`chooseObjective` in `stores/game.ts`; a null `currentObjective` is what surfaces the
218briefing). `RunSettings` is authored in the same briefing — a sibling fieldset to the
219existing era/theme steer dials, closed enums, committed only on Begin — threaded through
220`chooseObjective` into **one new `runSettings` state field cleared by `resetGame`**, and
221read by `sendMessage` and the pure dials. Because it carries only pre-run choices (no
222dates, no server `runId`, none of the staleness/account plumbing), it round-trips through
223JSON or a URL param cleanly — which is exactly what makes it the right unit to travel with
224a run. It must work for **anonymous** players (the default path today). A saved profile
225default is a later tie to accounts (`#83`), layered on top — the per-run choice is the
226primitive.
227 
228**Settings travel with a run.** There is **no run snapshot, share, or seed concept in the
229code today** — a run is entirely live and ephemeral. That makes this greenfield, and it
230argues for designing `RunSettings` as a **small serializable bundle from the start**, next
231to a `seed`. For shared-run "beat this" (`#88`) and replay (`#89`) to be *fair*, the
232snapshot has to carry both the rules and the seed; otherwise two players aren't playing
233the same game. The seed is the one piece worth plumbing in v1 even before daily/seeded
234modes ship, because retrofitting determinism later is far more invasive than reserving the
235field now (the dice live behind `rollD20` in `utils/dice.ts` — a single, swappable source).
236 
237## Safety stays server-authoritative
238 
239Several knobs are server-enforced and closed-enum on purpose: the deceased-only contact
240floor (`isDeceased`, `server/utils/figure-grounding.ts`, fail-closed — a figure with no
241confirmed death is never contactable), the objective bounds (`#71`), the in-code clamp of
242the engine's swing into the rolled band, and moderation. A settings layer **must not
243become a client bypass.** Concretely:
244 
245- `RunSettings` is **validated and clamped server-side**, to an allowed range per field —
246  the client's chosen values are untrusted input, like every other field. This is the
247  pattern already in place: `send-message.post.ts` and `research.post.ts` **re-ground the
248  figure name** against the untrusted payload rather than trusting a client claim of "this
249  person is contactable."
250- Difficulty scales the *game* (harder/easier), never the *safety floor*. There is no
251  difficulty that lets you message a living person or dodge moderation. A Sandbox / "anywhen"
252  stance that *did* relax the lifetime + deceased-only bounds (its own deferred slice, not a
253  difficulty knob) would flip a **server-read** flag, never a client toggle the POST handler
254  honors — and moderation (`REVISIONIST_MODERATION`) is never surfaced to players at all;
255  `off` is an operator/calibration lever only.
256- The closed enums stay closed. A preset id is one of a fixed set; an out-of-range message
257  count or figure cap is rejected, not honored.
258 
259## Evals: a preset can't silently break the curve
260 
261The tuning expectations already live as evals, and a new difficulty knob has to extend
262them or it can regress the curve invisibly:
263 
264- [`evals/bakeoff.eval.ts`](../../evals/bakeoff.eval.ts) scores **the NEUTRAL-band EV
265  corridor the run economy is tuned around** — the exact invariant a preset's retune
266  threatens.
267- [`evals/behavior.eval.ts`](../../evals/behavior.eval.ts) checks the model-behavior
268  invariants the mechanics rest on (band steering, `sharp ≥ vague` craft ordering,
269  anachronism accuracy).
270- [`evals/causal-chain.eval.ts`](../../evals/causal-chain.eval.ts) confirms stepping
271  stones beat blasts end-to-end; [`evals/judge-tune.eval.ts`](../../evals/judge-tune.eval.ts)
272  pins craft-grade anchoring (which feeds the economy).
273 
274But the existing coverage has two gaps a preset would fall straight through, and naming
275them is half the value of this exploration:
276 
2771. **The corridor eval guards the wrong number.** It scores `baseProgressChange` — the swing
278   *before* the anachronism / causal-chain / craft-gain / momentum multipliers. So the four
279   downstream multipliers are an **unguarded realized-EV surface**: a "hard" preset that
280   halved `CRAFT_GAIN_FACTOR` would change the EV the player actually experiences while the
281   corridor eval stayed green. The `[4,9]` corridor is a real invariant, but it is *not* the
282   EV the run is won or lost on.
2832. **The corridor bounds are hardcoded literals, not a function of the preset.** If Story
284   legitimately targets a higher neutral EV and Iron a lower one, today's absolute `[4,9]`
285   assertion would flag the *intended* presets as misses. The corridor eval has to become
286   **preset-parameterized** — fed each preset's target band.
287 
288**Requirement for the implementation:** each shipped preset needs (a) a parameterized
289pre-multiplier corridor assertion fed its own target, and (b) a **realized-EV** assertion
290that composes the full pipeline (so a multiplier change can't move the curve unseen) and a
291plausible win rate at sound + calibrated play. The pure dials (bands, decay, momentum,
292craft) are already unit-tested in isolation; the new surface to cover is *the composition
293under each preset*.
294 
295## Scope & monetization
296 
297v1 is deliberately small: presets + two dials + seed plumbing. The open question worth
298**noting, not deciding here**: whether any setting (e.g. seeded/daily competitive modes,
299or an Iron leaderboard) is paid-gated. The accounts/paywall seam already exists (`#83`,
300the runs economy); this note flags the question and leaves the call to the monetization
301track.
302 
303## Recommended v1, restated
304 
305- **Surface:** three difficulty presets (Story · Standard · Iron) + two run-shape dials
306  (messages per run, distinct-figures cap), chosen at mission-select. Custom per-dial
307  overrides deferred to v2.
308- **Model:** a small serializable `RunSettings` bundle (`difficulty`, `messagesPerRun`,
309  `distinctFiguresCap`, `seed`), validated + clamped server-side, stored in the run,
310  anonymous-friendly, profile-default later (`#83`).
311- **Economy:** each preset re-tunes the bundle (message count + band economy + the wager /
312  decay / momentum / stake) **together**, with Standard == today's game unchanged.
313- **Travel:** plumb a deterministic `seed` now; carry `RunSettings` + `seed` in the run
314  snapshot when sharing/replay (`#88`/`#89`) lands.
315- **Guardrails:** safety floor untouched and server-authoritative; an EV-corridor eval per
316  preset.
317 
318## Implementation issues this note spawns
319 
320Ready-to-file, in dependency order:
321 
3221. **`RunSettings` bundle + server validation + seed plumbing.** Define the serializable
323   type (`difficulty`, `messagesPerRun`, `distinctFiguresCap`, `seed`), thread it through
324   the store run-state and `sendMessage`, validate + clamp server-side, and route the dice
325   through a seeded source behind `rollD20`. No UI beyond a default. *Foundation for the
326   rest.*
3272. **Difficulty presets + economy retune + eval coverage.** Implement Story/Standard/Iron
328   as preset bundles that scale the internal tuning dials together; Standard reproduces
329   today's curve exactly. Make the corridor eval **preset-parameterized** and add a
330   **realized-EV** assertion (full pipeline, not just `baseProgressChange`) per preset.
331   First promote the re-typed eval constants (±3 valence, 160-char) to imports and derive
332   `STAKED_SWING_CAP` from the win threshold so nothing diverges silently. *Depends on 1.*
3333. **Run-shape dials at mission-select.** Surface `messagesPerRun` and
334   `distinctFiguresCap` (incl. the single-figure challenge) in `MissionSelect.vue`, with
335   the figure cap enforced server-side. *Depends on 1; pairs with 2 for the message-count
336   retune.*
3374. **Settings + seed travel with a shared run.** Carry `RunSettings` + `seed` in the run
338   snapshot so a shared/replayed run is the same game. *Depends on 1 and on `#88`/`#89`.*
339 
340## Explicitly out of scope (per #90)
341 
342No implementation, no final `RunSettings` schema, no settings UI here. No commitment to the
343final set — this is divergent brainstorming plus a recommendation. Not a re-tuning of the
344existing curve; this only identifies *where* each difficulty would re-tune it.
345 
346---
347 
348*Related:* [#83](https://github.com/mseeks/revisionist/issues/83) (accounts — saved
349defaults) · [#88](https://github.com/mseeks/revisionist/issues/88) /
350[#89](https://github.com/mseeks/revisionist/issues/89) (sharing & replay — why a run
351should carry its settings + seed) · [#71](https://github.com/mseeks/revisionist/issues/71)
352(objective steering) · [#72](https://github.com/mseeks/revisionist/issues/72) (safely-dead
353floor) · [#60](https://github.com/mseeks/revisionist/issues/60) (guided first-run).

Safety stays server-authoritative

A settings layer must never become a client bypass. The deceased-only contact floor (#72) is the clearest case: it's fail-closed and server-enforced. Difficulty can scale the game; it can never relax this.

A figure with no confirmed death is never contactable. Re-checked server-side against the untrusted payload in the send/research handlers.

isDeceased — fail-closed · 325 lines

isDeceased — fail-closed325 lines · TypeScript

⋯ 59 lines hidden (lines 1–59)1/**
* Real-world grounding for historical figures — the backbone of the "timeline RPG"
* direction (see docs/ROADMAP.md). Resolves a free-form name to solid facts so the
* game can show who someone was, validate *when* you may contact them, and feed the
* role-play real dates.
*
* Pipeline (the wiki APIs are open + key-less):
*   1. Wikipedia REST summary — the reliable resolver. It follows redirects and
*      picks the notable article, giving a canonical title, a one-line description,
*      a blurb, a portrait, and the Wikidata item id. (Wikidata search alone is NOT
*      reliable: "Cleopatra" resolves to "female given name", "Genghis Khan" to an
*      Iron Maiden song.)
*   2. Wikidata, looked up by that item id (title as fallback) — structured birth
*      (P569) / death (P570), taking the best-ranked claim that actually carries a
*      date, with sub-year precision surfaced honestly as `circa`.
*   3. If the record still has no birth year, a small AI estimator bridges the gap
*      with circa dates (issue #31) — so a real, resolvable figure keeps their
*      "when" slider even when Wikidata can't date them.
*
* Anything unresolved returns `{ resolved: false }` (with `transient` set when the
* lookup couldn't complete). Contact callers now BLOCK an ungrounded name (#73) —
* only a real, documented figure can be reached — while a transient miss is a retry.
*
* Cache honesty: only definitive answers — a real Wikidata reply (dated or not,
* with the estimator genuinely consulted), a genuine no-such-article miss, a
* disambiguation page — keep the full TTL. A transient failure anywhere on the
* path (a rate-limit 429, a timeout, an estimator outage) gets a short TTL, so
* one blip never poisons a figure for a day.
*/
30import { estimateLifespan } from './lifespan-estimator'
31import { SAFELY_HISTORICAL_BEFORE_YEAR } from './historical-floor'
32 
33/** A year on the timeline. `signed` is AD-positive / BCE-negative for comparison. */
34export interface FigureYear {
  year: number
  bce: boolean
  signed: number
  display: string
  /** Approximate: sub-year Wikidata precision (decade/century/…) or an AI estimate. */
  circa?: boolean
41}
42 
43export interface GroundedFigure {
  name: string
  resolved: boolean
  description?: string
  extract?: string
  born?: FigureYear
  died?: FigureYear
  living?: boolean
  thumbnail?: string
  wikiUrl?: string
  /** The lookup couldn't be completed (rate-limit / timeout / outage), so an
   *  unresolved result is "we don't know yet", not "no such person". The contact
   *  gate treats this as a retry rather than a definitive miss — and never as a
   *  free-form pass (#72 / #73). */
  transient?: boolean
58}
59 
60/**
* The deceased-only contact floor (#72): a figure may be reached only once we can
* confirm they have died. A resolved figure with no death year is living (or not
* datable enough to prove otherwise) and is never contactable — fail closed. An
* unresolved name is not deceased here either (the free-form path is removed in #73).
* The canonical predicate, shared by the suggester and the send-message gate; the
* client store inlines the same rule (it can't import this server-only module).
*/
68export function isDeceased(figure: GroundedFigure): boolean {
  return figure.resolved && !!figure.died
70}
⋯ 255 lines hidden (lines 71–325)71 
72/**
* The one header for every Wikipedia / Wikidata call the server makes — grounding,
* the name autocomplete, and the suggester's lookups all share it (issue #58).
* Wikimedia's User-Agent policy wants the client identified plus a reachable CONTACT
* so an operator can be reached about problematic traffic; an agent without one gets
* throttled harder, and rate-limit blips are the dominant real-world failure for the
* autocomplete. A mailto is that contact — the deployed site is auth-gated and the
* repo private, so neither would reach a human. Exported so every caller sends the
* identical compliant string instead of drifting per-feature copies.
*/
82export const WIKI_HEADERS = {
  accept: 'application/json',
  'User-Agent': 'Revisionist/1.0 (timeline RPG; mailto:matthew@mseeks.me)'
85}
86 
87const FULL_TTL_MS = 24 * 60 * 60 * 1000
88const TRANSIENT_TTL_MS = 10 * 60 * 1000
89const WIKIDATA_RETRY_DELAY_MS = 400
90const cache = new Map<string, { value: GroundedFigure; expires: number }>()
91 
92/** Builds a `FigureYear`; the display string owns the "c." honesty marker. */
93export function makeFigureYear(year: number, bce: boolean, circa = false): FigureYear {
  const base = bce ? `${year} BC` : `${year}`
  return {
      year,
      bce,
      signed: bce ? -year : year,
      display: circa ? `c. ${base}` : base,
      ...(circa ? { circa: true } : {})
  }
102}
103 
104/**
* Parses a Wikidata time literal (e.g. "+1856-07-10T..", "-0069-01-13T..") to a year.
* Precision 9 means year-level; anything below (8 decade, 7 century, 6 millennium)
* still carries a representative year in the literal, but only approximately —
* those parse as `circa` rather than being dropped or displayed as exact.
*/
110export function parseWikidataYear(time?: string, precision?: number): FigureYear | undefined {
  if (!time) return undefined
  const m = /^([+-])0*(\d+)-/.exec(time)
  if (!m) return undefined
  const year = parseInt(m[2], 10)
  if (!year) return undefined
  const bce = m[1] === '-'
  return makeFigureYear(year, bce, precision != null && precision < 9)
118}
119 
120/** The slice of the Wikipedia REST summary we actually read. */
121interface WikiSummary {
  type?: string
  title?: string
  description?: string
  extract?: string
  thumbnail?: { source?: string }
  content_urls?: { desktop?: { page?: string } }
  wikibase_item?: string
129}
130 
131/** The slice of a Wikidata date claim we actually read. */
132interface WikidataClaim {
  rank?: string
  mainsnak?: {
      snaktype?: string
      datavalue?: { value?: { time?: string; precision?: number } }
  }
138}
139 
140/** The slice of the Wikidata `wbgetentities` response we actually read. */
141interface WikidataEntities {
  entities?: Record<string, { claims?: Record<string, WikidataClaim[]> }>
143}
144 
145/**
* The best date a claim list actually carries. Wikidata routinely stacks several
* birth/death claims (scholarly guesses, deprecated values, "unknown value"
* placeholders) and the community-preferred one is often NOT first — Moses, Jesus
* and Confucius all keep theirs at index 2. So: only claims whose snak carries a
* real time (somevalue/novalue snaks don't), never deprecated, preferred rank first.
*/
152export function pickClaimYear(claims?: WikidataClaim[]): FigureYear | undefined {
  const usable = (claims ?? []).filter(c =>
      c.rank !== 'deprecated' &&
      c.mainsnak?.snaktype === 'value' &&
      c.mainsnak.datavalue?.value?.time
  )
  const best = usable.find(c => c.rank === 'preferred') ?? usable[0]
  const value = best?.mainsnak?.datavalue?.value
  return parseWikidataYear(value?.time, value?.precision)
161}
162 
163/**
* A fetch that tells a definitive miss from a transient one: 404 means the thing
* genuinely isn't there (cacheable at full TTL), anything else — 429, 5xx, timeout,
* network error — is weather to retry soon, not remember for a day.
*/
168interface FetchOutcome<T> {
  data: T | null
  transient: boolean
171}
172 
173async function fetchJson<T>(url: string): Promise<FetchOutcome<T>> {
  try {
      const res = await fetch(url, { headers: WIKI_HEADERS, signal: AbortSignal.timeout(6000) })
      if (!res.ok) return { data: null, transient: res.status !== 404 }
      return { data: (await res.json()) as T, transient: false }
  } catch {
      return { data: null, transient: true }
  }
181}
182 
183interface WikidataDates {
  born?: FigureYear
  died?: FigureYear
  /** True when we never got a real answer (so the result must not cache long). */
  transient: boolean
188}
189 
190/**
* Birth/death from Wikidata — by item id when the summary supplied one (immune to
* title-matching quirks), by sitelink title otherwise. Rate-limit blips are the
* dominant way dates go missing in practice (a 429 body carries no `entities`), so
* a no-entities response gets one spaced retry before being declared transient.
*/
196async function wikidataDates(qid: string | undefined, title: string): Promise<WikidataDates> {
  const subject = qid
      ? `ids=${encodeURIComponent(qid)}`
      : `sites=enwiki&titles=${encodeURIComponent(title)}&normalize=1`
  const url = `https://www.wikidata.org/w/api.php?action=wbgetentities&${subject}&props=claims&languages=en&format=json&origin=*`
  let outcome = await fetchJson<WikidataEntities>(url)
  if (!outcome.data?.entities) {
      await new Promise(resolve => setTimeout(resolve, WIKIDATA_RETRY_DELAY_MS))
      outcome = await fetchJson<WikidataEntities>(url)
  }
  const entities = outcome.data?.entities
  if (!entities) return { transient: true }
  const id = Object.keys(entities)[0]
  const claims = id ? entities[id]?.claims : undefined
  return { born: pickClaimYear(claims?.P569), died: pickClaimYear(claims?.P570), transient: false }
211}
212 
213/**
* Resolves a name to grounded facts (cached). Never throws; returns
* `{ resolved: false }` when the figure can't be confidently identified.
*/
217export async function groundFigure(rawName: string): Promise<GroundedFigure> {
  const name = (rawName || '').trim()
  if (!name) return { name: '', resolved: false }
220 
  const key = name.toLowerCase()
  const hit = cache.get(key)
  if (hit && hit.expires > Date.now()) return hit.value
224 
  const { value, ttlMs } = await resolve(name)
  cache.set(key, { value, expires: Date.now() + ttlMs })
  return value
228}
229 
230/**
* Keep a URL only if it's a plain http(s) link — drop `javascript:` / `data:` /
* relative values. These come from a remote Wikipedia response and end up bound to
* `:href` / `:src` in the figure dossier; Vue escapes the value but NOT the scheme,
* so a spoofed `javascript:` URL would execute on click. (Surfaced by the
* unsafe-render loop.) Exported for the figure-search route, which binds Wikipedia
* thumbnails the same way.
*/
238export function safeUrl(url?: string): string | undefined {
  if (!url) return undefined
  try {
      const { protocol } = new URL(url)
      return protocol === 'https:' || protocol === 'http:' ? url : undefined
  } catch {
      return undefined
  }
246}
247 
248interface Resolution {
  value: GroundedFigure
  ttlMs: number
251}
252 
253/** A purely AI-estimated death is only trusted as "historical" (and the figure
*  contactable, #72) when it predates this year — a recent estimated death is the
*  least trustworthy signal and could mark a living person dead. Documented deaths
*  are exempt (they're facts). The same safely-historical line the objective bounds
*  reuse (#71), sourced once from historical-floor so the two never drift. */
258const ESTIMATED_DEATH_HISTORICAL_BEFORE = SAFELY_HISTORICAL_BEFORE_YEAR
259 
260async function resolve(name: string): Promise<Resolution> {
  const summary = await fetchJson<WikiSummary>(
      `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(name)}`
  )
264 
  // No article, or an ambiguous disambiguation page → can't pin a person.
  const article = summary.data
  if (!article || article.type === 'disambiguation' || !article.title) {
      return {
          value: { name, resolved: false, transient: summary.transient },
          ttlMs: summary.transient ? TRANSIENT_TTL_MS : FULL_TTL_MS
      }
  }
273 
  const title: string = article.title
275 
  const dates = await wikidataDates(article.wikibase_item, title)
  let born = dates.born
  let died = dates.died
  let bridgeTransient = false
280 
  // The AI bridge (issue #31): the record knows WHO they are but not WHEN — either
  // Wikidata genuinely has no usable birth claim, or the lookup is down right now.
  // Estimated years arrive marked circa, so the dossier and prompts stay honest.
  // A recorded death is law: the estimate only fills what the record lacks, and an
  // estimate that contradicts the record (born after the documented death) is
  // dropped whole rather than shipped as an incoherent lifespan.
  if (!born) {
      const bridge = await estimateLifespan(title, article.description, article.extract, died?.display)
      bridgeTransient = bridge.transient
      if (bridge.estimate) {
          const estBorn = makeFigureYear(bridge.estimate.born.year, bridge.estimate.born.bce, true)
          if (!died || estBorn.signed <= died.signed) {
              born = estBorn
              // A purely AI-ESTIMATED death is trusted as "deceased" (the floor in
              // #72) only when it's clearly historical. An LLM guess of a RECENT
              // death is exactly what could mark a living person contactable, so we
              // don't promote it — the figure stays `living` and is blocked. A
              // DOCUMENTED death (already in `died`) is a fact and is kept as-is.
              const estDied = bridge.estimate.died
                  ? makeFigureYear(bridge.estimate.died.year, bridge.estimate.died.bce, true)
                  : undefined
              died = died ?? (estDied && estDied.signed <= ESTIMATED_DEATH_HISTORICAL_BEFORE ? estDied : undefined)
          }
      }
  }
306 
  return {
      value: {
          name: title,
          resolved: true,
          description: article.description || undefined,
          extract: article.extract || undefined,
          born,
          died,
          living: !!born && !died,
          thumbnail: safeUrl(article.thumbnail?.source),
          wikiUrl: safeUrl(article.content_urls?.desktop?.page),
          transient: dates.transient || bridgeTransient
      },
      // Anything short of a definitive answer keeps the short TTL: a transient
      // Wikidata miss (even when the estimator papered over it — the next lookup
      // should get a shot at the real dates) and an estimator outage alike.
      ttlMs: dates.transient || bridgeTransient ? TRANSIENT_TTL_MS : FULL_TTL_MS
  }
325}

The eval gap the exploration surfaced

The sharpest finding, and one a reviewer should verify in source. The EV-corridor eval scores baseProgressChange — the swing before the anachronism / causal-chain / craft-gain / momentum multipliers. So those four downstream multipliers are an unguarded realized-EV surface: a 'hard' preset that halved CRAFT_GAIN_FACTOR would change the EV the player actually experiences while this eval stayed green. And the bound is a hardcoded literal.

Line 110 means over r.baseProgressChange (pre-multiplier); line 123 hardcodes >= 4 && <= 9.

The corridor assertion · 372 lines

The corridor assertion372 lines · TypeScript

⋯ 107 lines hidden (lines 1–107)1/**
* The provider bake-off (GTM dispatch 1) — the same fixtures driven down BOTH
* lanes of the per-task routing seam, scored per layer:
*
*   Timeline  — band→swing ordering, the NEUTRAL-band EV corridor the run
*               economy is tuned around, valence↔sign, anachronism accuracy.
*   Judge     — calibration against the labeled craft ladders (ordinal
*               agreement + hard fairness violations), the Haiku gate.
*   Character — dice-band differential, 160-char discipline, era-blindness.
*   Chronicler— blind pairwise prose (position-debiased, dual-graded), plus a
*               ledger-consistency gate; the epilogue judged separately.
*   Cost      — real usage per lane from the gateway's telemetry observer.
*
* Run with: `npm run eval:bakeoff` (needs OPENAI_API_KEY + ANTHROPIC_API_KEY).
* Results land in evals/results/ as JSON alongside the printed scorecard.
* Lane passes are sequential; REVISIONIST_AI_LANE flips the whole seam per pass.
*/
18import { describe, it, afterAll } from 'vitest'
19import { mkdirSync, writeFileSync } from 'node:fs'
20import { resolve } from 'node:path'
21import { DiceOutcome } from '~/utils/dice'
22import { callCharacterAI, callTimelineAI, callChroniclerAI, callJudgeAI } from '~/server/utils/openai'
23import { setAiCallObserver, type AiCallTelemetry } from '~/server/utils/ai-gateway'
24import { CRAFT_MODIFIER } from '~/utils/craft'
25import { RUN, record, recordedRows, sample, gradeAll, prefer, mean, printScorecard } from './harness'
26import {
  ROLL_BY_BAND,
  TIMELINE_FIXED,
  ANACHRONISM_INPERIOD,
  ANACHRONISM_FUTURE,
  CHARACTER,
  OBJECTIVE
33} from './fixtures'
34import { JUDGE_LADDERS, EPILOGUE_LEDGER, CHRONICLE_CRITERIA } from './bakeoff-fixtures'
35 
36const LANES = ['anthropic', 'openai'] as const
37type Lane = (typeof LANES)[number]
38 
39/** Samples per cell — sized for a decision, not a census; paired across lanes. */
40const N_TIMELINE = 10
41const N_ANACHRONISM = 8
42const N_JUDGE = 2
43const N_CHARACTER = 8
44const K_CHRONICLE = 5
45 
46/** Anthropic list prices per MTok (verified 2026-06); OpenAI reported as tokens. */
47const ANTHROPIC_PRICES: Record<string, { input: number; output: number }> = {
  'claude-haiku-4-5': { input: 1, output: 5 },
  'claude-sonnet-4-6': { input: 3, output: 15 },
  'claude-opus-4-8': { input: 5, output: 25 }
51}
52 
53interface UsageCell { calls: number; input: number; output: number }
54const usageByLane: Record<Lane, Record<string, UsageCell>> = { anthropic: {}, openai: {} }
55let currentLane: Lane = 'anthropic'
56 
57function collect(t: AiCallTelemetry): void {
  if (!t.usage) return
  const key = `${t.task}:${t.model}`
  const cell = (usageByLane[currentLane][key] ??= { calls: 0, input: 0, output: 0 })
  cell.calls++
  cell.input += t.usage.inputTokens
  cell.output += t.usage.outputTokens
64}
65 
66function enterLane(lane: Lane): void {
  currentLane = lane
  process.env.REVISIONIST_AI_LANE = lane
  setAiCallObserver(collect)
70}
71 
72/** Everything the JSON snapshot carries, accumulated across the it-blocks. */
73const results: Record<string, unknown> = { lanes: {} }
74function laneResults(lane: Lane): Record<string, unknown> {
  const lanes = results.lanes as Record<string, Record<string, unknown>>
  return (lanes[lane] ??= {})
77}
78 
79const chronicles: Record<Lane, { mid: string[]; epilogue: string[] }> = {
  anthropic: { mid: [], epilogue: [] },
  openai: { mid: [], epilogue: [] }
82}
83 
84afterAll(() => {
  setAiCallObserver(null)
  delete process.env.REVISIONIST_AI_LANE
  printScorecard()
88})
89 
90function skip(layer: string, invariant: string): void {
  record({ layer, invariant, result: 'skipped (needs both keys)', status: 'skipped' })
92}
93 
94for (const lane of LANES) {
  describe(`${lane} lane`, () => {
      it('timeline: bands, corridor, anachronism', async () => {
          if (!RUN) {
              skip(`TL·${lane}`, 'band ordering / corridor / anachronism')
              return
          }
          enterLane(lane)
102 
          const bandMeans: number[] = []
          let vOK = 0
          let vTotal = 0
          for (const band of ROLL_BY_BAND) {
              const res = await sample(N_TIMELINE, () =>
                  callTimelineAI({ ...TIMELINE_FIXED, diceRoll: band.roll, diceOutcome: band.outcome }))
              const ripples = res.flatMap(r => (r.success && r.ripple ? [r.ripple] : []))
              bandMeans.push(Math.round(mean(ripples.map(r => r.baseProgressChange)) * 10) / 10)
              for (const r of ripples) {
                  vTotal++
                  const s = r.progressChange
                  if ((r.valence === 'positive' && s > 0) || (r.valence === 'negative' && s < 0) || (r.valence === 'neutral' && Math.abs(s) <= 3)) vOK++
              }
          }
          let ordered = 0
          for (let i = 1; i < bandMeans.length; i++) if (bandMeans[i] >= bandMeans[i - 1]) ordered++
          // The run economy is tuned around ~+6/turn for sound unaided play —
          // the NEUTRAL band (0..+12) is the anchor; a lane whose neutral mean
          // drifts out of [4, 9] silently rebalances the whole game.
          const neutralMean = bandMeans[2]
          const corridorOK = neutralMean >= 4 && neutralMean <= 9
124 
⋯ 248 lines hidden (lines 125–372)125            const inP = await sample(N_ANACHRONISM, () =>
              callTimelineAI({ ...ANACHRONISM_INPERIOD, diceRoll: 12, diceOutcome: DiceOutcome.NEUTRAL }))
          const fut = await sample(N_ANACHRONISM, () =>
              callTimelineAI({ ...ANACHRONISM_FUTURE, diceRoll: 12, diceOutcome: DiceOutcome.NEUTRAL }))
          const inLevels = inP.flatMap(r => (r.success && r.ripple ? [r.ripple.anachronism] : []))
          const futLevels = fut.flatMap(r => (r.success && r.ripple ? [r.ripple.anachronism] : []))
          const inOK = inLevels.filter(a => a === 'in-period' || a === 'ahead').length
          const futOK = futLevels.filter(a => a === 'far-ahead' || a === 'impossible').length
133 
          laneResults(lane).timeline = {
              bandMeans, ordered, neutralMean, corridorOK,
              valence: { ok: vOK, total: vTotal },
              anachronism: { inOK, inTotal: inLevels.length, futOK, futTotal: futLevels.length }
          }
          record({
              layer: `TL·${lane}`,
              invariant: 'band means + ordering',
              result: vTotal === 0 ? 'no samples' : `[${bandMeans.join(', ')}] · ${ordered}/4 ordered`,
              status: vTotal === 0 ? 'error' : ordered >= 4 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `TL·${lane}`,
              invariant: 'neutral EV corridor [4..9]',
              result: `mean ${neutralMean}`,
              status: vTotal === 0 ? 'error' : corridorOK ? 'ok' : 'soft-miss'
          })
          record({
              layer: `TL·${lane}`,
              invariant: 'valence↔sign',
              result: `${vOK}/${vTotal}`,
              status: vTotal > 0 && vOK / vTotal >= 0.9 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `TL·${lane}`,
              invariant: 'anachronism accuracy',
              result: `in-period ${inOK}/${inLevels.length} · future ${futOK}/${futLevels.length}`,
              status: inLevels.length + futLevels.length > 0 && (inOK + futOK) / (inLevels.length + futLevels.length) >= 0.75 ? 'ok' : 'soft-miss'
          })
      })
164 
      it('judge: calibration ladders', async () => {
          if (!RUN) {
              skip(`JD·${lane}`, 'ladder calibration')
              return
          }
          enterLane(lane)
171 
          let orderedPairs = 0
          let totalPairs = 0
          let hardViolations = 0
          const ladderMeans: number[][] = []
          for (const ladder of JUDGE_LADDERS) {
              const rungMeans: number[] = []
              for (const dispatch of ladder.rungs) {
                  const res = await sample(N_JUDGE, () =>
                      callJudgeAI({ objective: ladder.objective, figureName: ladder.figureName, when: ladder.when, userMessage: dispatch }))
                  const mods = res.flatMap(r => (r.success && r.judge ? [CRAFT_MODIFIER[r.judge.craft]] : []))
                  rungMeans.push(mean(mods))
                  // Fairness floor: the bottom two rungs must never read masterful
                  // (+2), the top rung must never read reckless (-2).
                  const rungIndex = ladder.rungs.indexOf(dispatch)
                  if (rungIndex >= 2 && mods.some(m => m >= 2)) hardViolations++
                  if (rungIndex === 0 && mods.some(m => m <= -2)) hardViolations++
              }
              ladderMeans.push(rungMeans)
              for (let i = 0; i < rungMeans.length; i++) {
                  for (let j = i + 1; j < rungMeans.length; j++) {
                      totalPairs++
                      if (rungMeans[i] >= rungMeans[j]) orderedPairs++
                  }
              }
          }
197 
          laneResults(lane).judge = { ladderMeans, orderedPairs, totalPairs, hardViolations }
          record({
              layer: `JD·${lane}`,
              invariant: 'ladder ordinal agreement',
              result: `${orderedPairs}/${totalPairs} pairs ordered`,
              status: totalPairs > 0 && orderedPairs / totalPairs >= 0.9 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `JD·${lane}`,
              invariant: 'hard violations',
              result: `${hardViolations}`,
              status: hardViolations === 0 ? 'ok' : 'soft-miss'
          })
      })
212 
      it('character: differential, discipline, era-blindness', async () => {
          if (!RUN) {
              skip(`CH·${lane}`, 'differential / 160 / era')
              return
          }
          enterLane(lane)
219 
          const succ = await sample(N_CHARACTER, () =>
              callCharacterAI(CHARACTER.figureName, CHARACTER.nudgeMessage, [], DiceOutcome.CRITICAL_SUCCESS, CHARACTER.grounding))
          const fail = await sample(N_CHARACTER, () =>
              callCharacterAI(CHARACTER.figureName, CHARACTER.nudgeMessage, [], DiceOutcome.CRITICAL_FAILURE, CHARACTER.grounding))
          const succR = succ.flatMap(r => (r.success && r.characterResponse ? [r.characterResponse] : []))
          const failR = fail.flatMap(r => (r.success && r.characterResponse ? [r.characterResponse] : []))
226 
          const q = `Does the figure decisively and favorably act toward this goal — "${CHARACTER.nudgeGoal}"? Answer yes only if they clearly move to do it.`
          const sG = await gradeAll(q, succR.map(a => a.action))
          const fG = await gradeAll(q, failR.map(a => a.action))
          const sRate = sG.graded ? sG.yes / sG.graded : 0
          const fRate = fG.graded ? fG.yes / fG.graded : 0
232 
          const all = [...succR, ...failR]
          const within = all.filter(a => a.message.length <= 160).length
235 
          const future = await sample(N_CHARACTER, () =>
              callCharacterAI(CHARACTER.figureName, CHARACTER.futureMessage, [], DiceOutcome.NEUTRAL, CHARACTER.grounding))
          const futureReplies = future.flatMap(r => (r.success && r.characterResponse ? [r.characterResponse.message] : []))
          const eraQ = 'Does this reply treat events beyond the speaker’s own lifetime as established fact, or acknowledge knowing the future / being in a game? Answer yes if it breaks the historical illusion.'
          const eraG = await gradeAll(eraQ, futureReplies)
241 
          laneResults(lane).character = {
              actToward: { success: sG, fail: fG },
              len160: { within, total: all.length },
              eraBreaks: eraG
          }
          record({
              layer: `CH·${lane}`,
              invariant: 'band→reaction differential',
              result: `crit-succ ${sG.yes}/${sG.graded} · crit-fail ${fG.yes}/${fG.graded} (${sG.contested + fG.contested} contested)`,
              status: sG.graded && fG.graded ? (sRate > fRate ? 'ok' : 'soft-miss') : 'error'
          })
          record({
              layer: `CH·${lane}`,
              invariant: 'reply ≤160 chars',
              result: `${within}/${all.length}`,
              status: all.length > 0 && within / all.length >= 0.8 ? 'ok' : 'soft-miss'
          })
          record({
              layer: `CH·${lane}`,
              invariant: 'no future-as-fact',
              result: `${eraG.graded - eraG.yes}/${eraG.graded} stay in-era (${eraG.contested} contested)`,
              status: eraG.graded > 0 && eraG.yes / eraG.graded <= 0.25 ? 'ok' : 'soft-miss'
          })
      })
266 
      it('chronicler: generate tellings (judged cross-lane later)', async () => {
          if (!RUN) {
              skip(`CR·${lane}`, 'tellings generated')
              return
          }
          enterLane(lane)
273 
          const mid = await sample(K_CHRONICLE, () =>
              callChroniclerAI({ objective: OBJECTIVE, timeline: EPILOGUE_LEDGER.slice(0, 3), status: 'playing', progress: 55 }))
          const epi = await sample(K_CHRONICLE, () =>
              callChroniclerAI({ objective: OBJECTIVE, timeline: EPILOGUE_LEDGER, status: 'victory', progress: 100 }))
          chronicles[lane].mid = mid.flatMap(r => (r.success && r.chronicle ? [`${r.chronicle.title}\n${r.chronicle.paragraphs.join('\n')}`] : []))
          chronicles[lane].epilogue = epi.flatMap(r => (r.success && r.chronicle ? [`${r.chronicle.title}\n${r.chronicle.paragraphs.join('\n')}`] : []))
280 
          const facts = 'These facts are TRUE: (1) Caesar spared the library from fire; (2) Cleopatra endowed it; (3) Octavian later spared Alexandria and endowed the Museion. Does the narrative CONTRADICT any of these (e.g. the library burns or is lost)? Answer yes if it contradicts.'
          const g = await gradeAll(facts, [...chronicles[lane].mid, ...chronicles[lane].epilogue])
283 
          laneResults(lane).chronicler = { consistency: g, midCount: chronicles[lane].mid.length, epilogueCount: chronicles[lane].epilogue.length }
          record({
              layer: `CR·${lane}`,
              invariant: 'ledger consistency',
              result: `${g.graded - g.yes}/${g.graded} consistent (${g.contested} contested)`,
              status: g.graded > 0 && g.yes / g.graded <= 0.25 ? 'ok' : 'soft-miss'
          })
      })
  })
293}
294 
295describe('cross-lane', () => {
  it('chronicle pairwise + cost + snapshot', async () => {
      if (!RUN) {
          skip('XL', 'pairwise / cost / snapshot')
          return
      }
      setAiCallObserver(null)
302 
      // Blind pairwise: pair lane outputs by index, both kinds. Votes are
      // position-debiased and dual-graded inside prefer().
      async function pairwise(kind: 'mid' | 'epilogue'): Promise<{ anthropic: number; openai: number }> {
          const a = chronicles.anthropic[kind]
          const o = chronicles.openai[kind]
          const pairs = Math.min(a.length, o.length)
          let aVotes = 0
          let oVotes = 0
          for (let i = 0; i < pairs; i++) {
              const v = await prefer(CHRONICLE_CRITERIA, a[i], o[i])
              aVotes += v.a
              oVotes += v.b
          }
          return { anthropic: aVotes, openai: oVotes }
      }
318 
      const midVotes = await pairwise('mid')
      const epiVotes = await pairwise('epilogue')
      results.pairwise = { mid: midVotes, epilogue: epiVotes }
      record({
          layer: 'XL',
          invariant: 'chronicle pairwise (mid-run)',
          result: `anthropic ${midVotes.anthropic} · openai ${midVotes.openai}`,
          status: 'ok'
      })
      record({
          layer: 'XL',
          invariant: 'epilogue pairwise',
          result: `anthropic ${epiVotes.anthropic} · openai ${epiVotes.openai}`,
          status: 'ok'
      })
334 
      // Cost from real usage. Anthropic priced from the verified list; the
      // OpenAI lane is reported in raw tokens (its prices live outside the repo).
      for (const lane of LANES) {
          const cells = usageByLane[lane]
          let dollars = 0
          let input = 0
          let output = 0
          let calls = 0
          for (const [key, cell] of Object.entries(cells)) {
              input += cell.input
              output += cell.output
              calls += cell.calls
              const model = key.split(':')[1]
              const price = ANTHROPIC_PRICES[model]
              if (price) dollars += (cell.input * price.input + cell.output * price.output) / 1_000_000
          }
          laneResults(lane).usage = { calls, input, output, dollars: lane === 'anthropic' ? Math.round(dollars * 10000) / 10000 : null, byTask: cells }
          record({
              layer: 'COST',
              invariant: `${lane} battery usage`,
              result: `${calls} calls · ${input} in · ${output} out${lane === 'anthropic' ? ` · $${dollars.toFixed(4)}` : ''}`,
              status: 'ok'
          })
      }
359 
      results.rows = recordedRows()
      results.meta = {
          date: new Date().toISOString(),
          samples: { N_TIMELINE, N_ANACHRONISM, N_JUDGE, N_CHARACTER, K_CHRONICLE },
          graders: 'dual (gpt-5.4 + claude-sonnet-4-6), agreement-gated, position-debiased pairwise'
      }
      const dir = resolve(process.cwd(), 'evals/results')
      mkdirSync(dir, { recursive: true })
      const file = resolve(dir, `bakeoff-${new Date().toISOString().slice(0, 10)}.json`)
      writeFileSync(file, JSON.stringify(results, null, 2))
      process.stdout.write(`\nbake-off snapshot → ${file}\n`)
  })
372})

What the note spawns

A design exploration earns its keep by ending in concrete, ordered work. The note closes with four implementation issues in dependency order — the RunSettings foundation first, then presets + eval coverage, the mission-select dials, and settings-travel-with-a-run.

Implementation issues, in dependency order · 353 lines

Implementation issues, in dependency order353 lines · Markdown

⋯ 317 lines hidden (lines 1–317)1# Game Settings Layer — difficulty, run shape, constraints
2 
3> **Design exploration for [#90](https://github.com/mseeks/revisionist/issues/90).** This is a
4> recommendation, not an implementation. No `RunSettings` schema, no settings UI, no
5> retuning of the live curve — just the design space, a recommended v1, and the
6> implementation issues this note should spawn. For what is true in the code today,
7> read [`../../CLAUDE.md`](../../CLAUDE.md); for forward intent, [`../ROADMAP.md`](../ROADMAP.md).
8 
9## TL;DR — the recommendation
10 
11Ship a **lean v1**: three difficulty **presets** as the primary surface, **two run-shape
12dials** exposed directly, and a **deterministic seed** plumbed in (no UI yet). Defer
13everything else.
14 
15| v1 (ship) | v2 (next) | Deferred / never |
16|---|---|---|
17| **Difficulty presets:** Story · Standard · Iron | Per-dial **Custom** overrides | Daily challenge, score normalization |
18| **Messages per run** (run length) | Timeline-window constraints (era clamp, chronological-only) | Message length (it's core identity — leave fixed) |
19| **Distinct-figures cap** (incl. single-figure) | Sandbox / "anywhen" stance (its own slice) | Paid-gating (note the question; don't decide) |
20| **Seed** (plumbing only — basis for sharing/replay) | Repeat-contact + grounded-only policies | — |
21 
22Four load-bearing decisions, each argued below:
23 
241. **Presets bundle the dials; they are not independent sliders.** The run economy is a
25   tuned system. A preset must move the band economy *with* message count and win
26   threshold, or the win rate breaks.
272. **`RunSettings` is a small serializable bundle, chosen at mission-select**, stored in
28   the run, validated server-side. Design it serializable from day one so a shared run
29   (`#88`/`#89`) can carry its rules + seed.
303. **Safety never moves.** Difficulty can make the *game* harder or easier; it can never
31   relax the server-authoritative safety floor (`#72` deceased-only, `#71` objective
32   bounds, the swing clamp, moderation). Those stay closed-enum and server-enforced.
334. **Every preset needs eval coverage** so a retune can't silently regress the EV
34   corridor the economy rests on.
35 
36## Today: one fixed configuration
37 
38The game ships as a single, well-tuned configuration. Every rule is a named constant —
39already centralized, just not player-facing. The cross-module ones live in
40[`utils/game-config.ts`](../../utils/game-config.ts); the rest sit per-module by design.
41 
42| Constant | Value | File | Controls |
43|---|---|---|---|
44| `TOTAL_MESSAGES` | `5` | `utils/game-config.ts` | dispatches allotted per run |
45| `MAX_PROGRESS` | `100` | `utils/game-config.ts` | win threshold (progress is clamped 0..100) |
46| `MAX_PROGRESS_SWING` | `50` | `utils/game-config.ts` | the per-turn fuse (hard clamp on a resolved swing) |
47| `MAX_MESSAGE_CHARS` | `160` | `utils/game-config.ts` | chars per dispatch |
48| `SWING_BANDS` | CF −35..−15 · F −15..−5 · N 0..+12 · S +15..+30 · CS +30..+45 | `utils/swing-bands.ts` | the D20 band → progress table (the run economy) |
49| dice faces | CF 1–2 · F 3–8 · N 9–12 · S 13–18 · CS 19–20 (2/6/4/6/2) | `utils/dice.ts` | the natural-roll distribution |
50| `STAKE_MULTIPLIER` / `STAKED_SWING_CAP` | `2` / `100` | `utils/swing-bands.ts` | the last-stand wager on a final dispatch |
51| `CRAFT_MODIFIER` / `CRAFT_GAIN_FACTOR` | ±2 roll / ×0.15–1.45 gain | `utils/craft.ts` | the Message Judge's two channels |
52| `MOMENTUM_MAX` / `MOMENTUM_STEP` | `4` / `0.1` (cap ×1.4) | `utils/momentum.ts` | the run-level gains amplifier |
53| `BRIDGE_FREE` / `SCALE` / `CHAIN_FLOOR` | `75` / `550` / `0.12` | `utils/causal-chain.ts` | causal-chain decay |
54| `GAIN_FACTOR` / `LOSS_FACTOR` / `KNEE` | ×1–1.6 / ×1–2 / `40` | `server/utils/anachronism.ts` | the future-knowledge wager |
55| `SAFELY_HISTORICAL_BEFORE_YEAR` | (the floor) | `server/utils/historical-floor.ts` | the safely-dead / safely-historical line (`#71`/`#72`) |
56 
57`utils/game-config.ts` is the natural seam for a settings layer — but its own header says
58only *cross-module* rules belong there; many dials are intentionally local. Part of the
59work is deciding **which constants get promoted into a player-facing `RunSettings`** and
60which stay internal.
61 
62## The core risk: the economy is a tuned system, not free dials
63 
64This is the whole reason these aren't already settings, and the reason a difficulty
65"level" must be a **bundle** rather than a row of independent sliders.
66 
67**The EV corridor.** With the documented face distribution (2/6/4/6/2 over 20) and the
68band midpoints, the expected swing for *sound, unaided* play (craft modifier 0, no wager,
69no chain, no momentum) is:
70 
71```
72P(CF)=0.10  P(F)=0.30  P(N)=0.20  P(S)=0.30  P(CS)=0.10
73mid:  −25       −10       +6        +22.5       +37.5
74EV = .10(−25) + .30(−10) + .20(6) + .30(22.5) + .10(37.5) ≈ +6.2 / turn
75```
76 
77That matches the tuning intent stated in `utils/swing-bands.ts` ("roughly +6/turn" for
78sound play). Over `TOTAL_MESSAGES = 5` turns that is ≈ **+31 of 100** — an *honorable
79loss*. The gap to 100 is what craft, a calibrated anachronism wager, and momentum are
80meant to close, so victory is earned rather than drawn from a lottery.
81 
82**The pipeline that produces a turn's swing** (`callTimelineAI`,
83`server/utils/openai.ts`), in order:
84 
851. Roll a D20; **craft modifier (±2)** shifts the roll (clamped 1–20) → this picks the band.
862. Model proposes a swing; it is **clamped into the rolled band** (`SWING_BANDS`).
873. **Anachronism amplifier** (`amplifyForAnachronism`) widens both signs, asymmetric
88   (gains ×1.15/1.35/1.6, losses ×1.25/1.6/2), soft knee above ±40, re-clamped to ±50.
894. **Causal-chain decay** (`decayForChain`) diffuses both signs toward zero by distance
90   from the nearest foothold (floor 0.12).
915. **Gains-only** multipliers: positive swing × `CRAFT_GAIN_FACTOR` × `momentumFactor`.
92   Losses are never scaled — skill buys reach, never immunity.
936. **Clamp to ±`MAX_PROGRESS_SWING`** (the per-turn fuse).
947. On a final *staked* dispatch only: `applyStake` doubles, clamp ±100.
95 
96**Why the coupling bites.** The corridor is calibrated against `TOTAL_MESSAGES` *and*
97`MAX_PROGRESS` together:
98 
99- Cut messages 5 → 3 and unaided play yields ≈ +18, while the per-turn band ceiling is
100  +45 (`BAND_CEILING`). The win now demands ≈ +33/turn average — near-impossible inside
101  the bands. The run is "harder" by accident, not design.
102- Raise the win threshold 100 → 150 and the same thing happens from the other side.
103- Widen the per-turn fuse and the stake's drama collapses (every turn can already swing
104  the meter).
105 
106So a difficulty preset cannot change message count or win threshold *and leave the bands
107alone*. The bands, the message count, and the threshold move **together**, as one tuned
108bundle, validated by eval. This single fact drives the entire design: **presets, not
109sliders.**
110 
111The honest framing for a preset: it sets a *target* unaided-finish ratio (today ≈ 0.31 of
112the win bar) and a target aided EV, then derives the dials to hit them. There is one
113genuinely clean exception, and it points at the simplest KISS move: **message count
114re-prices the run while leaving every per-turn artifact byte-identical** (bands, dice,
115legend, prompt calibration all unchanged). The pragmatic call is to let message count *be*
116a difficulty axis — Story = more messages, Iron = fewer — and accept that the corridor
117ratio moves with it, rather than re-scaling the bands to hold the ratio constant. Document
118the shift as the intended knob.
119 
120### Gotchas the implementation must handle
121 
122Making these constants settings exposes seams that are invisible today because the values
123happen to line up:
124 
125- **Coincidentally-equal literals must become derived.** `STAKED_SWING_CAP` is a hardcoded
126  `100` (`utils/swing-bands.ts`), *not* a reference to `MAX_PROGRESS`. They are equal by
127  intent (a staked throw sweeps the whole meter) but would silently diverge the moment the
128  win threshold becomes a setting. Same risk anywhere a tuning value re-derives a
129  game-config number by hand.
130- **Re-typed eval constants would desync.** The ±3 valence window and the 160-char cap are
131  re-typed inside the eval fixtures, not imported. A preset touching them desyncs the evals
132  from the game silently. Promote them to imports first.
133- **`BAND_CEILING ≤ MAX_PROGRESS_SWING` is a pinned invariant** (`swing-bands.spec.ts`). Any
134  preset that reshapes the bands has to re-check it, or the amplifier loses its headroom.
135 
136## What gets promoted vs stays internal
137 
138A clean split keeps the settings surface small and the safety/tuning invariants intact.
139 
140**Promote into `RunSettings` (player-facing, per run):**
141 
142- `messagesPerRun` (← `TOTAL_MESSAGES`) — the cleanest standalone run-shape knob.
143- `winThreshold` (← `MAX_PROGRESS`) — only via presets (it re-tunes the corridor).
144- `distinctFiguresCap` — a *new* constraint (none today); 1 = single-thread challenge.
145- `difficulty` — a preset id that *bundles* the tuning dials below.
146- `seed` — deterministic dice; plumbing now, surfaced later for sharing/replay.
147 
148**Keep internal, scaled only *through* a preset (never a raw slider):** the band table,
149the dice reshaping, `CRAFT_*`, `MOMENTUM_*`, the anachronism factors, the chain decay,
150the stake. These are the tuning dials; exposing them raw is how a player breaks the
151curve. A v2 "Custom" mode can open a curated subset behind an advanced panel.
152 
153**Keep internal and immovable (safety):** `isDeceased` / `SAFELY_HISTORICAL_BEFORE_YEAR`
154(`#72`), the objective bounds (`#71`), the in-code band clamp, and moderation
155(`REVISIONIST_MODERATION`). Difficulty does not get a vote here.
156 
157**Leave fixed:** `MAX_MESSAGE_CHARS = 160`. The 160-char discipline is core identity and
158an eval'd Character-layer invariant; making it a dial dilutes the game's signature
159constraint for little variety.
160 
161## The candidate catalog, triaged
162 
163The issue's brainstorm (groups A–G), cut to a v1 verdict. The full rationale for the
164"economy" rows is the section above.
165 
166| Candidate | Maps to | Verdict | Why |
167|---|---|---|---|
168| Messages per run | `TOTAL_MESSAGES` | **v1 dial** | cleanest run-shape lever; couples to the corridor, so its retune rides the preset |
169| Distinct-figures cap | new constraint | **v1 dial** | adds real variety (single-figure run), no economy coupling, server-checkable |
170| Difficulty preset | bundles the tuning dials | **v1 (primary)** | the only safe way to move the coupled economy |
171| Win threshold | `MAX_PROGRESS` | **v1, preset-only** | moves the corridor — must ride a preset, never a free slider |
172| Per-turn fuse | `MAX_PROGRESS_SWING` | **internal** | a safety clamp + the stake's basis; not a player knob |
173| Roll variance / band reshape | dice + bands | **internal (preset-scaled)** | the corridor itself |
174| Craft weight / anachronism / decay / momentum / stake | the tuning dials | **internal (preset-scaled)** | exposing raw breaks tuning |
175| Timeline-window constraints (era clamp, chronological-only) | new, atop the when-slider | **v2** | strong variety, but needs its own UX + eval; lifetime bound already exists |
176| Sandbox / "anywhen" | drop lifetime + safely-dead bounds | **deferred (own slice)** | collides with the safety floor; a deliberate separate stance, not a difficulty knob |
177| Repeat-contact / grounded-only | figure policy | **v2** | grounded-only is already the floor (`#73`); repeat-contact is a light add |
178| Safely-dead cutoff relax | `#72` floor | **never (as difficulty)** | safety, server-authoritative — cannot be a difficulty lever |
179| Objective source / steering / anchor visibility / reroll cap | `#71`, objective compose | **v2** | ties to objective work, not the core economy |
180| Assist (tutorial, scaffolding, archive access) | `#60`, UI | **folds into presets** | Story shows scaffolding; Iron hides it + caps research |
181| Seed | new | **v1 (plumbing)** | the basis for fair sharing/replay; cheap to land early |
182| Daily challenge / speedrun / score normalization | meta modes | **deferred** | depend on seed + sharing; design after the bundle exists |
183 
184## The v1 proposal: three presets
185 
186Three is the right number: an on-ramp, the tuned default, and a brutal mode — from one
187engine. The dial values below are **illustrative targets to be validated by eval**, not
188final tuning (the issue forbids re-tuning the live curve here; this just shows *where*
189each preset would re-tune it).
190 
191| Dimension | **Story** (on-ramp) | **Standard** (today) | **Iron** (veteran) |
192|---|---|---|---|
193| Target unaided EV/turn | higher (~+9) | ~+6 (today) | lower (~+4) |
194| Messages per run | 6–7 | **5** | 4 |
195| Win threshold | 100 | **100** | 100 (decisive feel via tighter economy, not a higher bar) |
196| Band economy | gentler losses, fatter Success | **today** | harsher losses, leaner gains |
197| Anachronism penalty | softened | **today** | harsher losses |
198| Causal-chain decay | gentler | **today** | steeper (chaining matters more) |
199| Last stand (stake) | on | **on** | **off** (no safety net) |
200| Scaffolding (band table, pace hint, ⚡/⏳ chips) | all shown | **shown** | hidden |
201| Archive (research) | unlimited | **unlimited** | capped or disabled |
202| Guided first-run (`#60`) | on | default | off |
203 
204Standard *is* the current configuration — shipping presets must not change today's game.
205Story and Iron are symmetric moves outward from it, each a coherent bundle rather than a
206pile of toggles. Note that "harder" on Iron comes mostly from a leaner economy and a
207removed safety net, **not** from raising the win bar — keeping the meter legible.
208 
209## Surface, persistence, and travel
210 
211**Presets over a wall of sliders.** The mission-select briefing
212([`components/MissionSelect.vue`](../../components/MissionSelect.vue)) gains one row: a
213three-way difficulty chip plus the two run-shape dials (messages, figure cap). That is
214the entire v1 surface. A "Custom" disclosure (per-dial overrides) is explicitly v2.
215 
216**Where settings live.** A run starts when the player commits an objective
217(`chooseObjective` in `stores/game.ts`; a null `currentObjective` is what surfaces the
218briefing). `RunSettings` is authored in the same briefing — a sibling fieldset to the
219existing era/theme steer dials, closed enums, committed only on Begin — threaded through
220`chooseObjective` into **one new `runSettings` state field cleared by `resetGame`**, and
221read by `sendMessage` and the pure dials. Because it carries only pre-run choices (no
222dates, no server `runId`, none of the staleness/account plumbing), it round-trips through
223JSON or a URL param cleanly — which is exactly what makes it the right unit to travel with
224a run. It must work for **anonymous** players (the default path today). A saved profile
225default is a later tie to accounts (`#83`), layered on top — the per-run choice is the
226primitive.
227 
228**Settings travel with a run.** There is **no run snapshot, share, or seed concept in the
229code today** — a run is entirely live and ephemeral. That makes this greenfield, and it
230argues for designing `RunSettings` as a **small serializable bundle from the start**, next
231to a `seed`. For shared-run "beat this" (`#88`) and replay (`#89`) to be *fair*, the
232snapshot has to carry both the rules and the seed; otherwise two players aren't playing
233the same game. The seed is the one piece worth plumbing in v1 even before daily/seeded
234modes ship, because retrofitting determinism later is far more invasive than reserving the
235field now (the dice live behind `rollD20` in `utils/dice.ts` — a single, swappable source).
236 
237## Safety stays server-authoritative
238 
239Several knobs are server-enforced and closed-enum on purpose: the deceased-only contact
240floor (`isDeceased`, `server/utils/figure-grounding.ts`, fail-closed — a figure with no
241confirmed death is never contactable), the objective bounds (`#71`), the in-code clamp of
242the engine's swing into the rolled band, and moderation. A settings layer **must not
243become a client bypass.** Concretely:
244 
245- `RunSettings` is **validated and clamped server-side**, to an allowed range per field —
246  the client's chosen values are untrusted input, like every other field. This is the
247  pattern already in place: `send-message.post.ts` and `research.post.ts` **re-ground the
248  figure name** against the untrusted payload rather than trusting a client claim of "this
249  person is contactable."
250- Difficulty scales the *game* (harder/easier), never the *safety floor*. There is no
251  difficulty that lets you message a living person or dodge moderation. A Sandbox / "anywhen"
252  stance that *did* relax the lifetime + deceased-only bounds (its own deferred slice, not a
253  difficulty knob) would flip a **server-read** flag, never a client toggle the POST handler
254  honors — and moderation (`REVISIONIST_MODERATION`) is never surfaced to players at all;
255  `off` is an operator/calibration lever only.
256- The closed enums stay closed. A preset id is one of a fixed set; an out-of-range message
257  count or figure cap is rejected, not honored.
258 
259## Evals: a preset can't silently break the curve
260 
261The tuning expectations already live as evals, and a new difficulty knob has to extend
262them or it can regress the curve invisibly:
263 
264- [`evals/bakeoff.eval.ts`](../../evals/bakeoff.eval.ts) scores **the NEUTRAL-band EV
265  corridor the run economy is tuned around** — the exact invariant a preset's retune
266  threatens.
267- [`evals/behavior.eval.ts`](../../evals/behavior.eval.ts) checks the model-behavior
268  invariants the mechanics rest on (band steering, `sharp ≥ vague` craft ordering,
269  anachronism accuracy).
270- [`evals/causal-chain.eval.ts`](../../evals/causal-chain.eval.ts) confirms stepping
271  stones beat blasts end-to-end; [`evals/judge-tune.eval.ts`](../../evals/judge-tune.eval.ts)
272  pins craft-grade anchoring (which feeds the economy).
273 
274But the existing coverage has two gaps a preset would fall straight through, and naming
275them is half the value of this exploration:
276 
2771. **The corridor eval guards the wrong number.** It scores `baseProgressChange` — the swing
278   *before* the anachronism / causal-chain / craft-gain / momentum multipliers. So the four
279   downstream multipliers are an **unguarded realized-EV surface**: a "hard" preset that
280   halved `CRAFT_GAIN_FACTOR` would change the EV the player actually experiences while the
281   corridor eval stayed green. The `[4,9]` corridor is a real invariant, but it is *not* the
282   EV the run is won or lost on.
2832. **The corridor bounds are hardcoded literals, not a function of the preset.** If Story
284   legitimately targets a higher neutral EV and Iron a lower one, today's absolute `[4,9]`
285   assertion would flag the *intended* presets as misses. The corridor eval has to become
286   **preset-parameterized** — fed each preset's target band.
287 
288**Requirement for the implementation:** each shipped preset needs (a) a parameterized
289pre-multiplier corridor assertion fed its own target, and (b) a **realized-EV** assertion
290that composes the full pipeline (so a multiplier change can't move the curve unseen) and a
291plausible win rate at sound + calibrated play. The pure dials (bands, decay, momentum,
292craft) are already unit-tested in isolation; the new surface to cover is *the composition
293under each preset*.
294 
295## Scope & monetization
296 
297v1 is deliberately small: presets + two dials + seed plumbing. The open question worth
298**noting, not deciding here**: whether any setting (e.g. seeded/daily competitive modes,
299or an Iron leaderboard) is paid-gated. The accounts/paywall seam already exists (`#83`,
300the runs economy); this note flags the question and leaves the call to the monetization
301track.
302 
303## Recommended v1, restated
304 
305- **Surface:** three difficulty presets (Story · Standard · Iron) + two run-shape dials
306  (messages per run, distinct-figures cap), chosen at mission-select. Custom per-dial
307  overrides deferred to v2.
308- **Model:** a small serializable `RunSettings` bundle (`difficulty`, `messagesPerRun`,
309  `distinctFiguresCap`, `seed`), validated + clamped server-side, stored in the run,
310  anonymous-friendly, profile-default later (`#83`).
311- **Economy:** each preset re-tunes the bundle (message count + band economy + the wager /
312  decay / momentum / stake) **together**, with Standard == today's game unchanged.
313- **Travel:** plumb a deterministic `seed` now; carry `RunSettings` + `seed` in the run
314  snapshot when sharing/replay (`#88`/`#89`) lands.
315- **Guardrails:** safety floor untouched and server-authoritative; an EV-corridor eval per
316  preset.
317 
318## Implementation issues this note spawns
319 
320Ready-to-file, in dependency order:
321 
3221. **`RunSettings` bundle + server validation + seed plumbing.** Define the serializable
323   type (`difficulty`, `messagesPerRun`, `distinctFiguresCap`, `seed`), thread it through
324   the store run-state and `sendMessage`, validate + clamp server-side, and route the dice
325   through a seeded source behind `rollD20`. No UI beyond a default. *Foundation for the
326   rest.*
3272. **Difficulty presets + economy retune + eval coverage.** Implement Story/Standard/Iron
328   as preset bundles that scale the internal tuning dials together; Standard reproduces
329   today's curve exactly. Make the corridor eval **preset-parameterized** and add a
330   **realized-EV** assertion (full pipeline, not just `baseProgressChange`) per preset.
331   First promote the re-typed eval constants (±3 valence, 160-char) to imports and derive
332   `STAKED_SWING_CAP` from the win threshold so nothing diverges silently. *Depends on 1.*
3333. **Run-shape dials at mission-select.** Surface `messagesPerRun` and
334   `distinctFiguresCap` (incl. the single-figure challenge) in `MissionSelect.vue`, with
335   the figure cap enforced server-side. *Depends on 1; pairs with 2 for the message-count
336   retune.*
3374. **Settings + seed travel with a shared run.** Carry `RunSettings` + `seed` in the run
338   snapshot so a shared/replayed run is the same game. *Depends on 1 and on `#88`/`#89`.*
⋯ 15 lines hidden (lines 339–353)339 
340## Explicitly out of scope (per #90)
341 
342No implementation, no final `RunSettings` schema, no settings UI here. No commitment to the
343final set — this is divergent brainstorming plus a recommendation. Not a re-tuning of the
344existing curve; this only identifies *where* each difficulty would re-tune it.
345 
346---
347 
348*Related:* [#83](https://github.com/mseeks/revisionist/issues/83) (accounts — saved
349defaults) · [#88](https://github.com/mseeks/revisionist/issues/88) /
350[#89](https://github.com/mseeks/revisionist/issues/89) (sharing & replay — why a run
351should carry its settings + seed) · [#71](https://github.com/mseeks/revisionist/issues/71)
352(objective steering) · [#72](https://github.com/mseeks/revisionist/issues/72) (safely-dead
353floor) · [#60](https://github.com/mseeks/revisionist/issues/60) (guided first-run).