evidential_protocol/

validate.rs

//! Validation for EP/1.0 structures.
//!
//! Produces a list of [`ValidationError`]s with severity levels so callers
//! can distinguish hard failures from advisory warnings.

use crate::types::*;
use serde::Serialize;

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/// Severity of a validation finding.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Severity {
    /// Must be fixed — the structure is invalid.
    Error,
    /// Advisory — the structure is technically valid but sub-optimal.
    Warning,
}

/// A single validation finding.
#[derive(Debug, Clone)]
pub struct ValidationError {
    /// Short rule identifier (e.g. "confidence_floor").
    pub rule: String,
    /// Human-readable description.
    pub message: String,
    /// JSON-path-style location of the problem (e.g. "claims[0].evidence").
    pub path: Option<String>,
    /// Whether this is a hard error or advisory warning.
    pub severity: Severity,
}

/// Aggregated result of validating a full response.
#[derive(Debug)]
pub struct ValidationResult {
    /// `true` only if there are zero errors (warnings are allowed).
    pub valid: bool,
    /// All findings with [`Severity::Error`].
    pub errors: Vec<ValidationError>,
    /// All findings with [`Severity::Warning`].
    pub warnings: Vec<ValidationError>,
}

// ---------------------------------------------------------------------------
// Evidence validation
// ---------------------------------------------------------------------------

/// Validate a single [`Evidence`] value.
///
/// Returns a (possibly empty) list of findings. The `path` prefix is used to
/// build JSON-path-style locations in error messages.
pub fn validate_evidence(evidence: &Evidence, path: &str) -> Vec<ValidationError> {
    let mut findings: Vec<ValidationError> = Vec::new();

    // confidence must be in [0.0, 1.0]
    if evidence.confidence < 0.0 || evidence.confidence > 1.0 {
        findings.push(ValidationError {
            rule: "confidence_range".to_string(),
            message: format!(
                "Confidence {} is outside the valid range [0.0, 1.0]",
                evidence.confidence
            ),
            path: Some(format!("{path}.confidence")),
            severity: Severity::Error,
        });
    }

    // confidence must meet the class floor
    if evidence.confidence < evidence.class.confidence_floor() {
        findings.push(ValidationError {
            rule: "confidence_floor".to_string(),
            message: format!(
                "Confidence {} is below the floor {} for class {}",
                evidence.confidence,
                evidence.class.confidence_floor(),
                evidence.class,
            ),
            path: Some(format!("{path}.confidence")),
            severity: Severity::Error,
        });
    }

    // source must not be empty
    if evidence.source.trim().is_empty() {
        findings.push(ValidationError {
            rule: "source_required".to_string(),
            message: "Evidence source must not be empty".to_string(),
            path: Some(format!("{path}.source")),
            severity: Severity::Error,
        });
    }

    // timestamp must not be empty
    if evidence.timestamp.trim().is_empty() {
        findings.push(ValidationError {
            rule: "timestamp_required".to_string(),
            message: "Evidence timestamp must not be empty".to_string(),
            path: Some(format!("{path}.timestamp")),
            severity: Severity::Error,
        });
    }

    // Conjecture MUST have reasoning
    if evidence.class == EvidenceClass::Conjecture && evidence.reasoning.is_none() {
        findings.push(ValidationError {
            rule: "conjecture_reasoning".to_string(),
            message: "Conjecture evidence must include reasoning".to_string(),
            path: Some(format!("{path}.reasoning")),
            severity: Severity::Error,
        });
    }

    // Direct SHOULD have ttl
    if evidence.class == EvidenceClass::Direct && evidence.ttl.is_none() {
        findings.push(ValidationError {
            rule: "direct_ttl".to_string(),
            message: "Direct evidence should specify a TTL for cache freshness".to_string(),
            path: Some(format!("{path}.ttl")),
            severity: Severity::Warning,
        });
    }

    findings
}

// ---------------------------------------------------------------------------
// Claim validation
// ---------------------------------------------------------------------------

/// Validate a single [`EvidentialClaim`] at the given index.
pub fn validate_claim(claim: &EvidentialClaim, index: usize) -> Vec<ValidationError> {
    let mut findings: Vec<ValidationError> = Vec::new();
    let path = format!("claims[{index}]");

    if claim.claim.trim().is_empty() {
        findings.push(ValidationError {
            rule: "claim_text_required".to_string(),
            message: "Claim text must not be empty".to_string(),
            path: Some(path.clone()),
            severity: Severity::Error,
        });
    }

    findings.extend(validate_evidence(&claim.evidence, &format!("{path}.evidence")));

    findings
}

// ---------------------------------------------------------------------------
// Response validation
// ---------------------------------------------------------------------------

/// Validate a complete [`EvidentialResponse`].
///
/// Checks envelope-level constraints and delegates to per-claim validation.
pub fn validate_response<T: Serialize>(response: &EvidentialResponse<T>) -> ValidationResult {
    let mut errors: Vec<ValidationError> = Vec::new();
    let mut warnings: Vec<ValidationError> = Vec::new();

    // ep_version must be "1.0"
    if response.ep_version != "1.0" {
        errors.push(ValidationError {
            rule: "ep_version".to_string(),
            message: format!(
                "Unsupported EP version \"{}\"; expected \"1.0\"",
                response.ep_version
            ),
            path: Some("ep_version".to_string()),
            severity: Severity::Error,
        });
    }

    // producer must not be empty
    if response.producer.trim().is_empty() {
        errors.push(ValidationError {
            rule: "producer_required".to_string(),
            message: "Producer must not be empty".to_string(),
            path: Some("producer".to_string()),
            severity: Severity::Error,
        });
    }

    // must have at least one claim
    if response.claims.is_empty() {
        errors.push(ValidationError {
            rule: "claims_required".to_string(),
            message: "Response must contain at least one claim".to_string(),
            path: Some("claims".to_string()),
            severity: Severity::Error,
        });
    }

    // validate each claim
    for (i, claim) in response.claims.iter().enumerate() {
        for finding in validate_claim(claim, i) {
            match finding.severity {
                Severity::Error => errors.push(finding),
                Severity::Warning => warnings.push(finding),
            }
        }
    }

    // aggregate_class must be the weakest class among all claims
    if !response.claims.is_empty() {
        let weakest = response
            .claims
            .iter()
            .map(|c| c.evidence.class)
            .min_by_key(|c| c.strength())
            .unwrap();

        if response.aggregate_class != weakest {
            errors.push(ValidationError {
                rule: "aggregate_class_weakest".to_string(),
                message: format!(
                    "Aggregate class \"{}\" does not match weakest claim class \"{}\"",
                    response.aggregate_class, weakest
                ),
                path: Some("aggregate_class".to_string()),
                severity: Severity::Error,
            });
        }
    }

    ValidationResult {
        valid: errors.is_empty(),
        errors,
        warnings,
    }
}