Struct SqliteStore 

pub struct SqliteStore { /* private fields */ }

Embedded SQLite store with transactional snapshot publication.

Implementations

impl SqliteStore

pub const fn supports_inplace_restore() -> bool

Returns whether Self::restore_from can replace an existing on-disk database.

pub fn open(path: impl AsRef<Path>) -> Result<Self, StoreError>

Opens an exact 1.0.0 store or initializes a new empty database.

Errors

Returns StoreError if SQLite cannot open, initialize, or validate the database.

pub fn backup_file( database_path: &Path, destination: &Path, ) -> Result<(), StoreError>

Creates a validated online backup of the exact 1.0.0 schema.

A source on read-only media is treated as immutable only when no SQLite sidecars exist.

Errors

Returns StoreError when the source is invalid or the destination already exists.

pub fn restore_from( database_path: &Path, backup_path: &Path, ) -> Result<RestoreReport, StoreError>

Restores a validated backup with the exact 1.0.0 schema.

The existing destination is first preserved as a non-overwriting safety backup. Restore is refused while another SqliteStore has the destination open. In-place replacement is supported on Linux, macOS, and Windows.

Errors

Returns StoreError if validation, locking, safety backup, or restore fails.

pub fn open_read_only(path: impl AsRef<Path>) -> Result<Self, StoreError>

Opens an existing store without writes or implicit schema changes.

A database on read-only media is treated as immutable only when no SQLite sidecars exist.

Errors

Returns StoreError if the database is absent, corrupt, or not the exact 1.0.0 schema.

pub fn in_memory() -> Result<Self, StoreError>

Creates an in-memory store for isolated tests and ephemeral operations.

Errors

Returns StoreError if SQLite cannot configure or initialize the database.

pub fn schema_version(&self) -> Result<i64, StoreError>

Returns the exact initial schema version recorded by this store.

Errors

Returns StoreError when schema metadata cannot be read.

pub fn database_instance_id(&self) -> Result<String, StoreError>

Returns the opaque identity that binds disposable operational state to this database.

Errors

Returns StoreError when exact schema metadata cannot be read.

pub fn save_workspace_registry( &mut self, workspace: &WorkspaceRecord, ) -> Result<(), StoreError>

Atomically replaces repository registrations for one workspace.

Errors

Returns StoreError on serialization, constraint, or transaction failure.

pub fn workspace_exists(&self, workspace: &str) -> Result<bool, StoreError>

Returns whether a workspace name is already persisted.

Errors

Returns StoreError when the registry cannot be queried.

pub fn remove_workspace(&mut self, workspace: &str) -> Result<bool, StoreError>

Removes one workspace and garbage-collects unreferenced repository records.

Errors

Returns StoreError when the transactional removal fails.

pub fn list_workspaces( &self, ) -> Result<Vec<WorkspaceRegistrySummary>, StoreError>

Lists persisted workspaces in deterministic name order.

Errors

Returns StoreError when registry rows or counts cannot be read.

pub fn load_workspace_registry( &self, workspace: &str, ) -> Result<WorkspaceRecord, StoreError>

Loads a workspace and its repository registrations in alias order.

Errors

Returns StoreError::RegistryIncomplete when required identity data is missing, or another StoreError when stored values are invalid.

pub fn backup_to(&self, destination: &Path) -> Result<(), StoreError>

Creates a consistent online backup at a new destination path.

Errors

Returns StoreError when the destination already exists or the backup cannot complete.

pub fn load_current_freshness( &self, workspace: &str, ) -> Result<Vec<RepoFreshness>, StoreError>

Loads per-repository freshness from the current workspace snapshot.

Errors

Returns StoreError when no current snapshot exists or stored freshness is invalid.

pub fn load_current_artifact_fingerprints( &self, workspace: &str, ) -> Result<Vec<ArtifactFingerprint>, StoreError>

Loads extractor-relevant fingerprints from the current snapshot.

Errors

Returns StoreError when no current snapshot exists or stored paths are invalid.

