rhdl_gen/

lib.rs

#![doc = include_str!("../README.md")]
#![forbid(unsafe_code)]

use std::{
    collections::BTreeMap,
    ffi::OsString,
    fmt::Write as _,
    fs::{self, OpenOptions},
    io::Write as _,
    path::{Path, PathBuf},
    process::Command as ProcessCommand,
    sync::atomic::{AtomicU64, Ordering},
    time::{Duration, Instant},
};

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

mod benchmark_kernel;
mod full_sha_check;
mod full_signer_check;
mod signer_throughput_check;
mod u280_hbm;
mod u280_hbm_check;
mod u280_hbm_rtl_check;

/// `HashSigsRS` revision used by the compatibility profile.
pub const HASHSIGS_REVISION: &str = "2d315dd4168804b7cbc51c51a1bf7ca27bf74140";

/// RHDL revision used to lower these Rust kernels to Verilog.
pub const RHDL_REVISION: &str = "c99d5cc53269a247bbc675d0fbd766991d409f56";

/// Evidence tier written to every generated artifact manifest.
pub const GENERATED_VERILOG_EVIDENCE_TIER: &str = "generated-verilog";

/// Command-line usage text.
pub const USAGE: &str = "Usage:\n  rhdl-gen list\n  rhdl-gen generate <TARGET> --output <DIRECTORY> [--force]\n  rhdl-gen check [--full] [--signer-full] [--temp-root <DIRECTORY>] [--keep]\n  rhdl-gen signer-throughput --source-evidence <DIRECTORY> --output <NEW_DIRECTORY>\n  rhdl-gen benchmark-kernel --output <NEW_DIRECTORY>\n  rhdl-gen u280-link-graph --kernel <VERILOG> --kernel-manifest <JSON> --signer-evidence <DIRECTORY> --output <NEW_JSON>\n  rhdl-gen u280-verify-link-graph --kernel <VERILOG> --kernel-manifest <JSON> --signer-evidence <DIRECTORY> --record <JSON>\n  rhdl-gen u280-hbm-rtl-check --kernel <VERILOG> --kernel-manifest <JSON> --signer-evidence <DIRECTORY> --record <JSON> --output <NEW_DIRECTORY>";

/// Parsed command-line operation.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum Command {
    /// List all registered generation targets.
    List,
    /// Generate one target and its manifest.
    Generate {
        /// Registry name of the target.
        target: String,
        /// Directory that receives the generated files.
        output: PathBuf,
        /// Permit replacement of the target's deterministic filenames.
        force: bool,
    },
    /// Generate and elaborate the supported smoke-check targets with Icarus,
    /// optionally adding Verilator lint and host-oracle arithmetic simulations
    /// for the unchecked complete SHA lane and exact three-lane farm.
    Check {
        /// Parent for the unique temporary check directory.
        temp_root: Option<PathBuf>,
        /// Preserve the unique directory after a successful or failed check.
        keep: bool,
        /// Also render the complete SHA lane and exact three-lane farm, then run
        /// Verilator lint/elaboration and deterministic arithmetic simulations.
        full: bool,
        /// Sequentially render and link the modular production signer, then run
        /// its fail-closed structural and generated-RTL equivalence gates.
        signer_full: bool,
    },
    /// Build and run the separately generated sustained-throughput testbench
    /// against an existing immutable successful production-signer bundle.
    SignerThroughput {
        /// Existing directory containing the complete signer check-evidence
        /// manifest and every immutable file in its checksum chain.
        source_evidence: PathBuf,
        /// New directory that receives the immutable throughput evidence.
        output: PathBuf,
    },
    /// Generate the immutable modular RHDL benchmark, metadata-derived Vitis
    /// wrapper, and packaging Tcl in sequential lowering children.
    BenchmarkKernel {
        /// New directory that receives the frozen generation bundle.
        output: PathBuf,
    },
    /// Bind the exact generated HBM kernel and successful signer evidence into
    /// one immutable graph record.
    U280LinkGraph {
        /// Generated Rust/RHDL shell plus metadata-derived adapter source.
        kernel: PathBuf,
        /// Canonical schema-2 generation manifest adjacent to the kernel.
        kernel_manifest: PathBuf,
        /// Successful immutable full-signer evidence directory.
        signer_evidence: PathBuf,
        /// New read-only checksum/graph JSON record.
        output: PathBuf,
    },
    /// Revalidate an existing immutable U280 link record without writing files.
    U280VerifyLinkGraph {
        /// Generated Rust/RHDL shell plus metadata-derived adapter source.
        kernel: PathBuf,
        /// Canonical schema-2 generation manifest adjacent to the kernel.
        kernel_manifest: PathBuf,
        /// Successful immutable full-signer evidence directory.
        signer_evidence: PathBuf,
        /// Existing canonical read-only schema-2 link record.
        record: PathBuf,
    },
    /// Run a source-tier external generated-RTL gate over the actual HBM top,
    /// actual signer bundle, AXI4-Lite, and deterministic HBM models.
    U280HbmRtlCheck {
        /// Generated Rust/RHDL shell plus metadata-derived adapter source.
        kernel: PathBuf,
        /// Canonical schema-2 generation manifest adjacent to the kernel.
        kernel_manifest: PathBuf,
        /// Successful immutable full-signer evidence directory.
        signer_evidence: PathBuf,
        /// Existing canonical read-only schema-2 live link record.
        record: PathBuf,
        /// New directory that receives the immutable external-RTL evidence.
        output: PathBuf,
    },
    /// Internal one-graph signer lowering operation used only by the parent
    /// `check --signer-full` process.
    #[doc(hidden)]
    InternalSignerLower {
        /// Exact graph to lower: `lane`, `skeleton`, or `benchmark-skeleton`.
        kind: String,
        /// New immutable source path written by the child.
        output: PathBuf,
        /// Clean parent commit that the child must independently rediscover.
        source_commit: String,
    },
    /// Print usage text.
    Help,
}

/// Metadata and generator for one extensible RTL target.
#[derive(Clone, Copy)]
pub struct TargetSpec {
    /// Stable command-line name.
    pub name: &'static str,
    /// Deterministic generated Verilog filename.
    pub verilog_filename: &'static str,
    /// Deterministic provenance-manifest filename.
    pub manifest_filename: &'static str,
    /// Cryptographic profile identifier.
    pub profile: &'static str,
    /// Top module expected in the generated Verilog.
    pub top_module: &'static str,
    /// Short human-facing description.
    pub description: &'static str,
    /// Validation boundary attached to this target and copied into manifests.
    pub validation_scope: &'static str,
    /// Whether ordinary unit-test generation loops may lower this target.
    pub default_unit_generation: bool,
    generate: fn() -> Result<String>,
}

impl std::fmt::Debug for TargetSpec {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("TargetSpec")
            .field("name", &self.name)
            .field("verilog_filename", &self.verilog_filename)
            .field("manifest_filename", &self.manifest_filename)
            .field("profile", &self.profile)
            .field("top_module", &self.top_module)
            .field("description", &self.description)
            .field("validation_scope", &self.validation_scope)
            .field("default_unit_generation", &self.default_unit_generation)
            .finish_non_exhaustive()
    }
}

fn reject_standalone_signer_generation() -> Result<String> {
    bail!(
        "the modular production signer has multiple immutable sources; use `rhdl-gen check --signer-full --keep`"
    )
}

static SIGNER_FULL_TARGET: TargetSpec = TargetSpec {
    name: full_signer_check::SIGNER_TARGET_NAME,
    verilog_filename: "wots_sha256_signer_top.bundle.v",
    manifest_filename: "wots_sha256_signer_top.bundle.manifest.json",
    profile: "HASHSIGS_SHA256_GENERIC_V1",
    top_module: full_signer_check::SIGNER_TOP_MODULE,
    description: "modular complete SHA-256 three-cluster signer bundle",
    validation_scope: "opt-in structural validation and finite generated-RTL equivalence only",
    default_unit_generation: false,
    generate: reject_standalone_signer_generation,
};

fn generate_keccak_round() -> Result<String> {
    keccak_rhdl::generate_round_verilog().context("lowering the isolated Keccak round")
}

fn generate_keccak_permutation() -> Result<String> {
    keccak_rhdl::generate_permutation_verilog()
        .context("lowering the complete Keccak permutation oracle")
}

fn generate_keccak_iterative() -> Result<String> {
    keccak_rhdl::generate_iterative_verilog().context("lowering the iterative Keccak engine")
}

fn combinational_kernel_module(
    module_name: &str,
    ports: &str,
    declarations: &str,
    function: &str,
    assignment: &str,
) -> String {
    format!(
        "module {module_name}({ports});\n{declarations}\n\n{function}\n\n{assignment}\nendmodule\n"
    )
}

fn generate_sha256_round() -> Result<String> {
    let function = sha256_rhdl::round_verilog().context("lowering the isolated SHA-256 round")?;
    Ok(combinational_kernel_module(
        "sha256_round_ooc",
        "state_i, round_constant_i, state_o",
        "  input wire [767:0] state_i;\n  input wire [31:0] round_constant_i;\n  output wire [767:0] state_o;",
        &function,
        "  assign state_o = kernel_round_kernel(state_i, round_constant_i);",
    ))
}

fn generate_sha256_compression() -> Result<String> {
    let function = sha256_rhdl::compression_verilog()
        .context("lowering the complete combinational SHA-256 compression oracle")?;
    Ok(combinational_kernel_module(
        "sha256_compression_ooc",
        "chaining_i, block_i, digest_o",
        "  input wire [255:0] chaining_i;\n  input wire [511:0] block_i;\n  output wire [255:0] digest_o;",
        &function,
        "  assign digest_o = kernel_compression_kernel(chaining_i, block_i);",
    ))
}

fn generate_sha256_pipeline_2() -> Result<String> {
    sha256_rhdl::round_pipeline_verilog::<2>()
        .context("lowering the checked two-stage SHA-256 round pipeline")
}

fn generate_sha256_pipeline_64_unchecked() -> Result<String> {
    sha256_rhdl::round_pipeline_unchecked_verilog::<64>()
        .context("rendering the unchecked 64-stage SHA-256 round pipeline")
}

