zipatch_rs/verify/

mod.rs

//! Post-apply integrity check for files produced by either the sequential
//! [`apply_patch`](crate::ApplyConfig::apply_patch) driver or the indexed
//! [`IndexApplier::execute`](crate::index::IndexApplier::execute) driver.
//!
//! The per-chunk CRC32 the parser already enforces catches transit corruption
//! of the patch stream itself, but it cannot detect silent corruption of the
//! *resulting* `SqPack` files on disk. Square Enix's patch lists carry SHA1
//! hashes for the post-apply `.index` / `.dat` files (whole-file or split into
//! fixed-size blocks); [`HashVerifier`](crate::verify::HashVerifier) reads those files back from disk and
//! compares against caller-supplied expected hashes.
//!
//! This is a separate verification step the caller invokes **after**
//! [`apply_patch`](crate::ApplyConfig::apply_patch) or
//! [`IndexApplier::execute`](crate::index::IndexApplier::execute) returns
//! `Ok`. The library never bakes hash verification into the apply loop —
//! parsing the SE patch list to build the expected-hash input is the
//! consumer's responsibility (in practice, `gaveloc-patcher`).
//!
//! # Modes
//!
//! - **Whole-file** ([`ExpectedHash::Whole`](crate::verify::ExpectedHash::Whole)) — single hash over the entire
//!   file. Cheap to express; an opaque single failure for multi-GiB files.
//! - **Block-mode** ([`ExpectedHash::Blocks`](crate::verify::ExpectedHash::Blocks)) — file is split into
//!   fixed-size blocks (the SE patch list uses 50 MiB); one hash per block.
//!   Pinpoints *which* block is bad, so a user-facing repair flow can
//!   re-fetch a narrow range rather than the whole file.
//!
//! Only SHA-1 is supported — it is what Square Enix's patch list carries.
//! Should the format ever ship another algorithm, a new enum can wrap the
//! current shape as an additive change.
//!
//! # Example
//!
//! ```no_run
//! use zipatch_rs::verify::{ExpectedHash, HashVerifier, Sha1Digest};
//!
//! let report = HashVerifier::new()
//!     .expect(
//!         "/opt/ffxiv/game/sqpack/ffxiv/000000.win32.index",
//!         ExpectedHash::whole(Sha1Digest::new([0u8; 20])),
//!     )
//!     .execute()
//!     .unwrap();
//!
//! if !report.is_clean() {
//!     for (path, outcome) in report.failures() {
//!         eprintln!("{}: {outcome:?}", path.display());
//!     }
//! }
//! ```

use crate::VerifyResult as Result;
#[cfg(feature = "parallel-verify")]
use rayon::iter::{IntoParallelIterator, ParallelIterator};
use sha1::{Digest, Sha1};
use std::collections::BTreeMap;
use std::fmt;
use std::fs::File;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use tracing::{debug, debug_span, info, info_span, trace, warn};

const READ_BUF_CAPACITY: usize = 64 * 1024;
const SHA1_DIGEST_LEN: usize = 20;

/// A 20-byte SHA-1 digest.
///
/// Used throughout [`crate::verify`] to carry both expected and computed
/// hashes. The newtype guarantees the length-of-20 invariant by construction —
/// no runtime length check, no `Vec<u8>` allocation per digest.
///
/// [`Display`](fmt::Display) renders as 40 lowercase hex characters;
/// [`FromStr`] parses the same form (rejecting any input that is not exactly
/// 40 hex characters).
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Sha1Digest([u8; SHA1_DIGEST_LEN]);

impl Sha1Digest {
    /// Construct from a 20-byte array.
    #[must_use]
    pub const fn new(bytes: [u8; SHA1_DIGEST_LEN]) -> Self {
        Self(bytes)
    }

    /// Borrow the underlying 20-byte array.
    #[must_use]
    pub const fn as_bytes(&self) -> &[u8; SHA1_DIGEST_LEN] {
        &self.0
    }
}

impl From<[u8; SHA1_DIGEST_LEN]> for Sha1Digest {
    fn from(bytes: [u8; SHA1_DIGEST_LEN]) -> Self {
        Self(bytes)
    }
}

impl From<Sha1Digest> for [u8; SHA1_DIGEST_LEN] {
    fn from(d: Sha1Digest) -> Self {
        d.0
    }
}

impl fmt::Display for Sha1Digest {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for b in &self.0 {
            write!(f, "{b:02x}")?;
        }
        Ok(())
    }
}

/// Error returned when [`Sha1Digest::from_str`] is given a malformed input.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParseSha1DigestError;

impl fmt::Display for ParseSha1DigestError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("invalid SHA-1 digest: expected 40 lowercase or uppercase hex characters")
    }
}

impl std::error::Error for ParseSha1DigestError {}

impl FromStr for Sha1Digest {
    type Err = ParseSha1DigestError;

    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        if s.len() != SHA1_DIGEST_LEN * 2 {
            return Err(ParseSha1DigestError);
        }
        let mut out = [0u8; SHA1_DIGEST_LEN];
        let bytes = s.as_bytes();
        for (i, slot) in out.iter_mut().enumerate() {
            let hi = hex_nibble(bytes[i * 2])?;
            let lo = hex_nibble(bytes[i * 2 + 1])?;
            *slot = (hi << 4) | lo;
        }
        Ok(Self(out))
    }
}

fn hex_nibble(b: u8) -> std::result::Result<u8, ParseSha1DigestError> {
    match b {
        b'0'..=b'9' => Ok(b - b'0'),
        b'a'..=b'f' => Ok(b - b'a' + 10),
        b'A'..=b'F' => Ok(b - b'A' + 10),
        _ => Err(ParseSha1DigestError),
    }
}

/// Expected hash spec for a single file.
///
/// Either a single whole-file digest, or a fixed-block-size digest per block.
/// Block-mode is what FFXIV patch lists actually carry for `.dat` files
/// (50 MiB blocks), because it pinpoints *which* block is bad. Whole-file
/// mode is the natural fit for small files (e.g. `.index` files), where a
/// single mismatched bit is best surfaced as a single failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ExpectedHash {
    /// Whole-file mode: a single SHA-1 digest over the entire file.
    Whole {
        /// Expected digest.
        hash: Sha1Digest,
    },
    /// Block-mode: file is split into `block_size`-byte chunks, each hashed
    /// independently. The last block may be shorter than `block_size`.
    Blocks {
        /// Block size in bytes. Must be non-zero.
        block_size: u64,
        /// One digest per block, in file order.
        hashes: Vec<Sha1Digest>,
    },
}

