@mentra/glasses-media 3.2.1 → 3.3.0-beta.954

package/README.md

@@ -4,7 +4,7 @@ Native receivers, WHIP publishers and network helpers shared by the Mentra App.
 
 - Android: the existing `GlassesMediaSource`, local WHIP and WHEP receivers, scoped SoftAP networking, decoded I420/PCM delivery, and transport diagnostics moved here. The ACS session and raw outgoing streams remain in `acs-meeting`.
 - iOS: `DecodedGlassesMediaSource` delivers `CVPixelBuffer` video and interleaved PCM16. `LocalWhipIngestSource` answers the glasses' existing WHIP client; `WhepVideoSource` retains the cloud subscription path.
-- `GlassesHotspotNetwork` uses the same persistent `NEHotspotConfiguration` join as gallery transfers. Wi-Fi carries the glasses link; cellular carries the call. It verifies the joined SSID and `en0` address, reports network loss, and retains a cancelled join until the uncancellable system callback has been cleaned up.
+- `GlassesHotspotNetwork` owns hotspot association for OTA, gallery transfers and media. iPhone uses persistent `NEHotspotConfiguration`; iOS-on-Mac uses public CoreWLAN in the app process and the standard Location permission needed to identify Wi-Fi networks. Wi-Fi carries the glasses link; cellular carries the call. The owner verifies the requested SSID and actual Wi-Fi interface address, retains that interface for loss checks and ACS binding, and serializes network writers across consumers. Cancellation retains custody until blocking native work and cleanup finish. Cleanup preserves a network the user joined afterward; a failed release rejects and retains ownership for a later cleanup attempt.
 
 The publisher owns its outgoing encoders, audio policy, and destination. Receivers do not open the phone microphone or play the glasses microphone locally. iOS uses a receive-only audio device to drive decoded PCM delivery without changing the app's audio session.
 
@@ -53,6 +53,18 @@ The iOS internet publisher posts its offer on the first server-reflexive candida
 
 Android temporarily lifts the cellular process pin while creating the local WHIP listener, then restores it before starting the outgoing publisher. Otherwise the listener inherits the cellular socket mark and cannot reply to the glasses. The outgoing audio callback supplies its own PCM frame clock: WebRTC's external-recording mode does not pace callbacks and reports zero captured bytes, so the callback fills the entire buffer and waits for the next frame interval without opening the phone microphone.
 
-An attempt-specific ID isolates late callbacks and glasses status. Reconnect tears down the glasses publisher, both phone peers and hotspot before rebuilding against the same provisioned input. Three retries bound consecutive failures; a minute of stable streaming renews the retry budget. Last-subscriber stop cancels startup/backoff, awaits native cleanup and disables the hotspot. Failed cleanup retains ownership and can be retried by stop. BLE-unreachable stop/hotspot commands are deferred until reconnection. ACS and managed streaming share a hotspot reservation. Native media queues keep running when the UI is backgrounded; Android holds a partial wake lock and uses the engine's background timers for retry/readiness.
+An attempt-specific ID isolates late callbacks and glasses status. Reconnect tears down the glasses publisher, both phone peers and hotspot before rebuilding against the same provisioned input. Three retries bound consecutive failures; a minute of stable streaming renews the retry budget. Last-subscriber stop cancels startup/backoff, awaits native cleanup and disables the hotspot. Failed cleanup retains ownership and can be retried by stop. BLE-unreachable stop/hotspot commands are deferred until reconnection. OTA, Gallery, ACS and managed streaming share one hotspot reservation before BLE AP changes or native association. OTA, Gallery and managed relay retain it until their owned cleanup completes. ACS still has an older retirement policy that releases its JavaScript reservation after reporting an unconfirmed stop; native association custody remains retained on failure. Consolidating that ACS retirement is a separate qualification gate. A refused OTA or Gallery caller makes no AP or association changes. Native media queues keep running when the UI is backgrounded; Android holds a partial wake lock and uses the engine's background timers for retry/readiness.
 
 Device qualification for this outgoing pipeline must include Android and iPhone: audio/video playback on the provisioned WHEP URL, mute/video-only capture, last-subscriber stop, cancellation at each setup step, cellular/hotspot/BLE loss and recovery, repeated starts, screen-off/background operation and a sustained thermal/audio-sync run. Unit tests and platform compilation cover lifecycle/format contracts; they do not establish those hardware results.
