swarm neighbours

2 files changed, 11 insertions, 4 deletions

diff --git a/docs/example.toml b/docs/example.toml
index 00bfed3..3761496 100644
--- a/docs/example.toml
+++ b/docs/example.toml
@@ -170,9 +170,11 @@ htpasswd = "/etc/continuum/htpasswd"
 # other side of a partition, takes to be noticed. Default: 60 keepalives (1h at 1m).
 # dormant-probe-max = "15m"
 
-# Neighbours each node keeps (at least 2). Swarms of up to this many + 1 nodes are a
+# Neighbours each member keeps (at least 2). Swarms of up to this many + 1 nodes are a
 # full mesh; larger ones sync over several hops. With several transports, about this
-# many per transport.
+# many per transport. A genesis node records it in the document as the swarm's, which
+# every node uses; elsewhere it counts only in a swarm that recorded none (one from
+# before), and must then be the same on every node.
 # neighbours = 12
 
 # Members that renewed their alive stamp within this time vote on remakes (a majority of
diff --git a/docs/peers.md b/docs/peers.md
index 29512a5..2ff10e0 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -278,8 +278,13 @@ neighbours are its neighbours on each transport it is on: every transport's grap
 connected, and a member on two transports is in both, so as long as some members are
 on several, the swarm is connected, and those have about `k` neighbours per
 transport. With 100 members of which 10 are online,
-the 10 form a full mesh; nodes that briefly disagree on who is reachable only add links. `k` is `--neighbours` (default 12), so swarms of up to 13 nodes are a
-full mesh. A node *initiates* only towards its neighbours (HELLO, keepalive, dormancy
+the 10 form a full mesh; nodes that briefly disagree on who is reachable only add links. `k` is the swarm's: its genesis node records its
+`--neighbours` (default 12) in the document (`_continuum/neighbours`), and every node
+builds the graph with that value, since every node must build the same one (the
+writers' trees are built on it); a protocol writer may change it later, and every node
+then recomputes its neighbours and the trees. A swarm from before it was recorded has
+none, and each node uses its own `--neighbours`, which must then be the same
+everywhere. So swarms of up to `k` + 1 nodes (13 by default) are a full mesh. A node *initiates* only towards its neighbours (HELLO, keepalive, dormancy
 checks, sync openings, pushing its changes, epoch announcements, the heal, the peer list
 in HELLO_REPLY) and *answers* anyone. Changes travel over several hops; heads in
 keepalives tell a node when a neighbour has something it lacks. Until a node is ready