From 54bcc0e4ee8e1e6a29e0e01369c2ba95b27abce8 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 03:48:03 +0000 Subject: 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": ""`), 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. --- docs/guides/federation/upgrades.md | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) (limited to 'docs/guides/federation/upgrades.md') 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. - -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 is judged at an event's history changes by a revision of federation 1, which a +version names by its ID (`"revision": ""`); 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. + +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). -- cgit v1.3.1