jschoubben
5e83ac2c22
Jochen: a normal application has 3-5 ADRs, maybe 10 for a large one, and we are at 65. Fair, and the cause is mine -- I recorded every FINDING as a decision rather than every fork in the road. Two merges, both cases where one decision had been split across many records because it was taken over several days rather than at once. 0019 absorbs ten records about how this repository works: what it is and that it is public, the folder flow, the two design layers, the issue front door, status in frontmatter, playbooks, the naming rule, the product name. Those were never ten decisions -- they were one, seen from ten angles as the repository took shape. 0016 absorbs the five about the lab: a node is a virtual machine, a router is scenery, a scenario declares the underlay, a scenario is a closed address space, and the two scenario classes. Same pattern -- one design, split by the order it was worked out in. The consolidated 0019 also raises the bar for what earns a record, since that is what produced 65: a record is warranted when there is a genuine fork -- a direction reversed, an alternative that will be proposed again, something contested. A finding is not a decision, and a bug is certainly not. Everything else belongs in the design document where the reasoning is actually read. The checker earned its place here. Deleting nine records left 13 dangling links across the repository and it named every one, including in AGENTS.md. Nothing was found by reading. Remaining clusters worth the same treatment: the host (8 records), delivery (5), modules (6), connectivity (4), substrate and control plane (4). That would be 52 down to roughly 30.
95 lines
6.6 KiB
Markdown
95 lines
6.6 KiB
Markdown
---
|
|
status: active
|
|
initiated: 2026-08-23
|
|
touches:
|
|
- 02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md
|
|
- 02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md
|
|
- 03-DESIGN/00-as-is/00-overview.md
|
|
- 03-DESIGN/01-to-be/00-work-breakdown.md
|
|
became: []
|
|
---
|
|
|
|
# 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 deliverables are [`skeleton.md`](skeleton.md) — tiers, repositories and the four design
|
|
moves — and [`code-skeleton.md`](code-skeleton.md) — the tier test, what a module looks like on
|
|
disk, and where today's catalogue lands.
|
|
|
|
## Why
|
|
|
|
Every structural decision so far has been a **correction**: eight contexts replacing thirty-three
|
|
modules ([ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md)), domains
|
|
replacing single-function modules
|
|
([ADR 0017](../../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md)). 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.
|
|
|
|
**And there is more residue than expected, from a knowable source.** This began as a
|
|
**dotfiles repository** — the first two days of history adopt dotfiles, add per-node dotfile
|
|
overrides, and introduce service symlinking with an ignore file. The flat one-directory-per-tool
|
|
catalogue, linking rather than copying, adoption of already-configured machines, per-node
|
|
overrides, and the desktop modules are all inherited from that, not chosen for a mesh. Recorded
|
|
in [`03-DESIGN/00-as-is/10-module-catalogue.md`](../../03-DESIGN/00-as-is/10-module-catalogue.md).
|
|
|
|
That makes this effort's question sharper than "what would we do differently": much of what
|
|
looks like design is a generalisation of *place files on my machines*, never revisited because
|
|
it was never stated as an assumption.
|
|
|
|
## The requirements this is designed against
|
|
|
|
Stated by the operator, recorded here so the skeleton can be checked against them rather than
|
|
against taste:
|
|
|
|
1. The mesh manages multiple computers — **full control**, through modules installed to nodes.
|
|
2. Mesh state lives in a **database**: which modules on which nodes, logs, configuration.
|
|
3. Configuration has **several touchpoints** — tool surface, web interface, others — all hosted
|
|
by the mesh itself.
|
|
4. **Connectivity** is core: every node reachable from every other over a shared overlay, some
|
|
nodes publicly exposed, firewalls configured.
|
|
5. The mesh **hosts applications** — and requires some of them itself. This is the circularity.
|
|
6. **Arch Linux only for now**; ideally any device, including phones, on lighter terms.
|
|
7. The end goal is to **operate an IT company** on it — development, design, deployment, full
|
|
circle, self-hosted. Personal cloud infrastructure.
|
|
8. **Agents make it self-improving and self-healing.**
|
|
9. It is **end-to-end testable on one machine**
|
|
([ADR 0016](../../02-DECISIONS/0016-the-lab.md)).
|
|
|
|
## 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](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md)
|
|
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](../005-domain-grouping/analysis.md) 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?~~ | **Answered 2026-08-25** by the operator: a node is a *managed machine inside the mesh*, not an unprivileged something — and a disconnected node is still a node, in a different situation. The question posed a class distinction; the answer is that there is none, and what varies is **state**. Recorded as [ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md). |
|
|
| ~~Does absorbing overlay, filtering, packages, supervision and the container runtime make the host too large?~~ | **Answered 2026-08-25** — [`host-size.md`](host-size.md). Measured: the absorption is smaller than the machinery that already applies state, and eight of ten adapters already carry no dependency. The risk is not size but direction, and it is two modules wide. The claim survives with its scope corrected — the host carries one concern, *apply declared state on this machine*, of which the six are instances. Recorded as [ADR 0037](../../02-DECISIONS/0037-the-host-applies-it-does-not-decide.md), designed in [`05-the-node-host.md`](../../03-DESIGN/01-to-be/05-the-node-host.md). |
|
|
| ~~Four substrate services or five?~~ | **Answered conditionally**, which is the honest form — [`07-the-substrate.md`](../../03-DESIGN/01-to-be/07-the-substrate.md). The substrate is *what the control plane consumes and cannot grant itself*. The identity provider qualifies only if the control plane delegates authentication; if it authenticates natively it is an ordinary hosted service. The count follows from a decision not yet taken, and asserting four was asserting that decision. |
|
|
| Does `feature` survive? | The skeleton splits it in two and argues the conflation is what makes the delivery pipeline hard to reason about. Unproven. |
|