fn generate_sha256_compression_lane_64_unchecked() -> Result<String> {
    sha256_rhdl::lane::try_full_compression_lane_unchecked_verilog()
        .context("rendering the unchecked complete 64-round SHA-256 compression lane")
}

fn generate_sha256_compression_farm_3x64_unchecked() -> Result<String> {
    sha256_rhdl::farm::try_full_three_lane_farm_generation_only_unchecked_verilog()
        .context("rendering the unchecked exact three-lane SHA-256 compression farm")
}

/// Registered RHDL Verilog generation targets.
///
/// New profile-specific targets should be added here without introducing a
/// runtime profile mux into any cryptographic datapath.
pub static TARGETS: &[TargetSpec] = &[
    TargetSpec {
        name: "legacy-keccak-round",
        verilog_filename: "legacy_keccak_round.v",
        manifest_filename: "legacy_keccak_round.manifest.json",
        profile: "LEGACY_KECCAK",
        top_module: "keccak_round_ooc",
        description: "compile-time round-0 cell for isolated RTL evaluation",
        validation_scope: "Icarus syntax/elaboration in the default check; no equivalence claim",
        default_unit_generation: true,
        generate: generate_keccak_round,
    },
    TargetSpec {
        name: "legacy-keccak-permutation",
        verilog_filename: "legacy_keccak_permutation.v",
        manifest_filename: "legacy_keccak_permutation.manifest.json",
        profile: "LEGACY_KECCAK",
        top_module: "keccak_f1600_ooc",
        description: "24-round combinational correctness oracle",
        validation_scope: "export-only in the default check; no synthesis or hardware claim",
        default_unit_generation: true,
        generate: generate_keccak_permutation,
    },
    TargetSpec {
        name: "legacy-keccak-iterative",
        verilog_filename: "legacy_keccak_iterative.v",
        manifest_filename: "legacy_keccak_iterative.manifest.json",
        profile: "LEGACY_KECCAK",
        top_module: "keccak_iterative",
        description: "one-round-per-cycle 24-round engine",
        validation_scope: "Icarus syntax/elaboration in the default check; no equivalence claim",
        default_unit_generation: true,
        generate: generate_keccak_iterative,
    },
    TargetSpec {
        name: "sha256-round",
        verilog_filename: "sha256_round.v",
        manifest_filename: "sha256_round.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: "sha256_round_ooc",
        description: "isolated combinational SHA-256 round with an explicit round constant",
        validation_scope: "Icarus syntax/elaboration in the default check; no equivalence claim",
        default_unit_generation: true,
        generate: generate_sha256_round,
    },
    TargetSpec {
        name: "sha256-compression-oracle",
        verilog_filename: "sha256_compression_oracle.v",
        manifest_filename: "sha256_compression_oracle.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: "sha256_compression_ooc",
        description: "slow full combinational SHA-256 compression oracle",
        validation_scope: "slow export-only target; excluded from default generation and Icarus checks",
        default_unit_generation: false,
        generate: generate_sha256_compression,
    },
    TargetSpec {
        name: "sha256-pipeline-2",
        verilog_filename: "sha256_pipeline_2.v",
        manifest_filename: "sha256_pipeline_2.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: "sha256_round_pipeline",
        description: "checked two-stage registered SHA-256 round-pipeline prefix",
        validation_scope: "RHDL-checked generation plus Icarus syntax/elaboration in the default check",
        default_unit_generation: true,
        generate: generate_sha256_pipeline_2,
    },
    TargetSpec {
        name: "sha256-pipeline-64-unchecked",
        verilog_filename: "sha256_pipeline_64_unchecked.v",
        manifest_filename: "sha256_pipeline_64_unchecked.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: "sha256_round_pipeline",
        description: "unchecked rendering of the complete 64-stage SHA-256 round pipeline; not equivalence evidence",
        validation_scope: "unchecked RHDL rendering; Verilator lint/control-only simulation are not RHDL/RTL equivalence evidence",
        default_unit_generation: false,
        generate: generate_sha256_pipeline_64_unchecked,
    },
    TargetSpec {
        name: "sha256-compression-lane-64-unchecked",
        verilog_filename: "sha256_compression_lane_64_unchecked.v",
        manifest_filename: "sha256_compression_lane_64_unchecked.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: "sha256_compression_lane",
        description: "complete 64-round BRAM-backed SHA-256 compression lane",
        validation_scope: "unchecked RHDL rendering; `check --full` adds Verilator lint and arithmetic simulation, but no synthesis, timing, route, or hardware claim",
        default_unit_generation: false,
        generate: generate_sha256_compression_lane_64_unchecked,
    },
    TargetSpec {
        name: "sha256-compression-farm-3x64-unchecked",
        verilog_filename: "sha256_compression_farm_3x64_unchecked.v",
        manifest_filename: "sha256_compression_farm_3x64_unchecked.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: "sha256_compression_farm_3x64",
        description: "exact ThreeLaneCompressionFarm with independent complete SHA-256 lanes",
        validation_scope: "unchecked RHDL rendering; `check --full` adds Verilator lint and cross-lane arithmetic simulation, but no synthesis, timing, route, or hardware claim",
        default_unit_generation: false,
        generate: generate_sha256_compression_farm_3x64_unchecked,
    },
    TargetSpec {
        name: u280_hbm::U280_HBM_TARGET_NAME,
        verilog_filename: "hashsigs_sha256_hbm_kernel.v",
        manifest_filename: "hashsigs_sha256_hbm_kernel.manifest.json",
        profile: "HASHSIGS_SHA256_GENERIC_V1",
        top_module: u280_hbm::U280_HBM_TOP_MODULE,
        description: "Rust/RHDL U280 HBM transport shell with an unresolved modular signer",
        validation_scope: "metadata coverage and wire-only adapter validation; generation alone is not parse, simulation, synthesis, timing, route, resource, or hardware evidence",
        default_unit_generation: false,
        generate: u280_hbm::generate,
    },
];

/// Source-tree identity captured before an artifact is written.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct SourceProvenance {
    /// Git commit containing the source baseline.
    pub commit: String,
    /// Whether tracked or untracked source-tree changes were present.
    pub dirty: bool,
}

impl SourceProvenance {
    /// Inspect the source worktree containing this crate without taking a Git
    /// optional lock.
    ///
    /// # Errors
    ///
    /// Returns an error if Git is unavailable or the source is not in a Git
    /// worktree.
    pub fn discover() -> Result<Self> {
        let source_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
        let commit = git_output(source_dir, ["rev-parse", "HEAD"])?;
        let status = git_output(
            source_dir,
            ["status", "--porcelain=v1", "--untracked-files=normal"],
        )?;
        Ok(Self {
            commit,
            dirty: !status.is_empty(),
        })
    }
}

/// Deterministic checksum and provenance record accompanying generated RTL.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ArtifactManifest {
    /// Manifest schema revision.
    pub schema_version: u32,
    /// Stable target registry name.
    pub target: String,
    /// Cryptographic profile identifier.
    pub profile: String,
    /// Evidence tier; always `generated-verilog` in this tool.
    pub evidence_tier: String,
    /// Exact validation boundary declared by the selected target.
    pub validation_scope: String,
    /// Generated Verilog filename relative to the manifest.
    pub verilog_file: String,
    /// SHA-256 digest of the exact generated Verilog bytes.
    pub verilog_sha256: String,
    /// Source Git commit captured before output creation.
    pub source_git_commit: String,
    /// Source dirty state captured before output creation.
    pub source_git_dirty: bool,
    /// Pinned RHDL revision.
    pub rhdl_revision: String,
    /// Pinned `HashSigsRS` revision.
    pub hashsigs_revision: String,
    /// Generator package version.
    pub generator_version: String,
}

/// Files produced by one generation operation.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct GeneratedArtifact {
    /// Generated Verilog path.
    pub verilog_path: PathBuf,
    /// Generated JSON manifest path.
    pub manifest_path: PathBuf,
    /// Parsed manifest written alongside the Verilog.
    pub manifest: ArtifactManifest,
}

/// Parse arguments excluding the executable name.
///
/// # Errors
///
/// Returns a descriptive error for missing, duplicate, or unknown arguments.
pub fn parse_args<I, S>(args: I) -> Result<Command>
where
    I: IntoIterator<Item = S>,
    S: Into<OsString>,
{
    let mut args = args.into_iter().map(Into::into);
    let Some(operation) = args.next() else {
        bail!("missing command");
    };
    match operation.to_str() {
        Some("list") => {
            ensure_no_extra(args, "list")?;
            Ok(Command::List)
        }
        Some("generate") => parse_generate(args),
        Some("check") => parse_check(args),
        Some("signer-throughput") => parse_signer_throughput(args),
        Some("benchmark-kernel") => parse_benchmark_kernel(args),
        Some("u280-link-graph") => parse_u280_link_graph(args),
        Some("u280-verify-link-graph") => parse_u280_verify_link_graph(args),
        Some("u280-hbm-rtl-check") => parse_u280_hbm_rtl_check(args),
        Some("__signer-lower") => parse_internal_signer_lower(args),
        Some("help" | "--help" | "-h") => {
            ensure_no_extra(args, "help")?;
            Ok(Command::Help)
        }
        Some(other) => bail!("unknown command `{other}`"),
        None => bail!("command is not valid UTF-8"),
    }
}

fn parse_benchmark_kernel(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    if args.next().as_deref() != Some(std::ffi::OsStr::new("--output")) {
        bail!("benchmark-kernel requires --output <NEW_DIRECTORY>");
    }
    let output = PathBuf::from(
        args.next()
            .ok_or_else(|| anyhow!("benchmark-kernel requires --output <NEW_DIRECTORY>"))?,
    );
    ensure_no_extra(args, "benchmark-kernel")?;
    Ok(Command::BenchmarkKernel { output })
}

