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

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.

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_u64s (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):

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.

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