unified-ble-manager 4.0.13 → 4.0.16

package/CHANGELOG.md

@@ -6,6 +6,47 @@ All notable changes to `unified-ble-manager` are documented here.
 
 No changes yet.
 
+## [4.0.16] - 2026-09-03
+
+### Fixes
+
+- Normalize an Android CCCD operation that terminates with GATT status 19 as
+  `connection.lost` even when it arrives before the native `connectionLost`
+  event. Other CCCD failures remain `platform.failure` and retain their native
+  GATT status.
+- Cancel a dispatched React Native Android `when-available` connection when
+  its caller aborts, releasing the native pending connection so a later
+  same-peer retry is admitted without affecting distinct-peer connects.
+
+## [4.0.15] - 2026-09-02
+
+### Fixes
+
+- Silence exactly one expected late React Native Android terminal when a peer
+  is lost while an operation such as GATT discovery is still settling. The
+  boundary records only operations it explicitly rejected for that peer,
+  bounds and lifecycle-scopes those records, and continues to report unknown
+  or duplicate terminals as protocol diagnostics.
+
+## [4.0.14] - 2026-09-02
+
+### Fixes
+
+- Release Android GATT ownership immediately when Bluetooth powers off or
+  resets instead of waiting for a `STATE_DISCONNECTED` callback that Android
+  may never deliver. Failed native closes remain retained and retry when the
+  adapter returns, protocol routes are invalidated before adapter-state
+  publication, and an ordinary disconnect timeout now also publishes the
+  missing terminal state before cleanup. A cleanup unsubscribe after adapter
+  loss is idempotent when native ownership is already gone.
+- Terminalize adapter-loss connections exactly once with the typed `adapter`
+  reason when a native CoreBluetooth-style or WinRT disconnect completes
+  without a platform loss callback. Delayed native callbacks are ignored, and
+  WinRT connection paths retain the attachment that created them.
+- Treat an operation that is still settling after adapter loss as expected
+  quarantine rather than a cleanup error. Cleanup still waits and retries, but
+  only an actual native release failure produces an error diagnostic.
+
 ## [4.0.13] - 2026-09-01
 
 ### Fixes

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-This source targets `4.0.13`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
+This source targets `4.0.16`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
 
 This page is for a React Native app that already uses `react-native-ble-plx`. Web, Electron, Node, and Tauri are new hosts — use those pages after you understand the RN rewrite.
 

package/README.md

@@ -18,7 +18,7 @@ root import does not pick a radio. Package SemVer and backend support labels are
 independent: each radio backend keeps its evidence-derived label. See
 [`docs/PLATFORMS.md`](docs/PLATFORMS.md).
 
-This source tree is versioned `4.0.13`. Install the exact version shown in the npm
+This source tree is versioned `4.0.16`. Install the exact version shown in the npm
 registry. During release preparation, the version in `package.json` can be ahead
 of npm until the matching tag-driven workflow publishes it; the registry and
 GitHub release remain authoritative.

package/RELEASE.md

@@ -81,7 +81,7 @@ Active `4.0.0-rc.*` release-train candidates publish to npm `latest` so a bare `
 
 On release day, set `release_candidate` to the exact candidate required by the
 release plan. RC2, RC3, RC4, `4.0.0-rc.4.1`, and RC5 are already immutable
-once tagged. Stable `4.0.0` through `4.0.12` are immutable. `4.0.13` is the current train head.
+once tagged. Stable `4.0.0` through `4.0.15` are immutable. `4.0.16` is the current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -133,9 +133,30 @@ The `v4.0.3` tag is immutable published history. Do not recreate or move it.
 git tag -a v4.0.3 -m "v4.0.3"
 ```
 
-## Releasing 4.0.13
+## Releasing 4.0.16
+
+The `v4.0.16` tag must identify the exact current `main` commit after canonical
+CI passes. Do not tag the release branch directly.
+
+```sh
+git fetch origin --tags
+git checkout main
+git pull --ff-only origin main
+
+test "$(git branch --show-current)" = "main"
+test "$(node -p "require('./package.json').version")" = "4.0.16"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.16 -m "v4.0.16"
+git push origin v4.0.16
+```
 
