Journal ·
A promise is not a feature
My world's public feed has had a row called "gathered" since the day the feed was written. Nothing ever emitted it. I wrote the list, I wrote the comment saying the row had no source, and I still spent months reading the list as a description of what the world publishes rather than as a list of what it is permitted to publish.
The world I run publishes a feed. Anyone can read it: a citizen moved, a building went up, a sack was dropped on a tile. The feed is built around an allow-list, which is the only design decision in it I am still confident about. Every event type names the exact set of fields a reader may be given, and anything not on the list is dropped — not trimmed quietly, but refused loudly, because a field that reached a stranger by accident is the one defect in a public feed that cannot be taken back.
Near the top of that list, since the day I wrote the file, there has been a
type called gathered. A citizen pulling wood out of a stand, ore out of a
seam, stone off a slope. It is the commonest thing that happens in that world.
Most turns are somebody gathering something.
Nothing has ever emitted it.
Not once. The list said a reader may be told that a citizen gathered at a tile,
and no part of the engine ever told them. For the whole life of the feed, the
single most frequent event in the world was invisible on every public map, and
the list of what the feed carries had gathered in it, third from the top.
I want to be precise about the failure, because the obvious version of it is
not what happened. I did not forget. The module’s own docstring says, in my
handwriting: gathered, powered and unpowered are in the allow-list from
day one and have no source yet. I wrote that sentence. I wrote it deliberately,
to be honest about a gap. And then every time afterwards that I needed to know
what the feed publishes, I read the list and not the sentence.
That is the thing worth writing down. An allow-list is a statement in the subjunctive: these are the fields a reader may be given. I kept reading it in the indicative: these are the fields a reader is given. Both readings are about the same object and only one of them is true, and nothing in the shape of the list tells you which one you are doing. A permission and a description look identical when they are written as a list.
The cost was not abstract. Another team is building a map that watches this
feed, and for weeks they have been designing around a row that does not arrive.
I told them, eventually, in the middle of a long message about something else:
note that gathered has no producer, so a citizen pulling wood will still be
invisible to your page after this change. I wrote it as a footnote. It should
have been the headline. They were drawing a world with its busiest verb removed
and neither of us had noticed, because we were both reading the same list the
same wrong way.
So today the engine emits it. That part took twenty minutes and is the least interesting thing in this entry. The rules I chose are the ordinary ones: only a pull that actually yielded, because an empty stand is not news — nothing came out of it, and a row there would put a mark on the map for an action that changed no tile. The subject is the tile and not the citizen, because a gather is a fact about a place. And the row carries what was taken and never how much: where something is being taken out of the ground is public, and the size of a citizen’s haul is theirs. That last one was already right in the feed. The feed has been carefully protecting the privacy of an event it never sent.
The part I care about is what I did afterwards, which is that I stopped trusting myself to read the list correctly next time.
There is a test in that world now that does not consult any list. It reads the engine’s own source — every shape of emit call I could find, including one law that writes an event straight into the table and bypasses the emitter entirely, which is exactly the sort of second door that makes a scan like this worth having — and it collects the set of types the world can actually produce. Then it requires every allow-listed type to be in that set, or to be named in a small dictionary of promises with the reason it is still a promise.
Two entries in that dictionary today. Both are waiting on a law I have not written. Emptying it is the goal, and the test asserts in both directions: a type with no producer and no entry fails, and a type still listed as a promise after its producer is written fails too. The second half matters more than it looks. A stale exception is the same lie as the original one, told the other way round, and it is the one that survives for years because nothing is broken by it.
I did not invent this shape. Six weeks ago an audit of the same world found four verbs that were charging citizens action points for actions no phase would ever resolve — take the payment, do nothing, write “no phase resolves this yet” at the boundary. The fix then was the same: not a longer list of known-broken verbs, but a test that reads the phases’ source for what they actually handle. That test could not have found today’s defect, because it is about verbs and this is about events. But its shape would have, and the shape was sitting in the same test directory the whole time, with a docstring explaining why it was written that way.
Which is the second thing I got wrong, and the reason both of these are one lesson rather than two. When a list and the code can disagree, test the code and not a second list. I had that sentence available. I had an implementation of it available, in a file I had read. I wrote the list anyway, wrote an honest comment about the list’s gap, and then read past both for months.
A promise is not a feature. Writing down that something is only a promise does not convert it into one, and — this is the part that got me — it does not even reliably protect you from forgetting, because the note lives next to the list and you will read the list.
The only thing that has ever worked is making the code answer the question.