From 3bf93bc192bf362b58b2161ac05da0bb8323bf43 Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 9 Nov 2026 17:33:24 +0000 Subject: docs: what is postponed or rejected stays in its own two files Docs and comments outside future-work.md and review-rejections.md say what the code does, and point nowhere else for what it doesn't: the architecture page's map, the transports' forwarders, keys with `/`, a strict swarm's registry, trust.md's "Not yet" (now saying what isn't protected, in a sentence), the topology bench, and the comments of the change benchmarks, capabilities' grantor, tokens, dissemination, refusals and topology. --- docs/access.md | 3 +-- docs/topology.md | 3 +-- docs/trust.md | 6 +++--- src/access/mod.rs | 3 +-- src/access/token.rs | 3 +-- src/document/bench.rs | 4 ++-- src/swarm/dissemination.rs | 3 +-- src/swarm/refusals.rs | 3 +-- src/swarm/topology/mod.rs | 3 +-- 9 files changed, 12 insertions(+), 19 deletions(-) diff --git a/docs/access.md b/docs/access.md index 7bacd91..1397656 100644 --- a/docs/access.md +++ b/docs/access.md @@ -468,8 +468,7 @@ kind, which its proposal and its snapshot's metadata say: a majority of members labelling it otherwise (`compact`, its snapshot holding the registry it wants) gets it followed, as nodes whose own build differs take the quorum's snapshot. So a strict swarm's registry, policy and bans change by its users' signatures against a minority of -members, not against a majority ([`trust.md`](trust.md); comparing a downloaded snapshot -with the node's own build is in [`future-work.md`](future-work.md)). Compaction +members, not against a majority ([`trust.md`](trust.md)). Compaction that keeps, at the places values are signed (the registry, `_continuum/access`, the bans, the paths listed in `userSigned`), only the values an operator looked over and signed, and sets the strict policy. What was written after its base reaches the new diff --git a/docs/topology.md b/docs/topology.md index 31abcf5..674eaed 100644 --- a/docs/topology.md +++ b/docs/topology.md @@ -92,8 +92,7 @@ Mycelium's round trips and 267 ms over Tor's: flooding on the member list's grap to that (its 12 neighbours give more paths than the bench's figure counts), writers' trees take 94 and 324 ms. PlumTree's gap is its tree's depth: along eager links alone a member is 5 to 6 hops from another over Mycelium's round trips (writers' trees: 1.9), -3.4 to 4.3 over Tor's (1.8). `docs/future-work.md` (Swappable topology and -dissemination) says how it got there and what was tried. +3.4 to 4.3 over Tor's (1.8). HyParView's active views settle at 5 neighbours each, nearly all held at both ends (up to 3 links of about 125 at one end only, at the end of a run). A member one short asks diff --git a/docs/trust.md b/docs/trust.md index 3839958..72a238d 100644 --- a/docs/trust.md +++ b/docs/trust.md @@ -159,6 +159,6 @@ Not against a hostile member, but against honest ones getting in each other's wa ## Not yet -What is left of protecting the swarm against its members, and of keys in browsers, is in -[`future-work.md`](future-work.md): Write protection by checking changes, Read access -beyond sealed values, Keys in browsers. +A member is trusted with what its own node writes as itself: checking changes protects +protocol data and the paths listed as signed, not data at large; reading is protected +only for sealed values; and keys stay out of browsers. diff --git a/src/access/mod.rs b/src/access/mod.rs index f3e5f80..e223756 100644 --- a/src/access/mod.rs +++ b/src/access/mod.rs @@ -68,8 +68,7 @@ pub(crate) struct Capability { /// nothing here. pub(crate) rights: BTreeSet, /// Who granted it: a user (`user:`), or for those the genesis node records, the - /// node (its node ID). Kept so that granting on, by delegation, can come later - /// without a new format (`future-work.md`, Authentication across nodes). + /// node (its node ID), kept with the capability. #[serde(default)] pub(crate) by: String, /// When it was granted (Unix ms). diff --git a/src/access/token.rs b/src/access/token.rs index 153737e..51c2449 100644 --- a/src/access/token.rs +++ b/src/access/token.rs @@ -11,8 +11,7 @@ //! //! Not Biscuit or UCAN (November 2026): a token only names a user, narrowing is asked //! of a node (which issues a narrower one), and Biscuit would bring about a hundred -//! crates, older versions of several of ours among them (Ed25519, SHA-2, protobuf): -//! `future-work.md`, Authentication across nodes. +//! crates, older versions of several of ours among them (Ed25519, SHA-2, protobuf). use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD as BASE64URL}; use serde::{Deserialize, Serialize}; diff --git a/src/document/bench.rs b/src/document/bench.rs index 39a8dc7..db76ccc 100644 --- a/src/document/bench.rs +++ b/src/document/bench.rs @@ -8,7 +8,7 @@ //! ways on the same input. //! //! `change_signatures`: what signing every change by its committer's node key would -//! cost (`future-work.md`, Write protection by checking changes): an Ed25519 signature +//! cost: an Ed25519 signature //! over a change's hash, made on every commit, checked on every change received. //! Against what the node does anyway on the same input: a local write, a sync message //! of many changes received (catching up), and a document of many changes loaded @@ -20,7 +20,7 @@ //! same input (`changes::misplaced_author`). //! //! `change_paths`: what knowing every received change's paths would cost, to judge it by -//! rules by path (`future-work.md`, Write protection by checking changes): each +//! rules by path: each //! change's operations decoded, and each object they name followed up to the root as //! the change left it (`store::changed_by`, so every node finds the same paths). Against //! receiving a sync message of many changes and loading a document of many changes, as diff --git a/src/swarm/dissemination.rs b/src/swarm/dissemination.rs index 9763449..4c15d0f 100644 --- a/src/swarm/dissemination.rs +++ b/src/swarm/dissemination.rs @@ -1,8 +1,7 @@ //! How a change reaches every member: whom a node sends a writer's changes to at once, //! and whom it leaves to the announcement rounds (`swarm::relay`, which repair what it //! misses: announcements, pulls, the slow round). Writers' trees (`swarm::tree`) are -//! one way; others can be tried against them in the benchmark (`docs/future-work.md`, -//! Swappable topology and dissemination). One per swarm: a node's part in passing a +//! one way; others can be tried against them in the benchmark. One per swarm: a node's part in passing a //! change on is worked out by itself and by its neighbours, and must agree. //! //! What every way keeps: the base underneath, pairs of neighbours syncing with diff --git a/src/swarm/refusals.rs b/src/swarm/refusals.rs index 30c3971..652f9bc 100644 --- a/src/swarm/refusals.rs +++ b/src/swarm/refusals.rs @@ -12,8 +12,7 @@ //! everything built on it: its document as it would be without them, its own writes //! among them quarantined, the others' listed as refused (`AppState::drop_taken`); one //! taking much, once a second member says so too. If its rules take it, the two -//! policies disagree, which it logs; finding out which is right is left -//! (`future-work.md`, Write protection by checking changes). +//! policies disagree, which it logs; it doesn't find out which is right. use std::time::Duration; diff --git a/src/swarm/topology/mod.rs b/src/swarm/topology/mod.rs index 2d812e5..8fae0ed 100644 --- a/src/swarm/topology/mod.rs +++ b/src/swarm/topology/mod.rs @@ -41,8 +41,7 @@ use graph::*; pub(crate) use graph::{RingAndPairs, pair_key, pair_score}; /// How members' neighbours are chosen: the graph above (`RingAndPairs`) is one way; -/// others can be tried against it in the benchmark (`docs/future-work.md`, Swappable -/// topology and dissemination). One per swarm: a node's neighbours must count it as +/// others can be tried against it in the benchmark. One per swarm: a node's neighbours must count it as /// theirs. /// /// A topology either computes a graph every node shares (`graph`: the same inputs give -- cgit v1.3.1