suaveplan/docs/old-network-planning/PHASE_4.md

Phase 4: Metrics and Host Selection

Overview

Phase 4 implements advanced network quality metrics and the trust-based host selection system. This phase is critical for ensuring optimal network performance by selecting the most capable and reliable nodes to serve as hosts. The system adapts from the old implementation but is integrated into the new architecture.

Key Components

1. Network Metrics Collection

The metrics system provides detailed insights into connection quality and node performance.

PingManager

The PingManager actively monitors connection quality through ping-pong messages.

Key Features:

• Accurate latency measurement
• Jitter calculation
• Packet loss detection
• Reliability scoring based on multiple factors
• Historical tracking for trend analysis

Implementation Requirements:

• Send regular ping messages at configurable intervals
• Track timeouts and calculate packet loss ratios
• Compute statistical metrics (average, min, max latency)
• Calculate a composite reliability score for connection quality
• Provide granular metrics that can be used for host selection decisions

2. Host Selection System

The host selection system ensures that the most suitable nodes are chosen to serve as hosts in the network hierarchy.

HostSelector

The HostSelector evaluates candidate nodes based on multiple weighted factors.

Key Features:

• Trust-based scoring from historical performance
• Multi-factor candidate evaluation
• Weighted scoring algorithm
• Consensus validation
• Stability thresholds enforcement

Implementation Requirements:

• Calculate weighted scores based on multiple metrics:
  • Latency (lower is better)
  • Stability (based on jitter and packet loss)
  • Uptime (connection duration)
  • Capabilities (hardware/network resources)
  • Trust score (historical hosting performance)
• Validate that the selected host has significant consensus
• Track historical hosting performance to improve future selections
• Manage host transitions when the current host becomes unsuitable

3. Voting System Integration

The voting system provides a democratic mechanism for making decisions within the network.

VotingManager

Key Features:

• Vote initiation and collection
• Configurable voting periods
• Participation thresholds
• Result determination with configurable consensus requirements

Implementation Requirements:

• Support different voting topics (host selection, configuration changes, etc.)
• Collect votes from eligible participants
• Apply voting rules to determine outcomes
• Handle timeouts and partial participation

VoteSession

Key Features:

• Lifecycle management for individual votes
• Vote validation
• Tamper-proof tallying
• Result publication

Implementation Requirements:

• Track the state of a specific voting session
• Validate incoming votes against the session rules
• Provide a secure tallying mechanism
• Generate deterministic results based on the votes received

Class Relationships

classDiagram
    class PingManager {
        -connection: IConnection
        -pendingPings: Map~number, number~
        -latencyHistory: number[]
        -packetsSent: number
        -packetsLost: number
        +start()
        +stop()
        -sendPing()
        -handleMessage(message)
        +getStats(): PingStats
    }
    
    class PingStats {
        +currentLatency: number
        +averageLatency: number
        +minLatency: number
        +maxLatency: number
        +jitter: number
        +packetLoss: number
        +reliabilityScore: number
    }
    
    class HostSelector {
        -connections: Map~string, IConnection~
        -pingManagers: Map~string, PingManager~
        -hostHistory: Map~string, HostHistory~
        -currentHost: string
        +addConnection(connection)
        +removeConnection(connectionId)
        +initiateHostSelection()
        -evaluateCandidates()
        -calculateWeightedScore(metrics)
        -validateConsensus(candidates)
        +updateHostSessionOutcome(hostId, successful)
    }
    
    class HostCandidate {
        +id: string
        +score: number
        +metrics: object
    }
    
    class VotingManager {
        -node: NetworkNode
        -sessions: Map~string, VoteSession~
        +startVote(topic, options)
        +castVote(voteId, choice)
        +getActiveVotes()
        -handleVoteCompletion(result)
    }
    
    class VoteSession {
        +id: string
        +topic: string
        +options: string[]
        +deadline: number
        +votes: Map~string, string~
        +addVote(voterId, choice)
        +tallyVotes()
        +hasConsensus()
        +getResult()
    }
    
    PingManager -- PingStats : produces
    HostSelector -- PingManager : uses
    HostSelector -- HostCandidate : evaluates
    VotingManager -- VoteSession : manages
    HostSelector -- VotingManager : may use for selection

Integration Points

Integration with NetworkNode

The metrics and host selection components integrate with the NetworkNode class:

1. Network Quality Metrics: Provide performance data for node promotion/demotion decisions
2. Host Selection: Guide reorganization when parent nodes disconnect or become unsuitable
3. Voting: Enable democratic decision-making within the hierarchy

Integration with Message Routing

The host selection system affects message routing decisions:

1. Route Optimization: Favor routes through high-quality connections
2. Failover Routes: Prepare alternative routes when connection quality degrades
3. Prioritization: Consider host capabilities when determining message priorities

Implementation Guidelines

Performance Considerations

1. Efficient Metrics Collection: Minimize overhead of ping-based measurements
2. Caching: Cache metrics calculations that don't need to be recalculated frequently
3. Asynchronous Processing: Ensure host selection calculations don't block the main processing
4. Batched Updates: Group metrics updates to reduce processing overhead

Edge Cases to Handle

1. Host Disconnection: Handle unexpected disconnection of the selected host
2. Metrics Outliers: Discard or normalize outlier measurements that could skew decisions
3. Concurrent Selection: Handle multiple simultaneous host selection attempts
4. Selection Ties: Provide tiebreaking mechanisms for equal-scoring candidates
5. Cold Start: Handle host selection when limited history is available

Testing Strategy

Metrics Testing

1. Accuracy Tests:

   • Verify latency measurements against known values
   • Test jitter calculation with synthetic patterns
   • Confirm packet loss detection works correctly

2. Edge Case Tests:

   • Test behavior with extremely high latency
   • Verify measurements with 100% packet loss
   • Test behavior with rapidly changing network conditions

Host Selection Testing

1. Selection Tests:

   • Verify selection of hosts based on synthetic metrics
   • Test weighted scoring with various weight configurations
   • Confirm consensus validation works as expected

2. Historical Testing:

   • Verify trust scores affect future selections
   • Test behavior after unsuccessful hosting sessions
   • Confirm long-term improvement in selection quality

Voting System Testing

1. Basic Functionality Tests:

   • Test vote initiation and collection
   • Verify tallying produces expected results
   • Confirm deadline enforcement works correctly

2. Edge Case Tests:

   • Test behavior with minimal participation
   • Verify handling of late votes
   • Test concurrent voting sessions

Success Criteria

This phase is complete when:

1. The PingManager accurately measures connection quality metrics
2. The HostSelector correctly evaluates and ranks candidates
3. Historical hosting performance affects future selections
4. The VotingManager successfully coordinates voting sessions
5. All components handle edge cases and failures gracefully
6. Tests demonstrate accurate and fair host selection under various conditions
7. All tests pass with 100% code coverage

The metrics and host selection system built in this phase provide the foundation for a self-organizing, adaptive network that optimizes for performance and reliability.