silicera 0.1.1

Hardware-native program specialization for AMD Zen — core discovery, measurement, and HNEP
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! Experiment reproducibility pack — export enough metadata to re-run later.
//!
//! Does not include personal paths or hardware serials.

use serde::{Deserialize, Serialize};
use crate::brand::{NAME, PHASE, VERSION};
use crate::hardware::{EnvironmentSnapshot, HardwareInfo};
use crate::Result;

/// Format id.
pub const REPRO_FORMAT: &str = "silicera-repro-pack";

/// Schema version.
pub const REPRO_VERSION: u32 = 1;

/// Compact reproducibility bundle.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReproPack {
    /// Format magic.
    pub format: String,
    /// Schema version.
    pub version: u32,
    /// Product name.
    pub product: String,
    /// Silicera version.
    pub silicera_version: String,
    /// Phase marker.
    pub phase: String,
    /// Experiment / command label.
    pub experiment: String,
    /// RFC3339 timestamp.
    pub created_at: String,
    /// Fingerprint when supported.
    pub fingerprint: Option<String>,
    /// Host brand.
    pub host_brand: String,
    /// Microarch tag when known.
    pub microarchitecture: Option<String>,
    /// Environment snapshot (no hostname).
    pub environment: EnvironmentSnapshot,
    /// Command-line / knobs used.
    pub parameters: serde_json::Value,
    /// Optional random seed.
    pub random_seed: Option<u64>,
    /// Optional result digest (hex) for an accompanying artifact.
    pub result_digest: Option<String>,
    /// Caveats.
    pub caveats: Vec<String>,
}

impl ReproPack {
    /// Build from live hardware + experiment metadata.
    pub fn capture(
        info: &HardwareInfo,
        experiment: impl Into<String>,
        parameters: serde_json::Value,
        random_seed: Option<u64>,
        result_digest: Option<String>,
    ) -> Self {
        let microarchitecture = info
            .fingerprint
            .as_ref()
            .and_then(|f| f.value.split(':').nth(2).map(|s| s.to_ascii_lowercase()));
        Self {
            format: REPRO_FORMAT.into(),
            version: REPRO_VERSION,
            product: NAME.into(),
            silicera_version: VERSION.into(),
            phase: PHASE.into(),
            experiment: experiment.into(),
            created_at: chrono::Utc::now().to_rfc3339(),
            fingerprint: info.fingerprint.as_ref().map(|f| f.value.clone()),
            host_brand: info.brand.clone(),
            microarchitecture,
            environment: info.environment.clone(),
            parameters,
            random_seed,
            result_digest,
            caveats: vec![
                "Repro packs identify measurement conditions; they are not authentication.".into(),
                "Re-run on the same fingerprint class; do not assume cross-machine transfer.".into(),
                "No user home paths or hardware serial numbers are included.".into(),
            ],
        }
    }

    /// Pretty JSON.
    pub fn to_json_pretty(&self) -> Result<String> {
        Ok(serde_json::to_string_pretty(self)?)
    }

    /// Write to path.
    pub fn write_to(&self, path: &std::path::Path) -> Result<()> {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        std::fs::write(path, self.to_json_pretty()?)?;
        Ok(())
    }
}