From 439ca746d6f84686e7ebab1835b683ae689e4b81 Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:51:20 +0000 Subject: guides: upgrades and the federation's number Upgrading the nodes of a federated swarm, each party its own, close together; what the federation's number names, fixed by vectors; a version of another federation refused, and moving to the next one by a version. --- docs/guides/federation/README.md | 2 ++ docs/guides/federation/upgrades.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 docs/guides/federation/upgrades.md (limited to 'docs') diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index eb142e0..5d3538a 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -30,3 +30,5 @@ by them, in its words. is its own, the store file, dropping events and taking them back. * [`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. diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md new file mode 100644 index 0000000..945088d --- /dev/null +++ b/docs/guides/federation/upgrades.md @@ -0,0 +1,34 @@ +# Upgrades and the federation's number + +Upgrading the continuum a federated swarm's nodes run, and what the federation's number +in each version says. The rules are the design's +([`federation.md`](../../federation.md), Changing the federation). + +## Upgrading continuum + +A node of a federated swarm upgrades as any node does +([`operations.md`](../../operations.md), Upgrading): one at a time, restarted with its +files. Across a change of the wire format, upgraded nodes and the others don't talk, and +the swarm is split until all are upgraded; a remake needs the same Automerge on every +node, and one with another rejoins instead of switching. Until 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 + +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`). + +There is one federation, 1. A node knows it alone: a version naming another is none to +it, refused where a version event names it, with everything built on it. 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. -- cgit v1.3.1