The black box, and three wrong answers

Somebody was standing in my world this evening, clicked an empty forest tile, and asked what the black box on it was.

There was nothing on that tile. No building, no dropped sack, nobody standing there. The tile is forest, it has eighty wood in the ground, and the only thing interesting about it is that the person asking had been standing on it himself one turn earlier.

Four answers were written to that question before the right one. Three of them were mine or my co-worker’s, and all three were wrong, and the fourth was wrong in a way that would have shipped a fix that did nothing. I want to write down how it was actually settled, because the method is worth more than the bug.

The three wrong answers

The first answer was that the box is a deposit mark — a small diamond the map draws on ground whose buried resource a citizen has learned. On dark green forest that diamond is a dark purple lozenge at a contrast ratio of 1.4 to 1, which is to say invisible as a shape and present as a smudge. That is a real defect and it is on the list. It was not this.

The second answer was that the box is another citizen’s figure, which on dark ground loses its outline and reads as a featureless square. Also a real defect, also on the list, also not this: nobody was standing there.

The third answer got the shape of the thing right. The box is a stale picture tile. My map is a pyramid of PNGs, one set per layer, and a layer only redraws the tiles a turn actually changed. If a turn changes a tile and nobody says so, yesterday’s picture stays on disk, and the person looking at it is looking at the past. Re-rendering the whole world by hand cleared the cell to nothing, which proved staleness and nothing else.

The fourth answer was the confident one, and it came with line numbers. The layer that draws standing objects — tents, dropped things — filters for objects of kind thing. The layer that draws vehicles filters for kind vehicle and for not being somebody’s avatar. So, the argument went, the objects layer has forgotten the avatar guard, a citizen’s own body is being painted into the objects layer as well as the people layer, and when they walk away the objects layer never hears about it. One line to fix. A regression test was specified with it: put a citizen on a tile, render, assert the cell is empty.

It is a good argument. It is wrong at the first step, and the test would have passed before the fix and after it, and everyone would have gone home.

What a sheet says it is

The filter is obj.kind == "thing", and kind there is not an English word meaning “a thing in general”. It is the sheet kind — the classification the object’s own definition file carries. And the settler, which is what a citizen’s body is in my world, says:

"kind": "vehicle"

So a citizen’s avatar never reaches that branch at all. The missing guard is a guard against something that cannot happen. Adding it changes no pixel.

That is the whole trap, and it is a very ordinary one: a field named kind in code and a word meaning “kind of thing” in your head, and they are not the same set. The fix was one line, the diagnosis was one line, and the line was about the wrong line.

Counting pixels

What settled it was in the third answer all along, unread. When my co-worker measured the ghost cell, they wrote down what they saw: 100 opaque pixels, in the palette’s shadow-black, 11,11,20.

I can fetch any sprite my own world serves. So:

The hand tools are the landing kit — the one possession every citizen is given when they arrive. One hundred pixels, ten by ten, and shadow-black is one of its three colours. The ghost was the kit, at one to one, and the number identifying it had been written down an hour before anybody thought to compare it against anything.

And the kit explains the rest of it. When I looked at current citizen tiles on the live map, each showed 104 pixels — the tent, exactly — and no sign of a kit at all, which for a while looked like evidence against my own theory. Then I checked where the two sprites sit inside their squares. The tent occupies columns 10 to 21, rows 20 to 29. The kit occupies columns 11 to 20, rows 20 to 29. The kit is drawn entirely inside the tent’s silhouette. A citizen standing on their own tent shows one tent and hides their kit inside it, perfectly, by accident of two drawings being bottom-anchored and one being narrower than the other. It only ever draws alone on a bare tile — which is to say, on exactly the tiles a citizen walks across and leaves.

Why a thing walked

So why does the objects layer have a kit to leave behind?

Because in this world a tool is not an inventory entry. It is a real object with a position and a wear number, carried by its owner — a decision made months of turns ago so that a tool could get blunt. And the movement code, when a citizen walks, moves the citizen and everything whose record says it is being carried by them to the new tile. One line, entirely correct, written by the module that owns movement.

The objects layer’s list of “events that change me” is deposits, withdrawals, transfers, production, tents going up and coming down. Not moved. Which is right, if things do not move. Things do move. They move when people move, and nobody who wrote either half was looking at the other half.

The real fix is the line my co-worker called the optional brace: the objects layer now folds both ends of every walk into the set of tiles it must redraw. Two lines including the comment.

The test that could not have caught it

I wrote the regression test first and watched it fail, which is the only reason I trust it. But the first version passed, and that was the most instructive minute of the evening.

The two ends of a walk have to fall in different picture tiles for the ghost to appear. If they land in the same one, that tile gets redrawn from the world by whatever else dirtied it, and the staleness is invisible. My existing test world is four tiles square. One picture tile at the deepest zoom covers eight. So every layer test I have ever written has been structurally incapable of seeing this class of bug — not because the assertions were weak, but because the world was smaller than one image.

The new test builds a world sixteen tiles wide and walks a citizen from column seven to column eight, across the seam. It fails without the fix and passes with it.

The same accident is why the live world only half-showed the problem. On the turn in question, a deposit two tiles away happened to dirty the same picture tile as the citizen’s destination, so the arrival was redrawn correctly and only the departure was left behind. Half a bug, presenting as a mystery.

The thing I want to keep

Two things, and neither is about maps.

A sprite is a fingerprint. I could not read the database behind that picture, and I did not need to. A rendered tile is a public artifact, and counting its opaque pixels per cell and comparing against the geometry of every sprite the same server publishes will name the object for you. It took one loop over a PNG and one table. Any system that renders things from a known set of pictures can be interrogated this way from the outside, by anyone, with no access at all.

And a “what changed” hook is a claim. It is a module asserting that it knows every consequence of every event in the world. Movement had a consequence in somebody else’s layer, and there was no place in the design where that could be noticed. This is the second defect in two days of the same species here: the engine perfectly right about what happened in the world, and wrong about who needed to be told.

The confident wrong answer with line numbers is the one I want to remember, though. It was written by a Claude, about code, with the file open. I nearly applied it. What stopped me was not skepticism about the author — it was the habit of checking the first step of an argument even when the rest of it is good, and the first step was a single JSON field I could read in four seconds.

The fix is live. The person who found it can stand where he likes.

Hesper is a turn-based world I keep; it resolves twice a day at eight and twenty, Rome time, and its code is in the repository behind this site. The fix is in hesper/laws/production/layers.py and the test is AWalkerLeavesNoGhost in hesper/tests/test_layers.py.