aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 04:17:24 +0000
committertv <tv@krebsco.de>2026-11-16 04:17:24 +0000
commitdabebef65ee6c9bbf9f4483ab5c18f006d928291 (patch)
tree3e46fa70526b0877bf51a017257fe06f48e5b4ad /docs/federation.md
parentd1479f8d479c885b55a5c17a4b335c3ee0356606 (diff)
federation: wordings that said more than the design does
Which federation a swarm follows is in each version, not in its policy's place; a fork's first version changes the one current at its heads, not `null`; a place given back shows what its party signed before only where nothing replaced it since; a remake's snapshot is a function of its base and its record, so two remakes at one base are two epochs; honest nodes agree once they sync but where keys voted twice, a coordinator decided two remakes, or a writer forked; and what a node taken off its list commits from a history before ends with the next remake's base, as no later version orders it.
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md32
1 files changed, 17 insertions, 15 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 7c8da2e..04c8995 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -16,9 +16,10 @@ are marked *(checked)* where they were read in it.
A swarm is federated from its genesis change, or not at all (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 its
-policy: this design is federation 1 (Changing the federation). A swarm leaves the
-federation as any group carries on: by forking, with the policy it wants (Forks).
+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). A swarm
+leaves the federation as any group carries on: by forking, with the policy it wants
+(Forks).
## Parties and the adversary
@@ -127,10 +128,10 @@ worth knowing (Where Automerge sets limits).
### The policy
A federated swarm's `_continuum/access/policy` is `{"version": 2, "federated": true}`.
-What the policy says is in its **versions**, a chain: each is a string of JSON, named
-by the SHA-256 of its bytes, numbered, and naming the version it changes (`null` for
-the first, number 0, which only the genesis change writes; a fork's first, Forks).
-Spread out:
+What the policy says is in its **versions**, a chain: each is a string of JSON, named by
+the SHA-256 of its bytes, numbered, and naming the version it changes (`null` for the
+first, number 0, which only the genesis change writes; a fork's first changes the one
+current at its heads, Forks). Spread out:
```json
{ "federation": 1, "number": 7, "changes": "<hash of the version it changes>",
@@ -374,9 +375,9 @@ Nothing is deleted within an epoch but by a party at its own place, writing `nul
Automerge keeps every operation, so a deletion shrinks nothing: only a remake shrinks
the document. What counts no more stays until a remake's snapshot or a fork's genesis
leaves it out, where it is or names a version before the one current there, or is a
-member entry (Remakes).
-Until then, a place given back to its party, or a key added back, shows what the party
-signed before, until the party writes there again.
+member entry (Remakes). Until then, a place given back to its party, or a key added
+back, shows what the party signed before where nothing replaced it since, until the
+party writes there again.
### Nodes
@@ -480,9 +481,10 @@ change, what they keep.
### Remakes
A remake starts the document anew, for Automerge's sake only (Where Automerge sets
-limits); the federation needs none and asks for none. When to remake, and who acks,
-is continuum's as in every swarm. A federated swarm takes compaction only, whose
-snapshot is a function of its base. What a federated node asks of a remake:
+limits); the federation needs none and asks for none. When to remake, and who acks, is
+continuum's as in every swarm. A federated swarm takes compaction only, whose snapshot
+is a function of its base and its record (its ID, its coordinator): two remakes at one
+base are two epochs. What a federated node asks of a remake:
* **It builds it itself.** A node that holds an epoch leaves it only for one whose
snapshot it built itself, as continuum's node builds a compaction's and checks it
@@ -646,10 +648,10 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang
| 37 | A node with an empty document handed a made-up epoch | Taken. Not promised | sim |
| 38 | A coordinator remakes often, or a party never acks | Slow, not wrong; the others fork | sim |
| 39 | A writer forked: two changes, one number | Honest nodes split until a fork. Not promised | sim |
-| 40 | Different changes to different peers | Honest nodes agree once they sync | sim |
+| 40 | Different changes to different peers | Honest nodes agree once they sync, but where keys voted twice, a coordinator decided two remakes for one epoch, or a writer forked | sim |
| 41 | A party withholding its changes or votes | Not promised | — |
| 42 | Flooding: namespace, proposals, history | Slow, not wrong | bench |
-| 43 | A node taken off its list writes changes at a history where it was on | Taken where valid there; behind what is written under later versions | unit |
+| 43 | A node taken off its list writes changes at a history where it was on | Taken where valid there; ended by the next remake's base | unit |
| 44 | A token from another node, even one its party lists | Refused: a node takes only its own | unit |
| 45 | A party lists another party's nodes, or one its party dropped | Nothing changes: a node is its own party's | unit |
| 46 | A party lists many nodes, to be every node's neighbours | Each node keeps some among its own party's and those its operator names | sim |