feat(kad-dht): add RoutingTableDiagnostics for routing health inspection

[bhuvan-somisetty]

What problem does this solve?

When a KadDHT node starts misbehaving - slow lookups, failed bootstraps, keys that can't be found - operators are flying blind. The routing table is a complete black box. The only way to debug it today is to manually add print statements inside the Kademlia internals or stare at raw bucket lists hoping something stands out.

This PR adds a first-class diagnostic surface so you can answer the real questions in seconds:

• Which k-buckets are under-populated or empty?
• Where are the keyspace coverage gaps that explain why certain keys can't be found?
• How fresh are the known peers — are half of them stale?
• What is the overall routing-table health as a single score you can log or alert on?

---

Architecture

flowchart TD
    A[KadDHT] -->|get_diagnostics| D[RoutingTableDiagnostics]
    B[RoutingTable] -->|get_diagnostics| D
    B --> C1[KBucket 0\nclosest peers]
    B --> C2[KBucket 1]
    B --> C3[KBucket N\nfarthest peers]
    C1 & C2 & C3 --> D

    D -->|analyse| R[RoutingTableReport]
    R --> S1[BucketStat list\nfill rate · stale count]
    R --> S2[CoverageGap list\nkeyspace holes]
    R --> S3[FreshnessDistribution\nfresh · aging · stale]
    R --> S4[health_score 0–100\nverdict]

Loading

The analyser is read-only - it never modifies the routing table.

---

What was added

libp2p/kad_dht/diagnostics.py - core engine

from libp2p.kad_dht import KadDHT

dht = KadDHT(host, mode)

report = dht.get_diagnostics().analyse()
print(report.summary())
print(f"Health score: {report.health_score}/100  ({report.verdict})")

Sample output:

=== KadDHT Routing Table Report ===
Timestamp       : 2026-05-15 23:29:54
Local peer      : 12D3KooWAbcd1234…
Health score    : 73.4/100  (good)

Peers           : 18
Buckets         : 4/6 populated
Keyspace cover  : 61.2%
Coverage gaps   : 2

Peer freshness
  Fresh  (<1 h) : 14
  Aging (1–12 h): 3
  Stale (12–24h): 1
  Very stale    : 0

Top coverage gaps (first 3):
  bucket #5: 00000000…–1fffffff… (0 peers)
  bucket #4: 20000000…–3fffffff… (1 peers)

Health score breakdown (0–100, composite):

Component	Weight	What it measures
Fill score	40 pts	Average bucket fill rate, weighted by proximity to local node
Freshness score	35 pts	Ratio of peers seen in the last hour
Coverage score	25 pts	Fraction of the 256-bit keyspace covered

Buckets closest to the local node are weighted exponentially higher - this reflects the Kademlia property that near buckets dominate routing success.

Convenience entry points

# Full report via KadDHT
report = dht.get_diagnostics().analyse()

# Full report via RoutingTable directly
report = dht.routing_table.get_diagnostics().analyse()

# Partial queries (no full report allocation needed)
score = dht.get_diagnostics().get_health_score()
gaps  = dht.get_diagnostics().get_coverage_gaps()
fresh = dht.get_diagnostics().get_freshness_distribution()
stats = dht.get_diagnostics().get_bucket_stats()

Public types exported from libp2p.kad_dht

from libp2p.kad_dht import (
    RoutingTableDiagnostics,
    RoutingTableReport,
    BucketStat,
    CoverageGap,
    FreshnessDistribution,
)

---

Tests

tests/core/kad_dht/test_routing_table_diagnostics.py - 27 unit tests, fully offline (mock host, no network required). Covers:

• BucketStat properties (is_full, is_empty, health)
• FreshnessDistribution ratios and totals
• Empty routing table, single-peer table, multi-bucket tables
• Coverage gap detection and ordering (emptiest bucket first)
• Health score sub-components individually and composite
• RoutingTableReport.summary() output format
• Freshness time-band boundaries (exactly at 1 h, 12 h, 24 h edges)
• Stale peer counting in bucket stats

---

Runnable example

examples/kademlia/routing_table_diagnostics.py - two-node demo:

# Terminal 1 - bootstrap node
python examples/kademlia/routing_table_diagnostics.py --port 8888 --mode server

# Terminal 2 - client (connects, warms up 5s, prints full report)
python examples/kademlia/routing_table_diagnostics.py \
    --port 9999 --mode server \
    --bootstrap /ip4/127.0.0.1/tcp/8888/p2p/<PeerID>

---

Non-goals / out of scope

• No metrics export (Prometheus, OpenTelemetry) - that belongs in a separate PR
• No periodic background task - callers decide when to run diagnostics
• No modifications to routing table logic - purely observational

---

Checklist

• New module libp2p/kad_dht/diagnostics.py with full docstrings
• RoutingTable.get_diagnostics() convenience factory
• KadDHT.get_diagnostics() convenience factory
• All new public types exported in libp2p/kad_dht/__init__.py
• 27 offline unit tests
• Runnable example in examples/kademlia/
• Read-only analyser - zero changes to routing table logic
• TYPE_CHECKING guard to avoid circular imports