Skip to main content

kernel/graph/
coverage.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//! Known limits of the supplied graph, not a claim of world completeness.
8
9use super::{Graph, ResourceNode};
10use serde::{Deserialize, Serialize};
11use uuid::Uuid;
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
14#[serde(rename_all = "snake_case")]
15pub enum CoverageLayer {
16    Possession,
17    Residency,
18    Disclosure,
19    Synchronization,
20    Projection,
21}
22
23impl CoverageLayer {
24    pub const ALL: [Self; 5] = [
25        Self::Possession,
26        Self::Residency,
27        Self::Disclosure,
28        Self::Synchronization,
29        Self::Projection,
30    ];
31}
32
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
34pub struct CoverageLimit {
35    pub layer: CoverageLayer,
36    pub reason: String,
37    /// Empty scope means the entire supplied graph. Hosts own these observations.
38    #[serde(default)]
39    pub resources: Vec<Uuid>,
40    /// Surface scope; empty scopes together mean the supplied graph.
41    #[serde(default, skip_serializing_if = "Vec::is_empty")]
42    pub surfaces: Vec<Uuid>,
43    /// None means the number beyond this boundary is unknown.
44    #[serde(default)]
45    pub count: Option<usize>,
46}
47
48impl CoverageLimit {
49    pub fn new(layer: CoverageLayer, reason: impl Into<String>) -> Self {
50        Self {
51            layer,
52            reason: reason.into(),
53            resources: vec![],
54            surfaces: vec![],
55            count: None,
56        }
57    }
58}
59
60/// An empty note means no known limit within this supplied graph.
61/// It never means all relevant data exists here or anywhere else.
62#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
63pub struct CoverageNote {
64    pub limits: Vec<CoverageLimit>,
65}
66
67impl CoverageNote {
68    pub fn push(&mut self, limit: CoverageLimit) {
69        if !self.limits.contains(&limit) {
70            self.limits.push(limit);
71        }
72    }
73    pub fn add_count(&mut self, layer: CoverageLayer, reason: impl Into<String>, count: usize) {
74        if count == 0 {
75            return;
76        }
77        let mut limit = CoverageLimit::new(layer, reason);
78        limit.count = Some(count);
79        self.push(limit);
80    }
81}
82
83impl Graph {
84    pub fn known_coverage(&self) -> &CoverageNote {
85        &self.known_coverage
86    }
87
88    /// Runtime host context, never graph truth, a journal edit or a geometry key.
89    pub fn set_known_coverage(&mut self, note: CoverageNote) {
90        if self.known_coverage != note {
91            self.known_coverage = note;
92            self.semantic_observation_revision += 1;
93        }
94    }
95
96    pub fn coverage_note(&self) -> CoverageNote {
97        let mut note = self.known_coverage.clone();
98        let mut unavailable = 0;
99        let mut unasserted = 0;
100        for link in self.pending_links() {
101            let missing: Vec<_> = [
102                link.source_resource,
103                ResourceNode::new(&link.target_iri).id(),
104            ]
105            .into_iter()
106            .filter(|id| self.resource(*id).is_none())
107            .collect();
108            if missing.is_empty() {
109                unasserted += 1;
110                continue;
111            }
112            if missing.iter().any(|id| {
113                !self.known_coverage.limits.iter().any(|limit| {
114                    limit.layer == CoverageLayer::Residency
115                        && ((limit.resources.is_empty() && limit.surfaces.is_empty())
116                            || limit.resources.contains(id))
117                })
118            }) {
119                unavailable += 1;
120            }
121        }
122        // Aggregate counts carry no private target IRIs or derived target ids.
123        note.add_count(
124            CoverageLayer::Possession,
125            "pending source claims have unavailable endpoints",
126            unavailable,
127        );
128        note.add_count(
129            CoverageLayer::Possession,
130            "pending source claims await assertion placement",
131            unasserted,
132        );
133        note
134    }
135
136    /// Coverage for explicit portable references, without inventing absent records.
137    pub fn coverage_for_resource_refs(&self, references: &[Uuid]) -> CoverageNote {
138        let mut note = self.coverage_note();
139        let missing: std::collections::BTreeSet<_> = references
140            .iter()
141            .copied()
142            .filter(|id| self.resource(*id).is_none())
143            .filter(|id| {
144                !self.known_coverage.limits.iter().any(|limit| {
145                    limit.layer == CoverageLayer::Residency
146                        && ((limit.resources.is_empty() && limit.surfaces.is_empty())
147                            || limit.resources.contains(id))
148                })
149            })
150            .collect();
151        if !missing.is_empty() {
152            let mut limit = CoverageLimit::new(
153                CoverageLayer::Possession,
154                "referenced resources are unavailable",
155            );
156            limit.count = Some(missing.len());
157            limit.resources = missing.into_iter().collect();
158            note.push(limit);
159        }
160        note
161    }
162
163    pub fn copy_semantic_context_from(&mut self, graph: &Self) {
164        self.restore_pending_link_state(graph.pending_link_state.clone());
165        self.set_known_coverage(graph.known_coverage.clone());
166    }
167
168    /// History starts from truth only, never an ambient extraction input.
169    pub fn clear_semantic_context(&mut self) {
170        self.restore_pending_link_state(Default::default());
171        self.set_known_coverage(Default::default());
172    }
173}
174
175#[cfg(test)]
176mod residency_scope_tests {
177    use super::*;
178    #[test]
179    fn surface_scope_does_not_hide_absent_resources() {
180        let mut graph = Graph::new();
181        let mut limit = CoverageLimit::new(CoverageLayer::Residency, "surface unloaded");
182        limit.surfaces.push(Uuid::from_u128(1));
183        graph.set_known_coverage(CoverageNote {
184            limits: vec![limit.clone()],
185        });
186        let unknown = Uuid::from_u128(2);
187        assert!(
188            graph
189                .coverage_for_resource_refs(&[unknown])
190                .limits
191                .iter()
192                .any(|l| l.layer == CoverageLayer::Possession)
193        );
194        limit.resources.push(unknown);
195        graph.set_known_coverage(CoverageNote {
196            limits: vec![limit.clone()],
197        });
198        assert!(
199            !graph
200                .coverage_for_resource_refs(&[unknown])
201                .limits
202                .iter()
203                .any(|l| l.layer == CoverageLayer::Possession)
204        );
205        limit.surfaces.clear();
206        limit.resources.clear();
207        assert!(
208            serde_json::to_value(&limit)
209                .unwrap()
210                .get("surfaces")
211                .is_none()
212        );
213        graph.set_known_coverage(CoverageNote {
214            limits: vec![limit],
215        });
216        assert!(
217            !graph
218                .coverage_for_resource_refs(&[unknown])
219                .limits
220                .iter()
221                .any(|l| l.layer == CoverageLayer::Possession)
222        );
223    }
224}