unified-ble-manager 4.0.20 → 4.0.23

package/CHANGELOG.md

@@ -6,6 +6,57 @@ All notable changes to `unified-ble-manager` are documented here.
 
 No changes yet.
 
+## [4.0.23] - 2026-09-05
+
+### Fixes
+
+- Share one adapter-state polling owner across IPC state watchers and readiness waits, sampling at
+  a 500 ms control-plane cadence. The previous 25 ms polling loop could fill
+  Tauri's bounded native correlation window and prevent scan cleanup or other
+  operations. Watchers retain independent cancellation and bounded streams;
+  stopping the last watcher releases polling, and stale reads cannot affect a
+  replacement watch owner. Native replay protection remains unchanged.
+- Honor readiness deadlines shorter than the polling interval and abort a
+  pending readiness delay immediately without issuing an extra native route.
+- Cancel event-driven readiness waits promptly in the shared public wrapper,
+  preserving `operation.aborted` even when the underlying stream closes first.
+- Bound and retain pending backend state-watch acquisitions. Aborted or timed-out
+  readiness calls no longer wait indefinitely for Web availability probes; late
+  resources are cleaned up and failed cleanup remains retryable during teardown.
+
+## [4.0.22] - 2026-09-04
+
+### Fixes
+
+- Arbitrate an Android asynchronous CCCD failure against an already-in-flight
+  disconnect callback for the same GATT generation. Android can deliver status
+  133 from `onDescriptorWrite`, accept local notification rollback, and only
+  then deliver the authoritative status-19 disconnect; exact subscriptions now
+  retain that provisional failure for a bounded 250 ms evidence window so the
+  command reports typed `connection.lost` without hiding genuine CCCD errors.
+
+## [4.0.21] - 2026-09-04 (unpublished)
+
+Publication was cancelled before the npm version check after physical Android
+hardware reproduced a later callback ordering that required the 4.0.22 fix.
+
+### Fixes
+
+- Preserve Android GATT status 19 when a peer disconnects while an exact or
+  non-exact CCCD subscription is awaiting `onDescriptorWrite`. The pending
+  subscription now reports typed `connection.lost` instead of generic
+  `platform.failure`; asynchronous CCCD status 133 remains an ordinary failure
+  when local-registration rollback succeeds.
+- Preserve that typed primary link-loss result when exact CCCD rollback also
+  fails; the cleanup failure remains separately reported and retryable.
+- Classify an exact synchronous CCCD descriptor-submission rejection as link
+  loss only when the subsequent local-registration rollback is also rejected;
+  genuine subscription rejections remain ordinary failures.
+- Apply the same two-signal rule when Android accepts descriptor submission but
+  its asynchronous CCCD callback fails before the connection-state callback:
+  a rejected rollback proves the link is gone, while a successful rollback
+  preserves the original platform failure and GATT status.
+
 ## [4.0.20] - 2026-09-03
 
 ### Fixes

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-This source targets `4.0.20`. 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.23`. 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.20`. Install the exact version shown in the npm
+This source tree is versioned `4.0.23`. 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,9 @@ 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.19` are immutable. `4.0.20` is the current train head.
+once tagged. Stable `4.0.0` through `4.0.20` are immutable. The unpublished
+`v4.0.21` tag is also immutable after its cancelled workflow. `4.0.22` is immutable published history. `4.0.23` is the
+current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -109,6 +111,42 @@ The first stable tag `v4.0.0` is immutable published history. Do not recreate or
 git tag -a v4.0.0 -m "v4.0.0"
 ```
 
+## Releasing 4.0.23
+
+Release `v4.0.23` only from the exact current `main` commit after its canonical
+CI succeeds. Verify `package.json` is `4.0.23`, the worktree is clean, and
+release-note extraction finds `## [4.0.23]`. Push a new annotated `v4.0.23`
+tag; never move the immutable `v4.0.22` tag. Follow the required local validation,
+publish workflow, and registry verification below.
+
+## Releasing 4.0.22
+
+The `v4.0.22` 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.22"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.22 -m "v4.0.22"
+git push origin v4.0.22
+```
+
+Before tagging, confirm release-note extraction finds `## [4.0.22]`.
+
+## Unpublished 4.0.21 tag
+
+The immutable `v4.0.21` tag triggered workflow `33862393779`, which was
+cancelled during native prebuilds before the npm version check or publication
+after physical Android hardware exposed a remaining CCCD callback-order race.
+It must not be recreated, moved, or published manually.
+
 ## Releasing 4.0.20
 
 The `v4.0.20` tag must identify the exact current `main` commit after canonical