pub fn load_current_extractor_batches( &self, workspace: &str, ) -> Result<Vec<StoredExtractorBatch>, StoreError>

Loads reusable source-owned extractor outputs from the current snapshot.

Errors

Returns StoreError when no current snapshot exists or stored values are invalid.

pub fn load_current_extractor_batches_with_limit( &self, workspace: &str, maximum_payload_bytes: u64, ) -> Result<Vec<StoredExtractorBatch>, StoreError>

Loads current extractor batches whose payload fits within maximum_payload_bytes.

Oversized rows are omitted before SQLite copies their BLOB into the process. Callers can consequently treat them as cache misses and recompute them under the active policy.

Errors

Returns StoreError when no current snapshot exists or stored values are invalid.

pub fn load_current_extractor_runs( &self, workspace: &str, ) -> Result<Vec<ExtractorRun>, StoreError>

Loads extractor run metrics from the current snapshot.

Errors

Returns StoreError when no current snapshot exists or run metrics are invalid.

pub fn persist_manual_links( &mut self, snapshot_id: &str, records: &[ManualLinkRecord], ) -> Result<(), StoreError>

Replaces manual link declarations for one existing snapshot in a transaction.

Records for other snapshots are retained, preserving historical declarations. Passing an empty slice clears only the selected snapshot’s declarations.

Errors

Returns StoreError when the snapshot or endpoint nodes are absent, metadata is unsafe or oversized, records conflict, or the transaction fails.

pub fn load_manual_links( &self, snapshot_id: &str, ) -> Result<Vec<ManualLinkRecord>, StoreError>

Loads manual link declarations for one immutable snapshot in stable identifier order.

Errors

Returns StoreError::SnapshotMissing when the snapshot is absent or another StoreError when persisted rows are malformed.

pub fn upsert_provider_capabilities( &mut self, record: &ProviderCapabilityRecord, ) -> Result<(), StoreError>

Inserts or replaces one source-free provider capability report.

The repository must currently be registered in the selected workspace. Replacement is scoped by workspace, repository, provider, and provider version.

Errors

Returns StoreError for invalid metadata, an unregistered repository, serialization, integer conversion, or constraint failures.

pub fn load_provider_capabilities( &self, workspace: &str, repo_id: &RepoId, provider: &str, provider_version: &str, ) -> Result<Option<ProviderCapabilityRecord>, StoreError>

Loads one source-free provider capability report.

Errors

Returns StoreError when lookup metadata is unsafe or oversized, or persisted data is malformed. An unknown scope returns Ok(None).

pub fn put_query_cache( &mut self, record: &QueryCacheRecord, ) -> Result<(), StoreError>

Inserts or replaces one bounded query result for an immutable snapshot.

Errors

Returns StoreError when metadata, JSON, timestamps, snapshot ownership, or size bounds are invalid.

pub fn load_query_cache( &self, workspace: &str, snapshot_id: &str, input_fingerprint: &str, now_unix_ms: u64, ) -> Result<Option<QueryCacheRecord>, StoreError>

Loads one unexpired cached query result for an exact immutable-snapshot fingerprint.

Errors

Returns StoreError when lookup metadata or persisted cache data is malformed.

pub fn clear_query_cache( &mut self, workspace: &str, ) -> Result<usize, StoreError>

Deletes every cached query result for one workspace.

Errors

Returns StoreError when the delete cannot be completed.

pub fn current_snapshot_summary( &self, workspace: &str, ) -> Result<StoredSnapshotSummary, StoreError>

Loads counts and identity for the current snapshot.

Errors

Returns StoreError when no current snapshot exists or counts cannot be read.

