irontide_session_core/

queue.rs

#![allow(
    clippy::cast_possible_truncation,
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    reason = "M175: queue position arithmetic — torrent counts fit u32"
)]

//! Queue position arithmetic for auto-managed torrents.

use irontide_core::Id20;

/// Compact representation of a queued torrent for position operations.
#[derive(Debug, Clone)]
pub struct QueueEntry {
    /// Info hash of the queued torrent.
    pub info_hash: Id20,
    /// Zero-based queue position; lower values are earlier in the queue.
    pub position: i32,
}

/// Assigns a position at the end of the queue. Returns the assigned position.
#[allow(dead_code)] // used by tests; session uses SessionActor::next_queue_position() instead
pub(crate) fn append_position(entries: &[QueueEntry]) -> i32 {
    entries
        .iter()
        .map(|e| e.position)
        .max()
        .map_or(0, |m| m + 1)
}

/// Removes a position and shifts all positions above it down by 1.
/// Returns the list of (`info_hash`, `old_pos`, `new_pos`) that changed.
pub fn remove_position(entries: &mut Vec<QueueEntry>, pos: i32) -> Vec<(Id20, i32, i32)> {
    entries.retain(|e| e.position != pos);
    let mut changed = Vec::new();
    for entry in entries.iter_mut() {
        if entry.position > pos {
            let old = entry.position;
            entry.position -= 1;
            changed.push((entry.info_hash, old, entry.position));
        }
    }
    changed
}

/// Moves a torrent to a new absolute position. Shifts others to maintain density.
/// Returns the list of (`info_hash`, `old_pos`, `new_pos`) for all changed entries.
pub fn set_position(
    entries: &mut [QueueEntry],
    info_hash: Id20,
    new_pos: i32,
) -> Vec<(Id20, i32, i32)> {
    let new_pos = new_pos.clamp(0, entries.len().saturating_sub(1) as i32);
    let old_pos = match entries.iter().find(|e| e.info_hash == info_hash) {
        Some(e) => e.position,
        None => return Vec::new(),
    };
    if old_pos == new_pos {
        return Vec::new();
    }

    let mut changed = Vec::new();

    if new_pos < old_pos {
        // Moving up: shift entries in [new_pos, old_pos) down by +1
        for entry in entries.iter_mut() {
            if entry.info_hash == info_hash {
                changed.push((entry.info_hash, old_pos, new_pos));
                entry.position = new_pos;
            } else if entry.position >= new_pos && entry.position < old_pos {
                let old = entry.position;
                entry.position += 1;
                changed.push((entry.info_hash, old, entry.position));
            }
        }
    } else {
        // Moving down: shift entries in (old_pos, new_pos] up by -1
        for entry in entries.iter_mut() {
            if entry.info_hash == info_hash {
                changed.push((entry.info_hash, old_pos, new_pos));
                entry.position = new_pos;
            } else if entry.position > old_pos && entry.position <= new_pos {
                let old = entry.position;
                entry.position -= 1;
                changed.push((entry.info_hash, old, entry.position));
            }
        }
    }

    changed
}

/// Move one position up (lower number = higher priority). Returns changes.
pub fn move_up(entries: &mut [QueueEntry], info_hash: Id20) -> Vec<(Id20, i32, i32)> {
    let pos = match entries.iter().find(|e| e.info_hash == info_hash) {
        Some(e) if e.position > 0 => e.position,
        _ => return Vec::new(),
    };
    set_position(entries, info_hash, pos - 1)
}

/// Move one position down. Returns changes.
pub fn move_down(entries: &mut [QueueEntry], info_hash: Id20) -> Vec<(Id20, i32, i32)> {
    let max_pos = entries.iter().map(|e| e.position).max().unwrap_or(0);
    let pos = match entries.iter().find(|e| e.info_hash == info_hash) {
        Some(e) if e.position < max_pos => e.position,
        _ => return Vec::new(),
    };
    set_position(entries, info_hash, pos + 1)
}

