Skip to main content

uqa_graph/persistent_store/
observations.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Retained participant attribution belongs to semantic graph access, not physical decoding or validation reads.
8
9use uqa_core::CancellationToken;
10use uqa_storage::catalog::graph_observations::{
11    scope_lifetime, GraphDefinitionKey, GraphDefinitionKind, GraphEntityKey,
12    GraphLabelDefinitionKey, GraphLabelName, GraphMembershipKey, GraphSelectionKey,
13};
14use uqa_storage::mvcc::{SerializablePredicate, SerializableReadContext, VersionError};
15use uqa_storage::{read_control::StorageReadControl, GraphEntityFilter, GraphEntityKind};
16
17use super::PersistentGraphStore;
18use crate::{GraphStoreError, GraphStoreResult};
19
20#[derive(Clone)]
21pub(super) struct GraphRead {
22    context: SerializableReadContext,
23    control: StorageReadControl,
24}
25
26impl GraphRead {
27    fn observe(
28        &self,
29        namespace: uqa_storage::catalog::graph_identifiers::GraphIdentifierNamespace,
30        predicate: SerializablePredicate<'_>,
31    ) -> GraphStoreResult<()> {
32        self.context
33            .observe_read(scope_lifetime(namespace), &self.control)
34            .map_err(VersionError::into_storage_error)?;
35        self.context
36            .observe_read(predicate, &self.control)
37            .map_err(VersionError::into_storage_error)?;
38        Ok(())
39    }
40}
41
42impl PersistentGraphStore {
43    pub(crate) fn observe_labels(&self, graph: &str, label: Option<&str>) -> GraphStoreResult<()> {
44        let Some(read) = &self.read else {
45            return Ok(());
46        };
47        self.observe_definition(GraphDefinitionKind::NamedGraph, Some(graph))?;
48        let label = label.map(|label| {
49            for kind in [crate::LabelKind::Vertex, crate::LabelKind::Edge] {
50                if label == kind.default_label_name() {
51                    return GraphLabelName::Reserved(kind.default_label_id());
52                }
53            }
54            GraphLabelName::Named(label)
55        });
56        let mut previous = None;
57        self.storage.visit_selection_namespaces(&mut |namespace| {
58            let object = namespace.serializable_scope_object();
59            if previous != Some(object) {
60                previous = Some(object);
61                read.observe(
62                    namespace,
63                    GraphLabelDefinitionKey::new(namespace, graph, label).predicate(),
64                )?;
65            }
66            Ok(())
67        })
68    }
69
70    /// Attribute a semantic catalog lookup even when its result comes from an immutable definition cache. Physical catalog restoration and planner estimates remain unobserved.
71    pub fn observe_definition(
72        &self,
73        kind: GraphDefinitionKind,
74        name: Option<&str>,
75    ) -> GraphStoreResult<()> {
76        let Some(read) = &self.read else {
77            return Ok(());
78        };
79        read.control.check()?;
80        let mut previous = None;
81        self.storage.visit_selection_namespaces(&mut |namespace| {
82            let object = namespace.serializable_scope_object();
83            if previous != Some(object) {
84                previous = Some(object);
85                read.observe(
86                    namespace,
87                    GraphDefinitionKey::new(namespace, kind, name).predicate(),
88                )?;
89            }
90            Ok(())
91        })
92    }
93
94    /// A stored reachability result depends on its starting vertices and each selected edge label, including empty results. Register those logical selectors without reconstructing paths or observing entity properties.
95    pub(crate) fn observe_cached_paths(
96        &self,
97        graph: &str,
98        sequence: &[String],
99    ) -> GraphStoreResult<()> {
100        self.observe_selection(
101            GraphEntityFilter::new(GraphEntityKind::Vertex, Some(graph)),
102            None,
103        )?;
104        for label in sequence {
105            let mut filter = GraphEntityFilter::new(GraphEntityKind::Edge, Some(graph));
106            filter.label = Some(label);
107            self.observe_selection(filter, None)?;
108        }
109        Ok(())
110    }
111
112    pub(super) fn observe_selection(
113        &self,
114        filter: GraphEntityFilter<'_>,
115        after: Option<u64>,
116    ) -> GraphStoreResult<()> {
117        let Some(read) = &self.read else {
118            return Ok(());
119        };
120        read.control.check()?;
121        let mut previous = None;
122        self.storage.visit_selection_namespaces(&mut |namespace| {
123            let object = namespace.serializable_entity_object();
124            if previous == Some(object) {
125                return Ok(());
126            }
127            previous = Some(object);
128            if let Some(graph) = filter.graph {
129                read.observe(
130                    namespace,
131                    GraphDefinitionKey::new(
132                        namespace,
133                        GraphDefinitionKind::NamedGraph,
134                        Some(graph),
135                    )
136                    .predicate(),
137                )?;
138            }
139            let key = GraphSelectionKey::new(namespace, filter, after)?;
140            read.observe(namespace, key.predicate())?;
141            Ok(())
142        })
143    }
144
145    pub(super) fn observe_membership(
146        &self,
147        kind: GraphEntityKind,
148        id: u64,
149        graph: Option<&str>,
150    ) -> GraphStoreResult<()> {
151        let Some(read) = &self.read else {
152            return Ok(());
153        };
154        read.control.check()?;
155        let namespace = self
156            .storage
157            .entity_observation_namespace(kind, id)?
158            .ok_or_else(|| {
159                GraphStoreError::Storage(
160                    "serializable graph memberships require an immutable namespace".into(),
161                )
162            })?;
163        read.observe(
164            namespace,
165            GraphMembershipKey::new(namespace, kind, id, graph).predicate(),
166        )?;
167        Ok(())
168    }
169
170    pub(super) fn for_each_selected_id(
171        &self,
172        filter: GraphEntityFilter<'_>,
173        visit: impl FnMut(u64) -> GraphStoreResult<()>,
174    ) -> GraphStoreResult<()> {
175        self.observe_selection(filter, None)?;
176        self.for_each_id(filter, visit)
177    }
178    /// Bind a query's original participant and allowance without observing data. Clones retain this binding; catalog caches should keep unbound handles and bind each executing reader explicitly.
179    pub fn with_serializable_read(
180        &self,
181        context: SerializableReadContext,
182        cancellation: &CancellationToken,
183    ) -> Self {
184        let control = context.read_control(cancellation);
185        let mut store = self.clone();
186        store.read = Some(GraphRead { context, control });
187        store
188    }
189
190    /// Remove a completed query's observer before retaining this handle as session catalog state. Its storage snapshot and resources are unchanged.
191    pub fn without_serializable_read(mut self) -> Self {
192        self.read = None;
193        self
194    }
195
196    pub(super) fn observe_entity(&self, kind: GraphEntityKind, id: u64) -> GraphStoreResult<()> {
197        if let Some(read) = &self.read {
198            read.control.check()?;
199            let namespace = self
200                .storage
201                .entity_observation_namespace(kind, id)?
202                .ok_or_else(|| {
203                    GraphStoreError::Storage(
204                        "serializable graph reads require an immutable entity namespace".into(),
205                    )
206                })?;
207            read.observe(
208                namespace,
209                GraphEntityKey::new(namespace, kind, id).predicate(),
210            )?;
211        }
212        Ok(())
213    }
214}