Struct HmsCore 

pub struct HmsCore { /* private fields */ }

Persistent operations take mutation_gate before ShardSet and component locks.

Implementations

impl HmsCore

pub fn compact(&self) -> Result<()>

pub fn compact_scrubbing(&self) -> Result<()>

Compacts and then physically erases what the compaction replaced: the old generation and any unreferenced leftovers are overwritten with zeros and synced before they are unlinked. The text segment is scrubbed per deleted document at delete time.

Afterwards nothing derived depends on the purged documents or on the order documents arrived in (see canonicalize_derived_state), so every query, status field other than the opaque counters, and file other than the generation’s name match a store that never held them and was purged at the same point.

impl HmsCore

pub fn synthesize_concepts(&self) -> Vec<ConceptCandidate>

Cluster similar vectors and return concept candidates with centroids and coherence scores.

Uses posting-list candidate generation: only vector pairs sharing at least one active index are compared, avoiding O(n²) all-pairs at high sparsity.

impl HmsCore

pub fn security_status(&self) -> Value

pub fn memorize_document(&self, input: DocumentInput) -> Result<u32>

pub fn memorize_document_with( &self, input: DocumentInput, options: &IngestOptions, ) -> Result<u32>

Self::memorize_document with per-call options: IngestOptions::encode chooses whether the chunk hypervectors are computed now, on first vector use, or never.

pub fn memorize_documents(&self, inputs: Vec<DocumentInput>) -> Result<Vec<u32>>

pub fn memorize_documents_with( &self, inputs: Vec<DocumentInput>, options: &IngestOptions, ) -> Result<Vec<u32>>

Self::memorize_documents with per-call options. Documents are prepared in parallel and committed as one transaction in input order; the encoder’s per-thread memo tables are pure caches, so the stored vectors do not depend on the thread count.

pub fn search_documents( &self, text: &str, options: &SearchOptions, ) -> Result<Vec<DocumentResult>>

pub fn count_documents(&self, text: &str) -> Result<usize>

The number of documents containing at least one word of text: every document an unfiltered lexical Self::search_documents can return, counted exactly rather than ranked.

pub fn document_index_trained(&self) -> bool

pub fn document_embedding_count(&self) -> usize

pub fn search_vectors( &self, embedding: &[f64], k: usize, options: &VectorQueryOptions, ) -> Result<Vec<DocumentResult>>

Nearest embedded chunks to embedding by cosine, best first; score and semantic_score both carry the cosine. Unfiltered vector queries are answered from the vector snapshot (documents::vector_index) when one is built: the graph index under Auto/Graph, the contiguous exact scan under Exact. Without a snapshot, or when the snapshot is too stale for this query, the generic exact path answers. Graph without a graph index fails with documents::GraphUnavailable.

pub fn vector_index_status(&self) -> VectorIndexStatus

pub fn rebuild_vector_index(&self, graph_min_rows: usize) -> Result<bool>

Captures the embedded chunks and publishes a fresh vector snapshot, with the graph index when the store has at least graph_min_rows of them. false when the store has no embedding space or too few embedded chunks (the snapshot is dropped then), or when another build is running (the published snapshot stays). The capture holds the store’s read lock; the graph build holds no lock.

pub fn maintain_vector_index(&self, graph_min_rows: usize) -> Result<bool>

Self::rebuild_vector_index when the status recommends it (no snapshot over a store with enough embedded chunks, or REBUILD_AFTER_MUTATIONS mutations since the capture); otherwise reports whether a snapshot exists.

pub fn train_document_index(&self) -> Result<()>

pub fn encode_pending_documents(&self) -> Result<usize>

Encodes and persists the hypervectors of every document memorized with documents::EncodeMode::Deferred that is still awaiting them, and returns how many documents that was. Vectors are computed from the stored chunk text exactly as eager ingest computes them. Idempotent; concurrent callers serialize on the store’s encode gate and the second one finds nothing left. A vector query runs this first, so pending documents are never silently missing from it.

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

Whether a document with this id currently resolves in the opened store.

pub fn set_keep_ingest_interner(&self, keep: bool)