fn parse_u280_link_graph(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let mut kernel = None;
    let mut kernel_manifest = None;
    let mut signer_evidence = None;
    let mut output = None;
    while let Some(argument) = args.next() {
        let (slot, description) = match argument.to_str() {
            Some("--kernel") => (&mut kernel, "--kernel requires a Verilog file"),
            Some("--kernel-manifest") => (
                &mut kernel_manifest,
                "--kernel-manifest requires a JSON file",
            ),
            Some("--signer-evidence") => (
                &mut signer_evidence,
                "--signer-evidence requires a directory",
            ),
            Some("--output") => (&mut output, "--output requires a new JSON file"),
            Some(other) => bail!("unknown u280-link-graph argument `{other}`"),
            None => bail!("u280-link-graph option is not valid UTF-8"),
        };
        if slot.is_some() {
            bail!("{} may only be specified once", argument.to_string_lossy());
        }
        *slot = Some(PathBuf::from(
            args.next().ok_or_else(|| anyhow!(description))?,
        ));
    }
    Ok(Command::U280LinkGraph {
        kernel: kernel.ok_or_else(|| anyhow!("u280-link-graph requires --kernel <VERILOG>"))?,
        kernel_manifest: kernel_manifest
            .ok_or_else(|| anyhow!("u280-link-graph requires --kernel-manifest <JSON>"))?,
        signer_evidence: signer_evidence
            .ok_or_else(|| anyhow!("u280-link-graph requires --signer-evidence <DIRECTORY>"))?,
        output: output.ok_or_else(|| anyhow!("u280-link-graph requires --output <NEW_JSON>"))?,
    })
}

fn parse_u280_verify_link_graph(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let mut kernel = None;
    let mut kernel_manifest = None;
    let mut signer_evidence = None;
    let mut record = None;
    while let Some(argument) = args.next() {
        let (slot, description) = match argument.to_str() {
            Some("--kernel") => (&mut kernel, "--kernel requires a Verilog file"),
            Some("--kernel-manifest") => (
                &mut kernel_manifest,
                "--kernel-manifest requires a JSON file",
            ),
            Some("--signer-evidence") => (
                &mut signer_evidence,
                "--signer-evidence requires a directory",
            ),
            Some("--record") => (&mut record, "--record requires an existing JSON file"),
            Some(other) => bail!("unknown u280-verify-link-graph argument `{other}`"),
            None => bail!("u280-verify-link-graph option is not valid UTF-8"),
        };
        if slot.is_some() {
            bail!("{} may only be specified once", argument.to_string_lossy());
        }
        *slot = Some(PathBuf::from(
            args.next().ok_or_else(|| anyhow!(description))?,
        ));
    }
    Ok(Command::U280VerifyLinkGraph {
        kernel: kernel
            .ok_or_else(|| anyhow!("u280-verify-link-graph requires --kernel <VERILOG>"))?,
        kernel_manifest: kernel_manifest
            .ok_or_else(|| anyhow!("u280-verify-link-graph requires --kernel-manifest <JSON>"))?,
        signer_evidence: signer_evidence.ok_or_else(|| {
            anyhow!("u280-verify-link-graph requires --signer-evidence <DIRECTORY>")
        })?,
        record: record.ok_or_else(|| anyhow!("u280-verify-link-graph requires --record <JSON>"))?,
    })
}

fn parse_u280_hbm_rtl_check(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let mut kernel = None;
    let mut kernel_manifest = None;
    let mut signer_evidence = None;
    let mut record = None;
    let mut output = None;
    while let Some(argument) = args.next() {
        let (slot, description) = match argument.to_str() {
            Some("--kernel") => (&mut kernel, "--kernel requires a Verilog file"),
            Some("--kernel-manifest") => (
                &mut kernel_manifest,
                "--kernel-manifest requires a JSON file",
            ),
            Some("--signer-evidence") => (
                &mut signer_evidence,
                "--signer-evidence requires a directory",
            ),
            Some("--record") => (&mut record, "--record requires an existing JSON file"),
            Some("--output") => (&mut output, "--output requires a new directory"),
            Some(other) => bail!("unknown u280-hbm-rtl-check argument `{other}`"),
            None => bail!("u280-hbm-rtl-check option is not valid UTF-8"),
        };
        if slot.is_some() {
            bail!("{} may only be specified once", argument.to_string_lossy());
        }
        *slot = Some(PathBuf::from(
            args.next().ok_or_else(|| anyhow!(description))?,
        ));
    }
    Ok(Command::U280HbmRtlCheck {
        kernel: kernel.ok_or_else(|| anyhow!("u280-hbm-rtl-check requires --kernel <VERILOG>"))?,
        kernel_manifest: kernel_manifest
            .ok_or_else(|| anyhow!("u280-hbm-rtl-check requires --kernel-manifest <JSON>"))?,
        signer_evidence: signer_evidence
            .ok_or_else(|| anyhow!("u280-hbm-rtl-check requires --signer-evidence <DIRECTORY>"))?,
        record: record.ok_or_else(|| anyhow!("u280-hbm-rtl-check requires --record <JSON>"))?,
        output: output
            .ok_or_else(|| anyhow!("u280-hbm-rtl-check requires --output <NEW_DIRECTORY>"))?,
    })
}

fn parse_signer_throughput(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let mut source_evidence = None;
    let mut output = None;
    while let Some(argument) = args.next() {
        match argument.to_str() {
            Some("--source-evidence") => {
                if source_evidence.is_some() {
                    bail!("--source-evidence may only be specified once");
                }
                source_evidence =
                    Some(PathBuf::from(args.next().ok_or_else(|| {
                        anyhow!("--source-evidence requires a directory")
                    })?));
            }
            Some("--output" | "-o") => {
                if output.is_some() {
                    bail!("--output may only be specified once");
                }
                output =
                    Some(PathBuf::from(args.next().ok_or_else(|| {
                        anyhow!("--output requires a new directory")
                    })?));
            }
            Some(other) => bail!("unknown signer-throughput argument `{other}`"),
            None => bail!("signer-throughput option is not valid UTF-8"),
        }
    }
    Ok(Command::SignerThroughput {
        source_evidence: source_evidence
            .ok_or_else(|| anyhow!("signer-throughput requires --source-evidence <DIRECTORY>"))?,
        output: output
            .ok_or_else(|| anyhow!("signer-throughput requires --output <NEW_DIRECTORY>"))?,
    })
}

fn parse_internal_signer_lower(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let kind = required_utf8(args.next(), "internal signer lowering kind")?;
    if !matches!(kind.as_str(), "lane" | "skeleton" | "benchmark-skeleton") {
        bail!("unknown internal signer lowering kind `{kind}`");
    }
    if args.next().as_deref() != Some(std::ffi::OsStr::new("--output")) {
        bail!("internal signer lowerer requires --output <FILE>");
    }
    let output = PathBuf::from(
        args.next()
            .ok_or_else(|| anyhow!("internal signer lowerer requires an output file"))?,
    );
    if args.next().as_deref() != Some(std::ffi::OsStr::new("--source-commit")) {
        bail!("internal signer lowerer requires --source-commit <COMMIT>");
    }
    let source_commit = required_utf8(args.next(), "internal signer source commit")?;
    ensure_no_extra(args, "internal signer lowerer")?;
    Ok(Command::InternalSignerLower {
        kind,
        output,
        source_commit,
    })
}

fn parse_generate(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let target = required_utf8(args.next(), "generation target")?;
    let mut output = None;
    let mut force = false;
    while let Some(argument) = args.next() {
        match argument.to_str() {
            Some("--output" | "-o") => {
                if output.is_some() {
                    bail!("--output may only be specified once");
                }
                output = Some(PathBuf::from(
                    args.next()
                        .ok_or_else(|| anyhow!("--output requires a directory"))?,
                ));
            }
            Some("--force") if !force => force = true,
            Some("--force") => bail!("--force may only be specified once"),
            Some(other) => bail!("unknown generate argument `{other}`"),
            None => bail!("generate option is not valid UTF-8"),
        }
    }
    Ok(Command::Generate {
        target,
        output: output.ok_or_else(|| anyhow!("generate requires --output <DIRECTORY>"))?,
        force,
    })
}

fn parse_check(mut args: impl Iterator<Item = OsString>) -> Result<Command> {
    let mut temp_root = None;
    let mut keep = false;
    let mut full = false;
    let mut signer_full = false;
    while let Some(argument) = args.next() {
        match argument.to_str() {
            Some("--temp-root") => {
                if temp_root.is_some() {
                    bail!("--temp-root may only be specified once");
                }
                temp_root =
                    Some(PathBuf::from(args.next().ok_or_else(|| {
                        anyhow!("--temp-root requires a directory")
                    })?));
            }
            Some("--keep") if !keep => keep = true,
            Some("--keep") => bail!("--keep may only be specified once"),
            Some("--full") if !full => full = true,
            Some("--full") => bail!("--full may only be specified once"),
            Some("--signer-full") if !signer_full => signer_full = true,
            Some("--signer-full") => bail!("--signer-full may only be specified once"),
            Some(other) => bail!("unknown check argument `{other}`"),
            None => bail!("check option is not valid UTF-8"),
        }
    }
    Ok(Command::Check {
        temp_root,
        keep,
        full,
        signer_full,
    })
}

fn required_utf8(value: Option<OsString>, description: &str) -> Result<String> {
    let value = value.ok_or_else(|| anyhow!("missing {description}"))?;
    value
        .into_string()
        .map_err(|_| anyhow!("{description} is not valid UTF-8"))
}

fn ensure_no_extra(mut args: impl Iterator<Item = OsString>, operation: &str) -> Result<()> {
    if let Some(extra) = args.next() {
        bail!(
            "{operation} does not accept argument `{}`",
            extra.to_string_lossy()
        );
    }
    Ok(())
}

/// Parse and execute arguments excluding the executable name.
///
/// # Errors
///
/// Returns argument, generation, filesystem, Git, Icarus, or Verilator
/// diagnostics.
pub fn run_from_args<I, S>(args: I) -> Result<String>
where
    I: IntoIterator<Item = S>,
    S: Into<OsString>,
{
    execute(parse_args(args)?)
}

