Skip to main content

kernel/graph/
edge_ops.rs

1// Copyright 2026 Mark Alan Boykin
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at https://mozilla.org/MPL/2.0/.
5// SPDX-License-Identifier: MPL-2.0
6
7//! Edge operations — assert, replay, dissolve, retract, traversal
8//! recording.
9//!
10//! Extracted from `graph/mod.rs` per the 2026-05-11 kernel
11//! decomposition pass. Stage 4 of the 2026-05-11 relation-taxonomy
12//! plan removed the legacy `add_edge` / `remove_edges` /
13//! `replay_add_edge_by_ids` / `replay_remove_edges_by_ids` paths and
14//! their `EdgeType`-shaped helpers; everything goes through
15//! [`EdgeAssertion`] / [`RelationSelector`] now.
16
17use euclid::default::Point2D;
18use petgraph::Direction;
19use petgraph::visit::{EdgeRef, IntoEdgeReferences};
20use uuid::Uuid;
21
22use crate::time::unix_epoch_millis;
23use crate::types::GraphScope;
24
25use super::edge_data::Traversal;
26use super::edge_data::{SemanticStatement, SemanticStatementSpec, StatementAssert};
27use super::edge_payload::EdgePayload;
28use super::edge_taxonomy::{EdgeAssertion, RelationKind, RelationSelector, SemanticSubKind};
29use super::identity::{EdgeKey, NodeKey, RelationKey};
30use super::{DissolvedTraversalRecord, Graph};
31use crate::persistence::PersistedEdge;
32
33/// What a selector retraction did to the statements it found: those it
34/// withdrew, and those the caller's predicate refused, which stay held.
35#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
36pub struct Retraction {
37    pub withdrawn: usize,
38    pub refused: usize,
39}
40
41impl Graph {
42    pub(crate) fn assert_relation(
43        &mut self,
44        from: NodeKey,
45        to: NodeKey,
46        assertion: EdgeAssertion,
47    ) -> Option<RelationKey> {
48        self.assert_relation_as(
49            from,
50            to,
51            assertion,
52            self.write_author().asserter_iri(),
53            None,
54        )
55    }
56
57    pub(crate) fn assert_relation_as(
58        &mut self,
59        from: NodeKey,
60        to: NodeKey,
61        assertion: EdgeAssertion,
62        asserter_iri: String,
63        asserted_at_ms: Option<u64>,
64    ) -> Option<RelationKey> {
65        if let EdgeAssertion::Semantic {
66            sub_kind, label, ..
67        } = assertion
68        {
69            return self
70                .assert_semantic_statement(
71                    from,
72                    to,
73                    SemanticStatementSpec {
74                        predicate: super::predicate_iri(sub_kind).into(),
75                        recognized_sub_kind: Some(sub_kind),
76                        label,
77                        graph_scope: GraphScope::Default,
78                        provenance_iri: Some(asserter_iri),
79                        asserted_at_ms,
80                        basis: Default::default(),
81                    },
82                )
83                .and_then(|(edge, outcome)| outcome.changed.then_some(edge));
84        }
85        let kind = match &assertion {
86            EdgeAssertion::Containment { sub_kind } => RelationKind::Containment(*sub_kind),
87            EdgeAssertion::Arrangement { sub_kind } => RelationKind::Arrangement(*sub_kind),
88            EdgeAssertion::Imported { sub_kind } => RelationKind::Imported(*sub_kind),
89            EdgeAssertion::Provenance { sub_kind } => RelationKind::Provenance(*sub_kind),
90            EdgeAssertion::Semantic { .. } => unreachable!(),
91        };
92        let derived = is_derived_containment(kind);
93        let stratum = super::built_in_relation_stratum(kind);
94        if derived
95            && self.derived_output_id_is_retained_for_pair(
96                match stratum {
97                    super::GraphStratum::Surface => "surface",
98                    super::GraphStratum::Resource => "resource",
99                },
100                from,
101                to,
102                kind,
103            )
104        {
105            return None;
106        }
107        let key = self.relation_bucket(from, to, stratum).ok()?;
108        if derived && self.derived_output_id_is_retained(key, kind) {
109            return None;
110        }
111        if !self.get_relation_mut(key)?.assert_relation_with_context(
112            assertion,
113            Some(asserter_iri),
114            if derived {
115                None
116            } else {
117                Some(asserted_at_ms.unwrap_or_else(unix_epoch_millis))
118            },
119        ) {
120            return None;
121        }
122        if derived {
123            self.normalize_derived_membership(key, kind);
124        }
125        self.bump_revision();
126        self.capture_statement_bucket(key);
127        Some(key)
128    }
129
130    pub(crate) fn assert_surface_relation_as(
131        &mut self,
132        from: NodeKey,
133        to: NodeKey,
134        assertion: EdgeAssertion,
135        asserter_iri: String,
136        asserted_at_ms: Option<u64>,
137    ) -> Option<RelationKey> {
138        if let EdgeAssertion::Semantic {
139            sub_kind,
140            label,
141        } = assertion
142        {
143            return self
144                .assert_surface_semantic_statement(
145                    from,
146                    to,
147                    SemanticStatementSpec {
148                        predicate: super::predicate_iri(sub_kind).into(),
149                        recognized_sub_kind: Some(sub_kind),
150                        label,
151                        graph_scope: GraphScope::Default,
152                        provenance_iri: Some(asserter_iri),
153                        asserted_at_ms,
154                        basis: Default::default(),
155                    },
156                )
157                .and_then(|(edge, outcome)| outcome.changed.then_some(edge));
158        }
159        let derived_kind = match &assertion {
160            EdgeAssertion::Containment { sub_kind }
161                if matches!(
162                    sub_kind,
163                    super::ContainmentSubKind::UrlPath | super::ContainmentSubKind::Domain
164                ) =>
165            {
166                Some(RelationKind::Containment(*sub_kind))
167            },
168            _ => None,
169        };
170        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
171            return None;
172        }
173        if let Some(edge_key) = self.find_edge_key(from, to) {
174            if let Some(kind) = derived_kind {
175                if self.derived_output_id_is_retained(RelationKey::Surface(edge_key), kind) {
176                    return None;
177                }
178            }
179            // Existing edge: assert onto its payload. A real change (a new relation on the pair —
180            // a multiplicity bump a weighted signal reads) advances the revision.
181            let changed = {
182                let payload = self.inner.edge_mut(edge_key)?;
183                payload.assert_relation_with_context(
184                    assertion,
185                    Some(asserter_iri.clone()),
186                    asserted_at_ms,
187                )
188            };
189            if changed {
190                if let Some(kind) = derived_kind {
191                    self.normalize_derived_membership(RelationKey::Surface(edge_key), kind);
192                }
193                self.bump_revision();
194                return Some(RelationKey::Surface(edge_key));
195            }
196            return None;
197        }
198        if let Some(kind) = derived_kind {
199            if self.derived_output_id_is_retained_for_pair("surface", from, to, kind) {
200                return None;
201            }
202        }
203        let mut payload = EdgePayload::new();
204        if !payload.assert_relation_with_context(
205            assertion,
206            Some(asserter_iri.clone()),
207            asserted_at_ms,
208        ) {
209            return None;
210        }
211        let edge_key = self.inner.connect(from, to, payload);
212        if let Some(kind) = derived_kind {
213            self.normalize_derived_membership(RelationKey::Surface(edge_key), kind);
214        }
215        self.bump_revision();
216        Some(RelationKey::Surface(edge_key))
217    }
218
219    /// Derived containment is a rule output, not authored history. Its ID is
220    /// stable for this directed source bucket and its time remains undated.
221    fn normalize_derived_membership(&mut self, key: RelationKey, kind: RelationKind) {
222        let endpoints = match key {
223            RelationKey::Surface(key) => self.inner.inner().edge_endpoints(key).map(|(a, b)| {
224                (
225                    "surface",
226                    self.inner.node(a).unwrap().id,
227                    self.inner.node(b).unwrap().id,
228                )
229            }),
230            RelationKey::Resource(key) => {
231                self.resources
232                    .inner()
233                    .edge_endpoints(key.raw())
234                    .map(|(a, b)| {
235                        (
236                            "resource",
237                            self.resources.node(a).unwrap().id(),
238                            self.resources.node(b).unwrap().id(),
239                        )
240                    })
241            },
242        };
243        let Some((stratum, from, to)) = endpoints else {
244            return;
245        };
246        let id = derived_containment_statement_id(stratum, from, to, kind);
247        if self.find_semantic_statement(&id).is_some() {
248            return;
249        }
250        for statement in &mut self.get_relation_mut(key).unwrap().assertions.statements {
251            if !statement.is_held() || statement.relation_kind() != kind {
252                continue;
253            }
254            statement.statement_id = id.clone();
255            statement.provenance_iri = Some("urn:mere:rule:derived-containment:v1".into());
256            statement.first_asserted_ms = None;
257            statement.asserted_at_ms = None;
258            statement.basis = crate::types::AssertionBasis {
259                method: Some(crate::types::AssertionMethod {
260                    iri: "urn:mere:method:derived-containment".into(),
261                    version: Some("1".into()),
262                }),
263                ..Default::default()
264            };
265        }
266    }
267
268    fn derived_output_id_is_retained(&self, key: RelationKey, kind: RelationKind) -> bool {
269        let endpoints = match key {
270            RelationKey::Surface(key) => {
271                self.inner.inner().edge_endpoints(key).and_then(|(a, b)| {
272                    Some(("surface", self.inner.node(a)?.id, self.inner.node(b)?.id))
273                })
274            },
275            RelationKey::Resource(key) => self
276                .resources
277                .inner()
278                .edge_endpoints(key.raw())
279                .and_then(|(a, b)| {
280                    Some((
281                        "resource",
282                        self.resources.node(a)?.id(),
283                        self.resources.node(b)?.id(),
284                    ))
285                }),
286        };
287        endpoints.is_some_and(|(stratum, from, to)| {
288            self.derived_output_id_is_retained_for_identity(stratum, from, to, kind)
289        })
290    }
291
292    fn derived_output_id_is_retained_for_pair(
293        &self,
294        stratum: &str,
295        from_key: NodeKey,
296        to_key: NodeKey,
297        kind: RelationKind,
298    ) -> bool {
299        let (Some(from), Some(to)) = (self.get_node(from_key), self.get_node(to_key)) else {
300            return false;
301        };
302        let (from, to) = if stratum == "resource" {
303            let from_id = self
304                .shown_resource_id(from_key)
305                .unwrap_or_else(|| super::resource::ResourceNode::new(from.url()).id());
306            let to_id = self
307                .shown_resource_id(to_key)
308                .unwrap_or_else(|| super::resource::ResourceNode::new(to.url()).id());
309            (from_id, to_id)
310        } else {
311            (from.id, to.id)
312        };
313        self.derived_output_id_is_retained_for_identity(stratum, from, to, kind)
314    }
315
316    fn derived_output_id_is_retained_for_identity(
317        &self,
318        stratum: &str,
319        from: Uuid,
320        to: Uuid,
321        kind: RelationKind,
322    ) -> bool {
323        let id = derived_containment_statement_id(stratum, from, to, kind);
324        self.find_semantic_statement(&id).is_some()
325    }
326
327    pub(crate) fn assert_semantic_relation_in_scope(
328        &mut self,
329        from: NodeKey,
330        to: NodeKey,
331        sub_kind: SemanticSubKind,
332        label: Option<String>,
333        graph_scope: GraphScope,
334    ) -> Option<RelationKey> {
335        self.assert_semantic_statement(
336            from,
337            to,
338            SemanticStatementSpec {
339                predicate: super::predicate_iri(sub_kind).into(),
340                recognized_sub_kind: Some(sub_kind),
341                label,
342                graph_scope,
343                provenance_iri: Some(self.write_author().asserter_iri()),
344                asserted_at_ms: None,
345                basis: Default::default(),
346            },
347        )
348        .and_then(|(edge, outcome)| outcome.changed.then_some(edge))
349    }
350
351    /// Assert an **open predicate** semantic relation from `from` to `to`,
352    /// identified by an IRI rather than a closed [`SemanticSubKind`]. Creates the
353    /// pair-local edge bucket if absent and appends one open semantic statement to
354    /// it; an edge carrying only such a statement still reports the `Semantic`
355    /// family. Returns the edge, or `None` if either endpoint is missing or the
356    /// same open predicate statement already exists. Write path for raw web
357    /// predicates (linked-data ingest / knot `rel`s outside Mere's vocabulary).
358    pub(crate) fn assert_semantic_predicate(
359        &mut self,
360        from: NodeKey,
361        to: NodeKey,
362        predicate: String,
363    ) -> Option<RelationKey> {
364        self.assert_semantic_predicate_in_scope(from, to, predicate, GraphScope::Default)
365    }
366
367    pub(crate) fn assert_semantic_predicate_in_scope(
368        &mut self,
369        from: NodeKey,
370        to: NodeKey,
371        predicate: String,
372        graph_scope: GraphScope,
373    ) -> Option<RelationKey> {
374        self.assert_semantic_statement(
375            from,
376            to,
377            SemanticStatementSpec {
378                recognized_sub_kind: None,
379                predicate,
380                label: None,
381                graph_scope,
382                provenance_iri: Some(self.write_author().asserter_iri()),
383                asserted_at_ms: None,
384                basis: Default::default(),
385            },
386        )
387        .and_then(|(edge, outcome)| outcome.changed.then_some(edge))
388    }
389
390    /// Replay helper: add node only if UUID is not already present.
391    pub(crate) fn replay_add_node_with_id_if_missing(
392        &mut self,
393        id: Uuid,
394        url: String,
395        position: Point2D<f32>,
396    ) -> Option<NodeKey> {
397        let (key, inserted) = self.insert_node_if_missing(id, url, position);
398        inserted.then_some(key)
399    }
400
401    /// Replay helper: remove node by stable UUID.
402    pub(crate) fn replay_remove_node_by_id(&mut self, node_id: Uuid) -> bool {
403        let Some(key) = self.get_node_key_by_id(node_id) else {
404            return false;
405        };
406        self.remove_node(key)
407    }
408
409    pub(crate) fn replay_retract_relations_by_ids(
410        &mut self,
411        from_id: Uuid,
412        to_id: Uuid,
413        selector: RelationSelector,
414    ) -> usize {
415        let Some(from_key) = self.get_node_key_by_id(from_id) else {
416            return 0;
417        };
418        let Some(to_key) = self.get_node_key_by_id(to_id) else {
419            return 0;
420        };
421        if selector != RelationSelector::Family(super::EdgeFamily::Traversal) {
422            return self.replay_withdraw_selected(from_key, to_key, selector);
423        }
424        self.retract_surface_relations(from_key, to_key, selector)
425    }
426
427    pub(crate) fn replay_assert_relation_by_ids(
428        &mut self,
429        from_id: Uuid,
430        to_id: Uuid,
431        assertion: EdgeAssertion,
432    ) -> Option<RelationKey> {
433        let from_key = self.get_node_key_by_id(from_id)?;
434        let to_key = self.get_node_key_by_id(to_id)?;
435        self.replay_surface_relation_as(
436            from_key,
437            to_key,
438            assertion,
439            self.write_author().asserter_iri(),
440        )
441    }
442
443    pub(crate) fn replay_set_edge_semantic_predicate_by_ids(
444        &mut self,
445        from_id: Uuid,
446        to_id: Uuid,
447        predicate: Option<String>,
448    ) -> bool {
449        let Some(from_key) = self.get_node_key_by_id(from_id) else {
450            return false;
451        };
452        let Some(to_key) = self.get_node_key_by_id(to_id) else {
453            return false;
454        };
455        let Some(edge_key) = self.find_edge_key(from_key, to_key) else {
456            return false;
457        };
458        self.set_edge_semantic_predicate(edge_key, predicate)
459    }
460
461    pub(crate) fn replay_assert_semantic_predicate_by_ids(
462        &mut self,
463        from_id: Uuid,
464        to_id: Uuid,
465        predicate: String,
466        asserter_iri: String,
467    ) -> Option<RelationKey> {
468        let from_key = self.get_node_key_by_id(from_id)?;
469        let to_key = self.get_node_key_by_id(to_id)?;
470        if !self.inner.contains_node(from_key) || !self.inner.contains_node(to_key) {
471            return None;
472        }
473        let edge_key = self
474            .find_edge_key(from_key, to_key)
475            .unwrap_or_else(|| self.inner.connect(from_key, to_key, EdgePayload::new()));
476        let outcome =
477            self.inner
478                .edge_mut(edge_key)?
479                .assert_semantic_statement(SemanticStatementSpec {
480                    predicate,
481                    recognized_sub_kind: None,
482                    label: None,
483                    graph_scope: GraphScope::Default,
484                    provenance_iri: Some(asserter_iri),
485                    asserted_at_ms: None,
486                    basis: Default::default(),
487                });
488        if outcome.changed {
489            self.bump_revision();
490            self.capture_semantic_pair(from_key, to_key);
491        }
492        Some(RelationKey::Surface(edge_key))
493    }
494
495    pub(crate) fn replay_append_traversal_by_ids(
496        &mut self,
497        from_id: Uuid,
498        to_id: Uuid,
499        trigger: super::edge_taxonomy::NavigationTrigger,
500        timestamp_ms: u64,
501    ) -> bool {
502        let Some(from_key) = self.get_node_key_by_id(from_id) else {
503            return false;
504        };
505        let Some(to_key) = self.get_node_key_by_id(to_id) else {
506            return false;
507        };
508        self.append_traversal(from_key, to_key, trigger, Some(timestamp_ms))
509    }
510
511    /// Dissolve helper: collect traversals from all incident edges and remove the node.
512    pub(crate) fn dissolve_remove_node_collect_traversals(
513        &mut self,
514        key: NodeKey,
515    ) -> Option<Vec<DissolvedTraversalRecord>> {
516        let _ = self.get_node(key)?;
517
518        let mut records = Vec::new();
519        let inner = self.inner.inner();
520        for edge in inner
521            .edges_directed(key, Direction::Outgoing)
522            .chain(inner.edges_directed(key, Direction::Incoming))
523        {
524            if edge.weight().traversals().is_empty() {
525                continue;
526            }
527
528            let from_node = self.get_node(edge.source())?;
529            let to_node = self.get_node(edge.target())?;
530            records.push(DissolvedTraversalRecord {
531                from_node_id: from_node.id,
532                to_node_id: to_node.id,
533                traversals: edge.weight().traversals().to_vec(),
534            });
535        }
536
537        let _ = self.remove_node(key);
538        Some(records)
539    }
540
541    /// Collect traversals from all incident edges without mutating graph state.
542    pub fn collect_node_traversals(&self, key: NodeKey) -> Option<Vec<DissolvedTraversalRecord>> {
543        let _ = self.get_node(key)?;
544
545        let mut records = Vec::new();
546        let inner = self.inner.inner();
547        for edge in inner
548            .edges_directed(key, Direction::Outgoing)
549            .chain(inner.edges_directed(key, Direction::Incoming))
550        {
551            if edge.weight().traversals().is_empty() {
552                continue;
553            }
554
555            let from_node = self.get_node(edge.source())?;
556            let to_node = self.get_node(edge.target())?;
557            records.push(DissolvedTraversalRecord {
558                from_node_id: from_node.id,
559                to_node_id: to_node.id,
560                traversals: edge.weight().traversals().to_vec(),
561            });
562        }
563
564        Some(records)
565    }
566
567    /// Statement-aware assert (petgraph-RDF Phase 1 write API): assert one
568    /// semantic statement with full per-statement metadata on the `(from, to)`
569    /// pair bucket, creating the bucket edge if absent. Content-dedup returns
570    /// the EXISTING fact handle (updating its metadata in place); a genuine
571    /// change bumps the revision. This compatibility surface writer remains
572    /// during P2 integration; the checked counterpart uses durable placement.
573    pub fn assert_semantic_statement(
574        &mut self,
575        from: NodeKey,
576        to: NodeKey,
577        spec: SemanticStatementSpec,
578    ) -> Option<(RelationKey, StatementAssert)> {
579        self.try_assert_semantic_statement(from, to, spec).ok()
580    }
581
582    pub(crate) fn assert_surface_semantic_statement(
583        &mut self,
584        from: NodeKey,
585        to: NodeKey,
586        mut spec: SemanticStatementSpec,
587    ) -> Option<(RelationKey, StatementAssert)> {
588        spec = spec.normalized();
589        if spec.provenance_iri.is_none() {
590            spec.provenance_iri = Some(self.write_author().asserter_iri());
591        }
592        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
593            return None;
594        }
595        if let Some((key, existing)) = self
596            .find_edge_key(from, to)
597            .and_then(|key| self.inner.edge(key).map(|payload| (key, payload)))
598            .and_then(|(key, payload)| {
599                payload
600                    .assertions()
601                    .iter()
602                    .find(|statement| {
603                        statement.withdrawn.is_none()
604                            && statement.predicate == spec.predicate
605                            && statement.recognized_sub_kind == spec.recognized_sub_kind
606                            && statement.graph_scope == spec.graph_scope
607                            && statement.provenance_iri == spec.provenance_iri
608                            && statement.basis.same_reason_as(&spec.basis)
609                    })
610                    .map(|statement| (key, statement.statement_id.clone()))
611            })
612        {
613            let changed = self.update_assertion_metadata_if_requested(
614                &existing,
615                spec.label,
616                spec.asserted_at_ms,
617                Some(spec.basis),
618            );
619            return Some((
620                RelationKey::Surface(key),
621                StatementAssert {
622                    statement_id: existing,
623                    changed,
624                },
625            ));
626        }
627        spec.asserted_at_ms.get_or_insert_with(unix_epoch_millis);
628        let edge_key = self
629            .find_edge_key(from, to)
630            .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
631        let outcome = {
632            let payload = self.inner.edge_mut(edge_key)?;
633            payload.assert_semantic_statement(spec)
634        };
635        if outcome.changed {
636            self.bump_revision();
637            self.capture_semantic_pair(from, to);
638        }
639        Some((RelationKey::Surface(edge_key), outcome))
640    }
641
642    /// Historical replay path. Missing source time stays absent; replay never
643    /// stamps a wall clock into a prior journal prefix.
644    pub(crate) fn replay_surface_relation_as(
645        &mut self,
646        from: NodeKey,
647        to: NodeKey,
648        assertion: EdgeAssertion,
649        asserter_iri: String,
650    ) -> Option<RelationKey> {
651        if let EdgeAssertion::Semantic {
652            sub_kind,
653            label,
654        } = assertion
655        {
656            if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
657                return None;
658            }
659            let edge_key = self
660                .find_edge_key(from, to)
661                .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
662            let outcome =
663                self.inner
664                    .edge_mut(edge_key)?
665                    .assert_semantic_statement(SemanticStatementSpec {
666                        predicate: super::predicate_iri(sub_kind).into(),
667                        recognized_sub_kind: Some(sub_kind),
668                        label,
669                        graph_scope: GraphScope::Default,
670                        provenance_iri: Some(asserter_iri),
671                        asserted_at_ms: None,
672                        basis: Default::default(),
673                    });
674            if outcome.changed {
675                self.bump_revision();
676                self.capture_semantic_pair(from, to);
677            }
678            return Some(RelationKey::Surface(edge_key));
679        }
680        let before: std::collections::BTreeSet<_> = self
681            .edges_between_undirected(from, to)
682            .flat_map(|(_, payload)| payload.assertions())
683            .map(|s| s.statement_id.clone())
684            .collect();
685        let result = self.assert_surface_relation_as(from, to, assertion, asserter_iri, None);
686        if let Some(RelationKey::Surface(key)) = result {
687            let from_id = self.get_node(from)?.id;
688            let to_id = self.get_node(to)?.id;
689            let payload = self.inner.edge_mut(key)?;
690            let mut generations = std::collections::BTreeMap::<String, usize>::new();
691            for statement in &payload.assertions.statements {
692                if before.contains(&statement.statement_id) {
693                    *generations.entry(statement.predicate.clone()).or_default() += 1;
694                }
695            }
696            for statement in &mut payload.assertions.statements {
697                if !before.contains(&statement.statement_id)
698                    && !is_derived_containment(statement.relation_kind())
699                {
700                    let generation = *generations.get(&statement.predicate).unwrap_or(&0);
701                    let bytes = serde_json::to_vec(&(
702                        "mere.legacy-replay-assertion",
703                        1u8,
704                        "surface",
705                        from_id,
706                        to_id,
707                        &statement.predicate,
708                        generation,
709                    ))
710                    .expect("string tuple JSON");
711                    statement.statement_id =
712                        Uuid::new_v5(&Uuid::NAMESPACE_URL, &bytes).urn().to_string();
713                }
714            }
715        }
716        result
717    }
718
719    /// Assert a semantic statement whose id is ALREADY minted — the re-ingest /
720    /// round-trip path (a reifier carried the fact handle, and preserving it is
721    /// what makes `RDF -> kernel -> RDF` id-stable). Reasserting the same
722    /// asserter updates its existing handle; endpoints must exist. The checked
723    /// counterpart supplies declaration-aware placement and collision errors.
724    pub fn assert_persisted_semantic_statement(
725        &mut self,
726        from: NodeKey,
727        to: NodeKey,
728        statement: SemanticStatement,
729    ) -> Option<RelationKey> {
730        self.try_assert_persisted_semantic_statement(from, to, statement)
731            .ok()
732    }
733
734    pub(crate) fn assert_surface_persisted_semantic_statement(
735        &mut self,
736        from: NodeKey,
737        to: NodeKey,
738        mut statement: SemanticStatement,
739    ) -> Option<RelationKey> {
740        if statement.provenance_iri.is_none() {
741            statement.provenance_iri = Some(self.write_author().asserter_iri());
742        }
743        if !self.inner.contains_node(from) || !self.inner.contains_node(to) {
744            return None;
745        }
746        let edge_key = self
747            .find_edge_key(from, to)
748            .unwrap_or_else(|| self.inner.connect(from, to, EdgePayload::new()));
749        let changed = {
750            let payload = self.inner.edge_mut(edge_key)?;
751            payload.upsert_persisted_semantic_statement(statement)
752        };
753        if changed {
754            self.bump_revision();
755            self.capture_semantic_pair(from, to);
756        }
757        Some(RelationKey::Surface(edge_key))
758    }
759
760    /// Compatibility spelling for an authored exact-ID withdrawal. The
761    /// assertion remains as a tombstone in its original pair bucket.
762    pub fn retract_semantic_statement(
763        &mut self,
764        _from: NodeKey,
765        _to: NodeKey,
766        statement_id: &str,
767    ) -> bool {
768        self.withdraw_semantic_assertion(statement_id, None, None)
769    }
770
771    /// Keep assertion ids and metadata exact through journal replay and undo.
772    pub(crate) fn capture_semantic_pair(&self, from: NodeKey, to: NodeKey) {
773        let (Some(from_node), Some(to_node)) = (self.get_node(from), self.get_node(to)) else {
774            return;
775        };
776        self.record_delta(&super::capture::CapturedDelta::ReplaySetEdgesByIds {
777            from_id: from_node.id.to_string(),
778            to_id: to_node.id.to_string(),
779            edges: self.persisted_edges_between(from, to),
780        });
781    }
782
783    pub(crate) fn retract_relations(
784        &mut self,
785        from: NodeKey,
786        to: NodeKey,
787        selector: RelationSelector,
788    ) -> usize {
789        self.retract_relations_where(from, to, selector, |_| true)
790            .withdrawn
791    }
792
793    /// [`retract_relations`](Self::retract_relations) that asks `allow` about
794    /// each statement before withdrawing it, across both strata of the pair.
795    /// A refused statement stays held and is counted in [`Retraction::refused`].
796    /// Traversal history holds no statements, so `allow` is not consulted for
797    /// that family.
798    pub fn retract_relations_where(
799        &mut self,
800        from: NodeKey,
801        to: NodeKey,
802        selector: RelationSelector,
803        mut allow: impl FnMut(&SemanticStatement) -> bool,
804    ) -> Retraction {
805        if selector == RelationSelector::Family(super::EdgeFamily::Traversal) {
806            return Retraction {
807                withdrawn: self.retract_traversals(from, to, selector),
808                refused: 0,
809            };
810        }
811        self.withdraw_selected_semantic_assertions(from, to, selector, true, &mut allow)
812    }
813
814    fn retract_traversals(
815        &mut self,
816        from: NodeKey,
817        to: NodeKey,
818        selector: RelationSelector,
819    ) -> usize {
820        let mut removed = self.retract_surface_relations(from, to, selector);
821        if removed > 0 {
822            self.capture_semantic_pair(from, to);
823        }
824        let Some((source, target)) = self.shown_resource_id(from).zip(self.shown_resource_id(to))
825        else {
826            return removed;
827        };
828        let keys: Vec<_> = self
829            .resource_relations()
830            .filter(|(_, a, b, payload)| {
831                (*a, *b) == (source, target) && payload.has_relation(selector)
832            })
833            .map(|(key, _, _, _)| key)
834            .collect();
835        let mut resource_removed = 0;
836        for key in keys {
837            let payload = self
838                .resources
839                .edge_mut(key.raw())
840                .expect("resource relation");
841            if payload.retract_relation(selector) {
842                resource_removed += 1;
843                if payload.is_empty() {
844                    self.resources.disconnect(key.raw());
845                }
846            }
847        }
848        if resource_removed > 0 {
849            self.bump_revision();
850            self.capture_resource_pair(source, target);
851            removed += resource_removed;
852        }
853        removed
854    }
855
856    /// Historical selector replay retains an undated tombstone instead of
857    /// stamping replay time. Exact journal pair snapshots remain the primary
858    /// replay form; this covers legacy selector deltas only.
859    pub(crate) fn replay_retract_relations(
860        &mut self,
861        from: NodeKey,
862        to: NodeKey,
863        selector: RelationSelector,
864    ) -> usize {
865        if selector != RelationSelector::Family(super::EdgeFamily::Traversal) {
866            return self.replay_withdraw_selected(from, to, selector);
867        }
868        self.retract_relations(from, to, selector)
869    }
870
871    /// Replay withdrawal of every held statement `selector` names between the
872    /// pair: undated, and never refused.
873    fn replay_withdraw_selected(
874        &mut self,
875        from: NodeKey,
876        to: NodeKey,
877        selector: RelationSelector,
878    ) -> usize {
879        self.withdraw_selected_semantic_assertions(from, to, selector, false, &mut |_| true)
880            .withdrawn
881    }
882
883    fn withdraw_selected_semantic_assertions(
884        &mut self,
885        from: NodeKey,
886        to: NodeKey,
887        selector: RelationSelector,
888        authored: bool,
889        allow: &mut dyn FnMut(&SemanticStatement) -> bool,
890    ) -> Retraction {
891        let matches_selector = |statement: &SemanticStatement| {
892            super::edge_payload::selector_matches_kind(selector, statement.relation_kind())
893        };
894        let mut found = self
895            .inner
896            .inner()
897            .edges_connecting(from, to)
898            .flat_map(|edge| edge.weight().held_assertions())
899            .filter(|statement| matches_selector(statement))
900            .cloned()
901            .collect::<Vec<_>>();
902        if authored
903            && let Some((source, target)) =
904                self.shown_resource_id(from).zip(self.shown_resource_id(to))
905        {
906            found.extend(
907                self.resource_relations()
908                    .filter(|(_, a, b, _)| (*a, *b) == (source, target))
909                    .flat_map(|(_, _, _, payload)| payload.held_assertions())
910                    .filter(|statement| matches_selector(statement))
911                    .cloned(),
912            );
913        }
914        found.sort_by(|a, b| a.statement_id.cmp(&b.statement_id));
915        found.dedup_by(|a, b| a.statement_id == b.statement_id);
916        let (allowed, refused): (Vec<_>, Vec<_>) =
917            found.into_iter().partition(|statement| allow(statement));
918        let withdrawn = allowed
919            .iter()
920            .filter(|statement| {
921                let id = &statement.statement_id;
922                if authored {
923                    self.withdraw_semantic_assertion(id, None, None)
924                } else {
925                    let author = self.write_author().asserter_iri();
926                    self.apply_imported_semantic_withdrawal(id, None, Some(author))
927                }
928            })
929            .count();
930        Retraction {
931            withdrawn,
932            refused: refused.len(),
933        }
934    }
935
936    fn retract_surface_relations(
937        &mut self,
938        from: NodeKey,
939        to: NodeKey,
940        selector: RelationSelector,
941    ) -> usize {
942        let edge_ids: Vec<EdgeKey> = self
943            .inner
944            .inner()
945            .edge_references()
946            .filter(|edge| {
947                edge.source() == from && edge.target() == to && edge.weight().has_relation(selector)
948            })
949            .map(|edge| edge.id())
950            .collect();
951
952        let mut removed = 0usize;
953        let mut edges_to_delete = Vec::new();
954        for edge_id in edge_ids {
955            if let Some(payload) = self.inner.edge_mut(edge_id)
956                && payload.retract_relation(selector)
957            {
958                removed += 1;
959                if payload.is_empty() {
960                    edges_to_delete.push(edge_id);
961                }
962            }
963        }
964        for edge_id in edges_to_delete {
965            let _ = self.inner.disconnect(edge_id);
966        }
967        if removed > 0 {
968            self.bump_revision();
969        }
970        removed
971    }
972
973    /// Replace every relation from `from` to `to` with `edges`, given in
974    /// persisted form, or with none. Exact replay and undo retain each carried
975    /// row, rather than merging parallel payloads through the legacy loader.
976    pub(crate) fn set_edges_between(
977        &mut self,
978        from: NodeKey,
979        to: NodeKey,
980        edges: &[PersistedEdge],
981    ) {
982        let existing: Vec<EdgeKey> = self
983            .inner
984            .inner()
985            .edges_connecting(from, to)
986            .map(|edge| edge.id())
987            .collect();
988        for key in existing {
989            let _ = self.inner.disconnect(key);
990        }
991        // Pair iteration visits the newest edge first, so insert in reverse
992        // order to preserve the exact capture's row order.
993        for (ordinal, edge) in edges.iter().enumerate().rev() {
994            let mut payload = super::snapshot::payload_from_persisted_at(
995                edge,
996                super::GraphStratum::Surface,
997                ordinal,
998            );
999            {
1000                let semantic = &mut payload.assertions;
1001                for statement in &mut semantic.statements {
1002                    statement.normalize_legacy_asserter();
1003                }
1004            }
1005            if !payload.is_empty() || edge.semantic.is_some() || edge.traversal.is_some() {
1006                self.inner.connect(from, to, payload);
1007            }
1008        }
1009        self.bump_revision();
1010    }
1011
1012    /// Get a mutable edge payload by key.
1013    pub(crate) fn get_edge_mut(&mut self, key: EdgeKey) -> Option<&mut EdgePayload> {
1014        self.inner.edge_mut(key)
1015    }
1016
1017    /// Legacy replay only: set the aggregate predicate on an existing edge.
1018    /// Live corrections retract one statement and assert its replacement.
1019    pub(crate) fn set_edge_semantic_predicate(
1020        &mut self,
1021        key: EdgeKey,
1022        predicate: Option<String>,
1023    ) -> bool {
1024        self.set_edge_semantic_predicate_as(key, predicate, self.write_author().asserter_iri())
1025    }
1026
1027    /// Legacy replay only, with the old record's attribution envelope.
1028    pub(crate) fn set_edge_semantic_predicate_as(
1029        &mut self,
1030        key: EdgeKey,
1031        predicate: Option<String>,
1032        asserter: String,
1033    ) -> bool {
1034        let Some(payload) = self.inner.edge_mut(key) else {
1035            return false;
1036        };
1037        let before = payload.clone();
1038        payload.set_semantic_predicate(predicate);
1039        {
1040            let semantic = &mut payload.assertions;
1041            for statement in &mut semantic.statements {
1042                if statement.provenance_iri.is_none() {
1043                    statement.provenance_iri = Some(asserter.clone());
1044                }
1045            }
1046        }
1047        if *payload != before {
1048            self.bump_revision();
1049        }
1050        true
1051    }
1052
1053    /// Get an edge payload by key.
1054    pub fn get_edge(&self, key: EdgeKey) -> Option<&EdgePayload> {
1055        self.inner.edge(key)
1056    }
1057
1058    /// Find the first directed edge key between two nodes.
1059    pub fn find_edge_key(&self, from: NodeKey, to: NodeKey) -> Option<EdgeKey> {
1060        self.inner.inner().find_edge(from, to)
1061    }
1062
1063    /// Every edge between `a` and `b` in either direction: all `a->b`
1064    /// edges first, then all `b->a` edges, each run in petgraph's
1065    /// `edges_connecting` order (deterministic for a given graph). The
1066    /// substrate is a multigraph, so a pair may carry an antiparallel
1067    /// or parallel set; read predicates that mean "the pair" rather
1068    /// than "the first arc" go through here instead of
1069    /// [`Self::find_edge_key`]. Self-loops (`a == b`) are yielded once.
1070    pub fn edges_between_undirected(
1071        &self,
1072        a: NodeKey,
1073        b: NodeKey,
1074    ) -> impl Iterator<Item = (EdgeKey, &EdgePayload)> + '_ {
1075        use petgraph::visit::EdgeRef;
1076        let inner = self.inner.inner();
1077        let forward = inner.edges_connecting(a, b);
1078        let backward = inner.edges_connecting(b, a).filter(move |_| a != b);
1079        forward
1080            .chain(backward)
1081            .map(|edge| (edge.id(), edge.weight()))
1082    }
1083
1084    /// Append a traversal event to an existing edge, or create an edge carrying the traversal.
1085    pub(crate) fn push_traversal(
1086        &mut self,
1087        from: NodeKey,
1088        to: NodeKey,
1089        traversal: Traversal,
1090    ) -> bool {
1091        if from == to || !self.inner.contains_node(from) || !self.inner.contains_node(to) {
1092            return false;
1093        }
1094        if let Some(edge_key) = self.find_edge_key(from, to)
1095            && let Some(payload) = self.inner.edge_mut(edge_key)
1096        {
1097            // Existing edge: a re-visit appends a traversal but does not change the structure, so
1098            // the revision holds (navigation re-visits must not churn the structural caches).
1099            payload.push_traversal(traversal);
1100            return true;
1101        }
1102        let mut payload = EdgePayload::new();
1103        payload.push_traversal(traversal);
1104        let _ = self.inner.connect(from, to, payload);
1105        self.bump_revision();
1106        true
1107    }
1108
1109    /// Append a traversal event by `(trigger, timestamp_ms?)`.
1110    /// Thin wrapper over [`Self::push_traversal`] matching the
1111    /// 2026-05-11 relation-taxonomy plan §7 signature — callers
1112    /// that just have a `NavigationTrigger` don't need to build a
1113    /// `Traversal` struct themselves. `timestamp_ms = None` stamps
1114    /// now-via-`Traversal::now`; `Some(t)` uses the supplied
1115    /// timestamp (importers, replay).
1116    pub(crate) fn append_traversal(
1117        &mut self,
1118        from: NodeKey,
1119        to: NodeKey,
1120        trigger: super::edge_taxonomy::NavigationTrigger,
1121        timestamp_ms: Option<u64>,
1122    ) -> bool {
1123        let traversal = match timestamp_ms {
1124            Some(timestamp_ms) => Traversal {
1125                timestamp_ms,
1126                trigger,
1127            },
1128            None => Traversal::now(trigger),
1129        };
1130        self.push_traversal(from, to, traversal)
1131    }
1132}
1133
1134fn derived_containment_statement_id(
1135    stratum: &str,
1136    from: Uuid,
1137    to: Uuid,
1138    kind: RelationKind,
1139) -> String {
1140    let predicate = kind
1141        .predicate_iri()
1142        .expect("derived containment has a canonical predicate");
1143    let bytes = serde_json::to_vec(&(
1144        "mere.derived-containment",
1145        1u8,
1146        stratum,
1147        from,
1148        to,
1149        predicate,
1150    ))
1151    .expect("derived containment identity is serializable");
1152    Uuid::new_v5(&Uuid::NAMESPACE_URL, &bytes).urn().to_string()
1153}
1154
1155#[cfg(test)]
1156mod legacy_predicate_revision_tests {
1157    use super::*;
1158
1159    fn fixture(asserter: Option<&str>) -> (Graph, NodeKey, NodeKey, EdgeKey) {
1160        let mut graph = Graph::new();
1161        let from = graph.add_node("https://source.test/".into(), Point2D::zero());
1162        let to = graph.add_node("https://target.test/".into(), Point2D::zero());
1163        let mut payload = EdgePayload::new();
1164        payload.push_persisted_semantic_statement(SemanticStatement {
1165            statement_id: "carried legacy handle".into(),
1166            predicate: "https://predicate.test/before".into(),
1167            recognized_sub_kind: None,
1168            label: Some("held label".into()),
1169            graph_scope: GraphScope::User,
1170            provenance_iri: asserter.map(str::to_owned),
1171            asserted_at_ms: Some(17),
1172            first_asserted_ms: Some(17),
1173            withdrawn: None,
1174            basis: Default::default(),
1175        });
1176        let edge = graph.inner.connect(from, to, payload);
1177        (graph, from, to, edge)
1178    }
1179
1180    #[test]
1181    fn legacy_predicate_replay_advances_revision_only_for_changed_payload() {
1182        use super::super::apply::{GraphDelta, GraphDeltaResult, apply_graph_delta};
1183
1184        let (mut graph, from, to, edge) = fixture(Some("https://author.test/"));
1185        let original = graph.get_edge(edge).unwrap().semantic_statements()[0].clone();
1186        let from_id = graph.get_node(from).unwrap().id;
1187        let to_id = graph.get_node(to).unwrap().id;
1188        let delta = GraphDelta::ReplaySetEdgeSemanticPredicateByIds {
1189            from_id,
1190            to_id,
1191            predicate: Some("https://predicate.test/after".into()),
1192            asserter_iri: "https://other-author.test/".into(),
1193        };
1194        let before_revision = graph.revision();
1195        assert!(matches!(
1196            apply_graph_delta(&mut graph, delta.clone()),
1197            GraphDeltaResult::NodeMetadataUpdated(true)
1198        ));
1199        assert_eq!(graph.revision(), before_revision + 1);
1200        let mut expected = original;
1201        expected.predicate = "https://predicate.test/after".into();
1202        assert_eq!(
1203            graph.get_edge(edge).unwrap().semantic_statements(),
1204            &[expected]
1205        );
1206
1207        let edited = graph.get_edge(edge).unwrap().clone();
1208        let edited_revision = graph.revision();
1209        assert!(matches!(
1210            apply_graph_delta(&mut graph, delta),
1211            GraphDeltaResult::NodeMetadataUpdated(true)
1212        ));
1213        assert_eq!(graph.get_edge(edge), Some(&edited));
1214        assert_eq!(
1215            graph.revision(),
1216            edited_revision,
1217            "same input remains a no-op"
1218        );
1219
1220        assert!(graph.set_edge_semantic_predicate_as(edge, None, "unused".into()));
1221        let payload = graph.get_edge(edge).unwrap();
1222        assert!(payload.held_assertions().next().is_none());
1223        assert_eq!(payload.semantic_statements().len(), 1);
1224        assert!(payload.semantic_statements()[0].withdrawn.is_some());
1225        assert_eq!(graph.revision(), edited_revision + 1);
1226        let cleared_revision = graph.revision();
1227        assert!(graph.set_edge_semantic_predicate_as(edge, None, "unused".into()));
1228        assert_eq!(graph.revision(), cleared_revision);
1229        assert!(!graph.set_edge_semantic_predicate_as(EdgeKey::new(1_000), None, "unused".into()));
1230        assert_eq!(graph.revision(), cleared_revision);
1231    }
1232
1233    #[test]
1234    fn legacy_predicate_attribution_repair_alone_advances_revision() {
1235        let (mut graph, _, _, edge) = fixture(None);
1236        let original = graph.get_edge(edge).unwrap().semantic_statements()[0].clone();
1237        let before_revision = graph.revision();
1238        assert!(graph.set_edge_semantic_predicate_as(
1239            edge,
1240            Some(original.predicate.clone()),
1241            "https://author.test/".into()
1242        ));
1243        let mut expected = original;
1244        expected.provenance_iri = Some("https://author.test/".into());
1245        assert_eq!(
1246            graph.get_edge(edge).unwrap().semantic_statements(),
1247            &[expected]
1248        );
1249        assert_eq!(graph.revision(), before_revision + 1);
1250        let repaired = graph.get_edge(edge).unwrap().clone();
1251        let repaired_revision = graph.revision();
1252        assert!(graph.set_edge_semantic_predicate_as(
1253            edge,
1254            Some("https://predicate.test/before".into()),
1255            "https://other-author.test/".into()
1256        ));
1257        assert_eq!(graph.get_edge(edge), Some(&repaired));
1258        assert_eq!(
1259            graph.revision(),
1260            repaired_revision,
1261            "existing attribution stays exact"
1262        );
1263    }
1264}
1265
1266fn is_derived_containment(kind: RelationKind) -> bool {
1267    matches!(
1268        kind,
1269        RelationKind::Containment(
1270            super::ContainmentSubKind::UrlPath | super::ContainmentSubKind::Domain
1271        )
1272    )
1273}