Skip to main content

kernel/graph/
pending_links.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//! Rebuildable extraction inputs, separate from graph truth and replay.
8
9use serde::{Deserialize, Serialize};
10use uuid::Uuid;
11
12use super::{Graph, ResourceNode, SemanticStatementSpec};
13
14#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
15pub enum PendingLinkRetention {
16    #[default]
17    SessionOnly,
18    UntilPurged,
19}
20
21/// Stable source ownership and optional original appearance context.
22/// No node indices, source documents or unasserted target records are retained.
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24pub struct PendingLink {
25    pub source_resource: Uuid,
26    pub source_surface: Option<Uuid>,
27    pub target_iri: String,
28    pub statement: SemanticStatementSpec,
29}
30
31#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
32pub struct PendingLinkState {
33    pub retention: PendingLinkRetention,
34    pub entries: Vec<PendingLink>,
35}
36
37/// A clone is a new live graph, not an escape from a replay/import scope.
38#[derive(Debug, Default)]
39pub(crate) struct Suppression(pub(crate) bool);
40
41impl Clone for Suppression {
42    fn clone(&self) -> Self {
43        Self::default()
44    }
45}
46
47#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
48pub struct PendingLinkRetry {
49    pub asserted: usize,
50    pub already_held: usize,
51    pub remaining: usize,
52}
53
54impl Graph {
55    pub fn pending_links(&self) -> &[PendingLink] {
56        &self.pending_link_state.entries
57    }
58
59    pub fn pending_link_state(&self) -> &PendingLinkState {
60        &self.pending_link_state
61    }
62
63    /// The durable representation excludes the default session-only entries.
64    pub fn retained_pending_link_state(&self) -> PendingLinkState {
65        let mut state = self.pending_link_state.clone();
66        if state.retention == PendingLinkRetention::SessionOnly {
67            state.entries.clear();
68        }
69        state
70    }
71
72    pub fn set_pending_link_retention(&mut self, retention: PendingLinkRetention) {
73        if self.pending_link_state.retention != retention {
74            self.pending_link_state.retention = retention;
75            self.semantic_observation_revision += 1;
76        }
77    }
78
79    /// Install a separate cache slot after truth replay, without deriving claims.
80    pub fn restore_pending_link_state(&mut self, state: PendingLinkState) {
81        if self.pending_link_state != state {
82            self.pending_link_state = state;
83            self.semantic_observation_revision += 1;
84        }
85    }
86
87    pub fn queue_pending_link(&mut self, mut link: PendingLink) -> bool {
88        if link.statement.provenance_iri.is_none() {
89            link.statement.provenance_iri = Some(self.write_author().asserter_iri());
90        }
91        link.target_iri = ResourceNode::new(&link.target_iri).canonical_iri().into();
92        if self.pending_link_state.entries.contains(&link) {
93            return false;
94        }
95        self.pending_link_state.entries.push(link);
96        self.semantic_observation_revision += 1;
97        true
98    }
99
100    /// Purging changes no snapshot, source document, assertion or journal entry.
101    pub fn purge_pending_links(&mut self) -> usize {
102        let count = self.pending_link_state.entries.len();
103        if count != 0 {
104            self.pending_link_state.entries.clear();
105            self.semantic_observation_revision += 1;
106        }
107        count
108    }
109
110    pub fn semantic_observation_revision(&self) -> u64 {
111        self.semantic_observation_revision
112    }
113
114    /// Suppress ambient extraction through a complete replay or import batch.
115    /// The previous scope is restored on unwind; clones do not inherit it.
116    pub fn without_pending_derivation<R>(&mut self, edit: impl FnOnce(&mut Self) -> R) -> R {
117        let previous = self.pending_derivation_suppressed.0;
118        self.pending_derivation_suppressed.0 = true;
119        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| edit(self)));
120        self.pending_derivation_suppressed.0 = previous;
121        match result {
122            Ok(result) => result,
123            Err(panic) => std::panic::resume_unwind(panic),
124        }
125    }
126
127    /// Retry only after completed live admission. Recorded assertions remain
128    /// authoritative: a carried held claim consumes its cache input unchanged.
129    pub fn retry_pending_links(&mut self) -> PendingLinkRetry {
130        if self.pending_derivation_suppressed.0 {
131            return PendingLinkRetry {
132                remaining: self.pending_links().len(),
133                ..Default::default()
134            };
135        }
136        let entries = self.pending_link_state.entries.clone();
137        let mut remaining = Vec::new();
138        let mut result = PendingLinkRetry::default();
139        for link in entries {
140            let target = ResourceNode::new(&link.target_iri).id();
141            if self.resource(link.source_resource).is_none() || self.resource(target).is_none() {
142                remaining.push(link);
143                continue;
144            }
145            match self.held_statement_by_resource_ids(link.source_resource, target, &link.statement)
146            {
147                Ok(Some(_)) => {
148                    result.already_held += 1;
149                    continue;
150                },
151                Err(_) => {
152                    remaining.push(link);
153                    continue;
154                },
155                Ok(None) => {},
156            }
157            match self.try_assert_semantic_statement_by_resource_ids(
158                link.source_resource,
159                target,
160                link.statement.clone(),
161            ) {
162                Ok((_, assertion)) => result.asserted += usize::from(assertion.changed),
163                Err(super::StatementWriteError::SurfaceContextRequired) => {
164                    let source = link
165                        .source_surface
166                        .and_then(|id| self.get_node_key_by_id(id))
167                        .filter(|&key| self.shown_resource_id(key) == Some(link.source_resource));
168                    let targets = self.surface_ids_showing_resource(target);
169                    let target_surface = (targets.len() == 1)
170                        .then(|| self.get_node_key_by_id(targets[0]))
171                        .flatten();
172                    let asserted = source.zip(target_surface).and_then(|(source, target)| {
173                        self.try_assert_semantic_statement(source, target, link.statement.clone())
174                            .ok()
175                    });
176                    if let Some((_, assertion)) = asserted {
177                        result.asserted += usize::from(assertion.changed);
178                    } else {
179                        remaining.push(link);
180                    }
181                },
182                Err(_) => remaining.push(link),
183            }
184        }
185        if remaining != self.pending_link_state.entries {
186            self.pending_link_state.entries = remaining;
187            self.semantic_observation_revision += 1;
188        }
189        result.remaining = self.pending_links().len();
190        result
191    }
192}