Skip to main content

kernel/graph/
resource_classifications.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//! Complete classification variants, retained origins and exact review edits.
8
9use super::resource_content::{ContentError, RESOURCE_CLASSIFICATIONS};
10use super::{Author, Graph, NodeKey};
11use crate::types::{ClassificationScheme, ClassificationStatus, NodeClassification};
12use serde::{Deserialize, Serialize};
13use uuid::Uuid;
14
15#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
16pub struct ClassificationOrigin {
17    pub surface_id: Uuid,
18    pub author: Option<Author>,
19    pub uncertainty: Option<String>,
20}
21
22#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
23pub struct ClassificationVariant {
24    pub variant_id: String,
25    /// Original record identity shared by divergent review versions.
26    #[serde(default, skip_serializing_if = "Option::is_none")]
27    pub original_variant_id: Option<String>,
28    pub classification: NodeClassification,
29    pub origins: Vec<ClassificationOrigin>,
30}
31
32pub(crate) fn validate_variants(variants: &[ClassificationVariant]) -> Result<(), ContentError> {
33    let mut ids = std::collections::BTreeMap::new();
34    for variant in variants {
35        if let Some(previous) = ids.insert(&variant.variant_id, variant)
36            && previous != variant
37        {
38            return Err(ContentError::InvalidFacet(format!(
39                "conflicting classification ID {:?}",
40                variant.variant_id
41            )));
42        }
43    }
44    Ok(())
45}
46
47/// Union exact variants and origins. Differing records for one logical key remain separate.
48pub fn merge_classification_variants(
49    left: &[ClassificationVariant],
50    right: &[ClassificationVariant],
51) -> Result<Vec<ClassificationVariant>, ContentError> {
52    // Two replicas may carry divergent review versions under the original ID.
53    // Admission requires normalized unique IDs; composition expands the versions.
54    let mut lineage = std::collections::BTreeMap::new();
55    for variant in left.iter().chain(right) {
56        let root = variant
57            .original_variant_id
58            .as_ref()
59            .unwrap_or(&variant.variant_id);
60        if let Some(previous) = lineage.insert(&variant.variant_id, root)
61            && previous != root
62        {
63            return Err(ContentError::InvalidFacet(
64                "conflicting classification lineage".into(),
65            ));
66        }
67    }
68    let mut groups = std::collections::BTreeMap::<
69        String,
70        std::collections::BTreeMap<String, ClassificationVariant>,
71    >::new();
72    for variant in left.iter().chain(right) {
73        let original = variant
74            .original_variant_id
75            .as_ref()
76            .unwrap_or(&variant.variant_id)
77            .clone();
78        let payload = serde_json::to_string(&variant.classification)
79            .map_err(|e| ContentError::InvalidFacet(e.to_string()))?;
80        let versions = groups.entry(original).or_default();
81        if let Some(existing) = versions.get_mut(&payload) {
82            for origin in &variant.origins {
83                if !existing.origins.contains(origin) {
84                    existing.origins.push(origin.clone());
85                }
86            }
87            if variant.original_variant_id.is_some() {
88                existing.original_variant_id = variant.original_variant_id.clone();
89            }
90        } else {
91            versions.insert(payload, variant.clone());
92        }
93    }
94    let mut merged = Vec::new();
95    for (original, versions) in groups {
96        let diverged = versions.len() > 1;
97        for (payload, mut version) in versions {
98            if diverged || version.original_variant_id.is_some() {
99                let key =
100                    serde_json::to_vec(&(&original, &payload)).expect("version key serializes");
101                version.variant_id = format!(
102                    "classification-version:{}",
103                    Uuid::new_v5(&Uuid::NAMESPACE_URL, &key)
104                );
105                version.original_variant_id = Some(original.clone());
106            }
107            version
108                .origins
109                .sort_by_key(|origin| serde_json::to_string(origin).expect("origin serializes"));
110            version.origins.dedup();
111            merged.push(version);
112        }
113    }
114    merged.sort_by(|a, b| a.variant_id.cmp(&b.variant_id));
115    Ok(merged)
116}
117
118impl Graph {
119    pub fn resource_classification_variants(&self, id: Uuid) -> Vec<ClassificationVariant> {
120        self.resource_content(id, RESOURCE_CLASSIFICATIONS)
121            .unwrap_or_default()
122    }
123
124    pub fn resource_classifications_conflicted(&self, id: Uuid) -> bool {
125        let variants = self.resource_classification_variants(id);
126        variants.iter().enumerate().any(|(index, left)| {
127            variants[index + 1..].iter().any(|right| {
128                left.classification.scheme == right.classification.scheme
129                    && left.classification.value == right.classification.value
130                    && left.classification != right.classification
131            })
132        })
133    }
134
135    pub(crate) fn add_shown_classifications(
136        &mut self,
137        key: NodeKey,
138        incoming: Vec<NodeClassification>,
139    ) -> bool {
140        if incoming.is_empty() {
141            return false;
142        }
143        let Some(surface_id) = self.get_node(key).map(|node| node.id) else {
144            return false;
145        };
146        let Some(id) = self.ensure_surface_resource(key) else {
147            return false;
148        };
149        let origin = ClassificationOrigin {
150            surface_id,
151            author: Some(self.write_author().clone()),
152            uncertainty: None,
153        };
154        let mut variants = self.resource_classification_variants(id);
155        for classification in incoming {
156            if let Some(existing) = variants
157                .iter_mut()
158                .find(|entry| entry.classification == classification)
159            {
160                if !existing.origins.contains(&origin) {
161                    existing.origins.push(origin.clone());
162                }
163            } else {
164                variants.push(ClassificationVariant {
165                    variant_id: Uuid::new_v4().to_string(),
166                    original_variant_id: None,
167                    classification,
168                    origins: vec![origin.clone()],
169                });
170            }
171        }
172        self.write_resource_content(id, RESOURCE_CLASSIFICATIONS, &variants)
173            .unwrap_or(false)
174    }
175
176    pub fn edit_resource_classification(
177        &mut self,
178        id: Uuid,
179        variant_id: &str,
180        status: Option<ClassificationStatus>,
181        primary: Option<bool>,
182    ) -> Result<bool, ContentError> {
183        let mut variants = self.resource_classification_variants(id);
184        let index = variants
185            .iter()
186            .position(|entry| entry.variant_id == variant_id)
187            .ok_or_else(|| ContentError::MissingClassification(variant_id.into()))?;
188        if let Some(status) = status {
189            variants[index].classification.status = status;
190        }
191        if let Some(primary) = primary {
192            let scheme = variants[index].classification.scheme.clone();
193            if primary {
194                for entry in &mut variants {
195                    if entry.classification.scheme == scheme {
196                        entry.classification.primary = false;
197                    }
198                }
199            }
200            variants[index].classification.primary = primary;
201        }
202        self.write_resource_content(id, RESOURCE_CLASSIFICATIONS, &variants)
203    }
204
205    pub fn remove_resource_classification(
206        &mut self,
207        id: Uuid,
208        variant_id: &str,
209    ) -> Result<bool, ContentError> {
210        let mut variants = self.resource_classification_variants(id);
211        let before = variants.len();
212        variants.retain(|entry| entry.variant_id != variant_id);
213        if before == variants.len() {
214            return Ok(false);
215        }
216        self.write_resource_content(id, RESOURCE_CLASSIFICATIONS, &variants)
217    }
218
219    pub(crate) fn unique_shown_classification(
220        &self,
221        key: NodeKey,
222        scheme: &ClassificationScheme,
223        value: &str,
224    ) -> Result<Option<(Uuid, String)>, ContentError> {
225        let Some(id) = self.shown_resource_id(key) else {
226            return Ok(None);
227        };
228        let matches: Vec<_> = self
229            .resource_classification_variants(id)
230            .into_iter()
231            .filter(|entry| {
232                entry.classification.scheme == *scheme && entry.classification.value == value
233            })
234            .collect();
235        match matches.len() {
236            0 => Ok(None),
237            1 => Ok(Some((id, matches[0].variant_id.clone()))),
238            _ => Err(ContentError::AmbiguousClassification(
239                matches.into_iter().map(|entry| entry.variant_id).collect(),
240            )),
241        }
242    }
243}