swarm-ca: state the store-is-world-readable rule once, not three times

`docs/swarm/ca.md` said it under *Constraints on the material* and again
under *Distributing the root*; this module's header said it a third time,
directly above a line already pointing at that doc.

Measured: 6-gram intersection between the module's comments and the doc,
32 -> 6. The sentence now appears once in the tree.

Module header keeps what a reader editing this file cannot see from the
config: that one root makes cross-hive trust O(1), that the two
provisioning modes differ only in who writes the artifacts, and the ⚠️
that both root key and root cert are runtime files — the cert as a
consequence, and that one costs something real, since nothing whose trust
store is built at build time can name it. Everything behind those is a
`docs/x.md::Section` pointer with the heading checked to exist.

Dropped the O(n²)-per-peer-pinning story: the live reason is that one root
is O(1), and how it used to be configured is history.

In the doc, *Distributing the root* now links to *Constraints on the
material* rather than restating it. Intra-doc `#anchor` links are already
the convention there — 85 of them across `docs/`, 8 in `gateway.md` alone.

Comments + one doc paragraph; no behaviour change. Refs #3901.
This commit is contained in:
atlas 2026-09-02 05:36:42 +02:00 committed by mara
commit 83bbd7a5ea
2 changed files with 13 additions and 28 deletions

View file

@ -154,9 +154,8 @@ this: it self-signs exactly as it always has.
## Distributing the root
The root **key** is a runtime file for an obvious reason: the nix store
is world-readable and content-addressed, so a key committed to a flake
is a key *published* to every consumer of that flake.
The root **key** is a runtime file for the reason in
[Constraints on the material](#constraints-on-the-material).
The root **certificate** is a runtime file as a *consequence* — it lives
beside the key under `swarm.ca.stateDir` — and that has a cost worth