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 fork is usually treated as a failure: a community that could not agree, a codebase now living twice, a project that split and lost. This record treats it as an operation with a name and a place in the design. Anyone may begin an…
A stack this tall invites a bespoke mechanism at each level. The record refuses that too, and the refusal is visible in the words: one vocabulary is applied across the whole cluster in a single round, and one pattern repeats at every level…
The catalog at the root of this design had an easy option: name a unit of account and be done. The record declines. The platform is described as currency-agnostic — payment is declared by contract, so one catalog carries many payment…
The first economics in this cluster charged for staying. An identity that remained present carried a continuing price for remaining present, and one that fell quiet was eventually wound down — existence as a subscription. The record…
A catalog cannot prove itself. Whatever sits at the root of authority has to be named, and the honest options are to name something external — which this design cannot supply — or to name itself, which is a statement about bootstrapping…
The most useful single change in this cluster is a documentation edit. A document describing a layered infrastructure design — entry points, hubs, data plane, topology, control — had been written as the architecture of the network. The…
The failure that drove this decision is worth stating in its own terms. A record points at another record by its content identity, and identity looks like proof. It is not. Anyone can build a registry of their own and assert that a given…
Moving live state between two foundations is the part of distributed design that usually happens once, badly, at an unsociable hour. This record treats it as a standing role instead of an incident.
This cluster contains a clean reversal. An earlier model had worlds evolving by version: a world produces a new version, consumers migrate across, the old one eventually falls away. The decision that replaced it says the opposite — worlds…
The most thorough early design for keeping history was also the one that could not be paid for. The pruning record says it plainly: an archival scheme where old state is kept cold and revived on demand requires someone to maintain that…
The recurring bug here is that an object is told who owns it. A field on the account says "owner: that identity there." The owner says nothing, so nothing cross-checks the claim. Half a binding looks exactly like a binding, which is why so…
Delegation is where most systems quietly become custodial. You grant someone authority to act for you, and the record of that grant ends up in whatever store the delegate controls. You find out how it was used afterwards, if at all.
Everybody has decision templates: how a group picks among options, who may act for whom, how a bridge between two groups gets authorised. Those templates usually live in prose, and prose drifts. Two implementations of "the same" rule…
Most storage designs assume that whatever is written stays. This record assumes the opposite: keeping bytes is a recurring obligation, and an obligation with no named payer is a bug, not a policy.
A single act at the top of a layered system — one registration, one write, one listing that stays listed — touches a dozen components that each did some work. The easy answer is a central accountant that bills the caller once. That answer…
The easy way to admit a participant is one gate and one credential: pay the price, get a key. The design record refuses that, because a single gate forces a choice between two bad options — cheap enough that anyone can flood in, or…
The earliest entry in this stretch of the record carries the previous day's date, and it does one thing: it reduces the working tree to sources and excludes generated output by rule. Before any question had been opened, the operation…
One commit in this stretch does exactly one thing: it excludes the agents' own session state from the repository. Not a research artifact and not a result, but the private working context each participant accumulates while operating. The…
Between the lane integrations, this record contains a recurring entry type that names no lane at all: small edits in the shared working area, labelled only as such, appearing dozens of times across the stretch and always between integration…
The periodic summaries in this record are numbered. The numbers do not run consecutively. Inside a working stretch where the neighbouring numbers are all present, several are simply missing, and nothing in the record explains the absence or…
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.