Whether the word interner built while preparing a document batch is kept for the next batch (the default). Keeping it saves re-stemming a corpus’s vocabulary across batches at a cost bounded by 2^18 distinct words (tens of MB at worst); a process holding many open stores, such as a multi-tenant server, can turn it off to free each batch’s interner with the batch. Turning it off frees the kept interner now.

pub fn document_count(&self) -> usize

Number of stored documents.

pub fn get_document(&self, id: &str) -> Option<DocumentRecord>

One stored document with its text, metadata and version.

pub fn list_documents( &self, from: Option<&str>, limit: usize, ) -> Vec<DocumentRecord>

Up to limit stored documents with ids at or after from, in id order. Resume after id X with from = X + "\0" (document ids cannot contain NUL).

pub fn delete_document(&self, id: &str) -> Result<bool>

pub fn memorize_batch(&self, items: &[MemorizeBatchItem]) -> Result<()>

One bounded transaction; either every item is logged or none is.

pub fn query_vector( &self, dense: &[f32], k: u32, ) -> Result<Vec<RetrievalResult>>

impl HmsCore

pub fn memorize_triplet( &self, id: String, h: String, r: String, t: String, ) -> Result<()>

Encode a (head, relation, tail) triplet as h XOR r XOR t and memorize it.

pub fn memorize_sequence(&self, id: String, sequence: &[String]) -> Result<()>

Encode an ordered sequence using position-based permutation and memorize it.

pub fn query_triplet( &self, h: String, r: String, k: u32, ) -> Result<Vec<RetrievalResult>>

Query for tails matching head XOR relation.

pub fn find_analogy( &self, a: &str, b: &str, c: &str, k: u32, ) -> Vec<RetrievalResult>

Find analogy: A is to B as C is to ? Returns k closest matches.

pub fn query_sequence( &self, partial: &[String], k: u32, ) -> Result<Vec<RetrievalResult>>

Query for sequences matching a partial sequence prefix.

impl HmsCore

pub fn revision(&self) -> u64

Advances by one per write transaction this process commits or replays, so equal values bracket an unchanged store and the difference of two readings counts the transactions between them. It starts at a random value per open, so one reading does not reveal how many transactions (inserts, deletes) the store has seen.

impl HmsCore

pub fn query(&self, query_vec: &EntangledHVec, k: u32) -> Vec<RetrievalResult>

Query the memory system for the k most similar vectors.

pub fn agent_registry(&self) -> &RwLock<AgentRegistry>

The registry of agents admitted by verified access credentials.

pub fn query_as( &self, agent_did: &str, query_vec: &EntangledHVec, k: u32, ) -> Result<Vec<RetrievalResult>>

Self::query, refused unless agent_did holds a current read grant. The caller must already have authenticated control of agent_did.

pub fn explain_query( &self, query_vec: &EntangledHVec, k: u32, ) -> QueryExplanation

pub fn index_status(&self) -> IndexStatus

pub fn storage_health(&self) -> StorageHealth

pub fn maintain_indices(&self) -> Result<IndexStatus>

Train any index whose configured threshold has been reached, then return the resulting lifecycle state. Calls are idempotent when indices are current.

pub fn maintain_indices_background( self: &Arc<Self>, ) -> JoinHandle<Result<IndexStatus>>

Run maintenance on a dedicated thread; training publishes only a current snapshot.

pub fn flush(&self) -> Result<()>

Flush persistent vector data to durable storage.

pub fn query_hopfield( &self, query_vec: &EntangledHVec, max_results: u32, ) -> Vec<RetrievalResult>

Energy-based associative retrieval using Hopfield-Fenchel-Young dynamics.

Unlike query (which returns a fixed top-k by similarity), this uses sparse entmax attention to naturally determine how many results are relevant. Returns at most max_results patterns with non-zero Hopfield attention weight.

pub fn query_batch( &self, queries: &[EntangledHVec], k: u32, ) -> Vec<Vec<RetrievalResult>>

Process multiple queries in parallel using rayon.

pub fn analyze_components(&self, vector: &EntangledHVec) -> Vec<RetrievalResult>

Analyze components of a vector by finding its nearest neighbors. Filters by similarity threshold from QueryConfig (default 0.05).

