Skip to main content

uqa_storage_sqlite/
graph.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Standalone `SQLite` graph storage using indexed records directly.
8//!
9//! The handle does not load a graph on open or retain entity/adjacency maps.
10//! Existing per-table schemas and legacy property encodings remain readable.
11//! Mutations follow the connection's physical or logical transactions/savepoints;
12//! multi-read queries pin one storage snapshot. Owned query results belong to the caller, not the store.
13
14mod access;
15mod native;
16#[cfg(test)]
17mod observations_tests;
18mod routing;
19
20use std::collections::{BTreeMap, BTreeSet};
21use std::sync::Arc;
22
23use crate::{ManagedConnection, SQLiteError, SQLiteStorageBackend};
24use uqa_core::{Edge, Value, Vertex};
25use uqa_storage::PersistentStorageBackend;
26
27use uqa_graph::{begin_graph_write, GraphStorage};
28use uqa_graph::{Direction, GraphStore, GraphStoreError, GraphStoreResult, PersistentGraphStore};
29
30const LEGACY_PROPERTIES_FORMAT: i64 = 1;
31const TAGGED_PROPERTIES_FORMAT: i64 = 2;
32
33/// Direct durable access to a standalone graph table family.
34pub struct SQLiteGraphStore {
35    inner: PersistentGraphStore,
36    backend: Arc<dyn PersistentStorageBackend>,
37    operation_gate: parking_lot::ReentrantMutex<()>,
38}
39
40fn graph_store_error(error: &GraphStoreError) -> SQLiteError {
41    uqa_storage::StorageBackendError::backend("graph", error.clone()).into()
42}
43
44fn sqlite_graph_error(error: SQLiteError) -> GraphStoreError {
45    uqa_storage::StorageBackendError::from(error).into()
46}
47
48impl SQLiteGraphStore {
49    /// Open a table family and migrate small access metadata once. Existing
50    /// records are streamed only for a legacy label-watermark migration.
51    pub fn open(conn: ManagedConnection, table_name: Option<&str>) -> Result<Self, SQLiteError> {
52        let suffix = table_name.unwrap_or("");
53        if !suffix
54            .chars()
55            .all(|character| character.is_ascii_alphanumeric() || character == '_')
56        {
57            return Err(SQLiteError::StorageBackend(format!(
58                "invalid graph table suffix {suffix:?}"
59            )));
60        }
61        let scope = suffix.to_ascii_lowercase();
62        let suffix = if suffix.is_empty() {
63            String::new()
64        } else {
65            format!("_{suffix}")
66        };
67        let backend: Arc<dyn PersistentStorageBackend> =
68            Arc::new(SQLiteStorageBackend::new(conn.clone()));
69        let storage = Arc::new(routing::RoutedGraphStorage {
70            native: native::NativeGraphStorage {
71                connection: conn.clone(),
72                backend: Arc::clone(&backend),
73                scope,
74            },
75            legacy: access::SQLiteGraphStorage {
76                conn,
77                backend: Arc::clone(&backend),
78                vtx_table: format!("_graph_vertices{suffix}"),
79                edge_table: format!("_graph_edges{suffix}"),
80                member_table: format!("_graph_membership{suffix}"),
81                catalog_table: format!("_graph_catalog{suffix}"),
82                metadata_table: format!("_graph_metadata{suffix}"),
83            },
84        });
85        let mut inner = PersistentGraphStore::from_storage(storage.clone());
86        let mut checkpoint =
87            begin_graph_write(Arc::clone(&backend)).map_err(|error| graph_store_error(&error))?;
88        let opened = (|| {
89            storage.ensure_tables()?;
90            match storage.metadata("direct_access_version")?.as_deref() {
91                Some("1") => {}
92                None => {
93                    for graph in storage
94                        .graph_names()
95                        .map_err(|error| graph_store_error(&error))?
96                    {
97                        inner
98                            .rebuild_label_registry_from_ids(&graph)
99                            .map_err(|error| graph_store_error(&error))?;
100                    }
101                    storage.save_metadata("direct_access_version", "1")?;
102                }
103                Some(other) => {
104                    return Err(SQLiteError::StorageBackend(format!(
105                        "unsupported standalone graph access version {other}"
106                    )))
107                }
108            }
109            Ok(())
110        })();
111        if let Err(error) = opened {
112            checkpoint
113                .rollback()
114                .map_err(|error| graph_store_error(&error))?;
115            return Err(error);
116        }
117        checkpoint
118            .commit()
119            .map_err(|error| graph_store_error(&error))?;
120        Ok(Self {
121            inner,
122            backend,
123            operation_gate: parking_lot::ReentrantMutex::new(()),
124        })
125    }
126
127    /// Execute several graph reads against one pinned storage snapshot.
128    /// Callers must serialize transaction ownership on this storage session.
129    pub fn read_snapshot<T>(
130        &self,
131        read: impl FnOnce(&PersistentGraphStore) -> GraphStoreResult<T>,
132    ) -> GraphStoreResult<T> {
133        struct ReadCheckpoint(Option<Arc<dyn PersistentStorageBackend>>);
134        impl Drop for ReadCheckpoint {
135            fn drop(&mut self) {
136                if let Some(backend) = &self.0 {
137                    let _ = backend.rollback_transaction();
138                }
139            }
140        }
141        let _operation = self.operation_gate.lock();
142        if self.backend.in_transaction() {
143            let context = self
144                .backend
145                .serializable_session()
146                .map(uqa_storage::mvcc::SerializableSession::serializable_read_context)
147                .transpose()?
148                .flatten();
149            return match context {
150                Some(context) => {
151                    let cancellation = self.backend.write_cancellation().unwrap_or_default();
152                    read(&self.inner.with_serializable_read(context, &cancellation))
153                }
154                None => read(&self.inner),
155            };
156        }
157        self.backend.begin_read_transaction()?;
158        let mut checkpoint = ReadCheckpoint(Some(Arc::clone(&self.backend)));
159        let result = read(&self.inner);
160        self.backend.rollback_transaction()?;
161        checkpoint.0 = None;
162        result
163    }
164
165    fn with_graph_mutation<T>(
166        &mut self,
167        operation: impl FnOnce(&mut PersistentGraphStore) -> GraphStoreResult<T>,
168    ) -> GraphStoreResult<T> {
169        let _operation = self.operation_gate.lock();
170        let context = self
171            .backend
172            .serializable_session()
173            .map(uqa_storage::mvcc::SerializableSession::serializable_read_context)
174            .transpose()?
175            .flatten();
176        let mut store = match context {
177            Some(context) => self.inner.with_serializable_read(
178                context,
179                &self.backend.write_cancellation().unwrap_or_default(),
180            ),
181            None => self.inner.clone(),
182        };
183        operation(&mut store)
184    }
185
186    /// Borrow the durable handle within an existing storage transaction.
187    pub fn as_graph_store(&self) -> &PersistentGraphStore {
188        &self.inner
189    }
190
191    pub fn create_graph(&mut self, name: &str) -> Result<(), SQLiteError> {
192        self.with_graph_mutation(|store| store.create_graph(name))
193            .map_err(|error| graph_store_error(&error))
194    }
195
196    pub fn drop_graph(&mut self, name: &str) -> Result<(), SQLiteError> {
197        self.with_graph_mutation(|store| store.drop_graph(name))
198            .map_err(|error| graph_store_error(&error))
199    }
200
201    pub fn graph_names(&self) -> Result<Vec<String>, SQLiteError> {
202        self.read_snapshot(GraphStore::graph_names)
203            .map_err(|error| graph_store_error(&error))
204    }
205
206    pub fn has_graph(&self, name: &str) -> Result<bool, SQLiteError> {
207        self.read_snapshot(|store| store.has_graph(name))
208            .map_err(|error| graph_store_error(&error))
209    }
210
211    pub fn union_graphs(&mut self, g1: &str, g2: &str, target: &str) -> Result<(), SQLiteError> {
212        self.with_graph_mutation(|store| store.union_graphs(g1, g2, target))
213            .map_err(|error| graph_store_error(&error))
214    }
215
216    pub fn intersect_graphs(
217        &mut self,
218        g1: &str,
219        g2: &str,
220        target: &str,
221    ) -> Result<(), SQLiteError> {
222        self.with_graph_mutation(|store| store.intersect_graphs(g1, g2, target))
223            .map_err(|error| graph_store_error(&error))
224    }
225
226    pub fn difference_graphs(
227        &mut self,
228        g1: &str,
229        g2: &str,
230        target: &str,
231    ) -> Result<(), SQLiteError> {
232        self.with_graph_mutation(|store| store.difference_graphs(g1, g2, target))
233            .map_err(|error| graph_store_error(&error))
234    }
235
236    pub fn copy_graph(&mut self, source: &str, target: &str) -> Result<(), SQLiteError> {
237        self.with_graph_mutation(|store| store.copy_graph(source, target))
238            .map_err(|error| graph_store_error(&error))
239    }
240
241    pub fn add_vertex(&mut self, vertex: Vertex, graph: &str) -> Result<(), SQLiteError> {
242        self.with_graph_mutation(|store| store.add_vertex(vertex, graph))
243            .map_err(|error| graph_store_error(&error))
244    }
245
246    pub fn add_edge(&mut self, edge: Edge, graph: &str) -> Result<(), SQLiteError> {
247        self.with_graph_mutation(|store| store.add_edge(edge, graph))
248            .map_err(|error| graph_store_error(&error))
249    }
250
251    pub fn remove_vertex(&mut self, vertex_id: u64, graph: &str) -> Result<(), SQLiteError> {
252        self.with_graph_mutation(|store| store.remove_vertex(vertex_id, graph))
253            .map_err(|error| graph_store_error(&error))
254    }
255
256    pub fn remove_edge(&mut self, edge_id: u64, graph: &str) -> Result<(), SQLiteError> {
257        self.with_graph_mutation(|store| store.remove_edge(edge_id, graph))
258            .map_err(|error| graph_store_error(&error))
259    }
260
261    pub fn neighbors(
262        &self,
263        vertex_id: u64,
264        label: Option<&str>,
265        direction: Direction,
266        graph: &str,
267    ) -> Result<Vec<u64>, SQLiteError> {
268        self.read_snapshot(|store| store.neighbors(vertex_id, label, direction, graph))
269            .map_err(|error| graph_store_error(&error))
270    }
271
272    pub fn vertices_by_label(&self, label: &str, graph: &str) -> Result<Vec<Vertex>, SQLiteError> {
273        self.read_snapshot(|store| store.vertices_by_label(label, graph))
274            .map_err(|error| graph_store_error(&error))
275    }
276
277    pub fn vertex_ids_by_label(&self, label: &str, graph: &str) -> Result<Vec<u64>, SQLiteError> {
278        self.read_snapshot(|store| store.vertex_ids_by_label(label, graph))
279            .map_err(|error| graph_store_error(&error))
280    }
281
282    pub fn vertices_in_graph(&self, graph: &str) -> Result<Vec<Vertex>, SQLiteError> {
283        self.read_snapshot(|store| store.vertices_in_graph(graph))
284            .map_err(|error| graph_store_error(&error))
285    }
286
287    pub fn edges_in_graph(&self, graph: &str) -> Result<Vec<Edge>, SQLiteError> {
288        self.read_snapshot(|store| store.edges_in_graph(graph))
289            .map_err(|error| graph_store_error(&error))
290    }
291
292    pub fn vertex_graphs(&self, vertex_id: u64) -> Result<BTreeSet<String>, SQLiteError> {
293        self.read_snapshot(|store| store.vertex_graphs(vertex_id))
294            .map_err(|error| graph_store_error(&error))
295    }
296
297    pub fn out_edge_ids(&self, vertex_id: u64, graph: &str) -> Result<BTreeSet<u64>, SQLiteError> {
298        self.read_snapshot(|store| store.out_edge_ids(vertex_id, graph))
299            .map_err(|error| graph_store_error(&error))
300    }
301
302    pub fn in_edge_ids(&self, vertex_id: u64, graph: &str) -> Result<BTreeSet<u64>, SQLiteError> {
303        self.read_snapshot(|store| store.in_edge_ids(vertex_id, graph))
304            .map_err(|error| graph_store_error(&error))
305    }
306
307    pub fn edge_ids_by_label(
308        &self,
309        label: &str,
310        graph: &str,
311    ) -> Result<BTreeSet<u64>, SQLiteError> {
312        self.read_snapshot(|store| store.edge_ids_by_label(label, graph))
313            .map_err(|error| graph_store_error(&error))
314    }
315
316    pub fn vertex_ids_in_graph(&self, graph: &str) -> Result<BTreeSet<u64>, SQLiteError> {
317        self.read_snapshot(|store| store.vertex_ids_in_graph(graph))
318            .map_err(|error| graph_store_error(&error))
319    }
320
321    pub fn require_vertex_in_graph(&self, vertex_id: u64, graph: &str) -> Result<(), SQLiteError> {
322        self.read_snapshot(|store| store.require_vertex_in_graph(vertex_id, graph))
323            .map_err(|error| graph_store_error(&error))
324    }
325
326    pub fn degree_distribution(&self, graph: &str) -> Result<BTreeMap<u64, u64>, SQLiteError> {
327        self.read_snapshot(|store| store.degree_distribution(graph))
328            .map_err(|error| graph_store_error(&error))
329    }
330
331    pub fn label_degree(&self, label: &str, graph: &str) -> Result<f64, SQLiteError> {
332        self.read_snapshot(|store| store.label_degree(label, graph))
333            .map_err(|error| graph_store_error(&error))
334    }
335
336    pub fn vertex_label_counts(&self, graph: &str) -> Result<BTreeMap<String, u64>, SQLiteError> {
337        self.read_snapshot(|store| store.vertex_label_counts(graph))
338            .map_err(|error| graph_store_error(&error))
339    }
340
341    pub fn get_vertex(&self, vertex_id: u64) -> Result<Option<Vertex>, SQLiteError> {
342        self.read_snapshot(|store| store.get_vertex(vertex_id))
343            .map_err(|error| graph_store_error(&error))
344    }
345
346    pub fn get_edge(&self, edge_id: u64) -> Result<Option<Edge>, SQLiteError> {
347        self.read_snapshot(|store| store.get_edge(edge_id))
348            .map_err(|error| graph_store_error(&error))
349    }
350
351    pub fn next_vertex_id(&mut self) -> Result<u64, SQLiteError> {
352        self.with_graph_mutation(GraphStore::next_vertex_id)
353            .map_err(|error| graph_store_error(&error))
354    }
355
356    pub fn next_edge_id(&mut self) -> Result<u64, SQLiteError> {
357        self.with_graph_mutation(GraphStore::next_edge_id)
358            .map_err(|error| graph_store_error(&error))
359    }
360
361    pub fn allocate_vertex_id(&mut self, label: &str, graph: &str) -> Result<u64, SQLiteError> {
362        self.with_graph_mutation(|store| store.allocate_vertex_id(label, graph))
363            .map_err(|error| graph_store_error(&error))
364    }
365
366    pub fn allocate_edge_id(&mut self, label: &str, graph: &str) -> Result<u64, SQLiteError> {
367        self.with_graph_mutation(|store| store.allocate_edge_id(label, graph))
368            .map_err(|error| graph_store_error(&error))
369    }
370
371    pub fn clear(&mut self) -> Result<(), SQLiteError> {
372        self.with_graph_mutation(GraphStore::clear)
373            .map_err(|error| graph_store_error(&error))
374    }
375
376    pub fn vertices(&self) -> Result<BTreeMap<u64, Vertex>, SQLiteError> {
377        self.read_snapshot(GraphStore::vertices)
378            .map_err(|error| graph_store_error(&error))
379    }
380
381    pub fn edges(&self) -> Result<BTreeMap<u64, Edge>, SQLiteError> {
382        self.read_snapshot(GraphStore::edges)
383            .map_err(|error| graph_store_error(&error))
384    }
385}
386
387impl GraphStore for SQLiteGraphStore {
388    fn vertex_id_page(
389        &self,
390        graph: &str,
391        after: Option<u64>,
392        limit: usize,
393    ) -> GraphStoreResult<Vec<u64>> {
394        self.read_snapshot(|store| store.vertex_id_page(graph, after, limit))
395    }
396    fn edge_id_page(
397        &self,
398        graph: &str,
399        after: Option<u64>,
400        limit: usize,
401    ) -> GraphStoreResult<Vec<u64>> {
402        self.read_snapshot(|store| store.edge_id_page(graph, after, limit))
403    }
404    fn transaction<T>(
405        &mut self,
406        operation: impl FnOnce(&mut Self) -> GraphStoreResult<T>,
407    ) -> GraphStoreResult<T> {
408        let mut checkpoint = self.inner.clone();
409        checkpoint.transaction(|_| operation(self))
410    }
411
412    fn create_graph(&mut self, name: &str) -> GraphStoreResult<()> {
413        self.with_graph_mutation(|store| store.create_graph(name))
414    }
415
416    fn drop_graph(&mut self, name: &str) -> GraphStoreResult<()> {
417        self.with_graph_mutation(|store| store.drop_graph(name))
418    }
419
420    fn graph_names(&self) -> GraphStoreResult<Vec<String>> {
421        self.read_snapshot(GraphStore::graph_names)
422    }
423
424    fn has_graph(&self, name: &str) -> GraphStoreResult<bool> {
425        self.read_snapshot(|store| store.has_graph(name))
426    }
427
428    fn union_graphs(&mut self, g1: &str, g2: &str, target: &str) -> GraphStoreResult<()> {
429        self.with_graph_mutation(|store| store.union_graphs(g1, g2, target))
430    }
431
432    fn intersect_graphs(&mut self, g1: &str, g2: &str, target: &str) -> GraphStoreResult<()> {
433        self.with_graph_mutation(|store| store.intersect_graphs(g1, g2, target))
434    }
435
436    fn difference_graphs(&mut self, g1: &str, g2: &str, target: &str) -> GraphStoreResult<()> {
437        self.with_graph_mutation(|store| store.difference_graphs(g1, g2, target))
438    }
439
440    fn copy_graph(&mut self, source: &str, target: &str) -> GraphStoreResult<()> {
441        self.with_graph_mutation(|store| store.copy_graph(source, target))
442    }
443
444    fn add_vertex(&mut self, vertex: Vertex, graph: &str) -> GraphStoreResult<()> {
445        self.with_graph_mutation(|store| store.add_vertex(vertex, graph))
446    }
447
448    fn add_edge(&mut self, edge: Edge, graph: &str) -> GraphStoreResult<()> {
449        self.with_graph_mutation(|store| store.add_edge(edge, graph))
450    }
451
452    fn remove_vertex(&mut self, vertex_id: u64, graph: &str) -> GraphStoreResult<()> {
453        self.with_graph_mutation(|store| store.remove_vertex(vertex_id, graph))
454    }
455
456    fn remove_edge(&mut self, edge_id: u64, graph: &str) -> GraphStoreResult<()> {
457        self.with_graph_mutation(|store| store.remove_edge(edge_id, graph))
458    }
459
460    fn neighbors(
461        &self,
462        vertex_id: u64,
463        label: Option<&str>,
464        direction: Direction,
465        graph: &str,
466    ) -> GraphStoreResult<Vec<u64>> {
467        self.read_snapshot(|store| store.neighbors(vertex_id, label, direction, graph))
468    }
469
470    fn vertices_by_label(&self, label: &str, graph: &str) -> GraphStoreResult<Vec<Vertex>> {
471        self.read_snapshot(|store| store.vertices_by_label(label, graph))
472    }
473
474    fn vertex_ids_by_label(&self, label: &str, graph: &str) -> GraphStoreResult<Vec<u64>> {
475        self.read_snapshot(|store| store.vertex_ids_by_label(label, graph))
476    }
477
478    fn vertices_in_graph(&self, graph: &str) -> GraphStoreResult<Vec<Vertex>> {
479        self.read_snapshot(|store| store.vertices_in_graph(graph))
480    }
481
482    fn edges_in_graph(&self, graph: &str) -> GraphStoreResult<Vec<Edge>> {
483        self.read_snapshot(|store| store.edges_in_graph(graph))
484    }
485
486    fn vertex_graphs(&self, vertex_id: u64) -> GraphStoreResult<BTreeSet<String>> {
487        self.read_snapshot(|store| store.vertex_graphs(vertex_id))
488    }
489    fn edge_graphs(&self, edge_id: u64) -> GraphStoreResult<BTreeSet<String>> {
490        self.read_snapshot(|store| store.edge_graphs(edge_id))
491    }
492    fn edges_by_label(&self, label: &str, graph: &str) -> GraphStoreResult<Vec<Edge>> {
493        self.read_snapshot(|store| store.edges_by_label(label, graph))
494    }
495
496    fn out_edge_ids(&self, vertex_id: u64, graph: &str) -> GraphStoreResult<BTreeSet<u64>> {
497        self.read_snapshot(|store| store.out_edge_ids(vertex_id, graph))
498    }
499
500    fn in_edge_ids(&self, vertex_id: u64, graph: &str) -> GraphStoreResult<BTreeSet<u64>> {
501        self.read_snapshot(|store| store.in_edge_ids(vertex_id, graph))
502    }
503
504    fn edge_ids_by_label(&self, label: &str, graph: &str) -> GraphStoreResult<BTreeSet<u64>> {
505        self.read_snapshot(|store| store.edge_ids_by_label(label, graph))
506    }
507
508    fn vertex_ids_in_graph(&self, graph: &str) -> GraphStoreResult<BTreeSet<u64>> {
509        self.read_snapshot(|store| store.vertex_ids_in_graph(graph))
510    }
511
512    fn require_vertex_in_graph(&self, vertex_id: u64, graph: &str) -> GraphStoreResult<()> {
513        self.read_snapshot(|store| store.require_vertex_in_graph(vertex_id, graph))
514    }
515
516    fn degree_distribution(&self, graph: &str) -> GraphStoreResult<BTreeMap<u64, u64>> {
517        self.read_snapshot(|store| store.degree_distribution(graph))
518    }
519
520    fn label_degree(&self, label: &str, graph: &str) -> GraphStoreResult<f64> {
521        self.read_snapshot(|store| store.label_degree(label, graph))
522    }
523
524    fn vertex_label_counts(&self, graph: &str) -> GraphStoreResult<BTreeMap<String, u64>> {
525        self.read_snapshot(|store| store.vertex_label_counts(graph))
526    }
527
528    fn get_vertex(&self, vertex_id: u64) -> GraphStoreResult<Option<Vertex>> {
529        self.read_snapshot(|store| store.get_vertex(vertex_id))
530    }
531
532    fn get_edge(&self, edge_id: u64) -> GraphStoreResult<Option<Edge>> {
533        self.read_snapshot(|store| store.get_edge(edge_id))
534    }
535
536    fn next_vertex_id(&mut self) -> GraphStoreResult<u64> {
537        self.with_graph_mutation(GraphStore::next_vertex_id)
538    }
539
540    fn next_edge_id(&mut self) -> GraphStoreResult<u64> {
541        self.with_graph_mutation(GraphStore::next_edge_id)
542    }
543
544    fn allocate_vertex_id(&mut self, label: &str, graph: &str) -> GraphStoreResult<u64> {
545        self.with_graph_mutation(|store| store.allocate_vertex_id(label, graph))
546    }
547
548    fn allocate_edge_id(&mut self, label: &str, graph: &str) -> GraphStoreResult<u64> {
549        self.with_graph_mutation(|store| store.allocate_edge_id(label, graph))
550    }
551
552    fn clear(&mut self) -> GraphStoreResult<()> {
553        self.with_graph_mutation(GraphStore::clear)
554    }
555
556    fn vertices(&self) -> GraphStoreResult<BTreeMap<u64, Vertex>> {
557        self.read_snapshot(GraphStore::vertices)
558    }
559
560    fn edges(&self) -> GraphStoreResult<BTreeMap<u64, Edge>> {
561        self.read_snapshot(GraphStore::edges)
562    }
563}
564
565fn decode_graph_id(kind: &str, id: i64) -> Result<u64, SQLiteError> {
566    u64::try_from(id).map_err(|_| {
567        SQLiteError::StorageBackend(format!("invalid negative {kind} id {id} in graph store"))
568    })
569}
570
571fn decode_properties(
572    properties_json: &str,
573    properties_format: i64,
574) -> Result<BTreeMap<String, Value>, SQLiteError> {
575    match properties_format {
576        LEGACY_PROPERTIES_FORMAT => {
577            let raw: BTreeMap<String, serde_json::Value> =
578                serde_json::from_str(properties_json).map_err(SQLiteError::from)?;
579            raw.into_iter()
580                .map(|(key, value)| decode_legacy_value(value).map(|value| (key, value)))
581                .collect()
582        }
583        TAGGED_PROPERTIES_FORMAT => {
584            serde_json::from_str(properties_json).map_err(SQLiteError::from)
585        }
586        other => Err(SQLiteError::StorageBackend(format!(
587            "unsupported graph properties format version {other}"
588        ))),
589    }
590}
591
592/// Decode records written by the original untagged `Value` serializer.
593/// Its `Bytes(Vec<u8>)` variant preceded `List`, so a JSON array made solely
594/// from byte-range integers (including `[]`) represented bytes at every
595/// nesting depth. New records use an explicit bytes tag and reserve raw JSON
596/// arrays for `Value::List`.
597fn decode_legacy_value(raw: serde_json::Value) -> Result<Value, SQLiteError> {
598    match raw {
599        serde_json::Value::Array(items) => {
600            let bytes = items
601                .iter()
602                .map(|item| item.as_u64().and_then(|number| u8::try_from(number).ok()))
603                .collect::<Option<Vec<_>>>();
604            if let Some(bytes) = bytes {
605                return Ok(Value::Bytes(bytes));
606            }
607            items
608                .into_iter()
609                .map(decode_legacy_value)
610                .collect::<Result<Vec<_>, _>>()
611                .map(Value::List)
612        }
613        serde_json::Value::Object(map) => {
614            if map
615                .get("$uqa_type")
616                .and_then(serde_json::Value::as_str)
617                .is_some()
618            {
619                let tagged: Value = serde_json::from_value(serde_json::Value::Object(map.clone()))
620                    .map_err(SQLiteError::from)?;
621                if !matches!(tagged, Value::Map(_)) {
622                    return Ok(tagged);
623                }
624            }
625            map.into_iter()
626                .map(|(key, value)| decode_legacy_value(value).map(|value| (key, value)))
627                .collect::<Result<BTreeMap<_, _>, _>>()
628                .map(Value::Map)
629        }
630        scalar => serde_json::from_value(scalar).map_err(SQLiteError::from),
631    }
632}
633
634pub(crate) fn encode_graph_id(kind: &str, id: u64) -> Result<i64, SQLiteError> {
635    i64::try_from(id).map_err(|_| {
636        SQLiteError::StorageBackend(format!("{kind} id {id} exceeds SQLite INTEGER range"))
637    })
638}
639
640#[cfg(test)]
641mod tests {
642    use super::*;
643    use uqa_core::{Value, Vertex};
644
645    #[test]
646    fn round_trip_through_sqlite() {
647        let conn = ManagedConnection::open_in_memory().unwrap();
648        let mut store = SQLiteGraphStore::open(conn.clone(), None).unwrap();
649        store.create_graph("g").unwrap();
650        store.add_vertex(Vertex::new(1, "person"), "g").unwrap();
651        store.add_vertex(Vertex::new(2, "person"), "g").unwrap();
652        store.add_edge(Edge::new(1, 1, 2, "knows"), "g").unwrap();
653        let other = SQLiteGraphStore::open(conn, None).unwrap();
654        assert!(other.has_graph("g").unwrap());
655        let vs = other.vertices_in_graph("g").unwrap();
656        assert_eq!(vs.len(), 2);
657        let es = other.edges_in_graph("g").unwrap();
658        assert_eq!(es.len(), 1);
659    }
660
661    #[test]
662    fn legacy_raw_bytes_and_edge_first_memberships_survive_reopen() {
663        let conn = ManagedConnection::open_in_memory().unwrap();
664        conn.with(|connection| {
665            // Exact pre-versioning table shapes. Insert the edge membership
666            // first to prove hydration is independent of SQLite row order.
667            connection.execute_batch(
668                r#"
669                CREATE TABLE _graph_vertices (
670                    vertex_id INTEGER PRIMARY KEY,
671                    label TEXT NOT NULL DEFAULT '',
672                    properties_json TEXT NOT NULL
673                );
674                CREATE TABLE _graph_edges (
675                    edge_id INTEGER PRIMARY KEY,
676                    source_id INTEGER NOT NULL,
677                    target_id INTEGER NOT NULL,
678                    label TEXT NOT NULL,
679                    properties_json TEXT NOT NULL
680                );
681                CREATE TABLE _graph_membership (
682                    graph TEXT NOT NULL,
683                    entity_kind TEXT NOT NULL,
684                    entity_id INTEGER NOT NULL,
685                    PRIMARY KEY (graph, entity_kind, entity_id)
686                );
687                CREATE TABLE _graph_catalog (name TEXT PRIMARY KEY);
688                INSERT INTO _graph_catalog (name) VALUES ('g');
689                INSERT INTO _graph_vertices
690                    (vertex_id, label, properties_json)
691                    VALUES
692                    (1, 'person', '{"bytes":[1,2],"nested":[[3,4]],"list":[256]}'),
693                    (2, 'person', '{}');
694                INSERT INTO _graph_edges
695                    (edge_id, source_id, target_id, label, properties_json)
696                    VALUES (10, 1, 2, 'knows', '{"bytes":[5,6]}');
697                INSERT INTO _graph_membership
698                    (graph, entity_kind, entity_id) VALUES ('g', 'e', 10);
699                INSERT INTO _graph_membership
700                    (graph, entity_kind, entity_id) VALUES ('g', 'v', 1);
701                INSERT INTO _graph_membership
702                    (graph, entity_kind, entity_id) VALUES ('g', 'v', 2);
703                "#,
704            )?;
705            Ok(())
706        })
707        .unwrap();
708
709        let reopened = SQLiteGraphStore::open(conn, None).unwrap();
710        let vertex = reopened.get_vertex(1).unwrap().unwrap();
711        assert_eq!(vertex.properties["bytes"], Value::Bytes(vec![1, 2]));
712        assert_eq!(
713            vertex.properties["nested"],
714            Value::List(vec![Value::Bytes(vec![3, 4])])
715        );
716        assert_eq!(
717            vertex.properties["list"],
718            Value::List(vec![Value::Int(256)])
719        );
720        assert_eq!(
721            reopened.get_edge(10).unwrap().unwrap().properties["bytes"],
722            Value::Bytes(vec![5, 6])
723        );
724    }
725
726    #[test]
727    fn list_and_explicit_bytes_properties_remain_distinct_after_reopen() {
728        let conn = ManagedConnection::open_in_memory().unwrap();
729        let mut store = SQLiteGraphStore::open(conn.clone(), None).unwrap();
730        store.create_graph("g").unwrap();
731        let mut vertex = Vertex::new(1, "payload");
732        vertex.properties.insert(
733            "list".into(),
734            Value::List(vec![Value::Int(1), Value::Int(2)]),
735        );
736        vertex
737            .properties
738            .insert("bytes".into(), Value::Bytes(vec![1, 2]));
739        store.add_vertex(vertex, "g").unwrap();
740        drop(store);
741
742        let reopened = SQLiteGraphStore::open(conn, None).unwrap();
743        let restored = reopened.get_vertex(1).unwrap().unwrap();
744        assert_eq!(
745            restored.properties["list"],
746            Value::List(vec![Value::Int(1), Value::Int(2)])
747        );
748        assert_eq!(restored.properties["bytes"], Value::Bytes(vec![1, 2]));
749    }
750
751    #[test]
752    fn failed_persistence_does_not_publish_partial_disk_state() {
753        let conn = ManagedConnection::open_in_memory().unwrap();
754        let mut store = SQLiteGraphStore::open(conn.clone(), None).unwrap();
755        store.create_graph("g").unwrap();
756        store.add_vertex(Vertex::new(1, "person"), "g").unwrap();
757        conn.with(|connection| {
758            connection.execute_batch(
759                r#"
760                CREATE TRIGGER fail_graph_membership
761                BEFORE INSERT ON "_graph_membership"
762                WHEN NEW.entity_id = 2
763                BEGIN
764                    SELECT RAISE(ABORT, 'forced graph persistence failure');
765                END;
766                "#,
767            )?;
768            Ok(())
769        })
770        .unwrap();
771
772        assert!(store.add_vertex(Vertex::new(2, "person"), "g").is_err());
773        assert!(store.get_vertex(1).unwrap().is_some());
774        assert!(store.get_vertex(2).unwrap().is_none());
775
776        conn.with(|connection| {
777            connection.execute_batch("DROP TRIGGER fail_graph_membership")?;
778            Ok(())
779        })
780        .unwrap();
781        let reopened = SQLiteGraphStore::open(conn, None).unwrap();
782        assert_eq!(reopened.vertices_in_graph("g").unwrap().len(), 1);
783        assert!(reopened.get_vertex(2).unwrap().is_none());
784    }
785
786    #[test]
787    fn unrelated_corrupt_payload_is_not_loaded_until_queried() {
788        let conn = ManagedConnection::open_in_memory().unwrap();
789        let mut store = SQLiteGraphStore::open(conn.clone(), None).unwrap();
790        store.create_graph("g").unwrap();
791        store.add_vertex(Vertex::new(1, "person"), "g").unwrap();
792        conn.with(|connection| {
793            connection.execute(
794                "UPDATE _graph_vertices SET properties_json = '{' WHERE vertex_id = 1",
795                [],
796            )?;
797            Ok(())
798        })
799        .unwrap();
800
801        store.add_vertex(Vertex::new(2, "person"), "g").unwrap();
802        let reopened = SQLiteGraphStore::open(conn, None).unwrap();
803        assert!(reopened.get_vertex(2).unwrap().is_some());
804        assert!(reopened.get_vertex(1).is_err());
805    }
806
807    #[test]
808    fn allocated_label_sequence_survives_reopen() {
809        let conn = ManagedConnection::open_in_memory().unwrap();
810        let mut store = SQLiteGraphStore::open(conn.clone(), None).unwrap();
811        store.create_graph("g").unwrap();
812        let first = store.allocate_vertex_id("person", "g").unwrap();
813        drop(store);
814
815        let mut reopened = SQLiteGraphStore::open(conn, None).unwrap();
816        let second = reopened.allocate_vertex_id("person", "g").unwrap();
817        assert_ne!(first, second);
818        assert!(second > first);
819    }
820}