From d425caf4a4b66e0794155f9593352b81cb87f2fe Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 15:15:40 +0000 Subject: docs/store: the document judges structure, the store judges events A change of a swarm holding a store is judged by what it is alone: it puts new keys under `_continuum/events` whose bytes hash to them, writes its node's own protocol data, carries its node's signature and is one Automerge writes. The store reads the events the document holds and takes them as it would from anywhere, each once it holds its dependencies, judged at its history; the rest stays in the document until the next remake. So a fold's verdict, a node's own refusal or a checkpoint refuses no change, nodes no longer drop and rebuild their documents at a move, and honest nodes hold one document whatever each reads from it. Membership is no longer judged at a change's history; a node keeps its own refusals and drops in a file of its own. Events are put again only where continuum refuses a change on its own, as of a writer's two changes of one number. --- docs/store.md | 90 +++++++++++++++++++++++++++++++---------------------------- 1 file changed, 47 insertions(+), 43 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/` 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. - -### Events, whichever change put them - -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. +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. + +### 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. + +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. -- cgit v1.3.1