impl HmsCore

pub fn new( dimensions: u32, storage_path: Option<String>, config: Option<HmsConfig>, ) -> Result<Self>

Create a new HMS instance. If storage_path is None, uses the current directory.

impl HmsCore

pub fn bundle<V: Borrow<EntangledHVec>>(&self, vectors: &[V]) -> EntangledHVec

Bundle vectors respecting the PrivacyConfig. When dp_enabled, uses Laplace noise with the configured epsilon.

pub fn dimensions(&self) -> usize

Returns the dimensionality of the hypervector space.

pub fn encode_text(&self, text: &str) -> EntangledHVec

Encode text into a sparse hypervector using multi-scale n-grams and word tokens.

pub fn analyze_text(&self, text: &str) -> TextMetrics

Compute word, sentence, syllable, and character-class counts for text.

pub fn calculate_readability(&self, metrics: &TextMetrics) -> f64

Compute Flesch Reading Ease score from text metrics.

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

Delete a vector by ID. Returns true if it existed. Crash-safe: tombstone is persisted first.

pub fn delete_with_reason(&self, id: &str, reason: Option<&str>) -> Result<bool>

pub fn memorize_meaning(&self, id: &str, text: &str) -> Result<()>

pub fn memorize_meaning_with_source( &self, id: &str, text: &str, source_uri: Option<&str>, ) -> Result<()>

pub fn memorize(&self, id: String, vector: EntangledHVec) -> Result<()>

Store a vector with the given ID. Persists to the arena log and updates all indices.

pub fn memorize_vector(&self, id: String, dense: &[f32]) -> Result<()>

Convert a dense f32 vector to sparse and memorize it.

pub fn memorize_scalar( &self, id: String, value: f64, min: f64, max: f64, ) -> Result<()>

Encode a bounded scalar value as a hypervector and memorize it.

pub fn vector_count(&self) -> u64

Returns the total number of stored vectors across all shards.

pub fn add_relation(&self, rel: &Relation) -> Result<()>

pub fn remove_relation( &self, source_id: &str, relation_type: &str, target_id: &str, ) -> Result<bool>

pub fn declare_relation_type(&self, rel_type: RelationType) -> Result<()>

pub fn traverse( &self, start_id: &str, relation_type: Option<&str>, max_depth: u32, at_time: f64, ) -> Vec<GraphPath>

pub fn outgoing_relations( &self, source_id: &str, relation_type: Option<&str>, at_time: f64, ) -> Vec<Relation>

pub fn incoming_relations( &self, target_id: &str, relation_type: Option<&str>, at_time: f64, ) -> Vec<Relation>

pub fn relation_count(&self) -> usize

pub fn federated_query( &self, peer_paths: &[String], query_vec: &EntangledHVec, k: u32, ) -> Result<Vec<RetrievalResult>>

Query across local instance and remote peers in parallel.

Improvements over naive collect-sort-truncate:

• BinaryHeap merge: O(N log k) top-k selection instead of O(N log N) sort.
• ID deduplication: same document appearing in multiple peers is counted once (highest similarity wins).
• Partial failure tolerance: a failed peer logs a warning and is skipped rather than aborting the entire query.

pub fn structural_query( &self, known: &[(&str, &EntangledHVec)], target_role: &str, ) -> Vec<StructuralResult>

pub fn multi_hop(&self, start: &str, relations: &[&str]) -> Vec<MultiHopResult>

pub fn meaning_cleanup(&self, noisy: &EntangledHVec) -> Option<(String, f64)>

pub fn declare_rule( &self, name: &str, input_relations: Vec<String>, output_relation: String, ) -> Result<()>

pub fn meaning_enabled(&self) -> bool

pub fn meaning_atom_count(&self) -> usize

pub fn meaning_composite_count(&self) -> usize

pub fn meaning_triple_count(&self) -> usize

pub fn meaning_rule_count(&self) -> usize

pub fn register_role(&mut self, name: &str, shift: usize) -> Result<()>

pub fn start_cognition(&self) -> Result<()>

pub fn stop_cognition(&self)

pub fn cognition_running(&self) -> bool

pub fn cognition_cycle_count(&self) -> u64

