From 2e0b0071e68d03942d1a4a7258d67a9d2fd30dd0 Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 11:09:24 +0000 Subject: federation: what an end-to-end read found at odds Read whole after the last series of changes, the design said a few things that no longer fit what it says elsewhere: * the example's version 7 named lass's keys anew at 4 but gave lass no node list, where a party new in a version has its list named anew; * a remake reaches no node that can't build it, nor one that isn't to follow it (not a member at the base, its coordinator unlisted); * the clause on whose word follows a decision sat after a colon meant for the abort; * what a node taken off its list could commit before a base ends with the remake only where the base holds that list; * a remake racing a listing leaves behind the nodes listed since the base, not "the nodes that took it"; * "Why it holds" now names the coordinator's listing; * attack 29: a node that lacks the base syncs it where a peer keeps it; * forks come at stage 4, so before it no swarm starts afresh by one; * a party drops a stolen key of its set itself; only one its version names takes a version. --- docs/federation.md | 54 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/federation.md b/docs/federation.md index bc3b514..72104a3 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -74,7 +74,8 @@ Not promised: * that honest nodes stay together where a node commits two changes under one writer and number: they are apart until operators have one side drop what it took, or a fork (Where Automerge sets limits); -* that a remake reaches every node: one that can't build it itself stays where it is; +* that a remake reaches every node: one that can't build it itself, or isn't to follow + it (Remakes), stays where it is; nor that nodes follow one remake where two were decided for one epoch: each follows the one it holds, until operators name one (Remakes); * that a node taken off its party's list can't still commit at a history from before: @@ -138,7 +139,8 @@ current at its heads, Forks). Spread out: "keys": { "tv": { "since": 0, "keys": ["ssh-ed25519 AAAA… tv"] }, "lass": { "since": 4, "keys": ["ssh-ed25519 AAAA… lass"] }, "makefu": { "since": 7, "keys": ["ssh-ed25519 AAAA… makefu"] } }, - "nodes": { "tv": { "since": 0, "nodes": [""] } }, + "nodes": { "tv": { "since": 0, "nodes": [""] }, + "lass": { "since": 4, "nodes": [] } }, "rules": [ { "path": "names/r/wiki", "writer": "lass" }, { "path": "home/{party}/**", "writer": "{party}" }, @@ -515,11 +517,11 @@ federated node asks of a remake: node that lacks some of the base (it was away) syncs it from peers that keep the old epoch, each change judged there, and builds then; where it can't build it, it stays where it is, says so, and never rejoins an epoch it refused. A remake's decision is - its coordinator's alone, and so is its abort, and a node follows one only where the - coordinator's party lists the coordinator, as the node reads it when it switches: - whether one expired is no node's to say, and one its coordinator leaves undecided - binds nobody. How long a node keeps the old document is its own setting, not the - remake's, and while it keeps it, it syncs it with nodes still on that epoch. + its coordinator's alone, and so is its abort: whether one expired is no node's to say, + and one its coordinator leaves undecided binds nobody. A node follows a decision only + where the coordinator's party lists the coordinator, as the node reads it when it + switches. How long a node keeps the old document is its own setting, not the remake's, + and while it keeps it, it syncs it with nodes still on that epoch. * **Two decisions for one epoch** come from a coordinator that wrote two, or from remakes decided at once. A node that holds both follows neither, says so, and leaves it to its operator. On its operator's word, a node builds the remake named of the @@ -556,15 +558,15 @@ written after it at a history where a version before the base's was current (its lagged), goes to the quarantine, and its party writes again. A swarm that never remakes stays as correct as one that remakes all the time; it only grows. A remake does end one thing: nothing is written at a history from before its base, so what a node taken off -its list could still commit there ends with it. +its list before the base could still commit there ends with it. -A remake that races a version or a listing leaves the nodes that took it where they are, -apart from those that switched, until their operators move them or a fork. An operator -moves a node that took a version by having it drop that version (Changing the policy): -the base then holds the version it reads, so it switches, and the new epoch writes the -version again from the votes replayed, as a node writes any it holds passed. A node with -an empty document can't check: it takes the epoch its peers give it, or the one its -operator pins. +A remake that races a version or a listing leaves the nodes that took the version, or +were listed since the base, where they are, apart from those that switched, until their +operators move them or a fork. An operator moves a node that took a version by having it +drop that version (Changing the policy): the base then holds the version it reads, so it +switches, and the new epoch writes the version again from the votes replayed, as a node +writes any it holds passed. A node with an empty document can't check: it takes the +epoch its peers give it, or the one its operator pins. ### Where Automerge sets limits @@ -622,12 +624,12 @@ long nodes stay together. node keeps the version it took, nodes holding the same changes still read the same policy, and the parties fork. 3. **Remakes.** A node follows a remake only where it built the snapshot itself, from a - base it holds, a member there, the version it reads written there; its peers' word - never moves it. What came after, under that version, is replayed in history's order, - each change judged as every node judges it: votes and proposals by the keys their - version names; envelopes as chains, from what the snapshot holds, by version, then - `seq`. So what counted, counts, but what a remake can't hold (Remakes), each of which - its party writes again. + base it holds, a member there, the version it reads written there, its coordinator + listed; its peers' word never moves it. What came after, under that version, is + replayed in history's order, each change judged as every node judges it: votes and + proposals by the keys their version names; envelopes as chains, from what the + snapshot holds, by version, then `seq`. So what counted, counts, but what a remake + can't hold (Remakes), each of which its party writes again. 4. **Carrying on.** A fork is a swarm of its own, named by its first version and the heads it names, its members those its lists name, joined by its operators' choice only. A party nobody follows carries on alone. @@ -667,7 +669,7 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang | 26 | A deletion of a value of another party, or of what counts no more | Refused: only a party's `null`, at its own place | unit | | 27 | An envelope outside an `@` key, a map in one, or a map on the way to one deleted or replaced | Refused | unit | | 28 | An envelope and a map at one key, written at once | None: envelopes go only in `@` keys, which hold no maps | unit | -| 29 | A remake whose snapshot isn't the one a node builds, whose base it lacks, or where it isn't a member | It stays, and never rejoins it | sim | +| 29 | A remake whose snapshot isn't the one a node builds, whose base it lacks and no peer keeps, or where it isn't a member | It stays, and never rejoins it | sim | | 30 | A coordinator records an old base, before the version nodes read | They stay | sim | | 31 | Two members advertise an epoch ahead, or offer a rejoin | Not taken: a node leaves its epoch only for one it built | sim | | 32 | A remake's decision or abort written by a node not its coordinator | Refused | unit | @@ -732,8 +734,8 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang * **Anything waiting on time** (final after so many days). Clocks are each node's own. Everything here waits on votes. * **Taking back what a stolen key signed, from history.** A thief makes its changes - look as old as it likes. A version dropping the key takes all of them back, and the - party signs again what was its own. + look as old as it likes. Dropping the key takes all of them back (the party drops a + key of its set, a version one it names), and the party signs again what was its own. * **One vote per version**, never to be cast again. It bounds what parties voting twice can do at a third of them, and leaves a split for good. With nays a split ends, and one party voting twice on a close vote can have two versions written; the @@ -836,8 +838,8 @@ On a federated swarm: version); the bound on the writers a party's nodes start in an epoch; and the sizes a version, a set, a list, a path and a value may have, each within what a sync message carries. A node that doesn't know the policy stops taking changes. Until stage 5, a - federated swarm takes no remake: one that grows too large starts afresh by a fork - whose version names the same parties, keys and rules. + federated swarm takes no remake: from stage 4 on, one that grows too large starts + afresh by a fork whose version names the same parties, keys and rules. 2. **What counts**, read by the current version and the keys; shown in the API. Reports of the versions a node refused, and its operator having it drop what it took; a tool reporting, from the votes, a party that voted twice. -- cgit v1.3.1