2026-08-23 19:21:14 +00:00
3 changed files with 209 additions and 1 deletions
@@ -0,0 +1,60 @@
 ---
 status: active
 initiated: 2026-08-23
 touches:
  - 02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md
  - 03-DESIGN/00-as-is/10-module-catalogue.md
  - 03-DESIGN/00-as-is/02-modules-and-manifests.md
 became: []
 ---
 # 005 — Which domains the catalogue groups into
 [ADR 0017](../../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md) settles
 that modules outside the platform core are grouped by domain rather than by single function,
 and deliberately does not settle the list. This effort settles the list — and, first, tests
 whether the premise survives measurement.
 ## What is being investigated
 Eighty-nine modules sit outside the platform core. The question is which of them belong
 together, and the method is evidence rather than intuition: **which modules actually change
 together**, measured across the full history of the code repository.
 ## Why
 The argument in ADR 0017 is that the catalogue's shape records what was installed rather than
 what anything is for — that four modules constituting "how a node is reachable" have no
 relationship the mesh can see, so a change to connectivity is made four times.
 That argument is testable. If those modules genuinely change together, the grouping is
 justified by more than tidiness. If they do not, the premise needs revising before a list is
 drawn from it.
 ## What it touches
 The catalogue's shape, the manifest, and — for one candidate grouping — the provisioning
 reference itself, since a requirement names a provider **module**. Grouping providers would
 change what a consumer names.
 ## Status
 Measurement is done and is in [`analysis.md`](analysis.md). It **partly contradicts the
 premise**, in a way that narrows the effort usefully:
 - Non-platform modules overwhelmingly change **alone** — 10% of commits touch more than one,
  and 50 of 89 never co-change with anything.
 - Two clusters do exist. One of them, reachability, holds up as a domain.
 - The other, the provisioned infrastructure providers, co-changes for a reason that argues
  **against** grouping rather than for it.
 The remaining work is the list itself, for the modules where grouping is justified, plus the
 open questions below.
 ## Open questions
 | Question | Why it is open |
 |---|---|
 | Whether provider modules group at all, and if so what a consumer's requirement names instead of a module. | The provisioning reference is load-bearing; getting it wrong is expensive. Opinion and evidence in the analysis; not yet decided. |
 | Whether applications group into domains now and leave the monorepo later as a unit, or leave first. | Decided in principle — group first, then split — but the migration order has real cost either way. |
 | What to do with the ~50 modules that co-change with nothing. | The evidence gives no grouping signal for them at all. That may mean they are correctly sized already. |