pub fn take_insights(&self) -> Vec<Insight>

pub fn cognition_insight_count(&self) -> usize

pub fn run_cognition_once(&self) -> Vec<Insight>

pub fn govern_memory(&self) -> GovernanceReport

pub fn cognition_enabled(&self) -> bool

pub fn add_goal( &self, name: &str, description: &str, relevance: f64, urgency: f64, cost: f64, ) -> Option<usize>

pub fn deactivate_goal(&self, name: &str) -> bool

pub fn active_goals(&self) -> Vec<(String, f64)>

pub fn plan_goal( &self, goal: &str, causal_relations: &[&str], max_depth: usize, ) -> Plan

pub fn generate_questions(&self) -> Vec<Question>

pub fn propose_rule( &self, name: &str, input_relations: Vec<String>, output_relation: &str, reason: &str, ) -> Option<usize>

pub fn approve_proposal(&self, id: usize) -> bool

pub fn reject_proposal(&self, id: usize) -> bool

pub fn pending_proposals(&self) -> usize

pub fn goal_count(&self) -> usize

pub fn active_goal_count(&self) -> usize

pub fn ivf_trained(&self) -> bool

Returns true if the IVF index has been trained.

pub fn train_ivf(&self) -> Result<()>

Train the IVF index on current vectors. Persists the index to disk.

pub fn nsg_trained(&self) -> bool

Returns true if the NSG graph index has been trained.

pub fn train_nsg(&self) -> Result<()>

Train the NSG graph index on current vectors. Persists the index to disk.

pub fn audit_since(&self, timestamp_ms: u64) -> Result<Vec<AuditEntry>>

Query the audit log for entries since timestamp_ms. Returns an empty vec if audit logging is disabled.

pub fn provenance_enabled(&self) -> bool

pub fn create_fact_provenance( &self, fact_id: &str, content: &[u8], source_uri: Option<&str>, ) -> Result<ProvenanceRecord>

pub fn create_triple_provenance( &self, params: &TripleProvenanceParams<'_>, ) -> Result<ProvenanceRecord>

pub fn create_store_manifest( &self, store_id: &str, store_data: &[u8], fact_count: usize, dimensions: u32, title: Option<&str>, ) -> Result<StoreManifest>

pub fn verify_fact_provenance( &self, record: &ProvenanceRecord, trust: &TrustStore, ) -> Result<VerificationResult>

pub fn provenance_self_trust(&self) -> Option<TrustStore>

A trust store containing this instance’s own provenance key, for authenticating records it signed. None if provenance is disabled.

pub fn verify_store_manifest( &self, manifest: &StoreManifest, store_data: Option<&[u8]>, trust: &TrustStore, ) -> Result<VerificationResult>

pub fn issuer_did(&self) -> Option<&str>

pub fn get_provenance(&self, fact_id: &str) -> Option<ProvenanceRecord>

pub fn provenance_count(&self) -> usize

pub fn create_self_manifest(&self, title: Option<&str>) -> Result<StoreManifest>

pub fn revoke_credential(&self, status_index: u64) -> Result<()>

pub fn is_credential_revoked(&self, status_index: u64) -> bool

pub fn verify_provenance_log(&self) -> Result<bool>

pub fn create_batch_provenance( &self, items: &[(&str, &[u8], Option<&str>)], ) -> Result<Vec<ProvenanceRecord>>

pub fn create_sigstore_bundle( &self, content: &[u8], identity: Option<&str>, ) -> Result<SigstoreBundle>

pub fn verify_sigstore_bundle( &self, bundle: &SigstoreBundle, content: &[u8], trusted_key: &VerifyingKey, ) -> Result<()>

pub fn create_cawg_assertion( &self, referenced: &[(String, String, Vec<u8>)], display_name: &str, ) -> Result<Value>

pub fn verify_cawg_assertion( &self, assertion: &Value, trust: &TrustStore, ) -> Result<Value>

pub fn factorize_diffusion( &self, product: &EntangledHVec, domain_codebooks: &[Vec<EntangledHVec>], max_iter: usize, ) -> Vec<Option<EntangledHVec>>

Decompose a product vector into factors from domain codebooks using diffusion.