add documentation

1 files changed, 154 insertions, 0 deletions

diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 0000000..71d3014
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,154 @@
+# Glossary
+
+The words used in the code, logs, API and docs, and what they mean here.
+
+## Nodes and the swarm
+
+**node**: a running continuum instance, together with its transports (and a Mycelium
+daemon it supervises), document, lifecycle (Joining, Ready, Rejoining), API and log. The word for what a single instance
+does: "the node becomes ready", "a new node joins". Rule of thumb: say *node* when
+nobody else is involved.
+
+**peer**: another node, seen from one node's side. Always relative to someone, which
+is why `PeerState`, `/peers` and dormancy are per peer. "A node forgets a dormant peer"
+reads right; "a peer becomes ready" doesn't. Rule of thumb: say *peer* when you mean
+"the other side" or "the others".
+
+**swarm**: all the nodes together, sharing one document. Identified by the **swarm
+ID**, which the genesis node chooses and records in the document (`_continuum/swarm`). An optional **swarm key** (`--swarm-key-file`)
+is a shared secret every node must prove in the handshake.
+
+**node ID**: who a node is, `continuum:<hex>`, from its **node key**
+(`--node-key-file`); the same whatever transport reaches it. An **address** says where
+a node is on one transport (`mycelium:<public key>`); a node proves its node ID at an
+address with WHO and ME ([`peers.md`](peers.md)).
+
+**seed**: something that can be resolved to reach a node (`--seeds`): an address on
+any transport, or a transport's own short form (for Mycelium a public key, an IPv6
+address, or a host name with an AAAA record for one; [`transports.md`](transports.md)).
+
+**state file**: what a node remembers across restarts (`--state-file`): its swarm ID
+and some members to rejoin through. Not the document.
+
+**document file**: a node's document on disk (`--document-file`), with the actor IDs
+it wrote with; the node resumes with it after a restart.
+
+**standing** of a peer, from one node's side (`Standing`):
+* **stranger**: has sent us something, nothing more.
+* **admitted**: proved the swarm key (or there is none).
+* **member**: completed the handshake and belongs to our swarm. Only members sync.
+
+**registered member**: a node listed in the swarm's member registry
+(`_continuum/members/<node ID>`), which every node writes for itself once ready.
+The registry, not the handshake, decides the topology and who votes on remakes. When
+the context doesn't make clear which is meant, say *registered member*.
+
+**neighbour**: a member this node keeps alive and syncs with on its own (keepalives,
+sync openings, relay). Up to `--neighbours` (k) of them, chosen from the registry
+(`swarm::topology`); with at most k + 1 reachable members, everyone is everyone's
+neighbour (**full mesh**). Other members are only answered.
+
+**alias**: the name a node gives itself (`--alias`), published in the registry. Not
+unique, never an identity; the node ID is.
+
+**dormant**: a peer we haven't heard from for 4 × keepalive. It is probed rarely and
+left out of the topology until it answers again.
+
+**stability tier**: what a node judges about itself and publishes in the registry. It
+becomes **stable** once it was connected at least 95 % of a full day, and **transient**
+again below 80 %. Stable members are preferred as neighbours, forming a backbone.
+
+**alive stamp**: the time a node last renewed its registry entry (about daily). Nodes
+renewed within `--electorate-window` form the electorate of a remake.
+
+## The document and sync
+
+**document**: the replicated Automerge document. The store API reads and writes paths
+in it.
+
+**protocol data**: what the nodes keep under `_continuum` in the document: the swarm
+ID, the member registry, forget records, remake records, the votes register and epoch
+metadata. Only users listed in `--protocol-writers` may change it through the store
+API; the swarm ID and epoch metadata never.
+
+**heads**: the hashes of the document's latest changes, those no other change depends
+on. Several heads mean concurrent changes that no later change has merged yet. Two
+nodes with the same heads have the same document.
+
+**opening**: the first sync message to a peer after a reset, before anything has come
+back from it. After `reset_sync()` the Automerge `sync::State` is new, so
+`their_heads`, `their_have` and `their_need` are all unset; an opening can only say
+"these are my heads, here is a Bloom filter of what we share", and carries no changes
+since we don't know yet what the peer has. The code doesn't track openings
+separately: `their_heads.is_none()` means nothing has come from the peer since the
+reset. Who may open towards whom: [`peers.md`](peers.md), Handshake and join.
+
+**path**: an address of a peer on one of this node's transports (`<scheme>:<target>`). A
+peer with several (on several transports) is reached on the best: paths are measured
+with a **PING** each answered by a **PONG**, and a path that fails, or stops answering,
+is passed over for the next.
+
+**keepalive**: what a pair exchanges when it has been quiet for a keepalive interval
+(`--keepalive`): a PING and its PONG, and every third time a **STATUS** and its
+STATUS_REPLY instead, carrying the sender's heads (or a digest of them and some of
+them), epoch and readiness. The two sides of a pair take turns; the one that **leads**
+the pair sends the first.
+
+**initial sync**: a joining node's first complete sync. It's **caught up** once a ready
+peer with non-empty heads has nothing left that it lacks.
+
+**catch-up source**: the one peer a joining node syncs with while catching up, the
+closest by round-trip time first.
+
+**relay**: in a partial mesh, a node announces new heads to its neighbours, which pull
+the changes they lack.
+
+**blob**: bytes too large for one message, fetched in chunks from several peers at once:
+an epoch's snapshot change (for a rejoining node) or a remake's content (for voters).
+
+## Epochs and remakes
+
+**epoch**: one stretch of the document's life, from one remake to the next. Peers on
+different epochs don't sync. Identified by its **generation** and its ID (the hash of its
+snapshot change), shown as `generation:id`.
+
+**generation**: an epoch's counter: the number of remakes since genesis. It orders
+epochs, so a node can tell whether a peer is behind or ahead. Two epochs of the same
+generation (different IDs) can only come from concurrent remakes.
+
+**genesis**: the first epoch (generation 0), and the **genesis node** that started the
+swarm (started with `--genesis`, empty or with content from `--remake`).
+
+**remake**: a coordinated move of the whole swarm to a new epoch. Kinds:
+**compact** (same content, no history), **replace** (new content as JSON),
+**import** (new content as an Automerge document).
+
+**base**: the heads the new epoch's content accounts for. Writes made after them are
+carried over into the new epoch (**replayed**), at their path or where the remake's
+**rules** say: by every node that switches, and by their author when it rejoins. A compaction's base is the coordinator's
+heads when it commits; other kinds fix it when proposed.
+
+**snapshot**: the new epoch's first change, which every node builds itself, byte for
+byte the same; its hash is the epoch ID.
+
+**coordinator**: the node a remake was proposed to. It counts the votes and writes the
+decision. If it is gone for good, another node can **adopt** the remake and become
+its coordinator.
+
+**electorate**: the registered members whose votes count for a remake, fixed when it is
+proposed. The remake commits once a **majority** (the **quorum**: more than half) voted
+for it. Each member has one vote per epoch, kept in the **votes register**
+(`_continuum/votes`); it is free again only if that remake is aborted.
+
+**switch**: a node moving to a committed epoch by building its snapshot itself.
+
+**rejoin**: a node moving to a newer epoch by fetching it from peers instead (it was away,
+or its own build failed).
+
+**replay window**: how far behind a rejoining node may be and still have its own writes
+carried over automatically.
+
+**quarantine**: a node's own writes a remake couldn't place, kept on that node for an
+operator to replay or discard.
+
+**archive**: the documents of previous epochs a node keeps for a while.