unified-ble-manager 4.0.15 → 4.0.16

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-This source targets `4.0.15`. 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.15`. 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.14` are immutable. `4.0.15` 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,6 +133,27 @@ 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.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
+```
+
+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
@@ -340,7 +361,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.15
+version=4.0.16
 
 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.15",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.16",
       "name": "unified-ble-manager",
-      "version": "4.0.15",
+      "version": "4.0.16",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.15"
+      "purl": "pkg:npm/unified-ble-manager@4.0.16"
     },
     "properties": [
       {
@@ -537,7 +537,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.15",
+      "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,7 +4,7 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.15"
+    "version": "4.0.16"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",

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
@@ -641,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
@@ -856,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,
@@ -1211,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,
@@ -2479,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
@@ -2494,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
@@ -2515,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
+            )
+          )
+        )
       }
     }
 

package/android/src/test/java/com/sfourdrinier/unifiedblemanager/protocol/UnifiedBleProtocolAndroidDispatcherLifecycleTest.kt

@@ -12,6 +12,7 @@ import com.sfourdrinier.unifiedblemanager.radio.BondedPeerSnapshot
 import com.sfourdrinier.unifiedblemanager.radio.normalizeBondedPeerSnapshots
 import com.sfourdrinier.unifiedblemanager.radio.bondedPeerAdapterReadiness
 import com.sfourdrinier.unifiedblemanager.radio.requiresImmediateGattTeardownOnAdapterState
+import com.sfourdrinier.unifiedblemanager.radio.classifyAndroidGattOperationFailure
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertArrayEquals
 import org.junit.Assert.assertFalse
@@ -31,6 +32,36 @@ import android.bluetooth.BluetoothAdapter
 import android.bluetooth.le.ScanSettings
 
 class UnifiedBleProtocolAndroidDispatcherLifecycleTest {
+  @Test
+  fun gattStatus19IsTypedAsLinkLossButOrdinaryCccdFailureIsNot() {
+    val linkLoss = classifyAndroidGattOperationFailure("cccd-write", 19)
+    assertTrue(linkLoss.isLinkLoss)
+    assertEquals(19, linkLoss.gattStatus)
+
+    val ordinaryFailure = classifyAndroidGattOperationFailure("cccd-write", 133)
+    assertFalse(ordinaryFailure.isLinkLoss)
+    assertEquals(133, ordinaryFailure.gattStatus)
+  }
+
+  @Test
+  fun dispatcherOnlyMapsTypedLinkLossToConnectionLost() {
+    val linkLoss = classifyAndroidGattOperationFailure("cccd-write", 19)
+    assertEquals("connectionLost", androidGattOperationFailureCode(linkLoss, "subscriptionFailed"))
+    assertEquals(19, androidGattOperationFailureStatus(linkLoss))
+
+    val ordinaryFailure = classifyAndroidGattOperationFailure("cccd-write", 133)
+    assertEquals("subscriptionFailed", androidGattOperationFailureCode(ordinaryFailure, "subscriptionFailed"))
+    assertEquals(133, androidGattOperationFailureStatus(ordinaryFailure))
+
+    // Matching an error message is intentionally insufficient: only the
+    // typed callback failure may change the public terminal vocabulary.
+    assertEquals(
+      "subscriptionFailed",
+      androidGattOperationFailureCode(IllegalStateException("onDescriptorWrite status=19"), "subscriptionFailed")
+    )
+    assertNull(androidGattOperationFailureStatus(IllegalStateException("onDescriptorWrite status=19")))
+  }
+
   @Test
   fun bondedPeerAdapterReadinessReturnsTypedFailuresInsteadOfAnEmptySuccess() {
     assertTrue(

package/docs/ELECTRON.md

@@ -4,7 +4,7 @@
 
 Main owns the radio. The renderer uses a versioned IPC client and never loads a native addon.
 
-This source targets `4.0.15`. Tagged releases ship Node-API v8 prebuilds covering macOS and Windows `arm64`/`x64` for both Node and modern Electron.
+This source targets `4.0.16`. Tagged releases ship Node-API v8 prebuilds covering macOS and Windows `arm64`/`x64` for both Node and modern Electron.
 
 `unified-ble-manager/electron/main` and
 `unified-ble-manager/electron/renderer` are the only Electron entrypoints.

package/docs/EXPO_PLUGIN.md

@@ -7,7 +7,7 @@ start a radio, request runtime permissions during prebuild, or prove physical
 radio/restoration reliability. Expo Go is not a supported BLE execution
 environment because it cannot contain this native module.
 
-Use the v2 plugin options in this `4.0.15` source. Those options match
+Use the v2 plugin options in this `4.0.16` source. Those options match
 the schema introduced at `4.0.0-rc.4`. Expo Go cannot load this native module.
 
 ## Installation and development build

package/docs/GAPS.4.0.md

@@ -14,7 +14,7 @@ This file tracks platform code, CI, package, lab, and live-radio evidence. It do
 
 The clean-baseline contract, unified core, public manager, deterministic backend, TCK, native protocol, first-party backend implementations, host-isolated package exports, SDK/CLI, and legacy-absence gates exist in the 4.0 source. Passing deterministic, compile, ABI, or package tests are implementation proof; they do not become physical-radio support evidence unless a retained record proves the corresponding live scenario.
 
-This source targets `unified-ble-manager@4.0.15`; the npm registry and release
+This source targets `unified-ble-manager@4.0.16`; the npm registry and release
 provenance, not a source version string, determine whether it is published.
 Earlier stable releases remain immutable published history. Backend support labels remain
 evidence-derived. This package does not rewrite the evidence inventory: a backend remains at the support level

package/docs/GETTING_STARTED.md

@@ -4,7 +4,7 @@
 
 This page gets you to a first scan, connect, read, notify, and teardown on React Native. Other hosts are linked at the bottom. The root import does not turn Bluetooth on.
 
-This source targets `4.0.15`; verify the published version in the npm registry.
+This source targets `4.0.16`; verify the published version in the npm registry.
 
 ## Pick a host
 
@@ -38,11 +38,11 @@ request runtime permissions on Android 12+, add
 #### Expo / CNG v2
 
 The Expo v2 schema and `unified-ble-manager/expo` factory are in this source.
-After the npm registry lists `4.0.15`, install that exact version and keep it in
+After the npm registry lists `4.0.16`, install that exact version and keep it in
 your lockfile while validating the native build:
 
 ```sh