@@ -0,0 +1,144 @@
 ---
 effort: 005-domain-grouping
 updated: 2026-08-23
 ---
 # Which modules actually change together
 ## Method
 Every commit in the code repository's main branch that touches the module catalogue, reduced
 to the set of modules it touched. Platform-namespace modules are excluded — their
 decomposition is settled by
 [ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md). Modules that no
 longer exist are excluded, because pre-rename names dominate the raw signal and describe a
 catalogue nobody works in.
 Commits touching more than eight modules are excluded from pair counting: a sweep across
 forty modules says the sweep happened, not that the modules are related.
 ## Finding 1 — these modules overwhelmingly change alone
 | Measure | Value |
 |---|---|
 | Non-platform modules today | 89 |
 | Commits touching at least one | 312 |
 | Commits touching two to eight together | 33 — **10%** |
 | Modules that never co-change with anything | **50 of 89** |
 Nine commits in ten touch exactly one module. More than half the catalogue has never been
 edited alongside anything else.
 This is the first thing a grouping proposal has to survive, and it is not what the premise
 predicts.
 ## Finding 2 — two clusters exist
 Everything above two co-changes falls into one of two groups.
 **The provisioned infrastructure providers.** The densest cluster: the relational stores with
 each other and with the cache, the broker, the object store and the image registry — a
 strongly connected set, six to two co-changes per pair.
 **Reachability.** The reverse proxy with the resolver, the firewall and the VPN; the firewall
 with the intrusion filter. Three to two co-changes per pair.
 Outside those: a torrent client with the VPN, twice. A login manager with a media player,
 twice. Nothing else reaches two.
 ## Finding 3 — the provider cluster is manifest churn, not cohesion
 This is the result that matters, and it is only visible by reading the commits rather than
 counting them.
 Every multi-provider commit is a **cross-cutting change to the machinery, applied N times**:
 | Date | What the commit did |
 |---|---|
 | 2026-04-15 | modules own their tools — decentralised tool serving |
 | 2026-04-24 | filesystem-driven feature detection; manifest boilerplate removed |
 | 2026-04-27 | remove runtime dependencies that were only build dependencies |
 | 2026-05-01 | hooks move into their own directory with their own package |
 | 2026-05-05 | hooks renamed to a stage-and-feature convention; legacy install scripts removed |
 | 2026-08-06 | verify **by shape in the SDK**, not by copying a script into every module |
 | 2026-08-11 | bind declared volume paths that leaked an anonymous volume per deploy |
 | 2026-08-23 | scope services to the local network and mesh; respect the profile gate |
 **Not one of them is a change to what a database is.** They are all "the manifest contract
 changed, therefore every manifest changed".
 Two consequences follow.
 Merging the providers into one module would not have prevented a single one of these commits.
 It would have made the same edit land in one file rather than six — which is a diff-size
 improvement, not a boundary.
 And the history already shows the correct fix being applied, repeatedly and successfully:
 *verify by shape in the SDK, not by copying a script into every module*. When the same edit
 must be made in every provider, the answer that worked was **moving the concern into the
 machinery**, not merging the modules that carry it.
 Co-change here measures coupling to the manifest contract. It does not measure domain
 cohesion, and using it as though it did would group the catalogue by which modules are most
 boilerplate-heavy.
 ## Finding 4 — reachability holds up
 The same reading applied to the reachability cluster gives a different answer. Most of its
 twenty-five multi-module commits are the same machinery churn — but not all, and the
 remainder are genuine:
 | Date | What the commit did |
 |---|---|
 | 2026-07-29 | let the mesh's proxy coexist with another listener on the same port |
 | 2026-08-03 | derive public split-DNS from node accessors so requests stop hairpinning |
 | 2026-08-06 | firewall mesh-only by default, public by declaration |
 Each is one intent — *change how a node is reachable* — landing across the proxy, the
 resolver, the firewall and the VPN together. That is exactly the shape ADR 0017 describes, and
 it is the only place in the catalogue where the measurement finds it.
 The 2026-08-23 scoping commit is the sharpest case: it spans the reachability cluster **and**
 two providers, because "which network is this exposed on" is a reachability question asked of
 a database.
 ## What this means for ADR 0017
 The record's principle stands, and its scope needs narrowing. Grouping by domain is:
 - **Justified by evidence** for reachability. One intent, several modules, repeatedly.
 - **Argued against by evidence** for the providers. The coupling is to the manifest contract,
  and the demonstrated fix is to move the concern into the machinery.
 - **Unsupported either way** for the fifty modules that co-change with nothing. Silence is not
  evidence of independence — many are simply rarely touched — but there is no measured basis
  for grouping them, and a proposal that groups them is drawn from intuition. It should say so.
 The catalogue's shape is still wrong in the way the record describes. Measurement says
 grouping is the right fix in fewer places than the record implies, and that a second fix —
 moving cross-cutting concerns into the machinery — accounts for most of what looks like
 grouping pressure.
 ## Recommendation on the provisioning reference
 Asked directly, and stated as an opinion because it is not yet decided.
 **Do not group the provider modules.** Three reasons, in order of weight:
 1. **The evidence for grouping them is the wrong evidence.** Finding 3.
 2. **A requirement names a provider module.** Grouping providers means a consumer names a
   resource type and something else chooses the implementation. That is not a folder move; it
   is implementation selection, a substantially larger design with its own failure modes, and
   nothing currently asks for it.
 3. **It would hide which implementation serves a requirement** — the one place the mesh most
   needs to be explicit, and precisely the indirection ADR 0017 warns grouping causes.
 A provider module is already exactly one purpose: it provisions one resource type. That is a
 boundary, not an accident of installation.
 ## Still to do
 - Draw the list for the cases where grouping is justified, and say plainly which entries rest
  on measurement and which on judgement.
 - Decide the ~50 silent modules: correctly sized, or unmeasured?
 - Test the reachability grouping against the migration cost — the modules in it are among the
  most-changed in the catalogue, so churn during a move is not hypothetical.
@@ -81,7 +81,11 @@ metrics, storage and data services — but naming them here would be reconstruct
 that has not been taken.
 Settling the list is a research effort, not an act of this record. Until it concludes, this
-ADR stays `proposed`.
+ADR stays `proposed`. That effort is
 [`01-RESEARCH/005-domain-grouping`](../01-RESEARCH/005-domain-grouping/00-overview.md), and its
 first measurement already narrows this record's scope: co-change analysis supports grouping for
 reachability, argues against it for the provisioned infrastructure providers, and finds no
 signal either way for the fifty modules that never change alongside anything.
 ## References