/// Execute one parsed command and return its human-readable output.
///
/// # Errors
///
/// Returns generation, filesystem, Git, Icarus, or Verilator diagnostics.
pub fn execute(command: Command) -> Result<String> {
    match command {
        Command::List => Ok(render_target_list()),
        Command::Help => Ok(USAGE.to_owned()),
        Command::Generate {
            target,
            output,
            force,
        } => {
            let spec = find_target(&target)?;
            let provenance = SourceProvenance::discover()?;
            let artifact = generate_target(spec, &output, force, &provenance)?;
            Ok(format!(
                "generated {}\nmanifest {}\nevidence tier: {}",
                artifact.verilog_path.display(),
                artifact.manifest_path.display(),
                GENERATED_VERILOG_EVIDENCE_TIER
            ))
        }
        Command::Check {
            temp_root,
            keep,
            full,
            signer_full,
        } => run_check(temp_root.as_deref(), keep, full, signer_full),
        Command::SignerThroughput {
            source_evidence,
            output,
        } => run_signer_throughput_check(&source_evidence, &output),
        Command::BenchmarkKernel { output } => {
            benchmark_kernel::run_benchmark_kernel_generation(&output)
        }
        Command::U280LinkGraph {
            kernel,
            kernel_manifest,
            signer_evidence,
            output,
        } => {
            let record = u280_hbm_check::write_immutable_combined_link_record(
                &kernel,
                &kernel_manifest,
                &signer_evidence,
                &output,
            )?;
            Ok(format!(
                "validated immutable provenance-bound U280 link graph\nrecord {}\nkernel sha256 {}\nsigner sha256 {}\nreachable modules {}\nevidence boundary: exact current generated source, successful finite signer evidence, and structural reachability only; not synthesis, timing, route, resource, or hardware evidence",
                output.display(),
                record.kernel.sha256,
                record.signer_bundle.sha256,
                record.modules.len()
            ))
        }
        Command::U280VerifyLinkGraph {
            kernel,
            kernel_manifest,
            signer_evidence,
            record,
        } => {
            let validated = u280_hbm_check::verify_immutable_combined_link_record(
                &kernel,
                &kernel_manifest,
                &signer_evidence,
                &record,
            )?;
            Ok(format!(
                "verified immutable provenance-bound U280 link graph\nrecord {}\nkernel sha256 {}\nsigner sha256 {}\nreachable modules {}\nno files written",
                record.display(),
                validated.kernel.sha256,
                validated.signer_bundle.sha256,
                validated.modules.len()
            ))
        }
        Command::U280HbmRtlCheck {
            kernel,
            kernel_manifest,
            signer_evidence,
            record,
            output,
        } => u280_hbm_rtl_check::run(
            &kernel,
            &kernel_manifest,
            &signer_evidence,
            &record,
            &output,
        ),
        Command::InternalSignerLower {
            kind,
            output,
            source_commit,
        } => full_signer_check::run_internal_lowerer(&kind, &output, &source_commit),
    }
}

/// Look up a target by its stable registry name.
///
/// # Errors
///
/// Returns an error listing valid target names when no match exists.
pub fn find_target(name: &str) -> Result<&'static TargetSpec> {
    TARGETS
        .iter()
        .find(|target| target.name == name)
        .ok_or_else(|| {
            anyhow!(
                "unknown target `{name}`; available targets: {}",
                TARGETS
                    .iter()
                    .map(|target| target.name)
                    .collect::<Vec<_>>()
                    .join(", ")
            )
        })
}

fn render_target_list() -> String {
    let mut output = String::from("TARGET\tPROFILE\tTOP\tVALIDATION\tDESCRIPTION\n");
    for target in TARGETS {
        let _ = writeln!(
            output,
            "{}\t{}\t{}\t{}\t{}",
            target.name,
            target.profile,
            target.top_module,
            target.validation_scope,
            target.description
        );
    }
    output.pop();
    output
}

/// Generate one target and its deterministic provenance manifest.
///
/// Source provenance must be captured before this function is called.  If
/// either deterministic destination exists, generation fails unless `force` is
/// true.
///
/// # Errors
///
/// Returns an error on lowering, serialization, directory, overwrite, or file
/// write failures.
pub fn generate_target(
    target: &TargetSpec,
    output_dir: &Path,
    force: bool,
    provenance: &SourceProvenance,
) -> Result<GeneratedArtifact> {
    fs::create_dir_all(output_dir).with_context(|| {
        format!(
            "creating selected output directory {}",
            output_dir.display()
        )
    })?;
    let verilog_path = output_dir.join(target.verilog_filename);
    let manifest_path = output_dir.join(target.manifest_filename);
    check_overwrite(&verilog_path, force)?;
    check_overwrite(&manifest_path, force)?;

    let mut verilog = (target.generate)()?;
    if !verilog.ends_with('\n') {
        verilog.push('\n');
    }
    let digest = hex::encode(Sha256::digest(verilog.as_bytes()));
    let manifest = ArtifactManifest {
        schema_version: 2,
        target: target.name.to_owned(),
        profile: target.profile.to_owned(),
        evidence_tier: GENERATED_VERILOG_EVIDENCE_TIER.to_owned(),
        validation_scope: target.validation_scope.to_owned(),
        verilog_file: target.verilog_filename.to_owned(),
        verilog_sha256: digest,
        source_git_commit: provenance.commit.clone(),
        source_git_dirty: provenance.dirty,
        rhdl_revision: RHDL_REVISION.to_owned(),
        hashsigs_revision: HASHSIGS_REVISION.to_owned(),
        generator_version: env!("CARGO_PKG_VERSION").to_owned(),
    };
    let mut manifest_json =
        serde_json::to_string_pretty(&manifest).context("serializing the provenance manifest")?;
    manifest_json.push('\n');

    write_output(&verilog_path, verilog.as_bytes(), force)?;
    if let Err(error) = write_output(&manifest_path, manifest_json.as_bytes(), force) {
        if !force {
            let _ = fs::remove_file(&verilog_path);
        }
        return Err(error);
    }
    Ok(GeneratedArtifact {
        verilog_path,
        manifest_path,
        manifest,
    })
}

fn check_overwrite(path: &Path, force: bool) -> Result<()> {
    if path.exists() && !force {
        bail!(
            "refusing to overwrite {}; pass --force to replace this target's files",
            path.display()
        );
    }
    Ok(())
}

fn write_output(path: &Path, content: &[u8], force: bool) -> Result<()> {
    let mut options = OpenOptions::new();
    options.write(true);
    if force {
        options.create(true).truncate(true);
    } else {
        options.create_new(true);
    }
    let mut file = options
        .open(path)
        .with_context(|| format!("opening output {}", path.display()))?;
    file.write_all(content)
        .with_context(|| format!("writing output {}", path.display()))?;
    file.sync_all()
        .with_context(|| format!("syncing output {}", path.display()))
}

fn git_output<const N: usize>(source_dir: &Path, arguments: [&str; N]) -> Result<String> {
    let output = ProcessCommand::new("git")
        .env("GIT_OPTIONAL_LOCKS", "0")
        .arg("--no-optional-locks")
        .arg("-C")
        .arg(source_dir)
        .args(arguments)
        .output()
        .context("running Git for source provenance")?;
    if !output.status.success() {
        bail!(
            "Git source-provenance command failed: {}",
            String::from_utf8_lossy(&output.stderr).trim()
        );
    }
    String::from_utf8(output.stdout)
        .context("Git source-provenance output is not UTF-8")
        .map(|output| output.trim().to_owned())
}

fn run_check(
    temp_root: Option<&Path>,
    keep: bool,
    full: bool,
    signer_full: bool,
) -> Result<String> {
    let provenance = SourceProvenance::discover()?;
    if signer_full && provenance.dirty {
        bail!(
            "`rhdl-gen check --signer-full` requires a clean source worktree; commit or remove source changes before producing immutable RTL evidence"
        );
    }
    let root = temp_root.map_or_else(std::env::temp_dir, Path::to_path_buf);
    fs::create_dir_all(&root)
        .with_context(|| format!("creating selected temporary root {}", root.display()))?;
    let workspace = CheckWorkspace::create(&root, keep)?;
    require_iverilog(workspace.path())?;
    let quick_targets = [
        "legacy-keccak-round",
        "legacy-keccak-iterative",
        "sha256-round",
        "sha256-pipeline-2",
    ];
    for target_name in quick_targets {
        let target = find_target(target_name)?;
        let artifact = generate_target(target, workspace.path(), false, &provenance)?;
        elaborate_with_iverilog(target, &artifact.verilog_path, workspace.path())?;
    }
    let full_report = if full {
        let full_targets = [
            (
                "sha256-compression-lane-64-unchecked",
                "sha256_lane_arithmetic_tb",
                full_sha_check::lane_testbench(),
                full_sha_check::LANE_PASS_MARKER,
            ),
            (
                "sha256-compression-farm-3x64-unchecked",
                "sha256_farm_arithmetic_tb",
                full_sha_check::farm_testbench(),
                full_sha_check::FARM_PASS_MARKER,
            ),
        ];
        let mut reports = Vec::with_capacity(full_targets.len() * 2);
        for (target_name, testbench_top, testbench, pass_marker) in full_targets {
            let target = find_target(target_name)?;
            let artifact = generate_target(target, workspace.path(), false, &provenance)?;
            reports.push(lint_with_verilator(
                target,
                &artifact.verilog_path,
                workspace.path(),
                keep,
            )?);
            reports.push(simulate_sha_arithmetic_with_verilator(
                target,
                &artifact.verilog_path,
                workspace.path(),
                keep,
                testbench_top,
                &testbench,
                pass_marker,
            )?);
        }
        Some(reports.join("\n"))
    } else {
        None
    };
    let signer_report = if signer_full {
        Some(run_signer_full_check(workspace.path(), keep, &provenance)?)
    } else {
        None
    };
    let disposition = if keep {
        format!("kept at {}", workspace.path().display())
    } else {
        "removed after success".to_owned()
    };
    let evidence_tier = GENERATED_VERILOG_EVIDENCE_TIER;
    let mut report = format!(
        "Icarus syntax/elaboration checks passed for {}\nevidence boundary: syntax/elaboration only; not simulation or equivalence evidence",
        quick_targets.join(", ")
    );
    if let Some(full_report) = full_report {
        let _ = write!(report, "\n{full_report}");
    }
    if let Some(signer_report) = signer_report {
        let _ = write!(report, "\n{signer_report}");
    }
    let _ = write!(
        report,
        "\ntemporary workspace: {disposition}\nevidence tier: {evidence_tier}"
    );
    Ok(report)
}

