jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
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.