Struct KnowledgeBase 

pub struct KnowledgeBase { /* private fields */ }

Thread-safe, indexed knowledge shared by evidence and decision engines.

Writes are atomic across primary records and secondary indexes. Read methods return owned snapshots, so callers never keep an internal lock while doing asynchronous work.

Ontology definitions provide domain meaning, while entities and relations form the instance graph. Evidence and entities are immutable once their IDs are observed. Facts, hypotheses, and relations may be updated only while their claim identity or graph identity remains unchanged.

Examples

use termivar_core::{
    ConfidenceScore, EntityId, Evidence, EvidenceKind, EvidenceSource,
    EvidenceValue, KnowledgePredicate,
};
use termivar_scanner::{KnowledgeBase, KnowledgeWrite};

let knowledge = KnowledgeBase::new();
let subject = EntityId::new("endpoint:https://example.test")?;
let predicate = KnowledgePredicate::new("http.header", "server")?;
let evidence = Evidence::new(
    subject.clone(),
    EvidenceKind::Http,
    predicate.clone(),
    EvidenceValue::Text("nginx".into()),
    EvidenceSource::new("discovery.headers", "server-header")?,
    ConfidenceScore::from_percent(85)?,
);

assert_eq!(knowledge.insert_evidence(evidence)?, KnowledgeWrite::Inserted);
assert_eq!(knowledge.evidence_for_subject(&subject).len(), 1);
assert_eq!(knowledge.evidence_for_predicate(&predicate).len(), 1);

Implementations

impl KnowledgeBase

pub fn derivation_children(&self, parent: &EvidenceId) -> BTreeSet<EvidenceId>

Returns the derived evidence records computed directly from parent, ordered by evidence ID. Forward lineage (a derived record’s exact parents) is read from that record’s termivar_core::EvidenceOrigin.

pub fn evidence(&self, id: &EvidenceId) -> Option<Evidence>

Returns an evidence snapshot by ID.

pub fn fact(&self, id: &str) -> Option<Fact>

Returns a fact snapshot by ID.

pub fn hypothesis(&self, id: &str) -> Option<Hypothesis>

Returns a hypothesis snapshot by ID.

pub fn evidence_for_subject(&self, subject: &EntityId) -> Vec<Evidence>

Returns evidence describing a subject, ordered by evidence ID.

pub fn evidence_for_predicate( &self, predicate: &KnowledgePredicate, ) -> Vec<Evidence>

Returns evidence matching a predicate, ordered by evidence ID.

pub fn facts_for_subject(&self, subject: &EntityId) -> Vec<Fact>

Returns facts describing a subject, ordered by fact ID.

pub fn facts_for_predicate(&self, predicate: &KnowledgePredicate) -> Vec<Fact>

Returns facts matching a predicate, ordered by fact ID.

pub fn hypotheses_for_subject(&self, subject: &EntityId) -> Vec<Hypothesis>

Returns hypotheses describing a subject, ordered by hypothesis ID.

pub fn hypotheses_for_predicate( &self, predicate: &KnowledgePredicate, ) -> Vec<Hypothesis>

Returns hypotheses matching a predicate, ordered by hypothesis ID.

impl KnowledgeBase

pub fn insert_evidence_with_relation( &self, evidence: Evidence, relation: KnowledgeRelation, ) -> Result<(KnowledgeWrite, KnowledgeWrite), KnowledgeBaseError>

Atomically inserts one immutable observation and its sole graph edge.

The relation must cite exactly the supplied evidence ID. Both identity conflicts are checked before either record or secondary index changes, so callers never persist an orphaned half of the bundle. Relation IDs, endpoints, custom kinds, and provenance are checked against the compiled storage ceilings before either record is written.

pub fn insert_entity( &self, entity: KnowledgeEntity, ) -> Result<KnowledgeWrite, KnowledgeBaseError>

Inserts one immutable knowledge-graph entity.

pub fn upsert_relation( &self, relation: KnowledgeRelation, ) -> Result<KnowledgeWrite, KnowledgeBaseError>

Inserts a relation or updates its confidence and provenance.

The source, destination, and relation kind form the immutable graph identity for an existing relation ID. Every field and provenance ID is validated against the compiled relation storage ceilings first.

pub fn entity(&self, id: &EntityId) -> Option<KnowledgeEntity>

