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

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

@@ -0,0 +1,355 @@
+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

@@ -0,0 +1,109 @@
+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

@@ -0,0 +1,160 @@
+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)
+    }
+}