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. None of it has been driven in a browser.

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

530 backend tests pass and the frontend builds. The whole of the UI work is unverified — 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 (21 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.
• 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.