DEV Community: Anton Brilliantov

Requirements Decide the Topology

Anton Brilliantov — Thu, 24 Sep 2026 16:26:48 +0000

No line in the requirements, nothing to argue about - the design argument is not a matter of taste.

👋 Hi, I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series has been about the order the work happens in: a wish becomes requirements, requirements become a contract, the contract becomes tasks and specs. This is the last part of it, and it goes back to the first link - because the requirement is where the shape of the system got decided, whether or not anybody wrote that line down. Running notes live on my GitHub: github.com/brilliant-almazov.

This is how I do it right now, with the price attached - maybe you already do it better, maybe you see it differently.

Primer, in one paragraph

A non-functional requirement says nothing about what the system does and everything about the conditions it does it under: load, latency, the ratio of reads to writes, how long data has to be kept, whether tenants share storage, what has to stay compatible with what. The systems here are Go services being carved out of a PHP monolith. Each one ships as a single image, declares the processes it runs in a manifest, and stores its data in PostgreSQL. Below, a layout means the package layout of a service: which directories exist and what is allowed to live in them.

The thesis

The arguments that eat the most calendar time in a design discussion - microservice or module, CQRS or not, a bus or a direct call - are not settled by taste, seniority or precedent. They are settled by a line in the non-functional requirements.

The useful half of that claim is the contrapositive: if there is no such line, there is nothing to argue about, because the requirement has not been gathered yet. A design discussion that cannot point at the line it is answering is not a design discussion. It is two people comparing preferences with a diagram between them.

The case: one line, all the way down to a directory name

The line: reads and writes behave differently here - different volumes, different shapes, different failure modes.

That is a sentence about conditions, not about features. Here is what it turns into, with nothing in between.

Exactly two layers touch the database. repository reads. manager writes. There is no third one - no store, no writer, no dao, no service. A manager that needs to read something calls a repository instead of growing its own SQL.

The layout runs from the component type, with the domain as a nested package - not the other way round:

  internal/
    repository/
      entity/          reads only
      order/
    manager/
      entity/          writes only
      order/
    handler/
      grpc/
        entity/

What it looks like in numbers, measured on 2026-08-16: 2 733 .go files excluding generated code, 252 packages, average file size 39 lines. That average is the tell. A layout that splits by component type first produces many small files by construction; you do not arrive at it by asking people to write shorter files.

What it cost. Two packages where most codebases have one thing called a service, and a manager that wants to read has to go through a repository instead of writing three lines of SQL where it stands. That is a real tax, paid on every feature, and it buys exactly one thing: the read path and the write path can be changed, measured and reasoned about separately - which is what the requirement line asked for.

Two neighbours of the same order, from the same set of requirements:

Heavy background work sits next to synchronous handles. → two binaries out of one image, server and worker, declared in the service manifest.
This data has to be kept, and old states have to be reconstructable. → monthly audit partitions with retention done by dropping a partition, HASH partitioning by owner, and two time axes instead of UPDATE. 66 migration files, 1 990 lines of migrations as of the same date.

And the boundary, said plainly: this is a breakdown of a structure and its price, not a report from a running installation. There is no production here with thousands of databases per tenant, and this service does not operate a shard map of its own.

How this is usually done

Three patterns, none of them stupid, all of them the same failure:

Non-functional requirements as a trailing section. The vocabulary is not the problem - ISO/IEC 25010 and ISO/IEC/IEEE 29148 provide perfectly good catalogues of quality characteristics. The placement is: a section after the functional part, written once for the approval meeting, never opened again during design.
The style is chosen by popularity and by what the team has done before. Which is a real input - Fowler's microservice trade-offs piece is largely about team-shaped costs - but it answers "what can we operate", not "what does this system need".
"We will figure it out when we hit it." Sometimes correct. It becomes a problem only when the thing hit is a data-model decision, because those are the ones that do not move afterwards.

What the three have in common is that they leave the design question with no cited input. A question with no cited input gets answered by whoever is most confident in the room.

The five lines

Requirement line	What follows from it
reads and writes carry different load and have different shapes	reads and writes are separate layers, and it is visible in the package layout
heavy background work sits next to synchronous handles	separate daemons of one service, declared in the manifest
any asynchronous processing	a queue, not a goroutine scanning a table
tenant isolation and data volume	a database per tenant, application-level sharding, or partitioning
history and corrections have to be reconstructable	a bitemporal model instead of `UPDATE`

The rest of this is one section per row.

1. Reads and writes are two layers

Covered above. The one thing worth repeating is the negative half: the rule is not "prefer small packages", it is that four common names do not exist. store, writer, dao and service all let read and write logic share an object, which is precisely what the requirement line ruled out. Banning the names is the cheap way to enforce the split, because a name is checkable and an intention is not.

This is not full CQRS. There is one model and one database; what is split is the code path, not the storage. The original framing is worth reading mostly for how narrow the useful version of it is.

2. Separate daemons, one image

Two binaries out of one image: server speaks gRPC; worker relays outgoing events, runs background calculations and drops expired audit partitions. Both are declared in the service manifest - which means the set of daemons is a stated fact about the service, not a consequence of somebody having added a goroutine to main.

The manifest matters more than the count. A daemon that is declared has a name, a place in the deployment and an owner; a background loop started inside a process has none of the three, and shows up in an incident as unexplained work.

Who gets to add a third one is a separate question, and the answer is the service owner. That is deliberately not a technical decision.

3. A queue, not a goroutine

Any asynchronous processing goes through a queue. Not "usually", not "unless it is small": a goroutine that scans a table on a timer and does the work itself is not a form of asynchronous processing. It is a background job pretending to be one.

  requirement:  any asynchronous processing
  ───────────────────────────────────────────────────────────────
  accepted      producer ──▶ queue ──▶ consumer
                back pressure · retry policy · visible depth ·
                the work survives a restart

  not a form    goroutine ──▶ SELECT ... WHERE pending ──▶ do it
                none of the four, and no signal that none of the
                four are there

The difference is not style. A queue gives back pressure, a retry policy, a visible depth and a place for the work to survive a restart; an in-process scanner gives none of the four, and gives no signal that it gives none of the four. Stating it as a rule rather than a preference matters because the scanner is always the cheaper thing to write on the day you write it.

4. One requirement, three different answers

Tenant isolation and data volume is the one line that does not resolve to a single structure. It has three answers, and they are not interchangeable:

A database per tenant. The strongest isolation, and the operational cost lands on migrations and connection pools.
Application-level sharding. Logical shards, a map from logical shard to physical address, and the shard bits carried inside the identifier itself, so the routing decision travels with the row.
Partitioning at the database level. HASH by owner for the large tables, monthly partitions for the audit trail, and retention performed by dropping a partition rather than deleting rows.

Partitions are not shards. Partitions live inside one database and are transparent to the planner - the query does not know they are there. Shards are different databases and are not transparent: something in the application has to decide which one to open. The two get discussed as though they were points on one scale, and they are not on the same scale at all. (The PostgreSQL manual is unusually clear about which problems partitioning does and does not solve.)

The honest boundary again, because this is the row where it matters most: partitioning is what actually runs here. The database-per-tenant answer and the sharding answer are described as structures and prices, not as installations I operate.

5. Two time axes

We have to be able to show what we thought at the time is a requirement line, and it is the only thing that justifies the structure it forces.

Two time axes: the valid axis, when a fact was true in the world, and the system axis, when the system came to believe it. The current state is a slice through those axes, not a separate table. There is no destructive UPDATE in the domain tables and no physical DELETE; a correction is a new row that closes the previous one on the system axis.

The price is real and it is paid on every read: nothing is a plain SELECT any more, everything carries a slice condition. It is worth paying because of that one requirement line, and for no other reason. Without "show me what we thought at the time", the second axis is a tax with no payer - which is the standard reason to keep the bitemporal machinery out of a system that never asked for it.

Why it has to come from the requirement

For each of the five, ask what changes if the requirement line does not exist.

The structure does not change. The layers are still there, the queue is still there, the second time axis is still there. What disappears is the reason - and with the reason gone, the first person to question the structure is arguing about preferences, and so is everyone answering them. Six months later the split gets undone by somebody with an equally good taste-level argument for undoing it.

If this line is missing	What is still true	What stops being true
reads and writes differ	the two layers still exist	why a manager may not hold SQL
heavy background work	`worker` still runs	why it is not a goroutine in `server`
any asynchronous processing	the queue still delivers	why the scanner was refused
tenant isolation and volume	the partitions still drop	why the owner is the partition key
history and corrections	the second axis still fills	why every read carries a slice condition

Every row of that table is an argument somebody will have. With the line, the argument takes a minute and ends in the requirements document. Without it, the argument is about experience, and experience is not a thing two people can check against each other.

That is the whole function of the requirement line. It is not documentation of a decision. It is the place where the decision was made, so that later arguments have somewhere to land other than seniority.

What it costs

A requirement stated as a number is a commitment. Somebody will measure against it, and the measurement can come back negative. A vague requirement never fails an audit, which is exactly why vague requirements are so popular.
A structure derived from a requirement is expensive to change when the requirement changes. That is the same cost curve as Part 1 of this series: the further down the chain a change lands, the more artefacts have to agree with it.
Some of these answers are structure-and-price, not experience. Database-per-tenant and application-level sharding are in that category here. Presenting them as operational track record would be a lie, and would make the parts I do run less believable.

When not to do this

The requirement is unknown and cannot be gathered. Then the honest activity is investigation, not design. A topology derived from a guess is a structure with a fake justification, which is worse than one with none.
The load is knowably small. Every one of the five costs something. At small scale four of them are pure overhead, and the fifth is usually a lookup table.
A prototype that lives until the first measurement. Its job is to produce the requirement line, not to obey one.

The multiplier line

An automated executor is very good at building whatever structure it is handed, and completely indifferent to whether that structure has a reason behind it. Hand it "split reads and writes" and it produces the layers; hand it "reads and writes carry different load, which is why they are split" and it produces the same layers - the code is identical either way. The difference shows up months later, in the first argument about whether to keep them, and by then the executor is not in the room. Speed of production multiplies the definitions it was given; the requirement line is where those definitions live.

From requirement to contract — Part 7, and the last part of this block. The next block starts from the other end: a catalogue of services, and the rule that a service exists when it is declared - not when its code happens to run.

If you do this better, tell me where your non-functional requirements live and who opens them during a design argument. If you have been through this, which structure in your system turned out to have no requirement behind it? If you see it differently, say where deriving the topology from stated requirements cost you more than deciding it by experience. How is it solved on your side, and what broke there?

TDD for Requirements

Anton Brilliantov — Thu, 24 Sep 2026 01:59:47 +0000

Write the checkable condition first - the requirement, the contract and the spec all obey it.

👋 Hi, I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series has been about the order the work happens in: a wish becomes requirements, requirements become a contract, the contract becomes tasks and specs. This part is the shortest one in it, because it is one move applied four times. Running notes live on my GitHub: github.com/brilliant-almazov.

This is how I do it right now, with the price attached - maybe you already do it better, maybe you see it differently.

Primer, in one paragraph

Each step of that road ends in a gate: one thing that is accepted, and one artefact that proves it - a number, a run, a file. A spec is the self-contained brief one executor runs end to end; an executor is whoever performs it, usually an automated one here, and nothing below changes if it is a person. This part is about where the artefact in that third column comes from, because a gate is only as good as the condition it was given.

The thesis

Write the checkable condition first. Then write the thing that satisfies it.

That is the same move as writing a test before the code, lifted one level up - out of the code and onto the requirement, the contract and the spec. Nothing about it is new at the code level. What changed for me is that I stopped filing it under testing and started treating it as the order in which things get written down at all.

The reason is not purity. A condition written first is the only thing a gate can lean on. Written afterwards, it is a description of whatever was built, and it accepts whatever was built.

The case: a condition that holds a direction and not a level

The honest example first, because it shows the limit of the idea rather than an advertisement for it.

What it was. "Coverage must not fall" lived as an intention. Everyone agreed with it and nobody could check it, which is the defining property of an intention: it has no output to read.

What was done. The intention was turned into a ratchet. The threshold is recorded in the repository, it can only move up, and an attempt to write a lower number in fails the pull request. That is a condition: it produces a verdict without anyone forming a view.

  the rule        the recorded threshold may only go up
  the check       a pull request that writes a lower number fails
  the reading     green  →  nobody lowered the bar
                  red    →  somebody tried, on the record

What is honest about it. The threshold currently stands at 0, while actual line coverage is 86.7%. The ratchet is wired and it works, but the bar has never been raised to where the tree already stands. So what the condition holds today is the direction - nobody can quietly lower the recorded number - and not the level: coverage could drift well below 86.7% and the check would stay green, because it is being compared to zero.

That is unfinished work, not an achievement, and I would rather write it down that way than round it up into a story about discipline. The move was right and the follow-through has not happened yet.

The same move, in time

The second instance went the other way round, which is what it is supposed to look like.

