summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:41:10 +0000
committertv <tv@krebsco.de>2026-11-18 13:42:58 +0100
commit0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (patch)
treecd8d576ac13160163a2cee508cf985ef183b3a01
parentb0f0e1a9edb08b324df2ec5e97d15e7089349fdb (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.
-rw-r--r--docs/access.md160
-rw-r--r--docs/api.md31
-rw-r--r--docs/federation-tests.md12
-rw-r--r--docs/federation.md266
-rw-r--r--docs/guides/federation/checkpoints.md2
-rw-r--r--docs/guides/federation/proposing-and-voting.md5
-rw-r--r--docs/guides/federation/running-a-node.md2
-rw-r--r--docs/guides/federation/writing-and-reading.md2
-rw-r--r--docs/measurements.md2
-rw-r--r--docs/remakes.md6
-rw-r--r--docs/store.md140
11 files changed, 326 insertions, 302 deletions
diff --git a/docs/access.md b/docs/access.md
index 71725e2..7c6c7e6 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -33,16 +33,16 @@ password hashes: every member reads the document).
doesn't read is left out, and anything but `false` disables.
* **`keys`**: the user's SSH keys, each by a name of its choosing, as an
`authorized_keys` line has it (`"laptop": "ssh-ed25519 AAAA… alice@laptop"`; Ed25519
- only; the comment, 256 bytes at most, is kept and checks nothing): what it signs values with (Values signed by their users, below) and logs in with. A user
- manages its own, whatever else it may do: `GET /auth/keys`, `PUT /auth/keys/<name>`
- with the line, `DELETE /auth/keys/<name>` (not with a token that has a `limit`); under a
- strict policy, by signing its
- entry with only its keys changed (`continuum-signed key-add laptop
- ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a key it holds already. Every
- node takes that from the user itself, as from one who may manage users. Its last key
- it removes only on a node where it has a password (`--htpasswd`), which it logs in
- by then (`409` elsewhere); under a strict policy, never (it signs its entry with
- one).
+ only; the comment, 256 bytes at most, is kept and checks nothing): what it signs values
+ with ([Values signed by their users](#values-signed-by-their-users), below) and logs in
+ with. A user manages its own, whatever else it may do: `GET /auth/keys`,
+ `PUT /auth/keys/<name>` with the line, `DELETE /auth/keys/<name>` (not with a token that
+ has a `limit`); under a strict policy, by signing its entry with only its keys changed
+ (`continuum-signed key-add laptop ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a
+ key it holds already. Every node takes that from the user itself, as from one who may
+ manage users. Its last key it removes only on a node where it has a password
+ (`--htpasswd`), which it logs in by then (`409` elsewhere); under a strict policy, never
+ (it signs its entry with one).
## A new swarm
@@ -52,16 +52,17 @@ everything (`[]` and `["_continuum"]`). Other users, of its `--htpasswd` or any
may do nothing until added (the genesis node warns of those of its `--htpasswd`). With
`--bootstrap-keys alice=ssh-ed25519\ AAAA…\ laptop` it records their keys too, so they
log in by key and sign values from the start, and with
-`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy (Values signed by
-their users, below) in the same change: the swarm is strict from its start, and no
-change of it is from before the policy. So it starts empty: content (`--genesis
---remake`) would be a change of its own before that one, and is refused with a strict
-policy; a swarm started from content turns strict through a strict remake (Turning a
-swarm strict, below).
-Without it, the swarm has no registry: its users are all alike (A swarm without a
-registry, below), until someone gives it one. `--protocol-writers` counts in
-both: without a registry, as who may write protocol data; with one, to set it right
-should nobody be left who may manage users (Keeping the swarm manageable, below).
+`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy
+([Values signed by their users](#values-signed-by-their-users), below) in the same change:
+the swarm is strict from its start, and no change of it is from before the policy. So it
+starts empty: content (`--genesis --remake`) would be a change of its own before that one,
+and is refused with a strict policy; a swarm started from content turns strict through a
+strict remake ([Turning a swarm strict](#turning-a-swarm-strict), below). Without it, the
+swarm has no registry: its users are all alike
+([A swarm without a registry](#a-swarm-without-a-registry), below), until someone gives it
+one. `--protocol-writers` counts in both: without a registry, as who may write protocol
+data; with one, to set it right should nobody be left who may manage users
+([Keeping the swarm manageable](#keeping-the-swarm-manageable), below).
## At the HTTP API
@@ -70,17 +71,17 @@ change to it counts on a node as soon as it has reached it.
* **The store** (`/store`, `/stream`): writing a path (`PUT`, `POST`, `DELETE`) takes
`write` on it, or, inside a list or text, on the list, as every node judges the
- change (a list's items have no paths of their own, Changes judged on every node,
- below); `?prune=true` deletes maps left empty only up to the highest one the
- user may write. Reading takes `read`: of a place the user may read only partly, it
- sees the keys on the way to what it may read, as a directory one may pass through
- but not list (a capability on `servers/eu` shows `servers` with `eu` alone in it),
- and nothing else; a list on the way is left out whole, as its items have no paths of
- their own. A shallow read (`?shallow=true`) shows such a map as a map and no more (no
- size), and nothing beside the way: a scalar at a `*` no capability covers stays
- hidden. Native forms (`text/plain` of a map, a counter as its own type) only of
- what it may read whole. What a write answers with is what was written. A stream
- shows what the user could read when it opened.
+ change (a list's items have no paths of their own,
+ [Changes judged on every node](#changes-judged-on-every-node), below); `?prune=true`
+ deletes maps left empty only up to the highest one the user may write. Reading takes
+ `read`: of a place the user may read only partly, it sees the keys on the way to what it
+ may read, as a directory one may pass through but not list (a capability on `servers/eu`
+ shows `servers` with `eu` alone in it), and nothing else; a list on the way is left out
+ whole, as its items have no paths of their own. A shallow read (`?shallow=true`) shows
+ such a map as a map and no more (no size), and nothing beside the way: a scalar at a `*`
+ no capability covers stays hidden. Native forms (`text/plain` of a map, a counter as its
+ own type) only of what it may read whole. What a write answers with is what was written.
+ A stream shows what the user could read when it opened.
* **Protocol data** is in the store too, under `_continuum`: `read` and `write` on it
as on any path.
* **Looking at the node** (`/admin/stats`, `GET /peers`, the dashboard): any user with
@@ -154,9 +155,9 @@ curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store
write anything as anyone ([`trust.md`](trust.md)). A token is a bearer's: whoever holds it is
the user until it ends, so it goes over TLS only, as passwords do.
-A user with keys in its entry (`keys`, The registry, above) logs in on any node without
-a password: it asks for a challenge, signs it with one of its keys, and gets the same
-token (`login: "key"`).
+A user with keys in its entry (`keys`, [The registry](#the-registry), above) logs in on
+any node without a password: it asks for a challenge, signs it with one of its keys, and
+gets the same token (`login: "key"`).
```sh
c=$(curl -s -X POST localhost:3000/auth/challenge | jq -r .challenge)
@@ -292,9 +293,10 @@ stays as it is, wherever it comes from later (a joining node catching up, say).
* Everything else, protocol data or not, by a user the registry lets write there.
* A map made on the way to what a change writes, where there was none (`servers`, for a
first write at `servers/eu/0`), as what it writes within it.
-* A node that isn't a member may only register itself; a banned node nothing (Banning
- a node, below). So a node registers before anything else it writes, through the API
- or its own: a change refused stays out with every change built on it.
+* A node that isn't a member may only register itself; a banned node nothing
+ ([Banning a node](#banning-a-node), below). So a node registers before anything else it
+ writes, through the API or its own: a change refused stays out with every change built
+ on it.
A node judges each change it makes the same way before it leaves, its own writes and
those through the API alike: one every node would refuse is rolled back, never
@@ -422,7 +424,7 @@ A member's node signs its changes, but the user a change names is its node's wor
member could write as any user. A swarm can have its users sign the values that
matter themselves, with their SSH keys, so no member can write them but as a user
signed them: the policy's `"values": "signed"` (strict; it requires signatures too),
-given to its genesis node (A new swarm, above):
+given to its genesis node ([A new swarm](#a-new-swarm), above):
```sh
continuum --genesis --bootstrap-users alice \
@@ -448,10 +450,10 @@ it logs in by key, writes and deletes signed values (`put config '{"mode": "fast
and checks one against its user's keys (`verify config`).
What a client reads to check a signature, the signer's keys, is in the registry, and
-whom to seal for (Values sealed for their readers, below) in `_continuum/access`: both
-protocol data, which a user's capabilities cover only if given so. Neither holds
-secrets (every member holds the document), so give the users who check or seal reading
-them:
+whom to seal for ([Values sealed for their readers](#values-sealed-for-their-readers),
+below) in `_continuum/access`: both protocol data, which a user's capabilities cover only
+if given so. Neither holds secrets (every member holds the document), so give the users
+who check or seal reading them:
```sh
curl -u alice -X POST -H 'Content-Type: application/json' \
@@ -468,40 +470,40 @@ _continuum/users/bob '{…}'`).
A node takes one only from that user, for that path, replacing what is there, by one of
the user's keys, and if the user may write there ([`api.md`](api.md), Signed values); it
writes nothing else there, nor within or above such a value (`409`), and the users API
-changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`, A
-new swarm, above) or through a remake (Turning a swarm strict, below), which keeps only
-what an operator looked over: each is its epoch's first change, so no change of a strict
-epoch is from before its policy. A change writing a strict policy where the policy isn't
-strict is refused; and a policy reads strict only where its `values` is a string, as
-continuum writes it: one that would read strict only through an Automerge text is one no
-node knows, never what its characters spell. A strict swarm stays strict: its policy is written again only
-as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a node
-that doesn't know a policy reads it as none it can judge by); to leave it, start a new
-swarm from its content (A new swarm, above). A value there that isn't an envelope starts
-its chain anew: any envelope its user once signed for that path replacing nothing
-(`prev` empty) can be put there again. Without the policy, signed values may be written
-all the same, and plain ones too.
+changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`,
+[A new swarm](#a-new-swarm), above) or through a remake
+([Turning a swarm strict](#turning-a-swarm-strict), below), which keeps only what an
+operator looked over: each is its epoch's first change, so no change of a strict epoch is
+from before its policy. A change writing a strict policy where the policy isn't strict is
+refused; and a policy reads strict only where its `values` is a string, as continuum
+writes it: one that would read strict only through an Automerge text is one no node knows,
+never what its characters spell. A strict swarm stays strict: its policy is written again
+only as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a
+node that doesn't know a policy reads it as none it can judge by); to leave it, start a
+new swarm from its content ([A new swarm](#a-new-swarm), above). A value there that isn't
+an envelope starts its chain anew: any envelope its user once signed for that path
+replacing nothing (`prev` empty) can be put there again. Without the policy, signed values
+may be written all the same, and plain ones too.
Keep two users who may manage users, or two keys each: under a strict policy, a
registry whose only manager lost its keys changes no more (the protocol writers do
everything there again only while nobody may manage users).
-Every node judges the changes it receives alike (Changes judged on every node, above),
-as their writer saw the registry: at such a place, only a string that is an envelope
-that checks, replacing the one there then; nothing within one; and above one, nothing
-replacing or deleting what holds one (a map made where there is none yet is fine). So
-a member writing to its document directly gets nothing there past the others: the
-registry, the policy and the bans change only as a user who may change them signed.
-But "may" is read where a change was written, which its writer chooses: a capability
-revoked, a user disabled or a key removed holds against members that weren't members
-before it, not against one that was, with a user that could sign then. That member can
-commit, at a history from before, an envelope the user signed then, numbered after what
-was there then, and the next after it, as far as it likes; the place's value is then
-the one with the highest `seq`. A remake ends it: nothing is written at a history from
-before the new epoch.
-A remake is outside this: its snapshot is the quorum's, so a `replace` or `import`
-remake a majority of members commits writes at signed places whatever its content
-holds, plain values too.
+Every node judges the changes it receives alike
+([Changes judged on every node](#changes-judged-on-every-node), above), as their writer
+saw the registry: at such a place, only a string that is an envelope that checks,
+replacing the one there then; nothing within one; and above one, nothing replacing or
+deleting what holds one (a map made where there is none yet is fine). So a member writing
+to its document directly gets nothing there past the others: the registry, the policy and
+the bans change only as a user who may change them signed. But "may" is read where a
+change was written, which its writer chooses: a capability revoked, a user disabled or a
+key removed holds against members that weren't members before it, not against one that
+was, with a user that could sign then. That member can commit, at a history from before,
+an envelope the user signed then, numbered after what was there then, and the next after
+it, as far as it likes; the place's value is then the one with the highest `seq`. A remake
+ends it: nothing is written at a history from before the new epoch. A remake is outside
+this: its snapshot is the quorum's, so a `replace` or `import` remake a majority of
+members commits writes at signed places whatever its content holds, plain values too.
### Turning a swarm strict
@@ -546,9 +548,10 @@ writing `_continuum/remakes`.
## Values sealed for their readers
Anyone may read the whole document: every member holds it. A value only some may read
-is sealed for them: encrypted with age to their SSH keys (`keys`, The registry,
-above), so only they open it. Every node syncs, stores and remakes it as the string it
-is, and none decrypts it: `cs1.<the age file, base64url>` (binary, not armored).
+is sealed for them: encrypted with age to their SSH keys (`keys`,
+[The registry](#the-registry), above), so only they open it. Every node syncs, stores and
+remakes it as the string it is, and none decrypts it: `cs1.<the age file, base64url>`
+(binary, not armored).
```sh
jq -r '.keys[]' <(curl -s -u alice localhost:3000/store/_continuum/users/bob) > readers
@@ -570,10 +573,11 @@ exactly their keys, as the registry has them when it is written. A node tells wi
decrypting: an age file names each `ssh-ed25519` recipient by a tag, the first four
bytes of the SHA-256 of its key. A write leaving a value there plain, or sealed for a
reader's key too few or a stranger's too many, is refused (`409`), and with the policy
-every node refuses such a change on receipt (Changes judged on every node, above). A
-value signed by its user (Values signed by their users) holds the sealed value; the
-signature is over the ciphertext, so every node checks who wrote it without reading
-it.
+every node refuses such a change on receipt
+([Changes judged on every node](#changes-judged-on-every-node), above). A value signed by
+its user ([Values signed by their users](#values-signed-by-their-users)) holds the sealed
+value; the signature is over the ciphertext, so every node checks who wrote it without
+reading it.
`scripts/continuum-signed` seals and opens them too, with age: `seal secrets/db
'{"password": "…"}'` seals for the readers declared there (or `CONTINUUM_READERS`),
diff --git a/docs/api.md b/docs/api.md
index 05abf44..418d7b9 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -26,12 +26,14 @@ curl -u alice:secret -X POST 'localhost:3000/store/stats/visits?increment=1' #
* `GET /store/<path>` reads, `PUT` writes (what is there then reads as the value
written; the maps on the way are created), `DELETE` deletes (`?prune=true` also
removes the maps it leaves empty), and `POST` inserts into a list at an index, the
- items from there moving up, or with `?increment=n` adds `n` to a counter (Concurrent
- writes), or with `?cast=<type>` casts what is there to another type (Types).
- `?signed=true` on any of them has the node sign the change (Signed changes).
+ items from there moving up, or with `?increment=n` adds `n` to a counter
+ ([Concurrent writes](#concurrent-writes)), or with `?cast=<type>` casts what is there to
+ another type ([Types](#types)). `?signed=true` on any of them has the node sign the
+ change ([Signed changes](#signed-changes)).
* Bodies are JSON (`application/json`, the default), text (`text/plain`, stored as a
- string), or a value of a type of its own (Types); answers are JSON, or as `Accept`
- asks. Numbers in JSON are stored as integers where they fit, as floats otherwise.
+ string), or a value of a type of its own ([Types](#types)); answers are JSON, or as
+ `Accept` asks. Numbers in JSON are stored as integers where they fit, as floats
+ otherwise.
* Every request needs a user from the node's `--htpasswd` (basic authentication: send
the password with the request, as `curl -u` does; the node asks for one with a
`401`'s `WWW-Authenticate` only of what isn't a browser, by its `Sec-Fetch-*`
@@ -165,9 +167,9 @@ way on every node:
Automerge's operation order (the write made after seeing more changes; between equals,
by the writer's actor ID), not by any clock: of two truly concurrent writes, which wins
is arbitrary, but it is the same on every node. Where the swarm's policy asks for
- signed values (Signed values, below), a string that is an envelope comes before
- anything else written there at once, a map too: of those, the one its user numbered
- highest (`seq`), of equal ones the one with the lower SHA-256.
+ signed values ([Signed values](#signed-values), below), a string that is an envelope
+ comes before anything else written there at once, a map too: of those, the one its user
+ numbered highest (`seq`), of equal ones the one with the lower SHA-256.
* **Maps written at the same key** merge into one: their keys are united, each key as
above.
* **A write and a delete** of the same key: the write stays (a delete removes only what
@@ -225,8 +227,8 @@ A node serves the store once it holds the swarm's document ([`lifecycle.md`](lif
* **Rejoining** a newer epoch after a remake it missed: reads answer from the document
before, with `x-continuum-stale` naming that epoch; writes are answered as usual and
go into that document (so reads show them), carried over into the new epoch when the
- rejoin ends, unless newer writes touched their paths (Concurrent writes); streams are
- `503`.
+ rejoin ends, unless newer writes touched their paths
+ ([Concurrent writes](#concurrent-writes)); streams are `503`.
* **Remakes** ([`remakes.md`](remakes.md)) don't interrupt anything else: a node switches to the new
document between two requests, and writes made meanwhile are carried over (at
their path, or where the remake's rules put them; [`remakes.md`](remakes.md), Writes around a
@@ -245,10 +247,11 @@ are each node's own (`--htpasswd`, or its proxy's): `alice` on two nodes is one
only where their operators make it so, which nothing checks.
`GET /admin/changes` lists them,
newest first, with the paths each touched and whether a signature by its node vouches
-for it (`verified`, Signed changes), and `GET /admin/refused` those this node refused under the swarm's policy ([`access.md`](access.md), Changes judged on every node); `GET /admin/changes/settings` those that
-touched what is at `settings`.
-Every node holds every change, so user names are known to the whole swarm, and so is
-who wrote what, until a remake drops the history ([`remakes.md`](remakes.md)).
+for it (`verified`, [Signed changes](#signed-changes)), and `GET /admin/refused` those
+this node refused under the swarm's policy ([`access.md`](access.md), Changes judged on
+every node); `GET /admin/changes/settings` those that touched what is at `settings`. Every
+node holds every change, so user names are known to the whole swarm, and so is who wrote
+what, until a remake drops the history ([`remakes.md`](remakes.md)).
## Signed changes
diff --git a/docs/federation-tests.md b/docs/federation-tests.md
index ba182ad..47b76e8 100644
--- a/docs/federation-tests.md
+++ b/docs/federation-tests.md
@@ -1,11 +1,11 @@
# Testing the store and the federation: a plan
-A plan, built stage by stage (By stage): so far, the store's tests, the federation's
-fold's, the store's on Automerge, the forks', and the remakes' (stages 1 to 5). It says
-how the store ([`store.md`](store.md)) and the federation
+A plan, built stage by stage ([By stage](#by-stage)): so far, the store's tests, the
+federation's fold's, the store's on Automerge, the forks', and the remakes' (stages 1 to
+5). It says how the store ([`store.md`](store.md)) and the federation
([`federation.md`](federation.md)) are tested, so that nothing in continuum breaks the
-federation, and no change made later breaks it apart. It is the contract the code is
-built to: a stage is done when its tests are.
+federation, and no change made later breaks it apart. It is the contract the code is built
+to: a stage is done when its tests are.
## What the tests rest on
@@ -22,7 +22,7 @@ built to: a stage is done when its tests are.
document and checks that every row has its test, and that no test names a row that
isn't there.
* **Every byte is fixed.** Every encoding the nodes must agree on has vectors, byte for
- byte (Fixed bytes).
+ byte ([Fixed bytes](#fixed-bytes)).
* **Nothing else changes.** All of it is behind the `federation` feature. A build
without it runs the tests continuum has today, untouched, and passes them.
diff --git a/docs/federation.md b/docs/federation.md
index 5faa478..2b76fdf 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -1,18 +1,17 @@
# Federation: a design
-A design, built stage by stage (Stages): so far, the store it builds on, held in memory
-and in a swarm's document, members by the federation and the store at a node's API, as
-[`store.md`](store.md) says; the federation as its fold (`federation::fold`), with the
-byte formats; a party's client (`continuum-party`, `federation::client`), which signs
+A design, built stage by stage ([Stages](#stages)): so far, the store it builds on, held
+in memory and in a swarm's document, members by the federation and the store at a node's
+API, as [`store.md`](store.md) says; the federation as its fold (`federation::fold`), with
+the byte formats; a party's client (`continuum-party`, `federation::client`), which signs
its party's events, votes by its record, signs again what a move refused, and names a
party that voted twice; and votes a node casts by itself (`federation::vote`), following
parties and proposing checkpoints, which back a checkpoint by the voters' rule, and
through which its party votes by hand. It says how a swarm can be kept by parties that
don't trust each other, for a first use: the krebs registry
([krebs/kartei](https://github.com/krebs/kartei)), today plain files in a git repository
-that one maintainer merges into. What it is for is narrow: to hand out identifiers
-(names, addresses, keys), and to give every party a namespace of its own that everyone
-reads.
+that one maintainer merges into. What it is for is narrow: to hand out identifiers (names,
+addresses, keys), and to give every party a namespace of its own that everyone reads.
It asks as little as it can of continuum and promises the least that makes a federation
possible. A federation that cooperates settles fast; one that doesn't comes apart, and
@@ -21,11 +20,12 @@ whoever wants to carry on with whom does so. Claims about the code are marked
## Optional
-A swarm is federated from its genesis change, or not at all (Starting a federation).
-Nothing else changes: a swarm that isn't stays as it is, its registry, rules, remakes
-and replay included. Which federation a swarm follows is a number of its own, in each
-version of its policy: this design is federation 1 (Changing the federation). Any group
-carries on with the policy it wants by forking (Forks), and leaves the federation by
+A swarm is federated from its genesis change, or not at all
+([Starting a federation](#starting-a-federation)). Nothing else changes: a swarm that
+isn't stays as it is, its registry, rules, remakes and replay included. Which federation a
+swarm follows is a number of its own, in each version of its policy: this design is
+federation 1 ([Changing the federation](#changing-the-federation)). Any group carries on
+with the policy it wants by forking ([Forks](#forks)), and leaves the federation by
starting a swarm of another kind, with what it takes along.
## Parties and the adversary
@@ -64,10 +64,11 @@ nothing coming from any node breaks a promise for the others.
2. **The policy changes only by the votes of two thirds of its parties**, as one history
saw their votes; and nodes that hold the same events read the same policy. Without
keys voting twice, a version that passed stays, on every node; with them, the nodes
- part, and the parties fork (Changing the policy).
+ part, and the parties fork ([Changing the policy](#changing-the-policy)).
3. **Any group carries on as it chooses.** Its parties fork with the policy they want,
and whoever wants to follow does; groups that parted come together as parties come
- in, one letting the other's in (Forks). Nobody is held by parties it doesn't follow.
+ in, one letting the other's in ([Forks](#forks)). Nobody is held by parties it doesn't
+ follow.
Not promised:
@@ -78,14 +79,15 @@ Not promised:
writers without end or keep remakes from committing ([`store.md`](store.md)), makes
nodes slow, or runs them out of memory, not wrong: denial of service breaks no promise
here, and the others fork away from it;
-* that honest nodes stay together where keys voted twice (Changing the policy): each
- node keeps the version it took, until its operator has it drop it, and one that had
- taken neither of two (it lagged behind, or joins) may be shown either first;
+* that honest nodes stay together where keys voted twice
+ ([Changing the policy](#changing-the-policy)): each node keeps the version it took,
+ until its operator has it drop it, and one that had taken neither of two (it lagged
+ behind, or joins) may be shown either first;
* that what isn't above a checkpoint's heads is taken once nodes moved to it: its party
- signs it again (Checkpoints);
+ signs it again ([Checkpoints](#checkpoints));
* that a node joining from the root, in a federation that never passed a checkpoint,
isn't shown a chain old keys grew: of two versions changing one it takes neither, but
- where its seeds are all the adversary's it is shown one (Checkpoints);
+ where its seeds are all the adversary's it is shown one ([Checkpoints](#checkpoints));
* that a checkpoint, or a fork's root, that a node takes on its operator's word is the
one the others built ([`store.md`](store.md), Pinned checkpoints).
@@ -133,13 +135,14 @@ Spread out:
key set are spelled so too, and node IDs as continuum spells them: `continuum:` and
the 64 lower-case hex digits of the node's Ed25519 public key.
* **What it does**, one field of:
- * `write`, `{"path": "<path>", "value": <value>}`: a value at a place (The policy);
- * `keys`, `["<key>", …]`: the party's key set (Keys);
- * `nodes`, `["<node ID>", …]`: its node list (Nodes);
- * `proposal`, a version, the object (Changing the policy);
+ * `write`, `{"path": "<path>", "value": <value>}`: a value at a place
+ ([The policy](#the-policy));
+ * `keys`, `["<key>", …]`: the party's key set ([Keys](#keys));
+ * `nodes`, `["<node ID>", …]`: its node list ([Nodes](#nodes));
+ * `proposal`, a version, the object ([Changing the policy](#changing-the-policy));
* `vote`, `{"on": "<hash>", "proposal": "<hash>", "yes": true}`, `"yes"` `true` or
- `false` (Changing the policy): a version's hash, the SHA-256 of its JCS bytes,
- written as an ID is.
+ `false` ([Changing the policy](#changing-the-policy)): a version's hash, the SHA-256
+ of its JCS bytes, written as an ID is.
* **`sig`**: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`)
over the event's bytes without `sig`: the SSHSIG blob of version 1, hashed with
`sha512`, its key the event's `key`, its reserved field empty, as `ssh-keygen` writes
@@ -153,8 +156,8 @@ Spread out:
makes either; a party's client makes `s` low.
Three things no party signs, as their bytes need no signer, each without `party`, `key`
-and `sig`: a version event (Changing the policy), and a federation's root and a fork's,
-which are checkpoints (Checkpoints).
+and `sig`: a version event ([Changing the policy](#changing-the-policy)), and a
+federation's root and a fork's, which are checkpoints ([Checkpoints](#checkpoints)).
An event is none if its bytes aren't the JCS encoding of the JSON they read as, if a
field is missing or more, if its `key` or `sig` doesn't read back to itself spelled as
@@ -171,14 +174,15 @@ another event of what a party signed. Of an event, federation 1 allows:
It names no swarm, no version and no ID of its own: its history says the first two. An
event signed in a federation, or in a fork once it forked, has that store's root in its
history, and no other store takes it ([`store.md`](store.md), Forks). An event is
-**written under** the version current at its history (Changing the policy).
+**written under** the version current at its history
+([Changing the policy](#changing-the-policy)).
### The policy
What the policy says is in its **versions**, a chain: each is a JSON object, named by
the SHA-256 of its JCS bytes, numbered, and naming the version it changes (`null` for
the first, number 0, which only the federation's root holds; a fork's changes the one
-current at its heads, Forks). Spread out:
+current at its heads, [Forks](#forks)). Spread out:
```json
{ "federation": 1, "number": 7, "changes": "<hash of the version it changes>",
@@ -201,19 +205,19 @@ current at its heads, Forks). Spread out:
it changes.
* **The parties and their keys** (`keys`): one party at least, each by name, as
continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -`, with one key or more
- (`ssh-ed25519` or `ecdsa-sha2-nistp256`, Events), none twice in the version. With them
- the party signs its votes and proposals on this version, its key set and its node list
- (Keys, Nodes). Its `since` is the number of the version that named them anew: this
- one's where it does (a party new in it, keys the parties replace, or the same keys
- named anew), else the `since` the version it changes gives the party, whose keys it
- then names unchanged.
+ (`ssh-ed25519` or `ecdsa-sha2-nistp256`, [Events](#events)), none twice in the version.
+ With them the party signs its votes and proposals on this version, its key set and its
+ node list ([Keys](#keys), [Nodes](#nodes)). Its `since` is the number of the version
+ that named them anew: this one's where it does (a party new in it, keys the parties
+ replace, or the same keys named anew), else the `since` the version it changes gives the
+ party, whose keys it then names unchanged.
* **The node lists** (`nodes`): every party's, a list of node IDs, none twice, with its
`since` as keys have one. The version that lets a party in names its list anew, empty
where it gives it no nodes, so that a list it wrote before it was taken out counts no
more; a later version may name it anew again; the first version and a fork's name
- those of the parties that start it (Nodes).
+ those of the parties that start it ([Nodes](#nodes)).
* **The checkpoint** (`checkpoint`), where the version names one: the heads at which the
- store moves to a checkpoint once the version is current (Checkpoints).
+ store moves to a checkpoint once the version is current ([Checkpoints](#checkpoints)).
* **The rules**, in order: the first whose path matches a path says who writes there. A
path is segments separated by `/`, none empty. A rule's first segment is literal, and
not `_continuum`; any other is literal, `{party}` (the name of a party of the version,
@@ -224,13 +228,13 @@ current at its heads, Forks). Spread out:
A **place** is a path a rule matches. A party writes there by a `write` event,
`{"path": …, "value": …}`: any JSON value, `null` emptying the place. Its value is the
-latest its party signed there that counts (What counts). A place is a path, not a key in
-a tree: a version may give a place and places below it alike, and nothing is both a
-value and the way to others. How names and addresses are spelled as paths is the
-application's: the registry writes a name by its labels, last first
-(`names/r/tv/toaster` for `toaster.tv.r`, `names/r/tv` for `tv.r`), and an address by
-its parts, so that a party's zone or block takes a rule or two. Rules go by first match,
-so a party named like a shared name takes it where a `{party}` rule comes before it: the
+latest its party signed there that counts ([What counts](#what-counts)). A place is a
+path, not a key in a tree: a version may give a place and places below it alike, and
+nothing is both a value and the way to others. How names and addresses are spelled as
+paths is the application's: the registry writes a name by its labels, last first
+(`names/r/tv/toaster` for `toaster.tv.r`, `names/r/tv` for `tv.r`), and an address by its
+parts, so that a party's zone or block takes a rule or two. Rules go by first match, so a
+party named like a shared name takes it where a `{party}` rule comes before it: the
application keeps party names apart from its spelling (no party named `wiki` while
`wiki.r` is lass's).
@@ -242,7 +246,7 @@ whatever it holds: whether it is a version is asked where a version event names
that nodes knowing more of what a version may say don't part from those knowing less. A
node shows whether a proposal is a version by the federation it knows, and a party's
client backs none that isn't: two thirds backing one that can never be written bind the
-federation to its version, as a yes binds (Changing the policy).
+federation to its version, as a yes binds ([Changing the policy](#changing-the-policy)).
What the swarm's document holds beyond the events, and what a node takes at its API, is
the store's ([`store.md`](store.md), On Automerge).
@@ -270,7 +274,8 @@ A party **votes** on a proposal by a `vote` event, naming the version the propos
dead, so that, once a checkpoint left them out, nothing names its party as voting
twice. A party votes from one client: two of its clients backing two proposals at once
is voting twice, as two of its nodes each voting by itself is, or a vote by hand
- beside the node that votes for it (Votes a node casts by itself).
+ beside the node that votes for it
+ ([Votes a node casts by itself](#votes-a-node-casts-by-itself)).
* **A proposal passes** once at least two thirds of its version's parties voted `true`
(3·yes ≥ 2·parties). It is **dead** once so many voted `false` that the rest can't
pass it (3·(parties − no) < 2·parties). A party whose `true` and `false` on one
@@ -332,7 +337,7 @@ chain the node took.
policy, and an event whose history holds both is refused, as no version is current
there; the sides are apart, and a node that lagged behind, or joins, may be shown
either first. The parties answer by forking, without the party that voted twice, or
- with its keys named anew (Forks).
+ with its keys named anew ([Forks](#forks)).
* **A party that voted twice shows** in the votes alone, both signed with keys their
version names for it: its `true` and `false` on one proposal, or its `true` on two
proposals of one version where neither is dead by all the votes cast. Where in history
@@ -350,7 +355,8 @@ chain the node took.
Everything the federation decides is a change of the policy: who the parties are, their
keys where they lost them, and their node lists where they have none; who writes where,
which is giving an identifier, taking it back and giving it to another; and the
-federation itself, by naming another (Changing the federation).
+federation itself, by naming another
+([Changing the federation](#changing-the-federation)).
### Keys
@@ -358,13 +364,13 @@ A party votes and proposes with the keys its version names for it, and signs wit
its key set and its node list. Everything else it signs with the keys of its **key
set**: a `keys` event, the list of its keys, none twice, signed with a key the version
it is written under names for the party. A set is checked only where it is written,
-never by the keys of a set (What counts, 2).
+never by the keys of a set ([What counts](#what-counts), 2).
-A party's keys are those of its set (What counts, 5) where the set is written under a
-version numbered at least the `since` its version gives the party's keys; otherwise, and
-while it has written none, those its version names. So once a version names a party's
-keys anew, no set written under an earlier version counts, and the party's next set
-does. Nothing is written for it: the version says it.
+A party's keys are those of its set ([What counts](#what-counts), 5) where the set is
+written under a version numbered at least the `since` its version gives the party's keys;
+otherwise, and while it has written none, those its version names. So once a version names
+a party's keys anew, no set written under an earlier version counts, and the party's next
+set does. Nothing is written for it: the version says it.
* **A value counts only while the key that signed it is among its party's keys**, as
above: votes, proposals, sets and node lists aside, which go by the keys their version
@@ -394,7 +400,7 @@ else does:
longer one, the place went to another, a rule changed; and of a party that is no
longer one, its key set and its node list;
2. a write signed by a key that isn't among its party's; and a key set or node list
- written under a version before the `since` its version gives it (Keys);
+ written under a version before the `since` its version gives it ([Keys](#keys));
3. a proposal on a version that isn't current, and the votes on that version;
4. a version behind the current one;
5. of the writes at a place that 1 and 2 leave, one another of them has in its history,
@@ -405,22 +411,23 @@ So a place's value, a party's set and its list are each the latest its party sig
counts: what the party signed after replaces what it signed before, whatever order the
events came in, and what counts no more replaces nothing. Nothing is deleted: a party
empties its place by writing `null`, and what counts no more stays in the store until a
-checkpoint leaves it out (Checkpoints). A place given back to its party, or a key added
-back, shows what the party signed before where nothing replaced it since and no
-checkpoint left it out, until the party writes there again. Two writes of one party at
-one place, neither in the other's history (two of its clients at once), leave the one
+checkpoint leaves it out ([Checkpoints](#checkpoints)). A place given back to its party,
+or a key added back, shows what the party signed before where nothing replaced it since
+and no checkpoint left it out, until the party writes there again. Two writes of one party
+at one place, neither in the other's history (two of its clients at once), leave the one
with the lower ID; the party writes again, after both, to choose.
### Checkpoints
A **checkpoint** writes down what counts at some heads: those heads, a version (the one
current there, or a fork's), and the IDs of the events that count there with that
-version current, version events aside, as it holds the version itself (What counts), as
-the JCS encoding of `{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs
-ascending and its version the version itself, the object, named by its SHA-256
-([`store.md`](store.md), Checkpoints). Every node holding the history up to those heads
-builds the same one, and its version counts as written: a version event of it that comes
-later is one the node took.
+version current, version events aside, as it holds the version itself
+([What counts](#what-counts)), as the JCS encoding of
+`{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs ascending and its
+version the version itself, the object, named by its SHA-256 ([`store.md`](store.md),
+Checkpoints). Every node holding the history up to those heads builds the same one, and
+its version counts as written: a version event of it that comes later is one the node
+took.
A version names a checkpoint by its heads (`checkpoint`): events after the current
checkpoint, at which it is current too, none in another's history, their IDs ascending,
@@ -435,26 +442,26 @@ they held for a while before it was proposed is among its heads, in their histor
above them: a move refuses what isn't above its heads, and heads a proposer made up,
built on little, would take back what was written since, a key set dropping a stolen key
among it. A node shows, for a proposed checkpoint, what it holds that its heads lack, as
-for a fork (Forks). This is the voter's rule, by its own clock: nothing more is judged.
-It is a version only where its proposal is above those heads, and a version event
-writing it is taken only where it is above them too, and so is every vote it is written
-on ([`store.md`](store.md), Events): so moving to the checkpoint refuses nothing that
-decided it. A party's client, and a node voting by itself, vote on the events proposing
-what they vote on, and a node proposes a checkpoint on its heads: so their votes are
-above those heads wherever the proposal is. A vote beside them binds its party as any
-yes does, until the move refuses it. A node that takes the version moves to the
-checkpoint: it builds it, forgets everything before those heads that it doesn't keep,
-and every event not above them, and refuses such events from then on. Judging an event
-after them needs nothing it forgot: the version, every party's keys and node list, and
-the proposals on the current version with their votes all count, and are kept. A node
-starting from a checkpoint reads what it keeps as written under its version, as it holds
-none of their histories: each was written under that one or an earlier, counting there,
-a kept proposal is on it, and a later `since` that leaves one out is past it. A node
-that can't build a checkpoint, as it was away across a move and a remake after it, or as
-it joins, takes it only where its operator pins it ([`store.md`](store.md), Pinned
-checkpoints). What it can't check of its heads it takes on its operator's word: that
-they are after the checkpoint current at the version naming them, at which that one is
-current too; so it judges that version as every node does.
+for a fork ([Forks](#forks)). This is the voter's rule, by its own clock: nothing more is
+judged. It is a version only where its proposal is above those heads, and a version event
+writing it is taken only where it is above them too, and so is every vote it is written on
+([`store.md`](store.md), Events): so moving to the checkpoint refuses nothing that decided
+it. A party's client, and a node voting by itself, vote on the events proposing what they
+vote on, and a node proposes a checkpoint on its heads: so their votes are above those
+heads wherever the proposal is. A vote beside them binds its party as any yes does, until
+the move refuses it. A node that takes the version moves to the checkpoint: it builds it,
+forgets everything before those heads that it doesn't keep, and every event not above
+them, and refuses such events from then on. Judging an event after them needs nothing it
+forgot: the version, every party's keys and node list, and the proposals on the current
+version with their votes all count, and are kept. A node starting from a checkpoint reads
+what it keeps as written under its version, as it holds none of their histories: each was
+written under that one or an earlier, counting there, a kept proposal is on it, and a
+later `since` that leaves one out is past it. A node that can't build a checkpoint, as it
+was away across a move and a remake after it, or as it joins, takes it only where its
+operator pins it ([`store.md`](store.md), Pinned checkpoints). What it can't check of its
+heads it takes on its operator's word: that they are after the checkpoint current at the
+version naming them, at which that one is current too; so it judges that version as every
+node does.
What a checkpoint loses: what counted no more before it, so that a key added back, or a
place given back, brings back nothing signed before it, and a party that voted twice on
@@ -475,8 +482,9 @@ what old keys can do to the versions after it.
A version that changes nothing but its number, what it changes and its checkpoint only
moves the store on. Like any version, it lapses the proposals on the version before, so
a party proposes one where nothing that can still pass is proposed on the current
-version. A federation's root is its first checkpoint, without heads (Starting a
-federation), and a fork's root a checkpoint at the heads it forks at (Forks).
+version. A federation's root is its first checkpoint, without heads
+([Starting a federation](#starting-a-federation)), and a fork's root a checkpoint at the
+heads it forks at ([Forks](#forks)).
### Votes a node casts by itself
@@ -487,10 +495,11 @@ as it judges any vote or proposal. The design has two in mind:
* **Following**: back a proposal where a party the rule names backed it, and vote
`false` where that party did; a proposal binds its proposer to nothing, so following
one would bind the node where that party is free. By default it follows only on a
- version that only moves to a checkpoint (Checkpoints), a `true` as a `false`; its
- operator may have it follow on any version, which hands that party the node's vote,
- its `false` among it: a party followed so by more than a third of the parties, its key
- kept on a node, ends every proposal, the one naming that key anew among them.
+ version that only moves to a checkpoint ([Checkpoints](#checkpoints)), a `true` as a
+ `false`; its operator may have it follow on any version, which hands that party the
+ node's vote, its `false` among it: a party followed so by more than a third of the
+ parties, its key kept on a node, ends every proposal, the one naming that key anew among
+ them.
* **Proposing a checkpoint**: propose a version that only moves to a checkpoint, at
heads the node has held for a while, once conditions its operator sets are met: so
many events or bytes held beyond its checkpoint, so many versions since it, or so long
@@ -505,33 +514,33 @@ Such a node keeps to what a party's client keeps to: one yes at a time; never `t
each voting by itself can vote twice; none for a proposal that is no version; and, by a
rule for checkpoints, none for a version that changes more than its number, what it
changes and its checkpoint, which it checks against the current one, nor for one whose
-heads leave out what it held for a while (Checkpoints). Where two checkpoints are
-proposed at once, the votes split, as any do; a rule may vote `false` on the one it
-doesn't back, so that one dies and its backers are free.
+heads leave out what it held for a while ([Checkpoints](#checkpoints)). Where two
+checkpoints are proposed at once, the votes split, as any do; a rule may vote `false` on
+the one it doesn't back, so that one dies and its backers are free.
It signs with a key the party's version names, which the party keeps on that node, not
apart: one stolen there votes, and writes the party's key set and node list, as the
-party's, until a version names its keys anew (Keys). A party that won't keep one there
-votes by hand. A party that has a node vote by itself votes by hand only through that
-node, which keeps the party's one record of its votes and refuses a vote that record
+party's, until a version names its keys anew ([Keys](#keys)). A party that won't keep one
+there votes by hand. A party that has a node vote by itself votes by hand only through
+that node, which keeps the party's one record of its votes and refuses a vote that record
forbids: a party votes from one client, and that node is it.
### Nodes
A party lists the nodes that carry for it, by node ID, in its **node list**: a `nodes`
event, the list of its nodes' IDs, none twice, signed with a key the version it is
-written under names for the party. A party's list is that one (What counts, 5) where it
-is written under a version numbered at least the `since` its version gives the party's
-list, otherwise the list its version gives, if any, as with keys (Keys). The store's
-members are the nodes each party's list names, each as its party's
-([`store.md`](store.md), Members); another party's list does nothing for a node. A
-party's list counts until the party writes another or a version names one anew, whatever
-keys its version names since, so that no change of keys leaves a swarm without members;
-a list a stolen key wrote stays until the party writes one under the version that
-replaced that key, which it can at once, through any member. A node puts whatever events
-it is given, its party's and others' alike: what counts is who signed an event, not
-which node put it. So a party without nodes of its own writes through any node that
-takes its events.
+written under names for the party. A party's list is that one
+([What counts](#what-counts), 5) where it is written under a version numbered at least the
+`since` its version gives the party's list, otherwise the list its version gives, if any,
+as with keys ([Keys](#keys)). The store's members are the nodes each party's list names,
+each as its party's ([`store.md`](store.md), Members); another party's list does nothing
+for a node. A party's list counts until the party writes another or a version names one
+anew, whatever keys its version names since, so that no change of keys leaves a swarm
+without members; a list a stolen key wrote stays until the party writes one under the
+version that replaced that key, which it can at once, through any member. A node puts
+whatever events it is given, its party's and others' alike: what counts is who signed an
+event, not which node put it. So a party without nodes of its own writes through any node
+that takes its events.
### Forks
@@ -540,13 +549,13 @@ the group won't follow passed, or the parties can't agree. It **forks**: it star
store of its own from the federation's ([`store.md`](store.md), Forks).
1. One of the group makes the fork's root, a checkpoint at the heads it forks at, which
- no party signs, so that one version and one set of heads make one fork (Checkpoints).
- Its version changes the version current at those heads, is numbered one past it, and
- names anew the keys of any party whose keys it changes; a root whose version doesn't
- is no fork. Its founders name their own node lists anew in it, so that their nodes
- are members there. It keeps the events that count at those heads with that version
- current. Every proposal is a chance to fork: the version is usually one that didn't
- pass.
+ no party signs, so that one version and one set of heads make one fork
+ ([Checkpoints](#checkpoints)). Its version changes the version current at those heads,
+ is numbered one past it, and names anew the keys of any party whose keys it changes; a
+ root whose version doesn't is no fork. Its founders name their own node lists anew in
+ it, so that their nodes are members there. It keeps the events that count at those
+ heads with that version current. Every proposal is a chance to fork: the version is
+ usually one that didn't pass.
2. A fork is named by its root's ID, which nobody can steer to a given name, the
federation it came from least of all. It takes only events with its root in their
history: what the stayers sign after it isn't taken there, nor what the fork's
@@ -570,9 +579,10 @@ keep, as a party's client signs again what a move refused. What one side signed
on the other only once it is signed there.
What a party's nodes do of themselves is their operators' business, written nowhere:
-join a fork their operator follows, vote by rules their operator set (Votes a node casts
-by itself), or do nothing without their operator. So a federation that cooperates can
-have a group that leads without being named: the active parties the others follow.
+join a fork their operator follows, vote by rules their operator set
+([Votes a node casts by itself](#votes-a-node-casts-by-itself)), or do nothing without
+their operator. So a federation that cooperates can have a group that leads without being
+named: the active parties the others follow.
### Shared identifiers
@@ -590,15 +600,15 @@ parties, zones, blocks and names that are nobody's by their spelling.
### Starting a federation
A federation starts with a store of its own: its root, a checkpoint without heads that
-keeps nothing, its version the first, which no party signs (Checkpoints), so one first
-version makes one federation, named by the root's ID. Among the node lists the version
-gives, one names a node of its founders', so the federation starts with members, and
-other nodes come in as their parties list them. Its swarm's genesis change holds the
-root, built byte for byte from it, its policy naming the fold `federation`
+keeps nothing, its version the first, which no party signs ([Checkpoints](#checkpoints)),
+so one first version makes one federation, named by the root's ID. Among the node lists
+the version gives, one names a node of its founders', so the federation starts with
+members, and other nodes come in as their parties list them. Its swarm's genesis change
+holds the root, built byte for byte from it, its policy naming the fold `federation`
(`{"version": 2, "store": "federation"}`, [`store.md`](store.md), On Automerge). So
-nothing is from before the federation: it changes by versions, and any group carries on
-by a fork. A running swarm doesn't become federated; its parties start one, and sign
-into it what they keep.
+nothing is from before the federation: it changes by versions, and any group carries on by
+a fork. A running swarm doesn't become federated; its parties start one, and sign into it
+what they keep.
## Why it holds
@@ -732,7 +742,7 @@ crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
* **The longest chain from the first version.** Old keys could still grow a chain longer
than the one nodes took.
* **A share each federation sets.** Two thirds is the federation's number's: another
- share is another federation (Changing the federation).
+ share is another federation ([Changing the federation](#changing-the-federation)).
* **Becoming federated in a running swarm.** It needs the time before closed, which
continuum doesn't do for a swarm turned strict either, values from before counting
only where a party signed them, and of two federating changes at once neither
diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md
index 0ff26fe..23f0e9c 100644
--- a/docs/guides/federation/checkpoints.md
+++ b/docs/guides/federation/checkpoints.md
@@ -17,7 +17,7 @@ their votes.
What it loses: what counted no more before the heads, so a key added back or a place
given back brings back nothing signed before them; votes on versions behind it, so a
party that voted twice there shows only in the votes the parties' clients kept; and what
-isn't above the heads, which its party signs again (After a move, below).
+isn't above the heads, which its party signs again ([After a move](#after-a-move), below).
## Proposing one
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index e342b5b..91da019 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -51,8 +51,9 @@ continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.
# proposal 8d02…
```
-With `--yes`, the client votes `true` on it too, as `vote 8d02… yes` does (Voting,
-below): a party whose node votes for it by itself votes through that node instead.
+With `--yes`, the client votes `true` on it too, as `vote 8d02… yes` does
+([Voting](#voting), below): a party whose node votes for it by itself votes through that
+node instead.
The client proposes only a version it would back: one changing the current one as a
version must (its `number`, `changes`, and each `since`), whose checkpoint, where it names
diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md
index a423376..b303fab 100644
--- a/docs/guides/federation/running-a-node.md
+++ b/docs/guides/federation/running-a-node.md
@@ -23,7 +23,7 @@ what its API lets in, and joining.
whenever it starts: without the file, it may then take what it refused. Keep it beside
the document file; one that doesn't read stops the node from starting.
* `--store-checkpoint ID`: a checkpoint the node reads its store from whenever it starts,
- instead of from the document's checkpoint, by its ID (Joining, below).
+ instead of from the document's checkpoint, by its ID ([Joining](#joining), below).
* `--store-neighbour-parties NAME,…`: parties among whose members, with its own party's,
the node keeps some of its neighbours.
* `--store-vote-key PATH` and the options with it: the node votes and proposes for its
diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md
index a9e0c5a..0a04773 100644
--- a/docs/guides/federation/writing-and-reading.md
+++ b/docs/guides/federation/writing-and-reading.md
@@ -68,7 +68,7 @@ A node refuses what every node refuses, judged at its history, and says why (`42
the federation spells one, or past its sizes.
* `it builds on …, refused` (`builtOn`): an event it builds on is refused.
* `it isn't above the checkpoint's heads` (`notAbove`): signed on heads a move to a
- checkpoint left behind (After a move, below).
+ checkpoint left behind ([After a move](#after-a-move), below).
And some by what the node took before (`own`), or as its operator had it drop them
(`dropped`): those are the node's alone ([`running-a-node.md`](running-a-node.md)).
diff --git a/docs/measurements.md b/docs/measurements.md
index 15aa614..d54f07b 100644
--- a/docs/measurements.md
+++ b/docs/measurements.md
@@ -139,7 +139,7 @@ How long changes written elsewhere took to reach this node, from the writer's co
stamp to the apply here, for every change in every applied sync message and every delta
fetched as a blob ([`peers.md`](peers.md)), once caught up.
The apply is timed by the peers' clocks: this node's own offset from them
-(`clock.offsetMs`, Clocks) is taken off.
+(`clock.offsetMs`, [Clocks](#clocks)) is taken off.
A histogram with buckets at 100 ms, 250 ms, 500 ms, 1 s, 2.5 s, 5 s, 10 s, 30 s, 1 min,
5 min, 1 h, and the rest.
diff --git a/docs/remakes.md b/docs/remakes.md
index 5a12873..94d50dc 100644
--- a/docs/remakes.md
+++ b/docs/remakes.md
@@ -395,8 +395,8 @@ remake report's `local.quarantine` on that node names the entry.
own`, error), but it follows peers that did: the epoch most of them are on. Nodes on
the other epoch of that generation rejoin it sideways once they see themselves
outnumbered (`More peers are on another epoch of this generation than on ours`,
- warn), and what was written there goes to quarantine ([`lifecycle.md`](lifecycle.md), Rejoining).
- Look at those quarantines; report how it came about (Limits).
+ warn), and what was written there goes to quarantine ([`lifecycle.md`](lifecycle.md),
+ Rejoining). Look at those quarantines; report how it came about ([Limits](#limits)).
* **Repairing records by hand.** Remake records live in the document under
`_continuum/remakes/<id>`. Old ones need no cleaning up: an epoch's document holds
the remakes proposed in it and the record of the remake that made it, and earlier
@@ -434,7 +434,7 @@ remake report's `local.quarantine` on that node names the entry.
in its electorate (with three members and one cut off, two joining on its side make
it 3 of 5 there, while the other side has 2 of 3). Two epochs of
the next generation result; the swarm follows the one more nodes are on, and the
- others' writes there are quarantined (Troubleshooting).
+ others' writes there are quarantined ([Troubleshooting](#troubleshooting)).
* **Same Automerge version.** Every node must build byte-identical snapshots, so all
nodes need the same Automerge version. A node whose build differs rejoins instead.
* **Lost votes.** Votes aren't stored outside the document. A node that voted, then
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