interactive-story/plan/16-world-state-refusals.md

World-state refusals: what the engine throws away, and who gets told

Read this before you play the Pokémon demo again. It records why two bugs in plan/15-pokemon-demo-handover.md were diagnosed wrongly, what the engine was actually doing, and what changed. Everything here is merged and green. It has now been driven in a browser; read "Driven in a browser" at the end first, because three of the five changes did not work and one bug explains all three.

Last updated: 2026-08-28.

---

The one sentence version

apply_delta records three outcomes for every change the model sends — applied, clamped, rejected — and everything downstream read only applied. A refused change therefore reached the player as an ordinary chip and reached the model, on the next turn, as a change that had succeeded.

What was actually wrong

plan/15 recorded two bugs and named a cause for each. Both causes were wrong, and the investigation is worth keeping because the same reasoning trap is easy to repeat: the visible evidence was "the number did not move", and the natural reading of that is that the model never tried.

pokemon_left was emitted every time

Adventure 43's action rows carry milo pokemon_left in world_changes at both faints, each with "delta": 0, "value": 3. The model saw the faint and wrote the path. It was not forgetting anything.

old == new == 3 is reachable only from a positive value. pokemon_left was min 0, max 3, initial 3, max_delta_per_turn 1, so +2 capped to +1, reached 4, and clamped back to the ceiling of 3. Net zero.

So the model sent the remaining count as an absolute — "two left" — instead of a delta of -1. Milo's four stats alternate between the two conventions:

stat	convention
active_pokemon	text, absolute
active_hp	number, delta
active_status	text, absolute
pokemon_left	number, delta

HP survives because damage is naturally phrased as a change. A count is naturally phrased as a state, so it got text semantics.

The general rule this produces: a numeric stat whose initial equals the boundary it moves away from turns every wrong-signed change into a silent no-op. Every hp in the scenario has that shape (initial == max). It has never fired only because damage is phrased as a decrease by luck of language.

Milestones were never emitted at all

Zero milestone changes across nine AI turns. EMIT_RULE asks for "milestones.<id>": true and apply_delta matches <id> against the schema key, but render_state_section printed only the description, and render_reference skipped the milestones section entirely (STAT_SECTIONS = ("world", "player")). The string graveler_defeated was nowhere in the prompt.

The same playtest is its own control: sandstorm_active is a flag, flags are printed by name, and it worked.

The replay was teaching the model to repeat itself

Found while deciding whether to feed refusals forward, and the most damaging of the three. _history_text re-attached each past turn's state block from world_delta["delta"] — what the model sent, not what was applied. So the turn after the faint contained the model's own block claiming "npc.milo.pokemon_left": 2, directly above a live values line reading pokemon_left 3/3, with nothing to say which was true.

That is a per-turn lesson that sending 2 is correct. The identical mistake at the second faint is what that lesson predicts.

What changed

Five changes, on fix-silent-clamps-and-milestone-ids.

1. Action.world_changes reports refusals (models.py). Reads clamped and rejected beside applied. Accepted stats carry clamped; refusals become kind: "rejected" entries. The fix key is present only when the engine wrote one — it is empty for every accepted change, and this property runs for every action of every list response.
2. The UI distinguishes three outcomes (Play.jsx, index.css). Clamped to a standstill reads no change — at its limit on a dashed chip; a partial clamp is marked (limited); a rejection carries its reason. Dashed and dimmed rather than red: the rules refusing a change is them working.
3. Milestones are named to the model (engine.py). The goals line is now Goals (mark with milestones.<id>): graveler_defeated — Knock out Milo's lead Graveler; …, the same treatment NPCs get with (npc.milo).
4. Refusals carry a generated correction (engine.py). Each rejection, and each clamp that moved nothing, builds a fix string from the stat definition at the point of refusal, so it quotes the real limits and lists the real names. render_refusals() renders them into the prompt directly above EMIT_REMINDER, for the previous AI turn only.
5. History replays what was accepted (builder.py). applied_delta() rebuilds the block from report["applied"], dropping any numeric entry where new == old so a change that moved nothing cannot be copied as a zero.

Plus the demo scenario: pokemon_left became pokemon_fainted (type: counter, initial: 0), which puts a wrong sign on the counter rule where it is rejected out loud instead of absorbed. The faint instruction moved into its own paragraph, and a world.turn line was added — it sat at 0 for the whole playtest because nothing ever told the model to move it.

The design call worth not re-litigating

A clamp that reduced a change but still moved the value says nothing. Only total losses are reported. If you tell a model its 80 damage became 30, it can treat the shortfall as a debt and send the remaining 50 next turn — which is the swing max_delta_per_turn exists to prevent. A rejection has no partial credit to chase. test_a_clamp_that_still_moved_the_value_says_nothing pins this.

How to test it

532 backend tests pass and the frontend builds. The UI work has no automated cover — this project has no frontend test runner, which is the standing reason its UI bugs are found by hand.

