aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/federation.md762
1 files changed, 408 insertions, 354 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 3bdbe34..7548eef 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -16,11 +16,9 @@ are marked *(checked)* where they were read in it.
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. Continuum's wire version
-says only whether a node can take part in a federation at all; which federation a
-swarm follows is a number of its own, in its policy: this design is federation 1
-(Changing the federation). A swarm leaves the federation as any group carries on: by
-forking, with the policy it wants (Forks).
+and replay included. Which federation a swarm follows is a number of its own, in its
+policy: this design is federation 1 (Changing the federation). A swarm leaves the
+federation as any group carries on: by forking, with the policy it wants (Forks).
## Parties and the adversary
@@ -51,13 +49,13 @@ that nothing coming from any node breaks a promise for the others.
1. **What counts is what a party signed, with a key it holds, where the policy lets it
write.** Every honest node that holds the swarm from its genesis change, or
- followed every remake since, checking each, refuses what the version current at a
- change's history doesn't let be written, whoever sends it, and reads nothing else as
- counting.
-2. **The policy changes only by the votes of a share of its parties**, two thirds
- unless they decide otherwise, as one history saw their votes; and nodes that hold
- the same changes read the same policy. Without a party voting twice, a version that
- passed stays; with one, the parties fork without it (Changing the policy).
+ followed every remake since, building each itself, refuses what the version current
+ at a change's history doesn't let be written, whoever sends it, and reads nothing
+ else as counting.
+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 changes 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).
3. **Any group carries on as it chooses.** Its parties fork with the policy they want,
and whoever wants to follow does. Nobody is held by parties it doesn't follow.
@@ -69,26 +67,33 @@ Not promised:
* that the swarm stays fast. A party that floods the document, or whose nodes keep
remakes from committing, makes nodes slow, 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, and one that had taken neither of two (it lagged
+ behind, or joins) may be shown either first;
* that honest nodes stay together where a node commits two changes under one writer
- and number: they are apart until a remake, or a fork (Where Automerge sets limits);
-* that a node taken off its party's list, or a key a party dropped by itself, can't
- still commit or sign at a history from before: only a version ends what a key signs
- (Keys), and a remake ends what is written at the time before it;
-* anything to a node that joins, or comes back after a remake without holding the
- epoch before: it takes the document on its peers' word (Remakes);
-* that what nodes read stays put after a party voted twice, until the parties fork.
+ and number: they are apart until a fork (Where Automerge sets limits);
+* that a remake reaches every node: one that can't build it itself stays where it is
+ (Remakes);
+* that a node taken off its party's list can't still commit at a history from before:
+ from the next remake's base on, it can't;
+* anything to a node with an empty document: it takes the epoch its peers give it, or
+ the one its operator pins (Remakes).
## The design
-It builds on values signed by their users ([`access.md`](access.md)): a value is an
-envelope its party signs, `cv2.<value>.<meta>.<signature>`, read the one way every part
-of continuum reads it *(checked: `document::signed`)*. The meta names the swarm, the
-path, who signed, when, the envelope it replaces (`prev`) and its number there (`seq`,
-one more than that one's). Under the federation it names also the **version** of the
-policy current where it was written, by number (`version`, The policy): a change writing
-one that names another is refused, but for an epoch's first change (a remake's snapshot,
-a fork's genesis), which is judged by none, and for the keys a version sets, which name
-the version being written (Keys). Of the envelopes a place holds, written at
+It builds on values signed by their users ([`access.md`](access.md)): continuum's
+signed value, `cv2.<value>.<meta>.<signature>`, read the one way every part of
+continuum reads it *(checked: `document::signed`)*. The meta names the swarm, the path,
+who signed, when, the envelope it replaces (`prev`) and its number there (`seq`, one
+more than that one's). A federated swarm's value is an envelope its party signs, the
+same with a prefix of its own, `cv3.<value>.<meta>.<signature>`, whose meta names also
+the **version** of the policy current where it was written, by number (`version`, The
+policy). A swarm that isn't federated reads a `cv3.` string as the string it is.
+
+A change writing an envelope that names another version than the one current at its
+history is refused, but for an epoch's first change (a remake's snapshot, a fork's
+genesis), which is judged by none, and for the key sets and node lists a version sets,
+which name the version being written (Keys). Of the envelopes a place holds, written at
once, the one with the highest version number is its value, then the highest `seq`, then
the lower SHA-256. So what a place holds is its party's to say, never the order of
operations, which whoever writes a change steers; and what was signed under a later
@@ -106,9 +111,9 @@ federation's.
* **The document at a set of changes**: the tree its writes make, the same on every
node for the same set. A deletion removes what its writer saw, and nothing written
at the same time.
-* **Remakes that lose nothing and add nothing**: whatever continuum does to start the
- document anew, a node follows it only where the new document reads as the old one
- did at the base (Remakes).
+* **Remakes a node builds itself**: whatever continuum does to start the document
+ anew, a node follows it only where it built the new document itself, from a base it
+ holds (Remakes).
Continuum's document is an Automerge document, which gives all of this and has limits
worth knowing (Where Automerge sets limits).
@@ -117,18 +122,20 @@ worth knowing (Where Automerge sets limits).
A federated swarm's `_continuum/access/policy` is `{"version": 2, "federated": true}`.
What the policy says is in its **versions**, a chain: each is a string of JSON, named
-by the SHA-256 of its bytes, numbered, and naming the version it changes (none for
-the first, number 0, which only the genesis change writes; a fork's first, Forks):
+by the SHA-256 of its bytes, numbered, and naming the version it changes (`null` for
+the first, number 0, which only the genesis change writes; a fork's first, Forks).
+Spread out:
```json
{ "federation": 1, "number": 7, "changes": "<hash of the version it changes>",
- "share": [2, 3],
"keys": { "tv": ["ssh-ed25519 AAAA… tv"],
"lass": ["ssh-ed25519 AAAA… lass"],
"makefu": ["ssh-ed25519 AAAA… makefu"] },
+ "nodes": {},
"rules": [
- { "path": "names/r/wiki/@", "writer": "lass" },
+ { "path": "names/r/wiki", "writer": "lass" },
{ "path": "home/{party}/**", "writer": "{party}" },
+ { "path": "names/r/{party}", "writer": "{party}" },
{ "path": "names/r/{party}/**", "writer": "{party}" },
{ "path": "ip4/10/243/7/*", "writer": "tv" },
{ "path": "names/**", "writer": false } ] }
@@ -136,159 +143,188 @@ the first, number 0, which only the genesis change writes; a fork's first, Forks
* **The federation** it follows, and its **number**, one more than that of the version
it changes.
-* **The share** of the parties a proposal needs, two whole numbers `[a, b]`, 0 < a ≤ b,
- 2·a > b: with `[2, 3]`, the votes of two of every three (3·votes ≥ 2·parties).
-* **The parties and their keys**: each party by name, as continuum's user names, 1 to
- 64 of `A-Z a-z 0-9 . _ @ -`, with the keys its votes and proposals on this version
- are signed with. Where a party's keys, as keys, differ from those the version it
- changes names (a party new in it, or one whose keys the parties replace), the version
- **sets** them (Keys).
+* **The parties and their keys**: one party at least, each by name, as continuum's
+ user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -` but not `@`, with one `ssh-ed25519` key
+ or more, compared as keys (their comments aside), 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). Where a party's keys differ from those the version it
+ changes names (a party new in it, or one whose keys the parties replace), the
+ version **sets** them (Keys).
+* **The node lists it sets** (`nodes`), by party, each a list of node IDs: the first
+ version and a fork's set those of the parties that start it (Nodes).
* **The rules**, in order: the first whose path matches a path says who writes there.
- A path is segments separated by `/`. A rule's first segment is literal, and not
- `_continuum`; any other is literal, `{party}` (a party's name), `*` (any one
- segment) or, last only, `**` (one segment or more). The writer is `"{party}"` (the
- party the path names, where the rule's path holds `{party}`), a party's name, or
- `false`: nobody. A path no rule matches, nobody writes.
+ A path is segments separated by `/`, none empty. A rule's first segment is literal,
+ and not `_continuum`; any other is literal, `{party}` (a party's name, once in a rule
+ at most), `*` (any one segment) or, last only, `**` (one segment or more); none is
+ `@`. A rule matches a path key by key: a key holding `/` is one segment, which only
+ `*` and `**` match. The writer is `"{party}"` (the party the path names, only where
+ the rule's path holds `{party}`), a party of the version, or `false`: nobody. A path
+ no rule matches, nobody writes.
-A **place** is a map key where an envelope is written: never within a list, nothing
-written within one, and a path that holds places is no place. How names and addresses
-are spelled as paths is the application's: the registry writes a name by its labels,
-last first, its own value at `@` (`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 is one rule. 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 `@`, nor `wiki` while `wiki.r` is lass's).
+A **place** is a path a rule matches. Its value is the envelope in its `@` key
+(`names/r/tv/toaster/@`). An envelope goes only in an `@` key, an `@` key never holds a
+map, and a change writes nothing else where rules say who writes but the maps on the
+way to `@` keys, never deleting or replacing one: so no key is both a value and the way
+to places, whatever the rules of any version say, and a version may give a place and
+places below it alike. Nothing is written within a list. 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).
-A version is none if it doesn't read as one (JSON with a key twice, fields missing or
-more), its bytes don't hash to its place, or it breaks any of the above: it can't
-pass, and a change writing it is refused.
+A version is none if its bytes aren't the JCS encoding (RFC 8785) of the JSON they read
+as, so that nothing in it is spelled two ways and no key is there twice; if a field is
+missing or more; if its bytes don't hash to its place; or if it breaks any of the above.
+It can't pass, and a change writing it as a version is refused. A proposal is taken
+whatever its text, its party and version read from its place and its envelope: whether
+it is a version is asked where it is written as one, so that nodes knowing more of what
+a version may say don't part from those knowing less.
The federation's own paths are its number's, not the rules': the same in every
-version.
+version. They hold their values directly, and never nest.
| Where | What | Who writes it |
|---|---|---|
| `_continuum/federation/versions/<hash>` | a version that passed | any member, once it passed |
| `_continuum/federation/proposals/<party>/<hash>` | a version proposed | that party |
| `_continuum/federation/votes/<party>/<version>/<proposal>` | `true` or `false` | that party |
-| `_continuum/federation/keys/<party>` | its keys | that party; the change that writes a version setting them |
-| `_continuum/federation/nodes/<party>` | its nodes' IDs | that party |
-| `_continuum/federation/went/<party>` | the fork it went to | that party |
+| `_continuum/federation/keys/<party>` | its keys | that party, by a key its version names; the change writing a version that sets them |
+| `_continuum/federation/nodes/<party>` | its nodes' IDs | that party, by a key its version names; the change writing a version that sets them |
+
+What a party writes is an envelope, signed by one of its keys. A version is written as
+its text, a plain string; the key sets and node lists it sets, as envelopes without a
+signature; all of them count by the votes the version had. A proposal's place takes
+only the proposal.
+
+A federated swarm has no user registry, and of `_continuum` takes only these writes:
+
+* at `_continuum/federation`, as the table says;
+* by a member: its own entry, its own acks, a remake's record and proposal, and the
+ abort of a remake that expired; by a remake's coordinator only: its decision;
+* by an epoch's first change (the genesis change, a remake's snapshot): epochs and the
+ swarm's ID.
-What a party writes is an envelope, signed by one of its keys. A version, and the keys a
-version sets, are written unsigned, and count by the votes the version had. A proposal's
-place takes only the proposal. Of continuum's own data, a federated swarm keeps what
-nodes write for the protocol (member entries, remakes and their acks, epochs), written
-by members as in every swarm, but a member's entry by that member only; a member's
-change carries its node's signature, as signatures are required in a strict swarm. It
-has no user registry: `_continuum/users`, bans, logouts, sessions, forgotten nodes,
-`_continuum/access` with the policy's place, and the swarm's topology (`neighbours`,
-`relays`, `topology`, `dissemination`) are closed: a write at, within or above any of
-them is refused, a member's entry by any other node too. The topology stays as the
-genesis change set it, and each node picks its own relays; nothing but the policy is
-read of the rest. A party logs in to its own nodes as its
-operator sets up, and a node takes tokens only from the nodes of its own party (Nodes).
+Everything else is closed, a write at, within or above it refused: 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. The topology stays as the genesis change set it; each node picks
+its own relays, and some of its neighbours by party (Nodes). Nothing but the policy is
+read of the rest. A member's change carries its node's signature, as signatures are
+required in a strict swarm. A party logs in to its own nodes as its operator sets up,
+and a node takes tokens only from the nodes of its own party (Nodes).
### Changing the policy
A **proposal** is a version a party writes at
`_continuum/federation/proposals/<party>/<hash>`, its hash the version's, signed with
-one of the keys the version it changes names for its party. It counts as written by
-those, whatever keys the party writes since, until it lapses.
+one of the keys the version it changes names for its party; it is on the version its
+envelope names, the one current at its history. It counts as written by those keys,
+whatever keys the party writes since, until it lapses.
A party **votes** on a proposal by writing `true` or `false` at
`_continuum/federation/votes/<party>/<version>/<proposal>`: the version the proposal
-changes, and the proposal, by their hashes. No vote there is no vote.
+is on, and the proposal, by their hashes. No vote there is no vote.
* **A vote is taken only where, at its history, its version is current and its
proposal is written.** A vote cast at a history from before can't reach a proposal
made since.
* **A vote never changes**, and **counts as cast**: signed with one of the keys its
version names for its party, whatever keys the party writes since. So a vote is
- checked from itself and its version alone, by a client too, after the document
- dropped it. It goes only with its version, when that is replaced (What counts), and
- nobody deletes it before. A write at a vote's place is refused.
-* **A proposal passes** once at least the share of its version's parties voted `true`.
- It is **dead** once so many voted `false` that the rest are fewer than the share.
+ checked from itself and its version alone, by a client too, after a remake left it
+ out. Nobody deletes it, and a write at a vote's place is refused.
+* **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).
* **One yes at a time.** A party's `true` is taken only if, at its history, every other
proposal on that version it voted `true` for is dead. So a party backs one proposal,
and is free again when that one can't pass any more.
+So a yes binds its party while its proposal can pass. Of nine parties, five back X, two
+prefer Y and two never vote: X needs one more and can't die, as that takes four nays.
+The five back nothing else on this version, and the others take X or fork. A proposal
+that could pass at one history and be taken back at another would let two versions be
+written without anyone voting twice.
+
Once a proposal passed on the current version, any member writes it at
-`_continuum/federation/versions/<hash>`, as it is, unsigned, with the keys it sets
-(Keys); every node judges that change by its history: the proposal written there, the
-votes it had, and the version it changes current. A version takes effect when it is
-written, and judges every change in sight of it.
+`_continuum/federation/versions/<hash>`, with the key sets and node lists it sets
+(Keys, Nodes); every node judges that change by its history: the proposal written there,
+on the version the text changes, its votes there, and that version current. A version
+takes effect when it is written, and judges every change in sight of it.
+
+**A node takes a version only where it changes the version the node reads**, or is that
+one, written again. A change writing any other, valid at its history or not, it refuses,
+with everything built on it, reports, and leaves to its operator; another node's
+refusal doesn't make it drop what it took. Where it holds two that change the one it
+reads, having taken neither, it takes neither until its operator names one. Without
+keys voting twice, every version written changes the one every node reads, and none is
+refused.
-**The current version** is the written version with the highest number; of two with
-one number, the lower hash. A number is checked where its version is written, so the
-highest is the end of the chain, read from what the document holds without the
-versions behind it, which may go (What counts).
+**The current version** is the written version with the highest number: the end of the
+chain the node took, read from what the document holds without the versions behind it,
+which a remake leaves out (Remakes).
* **Votes that split pass nothing**, like a proposal that gets only nays: three for
one proposal and three for another, of six. Nays end it: once a proposal is dead,
its backers are free, and another proposal can pass on the same version. Parties
that won't wait fork.
-* **Two versions with one number** are written only if a party voted twice: `true` and
- `false` on one proposal, each shown to some, or `true` on two; one party is enough
- where a vote is close. Nodes that hold both read the one with the lower hash, so
- they agree once they sync, and where nothing was built on the other, that settles
- it. Where both were built on before the sides met, what nodes read can change again
- while votes cast on the other side before then come in: each is taken where it was
- cast, as every vote is. And what was written under the version not read ranks with
- what was written under the other, both naming one number: a key set a thief writes
- there is ahead of the one the other version set. So the parties answer a double
- vote by forking without the party that voted twice, the fork's version setting
- every party's keys (Forks). What the side not read deleted as housekeeping, and
- counts by the version read, its party's client puts back.
+* **Two versions changing one** are written only where keys voted twice: a party
+ voting `true` and `false` on one proposal, each shown to some, or `true` on two; or
+ the keys an earlier version named, for two thirds of its parties, passing another
+ proposal on it at a history from before the version that followed: some party among
+ them backed that one too (two shares of two thirds share a party). Each node keeps the
+ version it took and refuses the other, so nodes holding the same changes still read
+ the same policy; 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).
* **A party that voted twice shows**: its two votes on one version, both signed with
- keys the version names for it, each taken where it was cast. A node reports it (a log,
- the API), with both votes, from the history: a place holding two votes counts by its
- read like any place, and two `true`s are voting twice only where neither proposal was
- dead at the other's history. A client keeps the votes, as they are signed and anyone
- can check them after the document has dropped them. That proves its keys signed both,
- not that it meant to: two of its nodes voting each by itself, or a stolen key, look
- the same. Taking it out is the parties' choice, and a fork.
+ keys the version names for it. A node reports it (a log, the API), with both votes,
+ as it reports every version it refused. Anyone can commit a vote again at another
+ history, so two `true`s are voting twice only where no copy of either was taken at a
+ history where the other's proposal was dead; two envelopes of one value at one vote's
+ place are one vote. A client keeps the votes, as they are signed and anyone can check
+ them after a remake left them out. That proves its keys signed both, not that it
+ meant to: two of its nodes voting each by itself, or a stolen key, look the same.
+ Taking it out is the parties' choice, and a fork.
* **A proposal on a version that isn't current lapses**, with the votes on that
version.
-Everything the federation decides is a change of the policy: who the parties are, and
-their keys where they lost them; who writes where, which is giving an identifier,
-taking it back and giving it to another; the share; and the federation itself, by
-naming another (Changing the federation).
+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).
### Keys
-A party votes and proposes with the keys its version names for it; everything else it
-writes, its node list among it, with its keys at
-`_continuum/federation/keys/<party>`: one envelope, the set,
-signed with a key of the set it replaces, numbered as any envelope. The change that
-writes a version setting a party's keys writes them there too, and only that change,
-or it is refused: an envelope without a signature (`cv2.<value>.<meta>.`), the keys the
-version sets and no others, its meta naming that version, the party as its user, `at`
-0, `prev` and `seq` as any envelope's, the same from every member at one history. It is
-ahead of every set written under an earlier version, and the party's next set names it
-as the one it replaces.
+A party votes and proposes with the keys its version names for it, and signs with them
+its key set and its node list. Everything else it signs with its keys at
+`_continuum/federation/keys/<party>`: one envelope, the set, signed with a key the
+version current at its history names for the party, numbered as any envelope. A set is
+checked only where it is written, never by the keys of a set (What counts, 2).
-* **A value counts only while the key that signed it is among its party's keys**,
- votes and proposals excepted, which go by their version's, and its node list, which
- counts until its party writes another (Nodes). Changing keys is: add the new keys to
- the set, sign again with one of them what should stay (a change is judged at its
- history, where only the set it replaces is the party's), then drop the old ones (a
- client does that, its deletions too). A key added back, from a backup say, can bring
- back what it signed, and what a `null` of its party covered once that `null` went
- (What counts).
-* **Only a version revokes a key.** A party changing its keys by itself adds keys and
- tidies; but a key it drops can still sign, at a history from before the drop, a set
- of its own numbered past the party's, and nothing in the document tells which of two
- chains from one set is the party's. A key lost, stolen, or retired and not
- destroyed, is answered by a version setting the party's keys, which is ahead of every
- set before it. What the party then signs again names that version, and is ahead of
- anything the old key writes at a history from before it.
-* **A party's own key change reaches its votes and proposals** once a version names
- its new keys; until then its version's keep voting, as only a version revokes a key.
- A party can keep the keys its version names apart, offline, and sign its values with
- a set of its own.
+The change that writes a version setting a party's keys writes them there too, and only
+that change, or it is refused: an envelope without a signature (`cv3.<value>.<meta>.`),
+the keys the version names for the party and no others, its meta naming the swarm, its
+path, that version and the party, `at` 0, `prev` empty and `seq` 0, so that it is the
+same wherever the version is written. It is ahead of every set naming an earlier
+version, and the party's next set replaces it.
+
+* **A value counts only while the key that signed it is among its party's keys**, those
+ of its set: votes, proposals, sets and node lists aside, which go by the keys their
+ version names. A party changes its keys by itself: it writes a set with the new keys,
+ signs again with one of them what should stay (a change is judged at its history,
+ where only the set it replaces is the party's), then writes a set without the old
+ ones (a client does it all). A key it dropped signs no set, and what it signed counts
+ no more; a key added back, from a backup say, brings back what it signed.
+* **Only a version revokes a key it names.** One lost or stolen is answered by a version
+ naming the party's keys anew, whose set is ahead of every set before it. What the
+ party then signs names that version, and is ahead of anything the old key writes at a
+ history from before it. Until then, the old key votes, and writes the party's set and
+ node list, as the party's.
+* **A party's own key change reaches its votes and proposals** once a version names its
+ new keys. A party can keep the keys its version names apart, offline, and sign its
+ values with a set of its own.
### What counts
@@ -296,55 +332,45 @@ A change is judged at its history, by the version current there, as every node j
it ([`access.md`](access.md), Changes judged on every node). So a value its party wrote
while it could write there is taken, even where a version written at the same time
says otherwise. What **counts** is read by the version current in the document as a
-whole. These count no more, and nothing else is stale:
+whole. These count no more, and nothing else does:
1. a value at a place its party may not write by the current version: the party is no
longer one, the place went to another, a rule changed; and of a party that is no
- longer one, its keys and its node list;
-2. a value signed by a key that isn't among its party's, votes and proposals
- excepted, which go by the keys their version names, and its node list;
+ longer one, its key set and its node list;
+2. a value signed by a key that isn't among its party's, votes, proposals, key sets
+ and node lists aside, which go by the keys their version names;
3. a proposal on a version that isn't current, and the votes on that version;
-4. a version behind the current one: of a lower number, or of its number with the
- higher hash;
+4. a version behind the current one;
5. an envelope behind another at its place;
-6. the member entry of a node its own party doesn't list (Nodes), read at the deleting
- change's history;
-7. a party's `null` where the deleting change's history holds everything its place held
- before it or beside it in this epoch, from empty, all signed by keys its party no
- longer holds. A `null` the epoch's first change holds goes only at a remake
- (Remakes), as what it covers isn't in this epoch's history to judge by. Judging it
- reads the place's history: slow, not wrong.
-
-**Any member may delete what counts no more**, place by place, never a map holding
-places, and a member entry whole; every node judges the deletion by the document the
-deleting change makes. That is the federation's own housekeeping; remakes carry whatever
-is there. So that deletions don't flood the document, the one whose write made something
-stale deletes it in the same change; others delete only what they find stale, as in a
-swarm whose parties went quiet.
+6. the member entry of a node its own party doesn't list (Nodes).
-**What is deleted can be put back** where its place is empty, by anyone who holds it,
-at a history where the version it names is current, and counts if its key is among its
-party's and its party may write there: a place taken from a party and given back may
-show what the party had there. Whatever the party writes there under a later version
-is ahead of it. So a party's `null` stays while what it covers could come back and
-count: it goes once that was all signed by keys its party dropped (7, above), or at a
-remake (Remakes). Neither happens by itself; either can, so that a swarm that never
-remakes can be kept from growing with every name ever deleted.
+Nothing is deleted within an epoch but by a party at its own place, writing `null`.
+Automerge keeps every operation, so a deletion shrinks nothing: only a remake shrinks
+the document. What counts no more stays until a remake's snapshot or a fork's genesis
+leaves it out, where it is or names a version before the one current there (Remakes).
+Until then, a place given back to its party, or a key added back, shows what the party
+signed before, until the party writes there again.
### Nodes
A party lists the nodes that carry for it, by node ID, at
-`_continuum/federation/nodes/<party>`. A node's party is its operator's, in its
-configuration, and its own member entry names it. A node is a member while that party
-lists it: it registers, commits changes and syncs, and nodes sync with members only
-(Stages); it takes tokens only from the nodes that party lists. Another party's list
-does nothing. A party's list counts as its party's, whichever of the party's keys
-signed it, until the party writes another, so that no change of keys leaves a swarm,
-or a fork, without members; a list a stolen key wrote stays until its party writes one
-under the version that replaced that key, which it can at once, through any member. A
-node commits whatever envelopes it is given, its party's and others'
-alike: what counts is who signed a value, not which node committed it. So a party
-without nodes of its own writes through any node that takes its envelopes.
+`_continuum/federation/nodes/<party>`: one envelope, signed with a key its version
+names, or set by a version as a version sets keys (Keys). A node's party is its
+operator's, in its configuration, and its own member entry names it. A node is a member
+while that party lists it: it registers, commits changes and syncs, and nodes sync with
+members only (Stages); it takes tokens only from the nodes that party lists. Another
+party's list does nothing. A party's list counts until the party writes another or a
+version sets one, 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 commits whatever envelopes it is given, its party's and others' alike: what
+counts is who signed a value, not which node committed it. So a party without nodes of
+its own writes through any node that takes its envelopes.
+
+A node keeps some of its neighbours among its own party's nodes and those of the
+parties its operator names, so that a party listing many nodes can't be every node's
+neighbours. A federated swarm has no swarm key: a secret its parties share keeps out
+nobody, and the node lists say who syncs.
### Forks
@@ -354,16 +380,18 @@ the group won't follow passed, the parties can't agree, or it leaves the federat
1. One of the group starts the new swarm. Its genesis change holds what the old document
read as at heads it names, built byte for byte from the fork's first version and
- those heads alone, with the old epoch's Automerge version: its writer from the fork's
+ those heads alone, with the swarm's Automerge version: its writer from the fork's
name, time 0, no message, nothing of a remake's metadata but what the heads fix; so
one version and one set of heads make one swarm, and a node that doesn't hold the
- heads' history takes it on its peers' word, as a joiner takes a remake. It holds all
- of it but for the federation's versions, the keys they set, continuum's member
- entries and the swarm's name: of versions, only the group's own, the fork's first. It
+ heads' history takes it on its peers' word, as a node with an empty document takes
+ an epoch. It holds all of it but for what a snapshot leaves out (Remakes), the
+ federation's versions, continuum's member entries and the swarm's name: of versions,
+ only the group's own, the fork's first, with the key sets and node lists it sets. It
names the highest version at those heads as the one it changes, is numbered one past
- it, and sets every party's keys; judged by none, as an epoch's first change is. Every
- proposal is a chance to fork: the version is usually one that didn't pass. To leave
- the federation, the genesis holds another policy instead, and what it needs.
+ it, and sets the node lists of the parties that start it, and the keys of any party
+ it names anew; judged by none, as an epoch's first change is. Every proposal is a
+ chance to fork: the version is usually one that didn't pass. To leave the
+ federation, the genesis holds another policy instead, and what it needs.
2. A fork is named by the hash of its first version together with the heads it names,
which nobody can steer to a given name, the old swarm's least of all: its genesis
change writes it at `_continuum/swarm`, as every node checks, and an envelope's meta
@@ -381,14 +409,12 @@ they left goes on for those who stay. A party the fork's version leaves out writ
nothing there, and what it had counts no more; to come back, the fork's parties let it
in by a version, as they would anyone new. A fork's version may name parties that
weren't among the first to go (every party its founders consider honest, say), so that
-they can follow whenever they like, without asking. A party that goes may say where,
-at `went/<party>`: the fork's genesis change, for those who follow it.
+they can follow whenever they like, without asking.
What a party's nodes do of themselves is their operators' business, written nowhere:
-join a fork where parties their operator follows went (`went/<party>`), vote as those
-voted, vote by
-bounds their operator set, or do nothing without their operator. So a federation that
-cooperates can have a group that leads without being named: the active parties the
+join a fork their operator follows, vote as parties their operator follows voted, vote
+by bounds their operator set, 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
@@ -400,75 +426,81 @@ back and given to another the same way. Nothing is first come, first served. The
value is what its writer signs there (`names/r/wiki/@`: where the name points); what
a former writer signed counts no more once a version gives the place to another.
-Routine work needs no vote: a version gives a party a zone or a block by one rule
+Routine work needs no vote: a version gives a party a zone or a block by a rule
(`ip4/10/243/7/*`), and a new host is a write where its party may write. Votes are
for parties, zones, blocks and names that are nobody's by their spelling.
### Starting a federation
A federation starts with a swarm of its own: its genesis change, the swarm's first,
-writes the federated policy and the first version, with the keys it sets, and the node
-list of its own node's party, naming that node, signed by that party for the swarm the
-change names (its operator holds a key of that party): so the federation starts with
-one member, and the other parties' lists come in through it. It records them as a swarm
-strict from its start records its policy (`--bootstrap-policy`) *(checked:
-`swarm::bootstrap`)*, which starts it empty: content before it would be a change from
-before the federation, judged by none. So nothing is from before the federation, and
-nothing writes the policy's place after the genesis change: the federation changes by
-versions, and is left by a fork. A running swarm doesn't become federated; its parties
-start one, and sign into it, after the genesis change, what they keep.
+writes the federated policy and the first version, with the key sets and node lists it
+sets, among them the list of its own node's party, naming that node: so the federation
+starts with members, and other nodes come in as their parties list them. It records
+them as a swarm strict from its start records its policy (`--bootstrap-policy`)
+*(checked: `swarm::bootstrap`)*, which starts it empty: content before it would be a
+change from before the federation, judged by none. So nothing is from before the
+federation, and nothing writes the policy's place after the genesis change: the
+federation changes by versions, and is left by a fork. A running swarm doesn't become
+federated; its parties start one, and sign into it, after the genesis change, what they
+keep.
### Remakes
A remake starts the document anew, for Automerge's sake only (Where Automerge sets
limits); the federation needs none and asks for none. When to remake, and who acks,
-is continuum's as in every swarm. What a federated node asks of a remake:
+is continuum's as in every swarm. A federated swarm takes compaction only, whose
+snapshot is a function of its base. What a federated node asks of a remake:
-* **It loses nothing and adds nothing.** A node follows a remake only where the new
- document reads as the old one did at the base, at every place and every path of the
- federation, as continuum reads it. A node checks that before it switches, stays
- where it is otherwise, and never rejoins an epoch it refused.
+* **It builds it itself.** A node that holds an epoch leaves it only for one whose
+ snapshot it built itself, as continuum's node builds a compaction's and checks it
+ against the committed epoch *(checked: `remake::switch`)*, from a base it holds, where
+ it is a member and the version it reads is written. Never on its peers' word, however
+ it hears of the new epoch: where it can't build it, it stays where it is, says so, and
+ never rejoins an epoch it refused. A remake's decision is its coordinator's alone, and
+ how long a node keeps the old document is its own setting, not the remake's.
+* **The snapshot** holds what the old document read as at the base, but for what counts
+ no more by the version current there and is or names a version before it, and a
+ party's `null` naming a version before it: nothing naming an earlier version can be
+ written in the new epoch, and an empty place reads as one holding `null` does.
* **Writes after the base** are replayed as the policy shapes them: at each place, the
chain of envelopes that leads from what the new document holds there to what the old
one reads, each in a change of its own, judged again in the new epoch, the other
writes with them, each after those its change builds on, clocks only between changes
neither of which saw the other, as continuum replays under a strict policy *(checked:
`remake::delta`)*. Versions written after the base go with them, each in one change
- with the keys it sets, whatever names a version before the next, each judged by the
- votes replayed before it. Votes and proposals go by the keys their version names,
- which is replayed before them, so they count as cast in the new epoch too, whatever
- key sets of their party are replayed around them. Whether a place is held already goes
- by version number, then `seq`. What the new epoch refuses (its key was dropped by a
- version, its place given to another) goes to the quarantine of the node that holds it,
- and its party signs it again if it still may.
-* **Housekeeping after the base** isn't replayed: what it deleted is stale again, and is
- deleted again, but for a `null` that went by rule 7 (What counts), which the snapshot
- holds, so that it goes only at the next remake. And where a chain starts on an empty
- place (`prev` empty) and what the new document holds there counts no more by what was
- replayed so far, the replaying node deletes that in the first link's own change,
- judged by the document that change makes, as housekeeping is; the link is checked
- against the place as the deletion leaves it.
-* **A party's `null`** is left out of the snapshot once a version later than the one
- it names is current: nothing naming an earlier one can be written in the new epoch,
- and an empty place reads as one holding `null` does. One the snapshot keeps goes
- only at a later remake (What counts).
+ with the key sets and node lists it sets, each judged by the votes replayed before
+ it. Votes and proposals go by the keys their version names, which is replayed before
+ them, so they count as cast in the new epoch too, whatever key sets of their party are
+ replayed around them. Whether a place is held already goes by version number, then
+ `seq`. What the new epoch refuses (its key was dropped, its place given to another)
+ goes to the quarantine of the node that holds it, and its party signs it again if it
+ still may.
-A remake's base is its coordinator's word, so all this holds for any base, not only a
-recent one. So a remake decides nothing that counts, but what it can't hold: of two
-envelopes of one version and `seq` at a place at the base, the snapshot keeps one, and a
-write after the base on the other, an envelope put back after it on one the snapshot
-lacks, or a write after it on a `null` the snapshot left out, goes to the quarantine,
-and its party writes again. A swarm that never remakes stays as correct as one that
-remakes all the time; it only grows slower. A remake does end one thing: nothing is
-written at a history from before it, so what a dropped key or a node taken off its list
-could still write there ends with it.
+So a remake decides nothing that counts, but what it can't hold: of two envelopes of one
+version and `seq` at a place at the base, the snapshot keeps one, and a write after the
+base on the other, a write after it on what the snapshot left out, or an envelope
+written after it at a history where a version before the base's was current (its node
+lagged), goes to the quarantine, and its party writes again. A swarm that never remakes
+stays as correct as one that remakes all the time; it only grows. A remake does end one
+thing: nothing is written at a history from before its base, so what a node taken off
+its list could still commit there ends with it.
-A node that doesn't hold the epoch before (it joins, or was away) can't check: it
-takes the epoch its peers give it.
+A remake that races a version or a listing leaves the nodes that took it where they
+are, apart from those that switched, until their operators move them or a fork. A node
+with an empty document can't check: it takes the epoch its peers give it, or the one
+its operator pins.
### Where Automerge sets limits
-Recommendations, not rules: none of these breaks a promise, only how fast a node is.
+* **Bytes.** The nodes of a federated swarm run one Automerge version, which its
+ federation's number names (Changing the federation): a rule, as two versions that
+ encode a change differently refuse each other's changes.
+* **Changes it shouldn't apply.** A change is first of all one Automerge itself
+ writes, or it is refused before Automerge sees it, in every swarm *(checked:
+ `document::changes::Written`)*.
+
+The rest are recommendations: none breaks a promise, only how fast a node is, or how
+long nodes stay together.
* **Writers.** Every writer costs every node memory while the epoch lasts, in
proportion to the document's history *(measured: about 4 bytes per change)*. A node
@@ -478,14 +510,9 @@ Recommendations, not rules: none of these breaks a promise, only how fast a node
* **One change a number.** A node that commits two changes under one writer and number
splits the nodes that took one from those that took the other: a node holding one
can't take the other. Continuum refuses the second as forged, by whoever brings it
- *(checked: `Signatures::forks`)*. A remake brings the two sides together again, and
- so does a fork.
-* **Changes it shouldn't apply.** A change is first of all one Automerge itself
- writes, or it is refused before Automerge sees it, in every swarm *(checked:
- `document::changes::Written`)*.
-* **History.** The document keeps all of it, which remakes bound.
-* **Bytes.** The nodes of an epoch run one Automerge version; a swarm moves to another
- at a remake.
+ *(checked: `Signatures::forks`)*. No remake brings the two sides together, as neither
+ builds from a base holding what it refused; a fork at heads both hold does.
+* **History.** The document keeps every operation, which only remakes bound.
## Why it holds
@@ -495,25 +522,30 @@ Recommendations, not rules: none of these breaks a promise, only how fast a node
everything built on it. What counts is read from what the document holds: the
current version, the highest number; each party's keys, by that version and its
set; each place's value, by version number, then `seq`. None of it depends
- on the order of operations. A copy of an older envelope is behind; a new one written
- at a history from before a version is behind what is written under it.
-2. **The policy.** A version is written only where, at one history, the share of the
- parties of the version it changes voted `true` for it. An honest party backs one
- proposal on a version at a time, and another only once the first is dead; its votes
- count as cast. So a proposal can't pass at one history and be dead at another
- unless some party's `true` and `false` for it are both there. Without a party voting
- twice, at most one version changes a version. With one, nodes still read the same
- version once they hold the same changes, and the parties fork.
-3. **Remakes.** A node follows a remake only where its snapshot reads as the old
- document did at the base, which it checks. What came after is replayed in history's
- order, each change judged as every node judges it: versions by the votes replayed
- before them; votes and proposals by the keys their version names, which comes
- before them; envelopes as chains, from what the snapshot holds, by version, then
- `seq`. So what counted, counts, but what a remake can't hold (Remakes), each of which
- its party writes again.
+ on the order of operations, and no key is both a value and the way to places. A copy
+ of an older envelope is behind; a new one written at a history from before a version
+ is behind what is written under it.
+2. **The policy.** A version is written only where, at one history, two thirds of the
+ parties of the version it changes voted `true` for it, and a node takes it only
+ where it changes the version the node reads. An honest party backs one proposal on a
+ version at a time, and another only once the first is dead; its votes count as cast.
+ So a proposal can't pass at one history and be dead at another unless some party's
+ `true` and `false` for it are both there, and two proposals on one version pass only
+ where some party backed both while neither was dead. Without keys voting twice, at
+ most one version changes a version, and every node takes it; keys an earlier version
+ named move no node that took the version after it. With them, each node keeps the
+ version it took, nodes holding the same changes still read the same policy, and the
+ parties fork.
+3. **Remakes.** A node follows a remake only where it built the snapshot itself, from a
+ base it holds, a member there, the version it reads written there; its peers' word
+ never moves it. What came after is replayed in history's order, each change judged as
+ every node judges it: versions by the votes replayed before them; votes and proposals
+ by the keys their version names, which comes before them; envelopes as chains, from
+ what the snapshot holds, by version, then `seq`. So what counted, counts, but what a
+ remake can't hold (Remakes), each of which its party writes again.
4. **Carrying on.** A fork is a swarm of its own, named by its first version and the
- heads it names, joined by its operators' choice only. A party nobody follows carries
- on alone.
+ heads it names, its members those its lists name, joined by its operators'
+ choice only. A party nobody follows carries on alone.
## Attacks
@@ -527,61 +559,61 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang
| 3 | An older envelope written where a newer one is | Refused: `prev`, `seq` | unit |
| 4 | An older envelope put beside the newer by a change that saw neither | Taken, and behind | unit |
| 5 | A former holder writes a chain at a history where it held the place | Behind what is written under the version that gave the place away | unit |
-| 6 | A dropped key writes a key-set chain at a history before the drop | Ahead of the party's own set, until a version sets the party's keys; then behind | unit |
-| 7 | A version written without the votes, or not changing the current one at its history | Refused at its history | unit |
-| 8 | A version that doesn't read, has a key twice, a share of a half, a rule under `_continuum` or without a literal first segment | No version: can't pass, refused when written | unit |
-| 9 | `true` on two proposals of one version | The second refused, unless the first is dead at its history | unit |
-| 10 | `true` on two proposals at once, from two nodes | Both taken; two versions of one number may be written; the lower hash is read; reported; the parties fork | unit, every order |
-| 11 | `true` and `false` on one proposal at once | Both held; a node that saw only one may write a version. As 10 | unit, every order |
-| 12 | A vote changed, or deleted while its version is current | Refused | unit |
-| 13 | A vote cast at a history from before, on a proposal made since | Refused: its proposal isn't written there | unit |
-| 14 | A party changes keys after voting or proposing, or beside its vote or proposal | It counts as cast, by its version's keys, at a remake too | unit |
-| 15 | Votes split, honestly or not | Nothing passes; nays make the proposals dead, and another passes | unit |
-| 16 | The parties beyond the share never vote, or vote `false` on everything | Nothing passes; the others fork | sim |
-| 17 | The party a version takes out writes that version itself | Written: a version counts by its votes, not its writer | unit |
-| 18 | A version written late beside one the parties went on from | A lower number: changes nothing | unit |
-| 19 | A proposer grinds its version's hash | Wins a tie of two versions of one number; only with a double vote, which a fork answers | unit |
-| 20 | Values signed with a stolen key | Count until a version drops the key, then none of them; under a version sharing its number with another, until a fork | unit |
-| 21 | A deleted value put back where its place is empty | Counts if its key and its place are still its party's; behind whatever the party writes there later | unit |
-| 22 | A write in another party's namespace, or at an identifier of another's | Refused by the rule | unit |
-| 23 | Housekeeping of something that counts | Refused, by the document the change makes | unit |
-| 24 | Housekeeping by a change that saw a time when it didn't count | Taken; the party writes again | unit |
-| 25 | A map holding places deleted, or a place written within | Refused | unit |
-| 26 | A remake whose document reads otherwise than the base | Nodes holding the base stay, and never rejoin it | sim |
-| 27 | Two envelopes at one place beyond a remake's base | The chain to the one read is replayed | unit |
-| 28 | A version written after a remake's base, an envelope written beside it | Replayed, the envelope first, as it names the version before | unit |
-| 29 | A joining node handed a made-up epoch | Taken. Not promised | sim |
-| 30 | The party with most nodes remakes often, or never acks | Slow, not wrong; the others fork | sim |
-| 31 | A writer forked: two changes, one number | Honest nodes split until a remake, or a fork. Not promised | sim |
-| 32 | Different changes to different peers | Honest nodes agree once they sync | sim |
-| 33 | A party withholding its changes or votes | Not promised | — |
-| 34 | Flooding: namespace, proposals, history, writers | Slow, not wrong | bench |
-| 35 | A node taken off its list writes changes at a history where it was on | Taken where valid there; behind what is written under later versions | unit |
-| 36 | A token from another party's node | Refused: a node's party is its configuration's | unit |
-| 37 | Envelopes the stayers sign after a fork, brought to the fork | Refused: signed for the other swarm | unit |
-| 38 | A fork whose genesis change differs from the document it names | Nodes holding that document don't join, and say what differs | sim |
-| 39 | A fork at heads of its founder's choosing | Joiners holding the document are told what those heads lack | sim |
-| 40 | A federation, or a policy, a node doesn't know | It stops taking changes | unit |
-| 41 | A party lists another party's nodes, or one its party dropped | Nothing changes: a node is its own party's | unit |
-| 42 | The versions behind the current one deleted | The current one is still the highest number | unit |
-| 43 | A vote cast on the side not read, before the sides met, sent after | That side may gain a version, and be read. Not promised: the parties fork | unit |
-| 44 | A key set written under the version not read, of two with one number | Ahead of the set the other wrote, until a fork | unit |
-| 45 | A place given to another and emptied after a base, its new holder writing after that | Replay deletes what counts no more there, then writes the new holder's chain | unit |
-| 46 | Two envelopes of one version and `seq` at a base, a write after it on the one not kept | Quarantined; its party writes again | unit |
-| 47 | A `null` deleted while what it covers could still count, or one the epoch's first change holds | Refused, by the deleting change's history | unit |
-| 48 | A fork's version giving a party that didn't go keys of its founder's | Joiners holding the document are told, party by party | sim |
-| 49 | Two parties each writing a key set beside the other's vote, crossed | Nothing: votes go by their version's keys, at a remake too | unit |
-| 50 | Content written before a federation's genesis change, and a change built on it | None: the genesis change is the swarm's first | unit |
-| 51 | A party's node writing another node's member entry | Refused: an entry is its member's | unit |
-| 52 | A `null` and an envelope of its party at once, the `null` read | Rule 7 waits for both: the `null` stays while the envelope could count | unit |
+| 6 | A key set signed by a key the version doesn't name, or by one a later version replaced, at a history from before | Refused; or behind the set the later version set | unit |
+| 7 | A key set without the key that signed it | Counts: a set is checked where it is written | unit |
+| 8 | A version written without the votes, or not changing the current one at its history | Refused at its history | unit |
+| 9 | A version not in its JCS bytes, a field missing or more, a rule under `_continuum`, without a literal first segment, with `@`, `**` not last, `{party}` twice, or a writer that is no party of it | No version: can't pass, refused where written as one | unit |
+| 10 | A proposal naming a federation, or saying what, a node doesn't know | Taken as a proposal; asked where it is written as a version | unit |
+| 11 | `true` on two proposals of one version | The second refused, unless the first is dead at its history | unit |
+| 12 | `true` on two proposals at once, from two nodes | Both taken; two versions changing one may be written; each node keeps the one it took and refuses the other; reported; the parties fork | unit, every order |
+| 13 | `true` and `false` on one proposal at once | Both held; a node that saw only one may write a version. As 12 | unit, every order |
+| 14 | A vote changed or deleted | Refused | unit |
+| 15 | A vote cast at a history from before, on a proposal made since | Refused: its proposal isn't written there | unit |
+| 16 | A party's vote committed again at another history | One vote; voting twice only where no copy of either was taken where the other's proposal was dead | unit |
+| 17 | A party changes keys after voting or proposing, or beside its vote or proposal | It counts as cast, by its version's keys, at a remake too | unit |
+| 18 | Votes split, honestly or not | Nothing passes; nays make the proposals dead, and another passes | unit |
+| 19 | The parties beyond two thirds never vote, or vote `false` on everything | Nothing passes; the others fork | sim |
+| 20 | The party a version takes out writes that version itself | Written: a version counts by its votes, not its writer | unit |
+| 21 | The keys an earlier version named, for two thirds of its parties, pass another proposal on it at a history from before, and raise its number | Refused by every node that took the version after it, and reported; a node that lagged may take it: keys voted twice | unit |
+| 22 | Two versions changing the one a node reads, coming together | It takes neither until its operator names one | unit |
+| 23 | Values signed with a key a party's set holds, stolen | Count until the party drops the key | unit |
+| 24 | A key a version names, stolen, votes, or writes its party's set or list | Counts while that version is current; the party's own vote beside it is voting twice, answered by a fork | unit |
+| 25 | A write in another party's namespace, or at an identifier of another's | Refused by the rule | unit |
+| 26 | A deletion of a value of another party, or of what counts no more | Refused: only a party's `null`, at its own place | unit |
+| 27 | An envelope outside an `@` key, a map in one, or a map on the way to one deleted or replaced | Refused | unit |
+| 28 | An envelope and a map at one key, written at once | None: envelopes go only in `@` keys, which hold no maps | unit |
+| 29 | A remake whose snapshot isn't the one a node builds, whose base it lacks, or where it isn't a member | It stays, and never rejoins it | sim |
+| 30 | A coordinator records an old base, before the version nodes read | They stay | sim |
+| 31 | Two members advertise an epoch ahead, or offer a rejoin | Not taken: a node leaves its epoch only for one it built | sim |
+| 32 | A remake's decision written by a node not its coordinator | Refused | unit |
+| 33 | Two envelopes at one place beyond a remake's base | The chain to the one read is replayed | unit |
+| 34 | A version written after a remake's base, an envelope written beside it | Replayed, the envelope first, as it names the version before | unit |
+| 35 | Two envelopes of one version and `seq` at a base, a write after it on the one not kept | Quarantined; its party writes again | unit |
+| 36 | A write after a base on what the snapshot left out, or naming a version before the base's | Quarantined; its party writes again | unit |
+| 37 | A node with an empty document handed a made-up epoch | Taken. Not promised | sim |
+| 38 | A coordinator remakes often, or a party never acks | Slow, not wrong; the others fork | sim |
+| 39 | A writer forked: two changes, one number | Honest nodes split until a fork. Not promised | sim |
+| 40 | Different changes to different peers | Honest nodes agree once they sync | sim |
+| 41 | A party withholding its changes or votes | Not promised | — |
+| 42 | Flooding: namespace, proposals, history, writers | Slow, not wrong | bench |
+| 43 | A node taken off its list writes changes at a history where it was on | Taken where valid there; behind what is written under later versions | unit |
+| 44 | A token from another party's node | Refused: a node's party is its configuration's | unit |
+| 45 | A party lists another party's nodes, or one its party dropped | Nothing changes: a node is its own party's | unit |
+| 46 | A party lists many nodes, to be every node's neighbours | Each node keeps some among its own party's and those its operator names | sim |
+| 47 | A party's node writing another node's member entry | Refused: an entry is its member's | unit |
+| 48 | A party's node writing under `_continuum` where the list doesn't say | Refused: closed | unit |
+| 49 | Envelopes the stayers sign after a fork, brought to the fork | Refused: signed for the other swarm | unit |
+| 50 | A fork whose genesis change differs from the document it names | Nodes holding that document don't join, and say what differs | sim |
+| 51 | A fork at heads of its founder's choosing | Joiners holding the document are told what those heads lack | sim |
+| 52 | A fork's version giving a party that didn't go keys of its founder's | Joiners holding the document are told, party by party | sim |
| 53 | Two founders forking one version at one set of heads | One swarm: the genesis change is built byte for byte | sim |
-| 54 | A party's node writing logouts, sessions, forgotten nodes, the topology, or at, within or above `_continuum/access` | Refused: closed | unit |
-| 55 | A federation's genesis change without its node's party's list | Nothing after it is taken: no node is a member. The genesis holds that list | unit |
-| 56 | A version replacing every listed party's keys, or a fork naming keys the lists weren't signed with | The lists still count, each its party's until it writes another | unit |
-| 57 | A key a version names, stolen, votes as its party | Counts until a version replaces it; the party's own vote beside it is a double vote, answered by a fork | unit |
-| 58 | A coordinator records an old base | Everything after it is replayed, each as every node judges it | sim |
-| 59 | A write after a base on a `null` the snapshot left out | Quarantined; its party writes again | unit |
-| 60 | A version written without the keys it sets, or keys written by another change | Refused | unit |
+| 54 | A group whose parties list no nodes forks | Its version sets their node lists | sim |
+| 55 | A federation, or a policy, a node doesn't know | It stops taking changes | unit |
+| 56 | Two parties each writing a key set beside the other's vote, crossed | Nothing: votes go by their version's keys, at a remake too | unit |
+| 57 | Content written before a federation's genesis change, and a change built on it | None: the genesis change is the swarm's first | unit |
+| 58 | A federation's genesis change whose first version lists no node | Nothing after it is taken: no node is a member | unit |
+| 59 | A version replacing every listed party's keys | The lists still count, each its party's until it writes another | unit |
+| 60 | A version written without the key sets or node lists it sets, or those written by another change, or numbered otherwise | Refused | unit |
## Roads not taken
@@ -601,9 +633,14 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang
time, at a history from before, and would undo a version long after it passed; and
honest parties who backed one proposal, then another once the first was dead, would
look as if they had voted twice.
-* **The longest chain from the first version.** It reads the same as the highest
- number, but needs every version kept, and a tie decided where two chains part, long
- behind both.
+* **Every node moving to one of two versions changing one**, the lower hash, say.
+ Whoever holds the keys an earlier version named, for two thirds of its parties, could
+ put another policy on every node at any time, raising its number alone, and grind
+ its hash. A node keeps the version it took, and the parties fork.
+* **The longest chain from the first version.** It needs every version kept, and 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).
* **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 preferred,
@@ -613,9 +650,20 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang
* **Votes counted by the keys their party had at their history.** A remake replays a
vote and its party's key set in an order of its own, and where two parties' key sets
and votes cross, no order keeps every vote. The keys a version names don't move.
-* **Freezing the policy once two versions share a number.** One party could stop the
- federation at every close vote; the lower hash keeps nodes agreeing until the parties
- fork.
+* **Housekeeping within an epoch**: members deleting what counts no more. Automerge
+ keeps every operation, so it shrinks nothing; and a place it empties reads whatever
+ its party once signed there and anyone puts back. A remake's snapshot and a fork's
+ genesis leave it out.
+* **Remakes of other kinds** (`replace`, `import`, `strict`), followed where the new
+ document reads as the old one did. A snapshot judged by none could swap an envelope
+ for one naming a later version, and a node would take it on its peers' word wherever
+ it can't read the old one. A compaction's snapshot every node builds itself.
+* **Rules of a fixed depth**, without `**`, so that the rules alone say whether a key is
+ a place or the way to places. A party's namespace would be flat; values in `@` keys do
+ the same with `**`.
+* **A place where a party says which fork it went to.** A node following it by itself
+ would follow a stolen key into a swarm with any policy; parties say where they went as
+ they like.
* **Forks within one document**, each side judging by its own chain of versions. It
needs judging per chain, judging again when a node changes sides, node lists and
remakes per chain. A swarm of its own needs none of it.
@@ -628,12 +676,13 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang
## Changing the federation
Every node of a swarm runs the same version of continuum today. A federated swarm's
-parties can't be made to upgrade together, so what all its nodes must agree on is named
-by the federation's number: the rules of this design, the envelope and how the value of
-a place is read, what makes a change one Automerge writes, how a path and a version are
-spelled and read, which version is current, the remake's check, its replay and its
-order. The hash of a change and its encoding are Automerge's
-version's.
+parties can't be made to upgrade together, so from the first federated swarm on,
+continuum's releases work together in one, and what all its nodes must agree on is
+named by the federation's number: the rules of this design, the envelope and how the
+value of a place is read, what makes a change one Automerge writes, how a path and a
+version are spelled and read, which version a node takes and which is current, the
+remake's snapshot, its replay and its order, and the Automerge version, whose encoding
+fixes a change's hash.
A change to the federation is a design like this one, with the next number. A swarm
moves to it by a version of its policy that names it (`"federation": 2`), which the
@@ -645,38 +694,43 @@ the federation, or the policy, its swarm has stops taking changes and says so.
The krebs registry today: users, their hosts, the hosts' names, addresses and keys.
On a federated swarm:
-* each krebs user is a party, its hosts in its namespace (`home/tv/hosts/laptop`: its
- keys, its addresses as it uses them). Every decision takes two thirds of all
- parties, quiet ones counted: the first version names the parties that will vote,
- and lets the others in as they turn up;
-* its names under `names/r/tv/` and `names/w/tv/` by one rule each, its address blocks
- by a rule each; other names given by versions;
+* the krebs users who will vote are its parties, each its hosts in its namespace
+ (`home/tv/hosts/laptop`: its keys, its addresses as it uses them). The others are in
+ a party that is a group, which holds its keys as it likes, their hosts in its
+ namespace, until a version makes one a party of its own. Every decision takes two
+ thirds of all parties, quiet ones counted, so the first version names only those
+ that will vote;
+* a party's names `names/r/tv` and those under it by a rule each, and so for
+ `names/w`; its address blocks by a rule each; other names given by versions;
* kartei's entries signed in by their parties after the genesis change, never as
content before it;
* a tool reads what counts and writes what kartei's consumers read today.
## Stages
-1. **The federated policy**: a swarm started federated by its genesis change, with its
- node's party's list; versions
- and what makes one valid, rules and paths, keys, votes, passing and dead, the current
- version, judging by it; votes and proposals by their version's keys; the protocol
- data closed but for member entries, each its member's, remakes, acks and epochs; the
- meta's version number and the order by it; node lists, a node's party in its
- configuration, and tokens from one's own party's nodes only; continuum's readings of
- a policy and of an envelope taking the federated policy and the meta's version beside
- the six fields it has today. A node that doesn't know the policy stops taking
- changes. Until stage 4, a federated swarm takes no remake.
+1. **The federated policy**: a swarm started federated by its genesis change, with the
+ key sets and node lists its first version sets; versions and what makes one valid,
+ rules and paths, values in `@` keys, keys, votes, passing and dead, which version a
+ node takes and the current one, judging by it; votes and proposals by their
+ version's keys; the protocol data as listed, all else closed; the `cv3.` envelope
+ with the meta's version, and the order by it; node lists, a node's party in its
+ configuration, and tokens from one's own party's nodes only; what every reading of a
+ strict policy in continuum (`strict()`) makes of the federated one; the byte formats
+ (a version's JCS bytes, hashes in paths and how two compare, the envelopes a version
+ sets, the meta's version). A node that doesn't know the policy stops taking changes.
+ Until stage 4, a federated swarm takes no remake.
2. **What counts**, read by the current version and the keys; shown in the API.
- Housekeeping. Reports of a party that voted twice.
+ Reports of a party that voted twice, and of versions a node refused.
3. **Nodes**: membership by the node lists and the party a node's own entry names, a
- node syncing with members only, as a swarm key does today (a wire change).
-4. **Remakes**: the check that a remake lost and added nothing; replay of versions with
- the envelopes.
+ node syncing with members only (a wire change), neighbours by party.
+4. **Remakes**: compaction only, each node building it from a base it holds, never on
+ its peers' word; replay of versions with the envelopes.
5. **Forks**: a swarm started from another's document, named by its first version and
the heads it names, and the check against it.
6. **The registry**: the rules for krebs, the tool that signs kartei's entries in as
their parties', after the genesis change, and the one that reads them out.
Each stage's tests are its rows of Attacks. Each stage keeps every swarm that isn't
-federated as it is, its tests passing untouched.
+federated as it is, its tests passing untouched. A federated swarm made before the last
+stage is for tests: a later stage judges it otherwise. Until stage 5, a writer forked
+splits the nodes for good.