vyre_driver/pipeline/

hashing.rs

//! Stable hashing helpers for compiled-pipeline cache identity.

use crate::backend::DispatchConfig;
use vyre_foundation::ir::Program;
use vyre_spec::BackendId;

/// Return the normalized program digest used by backend pipeline caches.
///
/// Thin forwarder: the digest and its per-`Program` memo are owned by
/// [`vyre_foundation::ir::Program::try_normalized_cache_digest`], so the
/// algorithm has exactly one implementation and is computed at most once per
/// program value instead of once per dispatch.
///
/// # Errors
///
/// Returns when the program contains an IR type or node shape that cannot be
/// serialized into stable cache identity. Dispatch admission should surface the
/// error rather than panic or generate a lossy cache key.
pub fn try_normalized_program_cache_digest(program: &Program) -> Result<[u8; 32], String> {
    program.try_normalized_cache_digest()
}

/// Return the normalized program digest used by backend pipeline caches.
#[must_use]
pub fn normalized_program_cache_digest(program: &Program) -> [u8; 32] {
    try_normalized_program_cache_digest(program).unwrap_or([0u8; 32])
}

/// Append dispatch policy fields that alter generated backend code to a cache
/// hasher.
pub fn update_dispatch_policy_cache_hash(hasher: &mut blake3::Hasher, config: &DispatchConfig) {
    hasher.update(b"ulp\0");
    match config.ulp_budget {
        Some(ulp) => {
            hasher.update(&[1, ulp]);
        }
        None => {
            hasher.update(&[0, 0]);
        }
    };
    hasher.update(b"\0wg\0");
    match config.workgroup_override {
        Some(workgroup) => {
            hasher.update(&[1]);
            for axis in workgroup {
                hasher.update(&axis.to_le_bytes());
            }
        }
        None => {
            hasher.update(&[0]);
        }
    };
}

/// Return the dispatch-policy digest used inside backend cache keys.
///
/// This keeps policy serialization single-sourced while letting backend cache
/// identities use the shared tuple-boundary-preserving key envelope instead of
/// owning a second ad hoc hasher sequence.
#[must_use]
pub fn dispatch_policy_cache_digest(config: &DispatchConfig) -> [u8; 32] {
    let mut hasher = blake3::Hasher::new();
    update_dispatch_policy_cache_hash(&mut hasher, config);
    *hasher.finalize().as_bytes()
}

/// Human-readable dispatch policy fingerprint for cache metadata.
#[must_use]
pub fn dispatch_policy_cache_string(config: &DispatchConfig) -> String {
    // "ulp=" (4) + max u8 decimal (3) + ":wg=" (4) + workgroup repr
    // (~32) ≈ 64 bytes worst case; pre-size so the 4 push_str calls
    // do not realloc.
    let mut policy = String::with_capacity(64);
    policy.push_str("ulp=");
    push_debug_option_u8(&mut policy, config.ulp_budget);
    policy.push_str(":wg=");
    push_debug_option_workgroup(&mut policy, config.workgroup_override);
    policy
}

/// Hex-encode bytes using lowercase ASCII.
#[must_use]
pub fn hex_encode(bytes: &[u8]) -> String {
    let mut out = String::with_capacity(bytes.len() * 2);
    push_lower_hex(bytes, &mut out);
    out
}

/// Append the lowercase-hex encoding of `bytes` to `out`. Single owner of the
/// lowercase-hex nibble loop for the whole driver.
pub fn push_lower_hex(bytes: &[u8], out: &mut String) {
    const HEX: &[u8; 16] = b"0123456789abcdef";
    for &byte in bytes {
        out.push(HEX[(byte >> 4) as usize] as char);
        out.push(HEX[(byte & 0x0f) as usize] as char);
    }
}

/// Hex-encode the first eight bytes of a 32-byte digest for compact ids.
#[must_use]
pub fn hex_short(bytes: &[u8; 32]) -> String {
    hex_encode(&bytes[..8])
}

/// Stable device fingerprint for persistent pipeline caches.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PipelineDeviceFingerprint {
    /// Vendor identifier.
    pub vendor: u32,
    /// Device identifier.
    pub device: u32,
    /// Cryptographic digest of driver/runtime revision text.
    pub driver_digest: [u8; 32],
}

