aboutsummaryrefslogtreecommitdiffstats
path: root/docs/store.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/store.md')
-rw-r--r--docs/store.md86
1 files changed, 45 insertions, 41 deletions
diff --git a/docs/store.md b/docs/store.md
index 952953c..cfa6d2a 100644
--- a/docs/store.md
+++ b/docs/store.md
@@ -147,9 +147,10 @@ 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
everything built on it, from whoever brings it, until its operator says otherwise, and
-reports it. 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.
+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
@@ -195,49 +196,52 @@ document holds no values but events.
A change of a swarm holding a store writes nothing but:
* **events**: at `_continuum/events/<ID>` the bytes whose ID it is, at a key held
- nowhere at the change's history; its dependencies held there, or put before it by the
- same change; taken by the fold at its history, and by the node's own (A node's own);
-* **continuum's protocol data**: by a member, its own entry, its own acks, a remake's
- record and proposal; by a remake's coordinator only, its decision or its abort; by an
- epoch's first change, epochs, the swarm's ID and the checkpoint.
+ nowhere at the change's history;
+* **its node's own protocol data**: its entry, its acks, a remake's record and proposal,
+ and, as a remake's coordinator, its decision or its abort; or, an epoch's first
+ change, epochs, the swarm's ID and the checkpoint.
Everything else is closed, a write at, within or above it refused: whatever isn't under
`_continuum`, users, bans, logouts, sessions, forgotten nodes, `_continuum/access` with
the policy's place, the swarm's topology (`neighbours`, `relays`, `topology`,
`dissemination`), and whatever a later continuum adds. Nothing deletes or replaces an
-event. A change is taken only from a member (Members), and carries its node's signature,
-as a strict swarm's changes do. Every node judges a change at its history, as continuum
-judges every change under a policy ([`access.md`](access.md), Changes judged on every
-node), and refuses it with everything built on it. The same event put by two changes at
-once is one event: its key holds the same bytes twice.
+event. A change carries its node's signature, as a strict swarm's changes do, and 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.
-### Events, whichever change put them
+### What the store takes from the document
-What the store holds is the events the document holds, by their bytes: which change put
-one, and how often, changes nothing. So a node that refuses a change, or drops one, puts
-again, in changes of its own, every event of it, and of what is built on it, that it
-doesn't refuse, read from those changes' own operations, each after its dependencies. An
-event of a change refused for something else it writes, or for its writer, still reaches
-the store; one refused by the fold, or by the node's own, takes with it only the events
-built on it. So two nodes' documents may differ where the events they hold don't: a
-writer's two changes of one number, which part the nodes holding one from those holding
-the other (Where Automerge sets limits), part no events. A node moving to a checkpoint
-drops, the same way, every change it holds that carries an event the move refuses. Until
-the next remake, the document still holds what the node forgot, and the node reads none
-of it.
+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.
+
+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). A node
+that refuses such a change puts again, in changes of its own, every event of it, and of
+what is built on it, read from those changes' own operations, each after its
+dependencies: so that what it carried still reaches the store, and the documents those
+two changes part hold the same events.
### Members
The fold names the members, each with its group: for the federation, the nodes each
party lists, each as its party's. A node's group is its operator's, in its
configuration, and its own entry names it. A node is a member while the fold names it
-with that group, at the node's heads, and nodes sync with members only. A change is
-taken only where its node is a member at the change's history with the events it puts
-added (an epoch's first change aside, which every node builds itself), so that a node an
-event makes a member can put that event itself. A swarm holding a store has no swarm
-key: a secret its members share keeps out nobody, and the fold says who syncs. A node
-keeps some of its neighbours among the members of its own group and of the groups its
-operator names, so that a group naming many nodes can't be every node's neighbours.
+with that group, as its store reads now, and nodes sync with members only. Nothing is
+judged by who was a member at a change's history: a change reaches a node only through a
+member, which could carry the same events itself, and the entry of a node that isn't a
+member counts for nothing where continuum reads entries (a remake's electorate, the
+entries a snapshot holds). A swarm holding a store has no swarm key: a secret its
+members share keeps out nobody, and the fold says who syncs. A node keeps some of its
+neighbours among the members of its own group and of the groups its operator names, so
+that a group naming many nodes can't be every node's neighbours.
At its API, a node takes no token another node issued, and whoever its operator lets in
may have it put events, whoever signed them, and write its own protocol data;
@@ -322,11 +326,11 @@ crafted changes. *Sim*: a simulation. *Bench*: measured, not judged.
|---|---|---|---|
| 1 | A change writing outside `_continuum/events` and the protocol data listed | Refused | unit |
| 2 | An event at a key its bytes don't hash to | Refused | unit |
-| 3 | An event whose dependencies aren't held at the change's history | Refused | unit |
+| 3 | An event whose dependencies never come | Taken by no node; it stays in the document until the next remake leaves it out | unit |
| 4 | An event deleted, or replaced | Refused | unit |
| 5 | The same event put by two changes at once, or again later | One event | unit |
-| 6 | An event the fold refuses, beside others in one change | Refused, with everything built on it; every node puts the others again | unit |
-| 7 | A change by a node that isn't a member at its history, the events it puts added | Refused | unit |
+| 6 | An event the fold refuses, beside others in one change | The change is taken; the store takes the others, and not that one, nor what is built on it | unit |
+| 7 | A change by a node that isn't a member, brought by one that is | Taken: its events count by who signed them, its entry for nothing | unit |
| 8 | Bytes that are none of the fold's events, or a root other than the store's | Refused | unit |
| 9 | A fork's events brought to a store it came from, or the other way | Never taken: their history lacks the root | unit |
| 10 | A writer forked: two changes, one number | The documents part, the events reach both sides, the state is the same | sim |
@@ -339,10 +343,10 @@ crafted changes. *Sim*: a simulation. *Bench*: measured, not judged.
| 17 | A token from another node | Refused: a node takes only its own | unit |
| 18 | A node writing another node's entry, or under `_continuum` where this doesn't say | Refused | unit |
| 19 | A group naming many nodes, to be every node's neighbours | Each node keeps some among its own group's and those its operator names | sim |
-| 20 | A node whose operator had it drop an event is sent it again, in another change | Refused, with everything built on it, until its operator says otherwise | unit |
+| 20 | A node whose operator had it drop an event is sent it again, in another change, before or after a restart | Not taken, with everything built on it, until its operator says otherwise | unit |
| 21 | A node no longer a member writes changes at a history where it was one | Taken where valid there: their events count by who signed them, and nobody follows a remake it decides | 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 | Refused; a change the node holds that carries one is dropped, its other events put again | 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 |
@@ -364,9 +368,9 @@ What the tests check of the store, with a fold made for them
what the fold lets a checkpoint forget; a node moving to a checkpoint reads the same
state whenever it moves, as long as it holds the same events after.
* **On Automerge.** For any run of events, changes, refusals, drops, checkpoints,
- remakes, rejoins and writers forked, the events a node's document holds, but for what
- it forgot, are the events it took, and its state is that of a store given those events
- alone.
+ remakes, rejoins and writers forked, the events a node takes from its document are
+ those a store given the same events alone takes, and honest nodes hold the same
+ document whatever each takes from it.
* **Bytes.** Fixed vectors, byte for byte: events and their IDs, checkpoints, a genesis
change, a fork's, a merge's, a snapshot.