refactor(tun): consolidate shared NIC configuration and tests (#2690)

* refactor(tun): consolidate shared NIC configuration and tests

Separate member claims from OS deltas so mobile admission updates do
not compute unused diffs. Reuse effective configurations for desktop
address, route, and MTU updates, and share the platform claims paths.

Remove redundant runtime dispatch and test-only public accessors while
preserving registration cleanup and platform device creation ordering.

Move configuration and lifecycle tests into focused modules. Reuse
setup and table-driven cases, and verify route replacement order,
source hints, stale registrations, and failed cleanup through behavior.

Validation: shared NIC unit and Docker integration tests, mobile claim
selection, TUN and public IPv6 tests, full-workspace clippy, Android
arm64 library check, and formatting of the changed files.

* docs(tun): describe shared Ring dispatch lifecycle

Document direct member Ring polling, mobile descriptor replacement,
and cooperative scheduling in the shared dispatcher. The dispatcher
implementation is already provided by the base branch in #2689.

* test(core): remove completion race from timeout budget test

Use a pending future to exercise stage-specific timeout errors.
A delayed CI runner can observe the old 20 ms sleep and 1 ms timeout
as ready together. Tokio polls the inner future first, returning Ok
instead of the error expected by the test.

Keep the timeout assertion without a competing completion timer.
Production timeout behavior is unchanged.

docs/core-architecture.md

@@ -445,6 +445,12 @@ and the last member's cleanup stops the dispatcher and releases the desktop
 device. A process-lifetime runtime does not extend the device's lifetime.
 Unnamed desktop TUNs and instance-local work retain their existing executors.
 
+Each member connects through one bounded Ring Tunnel. The shared dispatcher
+polls member streams in rotation and writes directly to their sinks, with no
+per-member forwarding tasks or intermediate packet queues. Desktop and mobile
+use one dispatch loop; mobile descriptor replacement is a control message.
+The loop consumes Tokio's cooperative budget even when packets are dropped.
+
 Only the member running the Magic DNS resolver claims its shared fake-IP
 route. The claim is removed before resolver shutdown and acquired by the next
 serving member after takeover. Client-only runners do not claim that route.

easytier-core/src/connectivity/manual/mod.rs

@@ -1381,13 +1381,14 @@ mod tests {
 
     #[tokio::test]
     async fn timeout_budget_reports_the_active_stage() {
-        let error =
-            with_timeout_budget("connect", Instant::now(), Duration::from_millis(1), async {
-                crate::foundation::time::sleep(Duration::from_millis(20)).await;
-                Ok::<(), anyhow::Error>(())
-            })
-            .await
-            .unwrap_err();
+        let error = with_timeout_budget(
+            "connect",
+            Instant::now(),
+            Duration::from_millis(1),
+            std::future::pending::<anyhow::Result<()>>(),
+        )
+        .await
+        .unwrap_err();
 
         assert!(error.to_string().contains("connect timeout after"));
     }

easytier/src/instance/shared_virtual_nic/ifcfg.rs

@@ -0,0 +1,272 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    net::{Ipv4Addr, Ipv6Addr},
+};
+
+use cidr::{Ipv4Cidr, Ipv4Inet, Ipv6Cidr, Ipv6Inet};
+
+use super::SharedVirtualNicMemberId;
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub struct SharedIpv4Route {
+    pub address: Ipv4Addr,
+    pub prefix: u8,
+    pub cost: Option<i32>,
+}
+
+impl SharedIpv4Route {
+    pub fn new(address: Ipv4Addr, prefix: u8, cost: Option<i32>) -> Self {
+        Self {
+            address,
+            prefix,
+            cost,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub struct SharedIpv6Route {
+    pub address: Ipv6Addr,
+    pub prefix: u8,
+    pub cost: Option<i32>,
+}
+
+impl SharedIpv6Route {
+    pub fn new(address: Ipv6Addr, prefix: u8, cost: Option<i32>) -> Self {
+        Self {
+            address,
+            prefix,
+            cost,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct SharedIfConfigClaims {
+    pub ipv4_addresses: BTreeSet<Ipv4Inet>,
+    pub ipv6_addresses: BTreeSet<Ipv6Inet>,
+    pub ipv4_routes: BTreeSet<SharedIpv4Route>,
+    pub ipv6_routes: BTreeSet<SharedIpv6Route>,
+    pub mtu: Option<u32>,
+}
+
+impl SharedIfConfigClaims {
+    fn ipv4_destinations(&self) -> impl Iterator<Item = (Ipv4Cidr, bool)> + '_ {
+        self.ipv4_addresses
+            .iter()
+            .map(|ip| (ip.network(), false))
+            .chain(
+                self.ipv4_routes
+                    .iter()
+                    .filter_map(|route| Ipv4Inet::new(route.address, route.prefix).ok())
+                    .map(|route| (route.network(), true)),
+            )
+    }
+
+    fn ipv6_destinations(&self) -> impl Iterator<Item = Ipv6Cidr> + '_ {
+        self.ipv6_addresses.iter().map(Ipv6Inet::network).chain(
+            self.ipv6_routes
+                .iter()
+                .filter_map(|route| Ipv6Inet::new(route.address, route.prefix).ok())
+                .map(|route| route.network()),
+        )
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct OwnedItemDelta<T> {
+    pub added: BTreeSet<T>,
+    pub removed: BTreeSet<T>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct SharedIfConfigDelta {
+    pub ipv4_addresses: OwnedItemDelta<Ipv4Inet>,
+    pub ipv6_addresses: OwnedItemDelta<Ipv6Inet>,
+    pub ipv4_routes: OwnedItemDelta<SharedIpv4Route>,
+    pub ipv6_routes: OwnedItemDelta<SharedIpv6Route>,
+}
+
+impl SharedIfConfigDelta {
+    pub(super) fn between(old: &SharedIfConfigClaims, new: &SharedIfConfigClaims) -> Self {
+        Self {
+            ipv4_addresses: item_delta(&old.ipv4_addresses, &new.ipv4_addresses),
+            ipv6_addresses: item_delta(&old.ipv6_addresses, &new.ipv6_addresses),
+            ipv4_routes: item_delta(&old.ipv4_routes, &new.ipv4_routes),
+            ipv6_routes: item_delta(&old.ipv6_routes, &new.ipv6_routes),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Default)]
+pub(crate) struct SharedIfConfig {
+    pub(super) member_claims: BTreeMap<SharedVirtualNicMemberId, SharedIfConfigClaims>,
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error(
+    "shared virtual NIC destination {requested} overlaps member {member_id} destination {existing}"
+)]
+pub(crate) struct SharedIfConfigConflict {
+    requested: String,
+    member_id: SharedVirtualNicMemberId,
+    existing: String,
+}
+
+impl SharedIfConfig {
+    pub(crate) fn ensure_disjoint(
+        &self,
+        member_id: SharedVirtualNicMemberId,
+        claims: &SharedIfConfigClaims,
+    ) -> anyhow::Result<()> {
+        let magic_dns = Ipv4Cidr::new(crate::instance::dns_server::MAGIC_DNS_FAKE_IP.parse()?, 32)?;
+        for (other_id, other) in &self.member_claims {
+            if *other_id == member_id {
+                continue;
+            }
+            for (requested, requested_is_route) in claims.ipv4_destinations() {
+                if let Some((existing, _)) =
+                    other
+                        .ipv4_destinations()
+                        .find(|(existing, existing_is_route)| {
+                            !(requested_is_route
+                                && *existing_is_route
+                                && requested == magic_dns
+                                && *existing == magic_dns)
+                                && ipv4_cidrs_overlap(requested, *existing)
+                        })
+                {
+                    return Err(SharedIfConfigConflict {
+                        requested: requested.to_string(),
+                        member_id: *other_id,
+                        existing: existing.to_string(),
+                    }
+                    .into());
+                }
+            }
+            for requested in claims.ipv6_destinations() {
+                if let Some(existing) = other
+                    .ipv6_destinations()
+                    .find(|existing| ipv6_cidrs_overlap(requested, *existing))
+                {
+                    return Err(SharedIfConfigConflict {
+                        requested: requested.to_string(),
+                        member_id: *other_id,
+                        existing: existing.to_string(),
+                    }
+                    .into());
+                }
+            }
+        }
+        Ok(())
+    }
+
+    pub(crate) fn apply_member_claims(
+        &mut self,
+        member_id: SharedVirtualNicMemberId,
+        claims: SharedIfConfigClaims,
+    ) {
+        self.member_claims.insert(member_id, claims);
+    }
+
+    pub(super) fn remove_member(&mut self, member_id: SharedVirtualNicMemberId) -> bool {
+        self.member_claims.remove(&member_id).is_some()
+    }
+
+    fn effective_mtu(&self) -> Option<u32> {
+        self.member_claims
+            .values()
+            .filter_map(|claims| claims.mtu)
+            .min()
+    }
+
+    #[cfg(test)]
+    pub(crate) fn owners_of_ipv4_route(
+        &self,
+        route: &SharedIpv4Route,
+    ) -> BTreeSet<SharedVirtualNicMemberId> {
+        self.member_claims
+            .iter()
+            .filter_map(|(member_id, claims)| {
+                claims.ipv4_routes.contains(route).then_some(*member_id)
+            })
+            .collect()
+    }
+
+    pub(super) fn effective(&self) -> SharedIfConfigClaims {
+        SharedIfConfigClaims {
+            ipv4_addresses: self
+                .member_claims
+                .values()
+                .flat_map(|claims| claims.ipv4_addresses.iter().copied())
+                .collect(),
+            ipv6_addresses: self
+                .member_claims
+                .values()
+                .flat_map(|claims| claims.ipv6_addresses.iter().copied())
+                .collect(),
+            ipv4_routes: self
+                .member_claims
+                .values()
+                .flat_map(|claims| claims.ipv4_routes.iter().cloned())
+                .collect(),
+            ipv6_routes: self
+                .member_claims
+                .values()
+                .flat_map(|claims| claims.ipv6_routes.iter().cloned())
+                .collect(),
+            mtu: self.effective_mtu(),
+        }
+    }
+
+    pub(super) fn claims_of(&self, member_id: SharedVirtualNicMemberId) -> SharedIfConfigClaims {
+        self.member_claims
+            .get(&member_id)
+            .cloned()
+            .unwrap_or_default()
+    }
+
+    pub(super) fn ipv4_route_source_hint(&self, route: &SharedIpv4Route) -> Option<Ipv4Addr> {
+        let route_inet = Ipv4Inet::new(route.address, route.prefix).ok();
+        let mut fallback = None;
+
+        for claims in self.member_claims.values() {
+            if !claims.ipv4_routes.contains(route) {
+                continue;
+            }
+
+            for address in &claims.ipv4_addresses {
+                fallback.get_or_insert(address.address());
+                if route_inet
+                    .as_ref()
+                    .is_some_and(|route_inet| route_inet.contains(&address.address()))
+                {
+                    return Some(address.address());
+                }
+            }
+        }
+
+        fallback
+    }
+}
+
+fn item_delta<T>(old: &BTreeSet<T>, new: &BTreeSet<T>) -> OwnedItemDelta<T>
+where
+    T: Ord + Clone,
+{
+    OwnedItemDelta {
+        added: new.difference(old).cloned().collect(),
+        removed: old.difference(new).cloned().collect(),
+    }
+}
+
+fn ipv4_cidrs_overlap(left: Ipv4Cidr, right: Ipv4Cidr) -> bool {
+    left.contains(&right.first_address()) || right.contains(&left.first_address())
+}
+
+fn ipv6_cidrs_overlap(left: Ipv6Cidr, right: Ipv6Cidr) -> bool {
+    left.contains(&right.first_address()) || right.contains(&left.first_address())
+}
+
+#[cfg(test)]
+mod tests;

easytier/src/instance/shared_virtual_nic/ifcfg/tests.rs

@@ -0,0 +1,128 @@
+use super::*;
+
+fn member_id(n: u128) -> SharedVirtualNicMemberId {
+    uuid::Uuid::from_u128(n)
+}
+
+fn route(cidr: &str) -> SharedIpv4Route {
+    let ip: Ipv4Inet = cidr.parse().unwrap();
+    SharedIpv4Route::new(ip.address(), ip.network_length(), None)
+}
+
+#[test]
+fn shared_route_and_mtu_follow_member_ownership() {
+    let route = route("100.100.100.101/32");
+    let mut ifcfg = SharedIfConfig::default();
+    for (member, mtu) in [(member_id(1), 1400), (member_id(2), 1300)] {
+        let old = ifcfg.effective();
+        ifcfg.apply_member_claims(
+            member,
+            SharedIfConfigClaims {
+                ipv4_routes: BTreeSet::from([route.clone()]),
+                mtu: Some(mtu),
+                ..Default::default()
+            },
+        );
+        let next = ifcfg.effective();
+        let delta = SharedIfConfigDelta::between(&old, &next);
+        assert_eq!(
+            delta.ipv4_routes.added.contains(&route),
+            member == member_id(1)
+        );
+        assert!(delta.ipv4_routes.removed.is_empty());
+        assert_eq!(next.mtu, Some(mtu));
+    }
+    assert_eq!(
+        ifcfg.owners_of_ipv4_route(&route),
+        BTreeSet::from([member_id(1), member_id(2)])
+    );
+
+    for (member, expected_mtu) in [(member_id(2), Some(1400)), (member_id(1), None)] {
+        let old = ifcfg.effective();
+        assert!(ifcfg.remove_member(member));
+        let next = ifcfg.effective();
+        let delta = SharedIfConfigDelta::between(&old, &next);
+        assert!(delta.ipv4_routes.added.is_empty());
+        assert_eq!(
+            delta.ipv4_routes.removed.contains(&route),
+            expected_mtu.is_none()
+        );
+        assert_eq!(next.mtu, expected_mtu);
+    }
+    assert!(ifcfg.owners_of_ipv4_route(&route).is_empty());
+    assert!(!ifcfg.remove_member(member_id(1)));
+}
+
+#[test]
+fn replacing_member_claims_releases_previous_addresses() {
+    let first_ip: Ipv4Inet = "10.30.0.2/24".parse().unwrap();
+    let second_ip: Ipv4Inet = "10.30.0.3/24".parse().unwrap();
+    let mut ifcfg = SharedIfConfig::default();
+    for ip in [first_ip, second_ip] {
+        let old = ifcfg.effective();
+        ifcfg.apply_member_claims(
+            member_id(1),
+            SharedIfConfigClaims {
+                ipv4_addresses: BTreeSet::from([ip]),
+                ..Default::default()
+            },
+        );
+        let delta = SharedIfConfigDelta::between(&old, &ifcfg.effective());
+        assert_eq!(delta.ipv4_addresses.added, BTreeSet::from([ip]));
+        assert_eq!(delta.ipv4_addresses.removed, old.ipv4_addresses);
+        assert_eq!(
+            ifcfg.claims_of(member_id(1)).ipv4_addresses,
+            BTreeSet::from([ip])
+        );
+    }
+}
+
+#[test]
+fn only_magic_dns_routes_can_overlap_between_members() {
+    let address_claims = SharedIfConfigClaims {
+        ipv4_addresses: BTreeSet::from(["100.100.100.101/32".parse().unwrap()]),
+        ..Default::default()
+    };
+    let route_claims = SharedIfConfigClaims {
+        ipv4_routes: BTreeSet::from([route("100.100.100.101/32")]),
+        ..Default::default()
+    };
+
+    for (first, second, allowed) in [
+        (&route_claims, &route_claims, true),
+        (&address_claims, &address_claims, false),
+        (&address_claims, &route_claims, false),
+        (&route_claims, &address_claims, false),
+    ] {
+        let mut ifcfg = SharedIfConfig::default();
+        ifcfg.apply_member_claims(member_id(1), first.clone());
+        assert_eq!(ifcfg.ensure_disjoint(member_id(2), second).is_ok(), allowed);
+        assert!(ifcfg.ensure_disjoint(member_id(1), second).is_ok());
+    }
+}
+
+#[test]
+fn route_source_hint_prefers_an_owner_address_inside_the_route() {
+    let route = route("10.90.1.0/24");
+    let mut ifcfg = SharedIfConfig::default();
+    for (addresses, expected) in [
+        (vec!["10.1.1.1/24"], "10.1.1.1"),
+        (vec!["10.1.1.1/24", "10.90.1.1/24"], "10.90.1.1"),
+    ] {
+        ifcfg.apply_member_claims(
+            member_id(1),
+            SharedIfConfigClaims {
+                ipv4_addresses: addresses
+                    .into_iter()
+                    .map(|ip| ip.parse().unwrap())
+                    .collect(),
+                ipv4_routes: BTreeSet::from([route.clone()]),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            ifcfg.ipv4_route_source_hint(&route),
+            Some(expected.parse().unwrap())
+        );
+    }
+}

easytier/src/instance/shared_virtual_nic/tests.rs

@@ -0,0 +1,322 @@
+use std::sync::Mutex as StdMutex;
+
+use crate::common::{ifcfg::IfConfiguerTrait, netns::NetNS};
+
+use super::*;
+
+const MEMBER: SharedVirtualNicMemberId = uuid::Uuid::from_u128(1);
+const REGISTRATION: SharedVirtualNicMemberRegistrationId = uuid::Uuid::from_u128(10);
+
+fn virtual_nic_config(mtu: u32, netns: Option<&str>) -> VirtualNicConfig {
+    VirtualNicConfig::new("et0".to_owned(), mtu, NetNS::new(netns.map(str::to_owned)))
+}
+
+fn address_claims(ip: &str) -> SharedIfConfigClaims {
+    SharedIfConfigClaims {
+        ipv4_addresses: BTreeSet::from([ip.parse().unwrap()]),
+        ..Default::default()
+    }
+}
+
+fn registered_nic() -> SharedVirtualNic {
+    let mut nic = SharedVirtualNic::new(virtual_nic_config(1500, None));
+    nic.member_registrations.insert(MEMBER, REGISTRATION);
+    nic.ifcfg
+        .apply_member_claims(MEMBER, address_claims("10.50.0.2/24"));
+    nic
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum RouteChange {
+    Add(SharedIpv4Route, Option<Ipv4Addr>),
+    Remove(SharedIpv4Route, Option<Ipv4Addr>),
+}
+
+#[derive(Clone, Default)]
+struct RecordingIfConfiger {
+    routes: Arc<StdMutex<Vec<RouteChange>>>,
+    fail_remove_ip: bool,
+}
+
+#[async_trait::async_trait]
+impl IfConfiguerTrait for RecordingIfConfiger {
+    async fn add_ipv4_route_with_source_hint(
+        &self,
+        _name: &str,
+        address: Ipv4Addr,
+        prefix: u8,
+        cost: Option<i32>,
+        source_hint: Option<Ipv4Addr>,
+    ) -> Result<(), Error> {
+        self.routes.lock().unwrap().push(RouteChange::Add(
+            SharedIpv4Route::new(address, prefix, cost),
+            source_hint,
+        ));
+        Ok(())
+    }
+
+    async fn remove_ipv4_route_with_cost_and_source_hint(
+        &self,
+        _name: &str,
+        address: Ipv4Addr,
+        prefix: u8,
+        cost: Option<i32>,
+        source_hint: Option<Ipv4Addr>,
+    ) -> Result<(), Error> {
+        self.routes.lock().unwrap().push(RouteChange::Remove(
+            SharedIpv4Route::new(address, prefix, cost),
+            source_hint,
+        ));
+        Ok(())
+    }
+
+    async fn remove_ip(&self, _name: &str, _ip: Option<Ipv4Inet>) -> Result<(), Error> {
+        if self.fail_remove_ip {
+            return Err(anyhow::anyhow!("forced remove_ip failure").into());
+        }
+        Ok(())
+    }
+}
+
+async fn set_ifcfg(nic: &SharedVirtualNic, ifcfg: RecordingIfConfiger) {
+    let mut device = nic.nic.lock().await;
+    device.set_ifname_for_test("et0".to_owned());
+    device.set_ifcfg_for_test(Box::new(ifcfg));
+}
+
+#[tokio::test]
+async fn conflicting_claims_leave_existing_configuration_intact() {
+    for configure_os in [true, false] {
+        let mut nic = SharedVirtualNic::new(virtual_nic_config(1500, None));
+        let mut healthy = address_claims("10.144.1.1/24");
+        healthy
+            .ipv6_addresses
+            .insert("fd00:1::1/64".parse().unwrap());
+        nic.ifcfg.apply_member_claims(MEMBER, healthy.clone());
+        let original = nic.ifcfg.effective();
+
+        let mut conflicting_ipv6 = address_claims("10.144.2.1/24");
+        // IPv4 is disjoint, but the later IPv6 claim overlaps the healthy member.
+        conflicting_ipv6
+            .ipv6_addresses
+            .insert("fd00:1::2/64".parse().unwrap());
+        let conflicting_route = SharedIfConfigClaims {
+            ipv4_routes: BTreeSet::from([SharedIpv4Route::new(
+                "10.144.0.0".parse().unwrap(),
+                16,
+                None,
+            )]),
+            ..Default::default()
+        };
+        for claims in [conflicting_ipv6, conflicting_route] {
+            let rejected_member = uuid::Uuid::from_u128(2);
+            let err = nic
+                .apply_member_claims(rejected_member, claims, configure_os)
+                .await
+                .unwrap_err();
+            assert!(err.to_string().contains("overlaps member"));
+            assert_eq!(nic.ifcfg.claims_of(MEMBER), healthy);
+            assert_eq!(
+                nic.ifcfg.claims_of(rejected_member),
+                SharedIfConfigClaims::default()
+            );
+            assert!(nic.is_valid());
+        }
+        assert_eq!(nic.ifcfg.effective(), original);
+    }
+}
+
+#[tokio::test]
+async fn mobile_claims_do_not_configure_the_os_interface() {
+    // There is no OS interface or ifname; native ifcfg calls would fail.
+    let mut nic = SharedVirtualNic::new(virtual_nic_config(1500, None));
+    let claims = SharedIfConfigClaims {
+        ipv4_addresses: BTreeSet::from(["10.144.1.1/24".parse().unwrap()]),
+        ipv6_addresses: BTreeSet::from(["fd00:1::1/64".parse().unwrap()]),
+        ipv4_routes: BTreeSet::from([SharedIpv4Route::new(
+            "10.145.0.0".parse().unwrap(),
+            16,
+            None,
+        )]),
+        ipv6_routes: BTreeSet::from([SharedIpv6Route::new("fd00:2::".parse().unwrap(), 64, None)]),
+        mtu: Some(1300),
+    };
+    for claims in [claims, SharedIfConfigClaims::default()] {
+        nic.apply_member_claims(MEMBER, claims.clone(), false)
+            .await
+            .unwrap();
+        assert_eq!(nic.ifcfg.claims_of(MEMBER), claims);
+        assert!(nic.is_valid());
+    }
+    #[cfg(mobile)]
+    {
+        nic.member_registrations.insert(MEMBER, REGISTRATION);
+        nic.link_up().await.unwrap();
+        nic.apply_member_mtu_for_registration(MEMBER, REGISTRATION, 1200)
+            .await
+            .unwrap();
+        assert_eq!(nic.ifcfg.claims_of(MEMBER).mtu, Some(1200));
+    }
+}
+
+#[tokio::test]
+async fn stale_registration_cannot_update_or_remove_current_claims() {
+    let mut nic = registered_nic();
+    let original = nic.ifcfg.effective();
+    let stale = uuid::Uuid::from_u128(9);
+    nic.apply_member_claims_for_registration(MEMBER, stale, SharedIfConfigClaims::default())
+        .await
+        .unwrap();
+    nic.apply_member_mtu_for_registration(MEMBER, stale, 1200)
+        .await
+        .unwrap();
+    nic.remove_member_registration_claims(MEMBER, stale)
+        .await
+        .unwrap();
+    assert_eq!(nic.ifcfg.effective(), original);
+    assert_eq!(nic.member_registrations.get(&MEMBER), Some(&REGISTRATION));
+}
+
+#[cfg(not(mobile))]
+#[tokio::test]
+async fn failed_cleanup_and_replacement_invalidate_without_committing_claims() {
+    for replacing in [false, true] {
+        let mut nic = registered_nic();
+        let original = nic.ifcfg.effective();
+        set_ifcfg(
+            &nic,
+            RecordingIfConfiger {
+                fail_remove_ip: true,
+                ..Default::default()
+            },
+        )
+        .await;
+        let result = if replacing {
+            nic.attach_member_registration(MEMBER, uuid::Uuid::from_u128(11))
+                .await
+        } else {
+            nic.remove_member_registration_claims(MEMBER, REGISTRATION)
+                .await
+        };
+        assert!(result.is_err(), "replacing={replacing}");
+        assert!(!nic.is_valid());
+        assert_eq!(nic.ifcfg.effective(), original);
+        assert_eq!(
+            nic.member_registrations.get(&MEMBER).copied(),
+            replacing.then_some(REGISTRATION)
+        );
+    }
+}
+
+#[tokio::test]
+async fn changed_route_source_is_removed_before_its_replacement_is_added() {
+    let route = SharedIpv4Route::new("10.90.2.0".parse().unwrap(), 24, Some(10));
+    let fallback = "10.1.2.1".parse().unwrap();
+    let preferred = "10.90.2.1".parse().unwrap();
+    for adding_owner in [true, false] {
+        let mut nic = SharedVirtualNic::new(virtual_nic_config(1500, None));
+        let ifcfg = RecordingIfConfiger::default();
+        set_ifcfg(&nic, ifcfg.clone()).await;
+        let mut claims = address_claims("10.1.2.1/24");
+        claims.ipv4_routes.insert(route.clone());
+        nic.ifcfg.apply_member_claims(MEMBER, claims);
+        let mut with_owner = nic.ifcfg.clone();
+        let mut claims = address_claims("10.90.2.1/24");
+        claims.ipv4_routes.insert(route.clone());
+        with_owner.apply_member_claims(uuid::Uuid::from_u128(2), claims);
+        let (next, old_source, new_source) = if adding_owner {
+            (with_owner, fallback, preferred)
+        } else {
+            (
+                std::mem::replace(&mut nic.ifcfg, with_owner),
+                preferred,
+                fallback,
+            )
+        };
+        nic.apply_ifcfg_update(&next).await.unwrap();
+        let changes = ifcfg.routes.lock().unwrap();
+        let mut expected = vec![
+            RouteChange::Remove(route.clone(), Some(old_source)),
+            RouteChange::Add(route.clone(), Some(new_source)),
+        ];
+        if cfg!(target_os = "linux") && !adding_owner {
+            expected.push(RouteChange::Add(route.clone(), Some(new_source)));
+        }
+        assert_eq!(*changes, expected, "adding_owner={adding_owner}");
+    }
+}
+
+#[tokio::test]
+async fn removing_route_preserves_its_old_cost_and_source_hint() {
+    let kept = SharedIpv4Route::new("10.90.4.0".parse().unwrap(), 24, Some(10));
+    let removed = SharedIpv4Route {
+        cost: Some(20),
+        ..kept.clone()
+    };
+    let source = "10.90.4.1".parse().unwrap();
+    let mut nic = SharedVirtualNic::new(virtual_nic_config(1500, None));
+    let ifcfg = RecordingIfConfiger::default();
+    set_ifcfg(&nic, ifcfg.clone()).await;
+    let mut claims = address_claims("10.90.4.1/24");
+    claims.ipv4_routes.extend([kept.clone(), removed.clone()]);
+    nic.ifcfg.apply_member_claims(MEMBER, claims.clone());
+    claims.ipv4_routes.remove(&removed);
+    let mut next = nic.ifcfg.clone();
+    next.apply_member_claims(MEMBER, claims);
+    nic.apply_ifcfg_update(&next).await.unwrap();
+    assert_eq!(
+        *ifcfg.routes.lock().unwrap(),
+        [RouteChange::Remove(removed, Some(source))]
+    );
+}
+
+fn create_member(
+    registry: &mut SharedVirtualNicRegistry,
+    dev_name: &str,
+    mtu: u32,
+    netns: Option<&str>,
+) -> SharedVirtualNicMember {
+    registry.create_member(
+        dev_name.to_owned(),
+        virtual_nic_config(mtu, netns),
+        uuid::Uuid::new_v4(),
+        Arc::new(Notify::new()),
+    )
+}
+
+#[test]
+fn registry_shares_devices_only_within_the_same_name_and_namespace() {
+    let mut registry = SharedVirtualNicRegistry::new();
+    let first = create_member(&mut registry, "et0", 1400, Some("net-a"));
+    for (name, netns, shared) in [
+        ("et0", Some("net-a"), true),
+        ("et0", Some("net-b"), false),
+        ("et1", Some("net-a"), false),
+        ("et0", None, false),
+    ] {
+        let next = create_member(&mut registry, name, 1300, netns);
+        assert_eq!(Arc::ptr_eq(&first.shared_nic, &next.shared_nic), shared);
+        assert_eq!(next.configured_mtu, 1300);
+    }
+    assert_eq!(first.configured_mtu, 1400);
+}
+
+#[test]
+fn registry_replaces_invalid_devices() {
+    let mut registry = SharedVirtualNicRegistry::new();
+    let first = create_member(&mut registry, "et0", 1500, None);
+    first.shared_nic.try_lock().unwrap().mark_invalid();
+    assert!(
+        registry
+            .get("et0", &virtual_nic_config(1500, None))
+            .is_none()
+    );
+    let next = create_member(&mut registry, "et0", 1500, None);
+    assert!(!Arc::ptr_eq(&first.shared_nic, &next.shared_nic));
+    assert!(Arc::ptr_eq(
+        &registry
+            .get("et0", &virtual_nic_config(1500, None))
+            .unwrap(),
+        &next.shared_nic,
+    ));
+}