uqa-graph 0.5.2

Graph store, RPQ, Cypher (lexer/parser/AST/compiler), graph algorithms
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Physical graph access shared by engine catalogs and standalone `SQLite`.

use uqa_core::{Edge, Vertex};
use uqa_storage::{GraphEntityFilter, GraphEntityKind};

use crate::{GraphLabelRegistry, GraphStoreResult};

pub use super::identifiers::{decode_identifier_generation, GraphIdentifierScope};

/// Open a write transaction or a nested savepoint on the exact storage session.
pub fn begin_graph_write(
    backend: std::sync::Arc<dyn uqa_storage::PersistentStorageBackend>,
) -> GraphStoreResult<Box<dyn GraphWriteTransaction>> {
    let savepoint = if backend.in_transaction() {
        let id = uqa_storage::StorageSavepointId::allocate();
        backend.savepoint(id)?;
        Some(id)
    } else {
        backend.begin_transaction()?;
        None
    };
    Ok(Box::new(StorageGraphWriteTransaction {
        backend,
        savepoint,
        active: true,
    }))
}

struct StorageGraphWriteTransaction {
    backend: std::sync::Arc<dyn uqa_storage::PersistentStorageBackend>,
    savepoint: Option<uqa_storage::StorageSavepointId>,
    active: bool,
}

impl GraphWriteTransaction for StorageGraphWriteTransaction {
    fn commit(&mut self) -> GraphStoreResult<()> {
        if let Some(id) = self.savepoint {
            self.backend.release_savepoint(id)?;
        } else {
            self.backend.commit_transaction()?;
        }
        self.active = false;
        Ok(())
    }

    fn rollback(&mut self) -> GraphStoreResult<()> {
        if !self.active {
            return Ok(());
        }
        if let Some(id) = self.savepoint {
            self.backend.rollback_to_savepoint(id)?;
            self.backend.release_savepoint(id)?;
        } else {
            self.backend.rollback_transaction()?;
        }
        self.active = false;
        Ok(())
    }
}

impl Drop for StorageGraphWriteTransaction {
    fn drop(&mut self) {
        if self.active {
            let _ = self.rollback();
        }
    }
}

/// A live storage checkpoint. Implementations also roll back on Drop so a
/// panic cannot publish half a graph mutation.
pub trait GraphWriteTransaction {
    fn commit(&mut self) -> GraphStoreResult<()>;
    fn rollback(&mut self) -> GraphStoreResult<()>;
}

/// No entity, membership, or adjacency collection is retained by a handle.
/// Multi-read operations run in the caller's pinned storage transaction.
pub trait GraphStorage: Send + Sync {
    /// A selection can combine an original snapshot with private entities from another clear generation. Visit each physical namespace supplying that view without observing provider validation reads.
    fn visit_selection_namespaces(
        &self,
        visit: &mut dyn FnMut(
            uqa_storage::catalog::graph_identifiers::GraphIdentifierNamespace,
        ) -> GraphStoreResult<()>,
    ) -> GraphStoreResult<()> {
        let namespace = self.identifiers()?.ok_or_else(|| {
            crate::GraphStoreError::Storage(
                "serializable graph selections require an immutable namespace".into(),
            )
        })?;
        visit(namespace.namespace())
    }
    /// Select the same physical identity generation as the entity read. An overlay may read untouched entities from its original snapshot and changed entities from its writer.
    fn entity_observation_namespace(
        &self,
        _kind: GraphEntityKind,
        _id: u64,
    ) -> GraphStoreResult<Option<uqa_storage::catalog::graph_identifiers::GraphIdentifierNamespace>>
    {
        Ok(self.identifiers()?.map(|scope| scope.namespace()))
    }
    /// Autonomous identifiers for this physical entity namespace and its current clear generation. Missing capability retains serialized counter updates.
    fn identifiers(&self) -> GraphStoreResult<Option<GraphIdentifierScope<'_>>> {
        Ok(None)
    }
    fn guard_definition(&self, _graph: Option<&str>) -> GraphStoreResult<()> {
        if self.identifiers()?.is_some() {
            return Err(crate::GraphStoreError::Storage(
                "graph definition guards are not supported".into(),
            ));
        }
        Ok(())
    }
    /// Select a fresh durable namespace when clearing every graph and entity. Providers exposing identifiers must implement this transactionally.
    fn reset_identifiers(&self) -> GraphStoreResult<()> {
        if self.identifiers()?.is_some() {
            return Err(crate::GraphStoreError::Storage(
                "graph storage cannot reset its identifier generation".into(),
            ));
        }
        Ok(())
    }
    /// Copy only transaction-local write identities when preparing a new
    /// command candidate. The underlying durable snapshots remain shared.
    fn fork_overlay(&self) -> Option<std::sync::Arc<dyn GraphStorage>> {
        None
    }
    fn unmodified_read_snapshot(&self) -> Option<super::PersistentGraphStore> {
        None
    }
    fn begin_write(&self) -> GraphStoreResult<Box<dyn GraphWriteTransaction>>;
    fn graph_names(&self) -> GraphStoreResult<Vec<String>>;
    fn has_graph(&self, graph: &str) -> GraphStoreResult<bool>;
    fn create_graph(&self, graph: &str) -> GraphStoreResult<()>;
    fn delete_graph(&self, graph: &str) -> GraphStoreResult<()>;
    fn registry(&self, graph: &str) -> GraphStoreResult<GraphLabelRegistry>;
    fn save_registry(&self, graph: &str, registry: &GraphLabelRegistry) -> GraphStoreResult<()>;
    fn counter(&self, kind: GraphEntityKind) -> GraphStoreResult<Option<u64>>;
    fn save_counter(&self, kind: GraphEntityKind, next: u64) -> GraphStoreResult<()>;
    fn vertex(&self, id: u64) -> GraphStoreResult<Option<Vertex>>;
    /// Optional caller-ordered borrowed reads with the same no-reentry,
    /// early-stop and invocation-count contract as `GraphStore`.
    fn for_each_vertex_borrowed(
        &self,
        _ids: &[u64],
        _visit: &mut dyn FnMut(u64, Option<&Vertex>) -> bool,
    ) -> GraphStoreResult<Option<usize>> {
        Ok(None)
    }
    fn edge(&self, id: u64) -> GraphStoreResult<Option<Edge>>;
    fn save_vertex(&self, vertex: &Vertex) -> GraphStoreResult<()>;
    fn save_edge(&self, edge: &Edge) -> GraphStoreResult<()>;
    fn delete_vertex(&self, id: u64) -> GraphStoreResult<()>;
    fn delete_edge(&self, id: u64) -> GraphStoreResult<()>;
    fn ids(
        &self,
        filter: GraphEntityFilter<'_>,
        after: Option<u64>,
        limit: usize,
    ) -> GraphStoreResult<Vec<u64>>;
    fn count(&self, filter: GraphEntityFilter<'_>) -> GraphStoreResult<u64>;
    fn max_id(&self, kind: GraphEntityKind) -> GraphStoreResult<Option<u64>>;
    fn memberships(&self, kind: GraphEntityKind, id: u64) -> GraphStoreResult<Vec<String>>;
    fn has_membership(&self, kind: GraphEntityKind, id: u64, graph: &str)
        -> GraphStoreResult<bool>;
    fn attach(&self, kind: GraphEntityKind, id: u64, graph: &str) -> GraphStoreResult<()>;
    fn detach(&self, kind: GraphEntityKind, id: u64, graph: &str) -> GraphStoreResult<()>;
}