aboutsummaryrefslogtreecommitdiffstats
path: root/docs/store.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 15:16:39 +0000
committertv <tv@krebsco.de>2026-11-16 16:27:05 +0100
commit21f3d35556b2d9cec99f90ca23d5a6ff22b09779 (patch)
treebf4122d6f1dd7230470f5640fb4bd44d16faa3e4 /docs/store.md
parenta50c9e13b0017b993bfd4eebebccc57bc8010a7a (diff)
docs/store: forks in the fold, and the bytes of genesis changes
The fold makes a fork's root, from the states at heads of one store or several and what makes the fork; a node checks a fork's root by it. The state carries what judging needs of history, as the federation's carries the graph of its events, and the state is the same for the set a node takes, which its own refusals may make depend on order. The root is taken before the fold sees any event. A genesis change's writer is the first 16 bytes of the root's ID, and a fork's kept events follow its genesis change in changes of up to 1 MiB, in the order of their IDs.
Diffstat (limited to 'docs/store.md')
-rw-r--r--docs/store.md38
1 files changed, 26 insertions, 12 deletions
diff --git a/docs/store.md b/docs/store.md
index 8732b39..ea5b416 100644
--- a/docs/store.md
+++ b/docs/store.md
@@ -42,10 +42,11 @@ and a head brought again is taken as held; a root is its own checkpoint's one he
event's history back to its checkpoint.
A store's first checkpoint is its **root**, taken without judging, whose ID is the
-store's. A root without heads starts a store anew; one at heads of other stores starts a
-fork (Forks). Its events build on the root itself, whatever heads it was built at: until
-the store moves to a later checkpoint, the root's ID is the one head they all have in
-their history.
+store's: its bytes are a checkpoint's, which no fold reads as an event, so the store
+takes it as its own before the fold sees any event. A root without heads starts a store
+anew; one at heads of other stores starts a fork (Forks). Its events build on the root
+itself, whatever heads it was built at: until the store moves to a later checkpoint, the
+root's ID is the one head they all have in their history.
### Moving to a checkpoint
@@ -88,6 +89,8 @@ A fold says, of its events:
the state of a node's store, and the state at an event's history, which judging reads;
* **the checkpoint at some heads**: what of the history before them it keeps, and what
it says of the rest; and when the store moves to one;
+* **a fork's root**, from the states at heads of one store or of several, and what makes
+ the fork (the federation: its version);
* **the store's members**, the nodes that carry it, at a state, each with the name of
its group (Members);
* where it needs to, **what a node refuses that its history takes**, by what the node
@@ -112,6 +115,9 @@ pub trait Fold {
fn checkpoint(at: &Self::State, heads: &[Id]) -> (Vec<u8>, Vec<Id>);
/// The state a checkpoint reads as, with the events it keeps.
fn start(checkpoint: &[u8], kept: &[(Id, Vec<u8>)]) -> Result<Self::State, Refused>;
+ /// The root of a fork at `heads` of the stores reading as `at`, made by `spec`.
+ fn fork(at: &[&Self::State], heads: &[Id], spec: &[u8])
+ -> Result<(Vec<u8>, Vec<Id>), Refused>;
/// The heads of a later checkpoint, where a store reading as `now` moves to one.
fn moves_to(now: &Self::State) -> Option<Vec<Id>>;
/// The nodes that carry the store, each with its group.
@@ -119,6 +125,13 @@ pub trait Fold {
}
```
+The state carries what judging and reading need of the events' history: the
+federation's, the graph of the events it holds, so that it says what is in an event's
+history, what is above some heads, and what is dead at a history; `start` places every
+event a checkpoint keeps in the history of every event after it. `keeps` depends, by
+design, on the order a node takes events in: which events a node takes may differ by it,
+and the state of the set it takes doesn't.
+
How the store keeps states, so that judging an event at its history costs little, is its
own matter: it may keep the state of some events and add to it the rest of a history
that holds them all. Whatever it keeps reads as adding every event of the history anew,
@@ -192,12 +205,13 @@ document holds nothing but the store and continuum's protocol data.
| elsewhere under `_continuum` | continuum's protocol data, as far as this says |
The **genesis change**, the swarm's first, writes the policy, the swarm's ID, its epoch
-and the root, and nothing else, built byte for byte from the root: its writer from the
-root's ID, time 0, no message. So one root makes one swarm, and a node joining builds
-the genesis change and checks it. A fork's genesis change holds the events its root
-keeps too, each at its ID, built the same way. Continuum reads the policy as one asking
-for signed changes, as a strict one does, and nothing else of a strict policy: the
-document holds no values but events.
+and the root, and nothing else, built byte for byte from the root: its writer the first
+16 bytes of the root's ID, time 0, no message. So one root makes one swarm, and a node
+joining builds the genesis change and checks it. A fork's genesis change holds its root
+alone; the events the root keeps follow in changes of the same writer, each holding up
+to 1 MiB of them, in the order of their IDs, all built the same way. Continuum reads the
+policy as one asking for signed changes, as a strict one does, and nothing else of a
+strict policy: the document holds no values but events.
### What a change writes
@@ -372,8 +386,8 @@ What the tests check of the store, with a fold made for them
([`federation-tests.md`](federation-tests.md) says how they are built):
* **Order.** For every order of a set of events that puts each after its dependencies
- (all of them for small sets, seeded ones for larger), the state is the same, and so
- for the orders in which several nodes get them.
+ (all of them for small sets, seeded ones for larger), the state of the set a node
+ takes is the same, and so for the orders in which several nodes get them.
* **History.** The state at a history is the state of its events added anew, and judging
at it gives the same verdict whatever states the store kept.
* **Refusal.** An event refused is refused with everything built on it, on every node,