A guard that repairs a shared config key to its own known-good value silently reverts every other owner's entry

The lesson

A component that repairs configuration it does not exclusively own has two separate obligations, and satisfying the first one hides the failure of the second. It must ensure its requirement is met, and it must leave every other owner's requirement intact. Code written for the first obligation reads as complete, because from inside that component there is nothing else to see.

The tell is a key that is multi-valued in the file and single-valued in the code. The reader half knows the truth — it splits the stored value on a delimiter before looking for what it wants. The writer half forgets it, because a repair is naturally expressed as "write the value I know is correct", and the value a component knows is its own. Read as a list, written as a scalar: the two halves disagree about the shape of the same key, in the same module, usually within one screen of each other.

What makes this durable rather than obvious is that the coverage test protects the wrong thing. Asking "is my entry present?" is satisfied by a file containing only my entry, which is exactly the state the repair just created. So the narrowing is invisible on the run that caused it and on every run after it. The guard reports healthy, forever, about a configuration it silently reduced.

The second-order effect is worse than the missing setting. A guard exists so that a person stops having to remember something. Once it demonstrably restores a subset, everything it protects inherits the reliability of the subset, and nobody knows which half they are holding — so the guard's real product, not having to check, is gone while the guard still reports success.

The failure that taught it

A configuration key on a workstation accepted a comma-separated list of entries. An automated guard, run at start-up, existed because that file had been lost once before and the loss was invisible: the only symptom was a protection quietly not being applied. The guard read the key, confirmed its own entry was present, and wrote the key back from a constant when it was missing. It was careful in every other respect — atomic write, fail-open on every path, no side effects on import, and a note printed only when a restart was still owed.

Later, a person widened that same key by hand to cover a second case, verified the new behaviour, and moved on. The guard's coverage test still passed, because the entry it looks for was still there. Nothing was wrong yet.

The defect is what the file was worth after the next reset. Running the guard against a scratch copy of the configuration directory with the file removed showed the repair writing the key back containing one entry — its own — with the hand-added entry gone, and printing that the setting "has been restored automatically". Read literally, that message is false in the way that matters: something was restored, not everything, and the difference is precisely the part a person added deliberately because the automated half did not know to.

The reproduction mattered more than the reading. Both functions are short and plainly written, and in review each one is correct. Only running the repair against an empty directory and printing the resulting file makes the narrowing visible as an artifact, and the success message makes it a finding rather than a curiosity.

How to apply it

When a component writes shared configuration, make the write a merge of the existing value rather than an assignment of a known one. If the code splits a key on a delimiter anywhere, it has already established the key is a list, and every write to that key must preserve the entries it did not put there.

Write the coverage test against the requirement, not the author. "Does the configuration satisfy every constraint anyone recorded?" and "is my constant present?" have the same answer only in the state the repair itself produces, which is why the second question is never a check on the first.

Test a repair by running it against a reset copy, not a correct one. A repair path only ever executes in the state where the file has been lost, so a review that reads it against a healthy file never sees what it produces. One scratch directory and one print of the resulting file is the whole test, and it is the only thing that surfaces this class before a user does.

Say what was restored, not that restoration happened. A message asserting more than the code did is what converts a recoverable gap into one nobody looks for again — the person who reads "restored automatically" has been told, accurately, that they can stop checking.

Where a component genuinely cannot know the other entries, that is a reason to report drift rather than repair it. Repairing is right when the fix is total; a partial repair delivered with a success message is worse than a report, because a report leaves the person's knowledge intact.