aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 14:21:10 +0000
committertv <tv@krebsco.de>2026-11-16 15:26:32 +0100
commite320826b6fbaab162029ff16c53cfbdbb83231a5 (patch)
treec4276bcc1609a4a48fb637eb36c4bd662c2e9e6e /docs/federation.md
parent486be5434c654a74656faa040fba4771ff04d4f1 (diff)
docs/federation: merges
Groups that parted come together by a fork at heads of several stores, which merges them. Its version's `changes` lists the versions current at those heads and is numbered one past the highest; it names every party's keys and node list anew, so that no key set or list of any side counts; and its root keeps, of each side, the values that count there at places the merge's version gives their party. A value counts in the merge once the key that signed it is among its party's keys there, so a key one side dropped brings back nothing unless the party lists it again. A party's place written on two sides leaves the lower ID until it writes again; an identifier given to different parties goes by the merge's rules. Merging in place, both stores voting to move to one checkpoint, is a road not taken.
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md54
1 files changed, 45 insertions, 9 deletions
diff --git a/docs/federation.md b/docs/federation.md
index a7da50c..ad42dd0 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -58,7 +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. Nobody is held by parties it doesn't follow.
+ and whoever wants to follow does; groups that parted come together the same way.
+ Nobody is held by parties it doesn't follow.
Not promised:
@@ -139,7 +140,8 @@ its history (Changing the policy).
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, Forks). Spread out:
+current at its heads, and a merge's lists those current at its heads, Forks). Spread
+out:
```json
{ "federation": 1, "number": 7, "changes": "<hash of the version it changes>",
@@ -159,7 +161,7 @@ current at its heads, Forks). Spread out:
```
* **The federation** it follows, and its **number**, one more than that of the version
- it changes.
+ it changes (of the highest, for a merge's).
* **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 . _ @ -` but not `@`, with one
`ssh-ed25519` key or more, compared as keys (their comments aside), none twice in the
@@ -362,10 +364,11 @@ 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 (What counts), as the JCS encoding of
-`{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs ascending, 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.
+version current (What counts; a merge's root keeps otherwise, Forks), as the JCS
+encoding of `{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs
+ascending, 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 names a checkpoint by its heads (`checkpoint`). It is a version only where its
proposal is above those heads, and a vote on it, or a version event writing it, is taken
@@ -390,7 +393,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 else 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 (Forks).
+fork's root a checkpoint at the heads it forks at, of one store or of several (Forks).
### Votes a node casts by itself
@@ -467,6 +470,28 @@ 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.
+
+Where a party wrote one place on two sides, the lower ID counts until it writes there
+again; 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.
+
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
by itself), or do nothing without their operator. So a federation that cooperates can
@@ -596,6 +621,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, then a merge | The lower ID counts until it writes there again | 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 |
## Roads not taken
@@ -650,6 +681,11 @@ 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.
* **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.
@@ -720,7 +756,7 @@ continuum builds and behaves as it does, and its tests pass untouched.
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.
+ checked by the nodes holding that history; merges, forks at heads of several stores.
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