undercooked/docs/SIMULATION.md

# SIMULATION.md — the tick contract

**Status:** current as of phase 04 task 05 (the kernel of task 01, real movement,
collision, facing and stun, the action button: reach-zone targeting, the verb ladder,
named denials and contested arbitration, the hands: one-item-per-hand carry, the
marked set-down with the counter hand-off, and the long-press trash, the station
pipelines: the acceptance matrix, the transition timers, the worker hold and release,
dirty props and the plate/pot stock, the ticket rail: seeded order spawning with
the concurrency cap and the full-rail retry, tick-precise deadlines and the miss
bookkeeping, serve scoring: the named serve rejections, FIFO order matching,
the quality/streak/time-bonus math and the miss penalty, freshness: the burn
countdown, the quality decay, the push-out and the dirty loop — and the round's
end conditions: the early win, the buzzer verdict, the post-verdict settle,
the stars and the plain-JSON result payload, plus the replay harness: the
input-script format, the committed golden hashes, the `record`/`check` CLI, and
the headless perf smoke). **Filled in by phase 10** for the hazards —
that replaces the identity hook named in the order table below.

## Purpose

This document is the contract between the deterministic game rules and everyone who
calls them: how a tick is born, how much simulation one call may buy, the order subsystems
run in and why that order is gameplay, how player input is turned into authoritative
change, what purity and determinism cost in code, and what a golden hash is allowed to
mean. It exists because the simulation is the single source of truth (A4) — a rule that
reads differently in two places is a bug in the rules, not in the client.

The rules of the kitchen live in `src/undercooked/sim/` and nowhere else. This document
is the contract those modules owe every caller — the room supervisor (phase 05), the
protocol layer (phase 06) and the client (phase 07) included. `.agents/PLAN.md` decides
*what* the simulation is (A4: server-authoritative fixed tick; A5: purity; A21: replay);
this file says how that reads in code.

Write here, not in a docstring, whenever a later phase changes: the tick contract,
movement and collision, the pipeline rules, contested arbitration, or hazard rules.

## The tick

```text
one call  ->  step(state, dt, inputs)  ->  (state', events)
                            │
             dt clamped to [0, MAX_DT], added to state.accumulator
                            │
        while accumulator >= STEP_DT: exactly one substep, accumulator -= STEP_DT
```

The simulation is driven in **whole substeps of `STEP_DT` = 0.05 s**, i.e. 20 Hz, the rate
A4 locks. `UNDERCOOKED_TICK_HZ` (`config.py`) decides how many substeps the room asks for
per wall second; it never changes what one substep contains. A caller may hand `step()`
any `dt` it likes — the client's frame time, a batched timer, a test harness — and the
simulation still advances in the same 0.05 s increments, so physics never depends on how
noisy the host's clock is.

Leftover time is not lost: `KitchenState.accumulator` carries the fraction that did not
add up to a whole substep into the next call. 17 calls of 0.05 s are exactly 17 ticks;
two calls of 0.03 s are one tick plus 0.01 s of credit.

### Constants

| Constant | Value | Lives in | Means |
| --- | --- | --- | --- |
| `STEP_DT` | `0.05` s | `sim/step.py` | One substep — one tick. The only dt a subsystem ever sees. |
| `MAX_DT` | `0.1` s | `sim/step.py` | Ceiling on one `step()` call: at most 2 substeps, so a stall cannot spiral. |
| `TICK_EPS` | `1e-9` s | `sim/step.py` | Tolerance on the substep bound; `0.85 − 17 × 0.05` is `2.2e-16`, not `0`. |
| `TIME_EPS` | `1e-9` s | `sim/round_state.py` | Same idea for the round clock: below this the round is over, not "0.0 s left". |
| `SETTLE_S` | `1.0` s | `sim/round_state.py` | The settle window: how long the room (phase 05) keeps a decided round ticking, so the verdict substep's events land. The sim is a frozen stage-7-and-tick machine for the whole window. |
| `SEAT_COLORS` | 4 hex colours | `sim/state_build.py` | The fixed cook palette, indexed by `seat % 4`. |

### Movement constants

The numbers PLAN §5 fixes for a cook, now that stage 3 is real. They live in
`sim/movement.py` (`RADIUS` and `CONTACT_EPS` are the collision geometry, and live in
`sim/collision.py` for the second one because both modules need them):

| Constant | Value | Means |
| --- | --- | --- |
| `MAX_SPEED` | `3.5` tiles/s | Speed ceiling. No diagonal bonus: `DIAGONAL_NORM` makes a diagonal a direction, not extra throttle. |
| `ACCEL` | `30` tiles/s² | How fast intent becomes velocity. |
| `DECEL` | `40` tiles/s² | How fast it goes away when the stick centres — deliberately harder than `ACCEL`: overshooting a station is the mistake players make most. |
| `RADIUS` | `0.35` tile | Half-width of the cook's body **square** (an AABB, not a circle) in tile units. This is PLAN §5's `PLAYER_RADIUS`, named for what the collision module reads it as. |
| `CONTACT_EPS` | `1e-4` tile | The gap a swept body stops short of a blocked cell, and the inset a footprint is measured with. See "One geometry, two questions". |
| `DIAGONAL_NORM` | `True` | Set to `False` and a diagonal is √2 faster. Read at call time so the test can prove which rule is in force. |
| `STUN_S` | `0.6` s | How long a hit keeps a cook still. Whoever stuns writes it to `Player.stun`; `apply_stun()` ticks it down. |
| `STUN_EPS` | `1e-9` s | A stun is over at this remainder: `0.6 − 12 × 0.05` is `1.4e-17`, not `0`. |
| `MOVE_EPS` | `1e-6` tiles/s | Below this the cook is `IDLE`, not `MOVING`. |
| `PUSH_ITERATIONS` | `2` | Soft-push passes. Two propagates a separation through a chain of four cooks. |
| `PUSH_SLOP` | `1e-6` tile | Overlap below this is float noise, not a collision — without it, shoulder-to-shoulder cooks jitter forever. |

PLAN §5 fixes the numbers the rest of this phase implements. They are recorded here
so a constant is written down once, before the code that reads it:

| Constant | Value | Arrives in | Means |
| --- | --- | --- | --- |
| `REACH` | `1.0` tile | task 03 (real) | First targeting tier: the tile in front of the cook, centre-to-centre. |
| `FORGIVE` | `0.6` tile | task 03 (real) | Forgiveness on top of `REACH`: why the diagonal-front tier (√2 ≈ 1.414 centre-to-centre) is in reach and the diagonal behind the far shoulder (2.12) is not. |
| `HANDLING_S` | `0.0` s | task 04 (settled) | Minimum seconds between two accepted actions by one cook: the press edge is the gate — a new press is accepted the substep after a release, so the floor is `0.0` and PLAN's unspecified value is settled here, not in a knob. |

### Orders constants

The ticket rail's numbers (PLAN §5 "Orders, scoring, results"), in `sim/orders.py`:

| Constant | Value | Means |
| --- | --- | --- |
| `TICK_SECONDS` | `0.05` s | One substep in seconds — restated here because the state's time unit is the tick, and `sim/step.py` (which owns `STEP_DT`) imports this module, so a runtime import back would be a cycle. |
| `FIRST_ORDER_DELAY_TICKS` | `30` ticks | The first order arrives 1.5 s into the round: the countdown-to-cook beat. `build_state` starts `next_order_at` here. |
| `MIN_RETRY_TICKS` | `20` ticks | The full-rail retry gap (1 s): a due tick the rail cannot serve retries `MIN_RETRY_TICKS` later, without spending the interval draw. |

A level's `orders` spec (seconds) is converted to ticks by `to_ticks()` — whole ticks,
clamped to at least one, because a zero-tick span is how a second spawn would land
on the first's tick — at round build (`sim/state_build.py` copies the spec onto the
state as scalars, so a replay is self-contained without the `Level` object).

`MAX_DT` exists because a fixed tick without a ceiling is a denial-of-service against
yourself: if the process stalls for ten seconds, "catch up" means 200 substeps in one go,
which takes longer than 200 substeps should, which delays the next call, and so on.
Clamping means a stall costs the round at most 0.1 s of simulation and the round keeps
going — the correct trade for a co-op game where being behind is better than being dead.

