u280_evidence_oracle/

sealed_result.rs

//! Receipt-bound, typed revalidation of a completed Phase-B oracle result.

use super::{
    DEFAULT_KERNEL, MAXIMUM_BATCH, MAXIMUM_P95_CAPTURE_CYCLES_EXACT,
    MINIMUM_SIGNATURES_PER_SECOND_EXACT, OracleOutcome, PERFORMANCE_CLOCK_BOUND_HZ,
    PHASE_B_ORACLE_RECEIPT_SCHEMA, PHASE_B_TYPED_RESULT_CONTRACT, PHASE_B_TYPED_RESULT_SCHEMA,
    PROFILE, REQUEST_KIND, REQUIRED_PERFORMANCE_BATCH, REQUIRED_PERFORMANCE_SAMPLES,
    RESULT_EVIDENCE_BOUNDARY, RESULT_KIND, SUMMARY_BYTES, SampleSpec, SampleValidationState,
    advance_reservation_chain, expected_layout, output_poison, validate_coordination_hardware,
    validate_coordination_records, validate_hardware_identity, validate_reservation,
    validate_results, validate_results_statistics, validate_run_metadata, validate_sample_contract,
    validate_transport_contract,
};
use crate::archive::{
    ArchiveSnapshot, FileRecord, StrictExternalFile, StrictResultFile, StrictResultSnapshot,
    TypedTransportPolicy, is_lower_hex, open_strict_external_file, open_strict_typed_result,
    open_verified_file_exact, read_verified_small_exact, sha256_bytes,
    verify_transport_archive_again_exact, verify_typed_transport_archive,
};
use crate::model::{
    OracleRequest, ReservationReceipt, ResultsEnvelope, RunMetadata, TransportContract,
    parse_canonical_json, parse_strict_json,
};
use anyhow::{Context, Result, bail, ensure};
use hashsigs_reference::{
    FUSED_OUTPUT_BYTES, HashSigsSha256GenericV1, MessageDigest, PrivateSeed, SIGNATURE_BYTES,
    Sha256GenericWots,
};
use serde::{Deserialize, Serialize};
use sha2::{Digest as _, Sha256};
use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::path::{Component, Path, PathBuf};

const RECEIPT_KIND: &str = "hashsigs_phase_b_rust_oracle_receipt";
const COMPLETED_RESULT_KIND: &str = "completed_comparison";
const MAXIMUM_CREATION_RECEIPT_BYTES: usize = 64 * 1024;
const MAXIMUM_RESULT_REQUESTS: usize = 8_192;
const MAXIMUM_RESULT_JOBS: u64 = 1_048_576;
const MAXIMUM_JOB_TRANSCRIPT_BYTES: u64 = 512 * 1024 * 1024;
const JOB_READ_BUFFER_BYTES: usize = 64 * 1024;
const MAXIMUM_JOB_LINE_BYTES: usize = 4 * 1024;
const MINIMUM_JOB_LINE_BYTES: u64 = 256;
const INPUT_BYTES_PER_JOB: u64 = 64;
const OUTPUT_SLOT_BYTES: u64 = 4_096;
const OUTPUT_VALID_BYTES: u64 = 2_208;
const OUTPUT_VALID_BYTES_USIZE: usize = 2_208;
const OUTPUT_SLOT_BYTES_USIZE: usize = 4_096;
const OUTPUT_PADDING_BYTES: u64 = 1_888;
const EXPECTED_PRODUCER: &str = "independent Rust Sha256GenericWots oracle";
const EXPECTED_PINNED_COMMIT: &str = "2d315dd4168804b7cbc51c51a1bf7ca27bf74140";
const TYPED_TRANSPORT_ROOT_BUDGET: u64 = 128 * 1024 * 1024;
const TYPED_TRANSPORT_SAMPLE_METADATA_BUDGET: u64 = 512 * 1024;
const TYPED_TRANSPORT_SAMPLE_JSON_BYTES: u64 = 1024 * 1024;
const MAXIMUM_TYPED_PERFORMANCE_SAMPLES: usize = 1_000_000;

#[derive(Debug, Eq, PartialEq)]
struct VerifiedMarker;

/// Descriptor-retained capture of the exact oracle creation receipt.
///
/// The capture is created only by [`open_verified_oracle_receipt_capture`]. It
/// retains the absolute parent, basename, file descriptor, exact byte count,
/// and SHA-256 so final result revalidation cannot silently substitute a
/// caller-owned byte slice.
///
/// It cannot be constructed externally:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedOracleReceiptCapture;
/// let _forged = VerifiedOracleReceiptCapture {};
/// ```
///
/// It is deliberately non-`Clone` and non-deserializable:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedOracleReceiptCapture;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedOracleReceiptCapture>();
/// ```
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedOracleReceiptCapture;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedOracleReceiptCapture>();
/// ```
#[derive(Debug)]
pub struct VerifiedOracleReceiptCapture {
    retained: StrictExternalFile,
    exact_bytes: Vec<u8>,
    _marker: VerifiedMarker,
}

impl VerifiedOracleReceiptCapture {
    /// Exact canonical absolute capture path.
    #[must_use]
    pub fn path(&self) -> &Path {
        self.retained.path()
    }

    /// Exact receipt byte count, including the terminal newline.
    #[must_use]
    pub fn byte_count(&self) -> u64 {
        self.retained.record().bytes
    }

    /// SHA-256 of the exact receipt bytes, including the terminal newline.
    #[must_use]
    pub fn sha256(&self) -> &str {
        &self.retained.record().sha256
    }

    /// Revalidates the retained receipt descriptor and its absolute pathname.
    ///
    /// # Errors
    ///
    /// Returns an error if the parent, path, metadata, byte count, or content
    /// digest changed since capture.
    pub fn revalidate(&self) -> Result<()> {
        self.retained.revalidate()
    }

    fn exact_bytes(&self) -> &[u8] {
        &self.exact_bytes
    }
}

/// One immutable file or manifest binding recovered from the sealed result.
///
/// The private marker and fields prevent external construction. In particular,
/// this external doctest must not compile:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedResultArtifactBinding;
/// let _forged = VerifiedResultArtifactBinding {
///     file: "SHA256SUMS".to_owned(),
///     bytes: 1,
///     sha256: "00".repeat(32),
/// };
/// ```
///
/// This proof fragment is not deserializable:
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedResultArtifactBinding;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedResultArtifactBinding>();
/// ```
///
/// It is also deliberately non-`Clone`:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedResultArtifactBinding;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedResultArtifactBinding>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedResultArtifactBinding {
    file: String,
    bytes: u64,
    sha256: String,
    _marker: VerifiedMarker,
}

impl VerifiedResultArtifactBinding {
    /// Exact producer-owned filename.
    #[must_use]
    pub fn file(&self) -> &str {
        &self.file
    }

    /// Exact byte count.
    #[must_use]
    pub fn bytes(&self) -> u64 {
        self.bytes
    }

    /// Lowercase SHA-256 digest.
    #[must_use]
    pub fn sha256(&self) -> &str {
        &self.sha256
    }
}

/// One input or output artifact retained for a verified request.
///
/// This type has no public constructor:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedRequestArtifactBinding;
/// let _forged = VerifiedRequestArtifactBinding {
///     file: "input.bin".to_owned(),
///     logical_bytes: 64,
///     stored_bytes: 64,
///     sha256: "00".repeat(32),
/// };
/// ```
///
/// It is not deserializable:
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedRequestArtifactBinding;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedRequestArtifactBinding>();
/// ```
///
/// It is not cloneable:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedRequestArtifactBinding;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedRequestArtifactBinding>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedRequestArtifactBinding {
    file: String,
    logical_bytes: u64,
    stored_bytes: u64,
    sha256: String,
    _marker: VerifiedMarker,
}

impl VerifiedRequestArtifactBinding {
    /// Request-local artifact filename.
    #[must_use]
    pub fn file(&self) -> &str {
        &self.file
    }

    /// Logical byte count authenticated by the original request.
    #[must_use]
    pub fn logical_bytes(&self) -> u64 {
        self.logical_bytes
    }

    /// Stored byte count authenticated by the original request.
    #[must_use]
    pub fn stored_bytes(&self) -> u64 {
        self.stored_bytes
    }

    /// Lowercase artifact SHA-256 digest.
    #[must_use]
    pub fn sha256(&self) -> &str {
        &self.sha256
    }
}

/// The routed hardware image binding recovered from one oracle request.
///
/// This external construction must not compile:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedXclbinBinding;
/// let _forged = VerifiedXclbinBinding {
///     path: "forged.xclbin".to_owned(),
///     bytes: 1,
///     sha256: "00".repeat(32),
/// };
/// ```
///
/// It is not deserializable:
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedXclbinBinding;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedXclbinBinding>();
/// ```
///
/// It is not cloneable:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedXclbinBinding;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedXclbinBinding>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedXclbinBinding {
    path: String,
    bytes: u64,
    sha256: String,
    _marker: VerifiedMarker,
}

impl VerifiedXclbinBinding {
    /// Exact absolute path captured by the transport producer.
    #[must_use]
    pub fn path(&self) -> &str {
        &self.path
    }

    /// Exact xclbin byte count.
    #[must_use]
    pub fn bytes(&self) -> u64 {
        self.bytes
    }

    /// Lowercase xclbin SHA-256 digest.
    #[must_use]
    pub fn sha256(&self) -> &str {
        &self.sha256
    }
}

/// Exact XRT build identity recovered from the retained native-XRT reports.
///
/// The fields are private, the type has no public constructor, and it is
/// deliberately neither cloneable nor deserializable.
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedXrtBuildIdentity {
    version: String,
    branch: String,
    hash: String,
    build_date: String,
    _marker: VerifiedMarker,
}

impl VerifiedXrtBuildIdentity {
    /// Exact XRT version string.
    #[must_use]
    pub fn version(&self) -> &str {
        &self.version
    }

    /// Exact XRT branch string.
    #[must_use]
    pub fn branch(&self) -> &str {
        &self.branch
    }

    /// Canonical lowercase XRT build hash.
    #[must_use]
    pub fn hash(&self) -> &str {
        &self.hash
    }

    /// Exact XRT build timestamp.
    #[must_use]
    pub fn build_date(&self) -> &str {
        &self.build_date
    }
}

/// Exact programmed xclbin identity from the continuous pre/post card capture.
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedHardwareXclbinIdentity {
    path: String,
    bytes: u64,
    sha256: String,
    uuid: String,
    interface_uuid: String,
    deployment_platform: String,
    fpga_part: String,
    target: String,
    _marker: VerifiedMarker,
}

impl VerifiedHardwareXclbinIdentity {
    /// Exact absolute xclbin path recorded by the card runner.
    #[must_use]
    pub fn path(&self) -> &str {
        &self.path
    }

    /// Exact xclbin byte count.
    #[must_use]
    pub fn bytes(&self) -> u64 {
        self.bytes
    }

    /// Exact lowercase xclbin SHA-256.
    #[must_use]
    pub fn sha256(&self) -> &str {
        &self.sha256
    }

    /// Exact loaded xclbin UUID.
    #[must_use]
    pub fn uuid(&self) -> &str {
        &self.uuid
    }

    /// Exact shell interface UUID declared by the xclbin.
    #[must_use]
    pub fn interface_uuid(&self) -> &str {
        &self.interface_uuid
    }

    /// Exact deployment-platform/XSA name carried by the xclbin.
    #[must_use]
    pub fn deployment_platform(&self) -> &str {
        &self.deployment_platform
    }

    /// Exact FPGA part carried by the xclbin identity.
    #[must_use]
    pub fn fpga_part(&self) -> &str {
        &self.fpga_part
    }

    /// Exact xclbin target (`hw` for this contract).
    #[must_use]
    pub fn target(&self) -> &str {
        &self.target
    }
}

/// Strict, continuous physical-card identity recovered from the transport.
///
/// A value is created only after re-running the existing pre-load, post-load,
/// and post-run native-XRT continuity checks, including the raw platform and
/// host reports. It is not a route seal and does not prove current card
/// ownership.
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedHardwareCardIdentity;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedHardwareCardIdentity>();
/// ```
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedHardwareCardIdentity;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedHardwareCardIdentity>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedHardwareCardIdentity {
    device_index: u64,
    bdf: String,
    device_name: String,
    xmc_serial_number: String,
    shell_vbnv: String,
    logic_uuid: String,
    interface_uuid: String,
    fpga_part: String,
    xrt_build: VerifiedXrtBuildIdentity,
    xclbin: VerifiedHardwareXclbinIdentity,
    _marker: VerifiedMarker,
}

impl VerifiedHardwareCardIdentity {
    /// Exact XRT device index used by the run.
    #[must_use]
    pub fn device_index(&self) -> u64 {
        self.device_index
    }

    /// Canonical physical `PCIe` BDF.
    #[must_use]
    pub fn bdf(&self) -> &str {
        &self.bdf
    }

    /// Exact XRT device/shell name.
    #[must_use]
    pub fn device_name(&self) -> &str {
        &self.device_name
    }

    /// Exact XMC serial number.
    #[must_use]
    pub fn xmc_serial_number(&self) -> &str {
        &self.xmc_serial_number
    }

