parlov-core 0.5.0

//! Typed observations extracted from differential analysis.

use serde::{Deserialize, Serialize};

/// A typed observation extracted from differential analysis.
///
/// Each signal represents one piece of evidence: a status code difference, a header that appeared
/// on one side but not the other, a body content change, etc. Signals are the atoms that
/// classifiers compose into verdicts.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Signal {
    /// What category of differential this signal represents.
    pub kind: SignalKind,
    /// Human-readable description of the observation, e.g. `"304 vs 404"`.
    pub evidence: String,
    /// RFC section grounding the expected behavior, e.g. `"RFC 9110 \u{00a7}13.1.2"`.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub rfc_basis: Option<String>,
}

/// Categories of observable differential signals.
///
/// Each variant maps to a distinct signal extractor in `parlov-analysis`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum SignalKind {
    /// Status codes differ between baseline and probe responses.
    StatusCodeDiff,
    /// A response header is present in one set but absent in the other.
    HeaderPresence,
    /// A response header has different values across baseline and probe sets.
    HeaderValue,
    /// Response body content differs between sets.
    BodyDiff,
    /// Response timing distributions differ (statistical significance required).
    TimingDiff,
    /// A response header leaks additional metadata, e.g. `Content-Range` reveals resource size.
    MetadataLeak,
}

/// Classification of leak impact, independent of confidence.
///
/// Determines severity when gated by confidence threshold. Computed from the peak leak type
/// among validated signals — existence-only is `Low`, metadata disclosure is `Medium`, sensitive
/// metadata (exact sizes, internal state) is `High`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum ImpactClass {
    /// Existence confirmed, no metadata disclosed.
    Low,
    /// Metadata disclosed (validators, auth scheme, timing).
    Medium,
    /// Sensitive metadata disclosed (exact size, internal state).
    High,
}