u280_hbm_sim/

artifact.rs

//! Source-simulation artifact serialization and independent-oracle handoff.

use std::collections::BTreeMap;
use std::fs;
use std::path::Path;

use anyhow::{Context, Result, ensure};
use serde::Serialize;
use sha2::{Digest as _, Sha256};

use crate::{CaseArtifacts, PROFILE_NAME, SimulationReport};

#[derive(Serialize)]
struct Geometry {
    input_bytes_per_job: u64,
    output_payload_bytes_per_job: u64,
    output_slot_bytes_per_job: u64,
    summary_bytes: u64,
}

#[derive(Serialize)]
struct FileBinding {
    file: &'static str,
    bytes: u64,
    sha256: String,
}

#[derive(Serialize)]
struct OracleRequest<'a> {
    schema: u64,
    kind: &'static str,
    evidence_tier: &'static str,
    source_simulation_valid: bool,
    cryptographic_oracle_valid: Option<bool>,
    hardware_completion_promotable: bool,
    independent_rust_oracle_required: bool,
    profile: &'static str,
    case: &'a str,
    batch: u32,
    geometry: Geometry,
    successfully_retired_jobs: &'a [u32],
    compare_all_jobs: bool,
    files: Vec<FileBinding>,
}

fn sha256(bytes: &[u8]) -> String {
    let digest = Sha256::digest(bytes);
    let mut output = String::with_capacity(64);
    for byte in digest {
        use std::fmt::Write as _;
        write!(&mut output, "{byte:02x}").expect("writing to a String cannot fail");
    }
    output
}

fn json_line<T: Serialize>(value: &T) -> Result<Vec<u8>> {
    let mut bytes = serde_json::to_vec_pretty(value).context("cannot serialize simulation JSON")?;
    bytes.push(b'\n');
    Ok(bytes)
}

fn binding(file: &'static str, bytes: &[u8]) -> FileBinding {
    FileBinding {
        file,
        bytes: u64::try_from(bytes.len()).expect("artifact length fits u64"),
        sha256: sha256(bytes),
    }
}

fn write_new_file(directory: &Path, name: &str, bytes: &[u8]) -> Result<()> {
    let path = directory.join(name);
    ensure!(
        !path.exists(),
        "refusing to replace artifact {}",
        path.display()
    );
    fs::write(&path, bytes).with_context(|| format!("cannot write {}", path.display()))
}

/// Write one completed source-simulation case to a new directory.
///
/// # Errors
///
/// Returns an error if the directory already exists, serialization fails, or
/// any artifact cannot be written.
pub fn write_case_artifacts(directory: &Path, artifacts: &CaseArtifacts) -> Result<()> {
    ensure!(
        !directory.exists(),
        "refusing to replace source-simulation directory {}",
        directory.display()
    );
    let batch = usize::try_from(artifacts.report.batch).context("batch does not fit this host")?;
    let expected_inputs = batch.checked_mul(64).context("input geometry overflow")?;
    let expected_outputs = batch
        .max(1)
        .checked_mul(4_096)
        .context("output geometry overflow")?;
    ensure!(
        artifacts.inputs.len() == expected_inputs,
        "source inputs differ from the request geometry"
    );
    ensure!(
        artifacts.outputs.len() == expected_outputs,
        "source outputs differ from the request geometry, including the zero-batch sentinel"
    );
    let report_bytes = json_line(&artifacts.report)?;
    let request = OracleRequest {
        schema: 1,
        kind: "hashsigs_u280_source_simulation_oracle_request",
        evidence_tier: "rhdl_source_simulation",
        source_simulation_valid: true,
        cryptographic_oracle_valid: None,
        hardware_completion_promotable: false,
        independent_rust_oracle_required: true,
        profile: PROFILE_NAME,
        case: &artifacts.report.case,
        batch: artifacts.report.batch,
        geometry: Geometry {
            input_bytes_per_job: 64,
            output_payload_bytes_per_job: 2_208,
            output_slot_bytes_per_job: 4_096,
            summary_bytes: 64,
        },
        successfully_retired_jobs: &artifacts.report.completed_jobs,
        compare_all_jobs: artifacts.report.expected_success,
        files: vec![
            binding("inputs.bin", &artifacts.inputs),
            binding("outputs.bin", &artifacts.outputs),
            binding("summary.bin", &artifacts.summary),
            binding("source-simulation.json", &report_bytes),
        ],
    };
    let request_bytes = json_line(&request)?;
    let files = [
        ("inputs.bin", artifacts.inputs.as_slice()),
        ("oracle-request.json", request_bytes.as_slice()),
        ("outputs.bin", artifacts.outputs.as_slice()),
        ("source-simulation.json", report_bytes.as_slice()),
        ("summary.bin", artifacts.summary.as_slice()),
    ];
    fs::create_dir(directory)
        .with_context(|| format!("cannot create simulation directory {}", directory.display()))?;
    for (name, bytes) in files {
        write_new_file(directory, name, bytes)?;
    }
    let mut manifest = String::new();
    for (name, bytes) in files {
        use std::fmt::Write as _;
        writeln!(&mut manifest, "{}  {name}", sha256(bytes))
            .expect("writing to a String cannot fail");
    }
    write_new_file(directory, "SHA256SUMS", manifest.as_bytes())?;
    Ok(())
}

/// Write a top-level index for a freshly created standard-suite directory.
///
/// # Errors
///
/// Returns an error if serialization or writing fails.
pub fn write_suite_index(directory: &Path, reports: &[SimulationReport]) -> Result<()> {
    #[derive(Serialize)]
    struct Suite<'a> {
        schema: u64,
        kind: &'static str,
        evidence_tier: &'static str,
        source_simulation_valid: bool,
        cryptographic_oracle_valid: Option<bool>,
        hardware_completion_promotable: bool,
        cases: &'a [SimulationReport],
    }
    let bytes = json_line(&Suite {
        schema: 1,
        kind: "hashsigs_u280_mock_hbm_source_simulation_suite",
        evidence_tier: "rhdl_source_simulation",
        source_simulation_valid: true,
        cryptographic_oracle_valid: None,
        hardware_completion_promotable: false,
        cases: reports,
    })?;
    write_new_file(directory, "suite.json", &bytes)
}

pub(crate) fn merge_register_words(registers: &BTreeMap<String, u32>, prefix: &str) -> Result<u64> {
    let low = registers
        .get(&format!("{prefix}_lo"))
        .copied()
        .with_context(|| format!("missing {prefix}_lo register"))?;
    let high = registers
        .get(&format!("{prefix}_hi"))
        .copied()
        .with_context(|| format!("missing {prefix}_hi register"))?;
    Ok(u64::from(low) | (u64::from(high) << 32))
}