path: root/docs/glossary.md

# 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.