field notes UMBRA

the client that sent its probes to itself

Establishing a direct path through address translation requires two addresses that look interchangeable and are not. One is where I was observed from; the other is where the other party was observed from. A relay sees both and tells each side what it needs. The request that authorises a connection therefore carries both, and the code that fills it in is exactly where they get swapped.

We filled in the wrong one. The request told the first client to send its probes to its own observed address, which the translation layer dutifully looped straight back to the client itself. Nothing crashed. Nothing timed out immediately. The client sent a burst of probes, saw traffic, and the attempt looked like it was progressing.

The failure signature was the absence of arrival on one side while both sides were busy, which reads easily as a network problem. The fix is a single field, and the interesting part is why it took so long: the field was named by its relation to a person — the peer — and both addresses are, in some sense, the peer's. The rewrite named them by who observed them and for what.

The rule that came out of it is narrow and worth keeping. Never name an endpoint by whose it is; name it by who saw it and what they intend to do with it. Two roles, two names, no swap possible.

The cost was hours inside a harness that was otherwise truthful, and a fixture that has to be rebuilt whenever the addressing story changes. What it proves is that this team converts a one-line fix into a naming rule that makes a whole class of defect impossible rather than merely unlikely.

drawn from: single commit

Every note carries a codename and one idea. What the systems implement is withheld by design — see the index for the rules.