@mentra/bluetooth-sdk 3.2.0-dev.195 → 3.2.0-dev.200

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/MentraLiveGattLifecycle.kt

@@ -0,0 +1,64 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/**
+ * Process-wide barrier between Mentra Live GATT teardown and the next connection attempt.
+ *
+ * Android can keep the physical link alive after a disconnect request until it delivers the
+ * disconnected callback. Starting another GATT session before that callback can reuse the old link,
+ * including its already-consumed MTU exchange. Callers queue connection work here and release it
+ * only after every outstanding teardown has completed or timed out. A newer deferred connection
+ * replaces the previous one so reconnect retries cannot start multiple GATT sessions together.
+ */
+internal class MentraLiveGattTeardownBarrier {
+    private val activeTeardowns = mutableSetOf<Long>()
+    private var waitingConnection: (() -> Unit)? = null
+    private var nextToken = 1L
+
+    @Synchronized
+    fun beginTeardown(): Long {
+        val token = nextToken++
+        activeTeardowns.add(token)
+        return token
+    }
+
+    /** Admission and execution are one operation; production callers all use the main looper. */
+    @Synchronized
+    fun runWhenIdle(work: () -> Unit) {
+        if (activeTeardowns.isEmpty()) work() else waitingConnection = work
+    }
+
+    @Synchronized
+    fun completeTeardown(token: Long) {
+        if (!activeTeardowns.remove(token) || activeTeardowns.isNotEmpty()) return
+        val ready = waitingConnection.also { waitingConnection = null }
+        ready?.invoke()
+    }
+}
+
+/** One-shot guard shared by the MTU callback and its watchdog fallback. */
+internal class MentraLiveMtuSetupGate {
+    private var nextToken = 1L
+    private var pendingToken: Long? = null
+
+    @Synchronized
+    fun begin(): Long {
+        val token = nextToken++
+        pendingToken = token
+        return token
+    }
+
+    /** Returns true exactly once for the current setup operation. */
+    @Synchronized
+    fun complete(token: Long): Boolean {
+        if (pendingToken != token) {
+            return false
+        }
+        pendingToken = null
+        return true
+    }
+
+    @Synchronized
+    fun cancel() {
+        pendingToken = null
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/SerializedGattCallback.kt

@@ -0,0 +1,76 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattDescriptor
+
+/**
+ * Binder callbacks only capture their arguments. Session validation and all callback effects run
+ * on the lifecycle owner, in the same queue as connect and teardown. Notification bytes must be
+ * copied before dispatch: Android reuses the mutable characteristic between notifications.
+ */
+internal abstract class SerializedGattCallback(
+    private val enqueue: (() -> Unit) -> Unit,
+    private val isCurrent: (BluetoothGatt) -> Boolean,
+) : BluetoothGattCallback() {
+    private fun dispatch(gatt: BluetoothGatt, work: () -> Unit) {
+        enqueue { if (isCurrent(gatt)) work() }
+    }
+
+    final override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) =
+        dispatch(gatt) { handleConnectionStateChange(gatt, status, newState) }
+
+    final override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) =
+        dispatch(gatt) { handleServicesDiscovered(gatt, status) }
+
+    final override fun onPhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) =
+        dispatch(gatt) { handlePhyUpdate(gatt, txPhy, rxPhy, status) }
+
+    final override fun onPhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) =
+        dispatch(gatt) { handlePhyRead(gatt, txPhy, rxPhy, status) }
+
+    final override fun onCharacteristicRead(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int,
+    ) = dispatch(gatt) { handleCharacteristicRead(gatt, characteristic, status) }
+
+    final override fun onReadRemoteRssi(gatt: BluetoothGatt, rssi: Int, status: Int) =
+        dispatch(gatt) { handleReadRemoteRssi(gatt, rssi, status) }
+
+    final override fun onCharacteristicWrite(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int,
+    ) = dispatch(gatt) { handleCharacteristicWrite(gatt, characteristic, status) }
+
+    @Suppress("DEPRECATION")
+    final override fun onCharacteristicChanged(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic,
+    ) {
+        val value = characteristic.value?.copyOf() ?: return
+        dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, value) }
+    }
+
+    final override fun onCharacteristicChanged(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray,
+    ) {
+        val snapshot = value.copyOf()
+        dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, snapshot) }
+    }
+
+    final override fun onDescriptorWrite(
+        gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int,
+    ) = dispatch(gatt) { handleDescriptorWrite(gatt, descriptor, status) }
+
+    final override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) =
+        dispatch(gatt) { handleMtuChanged(gatt, mtu, status) }
+
+    protected abstract fun handleConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int)
+    protected abstract fun handleServicesDiscovered(gatt: BluetoothGatt, status: Int)
+    protected abstract fun handlePhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int)
+    protected abstract fun handlePhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int)
+    protected abstract fun handleCharacteristicRead(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int)
+    protected abstract fun handleReadRemoteRssi(gatt: BluetoothGatt, rssi: Int, status: Int)
+    protected abstract fun handleCharacteristicWrite(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int)
+    protected abstract fun handleCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, data: ByteArray)
+    protected abstract fun handleDescriptorWrite(gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int)
+    protected abstract fun handleMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int)
+}

