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.