Skip to main content

kernel/graph/
import_records.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//! Import-record operations.
8//!
9//! Manages the durable `import_records` truth on `Graph`: queries,
10//! membership suppression, replacement, and the projection of the table
11//! onto per-node `NodeImportProvenance` facets
12//! (`sync_node_import_provenance_from_records`).
13//!
14//! The table owns memberships and their suppression. The per-node facet
15//! is a projection that omits suppressed memberships, so nothing here
16//! rebuilds the table from it. `set_node_import_provenance` edits that
17//! node's memberships in the table; a snapshot that predates the table
18//! derives it from the legacy persisted column
19//! (`import_records_from_legacy_provenance`).
20//!
21//! Extracted from `graph/mod.rs` per the 2026-05-11 kernel
22//! decomposition pass.
23
24use std::collections::{BTreeMap, HashMap};
25
26use uuid::Uuid;
27
28use super::identity::NodeKey;
29use super::{Graph, current_unix_timestamp_secs, normalize_import_records};
30use crate::types::{
31    ImportRecord, ImportRecordMembership, NodeImportProvenance, NodeImportRecordSummary,
32};
33
34impl Graph {
35    pub fn import_records(&self) -> &[ImportRecord] {
36        &self.import_records
37    }
38
39    pub fn import_record_summaries_for_node(&self, key: NodeKey) -> Vec<NodeImportRecordSummary> {
40        let Some(node) = self.get_node(key) else {
41            return Vec::new();
42        };
43        let node_id = node.id.to_string();
44        let mut summaries = self
45            .import_records
46            .iter()
47            .filter(|record| {
48                record
49                    .memberships
50                    .iter()
51                    .any(|membership| membership.node_id == node_id && !membership.suppressed)
52            })
53            .map(|record| NodeImportRecordSummary {
54                record_id: record.record_id.clone(),
55                source_id: record.source_id.clone(),
56                source_label: record.source_label.clone(),
57                imported_at_secs: record.imported_at_secs,
58            })
59            .collect::<Vec<_>>();
60        summaries.sort_by(|left, right| {
61            right
62                .imported_at_secs
63                .cmp(&left.imported_at_secs)
64                .then_with(|| left.source_label.cmp(&right.source_label))
65                .then_with(|| left.record_id.cmp(&right.record_id))
66        });
67        summaries
68    }
69
70    pub fn import_record_member_keys(&self, record_id: &str) -> Vec<NodeKey> {
71        let mut member_keys = self
72            .import_records
73            .iter()
74            .find(|record| record.record_id == record_id)
75            .into_iter()
76            .flat_map(|record| record.memberships.iter())
77            .filter(|membership| !membership.suppressed)
78            .filter_map(|membership| Uuid::parse_str(&membership.node_id).ok())
79            .filter_map(|node_id| self.inner.key_of(&node_id))
80            .collect::<Vec<_>>();
81        member_keys.sort_by_key(|key| key.index());
82        member_keys.dedup();
83        member_keys
84    }
85
86    pub(crate) fn delete_import_record(&mut self, record_id: &str) -> bool {
87        let original_len = self.import_records.len();
88        self.import_records
89            .retain(|record| record.record_id != record_id);
90        if self.import_records.len() == original_len {
91            return false;
92        }
93        self.sync_node_import_provenance_from_records();
94        true
95    }
96
97    pub(crate) fn set_import_record_membership_suppressed(
98        &mut self,
99        record_id: &str,
100        key: NodeKey,
101        suppressed: bool,
102    ) -> bool {
103        let Some(node_id) = self.get_node(key).map(|node| node.id.to_string()) else {
104            return false;
105        };
106        let mut changed = false;
107        for record in &mut self.import_records {
108            if record.record_id != record_id {
109                continue;
110            }
111            for membership in &mut record.memberships {
112                if membership.node_id == node_id {
113                    if membership.suppressed != suppressed {
114                        membership.suppressed = suppressed;
115                        changed = true;
116                    }
117                    break;
118                }
119            }
120        }
121        if changed {
122            self.sync_node_import_provenance_from_records();
123        }
124        changed
125    }
126
127    pub(crate) fn set_import_records(&mut self, mut import_records: Vec<ImportRecord>) -> bool {
128        normalize_import_records(&mut import_records);
129        if self.import_records == import_records {
130            return false;
131        }
132        self.import_records = import_records;
133        self.sync_node_import_provenance_from_records();
134        true
135    }
136
137    pub(crate) fn sync_node_import_provenance_from_records(&mut self) {
138        let mut provenance_by_node = HashMap::<NodeKey, Vec<NodeImportProvenance>>::new();
139        for record in &self.import_records {
140            for membership in record
141                .memberships
142                .iter()
143                .filter(|membership| !membership.suppressed)
144            {
145                let Ok(node_id) = Uuid::parse_str(&membership.node_id) else {
146                    continue;
147                };
148                let Some(node_key) = self.inner.key_of(&node_id) else {
149                    continue;
150                };
151                provenance_by_node
152                    .entry(node_key)
153                    .or_default()
154                    .push(NodeImportProvenance {
155                        source_id: record.source_id.clone(),
156                        source_label: record.source_label.clone(),
157                    });
158            }
159        }
160
161        let node_keys = self.inner.inner().node_indices().collect::<Vec<_>>();
162        for node_key in node_keys {
163            let mut provenance = provenance_by_node.remove(&node_key).unwrap_or_default();
164            provenance.sort();
165            provenance.dedup();
166            self.set_node_facet(node_key, super::node_facets::PROVENANCE_IMPORT, &provenance);
167        }
168    }
169
170    /// Make `key`'s active provenance exactly `import_provenance`, touching
171    /// only that node's memberships. Other nodes and every suppressed
172    /// membership stay as the table has them.
173    pub(crate) fn set_node_import_provenance(
174        &mut self,
175        key: NodeKey,
176        import_provenance: Vec<NodeImportProvenance>,
177    ) -> bool {
178        let Some(node_id) = self.get_node(key).map(|node| node.id.to_string()) else {
179            return false;
180        };
181        let mut wanted = import_provenance;
182        wanted.sort();
183        wanted.dedup();
184        if active_provenance(&self.import_records, &node_id) == wanted {
185            return false;
186        }
187        let mut records = std::mem::take(&mut self.import_records);
188        assign_node_memberships(
189            &mut records,
190            &node_id,
191            &wanted,
192            current_unix_timestamp_secs(),
193        );
194        normalize_import_records(&mut records);
195        self.import_records = records;
196        let projected = active_provenance(&self.import_records, &node_id);
197        self.set_node_facet(key, super::node_facets::PROVENANCE_IMPORT, &projected);
198        true
199    }
200}
201
202fn is_source(record: &ImportRecord, source: &NodeImportProvenance) -> bool {
203    record.source_id == source.source_id && record.source_label == source.source_label
204}
205
206/// What the table projects onto a node: its unsuppressed memberships' sources.
207fn active_provenance(records: &[ImportRecord], node_id: &str) -> Vec<NodeImportProvenance> {
208    let mut provenance = records
209        .iter()
210        .filter(|record| {
211            record
212                .memberships
213                .iter()
214                .any(|membership| membership.node_id == node_id && !membership.suppressed)
215        })
216        .map(|record| NodeImportProvenance {
217            source_id: record.source_id.clone(),
218            source_label: record.source_label.clone(),
219        })
220        .collect::<Vec<_>>();
221    provenance.sort();
222    provenance.dedup();
223    provenance
224}
225
226/// Edit `node_id`'s memberships so its active sources are exactly `wanted`.
227/// A source the node lacks goes to the latest record of that source (an
228/// existing membership is un-suppressed), or to a new record if none exists.
229/// The node's suppressed memberships in other sources are left alone.
230fn assign_node_memberships(
231    records: &mut Vec<ImportRecord>,
232    node_id: &str,
233    wanted: &[NodeImportProvenance],
234    imported_at_secs: u64,
235) {
236    for record in records.iter_mut() {
237        if !wanted.iter().any(|source| is_source(record, source)) {
238            record
239                .memberships
240                .retain(|membership| membership.node_id != node_id || membership.suppressed);
241        }
242    }
243    records.retain(|record| !record.memberships.is_empty());
244    let active = active_provenance(records, node_id);
245    for source in wanted.iter().filter(|source| !active.contains(source)) {
246        let Some(record) = records
247            .iter_mut()
248            .rev()
249            .find(|record| is_source(record, source))
250        else {
251            records.push(ImportRecord {
252                record_id: format!("import-record:{}", source.source_id),
253                source_id: source.source_id.clone(),
254                source_label: source.source_label.clone(),
255                imported_at_secs,
256                memberships: vec![ImportRecordMembership {
257                    node_id: node_id.to_string(),
258                    suppressed: false,
259                }],
260            });
261            continue;
262        };
263        match record
264            .memberships
265            .iter_mut()
266            .find(|membership| membership.node_id == node_id)
267        {
268            Some(membership) => membership.suppressed = false,
269            None => record.memberships.push(ImportRecordMembership {
270                node_id: node_id.to_string(),
271                suppressed: false,
272            }),
273        }
274    }
275}
276
277/// Import records for a snapshot that predates the table: only the legacy
278/// per-node `import_provenance` column names the sources.
279pub(crate) fn import_records_from_legacy_provenance<'a>(
280    nodes: impl IntoIterator<Item = (Uuid, &'a [NodeImportProvenance])>,
281    imported_at_secs: u64,
282) -> Vec<ImportRecord> {
283    let mut grouped = BTreeMap::<(String, String), Vec<ImportRecordMembership>>::new();
284    for (node_id, provenance) in nodes {
285        for source in provenance {
286            grouped
287                .entry((source.source_id.clone(), source.source_label.clone()))
288                .or_default()
289                .push(ImportRecordMembership {
290                    node_id: node_id.to_string(),
291                    suppressed: false,
292                });
293        }
294    }
295    grouped
296        .into_iter()
297        .map(|((source_id, source_label), memberships)| ImportRecord {
298            record_id: format!("import-record:{source_id}"),
299            source_id,
300            source_label,
301            imported_at_secs,
302            memberships,
303        })
304        .collect()
305}