From a50c9e13b0017b993bfd4eebebccc57bc8010a7a Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 15:16:22 +0000 Subject: 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. --- docs/store.md | 61 +++++++++++++++++++++++++++++++++++------------------------ 1 file 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 -- cgit v1.3.1