hayao 0.4.1 → 0.4.2

package/design/30-systems/procgen-design.md

@@ -0,0 +1,118 @@
+---
+id: system-procgen-design
+title: Procedural Generation Design
+kind: system
+tags: [procgen, seeds, runs, variance, connectivity, controlled-randomness, generation, replayability]
+summary: Runs, seeds, and variance as content — controlled randomness that always connects, proven before you tune a single number.
+use-when: A design needs replayable, generated content (levels, dungeons, decks) instead of hand-authored maps.
+composes-with: [system-session-structure, system-encounter-design, system-save-and-checkpoint, genre-roguelike]
+anchors: [anchor-dead-cells, anchor-slay-the-spire]
+verify-with: docs/FUN.md#10-traditional-roguelike
+---
+
+# Procedural Generation Design
+
+**What it is.** Generating content from a **seed** instead of authoring it by
+hand — so a run is a *fresh, reproducible* configuration of known parts. Procgen
+turns "an agent hand-authors forty balanced rooms" (unreliable) into "an agent
+calls a generator and gets forty *proven* rooms" (reliable). The design work is
+choosing the **parts, the constraints, and the acceptance test** — not rolling
+dice and hoping.
+
+**Player fantasy / why it's fun.** *This run is mine.* Variance means the next run
+surprises you; a seed means it's fair, not arbitrary. The pull is **discovery
+under fairness** — every layout is new, but every layout is winnable (FUN.md §10).
+
+## When to use / when NOT
+
+| Use it when | Author by hand when |
+|---|---|
+| Replayability is the point (roguelike, survivors) | A crafted narrative sequence — procgen dilutes intent |
+| Content *volume* exceeds what you can hand-build | A handful of set-piece bosses ([[system-boss-design]]) |
+| You want a difficulty *band*, not fixed levels | Tutorial rooms — those teach a *specific* verb ([[system-onboarding]]) |
+
+> **Connectivity first, numbers later.** The single most common procgen failure is
+> an unreachable stair, item, or exit. Prove reachability across ~50 seeds *before*
+> you tune a single difficulty value (FUN.md §10). A generator that can produce an
+> unwinnable layout is a generator that *will*.
+
+## Variants
+
+| Variant | Generates | Grounded in Hayao |
+|---|---|---|
+| **Cellular cave** | organic open spaces | `generateCave(rng, opts)` (grep `docs/API.md`) |
+| **Room-and-corridor dungeon** | connected rooms | `generateDungeon(rng, opts)` |
+| **Solver-verified puzzle set** | in-band winnable levels | `generateLevels(factory, opts)` |
+| **Grammar / template assembly** | rooms from hand-made chunks | your factory over `world.rng` |
+| **Deck / drop draft** | reward pools | `pickEntry` / `weightedPick(rng, …)` |
+| **Noise / distribution** | terrain, placement fields | `valueNoise` / `hashNoise` (stateless) |
+
+## Tuning levers
+
+| Lever | Turns up… | Watch for |
+|---|---|---|
+| **Fill % / smoothing** (caves) | openness vs. maze-ness | over-smoothing erases variety ([`sandboxes/procgen-lab`](../../sandboxes/procgen-lab/)) |
+| **Difficulty band** | which candidates are kept | a band too narrow starves the generator (accept-rate) |
+| **Variance budget** | how different runs are | too much = incoherent; too little = same run twice |
+| **Reject hook** | genre rules a candidate must pass | the place to enforce "no start-adjacent goal" |
+| **Dedupe key** | how near-identical layouts collapse | without it, two seeds ship the same map |
+
+## How it wires to Hayao
+
+- **The generator is solver-backed.** `generateLevels(factory, {count, minDepth,
+  maxDepth, minNodes, maxNodes, reject, dedupeKey})` builds a candidate from a
+  seeded `factory(rng) → Puzzle`, *solves* it, and keeps only the winnable ones
+  in-band. Every kept level carries the sub-seed that reproduces it exactly — so
+  the campaign that ships is **data (a list of seeds), not forty hand-written
+  maps** ([`src/content/generate.ts`](../../src/content/generate.ts)).
+  `generateLevelsReport` surfaces the accept-rate and difficulty spread.
+  `levelFromSeed(factory, seed)` rebuilds any one level from its seed.
+- **Determinism is structural.** All randomness flows through `world.rng`;
+  sub-seeds derive from `hashString`, never wall-clock or `Math.random` — the same
+  `(seed, count, band, factory)` yields the same set on every machine (CLAUDE.md
+  invariant 2; FUN.md law 7).
+- **Connectivity is a lint.** `connectedComponents` / `reachableRegions` /
+  `astarGrid` (grep `docs/API.md`) prove stairs + all loot + exits reachable across
+  a seed sweep before any tuning.
+- **Learn the primitive alone:** [`sandboxes/procgen-lab`](../../sandboxes/procgen-lab/)
+  — `generateCave`, `valueNoise`, `autotileToCommands` with re-rollable seed, fill
+  %, smoothing passes. One mechanic, no genre.
+
+## Fails when…
+
+- **Unreachable content.** A stair, key, or exit behind an unbroken wall = an
+  unwinnable seed. The connectivity sweep catches it; skip the sweep and players
+  find it for you (FUN.md §10).
+- **Tuning before connectivity.** Balancing numbers on a generator that still
+  produces dead layouts wastes both passes.
+- **Wall-clock / Math.random inside generation.** Breaks reproducibility — a seed
+  no longer names a run, and goldens rot.
+- **Variance for its own sake.** Randomness with no floor of *quality* produces
+  slop; the acceptance test is what makes variance content.
+- **Same-map collapse.** No dedupe key and distinct seeds ship identical layouts.
+
+## Verify
+
+- **Connectivity sweep first:** stairs + all loot reachable across ~50 seeds
+  ([FUN.md §10](../../docs/FUN.md#10-traditional-roguelike)).
+- **Winnability, not experience:** a full-knowledge bot wins 10/10 random seeds —
+  that proves *a line exists*, the right claim for procgen (FUN.md §10).
+- **Seeded reproducibility:** the same seed yields the same layout + a hash-identical
+  turn-log replay (FUN.md law 7).
+- **In-band difficulty:** `generateLevelsReport` shows kept levels land inside the
+  target band; assert the ramp with `rampIssues`.
+
+## Composes with
+
+- [[system-session-structure]] — a seed defines one run; the run is the session container.
+- [[system-encounter-design]] — generated rooms still need pockets and clear exits.
+- [[system-save-and-checkpoint]] — a run resumes from `(seed, tuning, snapshot)`.
+- [[genre-roguelike]] — the genre whose fairness *is* procgen connectivity.
+- [[pattern-emergence]] — variance across systems is where generated stories come from.
+
+## See also
+
+- [`src/content/generate.ts`](../../src/content/generate.ts) — solver-backed level generation.
+- [`sandboxes/procgen-lab`](../../sandboxes/procgen-lab/) — the generation primitives alone.
+- [`docs/FUN.md` §10](../../docs/FUN.md#10-traditional-roguelike) — connectivity-first fairness.
+- [[anchor-dead-cells]] · [[anchor-slay-the-spire]] — procgen as the shape of a run.

package/design/30-systems/progression.md

@@ -0,0 +1,120 @@
+---
+id: system-progression
+title: Progression — XP, Levels, the Power Curve
+kind: system
+tags: [progression, xp, levels, power-curve, pacing, growth, vertical, horizontal]
+summary: Turning play into steadily-earned power; pacing the curve so growth never stalls and never trivialises the challenge it feeds.
+use-when: The design promises the player gets stronger over time and you need to shape how fast, along which axes, and how it stays fun.
+composes-with: [system-skill-trees, system-economy, system-reward-schedules, system-mastery-curve, system-difficulty-and-dda]
+anchors: [anchor-hades, anchor-vampire-survivors, anchor-dead-cells]
+verify-with: docs/FUN.md#14-incrementalidle
+---
+
+# Progression — XP, Levels, the Power Curve
+
+**What it is.** The **curve** that converts time-and-skill spent into durable
+power. XP fills a bar, the bar pops a level, the level buys a gain. The design
+work is not the bar — it is the *shape* of the curve and *what each level is
+worth*.
+
+**Player fantasy / why it's fun.** "I am becoming stronger, and I can feel it."
+Every session ends with the character measurably ahead of where it started. The
+pull is the **next** gain always sitting just inside reach.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| The fun is a rising arc — you *build* toward power | Mastery is the whole point; power is flat (Tetris, chess) |
+| Sessions need a between-run ledger of "I earned something" | A run should reset clean every time with no carryover |
+| You want a difficulty dial that the *player* turns by playing | Handing power out would erase the challenge that IS the game |
+
+If the game is pure execution (**[[genre-precision-platformer]]**,
+**[[genre-bullet-hell]]**), don't bolt on XP — the level *is* the reward. A
+platformer's "progression" is new *verbs* (**[[genre-metroidvania]]**), not
+bigger numbers.
+
+## Variants
+
+| Variant | Power comes from | Feels like | Example |
+|---|---|---|---|
+| **Vertical** | Bigger numbers on the same actions | Overwhelming what used to threaten you | Diablo levels; Vampire Survivors' in-run levels |
+| **Horizontal** | New *options*, not more damage | A wider toolbox, same lethality | Zelda items; Hades' boon variety |
+| **In-run (soft)** | Growth reset each run | A build arc per session | VS level-ups; roguelite per-run picks |
+| **Meta (hard)** | Growth persists between runs | A campaign under the runs | See [[system-meta-progression]] |
+| **Milestone** | Discrete unlocks at thresholds | Earned checkpoints, not a smooth ramp | "Beat act 2 → new class" |
+
+Most games layer two: an **in-run** vertical ramp under a **meta** horizontal
+one (Hades, Dead Cells). Name which axis carries the fantasy before you tune.
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **XP-to-next curve** | How fast levels come | Gentle geometric (×1.1–1.4/level). Flat = trivial; steep = a wall |
+| **Power-per-level** | The size of a gain | Each level must be *felt* — no "+0.3% crit" filler levels |
+| **Time-to-first-level** | The onboarding hook | Fast (< 60–90s of play). The first pop teaches the loop |
+| **Power-vs-challenge gap** | Whether growth trivialises | Enemies/costs must ramp *with* the player (law 3 inequality) |
+| **Level cap / soft cap** | Where the curve flattens | Cap before gains stop being felt, or switch axes (vertical→horizontal) |
+| **Catch-up** | Whether a behind player recovers | Optional; XP scaling on lower levels. Pairs with [[system-difficulty-and-dda]] |
+
+The one number that breaks games: **power outrunning challenge.** State it as a
+law-3 inequality — *enemy HP(t) grows ≥ player DPS(t)* — and assert it, exactly
+as horde-survival asserts superlinear spawn pressure against multiplicative
+build growth (**[[FUN.md §6]]**).
+
+## How it wires to Hayao
+
+- **Power is state.** XP, level, and stat totals live in `world.state`; the
+  level-up is a **sim step**, and the pick that spends it is an **input action**
+  (never a direct mutation) so replays and goldens stay honest — the same rule
+  incremental/idle lives by (**[[FUN.md §14]]**).
+- **The pop is choreography.** The sim resolves the level instantly and *returns*
+  a "leveled-up" beat; the view (flash, chime, particles on `LAYER_HUD`) replays
+  it and is `cosmetic = true`, deletable without changing `world.hash()`
+  (**[[FUN.md §6]]**).
+- **The curve is content, not code.** Pace levels the way `src/content/`
+  generates and ramps levels: express the difficulty series and feed it to
+  `assertRamp`/`rampIssues` (grep `docs/API.md`) so "the curve has no deserts and
+  no walls" is a test, not a vibe. See the generated-campaign flagship
+  `examples/lanternfold/`.
+- **Meta power persists** through `SaveManager` — see [[system-meta-progression]].
+
+## Fails when…
+
+- **Filler levels.** A gain you can't feel is a chore bar. Fewer, bigger levels
+  beat many tiny ones.
+- **The curve deserts.** A long stretch with no reachable next gain — the
+  incremental sin (**[[FUN.md §14]]**). Assert first-gain times per tier.
+- **Power laps challenge.** The build trivialises the content and the game turns
+  to autopilot; or challenge laps power and it's a wall. Both break the CI
+  *window* (**[[FUN.md §6]]**).
+- **Vertical-only forever.** Numbers with no new decisions get boring; introduce
+  a horizontal axis (options, [[system-skill-trees]]) once damage stops thrilling.
+- **Grind to progress.** If the only path to the next level is repeating a solved
+  encounter, you've built a timer, not a game.
+
+## Verify
+
+- Pacing/no-deserts and the payback discipline: **[[FUN.md §14]]** (incremental).
+- Power-vs-challenge as an asserted inequality: **[[FUN.md §6]]** (horde) and law
+  3 (derive constraints).
+- Ramp shape as a test: `assertRamp`/`rampIssues` over the level/curve series —
+  the same instrument `examples/lanternfold/` uses.
+- Skill-delta: intended play out-earns null play by a margin (universal law 2).
+
+## Composes with
+
+- [[system-skill-trees]] — where horizontal power *branches* into builds.
+- [[system-economy]] — XP is one faucet; levels are one sink among many.
+- [[system-meta-progression]] — the persistent layer under run-scoped growth.
+- [[system-mastery-curve]] — power should *raise the ceiling*, not replace skill.
+- [[system-reward-schedules]] — the drip that fills the XP bar between levels.
+- [[pattern-pacing-and-tension]] — the level curve IS a pacing curve.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §6, §14 — the pacing and challenge-gap proofs.
+- `src/content/generate.ts` · `campaign.ts` — generate-and-ramp content, don't
+  hand-author the curve.
+- `examples/lanternfold/` — a 42-level generated, ramp-asserted campaign.

package/design/30-systems/resource-loops.md

@@ -0,0 +1,112 @@
+---
+id: system-resource-loops
+title: Resource Loops — Gather → Convert → Spend
+kind: system
+tags: [resource-loops, gather, convert, spend, bottleneck, production, pacing, chains]
+summary: The gather→convert→spend cycle that structures effort; bottlenecks placed on purpose are the pacing, not a bug.
+use-when: The game asks the player to turn raw inputs into refined outputs into results, and you need the chain to breathe rather than stall or trivialize.
+composes-with: [system-economy, system-crafting, system-tech-tree, system-progression]
+anchors: [anchor-factorio, anchor-stardew-valley]
+verify-with: docs/FUN.md#14-incrementalidle
+---
+
+# Resource Loops — Gather → Convert → Spend
+
+**What it is.** The **cycle** at the heart of production games: *gather* a raw
+resource, *convert* it into something more useful, *spend* the result on progress —
+which unlocks better gathering, and the loop turns again, wider. The design work
+is deciding where the loop **narrows** — the bottleneck the player must solve.
+
+**Player fantasy / why it's fun.** "I built the pipeline that makes the thing that
+makes me stronger." Each loop closed is a small system mastered. The pull is the
+*next* bottleneck — the one resource you don't have enough of yet.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Progress runs through *making*, not just buying | The game has no crafting/production layer |
+| You want pacing to emerge from bottlenecks, not timers | A flat currency ([[system-economy]]) already carries it |
+| Chains of resources create planning/optimization depth | Extra steps would be busywork with no decision |
+
+A resource loop is **[[system-economy]]** with *structure*: instead of one bucket,
+a directed chain where each node's output feeds the next. Use it when the *shape*
+of the chain — what feeds what — is itself a puzzle.
+
+## Variants
+
+| Variant | Shape | Depth from | Example |
+|---|---|---|---|
+| **Linear chain** | A → B → C → goal | Clear ramp; one bottleneck at a time | Stardew crops → artisan goods → cash |
+| **Branching tree** | One input, many outputs | Prioritisation | Factorio iron → plates/gears/etc |
+| **Converging web** | Many inputs, one output | Logistics puzzle | Factorio science packs |
+| **Cyclic (renewable)** | Output feeds back to input | Sustainable scaling | Seeds from crops; power → mining → power |
+| **Sink loop** | Convert → spend → gone | Pacing pressure | Fuel: gather → burn → gather (survival) |
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Bottleneck placement** | *Where* the player feels scarcity | One clear binding constraint at a time — that's the current puzzle |
+| **Conversion ratio** | Inputs per output | Legible (2:1, 5:1), not 7.3:1 mystery math |
+| **Chain length** | Steps from raw to result | Long enough to plan, short enough to hold in head; add steps as content, not on day one |
+| **Throughput vs storage** | Flow rate vs stockpile | Flow-limited = active play; storage-limited = idle waiting |
+| **Renewability** | Whether a resource runs out | Renewable = sustainable; finite = a clock ([[system-economy]] inflation) |
+| **Parallel loops** | How many run at once | More loops = more to juggle; ramp the count |
+
+The bottleneck **is** the pacing. A loop with no binding constraint is a firehose —
+nothing to optimise. A loop with a *permanent* bottleneck is a wall. Good design
+*moves* the bottleneck: solve iron, now you're copper-limited, now power-limited.
+Each move is a fresh puzzle — the same "no deserts, no walls" discipline as an
+economy's pacing window (**[[FUN.md §14]]**).
+
+## How it wires to Hayao
+
+- **The chain is data.** Resource counts and converter states live in
+  `world.state`; each gather/convert/spend is an **input action**, so the whole
+  production run replays and hashes (**[[FUN.md §14]]**, law 7).
+- **Pacing is provable.** Balance-sim the loop with a bot that plays it out, then
+  assert *monotone production* and *no bottleneck desert* — the exact incremental
+  verify. The farming truth applies too: surface the player-critical number ("N
+  iron short") the way farming surfaces "nights left" (**[[FUN.md §15]]**).
+- **Ratios are law-3 inequalities.** "Converter throughput ≥ demand at tier T" is a
+  constraint you state in a comment and assert against the actual config, not a
+  vibe (**[[FUN.md law 3]]**).
+- **The reinvest-vs-hoard delta** is your skill proof: a bot that reinvests output
+  into more capacity beats one that hoards — farming measured 740 vs 236
+  (**[[FUN.md §15]]**, law 2).
+
+## Fails when…
+
+- **No bottleneck.** Everything abundant → no decisions → the loop is a chore of
+  clicking through steps. Always bind *one* constraint.
+- **A permanent wall.** A bottleneck that never resolves halts progress. Move it.
+- **Mystery ratios.** Illegible conversion math the player can't plan around.
+- **Idle throughput.** If output accrues while away with no active choice, it's a
+  timer, not a loop.
+- **Chain too long day one.** Ten steps before the first payoff buries the fun.
+  Introduce depth as the player scales, the way `src/content/` gates mechanics per
+  act.
+
+## Verify
+
+- Monotone production, no desert, pacing windows — the balance-sim:
+  **[[FUN.md §14]]**.
+- Reinvest-vs-hoard skill delta: **[[FUN.md §15]]**, law 2.
+- Conversion/throughput ratios as asserted inequalities: **[[FUN.md law 3]]**.
+- Surface the binding number to the player (the farming truth): **[[FUN.md §15]]**.
+
+## Composes with
+
+- [[system-economy]] — a resource loop is an economy with an explicit chain.
+- [[system-crafting]] — recipes are the *convert* step made combinatorial.
+- [[system-tech-tree]] — research gates unlock new links in the chain.
+- [[system-progression]] — spending the loop's output is how you grow.
+- [[pattern-emergence]] — interacting loops (power↔mining) generate depth.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §14 (pacing) · §15 (farming solvency + reinvest
+  delta) — the loop proofs.
+- **[[anchor-factorio]]** (the loop as the toy) · **[[anchor-stardew-valley]]**
+  (gentle linear chains).

package/design/30-systems/reward-schedules.md

@@ -0,0 +1,124 @@
+---
+id: system-reward-schedules
+title: Reward Schedules — Drops, Chests & Ethical Compulsion
+kind: system
+tags: [rewards, variable-ratio, loot, drops, chests, compulsion, dark-patterns, ethics]
+summary: How often and how surprisingly the game pays out; variable-ratio's grip, and the honest line between compelling and exploitative.
+use-when: The design hands out loot, drops, or chests and you need the payout rhythm to feel exciting without tipping into manipulation.
+composes-with: [system-economy, system-collectibles, system-meta-progression, system-progression, system-procgen-design]
+anchors: [anchor-vampire-survivors, anchor-hades, anchor-peggle]
+verify-with: docs/FUN.md#19-physics-arcade-breakoutpeggle
+---
+
+# Reward Schedules — Drops, Chests & Ethical Compulsion
+
+**What it is.** The **schedule** on which the game pays out — fixed (every N), or
+**variable-ratio** (random, averaging N). Variable-ratio is the most powerful
+reinforcement pattern known, which is exactly why it demands an ethical hand. This
+module is about wielding its *grip* to make earning thrilling — and refusing its
+use to *extract*.
+
+**Player fantasy / why it's fun.** "Maybe *this* one." Anticipation is the reward;
+the drop is the payoff. Uncertainty makes a trivial input (Peggle's last peg,
+opening a chest) feel enormous (**[[anchor-peggle]]**, maximal juice on trivial
+input).
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Loot/drops are a core reward channel | Rewards are deterministic and that's the point (puzzle clears) |
+| Anticipation itself is fun (chests, gacha-of-cosmetics) | The randomness would gate *required* progress unfairly |
+| You want surprise to punctuate a grind | It'd become a slot machine dressed as a game |
+
+**The honesty line.** Variable-ratio is fine for *cosmetics, flavor, and bonus*
+rewards where the base game is complete without them. It becomes a **dark pattern**
+when it gates required power behind paid randomness, hides odds, or engineers
+loss-aversion (streaks you'll "lose"). Design compulsion you'd be proud to explain.
+
+## Variants
+
+| Variant | Schedule | Feels like | Watch for |
+|---|---|---|---|
+| **Fixed-ratio** | Reward every N | Reliable, plannable | Predictable → less exciting |
+| **Variable-ratio** | Random, averages N | The slot-machine pull | Ethics; the honest use is *cosmetic/bonus* |
+| **Fixed-interval** | Reward every T time | Daily-login cadence | Retention manipulation if punitive |
+| **Pity / bad-luck protection** | Guaranteed by attempt N | Fairness floor on RNG | *Always* add this to variable-ratio |
+| **Tiered / weighted** | Common→rare distribution | Chase the rare | Odds must be *shown* |
+| **Deterministic reveal** | RNG resolved, shown honestly | Trust | This is the ethical default |
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Base rate** | How often you pay out | Frequent small + rare large — a steady drip with peaks |
+| **Variance** | How swingy | Enough surprise to thrill; not so much it feels arbitrary |
+| **Pity timer** | The fairness floor | *Mandatory* on any variable-ratio — guarantee by attempt N |
+| **Odds transparency** | Whether players know the chances | Show them. Hidden odds are a dark pattern, full stop |
+| **What's behind RNG** | Cosmetic vs required power | Keep *required* progress off the random schedule |
+| **Anticipation window** | The pause before reveal | Long enough to build tension, short enough not to annoy ([[pattern-juice-choreography]]) |
+
+### Dark patterns to refuse
+
+- **Hidden odds** — never. Publish them.
+- **Pay-to-random for power** — required strength behind a paywalled RNG box.
+- **Loss-aversion engineering** — "your streak resets in 2h" pressure.
+- **Near-miss manufacturing** — faking "so close!" reveals to bait retries.
+- **FOMO scarcity** — artificial time-limited rarity to force impulse.
+
+Compulsion is a tool; extraction is a choice. The Codex's stance: use anticipation
+to *reward* engagement, never to *punish* disengagement.
+
+## How it wires to Hayao
+
+- **RNG is sim, through `world.rng`.** Every drop rolls on `world.rng` — never
+  `Math.random` (CLAUDE.md invariant 2). This makes the whole schedule
+  *deterministic per seed*: a golden run hashes identically, and you can *audit*
+  the payout distribution in a test.
+- **Resolve, then choreograph.** The sim resolves the drop instantly and *returns*
+  the reveal as choreography; the view plays the chest-open, the flash, the rarity
+  color (`LAYER_HUD`, `cosmetic = true`) — deletable without changing the outcome
+  (**[[FUN.md law 6]]**). The anticipation is *view time over sim truth*, like
+  match-3's cascade script (**[[FUN.md §13]]**).
+- **Audit odds and pity in CI.** Roll N drops over seeds; assert the empirical
+  distribution matches the *stated* odds and that pity fires by attempt N — the
+  same "intent honesty" audit deckbuilders run on telegraphs (**[[FUN.md §11]]**).
+- **Prove the base game is complete without the RNG** — a bot that never opens a
+  random reward still clears the game. That's the ethical proof.
+
+## Fails when…
+
+- **No pity floor.** Pure RNG can strand a player for hundreds of attempts — cruel.
+  Always cap it.
+- **Hidden or lying odds.** The distribution doesn't match the shown numbers — an
+  auditable, shippable-blocking bug *and* an ethics failure.
+- **Required power behind RNG.** Progress gated on luck (or a wallet) — the game is
+  now a slot machine.
+- **Reveal fatigue.** Anticipation windows so long or frequent they annoy — tune
+  the pause.
+- **Reward inflation.** Everything's legendary → nothing is. Rarity needs scarcity
+  ([[system-economy]] inflation).
+
+## Verify
+
+- Odds/pity distribution audit over seeds (intent honesty): **[[FUN.md §11]]**.
+- Determinism per seed (golden hash of a drop run): **[[FUN.md law 7]]**.
+- Reveal is cosmetic — sim resolves, view replays, hashes equal: **[[FUN.md law 6]]**.
+- Base game clears without opening any random reward (a null-reward baseline):
+  **[[FUN.md law 4]]**.
+
+## Composes with
+
+- [[system-economy]] — drops are a faucet; rarity is inflation control.
+- [[system-collectibles]] — variable-ratio drives set completion.
+- [[system-meta-progression]] — the meta ledger fed by run rewards.
+- [[system-procgen-design]] — seeded randomness shares the same rng discipline.
+- [[pattern-juice-choreography]] — the anticipation→reveal is pure choreography.
+- [[pattern-risk-reward]] — push-your-luck chests turn the schedule into a decision.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §11 (intent-honesty audit) · law 6 (resolve-
+  then-choreograph) · law 4 (null baseline).
+- [`docs/JUICE.md`](../../docs/JUICE.md) — the anticipation→reveal feel gates.
+- **[[anchor-peggle]]** — maximal juice on a trivial, uncertain input.

package/design/30-systems/save-and-checkpoint.md

@@ -0,0 +1,113 @@
+---
+id: system-save-and-checkpoint
+title: Save & Checkpoint
+kind: system
+tags: [save, checkpoint, retry, respect-time, snapshot, hash, round-trip, resume]
+summary: Save, checkpoint, and retry that respect the player's time — built free on Hayao's pure-state snapshot/hash round-trip.
+use-when: The player can lose progress, needs to stop and resume, or should retry a failure without ceremony.
+composes-with: [system-session-structure, system-meta-progression, system-grace, pattern-anti-frustration]
+anchors: [anchor-celeste, anchor-hades]
+verify-with: docs/CONVENTIONS.md
+---
+
+# Save & Checkpoint
+
+**What it is.** The machinery that **preserves progress** — full saves, mid-level
+checkpoints, and instant retry after failure. Its real subject is **respect for the
+player's time**: never make someone redo what they've mastered, and never make a
+failure cost more than the mistake did.
+
+**Player fantasy / why it's fun.** Trust and momentum. Instant retry keeps a
+platformer in flow (Celeste: "each retry is instant, keeping the momentum alive").
+A checkpoint before a boss means the *fight* is the challenge, not the walk to it.
+The pull is that the game values your hours as much as you do.
+
+## When to use / when NOT
+
+| Design it carefully when | It's simpler when |
+|---|---|
+| Runs/levels are long enough to lose real progress | A 90-second arcade loop — restart is the save |
+| Failure is frequent (platformer, roguelite) | A turn-based game you can quit anytime (state is always saveable) |
+| The player stops and resumes across sittings | A pure toy with no progress to keep |
+
+> **The cost of failure should equal the mistake, not the walk back to it.**
+> Re-treading solved content to reach the hard part is a tax on time, not a test of
+> skill. Checkpoint *at* the challenge; retry *into* it.
+
+## Variants
+
+| Variant | Granularity | Feels like | Best for |
+|---|---|---|---|
+| **Instant retry** | the moment | "again, now" | precision platformer ([[anchor-celeste]]) |
+| **Checkpoint** | before a hard beat | "the fight, not the trek" | action, boss runs |
+| **Autosave** | on meaningful change | "I can quit safely" | sims, adventures |
+| **Manual save** | player-chosen | "I own my progress" | long-form, strategy |
+| **Roguelite persistence** | between runs | "death advanced *something*" | roguelites ([[anchor-hades]]) |
+| **Run suspend** | mid-run, resume later | "stop without losing the run" | long sessions |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Checkpoint density** | how much a death costs | too sparse = punishing; too dense = no stakes |
+| **Retry latency** | flow vs. weight | any load screen breaks a platformer's momentum |
+| **What persists** | run-reset vs. carry-over | defines how heavy death feels ([[system-meta-progression]]) |
+| **Save scope** | full world vs. milestone flags | full snapshot is exact; flags are compact but lossy |
+
+## How it wires to Hayao
+
+- **Save is nearly free here.** `world.state` is plain JSON + `world.rng`; RNG and
+  clock state are part of `world.hash()`, `world.snapshot()`, and saves, so a
+  restored world **resumes identically** — the property that makes replay and save
+  the same mechanism (CONVENTIONS: "a restored world resumes identically";
+  FUN.md law 7).
+- **Serialize / restore:** `serializeSnapshot(snap)` and `parseSnapshot(text)`
+  (grep `docs/API.md`) turn a `WorldSnapshot` into storable text and back —
+  round-trip a snapshot and hash both sides for a save-integrity test.
+- **Checkpoints are cheap snapshots.** The engine already keeps a periodic
+  `SnapshotRing` (every N frames) for Studio scrubbing/tape
+  ([`docs/STUDIO.md`](../../docs/STUDIO.md)) — the same primitive that powers
+  time-travel powers your checkpoints.
+- **Instant retry is `restart`.** A clean rebuild of world state (no leaked nodes,
+  no stale RNG) is a verified checklist item (CONVENTIONS §6). Buffer the retry
+  input across the death pause ([[system-grace]], FUN.md law 5).
+- **Meta persistence** is the between-run save ([[system-meta-progression]]).
+
+## Fails when…
+
+- **Re-treading solved content.** A death that sends you back through mastered
+  rooms taxes time, not skill — the anti-fun that grace exists to kill
+  ([[pattern-anti-frustration]]).
+- **Retry latency.** Any load/animation between death and retry drains a
+  platformer's momentum (contrast Celeste's instant retry).
+- **Save corrupts on resume.** If snapshot→restore doesn't round-trip to an equal
+  hash, saves silently diverge — test it (CONVENTIONS §5).
+- **Restart leaks.** Stale nodes or un-reset RNG after `restart` mean run N+1
+  inherits run N's ghosts (CONVENTIONS §6).
+- **Non-determinism sneaks in.** Any wall-clock or `Math.random` outside `world.rng`
+  makes a restored world *not* resume identically.
+
+## Verify
+
+- **Snapshot round-trip:** `snapshot → serializeSnapshot → parseSnapshot → restore`,
+  assert equal `world.hash()` at every checkpoint (CONVENTIONS §5, FUN.md law 7).
+- **Restart is clean:** `restart` fully rebuilds state — no leaked nodes, no stale
+  RNG (CONVENTIONS §6).
+- **Retry buffers intent:** frame-pump the death→retry window and assert the
+  buffered input is accepted ([`src/verify/gates.ts`](../../src/verify/gates.ts)
+  forgiveness gate; FUN.md law 5).
+- **Full run pinned:** `t.golden('full run', world.hash())` proves the whole
+  session replays bit-exactly (CONVENTIONS §7).
+
+## Composes with
+
+- [[system-session-structure]] — session length dictates checkpoint granularity.
+- [[system-meta-progression]] — the persistent save between runs.
+- [[system-grace]] — instant retry and input-buffering-through-a-pause are grace.
+- [[pattern-anti-frustration]] — respecting time is the mindset this system enforces.
+
+## See also
+
+- [`docs/CONVENTIONS.md`](../../docs/CONVENTIONS.md) — pure state, snapshot/hash, restart cleanliness.
+- [`docs/STUDIO.md`](../../docs/STUDIO.md) — the `SnapshotRing` and replay round-trip.
+- [[anchor-celeste]] · [[anchor-hades]] — instant retry and death-as-progress.