Struct TensorLogicStore 

pub struct TensorLogicStore<S: BlockStore> { /* private fields */ }

Storage manager for TensorLogic IR

Stores terms, predicates, and rules as content-addressed blocks

Implementations

impl<S: BlockStore> TensorLogicStore<S>

pub fn new(store: Arc<S>) -> Result<Self>

Create a new TensorLogic store

pub fn kb_version(&self) -> u64

Return the current KB version counter (monotonically increasing).

pub fn inference_cache_stats(&self) -> CacheStats

Access the inference cache statistics.

pub async fn store_term(&self, term: &Term) -> Result<Cid>

Store a term and return its CID

pub async fn get_term(&self, cid: &Cid) -> Result<Option<Term>>

Retrieve a term by CID

pub async fn store_predicate(&self, predicate: &Predicate) -> Result<Cid>

Store a predicate and return its CID

pub async fn get_predicate(&self, cid: &Cid) -> Result<Option<Predicate>>

Retrieve a predicate by CID

pub async fn store_rule(&self, rule: &Rule) -> Result<Cid>

Store a rule and return its CID

pub async fn get_rule(&self, cid: &Cid) -> Result<Option<Rule>>

Retrieve a rule by CID

pub async fn has(&self, cid: &Cid) -> Result<bool>

Check if a CID exists in storage

pub async fn delete(&self, cid: &Cid) -> Result<()>

Delete a stored item by CID

pub fn add_fact(&self, fact: Predicate) -> Result<()>

Add a fact to the knowledge base

pub fn add_rule(&self, rule: Rule) -> Result<()>

Add a rule to the knowledge base

pub fn retract_fact(&self, fact: &Predicate) -> Result<bool>

Retract a fact from the knowledge base (removes first matching fact).

pub fn infer(&self, goal: &Predicate) -> Result<Vec<Substitution>>

Run inference query on the knowledge base

Records the wall-clock duration of each call in an internal rolling window of the last 100 durations so that avg_inference_ms can report a meaningful average.

pub fn avg_inference_ms(&self) -> Option<f64>

Average inference duration in milliseconds over the last (up to 100) calls.

Returns None when no inference has been performed yet.

pub fn prove(&self, goal: &Predicate) -> Result<Option<Proof>>

Generate a proof for a goal

pub async fn store_proof(&self, proof: &Proof) -> Result<Cid>

Store a proof and return its CID

pub async fn get_proof(&self, cid: &Cid) -> Result<Option<Proof>>

Retrieve a proof by CID

pub fn verify_proof(&self, proof: &Proof) -> Result<bool>

Verify that a proof is valid against the current knowledge base

pub fn kb_stats(&self) -> KnowledgeBaseStats

Get knowledge base statistics

pub fn estimated_memory_bytes(&self) -> usize

Estimated memory usage in bytes for the in-memory knowledge base.

Uses a conservative heuristic:

• Each rule ≈ 500 bytes (head + body terms + serialised form)
• Each fact ≈ 200 bytes (predicate name + argument terms)

pub fn snapshot_kb(&self) -> Result<KnowledgeBase>

Return a snapshot (clone) of the current in-memory knowledge base.

The returned value is independent of the store; subsequent mutations are not reflected in the snapshot.

pub async fn store_rule_as_block(&self, rule: &Rule) -> Result<Cid>

Store a rule as a content-addressed IPLD block using the DAG-CBOR codec.

Unlike store_rule which serialises via JSON directly, this method goes through the crate::ipld_codec pipeline:

Rule → RuleIpld → Block (DAG-CBOR codec, SHA-256 CID)

Identical rules always produce the same CID, enabling deduplication across the network without reading the block contents.

pub async fn load_rule_from_block(&self, cid: &Cid) -> Result<Rule>

Load a rule that was stored via store_rule_as_block (or any IPLD block whose content is a valid RuleIpld JSON blob).

Returns ipfrs_core::Error::BlockNotFound when the CID is absent.

pub async fn store_kb_as_ipld(&self) -> Result<Cid>

Snapshot the in-memory knowledge base as an IPLD DAG.

Each rule is stored as an individual block (via store_rule_as_block) so that rules already present in the store are not re-written. Facts are stored inline in the root KnowledgeBaseIpld block.

Returns the CID of the root KB block. The caller can pin this CID to prevent garbage-collection of the whole DAG.

pub async fn rule_exists_by_cid(&self, rule: &Rule) -> Result<bool>

Check whether a rule is already present in the block store by computing its content-addressed CID and calling has().

This is a pure deduplication check: it does not add the rule to the in-memory knowledge base or write any block. The conversion is the same pipeline used by store_rule_as_block, so the CID is guaranteed to match.

pub async fn kb_stats_with_cids(&self) -> Result<TensorLogicStoreStats>

Extended knowledge base statistics that include content-addressed block accounting.

cid_indexed_rules reflects how many rules in the in-memory KB are already persisted as DAG-CBOR blocks (i.e., has() returns true for their computed CID). The async check is done concurrently for all rules so this method scales acceptably for large knowledge bases.

pub async fn index_rules_by_predicate( &self, ) -> Result<HashMap<String, Vec<Cid>>>

Build a predicate-name → CID index for all rules currently in the knowledge base by computing each rule’s DAG-CBOR CID.

Rules that fail CID computation are silently skipped. The index is built from the current in-memory snapshot; changes made after this call are not reflected.

This method is used by DistributedBackwardChainer to find DHT providers for relevant predicates without scanning all rules on every query.

pub fn save_snapshot(&self, path: &Path) -> Result<(), TensorLogicError>

Save all rules and facts to a snapshot file.

The snapshot is stored as pretty-printed JSON so it is human-readable and portable across restarts. After a successful save the dirty flag is cleared.

pub fn load_snapshot( &mut self, path: &Path, ) -> Result<KnowledgeBaseSnapshot, TensorLogicError>

Load rules and facts from a previously saved snapshot file.

The snapshot metadata (counts, timestamp, version) is returned. Note: the snapshot stores rules/facts as debug strings for human-readable audit trails. The raw KnowledgeBase is persisted separately via save_kb / load_kb for full round-trip fidelity; this method populates snapshot metadata.

After a successful load the dirty flag is cleared.

pub fn is_dirty(&self) -> bool

Whether the store has unsaved changes since the last snapshot save.

pub async fn save_kb<P: AsRef<Path>>(&self, path: P) -> Result<()>

Save the knowledge base to a file

Serializes the entire knowledge base (facts and rules) to a file for later loading.

Arguments

• path - Path to save the knowledge base file

pub async fn load_kb<P: AsRef<Path>>(&self, path: P) -> Result<()>

Load a knowledge base from a file

Loads a previously saved knowledge base from disk, replacing the current KB.

Arguments

• path - Path to the saved knowledge base file