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.
66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-04-02
|
|
deciders: jochen
|
|
reconstructed: 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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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`.
|