+
+### Incoming OTA server and outgoing media clients
+
+Hotspot association verifies the glasses SSID and the Wi-Fi interface/address for
+both uses. Gallery and relay clients also wait for outgoing Local Network access
+by connecting to the glasses HTTP endpoint. OTA selects `incoming-server`: it
+serves already downloaded artifacts to connections initiated by the glasses, and
+its own listener must become ready before the app sends the OTA manifest URL.
+It does not depend on the Gallery HTTP server being available. Apple TN3179 lists
+accepting incoming TCP as an operation that does not require Local Network
+permission. This does not change outgoing Gallery/relay consent or the shared
+network ownership and teardown rules.

package/android/src/main/java/com/mentra/glassesmedia/source/StillPhotoInbox.kt

@@ -0,0 +1,50 @@
+package com.mentra.glassesmedia.source
+
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Stills the glasses upload to the phone's ingest listener during a Direct-link call.
+ *
+ * A still is only accepted for a request id the host registered with [expect] before it asked the
+ * glasses to shoot, so nothing else on the hotspot can push an image onto the outgoing Teams tile.
+ * Process-wide because the listener is rebuilt on every SoftAP recovery while the photo request
+ * belongs to the meeting.
+ */
+object StillPhotoInbox {
+
+  /** Largest still accepted. A full-size Mentra Live JPEG is 1-3 MB. */
+  const val MAX_BYTES = 16L * 1024 * 1024
+
+  private val pending = ConcurrentHashMap<String, CompletableFuture<ByteArray>>()
+
+  /** Register [requestId]. Replaces an earlier registration of the same id. */
+  fun expect(requestId: String): CompletableFuture<ByteArray> {
+    val future = CompletableFuture<ByteArray>()
+    pending.put(requestId, future)?.cancel(false)
+    return future
+  }
+
+  /** True when a POST for [requestId] should be read. */
+  fun isExpected(requestId: String): Boolean = pending[requestId]?.isDone == false
+
+  /** Hand over a still. False when nothing is waiting for [requestId]. */
+  fun deliver(requestId: String, bytes: ByteArray): Boolean {
+    val future = pending[requestId] ?: return false
+    return future.complete(bytes)
+  }
+
+  /** The registration for [requestId], if any. */
+  fun lookup(requestId: String): CompletableFuture<ByteArray>? = pending[requestId]
+
+  /** Forget [requestId]; a waiter sees cancellation. */
+  fun cancel(requestId: String) {
+    pending.remove(requestId)?.cancel(false)
+  }
+
+  /** Leave, End, or a new join. */
+  fun cancelAll() {
+    val all = pending.keys.toList()
+    all.forEach { cancel(it) }
+  }
+}

package/android/src/main/java/com/mentra/glassesmedia/source/WhipIngestProtocol.kt

