parlov-analysis 0.4.0

Analysis engine trait and signal detection for parlov.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

//! Analysis engine for parlov: signal detection, statistics, and oracle classification.
//!
//! This crate is pure synchronous computation — no I/O, no async, no network stack. Keeping it
//! isolated from `parlov-probe` means changing statistical thresholds or adding a new oracle
//! pattern does not recompile `reqwest` or `hyper`.
//!
//! # Trait contract
//!
//! Implementors of [`Analyzer`] incrementally evaluate a growing [`DifferentialSet`] via
//! [`Analyzer::evaluate`] and signal when enough samples have been collected. The provided
//! [`Analyzer::analyze`] method wraps `evaluate` for callers that supply a complete set in one
//! shot.

#![deny(clippy::all)]
#![warn(clippy::pedantic)]
#![deny(missing_docs)]

pub mod existence;
pub mod signals;

use parlov_core::{DifferentialSet, OracleClass, OracleResult};

/// Decision returned by [`Analyzer::evaluate`] after inspecting the current sample set.
pub enum SampleDecision {
    /// Enough samples collected; here is the final result.
    Complete(Box<OracleResult>),
    /// Differential detected but not yet confirmed stable — collect one more pair.
    NeedMore,
}

/// Analyzes paired baseline/probe exchanges and produces an oracle verdict.
///
/// Implementors must be `Send + Sync` so they can be held in shared state across async tasks.
/// All methods take `&self` — analyzers are stateless with respect to individual probe runs.
pub trait Analyzer: Send + Sync {
    /// Incrementally evaluate a growing `DifferentialSet`.
    ///
    /// Called after each new exchange pair is added. Returns `NeedMore` until enough samples
    /// are collected to determine stability, then `Complete` with the final result.
    fn evaluate(&self, data: &DifferentialSet) -> SampleDecision;

    /// The oracle class this analyzer handles.
    fn oracle_class(&self) -> OracleClass;

    /// Analyze a fully-collected `DifferentialSet` and return a verdict.
    ///
    /// Provided method that delegates to [`evaluate`][Self::evaluate]. Exists for callers that
    /// supply a complete set in one shot rather than driving the incremental sampling loop.
    ///
    /// # Panics
    ///
    /// Panics when `evaluate` returns `NeedMore`, meaning the supplied set has fewer samples
    /// than this analyzer requires.
    fn analyze(&self, data: &DifferentialSet) -> OracleResult {
        match self.evaluate(data) {
            SampleDecision::Complete(result) => *result,
            SampleDecision::NeedMore => {
                panic!("analyze called with insufficient samples; use evaluate to drive sampling")
            }
        }
    }
}