Split oversized runtime modules + Async tests hardened

Co-Authored-By: brekotis <93345790+brekotis@users.noreply.github.com>

src/transport/middle_proxy/config_updater.rs

@@ -279,202 +279,9 @@ pub async fn fetch_proxy_config_via_upstream(
         .map(|(parsed, _raw)| parsed)
 }
 
-fn snapshot_passes_guards(
-    cfg: &ProxyConfig,
-    snapshot: &ProxyConfigData,
-    snapshot_name: &'static str,
-) -> bool {
-    if cfg.general.me_snapshot_require_http_2xx && !(200..=299).contains(&snapshot.http_status) {
-        warn!(
-            snapshot = snapshot_name,
-            http_status = snapshot.http_status,
-            "ME snapshot rejected by non-2xx HTTP status"
-        );
-        return false;
-    }
-
-    let min_proxy_for = cfg.general.me_snapshot_min_proxy_for_lines;
-    if snapshot.proxy_for_lines < min_proxy_for {
-        warn!(
-            snapshot = snapshot_name,
-            parsed_proxy_for_lines = snapshot.proxy_for_lines,
-            min_proxy_for_lines = min_proxy_for,
-            "ME snapshot rejected by proxy_for line floor"
-        );
-        return false;
-    }
-
-    true
-}
-
-async fn run_update_cycle(
-    pool: &Arc<MePool>,
-    cfg: &ProxyConfig,
-    state: &mut UpdaterState,
-    reinit_tx: &mpsc::Sender<MeReinitTrigger>,
-) {
-    let upstream = pool.upstream.clone();
-
-    let required_cfg_snapshots = cfg.general.me_config_stable_snapshots.max(1);
-    let required_secret_snapshots = cfg.general.proxy_secret_stable_snapshots.max(1);
-    let apply_cooldown = Duration::from_secs(cfg.general.me_config_apply_cooldown_secs);
-    let mut maps_changed = false;
-
-    let mut ready_v4: Option<(ProxyConfigData, u64)> = None;
-    let cfg_v4 = retry_fetch(
-        cfg.general
-            .proxy_config_v4_url
-            .as_deref()
-            .unwrap_or("https://core.telegram.org/getProxyConfig"),
-        upstream.clone(),
-    )
-    .await;
-    if let Some(cfg_v4) = cfg_v4
-        && snapshot_passes_guards(cfg, &cfg_v4, "getProxyConfig")
-    {
-        let cfg_v4_hash = hash_proxy_config(&cfg_v4);
-        let stable_hits = state.config_v4.observe(cfg_v4_hash);
-        if stable_hits < required_cfg_snapshots {
-            debug!(
-                stable_hits,
-                required_cfg_snapshots,
-                snapshot = format_args!("0x{cfg_v4_hash:016x}"),
-                "ME config v4 candidate observed"
-            );
-        } else if state.config_v4.is_applied(cfg_v4_hash) {
-            debug!(
-                snapshot = format_args!("0x{cfg_v4_hash:016x}"),
-                "ME config v4 stable snapshot already applied"
-            );
-        } else {
-            ready_v4 = Some((cfg_v4, cfg_v4_hash));
-        }
-    }
-
-    let mut ready_v6: Option<(ProxyConfigData, u64)> = None;
-    let cfg_v6 = retry_fetch(
-        cfg.general
-            .proxy_config_v6_url
-            .as_deref()
-            .unwrap_or("https://core.telegram.org/getProxyConfigV6"),
-        upstream.clone(),
-    )
-    .await;
-    if let Some(cfg_v6) = cfg_v6
-        && snapshot_passes_guards(cfg, &cfg_v6, "getProxyConfigV6")
-    {
-        let cfg_v6_hash = hash_proxy_config(&cfg_v6);
-        let stable_hits = state.config_v6.observe(cfg_v6_hash);
-        if stable_hits < required_cfg_snapshots {
-            debug!(
-                stable_hits,
-                required_cfg_snapshots,
-                snapshot = format_args!("0x{cfg_v6_hash:016x}"),
-                "ME config v6 candidate observed"
-            );
-        } else if state.config_v6.is_applied(cfg_v6_hash) {
-            debug!(
-                snapshot = format_args!("0x{cfg_v6_hash:016x}"),
-                "ME config v6 stable snapshot already applied"
-            );
-        } else {
-            ready_v6 = Some((cfg_v6, cfg_v6_hash));
-        }
-    }
-
-    if ready_v4.is_some() || ready_v6.is_some() {
-        if map_apply_cooldown_ready(state.last_map_apply_at, apply_cooldown) {
-            let update_v4 = ready_v4
-                .as_ref()
-                .map(|(snapshot, _)| snapshot.map.clone())
-                .unwrap_or_default();
-            let update_v6 = ready_v6.as_ref().map(|(snapshot, _)| snapshot.map.clone());
-            let update_is_empty =
-                update_v4.is_empty() && update_v6.as_ref().is_none_or(|v| v.is_empty());
-            let apply_outcome = if update_is_empty && !cfg.general.me_snapshot_reject_empty_map {
-                super::pool_config::SnapshotApplyOutcome::AppliedNoDelta
-            } else {
-                pool.update_proxy_maps(update_v4, update_v6).await
-            };
-
-            if matches!(
-                apply_outcome,
-                super::pool_config::SnapshotApplyOutcome::RejectedEmpty
-            ) {
-                warn!("ME config stable snapshot rejected (empty endpoint map)");
-            } else {
-                if let Some((snapshot, hash)) = ready_v4 {
-                    if let Some(dc) = snapshot.default_dc {
-                        pool.default_dc
-                            .store(dc, std::sync::atomic::Ordering::Relaxed);
-                    }
-                    state.config_v4.mark_applied(hash);
-                }
-
-                if let Some((_snapshot, hash)) = ready_v6 {
-                    state.config_v6.mark_applied(hash);
-                }
-
-                state.last_map_apply_at = Some(tokio::time::Instant::now());
-
-                if apply_outcome.changed() {
-                    maps_changed = true;
-                    info!("ME config update applied after stable-gate");
-                } else {
-                    debug!("ME config stable-gate applied with no map delta");
-                }
-            }
-        } else if let Some(last) = state.last_map_apply_at {
-            let wait_secs = map_apply_cooldown_remaining_secs(last, apply_cooldown);
-            debug!(wait_secs, "ME config stable snapshot deferred by cooldown");
-        }
-    }
-
-    if maps_changed {
-        enqueue_reinit_trigger(reinit_tx, MeReinitTrigger::MapChanged);
-    }
-
-    pool.reset_stun_state();
-
-    if cfg.general.proxy_secret_rotate_runtime {
-        match download_proxy_secret_with_max_len_via_upstream(
-            cfg.general.proxy_secret_len_max,
-            upstream,
-            cfg.general.proxy_secret_url.as_deref(),
-        )
-        .await
-        {
-            Ok(secret) => {
-                let secret_hash = hash_secret(&secret);
-                let stable_hits = state.secret.observe(secret_hash);
-                if stable_hits < required_secret_snapshots {
-                    debug!(
-                        stable_hits,
-                        required_secret_snapshots,
-                        snapshot = format_args!("0x{secret_hash:016x}"),
-                        "proxy-secret candidate observed"
-                    );
-                } else if state.secret.is_applied(secret_hash) {
-                    debug!(
-                        snapshot = format_args!("0x{secret_hash:016x}"),
-                        "proxy-secret stable snapshot already applied"
-                    );
-                } else {
-                    let rotated = pool.update_secret(secret).await;
-                    state.secret.mark_applied(secret_hash);
-                    if rotated {
-                        info!("proxy-secret rotated after stable-gate");
-                    } else {
-                        debug!("proxy-secret stable snapshot confirmed as unchanged");
-                    }
-                }
-            }
-            Err(e) => warn!(error = %e, "proxy-secret update failed"),
-        }
-    } else {
-        debug!("proxy-secret runtime rotation disabled by config");
-    }
-}
+// Stable-snapshot guards and one bounded update cycle.
+mod cycle;
+use cycle::run_update_cycle;
 
 pub async fn me_config_updater(
     pool: Arc<MePool>,

src/transport/middle_proxy/config_updater/cycle.rs

@@ -0,0 +1,198 @@
+use super::*;
+
+pub(super) fn snapshot_passes_guards(
+    cfg: &ProxyConfig,
+    snapshot: &ProxyConfigData,
+    snapshot_name: &'static str,
+) -> bool {
+    if cfg.general.me_snapshot_require_http_2xx && !(200..=299).contains(&snapshot.http_status) {
+        warn!(
+            snapshot = snapshot_name,
+            http_status = snapshot.http_status,
+            "ME snapshot rejected by non-2xx HTTP status"
+        );
+        return false;
+    }
+
+    let min_proxy_for = cfg.general.me_snapshot_min_proxy_for_lines;
+    if snapshot.proxy_for_lines < min_proxy_for {
+        warn!(
+            snapshot = snapshot_name,
+            parsed_proxy_for_lines = snapshot.proxy_for_lines,
+            min_proxy_for_lines = min_proxy_for,
+            "ME snapshot rejected by proxy_for line floor"
+        );
+        return false;
+    }
+
+    true
+}
+
+pub(super) async fn run_update_cycle(
+    pool: &Arc<MePool>,
+    cfg: &ProxyConfig,
+    state: &mut UpdaterState,
+    reinit_tx: &mpsc::Sender<MeReinitTrigger>,
+) {
+    let upstream = pool.upstream.clone();
+
+    let required_cfg_snapshots = cfg.general.me_config_stable_snapshots.max(1);
+    let required_secret_snapshots = cfg.general.proxy_secret_stable_snapshots.max(1);
+    let apply_cooldown = Duration::from_secs(cfg.general.me_config_apply_cooldown_secs);
+    let mut maps_changed = false;
+
+    let mut ready_v4: Option<(ProxyConfigData, u64)> = None;
+    let cfg_v4 = retry_fetch(
+        cfg.general
+            .proxy_config_v4_url
+            .as_deref()
+            .unwrap_or("https://core.telegram.org/getProxyConfig"),
+        upstream.clone(),
+    )
+    .await;
+    if let Some(cfg_v4) = cfg_v4
+        && snapshot_passes_guards(cfg, &cfg_v4, "getProxyConfig")
+    {
+        let cfg_v4_hash = hash_proxy_config(&cfg_v4);
+        let stable_hits = state.config_v4.observe(cfg_v4_hash);
+        if stable_hits < required_cfg_snapshots {
+            debug!(
+                stable_hits,
+                required_cfg_snapshots,
+                snapshot = format_args!("0x{cfg_v4_hash:016x}"),
+                "ME config v4 candidate observed"
+            );
+        } else if state.config_v4.is_applied(cfg_v4_hash) {
+            debug!(
+                snapshot = format_args!("0x{cfg_v4_hash:016x}"),
+                "ME config v4 stable snapshot already applied"
+            );
+        } else {
+            ready_v4 = Some((cfg_v4, cfg_v4_hash));
+        }
+    }
+
+    let mut ready_v6: Option<(ProxyConfigData, u64)> = None;
+    let cfg_v6 = retry_fetch(
+        cfg.general
+            .proxy_config_v6_url
+            .as_deref()
+            .unwrap_or("https://core.telegram.org/getProxyConfigV6"),
+        upstream.clone(),
+    )
+    .await;
+    if let Some(cfg_v6) = cfg_v6
+        && snapshot_passes_guards(cfg, &cfg_v6, "getProxyConfigV6")
+    {
+        let cfg_v6_hash = hash_proxy_config(&cfg_v6);
+        let stable_hits = state.config_v6.observe(cfg_v6_hash);
+        if stable_hits < required_cfg_snapshots {
+            debug!(
+                stable_hits,
+                required_cfg_snapshots,
+                snapshot = format_args!("0x{cfg_v6_hash:016x}"),
+                "ME config v6 candidate observed"
+            );
+        } else if state.config_v6.is_applied(cfg_v6_hash) {
+            debug!(
+                snapshot = format_args!("0x{cfg_v6_hash:016x}"),
+                "ME config v6 stable snapshot already applied"
+            );
+        } else {
+            ready_v6 = Some((cfg_v6, cfg_v6_hash));
+        }
+    }
+
+    if ready_v4.is_some() || ready_v6.is_some() {
+        if map_apply_cooldown_ready(state.last_map_apply_at, apply_cooldown) {
+            let update_v4 = ready_v4
+                .as_ref()
+                .map(|(snapshot, _)| snapshot.map.clone())
+                .unwrap_or_default();
+            let update_v6 = ready_v6.as_ref().map(|(snapshot, _)| snapshot.map.clone());
+            let update_is_empty =
+                update_v4.is_empty() && update_v6.as_ref().is_none_or(|v| v.is_empty());
+            let apply_outcome = if update_is_empty && !cfg.general.me_snapshot_reject_empty_map {
+                crate::transport::middle_proxy::pool_config::SnapshotApplyOutcome::AppliedNoDelta
+            } else {
+                pool.update_proxy_maps(update_v4, update_v6).await
+            };
+
+            if matches!(
+                apply_outcome,
+                crate::transport::middle_proxy::pool_config::SnapshotApplyOutcome::RejectedEmpty
+            ) {
+                warn!("ME config stable snapshot rejected (empty endpoint map)");
+            } else {
+                if let Some((snapshot, hash)) = ready_v4 {
+                    if let Some(dc) = snapshot.default_dc {
+                        pool.default_dc
+                            .store(dc, std::sync::atomic::Ordering::Relaxed);
+                    }
+                    state.config_v4.mark_applied(hash);
+                }
+
+                if let Some((_snapshot, hash)) = ready_v6 {
+                    state.config_v6.mark_applied(hash);
+                }
+
+                state.last_map_apply_at = Some(tokio::time::Instant::now());
+
+                if apply_outcome.changed() {
+                    maps_changed = true;
+                    info!("ME config update applied after stable-gate");
+                } else {
+                    debug!("ME config stable-gate applied with no map delta");
+                }
+            }
+        } else if let Some(last) = state.last_map_apply_at {
+            let wait_secs = map_apply_cooldown_remaining_secs(last, apply_cooldown);
+            debug!(wait_secs, "ME config stable snapshot deferred by cooldown");
+        }
+    }
+
+    if maps_changed {
+        enqueue_reinit_trigger(reinit_tx, MeReinitTrigger::MapChanged);
+    }
+
+    pool.reset_stun_state();
+
+    if cfg.general.proxy_secret_rotate_runtime {
+        match download_proxy_secret_with_max_len_via_upstream(
+            cfg.general.proxy_secret_len_max,
+            upstream,
+            cfg.general.proxy_secret_url.as_deref(),
+        )
+        .await
+        {
+            Ok(secret) => {
+                let secret_hash = hash_secret(&secret);
+                let stable_hits = state.secret.observe(secret_hash);
+                if stable_hits < required_secret_snapshots {
+                    debug!(
+                        stable_hits,
+                        required_secret_snapshots,
+                        snapshot = format_args!("0x{secret_hash:016x}"),
+                        "proxy-secret candidate observed"
+                    );
+                } else if state.secret.is_applied(secret_hash) {
+                    debug!(
+                        snapshot = format_args!("0x{secret_hash:016x}"),
+                        "proxy-secret stable snapshot already applied"
+                    );
+                } else {
+                    let rotated = pool.update_secret(secret).await;
+                    state.secret.mark_applied(secret_hash);
+                    if rotated {
+                        info!("proxy-secret rotated after stable-gate");
+                    } else {
+                        debug!("proxy-secret stable snapshot confirmed as unchanged");
+                    }
+                }
+            }
+            Err(e) => warn!(error = %e, "proxy-secret update failed"),
+        }
+    } else {
+        debug!("proxy-secret runtime rotation disabled by config");
+    }
+}

src/transport/middle_proxy/health/drain.rs

@@ -0,0 +1,212 @@
+use super::*;
+
+pub async fn me_drain_timeout_enforcer(pool: Arc<MePool>) {
+    let mut drain_warn_next_allowed: HashMap<u64, Instant> = HashMap::new();
+    loop {
+        tokio::time::sleep(Duration::from_secs(
+            HEALTH_DRAIN_TIMEOUT_ENFORCER_INTERVAL_SECS,
+        ))
+        .await;
+        reap_draining_writers(&pool, &mut drain_warn_next_allowed).await;
+    }
+}
+
+pub(in crate::transport::middle_proxy) async fn reap_draining_writers(
+    pool: &Arc<MePool>,
+    warn_next_allowed: &mut HashMap<u64, Instant>,
+) {
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let now = Instant::now();
+    let drain_ttl_secs = pool
+        .drain_runtime
+        .me_pool_drain_ttl_secs
+        .load(std::sync::atomic::Ordering::Relaxed);
+    let drain_threshold = pool
+        .drain_runtime
+        .me_pool_drain_threshold
+        .load(std::sync::atomic::Ordering::Relaxed);
+    let activity = pool.registry.writer_activity_snapshot().await;
+    let mut draining_writers = Vec::<DrainingWriterSnapshot>::new();
+    let mut empty_writer_ids = Vec::<u64>::new();
+    let mut force_close_writer_ids = Vec::<u64>::new();
+    let writers = pool.writers.read().await;
+    for writer in writers.iter() {
+        if !writer.draining.load(std::sync::atomic::Ordering::Relaxed) {
+            continue;
+        }
+        if activity
+            .bound_clients_by_writer
+            .get(&writer.id)
+            .copied()
+            .unwrap_or(0)
+            == 0
+        {
+            empty_writer_ids.push(writer.id);
+            continue;
+        }
+        draining_writers.push(DrainingWriterSnapshot {
+            id: writer.id,
+            writer_dc: writer.writer_dc,
+            addr: writer.addr,
+            generation: writer.generation,
+            created_at: writer.created_at,
+            draining_started_at_epoch_secs: writer
+                .draining_started_at_epoch_secs
+                .load(std::sync::atomic::Ordering::Relaxed),
+            drain_deadline_epoch_secs: writer
+                .drain_deadline_epoch_secs
+                .load(std::sync::atomic::Ordering::Relaxed),
+            allow_drain_fallback: writer
+                .allow_drain_fallback
+                .load(std::sync::atomic::Ordering::Relaxed),
+        });
+    }
+    drop(writers);
+
+    let overflow = if drain_threshold > 0 && draining_writers.len() > drain_threshold as usize {
+        draining_writers
+            .len()
+            .saturating_sub(drain_threshold as usize)
+    } else {
+        0
+    };
+
+    if overflow > 0 {
+        draining_writers.sort_by(|left, right| {
+            left.draining_started_at_epoch_secs
+                .cmp(&right.draining_started_at_epoch_secs)
+                .then_with(|| left.created_at.cmp(&right.created_at))
+                .then_with(|| left.id.cmp(&right.id))
+        });
+        warn!(
+            draining_writers = draining_writers.len(),
+            me_pool_drain_threshold = drain_threshold,
+            removing_writers = overflow,
+            "ME draining writer threshold exceeded, force-closing oldest draining writers"
+        );
+        for writer in draining_writers.drain(..overflow) {
+            force_close_writer_ids.push(writer.id);
+        }
+    }
+
+    for writer in draining_writers {
+        if drain_ttl_secs > 0
+            && writer.draining_started_at_epoch_secs != 0
+            && now_epoch_secs.saturating_sub(writer.draining_started_at_epoch_secs) > drain_ttl_secs
+            && should_emit_writer_warn(
+                warn_next_allowed,
+                writer.id,
+                now,
+                pool.warn_rate_limit_duration(),
+            )
+        {
+            warn!(
+                writer_id = writer.id,
+                writer_dc = writer.writer_dc,
+                endpoint = %writer.addr,
+                generation = writer.generation,
+                drain_ttl_secs,
+                force_close_secs = pool
+                    .drain_runtime
+                    .me_pool_force_close_secs
+                    .load(std::sync::atomic::Ordering::Relaxed),
+                allow_drain_fallback = writer.allow_drain_fallback,
+                "ME draining writer remains non-empty past drain TTL"
+            );
+        }
+        if writer.drain_deadline_epoch_secs != 0
+            && now_epoch_secs >= writer.drain_deadline_epoch_secs
+        {
+            warn!(writer_id = writer.id, "Drain timeout, force-closing");
+            force_close_writer_ids.push(writer.id);
+        }
+    }
+
+    let close_budget = health_drain_close_budget();
+    let requested_force_close = force_close_writer_ids.len();
+    let requested_empty_close = empty_writer_ids.len();
+    let requested_close_total = requested_force_close.saturating_add(requested_empty_close);
+    let mut closed_writer_ids = HashSet::<u64>::new();
+    let mut closed_total = 0usize;
+    for writer_id in force_close_writer_ids {
+        if closed_total >= close_budget {
+            break;
+        }
+        if !closed_writer_ids.insert(writer_id) {
+            continue;
+        }
+        pool.stats.increment_pool_force_close_total();
+        pool.remove_writer_and_close_clients(writer_id).await;
+        closed_total = closed_total.saturating_add(1);
+    }
+    for writer_id in empty_writer_ids {
+        if closed_total >= close_budget {
+            break;
+        }
+        if !closed_writer_ids.insert(writer_id) {
+            continue;
+        }
+        pool.remove_writer_and_close_clients(writer_id).await;
+        closed_total = closed_total.saturating_add(1);
+    }
+
+    let pending_close_total = requested_close_total.saturating_sub(closed_total);
+    if pending_close_total > 0 {
+        warn!(
+            close_budget,
+            closed_total,
+            pending_close_total,
+            "ME draining close backlog deferred to next health cycle"
+        );
+    }
+
+    // Keep warn cooldown state for draining writers still present in the pool;
+    // drop state only once a writer is actually removed.
+    let active_draining_writer_ids = {
+        let writers = pool.writers.read().await;
+        writers
+            .iter()
+            .filter(|writer| writer.draining.load(std::sync::atomic::Ordering::Relaxed))
+            .map(|writer| writer.id)
+            .collect::<HashSet<u64>>()
+    };
+    warn_next_allowed.retain(|writer_id, _| active_draining_writer_ids.contains(writer_id));
+}
+
+pub(in crate::transport::middle_proxy) fn health_drain_close_budget() -> usize {
+    let cpu_cores = std::thread::available_parallelism()
+        .map(std::num::NonZeroUsize::get)
+        .unwrap_or(1);
+    cpu_cores
+        .saturating_mul(HEALTH_DRAIN_CLOSE_BUDGET_PER_CORE)
+        .clamp(HEALTH_DRAIN_CLOSE_BUDGET_MIN, HEALTH_DRAIN_CLOSE_BUDGET_MAX)
+}
+
+#[derive(Debug, Clone)]
+struct DrainingWriterSnapshot {
+    id: u64,
+    writer_dc: i32,
+    addr: SocketAddr,
+    generation: u64,
+    created_at: Instant,
+    draining_started_at_epoch_secs: u64,
+    drain_deadline_epoch_secs: u64,
+    allow_drain_fallback: bool,
+}
+
+pub(super) fn should_emit_writer_warn(
+    next_allowed: &mut HashMap<u64, Instant>,
+    writer_id: u64,
+    now: Instant,
+    cooldown: Duration,
+) -> bool {
+    let Some(ready_at) = next_allowed.get(&writer_id).copied() else {
+        next_allowed.insert(writer_id, now + cooldown);
+        return true;
+    };
+    if now >= ready_at {
+        next_allowed.insert(writer_id, now + cooldown);
+        return true;
+    }
+    false
+}

src/transport/middle_proxy/health/family.rs

@@ -0,0 +1,484 @@
+use super::*;
+
+pub(super) async fn check_family(
+    family: IpFamily,
+    pool: &Arc<MePool>,
+    rng: &Arc<SecureRandom>,
+    backoff: &mut HashMap<(i32, IpFamily), u64>,
+    next_attempt: &mut HashMap<(i32, IpFamily), Instant>,
+    inflight: &mut HashMap<(i32, IpFamily), usize>,
+    outage_backoff: &mut HashMap<(i32, IpFamily), u64>,
+    outage_next_attempt: &mut HashMap<(i32, IpFamily), Instant>,
+    single_endpoint_outage: &mut HashSet<(i32, IpFamily)>,
+    shadow_rotate_deadline: &mut HashMap<(i32, IpFamily), Instant>,
+    idle_refresh_next_attempt: &mut HashMap<(i32, IpFamily), Instant>,
+    floor_warn_next_allowed: &mut HashMap<(i32, IpFamily), Instant>,
+) -> bool {
+    let enabled = match family {
+        IpFamily::V4 => pool.decision.ipv4_me,
+        IpFamily::V6 => pool.decision.ipv6_me,
+    };
+    if !enabled {
+        return false;
+    }
+
+    let mut family_degraded = false;
+
+    let mut dc_endpoints = HashMap::<i32, Vec<SocketAddr>>::new();
+    let map_guard = match family {
+        IpFamily::V4 => pool.proxy_map_v4.read().await,
+        IpFamily::V6 => pool.proxy_map_v6.read().await,
+    };
+    for (dc, addrs) in map_guard.iter() {
+        let entry = dc_endpoints.entry(*dc).or_default();
+        for (ip, port) in addrs.iter().copied() {
+            entry.push(SocketAddr::new(ip, port));
+        }
+    }
+    drop(map_guard);
+    for endpoints in dc_endpoints.values_mut() {
+        endpoints.sort_unstable();
+        endpoints.dedup();
+    }
+    let reconnect_budget = health_reconnect_budget(pool, dc_endpoints.len());
+    let reconnect_sem = Arc::new(Semaphore::new(reconnect_budget));
+
+    if pool.floor_mode() == MeFloorMode::Static {}
+
+    let mut live_addr_counts = HashMap::<(i32, SocketAddr), usize>::new();
+    let mut live_writer_ids_by_addr = HashMap::<(i32, SocketAddr), Vec<u64>>::new();
+    for writer in pool
+        .writers
+        .read()
+        .await
+        .iter()
+        .filter(|w| !w.draining.load(std::sync::atomic::Ordering::Relaxed))
+    {
+        if !matches!(
+            crate::transport::middle_proxy::pool::WriterContour::from_u8(
+                writer.contour.load(std::sync::atomic::Ordering::Relaxed),
+            ),
+            crate::transport::middle_proxy::pool::WriterContour::Active
+        ) {
+            continue;
+        }
+        let key = (writer.writer_dc, writer.addr);
+        *live_addr_counts.entry(key).or_insert(0) += 1;
+        live_writer_ids_by_addr
+            .entry(key)
+            .or_default()
+            .push(writer.id);
+    }
+    let writer_idle_since = pool.registry.writer_idle_since_snapshot().await;
+    let bound_clients_by_writer = pool
+        .registry
+        .writer_activity_snapshot()
+        .await
+        .bound_clients_by_writer;
+    let floor_plan = build_family_floor_plan(
+        pool,
+        family,
+        &dc_endpoints,
+        &live_addr_counts,
+        &live_writer_ids_by_addr,
+        &bound_clients_by_writer,
+    )
+    .await;
+    pool.set_adaptive_floor_runtime_caps(
+        floor_plan.active_cap_configured_total,
+        floor_plan.active_cap_effective_total,
+        floor_plan.warm_cap_configured_total,
+        floor_plan.warm_cap_effective_total,
+        floor_plan.target_writers_total,
+        floor_plan.active_writers_current,
+        floor_plan.warm_writers_current,
+    );
+    let live_writer_ids_by_addr = Arc::new(live_writer_ids_by_addr);
+    let writer_idle_since = Arc::new(writer_idle_since);
+    let bound_clients_by_writer = Arc::new(bound_clients_by_writer);
+    let mut reconnect_set = JoinSet::<FamilyReconnectOutcome>::new();
+    let mut scheduled_reconnects = ScheduledReconnects {
+        inflight,
+        keys: Vec::new(),
+    };
+
+    for (dc, endpoints) in dc_endpoints {
+        if endpoints.is_empty() {
+            continue;
+        }
+        let key = (dc, family);
+        let required = floor_plan
+            .by_dc
+            .get(&dc)
+            .map(|entry| entry.target_required)
+            .unwrap_or_else(|| {
+                pool.required_writers_for_dc_with_floor_mode(endpoints.len(), false)
+            });
+        let alive = endpoints
+            .iter()
+            .map(|addr| *live_addr_counts.get(&(dc, *addr)).unwrap_or(&0))
+            .sum::<usize>();
+
+        if endpoints.len() == 1 && pool.single_endpoint_outage_mode_enabled() && alive == 0 {
+            family_degraded = true;
+            if single_endpoint_outage.insert(key) {
+                pool.stats.increment_me_single_endpoint_outage_enter_total();
+                warn!(
+                    dc = %dc,
+                    ?family,
+                    required,
+                    endpoint_count = endpoints.len(),
+                    "Single-endpoint DC outage detected"
+                );
+            }
+
+            recover_single_endpoint_outage(
+                pool,
+                rng,
+                key,
+                endpoints[0],
+                required,
+                outage_backoff,
+                outage_next_attempt,
+                &reconnect_sem,
+            )
+            .await;
+            continue;
+        }
+
+        if single_endpoint_outage.remove(&key) {
+            pool.stats.increment_me_single_endpoint_outage_exit_total();
+            outage_backoff.remove(&key);
+            outage_next_attempt.remove(&key);
+            shadow_rotate_deadline.remove(&key);
+            idle_refresh_next_attempt.remove(&key);
+            info!(
+                dc = %dc,
+                ?family,
+                alive,
+                required,
+                endpoint_count = endpoints.len(),
+                "Single-endpoint DC outage recovered"
+            );
+        }
+
+        if alive >= required {
+            maybe_refresh_idle_writer_for_dc(
+                pool,
+                rng,
+                key,
+                dc,
+                family,
+                &endpoints,
+                alive,
+                required,
+                live_writer_ids_by_addr.as_ref(),
+                writer_idle_since.as_ref(),
+                bound_clients_by_writer.as_ref(),
+                idle_refresh_next_attempt,
+            )
+            .await;
+            maybe_rotate_single_endpoint_shadow(
+                pool,
+                rng,
+                key,
+                dc,
+                family,
+                &endpoints,
+                alive,
+                required,
+                live_writer_ids_by_addr.as_ref(),
+                bound_clients_by_writer.as_ref(),
+                shadow_rotate_deadline,
+            )
+            .await;
+            continue;
+        }
+        let missing = required - alive;
+        family_degraded = true;
+
+        let now = Instant::now();
+        if reconnect_sem.available_permits() == 0 {
+            let base_ms = pool.reconnect_runtime.me_reconnect_backoff_base.as_millis() as u64;
+            let next_ms = (*backoff.get(&key).unwrap_or(&base_ms)).max(base_ms);
+            let jitter = next_ms / JITTER_FRAC_NUM;
+            let wait = Duration::from_millis(next_ms)
+                + Duration::from_millis(rand::rng().random_range(0..=jitter.max(1)));
+            next_attempt.insert(key, now + wait);
+            debug!(
+                dc = %dc,
+                ?family,
+                alive,
+                required,
+                endpoint_count = endpoints.len(),
+                reconnect_budget,
+                "Skipping reconnect due to per-tick health reconnect budget"
+            );
+            continue;
+        }
+        if let Some(ts) = next_attempt.get(&key)
+            && now < *ts
+        {
+            continue;
+        }
+
+        let max_concurrent = pool
+            .reconnect_runtime
+            .me_reconnect_max_concurrent_per_dc
+            .max(1) as usize;
+        if scheduled_reconnects.current(&key) >= max_concurrent {
+            continue;
+        }
+        if pool
+            .has_refill_inflight_for_dc_key(crate::transport::middle_proxy::pool::RefillDcKey {
+                dc,
+                family,
+            })
+            .await
+        {
+            debug!(
+                dc = %dc,
+                ?family,
+                alive,
+                required,
+                endpoint_count = endpoints.len(),
+                "Skipping health reconnect: immediate refill is already in flight for this DC group"
+            );
+            continue;
+        }
+        scheduled_reconnects.reserve(key);
+        let pool_for_reconnect = pool.clone();
+        let rng_for_reconnect = rng.clone();
+        let reconnect_sem_for_dc = reconnect_sem.clone();
+        let endpoints_for_dc = endpoints.clone();
+        let live_writer_ids_by_addr_for_dc = live_writer_ids_by_addr.clone();
+        let writer_idle_since_for_dc = writer_idle_since.clone();
+        let bound_clients_by_writer_for_dc = bound_clients_by_writer.clone();
+        let active_cap_effective_total = floor_plan.active_cap_effective_total;
+        reconnect_set.spawn(async move {
+            let mut restored = 0usize;
+            for _ in 0..missing {
+                let Ok(reconnect_permit) = reconnect_sem_for_dc.clone().try_acquire_owned() else {
+                    break;
+                };
+                if pool_for_reconnect.active_contour_writer_count_total().await
+                    >= active_cap_effective_total
+                {
+                    let swapped = maybe_swap_idle_writer_for_cap(
+                        &pool_for_reconnect,
+                        &rng_for_reconnect,
+                        dc,
+                        family,
+                        &endpoints_for_dc,
+                        live_writer_ids_by_addr_for_dc.as_ref(),
+                        writer_idle_since_for_dc.as_ref(),
+                        bound_clients_by_writer_for_dc.as_ref(),
+                    )
+                    .await;
+                    if swapped {
+                        pool_for_reconnect
+                            .stats
+                            .increment_me_floor_swap_idle_total();
+                        restored += 1;
+                        continue;
+                    }
+
+                    let base_req = pool_for_reconnect
+                        .required_writers_for_dc_with_floor_mode(endpoints_for_dc.len(), false);
+                    if alive + restored >= base_req {
+                        pool_for_reconnect
+                            .stats
+                            .increment_me_floor_cap_block_total();
+                        pool_for_reconnect
+                            .stats
+                            .increment_me_floor_swap_idle_failed_total();
+                        debug!(
+                            dc = %dc,
+                            ?family,
+                            alive,
+                            required,
+                            active_cap_effective_total,
+                            "Adaptive floor cap reached, reconnect attempt blocked"
+                        );
+                        break;
+                    }
+                }
+                pool_for_reconnect.stats.increment_me_reconnect_attempt();
+                let res = tokio::time::timeout(
+                    pool_for_reconnect.reconnect_runtime.me_one_timeout,
+                    pool_for_reconnect.connect_endpoints_round_robin(
+                        dc,
+                        &endpoints_for_dc,
+                        rng_for_reconnect.as_ref(),
+                    ),
+                )
+                .await;
+                match res {
+                    Ok(true) => {
+                        restored += 1;
+                        pool_for_reconnect.stats.increment_me_reconnect_success();
+                    }
+                    Ok(false) => {
+                        debug!(dc = %dc, ?family, "ME round-robin reconnect failed")
+                    }
+                    Err(_) => {
+                        debug!(dc = %dc, ?family, "ME reconnect timed out");
+                    }
+                }
+                drop(reconnect_permit);
+            }
+
+            FamilyReconnectOutcome {
+                key,
+                dc,
+                family,
+                required,
+                endpoint_count: endpoints_for_dc.len(),
+            }
+        });
+    }
+
+    while let Some(joined) = reconnect_set.join_next().await {
+        let outcome = match joined {
+            Ok(outcome) => outcome,
+            Err(join_error) => {
+                debug!(error = %join_error, "Health reconnect task failed");
+                continue;
+            }
+        };
+        let now = Instant::now();
+        let now_alive = live_active_writers_for_dc_family(pool, outcome.dc, outcome.family).await;
+        if now_alive >= outcome.required {
+            info!(
+                dc = %outcome.dc,
+                family = ?outcome.family,
+                alive = now_alive,
+                required = outcome.required,
+                endpoint_count = outcome.endpoint_count,
+                "ME writer floor restored for DC"
+            );
+            backoff.insert(
+                outcome.key,
+                pool.reconnect_runtime.me_reconnect_backoff_base.as_millis() as u64,
+            );
+            let jitter = pool.reconnect_runtime.me_reconnect_backoff_base.as_millis() as u64
+                / JITTER_FRAC_NUM;
+            let wait = pool.reconnect_runtime.me_reconnect_backoff_base
+                + Duration::from_millis(rand::rng().random_range(0..=jitter.max(1)));
+            next_attempt.insert(outcome.key, now + wait);
+        } else {
+            let curr = *backoff
+                .get(&outcome.key)
+                .unwrap_or(&(pool.reconnect_runtime.me_reconnect_backoff_base.as_millis() as u64));
+            let next_ms = (curr.saturating_mul(2))
+                .min(pool.reconnect_runtime.me_reconnect_backoff_cap.as_millis() as u64);
+            backoff.insert(outcome.key, next_ms);
+            let jitter = next_ms / JITTER_FRAC_NUM;
+            let wait = Duration::from_millis(next_ms)
+                + Duration::from_millis(rand::rng().random_range(0..=jitter.max(1)));
+            next_attempt.insert(outcome.key, now + wait);
+            if pool.is_runtime_ready() {
+                let warn_cooldown = pool.warn_rate_limit_duration();
+                if should_emit_rate_limited_warn(
+                    floor_warn_next_allowed,
+                    outcome.key,
+                    now,
+                    warn_cooldown,
+                ) {
+                    warn!(
+                        dc = %outcome.dc,
+                        family = ?outcome.family,
+                        alive = now_alive,
+                        required = outcome.required,
+                        endpoint_count = outcome.endpoint_count,
+                        backoff_ms = next_ms,
+                        "DC writer floor is below required level, scheduled reconnect"
+                    );
+                }
+            } else {
+                info!(
+                    dc = %outcome.dc,
+                    family = ?outcome.family,
+                    alive = now_alive,
+                    required = outcome.required,
+                    endpoint_count = outcome.endpoint_count,
+                    backoff_ms = next_ms,
+                    "DC writer floor is below required level during startup, scheduled reconnect"
+                );
+            }
+        }
+    }
+
+    family_degraded
+}
+
+pub(super) fn health_reconnect_budget(pool: &Arc<MePool>, dc_groups: usize) -> usize {
+    let cpu_cores = pool.adaptive_floor_effective_cpu_cores().max(1);
+    let by_cpu = cpu_cores.saturating_mul(HEALTH_RECONNECT_BUDGET_PER_CORE);
+    let by_dc = dc_groups.saturating_mul(HEALTH_RECONNECT_BUDGET_PER_DC);
+    by_cpu
+        .saturating_add(by_dc)
+        .clamp(HEALTH_RECONNECT_BUDGET_MIN, HEALTH_RECONNECT_BUDGET_MAX)
+}
+
+pub(super) fn update_family_runtime_state(pool: &Arc<MePool>, family: IpFamily, degraded: bool) {
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let previous_state = pool.family_runtime_state(family);
+    let mut state_since_epoch_secs = pool.family_runtime_state_since_epoch_secs(family);
+    let previous_suppressed_until_epoch_secs = pool.family_suppressed_until_epoch_secs(family);
+    let previous_fail_streak = pool.family_fail_streak(family);
+    let previous_recover_success_streak = pool.family_recover_success_streak(family);
+
+    let (next_state, suppressed_until_epoch_secs, fail_streak, recover_success_streak) =
+        if previous_suppressed_until_epoch_secs > now_epoch_secs {
+            let fail_streak = if degraded {
+                previous_fail_streak.saturating_add(1)
+            } else {
+                previous_fail_streak
+            };
+            (
+                MeFamilyRuntimeState::Suppressed,
+                previous_suppressed_until_epoch_secs,
+                fail_streak,
+                0,
+            )
+        } else if degraded {
+            let fail_streak = previous_fail_streak.saturating_add(1);
+            if fail_streak >= FAMILY_SUPPRESS_FAIL_STREAK_THRESHOLD {
+                (
+                    MeFamilyRuntimeState::Suppressed,
+                    now_epoch_secs.saturating_add(FAMILY_SUPPRESS_DURATION_SECS),
+                    fail_streak,
+                    0,
+                )
+            } else {
+                (MeFamilyRuntimeState::Degraded, 0, fail_streak, 0)
+            }
+        } else if matches!(previous_state, MeFamilyRuntimeState::Healthy) {
+            (MeFamilyRuntimeState::Healthy, 0, 0, 0)
+        } else {
+            let recover_success_streak = previous_recover_success_streak.saturating_add(1);
+            if recover_success_streak >= FAMILY_RECOVER_SUCCESS_STREAK_TARGET {
+                (MeFamilyRuntimeState::Healthy, 0, 0, 0)
+            } else {
+                (
+                    MeFamilyRuntimeState::Recovering,
+                    0,
+                    0,
+                    recover_success_streak,
+                )
+            }
+        };
+
+    if next_state != previous_state || state_since_epoch_secs == 0 {
+        state_since_epoch_secs = now_epoch_secs;
+    }
+    pool.set_family_runtime_state(
+        family,
+        next_state,
+        state_since_epoch_secs,
+        suppressed_until_epoch_secs,
+        fail_streak,
+        recover_success_streak,
+    );
+}

src/transport/middle_proxy/health/floor_plan.rs

@@ -0,0 +1,261 @@
+use super::*;
+
+pub(super) fn should_emit_rate_limited_warn(
+    next_allowed: &mut HashMap<(i32, IpFamily), Instant>,
+    key: (i32, IpFamily),
+    now: Instant,
+    cooldown: Duration,
+) -> bool {
+    let Some(ready_at) = next_allowed.get(&key).copied() else {
+        next_allowed.insert(key, now + cooldown);
+        return true;
+    };
+    if now >= ready_at {
+        next_allowed.insert(key, now + cooldown);
+        return true;
+    }
+    false
+}
+
+pub(super) async fn live_active_writers_for_dc_family(
+    pool: &Arc<MePool>,
+    dc: i32,
+    family: IpFamily,
+) -> usize {
+    let writers = pool.writers.read().await;
+    writers
+        .iter()
+        .filter(|writer| {
+            if writer.draining.load(std::sync::atomic::Ordering::Relaxed) {
+                return false;
+            }
+            if writer.writer_dc != dc {
+                return false;
+            }
+            if !matches!(
+                crate::transport::middle_proxy::pool::WriterContour::from_u8(
+                    writer.contour.load(std::sync::atomic::Ordering::Relaxed),
+                ),
+                crate::transport::middle_proxy::pool::WriterContour::Active
+            ) {
+                return false;
+            }
+            match family {
+                IpFamily::V4 => writer.addr.is_ipv4(),
+                IpFamily::V6 => writer.addr.is_ipv6(),
+            }
+        })
+        .count()
+}
+
+pub(super) fn adaptive_floor_class_min(
+    pool: &Arc<MePool>,
+    endpoint_count: usize,
+    base_required: usize,
+) -> usize {
+    if endpoint_count <= 1 {
+        let min_single = (pool
+            .floor_runtime
+            .me_adaptive_floor_min_writers_single_endpoint
+            .load(std::sync::atomic::Ordering::Relaxed) as usize)
+            .max(1);
+        min_single.min(base_required.max(1))
+    } else {
+        pool.adaptive_floor_min_writers_multi_endpoint()
+            .min(base_required.max(1))
+    }
+}
+
+pub(super) fn adaptive_floor_class_max(
+    pool: &Arc<MePool>,
+    endpoint_count: usize,
+    base_required: usize,
+    cpu_cores: usize,
+) -> usize {
+    let extra_per_core = if endpoint_count <= 1 {
+        pool.adaptive_floor_max_extra_single_per_core()
+    } else {
+        pool.adaptive_floor_max_extra_multi_per_core()
+    };
+    base_required.saturating_add(cpu_cores.saturating_mul(extra_per_core))
+}
+
+pub(super) fn list_writer_ids_for_endpoints(
+    dc: i32,
+    endpoints: &[SocketAddr],
+    live_writer_ids_by_addr: &HashMap<(i32, SocketAddr), Vec<u64>>,
+) -> Vec<u64> {
+    let mut out = Vec::<u64>::new();
+    for endpoint in endpoints {
+        if let Some(ids) = live_writer_ids_by_addr.get(&(dc, *endpoint)) {
+            out.extend(ids.iter().copied());
+        }
+    }
+    out
+}
+
+pub(super) async fn build_family_floor_plan(
+    pool: &Arc<MePool>,
+    family: IpFamily,
+    dc_endpoints: &HashMap<i32, Vec<SocketAddr>>,
+    live_addr_counts: &HashMap<(i32, SocketAddr), usize>,
+    live_writer_ids_by_addr: &HashMap<(i32, SocketAddr), Vec<u64>>,
+    bound_clients_by_writer: &HashMap<u64, usize>,
+) -> FamilyFloorPlan {
+    let mut entries = Vec::<DcFloorPlanEntry>::new();
+    let mut by_dc = HashMap::<i32, DcFloorPlanEntry>::new();
+    let mut family_active_total = 0usize;
+
+    let floor_mode = pool.floor_mode();
+    let is_adaptive = floor_mode == MeFloorMode::Adaptive;
+    let cpu_cores = pool.adaptive_floor_effective_cpu_cores().max(1);
+    let (active_writers_current, warm_writers_current, _) =
+        pool.non_draining_writer_counts_by_contour().await;
+
+    for (dc, endpoints) in dc_endpoints {
+        if endpoints.is_empty() {
+            continue;
+        }
+        let _key = (*dc, family);
+        let base_required = pool.required_writers_for_dc(endpoints.len()).max(1);
+        let min_required = if is_adaptive {
+            adaptive_floor_class_min(pool, endpoints.len(), base_required)
+        } else {
+            base_required
+        };
+        let mut max_required = if is_adaptive {
+            adaptive_floor_class_max(pool, endpoints.len(), base_required, cpu_cores)
+        } else {
+            base_required
+        };
+        if max_required < min_required {
+            max_required = min_required;
+        }
+        // We initialize target_required at base_required to prevent 0-writer blackouts
+        // caused by proactively dropping an idle DC to a single fragile connection.
+        // The Adaptive Floor constraint loop below will gracefully compress idle DCs
+        // (prioritized via has_bound_clients = false) to min_required only when global capacity is reached.
+        let desired_raw = base_required;
+        let target_required = desired_raw.clamp(min_required, max_required);
+        let alive = endpoints
+            .iter()
+            .map(|endpoint| {
+                live_addr_counts
+                    .get(&(*dc, *endpoint))
+                    .copied()
+                    .unwrap_or(0)
+            })
+            .sum::<usize>();
+        family_active_total = family_active_total.saturating_add(alive);
+        let writer_ids = list_writer_ids_for_endpoints(*dc, endpoints, live_writer_ids_by_addr);
+        let has_bound_clients = has_bound_clients_on_endpoint(&writer_ids, bound_clients_by_writer);
+
+        entries.push(DcFloorPlanEntry {
+            dc: *dc,
+            endpoints: endpoints.clone(),
+            alive,
+            min_required,
+            target_required,
+            max_required,
+            has_bound_clients,
+            floor_capped: false,
+        });
+    }
+
+    if entries.is_empty() {
+        let active_cap_configured_total = pool.adaptive_floor_active_cap_configured_total();
+        let warm_cap_configured_total = pool.adaptive_floor_warm_cap_configured_total();
+        return FamilyFloorPlan {
+            by_dc,
+            active_cap_configured_total,
+            active_cap_effective_total: active_cap_configured_total,
+            warm_cap_configured_total,
+            warm_cap_effective_total: warm_cap_configured_total,
+            active_writers_current,
+            warm_writers_current,
+            target_writers_total: 0,
+        };
+    }
+
+    if !is_adaptive {
+        let target_total = entries
+            .iter()
+            .map(|entry| entry.target_required)
+            .sum::<usize>();
+        let active_cap_configured_total = pool.adaptive_floor_active_cap_configured_total();
+        let warm_cap_configured_total = pool.adaptive_floor_warm_cap_configured_total();
+        for entry in entries {
+            by_dc.insert(entry.dc, entry);
+        }
+        return FamilyFloorPlan {
+            by_dc,
+            active_cap_configured_total,
+            active_cap_effective_total: active_cap_configured_total.max(target_total),
+            warm_cap_configured_total,
+            warm_cap_effective_total: warm_cap_configured_total,
+            active_writers_current,
+            warm_writers_current,
+            target_writers_total: target_total,
+        };
+    }
+
+    let active_cap_configured_total = pool.adaptive_floor_active_cap_configured_total();
+    let warm_cap_configured_total = pool.adaptive_floor_warm_cap_configured_total();
+    let other_active = active_writers_current.saturating_sub(family_active_total);
+    let min_sum = entries
+        .iter()
+        .map(|entry| entry.min_required)
+        .sum::<usize>();
+    let mut target_sum = entries
+        .iter()
+        .map(|entry| entry.target_required)
+        .sum::<usize>();
+    let family_cap = active_cap_configured_total
+        .saturating_sub(other_active)
+        .max(min_sum);
+    if target_sum > family_cap {
+        entries.sort_by_key(|entry| {
+            (
+                entry.has_bound_clients,
+                std::cmp::Reverse(entry.target_required.saturating_sub(entry.min_required)),
+                std::cmp::Reverse(entry.alive),
+                entry.dc.abs(),
+                entry.dc,
+                entry.endpoints.len(),
+                entry.max_required,
+            )
+        });
+        let mut changed = true;
+        while target_sum > family_cap && changed {
+            changed = false;
+            for entry in &mut entries {
+                if target_sum <= family_cap {
+                    break;
+                }
+                if entry.target_required > entry.min_required {
+                    entry.target_required -= 1;
+                    entry.floor_capped = true;
+                    target_sum -= 1;
+                    changed = true;
+                }
+            }
+        }
+    }
+
+    for entry in entries {
+        by_dc.insert(entry.dc, entry);
+    }
+    let active_cap_effective_total =
+        active_cap_configured_total.max(other_active.saturating_add(min_sum));
+    let target_writers_total = other_active.saturating_add(target_sum);
+    FamilyFloorPlan {
+        by_dc,
+        active_cap_configured_total,
+        active_cap_effective_total,
+        warm_cap_configured_total,
+        warm_cap_effective_total: warm_cap_configured_total,
+        active_writers_current,
+        warm_writers_current,
+        target_writers_total,
+    }
+}

src/transport/middle_proxy/health/idle_refresh.rs

@@ -0,0 +1,203 @@
+use super::*;
+
+pub(super) async fn maybe_swap_idle_writer_for_cap(
+    pool: &Arc<MePool>,
+    rng: &Arc<SecureRandom>,
+    dc: i32,
+    family: IpFamily,
+    endpoints: &[SocketAddr],
+    live_writer_ids_by_addr: &HashMap<(i32, SocketAddr), Vec<u64>>,
+    writer_idle_since: &HashMap<u64, u64>,
+    bound_clients_by_writer: &HashMap<u64, usize>,
+) -> bool {
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut candidate: Option<(u64, SocketAddr, u64)> = None;
+    for endpoint in endpoints {
+        let Some(writer_ids) = live_writer_ids_by_addr.get(&(dc, *endpoint)) else {
+            continue;
+        };
+        for writer_id in writer_ids {
+            if bound_clients_by_writer.get(writer_id).copied().unwrap_or(0) > 0 {
+                continue;
+            }
+            let Some(idle_since_epoch_secs) = writer_idle_since.get(writer_id).copied() else {
+                continue;
+            };
+            let idle_age_secs = now_epoch_secs.saturating_sub(idle_since_epoch_secs);
+            if candidate
+                .as_ref()
+                .map(|(_, _, age)| idle_age_secs > *age)
+                .unwrap_or(true)
+            {
+                candidate = Some((*writer_id, *endpoint, idle_age_secs));
+            }
+        }
+    }
+
+    let Some((old_writer_id, endpoint, idle_age_secs)) = candidate else {
+        return false;
+    };
+
+    let connected = match tokio::time::timeout(
+        pool.reconnect_runtime.me_one_timeout,
+        pool.connect_one_for_dc(endpoint, dc, rng.as_ref()),
+    )
+    .await
+    {
+        Ok(Ok(())) => true,
+        Ok(Err(error)) => {
+            debug!(
+                dc = %dc,
+                ?family,
+                %endpoint,
+                old_writer_id,
+                idle_age_secs,
+                %error,
+                "Adaptive floor cap swap connect failed"
+            );
+            false
+        }
+        Err(_) => {
+            debug!(
+                dc = %dc,
+                ?family,
+                %endpoint,
+                old_writer_id,
+                idle_age_secs,
+                "Adaptive floor cap swap connect timed out"
+            );
+            false
+        }
+    };
+    if !connected {
+        return false;
+    }
+
+    pool.mark_writer_draining_with_timeout(old_writer_id, pool.force_close_timeout(), false)
+        .await;
+    info!(
+        dc = %dc,
+        ?family,
+        %endpoint,
+        old_writer_id,
+        idle_age_secs,
+        "Adaptive floor cap swap: idle writer rotated"
+    );
+    true
+}
+
+pub(super) async fn maybe_refresh_idle_writer_for_dc(
+    pool: &Arc<MePool>,
+    rng: &Arc<SecureRandom>,
+    key: (i32, IpFamily),
+    dc: i32,
+    family: IpFamily,
+    endpoints: &[SocketAddr],
+    alive: usize,
+    required: usize,
+    live_writer_ids_by_addr: &HashMap<(i32, SocketAddr), Vec<u64>>,
+    writer_idle_since: &HashMap<u64, u64>,
+    bound_clients_by_writer: &HashMap<u64, usize>,
+    idle_refresh_next_attempt: &mut HashMap<(i32, IpFamily), Instant>,
+) {
+    if alive < required {
+        return;
+    }
+
+    let now = Instant::now();
+    if let Some(next) = idle_refresh_next_attempt.get(&key)
+        && now < *next
+    {
+        return;
+    }
+
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut candidate: Option<(u64, SocketAddr, u64, u64)> = None;
+    for endpoint in endpoints {
+        let Some(writer_ids) = live_writer_ids_by_addr.get(&(dc, *endpoint)) else {
+            continue;
+        };
+        for writer_id in writer_ids {
+            if bound_clients_by_writer.get(writer_id).copied().unwrap_or(0) > 0 {
+                continue;
+            }
+            let Some(idle_since_epoch_secs) = writer_idle_since.get(writer_id).copied() else {
+                continue;
+            };
+            let idle_age_secs = now_epoch_secs.saturating_sub(idle_since_epoch_secs);
+            let threshold_secs = IDLE_REFRESH_TRIGGER_BASE_SECS
+                + (*writer_id % (IDLE_REFRESH_TRIGGER_JITTER_SECS + 1));
+            if idle_age_secs < threshold_secs {
+                continue;
+            }
+            if candidate
+                .as_ref()
+                .map(|(_, _, age, _)| idle_age_secs > *age)
+                .unwrap_or(true)
+            {
+                candidate = Some((*writer_id, *endpoint, idle_age_secs, threshold_secs));
+            }
+        }
+    }
+
+    let Some((old_writer_id, endpoint, idle_age_secs, threshold_secs)) = candidate else {
+        return;
+    };
+
+    let rotate_ok = match tokio::time::timeout(
+        pool.reconnect_runtime.me_one_timeout,
+        pool.connect_one_for_dc(endpoint, dc, rng.as_ref()),
+    )
+    .await
+    {
+        Ok(Ok(())) => true,
+        Ok(Err(error)) => {
+            debug!(
+                dc = %dc,
+                ?family,
+                %endpoint,
+                old_writer_id,
+                idle_age_secs,
+                threshold_secs,
+                %error,
+                "Idle writer pre-refresh connect failed"
+            );
+            false
+        }
+        Err(_) => {
+            debug!(
+                dc = %dc,
+                ?family,
+                %endpoint,
+                old_writer_id,
+                idle_age_secs,
+                threshold_secs,
+                "Idle writer pre-refresh connect timed out"
+            );
+            false
+        }
+    };
+
+    if !rotate_ok {
+        idle_refresh_next_attempt.insert(key, now + Duration::from_secs(IDLE_REFRESH_RETRY_SECS));
+        return;
+    }
+
+    pool.mark_writer_draining_with_timeout(old_writer_id, pool.force_close_timeout(), false)
+        .await;
+    idle_refresh_next_attempt.insert(
+        key,
+        now + Duration::from_secs(IDLE_REFRESH_SUCCESS_GUARD_SECS),
+    );
+    info!(
+        dc = %dc,
+        ?family,
+        %endpoint,
+        old_writer_id,
+        idle_age_secs,
+        threshold_secs,
+        alive,
+        required,
+        "Idle writer refreshed before upstream idle timeout"
+    );
+}

src/transport/middle_proxy/health/monitor.rs

@@ -0,0 +1,59 @@
+use super::*;
+
+pub async fn me_health_monitor(pool: Arc<MePool>, rng: Arc<SecureRandom>, _min_connections: usize) {
+    let mut backoff: HashMap<(i32, IpFamily), u64> = HashMap::new();
+    let mut next_attempt: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut inflight: HashMap<(i32, IpFamily), usize> = HashMap::new();
+    let mut outage_backoff: HashMap<(i32, IpFamily), u64> = HashMap::new();
+    let mut outage_next_attempt: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut single_endpoint_outage: HashSet<(i32, IpFamily)> = HashSet::new();
+    let mut shadow_rotate_deadline: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut idle_refresh_next_attempt: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut floor_warn_next_allowed: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut drain_warn_next_allowed: HashMap<u64, Instant> = HashMap::new();
+    let mut degraded_interval = true;
+    loop {
+        let interval = if degraded_interval {
+            pool.health_interval_unhealthy()
+        } else {
+            pool.health_interval_healthy()
+        };
+        tokio::time::sleep(interval).await;
+        pool.prune_closed_writers().await;
+        pool.sweep_endpoint_quarantine().await;
+        reap_draining_writers(&pool, &mut drain_warn_next_allowed).await;
+        let v4_degraded = check_family(
+            IpFamily::V4,
+            &pool,
+            &rng,
+            &mut backoff,
+            &mut next_attempt,
+            &mut inflight,
+            &mut outage_backoff,
+            &mut outage_next_attempt,
+            &mut single_endpoint_outage,
+            &mut shadow_rotate_deadline,
+            &mut idle_refresh_next_attempt,
+            &mut floor_warn_next_allowed,
+        )
+        .await;
+        let v6_degraded = check_family(
+            IpFamily::V6,
+            &pool,
+            &rng,
+            &mut backoff,
+            &mut next_attempt,
+            &mut inflight,
+            &mut outage_backoff,
+            &mut outage_next_attempt,
+            &mut single_endpoint_outage,
+            &mut shadow_rotate_deadline,
+            &mut idle_refresh_next_attempt,
+            &mut floor_warn_next_allowed,
+        )
+        .await;
+        update_family_runtime_state(&pool, IpFamily::V4, v4_degraded);
+        update_family_runtime_state(&pool, IpFamily::V6, v6_degraded);
+        degraded_interval = v4_degraded || v6_degraded;
+    }
+}

src/transport/middle_proxy/health/recovery.rs

@@ -0,0 +1,262 @@
+use super::*;
+
+pub(super) fn has_bound_clients_on_endpoint(
+    writer_ids: &[u64],
+    bound_clients_by_writer: &HashMap<u64, usize>,
+) -> bool {
+    writer_ids
+        .iter()
+        .any(|writer_id| bound_clients_by_writer.get(writer_id).copied().unwrap_or(0) > 0)
+}
+
+pub(super) async fn recover_single_endpoint_outage(
+    pool: &Arc<MePool>,
+    rng: &Arc<SecureRandom>,
+    key: (i32, IpFamily),
+    endpoint: SocketAddr,
+    required: usize,
+    outage_backoff: &mut HashMap<(i32, IpFamily), u64>,
+    outage_next_attempt: &mut HashMap<(i32, IpFamily), Instant>,
+    reconnect_sem: &Arc<Semaphore>,
+) {
+    let now = Instant::now();
+    if let Some(ts) = outage_next_attempt.get(&key)
+        && now < *ts
+    {
+        return;
+    }
+
+    let (min_backoff_ms, max_backoff_ms) = pool.single_endpoint_outage_backoff_bounds_ms();
+    if reconnect_sem.available_permits() == 0 {
+        outage_next_attempt.insert(key, now + Duration::from_millis(min_backoff_ms.max(250)));
+        debug!(
+            dc = %key.0,
+            family = ?key.1,
+            %endpoint,
+            required,
+            "Single-endpoint outage reconnect deferred by health reconnect budget"
+        );
+        return;
+    }
+    let Ok(_reconnect_permit) = reconnect_sem.clone().try_acquire_owned() else {
+        outage_next_attempt.insert(key, now + Duration::from_millis(min_backoff_ms.max(250)));
+        debug!(
+            dc = %key.0,
+            family = ?key.1,
+            %endpoint,
+            required,
+            "Single-endpoint outage reconnect deferred by semaphore saturation"
+        );
+        return;
+    };
+    pool.stats.increment_me_reconnect_attempt();
+    pool.stats
+        .increment_me_single_endpoint_outage_reconnect_attempt_total();
+
+    let bypass_quarantine = pool.single_endpoint_outage_disable_quarantine();
+    let attempt_ok = if bypass_quarantine {
+        pool.stats
+            .increment_me_single_endpoint_quarantine_bypass_total();
+        match tokio::time::timeout(
+            pool.reconnect_runtime.me_one_timeout,
+            pool.connect_one_for_dc(endpoint, key.0, rng.as_ref()),
+        )
+        .await
+        {
+            Ok(Ok(())) => true,
+            Ok(Err(e)) => {
+                debug!(
+                    dc = %key.0,
+                    family = ?key.1,
+                    %endpoint,
+                    error = %e,
+                    "Single-endpoint outage reconnect failed (quarantine bypass path)"
+                );
+                false
+            }
+            Err(_) => {
+                debug!(
+                    dc = %key.0,
+                    family = ?key.1,
+                    %endpoint,
+                    "Single-endpoint outage reconnect timed out (quarantine bypass path)"
+                );
+                false
+            }
+        }
+    } else {
+        let one_endpoint = [endpoint];
+        match tokio::time::timeout(
+            pool.reconnect_runtime.me_one_timeout,
+            pool.connect_endpoints_round_robin(key.0, &one_endpoint, rng.as_ref()),
+        )
+        .await
+        {
+            Ok(ok) => ok,
+            Err(_) => {
+                debug!(
+                    dc = %key.0,
+                    family = ?key.1,
+                    %endpoint,
+                    "Single-endpoint outage reconnect timed out"
+                );
+                false
+            }
+        }
+    };
+
+    if attempt_ok {
+        pool.stats
+            .increment_me_single_endpoint_outage_reconnect_success_total();
+        pool.stats.increment_me_reconnect_success();
+        outage_backoff.insert(key, min_backoff_ms);
+        let jitter = min_backoff_ms / JITTER_FRAC_NUM;
+        let wait = Duration::from_millis(min_backoff_ms)
+            + Duration::from_millis(rand::rng().random_range(0..=jitter.max(1)));
+        outage_next_attempt.insert(key, now + wait);
+        info!(
+            dc = %key.0,
+            family = ?key.1,
+            %endpoint,
+            required,
+            backoff_ms = min_backoff_ms,
+            "Single-endpoint outage reconnect succeeded"
+        );
+        return;
+    }
+
+    let current_ms = *outage_backoff.get(&key).unwrap_or(&min_backoff_ms);
+    let next_ms = current_ms.saturating_mul(2).min(max_backoff_ms);
+    outage_backoff.insert(key, next_ms);
+    let jitter = next_ms / JITTER_FRAC_NUM;
+    let wait = Duration::from_millis(next_ms)
+        + Duration::from_millis(rand::rng().random_range(0..=jitter.max(1)));
+    outage_next_attempt.insert(key, now + wait);
+    warn!(
+        dc = %key.0,
+        family = ?key.1,
+        %endpoint,
+        required,
+        backoff_ms = next_ms,
+        "Single-endpoint outage reconnect scheduled"
+    );
+}
+
+pub(super) async fn maybe_rotate_single_endpoint_shadow(
+    pool: &Arc<MePool>,
+    rng: &Arc<SecureRandom>,
+    key: (i32, IpFamily),
+    dc: i32,
+    family: IpFamily,
+    endpoints: &[SocketAddr],
+    alive: usize,
+    required: usize,
+    live_writer_ids_by_addr: &HashMap<(i32, SocketAddr), Vec<u64>>,
+    bound_clients_by_writer: &HashMap<u64, usize>,
+    shadow_rotate_deadline: &mut HashMap<(i32, IpFamily), Instant>,
+) {
+    if endpoints.len() != 1 || alive < required {
+        return;
+    }
+
+    let Some(interval) = pool.single_endpoint_shadow_rotate_interval() else {
+        return;
+    };
+
+    let now = Instant::now();
+    if let Some(deadline) = shadow_rotate_deadline.get(&key)
+        && now < *deadline
+    {
+        return;
+    }
+
+    let endpoint = endpoints[0];
+    if pool.is_endpoint_quarantined(endpoint).await {
+        pool.stats
+            .increment_me_single_endpoint_shadow_rotate_skipped_quarantine_total();
+        shadow_rotate_deadline.insert(key, now + Duration::from_secs(SHADOW_ROTATE_RETRY_SECS));
+        debug!(
+            dc = %dc,
+            ?family,
+            %endpoint,
+            "Single-endpoint shadow rotation skipped: endpoint is quarantined"
+        );
+        return;
+    }
+
+    let Some(writer_ids) = live_writer_ids_by_addr.get(&(dc, endpoint)) else {
+        shadow_rotate_deadline.insert(key, now + Duration::from_secs(SHADOW_ROTATE_RETRY_SECS));
+        return;
+    };
+
+    let mut candidate_writer_id = None;
+    for writer_id in writer_ids {
+        if bound_clients_by_writer.get(writer_id).copied().unwrap_or(0) == 0 {
+            candidate_writer_id = Some(*writer_id);
+            break;
+        }
+    }
+
+    let Some(old_writer_id) = candidate_writer_id else {
+        shadow_rotate_deadline.insert(key, now + Duration::from_secs(SHADOW_ROTATE_RETRY_SECS));
+        debug!(
+            dc = %dc,
+            ?family,
+            %endpoint,
+            alive,
+            required,
+            "Single-endpoint shadow rotation skipped: no empty writer candidate"
+        );
+        return;
+    };
+
+    let rotate_ok = match tokio::time::timeout(
+        pool.reconnect_runtime.me_one_timeout,
+        pool.connect_one_for_dc(endpoint, dc, rng.as_ref()),
+    )
+    .await
+    {
+        Ok(Ok(())) => true,
+        Ok(Err(e)) => {
+            debug!(
+                dc = %dc,
+                ?family,
+                %endpoint,
+                error = %e,
+                "Single-endpoint shadow rotation connect failed"
+            );
+            false
+        }
+        Err(_) => {
+            debug!(
+                dc = %dc,
+                ?family,
+                %endpoint,
+                "Single-endpoint shadow rotation connect timed out"
+            );
+            false
+        }
+    };
+
+    if !rotate_ok {
+        shadow_rotate_deadline.insert(
+            key,
+            now + interval.min(Duration::from_secs(SHADOW_ROTATE_RETRY_SECS)),
+        );
+        return;
+    }
+
+    pool.mark_writer_draining_with_timeout(old_writer_id, pool.force_close_timeout(), false)
+        .await;
+    pool.stats
+        .increment_me_single_endpoint_shadow_rotate_total();
+    shadow_rotate_deadline.insert(key, now + interval);
+    info!(
+        dc = %dc,
+        ?family,
+        %endpoint,
+        old_writer_id,
+        rotate_every_secs = interval.as_secs(),
+        "Single-endpoint shadow writer rotated"
+    );
+}

src/transport/middle_proxy/health/tests.rs

@@ -0,0 +1,323 @@
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use super::{ScheduledReconnects, reap_draining_writers};
+use crate::config::{GeneralConfig, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode};
+use crate::crypto::SecureRandom;
+use crate::network::IpFamily;
+use crate::network::probe::NetworkDecision;
+use crate::stats::Stats;
+use crate::transport::middle_proxy::codec::WriterCommand;
+use crate::transport::middle_proxy::pool::{MePool, MeWriter, WriterContour};
+use crate::transport::middle_proxy::registry::ConnMeta;
+
+#[test]
+fn reconnect_batch_releases_every_reserved_key_after_join_failures() {
+    let retained = (1, IpFamily::V4);
+    let removed = (2, IpFamily::V6);
+    let mut inflight = HashMap::from([(retained, 1)]);
+
+    {
+        let mut scheduled = ScheduledReconnects {
+            inflight: &mut inflight,
+            keys: Vec::new(),
+        };
+        scheduled.reserve(retained);
+        scheduled.reserve(removed);
+    }
+
+    assert_eq!(inflight.get(&retained), Some(&1));
+    assert!(!inflight.contains_key(&removed));
+}
+
+async fn make_pool(me_pool_drain_threshold: u64) -> Arc<MePool> {
+    let general = GeneralConfig {
+        me_pool_drain_threshold,
+        ..GeneralConfig::default()
+    };
+    let mut proxy_map_v4 = HashMap::new();
+    proxy_map_v4.insert(2, vec![(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 10)), 443)]);
+    let decision = NetworkDecision {
+        ipv4_me: true,
+        ..NetworkDecision::default()
+    };
+    MePool::new(
+        None,
+        vec![1u8; 32],
+        None,
+        false,
+        None,
+        Vec::new(),
+        false,
+        Vec::new(),
+        1,
+        None,
+        12,
+        1200,
+        proxy_map_v4,
+        HashMap::new(),
+        None,
+        decision,
+        None,
+        Arc::new(SecureRandom::new()),
+        Arc::new(Stats::default()),
+        general.me_keepalive_enabled,
+        general.me_keepalive_interval_secs,
+        general.me_keepalive_jitter_secs,
+        general.me_keepalive_payload_random,
+        general.rpc_proxy_req_every,
+        general.me_warmup_stagger_enabled,
+        general.me_warmup_step_delay_ms,
+        general.me_warmup_step_jitter_ms,
+        general.me_reconnect_max_concurrent_per_dc,
+        general.me_reconnect_backoff_base_ms,
+        general.me_reconnect_backoff_cap_ms,
+        general.me_reconnect_fast_retry_count,
+        general.me_single_endpoint_shadow_writers,
+        general.me_single_endpoint_outage_mode_enabled,
+        general.me_single_endpoint_outage_disable_quarantine,
+        general.me_single_endpoint_outage_backoff_min_ms,
+        general.me_single_endpoint_outage_backoff_max_ms,
+        general.me_single_endpoint_shadow_rotate_every_secs,
+        general.me_floor_mode,
+        general.me_adaptive_floor_idle_secs,
+        general.me_adaptive_floor_min_writers_single_endpoint,
+        general.me_adaptive_floor_min_writers_multi_endpoint,
+        general.me_adaptive_floor_recover_grace_secs,
+        general.me_adaptive_floor_writers_per_core_total,
+        general.me_adaptive_floor_cpu_cores_override,
+        general.me_adaptive_floor_max_extra_writers_single_per_core,
+        general.me_adaptive_floor_max_extra_writers_multi_per_core,
+        general.me_adaptive_floor_max_active_writers_per_core,
+        general.me_adaptive_floor_max_warm_writers_per_core,
+        general.me_adaptive_floor_max_active_writers_global,
+        general.me_adaptive_floor_max_warm_writers_global,
+        general.hardswap,
+        general.me_pool_drain_ttl_secs,
+        general.me_instadrain,
+        general.me_pool_drain_threshold,
+        general.me_pool_drain_soft_evict_enabled,
+        general.me_pool_drain_soft_evict_grace_secs,
+        general.me_pool_drain_soft_evict_per_writer,
+        general.me_pool_drain_soft_evict_budget_per_core,
+        general.me_pool_drain_soft_evict_cooldown_ms,
+        general.effective_me_pool_force_close_secs(),
+        general.me_pool_min_fresh_ratio,
+        general.me_hardswap_warmup_delay_min_ms,
+        general.me_hardswap_warmup_delay_max_ms,
+        general.me_hardswap_warmup_extra_passes,
+        general.me_hardswap_warmup_pass_backoff_base_ms,
+        general.me_bind_stale_mode,
+        general.me_bind_stale_ttl_secs,
+        general.me_secret_atomic_snapshot,
+        general.me_deterministic_writer_sort,
+        MeWriterPickMode::default(),
+        general.me_writer_pick_sample_size,
+        MeSocksKdfPolicy::default(),
+        general.me_writer_cmd_channel_capacity,
+        general.me_writer_byte_budget_bytes,
+        general.me_route_channel_capacity,
+        general.me_route_backpressure_enabled,
+        general.me_route_fairshare_enabled,
+        general.me_route_backpressure_base_timeout_ms,
+        general.me_route_backpressure_high_timeout_ms,
+        general.me_route_backpressure_high_watermark_pct,
+        general.me_reader_route_data_wait_ms,
+        general.me_health_interval_ms_unhealthy,
+        general.me_health_interval_ms_healthy,
+        general.me_warn_rate_limit_ms,
+        MeRouteNoWriterMode::default(),
+        general.me_route_no_writer_wait_ms,
+        general.me_route_hybrid_max_wait_ms,
+        general.me_route_blocking_send_timeout_ms,
+        general.me_route_inline_recovery_attempts,
+        general.me_route_inline_recovery_wait_ms,
+        16_384,
+    )
+}
+
+async fn insert_draining_writer(
+    pool: &Arc<MePool>,
+    writer_id: u64,
+    drain_started_at_epoch_secs: u64,
+) -> u64 {
+    let (conn_id, _rx) = pool.registry.register().await;
+    let (tx, _writer_rx) = mpsc::channel::<WriterCommand>(8);
+    let byte_budget = pool.new_writer_byte_budget();
+    let writer = MeWriter {
+        id: writer_id,
+        addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 4000 + writer_id as u16),
+        source_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+        writer_dc: 2,
+        generation: 1,
+        contour: Arc::new(AtomicU8::new(WriterContour::Draining.as_u8())),
+        created_at: Instant::now() - Duration::from_secs(writer_id),
+        tx: tx.clone(),
+        byte_budget: byte_budget.clone(),
+        cancel: CancellationToken::new(),
+        degraded: Arc::new(AtomicBool::new(false)),
+        rtt_ema_ms_x10: Arc::new(AtomicU32::new(0)),
+        draining: Arc::new(AtomicBool::new(true)),
+        draining_started_at_epoch_secs: Arc::new(AtomicU64::new(drain_started_at_epoch_secs)),
+        drain_deadline_epoch_secs: Arc::new(AtomicU64::new(0)),
+        allow_drain_fallback: Arc::new(AtomicBool::new(false)),
+    };
+    pool.writers.write().await.push(writer);
+    pool.registry
+        .register_writer(writer_id, tx, byte_budget)
+        .await;
+    pool.conn_count.fetch_add(1, Ordering::Relaxed);
+    assert!(
+        pool.registry
+            .bind_writer(
+                conn_id,
+                writer_id,
+                ConnMeta {
+                    target_dc: 2,
+                    client_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 6000),
+                    our_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443),
+                    proto_flags: 0,
+                },
+            )
+            .await
+    );
+    conn_id
+}
+
+async fn insert_live_writer(pool: &Arc<MePool>, writer_id: u64, writer_dc: i32) {
+    let (tx, _writer_rx) = mpsc::channel::<WriterCommand>(8);
+    let byte_budget = pool.new_writer_byte_budget();
+    let writer = MeWriter {
+        id: writer_id,
+        addr: SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(
+                203,
+                0,
+                113,
+                (writer_id as u8).saturating_add(1),
+            )),
+            4000 + writer_id as u16,
+        ),
+        source_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+        writer_dc,
+        generation: 2,
+        contour: Arc::new(AtomicU8::new(WriterContour::Active.as_u8())),
+        created_at: Instant::now(),
+        tx: tx.clone(),
+        byte_budget: byte_budget.clone(),
+        cancel: CancellationToken::new(),
+        degraded: Arc::new(AtomicBool::new(false)),
+        rtt_ema_ms_x10: Arc::new(AtomicU32::new(0)),
+        draining: Arc::new(AtomicBool::new(false)),
+        draining_started_at_epoch_secs: Arc::new(AtomicU64::new(0)),
+        drain_deadline_epoch_secs: Arc::new(AtomicU64::new(0)),
+        allow_drain_fallback: Arc::new(AtomicBool::new(false)),
+    };
+    pool.writers.write().await.push(writer);
+    pool.registry
+        .register_writer(writer_id, tx, byte_budget)
+        .await;
+    pool.conn_count.fetch_add(1, Ordering::Relaxed);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_force_closes_oldest_over_threshold() {
+    let pool = make_pool(2).await;
+    insert_live_writer(&pool, 1, 2).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let conn_a = insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(30)).await;
+    let conn_b = insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(20)).await;
+    let conn_c = insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(10)).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    let mut writer_ids: Vec<u64> = pool
+        .writers
+        .read()
+        .await
+        .iter()
+        .map(|writer| writer.id)
+        .collect();
+    writer_ids.sort_unstable();
+    assert_eq!(writer_ids, vec![1, 20, 30]);
+    assert!(pool.registry.get_writer(conn_a).await.is_none());
+    assert_eq!(
+        pool.registry.get_writer(conn_b).await.unwrap().writer_id,
+        20
+    );
+    assert_eq!(
+        pool.registry.get_writer(conn_c).await.unwrap().writer_id,
+        30
+    );
+}
+
+#[tokio::test]
+async fn reap_draining_writers_force_closes_overflow_without_replacement() {
+    let pool = make_pool(2).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let conn_a = insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(30)).await;
+    let conn_b = insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(20)).await;
+    let conn_c = insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(10)).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    let mut writer_ids: Vec<u64> = pool
+        .writers
+        .read()
+        .await
+        .iter()
+        .map(|writer| writer.id)
+        .collect();
+    writer_ids.sort_unstable();
+    assert_eq!(writer_ids, vec![20, 30]);
+    assert!(pool.registry.get_writer(conn_a).await.is_none());
+    assert_eq!(
+        pool.registry.get_writer(conn_b).await.unwrap().writer_id,
+        20
+    );
+    assert_eq!(
+        pool.registry.get_writer(conn_c).await.unwrap().writer_id,
+        30
+    );
+}
+
+#[tokio::test]
+async fn reap_draining_writers_keeps_timeout_only_behavior_when_threshold_disabled() {
+    let pool = make_pool(0).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let conn_a = insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(30)).await;
+    let conn_b = insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(20)).await;
+    let conn_c = insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(10)).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    let writer_ids: Vec<u64> = pool
+        .writers
+        .read()
+        .await
+        .iter()
+        .map(|writer| writer.id)
+        .collect();
+    assert_eq!(writer_ids, vec![10, 20, 30]);
+    assert_eq!(
+        pool.registry.get_writer(conn_a).await.unwrap().writer_id,
+        10
+    );
+    assert_eq!(
+        pool.registry.get_writer(conn_b).await.unwrap().writer_id,
+        20
+    );
+    assert_eq!(
+        pool.registry.get_writer(conn_c).await.unwrap().writer_id,
+        30
+    );
+}

src/transport/middle_proxy/health/zombie_watchdog.rs

@@ -0,0 +1,146 @@
+use super::*;
+
+/// Last-resort safety net for draining writers stuck past their deadline.
+///
+/// Runs periodically and force-closes draining writers that remain past their deadline.
+/// The watchdog keeps independent lock and removal timeouts so a stalled writer cannot
+/// prevent subsequent writers from being inspected.
+pub async fn me_zombie_writer_watchdog(pool: Arc<MePool>) {
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    const TICK_SECS: u64 = 30;
+    const SOFT_THRESHOLD_SECS: u64 = 60;
+    const HARD_THRESHOLD_SECS: u64 = 300;
+    const LOCK_TIMEOUT_SECS: u64 = 5;
+    const REMOVE_TIMEOUT_SECS: u64 = 10;
+    const HARD_DETACH_TIMEOUT_STREAK: u8 = 3;
+
+    let mut removal_timeout_streak = HashMap::<u64, u8>::new();
+
+    loop {
+        tokio::time::sleep(Duration::from_secs(TICK_SECS)).await;
+
+        let now = match SystemTime::now().duration_since(UNIX_EPOCH) {
+            Ok(d) => d.as_secs(),
+            Err(_) => continue,
+        };
+
+        // Phase 1: collect zombie IDs under a short read-lock with timeout.
+        let zombie_ids_with_meta: Vec<(u64, bool)> = {
+            let Ok(ws) =
+                tokio::time::timeout(Duration::from_secs(LOCK_TIMEOUT_SECS), pool.writers.read())
+                    .await
+            else {
+                warn!("zombie_watchdog: writers read-lock timeout, skipping tick");
+                continue;
+            };
+            ws.iter()
+                .filter(|w| w.draining.load(std::sync::atomic::Ordering::Relaxed))
+                .filter_map(|w| {
+                    let deadline = w
+                        .drain_deadline_epoch_secs
+                        .load(std::sync::atomic::Ordering::Relaxed);
+                    if deadline == 0 {
+                        return None;
+                    }
+                    let overdue = now.saturating_sub(deadline);
+                    if overdue == 0 {
+                        return None;
+                    }
+                    let started = w
+                        .draining_started_at_epoch_secs
+                        .load(std::sync::atomic::Ordering::Relaxed);
+                    let drain_age = now.saturating_sub(started);
+                    if drain_age > HARD_THRESHOLD_SECS {
+                        return Some((w.id, true));
+                    }
+                    if overdue > SOFT_THRESHOLD_SECS {
+                        return Some((w.id, false));
+                    }
+                    None
+                })
+                .collect()
+        };
+        // read lock released here
+
+        if zombie_ids_with_meta.is_empty() {
+            removal_timeout_streak.clear();
+            continue;
+        }
+
+        let mut active_zombie_ids = HashSet::<u64>::with_capacity(zombie_ids_with_meta.len());
+        for (writer_id, _) in &zombie_ids_with_meta {
+            active_zombie_ids.insert(*writer_id);
+        }
+        removal_timeout_streak.retain(|writer_id, _| active_zombie_ids.contains(writer_id));
+
+        warn!(
+            zombie_count = zombie_ids_with_meta.len(),
+            soft_threshold_secs = SOFT_THRESHOLD_SECS,
+            hard_threshold_secs = HARD_THRESHOLD_SECS,
+            "Zombie draining writers detected by watchdog, force-closing"
+        );
+
+        // Phase 2: remove each writer individually with a timeout.
+        // One stuck removal cannot block the rest.
+        for (writer_id, had_clients) in &zombie_ids_with_meta {
+            let result = tokio::time::timeout(
+                Duration::from_secs(REMOVE_TIMEOUT_SECS),
+                pool.remove_writer_and_close_clients(*writer_id),
+            )
+            .await;
+            match result {
+                Ok(()) => {
+                    removal_timeout_streak.remove(writer_id);
+                    pool.stats.increment_pool_force_close_total();
+                    info!(writer_id, had_clients, "Zombie writer removed by watchdog");
+                }
+                Err(_) => {
+                    let streak = removal_timeout_streak
+                        .entry(*writer_id)
+                        .and_modify(|value| *value = value.saturating_add(1))
+                        .or_insert(1);
+                    warn!(
+                        writer_id,
+                        had_clients,
+                        timeout_streak = *streak,
+                        "Zombie writer removal timed out"
+                    );
+                    if *streak < HARD_DETACH_TIMEOUT_STREAK {
+                        continue;
+                    }
+
+                    let hard_detach = tokio::time::timeout(
+                        Duration::from_secs(REMOVE_TIMEOUT_SECS),
+                        pool.remove_draining_writer_hard_detach(*writer_id),
+                    )
+                    .await;
+                    match hard_detach {
+                        Ok(true) => {
+                            removal_timeout_streak.remove(writer_id);
+                            pool.stats.increment_pool_force_close_total();
+                            info!(
+                                writer_id,
+                                had_clients, "Zombie writer hard-detached after repeated timeouts"
+                            );
+                        }
+                        Ok(false) => {
+                            removal_timeout_streak.remove(writer_id);
+                            debug!(
+                                writer_id,
+                                had_clients,
+                                "Zombie hard-detach skipped (writer already gone or no longer draining)"
+                            );
+                        }
+                        Err(_) => {
+                            warn!(
+                                writer_id,
+                                had_clients, "Zombie hard-detach timed out, will retry next tick"
+                            );
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

src/transport/middle_proxy/http_fetch.rs

@@ -159,15 +159,15 @@ pub(crate) async fn https_get(
         HTTP_REQUEST_TIMEOUT,
         Limited::new(response.into_body(), max_body_bytes).collect(),
     )
-        .await
-        .map_err(|_| ProxyError::Proxy(format!("HTTP body read timeout for {url}")))?
-        .map_err(|e| {
-            ProxyError::Proxy(format!(
-                "HTTP body read failed or exceeded {max_body_bytes} bytes for {url}: {e}"
-            ))
-        })?
-        .to_bytes()
-        .to_vec();
+    .await
+    .map_err(|_| ProxyError::Proxy(format!("HTTP body read timeout for {url}")))?
+    .map_err(|e| {
+        ProxyError::Proxy(format!(
+            "HTTP body read failed or exceeded {max_body_bytes} bytes for {url}: {e}"
+        ))
+    })?
+    .to_bytes()
+    .to_vec();
 
     Ok(HttpsGetResponse {
         status,

src/transport/middle_proxy/mod.rs

@@ -61,9 +61,9 @@ pub use ping::{
     MePingFamily, MePingReport, MePingSample, format_me_route, format_sample_line, run_me_ping,
 };
 pub use pool::MePool;
-pub(crate) use registry::ConnLease;
 #[allow(unused_imports)]
 pub use pool_nat::{detect_public_ip, stun_probe};
+pub(crate) use registry::ConnLease;
 pub use registry::ConnRegistry;
 pub use rotation::{MeReinitTrigger, me_reinit_scheduler, me_rotation_task};
 #[allow(unused_imports)]

src/transport/middle_proxy/pool/construction.rs

@@ -0,0 +1,412 @@
+use super::*;
+
+impl MePool {
+    pub(in crate::transport::middle_proxy) fn ratio_to_permille(ratio: f32) -> u32 {
+        let clamped = ratio.clamp(0.0, 1.0);
+        (clamped * 1000.0).round() as u32
+    }
+
+    pub(in crate::transport::middle_proxy) fn permille_to_ratio(permille: u32) -> f32 {
+        (permille.min(1000) as f32) / 1000.0
+    }
+
+    pub(in crate::transport::middle_proxy) fn now_epoch_secs() -> u64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs()
+    }
+
+    pub(in crate::transport::middle_proxy) fn normalize_force_close_secs(
+        force_close_secs: u64,
+    ) -> u64 {
+        if force_close_secs == 0 {
+            ME_FORCE_CLOSE_SAFETY_FALLBACK_SECS
+        } else {
+            force_close_secs
+        }
+    }
+
+    pub fn new(
+        proxy_tag: Option<Vec<u8>>,
+        proxy_secret: Vec<u8>,
+        nat_ip: Option<IpAddr>,
+        nat_probe: bool,
+        nat_stun: Option<String>,
+        nat_stun_servers: Vec<String>,
+        stun_tcp_fallback: bool,
+        http_ip_detect_urls: Vec<String>,
+        nat_probe_concurrency: usize,
+        detected_ipv6: Option<Ipv6Addr>,
+        me_one_retry: u8,
+        me_one_timeout_ms: u64,
+        proxy_map_v4: HashMap<i32, Vec<(IpAddr, u16)>>,
+        proxy_map_v6: HashMap<i32, Vec<(IpAddr, u16)>>,
+        default_dc: Option<i32>,
+        decision: NetworkDecision,
+        upstream: Option<Arc<UpstreamManager>>,
+        rng: Arc<SecureRandom>,
+        stats: Arc<crate::stats::Stats>,
+        me_keepalive_enabled: bool,
+        me_keepalive_interval_secs: u64,
+        me_keepalive_jitter_secs: u64,
+        me_keepalive_payload_random: bool,
+        rpc_proxy_req_every_secs: u64,
+        me_warmup_stagger_enabled: bool,
+        me_warmup_step_delay_ms: u64,
+        me_warmup_step_jitter_ms: u64,
+        me_reconnect_max_concurrent_per_dc: u32,
+        me_reconnect_backoff_base_ms: u64,
+        me_reconnect_backoff_cap_ms: u64,
+        me_reconnect_fast_retry_count: u32,
+        me_single_endpoint_shadow_writers: u8,
+        me_single_endpoint_outage_mode_enabled: bool,
+        me_single_endpoint_outage_disable_quarantine: bool,
+        me_single_endpoint_outage_backoff_min_ms: u64,
+        me_single_endpoint_outage_backoff_max_ms: u64,
+        me_single_endpoint_shadow_rotate_every_secs: u64,
+        me_floor_mode: MeFloorMode,
+        me_adaptive_floor_idle_secs: u64,
+        me_adaptive_floor_min_writers_single_endpoint: u8,
+        me_adaptive_floor_min_writers_multi_endpoint: u8,
+        me_adaptive_floor_recover_grace_secs: u64,
+        me_adaptive_floor_writers_per_core_total: u16,
+        me_adaptive_floor_cpu_cores_override: u16,
+        me_adaptive_floor_max_extra_writers_single_per_core: u16,
+        me_adaptive_floor_max_extra_writers_multi_per_core: u16,
+        me_adaptive_floor_max_active_writers_per_core: u16,
+        me_adaptive_floor_max_warm_writers_per_core: u16,
+        me_adaptive_floor_max_active_writers_global: u32,
+        me_adaptive_floor_max_warm_writers_global: u32,
+        hardswap: bool,
+        me_pool_drain_ttl_secs: u64,
+        me_instadrain: bool,
+        me_pool_drain_threshold: u64,
+        me_pool_drain_soft_evict_enabled: bool,
+        me_pool_drain_soft_evict_grace_secs: u64,
+        me_pool_drain_soft_evict_per_writer: u8,
+        me_pool_drain_soft_evict_budget_per_core: u16,
+        me_pool_drain_soft_evict_cooldown_ms: u64,
+        me_pool_force_close_secs: u64,
+        me_pool_min_fresh_ratio: f32,
+        me_hardswap_warmup_delay_min_ms: u64,
+        me_hardswap_warmup_delay_max_ms: u64,
+        me_hardswap_warmup_extra_passes: u8,
+        me_hardswap_warmup_pass_backoff_base_ms: u64,
+        me_bind_stale_mode: MeBindStaleMode,
+        me_bind_stale_ttl_secs: u64,
+        me_secret_atomic_snapshot: bool,
+        me_deterministic_writer_sort: bool,
+        me_writer_pick_mode: MeWriterPickMode,
+        me_writer_pick_sample_size: u8,
+        me_socks_kdf_policy: MeSocksKdfPolicy,
+        me_writer_cmd_channel_capacity: usize,
+        me_writer_byte_budget_bytes: usize,
+        me_route_channel_capacity: usize,
+        me_route_backpressure_enabled: bool,
+        me_route_fairshare_enabled: bool,
+        me_route_backpressure_base_timeout_ms: u64,
+        me_route_backpressure_high_timeout_ms: u64,
+        me_route_backpressure_high_watermark_pct: u8,
+        me_reader_route_data_wait_ms: u64,
+        me_health_interval_ms_unhealthy: u64,
+        me_health_interval_ms_healthy: u64,
+        me_warn_rate_limit_ms: u64,
+        me_route_no_writer_mode: MeRouteNoWriterMode,
+        me_route_no_writer_wait_ms: u64,
+        me_route_hybrid_max_wait_ms: u64,
+        me_route_blocking_send_timeout_ms: u64,
+        me_route_inline_recovery_attempts: u32,
+        me_route_inline_recovery_wait_ms: u64,
+        me_connection_cleanup_capacity: usize,
+    ) -> Arc<Self> {
+        let endpoint_dc_map = Self::build_endpoint_dc_map_from_maps(&proxy_map_v4, &proxy_map_v6);
+        let preferred_endpoints_by_dc =
+            Self::build_preferred_endpoints_by_dc(&decision, &proxy_map_v4, &proxy_map_v6);
+        let registry = Arc::new(ConnRegistry::with_route_and_cleanup_capacity(
+            me_route_channel_capacity,
+            me_connection_cleanup_capacity,
+        ));
+        registry.update_route_backpressure_policy(
+            me_route_backpressure_base_timeout_ms,
+            me_route_backpressure_high_timeout_ms,
+            me_route_backpressure_high_watermark_pct,
+        );
+        let (writer_epoch, _) = watch::channel(0u64);
+        let now_epoch_secs = Self::now_epoch_secs();
+        let reinit_status = ReinitStatusSnapshot {
+            active_generation: 1,
+            warm_generations: Vec::new(),
+            pending_hardswap_generation: 0,
+            pending_hardswap_started_at_epoch_secs: 0,
+            pending_hardswap_map_hash: 0,
+            inflight: 0,
+        };
+        stats.set_me_writer_byte_budget_limit_bytes(me_writer_byte_budget_bytes);
+        Arc::new(Self {
+            routing: Arc::new(RoutingCore {
+                registry,
+                writers: Arc::new(WritersState::new()),
+                rr: AtomicU64::new(0),
+                writer_epoch,
+                preferred_endpoints_by_dc: ArcSwap::from_pointee(preferred_endpoints_by_dc),
+            }),
+            reinit: Arc::new(ReinitCore {
+                generation: AtomicU64::new(1),
+                active_generation: AtomicU64::new(1),
+                warm_generation: AtomicU64::new(0),
+                pending_hardswap_generation: AtomicU64::new(0),
+                pending_hardswap_started_at_epoch_secs: AtomicU64::new(0),
+                pending_hardswap_map_hash: AtomicU64::new(0),
+                scheduler_inflight: AtomicUsize::new(0),
+                max_concurrency_effective: AtomicUsize::new(1),
+                coordinator: ParkingMutex::new(ReinitCoordinatorState {
+                    next_attempt_id: 1,
+                    active_generation: 1,
+                    desired_map_hash: 0,
+                    pending: None,
+                    attempts: HashMap::new(),
+                }),
+                status: ArcSwap::from_pointee(reinit_status),
+                hardswap: AtomicBool::new(hardswap),
+                me_hardswap_warmup_delay_min_ms: AtomicU64::new(me_hardswap_warmup_delay_min_ms),
+                me_hardswap_warmup_delay_max_ms: AtomicU64::new(me_hardswap_warmup_delay_max_ms),
+                me_hardswap_warmup_extra_passes: AtomicU32::new(
+                    me_hardswap_warmup_extra_passes as u32,
+                ),
+                me_hardswap_warmup_pass_backoff_base_ms: AtomicU64::new(
+                    me_hardswap_warmup_pass_backoff_base_ms,
+                ),
+            }),
+            writer_lifecycle: Arc::new(WriterLifecycleCore {
+                me_keepalive_enabled,
+                me_keepalive_interval: Duration::from_secs(me_keepalive_interval_secs),
+                me_keepalive_jitter: Duration::from_secs(me_keepalive_jitter_secs),
+                me_keepalive_payload_random,
+                rpc_proxy_req_every_secs: AtomicU64::new(rpc_proxy_req_every_secs),
+                writer_cmd_channel_capacity: me_writer_cmd_channel_capacity.max(1),
+                writer_byte_budget_permits: me_writer_byte_budget_bytes
+                    .div_ceil(crate::config::defaults::ME_WRITER_BYTE_PERMIT_UNIT_BYTES)
+                    .max(1),
+            }),
+            route_runtime: Arc::new(RouteRuntimeCore {
+                me_route_no_writer_mode: AtomicU8::new(me_route_no_writer_mode.as_u8()),
+                me_route_no_writer_wait: Duration::from_millis(me_route_no_writer_wait_ms),
+                me_route_hybrid_max_wait: Duration::from_millis(
+                    me_route_hybrid_max_wait_ms.max(50),
+                ),
+                me_route_blocking_send_timeout: Some(Duration::from_millis(
+                    me_route_blocking_send_timeout_ms.clamp(1, 5_000),
+                )),
+                me_route_last_success_epoch_ms: AtomicU64::new(0),
+                me_route_hybrid_timeout_warn_epoch_ms: AtomicU64::new(0),
+                me_async_recovery_last_trigger_epoch_ms: AtomicU64::new(0),
+                me_route_inline_recovery_attempts,
+                me_route_inline_recovery_wait: Duration::from_millis(
+                    me_route_inline_recovery_wait_ms,
+                ),
+            }),
+            health_runtime: Arc::new(HealthRuntimeCore {
+                me_health_interval_ms_unhealthy: AtomicU64::new(
+                    me_health_interval_ms_unhealthy.max(1),
+                ),
+                me_health_interval_ms_healthy: AtomicU64::new(me_health_interval_ms_healthy.max(1)),
+                me_warn_rate_limit_ms: AtomicU64::new(me_warn_rate_limit_ms.max(1)),
+                family_health_v4: ArcSwap::from_pointee(FamilyHealthSnapshot::new(
+                    MeFamilyRuntimeState::Healthy,
+                    now_epoch_secs,
+                    0,
+                    0,
+                    0,
+                )),
+                family_health_v6: ArcSwap::from_pointee(FamilyHealthSnapshot::new(
+                    MeFamilyRuntimeState::Healthy,
+                    now_epoch_secs,
+                    0,
+                    0,
+                    0,
+                )),
+            }),
+            drain_runtime: Arc::new(DrainRuntimeCore {
+                me_pool_drain_ttl_secs: AtomicU64::new(me_pool_drain_ttl_secs),
+                me_instadrain: AtomicBool::new(me_instadrain),
+                me_pool_drain_threshold: AtomicU64::new(me_pool_drain_threshold),
+                me_pool_drain_soft_evict_enabled: AtomicBool::new(me_pool_drain_soft_evict_enabled),
+                me_pool_drain_soft_evict_grace_secs: AtomicU64::new(
+                    me_pool_drain_soft_evict_grace_secs,
+                ),
+                me_pool_drain_soft_evict_per_writer: AtomicU8::new(
+                    me_pool_drain_soft_evict_per_writer.max(1),
+                ),
+                me_pool_drain_soft_evict_budget_per_core: AtomicU32::new(
+                    me_pool_drain_soft_evict_budget_per_core.max(1) as u32,
+                ),
+                me_pool_drain_soft_evict_cooldown_ms: AtomicU64::new(
+                    me_pool_drain_soft_evict_cooldown_ms.max(1),
+                ),
+                me_pool_force_close_secs: AtomicU64::new(Self::normalize_force_close_secs(
+                    me_pool_force_close_secs,
+                )),
+                me_pool_min_fresh_ratio_permille: AtomicU32::new(Self::ratio_to_permille(
+                    me_pool_min_fresh_ratio,
+                )),
+                me_last_drain_gate_route_quorum_ok: AtomicBool::new(false),
+                me_last_drain_gate_redundancy_ok: AtomicBool::new(false),
+                me_last_drain_gate_block_reason: AtomicU8::new(MeDrainGateReason::Open as u8),
+                me_last_drain_gate_updated_at_epoch_secs: AtomicU64::new(now_epoch_secs),
+            }),
+            single_endpoint_runtime: Arc::new(SingleEndpointRuntimeCore {
+                me_single_endpoint_shadow_writers: AtomicU8::new(me_single_endpoint_shadow_writers),
+                me_single_endpoint_outage_mode_enabled: AtomicBool::new(
+                    me_single_endpoint_outage_mode_enabled,
+                ),
+                me_single_endpoint_outage_disable_quarantine: AtomicBool::new(
+                    me_single_endpoint_outage_disable_quarantine,
+                ),
+                me_single_endpoint_outage_backoff_min_ms: AtomicU64::new(
+                    me_single_endpoint_outage_backoff_min_ms,
+                ),
+                me_single_endpoint_outage_backoff_max_ms: AtomicU64::new(
+                    me_single_endpoint_outage_backoff_max_ms,
+                ),
+                me_single_endpoint_shadow_rotate_every_secs: AtomicU64::new(
+                    me_single_endpoint_shadow_rotate_every_secs,
+                ),
+            }),
+            binding_policy: Arc::new(BindingPolicyCore {
+                me_bind_stale_mode: AtomicU8::new(me_bind_stale_mode.as_u8()),
+                me_bind_stale_ttl_secs: AtomicU64::new(me_bind_stale_ttl_secs),
+            }),
+            nat_runtime: Arc::new(NatRuntimeCore {
+                nat_ip_cfg: nat_ip,
+                nat_ip_detected: Arc::new(RwLock::new(None)),
+                nat_probe,
+                nat_stun,
+                nat_stun_servers,
+                stun_tcp_fallback,
+                http_ip_detect_urls,
+                nat_stun_live_servers: Arc::new(RwLock::new(Vec::new())),
+                nat_probe_concurrency: nat_probe_concurrency.max(1),
+                detected_ipv6,
+                nat_probe_attempts: std::sync::atomic::AtomicU8::new(0),
+                nat_probe_disabled: std::sync::atomic::AtomicBool::new(false),
+                stun_backoff_until: Arc::new(RwLock::new(None)),
+                nat_reflection_cache: Arc::new(Mutex::new(NatReflectionCache::default())),
+                nat_reflection_singleflight_v4: Arc::new(Mutex::new(())),
+                nat_reflection_singleflight_v6: Arc::new(Mutex::new(())),
+            }),
+            reconnect_runtime: Arc::new(ReconnectRuntimeCore {
+                me_one_retry,
+                me_one_timeout: Duration::from_millis(me_one_timeout_ms),
+                me_warmup_stagger_enabled,
+                me_warmup_step_delay: Duration::from_millis(me_warmup_step_delay_ms),
+                me_warmup_step_jitter: Duration::from_millis(me_warmup_step_jitter_ms),
+                me_reconnect_max_concurrent_per_dc,
+                me_reconnect_backoff_base: Duration::from_millis(me_reconnect_backoff_base_ms),
+                me_reconnect_backoff_cap: Duration::from_millis(me_reconnect_backoff_cap_ms),
+                me_reconnect_fast_retry_count,
+            }),
+            floor_runtime: Arc::new(FloorRuntimeCore {
+                me_floor_mode: AtomicU8::new(me_floor_mode.as_u8()),
+                me_adaptive_floor_idle_secs: AtomicU64::new(me_adaptive_floor_idle_secs),
+                me_adaptive_floor_min_writers_single_endpoint: AtomicU8::new(
+                    me_adaptive_floor_min_writers_single_endpoint,
+                ),
+                me_adaptive_floor_min_writers_multi_endpoint: AtomicU8::new(
+                    me_adaptive_floor_min_writers_multi_endpoint,
+                ),
+                me_adaptive_floor_recover_grace_secs: AtomicU64::new(
+                    me_adaptive_floor_recover_grace_secs,
+                ),
+                me_adaptive_floor_writers_per_core_total: AtomicU32::new(
+                    me_adaptive_floor_writers_per_core_total as u32,
+                ),
+                me_adaptive_floor_cpu_cores_override: AtomicU32::new(
+                    me_adaptive_floor_cpu_cores_override as u32,
+                ),
+                me_adaptive_floor_max_extra_writers_single_per_core: AtomicU32::new(
+                    me_adaptive_floor_max_extra_writers_single_per_core as u32,
+                ),
+                me_adaptive_floor_max_extra_writers_multi_per_core: AtomicU32::new(
+                    me_adaptive_floor_max_extra_writers_multi_per_core as u32,
+                ),
+                me_adaptive_floor_max_active_writers_per_core: AtomicU32::new(
+                    me_adaptive_floor_max_active_writers_per_core as u32,
+                ),
+                me_adaptive_floor_max_warm_writers_per_core: AtomicU32::new(
+                    me_adaptive_floor_max_warm_writers_per_core as u32,
+                ),
+                me_adaptive_floor_max_active_writers_global: AtomicU32::new(
+                    me_adaptive_floor_max_active_writers_global,
+                ),
+                me_adaptive_floor_max_warm_writers_global: AtomicU32::new(
+                    me_adaptive_floor_max_warm_writers_global,
+                ),
+                me_adaptive_floor_cpu_cores_detected: AtomicU32::new(1),
+                me_adaptive_floor_cpu_cores_effective: AtomicU32::new(1),
+                me_adaptive_floor_global_cap_raw: AtomicU64::new(0),
+                me_adaptive_floor_global_cap_effective: AtomicU64::new(0),
+                me_adaptive_floor_target_writers_total: AtomicU64::new(0),
+                me_adaptive_floor_active_cap_configured: AtomicU64::new(0),
+                me_adaptive_floor_active_cap_effective: AtomicU64::new(0),
+                me_adaptive_floor_warm_cap_configured: AtomicU64::new(0),
+                me_adaptive_floor_warm_cap_effective: AtomicU64::new(0),
+                me_adaptive_floor_active_writers_current: AtomicU64::new(0),
+                me_adaptive_floor_warm_writers_current: AtomicU64::new(0),
+            }),
+            writer_selection_policy: Arc::new(WriterSelectionPolicyCore {
+                secret_atomic_snapshot: AtomicBool::new(me_secret_atomic_snapshot),
+                me_deterministic_writer_sort: AtomicBool::new(me_deterministic_writer_sort),
+                me_writer_pick_mode: AtomicU8::new(me_writer_pick_mode.as_u8()),
+                me_writer_pick_sample_size: AtomicU8::new(me_writer_pick_sample_size.clamp(2, 4)),
+            }),
+            transport_policy: Arc::new(TransportPolicyCore {
+                me_socks_kdf_policy: AtomicU8::new(me_socks_kdf_policy.as_u8()),
+                me_route_backpressure_enabled: Arc::new(AtomicBool::new(
+                    me_route_backpressure_enabled,
+                )),
+                me_route_fairshare_enabled: Arc::new(AtomicBool::new(me_route_fairshare_enabled)),
+                me_reader_route_data_wait_ms: Arc::new(AtomicU64::new(
+                    me_reader_route_data_wait_ms,
+                )),
+            }),
+            lifecycle: MePoolLifecycle::new(),
+            decision,
+            upstream,
+            rng,
+            proxy_tag,
+            proxy_secret: Arc::new(RwLock::new(SecretSnapshot {
+                epoch: 1,
+                key_selector: if proxy_secret.len() >= 4 {
+                    u32::from_le_bytes([
+                        proxy_secret[0],
+                        proxy_secret[1],
+                        proxy_secret[2],
+                        proxy_secret[3],
+                    ])
+                } else {
+                    0
+                },
+                secret: proxy_secret,
+            })),
+            stats,
+            pool_size: 2,
+            proxy_map_v4: Arc::new(RwLock::new(proxy_map_v4)),
+            proxy_map_v6: Arc::new(RwLock::new(proxy_map_v6)),
+            endpoint_dc_map: Arc::new(RwLock::new(endpoint_dc_map)),
+            default_dc: AtomicI32::new(default_dc.unwrap_or(2)),
+            next_writer_id: AtomicU64::new(1),
+            writer_connect_active_reserved: AtomicUsize::new(0),
+            writer_connect_warm_reserved: AtomicUsize::new(0),
+            rtt_stats: Arc::new(Mutex::new(HashMap::new())),
+            refill_states: Arc::new(ParkingMutex::new(HashMap::new())),
+            refill_running: AtomicUsize::new(0),
+            refill_pending: AtomicUsize::new(0),
+            conn_count: AtomicUsize::new(0),
+            draining_active_runtime: AtomicU64::new(0),
+            endpoint_quarantine: Arc::new(Mutex::new(HashMap::new())),
+            kdf_material_fingerprint: Arc::new(RwLock::new(HashMap::new())),
+            runtime_ready: AtomicBool::new(false),
+        })
+    }
+}

src/transport/middle_proxy/pool/routing.rs

@@ -0,0 +1,286 @@
+use super::*;
+
+impl MePool {
+    pub(in crate::transport::middle_proxy) fn single_endpoint_outage_mode_enabled(&self) -> bool {
+        self.single_endpoint_runtime
+            .me_single_endpoint_outage_mode_enabled
+            .load(Ordering::Relaxed)
+    }
+
+    pub(in crate::transport::middle_proxy) fn single_endpoint_outage_disable_quarantine(
+        &self,
+    ) -> bool {
+        self.single_endpoint_runtime
+            .me_single_endpoint_outage_disable_quarantine
+            .load(Ordering::Relaxed)
+    }
+
+    pub(in crate::transport::middle_proxy) fn single_endpoint_outage_backoff_bounds_ms(
+        &self,
+    ) -> (u64, u64) {
+        let min_ms = self
+            .single_endpoint_runtime
+            .me_single_endpoint_outage_backoff_min_ms
+            .load(Ordering::Relaxed);
+        let max_ms = self
+            .single_endpoint_runtime
+            .me_single_endpoint_outage_backoff_max_ms
+            .load(Ordering::Relaxed);
+        if min_ms <= max_ms {
+            (min_ms, max_ms)
+        } else {
+            (max_ms, min_ms)
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) fn single_endpoint_shadow_rotate_interval(
+        &self,
+    ) -> Option<Duration> {
+        let secs = self
+            .single_endpoint_runtime
+            .me_single_endpoint_shadow_rotate_every_secs
+            .load(Ordering::Relaxed);
+        if secs == 0 {
+            None
+        } else {
+            Some(Duration::from_secs(secs))
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) fn family_order(&self) -> Vec<IpFamily> {
+        let mut order = Vec::new();
+        if self.decision.prefer_ipv6() {
+            if self.decision.ipv6_me {
+                order.push(IpFamily::V6);
+            }
+            if self.decision.ipv4_me {
+                order.push(IpFamily::V4);
+            }
+        } else {
+            if self.decision.ipv4_me {
+                order.push(IpFamily::V4);
+            }
+            if self.decision.ipv6_me {
+                order.push(IpFamily::V6);
+            }
+        }
+        order
+    }
+
+    pub(in crate::transport::middle_proxy) fn default_dc_for_routing(&self) -> i32 {
+        let dc = self.default_dc.load(Ordering::Relaxed);
+        if dc == 0 { 2 } else { dc }
+    }
+
+    pub(in crate::transport::middle_proxy) async fn has_configured_endpoints_for_dc(
+        &self,
+        dc: i32,
+    ) -> bool {
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await;
+            if map.get(&dc).is_some_and(|endpoints| !endpoints.is_empty()) {
+                return true;
+            }
+        }
+
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await;
+            if map.get(&dc).is_some_and(|endpoints| !endpoints.is_empty()) {
+                return true;
+            }
+        }
+
+        false
+    }
+
+    pub(in crate::transport::middle_proxy) async fn resolve_target_dc_for_routing(
+        &self,
+        target_dc: i32,
+    ) -> (i32, bool) {
+        if target_dc == 0 {
+            return (self.default_dc_for_routing(), true);
+        }
+
+        if self.has_configured_endpoints_for_dc(target_dc).await {
+            return (target_dc, false);
+        }
+
+        (self.default_dc_for_routing(), true)
+    }
+
+    pub(in crate::transport::middle_proxy) async fn resolve_dc_for_endpoint(
+        &self,
+        addr: SocketAddr,
+    ) -> i32 {
+        if let Some(cached) = self.endpoint_dc_map.read().await.get(&addr).copied()
+            && let Some(dc) = cached
+        {
+            return dc;
+        }
+
+        self.default_dc_for_routing()
+    }
+
+    pub(in crate::transport::middle_proxy) async fn proxy_map_for_family(
+        &self,
+        family: IpFamily,
+    ) -> HashMap<i32, Vec<(IpAddr, u16)>> {
+        match family {
+            IpFamily::V4 => self.proxy_map_v4.read().await.clone(),
+            IpFamily::V6 => self.proxy_map_v6.read().await.clone(),
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) fn merge_endpoint_dc(
+        endpoint_dc_map: &mut HashMap<SocketAddr, Option<i32>>,
+        dc: i32,
+        ip: IpAddr,
+        port: u16,
+    ) {
+        let endpoint = SocketAddr::new(ip, port);
+        match endpoint_dc_map.get_mut(&endpoint) {
+            None => {
+                endpoint_dc_map.insert(endpoint, Some(dc));
+            }
+            Some(existing) => {
+                if existing.is_some_and(|existing_dc| existing_dc != dc) {
+                    *existing = None;
+                }
+            }
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) fn build_preferred_endpoints_by_dc(
+        decision: &NetworkDecision,
+        map_v4: &HashMap<i32, Vec<(IpAddr, u16)>>,
+        map_v6: &HashMap<i32, Vec<(IpAddr, u16)>>,
+    ) -> HashMap<i32, Vec<SocketAddr>> {
+        let mut out = HashMap::<i32, Vec<SocketAddr>>::new();
+        let mut dcs = HashSet::<i32>::new();
+        dcs.extend(map_v4.keys().copied());
+        dcs.extend(map_v6.keys().copied());
+
+        for dc in dcs {
+            let v4 = map_v4
+                .get(&dc)
+                .map(|items| {
+                    items
+                        .iter()
+                        .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default();
+            let v6 = map_v6
+                .get(&dc)
+                .map(|items| {
+                    items
+                        .iter()
+                        .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default();
+
+            let mut selected = if decision.effective_multipath {
+                let mut both = Vec::<SocketAddr>::with_capacity(v4.len().saturating_add(v6.len()));
+                if decision.prefer_ipv6() {
+                    both.extend(v6.iter().copied());
+                    both.extend(v4.iter().copied());
+                } else {
+                    both.extend(v4.iter().copied());
+                    both.extend(v6.iter().copied());
+                }
+                both
+            } else if decision.prefer_ipv6() {
+                if !v6.is_empty() { v6 } else { v4 }
+            } else if !v4.is_empty() {
+                v4
+            } else {
+                v6
+            };
+
+            selected.sort_unstable();
+            selected.dedup();
+            out.insert(dc, selected);
+        }
+
+        out
+    }
+
+    pub(in crate::transport::middle_proxy) fn build_endpoint_dc_map_from_maps(
+        map_v4: &HashMap<i32, Vec<(IpAddr, u16)>>,
+        map_v6: &HashMap<i32, Vec<(IpAddr, u16)>>,
+    ) -> HashMap<SocketAddr, Option<i32>> {
+        let mut endpoint_dc_map = HashMap::<SocketAddr, Option<i32>>::new();
+        for (dc, endpoints) in map_v4 {
+            for (ip, port) in endpoints {
+                Self::merge_endpoint_dc(&mut endpoint_dc_map, *dc, *ip, *port);
+            }
+        }
+        for (dc, endpoints) in map_v6 {
+            for (ip, port) in endpoints {
+                Self::merge_endpoint_dc(&mut endpoint_dc_map, *dc, *ip, *port);
+            }
+        }
+        endpoint_dc_map
+    }
+
+    pub(in crate::transport::middle_proxy) async fn rebuild_endpoint_dc_map(&self) {
+        let map_v4 = self.proxy_map_v4.read().await.clone();
+        let map_v6 = self.proxy_map_v6.read().await.clone();
+        let rebuilt = Self::build_endpoint_dc_map_from_maps(&map_v4, &map_v6);
+        let preferred = Self::build_preferred_endpoints_by_dc(&self.decision, &map_v4, &map_v6);
+        *self.endpoint_dc_map.write().await = rebuilt;
+        self.preferred_endpoints_by_dc.store(Arc::new(preferred));
+        let configured_endpoints = self
+            .endpoint_dc_map
+            .read()
+            .await
+            .keys()
+            .copied()
+            .collect::<HashSet<SocketAddr>>();
+        {
+            let mut quarantine = self.endpoint_quarantine.lock().await;
+            let now = Instant::now();
+            quarantine.retain(|addr, expiry| *expiry > now && configured_endpoints.contains(addr));
+        }
+        {
+            let mut kdf_fp = self.kdf_material_fingerprint.write().await;
+            kdf_fp.retain(|addr, _| configured_endpoints.contains(addr));
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) async fn preferred_endpoints_for_dc(
+        &self,
+        dc: i32,
+    ) -> Vec<SocketAddr> {
+        let guard = self.preferred_endpoints_by_dc.load();
+        guard.get(&dc).cloned().unwrap_or_default()
+    }
+
+    pub(in crate::transport::middle_proxy) fn health_interval_unhealthy(&self) -> Duration {
+        Duration::from_millis(
+            self.health_runtime
+                .me_health_interval_ms_unhealthy
+                .load(Ordering::Relaxed)
+                .max(1),
+        )
+    }
+
+    pub(in crate::transport::middle_proxy) fn health_interval_healthy(&self) -> Duration {
+        Duration::from_millis(
+            self.health_runtime
+                .me_health_interval_ms_healthy
+                .load(Ordering::Relaxed)
+                .max(1),
+        )
+    }
+
+    pub(in crate::transport::middle_proxy) fn warn_rate_limit_duration(&self) -> Duration {
+        Duration::from_millis(
+            self.health_runtime
+                .me_warn_rate_limit_ms
+                .load(Ordering::Relaxed)
+                .max(1),
+        )
+    }
+}

src/transport/middle_proxy/pool/runtime_policy.rs

@@ -0,0 +1,408 @@
+use super::*;
+
+impl MePool {
+    /// Creates the immutable byte semaphore assigned to one ME writer generation.
+    pub(crate) fn new_writer_byte_budget(&self) -> Arc<Semaphore> {
+        Arc::new(Semaphore::new(
+            self.writer_lifecycle.writer_byte_budget_permits,
+        ))
+    }
+
+    pub fn current_generation(&self) -> u64 {
+        self.reinit.active_generation.load(Ordering::Relaxed)
+    }
+
+    pub fn set_runtime_ready(&self, ready: bool) {
+        self.runtime_ready.store(ready, Ordering::Relaxed);
+    }
+
+    pub fn is_runtime_ready(&self) -> bool {
+        self.runtime_ready.load(Ordering::Relaxed)
+    }
+
+    pub(in crate::transport::middle_proxy) fn now_epoch_millis() -> u64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64
+    }
+
+    pub(in crate::transport::middle_proxy) fn notify_writer_epoch(&self) {
+        self.writer_epoch.send_modify(|epoch| {
+            *epoch = epoch.wrapping_add(1);
+        });
+    }
+
+    pub(in crate::transport::middle_proxy) fn set_family_runtime_state(
+        &self,
+        family: IpFamily,
+        state: MeFamilyRuntimeState,
+        state_since_epoch_secs: u64,
+        suppressed_until_epoch_secs: u64,
+        fail_streak: u32,
+        recover_success_streak: u32,
+    ) {
+        let snapshot = Arc::new(FamilyHealthSnapshot::new(
+            state,
+            state_since_epoch_secs,
+            suppressed_until_epoch_secs,
+            fail_streak,
+            recover_success_streak,
+        ));
+        match family {
+            IpFamily::V4 => self.health_runtime.family_health_v4.store(snapshot),
+            IpFamily::V6 => self.health_runtime.family_health_v6.store(snapshot),
+        }
+    }
+
+    pub(crate) fn family_runtime_state(&self, family: IpFamily) -> MeFamilyRuntimeState {
+        match family {
+            IpFamily::V4 => self.health_runtime.family_health_v4.load().state,
+            IpFamily::V6 => self.health_runtime.family_health_v6.load().state,
+        }
+    }
+
+    pub(crate) fn family_runtime_state_since_epoch_secs(&self, family: IpFamily) -> u64 {
+        match family {
+            IpFamily::V4 => {
+                self.health_runtime
+                    .family_health_v4
+                    .load()
+                    .state_since_epoch_secs
+            }
+            IpFamily::V6 => {
+                self.health_runtime
+                    .family_health_v6
+                    .load()
+                    .state_since_epoch_secs
+            }
+        }
+    }
+
+    pub(crate) fn family_suppressed_until_epoch_secs(&self, family: IpFamily) -> u64 {
+        match family {
+            IpFamily::V4 => {
+                self.health_runtime
+                    .family_health_v4
+                    .load()
+                    .suppressed_until_epoch_secs
+            }
+            IpFamily::V6 => {
+                self.health_runtime
+                    .family_health_v6
+                    .load()
+                    .suppressed_until_epoch_secs
+            }
+        }
+    }
+
+    pub(crate) fn family_fail_streak(&self, family: IpFamily) -> u32 {
+        match family {
+            IpFamily::V4 => self.health_runtime.family_health_v4.load().fail_streak,
+            IpFamily::V6 => self.health_runtime.family_health_v6.load().fail_streak,
+        }
+    }
+
+    pub(crate) fn family_recover_success_streak(&self, family: IpFamily) -> u32 {
+        match family {
+            IpFamily::V4 => {
+                self.health_runtime
+                    .family_health_v4
+                    .load()
+                    .recover_success_streak
+            }
+            IpFamily::V6 => {
+                self.health_runtime
+                    .family_health_v6
+                    .load()
+                    .recover_success_streak
+            }
+        }
+    }
+
+    pub(crate) fn is_family_temporarily_suppressed(
+        &self,
+        family: IpFamily,
+        now_epoch_secs: u64,
+    ) -> bool {
+        self.family_suppressed_until_epoch_secs(family) > now_epoch_secs
+    }
+
+    pub(in crate::transport::middle_proxy) fn family_enabled_for_drain_coverage(
+        &self,
+        family: IpFamily,
+        now_epoch_secs: u64,
+    ) -> bool {
+        let configured = match family {
+            IpFamily::V4 => self.decision.ipv4_me,
+            IpFamily::V6 => self.decision.ipv6_me,
+        };
+        configured && !self.is_family_temporarily_suppressed(family, now_epoch_secs)
+    }
+
+    pub(in crate::transport::middle_proxy) fn set_last_drain_gate(
+        &self,
+        route_quorum_ok: bool,
+        redundancy_ok: bool,
+        block_reason: MeDrainGateReason,
+        updated_at_epoch_secs: u64,
+    ) {
+        self.drain_runtime
+            .me_last_drain_gate_route_quorum_ok
+            .store(route_quorum_ok, Ordering::Relaxed);
+        self.drain_runtime
+            .me_last_drain_gate_redundancy_ok
+            .store(redundancy_ok, Ordering::Relaxed);
+        self.drain_runtime
+            .me_last_drain_gate_block_reason
+            .store(block_reason as u8, Ordering::Relaxed);
+        self.drain_runtime
+            .me_last_drain_gate_updated_at_epoch_secs
+            .store(updated_at_epoch_secs, Ordering::Relaxed);
+    }
+
+    pub(crate) fn last_drain_gate_route_quorum_ok(&self) -> bool {
+        self.drain_runtime
+            .me_last_drain_gate_route_quorum_ok
+            .load(Ordering::Relaxed)
+    }
+
+    pub(crate) fn last_drain_gate_redundancy_ok(&self) -> bool {
+        self.drain_runtime
+            .me_last_drain_gate_redundancy_ok
+            .load(Ordering::Relaxed)
+    }
+
+    pub(crate) fn last_drain_gate_block_reason(&self) -> MeDrainGateReason {
+        MeDrainGateReason::from_u8(
+            self.drain_runtime
+                .me_last_drain_gate_block_reason
+                .load(Ordering::Relaxed),
+        )
+    }
+
+    pub(crate) fn last_drain_gate_updated_at_epoch_secs(&self) -> u64 {
+        self.drain_runtime
+            .me_last_drain_gate_updated_at_epoch_secs
+            .load(Ordering::Relaxed)
+    }
+
+    pub fn update_runtime_reinit_policy(
+        &self,
+        hardswap: bool,
+        drain_ttl_secs: u64,
+        instadrain: bool,
+        pool_drain_threshold: u64,
+        pool_drain_soft_evict_enabled: bool,
+        pool_drain_soft_evict_grace_secs: u64,
+        pool_drain_soft_evict_per_writer: u8,
+        pool_drain_soft_evict_budget_per_core: u16,
+        pool_drain_soft_evict_cooldown_ms: u64,
+        force_close_secs: u64,
+        min_fresh_ratio: f32,
+        hardswap_warmup_delay_min_ms: u64,
+        hardswap_warmup_delay_max_ms: u64,
+        hardswap_warmup_extra_passes: u8,
+        hardswap_warmup_pass_backoff_base_ms: u64,
+        bind_stale_mode: MeBindStaleMode,
+        bind_stale_ttl_secs: u64,
+        secret_atomic_snapshot: bool,
+        deterministic_writer_sort: bool,
+        writer_pick_mode: MeWriterPickMode,
+        writer_pick_sample_size: u8,
+        single_endpoint_shadow_writers: u8,
+        single_endpoint_outage_mode_enabled: bool,
+        single_endpoint_outage_disable_quarantine: bool,
+        single_endpoint_outage_backoff_min_ms: u64,
+        single_endpoint_outage_backoff_max_ms: u64,
+        single_endpoint_shadow_rotate_every_secs: u64,
+        floor_mode: MeFloorMode,
+        adaptive_floor_idle_secs: u64,
+        adaptive_floor_min_writers_single_endpoint: u8,
+        adaptive_floor_min_writers_multi_endpoint: u8,
+        adaptive_floor_recover_grace_secs: u64,
+        adaptive_floor_writers_per_core_total: u16,
+        adaptive_floor_cpu_cores_override: u16,
+        adaptive_floor_max_extra_writers_single_per_core: u16,
+        adaptive_floor_max_extra_writers_multi_per_core: u16,
+        adaptive_floor_max_active_writers_per_core: u16,
+        adaptive_floor_max_warm_writers_per_core: u16,
+        adaptive_floor_max_active_writers_global: u32,
+        adaptive_floor_max_warm_writers_global: u32,
+        me_health_interval_ms_unhealthy: u64,
+        me_health_interval_ms_healthy: u64,
+        me_warn_rate_limit_ms: u64,
+    ) {
+        self.reinit.hardswap.store(hardswap, Ordering::Relaxed);
+        self.drain_runtime
+            .me_pool_drain_ttl_secs
+            .store(drain_ttl_secs, Ordering::Relaxed);
+        self.drain_runtime
+            .me_instadrain
+            .store(instadrain, Ordering::Relaxed);
+        self.drain_runtime
+            .me_pool_drain_threshold
+            .store(pool_drain_threshold, Ordering::Relaxed);
+        // Runtime soft-evict knobs are updated lock-free to keep control-plane
+        // writes non-blocking; readers observe a short eventual-consistency
+        // window by design.
+        self.drain_runtime
+            .me_pool_drain_soft_evict_enabled
+            .store(pool_drain_soft_evict_enabled, Ordering::Relaxed);
+        self.drain_runtime
+            .me_pool_drain_soft_evict_grace_secs
+            .store(pool_drain_soft_evict_grace_secs, Ordering::Relaxed);
+        self.drain_runtime
+            .me_pool_drain_soft_evict_per_writer
+            .store(pool_drain_soft_evict_per_writer.max(1), Ordering::Relaxed);
+        self.drain_runtime
+            .me_pool_drain_soft_evict_budget_per_core
+            .store(
+                pool_drain_soft_evict_budget_per_core.max(1) as u32,
+                Ordering::Relaxed,
+            );
+        self.drain_runtime
+            .me_pool_drain_soft_evict_cooldown_ms
+            .store(pool_drain_soft_evict_cooldown_ms.max(1), Ordering::Relaxed);
+        self.drain_runtime.me_pool_force_close_secs.store(
+            Self::normalize_force_close_secs(force_close_secs),
+            Ordering::Relaxed,
+        );
+        self.drain_runtime
+            .me_pool_min_fresh_ratio_permille
+            .store(Self::ratio_to_permille(min_fresh_ratio), Ordering::Relaxed);
+        self.reinit
+            .me_hardswap_warmup_delay_min_ms
+            .store(hardswap_warmup_delay_min_ms, Ordering::Relaxed);
+        self.reinit
+            .me_hardswap_warmup_delay_max_ms
+            .store(hardswap_warmup_delay_max_ms, Ordering::Relaxed);
+        self.reinit
+            .me_hardswap_warmup_extra_passes
+            .store(hardswap_warmup_extra_passes as u32, Ordering::Relaxed);
+        self.reinit
+            .me_hardswap_warmup_pass_backoff_base_ms
+            .store(hardswap_warmup_pass_backoff_base_ms, Ordering::Relaxed);
+        self.binding_policy
+            .me_bind_stale_mode
+            .store(bind_stale_mode.as_u8(), Ordering::Relaxed);
+        self.binding_policy
+            .me_bind_stale_ttl_secs
+            .store(bind_stale_ttl_secs, Ordering::Relaxed);
+        self.writer_selection_policy
+            .secret_atomic_snapshot
+            .store(secret_atomic_snapshot, Ordering::Relaxed);
+        self.writer_selection_policy
+            .me_deterministic_writer_sort
+            .store(deterministic_writer_sort, Ordering::Relaxed);
+        let previous_writer_pick_mode = self.writer_pick_mode();
+        self.writer_selection_policy
+            .me_writer_pick_mode
+            .store(writer_pick_mode.as_u8(), Ordering::Relaxed);
+        self.writer_selection_policy
+            .me_writer_pick_sample_size
+            .store(writer_pick_sample_size.clamp(2, 4), Ordering::Relaxed);
+        if previous_writer_pick_mode != writer_pick_mode {
+            self.stats.increment_me_writer_pick_mode_switch_total();
+        }
+        self.single_endpoint_runtime
+            .me_single_endpoint_shadow_writers
+            .store(single_endpoint_shadow_writers, Ordering::Relaxed);
+        self.single_endpoint_runtime
+            .me_single_endpoint_outage_mode_enabled
+            .store(single_endpoint_outage_mode_enabled, Ordering::Relaxed);
+        self.single_endpoint_runtime
+            .me_single_endpoint_outage_disable_quarantine
+            .store(single_endpoint_outage_disable_quarantine, Ordering::Relaxed);
+        self.single_endpoint_runtime
+            .me_single_endpoint_outage_backoff_min_ms
+            .store(single_endpoint_outage_backoff_min_ms, Ordering::Relaxed);
+        self.single_endpoint_runtime
+            .me_single_endpoint_outage_backoff_max_ms
+            .store(single_endpoint_outage_backoff_max_ms, Ordering::Relaxed);
+        self.single_endpoint_runtime
+            .me_single_endpoint_shadow_rotate_every_secs
+            .store(single_endpoint_shadow_rotate_every_secs, Ordering::Relaxed);
+        let previous_floor_mode = self.floor_mode();
+        self.floor_runtime
+            .me_floor_mode
+            .store(floor_mode.as_u8(), Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_idle_secs
+            .store(adaptive_floor_idle_secs, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_min_writers_single_endpoint
+            .store(
+                adaptive_floor_min_writers_single_endpoint,
+                Ordering::Relaxed,
+            );
+        self.floor_runtime
+            .me_adaptive_floor_min_writers_multi_endpoint
+            .store(adaptive_floor_min_writers_multi_endpoint, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_recover_grace_secs
+            .store(adaptive_floor_recover_grace_secs, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_writers_per_core_total
+            .store(
+                adaptive_floor_writers_per_core_total as u32,
+                Ordering::Relaxed,
+            );
+        self.floor_runtime
+            .me_adaptive_floor_cpu_cores_override
+            .store(adaptive_floor_cpu_cores_override as u32, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_max_extra_writers_single_per_core
+            .store(
+                adaptive_floor_max_extra_writers_single_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.floor_runtime
+            .me_adaptive_floor_max_extra_writers_multi_per_core
+            .store(
+                adaptive_floor_max_extra_writers_multi_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.floor_runtime
+            .me_adaptive_floor_max_active_writers_per_core
+            .store(
+                adaptive_floor_max_active_writers_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.floor_runtime
+            .me_adaptive_floor_max_warm_writers_per_core
+            .store(
+                adaptive_floor_max_warm_writers_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.floor_runtime
+            .me_adaptive_floor_max_active_writers_global
+            .store(adaptive_floor_max_active_writers_global, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_max_warm_writers_global
+            .store(adaptive_floor_max_warm_writers_global, Ordering::Relaxed);
+        self.health_runtime
+            .me_health_interval_ms_unhealthy
+            .store(me_health_interval_ms_unhealthy.max(1), Ordering::Relaxed);
+        self.health_runtime
+            .me_health_interval_ms_healthy
+            .store(me_health_interval_ms_healthy.max(1), Ordering::Relaxed);
+        self.health_runtime
+            .me_warn_rate_limit_ms
+            .store(me_warn_rate_limit_ms.max(1), Ordering::Relaxed);
+        if previous_floor_mode != floor_mode {
+            self.stats.increment_me_floor_mode_switch_total();
+            match (previous_floor_mode, floor_mode) {
+                (MeFloorMode::Static, MeFloorMode::Adaptive) => {
+                    self.stats
+                        .increment_me_floor_mode_switch_static_to_adaptive_total();
+                }
+                (MeFloorMode::Adaptive, MeFloorMode::Static) => {
+                    self.stats
+                        .increment_me_floor_mode_switch_adaptive_to_static_total();
+                }
+                _ => {}
+            }
+        }
+    }
+}

src/transport/middle_proxy/pool/selection_policy.rs

@@ -0,0 +1,289 @@
+use super::*;
+
+impl MePool {
+    pub(in crate::transport::middle_proxy) async fn key_selector(&self) -> u32 {
+        self.proxy_secret.read().await.key_selector
+    }
+
+    pub(in crate::transport::middle_proxy) async fn non_draining_writer_counts_by_contour(
+        &self,
+    ) -> (usize, usize, usize) {
+        let ws = self.writers.read().await;
+        let mut active = 0usize;
+        let mut warm = 0usize;
+        for writer in ws.iter() {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
+                WriterContour::Active => active = active.saturating_add(1),
+                WriterContour::Warm => warm = warm.saturating_add(1),
+                WriterContour::Draining => {}
+            }
+        }
+        (active, warm, active.saturating_add(warm))
+    }
+
+    pub(in crate::transport::middle_proxy) async fn active_contour_writer_count_total(
+        &self,
+    ) -> usize {
+        let (active, _, _) = self.non_draining_writer_counts_by_contour().await;
+        active
+    }
+
+    pub(in crate::transport::middle_proxy) async fn secret_snapshot(&self) -> SecretSnapshot {
+        self.proxy_secret.read().await.clone()
+    }
+
+    pub(in crate::transport::middle_proxy) fn bind_stale_mode(&self) -> MeBindStaleMode {
+        MeBindStaleMode::from_u8(
+            self.binding_policy
+                .me_bind_stale_mode
+                .load(Ordering::Relaxed),
+        )
+    }
+
+    pub(in crate::transport::middle_proxy) fn writer_pick_mode(&self) -> MeWriterPickMode {
+        MeWriterPickMode::from_u8(
+            self.writer_selection_policy
+                .me_writer_pick_mode
+                .load(Ordering::Relaxed),
+        )
+    }
+
+    pub(in crate::transport::middle_proxy) fn writer_pick_sample_size(&self) -> usize {
+        self.writer_selection_policy
+            .me_writer_pick_sample_size
+            .load(Ordering::Relaxed)
+            .clamp(2, 4) as usize
+    }
+
+    pub(in crate::transport::middle_proxy) fn required_writers_for_dc(
+        &self,
+        endpoint_count: usize,
+    ) -> usize {
+        if endpoint_count == 0 {
+            return 0;
+        }
+        if endpoint_count == 1 {
+            let shadow = self
+                .single_endpoint_runtime
+                .me_single_endpoint_shadow_writers
+                .load(Ordering::Relaxed) as usize;
+            return (1 + shadow).max(3);
+        }
+        endpoint_count.max(3)
+    }
+
+    pub(in crate::transport::middle_proxy) fn floor_mode(&self) -> MeFloorMode {
+        MeFloorMode::from_u8(self.floor_runtime.me_floor_mode.load(Ordering::Relaxed))
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_min_writers_multi_endpoint(
+        &self,
+    ) -> usize {
+        (self
+            .floor_runtime
+            .me_adaptive_floor_min_writers_multi_endpoint
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_max_extra_single_per_core(
+        &self,
+    ) -> usize {
+        self.floor_runtime
+            .me_adaptive_floor_max_extra_writers_single_per_core
+            .load(Ordering::Relaxed) as usize
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_max_extra_multi_per_core(
+        &self,
+    ) -> usize {
+        self.floor_runtime
+            .me_adaptive_floor_max_extra_writers_multi_per_core
+            .load(Ordering::Relaxed) as usize
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_max_active_writers_per_core(
+        &self,
+    ) -> usize {
+        (self
+            .floor_runtime
+            .me_adaptive_floor_max_active_writers_per_core
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_max_warm_writers_per_core(
+        &self,
+    ) -> usize {
+        (self
+            .floor_runtime
+            .me_adaptive_floor_max_warm_writers_per_core
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_max_active_writers_global(
+        &self,
+    ) -> usize {
+        (self
+            .floor_runtime
+            .me_adaptive_floor_max_active_writers_global
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_max_warm_writers_global(
+        &self,
+    ) -> usize {
+        (self
+            .floor_runtime
+            .me_adaptive_floor_max_warm_writers_global
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_detected_cpu_cores(&self) -> usize {
+        std::thread::available_parallelism()
+            .map(|value| value.get())
+            .unwrap_or(1)
+            .max(1)
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_effective_cpu_cores(&self) -> usize {
+        let detected = self.adaptive_floor_detected_cpu_cores();
+        let override_cores = self
+            .floor_runtime
+            .me_adaptive_floor_cpu_cores_override
+            .load(Ordering::Relaxed) as usize;
+        let effective = if override_cores == 0 {
+            detected
+        } else {
+            override_cores.max(1)
+        };
+        self.floor_runtime
+            .me_adaptive_floor_cpu_cores_detected
+            .store(detected as u32, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_cpu_cores_effective
+            .store(effective as u32, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_cpu_cores_detected_gauge(detected as u64);
+        self.stats
+            .set_me_floor_cpu_cores_effective_gauge(effective as u64);
+        effective
+    }
+
+    // Keeps per-contour (active/warm) writer budget bounded by CPU count.
+    // Baseline is 86 writers on the first core and +48 for each extra core.
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_cpu_budget_per_contour_cap(
+        &self,
+        cores: usize,
+    ) -> usize {
+        const FIRST_CORE_WRITER_BUDGET: usize = 86;
+        const EXTRA_CORE_WRITER_BUDGET: usize = 48;
+        if cores == 0 {
+            return FIRST_CORE_WRITER_BUDGET;
+        }
+        FIRST_CORE_WRITER_BUDGET.saturating_add(
+            cores
+                .saturating_sub(1)
+                .saturating_mul(EXTRA_CORE_WRITER_BUDGET),
+        )
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_active_cap_configured_total(
+        &self,
+    ) -> usize {
+        let cores = self.adaptive_floor_effective_cpu_cores();
+        let per_contour_budget = self.adaptive_floor_cpu_budget_per_contour_cap(cores);
+        let configured = cores
+            .saturating_mul(self.adaptive_floor_max_active_writers_per_core())
+            .min(self.adaptive_floor_max_active_writers_global())
+            .min(per_contour_budget)
+            .max(1);
+        self.floor_runtime
+            .me_adaptive_floor_active_cap_configured
+            .store(configured as u64, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_active_cap_configured_gauge(configured as u64);
+        configured
+    }
+
+    pub(in crate::transport::middle_proxy) fn adaptive_floor_warm_cap_configured_total(
+        &self,
+    ) -> usize {
+        let cores = self.adaptive_floor_effective_cpu_cores();
+        let per_contour_budget = self.adaptive_floor_cpu_budget_per_contour_cap(cores);
+        let configured = cores
+            .saturating_mul(self.adaptive_floor_max_warm_writers_per_core())
+            .min(self.adaptive_floor_max_warm_writers_global())
+            .min(per_contour_budget)
+            .max(1);
+        self.floor_runtime
+            .me_adaptive_floor_warm_cap_configured
+            .store(configured as u64, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_warm_cap_configured_gauge(configured as u64);
+        configured
+    }
+
+    pub(in crate::transport::middle_proxy) fn set_adaptive_floor_runtime_caps(
+        &self,
+        active_cap_configured: usize,
+        active_cap_effective: usize,
+        warm_cap_configured: usize,
+        warm_cap_effective: usize,
+        target_writers_total: usize,
+        active_writers_current: usize,
+        warm_writers_current: usize,
+    ) {
+        self.floor_runtime
+            .me_adaptive_floor_global_cap_raw
+            .store(active_cap_configured as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_global_cap_effective
+            .store(active_cap_effective as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_target_writers_total
+            .store(target_writers_total as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_active_cap_configured
+            .store(active_cap_configured as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_active_cap_effective
+            .store(active_cap_effective as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_warm_cap_configured
+            .store(warm_cap_configured as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_warm_cap_effective
+            .store(warm_cap_effective as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_active_writers_current
+            .store(active_writers_current as u64, Ordering::Relaxed);
+        self.floor_runtime
+            .me_adaptive_floor_warm_writers_current
+            .store(warm_writers_current as u64, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_global_cap_raw_gauge(active_cap_configured as u64);
+        self.stats
+            .set_me_floor_global_cap_effective_gauge(active_cap_effective as u64);
+        self.stats
+            .set_me_floor_target_writers_total_gauge(target_writers_total as u64);
+        self.stats
+            .set_me_floor_active_cap_configured_gauge(active_cap_configured as u64);
+        self.stats
+            .set_me_floor_active_cap_effective_gauge(active_cap_effective as u64);
+        self.stats
+            .set_me_floor_warm_cap_configured_gauge(warm_cap_configured as u64);
+        self.stats
+            .set_me_floor_warm_cap_effective_gauge(warm_cap_effective as u64);
+        self.stats
+            .set_me_writers_active_current_gauge(active_writers_current as u64);
+        self.stats
+            .set_me_writers_warm_current_gauge(warm_writers_current as u64);
+    }
+}

src/transport/middle_proxy/pool/transport_policy.rs

@@ -0,0 +1,142 @@
+use super::*;
+
+impl MePool {
+    pub fn reset_stun_state(&self) {
+        self.nat_runtime
+            .nat_probe_attempts
+            .store(0, Ordering::Relaxed);
+        self.nat_runtime
+            .nat_probe_disabled
+            .store(false, Ordering::Relaxed);
+        if let Ok(mut live) = self.nat_runtime.nat_stun_live_servers.try_write() {
+            live.clear();
+        }
+    }
+
+    /// Translate the local ME address into the address material sent to the proxy.
+    pub fn translate_our_addr(&self, addr: SocketAddr) -> SocketAddr {
+        self.translate_our_addr_with_reflection(addr, None)
+    }
+
+    #[allow(dead_code)]
+    pub fn registry(&self) -> &Arc<ConnRegistry> {
+        &self.registry
+    }
+
+    pub fn update_runtime_transport_policy(
+        &self,
+        socks_kdf_policy: MeSocksKdfPolicy,
+        route_backpressure_enabled: bool,
+        route_fairshare_enabled: bool,
+        route_backpressure_base_timeout_ms: u64,
+        route_backpressure_high_timeout_ms: u64,
+        route_backpressure_high_watermark_pct: u8,
+        reader_route_data_wait_ms: u64,
+    ) {
+        self.transport_policy
+            .me_socks_kdf_policy
+            .store(socks_kdf_policy.as_u8(), Ordering::Relaxed);
+        self.transport_policy
+            .me_route_backpressure_enabled
+            .store(route_backpressure_enabled, Ordering::Relaxed);
+        self.transport_policy
+            .me_route_fairshare_enabled
+            .store(route_fairshare_enabled, Ordering::Relaxed);
+        self.transport_policy
+            .me_reader_route_data_wait_ms
+            .store(reader_route_data_wait_ms, Ordering::Relaxed);
+        self.registry.update_route_backpressure_policy(
+            route_backpressure_base_timeout_ms,
+            route_backpressure_high_timeout_ms,
+            route_backpressure_high_watermark_pct,
+        );
+    }
+
+    pub(in crate::transport::middle_proxy) fn socks_kdf_policy(&self) -> MeSocksKdfPolicy {
+        MeSocksKdfPolicy::from_u8(
+            self.transport_policy
+                .me_socks_kdf_policy
+                .load(Ordering::Relaxed),
+        )
+    }
+
+    pub(in crate::transport::middle_proxy) fn writers_arc(&self) -> Arc<WritersState> {
+        self.writers.clone()
+    }
+
+    pub(in crate::transport::middle_proxy) fn force_close_timeout(&self) -> Option<Duration> {
+        let secs = Self::normalize_force_close_secs(
+            self.drain_runtime
+                .me_pool_force_close_secs
+                .load(Ordering::Relaxed),
+        );
+        Some(Duration::from_secs(secs))
+    }
+
+    #[allow(dead_code)]
+    pub(in crate::transport::middle_proxy) fn drain_soft_evict_enabled(&self) -> bool {
+        self.drain_runtime
+            .me_pool_drain_soft_evict_enabled
+            .load(Ordering::Relaxed)
+    }
+
+    #[allow(dead_code)]
+    pub(in crate::transport::middle_proxy) fn drain_soft_evict_grace_secs(&self) -> u64 {
+        self.drain_runtime
+            .me_pool_drain_soft_evict_grace_secs
+            .load(Ordering::Relaxed)
+    }
+
+    #[allow(dead_code)]
+    pub(in crate::transport::middle_proxy) fn drain_soft_evict_per_writer(&self) -> usize {
+        self.drain_runtime
+            .me_pool_drain_soft_evict_per_writer
+            .load(Ordering::Relaxed)
+            .max(1) as usize
+    }
+
+    #[allow(dead_code)]
+    pub(in crate::transport::middle_proxy) fn drain_soft_evict_budget_per_core(&self) -> usize {
+        self.drain_runtime
+            .me_pool_drain_soft_evict_budget_per_core
+            .load(Ordering::Relaxed)
+            .max(1) as usize
+    }
+
+    #[allow(dead_code)]
+    pub(in crate::transport::middle_proxy) fn drain_soft_evict_cooldown(&self) -> Duration {
+        Duration::from_millis(
+            self.drain_runtime
+                .me_pool_drain_soft_evict_cooldown_ms
+                .load(Ordering::Relaxed)
+                .max(1),
+        )
+    }
+
+    #[allow(dead_code)]
+    pub(in crate::transport::middle_proxy) fn draining_active_runtime(&self) -> u64 {
+        self.draining_active_runtime.load(Ordering::Relaxed)
+    }
+
+    pub(in crate::transport::middle_proxy) fn increment_draining_active_runtime(&self) {
+        self.draining_active_runtime.fetch_add(1, Ordering::Relaxed);
+    }
+
+    pub(in crate::transport::middle_proxy) fn decrement_draining_active_runtime(&self) {
+        let mut current = self.draining_active_runtime.load(Ordering::Relaxed);
+        loop {
+            if current == 0 {
+                break;
+            }
+            match self.draining_active_runtime.compare_exchange_weak(
+                current,
+                current - 1,
+                Ordering::Relaxed,
+                Ordering::Relaxed,
+            ) {
+                Ok(_) => break,
+                Err(actual) => current = actual,
+            }
+        }
+    }
+}

src/transport/middle_proxy/pool/writer_admission.rs

@@ -0,0 +1,180 @@
+use super::*;
+
+impl MePool {
+    pub(in crate::transport::middle_proxy) async fn active_coverage_required_total(&self) -> usize {
+        let now_epoch_secs = Self::now_epoch_secs();
+        let mut endpoints_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
+
+        if self.family_enabled_for_drain_coverage(IpFamily::V4, now_epoch_secs) {
+            let map = self.proxy_map_v4.read().await;
+            for (dc, addrs) in map.iter() {
+                let entry = endpoints_by_dc.entry(*dc).or_default();
+                for (ip, port) in addrs.iter().copied() {
+                    entry.insert(SocketAddr::new(ip, port));
+                }
+            }
+        }
+
+        if self.family_enabled_for_drain_coverage(IpFamily::V6, now_epoch_secs) {
+            let map = self.proxy_map_v6.read().await;
+            for (dc, addrs) in map.iter() {
+                let entry = endpoints_by_dc.entry(*dc).or_default();
+                for (ip, port) in addrs.iter().copied() {
+                    entry.insert(SocketAddr::new(ip, port));
+                }
+            }
+        }
+
+        endpoints_by_dc
+            .values()
+            .map(|endpoints| self.required_writers_for_dc_with_floor_mode(endpoints.len(), false))
+            .sum()
+    }
+
+    pub(in crate::transport::middle_proxy) async fn can_open_writer_for_contour(
+        &self,
+        contour: WriterContour,
+        allow_coverage_override: bool,
+        writer_dc: i32,
+    ) -> bool {
+        let (active_writers, warm_writers, _) = self.non_draining_writer_counts_by_contour().await;
+        match contour {
+            WriterContour::Active => {
+                let active_cap = self.adaptive_floor_active_cap_configured_total();
+                if active_writers < active_cap {
+                    return true;
+                }
+                if !allow_coverage_override {
+                    return false;
+                }
+
+                let mut endpoints_len = 0;
+                let now_epoch = Self::now_epoch_secs();
+                if self.family_enabled_for_drain_coverage(IpFamily::V4, now_epoch) {
+                    if let Some(addrs) = self.proxy_map_v4.read().await.get(&writer_dc) {
+                        endpoints_len += addrs.len();
+                    }
+                }
+                if self.family_enabled_for_drain_coverage(IpFamily::V6, now_epoch) {
+                    if let Some(addrs) = self.proxy_map_v6.read().await.get(&writer_dc) {
+                        endpoints_len += addrs.len();
+                    }
+                }
+
+                if endpoints_len > 0 {
+                    let base_req =
+                        self.required_writers_for_dc_with_floor_mode(endpoints_len, false);
+                    let active_for_dc = {
+                        let ws = self.writers.read().await;
+                        ws.iter()
+                            .filter(|w| {
+                                !w.draining.load(std::sync::atomic::Ordering::Relaxed)
+                                    && w.writer_dc == writer_dc
+                                    && matches!(
+                                        WriterContour::from_u8(
+                                            w.contour.load(std::sync::atomic::Ordering::Relaxed),
+                                        ),
+                                        WriterContour::Active
+                                    )
+                            })
+                            .count()
+                    };
+                    if active_for_dc < base_req {
+                        return true;
+                    }
+                }
+
+                let coverage_required = self.active_coverage_required_total().await;
+                active_writers < coverage_required
+            }
+            WriterContour::Warm => warm_writers < self.adaptive_floor_warm_cap_configured_total(),
+            WriterContour::Draining => true,
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) async fn reserve_writer_open(
+        &self,
+        contour: WriterContour,
+        allow_coverage_override: bool,
+        writer_dc: i32,
+    ) -> Option<WriterOpenReservation<'_>> {
+        let counter = match contour {
+            WriterContour::Active => &self.writer_connect_active_reserved,
+            WriterContour::Warm => &self.writer_connect_warm_reserved,
+            WriterContour::Draining => {
+                return Some(WriterOpenReservation { counter: None });
+            }
+        };
+
+        loop {
+            if !self
+                .can_open_writer_for_contour(contour, allow_coverage_override, writer_dc)
+                .await
+            {
+                return None;
+            }
+            let (active_writers, warm_writers, _) =
+                self.non_draining_writer_counts_by_contour().await;
+            let live = match contour {
+                WriterContour::Active => active_writers,
+                WriterContour::Warm => warm_writers,
+                WriterContour::Draining => 0,
+            };
+            let mut limit = match contour {
+                WriterContour::Active => self.adaptive_floor_active_cap_configured_total(),
+                WriterContour::Warm => self.adaptive_floor_warm_cap_configured_total(),
+                WriterContour::Draining => usize::MAX,
+            };
+            if contour == WriterContour::Active && allow_coverage_override {
+                limit = limit
+                    .max(self.active_coverage_required_total().await)
+                    .saturating_add(
+                        self.reconnect_runtime
+                            .me_reconnect_max_concurrent_per_dc
+                            .max(1) as usize,
+                    );
+            }
+
+            let reserved = counter.load(Ordering::Acquire);
+            if live.saturating_add(reserved) >= limit {
+                return None;
+            }
+            if counter
+                .compare_exchange_weak(reserved, reserved + 1, Ordering::AcqRel, Ordering::Acquire)
+                .is_ok()
+            {
+                return Some(WriterOpenReservation {
+                    counter: Some(counter),
+                });
+            }
+        }
+    }
+
+    pub(in crate::transport::middle_proxy) fn required_writers_for_dc_with_floor_mode(
+        &self,
+        endpoint_count: usize,
+        reduce_for_idle: bool,
+    ) -> usize {
+        let base_required = self.required_writers_for_dc(endpoint_count);
+        if !reduce_for_idle {
+            return base_required;
+        }
+        if self.floor_mode() != MeFloorMode::Adaptive {
+            return base_required;
+        }
+        let min_writers = if endpoint_count == 1 {
+            (self
+                .floor_runtime
+                .me_adaptive_floor_min_writers_single_endpoint
+                .load(Ordering::Relaxed) as usize)
+                .max(1)
+        } else {
+            (self
+                .floor_runtime
+                .me_adaptive_floor_min_writers_multi_endpoint
+                .load(Ordering::Relaxed) as usize)
+                .max(1)
+        };
+        base_required.min(min_writers)
+    }
+}

src/transport/middle_proxy/pool_lifecycle.rs

@@ -143,11 +143,8 @@ impl MePoolLifecycle {
     }
 
     /// Spawns a writer after its caller completed task registration.
-    pub(super) fn spawn_registered_writer<F>(
-        &self,
-        registration: MeTaskRegistration<'_>,
-        future: F,
-    ) where
+    pub(super) fn spawn_registered_writer<F>(&self, registration: MeTaskRegistration<'_>, future: F)
+    where
         F: Future<Output = ()> + Send + 'static,
     {
         self.writer_tasks.spawn(future);
@@ -215,11 +212,7 @@ impl MePoolLifecycle {
     }
 
     /// Joins producers, writers, and cleanup ownership under one deadline.
-    pub(super) async fn shutdown_pool(
-        &self,
-        pool: &Arc<MePool>,
-        timeout: Duration,
-    ) -> bool {
+    pub(super) async fn shutdown_pool(&self, pool: &Arc<MePool>, timeout: Duration) -> bool {
         let deadline = tokio::time::Instant::now() + timeout;
         self.begin_shutdown();
         pool.set_runtime_ready(false);

src/transport/middle_proxy/pool_refill.rs

@@ -392,22 +392,21 @@ impl MePool {
             key: dc_key,
             active: true,
         };
-        self.lifecycle.spawn_registered_producer(registration, async move {
-            let mut current_addr = addr;
-            loop {
-                pool.stats.increment_me_refill_triggered_total();
-                let restored = pool
-                    .refill_writer_after_loss(current_addr, writer_dc)
-                    .await;
-                if !restored {
-                    warn!(%current_addr, dc = writer_dc, "ME immediate refill failed");
-                }
+        self.lifecycle
+            .spawn_registered_producer(registration, async move {
+                let mut current_addr = addr;
+                loop {
+                    pool.stats.increment_me_refill_triggered_total();
+                    let restored = pool.refill_writer_after_loss(current_addr, writer_dc).await;
+                    if !restored {
+                        warn!(%current_addr, dc = writer_dc, "ME immediate refill failed");
+                    }
 
-                let Some(next_addr) = run_guard.next_or_finish() else {
-                    return;
-                };
-                current_addr = next_addr;
-            }
-        });
+                    let Some(next_addr) = run_guard.next_or_finish() else {
+                        return;
+                    };
+                    current_addr = next_addr;
+                }
+            });
     }
 }

src/transport/middle_proxy/pool_reinit.rs

@@ -18,6 +18,13 @@ use super::pool::{
     ReinitPendingState, ReinitStatusSnapshot, WriterContour,
 };
 
+// Reinitialization admission, generation state, and coverage checks.
+mod coordination;
+// Generation warmup and stale-writer reconciliation.
+mod reconcile;
+
+#[cfg(test)]
+mod tests;
 const ME_HARDSWAP_PENDING_TTL_SECS: u64 = 1800;
 
 struct ReinitAttemptGuard {
@@ -70,10 +77,9 @@ fn publish_reinit_state(reinit: &ReinitCore, state: &ReinitCoordinatorState) {
         snapshot.warm_generations.last().copied().unwrap_or(0),
         Ordering::Release,
     );
-    reinit.pending_hardswap_generation.store(
-        snapshot.pending_hardswap_generation,
-        Ordering::Release,
-    );
+    reinit
+        .pending_hardswap_generation
+        .store(snapshot.pending_hardswap_generation, Ordering::Release);
     reinit.pending_hardswap_started_at_epoch_secs.store(
         snapshot.pending_hardswap_started_at_epoch_secs,
         Ordering::Release,
@@ -112,722 +118,3 @@ fn commit_reinit_state(
     }
     true
 }
-
-impl MePool {
-    fn desired_map_hash(desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>) -> u64 {
-        let mut hasher = DefaultHasher::new();
-        let mut dcs: Vec<i32> = desired_by_dc.keys().copied().collect();
-        dcs.sort_unstable();
-        for dc in dcs {
-            dc.hash(&mut hasher);
-            let mut endpoints: Vec<SocketAddr> = desired_by_dc
-                .get(&dc)
-                .map(|set| set.iter().copied().collect())
-                .unwrap_or_default();
-            endpoints.sort_unstable();
-            for endpoint in endpoints {
-                endpoint.hash(&mut hasher);
-            }
-        }
-        hasher.finish()
-    }
-
-    fn reserve_reinit_attempt(
-        self: &Arc<Self>,
-        hardswap: bool,
-        map_hash: u64,
-        now_epoch_secs: u64,
-    ) -> ReinitReservation {
-        let mut state = self.reinit.coordinator.lock();
-        state.desired_map_hash = map_hash;
-        let previous_generation = state.active_generation;
-        let mut pending_reused = false;
-        let mut pending_expired = false;
-        let mut pending_age_secs = 0;
-
-        let generation = if hardswap {
-            let reusable = state.pending.filter(|pending| {
-                pending_age_secs = now_epoch_secs.saturating_sub(pending.started_at_epoch_secs);
-                pending_expired = pending.started_at_epoch_secs > 0
-                    && pending_age_secs > ME_HARDSWAP_PENDING_TTL_SECS;
-                pending.generation >= previous_generation
-                    && pending.map_hash == map_hash
-                    && !pending_expired
-            });
-            if let Some(pending) = reusable {
-                pending_reused = true;
-                pending.generation
-            } else {
-                let generation = self.reinit.generation.fetch_add(1, Ordering::AcqRel) + 1;
-                state.pending = Some(ReinitPendingState {
-                    generation,
-                    started_at_epoch_secs: now_epoch_secs,
-                    map_hash,
-                });
-                generation
-            }
-        } else {
-            state.pending = None;
-            self.reinit.generation.fetch_add(1, Ordering::AcqRel) + 1
-        };
-
-        let attempt_id = state.next_attempt_id;
-        state.next_attempt_id = state.next_attempt_id.saturating_add(1);
-        state.attempts.insert(
-            attempt_id,
-            ReinitAttemptState {
-                generation,
-                map_hash,
-                hardswap,
-                committed: false,
-            },
-        );
-        publish_reinit_state(self.reinit.as_ref(), &state);
-        ReinitReservation {
-            attempt: ReinitAttemptGuard {
-                reinit: Arc::clone(&self.reinit),
-                attempt_id,
-                generation,
-                previous_generation,
-                map_hash,
-                hardswap,
-            },
-            pending_reused,
-            pending_expired,
-            pending_age_secs,
-        }
-    }
-
-    fn commit_reinit_attempt(&self, attempt: &ReinitAttemptGuard) -> bool {
-        let mut state = self.reinit.coordinator.lock();
-        if !commit_reinit_state(
-            &mut state,
-            attempt.attempt_id,
-            attempt.generation,
-            attempt.map_hash,
-            attempt.hardswap,
-        ) {
-            return false;
-        }
-        if attempt.hardswap {
-            let writers = self.writers.snapshot();
-            for writer in writers.iter() {
-                if !writer.draining.load(Ordering::Relaxed)
-                    && writer.generation == attempt.generation
-                {
-                    writer
-                        .contour
-                        .store(WriterContour::Active.as_u8(), Ordering::Release);
-                }
-            }
-        }
-        publish_reinit_state(self.reinit.as_ref(), &state);
-        true
-    }
-
-    fn coverage_ratio(
-        desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>,
-        active_writer_addrs: &HashSet<(i32, SocketAddr)>,
-    ) -> (f32, Vec<i32>) {
-        if desired_by_dc.is_empty() {
-            return (1.0, Vec::new());
-        }
-
-        let mut missing_dc = Vec::<i32>::new();
-        let mut covered = 0usize;
-        let mut total = 0usize;
-        for (dc, endpoints) in desired_by_dc {
-            if endpoints.is_empty() {
-                continue;
-            }
-            total += 1;
-            if endpoints
-                .iter()
-                .any(|addr| active_writer_addrs.contains(&(*dc, *addr)))
-            {
-                covered += 1;
-            } else {
-                missing_dc.push(*dc);
-            }
-        }
-
-        missing_dc.sort_unstable();
-        if total == 0 {
-            return (1.0, missing_dc);
-        }
-        let ratio = (covered as f32) / (total as f32);
-        (ratio, missing_dc)
-    }
-
-    pub async fn reconcile_connections(self: &Arc<Self>, rng: &SecureRandom) {
-        for family in self.family_order() {
-            let map = self.proxy_map_for_family(family).await;
-            for (dc, addrs) in &map {
-                let dc_addrs: Vec<SocketAddr> = addrs
-                    .iter()
-                    .map(|(ip, port)| SocketAddr::new(*ip, *port))
-                    .collect();
-                let dc_endpoints: HashSet<SocketAddr> = dc_addrs.iter().copied().collect();
-                if self
-                    .active_writer_count_for_dc_endpoints(*dc, &dc_endpoints)
-                    .await
-                    == 0
-                {
-                    let mut shuffled = dc_addrs.clone();
-                    shuffled.shuffle(&mut rand::rng());
-                    for addr in shuffled {
-                        if self.connect_one_for_dc(addr, *dc, rng).await.is_ok() {
-                            break;
-                        }
-                    }
-                }
-            }
-            if !self.decision.effective_multipath && self.connection_count() > 0 {
-                break;
-            }
-        }
-    }
-
-    async fn desired_dc_endpoints(&self) -> HashMap<i32, HashSet<SocketAddr>> {
-        let now_epoch_secs = Self::now_epoch_secs();
-        let mut out: HashMap<i32, HashSet<SocketAddr>> = HashMap::new();
-
-        if self.family_enabled_for_drain_coverage(IpFamily::V4, now_epoch_secs) {
-            let map_v4 = self.proxy_map_v4.read().await.clone();
-            for (dc, addrs) in map_v4 {
-                let entry = out.entry(dc).or_default();
-                for (ip, port) in addrs {
-                    entry.insert(SocketAddr::new(ip, port));
-                }
-            }
-        }
-
-        if self.family_enabled_for_drain_coverage(IpFamily::V6, now_epoch_secs) {
-            let map_v6 = self.proxy_map_v6.read().await.clone();
-            for (dc, addrs) in map_v6 {
-                let entry = out.entry(dc).or_default();
-                for (ip, port) in addrs {
-                    entry.insert(SocketAddr::new(ip, port));
-                }
-            }
-        }
-
-        out
-    }
-
-    pub(super) async fn has_non_draining_writer_per_desired_dc_group(&self) -> bool {
-        let desired_by_dc = self.desired_dc_endpoints().await;
-        let required_dcs: HashSet<i32> = desired_by_dc
-            .iter()
-            .filter_map(|(dc, endpoints)| {
-                if endpoints.is_empty() {
-                    None
-                } else {
-                    Some(*dc)
-                }
-            })
-            .collect();
-        if required_dcs.is_empty() {
-            return true;
-        }
-
-        let ws = self.writers.read().await;
-        let mut covered_dcs = HashSet::<i32>::with_capacity(required_dcs.len());
-        for writer in ws.iter() {
-            if writer.draining.load(Ordering::Relaxed) {
-                continue;
-            }
-            if required_dcs.contains(&writer.writer_dc) {
-                covered_dcs.insert(writer.writer_dc);
-                if covered_dcs.len() == required_dcs.len() {
-                    return true;
-                }
-            }
-        }
-        false
-    }
-
-    fn hardswap_warmup_connect_delay_ms(&self) -> u64 {
-        let min_ms = self
-            .reinit
-            .me_hardswap_warmup_delay_min_ms
-            .load(Ordering::Relaxed);
-        let max_ms = self
-            .reinit
-            .me_hardswap_warmup_delay_max_ms
-            .load(Ordering::Relaxed);
-        let (min_ms, max_ms) = if min_ms <= max_ms {
-            (min_ms, max_ms)
-        } else {
-            (max_ms, min_ms)
-        };
-        if min_ms == max_ms {
-            return min_ms;
-        }
-        rand::rng().random_range(min_ms..=max_ms)
-    }
-
-    fn hardswap_warmup_backoff_ms(&self, pass_idx: usize) -> u64 {
-        let base_ms = self
-            .reinit
-            .me_hardswap_warmup_pass_backoff_base_ms
-            .load(Ordering::Relaxed);
-        let cap_ms =
-            (self.reconnect_runtime.me_reconnect_backoff_cap.as_millis() as u64).max(base_ms);
-        let shift = (pass_idx as u32).min(20);
-        let scaled = base_ms.saturating_mul(1u64 << shift);
-        let core = scaled.min(cap_ms);
-        let jitter = (core / 2).max(1);
-        core.saturating_add(rand::rng().random_range(0..=jitter))
-    }
-
-    async fn fresh_writer_count_for_dc_endpoints(
-        &self,
-        generation: u64,
-        dc: i32,
-        endpoints: &HashSet<SocketAddr>,
-    ) -> usize {
-        let ws = self.writers.read().await;
-        ws.iter()
-            .filter(|w| !w.draining.load(Ordering::Relaxed))
-            .filter(|w| w.generation == generation)
-            .filter(|w| w.writer_dc == dc)
-            .filter(|w| endpoints.contains(&w.addr))
-            .count()
-    }
-
-    pub(super) async fn active_writer_count_for_dc_endpoints(
-        &self,
-        dc: i32,
-        endpoints: &HashSet<SocketAddr>,
-    ) -> usize {
-        let ws = self.writers.read().await;
-        ws.iter()
-            .filter(|w| !w.draining.load(Ordering::Relaxed))
-            .filter(|w| w.writer_dc == dc)
-            .filter(|w| endpoints.contains(&w.addr))
-            .count()
-    }
-
-    async fn warmup_generation_for_all_dcs(
-        self: &Arc<Self>,
-        rng: &SecureRandom,
-        generation: u64,
-        desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>,
-    ) {
-        let extra_passes = self
-            .reinit
-            .me_hardswap_warmup_extra_passes
-            .load(Ordering::Relaxed)
-            .min(10) as usize;
-        let total_passes = 1 + extra_passes;
-
-        for (dc, endpoints) in desired_by_dc {
-            if endpoints.is_empty() {
-                continue;
-            }
-
-            let mut endpoint_list: Vec<SocketAddr> = endpoints.iter().copied().collect();
-            endpoint_list.sort_unstable();
-            let required = self.required_writers_for_dc(endpoint_list.len());
-            let mut completed = false;
-            let mut last_fresh_count = self
-                .fresh_writer_count_for_dc_endpoints(generation, *dc, endpoints)
-                .await;
-
-            for pass_idx in 0..total_passes {
-                if last_fresh_count >= required {
-                    completed = true;
-                    break;
-                }
-
-                let missing = required.saturating_sub(last_fresh_count);
-                debug!(
-                    dc = *dc,
-                    pass = pass_idx + 1,
-                    total_passes,
-                    fresh_count = last_fresh_count,
-                    required,
-                    missing,
-                    endpoint_count = endpoint_list.len(),
-                    "ME hardswap warmup pass started"
-                );
-
-                for attempt_idx in 0..missing {
-                    let delay_ms = self.hardswap_warmup_connect_delay_ms();
-                    tokio::time::sleep(Duration::from_millis(delay_ms)).await;
-
-                    let connected = self
-                        .connect_endpoints_round_robin_with_generation_contour(
-                            *dc,
-                            &endpoint_list,
-                            rng,
-                            generation,
-                            WriterContour::Warm,
-                            false,
-                        )
-                        .await;
-                    debug!(
-                        dc = *dc,
-                        pass = pass_idx + 1,
-                        total_passes,
-                        attempt = attempt_idx + 1,
-                        delay_ms,
-                        connected,
-                        "ME hardswap warmup connect attempt finished"
-                    );
-                }
-
-                last_fresh_count = self
-                    .fresh_writer_count_for_dc_endpoints(generation, *dc, endpoints)
-                    .await;
-                if last_fresh_count >= required {
-                    completed = true;
-                    info!(
-                        dc = *dc,
-                        pass = pass_idx + 1,
-                        total_passes,
-                        fresh_count = last_fresh_count,
-                        required,
-                        "ME hardswap warmup floor reached for DC"
-                    );
-                    break;
-                }
-
-                if pass_idx + 1 < total_passes {
-                    let backoff_ms = self.hardswap_warmup_backoff_ms(pass_idx);
-                    debug!(
-                        dc = *dc,
-                        pass = pass_idx + 1,
-                        total_passes,
-                        fresh_count = last_fresh_count,
-                        required,
-                        backoff_ms,
-                        "ME hardswap warmup pass incomplete, delaying next pass"
-                    );
-                    tokio::time::sleep(Duration::from_millis(backoff_ms)).await;
-                }
-            }
-
-            if !completed {
-                warn!(
-                    dc = *dc,
-                    fresh_count = last_fresh_count,
-                    required,
-                    endpoint_count = endpoint_list.len(),
-                    total_passes,
-                    "ME warmup stopped: unable to reach required writer floor for DC"
-                );
-            }
-        }
-    }
-
-    pub async fn zero_downtime_reinit_after_map_change(
-        self: &Arc<Self>,
-        rng: &SecureRandom,
-    ) -> bool {
-        let desired_by_dc = self.desired_dc_endpoints().await;
-        let now_epoch_secs = Self::now_epoch_secs();
-        let v4_suppressed = self.is_family_temporarily_suppressed(IpFamily::V4, now_epoch_secs);
-        let v6_suppressed = self.is_family_temporarily_suppressed(IpFamily::V6, now_epoch_secs);
-        if desired_by_dc.is_empty() {
-            warn!("ME endpoint map is empty; skipping stale writer drain");
-            let reason = if (self.decision.ipv4_me && v4_suppressed)
-                || (self.decision.ipv6_me && v6_suppressed)
-            {
-                MeDrainGateReason::SuppressionActive
-            } else {
-                MeDrainGateReason::CoverageQuorum
-            };
-            self.set_last_drain_gate(false, false, reason, now_epoch_secs);
-            return false;
-        }
-
-        let desired_map_hash = Self::desired_map_hash(&desired_by_dc);
-        let hardswap = self.reinit.hardswap.load(Ordering::Relaxed);
-        let reservation =
-            self.reserve_reinit_attempt(hardswap, desired_map_hash, now_epoch_secs);
-        let attempt = reservation.attempt;
-        let previous_generation = attempt.previous_generation;
-        let generation = attempt.generation;
-        if reservation.pending_reused {
-            self.stats.increment_me_hardswap_pending_reuse_total();
-            debug!(
-                previous_generation,
-                generation,
-                pending_age_secs = reservation.pending_age_secs,
-                "ME hardswap continues with pending generation"
-            );
-        } else if reservation.pending_expired {
-            self.stats.increment_me_hardswap_pending_ttl_expired_total();
-            warn!(
-                previous_generation,
-                generation,
-                pending_age_secs = reservation.pending_age_secs,
-                pending_ttl_secs = ME_HARDSWAP_PENDING_TTL_SECS,
-                "ME hardswap pending generation expired by TTL; starting fresh generation"
-            );
-        }
-
-        if hardswap {
-            self.warmup_generation_for_all_dcs(rng, generation, &desired_by_dc)
-                .await;
-        } else {
-            self.reconcile_connections(rng).await;
-        }
-
-        let writers = self.writers.read().await;
-        let active_writer_addrs: HashSet<(i32, SocketAddr)> = writers
-            .iter()
-            .filter(|w| !w.draining.load(Ordering::Relaxed))
-            .map(|w| (w.writer_dc, w.addr))
-            .collect();
-        let min_ratio = Self::permille_to_ratio(
-            self.drain_runtime
-                .me_pool_min_fresh_ratio_permille
-                .load(Ordering::Relaxed),
-        );
-        let (coverage_ratio, missing_dc) =
-            Self::coverage_ratio(&desired_by_dc, &active_writer_addrs);
-        let mut route_quorum_ok = coverage_ratio >= min_ratio;
-        let mut redundancy_ok = missing_dc.is_empty();
-        let mut redundancy_missing_dc = missing_dc.clone();
-        let mut gate_coverage_ratio = coverage_ratio;
-        if !hardswap && coverage_ratio < min_ratio {
-            self.set_last_drain_gate(
-                false,
-                redundancy_ok,
-                MeDrainGateReason::CoverageQuorum,
-                now_epoch_secs,
-            );
-            warn!(
-                previous_generation,
-                generation,
-                coverage_ratio = format_args!("{coverage_ratio:.3}"),
-                min_ratio = format_args!("{min_ratio:.3}"),
-                missing_dc = ?missing_dc,
-                "ME reinit coverage below threshold; keeping stale writers"
-            );
-            return false;
-        }
-
-        if hardswap {
-            let fresh_writer_addrs: HashSet<(i32, SocketAddr)> = writers
-                .iter()
-                .filter(|w| !w.draining.load(Ordering::Relaxed))
-                .filter(|w| w.generation == generation)
-                .map(|w| (w.writer_dc, w.addr))
-                .collect();
-            let (fresh_coverage_ratio, fresh_missing_dc) =
-                Self::coverage_ratio(&desired_by_dc, &fresh_writer_addrs);
-            route_quorum_ok = fresh_coverage_ratio >= min_ratio;
-            redundancy_ok = fresh_missing_dc.is_empty();
-            redundancy_missing_dc = fresh_missing_dc.clone();
-            gate_coverage_ratio = fresh_coverage_ratio;
-            if fresh_coverage_ratio < min_ratio {
-                self.set_last_drain_gate(
-                    false,
-                    redundancy_ok,
-                    MeDrainGateReason::CoverageQuorum,
-                    now_epoch_secs,
-                );
-                warn!(
-                    previous_generation,
-                    generation,
-                    fresh_coverage_ratio = format_args!("{fresh_coverage_ratio:.3}"),
-                    missing_dc = ?fresh_missing_dc,
-                    "ME hardswap pending: fresh generation DC coverage incomplete"
-                );
-                return false;
-            }
-        }
-
-        self.set_last_drain_gate(
-            route_quorum_ok,
-            redundancy_ok,
-            MeDrainGateReason::Open,
-            now_epoch_secs,
-        );
-        if !redundancy_ok {
-            warn!(
-                missing_dc = ?redundancy_missing_dc,
-                coverage_ratio = format_args!("{gate_coverage_ratio:.3}"),
-                min_ratio = format_args!("{min_ratio:.3}"),
-                "ME reinit proceeds with weighted quorum while some DC groups remain uncovered"
-            );
-        }
-
-        if !self.commit_reinit_attempt(&attempt) {
-            debug!(
-                previous_generation,
-                generation,
-                "ME reinit result discarded after a newer desired-map attempt"
-            );
-            return false;
-        }
-
-        let desired_addrs: HashSet<(i32, SocketAddr)> = desired_by_dc
-            .iter()
-            .flat_map(|(dc, set)| set.iter().copied().map(|addr| (*dc, addr)))
-            .collect();
-
-        let stale_writer_ids: Vec<u64> = writers
-            .iter()
-            .filter(|w| !w.draining.load(Ordering::Relaxed))
-            .filter(|w| {
-                if hardswap {
-                    w.generation < generation
-                } else {
-                    !desired_addrs.contains(&(w.writer_dc, w.addr))
-                }
-            })
-            .map(|w| w.id)
-            .collect();
-        drop(writers);
-
-        if stale_writer_ids.is_empty() {
-            debug!("ME reinit cycle completed with no stale writers");
-            return true;
-        }
-
-        let drain_timeout = self.force_close_timeout();
-        let drain_timeout_secs = drain_timeout.map(|d| d.as_secs()).unwrap_or(0);
-        info!(
-            stale_writers = stale_writer_ids.len(),
-            previous_generation,
-            generation,
-            hardswap,
-            coverage_ratio = format_args!("{coverage_ratio:.3}"),
-            min_ratio = format_args!("{min_ratio:.3}"),
-            drain_timeout_secs,
-            "ME reinit cycle covered; processing stale writers"
-        );
-        self.stats.increment_pool_swap_total();
-        let can_drop_with_replacement = self.has_non_draining_writer_per_desired_dc_group().await;
-        if can_drop_with_replacement {
-            info!(
-                stale_writers = stale_writer_ids.len(),
-                "ME reinit stale writers: replacement coverage ready, force-closing clients for fast rebind"
-            );
-        } else {
-            warn!(
-                stale_writers = stale_writer_ids.len(),
-                "ME reinit stale writers: replacement coverage incomplete, keeping draining fallback"
-            );
-        }
-        for writer_id in stale_writer_ids {
-            self.mark_writer_draining_with_timeout(writer_id, drain_timeout, !hardswap)
-                .await;
-            if can_drop_with_replacement {
-                self.stats.increment_pool_force_close_total();
-                self.remove_writer_and_close_clients(writer_id).await;
-            }
-        }
-        true
-    }
-
-    pub async fn zero_downtime_reinit_periodic(self: &Arc<Self>, rng: &SecureRandom) -> bool {
-        self.zero_downtime_reinit_after_map_change(rng).await
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use std::collections::{HashMap, HashSet};
-    use std::net::{IpAddr, Ipv4Addr, SocketAddr};
-
-    use super::{MePool, commit_reinit_state};
-    use crate::transport::middle_proxy::pool::{
-        ReinitAttemptState, ReinitCoordinatorState, ReinitPendingState,
-    };
-
-    fn addr(octet: u8, port: u16) -> SocketAddr {
-        SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, octet)), port)
-    }
-
-    #[test]
-    fn coverage_ratio_counts_dc_coverage_not_floor() {
-        let dc1 = addr(1, 2001);
-        let dc2 = addr(2, 2002);
-
-        let mut desired_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
-        desired_by_dc.insert(1, HashSet::from([dc1]));
-        desired_by_dc.insert(2, HashSet::from([dc2]));
-
-        let active_writer_addrs = HashSet::from([(1, dc1)]);
-        let (ratio, missing_dc) = MePool::coverage_ratio(&desired_by_dc, &active_writer_addrs);
-
-        assert_eq!(ratio, 0.5);
-        assert_eq!(missing_dc, vec![2]);
-    }
-
-    #[test]
-    fn coverage_ratio_ignores_empty_dc_groups() {
-        let dc1 = addr(1, 2001);
-
-        let mut desired_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
-        desired_by_dc.insert(1, HashSet::from([dc1]));
-        desired_by_dc.insert(2, HashSet::new());
-
-        let active_writer_addrs = HashSet::from([(1, dc1)]);
-        let (ratio, missing_dc) = MePool::coverage_ratio(&desired_by_dc, &active_writer_addrs);
-
-        assert_eq!(ratio, 1.0);
-        assert!(missing_dc.is_empty());
-    }
-
-    #[test]
-    fn coverage_ratio_reports_missing_dcs_sorted() {
-        let dc1 = addr(1, 2001);
-        let dc2 = addr(2, 2002);
-
-        let mut desired_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
-        desired_by_dc.insert(2, HashSet::from([dc2]));
-        desired_by_dc.insert(1, HashSet::from([dc1]));
-
-        let (ratio, missing_dc) = MePool::coverage_ratio(&desired_by_dc, &HashSet::new());
-
-        assert_eq!(ratio, 0.0);
-        assert_eq!(missing_dc, vec![1, 2]);
-    }
-
-    #[test]
-    fn stale_concurrent_attempt_cannot_regress_active_generation() {
-        let mut state = ReinitCoordinatorState {
-            next_attempt_id: 3,
-            active_generation: 1,
-            desired_map_hash: 22,
-            pending: Some(ReinitPendingState {
-                generation: 3,
-                started_at_epoch_secs: 1,
-                map_hash: 22,
-            }),
-            attempts: HashMap::from([
-                (
-                    1,
-                    ReinitAttemptState {
-                        generation: 2,
-                        map_hash: 11,
-                        hardswap: true,
-                        committed: false,
-                    },
-                ),
-                (
-                    2,
-                    ReinitAttemptState {
-                        generation: 3,
-                        map_hash: 22,
-                        hardswap: true,
-                        committed: false,
-                    },
-                ),
-            ]),
-        };
-
-        assert!(commit_reinit_state(&mut state, 2, 3, 22, true));
-        assert_eq!(state.active_generation, 3);
-        assert!(!commit_reinit_state(&mut state, 1, 2, 11, true));
-        assert_eq!(state.active_generation, 3);
-        assert!(state.pending.is_none());
-    }
-}

src/transport/middle_proxy/pool_reinit/coordination.rs

@@ -0,0 +1,300 @@
+use super::*;
+
+impl MePool {
+    pub(super) fn desired_map_hash(desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>) -> u64 {
+        let mut hasher = DefaultHasher::new();
+        let mut dcs: Vec<i32> = desired_by_dc.keys().copied().collect();
+        dcs.sort_unstable();
+        for dc in dcs {
+            dc.hash(&mut hasher);
+            let mut endpoints: Vec<SocketAddr> = desired_by_dc
+                .get(&dc)
+                .map(|set| set.iter().copied().collect())
+                .unwrap_or_default();
+            endpoints.sort_unstable();
+            for endpoint in endpoints {
+                endpoint.hash(&mut hasher);
+            }
+        }
+        hasher.finish()
+    }
+
+    pub(super) fn reserve_reinit_attempt(
+        self: &Arc<Self>,
+        hardswap: bool,
+        map_hash: u64,
+        now_epoch_secs: u64,
+    ) -> ReinitReservation {
+        let mut state = self.reinit.coordinator.lock();
+        state.desired_map_hash = map_hash;
+        let previous_generation = state.active_generation;
+        let mut pending_reused = false;
+        let mut pending_expired = false;
+        let mut pending_age_secs = 0;
+
+        let generation = if hardswap {
+            let reusable = state.pending.filter(|pending| {
+                pending_age_secs = now_epoch_secs.saturating_sub(pending.started_at_epoch_secs);
+                pending_expired = pending.started_at_epoch_secs > 0
+                    && pending_age_secs > ME_HARDSWAP_PENDING_TTL_SECS;
+                pending.generation >= previous_generation
+                    && pending.map_hash == map_hash
+                    && !pending_expired
+            });
+            if let Some(pending) = reusable {
+                pending_reused = true;
+                pending.generation
+            } else {
+                let generation = self.reinit.generation.fetch_add(1, Ordering::AcqRel) + 1;
+                state.pending = Some(ReinitPendingState {
+                    generation,
+                    started_at_epoch_secs: now_epoch_secs,
+                    map_hash,
+                });
+                generation
+            }
+        } else {
+            state.pending = None;
+            self.reinit.generation.fetch_add(1, Ordering::AcqRel) + 1
+        };
+
+        let attempt_id = state.next_attempt_id;
+        state.next_attempt_id = state.next_attempt_id.saturating_add(1);
+        state.attempts.insert(
+            attempt_id,
+            ReinitAttemptState {
+                generation,
+                map_hash,
+                hardswap,
+                committed: false,
+            },
+        );
+        publish_reinit_state(self.reinit.as_ref(), &state);
+        ReinitReservation {
+            attempt: ReinitAttemptGuard {
+                reinit: Arc::clone(&self.reinit),
+                attempt_id,
+                generation,
+                previous_generation,
+                map_hash,
+                hardswap,
+            },
+            pending_reused,
+            pending_expired,
+            pending_age_secs,
+        }
+    }
+
+    pub(super) fn commit_reinit_attempt(&self, attempt: &ReinitAttemptGuard) -> bool {
+        let mut state = self.reinit.coordinator.lock();
+        if !commit_reinit_state(
+            &mut state,
+            attempt.attempt_id,
+            attempt.generation,
+            attempt.map_hash,
+            attempt.hardswap,
+        ) {
+            return false;
+        }
+        if attempt.hardswap {
+            let writers = self.writers.snapshot();
+            for writer in writers.iter() {
+                if !writer.draining.load(Ordering::Relaxed)
+                    && writer.generation == attempt.generation
+                {
+                    writer
+                        .contour
+                        .store(WriterContour::Active.as_u8(), Ordering::Release);
+                }
+            }
+        }
+        publish_reinit_state(self.reinit.as_ref(), &state);
+        true
+    }
+
+    pub(super) fn coverage_ratio(
+        desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>,
+        active_writer_addrs: &HashSet<(i32, SocketAddr)>,
+    ) -> (f32, Vec<i32>) {
+        if desired_by_dc.is_empty() {
+            return (1.0, Vec::new());
+        }
+
+        let mut missing_dc = Vec::<i32>::new();
+        let mut covered = 0usize;
+        let mut total = 0usize;
+        for (dc, endpoints) in desired_by_dc {
+            if endpoints.is_empty() {
+                continue;
+            }
+            total += 1;
+            if endpoints
+                .iter()
+                .any(|addr| active_writer_addrs.contains(&(*dc, *addr)))
+            {
+                covered += 1;
+            } else {
+                missing_dc.push(*dc);
+            }
+        }
+
+        missing_dc.sort_unstable();
+        if total == 0 {
+            return (1.0, missing_dc);
+        }
+        let ratio = (covered as f32) / (total as f32);
+        (ratio, missing_dc)
+    }
+
+    pub async fn reconcile_connections(self: &Arc<Self>, rng: &SecureRandom) {
+        for family in self.family_order() {
+            let map = self.proxy_map_for_family(family).await;
+            for (dc, addrs) in &map {
+                let dc_addrs: Vec<SocketAddr> = addrs
+                    .iter()
+                    .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                    .collect();
+                let dc_endpoints: HashSet<SocketAddr> = dc_addrs.iter().copied().collect();
+                if self
+                    .active_writer_count_for_dc_endpoints(*dc, &dc_endpoints)
+                    .await
+                    == 0
+                {
+                    let mut shuffled = dc_addrs.clone();
+                    shuffled.shuffle(&mut rand::rng());
+                    for addr in shuffled {
+                        if self.connect_one_for_dc(addr, *dc, rng).await.is_ok() {
+                            break;
+                        }
+                    }
+                }
+            }
+            if !self.decision.effective_multipath && self.connection_count() > 0 {
+                break;
+            }
+        }
+    }
+
+    pub(super) async fn desired_dc_endpoints(&self) -> HashMap<i32, HashSet<SocketAddr>> {
+        let now_epoch_secs = Self::now_epoch_secs();
+        let mut out: HashMap<i32, HashSet<SocketAddr>> = HashMap::new();
+
+        if self.family_enabled_for_drain_coverage(IpFamily::V4, now_epoch_secs) {
+            let map_v4 = self.proxy_map_v4.read().await.clone();
+            for (dc, addrs) in map_v4 {
+                let entry = out.entry(dc).or_default();
+                for (ip, port) in addrs {
+                    entry.insert(SocketAddr::new(ip, port));
+                }
+            }
+        }
+
+        if self.family_enabled_for_drain_coverage(IpFamily::V6, now_epoch_secs) {
+            let map_v6 = self.proxy_map_v6.read().await.clone();
+            for (dc, addrs) in map_v6 {
+                let entry = out.entry(dc).or_default();
+                for (ip, port) in addrs {
+                    entry.insert(SocketAddr::new(ip, port));
+                }
+            }
+        }
+
+        out
+    }
+
+    pub(in crate::transport::middle_proxy) async fn has_non_draining_writer_per_desired_dc_group(
+        &self,
+    ) -> bool {
+        let desired_by_dc = self.desired_dc_endpoints().await;
+        let required_dcs: HashSet<i32> = desired_by_dc
+            .iter()
+            .filter_map(|(dc, endpoints)| {
+                if endpoints.is_empty() {
+                    None
+                } else {
+                    Some(*dc)
+                }
+            })
+            .collect();
+        if required_dcs.is_empty() {
+            return true;
+        }
+
+        let ws = self.writers.read().await;
+        let mut covered_dcs = HashSet::<i32>::with_capacity(required_dcs.len());
+        for writer in ws.iter() {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            if required_dcs.contains(&writer.writer_dc) {
+                covered_dcs.insert(writer.writer_dc);
+                if covered_dcs.len() == required_dcs.len() {
+                    return true;
+                }
+            }
+        }
+        false
+    }
+
+    pub(super) fn hardswap_warmup_connect_delay_ms(&self) -> u64 {
+        let min_ms = self
+            .reinit
+            .me_hardswap_warmup_delay_min_ms
+            .load(Ordering::Relaxed);
+        let max_ms = self
+            .reinit
+            .me_hardswap_warmup_delay_max_ms
+            .load(Ordering::Relaxed);
+        let (min_ms, max_ms) = if min_ms <= max_ms {
+            (min_ms, max_ms)
+        } else {
+            (max_ms, min_ms)
+        };
+        if min_ms == max_ms {
+            return min_ms;
+        }
+        rand::rng().random_range(min_ms..=max_ms)
+    }
+
+    pub(super) fn hardswap_warmup_backoff_ms(&self, pass_idx: usize) -> u64 {
+        let base_ms = self
+            .reinit
+            .me_hardswap_warmup_pass_backoff_base_ms
+            .load(Ordering::Relaxed);
+        let cap_ms =
+            (self.reconnect_runtime.me_reconnect_backoff_cap.as_millis() as u64).max(base_ms);
+        let shift = (pass_idx as u32).min(20);
+        let scaled = base_ms.saturating_mul(1u64 << shift);
+        let core = scaled.min(cap_ms);
+        let jitter = (core / 2).max(1);
+        core.saturating_add(rand::rng().random_range(0..=jitter))
+    }
+
+    pub(super) async fn fresh_writer_count_for_dc_endpoints(
+        &self,
+        generation: u64,
+        dc: i32,
+        endpoints: &HashSet<SocketAddr>,
+    ) -> usize {
+        let ws = self.writers.read().await;
+        ws.iter()
+            .filter(|w| !w.draining.load(Ordering::Relaxed))
+            .filter(|w| w.generation == generation)
+            .filter(|w| w.writer_dc == dc)
+            .filter(|w| endpoints.contains(&w.addr))
+            .count()
+    }
+
+    pub(in crate::transport::middle_proxy) async fn active_writer_count_for_dc_endpoints(
+        &self,
+        dc: i32,
+        endpoints: &HashSet<SocketAddr>,
+    ) -> usize {
+        let ws = self.writers.read().await;
+        ws.iter()
+            .filter(|w| !w.draining.load(Ordering::Relaxed))
+            .filter(|w| w.writer_dc == dc)
+            .filter(|w| endpoints.contains(&w.addr))
+            .count()
+    }
+}

src/transport/middle_proxy/pool_reinit/reconcile.rs

@@ -0,0 +1,322 @@
+use super::*;
+
+impl MePool {
+    async fn warmup_generation_for_all_dcs(
+        self: &Arc<Self>,
+        rng: &SecureRandom,
+        generation: u64,
+        desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>,
+    ) {
+        let extra_passes = self
+            .reinit
+            .me_hardswap_warmup_extra_passes
+            .load(Ordering::Relaxed)
+            .min(10) as usize;
+        let total_passes = 1 + extra_passes;
+
+        for (dc, endpoints) in desired_by_dc {
+            if endpoints.is_empty() {
+                continue;
+            }
+
+            let mut endpoint_list: Vec<SocketAddr> = endpoints.iter().copied().collect();
+            endpoint_list.sort_unstable();
+            let required = self.required_writers_for_dc(endpoint_list.len());
+            let mut completed = false;
+            let mut last_fresh_count = self
+                .fresh_writer_count_for_dc_endpoints(generation, *dc, endpoints)
+                .await;
+
+            for pass_idx in 0..total_passes {
+                if last_fresh_count >= required {
+                    completed = true;
+                    break;
+                }
+
+                let missing = required.saturating_sub(last_fresh_count);
+                debug!(
+                    dc = *dc,
+                    pass = pass_idx + 1,
+                    total_passes,
+                    fresh_count = last_fresh_count,
+                    required,
+                    missing,
+                    endpoint_count = endpoint_list.len(),
+                    "ME hardswap warmup pass started"
+                );
+
+                for attempt_idx in 0..missing {
+                    let delay_ms = self.hardswap_warmup_connect_delay_ms();
+                    tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+
+                    let connected = self
+                        .connect_endpoints_round_robin_with_generation_contour(
+                            *dc,
+                            &endpoint_list,
+                            rng,
+                            generation,
+                            WriterContour::Warm,
+                            false,
+                        )
+                        .await;
+                    debug!(
+                        dc = *dc,
+                        pass = pass_idx + 1,
+                        total_passes,
+                        attempt = attempt_idx + 1,
+                        delay_ms,
+                        connected,
+                        "ME hardswap warmup connect attempt finished"
+                    );
+                }
+
+                last_fresh_count = self
+                    .fresh_writer_count_for_dc_endpoints(generation, *dc, endpoints)
+                    .await;
+                if last_fresh_count >= required {
+                    completed = true;
+                    info!(
+                        dc = *dc,
+                        pass = pass_idx + 1,
+                        total_passes,
+                        fresh_count = last_fresh_count,
+                        required,
+                        "ME hardswap warmup floor reached for DC"
+                    );
+                    break;
+                }
+
+                if pass_idx + 1 < total_passes {
+                    let backoff_ms = self.hardswap_warmup_backoff_ms(pass_idx);
+                    debug!(
+                        dc = *dc,
+                        pass = pass_idx + 1,
+                        total_passes,
+                        fresh_count = last_fresh_count,
+                        required,
+                        backoff_ms,
+                        "ME hardswap warmup pass incomplete, delaying next pass"
+                    );
+                    tokio::time::sleep(Duration::from_millis(backoff_ms)).await;
+                }
+            }
+
+            if !completed {
+                warn!(
+                    dc = *dc,
+                    fresh_count = last_fresh_count,
+                    required,
+                    endpoint_count = endpoint_list.len(),
+                    total_passes,
+                    "ME warmup stopped: unable to reach required writer floor for DC"
+                );
+            }
+        }
+    }
+
+    pub async fn zero_downtime_reinit_after_map_change(
+        self: &Arc<Self>,
+        rng: &SecureRandom,
+    ) -> bool {
+        let desired_by_dc = self.desired_dc_endpoints().await;
+        let now_epoch_secs = Self::now_epoch_secs();
+        let v4_suppressed = self.is_family_temporarily_suppressed(IpFamily::V4, now_epoch_secs);
+        let v6_suppressed = self.is_family_temporarily_suppressed(IpFamily::V6, now_epoch_secs);
+        if desired_by_dc.is_empty() {
+            warn!("ME endpoint map is empty; skipping stale writer drain");
+            let reason = if (self.decision.ipv4_me && v4_suppressed)
+                || (self.decision.ipv6_me && v6_suppressed)
+            {
+                MeDrainGateReason::SuppressionActive
+            } else {
+                MeDrainGateReason::CoverageQuorum
+            };
+            self.set_last_drain_gate(false, false, reason, now_epoch_secs);
+            return false;
+        }
+
+        let desired_map_hash = Self::desired_map_hash(&desired_by_dc);
+        let hardswap = self.reinit.hardswap.load(Ordering::Relaxed);
+        let reservation = self.reserve_reinit_attempt(hardswap, desired_map_hash, now_epoch_secs);
+        let attempt = reservation.attempt;
+        let previous_generation = attempt.previous_generation;
+        let generation = attempt.generation;
+        if reservation.pending_reused {
+            self.stats.increment_me_hardswap_pending_reuse_total();
+            debug!(
+                previous_generation,
+                generation,
+                pending_age_secs = reservation.pending_age_secs,
+                "ME hardswap continues with pending generation"
+            );
+        } else if reservation.pending_expired {
+            self.stats.increment_me_hardswap_pending_ttl_expired_total();
+            warn!(
+                previous_generation,
+                generation,
+                pending_age_secs = reservation.pending_age_secs,
+                pending_ttl_secs = ME_HARDSWAP_PENDING_TTL_SECS,
+                "ME hardswap pending generation expired by TTL; starting fresh generation"
+            );
+        }
+
+        if hardswap {
+            self.warmup_generation_for_all_dcs(rng, generation, &desired_by_dc)
+                .await;
+        } else {
+            self.reconcile_connections(rng).await;
+        }
+
+        let writers = self.writers.read().await;
+        let active_writer_addrs: HashSet<(i32, SocketAddr)> = writers
+            .iter()
+            .filter(|w| !w.draining.load(Ordering::Relaxed))
+            .map(|w| (w.writer_dc, w.addr))
+            .collect();
+        let min_ratio = Self::permille_to_ratio(
+            self.drain_runtime
+                .me_pool_min_fresh_ratio_permille
+                .load(Ordering::Relaxed),
+        );
+        let (coverage_ratio, missing_dc) =
+            Self::coverage_ratio(&desired_by_dc, &active_writer_addrs);
+        let mut route_quorum_ok = coverage_ratio >= min_ratio;
+        let mut redundancy_ok = missing_dc.is_empty();
+        let mut redundancy_missing_dc = missing_dc.clone();
+        let mut gate_coverage_ratio = coverage_ratio;
+        if !hardswap && coverage_ratio < min_ratio {
+            self.set_last_drain_gate(
+                false,
+                redundancy_ok,
+                MeDrainGateReason::CoverageQuorum,
+                now_epoch_secs,
+            );
+            warn!(
+                previous_generation,
+                generation,
+                coverage_ratio = format_args!("{coverage_ratio:.3}"),
+                min_ratio = format_args!("{min_ratio:.3}"),
+                missing_dc = ?missing_dc,
+                "ME reinit coverage below threshold; keeping stale writers"
+            );
+            return false;
+        }
+
+        if hardswap {
+            let fresh_writer_addrs: HashSet<(i32, SocketAddr)> = writers
+                .iter()
+                .filter(|w| !w.draining.load(Ordering::Relaxed))
+                .filter(|w| w.generation == generation)
+                .map(|w| (w.writer_dc, w.addr))
+                .collect();
+            let (fresh_coverage_ratio, fresh_missing_dc) =
+                Self::coverage_ratio(&desired_by_dc, &fresh_writer_addrs);
+            route_quorum_ok = fresh_coverage_ratio >= min_ratio;
+            redundancy_ok = fresh_missing_dc.is_empty();
+            redundancy_missing_dc = fresh_missing_dc.clone();
+            gate_coverage_ratio = fresh_coverage_ratio;
+            if fresh_coverage_ratio < min_ratio {
+                self.set_last_drain_gate(
+                    false,
+                    redundancy_ok,
+                    MeDrainGateReason::CoverageQuorum,
+                    now_epoch_secs,
+                );
+                warn!(
+                    previous_generation,
+                    generation,
+                    fresh_coverage_ratio = format_args!("{fresh_coverage_ratio:.3}"),
+                    missing_dc = ?fresh_missing_dc,
+                    "ME hardswap pending: fresh generation DC coverage incomplete"
+                );
+                return false;
+            }
+        }
+
+        self.set_last_drain_gate(
+            route_quorum_ok,
+            redundancy_ok,
+            MeDrainGateReason::Open,
+            now_epoch_secs,
+        );
+        if !redundancy_ok {
+            warn!(
+                missing_dc = ?redundancy_missing_dc,
+                coverage_ratio = format_args!("{gate_coverage_ratio:.3}"),
+                min_ratio = format_args!("{min_ratio:.3}"),
+                "ME reinit proceeds with weighted quorum while some DC groups remain uncovered"
+            );
+        }
+
+        if !self.commit_reinit_attempt(&attempt) {
+            debug!(
+                previous_generation,
+                generation, "ME reinit result discarded after a newer desired-map attempt"
+            );
+            return false;
+        }
+
+        let desired_addrs: HashSet<(i32, SocketAddr)> = desired_by_dc
+            .iter()
+            .flat_map(|(dc, set)| set.iter().copied().map(|addr| (*dc, addr)))
+            .collect();
+
+        let stale_writer_ids: Vec<u64> = writers
+            .iter()
+            .filter(|w| !w.draining.load(Ordering::Relaxed))
+            .filter(|w| {
+                if hardswap {
+                    w.generation < generation
+                } else {
+                    !desired_addrs.contains(&(w.writer_dc, w.addr))
+                }
+            })
+            .map(|w| w.id)
+            .collect();
+        drop(writers);
+
+        if stale_writer_ids.is_empty() {
+            debug!("ME reinit cycle completed with no stale writers");
+            return true;
+        }
+
+        let drain_timeout = self.force_close_timeout();
+        let drain_timeout_secs = drain_timeout.map(|d| d.as_secs()).unwrap_or(0);
+        info!(
+            stale_writers = stale_writer_ids.len(),
+            previous_generation,
+            generation,
+            hardswap,
+            coverage_ratio = format_args!("{coverage_ratio:.3}"),
+            min_ratio = format_args!("{min_ratio:.3}"),
+            drain_timeout_secs,
+            "ME reinit cycle covered; processing stale writers"
+        );
+        self.stats.increment_pool_swap_total();
+        let can_drop_with_replacement = self.has_non_draining_writer_per_desired_dc_group().await;
+        if can_drop_with_replacement {
+            info!(
+                stale_writers = stale_writer_ids.len(),
+                "ME reinit stale writers: replacement coverage ready, force-closing clients for fast rebind"
+            );
+        } else {
+            warn!(
+                stale_writers = stale_writer_ids.len(),
+                "ME reinit stale writers: replacement coverage incomplete, keeping draining fallback"
+            );
+        }
+        for writer_id in stale_writer_ids {
+            self.mark_writer_draining_with_timeout(writer_id, drain_timeout, !hardswap)
+                .await;
+            if can_drop_with_replacement {
+                self.stats.increment_pool_force_close_total();
+                self.remove_writer_and_close_clients(writer_id).await;
+            }
+        }
+        true
+    }
+
+    pub async fn zero_downtime_reinit_periodic(self: &Arc<Self>, rng: &SecureRandom) -> bool {
+        self.zero_downtime_reinit_after_map_change(rng).await
+    }
+}

src/transport/middle_proxy/pool_reinit/tests.rs

@@ -0,0 +1,97 @@
+use std::collections::{HashMap, HashSet};
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+
+use super::{MePool, commit_reinit_state};
+use crate::transport::middle_proxy::pool::{
+    ReinitAttemptState, ReinitCoordinatorState, ReinitPendingState,
+};
+
+fn addr(octet: u8, port: u16) -> SocketAddr {
+    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, octet)), port)
+}
+
+#[test]
+fn coverage_ratio_counts_dc_coverage_not_floor() {
+    let dc1 = addr(1, 2001);
+    let dc2 = addr(2, 2002);
+
+    let mut desired_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
+    desired_by_dc.insert(1, HashSet::from([dc1]));
+    desired_by_dc.insert(2, HashSet::from([dc2]));
+
+    let active_writer_addrs = HashSet::from([(1, dc1)]);
+    let (ratio, missing_dc) = MePool::coverage_ratio(&desired_by_dc, &active_writer_addrs);
+
+    assert_eq!(ratio, 0.5);
+    assert_eq!(missing_dc, vec![2]);
+}
+
+#[test]
+fn coverage_ratio_ignores_empty_dc_groups() {
+    let dc1 = addr(1, 2001);
+
+    let mut desired_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
+    desired_by_dc.insert(1, HashSet::from([dc1]));
+    desired_by_dc.insert(2, HashSet::new());
+
+    let active_writer_addrs = HashSet::from([(1, dc1)]);
+    let (ratio, missing_dc) = MePool::coverage_ratio(&desired_by_dc, &active_writer_addrs);
+
+    assert_eq!(ratio, 1.0);
+    assert!(missing_dc.is_empty());
+}
+
+#[test]
+fn coverage_ratio_reports_missing_dcs_sorted() {
+    let dc1 = addr(1, 2001);
+    let dc2 = addr(2, 2002);
+
+    let mut desired_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
+    desired_by_dc.insert(2, HashSet::from([dc2]));
+    desired_by_dc.insert(1, HashSet::from([dc1]));
+
+    let (ratio, missing_dc) = MePool::coverage_ratio(&desired_by_dc, &HashSet::new());
+
+    assert_eq!(ratio, 0.0);
+    assert_eq!(missing_dc, vec![1, 2]);
+}
+
+#[test]
+fn stale_concurrent_attempt_cannot_regress_active_generation() {
+    let mut state = ReinitCoordinatorState {
+        next_attempt_id: 3,
+        active_generation: 1,
+        desired_map_hash: 22,
+        pending: Some(ReinitPendingState {
+            generation: 3,
+            started_at_epoch_secs: 1,
+            map_hash: 22,
+        }),
+        attempts: HashMap::from([
+            (
+                1,
+                ReinitAttemptState {
+                    generation: 2,
+                    map_hash: 11,
+                    hardswap: true,
+                    committed: false,
+                },
+            ),
+            (
+                2,
+                ReinitAttemptState {
+                    generation: 3,
+                    map_hash: 22,
+                    hardswap: true,
+                    committed: false,
+                },
+            ),
+        ]),
+    };
+
+    assert!(commit_reinit_state(&mut state, 2, 3, 22, true));
+    assert_eq!(state.active_generation, 3);
+    assert!(!commit_reinit_state(&mut state, 1, 2, 11, true));
+    assert_eq!(state.active_generation, 3);
+    assert!(state.pending.is_none());
+}

src/transport/middle_proxy/pool_runtime_api.rs

@@ -68,10 +68,7 @@ impl MePool {
             .values()
             .filter(|pending| pending.is_some())
             .count();
-        let inflight_dc_keys = refill_states
-            .keys()
-            .copied()
-            .collect::<Vec<RefillDcKey>>();
+        let inflight_dc_keys = refill_states.keys().copied().collect::<Vec<RefillDcKey>>();
         drop(refill_states);
 
         let mut by_dc_map = HashMap::<(i16, &'static str), usize>::new();

src/transport/middle_proxy/pool_status.rs

@@ -8,6 +8,10 @@ use super::pool::{MePool, ReinitStatusSnapshot, WriterContour};
 use crate::config::{MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy};
 use crate::transport::upstream::IpPreference;
 
+// ME writer and DC coverage snapshots.
+mod status_snapshot;
+// ME runtime policy and coherent snapshot assembly.
+mod runtime_snapshot;
 #[derive(Clone, Debug)]
 pub(crate) struct MeApiWriterStatusSnapshot {
     pub writer_id: u64,
@@ -146,562 +150,6 @@ pub(crate) struct MeApiRuntimeSnapshot {
     pub network_path: Vec<MeApiDcPathSnapshot>,
 }
 
-impl MePool {
-    pub(crate) async fn admission_ready_conditional_cast(&self) -> bool {
-        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
-        if self.decision.ipv4_me {
-            let map = self.proxy_map_v4.read().await.clone();
-            extend_signed_endpoints(&mut endpoints_by_dc, map);
-        }
-        if self.decision.ipv6_me {
-            let map = self.proxy_map_v6.read().await.clone();
-            extend_signed_endpoints(&mut endpoints_by_dc, map);
-        }
-
-        if endpoints_by_dc.is_empty() {
-            return false;
-        }
-
-        let writers = self.writers.read().await.clone();
-        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
-        for writer in writers.iter() {
-            if writer.draining.load(Ordering::Relaxed) {
-                continue;
-            }
-            if let Ok(dc) = i16::try_from(writer.writer_dc) {
-                *live_writers_by_dc.entry(dc).or_insert(0) += 1;
-            }
-        }
-
-        for dc in endpoints_by_dc.keys() {
-            let alive = live_writers_by_dc.get(dc).copied().unwrap_or(0);
-            if alive == 0 {
-                return false;
-            }
-        }
-
-        true
-    }
-
-    #[allow(dead_code)]
-    pub(crate) async fn admission_ready_full_floor(&self) -> bool {
-        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
-        if self.decision.ipv4_me {
-            let map = self.proxy_map_v4.read().await.clone();
-            extend_signed_endpoints(&mut endpoints_by_dc, map);
-        }
-        if self.decision.ipv6_me {
-            let map = self.proxy_map_v6.read().await.clone();
-            extend_signed_endpoints(&mut endpoints_by_dc, map);
-        }
-
-        if endpoints_by_dc.is_empty() {
-            return false;
-        }
-
-        let writers = self.writers.read().await.clone();
-        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
-        for writer in writers.iter() {
-            if writer.draining.load(Ordering::Relaxed) {
-                continue;
-            }
-            if let Ok(dc) = i16::try_from(writer.writer_dc) {
-                *live_writers_by_dc.entry(dc).or_insert(0) += 1;
-            }
-        }
-
-        for (dc, endpoints) in endpoints_by_dc {
-            let endpoint_count = endpoints.len();
-            if endpoint_count == 0 {
-                return false;
-            }
-            let required = self.required_writers_for_dc_with_floor_mode(endpoint_count, false);
-            let alive = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
-            if alive < required {
-                return false;
-            }
-        }
-
-        true
-    }
-
-    pub(crate) async fn api_status_snapshot(&self) -> MeApiStatusSnapshot {
-        let reinit = self.reinit.status.load_full();
-        self.api_status_snapshot_for_reinit(reinit.as_ref()).await
-    }
-
-    async fn api_status_snapshot_for_reinit(
-        &self,
-        reinit: &ReinitStatusSnapshot,
-    ) -> MeApiStatusSnapshot {
-        let now_epoch_secs = Self::now_epoch_secs();
-        let active_generation = reinit.active_generation;
-        let drain_ttl_secs = self
-            .drain_runtime
-            .me_pool_drain_ttl_secs
-            .load(Ordering::Relaxed);
-
-        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
-        if self.decision.ipv4_me {
-            let map = self.proxy_map_v4.read().await.clone();
-            extend_signed_endpoints(&mut endpoints_by_dc, map);
-        }
-        if self.decision.ipv6_me {
-            let map = self.proxy_map_v6.read().await.clone();
-            extend_signed_endpoints(&mut endpoints_by_dc, map);
-        }
-
-        let configured_dc_groups = endpoints_by_dc.len();
-        let configured_endpoints = endpoints_by_dc.values().map(BTreeSet::len).sum();
-
-        let required_writers = endpoints_by_dc
-            .values()
-            .map(|endpoints| self.required_writers_for_dc_with_floor_mode(endpoints.len(), false))
-            .sum();
-
-        let idle_since = self.registry.writer_idle_since_snapshot().await;
-        let activity = self.registry.writer_activity_snapshot().await;
-        let rtt = self.rtt_stats.lock().await.clone();
-        let writers = self.writers.read().await.clone();
-
-        let mut live_writers_by_dc_endpoint = HashMap::<(i16, SocketAddr), usize>::new();
-        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
-        let mut fresh_writers_by_dc = HashMap::<i16, usize>::new();
-        let mut dc_rtt_agg = HashMap::<i16, (f64, u64)>::new();
-        let mut writer_rows = Vec::<MeApiWriterStatusSnapshot>::with_capacity(writers.len());
-
-        for writer in writers.iter() {
-            let endpoint = writer.addr;
-            let dc = i16::try_from(writer.writer_dc).ok();
-            let draining = writer.draining.load(Ordering::Relaxed);
-            let degraded = writer.degraded.load(Ordering::Relaxed);
-            let matches_active_generation = writer.generation == active_generation;
-            let in_desired_map = dc
-                .and_then(|dc_idx| endpoints_by_dc.get(&dc_idx))
-                .is_some_and(|endpoints| endpoints.contains(&endpoint));
-            let bound_clients = activity
-                .bound_clients_by_writer
-                .get(&writer.id)
-                .copied()
-                .unwrap_or(0);
-            let idle_for_secs = idle_since
-                .get(&writer.id)
-                .map(|idle_ts| now_epoch_secs.saturating_sub(*idle_ts));
-            let rtt_ema_ms = rtt.get(&writer.id).map(|(_, ema)| *ema);
-            let allow_drain_fallback = writer.allow_drain_fallback.load(Ordering::Relaxed);
-            let drain_started_at_epoch_secs = writer
-                .draining_started_at_epoch_secs
-                .load(Ordering::Relaxed);
-            let drain_deadline_epoch_secs =
-                writer.drain_deadline_epoch_secs.load(Ordering::Relaxed);
-            let drain_started_at_epoch_secs =
-                (drain_started_at_epoch_secs != 0).then_some(drain_started_at_epoch_secs);
-            let drain_deadline_epoch_secs =
-                (drain_deadline_epoch_secs != 0).then_some(drain_deadline_epoch_secs);
-            let drain_over_ttl = draining
-                && drain_ttl_secs > 0
-                && drain_started_at_epoch_secs
-                    .is_some_and(|started| now_epoch_secs.saturating_sub(started) > drain_ttl_secs);
-            let state = match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
-                WriterContour::Warm => "warm",
-                WriterContour::Active => "active",
-                WriterContour::Draining => "draining",
-            };
-
-            if !draining && let Some(dc_idx) = dc {
-                *live_writers_by_dc_endpoint
-                    .entry((dc_idx, endpoint))
-                    .or_insert(0) += 1;
-                *live_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
-                if let Some(ema_ms) = rtt_ema_ms {
-                    let entry = dc_rtt_agg.entry(dc_idx).or_insert((0.0, 0));
-                    entry.0 += ema_ms;
-                    entry.1 += 1;
-                }
-                if matches_active_generation && in_desired_map {
-                    *fresh_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
-                }
-            }
-
-            writer_rows.push(MeApiWriterStatusSnapshot {
-                writer_id: writer.id,
-                dc,
-                endpoint,
-                generation: writer.generation,
-                state,
-                draining,
-                degraded,
-                bound_clients,
-                idle_for_secs,
-                rtt_ema_ms,
-                matches_active_generation,
-                in_desired_map,
-                allow_drain_fallback,
-                drain_started_at_epoch_secs,
-                drain_deadline_epoch_secs,
-                drain_over_ttl,
-            });
-        }
-
-        writer_rows.sort_by_key(|row| (row.dc.unwrap_or(i16::MAX), row.endpoint, row.writer_id));
-
-        let mut dcs = Vec::<MeApiDcStatusSnapshot>::with_capacity(endpoints_by_dc.len());
-        let mut available_endpoints = 0usize;
-        let mut alive_writers = 0usize;
-        let mut fresh_alive_writers = 0usize;
-        let floor_mode = self.floor_mode();
-        let adaptive_cpu_cores = (self
-            .floor_runtime
-            .me_adaptive_floor_cpu_cores_effective
-            .load(Ordering::Relaxed) as usize)
-            .max(1);
-        for (dc, endpoints) in endpoints_by_dc {
-            let endpoint_count = endpoints.len();
-            let dc_available_endpoints = endpoints
-                .iter()
-                .filter(|endpoint| live_writers_by_dc_endpoint.contains_key(&(dc, **endpoint)))
-                .count();
-            let base_required = self.required_writers_for_dc(endpoint_count);
-            let dc_required_writers =
-                self.required_writers_for_dc_with_floor_mode(endpoint_count, false);
-            let floor_min = if endpoint_count <= 1 {
-                (self
-                    .floor_runtime
-                    .me_adaptive_floor_min_writers_single_endpoint
-                    .load(Ordering::Relaxed) as usize)
-                    .max(1)
-                    .min(base_required.max(1))
-            } else {
-                (self
-                    .floor_runtime
-                    .me_adaptive_floor_min_writers_multi_endpoint
-                    .load(Ordering::Relaxed) as usize)
-                    .max(1)
-                    .min(base_required.max(1))
-            };
-            let extra_per_core = if endpoint_count <= 1 {
-                self.floor_runtime
-                    .me_adaptive_floor_max_extra_writers_single_per_core
-                    .load(Ordering::Relaxed) as usize
-            } else {
-                self.floor_runtime
-                    .me_adaptive_floor_max_extra_writers_multi_per_core
-                    .load(Ordering::Relaxed) as usize
-            };
-            let floor_max =
-                base_required.saturating_add(adaptive_cpu_cores.saturating_mul(extra_per_core));
-            let floor_capped =
-                matches!(floor_mode, MeFloorMode::Adaptive) && dc_required_writers < base_required;
-            let dc_alive_writers = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
-            let dc_fresh_alive_writers = fresh_writers_by_dc.get(&dc).copied().unwrap_or(0);
-            let dc_load = activity
-                .active_sessions_by_target_dc
-                .get(&dc)
-                .copied()
-                .unwrap_or(0);
-            let dc_rtt_ms = dc_rtt_agg
-                .get(&dc)
-                .and_then(|(sum, count)| (*count > 0).then_some(*sum / (*count as f64)));
-
-            available_endpoints += dc_available_endpoints;
-            alive_writers += dc_alive_writers;
-            fresh_alive_writers += dc_fresh_alive_writers;
-
-            dcs.push(MeApiDcStatusSnapshot {
-                dc,
-                endpoint_writers: endpoints
-                    .iter()
-                    .map(|endpoint| MeApiDcEndpointWriterSnapshot {
-                        endpoint: *endpoint,
-                        active_writers: live_writers_by_dc_endpoint
-                            .get(&(dc, *endpoint))
-                            .copied()
-                            .unwrap_or(0),
-                    })
-                    .collect(),
-                endpoints: endpoints.into_iter().collect(),
-                available_endpoints: dc_available_endpoints,
-                available_pct: ratio_pct(dc_available_endpoints, endpoint_count),
-                required_writers: dc_required_writers,
-                floor_min,
-                floor_target: dc_required_writers,
-                floor_max,
-                floor_capped,
-                alive_writers: dc_alive_writers,
-                coverage_pct: ratio_pct(dc_alive_writers, dc_required_writers),
-                fresh_alive_writers: dc_fresh_alive_writers,
-                fresh_coverage_pct: ratio_pct(dc_fresh_alive_writers, dc_required_writers),
-                rtt_ms: dc_rtt_ms,
-                load: dc_load,
-            });
-        }
-
-        MeApiStatusSnapshot {
-            generated_at_epoch_secs: now_epoch_secs,
-            configured_dc_groups,
-            configured_endpoints,
-            available_endpoints,
-            available_pct: ratio_pct(available_endpoints, configured_endpoints),
-            required_writers,
-            alive_writers,
-            coverage_pct: ratio_pct(alive_writers, required_writers),
-            fresh_alive_writers,
-            fresh_coverage_pct: ratio_pct(fresh_alive_writers, required_writers),
-            writers: writer_rows,
-            dcs,
-        }
-    }
-
-    #[allow(dead_code)]
-    pub(crate) async fn api_runtime_snapshot(&self) -> MeApiRuntimeSnapshot {
-        let reinit = self.reinit.status.load_full();
-        self.api_runtime_snapshot_for_reinit(reinit.as_ref()).await
-    }
-
-    async fn api_runtime_snapshot_for_reinit(
-        &self,
-        reinit: &ReinitStatusSnapshot,
-    ) -> MeApiRuntimeSnapshot {
-        let now = Instant::now();
-        let now_epoch_secs = Self::now_epoch_secs();
-        let pending_started_at = reinit.pending_hardswap_started_at_epoch_secs;
-        let pending_hardswap_age_secs =
-            (pending_started_at > 0).then_some(now_epoch_secs.saturating_sub(pending_started_at));
-
-        let mut quarantined_endpoints = Vec::<MeApiQuarantinedEndpointSnapshot>::new();
-        {
-            let guard = self.endpoint_quarantine.lock().await;
-            for (endpoint, expires_at) in guard.iter() {
-                if *expires_at <= now {
-                    continue;
-                }
-                let remaining_ms = expires_at.duration_since(now).as_millis() as u64;
-                quarantined_endpoints.push(MeApiQuarantinedEndpointSnapshot {
-                    endpoint: *endpoint,
-                    remaining_ms,
-                });
-            }
-        }
-        quarantined_endpoints.sort_by_key(|entry| entry.endpoint);
-
-        let mut network_path = Vec::<MeApiDcPathSnapshot>::new();
-        if let Some(upstream) = &self.upstream {
-            for dc in 1..=5 {
-                let dc_idx = dc as i16;
-                let ip_preference = upstream
-                    .get_dc_ip_preference(dc_idx)
-                    .await
-                    .map(ip_preference_label);
-                let selected_addr_v4 = upstream.get_dc_addr(dc_idx, false).await;
-                let selected_addr_v6 = upstream.get_dc_addr(dc_idx, true).await;
-                network_path.push(MeApiDcPathSnapshot {
-                    dc: dc_idx,
-                    ip_preference,
-                    selected_addr_v4,
-                    selected_addr_v6,
-                });
-            }
-        }
-
-        MeApiRuntimeSnapshot {
-            active_generation: reinit.active_generation,
-            warm_generation: reinit.warm_generations.last().copied().unwrap_or(0),
-            warm_generations: reinit.warm_generations.clone(),
-            pending_hardswap_generation: reinit.pending_hardswap_generation,
-            pending_hardswap_age_secs,
-            reinit_inflight: reinit.inflight,
-            reinit_max_concurrency_effective: self
-                .reinit
-                .max_concurrency_effective
-                .load(Ordering::Acquire),
-            hardswap_enabled: self.reinit.hardswap.load(Ordering::Relaxed),
-            floor_mode: floor_mode_label(self.floor_mode()),
-            adaptive_floor_idle_secs: self
-                .floor_runtime
-                .me_adaptive_floor_idle_secs
-                .load(Ordering::Relaxed),
-            adaptive_floor_min_writers_single_endpoint: self
-                .floor_runtime
-                .me_adaptive_floor_min_writers_single_endpoint
-                .load(Ordering::Relaxed),
-            adaptive_floor_min_writers_multi_endpoint: self
-                .floor_runtime
-                .me_adaptive_floor_min_writers_multi_endpoint
-                .load(Ordering::Relaxed),
-            adaptive_floor_recover_grace_secs: self
-                .floor_runtime
-                .me_adaptive_floor_recover_grace_secs
-                .load(Ordering::Relaxed),
-            adaptive_floor_writers_per_core_total: self
-                .floor_runtime
-                .me_adaptive_floor_writers_per_core_total
-                .load(Ordering::Relaxed) as u16,
-            adaptive_floor_cpu_cores_override: self
-                .floor_runtime
-                .me_adaptive_floor_cpu_cores_override
-                .load(Ordering::Relaxed) as u16,
-            adaptive_floor_max_extra_writers_single_per_core: self
-                .floor_runtime
-                .me_adaptive_floor_max_extra_writers_single_per_core
-                .load(Ordering::Relaxed)
-                as u16,
-            adaptive_floor_max_extra_writers_multi_per_core: self
-                .floor_runtime
-                .me_adaptive_floor_max_extra_writers_multi_per_core
-                .load(Ordering::Relaxed)
-                as u16,
-            adaptive_floor_max_active_writers_per_core: self
-                .floor_runtime
-                .me_adaptive_floor_max_active_writers_per_core
-                .load(Ordering::Relaxed)
-                as u16,
-            adaptive_floor_max_warm_writers_per_core: self
-                .floor_runtime
-                .me_adaptive_floor_max_warm_writers_per_core
-                .load(Ordering::Relaxed)
-                as u16,
-            adaptive_floor_max_active_writers_global: self
-                .floor_runtime
-                .me_adaptive_floor_max_active_writers_global
-                .load(Ordering::Relaxed),
-            adaptive_floor_max_warm_writers_global: self
-                .floor_runtime
-                .me_adaptive_floor_max_warm_writers_global
-                .load(Ordering::Relaxed),
-            adaptive_floor_cpu_cores_detected: self
-                .floor_runtime
-                .me_adaptive_floor_cpu_cores_detected
-                .load(Ordering::Relaxed),
-            adaptive_floor_cpu_cores_effective: self
-                .floor_runtime
-                .me_adaptive_floor_cpu_cores_effective
-                .load(Ordering::Relaxed),
-            adaptive_floor_global_cap_raw: self
-                .floor_runtime
-                .me_adaptive_floor_global_cap_raw
-                .load(Ordering::Relaxed),
-            adaptive_floor_global_cap_effective: self
-                .floor_runtime
-                .me_adaptive_floor_global_cap_effective
-                .load(Ordering::Relaxed),
-            adaptive_floor_target_writers_total: self
-                .floor_runtime
-                .me_adaptive_floor_target_writers_total
-                .load(Ordering::Relaxed),
-            adaptive_floor_active_cap_configured: self
-                .floor_runtime
-                .me_adaptive_floor_active_cap_configured
-                .load(Ordering::Relaxed),
-            adaptive_floor_active_cap_effective: self
-                .floor_runtime
-                .me_adaptive_floor_active_cap_effective
-                .load(Ordering::Relaxed),
-            adaptive_floor_warm_cap_configured: self
-                .floor_runtime
-                .me_adaptive_floor_warm_cap_configured
-                .load(Ordering::Relaxed),
-            adaptive_floor_warm_cap_effective: self
-                .floor_runtime
-                .me_adaptive_floor_warm_cap_effective
-                .load(Ordering::Relaxed),
-            adaptive_floor_active_writers_current: self
-                .floor_runtime
-                .me_adaptive_floor_active_writers_current
-                .load(Ordering::Relaxed),
-            adaptive_floor_warm_writers_current: self
-                .floor_runtime
-                .me_adaptive_floor_warm_writers_current
-                .load(Ordering::Relaxed),
-            me_keepalive_enabled: self.writer_lifecycle.me_keepalive_enabled,
-            me_keepalive_interval_secs: self.writer_lifecycle.me_keepalive_interval.as_secs(),
-            me_keepalive_jitter_secs: self.writer_lifecycle.me_keepalive_jitter.as_secs(),
-            me_keepalive_payload_random: self.writer_lifecycle.me_keepalive_payload_random,
-            rpc_proxy_req_every_secs: self
-                .writer_lifecycle
-                .rpc_proxy_req_every_secs
-                .load(Ordering::Relaxed),
-            me_reconnect_max_concurrent_per_dc: self
-                .reconnect_runtime
-                .me_reconnect_max_concurrent_per_dc,
-            me_reconnect_backoff_base_ms: self
-                .reconnect_runtime
-                .me_reconnect_backoff_base
-                .as_millis() as u64,
-            me_reconnect_backoff_cap_ms: self.reconnect_runtime.me_reconnect_backoff_cap.as_millis()
-                as u64,
-            me_reconnect_fast_retry_count: self.reconnect_runtime.me_reconnect_fast_retry_count,
-            me_pool_drain_ttl_secs: self
-                .drain_runtime
-                .me_pool_drain_ttl_secs
-                .load(Ordering::Relaxed),
-            me_pool_force_close_secs: self
-                .drain_runtime
-                .me_pool_force_close_secs
-                .load(Ordering::Relaxed),
-            me_pool_min_fresh_ratio: Self::permille_to_ratio(
-                self.drain_runtime
-                    .me_pool_min_fresh_ratio_permille
-                    .load(Ordering::Relaxed),
-            ),
-            me_bind_stale_mode: bind_stale_mode_label(self.bind_stale_mode()),
-            me_bind_stale_ttl_secs: self
-                .binding_policy
-                .me_bind_stale_ttl_secs
-                .load(Ordering::Relaxed),
-            me_single_endpoint_shadow_writers: self
-                .single_endpoint_runtime
-                .me_single_endpoint_shadow_writers
-                .load(Ordering::Relaxed),
-            me_single_endpoint_outage_mode_enabled: self
-                .single_endpoint_runtime
-                .me_single_endpoint_outage_mode_enabled
-                .load(Ordering::Relaxed),
-            me_single_endpoint_outage_disable_quarantine: self
-                .single_endpoint_runtime
-                .me_single_endpoint_outage_disable_quarantine
-                .load(Ordering::Relaxed),
-            me_single_endpoint_outage_backoff_min_ms: self
-                .single_endpoint_runtime
-                .me_single_endpoint_outage_backoff_min_ms
-                .load(Ordering::Relaxed),
-            me_single_endpoint_outage_backoff_max_ms: self
-                .single_endpoint_runtime
-                .me_single_endpoint_outage_backoff_max_ms
-                .load(Ordering::Relaxed),
-            me_single_endpoint_shadow_rotate_every_secs: self
-                .single_endpoint_runtime
-                .me_single_endpoint_shadow_rotate_every_secs
-                .load(Ordering::Relaxed),
-            me_deterministic_writer_sort: self
-                .writer_selection_policy
-                .me_deterministic_writer_sort
-                .load(Ordering::Relaxed),
-            me_writer_pick_mode: writer_pick_mode_label(self.writer_pick_mode()),
-            me_writer_pick_sample_size: self.writer_pick_sample_size() as u8,
-            me_socks_kdf_policy: socks_kdf_policy_label(self.socks_kdf_policy()),
-            quarantined_endpoints,
-            network_path,
-        }
-    }
-
-    pub(crate) async fn api_coherent_snapshots(
-        &self,
-    ) -> (MeApiStatusSnapshot, MeApiRuntimeSnapshot) {
-        let mut attempts = 0usize;
-        loop {
-            let reinit = self.reinit.status.load_full();
-            let status = self.api_status_snapshot_for_reinit(reinit.as_ref()).await;
-            let runtime = self
-                .api_runtime_snapshot_for_reinit(reinit.as_ref())
-                .await;
-            attempts += 1;
-            if Arc::ptr_eq(&reinit, &self.reinit.status.load_full()) || attempts >= 3 {
-                return (status, runtime);
-            }
-        }
-    }
-}
-
 fn ratio_pct(part: usize, total: usize) -> f64 {
     if total == 0 {
         return 0.0;

src/transport/middle_proxy/pool_status/runtime_snapshot.rs

@@ -0,0 +1,250 @@
+use super::*;
+
+impl MePool {
+    #[allow(dead_code)]
+    pub(crate) async fn api_runtime_snapshot(&self) -> MeApiRuntimeSnapshot {
+        let reinit = self.reinit.status.load_full();
+        self.api_runtime_snapshot_for_reinit(reinit.as_ref()).await
+    }
+
+    async fn api_runtime_snapshot_for_reinit(
+        &self,
+        reinit: &ReinitStatusSnapshot,
+    ) -> MeApiRuntimeSnapshot {
+        let now = Instant::now();
+        let now_epoch_secs = Self::now_epoch_secs();
+        let pending_started_at = reinit.pending_hardswap_started_at_epoch_secs;
+        let pending_hardswap_age_secs =
+            (pending_started_at > 0).then_some(now_epoch_secs.saturating_sub(pending_started_at));
+
+        let mut quarantined_endpoints = Vec::<MeApiQuarantinedEndpointSnapshot>::new();
+        {
+            let guard = self.endpoint_quarantine.lock().await;
+            for (endpoint, expires_at) in guard.iter() {
+                if *expires_at <= now {
+                    continue;
+                }
+                let remaining_ms = expires_at.duration_since(now).as_millis() as u64;
+                quarantined_endpoints.push(MeApiQuarantinedEndpointSnapshot {
+                    endpoint: *endpoint,
+                    remaining_ms,
+                });
+            }
+        }
+        quarantined_endpoints.sort_by_key(|entry| entry.endpoint);
+
+        let mut network_path = Vec::<MeApiDcPathSnapshot>::new();
+        if let Some(upstream) = &self.upstream {
+            for dc in 1..=5 {
+                let dc_idx = dc as i16;
+                let ip_preference = upstream
+                    .get_dc_ip_preference(dc_idx)
+                    .await
+                    .map(ip_preference_label);
+                let selected_addr_v4 = upstream.get_dc_addr(dc_idx, false).await;
+                let selected_addr_v6 = upstream.get_dc_addr(dc_idx, true).await;
+                network_path.push(MeApiDcPathSnapshot {
+                    dc: dc_idx,
+                    ip_preference,
+                    selected_addr_v4,
+                    selected_addr_v6,
+                });
+            }
+        }
+
+        MeApiRuntimeSnapshot {
+            active_generation: reinit.active_generation,
+            warm_generation: reinit.warm_generations.last().copied().unwrap_or(0),
+            warm_generations: reinit.warm_generations.clone(),
+            pending_hardswap_generation: reinit.pending_hardswap_generation,
+            pending_hardswap_age_secs,
+            reinit_inflight: reinit.inflight,
+            reinit_max_concurrency_effective: self
+                .reinit
+                .max_concurrency_effective
+                .load(Ordering::Acquire),
+            hardswap_enabled: self.reinit.hardswap.load(Ordering::Relaxed),
+            floor_mode: floor_mode_label(self.floor_mode()),
+            adaptive_floor_idle_secs: self
+                .floor_runtime
+                .me_adaptive_floor_idle_secs
+                .load(Ordering::Relaxed),
+            adaptive_floor_min_writers_single_endpoint: self
+                .floor_runtime
+                .me_adaptive_floor_min_writers_single_endpoint
+                .load(Ordering::Relaxed),
+            adaptive_floor_min_writers_multi_endpoint: self
+                .floor_runtime
+                .me_adaptive_floor_min_writers_multi_endpoint
+                .load(Ordering::Relaxed),
+            adaptive_floor_recover_grace_secs: self
+                .floor_runtime
+                .me_adaptive_floor_recover_grace_secs
+                .load(Ordering::Relaxed),
+            adaptive_floor_writers_per_core_total: self
+                .floor_runtime
+                .me_adaptive_floor_writers_per_core_total
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_cpu_cores_override: self
+                .floor_runtime
+                .me_adaptive_floor_cpu_cores_override
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_max_extra_writers_single_per_core: self
+                .floor_runtime
+                .me_adaptive_floor_max_extra_writers_single_per_core
+                .load(Ordering::Relaxed)
+                as u16,
+            adaptive_floor_max_extra_writers_multi_per_core: self
+                .floor_runtime
+                .me_adaptive_floor_max_extra_writers_multi_per_core
+                .load(Ordering::Relaxed)
+                as u16,
+            adaptive_floor_max_active_writers_per_core: self
+                .floor_runtime
+                .me_adaptive_floor_max_active_writers_per_core
+                .load(Ordering::Relaxed)
+                as u16,
+            adaptive_floor_max_warm_writers_per_core: self
+                .floor_runtime
+                .me_adaptive_floor_max_warm_writers_per_core
+                .load(Ordering::Relaxed)
+                as u16,
+            adaptive_floor_max_active_writers_global: self
+                .floor_runtime
+                .me_adaptive_floor_max_active_writers_global
+                .load(Ordering::Relaxed),
+            adaptive_floor_max_warm_writers_global: self
+                .floor_runtime
+                .me_adaptive_floor_max_warm_writers_global
+                .load(Ordering::Relaxed),
+            adaptive_floor_cpu_cores_detected: self
+                .floor_runtime
+                .me_adaptive_floor_cpu_cores_detected
+                .load(Ordering::Relaxed),
+            adaptive_floor_cpu_cores_effective: self
+                .floor_runtime
+                .me_adaptive_floor_cpu_cores_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_global_cap_raw: self
+                .floor_runtime
+                .me_adaptive_floor_global_cap_raw
+                .load(Ordering::Relaxed),
+            adaptive_floor_global_cap_effective: self
+                .floor_runtime
+                .me_adaptive_floor_global_cap_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_target_writers_total: self
+                .floor_runtime
+                .me_adaptive_floor_target_writers_total
+                .load(Ordering::Relaxed),
+            adaptive_floor_active_cap_configured: self
+                .floor_runtime
+                .me_adaptive_floor_active_cap_configured
+                .load(Ordering::Relaxed),
+            adaptive_floor_active_cap_effective: self
+                .floor_runtime
+                .me_adaptive_floor_active_cap_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_warm_cap_configured: self
+                .floor_runtime
+                .me_adaptive_floor_warm_cap_configured
+                .load(Ordering::Relaxed),
+            adaptive_floor_warm_cap_effective: self
+                .floor_runtime
+                .me_adaptive_floor_warm_cap_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_active_writers_current: self
+                .floor_runtime
+                .me_adaptive_floor_active_writers_current
+                .load(Ordering::Relaxed),
+            adaptive_floor_warm_writers_current: self
+                .floor_runtime
+                .me_adaptive_floor_warm_writers_current
+                .load(Ordering::Relaxed),
+            me_keepalive_enabled: self.writer_lifecycle.me_keepalive_enabled,
+            me_keepalive_interval_secs: self.writer_lifecycle.me_keepalive_interval.as_secs(),
+            me_keepalive_jitter_secs: self.writer_lifecycle.me_keepalive_jitter.as_secs(),
+            me_keepalive_payload_random: self.writer_lifecycle.me_keepalive_payload_random,
+            rpc_proxy_req_every_secs: self
+                .writer_lifecycle
+                .rpc_proxy_req_every_secs
+                .load(Ordering::Relaxed),
+            me_reconnect_max_concurrent_per_dc: self
+                .reconnect_runtime
+                .me_reconnect_max_concurrent_per_dc,
+            me_reconnect_backoff_base_ms: self
+                .reconnect_runtime
+                .me_reconnect_backoff_base
+                .as_millis() as u64,
+            me_reconnect_backoff_cap_ms: self.reconnect_runtime.me_reconnect_backoff_cap.as_millis()
+                as u64,
+            me_reconnect_fast_retry_count: self.reconnect_runtime.me_reconnect_fast_retry_count,
+            me_pool_drain_ttl_secs: self
+                .drain_runtime
+                .me_pool_drain_ttl_secs
+                .load(Ordering::Relaxed),
+            me_pool_force_close_secs: self
+                .drain_runtime
+                .me_pool_force_close_secs
+                .load(Ordering::Relaxed),
+            me_pool_min_fresh_ratio: Self::permille_to_ratio(
+                self.drain_runtime
+                    .me_pool_min_fresh_ratio_permille
+                    .load(Ordering::Relaxed),
+            ),
+            me_bind_stale_mode: bind_stale_mode_label(self.bind_stale_mode()),
+            me_bind_stale_ttl_secs: self
+                .binding_policy
+                .me_bind_stale_ttl_secs
+                .load(Ordering::Relaxed),
+            me_single_endpoint_shadow_writers: self
+                .single_endpoint_runtime
+                .me_single_endpoint_shadow_writers
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_mode_enabled: self
+                .single_endpoint_runtime
+                .me_single_endpoint_outage_mode_enabled
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_disable_quarantine: self
+                .single_endpoint_runtime
+                .me_single_endpoint_outage_disable_quarantine
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_backoff_min_ms: self
+                .single_endpoint_runtime
+                .me_single_endpoint_outage_backoff_min_ms
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_backoff_max_ms: self
+                .single_endpoint_runtime
+                .me_single_endpoint_outage_backoff_max_ms
+                .load(Ordering::Relaxed),
+            me_single_endpoint_shadow_rotate_every_secs: self
+                .single_endpoint_runtime
+                .me_single_endpoint_shadow_rotate_every_secs
+                .load(Ordering::Relaxed),
+            me_deterministic_writer_sort: self
+                .writer_selection_policy
+                .me_deterministic_writer_sort
+                .load(Ordering::Relaxed),
+            me_writer_pick_mode: writer_pick_mode_label(self.writer_pick_mode()),
+            me_writer_pick_sample_size: self.writer_pick_sample_size() as u8,
+            me_socks_kdf_policy: socks_kdf_policy_label(self.socks_kdf_policy()),
+            quarantined_endpoints,
+            network_path,
+        }
+    }
+
+    pub(crate) async fn api_coherent_snapshots(
+        &self,
+    ) -> (MeApiStatusSnapshot, MeApiRuntimeSnapshot) {
+        let mut attempts = 0usize;
+        loop {
+            let reinit = self.reinit.status.load_full();
+            let status = self.api_status_snapshot_for_reinit(reinit.as_ref()).await;
+            let runtime = self.api_runtime_snapshot_for_reinit(reinit.as_ref()).await;
+            attempts += 1;
+            if Arc::ptr_eq(&reinit, &self.reinit.status.load_full()) || attempts >= 3 {
+                return (status, runtime);
+            }
+        }
+    }
+}

src/transport/middle_proxy/pool_status/status_snapshot.rs

@@ -0,0 +1,308 @@
+use super::*;
+
+impl MePool {
+    pub(crate) async fn admission_ready_conditional_cast(&self) -> bool {
+        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+
+        if endpoints_by_dc.is_empty() {
+            return false;
+        }
+
+        let writers = self.writers.read().await.clone();
+        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        for writer in writers.iter() {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            if let Ok(dc) = i16::try_from(writer.writer_dc) {
+                *live_writers_by_dc.entry(dc).or_insert(0) += 1;
+            }
+        }
+
+        for dc in endpoints_by_dc.keys() {
+            let alive = live_writers_by_dc.get(dc).copied().unwrap_or(0);
+            if alive == 0 {
+                return false;
+            }
+        }
+
+        true
+    }
+
+    #[allow(dead_code)]
+    pub(crate) async fn admission_ready_full_floor(&self) -> bool {
+        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+
+        if endpoints_by_dc.is_empty() {
+            return false;
+        }
+
+        let writers = self.writers.read().await.clone();
+        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        for writer in writers.iter() {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            if let Ok(dc) = i16::try_from(writer.writer_dc) {
+                *live_writers_by_dc.entry(dc).or_insert(0) += 1;
+            }
+        }
+
+        for (dc, endpoints) in endpoints_by_dc {
+            let endpoint_count = endpoints.len();
+            if endpoint_count == 0 {
+                return false;
+            }
+            let required = self.required_writers_for_dc_with_floor_mode(endpoint_count, false);
+            let alive = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            if alive < required {
+                return false;
+            }
+        }
+
+        true
+    }
+
+    pub(crate) async fn api_status_snapshot(&self) -> MeApiStatusSnapshot {
+        let reinit = self.reinit.status.load_full();
+        self.api_status_snapshot_for_reinit(reinit.as_ref()).await
+    }
+
+    pub(super) async fn api_status_snapshot_for_reinit(
+        &self,
+        reinit: &ReinitStatusSnapshot,
+    ) -> MeApiStatusSnapshot {
+        let now_epoch_secs = Self::now_epoch_secs();
+        let active_generation = reinit.active_generation;
+        let drain_ttl_secs = self
+            .drain_runtime
+            .me_pool_drain_ttl_secs
+            .load(Ordering::Relaxed);
+
+        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+
+        let configured_dc_groups = endpoints_by_dc.len();
+        let configured_endpoints = endpoints_by_dc.values().map(BTreeSet::len).sum();
+
+        let required_writers = endpoints_by_dc
+            .values()
+            .map(|endpoints| self.required_writers_for_dc_with_floor_mode(endpoints.len(), false))
+            .sum();
+
+        let idle_since = self.registry.writer_idle_since_snapshot().await;
+        let activity = self.registry.writer_activity_snapshot().await;
+        let rtt = self.rtt_stats.lock().await.clone();
+        let writers = self.writers.read().await.clone();
+
+        let mut live_writers_by_dc_endpoint = HashMap::<(i16, SocketAddr), usize>::new();
+        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        let mut fresh_writers_by_dc = HashMap::<i16, usize>::new();
+        let mut dc_rtt_agg = HashMap::<i16, (f64, u64)>::new();
+        let mut writer_rows = Vec::<MeApiWriterStatusSnapshot>::with_capacity(writers.len());
+
+        for writer in writers.iter() {
+            let endpoint = writer.addr;
+            let dc = i16::try_from(writer.writer_dc).ok();
+            let draining = writer.draining.load(Ordering::Relaxed);
+            let degraded = writer.degraded.load(Ordering::Relaxed);
+            let matches_active_generation = writer.generation == active_generation;
+            let in_desired_map = dc
+                .and_then(|dc_idx| endpoints_by_dc.get(&dc_idx))
+                .is_some_and(|endpoints| endpoints.contains(&endpoint));
+            let bound_clients = activity
+                .bound_clients_by_writer
+                .get(&writer.id)
+                .copied()
+                .unwrap_or(0);
+            let idle_for_secs = idle_since
+                .get(&writer.id)
+                .map(|idle_ts| now_epoch_secs.saturating_sub(*idle_ts));
+            let rtt_ema_ms = rtt.get(&writer.id).map(|(_, ema)| *ema);
+            let allow_drain_fallback = writer.allow_drain_fallback.load(Ordering::Relaxed);
+            let drain_started_at_epoch_secs = writer
+                .draining_started_at_epoch_secs
+                .load(Ordering::Relaxed);
+            let drain_deadline_epoch_secs =
+                writer.drain_deadline_epoch_secs.load(Ordering::Relaxed);
+            let drain_started_at_epoch_secs =
+                (drain_started_at_epoch_secs != 0).then_some(drain_started_at_epoch_secs);
+            let drain_deadline_epoch_secs =
+                (drain_deadline_epoch_secs != 0).then_some(drain_deadline_epoch_secs);
+            let drain_over_ttl = draining
+                && drain_ttl_secs > 0
+                && drain_started_at_epoch_secs
+                    .is_some_and(|started| now_epoch_secs.saturating_sub(started) > drain_ttl_secs);
+            let state = match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
+                WriterContour::Warm => "warm",
+                WriterContour::Active => "active",
+                WriterContour::Draining => "draining",
+            };
+
+            if !draining && let Some(dc_idx) = dc {
+                *live_writers_by_dc_endpoint
+                    .entry((dc_idx, endpoint))
+                    .or_insert(0) += 1;
+                *live_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
+                if let Some(ema_ms) = rtt_ema_ms {
+                    let entry = dc_rtt_agg.entry(dc_idx).or_insert((0.0, 0));
+                    entry.0 += ema_ms;
+                    entry.1 += 1;
+                }
+                if matches_active_generation && in_desired_map {
+                    *fresh_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
+                }
+            }
+
+            writer_rows.push(MeApiWriterStatusSnapshot {
+                writer_id: writer.id,
+                dc,
+                endpoint,
+                generation: writer.generation,
+                state,
+                draining,
+                degraded,
+                bound_clients,
+                idle_for_secs,
+                rtt_ema_ms,
+                matches_active_generation,
+                in_desired_map,
+                allow_drain_fallback,
+                drain_started_at_epoch_secs,
+                drain_deadline_epoch_secs,
+                drain_over_ttl,
+            });
+        }
+
+        writer_rows.sort_by_key(|row| (row.dc.unwrap_or(i16::MAX), row.endpoint, row.writer_id));
+
+        let mut dcs = Vec::<MeApiDcStatusSnapshot>::with_capacity(endpoints_by_dc.len());
+        let mut available_endpoints = 0usize;
+        let mut alive_writers = 0usize;
+        let mut fresh_alive_writers = 0usize;
+        let floor_mode = self.floor_mode();
+        let adaptive_cpu_cores = (self
+            .floor_runtime
+            .me_adaptive_floor_cpu_cores_effective
+            .load(Ordering::Relaxed) as usize)
+            .max(1);
+        for (dc, endpoints) in endpoints_by_dc {
+            let endpoint_count = endpoints.len();
+            let dc_available_endpoints = endpoints
+                .iter()
+                .filter(|endpoint| live_writers_by_dc_endpoint.contains_key(&(dc, **endpoint)))
+                .count();
+            let base_required = self.required_writers_for_dc(endpoint_count);
+            let dc_required_writers =
+                self.required_writers_for_dc_with_floor_mode(endpoint_count, false);
+            let floor_min = if endpoint_count <= 1 {
+                (self
+                    .floor_runtime
+                    .me_adaptive_floor_min_writers_single_endpoint
+                    .load(Ordering::Relaxed) as usize)
+                    .max(1)
+                    .min(base_required.max(1))
+            } else {
+                (self
+                    .floor_runtime
+                    .me_adaptive_floor_min_writers_multi_endpoint
+                    .load(Ordering::Relaxed) as usize)
+                    .max(1)
+                    .min(base_required.max(1))
+            };
+            let extra_per_core = if endpoint_count <= 1 {
+                self.floor_runtime
+                    .me_adaptive_floor_max_extra_writers_single_per_core
+                    .load(Ordering::Relaxed) as usize
+            } else {
+                self.floor_runtime
+                    .me_adaptive_floor_max_extra_writers_multi_per_core
+                    .load(Ordering::Relaxed) as usize
+            };
+            let floor_max =
+                base_required.saturating_add(adaptive_cpu_cores.saturating_mul(extra_per_core));
+            let floor_capped =
+                matches!(floor_mode, MeFloorMode::Adaptive) && dc_required_writers < base_required;
+            let dc_alive_writers = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            let dc_fresh_alive_writers = fresh_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            let dc_load = activity
+                .active_sessions_by_target_dc
+                .get(&dc)
+                .copied()
+                .unwrap_or(0);
+            let dc_rtt_ms = dc_rtt_agg
+                .get(&dc)
+                .and_then(|(sum, count)| (*count > 0).then_some(*sum / (*count as f64)));
+
+            available_endpoints += dc_available_endpoints;
+            alive_writers += dc_alive_writers;
+            fresh_alive_writers += dc_fresh_alive_writers;
+
+            dcs.push(MeApiDcStatusSnapshot {
+                dc,
+                endpoint_writers: endpoints
+                    .iter()
+                    .map(|endpoint| MeApiDcEndpointWriterSnapshot {
+                        endpoint: *endpoint,
+                        active_writers: live_writers_by_dc_endpoint
+                            .get(&(dc, *endpoint))
+                            .copied()
+                            .unwrap_or(0),
+                    })
+                    .collect(),
+                endpoints: endpoints.into_iter().collect(),
+                available_endpoints: dc_available_endpoints,
+                available_pct: ratio_pct(dc_available_endpoints, endpoint_count),
+                required_writers: dc_required_writers,
+                floor_min,
+                floor_target: dc_required_writers,
+                floor_max,
+                floor_capped,
+                alive_writers: dc_alive_writers,
+                coverage_pct: ratio_pct(dc_alive_writers, dc_required_writers),
+                fresh_alive_writers: dc_fresh_alive_writers,
+                fresh_coverage_pct: ratio_pct(dc_fresh_alive_writers, dc_required_writers),
+                rtt_ms: dc_rtt_ms,
+                load: dc_load,
+            });
+        }
+
+        MeApiStatusSnapshot {
+            generated_at_epoch_secs: now_epoch_secs,
+            configured_dc_groups,
+            configured_endpoints,
+            available_endpoints,
+            available_pct: ratio_pct(available_endpoints, configured_endpoints),
+            required_writers,
+            alive_writers,
+            coverage_pct: ratio_pct(alive_writers, required_writers),
+            fresh_alive_writers,
+            fresh_coverage_pct: ratio_pct(fresh_alive_writers, required_writers),
+            writers: writer_rows,
+            dcs,
+        }
+    }
+}

src/transport/middle_proxy/pool_writer.rs

@@ -22,6 +22,9 @@ use super::pool::{MePool, MeWriter, WriterContour};
 use super::reader::reader_loop;
 use super::wire::build_proxy_req_payload;
 
+// Writer admission, teardown, and drain-state transitions.
+mod runtime;
+
 const ME_ACTIVE_PING_SECS: u64 = 25;
 const ME_ACTIVE_PING_JITTER_SECS: i64 = 5;
 const ME_IDLE_KEEPALIVE_MAX_SECS: u64 = 5;
@@ -327,465 +330,3 @@ async fn rpc_proxy_req_signal_loop(
         conn_lease.unregister().await;
     }
 }
-
-impl MePool {
-    pub(crate) async fn prune_closed_writers(self: &Arc<Self>) {
-        let closed_writer_ids: Vec<u64> = {
-            let ws = self.writers.read().await;
-            ws.iter()
-                .filter(|w| w.tx.is_closed())
-                .map(|w| w.id)
-                .collect()
-        };
-        if closed_writer_ids.is_empty() {
-            return;
-        }
-
-        for writer_id in closed_writer_ids {
-            let _ = self.remove_writer_and_close_clients(writer_id).await;
-        }
-    }
-
-    pub(crate) async fn connect_one_for_dc(
-        self: &Arc<Self>,
-        addr: SocketAddr,
-        writer_dc: i32,
-        rng: &SecureRandom,
-    ) -> Result<()> {
-        self.connect_one_with_generation_contour(
-            addr,
-            rng,
-            self.current_generation(),
-            WriterContour::Active,
-            writer_dc,
-        )
-        .await
-    }
-
-    pub(super) async fn connect_one_with_generation_contour(
-        self: &Arc<Self>,
-        addr: SocketAddr,
-        rng: &SecureRandom,
-        generation: u64,
-        contour: WriterContour,
-        writer_dc: i32,
-    ) -> Result<()> {
-        self.connect_one_with_generation_contour_for_dc(addr, rng, generation, contour, writer_dc)
-            .await
-    }
-
-    pub(super) async fn connect_one_with_generation_contour_for_dc(
-        self: &Arc<Self>,
-        addr: SocketAddr,
-        rng: &SecureRandom,
-        generation: u64,
-        contour: WriterContour,
-        writer_dc: i32,
-    ) -> Result<()> {
-        self.connect_one_with_generation_contour_for_dc_with_cap_policy(
-            addr, rng, generation, contour, writer_dc, false,
-        )
-        .await
-    }
-
-    pub(super) async fn connect_one_with_generation_contour_for_dc_with_cap_policy(
-        self: &Arc<Self>,
-        addr: SocketAddr,
-        rng: &SecureRandom,
-        generation: u64,
-        contour: WriterContour,
-        writer_dc: i32,
-        allow_coverage_override: bool,
-    ) -> Result<()> {
-        let Some(_writer_open_reservation) = self
-            .reserve_writer_open(contour, allow_coverage_override, writer_dc)
-            .await
-        else {
-            return Err(ProxyError::Proxy(format!(
-                "ME {contour:?} writer cap reached"
-            )));
-        };
-
-        let secret_len = self.proxy_secret.read().await.secret.len();
-        if secret_len < 32 {
-            return Err(ProxyError::Proxy(
-                "proxy-secret too short for ME auth".into(),
-            ));
-        }
-
-        let dc_idx = i16::try_from(writer_dc).ok();
-        let (stream, _connect_ms, upstream_egress) = self.connect_tcp(addr, dc_idx).await?;
-        let hs = self
-            .handshake_only(stream, addr, upstream_egress, rng)
-            .await?;
-        let Some(task_registration) = self.lifecycle.try_register() else {
-            return Err(ProxyError::Proxy("ME pool lifecycle closed".into()));
-        };
-
-        let writer_id = self.next_writer_id.fetch_add(1, Ordering::Relaxed);
-        let contour = Arc::new(AtomicU8::new(contour.as_u8()));
-        let cancel = CancellationToken::new();
-        let degraded = Arc::new(AtomicBool::new(false));
-        let rtt_ema_ms_x10 = Arc::new(AtomicU32::new(0));
-        let draining = Arc::new(AtomicBool::new(false));
-        let draining_started_at_epoch_secs = Arc::new(AtomicU64::new(0));
-        let drain_deadline_epoch_secs = Arc::new(AtomicU64::new(0));
-        let allow_drain_fallback = Arc::new(AtomicBool::new(false));
-        let byte_budget = self.new_writer_byte_budget();
-        let (tx, rx) =
-            mpsc::channel::<WriterCommand>(self.writer_lifecycle.writer_cmd_channel_capacity);
-        let rpc_writer = RpcWriter {
-            writer: hs.wr,
-            key: hs.write_key,
-            iv: hs.write_iv,
-            seq_no: 0,
-            crc_mode: hs.crc_mode,
-            frame_buf: Vec::new(),
-        };
-        let writer = MeWriter {
-            id: writer_id,
-            addr,
-            source_ip: hs.source_ip,
-            writer_dc,
-            generation,
-            contour: contour.clone(),
-            created_at: Instant::now(),
-            tx: tx.clone(),
-            byte_budget: byte_budget.clone(),
-            cancel: cancel.clone(),
-            degraded: degraded.clone(),
-            rtt_ema_ms_x10: rtt_ema_ms_x10.clone(),
-            draining: draining.clone(),
-            draining_started_at_epoch_secs: draining_started_at_epoch_secs.clone(),
-            drain_deadline_epoch_secs: drain_deadline_epoch_secs.clone(),
-            allow_drain_fallback: allow_drain_fallback.clone(),
-        };
-        self.writers
-            .update(|writers| writers.push(writer.clone()))
-            .await;
-        self.registry
-            .register_writer(writer_id, tx.clone(), byte_budget)
-            .await;
-        self.registry.mark_writer_idle(writer_id).await;
-        self.conn_count.fetch_add(1, Ordering::Relaxed);
-        self.notify_writer_epoch();
-
-        let reg = self.registry.clone();
-        let writers_arc = self.writers_arc();
-        let ping_tracker = Arc::new(tokio::sync::Mutex::new(HashMap::<i64, Instant>::new()));
-        let ping_tracker_reader = ping_tracker.clone();
-        let ping_tracker_ping = ping_tracker.clone();
-        let rtt_stats = self.rtt_stats.clone();
-        let stats_reader = self.stats.clone();
-        let stats_reader_close = self.stats.clone();
-        let stats_ping = self.stats.clone();
-        let stats_signal = self.stats.clone();
-        let pool_lifecycle = Arc::downgrade(self);
-        let pool_ping = Arc::downgrade(self);
-        let pool_signal = Arc::downgrade(self);
-        let tx_reader = tx.clone();
-        let tx_ping = tx.clone();
-        let tx_signal = tx.clone();
-        let keepalive_enabled = self.writer_lifecycle.me_keepalive_enabled;
-        let keepalive_interval = self.writer_lifecycle.me_keepalive_interval;
-        let keepalive_jitter = self.writer_lifecycle.me_keepalive_jitter;
-        let keepalive_jitter_signal = self.writer_lifecycle.me_keepalive_jitter;
-        let rpc_proxy_req_every_secs = self
-            .writer_lifecycle
-            .rpc_proxy_req_every_secs
-            .load(Ordering::Relaxed);
-        let cancel_reader = cancel.clone();
-        let cancel_writer = cancel.clone();
-        let cancel_ping = cancel.clone();
-        let cancel_signal = cancel.clone();
-        let cancel_select = cancel.clone();
-        let cancel_cleanup = cancel.clone();
-        let route_backpressure_enabled =
-            self.transport_policy.me_route_backpressure_enabled.clone();
-        let route_fairshare_enabled = self.transport_policy.me_route_fairshare_enabled.clone();
-        let reader_route_data_wait_ms = self.transport_policy.me_reader_route_data_wait_ms.clone();
-
-        self.lifecycle.spawn_registered_writer(task_registration, async move {
-            // Reader MUST be the first branch in biased select! to avoid read starvation.
-            let exit = tokio::select! {
-                biased;
-
-                reader_res = reader_loop(
-                    hs.rd,
-                    hs.read_key,
-                    hs.read_iv,
-                    hs.crc_mode,
-                    reg.clone(),
-                    BytesMut::new(),
-                    BytesMut::new(),
-                    tx_reader,
-                    ping_tracker_reader,
-                    rtt_stats,
-                    stats_reader,
-                    writer_id,
-                    degraded,
-                    rtt_ema_ms_x10,
-                    route_backpressure_enabled,
-                    route_fairshare_enabled,
-                    reader_route_data_wait_ms,
-                    cancel_reader,
-                ) => WriterLifecycleExit::Reader(reader_res),
-                writer_res = writer_command_loop(rx, rpc_writer, cancel_writer) => {
-                    WriterLifecycleExit::Writer(writer_res)
-                }
-                _ = ping_loop(
-                    pool_ping,
-                    writer_id,
-                    tx_ping,
-                    ping_tracker_ping,
-                    stats_ping,
-                    keepalive_enabled,
-                    keepalive_interval,
-                    keepalive_jitter,
-                    cancel_ping,
-                ) => WriterLifecycleExit::Ping,
-                _ = rpc_proxy_req_signal_loop(
-                    pool_signal,
-                    writer_id,
-                    tx_signal,
-                    stats_signal,
-                    cancel_signal,
-                    keepalive_jitter_signal,
-                    rpc_proxy_req_every_secs,
-                ) => WriterLifecycleExit::Signal,
-                _ = cancel_select.cancelled() => WriterLifecycleExit::Cancelled,
-            };
-
-            match exit {
-                WriterLifecycleExit::Reader(res) => {
-                    let idle_close_by_peer = if let Err(e) = res.as_ref() {
-                        is_me_peer_closed_error(e) && reg.is_writer_empty(writer_id).await
-                    } else {
-                        false
-                    };
-                    if idle_close_by_peer {
-                        stats_reader_close.increment_me_idle_close_by_peer_total();
-                        info!(writer_id, "ME socket closed by peer on idle writer");
-                    }
-                    if let Err(e) = res
-                        && !idle_close_by_peer
-                    {
-                        warn!(error = %e, "ME reader ended");
-                    }
-                }
-                WriterLifecycleExit::Writer(res) => {
-                    if let Err(e) = res {
-                        warn!(error = %e, "ME writer command loop ended");
-                    }
-                }
-                WriterLifecycleExit::Ping => {
-                    debug!(writer_id, "ME ping loop finished");
-                }
-                WriterLifecycleExit::Signal => {
-                    debug!(writer_id, "ME rpc_proxy_req signal loop finished");
-                }
-                WriterLifecycleExit::Cancelled => {}
-            }
-
-            if let Some(pool) = pool_lifecycle.upgrade() {
-                pool.remove_writer_and_close_clients(writer_id).await;
-            } else {
-                // Fallback for shutdown races: make lifecycle exit observable by prune.
-                cancel_cleanup.cancel();
-            }
-
-            let remaining = writers_arc.read().await.len();
-            debug!(writer_id, remaining, "ME writer lifecycle task finished");
-        });
-
-        Ok(())
-    }
-
-    pub(crate) async fn remove_writer_and_close_clients(self: &Arc<Self>, writer_id: u64) {
-        // Full client cleanup now happens inside `registry.writer_lost` to keep
-        // writer reap/remove paths strictly non-blocking per connection.
-        let _ = self
-            .remove_writer_with_mode(writer_id, WriterTeardownMode::Any)
-            .await;
-    }
-
-    pub(super) async fn remove_draining_writer_hard_detach(
-        self: &Arc<Self>,
-        writer_id: u64,
-    ) -> bool {
-        self.remove_writer_with_mode(writer_id, WriterTeardownMode::DrainingOnly)
-            .await
-    }
-
-    #[allow(dead_code)]
-    async fn remove_writer_only(self: &Arc<Self>, writer_id: u64) -> bool {
-        self.remove_writer_with_mode(writer_id, WriterTeardownMode::Any)
-            .await
-    }
-
-    // Authoritative teardown primitive shared by normal cleanup and watchdog path.
-    // Lock-order invariant:
-    // 1) mutate `writers` under pool write lock,
-    // 2) release pool lock,
-    // 3) run registry/metrics/refill side effects.
-    // `registry.writer_lost` must never run while `writers` lock is held.
-    async fn remove_writer_with_mode(
-        self: &Arc<Self>,
-        writer_id: u64,
-        mode: WriterTeardownMode,
-    ) -> bool {
-        let mut close_tx: Option<mpsc::Sender<WriterCommand>> = None;
-        let mut removed_addr: Option<SocketAddr> = None;
-        let mut removed_dc: Option<i32> = None;
-        let mut removed_uptime: Option<Duration> = None;
-        let mut trigger_refill = false;
-        let mut removed = false;
-        {
-            let mut ws = self.writers.write().await;
-            if let Some(pos) = ws.iter().position(|w| w.id == writer_id) {
-                if matches!(mode, WriterTeardownMode::DrainingOnly)
-                    && !ws[pos].draining.load(Ordering::Relaxed)
-                {
-                    return false;
-                }
-                let w = ws.remove(pos);
-                let was_draining = w.draining.load(Ordering::Relaxed);
-                if was_draining {
-                    self.stats.decrement_pool_drain_active();
-                    self.decrement_draining_active_runtime();
-                }
-                self.stats.increment_me_writer_removed_total();
-                w.cancel.cancel();
-                removed_addr = Some(w.addr);
-                removed_dc = Some(w.writer_dc);
-                removed_uptime = Some(w.created_at.elapsed());
-                trigger_refill = !was_draining;
-                if trigger_refill {
-                    self.stats.increment_me_writer_removed_unexpected_total();
-                }
-                close_tx = Some(w.tx.clone());
-                self.conn_count.fetch_sub(1, Ordering::Relaxed);
-                removed = true;
-            }
-        }
-        // State invariant:
-        // - writer is removed from `self.writers` (pool visibility),
-        // - writer is removed from registry routing/binding maps via `writer_lost`.
-        // The close command below is only a best-effort accelerator for task shutdown.
-        // Cleanup progress must never depend on command-channel availability.
-        let _ = self.registry.writer_lost(writer_id).await;
-        self.rtt_stats.lock().await.remove(&writer_id);
-        if let Some(tx) = close_tx {
-            // Keep teardown critical path non-blocking: close is best-effort only.
-            let _ = tx.try_send(WriterCommand::Close);
-        }
-        if let Some(addr) = removed_addr {
-            if let Some(uptime) = removed_uptime {
-                // Quarantine contract: only unexpected removals are considered endpoint flap.
-                if trigger_refill {
-                    self.stats
-                        .increment_me_endpoint_quarantine_unexpected_total();
-                    self.maybe_quarantine_flapping_endpoint(addr, uptime, "unexpected")
-                        .await;
-                } else {
-                    self.stats
-                        .increment_me_endpoint_quarantine_draining_suppressed_total();
-                    debug!(
-                        %addr,
-                        uptime_ms = uptime.as_millis(),
-                        "Skipping endpoint quarantine for draining writer removal"
-                    );
-                }
-            }
-            if trigger_refill && let Some(writer_dc) = removed_dc {
-                self.trigger_immediate_refill_for_dc(addr, writer_dc);
-            }
-        }
-        if removed {
-            self.notify_writer_epoch();
-        }
-        removed
-    }
-
-    pub(crate) async fn mark_writer_draining_with_timeout(
-        self: &Arc<Self>,
-        writer_id: u64,
-        timeout: Option<Duration>,
-        allow_drain_fallback: bool,
-    ) {
-        let timeout = timeout.filter(|d| !d.is_zero());
-        let found = {
-            let mut ws = self.writers.write().await;
-            if let Some(w) = ws.iter_mut().find(|w| w.id == writer_id) {
-                let already_draining = w.draining.swap(true, Ordering::Relaxed);
-                w.allow_drain_fallback
-                    .store(allow_drain_fallback, Ordering::Relaxed);
-                let now_epoch_secs = Self::now_epoch_secs();
-                w.draining_started_at_epoch_secs
-                    .store(now_epoch_secs, Ordering::Relaxed);
-                let drain_deadline_epoch_secs = timeout
-                    .map(|duration| now_epoch_secs.saturating_add(duration.as_secs()))
-                    .unwrap_or(0);
-                w.drain_deadline_epoch_secs
-                    .store(drain_deadline_epoch_secs, Ordering::Relaxed);
-                if !already_draining {
-                    self.stats.increment_pool_drain_active();
-                    self.increment_draining_active_runtime();
-                }
-                w.contour
-                    .store(WriterContour::Draining.as_u8(), Ordering::Relaxed);
-                w.draining.store(true, Ordering::Relaxed);
-                true
-            } else {
-                false
-            }
-        };
-
-        if !found {
-            return;
-        }
-
-        let timeout_secs = timeout.map(|d| d.as_secs()).unwrap_or(0);
-        debug!(
-            writer_id,
-            timeout_secs, allow_drain_fallback, "ME writer marked draining"
-        );
-    }
-
-    pub(crate) async fn mark_writer_draining(self: &Arc<Self>, writer_id: u64) {
-        self.mark_writer_draining_with_timeout(writer_id, Some(Duration::from_secs(300)), false)
-            .await;
-    }
-
-    pub(super) fn writer_accepts_new_binding(&self, writer: &MeWriter) -> bool {
-        if !writer.draining.load(Ordering::Relaxed) {
-            return true;
-        }
-        if !writer.allow_drain_fallback.load(Ordering::Relaxed) {
-            return false;
-        }
-
-        match self.bind_stale_mode() {
-            MeBindStaleMode::Never => false,
-            MeBindStaleMode::Always => true,
-            MeBindStaleMode::Ttl => {
-                let ttl_secs = self
-                    .binding_policy
-                    .me_bind_stale_ttl_secs
-                    .load(Ordering::Relaxed);
-                if ttl_secs == 0 {
-                    return true;
-                }
-
-                let started = writer
-                    .draining_started_at_epoch_secs
-                    .load(Ordering::Relaxed);
-                if started == 0 {
-                    return false;
-                }
-
-                Self::now_epoch_secs().saturating_sub(started) <= ttl_secs
-            }
-        }
-    }
-}

src/transport/middle_proxy/pool_writer/runtime.rs

@@ -0,0 +1,467 @@
+use super::*;
+
+impl MePool {
+    pub(crate) async fn prune_closed_writers(self: &Arc<Self>) {
+        let closed_writer_ids: Vec<u64> = {
+            let ws = self.writers.read().await;
+            ws.iter()
+                .filter(|w| w.tx.is_closed())
+                .map(|w| w.id)
+                .collect()
+        };
+        if closed_writer_ids.is_empty() {
+            return;
+        }
+
+        for writer_id in closed_writer_ids {
+            let _ = self.remove_writer_and_close_clients(writer_id).await;
+        }
+    }
+
+    pub(crate) async fn connect_one_for_dc(
+        self: &Arc<Self>,
+        addr: SocketAddr,
+        writer_dc: i32,
+        rng: &SecureRandom,
+    ) -> Result<()> {
+        self.connect_one_with_generation_contour(
+            addr,
+            rng,
+            self.current_generation(),
+            WriterContour::Active,
+            writer_dc,
+        )
+        .await
+    }
+
+    pub(in crate::transport::middle_proxy) async fn connect_one_with_generation_contour(
+        self: &Arc<Self>,
+        addr: SocketAddr,
+        rng: &SecureRandom,
+        generation: u64,
+        contour: WriterContour,
+        writer_dc: i32,
+    ) -> Result<()> {
+        self.connect_one_with_generation_contour_for_dc(addr, rng, generation, contour, writer_dc)
+            .await
+    }
+
+    pub(in crate::transport::middle_proxy) async fn connect_one_with_generation_contour_for_dc(
+        self: &Arc<Self>,
+        addr: SocketAddr,
+        rng: &SecureRandom,
+        generation: u64,
+        contour: WriterContour,
+        writer_dc: i32,
+    ) -> Result<()> {
+        self.connect_one_with_generation_contour_for_dc_with_cap_policy(
+            addr, rng, generation, contour, writer_dc, false,
+        )
+        .await
+    }
+
+    pub(in crate::transport::middle_proxy) async fn connect_one_with_generation_contour_for_dc_with_cap_policy(
+        self: &Arc<Self>,
+        addr: SocketAddr,
+        rng: &SecureRandom,
+        generation: u64,
+        contour: WriterContour,
+        writer_dc: i32,
+        allow_coverage_override: bool,
+    ) -> Result<()> {
+        let Some(_writer_open_reservation) = self
+            .reserve_writer_open(contour, allow_coverage_override, writer_dc)
+            .await
+        else {
+            return Err(ProxyError::Proxy(format!(
+                "ME {contour:?} writer cap reached"
+            )));
+        };
+
+        let secret_len = self.proxy_secret.read().await.secret.len();
+        if secret_len < 32 {
+            return Err(ProxyError::Proxy(
+                "proxy-secret too short for ME auth".into(),
+            ));
+        }
+
+        let dc_idx = i16::try_from(writer_dc).ok();
+        let (stream, _connect_ms, upstream_egress) = self.connect_tcp(addr, dc_idx).await?;
+        let hs = self
+            .handshake_only(stream, addr, upstream_egress, rng)
+            .await?;
+        let Some(task_registration) = self.lifecycle.try_register() else {
+            return Err(ProxyError::Proxy("ME pool lifecycle closed".into()));
+        };
+
+        let writer_id = self.next_writer_id.fetch_add(1, Ordering::Relaxed);
+        let contour = Arc::new(AtomicU8::new(contour.as_u8()));
+        let cancel = CancellationToken::new();
+        let degraded = Arc::new(AtomicBool::new(false));
+        let rtt_ema_ms_x10 = Arc::new(AtomicU32::new(0));
+        let draining = Arc::new(AtomicBool::new(false));
+        let draining_started_at_epoch_secs = Arc::new(AtomicU64::new(0));
+        let drain_deadline_epoch_secs = Arc::new(AtomicU64::new(0));
+        let allow_drain_fallback = Arc::new(AtomicBool::new(false));
+        let byte_budget = self.new_writer_byte_budget();
+        let (tx, rx) =
+            mpsc::channel::<WriterCommand>(self.writer_lifecycle.writer_cmd_channel_capacity);
+        let rpc_writer = RpcWriter {
+            writer: hs.wr,
+            key: hs.write_key,
+            iv: hs.write_iv,
+            seq_no: 0,
+            crc_mode: hs.crc_mode,
+            frame_buf: Vec::new(),
+        };
+        let writer = MeWriter {
+            id: writer_id,
+            addr,
+            source_ip: hs.source_ip,
+            writer_dc,
+            generation,
+            contour: contour.clone(),
+            created_at: Instant::now(),
+            tx: tx.clone(),
+            byte_budget: byte_budget.clone(),
+            cancel: cancel.clone(),
+            degraded: degraded.clone(),
+            rtt_ema_ms_x10: rtt_ema_ms_x10.clone(),
+            draining: draining.clone(),
+            draining_started_at_epoch_secs: draining_started_at_epoch_secs.clone(),
+            drain_deadline_epoch_secs: drain_deadline_epoch_secs.clone(),
+            allow_drain_fallback: allow_drain_fallback.clone(),
+        };
+        self.writers
+            .update(|writers| writers.push(writer.clone()))
+            .await;
+        self.registry
+            .register_writer(writer_id, tx.clone(), byte_budget)
+            .await;
+        self.registry.mark_writer_idle(writer_id).await;
+        self.conn_count.fetch_add(1, Ordering::Relaxed);
+        self.notify_writer_epoch();
+
+        let reg = self.registry.clone();
+        let writers_arc = self.writers_arc();
+        let ping_tracker = Arc::new(tokio::sync::Mutex::new(HashMap::<i64, Instant>::new()));
+        let ping_tracker_reader = ping_tracker.clone();
+        let ping_tracker_ping = ping_tracker.clone();
+        let rtt_stats = self.rtt_stats.clone();
+        let stats_reader = self.stats.clone();
+        let stats_reader_close = self.stats.clone();
+        let stats_ping = self.stats.clone();
+        let stats_signal = self.stats.clone();
+        let pool_lifecycle = Arc::downgrade(self);
+        let pool_ping = Arc::downgrade(self);
+        let pool_signal = Arc::downgrade(self);
+        let tx_reader = tx.clone();
+        let tx_ping = tx.clone();
+        let tx_signal = tx.clone();
+        let keepalive_enabled = self.writer_lifecycle.me_keepalive_enabled;
+        let keepalive_interval = self.writer_lifecycle.me_keepalive_interval;
+        let keepalive_jitter = self.writer_lifecycle.me_keepalive_jitter;
+        let keepalive_jitter_signal = self.writer_lifecycle.me_keepalive_jitter;
+        let rpc_proxy_req_every_secs = self
+            .writer_lifecycle
+            .rpc_proxy_req_every_secs
+            .load(Ordering::Relaxed);
+        let cancel_reader = cancel.clone();
+        let cancel_writer = cancel.clone();
+        let cancel_ping = cancel.clone();
+        let cancel_signal = cancel.clone();
+        let cancel_select = cancel.clone();
+        let cancel_cleanup = cancel.clone();
+        let route_backpressure_enabled =
+            self.transport_policy.me_route_backpressure_enabled.clone();
+        let route_fairshare_enabled = self.transport_policy.me_route_fairshare_enabled.clone();
+        let reader_route_data_wait_ms = self.transport_policy.me_reader_route_data_wait_ms.clone();
+
+        self.lifecycle
+            .spawn_registered_writer(task_registration, async move {
+                // Reader MUST be the first branch in biased select! to avoid read starvation.
+                let exit = tokio::select! {
+                    biased;
+
+                    reader_res = reader_loop(
+                        hs.rd,
+                        hs.read_key,
+                        hs.read_iv,
+                        hs.crc_mode,
+                        reg.clone(),
+                        BytesMut::new(),
+                        BytesMut::new(),
+                        tx_reader,
+                        ping_tracker_reader,
+                        rtt_stats,
+                        stats_reader,
+                        writer_id,
+                        degraded,
+                        rtt_ema_ms_x10,
+                        route_backpressure_enabled,
+                        route_fairshare_enabled,
+                        reader_route_data_wait_ms,
+                        cancel_reader,
+                    ) => WriterLifecycleExit::Reader(reader_res),
+                    writer_res = writer_command_loop(rx, rpc_writer, cancel_writer) => {
+                        WriterLifecycleExit::Writer(writer_res)
+                    }
+                    _ = ping_loop(
+                        pool_ping,
+                        writer_id,
+                        tx_ping,
+                        ping_tracker_ping,
+                        stats_ping,
+                        keepalive_enabled,
+                        keepalive_interval,
+                        keepalive_jitter,
+                        cancel_ping,
+                    ) => WriterLifecycleExit::Ping,
+                    _ = rpc_proxy_req_signal_loop(
+                        pool_signal,
+                        writer_id,
+                        tx_signal,
+                        stats_signal,
+                        cancel_signal,
+                        keepalive_jitter_signal,
+                        rpc_proxy_req_every_secs,
+                    ) => WriterLifecycleExit::Signal,
+                    _ = cancel_select.cancelled() => WriterLifecycleExit::Cancelled,
+                };
+
+                match exit {
+                    WriterLifecycleExit::Reader(res) => {
+                        let idle_close_by_peer = if let Err(e) = res.as_ref() {
+                            is_me_peer_closed_error(e) && reg.is_writer_empty(writer_id).await
+                        } else {
+                            false
+                        };
+                        if idle_close_by_peer {
+                            stats_reader_close.increment_me_idle_close_by_peer_total();
+                            info!(writer_id, "ME socket closed by peer on idle writer");
+                        }
+                        if let Err(e) = res
+                            && !idle_close_by_peer
+                        {
+                            warn!(error = %e, "ME reader ended");
+                        }
+                    }
+                    WriterLifecycleExit::Writer(res) => {
+                        if let Err(e) = res {
+                            warn!(error = %e, "ME writer command loop ended");
+                        }
+                    }
+                    WriterLifecycleExit::Ping => {
+                        debug!(writer_id, "ME ping loop finished");
+                    }
+                    WriterLifecycleExit::Signal => {
+                        debug!(writer_id, "ME rpc_proxy_req signal loop finished");
+                    }
+                    WriterLifecycleExit::Cancelled => {}
+                }
+
+                if let Some(pool) = pool_lifecycle.upgrade() {
+                    pool.remove_writer_and_close_clients(writer_id).await;
+                } else {
+                    // Fallback for shutdown races: make lifecycle exit observable by prune.
+                    cancel_cleanup.cancel();
+                }
+
+                let remaining = writers_arc.read().await.len();
+                debug!(writer_id, remaining, "ME writer lifecycle task finished");
+            });
+
+        Ok(())
+    }
+
+    pub(crate) async fn remove_writer_and_close_clients(self: &Arc<Self>, writer_id: u64) {
+        // Full client cleanup now happens inside `registry.writer_lost` to keep
+        // writer reap/remove paths strictly non-blocking per connection.
+        let _ = self
+            .remove_writer_with_mode(writer_id, WriterTeardownMode::Any)
+            .await;
+    }
+
+    pub(in crate::transport::middle_proxy) async fn remove_draining_writer_hard_detach(
+        self: &Arc<Self>,
+        writer_id: u64,
+    ) -> bool {
+        self.remove_writer_with_mode(writer_id, WriterTeardownMode::DrainingOnly)
+            .await
+    }
+
+    #[allow(dead_code)]
+    async fn remove_writer_only(self: &Arc<Self>, writer_id: u64) -> bool {
+        self.remove_writer_with_mode(writer_id, WriterTeardownMode::Any)
+            .await
+    }
+
+    // Authoritative teardown primitive shared by normal cleanup and watchdog path.
+    // Lock-order invariant:
+    // 1) mutate `writers` under pool write lock,
+    // 2) release pool lock,
+    // 3) run registry/metrics/refill side effects.
+    // `registry.writer_lost` must never run while `writers` lock is held.
+    async fn remove_writer_with_mode(
+        self: &Arc<Self>,
+        writer_id: u64,
+        mode: WriterTeardownMode,
+    ) -> bool {
+        let mut close_tx: Option<mpsc::Sender<WriterCommand>> = None;
+        let mut removed_addr: Option<SocketAddr> = None;
+        let mut removed_dc: Option<i32> = None;
+        let mut removed_uptime: Option<Duration> = None;
+        let mut trigger_refill = false;
+        let mut removed = false;
+        {
+            let mut ws = self.writers.write().await;
+            if let Some(pos) = ws.iter().position(|w| w.id == writer_id) {
+                if matches!(mode, WriterTeardownMode::DrainingOnly)
+                    && !ws[pos].draining.load(Ordering::Relaxed)
+                {
+                    return false;
+                }
+                let w = ws.remove(pos);
+                let was_draining = w.draining.load(Ordering::Relaxed);
+                if was_draining {
+                    self.stats.decrement_pool_drain_active();
+                    self.decrement_draining_active_runtime();
+                }
+                self.stats.increment_me_writer_removed_total();
+                w.cancel.cancel();
+                removed_addr = Some(w.addr);
+                removed_dc = Some(w.writer_dc);
+                removed_uptime = Some(w.created_at.elapsed());
+                trigger_refill = !was_draining;
+                if trigger_refill {
+                    self.stats.increment_me_writer_removed_unexpected_total();
+                }
+                close_tx = Some(w.tx.clone());
+                self.conn_count.fetch_sub(1, Ordering::Relaxed);
+                removed = true;
+            }
+        }
+        // State invariant:
+        // - writer is removed from `self.writers` (pool visibility),
+        // - writer is removed from registry routing/binding maps via `writer_lost`.
+        // The close command below is only a best-effort accelerator for task shutdown.
+        // Cleanup progress must never depend on command-channel availability.
+        let _ = self.registry.writer_lost(writer_id).await;
+        self.rtt_stats.lock().await.remove(&writer_id);
+        if let Some(tx) = close_tx {
+            // Keep teardown critical path non-blocking: close is best-effort only.
+            let _ = tx.try_send(WriterCommand::Close);
+        }
+        if let Some(addr) = removed_addr {
+            if let Some(uptime) = removed_uptime {
+                // Quarantine contract: only unexpected removals are considered endpoint flap.
+                if trigger_refill {
+                    self.stats
+                        .increment_me_endpoint_quarantine_unexpected_total();
+                    self.maybe_quarantine_flapping_endpoint(addr, uptime, "unexpected")
+                        .await;
+                } else {
+                    self.stats
+                        .increment_me_endpoint_quarantine_draining_suppressed_total();
+                    debug!(
+                        %addr,
+                        uptime_ms = uptime.as_millis(),
+                        "Skipping endpoint quarantine for draining writer removal"
+                    );
+                }
+            }
+            if trigger_refill && let Some(writer_dc) = removed_dc {
+                self.trigger_immediate_refill_for_dc(addr, writer_dc);
+            }
+        }
+        if removed {
+            self.notify_writer_epoch();
+        }
+        removed
+    }
+
+    pub(crate) async fn mark_writer_draining_with_timeout(
+        self: &Arc<Self>,
+        writer_id: u64,
+        timeout: Option<Duration>,
+        allow_drain_fallback: bool,
+    ) {
+        let timeout = timeout.filter(|d| !d.is_zero());
+        let found = {
+            let mut ws = self.writers.write().await;
+            if let Some(w) = ws.iter_mut().find(|w| w.id == writer_id) {
+                let already_draining = w.draining.swap(true, Ordering::Relaxed);
+                w.allow_drain_fallback
+                    .store(allow_drain_fallback, Ordering::Relaxed);
+                let now_epoch_secs = Self::now_epoch_secs();
+                w.draining_started_at_epoch_secs
+                    .store(now_epoch_secs, Ordering::Relaxed);
+                let drain_deadline_epoch_secs = timeout
+                    .map(|duration| now_epoch_secs.saturating_add(duration.as_secs()))
+                    .unwrap_or(0);
+                w.drain_deadline_epoch_secs
+                    .store(drain_deadline_epoch_secs, Ordering::Relaxed);
+                if !already_draining {
+                    self.stats.increment_pool_drain_active();
+                    self.increment_draining_active_runtime();
+                }
+                w.contour
+                    .store(WriterContour::Draining.as_u8(), Ordering::Relaxed);
+                w.draining.store(true, Ordering::Relaxed);
+                true
+            } else {
+                false
+            }
+        };
+
+        if !found {
+            return;
+        }
+
+        let timeout_secs = timeout.map(|d| d.as_secs()).unwrap_or(0);
+        debug!(
+            writer_id,
+            timeout_secs, allow_drain_fallback, "ME writer marked draining"
+        );
+    }
+
+    pub(crate) async fn mark_writer_draining(self: &Arc<Self>, writer_id: u64) {
+        self.mark_writer_draining_with_timeout(writer_id, Some(Duration::from_secs(300)), false)
+            .await;
+    }
+
+    pub(in crate::transport::middle_proxy) fn writer_accepts_new_binding(
+        &self,
+        writer: &MeWriter,
+    ) -> bool {
+        if !writer.draining.load(Ordering::Relaxed) {
+            return true;
+        }
+        if !writer.allow_drain_fallback.load(Ordering::Relaxed) {
+            return false;
+        }
+
+        match self.bind_stale_mode() {
+            MeBindStaleMode::Never => false,
+            MeBindStaleMode::Always => true,
+            MeBindStaleMode::Ttl => {
+                let ttl_secs = self
+                    .binding_policy
+                    .me_bind_stale_ttl_secs
+                    .load(Ordering::Relaxed);
+                if ttl_secs == 0 {
+                    return true;
+                }
+
+                let started = writer
+                    .draining_started_at_epoch_secs
+                    .load(Ordering::Relaxed);
+                if started == 0 {
+                    return false;
+                }
+
+                Self::now_epoch_secs().saturating_sub(started) <= ttl_secs
+            }
+        }
+    }
+}

src/transport/middle_proxy/tests/health_adversarial_tests.rs

@@ -234,383 +234,9 @@ async fn set_writer_runtime_state(
     }
 }
 
-#[tokio::test]
-async fn reap_draining_writers_clears_warn_state_when_pool_empty() {
-    let (pool, _rng) = make_pool(128, 1, 1).await;
-    let mut warn_next_allowed = HashMap::new();
-    warn_next_allowed.insert(11, Instant::now() + Duration::from_secs(5));
-    warn_next_allowed.insert(22, Instant::now() + Duration::from_secs(5));
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(warn_next_allowed.is_empty());
-}
-
-#[tokio::test]
-async fn reap_draining_writers_respects_threshold_across_multiple_overflow_cycles() {
-    let threshold = 3u64;
-    let (pool, _rng) = make_pool(threshold, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=60u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    }
-
-    let mut warn_next_allowed = HashMap::new();
-    for _ in 0..64 {
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        if writer_count(&pool).await <= threshold as usize {
-            break;
-        }
-    }
-
-    assert_eq!(writer_count(&pool).await, threshold as usize);
-    assert_eq!(sorted_writer_ids(&pool).await, vec![1, 2, 3]);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_handles_large_empty_writer_population() {
-    let (pool, _rng) = make_pool(128, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let total = health_drain_close_budget()
-        .saturating_mul(3)
-        .saturating_add(27);
-
-    for writer_id in 1..=total as u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(120), 0, 0).await;
-    }
-
-    let mut warn_next_allowed = HashMap::new();
-    for _ in 0..24 {
-        if writer_count(&pool).await == 0 {
-            break;
-        }
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    }
-
-    assert_eq!(writer_count(&pool).await, 0);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_processes_mass_deadline_expiry_without_unbounded_growth() {
-    let (pool, _rng) = make_pool(128, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let total = health_drain_close_budget()
-        .saturating_mul(4)
-        .saturating_add(31);
-
-    for writer_id in 1..=total as u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(180),
-            1,
-            now_epoch_secs.saturating_sub(1),
-        )
-        .await;
-    }
-
-    let mut warn_next_allowed = HashMap::new();
-    for _ in 0..40 {
-        if writer_count(&pool).await == 0 {
-            break;
-        }
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    }
-
-    assert_eq!(writer_count(&pool).await, 0);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_maintains_warn_state_subset_property_under_bulk_churn() {
-    let (pool, _rng) = make_pool(128, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let mut warn_next_allowed = HashMap::new();
-
-    for wave in 0..40u64 {
-        for offset in 0..8u64 {
-            insert_draining_writer(
-                &pool,
-                wave * 100 + offset,
-                now_epoch_secs.saturating_sub(400 + offset),
-                1,
-                0,
-            )
-            .await;
-        }
-
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        assert!(warn_next_allowed.len() <= writer_count(&pool).await);
-
-        let ids = sorted_writer_ids(&pool).await;
-        for writer_id in ids.into_iter().take(3) {
-            let _ = pool.remove_writer_and_close_clients(writer_id).await;
-        }
-
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        assert!(warn_next_allowed.len() <= writer_count(&pool).await);
-    }
-}
-
-#[tokio::test]
-async fn reap_draining_writers_budgeted_cleanup_never_increases_pool_size() {
-    let (pool, _rng) = make_pool(5, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=200u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(240).saturating_add(writer_id),
-            1,
-            0,
-        )
-        .await;
-    }
-
-    let mut warn_next_allowed = HashMap::new();
-    let mut previous = writer_count(&pool).await;
-    for _ in 0..32 {
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        let current = writer_count(&pool).await;
-        assert!(current <= previous);
-        previous = current;
-    }
-}
-
-#[tokio::test]
-async fn me_health_monitor_converges_to_threshold_under_live_injection_churn() {
-    let threshold = 7u64;
-    let (pool, rng) = make_pool(threshold, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=40u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
-            1,
-            0,
-        )
-        .await;
-    }
-
-    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
-
-    for wave in 0..8u64 {
-        for offset in 0..10u64 {
-            insert_draining_writer(
-                &pool,
-                1000 + wave * 100 + offset,
-                now_epoch_secs.saturating_sub(120).saturating_add(offset),
-                1,
-                0,
-            )
-            .await;
-        }
-        tokio::time::sleep(Duration::from_millis(5)).await;
-    }
-
-    tokio::time::sleep(Duration::from_millis(120)).await;
-    monitor.abort();
-    let _ = monitor.await;
-
-    assert!(writer_count(&pool).await <= threshold as usize);
-}
-
-#[tokio::test]
-async fn me_health_monitor_drains_deadline_storm_with_budgeted_progress() {
-    let (pool, rng) = make_pool(128, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=220u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(120),
-            1,
-            now_epoch_secs.saturating_sub(1),
-        )
-        .await;
-    }
-
-    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
-    tokio::time::sleep(Duration::from_millis(120)).await;
-    monitor.abort();
-    let _ = monitor.await;
-
-    assert_eq!(writer_count(&pool).await, 0);
-}
-
-#[tokio::test]
-async fn me_health_monitor_eliminates_mixed_empty_and_deadline_backlog() {
-    let threshold = 12u64;
-    let (pool, rng) = make_pool(threshold, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=180u64 {
-        let bound_clients = if writer_id % 3 == 0 { 0 } else { 1 };
-        let deadline = if writer_id % 2 == 0 {
-            now_epoch_secs.saturating_sub(1)
-        } else {
-            0
-        };
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(250).saturating_add(writer_id),
-            bound_clients,
-            deadline,
-        )
-        .await;
-    }
-
-    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
-    tokio::time::sleep(Duration::from_millis(140)).await;
-    monitor.abort();
-    let _ = monitor.await;
-
-    assert!(writer_count(&pool).await <= threshold as usize);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_deterministic_mixed_state_churn_preserves_invariants() {
-    let threshold = 9u64;
-    let (pool, _rng) = make_pool(threshold, 1, 1).await;
-    let mut warn_next_allowed = HashMap::new();
-    let mut seed = 0x9E37_79B9_7F4A_7C15u64;
-    let mut next_writer_id = 20_000u64;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=72u64 {
-        let bound_clients = if writer_id % 4 == 0 { 0 } else { 1 };
-        let deadline = if writer_id % 5 == 0 {
-            now_epoch_secs.saturating_sub(1)
-        } else {
-            0
-        };
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(500).saturating_add(writer_id),
-            bound_clients,
-            deadline,
-        )
-        .await;
-    }
-
-    for _round in 0..90 {
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-        let draining_ids = draining_writer_ids(&pool).await;
-        assert!(
-            warn_next_allowed.keys().all(|id| draining_ids.contains(id)),
-            "warn-state keys must always be a subset of live draining writers"
-        );
-
-        let writer_ids = sorted_writer_ids(&pool).await;
-        if writer_ids.is_empty() {
-            continue;
-        }
-
-        let remove_n = (lcg_next(&mut seed) % 3) as usize;
-        for writer_id in writer_ids.iter().copied().take(remove_n) {
-            let _ = pool.remove_writer_and_close_clients(writer_id).await;
-        }
-
-        let survivors = sorted_writer_ids(&pool).await;
-        if !survivors.is_empty() {
-            let idx = (lcg_next(&mut seed) as usize) % survivors.len();
-            let target = survivors[idx];
-            set_writer_runtime_state(&pool, target, false, 0, 0).await;
-        }
-
-        let survivors = sorted_writer_ids(&pool).await;
-        if survivors.len() > 1 {
-            let idx = (lcg_next(&mut seed) as usize) % survivors.len();
-            let target = survivors[idx];
-            let expired_deadline = if lcg_next(&mut seed) & 1 == 0 {
-                now_epoch_secs.saturating_sub(1)
-            } else {
-                0
-            };
-            set_writer_runtime_state(
-                &pool,
-                target,
-                true,
-                now_epoch_secs.saturating_sub(120),
-                expired_deadline,
-            )
-            .await;
-        }
-
-        let inject_n = (lcg_next(&mut seed) % 4) as usize;
-        for _ in 0..inject_n {
-            let bound_clients = if lcg_next(&mut seed) & 1 == 0 { 0 } else { 1 };
-            let deadline = if lcg_next(&mut seed) & 1 == 0 {
-                now_epoch_secs.saturating_sub(1)
-            } else {
-                0
-            };
-            insert_draining_writer(
-                &pool,
-                next_writer_id,
-                now_epoch_secs.saturating_sub(240),
-                bound_clients,
-                deadline,
-            )
-            .await;
-            next_writer_id = next_writer_id.saturating_add(1);
-        }
-    }
-
-    for _ in 0..64 {
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        if writer_count(&pool).await <= threshold as usize {
-            break;
-        }
-    }
-
-    assert!(writer_count(&pool).await <= threshold as usize);
-    let draining_ids = draining_writer_ids(&pool).await;
-    assert!(warn_next_allowed.keys().all(|id| draining_ids.contains(id)));
-}
-
-#[tokio::test]
-async fn reap_draining_writers_repeated_draining_flips_never_leave_stale_warn_state() {
-    let (pool, _rng) = make_pool(64, 1, 1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-
-    for writer_id in 1..=24u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(240), 1, 0).await;
-    }
-
-    let mut warn_next_allowed = HashMap::new();
-    for _round in 0..48u64 {
-        for writer_id in 1..=24u64 {
-            let draining = (writer_id + _round) % 3 != 0;
-            set_writer_runtime_state(
-                &pool,
-                writer_id,
-                draining,
-                now_epoch_secs.saturating_sub(120),
-                0,
-            )
-            .await;
-        }
-
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-        let draining_ids = draining_writer_ids(&pool).await;
-        assert!(
-            warn_next_allowed.keys().all(|id| draining_ids.contains(id)),
-            "warn-state map must not retain entries for writers outside draining set"
-        );
-    }
-}
-
-#[test]
-fn health_drain_close_budget_is_within_expected_bounds() {
-    let budget = health_drain_close_budget();
-    assert!((16..=256).contains(&budget));
-}
+// Bulk and monitor-driven drain adversarial cases.
+#[path = "health_adversarial_tests/bulk.rs"]
+mod bulk;
+// Deterministic churn and stale-state adversarial cases.
+#[path = "health_adversarial_tests/churn.rs"]
+mod churn;

src/transport/middle_proxy/tests/health_adversarial_tests/bulk.rs

@@ -0,0 +1,240 @@
+use super::*;
+
+#[tokio::test]
+async fn reap_draining_writers_clears_warn_state_when_pool_empty() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let mut warn_next_allowed = HashMap::new();
+    warn_next_allowed.insert(11, Instant::now() + Duration::from_secs(5));
+    warn_next_allowed.insert(22, Instant::now() + Duration::from_secs(5));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(warn_next_allowed.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_respects_threshold_across_multiple_overflow_cycles() {
+    let threshold = 3u64;
+    let (pool, _rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=60u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _ in 0..64 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if writer_count(&pool).await <= threshold as usize {
+            break;
+        }
+    }
+
+    assert_eq!(writer_count(&pool).await, threshold as usize);
+    assert_eq!(sorted_writer_ids(&pool).await, vec![1, 2, 3]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_handles_large_empty_writer_population() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let total = health_drain_close_budget()
+        .saturating_mul(3)
+        .saturating_add(27);
+
+    for writer_id in 1..=total as u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(120), 0, 0).await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _ in 0..24 {
+        if writer_count(&pool).await == 0 {
+            break;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    }
+
+    assert_eq!(writer_count(&pool).await, 0);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_processes_mass_deadline_expiry_without_unbounded_growth() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let total = health_drain_close_budget()
+        .saturating_mul(4)
+        .saturating_add(31);
+
+    for writer_id in 1..=total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(180),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _ in 0..40 {
+        if writer_count(&pool).await == 0 {
+            break;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    }
+
+    assert_eq!(writer_count(&pool).await, 0);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_maintains_warn_state_subset_property_under_bulk_churn() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut warn_next_allowed = HashMap::new();
+
+    for wave in 0..40u64 {
+        for offset in 0..8u64 {
+            insert_draining_writer(
+                &pool,
+                wave * 100 + offset,
+                now_epoch_secs.saturating_sub(400 + offset),
+                1,
+                0,
+            )
+            .await;
+        }
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= writer_count(&pool).await);
+
+        let ids = sorted_writer_ids(&pool).await;
+        for writer_id in ids.into_iter().take(3) {
+            let _ = pool.remove_writer_and_close_clients(writer_id).await;
+        }
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= writer_count(&pool).await);
+    }
+}
+
+#[tokio::test]
+async fn reap_draining_writers_budgeted_cleanup_never_increases_pool_size() {
+    let (pool, _rng) = make_pool(5, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=200u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(240).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    let mut previous = writer_count(&pool).await;
+    for _ in 0..32 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        let current = writer_count(&pool).await;
+        assert!(current <= previous);
+        previous = current;
+    }
+}
+
+#[tokio::test]
+async fn me_health_monitor_converges_to_threshold_under_live_injection_churn() {
+    let threshold = 7u64;
+    let (pool, rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=40u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+
+    for wave in 0..8u64 {
+        for offset in 0..10u64 {
+            insert_draining_writer(
+                &pool,
+                1000 + wave * 100 + offset,
+                now_epoch_secs.saturating_sub(120).saturating_add(offset),
+                1,
+                0,
+            )
+            .await;
+        }
+        tokio::time::sleep(Duration::from_millis(5)).await;
+    }
+
+    tokio::time::sleep(Duration::from_millis(120)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(writer_count(&pool).await <= threshold as usize);
+}
+
+#[tokio::test]
+async fn me_health_monitor_drains_deadline_storm_with_budgeted_progress() {
+    let (pool, rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=220u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(120),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(120)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert_eq!(writer_count(&pool).await, 0);
+}
+
+#[tokio::test]
+async fn me_health_monitor_eliminates_mixed_empty_and_deadline_backlog() {
+    let threshold = 12u64;
+    let (pool, rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=180u64 {
+        let bound_clients = if writer_id % 3 == 0 { 0 } else { 1 };
+        let deadline = if writer_id % 2 == 0 {
+            now_epoch_secs.saturating_sub(1)
+        } else {
+            0
+        };
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(250).saturating_add(writer_id),
+            bound_clients,
+            deadline,
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(140)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(writer_count(&pool).await <= threshold as usize);
+}

src/transport/middle_proxy/tests/health_adversarial_tests/churn.rs

@@ -0,0 +1,143 @@
+use super::*;
+
+#[tokio::test]
+async fn reap_draining_writers_deterministic_mixed_state_churn_preserves_invariants() {
+    let threshold = 9u64;
+    let (pool, _rng) = make_pool(threshold, 1, 1).await;
+    let mut warn_next_allowed = HashMap::new();
+    let mut seed = 0x9E37_79B9_7F4A_7C15u64;
+    let mut next_writer_id = 20_000u64;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=72u64 {
+        let bound_clients = if writer_id % 4 == 0 { 0 } else { 1 };
+        let deadline = if writer_id % 5 == 0 {
+            now_epoch_secs.saturating_sub(1)
+        } else {
+            0
+        };
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(500).saturating_add(writer_id),
+            bound_clients,
+            deadline,
+        )
+        .await;
+    }
+
+    for _round in 0..90 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+        let draining_ids = draining_writer_ids(&pool).await;
+        assert!(
+            warn_next_allowed.keys().all(|id| draining_ids.contains(id)),
+            "warn-state keys must always be a subset of live draining writers"
+        );
+
+        let writer_ids = sorted_writer_ids(&pool).await;
+        if writer_ids.is_empty() {
+            continue;
+        }
+
+        let remove_n = (lcg_next(&mut seed) % 3) as usize;
+        for writer_id in writer_ids.iter().copied().take(remove_n) {
+            let _ = pool.remove_writer_and_close_clients(writer_id).await;
+        }
+
+        let survivors = sorted_writer_ids(&pool).await;
+        if !survivors.is_empty() {
+            let idx = (lcg_next(&mut seed) as usize) % survivors.len();
+            let target = survivors[idx];
+            set_writer_runtime_state(&pool, target, false, 0, 0).await;
+        }
+
+        let survivors = sorted_writer_ids(&pool).await;
+        if survivors.len() > 1 {
+            let idx = (lcg_next(&mut seed) as usize) % survivors.len();
+            let target = survivors[idx];
+            let expired_deadline = if lcg_next(&mut seed) & 1 == 0 {
+                now_epoch_secs.saturating_sub(1)
+            } else {
+                0
+            };
+            set_writer_runtime_state(
+                &pool,
+                target,
+                true,
+                now_epoch_secs.saturating_sub(120),
+                expired_deadline,
+            )
+            .await;
+        }
+
+        let inject_n = (lcg_next(&mut seed) % 4) as usize;
+        for _ in 0..inject_n {
+            let bound_clients = if lcg_next(&mut seed) & 1 == 0 { 0 } else { 1 };
+            let deadline = if lcg_next(&mut seed) & 1 == 0 {
+                now_epoch_secs.saturating_sub(1)
+            } else {
+                0
+            };
+            insert_draining_writer(
+                &pool,
+                next_writer_id,
+                now_epoch_secs.saturating_sub(240),
+                bound_clients,
+                deadline,
+            )
+            .await;
+            next_writer_id = next_writer_id.saturating_add(1);
+        }
+    }
+
+    for _ in 0..64 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if writer_count(&pool).await <= threshold as usize {
+            break;
+        }
+    }
+
+    assert!(writer_count(&pool).await <= threshold as usize);
+    let draining_ids = draining_writer_ids(&pool).await;
+    assert!(warn_next_allowed.keys().all(|id| draining_ids.contains(id)));
+}
+
+#[tokio::test]
+async fn reap_draining_writers_repeated_draining_flips_never_leave_stale_warn_state() {
+    let (pool, _rng) = make_pool(64, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=24u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(240), 1, 0).await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _round in 0..48u64 {
+        for writer_id in 1..=24u64 {
+            let draining = (writer_id + _round) % 3 != 0;
+            set_writer_runtime_state(
+                &pool,
+                writer_id,
+                draining,
+                now_epoch_secs.saturating_sub(120),
+                0,
+            )
+            .await;
+        }
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+        let draining_ids = draining_writer_ids(&pool).await;
+        assert!(
+            warn_next_allowed.keys().all(|id| draining_ids.contains(id)),
+            "warn-state map must not retain entries for writers outside draining set"
+        );
+    }
+}
+
+#[test]
+fn health_drain_close_budget_is_within_expected_bounds() {
+    let budget = health_drain_close_budget();
+    assert!((16..=256).contains(&budget));
+}

src/transport/middle_proxy/tests/health_regression_tests.rs

@@ -203,422 +203,9 @@ async fn set_writer_draining(pool: &Arc<MePool>, writer_id: u64, draining: bool)
     }
 }
 
-#[tokio::test]
-async fn reap_draining_writers_drops_warn_state_for_removed_writer() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let conn_ids = insert_draining_writer(
-        &pool,
-        7,
-        now_epoch_secs.saturating_sub(180),
-        1,
-        now_epoch_secs.saturating_add(3_600),
-    )
-    .await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    assert!(warn_next_allowed.contains_key(&7));
-
-    let _ = pool.remove_writer_and_close_clients(7).await;
-    assert!(pool.registry.get_writer(conn_ids[0]).await.is_none());
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    assert!(!warn_next_allowed.contains_key(&7));
-}
-
-#[tokio::test]
-async fn reap_draining_writers_removes_empty_draining_writers() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(&pool, 1, now_epoch_secs.saturating_sub(40), 0, 0).await;
-    insert_draining_writer(&pool, 2, now_epoch_secs.saturating_sub(30), 0, 0).await;
-    insert_draining_writer(&pool, 3, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert_eq!(current_writer_ids(&pool).await, vec![3]);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_overflow_closes_oldest_non_empty_writers() {
-    let pool = make_pool(2).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(&pool, 11, now_epoch_secs.saturating_sub(40), 1, 0).await;
-    insert_draining_writer(&pool, 22, now_epoch_secs.saturating_sub(30), 1, 0).await;
-    insert_draining_writer(&pool, 33, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    insert_draining_writer(&pool, 44, now_epoch_secs.saturating_sub(10), 1, 0).await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert_eq!(current_writer_ids(&pool).await, vec![33, 44]);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_deadline_force_close_applies_under_threshold() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(
-        &pool,
-        50,
-        now_epoch_secs.saturating_sub(15),
-        1,
-        now_epoch_secs.saturating_sub(1),
-    )
-    .await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(current_writer_ids(&pool).await.is_empty());
-}
-
-#[tokio::test]
-async fn reap_draining_writers_limits_closes_per_health_tick() {
-    let pool = make_pool(1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    let writer_total = close_budget.saturating_add(20);
-    for writer_id in 1..=writer_total as u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    }
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert_eq!(pool.writers.read().await.len(), writer_total - close_budget);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_keeps_warn_state_for_deadline_backlog_writers() {
-    let pool = make_pool(0).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    let writer_total = close_budget.saturating_add(5);
-    for writer_id in 1..=writer_total as u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(60),
-            1,
-            now_epoch_secs.saturating_sub(1),
-        )
-        .await;
-    }
-    let target_writer_id = writer_total as u64;
-    let mut warn_next_allowed = HashMap::new();
-    warn_next_allowed.insert(target_writer_id, Instant::now() + Duration::from_secs(300));
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(writer_exists(&pool, target_writer_id).await);
-    assert!(warn_next_allowed.contains_key(&target_writer_id));
-}
-
-#[tokio::test]
-async fn reap_draining_writers_keeps_warn_state_for_overflow_backlog_writers() {
-    let pool = make_pool(1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    let writer_total = close_budget.saturating_add(6);
-    for writer_id in 1..=writer_total as u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
-            1,
-            0,
-        )
-        .await;
-    }
-    let target_writer_id = writer_total.saturating_sub(1) as u64;
-    let mut warn_next_allowed = HashMap::new();
-    warn_next_allowed.insert(target_writer_id, Instant::now() + Duration::from_secs(300));
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(writer_exists(&pool, target_writer_id).await);
-    assert!(warn_next_allowed.contains_key(&target_writer_id));
-}
-
-#[tokio::test]
-async fn reap_draining_writers_drops_warn_state_when_writer_exits_draining_state() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(&pool, 71, now_epoch_secs.saturating_sub(60), 1, 0).await;
-
-    let mut warn_next_allowed = HashMap::new();
-    warn_next_allowed.insert(71, Instant::now() + Duration::from_secs(300));
-
-    set_writer_draining(&pool, 71, false).await;
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(writer_exists(&pool, 71).await);
-    assert!(
-        !warn_next_allowed.contains_key(&71),
-        "warn cooldown state must be dropped after writer leaves draining state"
-    );
-}
-
-#[tokio::test]
-async fn reap_draining_writers_preserves_warn_state_across_multiple_budget_deferrals() {
-    let pool = make_pool(0).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    let writer_total = close_budget.saturating_mul(2).saturating_add(1);
-    for writer_id in 1..=writer_total as u64 {
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(120),
-            1,
-            now_epoch_secs.saturating_sub(1),
-        )
-        .await;
-    }
-
-    let tail_writer_id = writer_total as u64;
-    let mut warn_next_allowed = HashMap::new();
-    warn_next_allowed.insert(tail_writer_id, Instant::now() + Duration::from_secs(300));
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    assert!(writer_exists(&pool, tail_writer_id).await);
-    assert!(warn_next_allowed.contains_key(&tail_writer_id));
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    assert!(writer_exists(&pool, tail_writer_id).await);
-    assert!(warn_next_allowed.contains_key(&tail_writer_id));
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    assert!(!writer_exists(&pool, tail_writer_id).await);
-    assert!(
-        !warn_next_allowed.contains_key(&tail_writer_id),
-        "warn cooldown state must clear once writer is actually removed"
-    );
-}
-
-#[tokio::test]
-async fn reap_draining_writers_backlog_drains_across_ticks() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    let writer_total = close_budget.saturating_mul(2).saturating_add(7);
-    for writer_id in 1..=writer_total as u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 0, 0).await;
-    }
-    let mut warn_next_allowed = HashMap::new();
-
-    for _ in 0..8 {
-        if pool.writers.read().await.is_empty() {
-            break;
-        }
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-    }
-
-    assert!(pool.writers.read().await.is_empty());
-}
-
-#[tokio::test]
-async fn reap_draining_writers_threshold_backlog_converges_to_threshold() {
-    let threshold = 5u64;
-    let pool = make_pool(threshold).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    let writer_total = threshold as usize + close_budget.saturating_add(12);
-    for writer_id in 1..=writer_total as u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    }
-    let mut warn_next_allowed = HashMap::new();
-
-    for _ in 0..16 {
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        if pool.writers.read().await.len() <= threshold as usize {
-            break;
-        }
-    }
-
-    assert_eq!(pool.writers.read().await.len(), threshold as usize);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_threshold_zero_preserves_non_expired_non_empty_writers() {
-    let pool = make_pool(0).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(40), 1, 0).await;
-    insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(30), 1, 0).await;
-    insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert_eq!(current_writer_ids(&pool).await, vec![10, 20, 30]);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_prioritizes_force_close_before_empty_cleanup() {
-    let pool = make_pool(1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let close_budget = health_drain_close_budget();
-    for writer_id in 1..=close_budget.saturating_add(1) as u64 {
-        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
-    }
-    let empty_writer_id = close_budget.saturating_add(2) as u64;
-    insert_draining_writer(
-        &pool,
-        empty_writer_id,
-        now_epoch_secs.saturating_sub(20),
-        0,
-        0,
-    )
-    .await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert_eq!(current_writer_ids(&pool).await, vec![1, empty_writer_id]);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_empty_cleanup_does_not_increment_force_close_metric() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(&pool, 1, now_epoch_secs.saturating_sub(60), 0, 0).await;
-    insert_draining_writer(&pool, 2, now_epoch_secs.saturating_sub(50), 0, 0).await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(current_writer_ids(&pool).await.is_empty());
-    assert_eq!(pool.stats.get_pool_force_close_total(), 0);
-}
-
-#[tokio::test]
-async fn reap_draining_writers_handles_duplicate_force_close_requests_for_same_writer() {
-    let pool = make_pool(1).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    insert_draining_writer(
-        &pool,
-        10,
-        now_epoch_secs.saturating_sub(30),
-        1,
-        now_epoch_secs.saturating_sub(1),
-    )
-    .await;
-    insert_draining_writer(
-        &pool,
-        20,
-        now_epoch_secs.saturating_sub(20),
-        1,
-        now_epoch_secs.saturating_sub(1),
-    )
-    .await;
-    let mut warn_next_allowed = HashMap::new();
-
-    reap_draining_writers(&pool, &mut warn_next_allowed).await;
-
-    assert!(current_writer_ids(&pool).await.is_empty());
-}
-
-#[tokio::test]
-async fn reap_draining_writers_warn_state_never_exceeds_live_draining_population_under_churn() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let mut warn_next_allowed = HashMap::new();
-
-    for wave in 0..12u64 {
-        for offset in 0..9u64 {
-            insert_draining_writer(
-                &pool,
-                wave * 100 + offset,
-                now_epoch_secs.saturating_sub(120 + offset),
-                1,
-                0,
-            )
-            .await;
-        }
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
-
-        let existing_writer_ids = current_writer_ids(&pool).await;
-        for writer_id in existing_writer_ids.into_iter().take(4) {
-            let _ = pool.remove_writer_and_close_clients(writer_id).await;
-        }
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
-    }
-}
-
-#[tokio::test]
-async fn reap_draining_writers_mixed_backlog_converges_without_leaking_warn_state() {
-    let pool = make_pool(6).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let mut warn_next_allowed = HashMap::new();
-
-    for writer_id in 1..=18u64 {
-        let bound_clients = if writer_id % 3 == 0 { 0 } else { 1 };
-        let deadline = if writer_id % 2 == 0 {
-            now_epoch_secs.saturating_sub(1)
-        } else {
-            0
-        };
-        insert_draining_writer(
-            &pool,
-            writer_id,
-            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
-            bound_clients,
-            deadline,
-        )
-        .await;
-    }
-
-    for _ in 0..16 {
-        reap_draining_writers(&pool, &mut warn_next_allowed).await;
-        if pool.writers.read().await.len() <= 6 {
-            break;
-        }
-    }
-
-    assert!(pool.writers.read().await.len() <= 6);
-    assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
-}
-
-#[test]
-fn general_config_default_drain_threshold_remains_enabled() {
-    assert_eq!(GeneralConfig::default().me_pool_drain_threshold, 32);
-    assert!(GeneralConfig::default().me_pool_drain_soft_evict_enabled);
-    assert_eq!(
-        GeneralConfig::default().me_pool_drain_soft_evict_grace_secs,
-        10
-    );
-    assert_eq!(
-        GeneralConfig::default().me_pool_drain_soft_evict_per_writer,
-        2
-    );
-    assert_eq!(
-        GeneralConfig::default().me_pool_drain_soft_evict_budget_per_core,
-        16
-    );
-    assert_eq!(
-        GeneralConfig::default().me_pool_drain_soft_evict_cooldown_ms,
-        1000
-    );
-    assert_eq!(
-        GeneralConfig::default().me_bind_stale_mode,
-        MeBindStaleMode::Never
-    );
-}
-
-#[tokio::test]
-async fn prune_closed_writers_closes_bound_clients_when_writer_is_non_empty() {
-    let pool = make_pool(128).await;
-    let now_epoch_secs = MePool::now_epoch_secs();
-    let conn_ids =
-        insert_draining_writer(&pool, 910, now_epoch_secs.saturating_sub(60), 1, 0).await;
-
-    pool.prune_closed_writers().await;
-
-    assert!(!writer_exists(&pool, 910).await);
-    assert!(pool.registry.get_writer(conn_ids[0]).await.is_none());
-}
+// Budgeted drain cleanup regression cases.
+#[path = "health_regression_tests/budgeted.rs"]
+mod budgeted;
+// Backlog convergence and pruning regression cases.
+#[path = "health_regression_tests/convergence.rs"]
+mod convergence;

src/transport/middle_proxy/tests/health_regression_tests/budgeted.rs

@@ -0,0 +1,240 @@
+use super::*;
+
+#[tokio::test]
+async fn reap_draining_writers_drops_warn_state_for_removed_writer() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let conn_ids = insert_draining_writer(
+        &pool,
+        7,
+        now_epoch_secs.saturating_sub(180),
+        1,
+        now_epoch_secs.saturating_add(3_600),
+    )
+    .await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(warn_next_allowed.contains_key(&7));
+
+    let _ = pool.remove_writer_and_close_clients(7).await;
+    assert!(pool.registry.get_writer(conn_ids[0]).await.is_none());
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(!warn_next_allowed.contains_key(&7));
+}
+
+#[tokio::test]
+async fn reap_draining_writers_removes_empty_draining_writers() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 1, now_epoch_secs.saturating_sub(40), 0, 0).await;
+    insert_draining_writer(&pool, 2, now_epoch_secs.saturating_sub(30), 0, 0).await;
+    insert_draining_writer(&pool, 3, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![3]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_overflow_closes_oldest_non_empty_writers() {
+    let pool = make_pool(2).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 11, now_epoch_secs.saturating_sub(40), 1, 0).await;
+    insert_draining_writer(&pool, 22, now_epoch_secs.saturating_sub(30), 1, 0).await;
+    insert_draining_writer(&pool, 33, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    insert_draining_writer(&pool, 44, now_epoch_secs.saturating_sub(10), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![33, 44]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_deadline_force_close_applies_under_threshold() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(
+        &pool,
+        50,
+        now_epoch_secs.saturating_sub(15),
+        1,
+        now_epoch_secs.saturating_sub(1),
+    )
+    .await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(current_writer_ids(&pool).await.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_limits_closes_per_health_tick() {
+    let pool = make_pool(1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_add(20);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    }
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(pool.writers.read().await.len(), writer_total - close_budget);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_keeps_warn_state_for_deadline_backlog_writers() {
+    let pool = make_pool(0).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_add(5);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(60),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+    let target_writer_id = writer_total as u64;
+    let mut warn_next_allowed = HashMap::new();
+    warn_next_allowed.insert(target_writer_id, Instant::now() + Duration::from_secs(300));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(writer_exists(&pool, target_writer_id).await);
+    assert!(warn_next_allowed.contains_key(&target_writer_id));
+}
+
+#[tokio::test]
+async fn reap_draining_writers_keeps_warn_state_for_overflow_backlog_writers() {
+    let pool = make_pool(1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_add(6);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+    let target_writer_id = writer_total.saturating_sub(1) as u64;
+    let mut warn_next_allowed = HashMap::new();
+    warn_next_allowed.insert(target_writer_id, Instant::now() + Duration::from_secs(300));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(writer_exists(&pool, target_writer_id).await);
+    assert!(warn_next_allowed.contains_key(&target_writer_id));
+}
+
+#[tokio::test]
+async fn reap_draining_writers_drops_warn_state_when_writer_exits_draining_state() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 71, now_epoch_secs.saturating_sub(60), 1, 0).await;
+
+    let mut warn_next_allowed = HashMap::new();
+    warn_next_allowed.insert(71, Instant::now() + Duration::from_secs(300));
+
+    set_writer_draining(&pool, 71, false).await;
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(writer_exists(&pool, 71).await);
+    assert!(
+        !warn_next_allowed.contains_key(&71),
+        "warn cooldown state must be dropped after writer leaves draining state"
+    );
+}
+
+#[tokio::test]
+async fn reap_draining_writers_preserves_warn_state_across_multiple_budget_deferrals() {
+    let pool = make_pool(0).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_mul(2).saturating_add(1);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(120),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+
+    let tail_writer_id = writer_total as u64;
+    let mut warn_next_allowed = HashMap::new();
+    warn_next_allowed.insert(tail_writer_id, Instant::now() + Duration::from_secs(300));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(writer_exists(&pool, tail_writer_id).await);
+    assert!(warn_next_allowed.contains_key(&tail_writer_id));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(writer_exists(&pool, tail_writer_id).await);
+    assert!(warn_next_allowed.contains_key(&tail_writer_id));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(!writer_exists(&pool, tail_writer_id).await);
+    assert!(
+        !warn_next_allowed.contains_key(&tail_writer_id),
+        "warn cooldown state must clear once writer is actually removed"
+    );
+}
+
+#[tokio::test]
+async fn reap_draining_writers_backlog_drains_across_ticks() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_mul(2).saturating_add(7);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 0, 0).await;
+    }
+    let mut warn_next_allowed = HashMap::new();
+
+    for _ in 0..8 {
+        if pool.writers.read().await.is_empty() {
+            break;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    }
+
+    assert!(pool.writers.read().await.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_threshold_backlog_converges_to_threshold() {
+    let threshold = 5u64;
+    let pool = make_pool(threshold).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = threshold as usize + close_budget.saturating_add(12);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    }
+    let mut warn_next_allowed = HashMap::new();
+
+    for _ in 0..16 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if pool.writers.read().await.len() <= threshold as usize {
+            break;
+        }
+    }
+
+    assert_eq!(pool.writers.read().await.len(), threshold as usize);
+}

src/transport/middle_proxy/tests/health_regression_tests/convergence.rs

@@ -0,0 +1,182 @@
+use super::*;
+
+#[tokio::test]
+async fn reap_draining_writers_threshold_zero_preserves_non_expired_non_empty_writers() {
+    let pool = make_pool(0).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(40), 1, 0).await;
+    insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(30), 1, 0).await;
+    insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![10, 20, 30]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_prioritizes_force_close_before_empty_cleanup() {
+    let pool = make_pool(1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    for writer_id in 1..=close_budget.saturating_add(1) as u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    }
+    let empty_writer_id = close_budget.saturating_add(2) as u64;
+    insert_draining_writer(
+        &pool,
+        empty_writer_id,
+        now_epoch_secs.saturating_sub(20),
+        0,
+        0,
+    )
+    .await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![1, empty_writer_id]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_empty_cleanup_does_not_increment_force_close_metric() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 1, now_epoch_secs.saturating_sub(60), 0, 0).await;
+    insert_draining_writer(&pool, 2, now_epoch_secs.saturating_sub(50), 0, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(current_writer_ids(&pool).await.is_empty());
+    assert_eq!(pool.stats.get_pool_force_close_total(), 0);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_handles_duplicate_force_close_requests_for_same_writer() {
+    let pool = make_pool(1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(
+        &pool,
+        10,
+        now_epoch_secs.saturating_sub(30),
+        1,
+        now_epoch_secs.saturating_sub(1),
+    )
+    .await;
+    insert_draining_writer(
+        &pool,
+        20,
+        now_epoch_secs.saturating_sub(20),
+        1,
+        now_epoch_secs.saturating_sub(1),
+    )
+    .await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(current_writer_ids(&pool).await.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_warn_state_never_exceeds_live_draining_population_under_churn() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut warn_next_allowed = HashMap::new();
+
+    for wave in 0..12u64 {
+        for offset in 0..9u64 {
+            insert_draining_writer(
+                &pool,
+                wave * 100 + offset,
+                now_epoch_secs.saturating_sub(120 + offset),
+                1,
+                0,
+            )
+            .await;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
+
+        let existing_writer_ids = current_writer_ids(&pool).await;
+        for writer_id in existing_writer_ids.into_iter().take(4) {
+            let _ = pool.remove_writer_and_close_clients(writer_id).await;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
+    }
+}
+
+#[tokio::test]
+async fn reap_draining_writers_mixed_backlog_converges_without_leaking_warn_state() {
+    let pool = make_pool(6).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut warn_next_allowed = HashMap::new();
+
+    for writer_id in 1..=18u64 {
+        let bound_clients = if writer_id % 3 == 0 { 0 } else { 1 };
+        let deadline = if writer_id % 2 == 0 {
+            now_epoch_secs.saturating_sub(1)
+        } else {
+            0
+        };
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
+            bound_clients,
+            deadline,
+        )
+        .await;
+    }
+
+    for _ in 0..16 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if pool.writers.read().await.len() <= 6 {
+            break;
+        }
+    }
+
+    assert!(pool.writers.read().await.len() <= 6);
+    assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
+}
+
+#[test]
+fn general_config_default_drain_threshold_remains_enabled() {
+    assert_eq!(GeneralConfig::default().me_pool_drain_threshold, 32);
+    assert!(GeneralConfig::default().me_pool_drain_soft_evict_enabled);
+    assert_eq!(
+        GeneralConfig::default().me_pool_drain_soft_evict_grace_secs,
+        10
+    );
+    assert_eq!(
+        GeneralConfig::default().me_pool_drain_soft_evict_per_writer,
+        2
+    );
+    assert_eq!(
+        GeneralConfig::default().me_pool_drain_soft_evict_budget_per_core,
+        16
+    );
+    assert_eq!(
+        GeneralConfig::default().me_pool_drain_soft_evict_cooldown_ms,
+        1000
+    );
+    assert_eq!(
+        GeneralConfig::default().me_bind_stale_mode,
+        MeBindStaleMode::Never
+    );
+}
+
+#[tokio::test]
+async fn prune_closed_writers_closes_bound_clients_when_writer_is_non_empty() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let conn_ids =
+        insert_draining_writer(&pool, 910, now_epoch_secs.saturating_sub(60), 1, 0).await;
+
+    pool.prune_closed_writers().await;
+
+    assert!(!writer_exists(&pool, 910).await);
+    assert!(pool.registry.get_writer(conn_ids[0]).await.is_none());
+}

src/transport/upstream/connect.rs

@@ -0,0 +1,413 @@
+use super::*;
+
+impl UpstreamManager {
+    pub(super) async fn connect_selected_upstream(
+        &self,
+        idx: usize,
+        upstream: UpstreamConfig,
+        target: SocketAddr,
+        dc_idx: Option<i16>,
+        bind_rr: Option<Arc<AtomicUsize>>,
+    ) -> Result<(UpstreamStream, UpstreamEgressInfo)> {
+        let connect_started_at = Instant::now();
+        let mut last_error: Option<ProxyError> = None;
+        let mut attempts_used = 0u32;
+        for attempt in 1..=self.connect_retry_attempts {
+            let elapsed = connect_started_at.elapsed();
+            if elapsed >= self.connect_budget {
+                last_error = Some(ProxyError::ConnectionTimeout {
+                    addr: target.to_string(),
+                });
+                break;
+            }
+            let remaining_budget = self.connect_budget.saturating_sub(elapsed);
+            let attempt_timeout =
+                Duration::from_secs(self.tg_connect_timeout_secs).min(remaining_budget);
+            if attempt_timeout.is_zero() {
+                last_error = Some(ProxyError::ConnectionTimeout {
+                    addr: target.to_string(),
+                });
+                break;
+            }
+            attempts_used = attempt;
+            self.stats.increment_upstream_connect_attempt_total();
+            let start = Instant::now();
+            match self
+                .connect_via_upstream(idx, &upstream, target, bind_rr.clone(), attempt_timeout)
+                .await
+            {
+                Ok((stream, egress)) => {
+                    let rtt_ms = start.elapsed().as_secs_f64() * 1000.0;
+                    self.stats.increment_upstream_connect_success_total();
+                    self.stats
+                        .observe_upstream_connect_attempts_per_request(attempts_used);
+                    self.stats.observe_upstream_connect_duration_ms(
+                        connect_started_at.elapsed().as_millis() as u64,
+                        true,
+                    );
+                    let mut guard = self.upstreams.write().await;
+                    if let Some(u) = guard.get_mut(idx) {
+                        if !u.healthy {
+                            debug!(rtt_ms = format!("{:.1}", rtt_ms), "Upstream recovered");
+                        }
+                        if attempt > 1 {
+                            debug!(
+                                attempt,
+                                attempts = self.connect_retry_attempts,
+                                rtt_ms = format!("{:.1}", rtt_ms),
+                                "Upstream connect recovered after retry"
+                            );
+                        }
+                        u.healthy = true;
+                        u.fails = 0;
+
+                        if let Some(di) = dc_idx.and_then(UpstreamState::dc_array_idx) {
+                            u.dc_latency[di].update(rtt_ms);
+                        }
+                    }
+                    return Ok((stream, egress));
+                }
+                Err(e) => {
+                    let hard_error =
+                        self.connect_failfast_hard_errors && Self::is_hard_connect_error(&e);
+                    if hard_error {
+                        self.stats
+                            .increment_upstream_connect_failfast_hard_error_total();
+                    }
+                    if attempt < self.connect_retry_attempts && !hard_error {
+                        debug!(
+                            attempt,
+                            attempts = self.connect_retry_attempts,
+                            target = %target,
+                            error = %e,
+                            "Upstream connect attempt failed, retrying"
+                        );
+                        let backoff = self.retry_backoff_with_jitter();
+                        if !backoff.is_zero() {
+                            tokio::time::sleep(backoff).await;
+                        }
+                    } else if hard_error {
+                        debug!(
+                            attempt,
+                            attempts = self.connect_retry_attempts,
+                            target = %target,
+                            error = %e,
+                            "Upstream connect failed with hard error, failfast is active"
+                        );
+                    }
+                    last_error = Some(e);
+                    if hard_error {
+                        break;
+                    }
+                }
+            }
+        }
+
+        self.stats.increment_upstream_connect_fail_total();
+        self.stats
+            .observe_upstream_connect_attempts_per_request(attempts_used);
+        self.stats.observe_upstream_connect_duration_ms(
+            connect_started_at.elapsed().as_millis() as u64,
+            false,
+        );
+
+        let error = last_error.unwrap_or_else(|| {
+            ProxyError::Config("Upstream connect attempts exhausted".to_string())
+        });
+
+        let mut guard = self.upstreams.write().await;
+        if let Some(u) = guard.get_mut(idx) {
+            // Intermediate attempts are intentionally ignored here.
+            // Health state is degraded only when the entire connect cycle fails.
+            u.fails += 1;
+            warn!(
+                fails = u.fails,
+                attempts = self.connect_retry_attempts,
+                "Upstream failed after retries: {}",
+                error
+            );
+            if u.fails >= self.unhealthy_fail_threshold {
+                u.healthy = false;
+                warn!(
+                    fails = u.fails,
+                    threshold = self.unhealthy_fail_threshold,
+                    "Upstream marked unhealthy"
+                );
+            }
+        }
+        Err(error)
+    }
+
+    pub(super) async fn connect_via_upstream(
+        &self,
+        upstream_id: usize,
+        config: &UpstreamConfig,
+        target: SocketAddr,
+        bind_rr: Option<Arc<AtomicUsize>>,
+        connect_timeout: Duration,
+    ) -> Result<(UpstreamStream, UpstreamEgressInfo)> {
+        match &config.upstream_type {
+            UpstreamType::Direct {
+                interface,
+                bind_addresses,
+                bindtodevice,
+            } => {
+                let bind_ip = Self::resolve_bind_address(
+                    interface,
+                    bind_addresses,
+                    target,
+                    bind_rr.as_deref(),
+                    true,
+                );
+                if bind_ip.is_none() && bind_addresses.as_ref().is_some_and(|v| !v.is_empty()) {
+                    return Err(ProxyError::Config(format!(
+                        "No valid bind_addresses for target family {target}"
+                    )));
+                }
+
+                let socket = create_outgoing_socket_bound(target, bind_ip)?;
+                if let Some(device) = bindtodevice.as_deref().filter(|value| !value.is_empty()) {
+                    bind_outgoing_socket_to_device(&socket, device).map_err(ProxyError::Io)?;
+                    debug!(bindtodevice = %device, target = %target, "Pinned socket to interface");
+                }
+                if let Some(ip) = bind_ip {
+                    debug!(bind = %ip, target = %target, "Bound outgoing socket");
+                } else if interface.is_some() || bind_addresses.is_some() {
+                    debug!(target = %target, "No matching bind address for target family");
+                }
+
+                socket.set_nonblocking(true)?;
+                match socket.connect(&target.into()) {
+                    Ok(()) => {}
+                    Err(err)
+                        if err.raw_os_error() == Some(libc::EINPROGRESS)
+                            || err.kind() == std::io::ErrorKind::WouldBlock => {}
+                    Err(err) => return Err(ProxyError::Io(err)),
+                }
+
+                let std_stream: std::net::TcpStream = socket.into();
+                let stream = TcpStream::from_std(std_stream)?;
+
+                match tokio::time::timeout(connect_timeout, stream.writable()).await {
+                    Ok(Ok(())) => {}
+                    Ok(Err(e)) => return Err(ProxyError::Io(e)),
+                    Err(_) => {
+                        return Err(ProxyError::ConnectionTimeout {
+                            addr: target.to_string(),
+                        });
+                    }
+                }
+                if let Some(e) = stream.take_error()? {
+                    return Err(ProxyError::Io(e));
+                }
+
+                let local_addr = stream.local_addr().ok();
+                Ok((
+                    UpstreamStream::Tcp(stream),
+                    UpstreamEgressInfo {
+                        upstream_id,
+                        route_kind: UpstreamRouteKind::Direct,
+                        local_addr,
+                        direct_bind_ip: bind_ip,
+                        socks_bound_addr: None,
+                        socks_proxy_addr: None,
+                    },
+                ))
+            }
+            UpstreamType::Socks4 {
+                address,
+                interface,
+                user_id,
+            } => {
+                // Try to parse as SocketAddr first (IP:port), otherwise treat as hostname:port
+                let mut stream = if let Ok(proxy_addr) = address.parse::<SocketAddr>() {
+                    // IP:port format - use socket with optional interface binding
+                    let bind_ip = Self::resolve_bind_address(
+                        interface,
+                        &None,
+                        proxy_addr,
+                        bind_rr.as_deref(),
+                        false,
+                    );
+
+                    let socket = create_outgoing_socket_bound(proxy_addr, bind_ip)?;
+
+                    socket.set_nonblocking(true)?;
+                    match socket.connect(&proxy_addr.into()) {
+                        Ok(()) => {}
+                        Err(err)
+                            if err.raw_os_error() == Some(libc::EINPROGRESS)
+                                || err.kind() == std::io::ErrorKind::WouldBlock => {}
+                        Err(err) => return Err(ProxyError::Io(err)),
+                    }
+
+                    let std_stream: std::net::TcpStream = socket.into();
+                    let stream = TcpStream::from_std(std_stream)?;
+
+                    match tokio::time::timeout(connect_timeout, stream.writable()).await {
+                        Ok(Ok(())) => {}
+                        Ok(Err(e)) => return Err(ProxyError::Io(e)),
+                        Err(_) => {
+                            return Err(ProxyError::ConnectionTimeout {
+                                addr: proxy_addr.to_string(),
+                            });
+                        }
+                    }
+                    if let Some(e) = stream.take_error()? {
+                        return Err(ProxyError::Io(e));
+                    }
+                    stream
+                } else {
+                    // Hostname:port format - use tokio DNS resolution
+                    // Note: interface binding is not supported for hostnames
+                    if interface.is_some() {
+                        warn!(
+                            "SOCKS4 interface binding is not supported for hostname addresses, ignoring"
+                        );
+                    }
+                    self.connect_hostname_with_dns_override(address, connect_timeout)
+                        .await?
+                };
+
+                // replace socks user_id with config.selected_scope, if set
+                let scope: Option<&str> =
+                    Some(config.selected_scope.as_str()).filter(|s| !s.is_empty());
+                let _user_id: Option<&str> = scope.or(user_id.as_deref());
+
+                let bound = match tokio::time::timeout(
+                    connect_timeout,
+                    connect_socks4(&mut stream, target, _user_id),
+                )
+                .await
+                {
+                    Ok(Ok(bound)) => bound,
+                    Ok(Err(e)) => return Err(e),
+                    Err(_) => {
+                        return Err(ProxyError::ConnectionTimeout {
+                            addr: target.to_string(),
+                        });
+                    }
+                };
+                let local_addr = stream.local_addr().ok();
+                let socks_proxy_addr = stream.peer_addr().ok();
+                Ok((
+                    UpstreamStream::Tcp(stream),
+                    UpstreamEgressInfo {
+                        upstream_id,
+                        route_kind: UpstreamRouteKind::Socks4,
+                        local_addr,
+                        direct_bind_ip: None,
+                        socks_bound_addr: Some(bound.addr),
+                        socks_proxy_addr,
+                    },
+                ))
+            }
+            UpstreamType::Socks5 {
+                address,
+                interface,
+                username,
+                password,
+            } => {
+                // Try to parse as SocketAddr first (IP:port), otherwise treat as hostname:port
+                let mut stream = if let Ok(proxy_addr) = address.parse::<SocketAddr>() {
+                    // IP:port format - use socket with optional interface binding
+                    let bind_ip = Self::resolve_bind_address(
+                        interface,
+                        &None,
+                        proxy_addr,
+                        bind_rr.as_deref(),
+                        false,
+                    );
+
+                    let socket = create_outgoing_socket_bound(proxy_addr, bind_ip)?;
+
+                    socket.set_nonblocking(true)?;
+                    match socket.connect(&proxy_addr.into()) {
+                        Ok(()) => {}
+                        Err(err)
+                            if err.raw_os_error() == Some(libc::EINPROGRESS)
+                                || err.kind() == std::io::ErrorKind::WouldBlock => {}
+                        Err(err) => return Err(ProxyError::Io(err)),
+                    }
+
+                    let std_stream: std::net::TcpStream = socket.into();
+                    let stream = TcpStream::from_std(std_stream)?;
+
+                    match tokio::time::timeout(connect_timeout, stream.writable()).await {
+                        Ok(Ok(())) => {}
+                        Ok(Err(e)) => return Err(ProxyError::Io(e)),
+                        Err(_) => {
+                            return Err(ProxyError::ConnectionTimeout {
+                                addr: proxy_addr.to_string(),
+                            });
+                        }
+                    }
+                    if let Some(e) = stream.take_error()? {
+                        return Err(ProxyError::Io(e));
+                    }
+                    stream
+                } else {
+                    // Hostname:port format - use tokio DNS resolution
+                    // Note: interface binding is not supported for hostnames
+                    if interface.is_some() {
+                        warn!(
+                            "SOCKS5 interface binding is not supported for hostname addresses, ignoring"
+                        );
+                    }
+                    self.connect_hostname_with_dns_override(address, connect_timeout)
+                        .await?
+                };
+
+                debug!(config = ?config, "Socks5 connection");
+                // replace socks user:pass with config.selected_scope, if set
+                let scope: Option<&str> =
+                    Some(config.selected_scope.as_str()).filter(|s| !s.is_empty());
+                let _username: Option<&str> = scope.or(username.as_deref());
+                let _password: Option<&str> = scope.or(password.as_deref());
+
+                let bound = match tokio::time::timeout(
+                    connect_timeout,
+                    connect_socks5(&mut stream, target, _username, _password),
+                )
+                .await
+                {
+                    Ok(Ok(bound)) => bound,
+                    Ok(Err(e)) => return Err(e),
+                    Err(_) => {
+                        return Err(ProxyError::ConnectionTimeout {
+                            addr: target.to_string(),
+                        });
+                    }
+                };
+                let local_addr = stream.local_addr().ok();
+                let socks_proxy_addr = stream.peer_addr().ok();
+                Ok((
+                    UpstreamStream::Tcp(stream),
+                    UpstreamEgressInfo {
+                        upstream_id,
+                        route_kind: UpstreamRouteKind::Socks5,
+                        local_addr,
+                        direct_bind_ip: None,
+                        socks_bound_addr: Some(bound.addr),
+                        socks_proxy_addr,
+                    },
+                ))
+            }
+            UpstreamType::Shadowsocks { url, interface } => {
+                let stream = connect_shadowsocks(url, interface, target, connect_timeout).await?;
+                let local_addr = stream.get_ref().local_addr().ok();
+                Ok((
+                    UpstreamStream::Shadowsocks(Box::new(stream)),
+                    UpstreamEgressInfo {
+                        upstream_id,
+                        route_kind: UpstreamRouteKind::Shadowsocks,
+                        local_addr,
+                        direct_bind_ip: None,
+                        socks_bound_addr: None,
+                        socks_proxy_addr: None,
+                    },
+                ))
+            }
+        }
+    }
+}

src/transport/upstream/health_checks.rs

@@ -0,0 +1,243 @@
+use super::*;
+
+impl UpstreamManager {
+    /// Background health check based on reachable DC groups through each upstream.
+    /// Upstream stays healthy while at least `MIN_HEALTHY_DC_GROUPS` groups are reachable.
+    pub async fn run_health_checks(
+        &self,
+        prefer_ipv6: bool,
+        ipv4_enabled: bool,
+        ipv6_enabled: bool,
+        dc_overrides: HashMap<String, Vec<String>>,
+    ) {
+        let (health_ipv4_enabled, health_ipv6_enabled) = {
+            let guard = self.upstreams.read().await;
+            (
+                ipv4_enabled
+                    || guard
+                        .iter()
+                        .any(|upstream| upstream.config.ipv4 == Some(true)),
+                ipv6_enabled
+                    || guard
+                        .iter()
+                        .any(|upstream| upstream.config.ipv6 == Some(true)),
+            )
+        };
+        let groups = Self::build_health_check_groups(
+            health_ipv4_enabled,
+            health_ipv6_enabled,
+            &dc_overrides,
+        );
+        let required_healthy_groups = Self::required_healthy_group_count(groups.len());
+        let mut endpoint_rotation: HashMap<(usize, i16, bool), usize> = HashMap::new();
+
+        if groups.is_empty() {
+            warn!("No DC groups available for upstream health-checks");
+        }
+
+        loop {
+            tokio::time::sleep(Duration::from_secs(HEALTH_CHECK_INTERVAL_SECS)).await;
+
+            if groups.is_empty() || required_healthy_groups == 0 {
+                continue;
+            }
+
+            let target_upstreams: Vec<usize> = {
+                let guard = self.upstreams.read().await;
+                let has_unscoped = guard
+                    .iter()
+                    .any(|upstream| Self::is_unscoped_upstream(&upstream.config));
+                guard
+                    .iter()
+                    .enumerate()
+                    .filter(|(_, upstream)| {
+                        Self::should_check_in_default_dc_connectivity(
+                            has_unscoped,
+                            &upstream.config,
+                        )
+                    })
+                    .map(|(idx, _)| idx)
+                    .collect()
+            };
+
+            for i in target_upstreams {
+                let (config, bind_rr) = {
+                    let guard = self.upstreams.read().await;
+                    let u = &guard[i];
+                    (u.config.clone(), u.bind_rr.clone())
+                };
+                let (upstream_ipv4_enabled, upstream_ipv6_enabled) =
+                    Self::resolve_probe_dc_families(&config, ipv4_enabled, ipv6_enabled);
+                let upstream_prefer_ipv6 = config.prefer_ipv6(prefer_ipv6);
+
+                let mut healthy_groups = 0usize;
+                let mut latency_updates: Vec<(usize, f64)> = Vec::new();
+
+                for group in &groups {
+                    let mut group_ok = false;
+                    let mut group_rtt_ms = None;
+
+                    for (is_primary, endpoints) in
+                        Self::health_check_endpoint_order(group, upstream_prefer_ipv6)
+                    {
+                        if endpoints.is_empty() {
+                            continue;
+                        }
+
+                        let filtered_endpoints: Vec<SocketAddr> = endpoints
+                            .iter()
+                            .copied()
+                            .filter(|endpoint| {
+                                if endpoint.is_ipv4() {
+                                    upstream_ipv4_enabled
+                                } else {
+                                    upstream_ipv6_enabled
+                                }
+                            })
+                            .collect();
+
+                        if filtered_endpoints.is_empty() {
+                            continue;
+                        }
+
+                        let rotation_key = (i, group.dc_idx, is_primary);
+                        let start_idx = *endpoint_rotation.entry(rotation_key).or_insert(0)
+                            % filtered_endpoints.len();
+                        let mut next_idx = (start_idx + 1) % filtered_endpoints.len();
+
+                        for step in 0..filtered_endpoints.len() {
+                            let endpoint_idx = (start_idx + step) % filtered_endpoints.len();
+                            let endpoint = filtered_endpoints[endpoint_idx];
+
+                            let start = Instant::now();
+                            let result = tokio::time::timeout(
+                                Duration::from_secs(HEALTH_CHECK_CONNECT_TIMEOUT_SECS),
+                                self.connect_via_upstream(
+                                    i,
+                                    &config,
+                                    endpoint,
+                                    Some(bind_rr.clone()),
+                                    Duration::from_secs(HEALTH_CHECK_CONNECT_TIMEOUT_SECS),
+                                ),
+                            )
+                            .await;
+
+                            match result {
+                                Ok(Ok(_stream)) => {
+                                    group_ok = true;
+                                    group_rtt_ms = Some(start.elapsed().as_secs_f64() * 1000.0);
+                                    next_idx = (endpoint_idx + 1) % filtered_endpoints.len();
+                                    break;
+                                }
+                                Ok(Err(e)) => {
+                                    debug!(
+                                        upstream = i,
+                                        dc = group.dc_idx,
+                                        endpoint = %endpoint,
+                                        primary = is_primary,
+                                        error = %e,
+                                        "Health-check endpoint failed"
+                                    );
+                                }
+                                Err(_) => {
+                                    debug!(
+                                        upstream = i,
+                                        dc = group.dc_idx,
+                                        endpoint = %endpoint,
+                                        primary = is_primary,
+                                        "Health-check endpoint timed out"
+                                    );
+                                }
+                            }
+                        }
+
+                        endpoint_rotation.insert(rotation_key, next_idx);
+
+                        if group_ok {
+                            break;
+                        }
+                    }
+
+                    if group_ok {
+                        healthy_groups += 1;
+                        if let (Some(dc_array_idx), Some(rtt_ms)) =
+                            (UpstreamState::dc_array_idx(group.dc_idx), group_rtt_ms)
+                        {
+                            latency_updates.push((dc_array_idx, rtt_ms));
+                        }
+                    }
+                }
+
+                let mut guard = self.upstreams.write().await;
+                let u = &mut guard[i];
+
+                for (dc_array_idx, rtt_ms) in latency_updates {
+                    u.dc_latency[dc_array_idx].update(rtt_ms);
+                }
+
+                if healthy_groups >= required_healthy_groups {
+                    if !u.healthy {
+                        info!(
+                            upstream = i,
+                            healthy_groups,
+                            total_groups = groups.len(),
+                            required_groups = required_healthy_groups,
+                            "Upstream recovered by DC-group health threshold"
+                        );
+                    }
+                    u.healthy = true;
+                    u.fails = 0;
+                } else {
+                    u.fails += 1;
+                    debug!(
+                        upstream = i,
+                        healthy_groups,
+                        total_groups = groups.len(),
+                        required_groups = required_healthy_groups,
+                        fails = u.fails,
+                        "Upstream health-check below DC-group threshold"
+                    );
+                    if u.fails >= self.unhealthy_fail_threshold {
+                        u.healthy = false;
+                        warn!(
+                            upstream = i,
+                            healthy_groups,
+                            total_groups = groups.len(),
+                            required_groups = required_healthy_groups,
+                            fails = u.fails,
+                            threshold = self.unhealthy_fail_threshold,
+                            "Upstream unhealthy (insufficient reachable DC groups)"
+                        );
+                    }
+                }
+
+                u.last_check = std::time::Instant::now();
+            }
+        }
+    }
+
+    /// Get the preferred IP for a DC (for use by other components)
+    #[allow(dead_code)]
+    pub async fn get_dc_ip_preference(&self, dc_idx: i16) -> Option<IpPreference> {
+        let guard = self.upstreams.read().await;
+        if guard.is_empty() {
+            return None;
+        }
+
+        UpstreamState::dc_array_idx(dc_idx).map(|idx| guard[0].dc_ip_pref[idx])
+    }
+
+    /// Get preferred DC address based on config preference
+    #[allow(dead_code)]
+    pub async fn get_dc_addr(&self, dc_idx: i16, prefer_ipv6: bool) -> Option<SocketAddr> {
+        let arr_idx = UpstreamState::dc_array_idx(dc_idx)?;
+
+        let ip = if prefer_ipv6 {
+            TG_DATACENTERS_V6[arr_idx]
+        } else {
+            TG_DATACENTERS_V4[arr_idx]
+        };
+
+        Some(SocketAddr::new(ip, TG_DATACENTER_PORT))
+    }
+}

src/transport/upstream/manager_config.rs

@@ -0,0 +1,470 @@
+use super::*;
+
+impl UpstreamManager {
+    pub(super) fn is_unscoped_upstream(upstream: &UpstreamConfig) -> bool {
+        upstream.scopes.is_empty()
+    }
+
+    pub(super) fn should_check_in_default_dc_connectivity(
+        has_unscoped: bool,
+        upstream: &UpstreamConfig,
+    ) -> bool {
+        !has_unscoped || Self::is_unscoped_upstream(upstream)
+    }
+
+    pub fn new(
+        configs: Vec<UpstreamConfig>,
+        connect_retry_attempts: u32,
+        connect_retry_backoff_ms: u64,
+        connect_budget_ms: u64,
+        tg_connect_timeout_secs: u64,
+        unhealthy_fail_threshold: u32,
+        connect_failfast_hard_errors: bool,
+        stats: Arc<Stats>,
+    ) -> Self {
+        let states = configs
+            .into_iter()
+            .filter(|c| c.enabled)
+            .map(UpstreamState::new)
+            .collect();
+
+        Self {
+            upstreams: Arc::new(RwLock::new(states)),
+            connect_retry_attempts: connect_retry_attempts.max(1),
+            connect_retry_backoff: Duration::from_millis(connect_retry_backoff_ms),
+            connect_budget: Duration::from_millis(connect_budget_ms.max(1)),
+            tg_connect_timeout_secs: tg_connect_timeout_secs.max(1),
+            unhealthy_fail_threshold: unhealthy_fail_threshold.max(1),
+            connect_failfast_hard_errors,
+            no_upstreams_warn_epoch_ms: Arc::new(AtomicU64::new(0)),
+            no_healthy_warn_epoch_ms: Arc::new(AtomicU64::new(0)),
+            stats,
+            dns_resolver: Arc::new(GenerationDnsResolver::default()),
+        }
+    }
+
+    pub(crate) fn with_dns_overrides(self, entries: &[String]) -> Result<Self> {
+        self.dns_resolver.apply_entries(entries)?;
+        Ok(self)
+    }
+
+    pub(crate) fn update_dns_overrides(&self, entries: &[String]) -> Result<()> {
+        self.dns_resolver.apply_entries(entries)
+    }
+
+    pub(crate) fn dns_resolver(&self) -> Arc<GenerationDnsResolver> {
+        Arc::clone(&self.dns_resolver)
+    }
+
+    pub(crate) async fn resolve_all(&self, host: &str, port: u16) -> Result<Vec<SocketAddr>> {
+        if let Some(addr) = self.dns_resolver.resolve_socket_addr(host, port) {
+            return Ok(vec![addr]);
+        }
+        let addrs = tokio::net::lookup_host((host, port))
+            .await
+            .map_err(ProxyError::Io)?
+            .take(DNS_RESULT_MAX_ADDRESSES)
+            .collect::<Vec<_>>();
+        if addrs.is_empty() {
+            return Err(ProxyError::Proxy(format!(
+                "DNS returned no addresses for {host}:{port}"
+            )));
+        }
+        Ok(addrs)
+    }
+
+    pub(crate) async fn resolve_hostname(&self, host: &str, port: u16) -> Result<SocketAddr> {
+        let addrs = self.resolve_all(host, port).await?;
+        if let Some(addr) = addrs.iter().copied().find(SocketAddr::is_ipv4) {
+            return Ok(addr);
+        }
+        addrs.first().copied().ok_or_else(|| {
+            ProxyError::Proxy(format!("DNS returned no addresses for {host}:{port}"))
+        })
+    }
+
+    pub(super) fn now_epoch_ms() -> u64 {
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64
+    }
+
+    pub(super) fn should_emit_warn(last_epoch_ms: &AtomicU64, cooldown_ms: u64) -> bool {
+        let now_epoch_ms = Self::now_epoch_ms();
+        let previous_epoch_ms = last_epoch_ms.load(Ordering::Relaxed);
+        if now_epoch_ms.saturating_sub(previous_epoch_ms) < cooldown_ms {
+            return false;
+        }
+        last_epoch_ms
+            .compare_exchange(
+                previous_epoch_ms,
+                now_epoch_ms,
+                Ordering::AcqRel,
+                Ordering::Relaxed,
+            )
+            .is_ok()
+    }
+
+    pub fn try_api_snapshot(&self) -> Option<UpstreamApiSnapshot> {
+        let guard = self.upstreams.try_read().ok()?;
+        let now = std::time::Instant::now();
+
+        let mut summary = UpstreamApiSummarySnapshot {
+            configured_total: guard.len(),
+            ..UpstreamApiSummarySnapshot::default()
+        };
+        let mut upstreams = Vec::with_capacity(guard.len());
+
+        for (idx, upstream) in guard.iter().enumerate() {
+            if upstream.healthy {
+                summary.healthy_total += 1;
+            } else {
+                summary.unhealthy_total += 1;
+            }
+
+            let (route_kind, address) = Self::describe_upstream(&upstream.config.upstream_type);
+            match route_kind {
+                UpstreamRouteKind::Direct => summary.direct_total += 1,
+                UpstreamRouteKind::Socks4 => summary.socks4_total += 1,
+                UpstreamRouteKind::Socks5 => summary.socks5_total += 1,
+                UpstreamRouteKind::Shadowsocks => summary.shadowsocks_total += 1,
+            }
+
+            let mut dc = Vec::with_capacity(NUM_DCS);
+            for dc_idx in 0..NUM_DCS {
+                dc.push(UpstreamApiDcSnapshot {
+                    dc: (dc_idx + 1) as i16,
+                    latency_ema_ms: upstream.dc_latency[dc_idx].get(),
+                    ip_preference: upstream.dc_ip_pref[dc_idx],
+                });
+            }
+
+            upstreams.push(UpstreamApiItemSnapshot {
+                upstream_id: idx,
+                route_kind,
+                address,
+                weight: upstream.config.weight,
+                scopes: upstream.config.scopes.clone(),
+                healthy: upstream.healthy,
+                fails: upstream.fails,
+                last_check_age_secs: now.saturating_duration_since(upstream.last_check).as_secs(),
+                effective_latency_ms: upstream.effective_latency(None),
+                dc,
+            });
+        }
+
+        Some(UpstreamApiSnapshot { summary, upstreams })
+    }
+
+    pub async fn api_health_summary(&self) -> UpstreamApiHealthSummary {
+        let guard = self.upstreams.read().await;
+        let mut summary = UpstreamApiHealthSummary {
+            configured_total: guard.len(),
+            healthy_total: 0,
+        };
+        for upstream in guard.iter() {
+            if upstream.healthy {
+                summary.healthy_total += 1;
+            }
+        }
+        summary
+    }
+
+    pub(super) fn describe_upstream(upstream_type: &UpstreamType) -> (UpstreamRouteKind, String) {
+        match upstream_type {
+            UpstreamType::Direct { .. } => (UpstreamRouteKind::Direct, "direct".to_string()),
+            UpstreamType::Socks4 { address, .. } => (UpstreamRouteKind::Socks4, address.clone()),
+            UpstreamType::Socks5 { address, .. } => (UpstreamRouteKind::Socks5, address.clone()),
+            UpstreamType::Shadowsocks { url, .. } => (
+                UpstreamRouteKind::Shadowsocks,
+                sanitize_shadowsocks_url(url).unwrap_or_else(|_| "invalid".to_string()),
+            ),
+        }
+    }
+
+    pub fn api_policy_snapshot(&self) -> UpstreamApiPolicySnapshot {
+        UpstreamApiPolicySnapshot {
+            connect_retry_attempts: self.connect_retry_attempts,
+            connect_retry_backoff_ms: self.connect_retry_backoff.as_millis() as u64,
+            connect_budget_ms: self.connect_budget.as_millis() as u64,
+            unhealthy_fail_threshold: self.unhealthy_fail_threshold,
+            connect_failfast_hard_errors: self.connect_failfast_hard_errors,
+        }
+    }
+
+    pub(super) fn resolve_probe_dc_families(
+        upstream: &UpstreamConfig,
+        ipv4_available: bool,
+        ipv6_available: bool,
+    ) -> (bool, bool) {
+        (
+            upstream.ipv4.unwrap_or(ipv4_available),
+            upstream.ipv6.unwrap_or(ipv6_available),
+        )
+    }
+
+    pub(super) fn resolve_runtime_dc_families(
+        upstream: &UpstreamConfig,
+        dc_preference: IpPreference,
+    ) -> (bool, bool) {
+        let (auto_ipv4, auto_ipv6) = match dc_preference {
+            IpPreference::PreferV4 => (true, false),
+            IpPreference::PreferV6 => (false, true),
+            IpPreference::BothWork | IpPreference::Unknown | IpPreference::Unavailable => {
+                (true, true)
+            }
+        };
+
+        (
+            upstream.ipv4.unwrap_or(auto_ipv4),
+            upstream.ipv6.unwrap_or(auto_ipv6),
+        )
+    }
+
+    pub(super) fn dc_table_addr(dc_idx: i16, ipv6: bool, port: u16) -> Option<SocketAddr> {
+        let arr_idx = UpstreamState::dc_array_idx(dc_idx)?;
+        let ip = if ipv6 {
+            TG_DATACENTERS_V6[arr_idx]
+        } else {
+            TG_DATACENTERS_V4[arr_idx]
+        };
+        Some(SocketAddr::new(ip, port))
+    }
+
+    pub(super) fn resolve_runtime_dc_target(
+        target: SocketAddr,
+        dc_idx: Option<i16>,
+        upstream: &UpstreamConfig,
+        dc_preference: IpPreference,
+    ) -> Result<SocketAddr> {
+        let (allow_ipv4, allow_ipv6) = Self::resolve_runtime_dc_families(upstream, dc_preference);
+        let preferred_ipv6 = match dc_preference {
+            IpPreference::PreferV6 => Some(true),
+            IpPreference::PreferV4 => Some(false),
+            IpPreference::BothWork | IpPreference::Unknown | IpPreference::Unavailable => {
+                upstream.prefer.map(|prefer| prefer == 6)
+            }
+        };
+        if let Some(preferred_ipv6) = preferred_ipv6
+            && target.is_ipv6() != preferred_ipv6
+        {
+            let preferred_allowed = if preferred_ipv6 {
+                allow_ipv6
+            } else {
+                allow_ipv4
+            };
+            if preferred_allowed {
+                if let Some(dc_idx) = dc_idx
+                    && let Some(remapped) =
+                        Self::dc_table_addr(dc_idx, preferred_ipv6, target.port())
+                {
+                    return Ok(remapped);
+                }
+            }
+        }
+
+        if (target.is_ipv4() && allow_ipv4) || (target.is_ipv6() && allow_ipv6) {
+            return Ok(target);
+        }
+
+        if !allow_ipv4 && !allow_ipv6 {
+            return Err(ProxyError::Config(format!(
+                "Upstream DC family policy blocks all families for target {target}"
+            )));
+        }
+
+        let Some(dc_idx) = dc_idx else {
+            return Err(ProxyError::Config(format!(
+                "Upstream DC family policy cannot remap target {target} without dc_idx"
+            )));
+        };
+
+        let remapped = if target.is_ipv4() {
+            if allow_ipv6 {
+                Self::dc_table_addr(dc_idx, true, target.port())
+            } else {
+                None
+            }
+        } else if allow_ipv4 {
+            Self::dc_table_addr(dc_idx, false, target.port())
+        } else {
+            None
+        };
+
+        remapped.ok_or_else(|| {
+            ProxyError::Config(format!(
+                "Upstream DC family policy rejected target {target} (dc_idx={dc_idx})"
+            ))
+        })
+    }
+
+    #[cfg(unix)]
+    pub(super) fn resolve_interface_addrs(name: &str, want_ipv6: bool) -> Vec<IpAddr> {
+        use nix::ifaddrs::getifaddrs;
+
+        let mut out = Vec::new();
+        if let Ok(addrs) = getifaddrs() {
+            for iface in addrs {
+                if iface.interface_name != name {
+                    continue;
+                }
+                if let Some(address) = iface.address {
+                    if let Some(v4) = address.as_sockaddr_in() {
+                        if !want_ipv6 {
+                            out.push(IpAddr::V4(v4.ip()));
+                        }
+                    } else if let Some(v6) = address.as_sockaddr_in6()
+                        && want_ipv6
+                    {
+                        out.push(IpAddr::V6(v6.ip()));
+                    }
+                }
+            }
+        }
+        out.sort_unstable();
+        out.dedup();
+        out
+    }
+
+    pub(crate) fn resolve_bind_address(
+        interface: &Option<String>,
+        bind_addresses: &Option<Vec<String>>,
+        target: SocketAddr,
+        rr: Option<&AtomicUsize>,
+        validate_ip_on_interface: bool,
+    ) -> Option<IpAddr> {
+        let want_ipv6 = target.is_ipv6();
+
+        if let Some(addrs) = bind_addresses.as_ref().filter(|v| !v.is_empty()) {
+            let mut candidates: Vec<IpAddr> = addrs
+                .iter()
+                .filter_map(|s| s.parse::<IpAddr>().ok())
+                .filter(|ip| ip.is_ipv6() == want_ipv6)
+                .collect();
+
+            // Explicit bind IP has strict priority over interface auto-selection.
+            if validate_ip_on_interface
+                && let Some(iface) = interface
+                && iface.parse::<IpAddr>().is_err()
+            {
+                #[cfg(unix)]
+                {
+                    let iface_addrs = Self::resolve_interface_addrs(iface, want_ipv6);
+                    if !iface_addrs.is_empty() {
+                        candidates.retain(|ip| {
+                            let ok = iface_addrs.contains(ip);
+                            if !ok {
+                                warn!(
+                                    interface = %iface,
+                                    bind_ip = %ip,
+                                    target = %target,
+                                    "Configured bind address is not assigned to interface"
+                                );
+                            }
+                            ok
+                        });
+                    } else if !candidates.is_empty() {
+                        warn!(
+                            interface = %iface,
+                            target = %target,
+                            "Configured interface has no addresses for target family"
+                        );
+                        candidates.clear();
+                    }
+                }
+            }
+
+            if !candidates.is_empty() {
+                if let Some(counter) = rr {
+                    let idx = counter.fetch_add(1, Ordering::Relaxed) % candidates.len();
+                    return Some(candidates[idx]);
+                }
+                return candidates.first().copied();
+            }
+
+            if validate_ip_on_interface
+                && interface
+                    .as_ref()
+                    .is_some_and(|iface| iface.parse::<IpAddr>().is_err())
+            {
+                warn!(
+                    interface = interface.as_deref().unwrap_or(""),
+                    target = %target,
+                    "No valid bind_addresses left for interface"
+                );
+            }
+
+            return None;
+        }
+
+        if let Some(iface) = interface {
+            if let Ok(ip) = iface.parse::<IpAddr>() {
+                if ip.is_ipv6() == want_ipv6 {
+                    return Some(ip);
+                }
+            } else {
+                #[cfg(unix)]
+                if let Some(ip) = resolve_interface_ip(iface, want_ipv6) {
+                    return Some(ip);
+                }
+            }
+        }
+
+        None
+    }
+
+    pub(super) async fn connect_hostname_with_dns_override(
+        &self,
+        address: &str,
+        connect_timeout: Duration,
+    ) -> Result<TcpStream> {
+        if let Some((host, port)) = split_host_port(address)
+            && let Some(addr) = self.dns_resolver.resolve_socket_addr(&host, port)
+        {
+            return match tokio::time::timeout(connect_timeout, TcpStream::connect(addr)).await {
+                Ok(Ok(stream)) => Ok(stream),
+                Ok(Err(e)) => Err(ProxyError::Io(e)),
+                Err(_) => Err(ProxyError::ConnectionTimeout {
+                    addr: addr.to_string(),
+                }),
+            };
+        }
+
+        match tokio::time::timeout(connect_timeout, TcpStream::connect(address)).await {
+            Ok(Ok(stream)) => Ok(stream),
+            Ok(Err(e)) => Err(ProxyError::Io(e)),
+            Err(_) => Err(ProxyError::ConnectionTimeout {
+                addr: address.to_string(),
+            }),
+        }
+    }
+
+    pub(super) fn retry_backoff_with_jitter(&self) -> Duration {
+        if self.connect_retry_backoff.is_zero() {
+            return Duration::ZERO;
+        }
+        let base_ms = self.connect_retry_backoff.as_millis() as u64;
+        if base_ms == 0 {
+            return self.connect_retry_backoff;
+        }
+        let jitter_cap_ms = (base_ms / 2).max(1);
+        let jitter_ms = rand::rng().random_range(0..=jitter_cap_ms);
+        Duration::from_millis(base_ms.saturating_add(jitter_ms))
+    }
+
+    pub(super) fn is_hard_connect_error(error: &ProxyError) -> bool {
+        match error {
+            ProxyError::Config(_) | ProxyError::ConnectionRefused { .. } => true,
+            ProxyError::Io(ioe) => matches!(
+                ioe.kind(),
+                std::io::ErrorKind::ConnectionRefused
+                    | std::io::ErrorKind::AddrInUse
+                    | std::io::ErrorKind::AddrNotAvailable
+                    | std::io::ErrorKind::InvalidInput
+                    | std::io::ErrorKind::Unsupported
+            ),
+            _ => false,
+        }
+    }
+}

src/transport/upstream/selection.rs

@@ -0,0 +1,185 @@
+use super::*;
+
+impl UpstreamManager {
+    /// Select upstream using latency-weighted random selection.
+    pub(super) async fn select_upstream(
+        &self,
+        dc_idx: Option<i16>,
+        scope: Option<&str>,
+    ) -> Option<usize> {
+        let upstreams = self.upstreams.read().await;
+        if upstreams.is_empty() {
+            return None;
+        }
+        // Scope filter:
+        //   If scope is set: only scoped and matched items
+        //   If scope is not set: only unscoped items
+        let filtered_upstreams: Vec<usize> = upstreams
+            .iter()
+            .enumerate()
+            .filter(|(_, u)| {
+                scope.map_or(u.config.scopes.is_empty(), |req_scope| {
+                    u.config
+                        .scopes
+                        .split(',')
+                        .map(str::trim)
+                        .any(|s| s == req_scope)
+                })
+            })
+            .map(|(i, _)| i)
+            .collect();
+
+        // Healthy filter
+        let healthy: Vec<usize> = filtered_upstreams
+            .iter()
+            .filter(|&&i| upstreams[i].healthy)
+            .copied()
+            .collect();
+
+        if filtered_upstreams.is_empty() {
+            if Self::should_emit_warn(self.no_upstreams_warn_epoch_ms.as_ref(), 5_000) {
+                warn!(
+                    scope = scope,
+                    "No upstreams available! Using first (direct?)"
+                );
+            }
+            return None;
+        }
+
+        if healthy.is_empty() {
+            if Self::should_emit_warn(self.no_healthy_warn_epoch_ms.as_ref(), 5_000) {
+                warn!(
+                    scope = scope,
+                    "No healthy upstreams available! Using random."
+                );
+            }
+            return Some(filtered_upstreams[rand::rng().random_range(0..filtered_upstreams.len())]);
+        }
+
+        if healthy.len() == 1 {
+            return Some(healthy[0]);
+        }
+
+        let weights: Vec<(usize, f64)> = healthy
+            .iter()
+            .map(|&i| {
+                let base = upstreams[i].config.weight as f64;
+                let latency_factor = upstreams[i]
+                    .effective_latency(dc_idx)
+                    .map(|ms| if ms > 1.0 { 1000.0 / ms } else { 1000.0 })
+                    .unwrap_or(1.0);
+
+                (i, base * latency_factor)
+            })
+            .collect();
+
+        let total: f64 = weights.iter().map(|(_, w)| w).sum();
+
+        if total <= 0.0 {
+            return Some(healthy[rand::rng().random_range(0..healthy.len())]);
+        }
+
+        let mut choice: f64 = rand::rng().random_range(0.0..total);
+
+        for &(idx, weight) in &weights {
+            if choice < weight {
+                trace!(
+                    upstream = idx,
+                    dc = ?dc_idx,
+                    weight = format!("{:.2}", weight),
+                    total = format!("{:.2}", total),
+                    "Upstream selected"
+                );
+                return Some(idx);
+            }
+            choice -= weight;
+        }
+
+        Some(healthy[0])
+    }
+
+    /// Connect to target through a selected upstream.
+    pub async fn connect(
+        &self,
+        target: SocketAddr,
+        dc_idx: Option<i16>,
+        scope: Option<&str>,
+    ) -> Result<UpstreamStream> {
+        let idx = self
+            .select_upstream(dc_idx, scope)
+            .await
+            .ok_or_else(|| ProxyError::Config("No upstreams available".to_string()))?;
+
+        let (mut upstream, bind_rr, dc_preference) = {
+            let guard = self.upstreams.read().await;
+            let state = &guard[idx];
+            let dc_preference = dc_idx
+                .and_then(UpstreamState::dc_array_idx)
+                .map(|dc_array_idx| state.dc_ip_pref[dc_array_idx])
+                .unwrap_or(IpPreference::Unknown);
+            (
+                state.config.clone(),
+                Some(state.bind_rr.clone()),
+                dc_preference,
+            )
+        };
+
+        if let Some(s) = scope {
+            upstream.selected_scope = s.to_string();
+        }
+
+        let target = if dc_idx.is_some() {
+            Self::resolve_runtime_dc_target(target, dc_idx, &upstream, dc_preference)?
+        } else {
+            target
+        };
+
+        let (stream, _) = self
+            .connect_selected_upstream(idx, upstream, target, dc_idx, bind_rr)
+            .await?;
+        Ok(stream)
+    }
+
+    /// Connect to target through a selected upstream and return egress details.
+    pub async fn connect_with_details(
+        &self,
+        target: SocketAddr,
+        dc_idx: Option<i16>,
+        scope: Option<&str>,
+    ) -> Result<(TcpStream, UpstreamEgressInfo)> {
+        let idx = self
+            .select_upstream(dc_idx, scope)
+            .await
+            .ok_or_else(|| ProxyError::Config("No upstreams available".to_string()))?;
+
+        let (mut upstream, bind_rr, dc_preference) = {
+            let guard = self.upstreams.read().await;
+            let state = &guard[idx];
+            let dc_preference = dc_idx
+                .and_then(UpstreamState::dc_array_idx)
+                .map(|dc_array_idx| state.dc_ip_pref[dc_array_idx])
+                .unwrap_or(IpPreference::Unknown);
+            (
+                state.config.clone(),
+                Some(state.bind_rr.clone()),
+                dc_preference,
+            )
+        };
+
+        // Set scope for configuration copy
+        if let Some(s) = scope {
+            upstream.selected_scope = s.to_string();
+        }
+
+        let target = if dc_idx.is_some() {
+            Self::resolve_runtime_dc_target(target, dc_idx, &upstream, dc_preference)?
+        } else {
+            target
+        };
+
+        let (stream, egress) = self
+            .connect_selected_upstream(idx, upstream, target, dc_idx, bind_rr)
+            .await?;
+        Ok((stream.into_tcp()?, egress))
+    }
+}

src/transport/upstream/startup_probe.rs

@@ -0,0 +1,420 @@
+use super::*;
+
+impl UpstreamManager {
+    /// Ping all Telegram DCs through all upstreams.
+    /// Tests BOTH IPv6 and IPv4, returns separate results for each.
+    pub async fn ping_all_dcs(
+        &self,
+        prefer_ipv6: bool,
+        dc_overrides: &HashMap<String, Vec<String>>,
+        ipv4_enabled: bool,
+        ipv6_enabled: bool,
+    ) -> Vec<StartupPingResult> {
+        let upstreams: Vec<(usize, UpstreamConfig, Arc<AtomicUsize>)> = {
+            let guard = self.upstreams.read().await;
+            guard
+                .iter()
+                .enumerate()
+                .map(|(i, u)| (i, u.config.clone(), u.bind_rr.clone()))
+                .collect()
+        };
+        let has_unscoped = upstreams
+            .iter()
+            .any(|(_, cfg, _)| Self::is_unscoped_upstream(cfg));
+
+        let mut all_results = Vec::new();
+
+        for (upstream_idx, upstream_config, bind_rr) in &upstreams {
+            // DC connectivity checks should follow the default routing path.
+            // Scoped upstreams are included only when no unscoped upstream exists.
+            if !Self::should_check_in_default_dc_connectivity(has_unscoped, upstream_config) {
+                continue;
+            }
+
+            let (upstream_ipv4_enabled, upstream_ipv6_enabled) =
+                Self::resolve_probe_dc_families(upstream_config, ipv4_enabled, ipv6_enabled);
+            let upstream_prefer_ipv6 = upstream_config.prefer_ipv6(prefer_ipv6);
+            let upstream_name = match &upstream_config.upstream_type {
+                UpstreamType::Direct {
+                    interface,
+                    bind_addresses,
+                    bindtodevice,
+                } => {
+                    let mut direct_parts = Vec::new();
+                    if let Some(dev) = interface.as_deref().filter(|v| !v.is_empty()) {
+                        direct_parts.push(format!("dev={dev}"));
+                    }
+                    if let Some(src) = bind_addresses.as_ref().filter(|v| !v.is_empty()) {
+                        direct_parts.push(format!("src={}", src.join(",")));
+                    }
+                    if let Some(device) = bindtodevice.as_deref().filter(|v| !v.is_empty()) {
+                        direct_parts.push(format!("bindtodevice={device}"));
+                    }
+                    if direct_parts.is_empty() {
+                        "direct".to_string()
+                    } else {
+                        format!("direct {}", direct_parts.join(" "))
+                    }
+                }
+                UpstreamType::Socks4 { address, .. } => format!("socks4://{}", address),
+                UpstreamType::Socks5 { address, .. } => format!("socks5://{}", address),
+                UpstreamType::Shadowsocks { url, .. } => {
+                    let address =
+                        sanitize_shadowsocks_url(url).unwrap_or_else(|_| "invalid".to_string());
+                    format!("shadowsocks://{address}")
+                }
+            };
+
+            let mut v6_results = Vec::with_capacity(NUM_DCS);
+            if upstream_ipv6_enabled {
+                for dc_zero_idx in 0..NUM_DCS {
+                    let dc_v6 = TG_DATACENTERS_V6[dc_zero_idx];
+                    let addr_v6 = SocketAddr::new(dc_v6, TG_DATACENTER_PORT);
+
+                    let result = tokio::time::timeout(
+                        Duration::from_secs(DC_PING_TIMEOUT_SECS),
+                        self.ping_single_dc(
+                            *upstream_idx,
+                            upstream_config,
+                            Some(bind_rr.clone()),
+                            addr_v6,
+                        ),
+                    )
+                    .await;
+
+                    let ping_result = match result {
+                        Ok(Ok(rtt_ms)) => {
+                            let mut guard = self.upstreams.write().await;
+                            if let Some(u) = guard.get_mut(*upstream_idx) {
+                                u.dc_latency[dc_zero_idx].update(rtt_ms);
+                            }
+                            DcPingResult {
+                                dc_idx: dc_zero_idx + 1,
+                                dc_addr: addr_v6,
+                                rtt_ms: Some(rtt_ms),
+                                error: None,
+                            }
+                        }
+                        Ok(Err(e)) => DcPingResult {
+                            dc_idx: dc_zero_idx + 1,
+                            dc_addr: addr_v6,
+                            rtt_ms: None,
+                            error: Some(e.to_string()),
+                        },
+                        Err(_) => DcPingResult {
+                            dc_idx: dc_zero_idx + 1,
+                            dc_addr: addr_v6,
+                            rtt_ms: None,
+                            error: Some("timeout".to_string()),
+                        },
+                    };
+                    v6_results.push(ping_result);
+                }
+            } else {
+                for dc_zero_idx in 0..NUM_DCS {
+                    let dc_v6 = TG_DATACENTERS_V6[dc_zero_idx];
+                    v6_results.push(DcPingResult {
+                        dc_idx: dc_zero_idx + 1,
+                        dc_addr: SocketAddr::new(dc_v6, TG_DATACENTER_PORT),
+                        rtt_ms: None,
+                        error: Some(if ipv6_enabled {
+                            "ipv6 disabled by upstream policy".to_string()
+                        } else {
+                            "ipv6 disabled".to_string()
+                        }),
+                    });
+                }
+            }
+
+            let mut v4_results = Vec::with_capacity(NUM_DCS);
+            if upstream_ipv4_enabled {
+                for dc_zero_idx in 0..NUM_DCS {
+                    let dc_v4 = TG_DATACENTERS_V4[dc_zero_idx];
+                    let addr_v4 = SocketAddr::new(dc_v4, TG_DATACENTER_PORT);
+
+                    let result = tokio::time::timeout(
+                        Duration::from_secs(DC_PING_TIMEOUT_SECS),
+                        self.ping_single_dc(
+                            *upstream_idx,
+                            upstream_config,
+                            Some(bind_rr.clone()),
+                            addr_v4,
+                        ),
+                    )
+                    .await;
+
+                    let ping_result = match result {
+                        Ok(Ok(rtt_ms)) => {
+                            let mut guard = self.upstreams.write().await;
+                            if let Some(u) = guard.get_mut(*upstream_idx) {
+                                u.dc_latency[dc_zero_idx].update(rtt_ms);
+                            }
+                            DcPingResult {
+                                dc_idx: dc_zero_idx + 1,
+                                dc_addr: addr_v4,
+                                rtt_ms: Some(rtt_ms),
+                                error: None,
+                            }
+                        }
+                        Ok(Err(e)) => DcPingResult {
+                            dc_idx: dc_zero_idx + 1,
+                            dc_addr: addr_v4,
+                            rtt_ms: None,
+                            error: Some(e.to_string()),
+                        },
+                        Err(_) => DcPingResult {
+                            dc_idx: dc_zero_idx + 1,
+                            dc_addr: addr_v4,
+                            rtt_ms: None,
+                            error: Some("timeout".to_string()),
+                        },
+                    };
+                    v4_results.push(ping_result);
+                }
+            } else {
+                for dc_zero_idx in 0..NUM_DCS {
+                    let dc_v4 = TG_DATACENTERS_V4[dc_zero_idx];
+                    v4_results.push(DcPingResult {
+                        dc_idx: dc_zero_idx + 1,
+                        dc_addr: SocketAddr::new(dc_v4, TG_DATACENTER_PORT),
+                        rtt_ms: None,
+                        error: Some(if ipv4_enabled {
+                            "ipv4 disabled by upstream policy".to_string()
+                        } else {
+                            "ipv4 disabled".to_string()
+                        }),
+                    });
+                }
+            }
+
+            // === Ping DC overrides (v4/v6) ===
+            for (dc_key, addrs) in dc_overrides {
+                let dc_num: i16 = match dc_key.parse::<i16>() {
+                    Ok(v) if v > 0 => v,
+                    Err(_) => {
+                        warn!(dc = %dc_key, "Invalid dc_overrides key, skipping");
+                        continue;
+                    }
+                    _ => continue,
+                };
+                let dc_idx = dc_num as usize;
+                for addr_str in addrs {
+                    match addr_str.parse::<SocketAddr>() {
+                        Ok(addr) => {
+                            let is_v6 = addr.is_ipv6();
+                            if (is_v6 && !upstream_ipv6_enabled)
+                                || (!is_v6 && !upstream_ipv4_enabled)
+                            {
+                                continue;
+                            }
+                            let result = tokio::time::timeout(
+                                Duration::from_secs(DC_PING_TIMEOUT_SECS),
+                                self.ping_single_dc(
+                                    *upstream_idx,
+                                    upstream_config,
+                                    Some(bind_rr.clone()),
+                                    addr,
+                                ),
+                            )
+                            .await;
+
+                            let ping_result = match result {
+                                Ok(Ok(rtt_ms)) => DcPingResult {
+                                    dc_idx,
+                                    dc_addr: addr,
+                                    rtt_ms: Some(rtt_ms),
+                                    error: None,
+                                },
+                                Ok(Err(e)) => DcPingResult {
+                                    dc_idx,
+                                    dc_addr: addr,
+                                    rtt_ms: None,
+                                    error: Some(e.to_string()),
+                                },
+                                Err(_) => DcPingResult {
+                                    dc_idx,
+                                    dc_addr: addr,
+                                    rtt_ms: None,
+                                    error: Some("timeout".to_string()),
+                                },
+                            };
+
+                            if is_v6 {
+                                v6_results.push(ping_result);
+                            } else {
+                                v4_results.push(ping_result);
+                            }
+                        }
+                        Err(_) => {
+                            warn!(dc = %dc_idx, addr = %addr_str, "Invalid dc_overrides address, skipping")
+                        }
+                    }
+                }
+            }
+
+            // Check if both IP versions have at least one working DC
+            let v6_has_working = v6_results.iter().any(|r| r.rtt_ms.is_some());
+            let v4_has_working = v4_results.iter().any(|r| r.rtt_ms.is_some());
+            let both_available = v6_has_working && v4_has_working;
+
+            // Update IP preference for each DC
+            {
+                let mut guard = self.upstreams.write().await;
+                if let Some(u) = guard.get_mut(*upstream_idx) {
+                    for dc_zero_idx in 0..NUM_DCS {
+                        let v6_ok = v6_results[dc_zero_idx].rtt_ms.is_some();
+                        let v4_ok = v4_results[dc_zero_idx].rtt_ms.is_some();
+
+                        u.dc_ip_pref[dc_zero_idx] = match (v6_ok, v4_ok) {
+                            (true, true) => IpPreference::BothWork,
+                            (true, false) => IpPreference::PreferV6,
+                            (false, true) => IpPreference::PreferV4,
+                            (false, false) => IpPreference::Unavailable,
+                        };
+                    }
+                }
+            }
+
+            all_results.push(StartupPingResult {
+                v6_results,
+                v4_results,
+                upstream_name,
+                prefer_ipv6: upstream_prefer_ipv6,
+                both_available,
+            });
+        }
+
+        all_results
+    }
+
+    pub(super) async fn ping_single_dc(
+        &self,
+        upstream_id: usize,
+        config: &UpstreamConfig,
+        bind_rr: Option<Arc<AtomicUsize>>,
+        target: SocketAddr,
+    ) -> Result<f64> {
+        let start = Instant::now();
+        let _ = self
+            .connect_via_upstream(
+                upstream_id,
+                config,
+                target,
+                bind_rr,
+                Duration::from_secs(DC_PING_TIMEOUT_SECS),
+            )
+            .await?;
+        Ok(start.elapsed().as_secs_f64() * 1000.0)
+    }
+
+    pub(super) fn required_healthy_group_count(total_groups: usize) -> usize {
+        if total_groups == 0 {
+            0
+        } else {
+            total_groups.min(MIN_HEALTHY_DC_GROUPS)
+        }
+    }
+
+    pub(super) fn build_health_check_groups(
+        ipv4_enabled: bool,
+        ipv6_enabled: bool,
+        dc_overrides: &HashMap<String, Vec<String>>,
+    ) -> Vec<HealthCheckGroup> {
+        let mut v4_by_dc: HashMap<i16, Vec<SocketAddr>> = HashMap::new();
+        let mut v6_by_dc: HashMap<i16, Vec<SocketAddr>> = HashMap::new();
+
+        if ipv4_enabled {
+            for (idx, dc_ip) in TG_DATACENTERS_V4.iter().enumerate() {
+                let dc_idx = (idx + 1) as i16;
+                v4_by_dc
+                    .entry(dc_idx)
+                    .or_default()
+                    .push(SocketAddr::new(*dc_ip, TG_DATACENTER_PORT));
+            }
+        }
+
+        if ipv6_enabled {
+            for (idx, dc_ip) in TG_DATACENTERS_V6.iter().enumerate() {
+                let dc_idx = (idx + 1) as i16;
+                v6_by_dc
+                    .entry(dc_idx)
+                    .or_default()
+                    .push(SocketAddr::new(*dc_ip, TG_DATACENTER_PORT));
+            }
+        }
+
+        for (dc_key, addrs) in dc_overrides {
+            let dc_idx = match dc_key.parse::<i16>() {
+                Ok(v) if v > 0 => v,
+                _ => {
+                    warn!(dc = %dc_key, "Invalid dc_overrides key for health-check, skipping");
+                    continue;
+                }
+            };
+
+            for addr_str in addrs {
+                match addr_str.parse::<SocketAddr>() {
+                    Ok(addr) if addr.is_ipv6() => {
+                        if ipv6_enabled {
+                            v6_by_dc.entry(dc_idx).or_default().push(addr);
+                        }
+                    }
+                    Ok(addr) => {
+                        if ipv4_enabled {
+                            v4_by_dc.entry(dc_idx).or_default().push(addr);
+                        }
+                    }
+                    Err(_) => {
+                        warn!(
+                            dc = %dc_idx,
+                            addr = %addr_str,
+                            "Invalid dc_overrides address for health-check, skipping"
+                        );
+                    }
+                }
+            }
+        }
+
+        for addrs in v4_by_dc.values_mut() {
+            addrs.sort_unstable();
+            addrs.dedup();
+        }
+        for addrs in v6_by_dc.values_mut() {
+            addrs.sort_unstable();
+            addrs.dedup();
+        }
+
+        let mut all_dcs = BTreeSet::new();
+        all_dcs.extend(v4_by_dc.keys().copied());
+        all_dcs.extend(v6_by_dc.keys().copied());
+
+        let mut groups = Vec::with_capacity(all_dcs.len());
+        for dc_idx in all_dcs {
+            let v4_endpoints = v4_by_dc.remove(&dc_idx).unwrap_or_default();
+            let v6_endpoints = v6_by_dc.remove(&dc_idx).unwrap_or_default();
+
+            if v4_endpoints.is_empty() && v6_endpoints.is_empty() {
+                continue;
+            }
+
+            groups.push(HealthCheckGroup {
+                dc_idx,
+                v4_endpoints,
+                v6_endpoints,
+            });
+        }
+
+        groups
+    }
+
+    pub(super) fn health_check_endpoint_order(
+        group: &HealthCheckGroup,
+        prefer_ipv6: bool,
+    ) -> [(bool, &[SocketAddr]); 2] {
+        if prefer_ipv6 {
+            [(true, &group.v6_endpoints), (false, &group.v4_endpoints)]
+        } else {
+            [(true, &group.v4_endpoints), (false, &group.v6_endpoints)]
+        }
+    }
+}

src/transport/upstream/tests.rs

@@ -0,0 +1,231 @@
+use super::*;
+use std::sync::Arc;
+
+use crate::stats::Stats;
+
+const TEST_SHADOWSOCKS_URL: &str =
+    "ss://2022-blake3-aes-256-gcm:MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE=@127.0.0.1:8388";
+
+fn manager_with_dns(entries: &[String]) -> UpstreamManager {
+    UpstreamManager::new(Vec::new(), 1, 1, 1, 1, 1, false, Arc::new(Stats::new()))
+        .with_dns_overrides(entries)
+        .unwrap()
+}
+
+#[tokio::test]
+async fn generation_local_dns_overrides_are_isolated_and_case_insensitive() {
+    let active = manager_with_dns(&["Front.Example:443:192.0.2.10".to_string()]);
+    let candidate = manager_with_dns(&["front.example:443:[2001:db8::10]".to_string()]);
+
+    assert_eq!(
+        active.resolve_hostname("front.example", 443).await.unwrap(),
+        "192.0.2.10:443".parse::<SocketAddr>().unwrap()
+    );
+    assert_eq!(
+        candidate
+            .resolve_hostname("FRONT.EXAMPLE", 443)
+            .await
+            .unwrap(),
+        "[2001:db8::10]:443".parse::<SocketAddr>().unwrap()
+    );
+
+    candidate
+        .update_dns_overrides(&["front.example:443:192.0.2.20".to_string()])
+        .unwrap();
+    assert_eq!(
+        active.resolve_hostname("FRONT.EXAMPLE", 443).await.unwrap(),
+        "192.0.2.10:443".parse::<SocketAddr>().unwrap()
+    );
+    assert_eq!(
+        candidate
+            .resolve_hostname("front.example", 443)
+            .await
+            .unwrap(),
+        "192.0.2.20:443".parse::<SocketAddr>().unwrap()
+    );
+}
+
+#[test]
+fn required_healthy_group_count_applies_three_group_threshold() {
+    assert_eq!(UpstreamManager::required_healthy_group_count(0), 0);
+    assert_eq!(UpstreamManager::required_healthy_group_count(1), 1);
+    assert_eq!(UpstreamManager::required_healthy_group_count(2), 2);
+    assert_eq!(UpstreamManager::required_healthy_group_count(3), 3);
+    assert_eq!(UpstreamManager::required_healthy_group_count(5), 3);
+}
+
+#[test]
+fn build_health_check_groups_merges_family_endpoints_with_preference() {
+    let mut overrides = HashMap::new();
+    overrides.insert(
+        "2".to_string(),
+        vec![
+            "203.0.113.10:443".to_string(),
+            "203.0.113.11:443".to_string(),
+            "[2001:db8::10]:443".to_string(),
+        ],
+    );
+
+    let groups = UpstreamManager::build_health_check_groups(true, true, &overrides);
+    let dc2 = groups
+        .iter()
+        .find(|g| g.dc_idx == 2)
+        .expect("dc2 must be present");
+
+    assert!(dc2.v6_endpoints.iter().all(|addr| addr.is_ipv6()));
+    assert!(dc2.v4_endpoints.iter().all(|addr| addr.is_ipv4()));
+    assert!(
+        dc2.v6_endpoints
+            .contains(&"[2001:db8::10]:443".parse::<SocketAddr>().unwrap())
+    );
+    assert!(
+        dc2.v4_endpoints
+            .contains(&"203.0.113.10:443".parse::<SocketAddr>().unwrap())
+    );
+    assert!(
+        dc2.v4_endpoints
+            .contains(&"203.0.113.11:443".parse::<SocketAddr>().unwrap())
+    );
+
+    let ordered = UpstreamManager::health_check_endpoint_order(dc2, true);
+    assert!(ordered[0].1.iter().all(|addr| addr.is_ipv6()));
+    assert!(ordered[1].1.iter().all(|addr| addr.is_ipv4()));
+}
+
+#[test]
+fn build_health_check_groups_keeps_multiple_endpoints_per_group() {
+    let mut overrides = HashMap::new();
+    overrides.insert(
+        "9".to_string(),
+        vec![
+            "198.51.100.1:443".to_string(),
+            "198.51.100.2:443".to_string(),
+            "198.51.100.1:443".to_string(),
+        ],
+    );
+
+    let groups = UpstreamManager::build_health_check_groups(true, false, &overrides);
+    let dc9 = groups
+        .iter()
+        .find(|g| g.dc_idx == 9)
+        .expect("override-only dc group must be present");
+
+    assert_eq!(dc9.v4_endpoints.len(), 2);
+    assert!(
+        dc9.v4_endpoints
+            .contains(&"198.51.100.1:443".parse::<SocketAddr>().unwrap())
+    );
+    assert!(
+        dc9.v4_endpoints
+            .contains(&"198.51.100.2:443".parse::<SocketAddr>().unwrap())
+    );
+    assert!(dc9.v6_endpoints.is_empty());
+}
+
+#[test]
+fn hard_connect_error_classification_detects_connection_refused() {
+    let error = ProxyError::ConnectionRefused {
+        addr: "127.0.0.1:443".to_string(),
+    };
+    assert!(UpstreamManager::is_hard_connect_error(&error));
+}
+
+#[test]
+fn hard_connect_error_classification_skips_timeouts() {
+    let error = ProxyError::ConnectionTimeout {
+        addr: "127.0.0.1:443".to_string(),
+    };
+    assert!(!UpstreamManager::is_hard_connect_error(&error));
+}
+
+#[test]
+fn unscoped_selection_detects_default_route_upstream() {
+    let mut upstream = UpstreamConfig {
+        upstream_type: UpstreamType::Direct {
+            interface: None,
+            bind_addresses: None,
+            bindtodevice: None,
+        },
+        weight: 1,
+        enabled: true,
+        scopes: String::new(),
+        selected_scope: String::new(),
+        ipv4: None,
+        ipv6: None,
+        prefer: None,
+    };
+
+    assert!(UpstreamManager::is_unscoped_upstream(&upstream));
+    upstream.scopes = "local".to_string();
+    assert!(!UpstreamManager::is_unscoped_upstream(&upstream));
+    assert!(!UpstreamManager::should_check_in_default_dc_connectivity(
+        true, &upstream
+    ));
+    assert!(UpstreamManager::should_check_in_default_dc_connectivity(
+        false, &upstream
+    ));
+}
+
+#[test]
+fn resolve_bind_address_prefers_explicit_bind_ip() {
+    let target = "203.0.113.10:443".parse::<SocketAddr>().unwrap();
+    let bind = UpstreamManager::resolve_bind_address(
+        &Some("198.51.100.20".to_string()),
+        &Some(vec!["198.51.100.10".to_string()]),
+        target,
+        None,
+        true,
+    );
+
+    assert_eq!(bind, Some("198.51.100.10".parse::<IpAddr>().unwrap()));
+}
+
+#[test]
+fn resolve_bind_address_does_not_fallback_to_interface_when_bind_addresses_present() {
+    let target = "203.0.113.10:443".parse::<SocketAddr>().unwrap();
+    let bind = UpstreamManager::resolve_bind_address(
+        &Some("198.51.100.20".to_string()),
+        &Some(vec!["2001:db8::10".to_string()]),
+        target,
+        None,
+        true,
+    );
+
+    assert_eq!(bind, None);
+}
+
+#[test]
+fn api_snapshot_reports_shadowsocks_as_sanitized_route() {
+    let manager = UpstreamManager::new(
+        vec![UpstreamConfig {
+            upstream_type: UpstreamType::Shadowsocks {
+                url: TEST_SHADOWSOCKS_URL.to_string(),
+                interface: None,
+            },
+            weight: 2,
+            enabled: true,
+            scopes: String::new(),
+            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
+            prefer: None,
+        }],
+        1,
+        100,
+        1000,
+        10,
+        1,
+        false,
+        Arc::new(Stats::new()),
+    );
+
+    let snapshot = manager.try_api_snapshot().expect("snapshot");
+    assert_eq!(snapshot.summary.configured_total, 1);
+    assert_eq!(snapshot.summary.shadowsocks_total, 1);
+    assert_eq!(snapshot.upstreams.len(), 1);
+    assert_eq!(
+        snapshot.upstreams[0].route_kind,
+        UpstreamRouteKind::Shadowsocks
+    );
+    assert_eq!(snapshot.upstreams[0].address, "127.0.0.1:8388");
+}