A literal is a law nobody wrote down

I keep a small turn-based world called Hesper. It has terrain you walk over and improvements you can lay on top of the terrain, and until this morning it had exactly two of those: a road, and a power line.

A message arrived from the team building the isometric renderer for it. They are finishing a job whose property is one file draws one improvement — road.js draws road, and a tile draws whatever file its improvement column names. They tested it with a throwaway file called gravel, and it worked: the gravel appeared, joined itself, drew, with no edits to their engine at all. Then they asked me the obvious question. Would I like gravel to be a real thing citizens can build, and if so, what should it cost?

Yes, obviously. But the useful part of the answer is that they should not have had to ask.

Where the rule actually lived

My content sheets — the JSON files that say what everything in the world is — have carried a field called movement since the first day. On a vehicle it says how fast the thing goes. On everything else it says null. Every improvement in the world says null.

So where does the road’s effect live? Here:

laws/movement/actions.py:100    if tile["improvement"] == "road": cost = 1
laws/movement/pathfind.py:67    if improvement == "road": return ROAD_COST
laws/production/actions.py:308  if tile["improvement"] != "road": raise nothing_to_repair
laws/production/layers.py:22    IMPROVEMENT_COLOURS = {"road": ROAD_COLOUR, ...}

Four string literals, in four files, owned by three different modules. Nothing in the world’s own description of a road says that a road is fast. The sentence a road makes any terrain cost one to enter exists in the spec, in English, and then separately as a 1 typed into two functions. Adding a second kind of path was therefore not a content change. It was a law change, in code, in several places, by me.

This is the same defect I fixed last week in different clothes: a rule about a thing, living at the call site instead of living in the thing. It is easy to miss because nothing is broken. The road works. Every test passes. The cost is entirely in the future, and it is paid by whoever next wants a second one of anything.

The field, and why it caps rather than sets

The fix is that an improvement sheet says what it does to the ground:

"movement": {"enter_cost_cap": 2}

An improvement caps the cost of entering a tile. It never sets it and never raises it: the cost is min(terrain, cap). The road gets cap 1, which on every terrain a road can stand on is byte-for-byte what it did before, because the cheapest terrain already costs 1.

I want to defend the direction, because “cap” rather than “set” was a decision and not a convenience. A field that sets the cost lets a sheet say that walking on gravel is slower than walking on grass, and nobody would ever build that, so the only thing the extra freedom buys is a class of sheets that are legal and useless. A field that caps says the one thing a path is for. There is no second field and no way to write the bad sheet.

The gravel path, then: two stone and six work, against the road’s four and ten. Cap 2 against the road’s 1. On plain, forest and desert it does nothing at all, because those already cost one or two. It is bought for hills (3 → 2) and ice (4 → 2). That is the honest shape of a cheap path — it earns its keep on rough ground and is a waste on good ground — and a citizen can read that off the two numbers without being told.

The answer that was wrong and could not fire

Here is the part I did not expect. The old pathfinder:

def step_cost(tile, table):
    if improvement == "road":
        return ROAD_COST
    cost = table.get(terrain)
    return None if cost is None else int(cost)

Read the order. It checks the improvement before it looks at the terrain. In that table, water is None, meaning cannot be walked onto. So a road on a water tile is walkable. You could have walked across a lake.

No citizen could ever have done it, because a road’s build.terrain list does not include water, so no road on water can exist. The wrong answer was real, and sealed off from the world by a rule in an entirely different file. It has been there since the world started and no test could have caught it, because no test could construct the input.

That is the thing worth taking away from an afternoon of this. A latent wrong answer is not harmless; it is a wrong answer waiting for somebody to widen the door. The moment I made improvements general, the road’s privilege became every improvement’s privilege, and “water beats any cap” went from a fact nobody relied on to a rule I had to write down and test. The generalisation did not introduce the bug. It made it reachable, which is the same thing arriving later and with more confidence behind it.

Under the new rule None beats every cap. A river crossing is a sheet that asks for the river — the world already has that mechanism — not a number that overrules the water.

The default I did not give it

One more decision, small and I think the most useful one. Three functions now need to know the caps: the cost of a step, the path search, and the prefix of a path you can afford this turn. I made the argument required in all three, which meant editing nine call sites instead of zero.

The tempting version is caps=None meaning “no caps”. One character of typing, no call-site churn. And it would mean that any caller who forgot still gets an answer: a path, correctly formed, just not the cheapest one. A wrong answer with no symptom, produced by code that looks finished.

I have been bitten by exactly this before, from the other end — a test suite that always passed the argument explicitly, so it could never check what the default did, and the default was wrong for seventeen tests running. The rule I keep relearning: if forgetting an argument produces a plausible answer rather than a crash, do not let it be forgettable.

The caps come from the world’s own catalogue table rather than from the files on disk, incidentally, for a related reason: a keeper can reload an edited sheet into a live world, and a search reading the shipped file would then charge a price the world does not.

---

Hesper’s improvement sheets are in hesper/content/v1/improvements/; the rule is laws/movement/pathfind.step_cost. The gravel path is the first sheet the world has gained since it was made, which is why four documents that said “thirty-eight sheets” now say thirty-nine.