fn run_signer_full_check(
    output_dir: &Path,
    keep: bool,
    provenance: &SourceProvenance,
) -> Result<String> {
    let artifact = full_signer_check::generate_bundle(output_dir, provenance)?;
    full_signer_check::validate_persisted_bundle(&artifact)?;
    let lint = lint_with_verilator(&SIGNER_FULL_TARGET, &artifact.bundle_path, output_dir, keep)?;
    let lint_log_path = output_dir.join(format!(
        "verilator-lint-{}.log",
        full_signer_check::SIGNER_TARGET_NAME
    ));
    let object_dir = output_dir.join(format!(
        "verilator_sim_{}",
        full_signer_check::SIGNER_TARGET_NAME
    ));

    full_signer_check::validate_persisted_bundle(&artifact)?;
    let build = build_verilator_testbench(VerilatorBuildRequest {
        target: &SIGNER_FULL_TARGET,
        verilog: &artifact.bundle_path,
        output_dir,
        keep,
        testbench_top: full_signer_check::SIGNER_TESTBENCH_TOP,
        testbench_path: &artifact.testbench_path,
        object_dir: &object_dir,
        evidence_label: "signer",
    })?;
    full_signer_check::validate_persisted_bundle(&artifact)?;
    let simulation = run_verilator_testbench(
        &SIGNER_FULL_TARGET,
        output_dir,
        keep,
        full_signer_check::SIGNER_TESTBENCH_TOP,
        full_signer_check::SIGNER_PASS_MARKER,
        &object_dir,
        "signer",
    )?;
    full_signer_check::validate_persisted_bundle(&artifact)?;
    let evidence_manifest = full_signer_check::write_check_evidence_manifest(
        &artifact,
        &lint_log_path,
        &build.log_path,
        &simulation.log_path,
    )?;

    Ok(format!(
        "{lint}\nVerilator modular production-signer simulation passed with marker `{}` after {:.3}s build + {:.3}s run\nevidence boundary: exact finite-vector generated-RTL equivalence for one reset-discarded job and twelve completed jobs, including saturation, frame bytes, job identity, ready/valid stability, final hold, releases, and quiescence; not formal proof, sustained-throughput, synthesis, timing, route, resource, or hardware evidence\nimmutable lane source: {}\nimmutable signer skeleton: {}\nimmutable linked bundle: {}\nimmutable bundle manifest: {}\nimmutable signer testbench: {}\nimmutable lowering logs: {}, {}\nimmutable check-evidence manifest: {}\nVerilator signer logs: {}, {}",
        full_signer_check::SIGNER_PASS_MARKER,
        build.elapsed.as_secs_f64(),
        simulation.elapsed.as_secs_f64(),
        render_artifact_location(&artifact.lane_path, keep),
        render_artifact_location(&artifact.skeleton_path, keep),
        render_artifact_location(&artifact.bundle_path, keep),
        render_artifact_location(&artifact.manifest_path, keep),
        render_artifact_location(&artifact.testbench_path, keep),
        render_artifact_location(&artifact.lane_lowering_log_path, keep),
        render_artifact_location(&artifact.skeleton_lowering_log_path, keep),
        render_artifact_location(&evidence_manifest, keep),
        render_artifact_location(&build.log_path, keep),
        render_artifact_location(&simulation.log_path, keep),
    ))
}

fn create_throughput_output_directory(selected: &Path, source_evidence: &Path) -> Result<PathBuf> {
    ensure!(
        !selected.exists(),
        "signer-throughput output already exists; select a new directory: {}",
        selected.display()
    );
    let file_name = selected
        .file_name()
        .filter(|name| !name.is_empty())
        .ok_or_else(|| anyhow!("signer-throughput output must name a new child directory"))?;
    let parent = selected
        .parent()
        .filter(|parent| !parent.as_os_str().is_empty())
        .unwrap_or_else(|| Path::new("."));
    ensure!(
        parent.is_dir(),
        "signer-throughput output parent does not exist: {}",
        parent.display()
    );
    let parent = fs::canonicalize(parent)
        .with_context(|| format!("canonicalizing output parent {}", parent.display()))?;
    let output = parent.join(file_name);
    ensure!(
        !output.starts_with(source_evidence),
        "signer-throughput output must not modify the immutable source-evidence directory"
    );
    let repository = Path::new(env!("CARGO_MANIFEST_DIR"))
        .parent()
        .and_then(Path::parent)
        .context("rhdl-gen crate is not nested beneath the workspace root")?;
    let repository = fs::canonicalize(repository)
        .context("canonicalizing the signer-throughput flow workspace")?;
    ensure!(
        !output.starts_with(&repository),
        "signer-throughput output must be outside the source workspace"
    );
    fs::create_dir(&output)
        .with_context(|| format!("creating signer-throughput output {}", output.display()))?;
    fs::canonicalize(&output).with_context(|| {
        format!(
            "canonicalizing signer-throughput output {}",
            output.display()
        )
    })
}

fn require_verilator_version(output_dir: &Path) -> Result<String> {
    let output = ProcessCommand::new("verilator")
        .env("TMPDIR", output_dir)
        .env("TMP", output_dir)
        .env("TEMP", output_dir)
        .arg("--version")
        .output()
        .map_err(|error| {
            if error.kind() == std::io::ErrorKind::NotFound {
                anyhow!(
                    "Verilator is required for `rhdl-gen signer-throughput` but was not found in PATH"
                )
            } else {
                anyhow!(error)
            }
        })?;
    ensure!(
        output.status.success(),
        "Verilator is present but `verilator --version` failed: {}",
        String::from_utf8_lossy(&output.stderr).trim()
    );
    let version = String::from_utf8(output.stdout).context("Verilator version is not UTF-8")?;
    ensure!(
        !version.trim().is_empty(),
        "Verilator returned an empty version"
    );
    Ok(version.trim().to_owned())
}

fn run_signer_throughput_check(source_evidence: &Path, output: &Path) -> Result<String> {
    let flow_provenance = SourceProvenance::discover()?;
    ensure!(
        !flow_provenance.dirty,
        "`rhdl-gen signer-throughput` requires a clean flow worktree so its evidence binds committed code"
    );
    let source = full_signer_check::validate_successful_evidence_directory(source_evidence)?;
    let output_dir = create_throughput_output_directory(output, &source.directory)?;
    let flow_executable = std::env::current_exe().context("locating the rhdl-gen executable")?;
    let flow_executable_record = full_signer_check::file_record(&flow_executable)?;
    let verilator_version = require_verilator_version(&output_dir)?;
    let testbench_path = signer_throughput_check::write_throughput_testbench(&output_dir)?;
    let testbench_record = full_signer_check::file_record(&testbench_path)?;
    let object_dir = output_dir.join("verilator_sim_sha256-signer-sustained-throughput");

    ensure!(
        full_signer_check::validate_successful_evidence_directory(&source.directory)? == source,
        "signer source evidence changed before throughput build"
    );
    let build = build_verilator_testbench(VerilatorBuildRequest {
        target: &SIGNER_FULL_TARGET,
        verilog: &source.bundle_path,
        output_dir: &output_dir,
        keep: true,
        testbench_top: signer_throughput_check::THROUGHPUT_TESTBENCH_TOP,
        testbench_path: &testbench_path,
        object_dir: &object_dir,
        evidence_label: "signer-throughput",
    })?;
    ensure!(
        full_signer_check::file_record(&testbench_path)? == testbench_record,
        "throughput testbench changed during Verilator build"
    );
    ensure!(
        full_signer_check::validate_successful_evidence_directory(&source.directory)? == source,
        "signer source evidence changed during throughput build"
    );
    let simulator = object_dir.join(format!(
        "V{}",
        signer_throughput_check::THROUGHPUT_TESTBENCH_TOP
    ));
    let simulator_record = full_signer_check::file_record(&simulator)?;
    let simulation = run_verilator_testbench(
        &SIGNER_FULL_TARGET,
        &output_dir,
        true,
        signer_throughput_check::THROUGHPUT_TESTBENCH_TOP,
        signer_throughput_check::THROUGHPUT_PASS_MARKER,
        &object_dir,
        "signer-throughput",
    )?;
    ensure!(
        full_signer_check::file_record(&simulator)? == simulator_record,
        "Verilator throughput simulator changed while it was running"
    );
    ensure!(
        full_signer_check::file_record(&testbench_path)? == testbench_record,
        "throughput testbench changed during simulation"
    );
    ensure!(
        full_signer_check::validate_successful_evidence_directory(&source.directory)? == source,
        "signer source evidence changed during throughput simulation"
    );
    let final_flow_provenance = SourceProvenance::discover()?;
    ensure!(
        final_flow_provenance == flow_provenance && !final_flow_provenance.dirty,
        "throughput flow source changed during the external build or simulation"
    );
    ensure!(
        full_signer_check::file_record(&flow_executable)? == flow_executable_record,
        "rhdl-gen executable changed during the throughput gate"
    );
    let manifest = signer_throughput_check::write_throughput_manifest(
        &output_dir,
        &signer_throughput_check::ThroughputManifestInputs {
            source: &source,
            flow_provenance: &flow_provenance,
            flow_executable: &flow_executable,
            verilator_version: &verilator_version,
            testbench: &testbench_path,
            simulator: &simulator,
            build_log: &build.log_path,
            simulation_log: &simulation.log_path,
        },
    )?;

    Ok(format!(
        "Verilator sustained signer throughput simulation passed with marker `{}` after {:.3}s build + {:.3}s run\nevidence boundary: 72 exact fused private-seed oracle frames under continuous admission and always-ready output; completion boundaries 12 through 60 must span at most 24,000 cycles (500 cycles/result normalized at 250 MHz); not formal proof, synthesis, timing, route, resource, or hardware evidence\nimmutable source signer bundle: {}\nimmutable source bundle/check-evidence manifests: {}, {}\nimmutable throughput testbench: {}\nread-only throughput simulator: {}\nimmutable throughput build/simulation logs: {}, {}\nimmutable throughput evidence manifest: {}",
        signer_throughput_check::THROUGHPUT_PASS_MARKER,
        build.elapsed.as_secs_f64(),
        simulation.elapsed.as_secs_f64(),
        source.bundle_path.display(),
        source.bundle_manifest_path.display(),
        source.check_evidence_manifest_path.display(),
        testbench_path.display(),
        simulator.display(),
        build.log_path.display(),
        simulation.log_path.display(),
        manifest.display(),
    ))
}