Part 1 of this series described an audit that found 44 copies of four ways to read rows from a database. The part that belongs here is not the refactor - it is that the closing condition was written while copies were still being moved, not after the last one:

  for rows.Next()   ·   rows.Err()   ·   rows.Close()   ·   QueryRow(
  ────────────────────────────────────────────────────────────────────
  appear in the tree in exactly one package
  held by a test that fails the build the moment a second copy appears

Because that sentence existed early, every iteration in the set had something to be accepted against, and the last iteration was not a judgement call about whether the job was finished. The test answered.

On performance, the condition is a number taken beforehand

The third instance is the one that is easiest to skip, because it costs work before the work.

A performance condition is a baseline measurement, taken on the old behaviour and frozen as a constant in the test. The new run is compared against that constant, and the comparison is printed. "It got better" without "what it was" is not proof - it is a recollection, and recollections about performance are usually about the last run rather than the first.

Taking that measurement means running the old code on purpose, after you already know how you want to change it. It is the least satisfying half-hour in the task, and it is the entire reason the result is arguable at all.

How this is normally done

None of this is new craft, and I am not claiming otherwise.

The test comes before the code - test-driven development has been the standard statement of the move for two decades.
Acceptance criteria are written on the story, before implementation, often in a given / when / then shape so the condition reads the same to both sides.
Non-functional requirements get their own section of the requirements document - that is what ISO/IEC/IEEE 29148 formalises.

All three work. What I keep from them is the ordering rule and nothing else: no template, no separate document, no role that owns it.

The four levels

The move is the same each time; the form of the condition is different, and that is the part worth being concrete about.

level	the form the condition takes	what it is without it
requirement	one command, or one number	an adjective two people read differently
contract	the list of cases, before any field is named	a message shape chosen by whoever typed first
spec	an acceptance command with nothing left to substitute	a transition settled by discussion
performance	a baseline taken on the old behaviour	a comparison against a memory

On a requirement

The condition is something that can be run as one command or read as one number. "Works fast" is not a criterion: nobody can say when it is met, so acceptance falls back to whoever is more insistent that day. "Holds N requests per second below M latency" is a criterion: one command runs it, or one number answers it, and both sides read the result the same way.

I am deliberately leaving N and M as letters. Those numbers belong to the system being specified, not to an article about the order the work is written in.

On a contract

The condition is the set of cases the contract has to be able to express, written down before a single field is named: success, refusal, conflict, an empty response, a page boundary. Five rows, minutes to write, and they settle most of the message shape - the empty case decides that an empty list is an answer rather than an error, the page-boundary case decides that the response carries a cursor, the refusal case decides that codes are an enum rather than prose in a message string.

On a spec

The condition is the acceptance command, written into the text of the spec with no substitutions left in it - no angle brackets, no "fill in the package here". And it runs against its own package only, not the whole tree, because an iteration accepted by a full run is being accepted by everybody else's work as well.

There is a second reading of the same rule, and it is the more useful one: an iteration that gets rewritten after it was accepted means the criterion was not checkable. The executor is not the finding there. The criterion is.

On performance

The condition is the baseline described above: taken on the old behaviour, frozen as a constant, compared against and printed.

One requirement, all the way down

Neutral domain, so the shape is the only thing visible.

The wish: the entity list should come back quickly. Not a requirement yet - there is nothing in it to check.

  requirement   the list returns within M for a page of N entities
                on an account of the size we actually have

  contract      cases before fields:
                  success · empty response · page boundary

  spec          go test ./internal/repository/entity/... -race -count=1

  performance   baseline taken on the current query, frozen in the test,
                the new query compared against it

Four conditions, none of which needed the implementation to exist. And each one decided something about what came next: the case list decided that the response carries a cursor, the acceptance command decided where the boundary of the iteration is, the baseline decided which number the change would be about.

Why the order matters

Because a condition written first is not a check on the work - it is a description of the work's shape, produced before the shape exists and therefore able to choose it.

The case list decides which fields the contract needs. The acceptance command decides where one iteration ends and the next begins. The baseline decides which number the change is even about. Write any of them afterwards and they still read the same on the page, but each one now agrees with whatever was built, because it was written by somebody looking at it.

And then there is the gate. A transition needs an artefact rather than an opinion, and a condition written first is how one gets manufactured: it exists before there is anything to be defensive about.

What it costs

We do not have a separate artefact for this. There is no requirements test suite, no file where the conditions live as their own set. Checkability is expressed by the acceptance criterion in the spec and by forbidding tests in the tree - which is thinner than it sounds when I say "condition first", and I would rather name that than imply a system I do not have.
Writing the condition before the solution is harder than it looks. It is genuinely easy to sit for twenty minutes on one sentence, and it is not always twenty minutes well spent.
The baseline is work before the work. Running the old behaviour on purpose feels like a detour every single time.
A condition can be technically true and hold nothing. The ratchet at 0 is the example in this very article. A green check is not proof that the bar is where you think it is.

When not to do this

Research, where the point is that nobody yet knows what should be built. There is nothing to write a condition about, and forcing one produces a confident sentence about a system nobody understands.
"Make it nicer". Where no criterion exists, inventing one produces a criterion for the wrong thing, and then the work optimises for it.
A one-off change where the condition is longer than the fix. Two lines of code do not need a paragraph of acceptance ceremony, and I skip it.

The multiplier

A criterion that runs as one command is the only form of acceptance that reads identically to a person and to an automated executor. Everything else - a definition of done written in adjectives, a reviewer's sense that this looks about right, a claim that the iteration is finished - needs somebody to look at it with their own eyes, and that somebody does not scale and does not stay consistent across a set of twenty iterations. Speed of execution makes the condition matter more, not less: whatever the condition failed to say gets built twenty times, quickly.

From requirement to contract — Part 6. Next: non-functional requirements decide the shape of the system - which layer takes the work, whether there is a queue in the middle, whether reads and writes are separated at all.

If you do this better, tell me what your conditions look like and where they live. If you have been through this, what did your version of the threshold at zero turn out to be - the check that was green and held nothing? If you see it differently, say where writing the condition first cost you more than it bought. How is it solved on your side, and what broke there?

Accountability Stays Human

Anton Brilliantov — Wed, 23 Sep 2026 12:18:31 +0000

The executor writes most of the code; the check has to come from outside it.

👋 Hi, I'm Anton — a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series is about the order the work happens in: a wish becomes requirements, requirements become a contract, the contract becomes tasks and specs, and the specs get run. This part is about the thing that does not travel down that road with the work — who is answerable for the result. Running notes live on my GitHub: github.com/brilliant-almazov.

This is how I do it right now, with the price attached — maybe you already do it better, maybe you see it differently.

Primer, in one paragraph

The cast is small. A spec is a self-contained brief for one unit of work: it names the files, states the change and states what makes it accepted. An executor performs one spec end to end; here that is usually an automated one, and nothing below changes if it is a person. A lead prepares the facts, hands the specs out and accepts the results — that is me. The rules an executor is expected to follow live in an instruction file it reads before it starts. That file is the setting for everything that follows.

The rule everybody had

There was a rule, and it was not a vague one. In a test, the context comes from the test runtime; the empty placeholder context is forbidden. It was written down, in the instruction file, in the place rules are kept, and every executor read it before writing a line.

Tests kept arriving with the empty one.

Not once, and not from one executor. Across weeks, in whatever direction the work went, in files written by different runs on different days. The rule existed. It had been read. Nothing enforced it, so it did not hold.

It started holding on the day writing such a file began to fail.

That is the whole article in three lines. The rest of it is the price:

  reminder   a sentence in the conversation      lives for one session
  rule       a line in the instruction file      works while it is read
  check      a run that fails                    works whether or not anyone remembers

What the rule was worth unenforced: 421 calls in 184 files

Eventually I counted instead of assuming. In one service tree, with the rule in force and visible: 421 calls to the empty context, across 184 test files.

The number is not the interesting part. What those tests were worth is.

A test built on the empty context has two properties, and both of them are quiet:

It does not cancel along with itself. The test's own lifetime is not attached to anything the test runtime controls, so when the thing under test hangs, the test hangs with it until the package timeout — instead of failing at the moment the deadline passes.
It checks nothing at all about context propagation. If the production code drops the context it was handed and quietly substitutes its own, the suite stays green. The exact defect the rule existed to prevent is the one defect that class of test cannot see.

So the suite was green, and green meant considerably less than everyone reading it assumed.

What the rule became. The form was made explicit rather than implied: the context in a test comes from the test runtime; a port stub does not discard the context it is handed but keeps it in a field and hands it back to the test; and every transport, repository, manager and consumer carries a cancellation test — cancel the context, assert the failure, assert nothing was written. Then the part that actually changed the outcome: writing a test file that uses the empty context fails. Not a warning in a linter report somebody reads on Friday. The write does not complete.

The repair took a set of small mechanical iterations, one file at a time, and none of it was interesting. That is the shape of this kind of debt: the discovery is one command, the fix is a queue of boring edits, and the only thing that stops the queue from re-forming next month is the thing that fires on the write.

Two more findings from the same period, same class, one line each:

A cache-invalidation consumer was written and registered in no daemon at all. The package compiles. Its unit tests are green. In production, invalidation does not run — not slowly, not intermittently. It does not run.
A decode failure is returned as an ordinary error. The driver reads a returned error as "hand it back", and the subscription declares no redelivery limit, no backoff and no dead-letter queue. One undecodable message retries forever.

Three findings, one shape. Every one of them is caught by a check that runs outside the executor's own account of what it did. Not one of them is caught by a green build — because in all three cases the build was green.

How this is normally handled

Nothing below is a criticism. It is the baseline, and each line of it is reasonable where it came from.

Practice	The common shape	Where it stops
Review	Reading the change is the main way a machine-written error is caught	A reviewer's attention is finite and uneven, and it degrades exactly when volume rises
Instruction file	Conventions written into a file the executor reads — the `AGENTS.md` convention and its equivalents	It works while it is read, and reading it is not verifiable from outside
Green tests	The suite passed, so the change is fine	A test can be green because it asserts nothing — see coverage as a signal

All three are true, and none of them is enforcement. Each leaves a gap that is filled by somebody remembering — a reviewer remembering to look for the thing, an executor remembering the line it read, a reader remembering that green is a weaker signal than it looks. Remembering is exactly the resource that does not survive volume.

The share of the code is high; the accountability does not divide

Most of the code in this work is produced by an executor. I am not going to attach a percentage to that — I do not measure it, and putting an invented number next to a real one is how the real one stops being believed.

What I will state flatly is the part that does not scale with the share:

Setup, checking and acceptance stay with a person. Whatever fraction of the code the executor writes, none of the answerability moves with it.

This is not an ethical position and I would rather not dress it up as one. It is about who answers to whoever is paying. Nobody on the other side of that conversation has any interest in which part of the output was typed by whom. There is one name attached to the result, and it is a human one — so the checking has to sit in the same place the answering does.

The reason is technical, not ideological

The practical reason is narrower and more useful than the moral one: an executor fails in a predictable, small set of ways.

Not randomly, and not creatively. It reproduces a form it saw nearby. It satisfies the letter of an acceptance criterion that was written loosely. It writes the code and does not wire it up. It answers "done" because the last command it ran exited zero.

A predictable failure has exactly one reliable answer, and trust is not it. When a mistake recurs, the response is not a firmer reminder — it is a check that makes the mistake impossible to commit. Everything else in this article follows from that one sentence.

The ladder: reminder → rule → check

I named this ladder in passing in the previous part. Here is the version with each rung honestly priced.

Reminder. A sentence in a conversation: "don't do that". It works for the duration of that conversation and is gone at the end of it. The next executor never saw it. That is not a weakness of the executor — it is what a reminder is.

Rule. A line in the instruction file. Better: it survives the session, it is quotable, it is the same for everyone. And it is conditional on being read, and on being read the same way twice. The 421 calls are what that condition costs once the file is long and the rule is one line in the middle of it.

Check. A linter rule, a forbidding test, a structure test, a blocking hook on the tool that writes the file. It does not care whether anybody remembers it exists. It fires at the moment of the mistake, on the mistake, with the fix in the message.

The rungs are not alternatives. A rule that keeps being broken is a check that has not been written yet.

Five rules that became checks

Concrete, from the current setup. Each row was a rule first, was broken, and became a check afterwards.

The rule it used to be	The check it is now
read rows through the one shared core, not by hand	a forbidding test: `for rows.Next()` appears in exactly one package
keep the environment catalog and the metrics snapshot true	a drift check in the build: regenerate, compare, fail on a difference
do not let test coverage slide	a ratchet on the threshold — it can rise, it cannot be lowered
do not write a spec containing a phrase that makes it unrunnable	the file write is blocked when that phrasing appears in the text
take the context in a test from the test runtime	the file write is blocked when the empty context appears in a test

Read the right-hand column as a group. None of those five is clever. Every one of them is mechanical, cheap to run, and — this is the point — indifferent to who is at the keyboard and how the day is going. That indifference is the entire property being bought.

A gate leans on an artefact, not on a claim

From which one requirement on the process follows, short enough to fit on a line:

Every gate leans on an artefact — a number, a run, a file — and never on the executor's statement that the thing is done.

Drawn as the two things that arrive at a transition, it is not a subtle design:

   "the iteration is finished"  ──▶ ┃  closed          a claim is not an input
                                    ┃
   number · test run · file    ──────────────▶        the artefact is the input

"It's done" is a claim. It carries no information about whether it is true, and it costs nothing to produce — including when I am the one producing it. A number that was measured, a command that was run with its output read, a file that exists at a named path: those can be wrong too, but they can be wrong checkably, which is a different category of thing.

This is not scepticism about the executor. It is the same rule turned on me: when I say a spec is ready, that is a claim; when the spec contains no open question, that is a fact somebody else can verify without asking me.

What this costs

The bill is real, and it arrives in four parts.

Every check is code. It has to be written, and then maintained indefinitely, against a tree that keeps moving. The five above were not free and they are not finished.
A check catches form, never intent. for rows.Next() in exactly one package is a fact about shape. It says nothing about whether the query behind it is the right query. No amount of this saves a wrong architecture; it only stops a known-wrong form from spreading.
A false positive is expensive twice. It costs the executor's run, and it costs the credibility of the check — one that cries wolf gets routed around, and then it is worse than nothing.
One of these is honestly unfinished. The coverage ratchet exists and works in the direction it was built for: the threshold can only ever rise. But the threshold is currently set to 0, while actual coverage sits at 86.7 %. The mechanism is in place; the bar has not been raised to meet it. That is a job not yet done, and I would rather list it here than let the word "ratchet" imply a discipline that is not being applied yet.

When not to do this

A one-off script nobody will maintain. The check outlives the thing it guards, and then it is pure cost.
A rule that has never actually been broken. Start with the reminder. A check written for a hypothetical failure buys nothing and adds a thing to maintain. Let the rule fail first, then automate it.
An area with no checkable signal. If the property you care about has no mechanical fingerprint, an invented one produces false positives — and false positives are how a check loses its authority.

The honest caveat

All of this is kept on my own tasks. There is no multi-person sample behind any of it. The 421 and the 184 are counts from one tree on one day, not a study; the five checks are the ones I happened to need, in the order I happened to need them.

I would be misrepresenting the material if I presented it as an industry finding rather than as one practitioner's log, and I have no way of knowing which parts of it survive contact with a team of eight.

The multiplier

The uncomfortable version of the throughline: speed of production amplifies whoever set the definitions, and it amplifies a bad definition exactly as efficiently as a good one. An executor that writes a correct file in four minutes writes an incorrectly specified one in four minutes too — and then it writes a hundred of them.

Which is why the ladder ends where it does. The faster the production side gets, the less the middle rung is worth on its own, and the more of the outcome rests on checks that fire without anyone being present. That leaves the definitions — what counts as done, what counts as an artefact, which mistake is worth a check — sitting exactly where they were before any of this started: with a person, who cannot delegate them, and who is the one asked about the result.

From requirement to contract — Part 5. Next: the checkable condition comes before the thing that satisfies it — writing the test, the criterion or the guard first, and what changes when the order runs the other way.

If you do this better, tell me which of your rules you managed to turn into a check and which ones resisted. If you have been through this, what was your version of the 421 — the rule everyone had read and nobody followed? If you see it differently, say where a blocking check cost you more than the mistake it prevented. How is it solved on your side, and what broke there?

Gates, Not Micromanagement

Anton Brilliantov — Tue, 22 Sep 2026 17:10:07 +0000

Control lives on the transitions; between them nobody watches.

👋 Hi, I'm Anton — a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series is about the order the work happens in: a wish becomes requirements, requirements become a contract, the contract becomes tasks and specs. This part is about where the checks sit on that road, and about the kind of supervision I stopped doing. Running notes live on my GitHub: github.com/brilliant-almazov.

This is how I do it right now, with the price attached — maybe you already do it better, maybe you see it differently.

Primer, in one paragraph

The shape of the work in this series: a wish becomes requirements, requirements become a contract declared in a schema, the contract becomes tasks, and a task becomes a spec — a self-contained brief that one executor runs end to end without reading anything outside the files it names. An executor is whoever performs one such spec; here that is usually an automated one, and nothing below changes if it is a person. A lead prepares the facts, hands the specs out and accepts the results. That is the whole cast: a road with steps on it, specs travelling down it, and one person deciding whether a step has been passed.

The thesis

Control belongs on the transitions, not on the process.

Watching how the work is going produces no fact that the acceptance of the next transition would not produce anyway. It produces a feeling of proximity, at the price of an interruption on both sides — and it produces it repeatedly, because a process has no natural end and a transition does.

So the road from a wish to a release is cut into five transitions, and each of them carries exactly two things: what is accepted, and what proves it. Everything between two gates is nobody's business until the next gate.

  wish ──▶ requirements ──▶ contract ──▶ spec ──▶ execution ──▶ acceptance ──▶ release
                         │            │        │             │              │
                        [1]          [2]      [3]           [4]            [5]
                      numbers    compatibility  no open    one command   build, tests,
                     not "fast"     is green    question    that runs   structure, drift

How this is normally done

Nothing below is a criticism. It is the baseline I moved away from, and every line of it is reasonable in the setting it came from.

Practice	The common shape
Daily status	A daily meeting where everyone says what they did and what they will do
Board with columns	A work-in-progress limit on a board, so load is visible at a glance
Review along the way	Reading changes as they appear, not only at the end
Progress report	A written summary of how far along the work is, produced on a cadence

All four answer the question how is it going. None of them answers may this step be passed. That is the question I care about, because it is the only one that changes what happens next.

The five gates

Transition	What is accepted	What proves it
requirements → contract	requirements are complete and consistent	non-functional ones stated as numbers, not as the word "fast"
contract → spec	the contract is accepted	the compatibility check is green
spec → execution	the spec is runnable without reconnaissance	there is no open question in its text
execution → acceptance	the code does what it claims	one acceptance command
acceptance → release	the change does not break the neighbours	build, tests, structure and drift checks

The third column is the whole design. It is not a wish, not a definition of done written in adjectives, not "the reviewer is happy". It is something that can be run or read: a number, a green check, the absence of a question mark, a command, a build.

A gate whose third column cannot be filled in is not a gate. It is a meeting.

Firing one looks like this, and it looks the same every time:

   execution ──▶ acceptance
   ────────────────────────────────────────────────
   the claim     "the iteration is finished"
   the artefact  one command, run, output read
                 ─────────────────────────────────
                 ok      → transition passed
                 not ok  → not accepted, no discussion of effort

The claim and the artefact are on separate lines on purpose. The first one is never the input to the decision; the second one always is.

Between the gates, nobody watches

   gate 3 ───────────────── the interval ───────────────── gate 4
   spec handed over       nobody watches in here          acceptance
                          ✗ no status check-in
                          ✗ no progress report
                          ✗ no review mid-run

Two consequences, and the second one is the uncomfortable one.

Nobody interrupts the work in progress. Not to ask how it is going, not to suggest a better approach halfway, not to look at a half-written file. The interval belongs to whoever is inside it.

Responsibility is delegated together with the decisions. Whoever holds a gate has the right to say not accepted, and is not obliged to justify it line by line. That right is what makes the gate a gate; without it the gate degenerates into an opinion that can be argued past, and the process reverts to supervision by whoever argues longest.

A gate stands on an artefact, not on a claim

This is the line I would keep if I had to delete everything else in this article.

A statement that the work is done is not evidence that the work is done. Not from an executor, not from me. Every gate leans on an artefact — a number, a run, a file — and the artefact is looked at, not reported on.

The reason is not ideological, it is a property of the executor. Executors fail in a predictable, small set of ways, and the reliable answer to a predictable failure is an external check rather than trust. The ladder I use everywhere is reminder → rule → check: a reminder lives in one conversation, a rule works for as long as somebody reads it, and only the check works whether or not anyone remembers it exists.

That ladder applies to me as much as to anyone else. When I say the spec is ready, that is a claim. When the spec contains no open question, that is a fact somebody can verify without me.

The case: five signs, all of them read at a gate

Here is what this actually looks like on real work, rather than as a principle.

A set of specs is written, handed out, executed, accepted. Along the way, five things can happen. Each of them is visible at a gate — during acceptance, or as a blocked write — and none of them requires anybody to have watched the work happen.

Sign	What it actually means
a clarifying question was asked	a fact was not written into the spec
a rule blocked the write	a primitive that should have been reused was not named
two iterations edit the same file	the split into iterations is wrong
an iteration is rewritten after acceptance	the acceptance criterion was not checkable
an iteration ate more context than its named files need	a defect of the spec

Read the right-hand column again. Not one entry says anything about the executor. Every one of them is a defect of the specification, discovered at a transition and paid for at that transition.

The extreme case of the last row is the number I keep coming back to in this series: iterations of one early set were eating about 350 000 tokens each, because the executor was assembling its own context — hunting for types, paths and signatures instead of receiving them. The tasks were completing. Nothing looked wrong from the outside. The cost was visible only because acceptance recorded it, and it turned into two concrete repairs — a closed list of files per iteration, and a section of stated facts in the controlling spec.

I am not going to attach a count of how often each sign fired, or how long a transition takes. Those numbers do not exist in my records, and inventing them next to a real one is how a real one stops being believed.

What it looks like from the lead's side

The chain is short, and the shape of it is the point:

Prepare the facts. The only step where reading around the codebase is allowed at all.
Hand out. One executor, one task, one context.
Accept the iteration — by its own package only. There is no full run inside an iteration.
Accept the stage — one full run, once, at the end.

The lead does not write code. That is not a rank, it is a conflict of interest: the person holding a gate should not also be the person whose work the gate is judging.

Why gates and not observation

Observation requires presence. A gate does not: it fires when the transition is attempted, whether or not anyone is at their desk.
Observation catches only what has already happened, and usually catches it in the version the observer was told about. A gate catches a divergence at the moment of the transition, and it costs one run.
Observation scales badly. Two parallel executors are already more than one person can watch honestly; the gates do not care how many there are, because they sit on the road rather than on the worker.

What this costs

Every gate needs an artefact, and building the artefact is work. A gate without one drifts into taste, and taste is exactly the thing being replaced. That is a real up-front bill: the compatibility check, the acceptance command, the structure and drift checks all had to be built before any of this could be run this way.
"Not accepted" without a line-by-line justification reads as rude. It works only where there is enough trust in whoever holds the gate, and it takes a while to establish that trust. In a setting without it, this style is corrosive.
Between gates, nothing is known about the work. If a transition is long, bad news arrives late. The cure is a finer split — more, smaller transitions — not the reintroduction of supervision. Every time I have been tempted to add a check-in, the real problem was that an iteration was too big.

When not to do this

Research. When the transition is not visible yet, there is nothing to put a gate on. First the exploration, then the spec, then the gates.
A task without a readiness criterion. "Make it nicer", "improve it" — there is nothing to accept, so acceptance cannot happen and the gate is theatre.
Teaching someone new. Here the process itself is the point: watching how a person arrives at an answer is the entire content of the exercise. Gating only the outcome teaches nothing.

The multiplier

An executor cannot be given a conversation about how the work is going. There is nowhere to put one. It can be given exactly two things: an input and a criterion — and it will return exactly what those two describe, including everything they failed to describe.

Which means the discipline that reads as harsh when applied to people turns out to be the only shape that works at all here. Not because the tooling demands rigour, but because it removes the fallback: with a person, a vague spec is quietly repaired by a conversation nobody records. With an executor there is no conversation, so the vagueness is delivered intact, in the output, at the gate. That is a good thing. It just leaves the definitions with nowhere to hide, and the definitions are still mine to get right.

From requirement to contract — Part 4. Next: responsibility does not move to the executor, even when the executor writes most of the code — what stays on a person, and what it takes to keep it there.

If you do this better, tell me what your third column looks like — what artefact your transitions actually lean on. If you have been through this, what did removing the status check-in break first? If you see it differently, say where watching the process caught something a gate would have missed. How is it solved on your side, and what broke there?

The Tracker Is the Spine

Anton Brilliantov — Sun, 20 Sep 2026 22:02:27 +0000

Estimate, status, incidents, budget — one thread, or the cost of a requirement is a feeling.

👋 Hi, I'm Anton — a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series is about the order the work happens in: a wish becomes requirements, requirements become a contract, the contract becomes tasks. This part is about the last link — the tracker task — and about what it has to carry before anyone can answer "what did that requirement cost".

Running notes live on my GitHub: github.com/brilliant-almazov. This is how I do it right now, with the price attached — maybe you already do it better, maybe you see it differently.

The thesis

The tracker here is not reporting and it is not ceremony. It is the only place where a requirement, a contract, a unit of executable work, a pull request and an acceptance decision sit on one thread, in an order you can walk in either direction.

That thread exists for exactly one question: what did this cost? Not "was everyone busy" — what one requirement cost, from the sentence someone said out loud to the change being accepted.

Without an estimate written before the work and a fact recorded after it, that question has no answer. It has opinions. "That one was expensive" and "that one was fine" become statements about how the week felt, and every argument about scope after that is an argument between two feelings.

The case: iterations that cost 350 000 tokens each

The concrete thing that made me build this rather than talk about it.

What happened. In one of the early prompt sets, each iteration was eating about 350 000 tokens. The tasks were being completed. Nothing was failing. The number simply sat there in the task, next to the estimate, being much larger than the estimate implied.

Where it was going. Not into writing code. The largest single line item was reconnaissance: the executor was assembling its own context — hunting for types, for file paths, for signatures, reading neighbouring packages to work out how things were done around here. After reconnaissance came repeat runs, and after that, rework.

What that actually meant. The same fact — one type name, one signature, one convention — was being rediscovered independently by every executor that touched that area. The cost of a fact was being multiplied by the number of people who needed it, and nobody was writing the fact down anywhere it would be found next time.

What changed. The spec grew two things: a closed list of files for each iteration, and a section called facts of the set. A fact is written once, in the spec. Reading is limited to the named files — at most three of them. Searching the tree is not permitted.

What is visible today. As of 2026-08-16: 298 spec files, more than 20 closed sets, 3 sets in flight, 5 written but not yet taken, and the largest single set at 41 files. Real set sizes, for scale: 13, 12 and 40 iterations.

I am not going to attach hours or money to that case. Those values do not exist in my records, and putting invented ones next to a real argument is how a real argument stops being trusted.

The part worth keeping is this: the 350 000 was only ever visible because the task carried an estimate and a recorded fact. Without both, it is an executor that finished its work. With both, it is a spec defect with a price on it.

How this is normally done

Nothing below is a criticism; it is the baseline I diverged from, and it is a reasonable baseline.

Practice	The common shape
Estimate	Abstract units of complexity — story points, deliberately not hours, deliberately relative
Status	Movement through a board, largely as reporting upward to a manager
Reflection	A retrospective at the end of an iteration, discussing the period as a whole
Incidents	Written up afterwards, in a postmortem, for the events big enough to warrant one

The reason points avoid hours is sound: hours invite the estimate to be read as a commitment, and relative sizing between people is more stable than absolute sizing. The reason retrospectives are periodic is also sound — a period gives you a sample.

My problem with the baseline is narrower than "it's wrong". It is that none of those four practices attaches a number to one requirement. They attach numbers to a period, a board, or an outage.

What I do instead — four practices, on every task

1. An estimate is mandatory

Every task carries an estimate before work starts. The scale is hours of executor time: 1 point ≈ 1 hour of an executor's run.

Property	Rule
When	Set before the work starts, never after
Scale	Hours of executor time, not abstract complexity
On scope change	Revised explicitly, as a visible edit, not quietly absorbed
What it excludes	Human hours. This estimates the run, not the labour

That last row is the one people push back on, and the pushback is fair — it is the exact thing story points were invented to avoid. My defence is that this scale is not measuring a person, so it cannot be used as a promise extracted from one. It measures a run whose actual cost is recorded afterwards in the same units. An estimate you can compare against a fact in the same unit is worth more to me than an estimate that is safe from misuse.

2. Status moves on every transition

  taken into work  ────►  PR opened  ────►  accepted
                             │
                             └──► blocked on something external
                                  (a status, not silence)

Three transitions, each one moved the moment it happens. The fourth state matters most: when a task is waiting on something outside it, that is a named status, not a task that has gone quiet. Silence and blocked look identical from outside and cost very different things.

3. Incidents are recorded at the moment they happen

Five categories. One line each, written when the thing occurs.

Category	What it catches
Executor error	The work was done wrong against a spec that was clear
Scope change	The requirement moved after the task was estimated
Spec ambiguity	The spec permitted two readings and the wrong one was taken
Technical surprise	Reality differed from what the spec assumed
External block	Progress stopped on something outside this task

And one rule that does more work than the five categories combined: reconstructing incidents after the fact is itself an incident. Not a scolding — a data-quality statement. Numbers assembled from memory at the end of a task are numbers you cannot act on, so the act of assembling them late gets recorded as the defect it is.

4. A final report closes the task

Every task ends with a report in a fixed shape, so that tasks are comparable to each other:

  time            executor  ·  human  ·  pauses
  tokens          ─
  money           ─
  external calls  ─
  incidents       ─
  estimate        ─
  actual          ─
  result          ─

The slots above are empty on purpose. I am publishing the shape of the report, not a filled example — I do not have a sanitised filled one to show, and inventing plausible hours and dollars to make a figure look complete would undo the entire point of the section.

What the thread makes visible

Every number below exists only because each task carries an estimate and a recorded fact. Remove either one and these are anecdotes.

What	Value
Tokens per iteration, one early set	≈ 350 000
Largest expense inside that	Reconnaissance — types, paths, signatures, neighbouring packages
Real set sizes	13 · 12 · 40 iterations
Spec files, as of 2026-08-16	298
Closed sets	20+
Sets in flight	3
Written, not yet taken	5
Largest single set	41 files

The distribution is the interesting part. Sets of 13 and 12 iterations sit next to a set of 40, and knowing which shape you are about to start is the difference between an estimate and a guess. That distribution is only knowable because the closed sets kept their numbers.

Signals that a task was expensive

Five of them. Each is one line in the task, and any one of them means the work cost more than the estimate implied:

A clarifying question had to be asked.
A rule fired and blocked something.
Two iterations edited the same file.
An iteration was rewritten after acceptance.
An iteration consumed more context than its named files could account for.

All five are read the same way, and this is the part that decides whether the practice survives contact with people: these calibrate the spec, not the executor. A clarifying question means a sentence was ambiguous. A rewrite after acceptance means the readiness criterion was wrong. The moment any of these is read as a performance signal about whoever did the work, recording them honestly stops, and the whole thread turns into fiction that costs time to produce.

Why this shape

Because the estimate and the fact are in the same unit. Hours of executor time, estimated up front, hours of executor time recorded afterwards. That gives one number you can put next to the value of the requirement and ask whether the trade was worth making. Two numbers in different units — points against dollars, complexity against duration — cannot be compared without a conversion nobody agrees on.

Because incident categories answer "what do I fix", not "who was wrong". Each category has a different repair, and the repair is what makes the category worth writing down:

Category	What it repairs
Spec ambiguity	Fixed in text — the sentence gets rewritten
Executor error	Fixed by an external check, not by asking for more care
Scope change	Fixed in the estimate, explicitly and visibly
Technical surprise	Fixed in the facts section, so the next set inherits it
External block	Fixed by making the wait visible, not by waiting quietly

Two of those repairs are the subject of the next parts of this series. Ambiguity is repaired by making the spec exhaustive. Executor error is repaired by a check that runs whether or not anyone remembers to run it.

The multiplier

An automated executor makes the accounting cheap — the numbers can be pulled and folded into a report without anyone typing them. What it does not do is decide what counts as an incident, or what the estimate should have been, or which of the five categories a given failure belongs in. Those are judgements, and the whole value of the thread is in them. Cheap measurement amplifies whoever set the definitions; it does not supply the definitions.

What this costs

It taxes every task. Estimating, moving status, writing incidents as they happen and closing with a report all take time on every single task, including the tiny ones.
It is the first thing to be dropped under pressure. When a deadline is close, the accounting is what gets skipped, and it gets skipped exactly when the data would have been most useful.
Late reconstruction produces numbers you cannot trust. Which is why it is classified as an incident rather than as a catch-up — the alternative is a tracker full of confident, wrong figures.
The scale does not transfer. "One point ≈ one hour of an executor run" is not a scale for estimating a team of people, and using it that way would reproduce every problem story points were designed to solve.

When not to do this

A one-off change. Seven fields of accounting around a single-line fix is ceremony, and I skip it.
A task with no readiness criterion. If there is nothing to accept, there is no end to the thread, and a report on an unaccepted task is a report on nothing.
Somebody else's process. Where status already carries a different meaning — a contractual milestone, a billing state — overloading it with a second meaning breaks the first one.

The honest caveat

The estimates, the incidents and the budgets described here are kept on my own tasks. There is no multi-person sample behind any of it, and I would be misrepresenting it if I presented these numbers as an industry finding rather than as one practitioner's log.

There is also no separate analysis function in this setup: requirements are formulated by the person who owns the task. That works at this size and it is a known limit, not a design principle.

From requirement to contract — Part 3. Next: watching a process is not the same as gating it — where the checks sit on the transitions themselves, so that a step cannot be passed rather than merely being observed.

If you do this better, tell me what unit your estimate and your actual are both recorded in. If you have been through this, what did your version of the 350 000 turn out to be hiding? If you see it differently, say where per-task accounting cost you more than it returned. How is it solved on your side, and what broke there?

The Contract Is a .proto File

Anton Brilliantov — Sat, 19 Sep 2026 16:36:38 +0000

One handle, one source of truth - the HTTP spec is derived, not written.

👋 Hi, I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series is about the road from a requirement to a contract: what has to be true before anybody writes code. This part is the short one, with a single claim in it. Running notes live on my GitHub: github.com/brilliant-almazov.

This is how I do it right now, with the price attached - maybe you already do it better, maybe you see it differently.

Primer, in one paragraph

Every service-to-service call in this system is declared in a schema file - a .proto - kept in one shared contract repository. The build turns that file into typed clients and servers for both sides of the call. The same file also carries the HTTP role of a handle: the door service exposes it over HTTP, and the HTTP specification is produced from the schema rather than maintained beside it. One file per interface; everything else in the picture is output.

The claim

The contract is declared in the schema, and nowhere else. Messages, calls, the meaning of each field, which fields are required, the bounds a value may take, the codes a refusal can carry - all of it lives in the .proto. Nothing about the interface is described in a second place.

That reads like a style preference until you name the alternative out loud: two documents that mean the same thing, kept in step by a person remembering to do it.

The case: a declaration that is checked by the build

I did not learn this on handles. I learned it on the two most boring artifacts a service has - its environment variables and its metrics - where the same principle is already running.

What it was. Both were described by hand, in files next to the code, and both drifted from the code quietly. Nothing failed. The description was simply wrong, and it stayed wrong for as long as nobody happened to read it against the source.

What was done. Both descriptions are now taken off the code by machine and kept as repository artifacts. For a variable declared by the service configuration the catalog records defined_in - the file and the line of the declaration; for one declared by the platform, the owning catalog. The metrics snapshot has one row per metric plus a <dynamic> row for the factory that registers metrics at runtime.

Artifact	Entries	Where they come from	An entry records
Environment catalog	59 variables	45 platform · 14 service config	where it is declared
Metrics snapshot	67 entries	59 platform · 6 service · `<dynamic>`	how it is registered

What holds it. Drift is a build failure. The check runs the same generator in --check mode whenever any .go file, the manifest, the modules file or the snapshot itself changes, and the generator is installed at the same platform version the service has in its modules. Not a review convention, not a linter warning - a red build.

Where it stops. Resource variables are not in the catalog: the platform builds their names by concatenation at runtime, so there is nothing static to read. That is a stated hole rather than a silent one, and it is the honest part of the claim.

The conclusion is one line, and it is the whole article:

A description written by hand drifts. A description that is derived and checked does not.

The schema does exactly that, for a call and for an HTTP handle.

How this is usually done

The common arrangement is three files describing one interface. The schema declares the call. A separate document describes the HTTP surface - an OpenAPI file, hand-written or half-generated. Human-facing documentation is the third. All three are true on the day they are written, and after that, keeping them equal is manual work backed by an agreement.

The agreement is the failure point. Nothing in the pipeline notices when the schema gains a field the HTTP document has never heard of.

What we do instead: one handle, one source

The HTTP handle is not a second interface. It is the same contract with its role marked: the method carries an HTTP annotation in its declaration, and the HTTP specification is produced from the schema.

                    .proto  (one file)
        messages · calls · required fields · bounds · refusal codes
                              │
                  ┌───────────┴───────────┐
                  ▼                       ▼
            gRPC call                HTTP handle
            typed client             role marked by an annotation
            typed server             spec derived from this same file

            ✗  hand-written HTTP spec, kept in step by a person

Stated as a prohibition, which is how I actually apply it: there are no two sources of truth for one handle. If a fact about the interface is written in a second place, that place is either generated or wrong.

Compatibility is not my judgement either. The contract build tool checks every change against the published schema, so a breaking change is visible before a line of implementation exists. That is what makes the gate at the end of the previous part enforceable: a requirement moves on to specification only with an accepted contract, and accepted means the compatibility check is green.

Contract analytics is its own step

Because the schema is the only place, arguing about it early is cheap and arguing about it late is not. So the field-by-field discussion - names, enums, what a zero value means, what a refusal returns - happens on the schema, before generation, where an edit costs a line.

The part I insist on is the order. The set of cases the contract has to be able to express is written before a single field is named:

  success           the ordinary answer, and what it contains
  refusal           which codes exist, and what the caller does with each
  conflict          two inputs that each exist but disagree
  empty response    a valid empty list, not an error
  page boundary     how the caller asks for more, and how it learns there is no more

Five rows. They take minutes to write and they settle most of the message shape: the empty case decides that an empty list is an answer and not an error, the page-boundary case decides that the response carries a cursor, and the refusal case decides that codes are an enum rather than free text in a message string.

The example

Neutral package, neutral domain - this is the shape, not our schema:

syntax = "proto3";

package example.v1;

service EntityService {
  // The HTTP role is declared on the method; the HTTP spec is derived from it.
  rpc ListEntities(ListEntitiesRequest) returns (ListEntitiesResponse);
}

message ListEntitiesRequest {
  string parent_id  = 1;  // required; a refusal, not an empty list, when it does not exist
  int32  page_size  = 2;  // 1..200, clamped server-side; 0 means the default
  string page_token = 3;  // cursor from a previous response; empty asks for the first page
}

message ListEntitiesResponse {
  repeated Entity entities        = 1;  // an empty list is a valid answer
  string          next_page_token = 2;  // empty only when this is the last page
}

enum RefusalCode {
  REFUSAL_CODE_UNSPECIFIED        = 0;
  REFUSAL_CODE_PARENT_NOT_FOUND   = 1;
  REFUSAL_CODE_PAGE_TOKEN_INVALID = 2;
  REFUSAL_CODE_SELECTOR_CONFLICT  = 3;
}

Four of the five cases are visible there without reading any implementation, and the fifth - conflict - has a code reserved for it. Lists are cursor-paginated with a clamped page size; there are no unbounded lists here.

What stays data, and not contract

Not everything that looks like an enum belongs in the schema. A category - a type, a status, the level at which something is attached - is a dictionary row and a string code, not a .proto enum. A new category is then added as data: no contract change, no regeneration, no rollout. An enum is reserved for the things that change together with the code, where a new member means nothing until some branch handles it.

The test I use is one question: if a new member arrives, does any code have to change? No - dictionary. Yes - enum.

What it costs

Three costs, all real:

The schema becomes a bottleneck. Until the contract is accepted there is no code and no work to hand out. That is deliberate, and it is still a bottleneck.
Field discussion looks like bureaucracy - right up to the first breaking change that gets caught before implementation instead of after release.
The contract build tool is one more dependency in the build, with its own version to keep in step with everything else.

The cost that is easiest to underrate is the one this ladder prices - the same edit, before and after generation:

  edit in the schema, before generation     1 line
  ───────────────────────────────────────────────────────────────
  edit after generation                     contract
                                            generated code
                                            service code
                                            tests
                                            documentation

When not to do this

Three cases where I would not pay for any of it: an interface with exactly one consumer and that consumer inside the same binary; a one-off internal handle with a life expectancy of a week; and exploratory work where the shape of the answer is genuinely not known yet and the first few versions are meant to be thrown away.

The multiplier line

A schema that both the call and the HTTP specification are derived from is the same move as putting a fact into the text of a specification, one level up: the executor does not choose the shape of the answer, it receives it. What is derived cannot drift, and what cannot drift needs nobody to remember it.

From requirement to contract — Part 2. Next: the tracker - the only place where the price of a requirement is actually visible, and what that price looks like once it is written down honestly.

If you do this better, tell me where you keep the HTTP description when the schema is the source. If you have been through this, what did your second source of truth turn out to cost? If you see it differently, say where a hand-written spec beats a derived one. How is it solved on your side, and what broke there?

Requirements Come Before the Contract

Anton Brilliantov — Fri, 18 Sep 2026 08:28:35 +0000

Until the schema is declared, changing your mind costs one paragraph.

👋 Hi, I'm Anton — a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This series is about the order the work happens in: what has to exist before anyone writes a line of code, and what that order is actually worth. This part is about the first links of that chain — a wish, and the requirements it becomes. Running notes live on my GitHub: github.com/brilliant-almazov.

This is how I do it right now, with the price attached — maybe you already do it better, maybe you see it differently.

The moment a requirement changes

Someone comes back and says the thing should behave slightly differently. Same sentence, one clause changed. What that costs depends entirely on one question: has the contract been declared yet?

Before it has, the requirement is the only artefact that exists. Editing it is editing one paragraph. Nothing downstream has been generated from it, so nothing downstream has to agree with the edit.

After it has, the same clause moves five things that must stay consistent with each other:

  before                          after
  ──────                          ─────
  the requirement                 the contract
                                  generated code
                                  handwritten code
                                  tests
                                  documentation

  one artefact                    five artefacts, in step

I am not going to attach hours or money to that. I do not have those numbers, and putting invented ones next to a real argument is how a real argument stops being trusted. The shape is the point: one edit against a coordinated edit.

What this article is about is where that line sits, and why it is worth knowing before you cross it rather than after.

The case: a form nobody ever decided

The clearest thing I have on this is not a dramatic outage. It is a boring one, which is why it generalises.

Reading rows out of a database is a form. Open a result set, loop it, check the error, close it. Or read exactly one row. Or count. Or ask whether a row exists at all. Four shapes, all of them decided a hundred times a year by whoever is typing at the moment.

That form was never stated as a requirement, so every author decided it locally. An audit of one service tree on 2026-08-13 found 44 copies of four forms:

form	what it is for	copies
many-row loop	read a set of rows	18
single row	read exactly one row	6
counter	`COUNT(*)` into a number	8
existence probe	does a row exist at all	12
total		44

Two details make this a requirements story rather than a tidiness story.

First, 12 of the 44 differed from each other only in the text of the error wrapper. Not in behaviour, not in the type they returned in any meaningful way — in one sentence of prose attached to a failure. Twelve authors wrote the same loop and phrased the same failure twelve ways, because there was nothing to conform to.

Second, the right form already existed in that tree. It had been written, it worked — and it lived inside a domain package, where nothing outside that domain could reach it. So the tree did not lack a solution. It lacked a statement that this was the solution, made before the copies existed.

What it took to close

Moving the 44 onto one core took a set of 40 iterations, one file per iteration. That is the honest cost line: not a heroic weekend, a queue of small mechanical changes, each one boring on its own.

The part worth stealing is not the refactor. It is the closing criterion that came out of it, which is checkable by a machine:

  for rows.Next()   ·   rows.Err()   ·   rows.Close()   ·   QueryRow(
  ─────────────────────────────────────────────────────────────────
  appear in the tree in exactly one package — held by a test that
  fails the build the moment a second copy shows up

That sentence is what a requirement is supposed to look like. It is not "be consistent about database reads". It is a condition somebody can run, that answers yes or no, and that keeps answering after everyone involved has forgotten the conversation.

The same service carries a second decision of exactly this kind. It grows by number of packages, not by size of file: it went from 13 packages at an average file of 50 lines to 252 packages at an average of 39. Whether you like that shape is beside the point — it was decided once, in front, so no author had to re-decide it and no two authors could decide it differently.

How this is normally done

There is a well-developed craft here, and I am not pretending otherwise.

A requirements document from a template — the Volere specification template is the classic one, and ISO/IEC/IEEE 29148 is the standard that formalises the whole activity.
A dedicated analyst role, with its own body of knowledge — that is what BABOK is for.
Requirements as a wiki section, living next to the design pages.
A call, then minutes — decide by voice, write down what was decided.

All of these work. They work best where there are more roles than there are here: an analyst who owns the document, reviewers who read it, a cadence that keeps it current. Where the same person holds the wish, the requirement and the acceptance, a heavy template mostly produces a document nobody re-reads. What I kept from that craft is the part that survives being small: every step leaves a file, and no step is a conversation.

How I do it — the chain

Seven links. Each one is an artefact somebody can open, not a thing somebody remembers.

Wish — one sentence, in the customer's own language. Not a design, not a ticket: the sentence they actually said.
Requirements — functional and non-functional, written down as a list.
Contract — a .proto file. This is the first artefact that code is generated from.
Tracker tasks — one per executable unit, each with an estimate and an acceptance criterion.
Spec — a written specification for whoever does the work, precise enough to be executed without asking questions.
Code and tests.
Acceptance — a gate that passes or fails.

The line that does the work: before link 3, no code exists. Not "we try not to start early" — there is nothing to start from, because the thing code is generated from has not been written yet.

What "non-functional" means here

This is the half that gets skipped, so it is worth being concrete. In practice the non-functional list is short and always the same headings:

heading	the question it answers
load	how much of this, and how often
latency	how long the caller is willing to wait
read-to-write ratio	which side of the system this feature actually stresses
retention	how long the data has to stay readable
tenant isolation	what one account is allowed to see of another
compatibility	what already depends on this and must keep working

None of these is documentation for its own sake. Each one is a line that later decides something structural — which layer takes the work, whether there is a queue in the middle, whether reads and writes are separate at all. That consequence is a whole topic of its own and it is the last part of this series; here I only want to establish that the line has to be written down before the contract, because the contract is where those consequences start to be expensive.

Decomposition goes by architecture, not by taste

Once a requirement is written, it has to land somewhere. Which layer it lands on is a property of the system, not a preference of whoever picked it up.

listing entities stays fast as an account grows — a read requirement. It lands on the read layer: queries, indexes, pagination.
an order is written in one transaction — a write requirement. It lands on the write layer: transaction boundary, conflict rules.
recalculation never blocks the caller — a requirement about pace, not about either. It lands on a background worker: queue, retry policy.

The test of whether decomposition is really architectural is simple: hand the same sentence to two people and see whether it lands in the same place. If it can land in three places depending on who reads it, the sentence is not a requirement yet.

Why the order is worth keeping

Because reversing is allowed, and it stays cheap up to the fifth link.

That gives one rule I can apply without thinking about it: a requirement that is still being argued about is reworked on the schema, not after generation. If two of us disagree about what a field means, the argument is cheap right now and expensive in an hour.

The second rule is about what a requirement is allowed to say. Every requirement needs a criterion that is either one command or one number.

"Works fast" is not a criterion: nobody can say when it is met, so acceptance falls back to whoever is more insistent that day. "Holds N requests per second below M latency" is a criterion: one command runs it, or one number answers it, and both sides read the result the same way. I am deliberately leaving N and M as letters — those numbers belong to the system being built, not to an article about the order of the work.

What it costs

This is not free, and pretending it is would be the fastest way to make it look like advice.

Somebody has to hold the whole chain. Seven links only work as one thread if one person can see all seven. That person is a bottleneck by construction.
There is no analyst function here, and no analyst. The owner of the task writes the requirements and runs the breakdown. That is fewer handoffs and also fewer second opinions — a wrong requirement stays wrong until it is caught by acceptance.
There is no formal requirements document. No template, no numbered specification, no sign-off page. Requirements live in the tracker task and in the spec. It works because the artefacts are small and current; it would not survive a reader who joins in a year and expects a document.
On a small change the chain does not pay for itself. Seven links around a one-line fix is ceremony, and I skip it.

When not to do this

A research task, where the point is that nobody knows yet what should be built. There are no requirements to gather because the input to them does not exist. That work is investigation first, requirements after, and forcing the order the other way produces confident sentences about a system nobody understands.
A one-off change that will never be extended and has no consumers.
A task with no readiness criterion. If nothing can be checked at the end, acceptance is impossible and the last link of the chain is missing, which makes the other six decorative.

The multiplier

An automated executor does not care what order it got the facts in. Hand it a task with the form undecided and it will decide the form, confidently, and keep going — and it will do that separately in each of the 44 places, because each place is a fresh conversation to it. It does not get slower when the input is incomplete; it gets more expensive, quietly, and the bill arrives later as inconsistency.

Which is the actual argument for the order. The chain is not there to help whoever is executing. It is there for whoever pays for the rework.

From requirement to contract — Part 1. Next: there is exactly one contract, and it is a .proto file — including for endpoints that are only ever spoken to over HTTP.

If you do this better, tell me where your requirements live and who keeps them current. If you have been through this, what did your version of the 44 copies turn out to be? If you see it differently, say where writing requirements first cost you more than it saved. How is it solved on your side, and what broke there?

Dependency Injection in Go, After Years of Symfony

Anton Brilliantov — Thu, 17 Sep 2026 12:58:07 +0000

The container I had, the container I don't have, and what I do instead.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This one is about the single piece of Symfony I missed most on the way over, and about what I found when I stopped missing it and looked at what I'd built in its place. Notes: github.com/brilliant-almazov.

As always: this is what I do on one codebase, with the costs I actually pay. Not advice for yours.

What the container actually did for me

In Symfony, dependency injection is not a topic. It's infrastructure that has been finished for years, and the measure of how finished it is: I went whole quarters without opening a wiring file.

Six things it does, and it's worth separating what each one buys from what each one hides, because they are not the same list.

Autowiring. A constructor asks for an interface, the container resolves it by type. Adding a dependency to a class is adding a parameter - no configuration line, no registration, nothing else edited.

final class OrderCreator 
{
    public function __construct(
        private readonly OrderRepository $orders,
        private readonly EventBus $events,
    ) {}
}

What it buys: a new collaborator costs one line, in the file where it's used. What it hides: the code that constructs this object doesn't exist as text anyone wrote. There is no call site to read.

Services declared by configuration. config/services.yaml with autowire: true, autoconfigure: true, and a resource glob that registers an entire directory. Buys: a directory of new classes is available without touching a wiring file at all. Hides: the population of the container is data, and the answer to "what objects exist" is a query, not a file.

Decoration. #[AsDecorator], or decorates: plus .inner in configuration, wraps an existing service so that every existing caller gets the wrapper instead - callers untouched, order controlled by priority. Buys: cross-cutting behaviour added without editing a single consumer. Hides: the class you're reading may not be the object that runs. OrderCreator in the file, three decorators in the container, and nothing at the call site says so.

Lazy services. lazy: true gives you a proxy; the real object is constructed on first method call. Buys: an expensive dependency that most requests never touch stops costing those requests anything. Hides: construction time moves to a place you're not looking at when you profile.

Per-environment graphs and compiler passes. A different set of definitions per environment, plus compiler passes that rewrite the graph as it's built. Buys: the test graph and the production graph are the same design with substituted parts. Hides: two graphs that must stay true to each other, and one of them is assembled by code that runs at build time.

A compiled container. The whole graph is resolved ahead of the request and written out as generated PHP. This is the part people forget when they call container DI "dynamic": a missing dependency, an ambiguous type hint, a service that can't be constructed - all of that fails when the container compiles, not on the request that needed it. And debug:container / debug:autowiring answer questions about the graph from the command line.

Put the buys together and you get the single sentence that makes the container worth it: adding a dependency costs one constructor parameter, and the graph is verified before anything serves traffic.

Put the hides together and you get the price: the graph is not in the code you read. To find out what an object actually receives at runtime, you run a tool. That's not a complaint - in a monolith with hundreds of services in one process, hand-writing that assembly would be worse in every direction. The container earns its keep exactly there, and the size of the graph is why.

  in Symfony           what it buys              what it hides
  ---------------------------------------------------------------------
  autowire: true       one constructor param     nobody writes the
                                                 constructing call
  services.yaml        a directory by one glob   what exists is data
  #[AsDecorator]       no consumer edited        what runs is not
                                                 what you read
  lazy: true           built on first call       construction moves
  services_test.yaml   parts swapped per env     two graphs to keep true
  debug:container      the graph in one command  it is not in a file

Why Go doesn't have this out of the box

Go's answer is that a dependency is a parameter, and parameters are passed at call sites, and call sites are text in a file that a person wrote.

There are no annotations to read. There is no convention that the runtime inspects your types and builds things for you. The compiler assembles nothing on your behalf; go build does not have a hook where a framework gets to construct your object graph. This is the same design decision that gives Go no inheritance, no implicit constructors, no exceptions - the reading of a line should not depend on machinery declared elsewhere.

I've stopped treating that as an omission. But it has a price, and the price is not "you type more".

The price is that everything the container did for you is now something you either write or do without. Lazy construction, decoration, per-environment substitution, lifecycle ordering - the language has no opinion about any of it, so each one arrives as a small hand-rolled mechanism, written under deadline, by whoever hit the need first.

I have the receipt for this. When I audited my own Go service for code that already existed in the shared platform library, one of the findings was a scheduler initialised lazily on a sync.Once with captured variables, instead of the platform's initialisation-state store. That's lazy: true, rebuilt by hand, in one service, by me. It works. It's also invisible to anything that could tell me it exists - no declaration, no registry, no way to ask the process what is lazy and what isn't.

The same audit found a service running two different loggers in two different packages. Nothing enforces that a dependency is the dependency when the dependency is just an argument.

The four options, and what each one charges

Everybody in Go knows all four. They're not ranked; they're priced.

Manual assembly at the composition root

The direct route: a function that constructs everything in order and hands the result to the daemon.

func buildServer(ctx context.Context, deps platform.Deps) (*Server, error) {
    orders := repository.NewOrders(deps.Executor)
    entities := repository.NewEntities(deps.Executor)
    orderWrites := manager.NewOrders(orders, deps.Clock, deps.Ids)
    // ...and so on, in dependency order, for every domain
}

Charges: one long function that every feature touches, so every feature branch conflicts in it; the order is maintained by hand; and - this is the one that actually bites - nothing tells you when a node is missing. More on that below, because it's the whole reason this article isn't just "write it by hand, it's fine".

When it fits: a graph you can hold in your head, or a graph that repeats the same shape enough that the repetition can be factored out.

Code generation of the graph

The wire-shaped approach: declare provider functions, declare what you want, and a generator writes the assembly function you'd have written yourself, at build time, in real Go you can read and step through.

Charges: a generator in the build path, and everyone who touches the project needs it; errors phrased in the generator's vocabulary rather than the language's; and when something is wrong you debug generated code, which is a file nobody wrote and everybody is slightly afraid to edit. It also puts a DO NOT EDIT header in the repository - and in my experience a DO NOT EDIT header is a rule, not a mechanism, unless a drift check enforces it.

When it fits: a large, fairly stable graph where the assembly function has become genuinely unpleasant, and the team already runs generators for other reasons.

A runtime container with reflection

The dig/fx-shaped approach, and the closest thing to what I had in Symfony: register constructors, ask for a type, get the graph built by reflection. fx adds lifecycle on top - ordered start and stop hooks, which is a real problem you'd otherwise solve by hand in every service.

Charges: resolution moves to runtime. A missing provider is a start-up error phrased in terms of reflect.Type, not a compile error on a line. The graph isn't in the code - you're back to "ask the tool", except the tool is now inside your process. Debugging goes through the container, which means the layer you least want to learn is the layer you must learn first when something is wrong.

When it fits: many components with the same shape and a real lifecycle problem - things that must start in order and stop in reverse. If you're writing that ordering by hand in every binary, a container is not an indulgence.

Functional options and plain constructors

Not dependency injection at all, but it covers the part of the problem people usually mean: an object with several optional collaborators.

func NewClient(base string, opts ...Option) *Client

Charges: constructors grow, and the option list quietly becomes the object's configuration surface - which is fine until two options are mutually exclusive and nothing says so. Nothing resolves anything: you still write every call site.

When it fits: a library boundary, or any constructor where most callers want defaults and a few want one thing changed.

    option               gives                      charges
    -------------------------------------------------------------------
 >  manual assembly      the graph is a file,       a missing node is
                         in order                   a green build
    generated graph      real Go the compiler       a generator in the
                         checks                     build; code nobody wrote
    runtime container    resolution and             a start-up message
                         lifecycle ordering         about a reflect.Type
    functional options   defaults with one          constructors grow into
                         thing changed              a config surface

Two of these - manual assembly and options - are the language's own grain. The other two rebuild a container out of tooling: one at build time, one at run time. That's the actual choice, and it's not between "explicit" and "convenient". It's about when you want to find out that the graph is wrong: at compile, at start-up, or never.

How I assemble a service

My answer is a split, and I only noticed it was a split when I sat down to write this. Infrastructure is declared. Domain objects are written.

The declared half

Every service carries one manifest. It declares the daemons and the resources, and that declaration is the only place they're declared:

service:
  name: <service>
  daemons:
    - name: server
      handlers: [grpc]
    - name: worker
      handlers: [scheduler]

infra:
  postgres:
    - name: main
  tx:
    - name: main
      pool: main
  grpc:
    - name: api
      daemons: [server]
  resources:
    - type: messaging
      name: main

From that declaration the platform builds the pool, the transaction registry, the gRPC server, the scheduler and the broker connection - and the name of every environment variable follows from it by one convention, <TYPE>_<NAME>_<FIELD>:

Declaration	Variable
`postgres: main`	`POSTGRES_MAIN_DSN`
`grpc: api`	`GRPC_API_PORT`
`messaging: main`	`MESSAGING_MAIN_RABBITMQ_URL`

That is a container. It's a small one, it only wires infrastructure, and I did not think of it as dependency injection until I compared it side by side with services.yaml. Same trade exactly: a declaration instead of a call site, convenience bought with implicitness.

What makes me comfortable with it is the one thing Symfony's container also does and most hand-rolled configuration doesn't - the declaration is verified. The service's variable catalogue is a generated artefact: 59 variables, 45 of them declared by the platform and 14 by the service's own configuration, each service-side one recorded with the file and line it's defined in. Drift between the declaration and the code fails CI. If the graph isn't in the code I read, then something had better be checking it, and here something is.

  declared - the manifest             written - the assembly
  ---------------------------------   -------------------------------
  postgres: main                      executor    a pool or a tx
    -> POSTGRES_MAIN_DSN              repository  reads only
  grpc: api                           manager     writes, find-or-create
    -> GRPC_API_PORT                  method      one of 20 generic RPCs
  messaging: main                     Calls       the domain's handlers
    -> MESSAGING_MAIN_RABBITMQ_URL    daemon      server or worker
  ---------------------------------
  59 variables catalogued, 45 of
  them from the platform; drift
  against the code fails CI

The written half

Domain objects are assembled by hand, in layers, in dependency order, in the daemon's assembly package for the domain:

the executor - a pool or a transaction, and nothing downstream knows which;
repositories - read only;
managers - write only, including find-or-create;
the RPC method bodies, which live in generic methods rather than in the domain;
the domain's Calls, where the handlers are named;
the daemon, which mounts them.

Two rules do most of the work here. Dependencies are interfaces, one interface per file in a cross-cutting port package - so an assembly line reads as "this concrete thing satisfies that named role", and a test substitutes at the same seam. And the transaction is not an argument: tx pgx.Tx in a signature is forbidden. Transactionality is a decorator applied from the outside, on mutations only, with the executor taken from the context. The domain code does not know it is running inside a transaction.

That decorator is worth noticing, because it's Symfony's decoration idea kept and everything around it dropped. It's the same benefit - a cross-cutting concern that consumers don't implement - and the difference is that it's applied at one visible place per domain rather than through a configuration key. I took the pattern and refused the indirection.

Why this stays readable longer than you'd expect

Manual wiring supposedly collapses under its own weight. Mine hasn't yet, and the reason is not discipline. It's that the repeated subtree is a generic, not a copy.

Packages are laid out by component type first with the domain nested inside - internal/repository/<domain>, internal/manager/<domain>, internal/grpc/handler/<domain>, internal/daemon/server/<domain>. Between two domains, the assembly differs in the type and in the spec, and in nothing else. So the assembly itself became a core with type parameters - Builder[Repo, Mgr], Domain[Repo, Mgr], Input, ManagerInput[Repo], HandlerInput[Repo, Mgr] - and a domain's wiring is four small files with the same skeleton.

The numbers say the same thing from outside: the service is 2733 non-generated Go files across 252 packages, averaging 39 lines; 44 files exceed 100 lines and only two of those aren't tests. A composition root would be enormous in that tree if each domain's subtree were bespoke. It isn't, so it isn't.

This is the honest form of "manual wiring is fine": manual wiring is fine when the wiring is regular. A container's biggest win is over irregularity - N different shapes, each needing its own construction. Remove the irregularity and you remove most of the win.

  executor      port.Executor       a pool or a transaction
     |
  repository    Reader[In, Out]     read side only
     |
  manager       Manager             write side only, find-or-create
     |
  method        20 generic RPCs     the RPC body, not in the domain
     |
  calls         Domain[Repo, Mgr]   the domain's handlers, named
     |
  daemon        server / worker     one image, two assembly points

  transactionality: a decorator, applied on mutations only.
  tx pgx.Tx never appears in a signature - the executor comes
  from the context, and the domain does not know it is in one.

Where manual assembly breaks

Now the part I'd want to read if someone else wrote this.

It fails silently, and that's a category difference

The same audit that found the hand-rolled lazy scheduler found this: a cache-invalidation consumer, fully written, registered in no daemon. Its subscription was never wired anywhere. In production, cache invalidation did not run at all.

Look at what didn't catch it:

the compiler - the package compiles perfectly; being uncalled is not an error in any language;
the unit tests - green, because they test the consumer's logic, and the logic was correct;
review - there is nothing to see. The absence is in a different file from the thing that's absent.

This is the exact failure mode a compiled container removes. In Symfony, a service that nothing uses is at worst a warning you can query for, and a service whose dependency is missing fails the container build. In hand-wired Go, "I forgot to add the line" produces a green build, green tests, and a feature that silently doesn't exist.

That asymmetry is the strongest argument against my own approach, and I'd rather state it than argue with it.

  internal/consumer/<domain>   written, correct, registered in no daemon
        |
        +-- the compiler     [passed]  the package compiles
        +-- its unit tests   [passed]  green - the logic is right
        +-- review           [passed]  the absence is in another file
        |
        v
  in production, cache invalidation did not run at all

Two composition roots drift

One image builds two binaries, server and worker, selected by a build argument. That's two assembly points. Anything both need is written twice, and the two copies diverge in the direction nobody is looking - the same class of drift as the two loggers the audit found in one service.

A container has one graph and a per-binary selection of it. Hand wiring has two graphs that happen to agree today.

The tests are a third graph

Every test that needs a real graph builds one. My answer is rigs and stands in a shared test-support package with no assertions in them - which works, and which is a third assembly point that drifts from the other two exactly the same way. Nothing about hand wiring makes this go away; it makes it your problem to name.

The threshold, said honestly

I don't have a node count where I'd switch. What I have is three signals, and any one of them is the moment:

a subtree that isn't regular - a domain whose construction genuinely differs, appearing more than twice;
lifecycle ordering by hand - things that must start in order and stop in reverse, written per binary, which is a bug factory and precisely what fx exists for;
a wiring omission reaching production twice - because the first time is a mistake and the second time is a property of the method.

What I'd do before switching is climb the ladder I use for everything else: reminder → rule → check. A reminder lives for one conversation. A rule lives while people read it. Only a check works - a structure test that walks the tree and fails the build when a consumer type exists that no daemon's assembly references. That test would have caught the unregistered consumer, it is exactly the compiled container's guarantee reproduced at a fraction of the machinery, and I want to be precise: I haven't written it. It's a plan. The rule that says "always register your consumer" is currently living in my head, which is the level of the ladder that demonstrably didn't work.

  break point              what absorbs it today            status
  -------------------------------------------------------------------
  a wiring omission        a structure test over the tree   NOT WRITTEN
  two composition roots    nothing - server and worker      DRIFTS
                           are assembled twice
  a third graph in tests   rigs and stands, no assertions   held
  an irregular subtree     one generic assembly per domain  held

The open question

So: does Go need a proper container, or is the convenience necessarily bought with implicitness?

I notice I haven't answered it consistently in my own code. I accepted declaration-driven wiring for infrastructure - the manifest is a container by any reasonable definition - and refused it for domain objects. That line isn't "explicit always". It's closer to: declare the plumbing that is identical in every service; write the graph that is the design. The manifest describes something that should be the same everywhere and boring; the domain assembly describes decisions specific to this service, and I want those in a file, in order, where a reader trips over them.

The other half of my comfort is the check. The declared half of my wiring is safe not because it's small but because drift between the declaration and the reality fails a build. That suggests the thing I actually want from a Go container isn't reflection and it isn't code generation - it's verification: something that knows what the graph is supposed to be and fails when the code disagrees. Symfony gets that by compiling the container. Wire gets it by generating real code the compiler then checks. A runtime container mostly doesn't get it at all, which is why it's the option I'm least drawn to despite it being the one closest to what I had.

Where that leaves me, for now: hand wiring plus a regular layout plus generics for the repeating subtree, and one unwritten structure test that would close the gap the container closed for free. I'm staying here because the graph being readable has been worth more to me than the graph being short - and because the one production bug this approach cost me was cheap to find once I went looking, which is not a guarantee, just a result.

Ask me again when the third binary shows up.

That's my experience and my price for it. If you've built the check I described, if you run a container in Go and it's been fine, or if you look at this differently - I'd like to hear how it's solved on your side, and what broke when you tried.

One Read Core, and the Code That Proves It

Anton Brilliantov — Tue, 15 Sep 2026 20:37:59 +0000

A generic core is easy to describe and hard to show. So here it is, with the parts I would not put in a talk.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, carving a live PHP monolith into Go services. The previous piece was about why my code ended up on type parameters at all. This one is the code itself: the core, one instantiation of it, and a consumer that uses it badly. Notes: github.com/brilliant-almazov.

Names below are neutral - entity, order, Search, Create. Shapes, counts and defects are what is in the tree.

The core: one shape for everything that has history

The service is bitemporal. Not "has an audit table" - bitemporal in the ordinary sense of the word, as a property of every domain table:

No destructive UPDATE exists in a domain table. A change is a new version row. The single permitted UPDATE is closing an interval, in the same transaction that opens the next one.
No physical DELETE exists. "Deleted" is a new version carrying a new status; "the link is gone" is a closed interval.
There are no updated_at / updated_by columns anywhere, because there is no edit in place. The header row carries created_by, the version row carries recorded_by.
Every historicised row carries two axes: valid time (valid_from / valid_to - when the fact is true in the world) and system time (recorded_at / superseded_at - when we wrote it down and when we corrected it). Mixing them is forbidden: fixing a typo must not rewrite the past.
Current state is a slice, not a table: valid_to IS NULL AND superseded_at IS NULL.

That is six rules, and every one of them is a place where a hand-written per-domain implementation goes wrong differently. Written per domain, the fourth entity's Close forgets superseded_at and nobody notices until someone asks what a value was in March.

So there is one core, and one only:

type Revisioned[T any] struct {
    spec   Spec[Header, T, Version]
    reader Reader[Query, T]
    writer Appender[T]
}

func (r Revisioned[T]) Current(ctx context.Context, key Key) (T, error)
func (r Revisioned[T]) AsOf(ctx context.Context, key Key, at time.Time) (T, error)
func (r Revisioned[T]) KnownAsOf(ctx context.Context, key Key, at, known time.Time) (T, error)
func (r Revisioned[T]) Append(ctx context.Context, key Key, next T, from time.Time) (T, error)
func (r Revisioned[T]) Correct(ctx context.Context, id int64, fixed T) (T, error)
func (r Revisioned[T]) Close(ctx context.Context, key Key, to time.Time) error

Six methods, one type parameter, and the parameter is narrower than it looks. T is the payload, not the row. The header group (identity: the Snowflake id, the owner, the code) and the version group (valid_from, valid_to, recorded_at, superseded_at, recorded_by) are identical in every domain, so they are not parameters - they are fixed positions in Spec, which is the second half of the design:

type Spec[H, P, V any] struct {
    Table   string
    Header  Columns[H]
    Payload Columns[P]
    Version Columns[V]
}

Spec[H, P, V] is what a domain hands over as data, and Revisioned[T] is what reads and writes it. The split is the whole trick: three column groups, because the three groups behave differently. Identity is written once and never again. Payload is what a new version replaces. Version columns are the only ones the core itself sets, and no domain code is allowed to touch them - if a domain could set recorded_at, the system axis would be a suggestion.

Here is Append, which is the method that carries the invariant:

func (r Revisioned[T]) Append(
    ctx context.Context, key Key, next T, from time.Time,
) (T, error) {
    var zero T

    closed, err := r.writer.CloseOpen(ctx, key, from)
    if err != nil {
        return zero, fmt.Errorf("%w: %w", ErrCloseInterval, err)
    }
    if closed == 0 && !key.First {
        return zero, ErrAborted
    }

    return r.writer.Insert(ctx, key, next, from)
}

CloseOpen is the one legal UPDATE: it stamps valid_to on the currently open interval. closed == 0 on a key that is not brand new means somebody else closed it between my read and my write, and the answer to that is ABORTED - not a retry, not an upsert. There is no ON CONFLICT anywhere in this service; writes are select-then-insert, and a taken key is ALREADY_EXISTS from the write layer rather than a constraint violation from Postgres.

The reason it is safe to concentrate this much in one function: the schema has no FK, no UNIQUE, no CHECK, no EXCLUDE. Only a primary key on the Snowflake id and ordinary indexes, some partial. Integrity lives in the write layer, in the domain invariants, and in tests. Which means the write layer had better be one piece of code and not forty - and this is exactly the seam where a type parameter earns its place, because between entity and order the only thing that differs is T.

  ONE ROW, TWO TIME AXES

  valid time — when the fact is true in the world

  ┌───────────────────────────────┐ ┌───────────────────────────────┐
  │ version 1                     │ │ version 2                     │
  │ valid_from   2026-01-01       │ │ valid_from   2026-03-01       │
  │ valid_to     2026-03-01       │ │ valid_to     NULL             │
  └───────────────────────────────┘ └───────────────────────────────┘

  system time — when we wrote it down, and when we corrected it

  ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
  │ recorded_at        │ │ superseded_at      │ │ recorded_at        │
  │ 2026-03-01         │ │ 2026-04-02         │ │ 2026-04-02         │
  │ we wrote it down   │ │ we corrected it    │ │ the correction     │
  └────────────────────┘ └────────────────────┘ └────────────────────┘

  the correction adds a row on the SYSTEM axis;
  it does not move the VALID axis

  current state is a slice, not a table
      valid_to IS NULL AND superseded_at IS NULL

What the parameter decides, and what it doesn't

The question worth asking about any generic core is how much the parameter actually absorbed. For Revisioned[T]:

The parameter decides: the scan target of a version row, the argument type of Append and Correct, the return type of all three reads, and - through Columns[P] - which columns the payload group has.

The spec decides, as data: table name, column names, the aliases, which column carries the reference to the header, which carries the label.

The domain still writes by hand: its filter type, its payload struct, its sentinel errors, and the rules that are genuinely its own. In the skeleton I designed for generation, that split is explicit per layer - the repository layer has calls.go, repository.go, revision.go, deps.go and two method files as fully mechanical, and spec.go plus three method files (header.go, code_taken.go, slug_taken.go) as hand-written bodies. Four hand-written files per domain, and the fourth is the interesting one: code_taken.go is where "this key is already used" is defined, and no core can guess that.

  ┌──────────────────────┐ ┌──────────────────────┐ ┌────────────────────┐
  │ THE TYPE PARAMETER   │ │ THE SPEC DECIDES,    │ │ THE DOMAIN STILL   │
  │ DECIDES              │ │ AS DATA              │ │ WRITES BY HAND     │
  │                      │ │                      │ │                    │
  │ scan target of a     │ │ table name           │ │ the filter type    │
  │ version row          │ │ column names and     │ │ the payload struct │
  │ argument of Append   │ │ aliases              │ │ the sentinel       │
  │ and Correct          │ │ the reference column │ │ errors             │
  │ return type of all   │ │ the label column     │ │ what counts as a   │
  │ three reads          │ │                      │ │ taken key          │
  │ which columns the    │ │                      │ │                    │
  │ payload has          │ │                      │ │                    │
  │                      │ │                      │ │                    │
  │ Revisioned[T]        │ │ Spec[H, P, V]        │ │ 4 files per domain │
  └──────────────────────┘ └──────────────────────┘ └────────────────────┘

  the fourth hand-written file is the interesting one
      code_taken.go — no core can guess what makes a key already used

The ports around it are one interface per file, each with one method, each generic over the same T:

type Viewer[T any] interface {
    Current(ctx context.Context, key Key) (T, error)
}

type Historian[T any] interface {
    AsOf(ctx context.Context, key Key, at time.Time) (T, error)
    KnownAsOf(ctx context.Context, key Key, at, known time.Time) (T, error)
}

There are eleven of these - Scoped, Self, Creator, Updater, Corrector, Archiver, Viewer, Finder, Locator, Searcher, Historian - so a consumer depends on the two methods it uses rather than on a struct with six. Revisioned[T] satisfies Viewer[T] and Historian[T] without knowing either exists.

Instantiation: a domain is a declaration

Adding a domain does not create a new package of logic. It creates a spec, a handful of genuinely domain-specific files, and a set of type declarations:

package entity

type Repo = repository.Base[Row, Filter, Patch]
type Mgr = manager.Base[Row, Create, Patch]

var Domain = domain.New(domain.Input[Repo, Mgr]{
    Spec:      Spec,
    Events:    Events,
    Sentinels: Errors,
})

domain.New returns Domain[Repo, Mgr], built by Builder[Repo, Mgr], and the inputs are typed the same way (ManagerInput[Repo], HandlerInput[Repo, Mgr]). Then the assembly file, which is the only place in a domain where you can see the shape of the whole thing at once:

func (d Domain[Repo, Mgr]) Calls() Calls {
    return Calls{
        Get:     method.Get(d.repo),
        Search:  method.Search(d.repo),
        Walk:    method.Walk(d.repo),
        Create:  tx.On(method.Create(d.mgr)),
        Correct: tx.On(method.Correct(d.mgr)),
        Archive: tx.On(method.Archive(d.mgr)),
    }
}

method.Get, method.Search, method.Create are not this domain's code. They are 3 of 20 generic RPC methods that hold every request body in the service: archive, attach, close, correct, create, create_batch, detach, find_all_by_ids, get, get_by_key, list_revisions, lookup, lookup_pair, move, mutation, save, search, set, update, walk. Each has a single execution method, Handle(ctx, req). A domain's handler package contains no request flow at all - a struct with a deps field, a constructor, and a Call() returning the lambda the transport wires in.

tx.On is the transaction decorator, applied only on mutations, with the executor taken from the context - tx pgx.Tx in a signature is banned, so domain code cannot know it is inside a transaction.

Why a declaration rather than a package - the numbers make the case better than the argument does. The service is 2733 non-generated .go files across 252 packages, averaging 39 lines. Files over 100 lines: 44, of which 2 are not tests (105 and 102 lines). It grows by files and packages, not by files getting fatter, and that only holds while the per-domain content stays a spec plus a few honest files.

Between tags, code and tests move together:

Tag	Code	Tests	Tests/code	Files	Packages
v1.4.0	50755	62986	1.24	1300	175
v1.8.0	58372	72758	1.25	1476	205
HEAD	61411	76468	1.25	1540	252

The ratio sits at 1.25 and hasn't dropped below 1.14 since v1.0.0. That is what a load-bearing core does to a test suite: tests pile onto the one thing everything depends on instead of spreading thin over N copies.

  ┌──────────────────────────────────────────────────────────────────────┐
  │ THE DOMAIN SUPPLIES                                                  │
  │    Spec — handed over as data                                        │
  │    4 hand-written files                                              │
  │    type declarations                                                 │
  └──────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
  ┌──────────────────────────────────────────────────────────────────────┐
  │ THE DOMAIN ASSEMBLES — one file, the whole shape visible in it       │
  │    Calls{ Get, Search, Walk }                                        │
  │    Calls{ Create, Correct, Archive }    wrapped in tx.On             │
  └──────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
  ┌──────────────────────────────────────────────────────────────────────┐
  │ EVERY DOMAIN SHARES                                                  │
  │    20 generic RPC methods, one Handle(ctx, req) each                 │
  │    archive · attach · close · correct · create · create_batch ·      │
  │    detach · find_all_by_ids · get · get_by_key · list_revisions ·    │
  │    lookup · lookup_pair · move · mutation · save · search · set ·    │
  │    update · walk                                                     │
  └──────────────────────────────────────────────────────────────────────┘

  2733 files    252 packages    39 lines average
  44 files over 100 lines, 2 of them not tests

The consumer, exactly as it is

In August 2026 I audited my own service for one specific thing: code that re-implements something the shared platform library already gives me - startup and shutdown, migrations, audit, the outbox runner, the messaging driver, transactions, paging, an LRU cache with TTL and metrics, bulk insert, typed message dispatch, test infrastructure. The audit found ten places where the service had written its own version anyway. Four are in one consumer, and here is roughly what it looks like:

func (c Invalidation) Handle(ctx context.Context, d amqp.Delivery) error {
    var msg struct {
        Type    string `json:"type"`
        Subject struct {
            Type string `json:"type"`
            ID   string `json:"id"`
        } `json:"subject"`
    }
    if err := json.Unmarshal(d.Body, &msg); err != nil {
        return fmt.Errorf("decode invalidation: %w", err)
    }

    if c.seen.Has(msg.Subject.ID) {
        return nil
    }
    c.seen.Add(msg.Subject.ID)

    c.cache.Drop(msg.Subject.Type, msg.Subject.ID)
    return nil
}

Four defects, in ascending order of embarrassment.

One: the body is decoded by hand. The platform has typed dispatch with a serialiser registry - you register a codec per message type and the handler receives a typed value. It is unusable here, and not because I didn't know about it: the publisher sends with empty headers, so the receiver has nothing to select a codec by. The defect is upstream of the code you are reading, which is what makes it expensive - fixing the consumer alone changes nothing.

Two: the deduplication is a hand-written ring of 1024 ids. A fixed array, a mutex, a write cursor. No TTL, no capacity policy worth the name, no metrics - so when it drops a message it shouldn't have, nothing anywhere records that it happened. Sitting in the platform, imported by this same service, is a cache with exactly TTL, capacity and metrics. The audit also found three more hand-written caches in the service, all map + RWMutex, all without TTL, capacity or metrics.

Three: the subscription declares no redelivery limit, no backoff and no dead-letter queue, and that fmt.Errorf on decode failure is returned as an ordinary error. The driver's contract for an ordinary error is redelivery. So a message that cannot be decoded is redelivered, fails to decode, is redelivered - a poison loop, built out of two individually reasonable lines.

Four, and this is the one worth the article: this consumer is not registered in any daemon. The subscription list is assembled in one file per daemon, and the constructor for this one is called from nowhere. Which means cache invalidation has never run in production. Not "runs badly" - has never run.

Nothing caught it. The package compiles, because an unused exported constructor is not an error in Go. Its unit tests are green, because they construct it directly and assert behaviour that is genuinely correct. Coverage is 86.7% and this code is inside that number. Every signal was green about a component wired to nothing.

That is the honest limit of a well-typed core: the type system checks the shape of a call, and has nothing to say about a call that is never made. All the parameterisation above buys me correctness within a path. It buys me nothing at all about which paths exist.

Why is it still like this? Because fixing it is not one commit: headers on publish change the publisher and the message contract, typed dispatch changes the handler, redelivery limits and a dead-letter queue change the subscription declaration, and the ring is deleted only after the platform cache is wired in. That work is a set of prompts sitting in a queue - written, not executed.

  ┌──────────────────────────────────────────────────────────────────┐
  │ 1  the body is decoded by hand                                   │
  │    json.Unmarshal in the handler                                 │
  │    the publisher sends EMPTY HEADERS — typed dispatch cannot     │
  │    select a codec, so the fix is upstream of this code           │
  ├──────────────────────────────────────────────────────────────────┤
  │ 2  the deduplication is a hand-written ring of 1024 ids          │
  │    a fixed array, a mutex, a write cursor                        │
  │    no TTL, no capacity policy, no metrics — a wrong drop is      │
  │    recorded nowhere.  Three more hand-written caches exist.      │
  ├──────────────────────────────────────────────────────────────────┤
  │ 3  no redelivery limit, no backoff, no dead-letter queue         │
  │    an undecodable message is redelivered, fails, is redelivered  │
  │    a poison loop, built out of two individually reasonable lines │
  ├──────────────────────────────────────────────────────────────────┤
  │ 4  the constructor is called from nowhere                        │
  │    registered in NO daemon — cache invalidation has NEVER run    │
  │    in production                                                 │
  └──────────────────────────────────────────────────────────────────┘

  and every signal about it was green
      compiles        unit tests pass        coverage 86.7%

  the type system checks the shape of a call;
  it says nothing about a call that is never made

Could this have been declarative?

This is the part I have no answer to, left open rather than dressed up as a conclusion.

Everything above is code that builds a thing from a description: Spec[H, P, V] is a description, Calls() is a list, a domain's package is six declarations and four hand-written files. The obvious next step is to write only the description.

I have a design for that: a generator taking two inputs - a YAML description of the domain (name and plural, Go types, whether it is owner-scoped, whether it has a slug, header table, revision table, reference column, label column, table aliases, payload columns with Go type, SQL type, nullability and comment, domain event types, the set of sentinel errors, the number of the first migration) and the .proto descriptor (full gRPC service name, RPCs with request and response types, the entity message, the batch messages). Neither input covers the skeleton alone. Rendering is string concatenation with token replacement, not a template engine, and each .go output goes through the formatter. Generated files carry a DO NOT EDIT header and a drift check that fails the build if the tree and the generator disagree.

It is 12 iterations of design, and it is not written. So this section is a question, not a report.

The case for: the description is shorter than the code, it is checkable, and drift becomes a build failure instead of a code review. And I have one place where declarative already won unambiguously - categories. Anything that is a category (a vertical, a type, a status, a binding level) is a dictionary row plus a string code, not an enum. A new attribute, a new dictionary entry, a new binding level is added as data: no schema migration, no contract change, no rollout. Enums survive only for things that change together with code - a value's state, its source, its type, an entity's status.

The case against is the one I keep bumping into: declarative doesn't remove complexity, it moves it into the description and into the validation of the description. The YAML above has around fifteen fields per domain, several of which are only meaningful in combination. Every one of those combinations needs a rule, an error message, and a test - which is code, just code you can't step through with a debugger. And the failure mode changes character: a wrong Go declaration is a compile error on a line; a wrong YAML field is a generated file that compiles and does the wrong thing.

There is a second cost specific to how I work: most of the code in this service is written by an agent from a written spec. A declarative layer means the agent writes the description instead of the code - fewer signatures to anchor on, and no compiler telling it immediately that the shape is wrong. An early prompt set burned about 350,000 tokens per iteration because the executor went looking for context it wasn't given, and a sparse description is an invitation to exactly that.

So: probably yes, this could have been meaningfully more declarative. Whether it should be, I don't know, and the honest reason is that I've never paid the second bill - the one for validating the description - on this codebase.

  ┌────────────────────────────────┐ ┌──────────────────────────────────┐
  │ TODAY: A GO DECLARATION        │ │ DESCRIBED: YAML + PROTO          │
  │                                │ │                                  │
  │ Spec, four hand-written files, │ │ 12 iterations designed,          │
  │ aliases                        │ │ NOT WRITTEN                      │
  │ checked by the compiler at     │ │ shorter, and drift fails the     │
  │ the call site                  │ │ build                            │
  │ a wrong field does not build   │ │ ~15 fields, meaningful only in   │
  │ more lines than the            │ │ combination                      │
  │ description would be           │ │ a wrong field compiles and       │
  │                                │ │ misbehaves                       │
  │                                │ │                                  │
  │ domain.New(domain.Input[...])  │ │ not written                      │
  └────────────────────────────────┘ └──────────────────────────────────┘

  one place where the declarative form already won, without argument
      a category is a dictionary row — added as data,
      no migration, no contract change

  declarative does not remove the complexity;
  it moves it into validating the description

What the cores cost me

Six of them.

Revisioned[T] reads as if T were the row. It isn't - T is the payload. Everyone who instantiates it for the first time gets that wrong, and the compiler's message names the core's parameters, not theirs - so one naming decision, made once, costs a briefing on every new domain.

Spec[H, P, V] is three letters that require a briefing. Header, payload, version. Once you know it, the signature is a compressed statement of the whole table model. Before you know it, it is noise, and there is nowhere in the code to look it up, because there are no comments in .go files - the meaning has to live in names and tests.

Twenty generic RPC methods means twenty places nothing can be domain-specific. When one of them needs a behaviour a single domain wants, the pressure is to add a flag - and a flag on a generic method is a second implementation hiding inside the first. Saying no costs a longer conversation every time than saying yes would.

The ban on a domain-local copy is enforced, and enforcement has a bill. A guard test holds the invariant that the row-loop primitives appear in exactly one package; a tool hook blocks writing a duplicate of an existing generic. When an executor hits that block mid-task, it stops and starts hunting for why - one of the recurring token sinks in my prompt sets. The check is worth it; "add a linter rule" is just usually costed as free, and it isn't.

Integrity moved from the database into the code, which is a direct consequence of one core owning writes. No foreign keys, no unique constraints. Uniqueness is a read-then-write in the write layer returning ALREADY_EXISTS; a lost interval race is ABORTED. Both are correct and both are mine to keep correct. A UNIQUE index would have been checked by a system with far better testing than mine.

And the boundary, which is the important one: this pays off because every table in this service has the same three column groups and the same two time axes. Take away the historicity and half of Revisioned[T] is ceremony around a plain read. Take away the rigid package layout - component type first, domain nested - and instantiation stops being a declaration and becomes a per-domain wiring exercise, which is a framework being maintained rather than a parameter being used. The core isn't the achievement. The uniformity that made a core possible is, and it was decided long before any of this code existed.

That's the code and the bill. If you want a specific piece of it - the write path with the interval close, the twenty generic methods and how a request finds one, or the consumer rewrite once the publisher sends headers - tell me which and I'll write that one next. And if you've built the declarative version of this and know what validating the description actually costs: I'd like to hear how it's solved on your side, and what broke when you tried.

Life Before Generics

Anton Brilliantov — Tue, 15 Sep 2026 20:35:55 +0000

The type parameter didn't make my code clever. It moved a class of checking out of review and into the compiler - and it charged me for it.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This one is personal history plus the code it produced: where I learned to live without generics, what I built instead, and what a service looks like now that I don't have to. Notes: github.com/brilliant-almazov.

As always: this is what I do on one codebase, with the costs I actually pay. Not advice for yours.

Where I come from

PHP has no generics. Not "has them awkwardly" - has none. There is no syntax for a type parameter, and there is no runtime that could check one if there were.

So we suffered a little, and then we solved it differently. Four tools, in roughly the order you reach for them:

Interfaces. The thing you pass in is described by what it can do, and the concrete type is nobody's business.
Base classes. The shared behaviour goes into an abstract parent; each child fills in the parts that differ. Inheritance stands in for parameterisation.
Arrays of mixed things. A collection is array, and what's inside it is a matter of convention.
Duck typing at the edges. At the boundary you accept what arrives and check it yourself.

And then, holding all of it together: a lot of discipline. A repository looked like this - and I want to be fair to it, because it worked:

abstract class AbstractRepository
{
    /** @return object[] */
    public function findBy(array $criteria): array
    {
        // one implementation, shared by everything
    }
}

final class OrderRepository extends AbstractRepository
{
    /** @return Order[] */
    public function findBy(array $criteria): array
    {
        return parent::findBy($criteria);
    }
}

Look at what is carrying the type in that snippet. It isn't the signature - the signature says array, which is to say "anything". It's the docblock. @return Order[] is the type parameter, written in a comment, enforced by a static analyser that runs in CI if someone set one up, and by nothing at all at runtime.

The ecosystem did eventually build the missing feature in comments. Psalm and PHPStan understand @template, and you can write something that reads almost like the real thing:

/**
 * @template T of object
 */
abstract class AbstractRepository
{
    /**
     * @param class-string<T> $class
     * @return list<T>
     */
    public function findBy(string $class, array $criteria): array { /* ... */ }
}

I used this, I liked it, and I want to be precise about what it is and isn't. It is a real type system - it catches real mistakes, and a codebase at max analyser level is a genuinely different place to work. It is not the compiler:

it runs where someone installed it, at the level someone configured, with the baseline someone generated when the errors got inconvenient;
it describes the code rather than constraining it, so a @return list<Order> above a method that returns list<Entity> is a lie the runtime is perfectly happy to execute;
and it disappears the moment a value crosses a boundary the annotations don't cover - a decoded JSON body, a row out of the database, a mixed from a queue.

The failure mode is not "the analyser is wrong". It's that the type lives in a place a person can edit without the program changing, so it drifts, and it drifts silently.

  four substitutes for a type parameter, in a language that has none

  ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ ┌──────────────┐
  │ interfaces     │ │ base classes   │ │ arrays of    │ │ duck typing  │
  │                │ │                │ │ mixed things │ │ at the edges │
  │ interface      │ │ abstract class │ │ array        │ │ is_a()       │
  └────────────────┘ └────────────────┘ └──────────────┘ └──────────────┘

  and one thing holding all four up

  ┌────────────────────────┐
  │       DISCIPLINE       │
  └────────────────────────┘
       │              │
       ▼              ▼
    review          tests

  the compiler is not on this diagram

That is the whole cost, and it's worth stating plainly rather than as a complaint:

The compiler could not help, so the checking moved into review and into tests.

Both of those are real mechanisms and both of them work - they just cost a person's attention every time, forever, on every change. A wrong type in an array is caught by a test if someone wrote that test, or by a reviewer if someone was looking. Neither is a property of the code. Both are properties of the team's current level of care, which is not a stable quantity.

The second cost is subtler and I only noticed it after leaving: the substitutes are not free of their own gravity. Base classes accumulate. What starts as "shared read behaviour" becomes a parent with eleven protected methods, four of which two children override in incompatible ways. The inheritance chain becomes the place where the polymorphism lives, and it is much harder to delete than a type parameter is. You can remove a type parameter in an afternoon. Removing a base class is a project with a name.

Go before generics

Then I came to Go, which at the time didn't have generics either. Different language, same missing thing, and - this is the part that surprised me - a worse set of substitutes, because Go has neither inheritance nor a static-analyser culture that reads comments.

There were four honest options and everybody knew all four.

Option one: interface{} and a type assertion. You accept anything, and at the point of use you assert what you actually have.

func collect(rows pgx.Rows, scan func(pgx.Rows) (interface{}, error)) ([]interface{}, error)

Every caller then unpacks the result:

items, err := collect(rows, scanOrder)
orders := make([]Order, 0, len(items))
for _, item := range items {
    order, ok := item.(Order)
    if !ok {
        return nil, ErrBadType
    }
    orders = append(orders, order)
}

That is the PHP docblock again, except now the failure is at runtime and the unpacking is code you have to write, review and test. You didn't remove the copy - you moved it, and made it longer. There's a second bill people forget: every element goes through an interface box on the way in and a type assertion on the way out, so a hot read path pays allocation and indirection for the privilege of being untyped.

Option two: reflection. You can write the loop once and fill a *[]Order handed in as any, matching columns to struct fields at runtime. It works - several well-known libraries are built on it. It also moves every mistake to runtime, makes the code unreadable in exactly the place you most want to read it, and costs enough per row that you notice on a large result set.

Option three: code generation. Write the shape once as a template, generate a typed copy per entity, commit the output. It genuinely works, and the typed result is exactly what you wanted. What you buy it with: a build step, generated files in the repository, a DO NOT EDIT header that people edit anyway, and debugging that happens in a file nobody wrote.

Option four - the honest one: write it once per type. No cleverness, no runtime failure mode, no build step. Just the same function again, with Order where Entity used to be.

Most of my Go, and most of the Go I read, was option four. It reads fine. Here is one read path, written the honest way:

func (r *OrderRepository) Search(ctx context.Context, f OrderFilter) ([]Order, error) {
    rows, err := r.pool.Query(ctx, orderSearchSql, f.TenantId, f.Cursor, f.Limit)
    if err != nil {
        return nil, fmt.Errorf("query orders: %w", err)
    }
    defer rows.Close()

    out := make([]Order, 0, f.Limit)
    for rows.Next() {
        var o Order
        if err := rows.Scan(&o.ID, &o.TenantId, &o.Code, &o.CreatedAt); err != nil {
            return nil, fmt.Errorf("scan order: %w", err)
        }
        out = append(out, o)
    }
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("iterate orders: %w", err)
    }
    return out, nil
}

Nothing is wrong with that function. It is clear, it handles its errors, errors.Is will still match through the wraps. The problem is that there is another one exactly like it for Entity, and another for Account, and the fourth one is being written right now in a branch you haven't seen.

And the copies rot at different speeds. That is the part that costs money. One of them learns to call rows.Close() on the early-return path; the others don't. One of them starts checking rows.Err() after the loop; two of them still treat "zero rows" and "the connection died mid-iteration" as the same answer. You don't find that by reading - all four look right in isolation. You find it when a query returns eleven rows out of a thousand and nothing anywhere says why.

  ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
  │ interface{} +        │ │ go:generate          │ │ one copy per type    │
  │ assertion            │ │                      │ │                      │
  │                      │ │                      │ │                      │
  │ GIVES                │ │ GIVES                │ │ GIVES                │
  │ one implementation   │ │ typed output         │ │ nothing to explain   │
  │                      │ │                      │ │                      │
  │ CHARGES              │ │ CHARGES              │ │ CHARGES              │
  │ runtime failure,     │ │ a build step and     │ │ the same function    │
  │ unpacking at every   │ │ files nobody wrote   │ │ again, and again     │
  │ caller               │ │                      │ │                      │
  └──────────────────────┘ └──────────────────────┘ └──────────────────────┘
                                                     the one most Go
                                                     actually picked

What the copies actually differ in

This isn't a hypothetical for me. In August 2026 I ran an audit over my own service looking for hand-written ways to read rows out of Postgres. It found 44 copies of four forms:

Form	Copies
many-row loop (`for rows.Next()` → `rows.Err()` → wrap the error)	18
single row	6
`COUNT(*)` counter	8
existence probe (one `rows.Next()`)	12

Then I lined them up next to each other and looked at what was actually different between any two of them. Two things:

the result type;
the wording of the error wrapper.

Twelve of the forty-four differed only in the second one. Twelve functions, identical down to the loop structure, whose entire distinguishing content was that one said scan order and another said scanning entity row.

That detail sounds like a joke about naming. It isn't. Error text is an interface: something upstream matches on it, a dashboard groups by it, a person searches the logs for it. Twelve spellings of one failure means the log query that finds the incident finds a third of it.

A thing that differs from its neighbour only in a type - that is not a family of functions. That is one function and a parameter, typed out by hand forty-four times. The copies existed because at the time there was no way to say it, and then they kept existing because by the time there was, nobody went back.

  44 copies of four forms

  many-row loop     ██████████████████  18
  single row        ███████              6
  COUNT(*) counter  █████████            8
  existence probe   ████████████        12
                                        ──
                                        44

  of those 44, TWELVE differ only in the wording of the error wrapper

  the result type and the error text are the whole difference

How I write a service now

So here is the current shape. It's the point of this piece, and every part of it is a place where the type parameter sits.

A domain in my service is six things. All names below are neutral (entity, order) - the shapes are real.

1. The entity is the typed unit

Everything below is parameterised over it. It's a plain struct plus its identifiers - no framework, no base type, no marker interface, no embedded Model. It's the thing the type parameter is.

package entity

type Row struct {
    ID        int64
    TenantId  int64
    Code      string
    Revision  int32
    CreatedAt time.Time
}

That it's a plain struct matters more than it looks. The moment an entity has to implement something to participate, the constraint stops describing data and starts describing a framework, and every new domain pays an initiation fee.

2. The repository holds the read operations, generic over the entity

The read side is where the copy-paste lived, so it's where the cores are. Three small interfaces carry the whole thing:

// what can execute a query — a pool, or a transaction, and nothing else knows which
type Executor interface {
    Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
}

// how a typed input becomes SQL
type Statement[In any] interface {
    Build(in In) (sql string, args []any, err error)
}

// how one row becomes a typed value
type Scanner[Out any] interface {
    Scan(rows pgx.Rows) (Out, error)
}

And the core those three make possible - this is the one that forty-four functions collapsed onto:

type Reader[In, Out any] struct {
    executor  Executor
    statement Statement[In]
    scanner   Scanner[Out]
}

func (r Reader[In, Out]) Query(ctx context.Context, in In) ([]Out, error) {
    sql, args, err := r.statement.Build(in)
    if err != nil {
        return nil, fmt.Errorf("%w: %w", ErrStatement, err)
    }

    rows, err := r.executor.Query(ctx, sql, args...)
    if err != nil {
        return nil, fmt.Errorf("%w: %w", ErrQuery, err)
    }
    defer rows.Close()

    out := make([]Out, 0)
    for rows.Next() {
        item, err := r.scanner.Scan(rows)
        if err != nil {
            return nil, fmt.Errorf("%w: %w", ErrScan, err)
        }
        out = append(out, item)
    }
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("%w: %w", ErrIterate, err)
    }
    return out, nil
}

