Theo Zourzouvillys
I’m half English and half Greek, but not fully at home in either. I build software, sail a boat up the west coast every summer, and write about both — mostly about what it takes to make things that last.
Read the long version →
A collection of essays, engineering field notes, poems, logbook entries, and half-finished thinking — numbered, dated, and kept current.
- Field NotesZFN-N66
Short, numbered positions on how to build software well — and the open problems I haven't settled yet.
- BlueprintsZBP-N6
Normative implementation specifications, versioned and numbered to the requirement, written to be handed to a builder and built from.
- Essays—8
Longer prose that takes a side — on engineering, leadership, the machines we are now building with, and the water.
- Poetry—14
The interior register — what the technical writing has no room for.
- Logbook—1
Short entries from the boat: where we are, what the water did, what it taught.
Latest
- BlueprintZBP-5v1 · draftA runtime for partitioned stateful servicesA specification for services whose per-key state lives in memory on one instance at a time: a published partition map rather than a hash function, epoch-fenced ownership leases, checkpoint-journal-stream recovery, live handoff on rollout, and operator-governed placement.
- Field NoteZFN-65Journal the write, apply it in micro-batchesIf nothing the caller does next depends on a write, it does not belong in the request path: append it to a durable ordered journal and apply it in micro-batches. The bill is ordering. Sequence comes from the journal, never the clock, and never two paths to one row.
- EssayFifteen Years of Bullet PointsExtraction and generation look identical from the outside. Forty-six of my field notes share a publication date, and the difference between the two is the only thing worth arguing about.
- EssayNobody Reviews the AssemblyNobody reviews the assembly a compiler emits. Increasingly nobody reads the code a model writes either, so the specification becomes the thing you review.
- Field NoteZFN-64A config change is a deployConfig changes cause outages as often as code — and ride to production with none of code's safeguards. Anything that changes production behaviour is a deploy, whatever file it lives in: versioned, validated, canaried, staged, observable, and revertible in one motion.
- Field NoteZFN-63Decouple deploy from release — and give every flag a death dateA deploy puts code on servers; a release changes what users see. Coupled, a deploy is a bet you can only unwind by redeploying. Decoupled by flags, deploys become boring and releases progressive and instantly reversible. But a flag is a loan: owner, death date, or Knight Capital.
- Field NoteZFN-62Expand, migrate, contract: schema changes in three movesEvery deploy runs two code versions against one database — and rollback runs yesterday's code on today's schema. No schema change may break either. So every migration is three shippable moves: expand (additive), migrate (backfill, verify), contract (remove, later, deliberately).
- Field NoteZFN-61Propagate the deadlineEvery request has a deadline whether you set one or not — the caller's patience. Make it explicit at the edge, carry it as remaining budget on every hop, check it before expensive steps, and cancel downstream when it dies. Work past the deadline is the fuel of cascading collapse.
- Field NoteZFN-60Drain before you die: graceful shutdown is a protocolSIGTERM isn't an emergency — it's every deploy and scale-in. Shutdown is a protocol: stop attracting work, drain while the balancer catches up, hand back in-flight work, release leases, exit before SIGKILL. But graceful is only the optimisation — crash-safe is the requirement.
- Field NoteZFN-59Two clocks: monotonic for durations, wall time for recordsYou have two clocks. Wall time names moments — and it jumps, slews, and runs backwards. The monotonic clock measures elapsed time — and means nothing across machines or reboots. Every timeout, lease, and cross-machine ordering bug is one clock doing the other's job.
- Field NoteZFN-58Errors are part of the contractError paths are the half of your API clients depend on most, and usually the half nobody designed. Enumerate error codes in the schema like any other type: stable code, retryable-or-not, whose fault, structured params. Machines branch on codes — anyone parsing prose is broken.
- Field NoteZFN-57Deletion is a feature: design it on day oneA deleted_at column is not deletion. Real deletion is a workflow with an SLA: it must reach every replica, projection, index, cache, log, and backup — and you must prove it ran. Partition by owner, propagate tombstones on the event rails, crypto-shred what you can't rewrite.
- Field NoteZFN-56IDs are an interface: prefix the type, randomise the bodyAn ID is read by more than your database: humans in logs, machines at boundaries, adversaries probing. Serve all three — a type prefix so IDs self-describe and misuse fails at parse time, a random body so nothing leaks or enumerates, time-ordered only when the index needs it.
- Field NoteZFN-55On AWS, the account is the unit of isolationIAM inside one account is access control; the account boundary is isolation. Quotas, billing, credential scope, and blast radius are all account-shaped, and cross-account access fails closed. One workload per account, guardrailed by SCPs and RCPs — plumbing friction is the point.
- Field NoteZFN-54Quarantine freshly published dependenciesThe dangerous dependency isn't the old one with a CVE — it's the version published an hour ago by whoever phished the maintainer. Malicious releases are mostly caught within days. Pin everything, and refuse to install anything younger than 72 hours. Freshness is exposure.
- Field NoteZFN-53Make abuse cost money: attack the unit economics, not the identityAbuse at scale is a business with a P&L. Detection is an arms race you eventually lose, because the attacker gets unlimited free queries against your classifier. Instead find the metered input they can't substitute away from, and inflate it — per attempt, dialled by risk.
- EssayProof of Transfer: Billing Signup Abuse by the GigabyteResidential proxies killed IP reputation — but they're billed per gigabyte, and that's the crack. Make a client move a large block of unforgeable bytes and you've built a control that costs an honest user seconds and costs an abuser a real invoice, on every attempt. Here's how to enforce it, and everywhere it hurts.
- Field NoteZFN-52Conventional Commits: the log is an interface, not a diaryWrite every commit message as Conventional Commits — type, scope, breaking marker, prose body, reference footers. The log is the only documentation permanently welded to the change; structure is what makes it queryable and versions derivable. Enforce it in CI.
- Field NoteZFN-51Design the request envelope before the first endpointAuth, idempotency keys, trace IDs, vector clocks: context about a request, not part of it. Define an envelope alongside the payload in the schema on day one — transport-native, per-hop vs propagated, owned by generated SDKs and middleware. The retrofit is what costs you.
- Field NoteZFN-50See something, say something — you owe a report, not a repairTwo standing duties beyond your assigned work: see something, say something, and leave things better than you found it. But the duty is to report, not to repair — route it to the owner and move on. Security issues always go to security, including ones you fixed yourself.
- BlueprintZBP-4v1 · stableAuthentication for a multi-tenant SaaS productA complete specification for SaaS authentication: one global user, explicit per-org membership, server-authoritative sessions that die with membership, SSO enforcement that closes every side door, scoped invitations, org-owned API keys, and audited support access.
- BlueprintZBP-3v1 · stableTenant isolation in a multi-tenant systemA complete specification for keeping tenants apart: tenant context established once from authenticated material, tenant id as partition key, enforcement in a layer application code cannot bypass, ownership verified at every boundary, and continuous leak detection.
- BlueprintZBP-2v1 · stableA Security Token Service for workload identityA complete specification for a workload STS: platform attestation as the only bootstrap, RFC 8693 token exchange, downscope-only policy, short-lived at+jwt tokens bound to a holder key, KMS signing keys with overlapping rotation, and local verification.
- BlueprintZBP-1v1 · stableDPoP-bound requests across an API surfaceA complete specification for sender-constrained HTTP requests using DPoP (RFC 9449): key handling, proof construction, token binding via cnf.jkt, the resource-server validation algorithm in order, nonces, replay defence, and executable test vectors.
- BlueprintZBP-0v1 · stableBlueprintsWhat Blueprints are: versioned, normative implementation specifications for cross-cutting concerns, written to be pulled into a build by URL and implemented directly — by a person or by a language model — with numbered requirements you can grep for.
Say hi
I work remotely from the boat in Alaska all summer, which is about as off-grid as it gets, and I really value the chance to talk to people. You don’t need a pitch or a project — just real conversation.
Schedule a call