    /// Exact U280 shell VBNV.
    #[must_use]
    pub fn shell_vbnv(&self) -> &str {
        &self.shell_vbnv
    }

    /// Exact shell logic UUID.
    #[must_use]
    pub fn logic_uuid(&self) -> &str {
        &self.logic_uuid
    }

    /// Exact shell interface UUID.
    #[must_use]
    pub fn interface_uuid(&self) -> &str {
        &self.interface_uuid
    }

    /// Exact FPGA part reported continuously by the card capture.
    #[must_use]
    pub fn fpga_part(&self) -> &str {
        &self.fpga_part
    }

    /// Strict XRT build identity.
    #[must_use]
    pub fn xrt_build(&self) -> &VerifiedXrtBuildIdentity {
        &self.xrt_build
    }

    /// Strict programmed xclbin identity.
    #[must_use]
    pub fn xclbin(&self) -> &VerifiedHardwareXclbinIdentity {
        &self.xclbin
    }
}

/// Routed-clock evidence binding declared consistently by the transport.
///
/// The evidence file itself is outside the transport archive. A later route
/// join must match this exact path/length/digest to accepted route evidence.
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedRoutedClockEvidenceBinding {
    path: String,
    bytes: u64,
    sha256: String,
    _marker: VerifiedMarker,
}

impl VerifiedRoutedClockEvidenceBinding {
    /// Exact evidence path captured by the card runner.
    #[must_use]
    pub fn path(&self) -> &str {
        &self.path
    }

    /// Exact declared evidence byte count.
    #[must_use]
    pub fn bytes(&self) -> u64 {
        self.bytes
    }

    /// Exact declared evidence SHA-256.
    #[must_use]
    pub fn sha256(&self) -> &str {
        &self.sha256
    }
}

/// Exact clock fields shared by metadata, results, and every request.
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedClockObservation {
    requested_clock_hz_metadata: Option<u64>,
    declared_routed_hz: Option<u64>,
    routed_clock_evidence: Option<VerifiedRoutedClockEvidenceBinding>,
    supports_hardware_rate_claim: bool,
    _marker: VerifiedMarker,
}

impl VerifiedClockObservation {
    /// Requested clock metadata, which never substitutes for route evidence.
    #[must_use]
    pub fn requested_clock_hz_metadata(&self) -> Option<u64> {
        self.requested_clock_hz_metadata
    }

    /// Routed clock declared by the transport, before an accepted route join.
    #[must_use]
    pub fn declared_routed_hz(&self) -> Option<u64> {
        self.declared_routed_hz
    }

    /// Exact declared route-evidence binding, if present.
    #[must_use]
    pub fn routed_clock_evidence(&self) -> Option<&VerifiedRoutedClockEvidenceBinding> {
        self.routed_clock_evidence.as_ref()
    }

    /// Whether the transport consistently declared a hardware-rate claim.
    #[must_use]
    pub fn supports_hardware_rate_claim(&self) -> bool {
        self.supports_hardware_rate_claim
    }
}

/// One independently re-parsed raw timing/summary/diagnostic observation.
///
/// `capture_core_interval_cycles` is the raw numerator spanning `batch - 1`
/// inter-result intervals. `whole_kernel_nanoseconds` is the raw elapsed
/// numerator spanning `batch` results. The final promoter must consume these
/// observations through the enclosing opaque guard, not accept caller-created
/// lookalike samples.
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedPerformanceSample;
/// let _forged = VerifiedPerformanceSample {};
/// ```
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedPerformanceSample;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedPerformanceSample>();
/// ```
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedPerformanceSample;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedPerformanceSample>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedPerformanceSample {
    sample: String,
    phase: String,
    sample_index: usize,
    batch: u32,
    capture_core_interval_cycles: u64,
    memory_retirement_interval_cycles: u64,
    whole_kernel_nanoseconds: u64,
    _marker: VerifiedMarker,
}

impl VerifiedPerformanceSample {
    /// Canonical transport sample path.
    #[must_use]
    pub fn sample(&self) -> &str {
        &self.sample
    }

    /// Launch phase (`warmup` or `measured`).
    #[must_use]
    pub fn phase(&self) -> &str {
        &self.phase
    }

    /// Zero-based sample index within its batch and phase.
    #[must_use]
    pub fn sample_index(&self) -> usize {
        self.sample_index
    }

    /// Exact launch batch.
    #[must_use]
    pub fn batch(&self) -> u32 {
        self.batch
    }

    /// Raw capture/core span in cycles over `batch - 1` intervals.
    #[must_use]
    pub fn capture_core_interval_cycles(&self) -> u64 {
        self.capture_core_interval_cycles
    }

    /// Raw memory-retirement span in cycles over `batch - 1` intervals.
    #[must_use]
    pub fn memory_retirement_interval_cycles(&self) -> u64 {
        self.memory_retirement_interval_cycles
    }

    /// Raw whole-kernel elapsed time in nanoseconds over `batch` results.
    #[must_use]
    pub fn whole_kernel_nanoseconds(&self) -> u64 {
        self.whole_kernel_nanoseconds
    }

    /// Whether this sample belongs to the required p95 population.
    #[must_use]
    pub fn is_required_performance_population(&self) -> bool {
        self.batch == REQUIRED_PERFORMANCE_BATCH && self.phase == "measured"
    }
}

/// Exact integer performance observations derived from retained raw samples.
///
/// The raw p95 numerators and denominators deliberately match the promoter
/// core's `PerformanceAssessment` interface. Every decision is made with
/// cross-multiplied `u128` arithmetic; no floating-point value can pass or fail
/// a threshold here.
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedPerformanceObservations;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedPerformanceObservations>();
/// ```
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedPerformanceObservations;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedPerformanceObservations>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedPerformanceObservations {
    required_batch: u32,
    minimum_measured_samples: usize,
    required_batch_requested: bool,
    observed_measured_samples: usize,
    p95_rank: Option<usize>,
    p95_capture_interval_cycles: Option<u64>,
    capture_results_denominator: u32,
    p95_whole_kernel_nanoseconds: Option<u64>,
    whole_kernel_results_denominator: u32,
    clock: VerifiedClockObservation,
    samples: Vec<VerifiedPerformanceSample>,
    _marker: VerifiedMarker,
}

impl VerifiedPerformanceObservations {
    /// Required performance batch (`16_384`).
    #[must_use]
    pub fn required_batch(&self) -> u32 {
        self.required_batch
    }

    /// Minimum measured population (`30`).
    #[must_use]
    pub fn minimum_measured_samples(&self) -> usize {
        self.minimum_measured_samples
    }

    /// Exact arithmetic normalization clock (`250_000_000 Hz`).
    #[must_use]
    pub fn normalized_clock_hz(&self) -> u64 {
        PERFORMANCE_CLOCK_BOUND_HZ
    }

    /// Exact minimum sustained rate (`500_000 signatures/s`).
    #[must_use]
    pub fn minimum_signatures_per_second(&self) -> u64 {
        MINIMUM_SIGNATURES_PER_SECOND_EXACT
    }

    /// Exact maximum p95 capture/core cost (`500 cycles/result`).
    #[must_use]
    pub fn maximum_capture_cycles_per_result(&self) -> u64 {
        MAXIMUM_P95_CAPTURE_CYCLES_EXACT
    }

    /// Whether the required batch was requested by the retained run.
    #[must_use]
    pub fn required_batch_requested(&self) -> bool {
        self.required_batch_requested
    }

    /// Exact number of measured samples in the required batch.
    #[must_use]
    pub fn observed_measured_samples(&self) -> usize {
        self.observed_measured_samples
    }

    /// Whether the minimum measured population is present.
    #[must_use]
    pub(crate) fn sample_count_requirement_met(&self) -> bool {
        self.observed_measured_samples >= self.minimum_measured_samples
    }

    /// One-based nearest-rank p95 position within the measured population.
    #[must_use]
    pub fn p95_rank(&self) -> Option<usize> {
        self.p95_rank
    }

    /// Raw p95 capture/core numerator in cycles.
    #[must_use]
    pub fn p95_capture_interval_cycles(&self) -> Option<u64> {
        self.p95_capture_interval_cycles
    }

    /// Inter-result denominator for the capture/core numerator.
    #[must_use]
    pub fn capture_results_denominator(&self) -> u32 {
        self.capture_results_denominator
    }

    /// Raw p95 whole-kernel elapsed numerator in nanoseconds.
    #[must_use]
    pub fn p95_whole_kernel_nanoseconds(&self) -> Option<u64> {
        self.p95_whole_kernel_nanoseconds
    }

    /// Result-count denominator for the whole-kernel numerator.
    #[must_use]
    pub fn whole_kernel_results_denominator(&self) -> u32 {
        self.whole_kernel_results_denominator
    }

    /// Exact shared clock observation.
    #[must_use]
    pub fn clock(&self) -> &VerifiedClockObservation {
        &self.clock
    }

    /// Exact `p95 <= 500 cycles/result` decision.
    #[must_use]
    pub(crate) fn capture_cycles_threshold_met(&self) -> bool {
        exact_capture_cycles_threshold_met(self.p95_capture_interval_cycles)
    }

    /// Exact normalized-250-MHz `>= 500_000 signatures/s` decision.
    #[must_use]
    pub(crate) fn normalized_250mhz_rate_threshold_met(&self) -> bool {
        exact_capture_rate_threshold_met(
            PERFORMANCE_CLOCK_BOUND_HZ,
            self.p95_capture_interval_cycles,
        )
    }

    /// Exact declared-routed-clock `>= 500_000 signatures/s` decision.
    #[must_use]
    pub(crate) fn declared_routed_rate_threshold_met(&self) -> bool {
        self.clock.supports_hardware_rate_claim
            && self.clock.routed_clock_evidence.is_some()
            && self.clock.declared_routed_hz.is_some_and(|clock_hz| {
                exact_capture_rate_threshold_met(clock_hz, self.p95_capture_interval_cycles)
            })
    }

    /// Exact whole-kernel-elapsed `>= 500_000 signatures/s` decision.
    #[must_use]
    pub(crate) fn whole_kernel_rate_threshold_met(&self) -> bool {
        exact_whole_kernel_rate_threshold_met(self.p95_whole_kernel_nanoseconds)
    }

    /// Whether the full required population and routed-clock inputs exist.
    #[must_use]
    pub(crate) fn threshold_observations_complete(&self) -> bool {
        self.required_batch_requested
            && self.sample_count_requirement_met()
            && self.p95_capture_interval_cycles.is_some()
            && self.p95_whole_kernel_nanoseconds.is_some()
            && self.clock.declared_routed_hz.is_some()
            && self.clock.routed_clock_evidence.is_some()
            && self.clock.supports_hardware_rate_claim
    }

    /// Pre-route-join conjunction of the complete population and exact costs.
    ///
    /// This decision is deliberately non-promotable: the routed-clock evidence
    /// binding is declared by the transport but its external bytes have not yet
    /// been joined to an accepted route seal. The final promoter must repeat
    /// these exact comparisons while performing that join.
    #[must_use]
    pub(crate) fn pre_route_join_performance_thresholds_met(&self) -> bool {
        self.threshold_observations_complete()
            && self.capture_cycles_threshold_met()
            && self.normalized_250mhz_rate_threshold_met()
            && self.declared_routed_rate_threshold_met()
            && self.whole_kernel_rate_threshold_met()
    }

    /// Every independently parsed sample, including warmups and controls.
    #[must_use]
    pub fn samples(&self) -> &[VerifiedPerformanceSample] {
        &self.samples
    }
}

/// Semantically revalidated fields for one complete oracle request.
///
/// Its private fields and seal prevent external struct construction:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedResultRequest;
/// let _forged = VerifiedResultRequest {};
/// ```
///
/// This type is deliberately not deserializable by callers:
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedResultRequest;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedResultRequest>();
/// ```
///
/// It is also deliberately non-`Clone`:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedResultRequest;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedResultRequest>();
/// ```
#[derive(Debug, Eq, PartialEq)]
pub struct VerifiedResultRequest {
    sample: String,
    phase: String,
    sample_index: usize,
    request_sha256: String,
    run_id: String,
    coordination_intent: VerifiedResultArtifactBinding,
    coordination_burn: VerifiedResultArtifactBinding,
    coordination_receipt: VerifiedResultArtifactBinding,
    batch: u32,
    nonce_hex: String,
    reservation_record_sha256: String,
    xclbin: VerifiedXclbinBinding,
    hardware_identity_pre_run: VerifiedResultArtifactBinding,
    input: VerifiedRequestArtifactBinding,
    output: VerifiedRequestArtifactBinding,
    jobs: u32,
    matched_jobs: u32,
    mismatched_jobs: u32,
    padding_valid: bool,
    cryptographic_oracle_valid: bool,
    _marker: VerifiedMarker,
}

impl VerifiedResultRequest {
    /// Canonical sample path inside the retained transport archive.
    #[must_use]
    pub fn sample(&self) -> &str {
        &self.sample
    }

    /// Launch phase (`warmup` or `measured`).
    #[must_use]
    pub fn phase(&self) -> &str {
        &self.phase
    }

    /// Zero-based sample index within the batch and phase.
    #[must_use]
    pub fn sample_index(&self) -> usize {
        self.sample_index
    }