Four sentinels - ErrStatement, ErrQuery, ErrScan, ErrIterate - and every caller everywhere matches them with errors.Is through however many wraps sit on top. That's the twelve spellings problem closed by construction rather than by a naming convention.

The other three forms are the same core with a different tail: one row, a count, an existence probe. Each is ten lines, each exists once.

A domain's read path becomes a declaration:

var searchOrders = rows.NewReader[order.Filter, order.Row](
    executor,
    order.SearchStatement{},
    order.RowScanner{},
)

Three lines instead of twenty-two, and - this matters more - the loop, the close, the rows.Err() check and the error wording are now in one place, so twelve functions can no longer disagree about how to phrase the same failure or about whether to check the iteration error at all.

Above the reader sits the part a domain actually configures. Spec is the description of a table: what the header row is, what the payload is, how the version is carried.

type Spec[H, P, V any] struct {
    Table   string
    Header  Columns[H]   // identity: id, tenant, code
    Payload Columns[P]   // the changing part
    Version Columns[V]   // revision, valid-from, valid-to
}

Three parameters look like a lot until you notice they're the three groups every table in this service actually has, and that separating them is what lets one core do keyset pagination, optimistic locking and partial updates without a domain writing any of them.

Paging is generic too, and it's the sort of type that must exist exactly once in a codebase:

