contract changes arrive as reviewed changes
A written contract and a shipped implementation drift apart in one direction: the implementation wins and the document becomes archaeology. Two practices in this period worked against that.
field notes
Writing
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.
All field notes
all
ABACUS 60
FLINT 12
KEEL 24
LARDER 24
LATTICE 36
MERIDIAN 24
MISE 24
SCRIBE 12
TROUPE 12
UMBRA 24
filter by theme · 244 total
the exposed default, made impossible
A development database was published on every network interface rather than the loopback one. It was found by a scanner, brute-forced, and left carrying a back door. Nobody had decided to expose it. The default mapping did that, and every…
events that cannot precede their commit
A live board for staff is a latency problem that is really a truth problem. The obvious implementation is an in-process broadcast: when state changes, publish. It is fast, it is simple, and it makes it possible for a board to display a…
verify the artifact, not the source
Verification kept producing a specific kind of wrong answer. The tree was correct, the local build was correct, the browser checks were green, and the thing users were actually loading was older than all of it. Two mechanisms were…
the numbers the product will not invent
Sample content has a way of surviving into production. A review section carried a demonstration fallback: a few plausible reviews and an average just under five stars, rendered when the real fetch failed. It existed to make review builds…
variation by configuration, never by branch
Per-customer difference is where products fork. One business wants the offers in the sidebar, another wants them as a strip; one wants a denser grid. The fast answer is a branch, then a build flag, then a separate deployment, and then…
registration is not deployment
Bringing a new business onto the platform looks like one operation and is really two. There is the record of the business: its identity, its routing key, its configuration, and a starter menu attributed to it. And there is the deployment of…
generated desired state, validated but not applied
Every name the platform answers on should get a real certificate. Names that resolve to the origin but match no route fall through to a default, self-signed one — a small leak, a real annoyance, and the kind of thing that gets fixed by…
emptiness is not correctness
Two defects in the same period, and they share a shape. Both returned success. Neither raised an error. Both produced a surface that simply had nothing on it.
the constraint that was never created
A design said orders keep their reference to the area they were priced against. The code agreed. The store did not, and nobody found out for several changes.
isolation belongs to the storage boundary
Serving many independent businesses from one store gives you a choice about where isolation lives. It can live in every query, politely: each read filters for the business it is serving. That works exactly as long as every author, on every…
the ledger is the contract
On a platform shared by many independent businesses, the data shape is not a private implementation detail. Every surface, every workstream and every future feature reads it. So a schema change is a contract change, and the hard part is not…
the value judgments get a record of their own
From its first round, this cluster carries a place for the ethical and philosophical claims the design rests on, written in prose and revised alongside the technical record. It is not a rulebook for participants and not a statement of…
the founder, filed as a participant
There is a dedicated artifact in this cluster for the founding identity, built with the same participant model as anyone else: a self-describing manifest, owned artifacts, and agreements that express what it may do.
behaviour as a lens over the record
The record describes participants as actors. That framing is familiar and it arrives with baggage: an actor needs mutable state and an inbox, which this same design forbids storing, because its records are immutable. One half of the design…
the successor publishes what it drops
Documentation for a late prototype in this cluster opens with a map of what it replaces. It lists what came forward from earlier rounds, what is new, and what has been set aside for a later one, and it names its predecessors explicitly…
compatibility on its own axis
Once there are many independent lineages, the question of whether two of them are compatible stops being answerable by comparison. They will never share a label, so there is nothing obvious to compare. The record answers by giving…
a tie is a contract, not a feature
The obvious build is a relationship service: a table of who is bound to whom, a query surface, a component that can answer membership questions on behalf of everything else. The record refuses it. Ties between identities are agreements made…
an archive, not a rewrite
Work that stops being true is usually deleted, or quietly left where it falls. This record does neither. Deprecated material was imported into a place of its own with its history attached, and later the pieces nested inside it were…
the ledger that stopped saying accepted
One entry in this cluster is a subtraction. The status marks were removed from the decision headers and replaced with timestamps. A record of decisions had been labelling each one with where it stood; afterwards it records only what was…
method
What a field note is
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.
shape
What made the problem genuinely hard, before any solution appeared.
tension
The two things that could not both be true — stated precisely, because
that is the part that transfers.
decision
What was chosen, and what it cost. Cost is the
credibility; a decision with no cost attached has not been described.
ceiling
A codename, a theme, and a class of problem — never a hostname, a
parameter, a version or a vendor. Under the disclosure rules the hint
is the category, not the instance.
Prefer records with dates and root causes? Those are on incidents. Live numbers are on stats.