/// Move to position 0 (highest priority). Returns changes.
pub fn move_top(entries: &mut [QueueEntry], info_hash: Id20) -> Vec<(Id20, i32, i32)> {
    set_position(entries, info_hash, 0)
}

/// Move to last position (lowest priority). Returns changes.
pub fn move_bottom(entries: &mut [QueueEntry], info_hash: Id20) -> Vec<(Id20, i32, i32)> {
    let max_pos = entries.len().saturating_sub(1) as i32;
    set_position(entries, info_hash, max_pos)
}

// ---------------------------------------------------------------------------
// Auto-manage evaluation
// ---------------------------------------------------------------------------

/// Classification of a torrent for queue evaluation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QueueCategory {
    /// Incomplete torrent — counts against `active_downloads`.
    Downloading,
    /// Complete torrent — counts against `active_seeds`.
    Seeding,
    /// Hash-checking / verifying — counts against `active_checking`.
    Checking,
}

/// Snapshot of a torrent for queue evaluation.
#[derive(Debug, Clone)]
pub struct QueueCandidate {
    /// Info hash of the torrent under evaluation.
    pub info_hash: Id20,
    /// Current queue position; lower values are evaluated first.
    pub position: i32,
    /// Classification (downloading / seeding / checking) for slot accounting.
    pub category: QueueCategory,
    /// Whether the torrent currently occupies an active slot.
    pub is_active: bool,
    /// Whether the torrent is below the slow-transfer threshold; excluded from
    /// the active counts when [`QueueConfig::dont_count_slow`] is set.
    pub is_inactive: bool,
    /// Recently started torrents are exempt from being paused (anti-flap).
    pub recently_started: bool,
    /// Swarm demand rank for seeding torrents (higher = more demand). `None` for non-seeding.
    pub seed_rank: Option<i32>,
}

/// Named configuration for queue evaluation limits.
#[derive(Debug, Clone)]
pub struct QueueConfig {
    /// Maximum number of concurrently active downloading torrents.
    pub active_downloads: i32,
    /// Maximum number of concurrently active seeding torrents.
    pub active_seeds: i32,
    /// Maximum number of concurrently active hash-checking torrents.
    pub active_checking: i32,
    /// Maximum total active torrents; negative means unlimited.
    pub active_limit: i32,
    /// When `true`, torrents below the slow-transfer threshold do not count
    /// toward the active limits.
    pub dont_count_slow: bool,
    /// When `true`, seeding torrents are allotted slots ahead of downloads.
    pub prefer_seeds: bool,
}

/// Result of queue evaluation: which torrents to start and stop.
#[derive(Debug, Default)]
pub struct QueueDecision {
    /// Torrents to resume (promote into an active slot).
    pub to_resume: Vec<Id20>,
    /// Torrents to pause (demote out of an active slot).
    pub to_pause: Vec<Id20>,
}

/// Compute swarm demand rank for a seeding torrent.
///
/// Higher values = more demand. Returns `i32::MAX` when seeders is 0 (infinite
/// demand), 0 when leechers is 0 (no demand). Negative inputs (unknown from
/// tracker) are treated as 0.
#[must_use]
pub fn compute_seed_rank(num_complete: i32, num_incomplete: i32) -> i32 {
    let seeders = i64::from(num_complete.max(0));
    let leechers = i64::from(num_incomplete.max(0));
    if leechers == 0 {
        return 0;
    }
    if seeders == 0 {
        return i32::MAX;
    }
    i32::try_from((leechers * 1000) / seeders).unwrap_or(i32::MAX)
}