impl ExpectedHash {
    /// Construct a whole-file SHA-1 spec.
    #[must_use]
    pub fn whole(hash: Sha1Digest) -> Self {
        ExpectedHash::Whole { hash }
    }

    /// Construct a block-mode SHA-1 spec.
    #[must_use]
    pub fn blocks(block_size: u64, hashes: Vec<Sha1Digest>) -> Self {
        ExpectedHash::Blocks { block_size, hashes }
    }

    fn validate(&self) -> Result<()> {
        match self {
            ExpectedHash::Whole { .. } => Ok(()),
            ExpectedHash::Blocks { block_size, .. } => {
                if *block_size == 0 {
                    return Err(crate::VerifyError::InvalidField {
                        context: "ExpectedHash::Blocks block_size must be non-zero",
                    });
                }
                Ok(())
            }
        }
    }
}

/// Per-file outcome of a [`HashVerifier::execute`] run.
///
/// `#[non_exhaustive]` so future outcome shapes (e.g. permission-denied
/// split out from generic IO, or a partial-read outcome distinct from
/// `IoError`) can be added without a `SemVer` break.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FileVerifyOutcome {
    /// File matched the expected hash (whole-file mode) or every block matched
    /// (block-mode).
    Match,
    /// Whole-file mode: the computed digest did not equal the expected digest.
    WholeMismatch {
        /// Expected digest.
        expected: Sha1Digest,
        /// Digest computed over the on-disk file.
        actual: Sha1Digest,
    },
    /// Block-mode: one or more blocks failed.
    ///
    /// `mismatched_blocks` holds the zero-based indices of blocks whose hash
    /// did not match, in ascending order. `expected_block_count` is the number
    /// of block hashes the caller supplied. `actual_block_count` is the number
    /// of blocks the file would contain at `block_size` (i.e. `ceil(size /
    /// block_size)`); a difference means the file is shorter or longer than
    /// the caller's expectation and every "extra" or "missing" block index is
    /// reported in `mismatched_blocks`.
    BlockMismatches {
        /// Zero-based indices of mismatched blocks, ascending.
        mismatched_blocks: Vec<usize>,
        /// Number of block hashes the caller supplied.
        expected_block_count: usize,
        /// Number of blocks the on-disk file would split into at `block_size`.
        actual_block_count: usize,
    },
    /// The file does not exist on disk.
    Missing,
    /// An I/O error occurred while reading the file. `kind` is the
    /// [`std::io::ErrorKind`] callers branch on (e.g. [`std::io::ErrorKind::PermissionDenied`]
    /// to prompt for elevation, [`std::io::ErrorKind::NotFound`] is reported
    /// as [`FileVerifyOutcome::Missing`] instead). `message` is the
    /// `std::io::Error` `Display` rendering, preserved as a string so the
    /// report stays `Clone + PartialEq` for downstream consumers.
    IoError {
        /// `std::io::ErrorKind` of the underlying error.
        kind: std::io::ErrorKind,
        /// Human-readable rendering of the error.
        message: String,
    },
}

/// Structured outcome of a [`HashVerifier::execute`] run.
///
/// One entry per file the caller registered via [`HashVerifier::expect`].
/// Iteration order is by [`PathBuf`] ordering (the underlying `BTreeMap`).
///
/// `#[non_exhaustive]`: future per-run aggregate fields (totals, elapsed
/// time, parallelism stats) may be added without a `SemVer` break.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct HashVerifyReport {
    /// Per-file outcome, keyed by the absolute path the caller registered.
    pub files: BTreeMap<PathBuf, FileVerifyOutcome>,
}

impl HashVerifyReport {
    /// `true` iff every registered file matched.
    #[must_use]
    pub fn is_clean(&self) -> bool {
        self.files
            .values()
            .all(|o| matches!(o, FileVerifyOutcome::Match))
    }

    /// Iterate the failing files (everything that is not [`FileVerifyOutcome::Match`]).
    pub fn failures(&self) -> impl Iterator<Item = (&Path, &FileVerifyOutcome)> {
        self.files
            .iter()
            .filter(|(_, o)| !matches!(o, FileVerifyOutcome::Match))
            .map(|(p, o)| (p.as_path(), o))
    }

    /// Count of failing files.
    #[must_use]
    pub fn failure_count(&self) -> usize {
        self.failures().count()
    }
}

/// Build up a set of `(path, expected_hash)` pairs, then [`Self::execute`] to
/// hash the on-disk files and compare against the expected values.
///
/// The verifier never writes — it opens each registered file read-only, hashes
/// it (whole-file or per-block), and produces a [`HashVerifyReport`]. Missing
/// files and I/O errors during read are recorded as per-file outcomes rather
/// than aborting the run — consumers want the full picture in a single pass.
///
/// # Error semantics
///
/// `execute` returns `Err` only for *programmer* errors detected up front
/// (e.g. a zero `block_size`). Filesystem errors against the registered paths
/// are captured per-file in [`FileVerifyOutcome::IoError`] /
/// [`FileVerifyOutcome::Missing`].
///
/// # Security
///
/// Files are opened via [`std::fs::File::open`], which follows symbolic
/// links on every platform `zipatch-rs` supports. The verifier itself never
/// writes — the worst-case outcome of a hostile symlink pointed at a file
/// outside the install root is an information-disclosure-via-hash: the
/// target file's SHA1 would appear in the report's
/// [`FileVerifyOutcome::WholeMismatch`] `actual` field.
///
/// If the caller derives registered paths from untrusted input (e.g. a
/// patch-list response from a server that could be tampered with), it is
/// **the caller's responsibility** to canonicalize the install root and
/// reject paths that escape it before passing them to [`Self::expect`].
/// `zipatch-rs` does not canonicalize or symlink-fence on the caller's
/// behalf, because the appropriate root depends on the consumer's install
/// layout.
#[derive(Debug, Default)]
pub struct HashVerifier {
    tasks: Vec<(PathBuf, ExpectedHash)>,
}

