[Fix] Enforce the connected-peer cap when provers are present

[thep2p]

Motivation

Heartbeat::handle_connected_peers is meant to trim the node back to MAXIMUM_NUMBER_OF_PEERS (21) whenever it's over. It doesn't: whenever any provers are connected, it under-disconnects and the node settles at up to max_peers + connected_provers — 26 instead of 21, a ~24% overshoot of the configured cap — and never converges.

Root cause is a single wrong operand when splitting the disconnect budget between provers and everyone else:

num_surplus_clients_validators = num_surplus_peers − num_remaining_provers   // provers that STAY    ❌                                                             
                                                     − num_surplus_provers     // provers being DROPPED ✅                                                            

Every prover disconnected is also a peer disconnected, so the non-prover budget must net out the provers being removed, not the ones remaining. Subtracting the larger "remaining" count drains the budget — usually to 0 — so non-provers are never trimmed:

26 connected, 3 provers, caps 21/5  →  must remove 5                                                                                                                
    buggy: drops 2 → 24 left  ❌                                                                                                                                      
    fixed: drops 5 → 21 left  ✅  

Fix:

• Correct the operand: num_remaining_provers → num_surplus_provers.
• Extract the arithmetic into a pure, side-effect-free helper calculate_surplus_peer_count, so the policy is unit-testable without standing up a live Router.

Test Plan

Added a table-driven unit test over four regimes (normal, prover-heavy, no-surplus, all-provers), each asserting the exact (provers, others) split and the invariant provers + others == max(surplus_peers, surplus_provers). Red on staging, green with the fix. Router suite and clippy --lib -D warnings pass.

Documentation

Does not add or change functionality, solely fixing an invariant.

Backwards compatibility

None affected — no wire, storage, or protocol changes; purely an internal connection-management correction.