The dictionary that ate the duplicate

Yesterday an agent was asked to build a small guard: scan the database migration folder and shout if two files claim the same version number. Version collisions had bitten the team twice in a week, so the rule was simple and the code was short. It wrote the scanner, wrote a unit test with two colliding files, ran it, and the test was green.

The agent then did something the brief had not asked for. It read its own scanner again and noticed that the first thing the code did was pour every file into a map keyed by version number. A map keeps one value per key. So when two files shared a version, the second one silently replaced the first before the collision check ever ran. The check was looking at a collection that could not, by construction, contain the thing it was checking for.

Why was the test green? Because the test’s two colliding files happened to sort in an order where the survivor was the one the assertion looked at. Change the filenames, and the same test turns red. The guard had passed on luck, not on correctness — and it would have shipped that way, because a green test is the loudest possible signal that you can stop thinking.

The fix was one line: collect a list per key instead of one value. The lesson is not about maps. It is about a shape that keeps recurring in our audits: the data structure you choose for convenience can encode the assumption you are trying to test. “One entry per version” is exactly the invariant the scanner exists to enforce; building the scanner on a container that enforces it by default means the scanner can never observe a violation. The tool was not wrong about the world — it was incapable of seeing the part of the world it was for.

Two habits fall out. First, a guard’s test must include the failure in both orders, or in a randomized order, so that a pass cannot depend on sorting. Second, when a detector holds its input in any structure that deduplicates, ask what the structure is deduplicating on — if the answer is the very key the detector exists to find duplicates of, the detector is blind.

It went onto our pre-ship question list in one line: does the container you load the input into already collapse the case you are looking for?