impl HashVerifier {
    /// Construct an empty verifier.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Register `path` with `expected`.
    ///
    /// Registering the same path twice with **identical** [`ExpectedHash`]
    /// values is a no-op (the second registration is silently absorbed at
    /// [`Self::execute`] time). Registering the same path twice with
    /// **different** [`ExpectedHash`] values is a programmer error and causes
    /// [`Self::execute`] to return [`crate::VerifyError::InvalidField`].
    /// The check fires at execute-time rather than here so the builder API
    /// stays infallible.
    #[must_use]
    pub fn expect(mut self, path: impl Into<PathBuf>, expected: ExpectedHash) -> Self {
        self.tasks.push((path.into(), expected));
        self
    }

    /// Hash each registered file and compare against its expected hash.
    ///
    /// Returns a [`HashVerifyReport`] describing every file. The report is
    /// always populated for every registered task — `is_clean()` distinguishes
    /// a fully-passing run from a failing one. See the struct docs for the
    /// error policy.
    ///
    /// # Errors
    ///
    /// Returns [`crate::VerifyError::InvalidField`] if any registered
    /// [`ExpectedHash`] is malformed (zero `block_size`). Filesystem errors
    /// are *not* returned here — they appear as
    /// [`FileVerifyOutcome::IoError`] / [`FileVerifyOutcome::Missing`] entries
    /// in the report.
    pub fn execute(self) -> Result<HashVerifyReport> {
        let span = info_span!(
            crate::tracing_schema::span_names::VERIFY_HASHES,
            files = self.tasks.len()
        );
        let _enter = span.enter();
        let started = std::time::Instant::now();

        for (_, exp) in &self.tasks {
            exp.validate()?;
        }

        let mut seen: BTreeMap<&Path, &ExpectedHash> = BTreeMap::new();
        for (path, exp) in &self.tasks {
            match seen.get(path.as_path()) {
                Some(prev) if *prev == exp => {}
                Some(_) => {
                    return Err(crate::VerifyError::InvalidField {
                        context: "HashVerifier: same path registered with conflicting ExpectedHash values",
                    });
                }
                None => {
                    seen.insert(path.as_path(), exp);
                }
            }
        }

        let mut report = HashVerifyReport::default();
        let parent = &span;
        // The chain body is identical for both branches; only the iterator
        // shape differs. Under `parallel-verify` the per-file work fans out
        // across rayon's pool; without it the verifier runs serially in the
        // calling thread and `rayon` is not a dependency.
        #[cfg(feature = "parallel-verify")]
        let task_iter = self.tasks.into_par_iter();
        #[cfg(not(feature = "parallel-verify"))]
        let task_iter = self.tasks.into_iter();
        let results: Vec<(PathBuf, FileVerifyOutcome, u64)> = task_iter
            .map(|(path, expected)| {
                parent.in_scope(|| {
                    let sub = debug_span!(
                        crate::tracing_schema::span_names::VERIFY_FILE,
                        path = %path.display()
                    );
                    let _e = sub.enter();
                    let mut scratch = vec![0u8; READ_BUF_CAPACITY];
                    let (outcome, bytes) = verify_one(&path, &expected, &mut scratch);
                    match &outcome {
                        FileVerifyOutcome::Match => {
                            debug!(bytes_hashed = bytes, "verify_hashes: file match");
                        }
                        FileVerifyOutcome::Missing => {
                            warn!("verify_hashes: file missing");
                        }
                        FileVerifyOutcome::IoError { kind, message } => {
                            warn!(?kind, error = %message, "verify_hashes: io error during hash");
                        }
                        FileVerifyOutcome::WholeMismatch { .. } => {
                            debug!(bytes_hashed = bytes, "verify_hashes: whole-file mismatch");
                        }
                        FileVerifyOutcome::BlockMismatches {
                            mismatched_blocks, ..
                        } => {
                            debug!(
                                bytes_hashed = bytes,
                                bad_blocks = mismatched_blocks.len(),
                                "verify_hashes: block-mode mismatches"
                            );
                        }
                    }
                    (path, outcome, bytes)
                })
            })
            .collect();

        let mut total_bytes: u64 = 0;
        for (path, outcome, bytes) in results {
            total_bytes += bytes;
            report.files.insert(path, outcome);
        }

        let failures = report.failure_count();
        info!(
            files = report.files.len(),
            failures,
            bytes_hashed = total_bytes,
            elapsed_ms = started.elapsed().as_millis() as u64,
            "verify_hashes: run complete"
        );
        Ok(report)
    }
}

fn verify_one(
    path: &Path,
    expected: &ExpectedHash,
    scratch: &mut [u8],
) -> (FileVerifyOutcome, u64) {
    let mut file = match File::open(path) {
        Ok(f) => f,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            return (FileVerifyOutcome::Missing, 0);
        }
        Err(e) => {
            return (
                FileVerifyOutcome::IoError {
                    kind: e.kind(),
                    message: e.to_string(),
                },
                0,
            );
        }
    };

    match expected {
        ExpectedHash::Whole { hash } => match hash_whole(&mut file, scratch) {
            Ok((actual, n)) => {
                if actual == *hash {
                    (FileVerifyOutcome::Match, n)
                } else {
                    (
                        FileVerifyOutcome::WholeMismatch {
                            expected: *hash,
                            actual,
                        },
                        n,
                    )
                }
            }
            Err(e) => (
                FileVerifyOutcome::IoError {
                    kind: e.kind(),
                    message: e.to_string(),
                },
                0,
            ),
        },
        ExpectedHash::Blocks { block_size, hashes } => {
            hash_blocks(&mut file, *block_size, hashes, scratch)
        }
    }
}

fn finalize(hasher: Sha1) -> Sha1Digest {
    let out = hasher.finalize();
    let mut bytes = [0u8; SHA1_DIGEST_LEN];
    bytes.copy_from_slice(&out);
    Sha1Digest(bytes)
}