Returns an entity snapshot by ID.

pub fn relation(&self, id: &RelationId) -> Option<KnowledgeRelation>

Returns a relation snapshot by ID.

pub fn relations_from(&self, entity_id: &EntityId) -> Vec<KnowledgeRelation>

Returns outgoing graph relations, ordered by relation ID.

pub fn relations_to(&self, entity_id: &EntityId) -> Vec<KnowledgeRelation>

Returns incoming graph relations, ordered by relation ID.

pub fn relations_to_page( &self, entity_id: &EntityId, after_exclusive: Option<&RelationId>, limit: usize, ) -> Vec<KnowledgeRelation>

Returns one bounded page of incoming relations in stable ID order.

after_exclusive is an exclusive cursor and does not need to identify a stored relation. At most limit indexed records are cloned. A zero limit returns immediately without reading the store.

impl KnowledgeBase

pub fn snapshot_for_subject(&self, subject: &EntityId) -> KnowledgeSnapshot

Captures all rule-visible knowledge for a subject under one read lock.

impl KnowledgeBase

pub fn new() -> Self

Creates an empty knowledge base with standard ontology relation types.

pub fn register_concept( &self, concept: OntologyConcept, ) -> Result<OntologyWrite, OntologyError>

Registers a domain concept in the ontology.

pub fn register_relation_type( &self, relation_type: OntologyRelationType, ) -> Result<OntologyWrite, OntologyError>

Registers a custom semantic relation type in the ontology.

pub fn register_axiom( &self, axiom: OntologyAxiom, ) -> Result<OntologyWrite, OntologyError>

Registers a validated semantic axiom in the ontology.

pub fn ontology_snapshot(&self) -> Ontology

Returns an owned, internally consistent ontology snapshot.

pub fn ontology_is_related( &self, subject: &ConceptId, relation: &RelationTypeId, object: &ConceptId, ) -> Result<bool, OntologyError>

Evaluates a semantic relationship using the registered ontology.

pub fn ontology_is_a( &self, child: &ConceptId, ancestor: &ConceptId, ) -> Result<bool, OntologyError>

Evaluates the canonical transitive ontology hierarchy.

pub fn stats(&self) -> KnowledgeBaseStats

Returns a consistent count snapshot under one read lock.

impl KnowledgeBase

pub fn insert_evidence( &self, evidence: Evidence, ) -> Result<KnowledgeWrite, KnowledgeBaseError>

Inserts one immutable observation.

Repeating the exact record is idempotent. Reusing an evidence ID for a different observation is rejected because provenance IDs are immutable.

pub fn insert_evidence_batch( &self, evidence: Vec<Evidence>, ) -> Result<Vec<KnowledgeWrite>, KnowledgeBaseError>

Inserts an evidence batch in one write transaction.

Every identity is validated before the first record is written. If an existing record or another item in the batch reuses an evidence ID for different meaning, the complete batch is rejected without changing the knowledge base. Results preserve input order; exact duplicates are idempotent.

pub fn upsert_fact( &self, fact: Fact, ) -> Result<KnowledgeWrite, KnowledgeBaseError>

Inserts a materialized fact or updates its confidence and provenance.

The subject, predicate, and value form the immutable claim identity for an existing fact ID.

pub fn upsert_hypothesis( &self, hypothesis: Hypothesis, ) -> Result<KnowledgeWrite, KnowledgeBaseError>

Inserts a hypothesis or updates its Bayesian evaluation.

The subject, predicate, and value form the immutable claim identity for an existing hypothesis ID.

pub fn upsert_hypothesis_batch( &self, hypotheses: Vec<Hypothesis>, ) -> Result<Vec<KnowledgeWrite>, KnowledgeBaseError>

Inserts or updates a hypothesis batch in one write transaction.

Every stored and intra-batch identity is validated before the first hypothesis or secondary index changes. Reusing an ID for a different claim, or supplying different evaluations for one ID in the same batch, rejects the complete batch. Results preserve input order; semantically exact duplicates are idempotent even when their update timestamps differ.

Trait Implementations

impl Clone for KnowledgeBase

fn clone(&self) -> KnowledgeBase

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KnowledgeBase

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

Formats the value using the given formatter.

impl Default for KnowledgeBase

fn default() -> KnowledgeBase

Returns the “default value” for a type.