fn lint_with_verilator(
    target: &TargetSpec,
    verilog: &Path,
    output_dir: &Path,
    keep: bool,
) -> Result<String> {
    let version = ProcessCommand::new("verilator")
        .env("TMPDIR", output_dir)
        .env("TMP", output_dir)
        .env("TEMP", output_dir)
        .arg("--version")
        .output()
        .map_err(|error| {
            if error.kind() == std::io::ErrorKind::NotFound {
                anyhow!(
                    "Verilator is required for `rhdl-gen check --full` or `--signer-full` but was not found in PATH"
                )
            } else {
                anyhow!(error)
            }
        })?;
    if !version.status.success() {
        bail!(
            "Verilator is present but `verilator --version` failed: {}",
            String::from_utf8_lossy(&version.stderr).trim()
        );
    }
    let version = String::from_utf8_lossy(&version.stdout).trim().to_owned();
    let object_dir = output_dir.join(format!("verilator_lint_{}", target.name));
    let started = Instant::now();
    let output = ProcessCommand::new("verilator")
        .env("TMPDIR", output_dir)
        .env("TMP", output_dir)
        .env("TEMP", output_dir)
        .arg("--lint-only")
        .arg("-Wall")
        .arg("-Wno-fatal")
        .arg("--threads")
        .arg("1")
        .arg("--top-module")
        .arg(target.top_module)
        .arg("--Mdir")
        .arg(&object_dir)
        .arg(verilog)
        .output()
        .with_context(|| format!("invoking Verilator for target {}", target.name))?;
    let elapsed = started.elapsed();
    let stdout = String::from_utf8_lossy(&output.stdout);
    let stderr = String::from_utf8_lossy(&output.stderr);
    let warning_inventory = verilator_warning_inventory(&stderr);
    let warning_count = warning_inventory.values().sum::<usize>();
    let warning_summary = render_warning_inventory(&warning_inventory);
    let log_path = output_dir.join(format!("verilator-lint-{}.log", target.name));
    let log = format!(
        "command: verilator --lint-only -Wall -Wno-fatal --threads 1 --top-module {} --Mdir {} {}\nversion: {version}\nelapsed_seconds: {:.3}\nstatus: {}\nstdout:\n{}\nstderr:\n{}\n",
        target.top_module,
        object_dir.display(),
        verilog.display(),
        elapsed.as_secs_f64(),
        output.status,
        stdout.trim(),
        stderr.trim(),
    );
    fs::write(&log_path, log)
        .with_context(|| format!("writing Verilator diagnostic log {}", log_path.display()))?;
    if !output.status.success() {
        bail!(
            "Verilator lint/elaboration failed for target {} (top {}) after {:.3}s; diagnostic log: {}:\nstdout:\n{}\nstderr:\n{}",
            target.name,
            target.top_module,
            elapsed.as_secs_f64(),
            render_artifact_location(&log_path, keep),
            stdout.trim(),
            stderr.trim()
        );
    }
    Ok(format!(
        "Verilator lint/elaboration passed for {} (top {}) with {version} in {:.3}s; accepted warning inventory: {} total ({}) (captured in log)\nevidence boundary: unchecked rendering plus lint/elaboration only; not simulation or equivalence evidence; warning acceptance is not a warning-clean claim\nVerilator log: {}",
        target.name,
        target.top_module,
        elapsed.as_secs_f64(),
        warning_count,
        warning_summary,
        render_artifact_location(&log_path, keep)
    ))
}

fn verilator_warning_inventory(stderr: &str) -> BTreeMap<String, usize> {
    let mut inventory = BTreeMap::new();
    for code in stderr.lines().filter_map(|line| {
        line.strip_prefix("%Warning-")
            .and_then(|warning| warning.split_once(':'))
            .map(|(code, _)| code)
    }) {
        *inventory.entry(code.to_owned()).or_default() += 1;
    }
    inventory
}

fn render_warning_inventory(inventory: &BTreeMap<String, usize>) -> String {
    if inventory.is_empty() {
        return "none".to_owned();
    }
    let mut summary = String::new();
    for (index, (code, count)) in inventory.iter().enumerate() {
        if index != 0 {
            summary.push_str(", ");
        }
        write!(summary, "{code}={count}").expect("writing to a String cannot fail");
    }
    summary
}

fn simulate_sha_arithmetic_with_verilator(
    target: &TargetSpec,
    verilog: &Path,
    output_dir: &Path,
    keep: bool,
    testbench_top: &str,
    testbench: &str,
    pass_marker: &str,
) -> Result<String> {
    let testbench_path = output_dir.join(format!("{testbench_top}.sv"));
    fs::write(&testbench_path, testbench).with_context(|| {
        format!(
            "writing SHA arithmetic testbench {}",
            testbench_path.display()
        )
    })?;
    let object_dir = output_dir.join(format!("verilator_sim_{}", target.name));
    let build = build_verilator_testbench(VerilatorBuildRequest {
        target,
        verilog,
        output_dir,
        keep,
        testbench_top,
        testbench_path: &testbench_path,
        object_dir: &object_dir,
        evidence_label: "arithmetic",
    })?;
    let simulation = run_verilator_testbench(
        target,
        output_dir,
        keep,
        testbench_top,
        pass_marker,
        &object_dir,
        "arithmetic",
    )?;
    Ok(format!(
        "Verilator generated-RTL arithmetic simulation passed for {} with marker `{}` after {:.3}s build + {:.3}s run\nevidence boundary: deterministic host-model equivalence, exact latency, tag, bubble, and reset-valid behavior for the exercised vectors only; not formal proof, synthesis, timing, route, or hardware evidence\nVerilator testbench: {}\nVerilator simulation logs: {}, {}",
        target.name,
        pass_marker,
        build.elapsed.as_secs_f64(),
        simulation.elapsed.as_secs_f64(),
        render_artifact_location(&testbench_path, keep),
        render_artifact_location(&build.log_path, keep),
        render_artifact_location(&simulation.log_path, keep)
    ))
}

struct VerilatorPhaseEvidence {
    elapsed: Duration,
    log_path: PathBuf,
}

#[derive(Clone, Copy)]
struct VerilatorBuildRequest<'a> {
    target: &'a TargetSpec,
    verilog: &'a Path,
    output_dir: &'a Path,
    keep: bool,
    testbench_top: &'a str,
    testbench_path: &'a Path,
    object_dir: &'a Path,
    evidence_label: &'a str,
}

fn build_verilator_testbench(request: VerilatorBuildRequest<'_>) -> Result<VerilatorPhaseEvidence> {
    let VerilatorBuildRequest {
        target,
        verilog,
        output_dir,
        keep,
        testbench_top,
        testbench_path,
        object_dir,
        evidence_label,
    } = request;
    let build_started = Instant::now();
    let build = ProcessCommand::new("verilator")
        .env("TMPDIR", output_dir)
        .env("TMP", output_dir)
        .env("TEMP", output_dir)
        .arg("--binary")
        .arg("--timing")
        .arg("-Wno-fatal")
        .arg("-Wno-DECLFILENAME")
        .arg("-Wno-UNUSEDSIGNAL")
        .arg("--threads")
        .arg("1")
        .arg("-j")
        .arg("1")
        .arg("--top-module")
        .arg(testbench_top)
        .arg("--Mdir")
        .arg(object_dir)
        .arg(verilog)
        .arg(testbench_path)
        .output()
        .with_context(|| {
            format!(
                "building the Verilator {evidence_label} testbench for {}",
                target.name,
            )
        })?;
    let build_elapsed = build_started.elapsed();
    let build_stdout = String::from_utf8_lossy(&build.stdout);
    let build_stderr = String::from_utf8_lossy(&build.stderr);
    let build_log_path = output_dir.join(format!(
        "verilator-{evidence_label}-build-{}.log",
        target.name
    ));
    let build_log = format!(
        "command: verilator --binary --timing -Wno-fatal -Wno-DECLFILENAME -Wno-UNUSEDSIGNAL --threads 1 -j 1 --top-module {testbench_top} --Mdir {} {} {}\nelapsed_seconds: {:.3}\nstatus: {}\nstdout:\n{}\nstderr:\n{}\n",
        object_dir.display(),
        verilog.display(),
        testbench_path.display(),
        build_elapsed.as_secs_f64(),
        build.status,
        build_stdout.trim(),
        build_stderr.trim()
    );
    fs::write(&build_log_path, build_log).with_context(|| {
        format!(
            "writing {evidence_label} simulation build log {}",
            build_log_path.display()
        )
    })?;
    if !build.status.success() {
        bail!(
            "Verilator could not build the {evidence_label} testbench for {} after {:.3}s; diagnostic log: {}:\nstdout:\n{}\nstderr:\n{}",
            target.name,
            build_elapsed.as_secs_f64(),
            render_artifact_location(&build_log_path, keep),
            build_stdout.trim(),
            build_stderr.trim()
        );
    }
    Ok(VerilatorPhaseEvidence {
        elapsed: build_elapsed,
        log_path: build_log_path,
    })
}

