@mentra/bluetooth-sdk 3.3.0-dev.316 → 3.3.0-dev.320

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

@@ -0,0 +1,270 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class NimoCanvasSessionTest {
+  private val frameA = byteArrayOf(0, 0, 1)
+  private val frameB = byteArrayOf(1, 0, 1, 1)
+  private val frameC = byteArrayOf(2, 0, 1, 2)
+  private fun send(actions: List<NimoCanvasSession.Action>): NimoCanvasSession.Action.Send =
+    actions.single() as NimoCanvasSession.Action.Send
+  private fun success(session: NimoCanvasSession, key: Int) = session.response(key,
+    if (key == 4) byteArrayOf(0, 0xFD.toByte(), 0, 0, 0) else byteArrayOf(0, 0xFD.toByte()))
+  private fun launched(session: NimoCanvasSession): NimoCanvasSession.Action.Send {
+    assertTrue(session.offer(frameA, "one:1").isEmpty())
+    assertEquals(1, send(session.readiness(true)).key)
+    return send(success(session, 1))
+  }
+
+  @Test fun launchAckPrecedesUpdateAndLatestOfferWins() {
+    val session = NimoCanvasSession()
+    session.readiness(true)
+    assertEquals(1, send(session.offer(frameA, "one:1")).key)
+    assertTrue(session.offer(frameB, "one:1").isEmpty())
+    assertTrue(session.offer(frameC, "one:1").isEmpty())
+    val update = send(success(session, 1))
+    assertEquals(4, update.key)
+    assertArrayEquals(frameC, update.frame)
+  }
+
+  @Test fun inflightUpdatesCoalesceAndDedupUsesActualBytes() {
+    val session = NimoCanvasSession()
+    launched(session)
+    session.offer(frameB, "one:1")
+    session.offer(frameC, "one:1")
+    assertArrayEquals(frameC, send(success(session, 4)).frame)
+    assertTrue(success(session, 4).isEmpty())
+    assertTrue(session.offer(frameC.copyOf(), "one:1").isEmpty())
+    assertArrayEquals(frameB, send(session.offer(frameB, "one:1")).frame)
+  }
+
+  @Test fun dedupDoesNotOverrideReversionWhileUpdateIsInFlight() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+    session.offer(frameB, "one:1")
+    session.offer(frameA, "one:1")
+    assertArrayEquals(frameA, send(success(session, 4)).frame)
+  }
+
+  @Test fun replayEpochAndReconnectForceAcceptedFrameAgain() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+    assertEquals(4, send(session.offer(frameA, "one:1", force = true)).key)
+    success(session, 4)
+    assertEquals(4, send(session.offer(frameA, "one:2")).key)
+    success(session, 4)
+    session.disconnected()
+    assertEquals(1, send(session.readiness(true)).key)
+    assertEquals(4, send(success(session, 1)).key)
+  }
+
+  @Test fun malformedSuccessAndWrongCommandCannotAcknowledgeLaunch() {
+    val session = NimoCanvasSession()
+    session.offer(frameA, "one:1"); val launch = send(session.readiness(true))
+    assertTrue(session.response(1, byteArrayOf(0)).isEmpty())
+    assertTrue(session.response(1, byteArrayOf(0, 0x04)).isEmpty())
+    assertTrue(session.response(4, byteArrayOf(0, 0xFD.toByte(), 0, 0, 0)).isEmpty())
+    assertTrue(session.timeout(launch.ticket).single() is NimoCanvasSession.Action.Reconnect)
+  }
+
+  @Test fun timeoutRequiresFreshTransportBeforeLateAckCanDoAnything() {
+    val session = NimoCanvasSession()
+    val update = launched(session)
+    assertTrue(session.timeout(update.ticket).single() is NimoCanvasSession.Action.Reconnect)
+    assertTrue(success(session, 4).isEmpty())
+    assertTrue(session.offer(frameB, "one:1").isEmpty())
+    session.disconnected()
+    assertEquals(1, send(session.readiness(true)).key)
+    assertTrue(session.timeout(update.ticket).isEmpty())
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+  }
+
+  @Test fun unsupportedAndInvalidDoNotRetryUnchangedFrame() {
+    for (status in listOf(1, 5, 6)) {
+      val session = NimoCanvasSession()
+      launched(session)
+      assertTrue(session.response(4, byteArrayOf(status.toByte())).single() is NimoCanvasSession.Action.Rejected)
+      assertTrue(session.offer(frameA, "one:1").isEmpty())
+      assertTrue(session.offer(frameA, "one:2", force = true).isEmpty())
+      assertArrayEquals(frameB, send(session.offer(frameB, "one:1")).frame)
+    }
+  }
+
+  @Test fun failedLaunchDoesNotRetryIdenticalLaunchForChangingCaptions() {
+    for (status in listOf(1, 5, 6)) {
+      val session = NimoCanvasSession()
+      session.offer(frameA, "one:1"); session.readiness(true)
+      assertTrue(session.response(1, byteArrayOf(status.toByte())).single() is NimoCanvasSession.Action.Rejected)
+      assertTrue(session.offer(frameB, "one:1").isEmpty())
+      assertTrue(session.offer(frameC, "one:2", true).isEmpty())
+      session.disconnected()
+      assertEquals(1, send(session.readiness(true)).key)
+    }
+  }
+
+  @Test fun readinessErrorWaitsForExplicitReadySignal() {
+    val session = NimoCanvasSession()
+    launched(session)
+    assertTrue(session.response(4, byteArrayOf(7)).single() is NimoCanvasSession.Action.Rejected)
+    assertTrue(session.offer(frameB, "one:1").isEmpty())
+    assertTrue(session.readiness(true).isEmpty())
+    assertTrue(session.readiness(false).isEmpty())
+    assertEquals(1, send(session.readiness(true)).key)
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+  }
+
+  @Test fun freshConfirmedReadinessReleasesNotReadyWithoutFalseEdge() {
+    for (key in listOf(1, 4)) {
+      val session = NimoCanvasSession()
+      session.offer(frameA, "one:1"); session.readiness(true)
+      if (key == 4) success(session, 1)
+      assertTrue(session.response(key, byteArrayOf(7)).single() is NimoCanvasSession.Action.Rejected)
+      assertTrue(session.offer(frameB, "one:1").isEmpty())
+      assertTrue("cached true must not release status 7", session.readiness(true).isEmpty())
+      assertEquals(1, send(session.confirmedReadiness(true)).key)
+      assertArrayEquals(frameB, send(success(session, 1)).frame)
+    }
+  }
+
+  @Test fun confirmedNotReadyStaysBlockedUntilConfirmedReady() {
+    val session = NimoCanvasSession()
+    launched(session)
+    session.response(4, byteArrayOf(7))
+    assertTrue(session.confirmedReadiness(false).isEmpty())
+    assertTrue(session.offer(frameB, "one:1").isEmpty())
+    assertEquals(1, send(session.confirmedReadiness(true)).key)
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+  }
+
+  @Test fun repeatedReadyButRejectedLaunchHasBoundedRecovery() {
+    val session = NimoCanvasSession()
+    session.offer(frameA, "one:1"); session.readiness(true)
+    repeat(3) {
+      session.response(1, byteArrayOf(7))
+      assertEquals(1, send(session.confirmedReadiness(true)).key)
+      assertTrue("duplicate heartbeat cannot overlap Launch", session.confirmedReadiness(true).isEmpty())
+    }
+    session.response(1, byteArrayOf(7))
+    repeat(5) { assertTrue("ready-only recovery must stop after three retries", session.confirmedReadiness(true).isEmpty()) }
+    session.offer(frameB, "one:2", true)
+    assertTrue(session.confirmedReadiness(true).isEmpty())
+    session.readiness(false)
+    assertEquals(1, send(session.confirmedReadiness(true)).key)
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+    success(session, 4)
+    session.offer(frameC, "one:2")
+    session.response(4, byteArrayOf(7))
+    assertEquals(1, send(session.confirmedReadiness(true)).key)
+  }
+
+  @Test fun confirmedReadyDoesNotUnlockRejectedLaunchOrDeviceLock() {
+    for (status in listOf(1, 5, 6, 8)) {
+      val session = NimoCanvasSession()
+      session.offer(frameA, "one:1"); session.readiness(true)
+      session.response(1, byteArrayOf(status.toByte()))
+      assertTrue(session.offer(frameB, "one:2", true).isEmpty())
+      assertTrue(session.confirmedReadiness(false).isEmpty())
+      assertTrue(session.confirmedReadiness(true).isEmpty())
+    }
+  }
+
+  @Test fun deviceLockedStopsAllCanvasUntilNewTransport() {
+    val session = NimoCanvasSession()
+    launched(session)
+    session.response(4, byteArrayOf(8))
+    assertTrue(session.readiness(true).isEmpty())
+    assertTrue(session.confirmedReadiness(true).isEmpty())
+    assertTrue(session.offer(frameB, "one:2", true).isEmpty())
+    session.disconnected()
+    assertEquals(1, send(session.readiness(true)).key)
+  }
+
+  @Test fun statusTwoResetsTransportInsteadOfBlindRetry() {
+    val session = NimoCanvasSession()
+    launched(session)
+    val actions = session.response(4, byteArrayOf(2))
+    assertEquals(2, actions.size)
+    assertTrue(actions.last() is NimoCanvasSession.Action.Reconnect)
+    assertTrue(session.offer(frameB, "one:1").isEmpty())
+  }
+
+  @Test fun explicitExitWaitsForCurrentCommandAndDoesNotReplayOldFrame() {
+    val session = NimoCanvasSession()
+    launched(session)
+    assertTrue(session.exit().isEmpty())
+    assertEquals(3, send(success(session, 4)).key)
+    assertTrue(session.nativeApp(0xFD, false).isEmpty())
+    assertTrue(success(session, 3).isEmpty())
+    session.disconnected()
+    assertTrue(session.readiness(true).isEmpty())
+  }
+
+  @Test fun newSceneDuringExitLaunchesOnlyAfterExitAck() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+    assertEquals(3, send(session.exit()).key)
+    assertTrue(session.offer(frameB, "two:1").isEmpty())
+    assertTrue(session.nativeApp(0xFD, false).isEmpty())
+    assertEquals(1, send(success(session, 3)).key)
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+  }
+
+  @Test fun actualNativeTakeoverDuringExitDiscardsNewerScene() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+    assertEquals(3, send(session.exit()).key)
+    session.offer(frameB, "two:1")
+    assertTrue(session.nativeApp(0, true).isEmpty())
+    assertTrue(success(session, 3).isEmpty())
+    session.disconnected()
+    assertTrue(session.readiness(true).isEmpty())
+  }
+
+  @Test fun nativeTakeoverSuppressesReplayUntilNewHostFrame() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+    assertTrue(session.nativeApp(0, true).isEmpty())
+    assertTrue(session.readiness(true).isEmpty())
+    assertEquals(1, send(session.offer(frameA, "one:1")).key)
+  }
+
+  @Test fun nativeTakeoverOrReadinessLossDuringCommandResets() {
+    for (takeover in listOf(true, false)) {
+      val session = NimoCanvasSession(); launched(session)
+      val actions = if (takeover) session.nativeApp(0, true) else session.readiness(false)
+      assertTrue(actions.single() is NimoCanvasSession.Action.Reconnect)
+    }
+  }
+
+  @Test fun offersCopyMutableInputAndRejectOversizedFrame() {
+    val session = NimoCanvasSession()
+    val input = frameA.copyOf(); session.offer(input, "one:1"); input[0] = 99
+    session.readiness(true)
+    assertArrayEquals(frameA, send(success(session, 1)).frame)
+    assertThrows(IllegalArgumentException::class.java) { session.offer(ByteArray(12281), "one:1") }
+  }
+
+  @Test fun diagnosticHoldRetainsOnlyLatestSceneUntilReleased() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+
+    assertTrue(session.hold(true).isEmpty())
+    assertTrue(session.offer(frameB, "two:1").isEmpty())
+    assertTrue(session.offer(frameC, "two:2", force = true).isEmpty())
+
+    val update = send(session.hold(false))
+    assertEquals(4, update.key)
+    assertArrayEquals(frameC, update.frame)
+  }
+
+  @Test fun preemptedHoldDoesNotFlushStaleSceneBeforeExit() {
+    val session = NimoCanvasSession()
+    launched(session); success(session, 4)
+    session.hold(true)
+    session.offer(frameB, "two:1")
+
+    assertTrue(session.hold(false, resume = false).isEmpty())
+    assertEquals(3, send(session.exit()).key)
+  }
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoDiagnosticsTest.kt

