@mentra/acs-meeting 3.2.0-dev.221 → 3.2.0-dev.223

package/android/src/main/java/com/mentra/acsmeeting/source/MeetingVideoSourceSpec.kt

@@ -0,0 +1,73 @@
+package com.mentra.acsmeeting.source
+
+/**
+ * Where the meeting's glasses video comes from, as sent by the host.
+ *
+ * A sealed type rather than a nullable URL because the two transports need different inputs and
+ * have no meaningful intersection: WHEP needs a URL it is given, while SoftAP produces one only
+ * after binding a listener. Modelling it as `whepUrl: String?` invites the exact bug this replaces
+ * — an empty string reaching the WHEP subscriber and failing several seconds later as an opaque
+ * HTTP error.
+ */
+sealed interface MeetingVideoSourceSpec {
+
+  val kind: SourceKind
+
+  /** Subscribe to a Cloudflare WHEP endpoint. */
+  data class Whep(val url: String) : MeetingVideoSourceSpec {
+    override val kind = SourceKind.WHEP
+  }
+
+  /**
+   * Serve a WHIP endpoint on the glasses hotspot.
+   *
+   * @param bindAddress the phone's own IPv4 on the hotspot. The orchestrator joins the network and
+   *   supplies this; it cannot be known before the join completes.
+   */
+  data class SoftAp(val bindAddress: String?) : MeetingVideoSourceSpec {
+    override val kind = SourceKind.SOFTAP
+  }
+
+  /** Locally generated frames, for the synthetic diagnostic arm. */
+  data object Synthetic : MeetingVideoSourceSpec {
+    override val kind = SourceKind.DIRECT
+  }
+
+  fun toConfig(): SourceConfig = when (this) {
+    is Whep -> SourceConfig(url, SourceKind.WHEP)
+    is SoftAp -> SourceConfig("", SourceKind.SOFTAP, bindAddress)
+    Synthetic -> SourceConfig("", SourceKind.DIRECT)
+  }
+
+  companion object {
+    const val TYPE_WHEP = "whep"
+    const val TYPE_SOFTAP = "softap"
+
+    /**
+     * Parses the `videoSource` map from the JS bridge, falling back to a bare `whepUrl` so a host
+     * that predates the union keeps working.
+     *
+     * Throws rather than defaulting. A malformed source must fail at the bridge, where the message
+     * names the field, instead of surfacing later as a call that joins and shows nothing.
+     */
+    fun parse(videoSource: Map<*, *>?, legacyWhepUrl: String?): MeetingVideoSourceSpec {
+      if (videoSource == null) {
+        val url = legacyWhepUrl?.trim().orEmpty()
+        require(url.isNotEmpty()) { "videoSource or whepUrl is required" }
+        return Whep(url)
+      }
+
+      return when (val type = (videoSource["type"] as? String)?.trim()?.lowercase()) {
+        TYPE_WHEP -> {
+          val url = (videoSource["url"] as? String)?.trim() ?: legacyWhepUrl?.trim().orEmpty()
+          require(url.isNotEmpty()) { "videoSource.url is required for a whep source" }
+          Whep(url)
+        }
+
+        TYPE_SOFTAP -> SoftAp((videoSource["bindAddress"] as? String)?.trim()?.ifEmpty { null })
+
+        else -> throw IllegalArgumentException("unsupported videoSource.type: $type")
+      }
+    }
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/source/SdpAdapter.kt

@@ -0,0 +1,17 @@
+package com.mentra.acsmeeting.source
+
+import org.webrtc.SdpObserver
+import org.webrtc.SessionDescription
+
+/**
+ * No-op [SdpObserver] so call sites override only the one callback they care about.
+ *
+ * Shared by the Cloudflare and SoftAP paths, which negotiate in opposite directions and therefore
+ * each ignore a different half of this interface.
+ */
+internal open class SdpAdapter : SdpObserver {
+  override fun onCreateSuccess(sdp: SessionDescription) {}
+  override fun onSetSuccess() {}
+  override fun onCreateFailure(error: String) {}
+  override fun onSetFailure(error: String) {}
+}

package/android/src/main/java/com/mentra/acsmeeting/source/SelectedIcePair.kt

@@ -0,0 +1,139 @@
+package com.mentra.acsmeeting.source
+
+import com.mentra.acsmeeting.network.Ipv4Prefix
+
+/**
+ * Reads the path media is *actually* taking out of a WebRTC stats sample.
+ *
+ * The SDP guard checks what each side offered. That is necessary and not sufficient: an answer can
+ * carry a perfectly good hotspot candidate and ICE can still select a different pair, at which point
+ * the SoftAP call is running over an interface that either cannot reach the glasses or defeats the
+ * whole point of the transport. The only honest question is which pair got nominated.
+ *
+ * ## Why the selection is followed rather than inferred
+ *
+ * This used to pick "a nominated succeeded pair, else any succeeded pair, else whichever pair has
+ * the most received bytes". None of those identify the current path. A succeeded pair is only a pair
+ * that once passed a connectivity check, and historical bytes belong to a pair that may have been
+ * replaced. Using it as acceptance evidence meant a run could be graded on a pair that was not
+ * carrying the call.
+ *
+ * The transport's `selectedCandidatePairId` is the specification's answer to exactly this question,
+ * so it is read and followed. When it is not available the verdict is [IcePathVerdict.Unknown] —
+ * insufficient evidence, never a pass.
+ *
+ * Kept free of `org.webrtc` types so the decision is unit testable; [LocalWhipIngestSource] adapts
+ * `RTCStatsReport` into these shapes.
+ */
+data class IceCandidatePairStats(
+  val id: String,
+  /** `succeeded`, `in-progress`, `failed`, … as libwebrtc spells it. */
+  val state: String?,
+  val nominated: Boolean,
+  val localCandidateId: String?,
+  val remoteCandidateId: String?,
+  val bytesReceived: Long,
+)
+
+data class IceCandidateStats(
+  val id: String,
+  val address: String?,
+  val candidateType: String?,
+)
+
+/** The transport entry, for the one field that names the pair in use. */
+data class IceTransportStats(val id: String, val selectedCandidatePairId: String?)
+
+sealed interface IcePathVerdict {
+  /**
+   * Media is on the network we joined.
+   *
+   * [pairId] and [iceGeneration] are carried so two samples can be compared as the same path. Byte
+   * growth across a pair change says nothing, and comparing it anyway is how an idle path could
+   * read as a flowing one.
+   */
+  data class OnHotspot(
+    val pairId: String,
+    val iceGeneration: Int,
+    val local: String,
+    val remote: String?,
+    val bytesReceived: Long,
+  ) : IcePathVerdict
+
+  /** A pair was selected and it is not on the hotspot. This is the silent failure worth killing. */
+  data class OffHotspot(val pairId: String, val local: String?, val prefix: String) : IcePathVerdict
+
+  /** Not enough information to judge. Never a pass, and never on its own a reason to fail a call. */
+  data class Unknown(val reason: String) : IcePathVerdict
+}
+
+object SelectedIcePair {
+
+  /**
+   * The pair the transport says is selected, or null with the reason it could not be identified.
+   *
+   * Deliberately no fallback. Every fallback that was here answered a different question than
+   * "which pair is carrying this call".
+   */
+  fun selected(
+    transports: List<IceTransportStats>,
+    pairs: List<IceCandidatePairStats>,
+  ): Result<IceCandidatePairStats> {
+    if (transports.isEmpty()) return Result.failure(Missing("no_transport_stats"))
+    val selectedId =
+      transports.firstNotNullOfOrNull { it.selectedCandidatePairId }
+        ?: return Result.failure(Missing("no_selected_pair"))
+    val pair =
+      pairs.firstOrNull { it.id == selectedId }
+        ?: return Result.failure(Missing("selected_pair_absent_from_report"))
+    return Result.success(pair)
+  }
+
+  /** Carries the reason a selection could not be identified, for the trace. */
+  class Missing(val reason: String) : Exception(reason)
+
+  fun verdict(
+    transports: List<IceTransportStats>,
+    pairs: List<IceCandidatePairStats>,
+    candidates: Map<String, IceCandidateStats>,
+    prefix: Ipv4Prefix?,
+    iceGeneration: Int,
+  ): IcePathVerdict {
+    val pair =
+      selected(transports, pairs).getOrElse { error ->
+        return IcePathVerdict.Unknown((error as? Missing)?.reason ?: "selection_failed")
+      }
+    // No prefix means the host could not describe the network it joined. Reporting that as
+    // "off hotspot" would fail healthy calls on any host whose LinkProperties read came back empty.
+    if (prefix == null) return IcePathVerdict.Unknown("no_scoped_prefix")
+    val local = pair.localCandidateId?.let { candidates[it] }?.address
+      ?: return IcePathVerdict.Unknown("no_local_candidate")
+    val remote = pair.remoteCandidateId?.let { candidates[it] }?.address
+    if (!prefix.contains(local)) return IcePathVerdict.OffHotspot(pair.id, local, prefix.toString())
+    return IcePathVerdict.OnHotspot(pair.id, iceGeneration, local, remote, pair.bytesReceived)
+  }
+
+  /** Outcome of comparing two samples. Only [Flow.Compared] says anything about media. */
+  sealed interface Flow {
+    data class Compared(val before: Long, val after: Long) : Flow {
+      val flowing: Boolean
+        get() = after > before
+    }
+
+    /** The samples are not the same path, so growth between them is not evidence either way. */
+    data class NotComparable(val reason: String) : Flow
+  }
+
+  /**
+   * Compare byte counters only when both samples are the same pair on the same ICE generation.
+   *
+   * The previous check compared two numbers with no pair identity at all, which a renomination or a
+   * session restart silently invalidated.
+   */
+  fun flow(first: IcePathVerdict, second: IcePathVerdict.OnHotspot): Flow {
+    val before = first as? IcePathVerdict.OnHotspot ?: return Flow.NotComparable("first_sample_unusable")
+    if (before.iceGeneration != second.iceGeneration) return Flow.NotComparable("ice_generation_changed")
+    if (before.pairId != second.pairId) return Flow.NotComparable("pair_changed")
+    return Flow.Compared(before.bytesReceived, second.bytesReceived)
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/source/SoftApIceDiagnosis.kt

@@ -0,0 +1,144 @@
+package com.mentra.acsmeeting.source
+
+import com.mentra.acsmeeting.network.Ipv4Prefix
+import com.mentra.acsmeeting.network.ScopedNetworkChangeDetector.PublishedEntry
+
+/**
+ * Separates the causes of "the answer carried no hotspot candidate".
+ *
+ * That single symptom has been produced on device by four different faults, and a coarse error code
+ * cannot tell them apart — which is how one of them was misattributed and "fixed" by a change that
+ * created the next. Each fault is distinguished by state that only exists at the moment of
+ * gathering, so it is captured there and reduced to a [Fault] rather than inferred from logs later:
+ *
+ *  - the hotspot address is not in the kernel's interface table, so nothing could have gathered it
+ *  - the address is there but the inventory libwebrtc holds does not contain the hotspot, or two
+ *    entries share a handle so one overwrote the other
+ *  - both are fine and still nothing was gathered, which leaves the socket bind
+ *  - candidates were gathered, none on the hotspot, so the wrong address is being advertised
+ *
+ * The [Fault] is a hypothesis narrowed by observation, not a proof; the raw fields travel with it so
+ * a run can be re-read without trusting the classifier.
+ */
+object SoftApIceDiagnosis {
+
+    /** The narrowed cause. Ordered from "cannot possibly work" to "worked, wrong answer". */
+    enum class Fault {
+        /** The scoped address is absent from `getifaddrs`. ICE has nothing to gather. */
+        MISSING_INTERFACE,
+
+        /** The hotspot is not in libwebrtc's inventory, or a handle collision dropped it. */
+        ERASED_ENTRY,
+
+        /** Address present, entry published, zero candidates: the socket could not bind. */
+        FAILED_BINDING,
+
+        /** Candidates gathered, none on the hotspot: a truthful port with the wrong address. */
+        WRONG_ADDRESS,
+
+        /** The observations do not narrow to one cause. */
+        INDETERMINATE,
+    }
+
+    /** A gathered candidate reduced to the two things that matter: its address and whose it is. */
+    data class CandidateFact(val address: String?, val owner: String?, val onHotspot: Boolean) {
+        override fun toString(): String = "${address ?: "?"}@${owner ?: "ABSENT"}"
+    }
+
+    data class Diagnosis(
+        val code: String,
+        val fault: Fault,
+        val scopedAddress: String?,
+        val scopedOwner: String?,
+        val scopedPrefix: Ipv4Prefix?,
+        val published: List<PublishedEntry>,
+        val candidates: List<CandidateFact>,
+    ) {
+        val scopedInTable: Boolean
+            get() = scopedOwner != null
+
+        val hotspotCandidates: List<CandidateFact>
+            get() = candidates.filter { it.onHotspot }
+
+        val offHotspot: List<CandidateFact>
+            get() = candidates.filterNot { it.onHotspot }
+
+        /**
+         * Flattened for [SoftApTrace][com.mentra.acsmeeting.trace.SoftApTrace] and the analyzer.
+         * Field names are the contract `softap-call-proof.mjs` reads, so they are stable.
+         */
+        fun fields(): Array<Pair<String, Any?>> =
+            arrayOf(
+                "code" to code,
+                "fault" to fault.name,
+                "scopedAddress" to (scopedAddress ?: "none"),
+                "scopedOwner" to (scopedOwner ?: "ABSENT"),
+                "scopedInTable" to scopedInTable,
+                "scopedPrefix" to (scopedPrefix?.toString() ?: "unknown"),
+                "publishedInventory" to
+                    published.joinToString(",").ifEmpty { "none" },
+                "publishedHotspot" to publishesHotspot(),
+                "handleCollision" to hasHandleCollision(),
+                "gathered" to candidates.size,
+                "hotspotCandidates" to hotspotCandidates.size,
+                "offHotspot" to offHotspot.joinToString(",").ifEmpty { "none" },
+            )
+
+        internal fun publishesHotspot(): Boolean =
+            scopedAddress != null && published.any { scopedAddress in it.addresses }
+
+        internal fun hasHandleCollision(): Boolean {
+            val handles = published.map { it.handle }
+            return handles.size != handles.distinct().size
+        }
+    }
+
+    /** Coarse label: nothing was gathered at all. */
+    const val CODE_NO_CANDIDATES = "no_candidates_gathered"
+
+    /** Coarse label: candidates exist, but every one is off the hotspot. */
+    const val CODE_ONLY_NON_HOTSPOT = "only_non_hotspot_candidates"
+
+    /**
+     * Classify a failed gathering pass.
+     *
+     * [scopedOwner] is the interface the kernel says owns [scopedAddress], normally from
+     * `NetworkFacts.ownerOf`; null means the address is not in the table.
+     */
+    fun diagnose(
+        scopedAddress: String?,
+        scopedOwner: String?,
+        scopedPrefix: Ipv4Prefix?,
+        published: List<PublishedEntry>,
+        candidates: List<CandidateFact>,
+    ): Diagnosis {
+        val code =
+            if (candidates.isEmpty()) CODE_NO_CANDIDATES else CODE_ONLY_NON_HOTSPOT
+        val partial =
+            Diagnosis(
+                code,
+                Fault.INDETERMINATE,
+                scopedAddress,
+                scopedOwner,
+                scopedPrefix,
+                published,
+                candidates,
+            )
+        return partial.copy(fault = classify(partial))
+    }
+
+    /**
+     * Order is load-bearing. A missing interface also looks like a failed bind, and an erased entry
+     * also looks like one, so the checks that rule those out have to come first — otherwise every
+     * run is blamed on the socket and the actual cause is never seen.
+     */
+    private fun classify(diagnosis: Diagnosis): Fault =
+        when {
+            diagnosis.scopedAddress == null -> Fault.MISSING_INTERFACE
+            !diagnosis.scopedInTable -> Fault.MISSING_INTERFACE
+            !diagnosis.publishesHotspot() || diagnosis.hasHandleCollision() -> Fault.ERASED_ENTRY
+            diagnosis.candidates.isEmpty() -> Fault.FAILED_BINDING
+            diagnosis.hotspotCandidates.isEmpty() -> Fault.WRONG_ADDRESS
+            else -> Fault.INDETERMINATE
+        }
+}

package/android/src/main/java/com/mentra/acsmeeting/source/SoftApIcePolicy.kt

@@ -0,0 +1,46 @@
+package com.mentra.acsmeeting.source
+
+import org.webrtc.PeerConnectionFactory
+
+/**
+ * Keeps the SoftAP peer's ICE on the hotspot.
+ *
+ * Answering with a cellular candidate is the quiet failure mode: the glasses have no route to the
+ * phone's mobile address, so ICE either fails after a full timeout or, worse, connects over some
+ * other shared network and the "direct" link is a fiction. Rather than hope ICE prefers the right
+ * interface, this removes the wrong ones from consideration entirely.
+ *
+ * [networkIgnoreMask] is a real libwebrtc knob — `PeerConnectionFactory.Options.networkIgnoreMask`
+ * — unlike the socket factory the design originally assumed existed. Combined with an empty ICE
+ * server list (so no srflx or relay candidate can be gathered at all) it leaves exactly one kind of
+ * candidate available: a Wi-Fi host candidate, which on a phone joined to the glasses hotspot is
+ * the hotspot address.
+ *
+ * Pure integer arithmetic, so it is unit tested rather than assumed.
+ */
+object SoftApIcePolicy {
+
+  /**
+   * Adapters the SoftAP peer must not gather on.
+   *
+   * Cellular is the dangerous one and the reason this exists. VPN is excluded because a corporate
+   * VPN on the phone would otherwise offer a tunnel address the glasses cannot reach. Loopback is
+   * excluded because it is never reachable from another device and only adds candidates to sift
+   * through. Ethernet is left available: a USB-tethered debug setup is legitimate, and it is not a
+   * route that can silently substitute for the hotspot.
+   */
+  fun networkIgnoreMask(): Int =
+    PeerConnectionFactory.Options.ADAPTER_TYPE_CELLULAR or
+      PeerConnectionFactory.Options.ADAPTER_TYPE_VPN or
+      PeerConnectionFactory.Options.ADAPTER_TYPE_LOOPBACK or
+      PeerConnectionFactory.Options.ADAPTER_TYPE_ETHERNET or
+      PeerConnectionFactory.Options.ADAPTER_TYPE_ANY
+
+  /** Whether [adapterType] is gathered on, given [mask]. Mirrors libwebrtc's own bitwise test. */
+  fun allowsAdapter(mask: Int, adapterType: Int): Boolean = (mask and adapterType) == 0
+
+  /** Factory options for the SoftAP peer. The network monitor stays on; we need it to see Wi-Fi. */
+  fun factoryOptions(): PeerConnectionFactory.Options = PeerConnectionFactory.Options().apply {
+    networkIgnoreMask = networkIgnoreMask()
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/source/SoftApSdpGuard.kt

@@ -0,0 +1,160 @@
+package com.mentra.acsmeeting.source
+
+import com.mentra.acsmeeting.network.Ipv4Prefix
+
+/**
+ * Checks that a SoftAP negotiation is actually staying on the SoftAP.
+ *
+ * The failure this exists to catch is silent. If the phone answers with a candidate on its cellular
+ * or home-Wi-Fi interface, or the glasses offer one, ICE may still connect — over a path that
+ * defeats the entire point of SoftAP and, in the cellular case, cannot work at all because the
+ * glasses have no route to it. Media either never flows or flows the long way while the logs look
+ * healthy. So both the offer we receive and the answer we send are asserted against the hotspot
+ * subnet before either is used.
+ *
+ * When the host can describe the network it joined, candidates are matched against that exact
+ * prefix — the real invariant is "on the network we joined", and RFC1918 is only a stand-in for it.
+ * Cellular carriers hand out 10/8 addresses, so the stand-in accepts precisely the interface this
+ * gate exists to reject. Without a prefix (no scoped handle) the check falls back to RFC1918, which
+ * deliberately matches `com.mentra.asg_client.io.streaming.config.IcePostPolicy` on the glasses. The
+ * two cannot share code across the module boundary, so
+ * [SoftApSdpGuardTest][com.mentra.acsmeeting.source.SoftApSdpGuardTest] pins the same cases the
+ * glasses-side test pins.
+ */
+object SoftApSdpGuard {
+
+  sealed interface Verdict {
+    /** At least one usable hotspot host candidate. [routableCandidates] is non-fatal, see below. */
+    data class Ok(val hostCandidates: List<String>, val routableCandidates: List<String>) : Verdict
+
+    data class Rejected(val code: String, val detail: String) : Verdict
+  }
+
+  /**
+   * No `typ host` candidate on the hotspot subnet, split by whether anything was gathered at all.
+   *
+   * One code covered both for a long time and it cost real debugging time: "nothing gathered" and
+   * "gathered the wrong address" are different faults with different fixes, and the single code
+   * made a run that had regressed from one to the other look unchanged.
+   * [SoftApIceDiagnosis] narrows them further; these two are the coarse label.
+   */
+  const val REASON_NO_CANDIDATES = SoftApIceDiagnosis.CODE_NO_CANDIDATES
+
+  /** See [REASON_NO_CANDIDATES]. Candidates exist, none of them on the hotspot. */
+  const val REASON_ONLY_NON_HOTSPOT = SoftApIceDiagnosis.CODE_ONLY_NON_HOTSPOT
+
+  /** Not SDP, or SDP with no media section. */
+  const val REASON_MALFORMED = "malformed_sdp"
+
+  /**
+   * Candidates that are not host candidates on a private subnet — srflx, relay, or a host candidate
+   * on a public address. In host-only mode none should appear; if they do, ICE could select one, so
+   * they are reported for logging. They are not rejected on the offer side: the glasses may run an
+   * older build that still gathers them, and dropping the call would be worse than a warning when a
+   * valid hotspot candidate is also present.
+   */
+  fun inspect(sdp: String?, prefix: Ipv4Prefix? = null): Verdict {
+    if (sdp.isNullOrBlank()) return Verdict.Rejected(REASON_MALFORMED, "empty sdp")
+    if (!sdp.contains("m=")) return Verdict.Rejected(REASON_MALFORMED, "no media section")
+
+    val candidates = candidateLines(sdp)
+    val host = candidates.filter { isSoftApHostCandidate(it, prefix) }
+    val routable = candidates.filterNot { isSoftApHostCandidate(it, prefix) }
+
+    if (host.isEmpty()) {
+      val scope = if (prefix != null) " (hotspot is $prefix)" else ""
+      return if (candidates.isEmpty()) {
+        Verdict.Rejected(REASON_NO_CANDIDATES, "no candidates at all$scope")
+      } else {
+        Verdict.Rejected(
+          REASON_ONLY_NON_HOTSPOT,
+          "only non-hotspot candidates$scope: ${routable.joinToString("; ")}",
+        )
+      }
+    }
+    return Verdict.Ok(host, routable)
+  }
+
+  /** Every `a=candidate:` attribute, with the `a=` prefix stripped. */
+  fun candidateLines(sdp: String): List<String> =
+    sdp.lineSequence()
+      .map { it.trim() }
+      .filter { it.startsWith("a=candidate:") }
+      .map { it.removePrefix("a=") }
+      .toList()
+
+  /**
+   * A `typ host` candidate on the hotspot: inside [prefix] when we know it, RFC1918 otherwise.
+   *
+   * mDNS-obfuscated candidates (`<uuid>.local`) are rejected on purpose. libwebrtc emits them to
+   * hide private addresses from remote peers, and the glasses cannot resolve them, so a negotiation
+   * that only offers those is broken however healthy it looks. Seeing this fire means the answering
+   * peer needs its mDNS obfuscation disabled.
+   */
+  fun isSoftApHostCandidate(candidate: String, prefix: Ipv4Prefix? = null): Boolean {
+    if (!candidate.contains("typ host")) return false
+    val onHotspot: (String) -> Boolean = if (prefix != null) prefix::contains else ::isPrivateIpv4
+    return candidate.split(Regex("\\s+")).any(onHotspot)
+  }
+
+  /**
+   * What [pinHostAddresses] did to one answer.
+   *
+   * [rewritten] is the host-candidate addresses that were off the hotspot and got replaced.
+   * Empty means the gathered SDP already advertised the scoped IP, so signaling and native state
+   * already match and nothing was edited.
+   */
+  data class PinResult(val sdp: String, val rewritten: List<String>)
+
+  /**
+   * Force every `typ host` candidate onto [scopedAddress].
+   *
+   * Needed because a bindable network handle marks the ICE sockets onto the SoftAP — which is what
+   * actually delivers UDP — and then libwebrtc substitutes the phone's default-route address into
+   * the candidate. The glasses have no route to that address. Replacing only the connection address
+   * of host lines (field 5, not `raddr`) keeps srflx/relay untouched and leaves a candidate that
+   * was already on the hotspot alone.
+   *
+   * The socket is still the marked one libwebrtc created. This only changes what the glasses are
+   * told to send to, so it stays honest only when that socket is on [scopedAddress]'s network.
+   */
+  fun pinHostAddresses(sdp: String, scopedAddress: String, prefix: Ipv4Prefix): PinResult {
+    val rewritten = mutableListOf<String>()
+    val lines = sdp.split(Regex("(?<=\\r?\\n)", RegexOption.MULTILINE))
+    val pinned =
+      lines.joinToString("") { line ->
+        val body = line.trimEnd('\r', '\n')
+        if (!body.contains("candidate:") || !body.contains("typ host")) return@joinToString line
+        val address = candidateAddress(body) ?: return@joinToString line
+        if (prefix.contains(address) || address == scopedAddress) return@joinToString line
+        rewritten += address
+        line.replaceFirst(address, scopedAddress)
+      }
+    return PinResult(pinned, rewritten)
+  }
+
+  /**
+   * The connection address of a candidate line, for attributing it to a real interface.
+   *
+   * Field 5 of `candidate:<foundation> <component> <transport> <priority> <address> <port> ...`,
+   * per RFC 5245. Read positionally rather than by scanning for anything dotted-quad-shaped: a
+   * `raddr` on an srflx line would otherwise win and point at the wrong interface.
+   */
+  fun candidateAddress(candidate: String): String? {
+    val fields = candidate.trim().removePrefix("a=").split(Regex("\\s+"))
+    return fields.getOrNull(4)?.takeIf { it.count { char -> char == '.' } == 3 }
+  }
+
+  /** RFC1918: 10/8, 172.16/12, 192.168/16. Rejects loopback, link-local and public addresses. */
+  fun isPrivateIpv4(token: String): Boolean {
+    val octets = token.split('.')
+    if (octets.size != 4) return false
+    val values = octets.map { it.toIntOrNull() ?: return false }
+    if (values.any { it < 0 || it > 255 }) return false
+    return when {
+      values[0] == 10 -> true
+      values[0] == 172 && values[1] in 16..31 -> true
+      else -> values[0] == 192 && values[1] == 168
+    }
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/source/TrackRegistry.kt

@@ -4,7 +4,9 @@ package com.mentra.acsmeeting.source
  * Dedupe WebRTC track attachments by native track id.
  * Three observer callbacks can deliver distinct Java wrappers of one track;
  * object identity cannot be used. [reset] is load-bearing: [CloudflareWhepSource.start]
- * calls stop first, and a stale claim set makes reconnect never attach a sink.
+ * calls stop first, and a stale claim set makes reconnect never attach a sink. SoftAP
+ * WHIP renegotiate reuses the same track id (`video0`); without a reset the new peer
+ * decodes frames that never reach the ACS sink.
  */
 class TrackRegistry {
   private val ids = mutableSetOf<String>()

package/android/src/main/java/com/mentra/acsmeeting/source/VideoSourceArm.kt

@@ -8,6 +8,8 @@ enum class DecoderMode { TEXTURE, BYTE_BUFFER }
 
 enum class PixelFormatArm { I420, NV12 }
 
+enum class OutgoingRateArm { ADVERTISE_REQUESTED, CLAMP_TO_SOFTWARE_CEILING }
+
 /**
  * Investigation arm. SYNTHETIC bypasses glasses, Cloudflare, WHEP and decode.
  * Ships as WHEP. Flip locally to run the experiment; do not commit SYNTHETIC.
@@ -33,6 +35,73 @@ object AcsInvestigation {
   val decoderMode = DecoderMode.TEXTURE
   val zeroCopy = false
   val pixelFormat = PixelFormatArm.I420
+
+  /**
+   * The rate we declare to ACS.
+   *
+   * CLAMP_TO_SOFTWARE_CEILING pins it to [VideoProfile.SOFTWARE_ENCODER_FPS]
+   * whenever the profile asks for more. It was the default on the strength of
+   * soaks that reported `codecName: "h264 sw"` alongside wire ≈ 8.8 fps, read as
+   * an encoder ceiling. Two things in the device logs say it was never the
+   * encoder.
+   *
+   * 720p15 and 540p15 both reported ~8.8 fps. 540p is 52% of the pixels of 720p,
+   * so a CPU-bound encoder would have been close to twice as fast at the smaller
+   * size; a limit that does not move with pixel count is not a pixel cost. And
+   * once [FramePacer] delivered a steady cadence, `wire` tracked what we handed
+   * ACS — 6.9 against 7.1 admitted — which is an encoder keeping up, not one
+   * saturating. Both of those soaks ran through a send path that could not hold a
+   * rate, so what they measured was our delivery.
+   *
+   * ADVERTISE_REQUESTED runs the configuration that was never actually tried:
+   * declare the profile's own fps and let the corrected pacer deliver it. Read
+   * the `P7 rate` verdict for what binds; it distinguishes an encoder that cannot
+   * keep up from a rate controller starving one that can, and those two want
+   * opposite fixes.
+   */
+  val outgoingRate = OutgoingRateArm.ADVERTISE_REQUESTED
+
+  /**
+   * libwebrtc's own `LS_INFO` stream during a SoftAP call.
+   *
+   * The one place that says which interfaces `BasicNetworkManager` kept, what adapter type it gave
+   * each one, and every `BindSocketToNetwork` result — the evidence that separated a hotspot the
+   * kernel had from one libwebrtc had erased. It is also loud, and it is the native stack's whole
+   * log, not ours.
+   *
+   * Flip to false once the SoftAP path is green on device. Keep the `NetworkFacts` stages either
+   * way: they are ours, bounded, and the thing that makes the next regression readable.
+   */
+  const val LIBWEBRTC_VERBOSE = true
+
+  /**
+   * How long to hold outgoing microphone PCM before the resampler, to align the wearer's voice
+   * with their video at the far end.
+   *
+   * Ships at 0, and 0 is not a placeholder: the audio and the video reach ACS over different
+   * transports (BLE LC3 versus SoftAP WebRTC) with different latencies, but *how* different is a
+   * receiver-side measurement, not something either side can infer. Deriving it from first-frame
+   * arrival times measures startup skew and would be wrong by however long the camera took to boot.
+   *
+   * Calibrate the ingest path with a clap in frame and read `AVSYNC clap audioLeadMs`. That is
+   * the offset the delay line can cancel. ACS/Teams jitter after ingest still needs a Teams
+   * recording. It is logged as `configuredDelayMs` and deliberately never reported as a measured
+   * offset.
+   */
+  const val acsAudioDelayMs = 0
+
+  /**
+   * Whether outgoing audio buffers carry a presentation timestamp.
+   *
+   * Whether ACS honours these for lip-sync on *raw* audio is unanswered — the SDK exposes the
+   * setter and documents nothing about the receiver. The only way to find out is to record the
+   * Teams receiver with this on and with it off and compare, so it has to be switchable; a constant
+   * true would leave two of the four measurement configurations unreachable.
+   *
+   * Defaults to true because the fallback is worse for an unrelated reason: a run of zero
+   * timestamps is what makes the Teams jitter buffer hold.
+   */
+  const val acsAudioTimestamps = true
 }
 
 data class SyntheticConfig(