unified-ble-manager 4.0.16 → 4.0.18

package/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to `unified-ble-manager` are documented here.
 
 No changes yet.
 
+## [4.0.18] - 2026-09-03
+
+### Fixes
+
+- Let exactly one lifecycle path complete a React Native subscription command
+  when peer disconnection races a late CCCD callback. Android atomically
+  claims the pending command before emitting a failure, while Apple ignores
+  subscription completions from a disconnected connection generation.
+
+## [4.0.17] - 2026-09-03
+
+### Fixes
+
+- Downgrade expected late native connect-cleanup diagnostics after caller
+  cancellation from error severity to informational telemetry, while retaining
+  the physical connection quarantine until native teardown is confirmed.
+
 ## [4.0.16] - 2026-09-03
 
 ### Fixes

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-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 source targets `4.0.18`. 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.16`. Install the exact version shown in the npm
+This source tree is versioned `4.0.18`. 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.15` are immutable. `4.0.16` is the current train head.
+once tagged. Stable `4.0.0` through `4.0.17` are immutable. `4.0.18` is the current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -133,6 +133,48 @@ 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.18
+
+The `v4.0.18` 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.18"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.18 -m "v4.0.18"
+git push origin v4.0.18
+```
+
+Before tagging, confirm release-note extraction finds `## [4.0.18]`.
+
+## Releasing 4.0.17
+
+The `v4.0.17` 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.17"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.17 -m "v4.0.17"
+git push origin v4.0.17
+```
+
+Before tagging, confirm release-note extraction finds `## [4.0.17]`.
+
 ## Releasing 4.0.16
 
 The `v4.0.16` tag must identify the exact current `main` commit after canonical
@@ -361,7 +403,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.16
+version=4.0.18
 
 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.16",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.18",
       "name": "unified-ble-manager",