fn hash_whole<R: Read>(reader: &mut R, scratch: &mut [u8]) -> std::io::Result<(Sha1Digest, u64)> {
    let mut hasher = Sha1::new();
    let mut total: u64 = 0;
    loop {
        let n = reader.read(scratch)?;
        if n == 0 {
            break;
        }
        hasher.update(&scratch[..n]);
        total += n as u64;
        trace!(chunk_bytes = n, "verify_hashes: whole-file chunk");
    }
    Ok((finalize(hasher), total))
}

fn hash_blocks<R: Read>(
    reader: &mut R,
    block_size: u64,
    expected: &[Sha1Digest],
    scratch: &mut [u8],
) -> (FileVerifyOutcome, u64) {
    // Stream-hash one block at a time so memory stays O(scratch) regardless of
    // file size.
    let mut mismatched: Vec<usize> = Vec::new();
    let mut block_idx: usize = 0;
    let mut total_bytes: u64 = 0;
    let mut hasher = Sha1::new();
    let mut block_bytes_remaining: u64 = block_size;
    let mut block_had_bytes = false;

    loop {
        // Cap reads so we never spill across a block boundary.
        let want = block_bytes_remaining.min(scratch.len() as u64) as usize;
        if want == 0 {
            finish_and_compare(&mut hasher, block_idx, expected, &mut mismatched);
            block_idx += 1;
            block_bytes_remaining = block_size;
            block_had_bytes = false;
            continue;
        }
        let n = match reader.read(&mut scratch[..want]) {
            Ok(n) => n,
            Err(e) => {
                return (
                    FileVerifyOutcome::IoError {
                        kind: e.kind(),
                        message: e.to_string(),
                    },
                    total_bytes,
                );
            }
        };
        if n == 0 {
            if block_had_bytes {
                // Trailing short block at EOF — finalize and compare.
                finish_and_compare(&mut hasher, block_idx, expected, &mut mismatched);
                block_idx += 1;
            }
            break;
        }
        hasher.update(&scratch[..n]);
        total_bytes += n as u64;
        block_bytes_remaining -= n as u64;
        block_had_bytes = true;
        trace!(block_idx, chunk_bytes = n, "verify_hashes: block chunk");
    }

    // File ran out before we hit `expected.len()` blocks — flag each missing
    // index as a mismatch. Conversely, if more blocks fit than the caller
    // supplied, every excess block index past `expected.len()` has already
    // been flagged inside `finish_and_compare`.
    for missing in block_idx..expected.len() {
        mismatched.push(missing);
    }

    let actual_block_count = block_idx;
    let expected_block_count = expected.len();
    let outcome = if mismatched.is_empty() && actual_block_count == expected_block_count {
        FileVerifyOutcome::Match
    } else {
        mismatched.sort_unstable();
        mismatched.dedup();
        FileVerifyOutcome::BlockMismatches {
            mismatched_blocks: mismatched,
            expected_block_count,
            actual_block_count,
        }
    };
    (outcome, total_bytes)
}

