---
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`.