-      "version": "4.0.16",
+      "version": "4.0.18",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.16"
+      "purl": "pkg:npm/unified-ble-manager@4.0.18"
     },
     "properties": [
       {
@@ -537,7 +537,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.16",
+      "ref": "pkg:npm/unified-ble-manager@4.0.18",
       "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.16"
+    "version": "4.0.18"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",

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

@@ -879,11 +879,10 @@ class UnifiedBleProtocolAndroidDispatcher(
     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
+    // Claim before constructing or emitting the terminal. Link loss can race a
+    // native CCCD callback; a check followed by a later claim lets both paths
+    // publish a result for the same operation.
+    if (!claimExactPendingCommand(pendingCommands, operationKey(command), command)) return
     val errorFields = mutableMapOf<Int, ProtocolWireValue>(
         1 to ProtocolWireValue.StringValue(code),
         2 to ProtocolWireValue.StringValue("android"),
@@ -908,7 +907,6 @@ class UnifiedBleProtocolAndroidDispatcher(
       )
     )
     UnifiedBleProtocolJsiBinding.emitRecord(nativeHandle, ProtocolWireEncoder.encode(result))
-    if (!bondedPeerCommand) claimExactPendingCommand(pendingCommands, operationKey(command), command)
     radioOperationIds.remove(operationKey(command))
   }
 

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

@@ -978,7 +978,7 @@ class OwnedAndroidGattRadio(private val context: Context) {
     val r =
       Runnable {
         if (gatts[key] === gatt) {
-          OwnedAndroidLog.e("GATT close safety timeout for $key (DISCONNECTED never arrived)")
+          OwnedAndroidLog.i("GATT close safety timeout; cleanup callback absent, forced close proceeding for $key")
           dispatchConnectionState(key, false, BluetoothGatt.GATT_FAILURE)
           failPendingForDevice(key, "disconnected timeout")
           val teardownFailure = completeGattTeardown(key, gatt)

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

@@ -17,6 +17,10 @@ object OwnedAndroidLog {
     if (level <= Log.DEBUG) Log.d(TAG, msg)
   }
 
+  @JvmStatic fun i(msg: String) {
+    if (level <= Log.INFO) Log.i(TAG, msg)
+  }
+
   @JvmStatic fun e(msg: String, t: Throwable? = null) {
     try {
       if (t != null) Log.e(TAG, msg, t) else Log.e(TAG, msg)

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

@@ -269,7 +269,6 @@ class UnifiedBleProtocolAndroidDispatcherLifecycleTest {
       dispatcher.indexOf("private fun emitFailure"),
       dispatcher.indexOf("private fun emitCancelled")
     )
-    assertTrue(failure.contains("bondedPeerCommand"))
     assertTrue(
       failure.indexOf("claimExactPendingCommand") <
         failure.indexOf("UnifiedBleProtocolJsiBinding.emitRecord")
@@ -281,6 +280,28 @@ class UnifiedBleProtocolAndroidDispatcherLifecycleTest {
     )
   }
 
+  @Test
+  fun cccdFailureClaimsThePendingCommandBeforeEmittingItsTerminal() {
+    val dispatcher = readAndroidSource(
+      "android/src/main/java/com/sfourdrinier/unifiedblemanager/protocol/UnifiedBleProtocolAndroidDispatcher.kt"
+    )
+    val failure = dispatcher.substring(
+      dispatcher.indexOf("private fun emitFailure"),
+      dispatcher.indexOf("private fun emitCancelled")
+    )
+
+    // Link loss and the CCCD callback can run concurrently. Claiming before
+    // emission makes the first terminal the owner; a late subscriptionFailed
+    // callback must not pass a check-then-emit race and publish a duplicate.
+    val claimIndex = failure.indexOf(
+      "if (!claimExactPendingCommand(pendingCommands, operationKey(command), command)) return",
+      failure.indexOf("Claim before constructing")
+    )
+    val emitIndex = failure.indexOf("UnifiedBleProtocolJsiBinding.emitRecord")
+    assertTrue(claimIndex >= 0)
+    assertTrue(claimIndex < emitIndex)
+  }
+
   @Test
   fun bondedPeerSnapshotBridgeHasAnOwnedRadioAndDispatcherRoute() {
     val radio = readAndroidSource(
@@ -839,6 +860,21 @@ class UnifiedBleProtocolAndroidDispatcherLifecycleTest {
     assertTrue(connectionLossIndex < teardownIndex)
   }
 
+  @Test
+  fun gattSafetyCloseTimeoutUsesInformationalDiagnostics() {
+    val radio = readAndroidSource(
+      "android/src/main/java/com/sfourdrinier/unifiedblemanager/radio/OwnedAndroidGattRadio.kt"
+    )
+    val timeout = radio.substring(
+      radio.indexOf("private fun scheduleSafeClose"),
+      radio.indexOf("private fun cancelSafeClose")
+    )
+
+    assertTrue(timeout.contains("OwnedAndroidLog.i(\"GATT close safety timeout"))
+    assertFalse(timeout.contains("OwnedAndroidLog.w(\"GATT close safety timeout"))
+    assertFalse(timeout.contains("OwnedAndroidLog.e(\"GATT close safety timeout"))
+  }
+
   @Test
   fun adapterLossClosesGattOwnersBeforeForwardingTheState() {
     val radio = readAndroidSource(

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.16`. Tagged releases ship Node-API v8 prebuilds covering macOS and Windows `arm64`/`x64` for both Node and modern Electron.
+This source targets `4.0.18`. 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.16` source. Those options match
+Use the v2 plugin options in this `4.0.18` 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.16`; the npm registry and release
+This source targets `unified-ble-manager@4.0.18`; 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.16`; verify the published version in the npm registry.
+This source targets `4.0.18`; 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.16`, install that exact version and keep it in
+After the npm registry lists `4.0.18`, install that exact version and keep it in
 your lockfile while validating the native build:
 
 ```sh
-pnpm add unified-ble-manager@4.0.16
+pnpm add unified-ble-manager@4.0.18
 ```
 
 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.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.
+This source targets `4.0.18`. 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.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.
+This guide targets `4.0.18`. 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.16`
+`unified-ble-manager@4.0.18`
 
 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/ios/NativeProtocol/UnifiedBleProtocolAppleExecution.mm

@@ -1400,6 +1400,11 @@ void dispatchCommand(
     const auto subscription = requiredString(command, 7U);
     const auto subscriptionIdentifier = [NSString stringWithUTF8String:subscription.c_str()];
     void (^completion)(NSError*) = ^(NSError* error) {
+      // CoreBluetooth can complete a CCCD write after didDisconnect. The
+      // disconnect path removes this connection generation before publishing
+      // its event, so suppress any completion that is now stale and let the
+      // boundary's connectionLost terminal own the pending operation.
+      if (!currentConnectionGenerationMatches(state, endpoint.peer, endpoint.connectionGeneration)) return;
       if (error == nil) static_cast<void>(success(state, command));
       else fail(state, command, "subscriptionFailed", error);
     };

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

@@ -708,7 +708,7 @@ class CoreBluetoothBackend {
       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);
+        console.info(`${this.diagnosticTag('connect')} Cancelled native connection cleanup is not yet confirmed; quarantine retained:`, record.nativePeerId);
       }
     };
     try {