Run the backend from backend/ with .venv/Scripts/python.exe -m pytest tests/. The new file is tests/test_change_visibility.py (23 tests). Each of the three mechanisms fails its own test when disabled; that was checked by sabotage, not assumed.

To drive it, re-seed the scenario and play the demo:

1. A refusal chip. Open the World State drawer, use its ✎ edit mode to put Milo's active_hp at full, then play a turn where he takes no damage but the model tries to heal him. Easier and more reliable: send a deliberately wrong block by editing an AI turn. What you are looking for is a dashed chip reading no change — at its limit, not a +0.
2. The milestone. Knock out Graveler. graveler_defeated should tick, and a ✓ graveler defeated chip should appear. This is the single clearest pass/fail in the whole change — it never once happened before.
3. The faint counter. At the same faint, pokemon_fainted should go 0 → 1. If the model sends an absolute again, it is now refused rather than absorbed, and the refusal note should appear in the next turn's prompt. Read it under Insights → the turn's context snapshot, section world_state_refusals.
4. The replay. In the same snapshot, check the replayed history: a past turn's state block should carry only the changes that were accepted.
5. world.turn should now advance by 1 per reply.

Check the narrow layout too. The chips grew longer text, and .chg is inside the story column with nothing to scroll sideways — overflow-wrap: anywhere is doing the work, and it was not re-checked at 390 px. Chrome clamps its minimum window width to ~500 px, so relaunch with --window-size= rather than trying to resize a maximized window.

Still open

• The missing state block from plan/15 bug 1 is unexplained. Truncation at max_output_tokens removes the block, which LENGTH_HEADROOM exists to prevent, and it was never ruled out. The distinguishing evidence is whether the narration ends mid-sentence with finish_reason: length.
• Every hp stat still has the initial == max shape. Now visible when it bites, rather than silent, but not designed out.
• The stale "Road to the Champion" scenario and adventure 42 are still on production. Deleting them is hand-work and was deliberately not automated. Automated on 2026-08-28: seed.py now deletes seeded scenarios no seed file claims. Adventure 42 survives with a NULL scenario_id, and losing the cover art is the whole cost.
• The Bandit Camp demo (04-rpg-world-state.json) was not checked for the same milestone problem. Its milestones were equally unnamed to the model before this change, so it is worth asking whether one has ever fired there.

---

Driven in a browser, 2026-08-28

Adventure 45, four turns, on production against the demo model. Two of the five changes worked. Three did not reach anyone, for one reason.

The bug: the stored column dropped two of the three lists

world_delta_of in routers/adventures.py wrote delta and applied only. Every consumer that distinguishes outcomes reads the other two:

• Action.world_changes builds clamped_paths from world_delta["clamped"], so every chip carried clamped: false. Play.jsx's blocked = c.clamped && d === 0 could never be true, and (limited) could never render.
• With no rejected list, a kind: "rejected" chip was unreachable.
• worldstate.refusals reads both lists, so render_refusals always returned an empty string and no correction ever reached the next prompt.

The fix string survived only because the engine stores it inside the applied entry. Turn 3 is the record: the snapshot's report.clamped held npc.ivysaur.hp and npc.milo.active_hp with correct fix text, both chips came back clamped: false, turn 4's prompt contained no correction, and the model repeated the same mistake.

world_delta_of now carries all three lists.

Why the 21 tests passed. The action() helper in test_change_visibility.py built the column by hand as {"delta": delta, **report}, with every list present. The write path was never exercised. The helper now fills the column through world_delta_of. Removing the two lines again fails 9 of the 23 tests; that was checked, not assumed.

The two that were not code faults

graveler_defeated never fired and world.turn never moved. Both instructions are present and correct in the assembled prompt: the goals line reads Goals (mark with milestones.<id>): graveler_defeated — …, and the scenario says to add 1 to world.turn every reply. The demo model ignores both. Change 3 landed; the model is the limit.

The absolutes were coming from the scenario's own wording

The model sent a total, not a change, for almost every number: npc.ivysaur.hp: 96, npc.milo.active_hp: 65 then 88, player.potions: 2. Because every hp has initial == max, each one clamped back to where it started. potions went up when the player spent one.

EMIT_RULE does say "CHANGES ONLY, as deltas (not new totals)", and EMIT_REMINDER repeats "deltas only". The scenario contradicted both at closer range. milo.active_hp.desc said "Reset this to the newcomer's full HP", which is an instruction to send an absolute, and that desc is injected every turn. The bullets said "Drop the HP … and raise it", naming a direction but never a sign. The only line that said "(not a delta)" was player.active_pokemon, so naming the exception made the rule look optional.

The one stat whose desc used delta wording, pokemon_fainted ("Add 1 each time"), is the one that worked.

Fixed in 05-league-championship.json: every hp desc and the potion desc now state the sign, the bullets do too, and the lead-in says plainly that every number is a change with a worked example. milo.active_hp.max_delta_per_turn went 65 → 98, because a switch legitimately moves that stat a full bar and the old cap made the reset unreachable in one turn.