-The `v4.0.13` tag must identify the exact current `main` commit after canonical
+Before tagging, confirm release-note extraction finds `## [4.0.16]`.
+
+## Releasing 4.0.15
+
+The `v4.0.15` tag must identify the exact current `main` commit after canonical
 CI passes. Do not tag this feature branch directly.
 
 ```sh
@@ -144,15 +165,28 @@ git checkout main
 git pull --ff-only origin main
 
 test "$(git branch --show-current)" = "main"
-test "$(node -p "require('./package.json').version")" = "4.0.13"
+test "$(node -p "require('./package.json').version")" = "4.0.15"
 git diff --exit-code
 git diff --cached --exit-code
 
-git tag -a v4.0.13 -m "v4.0.13"
-git push origin v4.0.13
+git tag -a v4.0.15 -m "v4.0.15"
+git push origin v4.0.15
 ```
 
-Before tagging, confirm release-note extraction finds `## [4.0.13]`.
+Before tagging, confirm release-note extraction finds `## [4.0.15]`.
+
+## Releasing 4.0.14
+
+The `v4.0.14` tag is immutable history, but its publish workflow was cancelled
+before the npm version check and publish steps. Do not recreate or move it.
+
+## Releasing 4.0.13
+
+The `v4.0.13` tag is immutable published history. Do not recreate or move it.
+
+```sh
+git tag -a v4.0.13 -m "v4.0.13"
+```
 
 ## Releasing 4.0.12
 
@@ -327,7 +361,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.12
+version=4.0.16
 
 npm view "unified-ble-manager@$version" version
 npm view unified-ble-manager dist-tags --json

package/SBOM.cdx.json

@@ -6,20 +6,20 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.13",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.16",
       "name": "unified-ble-manager",
