jschoubben
e1f4c7d9e0
0003 is now superseded by 0056. Nothing is left proposed. Applied: - 06 corrected from ten contexts to seven plus the api, each row now stating why it passes the more-than-one-node test. work, knowledge and stream are named as mesh-hosted rather than dropped; `ai` folds into config; `record` is deferred explicitly rather than listed. Its frontmatter now cites 0055. - how-we-build §4 amended per 0054, and the derived page republished by playbook 05. The sync found the drift the playbook exists to catch: the published §4 and the source did not say the same thing. The source said "four accidents, not four boundaries"; the published page said "one intent expressed four times", and only the published page carried the scope caveat. Same rule, two texts, already diverging. Verified the republish by reading back -- the new rule is present and the old section's body returns nothing -- rather than trusting the success message. The two smaller findings: - 0051 separated the transport identity from the declaring authority. It said the token carries "an address" and "the identity to expect" without saying what the node dials. It dials the broker, so pinning only that would make the control plane's authority transitive and let a compromised broker forge declarations -- which, since the host applies whatever the link delivers, is the whole machine. The token now carries four things, and declarations are signed and verified per declaration. Cost recorded: rotating the signing identity is fleet-wide. - 0026 no longer restates 0022's rule about generated views. 0022's own words are "prose does not restate status; one place, and two is one too many", which is what 0026 was doing to it.
3.1 KiB
status, superseded-by, date, deciders, reconstructed
| status | superseded-by | date | deciders | reconstructed |
|---|---|---|---|---|
| superseded | 02-DECISIONS/0056-the-authority-is-the-control-plane-not-a-database.md | 2026-04-02 | jochen | true |
3. The mesh database is the source of truth; the repository is node-agnostic
Reconstructed after the fact from the evidence cited below.
Context
Two things must be known to run the mesh: what exists — which modules there are, what each declares, how each is built — and what runs where — which node hosts which module, with which settings, at which version.
The repository is the natural home of the first. It was initially also the home of the second: per-node directories held that node's configuration, and adopting a machine meant committing its files. That has three costs. A node cannot be changed without a commit, so runtime state and source share a review cadence they do not share a rhythm with. Two nodes cannot be reconciled, because nothing holds both. And the repository becomes an inventory of the installation, which is exactly the content that cannot be made public.
Considered options
- Per-node directories in the repository. Rejected — it is what existed. Every binding change is a commit and a deploy, and the repository accumulates an inventory of one particular mesh.
- Configuration files distributed to nodes and edited there. Rejected. There is then no authority: two nodes disagreeing have no arbiter, and drift is invisible until something breaks.
- A mesh database as the single authority, cached locally for resilience. Chosen.
Decision
A single database holds every binding: which node hosts which module, at which selection, with which environment overrides, plus mesh-level settings that all nodes read. The runtime loads its configuration from that database at startup and falls back to a local cache when the database is unreachable.
The repository defines what exists. The database defines what runs where. No node-to-module mapping is ever committed.
A node is therefore not described anywhere in source. Bringing one into the mesh is a database operation.
Consequences
- The repository becomes node-agnostic, and can be published without disclosing an installation. This repository's public stance rests on that property.
- A binding changes without a commit, a build, or a deploy.
- The local cache means a node survives losing the database, but a node running from cache is running from a snapshot with no indication of its age. Divergence is silent by construction.
- The database is the hardest dependency in the mesh. It is also a module, provisioned like any other, which makes its bootstrap circular — resolved by the first-node initialisation script, and the reason such a script exists.
- Nothing on a node is authoritative. That is what makes the next decision necessary.
References
Phase 3: rename core modules to hal/ namespace, 2026-04-02, and the mesh configuration tables that landed with it.- Knowledge base:
mesh— "The repo is node-agnostic. It contains no per-node assignments." - The stale-cache shape:
troubleshooting/installed-version-and-deployments-are-stale.