fn run_verilator_testbench(
    target: &TargetSpec,
    output_dir: &Path,
    keep: bool,
    testbench_top: &str,
    pass_marker: &str,
    object_dir: &Path,
    evidence_label: &str,
) -> Result<VerilatorPhaseEvidence> {
    let executable = object_dir.join(format!("V{testbench_top}"));
    let simulation_started = Instant::now();
    let simulation = ProcessCommand::new(&executable)
        .env("TMPDIR", output_dir)
        .env("TMP", output_dir)
        .env("TEMP", output_dir)
        .output()
        .with_context(|| {
            format!(
                "running Verilator {evidence_label} simulation {}",
                executable.display(),
            )
        })?;
    let simulation_elapsed = simulation_started.elapsed();
    let simulation_stdout = String::from_utf8_lossy(&simulation.stdout);
    let simulation_stderr = String::from_utf8_lossy(&simulation.stderr);
    let simulation_log_path = output_dir.join(format!(
        "verilator-{evidence_label}-simulation-{}.log",
        target.name,
    ));
    let simulation_log = format!(
        "elapsed_seconds: {:.3}\nstatus: {}\nstdout:\n{}\nstderr:\n{}\n",
        simulation_elapsed.as_secs_f64(),
        simulation.status,
        simulation_stdout.trim(),
        simulation_stderr.trim()
    );
    fs::write(&simulation_log_path, simulation_log).with_context(|| {
        format!(
            "writing {evidence_label} simulation log {}",
            simulation_log_path.display()
        )
    })?;
    if !simulation.status.success() || !simulation_stdout.contains(pass_marker) {
        bail!(
            "Verilator {evidence_label} simulation failed for {} after {:.3}s; expected marker `{}`; diagnostic log: {}:\nstdout:\n{}\nstderr:\n{}",
            target.name,
            simulation_elapsed.as_secs_f64(),
            pass_marker,
            render_artifact_location(&simulation_log_path, keep),
            simulation_stdout.trim(),
            simulation_stderr.trim()
        );
    }
    Ok(VerilatorPhaseEvidence {
        elapsed: simulation_elapsed,
        log_path: simulation_log_path,
    })
}

fn render_artifact_location(path: &Path, keep: bool) -> String {
    if keep {
        format!("{} (preserved by --keep)", path.display())
    } else {
        format!(
            "{} (ephemeral; removed when the check exits, use --keep to preserve)",
            path.display()
        )
    }
}

fn require_iverilog(temp_dir: &Path) -> Result<()> {
    let output = ProcessCommand::new("iverilog")
        .env("TMPDIR", temp_dir)
        .env("TMP", temp_dir)
        .env("TEMP", temp_dir)
        .arg("-V")
        .output()
        .map_err(|error| {
            if error.kind() == std::io::ErrorKind::NotFound {
                anyhow!(
                    "Icarus Verilog (`iverilog`) is required for `rhdl-gen check` but was not found in PATH"
                )
            } else {
                anyhow!(error)
            }
        })?;
    if !output.status.success() {
        bail!(
            "Icarus Verilog is present but `iverilog -V` failed: {}",
            String::from_utf8_lossy(&output.stderr).trim()
        );
    }
    Ok(())
}

fn elaborate_with_iverilog(target: &TargetSpec, verilog: &Path, output_dir: &Path) -> Result<()> {
    let elaborated = output_dir.join(format!("{}.ivl", target.name));
    let output = ProcessCommand::new("iverilog")
        .env("TMPDIR", output_dir)
        .env("TMP", output_dir)
        .env("TEMP", output_dir)
        .arg("-g2012")
        .arg("-s")
        .arg(target.top_module)
        .arg("-o")
        .arg(&elaborated)
        .arg(verilog)
        .output()
        .with_context(|| format!("invoking Icarus for target {}", target.name))?;
    if !output.status.success() {
        bail!(
            "Icarus syntax/elaboration failed for target {} (top {}):\nstdout:\n{}\nstderr:\n{}",
            target.name,
            target.top_module,
            String::from_utf8_lossy(&output.stdout).trim(),
            String::from_utf8_lossy(&output.stderr).trim()
        );
    }
    Ok(())
}

static CHECK_DIRECTORY_COUNTER: AtomicU64 = AtomicU64::new(0);

struct CheckWorkspace {
    path: PathBuf,
    keep: bool,
}

impl CheckWorkspace {
    fn create(root: &Path, keep: bool) -> Result<Self> {
        for _ in 0..100 {
            let counter = CHECK_DIRECTORY_COUNTER.fetch_add(1, Ordering::Relaxed);
            let path = root.join(format!("rhdl-gen-check-{}-{counter}", std::process::id()));
            match fs::create_dir(&path) {
                Ok(()) => {
                    let canonical = fs::canonicalize(&path).with_context(|| {
                        format!(
                            "canonicalizing temporary check directory {}",
                            path.display()
                        )
                    });
                    let path = match canonical {
                        Ok(path) => path,
                        Err(error) => {
                            let _ = fs::remove_dir(&path);
                            return Err(error);
                        }
                    };
                    return Ok(Self { path, keep });
                }
                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
                Err(error) => {
                    return Err(error).with_context(|| {
                        format!("creating temporary check directory {}", path.display())
                    });
                }
            }
        }
        bail!(
            "could not allocate a unique check directory beneath {}",
            root.display()
        )
    }

    fn path(&self) -> &Path {
        &self.path
    }
}

