jschoubben
f49d177a31
0054 -- things that change together share an authority, not a package. The constitution instructs agents to group "how a node is reachable" into one module, citing superseded ADR 0017; ADR 0044 says there is no networking thing to install. Since the constitution is injected where work is decided, the superseded rule is the one actually steering work. The observation behind it was right -- research 005 measured that reachability is the only place modules genuinely change together -- but the conclusion was wrong: tight coupling means a shared authority, not one artifact. wireguard and traefik deploy to different node sets, so the merged module would be assigned where half is unwanted. Requires amending how-we-build and republishing the derived page. 0055 -- the control plane is the node-coordinating contexts. Three context lists were in circulation (0015 says nine, 06 says ten, the README said eight) and none was decided. Research 006 said explicitly that the change "belongs in a new record -- not written here", and the design used the list anyway. Reconciling them shows `stream` and `ai` were dropped with no reasoning at all. Applying 06's own test -- needs to know about more than one node -- gives seven contexts plus the api, with work, knowledge and stream as hosted applications and `ai` folded into config as an ordinary grant. The record defers rather than lists. The cost is stated rather than reassured away: a board composing across the boundary reads more than one interface. That was raised before as "only moves the problem up a layer", and the answer is that 0045 already requires surfaces to read interfaces rather than stores -- what changes is the count, not the kind of work. 0056 -- the authority is the control plane, not a database. Every clause of 0003 has been decided against in four separate records and it is still accepted and cited as live. The error underneath is the same category error 0054 corrects: "source of truth" named a storage location when it meant an authority, and once the store is the answer, shared schemas follow. The half that was right -- the repository defines what exists, the mesh defines what runs where -- survives untouched. Best consequence: the cache mode disappears, so a node that has not heard from the mesh is no longer indistinguishable from one that has. 0003 is left accepted until 0056 is.
112 lines
6.0 KiB
Markdown
112 lines
6.0 KiB
Markdown
---
|
|
status: proposed
|
|
date: 2026-08-27
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 0044-a-module-declares-presence-instantiation-and-exclusion.md
|
|
---
|
|
|
|
# 54. Things that change together share an authority, not a package
|
|
|
|
## Context
|
|
|
|
[`how-we-build.md`](../00-META/how-we-build.md) — the constitution, injected wherever work is
|
|
decided ([ADR 0009](0009-the-mesh-is-governed-by-a-constitution.md),
|
|
[ADR 0025](0025-hq-is-the-source-of-the-constitution.md)) — carries this rule:
|
|
|
|
> ### Group by domain, not by single function
|
|
>
|
|
> A module is a purpose, not a piece of software. Four modules that together constitute "how a
|
|
> node is reachable" and cannot be assigned, versioned or replaced as one thing are four
|
|
> accidents, not four boundaries. — ADR 0017
|
|
|
|
**[ADR 0017](0017-modules-outside-the-core-are-grouped-by-domain.md) is superseded**, and
|
|
[ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md) says the opposite in
|
|
as many words:
|
|
|
|
> The domain module goes with it: **there is no `networking` thing to install, there are
|
|
> concrete modules named individually.**
|
|
|
|
So the governing document instructs agents to do the thing the decision record forbids. This is
|
|
not a stale citation in a design note — it is
|
|
[ADR 0040](0040-the-constitution-absorbs-what-is-enforced.md)'s concern running backwards, in the
|
|
one document whose entire purpose is to be followed.
|
|
|
|
**The example makes it concrete.** *"How a node is reachable"* is exactly the case
|
|
[`08-connectivity.md`](../03-DESIGN/01-to-be/08-connectivity.md) has now designed — and the
|
|
design resolves it the other way: five responsibilities under one **context**, delivered by
|
|
individual modules with edges between them. Anyone following the constitution would build the
|
|
merged `networking` module that 0044 removed and 08 does not have.
|
|
|
|
## What was right about the old rule
|
|
|
|
The rule is not simply wrong, and replacing it badly would lose something measured.
|
|
|
|
[Research 005](../01-RESEARCH/005-domain-grouping/analysis.md) surveyed the whole catalogue and
|
|
found that reachability is **the only** place where modules genuinely change together under one
|
|
intent — the proxy with the resolver, the firewall with the overlay, repeatedly. That is a real
|
|
observation about coupling, and the smell it identifies is real: four things that always change
|
|
together and cannot be reasoned about separately are not four boundaries.
|
|
|
|
**The observation was right and the conclusion was wrong.** Coupling that tight means they share
|
|
an *authority* — one place that decides for all of them. It does not mean they should be one
|
|
installable artifact, and merging them into one is how the observation gets acted on badly:
|
|
`wireguard` and `traefik` are deployed on different sets of nodes, so a module containing both
|
|
would be assigned where half of it is unwanted.
|
|
|
|
## Decision
|
|
|
|
**Things that change together share an authority, not a package.**
|
|
|
|
Two units, deliberately separate, and conflating them is what ADR 0017 did:
|
|
|
|
| | is | example |
|
|
|---|---|---|
|
|
| a **context** | the unit of **coherence** — one authority, one store, one set of decisions | `connectivity` decides the overlay, names, routes, filtering and certificates |
|
|
| a **module** | the unit of **delivery** — assignable, versionable, replaceable on its own | `wireguard`, the resolver, the proxy, the firewall — four, named individually |
|
|
|
|
**When several modules always change together, the answer is to name the context that decides for
|
|
them** — not to merge them. Connectivity is the worked example and the proof: one authority, five
|
|
responsibilities, four or more separately assigned modules, and no `networking` module anywhere.
|
|
|
|
**Relationships are edges, not folders**
|
|
([ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md)). What grouping was
|
|
for — finding things, seeing what belongs together — is a tag and a query, neither of which
|
|
anybody has to keep true by hand.
|
|
|
|
### The constitution is amended
|
|
|
|
The section *Group by domain, not by single function* is **replaced**, not repaired, and the
|
|
derived page republished ([ADR 0025](0025-hq-is-the-source-of-the-constitution.md)). The
|
|
replacement keeps the observation and changes the instruction:
|
|
|
|
> ### Things that change together share an authority, not a package
|
|
>
|
|
> When several modules always change together under one intent, name the context that decides
|
|
> for them. Do not merge them: they are delivered to different nodes, and a module that must be
|
|
> assigned where half of it is unwanted is not a boundary either. Coherence is a context;
|
|
> delivery is a module. — ADR 0054
|
|
|
|
## Consequences
|
|
|
|
- **The instruction now matches the design.** An agent reading the constitution and an agent
|
|
reading 0044 reach the same answer, which they currently do not.
|
|
- **The republication is the point, not a formality.** Until the derived page is regenerated the
|
|
mesh is still governed by the old rule, and this record has changed nothing where it matters.
|
|
Verified by reading the rule back out of the published page
|
|
([ADR 0035](0035-a-picture-is-read-from-what-runs.md)), not by the publish reporting success.
|
|
- **`context` becomes a word the constitution uses**, which raises the obvious next question —
|
|
*which contexts are there* — and that is
|
|
[ADR 0055](0055-the-control-plane-is-the-node-coordinating-contexts.md), not this record.
|
|
- **This is the second time a superseded record was found still steering work.** The first was
|
|
the to-be README citing 0017 for work still to do. Both were found by a review rather than by
|
|
anything automatic, and nothing stops the third — **a superseded record has no mechanism that
|
|
finds its live citations.** Worth an issue in its own right.
|
|
|
|
## References
|
|
|
|
- [ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md) — what superseded 0017.
|
|
- [ADR 0025](0025-hq-is-the-source-of-the-constitution.md) — why amending the source is not enough.
|
|
- [Research 005](../01-RESEARCH/005-domain-grouping/analysis.md) — the measurement the old rule rested on.
|
|
- [`08-connectivity.md`](../03-DESIGN/01-to-be/08-connectivity.md) — the worked example.
|