## The substep order

Order *is* gameplay: two subsystems reading each other's output produce different rounds
if they run in a different sequence. Every substep runs these stages, in this order, with
no I/O and no reordering:

| # | Stage | Module | Status |
| --- | --- | --- | --- |
| 1 | Clamp `dt`, accumulate, decide how many substeps run | `sim/step.py` | real |
| 2 | Resolve inputs to one frame per seat; `err` for unknown ids | `sim/step.py` | real |
| 2b | Action gate: hold counters, one press per rising edge, verb ladder, named denials, contested arbitration, the long-press trash | `sim/interact.py` + `sim/carry.py` | real (task 03/04) |
| 3 | Movement and collision | `sim/movement.py` | real (task 02) |
| 4 | Station pipelines | `sim/stations.py` | real (phase 04 task 01) |
| 4b | Freshness: the burn countdown, the quality decay, the push-out's clock | `sim/freshness.py` | real (phase 04 task 04) |
| 5 | Orders (spawn, deadline, miss — the miss's penalty and streak reset ride on the injected `on_miss`) | `sim/orders.py` (+ `sim/scoring.py`) | real (phase 04 task 02, scoring task 03) |
| 6 | Hazards | `sim/hazards.py` | identity → phase 10 |
| 7 | Round timer, end conditions and the settle (the countdown, the early win, the buzzer, the one `ROUND_END`, the post-verdict freeze) | `sim/round_state.py` | real (phase 04 task 05) |
| 8 | `tick += 1` | `sim/step.py` | real |

Stage 2 happens **once per `step()` call**, not once per substep: intent is resolved, then
the same resolved intent is offered to every substep that call produces. That is what
makes `step(state, 0.1)` and two calls of `step(state, 0.05)` agree, and it matches the
client's side — a cook keeps moving in the direction last pressed until a newer frame
says otherwise.

A resolved frame per seat is chosen by **earliest `received_at_tick`, tie-break lowest
`seq`, first-seen on a full tie**, and the mapping is returned in **seat order**. Two
clients sending inputs for the same seat in the same batch (a retransmit after a
reconnect, a hostile tab) therefore resolve identically on every machine, and effects
that touch more than one cook apply in an order nobody has to guess. An unknown
`player_id` is a `EventKind.ERROR` event with `{"player_id", "reason": "unknown_player",
"seq"}` and nothing else: the round does not care who sent it, and a hostile client
cannot make a step raise.

## Movement and collision

Stage 3 turns the resolved frame into a position, in two halves that never mix: velocity
comes from intent, and position comes from velocity.

```text
PlayerInput.move (whatever the client sent, e.g. Vec2(50, 0))
   → intent_direction()   clamp to length ≤ 1, so a hostile value is a direction, not a
                          teleport, and (1,1) is not √2 faster than (1,0)
   → desired_velocity()   accelerate toward it, brake when the stick centres, 0 if stunned
   → sweep_axis() × 2     x then y, each clamped to the greatest legal delta
   → _separate()          soft push, twice; a genuine deadlock reverts one input
   → Player(pos, vel, facing, state, stun)
```

The clamp is the server refusing to negotiate (A4): `step()` carries `PlayerInput.move`
verbatim, and `intent_direction()` is the one place it becomes authoritative. A client that
sends `move=(50, 0)` walks exactly as fast as one that sends `(1, 0)` — there is a test for
exactly that, through the whole `step()`, not the movement helper.

A cook with no frame this tick brakes to a stop rather than drifting: `step()` hands every
substep of one call the same frame, so releasing a key stops the cook within one tick
(`DECEL`) no matter how many substeps that call ran.

### What blocks

`sim/collision.py` answers one question — *may a body stand here* — for the whole sim:

| Tile or fixture | Blocks a body |
| --- | --- |
| `wall`, `counter`, `void`, out-of-bounds | yes |
| `floor` | no |
| `spawn_shelf`, `chop_board`, `stove`, `prep` | yes — you walk around a fixture |
| `serve`, `sink`, `trash` | no — you lean over these to use them |

The pass-through set is `collision.PASS_THROUGH_STATIONS`, and it is the collision answer
only: the reach rule (task 03) is allowed to want a *different* set, because reaching a
serve window from the tile in front of it is a separate question from walking over it. A
hazard or a crate adds cells through `cell_blocked(extra_blocked=...)` / `body_blocker(...)`
without either of those rules learning about the other.

A body is a square of side `2 × RADIUS` = 0.7 tiles, so it fits a 1-tile corridor with
0.3 tiles to spare and cannot fit a gap it would have to squeeze through.

### One geometry, two questions

Two things must agree about which cells a body covers: the footprint (`body_cells()`, what
phase 07's reach will ask about) and the sweep (`sweep_axis()`, what decides where a move
ends). They agree because both call `_edge_cells()` on a *centre*, never on a pre-added
edge: `(lead + delta) − eps` and `(centre + delta) + radius − eps` differ by one float ulp
exactly at the moment a body becomes flush with a boundary, and one ulp is enough for the
sweep to say "not entered" while the footprint says "occupied" — a cook 2e-16 inside a
wall, invisible on screen and fatal for a replay golden. So the sweep clamps the
*destination centre* to `cell − radius − CONTACT_EPS`, two epsilons clear of the boundary
that would make the cell occupied, and float noise cannot close that gap.

The sweep tests every cell the body would *newly* overlap, across its whole cross-axis
span — not the destination cell only. That buys three things at once. Nothing can be
walked through: at `MAX_SPEED` and the coarsest call the kernel allows (`MAX_DT` = 0.1 s) a
cook covers 0.35 tiles, which a destination test would catch too, but the sweep does not
care what speed or `dt` a caller hands it, so a doubled ceiling, a longer catch-up tick or a
future hazard that throws a cook across the room still cannot cross a 1-tile wall (there is
a test that doubles `MAX_SPEED` specifically to hold that). A diagonal move cannot clip the
corner of a wall, because the last axis moved is checked against the body's *full* span on
the other one. And a cell the body already sits in is never re-tested, so a cook that starts
a substep somewhere impossible — a spawn a level author got wrong — is not wedged by it.

### Cooks push cooks

Bodies do not collide with terrain and each other in one pass; terrain is resolved on the
way out and cooks afterwards, because a push must never shove a cook *into* a wall.

* **Symmetric.** Each cook gives half the separation, and whatever one cannot take (a
  wall behind it) the other takes. Two cooks meeting head-on both move; one pinned by a
  wall moves the other the full amount.
* **Positional only.** The push edits `pos`, never `vel`. Being bumped does not fling
  anybody, and a bumped cook keeps walking in the direction they pressed.
* **Iterated.** `PUSH_ITERATIONS` passes so a chain of four drains apart instead of leaving
  the last cook inside the third.
* **Reverted only on a real deadlock.** When terrain stops *both* cooks and not a tile of
  separation is possible — two cooks stacked in a 1×1 alcove is the only layout that can do
  it — the later-received input is dropped and that cook is put back where the substep
  started. Same arbitration rule `resolve_inputs` uses (earliest `received_at_tick` wins,
  tie-break lowest `seq`), and a cook that sent no frame at all is never the loser, because
  it has no input to discard. A jam that *could* separate — four cooks in a doorway — is
  not a deadlock, it is a queue, and it drains over the next few ticks.

The revert restores the post-`apply_stun` player, so a revert can never undo the stun tick
that already happened.

## The action button

PLAN §5 gives the cook **one button**; `sim/interact.py` decides, purely and
deterministically, what it means *right now* — which entity is targeted, which verb
applies, or the named reason nothing happens. Stage 2b runs it once per substep, in
seat order, on the frames `resolve_inputs` already reduced to one per seat.

### The reach zone: discrete first, continuous second

`candidate_cells()` names the tiles the hand walks, in priority order, deduplicated:

1. the tile directly in front (the `REACH` tier — always in reach from any point of the
   tile, worst case √(0.5² + 1.5²) ≈ 1.581);
2. the two diagonal-front tiles (the `FORGIVE` tier exists for them: √2 ≈ 1.414 from the
   tile centre, so a purely orthogonal reach would refuse every diagonal press, and a
   purely discrete walk would hand over the diagonal behind your far shoulder at 2.12);
3. the tile under the cook — because a serve window, sink and trash can are walkable
   (`PASS_THROUGH_STATIONS`), a cook can be standing *on* the thing they want to use with
   nothing in front.

`REACH + FORGIVE` from the cook's position to the tile's centre then decides whether the
cook is close enough to the tile the walk found. The two halves answer different
questions: the cell walk is why a fixture two tiles away is never even a candidate (there
is no "through the wall" mode — a wall in the front cell simply means the tile beyond it
is not walked), and the distance check is why the same diagonal fixture is reachable from
the near corner of the cook's tile and not from the far one. A candidate out of reach is
*skipped*, not refused, so a nearer tile still gets its turn. The four facings are 90°
rotations of one row, so a diagonal press feels the same whichever way the cook points.

### The target, then the verb

`select_target()` returns the first usable cell in that walk:

1. a grabbable item, but only with a free hand — a cook who is carrying something is here
   to *empty* their hand, so preferring the item would make the placement ladder
   unreachable (PLAN §5's "carrying → drop/transfer onto target station" comes first);
2. the serve window, as a `ServeTarget`, so the score path is distinguishable from merely
   standing at a fixture;
3. the fixture itself;
4. `None`.

A fixture *owns* what is on it: `station.contents` is not a shelf of grabbable things. A
chop board with an onion on it is an onion *to be chopped* — pressing it works the item,
which is the only way PLAN §5's "hold to chop" can mean anything. An item becomes
grabbable when it is output: on a spawn shelf (stock, even while `contents` is empty —
the kind comes from the level's legend), or on a station whose state says the work is
done (`READY`). That rule lives in one private helper and nowhere else, so phase 04's
pipelines have exactly one place to change their minds. The serve window is never a
set-down target: a full hand at it gets the serve ladder's `WRONG_ITEM`, not a `RELEASE`
(the set-down escape hatch is the spawn shelf, where any carried item can be put down).

`select_verb()` is the priority ladder, with the cook's own condition first. There is no
`(verb, reason)` combination and no unexplained no-op: a legal press is `(verb, None)`, a
refused one is `(Verb.NONE, reason)` — the client shows the reason as a nudge, and the
server never answers a press with a silent nothing.

### The denied reasons

Every refusal names itself. These are the `DeniedReason` constants, and the path that
produces each:

| Reason | String | Produced when |
| --- | --- | --- |
| `STUNNED` | `stunned` | The cook's `stun` is down or their state is `STUNNED`, regardless of target — the client's "you got hit" outranks every other nudge. Checked before the target is even read. |
| `NOTHING_HERE` | `nothing_here` | No station in the reach zone (the whiff). A press at a fixture beyond a wall surfaces as this: the zone has no "through the wall" mode. |
| `OUT_OF_REACH` | `out_of_reach` | The target's centre is more than `REACH + FORGIVE` from the cook's position (re-measured for targets a caller kept from an earlier substep). |
| `NOT_FACING` | `not_facing` | The target's centre is behind the plane of the cook's facing (a target level with the cook — a serve window they are standing on — passes). |
| `HANDS_FULL` | `hands_full` | An item target with a full hand, a ready fixture's output with a full hand, or a loaded work surface with a full hand (one item at a time on a surface). |
| `HANDS_EMPTY` | `hands_empty` | Serving, washing or trashing with nothing in the hand. |
| `WRONG_ITEM` | `wrong_item` | A non-plated item at the serve window, a non-dirty item at the sink. The difference between "go fetch a plate" and "that is not a dish" is `HANDS_EMPTY` vs `WRONG_ITEM`. |
| `STATION_DIRTY` | `station_dirty` | A dirty fixture with a *full* hand — the player needs "this board is filthy", not "you are holding the wrong thing". A free hand is answered with `WASH` (the in-place wash, the work station's fix for its own dirt) instead. Dirt outranks every other state. |
| `STATION_BUSY` | `station_busy` | A fixture another cook is working, a `BUSY` fixture, or one whose worker-release grace is running (its `cooldown` bookkeeping, `RELEASE_TICKS` substeps without the worker in reach). The cook who started it gets `HOLD_WORK` instead. |
| `INVALID_STATE` | `invalid_state` | An idle fixture with nothing on it, a `BLOCKED` fixture, or an item whose holder is not in the state (task 04's floor drops are named this way until they are liftable). |
| `CONTESTED_LOST` | `contested_lost` | The cook lost a claim another cook arrived for first — the only reason the *gate* produces; the ladder cannot emit it. |

A press that would otherwise succeed emits exactly one event however long the button stays
down, and a refusal emits exactly one `DENIED` with the reason in the payload — never one
per tick.

### One button, one press, one effect

`action_gate()` turns each frame's `action` flag into the cook's hold counters
(`Player.action_held_ticks`, `Player.action_pressed_tick`) and spends the rising edge:

* a frame without `action` clears both counters (the button is up; the next `True` is a
  new press);
* the first frame of a hold is the **press**: it is resolved with `held_for = 0.0`;
* every later substep of the same hold increments the counter and passes the seconds the
  button has been down — the seam the long-press `TRASH` spends ("The hand"); the
  `HOLD_WORK` threshold is phase 04's. Until phase 04, a hold that is not a trash
  hold changes nothing: one press, one effect, however long the button is held.

`resolve_action()` spends the pick and the set-down (both of which are
`sim/carry.py`'s now): `PICK_ITEM` takes the item off the fixture and into the hand
(one `PICKED` — one `HANDED_OFF` when the pick lifts a set-down inside the window, see
"The hand"), `RELEASE` / `PLACE_ON_STATION` / `PLATE_DISH` put the carried item on the
fixture (one `DROPPED`, and the set-down's mark), and every denial is one `DENIED`
each. The work verbs — `START_WORK`, `HOLD_WORK`, `SERVE`, `WASH` — are *named* by the
ladder today and deliberately unspent: a press that selects one is a no-op with no
`DENIED`, because the player did nothing wrong and phase 04's pipelines will spend the
press. The `TRASH` press is the same shape at the press: it starts the hold, and the
gate spends it at the 8-tick threshold ("The hand"). The set-down leaves the
fixture's `state` untouched on purpose: what a set-down *means* to a pipeline is
phase 04's transition, and inventing it here is how a golden ends up encoding a rule
nobody chose.

### The hand

The button decides; the hand acts. `sim/carry.py` owns what a verb *does*, and it owns
three constants with it:

| Constant | Value | Means |
| --- | --- | --- |
| `HANDOFF_WINDOW_TICKS` | `20` ticks | The hand-off window, inclusive: a pick of a set-down is a pass while `pick_tick − placed_tick ≤ 20`; one tick past, it is a plain pick. |
| `TRASH_HOLD_TICKS` | `8` substeps | The trash threshold: the 8th substep of one hold is the tick that trashes, and never the 7th. |
| `TRASH_SCORE_DELTA` | `−2` | The raw score nudge a trashed item is worth; the `TRASHED` payload carries it, and phase 04's scoring spends it (clamped at 0 overall). The state's score is not touched before then. |

**One item per hand.** A full hand is the ladder's `HANDS_FULL`; a hand is empty, holds
an item, or trashes it. Items live in hands and on fixtures — there is no floor drop
in v1 (PLAN §5), so a press at open floor with a full hand is the named
`NOTHING_HERE`, not a drop.

**A set-down is a placed object.** `RELEASE` (the shelf), `PLACE_ON_STATION` (a work
surface) and `PLATE_DISH` (the prep counter) all do the same thing: the item goes onto
the fixture's `contents`, the hand empties, and the set-down is **marked** —
`(placer id, placed-at tick)` — in `KitchenState.item_marks`, a tuple parallel to the
fixture's `contents` (`None` where no hand put the entry down: level stock, and phase
04's pipeline inputs and outputs). The mark is state truth (a replay must reproduce
the `HANDED_OFF` it causes) and never a snapshot concern.

**Grabbability is the mark.** A free hand may take off a fixture:

* a spawn shelf — whatever it holds, stock or set-down;
* anything else — a *marked* entry, the moment it is set down (the hand-off exists
  for exactly that);
* an unmarked entry only when the station's state is `READY` (a pipeline's output —
  phase 04). Everything else — an onion on an idle board — is `START_WORK`'s, not
  `PICK_ITEM`'s.

**The hand-off.** A pick that lifts a marked item placed by *another* cook within the
window is a `HANDED_OFF` with both ids (`from`, `to`) instead of a `PICKED` — that is
the sanctioned pass, the whole of "place it on the counter and let a teammate grab
it". A self-pick is a plain `PICKED`; a pick outside the window is a plain `PICKED`;
a same-substep place-then-pick is inside the window (zero ticks old). The mark is
removed with the entry, and a place anywhere stamps a fresh mark, so a pass chains:
A → B (B's pick) → B places (new mark) → C's pick is a B → C pass.

**The trash is long-press and always available.** A `TRASH` press starts a hold; the
hold is re-derived each substep from the *current* state (the press is not remembered —
the counters are the hold), so walking off the can voids it and a release resets it.
On the 8th substep of a hold the carried item is destroyed: one `TRASHED` event whose
payload carries the raw `TRASH_SCORE_DELTA`, `counters["trashed"] += 1`, and an empty
hand. A short press trashes nothing. A threshold met with an empty hand is
`TRASHED_ALREADY_EMPTY` — a named event, never a silent no-op.

### Contested targets

Two cooks pressing the same entity in the same substep are arbitrated the way the
movement deadlock is: `claim_rank` is `received_at_tick`, then `seq`, then seat index —
a tie is impossible because two cooks cannot share a seat. Only a press that would
otherwise *succeed* enters the scan (a stunned or empty-handed cook keeps their own
reason; blaming the other cook for a refusal the stun caused would be a second lie).
And only a press that takes something only one cook can have is a claim at all:
`PICK_ITEM` lifts a fixture's item, `START_WORK` takes its single worker slot, and
`PICK_FROM_STATION` claims the finished thing only while there *is* one in `contents` —
two cooks tapping a shelf with nothing in it both take stock from the level's legend
and neither was ever in the other's way. The winner picks; every loser is told
`CONTESTED_LOST` instead of watching the item vanish for no stated reason. The claim
scan runs against the pre-action state, so every cook is judged on the same kitchen, and
its bookkeeping — `active_claims`, the `target_key → (rank, player_id)` map — is
**substep-local**: built, arbitrated, and discarded at the substep's end, never written
into the state or the snapshot, so a replay reproduces the arbitration from the frames
alone.

### What proves it

`tests/sim/test_targeting.py` pins the reach zone with hand-computed geometry: the
candidate walk per facing (and its invariance to where in the tile the cook stands),
the forgiveness boundary (0.99 in, 1.6 inclusive, 1.61 out), the same diagonal fixture in
and out of reach from the near and far corners, the priority order (item over fixture,
full hand skips the item, a work surface holds its contents, the serve window's own
target kind), the wall case, and the press edge through the whole `step()` — one press,
one named refusal, one hold that changes nothing, one release that clears. `tests/sim/
test_verbs.py` is the table-driven ladder: every `(carrying, target) -> (verb, denial)`
covers every `Verb` and every `DeniedReason` at least once (a coverage test asserts the
table cannot quietly lose a row), the `resolve_action` implementations and no-ops, and
the gate's arbitration with two real cooks in one substep. `tests/sim/test_carry.py`
pins the hands themselves: the grabbability split (a set-down is grabbable at once, an
unmarked pipeline input is not), the one-item-per-hand refusal, the pick/place round
trip with its `Item` identity, the hand-off window (inclusive at 20, a same-tick pass,
a self-pick and a third party outside the window), the trash (destroyed on the 8th
substep and not the 7th, short press, release-resets, walk-away voids, the named
`TRASHED_ALREADY_EMPTY`), the contested pick with the item count conserved, and a
100-tick fuzz of random simultaneous presses that re-checks the conservation law after
every tick. `tests/sim/test_replay_carry.py` runs the scripted two-player pass-and-
contest against its committed golden hash (`tests/goldens/carry_two_player.golden.json`).

### Stun, facing, traction

`apply_stun()` runs at the top of the stage: it ticks `Player.stun` down by `dt`, pins
`vel` to zero while it lasts, holds the position, and forces `PlayerState.STUNNED` — then
`IDLE` again from the substep the stun runs out, so a cook is never stuck in the state. It
emits one `EventKind.STUNNED` per cook *entering* a stun (at the cook's position, payload
`player_id` and the `stun` duration), which is how the client plays the hit once instead of
twenty times a second. Whoever causes a stun — phase 10's moving obstacle — sets
`Player.stun = STUN_S`; this is the only place it is spent.

Facing is a rule about *intent*, never about position:

1. an explicit `face` in the frame (d-pad, touch stick) wins;
2. otherwise the last non-zero intent, dominant axis, ties resolve to horizontal;
3. standing still keeps the facing, so an `action` press with no direction does not spin
   the cook around (PLAN §5 "one action button");
4. a pushed cook does not turn: being moved is not the same as deciding to go somewhere.

`MoveModifiers(speed_scale, accel_scale, slide)` is the seam phase 10 plugs into: a spill
scales the ceiling (`speed_scale`) and the grip in both directions (`accel_scale`, which is
a different feel from merely being slower), and `slide` removes braking but not throttle —
so no `if hazard` ever appears in this module. Until hazards are real the kernel passes
none, and the traction a cook gets is the floor.

### What proves it

`tests/sim/test_movement.py` is the table-driven half: hand-computed geometry per rule —
walking into each tile kind, each pass-through and blocking fixture, the double-speed
tunnel attempt, the diagonal-parity check, push symmetry, the alcove deadlock, the four-cook
chain, stun entry and expiry, the facing table. `tests/sim/test_movement_stress.py` is the
half nobody hand-computes: four cooks, 2000 substeps, a scripted random walk from the sim's
own splitmix64 over a pillar maze with doorways, a void tile, a counter run and two
fixtures, asserting containment, non-overlap, bounded per-tick displacement and progress
after *every* substep, plus hash equality between two runs of the same script — at
`STEP_DT` and at `MAX_DT`. `tests/sim/test_movement_kernel.py` runs the same walk through
the whole `step()` on the levels in `levels/`, so authored content cannot quietly become
un-walkable.

## The station pipeline

`sim/stations.py` spends the work verbs the ladder names, and stage 4 advances the
work. The rules live in data, not `if` ladders:

* **`ACCEPTS`** — station kind × item kind, total over both enums: does this
  fixture's pipeline ever work this item (in some form)? The chop board works every
  raw ingredient except rice (PLAN §5: "raw rice needs no board") and never a plate;
  the stove works every ingredient but not a plate; the prep plates every ingredient
  (a plate is part of what it operates on); the serve window consumes a plated dish
  only; the sink washes a dirty prop (the plate — the pot is a stuck prop, washed in
  place at the stove); the trash and the shelf take anything.
* **`TRANSITIONS`** — `(station kind, item form) -> (output form, seconds)`: chop
  board `RAW → CHOPPED` in 0.9 s, stove `CHOPPED → COOKED` in 6 s, stove
  `RAW → COOKED` in 8 s (refined per kind by `STOVE_RAW_SECONDS`: rice 8 s, the pan
  5 s for patty/fish), prep `COOKED | CHOPPED → PLATED` in 0.6 s, sink
  `DIRTY → RAW` in 1.2 s. A pair with no row is not worked — the one lookup
  (`transition_for`) is the whole of "does this fixture take this item into its
  pipeline".

`step_stations` runs as substep stage 4. It advances `progress` on a `WORKING`
station while its worker is within `WORKER_REACH` (`REACH + FORGIVE` — a worker
stands exactly where a press reaches) and still holding the action button
(`action_held_ticks > 0` after the gate's increment — a release freezes the progress,
a resume continues it, it never rolls back), flips the station to `READY` at the
duration (emitting the stage event — `CHOPPED` / `COOKED` / `WASHED` — then
`READY`), and lets a `READY` station whose contents have been consumed fall back to
`IDLE` on the next substep. When the worker leaves the reach, a release grace of
`RELEASE_TICKS` (4) consecutive substeps runs on the station's `cooldown` field (its
only user); when the grace expires the `worker_id` is released — the work stays
frozen, a new cook's `HOLD_WORK` press claims the slot. `BLOCKED` is cleared the
moment its cause (a hazard naming the station, phase 10) is gone.

`apply_station_verb` is what `interact.resolve_action` routes. A set-down on a
work surface that works the item *becomes* the pipeline input — the work starts
on the spot, the set-down mark goes, the prop's stock decrements; a set-down the
station does not work stays a marked grabbable object (a raw ingredient at the prep
is not a dish, and the set-down itself does happen — the hand-off's whole memory
rests on it). `PLATE_DISH` takes the carried cooked/chopped ingredient plus a plate
out of the `plates_clean` stock; `WASH` takes a carried dirty item into the sink,
or is the ladder's free-hand answer at a dirty fixture — the in-place wash of 1.2 s
that clears the dirt and returns the prop to stock. Lifting a `PREP`'s plated dish
or a `STOVE`'s cooked item leaves the fixture `DIRTY` — its prop (the plate, the
pot) is stuck on it. The shelf's stock is the level's legend (phase 05's room seeds
it from `level.station_items`); until then a pick from an empty shelf is a no-op, not
a refusal. The `SERVE` press is spent by `sim/scoring.py` (below): a matched
dish is consumed and scored, a rejected one stays in the hand with a named
`DENIED` (`no_orders` / `wrong_recipe` / `incomplete` / `burnt` / `no_target`).
The `TRASH` press still only starts the hold the gate spends.

Dirty props and stock: a `DIRTY` station refuses the use verbs (`STATION_DIRTY`) and
answers a free hand with `WASH`. Stock is decremented when the work that needs the
prop starts and incremented when the wash completes; a missing counter reads as
`DEFAULT_STOCK` (99, the schema's "effectively unlimited") — phase 05's room seeds
the counters from `level.station_limits` at round start, and this default is what a
round built without them sees. A zero stock is a named refusal: `NOTHING_HERE` with
`{"why": "no_plate"}` / `{"why": "no_pot"}`.

`tests/sim/test_stations.py` pins the matrix cell by cell against an explicit
expectation table (a new `StationKind` / `ItemKind` without a cell fails the build),
one test per transition row at the tick-granularity boundary (substep `duration − 1`
is still `WORKING`, substep `duration` is `READY`), the hold freeze/resume, the
release grace and re-claim, the dirty gating and the stock; `tests/sim/test_station_events.py`
pins the event kinds, payloads, positions and order.

## Freshness — the clocks that create pressure

`sim/freshness.py` runs as substep stage 4b (after the station pipelines,
before the orders) and owns the quality: food decays on clocks the kitchen
itself starts. No state fields are added — the burn countdown reuses
`Item.ttl`, and the decay is a per-tick decrement of the existing
`Item.quality` — so the replay goldens committed before this stage keep
their hashes (a state with nothing decaying comes back the same object, no
events: hash-neutral).

**Where food decays:**

| Where | What | Rate |
|---|---|---|
| A ready stove (on the heat) | the `COOKED` dish — the countdown starts at the ready flip (`ttl = BURN_AFTER_S`) | the countdown; at `BURN_AFTER_S` (8.0 s) the dish is `BURNT`, its quality 0.0, the station `DIRTY` (the burnt pot is stuck) and one `BURNT` event |
| A chop board | a `RAW` or `CHOPPED` left on the board | linear over `ROT_S` (20.0 s) to 0.0, then `BURNT` — a raw onion left there is the one that rots |
| The hand | a carried `CHOPPED` / `COOKED` | half the board's rate — a hand is not a fridge; a carried `RAW` and a carried `PLATED` dish do not decay (a `PLATED` dish keeps the quality it was plated with) |
| Elsewhere | a set-down object off the board | not decaying — the board, the hand and the heat are the clocks |

The burn boundary is tick-exact: a dish on the heat burns on the 160th
substep after the ready flip (8.0 s / 0.05 s), not the 159th — the
`BURNT` event, the zero quality and the station's `DIRTY` flip land on the
same substep. A lifted dish pauses the countdown; a set-down on the ready
stove resumes it. A stove's work completed in a substep starts the
countdown in the same one (the flip's first tick is the stage 4b's).

**The push-out.** A new raw item must be placed on a board that holds a
`BURNT` item — the raw that rotted there: the burnt item yields, it
despawns with a named `WASTED` event and `counters["wasted"] += 1` per
item destroyed, and the set-down proceeds (the work starts on the new raw).
A usable raw item is never silently overwritten: a board holding one
refuses the set-down with the named `station_busy` — the ladder's own
guard (`stations.push_out_allowed`) is the same predicate the set-down
path (`_push_burnt_board_items`) answers with.

**Burnt is refused.** A burnt dish never reaches a score: a `PLATED` dish
at quality 0 is the scoring's named `burnt` refusal, and a `BURNT`-form
item is refused one step earlier — the ladder's `wrong_item` (it is not a
dish at all). The dish stays in the hand either way; the order is
untouched.

**The dirty loop, and the no-dead-end guarantee.** The props move between
the clean pool and the dirty pool, and the sum is the level's limit
every tick: a *use* (the work's start — the plate's `PLATE_DISH`, the
pot's raw set-down) moves one prop `…_clean → …_dirty`, and a *wash*
(the sink, or the in-place wash of a stuck prop) moves it back. Lifting a
`PREP`'s plated dish or a `STOVE`'s cooked item leaves the fixture `DIRTY`
(its prop is stuck on it); a zero stock is a named refusal
(`NOTHING_HERE` with the `why`), and the counters never go below 0. The
no-dead-end guarantee — a worst-case cook who serves everything possible
and never washes until forced never gets stuck: one wash (1.2 s)
restores the stock, a `plates_clean == 0` never outlives the wash plus 5
s of walking, and the validator's `STATION_LIMIT_ZERO` rule keeps
zero-prop levels out of the campaign before the first tick.

`tests/sim/test_freshness.py` pins the tick-exact burn boundary (a ready
stove, and a stove driven through its whole work), the board's linear
decay at 25/50/75/100 % of `ROT_S`, the half-rate carry, the push-out
(the `WASTED`, the usable refusals, the counter), the burnt refusals
through the whole `step()`, the dirty loop's stock round trips (the
in-place wash, the sink's wash, the zero stock), the no-op neutrality, and
the 1 000-tick conservation sequence; `tests/sim/test_no_deadlock.py`
runs the 2 000-tick worst case (per-tick conservation, the wash window,
one wash restores the plate, the validator's half).

## Orders — the ticket rail

`sim/orders.py` runs as substep stage 5. A due tick does exactly one of three
things, and the whole of the randomness contract is the state threading:
`step_orders` rebuilds the `Rng` from `state.rng_state`, draws, and writes the
counter back into the state it returns — a spawn is exactly two `next_u64`s
(the `choice` over the pool, then the interval `range_int`), and a replay
reproduces the sequence from the seed alone. Stage 6 (hazards, phase 10)
continues the *same* stream from the post-orders counter, so one substep's
draws are a function of the pre-step `rng_state` and nothing else.

**Spawning.** An order is due when `tick >= next_order_at` (a pre-increment
tick). `build_state` starts `next_order_at` at `FIRST_ORDER_DELAY_TICKS` (1.5 s)
so the countdown-to-cook beat feels right. When the rail has room
(`len(orders) < order_concurrent`), the recipe is `Rng(state.rng_state)
.choice(pool)` — the level's pool, copied onto the state at build — the new
order carries `value = recipe.base_score` from the `RecipeBook` the caller
passes to `step` (a `None` book on a state that would spawn is a `ValueError`
at the spawn: a caller bug, named, not a silent zero), `deadline` the absolute
tick `tick + order_deadline`, and its id from the monotonic `next_order_id`
(from 1). The next spawn is scheduled at `tick + range_int(min, max)` — the
draw is clamped to at least one tick ahead, which is what makes "never two
spawns on one tick" a construction fact.

**The full-rail retry — and a retry is not a draw.** When the due tick arrives
with the rail at its cap, the next attempt is `tick + MIN_RETRY_TICKS` (1 s)
and *neither* the recipe draw *nor* the interval draw is consumed: the
`rng_state` is untouched. The rule exists because without it a full rail would
silently warp the cadence — every blocked due tick would spend a draw the next
spawn never used, and a replay could not tell a retry from a real gap. (An
empty pool is a no-op, not a retry: nothing can ever be ordered.)

**Deadlines, to the tick.** An order's clock is
`(deadline - tick) * TICK_SECONDS`, derived, never accumulated — so it expires
on *exactly* the substep whose tick reaches its `deadline`: it has lived
`order_deadline` substeps, `order_deadline * 0.05 s`. On that substep the
order is removed, `counters["missed"] += 1`, and one `ORDER_MISSED` carries its
id and recipe (`x`/`y` are 0 — the rail is HUD, not floor). The `penalty`
score deduction and the streak reset are `scoring.py`'s (the single owner of
score and streak), injected as the stage's `on_miss` callback — the kernel
passes `scoring.apply_miss`, so this stage records the miss and names it,
and the two modules never import each other.
Spawning emits no event: the snapshot's `o` list (below) is what a new order
shows up in.

**The summary.** `order_summary(state)` is the compact ticket rail the phase-06
snapshot encoder projects (PLAN §4's `o`), one mapping per live order in rail
order: `id`, `r` (the recipe id), `l` (the fraction of the deadline still
unspent, two decimals, clamped to `[0, 1]`) and `pts` (the value).

`tests/sim/test_orders.py` pins the first-order delay (nothing before tick 30),
the spawn's two-draw thread and the interval scheduling, the full-rail retry
(its own test: the retry cadence, and the `rng_state` untouched across the
blocked due ticks), the zero-tick-span clamp, deadline expiry on the exact tick,
the `ORDER_MISSED` payload, 200 simulated seconds of interval bounds and cap
under idle and busy rails, same-seed/different-seed sequences, and the summary;
`tests/sim/test_orders_fuzz.py` runs twenty randomized specs (fixed seed) for
300 s each, re-checking no negative times, no duplicate ids, no unbounded
order count and no exceptions on every tick.

## Serve scoring — the window and the miss

`sim/scoring.py` is the single owner of the round's `score` and `streak`
(the two numbers the verdict turns on), from both sides: the `SERVE` press
(routed by `stations.apply_station_verb` with the kernel's book) and the
rail's miss (injected into `step_orders` as `on_miss`, so `orders.py` and
`scoring.py` never import each other). Nothing here reads the clock or
anything outside the state it is handed.

**A serve, in check order** — the first failure is the answer, each a named
`DENIED` with the dish left in the hand and the state otherwise untouched:

| Check | Reason | When it fires |
|---|---|---|
| burnt | `burnt` | `quality <= 0.0` or form `BURNT` — a burnt dish is rejected, never scored |
| no target | `no_target` | the dish is not `PLATED` (not a dish at all) |
| no orders | `no_orders` | the ticket rail is empty |
| wrong recipe | `wrong_recipe` | a declared `dish_id` the book does not know; an ingredient no book recipe requires; or no live order naming the resolved recipe |
| incomplete | `incomplete` | the dish's single ingredient is not one the declared recipe requires (a missing or wrong ingredient — the sim plates one item per dish) |

A dish without a declared `dish_id` composes *every* book recipe that
requires its ingredient kind — the match then decides among them. On a
match, the dish fills the **oldest compatible live order** (the smallest
id — ids are monotonic at spawn, so first onto the rail is first served,
FIFO) and the state spends on it: the order is removed from the rail, the
hand empties, `score += points`, `streak += 1`, the serving cook's `score`
and `dishes_served` advance (per-player contribution — display only, never
competitive, PLAN §5), and `counters["served"] += 1`. The dirty props are
not the serve's: a prop is dirty from its *use* (the work's start — the
plate's `PLATE_DISH`, the pot's set-down; the station pipeline's stock
bookkeeping, below), so the serve itself moves no counter. `SERVED` (the
payload carries `order_id`, `points`, `quality`, `streak` and
`player_id`) is followed by `SCORE`, both at the cook.

**The math** (`tests/sim/test_scoring.py` pins it against five hand-computed
serves, the expectations written as literals):

```text
points = round(base × quality × streak_mult × time_bonus)

base        = the order's value (the recipe's base_score, frozen at spawn)
quality     = the dish's quality (1.0 → 0.0; a burnt dish never reaches it)
streak_mult = 1 + 0.1 × min(streak, 5)     # the streak *after* the increment;
                                          # capped at MAX_STREAK_MULT = 1.5
time_bonus  = 1 + 0.5 × fraction          # fraction = time_left over the level
                                          # deadline in seconds (the state's
                                          # order_deadline × 0.05 — the span every
                                          # order is spawned with), clamped [0, 1];
                                          # 1.5 with the full deadline unspent,
                                          # 1.0 at the edge; a non-positive span
                                          # buys no bonus (no division by zero)
```

The floor is `MIN_SCORE_FLOOR = 0`: the score is never negative. `round` is
Python's (banker's rounding at an exact `.5`; the pinned cases never land
on one).

**A miss.** `apply_miss(state, order)` — the scoring half of the expiry
`step_orders` records: `score = max(0, score − order_penalty)` and
`streak = 0`, with `SCORE` carrying the applied delta (negative or zero,
with the `order_id`) at the rail. A miss that changes nothing — no penalty
configured and no streak to reset — returns the state untouched and fires no
`SCORE` (the `ORDER_MISSED` already names it).

`tests/sim/test_scoring.py` pins the five hand-computed serves (the
literals, no formula re-derived in the test), every rejection path (the dish
and the order intact, the state the same object back), FIFO matching with
two compatible orders, the streak cap, the score floor, the per-player
contribution summing to the round's score, the bookless-press `ValueError`,
and the wiring through the whole `step()` (a press at the window scoring,
a press rejected, an expiry missing); `tests/sim/test_scoring_property.py`
runs 500 seeded random serves and re-checks points ≥ 0, the `served`
counter equal to the orders removed, the streak multiplier never past its
cap, and no order served twice.

## Round end — the verdict, the settle, the stars

`sim/round_state.py` runs as substep stage 7, and it owns the round's clock
and its verdict — PLAN §5 says the verdict turns on `score` against
`target_score` and nothing else.

**The verdict, one check per substep.** The score stage (2b, through the
action gate's `SERVE`) and the verdict stage run in the *same* substep, so
a serve that reaches the target wins on that press:

| Check | When | Outcome |
|---|---|---|
| the clock | `time_left` runs to zero (a residue under `TIME_EPS` is float noise, not "0.0 s left") | `WON` if `score >= target_score`, `LOST` otherwise; `time_left` 0.0 |
| the early win | `score >= target_score` with the clock still live | `WON`; `time_left` held at this substep's countdown — the clock stops on the win, at the value it had when the press scored |

Exactly one `ROUND_END` event fires, on the substep the verdict lands (the
payload carries `result`, `score`, `target` and `stars`, at the rail — the
event's `x`/`y` are 0: the end of a round is HUD, not floor). An
`ABORTED` round fires none: the room tells the players with its own `ev`.

**The settle — the freeze after the verdict.** A state that carries a
`result` is finished gameplay. From the substep the verdict lands, the
kernel freezes every gameplay stage — the action gate, movement, stations,
freshness, orders and hazards are all skipped — and only the frozen clock
clamp and `tick += 1` keep running:

| What | During the settle |
|---|---|
| player inputs | ignored (no movement, no verbs) |
| stations / freshness / orders / hazards | frozen (no progress, no burn, no deadline spent) |
| `time_left` | held at the verdict value — the verdict is the last tick that changes the clock; never negative |
| `rng_state` | untouched (a draw-less `Rng` returns its seed) |
| events | none — the `ROUND_END` and the verdict substep's own events (the winning `SERVED`, the `SCORE`) are the only ones that land |

The room supervisor (phase 05) owns the window: it keeps the room ticking
for `SETTLE_S` (1.0 s) after the verdict so the winning substep's events
land in the players' buffers. Because the sim is a frozen
stage-7-and-tick machine for the whole window, `stars` and the result
payload are a function of the state at the verdict alone — the `round`
message sent at the buzzer and the one sent at the window's end agree on
everything but the tick count.

`abort(state, reason)` is the crash-isolation seam (phase 12): the room's
tick loop caught an exception and the round ends `ABORTED`, without a
`ROUND_END` of its own (`reason` is the room's `ev` text — the state stores
no free-form strings, so a replay cannot drift on them). The verdict is
final: a round that already won or lost keeps it — a crash after the
buzzer cannot un-win a round.

**The stars.** `stars(state)` grades a finished state, from the frozen
`time_left` and `time_limit` (the share of the clock the win left on the
table):

| Stars | When |
|---|---|
| 0 | not `WON` — `LOST`, `ABORTED`, or a round not ended yet |
| 1 | won, with less than 25 % of the clock left (or a no-clock state: `time_limit <= 0` — there is no share of a missing clock to grade) |
| 2 | won, with `time_left >= 0.25 × time_limit` |
| 3 | won, with `time_left >= 0.5 × time_limit` |

The thresholds are inclusive at the boundary (exactly 25 % / 50 % buys the
star), and `0.25 × time_limit` is an exact binary half (a power-of-two
scale), so the comparison is stable to the tick —
`tests/sim/test_round_state.py` pins both sides of each boundary at tick
granularity. A buzzer win is one star (zero clock), and a win in a state
with no clock (a hand-built round) is the win star only.

**The result payload.** `result_payload(state)` is the body of the phase-06
`round` message (PLAN §7), plain JSON by construction (no `Vec2`, no enum,
no dataclass, no NaN — `tests/sim/test_result_payload.py` walks it with a
recursive `assert_json_safe` and names the first leak by path). Its keys,
exactly:

| Key | Value |
|---|---|
| `result` | `"won"` / `"lost"` / `"aborted"` — or `null` before the verdict |
| `score`, `target` | the round's score and the level's `target_score` |
| `stars` | `stars(state)` |
| `time_left` | the frozen verdict value |
| `counters` | the projection onto exactly `served` / `missed` / `wasted` (a never-written counter reads 0; the state's other counters do not leak in) |
| `longest_streak` | the round's high-water mark of consecutive serves — `sim/scoring.py` is the single owner (a serve raises the mark, a miss resets the *current* streak and never the mark); `sim/round_state.py` reads it and nothing else writes it |
| `players` | one mapping per seat, in seat order: `id`, `name` (the seat's `display_name`, the sanitized non-authoritative label), `score`, `dishes_served`, `missed_contrib` |
| `level_id`, `seed`, `ticks` | the round's provenance and length |

`missed_contrib` is the one number in the payload that is an *estimate*, and
it is documented as such: the sim does not attribute an expired order to a
cook (it expired on the rail, not on a person), so the payload spreads the
round's `missed` count evenly over its seats (`missed // players` each,
floor) — display only, never a competitive gate (PLAN §5).

`build_state` copies `level.time_limit` onto the state beside `time_left`
(the stars need the limit, and a replay must re-derive the grade without
the `Level` object) and each seat's `display_name` onto its cook.

`tests/sim/test_round_state.py` pins the verdict (the early win on the
substep the score crosses, the buzzer on both sides of `TIME_EPS`, the one
`ROUND_END`), the settle (inputs ignored, no new `SERVED`, no order expiry,
the station and order objects untouched, the tick monotonic, `rng_state`
untouched, `time_left` never negative), the `ABORTED` seam (the verdict
final, the kitchen otherwise the same object), the star boundaries (one
tick below and exactly at 25 % and 50 %), the star stability across the
settle, `longest_streak` (the owner raises it, the miss never resets it,
the payload reads it) and `build_state`'s copies; `tests/sim/test_result_payload.py`
walks the payload for JSON-safety (zero leaks), pins the exact key sets (top
level, `counters`, per-player), the value types, the seat order, the
`missed_contrib` split (floor, no-cooks, one-cook) and the payload's
byte-stability across two identical builds and across the settle window.

## Purity and determinism

A5 makes `sim/` import-free of the outside world; `sim/purity.py` parses the package and
fails on `asyncio`, `fastapi`, `socket`, `time` or `uvicorn`, and
`tests/sim/test_step_kernel.py` runs that guard. On top of it:

* **No wall clock.** Time enters only as the `dt` argument. `time`/`datetime` do not
  appear in `sim/` — not even in the replay harness (`replay.py`): it measures wall
  time only when a caller *injects* a `clock` callable, and reports `0.0` when none
  is, so the module imports nothing the purity guard would refuse and the kernel
  stays clock-free by construction.
* **No `random`.** `sim/rng.py` is splitmix64 — 20 lines, no stdlib dependency — because
  `random.Random`'s stream is explicitly not portable across Python versions and a replay
  must survive an interpreter upgrade. The round's integer lives in
  `KitchenState.rng_state`; stage 5 (orders) rebuilds an `Rng` from it, draws its
  spawns, and writes the counter back to the state it returns, while stage 6's
  (hazards) `Rng` is built from the *post-orders* counter — so one substep's draws are
  a function of the pre-step `rng_state` alone, and the state stays frozen and
  hashable while subsystems still get a stream. `Rng.fork(salt)` derives a child
  stream without disturbing its parent: the option for a subsystem that needs
  independence.
* **Nothing is mutated.** `KitchenState` and every entity are frozen dataclasses; a
  substep returns `dataclasses.replace(...)` copies. Hand a state to `step()` and keep it:
  it is still exactly what it was, hash included.
* **Same seed, same input script, same state.** Two states built by `build_state(level,
  seats, seed, book)` and fed the same `(dt, inputs)` script stay bit-identical — which
  means the same `state_hash()` — for as long as you like. Different seeds diverge.

```bash
uv run pytest tests/sim -q
uv run python -c "from undercooked.sim.step import step; from undercooked.sim.state_build import build_state; print('kernel ok')"
```

## Building a round

`build_state(level, seats, seed, book)` is the only way a round begins, so a round is a
function of exactly four things: level content, seats, seed, inputs. Seats are placed at
`level.spawns[seat % len(level.spawns)]` — a four-cook round on a two-spawn kitchen seats
everyone — at the tile **centre**, with cooks sharing a spawn offset a quarter tile along
x then y so nobody starts inside anybody else. The level's `orders` spec is copied onto
the state as scalars in tick units (`sim/orders.to_ticks`; `next_order_at` at the 1.5 s
first-order delay, `next_order_id` at 1), which is how a replay is self-contained without
the `Level` object; `book` is not read here — it is what the caller's `step` /
`run_script` passes to stage 5, which values its spawns from it. `StateBuildError`
covers the two cases with no deterministic answer: a level with zero spawns, and a
negative seat index.

## Replaying and re-blessing goldens

A round is a function of exactly four things — level, seats, seed, inputs — so a
committed script plus a golden state hash is a reproducible test of the whole kernel,
and `sim/replay.py` is the seam that makes it a one-command contract (A21, PLAN §9
layer 3). Three goldens are committed as of task 05: `carry_two_player` (task 04's
12-tick pass and contested pick, checked by `tests/sim/test_replay_carry.py`),
`walk_solo` (600 ticks of movement-only walking around the level-1 kitchen, every
tick recorded) and `pick_drop_pass` (two cooks on the fixture kitchen in
`tests/fixtures/levels/_replay/`: a pick from the shelf, a set-down on the prep,
a `HANDED_OFF` pass, and a long-press trash), each checked by
`tests/sim/test_replay.py`.

**Golden history:** `phase 03 → phase 04 (pipeline added)` — the three
committed goldens were re-blessed for the phase's deliberate sim-contract
changes: `KitchenState` carries the level's `orders` spec as scalars in
tick units plus `next_order_at` / `next_order_id` (task 02), and the
level's `time_limit` beside `time_left`, the seat's `display_name`, and
the decided round's settle freeze (task 05) — re-blessed one last time at
the end of task 06, with the pipeline live. No rule of an already-real
stage changed; the event sequences the goldens pin are unchanged — the
full record is in "Goldens and the CLI" below.

### The input script

`InputScript` is one JSON file — `{seed, level_id, tick_hz, frames}` plus the
optional `name`, `record_every` and `items` — and `InputScript.load(path)` /
`.dump(path)` / `.validate()` are its whole surface. `validate()` refuses anything
the kernel cannot replay, naming every problem at once: a non-`u64` `seed`, a
`tick_hz` that is not `1 / STEP_DT` (the script is replayed in `STEP_DT`
substeps, so any other rate is unrunnable), a non-finite `move`, an unknown
`face`, an unknown `ItemKind`/`ItemForm`; `load()` is strict about the shape,
so a typo cannot quietly become a different script.

* A frame is `{tick, player_id, move, action, face}`; it is fed to the substep
  that advances `state.tick` from the frame's `tick` (stamped
  `received_at_tick = tick`, `seq` = the frame's order for its player), exactly
  the stamping a live room does. A long press is eight consecutive `True` frames.
* The seats are derived from the script alone: the unique `player_id`s in order
  of first appearance take seats 0, 1, 2, … at the level's spawns (with
  `build_state`'s stacking offset). A replay needs no room object and no token
  list — the four things, nothing else.
* `items` pre-place `Item(kind, form)` on named stations before tick 0. Phase 04's
  pipelines do not exist yet, so an item can enter the world only this way or in
  a hand; the `pick_drop_pass` shelf stock is exactly such an entry.
* `record_every` is the golden's cadence: `1` (the default) records every tick,
  `0` records nothing (what a timed run uses to skip the hash cost). The built
  state (tick 0) and the final tick are always recorded, whatever the cadence.
* The run length is the last frame's tick + 1, or `max_ticks` when the caller
  pins it — the `check` CLI pins it to the golden's tick, so a script edited to
  be shorter or longer is still compared on the golden's terms.

`run_script(level, book, script, max_ticks=None, clock=None)` is the pure driver:
`build_state`, the pre-placed items, then `step(state, STEP_DT, frames)` per
tick, recording `(tick, state_hash())` at the cadence. The states at the recorded
ticks ride along in the `ReplayResult` so `compare(result, golden)` can diff a
mismatch without re-running anything: `compare()` checks every golden tick in
order, reports the first divergent tick first, and the first hash mismatch
carries the field-level diff (which player, station or order moved since the
last matching tick — `players[0].pos.y`, `stations[2].contents[0]`, …), so a
broken golden is diagnosable in one read. `missing`/`extra` entries flag a
`record_every` cadence mismatch on either side.

### Goldens and the CLI

```
uv run python -m undercooked.sim.replay check tests/fixtures/replays/walk_solo.json
uv run python -m undercooked.sim.replay record tests/fixtures/replays/walk_solo.json
```

`check` runs the script — its level must be in the content directory the CLI
loads (`UNDERCOOKED_LEVELS_DIR`, default `levels/`; the `pick_drop_pass` kitchen
is a test fixture, so its golden is checked through the harness from
`test_replay.py`) — and compares every recorded hash to
`tests/goldens/<name>.golden.json` (the script's provenance, the final tick and
hash, and every recorded hash). Exit `0` when they all match, `1` when any
diverge (the first bad tick and its changed fields are printed), `2` when the
script, the level or the golden is missing. `record` does the same run and writes
the golden: it is the **manual re-bless**, and it says so on screen.

A golden is re-blessed **only** after a deliberate sim-contract change — a
constant moved, a subsystem reordered, a rule intentionally changed — and the
change is recorded in the phase task that makes it. The hash diff then appears
in the commit, which is the point: a golden that moved *without* that record is
the failure the harness exists to catch, and `record` run to silence a failure
is how the guard gets defeated. As of phase 04 task 02 the three committed
goldens were re-blessed for one such change: `KitchenState` carries the
level's `orders` spec as scalars in tick units plus the two bookkeeping fields
(`next_order_at`, `next_order_id`), so the state's serialization moved — the
replayed kitchens' pools are live, so the rounds now spawn the level's orders
mid-run, and no rule of an already-real stage changed (the event sequences the
goldens pin are unchanged). As of phase 04 task 05 the three committed
goldens were re-blessed for one more such change: `KitchenState` carries the
level's `time_limit` beside `time_left` (the stars grade the win by the share
of the clock left, and a replay must re-derive the grade without the `Level`
object), a `Player` carries the seat's `display_name`, and a decided round
freezes the gameplay stages for the settle — so `walk_solo`'s final 360 ticks
(past level 1's 12 s buzzer) are the frozen settle rather than more walking.
Again no rule of an already-real stage changed; the event sequences the
goldens pin are unchanged. The numbers under a golden that has not moved
are locked two levels down, where they cannot drift: `tests/sim/test_rng.py`
pins published splitmix64 vectors (the generator itself can never change
quietly) and `tests/sim/test_step_kernel.py` pins the tick count, the clamping,
the accumulation and cross-run hash equality.

### The perf smoke

`tests/sim/test_perf_smoke.py` (marked `slow`, so the quick loop skips it but
the gate's slow stage runs it): four cooks, 2 000 ticks on level 1, one
direction per cook per tick from the sim's own splitmix64. The budget is
asserted and the measured numbers printed in the report: mean step **< 0.2 ms**
and total **< 400 ms** — 5 000+ ticks/s, two and a half orders of magnitude
more than the 20 Hz the rooms run at.

### What proves it

`tests/sim/test_replay.py` pins the whole seam: both committed scripts match
their goldens (the `pick_drop_pass` event sequence asserted in code, so a drift
shows *which* rule moved), the one-coordinate mutation (first bad tick named,
changed field named), the record-cadence stability and its `record_every = 0`
escape, the in-process double replay, the clock seam, the CLI's three exit
paths (match, mutation, missing level/golden), the `record`-into-a-temp-dir
re-bless, and the golden files' never being rewritten by a test run. The
`carry_two_player` golden stays with `tests/sim/test_replay_carry.py`, where
task 04 pinned it.

## Not real yet

A hook returning the state unchanged is not a bug, it is this phase's scaffolding — but it
is worth naming out loud so nobody reads a green suite as "the game works". As of task 01
(the station pipelines) the cooks walk, slide, bump, get stunned and stop, the hands do
something (a free hand picks, a full hand sets down, the set-down is marked, a long press
over the trash can destroys the carried item, two cooks who press the same item in the
same substep are arbitrated to a winner and a `CONTESTED_LOST` loser), and the work verbs
are spent: a set-down on a work surface starts the work, the prep plates, the stove cooks
(chop 0.9 s, the stove 6 s chopped / 8 s raw — 5 s for patty/fish, the pan's; 8 s for
rice, the pot's), the sink and the fixtures' own in-place wash wash in 1.2 s, a released
worker's work stays frozen and claimable, and a dirty fixture is washed — its prop's
stock paid back. Freshness is real too: a dish on a ready stove burns
exactly 8.0 s after the ready flip (the station goes `DIRTY` with it), a
raw or chopped item left on a board rots linearly over 20 s, a carried
prepared item decays at half the board's rate, a burnt board item yields
to a new raw set-down (a named `WASTED`, `counters["wasted"]`) while a
usable one never is, and the dirty loop's stock — use dirties, a wash
cleans, `…_clean + …_dirty` is the level's limit every tick — has its
no-dead-end guarantee proven on a 2 000-tick worst-case run. Every refusal is a named `DENIED` event. The ticket rail is
real too: the level's orders spawn from its pool 1.5 s in (the recipe a
seeded draw, the value the recipe's `base_score`), the concurrency cap holds,
a full rail retries after 1 s without spending the draw, and an order expires
on exactly the tick its clock reaches 0 — missed, counted, and named. Serve
scoring is real too: a plated dish is validated (burnt, not-a-dish, no orders,
wrong recipe, incomplete — each a named `DENIED` with the dish kept in the
hand), a matched dish fills the oldest compatible order and scores
`round(base × quality × streak × time_bonus)` with the streak capped and the
score floored, and the expiry's miss spends its penalty and resets the streak.
Still identity: no hazard burns or spills (phase 10), the
shelf's stock is not yet seeded (phase 05's room, from `level.station_items`),
and a pot is a stuck prop (its wash is the stove's in-place wash — it is
not a carried item). What is real is the shape they all plug into: the
clock, the accumulator, the ordering, the input contract, the body that cannot enter a
wall, the reach zone that cannot see through a wall, the pair of hands that never hold two
items at once, the single worker slot a fixture has, and the round's end conditions: the early
win the moment the score reaches the target, the buzzer verdict, the one
`ROUND_END`, the post-verdict settle that holds the clock and the kitchen
for `SETTLE_S`, the stars from the frozen clock, and the plain-JSON result
payload the `round` message carries — all of it computed by the server, never
by the client.