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) -> Self

Create a new service with the given configuration.

pub fn from_store(config: HnswServiceConfig, store: HnswStore) -> Self

Wrap an existing HnswStore (e.g. after loading a snapshot).

Counters and epoch start at zero; callers that restore backend-level epoch (e.g. crate::vector_hnsw::HnswBackend) set it separately.

pub fn snapshot_entries(&self) -> Vec<HnswEntry>

Snapshot all stored entries for composite backend persistence.

pub fn ef_params(&self) -> (usize, usize)

Current (ef_search, ef_construction) used by the inner store.

pub fn delete(&self, id: &str) -> bool

Hard-delete an entry by string id. Returns true if it was present.

pub fn with_eml(config: HnswServiceConfig, eml_config: HnswEmlConfig) -> Self

Create a new service with custom EML 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.

When EML is enabled and trained, the beam width (ef_search) is adapted per-query and the rebuild model is consulted after each search. When a region → entry-node path table is available (WEFT-385 / HNSW-EML #4), search is guided through predicted entry nodes. Training data is recorded for continuous learning.

pub fn rebuild_path_table(&self)

Explicitly rebuild the region → entry-node path table from the current store contents (WEFT-385).

pub fn path_table_ready(&self) -> bool

Whether guided path prediction is active.

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

Brute-force ground-truth search for recall measurement.

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

Measure recall against brute-force and feed the EML rebuild model.

pub fn build_tiered(&self, top_k: usize) -> TieredSearch

Build a tiered index from the current store contents.

Uses the EML distance model’s learned dimension ordering when available, falling back to the first N dimensions otherwise. The returned TieredSearch owns separate coarse/full indexes.

pub fn eml_status(&self) -> HnswEmlStatus

Borrow the EML manager (for status/benchmarking).

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<Self, 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<Self, Error>

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

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

impl HnswService

pub fn insert_relationship( &self, stable_id: &str, embedding: Vec<f32>, metadata: Value, )

Insert a relationship (edge) embedding under rel::{stable_id}.

Metadata should include at least kind: "relationship" and the edge endpoints so consumers can reconstruct the hit without a separate graph lookup.

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

Search and keep only relationship-prefixed hits (rel::).

Oversamples the underlying store so entity vectors do not starve edge results when both share one HNSW index.

Trait Implementations

impl Debug for HnswService

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

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 + Send + Sync>>> + Send + 'async_trait>>

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

Start the service.

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

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

Stop the service.

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

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

Perform a health check.

fn health_detail(&self) -> Option<String>

Optional operator-facing detail (metrics, endpoints, …).

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

where Self: 'async_trait, 'life0: '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 Self: 'async_trait, 'life0: 'async_trait,

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