From d49b7256866d48d32f33ff52d1e6d0c9f06f92f7 Mon Sep 17 00:00:00 2001 From: tv Date: Fri, 13 Nov 2026 02:03:35 +0000 Subject: federation: a root is a user, an epoch's first change its root change "Root" meant both a user and an epoch's first change. The first is now always the root change. The budget's test goes with the budget (stage 8), and a crafted change's tests, which exist, with stage 1. --- docs/federation.md | 77 +++++++++++++++++++++++++++--------------------------- 1 file changed, 39 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/federation.md b/docs/federation.md index e4ab26d..41eabfe 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -12,8 +12,8 @@ section lists them. How sure each part of the design is, is said with the promis ## Optional -A swarm is federated if its root carries the federated policy (below). Everything here -holds under that policy, and nothing else changes: +A swarm is federated if its genesis change carries the federated policy (below). +Everything here holds under that policy, and nothing else changes: * A swarm started as today has no such policy and stays as it is: its rules, its users with their capabilities, its remakes by the members' votes, its tokens, and @@ -185,18 +185,19 @@ go by being unvouched; each has its namespace; names of declared kinds are held user each; what a key signed can be cut off after the fact; and the swarm decides by its voters' votes. -### The policy, in the root +### The policy, in the genesis change A federated swarm's policy is `{"version": 2, "values": "signed", "users": "vouched"}`, with what the rules read beside it in `_continuum/access`: the kinds of names (`claims`), the paths in namespaces whose values are signed (`userSigned`, as today), -and the **numbers**. All of it is in the swarm's root, its genesis change, with the -roots, the voters, and the users it starts with: +and the **numbers**. All of it is in the swarm's genesis change, with the roots, the +voters, and the users it starts with. ("Root" here is always a user: an epoch's first +change, the genesis change or a remake's snapshot, is its **root change**.) * Nothing is ever written before the policy, so nothing is judged by none. -* Every node is given a root and takes no other: the genesis root (`--genesis-root`), - or, in a swarm that was remade, the ID of a later epoch. The root is what a party - trusts, not what its seeds say. +* Every node is given a root change and takes no other: the genesis change + (`--genesis-root`), or, in a swarm that was remade, the ID of a later epoch. That + is what a party trusts, not what its seeds say. * A node that doesn't know the policy doesn't sync at all. (Today it receives without judging *(docs)*, which here would let anything in.) @@ -360,8 +361,8 @@ it does give: a creator's limit bounds how many users come in through it, and ea shows below it, for all to see, and goes with it when it goes. Bringing someone in means handing over, out of the document, what a party needs to -connect and to start (the root, some seeds, the swarm key where there is one), and -writing the `create`. +connect and to start (the root change, some seeds, the swarm key where there is one), +and writing the `create`. **The roots** are the users the epoch's root change names as such: in a genesis change the user who starts the swarm, or those the file it starts from names; then @@ -1033,8 +1034,8 @@ which every node works out itself. off a stolen key and to sort out what is contested. After, what a thief did stands until it is undone by hand. * **A node that was away** comes back as said below (Coming back after remakes). -* **A node that joins** is given a root to start from, by whoever brings its user in: - the genesis root, or the ID of a later epoch. +* **A node that joins** is given a root change to start from, by whoever brings its + user in: the genesis change, or the ID of a later epoch. * **No other kinds.** `replace` and `import` put content nobody signed: they start a new swarm. @@ -1059,7 +1060,7 @@ in one of two ways: epoch it is in, judging every change; sees the remake decided; builds the snapshot itself; and is in the next epoch, whose ID is the snapshot's hash. So on, epoch by epoch, as far as peers keep them: with an archive within reach, - from any epoch to the swarm's, and for a node that joins, from the genesis root. + from any epoch to the swarm's, and for a node that joins, from the genesis change. Where the walk ends in another epoch than the node's peers are in, the node stops and shows it, for its operator to say which: an archive can keep changes back, and a decision of long ago can be made up with keys stolen since. Keeping @@ -1222,8 +1223,8 @@ rules are. A change is valid if, in the document at its dependencies: -1. It has no dependencies and is the root the node was given (the genesis change, or - the epoch's snapshot). Else: +1. It has no dependencies and is the root change the node was given (the genesis + change, or the epoch's snapshot). Else: 2. Its committer is a node that carries for a user there, one that isn't out and hasn't stopped there, proven by the node's signature. Or the change is the one by which a node comes to carry: it holds a `node` statement naming its committer, by a @@ -1481,9 +1482,9 @@ clock, and the order things reached it in, enter only into what its own node wri (its stamps, taking a proposal up, the base it takes), never into what it reads from the document. What must hold for this, and doesn't everywhere today: -* the root given, never learned; -* no window without a policy (it is in the root), and no syncing under a policy the - node doesn't know; +* the root change given, never learned; +* no window without a policy (it is in the genesis change), and no syncing under a + policy the node doesn't know; * a batch judged at heads that differ from a change's dependencies only where nothing the rules read changed in between: what screening takes as read by rules *(checked: `screen::relevant` lists members, users, remakes, votes, access and node bans)* must @@ -1774,7 +1775,7 @@ back, so the point only moves forward as more of them show up. | Forge votes, commit a remake alone | Votes are users', signed; a decision takes two thirds of the voters, and every node judges the records; every node builds the snapshot itself | | Make the swarm forget peers | A forget record of another's node is refused; whom a node talks to is its own | | Advertise an epoch a rejoining node follows | A node follows a remake it sees decided, or an epoch its operator gave it | -| Be a joining node's first sync | Judged from the root on, by the policy in it | +| Be a joining node's first sync | Judged from the root change on, by the policy in it | | Say it is ready, be a catch-up source | Still believed: it can hold changes back, not add any. A joiner syncs with the others after | | Sign a token every node takes | Taken by the nodes whose operators named it | | Let any user of the registry log in | The users it carries for, and those its operator names | @@ -1796,7 +1797,7 @@ decision, resolving and its API, the drop an operator asks for. All of it is general: a swarm with other kinds, or none, uses the same. In the application, for the registry: which kinds there are and their rules (data in -the root), what a host's entry holds, the client that signs (an extension of +the genesis change), what a host's entry holds, the client that signs (an extension of `scripts/continuum-signed`), moving the repository in, and writing out the files the consumers read. Whether a host's entry may use a name is the application's check against the resolved registry, when it writes the files out. So are a node kept as @@ -1807,21 +1808,20 @@ continuum, with a policy of its own, where it hasn't; either way a decision. What changes in continuum besides the rules, under the federated policy only: policy version 2; the envelope's payload names the user ID, the epoch, and for a statement -what its signer saw; a node is given its root, syncs under no policy it doesn't know, -takes tokens and logins by key as its operator says, writes no sessions into the +what its signer saw; a node is given its root change, syncs under no policy it doesn't +know, takes tokens and logins by key as its operator says, writes no sessions into the document, keeps its writer over a clean stop, stamps as often as the policy says, keeps its seeds and its user's other nodes as neighbours, keeps the document of an epoch it left on disk and answers for it, keeps a quarantine on disk that holds envelopes, commits its carry record after a remake and writes again what the epoch -lacks, takes no remake -but one its voters decided, rejoins no epoch because peers advertise it, and refuses -what its bounds say. For every swarm: the wire's version, with a handshake that says -which epochs its node keeps, and a node that speaks the wire version before its own -too. [`trust.md`](trust.md), [`access.md`](access.md), [`remakes.md`](remakes.md) and -the glossary get the federated case: party, statement, in sight of, line, root, the -seats', voter, claim, cut, late, giving way, contested, settled, final, out, gone, -uncovered, seen for, taking a proposal up, a decision that holds, what hangs, carried -over, refusing a decision, bounds, the numbers. +lacks, takes no remake but one its voters decided, rejoins no epoch because peers +advertise it, and refuses what its bounds say. For every swarm: the wire's version, +with a handshake that says which epochs its node keeps, and a node that speaks the +wire version before its own too. [`trust.md`](trust.md), [`access.md`](access.md), +[`remakes.md`](remakes.md) and the glossary get the federated case: party, statement, +in sight of, line, root, the seats', voter, claim, cut, late, giving way, contested, +settled, final, out, gone, uncovered, seen for, taking a proposal up, a decision that +holds, what hangs, carried over, refusing a decision, bounds, the numbers. ## Continuum changing under a swarm @@ -1909,7 +1909,7 @@ Statements and users: | 10 | Creates a name another has, saying it saw nothing of it | Hold both; late once a root saw the first. Before: contested, or the first is late where a root's node got the other first | 4, 5 | unit: `a_backdated_creation_is_late` | | 11 | Gets a user's name contested to free its names | Its claims stand without the name | 5 | unit: `claims_stand_without_the_name` | | 12 | Creates many users, each claiming many names (sybils); creates them out of each other's sight to pass the limit | Refuse past the limits in sight; out of sight, those past them don't count. A limit bounds how many each user brings in itself, not how many come in below it: each shows below its creator, for all to see, and goes with it when it is unvouched | 6 | unit: `limits_on_creating`, `past_a_limit_out_of_sight` | -| 13 | Adds keys, nodes or statements without end; signs and gives up without end (vouch and unvouch, claim and release, key and retire) | Refuse past the limits. What is given up counts toward none: it is taken no faster than a budget per party, and a remake leaves it out | 6 | unit: `limits_on_a_register`; sim: `a_party_past_its_budget_waits` | +| 13 | Adds keys, nodes or statements without end; signs and gives up without end (vouch and unvouch, claim and release, key and retire) | Refuse past the limits. What is given up counts toward none: it is taken no faster than a budget per party (row of the budget, stage 8), and a remake leaves it out | 6 | unit: `limits_on_a_register` | | 14 | Signs more than its limit out of each other's sight; another claims a name that so doesn't count; then gives the earlier ones up | What comes to count later than it was signed gives way to what was claimed in sight of it meanwhile | 5 | unit: `counting_late_gives_way` | | 15 | With a stolen key, signs statements that come before its user's own (keys, creations, claims), to push those past their limits | Until the key is cut off they do. What a cut leaves out comes before nothing: the user's own count again, and what was claimed in sight of them meanwhile gives way where a root's node had seen them hold | 3 | unit: `cut_off_comes_before_nothing` | | 16 | Names another party's node as one that carries for it; offers that node a token of its own | A node carries only once it committed the statement naming it; an honest node takes tokens only from nodes its operator named | 3 | unit: `a_node_carries_by_its_own_word`, `a_token_of_ones_party` | @@ -2037,12 +2037,12 @@ Nodes and syncing: | 108 | Forks its node's actor | The nodes that took each split; one offered both holds proof and refuses the node; a side drops by its operator's choice | not promised | sim: `a_forked_actor_is_proven`, `a_side_drops_a_fork` | | 109 | Holds changes back, or passes on some | They come by other nodes; a joiner caught up with it syncs on | 6 | sim: `withheld_changes_arrive` | | 110 | Places its nodes around a victim by choosing their keys | The victim's node keeps its seeds and its user's other nodes as neighbours; a claim not settled for long shows. It costs time, not names | 5, 6 | sim: `around_a_victim` | -| 111 | Hands a joining node another root, or changes from before the policy | Refuse the handshake; there is no before | 1 | sim: `a_joiner_takes_its_root_only` | +| 111 | Hands a joining node another root change, or changes from before the policy | Refuse the handshake; there is no before | 1 | sim: `a_joiner_takes_its_root_only` | | 112 | Signs a token for any user with its node's key | Taken only by a node whose operator named the signing node | 3 | unit: `a_token_of_ones_party` | | 113 | Logs in on another party's node with a key of the registry; has a name in the registry that the node's own users have | Keys in the registry give nothing on anyone's node by themselves: whom a node lets in is its operator's, and what a user may write is in its signature | 3 | unit: `registry_keys_open_no_node` | | 114 | Lies in its member entry (ready, reached, stable); publishes a short window there to make every node stamp hourly; writes an entry of any size | Sync and trees bend; nothing gets in that way. How often nodes stamp is the policy's; an entry has a shape and a size, or the change is refused | 6 | unit: `an_entry_has_a_shape`, `stamps_by_the_policy`; argued (Reaching the others) | | 115 | Sends envelopes that don't check, without end | Refuse each (a signature costs about 30 µs to check *(docs)*); the node is refused as a whole after the first of its own | 6 | sim: `a_refused_node_costs_little` | -| 116 | Writes its own member entry without end; fills the waiting changes; sends changes that say they saw little, each to be judged far back | Take them no faster than a budget per party: put off, never refused; a share of the waiting each | 6 | sim: `a_party_past_its_budget_waits` | +| 116 | Writes its own member entry without end; signs and gives up without end; fills the waiting changes; sends changes that say they saw little, each to be judged far back | Take them no faster than a budget per party: put off, never refused; a share of the waiting each | 6 | sim: `a_party_past_its_budget_waits` | | 117 | Starts a writer with every change: each costs every node memory in proportion to the document's history | Past `limits.writers` a party and epoch, every node puts off the changes that start more, taking none from the party's own nodes. Nothing is refused; what reaches a node within others' histories is held, and a remake leaves it out | 6; not bounded | sim: `writers_past_a_budget_wait` | | 118 | Sends a change of a few bytes that holds a million operations | Taken, at the cost of applying it: nothing bounds a change's operations | not promised | argued | | 119 | Crafts a change Automerge won't take, or that writes in an object nowhere to be found | Refuse *(checked: the rules refuse the second today)*; only the message that brought it fails | 1 | unit: `a_change_writing_nowhere` | @@ -2117,12 +2117,13 @@ their vectors. At every stage the existing tests pass untouched (125). 1. **A federated swarm's frame.** `--genesis-policy` (a file, written into the genesis change with the roots, the voters and the users it starts with); a federated node - is given its root, syncs under no policy it doesn't know, takes no remake yet, - takes tokens and logins by key as its operator says, keeps ended sessions to + is given its root change, syncs under no policy it doesn't know, takes no remake + yet, takes tokens and logins by key as its operator says, keeps ended sessions to itself, stamps as the policy says, and writes a member entry of the policy's shape and size. What the genesis change sets for the swarm as a whole is read from the - policy. Tests: 111 to 114, 123, 125, and the policy's existing tests under a policy - from the root. + policy. Tests: 111 to 114, 120, 123, 125, and the policy's existing tests under a + policy from the genesis change. Those of a crafted change exist already: screening + refuses those in every swarm. 2. **Statements.** The users' registers (`create`, `key`, `node`, `vouch`, `release`); the user ID, the epoch and what its signer saw in an envelope; nodes carrying for users by their own word, and the rule for committers by it; nothing plain; the -- cgit v1.3.1