jschoubben
00b8398d07
Agent is a first-class concept here — a participant, some of whom are human, holding identity and memory. Using it for the tier-0 node binary put both meanings in one document: hal-agent at tier 0, agents at tier 2. That is the anatomy-naming failure again, an evocative domain word pointing at infrastructure, and how-we-build 4 exists to catch it. ADR 0015's own title supplies the fix: the mesh brokers, nodes host, agents think. So the control plane brokers (hal-mesh), the tier-0 binary hosts (hal-host), the participant thinks (agents, untouched). hal-node was rejected — Node is the inventory aggregate, the binary is what runs on it. Recorded in the document as a near-miss rather than quietly corrected. Tiers now explained before the tree, as a boot narrative, with the point they were carrying made explicit: dependencies point only downward, that is the whole bootstrap answer, and the current mesh violates it — the database is a module, modules come from the pipeline, the pipeline needs the database. Connectivity gains the part that was missing. Naming a context says who decides, not who runs it: overlay membership is tier 0 in the host, policy is tier 2, machinery is tier 4 modules. And the host's link to the control plane deliberately does not run over the overlay, or the overlay would have to exist before a node could be told how to join it. 'tier' is this document's coinage and did not land on first reading; that is now an open question rather than settled vocabulary.
4.4 KiB
status, initiated, touches, became
| status | initiated | touches | became | ||||
|---|---|---|---|---|---|---|---|
| active | 2026-08-23 |
|
006 — The mesh designed from nothing
What is being investigated
What the mesh would look like if it were laid out today, with the requirements known and none of the accumulated shape — expressed as a skeleton: repositories at the root, modules inside them, and whatever turns out to be the right leaf unit below that.
The deliverable is skeleton.md.
Why
Every structural decision so far has been a correction: eight contexts replacing thirty-three modules (ADR 0015), domains replacing single-function modules (ADR 0017). A correction inherits the frame of the thing it corrects, and two of the mesh's oldest problems look unsolvable from inside that frame:
- The bootstrap circularity. The mesh needs a database, a bus, a registry and an identity provider. Those are modules the mesh installs. The mesh cannot install them before it exists. This has been worked around repeatedly and never designed away.
- Participation requires privilege. Everything assumes root on a machine whose packages and services the mesh owns. A phone cannot participate on those terms, and neither can a machine someone else administers.
Designing from nothing is a way to find out which parts of the current shape are requirements and which are residue.
The requirements this is designed against
Stated by the operator, recorded here so the skeleton can be checked against them rather than against taste:
- The mesh manages multiple computers — full control, through modules installed to nodes.
- Mesh state lives in a database: which modules on which nodes, logs, configuration.
- Configuration has several touchpoints — tool surface, web interface, others — all hosted by the mesh itself.
- Connectivity is core: every node reachable from every other over a shared overlay, some nodes publicly exposed, firewalls configured.
- The mesh hosts applications — and requires some of them itself. This is the circularity.
- Arch Linux only for now; ideally any device, including phones, on lighter terms.
- The end goal is to operate an IT company on it — development, design, deployment, full circle, self-hosted. Personal cloud infrastructure.
- Agents make it self-improving and self-healing.
- It is end-to-end testable on one machine (ADR 0016).
Status
A first skeleton exists, with four design moves that the current shape does not have. It is
active because two of them are unproven and one contradicts a record that is already
accepted.
Finding worth stating up front: ADR 0015 names nine bounded contexts and none of them owns connectivity — no overlay, no resolution, no firewall, no ingress. Requirement 4 has no home in the accepted decomposition, while research 005 found reachability to be the only part of the catalogue where modules genuinely change together under one intent. The skeleton adds it.
Open questions
| Question | Why it is open |
|---|---|
| Does the record — the event log contexts integrate through — belong to the substrate or the control plane? | It is infrastructure by shape and domain by content. Placing it wrong reintroduces a circularity. |
| One repository per tier, or per context? | Already open from ADR 0015 as "catalogue destination — one repository or many". The skeleton assumes per tier and does not settle it. |
| Does an unprivileged node earn a place in the inventory, or only a presence? | Decides whether "node" means one thing or two. |
Does feature survive? |
The skeleton splits it in two and argues the conflation is what makes the delivery pipeline hard to reason about. Unproven. |
Is tier the right word? |
It is this document's coinage, not established vocabulary, and it did not land on first reading. boot order and ring are the alternatives. The concept is settled; the word is not. |