roots: an epoch's root pinned, and named in every handshake

Review 2, N7, the care it raised: a joining node's empty document took
as the first epoch's root whatever dependency-less change came first,
from whichever peer it joined through; the first epoch's ID is all
zeros, so nothing pinned it. A remake's epoch has its ID, the snapshot
change's hash, which the rules hold its root to.

* Every node names its epoch's root in HELLO and HELLO_REPLY (the
  epoch's ID for a remake's, its genesis change for the first; wire
  version 45). A node whose document starts from another root of the
  same epoch refuses the handshake, logging it: another history under
  the swarm's ID, a forged root or a genesis started again.
* A joining node with an empty document takes as its root only the one
  it was given (--genesis-root, new), else the one its peers name, and
  none while they name different ones (access::screen::RootPin, kept
  in Screening across documents): one peer hands it another root only
  if it is all the joiner hears, or never, with --genesis-root. A root
  refused is listed with the refused, what builds on it with it.
* The genesis node logs the root (`The swarm's root`); GET
  /admin/epochs shows it (`root`).

A genesis started again under a remembered swarm ID used to merge with
the nodes of it still running; they now refuse it (another root), and
the docs say to join them with seeds instead.

The epoch's identity stays as it is (generation 0 all zeros): records
and epoch metadata name it so, and every comparison of epochs with
them.

4 files changed, 21 insertions, 1 deletions

diff --git a/docs/access.md b/docs/access.md
index c5365b7..782724a 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -318,6 +318,16 @@ policy's own change and everything after it, as every other node does. While nei
 its document nor what it receives holds a policy, it judges only that a root is the
 epoch's, and nothing costs more than applying the changes.
 
+An epoch's root is pinned. A remake's is its epoch's ID, the hash of its snapshot. The
+first epoch's is its genesis change, which its genesis node logs (`The swarm's root`)
+and `GET /admin/epochs` shows (`root`). Every node names its root in its handshakes: a
+node whose document starts from another root of the same epoch refuses the handshake
+(another history under the swarm's ID: a forged root, or a genesis started again).
+A node joining with an empty document takes as its root only the one it was given
+(`--genesis-root`), or else the one its peers name, and none while they name different
+ones. So one peer hands a joiner another root only if it is all the joiner hears, or
+never, with `--genesis-root`.
+
 What it doesn't do yet:
 
 * **Prove the user.** A change is its node's (with signatures required, proven) and its
diff --git a/docs/example.toml b/docs/example.toml
index d5af848..70d65b2 100644
--- a/docs/example.toml
+++ b/docs/example.toml
@@ -105,6 +105,12 @@ htpasswd = "/etc/continuum/htpasswd"
 # together at most.
 # key-logins-per-user = 100
 
+# The hash of the swarm's genesis change (hex, as its genesis node logs it and GET
+# /admin/epochs shows it): joining with an empty document, the only root this node
+# takes. Without, the one its peers name, none while they name different ones
+# (docs/access.md).
+# genesis-root = "…"
+
 # SSH keys, as authorized_keys lines (ssh-ed25519 <base64> [comment]), whose signature
 # on a strict remake's manifest this node takes: the values kept when the swarm turns
 # strict (docs/access.md). Without, it votes for no strict remake; a majority of the
diff --git a/docs/lifecycle.md b/docs/lifecycle.md
index 9fe9442..829e425 100644
--- a/docs/lifecycle.md
+++ b/docs/lifecycle.md
@@ -62,7 +62,7 @@ Then the node is either ready at once or joining:
 
 | Start | Without a remembered swarm | With one (state file) |
 |---|---|---|
-| `--genesis` | a new swarm, ready at once | that swarm again, empty; nodes of it still running merge with this one |
+| `--genesis` | a new swarm, ready at once | that swarm again, empty, from a new root, which nodes of it still running refuse (to join them, give seeds) |
 | document file holding a document | ready at once, on the document's swarm and epoch | the same; the two must name the same swarm |
 | `--recover-from` | ready at once, on the backup's swarm and epoch | the same; the two must name the same swarm |
 | seeds, or none | joining through the seeds | joining that swarm, through the seeds and the remembered members |
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index bb017f0..4a49d2b 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -3100,6 +3100,10 @@ components:
       properties:
         current:
           $ref: '#/components/schemas/Epoch'
+        root:
+          type: string
+          nullable: true
+          description: The hash of the epoch's root (hex), where the document holds it - for the first epoch, its genesis change, which a joining node may be given (`--genesis-root`).
         archived:
           type: array
           items: