clm-kernel 0.0.20

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 1 formal oracle witness verifier (CLC-02 / WP-552-4).
//!
//! Pure data types and deterministic cryptographic verification functions for sealed
//! formal oracle witnesses. Independent of native OS process execution, suitable for WASM.

use std::collections::BTreeSet;

/// Domain-separation prefix for formal oracle witness preimages.
pub const ORACLE_WITNESS_DOMAIN: &str = "clm.formal.oracle.witness.v1";

/// Closed four-state formal oracle verification status.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum OracleWitnessStatus {
    #[serde(rename = "VERIFIED")]
    Verified,
    #[serde(rename = "REFUTED")]
    Refuted,
    #[serde(rename = "STALE_WITNESS")]
    StaleWitness,
    #[serde(rename = "SKIPPED_UNAVAILABLE")]
    SkippedUnavailable,
}

/// Input commitment fields bound into a sealed OracleWitness.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct OracleWitnessInput {
    pub runtime_id: String,
    pub profile_id: String,
    pub status: OracleWitnessStatus,
    pub source_digest: String,
    pub theorem_digest: String,
    pub toolchain_version: String,
    pub argv: Vec<String>,
    pub env_allowlist: Vec<String>,
    pub result_digest: String,
    pub diagnostic_digest: String,
}

/// Sealed formal oracle witness receipt with domain-separated BLAKE3 digest.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct OracleWitness {
    pub schema_version: String,
    pub runtime_id: String,
    pub profile_id: String,
    pub status: OracleWitnessStatus,
    pub source_digest: String,
    pub theorem_digest: String,
    pub toolchain_version: String,
    pub argv: Vec<String>,
    pub env_allowlist: Vec<String>,
    pub result_digest: String,
    pub diagnostic_digest: String,
    pub witness_digest: String,
}

/// Expected freshness anchors checked when re-verifying a sealed witness.
#[derive(Debug, Clone, Default)]
pub struct WitnessFreshnessExpectation {
    pub source_digest: Option<String>,
    pub theorem_digest: Option<String>,
    pub toolchain_version: Option<String>,
}

#[derive(serde::Serialize)]
struct PreimagePayload<'a> {
    runtime_id: &'a str,
    profile_id: &'a str,
    source_digest: &'a str,
    theorem_digest: &'a str,
    toolchain_version: &'a str,
    argv: &'a [String],
    env_allowlist: &'a [String],
    result_digest: &'a str,
    diagnostic_digest: &'a str,
}

/// Compute prefixed BLAKE3 digest (`blake3:<64-hex>`) over raw bytes.
pub fn compute_formal_blake3(bytes: &[u8]) -> String {
    format!("blake3:{}", blake3::hash(bytes).to_hex())
}

/// Serialize deterministic UTF-8 preimage binding all formal witness commitments.
pub fn serialize_oracle_witness_preimage(
    runtime_id: &str,
    profile_id: &str,
    source_digest: &str,
    theorem_digest: &str,
    toolchain_version: &str,
    argv: &[String],
    env_allowlist: &[String],
    result_digest: &str,
    diagnostic_digest: &str,
) -> String {
    let payload = PreimagePayload {
        runtime_id,
        profile_id,
        source_digest,
        theorem_digest,
        toolchain_version,
        argv,
        env_allowlist,
        result_digest,
        diagnostic_digest,
    };
    format!(
        "{}\n{}",
        ORACLE_WITNESS_DOMAIN,
        serde_json::to_string(&payload).unwrap_or_default()
    )
}

/// Compute domain-separated BLAKE3 digest (`blake3:<64-hex>`) for witness fields.
pub fn compute_oracle_witness_digest(
    runtime_id: &str,
    profile_id: &str,
    source_digest: &str,
    theorem_digest: &str,
    toolchain_version: &str,
    argv: &[String],
    env_allowlist: &[String],
    result_digest: &str,
    diagnostic_digest: &str,
) -> String {
    let preimage = serialize_oracle_witness_preimage(
        runtime_id,
        profile_id,
        source_digest,
        theorem_digest,
        toolchain_version,
        argv,
        env_allowlist,
        result_digest,
        diagnostic_digest,
    );
    compute_formal_blake3(preimage.as_bytes())
}

