Order the records the way the system is learned

Jochen asked whether the order made sense. It did not -- it followed when
things happened to be decided, which after consolidation is fictional anyway
since record 5 alone folds decisions taken across a week.

Concretely wrong before: the domain statement sat at 8, after five engineering
rules; the constitution was scattered across 5, 12 and 17; the tiers landed at
15, 16, 21 and 22 with process records in between.

Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what
runs on them and how it gets there (9-10), how it is built (11-16), how it is
checked (17-18), how we work (19-23).

Two things made this safe rather than free. It is a permutation, not a
compaction, so the renames go through temporary names -- otherwise two files
want one slot and one is lost. And the reference rewrite is a single
simultaneous pass, because almost every number moved into a slot another number
was vacating; replacing one at a time would have cascaded and pointed things at
the wrong record while still resolving.

Verified: 284 [ADR NNNN](path) links across the repository, all with matching
text and target.

The ordering principle is now stated in 19 rather than left implicit -- the
repository already said "the numbering is the flow" about its folders, and
there was no reason for the records to be the exception.
This commit is contained in:
2026-08-28 23:30:42 +02:00
parent e1febe8e0f
commit 333356cff3
85 changed files with 471 additions and 465 deletions
+12 -12
View File
@@ -4,9 +4,9 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0001-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0021-the-substrate-and-the-control-plane.md
- 02-DECISIONS/0002-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0009-modules-and-the-graph.md
- 02-DECISIONS/0006-the-substrate-and-the-control-plane.md
---
# The mesh as it stands
@@ -28,11 +28,11 @@ onto it and can be regenerated.
containerised service is a module. A set of capabilities with no service behind them is a
module. A bare marker whose whole content is that a node has it is a module. The mesh's own
components are modules on exactly the same terms as everything else it carries
([ADR 0019](../../02-DECISIONS/0019-modules-and-the-graph.md)).
([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md)).
**An agent** is a participant. Some agents are human. What differs is modality — how the agent
acts — and not category: both hold identity, both act, both accumulate memory
([ADR 0007](../../02-DECISIONS/0007-agents-are-persistent-employees.md)).
([ADR 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)).
## Where truth lives
@@ -40,10 +40,10 @@ The repository defines **what exists**: the modules, what each declares, how eac
The mesh database defines **what runs where**: which node is assigned which module, at which
selection, with which overrides, plus the settings every node reads. No node-to-module mapping
is ever committed ([ADR 0021](../../02-DECISIONS/0021-the-substrate-and-the-control-plane.md)).
is ever committed ([ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)).
Everything on a node's disk is **derived** from those two, and is regenerated rather than
edited ([ADR 0002](../../02-DECISIONS/0002-managed-files-are-generated-never-edited.md)). A node that
edited ([ADR 0011](../../02-DECISIONS/0011-managed-files-are-generated-never-edited.md)). A node that
loses its database keeps running from a local cache, which is deliberate and has the obvious
cost: the cache carries no indication of its own age.
@@ -51,7 +51,7 @@ cost: the cache carries no indication of its own age.
Nothing dials a node. Every node dials the broker outbound, owns an exchange named for itself,
and consumes from its own request queue
([ADR 0001](../../02-DECISIONS/0001-nodes-communicate-over-a-broker.md)). Three message shapes carry
([ADR 0002](../../02-DECISIONS/0002-nodes-communicate-over-a-broker.md)). Three message shapes carry
everything: requests expecting a reply, commands instructing that a stage of work be done, and
events stating that something happened.
@@ -65,9 +65,9 @@ goes to where the capability is.
A push to the forge is the only trigger. What follows is three silos with deliberately
different cardinality: compile once, package and upload once, then install-configure-start-
verify **on every assigned node**
([ADR 0023](../../02-DECISIONS/0023-delivery.md)). What travels between
([ADR 0010](../../02-DECISIONS/0010-delivery.md)). What travels between
build and node is a self-contained build output, so a deploy is extract-and-run and touches no
network ([ADR 0023](../../02-DECISIONS/0023-delivery.md)).
network ([ADR 0010](../../02-DECISIONS/0010-delivery.md)).
Modules are resolved into dependency levels and a level completes before the next begins, so a
module always builds against its dependencies as they were just published.
@@ -78,7 +78,7 @@ A module declares what it **provides** and what it **requires**. The mesh satisf
requirement: it creates the resource, generates the credential, records the grant, and writes
the values where the module will read them. The module never learns which node its database
lives on, and nobody ever writes a credential by hand
([ADR 0019](../../02-DECISIONS/0019-modules-and-the-graph.md)).
([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md)).
This is the property the mesh's whole shape rests on, and it is why provisioning is treated as
a core concern rather than as plumbing.
@@ -92,7 +92,7 @@ named for a feature the module does not declare, a stage that reported it had di
message rather than that the effect happened, a package that 404ed from every mirror while the
job went green.
[ADR 0023](../../02-DECISIONS/0023-delivery.md) is the response, and it is applied
[ADR 0010](../../02-DECISIONS/0010-delivery.md) is the response, and it is applied
instance by instance rather than enforced by a mechanism. New instances are still being found.
That is an as-is fact, not a criticism: it is the single most useful thing to know about this
system before changing it.