jschoubben
e1f4c7d9e0
0003 is now superseded by 0056. Nothing is left proposed. Applied: - 06 corrected from ten contexts to seven plus the api, each row now stating why it passes the more-than-one-node test. work, knowledge and stream are named as mesh-hosted rather than dropped; `ai` folds into config; `record` is deferred explicitly rather than listed. Its frontmatter now cites 0055. - how-we-build §4 amended per 0054, and the derived page republished by playbook 05. The sync found the drift the playbook exists to catch: the published §4 and the source did not say the same thing. The source said "four accidents, not four boundaries"; the published page said "one intent expressed four times", and only the published page carried the scope caveat. Same rule, two texts, already diverging. Verified the republish by reading back -- the new rule is present and the old section's body returns nothing -- rather than trusting the success message. The two smaller findings: - 0051 separated the transport identity from the declaring authority. It said the token carries "an address" and "the identity to expect" without saying what the node dials. It dials the broker, so pinning only that would make the control plane's authority transitive and let a compromised broker forge declarations -- which, since the host applies whatever the link delivers, is the whole machine. The token now carries four things, and declarations are signed and verified per declaration. Cost recorded: rotating the signing identity is fleet-wide. - 0026 no longer restates 0022's rule about generated views. 0022's own words are "prose does not restate status; one place, and two is one too many", which is what 0026 was doing to it.
6.5 KiB
status, date, deciders, reconstructed, extends
| status | date | deciders | reconstructed | extends |
|---|---|---|---|---|
| accepted | 2026-08-27 | jochen | false | 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 — the constitution, injected wherever work is
decided (ADR 0009,
ADR 0025) — 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 is superseded, and ADR 0044 says the opposite in as many words:
The domain module goes with it: there is no
networkingthing 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'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 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 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). 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). 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.
- Synced 2026-08-27, playbook 05. The derived page carries the new rule and §4 keeps its number. Verified by reading back, not by the publish reporting success: the replacement text is present, and the old section's body — scope under measurement: grouping is evidenced for reachability — returns nothing.
- The sync found a drift the playbook exists to catch. The published §4 and the source did not say the same thing: the source spoke of four accidents, not four boundaries, the published page of one intent expressed four times, and only the published page carried the scope caveat. Same rule, two texts, already diverging — which is the exact failure ADR 0025 predicted and the reason the playbook re-publishes the whole page rather than patching a section.
contextbecomes a word the constitution uses, which raises the obvious next question — which contexts are there — and that is ADR 0055, 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 — what superseded 0017.
- ADR 0025 — why amending the source is not enough.
- Research 005 — the measurement the old rule rested on.
08-connectivity.md— the worked example.