type Page[T any] struct {
    Items         []T
    NextPageToken string
}

I've seen the entity-shaped version of this three times in one repository under three names. A page is not about orders; it is about pages.

3. The manager holds the write operations, generic over the entity

One layer, one job: writes, including find-or-create. Repository reads, manager writes, and there is no third thing - no store, no service, no dao. If a manager needs to read, it calls the repository rather than growing its own SQL.

type Manager[E, C, U any] struct {
    executor Executor
    spec     Spec[E, C, U]
    reader   Reader[Key[E], E]
}

func (m Manager[E, C, U]) FindOrCreate(ctx context.Context, key Key[E], create C) (E, error)
func (m Manager[E, C, U]) Update(ctx context.Context, key Key[E], patch U) (E, error)
func (m Manager[E, C, U]) Archive(ctx context.Context, key Key[E]) error

FindOrCreate is the one worth pausing on, because it's where a copy-per-domain hurts most. It is a select, then a conditional insert, then a re-read on conflict - and every hand-written instance of it gets the conflict branch subtly differently. Written once, the race is thought about once.

Note what is not in these signatures: no tx pgx.Tx. The executor is a field, and a transaction-scoped instance is a new value, not a new argument:

func (m Manager[E, C, U]) WithTx(tx pgx.Tx) Manager[E, C, U] {
    m.executor = tx
    return m
}