    /// SHA-256 of the request's exact `oracle-request.json` bytes.
    #[must_use]
    pub fn request_sha256(&self) -> &str {
        &self.request_sha256
    }

    /// Coordination run identifier checked against the result-wide run.
    #[must_use]
    pub fn run_id(&self) -> &str {
        &self.run_id
    }

    /// Request-local intent binding checked against the result-wide root.
    #[must_use]
    pub fn coordination_intent(&self) -> &VerifiedResultArtifactBinding {
        &self.coordination_intent
    }

    /// Request-local authorization-burn binding.
    #[must_use]
    pub fn coordination_burn(&self) -> &VerifiedResultArtifactBinding {
        &self.coordination_burn
    }

    /// Request-local post-lock coordination receipt binding.
    #[must_use]
    pub fn coordination_receipt(&self) -> &VerifiedResultArtifactBinding {
        &self.coordination_receipt
    }

    /// Requested jobs in this launch.
    #[must_use]
    pub fn batch(&self) -> u32 {
        self.batch
    }

    /// Canonical request nonce.
    #[must_use]
    pub fn nonce_hex(&self) -> &str {
        &self.nonce_hex
    }

    /// Reservation-record SHA-256 bound by the request.
    #[must_use]
    pub fn reservation_record_sha256(&self) -> &str {
        &self.reservation_record_sha256
    }

    /// Exact hardware xclbin binding.
    #[must_use]
    pub fn xclbin(&self) -> &VerifiedXclbinBinding {
        &self.xclbin
    }

    /// Exact pre-run native-XRT identity binding.
    #[must_use]
    pub fn hardware_identity_pre_run(&self) -> &VerifiedResultArtifactBinding {
        &self.hardware_identity_pre_run
    }

    /// Request-authenticated input artifact binding.
    #[must_use]
    pub fn input(&self) -> &VerifiedRequestArtifactBinding {
        &self.input
    }

    /// Request-authenticated full output-allocation binding.
    #[must_use]
    pub fn output(&self) -> &VerifiedRequestArtifactBinding {
        &self.output
    }

    /// Complete job count represented by the transcript.
    #[must_use]
    pub fn jobs(&self) -> u32 {
        self.jobs
    }

    /// Transcript jobs whose expected and observed digests match.
    #[must_use]
    pub fn matched_jobs(&self) -> u32 {
        self.matched_jobs
    }

    /// Transcript jobs whose expected and observed digests differ.
    #[must_use]
    pub fn mismatched_jobs(&self) -> u32 {
        self.mismatched_jobs
    }

    /// Whether every reserved output byte retained its required poison value.
    #[must_use]
    pub fn padding_valid(&self) -> bool {
        self.padding_valid
    }

    /// Recomputed conjunction of complete payload and padding validity.
    #[must_use]
    pub fn cryptographic_oracle_valid(&self) -> bool {
        self.cryptographic_oracle_valid
    }
}

/// Opaque, descriptor-retaining view of a receipt-bound Phase-B oracle result.
///
/// It cannot be constructed or deserialized externally, and it intentionally
/// does not implement `Clone`:
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedSealedResult;
/// let _forged = VerifiedSealedResult {};
/// ```
///
/// ```compile_fail
/// use serde::de::DeserializeOwned;
/// use u280_evidence_oracle::VerifiedSealedResult;
/// fn require_deserialize<T: DeserializeOwned>() {}
/// require_deserialize::<VerifiedSealedResult>();
/// ```
///
/// ```compile_fail
/// use u280_evidence_oracle::VerifiedSealedResult;
/// fn require_clone<T: Clone>() {}
/// require_clone::<VerifiedSealedResult>();
/// ```
///
/// The returned values describe historical evidence. Keep this guard alive and
/// call [`Self::revalidate`] immediately before the promoter publishes its own
/// sealed result. That call uses the same retained result and transport root
/// descriptors; path-only snapshots are not substituted.
#[derive(Debug)]
pub struct VerifiedSealedResult {
    transport_manifest: VerifiedResultArtifactBinding,
    final_hardware_identity: VerifiedResultArtifactBinding,
    hardware_card_identity: VerifiedHardwareCardIdentity,
    performance: VerifiedPerformanceObservations,
    run_id: String,
    coordination_intent: VerifiedResultArtifactBinding,
    coordination_burn: VerifiedResultArtifactBinding,
    coordination_receipt: VerifiedResultArtifactBinding,
    samples: usize,
    jobs: u64,
    matched_jobs: u64,
    mismatched_jobs: u64,
    all_padding_valid: bool,
    cryptographic_oracle_valid: bool,
    requests: Vec<VerifiedResultRequest>,
    result_directory: PathBuf,
    result_manifest: VerifiedResultArtifactBinding,
    creation_receipt: VerifiedOracleReceiptCapture,
    result_snapshot: StrictResultSnapshot,
    transport_snapshot: ArchiveSnapshot,
    _marker: VerifiedMarker,
}

