Skip to main content

kernel/graph/
membership.rs

1// Copyright 2026 Mark Alan Boykin
2// SPDX-License-Identifier: MPL-2.0
3
4//! Runtime membership witnesses, authored at the kernel's insertion boundary.
5//! These are not persisted identity, a graph revision, or an authorization lease.
6use super::{Graph, Node, NodeKey};
7use uuid::Uuid;
8
9/// One live surface membership. Cloning a graph preserves it; removing and
10/// recreating a member creates a new witness, even with the same UUID/key.
11/// Snapshot materialization starts new runtime lives. There is no numeric or
12/// serialization API: durable identity remains the member UUID.
13#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
14pub struct SurfaceNodeLifetime(u64);
15
16impl SurfaceNodeLifetime {
17    fn fresh() -> Self {
18        use std::sync::atomic::{AtomicU64, Ordering};
19        static NEXT: AtomicU64 = AtomicU64::new(1);
20        Self(
21            NEXT.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |n| n.checked_add(1))
22                .expect("surface membership lifetime space exhausted"),
23        )
24    }
25}
26
27impl Graph {
28    /// Observe membership without allocating or changing its life.
29    pub fn surface_node_lifetime(&self, id: Uuid) -> Option<SurfaceNodeLifetime> {
30        self.inner.key_of(&id)?;
31        self.surface_node_lifetimes.get(&id).copied()
32    }
33
34    /// All surface insertions, including copy and snapshot materialization,
35    /// share this boundary and its one contract: insert-if-missing. An id that
36    /// is already a member keeps its node and membership untouched, and the
37    /// flag is `false`; callers then skip their own indices and revisions.
38    pub(super) fn insert_surface_node(&mut self, node: Node) -> (NodeKey, bool) {
39        let id = node.id;
40        if let Some(key) = self.inner.key_of(&id) {
41            return (key, false);
42        }
43        let key = self.inner.insert(node);
44        self.surface_node_lifetimes
45            .insert(id, SurfaceNodeLifetime::fresh());
46        (key, true)
47    }
48}
49
50#[cfg(test)]
51mod tests {
52    use super::super::snapshot::ResourceSnapshotError;
53    use super::*;
54    #[test]
55    fn ordinary_edits_upserts_and_clones_keep_membership_but_recreation_does_not() {
56        let mut graph = Graph::new();
57        let id = Uuid::from_u128(1);
58        let key = graph.add_node_with_id(id, "https://original.example".into(), Default::default());
59        let old = graph.surface_node_lifetime(id).unwrap();
60        let mut candidate = graph.clone();
61        candidate.set_node_title(key, "Ordinary edit".into());
62        assert_eq!(candidate.surface_node_lifetime(id), Some(old));
63        assert_eq!(
64            candidate.add_node_with_id(id, "https://updated.example".into(), Default::default()),
65            key
66        );
67        assert_eq!(candidate.surface_node_lifetime(id), Some(old));
68        assert!(candidate.remove_node(key));
69        assert_eq!(candidate.surface_node_lifetime(id), None);
70        let next =
71            candidate.add_node_with_id(id, "https://recreated.example".into(), Default::default());
72        assert_eq!(key, next, "exercise graph slot reuse");
73        assert_ne!(candidate.surface_node_lifetime(id), Some(old));
74        assert_eq!(
75            graph.surface_node_lifetime(id),
76            Some(old),
77            "detached candidate cannot mutate live identity"
78        );
79    }
80    #[test]
81    fn copies_share_the_insert_boundary_and_remove_never_keeps_a_dead_witness() {
82        let mut donor = Graph::new();
83        let source_id = Uuid::from_u128(2);
84        let source = donor.add_node_with_id(
85            source_id,
86            "https://source.example".into(),
87            Default::default(),
88        );
89        let mut graph = Graph::new();
90        let id = Uuid::from_u128(3);
91        let key = graph.copy_node_from_with_id(
92            id,
93            donor.get_node(source).unwrap(),
94            None,
95            Default::default(),
96        );
97        let old = graph.surface_node_lifetime(id).unwrap();
98        assert_eq!(
99            graph.copy_node_from_with_id(
100                id,
101                donor.get_node(source).unwrap(),
102                None,
103                Default::default()
104            ),
105            key
106        );
107        assert_eq!(graph.surface_node_lifetime(id), Some(old));
108        assert!(graph.remove_node(key));
109        assert!(!graph.remove_node(key));
110        assert!(graph.surface_node_lifetimes.is_empty());
111        graph.copy_node_from_with_id(
112            id,
113            donor.get_node(source).unwrap(),
114            None,
115            Default::default(),
116        );
117        assert_ne!(graph.surface_node_lifetime(id), Some(old));
118        assert_ne!(
119            graph.surface_node_lifetime(id),
120            donor.surface_node_lifetime(source_id)
121        );
122    }
123    #[test]
124    fn adding_an_existing_id_live_keeps_the_node_and_the_url_index_honest() {
125        use crate::graph::apply::{GraphDelta, add_node, apply_graph_delta};
126        use crate::graph::replay_captured_deltas;
127        use std::sync::{Arc, Mutex};
128        let (old, new, unrelated) = (
129            "https://t.test/old",
130            "https://t.test/new",
131            "https://t.test/x",
132        );
133        let mut graph = Graph::new();
134        let seen = Arc::new(Mutex::new(Vec::new()));
135        let sink = seen.clone();
136        graph.set_recorder(Some(Arc::new(move |delta| {
137            sink.lock().unwrap().push(delta.clone())
138        })));
139        let id = Uuid::from_u128(101);
140        let first = add_node(&mut graph, Some(id), old.into(), Default::default());
141        let (recorded, revision) = (seen.lock().unwrap().len(), graph.revision());
142        let second = add_node(&mut graph, Some(id), new.into(), Default::default());
143        assert_eq!(first, second);
144        assert_eq!(graph.node_count(), 1);
145        assert_eq!(graph.get_node(first).unwrap().url(), old);
146        assert_eq!(graph.get_nodes_by_url(old), vec![first]);
147        assert!(graph.get_nodes_by_url(new).is_empty());
148        assert_eq!(
149            seen.lock().unwrap().len(),
150            recorded,
151            "a no-op records nothing"
152        );
153        assert_eq!(graph.revision(), revision);
154        let replayed = replay_captured_deltas(seen.lock().unwrap().clone());
155        assert_eq!(
156            replayed.get_node_by_id(id).unwrap().1.url(),
157            old,
158            "live and replay agree"
159        );
160        apply_graph_delta(&mut graph, GraphDelta::RemoveNode { key: first });
161        assert!(graph.get_nodes_by_url(old).is_empty());
162        let other = add_node(
163            &mut graph,
164            Some(Uuid::from_u128(102)),
165            unrelated.into(),
166            Default::default(),
167        );
168        assert_eq!(other, first, "arena key is recycled");
169        assert!(
170            graph.get_nodes_by_url(old).is_empty(),
171            "the old address never resolves to the recycled slot"
172        );
173        assert_eq!(graph.get_nodes_by_url(unrelated), vec![other]);
174    }
175    #[test]
176    fn copy_onto_an_existing_id_keeps_the_first_node_and_a_repeated_snapshot_id_is_refused() {
177        let mut graph = Graph::new();
178        let id = Uuid::from_u128(5);
179        let key = graph.add_node_with_id(id, "https://first.example".into(), Default::default());
180        let mut donor = Graph::new();
181        let source = donor.add_node_with_id(
182            Uuid::from_u128(6),
183            "https://donor.example".into(),
184            Default::default(),
185        );
186        let copy = graph.copy_node_from_with_id(
187            id,
188            donor.get_node(source).unwrap(),
189            None,
190            Default::default(),
191        );
192        assert_eq!(copy, key);
193        assert_eq!(graph.get_node(key).unwrap().url(), "https://first.example");
194        assert!(graph.get_nodes_by_url("https://donor.example").is_empty());
195        let mut snapshot = graph.to_snapshot();
196        let mut other = Graph::new();
197        other.add_node_with_id(
198            Uuid::from_u128(7),
199            "https://repeat.example".into(),
200            Default::default(),
201        );
202        let mut repeated = other.to_snapshot().nodes.remove(0);
203        repeated.node_id = id.to_string();
204        repeated.title = "Repeat".into();
205        snapshot.nodes.push(repeated);
206        assert_eq!(
207            Graph::try_from_snapshot(&snapshot).err(),
208            Some(ResourceSnapshotError::RepeatedSurfaceId {
209                surface_id: id,
210                first_index: 0,
211                index: 1
212            })
213        );
214    }
215    #[test]
216    fn persisted_content_restores_with_new_runtime_membership() {
217        let mut graph = Graph::new();
218        let id = Uuid::from_u128(4);
219        graph.add_node_with_id(id, "https://persisted.example".into(), Default::default());
220        let snapshot = graph.to_snapshot();
221        let restored = Graph::from_snapshot(&snapshot);
222        assert!(restored.get_node_by_id(id).is_some());
223        assert_eq!(
224            restored.get_node_by_id(id).unwrap().1.title,
225            graph.get_node_by_id(id).unwrap().1.title
226        );
227        assert_ne!(
228            graph.surface_node_lifetime(id),
229            restored.surface_node_lifetime(id)
230        );
231    }
232}