4. The query builder is declarative

This is the piece that actually made the read side stop being copy-paste, and it's easy to under-sell. All SQL in the service goes through a builder; raw SQL in Go is forbidden, with migration DDL and test fixtures as the only exemptions.

The point of the builder isn't string safety. It's that you describe what you want, not how to assemble it:

spec := query.
    Select[order.Row](order.Columns...).
    From(order.Table).
    Where(order.TenantEq, order.NotArchived).
    OrderBy(order.CreatedAtDesc).
    Page(cursor)

Compare that with the alternative, which is a function that concatenates a WHERE clause conditionally and gets the placeholder numbering right by hand. Written once, that function is fine. Written once per domain, it is the same bug eight times - and the bug is always the same bug, some variation of a filter that silently didn't apply. Silently is the operative word: a filter that doesn't apply returns more rows, and more rows look like data, not like a failure.

Because the builder is declarative, the reader above can be generic at all. Statement[In] doesn't need to know how a filter becomes SQL; it needs a description it can turn into one.

5. Processors plug into the builder instead of being baked into each query

A read is rarely just "select these columns". It's "select these columns, apply whatever filters the caller sent, sort by whatever they asked for, clamp the page size". Every one of those is a transformation of the query, and every one of them used to be an if inside a hand-written method.

Now they're values:

