jschoubben
004057d85c
I have been treating "what a node presents to prove it is that node" as an undecided design question for weeks, and blocking on it. It was decided. 08-connectivity says of the overlay keys: each node generates its own keypair, the private key never leaves the machine, the public key is published to the mesh -- and says explicitly that this IS ADR 0004's "a node holds its own identity", applied. Nobody had applied it to the thing 0004 is actually about. What caused it was a word. The lifecycle said a joining node receives its own durable identity, which reads as the mesh issuing something, and then the question is what. The mesh issues nothing. A node arrives holding its identity; what it receives is being known. That line now says what happens: it presents the one-time secret and its own public key, which the mesh records. The rule above it then holds literally rather than aspirationally. The mesh stores a public key, so a copy of the mesh's database grants nothing, and compromise of a node really is compromise of only that node. Also recorded, since it was asked directly: same principle as SSH, own key, not the machine's SSH host key. Host keys are regenerated by reinstalls and image clones, which would silently un-enrol a node; their lifecycle belongs to sshd rather than the mesh; and a partial host has no SSH daemon at all, so an identity scheme resting on one excludes a supported kind of node. The good half of that idea is kept: the mesh knows every node, so it can distribute host keys the way it distributes authorised keys, and node-to-node SSH stops depending on trust-on-first-use.
02-DECISIONS
Architecture decision records — the "why" trail behind the rules in
00-META and the specifications in 03-DESIGN.
Numbered 02 because a decision precedes the design it authorises. Research concludes,
the decision is recorded here, and only then is the design written. Following the folder
numbers walks the process in the order it happens.
One file per decision, numbered, never deleted. A superseded record has its status: changed
and gains a pointer to what replaced it — its text is never edited. The reasoning that was
rejected is the expensive half to rediscover.
The records run in the order the decisions were taken, oldest first.
Every decision is a record. There is no ledger and no index file — if a decision is worth
recording it is worth a record, and if it is not worth a record it is not recorded
(ADR 0019). A "decision" small enough to be one line is
almost always a rule, and a rule belongs in
00-META/how-we-build.md, where it is enforced and keeps the
incident that earned it.
Frontmatter
---
status: proposed | accepted | superseded
date: YYYY-MM-DD # when the decision was taken, not when it was written down
deciders: name
reconstructed: true|false # true when the record was written after the fact from evidence
superseded-by: # 02-DECISIONS/NNNN-....md, when status is superseded
extends: # 02-DECISIONS/NNNN-....md, when this record widens an earlier one
---
Body
# N. Title in plain language
## Context what was true, with evidence
## Considered Options numbered, each with why it was rejected
## Decision what was decided
## Consequences what follows, including what got harder
## References commits, pull requests, knowledge-base entries, prior art
State evidence, not assertion. "Zero of 124 modules declare brain as a dependency"
outranks "the dependency rule is not followed".
Reconstructed records
Records 0001–0014 were written on 2026-08-23, after the decisions they describe. Records 0015 onward were taken as records. Those
decisions were taken in implementation rather than in a document; the records state what was
decided and the evidence it was decided from, and each carries reconstructed: true and says
so in its first lines.
A reconstructed record is not a transcript. Where the deliberation is not recoverable, the options section states what the alternatives were and why the chosen one won on the evidence available — not a discussion that did not happen. Where a date is not establishable it says so rather than guessing.
Index
A number identifies a record and never changes. Records are referenced from outside this repository — code comments, commit messages — so a number that moves invalidates them silently. Renumbering once cost 96 references across two code repositories, and that is why the numbers are now fixed.
So the folder is in creation order, and the reading order lives here. It is generated from
each record's topic: and written, because a reader looking at the folder on a forge sees the
folder rather than a command. The objection to a written index is that it drifts — which is
answered by checking it rather than by refusing to write one:
python3 00-META/checks/index.py --write regenerate
python3 00-META/checks/index.py fail if stale
What the mesh is
- 0001 — The mesh brokers capabilities; nodes host; agents think
- 0002 — Nodes communicate over a message broker, not over HTTP
- 0003 — An agent is a persistent employee, not an instance of a pool
Its tiers, from the bottom up
- 0004 — A node, and how it joins
- 0005 — The node host
- 0006 — The substrate and the control plane
- 0007 — Connectivity
- 0008 — A context owns its store, exclusively
What runs on them, and how it gets there
- 0009 — Modules and the graph
- 0010 — Delivery
How it is built
- 0011 — Managed files are generated onto nodes and never edited there
- 0012 — The mesh creates no symlinks — a derived file is a copy
- 0013 — Schema and state changes are numbered migrations, in the same language as the code
- 0014 — No workspace — each module is a standalone package consuming published dependencies
- 0015 — Applications live in their own repository; the monorepo is for the mesh
- 0016 — The lab
How it is checked
- 0017 — A test defends a decision
- 0018 — A picture of a system is read from the system, never from what asked for it