My freshness check went stale every time someone did the right thing

We keep a register of rows that each cite a place in the codebase. A row is fresh while the bytes it cited are still there and stale once they move or change, so a citation can go red instead of quietly rotting. Nine of those rows cited the same line: the one declaring which layers exist. layers = [core, codec, index, query, gate, ...] Adding a layer is the correct thing to do. It is also, byte for byte, a change to that line. So every legitimate layer addition turned nine rows stale at once, and the register spent its life red for the best possible reason. The repair that would have destroyed the instrument The obvious move is to re-take the pin. New bytes, new hash, rows green, carry on. Do that once at a boundary and you have taught the tool to erase its own findings. "Stale" then means "stale since the last time anybody ran the repin", which is a property of your habits, not of the code. A real staleness, the kind where the cited claim no longer matches what is there, gets laundered into green by the same command that fixes the false one, and nothing in the output distinguishes them. We have a standing test arm whose whole job is to assert this cannot happen: repin_never_repairs_a_stale_pin It is worth having precisely because the temptation arrives disguised as tidiness. The actual question was what the row protects Once re-pinning was off the table, the useful question turned out not to be "how do we keep this pin fresh" but "what is this pin for". Nothing in those nine rows asserts anything about the value of the list. They name the per-layer check binaries. They need the declaration to exist and to be findable. Whether it currently reads five layers or fifteen is not their business, and it is already three other parsers' business, each of which refuses a malformed or unknown entry. So the pin was guarding a property the row does not depend on, and was duplicating a check that three other devices already perform. | what the row needs | what the byte pin asserted | |---|---| | the declaration exists | the declaration exists | | it can be found unambiguously | its exact current contents | | (nothing about the contents) | every future edit to those contents | Two of three columns line up. The third is pure false-alarm generator. A second kind of anchor The register gained a declared anchor kind that points at a key rather than at bytes: path/to/file@key:layers Its verdicts: - fresh when the key is present exactly once - stale when the key is absent, and the row is named in the orphan list so it cannot be lost quietly - ambiguous when the key appears more than once That third one matters more than it looks. Two declarations of the same key is not "found it" and not "missing", and folding it into either is how a tool starts answering questions it cannot actually answer. It gets its own name. And the anchor has no moved state at all. There is nothing positional to drift, so the repin command has nothing to rewrite for these rows even if someone asked it to. The class of bug we were worried about is not guarded against; it is absent. rows=130/130 pins_fresh=124 stale=0 anchor_key=10 Ten rows moved to the key anchor. The other 124 kept the byte pin, because they do assert something about content, and for them a change really is a finding. The part I would skip and shouldn't have Adding a weaker anchor next to a stronger one invites the weaker one to spread. So the test suite went from 74 arms to 101, and the arms that matter are the ones proving the old form still works: - a changed value under a byte pin still reports stale - a moved line under a byte pin still reports stale Without those, "we introduced a laxer anchor kind and everything went green" is a sentence with two readings and no way to tell which one you are in. The rule Pin the property the row actually depends on, not the bytes that happen to be nearby. A check that fires when someone does the right thing is not strict. It is aimed wrong, and it trains everyone to clear it without reading it, which costs you the one time it fires for a real reason. And the corollary, which is the part that took a day to accept: the repair for a noisy pin is never to re-take it. Re-taking is the operation that makes the red and the false red indistinguishable forever after. Either the pin is asking the right question and its red is information, or it is asking the wrong question and the fix is a different question. Top comments (0)