Skip to main content

kernel/graph/
edge_payload.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//! One assertion list per directed bucket, plus the traversal event rollup.
8//!
9//! The four former structural sidecars are compatibility projections. Their
10//! predicates now carry the same exact identity and lifecycle as semantic facts.
11
12use super::edge_data::{
13    ArrangementData, AssertionData, ContainmentData, EdgeMetrics, ImportedData, ProvenanceData,
14    SemanticData, SemanticStatement, SemanticStatementSpec, StatementAssert, Traversal,
15    TraversalData, UNKNOWN_LEGACY_ASSERTER_IRI, predicate_iri,
16};
17use super::edge_taxonomy::{
18    ArrangementSubKind, EdgeAssertion, EdgeFamily, RelationKind, RelationSelector, SemanticSubKind,
19};
20use crate::types::{AssertionWithdrawal, GraphScope};
21use rkyv::{Archive, Deserialize, Serialize};
22use std::collections::BTreeSet;
23
24/// Borrowed semantic compatibility projection, never another assertion store.
25pub struct SemanticDataView<'a> {
26    pub sub_kinds: &'a BTreeSet<SemanticSubKind>,
27    pub label: &'a Option<String>,
28    pub predicate: &'a Option<String>,
29    pub statements: &'a [SemanticStatement],
30}
31
32#[derive(
33    Debug,
34    Clone,
35    PartialEq,
36    Eq,
37    Archive,
38    Serialize,
39    Deserialize,
40    serde::Serialize,
41    serde::Deserialize,
42)]
43pub struct EdgePayload {
44    /// All retained assertions, including withdrawal tombstones. The legacy
45    /// `SemanticData` name is a source compatibility alias for the record store.
46    pub assertions: AssertionData,
47    pub traversal: Option<TraversalData>,
48}
49
50pub fn selector_matches_kind(selector: RelationSelector, kind: RelationKind) -> bool {
51    match selector {
52        RelationSelector::Family(family) => family == kind.family(),
53        RelationSelector::Semantic(value) => kind == RelationKind::Semantic(value),
54        RelationSelector::Containment(value) => kind == RelationKind::Containment(value),
55        RelationSelector::Arrangement(value) => kind == RelationKind::Arrangement(value),
56        RelationSelector::Imported(value) => kind == RelationKind::Imported(value),
57        RelationSelector::Provenance(value) => kind == RelationKind::Provenance(value),
58    }
59}
60
61impl<'a> SemanticDataView<'a> {
62    pub fn statements(&self) -> &'a [SemanticStatement] {
63        self.statements
64    }
65}
66
67impl EdgePayload {
68    pub fn new() -> Self {
69        Self {
70            assertions: SemanticData::default(),
71            traversal: None,
72        }
73    }
74
75    pub fn assertions(&self) -> &[SemanticStatement] {
76        &self.assertions.statements
77    }
78
79    pub fn held_assertions(&self) -> impl Iterator<Item = &SemanticStatement> {
80        self.assertions()
81            .iter()
82            .filter(|statement| statement.is_held())
83    }
84
85    pub fn semantic_statements(&self) -> &[SemanticStatement] {
86        let count = self
87            .assertions()
88            .partition_point(SemanticStatement::is_semantic);
89        &self.assertions()[..count]
90    }
91
92    pub fn held_semantic_statements(&self) -> impl Iterator<Item = &SemanticStatement> {
93        self.semantic_statements()
94            .iter()
95            .filter(|statement| statement.is_held())
96    }
97
98    pub fn semantic_data(&self) -> Option<SemanticDataView<'_>> {
99        (!self.semantic_statements().is_empty()).then(|| SemanticDataView {
100            sub_kinds: &self.assertions.sub_kinds,
101            label: &self.assertions.label,
102            predicate: &self.assertions.predicate,
103            statements: self.semantic_statements(),
104        })
105    }
106
107    pub fn has_relation(&self, selector: RelationSelector) -> bool {
108        if selector == RelationSelector::Family(EdgeFamily::Traversal) {
109            return self.traversal.is_some();
110        }
111        self.held_assertions()
112            .any(|statement| selector_matches_kind(selector, statement.relation_kind()))
113    }
114
115    /// Legacy membership ensure. A caller who has an independent reason uses
116    /// the statement-aware Graph writer and its exact returned assertion ID.
117    pub fn assert_relation(&mut self, assertion: EdgeAssertion) -> bool {
118        self.assert_relation_with_context(assertion, None, None)
119    }
120
121    pub(crate) fn assert_relation_with_context(
122        &mut self,
123        assertion: EdgeAssertion,
124        asserter: Option<String>,
125        at_ms: Option<u64>,
126    ) -> bool {
127        let (kind, label) = match assertion {
128            EdgeAssertion::Semantic {
129                sub_kind, label, ..
130            } => (RelationKind::Semantic(sub_kind), label),
131            EdgeAssertion::Containment { sub_kind } => (RelationKind::Containment(sub_kind), None),
132            EdgeAssertion::Arrangement { sub_kind } => (RelationKind::Arrangement(sub_kind), None),
133            EdgeAssertion::Imported { sub_kind } => (RelationKind::Imported(sub_kind), None),
134            EdgeAssertion::Provenance { sub_kind } => (RelationKind::Provenance(sub_kind), None),
135        };
136        if kind.family() != EdgeFamily::Semantic
137            && self.held_assertions().any(|s| s.relation_kind() == kind)
138        {
139            return false;
140        }
141        self.assertions
142            .assert_statement(SemanticStatementSpec {
143                predicate: kind
144                    .predicate_iri()
145                    .expect("asserted kind has a predicate")
146                    .into(),
147                recognized_sub_kind: match kind {
148                    RelationKind::Semantic(k) => Some(k),
149                    _ => None,
150                },
151                label,
152                provenance_iri: asserter.or_else(|| Some(UNKNOWN_LEGACY_ASSERTER_IRI.into())),
153                asserted_at_ms: at_ms,
154                ..Default::default()
155            })
156            .changed
157    }
158
159    /// Physical removal remains reserved for regeneration, migration and
160    /// compaction. Authored withdrawals use Graph's exact-ID lifecycle writer.
161    pub(crate) fn retract_relation(&mut self, selector: RelationSelector) -> bool {
162        if selector == RelationSelector::Family(EdgeFamily::Traversal) {
163            return self.traversal.take().is_some();
164        }
165        let before = self.assertions().len();
166        self.assertions
167            .statements
168            .retain(|s| !s.is_held() || !selector_matches_kind(selector, s.relation_kind()));
169        if self.assertions().len() == before {
170            return false;
171        }
172        self.assertions.rebuild_compat();
173        true
174    }
175
176    pub fn is_empty(&self) -> bool {
177        self.assertions().is_empty() && self.traversal.is_none()
178    }
179    pub fn label(&self) -> Option<&str> {
180        self.assertions.label.as_deref()
181    }
182
183    pub(crate) fn assert_semantic_predicate(&mut self, predicate: String) -> bool {
184        self.assert_semantic_predicate_in_scope(predicate, GraphScope::Default)
185    }
186    pub(crate) fn assert_semantic_relation_in_scope(
187        &mut self,
188        sub_kind: SemanticSubKind,
189        label: Option<String>,
190        scope: GraphScope,
191    ) -> bool {
192        self.assertions.insert_statement(
193            Some(sub_kind),
194            predicate_iri(sub_kind).into(),
195            label,
196            scope,
197            None,
198            None,
199        )
200    }
201    pub(crate) fn assert_semantic_predicate_in_scope(
202        &mut self,
203        predicate: String,
204        scope: GraphScope,
205    ) -> bool {
206        self.assertions
207            .insert_statement(None, predicate, None, scope, None, None)
208    }
209    pub(crate) fn assert_semantic_statement(
210        &mut self,
211        spec: SemanticStatementSpec,
212    ) -> StatementAssert {
213        self.assertions.assert_statement(spec)
214    }
215    pub(crate) fn withdraw_semantic_statement(
216        &mut self,
217        id: &str,
218        withdrawal: AssertionWithdrawal,
219    ) -> bool {
220        self.assertions.withdraw_statement(id, withdrawal)
221    }
222    pub(crate) fn compact_semantic_statement(&mut self, id: &str) -> bool {
223        self.assertions.compact_statement(id)
224    }
225    pub(crate) fn upsert_persisted_semantic_statement(
226        &mut self,
227        statement: SemanticStatement,
228    ) -> bool {
229        self.assertions.upsert_persisted_statement(statement)
230    }
231    pub(crate) fn push_persisted_semantic_statement(
232        &mut self,
233        statement: SemanticStatement,
234    ) -> bool {
235        self.assertions.push_persisted_statement(statement)
236    }
237    pub fn set_semantic_predicate(&mut self, predicate: Option<String>) {
238        self.assertions.set_statement_predicate(predicate);
239    }
240
241    pub fn traversal_data(&self) -> Option<&TraversalData> {
242        self.traversal.as_ref()
243    }
244    pub fn arrangement_data(&self) -> Option<ArrangementData> {
245        let sub_kinds = self
246            .held_assertions()
247            .filter_map(|s| match s.relation_kind() {
248                RelationKind::Arrangement(k) => Some(k),
249                _ => None,
250            })
251            .collect::<BTreeSet<_>>();
252        (!sub_kinds.is_empty()).then_some(ArrangementData { sub_kinds })
253    }
254    pub fn containment_data(&self) -> Option<ContainmentData> {
255        let sub_kinds = self
256            .held_assertions()
257            .filter_map(|s| match s.relation_kind() {
258                RelationKind::Containment(k) => Some(k),
259                _ => None,
260            })
261            .collect::<BTreeSet<_>>();
262        (!sub_kinds.is_empty()).then_some(ContainmentData { sub_kinds })
263    }
264    pub fn imported_data(&self) -> Option<ImportedData> {
265        let sub_kinds = self
266            .held_assertions()
267            .filter_map(|s| match s.relation_kind() {
268                RelationKind::Imported(k) => Some(k),
269                _ => None,
270            })
271            .collect::<BTreeSet<_>>();
272        (!sub_kinds.is_empty()).then_some(ImportedData { sub_kinds })
273    }
274    pub fn provenance_data(&self) -> Option<ProvenanceData> {
275        let sub_kinds = self
276            .held_assertions()
277            .filter_map(|s| match s.relation_kind() {
278                RelationKind::Provenance(k) => Some(k),
279                _ => None,
280            })
281            .collect::<BTreeSet<_>>();
282        (!sub_kinds.is_empty()).then_some(ProvenanceData { sub_kinds })
283    }
284    pub fn has_arrangement_sub_kind(&self, kind: ArrangementSubKind) -> bool {
285        self.has_relation(RelationSelector::Arrangement(kind))
286    }
287    pub fn has_durable_arrangement_relation(&self) -> bool {
288        self.arrangement_data()
289            .is_some_and(|data| data.has_durable_relation())
290    }
291    pub fn has_session_arrangement_relation(&self) -> bool {
292        self.arrangement_data()
293            .is_some_and(|data| data.has_session_relation())
294    }
295    pub fn traversals(&self) -> &[Traversal] {
296        self.traversal
297            .as_ref()
298            .map(|data| data.traversals.as_slice())
299            .unwrap_or(&[])
300    }
301    pub fn metrics(&self) -> EdgeMetrics {
302        self.traversal
303            .as_ref()
304            .map(|data| data.metrics)
305            .unwrap_or_default()
306    }
307    pub fn push_traversal(&mut self, traversal: Traversal) {
308        self.traversal
309            .get_or_insert_with(TraversalData::default)
310            .push(traversal);
311    }
312    pub fn families(&self) -> BTreeSet<EdgeFamily> {
313        let mut families = self
314            .held_assertions()
315            .map(|s| s.relation_kind().family())
316            .collect::<BTreeSet<_>>();
317        if self.traversal.is_some() {
318            families.insert(EdgeFamily::Traversal);
319        }
320        families
321    }
322    pub fn has_held_topology(&self) -> bool {
323        self.traversal.is_some() || self.held_assertions().next().is_some()
324    }
325}
326
327impl Default for EdgePayload {
328    fn default() -> Self {
329        Self::new()
330    }
331}