fix: make trust scores effective in find_closest_nodes

[maqi]

Summary

• Fixed a bug where trust scores were never actually used in find_closest_nodes()
• The previous implementation sorted by full XOR distance first, but since peer IDs are unique, distances are always unique - making trust scores dead code
• Introduced distance bucketing using leading zero bits as 'distance magnitude' to group similarly-close nodes
• Within each magnitude bucket, nodes are now sorted by trust (desc) then RTT (asc)

Problem

The original code:

a_distance.cmp(&b_distance)
    .then_with(|| /* trust comparison */)
    .then_with(|| /* RTT comparison */)

Since XOR distances between unique peer IDs and any target are always unique, the then_with closures for trust and RTT were never executed.

Solution

Use distance magnitude (256 - leading_zeros) as a coarse grouping:

• Nodes with the same magnitude are within a factor of 2 in actual distance
• This preserves Kademlia's convergence properties
• Trust now meaningfully influences selection among similarly-close nodes

Test plan

• Verify existing tests pass
• Manual verification that trust scores affect node selection within same distance magnitude

[dirvine]

Thank you @maqi for this excellent bug fix! 🎉

You correctly identified a subtle but important issue where trust scores were dead code due to unique XOR distances. The distance magnitude bucketing solution is elegant and preserves Kademlia's routing properties while enabling trust-weighted selection.

What we merged:

✅ Your contribution:

• Distance magnitude bucketing using leading zero bits
• Trust as tiebreaker within magnitude buckets
• Clear problem analysis and solution rationale

✅ Additional improvements we added on top:

• 5 comprehensive tests covering:
  • Trust system integration verification
  • Distance magnitude bucketing properties
  • Edge cases (self-lookup, all-zero/all-ones distances)
  • Security: distance always overrides trust
  • Performance regression testing
• Security documentation explaining threat model and Sybil resistance
• Edge case documentation for distance_magnitude() function
• Saturating arithmetic to prevent underflow edge cases

Verification:

• ✅ All new tests pass (5/5)
• ✅ Zero clippy warnings
• ✅ Code formatting passes
• ✅ No performance regression detected

Your fix is now merged to main! The trust system will now meaningfully reduce timeouts and improve reliability by preferring trusted nodes among similarly-distant peers.

Thanks again for the contribution! 🚀