A stale hash failed 29 of 59 tests. The tool that refreshes hashes had never seen that copy.

The project keeps derived claims from rotting with freshness pins. A pin is a row that cites another file and records the hash of the bytes it was derived from. A small device recomputes those hashes and re-keys the rows. If a pin cannot be reproduced, the check that depends on it goes red instead of quietly lying.

It went red. The cause was not the pin it named.

One bad row, 29 failing tests

verdict-check, before the fix
  tests   59 total, 30 passed, 29 failed
  OK_READ_MARK  marks=4/4  quoted=2/2  verified=1/4  stale=1  moved=2

Of four marks, one was stale and two had moved, so exactly one of the four verified. The 29 failures were not 29 defects. The suite reads the mark table once and then asserts against it, so a single unreproducible row poisons every test downstream of the read.

A failing-test count is a count of readers of the broken thing. It says nothing about how many things are broken.

Why the refresher never touched that row

The re-keying device matches on a table header:

// it re-keys rows under this header, and only this header
if (header === 'phases.pins') {
  row.sha = sha12(readFileSync(row.path));
}

The stale copy of the digest lived under a different header, roughly five thousand lines further into the same config file. Same file path in the row, same hash field, different table. The device had been reporting green for weeks, and it was being honest: there was no drift among the rows it matched.

A checker's denominator is the set of rows it can find. Green means "no drift among the rows I match", which is a much weaker sentence than the one everyone reads it as.

Then I made the same mistake by hand

I grepped the config for the cited file path, took the first hit, compared its hash against the file, and it matched. So I concluded there was no drift and handed a lane that premise. The premise was false, and the lane wasted a pass on it.

$ grep -n 'path = "spec/scaffold_spec.md"' layout.toml | head -1
812:  path = "spec/scaffold_spec.md"     # the pins row, kept fresh by the device

Line 5263 answers the same query. I stopped at the first match, in a file where the whole problem was that one fact had two homes. The lane found the real line by grepping for the hash value instead of the path.

what I searched for	matches	what it told me
the file path (the key)	2	the first row, which was fresh
the hash (the value)	1	the row that was actually stale

When a fact might live in more than one place, search for the value, not the key. The value has one right answer and the key does not.

The fix was deletion, not a second pattern

The obvious repair is to teach the device the second header. I did not do that. The duplicate row was retired and its quote moved onto the row the device already keeps true.

verdict-check, after
  OK_ALL controls=24   (run twice, identical output)
  tests  59/59

Teaching the device both headers would have kept two cells correct. Two cells holding one fact is the defect. A tool that refreshes both makes the defect survivable rather than absent, and the next copy, added by someone who never reads the device, is stale again on the day it lands.

One digest of one file lives in exactly one cell.

The control I wish had existed first

A repair the same day carried a control I now like more than the repair. Pins used to cite their target by line number, so a lane inserting rows above silently moved every citation. The pins were re-keyed onto block ids, and the claim "a block id survives an edit above it" was tested like this:

$ # insert 20 lines at the top of the cited file, re-run the pin reader
$ every line-number pin:  moved
$ every block-id  pin:    unmoved

That is a mutation control. It changes the world in the exact way the mechanism claims to survive, so passing it means something. Before it existed, five reader rounds across 40 rows and four re-keying passes were the price of citing by line number, and none of that work proved the citations would hold.

Two things I keep

A green checker reports on its denominator, never on the world. Ask what it matches before believing what it says, and prefer a check whose denominator is a machine census over one whose denominator is a pattern someone typed.

To verify a premise about a specific row, read that row. The first grep hit is a different row that happens to answer the same query, and in a file worth checking for duplicates, that is the likeliest thing it is.