impl PipelineDeviceFingerprint {
    /// Build a fingerprint from numeric identifiers and revision text.
    #[must_use]
    pub fn from_parts(vendor: u32, device: u32, revision: &str, revision_extra: &str) -> Self {
        let mut hasher = blake3::Hasher::new();
        hasher.update(b"vyre-pipeline-device-fingerprint-v1\0");
        hasher.update(revision.as_bytes());
        hasher.update(b"\0extra\0");
        hasher.update(revision_extra.as_bytes());
        Self {
            vendor,
            device,
            driver_digest: *hasher.finalize().as_bytes(),
        }
    }

    /// Compose a cache key from canonical program digest and device identity.
    #[must_use]
    pub fn cache_key(self, program_digest: [u8; 32]) -> [u8; 32] {
        let mut hasher = blake3::Hasher::new();
        hasher.update(b"vyre-disk-pipeline-cache-key-v1\0program\0");
        hasher.update(&program_digest);
        hasher.update(b"\0vendor\0");
        hasher.update(&self.vendor.to_le_bytes());
        hasher.update(b"\0device\0");
        hasher.update(&self.device.to_le_bytes());
        hasher.update(b"\0driver\0");
        hasher.update(&self.driver_digest);
        *hasher.finalize().as_bytes()
    }
}

pub(super) fn push_debug_option_u8(out: &mut String, value: Option<u8>) {
    match value {
        Some(value) => {
            out.push_str("Some(");
            push_decimal_u8(out, value);
            out.push(')');
        }
        None => out.push_str("None"),
    }
}

pub(super) fn push_debug_option_workgroup(out: &mut String, value: Option<[u32; 3]>) {
    match value {
        Some([x, y, z]) => {
            out.push_str("Some([");
            push_decimal_u32(out, x);
            out.push_str(", ");
            push_decimal_u32(out, y);
            out.push_str(", ");
            push_decimal_u32(out, z);
            out.push_str("])");
        }
        None => out.push_str("None"),
    }
}

pub(super) fn push_decimal_u8(out: &mut String, value: u8) {
    push_decimal_u32(out, u32::from(value));
}

pub(super) fn push_decimal_u32(out: &mut String, value: u32) {
    let mut buf = [0_u8; 10];
    let mut n = value;
    let mut i = buf.len();
    if n == 0 {
        out.push('0');
        return;
    }
    while n > 0 {
        i -= 1;
        buf[i] = b'0' + (n % 10) as u8;
        n /= 10;
    }
    for &digit in &buf[i..] {
        out.push(digit as char);
    }
}

#[cfg(test)]
mod tests {
    use super::{
        dispatch_policy_cache_digest, hex_encode, push_decimal_u32, push_lower_hex,
        update_dispatch_policy_cache_hash,
    };
    use crate::backend::DispatchConfig;

    #[test]
    fn hex_encode_and_push_lower_hex_agree_on_known_bytes() {
        assert_eq!(hex_encode(&[0x00, 0xff, 0x1a, 0x0f]), "00ff1a0f");
        let mut out = String::from("k=");
        push_lower_hex(&[0xde, 0xad, 0xbe, 0xef], &mut out);
        assert_eq!(out, "k=deadbeef");
    }

    #[test]
    fn push_decimal_u32_renders_boundaries() {
        let mut out = String::new();
        push_decimal_u32(&mut out, 0);
        push_decimal_u32(&mut out, 42);
        push_decimal_u32(&mut out, u32::MAX);
        assert_eq!(out, "0424294967295");
    }

    #[test]
    fn dispatch_policy_cache_digest_matches_shared_hasher_for_generated_configs() {
        for case in 0..4096u32 {
            let mut config = DispatchConfig::default();
            if case & 1 != 0 {
                config.ulp_budget = Some((case as u8).wrapping_mul(17).wrapping_add(1));
            }
            if case & 2 != 0 {
                config.workgroup_override = Some([
                    1 + (case & 255),
                    1 + ((case.rotate_left(7) >> 3) & 31),
                    1 + ((case.rotate_right(5) >> 2) & 7),
                ]);
            }

            let mut hasher = blake3::Hasher::new();
            update_dispatch_policy_cache_hash(&mut hasher, &config);
            assert_eq!(
                dispatch_policy_cache_digest(&config),
                *hasher.finalize().as_bytes(),
                "Fix: dispatch-policy digest must stay single-sourced through update_dispatch_policy_cache_hash for generated case {case}."
            );
        }
    }
}