package/android/src/main/java/com/mentra/bluetoothsdk/status/DeviceStatus.kt

@@ -200,9 +200,8 @@ data class VersionInfoResult(
             systemTimeMs?.let { put("systemTimeMs", it) }
             put("otaVersionUrl", otaVersionUrl)
             put("appVersion", appVersion)
-            // Only when known. requestVersionInfo() resolves from ANY version_info chunk, and
-            // only chunk 1 carries package_name — emitting "" from a chunk-3 resolution would
-            // overwrite a known identity with "absent", which the OTA guard reads as stock.
+            // Only when known: per-chunk events may omit package identity. Emitting an empty
+            // value would overwrite a known identity, which the OTA guard uses to identify stock.
             if (packageName.isNotEmpty()) {
                 put("packageName", packageName)
             }

package/android/src/test/java/com/mentra/bluetoothsdk/VersionInfoBridgeTest.kt

@@ -0,0 +1,33 @@
+package com.mentra.bluetoothsdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [28])
+class VersionInfoBridgeTest {
+    @Test
+    fun wireMetadataSurvivesBridgeNormalizationAndCompletesOnlyAfterBothChunks() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val outcomes = mutableListOf<VersionInfoAccumulatorOutcome>()
+        val sink = Bridge.addEventSink { type, body ->
+            if (type == "version_info") outcomes.add(accumulator.accept(body))
+        }
+        val common = mapOf<String, Any>("request_id" to "request-1", "sid" to "asg-1", "chunkCount" to 2)
+        try {
+            Bridge.sendVersionInfo(common + mapOf("chunkIndex" to 1, "final" to false, "build_number" to "42"), "version_info_1")
+            Bridge.sendVersionInfo(common + mapOf("chunkIndex" to 2, "final" to true, "bes_fw_version" to "new"), "version_info_3")
+            assertEquals(VersionInfoAccumulatorOutcome.Waiting, outcomes[0])
+            val complete = outcomes[1] as VersionInfoAccumulatorOutcome.Complete
+            assertEquals("42", complete.result.buildNumber)
+            assertEquals("new", complete.result.besFirmwareVersion)
+            assertTrue(complete.result.toMap().keys.none { it.startsWith("_response") })
+        } finally {
+            Bridge.removeEventSink(sink)
+        }
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/VersionInfoResponseAccumulatorTest.kt

@@ -0,0 +1,169 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class VersionInfoResponseAccumulatorTest {
+    @Test
+    fun mergesCurrentChunksAndCompletesOnFirmwareChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+
+        assertThat(accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+
+        val complete =
+            accumulator.accept(
+                chunk(
+                    "version_info_3",
+                    "request-1",
+                    "buildNumber" to "",
+                    "besFirmwareVersion" to "26.8.27.0",
+                    "mtkFirmwareVersion" to "MentraLive_20260709",
+                )
+            ) as VersionInfoAccumulatorOutcome.Complete
+
+        assertThat(complete.result.buildNumber).isEqualTo("42")
+        assertThat(complete.result.besFirmwareVersion).isEqualTo("26.8.27.0")
+        assertThat(complete.result.mtkFirmwareVersion).isEqualTo("MentraLive_20260709")
+    }
+
+    @Test
+    fun ignoresMismatchedAndTrailingStaleChunks() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+
+        assertThat(accumulator.accept(chunk("version_info_1", "other", "buildNumber" to "old")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        assertThat(accumulator.accept(chunk("version_info_3", null, "besFirmwareVersion" to "stale")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+    }
+
+    @Test
+    fun doesNotMixCorrelatedAndUncorrelatedSequences() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42"))
+
+        assertThat(accumulator.accept(chunk("version_info_3", null, "besFirmwareVersion" to "stale")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+
+        val complete =
+            accumulator.accept(
+                chunk("version_info_3", "request-1", "besFirmwareVersion" to "current")
+            ) as VersionInfoAccumulatorOutcome.Complete
+        assertThat(complete.result.besFirmwareVersion).isEqualTo("current")
+    }
+
+    @Test
+    fun staleUncorrelatedResponsesCannotReplaceCorrelatedSequence() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42"))
+
+        assertThat(accumulator.accept(chunk("version_info_1", null, "buildNumber" to "stale")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        assertThat(accumulator.accept(chunk("version_info", null, "buildNumber" to "legacy")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+
+        val complete =
+            accumulator.accept(
+                chunk("version_info_3", "request-1", "besFirmwareVersion" to "current")
+            ) as VersionInfoAccumulatorOutcome.Complete
+        assertThat(complete.result.buildNumber).isEqualTo("42")
+        assertThat(complete.result.besFirmwareVersion).isEqualTo("current")
+    }
+
+    @Test
+    fun repeatedFirstChunkResetsRatherThanMixingResponses() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        accumulator.accept(chunk("version_info_1", null, "appVersion" to "old"))
+        accumulator.accept(chunk("version_info_1", null, "buildNumber" to "43"))
+
+        val complete = (accumulator.accept(chunk("version_info_3", null, "besFirmwareVersion" to "new"))
+            as VersionInfoAccumulatorOutcome.Complete).result
+
+        assertThat(complete.appVersion).isEmpty()
+        assertThat(complete.buildNumber).isEqualTo("43")
+        assertThat(complete.besFirmwareVersion).isEqualTo("new")
+    }
+
+    @Test
+    fun legacySingleMessageCompletesImmediately() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+
+        val complete =
+            accumulator.accept(chunk("version_info", null, "buildNumber" to "7"))
+                as VersionInfoAccumulatorOutcome.Complete
+
+        assertThat(complete.result.buildNumber).isEqualTo("7")
+    }
+
+    @Test
+    fun legacyFirstChunkDoesNotCompleteWithoutFinalChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        assertThat(accumulator.accept(chunk("version_info_1", null, "buildNumber" to "8")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+    }
+
+    @Test
+    fun modernFinalChunkWaitsForMissingFirstChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        assertThat(accumulator.accept(chunk("version_info_3", "request-1", "besFirmwareVersion" to "new")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+        val result = accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42"))
+            as VersionInfoAccumulatorOutcome.Complete
+        assertThat(result.result.buildNumber).isEqualTo("42")
+        assertThat(result.result.besFirmwareVersion).isEqualTo("new")
+    }
+
+    @Test
+    fun duplicateChunkDoesNotCountAsMissingChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val first = chunk("version_info_1", "request-1", "buildNumber" to "42")
+        assertThat(accumulator.accept(first)).isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+        assertThat(accumulator.accept(first)).isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+    }
+
+    @Test
+    fun rejectsMalformedModernMetadataAndMixedProcess() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val first = chunk("version_info_1", "request-1", "buildNumber" to "42")
+        for ((key, value) in listOf(
+            VersionInfoResponseAccumulator.RESPONSE_COUNT_KEY to 2.5,
+            VersionInfoResponseAccumulator.RESPONSE_INDEX_KEY to true,
+            VersionInfoResponseAccumulator.RESPONSE_FINAL_KEY to true,
+            VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY to "",
+        )) {
+            assertThat(accumulator.accept(first + (key to value))).isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        }
+        accumulator.accept(first)
+        val last = chunk("version_info_3", "request-1", "besFirmwareVersion" to "new")
+        assertThat(accumulator.accept(last + (VersionInfoResponseAccumulator.RESPONSE_SID_KEY to "process-2")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        assertThat(accumulator.accept(last)).isInstanceOf(VersionInfoAccumulatorOutcome.Complete::class.java)
+    }
+
+    @Test
+    fun correlatedResponseWithoutCompletenessMetadataCannotComplete() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val event = mapOf<String, Any>(
+            VersionInfoResponseAccumulator.RESPONSE_CHUNK_KEY to "version_info_3",
+            VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY to "request-1",
+        )
+        assertThat(accumulator.accept(event)).isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+    }
+
+    private fun chunk(
+        type: String,
+        requestId: String?,
+        vararg values: Pair<String, Any>,
+    ): Map<String, Any> =
+        buildMap {
+            put(VersionInfoResponseAccumulator.RESPONSE_CHUNK_KEY, type)
+            requestId?.let {
+                put(VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY, it)
+                put(VersionInfoResponseAccumulator.RESPONSE_INDEX_KEY, if (type == "version_info_1") 1 else 2)
+                put(VersionInfoResponseAccumulator.RESPONSE_COUNT_KEY, 2)
+                put(VersionInfoResponseAccumulator.RESPONSE_FINAL_KEY, type == "version_info_3")
+                put(VersionInfoResponseAccumulator.RESPONSE_SID_KEY, "process-1")
+            }
+            putAll(values)
+        }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/services/ForegroundServiceManifestTest.kt

@@ -0,0 +1,57 @@
+package com.mentra.bluetoothsdk.services
+
+import android.Manifest
+import android.content.ComponentName
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.location.LocationManager
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+import org.robolectric.util.ReflectionHelpers
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+class ForegroundServiceManifestTest {
+    @Test
+    fun `host manifest controls startup and resume even with all permissions granted`() {
+        val application = RuntimeEnvironment.getApplication()
+        val component = ComponentName(application, ForegroundService::class.java)
+        val info = application.packageManager.getServiceInfo(component, 0)
+        ReflectionHelpers.setField(info, "mForegroundServiceType", ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE)
+        shadowOf(application.packageManager).addOrUpdateService(info)
+        shadowOf(application).grantPermissions(
+            Manifest.permission.BLUETOOTH_CONNECT,
+            Manifest.permission.RECORD_AUDIO,
+            Manifest.permission.ACCESS_FINE_LOCATION,
+        )
+        shadowOf(application.getSystemService(LocationManager::class.java)).setLocationEnabled(true)
+
+        val controller = Robolectric.buildService(ForegroundService::class.java).create()
+        val service = controller.get()
+        try {
+            assertEquals(ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE, service.foregroundServiceType)
+            service.onStartCommand(Intent(ForegroundService.ACTION_REFRESH_TYPES), 0, 1)
+            assertEquals(ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE, service.foregroundServiceType)
+            service.onStartCommand(null, 0, 2)
+            assertEquals(ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE, service.foregroundServiceType)
+        } finally {
+            controller.destroy()
+        }
+    }
+
+    @Test
+    fun `default library manifest retains the MentraOS startup type`() {
+        val controller = Robolectric.buildService(ForegroundService::class.java).create()
+        try {
+            assertEquals(ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC, controller.get().foregroundServiceType)
+        } finally {
+            controller.destroy()
+        }
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/services/ForegroundServiceTypeTest.kt

@@ -6,6 +6,58 @@ import org.junit.Assert.assertTrue
 import org.junit.Test
 
 class ForegroundServiceTypeTest {
+    @Test
+    fun `connected-device-only host bootstraps without dataSync`() {
+        assertEquals(
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
+            ForegroundService.bootstrapServiceType(ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE),
+        )
+    }
+
+    @Test
+    fun `permissions cannot enable types excluded by the host manifest`() {
+        assertEquals(
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
+            ForegroundService.preferredServiceType(
+                hasConnectedDeviceAccess = true,
+                hasMicrophoneAccess = true,
+                hasLocationAccess = true,
+                declaredTypes = ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
+            ),
+        )
+    }
+
+    @Test
+    fun `restricted host fallback never adds undeclared dataSync`() {
+        assertEquals(
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
+            ForegroundService.preferredServiceType(
+                hasConnectedDeviceAccess = false,
+                hasMicrophoneAccess = false,
+                hasLocationAccess = false,
+                declaredTypes = ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
+            ),
+        )
+    }
+
+    @Test
+    fun `MentraOS retains all eligible long-running types`() {
+        assertEquals(
+            ForegroundService.DEFAULT_SERVICE_TYPES and
+                    ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC.inv(),
+            ForegroundService.preferredServiceType(
+                hasConnectedDeviceAccess = true,
+                hasMicrophoneAccess = true,
+                hasLocationAccess = true,
+            ),
+        )
+    }
+
+    @Test(expected = IllegalArgumentException::class)
+    fun `host without a valid bootstrap type fails explicitly`() {
+        ForegroundService.bootstrapServiceType(ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION)
+    }
+
     @Test
     fun `bootstrap starts as dataSync`() {
         assertEquals(

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/MentraLiveGattCallbackTest.kt

@@ -0,0 +1,94 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattDescriptor
+import java.util.UUID
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [28])
+class MentraLiveGattCallbackTest {
+    private fun gatt(): BluetoothGatt =
+        BluetoothAdapter.getDefaultAdapter().getRemoteDevice("AA:BB:CC:DD:EE:FF")
+            .connectGatt(RuntimeEnvironment.getApplication(), false, object : BluetoothGattCallback() {})
+
+    private class RecordingCallback(
+        enqueue: (() -> Unit) -> Unit,
+        isCurrent: (BluetoothGatt) -> Boolean = { true },
+    ) : SerializedGattCallback(enqueue, isCurrent) {
+        val events = mutableListOf<String>()
+        val packets = mutableListOf<ByteArray>()
+        override fun handleConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) { events.add("connection") }
+        override fun handleServicesDiscovered(gatt: BluetoothGatt, status: Int) { events.add("services") }
+        override fun handlePhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) { events.add("phyUpdate") }
+        override fun handlePhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) { events.add("phyRead") }
+        override fun handleCharacteristicRead(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int) { events.add("read") }
+        override fun handleReadRemoteRssi(gatt: BluetoothGatt, rssi: Int, status: Int) { events.add("rssi") }
+        override fun handleCharacteristicWrite(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int) { events.add("write") }
+        override fun handleCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, data: ByteArray) { packets.add(data) }
+        override fun handleDescriptorWrite(gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int) { events.add("descriptor") }
+        override fun handleMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) { events.add("mtu") }
+    }
+
+    @Test
+    fun `all callbacks defer effects until the lifecycle owner executes them`() {
+        val queue = ArrayDeque<() -> Unit>()
+        val callback = RecordingCallback({ work -> queue.addLast(work) })
+        val gatt = gatt()
+        val characteristic = BluetoothGattCharacteristic(UUID.randomUUID(), 0, 0)
+        val descriptor = BluetoothGattDescriptor(UUID.randomUUID(), 0)
+        callback.onConnectionStateChange(gatt, 0, 2)
+        callback.onServicesDiscovered(gatt, 0)
+        callback.onPhyUpdate(gatt, 1, 1, 0)
+        callback.onPhyRead(gatt, 1, 1, 0)
+        callback.onCharacteristicRead(gatt, characteristic, 0)
+        callback.onReadRemoteRssi(gatt, -50, 0)
+        callback.onCharacteristicWrite(gatt, characteristic, 0)
+        callback.onDescriptorWrite(gatt, descriptor, 0)
+        callback.onMtuChanged(gatt, 512, 0)
+        assertEquals(emptyList<String>(), callback.events)
+        while (queue.isNotEmpty()) queue.removeFirst().invoke()
+        assertEquals(listOf("connection", "services", "phyUpdate", "phyRead", "read", "rssi", "write", "descriptor", "mtu"), callback.events)
+    }
+
+    @Test
+    @Suppress("DEPRECATION")
+    fun `queued notifications retain their own bytes when Android reuses characteristic`() {
+        val queue = ArrayDeque<() -> Unit>()
+        val callback = RecordingCallback({ work -> queue.addLast(work) })
+        val gatt = gatt()
+        val characteristic = BluetoothGattCharacteristic(UUID.randomUUID(), 0, 0)
+        val buffer = byteArrayOf(1, 2)
+        characteristic.value = buffer
+        callback.onCharacteristicChanged(gatt, characteristic)
+        buffer[0] = 3
+        callback.onCharacteristicChanged(gatt, characteristic)
+        buffer[0] = 4
+        while (queue.isNotEmpty()) queue.removeFirst().invoke()
+        assertArrayEquals(byteArrayOf(1, 2), callback.packets[0])
+        assertArrayEquals(byteArrayOf(3, 2), callback.packets[1])
+    }
+
+    @Test
+    fun `replacement invalidates callbacks already waiting on the lifecycle queue`() {
+        val queue = ArrayDeque<() -> Unit>()
+        var epoch = 1
+        val callback = RecordingCallback({ work -> queue.addLast(work) }, { epoch == 1 })
+        val gatt = gatt()
+        callback.onConnectionStateChange(gatt, 0, 0)
+        callback.onServicesDiscovered(gatt, 0)
+        callback.onMtuChanged(gatt, 512, 0)
+        epoch = 2
+        while (queue.isNotEmpty()) queue.removeFirst().invoke()
+        assertEquals(emptyList<String>(), callback.events)
+    }
+}