Not fixed: the initial == max shape itself. It is now loud rather than silent, and the wording removes the usual cause, but the shape is still there.

---

Driven against Claude, 2026-08-28

The four turns above ran on the free demo model, which ignored two instructions that were present and correct in the prompt. To separate model behavior from code, the same demo was played again through backend/tools/claude_shim.py, an OpenAI-compatible endpoint backed by the local claude command line tool. The model was sonnet. See the README for how to run it.

Every one of the five changes worked:

Turn	Chips
1	turn +1, active pokemon → Wartortle, wartortle hp -8, milo active hp -46, dashed type advantage used refused — no such flag
2	turn +1, milo active hp -52, milo pokemon fainted +1, milo active pokemon → Onix, ✓ graveler defeated
3	turn +1 (limited), dashed milo active hp no change — at its limit
4	turn +1, milo active hp +32, ✓ type advantage used

graveler_defeated fired for the first time in five playtests, world.turn moved every turn, pokemon_fainted went 0 to 1 at the faint, and every HP number was a signed change rather than a total. The two failures left open above were the demo model, not the instructions.

The refusal loop is verified end to end. Turn 3 clamped to nothing. Turn 4's assembled prompt, read from GET /api/adventures/1/actions/9/context, carried the correction verbatim:

[Part of your last state block was not applied. Correct it in this turn's block:
- `npc.milo.active_hp` did not move. It is already at its minimum of 0 (it runs
  from 0 to 98; it moves at most 98 per turn).]

The model's next delta was {"world.turn": 1, "npc.milo.active_hp": 32, "milestones.type_advantage_used": true}. That is the loop the whole change exists for, and it had never been observed running.

The one bug that is still a schema fault

At the faint the model set npc.milo.active_pokemon to Onix and sent no positive active_hp change, so Onix arrived on the field at 0 of 98 and every later hit was refused. Sonnet followed the rest of the scenario closely, so this is the schema rather than the model: active_hp is one stat with one max of 98, shared by Graveler at 98, Onix at 90, and Kabutops at 88. A switch has to raise it, and nothing in the schema can raise it on the referee's side.

The fix is to give Milo's three Pokemon their own NPC entries, which also removes the initial == max shape from this demo. Not done: the session's remaining time went to the guest starter instead.

Cost

About $0.04 a turn, billed against the Claude subscription rather than a card. Roughly 13k of each request's 20k prompt tokens is the command line tool's own overhead; the app's prompt is about 7k.

---

What shipped alongside it, 2026-08-28

A permanent local test rig. backend/tools/claude_shim.py is now in the repo. It finds the claude binary through AIDND_CLAUDE_BIN, then PATH, then the per-user install, and takes --port and --claude.

The demo says Pokemon in its title, and has a Pokeball for cover art. 05-league-championship.json is now [Demo] Pokemon League Championship: Round One. Renaming a seed exposed a fault: seed.py matches a seed to its row by title, so a rename inserted a second public scenario and stranded the first, which is the same failure this file records for "Road to the Champion". Seeds now carry previous_titles, and _find_renamed lands the rename on the existing row. The scenario kept its id, and no orphan appeared.

The cover art is a 3.2 kB PNG data URI. An SVG one was tried first and stored as an empty image_url: app/images.py accepts raster formats only, on purpose, because SVG can carry script and these bytes are served from the app's own origin. backend/tools/make_pokeball.py draws the ball with zlib alone, so regenerating it needs no image library.

Seeded scenarios no seed file claims are deleted. previous_titles stops a rename stranding a row, but the rows already stranded still needed deleting by hand on every deployment. _sweep_unclaimed removes them on the next boot. Only a NULL owner with is_public is reachable, so nothing a player made can be touched, and adventures.scenario_id is ON DELETE SET NULL, so an adventure started from a deleted demo keeps its story and loses only the artwork. The sweep is skipped when a seed file fails to parse, and an empty seed directory never reaches it: neither reads as an instruction to delete live content.

Every new guest gets the played adventure. app/starter.py copies a shipped export bundle into each new guest account, from the guest mint in routers/auth.py. The bundle is this session's adventure trimmed to its first two exchanges, which ends on the knockout and shows an applied change, a refused one, and a milestone. It stops before the Onix bug above, and the state it leaves has Onix at its own 90 HP so a guest can play on from it.

An adventure has no cover art of its own and inherits its scenario's, and a bundle carries no scenario id, because an id is local to one database. The starter file names its source under scenarioTitle instead, and starter._link_scenario looks it up, so the copy shows the Pokeball rather than a monogram tile.

The row building that POST /adventures/import did inline moved into bundle.materialize, which both callers now use. The limit and rate checks stayed in the endpoint: the starter writes a file the server ships, so it has no untrusted list to cap. tests/test_starter_adventure.py covers the file, the copy, the chips, the playable end state, and the two failure paths.