aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 03:48:03 +0000
committertv <tv@krebsco.de>2026-11-19 05:10:06 +0100
commit54bcc0e4ee8e1e6a29e0e01369c2ba95b27abce8 (patch)
tree20568ac1b47394ae9e603630fe1ab5464d1f7900 /docs/guides/federation
parente5f8df2a78f26d5928d1c96573dae5620dba5e25 (diff)
federation: a version names the revision of federation 1 it follows
What every node must agree on was named by the federation's number alone, and a change that only took more kept it: a party could use it before every node ran it, and nodes not upgraded refused what followed and parted from the others. A version now names the revision it follows by its ID (`"revision": "<ID>"`), the SHA-256 of the JCS list of the features it adds to the base revision federation 1 began with (`federation::revision`); a version naming none follows the base revision, ECDSA keys among it, so the versions written so far read as they did. A version names the base revision only by leaving `revision` out, and a revision no earlier than the one of the version it changes. A continuum that doesn't know a revision, another build's among them, can't read a version naming it: it stops at a version event writing one, and says which revision and what it knows. There are no revisions yet but the base revision. `federation.md` says how a revision is rolled out, then passed, and what a later continuum may leave out; the upgrades guide, and the one on a node stopped, alike.
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/upgrades.md34
-rw-r--r--docs/guides/federation/when-things-go-wrong.md11
3 files changed, 23 insertions, 24 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index 5a44306..32f8756 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -31,7 +31,7 @@ by them, in its words.
* [`remakes.md`](remakes.md): compactions only, the electorate, the snapshot, putting
again after a switch, two epochs for one, and rejoining.
* [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, and what the
- federation's number says.
+ federation's number and its revision say.
* [`watching.md`](watching.md): what a node's API and its log say that needs an operator
or a party.
* [`building-on-the-api.md`](building-on-the-api.md): an application reading what
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index df01b05..a106137 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -16,14 +16,14 @@ continuum's first release, take every upgrade as such a change.
Nobody runs every node of a federated swarm: each party's operators upgrade its nodes.
Agree on when, among the parties, and upgrade close together.
-## The federation's number
+## The federation's number and its revision
What every node must agree on, byte for byte, is named by the federation's number,
-which every version gives (`"federation": 1`): the rules, how an event, a version and a
-checkpoint are spelled, signed and judged, what the events read as, and, on Automerge,
-what the document holds, what a change writes, the genesis change built from the root,
-the snapshot, and the Automerge version, whose encoding fixes a change's hash. Their
-bytes are fixed by vectors that the tests check (`federation::vectors`).
+which every version gives (`"federation": 1`), and its revision: the rules, how an event,
+a version and a checkpoint are spelled, signed and judged, what the events read as, and,
+on Automerge, what the document holds, what a change writes, the genesis change built from
+the root, the snapshot, and the Automerge version, whose encoding fixes a change's hash.
+Their bytes are fixed by vectors that the tests check (`federation::vectors`).
There is one federation, 1. A node knows it alone: a version naming another is none to
it. Where one passes, the node stops at the version event writing it, taking nothing and
@@ -32,16 +32,14 @@ that event ([`when-things-go-wrong.md`](when-things-go-wrong.md),
[A node stopped](when-things-go-wrong.md#a-node-stopped)). A proposal naming another is
taken as a proposal, and a party's client backs none.
-A change to any of that is a federation of its own, with the next number, and its own
-design. A swarm moves to it by a version naming it, which the parties pass once their
-nodes run a continuum that knows it.
+What is judged at an event's history changes by a revision of federation 1, which a
+version names by its ID (`"revision": "<ID>"`); a version naming none follows the base
+revision, `ecdsa-sha2-nistp256` keys beside Ed25519 ones among it. There are none yet but
+the base revision. A node that doesn't know the revision a version names reads it as it
+reads one of another federation: none, and it stops at a version event writing it. What a
+revision adds is taken only under a version naming it, which two thirds pass, so no party
+uses it early: roll it out first, every party's operators upgrading their nodes, then pass
+a version naming it.
-A change that only has the federation take what it refused, and reads nothing it took
-otherwise, keeps the number: `ecdsa-sha2-nistp256` keys beside Ed25519 ones. Roll it out
-first, then use it: every party's operators upgrade their nodes, and only then does a
-party name such a key in a version or a key set, or sign with one. A node not upgraded
-refuses what uses it and reads otherwise than the others; at a version naming such a key,
-none to it, it stops, until it is upgraded. Nothing but agreement keeps a party from using
-it early. The next such change names itself in the version, so that two thirds decide
-when it is used: what it adds is taken only under a version naming it, and a node not
-upgraded stops at that version.
+What no history judges, the document, a change and the snapshot, no version names: a
+change there splits the swarm until every node runs it (above).
diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md
index fad11c5..8171201 100644
--- a/docs/guides/federation/when-things-go-wrong.md
+++ b/docs/guides/federation/when-things-go-wrong.md
@@ -78,13 +78,14 @@ can't judge`), and `GET /events` names the event, why, and how many it holds bac
```sh
curl -s -u tv:secret localhost:3000/events | jq -r .stopped.why
-# version 3c0f… passed, and doesn't read as one here: of federation 2, and this
-# continuum knows 1 alone
+# version 3c0f… passed, and doesn't read as one here: revision 9f2c…, which this
+# continuum doesn't know, as it knows the base revision alone: a release that knows it
+# reads this version
```
-`why` says what doesn't read: a federation this continuum doesn't know, a field it
-doesn't know, by its name, a key of a type it doesn't take, or whatever else makes a
-version none ([`proposing-and-voting.md`](proposing-and-voting.md),
+`why` says what doesn't read: a federation or a revision this continuum doesn't know, a
+field it doesn't know, by its name, a key of a type it doesn't take, or whatever else
+makes a version none ([`proposing-and-voting.md`](proposing-and-voting.md),
[Writing a version](proposing-and-voting.md#writing-a-version)).
Upgrade the node to a continuum that reads it: restarted, it reads its store anew and