diff options
| author | tv <tv@krebsco.de> | 2026-11-16 14:21:10 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-16 15:26:32 +0100 |
| commit | e320826b6fbaab162029ff16c53cfbdbb83231a5 (patch) | |
| tree | c4276bcc1609a4a48fb637eb36c4bd662c2e9e6e /docs/federation.md | |
| parent | 486be5434c654a74656faa040fba4771ff04d4f1 (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.md | 54 |
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 |
