jschoubben
4d19e93900
The design layer described every service by role and never once by name: Postgres appeared in zero design documents. That was over-application of the research rule "never identify the mesh it observed", which is about node names and domains, not software. Two things were actually broken by it. substrate.lock pins images by digest and a digest belongs to a named image, so the bundle could not be written from the design. And a reader could not tell a settled choice from an unexamined one -- "a relational store" reads identically either way. ADR 0048 names them: PostgreSQL, LavinMQ, MinIO, an OCI registry, Docker. The argument for each is continuity, which is a real argument -- replacing a substrate service migrates the mesh's own state. Role and product are now both written, because the design depends on the protocol while the installer needs the product. Also separates two questions the substrate doc had merged: being substrate and being in the bundle. Only Postgres must precede the control plane; the rest are substrate by role and ordinary by delivery. Whether the bus joins it is left open, because it turns on the control plane's internal shape. Names the forge as Gitea, and records ingress/Traefik as an unclosed gap rather than a naming one -- nothing says what terminates TLS or which tier owns it. Fixes a miscount: the host's bootstrap vocabulary is six shapes, not five.
5.5 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | |||
|---|---|---|---|---|---|---|---|
| to-be | designed | 2026-08-27 |
|
The control plane
Tier 2. The term appears seventy-nine times across this repository and was defined nowhere,
which is how-we-build §5 failing on this repository's own vocabulary.
This document defines it. It does not design the contexts inside it; those are open in research 006.
The definition
The control plane is everything that needs to know about more than one node.
That is the whole test, and it is not arbitrary — it follows from ADR 0037. The host applies and does not decide because deciding needs knowledge the machine does not have. So the line falls exactly there:
| Question | Whose |
|---|---|
| write this file, with this content, with this mode | the host — one machine |
| which nodes should run the store | the control plane — needs every node |
| is this unit running | the host — one machine |
| which peers belong in this node's overlay | the control plane — needs every node |
| what does this machine have installed | the host reports; the control plane records |
| has this node been unreachable for a week | the control plane — nobody else is watching |
A useful consequence: anything a single machine could answer alone is not the control plane's. If it needs no second node, putting it here is a mistake, and the tier rule will not catch it because the dependency direction is still correct.
What is inside it
Ten contexts and one interface, from the skeleton (research 006):
| record | the event log every other context integrates through |
| inventory | nodes, modules, assignments, versions |
| config | settings, secrets, and deriving them onto nodes |
| connectivity | overlay, resolution, exposure, filtering, certificates |
| provisioning | resource grants between modules |
| delivery | source to artifact to node |
| observability | health, logs, metrics, alerts |
| identity | agents, humans, services, authorisation |
| work | tasks, workflows, runs |
| knowledge | memory, documents, retrieval |
| api | the one interface every surface speaks to |
These are contexts, not services. They are separate in the sense that matters — each owns
its own store, and they integrate through the record rather than by reading one another
(how-we-build §4). They are not separate deployables, and
research 011 records why that
constraint is load-bearing: a single surface can compose them only while there is one interface
in front of them.
What it is not
- Not the thing that changes machines. It decides; the host applies. It never reaches into a node except through the host.
- Not a surface. Tier 3 is how people and agents reach it. It has one interface; the surfaces are what speak to that interface.
- Not the substrate. It runs on tier 1 — PostgreSQL, LavinMQ, MinIO, an OCI registry (ADR 0048) — and cannot start without them, which is what makes them a lower tier.
- Not privileged on a node. It has no more access to a machine than the declaration vocabulary allows (ADR 0039).
It is also a consumer
The property that makes tier 2 unlike the others: the control plane has requirements of its own. It needs a PostgreSQL database, an AMQP virtual host, and a bucket — the same things any module needs, granted the same way.
That is the circularity the tiers exist to resolve rather than hide: the control plane cannot provision its own database, because it is not running yet. So its store and its virtual host are raised from the bundle the host carries, before there is a control plane to ask (ADR 0038, research 011).
Where it runs
On nodes, like anything else. It is not a place outside the mesh; it is modules the mesh hosts, assigned to nodes by the same mechanism as everything else.
Which raises a question this document does not answer: how many nodes run it, and what happens when the one running it is down. The broker is one per mesh by decision; whether the control plane is, and what a node does while it cannot reach it, is ADR 0036's ordinary situation seen from the other end — and it is not designed.
Open
- The contexts themselves. Ten is the skeleton's claim, not a settled list. Research 006 asks whether the record belongs here or in the substrate, and whether identity is a context or a substrate service.
- How far it may be split. One deployable today. Splitting a context out costs the single interface a surface depends on (research 011).
- How many run, and what a node does without one. Above.
- What the interface is. One interface is stated; its shape, and whether it is request, subscription or both, is not (research 011).