ruvix_types/

proof.rs

//! Proof-gated mutation types (ADR-047 integration).
//!
//! In RuVix, proof-gated mutation is a kernel invariant. The kernel physically
//! prevents state mutation without a valid proof token.

/// Proof tier determining verification complexity.
///
/// Higher tiers provide stronger guarantees but take longer to verify.
/// The scheduler may route based on proof tier.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum ProofTier {
    /// Sub-microsecond hash check. For high-frequency vector updates.
    /// Uses precomputed proof cache when available.
    Reflex = 0,

    /// Merkle witness verification. For graph mutations.
    /// Verifies against a Merkle root of the current state.
    Standard = 1,

    /// Full coherence verification with mincut analysis.
    /// For structural changes that affect graph partitioning.
    Deep = 2,
}

impl ProofTier {
    /// Returns the tier name as a string.
    #[inline]
    #[must_use]
    pub const fn as_str(&self) -> &'static str {
        match self {
            Self::Reflex => "Reflex",
            Self::Standard => "Standard",
            Self::Deep => "Deep",
        }
    }

    /// Returns the maximum allowed verification time in microseconds.
    #[inline]
    #[must_use]
    pub const fn max_verification_time_us(&self) -> u32 {
        match self {
            Self::Reflex => 1,       // <1us
            Self::Standard => 100,   // <100us
            Self::Deep => 10_000,    // <10ms
        }
    }

    /// Converts from a raw u8 value.
    #[inline]
    #[must_use]
    pub const fn from_u8(value: u8) -> Option<Self> {
        match value {
            0 => Some(Self::Reflex),
            1 => Some(Self::Standard),
            2 => Some(Self::Deep),
            _ => None,
        }
    }
}

impl Default for ProofTier {
    fn default() -> Self {
        Self::Standard
    }
}

/// Proof payload containing the actual proof data.
///
/// The kernel verifies the proof payload according to the tier.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
pub enum ProofPayload {
    /// Hash check payload for Reflex tier.
    /// Contains a 32-byte hash of the mutation.
    Hash {
        /// SHA-256 hash of the mutation data.
        hash: [u8; 32],
    },

    /// Merkle witness for Standard tier.
    /// Contains the Merkle path from leaf to root.
    MerkleWitness {
        /// Root hash of the Merkle tree.
        root: [u8; 32],
        /// Leaf index in the Merkle tree.
        leaf_index: u32,
        /// Number of path elements (max 32 for depth-32 tree).
        path_len: u8,
        /// Path elements (siblings along the path).
        /// Only first `path_len` elements are valid.
        path: [[u8; 32]; 32],
    },

    /// Coherence certificate for Deep tier.
    /// Contains coherence scores and partition metadata.
    CoherenceCert {
        /// Coherence score before mutation (0.0-1.0 as u16, 0-10000).
        score_before: u16,
        /// Expected coherence score after mutation.
        score_after: u16,
        /// Partition ID affected by the mutation.
        partition_id: u32,
        /// Signature over the coherence data.
        signature: [u8; 64],
    },
}

impl Default for ProofPayload {
    fn default() -> Self {
        Self::Hash { hash: [0u8; 32] }
    }
}

/// A proof token authorizing a specific mutation.
///
/// Generated by the Proof Engine and consumed by a mutating syscall.
/// Proof tokens are single-use (nonce prevents replay).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
pub struct ProofToken {
    /// Hash of the mutation being authorized.
    pub mutation_hash: [u8; 32],

    /// Proof tier (Reflex, Standard, Deep).
    pub tier: ProofTier,

    /// The proof payload (varies by tier).
    pub payload: ProofPayload,

    /// Expiry timestamp (nanoseconds since epoch).
    /// Proofs are time-bounded to prevent replay.
    pub valid_until_ns: u64,

    /// Nonce to prevent proof reuse.
    pub nonce: u64,
}

impl ProofToken {
    /// Creates a new proof token.
    #[inline]
    #[must_use]
    pub const fn new(
        mutation_hash: [u8; 32],
        tier: ProofTier,
        payload: ProofPayload,
        valid_until_ns: u64,
        nonce: u64,
    ) -> Self {
        Self {
            mutation_hash,
            tier,
            payload,
            valid_until_ns,
            nonce,
        }
    }

    /// Checks if the proof token has expired.
    #[inline]
    #[must_use]
    pub const fn is_expired(&self, current_time_ns: u64) -> bool {
        current_time_ns > self.valid_until_ns
    }
}

impl Default for ProofToken {
    fn default() -> Self {
        Self {
            mutation_hash: [0u8; 32],
            tier: ProofTier::Standard,
            payload: ProofPayload::default(),
            valid_until_ns: 0,
            nonce: 0,
        }
    }
}

/// A proof attestation recorded in the kernel witness log.
///
/// Every successful proof-gated mutation emits an attestation.
/// Compatible with ADR-047 ProofAttestation (82 bytes).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
pub struct ProofAttestation {
    /// Hash of the proof term state (32 bytes).
    pub proof_term_hash: [u8; 32],

    /// Hash of the environment declarations (32 bytes).
    pub environment_hash: [u8; 32],

    /// Nanosecond UNIX timestamp of verification.
    pub verification_timestamp_ns: u64,

    /// Verifier version (e.g., 0x00_01_00_00 = 0.1.0).
    pub verifier_version: u32,

    /// Number of type-check reduction steps consumed.
    pub reduction_steps: u32,

    /// Cache hit rate (0-10000 = 0.00%-100.00%).
    pub cache_hit_rate_bps: u16,
}

impl ProofAttestation {
    /// Size of attestation in bytes (82 bytes per ADR-047).
    pub const SIZE: usize = 82;

    /// Creates a new proof attestation.
    #[inline]
    #[must_use]
    pub const fn new(
        proof_term_hash: [u8; 32],
        environment_hash: [u8; 32],
        verification_timestamp_ns: u64,
        verifier_version: u32,
        reduction_steps: u32,
        cache_hit_rate_bps: u16,
    ) -> Self {
        Self {
            proof_term_hash,
            environment_hash,
            verification_timestamp_ns,
            verifier_version,
            reduction_steps,
            cache_hit_rate_bps,
        }
    }
}

impl Default for ProofAttestation {
    fn default() -> Self {
        Self {
            proof_term_hash: [0u8; 32],
            environment_hash: [0u8; 32],
            verification_timestamp_ns: 0,
            verifier_version: 0,
            reduction_steps: 0,
            cache_hit_rate_bps: 0,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_proof_tier_ordering() {
        assert!((ProofTier::Reflex as u8) < (ProofTier::Standard as u8));
        assert!((ProofTier::Standard as u8) < (ProofTier::Deep as u8));
    }

    #[test]
    fn test_proof_token_expiry() {
        let token = ProofToken::new(
            [0u8; 32],
            ProofTier::Standard,
            ProofPayload::default(),
            1000,
            1,
        );

        assert!(!token.is_expired(500));
        assert!(!token.is_expired(1000));
        assert!(token.is_expired(1001));
    }

    #[test]
    fn test_attestation_size() {
        // Verify the attestation fits in 82 bytes
        // Note: Due to padding, the actual struct may be larger,
        // but serialized form should be 82 bytes
        assert_eq!(ProofAttestation::SIZE, 82);
    }
}