aboutsummaryrefslogtreecommitdiffstats
path: root/docs/store.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 15:16:22 +0000
committertv <tv@krebsco.de>2026-11-16 16:27:03 +0100
commita50c9e13b0017b993bfd4eebebccc57bc8010a7a (patch)
treea4c528ea53f4147d3a48815f4274ffc762fef9b0 /docs/store.md
parentd7e12d2949a846918ab09205674baf2a16ecb9da (diff)
docs/store: checkpoint heads, drops around them, and joining
A checkpoint's heads are events after the store's checkpoint, none in another's history, and are held by their IDs after the move, so that what builds on them is taken; "above" says so more plainly, and that no head is above its own heads. A node drops only events after its checkpoint, as every later event builds on what the checkpoint keeps, and undoes a move only by a pin. Until the next remake the document holds what a node forgot, and a node away syncs it; after it, a node that can't build the checkpoint pins it. A node joins from a pinned checkpoint, and from the root only a store that never moved: from the root, what came before a checkpoint can be grown anew by what the fold refuses since.
Diffstat (limited to 'docs/store.md')
-rw-r--r--docs/store.md61
1 files changed, 36 insertions, 25 deletions
diff --git a/docs/store.md b/docs/store.md
index 6ccba27..8732b39 100644
--- a/docs/store.md
+++ b/docs/store.md
@@ -22,9 +22,9 @@ lower-case hex digits. In its bytes it names the events it builds on, its
**dependencies**, by their IDs; how it names them is its fold's. An event's **history**
is everything it builds on: its dependencies, theirs, and so on, which its ID fixes. The
**heads** of a set of events are the events nothing in it builds on. An event is
-**above** some heads where it has them all in its history, and so has every event in its
-history that isn't one of them or in their history: it builds on them, and on nothing
-written beside them.
+**above** some heads where it has them all in its history, and every event of its
+history that isn't one of them, nor in their history, has them all in its own: it builds
+on them, and on nothing written beside them. None of the heads is above them.
## Checkpoints
@@ -36,9 +36,10 @@ heads, so every node holding the history up to them builds the same one.
A store holds a checkpoint, the events it keeps, byte for byte, and the events after it:
each above the checkpoint's heads, its dependencies among those heads and the events
-after them; a root is its own checkpoint's one head (below). A store takes an event only
-once it holds its dependencies, so it holds every event's history back to its
-checkpoint.
+after them. The heads are held by their IDs, whether the checkpoint keeps them or not,
+and a head brought again is taken as held; a root is its own checkpoint's one head
+(below). A store takes an event only once it holds its dependencies, so it holds every
+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
@@ -48,26 +49,31 @@ their history.
### Moving to a checkpoint
-The fold says when the store moves to a later checkpoint, and at which heads (the
-federation: by a version that names them, once a node takes it). A node then builds the
-checkpoint at those heads, forgets every event before them that it doesn't keep and
-every event not above them, and refuses such events from then on. The fold names heads
-that whatever makes the store move is above, so that moving refuses none of it. Judging
-an event after those heads needs nothing the node forgot, as the fold keeps what judging
-reads; and what is read from the checkpoint and the events after it is what the whole
-history reads, but for what the fold lets a checkpoint forget. Its tests check both
-(Tests). A node keeps what it forgot for as long as its operator sets, and gives it to
-nodes catching up.
+The fold says when the store moves to a later checkpoint, and at which heads: events
+after the store's checkpoint, none in another's history (the federation: by a version
+that names them, once a node takes it). A node then builds the checkpoint at those
+heads, forgets every event before them that it doesn't keep and every event not above
+them, and refuses such events from then on. The fold names heads that whatever makes the
+store move is above, so that moving refuses none of it. Judging an event after those
+heads needs nothing the node forgot, as the fold keeps what judging reads; and what is
+read from the checkpoint and the events after it is what the whole history reads, but
+for what the fold lets a checkpoint forget. Its tests check both (Tests). Until the next
+remake, the document still holds what a node forgot, and a node that was away syncs it
+as any (On Automerge); after it, one that can't build the checkpoint takes it where its
+operator pins it.
### Pinned checkpoints
A node builds every checkpoint it moves to itself, from the one before and the events up
to the new heads, and judges every event after it. A checkpoint it can't build, as it
-was away longer than its peers kept what they forgot, or as it joins, it takes only
-where its operator pins it, by its ID, and then judges every event after it as any. A
-node joining starts from the root its operator names, the swarm's ID, or from a
-checkpoint its operator pins. So a node takes nothing on a peer's word: what it didn't
-build or judge itself, its operator vouched for.
+was away across a move and a remake after it, or as it joins, it takes only where its
+operator pins it, by its ID, and then judges every event after it as any. A node joining
+starts from a checkpoint its operator pins; only for a store that never moved does the
+root its operator names, the swarm's ID, suffice. Once a store moved, what came before
+its checkpoint can be grown anew from the root by what the fold refuses since (the
+federation: keys of versions long replaced, [`federation.md`](federation.md),
+Checkpoints), and a node joining from the root would take it. So a node takes nothing on
+a peer's word: what it didn't build or judge itself, its operator vouched for.
## The fold
@@ -145,7 +151,9 @@ A fold may have a node refuse an event its history takes, by what the node took
the federation's node takes a version only where it changes the one the node reads, and
moves to a checkpoint as it takes a version naming one
([`federation.md`](federation.md), Changing the policy, Checkpoints). And an operator
-may have its node **drop** events it took. Either way the node refuses the event and
+may have its node **drop** events it took after its checkpoint; not what the checkpoint
+keeps or holds by ID, as every event after it builds on that. A node undoes a move only
+by taking a checkpoint its operator pins. Either way the node refuses the event and
everything built on it, from whoever brings it, until its operator says otherwise, and
reports it; it keeps what it refuses so, and its operator's drops, in a file of its own,
across restarts. No peer's word moves a node; its operator's does. A node that refuses
@@ -351,9 +359,12 @@ crafted changes. *Sim*: a simulation. *Bench*: measured, not judged.
| 21 | A node no longer a member decides a remake, its decision brought by a member | Followed as any decision: a remake changes no event | unit |
| 22 | A checkpoint a node can't build, handed to it by peers | Taken only where its operator pinned it | unit |
| 23 | An event not above the heads of the checkpoint a node moved to | Not taken; the change that carries it is, and stays in the document until the next remake | unit |
-| 24 | A node away while the others moved to a checkpoint and forgot what came before | It builds the checkpoint from what a peer kept, or takes it where its operator pins it | sim |
-| 25 | A remake whose base comes before a checkpoint, switched after nodes moved to it | They switch, keep their checkpoint, and read none of what it forgot | sim |
-| 26 | Flooding: events, writers, history, remakes | Slow, or out of memory; not wrong | bench |
+| 24 | A node away while the others moved to a checkpoint and forgot what came before | It builds the checkpoint from the document, which holds what came before until the next remake; after it, it takes it where its operator pins it | sim |
+| 25 | Heads for a checkpoint before the store's, or one in another's history | No move: the fold names none such | unit |
+| 26 | A head brought again after a move | Taken as held, and not read anew | unit |
+| 27 | An operator has its node drop an event its checkpoint keeps | Refused: a node drops only events after its checkpoint | unit |
+| 28 | A remake whose base comes before a checkpoint, switched after nodes moved to it | They switch, keep their checkpoint, and read none of what it forgot | sim |
+| 29 | Flooding: events, writers, history, remakes | Slow, or out of memory; not wrong | bench |
## Tests