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.
118 lines
6.5 KiB
Markdown
118 lines
6.5 KiB
Markdown
---
|
|
status: accepted
|
|
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.
|
|
- **Synced 2026-08-27**, playbook [05](../00-META/process/05-constitution-sync.md). 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](0025-hq-is-the-source-of-the-constitution.md) predicted and the reason the playbook
|
|
re-publishes the whole page rather than patching a section.
|
|
- **`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.
|