pub fn publish_snapshot( &mut self, batch: SnapshotBatch<'_>, ) -> Result<(), StoreError>

Atomically replaces the current workspace snapshot.

The candidate is invisible as current until all nodes, evidence, edges, and evidence references are committed successfully.

Errors

Returns StoreError on community validation, constraint, serialization, or transaction failure.

pub fn publish_snapshot_with_progress<F>( &mut self, batch: SnapshotBatch<'_>, progress: F, ) -> Result<(), StoreError>

where F: FnMut(u64),

Publishes one atomic snapshot while reporting each completed durable row insertion.

Errors

Returns StoreError under the same conditions as Self::publish_snapshot.

pub fn load_current_graph( &self, workspace: &str, ) -> Result<(Vec<Node>, Vec<Edge>), StoreError>

Loads nodes and edges from the current workspace snapshot.

Errors

Returns StoreError when no current snapshot exists or stored data is invalid.

pub fn load_graph_snapshot( &self, snapshot_id: &str, ) -> Result<(Vec<Node>, Vec<Edge>), StoreError>

Loads nodes and edges from one immutable graph snapshot.

Rows are returned in stable identifier order.

Errors

Returns StoreError::SnapshotMissing when the snapshot does not exist, or another StoreError when stored rows cannot be decoded.

pub fn load_current_evidence( &self, workspace: &str, ) -> Result<Vec<Evidence>, StoreError>

Loads evidence metadata for the current workspace snapshot.

Errors

Returns StoreError when the current snapshot is absent or stored tags are malformed.

pub fn load_evidence_snapshot( &self, snapshot_id: &str, ) -> Result<Vec<Evidence>, StoreError>

Loads evidence metadata for one immutable graph snapshot.

Line ranges, extractor versions, commits, and notes predate their normalized storage columns and therefore remain absent in this projection.

Errors

Returns StoreError::SnapshotMissing when the snapshot is absent or StoreError::MalformedStoredData when a stored provenance tag is invalid.

pub fn search_current_nodes( &self, workspace: &str, query: &str, limit: usize, ) -> Result<Vec<Node>, StoreError>

Searches current snapshot node labels and stable keys using bounded FTS5.

The input is always treated as a quoted phrase rather than raw FTS syntax.

Errors

Returns StoreError for empty input, limits outside 1..=100, invalid stored tags, or SQLite failures.

pub fn search_current_nodes_ranked( &self, workspace: &str, query: &str, limit: usize, ) -> Result<Vec<StoredNodeSearchHit>, StoreError>

Searches current nodes and includes the native FTS5 relevance score.

The non-empty query is limited to 1,024 UTF-8 bytes, treated as a quoted phrase, and bound as a parameter. The result limit is 1..=500. Hits are ordered by ascending bm25 score and then stable node identifier.

Errors

Returns StoreError::InvalidSearchQuery for empty input or limits outside 1..=500. Invalid stored node tags or non-finite ranks are rejected as malformed data.

pub fn load_current_community_snapshot( &self, workspace: &str, ) -> Result<CommunitySnapshot, StoreError>

Loads the community analysis associated with the current workspace snapshot.

Errors

Returns StoreError when no current graph snapshot or community analysis exists, or when persisted rows are malformed.

pub fn load_community_snapshot( &self, snapshot_id: &str, ) -> Result<CommunitySnapshot, StoreError>

Loads one immutable community analysis in deterministic identifier order.

Errors

Returns StoreError::SnapshotMissing when the graph snapshot does not exist, StoreError::CommunitySnapshotMissing when it has no analysis, or StoreError::MalformedStoredData when persisted rows violate domain invariants.

pub fn load_workspace_community_snapshot( &self, workspace: &str, snapshot_id: &str, ) -> Result<CommunitySnapshot, StoreError>

Loads an immutable community analysis only when it belongs to the requested workspace.

Errors

Returns StoreError::SnapshotMissing when the snapshot is absent or belongs to another workspace, preserving workspace isolation at read-only delivery boundaries.

pub fn integrity_check(&self) -> Result<bool, StoreError>

Runs SQLite’s quick integrity check.

Errors

Returns StoreError if SQLite cannot perform the check.

pub fn diagnostics(&self) -> Result<StoreDiagnostics, StoreError>

Observes SQLite safety and indexing capabilities without modifying the store.

Errors

Returns StoreError when SQLite cannot provide the requested diagnostics.