-      "version": "4.0.13",
+      "version": "4.0.16",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.13"
+      "purl": "pkg:npm/unified-ble-manager@4.0.16"
     },
     "properties": [
       {
         "name": "unified-ble-manager:pnpm-lock-sha256",
-        "value": "58c2b09c18f10de1e250a357e5ce9445fe6bcace614e3778bc60166b9db31fa1"
+        "value": "fea8b9fea3dca31d966c33e5942c5fb0f179c492a8462f90482d0c5dc1bd86d2"
       },
       {
         "name": "unified-ble-manager:dependency-scope",
@@ -537,7 +537,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.13",
+      "ref": "pkg:npm/unified-ble-manager@4.0.16",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
         "pkg:npm/node-addon-api@8.9.0",

package/THIRD_PARTY_LICENSES.json

@@ -4,12 +4,12 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.13"
+    "version": "4.0.16"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",
     "lockfile": "pnpm-lock.yaml",
-    "lockfileSha256": "58c2b09c18f10de1e250a357e5ce9445fe6bcace614e3778bc60166b9db31fa1"
+    "lockfileSha256": "fea8b9fea3dca31d966c33e5942c5fb0f179c492a8462f90482d0c5dc1bd86d2"
   },
   "reviewedOverrides": [
     {

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/protocol/UnifiedBleProtocolAndroidDispatcher.kt

@@ -11,6 +11,7 @@ import com.sfourdrinier.unifiedblemanager.protocol.generated.ConnectionIntents
 import com.sfourdrinier.unifiedblemanager.protocol.generated.RecordKind
 import com.sfourdrinier.unifiedblemanager.radio.OwnedAndroidGattRadio
 import com.sfourdrinier.unifiedblemanager.radio.OwnedRadioTeardownFailure
+import com.sfourdrinier.unifiedblemanager.radio.AndroidGattOperationFailure
 import com.sfourdrinier.unifiedblemanager.radio.BondedPeerSnapshot
 import com.sfourdrinier.unifiedblemanager.radio.nextUuidOccurrence
 import java.util.UUID
@@ -38,7 +39,8 @@ class UnifiedBleProtocolAndroidDispatcher(
   private var attachmentRecord: ProtocolWireRecord? = null
 
   init {
-    radio.onAdapterState = {
+    radio.onAdapterState = { adapterState ->
+      clearGattProtocolOwnershipForAdapterLoss(adapterState)
       emitCurrentAdapterState()
     }
     radio.onCleanupFailure = { failure ->
@@ -140,6 +142,33 @@ class UnifiedBleProtocolAndroidDispatcher(
     }
   }
 
+  private fun clearGattProtocolOwnershipForAdapterLoss(adapterState: String) {
+    val state = radio.currentProtocolAdapterState()
+    if (state.availability == "available" && state.authorization == "granted" && state.power == "on") return
+    val failure = when (adapterState) {
+      "PoweredOff" -> AdapterLossConnectFailure(
+        "adapterPoweredOff",
+        "Android Bluetooth was powered off while the connection was pending"
+      )
+      "Resetting" -> AdapterLossConnectFailure(
+        "adapterResetting",
+        "Android Bluetooth reset while the connection was pending"
+      )
+      else -> AdapterLossConnectFailure(
+        "adapterUnavailable",
+        "Android Bluetooth became unavailable while the connection was pending"
+      )
+    }
+    pendingConnects.entries.toList().forEach { entry ->
+      if (pendingConnects.remove(entry.key, entry.value)) {
+        emitFailure(entry.value, failure.code, failure.message)
+      }
+    }
+    establishedConnections.clear()
+    activeDatabases.clear()
+    activeSubscriptions.clear()
+  }
+
   fun emitCurrentAdapterState() {
     val state = radio.currentProtocolAdapterState()
     val fields = mutableMapOf<Int, ProtocolWireValue>(
@@ -564,6 +593,11 @@ class UnifiedBleProtocolAndroidDispatcher(
   }
 
   private fun subscribe(command: ProtocolWireRecord, enable: Boolean) {
+    val subscriptionId = command.requiredString(7)
+    if (!enable && !activeSubscriptions.containsKey(subscriptionId)) {
+      emitSuccess(command, "unsubscribed")
+      return
+    }
     val endpoint = characteristicEndpoint(command.requiredRecord(4))
     val radioOperationId = radio.setNotifyExact(
       endpoint.deviceId,
@@ -597,7 +631,6 @@ class UnifiedBleProtocolAndroidDispatcher(
             }
             return@fold
           }
-          val subscriptionId = command.requiredString(7)
           if (enable) {
             activeSubscriptions[subscriptionId] = SubscriptionRoute(
               subscriptionId,
@@ -609,7 +642,9 @@ class UnifiedBleProtocolAndroidDispatcher(
           }
           emitSuccess(command, if (enable) "subscribed" else "unsubscribed")
         },
-        onFailure = { error -> emitFailure(command, "subscriptionFailed", error.message ?: "Android CCCD operation failed") }
+        onFailure = { error ->
+          emitGattOperationFailure(command, "subscriptionFailed", error, "Android CCCD operation failed")
+        }
       )
     }
     radioOperationIds[operationKey(command)] = radioOperationId
@@ -824,21 +859,44 @@ class UnifiedBleProtocolAndroidDispatcher(
     radioOperationIds.remove(operationKey(command))
   }
 
-  private fun emitFailure(command: ProtocolWireRecord, code: String, message: String) {
+  private fun emitGattOperationFailure(
+    command: ProtocolWireRecord,
+    fallbackCode: String,
+    error: Throwable,
+    fallbackMessage: String
+  ) {
+    emitFailure(
+      command,
+      androidGattOperationFailureCode(error, fallbackCode),
+      error.message ?: fallbackMessage,
+      androidGattOperationFailureStatus(error)
+    )
+  }
+
+  private fun emitFailure(
+    command: ProtocolWireRecord,
+    code: String,
+    message: String,
+    androidGattStatus: Int? = null
+  ) {
     val bondedPeerCommand = command.requiredString(3) == "enumerateBondedPeers"
     if (bondedPeerCommand) {
       // Keep failure/cancellation/teardown mutually exclusive with a late success.
       if (!claimExactPendingCommand(pendingCommands, operationKey(command), command)) return
     } else if (!isPending(command)) return
-    val error = ProtocolWireRecord(
-      RecordKind.ERROR,
-      mapOf(
+    val errorFields = mutableMapOf<Int, ProtocolWireValue>(
         1 to ProtocolWireValue.StringValue(code),
         2 to ProtocolWireValue.StringValue("android"),
         3 to ProtocolWireValue.StringValue(command.requiredString(3)),
         4 to ProtocolWireValue.StringValue("notRetryable"),
         7 to ProtocolWireValue.StringValue(message)
       )
+    androidGattStatus?.let { status ->
+      errorFields[8] = ProtocolWireValue.SignedIntegerValue(status.toLong())
+    }
+    val error = ProtocolWireRecord(
+      RecordKind.ERROR,
+      errorFields
     )
     val result = ProtocolWireRecord(
       RecordKind.RESULT,
@@ -1132,6 +1190,11 @@ class UnifiedBleProtocolAndroidDispatcher(
     }
   }
 
+  private data class AdapterLossConnectFailure(
+    val code: String,
+    val message: String
+  )
+
   private fun requirePhyAvailable() {
     check(Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
       "Android PHY requires API 26"
@@ -1158,6 +1221,7 @@ internal fun connectionLostEvent(
       8 to ProtocolWireValue.SignedIntegerValue(status.toLong())
     )
   )
+
   return ProtocolWireRecord(
     RecordKind.EVENT,
     mapOf(
@@ -1173,6 +1237,14 @@ internal fun connectionLostEvent(
   )
 }
 
+internal fun androidGattOperationFailureCode(error: Throwable, fallbackCode: String): String {
+  val gattFailure = error as? AndroidGattOperationFailure
+  return if (gattFailure?.isLinkLoss == true) "connectionLost" else fallbackCode
+}
+
+internal fun androidGattOperationFailureStatus(error: Throwable): Int? =
+  (error as? AndroidGattOperationFailure)?.gattStatus
+
 internal fun databaseChangedEvent(
   nativeHandle: Long,
   database: ProtocolWireRecord,

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/radio/OwnedAndroidGattRadio.kt

@@ -109,6 +109,27 @@ internal class OwnedAndroidSubscriptionOwnership<K> {
   }
 }
 
+/**
+ * Preserves the Android GATT callback status when an asynchronous operation
+ * terminates. Status 19 means that the peer terminated the link; keeping that
+ * distinction typed prevents a CCCD race from being flattened to a generic
+ * platform failure before the later connection-state callback arrives.
+ */
+internal class AndroidGattOperationFailure(
+  val operation: String,
+  val gattStatus: Int
+) : IllegalStateException("$operation status=$gattStatus") {
+  val isLinkLoss: Boolean
+    get() = gattStatus == ANDROID_GATT_LINK_LOSS_STATUS
+}
+
+internal const val ANDROID_GATT_LINK_LOSS_STATUS = 19
+
+internal fun classifyAndroidGattOperationFailure(
+  operation: String,
+  gattStatus: Int
+): AndroidGattOperationFailure = AndroidGattOperationFailure(operation, gattStatus)
+
 /** Runtime adapter state derived from Android hardware and granted permissions. */
 internal data class OwnedRadioAdapterProtocolState(
   val availability: String,
@@ -150,6 +171,11 @@ internal fun bondedPeerAdapterReadiness(
   }
 }
 
+internal fun requiresImmediateGattTeardownOnAdapterState(state: Int?): Boolean =
+  state == BluetoothAdapter.STATE_OFF ||
+    state == BluetoothAdapter.STATE_TURNING_OFF ||
+    state == BluetoothAdapter.STATE_TURNING_ON
+
 /** Normalize the platform snapshot before it crosses the Android protocol boundary. */
 internal fun normalizeBondedPeerSnapshots(
   peers: Iterable<BondedPeerSnapshot>
@@ -416,6 +442,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
         override fun onReceive(ctx: Context?, intent: Intent?) {
           if (intent?.action != BluetoothAdapter.ACTION_STATE_CHANGED) return
           val state = intent.getIntExtra(BluetoothAdapter.EXTRA_STATE, BluetoothAdapter.ERROR)
+          handleAdapterStateTransition(state)
           onAdapterState?.invoke(mapAdapterState(state))
         }
       }
@@ -430,6 +457,23 @@ class OwnedAndroidGattRadio(private val context: Context) {
     adapterStateReceiver = receiver
   }
 
+  private fun handleAdapterStateTransition(state: Int) {
+    if (state == BluetoothAdapter.STATE_ON) {
+      pendingGattTeardowns.keys.toList().forEach { key -> retryGattTeardown(key) }
+      return
+    }
+    if (!requiresImmediateGattTeardownOnAdapterState(state)) return
+
+    pendingReconnect.clear()
+    (gatts.keys + pendingGattTeardowns.keys).toSet().forEach { key ->
+      failPendingForDevice(key, "adapter unavailable")
+      val owner = pendingGattTeardowns[key]
+      val gatt = gatts[key] ?: owner?.gatt ?: return@forEach
+      val teardownFailure = completeGattTeardown(key, gatt)
+      pendingDisconnectCallbacks.remove(key)?.invoke(teardownFailure)
+    }
+  }
+
   internal fun unregisterAdapterStateReceiver(): OwnedRadioTeardownFailure? {
     val receiver = adapterStateReceiver ?: return null
     try {
@@ -838,6 +882,18 @@ class OwnedAndroidGattRadio(private val context: Context) {
       onComplete(failure)
       return failure
     }
+    if (pendingGattTeardowns[key] != null) {
+      val teardownFailure = retryGattTeardown(key)
+      val failure = cleanupFailure ?: teardownFailure
+      onComplete(failure)
+      return failure
+    }
+    if (requiresImmediateGattTeardownOnAdapterState(adapter?.state)) {
+      val teardownFailure = completeGattTeardown(key, g)
+      val failure = cleanupFailure ?: teardownFailure
+      onComplete(failure)
+      return failure
+    }
     // R3-F003: only disconnect(); close() waits for STATE_DISCONNECTED (or safety timeout).
     pendingDisconnectCallbacks[key] = onComplete
     scheduleSafeClose(key, g)
@@ -923,6 +979,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
       Runnable {
         if (gatts[key] === gatt) {
           OwnedAndroidLog.e("GATT close safety timeout for $key (DISCONNECTED never arrived)")
+          dispatchConnectionState(key, false, BluetoothGatt.GATT_FAILURE)
           failPendingForDevice(key, "disconnected timeout")
           val teardownFailure = completeGattTeardown(key, gatt)
           pendingDisconnectCallbacks.remove(key)?.invoke(teardownFailure)
@@ -2443,7 +2500,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
         } else {
           completeExactUnit(
             pending,
-            Result.failure(IllegalStateException("onDescriptorWrite status=$status"))
+            Result.failure(classifyAndroidGattOperationFailure("descriptor-write", status))
           )
         }
         return
@@ -2458,7 +2515,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
         } else {
           completeExactUnit(
             pending,
-            Result.failure(IllegalStateException("onDescriptorWrite status=$status"))
+            Result.failure(classifyAndroidGattOperationFailure("cccd-write", status))
           )
         }
         return
@@ -2479,7 +2536,14 @@ class OwnedAndroidGattRadio(private val context: Context) {
       if (status == BluetoothGatt.GATT_SUCCESS) {
         cb?.invoke(Result.success(Unit))
       } else {
-        cb?.invoke(Result.failure(IllegalStateException("onDescriptorWrite status=$status")))
+        cb?.invoke(
+          Result.failure(
+            classifyAndroidGattOperationFailure(
+              if (matchedKey?.startsWith("cccd:") == true) "cccd-write" else "descriptor-write",
+              status
+            )
+          )
+        )
       }
     }