@mentra/acs-meeting 3.2.0-dev.222 → 3.2.0-dev.225

package/android/src/main/java/com/mentra/acsmeeting/network/ScopedNetworkChangeDetector.kt

@@ -1,355 +0,0 @@
-package com.mentra.acsmeeting.network
-
-import android.content.Context
-import android.net.ConnectivityManager
-import com.mentra.acsmeeting.trace.SoftApTrace
-import java.net.Inet4Address
-import org.webrtc.NetworkChangeDetector
-import org.webrtc.NetworkMonitor
-import org.webrtc.NetworkMonitorAutoDetect
-
-/**
- * Adds the scoped SoftAP network to libwebrtc's Android network inventory.
- *
- * ## Why this exists
- *
- * The SoftAP [Network] is requested without `NET_CAPABILITY_INTERNET` so that Android keeps ACS on
- * cellular. But stock libwebrtc's `NetworkMonitorAutoDetect` registers a request for
- * *internet-capable* networks, so it never sees this one, and ICE therefore never gathers a host
- * candidate on the hotspot subnet. Holding a scoped `Network` object is not by itself enough to make
- * libwebrtc's internally-created UDP sockets use that interface — `PeerConnectionFactory.Options`
- * exposes `networkIgnoreMask` and `disableNetworkMonitor`, not a socket factory or a network handle.
- *
- * Injecting the interface into the inventory is the supported way through: it is the same technique
- * the glasses already use for their `ap0` tethering interface in
- * `HotspotAwareNetworkChangeDetector`.
- *
- * The monitor this touches is process-wide and the libwebrtc AAR is shared with LiveKit, so the
- * takeover is scoped and reversible; [ScopedNetworkObserver] documents and enforces that contract.
- *
- * ## Why the handle is the real [Network] handle
- *
- * Two device-proven behaviours, both captured, both fatal on their own:
- *
- * Handle `0` makes `BindSocketToNetwork` return `NOT_IMPLEMENTED`, so libwebrtc binds the socket to
- * `192.168.43.x` and advertises that address. The answer is truthful. ICE checks then sit on that
- * pair with `|CR-I|-|0|0|` forever: the OS accepted the bind, and even a send-only datagram, but
- * unmarked UDP on a non-default network is not delivered. 18:56 / 19:01 runs: ACS `CONNECTED`,
- * `ingest_host_candidate onHotspot=true`, then `ingest_no_first_frame` and the glasses reporting
- * `ICE did not connect`.
- *
- * A real handle makes `android_setsocknetwork` succeed, so the socket is marked onto the scoped
- * SoftAP and ICE packets can actually leave and return. libwebrtc then rebinds to `0.0.0.0` and
- * `UDPPort` substitutes the default-route (cellular) address into the candidate:
- *
- * ```
- * Allocate ports on wlan0
- * Port[...:Net[wlan0:192.168.43.x/24:Wifi:id=5]]: Gathered candidate: Cand[...:10.48.51.x:...:host...]
- * ```
- *
- * That advertised address is what the glasses would send to, and they have no route to it. So the
- * handle is real — sockets must be marked — and [SoftApSdpGuard.pinHostAddresses] rewrites the
- * answer the glasses see back onto the scoped IP. One inventory entry, so the handle cannot collide
- * with a decoy the way `0` did when we published more than one.
- *
- * ## Status
- *
- * Whether stock libwebrtc needs this at all is exactly what the Phase 0.5 feasibility gate
- * (`SoftApFeasibilityGateTest`) measures. The gate fired on-device (see [install]), so
- * [AcsMeetingModule][com.mentra.acsmeeting.AcsMeetingModule] installs it at module creation.
- */
-class ScopedNetworkChangeDetector
-internal constructor(
-    private val delegate: NetworkChangeDetector,
-    private val scopedNetworkSupplier: () -> ScopedInterface?,
-    private val observer: ScopedNetworkObserver? = null,
-) : NetworkChangeDetector {
-
-    constructor(
-        observer: NetworkChangeDetector.Observer,
-        context: Context,
-        scopedNetwork: ScopedSoftApNetwork,
-    ) : this(wire(observer, context) { resolveScopedInterface(context, scopedNetwork) })
-
-    private constructor(wired: Wired) : this(wired.delegate, wired.scoped, wired.observer)
-
-    /** The SoftAP interface as libwebrtc needs to see it. */
-    data class ScopedInterface(
-        val name: String,
-        val networkHandle: Long,
-        val ipv4Addresses: List<ByteArray>,
-    )
-
-    /**
-     * One inventory entry as libwebrtc was told about it.
-     *
-     * Kept as plain values rather than the webrtc type so [lastPublished] can outlive a gathering
-     * pass without pinning native objects, and so the diagnosis can be unit tested.
-     */
-    data class PublishedEntry(
-        val name: String,
-        val type: String,
-        val handle: Long,
-        val addresses: List<String>,
-    ) {
-        override fun toString(): String = "$name[$type]#$handle(${addresses.joinToString("/")})"
-    }
-
-    override fun getCurrentConnectionType(): NetworkChangeDetector.ConnectionType {
-        val delegateType = delegate.currentConnectionType
-        if (delegateType == NetworkChangeDetector.ConnectionType.CONNECTION_NONE &&
-            scopedNetworkSupplier() != null
-        ) {
-            return NetworkChangeDetector.ConnectionType.CONNECTION_WIFI
-        }
-        return delegateType
-    }
-
-    override fun supportNetworkCallback(): Boolean = delegate.supportNetworkCallback()
-
-    override fun getActiveNetworkList(): List<NetworkChangeDetector.NetworkInformation> {
-        val scoped = scopedNetworkSupplier()
-        val table = NetworkFacts.snapshot()
-        val stock = delegate.activeNetworkList
-
-        // The three views that have to agree, logged side by side. libwebrtc gathers from the
-        // kernel table; we only get to label the names in it. A scoped address missing from
-        // `ifaddrs`, or present under a different name than LinkProperties claims, is
-        // unrecoverable by any mask — and is invisible unless all three are printed together.
-        SoftApTrace.stage(
-            "softap_ifaddrs",
-            "gatherable" to NetworkFacts.render(NetworkFacts.gatherable(table)),
-            "all" to NetworkFacts.render(table),
-        )
-        SoftApTrace.stage(
-            "webrtc_stock_inventory",
-            "count" to stock.orEmpty().size,
-            "interfaces" to renderInventory(stock),
-        )
-        if (scoped != null) {
-            val address = scoped.ipv4Addresses.firstOrNull()?.let { formatIpv4(it) }
-            val owner = address?.let { NetworkFacts.ownerOf(it, table) }
-            // The smoking-gun check. `claimed` is what LinkProperties told us; `owner` is what the
-            // kernel says. If owner is null the address is not in the table at all and ICE cannot
-            // gather it; if they differ, our WIFI label is being applied to the wrong interface.
-            SoftApTrace.stage(
-                "softap_scoped_address_owner",
-                "address" to (address ?: "none"),
-                "claimed" to scoped.name,
-                "owner" to (owner ?: "ABSENT"),
-                "agrees" to (owner != null && owner == scoped.name),
-                "handle" to scoped.networkHandle,
-            )
-        }
-
-        val merged = mergeScopedNetwork(stock, scoped)
-        lastPublished = snapshotOf(merged)
-        SoftApTrace.stage(
-            "webrtc_network_inventory",
-            "count" to merged.size,
-            "interfaces" to lastPublished.joinToString(",") { it.toString() },
-        )
-        observer?.publish(merged)
-        return merged
-    }
-
-    override fun destroy() {
-        // Give the monitor back before the delegate goes away, otherwise the synthetic entry is
-        // the last thing libwebrtc was told about and every later connection inherits it.
-        observer?.restore()
-        delegate.destroy()
-    }
-
-    companion object {
-
-        /**
-         * What was last handed to libwebrtc, for the rejection diagnostics.
-         *
-         * A missing hotspot candidate has several causes and they are only separable by knowing
-         * whether the hotspot was in the inventory at gathering time, and whether any two entries
-         * shared a handle. Process-wide because the inventory is; read-only for callers.
-         */
-        @Volatile
-        @JvmStatic
-        var lastPublished: List<PublishedEntry> = emptyList()
-            private set
-
-        /** An inventory entry reduced to the fields a diagnosis or a trace needs. */
-        @JvmStatic
-        fun snapshotOf(
-            entries: List<NetworkChangeDetector.NetworkInformation>?,
-        ): List<PublishedEntry> =
-            entries.orEmpty().map { info ->
-                PublishedEntry(
-                    info.name,
-                    info.type.name,
-                    info.handle,
-                    info.ipAddresses.map { formatIpv4(it.address) },
-                )
-            }
-
-        /** `name[type]#handle(ips)` per entry — the shape both traces and diagnostics want. */
-        @JvmStatic
-        fun renderInventory(
-            entries: List<NetworkChangeDetector.NetworkInformation>?,
-        ): String = snapshotOf(entries).joinToString(",") { it.toString() }
-
-        /**
-         * The handle that tells libwebrtc "bind to the address, not to a network".
-         *
-         * `AndroidNetworkMonitor::BindSocketToNetwork` maps a zero handle to `NOT_IMPLEMENTED`,
-         * which is the only branch that leaves the socket bound to a real local address — and so
-         * the only branch that yields a truthful host candidate. Named because it is load-bearing,
-         * not a placeholder.
-         */
-        const val UNBINDABLE_HANDLE = 0L
-
-        /**
-         * Register this detector as the one libwebrtc builds when it starts monitoring.
-         *
-         * `NetworkMonitor` is process-wide and only consults the factory when it creates a
-         * detector — on the first `startMonitoring` and again after every `stopMonitoring` that
-         * drops the observer count to zero. So this must run before any `PeerConnectionFactory`
-         * exists, and [scopedNetworkSupplier] must resolve the *current* join at call time rather
-         * than capture one instance: the module recreates its [ScopedSoftApNetwork] across
-         * sessions.
-         *
-         * Idempotent. Feasibility gate result that made this necessary, on a Galaxy S25 /
-         * Android 16 with webrtc-sdk 137: `NetworkMonitorAutoDetect.networkToInfo` drops every
-         * network lacking `NET_CAPABILITY_INTERNET`, so the answer to the glasses' offer carried
-         * zero host candidates and the ingest returned WHIP 500 `no_softap_host_candidate`.
-         */
-        private data class Wired(
-            val delegate: NetworkChangeDetector,
-            val scoped: () -> ScopedInterface?,
-            val observer: ScopedNetworkObserver,
-        )
-
-        /**
-         * One observer is shared: AutoDetect's callbacks go through it, and so does the
-         * reconcile in [getActiveNetworkList]. Two instances would drop stock handles on one
-         * and publish the hotspot on the other, which is how the native list stayed dirty.
-         */
-        private fun wire(
-            downstream: NetworkChangeDetector.Observer,
-            context: Context,
-            scoped: () -> ScopedInterface?,
-        ): Wired {
-            val filter = ScopedNetworkObserver(downstream, scoped)
-            return Wired(NetworkMonitorAutoDetect(filter, context), scoped, filter)
-        }
-
-        @JvmStatic
-        fun install(scopedNetworkSupplier: () -> ScopedSoftApNetwork?) {
-            val monitor = NetworkMonitor.getInstance()
-            // A live detector was built by an earlier factory (or the stock one) and will not be
-            // replaced until monitoring restarts; say so in the trace so a missing host candidate
-            // after this point has an explanation.
-            SoftApTrace.stage(
-                "webrtc_network_detector_installed",
-                "monitorObservers" to monitor.numObservers,
-            )
-            monitor.setNetworkChangeDetectorFactory { observer, context ->
-                val wired =
-                    wire(observer, context) {
-                        scopedNetworkSupplier()?.let { resolveScopedInterface(context, it) }
-                    }
-                ScopedNetworkChangeDetector(wired.delegate, wired.scoped, wired.observer)
-            }
-        }
-
-        /**
-         * The SoftAP inventory: exactly one entry, the scoped network, typed Wi-Fi.
-         *
-         * Publishing decoy entries for the other interfaces was tried and is wrong. The theory was
-         * that an interface the monitor has never heard of comes back `ADAPTER_TYPE_UNKNOWN == 0`
-         * and `networkIgnoreMask and 0` is always `0`, making an omitted interface unmaskable. The
-         * device log says otherwise: an interface with no monitor entry is dropped from the network
-         * list entirely, not admitted as unknown. Here `rmnet_data0` vanishes the moment its entry
-         * is gone, while `lo` survives because libwebrtc types loopback from the interface flags
-         * and the mask drops it:
-         *
-         * ```
-         * Network connected: NetInfo[name wlan0; handle 0; type 2]
-         * Count of networks: 3
-         *   Net[wlan0:192.168.43.x/24:Wifi:id=5]
-         *   Net[lo:...:Loopback:id=2]
-         *   Net[lo:127.0.0.x/8:Loopback:id=1]
-         * ```
-         *
-         * Worse, the decoys were actively fatal. `AndroidNetworkMonitor` keys its networks by
-         * *handle*, and both the hotspot and the decoys have to use [UNBINDABLE_HANDLE], so each
-         * `onNetworkConnect` overwrote the previous one. Whichever arrived last was the only
-         * network the monitor knew, and when that was a masked decoy the answer carried no
-         * candidates at all:
-         *
-         * ```
-         * Network connected: NetInfo[name wlan0; handle 0; type 2]
-         * Network connected: NetInfo[name rmnet_data0; handle 0; type 4]
-         * Count of networks: 4 -> rmnet_data0, rmnet_data0, lo, lo   (wlan0 gone)
-         * ```
-         *
-         * One entry, therefore. The invariant stays structural — the only gatherable adapter is the
-         * scoped SoftAP — and it no longer depends on a handle being unique.
-         *
-         * When the hotspot shares an interface *name* with a stock address, the scoped entry wins
-         * and carries only its `LinkProperties` addresses. Type cannot separate two addresses on
-         * one name, so that residual case is caught by `SoftApSdpGuard` instead.
-         */
-        @JvmStatic
-        fun mergeScopedNetwork(
-            detected: List<NetworkChangeDetector.NetworkInformation>?,
-            scoped: ScopedInterface?,
-        ): List<NetworkChangeDetector.NetworkInformation> {
-            val hotspot = scoped?.let { toNetworkInformation(it) } ?: return detected.orEmpty()
-            return listOf(hotspot)
-        }
-
-        /** Dotted-quad for the inventory trace. */
-        @JvmStatic
-        fun formatIpv4(bytes: ByteArray): String =
-            bytes.joinToString(".") { (it.toInt() and 0xff).toString() }
-
-        /** Null when the interface has no address, which libwebrtc cannot use. */
-        @JvmStatic
-        fun toNetworkInformation(
-            scoped: ScopedInterface,
-        ): NetworkChangeDetector.NetworkInformation? {
-            if (scoped.ipv4Addresses.isEmpty()) return null
-            val addresses =
-                scoped.ipv4Addresses
-                    .map { NetworkChangeDetector.IPAddress(it) }
-                    .toTypedArray()
-            return NetworkChangeDetector.NetworkInformation(
-                scoped.name,
-                NetworkChangeDetector.ConnectionType.CONNECTION_WIFI,
-                NetworkChangeDetector.ConnectionType.CONNECTION_NONE,
-                // The real handle, so BindSocketToNetwork marks ICE sockets onto this Network.
-                // Handle 0 advertised the right address and then never completed a check; see the
-                // class doc. SoftApSdpGuard.pinHostAddresses puts the scoped IP back in the SDP.
-                scoped.networkHandle,
-                addresses,
-            )
-        }
-
-        /** Resolve the joined SoftAP into the interface libwebrtc should be told about. */
-        private fun resolveScopedInterface(
-            context: Context,
-            scopedNetwork: ScopedSoftApNetwork,
-        ): ScopedInterface? {
-            val network = scopedNetwork.network() ?: return null
-            val manager =
-                context.getSystemService(ConnectivityManager::class.java) ?: return null
-            val properties = manager.getLinkProperties(network) ?: return null
-            val interfaceName = properties.interfaceName ?: return null
-            // LinkProperties of *this* Network, not NetworkInterface.getByName. On a phone that
-            // kept internet Wi-Fi up, wlan0 can carry both 10.x and 192.168.43.x; getByName would
-            // hand ICE both, and it just picked the 10.x.
-            val addresses =
-                properties.linkAddresses
-                    .mapNotNull { (it.address as? Inet4Address)?.address }
-            if (addresses.isEmpty()) return null
-            return ScopedInterface(interfaceName, network.networkHandle, addresses)
-        }
-    }
-}