/// Evaluate the queue and decide which torrents to start/stop.
///
/// Negative limits mean "unlimited" for that category.
/// Checking torrents are processed first (transient, shouldn't be blocked by
/// DL/seed slot accounting). They count toward `active_limit` but NOT toward
/// `active_downloads` or `active_seeds`.
/// Seeding group is sorted by `seed_rank` descending (higher demand first),
/// breaking ties by queue position.
#[must_use]
pub fn evaluate(candidates: &[QueueCandidate], config: &QueueConfig) -> QueueDecision {
    let mut decision = QueueDecision::default();

    let mut checking: Vec<_> = candidates
        .iter()
        .filter(|c| c.category == QueueCategory::Checking)
        .collect();
    checking.sort_by_key(|c| c.position);

    let mut downloads: Vec<_> = candidates
        .iter()
        .filter(|c| c.category == QueueCategory::Downloading)
        .collect();
    downloads.sort_by_key(|c| c.position);

    let mut seeds: Vec<_> = candidates
        .iter()
        .filter(|c| c.category == QueueCategory::Seeding)
        .collect();
    seeds.sort_by(|a, b| {
        let rank_a = a.seed_rank.unwrap_or(0);
        let rank_b = b.seed_rank.unwrap_or(0);
        rank_b.cmp(&rank_a).then(a.position.cmp(&b.position))
    });

    let mut total_active: i32 = 0;

    // Checking always first — transient operations that shouldn't be blocked
    evaluate_group(
        &checking,
        config.active_checking,
        config.active_limit,
        config.dont_count_slow,
        &mut total_active,
        &mut decision,
    );

    let dl_seed_groups: Vec<(&[&QueueCandidate], i32)> = if config.prefer_seeds {
        vec![
            (&seeds, config.active_seeds),
            (&downloads, config.active_downloads),
        ]
    } else {
        vec![
            (&downloads, config.active_downloads),
            (&seeds, config.active_seeds),
        ]
    };

    for (group, limit) in dl_seed_groups {
        evaluate_group(
            group,
            limit,
            config.active_limit,
            config.dont_count_slow,
            &mut total_active,
            &mut decision,
        );
    }

    decision
}

fn evaluate_group(
    group: &[&QueueCandidate],
    limit: i32,
    active_limit: i32,
    dont_count_slow: bool,
    total_active: &mut i32,
    decision: &mut QueueDecision,
) {
    let mut category_active: i32 = 0;

    for candidate in group {
        let counts_toward_limit = !(dont_count_slow && candidate.is_inactive);

        if candidate.is_active {
            if counts_toward_limit {
                category_active += 1;
                *total_active += 1;
            }
            let over_category = limit >= 0 && category_active > limit;
            let over_total = active_limit >= 0 && *total_active > active_limit;
            if (over_category || over_total) && !candidate.recently_started {
                decision.to_pause.push(candidate.info_hash);
                if counts_toward_limit {
                    category_active -= 1;
                    *total_active -= 1;
                }
            }
        } else {
            let under_category = limit < 0 || category_active < limit;
            let under_total = active_limit < 0 || *total_active < active_limit;
            if under_category && under_total {
                decision.to_resume.push(candidate.info_hash);
                if counts_toward_limit {
                    category_active += 1;
                    *total_active += 1;
                }
            }
        }
    }
}

