aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 11:09:24 +0000
committertv <tv@krebsco.de>2026-11-16 11:09:24 +0000
commit2e0b0071e68d03942d1a4a7258d67a9d2fd30dd0 (patch)
tree34479f75e0bbf332f81edc25f1c24b0cb97c97e1 /docs/federation.md
parentff2da13601f8055d037758fd8c1056db6185f106 (diff)
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.
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md54
1 files 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": ["<node ID>"] } },
+ "nodes": { "tv": { "since": 0, "nodes": ["<node ID>"] },
+ "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.