Skip to main content

kernel/graph/
edge_payload.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! `EdgePayload` — the structural + temporal payload carried on every
5//! graph edge. Composes the taxonomy types from
6//! [`super::edge_taxonomy`] into a single payload struct whose
7//! **typed sidecars are authoritative**: `EdgeFamily` is derived from
8//! which sidecars are populated, not from a parallel index set.
9//!
10//! Per the 2026-05-11 relation-taxonomy plan stage 4: the legacy
11//! `kinds: BTreeSet<EdgeKind>` cache and `families: BTreeSet<EdgeFamily>`
12//! field are gone. [`Self::families`] returns a freshly-computed set
13//! over the sidecars on each call; reads go through [`Self::has_relation`]
14//! with a [`RelationSelector`] discriminant.
15
16use std::collections::BTreeSet;
17
18use rkyv::{Archive, Deserialize, Serialize};
19
20use crate::types::GraphScope;
21
22use super::edge_data::{
23    ArrangementData, ContainmentData, EdgeMetrics, ImportedData, ProvenanceData, SemanticData,
24    SemanticStatement, SemanticStatementSpec, StatementAssert, Traversal, TraversalData,
25    predicate_iri,
26};
27use super::edge_taxonomy::{
28    ArrangementSubKind, EdgeAssertion, EdgeFamily, RelationSelector, SemanticSubKind,
29};
30
31/// Edge semantics payload: structural assertions + temporal traversal events.
32#[derive(Debug, Clone, PartialEq, Eq, Archive, Serialize, Deserialize)]
33pub struct EdgePayload {
34    pub semantic: Option<SemanticData>,
35    pub traversal: Option<TraversalData>,
36    pub arrangement: Option<ArrangementData>,
37    pub containment: Option<ContainmentData>,
38    pub imported: Option<ImportedData>,
39    pub provenance: Option<ProvenanceData>,
40}
41
42impl EdgePayload {
43    pub fn new() -> Self {
44        Self {
45            semantic: None,
46            traversal: None,
47            arrangement: None,
48            containment: None,
49            imported: None,
50            provenance: None,
51        }
52    }
53
54    fn insert_semantic_relation(
55        &mut self,
56        sub_kind: SemanticSubKind,
57        label: Option<String>,
58    ) -> bool {
59        self.insert_semantic_relation_in_scope(sub_kind, label, GraphScope::Default)
60    }
61
62    fn insert_semantic_relation_in_scope(
63        &mut self,
64        sub_kind: SemanticSubKind,
65        label: Option<String>,
66        graph_scope: GraphScope,
67    ) -> bool {
68        let data = self.semantic.get_or_insert_with(SemanticData::default);
69        data.insert_statement(
70            Some(sub_kind),
71            predicate_iri(sub_kind).to_string(),
72            label,
73            graph_scope,
74            None,
75            None,
76        )
77    }
78
79    fn remove_semantic_relation(&mut self, sub_kind: SemanticSubKind) -> bool {
80        let Some(data) = self.semantic.as_mut() else {
81            return false;
82        };
83        if !data.remove_statements_with_sub_kind(sub_kind) {
84            return false;
85        }
86        if data.statements().is_empty() {
87            self.semantic = None;
88        }
89        true
90    }
91
92    /// Write-side relation assertion. Returns `true` when the payload
93    /// changed (new sub-kind inserted, or label refreshed).
94    pub fn assert_relation(&mut self, assertion: EdgeAssertion) -> bool {
95        match assertion {
96            EdgeAssertion::Semantic {
97                sub_kind, label, ..
98            } => self.insert_semantic_relation(sub_kind, label),
99            EdgeAssertion::Containment { sub_kind } => self
100                .containment
101                .get_or_insert_with(ContainmentData::default)
102                .insert(sub_kind),
103            EdgeAssertion::Arrangement { sub_kind } => self
104                .arrangement
105                .get_or_insert_with(ArrangementData::default)
106                .insert(sub_kind),
107            EdgeAssertion::Imported { sub_kind } => self
108                .imported
109                .get_or_insert_with(ImportedData::default)
110                .sub_kinds
111                .insert(sub_kind),
112            EdgeAssertion::Provenance { sub_kind } => self
113                .provenance
114                .get_or_insert_with(ProvenanceData::default)
115                .sub_kinds
116                .insert(sub_kind),
117        }
118    }
119
120    pub fn has_relation(&self, selector: RelationSelector) -> bool {
121        match selector {
122            RelationSelector::Family(family) => self.has_family(family),
123            RelationSelector::Semantic(sub_kind) => self
124                .semantic
125                .as_ref()
126                .is_some_and(|data| data.sub_kinds.contains(&sub_kind)),
127            RelationSelector::Containment(sub_kind) => self
128                .containment
129                .as_ref()
130                .is_some_and(|data| data.contains(sub_kind)),
131            RelationSelector::Arrangement(sub_kind) => self
132                .arrangement
133                .as_ref()
134                .is_some_and(|data| data.contains(sub_kind)),
135            RelationSelector::Imported(sub_kind) => self
136                .imported
137                .as_ref()
138                .is_some_and(|data| data.sub_kinds.contains(&sub_kind)),
139            RelationSelector::Provenance(sub_kind) => self
140                .provenance
141                .as_ref()
142                .is_some_and(|data| data.sub_kinds.contains(&sub_kind)),
143        }
144    }
145
146    pub fn retract_relation(&mut self, selector: RelationSelector) -> bool {
147        match selector {
148            RelationSelector::Family(EdgeFamily::Traversal) => self.traversal.take().is_some(),
149            RelationSelector::Family(_) => false,
150            RelationSelector::Semantic(sub_kind) => self.remove_semantic_relation(sub_kind),
151            RelationSelector::Containment(sub_kind) => {
152                let Some(data) = self.containment.as_mut() else {
153                    return false;
154                };
155                if !data.remove(sub_kind) {
156                    return false;
157                }
158                if data.is_empty() {
159                    self.containment = None;
160                }
161                true
162            }
163            RelationSelector::Arrangement(sub_kind) => {
164                let Some(data) = self.arrangement.as_mut() else {
165                    return false;
166                };
167                if !data.remove(sub_kind) {
168                    return false;
169                }
170                if data.is_empty() {
171                    self.arrangement = None;
172                }
173                true
174            }
175            RelationSelector::Imported(sub_kind) => {
176                let Some(data) = self.imported.as_mut() else {
177                    return false;
178                };
179                if !data.sub_kinds.remove(&sub_kind) {
180                    return false;
181                }
182                if data.sub_kinds.is_empty() {
183                    self.imported = None;
184                }
185                true
186            }
187            RelationSelector::Provenance(sub_kind) => {
188                let Some(data) = self.provenance.as_mut() else {
189                    return false;
190                };
191                if !data.sub_kinds.remove(&sub_kind) {
192                    return false;
193                }
194                if data.sub_kinds.is_empty() {
195                    self.provenance = None;
196                }
197                true
198            }
199        }
200    }
201
202    fn has_family(&self, family: EdgeFamily) -> bool {
203        match family {
204            EdgeFamily::Semantic => self.semantic.as_ref().is_some_and(|data| {
205                !data.statements().is_empty()
206                    || !data.sub_kinds.is_empty()
207                    || data.predicate.is_some()
208            }),
209            EdgeFamily::Traversal => self.traversal.is_some(),
210            EdgeFamily::Containment => self
211                .containment
212                .as_ref()
213                .is_some_and(|data| !data.is_empty()),
214            EdgeFamily::Arrangement => self
215                .arrangement
216                .as_ref()
217                .is_some_and(|data| !data.is_empty()),
218            EdgeFamily::Imported => self
219                .imported
220                .as_ref()
221                .is_some_and(|data| !data.sub_kinds.is_empty()),
222            EdgeFamily::Provenance => self
223                .provenance
224                .as_ref()
225                .is_some_and(|data| !data.sub_kinds.is_empty()),
226        }
227    }
228
229    pub fn is_empty(&self) -> bool {
230        !self.has_family(EdgeFamily::Semantic)
231            && self.traversal.is_none()
232            && !self.has_family(EdgeFamily::Containment)
233            && !self.has_family(EdgeFamily::Arrangement)
234            && !self.has_family(EdgeFamily::Imported)
235            && !self.has_family(EdgeFamily::Provenance)
236    }
237
238    pub fn label(&self) -> Option<&str> {
239        self.semantic
240            .as_ref()
241            .and_then(|data| data.label.as_deref())
242    }
243
244    pub fn semantic_data(&self) -> Option<&SemanticData> {
245        self.semantic.as_ref()
246    }
247
248    pub fn semantic_statements(&self) -> &[SemanticStatement] {
249        self.semantic
250            .as_ref()
251            .map(SemanticData::statements)
252            .unwrap_or(&[])
253    }
254
255    pub(crate) fn assert_semantic_predicate(&mut self, predicate: String) -> bool {
256        self.assert_semantic_predicate_in_scope(predicate, GraphScope::Default)
257    }
258
259    pub(crate) fn assert_semantic_relation_in_scope(
260        &mut self,
261        sub_kind: SemanticSubKind,
262        label: Option<String>,
263        graph_scope: GraphScope,
264    ) -> bool {
265        self.insert_semantic_relation_in_scope(sub_kind, label, graph_scope)
266    }
267
268    pub(crate) fn assert_semantic_predicate_in_scope(
269        &mut self,
270        predicate: String,
271        graph_scope: GraphScope,
272    ) -> bool {
273        self.semantic
274            .get_or_insert_with(SemanticData::default)
275            .insert_statement(None, predicate, None, graph_scope, None, None)
276    }
277
278    /// Statement-aware assert on this pair bucket (creates the semantic
279    /// sidecar if absent). Returns the fact handle + whether anything changed.
280    pub(crate) fn assert_semantic_statement(
281        &mut self,
282        spec: SemanticStatementSpec,
283    ) -> StatementAssert {
284        self.semantic
285            .get_or_insert_with(SemanticData::default)
286            .assert_statement(spec)
287    }
288
289    /// Precise retract by fact handle. Clears the semantic sidecar when its
290    /// last statement goes (the caller removes the petgraph edge when the
291    /// whole payload empties, same as `retract_relation`).
292    pub(crate) fn retract_semantic_statement(&mut self, statement_id: &str) -> bool {
293        let Some(data) = self.semantic.as_mut() else {
294            return false;
295        };
296        if !data.retract_statement(statement_id) {
297            return false;
298        }
299        if data.statements().is_empty() {
300            self.semantic = None;
301        }
302        true
303    }
304
305    pub(crate) fn push_persisted_semantic_statement(
306        &mut self,
307        statement: SemanticStatement,
308    ) -> bool {
309        self.semantic
310            .get_or_insert_with(SemanticData::default)
311            .push_persisted_statement(statement)
312    }
313
314    /// Set (or clear) the open predicate IRI on the semantic sidecar, creating
315    /// the sidecar if needed. The predicate is independent of `sub_kinds`: a
316    /// recognized edge carries both; a raw web predicate may carry only this.
317    pub fn set_semantic_predicate(&mut self, predicate: Option<String>) {
318        if predicate.is_none() && self.semantic.is_none() {
319            return;
320        }
321        if let Some(data) = self.semantic.as_mut() {
322            data.set_statement_predicate(predicate);
323            if data.statements().is_empty() {
324                self.semantic = None;
325            }
326            return;
327        }
328        let mut data = SemanticData::default();
329        data.set_statement_predicate(predicate);
330        if !data.statements().is_empty() {
331            self.semantic = Some(data);
332        }
333    }
334
335    pub fn traversal_data(&self) -> Option<&TraversalData> {
336        self.traversal.as_ref()
337    }
338
339    pub fn arrangement_data(&self) -> Option<&ArrangementData> {
340        self.arrangement.as_ref()
341    }
342
343    pub fn containment_data(&self) -> Option<&ContainmentData> {
344        self.containment.as_ref()
345    }
346
347    pub fn imported_data(&self) -> Option<&ImportedData> {
348        self.imported.as_ref()
349    }
350
351    pub fn provenance_data(&self) -> Option<&ProvenanceData> {
352        self.provenance.as_ref()
353    }
354
355    pub fn has_arrangement_sub_kind(&self, sub_kind: ArrangementSubKind) -> bool {
356        self.arrangement
357            .as_ref()
358            .is_some_and(|data| data.contains(sub_kind))
359    }
360
361    pub fn has_durable_arrangement_relation(&self) -> bool {
362        self.arrangement
363            .as_ref()
364            .is_some_and(ArrangementData::has_durable_relation)
365    }
366
367    pub fn has_session_arrangement_relation(&self) -> bool {
368        self.arrangement
369            .as_ref()
370            .is_some_and(ArrangementData::has_session_relation)
371    }
372
373    pub fn traversals(&self) -> &[Traversal] {
374        self.traversal
375            .as_ref()
376            .map(|data| data.traversals.as_slice())
377            .unwrap_or(&[])
378    }
379
380    pub fn metrics(&self) -> EdgeMetrics {
381        self.traversal
382            .as_ref()
383            .map(|data| data.metrics)
384            .unwrap_or_default()
385    }
386
387    pub fn push_traversal(&mut self, traversal: Traversal) {
388        self.traversal
389            .get_or_insert_with(TraversalData::default)
390            .push(traversal);
391    }
392
393    /// Compute the set of [`EdgeFamily`] tags carried by this payload
394    /// from the populated sidecars. Materialized fresh on each call —
395    /// there is no parallel cache.
396    pub fn families(&self) -> BTreeSet<EdgeFamily> {
397        let mut out = BTreeSet::new();
398        if self.has_family(EdgeFamily::Semantic) {
399            out.insert(EdgeFamily::Semantic);
400        }
401        if self.has_family(EdgeFamily::Traversal) {
402            out.insert(EdgeFamily::Traversal);
403        }
404        if self.has_family(EdgeFamily::Containment) {
405            out.insert(EdgeFamily::Containment);
406        }
407        if self.has_family(EdgeFamily::Arrangement) {
408            out.insert(EdgeFamily::Arrangement);
409        }
410        if self.has_family(EdgeFamily::Imported) {
411            out.insert(EdgeFamily::Imported);
412        }
413        if self.has_family(EdgeFamily::Provenance) {
414            out.insert(EdgeFamily::Provenance);
415        }
416        out
417    }
418}
419
420impl Default for EdgePayload {
421    fn default() -> Self {
422        Self::new()
423    }
424}