Struct CausalDistanceComputer 

pub struct CausalDistanceComputer { /* private fields */ }

Causal distance computer backed by MAGMA graph BFS.

Computes the shortest causal-edge hop count between the current goal entity and each candidate entity. BFS is bounded by max_depth to satisfy NFR-003. Results are cached per goal entity id to avoid re-traversal within the same turn.

Implementations

impl CausalDistanceComputer

pub fn new( graph_store: Arc<GraphStore>, max_depth: u32, neutral_distance: u32, ) -> Self

Create a new computer.

Parameters

• max_depth: BFS hop limit (default: 10).
• neutral_distance: distance assigned to unreachable entities (default: 5).

pub async fn compute( &mut self, goal_entity_id: Option<i64>, entity_ids: &[i64], ) -> Result<HashMap<i64, u32>, MemoryError>

Compute causal distances from goal_entity_id to each entity in entity_ids.

Returns a map of entity_id → causal distance where unreachable or missing entities receive neutral_distance. When goal_entity_id is None, returns an empty map (callers treat absent entries as neutral, contributing zero to the signal per FR-006).

BFS result is cached per goal_entity_id; the cache is invalidated only when the goal entity changes.

Errors

Returns an error if the graph BFS query fails.

pub fn distance_to_score(distance: u32) -> f64

Convert a raw causal distance to a score in [0.0, 1.0].

Distance 1 → 1.0, distance 5 → 0.2, neutral_distance → neutral value. Distance 0 (goal entity itself) → 1.0 (clamped).

pub fn invalidate_cache(&mut self)

Invalidate the BFS cache. Call at turn boundaries when the goal entity may change.