fix(consensus): clarify AVX validation evidence

Expose the reducer backend in tests, document scratch-buffer consumption, and make custody paths and Criterion scope portable.

Author: metaphorics

crates/consensus/src/sha256d64.rs

@@ -358,8 +358,12 @@ mod tests {
     #[test]
     fn avx2_matches_independent_sha256d_vectors() {
         let Some(avx2) = detect_avx2() else {
+            eprintln!(
+                "test avx2_matches_independent_sha256d_vectors: AVX2 unavailable — skipping AVX2 vector test"
+            );
             return;
         };
+        eprintln!("test avx2_matches_independent_sha256d_vectors: running with AVX2 backend");
         let mut input = [[0_u8; 64]; 8];
         for (lane, message) in input.iter_mut().enumerate() {
             let lane = match u8::try_from(lane) {
@@ -387,8 +391,12 @@ mod tests {
     #[test]
     fn avx2_matches_literal_zero_message_digest() {
         let Some(avx2) = detect_avx2() else {
+            eprintln!(
+                "test avx2_matches_literal_zero_message_digest: AVX2 unavailable — skipping AVX2 zero-message test"
+            );
             return;
         };
+        eprintln!("test avx2_matches_literal_zero_message_digest: running with AVX2 backend");
         let input = [[0_u8; 64]; 8];
         let mut output = [[0_u8; 32]; 8];
         avx2.transform_8way(&input, &mut output);

crates/consensus/src/verify_block.rs

@@ -146,6 +146,11 @@ fn verify_merkle_root_with_txids(
 /// Computes the merkle root from caller-supplied transaction IDs and compares
 /// it to the block header. Mutation is intentionally ignored here; the later
 /// consensus path owns the mutation check and its error precedence.
+///
+/// On a nonempty successful reduction the mutable `txids` scratch buffer is
+/// consumed and reduced in place to a single element (the root). Returns
+/// `false` for empty input, encoding failure, or a root that does not match
+/// the block header's merkle root.
 #[doc(hidden)]
 pub fn block_merkle_root_matches_txids(block: &bitcoin::Block, txids: &mut Vec<Txid>) -> bool {
     match merkle_root_and_mutation(txids) {
@@ -269,6 +274,7 @@ mod tests {
     };
     use crate::ConsensusError;
     use crate::rust_path::TipState;
+    use crate::sha256d64::detect_avx2;
 
     #[test]
     fn valid_single_coinbase_block_passes() {
@@ -548,8 +554,23 @@ mod tests {
         }
     }
 
+    /// Reports whether `candidate_merkle` dispatches to the AVX2 or scalar
+    /// `SHA256d` backend. Does not assert AVX2 availability — scalar-only hosts
+    /// and generic runners remain supported.
+    fn candidate_reducer_backend() -> &'static str {
+        if detect_avx2().is_some() {
+            "avx2"
+        } else {
+            "scalar"
+        }
+    }
+
     #[test]
     fn avx2_matches_scalar_for_all_leaf_counts_0_to_129() {
+        eprintln!(
+            "avx2_matches_scalar_for_all_leaf_counts_0_to_129: candidate reducer backend = {}",
+            candidate_reducer_backend()
+        );
         for leaf_count in 0..=129 {
             let txids = txids(leaf_count);
             let mut avx = txids.clone();
@@ -562,6 +583,10 @@ mod tests {
 
     #[test]
     fn lane_boundary_pairs_seven_and_eight() {
+        eprintln!(
+            "lane_boundary_pairs_seven_and_eight: candidate reducer backend = {}",
+            candidate_reducer_backend()
+        );
         for leaf_count in [14, 15, 16, 17, 31, 32, 33] {
             let txids = txids(leaf_count);
             let mut avx = txids.clone();
@@ -576,6 +601,10 @@ mod tests {
 
     #[test]
     fn nonadjacent_duplicates_are_not_mutated() {
+        eprintln!(
+            "nonadjacent_duplicates_are_not_mutated: candidate reducer backend = {}",
+            candidate_reducer_backend()
+        );
         let a = txid(1);
         let b = txid(2);
 
@@ -593,6 +622,10 @@ mod tests {
 
     #[test]
     fn synthetic_odd_duplicate_distinguishes_padding_from_mutation() {
+        eprintln!(
+            "synthetic_odd_duplicate_distinguishes_padding_from_mutation: candidate reducer backend = {}",
+            candidate_reducer_backend()
+        );
         let a = txid(1);
         let b = txid(2);
 
@@ -617,6 +650,10 @@ mod tests {
 
     #[test]
     fn core_ambiguous_six_leaf_tree_vs_duplicated_tail() {
+        eprintln!(
+            "core_ambiguous_six_leaf_tree_vs_duplicated_tail: candidate reducer backend = {}",
+            candidate_reducer_backend()
+        );
         // Core test vector: [1..6] and [1..6, 5, 6] share a root but only the
         // duplicated version is mutated.
         let one_to_six: Vec<Txid> = (1u8..=6).map(txid).collect();

docs/benchmarks/data/end-to-end-sync/avx2-merkle-custody-v1.json

@@ -404,6 +404,10 @@
     "parents_64_speedup": 4.564475858916201,
     "parents_1024_speedup": 5.5749675465166595
   },
+  "criterion_notes": {
+    "ratio_scope": "The reported criterion ratios include identical scratch-buffer refill overhead in both the candidate and scalar arms, so they are conservative end-to-end Merkle-reducer ratios rather than pure-kernel SHA256d ratios.",
+    "conservative": "Because the scalar arm benefits from the same buffer-reuse strategy as the candidate, any AVX2 kernel advantage is partially absorbed by shared setup cost, making these speedup figures lower bounds on the raw kernel speedup."
+  },
   "final_source_smoke": {
     "command": "taskset -c 0-31 target/release/examples/mainnet_prefix_replay --stop-height 150000 --blocks-file $CORPUS --assume-valid-height 0 --storage-backend fjall --data-dir $DATA_DIR --output $OUTPUT",
     "label": "candidate-final-source",
@@ -415,11 +419,11 @@
     "stop_hash": "0000000000000a3290f20e75860d505ce0e948a1d1d846bec7e39015d242884b"
   },
   "optional_local_archive": {
-    "fjall": "/home/alpha/bench-g14/results/avx2-merkle-paired/packet.json",
-    "rocksdb": "/home/alpha/bench-g14/results/avx2-merkle-rocksdb-paired/packet.json",
-    "redb": "/home/alpha/bench-g14/results/avx2-merkle-redb-paired/packet.json",
-    "core": "/home/alpha/bench-g14/results/avx2-merkle-core-final/packet.json",
-    "validation": "/home/alpha/bench-g14/results/avx2-merkle-validation/packet.json",
-    "smoke": "/home/alpha/bench-g14/results/avx2-merkle-final-smoke/packet.json"
+    "fjall": "$BENCH_RESULTS/avx2-merkle-paired/packet.json",
+    "rocksdb": "$BENCH_RESULTS/avx2-merkle-rocksdb-paired/packet.json",
+    "redb": "$BENCH_RESULTS/avx2-merkle-redb-paired/packet.json",
+    "core": "$BENCH_RESULTS/avx2-merkle-core-final/packet.json",
+    "validation": "$BENCH_RESULTS/avx2-merkle-validation/packet.json",
+    "smoke": "$BENCH_RESULTS/avx2-merkle-final-smoke/packet.json"
   }
 }