pub struct Store { /* private fields */ }Expand description
A Roteiro graph store backed by a single SQLite database.
Implementations§
Source§impl Store
impl Store
Sourcepub fn open(path: &Path) -> Result<Self, StoreError>
pub fn open(path: &Path) -> Result<Self, StoreError>
Open (creating if absent) a store at path and apply pending migrations.
§Errors
Returns StoreError::Sqlite if the database cannot be opened or a
migration fails.
Sourcepub fn open_in_memory() -> Result<Self, StoreError>
pub fn open_in_memory() -> Result<Self, StoreError>
Sourcepub fn schema_version(&self) -> Result<u32, StoreError>
pub fn schema_version(&self) -> Result<u32, StoreError>
The schema version this store has been migrated to.
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn node_count(&self) -> Result<u64, StoreError>
pub fn node_count(&self) -> Result<u64, StoreError>
Sourcepub fn edge_count(&self) -> Result<u64, StoreError>
pub fn edge_count(&self) -> Result<u64, StoreError>
Sourcepub fn upsert_node(&self, node: &Node) -> Result<(), StoreError>
pub fn upsert_node(&self, node: &Node) -> Result<(), StoreError>
Insert or update a node, keyed by its natural Node::key.
§Errors
Returns StoreError::Json if meta cannot be serialized, or
StoreError::Sqlite on write failure.
Sourcepub fn insert_edge(&self, edge: &Edge) -> Result<(), StoreError>
pub fn insert_edge(&self, edge: &Edge) -> Result<(), StoreError>
Insert an edge. Both endpoints must already resolve to nodes.
§Errors
Returns StoreError::InvalidEdge if the provenance/confidence
invariant is violated, StoreError::UnknownNode if an endpoint key is
absent, or StoreError::Sqlite on write failure.
Sourcepub fn apply_factset(&mut self, facts: &FactSet) -> Result<(), StoreError>
pub fn apply_factset(&mut self, facts: &FactSet) -> Result<(), StoreError>
Apply a fact set atomically: all nodes are upserted, then all edges are inserted, in a single transaction. On any error nothing is committed.
§Errors
Returns the first error encountered (see Store::upsert_node and
Store::insert_edge); the transaction is rolled back.
Sourcepub fn sync_state(&self) -> Result<Option<String>, StoreError>
pub fn sync_state(&self) -> Result<Option<String>, StoreError>
The HEAD tree id recorded at the last successful Store::rebuild, if
any. Used by the sync engine to detect an unchanged tree.
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn sync_env(&self) -> Result<Option<String>, StoreError>
pub fn sync_env(&self) -> Result<Option<String>, StoreError>
The extractor environment recorded with the last committed [sync],
None if unset (a legacy row, or the last sync was a worktree/index
preview). The incremental committed sync compares this to the current
env and falls back to a full re-extraction when they differ.
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn set_sync_env(&self, env: &str) -> Result<(), StoreError>
pub fn set_sync_env(&self, env: &str) -> Result<(), StoreError>
Record the extractor environment for the current synced tree. Called by a
committed sync right after it writes the tree, so a later sync can decide
whether the incremental fast path is sound. A no-op if no tree is recorded.
§Errors
Returns StoreError::Sqlite on write failure.
Sourcepub fn rebuild(
&mut self,
facts: &FactSet,
tree: Option<&str>,
) -> Result<(), StoreError>
pub fn rebuild( &mut self, facts: &FactSet, tree: Option<&str>, ) -> Result<(), StoreError>
Atomically replace the entire graph with facts, recording tree as the
synced state (or clearing it when tree is None). All existing nodes
and edges are deleted first, so the store reflects exactly the given fact
set.
Passing None records no synced tree — distinct from an empty string —
so Store::sync_state returns None and a later sync will not
spuriously short-circuit.
§Errors
Returns the first error encountered (see Store::apply_factset); on any
error nothing is committed.
Sourcepub fn reconcile(
&mut self,
facts: &FactSet,
tree: Option<&str>,
) -> Result<(), StoreError>
pub fn reconcile( &mut self, facts: &FactSet, tree: Option<&str>, ) -> Result<(), StoreError>
Bring the store to exactly facts (as Store::rebuild does) but writing
only what differs instead of wiping and reinserting the whole graph —
the git-style “write only the delta”. Unchanged node rows (which carry the
heavy JSON meta) and unchanged edge rows are left untouched; only removed
rows are deleted and new/changed rows written. The final state — nodes,
edges, and sync_state — is identical to rebuild(facts, tree).
Leaving unchanged edges in place means their row ids do not match a cold
rebuild’s — which is safe because every edge query is content-ordered
((src, dst, kind, provenance), see Store::all_edges), never by row
id. So an incrementally reconciled store and a fresh rebuild return every
query identically; the delta is invisible above the storage layer.
§Errors
Returns StoreError on a query failure; the transaction is rolled back.
Sourcepub fn get_node(&self, key: &str) -> Result<Option<Node>, StoreError>
pub fn get_node(&self, key: &str) -> Result<Option<Node>, StoreError>
Fetch a node by its natural key.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt if a stored value cannot be decoded.
Sourcepub fn all_keys(&self) -> Result<Vec<String>, StoreError>
pub fn all_keys(&self) -> Result<Vec<String>, StoreError>
Every node key in the store, ordered. Useful for whole-graph exports.
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn export_factset(&self) -> Result<FactSet, StoreError>
pub fn export_factset(&self) -> Result<FactSet, StoreError>
Dump the entire graph as a single FactSet, with nodes and edges in a
deterministic order — suitable for a portable, content-stable artifact.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn nodes_by_kind(&self, kind: &NodeKind) -> Result<Vec<Node>, StoreError>
pub fn nodes_by_kind(&self, kind: &NodeKind) -> Result<Vec<Node>, StoreError>
All nodes of a given kind.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn nodes_by_kind_named(
&self,
kind: &NodeKind,
name_lower: &str,
) -> Result<Vec<Node>, StoreError>
pub fn nodes_by_kind_named( &self, kind: &NodeKind, name_lower: &str, ) -> Result<Vec<Node>, StoreError>
Nodes of a given kind whose name equals name_lower case-insensitively,
ordered by key. Narrows a lookup at the SQL layer — using the kind index and
filtering name in-query — so only matching rows are decoded, never every
node of that kind. Used by the cross-repo follow bridge to fetch just the
candidate struct(s) for a config section rather than scanning all structs.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn config_keys(&self) -> Result<Vec<ConfigKey>, StoreError>
pub fn config_keys(&self) -> Result<Vec<ConfigKey>, StoreError>
Every config_key node’s flattened setting (ADR-0009), read back out of
the graph as crate::ConfigKeys — the graph-native source the cross-repo
link matcher (roteiro links --infer) consumes, so it never re-parses
config files. Ordered by node key (deterministic). A node missing the
key/path a well-formed config_key carries is skipped defensively.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn nodes_by_path(&self, path: &str) -> Result<Vec<Node>, StoreError>
pub fn nodes_by_path(&self, path: &str) -> Result<Vec<Node>, StoreError>
Every node whose source path is path, ordered by key — the file node
plus the symbols and markers defined in it. Used to scope a change to the
graph (e.g. roteiro review).
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn nodes_by_provenance(
&self,
provenance: Provenance,
) -> Result<Vec<Node>, StoreError>
pub fn nodes_by_provenance( &self, provenance: Provenance, ) -> Result<Vec<Node>, StoreError>
Every node produced by a given layer, ordered by key. The incremental
sync loads the Derived layer to reconstruct the extraction graph
without re-reading every blob.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn all_nodes(&self) -> Result<Vec<Node>, StoreError>
pub fn all_nodes(&self) -> Result<Vec<Node>, StoreError>
Every node in the store, ordered by key. Unlike Store::export_factset
this decodes no edges, so it is cheap for node-only scans (e.g. search).
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on decode failure.
Sourcepub fn all_edges(&self) -> Result<Vec<Edge>, StoreError>
pub fn all_edges(&self) -> Result<Vec<Edge>, StoreError>
Every edge in the store, with endpoints resolved to their node keys. Used
by Store::reconcile to diff the edge set.
Ordered by the edge’s content — (src key, dst key, kind, provenance),
the table’s unique tuple — not by row id. This makes the order a function
of the graph, not of insertion history, so an incrementally
reconciled store and a cold rebuild
return edges identically. (The same reason node scans order by key.)
§Errors
Returns StoreError::Sqlite or StoreError::Corrupt on failure.
Sourcepub fn edges_from(&self, key: &str) -> Result<Vec<Edge>, StoreError>
pub fn edges_from(&self, key: &str) -> Result<Vec<Edge>, StoreError>
Edges whose source is the node with the given key, in content order
((dst key, kind, provenance) — src is fixed). Content-ordered rather
than by row id so the result is history-independent; see Store::all_edges.
§Errors
Returns StoreError::Sqlite or StoreError::Corrupt on failure.
Sourcepub fn edges_to(&self, key: &str) -> Result<Vec<Edge>, StoreError>
pub fn edges_to(&self, key: &str) -> Result<Vec<Edge>, StoreError>
Edges whose destination is the node with the given key, in content order
((src key, kind, provenance) — dst is fixed). See Store::all_edges.
§Errors
Returns StoreError::Sqlite or StoreError::Corrupt on failure.
Sourcepub fn edges_by_provenance(
&self,
provenance: Provenance,
) -> Result<Vec<Edge>, StoreError>
pub fn edges_by_provenance( &self, provenance: Provenance, ) -> Result<Vec<Edge>, StoreError>
All edges with the given provenance, in content order
((src key, dst key, kind) — provenance is fixed). See Store::all_edges.
§Errors
Returns StoreError::Sqlite or StoreError::Corrupt on failure.
Sourcepub fn delete_edges_by_provenance(
&self,
provenance: Provenance,
) -> Result<u64, StoreError>
pub fn delete_edges_by_provenance( &self, provenance: Provenance, ) -> Result<u64, StoreError>
Delete all edges with the given provenance, returning how many were
removed. Used to re-derive a whole provenance class authoritatively (e.g.
inferred edges when re-running inference with different parameters).
§Errors
Returns StoreError::Sqlite on write failure.
Sourcepub fn delete_edges_by_src_ref(&self, src_ref: &str) -> Result<u64, StoreError>
pub fn delete_edges_by_src_ref(&self, src_ref: &str) -> Result<u64, StoreError>
Delete all edges carrying the given src_ref, returning how many were
removed. Lets one producer of inferred edges (e.g. the embedding layer,
or a Graphify import) re-derive its own edges authoritatively without
touching edges another producer contributed.
§Errors
Returns StoreError::Sqlite on write failure.
Sourcepub fn apply_import_layer(
&mut self,
src_ref: &str,
facts: &FactSet,
) -> Result<ImportApplied, StoreError>
pub fn apply_import_layer( &mut self, src_ref: &str, facts: &FactSet, ) -> Result<ImportApplied, StoreError>
Apply an import layer to the live graph and persist it durably under
src_ref, validating as it goes: this ref’s prior edges are cleared
(an authoritative re-import), the layer’s nodes are upserted, and each
edge is applied only if both endpoints resolve. Dangling edges — cross-
references to code that is not present — are dropped, and only the
validated (trimmed) layer is persisted, so stale data is never stored.
This is the “validate on import” half; Store::reapply_imports is the
“validate on sync” half, re-checking layers against the rebuilt graph.
§Errors
Returns StoreError::Json if facts cannot be (de)serialized,
StoreError::InvalidEdge on a malformed edge, or StoreError::Sqlite
on write failure.
Sourcepub fn delete_import(&self, src_ref: &str) -> Result<bool, StoreError>
pub fn delete_import(&self, src_ref: &str) -> Result<bool, StoreError>
Remove the persisted import layer for src_ref, returning whether one
existed. Does not remove edges already in the live graph (use
Store::delete_edges_by_src_ref for that).
§Errors
Returns StoreError::Sqlite on write failure.
Sourcepub fn import_refs(&self) -> Result<Vec<String>, StoreError>
pub fn import_refs(&self) -> Result<Vec<String>, StoreError>
The src_refs of all persisted import layers, ordered.
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn reapply_imports(&mut self) -> Result<ImportApplied, StoreError>
pub fn reapply_imports(&mut self) -> Result<ImportApplied, StoreError>
Re-apply every persisted import layer on top of the current graph and re-validate it: all import nodes are upserted first (so cross-layer and self references resolve), then each edge is applied; an edge whose endpoint is now absent — a cross-reference to code a sync removed — is pruned from the persisted layer, not merely skipped. So the durable store keeps only still-correct data. Idempotent; safe to run after each rebuild.
§Errors
Returns StoreError::Json if a stored layer cannot be (de)serialized,
or StoreError::Sqlite on write failure.
Sourcepub fn neighbors(
&self,
key: &str,
dir: Direction,
) -> Result<Vec<Node>, StoreError>
pub fn neighbors( &self, key: &str, dir: Direction, ) -> Result<Vec<Node>, StoreError>
Neighbouring nodes reachable from key in the given direction. Returns
an empty vector if the node does not exist.
§Errors
Returns StoreError::Sqlite, StoreError::Json, or
StoreError::Corrupt on failure.
Sourcepub fn context_cache_get(
&self,
key: &str,
) -> Result<Option<(String, String)>, StoreError>
pub fn context_cache_get( &self, key: &str, ) -> Result<Option<(String, String)>, StoreError>
Fetch the cached context bundle for key as (fingerprint, json), if
present. The caller compares the fingerprint to the node’s current one to
decide whether the entry is fresh (see crate::context).
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn context_cache_fingerprint(
&self,
key: &str,
) -> Result<Option<String>, StoreError>
pub fn context_cache_fingerprint( &self, key: &str, ) -> Result<Option<String>, StoreError>
Fetch just the cached fingerprint for key, without reading the (larger)
JSON payload — for a cheap freshness check.
§Errors
Returns StoreError::Sqlite on query failure.
Sourcepub fn context_cache_put(
&self,
key: &str,
fingerprint: &str,
json: &str,
) -> Result<(), StoreError>
pub fn context_cache_put( &self, key: &str, fingerprint: &str, json: &str, ) -> Result<(), StoreError>
Store (or replace) the cached context bundle for key.
§Errors
Returns StoreError::Sqlite on write failure.
Sourcepub fn context_cache_delete(&self, key: &str) -> Result<bool, StoreError>
pub fn context_cache_delete(&self, key: &str) -> Result<bool, StoreError>
Delete the cached context entry for key, returning whether one existed.
§Errors
Returns StoreError::Sqlite on write failure.
Sourcepub fn context_cache_keys(&self) -> Result<Vec<String>, StoreError>
pub fn context_cache_keys(&self) -> Result<Vec<String>, StoreError>
Every key with a cached context entry, ordered. Used to prune entries for nodes that no longer exist.
§Errors
Returns StoreError::Sqlite on query failure.