From c9c7807bf0f068474ce5c853244bcb392bdfcce3 Mon Sep 17 00:00:00 2001
From: tv <tv@krebsco.de>
Date: Sun, 8 Nov 2026 19:16:10 +0000
Subject: roots: an epoch's root pinned, and named in every handshake

Review 2, N7, the care it raised: a joining node's empty document took
as the first epoch's root whatever dependency-less change came first,
from whichever peer it joined through; the first epoch's ID is all
zeros, so nothing pinned it. A remake's epoch has its ID, the snapshot
change's hash, which the rules hold its root to.

* Every node names its epoch's root in HELLO and HELLO_REPLY (the
  epoch's ID for a remake's, its genesis change for the first; wire
  version 45). A node whose document starts from another root of the
  same epoch refuses the handshake, logging it: another history under
  the swarm's ID, a forged root or a genesis started again.
* A joining node with an empty document takes as its root only the one
  it was given (--genesis-root, new), else the one its peers name, and
  none while they name different ones (access::screen::RootPin, kept
  in Screening across documents): one peer hands it another root only
  if it is all the joiner hears, or never, with --genesis-root. A root
  refused is listed with the refused, what builds on it with it.
* The genesis node logs the root (`The swarm's root`); GET
  /admin/epochs shows it (`root`).

A genesis started again under a remembered swarm ID used to merge with
the nodes of it still running; they now refuse it (another root), and
the docs say to join them with seeds instead.

The epoch's identity stays as it is (generation 0 all zeros): records
and epoch metadata name it so, and every comparison of epochs with
them.
---
 src/access/screen.rs | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

(limited to 'src/access/screen.rs')

diff --git a/src/access/screen.rs b/src/access/screen.rs
index 758c83b..690e032 100644
--- a/src/access/screen.rs
+++ b/src/access/screen.rs
@@ -75,6 +75,20 @@ pub(crate) struct Screening {
     /// Changes this node holds that peers say the swarm's rules refuse, and its own do
     /// too, whose drop would take much: each with the peers that said so (`hold_drop`).
     held_drops: HashMap<ChangeHash, BTreeSet<String>>,
+    /// Which change an empty document of the first epoch takes as its root
+    /// (`swarm::roots`); kept from one document to the next.
+    pub(crate) root_pin: RootPin,
+}
+
+/// Which change an empty document of the first epoch takes as its root: any (nothing
+/// heard of it, nor given), the one given (`--genesis-root`) or that its peers name, or
+/// none while they name different ones.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub(crate) enum RootPin {
+    #[default]
+    Any,
+    Only(ChangeHash),
+    Disputed,
 }
 
 /// A member refused as a whole: since when, for which change of its, and why.
@@ -116,11 +130,20 @@ impl Refusals {
 }
 
 impl Screening {
+    /// Empty, with `root_pin`.
+    pub(crate) fn pinned(root_pin: RootPin) -> Self {
+        Screening {
+            root_pin,
+            ..Screening::default()
+        }
+    }
+
     /// Itself for the document `epoch_seq`: emptied if it was another's.
     pub(crate) fn of(&mut self, epoch_seq: u32) -> &mut Self {
         if self.epoch_seq != epoch_seq {
             *self = Screening {
                 epoch_seq,
+                root_pin: std::mem::take(&mut self.root_pin),
                 ..Screening::default()
             };
         }
@@ -629,10 +652,48 @@ pub(crate) fn apply_bytes(
     if let Some(misplaced) = crate::document::changes::misplaced_author(bytes) {
         anyhow::bail!("Refused changes: {misplaced}");
     }
-    let changes = crate::document::changes::changes_in(bytes)
+    let mut changes = crate::document::changes::changes_in(bytes)
         .ok_or_else(|| anyhow::anyhow!("Refused changes that don't load"))?;
     let mut screening = screening.lock_or_recover();
     let screening = screening.of(epoch_seq);
+    // Into an empty document of the first epoch, a root only as pinned: one given or
+    // named by the peers, none while they disagree (left for later). What builds on a
+    // root refused is refused with it; on one left, it waits.
+    let mut pinned_out = Vec::new();
+    if epoch.generation == 0 && doc.get_heads().is_empty() && screening.root_pin != RootPin::Any {
+        changes.retain(|change| {
+            if !change.deps().is_empty() {
+                return true;
+            }
+            match &screening.root_pin {
+                RootPin::Only(root) if *root == change.hash() => true,
+                RootPin::Only(root) => {
+                    pinned_out.push((
+                        change.clone(),
+                        format!("a root other than the swarm's ({root})"),
+                    ));
+                    false
+                }
+                _ => false,
+            }
+        });
+    }
+    let mut refused_roots = Vec::new();
+    for (change, why) in pinned_out {
+        screening.refusals.insert(change.hash(), change.hash());
+        refused_roots.push(Refused {
+            committer: change.author().and_then(|author| {
+                std::str::from_utf8(author.as_bytes())
+                    .ok()
+                    .map(str::to_owned)
+            }),
+            user: None,
+            paths: BTreeSet::new(),
+            why,
+            change,
+        });
+    }
+    screening.record(refused_roots);
     if changes.is_empty() && screening.waiting.len() == 0 {
         return Ok(Outcome::default());
     }
-- 
cgit v1.3.1