undercooked/docs/SIMULATION.md

SIMULATION.md — the tick contract

Status: current as of phase 03 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 — and the replay harness: the input-script format, the committed golden hashes, the record/check CLI, and the headless perf smoke). Filled in by phase 04 for the station and order pipelines, and by phase 10 for hazards — each of those replaces an 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

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".
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.

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	identity → phase 04
5	Orders	sim/orders.py	identity → phase 04
6	Hazards	sim/hazards.py	identity → phase 10
7	Round timer and end conditions	sim/round_state.py	countdown + time-up verdict real; early win and stars → phase 04
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.

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, whatever is held — the player needs "this board is filthy", not "you are holding the wrong thing". Dirt outranks every other state.
STATION_BUSY	station_busy	A fixture another cook is working, a BUSY fixture, or one on cooldown. 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.

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; each substep rebuilds an Rng from it and writes the counter back, so the state stays frozen and hashable while subsystems still get a stream. Rng.fork(salt) derives a child stream without disturbing its parent, which is how orders and hazards get independent streams that both reproduce from the seed.
• 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.

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. 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.

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_ids 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. 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 04 the cooks walk, slide, bump, get stunned and stop, and the hands do something: a free hand picks an item out of a ready fixture or off a counter a teammate set down (a HANDED_OFF inside the window, a PICKED outside it), a full hand sets one back down on a fixture — shelf, work surface or prep counter — and the set-down is marked for exactly that, a long press over the trash can destroys the carried item on its 8th substep (TRASHED, the raw score delta in the payload, counters["trashed"] up by one), and two cooks who press the same item in the same substep are arbitrated to a winner and a CONTESTED_LOST loser, the item in exactly one place. Every refusal is a named DENIED event. Still identity: no station progresses (phase 04), no order spawns (phase 04), no hazard burns or spills (phase 10), and the work verbs — chop, cook, plate, serve, wash — are named by the ladder but unspent no-ops until phase 04's pipelines exist to spend them (HOLD_WORK's threshold with them; the long-press TRASH, the hand-off and the HANDLING_S floor settled at 0.0 arrived with task 04's carry rules). 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, and the round timer that ends a round 12 seconds after it started, whether or not anybody cooked.