Struct BeliefStore 

pub struct BeliefStore { /* private fields */ }

Persistence layer for the pre-commitment probabilistic edge layer.

All mutations go through this type: creating new beliefs, applying Noisy-OR evidence updates, marking beliefs as promoted, and evicting stale candidates.

Obtain an instance via BeliefStore::new after running the zeph-db migrations.

Implementations

impl BeliefStore

pub fn new(pool: DbPool, config: BeliefMemConfig) -> Self

Create a new BeliefStore wrapping pool with the given configuration.

Examples

use zeph_memory::graph::belief::{BeliefStore, BeliefMemConfig};
use zeph_db::DbPool;

async fn example(pool: DbPool) {
    let store = BeliefStore::new(pool, BeliefMemConfig::default());
}

pub async fn record_evidence( &self, source_entity_id: i64, target_entity_id: i64, relation: &str, canonical_relation: &str, fact: &str, edge_type: EdgeType, evidence_prob: f32, episode_id: Option<&str>, ) -> Result<Option<PendingBelief>, MemoryError>

Record new evidence for a candidate edge and apply Noisy-OR accumulation.

If a matching pending_belief exists for the same (source_entity_id, target_entity_id, canonical_relation, edge_type) tuple, this method:

1. Applies optional temporal decay to the existing probability.
2. Combines the decayed probability with evidence_prob via Noisy-OR.
3. Persists the update and appends a row to belief_evidence.

If no matching belief exists and evidence_prob >= min_entry_prob, a new belief row is created.

Returns Some(PendingBelief) when the updated probability crosses promote_threshold. The caller is responsible for calling GraphStore::insert_or_supersede to commit the promoted belief, then calling BeliefStore::mark_promoted to record the committed edge ID.

Returns None when the belief exists but has not yet crossed the threshold, or when evidence_prob < min_entry_prob and no prior belief existed.

Errors

Returns MemoryError for database failures.

pub async fn retrieve_candidates( &self, source_entity_id: i64, canonical_relation: &str, top_k: Option<usize>, ) -> Result<Vec<PendingBelief>, MemoryError>

Retrieve the top-K unpromoted beliefs for a (source, canonical_relation) pair, ordered by probability descending.

This is a fallback for graph recall: called only when no committed edge exists. Results are annotated by the caller as uncertain (is_uncertain: true).

Errors

Returns MemoryError for database failures.

pub async fn mark_promoted( &self, belief_id: i64, committed_edge_id: i64, ) -> Result<(), MemoryError>

Mark a belief as promoted and record the committed edge ID.

Sets promoted_at to the current Unix timestamp and stores committed_edge_id so the belief audit trail links to the committed graph edge.

Errors

Returns MemoryError for database failures.

pub async fn evict_stale( &self, source_entity_id: i64, canonical_relation: &str, ) -> Result<usize, MemoryError>

Evict old low-probability beliefs for a (source, canonical_relation) group that exceed BeliefMemConfig::max_candidates_per_group.

The max_candidates_per_group highest-probability beliefs are retained; the rest are deleted. Returns the number of rows deleted.

Errors

Returns MemoryError for database failures.