field notes
Short notes from real engineering work: one decision, one incident, one reversal at a time. Each one names the shape of the problem, the tension that made it hard, the decision, and what it cost. The internals stay out — the codename is the hint.
If you have five minutes rather than an afternoon: the three case studies condense this material to one problem, one decision and what the decision cost. The notes below are the record those studies cite — and the projects the codenames belong to are on the front page.
A handshake can complete while carrying nothing. Our relay had been built in stages, and one stage — the branch that fetches a peer's pre-published one-time handshake key and forwards it to the requester — was still a stub. The stub…
This is the note about the day we caught ourselves testing the wrong party. The claim under test was that two peers behind different kinds of address translation could find each other and hold a direct session. The test passed, repeatedly,…
Every roadmap wants to ship the interesting thing first. Ours could not, because the interesting thing was a cryptographic upgrade that invalidates every existing message shape at once: new key material, a new handshake, new frame variants.…
Two nodes that must talk to each other cannot both be upgraded at the same instant, and a peer-to-peer fabric has no maintenance window in which the whole network is quiet. Every wire format we ship has to be readable by parties still…
method
Not a changelog entry and not a repository summary. One decision, one incident, one reversal, or one hard-won invariant — the thing an engineer would tell you at a whiteboard.
Prefer records with dates and root causes? Those are on incidents. Live numbers are on stats.