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/federation.md | 81 ++++++++++++++++---------- docs/guides/federation/README.md | 2 +- docs/guides/federation/upgrades.md | 36 ++++++------ docs/guides/federation/when-things-go-wrong.md | 11 ++-- 4 files changed, 74 insertions(+), 56 deletions(-) (limited to 'docs') diff --git a/docs/federation.md b/docs/federation.md index a547026..766c9a6 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -23,8 +23,9 @@ whoever wants to carry on with whom does so. Claims about the code are marked A swarm is federated from its genesis change, or not at all ([Starting a federation](#starting-a-federation)). Nothing else changes: a swarm that isn't stays as it is, its registry, rules, remakes and replay included. Which federation a -swarm follows is a number of its own, in each version of its policy: this design is -federation 1 ([Changing the federation](#changing-the-federation)). Any group carries on +swarm follows is a number of its own, in each version of its policy, with the revision of +it: this design is federation 1 +([Changing the federation](#changing-the-federation)). Any group carries on with the policy it wants by forking ([Forks](#forks)), and leaves the federation by starting a swarm of another kind, with what it takes along. @@ -203,8 +204,9 @@ current at its heads, [Forks](#forks)). Spread out: { "path": "names/**", "writer": false } ] } ``` -* **The federation** it follows, and its **number**, one more than that of the version - it changes. +* **The federation** it follows, its **revision** of it where that isn't the base + revision (`revision`, [Changing the federation](#changing-the-federation)), and its + **number**, one more than that of the version it changes. * **The parties and their keys** (`keys`): one party at least, each by name, as continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -`, with one key or more (`ssh-ed25519` or `ecdsa-sha2-nistp256`, [Events](#events)), none twice in the version. @@ -837,36 +839,53 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged. Every node of a swarm runs the same version of continuum today. A federated swarm's parties can't be made to upgrade together, so from the first federated swarm on, continuum's releases work together in one, and what all its nodes must agree on is named -by the federation's number: the rules of this design, an event and its signature, how a -path and a version are spelled and read, the sizes each may have, how an event is judged -and what the events read as, which version a node takes and which is current, what a -checkpoint keeps and how it is spelled; and of the store on Automerge -([`store.md`](store.md)), what the document holds, what a change writes, the snapshot, -and the Automerge version, whose encoding fixes a change's hash. - -A change to the federation is a design like this one, with the next number. A swarm -moves to it by a version of its policy that names it (`"federation": 2`), which the -parties pass once their nodes run a continuum that knows it. A node that doesn't know -the federation its swarm's root names holds no store, and says so. One that doesn't read -a version that passed on the version it reads stops at the version event writing it, and +by the federation's number and its revision: the rules of this design, an event and its +signature, how a path and a version are spelled and read, the sizes each may have, how an +event is judged and what the events read as, which version a node takes and which is +current, what a checkpoint keeps and how it is spelled; and of the store on Automerge +([`store.md`](store.md)), what the document holds, what a change writes, the snapshot, and +the Automerge version, whose encoding fixes a change's hash. + +Of that, what is judged at an event's history changes by a **revision** of federation 1, +which a version names by its ID (`"revision": ""`); one naming none follows the +**base revision**, which federation 1 began with, keys of type `ecdsa-sha2-nistp256` +among it. A revision adds a feature to those of the one before, and its ID is the SHA-256 +of the JCS list of its features' names, so that a continuum that doesn't know a revision, +another build's among them, can't read a version naming it. There are none yet but the +base revision. What no history judges, the document, a change, the snapshot and the +Automerge version, no version names: a change there splits the swarm until every node +runs it ([`guides/federation/upgrades.md`](guides/federation/upgrades.md)). + +A version leaves `revision` out for the base revision, and names a revision no earlier +than that of the version it changes. What a revision adds counts at a history only where +the version current there names that revision or a later one: before, every node judges +as before, so that what a party uses early, every node refuses alike. A version is read by +the revision it names, so one moving to a revision may already hold what that revision +adds to a version; its proposal, the votes on it and its version event are judged under +the version before. + +A node that doesn't read a version that passed on the version it reads, of a revision or +a federation it doesn't know or none at all, stops at the version event writing it, and says so: it takes nothing and refuses nothing from then on, leaving out none of it, a remake's snapshot neither, and keeps none of it across a restart, until it runs a continuum that reads it, or its operator has it drop that event ([`store.md`](store.md), -[A node's own](store.md#a-nodes-own)). Dropped, the node refuses -that event and any writing that version, as any version its operator had it drop, and -goes on under the version before. One beside the version it reads, it refuses of its own, -as any other ([Changing the policy](#changing-the-policy)). - -A change that only has the federation take what it refused, and reads nothing it took -otherwise, keeps the number: the keys of type `ecdsa-sha2-nistp256` taken beside Ed25519 -ones are such a change. It is rolled out first and used after: every node runs a -continuum that takes it before any party uses it. A node that doesn't refuses what uses -it, and reads otherwise than the others until it does; at a version naming such a key, -which it doesn't read, it stops, as above. So that no party picks the moment nodes part, -the next such change names itself in the version, by a field that only a version using -it gives: a continuum that takes it takes what it adds only under a version naming it, -which two thirds pass, and a node running one that doesn't stops at that version rather -than refusing what follows. +[A node's own](store.md#a-nodes-own)). Dropped, the node refuses that event and any +writing that version, as any version its operator had it drop, and goes on under the +version before. One beside the version it reads, it refuses of its own, as any other +([Changing the policy](#changing-the-policy)). A node that doesn't know the federation its +swarm's root names holds no store, and says so. + +So a revision is rolled out, then passed: every party's operators restart its nodes on a +continuum that knows it, and the parties pass a version naming it once theirs do, as a +party's client backs no version it doesn't read. Who hasn't by then stops at that version, +and takes part again once it has. Once a store moved to a checkpoint at a version naming +a revision, nodes join it only from a pinned checkpoint, and nobody judges what came +before again: a later continuum may hold only stores at that revision or after, and leave +out the rules of the revisions before. + +A change a node can't make while it reads the versions before by their own rules is a +federation of its own, a design like this one with the next number, which a version names +(`"federation": 2`). ## The registry on it 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. - -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). 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 -- cgit v1.3.1