From c148066de446c73230023eec830eb018d162822b Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 10 Oct 2026 18:14:28 +0200 Subject: [PATCH] Open research 044: what leaves the controller next Every controller change walks the core's tier and holds up every other walk (issue 382), while most of the week's change sat in one package. Framed as questions: which domain changes most and needs the core least. --- .../00-overview.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 01-RESEARCH/044-what-leaves-the-controller-next/00-overview.md diff --git a/01-RESEARCH/044-what-leaves-the-controller-next/00-overview.md b/01-RESEARCH/044-what-leaves-the-controller-next/00-overview.md new file mode 100644 index 00000000..7f5e87b3 --- /dev/null +++ b/01-RESEARCH/044-what-leaves-the-controller-next/00-overview.md @@ -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.