/// Construct a sealed OracleWitness with sorted unique env_allowlist and BLAKE3 digest.
pub fn build_oracle_witness(input: OracleWitnessInput) -> OracleWitness {
    let normalized_env: Vec<String> = input
        .env_allowlist
        .into_iter()
        .collect::<BTreeSet<_>>()
        .into_iter()
        .collect();
    let witness_digest = compute_oracle_witness_digest(
        &input.runtime_id,
        &input.profile_id,
        &input.source_digest,
        &input.theorem_digest,
        &input.toolchain_version,
        &input.argv,
        &normalized_env,
        &input.result_digest,
        &input.diagnostic_digest,
    );
    OracleWitness {
        schema_version: ORACLE_WITNESS_DOMAIN.to_string(),
        runtime_id: input.runtime_id,
        profile_id: input.profile_id,
        status: input.status,
        source_digest: input.source_digest,
        theorem_digest: input.theorem_digest,
        toolchain_version: input.toolchain_version,
        argv: input.argv,
        env_allowlist: normalized_env,
        result_digest: input.result_digest,
        diagnostic_digest: input.diagnostic_digest,
        witness_digest,
    }
}

/// Evaluate a sealed OracleWitness against freshness expectations into a closed 4-state verdict.
pub fn verify_oracle_witness(
    witness: &OracleWitness,
    expected: Option<&WitnessFreshnessExpectation>,
) -> OracleWitnessStatus {
    if witness.schema_version != ORACLE_WITNESS_DOMAIN {
        return OracleWitnessStatus::Refuted;
    }
    let recomputed = compute_oracle_witness_digest(
        &witness.runtime_id,
        &witness.profile_id,
        &witness.source_digest,
        &witness.theorem_digest,
        &witness.toolchain_version,
        &witness.argv,
        &witness.env_allowlist,
        &witness.result_digest,
        &witness.diagnostic_digest,
    );
    if witness.witness_digest != recomputed {
        return OracleWitnessStatus::Refuted;
    }
    if witness.status == OracleWitnessStatus::StaleWitness {
        return OracleWitnessStatus::StaleWitness;
    }
    if let Some(exp) = expected {
        let src_stale = exp
            .source_digest
            .as_ref()
            .is_some_and(|s| s != &witness.source_digest);
        let thm_stale = exp
            .theorem_digest
            .as_ref()
            .is_some_and(|t| t != &witness.theorem_digest);
        let ver_stale = exp
            .toolchain_version
            .as_ref()
            .is_some_and(|v| v != &witness.toolchain_version);
        if src_stale || thm_stale || ver_stale {
            return OracleWitnessStatus::StaleWitness;
        }
    }
    match witness.status {
        OracleWitnessStatus::SkippedUnavailable => OracleWitnessStatus::SkippedUnavailable,
        OracleWitnessStatus::Verified => OracleWitnessStatus::Verified,
        OracleWitnessStatus::Refuted | OracleWitnessStatus::StaleWitness => {
            OracleWitnessStatus::Refuted
        }
    }
}

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

    #[test]
    fn test_build_and_verify_oracle_witness() {
        let input = OracleWitnessInput {
            runtime_id: "lean4".to_string(),
            profile_id: "default".to_string(),
            status: OracleWitnessStatus::Verified,
            source_digest: "blake3:1111".to_string(),
            theorem_digest: "blake3:2222".to_string(),
            toolchain_version: "4.8.0".to_string(),
            argv: vec!["lake".to_string(), "build".to_string()],
            env_allowlist: vec!["PATH".to_string(), "HOME".to_string()],
            result_digest: "blake3:3333".to_string(),
            diagnostic_digest: "blake3:4444".to_string(),
        };
        let witness = build_oracle_witness(input);
        assert_eq!(witness.status, OracleWitnessStatus::Verified);
        assert!(witness.witness_digest.starts_with("blake3:"));

        let status = verify_oracle_witness(&witness, None);
        assert_eq!(status, OracleWitnessStatus::Verified);

        let expectation = WitnessFreshnessExpectation {
            source_digest: Some("blake3:1111".to_string()),
            theorem_digest: Some("blake3:2222".to_string()),
            toolchain_version: Some("4.8.0".to_string()),
        };
        assert_eq!(
            verify_oracle_witness(&witness, Some(&expectation)),
            OracleWitnessStatus::Verified
        );

        let stale_exp = WitnessFreshnessExpectation {
            source_digest: Some("blake3:9999".to_string()),
            ..Default::default()
        };
        assert_eq!(
            verify_oracle_witness(&witness, Some(&stale_exp)),
            OracleWitnessStatus::StaleWitness
        );
    }
}