Merge pull request 'Research 044: what leaves the controller next' (#287) from research/044-what-leaves-the-controller-next into main

2026-10-10 16:17:30 +00:00
parent 62efd13e07 c148066de4
commit 3c323370b7
1 changed files with 99 additions and 0 deletions
@@ -0,0 +1,99 @@
+---
+status: active
+initiated: 2026-10-10
+touches:
+  - 03-DESIGN/01-to-be/06-the-controller.md
+  - 03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md
+  - 03-DESIGN/01-to-be/46-the-conversation-with-the-operator.md
+  - 02-DECISIONS/0008-a-context-owns-its-store.md
+  - 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md
+  - 02-DECISIONS/0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md
+  - 02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md
+  - 02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md
+  - 02-DECISIONS/0276-merges-are-assembled-in-a-rolling-window-and-each-batch-is-delivered-by-one-walk-with-one-commit-per-repository.md
+  - the controller's code and the walk of its builds
+became: []
+---
+
+# 044 — What leaves the controller next
+
+## What
+
+Which part of the controller should move into a module of its own next, chosen by evidence rather
+than by taste: the domains whose code changes most often and needs the core least. The effort frames
+the questions below and answers none of them yet; the research itself is done separately.
+
+The controller has shed parts before. Deliveries moved to the `mesh-delivery` module
+([ADR 0239](../../02-DECISIONS/0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md)),
+issues to the issue tracker held by `mesh-issues`
+([ADR 0275](../../02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md)),
+and reading the record to the `records` module
+([ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)).
+This effort asks what comes after those three, and whether the way they moved is a pattern worth
+repeating.
+
+## Why
+
+The controller is the component that changes most and costs most to change. Measured on the
+controller's `main` branch on 2026-10-10:
+
+- 191 merges in the 7 days before.
+- About 104,000 lines of Go outside tests. About 44,000 of them sit in one package (`cmd/mesh-controller`,
+  94 files), which took about 60% of the week's file changes. The next packages by share of change were
+  `internal/catalogue`, `internal/inventory`, `internal/broker` and `internal/link`.
+
+Every controller change, however small, walks the core's tier through the first-node gate, and only one
+walk is open at a time
+([ADR 0276](../../02-DECISIONS/0276-merges-are-assembled-in-a-rolling-window-and-each-batch-is-delivered-by-one-walk-with-one-commit-per-repository.md)).
+Issue 382 in the issue tracker (a small fix takes 45 minutes to reach a node) measured the cost on
+2026-10-10: a notification fix merged at 14:46 had not reached its node at 15:08, because it waited
+behind two other walks, and each tier costs about 4 to 5 minutes. A change to a part that does not
+need to be in the controller still pays that price, and still holds up every other walk while it does.
+
+## The questions
+
+1. **Where the change goes, by domain.** Group the last month's controller merges by the domains of
+   [ADR 0244](../../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)
+   (Module, Core, Placement, Provisioning, Identity and access, Change and delivery, Health and repair,
+   Data, Connectivity, Operator and conversation). How is a merge assigned to a domain when it touches
+   several, and how many merges cannot be assigned at all? Is the domain of a file, a package or a verb
+   the better unit?
+2. **Which domains are worth moving.** Rank the domains by their rate of change multiplied by how little
+   they need the core: how few of the controller's stores they read, how few of its verbs they call
+   in-process, and whether they could do their work through the bus alone. Which signal of "needs the
+   core" can be measured from the code, and which only by trying?
+3. **The candidates to test against that ranking.**
+   - The probes, conditions and the hand-act log as a monitoring module (to-be 45), raising and
+     clearing conditions on the bus.
+   - The asks, proposals and the wording of notifications, moved to the operator's channel side
+     (to-be 46).
+   - The machine's network checks
+     ([ADR 0241](../../02-DECISIONS/0241-a-machine-says-how-its-network-is-and-an-outside-writer-of-a-mesh-file-is-a-finding.md)).
+
+   For each one: what it reads from the controller today, what it writes there, and what would break
+   if the controller were not reachable while it ran.
+4. **What must stay.** Deciding what each node runs is the controller's reason to exist (to-be 06).
+   Where exactly does that boundary run: does the catalogue's reading, the inventory, the broker or the
+   link belong inside it or beside it? What is the smallest controller that still decides every node?
+5. **How a domain moves out without a flag day.** How did the earlier three move: served in both places
+   for a while, a seat verb promised before it is required
+   ([ADR 0246](../../02-DECISIONS/0246-a-seats-new-verb-is-promised-before-it-is-required.md)), a store
+   handed over ([ADR 0008](../../02-DECISIONS/0008-a-context-owns-its-store.md))? What went wrong in those
+   moves, and what does a move need so that no node and no caller sees a gap?
+6. **How the effect is measured afterwards.** Which numbers say a move worked: controller merges per week,
+   the time from merge to a node running the fix, the share of walks that touch the core's tier, the
+   number of walks waiting behind a controller walk. What is their baseline today, and where are they
+   read from, so that the same measurement can be repeated after each move?
+
+## Words
+
+The glossary has no word for "how little a domain needs the core". This effort uses **coupling to the
+core** as a plain description until a decision settles a word. "Monitoring module" is also a plain
+description, not a glossary word; the glossary's words for what it would hold are **probe**,
+**condition** and **hand-act**.
+
+## What it touches
+
+The controller's design and code (to-be 06), the core that cannot fail silently (to-be 45), the
+conversation with the operator (to-be 46), the walk of builds (ADR 0276), and the earlier extractions
+(ADR 0153, ADR 0239, ADR 0275) as precedent.