Struct HnswService 

pub struct HnswService { /* private fields */ }

Kernel service wrapping the HNSW vector store.

All mutable access to the inner HnswStore is serialized through a Mutex. Atomic counters track insert and search operations for observability without requiring the lock.

Implementations

impl HnswService

pub fn new(config: HnswServiceConfig) -> HnswService

Create a new service with the given configuration.

pub fn set_chain_manager(&mut self, cm: Arc<ChainManager>)

Set the chain manager for exochain event logging.

pub fn set_governance_engine(&mut self, engine: Arc<GovernanceEngine>)

Set the governance engine for gating destructive operations.

pub fn insert(&self, id: String, embedding: Vec<f32>, metadata: Value)

Insert an embedding with associated metadata (upsert semantics).

pub fn current_epoch(&self) -> u64

Return the current monotonic epoch.

pub fn search(&self, query: &[f32], top_k: usize) -> Vec<HnswSearchResult>

Search for the top_k nearest embeddings to query.

pub fn search_batch( &self, queries: &[&[f32]], top_k: usize, ) -> Vec<Vec<HnswSearchResult>>

Batch search: acquire the lock once, perform all queries, release.

This avoids per-query mutex acquisition overhead when processing multiple embeddings in a single tick (e.g., DEMOCRITUS loop).

pub fn insert_multi_key( &self, primary_id: String, keys: &[MultiKey], metadata: Value, max_keys: usize, )

Insert an entity with multiple search keys.

Each key generates a separate embedding entry in the store, all sharing the same primary_id prefix. The stored ID has the form "{primary_id}::{key_type}". This allows the entity to be found via different query formulations (name, context, description, etc.).

Keys beyond max_keys are silently dropped.

pub fn search_dedup(&self, query: &[f32], top_k: usize) -> Vec<HnswSearchResult>

Search with deduplication by primary entity ID.

Because multi-key insertion stores several embeddings for one entity, a single query may match multiple keys of the same entity. This method searches for top_k * 3 candidates, deduplicates by stripping the "::key_type" suffix, and returns up to top_k unique entities. The best (highest) score among duplicates is kept.

pub fn len(&self) -> usize

Return the number of entries currently in the store.

pub fn is_empty(&self) -> bool

Return true if the store contains no entries.

pub fn insert_count(&self) -> u64

Total number of insert operations since service creation.

pub fn search_count(&self) -> u64

Total number of search operations since service creation.

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

Replace the inner store with a fresh, empty instance.

Useful for calibration cleanup. Counters are not reset.

Returns Err if the governance engine denies the bulk destruction.

pub fn config(&self) -> &HnswServiceConfig

Borrow the service configuration.

pub fn save_to_file(&self, path: &Path) -> Result<(), Error>

Persist the HNSW store to a JSON file.

Delegates to the underlying HnswStore::save. The HNSW index graph is not serialized; it will be rebuilt on load.

pub fn load_from_file(path: &Path) -> Result<HnswService, Error>

Load an HNSW store from a JSON file and create a new service.

Delegates to HnswStore::load. The HNSW index is rebuilt from the saved entries. Counters start at zero.

Note: chain logging for hnsw.load requires calling [set_chain_manager] after construction; use [load_from_file_logged] when a chain manager is available.

pub fn load_from_file_logged( path: &Path, cm: Arc<ChainManager>, ) -> Result<HnswService, Error>

Load an HNSW store from a JSON file with chain logging.

Same as [load_from_file] but emits an hnsw.load chain event.

Trait Implementations

impl Debug for HnswService

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl SystemService for HnswService

fn name(&self) -> &str

Human-readable service name.

fn service_type(&self) -> ServiceType

Service type category.

fn start<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>

where 'life0: 'async_trait, HnswService: 'async_trait,

Start the service.

fn stop<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>

where 'life0: 'async_trait, HnswService: 'async_trait,

Stop the service.

fn health_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = HealthStatus> + Send + 'async_trait>>

where 'life0: 'async_trait, HnswService: 'async_trait,

Perform a health check.

fn liveness_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ProbeResult> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Liveness probe (K2b-G2, os-patterns).

fn readiness_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ProbeResult> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Readiness probe (K2b-G2, os-patterns).