aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 17:10:41 +0000
committertv <tv@krebsco.de>2026-11-16 18:28:20 +0100
commit8f6ec848b01fa692b09ae8aae25d383d281eb996 (patch)
treefdfd1a03b55802cb667c55b68b3c70817c413e91 /docs/federation.md
parente7f8b368db441dbd2c91b08e7e04fa34bed01a1a (diff)
federation: groups that parted come together as parties come in, not by merges
A merge, a fork at heads of several stores, named every party's keys anew, so that a party wrote its key set again before anything a key of its set signed counted there; and kept each side's values side by side, so that a value a party replaced on one side came back where the other side's write had the lower ID. Letting the other side's parties in, by a version or a fork naming them, who sign again what they keep as a party's client signs again what a move refused, does the same with nothing new. So a fork is at heads of one store: the fold makes its root from that store's state, and the store from its own heads (`Store::fork`). Merges' rows go, those after them move up, and Roads not taken says why, with merging in place.
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md86
1 files changed, 31 insertions, 55 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 46404d9..2041d7e 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -58,8 +58,8 @@ nothing coming from any node breaks a promise for the others.
keys voting twice, a version that passed stays, on every node; with them, the nodes
part, and the parties fork (Changing the policy).
3. **Any group carries on as it chooses.** Its parties fork with the policy they want,
- and whoever wants to follow does; groups that parted come together the same way.
- Nobody is held by parties it doesn't follow.
+ and whoever wants to follow does; groups that parted come together as parties come
+ in, one letting the other's in (Forks). Nobody is held by parties it doesn't follow.
Not promised:
@@ -100,7 +100,7 @@ What it asks of the store:
before, and an operator having its node drop what it took.
* **Checkpoints**: the store starting anew from what counts at heads the parties name,
forgetting the rest.
-* **Forks**: a store whose root is a checkpoint at heads of another store, or of several.
+* **Forks**: a store whose root is a checkpoint at heads of another store.
* **Members**: the nodes that carry the store, which the federation names.
### Events
@@ -155,8 +155,7 @@ history, and no other store takes it ([`store.md`](store.md), Forks). An event i
What the policy says is in its **versions**, a chain: each is a JSON object, named by
the SHA-256 of its JCS bytes, numbered, and naming the version it changes (`null` for
the first, number 0, which only the federation's root holds; a fork's changes the one
-current at its heads, and a merge's lists those current at its heads, Forks). Spread
-out:
+current at its heads, Forks). Spread out:
```json
{ "federation": 1, "number": 7, "changes": "<hash of the version it changes>",
@@ -176,7 +175,7 @@ out:
```
* **The federation** it follows, and its **number**, one more than that of the version
- it changes (of the highest, for a merge's).
+ 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
`ssh-ed25519` key or more, compared as keys (their comments aside), none twice in the
@@ -387,13 +386,12 @@ with the lower ID; the party writes again, after both, to choose.
A **checkpoint** writes down what counts at some heads: those heads, a version (the one
current there, or a fork's), and the IDs of the events that count there with that
-version current, version events aside, as it holds the version itself (What counts; a
-merge's root keeps otherwise, Forks), as the JCS encoding of
-`{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs ascending and its
-version the version itself, the object, named by its SHA-256 ([`store.md`](store.md),
-Checkpoints). Every node holding the history up to those heads builds the same one, and
-its version counts as written: a version event of it that comes later is one the node
-took.
+version current, version events aside, as it holds the version itself (What counts), as
+the JCS encoding of `{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs
+ascending and its version the version itself, the object, named by its SHA-256
+([`store.md`](store.md), Checkpoints). Every node holding the history up to those heads
+builds the same one, and its version counts as written: a version event of it that comes
+later is one the node took.
A version names a checkpoint by its heads (`checkpoint`): events after the current
checkpoint, at which it is current too, none in another's history, their IDs ascending,
@@ -436,8 +434,7 @@ A version that changes nothing but its number, what it changes and its checkpoin
moves the store on. Like any version, it lapses the proposals on the version before, so
a party proposes one where nothing that can still pass is proposed on the current
version. A federation's root is its first checkpoint, without heads (Starting a
-federation), and a fork's root a checkpoint at the heads it forks at, of one store or of
-several (Forks).
+federation), and a fork's root a checkpoint at the heads it forks at (Forks).
### Votes a node casts by itself
@@ -519,28 +516,10 @@ in by a version, as they would anyone new. A fork's version may name parties tha
weren't among the first to go (every party its founders consider honest, say), so that
they can follow whenever they like, without asking.
-Groups that parted come together the same way: a fork at heads of several stores
-**merges** them, the federation and a fork of it, say, or two forks
-([`store.md`](store.md), Forks). Its root differs from a fork's in three things:
-
-* its version's `changes` lists the versions current at those heads, ascending, and its
- number is one past the highest of them;
-* its version names every party's keys and node list anew, so that no key set or node
- list of any side counts in the merge: it may give a party the keys it had on the
- sides, or others, and each party writes its set anew;
-* it keeps, of each side, the values that count there at places its version gives their
- party, and nothing else. One counts in the merge once the key that signed it is among
- its party's keys there (Keys), so that what a key one side dropped signed counts only
- where the party lists that key again.
-
-The events a merge's root keeps are in none of each other's histories: where a party
-wrote one place on two sides, the lower ID counts until it writes there again, whatever
-either side's history held; where the sides gave an identifier to different parties, the
-merge's rules say whose values count. What a side writes after those heads isn't taken
-in the merge, and its party signs it again. A node holding the history up to all those
-heads builds the root and checks it; one holding some of it says, side by side, what it
-holds that those heads lack, and party by party what keys the merge gives; one holding
-none takes the root on its operator's word.
+Groups that parted come together as any party comes in: one side lets the other side's
+parties in, by a version, or by a fork naming them, and they sign there again what they
+keep, as a party's client signs again what a move refused. What one side signed counts
+on the other only once it is signed there.
What a party's nodes do of themselves is their operators' business, written nowhere:
join a fork their operator follows, vote by rules their operator set (Votes a node casts
@@ -671,18 +650,12 @@ crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
| 59 | Two checkpoints proposed at once, by nodes voting by themselves | The votes split; nays from the nodes backing one make the other dead, and its backers are free | sim |
| 60 | Two nodes of one party, each voting by itself | They can vote twice, answered as any party voting twice: a party has one node vote by itself | — |
| 61 | A key a version names, kept on a node that votes by itself, stolen with it | As 23: it counts while that version is current | unit |
-| 62 | A merge whose version doesn't name every party's keys and node list anew, or whose `changes` doesn't list the versions current at its heads | No merge | unit |
-| 63 | A key one side dropped, still in the party's set on the other, then a merge | What it signed counts only where the party lists it again | unit |
-| 64 | A party wrote one place on two sides, one write built on the other before they parted, then a merge | The lower ID counts until it writes there again: a merge's kept events are in none of each other's histories | unit |
-| 65 | An identifier given to different parties on two sides, then a merge | The merge's rules say whose values count; the others' aren't kept | unit |
-| 66 | A merge's root keeping a value that didn't count on its side, or at a place its version gives another | Nodes holding that side build the root, find it differs, and don't join; others take it on their operator's word | sim |
-| 67 | Events a side writes after a merge's heads, brought to the merge | Never taken: their history lacks its root; their party signs them again | unit |
-| 68 | A party's event spelled anew by another: its `sig` or `key` encoded otherwise, its signature's S not canonical, its blob naming another key | None: `key` and `sig` read back to themselves, the signature is checked strictly, and the blob's key is `key` | unit |
-| 69 | A node joining from the root is shown a chain old keys grew, beside the one the others took | It takes neither, and reports; once a checkpoint passed, it joins from a pinned one, where that chain is refused | unit |
-| 70 | Checkpoint heads before the current checkpoint, or at which it isn't current, or one in another's history | No version: a version event naming it is refused | unit |
-| 71 | After a checkpoint, a party that backed a second proposal once its first was dead, the nays that freed it withheld by those who cast them | Not named: its client keeps those nays with its `true` | unit |
-| 72 | Two clients of one party back two proposals at once | Voting twice: a party votes from one client | — |
-| 73 | A party keeps a proposal alive that nobody else backs, holding back automatic checkpoints | The party a node follows votes it `false`, and its followers with it, until it is dead | sim |
+| 62 | A party's event spelled anew by another: its `sig` or `key` encoded otherwise, its signature's S not canonical, its blob naming another key | None: `key` and `sig` read back to themselves, the signature is checked strictly, and the blob's key is `key` | unit |
+| 63 | A node joining from the root is shown a chain old keys grew, beside the one the others took | It takes neither, and reports; once a checkpoint passed, it joins from a pinned one, where that chain is refused | unit |
+| 64 | Checkpoint heads before the current checkpoint, or at which it isn't current, or one in another's history | No version: a version event naming it is refused | unit |
+| 65 | After a checkpoint, a party that backed a second proposal once its first was dead, the nays that freed it withheld by those who cast them | Not named: its client keeps those nays with its `true` | unit |
+| 66 | Two clients of one party back two proposals at once | Voting twice: a party votes from one client | — |
+| 67 | A party keeps a proposal alive that nobody else backs, holding back automatic checkpoints | The party a node follows votes it `false`, and its followers with it, until it is dead | sim |
## Roads not taken
@@ -737,11 +710,14 @@ crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
* **A place where a party says which fork it went to.** A node following it by itself
would follow a stolen key into a swarm with any policy; parties say where they went as
they like.
-* **Merging in place**: two stores each passing a version that moves them to one
- checkpoint. It needs a version that changes two, nodes on each side taking the other
- side's part on someone's word, and leaves two swarms, one of whose nodes move to the
- other's anyway. A merge is a fork from both: whoever wants to carry on together
- follows it.
+* **Merges**: a fork at heads of several stores, keeping what counts on each side. Its
+ version names every party's keys anew, so that a party writes its key set again
+ before anything a key of its set signed counts; and a value a party replaced on one
+ side comes back where the other side's write has the lower ID. Letting the other
+ side's parties in, who sign again what they keep, does the same with nothing new. Nor
+ merging in place, two stores each passing a version that moves them to one
+ checkpoint: it needs a version that changes two, and nodes on each side taking the
+ other side's part on someone's word.
* **Forks within one store**, each side judging by its own chain of versions. It needs
judging per chain, judging again when a node changes sides, and members per chain. A
store of its own needs none of it.
@@ -813,7 +789,7 @@ continuum builds and behaves as it does, and its tests pass untouched.
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.
4. **Forks**: a store whose root is a checkpoint at another's heads, named by its root,
- checked by the nodes holding that history; merges, forks at heads of several stores.
+ checked by the nodes holding that history.
5. **Remakes**: compaction only, the snapshot holding the store as it is at its base,
and every event beyond it put again.
6. **The registry**: the rules for krebs, the tool that signs kartei's entries in as