Skip to main content

kernel/graph/
edge_ops.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Edge operations — assert, replay, dissolve, retract, traversal
5//! recording.
6//!
7//! Extracted from `graph/mod.rs` per the 2026-05-11 kernel
8//! decomposition pass. Stage 4 of the 2026-05-11 relation-taxonomy
9//! plan removed the legacy `add_edge` / `remove_edges` /
10//! `replay_add_edge_by_ids` / `replay_remove_edges_by_ids` paths and
11//! their `EdgeType`-shaped helpers; everything goes through
12//! [`EdgeAssertion`] / [`RelationSelector`] now.
13
14use euclid::default::Point2D;
15use petgraph::Direction;
16use petgraph::visit::{EdgeRef, IntoEdgeReferences};
17use uuid::Uuid;
18
19use crate::types::GraphScope;
20
21use super::edge_data::Traversal;
22use super::edge_data::{SemanticStatement, SemanticStatementSpec, StatementAssert};
23use super::edge_payload::EdgePayload;
24use super::edge_taxonomy::{EdgeAssertion, RelationSelector, SemanticSubKind};
25use super::identity::{EdgeKey, NodeKey};
26use super::{DissolvedTraversalRecord, Graph};
27
28impl Graph {
29    pub(crate) fn assert_relation(
30        &mut self,
31        from: NodeKey,
32        to: NodeKey,
33        assertion: EdgeAssertion,
34    ) -> Option<EdgeKey> {
35        if let EdgeAssertion::Semantic {
36            sub_kind,
37            label,
38            decay_progress: _,
39        } = assertion
40        {
41            return self.assert_semantic_relation_in_scope(
42                from,
43                to,
44                sub_kind,
45                label,
46                GraphScope::Default,
47            );
48        }
49        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
50            return None;
51        }
52        if let Some(edge_key) = self.find_edge_key(from, to) {
53            // Existing edge: assert onto its payload. A real change (a new relation on the pair —
54            // a multiplicity bump a weighted signal reads) advances the revision.
55            let changed = {
56                let payload = self.inner.edge_mut(edge_key)?;
57                payload.assert_relation(assertion)
58            };
59            if changed {
60                self.bump_revision();
61                return Some(edge_key);
62            }
63            return None;
64        }
65        let mut payload = EdgePayload::new();
66        if !payload.assert_relation(assertion) {
67            return None;
68        }
69        let edge_key = self.inner.connect(from, to, payload);
70        self.bump_revision();
71        Some(edge_key)
72    }
73
74    pub(crate) fn assert_semantic_relation_in_scope(
75        &mut self,
76        from: NodeKey,
77        to: NodeKey,
78        sub_kind: SemanticSubKind,
79        label: Option<String>,
80        graph_scope: GraphScope,
81    ) -> Option<EdgeKey> {
82        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
83            return None;
84        }
85        let edge_key = self
86            .find_edge_key(from, to)
87            .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
88        let changed = {
89            let payload = self.inner.edge_mut(edge_key)?;
90            payload.assert_semantic_relation_in_scope(sub_kind, label, graph_scope)
91        };
92        if changed {
93            self.bump_revision();
94            return Some(edge_key);
95        }
96        None
97    }
98
99    /// Assert an **open predicate** semantic relation from `from` to `to`,
100    /// identified by an IRI rather than a closed [`SemanticSubKind`]. Creates the
101    /// pair-local edge bucket if absent and appends one open semantic statement to
102    /// it; an edge carrying only such a statement still reports the `Semantic`
103    /// family. Returns the edge, or `None` if either endpoint is missing or the
104    /// same open predicate statement already exists. Write path for raw web
105    /// predicates (linked-data ingest / knot `rel`s outside Mere's vocabulary).
106    pub(crate) fn assert_semantic_predicate(
107        &mut self,
108        from: NodeKey,
109        to: NodeKey,
110        predicate: String,
111    ) -> Option<EdgeKey> {
112        self.assert_semantic_predicate_in_scope(from, to, predicate, GraphScope::Default)
113    }
114
115    pub(crate) fn assert_semantic_predicate_in_scope(
116        &mut self,
117        from: NodeKey,
118        to: NodeKey,
119        predicate: String,
120        graph_scope: GraphScope,
121    ) -> Option<EdgeKey> {
122        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
123            return None;
124        }
125        let edge_key = self
126            .find_edge_key(from, to)
127            .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
128        let changed = {
129            let payload = self.inner.edge_mut(edge_key)?;
130            payload.assert_semantic_predicate_in_scope(predicate, graph_scope)
131        };
132        if changed {
133            self.bump_revision();
134            return Some(edge_key);
135        }
136        None
137    }
138
139    /// Replay helper: add node only if UUID is not already present.
140    pub(crate) fn replay_add_node_with_id_if_missing(
141        &mut self,
142        id: Uuid,
143        url: String,
144        position: Point2D<f32>,
145    ) -> Option<NodeKey> {
146        if self.get_node_key_by_id(id).is_some() {
147            return None;
148        }
149        Some(self.add_node_with_id(id, url, position))
150    }
151
152    /// Replay helper: remove node by stable UUID.
153    pub(crate) fn replay_remove_node_by_id(&mut self, node_id: Uuid) -> bool {
154        let Some(key) = self.get_node_key_by_id(node_id) else {
155            return false;
156        };
157        self.remove_node(key)
158    }
159
160    pub(crate) fn replay_retract_relations_by_ids(
161        &mut self,
162        from_id: Uuid,
163        to_id: Uuid,
164        selector: RelationSelector,
165    ) -> usize {
166        let Some(from_key) = self.get_node_key_by_id(from_id) else {
167            return 0;
168        };
169        let Some(to_key) = self.get_node_key_by_id(to_id) else {
170            return 0;
171        };
172        self.retract_relations(from_key, to_key, selector)
173    }
174
175    pub(crate) fn replay_assert_relation_by_ids(
176        &mut self,
177        from_id: Uuid,
178        to_id: Uuid,
179        assertion: EdgeAssertion,
180    ) -> Option<EdgeKey> {
181        let from_key = self.get_node_key_by_id(from_id)?;
182        let to_key = self.get_node_key_by_id(to_id)?;
183        self.assert_relation(from_key, to_key, assertion)
184    }
185
186    pub(crate) fn replay_set_edge_semantic_predicate_by_ids(
187        &mut self,
188        from_id: Uuid,
189        to_id: Uuid,
190        predicate: Option<String>,
191    ) -> bool {
192        let Some(from_key) = self.get_node_key_by_id(from_id) else {
193            return false;
194        };
195        let Some(to_key) = self.get_node_key_by_id(to_id) else {
196            return false;
197        };
198        let Some(edge_key) = self.find_edge_key(from_key, to_key) else {
199            return false;
200        };
201        self.set_edge_semantic_predicate(edge_key, predicate)
202    }
203
204    pub(crate) fn replay_assert_semantic_predicate_by_ids(
205        &mut self,
206        from_id: Uuid,
207        to_id: Uuid,
208        predicate: String,
209    ) -> Option<EdgeKey> {
210        let from_key = self.get_node_key_by_id(from_id)?;
211        let to_key = self.get_node_key_by_id(to_id)?;
212        self.assert_semantic_predicate(from_key, to_key, predicate)
213    }
214
215    pub(crate) fn replay_append_traversal_by_ids(
216        &mut self,
217        from_id: Uuid,
218        to_id: Uuid,
219        trigger: super::edge_taxonomy::NavigationTrigger,
220        timestamp_ms: u64,
221    ) -> bool {
222        let Some(from_key) = self.get_node_key_by_id(from_id) else {
223            return false;
224        };
225        let Some(to_key) = self.get_node_key_by_id(to_id) else {
226            return false;
227        };
228        self.append_traversal(from_key, to_key, trigger, Some(timestamp_ms))
229    }
230
231    /// Dissolve helper: collect traversals from all incident edges and remove the node.
232    pub(crate) fn dissolve_remove_node_collect_traversals(
233        &mut self,
234        key: NodeKey,
235    ) -> Option<Vec<DissolvedTraversalRecord>> {
236        let _ = self.get_node(key)?;
237
238        let mut records = Vec::new();
239        let inner = self.inner.inner();
240        for edge in inner
241            .edges_directed(key, Direction::Outgoing)
242            .chain(inner.edges_directed(key, Direction::Incoming))
243        {
244            if edge.weight().traversals().is_empty() {
245                continue;
246            }
247
248            let from_node = self.get_node(edge.source())?;
249            let to_node = self.get_node(edge.target())?;
250            records.push(DissolvedTraversalRecord {
251                from_node_id: from_node.id,
252                to_node_id: to_node.id,
253                traversals: edge.weight().traversals().to_vec(),
254            });
255        }
256
257        let _ = self.remove_node(key);
258        Some(records)
259    }
260
261    /// Collect traversals from all incident edges without mutating graph state.
262    pub fn collect_node_traversals(&self, key: NodeKey) -> Option<Vec<DissolvedTraversalRecord>> {
263        let _ = self.get_node(key)?;
264
265        let mut records = Vec::new();
266        let inner = self.inner.inner();
267        for edge in inner
268            .edges_directed(key, Direction::Outgoing)
269            .chain(inner.edges_directed(key, Direction::Incoming))
270        {
271            if edge.weight().traversals().is_empty() {
272                continue;
273            }
274
275            let from_node = self.get_node(edge.source())?;
276            let to_node = self.get_node(edge.target())?;
277            records.push(DissolvedTraversalRecord {
278                from_node_id: from_node.id,
279                to_node_id: to_node.id,
280                traversals: edge.weight().traversals().to_vec(),
281            });
282        }
283
284        Some(records)
285    }
286
287    /// Statement-aware assert (petgraph-RDF Phase 1 write API): assert one
288    /// semantic statement with full per-statement metadata on the `(from, to)`
289    /// pair bucket, creating the bucket edge if absent. Content-dedup returns
290    /// the EXISTING fact handle (updating its metadata in place); a genuine
291    /// change bumps the revision. `None` only when an endpoint is missing.
292    pub fn assert_semantic_statement(
293        &mut self,
294        from: NodeKey,
295        to: NodeKey,
296        spec: SemanticStatementSpec,
297    ) -> Option<(EdgeKey, StatementAssert)> {
298        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
299            return None;
300        }
301        let edge_key = self
302            .find_edge_key(from, to)
303            .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
304        let outcome = {
305            let payload = self.inner.edge_mut(edge_key)?;
306            payload.assert_semantic_statement(spec)
307        };
308        if outcome.changed {
309            self.bump_revision();
310        }
311        Some((edge_key, outcome))
312    }
313
314    /// Assert a semantic statement whose id is ALREADY minted — the re-ingest /
315    /// round-trip path (a reifier carried the fact handle, and preserving it is
316    /// what makes `RDF -> kernel -> RDF` id-stable). Same content-dedup as the
317    /// persisted-snapshot load; endpoints must exist.
318    pub fn assert_persisted_semantic_statement(
319        &mut self,
320        from: NodeKey,
321        to: NodeKey,
322        statement: SemanticStatement,
323    ) -> Option<EdgeKey> {
324        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
325            return None;
326        }
327        let edge_key = self
328            .find_edge_key(from, to)
329            .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
330        let changed = {
331            let payload = self.inner.edge_mut(edge_key)?;
332            payload.push_persisted_semantic_statement(statement)
333        };
334        if changed {
335            self.bump_revision();
336        }
337        Some(edge_key)
338    }
339
340    /// Precise retract by fact handle (the id `assert_semantic_statement`
341    /// returned, also carried on every projected reifier). Removes the
342    /// statement from the pair bucket; an emptied payload removes the petgraph
343    /// edge itself, so "there is an edge A -> B" keeps meaning "at least one
344    /// fact or other family payload exists on the pair".
345    pub fn retract_semantic_statement(
346        &mut self,
347        from: NodeKey,
348        to: NodeKey,
349        statement_id: &str,
350    ) -> bool {
351        let Some(edge_key) = self.find_edge_key(from, to) else {
352            return false;
353        };
354        let (removed, now_empty) = {
355            let Some(payload) = self.inner.edge_mut(edge_key) else {
356                return false;
357            };
358            let removed = payload.retract_semantic_statement(statement_id);
359            (removed, removed && payload.is_empty())
360        };
361        if now_empty {
362            let _ = self.inner.disconnect(edge_key);
363        }
364        if removed {
365            self.bump_revision();
366        }
367        removed
368    }
369
370    pub(crate) fn retract_relations(
371        &mut self,
372        from: NodeKey,
373        to: NodeKey,
374        selector: RelationSelector,
375    ) -> usize {
376        let edge_ids: Vec<EdgeKey> = self
377            .inner
378            .inner()
379            .edge_references()
380            .filter(|edge| {
381                edge.source() == from && edge.target() == to && edge.weight().has_relation(selector)
382            })
383            .map(|edge| edge.id())
384            .collect();
385
386        let mut removed = 0usize;
387        let mut edges_to_delete = Vec::new();
388        for edge_id in edge_ids {
389            if let Some(payload) = self.inner.edge_mut(edge_id)
390                && payload.retract_relation(selector)
391            {
392                removed += 1;
393                if payload.is_empty() {
394                    edges_to_delete.push(edge_id);
395                }
396            }
397        }
398        for edge_id in edges_to_delete {
399            let _ = self.inner.disconnect(edge_id);
400        }
401        if removed > 0 {
402            self.bump_revision();
403        }
404        removed
405    }
406
407    /// Get a mutable edge payload by key.
408    pub(crate) fn get_edge_mut(&mut self, key: EdgeKey) -> Option<&mut EdgePayload> {
409        self.inner.edge_mut(key)
410    }
411
412    /// Set (or clear) the canonical semantic-predicate IRI on an existing edge.
413    /// Returns whether the edge exists. The sanctioned write path for a payload's
414    /// predicate — the linked-data ingest and inker statements previously reached
415    /// it through `get_edge_mut` (write-path migration, 2026-07-01). A content
416    /// annotation on an existing edge, not a structural change, so the revision
417    /// holds (same rule as title/tag edits).
418    pub(crate) fn set_edge_semantic_predicate(
419        &mut self,
420        key: EdgeKey,
421        predicate: Option<String>,
422    ) -> bool {
423        let Some(payload) = self.inner.edge_mut(key) else {
424            return false;
425        };
426        payload.set_semantic_predicate(predicate);
427        true
428    }
429
430    /// Get an edge payload by key.
431    pub fn get_edge(&self, key: EdgeKey) -> Option<&EdgePayload> {
432        self.inner.edge(key)
433    }
434
435    /// Find the first directed edge key between two nodes.
436    pub fn find_edge_key(&self, from: NodeKey, to: NodeKey) -> Option<EdgeKey> {
437        self.inner.inner().find_edge(from, to)
438    }
439
440    /// Append a traversal event to an existing edge, or create an edge carrying the traversal.
441    pub(crate) fn push_traversal(
442        &mut self,
443        from: NodeKey,
444        to: NodeKey,
445        traversal: Traversal,
446    ) -> bool {
447        if from == to || !self.inner.contains_node(from) || !self.inner.contains_node(to) {
448            return false;
449        }
450        if let Some(edge_key) = self.find_edge_key(from, to)
451            && let Some(payload) = self.inner.edge_mut(edge_key)
452        {
453            // Existing edge: a re-visit appends a traversal but does not change the structure, so
454            // the revision holds (navigation re-visits must not churn the structural caches).
455            payload.push_traversal(traversal);
456            return true;
457        }
458        let mut payload = EdgePayload::new();
459        payload.push_traversal(traversal);
460        let _ = self.inner.connect(from, to, payload);
461        self.bump_revision();
462        true
463    }
464
465    /// Append a traversal event by `(trigger, timestamp_ms?)`.
466    /// Thin wrapper over [`Self::push_traversal`] matching the
467    /// 2026-05-11 relation-taxonomy plan §7 signature — callers
468    /// that just have a `NavigationTrigger` don't need to build a
469    /// `Traversal` struct themselves. `timestamp_ms = None` stamps
470    /// now-via-`Traversal::now`; `Some(t)` uses the supplied
471    /// timestamp (importers, replay).
472    pub(crate) fn append_traversal(
473        &mut self,
474        from: NodeKey,
475        to: NodeKey,
476        trigger: super::edge_taxonomy::NavigationTrigger,
477        timestamp_ms: Option<u64>,
478    ) -> bool {
479        let traversal = match timestamp_ms {
480            Some(timestamp_ms) => Traversal {
481                timestamp_ms,
482                trigger,
483            },
484            None => Traversal::now(trigger),
485        };
486        self.push_traversal(from, to, traversal)
487    }
488}