/// Post-pass: for each category, if a queued torrent has strictly higher
/// priority (lower position) than the lowest-priority active torrent, swap
/// them. One swap per category per tick to prevent cascade instability.
pub fn apply_preemption(decision: &mut QueueDecision, candidates: &[QueueCandidate]) {
    for category in [
        QueueCategory::Downloading,
        QueueCategory::Seeding,
        QueueCategory::Checking,
    ] {
        let cat_candidates: Vec<_> = candidates
            .iter()
            .filter(|c| c.category == category)
            .collect();

        // Find lowest-priority active torrent (not recently_started, not already in to_pause)
        let worst_active = cat_candidates
            .iter()
            .filter(|c| c.is_active && !c.recently_started)
            .filter(|c| !decision.to_pause.contains(&c.info_hash))
            .max_by_key(|c| c.position);

        // Find highest-priority queued torrent (not already in to_resume)
        let best_queued = cat_candidates
            .iter()
            .filter(|c| !c.is_active)
            .filter(|c| !decision.to_resume.contains(&c.info_hash))
            .min_by_key(|c| c.position);

        if let (Some(active), Some(queued)) = (worst_active, best_queued)
            && queued.position < active.position
        {
            decision.to_pause.push(active.info_hash);
            decision.to_resume.push(queued.info_hash);
        }
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    fn make_hash(n: u8) -> Id20 {
        Id20::from([n; 20])
    }

    fn make_entries(n: usize) -> Vec<QueueEntry> {
        (0..n)
            .map(|i| QueueEntry {
                info_hash: make_hash(i as u8),
                position: i as i32,
            })
            .collect()
    }

    fn positions(entries: &[QueueEntry]) -> Vec<(u8, i32)> {
        let mut v: Vec<_> = entries
            .iter()
            .map(|e| (e.info_hash.as_ref()[0], e.position))
            .collect();
        v.sort_by_key(|&(_, pos)| pos);
        v
    }

    // ---- Position arithmetic ----

    #[test]
    fn append_to_empty() {
        assert_eq!(append_position(&[]), 0);
    }

    #[test]
    fn append_to_existing() {
        let entries = make_entries(3);
        assert_eq!(append_position(&entries), 3);
    }

    #[test]
    fn remove_middle_shifts_down() {
        let mut entries = make_entries(4);
        let changed = remove_position(&mut entries, 1);
        assert_eq!(entries.len(), 3);
        assert_eq!(positions(&entries), vec![(0, 0), (2, 1), (3, 2)]);
        assert_eq!(changed.len(), 2);
    }

    #[test]
    fn remove_last_no_shifts() {
        let mut entries = make_entries(3);
        let changed = remove_position(&mut entries, 2);
        assert_eq!(entries.len(), 2);
        assert_eq!(positions(&entries), vec![(0, 0), (1, 1)]);
        assert!(changed.is_empty());
    }

    #[test]
    fn set_position_move_up() {
        let mut entries = make_entries(4);
        let changed = set_position(&mut entries, make_hash(3), 1);
        assert_eq!(positions(&entries), vec![(0, 0), (3, 1), (1, 2), (2, 3)]);
        assert_eq!(changed.len(), 3);
    }

    #[test]
    fn set_position_move_down() {
        let mut entries = make_entries(4);
        let changed = set_position(&mut entries, make_hash(0), 2);
        assert_eq!(positions(&entries), vec![(1, 0), (2, 1), (0, 2), (3, 3)]);
        assert_eq!(changed.len(), 3);
    }

    #[test]
    fn set_position_same_is_noop() {
        let mut entries = make_entries(3);
        let changed = set_position(&mut entries, make_hash(1), 1);
        assert!(changed.is_empty());
    }

    #[test]
    fn move_up_from_zero_is_noop() {
        let mut entries = make_entries(3);
        let changed = move_up(&mut entries, make_hash(0));
        assert!(changed.is_empty());
    }

    #[test]
    fn move_up_swaps_adjacent() {
        let mut entries = make_entries(3);
        let changed = move_up(&mut entries, make_hash(2));
        assert_eq!(positions(&entries), vec![(0, 0), (2, 1), (1, 2)]);
        assert_eq!(changed.len(), 2);
    }

    #[test]
    fn move_down_from_last_is_noop() {
        let mut entries = make_entries(3);
        let changed = move_down(&mut entries, make_hash(2));
        assert!(changed.is_empty());
    }

    #[test]
    fn move_top_sends_to_front() {
        let mut entries = make_entries(4);
        let _changed = move_top(&mut entries, make_hash(3));
        assert_eq!(positions(&entries), vec![(3, 0), (0, 1), (1, 2), (2, 3)]);
    }

    #[test]
    fn move_bottom_sends_to_end() {
        let mut entries = make_entries(4);
        let _changed = move_bottom(&mut entries, make_hash(0));
        assert_eq!(positions(&entries), vec![(1, 0), (2, 1), (3, 2), (0, 3)]);
    }

    // ---- Evaluate algorithm ----

    fn default_config() -> QueueConfig {
        QueueConfig {
            active_downloads: 3,
            active_seeds: 5,
            active_checking: 1,
            active_limit: 500,
            dont_count_slow: true,
            prefer_seeds: false,
        }
    }

    #[test]
    fn evaluate_starts_up_to_limit() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_downloads: 2,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_resume.len(), 2);
        assert_eq!(decision.to_resume[0], make_hash(0));
        assert_eq!(decision.to_resume[1], make_hash(1));
        assert!(decision.to_pause.is_empty());
    }

    #[test]
    fn evaluate_pauses_over_limit() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_downloads: 2,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(decision.to_resume.is_empty());
        assert_eq!(decision.to_pause.len(), 1);
        assert_eq!(decision.to_pause[0], make_hash(2));
    }

    #[test]
    fn evaluate_inactive_dont_count() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: true,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: true,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_downloads: 2,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(decision.to_resume.is_empty());
        assert!(decision.to_pause.is_empty());
    }

    #[test]
    fn evaluate_respects_active_limit() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(10),
                position: 0,
                category: QueueCategory::Seeding,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(11),
                position: 1,
                category: QueueCategory::Seeding,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(12),
                position: 2,
                category: QueueCategory::Seeding,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_limit: 4,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_pause.len(), 1);
        assert_eq!(decision.to_pause[0], make_hash(12));
    }

    #[test]
    fn evaluate_unlimited_limits() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_downloads: -1,
            active_seeds: -1,
            active_checking: -1,
            active_limit: -1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_resume.len(), 2);
        assert!(decision.to_pause.is_empty());
    }

    #[test]
    fn paused_torrents_excluded_from_candidates_never_resume() {
        let paused_hash = make_hash(99);
        let candidates = vec![QueueCandidate {
            info_hash: make_hash(0),
            position: 0,
            category: QueueCategory::Downloading,
            is_active: true,
            is_inactive: false,
            recently_started: false,
            seed_rank: None,
        }];
        let config = QueueConfig {
            active_downloads: 5,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(!decision.to_resume.contains(&paused_hash));
        assert!(!decision.to_pause.contains(&paused_hash));
    }

    #[test]
    fn evaluate_resumes_queued_when_slots_open() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            dont_count_slow: false,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(decision.to_pause.is_empty());
        assert_eq!(decision.to_resume, vec![make_hash(2)]);
    }

    #[test]
    fn evaluate_queued_stays_queued_when_over_limit() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(3),
                position: 3,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            dont_count_slow: false,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(!decision.to_resume.contains(&make_hash(3)));
    }

    // ---- Checking queue ----

    #[test]
    fn evaluate_checking_separate_from_downloads() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(20),
                position: 0,
                category: QueueCategory::Checking,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_checking: 1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(
            decision.to_pause.is_empty(),
            "3 DLs at limit + 1 checking: nothing paused"
        );
        assert_eq!(
            decision.to_resume,
            vec![make_hash(20)],
            "checking runs independently"
        );
    }

    #[test]
    fn evaluate_checking_respects_own_limit() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(20),
                position: 0,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(21),
                position: 1,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_checking: 1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_pause, vec![make_hash(21)]);
    }

    #[test]
    fn evaluate_checking_counts_toward_active_limit() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(20),
                position: 0,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(10),
                position: 0,
                category: QueueCategory::Seeding,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        // active_limit=2: checking(1) + DL(1) = 2, seed should be paused
        let config = QueueConfig {
            active_limit: 2,
            active_checking: 5,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_pause, vec![make_hash(10)]);
    }

    #[test]
    fn evaluate_checking_processed_first() {
        // With active_limit=2: checking takes a slot first, then DL gets 1 slot
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(20),
                position: 0,
                category: QueueCategory::Checking,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_limit: 2,
            active_checking: 1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(
            decision.to_resume.contains(&make_hash(20)),
            "checking resumed"
        );
        assert!(
            decision.to_resume.contains(&make_hash(0)),
            "first DL resumed"
        );
        assert!(
            !decision.to_resume.contains(&make_hash(1)),
            "second DL blocked by active_limit"
        );
    }

    // ---- Metadata uses checking budget ----

    #[test]
    fn evaluate_metadata_uses_checking_budget() {
        // 1 metadata (Checking) + 3 downloads under DL limit: no interference
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(20),
                position: 0,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_checking: 3,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert!(
            decision.to_pause.is_empty(),
            "metadata in Checking doesn't consume DL slot"
        );
        assert!(decision.to_resume.is_empty());
    }

    #[test]
    fn evaluate_metadata_respects_checking_limit() {
        // 4 metadata torrents, checking limit 3: 1 queued
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(20),
                position: 0,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(21),
                position: 1,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(22),
                position: 2,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(23),
                position: 3,
                category: QueueCategory::Checking,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = QueueConfig {
            active_checking: 3,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_pause, vec![make_hash(23)]);
    }

    // ---- Anti-flap timer ----

    #[test]
    fn evaluate_recently_started_exempt_from_pause() {
        // 4 active DLs, limit 3, lowest-priority is recently_started: NOT paused
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(3),
                position: 3,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: true,
                seed_rank: None,
            },
        ];
        let config = default_config();
        let decision = evaluate(&candidates, &config);
        assert!(
            !decision.to_pause.contains(&make_hash(3)),
            "recently_started torrent must not be paused"
        );
    }

    #[test]
    fn evaluate_recently_started_still_counts_toward_limit() {
        // 3 active DLs (one recently_started) + 1 queued, limit 3:
        // queued stays queued because recently_started occupies a slot
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: true,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(3),
                position: 3,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = default_config();
        let decision = evaluate(&candidates, &config);
        assert!(
            !decision.to_resume.contains(&make_hash(3)),
            "queued torrent blocked: recently_started holds the slot"
        );
    }

    #[test]
    fn evaluate_not_recently_started_can_be_paused() {
        // 4 active DLs, limit 3, lowest-priority NOT recently_started: paused
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(3),
                position: 3,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let config = default_config();
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_pause, vec![make_hash(3)]);
    }

    // ---- Per-peer rate inactive classification ----

    #[test]
    fn rate_based_inactive_uses_realtime_rate() {
        // Torrent with download_rate=0 (idle now) should be classified inactive
        // regardless of how many bytes it has downloaded historically. This test
        // validates the evaluator uses instantaneous rate, not a byte delta.
        let candidates = vec![QueueCandidate {
            info_hash: make_hash(0),
            position: 0,
            category: QueueCategory::Downloading,
            is_active: true,
            // is_inactive is computed by session.rs from stats.download_rate;
            // here we set it directly to simulate rate=0 (below threshold)
            is_inactive: true,
            recently_started: false,
            seed_rank: None,
        }];
        let config = QueueConfig {
            active_downloads: 1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        // dont_count_slow=true (default): inactive torrent doesn't count toward limit
        assert!(
            decision.to_pause.is_empty(),
            "inactive torrent exempt from pausing"
        );
    }

    // ---- Demand-ranked seeding queue ----

    #[test]
    fn evaluate_seed_rank_high_demand_first() {
        // 3 seeders, 2 slots: rank 5000 (5:1 leech:seed) beats rank 100
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(10),
                position: 0,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: Some(100),
            },
            QueueCandidate {
                info_hash: make_hash(11),
                position: 1,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: Some(5000),
            },
            QueueCandidate {
                info_hash: make_hash(12),
                position: 2,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: Some(200),
            },
        ];
        let config = QueueConfig {
            active_seeds: 2,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(decision.to_resume.len(), 2);
        assert_eq!(decision.to_resume[0], make_hash(11), "highest demand first");
        assert_eq!(
            decision.to_resume[1],
            make_hash(12),
            "second highest demand"
        );
    }

    #[test]
    fn evaluate_seed_rank_tie_breaks_by_position() {
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(10),
                position: 0,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: Some(500),
            },
            QueueCandidate {
                info_hash: make_hash(11),
                position: 1,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: Some(500),
            },
        ];
        let config = QueueConfig {
            active_seeds: 1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(
            decision.to_resume,
            vec![make_hash(10)],
            "lower position wins on tie"
        );
    }

    #[test]
    fn evaluate_seed_rank_none_treated_as_zero() {
        // num_complete=-1 (unknown) gets rank 0 via compute_seed_rank
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(10),
                position: 0,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(11),
                position: 1,
                category: QueueCategory::Seeding,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: Some(100),
            },
        ];
        let config = QueueConfig {
            active_seeds: 1,
            ..default_config()
        };
        let decision = evaluate(&candidates, &config);
        assert_eq!(
            decision.to_resume,
            vec![make_hash(11)],
            "known demand beats unknown"
        );
    }

    #[test]
    fn compute_seed_rank_zero_seeders_returns_max() {
        assert_eq!(compute_seed_rank(0, 5), i32::MAX);
    }

    #[test]
    fn compute_seed_rank_zero_leechers_returns_zero() {
        assert_eq!(compute_seed_rank(5, 0), 0);
    }

    // ---- Priority preemption (apply_preemption post-pass) ----

    #[test]
    fn preemption_displaces_lower_priority() {
        // apply_preemption on a decision where evaluate didn't swap:
        // 3 active at pos 0,1,4, queued at pos 2. Preemption swaps pos 4 ↔ pos 2.
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(2),
                position: 2,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(4),
                position: 4,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        // Start with empty decision (simulating evaluate at-limit, no changes)
        let mut decision = QueueDecision::default();
        apply_preemption(&mut decision, &candidates);
        assert!(
            decision.to_pause.contains(&make_hash(4)),
            "position 4 paused"
        );
        assert!(
            decision.to_resume.contains(&make_hash(2)),
            "position 2 resumed"
        );
    }

    #[test]
    fn preemption_respects_recently_started() {
        // Only active torrent is recently_started: no swap
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(4),
                position: 4,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: true,
                seed_rank: None,
            },
        ];
        let mut decision = QueueDecision::default();
        apply_preemption(&mut decision, &candidates);
        assert!(
            decision.to_pause.is_empty(),
            "recently_started not displaced"
        );
        assert!(decision.to_resume.is_empty(), "no swap");
    }

    #[test]
    fn preemption_noop_when_optimal() {
        // All active have lower positions than queued: no change
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(5),
                position: 5,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let mut decision = QueueDecision::default();
        apply_preemption(&mut decision, &candidates);
        assert!(decision.to_pause.is_empty(), "no swaps needed");
        assert!(decision.to_resume.is_empty(), "no swaps needed");
    }

    #[test]
    fn preemption_single_swap_per_category() {
        // 3 active at pos 3,4,5 + 2 queued at pos 0,1.
        // Single swap: pos 5 ↔ pos 0 only. Pos 1 stays queued.
        let candidates = vec![
            QueueCandidate {
                info_hash: make_hash(0),
                position: 0,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(1),
                position: 1,
                category: QueueCategory::Downloading,
                is_active: false,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(3),
                position: 3,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(4),
                position: 4,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
            QueueCandidate {
                info_hash: make_hash(5),
                position: 5,
                category: QueueCategory::Downloading,
                is_active: true,
                is_inactive: false,
                recently_started: false,
                seed_rank: None,
            },
        ];
        let mut decision = QueueDecision::default();
        apply_preemption(&mut decision, &candidates);
        assert_eq!(
            decision.to_pause,
            vec![make_hash(5)],
            "only pos 5 displaced"
        );
        assert_eq!(
            decision.to_resume,
            vec![make_hash(0)],
            "only pos 0 promoted"
        );
    }
}