Struct ProvenanceGraph

pub struct ProvenanceGraph { /* private fields */ }

Core structure that maintains an in‑memory DAG of provenance nodes and a persistent DoltGraph backend.

• WHAT – Holds:
  • persistence: The Dolt‑based storage implementation.
  • dag: A petgraph::DiGraph where node payloads are UUIDs and edges are ProvenanceEdges.
  • node_map: A fast lookup map from node UUID to the corresponding petgraph::NodeIndex.
• HOW – Provides methods to create nodes (record_node) and edges (record_link). These methods insert into the in‑memory graph and then persist the data in Dolt tables using simple INSERT statements followed by a commit.
• WHY – Separating the transient in‑memory representation from durable storage gives fast runtime queries while guaranteeing that the provenance graph can survive process restarts and be inspected via Dolt tools.

Implementations

impl ProvenanceGraph

pub fn new(persistence: DoltGraph) -> Self

Creates a new ProvenanceGraph backed by a pre‑initialised DoltGraph.

• WHAT – Returns a fresh instance with empty in‑memory structures.
• HOW – Stores the supplied persistence and constructs a new DiGraph and empty HashMap.
• WHY – Allows callers to decide where the Dolt repository lives (e.g. a temporary directory for tests or a permanent location for production).

pub fn record_node( &mut self, id: Uuid, address: &str, ) -> Result<(), BubbleError>

Records a provenance node with a unique Uuid and an associated address.

• WHAT – Persists the node both in‑memory (dag + node_map) and in a Dolt table called provenance_nodes.
• HOW – If the node does not already exist, it is added to the DAG and a row is inserted via persistence.insert_node. A commit is performed with a descriptive message.
• WHY – Storing the address (typically a UCXL address) allows later resolution of where the artifact originated.

pub fn record_link( &mut self, source: Uuid, target: Uuid, edge: ProvenanceEdge, ) -> Result<(), BubbleError>

Records a directed edge between two existing nodes.

• WHAT – Adds an edge of type ProvenanceEdge to the DAG and stores a corresponding row in the provenance_links Dolt table.
• HOW – Retrieves the NodeIndex for each UUID (erroring with BubbleError::NodeNotFound if missing), adds the edge to dag, then inserts a row containing a new link UUID, source/target IDs and the edge type as a string.
• WHY – Persisting links allows the full provenance graph to be queried outside the process, while the in‑memory representation keeps runtime operations cheap.