-pnpm add unified-ble-manager@4.0.15
+pnpm add unified-ble-manager@4.0.16
 ```
 
 The package does not run in Expo Go.

package/docs/NODE.md

@@ -10,7 +10,7 @@ The root import does not open an adapter. Pick one backend:
 | `unified-ble-manager/node/winrt`         | Windows                                      |
 | `unified-ble-manager/node/bluez`         | Linux (needs `dbus-next@^0.10.2` in the app) |
 
-This source targets `4.0.15`. Tagged releases ship Node-API v8 prebuilds for macOS and Windows on `arm64` and `x64`. A normal install should not compile native code. BlueZ talks D-Bus and has no addon.
+This source targets `4.0.16`. Tagged releases ship Node-API v8 prebuilds for macOS and Windows on `arm64` and `x64`. A normal install should not compile native code. BlueZ talks D-Bus and has no addon.
 
 ## One-call factories
 

package/docs/WEB.md

@@ -6,7 +6,7 @@ Use `unified-ble-manager/web` to run the public UBM manager directly in a browse
 
 The complete runnable TypeScript/Vite application is in [`example-web/`](../example-web/).
 
-This guide targets `4.0.15`. Web Bluetooth support still depends on the browser, operating system, adapter, and peripheral. UBM reports those runtime boundaries; it does not fabricate a fallback backend.
+This guide targets `4.0.16`. Web Bluetooth support still depends on the browser, operating system, adapter, and peripheral. UBM reports those runtime boundaries; it does not fabricate a fallback backend.
 
 ## Requirements
 

package/docs/generated/PLATFORM_SUPPORT.md

@@ -6,7 +6,7 @@ This page is generated by `scripts/docs/generate-platform-support.js` from valid
 
 ## Current package
 
-`unified-ble-manager@4.0.15`
+`unified-ble-manager@4.0.16`
 
 No evidence record is bound to this exact package version and artifact. Consequently, this generated page makes no Preview, Live Preview, Supported, or Reliability-qualified platform claim for the current package.
 

package/lib/commonjs/backends/corebluetooth/corebluetooth-backend.js

@@ -699,6 +699,18 @@ class CoreBluetoothBackend {
     this.nextConnection += 1;
     this.nextLease += 1;
     this.connectionsByNativeId.set(nativePeerId, record);
+    const cleanupCancelledConnection = async () => {
+      // A caller may abort before the boundary has dispatched the native
+      // connect. Preserve the quarantine record in that case so a late native
+      // success still receives compensation; once native owns the link,
+      // releaseLateCoreBluetoothConnection cancels both connecting and
+      // connected states through the boundary.
+      if (this.boundary.connectionState(nativePeerId) === 'disconnected') return;
+      const released = await (0, _corebluetoothLateConnectCleanup.releaseLateCoreBluetoothConnection)(this.boundary, this.connectionsByNativeId, record);
+      if (!released) {
+        console.error(`${this.diagnosticTag('connect')} Cancelled native connection remains active:`, record.nativePeerId);
+      }
+    };
     try {
       await this.operationLifecycle.awaitBoundaryOperation(options, 'direct-gatt.connect', () => this.boundary.connect(nativePeerId, intent), async () => {
         const released = await (0, _corebluetoothLateConnectCleanup.releaseLateCoreBluetoothConnection)(this.boundary, this.connectionsByNativeId, record);
@@ -706,10 +718,8 @@ class CoreBluetoothBackend {
           console.error(`${this.diagnosticTag('connect')} Late native connection remains active:`, record.nativePeerId);
         }
       }, async () => {
-        if (this.connectionsByNativeId.get(nativePeerId) === record) {
-          this.connectionsByNativeId.delete(nativePeerId);
-        }
-      }, String(record.connectionId));
+        await cleanupCancelledConnection();
+      }, String(record.connectionId), cleanupCancelledConnection);
     } catch (error) {
       const terminalCancellation = error instanceof _errors.BackendContractError && (error.normalized.code === 'operation.aborted' || error.normalized.code === 'operation.timed-out' || error.normalized.code === 'operation.cancelled-by-destroy');
       if (!terminalCancellation) {