type Processor[Q any] interface {
    Apply(q Q) Q
}

type Chain[Q any] []Processor[Q]

func (c Chain[Q]) Apply(q Q) Q {
    for _, p := range c {
        q = p.Apply(q)
    }
    return q
}

A read declares which processors it runs and in what order; the builder applies them. Adding a new filter to a domain is adding a processor to a list, not editing a query. Adding a sort that four domains need is writing one processor, not four ORDER BY branches.

The rule that keeps this from becoming its own mess: a processor is generic over the query, not over the domain. The moment I see OrderStatusProcessor and EntityStatusProcessor with the same body, that's the same forty-four-copies smell in a new costume.

6. The gRPC handler may or may not be transactional - and that's declared, not implemented

Transactions sit outside the read/write split entirely: a decorator applied from the outside, only on mutations, with the executor taken from the context. tx pgx.Tx in a signature is forbidden, and the domain code never learns it is running inside a transaction.

func Transactional[Req, Res any](pool *pgxpool.Pool, next Handler[Req, Res]) Handler[Req, Res] {
    return HandlerFunc[Req, Res](func(ctx context.Context, req Req) (Res, error) {
        var zero Res
        tx, err := pool.Begin(ctx)
        if err != nil {
            return zero, fmt.Errorf("%w: %w", ErrBegin, err)
        }
        defer tx.Rollback(ctx)

        res, err := next.Handle(WithExecutor(ctx, tx), req)
        if err != nil {
            return zero, err
        }
        if err := tx.Commit(ctx); err != nil {
            return zero, fmt.Errorf("%w: %w", ErrCommit, err)
        }
        return res, nil
    })
}

So "is this call transactional?" is a property declared where the domain's calls are assembled, alongside the handler, not a thing re-implemented per method:

func (d Domain) Calls() Calls {
    return Calls{
        Search: method.Search(d.repo),                          // read: no decorator
        Create: Transactional(d.pool, method.Create(d.manager)), // write: wrapped here
    }
}

The method body is the same code either way. That's the whole benefit: the decision is visible in one file per domain, and a method cannot quietly acquire or lose transactionality by someone editing its body.

The bodies themselves aren't in the domain at all. The RPC flow lives in one of 20 generic methods, each with a single Handle(ctx, req). What the domain's handler package contains is assembly: a type with a deps field, a constructor, and a Call() that returns the lambda the transport wires in.

  ONE DOMAIN, SIX PLACES — and the column that says what varies

  ┌──────────────────────────────────────────────────────────┐ ┌───────┐
  │ entity          Order                                    │ │  [T]  │
  │ manager         Manager[E, C, U]      writes             │ │  [T]  │
  │ repository      Reader[In, Out]       reads              │ │  [T]  │
  │ query builder   Select[Row]()         declarative        │ │  [Q]  │
  │ processors      Processor[Q]          plugged in         │ │  [Q]  │
  │ handler         Call()                transactionality   │ │  [T]  │
  │                                       declared, not      │ │       │
  │                                       implemented        │ │       │
  └──────────────────────────────────────────────────────────┘ └───────┘

  [T]  the domain's entity — the type parameter
  [Q]  the query — generic over the query, not over the domain

How I test a core that everything depends on

A generic core is load-bearing by definition, so the test shape changes with it. Three things I do that I didn't do when the code was forty-four copies.

Test the core once, across instantiations. The reader's test doesn't test orders. It instantiates the reader over two deliberately different types - one with a nullable column, one without - and runs the same table of cases: zero rows, one row, many rows, a scan failure mid-iteration, an iteration error after the last row, a cancelled context. Each of those cases used to be untested in forty-three places and tested in one.

