jschoubben
f49d177a31
0054 -- things that change together share an authority, not a package. The constitution instructs agents to group "how a node is reachable" into one module, citing superseded ADR 0017; ADR 0044 says there is no networking thing to install. Since the constitution is injected where work is decided, the superseded rule is the one actually steering work. The observation behind it was right -- research 005 measured that reachability is the only place modules genuinely change together -- but the conclusion was wrong: tight coupling means a shared authority, not one artifact. wireguard and traefik deploy to different node sets, so the merged module would be assigned where half is unwanted. Requires amending how-we-build and republishing the derived page. 0055 -- the control plane is the node-coordinating contexts. Three context lists were in circulation (0015 says nine, 06 says ten, the README said eight) and none was decided. Research 006 said explicitly that the change "belongs in a new record -- not written here", and the design used the list anyway. Reconciling them shows `stream` and `ai` were dropped with no reasoning at all. Applying 06's own test -- needs to know about more than one node -- gives seven contexts plus the api, with work, knowledge and stream as hosted applications and `ai` folded into config as an ordinary grant. The record defers rather than lists. The cost is stated rather than reassured away: a board composing across the boundary reads more than one interface. That was raised before as "only moves the problem up a layer", and the answer is that 0045 already requires surfaces to read interfaces rather than stores -- what changes is the count, not the kind of work. 0056 -- the authority is the control plane, not a database. Every clause of 0003 has been decided against in four separate records and it is still accepted and cited as live. The error underneath is the same category error 0054 corrects: "source of truth" named a storage location when it meant an authority, and once the store is the answer, shared schemas follow. The half that was right -- the repository defines what exists, the mesh defines what runs where -- survives untouched. Best consequence: the cache mode disappears, so a node that has not heard from the mesh is no longer indistinguishable from one that has. 0003 is left accepted until 0056 is.
5.8 KiB
status, date, deciders, reconstructed, supersedes, extends
| status | date | deciders | reconstructed | supersedes | extends |
|---|---|---|---|---|---|
| proposed | 2026-08-27 | jochen | false | 0003-the-mesh-database-is-the-source-of-truth.md | 0045-a-context-owns-its-store.md |
56. The authority is the control plane, not a database
Context
ADR 0003 is still accepted and still cited
as live by two as-is documents. Its decision says:
A single database holds every binding... The runtime loads its configuration from that database at startup and falls back to a local cache when the database is unreachable.
Every clause has since been decided against, in four separate records, none of which marked it superseded:
| 0003 says | contradicted by |
|---|---|
| a single database holds every binding | ADR 0045 — a context owns its store exclusively; three contexts must move out of the registry database, taking thirteen tables |
| the runtime loads from that database | ADR 0037 — the host does not query the mesh database |
| — | ADR 0039 — a node holds no credential to it |
| it falls back to a local cache | ADR 0043 — the host has its own store, which is not a cache of anything |
The two modules that still made 0003 literally true — wireguard and traefik, the only direct
database connections left — are removed by
ADR 0049 and ADR 0050.
When those land, nothing on any node reads the mesh database at all, and 0003 will describe a
mechanism with no remaining implementation.
The error underneath is a category error, and it is the same one ADR 0054 corrects elsewhere: source of truth named a storage location when what it meant was an authority. Once the store is the answer, "which database" becomes the question, and shared schemas follow — which is precisely the thirteen-table tangle ADR 0045 exists to undo.
Decision
The control plane is the authority for what runs where. A database is where one context keeps its state.
Three consequences of that sentence, replacing 0003's three clauses:
- There is no single mesh database. Each context owns its store exclusively
(ADR 0045). "The mesh database" is not a thing that exists;
the registry database is
inventory's store, and other contexts have their own. - No node reads any of them. A node is told what to own, over the link, in a bounded vocabulary (ADR 0037, ADR 0039). Reading the authority's storage is not how anything learns anything.
- A node runs from its own store, always — not as a fallback. The host records what it owns and reconciles against it (ADR 0043). That store is the node's own record of what it applied, not a copy of somebody else's state.
What survives from 0003, unchanged
The half that was right, and it is the half everything else cites:
The repository defines what exists. The mesh defines what runs where. No node-to-module mapping is ever committed, and a node is described nowhere in source.
That is what makes the repositories node-agnostic and it is why anything about the mesh can be published at all (ADR 0019). Nothing here weakens it — this record changes where the authority lives and how it is reached, not whether bindings are committed.
Consequences
- The cache mode disappears, and with it the fault it created. The as-is records the sharp edge: "a node running from cache looks identical to a node running from the database. There is no age on the cache and nothing reports divergence, so a node can be running yesterday's assignment set indefinitely without any signal that it is." Under this record there is no second mode to be mistaken for the first — a node always runs from its own store, and whether it has heard from the mesh recently is a separate, reportable fact rather than an invisible one.
- "The mesh database" should stop being said, including in conversation. It names a thing that will not exist, and it is the phrase that makes a shared schema sound reasonable.
- This closes the set of records that made nodes hold database credentials. 0037 decided it, 0039 named the exposure, 0049 and 0050 remove the two offenders, and this one removes the record that still authorised the arrangement — which was the last thing anybody could have cited in its defence.
- Two as-is documents cite 0003 and describe today's behaviour accurately. They are not wrong and should not be changed: ADR 0020 keeps the layers separate, and as-is describing a superseded decision is exactly what as-is is for. What changes is the citation's status, not its content.
- It does not say how today's mesh gets there. Thirteen tables move, two modules are rewritten, and nothing here costs that. Research 006 already lists the migration as unaddressed, and this record adds to what must migrate rather than explaining it.