@@ -445,7 +483,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.20
+version=4.0.23
 
 npm view "unified-ble-manager@$version" version
 npm view unified-ble-manager dist-tags --json

package/SBOM.cdx.json

@@ -6,15 +6,15 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.20",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.23",
       "name": "unified-ble-manager",
-      "version": "4.0.20",
+      "version": "4.0.23",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.20"
+      "purl": "pkg:npm/unified-ble-manager@4.0.23"
     },
     "properties": [
       {
@@ -537,7 +537,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.20",
+      "ref": "pkg:npm/unified-ble-manager@4.0.23",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
         "pkg:npm/node-addon-api@8.9.0",

package/THIRD_PARTY_LICENSES.json

@@ -4,7 +4,7 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.20"
+    "version": "4.0.23"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",

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

@@ -134,6 +134,90 @@ internal fun classifyAndroidNotificationRegistrationFailure(
   operation: String
 ): AndroidGattOperationFailure = AndroidGattOperationFailure(operation, null, isLinkLoss = true)
 
+/**
+ * Android may deliver an ordinary CCCD callback immediately before the
+ * authoritative status-19 connection callback for the same GATT generation.
+ * Keep only that provisional result pending long enough for lifecycle evidence
+ * already in flight to claim it. Descriptor writes and already-typed link loss
+ * are never delayed.
+ */
+internal fun shouldAwaitAndroidCccdDisconnectEvidence(failure: Throwable): Boolean =
+  failure is AndroidGattOperationFailure &&
+    failure.operation == "cccd-write" &&
+    !failure.isLinkLoss
+
+private const val ANDROID_CCCD_DISCONNECT_EVIDENCE_GRACE_MS = 250L
+
+internal class AndroidCccdTerminalArbiter<Key>(
+  private val schedule: (delayMs: Long, action: () -> Unit) -> Boolean,
+  private val onFallback: (key: Key, failure: AndroidGattOperationFailure) -> Unit
+) {
+  private val provisionalFailures = ConcurrentHashMap<Key, AndroidGattOperationFailure>()
+
+  fun defer(key: Key, failure: AndroidGattOperationFailure) {
+    if (provisionalFailures.putIfAbsent(key, failure) != null) return
+    val fallback: () -> Unit = {
+      val retained = provisionalFailures.remove(key)
+      if (retained != null) onFallback(key, retained)
+    }
+    if (!schedule(ANDROID_CCCD_DISCONNECT_EVIDENCE_GRACE_MS, fallback)) fallback()
+  }
+
+  fun claim(key: Key): AndroidGattOperationFailure? = provisionalFailures.remove(key)
+
+  fun isPending(key: Key): Boolean = provisionalFailures.containsKey(key)
+
+  fun clear() {
+    provisionalFailures.clear()
+  }
+}
+
+/** Synchronous API rejection after local CCCD registration, before Android starts ATT work. */
+internal class AndroidCccdSubmissionFailure(
+  val platformStatus: Int?
+) : IllegalStateException(
+  if (platformStatus == null) "writeDescriptor failed to start"
+  else "writeDescriptor failed to start status=$platformStatus"
+)
+
+/** Android rejected removal of the exact local notification registration. */
+internal class AndroidNotificationRollbackRejected :
+  IllegalStateException("setCharacteristicNotification rollback was rejected")
+
+internal fun androidGattTerminalResult(
+  result: Result<Unit>,
+  rollbackFailure: OwnedRadioTeardownFailure?
+): Result<Unit> {
+  val primaryFailure = result.exceptionOrNull()
+  val registrationRollbackRejected =
+    rollbackFailure?.throwable is AndroidNotificationRollbackRejected
+  if (registrationRollbackRejected && primaryFailure is AndroidCccdSubmissionFailure) {
+    return Result.failure(classifyAndroidNotificationRegistrationFailure("cccd-write"))
+  }
+  if (
+    registrationRollbackRejected &&
+    primaryFailure is AndroidGattOperationFailure &&
+    primaryFailure.operation == "cccd-write" &&
+    !primaryFailure.isLinkLoss
+  ) {
+    return Result.failure(
+      AndroidGattOperationFailure(
+        primaryFailure.operation,
+        primaryFailure.gattStatus,
+        isLinkLoss = true
+      )
+    )
+  }
+  if (rollbackFailure == null || result.isFailure) return result
+  return Result.failure(
+    IllegalStateException(
+      "CCCD operation failed; CCCD rollback failed: " +
+        (rollbackFailure.throwable.message ?: "unknown error"),
+      rollbackFailure.throwable
+    )
+  )
+}
+
 /** Runtime adapter state derived from Android hardware and granted permissions. */
 internal data class OwnedRadioAdapterProtocolState(
   val availability: String,
@@ -313,6 +397,13 @@ class OwnedAndroidGattRadio(private val context: Context) {
   private val exactWritePending = ConcurrentHashMap<BluetoothGattCharacteristic, ExactBytePending>()
   private val exactWriteValues = ConcurrentHashMap<BluetoothGattCharacteristic, ByteArray>()
   private val exactCccdPending = ConcurrentHashMap<BluetoothGattDescriptor, ExactUnitPending>()
+  private val exactCccdTerminalArbiter = AndroidCccdTerminalArbiter<BluetoothGattDescriptor>(
+    schedule = { delayMs, action -> mainHandler.postDelayed(action, delayMs) },
+    onFallback = fallback@ { descriptor, failure ->
+      val pending = exactCccdPending.remove(descriptor) ?: return@fallback
+      completeExactUnit(pending, Result.failure(failure))
+    }
+  )
   private val exactDescriptorReadPending = ConcurrentHashMap<BluetoothGattDescriptor, ExactBytePending>()
   private val exactDescriptorWritePending = ConcurrentHashMap<BluetoothGattDescriptor, ExactUnitPending>()
   private val activeNativeSubscriptionOwnership =
@@ -1754,7 +1845,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
           if (exactCccdPending.remove(cccd, pending)) {
             completeExactUnit(
               pending,
-              Result.failure(IllegalStateException("writeDescriptor failed to start status=$status"))
+              Result.failure(AndroidCccdSubmissionFailure(status))
             )
           }
         }
@@ -1767,7 +1858,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
           if (exactCccdPending.remove(cccd, pending)) {
             completeExactUnit(
               pending,
-              Result.failure(IllegalStateException("writeDescriptor failed to start"))
+              Result.failure(AndroidCccdSubmissionFailure(null))
             )
           }
         }
@@ -2080,6 +2171,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
       exactWritePending.clear()
       exactWriteValues.clear()
       exactCccdPending.clear()
+      exactCccdTerminalArbiter.clear()
       exactDescriptorReadPending.clear()
       exactDescriptorWritePending.clear()
       activeNativeSubscriptionOwnership.clear()
@@ -2138,12 +2230,24 @@ class OwnedAndroidGattRadio(private val context: Context) {
       }
   }
 
-  private fun failPendingForDevice(deviceKeyUpper: String, reason: String) {
+  private fun failPendingForDevice(
+    deviceKeyUpper: String,
+    reason: String,
+    gattStatus: Int? = null
+  ) {
     effectiveMtuByDevice.remove(deviceKeyUpper)
     deviceQueues.remove(deviceKeyUpper)?.clear(IllegalStateException(reason))
     val failBytes = Result.failure<ByteArray?>(IllegalStateException(reason))
     val failInt = Result.failure<Int>(IllegalStateException(reason))
     val failUnit = Result.failure<Unit>(IllegalStateException(reason))
+    // A peer link-loss callback can win the race with onDescriptorWrite. Keep
+    // that exact Android status on pending CCCD work so the protocol boundary
+    // reports connectionLost instead of flattening the race to platformFailure.
+    val failCccd: Result<Unit> = if (gattStatus == ANDROID_GATT_LINK_LOSS_STATUS) {
+      Result.failure(classifyAndroidGattOperationFailure("cccd-write", gattStatus))
+    } else {
+      failUnit
+    }
     pending.keys
       .filter { key ->
         keyBelongsToDevice(key, "discover", deviceKeyUpper) ||
@@ -2166,7 +2270,9 @@ class OwnedAndroidGattRadio(private val context: Context) {
           keyBelongsToDevice(key, "descWrite", deviceKeyUpper)
       }
       .toList()
-      .forEach { key -> pendingDesc.remove(key)?.invoke(failUnit) }
+      .forEach { key ->
+        pendingDesc.remove(key)?.invoke(if (key.startsWith("cccd:")) failCccd else failUnit)
+      }
     pendingDescRead.keys
       .filter { key -> keyBelongsToDevice(key, "descRead", deviceKeyUpper) }
       .toList()
@@ -2194,7 +2300,11 @@ class OwnedAndroidGattRadio(private val context: Context) {
       .filter { it.value.deviceKeyUpper == deviceKeyUpper }
       .forEach { entry ->
         if (exactCccdPending.remove(entry.key, entry.value)) {
-          completeExactUnit(entry.value, failUnit)
+          exactCccdTerminalArbiter.claim(entry.key)
+          completeExactUnit(
+            entry.value,
+            if (entry.value.subscriptionEnabled != null) failCccd else failUnit
+          )
         }
       }
     exactDescriptorReadPending.entries
@@ -2346,17 +2456,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
       pending.done()
       return
     }
-    val terminalResult = if (rollbackFailure == null) {
-      result
-    } else {
-      Result.failure(
-        IllegalStateException(
-          "${result.exceptionOrNull()?.message ?: "CCCD operation failed"}; " +
-            "CCCD rollback failed: ${rollbackFailure.throwable.message ?: "unknown error"}",
-          result.exceptionOrNull() ?: rollbackFailure.throwable
-        )
-      )
-    }
+    val terminalResult = androidGattTerminalResult(result, rollbackFailure)
     if (terminalResult.isSuccess && !pending.token.isPubliclySettled()) {
       pending.subscriptionEnabled?.let { enabled ->
         pending.subscriptionCharacteristic?.let { characteristic ->
@@ -2403,7 +2503,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
       } else {
         OwnedRadioTeardownFailure(
           "cccdRollback:$deviceKeyUpper:generation=$generation",
-          IllegalStateException("setCharacteristicNotification rollback was rejected")
+          AndroidNotificationRollbackRejected()
         )
       }
     } catch (throwable: Throwable) {
@@ -2411,6 +2511,16 @@ class OwnedAndroidGattRadio(private val context: Context) {
     }
   }
 
+  private fun deferExactCccdFailure(
+    descriptor: BluetoothGattDescriptor,
+    pending: ExactUnitPending,
+    failure: AndroidGattOperationFailure
+  ) {
+    if (exactCccdPending[descriptor] === pending) {
+      exactCccdTerminalArbiter.defer(descriptor, failure)
+    }
+  }
+
   private fun completeExactUnitDirect(
     callback: (Result<Unit>) -> Unit,
     done: () -> Unit,
@@ -2477,7 +2587,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
         // Always pass gatt status: status 133 etc. means failed connect, not clean disconnect.
         // R3-F003: close() only after STATE_DISCONNECTED (not from disconnect()/connect prior).
         dispatchConnectionState(id, false, status)
-        failPendingForDevice(key, "disconnected status=$status")
+        failPendingForDevice(key, "disconnected status=$status", status)
         val teardownFailure = completeGattTeardown(key, gatt, generation)
         pendingDisconnectCallbacks.remove(key)?.invoke(teardownFailure)
         if (teardownFailure != null) return
@@ -2514,18 +2624,29 @@ class OwnedAndroidGattRadio(private val context: Context) {
         }
         return
       }
-      exactCccdPending.remove(descriptor)?.let { pending ->
+      exactCccdPending[descriptor]?.let { pending ->
+        // The first callback owns the terminal. A contradictory duplicate
+        // callback cannot replace a provisional failure during arbitration.
+        if (exactCccdTerminalArbiter.isPending(descriptor)) return
         if (!isCurrentGatt(pending.deviceKeyUpper, gatt, pending.gattGeneration)) {
-          pending.done()
+          if (exactCccdPending.remove(descriptor, pending)) {
+            exactCccdTerminalArbiter.claim(descriptor)
+            pending.done()
+          }
           return@let
         }
         if (status == BluetoothGatt.GATT_SUCCESS) {
-          completeExactUnit(pending, Result.success(Unit))
+          if (exactCccdPending.remove(descriptor, pending)) {
+            completeExactUnit(pending, Result.success(Unit))
+          }
         } else {
-          completeExactUnit(
-            pending,
-            Result.failure(classifyAndroidGattOperationFailure("cccd-write", status))
-          )
+          val failure = classifyAndroidGattOperationFailure("cccd-write", status)
+          if (shouldAwaitAndroidCccdDisconnectEvidence(failure)) {
+            deferExactCccdFailure(descriptor, pending, failure)
+          } else if (exactCccdPending.remove(descriptor, pending)) {
+            exactCccdTerminalArbiter.claim(descriptor)
+            completeExactUnit(pending, Result.failure(failure))
+          }
         }
         return
       }