summaryrefslogtreecommitdiffstats
path: root/docs/store.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:48:29 +0000
committertv <tv@krebsco.de>2026-11-18 13:59:42 +0100
commitd130c0612b4c63f2d30da65ebcc231018c1f2606 (patch)
tree8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/store.md
parent0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (diff)
docs: references to another document's section linked to it
Where a document names a section of another after linking to it ("([`store.md`](store.md), Pinned checkpoints)"), the name links to that section too, by the id both GitHub and cgit's about filter give its heading; paragraphs that grew past the width are wrapped anew, links and code kept on one line each.
Diffstat (limited to 'docs/store.md')
-rw-r--r--docs/store.md79
1 files changed, 41 insertions, 38 deletions
diff --git a/docs/store.md b/docs/store.md
index f7f053b..02dc896 100644
--- a/docs/store.md
+++ b/docs/store.md
@@ -1,25 +1,25 @@
# The store: a design
-A design, built stage by stage ([`federation.md`](federation.md), Stages): so far, the
-store held in memory (`federation::store`), with a fold made for its tests and the
-federation's (`federation::fold`); and on Automerge, a swarm holding a store, started
-from its root or joined by its ID (`document::events`), each change judged by what it
-writes (`access::holding`), and the store a node reads from its document, by what is its
-own, putting again what the document lacks, from a checkpoint its operator pins if it
-pins one (`federation::held`); and members by the fold, each node of the party its
-operator names, syncing with members only, its neighbours among them, some among its own
-party's and those its operator names, and taking no token another node issued; and the
-store at a node's API (`api::events`), putting events and showing what counts, what it
-refused, and its operator's drops. Not yet: remakes, of which a swarm holding a store
-takes no records or acks. The store holds events. Each event is named by the hash of its
-bytes and names the events it builds on; it is judged where it was written, at that
-history, so every node judges it alike; and the events a node holds read as one state.
-The store starts from a checkpoint, the state at some heads written down, and holds what
-came after it; moving to a later checkpoint, a node forgets what matters no more, so
-that it holds what is relevant and nothing else. What the events are, how one is judged,
-what they read as and when the store moves to a checkpoint is a **fold**'s, and the
-store is generic over it. The federation ([`federation.md`](federation.md)) is its first
-fold.
+A design, built stage by stage ([`federation.md`](federation.md),
+[Stages](federation.md#stages)): so far, the store held in memory (`federation::store`),
+with a fold made for its tests and the federation's (`federation::fold`); and on
+Automerge, a swarm holding a store, started from its root or joined by its ID
+(`document::events`), each change judged by what it writes (`access::holding`), and the
+store a node reads from its document, by what is its own, putting again what the document
+lacks, from a checkpoint its operator pins if it pins one (`federation::held`); and
+members by the fold, each node of the party its operator names, syncing with members only,
+its neighbours among them, some among its own party's and those its operator names, and
+taking no token another node issued; and the store at a node's API (`api::events`),
+putting events and showing what counts, what it refused, and its operator's drops. Not
+yet: remakes, of which a swarm holding a store takes no records or acks. The store holds
+events. Each event is named by the hash of its bytes and names the events it builds on; it
+is judged where it was written, at that history, so every node judges it alike; and the
+events a node holds read as one state. The store starts from a checkpoint, the state at
+some heads written down, and holds what came after it; moving to a later checkpoint, a
+node forgets what matters no more, so that it holds what is relevant and nothing else.
+What the events are, how one is judged, what they read as and when the store moves to a
+checkpoint is a **fold**'s, and the store is generic over it. The federation
+([`federation.md`](federation.md)) is its first fold.
The store asks nothing of what carries its events. It is built first inside a swarm's
Automerge document ([On Automerge](#on-automerge)): continuum's sync, transports, saving
@@ -89,8 +89,9 @@ joining starts from a checkpoint its operator pins; only for a store that never
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.
+[Checkpoints](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
@@ -184,16 +185,16 @@ store stays fast.
A fold may have a node refuse an event its history takes, by what the node took before:
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 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
-what another took holds other events, and reads its own state from them; two that hold
-the same read the same.
+moves to a checkpoint as it takes a version naming one ([`federation.md`](federation.md),
+[Changing the policy](federation.md#changing-the-policy),
+[Checkpoints](federation.md#checkpoints)). And an operator 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 what another took holds other
+events, and reads its own state from them; two that hold the same read the same.
## Forks
@@ -206,7 +207,7 @@ those heads, the fork never takes; nor do they take what the fork takes, as no s
takes another's root, nor anything built on it. A node's own refusals are its store's.
What a fork's root holds, and who makes one, is its fold's: the federation builds one
byte for byte from its version and its heads, so that one version and one set of heads
-make one fork ([`federation.md`](federation.md), Forks).
+make one fork ([`federation.md`](federation.md), [Forks](federation.md#forks)).
## On Automerge
@@ -261,9 +262,10 @@ 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.
+([`access.md`](access.md),
+[Changes judged on every node](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
@@ -395,8 +397,9 @@ documents stay together.
## Attacks
What an attacker does to the store on Automerge, and what happens; a fold's own attacks
-are in its design ([`federation.md`](federation.md), Attacks). *Unit*: the judging, with
-crafted changes. *Sim*: a simulation. *Bench*: measured, not judged.
+are in its design ([`federation.md`](federation.md), [Attacks](federation.md#attacks)).
+*Unit*: the judging, with crafted changes. *Sim*: a simulation. *Bench*: measured, not
+judged.
| # | Attack | What happens | Test |
|---|---|---|---|