Assert the failure paths that the copies used to get wrong, and assert them by identity rather than by string:

_, err := reader.Query(ctx, filter)
require.ErrorIs(t, err, rows.ErrIterate)

Hold the invariant with a test, not with a review comment. The closing condition for the whole forty-four migration is mechanical: for rows.Next(), rows.Err(), rows.Close() and QueryRow( may appear in exactly one package in the tree. That's a test that walks the source and fails the build if a forty-fifth copy appears - which is the only form of "we agreed not to do that" that survives a busy week.

And because the core is on every read path, it carries the benchmark weight too: allocations per row are a property of one function now, so measuring it is worth doing and comparing it release to release is meaningful.

  ┌────────────────────────────────────────────────────────────────┐
  │ 1  one table of cases, run across TWO instantiations           │
  │    zero rows · one row · many rows · a scan failure mid-loop · │
  │    an iteration error after the last row · a cancelled context │
  ├────────────────────────────────────────────────────────────────┤
  │ 2  assert the failure by IDENTITY, not by string               │
  │    require.ErrorIs(t, err, rows.ErrIterate)                    │
  ├────────────────────────────────────────────────────────────────┤
  │ 3  a guard test walks the source and fails the build           │
  │    for rows.Next() · rows.Err() · rows.Close() · QueryRow(     │
  │    allowed in EXACTLY ONE package                              │
  └────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
                        one generic core

  the same table used to be untested in forty-three places

Why the type parameter is the right seam

Everything above only works because of a layout decision I made earlier, and the two are the same idea seen twice.

Packages are laid out by component type first, with the domain as a nested package:

internal/repository/entity
internal/repository/order
internal/manager/entity
internal/manager/order
internal/model/entity
internal/model/order

Not the inverse - internal/domain/<area>/repository, one package per business area holding every role.

Put the two layouts next to each other and ask what stays the same as you move from entity to order. In the type-first layout, the answer is: everything except the type. The read path for orders is the read path for entities with Order substituted. There is a single thing that varies, it has a name, and the language now has a way to spell it.

Between two domains' read paths	Differs?
the loop that walks the rows	no
the error wrapping and its wording	no
cursor handling and page clamping	no
how a filter becomes SQL	no
the table, columns and their scan targets	yes - the spec
the entity type	yes - the type parameter

Two rows on the right. One of them is data - a spec the domain hands over. The other is the parameter. Everything else is one core with N instantiations.

The rule I hold myself to is one line: if two things differ only in a type parameter, they are one generic. A domain-local copy sitting next to an existing generic is forbidden, and that ban is held by the guard test above rather than by review etiquette.

The practical consequence is the one I care about: adding a domain is declaring a type, not writing a package. It's a spec, a handful of files that carry genuinely domain-specific rules, and instantiations of everything else.

The effect is visible in the numbers

None of this is a claim about elegance. Over the tag history of the service, generated code excluded:

Tag	Code	Tests	Tests/code	Files	Packages	Average file
v0.4.0	28095	31952	1.14	640	85	43
v1.0.0	25097	35368	1.41	683	94	36
v1.1.0	29443	36272	1.23	804	109	36

At v1.0.0, lines of code dropped by roughly three thousand while test lines grew - that step is repeated domain files going into generic cores. The tests-to-code ratio went 1.14 → 1.41 and hasn't been below 1.14 since.

The other number worth reading: the service is 2733 files across 252 packages, averaging 39 lines. It grows by files and packages, not by files getting fatter - which is what you'd expect when the shared behaviour has somewhere to live.

  each █ = 1000 lines above a 20000 baseline

            v0.4.0            v1.0.0            v1.1.0
  tests     ████████████      ███████████████   ████████████████
            31952             35368             36272
  code      ████████          █████             █████████
            28095             25097             29443
                              ▲
                              └── the dip: 28095 ──▶ 25097

  tests/code   1.14   ──▶   1.41   ──▶   1.23

  the dip is repeated domain files going into generic cores

The honest cost

Generics are not free, and I'd rather list the bill than pretend the migration was a clean win.

Signatures get harder to read. Reader[In, Out] is fine. Spec[H, P, V] is three single letters that mean header, payload and version, and you have to know that. A generic core's signature is a compressed description of a design - which is efficient once you hold the design, and opaque before you do. New readers hit it before they hit anything friendly.

Error messages get worse. When an instantiation doesn't satisfy a constraint, the compiler points at the core, not at the line you wrote. You get told something about a type set, in terms of the core's parameter names, and you have to walk back to your own call site yourself. In the concrete, copy-per-type world, the error was on the line with the mistake.

Constraints leak into every caller. This is the one I underestimated. The moment a core takes [In, Out any], every wrapper around it takes them too, and every wrapper around that. Type parameters propagate outward through signatures until something concrete stops them. Pick the stopping point deliberately - mine is the domain's assembly file, where Domain[Repo, Mgr] becomes a plain Domain - or you'll find the parameters have reached the transport layer, and a gRPC handler is arguing about type sets.

  type parameters propagate OUTWARD until something concrete stops them

  ┌──────────────────────────────────────────────────────────────┐
  │  transport — concrete: no type parameter reaches here        │
  │  ┌────────────────────────────────────────────────────────┐  │
  │  │  domain assembly   Domain[Repo, Mgr]  ──▶  Domain      │  │
  │  │  the deliberate stop — the parameters end here         │  │
  │  │  ┌──────────────────────────────────────────────────┐  │  │
  │  │  │  wrapper   Manager[E, C, U]                      │  │  │
  │  │  │  ┌────────────────────────────────────────────┐  │  │  │
  │  │  │  │  core      Reader[In, Out]                 │  │  │  │
  │  │  │  └────────────────────────────────────────────┘  │  │  │
  │  │  └──────────────────────────────────────────────────┘  │  │
  │  └────────────────────────────────────────────────────────┘  │
  └──────────────────────────────────────────────────────────────┘

The core becomes load-bearing, and therefore risky. Forty-four call sites depending on one Query method is exactly the deduplication I wanted, and it also means one careless change there is a service-wide change. The copies had a property the core doesn't: a bug in one of them was a bug in one place. What I trade that for is that a fix is also in one place - but the blast radius is real and it's the reason the core carries disproportionate test weight.

Instantiation isn't free at build time. The compiler does real work per instantiation, and a core with three parameters used across a few dozen domains is measurably more to compile than the concrete code it replaced. It hasn't been a problem at my size. It's a line in the bill, not a footnote.

And the temptation. The failure mode of generics isn't writing too few, it's making one abstraction serve two things that were never the same. The tell is specific and I've learned to watch for it: a type parameter plus a boolean flag, or a type parameter plus a switch inside the core. That combination means the two instantiations wanted different behaviour and I forced them through one door. Two clear functions would have been better than one parameterised one with a mode.

When I don't reach for a type parameter

The list I actually use, in the order the questions come up:

The things differ in behaviour, not only in type. That's an interface. A constraint whose methods each implementation fills in differently is polymorphism wearing a type parameter's clothes.
There is exactly one instantiation and no second one in sight. A concrete type reads better, and the generic can be extracted the day the second one arrives - it's a five-minute refactor, not an architectural decision.
The constraint would have to enumerate half the language. If pinning down what the parameter can do takes longer than writing both versions, the abstraction isn't there yet.
It exists to save typing rather than to remove a decision. Deduplicating twelve identical error strings removes a decision - which wording is right. Deduplicating two four-line functions saves keystrokes and costs a reader.
The parameter is at the wrong level. Generic over one operation is usually right. Generic over an entire service is usually someone building a framework by accident.
It's the second abstraction over the same thing. A new generic next to an existing generic that nearly fits is the copy-paste problem again, one level up.

  ┌──────────────────────────────────┐ ┌──────────────────────────────────┐
  │ REACH FOR IT                     │ │ DON'T                            │
  │                                  │ │                                  │
  │ differs only in the type         │ │ differs in behaviour             │
  │ the same shape three or more     │ │ exactly one instantiation        │
  │ times                            │ │ a constraint longer than the     │
  │ one wording for one failure      │ │ code                             │
  │                                  │ │ it saves typing, not a decision  │
  │                                  │ │ the parameter is at the wrong    │
  │                                  │ │ level                            │
  │                                  │ │ a second abstraction over the    │
  │                                  │ │ same thing                       │
  │                                  │ │                                  │
  │                                  │ │ [T] + bool                       │
  │                                  │ │ two instantiations wanted        │
  │                                  │ │ different behaviour, forced      │
  │                                  │ │ through one door                 │
  └──────────────────────────────────┘ └──────────────────────────────────┘

The one conclusion

The type parameter didn't make me a better designer. It moved a specific, narrow class of checking - is this the type I said it was - out of review and tests and into the compiler, and it charged me harder-to-read signatures and a load-bearing core for it.

That's a good trade on repetitive, shape-heavy code with a rigid layout, which is exactly the code I write now. It's a bad trade the moment the things I'm unifying differ in anything other than the type - and the years in PHP, where I had to solve this without the tool at all, are what taught me to tell those two cases apart.

That's my experience and my price for it. If you do this better, if you've already been through it, or if you look at it differently - I'd like to hear how it's solved on your side, and what broke when you tried.

Wiring a New Service Into the Server and the Worker

Anton Brilliantov — Tue, 15 Sep 2026 20:33:34 +0000

Two binaries. One layout. Four ways to make a new unit of work exist in either of them - and what each way costs.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live
PHP monolith into Go services. Earlier parts of this series were about the manifest as the single
declaration a service makes about itself, the environment-variable catalog that falls out of it,
the metrics that arrive with the runtime, and deploy as a consequence of the same file. This part
is the seam underneath all of them: a new handler or a new consumer exists in the repository -
now how does it end up running? Notes:
github.com/brilliant-almazov.

This is what I do on one codebase, with the reasons and the price. You may already do it better,
you may have been here years ago, or you may look at it and disagree - all three are useful to me.

Two binaries out of one image

The service declares its daemons in the manifest, and there are exactly two of them:

service:
  name: <service>
  version: 0.1.0
  daemons:
    - name: server
      handlers: [grpc]
    - name: worker
      handlers: [scheduler]

infra:
  postgres:
    - name: main
      migrations: false
  tx:
    - name: main
      pool: main
  grpc:
    - name: api
      daemons: [server]
  scheduler:
    - name: main
      daemons: [worker]
  resources:
    - type: messaging
      name: main

That file is not documentation. Three things read it:

The build. One Dockerfile, --build-arg BINARY=, one image per daemon, pushed on a vX.Y.Z tag with the version and commit linked in through ldflags.
The deploy. A manual pipeline run with two parameters: which version, and which services - server, worker, or all. Those three values exist because the daemons: list has two entries.
The runtime. Resource declarations turn into environment-variable names by one convention, <TYPE>_<NAME>_<FIELD>: postgres:main becomes POSTGRES_MAIN_DSN, grpc:api becomes GRPC_API_PORT, messaging:main becomes MESSAGING_MAIN_RABBITMQ_URL.

  ┌────────────────────────────────────────────────────────┐
  │ the manifest                                           │
  │   daemons:                                             │
  │     - name: server    handlers: [grpc]                 │
  │     - name: worker    handlers: [scheduler]            │
  └────────────────────────────────────────────────────────┘
     │
     ├──▶ the build     one Dockerfile, --build-arg BINARY=,
     │                  one image per daemon, pushed on a tag
     ├──▶ the deploy    a manual pipeline run: version, and
     │                  server | worker | all
     └──▶ the runtime   POSTGRES_MAIN_DSN · GRPC_API_PORT ·
                        MESSAGING_MAIN_RABBITMQ_URL

  Resource names follow one convention: <TYPE>_<NAME>_<FIELD>.
  A binary nobody declared is a binary nobody ships.

The composition of that list is the service owner's decision and nobody else's. A new cmd/* is
not something an implementer adds because a new kind of background work showed up - new background
work goes into an existing daemon. That rule is written into every control prompt in this repo, and
it exists because the alternative is a binary that builds fine and has no deploy target: the
pipeline only knows server, worker and all, and a third image nobody declared is an image
nobody ships.

The cost of that rule, stated plainly: worker becomes a mixed bag. The outbound relay, audit
partition retention, derived calculations and the gauge observer all live in one process. They have
different failure modes and different appetites, and they scale together whether that suits them or
not. Splitting them is a decision with a manifest change, a new image and a new deploy target
behind it - not a refactor someone does on a Friday.

Different units, the same shape

The two binaries drive different things. The server drives incoming calls; the worker drives
messages and schedules. The packages that hold them sit in the same layout, one folder per daemon:

internal/daemon/server/<domain>     assembly of a domain's Calls
internal/daemon/worker/<...>        relay, retention, derived, observe
internal/consumer/<domain>          subscriptions
internal/publisher/<domain>         outbound publication

On the server side, a domain's assembly is four files, and none of them contains a handler body. The
RPC flow lives in a generic method with a single execution method, Handle(ctx, req) - there are
twenty of those generic RPCs covering create, get, list_revisions, search, update, walk
and the rest. What the domain package holds is a type with a deps field, a NewXxx(deps)
constructor, and a Call() method returning the lambda the generic flow will invoke.

On the worker side, the unit is a consumer bound to a queue, or a job on a schedule. Different
trigger, same skeleton: something is constructed with its dependencies, and then handed to a runtime
that will drive it.

That symmetry is the reason registration can have one shape across both binaries. It is also why the
question "where is this declared" has one answer instead of two. In a tree of 2733 non-generated
.go files across 252 packages, averaging 39 lines each, the assembly point is the only place
where the whole picture of what runs is visible at all. Nobody reads 252 packages to find out what
the worker does; they read one folder.

  ┌─────────────────────────────────┐ ┌─────────────────────────────────┐
  │ server                          │ │ worker                          │
  │ one unit per domain             │ │ one unit per queue or schedule  │
  │                                 │ │                                 │
  │ internal/daemon/server/         │ │ internal/daemon/worker/<...>    │
  │ <domain>                        │ │ relay · retention · derived ·   │
  │ four files of assembly,         │ │ observe                         │
  │ no handler body                 │ │ internal/consumer/<domain>      │
  │ Handle(ctx, req) — twenty       │ │ internal/publisher/<domain>     │
  │ generic RPCs                    │ │ bound to a queue, or run on     │
  │ NewXxx(deps) -> Call()          │ │ a schedule                      │
  └─────────────────────────────────┘ └─────────────────────────────────┘
                   │                                   │
                   ▼                                   ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │ the same three steps on both sides                                  │
  │ construct with deps  ──▶  register in the set  ──▶  the runtime     │
  │ drives it                                                           │
  └─────────────────────────────────────────────────────────────────────┘

  2733 non-generated files in 252 packages — the assembly point
  is the only place the whole picture is visible.

Four shapes registration can take

Here are the four I've actually weighed, with the form each one takes in Go, what it buys, and what
it bills.

1. An explicit list at the assembly point

Everything the binary runs is written out by hand, in one place, in order.

func serverUnits(d Deps) []Unit {
    return []Unit{
        entity.NewCalls(d),
        order.NewCalls(d),
        account.NewCalls(d),
    }
}

What it buys. The order is visible as source order. Nothing happens by itself - if a name isn't
in that slice, it isn't running, and you can see that without a debugger. When something starts in
the wrong sequence, the fix is moving a line.

What it costs. The list is edited by hand, and there are two of them - one per daemon. A unit
that belongs in both gets added to both, or gets added to one and quietly forgotten in the other.
This is the shape whose failure mode I'll come back to below, because it's the one that bit me.

When it fits. Small sets, and any set where the order genuinely matters and is not derivable.
A list of five is easier to read than any machinery for generating a list of five.

2. Registration through an interface

Every unit implements a common registration contract, and the assembly point iterates a set.

type Unit interface {
    Register(ctx context.Context, rt Runtime) error
}

for _, u := range units {
    if err := u.Register(ctx, rt); err != nil {
        return err
    }
}

What it buys. Adding a unit means writing one implementation, and every unit has the same shape -
which matters a lot when the tree already carries generic cores for domain assembly (Builder[Repo, Mgr], Domain[Repo, Mgr], HandlerInput[Repo, Mgr]). A uniform contract means the assembly loop is
written once and never touched again.

What it costs. Somebody still builds units. The interface moves the uniformity problem; it does
not remove the list. And the initialization order becomes implicit - it's now the order of a slice
someone constructed elsewhere, which reads like a detail and behaves like a dependency graph.

When it fits. When the set is large enough that per-unit boilerplate is the dominant cost, and
when the units genuinely are peers - no unit needs another one to be up first.

3. Self-declaration at import time

Each package registers itself in an init(), and the binary blank-imports the packages.

func init() {
    registry.Add("entity", newEntityUnit)
}

import _ "internal/consumer/entity"

What it buys. Zero edits at the assembly point. The package that owns the behaviour also owns the
fact that it runs.

What it costs. I'll say this one as a risk rather than a convenience: presence and order both
become properties of the import graph. Whether a unit runs depends on whether some file, possibly
in a third package, still has a blank import that a tidy-up tool has no reason to keep. Order depends
on Go's package initialization order, which is a real rule but not one anybody reads a diff against.
And the failure is a runtime failure - the binary starts, the registry is short one entry, and
nothing anywhere says so. Compare that with shape 1, where the same failure is a missing line in a
slice you can read.

When it fits. Plugin-shaped sets where the members are genuinely independent and the cost of one
missing member is low - codec registries, format handlers. Not the set that decides whether cache
invalidation happens.

4. Declared in the manifest, assembled from the declaration

The unit is declared once, declaratively, and the wiring code is produced from that declaration.

daemons:
  - name: worker
    handlers: [scheduler]
    consumers: [entity_invalidation]

What it buys. Declaration and operation become the same fact. That's not hypothetical here: the
manifest already produces environment-variable names, deploy targets and the resource wiring, and
two machine-written snapshots already exist as checked-in artifacts - a catalog of 59 environment
variables (45 from the platform, 14 from the service config, each service variable carrying the
file and line it's defined in), and a snapshot of 67 metric records. Both fail CI on drift. A
consumer declared in the same file would inherit the same property.

What it costs. You need a generator or reflection, and manifest-versus-code drift becomes a new
class of bug - one that is invisible until you build the checker that looks for it. There's a
specific trap in that checker, learned the expensive way on the metrics snapshot: the tool has to be
built at the platform version pinned in the service's module file, resolved from the modules and
compiled at that ref. Build it from the latest platform instead and it compares your snapshot against
a catalog you don't have, and the failure looks both confusing and correct.

Honest status. The generator that would produce daemon assembly this way is designed and not
written: a twelve-iteration specification, with domain assembly listed as fully generated - all four
files, no hand-written bodies - and an explicit ban on starting it without a direct instruction. I'm
describing a shape I've specified and costed, not one I've run.

  Four shapes registration can take
  ──────────────────────────────────────────────────────────────────
  1  an explicit list at the assembly point            in use
     buys   order is source order; nothing runs by itself
     bills  two lists edited by hand — one per daemon
  ──────────────────────────────────────────────────────────────────
  2  a common Register interface                       uniform
     buys   one implementation per unit, one shape for all
     bills  someone still builds the set; order goes implicit
  ──────────────────────────────────────────────────────────────────
  3  init() at import time                             a risk
     buys   zero edits at the assembly point
     bills  presence and order follow the import graph;
            the failure is at runtime
  ──────────────────────────────────────────────────────────────────
  4  declared in the manifest, generated from it       not written
     buys   the declaration and the operation are one fact
     bills  needs a generator; manifest-vs-code drift is a new
            bug class

Initialization order is not a detail

Whatever shape you pick, something decides what comes up before what. The dependency chain in this
service is short and completely mundane:

pool  →  tx registry  →  repository / manager  →  domain assembly  →  handler | consumer | job

Two wrinkles in it are worth naming, because both are places where "it happens to work" and "it is
specified to work" look identical from the outside.

The migrations resource resolves its DSN from the pool's variable. It has no variable of its own.
So the pool declaration has to be real before migrations mean anything - and if you were tempted to
give migrations their own DSN "just to be explicit", you'd have created two sources of truth for one
connection string, which is the same failure as a duplicated metric name in a different costume.

The scheduler resource holds the cron expressions. The service reads no CRON_* variables of its
own. A job's schedule is therefore a property of a declared resource, not of the job's code - which
is what you want, and which is also why the job cannot start before the resource it's scheduled by.

Where this went wrong for real, found during an audit of my own service against the platform: a
scheduler initialized lazily through sync.Once with captured variables, instead of using the
platform's worker init-state store. It worked. It also meant the initialization moment was whenever
the first tick happened to fire, which is not a moment you can point at, order against, or test. The
platform ships worker and worker/initstate precisely so that "this worker is initialized" is a
state you can read rather than an event you hope already happened.

Two more ordering rules that come from operations rather than from the compiler:

One publisher per gauge. The outbound-queue and audit gauges are published by worker only. server does not publish them, even though the code that could is in the same module. Two processes publishing one gauge produce a graph that jumps between two values depending on which replica was scraped last - it reads as a real oscillation, and it costs an afternoon every time somebody new sees it. That is a registration decision: same code, registered in one daemon and not the other.
One drainer for the outbound queue. The relay reads rows strictly in id order and FOR UPDATE SKIP LOCKED is deliberately not used, because parallel draining breaks event order, and event order is the thing a consumer relies on to rebuild a correct replica. So the relay is registered once, in one daemon, and "let's run two for throughput" is a data-model change wearing a performance costume.

  pool                     declared as postgres:main; migrations
    │                      resolve their DSN from the pool variable
    ▼
  tx registry              a decorator on mutations; no tx in any
    │                      signature
    ▼
  repository | manager     the manager calls the repository,
    │                      never copies SQL
    ▼
  domain assembly          NewXxx(deps) and Call(); the handler
    │                      body is not in the domain package
    ▼
  handler | consumer | job the scheduler resource holds the cron;
                           the service reads no CRON_* variables

  ┌───────────────────────────────────┐ ┌───────────────────────────────────┐
  │ one publisher per gauge           │ │ one drainer for the outbox        │
  │                                   │ │                                   │
  │ worker publishes them;            │ │ rows strictly in id order;        │
  │ server does not                   │ │ no SKIP LOCKED                    │
  └───────────────────────────────────┘ └───────────────────────────────────┘

  Same code, registered in one daemon and not in the other —
  a wiring decision, not a code decision.

The error you want at build time

Here is the one that made me care about this topic.

A cache-invalidation consumer, fully written, registered in no daemon at all. The package
compiled. Its unit tests were green - the handler logic was tested directly, and it was correct. The
subscription was simply never added to either daemon's set, so in production cache invalidation did
not happen. Not intermittently. At all.

Nothing in the toolchain had an opinion about this, and it's worth being precise about why:

The compiler is satisfied: the package is imported by its own tests, so it isn't even dead code.
Unit tests are satisfied: they construct the unit directly and exercise it.
Coverage is satisfied: the package is covered. Coverage measures whether lines ran under test, not whether they run in production.
The metrics were satisfied too, in the worst way. There is no metric for a subscription that doesn't exist. Broker delivery metrics are per-queue and per-handler, and a handler that never registered has no queue and no series - so the dashboard shows nothing, which is exactly what a healthy idle consumer also shows.

The mirror image of that bug is just as real: registered but not declared. Background work added
to a daemon that the manifest doesn't describe. It runs on your machine and in tests. It has no
deploy target if it needed its own binary, no environment-variable names for the resource it wanted,
and no row in anything that would tell an operator it exists. Where the first bug is silent in
production, this one is silent in the paperwork - and it surfaces at 3am when someone needs to know
what that process is.

Both bugs have the same anatomy: the declaration and the reality are two facts, kept in two places,
with nothing comparing them.

  ┌─────────────────────────────────┐ ┌─────────────────────────────────┐
  │ written, registered nowhere     │ │ registered, never declared      │
  │                                 │ │                                 │
  │ the package compiles            │ │ it runs locally and in tests    │
  │ its unit tests are green        │ │ no deploy target for it         │
  │ coverage counts the lines       │ │ no environment-variable names   │
  │ no subscription -> no queue     │ │ nothing an operator can read    │
  │ -> no series                    │ │                                 │
  │                                 │ │                                 │
  │ invalidation never ran in       │ │ silent in the paperwork,        │
  │ production                      │ │ not in the logs                 │
  └─────────────────────────────────┘ └─────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────┐
  │ the check that closes both                                          │
  │ every registration type appears in exactly one daemon's set         │
  └─────────────────────────────────────────────────────────────────────┘

  Not "is tested", not "is imported" — is in a set that
  a daemon iterates.

Reminder, rule, check

The ladder I use for anything in this class is three rungs, and only the third one holds weight.

A reminder lives in one conversation and dies with it. Telling a person - or an agent - "don't
forget to register the consumer" works exactly once, for exactly that consumer.

A rule in a written instruction works for as long as people read the instruction. That's longer
than a reminder and still not a guarantee; the failure mode is quiet and looks like nothing.

A check is the only rung that holds: a linter, a forbidding test, a structural test, a CI drift
check, a blocking hook. In this repository the checks that already exist and already fail builds are
these:

the environment-variable catalog is regenerated in --check mode on any change to a .go file, the manifest, the module files or the snapshot itself - drift fails the build;
the metrics snapshot has an identically shaped check of its own;
a forbidding test asserts that a particular row-reading construct appears in exactly one package - it was written after an audit found 44 copies of four row-reading forms in the tree and consolidated them onto one generic core;
a coverage ratchet that can only go up. Fair disclosure: the threshold currently sits at 0 while actual coverage is 86.7% - the mechanism is wired, the bar hasn't been raised yet.

The registration check that follows from this article's bug is the same shape, and it's cheap: assert
that every type implementing the registration contract appears in exactly one daemon's set. Not "is
tested". Not "is imported". Is in a set that a daemon iterates. With shape 4, the same assertion
becomes a comparison between the manifest and the generated assembly, which is why the drift checker
is the interesting part of that shape and the generator is the boring part.

Notice what all four of those checks have in common: none of them are about code being correct. They
are about a declaration and a reality being the same object. That is the entire subject of this
article, and it turns out to be the entire subject of the manifest too.

What this costs

The bill for the way I've landed, without the sales pitch attached.

The assembly point is a file people edit by hand. Two of them, one per daemon. Adding a unit
means touching a list that is not where the interesting code is, and the diff looks trivial, which is
exactly the kind of diff a reviewer skims. That's the shape of the bug above; keeping the shape means
keeping the exposure and paying for a check instead.

Uniformity has a floor. Making every unit implement the same contract means the odd unit - the
one that genuinely needs to come up before another - either doesn't fit the contract, or fits it by
being placed carefully in a slice, which is order-as-a-side-effect and reads as an accident to
anyone who wasn't there.

A rule that forbids new binaries pushes work into worker. I described that above and I'll count
it here as a cost, not a design win: one process is doing relay, retention, derived calculations and
gauge observation, and the reason they share a process is a governance rule about who gets to add a
cmd/*, not a claim that they belong together.

A check is another artifact to keep honest. The env catalog check and the metrics snapshot check
both fail builds, and some of those failures are real drift while others are somebody regenerating on
the wrong platform version. They pay for themselves. They are not free, and pretending otherwise is
how a team ends up with a check nobody trusts and everybody re-runs.

What I picked

An explicit list at the assembly point, with every unit built to the same constructor-and-Call()
shape so the list stays boring, and a check that compares the list against what exists - moving
toward shape 4 when the generator is actually written, because a declaration that is already
producing deploy targets and variable names should be producing this too.

That is a choice with a cost I've just spent four paragraphs describing, not a verdict on the other
three. Shape 2 is better than what I have if your unit count is large. Shape 3 is right for genuinely
plugin-shaped sets and wrong for anything whose absence is silent. Shape 4 is where I think this
ends up, and I'd rather say that than pretend I'm already there.

The one thing I'd argue for regardless of which shape you pick: whatever declares that a unit runs
should be comparable, by a machine, against what actually runs. Every failure in this article -
the unregistered consumer, the undeclared job, the two-source DSN, the lazily initialized scheduler -
is one fact stored twice with nothing checking the copies against each other.

So - how is this solved where you are? I'm specifically interested in two things: whether you use
init()-time registration for anything load-bearing and how that's gone, and whether you have a
check that a written unit is actually wired into a running process. If you generate your wiring from
a declaration, I'd like to know what your drift checker catches most often - I suspect it isn't what
you built it for.

Operations out of the box.

Next in this series: what a service owes the rest of the fleet once it exists - the card that gets
assembled from the same declaration, and who owns it.

Generation and Operations Are One Thing

Anton Brilliantov — Mon, 14 Sep 2026 19:41:56 +0000

Add a service and you get code, observability and deploy. If the second half is done by hand after the first, the description of the system and the system itself drift apart — and you always find out later than it happened.

👋 I'm Anton — a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This is the last part of a block about what a service gets for free the moment it exists. Notes and code: github.com/brilliant-almazov.

Here's the thought I want to leave the block on. It may be useful to you, or you may look at it from a completely different angle — both are interesting to me. As always: this is one codebase, my constraints, my price. Not a recommendation for yours.

The thesis

Generation and operations are not two neighbouring processes. They are one.

Add a service and you get the code, the observability and the deploy — in one motion, from one declaration. The alternative is not "generate the code first, wire up operations after". The alternative is that the environment-variable catalogue, the metrics snapshot and the pipelines get written by hand, some time after the code, by someone who remembers most of it.

And then the platform's description of the system stops matching the system. Not loudly. Quietly, one file at a time, and the discovery happens much later than the divergence.

Three ways it drifts

Every drift I've hit looks like one of these:

A variable appeared, and the catalogue doesn't have it. The code reads it. The document that is supposed to list every variable this service needs does not mention it. The service starts on your machine and doesn't start in an environment nobody re-read the document for.
A metric was deleted, and the dashboard still draws it. The panel is there, the line is flat, and flat reads as healthy until someone asks why it has been exactly zero since spring.
A daemon was declared, and there's nothing to deploy it. The manifest says there are two binaries. The build job knows about one. The new one exists in the repository and nowhere else.

code                        description of the system
─────────────────────       ─────────────────────────────
env var added          ✗    catalogue missing it
metric removed         ✗    dashboard still draws it
daemon declared        ✗    nothing to deploy it

              ✗ = the gap nobody is told about

They have the same shape. In all three the code is right and the description of the system is wrong — and in all three you learn about it from production, not from the repository.

That last part is what makes this worth engineering around. A wrong description that fails loudly is a bug. A wrong description that fails silently is a habit: after the second time, nobody trusts the document, and then there is no point maintaining it at all.

What holds it together, part one: a single declaration

There is exactly one place where a service says what it is — its manifest:

service:
  name: <service>
  version: 0.1.0
  daemons:
    - name: server
      handlers: [grpc]
    - name: worker
      handlers: [scheduler]

infra:
  postgres:
    - name: main
      migrations: false
  tx:
    - name: main
      pool: main
  grpc:
    - name: api
      daemons: [server]
  scheduler:
    - name: main
      daemons: [worker]
  resources:
    - type: messaging
      name: main

That file is short, and almost everything operational is downstream of it.

Environment variable names are derived, not chosen. The convention is <TYPE>_<NAME>_<FIELD>, applied mechanically:

Declared in the manifest	Variable the platform reads
`postgres: main`	`POSTGRES_MAIN_DSN`
`grpc: api`	`GRPC_API_PORT`
`messaging: main`	`MESSAGING_MAIN_RABBITMQ_URL`

Once you know the rule, a double-looking name like OUTBOX_EVENT_OUTBOX_BATCH_SIZE stops being a typo and becomes readable: type OUTBOX, resource named event_outbox, field BATCH_SIZE. The scheduler resource carries the cron expression, so the service never reads a CRON_* variable of its own. The migration resource resolves its DSN from the pool's variable and has none of its own.

Pipelines are downstream of the same file. The build job builds per declared daemon out of a single Dockerfile with --build-arg BINARY=; the deploy job takes a version and which of the declared services to move. Nobody maintains a second list of binaries anywhere.

                    ┌──────────────────────┐
                    │  the service manifest │
                    └───────────┬───────────┘
             ┌──────────────────┼──────────────────┐
             ▼                  ▼                  ▼
      ┌────────────┐   ┌─────────────────┐   ┌────────────┐
      │ env names  │   │ metrics snapshot│   │ pipelines  │
      └─────┬──────┘   └────────┬────────┘   └─────┬──────┘
            ▼                   ▼                  ▼
      ┌────────────┐   ┌─────────────────┐   ┌──────────────────┐
      │  --check   │   │ snapshot check  │   │ build by declared│
      │            │   │                 │   │ daemons          │
      └────────────┘   └─────────────────┘   └──────────────────┘
        drift check       drift check           the build itself

One declaration, one source. The point isn't elegance — it's that there is no second place for a human to forget.

What holds it together, part two: drift checks

A single source only stays single if something enforces it. So the derived artefacts are generated, committed, and then guarded.

The environment-variable catalogue

The catalogue is a generated file in the repository — every variable this service can read, where it came from, whether it's required, whether it's secret:

# AUTO-GENERATED by <snapshot tool>. DO NOT EDIT.
schema_version: 1
service: <service>
generated_at: 2026-08-16T01:24:46Z
vars:
  - name: APP_ENV
    source: platform
    catalog: <platform package>
    required: false
    secret: false
    help: prod/staging/dev label exposed in platform_info
  - name: AUDIT_RECORDS_RETENTION_MONTHS
    source: service_config
    defined_in: internal/daemon/worker/retention/config.go:16
    required: false
    secret: false

59 variables — 45 declared by the platform, 14 by the service's own configuration. A service variable records defined_in with the file and line number; a platform variable records the catalogue package that owns it. So the answer to "where does this come from" is in the file, not in someone's memory.

Drift is a build failure. CI runs the same generator in --check mode on a change to any .go file, the manifest, the modules file, or the snapshot itself. If the regenerated catalogue differs from the committed one, the pull request is red.

One detail in that check took a while to get right, and it's the difference between the check working and the check lying: the generator is built at the same platform version the service's modules file pins. The version is resolved from the modules file, the platform is fetched at that ref, the binary is built from it. Skip that, and CI compares your snapshot against somebody else's version of the catalogue — and reports a difference that is not yours.

Locally there's a script that does the same regeneration and reverts the file if the only change is the generation timestamp. Timestamp-only noise in history is worse than no history.

And an honest gap in this one: resource variables don't make it into the snapshot. The platform builds their names by concatenation at runtime, while the snapshot reads configuration declarations. So resource names are documented in a table instead, and the snapshot's test asserts that the platform names are present and that forbidden names are absent — for example, the names of a broker this service does not use.

The metrics snapshot

The second machine-written artefact: name, type, help, labels, histogram buckets, source (platform or service), and where it's declared. 67 entries, including a <dynamic> record standing in for the dynamic-metric factory.

Drift in it fails CI too, by a separate check built the same way.

That snapshot is also where "a metric was deleted and the dashboard still draws it" gets caught: the deletion shows up as a diff in a reviewable file rather than as a flat line on a panel nobody is looking at.

The generated skeleton — specified, not running

The third check is designed and not built, so let me be precise about it.

The plan is that every generated file carries the Code generated by … DO NOT EDIT. header — that header is a contract, not decoration — and that a comparison mode returns a non-zero exit code when what the generator produces differs from what's committed. Editing a generated file by hand is forbidden by the same rule.

That work exists as a 12-iteration specification and a standing instruction not to start it without an explicit go-ahead. It is not a tool anyone can run today.

Check	Watches	On mismatch	Status
Env catalogue `--check`	any `.go`, the manifest, the modules file, the snapshot	red build	running
Metrics snapshot check	metric declarations	red build	running
Generated-skeleton compare	files carrying the `DO NOT EDIT.` header	non-zero exit	specified

Drift checks are the whole mechanism. They are how "declared" and "actual" stay the same thing instead of two things that agree for a while.

Why this is one piece with the generator

The generator does not only produce code. It produces the things operations are assembled from: the declarations that environment variable names are derived from, the metric declarations the snapshot reads, the daemon list the pipelines build and deploy.

Which means you can separate "generation" from "operations" only by paying for it in manual synchronisation — of three artefacts, forever, by hand, each with its own way of being quietly wrong.

There's a small example that shows how quiet that failure can be, from the build side. The linker silently ignores -X pointing at a symbol that doesn't exist. The build is green, the version stays dev, and dev travels into the audit trail and into the trace attribute for as long as nobody looks. So there's a build target that compiles both binaries with a test tag and greps the binary for that tag; empty output means the symbol is wrong. The ldflags target has to be correct in both the Makefile and the Dockerfile — the template historically carried a dead target, and a dead target is exactly the kind of defect that never announces itself.

Same class of problem as the drift checks: something declares a fact, nothing verifies it, and the mismatch surfaces months later in a place you weren't looking.

The honest boundary

What this block described is not uniformly finished, and the difference matters more than the story:

in place                                still a plan
──────────────────────────────────      ────────────────────────────────
the manifest - one declaration          skeleton generator - 12 iterations
env catalogue - 59 variables, --check   coverage threshold - 0 vs 86.7%
metrics snapshot - 67 entries           wait-for-health step in deploy
three pipelines - build, tests, deploy

In place	Still a plan
The manifest as the single declaration	The skeleton generator — a 12-iteration specification, not started
The env catalogue: 59 variables, `--check` in CI	The coverage threshold: the ratchet is `0` today
The metrics snapshot: 67 entries, its own CI check	A "wait for health" step in the deploy pipeline
Three pipelines: build, tests, deploy

To spell out the ones that are easy to overstate:

The skeleton generator is not written. There is a specification of 12 iterations and an explicit rule not to begin it without a direct instruction. Everything above about generated headers and compare mode is design, not a tool.
There are no dashboard or alert files in this repository, and there won't be. The dashboard is assembled by a generator alongside the rest of the fleet's dashboards; the alert rules are described in text and live on the fleet's monitoring side.
The deploy pipeline has no "wait for health" step. The platform serves /health and /ready; checking after a rollout is the environment's job, not the pipeline's.
The coverage threshold is 0. The ratchet exists and can only go up, but the bar hasn't been set. Actual line coverage is 86.7% — which is the number that makes leaving the threshold at 0 slightly embarrassing rather than harmless.

What it costs

Three drift checks are three places where a pull request goes red because of a file that looks like documentation. That reads as bureaucracy right up until the first time one of them catches a variable you added and forgot. It still reads as bureaucracy to whoever didn't add the variable.

A single declaration means there is nowhere to cut a corner. You can't add a quick variable "just for now" without the catalogue noticing, can't drop a metric without the snapshot noticing, can't add a binary the pipelines don't know about. That is the entire benefit, and it is also the entire complaint.

And the coupling earns its keep in proportion to how many services you have. On one service, generating the catalogue, guarding the snapshot and deriving pipelines from a manifest is more machinery than the problem deserves — you'd know all 59 variables by heart. The value shows up when the same shape repeats across services and nobody can hold any of them in their head.

For scale, the service these numbers come from is 2733 .go files across 252 packages, averaging 39 lines per file. Nothing about that is memorable by hand. That's the point.

The one conclusion

"Declared" and "actual" should match by construction, not by agreement. An agreement holds until the first hurried Friday; construction doesn't need anyone to remember.

That's my experience and my price for it, on one codebase, with the boundary above drawn as honestly as I can draw it.

If you do this better — if your platform derives more from one declaration than mine does — I'd like to hear how. If you've been through this and came out the other side deciding the checks weren't worth it, that's just as interesting. And if you look at it from a different angle entirely and think the coupling is a mistake, say so.

The question I'd actually like answered: how is this solved on your side, and what broke before you solved it that way?

Operations out of the box — Part 5. That closes this block: what a service gets the moment it's declared, and what keeps the declaration honest.

Next block: data and scaling — starting with treating a database as the unit of tenancy, and what that costs once there's more than one of them.