jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
3.0 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 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.