impl Drop for CheckWorkspace {
    fn drop(&mut self) {
        if !self.keep {
            let _ = fs::remove_dir_all(&self.path);
        }
    }
}

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

    static TEST_DIRECTORY_COUNTER: AtomicU64 = AtomicU64::new(0);

    struct TestDirectory(PathBuf);

    impl TestDirectory {
        fn new(label: &str) -> Self {
            let counter = TEST_DIRECTORY_COUNTER.fetch_add(1, Ordering::Relaxed);
            let path = std::env::temp_dir().join(format!(
                "rhdl-gen-test-{}-{counter}-{label}",
                std::process::id()
            ));
            fs::create_dir(&path).expect("create selected test directory");
            Self(path)
        }
    }

    impl Drop for TestDirectory {
        fn drop(&mut self) {
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    fn fixture_provenance() -> SourceProvenance {
        SourceProvenance {
            commit: "0123456789abcdef0123456789abcdef01234567".to_owned(),
            dirty: false,
        }
    }

    #[allow(
        clippy::too_many_lines,
        reason = "the supported-command matrix is kept in one test so every parsed variant remains auditable together"
    )]
    #[test]
    fn parses_supported_commands() {
        assert_eq!(parse_args(["list"]).expect("list parses"), Command::List);
        assert_eq!(
            parse_args([
                "generate",
                "legacy-keccak-round",
                "--output",
                "/tmp/example",
                "--force",
            ])
            .expect("generate parses"),
            Command::Generate {
                target: "legacy-keccak-round".to_owned(),
                output: PathBuf::from("/tmp/example"),
                force: true,
            }
        );
        assert_eq!(
            parse_args(["check", "--full", "--temp-root", "/tmp", "--keep"]).expect("check parses"),
            Command::Check {
                temp_root: Some(PathBuf::from("/tmp")),
                keep: true,
                full: true,
                signer_full: false,
            }
        );
        assert_eq!(
            parse_args(["check", "--signer-full"]).expect("signer check parses"),
            Command::Check {
                temp_root: None,
                keep: false,
                full: false,
                signer_full: true,
            }
        );
        assert_eq!(
            parse_args([
                "signer-throughput",
                "--source-evidence",
                "/tmp/source",
                "--output",
                "/tmp/output",
            ])
            .expect("signer throughput parses"),
            Command::SignerThroughput {
                source_evidence: PathBuf::from("/tmp/source"),
                output: PathBuf::from("/tmp/output"),
            }
        );
        assert_eq!(
            parse_args(["benchmark-kernel", "--output", "/tmp/benchmark"])
                .expect("benchmark kernel parses"),
            Command::BenchmarkKernel {
                output: PathBuf::from("/tmp/benchmark"),
            }
        );
        assert_eq!(
            parse_args([
                "u280-link-graph",
                "--kernel",
                "/tmp/kernel.v",
                "--kernel-manifest",
                "/tmp/kernel.manifest.json",
                "--signer-evidence",
                "/tmp/signer-evidence",
                "--output",
                "/tmp/combined.json",
            ])
            .expect("U280 link graph parses"),
            Command::U280LinkGraph {
                kernel: PathBuf::from("/tmp/kernel.v"),
                kernel_manifest: PathBuf::from("/tmp/kernel.manifest.json"),
                signer_evidence: PathBuf::from("/tmp/signer-evidence"),
                output: PathBuf::from("/tmp/combined.json"),
            }
        );
        assert_eq!(
            parse_args([
                "u280-verify-link-graph",
                "--kernel",
                "/tmp/kernel.v",
                "--kernel-manifest",
                "/tmp/kernel.manifest.json",
                "--signer-evidence",
                "/tmp/signer-evidence",
                "--record",
                "/tmp/combined.json",
            ])
            .expect("U280 link graph verifier parses"),
            Command::U280VerifyLinkGraph {
                kernel: PathBuf::from("/tmp/kernel.v"),
                kernel_manifest: PathBuf::from("/tmp/kernel.manifest.json"),
                signer_evidence: PathBuf::from("/tmp/signer-evidence"),
                record: PathBuf::from("/tmp/combined.json"),
            }
        );
        assert_eq!(
            parse_args([
                "u280-hbm-rtl-check",
                "--kernel",
                "/tmp/kernel.v",
                "--kernel-manifest",
                "/tmp/kernel.manifest.json",
                "--signer-evidence",
                "/tmp/signer-evidence",
                "--record",
                "/tmp/combined.json",
                "--output",
                "/tmp/rtl-evidence",
            ])
            .expect("U280 HBM RTL check parses"),
            Command::U280HbmRtlCheck {
                kernel: PathBuf::from("/tmp/kernel.v"),
                kernel_manifest: PathBuf::from("/tmp/kernel.manifest.json"),
                signer_evidence: PathBuf::from("/tmp/signer-evidence"),
                record: PathBuf::from("/tmp/combined.json"),
                output: PathBuf::from("/tmp/rtl-evidence"),
            }
        );
        assert_eq!(
            parse_args([
                "__signer-lower",
                "lane",
                "--output",
                "/tmp/lane.v",
                "--source-commit",
                "0123456789abcdef",
            ])
            .expect("internal signer lowerer parses"),
            Command::InternalSignerLower {
                kind: "lane".to_owned(),
                output: PathBuf::from("/tmp/lane.v"),
                source_commit: "0123456789abcdef".to_owned(),
            }
        );
    }

    #[allow(
        clippy::too_many_lines,
        reason = "the rejected-command matrix is kept in one test so incomplete and duplicate cases remain auditable together"
    )]
    #[test]
    fn rejects_incomplete_or_duplicate_arguments() {
        assert!(parse_args(["generate", "legacy-keccak-round"]).is_err());
        assert!(
            parse_args([
                "generate",
                "legacy-keccak-round",
                "-o",
                "one",
                "--output",
                "two",
            ])
            .is_err()
        );
        assert!(parse_args(["list", "extra"]).is_err());
        assert!(parse_args(["unknown"]).is_err());
        assert!(parse_args(["check", "--full", "--full"]).is_err());
        assert!(parse_args(["check", "--signer-full", "--signer-full"]).is_err());
        assert!(parse_args(["signer-throughput", "--output", "one"]).is_err());
        assert!(parse_args(["benchmark-kernel"]).is_err());
        assert!(parse_args(["benchmark-kernel", "--output", "one", "extra"]).is_err());
        assert!(
            parse_args([
                "u280-link-graph",
                "--kernel",
                "kernel.v",
                "--output",
                "combined.json",
            ])
            .is_err()
        );
        assert!(
            parse_args([
                "u280-link-graph",
                "--kernel",
                "one.v",
                "--kernel",
                "two.v",
                "--kernel-manifest",
                "kernel.json",
                "--signer-evidence",
                "signer-evidence",
                "--output",
                "combined.json",
            ])
            .is_err()
        );
        assert!(
            parse_args([
                "u280-verify-link-graph",
                "--kernel",
                "kernel.v",
                "--kernel-manifest",
                "kernel.json",
                "--signer-evidence",
                "signer-evidence",
            ])
            .is_err()
        );
        assert!(
            parse_args([
                "u280-hbm-rtl-check",
                "--kernel",
                "kernel.v",
                "--kernel-manifest",
                "kernel.json",
                "--signer-evidence",
                "signer-evidence",
                "--record",
                "combined.json",
            ])
            .is_err()
        );
        assert!(
            parse_args([
                "u280-hbm-rtl-check",
                "--kernel",
                "one.v",
                "--kernel",
                "two.v",
                "--kernel-manifest",
                "kernel.json",
                "--signer-evidence",
                "signer-evidence",
                "--record",
                "combined.json",
                "--output",
                "evidence",
            ])
            .is_err()
        );
        assert!(
            parse_args([
                "u280-verify-link-graph",
                "--kernel",
                "kernel.v",
                "--kernel-manifest",
                "one.json",
                "--kernel-manifest",
                "two.json",
                "--signer-evidence",
                "signer-evidence",
                "--record",
                "combined.json",
            ])
            .is_err()
        );
        assert!(
            parse_args([
                "signer-throughput",
                "--source-evidence",
                "one",
                "--source-evidence",
                "two",
                "--output",
                "three",
            ])
            .is_err()
        );
        assert!(parse_args(["__signer-lower", "farm"]).is_err());
    }

    #[test]
    fn registry_is_profile_explicit_and_easy_to_extend() {
        let expected_names = [
            "legacy-keccak-round",
            "legacy-keccak-permutation",
            "legacy-keccak-iterative",
            "sha256-round",
            "sha256-compression-oracle",
            "sha256-pipeline-2",
            "sha256-pipeline-64-unchecked",
            "sha256-compression-lane-64-unchecked",
            "sha256-compression-farm-3x64-unchecked",
            "sha256-u280-hbm-kernel",
        ];
        assert_eq!(TARGETS.len(), 10);
        assert_eq!(
            TARGETS.iter().map(|target| target.name).collect::<Vec<_>>(),
            expected_names.to_vec()
        );
        for target in TARGETS {
            assert!(matches!(
                target.profile,
                "LEGACY_KECCAK" | "HASHSIGS_SHA256_GENERIC_V1"
            ));
            assert!(
                Path::new(target.verilog_filename)
                    .extension()
                    .is_some_and(|extension| extension.eq_ignore_ascii_case("v"))
            );
            assert!(target.manifest_filename.ends_with(".manifest.json"));
            assert!(!target.validation_scope.is_empty());
        }
        assert_eq!(
            find_target("sha256-pipeline-64-unchecked")
                .expect("unchecked target is registered")
                .profile,
            "HASHSIGS_SHA256_GENERIC_V1"
        );
    }

    #[test]
    fn generation_is_deterministic_and_manifest_digest_matches() {
        let first = TestDirectory::new("deterministic-first");
        let second = TestDirectory::new("deterministic-second");
        let target = find_target("legacy-keccak-round").expect("registered target");
        let provenance = fixture_provenance();
        let first_artifact =
            generate_target(target, &first.0, false, &provenance).expect("first generation");
        let second_artifact =
            generate_target(target, &second.0, false, &provenance).expect("second generation");

        let first_verilog = fs::read(&first_artifact.verilog_path).expect("read first Verilog");
        let second_verilog = fs::read(&second_artifact.verilog_path).expect("read second Verilog");
        assert_eq!(first_verilog, second_verilog);
        assert_eq!(
            fs::read(&first_artifact.manifest_path).expect("read first manifest"),
            fs::read(&second_artifact.manifest_path).expect("read second manifest")
        );
        assert_eq!(
            first_artifact.manifest.verilog_sha256,
            hex::encode(Sha256::digest(&first_verilog))
        );
        assert_eq!(
            first_artifact.manifest.evidence_tier,
            GENERATED_VERILOG_EVIDENCE_TIER
        );
        assert_eq!(
            first_artifact.manifest.validation_scope,
            target.validation_scope
        );
        assert_eq!(first_artifact.manifest.source_git_commit, provenance.commit);
        assert!(!first_artifact.manifest.source_git_dirty);
    }

    #[test]
    fn overwrite_requires_force_and_preserves_existing_content() {
        let directory = TestDirectory::new("overwrite");
        let target = find_target("legacy-keccak-round").expect("registered target");
        let provenance = fixture_provenance();
        let artifact =
            generate_target(target, &directory.0, false, &provenance).expect("initial generation");
        let original = fs::read(&artifact.verilog_path).expect("read initial output");
        let error = generate_target(target, &directory.0, false, &provenance)
            .expect_err("overwrite must fail");
        assert!(error.to_string().contains("refusing to overwrite"));
        assert_eq!(
            fs::read(&artifact.verilog_path).expect("read preserved output"),
            original
        );
        generate_target(target, &directory.0, true, &provenance).expect("forced generation");
        assert_eq!(
            fs::read(&artifact.verilog_path).expect("read forced output"),
            original
        );
    }

    #[test]
    fn throughput_output_requires_a_new_directory_outside_source_evidence() {
        let source = TestDirectory::new("throughput-source-evidence");
        let output_parent = TestDirectory::new("throughput-output-parent");
        assert!(
            create_throughput_output_directory(&source.0, &source.0).is_err(),
            "an existing directory must never be reused"
        );
        assert!(
            create_throughput_output_directory(&source.0.join("nested"), &source.0).is_err(),
            "the immutable source-evidence directory must never receive output"
        );
        let selected = output_parent.0.join("new-evidence");
        let created = create_throughput_output_directory(&selected, &source.0)
            .expect("create new external throughput output");
        assert!(created.is_dir());
        assert_eq!(
            created,
            fs::canonicalize(&selected).expect("canonical new output")
        );
    }

    #[test]
    fn default_generation_targets_contain_their_declared_top_modules() {
        for target in TARGETS
            .iter()
            .filter(|target| target.default_unit_generation)
        {
            let generated = (target.generate)().expect("target lowers");
            assert!(
                generated.contains(&format!("module {}", target.top_module)),
                "target {} lacks top {}",
                target.name,
                target.top_module
            );
        }
    }

    #[test]
    fn slow_and_unchecked_targets_are_not_in_default_generation_loops() {
        for name in [
            "sha256-compression-oracle",
            "sha256-pipeline-64-unchecked",
            "sha256-compression-lane-64-unchecked",
            "sha256-compression-farm-3x64-unchecked",
        ] {
            assert!(
                !find_target(name)
                    .expect("special target is registered")
                    .default_unit_generation
            );
        }
        assert!(
            find_target("sha256-pipeline-64-unchecked")
                .expect("unchecked target is registered")
                .validation_scope
                .contains("not RHDL/RTL equivalence evidence")
        );
    }

    #[test]
    fn full_check_support_files_make_their_scope_and_lifetime_explicit() {
        assert!(full_sha_check::lane_testbench().contains(full_sha_check::LANE_PASS_MARKER));
        assert!(full_sha_check::farm_testbench().contains(full_sha_check::FARM_PASS_MARKER));
        assert!(
            render_artifact_location(Path::new("example.log"), false)
                .contains("ephemeral; removed when the check exits")
        );
        assert!(
            render_artifact_location(Path::new("example.log"), true)
                .contains("preserved by --keep")
        );
    }

    #[test]
    fn verilator_warning_inventory_is_code_specific_and_deterministic() {
        let stderr = "%Warning-UNUSEDSIGNAL: first\n%Warning-UNOPTFLAT: second\ncontinuation\n%Warning-UNUSEDSIGNAL: third\n";
        let inventory = verilator_warning_inventory(stderr);
        assert_eq!(inventory.get("UNOPTFLAT"), Some(&1));
        assert_eq!(inventory.get("UNUSEDSIGNAL"), Some(&2));
        assert_eq!(
            render_warning_inventory(&inventory),
            "UNOPTFLAT=1, UNUSEDSIGNAL=2"
        );
        assert_eq!(render_warning_inventory(&BTreeMap::new()), "none");
    }
}