fn finish_and_compare(
    hasher: &mut Sha1,
    block_idx: usize,
    expected: &[Sha1Digest],
    mismatched: &mut Vec<usize>,
) {
    // Replace the in-progress hasher with a fresh one, taking ownership of the
    // finished state so we can finalize it without disturbing the loop.
    let finished = std::mem::replace(hasher, Sha1::new());
    let digest = finalize(finished);
    match expected.get(block_idx) {
        Some(want) if *want == digest => {}
        _ => mismatched.push(block_idx),
    }
}

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

    fn sha1_of(bytes: &[u8]) -> Sha1Digest {
        let mut h = Sha1::new();
        h.update(bytes);
        finalize(h)
    }

    fn write_tmp(bytes: &[u8]) -> (tempfile::TempDir, PathBuf) {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("f.bin");
        let mut f = File::create(&path).unwrap();
        f.write_all(bytes).unwrap();
        f.sync_all().unwrap();
        (dir, path)
    }

    #[test]
    fn report_is_clean_when_empty() {
        let r = HashVerifyReport::default();
        assert!(r.is_clean());
        assert_eq!(r.failure_count(), 0);
        assert_eq!(r.failures().count(), 0);
    }

    #[test]
    fn whole_sha1_match() {
        let payload = b"hello world".repeat(1000);
        let (_d, path) = write_tmp(&payload);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(sha1_of(&payload)))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    #[test]
    fn whole_sha1_mismatch() {
        let (_d, path) = write_tmp(b"abc");
        let bad = Sha1Digest::new([0u8; 20]);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(bad))
            .execute()
            .unwrap();
        assert!(!report.is_clean());
        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::WholeMismatch { expected, actual } => {
                assert_eq!(*expected, bad);
                assert_eq!(*actual, sha1_of(b"abc"));
            }
            other => panic!("expected WholeMismatch, got {other:?}"),
        }
    }

    #[test]
    fn block_mode_match() {
        let block_size: u64 = 256;
        let mut payload = Vec::new();
        for i in 0..5u8 {
            payload.extend(std::iter::repeat_n(i, block_size as usize));
        }
        // Add a short trailing block.
        payload.extend_from_slice(&[0xAB; 17]);

        let hashes: Vec<Sha1Digest> = payload.chunks(block_size as usize).map(sha1_of).collect();
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, hashes.clone()))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
        assert_eq!(hashes.len(), 6); // 5 full + 1 short
    }

    #[test]
    fn block_mode_specific_block_mismatch() {
        let block_size: u64 = 128;
        let mut payload = vec![0u8; (block_size as usize) * 4];
        // Corrupt block 2 by writing to the on-disk file *after* computing the
        // expected hashes from the clean payload.
        let clean = payload.clone();
        payload[(block_size as usize) * 2 + 7] = 0xFF;

        let expected: Vec<Sha1Digest> = clean.chunks(block_size as usize).map(sha1_of).collect();
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, expected))
            .execute()
            .unwrap();
        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::BlockMismatches {
                mismatched_blocks,
                expected_block_count,
                actual_block_count,
            } => {
                assert_eq!(mismatched_blocks, &vec![2]);
                assert_eq!(*expected_block_count, 4);
                assert_eq!(*actual_block_count, 4);
            }
            other => panic!("expected BlockMismatches, got {other:?}"),
        }
    }

    #[test]
    fn missing_file_reported() {
        let dir = tempfile::tempdir().unwrap();
        let missing = dir.path().join("does-not-exist");
        let report = HashVerifier::new()
            .expect(&missing, ExpectedHash::whole(Sha1Digest::new([0u8; 20])))
            .execute()
            .unwrap();
        assert_eq!(
            report.files.get(&missing).unwrap(),
            &FileVerifyOutcome::Missing
        );
        assert!(!report.is_clean());
    }

    #[test]
    fn block_mode_file_shorter_than_expected_flags_trailing_missing_blocks() {
        let block_size: u64 = 64;
        // On-disk file: 2 full blocks. Caller expects 4 blocks of hashes.
        let payload = vec![0u8; (block_size as usize) * 2];
        let expected: Vec<Sha1Digest> = payload
            .chunks(block_size as usize)
            .map(sha1_of)
            .chain(std::iter::repeat_n(Sha1Digest::new([0u8; 20]), 2))
            .collect();
        assert_eq!(expected.len(), 4);
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, expected))
            .execute()
            .unwrap();
        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::BlockMismatches {
                mismatched_blocks,
                expected_block_count,
                actual_block_count,
            } => {
                assert_eq!(*expected_block_count, 4);
                assert_eq!(*actual_block_count, 2);
                assert_eq!(mismatched_blocks, &vec![2, 3]);
            }
            other => panic!("expected BlockMismatches, got {other:?}"),
        }
    }

    #[test]
    fn block_mode_file_longer_than_expected_flags_extra_blocks() {
        let block_size: u64 = 32;
        let payload = vec![0u8; (block_size as usize) * 4];
        // Caller supplies only 2 of 4 block hashes (matching the first two).
        let expected: Vec<Sha1Digest> = payload
            .chunks(block_size as usize)
            .take(2)
            .map(sha1_of)
            .collect();
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, expected))
            .execute()
            .unwrap();
        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::BlockMismatches {
                mismatched_blocks,
                expected_block_count,
                actual_block_count,
            } => {
                assert_eq!(*expected_block_count, 2);
                assert_eq!(*actual_block_count, 4);
                assert_eq!(mismatched_blocks, &vec![2, 3]);
            }
            other => panic!("expected BlockMismatches, got {other:?}"),
        }
    }

    #[test]
    fn empty_file_whole_mode_matches_sha1_of_empty() {
        let (_d, path) = write_tmp(&[]);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(sha1_of(&[])))
            .execute()
            .unwrap();
        assert!(report.is_clean());
    }

    #[test]
    fn empty_file_block_mode_matches_zero_blocks() {
        // Zero blocks expected; zero blocks present.
        let (_d, path) = write_tmp(&[]);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(1024, vec![]))
            .execute()
            .unwrap();
        assert!(report.is_clean());
    }

    #[test]
    fn zero_block_size_is_rejected_up_front() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("any");
        let err = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(0, vec![]))
            .execute()
            .unwrap_err();
        assert!(
            matches!(err, crate::VerifyError::InvalidField { context } if context.contains("block_size")),
            "got {err:?}"
        );
    }

    #[test]
    fn block_mode_block_size_exceeds_read_buf_capacity_match() {
        // Each block is larger than READ_BUF_CAPACITY (64 KiB) so the inner
        // read loop must iterate multiple times before `want == 0` triggers
        // the finalize branch. Use 200 KiB blocks: 3 full + 1 short trailing.
        let block_size: u64 = 200 * 1024;
        let mut payload = Vec::with_capacity((block_size as usize) * 3 + 17);
        for i in 0..3u8 {
            payload.extend(std::iter::repeat_n(i.wrapping_mul(31), block_size as usize));
        }
        payload.extend_from_slice(&[0xCD; 17]);

        let hashes: Vec<Sha1Digest> = payload.chunks(block_size as usize).map(sha1_of).collect();
        assert_eq!(hashes.len(), 4);
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, hashes))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    #[test]
    fn block_mode_block_size_exceeds_read_buf_capacity_mismatch() {
        // Same shape as the match test, but corrupt a byte deep inside block 1
        // (past the first 64 KiB read) so the mismatch only surfaces if the
        // multi-read accumulation inside a single block works.
        let block_size: u64 = 200 * 1024;
        let mut payload = Vec::with_capacity((block_size as usize) * 3);
        for i in 0..3u8 {
            payload.extend(std::iter::repeat_n(i.wrapping_mul(17), block_size as usize));
        }
        let clean = payload.clone();
        // Corrupt block 1 at offset 150 KiB (well past the first 64 KiB read).
        payload[(block_size as usize) + 150 * 1024] ^= 0xFF;

        let expected: Vec<Sha1Digest> = clean.chunks(block_size as usize).map(sha1_of).collect();
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, expected))
            .execute()
            .unwrap();
        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::BlockMismatches {
                mismatched_blocks,
                expected_block_count,
                actual_block_count,
            } => {
                assert_eq!(mismatched_blocks, &vec![1]);
                assert_eq!(*expected_block_count, 3);
                assert_eq!(*actual_block_count, 3);
            }
            other => panic!("expected BlockMismatches, got {other:?}"),
        }
    }

    #[test]
    fn block_mode_single_short_block_distinguishes_from_empty_file() {
        // File shorter than `block_size` with exactly one expected hash. This
        // exercises the trailing-short-block finalize path when the *only*
        // block is short — distinct from the empty-file (zero blocks) path.
        let block_size: u64 = 200 * 1024;
        let payload = vec![0x7Eu8; 1000]; // far less than block_size
        let hashes = vec![sha1_of(&payload)];
        let (_d, path) = write_tmp(&payload);

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, hashes))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    #[cfg(target_family = "unix")]
    #[test]
    fn permission_denied_open_reports_io_error_with_kind() {
        use std::os::unix::fs::PermissionsExt;

        let (_d, path) = write_tmp(b"forbidden");
        // Drop read permission. TempDir cleanup uses unlink (not
        // open-for-read), so 0o000 on the file itself does not block cleanup.
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o000)).unwrap();

        // Skip when running as root — chmod 0o000 is bypassed by
        // CAP_DAC_OVERRIDE, so root can still open the file. Probe via
        // File::open: if the open succeeds against 0o000, the running user
        // has the cap and the test would not exercise the IoError path.
        if File::open(&path).is_ok() {
            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
            eprintln!("skipping: running with CAP_DAC_OVERRIDE, chmod 0o000 does not block open");
            return;
        }

        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(Sha1Digest::new([0u8; 20])))
            .execute()
            .unwrap();

        // Restore so the TempDir cleanup is robust regardless of platform quirks.
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();

        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::IoError { kind, message } => {
                assert_eq!(*kind, std::io::ErrorKind::PermissionDenied, "got {kind:?}");
                assert!(!message.is_empty(), "message should carry the error text");
            }
            other => panic!("expected IoError with PermissionDenied kind, got {other:?}"),
        }
    }

    // Note: the mid-read `Err` branch in `hash_blocks` (the second `IoError`
    // construction site) is not directly tested. Provoking a mid-read IO
    // error deterministically requires substituting a custom `Read` impl for
    // `File`, which the current `hash_blocks` signature does not accept. The
    // permission-denied test above covers the `IoError` construction shape
    // (kind + message), and the open-time and mid-read arms are byte-identical.

    #[test]
    fn duplicate_identical_registration_is_noop() {
        let (_d, path) = write_tmp(b"abc");
        let expected = ExpectedHash::whole(sha1_of(b"abc"));
        let report = HashVerifier::new()
            .expect(&path, expected.clone())
            .expect(&path, expected)
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
        assert_eq!(report.files.len(), 1);
    }

    #[test]
    fn duplicate_conflicting_registration_errors() {
        let (_d, path) = write_tmp(b"abc");
        let err = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(sha1_of(b"abc")))
            .expect(&path, ExpectedHash::whole(Sha1Digest::new([0u8; 20])))
            .execute()
            .unwrap_err();
        assert!(
            matches!(err, crate::VerifyError::InvalidField { context } if context.contains("conflicting")),
            "got {err:?}"
        );
    }

    #[test]
    fn failures_iter_excludes_matches() {
        let (_d1, ok) = write_tmp(b"a");
        let (_d2, bad) = write_tmp(b"b");
        let report = HashVerifier::new()
            .expect(&ok, ExpectedHash::whole(sha1_of(b"a")))
            .expect(&bad, ExpectedHash::whole(Sha1Digest::new([0u8; 20])))
            .execute()
            .unwrap();
        let fails: Vec<_> = report.failures().collect();
        assert_eq!(fails.len(), 1);
        assert_eq!(fails[0].0, bad.as_path());
    }

    /// Reader that yields `n_ok` bytes of zeros, then fails on the next read
    /// with the given `ErrorKind`. Used to exercise the mid-read IO error
    /// branches in `hash_whole` and `hash_blocks`.
    struct FailAfter {
        remaining_ok: usize,
        kind: std::io::ErrorKind,
    }

    impl Read for FailAfter {
        fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
            if self.remaining_ok == 0 {
                return Err(std::io::Error::new(self.kind, "injected"));
            }
            let n = self.remaining_ok.min(buf.len());
            buf[..n].fill(0);
            self.remaining_ok -= n;
            Ok(n)
        }
    }

    #[test]
    fn hash_whole_propagates_mid_read_io_error() {
        let mut reader = FailAfter {
            remaining_ok: 32,
            kind: std::io::ErrorKind::Other,
        };
        let mut scratch = vec![0u8; 16];
        let err = hash_whole(&mut reader, &mut scratch).unwrap_err();
        assert_eq!(err.kind(), std::io::ErrorKind::Other);
    }

    #[test]
    fn hash_blocks_surfaces_mid_read_io_error_as_outcome() {
        let mut reader = FailAfter {
            remaining_ok: 40,
            kind: std::io::ErrorKind::ConnectionAborted,
        };
        let mut scratch = vec![0u8; 16];
        let expected = vec![Sha1Digest::new([0u8; 20]); 4];
        let (outcome, bytes) = hash_blocks(&mut reader, 64, &expected, &mut scratch);
        match outcome {
            FileVerifyOutcome::IoError { kind, .. } => {
                assert_eq!(kind, std::io::ErrorKind::ConnectionAborted);
            }
            other => panic!("expected IoError outcome, got {other:?}"),
        }
        assert_eq!(
            bytes, 40,
            "bytes hashed up to the failure should be reported"
        );
    }

    // --- execute() with zero tasks ---

    #[test]
    fn execute_with_no_tasks_returns_clean_empty_report() {
        let report = HashVerifier::new().execute().unwrap();
        assert!(report.is_clean());
        assert_eq!(report.files.len(), 0);
        assert_eq!(report.failure_count(), 0);
    }

    // --- HashVerifyReport invariants ---

    #[test]
    fn report_nonempty_all_match_is_clean() {
        let (_d1, p1) = write_tmp(b"one");
        let (_d2, p2) = write_tmp(b"two");
        let report = HashVerifier::new()
            .expect(&p1, ExpectedHash::whole(sha1_of(b"one")))
            .expect(&p2, ExpectedHash::whole(sha1_of(b"two")))
            .execute()
            .unwrap();
        assert_eq!(report.files.len(), 2);
        assert!(report.is_clean());
        assert_eq!(report.failure_count(), 0);
        assert_eq!(report.failures().count(), 0);
    }

    #[test]
    fn failure_count_equals_failures_iter_count() {
        let (_d1, ok) = write_tmp(b"good");
        let (_d2, bad1) = write_tmp(b"bad1");
        let (_d3, bad2) = write_tmp(b"bad2");
        let report = HashVerifier::new()
            .expect(&ok, ExpectedHash::whole(sha1_of(b"good")))
            .expect(&bad1, ExpectedHash::whole(Sha1Digest::new([0u8; 20])))
            .expect(&bad2, ExpectedHash::whole(Sha1Digest::new([0u8; 20])))
            .execute()
            .unwrap();
        assert_eq!(report.failure_count(), report.failures().count());
        assert_eq!(report.failure_count(), 2);
    }

    #[test]
    fn report_files_iteration_order_is_by_path() {
        // BTreeMap guarantees sorted-key iteration; verify the contract holds
        // by registering paths out of lexicographic order and checking order.
        let dir = tempfile::tempdir().unwrap();
        let pb = dir.path().join("b.bin");
        let pa = dir.path().join("a.bin");
        let pc = dir.path().join("c.bin");
        for p in [&pb, &pa, &pc] {
            let mut f = File::create(p).unwrap();
            f.write_all(b"x").unwrap();
        }
        let report = HashVerifier::new()
            .expect(&pb, ExpectedHash::whole(sha1_of(b"x")))
            .expect(&pa, ExpectedHash::whole(sha1_of(b"x")))
            .expect(&pc, ExpectedHash::whole(sha1_of(b"x")))
            .execute()
            .unwrap();
        let keys: Vec<&PathBuf> = report.files.keys().collect();
        assert_eq!(keys[0], &pa);
        assert_eq!(keys[1], &pb);
        assert_eq!(keys[2], &pc);
    }

    // --- FileVerifyOutcome derive sanity ---

    #[test]
    fn file_verify_outcome_clone_and_partialeq() {
        let outcomes = [
            FileVerifyOutcome::Match,
            FileVerifyOutcome::Missing,
            FileVerifyOutcome::WholeMismatch {
                expected: Sha1Digest::new([0u8; 20]),
                actual: Sha1Digest::new([1u8; 20]),
            },
            FileVerifyOutcome::BlockMismatches {
                mismatched_blocks: vec![0, 2],
                expected_block_count: 3,
                actual_block_count: 3,
            },
            FileVerifyOutcome::IoError {
                kind: std::io::ErrorKind::Other,
                message: "oops".to_string(),
            },
        ];
        for o in &outcomes {
            let cloned = o.clone();
            assert_eq!(o, &cloned, "Clone+PartialEq round-trip failed for {o:?}");
        }
        assert_ne!(
            FileVerifyOutcome::Match,
            FileVerifyOutcome::Missing,
            "distinct variants must not compare equal"
        );
    }

    // --- HashVerifier::expect builder semantics ---

    #[test]
    fn many_chained_expects_all_evaluated() {
        let dir = tempfile::tempdir().unwrap();
        let n = 10usize;
        let mut builder = HashVerifier::new();
        let mut paths = Vec::with_capacity(n);
        for i in 0..n {
            let p = dir.path().join(format!("f{i}.bin"));
            let mut f = File::create(&p).unwrap();
            f.write_all(&[i as u8]).unwrap();
            builder = builder.expect(&p, ExpectedHash::whole(sha1_of(&[i as u8])));
            paths.push(p);
        }
        let report = builder.execute().unwrap();
        assert_eq!(report.files.len(), n);
        assert!(report.is_clean(), "got {report:?}");
    }

    #[test]
    fn whole_then_blocks_registration_for_same_path_conflicts() {
        let (_d, path) = write_tmp(b"hi");
        let err = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(sha1_of(b"hi")))
            .expect(&path, ExpectedHash::blocks(2, vec![sha1_of(b"hi")]))
            .execute()
            .unwrap_err();
        assert!(
            matches!(err, crate::VerifyError::InvalidField { context } if context.contains("conflicting")),
            "got {err:?}"
        );
    }

    // --- Block boundary conditions ---

    #[test]
    fn block_mode_exact_multiple_of_block_size_no_trailing() {
        let block_size: u64 = 64;
        let payload = vec![0xAAu8; (block_size as usize) * 3];
        let hashes: Vec<Sha1Digest> = payload.chunks(block_size as usize).map(sha1_of).collect();
        assert_eq!(hashes.len(), 3);
        let (_d, path) = write_tmp(&payload);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, hashes))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    #[test]
    fn block_mode_n_blocks_plus_one_byte_trailing() {
        let block_size: u64 = 64;
        let mut payload = vec![0xBBu8; (block_size as usize) * 3];
        payload.push(0xCC);
        let hashes: Vec<Sha1Digest> = payload.chunks(block_size as usize).map(sha1_of).collect();
        assert_eq!(hashes.len(), 4);
        let (_d, path) = write_tmp(&payload);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, hashes))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    #[test]
    fn block_mode_single_byte_file() {
        let (_d, path) = write_tmp(&[0x42]);
        let hashes = vec![sha1_of(&[0x42])];
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(1024, hashes))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    #[test]
    fn block_mode_block_size_one_each_byte_is_own_block() {
        let payload = b"abc";
        let hashes: Vec<Sha1Digest> = payload.iter().map(|b| sha1_of(&[*b])).collect();
        assert_eq!(hashes.len(), 3);
        let (_d, path) = write_tmp(payload);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(1, hashes))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    // --- BlockHasher state isolation between blocks ---

    #[test]
    fn block_hasher_state_does_not_bleed_between_identical_content_blocks() {
        // Both blocks contain the same bytes. Expected[0] matches; expected[1]
        // is deliberately wrong. If state bled, block 1's hash would equal
        // block 0's hash (which happens to equal expected[0]) — masking the
        // mismatch. A correct implementation resets the hasher between blocks,
        // so expected[1] != actual[1] and block 1 is flagged.
        let block_size: u64 = 32;
        let content = vec![0x5Au8; block_size as usize];
        let payload: Vec<u8> = content.iter().chain(content.iter()).copied().collect();
        let correct_hash = sha1_of(&content);
        let wrong_hash = Sha1Digest::new([0u8; 20]);
        assert_ne!(correct_hash, wrong_hash);
        let hashes = vec![correct_hash, wrong_hash];
        let (_d, path) = write_tmp(&payload);
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::blocks(block_size, hashes))
            .execute()
            .unwrap();
        match report.files.get(&path).unwrap() {
            FileVerifyOutcome::BlockMismatches {
                mismatched_blocks,
                expected_block_count,
                actual_block_count,
            } => {
                assert_eq!(mismatched_blocks, &vec![1]);
                assert_eq!(*expected_block_count, 2);
                assert_eq!(*actual_block_count, 2);
            }
            other => panic!("expected BlockMismatches for block 1 only, got {other:?}"),
        }
    }

    // --- Path edge cases ---

    #[test]
    fn path_with_spaces_and_utf8() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("file with spaces café.bin");
        let mut f = File::create(&path).unwrap();
        f.write_all(b"data").unwrap();
        f.sync_all().unwrap();
        let report = HashVerifier::new()
            .expect(&path, ExpectedHash::whole(sha1_of(b"data")))
            .execute()
            .unwrap();
        assert!(report.is_clean(), "got {report:?}");
    }

    // --- Parallel fan-out determinism ---

    // 32 files (above rayon's typical split threshold): half match, half don't.
    // Verifies that the parallel collector produces a sorted BTreeMap with the
    // right failure count, and that two runs on equivalent input are identical.
    #[test]
    fn parallel_fan_out_report_is_deterministic_and_sorted() {
        const N: usize = 32;
        let dir = tempfile::tempdir().unwrap();
        let mut builder = HashVerifier::new();
        let mut expected_failures = 0usize;
        let mut paths: Vec<PathBuf> = Vec::with_capacity(N);
        for i in 0..N {
            let p = dir.path().join(format!("file_{i:03}.bin"));
            let payload = vec![i as u8; 1024 * 1024];
            let mut f = File::create(&p).unwrap();
            f.write_all(&payload).unwrap();
            f.sync_all().unwrap();
            let hash = if i % 2 == 0 {
                sha1_of(&payload)
            } else {
                expected_failures += 1;
                Sha1Digest::new([0u8; 20])
            };
            builder = builder.expect(&p, ExpectedHash::whole(hash));
            paths.push(p);
        }

        let run1 = builder.execute().unwrap();
        assert_eq!(run1.files.len(), N);
        assert_eq!(run1.failure_count(), expected_failures);

        let keys: Vec<&PathBuf> = run1.files.keys().collect();
        for w in keys.windows(2) {
            assert!(w[0] < w[1], "BTreeMap keys out of order: {w:?}");
        }

        // Rebuild an equivalent verifier to check idempotence.
        let mut builder2 = HashVerifier::new();
        for (i, p) in paths.iter().enumerate() {
            let payload = vec![i as u8; 1024 * 1024];
            let hash = if i % 2 == 0 {
                sha1_of(&payload)
            } else {
                Sha1Digest::new([0u8; 20])
            };
            builder2 = builder2.expect(p, ExpectedHash::whole(hash));
        }
        let run2 = builder2.execute().unwrap();
        assert_eq!(run1, run2, "two equivalent runs produced different reports");
    }

    // Registers files in a shuffled (non-lexicographic) order and asserts that
    // the report's BTreeMap keys are still sorted, guarding against any future
    // replacement of BTreeMap with a hash-map in the merge loop.
    #[test]
    fn parallel_fan_out_shuffled_registration_order_report_sorted() {
        const N: usize = 32;
        let dir = tempfile::tempdir().unwrap();
        // Shuffled index sequence: reverse-order registration.
        let indices: Vec<usize> = (0..N).rev().collect();
        let mut builder = HashVerifier::new();
        let mut paths: Vec<PathBuf> = Vec::with_capacity(N);
        // Pre-create all files so paths vec is in 0..N order for comparison.
        for i in 0..N {
            let p = dir.path().join(format!("z_{i:03}.bin"));
            let mut f = File::create(&p).unwrap();
            f.write_all(&[i as u8]).unwrap();
            f.sync_all().unwrap();
            paths.push(p);
        }
        // Register in reverse order so the task list is not lexicographically sorted.
        for &i in &indices {
            let payload = [i as u8];
            builder = builder.expect(&paths[i], ExpectedHash::whole(sha1_of(&payload)));
        }
        let report = builder.execute().unwrap();
        assert_eq!(report.files.len(), N);
        assert!(report.is_clean(), "all files should match; got {report:?}");
        let keys: Vec<&PathBuf> = report.files.keys().collect();
        for w in keys.windows(2) {
            assert!(w[0] < w[1], "report keys not sorted: {w:?}");
        }
    }

    // --- Sha1Digest newtype ---

    #[test]
    fn sha1_digest_display_is_40_lowercase_hex() {
        let d = Sha1Digest::new([
            0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d,
            0x0e, 0x0f, 0xfe, 0xed, 0xfa, 0xce,
        ]);
        let s = d.to_string();
        assert_eq!(s.len(), 40);
        assert_eq!(s, "000102030405060708090a0b0c0d0e0ffeedface");
    }

    #[test]
    fn sha1_digest_from_str_roundtrip() {
        let bytes = [
            0xde, 0xad, 0xbe, 0xef, 0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x11, 0x22,
            0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
        ];
        let d = Sha1Digest::new(bytes);
        let s = d.to_string();
        let parsed: Sha1Digest = s.parse().unwrap();
        assert_eq!(parsed, d);
        assert_eq!(parsed.as_bytes(), &bytes);
    }

    #[test]
    fn sha1_digest_from_str_accepts_uppercase() {
        let parsed: Sha1Digest = "DEADBEEF000102030405060708090A0B0C0D0E0F".parse().unwrap();
        let expected = Sha1Digest::new([
            0xde, 0xad, 0xbe, 0xef, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09,
            0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
        ]);
        assert_eq!(parsed, expected);
    }

    #[test]
    fn sha1_digest_from_str_rejects_wrong_length() {
        assert!("abc".parse::<Sha1Digest>().is_err());
        assert!("0".repeat(39).parse::<Sha1Digest>().is_err());
        assert!("0".repeat(41).parse::<Sha1Digest>().is_err());
    }

    #[test]
    fn sha1_digest_from_str_rejects_non_hex() {
        assert!("g".repeat(40).parse::<Sha1Digest>().is_err());
        let mut s = "0".repeat(39);
        s.push('z');
        assert!(s.parse::<Sha1Digest>().is_err());
    }

    #[test]
    fn sha1_digest_is_copy_and_eq() {
        let d = Sha1Digest::new([7u8; 20]);
        let copy = d;
        assert_eq!(copy, d);
        assert_eq!(d, Sha1Digest::new([7u8; 20]));
    }
}