impl VerifiedSealedResult {
    /// Fixed cryptographic profile accepted by this typed verifier.
    #[must_use]
    pub fn profile(&self) -> &'static str {
        PROFILE
    }

    /// Canonical retained transport root.
    #[must_use]
    pub fn transport_root(&self) -> &Path {
        &self.transport_snapshot.root
    }

    /// Exact transport `SHA256SUMS` binding validated by the original oracle.
    #[must_use]
    pub fn transport_manifest(&self) -> &VerifiedResultArtifactBinding {
        &self.transport_manifest
    }

    /// Exact final native-XRT hardware identity binding.
    #[must_use]
    pub fn final_hardware_identity(&self) -> &VerifiedResultArtifactBinding {
        &self.final_hardware_identity
    }

    /// Strict card and programmed-image identity proof.
    #[must_use]
    pub fn hardware_card_identity(&self) -> &VerifiedHardwareCardIdentity {
        &self.hardware_card_identity
    }

    /// Independently parsed exact performance observations.
    #[must_use]
    pub fn performance(&self) -> &VerifiedPerformanceObservations {
        &self.performance
    }

    /// Final hardware promotion remains the later route/card combiner's job.
    #[must_use]
    pub fn hardware_completion_promotable(&self) -> bool {
        false
    }

    /// Coordination run identifier shared by every request.
    #[must_use]
    pub fn run_id(&self) -> &str {
        &self.run_id
    }

    /// Result-wide coordination intent root.
    #[must_use]
    pub fn coordination_intent(&self) -> &VerifiedResultArtifactBinding {
        &self.coordination_intent
    }

    /// Result-wide durable authorization-burn root.
    #[must_use]
    pub fn coordination_burn(&self) -> &VerifiedResultArtifactBinding {
        &self.coordination_burn
    }

    /// Result-wide post-lock coordination receipt root.
    #[must_use]
    pub fn coordination_receipt(&self) -> &VerifiedResultArtifactBinding {
        &self.coordination_receipt
    }

    /// Number of complete request samples.
    #[must_use]
    pub fn samples(&self) -> usize {
        self.samples
    }

    /// Number of transcript jobs across all samples.
    #[must_use]
    pub fn jobs(&self) -> u64 {
        self.jobs
    }

    /// Number of matching transcript jobs.
    #[must_use]
    pub fn matched_jobs(&self) -> u64 {
        self.matched_jobs
    }

    /// Number of mismatching transcript jobs.
    #[must_use]
    pub fn mismatched_jobs(&self) -> u64 {
        self.mismatched_jobs
    }

    /// Conjunction of every request's padding decision.
    #[must_use]
    pub fn all_padding_valid(&self) -> bool {
        self.all_padding_valid
    }

    /// Recomputed complete cryptographic decision.
    #[must_use]
    pub fn cryptographic_oracle_valid(&self) -> bool {
        self.cryptographic_oracle_valid
    }

    /// Revalidated request-level joins and decisions.
    #[must_use]
    pub fn requests(&self) -> &[VerifiedResultRequest] {
        &self.requests
    }

    /// Canonical result directory bound by the exact creation receipt.
    #[must_use]
    pub fn result_directory(&self) -> &Path {
        &self.result_directory
    }

    /// Result directory's exact `SHA256SUMS` creation-time binding.
    #[must_use]
    pub fn result_manifest(&self) -> &VerifiedResultArtifactBinding {
        &self.result_manifest
    }

    /// Descriptor-retained exact creation receipt.
    #[must_use]
    pub fn creation_receipt(&self) -> &VerifiedOracleReceiptCapture {
        &self.creation_receipt
    }

    /// Revalidates the complete result and transport through their originally
    /// retained roots.
    ///
    /// # Errors
    ///
    /// Returns an error if either absolute root path identity, tree, manifest,
    /// or any covered file changed since this guard was created.
    ///
    /// No filesystem API can prevent the owner from changing a path after
    /// this method returns. A promoter must therefore publish the receipt and
    /// both manifest identities, not claim that either path remains immutable.
    pub fn revalidate(&self) -> Result<()> {
        self.creation_receipt.revalidate()?;
        self.result_snapshot.revalidate()?;
        verify_transport_archive_again_exact(&self.transport_snapshot)?;
        self.creation_receipt.revalidate()?;
        Ok(())
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
struct SealedBinding {
    file: String,
    bytes: u64,
    sha256: String,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
struct SealedRequestArtifactBinding {
    file: String,
    logical_bytes: u64,
    stored_bytes: u64,
    sha256: String,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
struct SealedXclbinBinding {
    path: String,
    bytes: u64,
    sha256: String,
}

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct SealedRequest {
    sample: String,
    phase: String,
    sample_index: usize,
    request_sha256: String,
    run_id: String,
    coordination_intent: SealedBinding,
    coordination_burn: SealedBinding,
    coordination_receipt: SealedBinding,
    batch: u32,
    nonce_hex: String,
    reservation_record_sha256: String,
    xclbin: SealedXclbinBinding,
    hardware_identity_pre_run: SealedBinding,
    input: SealedRequestArtifactBinding,
    output: SealedRequestArtifactBinding,
    jobs: u32,
    matched_jobs: u32,
    padding_valid: bool,
    cryptographic_oracle_valid: bool,
}

// These booleans are distinct fields in the sealed canonical JSON contract;
// replacing them with enums would change its wire representation.
#[allow(clippy::struct_excessive_bools)]
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct SealedSummary {
    schema: u64,
    kind: String,
    verifier_contract: String,
    profile: String,
    producer: String,
    pinned_hashsigs_rs_commit: String,
    transport_manifest: SealedBinding,
    run_id: String,
    coordination_intent: SealedBinding,
    coordination_burn: SealedBinding,
    coordination_receipt: SealedBinding,
    final_hardware_identity: SealedBinding,
    worker_threads: usize,
    sample_count: usize,
    total_jobs: u64,
    matched_jobs: u64,
    mismatched_jobs: u64,
    all_padding_valid: bool,
    requests: Vec<SealedRequest>,
    cryptographic_oracle_valid: bool,
    card_identity_promotable: bool,
    performance_promotable: bool,
    hardware_completion_promotable: bool,
    evidence_boundary: String,
}

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct SealedJob {
    schema: u64,
    sample: String,
    job_index: u32,
    input_sha256: String,
    expected_sha256: String,
    observed_sha256: String,
    r#match: bool,
}

// These booleans are distinct fields in the canonical creation receipt;
// replacing them with enums would break receipt compatibility.
#[allow(clippy::struct_excessive_bools)]
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct CompletedReceipt {
    schema: u64,
    kind: String,
    result_kind: String,
    result_schema: u64,
    typed_verifier_contract: String,
    result_directory: String,
    manifest: SealedBinding,
    structural_validation_valid: bool,
    cryptographic_oracle_valid: bool,
    card_identity_promotable: bool,
    performance_promotable: bool,
    hardware_completion_promotable: bool,
    samples: usize,
    jobs: u64,
}

#[derive(Clone, Copy, Debug)]
struct TranscriptCount {
    jobs: u32,
    matched_jobs: u32,
    padding_valid: bool,
}

struct VerifiedValues {
    transport_manifest: VerifiedResultArtifactBinding,
    final_hardware_identity: VerifiedResultArtifactBinding,
    run_id: String,
    coordination_intent: VerifiedResultArtifactBinding,
    coordination_burn: VerifiedResultArtifactBinding,
    coordination_receipt: VerifiedResultArtifactBinding,
    samples: usize,
    jobs: u64,
    matched_jobs: u64,
    mismatched_jobs: u64,
    all_padding_valid: bool,
    cryptographic_oracle_valid: bool,
    requests: Vec<VerifiedResultRequest>,
}

struct VerifiedTransportEvidence {
    hardware_card_identity: VerifiedHardwareCardIdentity,
    performance: VerifiedPerformanceObservations,
}

#[derive(Debug, Eq, PartialEq)]
struct ExactPerformanceDecision {
    required_batch_requested: bool,
    observed_measured_samples: usize,
    p95_rank: Option<usize>,
    p95_capture_interval_cycles: Option<u64>,
    p95_whole_kernel_nanoseconds: Option<u64>,
}

/// Serializes the exact canonical schema-2 creation-receipt line.
///
/// The returned string excludes the terminal newline; the CLI adds exactly one
/// newline when it writes the line to stdout. Callers that retain the receipt
/// as bytes must retain that newline as well.
///
/// # Errors
///
/// Returns an error if the canonical result path is not UTF-8 or the outcome's
/// manifest binding is noncanonical.
pub fn completed_result_receipt_line(outcome: &OracleOutcome) -> Result<String> {
    let result_directory = outcome
        .result_directory
        .to_str()
        .context("result directory is not valid UTF-8")?;
    ensure!(
        is_nonzero_lower_hex(&outcome.result_manifest_sha256, 64)
            && outcome.result_manifest_bytes > 0,
        "result manifest binding is not canonical"
    );
    let receipt = CompletedReceipt {
        schema: PHASE_B_ORACLE_RECEIPT_SCHEMA,
        kind: RECEIPT_KIND.to_owned(),
        result_kind: COMPLETED_RESULT_KIND.to_owned(),
        result_schema: PHASE_B_TYPED_RESULT_SCHEMA,
        typed_verifier_contract: PHASE_B_TYPED_RESULT_CONTRACT.to_owned(),
        result_directory: result_directory.to_owned(),
        manifest: SealedBinding {
            file: "SHA256SUMS".to_owned(),
            bytes: outcome.result_manifest_bytes,
            sha256: outcome.result_manifest_sha256.clone(),
        },
        structural_validation_valid: true,
        cryptographic_oracle_valid: outcome.cryptographic_oracle_valid,
        card_identity_promotable: false,
        performance_promotable: false,
        hardware_completion_promotable: false,
        samples: outcome.samples,
        jobs: outcome.jobs,
    };
    serde_json::to_string(&receipt).context("cannot serialize strict result receipt")
}

/// Securely opens and validates one exact schema-2 creation-receipt capture.
///
/// The file must be a bounded, nonempty, singly linked regular file beneath an
/// absolute symlink-free parent path. Its canonical bytes are parsed before the
/// descriptor-backed capture is returned.
///
/// # Errors
///
/// Returns an error for an insecure path or file type, a malformed receipt, an
/// unsupported receipt contract, or any open/read/revalidation race.
pub fn open_verified_oracle_receipt_capture(path: &Path) -> Result<VerifiedOracleReceiptCapture> {
    let maximum_bytes = u64::try_from(MAXIMUM_CREATION_RECEIPT_BYTES)
        .context("creation-receipt bound exceeds u64")?;
    let (retained, exact_bytes) =
        open_strict_external_file(path, maximum_bytes, "oracle creation receipt")?;
    let receipt: CompletedReceipt = parse_canonical_json(&exact_bytes, "creation receipt")?;
    validate_receipt_header(&receipt)?;
    ensure!(
        canonical_absolute_path(Path::new(&receipt.result_directory)),
        "creation receipt result path is not absolute and canonical"
    );
    let capture = VerifiedOracleReceiptCapture {
        retained,
        exact_bytes,
        _marker: VerifiedMarker,
    };
    capture.revalidate()?;
    Ok(capture)
}

/// Revalidates a completed Phase-B result from its descriptor-retained receipt.
///
/// The receipt must be the exact canonical schema-2 line emitted by the oracle,
/// including its sole trailing newline. This API takes no caller-supplied result
/// path, manifest digest, summary JSON, or decision. It reads those bindings
/// from the receipt and descriptor-rooted sealed directory. The separate
/// `transport_root` argument names the original producer archive whose exact
/// manifest is bound by the result.
///
/// # Evidence boundary
///
/// A successful return binds the descriptor-retained receipt capture, joins
/// the result to the retained transport manifest, re-runs the strict native-XRT
/// card-identity chain, derives sample order from that transport, independently
/// parses every timing/summary/diagnostic record, and recomputes every job
/// digest and padding byte. Required-batch p95 performance is exposed only as
/// exact integer observations; its pre-route threshold assessment stays
/// internal.
/// The receipt is an external creation-time anchor, not a signature: its
/// custodian must preserve its descriptor-backed path and exact bytes. This
/// API does not join an accepted route seal, authenticate the external
/// routed-clock evidence file, prove
/// current card ownership, establish ledger honesty or journal nonrollback, or
/// prevent cross-archive replay. The final promoter must still keep a durable
/// global seen-set and combine the separate accepted-route evidence.
///
/// The returned guard describes historical evidence until
/// [`VerifiedSealedResult::revalidate`] succeeds immediately before promoter
/// publication.
///
/// The receipt capture is consumed and cannot be replayed into a second guard:
///
/// ```compile_fail
/// use std::path::Path;
/// use u280_evidence_oracle::{
///     VerifiedOracleReceiptCapture, verify_typed_sealed_result,
/// };
/// fn cannot_reuse(capture: VerifiedOracleReceiptCapture, transport: &Path) {
///     let _first = verify_typed_sealed_result(capture, transport);
///     let _second = verify_typed_sealed_result(capture, transport);
/// }
/// ```
///
/// # Errors
///
/// Returns an error for a noncanonical or mismatched receipt, any filesystem or
/// manifest mismatch in either archive, a noncanonical/extended result record,
/// an unbounded or incomplete transcript, an original-request/artifact/job
/// splice, inconsistent decisions, or a premature promotion flag.
pub fn verify_typed_sealed_result(
    creation_receipt: VerifiedOracleReceiptCapture,
    transport_root: &Path,
) -> Result<VerifiedSealedResult> {
    creation_receipt.revalidate()?;
    let receipt: CompletedReceipt = {
        let exact_bytes = creation_receipt.exact_bytes();
        ensure!(
            exact_bytes.len() <= MAXIMUM_CREATION_RECEIPT_BYTES,
            "creation receipt exceeds its strict size limit"
        );
        parse_canonical_json(exact_bytes, "creation receipt")?
    };
    validate_receipt_header(&receipt)?;

    let requested_root = Path::new(&receipt.result_directory);
    ensure!(
        canonical_absolute_path(requested_root),
        "creation receipt result path is not absolute and canonical"
    );
    let header = open_strict_typed_result(requested_root)?;
    ensure!(
        header.root() == requested_root,
        "creation receipt result path is not the canonical descriptor-rooted path"
    );
    let receipt_manifest = FileRecord {
        bytes: receipt.manifest.bytes,
        sha256: receipt.manifest.sha256.clone(),
    };
    ensure!(
        header.manifest() == &receipt_manifest,
        "result manifest differs from the exact creation receipt"
    );

    let summary_bytes = header.read_summary()?;
    let summary: SealedSummary = parse_canonical_json(&summary_bytes, "summary.json")?;
    let expected_jobs = validate_summary_header(&summary)?;
    let transcript_maximum = validate_transcript_size(header.jobs_bytes(), expected_jobs)?;
    let result_snapshot = header.verify_jobs(transcript_maximum)?;

    let transport_policy = typed_transport_policy(&summary, expected_jobs)?;
    let transport_snapshot = verify_typed_transport_archive(transport_root, transport_policy)?;
    validate_transport_manifest_and_roots(&transport_snapshot, &summary)?;
    let transport_evidence =
        validate_typed_hardware_and_performance(&transport_snapshot, &summary)?;
    let transcript_counts =
        validate_transport_join(&result_snapshot, &transport_snapshot, &summary)?;
    let values = validate_summary_decisions(summary, &transcript_counts)?;
    validate_receipt_result_join(&receipt, &values)?;

    creation_receipt.revalidate()?;
    result_snapshot.revalidate()?;
    verify_transport_archive_again_exact(&transport_snapshot)?;
    creation_receipt.revalidate()?;
    let result_directory = result_snapshot.root.clone();
    Ok(VerifiedSealedResult {
        transport_manifest: values.transport_manifest,
        final_hardware_identity: values.final_hardware_identity,
        hardware_card_identity: transport_evidence.hardware_card_identity,
        performance: transport_evidence.performance,
        run_id: values.run_id,
        coordination_intent: values.coordination_intent,
        coordination_burn: values.coordination_burn,
        coordination_receipt: values.coordination_receipt,
        samples: values.samples,
        jobs: values.jobs,
        matched_jobs: values.matched_jobs,
        mismatched_jobs: values.mismatched_jobs,
        all_padding_valid: values.all_padding_valid,
        cryptographic_oracle_valid: values.cryptographic_oracle_valid,
        requests: values.requests,
        result_directory,
        result_manifest: verified_binding(&receipt.manifest),
        creation_receipt,
        result_snapshot,
        transport_snapshot,
        _marker: VerifiedMarker,
    })
}

fn validate_receipt_header(receipt: &CompletedReceipt) -> Result<()> {
    ensure!(
        receipt.schema == PHASE_B_ORACLE_RECEIPT_SCHEMA,
        "creation receipt schema must be {PHASE_B_ORACLE_RECEIPT_SCHEMA}"
    );
    ensure!(
        receipt.kind == RECEIPT_KIND,
        "creation receipt kind changed"
    );
    ensure!(
        receipt.result_kind == COMPLETED_RESULT_KIND,
        "creation receipt is not a completed comparison"
    );
    ensure!(
        receipt.result_schema == PHASE_B_TYPED_RESULT_SCHEMA,
        "creation receipt result schema must be {PHASE_B_TYPED_RESULT_SCHEMA}"
    );
    ensure!(
        receipt.typed_verifier_contract == PHASE_B_TYPED_RESULT_CONTRACT,
        "creation receipt typed-verifier contract changed"
    );
    validate_binding(&receipt.manifest, "SHA256SUMS", "creation receipt manifest")?;
    ensure!(
        receipt.structural_validation_valid,
        "creation receipt structural decision is false"
    );
    ensure!(
        !receipt.card_identity_promotable
            && !receipt.performance_promotable
            && !receipt.hardware_completion_promotable,
        "creation receipt makes a premature promotion claim"
    );
    ensure!(
        receipt.samples > 0 && receipt.samples <= MAXIMUM_RESULT_REQUESTS,
        "creation receipt sample count exceeds the verifier policy"
    );
    ensure!(
        receipt.jobs <= MAXIMUM_RESULT_JOBS,
        "creation receipt job count exceeds the verifier policy"
    );
    Ok(())
}

fn validate_summary_header(summary: &SealedSummary) -> Result<u64> {
    ensure!(
        summary.schema == PHASE_B_TYPED_RESULT_SCHEMA,
        "typed result schema must be {PHASE_B_TYPED_RESULT_SCHEMA}"
    );
    ensure!(summary.kind == RESULT_KIND, "typed result kind changed");
    ensure!(
        summary.verifier_contract == PHASE_B_TYPED_RESULT_CONTRACT,
        "typed result verifier contract changed"
    );
    ensure!(summary.profile == PROFILE, "typed result profile changed");
    ensure!(
        summary.producer == EXPECTED_PRODUCER,
        "typed result producer changed"
    );
    ensure!(
        summary.pinned_hashsigs_rs_commit == EXPECTED_PINNED_COMMIT,
        "typed result HashSigsRS pin changed"
    );
    validate_binding(
        &summary.transport_manifest,
        "SHA256SUMS",
        "transport manifest",
    )?;
    validate_binding(
        &summary.coordination_intent,
        "coordination-intent.json",
        "coordination intent",
    )?;
    validate_binding(
        &summary.coordination_burn,
        "coordination-burn.json",
        "coordination burn",
    )?;
    validate_binding(
        &summary.coordination_receipt,
        "coordination-receipt.json",
        "coordination receipt",
    )?;
    validate_binding(
        &summary.final_hardware_identity,
        "hardware-identity.json",
        "final hardware identity",
    )?;
    ensure!(
        is_nonzero_lower_hex(&summary.run_id, 32),
        "typed result run id is not canonical"
    );
    ensure!(
        (1..=256).contains(&summary.worker_threads),
        "typed result worker count is invalid"
    );
    ensure!(
        summary.sample_count > 0
            && summary.sample_count <= MAXIMUM_RESULT_REQUESTS
            && summary.sample_count == summary.requests.len(),
        "typed result sample count differs from its bounded complete request set"
    );
    ensure!(
        !summary.card_identity_promotable
            && !summary.performance_promotable
            && !summary.hardware_completion_promotable,
        "typed result makes a premature promotion claim"
    );
    ensure!(
        summary.evidence_boundary == RESULT_EVIDENCE_BOUNDARY,
        "typed result evidence boundary changed"
    );

    let mut expected_jobs = 0_u64;
    let mut seen_samples = HashSet::new();
    let mut seen_requests = HashSet::new();
    let mut seen_nonces = HashSet::new();
    let mut seen_reservations = HashSet::new();
    for request in &summary.requests {
        validate_request_shape(request, summary)?;
        ensure!(
            seen_samples.insert(request.sample.as_str()),
            "typed result repeats a request sample"
        );
        ensure!(
            seen_requests.insert(request.request_sha256.as_str())
                && seen_nonces.insert(request.nonce_hex.as_str())
                && seen_reservations.insert(request.reservation_record_sha256.as_str()),
            "typed result repeats a request, nonce, or reservation"
        );
        ensure!(
            request.jobs == request.batch,
            "request job count differs from its batch"
        );
        expected_jobs = expected_jobs
            .checked_add(u64::from(request.jobs))
            .context("typed result total job count overflow")?;
    }
    ensure!(
        expected_jobs == summary.total_jobs,
        "typed result total jobs differ from its complete request set"
    );
    ensure!(
        expected_jobs <= MAXIMUM_RESULT_JOBS,
        "typed result job count exceeds the verifier policy"
    );
    Ok(expected_jobs)
}

fn validate_transcript_size(bytes: u64, expected_jobs: u64) -> Result<u64> {
    if expected_jobs == 0 {
        ensure!(bytes == 0, "zero-job result has a nonempty transcript");
        return Ok(0);
    }
    let schema_maximum = expected_jobs
        .checked_mul(u64::try_from(MAXIMUM_JOB_LINE_BYTES).expect("line limit fits u64"))
        .context("job transcript schema bound overflow")?;
    let schema_minimum = expected_jobs
        .checked_mul(MINIMUM_JOB_LINE_BYTES)
        .context("job transcript minimum bound overflow")?;
    ensure!(
        bytes >= schema_minimum,
        "job transcript is too small for its schema-derived job count"
    );
    ensure!(
        bytes <= schema_maximum && bytes <= MAXIMUM_JOB_TRANSCRIPT_BYTES,
        "job transcript exceeds its schema-derived or absolute byte policy"
    );
    Ok(schema_maximum.min(MAXIMUM_JOB_TRANSCRIPT_BYTES))
}

fn typed_transport_policy(
    summary: &SealedSummary,
    expected_jobs: u64,
) -> Result<TypedTransportPolicy> {
    ensure!(
        expected_jobs == summary.total_jobs,
        "typed transport policy job count changed"
    );
    let mut files = BTreeMap::new();
    let mut directories = BTreeSet::from(["samples".to_owned()]);
    for (path, maximum) in [
        ("coordination-burn.json", 64 * 1024),
        ("coordination-intent.json", 64 * 1024),
        ("coordination-receipt.json", 64 * 1024),
        ("hardware-identity-pre-run.json", 16 * 1024 * 1024),
        ("hardware-identity.json", 16 * 1024 * 1024),
        ("results.json", 16 * 1024 * 1024),
        ("run-metadata.json", 16 * 1024 * 1024),
        ("xrt-host.json", 64 * 1024),
        ("xrt-platform-post-run.json", 4 * 1024 * 1024),
        ("xrt-platform-pre-load.json", 4 * 1024 * 1024),
    ] {
        files.insert(path.to_owned(), maximum);
    }

    let mut artifact_bytes = 0_u64;
    for request in &summary.requests {
        let (batch_directory, _) = request
            .sample
            .rsplit_once('/')
            .context("typed result sample path has no batch directory")?;
        directories.insert(batch_directory.to_owned());
        directories.insert(request.sample.clone());
        for (file, maximum) in [
            ("diagnostics.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
            ("input.bin", request.input.stored_bytes),
            ("oracle-request.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
            ("oracle-request.sha256", 256),
            ("output.bin", request.output.stored_bytes),
            ("reservation.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
            ("summary-decoded.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
            ("summary.bin", SUMMARY_BYTES),
            ("timing.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
            ("transport.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
            ("validation.json", TYPED_TRANSPORT_SAMPLE_JSON_BYTES),
        ] {
            let path = format!("{}/{file}", request.sample);
            ensure!(
                files.insert(path, maximum).is_none(),
                "typed transport policy repeats a sample file"
            );
        }
        artifact_bytes = artifact_bytes
            .checked_add(request.input.stored_bytes)
            .and_then(|bytes| bytes.checked_add(request.output.stored_bytes))
            .and_then(|bytes| bytes.checked_add(SUMMARY_BYTES))
            .context("typed transport artifact budget overflow")?;
    }
    let metadata_budget = u64::try_from(summary.sample_count)
        .context("typed transport sample count exceeds u64")?
        .checked_mul(TYPED_TRANSPORT_SAMPLE_METADATA_BUDGET)
        .context("typed transport metadata budget overflow")?;
    let maximum_total_bytes = TYPED_TRANSPORT_ROOT_BUDGET
        .checked_add(artifact_bytes)
        .and_then(|bytes| bytes.checked_add(metadata_budget))
        .context("typed transport aggregate policy overflow")?;
    Ok(TypedTransportPolicy {
        files,
        directories,
        maximum_total_bytes,
    })
}

fn validate_transport_manifest_and_roots(
    transport: &ArchiveSnapshot,
    summary: &SealedSummary,
) -> Result<()> {
    ensure!(
        summary.transport_manifest.file == "SHA256SUMS"
            && summary.transport_manifest.bytes == transport.manifest.bytes
            && summary.transport_manifest.sha256 == transport.manifest.sha256,
        "typed result transport manifest differs from the original transport"
    );
    for (binding, path, label) in [
        (
            &summary.coordination_intent,
            "coordination-intent.json",
            "coordination intent",
        ),
        (
            &summary.coordination_burn,
            "coordination-burn.json",
            "coordination burn",
        ),
        (
            &summary.coordination_receipt,
            "coordination-receipt.json",
            "coordination receipt",
        ),
        (
            &summary.final_hardware_identity,
            "hardware-identity.json",
            "final hardware identity",
        ),
    ] {
        let record = transport
            .files
            .get(path)
            .with_context(|| format!("transport manifest omits {path}"))?;
        ensure!(
            binding.file == path
                && binding.bytes == record.bytes
                && binding.sha256 == record.sha256,
            "typed result {label} differs from the original transport"
        );
    }
    Ok(())
}

fn validate_typed_hardware_and_performance(
    transport: &ArchiveSnapshot,
    summary: &SealedSummary,
) -> Result<VerifiedTransportEvidence> {
    // Re-run the original oracle's complete coordination, native-XRT identity,
    // and results-envelope validation over the retained transport descriptors.
    // The typed result summary is not trusted as a substitute for these files.
    let coordination = validate_coordination_records(transport)?;
    let metadata: RunMetadata = parse_typed_transport_json(transport, "run-metadata.json")?;
    validate_run_metadata(&metadata, &coordination)?;
    ensure!(
        metadata.run_id == summary.run_id,
        "strict hardware/performance revalidation crossed coordination runs"
    );
    let hardware = validate_hardware_identity(transport, &metadata)?;
    validate_coordination_hardware(&coordination, &hardware)?;
    let results: ResultsEnvelope = parse_typed_transport_json(transport, "results.json")?;
    validate_results(&results, &metadata, &hardware.final_record, &coordination)?;

    // Parse every launch again through the original strict request, timing,
    // diagnostics, summary, and reservation validators. Only measured samples
    // feed percentile arithmetic, but warmups and controls must also validate.
    // expected_layout fixes every unique batch/phase/index path from metadata,
    // while validate_results fixes each measured count to that same metadata;
    // the population cannot be padded with arbitrary duplicate samples.
    let samples = expected_layout(transport, &metadata)?;
    ensure!(
        samples.len() == summary.requests.len(),
        "strict hardware/performance sample set differs from the typed result"
    );
    let mut validation_state = SampleValidationState {
        metadata: &metadata,
        pre_run_identity_record: &hardware.pre_run_record,
        coordination: &coordination,
        reservation_ids: HashSet::new(),
        nonces: HashSet::new(),
        reservation_chain: None,
    };
    let mut measured_metrics = Vec::new();
    let mut observations = Vec::with_capacity(samples.len());
    for sample in &samples {
        let validated = validate_sample_contract(transport, sample, &mut validation_state)?;
        let metrics = validated.metrics;
        ensure!(
            metrics.batch == sample.batch,
            "strict sample metrics changed batch identity"
        );
        if sample.phase == "measured" {
            measured_metrics.push(metrics);
        }
        observations.push(VerifiedPerformanceSample {
            sample: sample.relative.clone(),
            phase: sample.phase.to_owned(),
            sample_index: sample.index,
            batch: sample.batch,
            capture_core_interval_cycles: metrics.capture_span,
            memory_retirement_interval_cycles: metrics.memory_span,
            whole_kernel_nanoseconds: metrics.kernel_nanoseconds,
            _marker: VerifiedMarker,
        });
    }
    // This preserves compatibility with the producer's human-readable float
    // report. It is only a sealed-record consistency check: the typed proof's
    // pass/fail observations below use the raw integer numerators exclusively.
    validate_results_statistics(&results, &metadata, &measured_metrics)?;

    Ok(VerifiedTransportEvidence {
        hardware_card_identity: verified_hardware_card_identity(&hardware),
        performance: verified_performance_observations(&metadata, observations)?,
    })
}

fn verified_hardware_card_identity(
    hardware: &super::ValidatedHardwareIdentity,
) -> VerifiedHardwareCardIdentity {
    let identity = &hardware.pre_run;
    VerifiedHardwareCardIdentity {
        device_index: identity.device.index,
        bdf: identity.device.bdf.clone(),
        device_name: identity.device.name.clone(),
        xmc_serial_number: identity.platform.xmc_serial_number.clone(),
        shell_vbnv: identity.platform.shell_vbnv.clone(),
        logic_uuid: identity.platform.logic_uuid.clone(),
        interface_uuid: identity.device.interface_uuid.clone(),
        fpga_part: identity.platform.fpga_part.clone(),
        xrt_build: VerifiedXrtBuildIdentity {
            version: identity.xrt_build.version.clone(),
            branch: identity.xrt_build.branch.clone(),
            hash: identity.xrt_build.hash.clone(),
            build_date: identity.xrt_build.build_date.clone(),
            _marker: VerifiedMarker,
        },
        xclbin: VerifiedHardwareXclbinIdentity {
            path: identity.xclbin.path.clone(),
            bytes: identity.xclbin.digest.bytes,
            sha256: identity.xclbin.digest.sha256.clone(),
            uuid: identity.xclbin.uuid.clone(),
            interface_uuid: identity.xclbin.interface_uuid.clone(),
            deployment_platform: identity.xclbin.xsa_name.clone(),
            fpga_part: identity.xclbin.fpga_part.clone(),
            target: identity.xclbin.target.clone(),
            _marker: VerifiedMarker,
        },
        _marker: VerifiedMarker,
    }
}

fn verified_clock_observation(metadata: &RunMetadata) -> VerifiedClockObservation {
    let routed_clock_evidence = metadata
        .clock
        .routed_clock_evidence
        .as_ref()
        .map(|evidence| VerifiedRoutedClockEvidenceBinding {
            path: evidence.path.clone(),
            bytes: evidence.digest.bytes,
            sha256: evidence.digest.sha256.clone(),
            _marker: VerifiedMarker,
        });
    VerifiedClockObservation {
        requested_clock_hz_metadata: metadata.clock.requested_clock_hz_metadata,
        declared_routed_hz: metadata.clock.routed_clock_hz,
        routed_clock_evidence,
        supports_hardware_rate_claim: metadata.clock.supports_hardware_rate_claim,
        _marker: VerifiedMarker,
    }
}

fn verified_performance_observations(
    metadata: &RunMetadata,
    samples: Vec<VerifiedPerformanceSample>,
) -> Result<VerifiedPerformanceObservations> {
    let decision = exact_performance_decision(
        metadata.batches.contains(&REQUIRED_PERFORMANCE_BATCH),
        &samples,
    )?;
    let observations = VerifiedPerformanceObservations {
        required_batch: REQUIRED_PERFORMANCE_BATCH,
        minimum_measured_samples: REQUIRED_PERFORMANCE_SAMPLES,
        required_batch_requested: decision.required_batch_requested,
        observed_measured_samples: decision.observed_measured_samples,
        p95_rank: decision.p95_rank,
        p95_capture_interval_cycles: decision.p95_capture_interval_cycles,
        capture_results_denominator: REQUIRED_PERFORMANCE_BATCH - 1,
        p95_whole_kernel_nanoseconds: decision.p95_whole_kernel_nanoseconds,
        whole_kernel_results_denominator: REQUIRED_PERFORMANCE_BATCH,
        clock: verified_clock_observation(metadata),
        samples,
        _marker: VerifiedMarker,
    };
    // This provisional comparison is intentionally consumed only inside the
    // typed verifier. Public callers receive the exact observations; a later
    // route combiner must independently join accepted route evidence before it
    // can make a performance or hardware-completion claim.
    let _pre_route_only = observations.pre_route_join_performance_thresholds_met();
    Ok(observations)
}

fn exact_performance_decision(
    required_batch_requested: bool,
    samples: &[VerifiedPerformanceSample],
) -> Result<ExactPerformanceDecision> {
    let measured = samples
        .iter()
        .filter(|sample| sample.is_required_performance_population())
        .collect::<Vec<_>>();
    ensure!(
        measured.len() <= MAXIMUM_TYPED_PERFORMANCE_SAMPLES,
        "typed performance population exceeds its strict memory bound"
    );
    ensure!(
        measured.iter().all(|sample| {
            sample.capture_core_interval_cycles > 0 && sample.whole_kernel_nanoseconds > 0
        }),
        "typed performance population contains a zero raw cost"
    );
    let capture = measured
        .iter()
        .map(|sample| sample.capture_core_interval_cycles)
        .collect::<Vec<_>>();
    let whole = measured
        .iter()
        .map(|sample| sample.whole_kernel_nanoseconds)
        .collect::<Vec<_>>();
    let (p95_rank, p95_capture_interval_cycles) = exact_nearest_rank_p95(capture)?;
    let (_, p95_whole_kernel_nanoseconds) = exact_nearest_rank_p95(whole)?;
    let observed_measured_samples = measured.len();

    Ok(ExactPerformanceDecision {
        required_batch_requested,
        observed_measured_samples,
        p95_rank,
        p95_capture_interval_cycles,
        p95_whole_kernel_nanoseconds,
    })
}

fn exact_capture_cycles_threshold_met(p95_capture_interval_cycles: Option<u64>) -> bool {
    let capture_denominator = u128::from(REQUIRED_PERFORMANCE_BATCH - 1);
    p95_capture_interval_cycles.is_some_and(|cycles| {
        u128::from(cycles) <= u128::from(MAXIMUM_P95_CAPTURE_CYCLES_EXACT) * capture_denominator
    })
}

fn exact_capture_rate_threshold_met(
    clock_hz: u64,
    p95_capture_interval_cycles: Option<u64>,
) -> bool {
    let capture_denominator = u128::from(REQUIRED_PERFORMANCE_BATCH - 1);
    let minimum_rate = u128::from(MINIMUM_SIGNATURES_PER_SECOND_EXACT);
    p95_capture_interval_cycles.is_some_and(|cycles| {
        u128::from(clock_hz) * capture_denominator >= minimum_rate * u128::from(cycles)
    })
}

fn exact_whole_kernel_rate_threshold_met(p95_whole_kernel_nanoseconds: Option<u64>) -> bool {
    let whole_denominator = u128::from(REQUIRED_PERFORMANCE_BATCH);
    let minimum_rate = u128::from(MINIMUM_SIGNATURES_PER_SECOND_EXACT);
    p95_whole_kernel_nanoseconds.is_some_and(|nanoseconds| {
        1_000_000_000_u128 * whole_denominator >= minimum_rate * u128::from(nanoseconds)
    })
}

fn exact_nearest_rank_p95(mut values: Vec<u64>) -> Result<(Option<usize>, Option<u64>)> {
    if values.is_empty() {
        return Ok((None, None));
    }
    ensure!(
        values.len() <= MAXIMUM_TYPED_PERFORMANCE_SAMPLES,
        "typed p95 population exceeds its strict memory bound"
    );
    values.sort_unstable();
    let rank = values
        .len()
        .checked_mul(95)
        .context("typed p95 rank overflow")?
        .div_ceil(100);
    let value = values
        .get(rank.checked_sub(1).context("typed p95 rank underflow")?)
        .copied()
        .context("typed p95 rank exceeds its population")?;
    Ok((Some(rank), Some(value)))
}

struct TranscriptReader<'a> {
    file: &'a StrictResultFile,
    offset: u64,
}

impl<'a> TranscriptReader<'a> {
    fn new(file: &'a StrictResultFile) -> Self {
        Self { file, offset: 0 }
    }

    fn next_line(&mut self) -> Result<Option<Vec<u8>>> {
        if self.offset == self.file.bytes() {
            return Ok(None);
        }
        let mut line = Vec::new();
        while self.offset < self.file.bytes() {
            let remaining = self.file.bytes() - self.offset;
            let capacity = MAXIMUM_JOB_LINE_BYTES
                .checked_add(1)
                .and_then(|limit| limit.checked_sub(line.len()))
                .context("job transcript line length overflow")?;
            ensure!(
                capacity > 0,
                "job transcript line exceeds its strict size limit"
            );
            let amount = usize::try_from(
                remaining
                    .min(u64::try_from(capacity).expect("line capacity fits u64"))
                    .min(u64::try_from(JOB_READ_BUFFER_BYTES).expect("buffer size fits u64")),
            )
            .expect("bounded transcript read fits usize");
            let mut chunk = vec![0_u8; amount];
            self.file.read_exact_at(&mut chunk, self.offset)?;
            if let Some(position) = chunk.iter().position(|byte| *byte == b'\n') {
                let used = position + 1;
                line.extend_from_slice(&chunk[..used]);
                self.offset = self
                    .offset
                    .checked_add(u64::try_from(used).expect("line length fits u64"))
                    .context("job transcript offset overflow")?;
                ensure!(
                    line.len() <= MAXIMUM_JOB_LINE_BYTES,
                    "job transcript line exceeds its strict size limit"
                );
                return Ok(Some(line));
            }
            line.extend_from_slice(&chunk);
            self.offset = self
                .offset
                .checked_add(u64::try_from(amount).expect("chunk length fits u64"))
                .context("job transcript offset overflow")?;
            ensure!(
                line.len() <= MAXIMUM_JOB_LINE_BYTES,
                "job transcript line exceeds its strict size limit"
            );
        }
        bail!("job transcript has a truncated final line")
    }
}

fn parse_typed_transport_json<T>(transport: &ArchiveSnapshot, path: &str) -> Result<T>
where
    T: serde::de::DeserializeOwned,
{
    let maximum = transport
        .files
        .get(path)
        .with_context(|| format!("typed transport manifest omits {path}"))?
        .bytes;
    let bytes = read_verified_small_exact(transport, path, maximum)?;
    parse_strict_json(&bytes, path)
}

// Keep the fail-closed cross-artifact join linear so validation order and
// descriptor finalization remain directly auditable.
#[allow(clippy::too_many_lines)]
fn validate_transport_join(
    result: &StrictResultSnapshot,
    transport: &ArchiveSnapshot,
    summary: &SealedSummary,
) -> Result<Vec<TranscriptCount>> {
    let metadata: RunMetadata = parse_typed_transport_json(transport, "run-metadata.json")?;
    validate_transport_metadata_shape(&metadata, summary)?;
    let samples = expected_layout(transport, &metadata)?;
    ensure!(
        samples.len() == summary.requests.len(),
        "transport sample set differs from the typed result request set"
    );
    let jobs_file = result.file("jobs.jsonl")?;
    let mut transcript = TranscriptReader::new(jobs_file);
    let mut unique_private_seeds = HashSet::new();
    let mut reservation_ids = HashSet::new();
    let mut reservation_nonces = HashSet::new();
    let mut reservation_chain = None;
    let mut counts = Vec::with_capacity(samples.len());
    let oracle = Sha256GenericWots::new();

    for (sample, sealed) in samples.iter().zip(&summary.requests) {
        ensure!(
            sealed.sample == sample.relative
                && sealed.batch == sample.batch
                && sealed.phase == sample.phase
                && sealed.sample_index == sample.index,
            "typed result sample order or identity differs from the retained transport"
        );
        let request_path = format!("{}/oracle-request.json", sample.relative);
        let request_bytes =
            read_verified_small_exact(transport, &request_path, TYPED_TRANSPORT_SAMPLE_JSON_BYTES)?;
        let request_sha256 = sha256_bytes(&request_bytes);
        ensure!(
            request_sha256 == sealed.request_sha256,
            "typed result request digest differs from the retained transport"
        );
        let request: OracleRequest = parse_strict_json(&request_bytes, &request_path)?;
        validate_transport_request(transport, &metadata, sample, sealed, &request)?;
        let sidecar_path = format!("{}/oracle-request.sha256", sample.relative);
        let sidecar = read_verified_small_exact(transport, &sidecar_path, 256)?;
        ensure!(
            sidecar == format!("{request_sha256}  oracle-request.json\n").as_bytes(),
            "transport oracle-request sidecar differs from the exact request"
        );
        let reservation_path = format!("{}/reservation.json", sample.relative);
        let reservation_bytes = read_verified_small_exact(
            transport,
            &reservation_path,
            TYPED_TRANSPORT_SAMPLE_JSON_BYTES,
        )?;
        let reservation: ReservationReceipt =
            parse_strict_json(&reservation_bytes, &reservation_path)?;
        validate_reservation(&reservation, &reservation_bytes, &request)?;
        advance_reservation_chain(&mut reservation_chain, &reservation)?;
        ensure!(
            reservation_ids.insert(reservation.reservation_id)
                && reservation_nonces.insert(reservation.nonce),
            "retained transport repeats a reservation identity or nonce"
        );
        let transport_contract_path = format!("{}/transport.json", sample.relative);
        let transport_contract: TransportContract =
            parse_typed_transport_json(transport, &transport_contract_path)?;
        validate_transport_contract(&transport_contract, &request)?;

        let input_path = format!("{}/input.bin", sample.relative);
        let output_path = format!("{}/output.bin", sample.relative);
        let input = open_verified_file_exact(transport, &input_path)?;
        let output = open_verified_file_exact(transport, &output_path)?;
        let mut count = TranscriptCount {
            jobs: 0,
            matched_jobs: 0,
            padding_valid: true,
        };
        if sample.batch == 0 {
            let mut sentinel = [0_u8; OUTPUT_SLOT_BYTES_USIZE];
            output.read_exact_at(&mut sentinel, 0)?;
            count.padding_valid = sentinel.iter().enumerate().all(|(offset, byte)| {
                *byte == output_poison(u64::try_from(offset).expect("slot offset fits u64"))
            });
        }
        for job_index in 0..sample.batch {
            let line = transcript
                .next_line()?
                .context("job transcript omits one or more transport-owned jobs")?;
            let job: SealedJob = parse_canonical_json(&line, "jobs.jsonl line")?;
            ensure!(
                job.schema == 1 && job.sample == sample.relative && job.job_index == job_index,
                "job transcript is missing, duplicated, reordered, or relabeled"
            );
            for (digest, label) in [
                (&job.input_sha256, "job input"),
                (&job.expected_sha256, "job expected payload"),
                (&job.observed_sha256, "job observed payload"),
            ] {
                ensure!(
                    is_nonzero_lower_hex(digest, 64),
                    "{label} SHA-256 is not canonical"
                );
            }
            let computation = recompute_transport_job(
                oracle,
                &input,
                &output,
                job_index,
                &mut unique_private_seeds,
            )?;
            ensure!(
                job.input_sha256 == computation.input_sha256,
                "job input digest differs from retained transport input bytes"
            );
            ensure!(
                job.expected_sha256 == computation.expected_sha256,
                "job expected digest differs from independent WOTS recomputation"
            );
            ensure!(
                job.observed_sha256 == computation.observed_sha256,
                "job observed digest differs from retained transport output bytes"
            );
            ensure!(
                job.r#match == computation.payload_match
                    && job.r#match == (job.expected_sha256 == job.observed_sha256),
                "job match decision differs from independent transport evidence"
            );
            count.jobs = count.jobs.checked_add(1).context("job count overflow")?;
            if computation.payload_match {
                count.matched_jobs = count
                    .matched_jobs
                    .checked_add(1)
                    .context("matched job count overflow")?;
            }
            count.padding_valid &= computation.padding_valid;
        }
        input.finish()?;
        output.finish()?;
        counts.push(count);
    }
    ensure!(
        transcript.next_line()?.is_none(),
        "job transcript contains an extra transport-unowned job"
    );
    jobs_file.finish()?;
    Ok(counts)
}

fn validate_transport_metadata_shape(
    metadata: &RunMetadata,
    summary: &SealedSummary,
) -> Result<()> {
    ensure!(
        metadata.schema == 2,
        "transport run metadata schema must be 2"
    );
    ensure!(
        metadata.runner == "phase_b_hbm",
        "transport is not a Phase-B HBM run"
    );
    ensure!(
        metadata.kernel_name == DEFAULT_KERNEL
            && metadata.measured_runs_per_batch > 0
            && metadata.cryptographic_control == "Rust/RHDL kernel only"
            && metadata.output_oracle == "external Rust oracle required",
        "transport metadata execution/oracle contract changed"
    );
    ensure!(
        metadata.run_id == summary.run_id,
        "transport metadata and typed result name different runs"
    );
    ensure!(
        root_binding_matches(&metadata.coordination_intent, &summary.coordination_intent)
            && root_binding_matches(&metadata.coordination_burn, &summary.coordination_burn)
            && root_binding_matches(
                &metadata.coordination_receipt,
                &summary.coordination_receipt,
            ),
        "transport metadata coordination roots differ from the typed result"
    );
    ensure!(
        !metadata.batches.is_empty() && metadata.batches.len() <= MAXIMUM_RESULT_REQUESTS,
        "transport batch set exceeds the typed verifier policy"
    );
    let samples_per_batch = metadata
        .warmups_per_batch
        .checked_add(metadata.measured_runs_per_batch)
        .context("transport samples-per-batch overflow")?;
    let sample_count = metadata
        .batches
        .len()
        .checked_mul(samples_per_batch)
        .context("transport sample count overflow")?;
    ensure!(
        sample_count > 0
            && sample_count <= MAXIMUM_RESULT_REQUESTS
            && sample_count == summary.sample_count,
        "transport-derived sample count differs from the bounded typed result"
    );
    let mut batches = HashSet::new();
    for batch in &metadata.batches {
        ensure!(
            *batch <= MAXIMUM_BATCH && batches.insert(*batch),
            "transport metadata has an invalid or repeated batch"
        );
    }
    Ok(())
}

// This linear validation mirrors the canonical request contract and preserves
// the audit-visible order of its fail-closed checks.
#[allow(clippy::too_many_lines)]
fn validate_transport_request(
    transport: &ArchiveSnapshot,
    metadata: &RunMetadata,
    sample: &SampleSpec,
    sealed: &SealedRequest,
    request: &OracleRequest,
) -> Result<()> {
    ensure!(
        request.schema == 2,
        "transport oracle request schema must be 2"
    );
    ensure!(
        request.kind == REQUEST_KIND,
        "transport oracle request kind changed"
    );
    ensure!(
        request.profile == PROFILE,
        "transport oracle request profile changed"
    );
    ensure!(
        request.run_id == sealed.run_id && request.run_id == metadata.run_id,
        "typed result request differs from the transport coordination run"
    );
    ensure!(
        root_binding_matches(&request.coordination_intent, &sealed.coordination_intent)
            && root_binding_matches(&request.coordination_burn, &sealed.coordination_burn)
            && root_binding_matches(&request.coordination_receipt, &sealed.coordination_receipt,),
        "typed result request coordination roots differ from the original request"
    );
    ensure!(
        request.batch == sample.batch && request.batch == sealed.batch,
        "typed result request batch differs from the transport-owned sample"
    );
    ensure!(
        is_lower_hex(&request.nonce_hex, 16)
            && u64::from_str_radix(&request.nonce_hex, 16)? == request.nonce_u64
            && request.nonce_hex == sealed.nonce_hex,
        "typed result nonce differs from the original request"
    );
    ensure!(
        request.reservation_record_sha256 == sealed.reservation_record_sha256,
        "typed result reservation digest differs from the original request"
    );
    ensure!(
        request.xclbin.path == sealed.xclbin.path
            && request.xclbin.bytes == sealed.xclbin.bytes
            && request.xclbin.sha256 == sealed.xclbin.sha256
            && request.xclbin.path == metadata.xclbin.path
            && request.xclbin.bytes == metadata.xclbin.digest.bytes
            && request.xclbin.sha256 == metadata.xclbin.digest.sha256,
        "typed result xclbin differs from the transport request or metadata"
    );
    ensure!(
        request.clock == metadata.clock,
        "transport request clock binding differs from run metadata"
    );
    ensure!(
        root_binding_matches(
            &request.hardware_identity_pre_run,
            &sealed.hardware_identity_pre_run,
        ),
        "typed result pre-run identity differs from the original request"
    );
    let pre_run_record = transport
        .files
        .get("hardware-identity-pre-run.json")
        .context("transport manifest omits hardware-identity-pre-run.json")?;
    ensure!(
        request.hardware_identity_pre_run.archive_root_file == "hardware-identity-pre-run.json"
            && request.hardware_identity_pre_run.bytes == pre_run_record.bytes
            && request.hardware_identity_pre_run.sha256 == pre_run_record.sha256,
        "original request pre-run identity differs from the transport manifest"
    );

    let logical_input = u64::from(sample.batch)
        .checked_mul(INPUT_BYTES_PER_JOB)
        .context("transport input geometry overflow")?;
    let logical_output = u64::from(sample.batch)
        .checked_mul(OUTPUT_SLOT_BYTES)
        .context("transport output geometry overflow")?;
    let stored_output = if sample.batch == 0 {
        OUTPUT_SLOT_BYTES
    } else {
        logical_output
    };
    validate_transport_artifact_join(
        transport,
        sample,
        &request.artifacts.input,
        &sealed.input,
        "input.bin",
        logical_input,
    )?;
    validate_transport_artifact_join(
        transport,
        sample,
        &request.artifacts.full_output_allocation,
        &sealed.output,
        "output.bin",
        stored_output,
    )?;
    validate_transport_request_artifact(
        transport,
        sample,
        &request.artifacts.summary,
        "summary.bin",
        SUMMARY_BYTES,
    )?;
    for (artifact, file) in [
        (&request.artifacts.diagnostic_registers, "diagnostics.json"),
        (
            &request.artifacts.untimed_transport_validation,
            "validation.json",
        ),
        (&request.artifacts.timing, "timing.json"),
        (&request.artifacts.transport_contract, "transport.json"),
    ] {
        let path = format!("{}/{file}", sample.relative);
        let bytes = transport
            .files
            .get(&path)
            .with_context(|| format!("transport manifest omits {path}"))?
            .bytes;
        validate_transport_request_artifact(transport, sample, artifact, file, bytes)?;
    }
    ensure!(
        request.output_contract.slot_bytes == OUTPUT_SLOT_BYTES
            && request.output_contract.valid_bytes_per_job == OUTPUT_VALID_BYTES
            && request.output_contract.padding_bytes_per_job == OUTPUT_PADDING_BYTES
            && request.output_contract.requested_output_slot_bytes == logical_output
            && request.output_contract.full_output_allocation_bytes == stored_output,
        "transport request output contract has the wrong geometry"
    );
    ensure!(
        request.cryptographic_oracle_valid.is_none() && !request.hardware_completion_promotable,
        "transport request contains a premature oracle or promotion decision"
    );
    let must_bind = request
        .required_oracle_result
        .must_bind
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    ensure!(
        request.required_oracle_result.producer == "independent Rust oracle"
            && must_bind.len() == 7
            && must_bind[0] == "oracle-request.json sha256"
            && must_bind[1] == "coordination-intent.json sha256"
            && must_bind[2] == "coordination-burn.json sha256"
            && must_bind[3] == "coordination-receipt.json sha256"
            && must_bind[4] == "hardware-identity-pre-run.json sha256"
            && must_bind[5] == "top-level SHA256SUMS sha256"
            && must_bind[6] == "every input/output job"
            && request
                .required_oracle_result
                .must_not_mutate_transport_archive,
        "transport request required-oracle contract changed"
    );
    Ok(())
}

fn root_binding_matches(
    original: &crate::model::RootArtifactBinding,
    sealed: &SealedBinding,
) -> bool {
    original.archive_root_file == sealed.file
        && original.bytes == sealed.bytes
        && original.sha256 == sealed.sha256
}

fn validate_transport_artifact_join(
    transport: &ArchiveSnapshot,
    sample: &SampleSpec,
    original: &crate::model::ArtifactBinding,
    sealed: &SealedRequestArtifactBinding,
    expected_file: &str,
    expected_bytes: u64,
) -> Result<()> {
    ensure!(
        original.file == expected_file
            && original.logical_bytes == expected_bytes
            && original.stored_bytes == expected_bytes
            && sealed.file == original.file
            && sealed.logical_bytes == original.logical_bytes
            && sealed.stored_bytes == original.stored_bytes
            && sealed.sha256 == original.sha256,
        "typed result {expected_file} binding differs from the original request"
    );
    let path = format!("{}/{expected_file}", sample.relative);
    let record = transport
        .files
        .get(&path)
        .with_context(|| format!("transport manifest omits {path}"))?;
    ensure!(
        record.bytes == original.stored_bytes && record.sha256 == original.sha256,
        "original request {expected_file} differs from the transport manifest"
    );
    Ok(())
}

fn validate_transport_request_artifact(
    transport: &ArchiveSnapshot,
    sample: &SampleSpec,
    original: &crate::model::ArtifactBinding,
    expected_file: &str,
    expected_bytes: u64,
) -> Result<()> {
    ensure!(
        original.file == expected_file
            && original.logical_bytes == expected_bytes
            && original.stored_bytes == expected_bytes,
        "original request {expected_file} has invalid geometry"
    );
    let path = format!("{}/{expected_file}", sample.relative);
    let record = transport
        .files
        .get(&path)
        .with_context(|| format!("transport manifest omits {path}"))?;
    ensure!(
        record.bytes == original.stored_bytes && record.sha256 == original.sha256,
        "original request {expected_file} differs from the transport manifest"
    );
    Ok(())
}

struct JobRecomputation {
    input_sha256: String,
    expected_sha256: String,
    observed_sha256: String,
    payload_match: bool,
    padding_valid: bool,
}

fn recompute_transport_job(
    oracle: Sha256GenericWots,
    input_file: &StrictResultFile,
    output_file: &StrictResultFile,
    job_index: u32,
    unique_private_seeds: &mut HashSet<[u8; 32]>,
) -> Result<JobRecomputation> {
    let job_offset = u64::from(job_index);
    let mut input = [0_u8; 64];
    let mut output = [0_u8; OUTPUT_SLOT_BYTES_USIZE];
    input_file.read_exact_at(
        &mut input,
        job_offset
            .checked_mul(INPUT_BYTES_PER_JOB)
            .context("transport input offset overflow")?,
    )?;
    output_file.read_exact_at(
        &mut output,
        job_offset
            .checked_mul(OUTPUT_SLOT_BYTES)
            .context("transport output offset overflow")?,
    )?;
    let private_seed: [u8; 32] = input[..32].try_into().expect("fixed seed span");
    let message: [u8; 32] = input[32..].try_into().expect("fixed message span");
    let seed_sha256: [u8; 32] = Sha256::digest(private_seed).into();
    ensure!(
        unique_private_seeds.insert(seed_sha256),
        "retained transport repeats a one-time private seed"
    );
    let fused = oracle.sign_and_public_key_from_private_seed(
        PrivateSeed::<HashSigsSha256GenericV1>::new(private_seed),
        &MessageDigest::new(message),
    );
    let signature = fused.signature.to_bytes();
    let public_key = fused.public_key.to_bytes();
    let mut expected = [0_u8; FUSED_OUTPUT_BYTES];
    expected[..SIGNATURE_BYTES].copy_from_slice(&signature);
    expected[SIGNATURE_BYTES..].copy_from_slice(&public_key);
    let observed = &output[..OUTPUT_VALID_BYTES_USIZE];
    let payload_match = observed == expected.as_slice();
    let padding_valid =
        output[OUTPUT_VALID_BYTES_USIZE..]
            .iter()
            .enumerate()
            .all(|(padding_index, byte)| {
                let global = job_offset
                    .checked_mul(OUTPUT_SLOT_BYTES)
                    .and_then(|offset| offset.checked_add(OUTPUT_VALID_BYTES))
                    .and_then(|offset| {
                        offset.checked_add(
                            u64::try_from(padding_index).expect("padding offset fits u64"),
                        )
                    })
                    .expect("validated output geometry fits u64");
                *byte == output_poison(global)
            });
    let result = JobRecomputation {
        input_sha256: crate::archive::hex_lower(&Sha256::digest(input)),
        expected_sha256: crate::archive::hex_lower(&Sha256::digest(expected)),
        observed_sha256: crate::archive::hex_lower(&Sha256::digest(observed)),
        payload_match,
        padding_valid,
    };
    input.fill(0);
    output.fill(0);
    Ok(result)
}

// Keep each derived decision adjacent to its fail-closed consistency check so
// the aggregate validation sequence remains directly auditable.
#[allow(clippy::too_many_lines)]
fn validate_summary_decisions(
    summary: SealedSummary,
    transcript_counts: &[TranscriptCount],
) -> Result<VerifiedValues> {
    ensure!(
        transcript_counts.len() == summary.requests.len(),
        "job transcript request cardinality changed"
    );
    let mut total_jobs = 0_u64;
    let mut total_matched = 0_u64;
    let mut all_padding_valid = true;
    let mut common_pre_run = None;
    let mut common_xclbin = None;
    let mut verified_requests = Vec::with_capacity(summary.requests.len());

    for (request, transcript) in summary.requests.iter().zip(transcript_counts) {
        ensure!(
            transcript.jobs == request.jobs,
            "request job count differs from its complete transcript"
        );
        ensure!(
            request.matched_jobs == transcript.matched_jobs,
            "request matched-job count differs from its transcript"
        );
        ensure!(
            request.padding_valid == transcript.padding_valid,
            "request padding decision differs from retained transport bytes"
        );
        let mismatched_jobs = request
            .jobs
            .checked_sub(request.matched_jobs)
            .context("request matched-job count exceeds jobs")?;
        let cryptographic_oracle_valid = mismatched_jobs == 0 && transcript.padding_valid;
        ensure!(
            request.cryptographic_oracle_valid == cryptographic_oracle_valid,
            "request cryptographic decision differs from payload/padding evidence"
        );
        if let Some(binding) = &common_pre_run {
            ensure!(
                binding == &request.hardware_identity_pre_run,
                "requests bind different pre-run hardware identities"
            );
        } else {
            common_pre_run = Some(request.hardware_identity_pre_run.clone());
        }
        if let Some(binding) = &common_xclbin {
            ensure!(
                binding == &request.xclbin,
                "requests bind different hardware xclbins"
            );
        } else {
            common_xclbin = Some(request.xclbin.clone());
        }
        total_jobs = total_jobs
            .checked_add(u64::from(request.jobs))
            .context("typed result total job count overflow")?;
        total_matched = total_matched
            .checked_add(u64::from(request.matched_jobs))
            .context("typed result matched job count overflow")?;
        all_padding_valid &= transcript.padding_valid;
        verified_requests.push(VerifiedResultRequest {
            sample: request.sample.clone(),
            phase: request.phase.clone(),
            sample_index: request.sample_index,
            request_sha256: request.request_sha256.clone(),
            run_id: request.run_id.clone(),
            coordination_intent: verified_binding(&request.coordination_intent),
            coordination_burn: verified_binding(&request.coordination_burn),
            coordination_receipt: verified_binding(&request.coordination_receipt),
            batch: request.batch,
            nonce_hex: request.nonce_hex.clone(),
            reservation_record_sha256: request.reservation_record_sha256.clone(),
            xclbin: verified_xclbin(&request.xclbin),
            hardware_identity_pre_run: verified_binding(&request.hardware_identity_pre_run),
            input: verified_request_artifact(&request.input),
            output: verified_request_artifact(&request.output),
            jobs: request.jobs,
            matched_jobs: request.matched_jobs,
            mismatched_jobs,
            padding_valid: transcript.padding_valid,
            cryptographic_oracle_valid,
            _marker: VerifiedMarker,
        });
    }

    let mismatched_jobs = total_jobs
        .checked_sub(total_matched)
        .context("typed result matched-job count exceeds jobs")?;
    let cryptographic_oracle_valid = mismatched_jobs == 0 && all_padding_valid;
    ensure!(
        summary.total_jobs == total_jobs
            && summary.matched_jobs == total_matched
            && summary.mismatched_jobs == mismatched_jobs,
        "typed result aggregate job counters differ from the complete request set"
    );
    ensure!(
        summary.all_padding_valid == all_padding_valid,
        "typed result aggregate padding decision differs from its requests"
    );
    ensure!(
        summary.cryptographic_oracle_valid == cryptographic_oracle_valid,
        "typed result aggregate cryptographic decision is inconsistent"
    );

    Ok(VerifiedValues {
        transport_manifest: verified_binding(&summary.transport_manifest),
        final_hardware_identity: verified_binding(&summary.final_hardware_identity),
        run_id: summary.run_id,
        coordination_intent: verified_binding(&summary.coordination_intent),
        coordination_burn: verified_binding(&summary.coordination_burn),
        coordination_receipt: verified_binding(&summary.coordination_receipt),
        samples: summary.sample_count,
        jobs: total_jobs,
        matched_jobs: total_matched,
        mismatched_jobs,
        all_padding_valid,
        cryptographic_oracle_valid,
        requests: verified_requests,
    })
}

fn validate_receipt_result_join(receipt: &CompletedReceipt, values: &VerifiedValues) -> Result<()> {
    ensure!(
        receipt.samples == values.samples && receipt.jobs == values.jobs,
        "creation receipt sample/job totals differ from the typed result"
    );
    ensure!(
        receipt.cryptographic_oracle_valid == values.cryptographic_oracle_valid,
        "creation receipt cryptographic decision differs from the typed result"
    );
    Ok(())
}

fn validate_request_shape(request: &SealedRequest, summary: &SealedSummary) -> Result<()> {
    // Batch zero is the producer's poison-sentinel cryptographic control. It
    // carries no job/performance observation and every promotion flag remains
    // false; validate_request_artifact_geometry enforces its sole 4 KiB slot.
    ensure!(
        request.batch <= MAXIMUM_BATCH,
        "typed result request batch exceeds the shell ABI"
    );
    ensure!(
        matches!(request.phase.as_str(), "warmup" | "measured"),
        "typed result request phase is invalid"
    );
    let expected_sample = format!(
        "samples/batch-{:05}/{}-{:03}",
        request.batch, request.phase, request.sample_index
    );
    ensure!(
        request.sample == expected_sample,
        "typed result request sample path is noncanonical"
    );
    ensure!(
        is_nonzero_lower_hex(&request.request_sha256, 64),
        "typed result request SHA-256 is not canonical"
    );
    ensure!(
        request.run_id == summary.run_id,
        "typed result request crosses coordination runs"
    );
    ensure!(
        request.coordination_intent == summary.coordination_intent
            && request.coordination_burn == summary.coordination_burn
            && request.coordination_receipt == summary.coordination_receipt,
        "typed result request coordination roots differ from the result"
    );
    ensure!(
        is_lower_hex(&request.nonce_hex, 16),
        "typed result request nonce is not canonical"
    );
    ensure!(
        is_nonzero_lower_hex(&request.reservation_record_sha256, 64),
        "typed result request reservation SHA-256 is not canonical"
    );
    validate_binding(
        &request.hardware_identity_pre_run,
        "hardware-identity-pre-run.json",
        "request pre-run hardware identity",
    )?;
    validate_xclbin(&request.xclbin)?;
    validate_request_artifact_geometry(request)?;
    Ok(())
}

fn validate_request_artifact_geometry(request: &SealedRequest) -> Result<()> {
    let input_bytes = u64::from(request.batch)
        .checked_mul(INPUT_BYTES_PER_JOB)
        .context("typed result input geometry overflow")?;
    let logical_output = u64::from(request.batch)
        .checked_mul(OUTPUT_SLOT_BYTES)
        .context("typed result output geometry overflow")?;
    let output_bytes = if request.batch == 0 {
        OUTPUT_SLOT_BYTES
    } else {
        logical_output
    };
    validate_request_artifact(&request.input, "input.bin", input_bytes, input_bytes)?;
    validate_request_artifact(&request.output, "output.bin", output_bytes, output_bytes)?;
    Ok(())
}

fn validate_request_artifact(
    binding: &SealedRequestArtifactBinding,
    file: &str,
    logical_bytes: u64,
    stored_bytes: u64,
) -> Result<()> {
    ensure!(
        binding.file == file,
        "request artifact names the wrong file"
    );
    ensure!(
        binding.logical_bytes == logical_bytes && binding.stored_bytes == stored_bytes,
        "request artifact geometry differs from its batch"
    );
    ensure!(
        is_nonzero_lower_hex(&binding.sha256, 64),
        "request artifact SHA-256 is not canonical"
    );
    Ok(())
}

fn validate_xclbin(binding: &SealedXclbinBinding) -> Result<()> {
    ensure!(
        canonical_absolute_path(Path::new(&binding.path)),
        "typed result xclbin path is not absolute and canonical"
    );
    ensure!(binding.bytes > 0, "typed result xclbin is empty");
    ensure!(
        is_nonzero_lower_hex(&binding.sha256, 64),
        "typed result xclbin SHA-256 is not canonical"
    );
    Ok(())
}

fn validate_binding(binding: &SealedBinding, file: &str, label: &str) -> Result<()> {
    ensure!(binding.file == file, "{label} names the wrong file");
    ensure!(binding.bytes > 0, "{label} byte count must be positive");
    ensure!(
        is_nonzero_lower_hex(&binding.sha256, 64),
        "{label} SHA-256 is not canonical"
    );
    Ok(())
}

fn verified_binding(binding: &SealedBinding) -> VerifiedResultArtifactBinding {
    VerifiedResultArtifactBinding {
        file: binding.file.clone(),
        bytes: binding.bytes,
        sha256: binding.sha256.clone(),
        _marker: VerifiedMarker,
    }
}

fn verified_request_artifact(
    binding: &SealedRequestArtifactBinding,
) -> VerifiedRequestArtifactBinding {
    VerifiedRequestArtifactBinding {
        file: binding.file.clone(),
        logical_bytes: binding.logical_bytes,
        stored_bytes: binding.stored_bytes,
        sha256: binding.sha256.clone(),
        _marker: VerifiedMarker,
    }
}

fn verified_xclbin(binding: &SealedXclbinBinding) -> VerifiedXclbinBinding {
    VerifiedXclbinBinding {
        path: binding.path.clone(),
        bytes: binding.bytes,
        sha256: binding.sha256.clone(),
        _marker: VerifiedMarker,
    }
}

fn canonical_absolute_path(path: &Path) -> bool {
    path.is_absolute()
        && path
            .components()
            .all(|component| !matches!(component, Component::CurDir | Component::ParentDir))
        && path.to_str().is_some_and(|text| {
            !text.ends_with('/') && !text.contains("//") && !text.contains('\0')
        })
}

fn is_nonzero_lower_hex(value: &str, width: usize) -> bool {
    is_lower_hex(value, width) && value.bytes().any(|byte| byte != b'0')
}

#[cfg(test)]
mod exact_performance_tests {
    use super::{
        REQUIRED_PERFORMANCE_BATCH, VerifiedMarker, VerifiedPerformanceSample,
        exact_capture_cycles_threshold_met, exact_capture_rate_threshold_met,
        exact_performance_decision, exact_whole_kernel_rate_threshold_met,
    };

    const CAPTURE_BOUNDARY: u64 = 500 * 16_383;
    const WHOLE_KERNEL_BOUNDARY: u64 = 2_000 * 16_384;

    fn sample(
        index: usize,
        phase: &str,
        batch: u32,
        capture_core_interval_cycles: u64,
        whole_kernel_nanoseconds: u64,
    ) -> VerifiedPerformanceSample {
        VerifiedPerformanceSample {
            sample: format!("samples/batch-{batch:05}/{phase}-{index:03}"),
            phase: phase.to_owned(),
            sample_index: index,
            batch,
            capture_core_interval_cycles,
            memory_retirement_interval_cycles: capture_core_interval_cycles,
            whole_kernel_nanoseconds,
            _marker: VerifiedMarker,
        }
    }

    fn population(count: usize, capture: u64, whole: u64) -> Vec<VerifiedPerformanceSample> {
        (0..count)
            .map(|index| {
                sample(
                    index,
                    "measured",
                    REQUIRED_PERFORMANCE_BATCH,
                    capture,
                    whole,
                )
            })
            .collect()
    }

    #[test]
    fn exact_boundary_matches_the_promoter_core_contract() {
        let samples = population(30, CAPTURE_BOUNDARY, WHOLE_KERNEL_BOUNDARY);
        let decision = exact_performance_decision(true, &samples).unwrap();
        assert_eq!(decision.p95_rank, Some(29));
        assert_eq!(decision.p95_capture_interval_cycles, Some(CAPTURE_BOUNDARY));
        assert_eq!(
            decision.p95_whole_kernel_nanoseconds,
            Some(WHOLE_KERNEL_BOUNDARY)
        );
        assert!(exact_capture_cycles_threshold_met(
            decision.p95_capture_interval_cycles
        ));
        assert!(exact_capture_rate_threshold_met(
            250_000_000,
            decision.p95_capture_interval_cycles
        ));
        assert!(exact_whole_kernel_rate_threshold_met(
            decision.p95_whole_kernel_nanoseconds
        ));
    }

    #[test]
    fn one_raw_unit_beyond_each_boundary_fails_without_rounding() {
        let slow_capture = population(30, CAPTURE_BOUNDARY + 1, WHOLE_KERNEL_BOUNDARY);
        let capture = exact_performance_decision(true, &slow_capture).unwrap();
        assert!(!exact_capture_cycles_threshold_met(
            capture.p95_capture_interval_cycles
        ));
        assert!(!exact_capture_rate_threshold_met(
            250_000_000,
            capture.p95_capture_interval_cycles
        ));
        assert!(exact_whole_kernel_rate_threshold_met(
            capture.p95_whole_kernel_nanoseconds
        ));

        let slow_whole = population(30, CAPTURE_BOUNDARY, WHOLE_KERNEL_BOUNDARY + 1);
        let whole = exact_performance_decision(true, &slow_whole).unwrap();
        assert!(exact_capture_cycles_threshold_met(
            whole.p95_capture_interval_cycles
        ));
        assert!(!exact_whole_kernel_rate_threshold_met(
            whole.p95_whole_kernel_nanoseconds
        ));

        let routed_below_baseline = population(30, CAPTURE_BOUNDARY, WHOLE_KERNEL_BOUNDARY);
        let routed = exact_performance_decision(true, &routed_below_baseline).unwrap();
        assert!(exact_capture_rate_threshold_met(
            250_000_000,
            routed.p95_capture_interval_cycles
        ));
        assert!(!exact_capture_rate_threshold_met(
            249_999_999,
            routed.p95_capture_interval_cycles
        ));
    }

    #[test]
    fn nearest_rank_p95_is_the_conservative_twenty_ninth_of_thirty() {
        let mut samples = population(28, 1, 1);
        samples.push(sample(28, "measured", REQUIRED_PERFORMANCE_BATCH, 100, 200));
        samples.push(sample(
            29,
            "measured",
            REQUIRED_PERFORMANCE_BATCH,
            1_000,
            2_000,
        ));
        let decision = exact_performance_decision(true, &samples).unwrap();
        assert_eq!(decision.p95_rank, Some(29));
        assert_eq!(decision.p95_capture_interval_cycles, Some(100));
        assert_eq!(decision.p95_whole_kernel_nanoseconds, Some(200));
    }

    #[test]
    fn warmups_and_other_batches_cannot_complete_the_population() {
        let mut insufficient = population(29, CAPTURE_BOUNDARY, WHOLE_KERNEL_BOUNDARY);
        insufficient.push(sample(
            0,
            "warmup",
            REQUIRED_PERFORMANCE_BATCH,
            CAPTURE_BOUNDARY,
            WHOLE_KERNEL_BOUNDARY,
        ));
        insufficient.push(sample(0, "measured", 65, 1, 1));
        let count = exact_performance_decision(true, &insufficient).unwrap();
        assert_eq!(count.observed_measured_samples, 29);
        assert!(count.required_batch_requested);

        let complete_population = population(30, CAPTURE_BOUNDARY, WHOLE_KERNEL_BOUNDARY);
        let no_route = exact_performance_decision(true, &complete_population).unwrap();
        assert_eq!(no_route.observed_measured_samples, 30);
        assert!(exact_capture_cycles_threshold_met(
            no_route.p95_capture_interval_cycles
        ));
        assert!(exact_capture_rate_threshold_met(
            250_000_000,
            no_route.p95_capture_interval_cycles
        ));
        assert!(exact_whole_kernel_rate_threshold_met(
            no_route.p95_whole_kernel_nanoseconds
        ));
    }
}