@@ -43,11 +43,33 @@ object WhipIngestProtocol {
    */
   data class State(val activeSessionId: String? = null, val stopped: Boolean = false)
 
+  /**
+   * Base of the still endpoint on the same listener. During a call the glasses POST a full-size
+   * JPEG to `/photo/<requestId>` instead of the cloud, since their own hotspot has no internet.
+   */
+  const val STILL_PATH = "/photo"
+
   /** Where to point the `Location` header. WHIP clients DELETE against exactly this URL. */
   data class Endpoint(val host: String, val port: Int) {
     fun sessionUrl(sessionId: String) = "http://$host:$port$BASE_PATH/$sessionId"
+
+    /** Where the glasses upload the still for [requestId]. */
+    fun stillUrl(requestId: String) = "http://$host:$port$STILL_PATH/$requestId"
   }
 
+  private val STILL_ID = Regex("[A-Za-z0-9_-]{1,64}")
+
+  /** `/photo/<id>` -> `<id>` for a well-formed id; null for every other target. */
+  fun stillRequestIdOf(target: String): String? {
+    val path = target.substringBefore('?')
+    if (!path.startsWith("$STILL_PATH/")) return null
+    val id = path.removePrefix("$STILL_PATH/")
+    return id.takeIf { STILL_ID.matches(it) }
+  }
+
+  /** True for an id the still endpoint could ever accept, so the host can mint compatible ones. */
+  fun isValidStillRequestId(requestId: String): Boolean = STILL_ID.matches(requestId)
+
   data class Response(
     val status: Int,
     val reason: String,

package/android/src/main/java/com/mentra/glassesmedia/source/WhipIngestServer.kt

@@ -2,6 +2,7 @@ package com.mentra.glassesmedia.source
 
 import android.util.Log
 import com.mentra.glassesmedia.trace.SoftApTrace
+import java.io.BufferedInputStream
 import java.io.BufferedOutputStream
 import java.io.IOException
 import java.io.InputStream
@@ -231,12 +232,18 @@ class WhipIngestServer(
         socket.soTimeout = READ_TIMEOUT_MS
         val output = BufferedOutputStream(socket.getOutputStream())
         try {
-          val request = readRequest(socket.getInputStream())
-          if (request == null) {
+          val input = BufferedInputStream(socket.getInputStream())
+          val head = readHead(input)
+          if (head == null) {
             write(output, WhipIngestProtocol.Response(400, "Bad Request", body = "malformed request"))
             return
           }
-          write(output, handle(request))
+          val stillId = WhipIngestProtocol.stillRequestIdOf(head.target)
+          if (stillId != null) {
+            write(output, receiveStill(head, stillId, input))
+            return
+          }
+          write(output, handle(readBody(head, input)))
         } catch (error: Exception) {
           Log.w(TAG, "connection failed", error)
           runCatching {
@@ -336,6 +343,54 @@ class WhipIngestServer(
     }
   }
 
+  /**
+   * `POST /photo/<id>`: a full-size still from the glasses. Read only for an id the host is
+   * waiting on, so an unsolicited upload never costs the phone a multi-megabyte buffer.
+   */
+  private fun receiveStill(head: Head, requestId: String, input: InputStream): WhipIngestProtocol.Response {
+    if (!head.method.equals("POST", ignoreCase = true)) {
+      return WhipIngestProtocol.Response(405, "Method Not Allowed", mapOf("Allow" to "POST"), "POST a JPEG")
+    }
+    if (!StillPhotoInbox.isExpected(requestId)) {
+      SoftApTrace.stage("still_upload_unexpected", "requestId" to requestId)
+      return WhipIngestProtocol.Response(404, "Not Found", body = "no still pending for $requestId")
+    }
+    val length = head.contentLength
+    if (length == null || length <= 0) {
+      return WhipIngestProtocol.Response(411, "Length Required", body = "Content-Length required")
+    }
+    if (length > StillPhotoInbox.MAX_BYTES) {
+      return WhipIngestProtocol.Response(413, "Content Too Large", body = "still exceeds ${StillPhotoInbox.MAX_BYTES} bytes")
+    }
+    val startedAt = System.nanoTime() / 1_000_000
+    val bytes = ByteArray(length.toInt())
+    var read = 0
+    while (read < bytes.size) {
+      val count = input.read(bytes, read, bytes.size - read)
+      if (count < 0) break
+      read += count
+    }
+    if (read < bytes.size) {
+      SoftApTrace.failure("still_upload_truncated", "requestId" to requestId, "read" to read, "expected" to bytes.size)
+      return WhipIngestProtocol.Response(400, "Bad Request", body = "body ended after $read of ${bytes.size} bytes")
+    }
+    val delivered = StillPhotoInbox.deliver(requestId, bytes)
+    SoftApTrace.stage(
+      "still_upload_received",
+      "requestId" to requestId,
+      "bytes" to bytes.size,
+      "readMs" to (System.nanoTime() / 1_000_000 - startedAt),
+      "delivered" to delivered,
+    )
+    if (!delivered) return WhipIngestProtocol.Response(410, "Gone", body = "still for $requestId is no longer wanted")
+    return WhipIngestProtocol.Response(
+      200,
+      "OK",
+      mapOf("Content-Type" to "application/json"),
+      "{\"ok\":true,\"bytes\":${bytes.size}}",
+    )
+  }
+
   /** Frees the slot only if this session still holds it, so a newer publisher is not evicted. */
   private fun releaseSlot(sessionId: String) {
     synchronized(lock) {
@@ -362,21 +417,41 @@ class WhipIngestServer(
      */
     const val TOMBSTONE_MS = 3_000L
 
+    /** Request line and headers, read without consuming any of the body. */
+    internal class Head(
+      val method: String,
+      val target: String,
+      val contentType: String?,
+      val contentLength: Long?,
+    )
+
+    /** Longest request line or header line accepted; real ones are well under 200 bytes. */
+    private const val MAX_HEADER_LINE = 8 * 1024
+
     /**
      * Reads a request into [WhipIngestProtocol.Request]. Only `Content-Length` bodies are
      * supported: the glasses' WHIP client sends one, and `chunked` would be a silent 400 otherwise,
      * so it is rejected explicitly by the missing-length path below.
      */
     fun readRequest(stream: InputStream): WhipIngestProtocol.Request? {
-      val reader = stream.bufferedReader(Charsets.UTF_8)
+      val input = if (stream is BufferedInputStream) stream else BufferedInputStream(stream)
+      val head = readHead(input) ?: return null
+      return readBody(head, input)
+    }
+
+    /**
+     * Header parsing is byte-exact so the body that follows can be binary: the still endpoint
+     * reads a JPEG off the same stream, which a character reader would have buffered and decoded.
+     */
+    internal fun readHead(input: InputStream): Head? {
       val (method, target) = WhipIngestProtocol.parseRequestLine(
-        reader.readLine() ?: return null,
+        readLine(input) ?: return null,
       ) ?: return null
       SoftApTrace.stage("whip_request_line_read", "method" to method)
 
       val headers = mutableMapOf<String, String>()
       while (true) {
-        val line = reader.readLine() ?: break
+        val line = readLine(input) ?: break
         if (line.isEmpty()) break
         val separator = line.indexOf(':')
         if (separator <= 0) continue
@@ -386,24 +461,49 @@ class WhipIngestServer(
       val contentType = WhipIngestProtocol.headerValue(headers, "Content-Type")
       val contentLength = WhipIngestProtocol.headerValue(headers, "Content-Length")?.toLongOrNull()
       SoftApTrace.stage("whip_request_headers_read", "contentLength" to contentLength)
+      return Head(method, target, contentType, contentLength)
+    }
 
+    internal fun readBody(head: Head, input: InputStream): WhipIngestProtocol.Request {
+      val contentLength = head.contentLength
       // Do not read a body we have already decided to refuse. decide() checks the length first for
       // exactly this reason.
       if (contentLength == null || contentLength <= 0 ||
         contentLength > WhipIngestProtocol.MAX_BODY_BYTES
       ) {
-        return WhipIngestProtocol.Request(method, target, contentType, contentLength)
+        return WhipIngestProtocol.Request(head.method, head.target, head.contentType, contentLength)
       }
 
-      val body = CharArray(contentLength.toInt())
+      val body = ByteArray(contentLength.toInt())
       var read = 0
       while (read < body.size) {
-        val count = reader.read(body, read, body.size - read)
+        val count = input.read(body, read, body.size - read)
         if (count < 0) break
         read += count
         SoftApTrace.stage("whip_request_body_read", "read" to read, "expected" to body.size)
       }
-      return WhipIngestProtocol.Request(method, target, contentType, contentLength, String(body, 0, read))
+      return WhipIngestProtocol.Request(
+        head.method,
+        head.target,
+        head.contentType,
+        contentLength,
+        String(body, 0, read, Charsets.UTF_8),
+      )
+    }
+
+    /** One CRLF- or LF-terminated line, or null at end of stream before any byte. */
+    private fun readLine(input: InputStream): String? {
+      val line = java.io.ByteArrayOutputStream()
+      while (true) {
+        val next = input.read()
+        if (next < 0) return if (line.size() == 0) null else line.toString(Charsets.ISO_8859_1.name())
+        if (next == '\n'.code) break
+        line.write(next)
+        if (line.size() > MAX_HEADER_LINE) throw IOException("header line too long")
+      }
+      val bytes = line.toByteArray()
+      val end = if (bytes.isNotEmpty() && bytes.last() == '\r'.code.toByte()) bytes.size - 1 else bytes.size
+      return String(bytes, 0, end, Charsets.ISO_8859_1)
     }
 
     /** Convenience for tests and teardown paths that must not outlive the tombstone. */

package/index.d.ts

@@ -0,0 +1,11 @@
+/** Shared native association owner for the local glasses hotspot. */
+export const glassesHotspot: {
+  join(
+    id: string,
+    ssid: string,
+    password: string,
+    gateway?: string,
+    purpose?: "outgoing-client" | "incoming-server",
+  ): Promise<string>
+  leave(id: string): Promise<void>
+}

package/index.js

@@ -1 +1,10 @@
 // Native library. Media stays in native code; publishers consume decoded frames and PCM.
+
+// Load only when this transport is requested. Importing the package does not
+// start a native session or require Expo's application entry point.
+const native = () => require("expo-modules-core").requireNativeModule("MentraGlassesMediaRelay")
+export const glassesHotspot = Object.freeze({
+  join: (id, ssid, password, gateway, purpose = "outgoing-client") =>
+    native().joinLocalHotspot(id, ssid, password, gateway ?? null, purpose),
+  leave: (id) => native().leaveLocalHotspot(id),
+})

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotAccessPurpose.swift

@@ -0,0 +1,5 @@
+/// The traffic needed after joining the verified glasses Wi-Fi network.
+public enum HotspotAccessPurpose: String {
+    case outgoingClient = "outgoing-client"
+    case incomingServer = "incoming-server"
+}

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotInterfacePolicy.swift

@@ -0,0 +1,155 @@
+import Foundation
+
+/// One IPv4 address row reported by `getifaddrs`.
+public struct HotspotInterfaceAddress: Equatable {
+    public let name: String
+    public let isUp: Bool
+    public let ipv4: String
+
+    public init(name: String, isUp: Bool, ipv4: String) {
+        self.name = name
+        self.isUp = isUp
+        self.ipv4 = ipv4
+    }
+}
+
+/// One `getifaddrs` sample: every attached interface's kernel index (its `AF_LINK` row, present
+/// with or without an IPv4 address) and every IPv4 address row.
+public struct HotspotInterfaceSnapshot: Equatable {
+    public let links: [String: Int]
+    public let addresses: [HotspotInterfaceAddress]
+    /// Attached interfaces whose `AF_LINK` type is `IFT_ETHER`. Apple platforms report Wi-Fi and
+    /// wired Ethernet this way; cellular, VPN tunnel and loopback links have other types.
+    public let ethernetLinks: Set<String>
+
+    public init(links: [String: Int], addresses: [HotspotInterfaceAddress], ethernetLinks: Set<String> = []) {
+        self.links = links
+        self.addresses = addresses
+        self.ethernetLinks = ethernetLinks
+    }
+}
+
+/// Network framework's type for one interface on one evaluated path.
+public struct HotspotInterfaceReport: Equatable {
+    public let name: String
+    public let index: Int
+    public let isWifi: Bool
+
+    public init(name: String, index: Int, isWifi: Bool) {
+        self.name = name
+        self.index = index
+        self.isWifi = isWifi
+    }
+}
+
+/// The Wi-Fi interface carrying the glasses hotspot and the DHCP address it held when verified.
+public struct HotspotInterfaceBinding: Hashable {
+    public let interface: String
+    public let index: Int
+    public let address: String
+
+    public init(interface: String, index: Int, address: String) {
+        self.interface = interface
+        self.index = index
+        self.address = address
+    }
+}
+
+/// Wi-Fi identity learned during one hotspot session. Create a new value for every join.
+///
+/// A path's interface list describes routes, not hardware: after Wi-Fi moves to an AP without
+/// internet, both the default and the Wi-Fi-constrained path can omit it. An interface's type
+/// does not change while it stays attached, so a positive Wi-Fi report is kept for the same
+/// name and kernel index until that interface is detached or replaced. Omission from a later
+/// report is not evidence. Any non-Wi-Fi report for a name rejects it for the rest of the session.
+public struct HotspotWifiIdentity: Equatable {
+    public private(set) var trusted: [String: Int] = [:]
+    public private(set) var rejected: Set<String> = []
+    /// Trusted names later seen detached or replaced. A fresh report may trust the name again
+    /// for discovery, but an address verified before the change stays lost.
+    public private(set) var detached: Set<String> = []
+
+    public init() {}
+
+    public mutating func observe(_ reports: [HotspotInterfaceReport]) {
+        for report in reports where !report.isWifi {
+            rejected.insert(report.name)
+            trusted[report.name] = nil
+        }
+        for report in reports where report.isWifi && !report.name.isEmpty && report.index > 0 && !rejected.contains(report.name) {
+            // A new index means a different interface took the name; only this report vouches for it.
+            if let index = trusted[report.name], index != report.index { detached.insert(report.name) }
+            trusted[report.name] = report.index
+        }
+    }
+
+    /// Forget an interface that is no longer attached, or whose name now has another index.
+    /// Only a new positive report can re-establish it.
+    public mutating func observe(_ snapshot: HotspotInterfaceSnapshot) {
+        for (name, index) in trusted where snapshot.links[name] != index {
+            trusted[name] = nil
+            detached.insert(name)
+        }
+    }
+
+    /// Pin a binding chosen from hotspot client evidence (see `HotspotInterfacePolicy.select`)
+    /// as this session's Wi-Fi interface. It then ends exactly like a reported one.
+    public mutating func adopt(_ binding: HotspotInterfaceBinding) {
+        guard !rejected.contains(binding.interface), !detached.contains(binding.interface) else { return }
+        trusted[binding.interface] = binding.index
+    }
+}
+
+/// Wi-Fi is not always `en0`: a Mac can have built-in Ethernet on `en0` and Wi-Fi on `en1`.
+/// Identify the hotspot link by interface type and address, never by name or by the first
+/// private address, and keep that exact interface for the rest of the session.
+public enum HotspotInterfacePolicy {
+    /// The unique up IPv4 address, on an interface this session trusts as Wi-Fi and that is still
+    /// attached with the same index, that can be the hotspot client. With a BLE-reported gateway
+    /// it must be a valid client on that gateway's /24. Missing or ambiguous candidates return nil.
+    ///
+    /// A phone on cellular has no Wi-Fi path when the join starts, and after association iOS
+    /// leaves the internet-less glasses AP out of both paths, so no Wi-Fi report ever arrives.
+    /// Only when the session has no trusted Wi-Fi interface, the hotspot client address is the
+    /// evidence instead: the unique valid client of the BLE gateway's /24 on an attached
+    /// Ethernet-type link that no path has reported as non-Wi-Fi. Callers bind it only after the
+    /// glasses SSID matched, then require a connection from it to reach the gateway, and must
+    /// `adopt` it so the session pins that interface.
+    public static func select(snapshot: HotspotInterfaceSnapshot, identity: HotspotWifiIdentity,
+                              gateway: String?) -> HotspotInterfaceBinding?
+    {
+        if !identity.trusted.isEmpty {
+            return unique(snapshot, gateway: gateway) { identity.trusted[$0] }
+        }
+        guard let gateway else { return nil }
+        return unique(snapshot, gateway: gateway) { name in
+            guard snapshot.ethernetLinks.contains(name), !identity.rejected.contains(name),
+                  !identity.detached.contains(name) else { return nil }
+            return snapshot.links[name]
+        }
+    }
+
+    private static func unique(_ snapshot: HotspotInterfaceSnapshot, gateway: String?,
+                               index eligibleIndex: (String) -> Int?) -> HotspotInterfaceBinding?
+    {
+        let bindings = Set(snapshot.addresses.compactMap { row -> HotspotInterfaceBinding? in
+            guard let index = eligibleIndex(row.name), snapshot.links[row.name] == index,
+                  row.isUp, LocalMediaPolicy.isPrivate(row.ipv4) else { return nil }
+            if let gateway, !LocalMediaPolicy.isHotspotClientAddress(row.ipv4, gateway: gateway) { return nil }
+            return HotspotInterfaceBinding(interface: row.name, index: index, address: row.ipv4)
+        })
+        return bindings.count == 1 ? bindings.first : nil
+    }
+
+    /// A verified link remains usable only while the same attached interface is up with the same
+    /// address. Later path reports may omit it. Another interface acquiring that address, a
+    /// detach or replacement under the same name, or a non-Wi-Fi report ends it for the session.
+    /// Pass an identity that has already observed `snapshot`.
+    public static func isIntact(_ binding: HotspotInterfaceBinding, snapshot: HotspotInterfaceSnapshot,
+                                identity: HotspotWifiIdentity) -> Bool
+    {
+        guard identity.trusted[binding.interface] == binding.index, !identity.detached.contains(binding.interface),
+              snapshot.links[binding.interface] == binding.index else { return false }
+        return snapshot.addresses.contains { $0.name == binding.interface && $0.isUp && $0.ipv4 == binding.address }
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotJoinFailure.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+/// Explicit bridge facts; never forward native userInfo or arbitrary NSError descriptions.
+public struct HotspotJoinFailure {
+    public let code: String
+    public let message: String
+
+    public init(_ error: Error) {
+        if error is CancellationError || (error as? LocalMediaError)?.message == "Hotspot join cancelled" {
+            code = "ERR_HOTSPOT_CANCELLED"
+            message = "Hotspot join cancelled"
+        } else if let local = error as? LocalMediaError {
+            code = "ERR_HOTSPOT_JOIN"
+            // These messages are authored by the owned hotspot implementation, not NSError.
+            message = String(local.message.filter { !$0.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) }.prefix(512))
+        } else {
+            code = "ERR_HOTSPOT_NATIVE"
+            let native = error as NSError
+            let domain = native.domain.range(of: "^[A-Za-z0-9_.-]{1,128}$", options: .regularExpression) == nil ? "unavailable" : native.domain
+            message = "Hotspot join failed (\(domain), \(native.code))"
+        }
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotNetworkOwnership.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// One process-wide writer across OTA, gallery and native media sessions.
+/// Callers release only after native association and owned cleanup have ended.
+final class HotspotNetworkOwnership {
+    static let shared = HotspotNetworkOwnership()
+    private let lock = NSLock()
+    private var owner: UUID?
+
+    func acquire() -> UUID? {
+        lock.lock(); defer { lock.unlock() }
+        guard owner == nil else { return nil }
+        let token = UUID()
+        owner = token
+        return token
+    }
+
+    func release(_ token: UUID) {
+        lock.lock(); defer { lock.unlock() }
+        if owner == token { owner = nil }
+    }
+}