diff options
| author | tv <tv@krebsco.de> | 2026-11-18 12:41:10 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-18 13:42:58 +0100 |
| commit | 0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (patch) | |
| tree | cd8d576ac13160163a2cee508cf985ef183b3a01 /docs/store.md | |
| parent | b0f0e1a9edb08b324df2ec5e97d15e7089349fdb (diff) | |
docs: references to a section of the same document linked to it
Where a document names one of its own sections in parentheses ("(What
counts, 5)", "(Joining, below)"), the name links to the section by its
GitHub-style ID; paragraphs that grew past the width are wrapped anew,
links and code kept on one line each. References to another document's
sections stay as they are.
Diffstat (limited to 'docs/store.md')
| -rw-r--r-- | docs/store.md | 140 |
1 files changed, 73 insertions, 67 deletions
diff --git a/docs/store.md b/docs/store.md index 3ba60d1..f7f053b 100644 --- a/docs/store.md +++ b/docs/store.md @@ -22,9 +22,9 @@ store is generic over it. The federation ([`federation.md`](federation.md)) is i fold. The store asks nothing of what carries its events. It is built first inside a swarm's -Automerge document (On Automerge): continuum's sync, transports, saving and remakes -carry it, and none of them changes what it holds. All of it is behind the `federation` -feature: without it, continuum builds and behaves as it does. +Automerge document ([On Automerge](#on-automerge)): continuum's sync, transports, saving +and remakes carry it, and none of them changes what it holds. All of it is behind the +`federation` feature: without it, continuum builds and behaves as it does. ## Events @@ -54,9 +54,9 @@ 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: 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 another store 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. +anew; one at heads of another store starts a fork ([Forks](#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 @@ -68,10 +68,11 @@ them, and refuses such events from then on. The fold names heads that whatever m 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 a remake -whose snapshot holds that checkpoint or a later one, 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. +for what the fold lets a checkpoint forget. Its tests check both ([Tests](#tests)). Until +a remake whose snapshot holds that checkpoint or a later one, the document still holds +what a node forgot, and a node that was away syncs it as any +([On Automerge](#on-automerge)); after it, one that can't build the checkpoint takes it +where its operator pins it. ### Pinned checkpoints @@ -82,14 +83,14 @@ operator pins it, by its ID, and then judges every event after it as any. It fin its document: the document's checkpoint, or one the fold moves to at the history of an event the document holds (the federation: a version naming one), built at those heads from what the document holds, as any node builds it; the document holds what that takes, -from the document's checkpoint on (On Automerge, What the store takes from the -document). 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. +from the document's checkpoint on ([On Automerge](#on-automerge), +[What the store takes from the document](#what-the-store-takes-from-the-document)). 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 @@ -97,7 +98,8 @@ A fold says, of its events: * **what an event builds on**, read from its bytes; bytes that aren't one of its events are none, and are refused; -* **how large an event may be**, which the document judges a change by (On Automerge); +* **how large an event may be**, which the document judges a change by + ([On Automerge](#on-automerge)); * **whether an event is taken where its history reads as a given state**: judging. A root is taken only as its own store's, never by judging; * **the state a checkpoint and the events after it read as**, built by adding the events @@ -108,9 +110,9 @@ A fold says, of its events: * **a fork's root**, from the state at heads of another store, 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); + its group ([Members](#members)); * where it needs to, **what a node refuses that its history takes**, by what the node - took before (A node's own). + took before ([A node's own](#a-nodes-own)). In Rust, roughly: @@ -155,23 +157,23 @@ 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, -which its tests check (Tests). +which its tests check ([Tests](#tests)). ## What is promised 1. **Every node takes an event or none**, but for what a fold has a node refuse by what - it took, what an operator has its node drop (A node's own), and what moving to a - checkpoint refuses. An event is judged at its history, which its ID fixes, so every - node judges it alike, whenever and from whomever it comes. An event refused is + it took, what an operator has its node drop ([A node's own](#a-nodes-own)), and what + moving to a checkpoint refuses. An event is judged at its history, which its ID fixes, + so every node judges it alike, whenever and from whomever it comes. An event refused is refused with everything built on it. 2. **Nodes that hold the same checkpoint and the same events after it read the same state**, whatever order the events came in, and whatever carried them. 3. **Nothing underneath adds an event or takes one away.** What a node holds is what it took, less what a checkpoint forgot. Which document carries the events, which changes - put them, a remake, a rejoin: the fold sees none of it (On Automerge). + put them, a remake, a rejoin: the fold sees none of it ([On Automerge](#on-automerge)). 4. **A node takes nothing on a peer's word.** It builds every checkpoint itself and - judges every event after it, but for a checkpoint its operator pins (Pinned - checkpoints). + judges every event after it, but for a checkpoint its operator pins + ([Pinned checkpoints](#pinned-checkpoints)). Not promised: that an event reaches every node, as a node may withhold what it holds; that an event not above a checkpoint's heads is taken once nodes moved to it; that a @@ -255,36 +257,38 @@ the changes every node builds itself: an epoch's first change, and a fork's chan after it. They carry none, and their writer, derived from the root or from the remake *(checked: `remake::snapshot`)*, writes exactly them: any other change under that writer is refused, so nobody commits under it what every node doesn't build. A change is first -of all one Automerge itself writes (Where Automerge sets limits). Every node judges a -change by these alone, each a question of the change and its history, and refuses it -with everything built on it, as continuum refuses a change its rules refuse -([`access.md`](access.md), Changes judged on every node). It judges no event there: -which events it takes is its store's (below). The same event put by two changes at once -is one event: its key holds the same bytes twice. +of all one Automerge itself writes +([Where Automerge sets limits](#where-automerge-sets-limits)). Every node judges a change +by these alone, each a question of the change and its history, and refuses it with +everything built on it, as continuum refuses a change its rules refuse +([`access.md`](access.md), Changes judged on every node). It judges no event there: which +events it takes is its store's (below). The same event put by two changes at once is one +event: its key holds the same bytes twice. ### What the store takes from the document The store reads the events the document holds, by their bytes, and takes them as it would take them from anywhere: each once it holds its dependencies, judged at its -history, and by the node's own (A node's own). The rest it reads none of: an event -nobody takes, or one a checkpoint forgot, stays in the document until the next remake -leaves it out (Remakes). Which change put an event, and how often, changes nothing, so -honest nodes hold one document, whatever each reads from it. A node reads its store from -its document anew whenever it starts, from the document's checkpoint or the one its -operator pinned, by its own refusals and its operator's drops, which it keeps in a file -(A node's own): it keeps nothing else of the store across a restart. +history, and by the node's own ([A node's own](#a-nodes-own)). The rest it reads none of: +an event nobody takes, or one a checkpoint forgot, stays in the document until the next +remake leaves it out ([Remakes](#remakes)). Which change put an event, and how often, +changes nothing, so honest nodes hold one document, whatever each reads from it. A node +reads its store from its document anew whenever it starts, from the document's checkpoint +or the one its operator pinned, by its own refusals and its operator's drops, which it +keeps in a file ([A node's own](#a-nodes-own)): it keeps nothing else of the store across +a restart. **A node puts again**, in changes of its own, every event its document lacks that a store starting at the document's checkpoint would take, but for the node's own refusals and drops, and that the node has: one it holds, one in a change it refused, or one the -document it left held, at a switch or a rejoin (Remakes). It puts each after its -dependencies, once a short wait of its own has passed, random, so that not every node +document it left held, at a switch or a rejoin ([Remakes](#remakes)). It puts each after +its dependencies, once a short wait of its own has passed, random, so that not every node puts the same, and none another node put meanwhile. Each event is taken again as it was: its history is there too. Continuum still refuses some changes on its own, by what they -are or who wrote them: of a writer's two changes of one number, the second (Where -Automerge sets limits); what such a change carried still reaches the store, and the -documents those two changes part hold the same events. And no remake leaves out an -event a store starting at the new document's checkpoint takes. +are or who wrote them: of a writer's two changes of one number, the second +([Where Automerge sets limits](#where-automerge-sets-limits)); what such a change carried +still reaches the store, and the documents those two changes part hold the same events. +And no remake leaves out an event a store starting at the new document's checkpoint takes. ### Members @@ -307,11 +311,12 @@ what its fold reads from them. ### Remakes -A remake is continuum's, for Automerge's sake only (Where Automerge sets limits): the -store needs none, and asks for none. When to remake, and who acks, is continuum's as in -every swarm: acks tell an honest coordinator when to commit, and bind nobody. A swarm -holding a store takes compaction only, whose snapshot is a function of its base and its -record (its ID, its coordinator): two remakes at one base are two epochs. +A remake is continuum's, for Automerge's sake only +([Where Automerge sets limits](#where-automerge-sets-limits)): the store needs none, and +asks for none. When to remake, and who acks, is continuum's as in every swarm: acks tell +an honest coordinator when to commit, and bind nobody. A swarm holding a store takes +compaction only, whose snapshot is a function of its base and its record (its ID, its +coordinator): two remakes at one base are two epochs. * **The snapshot** holds the store a node reads from the document up to the base, starting at the document's checkpoint, by its own refusals and drops: the checkpoint @@ -330,27 +335,28 @@ record (its ID, its coordinator): two remakes at one base are two epochs. its coordinator's alone, and so is its abort. **Of two epochs decided for one**, by a coordinator that wrote two decisions or by remakes decided at once, a node follows the one with the lower ID, and a node on the other rejoins it. -* **After it switches**, a node puts again what the new document lacks (What the store - takes from the document): what it holds beyond the base, and, where it moved to a - later checkpoint since the base, what the old document holds that a store starting at - the snapshot's checkpoint takes to reach that one. A node that moved to a later - checkpoint since the base keeps its own, and reads none of what the snapshot holds - that its checkpoint forgot, as it read none of it in the old document. +* **After it switches**, a node puts again what the new document lacks + ([What the store takes from the document](#what-the-store-takes-from-the-document)): + what it holds beyond the base, and, where it moved to a later checkpoint since the base, + what the old document holds that a store starting at the snapshot's checkpoint takes to + reach that one. A node that moved to a later checkpoint since the base keeps its own, + and reads none of what the snapshot holds that its checkpoint forgot, as it read none of + it in the old document. * **A node that rejoins**, as it was away, lacks the base, or is on the higher of two epochs, takes the epoch its peers give it, or the one its operator pins, as continuum's node rejoins, but only where the snapshot's checkpoint is its document's, one it builds from that document, or one its operator pins: a snapshot holding an earlier one would leave the new document holding events whose history nobody puts again. It follows none whose policy isn't its swarm's, and reads nothing closed in one - it follows, as no change writes there (What a change writes). It keeps its own - checkpoint and reads from the new document what is above its heads, judging every - event; a later checkpoint the snapshot holds, which it can't build from what it holds, - it takes only where its operator pins it (Pinned checkpoints). It puts again what the - new document lacks, as after a switch. What its own refusals and its operator's drops - refuse, it reads none of. A node with an empty document does the same, from the root - its operator names or a checkpoint its operator pins. A made-up epoch can withhold - events from it, and keep it apart from the others, but make it take nothing it - wouldn't. + it follows, as no change writes there ([What a change writes](#what-a-change-writes)). + It keeps its own checkpoint and reads from the new document what is above its heads, + judging every event; a later checkpoint the snapshot holds, which it can't build from + what it holds, it takes only where its operator pins it + ([Pinned checkpoints](#pinned-checkpoints)). It puts again what the new document lacks, + as after a switch. What its own refusals and its operator's drops refuse, it reads none + of. A node with an empty document does the same, from the root its operator names or a + checkpoint its operator pins. A made-up epoch can withhold events from it, and keep it + apart from the others, but make it take nothing it wouldn't. So a remake changes no event a node holds, only which document carries them, which the fold never sees. A swarm that never remakes holds what one that remakes all the time |
