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.
2026-08-28 23:30:42 +02:00
parent e1febe8e0f
commit 333356cff3
85 changed files with 471 additions and 465 deletions
@@ -2,17 +2,17 @@
 status: graduated
 initiated: 2026-08-23
 touches:
-  - 02-DECISIONS/0019-modules-and-the-graph.md
+  - 02-DECISIONS/0009-modules-and-the-graph.md
  - 03-DESIGN/00-as-is/10-module-catalogue.md
  - 03-DESIGN/00-as-is/02-modules-and-manifests.md
 became:
-  - 02-DECISIONS/0019-modules-and-the-graph.md
-  - 02-DECISIONS/0019-modules-and-the-graph.md
+  - 02-DECISIONS/0009-modules-and-the-graph.md
+  - 02-DECISIONS/0009-modules-and-the-graph.md
 ---

 # 005 — Which domains the catalogue groups into

-[ADR 0019](../../02-DECISIONS/0019-modules-and-the-graph.md) settles
+[ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) settles
 that modules outside the platform core are grouped by domain rather than by single function,
 and deliberately does not settle the list. This effort settles the list — and, first, tests
 whether the premise survives measurement.
@@ -25,7 +25,7 @@ together**, measured across the full history of the code repository.

 ## Why

-The argument in ADR 0017 is that the catalogue's shape records what was installed rather than
+The argument in ADR 0022 is that the catalogue's shape records what was installed rather than
 what anything is for — that four modules constituting "how a node is reachable" have no
 relationship the mesh can see, so a change to connectivity is made four times.

@@ -59,12 +59,12 @@ open questions below.
 this effort — which is why it stayed open after being resolved.

 **Whether provider modules group at all** — *no.*
-[ADR 0019](../../02-DECISIONS/0019-modules-and-the-graph.md):
+[ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md):
 there is no `networking` thing to install, there are concrete modules named individually. Folders
 assert relationships; edges record them. *Provider* stops being a category at the same time.

 **Whether "group or leave" is even the right pair of options** — *it was not*, and that is the
-useful finding. [ADR 0019](../../02-DECISIONS/0019-modules-and-the-graph.md)
+useful finding. [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md)
 reframes it: things that change together share an **authority**, not a package. This effort's own
 measurement is what that record rests on — reachability being the *only* place modules genuinely
 co-change is why connectivity is a context and why nothing else needed one.
@@ -10,7 +10,7 @@ updated: 2026-08-23
 Every commit in the code repository's main branch that touches the module catalogue, reduced
 to the set of modules it touched. Platform-namespace modules are excluded — their
 decomposition is settled by
-[ADR 0008](../../02-DECISIONS/0008-mesh-brokers-nodes-host-agents-think.md). Modules that no
+[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md). Modules that no
 longer exist are excluded, because pre-rename names dominate the raw signal and describe a
 catalogue nobody works in.

@@ -95,14 +95,14 @@ remainder are genuine:
 | 2026-08-06 | firewall mesh-only by default, public by declaration |

 Each is one intent — *change how a node is reachable* — landing across the proxy, the
-resolver, the firewall and the VPN together. That is exactly the shape ADR 0017 describes, and
+resolver, the firewall and the VPN together. That is exactly the shape ADR 0022 describes, and
 it is the only place in the catalogue where the measurement finds it.

 The 2026-08-23 scoping commit is the sharpest case: it spans the reachability cluster **and**
 two providers, because "which network is this exposed on" is a reachability question asked of
 a database.

-## What this means for ADR 0017
+## What this means for ADR 0022

 The record's principle stands, and its scope needs narrowing. Grouping by domain is:

@@ -130,7 +130,7 @@ Asked directly, and stated as an opinion because it is not yet decided.
   is implementation selection, a substantially larger design with its own failure modes, and
   nothing currently asks for it.
 3. **It would hide which implementation serves a requirement** — the one place the mesh most
-   needs to be explicit, and precisely the indirection ADR 0017 warns grouping causes.
+   needs to be explicit, and precisely the indirection ADR 0022 warns grouping causes.

 A provider module is already exactly one purpose: it provisions one resource type. That is a
 boundary, not an accident of installation.