Struct ProjectionTracker 

pub struct ProjectionTracker { /* private fields */ }

Projection lifecycle tracker.

Tracks the health and staleness metadata of all projections. Projections are identified by ProjectionId which includes scope.

Authority: Observability only, NOT orchestration

This tracker is a passive bookkeeping / observability component. It records state transitions (build, invalidation, failure) so that callers can inspect projection health and decide whether to trigger rebuilds. Current methods emit Healthy, Stale, and Missing; other ProjectionHealth variants remain reserved for compatibility and external orchestration surfaces. The tracker does NOT:

• Schedule or execute projection rebuilds
• Retry failed builds automatically
• Communicate with upstream import pipelines
• Own any source of truth

Callers are responsible for executing rebuilds and reporting outcomes via record_build() / record_failure().

Implementations

impl ProjectionTracker

pub fn new(staleness_threshold_secs: u64) -> Self

pub fn record_build( &mut self, id: ProjectionId, source_count: usize, build_duration_ms: u64, version: Option<ProjectionVersion>, )

Record that a projection was successfully built.

This is a bookkeeping method, not a rebuild trigger. The tracker records that a build occurred but does not execute, schedule, or orchestrate any rebuild work. External callers must drive the actual rebuild and call this method to report the outcome.

pub fn record_failure(&mut self, id: ProjectionId, error: String)

Record that a projection build failed.

This is a bookkeeping method, not a retry trigger. The tracker records the failure but does not retry, schedule, or orchestrate any rebuild attempt. External callers must decide whether and when to retry, and call record_build() or record_failure() to report the next outcome.

pub fn invalidate( &mut self, event: &InvalidationEvent, ) -> ProjectionActionResult

Process an invalidation event, marking affected projections as stale.

pub fn invalidate_by_kind_and_scope( &mut self, kind: &ProjectionKind, scope: &ScopeKey, cause: StaleCause, ) -> ProjectionActionResult

Invalidate all projections of a given kind within a scope.

pub fn invalidate_scope( &mut self, scope: &ScopeKey, cause: StaleCause, ) -> ProjectionActionResult

Invalidate all projections within a scope (all kinds).

pub fn health(&self, id: &ProjectionId) -> ProjectionHealth

Get the health of a specific projection (with time-based staleness check).

pub fn get(&self, id: &ProjectionId) -> Option<&ProjectionMeta>

Get metadata for a specific projection.

pub fn all_ids(&self) -> impl Iterator<Item = &ProjectionId>

Iterate over all tracked projection IDs.

Useful for external rebuild drivers that need to scan for stale projections.

pub fn query_status( &self, kind: Option<&ProjectionKind>, scope: Option<&ScopeKey>, ) -> Vec<&ProjectionMeta>

Query status of all projections matching a kind and/or scope filter.

pub fn list(&self) -> Vec<&ProjectionMeta>

List all tracked projections.

pub fn remove(&mut self, id: &ProjectionId) -> Option<ProjectionMeta>

Remove a projection from tracking (forces recomputation on next access).

pub fn clear_scope(&mut self, scope: &ScopeKey) -> ProjectionActionResult

Clear all projections within a scope.

Trait Implementations

impl Debug for ProjectionTracker

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

Formats the value using the given formatter.