diff options
| author | tv <tv@krebsco.de> | 2026-11-19 03:48:03 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 05:10:06 +0100 |
| commit | 54bcc0e4ee8e1e6a29e0e01369c2ba95b27abce8 (patch) | |
| tree | 20568ac1b47394ae9e603630fe1ab5464d1f7900 /docs/federation.md | |
| parent | e5f8df2a78f26d5928d1c96573dae5620dba5e25 (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/federation.md')
| -rw-r--r-- | docs/federation.md | 77 |
1 files changed, 48 insertions, 29 deletions
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. +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. -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 +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": "<ID>"`); 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 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 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 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 |