@@ -0,0 +1,287 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import androidx.test.core.app.ApplicationProvider
+import java.io.File
+import java.util.concurrent.TimeUnit
+import org.json.JSONObject
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class NimoDiagnosticsTest {
+  private data class Write(val packet: ByteArray, val completed: () -> Unit)
+  private val writes = mutableListOf<Write>()
+  private var heldReady: (() -> Unit)? = null
+  private val holdReleases = mutableListOf<Boolean>()
+  private lateinit var diagnostics: NimoDiagnostics
+  private lateinit var root: File
+  private lateinit var previousDirectories: Set<String>
+
+  @Before fun setup() {
+    val context = ApplicationProvider.getApplicationContext<Context>()
+    root = File(context.filesDir, "nimo-framebuffer")
+    previousDirectories = root.listFiles()?.map { it.name }?.toSet() ?: emptySet()
+    diagnostics = NimoDiagnostics(
+      context,
+      Handler(Looper.getMainLooper()),
+      { frame, complete -> writes.add(Write(frame.copyOf(), complete)); true },
+      { ready -> heldReady = ready },
+      { resume -> holdReleases += resume },
+    )
+    diagnostics.connected(512)
+  }
+
+  @After fun dispose() { diagnostics.close() }
+
+  @Test fun probePreservesNotReadyAndAcceptsResponsesBeforeWriteCallbacks() {
+    start("probe")
+    driveToPageGate()
+    assertTrue(diagnostics.onPacket(fbpReply(writes[3].packet, ByteArray(240))))
+    val result = receipt()
+    assertTrue(result.getBoolean("probe_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertTrue(result.isNull("error"))
+    assertEquals(0, result.getJSONObject("readiness").getInt("ready"))
+    assertEquals(1, result.getJSONObject("readiness").getInt("tws"))
+    assertEquals(NimoFramebufferProtocol.EXPECTED_VERSION, result.getString("runtime_version"))
+    assertEquals(8, result.getInt("wire_events"))
+    assertEquals(8, File(captureDirectory(), "wire.jsonl").readLines().size)
+    writes.toList().forEach { it.completed() }
+    idle(4_000)
+    assertEquals(4, writes.size)
+    assertTrue(receipt().getBoolean("probe_ok"))
+    assertTrue(writes.all { it.packet[8] == 2.toByte() && (it.packet[9].toInt() and 255) in listOf(0x0B, 0x19, 0x15) })
+  }
+
+  @Test fun duplicateTriggerDoesNotStartAnotherRead() {
+    start("capture")
+    start("probe")
+    assertEquals(1, writes.size)
+    assertEquals(1, newDirectories().size)
+  }
+
+  @Test fun disconnectCancelsPendingTimeoutAndIgnoresLateWriteCompletion() {
+    start("capture")
+    writes.single().completed()
+    diagnostics.disconnected()
+    val error = receipt().getString("error")
+    assertTrue(error.contains("disconnected"))
+    diagnostics.connected(512)
+    writes.single().completed()
+    idle(4_000)
+    assertEquals(error, receipt().getString("error"))
+    assertEquals(1, writes.size)
+    assertFalse(diagnostics.onPacket(versionReply()))
+    assertFalse(receipt().getBoolean("ok"))
+  }
+
+  @Test fun timeoutStartsAtWriteCompletionAndDoesNotRetry() {
+    start("probe")
+    idle(5_000)
+    assertFalse(File(captureDirectory(), "session.json").exists())
+    writes.single().completed()
+    idle(2_900)
+    assertFalse(File(captureDirectory(), "session.json").exists())
+    idle(200)
+    assertTrue(receipt().getString("error").contains("response timeout"))
+    assertEquals(1, writes.size)
+  }
+
+  @Test fun captureRejectsCrcBeforeRequestingBulkPages() {
+    start("capture")
+    driveToPageGate()
+    val corrupted = fbpReply(writes[3].packet, ByteArray(240)).also { it[4] = (it[4].toInt() xor 1).toByte() }
+    assertTrue(diagnostics.onPacket(corrupted))
+    assertFalse(receipt().getBoolean("ok"))
+    assertFalse(receipt().getBoolean("probe_ok"))
+    assertTrue(receipt().getString("error").contains("CRC mismatch"))
+    assertEquals(4, writes.size)
+    assertEquals(0, receipt().getJSONArray("banks").length())
+  }
+
+  @Test fun totalDeadlineBoundsAWriteThatNeverCompletes() {
+    start("capture")
+    idle(600_001)
+    assertTrue(receipt().getString("error").contains("10-minute budget"))
+    writes.single().completed()
+    idle(4_000)
+    assertEquals(1, writes.size)
+  }
+
+  @Test fun heldSampleBudgetIncludesCanvasDrainAndStaleReadyCannotStartCapture() {
+    start("held-sample")
+    assertTrue(writes.isEmpty())
+    assertNotNull(heldReady)
+
+    idle(15_001)
+
+    assertEquals(listOf(true), holdReleases)
+    assertTrue(receipt().getString("error").contains("15-second budget"))
+    heldReady?.invoke()
+    assertTrue(writes.isEmpty())
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  @Test fun disconnectBeforeHeldCaptureIsReadyReleasesWithoutResumingCanvas() {
+    start("held-capture")
+
+    diagnostics.disconnected()
+
+    assertEquals(listOf(false), holdReleases)
+    assertTrue(receipt().getString("error").contains("disconnected"))
+    heldReady?.invoke()
+    assertTrue(writes.isEmpty())
+    assertEquals(listOf(false), holdReleases)
+  }
+
+  @Test fun duplicateHeldCaptureDoesNotReplaceHoldOrDeadline() {
+    start("held-sample")
+    val firstReady = heldReady
+
+    start("held-capture")
+
+    assertSame(firstReady, heldReady)
+    assertEquals(1, newDirectories().size)
+    idle(15_001)
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  @Test fun insufficientCapacityFailsWithoutSendingDiagnosticCommands() {
+    diagnostics.connected(20)
+    start("capture")
+    assertEquals(0, writes.size)
+    assertTrue(receipt().getString("error").contains("Write capacity"))
+  }
+
+  @Test fun samplePinsPreparedBankAndNeverClaimsStaticPairVerification() {
+    assertSample(1)
+  }
+
+  @Test fun sampleAlsoPinsPreparedBankZero() {
+    assertSample(0)
+  }
+
+  @Test fun heldSampleStartsOnlyAfterDrainAndReleasesOnSuccess() {
+    assertSample(1, "held-sample")
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  private fun assertSample(bank: Int, mode: String = "sample") {
+    val state = byteArrayOf((1 - bank).toByte(), bank.toByte(), 0, 0)
+    start(mode)
+    if (mode == "held-sample") {
+      assertTrue(writes.isEmpty())
+      requireNotNull(heldReady).invoke()
+    }
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240), state))
+    // The gate always probes bank0/page0; the sample follows its prepared selector.
+    repeat(315) { page ->
+      val request = writes.last().packet
+      assertEquals(bank, request[21].toInt())
+      assertEquals(page, (request[22].toInt() and 255) or ((request[23].toInt() and 255) shl 8))
+      diagnostics.onPacket(fbpReply(request, ByteArray(240) { page.toByte() }, state))
+    }
+    val result = receipt()
+    assertTrue(result.getBoolean("sample_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertFalse(result.getBoolean("atomic"))
+    assertFalse(result.getBoolean("optical"))
+    assertEquals("non_atomic_single_pass", result.getString("evidence_kind"))
+    assertEquals(0, result.getInt("static_pairs_verified"))
+    assertEquals(1, result.getJSONArray("banks").length())
+    assertEquals(319, writes.size)
+    assertEquals(638, result.getInt("wire_events"))
+    assertFalse(result.getBoolean("pixel_stability_verified"))
+    assertEquals(mode, result.getString("mode"))
+    assertEquals(75_600, File(captureDirectory(), "bank$bank-pass1.bin").length().toInt())
+  }
+
+  @Test fun sampleRejectsSelectorChangeBetweenGateAndFirstPageWithoutRetrying() {
+    start("sample")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240), byteArrayOf(1, 0, 0, 0)))
+    val result = receipt()
+    assertFalse(result.getBoolean("sample_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertTrue(result.getString("error").contains("Sample metadata differs from page gate"))
+    assertEquals(5, writes.size)
+    assertEquals(0, result.getJSONArray("banks").length())
+  }
+
+  @Test fun sampleTimeoutCannotProduceSuccessOrStartASecondPass() {
+    start("sample")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    writes.last().completed()
+    idle(3_001)
+    assertFalse(receipt().getBoolean("sample_ok"))
+    assertFalse(receipt().getBoolean("ok"))
+    assertEquals(5, writes.size)
+  }
+
+  @Test fun fullCaptureStillRequiresFourCompleteReadsAndTwoStaticPairs() {
+    start("capture")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    repeat(4) { pass ->
+      repeat(315) { page ->
+        val request = writes.last().packet
+        assertEquals(pass / 2, request[21].toInt())
+        diagnostics.onPacket(fbpReply(request, ByteArray(240) { page.toByte() }))
+      }
+      if (pass < 3) assertFalse(File(captureDirectory(), "session.json").exists())
+    }
+    assertTrue(receipt().getBoolean("ok"))
+    assertEquals(2, receipt().getInt("static_pairs_verified"))
+    assertEquals(4, receipt().getJSONArray("banks").length())
+    assertEquals(1264, writes.size)
+  }
+
+  private fun driveToPageGate() {
+    assertEquals(1, writes.size)
+    assertFalse(diagnostics.onPacket(versionReply()))
+    assertEquals(2, writes.size)
+    assertFalse(diagnostics.onPacket(frame(0x19, byteArrayOf(0, 0, 1, 0))))
+    assertEquals(3, writes.size)
+    assertTrue(diagnostics.onPacket(fbpReply(writes[2].packet, "537cf1p1".toByteArray())))
+    assertEquals(4, writes.size)
+  }
+
+  // Exercise the production coordinator without pretending Robolectric proves Android's
+  // signature-permission enforcement for the ADB receiver. That boundary needs a device test.
+  private fun start(mode: String) {
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java).apply { isAccessible = true }
+      .invoke(diagnostics, mode)
+  }
+  private fun idle(milliseconds: Long) = Shadows.shadowOf(Looper.getMainLooper()).idleFor(milliseconds, TimeUnit.MILLISECONDS)
+  private fun newDirectories() = root.listFiles()?.filter { it.name !in previousDirectories } ?: emptyList()
+  private fun captureDirectory() = newDirectories().single()
+  private fun receipt() = JSONObject(File(captureDirectory(), "session.json").readText())
+  private fun versionReply() = frame(0x0B, byteArrayOf(0) + NimoFramebufferProtocol.EXPECTED_VERSION.toByteArray())
+
+  private fun fbpReply(request: ByteArray, data: ByteArray, state: ByteArray = byteArrayOf(0, 1, 0, 0)): ByteArray {
+    val payload = byteArrayOf(0) + "FBP1".toByteArray() + request.copyOfRange(16, 24) + state + state +
+      byteArrayOf(data.size.toByte(), (data.size shr 8).toByte()) + data
+    return frame(0x15, payload)
+  }
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    val crc = NimoCanvasCodec.crc16(body)
+    return byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(),
+      crc.toByte(), (crc shr 8).toByte(), 0, 0) + body
+  }
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoFramebufferProtocolTest.kt

@@ -0,0 +1,127 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class NimoFramebufferProtocolTest {
+  @Test fun hexPreservesEveryByteAndEmptyEvidence() {
+    val bytes = ByteArray(256) { it.toByte() }
+    assertEquals(bytes.joinToString("") { "%02x".format(it.toInt() and 255) }, NimoFramebufferProtocol.hex(bytes))
+    assertEquals("", NimoFramebufferProtocol.hex(byteArrayOf()))
+  }
+  private val pingRequest = NimoFramebufferProtocol.Request(0x01020304L, 0, 0, 0)
+  // Fixed vectors produced independently by the existing Python FBP1 codec.
+  private val ping = hex("bf0023008234000002151f0000464250310403020100000000000100000001000008003533376366317031")
+  private val page = hex("bf000b0175e500000215070100464250310403020101013a010001000000010000f000") +
+    ByteArray(240) { it.toByte() }
+
+  @Test fun requestAndReplyMatchIndependentGoldenVectors() {
+    assertArrayEquals(hex("bf001000227a000002150c00464250310403020100000000"),
+      NimoFramebufferProtocol.requestFrame(pingRequest))
+    val reply = NimoFramebufferProtocol.reply(ping, pingRequest)
+    assertArrayEquals("537cf1p1".toByteArray(), reply.data)
+    assertEquals(NimoFramebufferProtocol.State(0, 1, 0, 0), reply.before)
+    val expectedPage = NimoFramebufferProtocol.Request(0x01020304L, 1, 1, 314)
+    assertArrayEquals(ByteArray(240) { it.toByte() }, NimoFramebufferProtocol.reply(page, expectedPage).data)
+  }
+
+  @Test fun rejectsCrcLengthsDirectionIndexAndCommand() {
+    for (offset in listOf(0, 1, 2, 4, 6, 8, 9, 10)) {
+      val invalid = ping.copyOf().also { it[offset] = (it[offset].toInt() xor 1).toByte() }
+      rejects { NimoFramebufferProtocol.reply(invalid, pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(ping + 0, pingRequest) }
+    rejects { NimoFramebufferProtocol.reply(ping.copyOf(ping.size - 1), pingRequest) }
+  }
+
+  @Test fun rejectsWrongTagMagicNonceOperationBankAndPage() {
+    for (offset in listOf(13, 17, 21, 22, 23, 33, 35)) {
+      val invalid = changeAndRecrc(ping, offset, ping[offset].toInt() xor 1)
+      rejects { NimoFramebufferProtocol.reply(invalid, pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(ping, pingRequest.copy(nonce = 9)) }
+    rejects { NimoFramebufferProtocol.reply(ping, pingRequest.copy(op = 1)) }
+  }
+
+  @Test fun rejectsStatusErrorsEvenWithValidCorrelation() {
+    for (status in listOf(1, 6, 7, 255)) {
+      val payload = ping.copyOfRange(12, 35).also { it[0] = status.toByte(); it[21] = 0; it[22] = 0 }
+      rejects { NimoFramebufferProtocol.reply(frame(0x15, payload), pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(changeAndRecrc(ping, 12, 6), pingRequest) }
+  }
+
+  @Test fun rejectsMetadataChangedWithinAndAcrossPagesAndOutOfOrder() {
+    val request = NimoFramebufferProtocol.Request(0x01020304L, 1, 1, 0)
+    val first = NimoFramebufferProtocol.reply(pageAt(0), request)
+    val read = NimoFramebufferProtocol.BankRead(request.nonce, request.bank)
+    read.add(first)
+    rejects { read.add(first) }
+    rejects { NimoFramebufferProtocol.BankRead(request.nonce, request.bank).add(first.copy(page = 1)) }
+    rejects { NimoFramebufferProtocol.reply(changeAndRecrc(pageAt(0), 29, 1), request) }
+    val changed = first.copy(page = 1, before = first.before.copy(dirty = 1), after = first.after.copy(dirty = 1))
+    val changedRead = NimoFramebufferProtocol.BankRead(request.nonce, request.bank)
+    changedRead.add(first)
+    rejects { changedRead.add(changed) }
+  }
+
+  @Test fun bankRequiresEveryPageAndIndependentEqualSecondPass() {
+    val first = completeBank(10)
+    val second = completeBank(11)
+    NimoFramebufferProtocol.verifyPair(first, second)
+    assertEquals(75600, first.bytes().size)
+    rejects { NimoFramebufferProtocol.verifyPair(first, first) }
+    rejects { NimoFramebufferProtocol.verifyPair(first, completeBank(12, changedLastPixel = true)) }
+    rejects { NimoFramebufferProtocol.BankRead(20, 1).bytes() }
+  }
+
+  @Test fun requestLimitsPreventArbitraryCommandsOrAddresses() {
+    for (request in listOf(pingRequest.copy(nonce = -1), pingRequest.copy(nonce = 0x100000000L),
+      pingRequest.copy(op = 2), pingRequest.copy(bank = 2), pingRequest.copy(page = 1),
+      pingRequest.copy(op = 1, page = 315))) {
+      rejects { NimoFramebufferProtocol.requestFrame(request) }
+    }
+    rejects { NimoFramebufferProtocol.queryFrame(0x0A) }
+  }
+
+  @Test fun basicResponsesRequireExactVersionAndReadinessShape() {
+    val version = byteArrayOf(0) + NimoFramebufferProtocol.EXPECTED_VERSION.toByteArray()
+    assertEquals(NimoFramebufferProtocol.EXPECTED_VERSION,
+      NimoFramebufferProtocol.version(frame(0x0B, version)))
+    rejects { NimoFramebufferProtocol.version(frame(0x0B, version + 0)) }
+    rejects { NimoFramebufferProtocol.version(frame(0x0B, version.copyOf().also { it[0] = 7 })) }
+    assertEquals(listOf(0, 0, 1, 0), NimoFramebufferProtocol.readiness(frame(0x19, byteArrayOf(0, 0, 1, 0))))
+    rejects { NimoFramebufferProtocol.readiness(frame(0x19, byteArrayOf(0, 1, 1))) }
+  }
+
+  private fun completeBank(nonce: Long, changedLastPixel: Boolean = false): NimoFramebufferProtocol.BankRead {
+    val read = NimoFramebufferProtocol.BankRead(nonce, 1)
+    repeat(315) { index ->
+      val original = NimoFramebufferProtocol.reply(pageAt(index),
+        NimoFramebufferProtocol.Request(0x01020304L, 1, 1, index))
+      val data = original.data.copyOf()
+      if (changedLastPixel && index == 314) data[239] = 0
+      read.add(original.copy(nonce = nonce, data = data))
+    }
+    return read
+  }
+
+  private fun pageAt(index: Int): ByteArray {
+    val result = page.copyOf()
+    result[23] = index.toByte(); result[24] = (index shr 8).toByte()
+    return recrc(result)
+  }
+  private fun changeAndRecrc(value: ByteArray, index: Int, byte: Int) =
+    recrc(value.copyOf().also { it[index] = byte.toByte() })
+  private fun recrc(value: ByteArray): ByteArray {
+    val crc = NimoCanvasCodec.crc16(value.copyOfRange(8, value.size))
+    value[4] = crc.toByte(); value[5] = (crc shr 8).toByte()
+    return value
+  }
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    return recrc(byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(), 0, 0, 0, 0) + body)
+  }
+  private fun rejects(block: () -> Unit) { assertThrows(IllegalArgumentException::class.java, block) }
+  private fun hex(value: String) = value.chunked(2).map { it.toInt(16).toByte() }.toByteArray()
+}