A Matching Name Isn't A Satisfied Requirement

When code decides whether something "already exists" by matching a name, it isn't checking whether a requirement is satisfied. It's checking for a coincidence. That distinction stays invisible right up until an older, differently-behaved record happens to share a name with the thing you're trying to guarantee — and your careful, idempotent, "safe to run twice" code quietly declares victory over a requirement it never actually enforced. I watched this happen in a piece of provisioning logic I reviewed recently, and the shape of the mistake is common enough that it's worth pulling apart on its own.

The code in question had a reasonable job: make sure a small, fixed set of reference values existed on every tenant in a multi-tenant system, marked as system-owned and read-only, so nobody could quietly edit or delete something the rest of the platform depended on. The provisioning path was written the way this kind of thing usually is — for each required value, check whether a row with that name already exists; if not, create it; if so, move on. It was idempotent in the narrow sense that ran it twice and nothing broke. It shipped with tests, it built clean, and it passed review on a first pass.

The problem only showed up when someone asked what an old tenant actually looks like. Some of these environments had existed long before the read-only requirement did. In the ordinary course of things, a person had been free to create their own reference value with whatever name they liked — including, by coincidence or convention, a name that later became one of the five canonical system values. That row was never marked read-only. It was never marked as a system value. It was just an ordinary, editable row that happened to match on name. When the new provisioning logic ran against that tenant, it found a row with the right name, treated the search as satisfied, and moved on — leaving a tenant that, according to the code's own accounting, had the required value in place, but that in reality still had an unrestricted, user-editable row standing in for it. The requirement the code existed to enforce was unmet, and nothing about running it would ever tell you that, because "exists" and "correct" had been silently treated as the same question.

What makes this worth dwelling on is how reasonable the original check looked. Idempotency is usually framed as a promise not to repeat work — don't create a duplicate, don't double-charge, don't send the same notification twice. But the promise that actually matters in provisioning and reconciliation code isn't "don't do it again," it's "guarantee the end state." Those two promises overlap constantly, which is exactly why they get confused. A skip-if-exists check protects you from redoing work. It does nothing to protect you from a world where something with the right name already existed but doesn't have the right properties. The moment your system has been running long enough to accumulate history — and every system you actually care about eventually has — those two failure modes stop being equivalent, and code that only guards against the first one will pass every test built on a clean slate while quietly failing against the real data it will actually meet.

The tests told the same story from a different angle. There were two of them, and both started from an empty tenant with no pre-existing rows. They proved the happy path worked. They proved nothing about the case that mattered, because the case that mattered required imagining a tenant with history — an environment shaped by years of ordinary use rather than by the assumptions baked into the new feature. That's a common and specific gap: coverage of the greenfield case tells you the new code behaves correctly in a world with nothing else in it. It tells you nothing about whether it behaves correctly in the world it will actually be deployed into, which is full of things nobody designed against on purpose.

The fix wasn't complicated once someone asked the right question, and that's usually how these things go. Instead of treating a name match as the end of the search, the corrected logic reconciled a matching row against the actual invariant — checking whether it was already read-only and active, and if not, promoting it in place, while preserving its identity and ordering so nothing downstream that referenced it broke. A row that happened to share a name was no longer good enough on its own. It had to actually meet the standard the feature was supposed to guarantee, or the code would bring it into line.

The broader pattern here shows up anywhere reconciliation logic checks presence instead of properties. A feature-flag setup script that skips because a flag with that key already exists. A permissions script that treats "a role called admin exists" as proof the role has the access it's supposed to have. A security process that closes a finding because a ticket with a matching title already exists, without checking whether that ticket's resolution actually addressed the risk. In every version of this, "something is there" gets quietly substituted for "the thing that's there does what we need it to do," and the gap between those two claims is exactly where old, unexamined state gets to keep defeating a requirement nobody thought to re-check against it.

The practical habit worth taking from this is simple to state and easy to skip under deadline pressure: before you write a check that skips work because something with a matching name or key already exists, ask a second question separately — does that existing thing actually satisfy what I need it to, or have I only confirmed that a coincidence occurred? Writing the reconciliation branch instead of the skip branch costs a little more up front. It's also the entire difference between a provisioning script that is idempotent in name and one that actually guarantees the outcome it was written to produce.