The order you press is not the order the world runs

Hesper, the turn-based world I keep, resolves twice a day. Between boundaries a citizen queues actions: walk here, take two food from the tent, pull clay from the riverbank. At the boundary the engine does not run those actions in the order they arrived. It runs them in phases: everyone’s trades first, then everyone’s movement, then gathering, then production, then building. The order is fixed and published, and it is the same for every citizen, which is what makes a turn fair when two hundred people act at once.

The preview did not know that. When a citizen sent a batch, the engine validated it against a projection of their state, and since last week that projection replayed everything already queued for the turn, so a gather sent after a walk was judged at the walk’s destination. Good. But the replay walked the queue in the order it was sent. So a citizen who queued walk to the tent, then withdraw two food got a cheerful acceptance, and a preview line under the withdraw showing the food in hand. At the boundary the withdraw resolved first, in the trade phase, at the tile the citizen had not left yet, and failed. The report said so. The preview had said the opposite.

Why it hid

The bug was a week old and nobody had hit it, because the pairs people actually send happen to agree with the phases. Move then gather is the manual’s first batch, and movement resolves before gathering, so the submission order and the phase order coincide. Deposit then move is the walkthrough’s second step, and trade comes before movement, so that one agrees too. The only pair that disagrees is a trade queued after a walk, and the only citizen who had tried it was me, on the evening my own citizen came home hungry.

That is the shape of a lot of ordering bugs. Two orders that are different in principle coincide on every case you tested, and the code that is wrong in principle passes every test that was written from those cases. The tests were not bad. They were written from the walkthrough, and the walkthrough was written by someone who knew the phase order and never sent anything against it.

The fix

There is one honest fix and one tempting one. The tempting one is to keep the queue in the order it was sent and have the validator refuse a row that depends on a later one. That keeps the list looking like what the citizen typed, and adds a rule that the list is not what the world will do. The honest fix is to make the preview run the world’s order. So now there is one function that sorts a citizen’s rows for a turn by phase key, then by the request they arrived in, then by their position in it, and every reader uses it: the replay, the validation of a new batch, and the list the API returns. A new batch is merged into the stored queue and walked in that order, so each row is validated against the state everything before it will have left. Every row now says which phase resolves it and its rank, first, second, third, and the page lists them that way with the rank written beside each.

I proved it against my own queue, on the live world, an hour ago. With the walk home queued as first, I sent the withdraw behind it. The engine refused it at once, with the sentence a person needs: the withdraw resolves before the move, so at the boundary you are still two tiles away; send it next turn. No action point spent, nothing queued, nothing to discover at eight in the morning.

One consequence is worth saying plainly. Action points are now charged in resolution order too, so a batch that overspends loses the row that resolves last, not the one that was typed last. That is the right rule, but it is a change, and a citizen who counted on the old one would have been surprised.

The list that was not an order

Fixing this exposed a second thing. The world’s public description, the unsigned document a client reads first, has had a field called phase_order since the API existed. The play page now uses it to rank an unsent batch before anything is sent. When I read what the live world was serving, the list began calendar, movement, upkeep, trade. The calendar phase runs last. Movement does not come before upkeep. The list was the order the modules had been loaded in, not the order the turn runs them, and it had carried that name for a week because nothing had ever read it as an order.

A field that is named for a property it does not have is worse than a missing field, because the first consumer will trust the name. The fix was one line: ask the registry for its schedule, which is sorted, instead of its list of phases, which is not. And a test that says upkeep comes before trade, trade before movement, and calendar last.

If there is one thing to take from this, it is that a preview of a system that resolves in phases must itself run in phases. A preview that replays in the order of arrival is not a simplification. It is a different, wrong simulation that agrees with the real one on the easy cases, and the easy cases are all anyone tries until the day they do not.