package/android/src/main/java/com/mentra/acsmeeting/network/ScopedNetworkError.kt

@@ -1,109 +0,0 @@
-package com.mentra.acsmeeting.network
-
-/**
- * Typed failures for a scoped SoftAP join.
- *
- * A denied local-network permission must surface as a distinct, immediate error rather than a
- * 30-second hang that looks like a flaky hotspot. `ACCESS_LOCAL_NETWORK` sits in the nearby-devices
- * group, so it is often already granted during development and easy to miss until a user without it
- * hits a silent timeout.
- */
-sealed class ScopedNetworkError(val code: String, message: String) : Exception(message) {
-
-    /** `ACCESS_LOCAL_NETWORK` (or the nearby-devices prerequisite) was not granted. */
-    class PermissionDenied(val permission: String) :
-        ScopedNetworkError(
-            CODE_PERMISSION_DENIED,
-            "Local network permission not granted: $permission",
-        )
-
-    /** No usable network arrived before the request timeout. */
-    class Timeout(val ssid: String, val timeoutMs: Int) :
-        ScopedNetworkError(CODE_TIMEOUT, "Timed out joining $ssid after ${timeoutMs}ms")
-
-    /**
-     * The framework reported it cannot provide this network at all.
-     *
-     * WifiNetworkSpecifier does not keep scanning for the request timeout. If the glasses AP is
-     * not in the current scan — or the user dismissed the system join sheet — this arrives in
-     * well under a second.
-     */
-    class Unavailable(val ssid: String) :
-        ScopedNetworkError(
-            CODE_UNAVAILABLE,
-            "Could not join $ssid (SSID not in scan, Wi-Fi off, or the system join prompt was dismissed)",
-        )
-
-    /** The network was joined and then went away mid-call. */
-    class Lost(val ssid: String) :
-        ScopedNetworkError(CODE_LOST, "Lost the connection to $ssid")
-
-    /** `requestNetwork` itself threw. */
-    class RequestFailed(val reason: String) :
-        ScopedNetworkError(CODE_REQUEST_FAILED, "Scoped network request failed: $reason")
-
-    /** Joined, but no IPv4 address was assigned, so nothing can bind to the link. */
-    class NoLocalAddress(val ssid: String) :
-        ScopedNetworkError(CODE_NO_LOCAL_ADDRESS, "Joined $ssid but no IPv4 address was assigned")
-
-    /**
-     * Joined, but the network never became usable for ICE: a callback never reported, or the
-     * address never appeared in the kernel's interface table.
-     *
-     * Failing here is deliberate. Proceeding produces an ICE answer with no hotspot candidate,
-     * which is the same symptom as several unrelated faults and cost real time to attribute.
-     */
-    class NotReady(val ssid: String, val missing: String) :
-        ScopedNetworkError(
-            CODE_NOT_READY,
-            "Joined $ssid but the network never became usable: still waiting for $missing",
-        )
-
-    /** Phone Wi-Fi radio is off. WifiNetworkSpecifier then fails as Unavailable in under a second. */
-    class WifiDisabled :
-        ScopedNetworkError(CODE_WIFI_DISABLED, "Phone Wi-Fi is off; turn it on before joining the glasses hotspot")
-
-    /**
-     * A VPN owns this app's UID. netd then refuses to bind our sockets to the hotspot network
-     * (`EPERM`), and the glasses' TCP handshake to the WHIP listener never completes because the
-     * reply path is captured by the tunnel. Verified on-device: a shell-UID listener on the same
-     * address accepts the glasses' connection while an app-UID listener times out. The scoped join
-     * itself succeeds, so without this check the failure only shows up ten seconds into the camera
-     * step as an opaque connect timeout.
-     */
-    class VpnCapturesApp :
-        ScopedNetworkError(
-            CODE_VPN_ACTIVE,
-            "A VPN is routing this app's traffic, so the glasses cannot reach the phone. " +
-                "Exclude Mentra from the VPN (split tunneling) or turn the VPN off, then retry",
-        )
-
-    companion object {
-        const val CODE_PERMISSION_DENIED = "SOFTAP_PERMISSION_DENIED"
-        const val CODE_TIMEOUT = "SOFTAP_JOIN_TIMEOUT"
-        const val CODE_UNAVAILABLE = "SOFTAP_UNAVAILABLE"
-        const val CODE_LOST = "SOFTAP_NETWORK_LOST"
-        const val CODE_REQUEST_FAILED = "SOFTAP_REQUEST_FAILED"
-        const val CODE_NO_LOCAL_ADDRESS = "SOFTAP_NO_LOCAL_ADDRESS"
-        const val CODE_NOT_READY = "SOFTAP_NETWORK_NOT_READY"
-        const val CODE_WIFI_DISABLED = "SOFTAP_WIFI_DISABLED"
-        const val CODE_VPN_ACTIVE = "SOFTAP_VPN_ACTIVE"
-
-        /** Map a terminal state-machine failure onto the typed error the call path reports. */
-        fun from(failure: ScopedNetworkState.Failure, ssid: String, timeoutMs: Int): ScopedNetworkError? =
-            when (failure) {
-                ScopedNetworkState.Failure.NONE -> null
-                ScopedNetworkState.Failure.TIMEOUT -> Timeout(ssid, timeoutMs)
-                ScopedNetworkState.Failure.UNAVAILABLE -> Unavailable(ssid)
-                ScopedNetworkState.Failure.LOST -> Lost(ssid)
-                ScopedNetworkState.Failure.PERMISSION_DENIED -> PermissionDenied(LOCAL_NETWORK_PERMISSION)
-                ScopedNetworkState.Failure.REQUEST_FAILED -> RequestFailed("requestNetwork threw")
-            }
-
-        /**
-         * Enforced on Android 17+ for apps targeting SDK 37+. Hosts targeting older SDKs
-         * retain implicit access through INTERNET and must not request this permission.
-         */
-        const val LOCAL_NETWORK_PERMISSION = "android.permission.ACCESS_LOCAL_NETWORK"
-    }
-}

package/android/src/main/java/com/mentra/acsmeeting/network/ScopedNetworkObserver.kt

@@ -1,160 +0,0 @@
-package com.mentra.acsmeeting.network
-
-import com.mentra.acsmeeting.trace.SoftApTrace
-import org.webrtc.NetworkChangeDetector
-
-/**
- * Owns libwebrtc's network state for as long as a scoped SoftAP is joined, and gives it back after.
- *
- * `getActiveNetworkList` is only a snapshot. libwebrtc's process-wide monitor also keeps every
- * network it has ever been told about through [onNetworkConnect]. AutoDetect is constructed with
- * this observer and reports cellular (and leftover home Wi-Fi) throughout the ACS join that happens
- * *before* ingest starts, and those handles stay in the native list. Gathering unions the snapshot
- * with that history, which is how a correct inventory still produced a lone cellular candidate.
- *
- * ## Ownership, not filtering
- *
- * The monitor is process-wide and the libwebrtc AAR is deliberately shared with LiveKit, so this
- * cannot simply mute callbacks and walk away. The contract is explicit:
- *
- *  - **While SoftAP is joined** this observer owns the monitor. Stock connect/disconnect callbacks
- *    are suppressed (but *recorded*), every handle outside the SoftAP inventory is disconnected,
- *    and exactly that inventory is connected.
- *  - **When the hotspot goes away** ownership is handed back by [restore]: the synthetic entry is
- *    disconnected and every stock network whose callback was suppressed is replayed, so a WHEP or
- *    LiveKit connection started afterwards sees real networks. Resuming pass-through alone is not
- *    enough — the networks it never heard about would stay missing until the OS happened to
- *    re-announce them.
- *
- * Restoration is driven from both directions, because either may come first: [publish] runs on
- * every inventory read, and each stock callback checks too, since after teardown the OS may be the
- * only thing still talking to us.
- */
-internal class ScopedNetworkObserver(
-    private val downstream: NetworkChangeDetector.Observer,
-    private val scoped: () -> ScopedNetworkChangeDetector.ScopedInterface?,
-) : NetworkChangeDetector.Observer() {
-
-    private val lock = Any()
-
-    /**
-     * Stock networks by handle, kept whole rather than as bare handles: replaying a suppressed
-     * network on teardown requires the [NetworkChangeDetector.NetworkInformation] verbatim.
-     */
-    private val stock = linkedMapOf<Long, NetworkChangeDetector.NetworkInformation>()
-
-    private val published = mutableSetOf<Long>()
-    private var lastSignature: String? = null
-
-    /** True while this observer has taken over the monitor and still owes a [restore]. */
-    private var owning = false
-
-    /**
-     * Make native state match [inventory] whenever SoftAP is up. A no-op when the snapshot has not
-     * changed, so [ScopedNetworkChangeDetector.getActiveNetworkList] can call this on every read.
-     */
-    fun publish(inventory: List<NetworkChangeDetector.NetworkInformation>) {
-        if (scoped() == null) {
-            restore()
-            return
-        }
-        val signature =
-            inventory.joinToString("|") { info ->
-                val ips =
-                    info.ipAddresses.joinToString("/") { address ->
-                        ScopedNetworkChangeDetector.formatIpv4(address.address)
-                    }
-                "${info.handle}:${info.name}:$ips"
-            }
-        synchronized(lock) {
-            if (signature == lastSignature) return
-            lastSignature = signature
-            owning = true
-
-            val keep = inventory.map { it.handle }.toSet()
-            // Stock handles announced *before* the join are the ones that poison gathering, so
-            // they are disconnected here even though their callbacks were never forwarded.
-            val dropped = (stock.keys + published).filterNot { it in keep }
-            dropped.forEach { handle -> downstream.onNetworkDisconnect(handle) }
-            published.clear()
-            inventory.forEach { info ->
-                published.add(info.handle)
-                downstream.onNetworkConnect(info)
-            }
-            SoftApTrace.stage(
-                "webrtc_network_reconciled",
-                "published" to inventory.size,
-                "dropped" to dropped.size,
-            )
-        }
-    }
-
-    /**
-     * Hand the monitor back: drop the synthetic entry, replay every suppressed stock network.
-     *
-     * Idempotent, and safe to call when this observer never took ownership.
-     */
-    fun restore() {
-        synchronized(lock) {
-            if (!owning) return
-            owning = false
-            lastSignature = null
-
-            val synthetic = published.toList()
-            published.clear()
-            synthetic.forEach { handle -> downstream.onNetworkDisconnect(handle) }
-            // Replay rather than wait: these networks exist, and the monitor was told they did not.
-            stock.values.forEach { info -> downstream.onNetworkConnect(info) }
-            SoftApTrace.stage(
-                "webrtc_network_restored",
-                "syntheticDropped" to synthetic.size,
-                "stockReplayed" to stock.size,
-            )
-        }
-    }
-
-    override fun onConnectionTypeChanged(connectionType: NetworkChangeDetector.ConnectionType) {
-        if (scoped() != null) {
-            downstream.onConnectionTypeChanged(NetworkChangeDetector.ConnectionType.CONNECTION_WIFI)
-            return
-        }
-        restore()
-        downstream.onConnectionTypeChanged(connectionType)
-    }
-
-    override fun onNetworkConnect(networkInfo: NetworkChangeDetector.NetworkInformation) {
-        if (scoped() != null) {
-            synchronized(lock) { stock[networkInfo.handle] = networkInfo }
-            SoftApTrace.stage(
-                "webrtc_stock_connect_suppressed",
-                "name" to networkInfo.name,
-                "handle" to networkInfo.handle,
-            )
-            return
-        }
-        // Restore before recording, so this network is forwarded once below rather than also
-        // arriving in the replay.
-        restore()
-        synchronized(lock) { stock[networkInfo.handle] = networkInfo }
-        downstream.onNetworkConnect(networkInfo)
-    }
-
-    override fun onNetworkDisconnect(networkHandle: Long) {
-        if (scoped() != null) {
-            synchronized(lock) { stock.remove(networkHandle) }
-            return
-        }
-        restore()
-        synchronized(lock) { stock.remove(networkHandle) }
-        downstream.onNetworkDisconnect(networkHandle)
-    }
-
-    override fun onNetworkPreference(
-        types: List<NetworkChangeDetector.ConnectionType>,
-        preference: Int,
-    ) {
-        if (scoped() != null) return
-        restore()
-        downstream.onNetworkPreference(types, preference)
-    }
-}